feat(framework): P6 — docs + compliance matrix + resident-budget CI (#607)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

docs/TASKS.md

@@ -48,6 +48,9 @@ Active workstream is **W1 — Federation v1**. Workers should:
 
 ## P5 — Overlay composer + cross-harness (#604) — feat/p5-overlay-composer
 
-- Status: in progress. R7 (compose-contract) + R8 (cross-harness) + R9 (composer test).
+- Status: MERGED to main (#605). R7 (compose-contract) + R8 (cross-harness) + R9 (composer test).
 - `composeContract({harness, mosaicHome})` pure fn + `.local` overlay deltas-by-value; `mosaic compose-contract <harness>` command; AGENTS bare-launch nudge; composer spec (per-tier anchor + Tier-3 byte-equality). Detail: scratchpads/p5-overlay-composer.md.
-- Defer to P6: CONTRIBUTING.md + compliance matrix; line-count CI ceiling; aiguide; alpha tag.
+
+## P6 — Docs, compliance matrix, alpha tag (#606) — feat/p6-docs-compliance-alpha
+
+- Status: in-repo deliverables done (CONTRIBUTING.md + harness×gate compliance matrix + check-resident-budget.sh + CI wiring + ALPHA-DOD.md). Remaining: alpha tag v0.0.39-alpha (Lead, post-merge). aiguide reconcile merged (#8). Detail: scratchpads/p6-docs-compliance-alpha.md.

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 <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).

docs/scratchpads/p6-docs-compliance-alpha.md

@@ -0,0 +1,29 @@
+# P6 — Docs, compliance matrix, alpha tag (constitution capstone)
+
+- **Issue:** #606 · **Branch:** `feat/p6-docs-compliance-alpha` · **Lineage:** #542
+- **Requirements:** R9 (resident line-count ceiling) + R10 (CONTRIBUTING + compliance matrix + aiguide) + alpha tag
+
+## Delivered (in-repo)
+
+- `framework/CONTRIBUTING.md` — layer model, operator-hygiene/PII prohibition, dedup rule, resident
+  budget, **dual-installer parity rule**, adding-a-harness, re-contamination rule, **harness×gate
+  compliance matrix** (hook-parity gap marked ⚠️ tracked-v2), known-limitations (§9 residuals), PR checklist.
+- `framework/tools/quality/scripts/check-resident-budget.sh` — line-count ceiling over framework-owned
+  resident files (CONSTITUTION + AGENTS + each runtime/\*/RUNTIME.md); `--self-test`; replaces the crude
+  inline ci.yml loop. Wired blocking in `.woodpecker/ci.yml`.
+- Composer unit test (R9) already runs via `pnpm test`; `verify-sanitized.sh` (P1) already wired.
+
+## Verification
+
+- Sanitization gate green (CONTRIBUTING is operator-neutral). Resident-budget self-test + real run green.
+- prettier clean. Current resident counts: CONSTITUTION 96, AGENTS 83, RUNTIME max 75 — all < ceiling.
+
+## Remaining
+
+- [ ] `aiguide` reconcile (separate repo `~/src/aiguide` / mosaicstack/aiguide) — consistency pass vs Constitution.
+- [ ] Alpha tag `mosaic-vX.Y.Z-alpha` — propose version; Lead cuts after full DoD §8 green + all phases merged.
+
+## Notes
+
+- Alpha DoD (DESIGN §8): all phases P0–P6 merged + CI green. P5 (#605) pending merge after 0.0.38 publish.
+- Hook parity (codex/opencode/pi) = tracked v2 gap, documented in the matrix, not closed here.