stack/docs/design/framework-constitution/DESIGN.md

Mosaic Framework Constitution — Canonical Design (Alpha)

Status: CANONICAL. This is the single design of record for the alpha. It supersedes synthesis-v1.md where they differ. It integrates synthesis-v1.md and the three red-team passes (debate/redteam-contrarian.md, debate/redteam-devex.md, debate/redteam-steward.md), each finding either mitigated here or explicitly accepted with rationale (§9). A PRD derives from this document; implementation derives from the PRD.

Scope: DQ1–DQ5 of BRIEF.md, plus the non-DQ release blockers (LICENSE, hardcoded credential path) the debate surfaced. Every claim is grounded in the real tree at packages/mosaic/framework/ and packages/mosaic/src/; paths and line numbers were re-verified against the working copy, not trusted from the prior papers.

---

0. What changed vs synthesis-v1

The synthesis layer model and "subtraction not addition" doctrine survive the red team intact and are adopted wholesale. What the red team broke — and this document fixes — is the seam between the spec and the mechanisms it assumed already existed. Three facts re-verified here change the plan:

1. The resident contract is the root file ~/.config/mosaic/AGENTS.md, seeded once and never re-seeded. launch.ts:326 reads root AGENTS.md; install.sh:236 seeds it only when absent ([[ ! -f ... ]]); file-adapter.ts:187 (if (existsSync(dest)) continue) does the same in the npm path. Removing files from PRESERVE_PATHS does NOT update them — it only stops preserving a file the seed loop then declines to recreate. The synthesis's headline drift fix is mechanically wrong (contrarian R1, steward RISK-04). Fixed in §3/§5.
2. mosaic <harness> already self-heals a missing SOUL.md via checkSoul() (launch.ts:55-68): it runs the setup wizard, so deleting defaults/SOUL.md does not brick a mosaic-launched session. The real hole is (a) bare launches that bypass mosaic, and (b) the wizard hanging on a non-TTY host (devex B1, contrarian R4). Fixed in §3/§4.
3. The contamination is broader than synthesis-v1 enumerated — re-grep finds the private credential path in three scripts (incl. tools/health/stack-health.sh:23), a private domain brain.woltje.com in the shipped prevent-memory-write.sh hook, and operator tokens across tools/, guides/, and the init generator's default role string — none of which the synthesis fix list or the proposed grep scope covered (devex B3, steward RISK-01/03). Fixed in §6.

There are two dual implementations of the upgrade logic (install.sh bash + file-adapter.ts npm), kept in sync only by a comment (file-adapter.ts:148). Every mechanism change in this document is specified as "in both installers, proven by one shared fixture suite" (contrarian R10). This is promoted to a first-class design constraint, not an afterthought.

---

1. Layering & Precedence (final model)

1.1 The legitimacy test

A layer boundary is legitimate iff the two sides differ in owner, upgrade-fate, OR residency. This single test (from synthesis-v1.md §1, banked by all three red teams) decides every split below and rejects gratuitous ones.

1.2 The canonical layers

Five concerns, four owned layers plus a non-resident governance spec.

#	Layer	Owns	Owner	Upgrade fate	Residency	Deployed path
L0	Constitution	Irreducible non-negotiable law: the hard gates, escalation triggers, block-vs-done, mode declaration, the two-axis precedence rule, the "hooks are the gate" doctrine, the "no operator context in framework PRs" firewall, and the universal merge-disambiguation rule (see §1.4)	Framework	Overwritten wholesale every upgrade (unconditional copy, never seed-if-absent). User MUST NOT edit.	Always resident, byte-budgeted	~/.config/mosaic/CONSTITUTION.md
L1	Standards & Guides	How to do the work well: secrets/ESO, trunk-based git, image tagging, E2E procedure, QA matrix, orchestrator protocol, all guides/*	Framework; a deployment may tighten via overlay	Overwritten; user delta lives in STANDARDS.local.md; guides never forked	STANDARDS.md resident; guides/* on-demand	~/.config/mosaic/STANDARDS.md, ~/.config/mosaic/guides/*
L2	Persona (SOUL)	Agent name, tone, role, communication style, persona principles	User (init-generated)	Never overwritten. Generated from template.	Always resident, byte-budgeted	~/.config/mosaic/SOUL.md (+ optional SOUL.local.md)
L3	Operator (USER)	Human name, pronouns, timezone, accessibility, comms prefs, projects, operator policy (e.g. merge-authority delegation), operator tool paths/env	User (init-generated)	Never overwritten.	Always resident, byte-budgeted	~/.config/mosaic/USER.md (+ optional USER.local.md, optional policy/*.md)
L4	Project / Runtime mechanism	Per-repo AGENTS.md deltas; harness-specific mechanism only (subagent syntax, hook/MCP wiring, injection tier)	Repo / framework	Project file user-owned; runtime mechanism overwritten	Project in-repo; runtime resident, ~15 lines	<repo>/AGENTS.md, ~/.config/mosaic/runtime/<h>/RUNTIME.md
—	Layer-Model spec (governance)	The definition of the layers, precedence, and "what may live in L0"	Framework maintainers	Source-only, never deployed	Not resident	packages/mosaic/framework/constitution/LAYER-MODEL.md

Deployed AGENTS.md is not a layer — it is the thin load-order dispatcher + Conditional Guide Loading table that routes to L0–L4. Framework-owned, overwritten on upgrade.

1.3 Precedence — typed two-axis, not a flat stack

Stated verbatim in L0:

Safety axis (gates, integrity, destructive actions): L0 Constitution is supreme. Nothing in STANDARDS, SOUL, USER, policy/, project AGENTS.md, runtime, or any injected reminder may relax, suspend, or contradict a Constitution gate. A lower layer may only make behavior stricter, never more permissive.

Taste axis (tone, formatting, verbosity, iconography): the operator layers (SOUL/USER) win over generic framework or model defaults. The framework has no legitimate opinion on style.

1.4 The merge-disambiguation correction (contrarian R6 — accepted and fixed)

The synthesis moved the entire gate #13 to an opt-in example. That silently weakens a hard gate: by the stricter-only rule, a deployment that does not adopt the example defaults to the strictest reading of "No self-merge" — never merge without the human — which contradicts gates #2/#9 the BRIEF says to preserve. Gate #13 is therefore split:

• Universal law (stays in L0, operator-agnostic): "A 'No self-merge' note on a PR means no UNREVIEWED self-merge; it does not suspend a coordinator-authorized merge. When a coordinator session is active, the post-review merge go-ahead is the coordinator's; once review gates pass, proceed on the coordinator's confirmation."
• Operator delegation (→ examples/policy/merge-authority.example.md): "don't wait on {{OPERATOR_NAME}} personally." The named-person clause and only that clause leaves L0.

This keeps the gate-interaction semantics universal while removing the PII.

1.5 Enforcement strength is a ranked ladder, not a choice

mechanical (hook / CI)  >  resident-by-value (system-prompt injection)  >  file-read (self-load fallback)

1. Mechanical first. Every checkable gate becomes a hook or CI check (no-force-merge, green-CI-before-done, no-hardcoded-secrets, no-PII, no-dead-paths, no-unrendered-tokens). This drains prose from the resident core — the precondition that makes tiers 2–3 viable. Precedent: prevent-memory-write.sh (runtime/claude/RUNTIME.md:30) — "the rule alone proved insufficient; the hook is the hard gate."
2. Resident-by-value second. The irreducible non-checkable stop-condition gates (block-vs-done, escalation, completion-definition) injected by value at primacy, restated as a ≤5-bullet anchor at recency (bottom).
3. File-read third (fallback). Tier-3/bare launches: unconditional read (see §1.6).

1.6 Tier-aware self-load (contrarian R9 / steward RISK-07 — accepted)

The fallback read instruction differs by tier:

• Tier-1 (injected by value): "CONSTITUTION.md is already in your context above; do not re-read." (true, because the launcher demonstrably injected it).
• Tier-3 (bare-launch pointer): unconditional — "READ ~/.config/mosaic/CONSTITUTION.md now, before your first action." No "if not already in context" introspection — models are unreliable at judging their own window, and this is the exact drift-prone path the fallback exists to protect.

This removes the false unconditional "already in your context — do not re-read" at defaults/AGENTS.md:11 (every paper flagged it; it is still live in the tree).

---

2. File-by-File Move / Sanitize Plan

2a. New files

New file	Content	Source
defaults/CONSTITUTION.md → deploys to ~/.config/mosaic/CONSTITUTION.md	L0, one flat file, ~70–90 lines. The 13 hard gates with the §1.4 split applied (operator name removed, disambiguation kept); 5 escalation triggers; block-vs-done; mode-declaration; the §1.3 two-axis precedence rule verbatim; the "hooks are the gate" doctrine; the §4 "no operator context in framework PRs" firewall; the §1.6 tier-aware self-load lines; one pointer to the guide index. Gates keep full wording; procedure (wrapper paths, --purpose flags) moves to L1. L0 is authored in capability verbs — no tool-named "else stop" (see §7, devex M7).	Extracted from defaults/AGENTS.md:23-87,143
constitution/LAYER-MODEL.md	The §1 model + precedence + "what may live in L0" + the overlay-eligibility list (§4). Source-only, never deployed, never resident.	This document
examples/personas/execution-partner.md	Sanitized, placeholdered essence of the Jarvis persona — a worked example, copied on request, never auto-loaded	defaults/SOUL.md (sanitized)
examples/overlays/e2e-loop.json	Sanitized essence of jarvis-loop.json (~/src/<your-project> placeholders)	runtime/claude/settings-overlays/jarvis-loop.json
examples/policy/merge-authority.example.md	The operator delegation clause from §1.4	defaults/AGENTS.md:37
LICENSE (monorepo root) + packages/mosaic/framework/LICENSE	MIT text + "license": "MIT" in package.json	new (D8)
CONTRIBUTING.md (framework package)	Layer model, PII/secrets prohibition, dedup rule, how to add a harness adapter, the re-contamination rule, the dual-installer parity rule, the known-limitations list (§9)	new
tools/quality/scripts/verify-sanitized.sh	The blocking CI gate (§6)	new
.woodpecker.yml (framework package or monorepo root)	Wires verify-sanitized.sh, the resident line-count check, and the composer unit test as blocking steps	new (steward RISK-02 — the gate is prose until wired)

2b. Files that shrink / change role

File	Change	DQ
defaults/AGENTS.md	Gut 155→~50-line dispatcher: load order + Conditional Guide table + tier-aware self-load. Zero restated gates. Remove the false line 11. Change seed semantics to unconditional overwrite (see §3).	DQ1, DQ5
defaults/STANDARDS.md	Drop "Master/slave" framing (line 5 → "Primary / satellite"); stop re-asserting L0 gates; end with the STANDARDS.local.md additive-include convention. Becomes overwrite-on-upgrade.	DQ1,3,5
defaults/TOOLS.md	Delete the MANDATORY jarvis-brain rule block (lines 40-44). Generic index only.	DQ2
defaults/README.md:72	--name Jarvis --user-name Jason --timezone America/Chicago → placeholder names.	DQ2
templates/SOUL.md.template	Already clean. Keep. Ensure every {{TOKEN}} resolves to a non-empty value in init (no token survives into a resident file).	DQ2
templates/agent/AGENTS.md.template and templates/agent/projects/*/{AGENTS,CLAUDE}.md.template	Delete the restated Hard-Gates block. Replace with: "This project is governed by ~/.config/mosaic/CONSTITUTION.md. Add only project-specific extensions below." Fix every rails/git/→tools/git/, rails/codex/→tools/codex/ across BOTH AGENTS.md.template and CLAUDE.md.template families (devex m10 — synthesis named only the AGENTS family).	DQ4,5
runtime/{claude,codex,pi,opencode}/RUNTIME.md	Strip restated policy. Reduce to harness mechanism + one-line CONSTITUTION.md reference. Rewrite the four "sequential-thinking MCP is required / else stop" lines to capability-verb form (§7).	DQ4,5
tools/_lib/credentials.sh:19, tools/git/detect-platform.sh:89, tools/health/stack-health.sh:23	${MOSAIC_CREDENTIALS_FILE:-$HOME/src/jarvis-brain/credentials.json} → ${MOSAIC_CREDENTIALS_FILE:?MOSAIC_CREDENTIALS_FILE must be set} (fast-fail per STANDARDS.md:35). Document the env var in USER.md.template under ## Tool Paths. Three sites, not two (steward RISK-01, devex B3).	DQ2 (blocker)
tools/qa/prevent-memory-write.sh:29	https://brain.woltje.com/v1/thoughts → ${OPENBRAIN_URL:?OPENBRAIN_URL must be set}/v1/thoughts. This hook prints its URL to the agent on every blocked write — a private domain in every install.	DQ2 (blocker-class)
tools/_scripts/mosaic-init:277-278	Default AGENT_NAME "Assistant" + the verbatim Jarvis role string ("execution partner and visibility engine"). Fail-closed on persona in --non-interactive unless --agent-name given; replace the role default with a neutral placeholder. (devex B2 — the generator re-creates the bug verify-sanitized.sh can't see.)	DQ2
tools/_scripts/mosaic-doctor:312	mosaic-jarvis skill → mosaic-agent (generic).	DQ2
guides/ORCHESTRATOR.md (99,111,152), ORCHESTRATOR-LEARNINGS.md:127, ORCHESTRATOR-PROTOCOL.md:4, TOOLS-REFERENCE.md (149,182,226), BOOTSTRAP.md	Replace jarvis-brain/... paths with ~/.config/mosaic/... canonical paths; remove the MANDATORY jarvis-brain rule block. (steward RISK-03 — broader than synthesis named.)	DQ2

2c. Files deleted / relocated

File	Action	Why
defaults/SOUL.md	Delete. Persona generated at init from template; mosaic self-heals via checkSoul(); bare-launch hole closed in §3.	Primary contamination vector
runtime/claude/settings-overlays/jarvis-loop.json	Delete → sanitized examples/overlays/e2e-loop.json	Personal project map
defaults/AUDIT-2026-02-17-framework-consistency.md	Move to monorepo docs/	Maintainer artifact, not agent context

---

3. Customization + Upgrade-Safety Mechanism

The single sentence a user can rely on: "Edit SOUL.md/USER.md and the *.local.md overlays freely — upgrades never touch them. Never edit CONSTITUTION.md/STANDARDS.md/guides/*/AGENTS.md — they update automatically every upgrade. To change framework behavior, add a .local.md overlay or a policy/ file (tighten-only)."

3.1 The seam = ownership, enforced by overwrite semantics (contrarian R1 / steward RISK-04 — the central fix)

The synthesis's "remove from PRESERVE_PATHS" is necessary but not sufficient. The seed-if-absent logic must be replaced with unconditional overwrite for the framework-owned root files, in BOTH installers:

1. Split the seed lists by ownership. DEFAULT_SEED_FILES (file-adapter.ts:16) and the install.sh:236 seed loop are split into:
   • FRAMEWORK_OWNED = CONSTITUTION.md, AGENTS.md, STANDARDS.md → always copied (overwrite) on every upgrade. Never in PRESERVE_PATHS.
   • USER_SEEDED = TOOLS.md (generated-then-tuned) → seed-if-absent, kept in PRESERVE_PATHS, retains .bak.<ts>-on-regenerate.
2. SOUL.md, USER.md, *.local.md, policy/, memory, sources, credentials are the only PRESERVE_PATHS entries. AGENTS.md and STANDARDS.md are removed.
3. Test the injected bytes, not file presence (contrarian R1). The migration fixtures assert what buildPrompt/launch.ts:325-333 composes, because testing defaults/AGENTS.md content would pass while the resident root contract stayed stale.

3.2 Additive overlays, launcher-composed (steward RISK-06 / devex M6 — build it, don't assume it)

mosaic compose-contract <harness> does not exist and is alpha-blocking, not assumed. Minimum viable spec:

• Concatenates, in precedence order, base + .local deltas before injection, so the model gets one pre-merged blob (no redundant read-merge ritual).
• Per-harness emission (the four harnesses are not symmetric):
  • Pi / mosaic claude / mosaic codex — append the merged blob via --append-system-prompt.
  • Codex / OpenCode — write the merged blob into the instructions file (~/.codex/instructions.md, ~/.config/opencode/AGENTS.md).
• Bare launches that bypass mosaic get base-only overlays (the launcher never ran to compose them). This is documented loudly as a known limitation (§9), and the AGENTS.md self-load fallback emits a one-line "overlays require mosaic <harness>; run mosaic doctor" nudge.
• Alpha scope cut (accepted): ship SOUL.local.md + USER.local.md (the two files users actually customize) and STANDARDS.local.md. Defer policy/*.md composition to v2 if build budget is tight — but the L0 merge-disambiguation rule (§1.4) means policy/ is additive delegation only, never load-bearing for a gate, so deferral is safe.

3.3 Versioning & migration

1. One global FRAMEWORK_VERSION integer + linear migrations (existing install.sh:157-198 scaffold). No per-layer version matrix (combinatorial test cliff). Per-layer template versions survive only as a mosaic doctor advisory.
2. Bump FRAMEWORK_VERSION 2→3. The v2→v3 migration:
   • Snapshot ~/.config/mosaic/ → ~/.config/mosaic/.backup-v3/ first (contrarian R2 — today there is no snapshot; the cp-fallback rm -rf at install.sh:140 can lose SOUL.md/ credentials on interrupt). Implement as atomic snapshot → sync → on-failure-restore in BOTH installers; a fixture kills the process mid-sync and asserts no data loss.
   • Vendor the v2 baseline of AGENTS.md/STANDARDS.md into the migration. If the installed file differs from the v2 baseline (it was user-edited — the sanctioned customization until now), copy it to AGENTS.md.pre-constitution.bak / STANDARDS.local.md and print a one-line notice before overwriting (contrarian R2, devex M5). Never silently delete; never auto-merge (Markdown has no merge semantics — a half-resolved merge leaves <<<<<<< markers in the resident identity file). Fixture 3 asserts the delta landed in .local.md, not merely that a backup exists.
   • Install CONSTITUTION.md as a new file nothing previously owned (avoids reclassifying a user-edited flat AGENTS.md).
3. Headless bootstrap (devex B1 / contrarian R4 — the hole checkSoul half-covers). mosaic <harness> self-heals a missing SOUL.md via checkSoul() (launch.ts:55), but the wizard hangs on a non-TTY host. Fix: install.sh runs mosaic-init --non-interactive after sync so a valid SOUL.md/USER.md always exists post-install; the wizard's non-interactive path is fail-closed on persona (devex B2) — it errors asking for --agent-name rather than silently shipping an agent named "Assistant" with the Jarvis role string.

3.4 The migration is the biggest risk — gate the alpha on a falsifiable fixture matrix

Alpha cannot tag until these pass with no interactive prompt, no hang, run against both install.sh and FileConfigAdapter.syncFramework from one shared suite (contrarian R10):

1. Fresh install → valid resident CONSTITUTION.md+AGENTS.md+SOUL.md+USER.md exist; assert injected bytes.
2. Legacy-flat user-edited install (MOSAIC_INSTALL_MODE=keep, the upgrade default; steward RISK-05) → law moves to CONSTITUTION.md, root AGENTS.md is overwritten with the new dispatcher, the user's old edits land in AGENTS.md.pre-constitution.bak, SOUL.md/credentials survive.
3. User-tuned-standard install → the STANDARDS.md delta survives as STANDARDS.local.md and the framework STANDARDS.md updates.
4. Unattended install (no TTY) → valid resident SOUL.md/USER.md exist, zero read calls, no agent named "Assistant".
5. Interrupt-during-sync → snapshot restore leaves no data loss.

3.5 Detection without enforcement

mosaic doctor reports drift / unrendered-tokens / budget-overflow / template-version-skew as advisories (warn, never block launch). --check-constitution is opt-in diagnostic, not a gate. Accepted limitation: drift on bare launches that never invoke mosaic is undetected by doctor (devex m9) — documented in CONTRIBUTING.md; the self-load fallback nudges the user toward doctor.

---

4. Sanitization — per-layer strategy + a class-closing CI gate

Ships generic (PII-free, complete): CONSTITUTION.md, AGENTS.md (dispatcher), STANDARDS.md, TOOLS.md (generic index), all guides/* (purged), templates/* (token-only), examples/* (placeholdered), runtime/*/RUNTIME.md (mechanism-only), adapters/*.md, LICENSE, CONTRIBUTING.md.

Generated at mosaic init: SOUL.md, USER.md, TOOLS.md, *.local.md, optional policy/*.md, per-harness runtime copies.

Deleted / relocated: per §2c.

4.1 The CI gate — honest scope (contrarian R7 / devex B3 / steward RISK-01,02,03)

verify-sanitized.sh is split into two rule-classes so it neither false-positives into being disabled nor under-scopes past the runnable contamination:

• Structural rules (operator-independent, always valid): unrendered {{...}}/${...} in resident files; dead /rails/ tokens; L0 must contain no tool-named hard-stop (grep CONSTITUTION.md for 'sequential-thinking|MCP.*REQUIRED|else stop' → fail, §7); no ${VAR:-$HOME/...} private-default in any *.sh.
• Current-contaminant denylist (labeled one-time regression guard, NOT a general PII detector): jarvis|jason|woltje|\bPDA\b|jarvis-brain|brain\.woltje\.com, and the specific absolute path /home/jwoltje/. Anchored to avoid comparison/jsonwebtoken false hits.
• Scope: defaults/ guides/ templates/ runtime/ adapters/ tools/ over both *.md and *.sh (the credential leak and the hook URL live in *.sh under tools/ — the synthesis grep covered neither). Excludes examples/.
• Self-test: the gate plants a jarvis-brain token in a fixture and asserts the gate fails, so a grep-syntax error can't silently no-op the gate (steward RISK-02).
• Wired blocking in .woodpecker.yml. Until green-and-wired, the alpha cannot tag.

4.2 The durable class-closer is the L0 prose firewall + human review, with the grep as backup

The primary author of future framework PRs is an agent running with some operator's SOUL/USER in context; a 6-token denylist cannot generalize to the next operator's name. So the primary control is the L0 rule, stated verbatim in CONSTITUTION.md:

"When proposing a framework PR or capturing a framework-improvement/tooling-gap, you MUST NOT include content derived from SOUL.md, USER.md, or operator-specific context. If you cannot express it operator-agnostically, it belongs in policy/ or a project AGENTS.md, not the framework."

The grep is the backup regression guard, explicitly labeled as such — not oversold as closing the PII class.

---

5. Cross-Harness Adapter Strategy

Single source: L0 CONSTITUTION.md is the one law text. No harness gets a forked copy; runtime files and project templates reference it, never restate it.

Adapter contract (mechanism only): adapters/<h>.md / runtime/<h>/RUNTIME.md may specify only (a) the injection channel + tier, and (b) how L0's capability verbs bind to concrete tools and whether absence is a hard stop. The Constitution says "use structured reasoning before planning"; the Claude adapter binds it to sequential-thinking MCP (gate=true); the Pi adapter to native thinking (gate=false). For the alpha, this binding is a markdown table; JSON manifests are v2.

Tiered, honest injection (the four harnesses are not symmetric — verified):

Harness	Channel	Tier	L0 delivery
Pi	--append-system-prompt, no hook backstop (adapters/pi.md:14)	1	By value at primacy; keep L0 tiny — resident fidelity is Pi's only enforcement
mosaic claude / mosaic codex	system-prompt append (launch.ts:518,551)	1	By value at primacy + ≤5-bullet recency anchor
Codex / OpenCode	instructions file	2	Resident-ish; composer writes merged blob; self-load backup
bare claude/codex/opencode	thin pointer	3	≤5-bullet anchor inline + unconditional "READ CONSTITUTION.md NOW"

Tier-3 anchor must be a literal L0 substring, not a paraphrase (devex M4 — accepted). You cannot forbid paraphrasing gates (D7) and then ship a 5-bullet paraphrase as the Tier-3 payload. The anchor is the exact bytes of the 5 irreducible stop-condition gate lines, so Tier-3 is a strict subset of Tier-1, never a divergent text. The composer unit test asserts byte-equality of the anchor against its L0 source lines.

Verification control — re-scoped (contrarian R3 / steward RISK-11 — accepted). The synthesis's "live-launch each harness in CI and assert effective context" is impractical (no Codex/OpenCode prompt dump; Tier-3 unassertable without reading model behavior). Replace with a composer unit test: assert buildPrompt(harness) output contains the irreducible-gate anchor for each tier, and that the Tier-3 anchor is byte-equal to its L0 source. This is real and cheap. Live-launch smoke testing is a v2 aspiration. Codex/OpenCode hook parity is a tracked gap in CONTRIBUTING.md's compliance matrix, not something the alpha closes.

sequential-thinking contradiction (devex M7 — accepted). It lives in four RUNTIME files (runtime/{claude,codex,opencode}/RUNTIME.md:3 say "required"; runtime/pi/RUNTIME.md:61 says "not gated"). All four are rewritten in the same PR to capability-verb form; L0 carries no tool-named "else stop"; the structural CI rule (§4.1) enforces it; a fixture asserts a bare pi launch does not emit a sequential-thinking halt.

---

6. Phased Implementation Plan (alpha — ordered, each phase independently shippable)

Each phase is a self-contained, CI-green PR. Order is dependency-driven: legal/safety first, then the extraction the rest depends on, then mechanism, then cross-harness, then the gate that locks it.

Phase 0 — Legal & runnable-leak blockers (no behavior change)

• Add MIT LICENSE (root + framework) + "license": "MIT" in package.json.
• Fix the credential path in all three *.sh sites → ${MOSAIC_CREDENTIALS_FILE:?...}.
• Fix brain.woltje.com in prevent-memory-write.sh → ${OPENBRAIN_URL:?...}.
• Ships independently; closes the legal window and the executable-leak class. No layer changes yet.

Phase 1 — The sanitization gate (the lock comes before the cleanup)

• Write verify-sanitized.sh with the §4.1 two-class rules + self-test; wire blocking in .woodpecker.yml. Build goes red on the current contamination — intended; it scopes Phase 2.
• Ships independently as "CI now fails on operator data," even before the data is removed (the red build is the worklist).

Phase 2 — Sanitize the existing tree to green (mechanical, no architecture)

• Purge all operator tokens across guides/, defaults/TOOLS.md, README.md, mosaic-doctor, mosaic-init defaults; rails/→tools/ across both template families; drop "Master/slave".
• Delete defaults/SOUL.md, jarvis-loop.json; relocate the AUDIT file; create examples/*.
• Phase 1's gate goes green. Ships independently; package is now PII-free but still pre-Constitution.

Phase 3 — Extract L0 by subtraction

• Create defaults/CONSTITUTION.md (gates one place, §1.4 split, capability-verb authored, precedence verbatim, firewall rule, tier-aware self-load).
• Gut defaults/AGENTS.md to the ~50-line dispatcher; remove the false line 11.
• Create constitution/LAYER-MODEL.md. Strip restated policy from STANDARDS.md + the four RUNTIME files; rewrite the sequential-thinking lines to capability verbs.
• Add the L0 line-count CI ceiling over framework-owned resident files only (§7).
• Ships independently; no install/migration changes yet — fresh installs get the new structure.

Phase 4 — Overwrite semantics + migration + headless bootstrap

• Split seed lists into FRAMEWORK_OWNED (overwrite) vs USER_SEEDED (seed-if-absent) in BOTH installers; remove AGENTS.md/STANDARDS.md from PRESERVE_PATHS; add CONSTITUTION.md.
• Implement snapshot→sync→restore; vendor the v2 baseline; v2→v3 migration moves user edits to .local/.bak. Bump FRAMEWORK_VERSION=3.
• install.sh runs mosaic-init --non-interactive (fail-closed persona).
• Land the shared fixture suite (§3.4) run against both installers. Gates the tag.

Phase 5 — Overlay composer + cross-harness composer test

• Build mosaic compose-contract <harness> per §3.2 (SOUL.local.md+USER.local.md+ STANDARDS.local.md; per-harness emission; documented bare-launch base-only behavior).
• Composer unit test (§5): per-tier anchor present; Tier-3 byte-equal to L0.
• Ships independently as "customization now survives upgrades."

Phase 6 — Docs, compliance matrix, alpha tag

• CONTRIBUTING.md (operator-hygiene, dual-installer parity rule, known-limitations §9, harness×gate compliance matrix with the hook-parity gap marked).
• PRD ↔ design reconciliation; tag the alpha after the full DoD (§8) is green.

---

7. Resident-token budget (steward RISK / contrarian R5 / devex m8 — accepted, re-scoped)

Budget the container by line count, keep gate wording intact. But CI cannot see user-generated SOUL.md/USER.md, and the resident set varies per harness tier (contrarian R5). So the control is split:

• CI (package-side): a line-count ceiling over framework-owned resident files only (CONSTITUTION.md + dispatcher AGENTS.md + the resident RUNTIME.md slice). Real and enforceable.
• mosaic doctor (runtime advisory): sums the actual composed prompt — including SOUL.md/ USER.md and the per-harness tier — and warns the operator. This is the only place the total resident budget is visible, and it is per-harness, not a single global number (devex m8: hook-less harnesses like Pi need more resident, so the advisory threshold is per-harness).

Gates keep full wording; procedure (wrapper paths, flags) moves to on-demand E2E-DELIVERY.md. Reject "exactly 500 words for L0" — gate #13 alone is ~110 words; a word cap forces paraphrasing law, the exact drift vector being killed.

---

8. Alpha Definition of Done (for the PRD)

Blocking, all CI-green: MIT LICENSE + package.json field; three credential-path sites + the hook URL fast-failed; verify-sanitized.sh (two-class, *.sh+*.md, self-tested) wired blocking; operator data purged from the full set (guides/tools/init-generator included); rails/→tools/ in both template families; defaults/SOUL.md+jarvis-loop.json deleted; CONSTITUTION.md extracted (gates one place, capability-verb, §1.4 split, no false "already loaded"); AGENTS.md/STANDARDS.md out of PRESERVE_PATHS and seed-semantics switched to overwrite in both installers; snapshot/ migration v2→v3 moving user edits to .local/.bak; mosaic-init --non-interactive fail-closed persona; 5-fixture matrix (§3.4) green against both installers asserting injected bytes; compose-contract built + composer unit test (per-tier anchor, Tier-3 byte-equality); resident line-count ceiling enforced; CONTRIBUTING.md + compliance matrix; tag the alpha. PRD precedes implementation.

Deferred to v2 (explicit): constitution/ deploy directory; adapters/<h>.capabilities.json; 3-way merge; live-launch cross-harness smoke test; policy/*.md composition; per-layer version stamps as a migration driver; DCO CI.

---

9. Red-Team Disposition (every finding mitigated or accepted)

Finding	Disposition
contrarian R1 / steward RISK-04 — "remove from PRESERVE_PATHS" doesn't update resident root file	Mitigated §3.1: split seed lists, unconditional overwrite for framework-owned, in BOTH installers; test injected bytes
contrarian R2 — snapshot/restore described but unimplemented; cp-fallback can lose data	Mitigated §3.3: atomic snapshot→sync→restore + interrupt fixture; user-edited AGENTS.md→.pre-constitution.bak
contrarian R3 / steward RISK-11 — live-launch smoke test impractical	Mitigated §5: re-scoped to composer unit test; live-launch → v2; hook-parity tracked in compliance matrix
contrarian R4 / devex B1 — deleting defaults/SOUL.md + interactive init bricks headless first-run	Mitigated §3.3: checkSoul() self-heals mosaic launches; install.sh runs --non-interactive init; fixture 4
contrarian R5 / devex m8 — line budget can't see user files / varies per tier	Mitigated §7: CI ceiling on framework files only; doctor per-harness runtime advisory
contrarian R6 — extracting gate #13 weakens a hard gate for non-adopters	Mitigated §1.4: split #13 — disambiguation stays universal in L0; only the named delegation leaves
contrarian R7 / devex B3 / steward RISK-03 — denylist false-positives / misses the class	Mitigated §4.1-4.2: two rule-classes (structural + labeled denylist); L0 prose firewall is the primary class-closer
contrarian R8 / steward RISK-06 / devex M6 — compose-contract is a new subsystem called "zero"	Accepted + scoped §3.2: alpha-blocking work item with tests; policy/ composition deferred to v2 with rationale
contrarian R9 / steward RISK-07 — conditional self-load asks model to introspect	Mitigated §1.6: Tier-3 read is unconditional; conditional only on Tier-1
contrarian R10 — two installers synced by a comment, TS path ignored	Mitigated throughout: every mechanism "in both installers, one shared fixture suite"
devex B2 — non-interactive init ships "Assistant" + Jarvis role	Mitigated §2b/§3.3: fail-closed persona; grep init defaults
devex B3 / steward RISK-01 — credential leak in 6+/3 files, grep misses tools/+*.sh	Mitigated §2b/§4.1: all three *.sh sites + hook URL; grep scoped to tools/ and *.sh
devex M4 — Tier-3 paraphrase = two "Mosaics"	Mitigated §5: Tier-3 anchor is a literal L0 substring; byte-equality asserted
devex M5 / steward RISK-05 — pulling from PRESERVE clobbers existing edits; non-TTY false-green	Mitigated §3.3/§3.4: vendor v2 baseline, extract delta→.local before overwrite; fixtures pin MOSAIC_INSTALL_MODE
devex M7 — sequential-thinking contradiction in 4 files; L0 "else stop" halts Pi	Mitigated §5/§4.1: rewrite all 4; L0 capability-verb only; structural CI rule + Pi fixture
devex m9 — doctor drift advisory absent on bare launches	Accepted §3.5: documented limitation; self-load nudge
devex m10 / steward RISK-08 — CLAUDE.md.template siblings keep rails/ + gates	Mitigated §2b: both template families; CI /rails/ rule over templates/
devex m11 — dead-path/legacy-term sanitization is one-off	Mitigated §4.1: structural rules close the dead-path class
steward RISK-02 — verify-sanitized.sh doesn't exist / unwired	Mitigated §2a/§4.1/Phase 1: built, self-tested, wired blocking
steward RISK-09 — "Master/slave" framing	Mitigated §2b: → "Primary / satellite"
steward RISK-10 — no LICENSE	Mitigated Phase 0

Accepted residual risks (stated in CONTRIBUTING.md): bare-launch overlay no-op (base-only) and bare-launch drift-undetected-by-doctor — both inherent to launches that bypass mosaic; mitigated by the unconditional Tier-3 self-load + nudge, not eliminated. Codex/OpenCode hook parity is a tracked v2 gap. Live-launch cross-harness verification is v2.