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

tools/orchestrator-matrix/README.md

@@ -13,6 +13,7 @@ mechanical quality gates.
 ## Components
 
 - `protocol/` - JSON schemas for task/event payloads
+- `dispatcher/` - MACP dispatch helpers for worktrees, command generation, results, and cleanup
 - `controller/mosaic_orchestrator.py` - deterministic controller loop
 - `adapters/` - runtime adapter guidance
 
@@ -83,3 +84,29 @@ Task injection message format (room text):
 ```text
 !mosaic-task {"id":"TASK-123","title":"Fix bug","command":"echo run","quality_gates":["pnpm lint"]}
 ```
+
+## MACP Notes
+
+MACP-aware tasks add dispatch metadata on top of the existing queue model:
+
+- `dispatch`: `exec`, `yolo`, or `acp`
+- `type`: task category used for orchestration intent
+- `worktree` / `branch`: task-specific git execution context
+- `brief_path`: markdown brief consumed by runtime-backed dispatchers
+- `result_path`: structured result JSON written under `.mosaic/orchestrator/`
+
+Controller behavior remains backward compatible:
+
+- Tasks without `dispatch` continue through the legacy shell execution path.
+- Tasks with `dispatch` use the MACP dispatcher and can emit `task.gated` and `task.escalated`.
+- `acp` dispatch is fail-safe in Phase 1: it escalates with `ACP dispatch requires OpenClaw integration (Phase 2)` instead of reporting success.
+- `yolo` dispatch stages the brief in a temporary file so the brief body does not appear in process arguments.
+
+Manual queue operations are exposed through:
+
+```bash
+mosaic macp submit ...
+mosaic macp status
+mosaic macp drain
+mosaic macp history --task-id TASK-001
+```