# Rebuttal — The Framework Architect **Lens:** Clean layering, single-source-of-truth, separation of concerns, long-term maintainability. **Author role:** Framework Architect **Responding to:** position-coder, position-contrarian, position-devex, position-aiml, position-steward, position-moonshot (and defending/extending position-architect). **One-line stance:** The six other papers converge on the *shape* I proposed — split law from persona from operator, make the seam physical, enforce it in CI. That convergence is the real signal of the conference. Where they diverge is on *how much machinery the seam needs*, and that is where the architecture is won or lost. My job here is to keep the seam **physical and boundary-checked** while killing two proposals that would re-introduce the exact coupling we are trying to remove — and to settle the one disagreement that actually determines whether this design is maintainable: **is enforcement a property of the launcher, or a property of the artifact?** --- ## 1. Strongest ideas from other personas worth keeping ### 1.1 Contrarian's "subtraction before structure" is the correct precondition for my own layering The Contrarian's central claim — *"the framework's biggest defect is not under-layering, it is over-volume and internal contradiction"* (position-contrarian §TL;DR) — is the most important corrective to my own paper, and I am adopting it as a hard precondition. I argued for **five layers**; the Contrarian and Coder argued for **four**. On reflection the Contrarian is right that *adding a fifth document called "Constitution" on top of four existing restatements yields five disagreeing law files, not one*. The architecture only pays off if the new `CONSTITUTION.md` is created **by extraction and deletion**, never by addition. I verified the contradiction he cites is live, not hypothetical: 12 template files under `templates/` still emit `~/.config/mosaic/rails/git/...` while the canonical contract uses `tools/git/...` (`defaults/AGENTS.md:30`), and `install.sh:192-194` *actively deletes* a stale `rails` symlink on migration. So the framework already knows `rails/` is dead and ships 12 templates that point an agent at a path the installer removes. That is a single-source-of-truth violation producing a runnable-command failure — exactly the class of bug my lens exists to eliminate. **Keep:** law stated once, everything else references it, CI greps for known-dead path tokens. This is non-negotiable and I will not let an elegant five-layer diagram obscure it. ### 1.2 DevEx's "ownership + mutability is the layer axis" sharpens my owner×cadence basis position-devex §DQ1 draws the layer lines by *"who owns the file and what happens to it on upgrade — not by subject matter,"* and position-aiml §DQ1 adds the *token-lifecycle* axis (residency). Both are refinements of the basis I proposed (owner × change-cadence). The synthesis is clean and I endorse it: **a layer boundary is legitimate iff the two sides differ in owner, upgrade-fate, OR residency.** That test does real work — it is precisely why `defaults/AGENTS.md:37`'s "(Policy: Jason, 2026-06-11.)" merge-authority clause cannot live in the constitution: it has a different owner (operator) and a different upgrade-fate (preserved, not clobbered) than the gate mechanism around it. Three independent papers reach the same seam from three different axes; that is the convergence worth banking. ### 1.3 Steward's license + credentials findings are the genuinely new, blocking facts position-steward is the only paper that surfaces two issues outside the DQ frame that are nonetheless **release blockers** and that my own paper missed: (1) there is no `LICENSE` file anywhere — *"Public does not mean licensed"* (§Cross-Cutting) — so the package is legally all-rights-reserved; and (2) `tools/_lib/credentials.sh:19` hardcodes `$HOME/src/jarvis-brain/credentials.json` as a credential default. From a maintainability lens these are layer-5 (deployment) contamination of the worst kind: a *security-relevant default* baked into shared tooling. **Keep:** both go in the alpha definition-of-done, and the credentials default becomes `${MOSAIC_CREDENTIALS_FILE:?...}` (fast-fail), consistent with the existing `STANDARDS.md:35` ban on `${VAR:-default}` for required values. The framework already has this rule for downstream apps; it is violating it in its own tooling. --- ## 2. Weakest / riskiest proposals — concrete failure modes ### 2.1 Moonshot's YAML front-matter + content-hash "launcher refuses to start" is layer inversion position-moonshot §DQ1 proposes putting `mosaic-layer: 0 / mosaic-owner: framework / mosaic-override: forbidden` front-matter in each deployed file, and having *"the launcher read these headers and refuse to start if a layer-0 file has been structurally overridden (content-hash check)."* position-steward §DQ3 proposes the same mechanism by another name: `mosaic doctor --check-constitution` comparing SHA-256 against a shipped `.checksums` file. This is architecturally backwards and I will die on this hill. **It makes the layer model a property of runtime metadata and a hashing tool, when the entire point of the re-architecture is to make the layer model a property of *directory structure*.** Failure modes: 1. **It re-couples what we just decoupled.** If "this file is immutable law" is encoded in YAML front-matter *inside the file*, then the immutability claim and the content it governs share a file — the same co-mingling (`defaults/SOUL.md` mixing persona + law + accommodation) we are eliminating. A user (or an agent) who edits the body can edit the header. The guarantee is self-referential. 2. **The checksum manifest is a fourth source of truth that will drift.** `.checksums` / `schema.json` / front-matter `mosaic-layer` all encode "what is framework-owned." So does the directory split. So does `install.sh`'s preserve/overwrite logic. That is four encodings of one fact. position-aiml §physics-#3 names exactly why this fails: *contradiction is silently lossy*. The first time a maintainer adds a constitution file and forgets to regenerate the checksum, `mosaic doctor` either false-positives (blocks every start) or the check is disabled — and a disabled integrity check is worse than none. 3. **"Launcher refuses to start" is a denial-of-service against the operator's own work.** A content-hash mismatch can be a benign line-ending normalization, an `rsync` mtime quirk, or a legitimate hotfix the user applied while waiting for an upstream PR. Hard-failing the launcher on byte-inequality turns a maintainability nicety into an availability outage. **The architecturally correct version is what I already proposed and the directory split gives for free:** framework-owned content lives under `~/.config/mosaic/constitution/` and is **`rsync --delete`'d wholesale on every upgrade** (position-coder §DQ3 `FRAMEWORK_DIRS`, position-architect §DQ3). The user *cannot* persist an edit to a clobbered directory across upgrade — that is the enforcement, and it requires zero hashes, zero front-matter, zero launcher gate. Immutability is enforced by *the file being overwritten*, not by *a tool checking whether it was*. Drift-detection-by-checksum is solving a problem that overwrite-by-directory deletes. If you want a doctor check, check *structure* ("is there a stray flat `AGENTS.md` shadowing `constitution/`?"), not *content bytes*. ### 2.2 Moonshot/DevEx's `.local.md` + 3-way-merge reconciliation engine is over-engineering the wrong layer position-moonshot §DQ3 and position-devex §DQ3 both propose a per-file template-version marker plus a **3-way merge** (base = old template, theirs = user file, ours = new template) that surfaces `SOUL.md.mosaic-merge` conflicts "exactly like git," plus copy-vs-symlink policy inversion in `mosaic-link-runtime-assets`. position-coder §DQ3 proposes the lighter `E2E-DELIVERY.local.md` overlay variant. The instinct (don't make users edit framework files) is right and is the same one I argued. But a 3-way-merge engine over Markdown prose is a maintainability liability that fails its own goal: 1. **Markdown has no merge semantics.** `git merge-file` resolves by *line*, not by *meaning*. A reflowed paragraph in the new template (one logical edit) produces a wall of phantom conflicts against a user's reflowed copy. The user is now hand-resolving `<<<<<<<` markers in their persona file on every upgrade — the precise "clobbered on upgrade" pain the BRIEF set out to kill, re-introduced as "conflict-resolution toil on upgrade." 2. **It is aimed at the layer that least needs it.** SOUL/USER are *small, user-owned, rarely re-templated*. The thing that genuinely evolves is the *framework* law (layer 1–2), and that is solved by overwrite, not merge. Building a merge engine for the stable layer while the volatile layer needs none is effort spent against the gradient. 3. **The simpler, strictly-better primitive already exists in this very ecosystem.** Additive override files — `policy/standards-overrides.md` (my §DQ3), Contrarian's ``, AIML's `.local.md` loaded-last-within-layer — give upgrade-safe customization with **zero merge conflicts**, because the framework file is never edited and the user delta is a separate, append-only file the composer concatenates. This is the config-layering pattern (base + drop-in) that `settings.json` / `settings.local.json` already use (`runtime/claude/RUNTIME.md:47`). Adopt the drop-in; reject the merge engine. **Verdict:** keep template-versioning *as a doctor signal* ("your SOUL was generated from template v2; v4 ships — review `examples/` for new sections"), but the resolution mechanism is an **additive overlay**, not a 3-way merge. Reserve any merge at all for the single genuinely-hand-tuned generated file (`TOOLS.md`), and even there surface conflicts in `doctor` rather than auto-resolving. ### 2.3 Moonshot's "Pi is the reference harness" inverts the single-source-of-truth dependency position-moonshot §DQ4: *"Pi is the Mosaic reference harness. When designing a new Constitution gate, first define it as a Pi extension behavior, then define the equivalent approximation for other harnesses."* position-devex's capability-manifest idea is the better-engineered cousin of this, and I keep that — but the "Pi-first" framing is a layering error. If the constitution is the single source of truth (every paper agrees it must be), then gates must be authored as **harness-agnostic capability requirements**, and *each* adapter — Pi included — resolves them to mechanism. Making one harness the reference means the abstract law is defined in terms of one concrete implementation's affordances; the day Pi's extension model changes, the *constitution* needs editing. That is the tail wagging the dog. position-devex §DQ4 already states the correct rule: the constitution speaks in **capability verbs** ("use structured reasoning for multi-step planning"), and `adapters/.capabilities.json` binds the verb to `mcp:sequential-thinking` (gate: true) on Claude or `native-thinking` (gate: false) on Pi. **Keep the capability manifest; drop the "Pi is canonical" framing.** No harness is canonical; the *capability vocabulary* is canonical, and it lives in layer 1, owned by no runtime. --- ## 3. The key disagreement, sharpened — and how to resolve it Strip away the agreements and exactly one fault line determines whether this architecture is maintainable long-term: > **Is the constitution enforced because the launcher injects it, or because the artifact is > self-bootstrapping and the directory layout makes it un-clobberable?** The two camps: - **Launcher-trust camp** (implicit in position-moonshot, parts of position-steward §DQ4): the launcher injects `CONSTITUTION.md` as system-prompt text, and we add metadata/hash checks so the launcher can *refuse to run* if law was tampered with. Enforcement is an active runtime behavior. - **Artifact-trust camp** (position-coder §"Single Strongest Recommendation", position-devex §"Biggest risk", position-aiml §DQ4): on 3 of 4 harnesses the "constitution" arrives only as a *user-editable pointer file that says "go read this,"* which a busy model can skip and a user can edit away (`defaults/AGENTS.md:11` even asserts the contract is *"ALREADY in your context... Do not re-read it"* — which position-devex §0 and position-contrarian §DQ4 both show is **false for a direct `claude` launch**). So the law must be (a) a file the agent is *unconditionally told to read*, and (b) backed by a *mechanical hook* where the harness has one (`runtime/claude/RUNTIME.md:30-32`: *"the rule alone proved insufficient — the hook is the hard gate"*). **My resolution — and I think it is the load-bearing decision of the whole conference:** enforcement is a property of the **artifact and the directory**, not the launcher. Three rules, in priority order: 1. **Immutability via directory, not metadata.** Framework law lives in `constitution/`, `rsync --delete`'d every upgrade. There is nothing to tamper-check because tampering does not survive an upgrade and the upgrade is the enforcement. This deletes the entire front-matter/checksum/launcher-refusal apparatus from §2.1. 2. **Residency via self-bootstrapping read, not launcher trust.** The thin `AGENTS.md` must say *"if `constitution/CONSTITUTION.md` is not already in context, READ IT NOW"* — never "it is already loaded" (fix `defaults/AGENTS.md:11`). This makes the law harness-agnostic by construction (position-coder's single strongest rec) and removes the dependency on every launcher getting injection order right. The launcher injecting by value is an *optimization* on strong harnesses, not the *guarantee*. 3. **Hard gates that are checkable become hooks/CI, not prose.** position-contrarian §DQ5, position-devex §DQ4, and position-aiml §DQ4 all converge here and they are right: no-force-merge, green-CI-before-done, no-hardcoded-secrets, no-PII-in-shipped-files, and no-dead-path-tokens are all mechanically checkable. Each becomes a hook (PreToolUse) or a CI grep. Prose law is the *spec*; the hook/CI is the *enforcement*. This is the only thing that kept memory-write discipline honest (the hook, not the rule), and it is the only thing that will keep the 29-file contamination from re-accreting. Why this resolution and not launcher-trust: **launcher-trust adds runtime machinery (metadata, hashes, refusal logic) to compensate for a structural weakness; artifact-trust removes the structural weakness so no machinery is needed.** A maintainable framework prefers the design where the invariant holds *because of how the files are laid out*, not *because a tool remembered to check*. Every checksum manifest is a liability that drifts; every directory that is unconditionally overwritten is a guarantee that cannot. **Concrete reconciliation for the alpha (what I'd put to a vote):** - Adopt **four ownership layers** (Constitution / Persona / Operator / Project), defined by the owner×upgrade-fate×residency test (§1.2), with a typed two-axis precedence: *safety → framework supreme; taste → user supreme* (position-contrarian §DQ1). Drop my fifth layer into a `policy/` *directory* under operator, not a new top-level layer. - **Physical seam:** `constitution/` (clobbered) vs root user files (preserved). No `PRESERVE_PATHS` entry for any framework file. This is the whole upgrade-safety story. - **Customization = additive overlays** (`policy/*.md`, `*.local.md` loaded-last-within-layer), **not** 3-way merge. - **Enforcement = self-bootstrapping read + hooks/CI**, **not** front-matter/checksum/launcher refusal. - **CI gates in the alpha DoD:** `verify-sanitized.sh` (no PII/home-paths/dead `rails/` tokens outside `examples/`), `verify-no-duplicate-gates.sh` (one normative MUST per file), `verify-constitution-budget.sh` (resident line ceiling — position-aiml/coder/devex all demand this), and a LICENSE/credentials-default check (position-steward). If we get the directory seam and the CI gates, *every other proposal in these seven papers is either mechanical or optional polish*. If we get a beautiful five-layer precedence diagram without them, we ship the 29-file contamination with prettier filenames. --- ## Top contentions (summary) 1. **Agree with the convergence, on one condition:** introduce the Constitution layer **by extraction and deletion, never addition** — verified live drift (12 templates emit dead `rails/git/` paths the installer deletes at `install.sh:193`) proves a fifth restatement yields five disagreeing law files, not one. 2. **Reject metadata/checksum/launcher-refusal enforcement** (moonshot front-matter, steward `--check-constitution`): it re-couples the immutability claim to the file it governs and adds a 4th drifting source of truth. **Enforce immutability by `rsync --delete` of `constitution/`** — overwrite *is* the guarantee; nothing to tamper-check. 3. **Reject the 3-way-merge reconciliation engine** (devex/moonshot): Markdown has no merge semantics, so it re-creates upgrade-time toil on the *stable* layer. **Use additive overlays** (`policy/*.md`, `*.local.md`) — zero conflicts, framework file never edited. 4. **Reject "Pi is the reference harness"** (moonshot): it defines abstract law in terms of one runtime's affordances. **Keep devex's capability-manifest** — the constitution speaks capability verbs; each adapter binds them; no harness is canonical. 5. **Resolve the core fault line toward artifact-trust:** the law is enforced because it is **self-bootstrapped (`AGENTS.md` says "READ IT NOW", never "already loaded" — fix `AGENTS.md:11`) and un-clobberable by directory**, plus **hooks/CI for every checkable gate** — not because the launcher injects it and a tool checks a hash. 6. **Keep, and put in the alpha DoD:** the four CI gates (sanitization, no-duplicate-gates, resident-budget) plus steward's two new blockers (**MIT LICENSE**, **credentials default → `${VAR:?}` fast-fail**) — the only durable controls against regression.