bootstrap/docs/scratchpads/macp-phase1.md

MACP Phase 1 Scratchpad

Objective

Implement MACP Phase 1 in mosaic-bootstrap by extending the orchestrator-matrix protocol, adding a dispatcher layer, wiring the controller, updating sync/config/CLI behavior, and preserving backward compatibility for legacy tasks.

Tracking

• Task ID: MACP-PHASE1
• Issue: #8
• Branch: feat/macp-phase1
• Repo: bootstrap

Budget

• User hard token budget: not specified
• Working assumption: complete in one implementation pass with focused verification and no unnecessary parallelization
• Budget response plan: keep scope limited to the requested file map and verification set

Plan

1. Extend task and event schemas and add the MACP result schema.
2. Build dispatcher/macp_dispatcher.py with isolated helpers for worktree, command, result, and cleanup logic.
3. Wire the controller to detect MACP-aware tasks, emit gated/escalated events, and preserve the legacy path for tasks without dispatch.
4. Add MACP defaults to config, add mosaic macp routing and shell script support, and extend tasks_md_sync.py.
5. Run backward-compatibility and MACP verification, then review/remediate before commit and PR flow.

Assumptions

1. dispatch presence is the MACP-aware signal for the controller, matching the user brief.
2. docs/tasks/MACP-PHASE1-brief.md is an input artifact for this delivery and should remain available for reference.
3. A minimal developer-facing documentation update tied to the orchestrator README/CLI behavior will satisfy the documentation gate for this change surface.

Risks

1. Worktree cleanup must be constrained to task-owned paths only.
2. Gate-state transitions need to remain compatible with current event consumers.
3. CLI submit behavior must avoid corrupting existing tasks.json structure.

Verification Plan

Acceptance Criterion	Verification Method	Evidence
AC-1 legacy tasks still work	Run controller against old-style tasks without dispatch	Passed: temp repo run completed legacy task and wrote completed result JSON
AC-2 MACP exec flow works	Run controller against MACP task queue and inspect result JSON/events/worktree cleanup	Passed: temp repo run produced task.gated and task.completed, wrote structured result JSON with files_changed, and removed the task worktree
AC-3 schemas are valid	Validate schema JSON loads and sample payloads parse/import cleanly	Passed: jsonschema.validate(...) succeeded for task, event, and result schema samples
AC-4 CLI works	Run mosaic macp submit/status/history against a test repo state	Passed: bin/mosaic-macp submit/status/history succeeded and bin/mosaic --help exposed macp
AC-5 imports are clean	Run python3 -c "import ..." for updated modules	Passed: importlib-based module loads and py_compile succeeded

Progress Log

• 2026-03-27: Loaded global/project/runtime contracts and required delivery guides.
• 2026-03-27: Created provider issue #8.
• 2026-03-27: Drafted PRD, task tracking, and this scratchpad before implementation.
• 2026-03-27: Implemented MACP schemas, dispatcher lifecycle, controller integration, CLI support, sync updates, and developer docs.
• 2026-03-27: Added explicit worker escalation handling via the MACP_ESCALATE: stdout marker.

Tests Run

• python3 -m py_compile tools/orchestrator-matrix/controller/mosaic_orchestrator.py tools/orchestrator-matrix/controller/tasks_md_sync.py tools/orchestrator-matrix/dispatcher/macp_dispatcher.py
• importlib module-load check for updated Python files
• jsonschema.validate(...) for task/event/result samples
• Temp repo legacy controller run with old-style tasks.json
• Temp repo MACP exec controller run with worktree/result/cleanup verification
• Temp repo CLI checks using bin/mosaic-macp submit, status, and history
• Temp repo tasks_md_sync.py --apply run with MACP columns
• git diff --check
• bash -n bin/mosaic bin/mosaic-macp

Review

• Automated review attempted with ~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted
• Initial review attempt failed because generated __pycache__ files introduced non-UTF-8 diff content; generated caches were removed
• Manual independent review completed on the dispatcher/controller/CLI delta
• Remediation applied: final MACP results are now written before worktree cleanup, and explicit worker escalation is handled instead of being ignored

Residual Risks

• The repo-local bin/mosaic route was verified through help output; full runtime routing depends on installation into $MOSAIC_HOME/bin.
• Explicit worker escalation currently uses a stdout marker convention rather than a richer structured worker-to-controller handoff.