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

jason.woltje · 2026-06-22T01:57:22Z

jason.woltje commented

2026-06-22 01:57:22 +00:00

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

Implements R7 + R8 + the R9 composer test of the Constitution alpha. Closes #604 (lineage #542).

What it does

mosaic compose-contract <harness> and the launcher both produce one pre-merged contract blob with operator *.local.md overlays composed in (DESIGN §3.2), so a user's deltas reach the model without a read-merge ritual.

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, so only the small delta is injected — preserves the P3 byte-budget tiering. 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). Validates the harness.
defaults/AGENTS.md bare-launch self-load fallback now nudges to relaunch via mosaic <harness> (or mosaic doctor) when overlays exist (R7 known-limitation, §9).

ASSUMPTION (steered autonomy)

Overlays are injected as deltas by value under labeled sections; bases keep existing residency (USER injected; SOUL/STANDARDS load-on-demand). Rationale: honors §3.2 without re-injecting large base prose / breaking the P3 byte budget. Full reasoning in docs/scratchpads/p5-overlay-composer.md.

Verification

compose-contract.spec.ts — 7 tests: per-tier anchors, Tier-3 byte-equality (injected L0 == CONSTITUTION.md on disk), overlay present/absent, whitespace-only ignored, per-harness runtime selection. ✅
launch.spec.ts — 26 existing tests still green (refactor regression). ✅
tsc clean on touched files; prettier clean; pnpm lint/typecheck pass.

Note for the reviewer

Commit 9f6da92 is a separate chore(format) fixing a pre-existing repo-wide format:check violation on main (docs/fleet/PRD-fleet-suite.md, markdown-table alignment only — no content change). It was blocking the pre-push gate; picked it up to unblock. Easy to drop/attribute separately if you'd rather handle it in the fleet-suite lineage.

Deferred to P6

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

🤖 Generated with Claude Code

## P5 — Overlay composer + cross-harness (`compose-contract`) Implements **R7 + R8** + the R9 composer test of the Constitution alpha. Closes #604 (lineage #542). ### What it does `mosaic compose-contract <harness>` and the launcher both produce one pre-merged contract blob with operator `*.local.md` overlays composed in (DESIGN §3.2), so a user's deltas reach the model without a read-merge ritual. - **`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, so only the small delta is injected — **preserves the P3 byte-budget tiering**. 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). Validates the harness. - **`defaults/AGENTS.md`** bare-launch self-load fallback now nudges to relaunch via `mosaic <harness>` (or `mosaic doctor`) when overlays exist (R7 known-limitation, §9). ### ASSUMPTION (steered autonomy) Overlays are injected as **deltas by value** under labeled sections; bases keep existing residency (USER injected; SOUL/STANDARDS load-on-demand). Rationale: honors §3.2 without re-injecting large base prose / breaking the P3 byte budget. Full reasoning in `docs/scratchpads/p5-overlay-composer.md`. ### Verification - `compose-contract.spec.ts` — **7 tests**: per-tier anchors, Tier-3 byte-equality (injected L0 == `CONSTITUTION.md` on disk), overlay present/absent, whitespace-only ignored, per-harness runtime selection. ✅ - `launch.spec.ts` — **26 existing tests** still green (refactor regression). ✅ - `tsc` clean on touched files; `prettier` clean; `pnpm lint`/`typecheck` pass. ### Note for the reviewer Commit `9f6da92` is a **separate** `chore(format)` fixing a **pre-existing** repo-wide `format:check` violation on `main` (`docs/fleet/PRD-fleet-suite.md`, markdown-table alignment only — no content change). It was blocking the pre-push gate; picked it up to unblock. Easy to drop/attribute separately if you'd rather handle it in the fleet-suite lineage. ### Deferred to P6 `CONTRIBUTING.md` + harness×gate compliance matrix; resident line-count CI ceiling; `aiguide` reconcile; alpha tag `mosaic-vX.Y.Z-alpha`. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

jason.woltje added 2 commits 2026-06-22 01:57:23 +00:00

feat(mosaic): P5 overlay composer — compose-contract + *.local overlays (#604 ) 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

chore(format): prettier docs/fleet/PRD-fleet-suite.md (pre-existing main violation)

ci/woodpecker/push/ci Pipeline was successful

Details

ci/woodpecker/pr/ci Pipeline was successful

Details

9f6da92a4b

Pre-existing repo-wide format:check failure on origin/main (markdown table
alignment only — no content change). Picked up to unblock the pre-push gate;
flagged to the Lead. Not part of the P5 composer change.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EsgTQzV5YUGk1JtCLP4B83

jason.woltje referenced this issue from a commit

2026-06-22 02:07:55 +00:00

feat(framework): P6 docs + compliance matrix + resident-budget CI (#606)

jason.woltje referenced this pull request

2026-06-22 02:08:14 +00:00

feat(framework): P6 — docs + compliance matrix + resident-budget CI #607

jason.woltje referenced this issue from a commit

2026-06-22 02:13:50 +00:00

docs(framework): alpha DoD §8 green-checklist + v0.0.39-alpha release notes

jason.woltje merged commit 23343bb7f0 into main

2026-06-22 02:16:06 +00:00

jason.woltje referenced this issue from a commit