bootstrap/docs/PRD.md

PRD: MACP Phase 1 Core Protocol Implementation

Metadata

• Owner: Jarvis
• Date: 2026-03-27
• Status: in-progress
• Best-Guess Mode: true

Problem Statement

The current orchestrator-matrix rail can queue shell-based worker tasks, but it does not yet expose a standardized protocol for dispatch selection, worktree-aware execution, structured results, or manual MACP queue operations. MACP Phase 1 extends the existing rail so orchestrators can delegate to multiple runtimes through a consistent task model while preserving current behavior for legacy tasks.

Objectives

1. Extend the existing orchestrator-matrix protocol and controller to support MACP-aware task dispatch and status tracking.
2. Add a dispatcher layer that manages worktree lifecycle, runtime command generation, and standardized results.
3. Provide a CLI entrypoint for manual MACP submission, status inspection, queue draining, and history review.

Scope

In Scope

1. Extend the orchestrator task and event schemas and add a result schema.
2. Add a Python dispatcher module under tools/orchestrator-matrix/dispatcher/.
3. Update the controller to use the dispatcher for MACP-aware tasks while preserving legacy execution paths.
4. Update orchestrator config templates, task markdown sync logic, and CLI routing/scripts for MACP commands.
5. Add verification for backward compatibility, schema validity, imports, and basic MACP execution flow.

Out of Scope

1. Rewriting the orchestrator controller architecture.
2. Changing Matrix transport behavior beyond schema compatibility.
3. Implementing real OpenClaw sessions_spawn execution beyond producing the config payload/command for callers.
4. Adding non-stdlib Python dependencies or npm-based tooling.

User/Stakeholder Requirements

1. MACP must evolve the current orchestrator-matrix implementation rather than replace it.
2. Legacy task queues without dispatch fields must continue to run exactly as before.
3. MACP-aware tasks must support dispatch modes yolo, acp, and exec.
4. Results must be written in a structured JSON format suitable for audit and orchestration follow-up.
5. A manual mosaic macp CLI must expose submit, status, drain, and history flows.

Functional Requirements

1. Task schema must include MACP dispatch, worktree, result, retry, branch, brief, issue/PR, and dependency fields.
2. Event schema must recognize task.gated, task.escalated, and task.retry.scheduled, plus a dispatcher source.
3. Dispatcher functions must set up worktrees, build commands, execute tasks, collect results, and clean up worktrees.
4. Controller run_single_task() must route MACP-aware tasks through the dispatcher and emit the correct lifecycle events/status transitions.
5. tasks_md_sync.py must map optional MACP table columns only when those headers are present in docs/TASKS.md; absent MACP headers must not inject MACP fields into legacy tasks.
6. bin/mosaic must route mosaic macp ... to a new bin/mosaic-macp script.

Non-Functional Requirements

1. Security: no secrets embedded in generated commands, config, or results.
2. Performance: controller remains deterministic and synchronous with no async or thread-based orchestration.
3. Reliability: worktree creation/cleanup failures must be surfaced predictably and produce structured task failure/escalation states.
4. Observability: lifecycle events, logs, and result JSON must clearly show task outcome, attempts, gates, and errors.

Acceptance Criteria

1. Existing legacy tasks without dispatch still run through the old shell path with unchanged behavior.
2. MACP-aware exec tasks run through the dispatcher and produce result JSON with gate outcomes.
3. New schemas validate task/event/result payload expectations for MACP fields and statuses.
4. mosaic macp submit, status, and history work from a bootstrapped repo state, and drain delegates to the existing orchestrator runner.
5. Python imports for the updated controller, dispatcher, and sync code complete without errors on Python 3.10+.

Constraints and Dependencies

1. Python implementation must use stdlib only and support Python 3.10+.
2. Shell tooling must remain bash-based and fit the existing Mosaic CLI style.
3. Dispatch fallback rules must use exec when dispatch is absent and config/default runtime when runtime is absent.
4. Worktree convention must derive from the repository name and task metadata unless explicitly overridden by task fields.

Risks and Open Questions

1. Risk: yolo command execution requires a PTY, so the dispatcher needs a safe wrapper that still behaves under subprocess.
2. Risk: worktree cleanup could remove a path unexpectedly if task metadata is malformed.
3. Risk: old queue consumers may assume only the original task statuses and event types.
4. Open Question: whether task.gated should be emitted by the dispatcher or controller once worker execution ends and quality gates begin.

Testing and Verification Expectations

1. Baseline checks: Python import validation, targeted script execution checks, JSON syntax/schema validation, and any repo-local validation applicable to changed code paths.
2. Situational testing: legacy orchestrator run with old-style tasks, MACP exec flow including result file generation, CLI submit/status/history behavior, and worktree lifecycle validation.
3. Evidence format: command-level results captured in the scratchpad and summarized in the final delivery report.

Milestone / Delivery Intent

1. Target milestone/version: 0.0.x bootstrap enhancement
2. Definition of done: code merged to main, CI terminal green, issue #8 closed, and verification evidence recorded against all acceptance criteria.

Assumptions

1. ASSUMPTION: A single issue can track the full Phase 1 implementation because the user requested one bounded feature delivery rather than separate independent tickets.
2. ASSUMPTION: For acp dispatch in Phase 1, the controller must escalate the task immediately with a clear reason instead of pretending work ran before OpenClaw integration exists.
3. ASSUMPTION: task.gated should be emitted by the controller as the transition into quality-gate execution, which keeps gate-state ownership in one place alongside the existing gate loop.