stack/docs/scratchpads/p5-overlay-composer.md

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

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