Jason Woltje
bca7fc4cf2
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
44 lines
2.9 KiB
Markdown
44 lines
2.9 KiB
Markdown
# 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)
|