substrate-ai 0.5.1 → 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, createEventEmitter, 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-BD0Ugp7F.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";
@@ -1004,6 +1004,26 @@ 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");
@@ -1017,7 +1037,6 @@ function mapInternalPhaseToEventPhase(internalPhase) {
 		case "IN_REVIEW": return "code-review";
 		case "IN_MINOR_FIX":
 		case "IN_MAJOR_FIX": return "fix";
-		case "IN_TEST_PLANNING": return "test-planning";
 		default: return null;
 	}
 }
@@ -1490,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);
@@ -1557,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 {
@@ -1603,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");
 		}
@@ -2849,7 +2923,7 @@ async function runSupervisorAction(options, deps = {}) {
 								await initSchema(expAdapter);
 								const { runRunAction: runPipeline } = await import(
 									/* @vite-ignore */
-									"../run-B-TUWMCv.js"
+									"../run-BSs4Dn0j.js"
 );
 								const runStoryFn = async (opts) => {
 									const exitCode = await runPipeline({
@@ -7964,6 +8038,8 @@ var EpicIngester = class {
 	* @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) {
@@ -8056,6 +8132,107 @@ function registerIngestEpicCommand(program) {
 	});
 }
 
+//#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);
@@ -8117,6 +8294,7 @@ async function createProgram() {
 	registerBrainstormCommand(program, version);
 	registerExportCommand(program, version);
 	registerIngestEpicCommand(program);
+	registerEpicStatusCommand(program);
 	registerUpgradeCommand(program);
 	return program;
 }

package/dist/{run-B-TUWMCv.js → run-BSs4Dn0j.js}

@@ -1,4 +1,4 @@
-import { registerRunCommand, runRunAction } from "./run-BD0Ugp7F.js";
+import { registerRunCommand, runRunAction } from "./run-CxoTrYdA.js";
 import "./logger-D2fS2ccL.js";
 import "./config-migrator-DtZW1maj.js";
 import "./helpers-BihqWgVe.js";

package/dist/{run-BD0Ugp7F.js → run-CxoTrYdA.js}

@@ -215,6 +215,24 @@ var DoltDatabaseAdapter = class {
 	async close() {
 		await this._client.close();
 	}
+	/**
+	* Query story keys from the `ready_stories` SQL view.
+	*
+	* Returns story keys whose status is `planned` or `ready` and whose
+	* hard dependencies are all `complete` in the work graph.
+	*
+	* On any SQL error (e.g., view not yet created by story 31-1 schema,
+	* or empty stories table), returns `[]` so the caller falls through to
+	* the legacy discovery chain.
+	*/
+	async queryReadyStories() {
+		try {
+			const rows = await this._client.query("SELECT `key` FROM ready_stories ORDER BY `key` ASC", void 0);
+			return rows.map((r) => r.key);
+		} catch {
+			return [];
+		}
+	}
 };
 
 //#endregion
@@ -242,6 +260,13 @@ var InMemoryDatabaseAdapter = class {
 	async close() {
 		this._tables.clear();
 	}
+	/**
+	* Work graph not supported in InMemoryDatabaseAdapter.
+	* Returns `[]` to signal the caller to use the legacy discovery path.
+	*/
+	async queryReadyStories() {
+		return [];
+	}
 	_execute(sql, params) {
 		const resolved = this._substituteParams(sql, params);
 		const upper = resolved.trimStart().toUpperCase();
@@ -281,8 +306,8 @@ var InMemoryDatabaseAdapter = class {
 		if (m) this._tables.delete(m[1]);
 		return [];
 	}
-	_insert(sql) {
-		const m = /INSERT\s+INTO\s+(\w+)\s*\(([^)]+)\)\s*VALUES\s*\((.+)\)\s*$/is.exec(sql);
+	_insert(sql, _ignoreConflicts = false) {
+		const m = /INSERT\s+(?:IGNORE\s+)?INTO\s+(\w+)\s*\(([^)]+)\)\s*VALUES\s*\((.+)\)\s*$/is.exec(sql);
 		if (!m) return [];
 		const tableName = m[1];
 		const cols = m[2].split(",").map((c) => c.trim());
@@ -7198,6 +7223,259 @@ function createDispatcher(options) {
 	return new DispatcherImpl(options.eventBus, options.adapterRegistry, config);
 }
 
+//#endregion
+//#region src/modules/work-graph/cycle-detector.ts
+/**
+* detectCycles — DFS-based cycle detection for story dependency graphs.
+*
+* Story 31-7: Cycle Detection in Work Graph
+*
+* Pure function; no database or I/O dependencies.
+*/
+/**
+* Detect cycles in a directed dependency graph represented as an edge list.
+*
+* Each edge `{ story_key, depends_on }` means story_key depends on depends_on
+* (i.e. story_key → depends_on is the directed edge we traverse).
+*
+* Uses iterative DFS with an explicit stack to avoid call-stack overflows on
+* large graphs, but also supports a nested recursive helper for cycle path
+* reconstruction.
+*
+* @param edges - List of dependency edges to check.
+* @returns `null` if the graph is acyclic (safe to persist), or a `string[]`
+*   containing the cycle path with the first and last element being the same
+*   story key (e.g. `['A', 'B', 'A']`).
+*/
+function detectCycles(edges) {
+	const adj = new Map();
+	for (const { story_key, depends_on } of edges) {
+		if (!adj.has(story_key)) adj.set(story_key, []);
+		adj.get(story_key).push(depends_on);
+	}
+	const visited = new Set();
+	const visiting = new Set();
+	const path$2 = [];
+	function dfs(node) {
+		if (visiting.has(node)) {
+			const cycleStart = path$2.indexOf(node);
+			return [...path$2.slice(cycleStart), node];
+		}
+		if (visited.has(node)) return null;
+		visiting.add(node);
+		path$2.push(node);
+		for (const neighbor of adj.get(node) ?? []) {
+			const cycle = dfs(neighbor);
+			if (cycle !== null) return cycle;
+		}
+		path$2.pop();
+		visiting.delete(node);
+		visited.add(node);
+		return null;
+	}
+	const allNodes = new Set([...edges.map((e) => e.story_key), ...edges.map((e) => e.depends_on)]);
+	for (const node of allNodes) if (!visited.has(node)) {
+		const cycle = dfs(node);
+		if (cycle !== null) return cycle;
+	}
+	return null;
+}
+
+//#endregion
+//#region src/modules/state/work-graph-repository.ts
+var WorkGraphRepository = class {
+	constructor(db) {
+		this.db = db;
+	}
+	/**
+	* Insert or replace a work-graph story node.
+	* Uses DELETE + INSERT so it works on InMemoryDatabaseAdapter (which does
+	* not support ON DUPLICATE KEY UPDATE).
+	*/
+	async upsertStory(story) {
+		await this.db.query(`DELETE FROM wg_stories WHERE story_key = ?`, [story.story_key]);
+		await this.db.query(`INSERT INTO wg_stories (story_key, epic, title, status, spec_path, created_at, updated_at, completed_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [
+			story.story_key,
+			story.epic,
+			story.title ?? null,
+			story.status,
+			story.spec_path ?? null,
+			story.created_at ?? null,
+			story.updated_at ?? null,
+			story.completed_at ?? null
+		]);
+	}
+	/**
+	* Insert a dependency edge.  Idempotent — if a row with the same
+	* (story_key, depends_on) already exists it is silently skipped.
+	*/
+	async addDependency(dep) {
+		const existing = await this.db.query(`SELECT story_key FROM story_dependencies WHERE story_key = ? AND depends_on = ?`, [dep.story_key, dep.depends_on]);
+		if (existing.length > 0) return;
+		await this.db.query(`INSERT INTO story_dependencies (story_key, depends_on, dependency_type, source, created_at) VALUES (?, ?, ?, ?, ?)`, [
+			dep.story_key,
+			dep.depends_on,
+			dep.dependency_type,
+			dep.source,
+			dep.created_at ?? null
+		]);
+	}
+	/**
+	* Persist contract-based dependency edges to `story_dependencies` as
+	* best-effort, idempotent writes.
+	*
+	* - edges where `reason` does NOT start with `'dual export:'` are persisted
+	*   as `dependency_type = 'blocks'` (hard prerequisites).
+	* - edges where `reason` starts with `'dual export:'` are persisted as
+	*   `dependency_type = 'informs'` (serialization hints, not hard gates).
+	*
+	* Idempotency is delegated to `addDependency()`, which skips the INSERT if
+	* a row with the same `(story_key, depends_on)` already exists.
+	*
+	* @param edges - Readonly list of contract dependency edges to persist.
+	*/
+	async addContractDependencies(edges) {
+		if (edges.length === 0) return;
+		for (const edge of edges) {
+			const dependency_type = edge.reason?.startsWith("dual export:") ? "informs" : "blocks";
+			await this.addDependency({
+				story_key: edge.to,
+				depends_on: edge.from,
+				dependency_type,
+				source: "contract",
+				created_at: new Date().toISOString()
+			});
+		}
+	}
+	/**
+	* Return all work-graph stories, optionally filtered by epic and/or status.
+	*/
+	async listStories(filter$1) {
+		if (!filter$1 || !filter$1.epic && !filter$1.status) return this.db.query(`SELECT * FROM wg_stories`);
+		const conditions = [];
+		const params = [];
+		if (filter$1.epic) {
+			conditions.push(`epic = ?`);
+			params.push(filter$1.epic);
+		}
+		if (filter$1.status) {
+			conditions.push(`status = ?`);
+			params.push(filter$1.status);
+		}
+		const where = conditions.join(" AND ");
+		return this.db.query(`SELECT * FROM wg_stories WHERE ${where}`, params);
+	}
+	/**
+	* Update the `status` (and optionally `completed_at`) of an existing
+	* work-graph story.
+	*
+	* This is a read-modify-write operation: SELECT existing row → build
+	* updated WgStory → upsertStory(). If no row exists for `storyKey` the
+	* call is a no-op (AC4).
+	*
+	* @param storyKey - Story identifier, e.g. "31-4"
+	* @param status   - Target WgStoryStatus value
+	* @param opts     - Optional `completedAt` ISO string for terminal phases
+	*/
+	async updateStoryStatus(storyKey, status, opts) {
+		const rows = await this.db.query(`SELECT * FROM wg_stories WHERE story_key = ?`, [storyKey]);
+		if (rows.length === 0) return;
+		const existing = rows[0];
+		const now = new Date().toISOString();
+		const isTerminal = status === "complete" || status === "escalated";
+		const updated = {
+			...existing,
+			status,
+			updated_at: now,
+			completed_at: isTerminal ? opts?.completedAt ?? now : existing.completed_at
+		};
+		await this.upsertStory(updated);
+	}
+	/**
+	* Return stories that are eligible for dispatch.
+	*
+	* A story is ready when:
+	*   1. Its status is 'planned' or 'ready', AND
+	*   2. It has no 'blocks' dependency whose blocking story is not 'complete'.
+	*
+	* Soft ('informs') dependencies never block dispatch.
+	*
+	* This is implemented programmatically rather than via the `ready_stories`
+	* VIEW so that the InMemoryDatabaseAdapter can handle it without VIEW support.
+	*/
+	async getReadyStories() {
+		const allStories = await this.db.query(`SELECT * FROM wg_stories`);
+		const candidates = allStories.filter((s) => s.status === "planned" || s.status === "ready");
+		if (candidates.length === 0) return [];
+		const deps = await this.db.query(`SELECT story_key, depends_on FROM story_dependencies WHERE dependency_type = 'blocks'`);
+		if (deps.length === 0) return candidates;
+		const blockerStatus = new Map(allStories.map((s) => [s.story_key, s.status]));
+		const depsMap = new Map();
+		for (const d of deps) {
+			if (!depsMap.has(d.story_key)) depsMap.set(d.story_key, []);
+			depsMap.get(d.story_key).push(d.depends_on);
+		}
+		return candidates.filter((s) => {
+			const blocking = depsMap.get(s.story_key) ?? [];
+			return blocking.every((dep) => blockerStatus.get(dep) === "complete");
+		});
+	}
+	/**
+	* Return stories that are planned/ready but cannot be dispatched because
+	* at least one hard-blocking ('blocks') dependency is not yet complete.
+	*
+	* For each blocked story, the returned object includes the full WgStory
+	* record plus the list of unsatisfied blockers (key, title, status).
+	*
+	* Soft ('informs') dependencies are ignored here, matching getReadyStories().
+	*/
+	/**
+	* Query the database for all 'blocks' dependency rows and run DFS cycle
+	* detection over them.
+	*
+	* Returns an empty array if no cycle is found (consistent with other
+	* repository methods that return empty arrays rather than null).
+	*
+	* Only 'blocks' deps are checked — soft 'informs' deps cannot cause
+	* dispatch deadlocks (AC5).
+	*/
+	async detectCycles() {
+		const rows = await this.db.query(`SELECT story_key, depends_on FROM story_dependencies WHERE dependency_type = 'blocks'`);
+		const cycle = detectCycles(rows);
+		return cycle ?? [];
+	}
+	async getBlockedStories() {
+		const allStories = await this.db.query(`SELECT * FROM wg_stories`);
+		const candidates = allStories.filter((s) => s.status === "planned" || s.status === "ready");
+		if (candidates.length === 0) return [];
+		const deps = await this.db.query(`SELECT story_key, depends_on FROM story_dependencies WHERE dependency_type = 'blocks'`);
+		if (deps.length === 0) return [];
+		const statusMap = new Map(allStories.map((s) => [s.story_key, s]));
+		const depsMap = new Map();
+		for (const d of deps) {
+			if (!depsMap.has(d.story_key)) depsMap.set(d.story_key, []);
+			depsMap.get(d.story_key).push(d.depends_on);
+		}
+		const result = [];
+		for (const story of candidates) {
+			const blockerKeys = depsMap.get(story.story_key) ?? [];
+			const unsatisfied = blockerKeys.filter((key) => statusMap.get(key)?.status !== "complete").map((key) => {
+				const s = statusMap.get(key);
+				return {
+					key,
+					title: s?.title ?? key,
+					status: s?.status ?? "unknown"
+				};
+			});
+			if (unsatisfied.length > 0) result.push({
+				story,
+				blockers: unsatisfied
+			});
+		}
+		return result;
+	}
+};
+
 //#endregion
 //#region src/modules/state/file-store.ts
 /**
@@ -9186,6 +9464,42 @@ function countFilesInLayout(content) {
 	return count;
 }
 
+//#endregion
+//#region src/modules/work-graph/spec-migrator.ts
+/**
+* spec-migrator — utilities for migrating story spec files away from the
+* deprecated `Status:` frontmatter field.
+*
+* Story 31-8: Deprecate Status Field in Story Spec Frontmatter
+*
+* Story status is now exclusively managed in the Dolt work graph
+* (`wg_stories.status`). These pure functions strip the deprecated field from
+* spec content before it is injected into agent prompts.
+*/
+/**
+* Remove the deprecated `Status:` line from story spec content.
+* Also removes the blank line immediately following the Status line.
+* Returns the original content unchanged if no Status line is present.
+*
+* The regex is anchored at the start of a line (`^` with multiline flag) so
+* it does NOT strip lines like `## Status Notes` or `The status is good`.
+*/
+function stripDeprecatedStatusField(content) {
+	return content.replace(/^Status:[^\n]*\n?(\n)?/m, "");
+}
+/**
+* Detect whether a story spec contains the deprecated Status field.
+* Returns the status value string (e.g. `'ready-for-dev'`) if found, or
+* `null` if absent.
+*
+* The regex is anchored at line start so incidental uses of the word "Status"
+* (e.g. in section headings) are not matched.
+*/
+function detectDeprecatedStatusField(content) {
+	const match$1 = /^Status:\s*(.+)$/m.exec(content);
+	return match$1 !== null ? match$1[1].trim() : null;
+}
+
 //#endregion
 //#region src/modules/compiled-workflows/dev-story.ts
 const logger$15 = createLogger("compiled-workflows:dev-story");
@@ -9294,6 +9608,14 @@ async function runDevStory(deps, params) {
 		}, "Story file is empty");
 		return makeFailureResult("story_file_empty");
 	}
+	const staleStatus = detectDeprecatedStatusField(storyContent);
+	if (staleStatus !== null) {
+		logger$15.warn({
+			storyFilePath,
+			staleStatus
+		}, "Story spec contains deprecated Status field — stripped before dispatch (status is managed by Dolt work graph)");
+		storyContent = stripDeprecatedStatusField(storyContent);
+	}
 	const complexity = computeStoryComplexity(storyContent);
 	const resolvedMaxTurns = resolveDevStoryMaxTurns(complexity.complexityScore);
 	logComplexityResult(storyKey, complexity, resolvedMaxTurns);
@@ -14451,6 +14773,22 @@ function buildTargetedFilesContent(issueList) {
 	return lines.join("\n");
 }
 /**
+* Map a StoryPhase to the corresponding WgStoryStatus for wg_stories writes.
+* Returns null for PENDING (no write needed).
+*/
+function wgStatusForPhase(phase) {
+	switch (phase) {
+		case "PENDING": return null;
+		case "IN_STORY_CREATION":
+		case "IN_TEST_PLANNING":
+		case "IN_DEV":
+		case "IN_REVIEW":
+		case "NEEDS_FIXES": return "in_progress";
+		case "COMPLETE": return "complete";
+		case "ESCALATED": return "escalated";
+	}
+}
+/**
 * Factory function that creates an ImplementationOrchestrator instance.
 *
 * @param deps - Injected dependencies (db, pack, contextCompiler, dispatcher,
@@ -14460,6 +14798,8 @@ function buildTargetedFilesContent(issueList) {
 function createImplementationOrchestrator(deps) {
 	const { db, pack, contextCompiler, dispatcher, eventBus, config, projectRoot, tokenCeilings, stateStore, telemetryPersistence, ingestionServer, repoMapInjector, maxRepoMapTokens } = deps;
 	const logger$26 = createLogger("implementation-orchestrator");
+	const wgRepo = new WorkGraphRepository(db);
+	const _wgInProgressWritten = new Set();
 	let _state = "IDLE";
 	let _startedAt;
 	let _completedAt;
@@ -14730,6 +15070,21 @@ function createImplementationOrchestrator(deps) {
 				err,
 				storyKey
 			}, "rollbackStory failed — branch may persist"));
+			if (updates.phase !== void 0) {
+				const targetStatus = wgStatusForPhase(updates.phase);
+				if (targetStatus !== null) if (targetStatus === "in_progress" && _wgInProgressWritten.has(storyKey)) {} else {
+					const fullUpdated = {
+						...existing,
+						...updates
+					};
+					const opts = targetStatus === "complete" || targetStatus === "escalated" ? { completedAt: fullUpdated.completedAt } : void 0;
+					wgRepo.updateStoryStatus(storyKey, targetStatus, opts).catch((err) => logger$26.warn({
+						err,
+						storyKey
+					}, "wg_stories status update failed (best-effort)"));
+					if (targetStatus === "in_progress") _wgInProgressWritten.add(storyKey);
+				}
+			}
 		}
 	}
 	/**
@@ -16210,6 +16565,7 @@ function createImplementationOrchestrator(deps) {
 				contractEdges,
 				edgeCount: contractEdges.length
 			}, "Contract dependency edges detected — applying contract-aware dispatch ordering");
+			wgRepo.addContractDependencies(contractEdges).catch((err) => logger$26.warn({ err }, "contract dep persistence failed (best-effort)"));
 			logger$26.info({
 				storyCount: storyKeys.length,
 				groupCount: batches.reduce((sum, b) => sum + b.length, 0),
@@ -16370,9 +16726,10 @@ function createImplementationOrchestrator(deps) {
 //#endregion
 //#region src/modules/implementation-orchestrator/story-discovery.ts
 /**
-* Unified story key resolution with a 4-level fallback chain.
+* Unified story key resolution with a 5-level fallback chain.
 *
 * 1. Explicit keys (from --stories flag) — returned as-is
+* 1.5. ready_stories SQL view — when work graph is populated (story 31-3)
 * 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)
@@ -16384,6 +16741,19 @@ function createImplementationOrchestrator(deps) {
 async function resolveStoryKeys(db, projectRoot, opts) {
 	if (opts?.explicit !== void 0 && opts.explicit.length > 0) return opts.explicit;
 	let keys = [];
+	const readyKeys = await db.queryReadyStories();
+	if (readyKeys.length > 0) {
+		let filteredKeys = readyKeys;
+		if (opts?.epicNumber !== void 0) {
+			const prefix = `${opts.epicNumber}-`;
+			filteredKeys = filteredKeys.filter((k) => k.startsWith(prefix));
+		}
+		if (opts?.filterCompleted === true && filteredKeys.length > 0) {
+			const completedKeys = await getCompletedStoryKeys(db);
+			filteredKeys = filteredKeys.filter((k) => !completedKeys.has(k));
+		}
+		return sortStoryKeys([...new Set(filteredKeys)]);
+	}
 	try {
 		const sql = 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] : [];
@@ -21750,5 +22120,5 @@ function registerRunCommand(program, _version = "0.0.0", projectRoot = process.c
 }
 
 //#endregion
-export { 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, createEventEmitter, 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, runRunAction, runSolutioningPhase, validateStopAfterFromConflict };
-//# sourceMappingURL=run-BD0Ugp7F.js.map
+export { 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, runRunAction, runSolutioningPhase, validateStopAfterFromConflict };
+//# sourceMappingURL=run-CxoTrYdA.js.map

package/dist/schema.sql

@@ -258,11 +258,10 @@ CREATE INDEX IF NOT EXISTS idx_wg_stories_epic ON wg_stories (epic);
 -- story_dependencies (Epic 31-1) — directed dependency edges
 -- ---------------------------------------------------------------------------
 CREATE TABLE IF NOT EXISTS story_dependencies (
-  story_key  VARCHAR(20)   NOT NULL,
-  depends_on VARCHAR(20)   NOT NULL,
-  dep_type   VARCHAR(20)   NOT NULL,
-  source     VARCHAR(20)   NOT NULL,
-  created_at DATETIME,
+  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)
 );
 
@@ -276,7 +275,7 @@ CREATE OR REPLACE VIEW ready_stories AS
       SELECT 1 FROM story_dependencies d
       JOIN wg_stories dep ON dep.story_key = d.depends_on
       WHERE d.story_key = s.story_key
-        AND d.dep_type = 'blocks'
+        AND d.dependency_type = 'blocks'
         AND dep.status <> 'complete'
     );
 

package/package.json

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

package/packs/bmad/prompts/create-story.md

@@ -32,7 +32,7 @@ Using the context above, write a complete, implementation-ready story file for s
    - Dev Notes with file paths, import patterns, testing requirements
 5. **Apply the scope cap** — see Scope Cap Guidance below
 6. **Write the story file** to: `_bmad-output/implementation-artifacts/{{story_key}}-<kebab-title>.md`
-   - Status must be: `ready-for-dev`
+   - Do NOT add a `Status:` field to the story file — story status is managed exclusively by the Dolt work graph (`wg_stories` table)
    - Dev Agent Record section must be present but left blank (to be filled by dev agent)
 
 ## Interface Contracts Guidance

package/packs/bmad/templates/story.md

@@ -1,7 +1,5 @@
 # Story {epic_num}.{story_num}: {Title}
 
-Status: draft
-
 ## Story
 
 As a {role},