From e0a16281b4ac0207ea48bf9fe61581a1a89eb32e Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Sun, 21 Jun 2026 21:13:38 -0500 Subject: [PATCH] =?UTF-8?q?docs(framework):=20alpha=20DoD=20=C2=A78=20gree?= =?UTF-8?q?n-checklist=20+=20v0.0.39-alpha=20release=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Maps every Constitution-alpha acceptance criterion (DESIGN §8) to its merged PR, and drafts the Gitea release notes for the v0.0.39-alpha tag. For the Lead to use when cutting the tag after P5 #605 -> P6 #607 -> aiguide #8 merge. Refs #606, #542 Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01EsgTQzV5YUGk1JtCLP4B83 --- .../framework-constitution/ALPHA-DOD.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 docs/design/framework-constitution/ALPHA-DOD.md diff --git a/docs/design/framework-constitution/ALPHA-DOD.md b/docs/design/framework-constitution/ALPHA-DOD.md new file mode 100644 index 0000000..d3fa979 --- /dev/null +++ b/docs/design/framework-constitution/ALPHA-DOD.md @@ -0,0 +1,75 @@ +# 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 ` 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).