# Mission Brief — Mosaic Framework Constitution & Public Sanitization (Alpha)

## The problem

`@mosaicstack/mosaic` ships a public, open-source agent framework under
`packages/mosaic/framework/`. Today it conflates three different things in the
same files:

1. **Universal framework law** — hard gates, delivery contract, escalation
   rules, integrity guardrails. Should be identical for every user and every
   harness. (currently spread across `defaults/AGENTS.md`, `guides/*`)
2. **Agent persona** — the agent's name, tone, identity. (currently
   `defaults/SOUL.md`, hardcoded to "Jarvis")
3. **The human operator's profile & preferences** — name, accommodations,
   projects, comms style. (currently leaks into `defaults/SOUL.md` as "PDA",
   into `defaults/USER.md`, runtime overlays like `jarvis-loop.json`)

Because of this conflation, the public package is **contaminated with one
operator's personal preferences** (29 files reference jarvis/jason/woltje/PDA),
and there is **no clean separation between what the framework owns (and updates)
and what a user owns (and customizes).** A downstream user who edits files gets
clobbered on upgrade; the maintainer's personal identity ships to everyone.

## The goal

Re-architect the framework so that:
- It is a **clean, generic, open-source framework** any team can adopt.
- There is a clear, enforced separation between a **Mosaic Constitution**
  (universal, framework-owned, non-negotiable) and **per-user/per-deployment
  customization** (identity, profile, preferences, project specifics).
- Users can **customize and still receive framework updates** without losing
  their changes or drifting (the deployed-vs-source drift problem is real today).
- The contract is **robust and consistent across harnesses** (Claude, Codex,
  Pi, OpenCode) which inject context differently.
- Ships as a **solid alpha release**.

## Current document architecture (ground truth — read the real files)

Repo working copy: `/home/jwoltje/src/_ms_stack`
Framework root:    `packages/mosaic/framework/`

- `defaults/` — `AGENTS.md` (thin-core contract), `SOUL.md` (persona),
  `STANDARDS.md`, `TOOLS.md`, `USER.md`. These deploy to `~/.config/mosaic/`.
  **Contaminated with personal data.**
- `templates/` — `SOUL.md.template`, `USER.md.template`, `TOOLS.md.template`,
  `agent/AGENTS.md.template`, project templates with `{{PLACEHOLDER}}` tokens.
  A template/personalization layer already exists but is under-used.
- `guides/` — on-demand deep guides (E2E-DELIVERY, ORCHESTRATOR, QA-TESTING,
  PRD, CODE-REVIEW, etc.). Mostly framework-universal.
- `runtime/{claude,codex,pi,opencode,mcp}/` — per-harness RUNTIME.md + settings.
- `adapters/{claude,codex,pi,generic}.md` — per-harness adapter notes.
- `profiles/` — domain / tech-stack / workflow presets (JSON).
- `install.sh` / `mosaic-init` — deploy/personalization entrypoints.

## Design questions to resolve (debate these)

- **DQ1 — Layering.** Should Mosaic introduce an explicit **Constitution** layer
  distinct from SOUL (persona) and USER (operator profile)? Define the canonical
  layers, what content belongs in each, and the precedence/override order.
- **DQ2 — Sanitization.** How to remove personal data from public `defaults/`
  while keeping a great out-of-box experience: generic-defaults vs
  empty-defaults+examples vs template-then-init. What ships vs what's generated.
- **DQ3 — Customization & upgrade safety.** How a user customizes and still
  pulls framework updates without losing changes or drifting. Layering/override,
  version pinning, migration, the deployed-vs-source reconciliation.
- **DQ4 — Cross-harness robustness.** How to make the Constitution enforce
  consistently across Claude/Codex/Pi/OpenCode given different injection and tool
  models. Single source of truth + adapter strategy.
- **DQ5 — Minimalism vs completeness.** The contract is large and partly
  duplicated. How to keep it robust but not bloated, contradictory, or
  model-degrading — thin always-resident core vs on-demand depth.

## Constraints / non-negotiables

- Output must be **harness-agnostic** in the core; harness specifics isolated to
  adapters/runtime.
- **No personal data, no secrets, no PII** in any public/shipped file.
- Must be **backward-compatible enough** to land as an alpha without breaking
  existing deployments catastrophically (migration path required).
- Keep the existing Mosaic hard gates intact (PR-review-before-merge, green CI,
  no forced merges, completion-defined-at-end) — this re-architecture is about
  *where rules live and how they're customized*, not weakening them.

## Definition of done (alpha)

A merged, CI-green PR that: establishes the Constitution/customization layering;
sanitizes the public package; provides an upgrade-safe customization mechanism;
documents the model; and tags an alpha release. A PRD precedes implementation.