substrate-ai 0.2.35 → 0.2.38

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-RJ0EHbfM.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-Q-rgJf4a.js"
 );
 								const runStoryFn = async (opts) => {
 									const exitCode = await runPipeline({

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

@@ -1,20 +1,23 @@
 <!-- substrate:start -->
 ## Substrate Pipeline
 
-This project uses Substrate for automated implementation pipelines. Substrate runs are long-running (5–40 minutes). Plan accordingly.
+This project uses Substrate for automated implementation pipelines. **When the user asks you to implement, build, or run the pipeline — go straight to running substrate. Do NOT explore the codebase, read source files, or plan the implementation yourself.** Substrate orchestrates sub-agents that handle all of that.
 
 ### Running the Pipeline
 
-**Preferred — Supervisor mode** (handles stalls, auto-restarts, post-run analysis):
+**Just run it.** Substrate auto-detects which pipeline phase to start from (analysis → planning → solutioning → implementation) and auto-discovers pending stories. You do not need to determine the phase or find story keys manually.
+
 ```
-substrate supervisor --output-format json --stories 7-1,7-2
+substrate supervisor --output-format json
 ```
 
-**Direct mode** (simpler, no auto-recovery):
+To target specific stories (if the user names them):
 ```
-substrate run --events --stories 7-1,7-2
+substrate supervisor --output-format json --stories 1-1,1-2,1-3
 ```
 
+If substrate needs input it can't auto-detect (e.g., a project concept for analysis), it will exit with a clear error message telling you what to provide.
+
 **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.

package/dist/{run-Cd7sfXzo.js → run-Q-rgJf4a.js}

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

package/dist/{run-XNRFAHEx.js → run-RJ0EHbfM.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"]
 */
@@ -9503,6 +9559,83 @@ function sortStoryKeys(keys) {
 	});
 }
 
+//#endregion
+//#region src/modules/phase-orchestrator/phase-detection.ts
+const PHASE_ARTIFACTS = [
+	{
+		phase: "research",
+		type: "research-findings",
+		optional: true
+	},
+	{
+		phase: "analysis",
+		type: "product-brief",
+		optional: false
+	},
+	{
+		phase: "planning",
+		type: "prd",
+		optional: false
+	},
+	{
+		phase: "solutioning",
+		type: "stories",
+		optional: false
+	}
+];
+/**
+* Detect the next phase to run based on DB state.
+*
+* Detection logic:
+* 1. If stories exist (decisions/epics.md) → implementation
+* 2. Walk forward through phases checking for completion artifacts
+* 3. Skip optional phases (research) if no artifact found
+* 4. The first required phase WITHOUT an artifact is where we start
+* 5. If nothing exists → analysis (needs concept)
+*/
+function detectStartPhase(db, projectRoot) {
+	try {
+		const storyKeys = resolveStoryKeys(db, projectRoot);
+		if (storyKeys.length > 0) return {
+			phase: "implementation",
+			reason: `${storyKeys.length} stories ready for implementation`,
+			needsConcept: false
+		};
+	} catch {}
+	let lastCompletedPhase;
+	try {
+		for (const entry of PHASE_ARTIFACTS) {
+			const row = db.prepare("SELECT id FROM artifacts WHERE phase = ? AND type = ? LIMIT 1").get(entry.phase, entry.type);
+			if (row !== void 0) lastCompletedPhase = entry.phase;
+			else if (!entry.optional) {
+				const needsConcept = entry.phase === "analysis";
+				const reason = lastCompletedPhase !== void 0 ? `${lastCompletedPhase} phase complete — continuing with ${entry.phase}` : "No pipeline state found — starting from the beginning";
+				return {
+					phase: entry.phase,
+					needsConcept,
+					reason
+				};
+			}
+		}
+	} catch {
+		return {
+			phase: "analysis",
+			reason: "No pipeline state found — starting from the beginning",
+			needsConcept: true
+		};
+	}
+	if (lastCompletedPhase !== void 0) return {
+		phase: "solutioning",
+		reason: "All phases completed but no stories found — re-running solutioning",
+		needsConcept: false
+	};
+	return {
+		phase: "analysis",
+		reason: "No pipeline state found — starting from the beginning",
+		needsConcept: true
+	};
+}
+
 //#endregion
 //#region src/modules/phase-orchestrator/built-in-phases.ts
 function logPhase(message) {
@@ -12341,7 +12474,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 +12829,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,18 +13627,54 @@ async function runRunAction(options) {
 	} catch {
 		logger.debug("Config loading skipped — using default token ceilings");
 	}
-	if (startPhase !== void 0) return runFullPipeline({
+	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;
+		}
+	}
+	let effectiveStartPhase = startPhase;
+	if (effectiveStartPhase === void 0) {
+		mkdirSync(dbDir, { recursive: true });
+		try {
+			const detectDb = new DatabaseWrapper(dbPath);
+			try {
+				detectDb.open();
+				runMigrations(detectDb.db);
+				const detection = detectStartPhase(detectDb.db, projectRoot);
+				if (detection.phase !== "implementation") {
+					effectiveStartPhase = detection.phase;
+					if (outputFormat === "human") process.stdout.write(`[AUTO-DETECT] ${detection.reason}\n`);
+					if (detection.needsConcept && concept === void 0) {
+						const errorMsg = `Pipeline needs to start from ${detection.phase} phase, which requires a concept.\nProvide --concept "your idea" or --concept-file path/to/brief.md`;
+						if (outputFormat === "json") process.stdout.write(formatOutput(null, "json", false, errorMsg) + "\n");
+						else process.stderr.write(`Error: ${errorMsg}\n`);
+						detectDb.close();
+						return 1;
+					}
+				} else if (outputFormat === "human") process.stdout.write(`[AUTO-DETECT] ${detection.reason}\n`);
+			} finally {
+				detectDb.close();
+			}
+		} catch {}
+	}
+	if (effectiveStartPhase !== void 0) return runFullPipeline({
 		packName,
 		packPath,
 		dbDir,
 		dbPath,
-		startPhase,
+		startPhase: effectiveStartPhase,
 		stopAfter,
 		concept,
 		concurrency,
 		outputFormat,
 		projectRoot,
 		tokenCeilings,
+		...parsedStoryKeys.length > 0 ? { stories: parsedStoryKeys } : {},
 		...eventsFlag === true ? { events: true } : {},
 		...skipUx === true ? { skipUx: true } : {},
 		...researchFlag === true ? { research: true } : {},
@@ -13513,16 +13682,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 +14189,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 +14427,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 +14532,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-RJ0EHbfM.js.map

package/package.json

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