feat(mosaic): P5 overlay composer — compose-contract + *.local overlays (#604)

Implements R7 + R8 of the Constitution alpha: launcher-composed operator
overlays so a user's *.local deltas reach the model as one pre-merged blob
(DESIGN §3.2), without re-injecting full base prose.

- composeContract(runtime, mosaicHome=MOSAIC_HOME): testable pure fn extracted
  from the launcher prompt assembly; buildRuntimePrompt delegates to it.
- Overlay logic (deltas by value, base files keep residency):
  - USER.local.md -> appended under the # User Profile block (USER is injected)
  - SOUL.local.md + STANDARDS.local.md -> trailing # Operator Overlays section
    (their bases are load-on-demand; only the small delta is injected, so the
    P3 byte-budget tiering is preserved). Whitespace-only overlays ignored.
  - Absent *.local -> base-only, automatically.
- New command: mosaic compose-contract <harness> -> prints the composed blob
  to stdout (inspection / mosaic doctor / diffing / the composer test).
- defaults/AGENTS.md: bare-launch self-load fallback now nudges to relaunch via
  mosaic <harness> (or mosaic doctor) when *.local overlays exist (R7 known-limit).
- compose-contract.spec.ts (7 tests): per-tier anchors, Tier-3 byte-equality
  (injected L0 == CONSTITUTION.md on disk), overlay present/absent, per-harness.

ASSUMPTION: overlays injected as deltas-by-value under labeled sections; bases
keep existing residency. Rationale in docs/scratchpads/p5-overlay-composer.md.

Verified: 7 composer + 26 launch tests pass; tsc-clean on touched files;
prettier clean. Defers to P6: CONTRIBUTING.md + compliance matrix, line-count
CI ceiling, aiguide reconcile, alpha tag.

Refs #604, #542

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EsgTQzV5YUGk1JtCLP4B83
This commit is contained in:
2026-06-21 20:54:30 -05:00
parent 6dbe452a9f
commit bca7fc4cf2
5 changed files with 237 additions and 12 deletions

View File

@@ -9,7 +9,10 @@ overwritten on upgrade. (Layer model: `constitution/LAYER-MODEL.md`.)
1. Your context already includes `CONSTITUTION.md` + `USER.md` + the TOOLS index + the runtime
contract (injected by `mosaic` launch) — do not re-read those. **If you were launched bare**
(a harness started without `mosaic`, so the law is NOT in your context), read
`~/.config/mosaic/CONSTITUTION.md` now, before your first action.
`~/.config/mosaic/CONSTITUTION.md` now, before your first action. A bare launch also gets
**base contracts only** — operator overlays (`*.local.md`) are composed by the launcher, so if
`SOUL.local.md`/`USER.local.md`/`STANDARDS.local.md` exist, relaunch via `mosaic <harness>` (or run
`mosaic doctor`) to pick them up.
2. Read `SOUL.md` (agent persona — small, once).
3. Read project-local `AGENTS.md` / `CLAUDE.md` if present (these may only make behavior stricter).
4. Read guides ONLY as triggered by the table below — pull role-relevant depth on demand, not up front.