e5eac889ec
- Fix 1: tasks_md_sync only sets MACP fields when columns exist in table headers - Fix 2: ACP dispatch now escalates instead of falsely completing - Fix 3: Removed premature collect_result() from dispatch_task() - Fix 4: Yolo brief staged via temp file (0600) instead of process args - Fix 5: cleanup_worktree validates path against configured worktree base
99 lines
6.2 KiB
Markdown
99 lines
6.2 KiB
Markdown
# 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.
|