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

Red-Team — Contrarian Skeptic vs. Synthesis v1

Lens: Contrarian Skeptic. Distrusts clever abstractions; hunts failure modes, over-engineering, and rules that read well but degrade real agent behavior. I tried to break the design in synthesis-v1.md, grounding every claim in the real tree. The synthesis already absorbed a lot of contrarian input, so I went after what survived or was newly introduced by the ruling itself.

Verdict: The layering and sanitization decisions are sound. But the synthesis's headline drift fix is mechanically wrong — it does not do what it claims, and the alpha would ship believing the drift bug is fixed when it is not. That is a blocker. Several other claims are aspirational controls presented as settled.

---

R1 — BLOCKER: "Remove from PRESERVE_PATHS" does NOT make gate updates reach existing installs

This is the synthesis's central, most-repeated claim — settled-item #7, D4, §5.1, and the alpha DoD all assert that removing AGENTS.md/STANDARDS.md from PRESERVE_PATHS is "the single change [that] makes gate updates reach every existing install (the literal drift bug)." It does not. I traced the actual install/launch code:

1. The resident, injected contract is the root file ~/.config/mosaic/AGENTS.md. Proof: packages/mosaic/src/commands/launch.ts:326 — parts.push(readFileSync(join(MOSAIC_HOME, 'AGENTS.md'))). It never reads defaults/AGENTS.md.
2. That root file is seeded once and never re-seeded. Proof, both install paths:
   • install.sh:235-240: for default_file in AGENTS.md STANDARDS.md TOOLS.md; do if [[ -f "$DEFAULTS_DIR/$default_file" ]] && [[ ! -f "$TARGET_DIR/$default_file" ]]; then cp ... — the ! -f guard means an existing root file is skipped.
   • file-adapter.ts:184-190: for (const entry of DEFAULT_SEED_FILES) { ... if (existsSync(dest)) continue; ... copyFileSync(...) } — same seed-once semantics.
3. defaults/ itself is rsynced into ~/.config/mosaic/defaults/ as a subdirectory, so removing the root file from PRESERVE_PATHS only refreshes the non-resident defaults/AGENTS.md copy that nothing injects.

Net effect of the synthesis's fix as written: rsync --delete now also deletes the user's customized root AGENTS.md on every keep upgrade (because it's no longer preserved) — but the seed loop will not put the new one back, because… actually it will, since the file is now absent — but only by accident, and only on the bash path. The two sync implementations (install.sh and file-adapter.ts) must stay byte-identical (file-adapter.ts:148 says so explicitly) and the synthesis never mentions file-adapter.ts exists. Any fix applied to one and not the other silently diverges the bash-install and npm-install upgrade behavior — exactly the cross-path drift the project already warns about in that comment.

The deeper trap: the seed mechanism is "copy if absent," which is structurally incompatible with "framework-owned, overwritten every upgrade." You cannot make a file both seeded-once-then-user-owned (today's model) and clobbered-every-upgrade (the Constitution model) by editing a path list. The synthesis's L0 doctrine requires the seed-if-absent logic for AGENTS.md/CONSTITUTION.md/STANDARDS.md to be replaced with unconditional overwrite, in both install.sh and file-adapter.ts, plus the DEFAULT_SEED_FILES list at file-adapter.ts:16 re-thought. None of that is in the plan.

Mitigation (required before alpha):

• Constitution model: L0 CONSTITUTION.md and the dispatcher AGENTS.md must be unconditionally copied/overwritten at the root on every upgrade (not seed-if-absent), in install.sh AND file-adapter.ts. Add a test fixture asserting that an upgrade over a modified root AGENTS.md replaces it.
• Add file-adapter.ts (and DEFAULT_SEED_FILES) to the file-by-file plan in §2b. The synthesis is incomplete: it plans the bash installer and the markdown, not the TS installer that ships in the npm package.
• The migration fixture matrix in §5.5 must assert the injected resident bytes (what launch.ts composes), not just on-disk file presence. Testing defaults/AGENTS.md content would pass while the resident contract is stale.

---

R2 — BLOCKER: the migration "snapshot/restore" is described but the restore path is a data-loss hazard

§5.4 says migration snapshots ~/.config/mosaic/ → .backup-v2/ "before touching disk," and §5.5 gates the alpha on three fixtures passing "with no interactive prompt, no hang." But the real installer (install.sh:105-154, sync_framework) does rsync -a --delete (or the cp fallback that find ... -exec rm -rf {} + wipes the target first). There is no snapshot step in the code today, and the synthesis describes it as if it exists. Worse:

• On the cp fallback path (no rsync), preservation is done by copying PRESERVE_PATHS to a tempdir, wiping the entire target, then copying source + restoring preserved paths (install.sh:128-153). If the process dies between the rm -rf (line 140) and the restore loop (line 144-151), the user's SOUL.md/USER.md/credentials are gone — no snapshot, no transaction. The synthesis's "snapshot to .backup-v2/" would fix this, but it is not written, not tested, and the DoD treats it as already-decided rather than to-be-built.
• --delete + removing AGENTS.md from preserve means on the first v2→v3 upgrade, a user who edited their root AGENTS.md (the install flow at install.sh:235 explicitly invites this: "must never be overwritten once the user has customized them") loses those edits with no migration of intent. The synthesis hand-waves this with "we do not try to diff/split a user-edited flat AGENTS.md" (§5.4) — but that is the population most likely to exist, since the current model encourages editing root AGENTS.md. Silent loss of a customized resident contract on the very first Constitution upgrade is the worst possible first impression for the alpha.

Mitigation:

• Implement the snapshot as an actual atomic step (snapshot → sync → on failure, restore) in BOTH installers, and add a fixture that kills the process mid-sync and asserts no data loss.
• For the user-edited-root-AGENTS.md case: on v2→v3, if the root AGENTS.md differs from the shipped v2 default, save it to AGENTS.md.pre-constitution.bak and emit a doctor advisory ("your old AGENTS.md had local edits; the gate content now lives in CONSTITUTION.md; your edits are preserved at for review"). Don't silently delete; don't try to auto-merge.

---

R3 — MAJOR: the cross-harness "CI smoke test asserts gates are resident" is the load-bearing control and it does not exist

D5 and §6 make the cross-harness claim true by leaning entirely on "a CI smoke test launches each harness path and asserts the irreducible gates are present in the effective context." This single sentence is doing all the work that makes "enforced consistently across Claude/Codex/Pi/OpenCode" more than aspiration. But:

• Two of the four harnesses (Codex, OpenCode) have no hook parity — the synthesis itself concedes this is "a tracked gap... not a silent inconsistency" (§6). So for those harnesses the only enforcement is resident-by-value text, and the smoke test is the only thing verifying it landed.
• Launching four real agent runtimes headlessly in CI, getting their effective context, and asserting text presence is a non-trivial harness — it needs each CLI installed, authed, and a way to dump the composed system prompt. launch.ts:518/551 build --append-system-prompt for Claude/Pi; there is no evidence Codex/OpenCode expose the composed prompt for assertion. The bare-claude (Tier-3 pointer) path can't be asserted at all without actually reading the model's behavior.
• The honest version is: assert what compose-contract/buildPrompt (launch.ts:300-339) emits, per harness — a unit test on the composer, not a live-launch smoke test. That is achievable and worth doing. The "live launch each harness" framing oversells it and will either be quietly downgraded or block the alpha indefinitely.

Mitigation: Re-scope the control to a composer unit test (assert buildPrompt(harness) output contains the irreducible-gate anchor for each tier), which is real and cheap, and demote the "live-launch smoke test" to a post-alpha aspiration. Track Codex/OpenCode hook-parity as an explicit known-limitation in COMPLIANCE.md, not as something the alpha closes.

---

R4 — MAJOR: deleting defaults/SOUL.md removes the only persona an injection-failure fallback can show

The synthesis deletes defaults/SOUL.md (settled #3, D6, §2c) so persona ships only as a template generated at mosaic init. Correct for sanitization. But consider the failure mode the synthesis itself worries about elsewhere — injection silently failed / bare launch / init never run:

• launch.ts:329 reads SOUL.md as optional (readOptional). If mosaic init was never run (or the user git cloned the framework and launched a bare claude), there is no SOUL.md at all, and AGENTS.md:14 instructs "Read ~/.config/mosaic/SOUL.md" — a file that does not exist. Today the shipped defaults/SOUL.md at least seeds a working persona. After deletion, the out-of-box, pre-init experience is "identity file missing," which AGENTS.md:144 (a hard gate!) says should make the agent stop and report. So the sanitization change can convert a clean first-run into a hard-stop, unless mosaic init is mandatory and enforced before any launch.
• The synthesis never states whether launch is blocked until init completes. If it isn't, deleting the default persona degrades first-run from "works with a generic persona" to "halts on missing core file." If it is, that's a new gate the migration must enforce and the DoD must list.

Mitigation: Either (a) make mosaic init a hard precondition of mosaic <harness> with a friendly "run init first" message (not the gate-13 hard-stop), OR (b) keep a generic, PII-free SOUL.md.default (literally the template with safe defaults already rendered) as the seed, and let init overwrite it — note this is exactly the "generic-defaults recreates the Jarvis bug" objection D6 rejected, so (a) is cleaner. Pick one explicitly; the current plan leaves a hole.

---

R5 — MAJOR: the resident line-count budget (D7) is unenforceable without a defined resident set, and the set is harness-variable

D7 enforces "a resident line-count ceiling in CI" over "the always-resident set (CONSTITUTION.md + AGENTS.md index + SOUL.md + USER.md + the resident RUNTIME slice)." Two problems:

1. SOUL.md and USER.md are user-generated and not in the repo (that's the whole point of D6). CI cannot count lines of files that don't exist in the package. So the CI budget can only cover the framework-owned files (CONSTITUTION.md, AGENTS.md, RUNTIME.md) — the operator can still blow the actual resident budget with a 600-line USER.md, and CI never sees it. The budget that matters (total tokens hitting the model) is exactly the one CI can't measure. This is "budget the container" measuring the wrong container.
2. The resident set differs per harness (§6 table: Tier-1 injects L0 by value, Tier-3 injects only a ≤5-bullet summary). So "the resident set" is not one number. A single CI ceiling either over-counts for Tier-3 or under-counts for Tier-1.

Mitigation: Split the control: (a) a CI package-side ceiling on framework-owned resident files (CONSTITUTION.md + dispatcher AGENTS.md + RUNTIME.md resident slice) — real and worth it; (b) a mosaic doctor runtime advisory that sums the actual composed prompt size including SOUL.md/ USER.md and warns the operator. Don't claim CI enforces a budget it structurally cannot see.

---

R6 — MAJOR: gate #13 (merge-authority) is being extracted to an example, which silently weakens a hard gate for the maintainer's own deployment

The synthesis moves the merge-authority clause (defaults/AGENTS.md:37, "Policy: Jason, 2026-06-11") out of L0 into examples/policy/merge-authority.example.md, adopted per-deployment (D1, §2a). Sound for sanitization. But note the BRIEF's non-negotiable: keep the existing hard gates intact (PR-review-before-merge, ... no forced merges). Gate #13 today interacts with the no-self-merge rule: it says "a 'No self-merge' note means no UNREVIEWED self-merge — it does not suspend coordinator-authorized merges." That is a load-bearing disambiguation of an existing hard gate. If it becomes an opt-in example file that a deployment may or may not adopt:

• A deployment that doesn't adopt the policy file has no rule disambiguating "No self-merge" vs coordinator-authorized merge → an orchestrator either over-blocks (waits on human, violating the steered-autonomy gates) or, worse, an agent reads "No self-merge" literally and the coordinator flow deadlocks. The synthesis's own "lower layers may only make stricter, never more permissive" precedence rule (§1) means an absent policy file defaults to the strictest reading — which is "never merge without the human," directly contradicting gates #2/#9 that the BRIEF says to preserve.
• So extraction doesn't just relocate operator data; it removes a conflict-resolution clause between two hard gates from the universal law. That's a behavioral regression dressed as sanitization.

Mitigation: Split clause #13. The operator-specific delegation ("don't wait on Jason personally") is operator policy → examples/policy/. The gate-interaction rule ("'No self-merge' = no UNREVIEWED self-merge; coordinator-authorized merges are not self-merges") is universal law and must stay in L0 CONSTITUTION.md, operator-agnostic. Don't ship an alpha where not-adopting an example file changes hard-gate semantics.

---

R7 — MINOR/MAJOR: verify-sanitized.sh denylist will false-positive and get disabled, OR miss the real class

D6's blocking grep matches jarvis|jason|woltje|\bPDA\b plus ~/src/<word> / /home/<word>/. Two predictable failures:

• False positives that train people to bypass: "jason" matches jasonwebtoken/jsonwebtoken typos, comparison, parse-adjacent strings? (\bPDA\b is fine; bare jason is not anchored in the spec). guides/ legitimately discusses JWT, JSON, etc. A blocking CI check that fires on legitimate content gets # noqa'd or the pattern narrowed until it's toothless. The synthesis says "close the class, not the tokens" but then specifies tokens (jarvis|jason|woltje). The class is "this operator's PII," which a denylist of three names cannot generalize — the next operator is named something else, and the agent writing future framework PRs runs with that operator's SOUL/USER in context (the synthesis's own §4 worry).
• The /home/<word>/ and ~/src/<word> patterns will hit legitimate documentation examples in guides (paths are how you explain tooling). Excluding examples/ (§4) isn't enough; guides are full of real paths.

Mitigation: Keep the grep but scope it honestly: (a) structural rules that don't depend on knowing the operator — unrendered {{...}}/${...} in resident files, dead /rails/ tokens, absolute /home/<specific-user>/ only (not generic /home/<word>/); (b) a separate allowlist-based check for the known current contaminants (jarvis|jason|woltje|PDA) as a one-time regression guard, clearly labeled "current-contaminant denylist, not a general PII detector." Don't oversell a 4-name grep as closing the PII class; the real class-closer is the L0 prose rule (§4) + human review, and that should be stated as the primary control with the grep as backup, not vice-versa.

---

R8 — MINOR: the .local.md overlay + compose-contract step is a new subsystem the DoD calls "zero new subsystems"

§5.5 claims the winning design adds "zero new subsystems (rsync + linear migration + overlays + a 15-line grep)." But D4/§5.2 introduce mosaic compose-contract <harness> that "concatenates, in precedence order, base + .local deltas before injection." Today launch.ts:300-339 buildPrompt does a fixed concatenation with no .local awareness and no precedence resolution. Adding per-layer overlay composition is a new subsystem: it needs discovery of SOUL.local.md/ USER.local.md/STANDARDS.local.md/policy/*.md, a defined precedence merge, and wiring into every harness launch path. Calling it "zero new subsystems" understates the alpha's actual build surface and risks it being descoped late, leaving the customization-safety promise (§5's "single sentence a user can rely on") unimplemented while the docs claim it works.

Mitigation: List compose-contract overlay composition as an explicit DoD work item with its own test (assert SOUL.local.md appends after SOUL.md, policy/*.md is tighten-only). For the alpha, if build budget is tight, ship only SOUL.local.md/USER.local.md (the two files users actually customize) and defer STANDARDS.local.md/policy/ to v2 — but say so, don't imply full overlay support.

---

R9 — MINOR: "self-load fallback" (READ CONSTITUTION.md NOW) reintroduces the exact false-confidence the synthesis flags in #9

Settled #9 correctly kills defaults/AGENTS.md:11's false "already in your context… do not re-read." The replacement (§1 tier-3, §6 table) is: dispatcher says "If CONSTITUTION.md is not already in your context, READ IT NOW." This is better, but the conditional "if not already in your context" asks the model to introspect on its own context window — something models are unreliable at. A model that has a stale or partial L0 resident may conclude "it's already here" and skip the read, getting the old gates. The honest tier-3 instruction is unconditional: "READ ~/.config/mosaic/CONSTITUTION.md now before your first action" — cheap, idempotent, no introspection. The conditional version optimizes away a one-file read at the cost of correctness on exactly the drift-prone path it's meant to protect.

Mitigation: On Tier-3 (pointer) launches, make the read unconditional. Reserve the conditional phrasing for Tier-1 (where injection-by-value genuinely already placed it and a re-read is wasteful). The tier table already distinguishes these — let the read instruction differ by tier too.

---

R10 — MINOR: dual-installer drift is itself an unmitigated systemic risk

install.sh (bash) and file-adapter.ts (TS) are two independent implementations of the same upgrade/preserve/seed logic, kept in sync only by a code comment (file-adapter.ts:148, install.sh:230). The synthesis's entire migration plan is written against install.sh and never acknowledges the TS path exists. Every fix in §2/§5 (remove from PRESERVE_PATHS, overwrite L0, snapshot, migration v2→v3) must be applied twice and verified equivalent, or the npm-installed users and the curl-install.sh users get different upgrade behavior — a cross-harness-style inconsistency one layer down, at install time.

Mitigation: Add a DoD item: a single shared test suite that runs the same upgrade fixtures against both install.sh and FileConfigAdapter.syncFramework, asserting identical resulting trees. Or, better, collapse to one implementation (have the bash installer shell out to the node CLI, or vice versa) before piling Constitution semantics onto both.

---

Ranked summary

#	Risk	Severity	One-line mitigation
R1	"Remove from PRESERVE_PATHS" does NOT update the resident root AGENTS.md (seed-if-absent; launch.ts:326 reads root, not defaults/) — the headline drift fix is mechanically false	BLOCKER	Replace seed-if-absent with unconditional overwrite for L0/dispatcher in BOTH install.sh and file-adapter.ts; test injected bytes, not file presence
R2	Migration snapshot/restore is described but not implemented; cp-fallback + --delete can lose SOUL.md/credentials on interrupt; user-edited root AGENTS.md silently lost on first upgrade	BLOCKER	Implement atomic snapshot→sync→restore in both installers; back up user-edited AGENTS.md to .pre-constitution.bak with a doctor advisory
R3	"Live-launch CI smoke test asserts gates resident on every harness" is the load-bearing cross-harness control and is impractical (no Codex/OpenCode prompt dump, Tier-3 unassertable)	MAJOR	Re-scope to a composer unit test on buildPrompt(harness); demote live-launch to v2; track hook-parity gaps in COMPLIANCE.md
R4	Deleting defaults/SOUL.md turns a clean first-run / bare-launch into a missing-core-file hard-stop (gate #13/§144) when init wasn't run	MAJOR	Make mosaic init a hard precondition with a friendly message, OR seed a generic rendered SOUL.md; decide explicitly
R5	Resident line-count budget can't see user-generated SOUL.md/USER.md and varies per harness tier — it measures the wrong container	MAJOR	CI ceiling on framework-owned resident files only; mosaic doctor runtime advisory for the real composed size
R6	Extracting merge-authority gate #13 to an opt-in example removes a hard-gate conflict-resolution clause; non-adopters default (per "stricter-only" rule) to never-merge, contradicting gates #2/#9 the BRIEF preserves	MAJOR	Split #13: operator delegation → policy/ example; the "No self-merge = no UNREVIEWED self-merge" gate-interaction rule stays universal in L0
R7	verify-sanitized.sh 4-name denylist false-positives (gets disabled) and can't generalize the PII class it claims to close	MAJOR/MINOR	Separate structural checks (always valid) from a labeled current-contaminant denylist; name human review + L0 prose rule as the primary class-closer
R8	mosaic compose-contract overlay composition is a real new subsystem the DoD calls "zero new subsystems"	MINOR	List it as an explicit DoD item with tests; for alpha ship only SOUL.local.md/USER.local.md, defer the rest and say so
R9	Conditional "if not already in context, READ CONSTITUTION.md" asks the model to introspect its context — unreliable on the drift-prone path it protects	MINOR	Make the Tier-3 pointer read unconditional; keep conditional only for Tier-1
R10	Two independent installers (install.sh + file-adapter.ts) kept in sync by a comment; synthesis ignores the TS path entirely	MINOR	Shared upgrade-fixture suite run against both, or collapse to one implementation before adding Constitution semantics

Bottom line: Adopt the layer model and sanitization as designed. Do not tag the alpha until R1 and R2 are fixed in both installer implementations and proven by a fixture matrix that asserts the injected resident bytes (not on-disk presence) — because as written, the synthesis ships an alpha that believes it fixed the drift bug while the resident contract stays stale.