MORPH

AGENT ORCHESTRATION PIPELINE FOR PI

---

SYNOPSIS

morph is a strict, 5-stage deterministic state machine designed to transform high-level intent into verified software artifacts. It orchestrates specialized agent teams within pi, enforcing strict data handoffs through a centralized Blackboard and a Directed Acyclic Graph (DAG) execution engine.

It utilizes a Hub-and-Spoke consensus model, deterministic git-diff validation, and an exhaustive 10-state Autorecovery Taxonomy to prevent hallucination loops and ensure architectural integrity without operator babysitting.

1. STATE MACHINE & DATA CONTRACTS

The pipeline evolves a "Product Shape" through five strictly enforced Zod schemas. Progression is impossible without a validated state extraction.

PHASE	AGENTS	OUTPUT SCHEMA	DESCRIPTION
SPARK	Visionary, Critic	SparkOutputSchema	Extracts core features, risk parameters, and the exact Deliverable Type.
PLAN	Architect, QA, Efficiency	PlanOutputSchema	Synthesizes Mermaid architecture, Data Models, and the JSON Task DAG.
WORK	Engineer, Peer Reviewer	WorkTaskResultSchema	Executes DAG tasks. Requires strict git-diff validation to pass.
REVIEW	Tech Lead, QA, Perf, User	ReviewOutputSchema	Generates a 1-10 Efficiency Score and a definitive GO / NO-GO verdict.
SHIP	DevOps, Release Consultant	ShipOutputSchema	Computes SEMVER, changelog, and a step-by-step rollback procedure.

2. DAG EXECUTION ENGINE

The Work phase execution is strictly controlled by a DAG Router (src/core/engine.ts).

• Topological Sorting: Tasks are resolved via Kahn's algorithm based on dependsOn arrays. Cycles will throw exceptions and trigger Plan-phase auto-repair.
• Wave Parallelization: Tasks with resolved dependencies are grouped into execution waves and processed in parallel batches (default maxParallel: 3).
• File Target Overlap Detection: Analyzes target files across waves. If concurrent edits to the same file are detected (severity: "high"), the engine applies serializeHighSeverityFileOverlaps to rewrite the DAG, forcing sequential execution to prevent git-patch collisions.
• Truthful Completion Verification: A task is never marked done based on LLM output alone. Morph compares a pre-task and post-task git worktree snapshot. If no file delta is detected, the task fails verification.

3. AUTONOMOUS AUTORECOVERY TAXONOMY

When an execution failure occurs, Morph diagnoses the state and categorizes it into one of 10 taxonomical states (diagnoseRecoveryState). Safe failures are retried automatically; critical failures halt execution and generate markdown incident reports.

• NO_EFFECT: The agent claimed success, but no git-diff was produced. Auto-safe retry.
• TOOL_FAILURE: Internal system exception or subprocess crash. Auto-safe retry.
• CLI_LAUNCH_FAILURE: Node/pi process spawn failure. Halts pipeline.
• AUTH_OR_QUOTA_FAILURE: API limits reached or 401 Unauthorized. Halts pipeline.
• REVIEW_REJECTED: The Peer Reviewer agent rejected the implementation. Feedback is automatically injected into the next Engineer retry attempt. Auto-safe retry.
• REVIEW_FORMAT_INVALID: Reviewer failed to provide a valid APPROVED/REJECTED verdict. Auto-safe retry.
• VERIFICATION_FAILED: File changes were detected, but they did not match the expected targets declared in the Task Node. Auto-safe retry.
• DEPENDENCY_BLOCKED: A parent task failed, recursively blocking all children. The engine will not retry blocked children until the parent is repaired. Halts pipeline.
• TASK_UNDERSPECIFIED: The LLM rejected the task due to fog-of-war. Requires replanning. Halts pipeline.
• STATE_INCONSISTENT: The Blackboard and repository state diverge impossibly (e.g., marked done but zero worktree changes). Auto-safe retry (wipes stale state).

4. HUB-AND-SPOKE CONSENSUS PROTOCOL

To prevent context bloat and hallucination loops, agents do not chat freely. They use a strict hub-and-spoke synthesis model.

• Plan Synthesis: The Lead Architect drafts a DAG. The QA Expert analyzes it for edge cases, and the Efficiency Manager checks for redundant loops. The Architect is then re-invoked to synthesize the feedback into a final JSON array.
• Review Routing: The determineReviewRouting system uses regex heuristics against the codebase diff to determine if the QA Auditor, Performance Guru, or End User agents need to be invoked. The Tech Lead then synthesizes their parallel reports into a final verdict.

5. CENTRALIZED BLACKBOARD & CONSERVATION

• Atomic File Swaps: All context is read/written atomically to .morph/state.json via .tmp file renaming to prevent corruption.
• Fallback JSON Repair: repairPersistedState dynamically fixes malformed states (e.g., truncating bloated array limits from older parsers) instead of destroying the Blackboard.
• Internal Monologue Stripping: <thinking> tokens and chain-of-thought blocks are purged via stripReasoningTokens before state handoffs.
• Context Sliding Window: Deep retry loops aggressively truncate historical context to prevent the window from collapsing during extended debugging sessions.
• Differential Patching: diff.ts invokes git diff --no-index for clean, unified patch blocks. If git fails, it falls back to an internal Longest Common Subsequence (LCS) matrix diff.

6. MISSION CONTROL TUI & BROWSER GATES

• Live TUI Display: Displays pipeline telemetry (PipelineDisplay), execution waves, real-time file-modification activity (FileActivity), and live token ledger costs via @earendil-works/pi-tui.
• Pre-Work Approval Gate: Before implementation begins, Morph generates work-spec.md and work-approval.html, launching a local REST/WebSocket server (localhost:4040/api/approve). The DAG must be explicitly approved via browser or terminal.
• Final Handoff Artifacts: Produces a comprehensive final-report.md / final-report.html detailing the quickstart guide, inferred project root, delivered architecture, and rollback instructions.
• Auto-Scaffolding Protection: Configuration tasks automatically execute git commit -m "morph: auto-commit" so Morph's internal git stash push checkpoints do not accidentally wipe untracked scaffolding logic.

INSTALLATION

pi install @boofpackdev/pi-morph

CLI CONTROL

SHORTCUTS

DAEMON COMMANDS

/morph:run <idea>  Start a new project
/morph:recover     Diagnose and resume from an Autorecovery failure state
/morph:status      Poll Blackboard for phase/token telemetry
/morph:reset       Purge local .morph/ context and kill active agents

---