substrate-ai 0.2.34 → 0.2.36

package/dist/cli/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { DEFAULT_CONFIG, DEFAULT_ROUTING_POLICY, DatabaseWrapper, SUBSTRATE_OWNED_SETTINGS_KEYS, VALID_PHASES, buildPipelineStatusOutput, createConfigSystem, createContextCompiler, createDispatcher, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, findPackageRoot, formatOutput, formatPhaseCompletionSummary, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getAllDescendantPids, getAutoHealthData, getSubstrateDefaultSettings, parseDbTimestampAsUtc, registerHealthCommand, registerRunCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion, resolveMainRepoRoot, runAnalysisPhase, runMigrations, runPlanningPhase, runSolutioningPhase, validateStopAfterFromConflict } from "../run-XNRFAHEx.js";
+import { DEFAULT_CONFIG, DEFAULT_ROUTING_POLICY, DatabaseWrapper, SUBSTRATE_OWNED_SETTINGS_KEYS, VALID_PHASES, buildPipelineStatusOutput, createConfigSystem, createContextCompiler, createDispatcher, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, findPackageRoot, formatOutput, formatPhaseCompletionSummary, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getAllDescendantPids, getAutoHealthData, getSubstrateDefaultSettings, parseDbTimestampAsUtc, registerHealthCommand, registerRunCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion, resolveMainRepoRoot, resolveStoryKeys, runAnalysisPhase, runMigrations, runPlanningPhase, runSolutioningPhase, validateStopAfterFromConflict } from "../run-B9OkdDIk.js";
 import { createLogger } from "../logger-D2fS2ccL.js";
 import { AdapterRegistry } from "../adapter-registry-PsWhP_1Q.js";
 import { CURRENT_CONFIG_FORMAT_VERSION, CURRENT_TASK_GRAPH_VERSION, PartialSubstrateConfigSchema } from "../config-migrator-DSi8KhQC.js";
@@ -1201,12 +1201,8 @@ async function runFullPipelineFromPhase(options) {
 						logger$14.warn({ err }, "Failed to record token usage");
 					}
 				});
-				const storyDecisions = db.prepare(`SELECT description FROM requirements WHERE pipeline_run_id = ? AND source = 'solutioning-phase'`).all(runId);
-				const storyKeys = [];
-				for (const req of storyDecisions) {
-					const keyMatch = /^(\d+-\d+):/.exec(req.description);
-					if (keyMatch) storyKeys.push(keyMatch[1]);
-				}
+				const storyKeys = resolveStoryKeys(db, projectRoot, { pipelineRunId: runId });
+				if (storyKeys.length === 0 && outputFormat === "human") process.stdout.write("[IMPLEMENTATION] No stories found for this run. Check solutioning phase output.\n");
 				await orchestrator.run(storyKeys);
 				if (outputFormat === "human") process.stdout.write("[IMPLEMENTATION] Complete\n");
 			}
@@ -2585,7 +2581,7 @@ async function runSupervisorAction(options, deps = {}) {
 								const expDb = expDbWrapper.db;
 								const { runRunAction: runPipeline } = await import(
 									/* @vite-ignore */
-									"../run-Cd7sfXzo.js"
+									"../run-LStYIzcb.js"
 );
 								const runStoryFn = async (opts) => {
 									const exitCode = await runPipeline({

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/dist/{run-XNRFAHEx.js → run-B9OkdDIk.js}

@@ -9404,6 +9404,44 @@ function createImplementationOrchestrator(deps) {
 //#endregion
 //#region src/modules/implementation-orchestrator/story-discovery.ts
 /**
+* Unified story key resolution with a 4-level fallback chain.
+*
+* 1. Explicit keys (from --stories flag) — returned as-is
+* 2. Decisions table (category='stories', phase='solutioning')
+* 3. Epic shard decisions (category='epic-shard') — parsed with parseStoryKeysFromEpics
+* 4. epics.md file on disk (via discoverPendingStoryKeys)
+*
+* Optionally filters out completed stories when filterCompleted is set.
+*
+* @returns Sorted, deduplicated array of story keys in "N-M" format
+*/
+function resolveStoryKeys(db, projectRoot, opts) {
+	if (opts?.explicit !== void 0 && opts.explicit.length > 0) return opts.explicit;
+	let keys = [];
+	try {
+		const query = opts?.pipelineRunId !== void 0 ? `SELECT key FROM decisions WHERE phase = 'solutioning' AND category = 'stories' AND pipeline_run_id = ? ORDER BY created_at ASC` : `SELECT key FROM decisions WHERE phase = 'solutioning' AND category = 'stories' ORDER BY created_at ASC`;
+		const params = opts?.pipelineRunId !== void 0 ? [opts.pipelineRunId] : [];
+		const rows = db.prepare(query).all(...params);
+		for (const row of rows) if (/^\d+-\d+/.test(row.key)) {
+			const match = /^(\d+-\d+)/.exec(row.key);
+			if (match !== null) keys.push(match[1]);
+		}
+	} catch {}
+	if (keys.length === 0) try {
+		const query = opts?.pipelineRunId !== void 0 ? `SELECT value FROM decisions WHERE category = 'epic-shard' AND pipeline_run_id = ? ORDER BY created_at ASC` : `SELECT value FROM decisions WHERE category = 'epic-shard' ORDER BY created_at ASC`;
+		const params = opts?.pipelineRunId !== void 0 ? [opts.pipelineRunId] : [];
+		const shardRows = db.prepare(query).all(...params);
+		const allContent = shardRows.map((r) => r.value).join("\n");
+		if (allContent.length > 0) keys = parseStoryKeysFromEpics(allContent);
+	} catch {}
+	if (keys.length === 0) keys = discoverPendingStoryKeys(projectRoot);
+	if (opts?.filterCompleted === true && keys.length > 0) {
+		const completedKeys = getCompletedStoryKeys(db);
+		keys = keys.filter((k) => !completedKeys.has(k));
+	}
+	return sortStoryKeys([...new Set(keys)]);
+}
+/**
 * Extract all story keys (N-M format) from epics.md content.
 *
 * Supports three extraction patterns found in real epics.md files:
@@ -9490,6 +9528,24 @@ function collectExistingStoryKeys(projectRoot) {
 	return existing;
 }
 /**
+* Collect story keys already completed in previous pipeline runs.
+* Scans pipeline_runs with status='completed' and extracts story keys
+* with phase='COMPLETE' from their token_usage_json state.
+*/
+function getCompletedStoryKeys(db) {
+	const completed = new Set();
+	try {
+		const rows = db.prepare(`SELECT token_usage_json FROM pipeline_runs WHERE status = 'completed' AND token_usage_json IS NOT NULL`).all();
+		for (const row of rows) try {
+			const state = JSON.parse(row.token_usage_json);
+			if (state.stories !== void 0) {
+				for (const [key, s] of Object.entries(state.stories)) if (s.phase === "COMPLETE") completed.add(key);
+			}
+		} catch {}
+	} catch {}
+	return completed;
+}
+/**
 * Sort story keys numerically by epic number (primary) then story number (secondary).
 * E.g. ["10-1", "1-2", "2-1"] → ["1-2", "2-1", "10-1"]
 */
@@ -12341,7 +12397,7 @@ async function runStoryGeneration(deps, params, gapAnalysis) {
 		pipeline_run_id: runId,
 		source: "solutioning-phase",
 		type: "functional",
-		description: `${story.title}: ${story.description}`,
+		description: `${story.key}: ${story.title}: ${story.description}`,
 		priority: story.priority
 	});
 	const totalStories = epics.reduce((sum, epic) => sum + epic.stories.length, 0);
@@ -12696,7 +12752,7 @@ async function runStoryGenerationMultiStep(deps, params) {
 		pipeline_run_id: params.runId,
 		source: "solutioning-phase",
 		type: "functional",
-		description: `${story.title}: ${story.description}`,
+		description: `${story.key}: ${story.title}: ${story.description}`,
 		priority: story.priority
 	});
 	const artifactId = storyStep?.artifactId ?? "";
@@ -13494,6 +13550,16 @@ async function runRunAction(options) {
 	} catch {
 		logger.debug("Config loading skipped — using default token ceilings");
 	}
+	let parsedStoryKeys = [];
+	if (storiesArg !== void 0 && storiesArg !== "") {
+		parsedStoryKeys = storiesArg.split(",").map((k) => k.trim()).filter((k) => k.length > 0);
+		for (const key of parsedStoryKeys) if (!validateStoryKey(key)) {
+			const errorMsg = `Story key '${key}' is not a valid format. Expected: <epic>-<story> (e.g., 10-1)`;
+			if (outputFormat === "json") process.stdout.write(formatOutput(null, "json", false, errorMsg) + "\n");
+			else process.stderr.write(`Error: ${errorMsg}\n`);
+			return 1;
+		}
+	}
 	if (startPhase !== void 0) return runFullPipeline({
 		packName,
 		packPath,
@@ -13506,6 +13572,7 @@ async function runRunAction(options) {
 		outputFormat,
 		projectRoot,
 		tokenCeilings,
+		...parsedStoryKeys.length > 0 ? { stories: parsedStoryKeys } : {},
 		...eventsFlag === true ? { events: true } : {},
 		...skipUx === true ? { skipUx: true } : {},
 		...researchFlag === true ? { research: true } : {},
@@ -13513,16 +13580,7 @@ async function runRunAction(options) {
 		...skipPreflight === true ? { skipPreflight: true } : {},
 		...injectedRegistry !== void 0 ? { registry: injectedRegistry } : {}
 	});
-	let storyKeys = [];
-	if (storiesArg !== void 0 && storiesArg !== "") {
-		storyKeys = storiesArg.split(",").map((k) => k.trim()).filter((k) => k.length > 0);
-		for (const key of storyKeys) if (!validateStoryKey(key)) {
-			const errorMsg = `Story key '${key}' is not a valid format. Expected: <epic>-<story> (e.g., 10-1)`;
-			if (outputFormat === "json") process.stdout.write(formatOutput(null, "json", false, errorMsg) + "\n");
-			else process.stderr.write(`Error: ${errorMsg}\n`);
-			return 1;
-		}
-	}
+	let storyKeys = [...parsedStoryKeys];
 	if (!existsSync(dbDir)) mkdirSync(dbDir, { recursive: true });
 	const dbWrapper = new DatabaseWrapper(dbPath);
 	try {
@@ -14029,7 +14087,7 @@ async function runRunAction(options) {
 	}
 }
 async function runFullPipeline(options) {
-	const { packName, packPath, dbDir, dbPath, startPhase, stopAfter, concept, concurrency, outputFormat, projectRoot, events: eventsFlag, skipUx, research: researchFlag, skipResearch: skipResearchFlag, skipPreflight, registry: injectedRegistry, tokenCeilings } = options;
+	const { packName, packPath, dbDir, dbPath, startPhase, stopAfter, concept, concurrency, outputFormat, projectRoot, events: eventsFlag, skipUx, research: researchFlag, skipResearch: skipResearchFlag, skipPreflight, registry: injectedRegistry, tokenCeilings, stories: explicitStories } = options;
 	if (!existsSync(dbDir)) mkdirSync(dbDir, { recursive: true });
 	const dbWrapper = new DatabaseWrapper(dbPath);
 	try {
@@ -14267,12 +14325,8 @@ async function runFullPipeline(options) {
 						process.stdout.write(`  [ESCALATED] ${payload.storyKey}: ${payload.lastVerdict}\n`);
 					});
 				}
-				const storyDecisions = db.prepare(`SELECT description FROM requirements WHERE status = 'active' AND source = 'solutioning-phase'`).all();
-				const storyKeys = [];
-				for (const req of storyDecisions) {
-					const keyMatch = /^(\d+-\d+):/.exec(req.description);
-					if (keyMatch) storyKeys.push(keyMatch[1]);
-				}
+				const storyKeys = resolveStoryKeys(db, projectRoot, { explicit: explicitStories });
+				if (storyKeys.length === 0 && outputFormat === "human") process.stdout.write("[IMPLEMENTATION] No stories found. Run solutioning first or pass --stories.\n");
 				if (outputFormat === "human") process.stdout.write(`[IMPLEMENTATION] Starting ${storyKeys.length} stories with concurrency=${concurrency}\n`);
 				await orchestrator.run(storyKeys);
 				if (outputFormat === "human") process.stdout.write("[IMPLEMENTATION] Complete\n");
@@ -14376,5 +14430,5 @@ function registerRunCommand(program, _version = "0.0.0", projectRoot = process.c
 }
 
 //#endregion
-export { DEFAULT_CONFIG, DEFAULT_ROUTING_POLICY, DatabaseWrapper, SUBSTRATE_OWNED_SETTINGS_KEYS, VALID_PHASES, buildPipelineStatusOutput, createConfigSystem, createContextCompiler, createDispatcher, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, findPackageRoot, formatOutput, formatPhaseCompletionSummary, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getAllDescendantPids, getAutoHealthData, getSubstrateDefaultSettings, parseDbTimestampAsUtc, registerHealthCommand, registerRunCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion, resolveMainRepoRoot, runAnalysisPhase, runMigrations, runPlanningPhase, runRunAction, runSolutioningPhase, validateStopAfterFromConflict };
-//# sourceMappingURL=run-XNRFAHEx.js.map
+export { DEFAULT_CONFIG, DEFAULT_ROUTING_POLICY, DatabaseWrapper, SUBSTRATE_OWNED_SETTINGS_KEYS, VALID_PHASES, buildPipelineStatusOutput, createConfigSystem, createContextCompiler, createDispatcher, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, findPackageRoot, formatOutput, formatPhaseCompletionSummary, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getAllDescendantPids, getAutoHealthData, getSubstrateDefaultSettings, parseDbTimestampAsUtc, registerHealthCommand, registerRunCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion, resolveMainRepoRoot, resolveStoryKeys, runAnalysisPhase, runMigrations, runPlanningPhase, runRunAction, runSolutioningPhase, validateStopAfterFromConflict };
+//# sourceMappingURL=run-B9OkdDIk.js.map

package/dist/{run-Cd7sfXzo.js → run-LStYIzcb.js}

@@ -1,4 +1,4 @@
-import { registerRunCommand, runRunAction } from "./run-XNRFAHEx.js";
+import { registerRunCommand, runRunAction } from "./run-B9OkdDIk.js";
 import "./logger-D2fS2ccL.js";
 import "./config-migrator-DSi8KhQC.js";
 import "./helpers-RL22dYtn.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "substrate-ai",
-  "version": "0.2.34",
+  "version": "0.2.36",
   "description": "Substrate — multi-agent orchestration daemon for AI coding agents",
   "type": "module",
   "license": "MIT",