stack/docs/design/framework-constitution/PRD.md

PRD — Mosaic Framework Constitution & Public Sanitization (Alpha)

Status: Active · Derives from: DESIGN.md (canonical design) · Mode: Orchestrator (autonomous) Source of record for requirements. Implementation derives from this PRD; the design supplies the rationale.

1. Objective

Re-architect the public @mosaicstack/mosaic framework so that universal Constitution law is cleanly separated from per-user customization (agent persona, operator profile, preferences); remove all personal data from the public package; make customization upgrade-safe; keep the contract robust across Claude/Codex/Pi/OpenCode; ship a solid alpha.

2. Operator decisions (locked)

Ref	Decision	Locked value
Q1	License	MIT (root + framework LICENSE, package.json field)
Q10	Persona example	Neutral only. Accommodation/PDA content stays in the operator's private init-generated SOUL.md/USER.md; public ships a generic persona example.
Q9	Pi runtime	Maintainer-internal for alpha. Public compliance matrix lists Claude/Codex/OpenCode as supported; Pi marked internal.
Q7	OpenBrain hook	Soft-degrade. prevent-memory-write.sh still blocks the write when OPENBRAIN_URL is unset; it just omits the OpenBrain nudge.
—	Q2/Q3/Q5/Q6/Q8	Proceed on DESIGN.md provisional defaults (bare-launch = best-effort; non-interactive persona fail-closed; overlay scope SOUL/USER/STANDARDS.local; migration = .bak+advisory; two installers + shared fixtures).
Q4	CI authority	Resolved: Woodpecker; config at repo-root .woodpecker/ (ci.yml install→typecheck→{lint,format,test}). New gates add steps/files there.

3. Re-grounding vs current main (drift since design)

main advanced 14 commits (June 16→20) during design. Verified deltas that change implementation targets (architecture unchanged):

• Credential leak fix simplified (was Phase 0 fail-closed). #551 added a ~/.config/mosaic/credentials.json preference but kept the ~/src/jarvis-brain/credentials.json fallback at credentials.sh:20,23, detect-platform.sh:89, stack-health.sh:23. Fix = drop the jarvis-brain fallback, default to ~/.config/mosaic/credentials.json (align with #551 intent; no fail-closed).
• launch.ts anchors shifted (#555/#556, +142/−11): checkSoul :63, buildPrompt reads AGENTS.md :334, --append-system-prompt :649/:682, opencode AGENTS.md :674. Target current lines.
• TOOLS.md rewritten (#554, +29 fleet cheatsheet) and prevent-memory-write.sh unchanged (still brain.woltje.com:29). install.sh, file-adapter.ts, mosaic-init unchanged — Phase 3/4 design holds.
• Contamination = 31 files (was 29); new sites: systemd/user/README.md, tools/git/test-issue-create-body-safety.sh, tools/bootstrap/agent-lint.sh, tools/{coolify,glpi}/README.md. Phase 2 scope updated.
• Active concurrent fleet development on main → keep phase PRs small and fast; rebase + re-verify anchors immediately before each phase's edits.

4. Requirements (the alpha must satisfy)

R1 — Legal. MIT LICENSE at monorepo root and packages/mosaic/framework/; "license":"MIT" in package.json. R2 — No executable leaks. No private path or domain in any shipped *.sh/hook: 4 credential sites → ~/.config/mosaic/credentials.json; prevent-memory-write.sh → ${OPENBRAIN_URL} soft-degrade. R3 — Sanitization gate. verify-sanitized.sh (structural rules + labeled current-contaminant denylist, self-tested, scoped to *.md+*.sh, excludes examples/) wired blocking in .woodpecker/. R4 — Clean tree. All 31 contaminated files purged; defaults/SOUL.md + jarvis-loop.json deleted; AUDIT-*.md relocated; examples/* created (neutral persona per Q10); rails/→tools/ in both template families. R5 — Constitution layer. defaults/CONSTITUTION.md (L0) extracted by subtraction: gates in one place, capability-verb authored (no tool-named "else stop"), two-axis precedence verbatim, §1.4 merge-disambiguation split, firewall rule, tier-aware self-load; AGENTS.md gutted to ~50-line dispatcher (remove false "already in context"); constitution/LAYER-MODEL.md governance spec; restated policy stripped from STANDARDS + 4 RUNTIME files. R6 — Upgrade-safe customization. Seed lists split FRAMEWORK_OWNED (overwrite) vs USER_SEEDED (seed-if-absent) in both installers; AGENTS.md/STANDARDS.md out of PRESERVE_PATHS; snapshot→sync→restore; v2→v3 migration moves user edits to .local/.bak; FRAMEWORK_VERSION=3; mosaic-init --non-interactive fail-closed persona. R7 — Overlay composer. mosaic compose-contract <harness> merges base + SOUL.local/USER.local/STANDARDS.local before injection; per-harness emission; bare-launch base-only documented. R8 — Cross-harness. Single L0 source; runtime/templates reference, never restate; tiered injection; Tier-3 anchor is a byte-equal L0 substring; sequential-thinking contradiction rewritten to capability verbs in all 4 RUNTIME files; Pi marked internal (Q9). R9 — Verification. 5-fixture migration matrix (fresh / legacy-edited / tuned-standard / no-TTY / interrupt) green against both installers asserting injected bytes; composer unit test (per-tier anchor + Tier-3 byte-equality); resident line-count CI ceiling over framework-owned resident files. R10 — Docs. CONTRIBUTING.md (layer model, PII prohibition, dual-installer parity, known-limitations, harness×gate compliance matrix with hook-parity gap); update aiguide to stay consistent with the Constitution.

5. Phased delivery (each phase = its own CI-green PR; references issue #542 lineage)

Phase	Scope	Gates the tag?	Key risk
P0	R1 + R2 (MIT LICENSE; 4 cred sites; OpenBrain soft-degrade)	— ships first	none (no behavior change)
P1	R3 (sanitization gate, self-tested, wired blocking; build goes red = P2 worklist)	yes	gate must self-test
P2	R4 (sanitize tree to green; delete SOUL.md/jarvis-loop; examples/*)	yes	breadth (31 files)
P3	R5 (extract CONSTITUTION.md by subtraction; gut AGENTS.md; LAYER-MODEL)	yes	weakening a gate during extraction
P4	R6 (overwrite semantics + migration + headless bootstrap, both installers + 5 fixtures)	yes — gates tag	migration data-loss
P5	R7 + R8 (compose-contract + composer test; cross-harness)	yes	new subsystem
P6	R9 line-count ceiling + R10 docs/compliance matrix + aiguide; tag mosaic-vX.Y.Z-alpha	yes	final reconciliation

6. Acceptance criteria (alpha Definition of Done)

All CI-green on main: R1–R10 satisfied; verify-sanitized.sh green-and-wired; git grep for the contaminant denylist over shipped paths returns zero; 5-fixture migration matrix green on both installers asserting injected bytes; composer unit test green; resident line-count ceiling enforced; CONTRIBUTING.md

• compliance matrix present; alpha tag pushed + release published; aiguide reconciled. Each phase PR independently reviewed (author≠reviewer) and merged.

7. Deferred to v2 (explicit)

constitution/ deploy dir; adapters/<h>.capabilities.json; 3-way merge; live-launch cross-harness smoke test; policy/*.md composition; per-layer version stamps as migration driver; DCO CI; Pi as public target.

8. Tracking

• Umbrella: issue #542 (agency patterns) folds into this lineage; a milestone/issue per phase created via ~/.config/mosaic/tools/git/*.sh before each phase's coding.
• Durable state: MISSION.md (phase status), this PRD, DESIGN.md (rationale), OPEN-QUESTIONS.md (resolved).