stack/docs/design/framework-constitution/debate/rebuttal-moonshot.md

# Rebuttal — Moonshot Visionary Lens

**Responding to:** position-aiml.md, position-architect.md, position-coder.md,
position-contrarian.md, position-devex.md, position-steward.md

**Ground truth files read:** `defaults/AGENTS.md` (155 lines), `defaults/SOUL.md` (53 lines),
`defaults/STANDARDS.md`, `templates/SOUL.md.template`, `templates/agent/AGENTS.md.template`
(stale `rails/git` paths at lines 5, 12–13), `runtime/claude/RUNTIME.md`,
`runtime/pi/RUNTIME.md`, `adapters/claude.md`, `guides/E2E-DELIVERY.md`,
`guides/ORCHESTRATOR.md`, `install.sh` (PRESERVE_PATHS line 24, FRAMEWORK_VERSION=2 line 28).

---

## Part 1 — The 2–3 Strongest Ideas Worth Keeping

### 1. The AI/ML lens's resident-token budget with mechanical enforcement (position-aiml.md)

This is the most technically grounded contribution in the debate. The AI/ML persona observes
that `defaults/AGENTS.md` already carries at least four parallel "these are the critical ones"
framings — `CRITICAL HARD GATES`, `Non-Negotiable Operating Rules`, `Other Hard Rules`, and
per-section `(Hard Rule)` tags — in 155 lines of always-resident law. It then proposes a hard
line-count cap enforced in `mosaic-doctor` and CI.

I endorse this without reservation. The cap is not cosmetic. Salience inflation is real: when
every rule is labeled CRITICAL, none is. The CI assertion is the load-bearing control because
every enforcement mechanism proposed in this debate — Constitution, layers, precedence rules — is
only as good as the text that reaches the model per-token. A Constitution that grows back to 155
lines within two releases achieves nothing. The budget gate keeps it honest. Ship it with the
same alpha as the Constitution, or the Constitution is cosmetic governance.

Concrete file consequence: add to `tools/ci/` (or extend the existing
`tools/quality/scripts/verify.sh` hook point) a line-count assertion that fails CI if
`CONSTITUTION.md` exceeds a fixed ceiling. The AI/ML paper suggests ~40 lines; my position paper
suggested 500 words. Either is defensible; the specific number matters less than the mechanism
that prevents erosion.

### 2. The Contrarian's "subtraction before structure" and live path-drift evidence (position-contrarian.md)

The Contrarian documents the `rails/git/` vs `tools/git/` split between
`templates/agent/AGENTS.md.template` lines 12–13 and `defaults/AGENTS.md` line 30 — not as a
hypothetical risk, but as a live stale-path bug that `install.sh:193` actively works around
(removes a stale `rails` symlink). Any agent following the template's queue-guard line gets
"no such file." That is a real breakage for downstream users today.

This single observation sharpens the entire DQ5 argument: duplication is not merely inelegant,
it already produces operational failures. The Contrarian's minimalism principle — "earn the
Constitution by deleting the four existing restatements, not by adding a fifth document" — is the
correct framing of what "success" looks like for this re-architecture. If we ship
`CONSTITUTION.md` and leave the law restated in `templates/agent/AGENTS.md.template` lines 6–16,
`guides/E2E-DELIVERY.md` lines 6–11, and `guides/ORCHESTRATOR.md` lines 9–22, we have five
disagreeing law files instead of four. The win is subtraction.

Concrete file consequence: the project template gate-block (`templates/agent/AGENTS.md.template`
lines 6–16, using the already-stale `rails/git` path) must be replaced with one line:
*"This project is governed by `~/.config/mosaic/CONSTITUTION.md`. Add only project-specific
extensions below."* That line cannot drift from itself.

### 3. The DevEx lens's "hooks are the real enforcement" elevation to doctrine (position-devex.md)

The DevEx paper makes a critical observation: `runtime/claude/RUNTIME.md` line 30–32 already
states explicitly that the memory-write rule "*alone proved insufficient — the hook is the hard
gate.*" That is the single most important lesson the existing framework has learned, and it is
buried in one runtime file rather than being promoted to Constitution doctrine.

The DevEx paper proposes: *"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."* This is the right
principle and it is already partially true for Claude (the `prevent-memory-write.sh` PreToolUse
hook, `qa-hook-stdin.sh`, `typecheck-hook.sh`). The gap is that the principle lives in a runtime
note, not in the Constitution, and Codex/OpenCode hook parity is untracked.

Elevating "hooks are primary enforcement; prose is the spec" to a Constitution-level statement
does something valuable beyond Claude sessions: it creates a tracked gap for every other harness,
making the enforcement asymmetry visible and actionable rather than invisible and assumed-away.

---

## Part 2 — The 2–3 Weakest or Riskiest Proposals

### 1. The DevEx 3-way merge for user files is engineering complexity that inverts the risk (position-devex.md)

The DevEx paper proposes adding `tools/_scripts/mosaic-reconcile` that does git-style 3-way
merges of `SOUL.md` and `USER.md` when the upstream template version advances. The motivation is
real: users should receive framework template improvements without losing their customizations.
But the failure mode of this mechanism is worse than the problem it solves.

Concrete failure mode: `SOUL.md` is a freeform Markdown document, not a structured data file. A
3-way merge of Markdown prose will produce conflict markers inside the agent's identity file. An
agent running with `SOUL.md.mosaic-merge` active — or worse, with an auto-merged file that
contains a semantically incoherent blend — has corrupted law. The DevEx paper acknowledges that
the merge surfaces as `SOUL.md.mosaic-merge` "for the user to resolve, exactly like git" — but
that comparison reveals the flaw: `git merge-file` on prose produces line-level conflicts that
humans resolve in an editor. An automated merge of freeform behavioral principles can produce
a document that is syntactically clean and semantically broken, with no conflict markers to alert
the user.

The simpler mechanism already proposed in the AI/ML paper — `*.local.md` overlay files that are
structurally additive, never merged — achieves 80% of the goal without the failure mode. A user
extends `SOUL.md` by writing `SOUL.local.md`; the framework never touches their base `SOUL.md`
after init; the framework template evolves without merging. The user misses framework SOUL
template updates, but SOUL updates should be rare and can be communicated via release notes. The
Contrarian's point applies: resist the complexity. The merge engine is over-engineering for an
upgrade safety mechanism that will interact with an LLM's identity file in ways we cannot fully
test.

### 2. The Architect's per-directory physical separation (`constitution/` subdirectory at deploy target) underestimates migration catastrophe (position-architect.md)

The Architect proposes restructuring the deploy target so that `~/.config/mosaic/constitution/`
holds framework law (always overwritten) while user files remain at root. The Architect's own
"biggest risk" section acknowledges the danger: *"the re-architecture's correctness depends
entirely on a migration that can tell 'framework file the user happened to edit' from 'user
file,' which is exactly the distinction the current flat model cannot make."*

But the paper understates how bad this gets. Consider the install path:

1. User has a live deployment with `~/.config/mosaic/AGENTS.md` in `PRESERVE_PATHS` (line 24 of
   `install.sh`).
2. User has edited `AGENTS.md` — specifically added custom guide-loading triggers.
3. The v2→v3 migration reclassifies `AGENTS.md` as framework-owned, clobbers it, moves content
   into `constitution/`.
4. The user's custom guide-loading triggers are gone. The migration "detected a user-edited
   AGENTS.md" and "extracted their non-framework additions into `AGENTS.local.md`" — but the
   heuristic for "non-framework additions" in a mixed document is not defined in the paper.

The Coder paper's migration approach is safer precisely because it avoids reclassification: it
keeps `AGENTS.md` at root as a thin pointer, seeds `constitution/CORE.md` as a *new* file that
nothing previously owned, and makes the agent self-load the Constitution from within `AGENTS.md`
rather than relying on launcher injection order. The physical directory move is not necessary for
the architecture to work — the ownership signal can be the filename convention
(`CONSTITUTION.md` = never edit, `SOUL.md` = yours) without restructuring the deploy layout.

The moonshot position: a physical `constitution/` subdirectory is a nice structural statement but
not required for alpha correctness, and it carries real migration risk for the existing installed
base. Reserve it for v2 once the alpha has proven the ownership model works in the flat layout.

### 3. The Steward's "rename `defaults/` to `constitution/`" conflates source and deploy semantics (position-steward.md)

The Steward proposes: *"rename `defaults/` to `constitution/` to make the semantics clear and
prevent future drift."* The instinct is right — the word "defaults" is confusing because it
conflates (a) the package source directory and (b) the deployed files that seed
`~/.config/mosaic/`. But renaming the source directory to `constitution/` creates a different
confusion: it implies that `defaults/SOUL.md` (which ships and deploys but is then user-owned)
is part of the Constitution, which it is not.

The correct fix is to be explicit about the dual role of `defaults/`: it is the *seeding source*
for the install, and individual files within it have different ownership classes after deployment.
Renaming to `constitution/` papers over the seeding role and will mislead future contributors
into thinking everything in the directory is framework law. The Moonshot position is: name the
ownership classes explicitly via file metadata (front matter `mosaic-layer: 0/1/2` as proposed
in the original Moonshot paper), not via directory structure. Directory names cannot encode
per-file ownership classes. Metadata can.

---

## Part 3 — The Key Disagreement and How to Resolve It

### The disagreement: is the Constitution a *document* or a *layer* — and which should be specified first?

Every position paper agrees on: create `CONSTITUTION.md`, sanitize `SOUL.md`, add a CI PII
grep, and remove `CONSTITUTION.md` from `PRESERVE_PATHS`. This is consensus.

The substantive disagreement is architectural: **should the Constitution be designed as a
document (the Contrarian, Coder) or as a layer in a formally-specified model (Moonshot,
Architect, DevEx)?**

The Contrarian says: ship a ~40-line document with the hard gates, delete the duplicates, wire
the CI grep. Done. Adding a layer model is over-engineering.

The Moonshot and Architect say: the document is the output of the layer model; design the model
first or the document will not be positioned correctly to evolve cleanly.

The Coder says: the document should be self-loading (agents are instructed to read it from
`AGENTS.md`) rather than injection-dependent, and that mechanical self-loading is more reliable
than any launcher injection order.

**The resolution: specify the layer model as a document, not as a build mechanism.**

The three positions are not actually in conflict. The Contrarian is right that the immediate
alpha deliverable is a document, not a build mechanism. The Moonshot/Architect are right that
without a stated layer model, the document will not be governed correctly going forward — the
"operator policy MAY delegate merge authority" example (`defaults/AGENTS.md:37`, attributed to
"Policy: Jason, 2026-06-11") shows what happens when operator policy and universal law occupy
the same document with no governance model: an operator policy decision sits inside hard gate
#13 of the universal contract, attributed to a specific person on a specific date, shipped to
every downstream user. That is not fixable by "just write a cleaner document" — it requires a
governance model that defines what is allowed inside `CONSTITUTION.md` and what must go
elsewhere (operator `policy/` files, per the Architect).

The Coder's self-loading mechanism resolves the cross-harness injection debate: instead of
fighting over whether `mosaic claude` composes the Constitution into `--append-system-prompt`
(currently not guaranteed — `adapters/claude.md` only references `STANDARDS.md` and repo
`AGENTS.md`, not a Constitution), make `AGENTS.md` unconditionally instruct the agent to read
`CONSTITUTION.md` at session start. This is the defensive fallback that survives any launcher
composition failure.

**Concrete resolution path:**

1. Write `defaults/CONSTITUTION.md` — exactly as the Moonshot paper specifies (≤500 words;
   6 hard gates, 3 mode declarations, 5 escalation triggers, Block/Done, superpowers list, model
   tier rule, guide index pointer). No operator policy, no persona, no harness mechanics. This is
   the alpha deliverable the Contrarian is asking for and the Moonshot is asking for — they agree
   on the document; they disagree only on whether to name the model that governs it.

2. Add to `defaults/AGENTS.md` (line 11 replacement): *"At session start, read
   `~/.config/mosaic/CONSTITUTION.md` — this is the immutable law. Do not re-read it on
   subsequent turns."* This removes the false "already in context" claim
   (`defaults/AGENTS.md:11`) that the Contrarian correctly flags as broken for direct launches,
   and makes Constitution loading harness-agnostic.

3. Write `constitution/LAYER-MODEL.md` — a single-page specification of the three ownership
   classes (L0 framework/immutable, L1 operator/persona/preserved, L2 operator/profile/preserved)
   and the precedence rule. This document does not ship to `~/.config/mosaic/`; it lives in the
   framework source as the governance spec that contributors and future PRs are measured against.
   The Contrarian has no objection to a governance document in `docs/` — only to it becoming a
   fourth always-resident law file. A spec in `constitution/` (source only, never deployed) is
   not a resident file.

4. Add the CI PII grep (`tools/ci/no-personal-data.sh`) over `defaults/`, `guides/`,
   `templates/`, `runtime/`, `adapters/`. Wire to `.woodpecker/`. This closes the re-contamination
   loop that the Moonshot paper identifies as the "biggest risk" — agents running on a
   personalized deployment proposing framework PRs that leak operator content. The grep is the
   only control that survives the operator's future self.

5. Remove `AGENTS.md` and `STANDARDS.md` from `PRESERVE_PATHS` in `install.sh:24`. Both are
   framework-owned; both silently freeze gate updates on the first user edit. `CONSTITUTION.md`
   replaces them as the always-overwritten law; `AGENTS.md` becomes a thin, stable pointer that
   rarely changes and does not need to be user-editable.

6. Extract the operator policy from hard gate #13 (`defaults/AGENTS.md:37`, "Policy: Jason,
   2026-06-11") into `examples/policy/merge-authority.example.md` and replace the gate text
   with the mechanism only: *"When a coordinator/orchestrator is active, the merge go-ahead
   is the coordinator's to give. Absent an operator policy stating otherwise, no-unreviewed
   self-merge is the default."* This is the clearest single example of what belongs in the
   Constitution (the mechanism/rule) vs. what belongs in operator policy (who has authority in
   a specific deployment).

---

## Summary: Top Contentions

1. **The CI resident-budget cap is not optional.** Ship it with the Constitution or the
   Constitution will grow back to 155 lines inside two releases and become the new problem.
   The AI/ML paper's mechanical line-count assertion in `mosaic-doctor`/CI is the load-bearing
   control for everything else.

2. **Subtraction is the Constitution's deliverable, not addition.** Creating `CONSTITUTION.md`
   without deleting the law from `templates/agent/AGENTS.md.template` lines 6–16,
   `guides/E2E-DELIVERY.md` lines 6–11, and `guides/ORCHESTRATOR.md` lines 9–22 produces five
   disagreeing law files. The live `rails/git` path bug proves this is not hypothetical.
   Every gate must have exactly one authoritative location.

3. **Operator policy has leaked into universal law and must be extracted.** Hard gate #13
   (`defaults/AGENTS.md:37`, "Policy: Jason, 2026-06-11") is the proof case. The Constitution
   layer model is justified not by elegance but by this specific failure: without a formal
   distinction between universal law and operator policy, a coordinator merge-authority decision
   made by one person on one date ships as non-negotiable global law to every downstream user.
   The fix is a `policy/` operator layer (per the Architect) with a Constitution that states
   only the mechanism, not the policy choice.

4. **3-way merge of freeform behavioral documents is riskier than the upgrade problem it solves.**
   The DevEx paper's `mosaic-reconcile` 3-way merge for `SOUL.md`/`USER.md` will produce
   semantically broken identity files without surfacing conflict markers. The `*.local.md` overlay
   pattern (AI/ML paper) achieves upgrade safety without automated merge of prose.

5. **The layer model belongs in `constitution/LAYER-MODEL.md` (source-only, never deployed)
   — not as another resident file.** The Contrarian's objection to adding governance documents
   is valid only if those documents become resident context. A spec file that governs what can
   be in `CONSTITUTION.md` is a contributor resource, not agent context. The Contrarian and
   Moonshot positions converge when the layer model is specified in the source tree rather than
   injected into every session.