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.