mosaicstack/stack
1
0
Fork 0
Code Issues 22 Pull Requests 1 Actions Packages Projects Releases 14 Wiki Activity

docs(design): mosaic framework constitution — expert conference output
Some checks failed
ci/woodpecker/push/ci Pipeline failed
Details

Browse Source 
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:
Jason Woltje
2026-06-15 23:47:49 -05:00
parent d481a74a86
commit c70b217a5c
22 changed files with 5822 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

439
docs/design/framework-constitution/debate/position-moonshot.md Normal file
View File

@@ -0,0 +1,439 @@
# 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:
```yaml
# In CONSTITUTION.md front matter:
---
mosaic-layer: 0
mosaic-owner: framework
mosaic-override: forbidden
---
```
```yaml
# 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:
```markdown
# 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`:
```markdown
| 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`.*