substrate-ai 0.5.0 → 0.5.2

package/dist/cli/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { AdapterTelemetryPersistence, AppError, DEFAULT_CONFIG, DEFAULT_ROUTING_POLICY, DoltClient, DoltNotInstalled, DoltRepoMapMetaRepository, DoltSymbolRepository, ERR_REPO_MAP_STORAGE_WRITE, FileStateStore, GitClient, GrammarLoader, IngestionServer, RepoMapInjector, RepoMapModule, RepoMapQueryEngine, RepoMapStorage, SUBSTRATE_OWNED_SETTINGS_KEYS, SymbolParser, VALID_PHASES, buildPipelineStatusOutput, checkDoltInstalled, createConfigSystem, createContextCompiler, createDatabaseAdapter, createDispatcher, createDoltClient, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStateStore, createStopAfterGate, findPackageRoot, formatOutput, formatPhaseCompletionSummary, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getAllDescendantPids, getAutoHealthData, getSubstrateDefaultSettings, initSchema, initializeDolt, isSyncAdapter, parseDbTimestampAsUtc, registerHealthCommand, registerRunCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion, resolveMainRepoRoot, resolveStoryKeys, runAnalysisPhase, runPlanningPhase, runSolutioningPhase, validateStopAfterFromConflict } from "../run-GqmIa5YW.js";
+import { AdapterTelemetryPersistence, AppError, DEFAULT_CONFIG, DEFAULT_ROUTING_POLICY, DoltClient, DoltNotInstalled, DoltRepoMapMetaRepository, DoltSymbolRepository, ERR_REPO_MAP_STORAGE_WRITE, FileStateStore, GitClient, GrammarLoader, IngestionServer, RepoMapInjector, RepoMapModule, RepoMapQueryEngine, RepoMapStorage, SUBSTRATE_OWNED_SETTINGS_KEYS, SymbolParser, VALID_PHASES, WorkGraphRepository, buildPipelineStatusOutput, checkDoltInstalled, createConfigSystem, createContextCompiler, createDatabaseAdapter, createDispatcher, createDoltClient, createEventEmitter, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStateStore, createStopAfterGate, detectCycles, findPackageRoot, formatOutput, formatPhaseCompletionSummary, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getAllDescendantPids, getAutoHealthData, getSubstrateDefaultSettings, initSchema, initializeDolt, isSyncAdapter, parseDbTimestampAsUtc, registerHealthCommand, registerRunCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion, resolveMainRepoRoot, resolveStoryKeys, runAnalysisPhase, runPlanningPhase, runSolutioningPhase, validateStopAfterFromConflict } from "../run-CxoTrYdA.js";
 import { createLogger } from "../logger-D2fS2ccL.js";
 import { AdapterRegistry } from "../adapter-registry-BkUvZSKJ.js";
 import { CURRENT_CONFIG_FORMAT_VERSION, CURRENT_TASK_GRAPH_VERSION, PartialSubstrateConfigSchema } from "../config-migrator-DtZW1maj.js";
@@ -19,7 +19,7 @@ import yaml from "js-yaml";
 import { createRequire } from "node:module";
 import * as path$1 from "node:path";
 import { isAbsolute, join as join$1 } from "node:path";
-import { existsSync as existsSync$1, mkdirSync as mkdirSync$1, writeFileSync as writeFileSync$1 } from "node:fs";
+import { existsSync as existsSync$1, mkdirSync as mkdirSync$1, readFileSync as readFileSync$1, writeFileSync as writeFileSync$1 } from "node:fs";
 import { access as access$1, readFile as readFile$1 } from "node:fs/promises";
 import { createInterface } from "node:readline";
 import { homedir } from "os";
@@ -574,8 +574,8 @@ async function directoryExists(path$2) {
 */
 async function runInitAction(options) {
 	const { pack: packName, projectRoot, outputFormat, force = false, yes: nonInteractive = false } = options;
-	const packPath = join(projectRoot, "packs", packName);
 	const dbRoot = await resolveMainRepoRoot(projectRoot);
+	const packPath = join(dbRoot, "packs", packName);
 	const substrateDir = join(dbRoot, ".substrate");
 	const dbPath = join(substrateDir, "substrate.db");
 	const configPath = join(substrateDir, "config.yaml");
@@ -1004,19 +1004,52 @@ function registerConfigCommand(program, _version) {
 	});
 }
 
+//#endregion
+//#region src/modules/work-graph/errors.ts
+/**
+* Work-graph error types.
+*
+* Story 31-7: Cycle Detection in Work Graph
+*/
+/**
+* Thrown by `EpicIngester.ingest()` when the provided dependency list
+* contains a cycle.  The `cycle` field contains the path of story keys
+* that form the cycle (first and last element are the same).
+*/
+var CyclicDependencyError = class extends Error {
+	constructor(cycle) {
+		super(`Cyclic dependency detected: ${cycle.join(" → ")}`);
+		this.cycle = cycle;
+		this.name = "CyclicDependencyError";
+	}
+};
+
 //#endregion
 //#region src/cli/commands/resume.ts
 const logger$16 = createLogger("resume-cmd");
+/**
+* Map internal orchestrator phase names to pipeline event protocol phase names.
+*/
+function mapInternalPhaseToEventPhase(internalPhase) {
+	switch (internalPhase) {
+		case "IN_STORY_CREATION": return "create-story";
+		case "IN_DEV": return "dev-story";
+		case "IN_REVIEW": return "code-review";
+		case "IN_MINOR_FIX":
+		case "IN_MAJOR_FIX": return "fix";
+		default: return null;
+	}
+}
 async function runResumeAction(options) {
-	const { runId: specifiedRunId, stopAfter, outputFormat, projectRoot, concurrency, pack: packName, registry } = options;
+	const { runId: specifiedRunId, stopAfter, outputFormat, projectRoot, concurrency, pack: packName, events: eventsFlag, registry } = options;
 	if (stopAfter !== void 0 && !VALID_PHASES.includes(stopAfter)) {
 		const errorMsg = `Invalid phase: "${stopAfter}". Valid phases: ${VALID_PHASES.join(", ")}`;
 		if (outputFormat === "json") process.stdout.write(formatOutput(null, "json", false, errorMsg) + "\n");
 		else process.stderr.write(`Error: ${errorMsg}\n`);
 		return 1;
 	}
-	const packPath = join(projectRoot, "packs", packName);
 	const dbRoot = await resolveMainRepoRoot(projectRoot);
+	const packPath = join(dbRoot, "packs", packName);
 	const dbPath = join(dbRoot, ".substrate", "substrate.db");
 	const doltDir = join(dbRoot, ".substrate", "state", ".dolt");
 	if (!existsSync(dbPath) && !existsSync(doltDir)) {
@@ -1086,6 +1119,7 @@ async function runResumeAction(options) {
 			concept,
 			concurrency,
 			outputFormat,
+			events: eventsFlag,
 			existingRunId: runId,
 			projectRoot,
 			registry
@@ -1103,7 +1137,7 @@ async function runResumeAction(options) {
 	}
 }
 async function runFullPipelineFromPhase(options) {
-	const { packName, packPath, dbDir, dbPath, startPhase, stopAfter, concept, concurrency, outputFormat, existingRunId, projectRoot, registry: injectedRegistry } = options;
+	const { packName, packPath, dbDir, dbPath, startPhase, stopAfter, concept, concurrency, outputFormat, events: eventsFlag, existingRunId, projectRoot, registry: injectedRegistry } = options;
 	if (!existsSync(dbDir)) mkdirSync(dbDir, { recursive: true });
 	const adapter = createDatabaseAdapter({
 		backend: "auto",
@@ -1143,6 +1177,8 @@ async function runFullPipelineFromPhase(options) {
 		let runId;
 		if (existingRunId !== void 0) runId = existingRunId;
 		else runId = await phaseOrchestrator.startRun(concept, startPhase);
+		let ndjsonEmitter;
+		if (eventsFlag === true) ndjsonEmitter = createEventEmitter(process.stdout);
 		const phaseOrder = [
 			"analysis",
 			"planning",
@@ -1239,12 +1275,87 @@ async function runFullPipelineFromPhase(options) {
 					config: {
 						maxConcurrency: concurrency,
 						maxReviewCycles: 2,
-						pipelineRunId: runId
+						pipelineRunId: runId,
+						enableHeartbeat: eventsFlag === true
 					},
 					projectRoot,
 					...ingestionServer !== void 0 ? { ingestionServer } : {},
 					...telemetryPersistence !== void 0 ? { telemetryPersistence } : {}
 				});
+				if (ndjsonEmitter !== void 0) {
+					const resolvedKeys = await resolveStoryKeys(adapter, projectRoot, { pipelineRunId: runId });
+					ndjsonEmitter.emit({
+						type: "pipeline:start",
+						ts: new Date().toISOString(),
+						run_id: runId,
+						stories: resolvedKeys,
+						concurrency
+					});
+					eventBus.on("orchestrator:story-phase-start", (payload) => {
+						const phase = mapInternalPhaseToEventPhase(payload.phase);
+						if (phase !== null) ndjsonEmitter.emit({
+							type: "story:phase",
+							ts: new Date().toISOString(),
+							key: payload.storyKey,
+							phase,
+							status: "in_progress"
+						});
+					});
+					eventBus.on("orchestrator:story-phase-complete", (payload) => {
+						const phase = mapInternalPhaseToEventPhase(payload.phase);
+						if (phase !== null) {
+							const result = payload.result;
+							ndjsonEmitter.emit({
+								type: "story:phase",
+								ts: new Date().toISOString(),
+								key: payload.storyKey,
+								phase,
+								status: "complete",
+								...phase === "code-review" && result?.verdict !== void 0 ? { verdict: result.verdict } : {},
+								...phase === "create-story" && result?.story_file !== void 0 ? { file: result.story_file } : {}
+							});
+						}
+					});
+					eventBus.on("orchestrator:story-complete", (payload) => {
+						ndjsonEmitter.emit({
+							type: "story:done",
+							ts: new Date().toISOString(),
+							key: payload.storyKey,
+							result: "success",
+							review_cycles: payload.reviewCycles
+						});
+					});
+					eventBus.on("orchestrator:story-escalated", (payload) => {
+						const rawIssues = Array.isArray(payload.issues) ? payload.issues : [];
+						const issues = rawIssues.map((issue) => {
+							const iss = issue;
+							return {
+								severity: iss.severity ?? "unknown",
+								file: iss.file ?? "",
+								desc: iss.desc ?? iss.description ?? ""
+							};
+						});
+						ndjsonEmitter.emit({
+							type: "story:escalation",
+							ts: new Date().toISOString(),
+							key: payload.storyKey,
+							reason: payload.lastVerdict ?? "escalated",
+							cycles: payload.reviewCycles ?? 0,
+							issues,
+							...payload.diagnosis !== void 0 ? { diagnosis: payload.diagnosis } : {}
+						});
+					});
+					eventBus.on("orchestrator:heartbeat", (payload) => {
+						ndjsonEmitter.emit({
+							type: "pipeline:heartbeat",
+							ts: new Date().toISOString(),
+							run_id: payload.runId,
+							active_dispatches: payload.activeDispatches,
+							completed_dispatches: payload.completedDispatches,
+							queued_dispatches: payload.queuedDispatches
+						});
+					});
+				}
 				eventBus.on("orchestrator:story-phase-complete", (payload) => {
 					try {
 						const result = payload.result;
@@ -1268,6 +1379,13 @@ async function runFullPipelineFromPhase(options) {
 				const storyKeys = await resolveStoryKeys(adapter, 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 (ndjsonEmitter !== void 0) ndjsonEmitter.emit({
+					type: "pipeline:complete",
+					ts: new Date().toISOString(),
+					succeeded: storyKeys,
+					failed: [],
+					escalated: []
+				});
 				if (outputFormat === "human") process.stdout.write("[IMPLEMENTATION] Complete\n");
 			}
 			if (stopAfter !== void 0 && currentPhase === stopAfter) {
@@ -1330,7 +1448,7 @@ async function runFullPipelineFromPhase(options) {
 	}
 }
 function registerResumeCommand(program, _version = "0.0.0", projectRoot = process.cwd(), registry) {
-	program.command("resume").description("Resume a previously interrupted pipeline run").option("--run-id <id>", "Pipeline run ID to resume (defaults to latest)").option("--pack <name>", "Methodology pack name", "bmad").option("--stop-after <phase>", "Stop pipeline after this phase completes (overrides saved state)").option("--concurrency <n>", "Maximum parallel conflict groups", (v) => parseInt(v, 10), 3).option("--project-root <path>", "Project root directory", projectRoot).option("--output-format <format>", "Output format: human (default) or json", "human").action(async (opts) => {
+	program.command("resume").description("Resume a previously interrupted pipeline run").option("--run-id <id>", "Pipeline run ID to resume (defaults to latest)").option("--pack <name>", "Methodology pack name", "bmad").option("--stop-after <phase>", "Stop pipeline after this phase completes (overrides saved state)").option("--concurrency <n>", "Maximum parallel conflict groups", (v) => parseInt(v, 10), 3).option("--project-root <path>", "Project root directory", projectRoot).option("--output-format <format>", "Output format: human (default) or json", "human").option("--events", "Emit structured NDJSON events on stdout for programmatic consumption").action(async (opts) => {
 		const outputFormat = opts.outputFormat === "json" ? "json" : "human";
 		const exitCode = await runResumeAction({
 			runId: opts.runId,
@@ -1339,6 +1457,7 @@ function registerResumeCommand(program, _version = "0.0.0", projectRoot = proces
 			projectRoot: opts.projectRoot,
 			concurrency: opts.concurrency,
 			pack: opts.pack,
+			events: opts.events,
 			registry
 		});
 		process.exitCode = exitCode;
@@ -1390,6 +1509,44 @@ async function runStatusAction(options) {
 	});
 	try {
 		await initSchema(adapter);
+		let workGraph;
+		try {
+			const wgRepo = new WorkGraphRepository(adapter);
+			const allStories = await adapter.query(`SELECT story_key, title, status FROM wg_stories`);
+			if (allStories.length > 0) {
+				const readyStoriesRaw = await wgRepo.getReadyStories();
+				const blockedStoriesRaw = await wgRepo.getBlockedStories();
+				const readyKeys = new Set(readyStoriesRaw.map((s) => s.story_key));
+				const blockedKeys = new Set(blockedStoriesRaw.map((b) => b.story.story_key));
+				const inProgressCount = allStories.filter((s) => s.status === "in_progress").length;
+				const completeCount = allStories.filter((s) => s.status === "complete").length;
+				const escalatedCount = allStories.filter((s) => s.status === "escalated").length;
+				workGraph = {
+					summary: {
+						ready: readyKeys.size,
+						blocked: blockedKeys.size,
+						inProgress: inProgressCount,
+						complete: completeCount,
+						escalated: escalatedCount
+					},
+					readyStories: readyStoriesRaw.map((s) => ({
+						key: s.story_key,
+						title: s.title ?? s.story_key
+					})),
+					blockedStories: blockedStoriesRaw.map((b) => ({
+						key: b.story.story_key,
+						title: b.story.title ?? b.story.story_key,
+						blockers: b.blockers.map((bl) => ({
+							key: bl.key,
+							title: bl.title,
+							status: bl.status
+						}))
+					}))
+				};
+			}
+		} catch (err) {
+			logger$15.debug({ err }, "Work graph query failed, continuing without work graph data");
+		}
 		let run;
 		if (runId !== void 0 && runId !== "") run = await getPipelineRunById(adapter, runId);
 		else run = await getLatestRun(adapter);
@@ -1457,7 +1614,8 @@ async function runStatusAction(options) {
 					stories_per_hour: storiesPerHour,
 					cost_usd: totalCostUsd
 				},
-				story_states: storeStories
+				story_states: storeStories,
+				workGraph: workGraph ?? null
 			};
 			process.stdout.write(formatOutput(enhancedOutput, "json", true) + "\n");
 		} else {
@@ -1503,6 +1661,22 @@ async function runStatusAction(options) {
 				process.stdout.write("\nStateStore Story States:\n");
 				for (const s of storeStories) process.stdout.write(`  ${s.storyKey}: ${s.phase} (${s.reviewCycles} review cycles)\n`);
 			}
+			if (workGraph !== void 0) {
+				const { summary, readyStories, blockedStories } = workGraph;
+				process.stdout.write("\nWork Graph:\n");
+				process.stdout.write(`  ${summary.inProgress} in progress, ${summary.ready} ready, ${summary.blocked} blocked, ${summary.complete} complete, ${summary.escalated} escalated\n`);
+				if (readyStories.length > 0) {
+					process.stdout.write("\n  Ready to dispatch:\n");
+					for (const s of readyStories) process.stdout.write(`    ${s.key}: ${s.title}\n`);
+				}
+				if (blockedStories.length > 0) {
+					process.stdout.write("\n  Blocked:\n");
+					for (const b of blockedStories) {
+						process.stdout.write(`    ${b.key}: ${b.title}\n`);
+						for (const bl of b.blockers) process.stdout.write(`      waiting on ${bl.key} (${bl.status}): ${bl.title}\n`);
+					}
+				}
+			}
 			process.stdout.write("\n");
 			process.stdout.write(formatTokenTelemetry(tokenSummary) + "\n");
 		}
@@ -2031,7 +2205,7 @@ async function runAmendAction(options) {
 	const dbRoot = await resolveMainRepoRoot(projectRoot);
 	const dbDir = join(dbRoot, ".substrate");
 	const dbPath = join(dbDir, "substrate.db");
-	const packPath = join(projectRoot, "packs", packName);
+	const packPath = join(dbRoot, "packs", packName);
 	const doltDir = join(dbRoot, ".substrate", "state", ".dolt");
 	if (!existsSync(dbPath) && !existsSync(doltDir)) {
 		process.stderr.write(`Error: Decision store not initialized. Run 'substrate init' first.\n`);
@@ -2749,7 +2923,7 @@ async function runSupervisorAction(options, deps = {}) {
 								await initSchema(expAdapter);
 								const { runRunAction: runPipeline } = await import(
 									/* @vite-ignore */
-									"../run-C-yCMYlt.js"
+									"../run-BSs4Dn0j.js"
 );
 								const runStoryFn = async (opts) => {
 									const exitCode = await runPipeline({
@@ -7142,7 +7316,7 @@ async function runRetryEscalatedAction(options) {
 			}
 			return 0;
 		}
-		const packPath = join(projectRoot, "packs", packName);
+		const packPath = join(dbRoot, "packs", packName);
 		const packLoader = createPackLoader();
 		let pack;
 		try {
@@ -7701,6 +7875,364 @@ function registerRoutingCommand(program) {
 	});
 }
 
+//#endregion
+//#region src/modules/work-graph/schema.ts
+/**
+* Work-graph schema DDL constants.
+*
+* Story 31-1 placeholder — defines the `stories`, `story_dependencies`, and
+* `ready_stories` DDL used by the EpicIngester and downstream consumers.
+*
+* NOTE: This file is a minimal placeholder created by story 31-2 because story
+* 31-1 (schema creation) had not yet run.  If story 31-1 produces a richer
+* schema, merge carefully and remove this note.
+*/
+const CREATE_STORIES_TABLE = `
+CREATE TABLE IF NOT EXISTS stories (
+  story_key VARCHAR(50) NOT NULL,
+  epic_num INT NOT NULL,
+  story_num INT NOT NULL,
+  title VARCHAR(500) NOT NULL,
+  priority VARCHAR(10) NOT NULL,
+  size VARCHAR(50) NOT NULL,
+  sprint INT NOT NULL,
+  status VARCHAR(50) NOT NULL DEFAULT 'planned',
+  PRIMARY KEY (story_key)
+)
+`.trim();
+const CREATE_STORY_DEPENDENCIES_TABLE = `
+CREATE TABLE IF NOT EXISTS story_dependencies (
+  story_key VARCHAR(50) NOT NULL,
+  depends_on VARCHAR(50) NOT NULL,
+  dependency_type VARCHAR(50) NOT NULL DEFAULT 'blocks',
+  source VARCHAR(50) NOT NULL DEFAULT 'explicit',
+  PRIMARY KEY (story_key, depends_on)
+)
+`.trim();
+const CREATE_READY_STORIES_VIEW = `
+CREATE VIEW IF NOT EXISTS ready_stories AS
+SELECT s.*
+FROM stories s
+WHERE s.status = 'planned'
+  AND NOT EXISTS (
+    SELECT 1 FROM story_dependencies sd
+    JOIN stories blocking ON sd.depends_on = blocking.story_key
+    WHERE sd.story_key = s.story_key
+      AND blocking.status != 'done'
+  )
+`.trim();
+
+//#endregion
+//#region src/modules/work-graph/epic-parser.ts
+/** Regex for sprint header lines: `**Sprint 1 —` (em dash or hyphen) */
+const SPRINT_HEADER_RE = /^\*\*Sprint\s+(\d+)\s*[—–-]/i;
+/**
+* Regex for story lines: `- 31-2: Epic doc ingestion (P0, Medium)`
+* Captures: epicNum, storyNum, title, priority, size
+*/
+const STORY_LINE_RE = /^-\s+(\d+)-(\d+):\s+(.+?)\s+\((P\d+),\s+([\w-]+)\)\s*$/;
+/** Regex to find the story map section heading */
+const STORY_MAP_HEADING_RE = /^#{1,6}\s+.*Story\s+Map/im;
+/** Regex to find the dependency chain line */
+const DEPENDENCY_CHAIN_RE = /\*\*Dependency\s+chain\*\*:\s*(.+)/i;
+/** Regex for "also gates" clauses: `31-3 also gates 31-6, 31-7` */
+const ALSO_GATES_RE = /^([\d]+-[\d]+)\s+also\s+gates\s+(.+)$/i;
+var EpicParser = class {
+	/**
+	* Parse story metadata from an epic planning document.
+	*
+	* @param content - Full text of the epic markdown document.
+	* @returns Array of `ParsedStory` objects, one per story line found.
+	* @throws {Error} If the story map section is absent or no stories can be parsed.
+	*/
+	parseStories(content) {
+		const headingMatch = STORY_MAP_HEADING_RE.exec(content);
+		if (!headingMatch) throw new Error("No story map section found in document");
+		const afterHeading = content.slice(headingMatch.index + headingMatch[0].length);
+		const stories = [];
+		let currentSprint = 0;
+		for (const rawLine of afterHeading.split("\n")) {
+			const line = rawLine.trim();
+			const sprintMatch = SPRINT_HEADER_RE.exec(line);
+			if (sprintMatch) {
+				currentSprint = parseInt(sprintMatch[1], 10);
+				continue;
+			}
+			const storyMatch = STORY_LINE_RE.exec(line);
+			if (storyMatch) {
+				const epicNum = parseInt(storyMatch[1], 10);
+				const storyNum = parseInt(storyMatch[2], 10);
+				stories.push({
+					story_key: `${epicNum}-${storyNum}`,
+					epic_num: epicNum,
+					story_num: storyNum,
+					title: storyMatch[3].trim(),
+					priority: storyMatch[4],
+					size: storyMatch[5],
+					sprint: currentSprint
+				});
+			}
+		}
+		if (stories.length === 0) throw new Error("Story map section found but contained no parseable story lines");
+		return stories;
+	}
+	/**
+	* Parse dependency relationships from an epic planning document.
+	*
+	* If the `**Dependency chain**:` line is absent, returns an empty array
+	* (not all epics declare dependencies).
+	*
+	* @param content - Full text of the epic markdown document.
+	* @returns Array of `ParsedDependency` objects.
+	*/
+	parseDependencies(content) {
+		const chainLineMatch = DEPENDENCY_CHAIN_RE.exec(content);
+		if (!chainLineMatch) return [];
+		const chainStr = chainLineMatch[1].trim();
+		const dependencies = [];
+		const clauses = chainStr.split(";").map((c) => c.trim()).filter(Boolean);
+		for (const clause of clauses) {
+			const alsoGatesMatch = ALSO_GATES_RE.exec(clause);
+			if (alsoGatesMatch) {
+				const gater = alsoGatesMatch[1].trim();
+				const gatedList = alsoGatesMatch[2].split(",").map((t) => t.trim()).filter(Boolean);
+				for (const gated of gatedList) dependencies.push({
+					story_key: gated,
+					depends_on: gater,
+					dependency_type: "blocks",
+					source: "explicit"
+				});
+				continue;
+			}
+			const parts = clause.split("→").map((p) => p.trim()).filter(Boolean);
+			for (let i = 0; i < parts.length - 1; i++) {
+				const upstream = parts[i];
+				const downstream = parts[i + 1];
+				dependencies.push({
+					story_key: downstream,
+					depends_on: upstream,
+					dependency_type: "blocks",
+					source: "explicit"
+				});
+			}
+		}
+		return dependencies;
+	}
+};
+
+//#endregion
+//#region src/modules/work-graph/epic-ingester.ts
+var EpicIngester = class {
+	adapter;
+	constructor(adapter) {
+		this.adapter = adapter;
+	}
+	/**
+	* Upsert stories and sync dependencies into the database.
+	*
+	* Both operations are wrapped in a single transaction: if either fails the
+	* entire batch is rolled back.
+	*
+	* @param stories      - Parsed story metadata from `EpicParser.parseStories()`.
+	* @param dependencies - Parsed dependency edges from `EpicParser.parseDependencies()`.
+	* @returns `IngestResult` with counts of affected rows.
+	*/
+	async ingest(stories, dependencies) {
+		const cycle = detectCycles(dependencies);
+		if (cycle !== null) throw new CyclicDependencyError(cycle);
+		return this.adapter.transaction(async (tx) => {
+			let storiesUpserted = 0;
+			for (const story of stories) {
+				const existing = await tx.query("SELECT status FROM stories WHERE story_key = ?", [story.story_key]);
+				if (existing.length > 0) await tx.query("UPDATE stories SET title = ?, priority = ?, size = ?, sprint = ? WHERE story_key = ?", [
+					story.title,
+					story.priority,
+					story.size,
+					story.sprint,
+					story.story_key
+				]);
+				else {
+					await tx.query("INSERT INTO stories (story_key, epic_num, story_num, title, priority, size, sprint, status) VALUES (?, ?, ?, ?, ?, ?, ?, ?)", [
+						story.story_key,
+						story.epic_num,
+						story.story_num,
+						story.title,
+						story.priority,
+						story.size,
+						story.sprint,
+						"planned"
+					]);
+					storiesUpserted++;
+				}
+			}
+			const epicNum = stories.length > 0 ? stories[0].epic_num : null;
+			if (epicNum !== null) await tx.query(`DELETE FROM story_dependencies WHERE source = 'explicit' AND story_key LIKE ?`, [`${epicNum}-%`]);
+			for (const dep of dependencies) await tx.query("INSERT INTO story_dependencies (story_key, depends_on, dependency_type, source) VALUES (?, ?, ?, ?)", [
+				dep.story_key,
+				dep.depends_on,
+				dep.dependency_type,
+				dep.source
+			]);
+			return {
+				storiesUpserted,
+				dependenciesReplaced: dependencies.length
+			};
+		});
+	}
+};
+
+//#endregion
+//#region src/cli/commands/ingest-epic.ts
+function registerIngestEpicCommand(program) {
+	program.command("ingest-epic <epic-doc-path>").description("Parse an epic planning doc and upsert story metadata into the work-graph").action(async (epicDocPath) => {
+		if (!existsSync$1(epicDocPath)) {
+			process.stderr.write(`Error: File not found: ${epicDocPath}\n`);
+			process.exitCode = 1;
+			return;
+		}
+		let content;
+		try {
+			content = readFileSync$1(epicDocPath, "utf-8");
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`Error: Cannot read file ${epicDocPath}: ${msg}\n`);
+			process.exitCode = 1;
+			return;
+		}
+		const parser = new EpicParser();
+		let stories;
+		let dependencies;
+		try {
+			stories = parser.parseStories(content);
+			dependencies = parser.parseDependencies(content);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`Error: ${msg}\n`);
+			process.exitCode = 1;
+			return;
+		}
+		const adapter = createDatabaseAdapter({
+			backend: "auto",
+			basePath: process.cwd()
+		});
+		try {
+			await adapter.exec(CREATE_STORIES_TABLE);
+			await adapter.exec(CREATE_STORY_DEPENDENCIES_TABLE);
+			const ingester = new EpicIngester(adapter);
+			const result = await ingester.ingest(stories, dependencies);
+			const epicNum = stories[0].epic_num;
+			process.stdout.write(`Ingested ${result.storiesUpserted} stories and ${result.dependenciesReplaced} dependencies from epic ${epicNum}\n`);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`Error: ${msg}\n`);
+			process.exitCode = 1;
+		} finally {
+			await adapter.close();
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/commands/epic-status.ts
+function sortByStoryKey(stories) {
+	return [...stories].sort((a, b) => {
+		const numA = parseInt(a.story_key.split("-")[1] ?? "0", 10);
+		const numB = parseInt(b.story_key.split("-")[1] ?? "0", 10);
+		return numA - numB;
+	});
+}
+const BADGE_WIDTH = 12;
+const STATUS_LABELS = {
+	complete: "complete  ",
+	in_progress: "in_progress",
+	ready: "ready     ",
+	planned: "planned   ",
+	escalated: "escalated ",
+	blocked: "blocked   "
+};
+function getBadge(status, isBlocked) {
+	if (isBlocked) return `[${STATUS_LABELS["blocked"] ?? "blocked   "}]`;
+	const label = STATUS_LABELS[status] ?? status.padEnd(BADGE_WIDTH - 2);
+	return `[${label}]`;
+}
+async function runEpicStatusAction(epicNum, opts) {
+	const adapter = createDatabaseAdapter({
+		backend: "auto",
+		basePath: process.cwd()
+	});
+	try {
+		await adapter.exec(CREATE_STORIES_TABLE);
+		await adapter.exec(CREATE_STORY_DEPENDENCIES_TABLE);
+		const repo = new WorkGraphRepository(adapter);
+		const rawStories = await repo.listStories({ epic: epicNum });
+		if (rawStories.length === 0) {
+			process.stderr.write(`No stories found for epic ${epicNum} (work graph not populated — run \`substrate ingest-epic\` first)\n`);
+			process.exitCode = 1;
+			return;
+		}
+		const stories = sortByStoryKey(rawStories);
+		const allBlocked = await repo.getBlockedStories();
+		const epicBlockedMap = new Map(allBlocked.filter((b) => b.story.epic === epicNum).map((b) => [b.story.story_key, b]));
+		const allReady = await repo.getReadyStories();
+		const epicReadySet = new Set(allReady.filter((s) => s.epic === epicNum).map((s) => s.story_key));
+		const summary = {
+			total: stories.length,
+			complete: stories.filter((s) => s.status === "complete").length,
+			inProgress: stories.filter((s) => s.status === "in_progress").length,
+			escalated: stories.filter((s) => s.status === "escalated").length,
+			blocked: epicBlockedMap.size,
+			ready: epicReadySet.size - epicBlockedMap.size,
+			planned: stories.filter((s) => (s.status === "planned" || s.status === "ready") && !epicBlockedMap.has(s.story_key) && !epicReadySet.has(s.story_key)).length
+		};
+		if (opts.outputFormat === "json") {
+			const output = {
+				epic: epicNum,
+				stories: stories.map((s) => {
+					const blockedInfo = epicBlockedMap.get(s.story_key);
+					const entry = {
+						key: s.story_key,
+						title: s.title ?? null,
+						status: blockedInfo ? "blocked" : s.status
+					};
+					if (blockedInfo) entry.blockers = blockedInfo.blockers.map((b) => ({
+						key: b.key,
+						title: b.title,
+						status: b.status
+					}));
+					return entry;
+				}),
+				summary
+			};
+			process.stdout.write(JSON.stringify(output, null, 2) + "\n");
+		} else {
+			process.stdout.write(`Epic ${epicNum} — ${stories.length} stories\n\n`);
+			for (const story of stories) {
+				const isBlocked = epicBlockedMap.has(story.story_key);
+				const badge = getBadge(story.status, isBlocked);
+				const keyPadded = story.story_key.padEnd(6);
+				const displayTitle = story.title ?? story.story_key;
+				let line = `  ${badge} ${keyPadded}  ${displayTitle}`;
+				if (isBlocked) {
+					const blockedInfo = epicBlockedMap.get(story.story_key);
+					const blockerList = blockedInfo.blockers.map((b) => `${b.key} (${b.status})`).join(", ");
+					line += `  [waiting on: ${blockerList}]`;
+				}
+				process.stdout.write(line + "\n");
+			}
+			process.stdout.write("\n");
+			process.stdout.write(`Epic ${epicNum}: ${summary.complete} complete · ${summary.inProgress} in_progress · ${summary.ready} ready · ${summary.blocked} blocked · ${summary.planned} planned · ${summary.escalated} escalated\n`);
+		}
+	} finally {
+		await adapter.close();
+	}
+}
+function registerEpicStatusCommand(program) {
+	program.command("epic-status <epic>").description("Show a generated status view of an epic from the Dolt work graph").option("--output-format <format>", "Output format: human (default) or json", "human").action(async (epic, options) => {
+		const fmt = options.outputFormat === "json" ? "json" : "human";
+		await runEpicStatusAction(epic, { outputFormat: fmt });
+	});
+}
+
 //#endregion
 //#region src/cli/index.ts
 process.setMaxListeners(20);
@@ -7761,6 +8293,8 @@ async function createProgram() {
 	registerWorktreesCommand(program, version);
 	registerBrainstormCommand(program, version);
 	registerExportCommand(program, version);
+	registerIngestEpicCommand(program);
+	registerEpicStatusCommand(program);
 	registerUpgradeCommand(program);
 	return program;
 }