feat: MACP Phase 1 — Core Protocol Implementation (#9)

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

@@ -0,0 +1,31 @@
+# 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>` via a PTY wrapper and stages the brief in a temporary file so the brief body is not exposed in process arguments.
+3. `acp`: escalates immediately with `ACP dispatch requires OpenClaw integration (Phase 2)` until real ACP/OpenClaw spawning exists.
+
+## 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. `tasks_md_sync.py` only injects MACP fields when the corresponding markdown headers exist, which keeps existing `tasks.json` workflows functional while allowing orchestrators to opt into MACP incrementally.