Files

Jason Woltje bca7fc4cf2 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

2026-06-21 20:54:30 -05:00

5.9 KiB

Executable File

Raw Blame History

Mosaic Agent Dispatcher

Thin load-order dispatcher + guide router. The non-negotiable law lives in ~/.config/mosaic/CONSTITUTION.md (L0) — this file does NOT restate gates. Framework-owned; overwritten on upgrade. (Layer model: constitution/LAYER-MODEL.md.)

Session Start — Load Order

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. 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.
Read SOUL.md (agent persona — small, once).
Read project-local AGENTS.md / CLAUDE.md if present (these may only make behavior stricter).
Read guides ONLY as triggered by the table below — pull role-relevant depth on demand, not up front.
For implementation work, read guides/E2E-DELIVERY.md (the full delivery procedure: PRD/tracking gates, execution cycle, testing, review, completion). STANDARDS.md is reference — load it only if the task needs standards validation (do not halt if missing).

Conditional Guide Loading (load only what the task needs)

Task	Guide
Project bootstrap	`guides/BOOTSTRAP.md`
PRD creation / requirements	`guides/PRD.md`
Implementation delivery (cycle/testing/completion)	`guides/E2E-DELIVERY.md`
Orchestration flow	`guides/ORCHESTRATOR.md`
Mission lifecycle / multi-session orchestration	`guides/ORCHESTRATOR-PROTOCOL.md`
Orchestrator estimation heuristics	`guides/ORCHESTRATOR-LEARNINGS.md`
Frontend changes	`guides/FRONTEND.md`
Backend/API changes	`guides/BACKEND.md`
Auth/authorization	`guides/AUTHENTICATION.md`
CI/CD changes	`guides/CI-CD-PIPELINES.md`
Infrastructure/DevOps/deployment	`guides/INFRASTRUCTURE.md`
Code review work	`guides/CODE-REVIEW.md`
TypeScript strict typing	`guides/TYPESCRIPT.md`
QA / test strategy	`guides/QA-TESTING.md`
Documentation (any code/API/auth/infra change)	`guides/DOCUMENTATION.md`
Secrets / vault usage	`guides/VAULT-SECRETS.md`
Tool/credential reference (service CLIs, wrappers)	`guides/TOOLS-REFERENCE.md`
Memory protocol (OpenBrain capture/recall)	`guides/MEMORY.md`

Subagent Model Selection (Cost — Hard Rule)

Select the cheapest model capable of the task; do NOT default to the most expensive (omitting the tier defaults to the parent — usually opus — and wastes budget).

haiku — search/grep/glob, codebase exploration, status/health checks, one-line mechanical fixes.
sonnet — code review, lint, test writing/fixing, standard feature implementation.
opus — complex architecture / multi-file refactors, security/auth logic, ambiguous design.

Start cheapest; escalate only when the task genuinely needs deeper reasoning. Runtime syntax for the tier is in the runtime contract.

Superpowers (use your tools — under-use is a violation)

Skills, hooks, MCP, and plugins are force multipliers you MUST use when applicable.

Skills: before implementation, scan ~/.config/mosaic/skills/ and load any matching the task domain; include skill loading in worker kickstarts. Do not load unrelated skills.
Hooks: never bypass or suppress hook output (see "hooks are the gate" in CONSTITUTION.md); fix hook failures like failing tests. If a hook is wrong, report it as a framework issue.
MCP: use structured-reasoning (sequential-thinking) for planning/architecture; the cross-agent memory layer (OpenBrain capture/search/recent) — search at session start, capture what you learn. Prefer web/browser/research tools over asking the human to look things up.
Plugins: use code-review / pr-review / architecture plugins proactively before opening a PR.
Self-evolution: capture framework-improvement / tooling-gap / framework-friction to OpenBrain — operator-agnostic only (see the framework-PR firewall in CONSTITUTION.md).

Missing core file

If CONSTITUTION.md, AGENTS.md, SOUL.md, or the runtime contract is missing, stop and report it. This agent-facing strictness is intentional and stricter than the launcher: the launcher injects CONSTITUTION.md tolerantly (skipping it if absent so pre-upgrade hosts keep working), but once a host is re-seeded a genuinely missing core file is a stop-and-report condition — not something to proceed past.

Session Closure

Confirm: required + situational tests passed (primary gate); aligned to docs/PRD.md; acceptance criteria mapped to evidence; independent code review passed (if code changed); required docs updated; scratchpad updated. For PR-workflow delivery: merged PR number + merge commit on main, terminal-green CI, linked issue closed (or docs/TASKS.md equivalent). If blocked by access/tooling, return blocked with the exact failed wrapper command — do not claim completion. Full checklist: guides/E2E-DELIVERY.md.

5.9 KiB Executable File Raw Blame History