# P5 — Overlay composer + cross-harness (compose-contract)

- **Issue:** #604 · **Branch:** `feat/p5-overlay-composer` · **Lineage:** #542 → constitution alpha
- **Requirements:** R7 (compose-contract) + R8 (cross-harness) + R9 (composer test)
- **Design of record:** `docs/design/framework-constitution/{DESIGN.md §3.2, PRD.md §4}` (on `feat/framework-constitution-alpha`)

## Locked design (sequential-thinking)

Current `launch.ts` assembly (`buildComposedPrompt`) injects by value: mission + PRD + hard-gate +
CONSTITUTION + AGENTS + USER + TOOLS + runtime. It does **not** inject SOUL or STANDARDS (those are
read-on-demand per the gutted AGENTS dispatcher), and has no `.local` overlay support.

**Decision (ASSUMPTION — recorded for the PR):** overlays are injected as **deltas by value** under
labeled sections; base files keep their existing residency.

- `USER.local.md` → appended directly under the `# User Profile` block (USER is injected).
- `SOUL.local.md` + `STANDARDS.local.md` → a trailing `# Operator Overlays` section (their bases are
  load-on-demand, so only the small delta is injected — not the full base prose).
- **Why:** honors DESIGN §3.2 ("model gets one pre-merged blob, no read-merge ritual") while preserving
  the P3 byte-budget tiering (don't re-inject large SOUL/STANDARDS prose). Precedence order kept: base
  layers first, operator overlays at recency.
- Base-only is automatic when a `.local` file is absent (`readOptional`).

## Plan

| #   | Task                                                                                                   | File                                    |
| --- | ------------------------------------------------------------------------------------------------------ | --------------------------------------- |
| 1   | Extract `composeContract({harness, mosaicHome})` pure fn; `buildComposedPrompt` delegates              | `src/commands/launch.ts`                |
| 2   | Overlay logic (USER.local under profile; SOUL/STANDARDS.local in `# Operator Overlays`)                | `src/commands/launch.ts`                |
| 3   | `mosaic compose-contract <harness>` command → prints blob to stdout                                    | `src/commands/launch.ts`                |
| 4   | Bare-launch overlay nudge in self-load fallback                                                        | `framework/defaults/AGENTS.md`          |
| 5   | `compose-contract.spec.ts`: per-tier anchor, Tier-3 byte-equality, overlay present/absent, per-harness | `src/commands/compose-contract.spec.ts` |

## Deferred to P6

CONTRIBUTING.md + harness×gate compliance matrix; resident line-count CI ceiling; `aiguide` reconcile;
alpha tag `mosaic-vX.Y.Z-alpha`.

## Status

- [x] Phase scaffold (branch, issue #604, scratchpad, TASKS)
- [ ] Implementation (tasks 1–5)
- [ ] prettier + vitest green; PR via wrapper → Lead (rides 0.0.39; 0.0.38 mid-cut)