stack/docs/design/framework-constitution/debate/redteam-devex.md

# Red Team — Cross-Harness DevEx

**Lens:** Cross-Harness DevEx Expert (Claude Code / Codex / Pi / OpenCode injection & tool
differences; portability; end-user customization & upgrade experience).
**Target:** `synthesis-v1.md` (Chief Architect ruling) against the real tree at
`packages/mosaic/framework/`.
**Method:** I re-ran the greps rather than trusting the papers. Every claim below cites a file I read.

I am not re-litigating the settled 80% (Constitution layer, delete `defaults/SOUL.md`, CI grep,
LICENSE, credential fast-fail, `PRESERVE_PATHS` removal). Those are right. Below is where I can
break the design *as written*, ordered by severity.

---

## BLOCKERS

### B1 — The customization mechanism the whole design rests on (`mosaic init`) is interactive-only and will hang every headless launch path

The synthesis stakes upgrade-safety and sanitization on "L2/L3 ship as templates only, generated at
init" (D6, §4) and "Generated at `mosaic init`" (§4). It treats `mosaic init` as a solved
primitive. It is not solved for the way Mosaic actually runs.

`tools/_scripts/mosaic-init` is **interactive by default** (line 50: "Interactive by default";
lines 113/138/184/287: bare `read -r`). The framework's own headless surfaces are numerous: the
Discord bridge runs with **"no human at this terminal"** (project `CLAUDE.md`, Discord Bridge
Protocol), the orchestrator spawns workers via `claude -p`/`codex exec` (`guides/ORCHESTRATOR.md:6`),
and the BRIEF's own migration constraint is **"no interactive prompt, no hang"**
(synthesis §5.5, fixtures 1–3).

Failure mode: a fresh container/CI/Discord deployment installs the framework (`install.sh` does
**not** seed `SOUL.md`/`USER.md` — confirmed `install.sh:231`, `install.sh:301`), an agent launches,
no `SOUL.md`/`USER.md` exists, and either (a) the launcher tries `mosaic init` and blocks on
`read -r` forever, or (b) the agent boots with the **"missing core file → stop and report"** gate
(`defaults/AGENTS.md:144`) firing on every cold start. The synthesis never specifies who runs init,
when, or in what mode on an unattended host.

**Mitigation (must be in the alpha DoD, not deferred):** Define a deterministic non-interactive
bootstrap. `install.sh` MUST, after rsync, run `mosaic-init --non-interactive` (the flag exists,
line 61) with documented defaults so a valid `SOUL.md`/`USER.md` always exists post-install. Add a
4th migration fixture to §5.5: *"unattended install (no TTY) → valid resident SOUL.md/USER.md exist,
zero `read` calls."* Until that fixture is green, the alpha cannot tag — this is the same falsifiable
gate the synthesis already applies to migration.

### B2 — The non-interactive default regenerates the exact bug D6 claims to reject ("Assistant" is the new "Jarvis")

D6 explicitly *rejects* "Generic-defaults for persona (recreates the bug — 'Assistant' becomes the
new 'Jarvis')." But the only persona-generation mechanism in the tree does exactly that:
`tools/_scripts/mosaic-init:277` is `prompt_if_empty AGENT_NAME "What name should agents use"
**"Assistant"**`. In `--non-interactive` mode (which B1 shows is the *only* viable mode for Mosaic's
headless fleet), `prompt_if_empty` takes the default — so every unattended deployment ships an agent
literally named **"Assistant"** with role "execution partner and visibility engine" (line 278, copied
verbatim from the Jarvis `defaults/SOUL.md:11`).

So the design's stated anti-pattern is the design's actual default. Worse: the role string is still
the operator's old role description, meaning a sliver of Jarvis persona survives sanitization through
the init defaults — invisible to `verify-sanitized.sh` because it lives in the *generator*, not in
`defaults/`.

**Mitigation:** Pick one and make it real: (a) make non-interactive init **fail closed** on persona
unless `--agent-name` is supplied (forces deployers to choose, no silent "Assistant"), or (b) accept
a generic persona as a *conscious* alpha decision and **strike the contradictory rejection from D6** —
you cannot both reject generic-default-persona and ship it. Either way, extend `verify-sanitized.sh`
to scan `tools/_scripts/mosaic-init` for operator-derived default strings (the role line is one).

### B3 — The sanitization fix list misses 5+ contaminated files; the CI grep as scoped will *fail the build on day one* or silently miss them

The synthesis "verified live facts" names exactly two files with the private credential path
(`tools/_lib/credentials.sh:19`, `tools/git/detect-platform.sh:89`) and D8 fixes "both." My grep
found **at least six**:

```
tools/_lib/credentials.sh:19
tools/git/detect-platform.sh:89
tools/health/stack-health.sh:23
tools/coolify/README.md:8
tools/glpi/README.md:8
tools/authentik/README.md:8
tools/woodpecker/README.md:8   (+ likely more tool READMEs)
```

Two independent breakages follow:

1. **Incomplete fix.** D8 patches 2 of 6+; `stack-health.sh:23` keeps the hardcoded private path as
   an *executable* default — the exact class D8 calls "worse than persona contamination… runnable."
2. **CI grep paradox.** D6 scopes `verify-sanitized.sh` over `defaults/ guides/ templates/ runtime/
   adapters/` and **excludes examples/** — but says nothing about `tools/`. So the blocking grep that
   is supposed to be the "only durable control" **does not even look in the directory where the
   runnable contamination lives.** If you widen scope to `tools/`, the build goes red on the README
   tokens immediately; if you don't, the credential leak ships. The synthesis has not reconciled this.

Also note: the synthesis's premise that this is a `${VAR:-default}` violation is half-right — the code
is *already* `${MOSAIC_CREDENTIALS_FILE:-$HOME/src/jarvis-brain/...}`, i.e. already overridable. The
defect is purely the *leaked private default*, not missing env support. The fix is to drop the default
(`${MOSAIC_CREDENTIALS_FILE:?...}`), and it must land in **all** call sites.

**Mitigation:** Enumerate the real contamination set with `grep -rn "jarvis-brain\|/home/jwoltje"
tools/` before writing the fix list; fix every hit; scope `verify-sanitized.sh` to include `tools/`
(README prose can use a placeholder like `$MOSAIC_CREDENTIALS_FILE` to pass the grep). Make the grep's
own scope a reviewed artifact — an under-scoped denylist is indistinguishable from no denylist.

---

## MAJOR

### M4 — Tiered injection legitimizes a real cross-harness drift: the bare-`claude` Tier-3 path silently runs on a *different, weaker* law text

The honesty of D5's tier table (`Pi=Tier1 by-value`, `bare claude=Tier3 pointer + ≤5-bullet inline`)
is the right instinct, but it ships **two different constitutions** to two users who both believe they
are "running Mosaic." Tier-1 gets all 13 gates by value; Tier-3 gets a 5-bullet summary plus a
*conditional* "READ CONSTITUTION.md if not resident." On a bare `claude` launch the model is already
mid-task with competing harness `<system-reminder>`s (I am reading several right now in this very
session) — the conditional read is the *weakest* tier by the synthesis's own ladder, and nothing
guarantees it fires. So gate #12 ("complexity trap"), gate #10 ("no manual docker build"), gate #6
("queue guard") — none resident on Tier-3 — are simply absent for that user. Two harnesses, two
behaviors, same "Mosaic" label. That is the cross-harness inconsistency the BRIEF (DQ4) exists to
kill, re-introduced as an accepted design property.

The current tree already has this disease and the synthesis under-counts it: `defaults/AGENTS.md:11`
asserts "The core contract is ALREADY in your context… Do not re-read it" — **provably false on bare
`claude`** (the synthesis catches this, consensus item 9, good) — but the *fix* (Tier-3 inline
summary) is itself a lossy re-statement of L0, which is the very "paraphrased law is the drift vector"
sin D7 rails against. You cannot simultaneously (a) forbid paraphrasing gates and (b) ship a 5-bullet
paraphrase of the gates as the Tier-3 payload.

**Mitigation:** The ≤5-bullet Tier-3 anchor must be **a literal substring of L0** (the same bytes,
not a summary) — pick the 5 truly irreducible *stop-condition* gates and inject those exact lines, so
Tier-3 is a strict subset of Tier-1, never a divergent paraphrase. And the CI smoke test (D5) must
assert **byte-equality** of that anchor against the L0 source, not mere "gates present." Otherwise the
smoke test passes while the texts drift.

### M5 — Removing `AGENTS.md`/`STANDARDS.md` from `PRESERVE_PATHS` will clobber real user edits on the first upgrade, because today those files are user-editable and edited

The single highest-value change (consensus item 7; §5.1) is "Remove `AGENTS.md` and `STANDARDS.md`
from `PRESERVE_PATHS`." Confirmed today: `install.sh:24` lists both as preserved. The drift bug is
real. But the migration is more dangerous than the synthesis admits.

`PRESERVE_PATHS` has protected `AGENTS.md`/`STANDARDS.md` since `FRAMEWORK_VERSION=2`
(`install.sh:28`). That means **every existing install may have a locally-modified
`AGENTS.md`/`STANDARDS.md`** — that was the *sanctioned* customization surface until now. The moment
v3 removes them from preserve and `rsync --delete` runs (`install.sh:116`), those edits are
**destroyed with no capture into `.local.md`**. The synthesis's fixture 3 ("user-tuned-standard →
survives as `STANDARDS.local.md`") *assumes* the migration first extracts the user delta into an
overlay — but §5.4 only describes snapshotting to `.backup-v2/` and installing new files. It never
specifies the **delta-extraction step** that turns a legacy edited `STANDARDS.md` into
`STANDARDS.local.md`. A `.backup-v2/` tarball the user never looks at is not "your change survived."

**Mitigation:** The v2→v3 migration MUST, for `AGENTS.md` and `STANDARDS.md`, diff the installed file
against the v2 *shipped* baseline; if they differ, write the diff (or the whole old file) to
`<name>.local.md` **before** overwriting, and print a one-line notice. This needs the v2 baseline
shipped inside the migration (the synthesis correctly notes "no current install has a base" for 3-way
merge — same problem here; solve it by vendoring the v2 baseline into the migration script, not by
hoping). Fixture 3 must assert the *content* landed in `.local.md`, not just that a backup exists.

### M6 — `.local.md` overlays only work if the launcher composes them; three of four harnesses have no such composer today

D4/§5.2 mandate "additive overlays, launcher-composed" via `mosaic compose-contract <harness>`. I
grepped: **no `compose-contract` exists** (only `prdy-init.sh`, `prdy-update.sh`, `adapters/pi.md`,
`README.md` mention "compose"). So the central upgrade-safety promise — "edit `*.local.md` freely" —
is backed by a command that isn't written. More portability-specific: the four harnesses inject
differently and only Pi clearly supports by-value append (`adapters/pi.md:14`
`--append-system-prompt`). Codex/OpenCode read an **instructions file** (`runtime/codex/RUNTIME.md:8`
`~/.codex/instructions.md`; `runtime/opencode/RUNTIME.md:8` `~/.config/opencode/AGENTS.md`), and bare
`claude` reads `~/.config/mosaic/` by self-load. For `.local.md` to take effect on Codex/OpenCode,
*something* must concatenate base+overlay into that instructions file at the right moment. The
synthesis assigns this to "the launcher" but never says the launcher writes the instructions file, nor
what happens for **bare** `claude`/`codex`/`opencode` launches that bypass `mosaic` entirely (the
exact Tier-3 path that exists *because users do this*). On those paths the overlay is simply never
composed and silently no-ops — the failure mode devex §2b (quoted in D4) supposedly already ruled out,
re-appearing for the non-`mosaic` launch.

**Mitigation:** (1) `compose-contract` is alpha-blocking, not assumed; spec it per harness:
Pi=append-prompt, Codex/OpenCode=write-merged-instructions-file, Claude=write into the self-loaded
`~/.config/mosaic/AGENTS.md` chain. (2) For **bare** launches that bypass `mosaic`, the self-load
fallback in `AGENTS.md` MUST also pull `*.local.md` (the dispatcher reads overlays too), or document
loudly that overlays require `mosaic <harness>` and bare launches get base-only. Pick one; don't leave
it implicit.

### M7 — The Pi/sequential-thinking capability split fixes one contradiction and leaves the inverse one live

D5 correctly kills the `defaults/AGENTS.md:143` ("sequential-thinking REQUIRED, else stop") vs
`adapters/pi.md` ("native thinking replaces it") contradiction via capability verbs. But the live tree
has the contradiction in **four** places, not one: `runtime/codex/RUNTIME.md:3`,
`runtime/opencode/RUNTIME.md:3`, and `runtime/claude/RUNTIME.md:3` all say "sequential-thinking MCP is
required," while `runtime/pi/RUNTIME.md:61` says "The Mosaic launcher does NOT gate on
sequential-thinking MCP for Pi." If L0 states the gate as a hard "else stop" (as `AGENTS.md:143` does
today) and only the *adapter* downgrades it for Pi, then a Pi agent that self-loads L0 on a bare `pi`
launch reads "REQUIRED, else stop" from the resident constitution and the "not gated" relief only from
the non-resident adapter — i.e. the *stronger* statement is the resident one and Pi agents will
spuriously halt. The capability-verb abstraction only resolves this if L0 is authored in verbs from
the start ("use structured reasoning") with **zero** tool-specific "else stop," and the gate-vs-no-gate
binding lives *only* in the adapter. The synthesis says this but the migration plan never rewrites the
four RUNTIME.md "required" lines; §2b only touches "restated policy," and a reader could leave the
contradictory line in.

**Mitigation:** Make "no tool-named hard-stop in L0" an explicit `verify-sanitized.sh` rule
(grep L0 for `sequential-thinking|MCP.*REQUIRED|else stop` → fail). Rewrite all four RUNTIME.md
capability lines in the same PR; add a smoke-test assertion that a bare `pi` launch does not emit the
sequential-thinking halt.

---

## MINOR

### m8 — Resident line-count budget without a per-harness baseline is a foot-gun for the weakest harness

D7 enforces a "resident line-count ceiling" over the resident set. Good. But the synthesis notes Pi's
"resident fidelity is Pi's *only* enforcement" (§6 table) — Pi has **no hook backstop**. A single
global line budget tuned for Claude (hooks + plugins absorb load) is simultaneously too loose for Pi
(which needs *everything* resident because it has no mechanical net) and the budget can't tell the
difference. **Mitigation:** budget per residency-tier, and document that on hook-less harnesses (Pi,
and Codex/OpenCode until hook parity — a "tracked gap" per §6) more of L0/L1 must stay resident; the
budget number is per-harness, not global.

### m9 — `mosaic doctor` drift advisory is the only drift detection, and it's opt-in on the paths where drift happens

D3/§5.6 make drift detection a *non-blocking advisory* in `mosaic doctor`. But drift happens precisely
on **bare** `claude`/`codex` launches that never invoke `mosaic` (hence never run `doctor`). So the
one detector is absent exactly where the disease lives — the same structural flaw the synthesis
correctly used to *reject* hash-refusal-on-launch (D3) applies to its own chosen replacement.
**Mitigation:** accept it as a known alpha limitation **in writing** (CONTRIBUTING/COMPLIANCE doc),
and have the `AGENTS.md` self-load fallback emit a one-line "run `mosaic doctor`" nudge when it detects
it was loaded outside a `mosaic` launcher. Don't claim drift is "detected" when it's only detected for
users who opt into the tool.

### m10 — `templates/agent/` ships 12 files with `rails/git/`; the dispatcher-replacement risks leaving CLAUDE.md siblings behind

Confirmed: `rails/git` / `/rails/` appears across `templates/agent/AGENTS.md.template` **and** the
`CLAUDE.md.template` siblings + all `projects/*` (django/typescript/nestjs-nextjs/python-*). §2b's fix
list names "`templates/agent/AGENTS.md.template` (+ 11 sibling/project templates)" but the grep shows
the `CLAUDE.md.template` variants carry the same dead `rails/` path and the same restated hard-gates
block. If the PR fixes the `AGENTS.md.template` set but not the `CLAUDE.md.template` set, Claude-first
projects (which read `CLAUDE.md`) keep emitting commands at a path `install.sh:192` deletes.
**Mitigation:** the `rails/`→`tools/` and gate-block-removal edits must target `templates/agent/**`
(both `AGENTS.md.template` and `CLAUDE.md.template`), enforced by the same `verify-sanitized.sh`
`/rails/` rule over `templates/`.

### m11 — "Master/slave" is not the only legacy-terminology / dead-path landmine; sanitize the class

§2b drops the "Master/slave model" framing at `STANDARDS.md:5` (confirmed present). Fine, but it's a
one-off fix for a class problem: `STANDARDS.md:42-44` also references `scripts/agent/session-start.sh`
lifecycle scripts and `adapters/claude.md:16` references `~/.config/mosaic/rails` ("linked into
`~/.claude`"). These are the same drift family (stale paths/terms in resident or near-resident files).
**Mitigation:** the CI grep's dead-path rule should cover `rails`, `scripts/agent/` (if those are
deprecated), and a small terminology denylist — close the class, per the synthesis's own D6 "close the
class, not the tokens" principle, which it applies to PII but not to dead paths/terms.

---

## Summary table

| ID | Severity | One-line risk | Core mitigation |
|----|----------|---------------|-----------------|
| B1 | blocker | `mosaic init` is interactive-only → hangs/blocks every headless (Discord/orchestrator/CI) cold start | `install.sh` runs `mosaic-init --non-interactive`; add unattended-install migration fixture |
| B2 | blocker | Non-interactive default ships agent named "Assistant" + Jarvis role string — the bug D6 *rejects* | Fail-closed on persona, or strike D6's rejection; grep init defaults in CI |
| B3 | blocker | Credential leak is in 6+ files (synthesis names 2); CI grep doesn't scope `tools/` | Enumerate real set; fix all; scope grep to `tools/` |
| M4 | major | Tier-3 bare-`claude` runs a divergent 5-bullet paraphrase of L0 → two "Mosaics" | Tier-3 anchor must be literal L0 substring; smoke test asserts byte-equality |
| M5 | major | Pulling `AGENTS.md`/`STANDARDS.md` from PRESERVE clobbers existing user edits | Migration extracts delta → `.local.md` before overwrite; vendor v2 baseline |
| M6 | major | `compose-contract` doesn't exist; overlays no-op on Codex/OpenCode + all bare launches | Spec composer per harness; define bare-launch overlay behavior |
| M7 | major | sequential-thinking hard-stop contradiction lives in 4 RUNTIME files; L0-resident "else stop" halts Pi | L0 in capability verbs only; CI rule bans tool-named hard-stops in L0 |
| m8 | minor | Global line budget ignores Pi's no-hook "resident is the only enforcement" | Per-harness residency budget |
| m9 | minor | `mosaic doctor` drift advisory absent on the bare launches where drift occurs | Document limitation; self-load nudge |
| m10 | minor | `CLAUDE.md.template` siblings keep `rails/git` + restated gates | Fix both template families; CI `/rails/` rule over `templates/` |
| m11 | minor | Dead-path/legacy-term sanitization is one-off, not class-closing | Extend CI grep to dead paths + term denylist |

**Bottom line:** the layer model and the "subtraction not addition" doctrine are sound. The design
breaks at the **seam between the spec and the mechanisms it assumes already exist** — `mosaic init`
(interactive, generic-default), `compose-contract` (absent), the migration's delta-extraction step
(unspecified), and a CI grep scoped to miss the runnable contamination. Every blocker is a case of the
synthesis describing a control as done when the tree shows it isn't. None of them weaken the hard gates
on paper; **B1, M4, M6 weaken them in practice** by letting an agent launch with the gates absent,
paraphrased, or un-composed — which is the one outcome the BRIEF's non-negotiables forbid.