docs(design): mosaic framework constitution — expert conference output

Conference of 7 experts (architect/moonshot/contrarian/coder/aiml/devex/steward)
debated layering, sanitization, upgrade-safety, cross-harness robustness.
Artifacts: BRIEF, 7 positions, 7 rebuttals, synthesis-v1, 3 red-team passes,
canonical DESIGN.md, OPEN-QUESTIONS.md, MISSION.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/design/framework-constitution/BRIEF.md

@@ -0,0 +1,88 @@
+# 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.