stack/docs/design/framework-constitution/ALPHA-DOD.md

Constitution Alpha — Definition-of-Done checklist + release notes

Drafted for the v0.0.39-alpha tag (Lead cuts after P5 #605 → P6 #607 → aiguide #8 merge). Maps every DoD §8 acceptance criterion to its merged evidence. Legend: ✅ merged on main · ⏳ review-ready PR (pending merge) · 🔲 Lead action.

DoD §8 green-checklist

#	Acceptance criterion (DESIGN §8)	Status	Evidence / PR
1	MIT LICENSE (root + framework) + "license":"MIT" in package.json	✅	P0 #570
2	Three credential-path sites + hook URL fast-failed (no private paths in *.sh/hooks)	✅	P0 #570
3	verify-sanitized.sh (two-class, *.sh+*.md, self-tested) wired blocking in CI	✅	P1 #572
4	Operator data purged from the full set (guides / tools / init-generator)	✅	P2 #572
5	rails/→tools/ in both template families	✅	P2 #572
6	jarvis-loop.json deleted; defaults/SOUL.md → neutral sanitized persona (Q10 decision)	✅	P2 #572
7	CONSTITUTION.md extracted (gates one place, capability-verb, §1.4 split, no false "already loaded")	✅	P3 #575 / #577
8	AGENTS.md/STANDARDS.md out of PRESERVE_PATHS + seed-semantics → overwrite in both installers	✅	P4 #590
9	Snapshot + v2→v3 migration moving user edits to .local/.bak; FRAMEWORK_VERSION=3	✅	P4 #590 / #593
10	mosaic-init --non-interactive fail-closed persona	✅	P4 #590
11	5-fixture migration matrix green against both installers asserting injected bytes	✅	P4 #590 / #593
12	compose-contract built + composer unit test (per-tier anchor + Tier-3 byte-equality)	⏳	P5 #605
13	Resident line-count ceiling enforced (framework-owned resident files)	⏳	P6 #607
14	CONTRIBUTING.md + harness×gate compliance matrix	⏳	P6 #607
15	aiguide reconciled with the Constitution	⏳	aiguide #8
16	Each phase PR CI-green; alpha tag pushed + Gitea release published	🔲	Lead (post-merge)

Note on #6: the DoD's literal "delete defaults/SOUL.md" was superseded by the resolved Q10 decision — ship a neutral, operator-agnostic example persona instead of deleting it. Main carries the sanitized 2.6 KB neutral SOUL.md ("Mosaic agent", no operator identity); the sanitization gate confirms it is PII-clean. Criterion met in spirit (no operator persona leaks) via the better option.

Gate to flip 12–14 → ✅: merge P5 #605 → P6 #607 (rebase auto-drops the dup format fix adc7df2/9f6da92) → aiguide #8, with ci.yml terminal-green on the merged head.

---

Release notes — v0.0.39-alpha (Mosaic Framework Constitution, alpha)

Mosaic Framework Constitution — Alpha

This release makes the Mosaic framework a safe-to-open-source, fork-and-customize agent operating layer. It separates the non-negotiable law from operator identity, makes customization survive upgrades, and wires the guarantees into CI.

Highlights

• Constitution (L0). The hard gates now live in one place — CONSTITUTION.md — authored in capability verbs, with a thin AGENTS.md dispatcher that references the law instead of restating it. Governance model in constitution/LAYER-MODEL.md.
• Public & sanitized. MIT-licensed; all operator identity, private paths, and credential sites removed from shipped files. A self-tested verify-sanitized.sh gate (two rule classes) runs blocking in CI so re-contamination can't merge.
• Upgrade-safe customization. Framework-owned files overwrite cleanly on upgrade while SOUL.md/USER.md/*.local.md/credentials are preserved. The v2→v3 migration snapshots first and moves any user-edited AGENTS.md/STANDARDS.md to .pre-constitution.bak/.local.md — never silently lost. Verified by a 5-fixture matrix across both installers.
• Operator overlays. mosaic compose-contract <harness> merges your *.local.md deltas into the contract per harness, so customization reaches the model as one pre-merged blob.
• Cross-harness. Single L0 source referenced (never restated) by Claude / Codex / OpenCode / Pi; tiered injection with a byte-equal Tier-3 fallback read.
• Guardrails in CI. Resident line-count ceiling over framework-owned resident files; composer unit test; sanitization gate — all blocking.
• Docs. CONTRIBUTING.md with the layer model, dual-installer parity rule, and a harness×gate compliance matrix (the Codex/OpenCode/Pi hook-parity gap is tracked for v2).

Known limitations (accepted, documented in CONTRIBUTING.md §9)

• Bare launches that bypass mosaic get base contracts only (no *.local overlays) and are not drift-checked by mosaic doctor — mitigated by the unconditional Tier-3 self-load + a nudge.
• Codex/OpenCode/Pi mechanical hook parity, policy/*.md composition, and live-launch cross-harness verification are v2.

Phase lineage: P0 #570 · P1+P2 #572 · P3 #575/#577 · P4 #590/#593 · P5 #605 · P6 #607 · aiguide #8 (umbrella #542).