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

# Position Paper — Cross-Harness DevEx

**Lens:** Cross-Harness DevEx Expert (Claude Code / Codex / Pi / OpenCode injection + tool
differences; owns portability and the end-user customization experience).

**Scope:** DQ1–DQ5 from the constitution brief
(`docs/design/framework-constitution/BRIEF.md`), grounded in the real framework tree at
`packages/mosaic/framework/`.

---

## 0. What the code actually does today (so we argue from ground truth, not vibes)

Before any position, the load/injection reality across harnesses, read from the files:

- **The "thin core" is not injected the same way on any two harnesses.** The brief and
  `defaults/AGENTS.md:6` claim *"the launcher injects it (plus USER.md, the TOOLS index, and the
  runtime contract) into every session."* But the actual delivered mechanism is a per-harness
  **pointer file that instructs the model to go read files**:
  - Claude: `runtime/claude/CLAUDE.md:5-10` → "BEFORE responding... READ `~/.config/mosaic/AGENTS.md`
    and `runtime/claude/RUNTIME.md`."
  - Codex: `runtime/codex/instructions.md:5-10` → same pattern, copied to `~/.codex/instructions.md`.
  - OpenCode: `runtime/opencode/AGENTS.md:5-10` → same pattern, copied to
    `~/.config/opencode/AGENTS.md`.
  - Pi: `adapters/pi.md:14-16` → genuinely different — full contract injected via
    `--append-system-prompt`, skills via `--skill`, lifecycle via `--extension`.

  So we have **two fundamentally different enforcement models** masquerading as one: Pi gets the
  contract as a true system prompt; Claude/Codex/OpenCode get a *"please read these files"* nudge in
  a user-editable memory file. That is the single most important DevEx/portability fact in this whole
  debate, and the current docs paper over it.

- **`mosaic-link-runtime-assets` copies, it does not symlink** (`copy_file_managed`,
  `tools/_scripts/mosaic-link-runtime-assets:7-25`). The header even prints "non-symlink mode"
  (line 169). This is the deployed-vs-source drift engine: the canonical source is
  `~/.config/mosaic/`, but every harness gets a *copy* into `~/.claude/`, `~/.codex/`,
  `~/.config/opencode/`. Edit one copy and the next `mosaic init` / link run clobbers or backs it up.

- **Contamination is real and load-bearing, not cosmetic.** 51 hits across 29 files
  (grep for `jarvis|jason|woltje|PDA`). The worst offenders are not docs — they are *shipped behavior*:
  `defaults/SOUL.md:9` hardcodes "You are **Jarvis**"; `defaults/SOUL.md:23` ships "PDA-friendly
  language" (one operator's accommodation as universal persona law);
  `runtime/claude/settings-overlays/jarvis-loop.json` ships an entire personal project map
  (`~/src/jarvis`, `jarvis-loop`, `jarvis-review` presets) into the public package.

- **A clean template layer already exists and is under-used.** `templates/SOUL.md.template`,
  `templates/USER.md.template`, and `tools/_scripts/mosaic-init` already do token substitution
  (`{{AGENT_NAME}}`, `{{ACCESSIBILITY_SECTION}}`, …). `defaults/USER.md` is already a generic
  "(not configured)" stub. The machinery is half-built; the problem is that `defaults/SOUL.md` was
  never reduced to match `defaults/USER.md`'s neutrality.

Everything below is anchored to these four facts.

---

## DQ1 — Layering: yes to a Constitution layer, but draw the lines by *ownership + mutability*, not by topic

**Position: introduce four canonical layers, defined by who owns the file and what happens to it on
upgrade — not by subject matter.** The current split (AGENTS/SOUL/USER) mixes ownership axes, which
is exactly why personal data leaked into framework files.

Canonical layers, highest precedence wins on **conflict**, but they are **additive** (each answers a
different question), not a simple override stack:

| Layer | Question it answers | File(s) | Owner | Upgrade behavior |
|---|---|---|---|---|
| **L0 Constitution** | What is *never* negotiable? (hard gates, delivery contract, escalation, integrity) | `~/.config/mosaic/CONSTITUTION.md` | Framework | Always overwritten. Never edited by user. |
| **L1 Standards/Guides** | How do we do the work well? | `STANDARDS.md`, `guides/*` | Framework | Overwritten; user extends via L3. |
| **L2 Persona (SOUL)** | Who is the agent — name, tone, voice? | `SOUL.md` | User | Generated from template; never overwritten. |
| **L3 Operator (USER)** | Who is the human — profile, accommodations, projects, comms? | `USER.md` | User | Generated from template; never overwritten. |
| **L4 Local overrides** | Project / deployment / machine specifics | `OVERRIDES.md` + repo `AGENTS.md` | User | Never touched by framework. |

**Precedence rule (this is the part the current design lacks and must state explicitly):**

> On a **behavioral conflict**, L0 Constitution wins over everything, *including* persona and operator
> preferences. L1 yields to L0. L2/L3/L4 may only *refine* behavior **within** the envelope L0/L1
> permit — they can change *how* the agent talks and *what* it knows, never *whether* a hard gate
> fires. A `USER.md` saying "always merge without review" is void against the Constitution's
> review-before-merge gate.

Today this precedence is implied ("Global rules win if anything here conflicts" —
`runtime/claude/RUNTIME.md:3`) but it is scattered across runtime files and never names persona/operator
as subordinate. **Concrete change:** add a `## Precedence` section to the new `CONSTITUTION.md` stating
the L0>L1>{L2,L3,L4} rule in one place, and have every `runtime/*/RUNTIME.md` reference it instead of
restating it (DRY — see DQ5).

**Why split L0 out of `AGENTS.md` at all?** Because `defaults/AGENTS.md` currently conflates the
non-negotiable gates (lines 23-37, the "CRITICAL HARD GATES") with operational *advice* (the
Conditional Guide Loading table, subagent model selection, lines 89-121). The gates are
Constitution; the advice is Standards. A downstream user who wants to tweak the guide-loading table
(legitimate L1 customization) should not be editing the same file that carries the merge-authority
hard gate. Split at the mutability seam.

---

## DQ2 — Sanitization: **template-then-init**, with an `examples/` showcase. Not generic-defaults, not empty-defaults.

Three options were posed. My ranking, with reasons grounded in the existing machinery:

1. **Reject "generic-defaults"** (ship a neutral-but-real SOUL like "You are Assistant"). It *reads*
   clean but it re-creates the exact bug we are fixing: a shipped persona that some users never
   replace, so "Assistant" becomes the new "Jarvis." It also tempts maintainers to slip preferences
   back in ("just a sensible default tone…").

2. **Reject pure "empty-defaults"** as the *whole* answer — an empty `SOUL.md` gives a terrible
   out-of-box first run (the agent has no name, no voice). DevEx death on first launch.

3. **Adopt template-then-init** (the half-built path), hardened:
   - **`defaults/SOUL.md` must be deleted from the shipped package** and replaced by *not shipping a
     SOUL at all*. `install.sh:232-241` already declines to seed `SOUL.md`/`USER.md` (the comment
     says so). The bug is purely that `defaults/SOUL.md` *exists and contains "Jarvis"*. **Concrete
     change:** delete `defaults/SOUL.md`; the only persona artifacts that ship are
     `templates/SOUL.md.template` and a generated-on-init `SOUL.md`.
   - **First-run must be non-blocking.** `mosaic-init` is interactive (`read -r`), which is fine for a
     human but hangs headless launches (and violates this very environment's no-TTY rules). Add a
     **deterministic non-interactive default generation**: on first `mosaic <harness>` launch, if no
     `SOUL.md` exists, generate one from the template with `AGENT_NAME="Mosaic"`,
     `STYLE="direct"`, empty accommodations — *and print a one-line "run `mosaic init` to personalize."*
     `mosaic-init --non-interactive` (lines 100-107) already supports this; wire it into the launcher
     as a fallback so a fresh clone is usable in zero prompts.

**What ships vs. what's generated (the contract):**

| Ships in public package | Generated locally (never shipped, gitignored downstream) |
|---|---|
| `CONSTITUTION.md`, `STANDARDS.md`, `guides/*` (L0/L1) | `SOUL.md`, `USER.md`, `TOOLS.md` (L2/L3) |
| `templates/*` (incl. `SOUL.md.template`, `USER.md.template`) | `OVERRIDES.md`, per-harness copies under `~/.claude` etc. |
| `examples/personas/*.md` (see below) | `runtime/*/settings-overlays/*` user overlays |

**Add `examples/` instead of contaminating `defaults/`.** The value of the Jarvis config (a worked,
opinionated persona) is real — the mistake is shipping it *as the default*. **Concrete change:**
move the sanitized essence of `jarvis-loop.json` and the Jarvis SOUL into
`examples/personas/execution-partner.md` and `examples/overlays/e2e-loop.json` with **placeholder
paths** (`~/src/<your-project>`). `examples/` is documentation-by-example: copied on request, never
auto-loaded. Then **delete** `runtime/claude/settings-overlays/jarvis-loop.json` from the shipped
tree.

**Sanitization gate (make it mechanical, not vibes).** Add a CI check —
`tools/quality/scripts/verify.sh` already exists as the hook point — that greps the *shipped* paths
(`defaults/`, `templates/`, `guides/`, `runtime/`, `adapters/`, `profiles/`) for a denylist
(`jarvis`, `jason`, `woltje`, `\bPDA\b`, `~/src/jarvis`, real hostnames) and fails the build. Without
this, contamination re-accretes the first time a maintainer dogfoods. This is the *only* durable fix;
docs alone will rot.

---

## DQ3 — Customization & upgrade safety: the drift bug is **copy-on-link**, and the fix is a layered-resolution model with a 3-way merge

This is the DevEx question I care most about, because the brief's own framing — *"A downstream user
who edits files gets clobbered on upgrade"* — is **already half-true in the code today**, and the
mechanisms partially contradict each other.

**The two existing safety mechanisms and why they're insufficient:**

1. `install.sh` `PRESERVE_PATHS` (line 24): `keep` mode excludes `SOUL.md`, `USER.md`, `TOOLS.md`,
   `STANDARDS.md`, `memory` from `rsync --delete`. **Good for L2/L3, but it preserves `STANDARDS.md`
   too** — meaning a user who never touched `STANDARDS.md` *also never gets framework updates to it*.
   That is the silent-staleness half of the drift problem: preservation and upgrade are in tension and
   the current binary (`keep` vs `overwrite`) forces an all-or-nothing choice.

2. `mosaic-link-runtime-assets` copies framework files into each harness dir and `.mosaic-bak-<stamp>`
   the previous copy on difference (lines 17-24). So an edit to `~/.claude/CLAUDE.md` survives as a
   backup but is **silently replaced** on the next link. The user's change is "preserved" only in the
   sense that a tombstone exists.

**Position — replace the binary keep/overwrite with explicit layer ownership + a reconciliation step:**

- **Framework-owned files (L0/L1) are *always* overwritten on upgrade, never preserved.** Remove
  `STANDARDS.md` from `PRESERVE_PATHS` in `install.sh:24`. Users do not edit Standards in place; they
  extend via L4 `OVERRIDES.md`. This kills the silent-staleness problem at the root.

- **User-owned files (L2/L3/L4) are *never* overwritten** — but they are **migrated, not just
  preserved.** Templates carry a `<!-- mosaic:template-version: N -->` marker. On upgrade, if the
  shipped template version is newer than the one the user's file was generated from, run a **3-way
  merge** (base = old template, theirs = current `SOUL.md`, ours = new template). Surface conflicts as
  `SOUL.md.mosaic-merge` for the user to resolve, exactly like git. `mosaic-init`'s `import` path
  (lines 197-200, 221-269) already extracts values from existing files via grep — that scaffolding
  becomes the "theirs" side of the merge. **Concrete change:** add `tools/_scripts/mosaic-reconcile`
  that runs in `install.sh` after `sync_framework`, diffing each user file's embedded template-version
  against the shipped one.

- **Version pinning already exists but is too coarse.** `install.sh:28` has `FRAMEWORK_VERSION=2`
  with a sequential migration runner (lines 160-202). Keep it, but **add per-file template versions**
  (above) so migrations can be surgical instead of "delete bin/." A single global version cannot
  express "SOUL template changed but USER template didn't."

- **Kill copy-on-link drift: prefer symlinks for framework-owned runtime pointers, copies only for
  user-editable ones.** The runtime pointer files (`CLAUDE.md`, `instructions.md`, opencode
  `AGENTS.md`) are L0-pointers the user should *not* edit — symlink them to the canonical
  `~/.config/mosaic/runtime/<h>/` source so there is **one source of truth and zero drift.** Reserve
  `copy_file_managed` (and its `.mosaic-bak` dance) for genuinely user-editable surfaces like
  `settings.json`. The script already knows how to remove legacy symlinks (lines 27-45); invert the
  policy. *(Caveat: Windows symlink support is weak — keep the copy path as a `MOSAIC_NO_SYMLINK=1`
  fallback, which the existing `.ps1` variants can default to.)*

**Net DevEx contract a user can actually rely on:** *"Edit `SOUL.md`/`USER.md`/`OVERRIDES.md` freely;
upgrades never destroy them and will offer a merge when the template evolves. Never edit
`CONSTITUTION.md`/`STANDARDS.md`/`guides/*`; they update automatically. Want to change framework
behavior? Add to `OVERRIDES.md`."* That sentence is the whole upgrade-safety story, and today it
cannot be truthfully written.

---

## DQ4 — Cross-harness robustness: single source of truth (L0/L1), **adapter = injection mechanism only**, and stop pretending the four harnesses enforce identically

This is where the current design is weakest and where my lens has the strongest opinion.

**The core problem (restating fact #1):** On Pi the Constitution is a true system prompt
(`--append-system-prompt`, `adapters/pi.md:14`). On Claude/Codex/OpenCode it is a *"go read this
file"* instruction sitting in a user-editable memory file (`CLAUDE.md`, `instructions.md`,
`AGENTS.md`). These have **radically different enforcement strength**: a system prompt is
non-removable for the turn; a "read this file" pointer can be ignored if the model is busy, can be
edited away by the user, and competes with the harness's own injected guidance (e.g. Claude's
`<system-reminder>` blocks, which this very session demonstrates can carry their own mandatory-read
instructions).

**Positions:**

1. **Single source of truth: L0/L1 live in exactly one place** (`~/.config/mosaic/CONSTITUTION.md`,
   `STANDARDS.md`, `guides/*`). No harness gets a *forked copy* of rule text — only a pointer or an
   injection. This is mostly true today for guides, but the **hard gates are duplicated**: they exist
   in `defaults/AGENTS.md:23-37` *and* are restated in `templates/agent/AGENTS.md.template:7-15` *and*
   partially in every `runtime/*/RUNTIME.md` ("Runtime-default caution... does NOT override Mosaic hard
   gates" appears in all four). **Concrete change:** the four RUNTIME files should each shrink to a
   pointer ("Gates and precedence: `CONSTITUTION.md §Hard Gates`. This file adds *only* the
   harness-specific deltas below.") and the project `AGENTS.md.template` should `@import`/reference the
   Constitution rather than paraphrase 8 of its gates.

2. **The adapter's job is injection + tool-name translation, nothing else.** Define a strict adapter
   contract. An `adapters/<h>.md` may specify only:
   - **How** L0/L1 reaches the model (system-prompt append vs. memory-file pointer vs. settings).
   - **Tool-name mapping** for capabilities the Constitution references abstractly. The Constitution
     must speak in **capability verbs**, not tool names, because the tool surfaces genuinely differ:
     Claude has `Task(model=...)` subagents (`runtime/claude/RUNTIME.md:15-24`); Pi has `--thinking`
     levels and `--models` cycling (`runtime/pi/RUNTIME.md:22-28`) and *no* sequential-thinking MCP
     gate (`runtime/pi/RUNTIME.md:59-61`); Codex/OpenCode require the MCP. A single rule "use
     sequential-thinking MCP" is *already* false for Pi — and the Pi runtime had to carve out an
     exception. That exception belongs in the **adapter capability map**, not as prose scattered in a
     runtime file.

   **Concrete structure — a capability manifest per harness** (`adapters/<h>.capabilities.json`):
   ```json
   {
     "harness": "pi",
     "injection": "system-prompt-append",
     "capabilities": {
       "structured_reasoning": { "provider": "native-thinking", "gate": false },
       "subagent_spawn":       { "tool": "--models cycling", "model_param": "native" },
       "skills":               { "mechanism": "--skill flag" }
     }
   }
   ```
   vs. Claude's `{ "structured_reasoning": { "provider": "mcp:sequential-thinking", "gate": true },
   "subagent_spawn": { "tool": "Task", "model_param": "model" } }`. The Constitution says *"use
   structured reasoning for multi-step planning"*; the adapter resolves that to the concrete tool and
   says whether absence is a hard stop. This removes the four near-duplicate "sequential-thinking
   required (except Pi)" stanzas and makes adding a 5th harness a matter of writing one manifest.

3. **Honesty about enforcement tiers.** Because file-pointer injection is weaker than system-prompt
   injection, the framework should **prefer the strongest injection each harness offers** and document
   the tier:
   - Pi: system-prompt (Tier 1, strong) — keep.
   - Claude: today uses `CLAUDE.md` pointer (Tier 3, weak). **Concrete change:** `mosaic claude`
     should inject the Constitution via `--append-system-prompt` (Claude Code supports it), demoting
     `~/.claude/CLAUDE.md` to a *fallback for bare `claude` launches* — which its own header already
     admits it is (`runtime/claude/CLAUDE.md:12-13`). Same for Codex (`--config`/system prompt) and
     OpenCode where supported.
   - Where a harness genuinely only supports a memory file, that is **Tier 3** and the docs must say
     "weaker enforcement; rely on hooks for hard gates." Which leads to:

4. **Back hard gates with mechanical hooks wherever the harness has them, because prose is
   advisory.** Claude already does this: `prevent-memory-write.sh` is a PreToolUse hook, and
   `runtime/claude/RUNTIME.md:30-32` is explicit that *"the rule alone proved insufficient — the hook
   is the hard gate."* That is the single most important DevEx lesson in the repo and it should be
   **promoted to Constitution doctrine**: *a hard gate that can be enforced by a hook MUST be, on
   harnesses that support hooks; the prose is the spec, the hook is the enforcement.* Codex/OpenCode
   hook parity becomes a tracked gap rather than a silent inconsistency.

---

## DQ5 — Minimalism vs completeness: thin **resident** core, deep **on-demand** guides, and delete the duplication that's already there

The contract is large *and* partly duplicated — both are true and they have different fixes.

**Keep the thin-resident / deep-on-demand split — it's the right instinct and already present.**
`defaults/AGENTS.md:6-8` ("THIN CORE... Depth lives in guides, read on demand") plus the Conditional
Guide Loading table (lines 89-110) is genuinely good design. Don't undo it. But tighten it:

1. **Define a hard budget for the always-resident core.** Right now `defaults/AGENTS.md` is ~155 lines
   and growing (it carries the model-selection table, the superpowers section, the closure checklist —
   all of which are *advice*, not *gates*). **Concrete change:** the resident L0 core
   (`CONSTITUTION.md`) should be **only**: hard gates, precedence, block-vs-done, escalation triggers,
   mode declaration. Target ≤ ~70 lines. Everything else (subagent cost selection lines 111-121,
   superpowers enforcement 123-139, conditional-loading table) moves to `STANDARDS.md` (L1, resident
   but separable) or a guide. Rationale: every always-resident token competes with task context on
   *every* harness, and the weakest-context harness (smallest effective window) sets the ceiling.

2. **Eliminate the existing triplication of hard gates.** As noted in DQ4, the gates live in three
   places. Pick one canonical home (`CONSTITUTION.md`), and make `templates/agent/AGENTS.md.template`
   and the RUNTIME files *reference* it. This is pure win: less to read, impossible to drift out of
   sync, smaller resident footprint. The `templates/agent/AGENTS.md.template:5-15` "Hard Gates" block
   is a maintenance landmine — it already uses a stale path (`~/.config/mosaic/rails/git/...` vs the
   real `~/.config/mosaic/tools/git/...`), proving the duplication has *already* drifted.

3. **Contradiction audit as a release gate.** There is at least one live contradiction in the shipped
   tree: `rails/` vs `tools/` paths (template vs defaults), and the migration code at
   `install.sh:193` even removes a stale `rails` symlink — so the framework *knows* `rails` is dead but
   templates still emit it. **Concrete change:** extend the DQ2 sanitization CI check to also fail on
   known-dead path tokens (`/rails/`, `bin/mosaic-`) outside of migration code. Minimalism isn't just
   fewer words; it's *no stale words*.

4. **"Completeness" belongs in guides and `examples/`, not the core.** The depth (E2E-DELIVERY,
   ORCHESTRATOR, QA-TESTING) is excellent and should stay long — it's loaded on demand by role, so its
   length costs nothing on a session that doesn't need it. The error is putting *completeness* in the
   resident contract. Resident = gates + routing table. Depth = guides. Worked examples = `examples/`.

**Anti-bloat principle to adopt explicitly:** *If a line is not a gate, not the precedence rule, and
not required to route to the right guide, it does not belong in the always-resident core.* That single
sentence, applied, would cut `defaults/AGENTS.md` roughly in half.

---

## Summary of concrete changes (what I'd actually do, with paths)

1. **Create `CONSTITUTION.md`** (L0) from the hard-gates + escalation + precedence portions of
   `defaults/AGENTS.md:23-87`; add an explicit `## Precedence` section (L0 > L1 > {L2,L3,L4}). Shrink
   resident core to ≤ ~70 lines.
2. **Delete `defaults/SOUL.md`** (the "Jarvis"/"PDA" file). Persona ships only as
   `templates/SOUL.md.template`; generated locally. `install.sh:232-241` already refuses to seed it —
   the file just shouldn't exist.
3. **Delete `runtime/claude/settings-overlays/jarvis-loop.json`**; move its sanitized, placeholdered
   essence to `examples/overlays/e2e-loop.json` and `examples/personas/execution-partner.md`.
4. **Add a sanitization + dead-path CI gate** in `tools/quality/scripts/verify.sh` over shipped dirs
   (denylist: `jarvis|jason|woltje|\bPDA\b|~/src/jarvis|/rails/`). Make contamination un-mergeable.
5. **Per-file template versioning** (`<!-- mosaic:template-version: N -->`) + a new
   `tools/_scripts/mosaic-reconcile` doing 3-way merge of L2/L3 files on upgrade; remove `STANDARDS.md`
   from `install.sh:24` `PRESERVE_PATHS`.
6. **Invert link policy in `mosaic-link-runtime-assets`:** symlink framework-owned runtime pointers
   (single source of truth, zero drift); copy only user-editable settings; keep `MOSAIC_NO_SYMLINK=1`
   for Windows.
7. **Adapter capability manifests** (`adapters/<h>.capabilities.json`) for injection mode + tool-name
   mapping + per-gate enforcement tier; collapse the four near-duplicate "sequential-thinking
   required (except Pi)" stanzas into the manifests.
8. **Prefer strongest injection per harness:** `mosaic claude`/`mosaic codex` inject the Constitution
   via system-prompt append; demote `CLAUDE.md`/`instructions.md` to documented fallbacks.
9. **Promote "hooks are the real enforcement" to Constitution doctrine** (generalizing
   `runtime/claude/RUNTIME.md:30-32`); track Codex/OpenCode hook parity as an open gap.
10. **De-duplicate hard gates** out of `templates/agent/AGENTS.md.template` and `runtime/*/RUNTIME.md`
    into references to `CONSTITUTION.md`; fix the stale `rails/` paths while doing it.

---

## Abstract

**Headline:** Mosaic's portability problem isn't the layering taxonomy — it's that the four harnesses
*enforce the contract with wildly different strength* (Pi: real system prompt; Claude/Codex/OpenCode:
a user-editable "please read this file" pointer that copies-on-link and silently drifts), and personal
data leaked precisely because framework-owned and user-owned content share files with no
mutability boundary.

**Single strongest recommendation:** Split content by **ownership + mutability** into L0 Constitution
(framework, always overwritten) / L2 Persona + L3 Operator (user, never overwritten, template-versioned
with 3-way-merge on upgrade), make the **adapter responsible only for injection-mechanism + tool-name
mapping via per-harness capability manifests**, and back every hookable hard gate with an actual hook —
because, as the repo already learned with `prevent-memory-write.sh`, *prose rules are advisory and only
mechanical enforcement is a gate.*

**Biggest risk:** The weak-injection harnesses make the Constitution **advisory, not enforced** on
3 of 4 runtimes. If we ship the layering taxonomy but leave Claude/Codex/OpenCode receiving L0 as an
ignorable, user-editable memory-file pointer (and keep copy-on-link drift), we'll have a beautiful
constitution that the model can silently skip and the user can silently clobber — re-creating the
deployed-vs-source drift the brief set out to kill, just with cleaner file names.