bootstrap/docs/DEVELOPER-GUIDE/orchestrator-matrix/macp-phase1.md

MACP Phase 1

MACP Phase 1 extends tools/orchestrator-matrix/ without replacing the existing deterministic controller model.

What Changed

1. Task and event schemas now describe MACP dispatch metadata, new lifecycle statuses, and dispatcher-originated events.
2. tools/orchestrator-matrix/dispatcher/macp_dispatcher.py manages task worktrees, dispatch command generation, result files, and cleanup.
3. mosaic_orchestrator.py routes MACP-aware tasks through the dispatcher while leaving legacy non-dispatch tasks on the original shell path.
4. bin/mosaic-macp adds manual submit, status, drain, and history operations for .mosaic/orchestrator/.

Dispatch Modes

1. exec: runs the task's command directly inside the task worktree.
2. yolo: launches mosaic yolo <runtime> with the task brief content via a PTY wrapper.
3. acp: emits the config payload a caller can hand to an ACP/OpenClaw session spawner.

Result Contract

MACP writes task result JSON under .mosaic/orchestrator/results/ by default. Result files capture:

1. Task status and timing
2. Attempt counters
3. Runtime and dispatch metadata
4. Changed files seen in the task worktree
5. Quality-gate command results
6. Error or escalation details

Compatibility

Legacy tasks that omit dispatch still behave like the original matrix controller. This keeps existing tasks.json workflows functional while allowing orchestrators to opt into MACP incrementally.