docs(design): mosaic framework constitution — expert conference output
Some checks failed
ci/woodpecker/push/ci Pipeline failed
Some checks failed
ci/woodpecker/push/ci Pipeline failed
Conference of 7 experts (architect/moonshot/contrarian/coder/aiml/devex/steward) debated layering, sanitization, upgrade-safety, cross-harness robustness. Artifacts: BRIEF, 7 positions, 7 rebuttals, synthesis-v1, 3 red-team passes, canonical DESIGN.md, OPEN-QUESTIONS.md, MISSION.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
269
docs/design/framework-constitution/debate/rebuttal-moonshot.md
Normal file
269
docs/design/framework-constitution/debate/rebuttal-moonshot.md
Normal file
@@ -0,0 +1,269 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user