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