stack/docs/design/framework-constitution/synthesis-v1.md

# Mosaic Framework Constitution — Synthesis v1 (Chief Architect Ruling)

**Status:** Canonical design. Resolves the seven-position debate (`debate/position-*.md`,
`debate/rebuttal-*.md`) against the BRIEF (`BRIEF.md`) and the real framework tree at
`packages/mosaic/framework/`. This document is the single design of record for the alpha. A PRD
derives from it; implementation derives from the PRD.

**Author:** Neutral Chief Architect.
**Scope:** DQ1–DQ5 of the BRIEF, plus the two release-blockers the debate surfaced outside the DQ
frame (LICENSE, hardcoded credential path).

---

## 0. Where the conference actually converged

Seven lenses, near-unanimous on the easy 80%. I am banking the consensus as settled and spending the
ruling on the contested 20%.

**Settled (all or nearly all papers agree — adopted without further debate):**

1. Introduce an explicit **Constitution** layer (framework-owned, immutable law) distinct from
   persona (SOUL) and operator profile (USER). (every paper)
2. Split content by **ownership × upgrade-fate × residency**, not by topic. (architect §1.2,
   devex DQ1, aiml DQ1, coder DQ1, contrarian DQ1)
3. **Delete `defaults/SOUL.md`** (the "Jarvis"/"PDA" file). Persona ships only as
   `templates/SOUL.md.template`, generated at init. `install.sh:232-241` already refuses to seed it.
   (every paper)
4. **Subtraction before structure:** create the Constitution *by extraction and deletion*, never by
   addition. A fifth restatement on top of four existing ones yields five disagreeing law files.
   (contrarian, endorsed in every rebuttal)
5. **A blocking CI grep** for personal data + dead paths is the only durable anti-regression control.
   (every paper)
6. **"Hooks are the real enforcement; prose is the spec"** — promote the repo's own
   `prevent-memory-write.sh` lesson (`runtime/claude/RUNTIME.md:30-32`) to Constitution doctrine.
   (devex DQ4, contrarian DQ5, aiml §1.2, coder, steward, moonshot)
7. **Remove framework-owned files from `PRESERVE_PATHS`** so gate updates reach existing installs.
   (every paper — this is the literal drift bug)
8. **An enforced resident-token budget**, or the new Constitution re-bloats into the old 155-line
   `AGENTS.md` within two releases. (aiml DQ5, endorsed by devex, coder, moonshot, contrarian)
9. **Fix the false `defaults/AGENTS.md:11` claim** ("already in your context… do not re-read") — it
   is provably false on a bare `claude` launch and teaches agents to skip the gates. (coder,
   contrarian, devex, aiml, moonshot)

**Verified live facts (I re-ran the greps, did not trust the papers):**

- `tools/_lib/credentials.sh:19` AND `tools/git/detect-platform.sh:89` both default to
  `$HOME/src/jarvis-brain/credentials.json` — a private path shipped as an executable default.
- `mosaic/rails/git/` appears in **12 shipped template files** (all of `templates/agent/` +
  `projects/*`), while `defaults/AGENTS.md:30` uses `tools/git/` and `install.sh:192-194` actively
  deletes a stale `rails` symlink. A dozen templates emit a command pointing at a path the installer
  removes.
- **No LICENSE** at monorepo root, `packages/mosaic/framework/`, or as a `package.json` field.

**Contested 20% (resolved in the Decision Records, §3):** number of layers; physical-directory split
vs flat files; one Constitution *file* vs a `constitution/` *directory*; 3-way merge vs `.local`
overlays; YAML front-matter + hash-refusal vs structural enforcement; capability-manifest JSON vs
prose table; injection-by-value vs self-load.

---

## 1. The Canonical Layer Model

Five **concerns**, collapsed into **four owned layers** plus a non-resident governance spec. The
collapse resolves the architect-vs-contrarian layer-count fight: the architect's "Standards" and
"Operator Policy" are real *concerns* but do not earn *separate sovereign documents* — Standards is
framework law that a deployment tightens via an additive overlay; Operator Policy is a section of
USER plus optional `policy/` example files. (Decision D1, D2.)

A layer boundary is legitimate **iff** the two sides differ in **owner**, **upgrade-fate**, OR
**residency**. This single test (architect §1.2, banked by every rebuttal) does all the work.

| # | Layer | Owns | Owner | Upgrade fate | Residency | Canonical deployed path |
|---|-------|------|-------|--------------|-----------|--------------------------|
| **L0** | **Constitution** | Irreducible non-negotiable law: hard gates, escalation triggers, block-vs-done, mode declaration, precedence rule, the "hooks are the gate" doctrine, the "no operator context in framework PRs" rule | Framework | **Overwritten wholesale every upgrade.** Never in `PRESERVE_PATHS`. 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, the E2E procedure, QA matrix, orchestrator protocol, all `guides/*` | Framework (deployment may **tighten** via overlay) | Overwritten; user delta lives in `STANDARDS.local.md` / never edits guides | `STANDARDS.md` resident; `guides/*` on-demand | `~/.config/mosaic/STANDARDS.md`, `~/.config/mosaic/guides/*` |
| **L2** | **Persona (SOUL)** | Agent name, tone, role, communication style, persona-scoped 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/accommodations, comms prefs, projects, **operator policy** (e.g. merge-authority delegation), operator tool paths | 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 config, MCP wiring, injection tier) | Repo / framework | Project file user-owned; runtime mechanism overwritten | Project loaded in-repo; runtime resident, ~15 lines | `<repo>/AGENTS.md`, `~/.config/mosaic/runtime/<h>/RUNTIME.md` |
| — | **Layer-Model spec** (governance) | The definition of these layers + precedence + "what may live in L0" | Framework maintainers | Source-only, **never deployed** | Not resident | `packages/mosaic/framework/constitution/LAYER-MODEL.md` |

`AGENTS.md` (deployed) is **not a layer** — it is the thin **load-order dispatcher + Conditional
Guide Loading table** that routes to L0–L4. It is framework-owned and overwritten on upgrade.

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

A flat "L0 > L1 > L2 > L3" ordering is a trap (contrarian DQ1, devex DQ1): persona and law are not on
the same axis. The governing rule, stated **verbatim in L0**, in one sentence each:

> **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.

This generalizes the two good instincts already half-present in the tree (`SOUL.md:48`, injected
reminders never expand permissions; `SOUL.md:32`, user formatting wins) and makes precedence **total
and one-sentence-holdable** rather than scattered across runtime files. (D3.)

### Enforcement strength is ranked, not chosen

Resolving the conference's central fault line (injection-by-value vs self-load vs metadata-gate): the
three are **not alternatives** — they are a **priority ladder** (aiml §3, devex §3, architect §3,
coder, contrarian):

```
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-template-tokens).
   A hook does not compete for attention or care about injection tier. This *drains* prose out of the
   resident core, which is the precondition that makes the next tier work.
2. **Resident-by-value second.** The irreducible *non-checkable* gates (the ones governing *when the
   agent stops* — block-vs-done, escalation, completion-definition) are injected by value at primacy
   on the strongest channel each harness offers, restated as a ≤5-bullet anchor at the recency
   position (bottom).
3. **File-read third (fallback).** `AGENTS.md` says: *"If `CONSTITUTION.md` is not already in your
   context, READ IT NOW."* — conditional, never the false unconditional "already loaded." This is the
   safety net for harnesses/launches where injection silently failed; it is explicitly the weakest
   tier, never the primary mechanism.

---

## 2. File-by-File Plan (what content moves where)

### 2a. New files

| New file | Content | Source of content |
|----------|---------|-------------------|
| `~/.config/mosaic/CONSTITUTION.md` (ships as `defaults/CONSTITUTION.md`) | **L0, one flat file, ~70–90 lines.** The 13 hard gates *minus* the operator-policy clause (see below); the 5 escalation triggers; block-vs-done; mode declaration protocol; the one-sentence precedence rule (both axes); the "hooks are the gate" doctrine; the "no operator context in framework PRs" rule; a single pointer line to the guide index. **Gates keep full unambiguous wording; procedure (wrapper paths, flags) moves to L1.** | Extracted from `defaults/AGENTS.md:23-87` |
| `packages/mosaic/framework/constitution/LAYER-MODEL.md` | The §1 layer model + precedence + "what may live in L0" governance spec. **Source-only, never deployed, never resident.** | This document |
| `packages/mosaic/framework/examples/personas/execution-partner.md` | The sanitized, placeholdered essence of the Jarvis persona (a worked example, copied on request, never auto-loaded) | `defaults/SOUL.md` (sanitized) |
| `packages/mosaic/framework/examples/overlays/e2e-loop.json` | The sanitized, placeholdered essence of `jarvis-loop.json` (`~/src/<your-project>` placeholders) | `runtime/claude/settings-overlays/jarvis-loop.json` |
| `packages/mosaic/framework/examples/policy/merge-authority.example.md` | The operator-policy merge-authority decision, as an *example* operator policy a deployment may adopt | `defaults/AGENTS.md:37` ("Policy: Jason, 2026-06-11") |
| `LICENSE` (monorepo root) + `packages/mosaic/framework/LICENSE` | MIT license text | new (D8) |
| `CONTRIBUTING.md` (framework package) | Layer model, PII/secrets prohibition, the dedup rule, how to add a harness adapter, the re-contamination rule | new (D8) |
| `tools/quality/scripts/verify-sanitized.sh` | The blocking CI grep (PII + home paths + dead `rails/` + unrendered tokens) | new (D6) |

### 2b. Files that shrink / change role

| File | Change | Why (DQ) |
|------|--------|----------|
| `defaults/AGENTS.md` | Gut from 155 lines to a **~50-line dispatcher**: load order + Conditional Guide Loading table + the self-bootstrapping "read CONSTITUTION.md if not resident" line. **Zero restated gates.** Remove from `PRESERVE_PATHS`. | DQ1, DQ5 |
| `defaults/STANDARDS.md` | Stays L1, but: drop the **"Master/slave model"** framing (line 5); stop re-asserting gates that now live in L0; end with an additive include convention for `STANDARDS.local.md`. Remove from `PRESERVE_PATHS`. | DQ1, DQ3, DQ5 |
| `defaults/TOOLS.md` | Delete the `jarvis-brain` MANDATORY rule (line 40). Generic tool index only; operator-specific rules move to the operator's `USER.md`/project `AGENTS.md`. | DQ2 |
| `templates/SOUL.md.template` | Already clean and correct. Keep. Ensure every `{{TOKEN}}` has a non-empty default in `mosaic-init` (no placeholder can survive into a resident file). | DQ2 |
| `templates/agent/AGENTS.md.template` (+ 11 sibling/project templates) | **Delete the restated Hard-Gates block.** Replace with one line: *"This project is governed by `~/.config/mosaic/CONSTITUTION.md`. Add only project-specific extensions below."* **Fix all `rails/git/` → `tools/git/`.** | DQ4, DQ5 |
| `runtime/{claude,codex,pi,opencode}/RUNTIME.md` | Strip restated policy (wrappers-first, mode declaration, caution-doesn't-override-gates). Reduce to **harness mechanism only** + a one-line reference to `CONSTITUTION.md`. | DQ4, DQ5 |
| `tools/_lib/credentials.sh:19`, `tools/git/detect-platform.sh:89` | `$HOME/src/jarvis-brain/credentials.json` → `${MOSAIC_CREDENTIALS_FILE:?MOSAIC_CREDENTIALS_FILE must be set}` (fast-fail, consistent with the framework's own `STANDARDS.md:35` ban on `${VAR:-default}` for required values). Document the env var in `USER.md.template` under `## Tool Paths`. | DQ2 (blocker) |
| `guides/ORCHESTRATOR.md` (lines 99,111,152), `guides/TOOLS-REFERENCE.md`, `guides/BOOTSTRAP.md` | Replace `jarvis-brain/docs/templates/` with `~/.config/mosaic/templates/` (the canonical install path). | DQ2 |

### 2c. Files deleted / moved out of the shipped package

| File | Action | Why |
|------|--------|-----|
| `defaults/SOUL.md` | **Delete.** Persona is generated at init from the template only. | Primary contamination vector |
| `runtime/claude/settings-overlays/jarvis-loop.json` | **Delete**; sanitized essence → `examples/overlays/e2e-loop.json` | Personal project map |
| `defaults/AUDIT-2026-02-17-framework-consistency.md` | **Move** to `docs/` at monorepo root (maintainer artifact, not agent context) | Not framework content |

---

## 3. Decision Records

Each contested question, resolved with Decision / Rationale / Rejected.

### D1 — Layer count: four owned layers (+ a non-resident spec), not five, not three

- **Decision:** L0 Constitution / L1 Standards+Guides / L2 Persona / L3 Operator / L4 Project+Runtime.
  "Operator Policy" is a section of L3 (USER) plus optional `policy/*.md`, not a fifth sovereign layer.
- **Rationale:** The owner×fate×residency test legitimizes splitting law from persona from operator
  (so the "Policy: Jason, 2026-06-11" clause at `defaults/AGENTS.md:37` *must* leave L0 — different
  owner, different upgrade-fate). But it does **not** legitimize a standalone `policy/` *layer*: no
  paper named a failure mode that "USER.md has a `## Operator Policy` section" cannot handle
  (steward §2b). Three layers (contrarian/coder) under-serves the merge-authority extraction; five
  (architect) re-creates the very `AGENTS.md`/`STANDARDS.md` overlap that already drifts (contrarian
  §2c). Four is the count where every boundary passes the test and none is gratuitous.
- **Rejected:** Architect's five layers (Standards + Operator-Policy + Deployment as separate
  sovereigns) — taxonomy inflation; more documents to keep non-duplicative is the disease, not the
  cure. Contrarian/coder's strict three — loses the operator-policy seam the merge-authority leak
  proves is needed.

### D2 — One flat `CONSTITUTION.md`, not a `constitution/` deploy directory

- **Decision:** L0 deploys as a **single flat file** `~/.config/mosaic/CONSTITUTION.md`. The
  `constitution/` directory exists **only in the package source**, holding the non-deployed
  `LAYER-MODEL.md` governance spec.
- **Rationale:** A directory of `GATES.md`+`DELIVERY.md`+… multiplies load-order failure points — on a
  weak-injection harness an agent can load file 1, get pulled into the task, and operate with
  incomplete gates (coder §3, devex "load-order indirection"). You can anchor a *file* at
  primacy+recency; you cannot anchor a *directory* (aiml). One file is injected/read whole and is
  impossible to partially load. The separation-of-concerns the directory camp wants is real but is a
  *post-alpha evolution target*, triggered only if L0 exceeds its budget.
- **Rejected:** Architect/steward/moonshot `constitution/` deploy directory — correct intuition, wrong
  alpha granularity; reserve for v2.

### D3 — Precedence is structural (placement + overwrite + hooks), not metadata/hash-enforced

- **Decision:** Enforce L0 supremacy and immutability through (a) **directory/overwrite mechanics** —
  L0 is overwritten wholesale every upgrade, so a user edit simply does not survive; (b) **placement**
  — L0 at primacy, ≤5-bullet anchor at recency, SOUL/USER in the low-attention middle; (c) **hooks/CI**
  for every checkable gate. No YAML front-matter, no content-hash launch gate.
- **Rationale:** Front-matter (`mosaic-layer: 0`, `mosaic-override: forbidden`) spends the single most
  valuable primacy-position attention slot on key-value pairs whose audience is a bash script, and
  teaches the model that override-rules are parseable properties — an injection surface (aiml §2.1,
  steward §2a, coder §2b, devex §2a). Hash-refusal-on-launch is invisible on the exact direct-launch
  paths where drift happens (it only runs inside `mosaic <harness>`), bricks the one user who
  customized, and false-positives on every mid-upgrade state and CRLF/trailing-newline diff (every
  rebuttal rejected it). Immutability-by-overwrite needs zero hashes: overwrite *is* the guarantee.
- **Rejected:** Moonshot's front-matter + "launcher refuses to start on hash mismatch"; steward's
  `--check-constitution`-as-error. A **post-hoc advisory** `mosaic doctor` drift *warning* (never a
  launch block, never on model-visible bytes) is acceptable and kept.

### D4 — Upgrade-safe customization = additive `.local` overlays, not 3-way merge

- **Decision:** Framework-owned files (L0, L1 `STANDARDS.md`+`guides/*`, `AGENTS.md`, runtime) are
  **overwritten wholesale** on upgrade. User customization that must survive lives in **never-touched
  additive overlays**: `SOUL.local.md`, `USER.local.md`, `STANDARDS.local.md`, optional `policy/*.md`.
  One overlay mechanism, **owned by the launcher/composer**, resolved *before* injection — not a
  per-guide variant, not an inert `<!-- mosaic:include -->` comment. `TOOLS.md` (generated then
  hand-tuned) is the one file that may keep the existing `.bak.<ts>` backup-on-regenerate behavior.
- **Rationale:** The directory/overwrite split makes 3-way merge **unnecessary** — there is nothing to
  merge when framework files are clobbered and user deltas are separate (architect §2.2, contrarian
  §2a). Markdown has no merge semantics: `git merge-file` resolves by line, so a reflowed paragraph
  produces phantom conflicts, and a half-resolved merge can leave `<<<<<<<` markers **inside the
  agent's resident identity file** — the same erratic-behavior class as a half-rendered `{{TOKEN}}`
  (aiml §2.3, moonshot §1). A 3-way merge also needs a `base` that **no current install has**
  (contrarian §2a) — most fragile exactly at the alpha boundary the BRIEF says must not break.
  Interactive merge prompts hang headless launches. The three papers that invented *different* overlay
  schemes (coder per-guide, aiml/devex per-layer, contrarian include-comment) must converge: devex
  (§2b) correctly rules that **per-layer overlays composed by the launcher** is the only one that does
  not silently no-op on a pointer harness.
- **Rejected:** Architect/devex 3-way `mosaic-reconcile`; moonshot interactive `[Y/n]` auto-merge;
  contrarian's inert include-comment; coder's per-guide `.local.md` (guides are L1, referenced not
  forked). Per-layer template-version markers survive **only as a `doctor` advisory signal** ("your
  SOUL was generated from template v2; v4 ships — review `examples/`"), never as a merge trigger.

### D5 — Cross-harness: single L0 source + capability-resolved adapters + tiered injection + a smoke test

- **Decision:** L0 is one canonical text. Adapters carry **mechanism only**. The Constitution speaks
  in **capability verbs** ("use structured reasoning before planning"); each harness adapter binds the
  verb to a concrete tool and declares whether absence is a hard stop. For the **alpha**, that binding
  is a **single markdown table** in the adapter docs (not a JSON manifest). Injection is **tiered and
  honest about asymmetry**: Tier-1 (system-prompt append: Pi, `mosaic claude`/`codex`) injects L0 by
  value; Tier-3 (bare `claude`/`codex`/`opencode` pointer) carries the ≤5-bullet irreducible-gate
  summary **inline** plus the read instruction. A **CI smoke test** launches each harness path and
  asserts the irreducible gates are present in the effective context — the control that makes
  "enforced across harnesses" *true* rather than aspirational.
- **Rationale:** The four harnesses genuinely do not inject symmetrically (devex §3, verified:
  `adapters/pi.md:14-16` system-prompt; Claude append-or-pointer with competing harness
  `<system-reminder>`s; Codex/OpenCode instructions-file). "Byte-for-byte everywhere" is an
  aspiration, not a switch. The capability-verb split kills the **already-live** contradiction —
  `defaults/AGENTS.md:143` says sequential-thinking MCP is REQUIRED-or-stop, while `adapters/pi.md`
  says native thinking replaces it (aiml §1.3). But a bespoke `capabilities.json` schema + validator
  for a four-row, three-axis table is over-engineering at alpha (coder §2c, contrarian §2c): a
  markdown table conveys the same and catches errors at review time. The JSON manifest is a good v2
  evolution once there are 6+ harnesses.
- **Rejected:** Devex's `adapters/<h>.capabilities.json` machine-read manifests **for the alpha**
  (kept as a v2 roadmap item); moonshot's "Pi is the reference harness" (inverts single-source-of-
  truth — defines abstract law in terms of one runtime's affordances; architect §2.3). Moonshot's
  `COMPLIANCE.md` harness×gate **matrix as documentation** is kept (good for visibility); machine-read-
  and-enforced is not.

### D6 — Sanitization: per-layer strategy + a blocking CI gate that closes the *class*, not the tokens

- **Decision:** Per-layer, not one global choice (contrarian DQ2): **L0/L1 ship generic-and-complete**
  (law has no PII once leaks are removed; empty law = no gates = dangerous); **L2/L3 ship as templates
  only**, generated at init (delete `defaults/SOUL.md`); **examples/ ship the worked Jarvis config**
  sanitized + placeholdered (`~/src/<your-project>`), copied on request, never auto-loaded. The
  blocking CI gate (`verify-sanitized.sh`) fails the build on the **structural class**, not just
  current tokens: `jarvis|jason|woltje|\bPDA\b`, plus `~/src/<word>` / `/home/<word>/` absolute home
  paths, plus dead `/rails/` tokens, plus unrendered `{{...}}`/`${...}` in resident files — over
  `defaults/ guides/ templates/ runtime/ adapters/`, excluding `examples/`.
- **Rationale:** The contamination reached ~29–55 files because `defaults/README.md:7`'s prose promise
  has no enforcement; a CI grep is ~15 lines and is the only durable control (every paper). It must
  close the *class* because the primary author of future framework PRs is an agent running with *some*
  operator's SOUL/USER in context — a denylist of today's tokens won't catch tomorrow's operator
  (steward §3, moonshot "biggest risk"). The unrendered-token check closes the half-rendered-template
  failure class (aiml §2.2): a `SOUL.md` containing `You are **{{AGENT_NAME}}**` makes the model adopt
  the literal braces.
- **Rejected:** Generic-defaults for persona (recreates the bug — "Assistant" becomes the new
  "Jarvis"; devex DQ2); empty-defaults for persona (terrible first-run); prose-only sanitization
  (already proven to decay).

### D7 — Resident-token budget: budget the *container* by line count, keep gate *wording* intact

- **Decision:** Enforce a **resident line-count ceiling in CI + `mosaic-doctor`** over the
  always-resident set (`CONSTITUTION.md` + `AGENTS.md` index + `SOUL.md` + `USER.md` + the resident
  RUNTIME slice). Budget the *container*, not the constitution's clarity. Gates keep full unambiguous
  wording; *procedure* (wrapper paths, `--purpose` flags) moves to on-demand `E2E-DELIVERY.md`.
- **Rationale:** A new top-level `CONSTITUTION.md` is psychologically tempting to fill and will
  re-bloat to 155 lines within two releases without a mechanical forcing function (aiml "biggest
  risk," moonshot §1). But moonshot's "exactly 500 words" is asserted, not derived, and is
  **self-defeating**: gate #13 alone is ~110 words, so a 500-word cap forces *paraphrasing the gates*
  — paraphrased law is the exact drift vector we are killing (aiml §2.2). Budget the resident *set* by
  line count (the mechanism several papers converge on); let each gate keep its wording; push
  procedure to guides.
- **Rejected:** Moonshot's "exactly 500 words for CONSTITUTION.md" — right instinct, wrong unit;
  forces lossy compression of normative text.

### D8 — Two non-DQ release blockers ship in the alpha DoD: LICENSE and the credential path

- **Decision:** Add **MIT** `LICENSE` (monorepo root + framework package) + `"license": "MIT"` in
  `package.json`, on day zero. Fix both hardcoded `$HOME/src/jarvis-brain/credentials.json` defaults to
  fast-fail env vars. Ship `CONTRIBUTING.md` (with the operator-data-hygiene section) with the alpha,
  not deferred.
- **Rationale:** "Public does not mean licensed" — under Berne, an unlicensed public repo is
  all-rights-reserved, so every fork/contribution has unclear IP status, and retroactively licensing
  after the alpha creates ambiguity about the pre-license period (steward, the only paper to surface
  this; endorsed by architect §1.3, devex §1c). A hardcoded private credential path shipped as an
  executable default is worse than the persona contamination — it is in the *tooling* layer and it is
  runnable. MIT maximizes adoption and signals genuine open infrastructure.
- **Rejected:** Deferring LICENSE/CONTRIBUTING to "pre-stable" — the alpha will have downstream users;
  the window to fix legal status cleanly closes at the alpha tag. AGPL/Apache considered; MIT chosen
  for adoption (revisitable, but pick one now).

---

## 4. Sanitization plan for the public package

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

**Generated at `mosaic init` (never in the package, gitignored downstream):**
`~/.config/mosaic/SOUL.md`, `USER.md`, `TOOLS.md` (rendered from templates), `*.local.md` overlays,
optional `policy/*.md`, per-harness runtime copies.

**Deleted / relocated from the shipped tree:** `defaults/SOUL.md` (delete);
`runtime/claude/settings-overlays/jarvis-loop.json` (delete → `examples/overlays/`);
`defaults/AUDIT-2026-02-17-*.md` (move to monorepo `docs/`).

**Mechanical gate (the durable control):** `tools/quality/scripts/verify-sanitized.sh`, wired into
`.woodpecker.yml`, blocking. Fails on: operator tokens; absolute home paths (`~/src/<word>`,
`/home/<word>/`); dead `/rails/` paths; unrendered `{{...}}`/`${...}` in resident files. Excludes
`examples/`. Plus a structural-firewall **L0 rule**: *"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."*

---

## 5. Customization + upgrade-safety mechanism

**The single sentence a user can now truthfully 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. Want to change framework behavior?
Add a `.local.md` overlay or a `policy/` file (tighten-only)."*

**Mechanism:**

1. **Physical seam = ownership.** Framework-owned files are overwritten wholesale (`rsync` without an
   exclude); user-owned files (`SOUL.md`, `USER.md`, `*.local.md`, `policy/`, `TOOLS.md`, `memory`,
   `sources`, `credentials`) are the *only* `PRESERVE_PATHS` entries. **Remove `AGENTS.md` and
   `STANDARDS.md` from `PRESERVE_PATHS`** — this single change makes gate updates reach every existing
   install (the literal drift bug, contrarian §0/§3).
2. **Additive overlays, launcher-composed.** `mosaic compose-contract <harness>` concatenates, in
   precedence order, base + `.local` deltas *before* injection, so the model receives one pre-merged
   blob and never runs a redundant read-merge ritual. (D4.)
3. **One global `FRAMEWORK_VERSION` integer + linear migrations** (the existing `install.sh:160-202`
   scaffold). No per-layer version matrix — it is a combinatorial test cliff no single maintainer will
   cover (contrarian, steward §2b). Per-layer template versions survive only as a `doctor` *advisory*.
4. **Migration v2→v3 (backward-compatible, the BRIEF's hard constraint):**
   - Snapshot `~/.config/mosaic/` → `~/.config/mosaic/.backup-v2/` before touching disk.
   - Install `CONSTITUTION.md` as a **new** file nothing previously owned (avoids the reclassification
     catastrophe moonshot §2 flags — we do **not** try to diff/split a user-edited flat `AGENTS.md`
     into "framework vs user" content).
   - Install the slimmed `AGENTS.md` dispatcher; remove `AGENTS.md`/`STANDARDS.md` from
     `PRESERVE_PATHS` going forward.
   - The agent self-loads L0 from `AGENTS.md` regardless of launcher injection (the self-bootstrap
     fallback), so even a stale-pointer install gets the gates.
5. **The migration is the biggest risk; gate it with a falsifiable test matrix** (contrarian §3, the
   *decider*, not a mitigation). Alpha cannot tag until three fixtures pass with **no interactive
   prompt, no hang**: (1) fresh install; (2) legacy-flat user-edited install — law moves, user files
   survive; (3) user-tuned-standard install — change survives as `STANDARDS.local.md`, framework
   `STANDARDS.md` updates. Smallest design that passes all three wins (it does: `rsync` + linear
   migration + overlays + a 15-line grep — zero new subsystems).
6. **Detection without enforcement:** `mosaic doctor` reports drift/unrendered-tokens/budget-overflow
   as **advisories** (warn, never block launch). `--check-constitution` is an opt-in diagnostic, not a
   gate (D3).

---

## 6. Cross-harness strategy (single source of truth + adapters)

**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 (kills the four-way duplication and the
live `rails/`-vs-`tools/` + sequential-thinking-except-Pi contradictions).

**Adapter contract (mechanism only):** an `adapters/<h>.md` / `runtime/<h>/RUNTIME.md` may specify
**only** (a) the injection channel + tier this harness uses, and (b) how L0's **capability verbs** map
to concrete tools (subagent syntax, MCP wiring, hook config). The Constitution says *"use structured
reasoning before planning"*; the Claude adapter binds it to `mcp:sequential-thinking` (gate=true), the
Pi adapter to native thinking (gate=false). For the alpha this binding is a markdown table; JSON
manifests are a v2 item once 6+ harnesses exist.

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

| Harness | Channel | Tier | L0 delivery |
|---------|---------|------|-------------|
| Pi | `--append-system-prompt` (+ no hook backstop) | 1 | By value at primacy; keep L0 tiny — resident fidelity is Pi's *only* enforcement |
| `mosaic claude` / `mosaic codex` | system-prompt append | 1 | By value at primacy + ≤5-bullet recency anchor |
| Codex / OpenCode (instructions-file) | written file | 2 | Resident-ish; self-load line as backup |
| bare `claude`/`codex`/`opencode` | thin pointer | 3 | Pointer carries the ≤5-bullet gate summary **inline** + "READ CONSTITUTION.md NOW" — never the false "already loaded" |

**Mechanical backstop:** every hookable gate is a hook where the harness supports one
(`prevent-memory-write.sh` precedent); Codex/OpenCode hook parity is a **tracked gap** in the
compliance doc, not a silent inconsistency. A **CI smoke test** asserts the irreducible gates are
resident on every harness path — the control that makes the cross-harness claim true.

---

## 7. Alpha Definition of Done (derived, for the PRD)

Blocking: MIT LICENSE + `package.json` field; credential-path fast-fail fix; `defaults/SOUL.md` +
`jarvis-loop.json` deleted; `rails/`→`tools/` fixed in 12 templates; `verify-sanitized.sh` green and
wired to CI; `CONSTITUTION.md` extracted (gates one place, dispatcher `AGENTS.md` self-bootstraps);
`AGENTS.md`/`STANDARDS.md` out of `PRESERVE_PATHS`; resident line-count budget enforced; per-layer
overlay + compose step; migration v2→v3 passing the 3-fixture matrix with no hang; cross-harness smoke
test green; `CONTRIBUTING.md` with operator-hygiene section; tag the alpha. PRD precedes implementation.

**Explicitly deferred to post-alpha (v2):** `constitution/` deploy directory; `adapters/<h>.capabilities.json`
JSON manifests; 3-way merge reconciliation; per-layer version stamps as a migration driver; DCO CI.