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.