# MORPH
__ ___ __
/ |/ /___ _________ / /_
/ /|_/ / __ \/ ___/ __ \/ __ \
/ / / / /_/ / / / /_/ / / / /
/_/ /_/\____/_/ / .___/_/ /_/
/_/
**AGENT ORCHESTRATION PIPELINE FOR PI**
[](https://npmjs.org/package/@boofpackdev/pi-morph)
[](https://opensource.org/licenses/MIT)
[](#)
---
## 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:** `` 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
```bash
pi install @boofpackdev/pi-morph
```
## CLI CONTROL
### SHORTCUTS
CTRL+M G : Full Guided Pipeline
CTRL+M S : Spark (Idea Refinement)
CTRL+M P : Plan (Architecture)
CTRL+M W : Work (Implementation)
CTRL+M R : Review (Audit)
CTRL+M H : Ship (Release)
### DAEMON COMMANDS
```text
/morph:run 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
```
---
MORPH OPERATIONAL DATA ยท EOF