substrate-ai 0.2.33 → 0.2.35

package/dist/cli/templates/claude-md-substrate-section.md

@@ -1,22 +1,63 @@
 <!-- substrate:start -->
 ## Substrate Pipeline
 
-This project uses Substrate for automated implementation pipelines.
-
-### Quick Start
-- Run `substrate run --help-agent` to get full pipeline interaction instructions
-- Run `substrate run --events` to execute the pipeline with structured event output
-- Run `substrate run --events --stories 7-1,7-2` to run specific stories
-
-### Monitoring Pipeline Runs
-- **DO NOT use `Task Output` to monitor substrate** — Claude Code task IDs do not map to substrate's internal processes
-- Monitor progress with: `substrate status --output-format json`
-- For real-time output: redirect stdout to a file, then tail it: `substrate run --events > /tmp/substrate-out.log 2>&1 &` then `tail -f /tmp/substrate-out.log`
-- Check pipeline health: `substrate health --output-format json`
-
-### Agent Behavior
-- On story escalation: read the flagged files and issues, propose a fix, ask the user before applying
-- On minor fix verdict: offer to fix automatically
-- Never re-run a failed story without explicit user confirmation
-- After pipeline completion: summarize results conversationally (X succeeded, Y failed, Z need attention)
+This project uses Substrate for automated implementation pipelines. Substrate runs are long-running (5–40 minutes). Plan accordingly.
+
+### Running the Pipeline
+
+**Preferred — Supervisor mode** (handles stalls, auto-restarts, post-run analysis):
+```
+substrate supervisor --output-format json --stories 7-1,7-2
+```
+
+**Direct mode** (simpler, no auto-recovery):
+```
+substrate run --events --stories 7-1,7-2
+```
+
+**CRITICAL execution rules:**
+- Pipeline runs take **5–40 minutes**. You MUST use `run_in_background: true` or `timeout: 600000` (10 min) when invoking via Bash tool. Default 2-minute timeout WILL kill the pipeline.
+- **NEVER pipe substrate output** to `head`, `tail`, `grep`, or any command that may close the pipe early — this causes EPIPE stalls that hang the process.
+- **DO NOT use `Task Output`** to monitor substrate — Claude Code task IDs do not map to substrate's internal processes.
+- For full event protocol and command reference: `substrate run --help-agent`
+
+### Monitoring (while pipeline is running)
+
+Poll status periodically (every 60–90s):
+```
+substrate status --output-format json
+```
+
+Check process health if pipeline seems quiet:
+```
+substrate health --output-format json
+```
+
+**Interpreting silence:** No output for 5 minutes = normal (agent is working). No output for 15+ minutes = likely stalled. Use `substrate health` to confirm, then consider killing and resuming.
+
+### After Pipeline Completes
+
+1. **Summarize results** conversationally: X succeeded, Y failed, Z escalated
+2. **Check metrics**: `substrate metrics --output-format json`
+3. **Read analysis** (if supervisor mode): `substrate metrics --analysis <run_id> --output-format json`
+
+### Handling Escalations and Failures
+
+- **On story escalation**: read the flagged files and issues listed in the escalation event, propose a fix, ask the user before applying
+- **On minor fix verdict** (`NEEDS_MINOR_FIXES`): offer to fix automatically
+- **On build verification failure**: read the build output, diagnose the compiler error, propose a fix
+- **On contract mismatch** (`pipeline:contract-mismatch`): cross-story interface conflict — read both stories' files, reconcile types manually
+- **Never re-run a failed story** without explicit user confirmation
+
+### Key Commands Reference
+
+| Command | Purpose |
+|---|---|
+| `substrate run --events` | Run pipeline with NDJSON event stream |
+| `substrate supervisor --output-format json` | Run with auto-recovery and analysis |
+| `substrate status --output-format json` | Poll current pipeline state |
+| `substrate health --output-format json` | Check process health and stall detection |
+| `substrate metrics --output-format json` | View historical run metrics |
+| `substrate resume` | Resume an interrupted pipeline run |
+| `substrate run --help-agent` | Full agent instruction reference (487 lines) |
 <!-- substrate:end -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "substrate-ai",
-  "version": "0.2.33",
+  "version": "0.2.35",
   "description": "Substrate — multi-agent orchestration daemon for AI coding agents",
   "type": "module",
   "license": "MIT",
@@ -46,7 +46,7 @@
     "build": "tsdown",
     "postbuild": "cp -r src/cli/templates dist/cli/templates",
     "dev": "tsx watch src/cli/index.ts",
-    "test": "flock -n -E 75 /tmp/substrate-test.lock vitest run --coverage || { ec=$?; if [ $ec -eq 75 ]; then echo '⚠ Test suite already running — wait or kill the other process'; fi; exit $ec; }",
+    "test": "vitest run --coverage",
     "test:fast": "vitest run --exclude 'src/__tests__/e2e/**' --exclude '**/*integration*' --exclude '**/*e2e*'",
     "test:changed": "vitest run --changed",
     "test:watch": "vitest",