Randall Stillwell 9405da8a45 feat(convoys): convoy lifecycle MCP and state machine (Epic 4)

Adds server-enforced convoy transitions with gate actor guards, convoy_events
logging, and six MCP tools (create, brief, transition, log, query, reconcile).

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-07-07 14:51:19 -05:00

1.5 KiB

Raw Blame History

Convoy lifecycle

Server-enforced convoy state machine for the agent pipeline (Epic 4). Convoys map to Echodo project objects; briefs map to child task objects.

Status enum

draft → convoy_review → ready → in_progress → pr_review → merged → released

Terminal / exceptional: blocked, cancelled

MCP tools

Tool	Purpose
`create_convoy`	Create `project` at `draft` with convoy metadata in `content`
`create_brief`	Create child `task` brief under a convoy
`transition_convoy_status`	Enforce actor + transition rules; writes `convoy_events`
`log_convoy_event`	Append role metrics / analytics row
`query_manifest_status`	Convoy status, briefs, recent events
`reconcile_from_files`	Import `.convoys/*.md` into Echodo; report pending outbox

Gate actors

human-gate-1 — plan approval (convoy_review ↔ ready / draft)
human-gate-2 — PR merge gate (pr_review ↔ merged / in_progress)
human-gate-3 — prod promote (merged → released)

Pipeline roles (role-architect, role-implementer, …) cannot perform gate transitions.

Local-first

Convoy markdown lives in .convoys/ (see .convoys/README.md). Failed MCP calls should append to .convoys/.pending-mcp-sync.jsonl; reconcile_from_files reports and clears the outbox after sync.

Implementation

State machine: packages/shared/src/convoy-lifecycle/
Events table: packages/database/src/schema/convoy_events.ts
MCP: apps/mcp-server/src/tools/*convoy*

1.5 KiB Raw Blame History