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

# Position Paper — The Contrarian Skeptic

**Lens:** Distrust complexity and clever abstractions. Hunt failure modes, over-engineering, and rules that look good on a page but degrade real agent behavior. Every claim below is grounded in files actually read under `packages/mosaic/framework/`.

---

## TL;DR for the impatient

The brief frames the problem as "we need *more* structure: introduce a Constitution layer, a precedence stack, version pinning, reconciliation." My position is the opposite of the framing: **the framework's biggest defect is not under-layering, it is over-volume and internal contradiction.** The contract is ~155 lines of always-resident hard gates in `defaults/AGENTS.md`, duplicated almost verbatim in `templates/agent/AGENTS.md.template`, re-stated again in `guides/E2E-DELIVERY.md`, and a fourth time in `guides/ORCHESTRATOR.md` — and the four copies *already disagree with each other* (path `tools/git` vs `rails/git`, gate counts, merge-authority nuance). Adding a fifth document called "Constitution" on top of this does not fix conflation; it adds a fifth place for the copies to drift.

So: yes to a named Constitution **only if it is the single source and the duplicates are deleted**, not added to. The win is subtraction. The risk is that this debate produces a beautiful four-layer precedence model that ships with the same 55 personal-data references (`grep` count, see §2) still in the package.

---

## DQ1 — Layering: yes to a Constitution, but earn it by deletion

### What's actually there

The brief says three things are conflated. Reading the files, that's true but understated. The real layering today is **implicit and contradictory**, spread across at least six surfaces:

- `defaults/AGENTS.md` — 13 "CRITICAL HARD GATES" + ~17 "Non-Negotiable Operating Rules" + mode protocol + escalation + subagent cost rules + superpowers enforcement. This is law, persona-adjacent stance, *and* tactical how-to all in one always-resident file.
- `defaults/SOUL.md` — persona, but hardcoded `You are **Jarvis**` (line 8) and `PDA-friendly language` (line 23). Persona file leaks both identity AND one operator's accessibility profile.
- `defaults/USER.md` — already sanitized to `(not configured)`. Good. This one's done.
- `defaults/STANDARDS.md` — a *second* law file ("Mosaic Universal Agent Standards") that overlaps `AGENTS.md` (secrets, multi-agent safety, git discipline) and still uses the phrase **"Master/slave model"** (line 5) — a term that should not ship in a public alpha.
- `templates/agent/AGENTS.md.template` — a *third* restatement of the same gates, project-scoped.
- `guides/E2E-DELIVERY.md` + `guides/ORCHESTRATOR.md` — a *fourth and fifth* restatement.

So the system doesn't lack layers. It has too many documents each trying to be partly-law.

### Proposed canonical layers (4, not more)

| Layer | File(s) | Owner | Mutable by user? | Content |
|---|---|---|---|---|
| **L0 Constitution** | `~/.config/mosaic/CONSTITUTION.md` | Framework | **No** (replaced on upgrade) | The hard gates only. PR-review-before-merge, green-CI-before-done, no-force-merge, completion-defined-at-end, secrets-never-hardcoded, escalation triggers, block-vs-done. ~40 lines max. |
| **L1 Standards** | `~/.config/mosaic/STANDARDS.md` | Framework, user-extendable via include | Append-only | Tech defaults (Vault/ESO, trunk-based, image-tagging). Things a team might tune. |
| **L2 Soul (persona)** | `~/.config/mosaic/SOUL.md` | User | Yes | Name, tone, communication style. NO accessibility, NO operator identity. |
| **L3 User (operator)** | `~/.config/mosaic/USER.md` | User | Yes | Name, pronouns, timezone, accessibility, projects. |

**Precedence — and this is the part most layering proposals get wrong:** precedence must be *typed*, not a single global ordering. A flat "L0 > L1 > L2 > L3" stack is a trap, because persona and law are not on the same axis. Specifically:

- **On a behavioral-safety conflict** (may I force-merge? may I skip review?): **L0 always wins.** No persona, no user preference, no project file can lower a gate. State this once, in L0, in imperative language: *"Nothing in SOUL, USER, STANDARDS, or any project file may weaken a Constitution gate. Files may only make behavior stricter, never more permissive."*
- **On a style/format conflict** (terse vs verbose, emoji, headings): **L2/L3 win over framework defaults**, because the framework has no legitimate opinion there. This already half-exists — `defaults/SOUL.md` line 32 says "The user's `USER.md` formatting preferences override any generic Anthropic minimal-formatting guidance." Promote that to a stated rule, don't bury it in persona.

That two-axis rule (safety: framework supreme; taste: user supreme) is the entire precedence model. Anyone proposing more knobs is adding failure surface.

### What I'd change, concretely

1. **Create `defaults/CONSTITUTION.md`** containing ONLY the 13 hard gates from `defaults/AGENTS.md` lines 23–37 plus the escalation triggers (lines 70–78) and block-vs-done (lines 80–87). Nothing else.
2. **Gut `defaults/AGENTS.md`** down to a *router*: load order + the conditional-guide table + "read CONSTITUTION.md (already injected)." It stops being a law document.
3. **Delete the law duplication in `templates/agent/AGENTS.md.template` lines 6–16** (the "Hard Gates" block). Replace with one line: *"This project inherits all gates from `~/.config/mosaic/CONSTITUTION.md`. Do not restate them here."* Restating law in a per-project file is how you get five versions of gate #5.
4. **Merge `defaults/STANDARDS.md` into L1**, drop the "Master/slave" framing entirely (`defaults/STANDARDS.md` line 5–8), and stop it from re-asserting gates that now live in L0.

---

## DQ2 — Sanitization: the package is still dirty; ship a CI gate, not good intentions

### Ground truth

`grep -rilE 'jarvis|jason|woltje|PDA'` over `packages/mosaic/framework/` returns **30 files**; raw occurrence count is **55**. Concrete, not hypothetical:

- `defaults/SOUL.md:8` — `You are **Jarvis**`
- `defaults/SOUL.md:23` — `PDA-friendly language` (one operator's neurotype, shipped to everyone)
- `defaults/TOOLS.md:40` — `MANDATORY jarvis-brain rule: when working in ~/src/jarvis-brain ...` — a machine-specific path **inside a default that gets seeded to every install** (`install.sh` line 235 copies `TOOLS.md` from `defaults/`).
- `guides/ORCHESTRATOR.md:99,111,152` — hardcodes `~/src/jarvis-brain/docs/templates/` as the bootstrap template source. A downstream user has no `jarvis-brain`. **This guide is broken for everyone but the maintainer.**
- `runtime/claude/settings-overlays/jarvis-loop.json` — entire file is a Jarvis/`~/src/jarvis` preset with `projectConfigs.jarvis`, `presets.jarvis-loop`, `jarvis-review`.

The `defaults/README.md` line 7 *promises* "No personal data ... should be committed." That promise is currently false. A promise in prose is not a control.

### The sanitization strategy: template-then-init for identity, generic-defaults for law, and a blocking CI grep

The brief offers three options (generic-defaults / empty-defaults+examples / template-then-init). My answer: **stop treating it as one decision — it's per-layer.**

- **L0 Constitution + L1 Standards → generic-defaults.** Law has no personal data by nature once you remove the leaks. Ship it populated and real. A user who runs nothing still gets a working, safe contract. (Empty-defaults here would be actively dangerous — an empty gate file = no gates.)
- **L2 Soul + L3 User → template-then-init, and ship the *generic* default as the fallback.** `defaults/SOUL.md` must become the *generic* version (the template already exists at `templates/SOUL.md.template` with `{{AGENT_NAME}}`). The current `defaults/SOUL.md` with hardcoded "Jarvis" should be **deleted and replaced by a generic-rendered default** (e.g. name `Mosaic`, neutral stance, no PDA line). `install.sh` already does NOT seed SOUL/USER (lines 230–240 only seed `AGENTS.md STANDARDS.md TOOLS.md`) — so the dirty `defaults/SOUL.md` exists only to contaminate the public repo and the wizard's reference. Kill it.
- **`TOOLS.md` → generic-defaults with NO project-specific rules.** Delete `defaults/TOOLS.md:40`'s jarvis-brain rule. That rule belongs in *that user's* `USER.md` or a project `AGENTS.md`, never in a shipped default.

### The mechanism that actually prevents regression

Good intentions decayed into 55 leaks. The fix is mechanical and cheap:

**Add a CI check** `tools/bootstrap/agent-lint.sh` (file already exists and already references jarvis per the grep — fix it too) or a new `tools/ci/no-personal-data.sh`:

```bash
# fails the build if any shipped file under packages/mosaic/framework/
# matches a denylist of personal tokens or absolute home paths.
grep -rinE 'jarvis|jason|woltje|\bPDA\b|/home/jwoltje|~/src/jarvis' \
  packages/mosaic/framework/ \
  --exclude-dir=.git \
  && { echo "PERSONAL DATA IN SHIPPED FRAMEWORK"; exit 1; } || exit 0
```

Wire it into the existing CI (`.woodpecker/`). This is ~10 lines and it is the *only* thing that will keep the package clean after this debate's enthusiasm fades. **A precedence model without this gate is theater.**

---

## DQ3 — Customization & upgrade safety: the real design already exists; the danger is over-engineering it

### What's actually there (and it's decent)

`install.sh` already implements the upgrade-safe mechanism the brief asks for:

- `PRESERVE_PATHS=("AGENTS.md" "SOUL.md" "USER.md" "TOOLS.md" "STANDARDS.md" "memory" ...)` (line 24) excluded from `rsync --delete` in `keep` mode (lines 118–124).
- `FRAMEWORK_VERSION=2` + `.framework-version` stamp + a real `run_migrations()` with sequential version gating (lines 160–202).
- Defaults live in `defaults/` and are *seeded* into the framework root only if absent (lines 230–241), so the user's edited copy is never clobbered.

This is a working source-vs-deployed reconciliation model **already**. The brief calls drift "a real problem today" — but the machinery to solve it is present. The actual bug is narrower: **`STANDARDS.md` is in `PRESERVE_PATHS` (user-owned) yet is also framework law.** That's the conflation, in one line. If law and customization share a file, you cannot upgrade the law without either clobbering the user (overwrite) or freezing the law forever (keep). This is *exactly* why L0 must be a separate file.

### What I'd change

1. **Constitution is NOT in `PRESERVE_PATHS`.** `CONSTITUTION.md` must be overwritten on every upgrade — that is the point of law. Add it to the *overwrite-always* set, not the preserve set.
2. **`STANDARDS.md` (L1) stays preserved but switches to an include model.** Ship `STANDARDS.md` that ends with: `# Local overrides\n<!-- mosaic:include STANDARDS.local.md -->`. The user edits `STANDARDS.local.md` (preserved, never shipped); the framework owns `STANDARDS.md` (overwritten). This gives upgrade-safe customization *without* the merge-conflict reconciliation engine someone will inevitably propose.
3. **Reject version-pinning per-file.** The brief floats "version pinning." Resist it. Per-file pins create a combinatorial matrix of (framework vN, user pinned vM) states that no one will test. One `FRAMEWORK_VERSION` integer + linear migrations (already built) is sufficient and comprehensible. Pinning is the over-engineering this lens exists to kill.

### Failure mode I want on the record

`install.sh` line 99: in non-interactive/non-TTY mode it defaults to `keep`. That means **a CI re-install silently keeps a user's stale law file.** Once L0 exists and is overwrite-always, this is fine. *Until* then, a downstream user who edited `AGENTS.md` (today's law file, which IS in `PRESERVE_PATHS`) **never receives a gate update.** That's the upgrade-drift bug, already live, today. Splitting out L0 is the fix; nothing else is.

---

## DQ4 — Cross-harness robustness: single source, dumb adapters, and stop pretending the runtimes are symmetric

### Ground truth

The adapters are tiny and mostly consistent (`adapters/claude.md`, `codex.md`, `pi.md`, `generic.md` all say "load STANDARDS.md + repo AGENTS.md"). The runtime refs (`runtime/claude/RUNTIME.md`, `runtime/codex/RUNTIME.md`) correctly say "global rules win on conflict." That spine is sound. **Do not rebuild it.**

The real cross-harness defects are concrete and small:

1. **Injection asymmetry is unmodeled.** `defaults/README.md` lines 127–135: `mosaic pi`/`claude` inject via `--append-system-prompt`; `codex`/`opencode` write to a file; direct launches use a thin pointer that the model must *choose* to read. So "the Constitution is always resident" is true for two harnesses and *aspirational* for the rest. `defaults/AGENTS.md` line 11 asserts "The core contract is ALREADY in your context (injected by `mosaic` launch). Do not re-read it." — **this is false for a direct `claude` launch**, where only the thin `~/.claude/CLAUDE.md` pointer exists. An agent that believes a false "it's already loaded" claim will skip loading the gates. That is a behavior-degrading rule.

   **Fix:** L0 must be injectable *by value*, not by reference, on every harness. The composed system prompt for ALL launchers must literally concatenate `CONSTITUTION.md`. For direct launches where injection isn't possible, the pointer must say "READ CONSTITUTION.md NOW" — never "it is already loaded."

2. **Codex memory override is a maintenance landmine.** `runtime/codex/RUNTIME.md:36` mandates durable memory to `~/.config/mosaic/memory/`, while `runtime/claude/RUNTIME.md:26–35` mandates OpenBrain and *write-blocks* `MEMORY.md` via a hook. Two harnesses, two contradictory memory truths. The Constitution should state the memory *principle* once (one cross-agent store, named) and let adapters bind the mechanism. Right now the principle lives in two runtime files saying different things.

3. **Path drift across harnesses/files.** `templates/agent/AGENTS.md.template` uses `~/.config/mosaic/rails/git/` (12 template files do); `defaults/AGENTS.md` and `guides/*` use `~/.config/mosaic/tools/git/` (20 refs). `install.sh:193` even removes a stale `rails` symlink. So half the shipped templates point at a path the installer deletes. **Any agent following the template's queue-guard command gets "no such file."** This is the single most concrete "rule that degrades real behavior" in the repo.

   **Fix:** one canonical path (`tools/git/`), enforced by the same CI grep as §2 (`grep -rn 'mosaic/rails/' packages/ && exit 1`).

### Design principle

Single source (`CONSTITUTION.md`) → composed into every launcher's system prompt by value → adapters carry ONLY the harness-specific *binding* (how to declare a subagent model, where MCP config lives), never a restatement of law. The adapters today are already close to this. The job is to keep them dumb and delete the law that has crept into guides/templates.

---

## DQ5 — Minimalism vs completeness: the core is bloated, contradictory, and partly self-defeating

This is the heart of my position.

### Evidence of bloat-induced degradation

- **Duplication breeds contradiction.** `defaults/AGENTS.md` hard gate #13 (lines 37) adds a nuanced "Merge authority (coordinated work)" exception dated 2026-06-11. `templates/agent/AGENTS.md.template` gate list (lines 6–16) does **not** contain it. So a project-scoped agent reading the template has a *different, staler* merge policy than a global agent. Two copies, two policies. With four copies, you get four.
- **The contract argues with itself about complexity.** `defaults/AGENTS.md:36` (gate #12) and `guides/E2E-DELIVERY.md:37` both contain a "COMPLEXITY TRAP" warning insisting intake is unconditional for "simple" tasks. The *existence* of a dedicated warning that agents keep skipping intake is itself evidence the contract is too heavy to internalize — agents shed it under load and the framework's response was to add *more* words telling them not to. That's a spiral. The fix for "agents skip the procedure because it's huge" is **a smaller procedure**, not a louder warning.
- **Always-resident volume.** Between `AGENTS.md` (155 lines), `STANDARDS.md` (~71), `SOUL.md` (~54), and `USER.md`, the launcher injects several hundred lines of MUST/HARD-RULE before the agent reads the task. Past a threshold, more imperatives reduce adherence to *each* imperative. The conditional-guide table (`AGENTS.md` lines 89–110) is the right instinct — push depth on-demand — but the always-resident core didn't shrink to match.

### Concrete minimalism proposal

1. **L0 Constitution: hard cap ~40 lines, gates only, no how-to.** A gate states the invariant ("Completion requires merged PR + green CI + closed issue") not the procedure (which wrapper, which flag). Procedure goes to `guides/E2E-DELIVERY.md`, loaded on implementation. The line `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge` does NOT belong in always-resident law (`AGENTS.md:30`); it belongs in the delivery guide.
2. **One law document, period.** After L0 exists, `AGENTS.md` keeps zero gates, the template keeps zero gates, the guides *reference* gates by number ("satisfies Constitution §C5") and never restate them. Single source or it rots — this repo is the proof.
3. **Kill the redundant second law file.** `STANDARDS.md`'s gate-like content (secrets HARD RULE, multi-agent safety, git discipline) is duplicated from `AGENTS.md`. Move the genuinely-standards parts to L1, delete the duplicated gates.
4. **Measure adherence, don't assume it.** The framework has no feedback loop proving the gates *work*. The hooks (`prevent-memory-write.sh`, `qa-hook-stdin.sh`, `typecheck-hook.sh` per `runtime/claude/RUNTIME.md:54–58`) are the right model: a gate enforced by a hook beats a gate written in prose ten times over. **Prefer mechanical enforcement (hooks/CI) over prose gates wherever the gate is checkable.** Each prose-only gate is a suggestion; each hook is a wall. The brief's "keep the hard gates intact" goal is best served by converting the checkable ones (no-force-merge, green-CI-before-done, no-hardcoded-secrets) into CI/hook checks, and trimming the prose.

### What completeness still requires

I'm not arguing for anarchy. The escalation triggers, block-vs-done distinction, and PR/CI/issue completion gate are load-bearing and must stay resident — they govern *when the agent stops*, which prose is the only place to encode. Keep those. Cut the procedural how-to and the duplication.

---

## Summary of concrete changes (file-level)

| # | Change | File(s) | Why |
|---|---|---|---|
| 1 | Create `CONSTITUTION.md`, gates only, ≤40 lines | new `defaults/CONSTITUTION.md` | Single source of law; separable from customization |
| 2 | Gut to a router; remove gates | `defaults/AGENTS.md` | Stop being a 5th law copy |
| 3 | Delete hard-gate block; reference Constitution | `templates/agent/AGENTS.md.template:6–16` | Kill per-project law drift (already stale re: merge-authority) |
| 4 | Delete dirty SOUL; ship generic default | `defaults/SOUL.md` (Jarvis/PDA lines 8,15,23) | Sanitize persona + accessibility leak |
| 5 | Delete jarvis-brain rule | `defaults/TOOLS.md:40` | Machine-specific path seeded to every install |
| 6 | Parameterize bootstrap template path | `guides/ORCHESTRATOR.md:99,111,152` | Guide is broken for all non-maintainer users |
| 7 | Delete or templatize the Jarvis preset | `runtime/claude/settings-overlays/jarvis-loop.json` | Pure personal contamination |
| 8 | Unify `rails/git`→`tools/git` | 12 `templates/**/*.template` files | Templates point at a path `install.sh:193` deletes |
| 9 | Fold STANDARDS into L1 + include model; drop "Master/slave" | `defaults/STANDARDS.md` | Resolve law/customization conflation + bad term |
| 10 | Add blocking CI personal-data + path-drift grep | new `tools/ci/no-personal-data.sh` + `.woodpecker/` | The only durable anti-regression control |
| 11 | Constitution = overwrite-always (not in PRESERVE_PATHS) | `install.sh:24` | Law must upgrade; today `AGENTS.md` is preserved → gate updates never reach edited installs |
| 12 | Pointer says "READ NOW", not "already loaded" | `defaults/AGENTS.md:11`, direct-launch pointers | False "already injected" claim makes agents skip gates on direct launch |

---

## The one thing I'd die on

**Subtraction before structure.** This debate will be tempted to design an elegant multi-layer Constitution with rich precedence and reconciliation. The repo's actual disease is *duplication and contradiction*, not missing layers. If we add `CONSTITUTION.md` without deleting the four existing restatements and wiring a CI grep, we will have five disagreeing law files instead of four, plus a prettier diagram. The layering is worth exactly as much as the deletions and the CI gate that accompany it — and not one line more.