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

Position Paper — Moonshot Visionary Lens

Mosaic Framework Constitution: What It Could Become

Author role: Moonshot Visionary — asks what Mosaic could become; pushes ambitious but defensible ideas for a best-in-class agent framework.

Ground truth baseline: All claims are grounded in files read under packages/mosaic/framework/ as of 2026-06-15. File paths are cited throughout.

---

Executive Summary

Mosaic's current architecture is one good design decision away from being the most rigorous open-source agent delivery framework available. The contamination problem (29 files with personal identity strings; defaults/SOUL.md hardcoding "Jarvis" and "PDA") is a symptom of a deeper structural ambiguity: the framework has never formally declared which of its three concerns — universal law, agent persona, and operator profile — owns what. Fix the ownership model decisively and the contamination, upgrade-safety, and cross-harness consistency problems all dissolve together.

The moonshot recommendation: treat the Constitution as immutable law, the SOUL as a typed contract with framework-enforced defaults, and the USER profile as a first-class citizen with schema validation at init time. Ship the three-layer model as a true alpha with mechanical upgrade-safety — not a migration guide, but a tool that enforces it.

---

DQ1 — Layering: The Constitution Must Be a Real Thing, Not a Section in AGENTS.md

What is actually there

defaults/AGENTS.md (~/.config/mosaic/AGENTS.md at deploy time) is described as the "thin core" and already does the right conceptual work: it holds hard gates, escalation triggers, mode declaration protocol, and the conditional guide loading table. But the document header says only "Mandatory behavior for all Mosaic agent runtimes" — there is no formal layer model, no precedence declaration, and no machine-readable signal that this content is framework-owned and non-overridable.

defaults/SOUL.md conflates two things that should be separate: (a) persona tokens ("Jarvis", "PDA-friendly") that are operator-customizable and (b) behavioral principles ("Clarity over performance theater", "Truthfulness over confidence") that are arguably universal law. The guardrails section of SOUL.md (defaults/SOUL.md, lines 44–52) overlaps heavily with AGENTS.md hard rules — duplication that will diverge.

defaults/STANDARDS.md exists as a third document with overlapping scope ("Non-Negotiables", load order) that is never formally placed in the layer hierarchy.

What the architecture should be

Three canonical layers with explicit precedence (highest to lowest):

Layer 0: CONSTITUTION.md   — framework-owned, immutable per release, no user overrides
Layer 1: SOUL.md           — operator-customizable persona, typed schema, framework defaults
Layer 2: USER.md           — operator profile, structured fields, generated at init time

What belongs in each layer:

Content	Layer	Rationale
Hard delivery gates (PR→merge→green CI)	0 CONSTITUTION	Violations cause real failures; no operator should weaken them
Mode declaration protocol	0 CONSTITUTION	Framework contract, not persona
Escalation triggers	0 CONSTITUTION	Safety critical; user preference irrelevant
Conditional guide loading table	0 CONSTITUTION	Structural, not stylistic
Subagent model tier rules	0 CONSTITUTION	Budget discipline is a framework concern
Superpowers enforcement rules	0 CONSTITUTION	Tool usage discipline
Block vs. Done distinction	0 CONSTITUTION	Core autonomy contract
Agent name, role description	1 SOUL	Operator persona choice
Behavioral principles	1 SOUL	Partially framework (honesty, autonomy) — see below
Communication style	1 SOUL	Operator preference
Accessibility / PDA flags	1 SOUL → USER	Operator profile concern
Operating stance (reversibility gauge)	Split: reversibility rule → L0; proactive surfacing → L1
User name, pronouns, timezone	2 USER	Identity data
Current projects table	2 USER	Operator context
Communication preferences	2 USER	Operator preference

Concrete file layout change:

framework/
  defaults/
    CONSTITUTION.md    # NEW — replaces the "law" sections of AGENTS.md
    SOUL.md            # Reduced to persona + operator-customizable principles only
    USER.md            # Unchanged structure; now formally Layer 2
    STANDARDS.md       # Demoted to advisory reference; merge non-negotiables into CONSTITUTION
    TOOLS.md           # Unchanged
  constitution/
    schema.json        # JSON Schema for SOUL.md fields (validates at mosaic init)
    LAYER-MODEL.md     # This document — the authoritative precedence spec

Precedence rule (explicit, machine-readable):

Add a mosaic.layer field to each deployed file:

# In CONSTITUTION.md front matter:
---
mosaic-layer: 0
mosaic-owner: framework
mosaic-override: forbidden
---

# In SOUL.md:
---
mosaic-layer: 1
mosaic-owner: operator
mosaic-extends: constitution
---

The launcher reads these headers and refuses to start if a layer-0 file has been structurally overridden (content-hash check against installed version). Layer-1 and layer-2 files are user-writable; the launcher merges them over framework defaults, never replaces them on upgrade.

What to do with behavioral principles that feel universal:

The SOUL principles "Truthfulness over confidence" and "Practical execution over abstract planning" are actually framework law, not persona style. Move them to CONSTITUTION.md. Leave persona-specific principles (tone, communication style, accessibility) in SOUL.md. The test: would removing this principle break delivery quality? If yes, it belongs in CONSTITUTION.

The STANDARDS.md problem:

defaults/STANDARDS.md duplicates load order, non-negotiables, and secrets rules that already exist in AGENTS.md/CONSTITUTION. It should either be merged into CONSTITUTION (for the hard rules) and removed, or explicitly demoted to a "quick reference card" with a header stating it derives from CONSTITUTION and must not be edited separately. Keeping two authoritative-sounding documents with overlapping content is how drift starts.

---

DQ2 — Sanitization: Template-Then-Init Is the Only Defensible Strategy

What is actually there

The templates/ directory already contains SOUL.md.template, USER.md.template, and agent/AGENTS.md.template with {{PLACEHOLDER}} tokens. defaults/SOUL.md hardcodes "Jarvis" and "PDA-friendly" — personal identity strings that make the public package unclean. defaults/USER.md (the deployed version) shows (not configured) placeholders, which means it was already sanitized at the defaults level, but SOUL.md was not.

The recommended approach

What ships in the public package (source of truth):

• defaults/CONSTITUTION.md — fully generic, no names, no personas, no preferences. Pure law.
• defaults/SOUL.md — a generic placeholder persona ("Mosaic Agent") that is functional but signals it should be customized. Must pass mosaic init to become useful.
• defaults/USER.md — the current sanitized version is correct; keep it.
• templates/SOUL.md.template — the template system is already half-built; complete it.

What mosaic init generates (never ships):

• ~/.config/mosaic/SOUL.md — generated from template, gitignored from the framework package.
• ~/.config/mosaic/USER.md — same.

The key insight: the current defaults/ files serve two conflicting purposes: they are both the "source" for the public package AND the "deployed" files on the operator's machine. These must be formally separated:

framework/
  defaults/          # What ships in the package — GENERIC, no PII
  generated/         # .gitignore'd — what mosaic init produces — PERSONAL

Or, simpler: the install script (install.sh) already copies defaults/ to ~/.config/mosaic/. The fix is ensuring the source files in defaults/ contain only generic content, and install.sh + mosaic init prompts the user to personalize afterward. The template system is the right foundation; it just needs to be the enforced path, not an optional one.

What about the audit file?

defaults/AUDIT-2026-02-17-framework-consistency.md should be deleted from defaults/ entirely. Framework audits are not agent context; they are maintainer artifacts and belong in docs/ or changelog/, not in the deployed config directory.

The contamination removal checklist:

Files with personal identity strings per the MISSION.md fact: 29 files. The pattern is jarvis|jason|woltje|PDA. Mechanically: grep -rli 'jarvis\|jason\|woltje\|PDA' packages/mosaic/framework/ identifies every file. Each is either (a) a defaults/ file that needs generic replacement, (b) a templates/ file that needs {{PLACEHOLDER}} tokens, or (c) a runtime/ overlay (runtime/claude/settings-overlays/jarvis-loop.json) that should be moved to an examples/ directory outside the deployed defaults.

---

DQ3 — Customization & Upgrade Safety: The Framework Must Enforce Its Own Contract

What is actually there

There is no upgrade-safety mechanism. The install script (install.sh) presumably copies defaults/ to ~/.config/mosaic/, which means a framework update overwrites operator customizations. The MISSION.md acknowledges "deployed ~/.config/mosaic has drifted ahead of source (extra SOUL guardrails) — reconciliation needed." This is the exact failure mode: manual edits to deployed files that are invisible to the source.

What must be built

The three-file-class model:

Class A: Framework-owned (CONSTITUTION.md, TOOLS.md)
  → Never overwritten by user; framework updates replace them unconditionally.
  → User MUST NOT edit these; launcher detects and warns on hash mismatch.

Class B: User-owned, framework-seeded (SOUL.md, USER.md)
  → Generated once at mosaic init from templates; owned by user forever after.
  → Framework updates NEVER touch these files.
  → New framework fields reach the user via migration notices (see below).

Class C: Framework-generated, user-invisible (runtime configs, hooks)
  → Managed entirely by mosaic install/upgrade; user edits are overwritten and warned.

The migration protocol (upgrade safety):

When the framework adds a new required field or section to a Class-B file, it cannot silently overwrite the user's file. Instead:

1. mosaic upgrade compares the installed Class-B file against the new template.
2. Diffs are shown: "New section ## Guardrails added in v1.2.0 — your file is missing it. Auto-merge? [Y/n]"
3. If auto-merge is accepted, the new section is appended (never replacing existing content).
4. If declined, the new section is written to SOUL.md.pending for the user to review.

This is not a new concept — it is exactly how Neovim's lazy.nvim handles plugin config migrations and how cargo handles edition migrations. Mosaic should adopt the same discipline.

Concrete file:

framework/
  constitution/
    MIGRATION.md       # Per-version migration notes; read by mosaic upgrade
    migrations/
      v1.0.0-v1.1.0.md  # What changed, what auto-merges, what requires manual review

Version pinning:

Each deployed ~/.config/mosaic/ directory should contain a .mosaic-version file written by mosaic install. mosaic upgrade reads this, applies only the migrations from the pinned version to the new version in sequence, and updates the pin. This solves the "drifted ahead of source" problem: the version file is the ground truth for reconciliation.

The deployed-vs-source drift problem specifically:

The MISSION.md notes that the deployed SOUL.md has "extra guardrails" not in source. With the three-class model: SOUL.md is Class B (user-owned). The extra guardrails are user additions. The migration tool will see them as user content and preserve them. The framework's new guardrail additions will be proposed as additions, not replacements. Drift becomes visible and manageable, not invisible and dangerous.

---

DQ4 — Cross-Harness Robustness: One Constitution, Thin Adapters, Verified Injection

What is actually there

The adapter files (adapters/claude.md, adapters/codex.md, adapters/generic.md, adapters/pi.md) are thin — essentially just "load STANDARDS.md + project AGENTS.md." The runtime files (runtime/claude/RUNTIME.md, runtime/codex/RUNTIME.md, runtime/pi/RUNTIME.md) are richer and contain real harness-specific behavior. But they all repeat the same phrase: "global rules win if anything here conflicts" — a statement of intent with no enforcement mechanism.

The injection model differs substantially across harnesses:

• Claude: CLAUDE.md is injected via project file + user file (~/.claude/CLAUDE.md). Full MCP support. Hooks enforced via settings.json.
• Codex: ~/.codex/instructions.md + config.toml. MCP via runtime config.
• Pi: Native --append-system-prompt, --skill, --extension. Native thinking levels replace sequential-thinking MCP.
• Generic/OpenCode: Minimal adapter; behavior undefined.

The problem: "global rules win" is a statement an LLM must reason about, not a machine-enforced constraint. An LLM in a Claude session that encounters a RUNTIME.md note saying "X" and a CONSTITUTION.md saying "not X" must reason about precedence. Under context pressure, it may get it wrong.

What must be built

Constitution as the single injection target:

Every harness adapter should inject exactly ONE file as the authoritative law: CONSTITUTION.md. The runtime file adds harness-specific mechanics (model syntax, MCP config, hooks) but never behavioral overrides of law.

Concretely, rewrite the adapters to say:

# Claude Adapter

## Injection Contract
1. CONSTITUTION.md MUST be injected before any other Mosaic file.
2. RUNTIME.md (this runtime's mechanics) is injected second.
3. SOUL.md and USER.md are injected third.
4. No runtime file may contradict CONSTITUTION.md.

## Claude-Specific Mechanics
[Claude-only content: settings.json hooks, MCP config, model tier syntax]

The compliance matrix (harness × gate):

Build and maintain a machine-readable compliance matrix at constitution/COMPLIANCE.md:

| Gate | Claude | Codex | Pi | OpenCode | Generic |
|------|--------|-------|-----|----------|---------|
| Mode declaration | hooks | instructions.md | extension | ? | manual |
| Sequential-thinking | MCP required | MCP required | native thinking OK | ? | required |
| Memory routing | prevent-memory-write.sh hook | memory override rule | extension | ? | manual |
| CI queue guard | ~/.config/mosaic/tools/git/ | same | same | same | same |

Gaps (marked ?) are known missing coverage. Ship alpha with gaps documented; fill gaps in subsequent releases. A matrix makes coverage visible; the current architecture makes it invisible.

The Pi special case:

Pi's adapter (adapters/pi.md) correctly identifies that Pi is the "native Mosaic runtime" with no permission restrictions, native thinking, and native extension hooks. This should be the reference implementation target: Pi is what Mosaic looks like when the harness cooperates fully. Claude/Codex/OpenCode are approximations of the Pi model, constrained by their harness capabilities.

Document this explicitly: "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."

Sequential-thinking across harnesses:

The current rule ("sequential-thinking MCP is REQUIRED; if unavailable, stop") is too brittle. Pi correctly identifies that native thinking levels are equivalent. The Constitution should say: "Structured multi-step reasoning is REQUIRED before planning/architecture actions. Implementations: sequential-thinking MCP (Claude/Codex), native thinking level ≥ medium (Pi), or documented equivalent." This is a behavior requirement, not a tool requirement — and it survives harness evolution.

---

DQ5 — Minimalism vs Completeness: Build a Two-Tier Injection Model

What is actually there

defaults/AGENTS.md is described as the "thin core" and instructs agents not to pre-load guides. The conditional guide loading table (AGENTS.md, lines 90–109) lists 14 guides that are loaded only when triggered by task type. This is the right instinct. But:

1. The "thin core" is not actually thin: AGENTS.md is 155 lines of dense behavioral rules, plus the loading table, plus cross-references to SOUL.md, STANDARDS.md, and guide files.
2. The guides themselves (guides/ORCHESTRATOR.md, guides/E2E-DELIVERY.md) contain content that partially duplicates the hard gates in AGENTS.md. For example, mode declaration protocol appears in AGENTS.md (lines 59–68) and again in E2E-DELIVERY.md (lines 6–11) and again in ORCHESTRATOR.md (the "MANDATORY" section before the overview).
3. There is no formal definition of what "thin core" means — no word budget, no inclusion criteria, no test for whether a rule belongs in core vs. guide.

The two-tier injection model

Tier 0: Always-resident (injected unconditionally, every session)

Target: 500 words or fewer. Enough to prevent catastrophic behavior without being read. Should fit in one context window slot.

Content criteria: A rule belongs in Tier 0 if and only if violating it in the FIRST action of a session (before any guide is loaded) would cause an irreversible failure.

CONSTITUTION.md (Tier 0 — always injected):
- Hard delivery gates (6 rules, ~80 words)
- Mode declaration protocol (3 options, ~40 words)  
- Escalation triggers (5 triggers, ~60 words)
- Block vs. Done distinction (~40 words)
- Core superpowers (sequential-thinking, OpenBrain, MCP — required tools list ~40 words)
- Subagent model tier rule (3 tiers, ~30 words)
- Session closure checklist pointer ("load E2E-DELIVERY.md") (~20 words)
Total: ~310 words

Everything else is Tier 1.

Tier 1: On-demand (conditional guide loading, exactly as today)

The existing conditional guide loading table is correct. The issue is that it is buried inside the Tier-0 document. Move the table to a new file:

constitution/GUIDE-INDEX.md   # The complete map of "task condition → guide path"

CONSTITUTION.md's Tier-0 content ends with a single pointer: "Guide index: ~/.config/mosaic/constitution/GUIDE-INDEX.md — load it when determining which guides apply to your task."

Eliminating duplication:

The mode declaration protocol is the canonical example of duplication. It appears in:

• defaults/AGENTS.md lines 59–68
• guides/E2E-DELIVERY.md lines 6–11
• guides/ORCHESTRATOR.md (early mandatory section)
• templates/agent/AGENTS.md.template lines 107–110

Rule: each behavioral rule has exactly one authoritative location. Other documents that need to reference it use a pointer, not a copy. "Mode declaration: see CONSTITUTION.md §Mode Declaration Protocol." This is the same principle that eliminates code duplication — apply it to documentation.

The duplication is not an accident: it arose because every guide author wanted the rule to be visible in their guide. The solution is not removing the rule from guides but replacing the copy with a one-line reference. A future reader can follow the pointer; the rule is maintained in exactly one place.

The "model-degrading" risk:

A 155-line AGENTS.md injected into every session consumes context budget and may degrade model performance on long conversations. The academic literature on LLM context length suggests that instructions beyond ~1000 tokens in the system prompt face diminishing compliance as the model context fills. By keeping Tier 0 under 500 words, Mosaic creates headroom for the guides that are actually relevant to the session to be loaded with full effect.

---

Synthesized Proposal: What the Alpha Should Ship

File layout

packages/mosaic/framework/
  defaults/
    CONSTITUTION.md     # NEW: Tier-0 law, ~500 words, no personal data, no persona
    SOUL.md             # Persona placeholder; generic "Mosaic Agent" persona
    USER.md             # Sanitized (already done)
    TOOLS.md            # Unchanged
    # STANDARDS.md → merged into CONSTITUTION or removed
    # AUDIT-* → deleted from defaults/
  constitution/
    LAYER-MODEL.md      # Precedence spec (Layer 0/1/2 definition)
    GUIDE-INDEX.md      # Conditional guide loading table (moved from CONSTITUTION.md)
    COMPLIANCE.md       # Harness × gate coverage matrix
    schema.json         # JSON Schema for SOUL.md and USER.md fields
    migrations/         # Per-version migration notes
  templates/
    SOUL.md.template    # Already exists; extend with all placeholder tokens
    USER.md.template    # Already exists; extend with all placeholder tokens
    # agent/, docs/, repo/ — unchanged
  guides/               # Unchanged; guide content stays, duplication replaced with pointers
  runtime/
    claude/             # Inject CONSTITUTION.md first (change CLAUDE.md + settings.json)
    codex/              # Inject CONSTITUTION.md first (change instructions.md)
    pi/                 # Inject CONSTITUTION.md via --append-system-prompt
    opencode/           # Define minimal injection contract
    mcp/                # Unchanged
  adapters/
    claude.md           # Rewrite: injection order + Claude-specific mechanics only
    codex.md            # Same pattern
    pi.md               # Same pattern; document as reference implementation
    generic.md          # Same pattern; document gaps explicitly

Precedence rule (three sentences, machine-readable)

Mosaic Layer Model:
  Layer 0 (CONSTITUTION.md): framework-owned, immutable per release. No operator override.
  Layer 1 (SOUL.md): operator-owned persona, seeded by framework, never overwritten on upgrade.
  Layer 2 (USER.md): operator profile, generated at init, never touched by framework after init.
  Conflicts resolve: Layer 0 > Layer 1 > Layer 2 > runtime-specific behavior.

What mosaic init does (alpha)

1. Copy defaults/CONSTITUTION.md → ~/.config/mosaic/CONSTITUTION.md (Class A, versioned)
2. Render templates/SOUL.md.template with user prompts → ~/.config/mosaic/SOUL.md (Class B)
3. Render templates/USER.md.template with user prompts → ~/.config/mosaic/USER.md (Class B)
4. Write .mosaic-version with current framework version
5. Never write personal data to any file that is committed to the framework source

What mosaic upgrade does (alpha)

1. Replace all Class-A files unconditionally
2. Read .mosaic-version, apply migrations in sequence for Class-B files
3. Propose additions for new required sections; never delete user content
4. Update .mosaic-version
5. Print compliance gap report from COMPLIANCE.md

---

What I Would Change vs. Current Design (with file paths)

Current	Change	Why
defaults/AGENTS.md is the "thin core"	Rename to defaults/CONSTITUTION.md; slim to ≤500 words; move guide index to constitution/GUIDE-INDEX.md	Name signals intent; word budget enforces it
defaults/SOUL.md hardcodes "Jarvis", "PDA"	Strip to generic "Mosaic Agent" placeholder; require mosaic init to personalize	Public package cannot ship personal identity
defaults/STANDARDS.md overlaps with AGENTS.md	Merge hard rules into CONSTITUTION.md; demote STANDARDS.md to advisory reference or delete	Duplication is the root cause of drift
defaults/AUDIT-2026-02-17-*.md in defaults/	Delete from defaults/; move to docs/ or changelog	Audit artifacts do not belong in agent context
runtime/claude/settings-overlays/jarvis-loop.json	Move to examples/ outside deployed defaults	Personal overlay cannot ship as framework default
No formal layer model	Add constitution/LAYER-MODEL.md with explicit precedence	Framework cannot enforce what it does not define
No upgrade-safety mechanism	Add constitution/migrations/, .mosaic-version, mosaic upgrade migration logic	Drift is the second-most-reported framework pain point
Mode declaration duplicated in 4+ files	Single authoritative location in CONSTITUTION.md; other files use one-line pointer	Each rule has one home
"Global rules win" (RUNTIME.md) is a statement	Make it structural: injection order + content-hash check on Class-A files	Enforcement beats statements
No compliance matrix	Add constitution/COMPLIANCE.md	Makes cross-harness gaps visible; drives roadmap
No word budget for Tier-0	500-word hard budget for CONSTITUTION.md	Context budget is a real constraint; discipline it

---

The Biggest Risk I See

The framework will re-contaminate itself within six months of the alpha.

Here is the failure mode: the operator (Jason) uses Mosaic daily. Mosaic's self-evolution rules (defaults/AGENTS.md lines 136–139) encourage agents to "capture recurring patterns" and propose framework improvements. Those proposals become PRs. Those PRs are authored by agents running on Jason's deployment — agents that have Jason's SOUL.md and USER.md in context. Without a structural firewall, framework-improvement PRs will leak operator-specific patterns, preferences, and terminology back into the public defaults.

The mitigation is not procedural ("remember to check for PII before merging"). It is structural:

1. A CI lint step (mosaic-lint-pii) that runs grep -rE 'jarvis|jason|woltje|PDA|your-name-here' packages/mosaic/framework/defaults/ packages/mosaic/framework/constitution/ packages/mosaic/framework/guides/ packages/mosaic/framework/adapters/ and fails the build on any match. Add it to .woodpecker.yml before the alpha ships.

2. Framework-improvement PRs must include a checklist item: "[ ] I confirm this change contains no operator-specific content."

3. The defaults/SOUL.md generic placeholder should itself say: "If you can read a specific person's name in this file, the sanitization has failed — report it as a framework bug."

Without this guardrail, the alpha will be clean, but the 1.0 release will not be.

---

Single Strongest Recommendation

Write defaults/CONSTITUTION.md — the real one — before writing any other alpha code.

Not AGENTS.md renamed. A new document, written from scratch, that:

• Is exactly 500 words or fewer
• Contains zero persona, zero personal data, zero harness-specific mechanics
• Contains the 6 hard gates, 3 mode declarations, 5 escalation triggers, Block/Done, superpowers list, model tier rule, and a pointer to the guide index
• Has front matter mosaic-layer: 0 / mosaic-owner: framework / mosaic-override: forbidden

Every other alpha task — SOUL.md sanitization, upgrade-safety mechanism, cross-harness adapter rewrites, contamination lint CI — is downstream of having a clean, authoritative layer-0 document. If CONSTITUTION.md is right, the rest is mechanical. If it is not written first, every other change will be written against the wrong abstraction.

---

Grounded in: packages/mosaic/framework/defaults/AGENTS.md, defaults/SOUL.md, defaults/STANDARDS.md, defaults/USER.md, templates/SOUL.md.template, templates/USER.md.template, templates/agent/AGENTS.md.template, guides/ORCHESTRATOR.md, guides/E2E-DELIVERY.md, runtime/claude/RUNTIME.md, runtime/codex/RUNTIME.md, runtime/pi/RUNTIME.md, adapters/claude.md, adapters/codex.md, adapters/pi.md, adapters/generic.md, docs/design/framework-constitution/BRIEF.md, docs/design/framework-constitution/MISSION.md.