substrate-ai 0.2.3 → 0.2.5

package/dist/cli/index.js

@@ -2,10 +2,10 @@
 import { createLogger, deepMask } from "../logger-C6n1g8uP.js";
 import { AdapterRegistry, createEventBus } from "../event-bus-J-bw-pkp.js";
 import { CURRENT_CONFIG_FORMAT_VERSION, CURRENT_TASK_GRAPH_VERSION, PartialSubstrateConfigSchema, SUPPORTED_CONFIG_FORMAT_VERSIONS, SubstrateConfigSchema, defaultConfigMigrator } from "../version-manager-impl-BpVx2DkY.js";
-import { DatabaseWrapper, SUBSTRATE_OWNED_SETTINGS_KEYS, VALID_PHASES, buildPipelineStatusOutput, createContextCompiler, createDispatcher, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, findPackageRoot, formatOutput, formatPhaseCompletionSummary, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getSubstrateDefaultSettings, registerRunCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion, resolveMainRepoRoot, runAnalysisPhase, runMigrations, runPlanningPhase, runSolutioningPhase, validateStopAfterFromConflict } from "../run-DlOWhkIF.js";
+import { DatabaseWrapper, SUBSTRATE_OWNED_SETTINGS_KEYS, VALID_PHASES, buildPipelineStatusOutput, createContextCompiler, createDispatcher, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, findPackageRoot, formatOutput, formatPhaseCompletionSummary, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getSubstrateDefaultSettings, parseDbTimestampAsUtc, registerRunCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion, resolveMainRepoRoot, runAnalysisPhase, runMigrations, runPlanningPhase, runSolutioningPhase, validateStopAfterFromConflict } from "../run-CDYE1PT3.js";
 import { ConfigError, ConfigIncompatibleFormatError } from "../errors-BPqtzQ4U.js";
-import { addTokenUsage, createDecision, getDecisionsByPhaseForRun, getLatestRun, getPipelineRunById, getTokenUsageSummary, updatePipelineRun } from "../decisions-BBLMsN_c.js";
-import { compareRunMetrics, getBaselineRunMetrics, getRunMetrics, getStoryMetricsForRun, incrementRunRestarts, listRunMetrics, tagRunAsBaseline } from "../metrics-BSg8VIHd.js";
+import { addTokenUsage, createDecision, getDecisionsByPhaseForRun, getLatestRun, getPipelineRunById, getTokenUsageSummary, listRequirements, updatePipelineRun } from "../decisions-DNYByk0U.js";
+import { aggregateTokenUsageForRun, compareRunMetrics, getBaselineRunMetrics, getRunMetrics, getStoryMetricsForRun, incrementRunRestarts, listRunMetrics, tagRunAsBaseline } from "../metrics-BSg8VIHd.js";
 import { abortMerge, createWorktree, getConflictingFiles, getMergedFiles, getOrphanedWorktrees, performMerge, removeBranch, removeWorktree, simulateMerge, verifyGitVersion } from "../git-utils-BtI5eNoN.js";
 import { registerUpgradeCommand } from "../upgrade-rV26kdh3.js";
 import { createRequire } from "module";
@@ -17,8 +17,9 @@ import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, re
 import yaml from "js-yaml";
 import { createRequire as createRequire$1 } from "node:module";
 import * as path$1 from "node:path";
+import { isAbsolute, join as join$1 } from "node:path";
 import BetterSqlite3 from "better-sqlite3";
-import { existsSync as existsSync$1 } from "node:fs";
+import { existsSync as existsSync$1, mkdirSync as mkdirSync$1, writeFileSync as writeFileSync$1 } from "node:fs";
 import { createInterface } from "node:readline";
 import { homedir } from "os";
 import { access as access$1 } from "node:fs/promises";
@@ -328,7 +329,7 @@ const DEFAULT_CONFIG = {
 
 //#endregion
 //#region src/cli/commands/init.ts
-const logger$16 = createLogger("init");
+const logger$17 = createLogger("init");
 const __dirname = dirname(new URL(import.meta.url).pathname);
 const INIT_EXIT_SUCCESS = 0;
 const INIT_EXIT_ERROR = 1;
@@ -349,7 +350,7 @@ async function scaffoldBmadFramework(projectRoot, force, outputFormat) {
 	const version = resolveBmadMethodVersion();
 	if (force && bmadExists) process.stderr.write(`Warning: Replacing existing _bmad/ framework with bmad-method@${version}\n`);
 	process.stdout.write(`Scaffolding BMAD framework from bmad-method@${version}\n`);
-	logger$16.info({
+	logger$17.info({
 		version,
 		dest: bmadDest
 	}, "Scaffolding BMAD framework");
@@ -359,7 +360,7 @@ async function scaffoldBmadFramework(projectRoot, force, outputFormat) {
 			const destDir = join(bmadDest, dir);
 			mkdirSync(destDir, { recursive: true });
 			cpSync(srcDir, destDir, { recursive: true });
-			logger$16.info({
+			logger$17.info({
 				dir,
 				dest: destDir
 			}, "Scaffolded BMAD framework directory");
@@ -378,7 +379,7 @@ async function scaffoldBmadFramework(projectRoot, force, outputFormat) {
 			"document_output_language: English"
 		].join("\n") + "\n";
 		await writeFile(configFile, configStub, "utf8");
-		logger$16.info({ configFile }, "Generated _bmad/_config/config.yaml stub");
+		logger$17.info({ configFile }, "Generated _bmad/_config/config.yaml stub");
 	}
 }
 const CLAUDE_MD_START_MARKER = "<!-- substrate:start -->";
@@ -393,7 +394,7 @@ async function scaffoldClaudeMd(projectRoot) {
 	try {
 		sectionContent = await readFile(templatePath, "utf8");
 	} catch {
-		logger$16.warn({ templatePath }, "CLAUDE.md substrate section template not found; skipping");
+		logger$17.warn({ templatePath }, "CLAUDE.md substrate section template not found; skipping");
 		return;
 	}
 	if (!sectionContent.endsWith("\n")) sectionContent += "\n";
@@ -411,7 +412,7 @@ async function scaffoldClaudeMd(projectRoot) {
 		newContent = existingContent + separator + sectionContent;
 	}
 	await writeFile(claudeMdPath, newContent, "utf8");
-	logger$16.info({ claudeMdPath }, "Wrote substrate section to CLAUDE.md");
+	logger$17.info({ claudeMdPath }, "Wrote substrate section to CLAUDE.md");
 }
 async function scaffoldStatuslineScript(projectRoot) {
 	const pkgRoot = findPackageRoot(__dirname);
@@ -422,7 +423,7 @@ async function scaffoldStatuslineScript(projectRoot) {
 	try {
 		content = await readFile(templatePath, "utf8");
 	} catch {
-		logger$16.warn({ templatePath }, "statusline.sh template not found; skipping");
+		logger$17.warn({ templatePath }, "statusline.sh template not found; skipping");
 		return;
 	}
 	const claudeDir = join(projectRoot, ".claude");
@@ -430,7 +431,7 @@ async function scaffoldStatuslineScript(projectRoot) {
 	mkdirSync(claudeDir, { recursive: true });
 	await writeFile(statuslinePath, content, "utf8");
 	chmodSync(statuslinePath, 493);
-	logger$16.info({ statuslinePath }, "Wrote .claude/statusline.sh");
+	logger$17.info({ statuslinePath }, "Wrote .claude/statusline.sh");
 }
 async function scaffoldClaudeSettings(projectRoot) {
 	const claudeDir = join(projectRoot, ".claude");
@@ -446,7 +447,7 @@ async function scaffoldClaudeSettings(projectRoot) {
 	if (!merged["$schema"]) merged["$schema"] = "https://json.schemastore.org/claude-code-settings.json";
 	mkdirSync(claudeDir, { recursive: true });
 	await writeFile(settingsPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
-	logger$16.info({ settingsPath }, "Wrote substrate settings to .claude/settings.json");
+	logger$17.info({ settingsPath }, "Wrote substrate settings to .claude/settings.json");
 }
 function resolveBmadMethodInstallerLibPath(fromDir = __dirname) {
 	try {
@@ -516,7 +517,7 @@ async function compileBmadAgents(bmadDir) {
 				writeFileSync(mdPath, result.xml, "utf-8");
 				compiled++;
 			} catch (compileErr) {
-				logger$16.debug({
+				logger$17.debug({
 					err: compileErr,
 					file
 				}, "Failed to compile agent YAML");
@@ -537,9 +538,9 @@ async function scaffoldClaudeCommands(projectRoot, outputFormat) {
 		const _require = createRequire$1(join(__dirname, "synthetic.js"));
 		try {
 			const compiledCount = await compileBmadAgents(bmadDir);
-			if (compiledCount > 0) logger$16.info({ compiledCount }, "Compiled agent YAML files to MD");
+			if (compiledCount > 0) logger$17.info({ compiledCount }, "Compiled agent YAML files to MD");
 		} catch (compileErr) {
-			logger$16.warn({ err: compileErr }, "Agent compilation failed; agent commands may be incomplete");
+			logger$17.warn({ err: compileErr }, "Agent compilation failed; agent commands may be incomplete");
 		}
 		const { AgentCommandGenerator } = _require(join(installerLibPath, "ide", "shared", "agent-command-generator.js"));
 		const { WorkflowCommandGenerator } = _require(join(installerLibPath, "ide", "shared", "workflow-command-generator.js"));
@@ -551,7 +552,7 @@ async function scaffoldClaudeCommands(projectRoot, outputFormat) {
 			const manifestGen = new ManifestGenerator();
 			await manifestGen.generateManifests(bmadDir, allModules, [], { ides: ["claude-code"] });
 		} catch (manifestErr) {
-			logger$16.warn({ err: manifestErr }, "ManifestGenerator failed; workflow/task commands may be incomplete");
+			logger$17.warn({ err: manifestErr }, "ManifestGenerator failed; workflow/task commands may be incomplete");
 		}
 		const commandsDir = join(projectRoot, ".claude", "commands");
 		mkdirSync(commandsDir, { recursive: true });
@@ -567,7 +568,7 @@ async function scaffoldClaudeCommands(projectRoot, outputFormat) {
 		const taskToolCount = await taskToolGen.writeDashArtifacts(commandsDir, taskToolArtifacts);
 		const total = agentCount + workflowCount + taskToolCount;
 		if (outputFormat !== "json") process.stdout.write(`Generated ${String(total)} Claude Code commands (${String(agentCount)} agents, ${String(workflowCount)} workflows, ${String(taskToolCount)} tasks/tools)\n`);
-		logger$16.info({
+		logger$17.info({
 			agentCount,
 			workflowCount,
 			taskToolCount,
@@ -577,7 +578,7 @@ async function scaffoldClaudeCommands(projectRoot, outputFormat) {
 	} catch (err) {
 		const msg = err instanceof Error ? err.message : String(err);
 		if (outputFormat !== "json") process.stderr.write(`Warning: .claude/commands/ generation failed: ${msg}\n`);
-		logger$16.warn({ err }, "scaffoldClaudeCommands failed; init continues");
+		logger$17.warn({ err }, "scaffoldClaudeCommands failed; init continues");
 	}
 }
 const PROVIDER_DEFAULTS = DEFAULT_CONFIG.providers;
@@ -651,7 +652,7 @@ async function runInitAction(options) {
 			discoveryReport = await registry.discoverAndRegister();
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
-			logger$16.error({ err }, "Adapter discovery failed");
+			logger$17.error({ err }, "Adapter discovery failed");
 			if (outputFormat === "json") process.stdout.write(formatOutput(null, "json", false, `Adapter discovery failed: ${message}`) + "\n");
 			else process.stderr.write(`  Error: adapter discovery failed — ${message}\n`);
 			return INIT_EXIT_ERROR;
@@ -700,12 +701,12 @@ async function runInitAction(options) {
 				return INIT_EXIT_ERROR;
 			}
 			if (force && existsSync(localManifest)) {
-				logger$16.info({ pack: packName }, "Replacing existing pack with bundled version");
+				logger$17.info({ pack: packName }, "Replacing existing pack with bundled version");
 				process.stderr.write(`Warning: Replacing existing pack '${packName}' with bundled version\n`);
 			}
 			mkdirSync(dirname(packPath), { recursive: true });
 			cpSync(bundledPackPath, packPath, { recursive: true });
-			logger$16.info({
+			logger$17.info({
 				pack: packName,
 				dest: packPath
 			}, "Scaffolded methodology pack");
@@ -758,7 +759,7 @@ async function runInitAction(options) {
 		const msg = err instanceof Error ? err.message : String(err);
 		if (outputFormat === "json") process.stdout.write(formatOutput(null, "json", false, msg) + "\n");
 		else process.stderr.write(`Error: ${msg}\n`);
-		logger$16.error({ err }, "init failed");
+		logger$17.error({ err }, "init failed");
 		return INIT_EXIT_ERROR;
 	}
 }
@@ -804,7 +805,7 @@ function formatUnsupportedVersionError(formatType, version, supported) {
 
 //#endregion
 //#region src/modules/config/config-system-impl.ts
-const logger$15 = createLogger("config");
+const logger$16 = createLogger("config");
 function deepMerge(base, override) {
 	const result = { ...base };
 	for (const [key, val] of Object.entries(override)) if (val !== null && val !== void 0 && typeof val === "object" && !Array.isArray(val) && typeof result[key] === "object" && result[key] !== null && !Array.isArray(result[key])) result[key] = deepMerge(result[key], val);
@@ -849,7 +850,7 @@ function readEnvOverrides() {
 	}
 	const parsed = PartialSubstrateConfigSchema.safeParse(overrides);
 	if (!parsed.success) {
-		logger$15.warn({ errors: parsed.error.issues }, "Invalid environment variable overrides ignored");
+		logger$16.warn({ errors: parsed.error.issues }, "Invalid environment variable overrides ignored");
 		return {};
 	}
 	return parsed.data;
@@ -913,7 +914,7 @@ var ConfigSystemImpl = class {
 			throw new ConfigError(`Configuration validation failed:\n${issues}`, { issues: result.error.issues });
 		}
 		this._config = result.data;
-		logger$15.debug("Configuration loaded successfully");
+		logger$16.debug("Configuration loaded successfully");
 	}
 	getConfig() {
 		if (this._config === null) throw new ConfigError("Configuration has not been loaded. Call load() before getConfig().", {});
@@ -976,7 +977,7 @@ var ConfigSystemImpl = class {
 				if (version !== void 0 && typeof version === "string" && !isVersionSupported(version, SUPPORTED_CONFIG_FORMAT_VERSIONS)) if (defaultConfigMigrator.canMigrate(version, CURRENT_CONFIG_FORMAT_VERSION)) {
 					const migrationOutput = defaultConfigMigrator.migrate(rawObj, version, CURRENT_CONFIG_FORMAT_VERSION, filePath);
 					if (migrationOutput.result.success) {
-						logger$15.info({
+						logger$16.info({
 							from: version,
 							to: CURRENT_CONFIG_FORMAT_VERSION,
 							backup: migrationOutput.result.backupPath
@@ -1019,7 +1020,7 @@ function createConfigSystem(options = {}) {
 
 //#endregion
 //#region src/cli/commands/config.ts
-const logger$14 = createLogger("config-cmd");
+const logger$15 = createLogger("config-cmd");
 const CONFIG_EXIT_SUCCESS = 0;
 const CONFIG_EXIT_ERROR = 1;
 const CONFIG_EXIT_INVALID = 2;
@@ -1045,7 +1046,7 @@ async function runConfigShow(opts = {}) {
 			return CONFIG_EXIT_INVALID;
 		}
 		const message = err instanceof Error ? err.message : String(err);
-		logger$14.error({ err }, "Failed to load configuration");
+		logger$15.error({ err }, "Failed to load configuration");
 		process.stderr.write(`  Error loading configuration: ${message}\n`);
 		return CONFIG_EXIT_ERROR;
 	}
@@ -1119,7 +1120,7 @@ async function runConfigExport(opts = {}) {
 			return CONFIG_EXIT_INVALID;
 		}
 		const message = err instanceof Error ? err.message : String(err);
-		logger$14.error({ err }, "Failed to load configuration");
+		logger$15.error({ err }, "Failed to load configuration");
 		process.stderr.write(`Error loading configuration: ${message}\n`);
 		return CONFIG_EXIT_ERROR;
 	}
@@ -1273,7 +1274,7 @@ function registerConfigCommand(program, _version) {
 
 //#endregion
 //#region src/cli/commands/resume.ts
-const logger$13 = createLogger("resume-cmd");
+const logger$14 = createLogger("resume-cmd");
 async function runResumeAction(options) {
 	const { runId: specifiedRunId, stopAfter, outputFormat, projectRoot, concurrency, pack: packName } = options;
 	if (stopAfter !== void 0 && !VALID_PHASES.includes(stopAfter)) {
@@ -1355,7 +1356,7 @@ async function runResumeAction(options) {
 		const msg = err instanceof Error ? err.message : String(err);
 		if (outputFormat === "json") process.stdout.write(formatOutput(null, "json", false, msg) + "\n");
 		else process.stderr.write(`Error: ${msg}\n`);
-		logger$13.error({ err }, "auto resume failed");
+		logger$14.error({ err }, "auto resume failed");
 		return 1;
 	} finally {
 		try {
@@ -1506,7 +1507,7 @@ async function runFullPipelineFromPhase(options) {
 							});
 						}
 					} catch (err) {
-						logger$13.warn({ err }, "Failed to record token usage");
+						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);
@@ -1565,7 +1566,7 @@ async function runFullPipelineFromPhase(options) {
 		const msg = err instanceof Error ? err.message : String(err);
 		if (outputFormat === "json") process.stdout.write(formatOutput(null, "json", false, msg) + "\n");
 		else process.stderr.write(`Error: ${msg}\n`);
-		logger$13.error({ err }, "pipeline from phase failed");
+		logger$14.error({ err }, "pipeline from phase failed");
 		return 1;
 	} finally {
 		try {
@@ -1590,7 +1591,7 @@ function registerResumeCommand(program, _version = "0.0.0", projectRoot = proces
 
 //#endregion
 //#region src/cli/commands/status.ts
-const logger$12 = createLogger("status-cmd");
+const logger$13 = createLogger("status-cmd");
 async function runStatusAction(options) {
 	const { outputFormat, runId, projectRoot } = options;
 	const dbRoot = await resolveMainRepoRoot(projectRoot);
@@ -1667,7 +1668,7 @@ async function runStatusAction(options) {
 		const msg = err instanceof Error ? err.message : String(err);
 		if (outputFormat === "json") process.stdout.write(formatOutput(null, "json", false, msg) + "\n");
 		else process.stderr.write(`Error: ${msg}\n`);
-		logger$12.error({ err }, "status action failed");
+		logger$13.error({ err }, "status action failed");
 		return 1;
 	} finally {
 		try {
@@ -2091,7 +2092,7 @@ Analyze thoroughly and return ONLY the JSON array with no additional text.`;
 
 //#endregion
 //#region src/cli/commands/amend.ts
-const logger$11 = createLogger("amend-cmd");
+const logger$12 = createLogger("amend-cmd");
 /**
 * Detect and apply supersessions after a phase completes in an amendment run.
 *
@@ -2122,7 +2123,7 @@ function runPostPhaseSupersessionDetection(db, amendmentRunId, currentPhase, han
 			});
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
-			logger$11.warn({
+			logger$12.warn({
 				err,
 				originalId: parentMatch.id,
 				supersedingId: newDec.id
@@ -2257,7 +2258,7 @@ async function runAmendAction(options) {
 		for (let i = startIdx; i < phaseOrder.length; i++) {
 			const currentPhase = phaseOrder[i];
 			const amendmentContext = handler.loadContextForPhase(currentPhase);
-			logger$11.info({
+			logger$12.info({
 				phase: currentPhase,
 				amendmentContextLen: amendmentContext.length
 			}, "Amendment context loaded for phase");
@@ -2377,7 +2378,7 @@ async function runAmendAction(options) {
 	} catch (err) {
 		const msg = err instanceof Error ? err.message : String(err);
 		process.stderr.write(`Error: ${msg}\n`);
-		logger$11.error({ err }, "amend failed");
+		logger$12.error({ err }, "amend failed");
 		return 1;
 	} finally {
 		try {
@@ -2402,21 +2403,47 @@ function registerAmendCommand(program, _version = "0.0.0", projectRoot = process
 
 //#endregion
 //#region src/cli/commands/health.ts
-const logger$10 = createLogger("health-cmd");
-function inspectProcessTree() {
+const logger$11 = createLogger("health-cmd");
+/** Default stall threshold in seconds — also used by supervisor default */
+const DEFAULT_STALL_THRESHOLD_SECONDS = 600;
+/**
+* Determine whether a ps output line represents the substrate pipeline orchestrator.
+* Handles invocation via:
+*   - `substrate run` (globally installed)
+*   - `substrate-ai run`
+*   - `node dist/cli/index.js run` (npm run substrate:dev)
+*   - `npx substrate run`
+*   - any node process whose command contains `run` with `--events` or `--stories`
+*/
+function isOrchestratorProcessLine(line) {
+	if (line.includes("grep")) return false;
+	if (line.includes("substrate run")) return true;
+	if (line.includes("substrate-ai run")) return true;
+	if (line.includes("index.js run")) return true;
+	if (line.includes("node") && /\srun(\s|$)/.test(line) && (line.includes("--events") || line.includes("--stories"))) return true;
+	return false;
+}
+function inspectProcessTree(execFileSyncOverride) {
 	const result = {
 		orchestrator_pid: null,
 		child_pids: [],
 		zombies: []
 	};
 	try {
-		const { execFileSync } = __require("node:child_process");
-		const psOutput = execFileSync("ps", ["-eo", "pid,ppid,stat,command"], {
+		let psOutput;
+		if (execFileSyncOverride !== void 0) psOutput = execFileSyncOverride("ps", ["-eo", "pid,ppid,stat,command"], {
 			encoding: "utf-8",
 			timeout: 5e3
 		});
+		else {
+			const { execFileSync } = __require("node:child_process");
+			psOutput = execFileSync("ps", ["-eo", "pid,ppid,stat,command"], {
+				encoding: "utf-8",
+				timeout: 5e3
+			});
+		}
 		const lines = psOutput.split("\n");
-		for (const line of lines) if (line.includes("substrate run") && !line.includes("grep")) {
+		for (const line of lines) if (isOrchestratorProcessLine(line)) {
 			const match = line.trim().match(/^(\d+)/);
 			if (match) {
 				result.orchestrator_pid = parseInt(match[1], 10);
@@ -2477,7 +2504,7 @@ async function getAutoHealthData(options) {
 		if (runId !== void 0) run = getPipelineRunById(db, runId);
 		else run = getLatestRun(db);
 		if (run === void 0) return NO_PIPELINE;
-		const updatedAt = new Date(run.updated_at);
+		const updatedAt = parseDbTimestampAsUtc(run.updated_at);
 		const stalenessSeconds = Math.round((Date.now() - updatedAt.getTime()) / 1e3);
 		let storyDetails = {};
 		let active = 0;
@@ -2499,8 +2526,9 @@ async function getAutoHealthData(options) {
 		} catch {}
 		const processInfo = inspectProcessTree();
 		let verdict = "NO_PIPELINE_RUNNING";
-		if (run.status === "running") if (processInfo.zombies.length > 0) verdict = "STALLED";
-		else if (stalenessSeconds > 600) verdict = "STALLED";
+		if (run.status === "running") if (processInfo.orchestrator_pid === null && active === 0 && completed > 0) verdict = "NO_PIPELINE_RUNNING";
+		else if (processInfo.zombies.length > 0) verdict = "STALLED";
+		else if (stalenessSeconds > DEFAULT_STALL_THRESHOLD_SECONDS) verdict = "STALLED";
 		else if (processInfo.orchestrator_pid !== null && processInfo.child_pids.length === 0 && active > 0) verdict = "STALLED";
 		else verdict = "HEALTHY";
 		else if (run.status === "completed" || run.status === "failed" || run.status === "stopped") verdict = "NO_PIPELINE_RUNNING";
@@ -2526,124 +2554,31 @@ async function getAutoHealthData(options) {
 	}
 }
 async function runHealthAction(options) {
-	const { outputFormat, runId, projectRoot } = options;
-	const dbRoot = await resolveMainRepoRoot(projectRoot);
-	const dbPath = join(dbRoot, ".substrate", "substrate.db");
-	if (!existsSync(dbPath)) {
-		const output = {
-			verdict: "NO_PIPELINE_RUNNING",
-			run_id: null,
-			status: null,
-			current_phase: null,
-			staleness_seconds: 0,
-			last_activity: "",
-			process: {
-				orchestrator_pid: null,
-				child_pids: [],
-				zombies: []
-			},
-			stories: {
-				active: 0,
-				completed: 0,
-				escalated: 0,
-				details: {}
-			}
-		};
-		if (outputFormat === "json") process.stdout.write(formatOutput(output, "json", true) + "\n");
-		else process.stdout.write("NO_PIPELINE_RUNNING — no substrate database found\n");
-		return 0;
-	}
-	const dbWrapper = new DatabaseWrapper(dbPath);
+	const { outputFormat } = options;
 	try {
-		dbWrapper.open();
-		const db = dbWrapper.db;
-		let run;
-		if (runId !== void 0) run = getPipelineRunById(db, runId);
-		else run = getLatestRun(db);
-		if (run === void 0) {
-			const output$1 = {
-				verdict: "NO_PIPELINE_RUNNING",
-				run_id: null,
-				status: null,
-				current_phase: null,
-				staleness_seconds: 0,
-				last_activity: "",
-				process: {
-					orchestrator_pid: null,
-					child_pids: [],
-					zombies: []
-				},
-				stories: {
-					active: 0,
-					completed: 0,
-					escalated: 0,
-					details: {}
-				}
-			};
-			if (outputFormat === "json") process.stdout.write(formatOutput(output$1, "json", true) + "\n");
-			else process.stdout.write("NO_PIPELINE_RUNNING — no pipeline runs found\n");
-			return 0;
-		}
-		const updatedAt = new Date(run.updated_at);
-		const stalenessSeconds = Math.round((Date.now() - updatedAt.getTime()) / 1e3);
-		let storyDetails = {};
-		let active = 0;
-		let completed = 0;
-		let escalated = 0;
-		try {
-			if (run.token_usage_json) {
-				const state = JSON.parse(run.token_usage_json);
-				if (state.stories) for (const [key, s] of Object.entries(state.stories)) {
-					storyDetails[key] = {
-						phase: s.phase,
-						review_cycles: s.reviewCycles
-					};
-					if (s.phase === "COMPLETE") completed++;
-					else if (s.phase === "ESCALATED") escalated++;
-					else if (s.phase !== "PENDING") active++;
-				}
-			}
-		} catch {}
-		const processInfo = inspectProcessTree();
-		let verdict = "NO_PIPELINE_RUNNING";
-		if (run.status === "running") if (processInfo.zombies.length > 0) verdict = "STALLED";
-		else if (stalenessSeconds > 600) verdict = "STALLED";
-		else if (processInfo.orchestrator_pid !== null && processInfo.child_pids.length === 0 && active > 0) verdict = "STALLED";
-		else verdict = "HEALTHY";
-		else if (run.status === "completed" || run.status === "failed" || run.status === "stopped") verdict = "NO_PIPELINE_RUNNING";
-		const output = {
-			verdict,
-			run_id: run.id,
-			status: run.status,
-			current_phase: run.current_phase,
-			staleness_seconds: stalenessSeconds,
-			last_activity: run.updated_at,
-			process: processInfo,
-			stories: {
-				active,
-				completed,
-				escalated,
-				details: storyDetails
-			}
-		};
-		if (outputFormat === "json") process.stdout.write(formatOutput(output, "json", true) + "\n");
+		const health = await getAutoHealthData(options);
+		if (outputFormat === "json") process.stdout.write(formatOutput(health, "json", true) + "\n");
 		else {
-			const verdictLabel = verdict === "HEALTHY" ? "HEALTHY" : verdict === "STALLED" ? "STALLED" : "NO PIPELINE RUNNING";
+			const verdictLabel = health.verdict === "HEALTHY" ? "HEALTHY" : health.verdict === "STALLED" ? "STALLED" : "NO PIPELINE RUNNING";
 			process.stdout.write(`\nPipeline Health: ${verdictLabel}\n`);
-			process.stdout.write(`  Run:          ${run.id}\n`);
-			process.stdout.write(`  Status:       ${run.status}\n`);
-			process.stdout.write(`  Phase:        ${run.current_phase ?? "N/A"}\n`);
-			process.stdout.write(`  Last Active:  ${run.updated_at} (${stalenessSeconds}s ago)\n`);
-			if (processInfo.orchestrator_pid !== null) {
-				process.stdout.write(`  Orchestrator: PID ${processInfo.orchestrator_pid}\n`);
-				process.stdout.write(`  Children:     ${processInfo.child_pids.length} active`);
-				if (processInfo.zombies.length > 0) process.stdout.write(` (${processInfo.zombies.length} ZOMBIE)`);
-				process.stdout.write("\n");
-			} else process.stdout.write("  Orchestrator: not running\n");
-			if (Object.keys(storyDetails).length > 0) {
-				process.stdout.write("\n  Stories:\n");
-				for (const [key, s] of Object.entries(storyDetails)) process.stdout.write(`    ${key}: ${s.phase} (${s.review_cycles} review cycles)\n`);
-				process.stdout.write(`\n  Summary: ${active} active, ${completed} completed, ${escalated} escalated\n`);
+			if (health.run_id !== null) {
+				process.stdout.write(`  Run:          ${health.run_id}\n`);
+				process.stdout.write(`  Status:       ${health.status}\n`);
+				process.stdout.write(`  Phase:        ${health.current_phase ?? "N/A"}\n`);
+				process.stdout.write(`  Last Active:  ${health.last_activity} (${health.staleness_seconds}s ago)\n`);
+				const processInfo = health.process;
+				if (processInfo.orchestrator_pid !== null) {
+					process.stdout.write(`  Orchestrator: PID ${processInfo.orchestrator_pid}\n`);
+					process.stdout.write(`  Children:     ${processInfo.child_pids.length} active`);
+					if (processInfo.zombies.length > 0) process.stdout.write(` (${processInfo.zombies.length} ZOMBIE)`);
+					process.stdout.write("\n");
+				} else process.stdout.write("  Orchestrator: not running\n");
+				const storyDetails = health.stories.details;
+				if (Object.keys(storyDetails).length > 0) {
+					process.stdout.write("\n  Stories:\n");
+					for (const [key, s] of Object.entries(storyDetails)) process.stdout.write(`    ${key}: ${s.phase} (${s.review_cycles} review cycles)\n`);
+					process.stdout.write(`\n  Summary: ${health.stories.active} active, ${health.stories.completed} completed, ${health.stories.escalated} escalated\n`);
+				}
 			}
 		}
 		return 0;
@@ -2651,12 +2586,8 @@ async function runHealthAction(options) {
 		const msg = err instanceof Error ? err.message : String(err);
 		if (outputFormat === "json") process.stdout.write(formatOutput(null, "json", false, msg) + "\n");
 		else process.stderr.write(`Error: ${msg}\n`);
-		logger$10.error({ err }, "health action failed");
+		logger$11.error({ err }, "health action failed");
 		return 1;
-	} finally {
-		try {
-			dbWrapper.close();
-		} catch {}
 	}
 }
 function registerHealthCommand(program, _version = "0.0.0", projectRoot = process.cwd()) {
@@ -2699,6 +2630,36 @@ function defaultSupervisorDeps() {
 				}
 			};
 		})(),
+		getTokenSnapshot: (runId, projectRoot) => {
+			try {
+				const dbPath = join(projectRoot, ".substrate", "substrate.db");
+				if (!existsSync(dbPath)) return {
+					input: 0,
+					output: 0,
+					cost_usd: 0
+				};
+				const dbWrapper = new DatabaseWrapper(dbPath);
+				try {
+					dbWrapper.open();
+					const agg = aggregateTokenUsageForRun(dbWrapper.db, runId);
+					return {
+						input: agg.input,
+						output: agg.output,
+						cost_usd: agg.cost
+					};
+				} finally {
+					try {
+						dbWrapper.close();
+					} catch {}
+				}
+			} catch {
+				return {
+					input: 0,
+					output: 0,
+					cost_usd: 0
+				};
+			}
+		},
 		runAnalysis: async (runId, projectRoot) => {
 			const dbPath = join(projectRoot, ".substrate", "substrate.db");
 			if (!existsSync(dbPath)) return;
@@ -2740,7 +2701,7 @@ function defaultSupervisorDeps() {
 */
 async function runSupervisorAction(options, deps = {}) {
 	const { pollInterval, stallThreshold, maxRestarts, outputFormat, projectRoot, runId, pack, experiment, maxExperiments } = options;
-	const { getHealth, killPid, resumePipeline, sleep, incrementRestarts, runAnalysis } = {
+	const { getHealth, killPid, resumePipeline, sleep, incrementRestarts, runAnalysis, getTokenSnapshot } = {
 		...defaultSupervisorDeps(),
 		...deps
 	};
@@ -2764,6 +2725,36 @@ async function runSupervisorAction(options, deps = {}) {
 			projectRoot
 		});
 		const ts = new Date().toISOString();
+		if (outputFormat === "json") {
+			const tokenSnapshot = health.run_id !== null ? getTokenSnapshot(health.run_id, projectRoot) : {
+				input: 0,
+				output: 0,
+				cost_usd: 0
+			};
+			const proc = health.process ?? {
+				orchestrator_pid: null,
+				child_pids: [],
+				zombies: []
+			};
+			emitEvent({
+				type: "supervisor:poll",
+				run_id: health.run_id,
+				verdict: health.verdict,
+				staleness_seconds: health.staleness_seconds,
+				stories: {
+					active: health.stories.active,
+					completed: health.stories.completed,
+					escalated: health.stories.escalated
+				},
+				story_details: health.stories.details,
+				tokens: tokenSnapshot,
+				process: {
+					orchestrator_pid: proc.orchestrator_pid,
+					child_count: proc.child_pids.length,
+					zombie_count: proc.zombies.length
+				}
+			});
+		}
 		log(`[${ts}] Health: ${health.verdict} | staleness=${health.staleness_seconds}s | stories: active=${health.stories.active} completed=${health.stories.completed} escalated=${health.stories.escalated}`);
 		if (health.verdict === "NO_PIPELINE_RUNNING") {
 			const elapsedSeconds = Math.round((Date.now() - startTime) / 1e3);
@@ -2832,7 +2823,7 @@ async function runSupervisorAction(options, deps = {}) {
 );
 							const { getLatestRun: getLatest } = await import(
 								/* @vite-ignore */
-								"../decisions-WIsicZiG.js"
+								"../decisions-DKXc-jnv.js"
 );
 							const dbPath = join(projectRoot, ".substrate", "substrate.db");
 							const expDbWrapper = new DatabaseWrapper(dbPath);
@@ -2842,7 +2833,7 @@ async function runSupervisorAction(options, deps = {}) {
 								const expDb = expDbWrapper.db;
 								const { runRunAction: runPipeline } = await import(
 									/* @vite-ignore */
-									"../run-CRmhkcwN.js"
+									"../run-XkrV99HV.js"
 );
 								const runStoryFn = async (opts) => {
 									const exitCode = await runPipeline({
@@ -2999,7 +2990,7 @@ function registerSupervisorCommand(program, _version = "0.0.0", projectRoot = pr
 
 //#endregion
 //#region src/cli/commands/metrics.ts
-const logger$9 = createLogger("metrics-cmd");
+const logger$10 = createLogger("metrics-cmd");
 async function runMetricsAction(options) {
 	const { outputFormat, projectRoot, limit = 10, compare, tagBaseline, analysis } = options;
 	if (analysis !== void 0) {
@@ -3105,7 +3096,7 @@ async function runMetricsAction(options) {
 		const msg = err instanceof Error ? err.message : String(err);
 		if (outputFormat === "json") process.stdout.write(formatOutput(null, "json", false, msg) + "\n");
 		else process.stderr.write(`Error: ${msg}\n`);
-		logger$9.error({ err }, "metrics action failed");
+		logger$10.error({ err }, "metrics action failed");
 		return 1;
 	} finally {
 		try {
@@ -3359,7 +3350,7 @@ function getPlanningCostTotal(db, sessionId) {
 function getLatestSessionId(_db) {
 	return null;
 }
-const logger$8 = createLogger("cost-cmd");
+const logger$9 = createLogger("cost-cmd");
 const COST_EXIT_SUCCESS = 0;
 const COST_EXIT_ERROR = 1;
 /**
@@ -3605,7 +3596,7 @@ async function runCostAction(options) {
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		process.stderr.write(`Error: ${message}\n`);
-		logger$8.error({ err }, "runCostAction failed");
+		logger$9.error({ err }, "runCostAction failed");
 		return COST_EXIT_ERROR;
 	} finally {
 		if (wrapper !== null) try {
@@ -3707,7 +3698,7 @@ function applyMonitorSchema(db) {
 
 //#endregion
 //#region src/persistence/monitor-database.ts
-const logger$7 = createLogger("persistence:monitor-db");
+const logger$8 = createLogger("persistence:monitor-db");
 var MonitorDatabaseImpl = class {
 	_db = null;
 	_path;
@@ -3718,10 +3709,10 @@ var MonitorDatabaseImpl = class {
 		this._open();
 	}
 	_open() {
-		logger$7.info({ path: this._path }, "Opening monitor database");
+		logger$8.info({ path: this._path }, "Opening monitor database");
 		this._db = new BetterSqlite3(this._path);
 		const walResult = this._db.pragma("journal_mode = WAL");
-		if (walResult?.[0]?.journal_mode !== "wal") logger$7.warn({ result: walResult?.[0]?.journal_mode }, "Monitor DB: WAL pragma did not confirm wal mode");
+		if (walResult?.[0]?.journal_mode !== "wal") logger$8.warn({ result: walResult?.[0]?.journal_mode }, "Monitor DB: WAL pragma did not confirm wal mode");
 		this._db.pragma("synchronous = NORMAL");
 		this._db.pragma("busy_timeout = 5000");
 		this._db.pragma("foreign_keys = ON");
@@ -3756,7 +3747,7 @@ var MonitorDatabaseImpl = class {
         total_retries       = total_retries + @retries,
         last_updated        = @lastUpdated
     `);
-		logger$7.info({ path: this._path }, "Monitor database ready");
+		logger$8.info({ path: this._path }, "Monitor database ready");
 	}
 	_assertOpen() {
 		if (this._db === null) throw new Error("MonitorDatabase: connection is closed");
@@ -3905,7 +3896,7 @@ var MonitorDatabaseImpl = class {
 		const db = this._assertOpen();
 		const cutoff = new Date(Date.now() - retentionDays * 24 * 60 * 60 * 1e3).toISOString();
 		const result = db.prepare("DELETE FROM task_metrics WHERE recorded_at < @cutoff").run({ cutoff });
-		logger$7.info({
+		logger$8.info({
 			cutoff,
 			deleted: result.changes
 		}, "Pruned old task_metrics rows");
@@ -3944,13 +3935,13 @@ var MonitorDatabaseImpl = class {
 			db.exec("ROLLBACK");
 			throw err;
 		}
-		logger$7.info("Rebuilt performance_aggregates from task_metrics");
+		logger$8.info("Rebuilt performance_aggregates from task_metrics");
 	}
 	resetAllData() {
 		const db = this._assertOpen();
 		db.exec("DELETE FROM task_metrics");
 		db.exec("DELETE FROM performance_aggregates");
-		logger$7.info({ path: this._path }, "Monitor data reset — all rows deleted");
+		logger$8.info({ path: this._path }, "Monitor data reset — all rows deleted");
 	}
 	getTaskMetricsDateRange() {
 		const db = this._assertOpen();
@@ -3967,7 +3958,7 @@ var MonitorDatabaseImpl = class {
 		if (this._db === null) return;
 		this._db.close();
 		this._db = null;
-		logger$7.info({ path: this._path }, "Monitor database closed");
+		logger$8.info({ path: this._path }, "Monitor database closed");
 	}
 	/**
 	* Access the raw underlying database for testing purposes only.
@@ -3980,7 +3971,7 @@ var MonitorDatabaseImpl = class {
 
 //#endregion
 //#region src/modules/monitor/recommendation-engine.ts
-const logger$6 = createLogger("monitor:recommendations");
+const logger$7 = createLogger("monitor:recommendations");
 var RecommendationEngine = class {
 	_monitorDb;
 	_filters;
@@ -4013,7 +4004,7 @@ var RecommendationEngine = class {
 		const sinceDate = new Date(Date.now() - this._historyDays * 24 * 60 * 60 * 1e3).toISOString();
 		const aggregates = this._monitorDb.getAggregates({ sinceDate });
 		if (aggregates.length === 0) {
-			logger$6.debug("No performance aggregates found — no recommendations to generate");
+			logger$7.debug("No performance aggregates found — no recommendations to generate");
 			return [];
 		}
 		const byTaskType = new Map();
@@ -4078,7 +4069,7 @@ var RecommendationEngine = class {
 			if (confDiff !== 0) return confDiff;
 			return b.improvement_percentage - a.improvement_percentage;
 		});
-		logger$6.debug({ count: recommendations.length }, "Generated routing recommendations");
+		logger$7.debug({ count: recommendations.length }, "Generated routing recommendations");
 		return recommendations;
 	}
 	/**
@@ -4244,7 +4235,7 @@ function generateMonitorReport(monitorDb, options = {}) {
 
 //#endregion
 //#region src/cli/commands/monitor.ts
-const logger$5 = createLogger("monitor-cmd");
+const logger$6 = createLogger("monitor-cmd");
 const MONITOR_EXIT_SUCCESS = 0;
 const MONITOR_EXIT_ERROR = 1;
 /**
@@ -4447,7 +4438,7 @@ async function runMonitorReportAction(options) {
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		process.stderr.write(`Error: ${message}\n`);
-		logger$5.error({ err }, "runMonitorReportAction failed");
+		logger$6.error({ err }, "runMonitorReportAction failed");
 		return MONITOR_EXIT_ERROR;
 	} finally {
 		if (monitorDb !== null) try {
@@ -4509,7 +4500,7 @@ async function runMonitorStatusAction(options) {
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		process.stderr.write(`Error: ${message}\n`);
-		logger$5.error({ err }, "runMonitorStatusAction failed");
+		logger$6.error({ err }, "runMonitorStatusAction failed");
 		return MONITOR_EXIT_ERROR;
 	} finally {
 		if (monitorDb !== null) try {
@@ -4544,7 +4535,7 @@ async function runMonitorResetAction(options) {
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		process.stderr.write(`Error: ${message}\n`);
-		logger$5.error({ err }, "runMonitorResetAction failed");
+		logger$6.error({ err }, "runMonitorResetAction failed");
 		return MONITOR_EXIT_ERROR;
 	} finally {
 		if (monitorDb !== null) try {
@@ -4592,7 +4583,7 @@ async function runMonitorRecommendationsAction(options) {
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		process.stderr.write(`Error: ${message}\n`);
-		logger$5.error({ err }, "runMonitorRecommendationsAction failed");
+		logger$6.error({ err }, "runMonitorRecommendationsAction failed");
 		return MONITOR_EXIT_ERROR;
 	} finally {
 		if (monitorDb !== null) try {
@@ -4670,7 +4661,7 @@ function registerMonitorCommand(program, version = "0.0.0", projectRoot = proces
 
 //#endregion
 //#region src/modules/git-worktree/git-worktree-manager-impl.ts
-const logger$4 = createLogger("git-worktree");
+const logger$5 = createLogger("git-worktree");
 const BRANCH_PREFIX = "substrate/task-";
 const DEFAULT_WORKTREE_BASE = ".substrate-worktrees";
 var GitWorktreeManagerImpl = class {
@@ -4689,7 +4680,7 @@ var GitWorktreeManagerImpl = class {
 		this._db = db;
 		this._onTaskReady = ({ taskId }) => {
 			this._handleTaskReady(taskId).catch((err) => {
-				logger$4.error({
+				logger$5.error({
 					taskId,
 					err
 				}, "Unhandled error in _handleTaskReady");
@@ -4703,40 +4694,40 @@ var GitWorktreeManagerImpl = class {
 		};
 	}
 	async initialize() {
-		logger$4.info({ projectRoot: this._projectRoot }, "GitWorktreeManager.initialize()");
+		logger$5.info({ projectRoot: this._projectRoot }, "GitWorktreeManager.initialize()");
 		await this.verifyGitVersion();
 		const cleaned = await this.cleanupAllWorktrees();
-		if (cleaned > 0) logger$4.info({ cleaned }, "Recovered orphaned worktrees on startup");
+		if (cleaned > 0) logger$5.info({ cleaned }, "Recovered orphaned worktrees on startup");
 		this._eventBus.on("task:ready", this._onTaskReady);
 		this._eventBus.on("task:complete", this._onTaskComplete);
 		this._eventBus.on("task:failed", this._onTaskFailed);
-		logger$4.info("GitWorktreeManager initialized");
+		logger$5.info("GitWorktreeManager initialized");
 	}
 	async shutdown() {
-		logger$4.info("GitWorktreeManager.shutdown()");
+		logger$5.info("GitWorktreeManager.shutdown()");
 		this._eventBus.off("task:ready", this._onTaskReady);
 		this._eventBus.off("task:complete", this._onTaskComplete);
 		this._eventBus.off("task:failed", this._onTaskFailed);
 		await this.cleanupAllWorktrees();
-		logger$4.info("GitWorktreeManager shutdown complete");
+		logger$5.info("GitWorktreeManager shutdown complete");
 	}
 	async _handleTaskReady(taskId) {
-		logger$4.debug({ taskId }, "task:ready — creating worktree");
+		logger$5.debug({ taskId }, "task:ready — creating worktree");
 		try {
 			await this.createWorktree(taskId);
 		} catch (err) {
-			logger$4.error({
+			logger$5.error({
 				taskId,
 				err
 			}, "Failed to create worktree for task");
 		}
 	}
 	async _handleTaskDone(taskId) {
-		logger$4.debug({ taskId }, "task done — cleaning up worktree");
+		logger$5.debug({ taskId }, "task done — cleaning up worktree");
 		try {
 			await this.cleanupWorktree(taskId);
 		} catch (err) {
-			logger$4.warn({
+			logger$5.warn({
 				taskId,
 				err
 			}, "Failed to cleanup worktree for task");
@@ -4746,7 +4737,7 @@ var GitWorktreeManagerImpl = class {
 		if (!taskId || taskId.trim().length === 0) throw new Error("createWorktree: taskId must be a non-empty string");
 		const branchName = BRANCH_PREFIX + taskId;
 		const worktreePath = this.getWorktreePath(taskId);
-		logger$4.debug({
+		logger$5.debug({
 			taskId,
 			branchName,
 			worktreePath,
@@ -4766,7 +4757,7 @@ var GitWorktreeManagerImpl = class {
 			worktreePath,
 			createdAt
 		};
-		logger$4.info({
+		logger$5.info({
 			taskId,
 			branchName,
 			worktreePath
@@ -4776,7 +4767,7 @@ var GitWorktreeManagerImpl = class {
 	async cleanupWorktree(taskId) {
 		const branchName = BRANCH_PREFIX + taskId;
 		const worktreePath = this.getWorktreePath(taskId);
-		logger$4.debug({
+		logger$5.debug({
 			taskId,
 			branchName,
 			worktreePath
@@ -4786,7 +4777,7 @@ var GitWorktreeManagerImpl = class {
 			await access$1(worktreePath);
 			worktreeExists = true;
 		} catch {
-			logger$4.debug({
+			logger$5.debug({
 				taskId,
 				worktreePath
 			}, "cleanupWorktree: worktree does not exist, skipping removal");
@@ -4794,7 +4785,7 @@ var GitWorktreeManagerImpl = class {
 		if (worktreeExists) try {
 			await removeWorktree(worktreePath, this._projectRoot);
 		} catch (err) {
-			logger$4.warn({
+			logger$5.warn({
 				taskId,
 				worktreePath,
 				err
@@ -4803,7 +4794,7 @@ var GitWorktreeManagerImpl = class {
 		try {
 			await removeBranch(branchName, this._projectRoot);
 		} catch (err) {
-			logger$4.warn({
+			logger$5.warn({
 				taskId,
 				branchName,
 				err
@@ -4813,13 +4804,13 @@ var GitWorktreeManagerImpl = class {
 			taskId,
 			branchName
 		});
-		logger$4.info({
+		logger$5.info({
 			taskId,
 			branchName
 		}, "Worktree cleaned up");
 	}
 	async cleanupAllWorktrees() {
-		logger$4.debug({ projectRoot: this._projectRoot }, "cleanupAllWorktrees");
+		logger$5.debug({ projectRoot: this._projectRoot }, "cleanupAllWorktrees");
 		const orphanedPaths = await getOrphanedWorktrees(this._projectRoot, this._baseDirectory);
 		let cleaned = 0;
 		for (const worktreePath of orphanedPaths) {
@@ -4828,12 +4819,12 @@ var GitWorktreeManagerImpl = class {
 			try {
 				await removeWorktree(worktreePath, this._projectRoot);
 				worktreeRemoved = true;
-				logger$4.debug({
+				logger$5.debug({
 					taskId,
 					worktreePath
 				}, "cleanupAllWorktrees: removed orphaned worktree");
 			} catch (err) {
-				logger$4.warn({
+				logger$5.warn({
 					taskId,
 					worktreePath,
 					err
@@ -4843,12 +4834,12 @@ var GitWorktreeManagerImpl = class {
 			let branchRemoved = false;
 			try {
 				branchRemoved = await removeBranch(branchName, this._projectRoot);
-				if (branchRemoved) logger$4.debug({
+				if (branchRemoved) logger$5.debug({
 					taskId,
 					branchName
 				}, "cleanupAllWorktrees: removed orphaned branch");
 			} catch (err) {
-				logger$4.warn({
+				logger$5.warn({
 					taskId,
 					branchName,
 					err
@@ -4856,14 +4847,14 @@ var GitWorktreeManagerImpl = class {
 			}
 			if (worktreeRemoved) cleaned++;
 		}
-		if (cleaned > 0) logger$4.info({ cleaned }, "cleanupAllWorktrees: recovered orphaned worktrees");
+		if (cleaned > 0) logger$5.info({ cleaned }, "cleanupAllWorktrees: recovered orphaned worktrees");
 		return cleaned;
 	}
 	async detectConflicts(taskId, targetBranch = "main") {
 		if (!taskId || taskId.trim().length === 0) throw new Error("detectConflicts: taskId must be a non-empty string");
 		const branchName = BRANCH_PREFIX + taskId;
 		const worktreePath = this.getWorktreePath(taskId);
-		logger$4.debug({
+		logger$5.debug({
 			taskId,
 			branchName,
 			targetBranch
@@ -4891,7 +4882,7 @@ var GitWorktreeManagerImpl = class {
 			branch: branchName,
 			conflictingFiles: report.conflictingFiles
 		});
-		logger$4.info({
+		logger$5.info({
 			taskId,
 			hasConflicts: report.hasConflicts,
 			conflictCount: conflictingFiles.length
@@ -4901,14 +4892,14 @@ var GitWorktreeManagerImpl = class {
 	async mergeWorktree(taskId, targetBranch = "main") {
 		if (!taskId || taskId.trim().length === 0) throw new Error("mergeWorktree: taskId must be a non-empty string");
 		const branchName = BRANCH_PREFIX + taskId;
-		logger$4.debug({
+		logger$5.debug({
 			taskId,
 			branchName,
 			targetBranch
 		}, "mergeWorktree");
 		const conflictReport = await this.detectConflicts(taskId, targetBranch);
 		if (conflictReport.hasConflicts) {
-			logger$4.info({
+			logger$5.info({
 				taskId,
 				conflictCount: conflictReport.conflictingFiles.length
 			}, "Merge skipped due to conflicts");
@@ -4930,7 +4921,7 @@ var GitWorktreeManagerImpl = class {
 			success: true,
 			mergedFiles
 		};
-		logger$4.info({
+		logger$5.info({
 			taskId,
 			branchName,
 			mergedFileCount: mergedFiles.length
@@ -4938,7 +4929,7 @@ var GitWorktreeManagerImpl = class {
 		return result;
 	}
 	async listWorktrees() {
-		logger$4.debug({
+		logger$5.debug({
 			projectRoot: this._projectRoot,
 			baseDirectory: this._baseDirectory
 		}, "listWorktrees");
@@ -4962,7 +4953,7 @@ var GitWorktreeManagerImpl = class {
 				createdAt
 			});
 		}
-		logger$4.debug({ count: results.length }, "listWorktrees: found worktrees");
+		logger$5.debug({ count: results.length }, "listWorktrees: found worktrees");
 		return results;
 	}
 	getWorktreePath(taskId) {
@@ -4982,7 +4973,7 @@ function createGitWorktreeManager(options) {
 
 //#endregion
 //#region src/cli/commands/merge.ts
-const logger$3 = createLogger("merge-cmd");
+const logger$4 = createLogger("merge-cmd");
 const MERGE_EXIT_SUCCESS = 0;
 const MERGE_EXIT_CONFLICT = 1;
 const MERGE_EXIT_ERROR = 2;
@@ -5020,7 +5011,7 @@ async function mergeTask(taskId, targetBranch, projectRoot) {
 		projectRoot
 	});
 	try {
-		logger$3.info({
+		logger$4.info({
 			taskId,
 			targetBranch
 		}, "Running conflict detection...");
@@ -5042,7 +5033,7 @@ async function mergeTask(taskId, targetBranch, projectRoot) {
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		console.error(`Error merging task "${taskId}": ${message}`);
-		logger$3.error({
+		logger$4.error({
 			taskId,
 			err
 		}, "merge --task failed");
@@ -5096,7 +5087,7 @@ async function mergeAll(targetBranch, projectRoot, taskIds) {
 			error: message
 		});
 		console.log(`  Error for task "${taskId}": ${message}`);
-		logger$3.error({
+		logger$4.error({
 			taskId,
 			err
 		}, "merge --all: task failed");
@@ -5149,7 +5140,7 @@ function registerMergeCommand(program, projectRoot = process.cwd()) {
 
 //#endregion
 //#region src/cli/commands/worktrees.ts
-const logger$2 = createLogger("worktrees-cmd");
+const logger$3 = createLogger("worktrees-cmd");
 const WORKTREES_EXIT_SUCCESS = 0;
 const WORKTREES_EXIT_ERROR = 1;
 /** Valid task statuses for filtering */
@@ -5276,7 +5267,7 @@ async function listWorktreesAction(options) {
 		try {
 			worktreeInfos = await manager.listWorktrees();
 		} catch (err) {
-			logger$2.error({ err }, "Failed to list worktrees");
+			logger$3.error({ err }, "Failed to list worktrees");
 			const message = err instanceof Error ? err.message : String(err);
 			process.stderr.write(`Error listing worktrees: ${message}\n`);
 			return WORKTREES_EXIT_ERROR;
@@ -5303,7 +5294,7 @@ async function listWorktreesAction(options) {
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		process.stderr.write(`Error: ${message}\n`);
-		logger$2.error({ err }, "listWorktreesAction failed");
+		logger$3.error({ err }, "listWorktreesAction failed");
 		return WORKTREES_EXIT_ERROR;
 	}
 }
@@ -5344,7 +5335,7 @@ function registerWorktreesCommand(program, version = "0.0.0", projectRoot = proc
 
 //#endregion
 //#region src/cli/commands/brainstorm.ts
-const logger$1 = createLogger("brainstorm-cmd");
+const logger$2 = createLogger("brainstorm-cmd");
 /**
 * Detect whether the project has existing planning artifacts that indicate
 * this is an amendment session (vs. a brand-new project brainstorm).
@@ -5390,13 +5381,13 @@ async function loadAmendmentContextDocuments(projectRoot) {
 	try {
 		brief = await readFile(briefPath, "utf-8");
 	} catch {
-		logger$1.warn({ briefPath }, "product-brief.md not found — continuing without brief context");
+		logger$2.warn({ briefPath }, "product-brief.md not found — continuing without brief context");
 		process.stderr.write(`Warning: product-brief.md not found at ${briefPath}\n`);
 	}
 	try {
 		prd = await readFile(prdPath, "utf-8");
 	} catch {
-		logger$1.warn({ prdPath }, "requirements.md not found — continuing without PRD context");
+		logger$2.warn({ prdPath }, "requirements.md not found — continuing without PRD context");
 		process.stderr.write(`Warning: requirements.md not found at ${prdPath}\n`);
 	}
 	return {
@@ -5605,7 +5596,7 @@ async function dispatchToPersonas(userPrompt, context, llmDispatch) {
 		}
 	];
 	const defaultDispatch = async (prompt, personaName) => {
-		logger$1.debug({
+		logger$2.debug({
 			personaName,
 			promptLength: prompt.length
 		}, "Dispatching to persona (stub mode)");
@@ -5622,7 +5613,7 @@ async function dispatchToPersonas(userPrompt, context, llmDispatch) {
 			};
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
-			logger$1.error({
+			logger$2.error({
 				err,
 				personaName: persona.name
 			}, "Persona dispatch failed");
@@ -5774,7 +5765,7 @@ async function runBrainstormSession(options, llmDispatch, rlInterface) {
 			}
 		});
 		rl.on("error", (err) => {
-			logger$1.error({ err }, "readline error");
+			logger$2.error({ err }, "readline error");
 			if (!sessionEnded) endSession(false);
 		});
 	});
@@ -5813,6 +5804,590 @@ function registerBrainstormCommand(program, _version = "0.0.0", projectRoot = pr
 	});
 }
 
+//#endregion
+//#region src/modules/export/renderers.ts
+/** Fields from analysis/product-brief decisions to render, in display order */
+const PRODUCT_BRIEF_FIELDS = [
+	"problem_statement",
+	"target_users",
+	"core_features",
+	"success_metrics",
+	"constraints",
+	"technology_constraints"
+];
+/**
+* Known acronyms that should appear fully uppercased when they are a standalone
+* word in a label (e.g. 'fr_coverage' → 'FR Coverage', 'api_style' → 'API Style').
+*/
+const UPPERCASE_ACRONYMS = new Set([
+	"fr",
+	"nfr",
+	"ux",
+	"api",
+	"db",
+	"id",
+	"url"
+]);
+/**
+* Convert a snake_case key to Title Case for display headings.
+* Known acronyms (fr, nfr, ux, api, db, id, url) are rendered fully uppercased.
+*/
+function fieldLabel(key) {
+	return key.replace(/_/g, " ").replace(/\b\w+/g, (word) => {
+		const lower = word.toLowerCase();
+		if (UPPERCASE_ACRONYMS.has(lower)) return lower.toUpperCase();
+		return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+	});
+}
+/**
+* Safely parse a JSON string; returns the original string if parsing fails.
+*/
+function safeParseJson(value) {
+	try {
+		return JSON.parse(value);
+	} catch {
+		return value;
+	}
+}
+/**
+* Render a decision value to a markdown-friendly string.
+* - Arrays → bulleted list items
+* - Objects → key: value lines
+* - Primitives → plain string
+*/
+function renderValue(rawValue) {
+	const parsed = safeParseJson(rawValue);
+	if (Array.isArray(parsed)) return parsed.map((item) => `- ${String(item)}`).join("\n");
+	if (typeof parsed === "object" && parsed !== null) return Object.entries(parsed).map(([k, v]) => `- **${fieldLabel(k)}**: ${String(v)}`).join("\n");
+	return String(parsed);
+}
+/**
+* Render analysis-phase decisions as a `product-brief.md` file.
+*
+* Merges `product-brief` category decisions with `technology-constraints`
+* category decisions (they are stored separately in the decision store).
+*
+* @param decisions - All decisions from the analysis phase (any category)
+* @returns Formatted markdown content for product-brief.md
+*/
+function renderProductBrief(decisions) {
+	const briefDecisions = decisions.filter((d) => d.category === "product-brief");
+	const techConstraintDecisions = decisions.filter((d) => d.category === "technology-constraints");
+	const briefMap = Object.fromEntries(briefDecisions.map((d) => [d.key, d.value]));
+	if (techConstraintDecisions.length > 0 && briefMap["technology_constraints"] === void 0) {
+		const tcBullets = techConstraintDecisions.flatMap((d) => {
+			const parsed = safeParseJson(d.value);
+			if (Array.isArray(parsed)) return parsed.map((item) => String(item));
+			return [String(parsed)];
+		});
+		briefMap["technology_constraints"] = JSON.stringify(tcBullets);
+	}
+	if (briefDecisions.length === 0 && techConstraintDecisions.length === 0) return "";
+	const parts = ["# Product Brief", ""];
+	for (const field of PRODUCT_BRIEF_FIELDS) {
+		const rawValue = briefMap[field];
+		if (rawValue === void 0) continue;
+		parts.push(`## ${fieldLabel(field)}`);
+		parts.push("");
+		parts.push(renderValue(rawValue));
+		parts.push("");
+	}
+	return parts.join("\n");
+}
+/**
+* Render planning-phase decisions (and requirements table) as a `prd.md` file.
+*
+* Sections rendered (when data is present):
+* - Project Classification (classification decisions)
+* - Functional Requirements (functional-requirements decisions)
+* - Non-Functional Requirements (non-functional-requirements decisions)
+* - Domain Model (domain-model decisions)
+* - User Stories (user-stories decisions)
+* - Tech Stack (tech-stack decisions)
+* - Out of Scope (out-of-scope decisions)
+*
+* @param decisions - All decisions from the planning phase
+* @param requirements - Requirements records from the requirements table (optional)
+* @returns Formatted markdown content for prd.md
+*/
+function renderPrd(decisions, requirements = []) {
+	if (decisions.length === 0) return "";
+	const parts = ["# Product Requirements Document", ""];
+	const classificationDecisions = decisions.filter((d) => d.category === "classification");
+	if (classificationDecisions.length > 0) {
+		parts.push("## Project Classification");
+		parts.push("");
+		for (const d of classificationDecisions) {
+			const parsed = safeParseJson(d.value);
+			if (Array.isArray(parsed)) {
+				parts.push(`**${fieldLabel(d.key)}**:`);
+				for (const item of parsed) parts.push(`- ${String(item)}`);
+			} else parts.push(`**${fieldLabel(d.key)}**: ${String(parsed)}`);
+		}
+		parts.push("");
+	}
+	const frDecisions = decisions.filter((d) => d.category === "functional-requirements");
+	if (frDecisions.length > 0) {
+		parts.push("## Functional Requirements");
+		parts.push("");
+		for (const d of frDecisions) {
+			const parsed = safeParseJson(d.value);
+			if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+				const fr = parsed;
+				const id = fr.id ?? d.key;
+				const priority = fr.priority ? ` [${fr.priority.toUpperCase()}]` : "";
+				parts.push(`- **${id}**${priority}: ${fr.description ?? d.value}`);
+				if (fr.acceptance_criteria && fr.acceptance_criteria.length > 0) for (const ac of fr.acceptance_criteria) parts.push(`  - ${ac}`);
+			} else parts.push(`- **${d.key}**: ${renderValue(d.value)}`);
+		}
+		parts.push("");
+	}
+	const nfrDecisions = decisions.filter((d) => d.category === "non-functional-requirements");
+	if (nfrDecisions.length > 0) {
+		parts.push("## Non-Functional Requirements");
+		parts.push("");
+		for (const d of nfrDecisions) {
+			const parsed = safeParseJson(d.value);
+			if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+				const nfr = parsed;
+				const id = nfr.id ?? d.key;
+				const cat = nfr.category ? ` [${nfr.category.toUpperCase()}]` : "";
+				parts.push(`- **${id}**${cat}: ${nfr.description ?? d.value}`);
+			} else parts.push(`- **${d.key}**: ${renderValue(d.value)}`);
+		}
+		parts.push("");
+	}
+	const domainDecisions = decisions.filter((d) => d.category === "domain-model");
+	if (domainDecisions.length > 0) {
+		parts.push("## Domain Model");
+		parts.push("");
+		for (const d of domainDecisions) parts.push(renderValue(d.value));
+		parts.push("");
+	}
+	const userStoryDecisions = decisions.filter((d) => d.category === "user-stories");
+	if (userStoryDecisions.length > 0) {
+		parts.push("## User Stories");
+		parts.push("");
+		for (const d of userStoryDecisions) {
+			const parsed = safeParseJson(d.value);
+			if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+				const us = parsed;
+				if (us.title) {
+					parts.push(`### ${us.title}`);
+					parts.push("");
+					if (us.description) {
+						parts.push(us.description);
+						parts.push("");
+					}
+				} else {
+					parts.push(renderValue(d.value));
+					parts.push("");
+				}
+			} else {
+				parts.push(renderValue(d.value));
+				parts.push("");
+			}
+		}
+	}
+	const techStackDecisions = decisions.filter((d) => d.category === "tech-stack");
+	if (techStackDecisions.length > 0) {
+		parts.push("## Tech Stack");
+		parts.push("");
+		for (const d of techStackDecisions) if (d.key === "tech_stack") {
+			const parsed = safeParseJson(d.value);
+			if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) for (const [k, v] of Object.entries(parsed)) parts.push(`- **${fieldLabel(k)}**: ${String(v)}`);
+			else parts.push(`- **${fieldLabel(d.key)}**: ${d.value}`);
+		} else parts.push(`- **${fieldLabel(d.key)}**: ${d.value}`);
+		parts.push("");
+	}
+	const outOfScopeDecisions = decisions.filter((d) => d.category === "out-of-scope");
+	if (outOfScopeDecisions.length > 0) {
+		parts.push("## Out of Scope");
+		parts.push("");
+		for (const d of outOfScopeDecisions) parts.push(renderValue(d.value));
+		parts.push("");
+	}
+	const functionalReqs = requirements.filter((r) => r.type === "functional");
+	const nonFunctionalReqs = requirements.filter((r) => r.type === "non_functional");
+	if ((functionalReqs.length > 0 || nonFunctionalReqs.length > 0) && frDecisions.length === 0 && nfrDecisions.length === 0) {
+		parts.push("## Requirements (from Requirements Table)");
+		parts.push("");
+		if (functionalReqs.length > 0) {
+			parts.push("### Functional Requirements");
+			parts.push("");
+			for (const r of functionalReqs) {
+				const priority = r.priority ? ` [${r.priority.toUpperCase()}]` : "";
+				parts.push(`- ${r.source ?? ""}${priority}: ${r.description}`);
+			}
+			parts.push("");
+		}
+		if (nonFunctionalReqs.length > 0) {
+			parts.push("### Non-Functional Requirements");
+			parts.push("");
+			for (const r of nonFunctionalReqs) {
+				const priority = r.priority ? ` [${r.priority.toUpperCase()}]` : "";
+				parts.push(`- ${priority}: ${r.description}`);
+			}
+			parts.push("");
+		}
+	}
+	return parts.join("\n");
+}
+/**
+* Render solutioning-phase architecture decisions as an `architecture.md` file.
+*
+* Groups all architecture decisions into a single `## Architecture Decisions`
+* section, formatting each as `**key**: value` with italicised rationale where
+* present.  The heading pattern matches the regex used by `seedMethodologyContext()`
+* so that the exported file can be round-tripped back into the decision store.
+*
+* @param decisions - All decisions from the solutioning phase (any category)
+* @returns Formatted markdown content for architecture.md, or '' if no data
+*/
+function renderArchitecture(decisions) {
+	const archDecisions = decisions.filter((d) => d.category === "architecture");
+	if (archDecisions.length === 0) return "";
+	const parts = ["# Architecture", ""];
+	parts.push("## Architecture Decisions");
+	parts.push("");
+	for (const d of archDecisions) {
+		const value = safeParseJson(d.value);
+		let displayValue;
+		if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+			displayValue = Object.entries(value).map(([k, v]) => `  - *${fieldLabel(k)}*: ${String(v)}`).join("\n");
+			parts.push(`**${d.key}**:`);
+			parts.push(displayValue);
+		} else if (Array.isArray(value)) {
+			displayValue = value.map((item) => `  - ${String(item)}`).join("\n");
+			parts.push(`**${d.key}**:`);
+			parts.push(displayValue);
+		} else {
+			displayValue = String(value);
+			if (d.rationale) parts.push(`**${d.key}**: ${displayValue} *(${d.rationale})*`);
+			else parts.push(`**${d.key}**: ${displayValue}`);
+		}
+	}
+	parts.push("");
+	return parts.join("\n");
+}
+/**
+* Render solutioning-phase epics and stories decisions as an `epics.md` file.
+*
+* Output format:
+* ```
+* ## Epic 1: Title
+* Description
+*
+* ### Story 1-1: Title
+* **Priority**: must
+* **Description**: ...
+* **Acceptance Criteria**:
+* - AC1
+* - AC2
+* ```
+*
+* The `## Epic N:` heading pattern is parsed by `parseEpicShards()` in
+* `seed-methodology-context.ts`, satisfying the round-trip contract (AC5).
+*
+* Stories are associated with their parent epic by the numeric prefix of the
+* story key (e.g., story key `2-3` → epic 2).
+*
+* @param decisions - All decisions from the solutioning phase (any category)
+* @returns Formatted markdown content for epics.md, or '' if no data
+*/
+function renderEpics(decisions) {
+	const epicDecisions = decisions.filter((d) => d.category === "epics");
+	const storyDecisions = decisions.filter((d) => d.category === "stories");
+	if (epicDecisions.length === 0 && storyDecisions.length === 0) return "";
+	const epicMap = new Map();
+	for (const d of epicDecisions) {
+		const match = /^epic-(\d+)$/i.exec(d.key);
+		if (match === null) continue;
+		const epicNum = parseInt(match[1], 10);
+		const parsed = safeParseJson(d.value);
+		if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+			const p = parsed;
+			epicMap.set(epicNum, {
+				num: epicNum,
+				title: p.title ?? `Epic ${epicNum}`,
+				description: p.description ?? ""
+			});
+		} else epicMap.set(epicNum, {
+			num: epicNum,
+			title: String(parsed),
+			description: ""
+		});
+	}
+	const storyMap = new Map();
+	for (const d of storyDecisions) {
+		const parsed = safeParseJson(d.value);
+		let story;
+		if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+			const p = parsed;
+			const storyKey = p.key ?? d.key;
+			const keyMatch = /^(\d+)-(\d+)/.exec(storyKey);
+			if (keyMatch === null) continue;
+			const epicNum = parseInt(keyMatch[1], 10);
+			const storyNum = parseInt(keyMatch[2], 10);
+			story = {
+				key: storyKey,
+				epicNum,
+				storyNum,
+				title: p.title ?? `Story ${storyKey}`,
+				description: p.description ?? "",
+				ac: p.acceptance_criteria ?? p.ac ?? [],
+				priority: p.priority ?? "must"
+			};
+		} else {
+			const storyKey = d.key;
+			const keyMatch = /^(\d+)-(\d+)/.exec(storyKey);
+			if (keyMatch === null) continue;
+			const epicNum = parseInt(keyMatch[1], 10);
+			const storyNum = parseInt(keyMatch[2], 10);
+			story = {
+				key: storyKey,
+				epicNum,
+				storyNum,
+				title: `Story ${storyKey}`,
+				description: String(parsed),
+				ac: [],
+				priority: "must"
+			};
+		}
+		if (!storyMap.has(story.epicNum)) storyMap.set(story.epicNum, []);
+		storyMap.get(story.epicNum).push(story);
+	}
+	for (const stories of storyMap.values()) stories.sort((a, b) => a.storyNum - b.storyNum);
+	const allEpicNums = new Set([...epicMap.keys(), ...storyMap.keys()]);
+	const sortedEpicNums = [...allEpicNums].sort((a, b) => a - b);
+	const parts = ["# Epics and Stories", ""];
+	for (const epicNum of sortedEpicNums) {
+		const epic = epicMap.get(epicNum);
+		const epicTitle = epic?.title ?? `Epic ${epicNum}`;
+		const epicDescription = epic?.description ?? "";
+		parts.push(`## Epic ${epicNum}: ${epicTitle}`);
+		parts.push("");
+		if (epicDescription) {
+			parts.push(epicDescription);
+			parts.push("");
+		}
+		const stories = storyMap.get(epicNum) ?? [];
+		for (const story of stories) {
+			parts.push(`### Story ${story.key}: ${story.title}`);
+			parts.push("");
+			parts.push(`**Priority**: ${story.priority}`);
+			if (story.description) parts.push(`**Description**: ${story.description}`);
+			if (story.ac.length > 0) {
+				parts.push("**Acceptance Criteria**:");
+				for (const ac of story.ac) parts.push(`- ${ac}`);
+			}
+			parts.push("");
+		}
+	}
+	return parts.join("\n");
+}
+/**
+* Render solutioning-phase readiness-findings decisions as a `readiness-report.md`.
+*
+* Groups findings by category, shows severity per finding, and emits an
+* overall pass/fail verdict based on whether any blockers were found.
+*
+* @param decisions - All decisions from the solutioning phase (any category)
+* @returns Formatted markdown content for readiness-report.md, or '' if no data
+*/
+function renderReadinessReport(decisions) {
+	const findingDecisions = decisions.filter((d) => d.category === "readiness-findings");
+	if (findingDecisions.length === 0) return "";
+	const findings = [];
+	for (const d of findingDecisions) {
+		const parsed = safeParseJson(d.value);
+		if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+			const p = parsed;
+			findings.push({
+				category: p.category ?? "general",
+				severity: p.severity ?? "minor",
+				description: p.description ?? String(parsed),
+				affected_items: p.affected_items ?? []
+			});
+		} else findings.push({
+			category: "general",
+			severity: "minor",
+			description: String(parsed),
+			affected_items: []
+		});
+	}
+	const hasCritical = findings.some((f) => f.severity === "blocker" || f.severity === "major");
+	const verdict = hasCritical ? "FAIL" : "PASS";
+	const parts = ["# Readiness Report", ""];
+	parts.push(`**Overall Verdict**: ${verdict}`);
+	parts.push("");
+	parts.push(`**Total Findings**: ${findings.length}`);
+	parts.push(`**Blockers**: ${findings.filter((f) => f.severity === "blocker").length}`);
+	parts.push(`**Major**: ${findings.filter((f) => f.severity === "major").length}`);
+	parts.push(`**Minor**: ${findings.filter((f) => f.severity === "minor").length}`);
+	parts.push("");
+	const byCategory = new Map();
+	for (const finding of findings) {
+		if (!byCategory.has(finding.category)) byCategory.set(finding.category, []);
+		byCategory.get(finding.category).push(finding);
+	}
+	const categoryOrder = [
+		"fr_coverage",
+		"architecture_compliance",
+		"story_quality",
+		"ux_alignment",
+		"dependency_validity",
+		"general"
+	];
+	const sortedCategories = [...byCategory.keys()].sort((a, b) => {
+		const ai = categoryOrder.indexOf(a);
+		const bi = categoryOrder.indexOf(b);
+		return (ai === -1 ? 999 : ai) - (bi === -1 ? 999 : bi);
+	});
+	for (const category of sortedCategories) {
+		const categoryFindings = byCategory.get(category);
+		const categoryLabel = fieldLabel(category);
+		parts.push(`## ${categoryLabel}`);
+		parts.push("");
+		for (const finding of categoryFindings) {
+			const severityTag = `[${finding.severity.toUpperCase()}]`;
+			parts.push(`- ${severityTag} ${finding.description}`);
+			if (finding.affected_items.length > 0) parts.push(`  - *Affected*: ${finding.affected_items.join(", ")}`);
+		}
+		parts.push("");
+	}
+	return parts.join("\n");
+}
+
+//#endregion
+//#region src/cli/commands/export.ts
+const logger$1 = createLogger("export-cmd");
+/**
+* Execute the export action.
+* Returns an exit code (0 = success, 1 = error).
+*/
+async function runExportAction(options) {
+	const { runId, outputDir, projectRoot, outputFormat } = options;
+	let dbWrapper;
+	try {
+		const dbRoot = await resolveMainRepoRoot(projectRoot);
+		const dbPath = join$1(dbRoot, ".substrate", "substrate.db");
+		if (!existsSync$1(dbPath)) {
+			const errorMsg = `Decision store not initialized. Run 'substrate init' first.`;
+			if (outputFormat === "json") process.stdout.write(JSON.stringify({ error: errorMsg }) + "\n");
+			else process.stderr.write(`Error: ${errorMsg}\n`);
+			return 1;
+		}
+		dbWrapper = new DatabaseWrapper(dbPath);
+		dbWrapper.open();
+		const db = dbWrapper.db;
+		let run;
+		if (runId !== void 0 && runId !== "") run = db.prepare("SELECT * FROM pipeline_runs WHERE id = ?").get(runId);
+		else run = getLatestRun(db);
+		if (run === void 0) {
+			const errorMsg = runId !== void 0 ? `Pipeline run '${runId}' not found.` : "No pipeline runs found. Run `substrate run` first.";
+			if (outputFormat === "json") process.stdout.write(JSON.stringify({ error: errorMsg }) + "\n");
+			else process.stderr.write(`Error: ${errorMsg}\n`);
+			return 1;
+		}
+		const activeRunId = run.id;
+		const resolvedOutputDir = isAbsolute(outputDir) ? outputDir : join$1(projectRoot, outputDir);
+		if (!existsSync$1(resolvedOutputDir)) mkdirSync$1(resolvedOutputDir, { recursive: true });
+		const filesWritten = [];
+		const phasesExported = [];
+		const analysisDecisions = getDecisionsByPhaseForRun(db, activeRunId, "analysis");
+		if (analysisDecisions.length > 0) {
+			const content = renderProductBrief(analysisDecisions);
+			if (content !== "") {
+				const filePath = join$1(resolvedOutputDir, "product-brief.md");
+				writeFileSync$1(filePath, content, "utf-8");
+				filesWritten.push(filePath);
+				phasesExported.push("analysis");
+				if (outputFormat === "human") process.stdout.write(`  Written: ${filePath}\n`);
+			}
+		}
+		const planningDecisions = getDecisionsByPhaseForRun(db, activeRunId, "planning");
+		if (planningDecisions.length > 0) {
+			const requirements = listRequirements(db).filter((r) => r.pipeline_run_id === activeRunId);
+			const content = renderPrd(planningDecisions, requirements);
+			if (content !== "") {
+				const filePath = join$1(resolvedOutputDir, "prd.md");
+				writeFileSync$1(filePath, content, "utf-8");
+				filesWritten.push(filePath);
+				if (!phasesExported.includes("planning")) phasesExported.push("planning");
+				if (outputFormat === "human") process.stdout.write(`  Written: ${filePath}\n`);
+			}
+		}
+		const solutioningDecisions = getDecisionsByPhaseForRun(db, activeRunId, "solutioning");
+		if (solutioningDecisions.length > 0) {
+			const archContent = renderArchitecture(solutioningDecisions);
+			if (archContent !== "") {
+				const filePath = join$1(resolvedOutputDir, "architecture.md");
+				writeFileSync$1(filePath, archContent, "utf-8");
+				filesWritten.push(filePath);
+				if (!phasesExported.includes("solutioning")) phasesExported.push("solutioning");
+				if (outputFormat === "human") process.stdout.write(`  Written: ${filePath}\n`);
+			}
+			const epicsContent = renderEpics(solutioningDecisions);
+			if (epicsContent !== "") {
+				const filePath = join$1(resolvedOutputDir, "epics.md");
+				writeFileSync$1(filePath, epicsContent, "utf-8");
+				filesWritten.push(filePath);
+				if (!phasesExported.includes("solutioning")) phasesExported.push("solutioning");
+				if (outputFormat === "human") process.stdout.write(`  Written: ${filePath}\n`);
+			}
+			const readinessContent = renderReadinessReport(solutioningDecisions);
+			if (readinessContent !== "") {
+				const filePath = join$1(resolvedOutputDir, "readiness-report.md");
+				writeFileSync$1(filePath, readinessContent, "utf-8");
+				filesWritten.push(filePath);
+				if (!phasesExported.includes("solutioning")) phasesExported.push("solutioning");
+				if (outputFormat === "human") process.stdout.write(`  Written: ${filePath}\n`);
+			}
+		}
+		if (outputFormat === "json") {
+			const result = {
+				files_written: filesWritten,
+				run_id: activeRunId,
+				phases_exported: phasesExported
+			};
+			process.stdout.write(JSON.stringify(result) + "\n");
+		} else {
+			if (filesWritten.length === 0) process.stdout.write(`No data found for run ${activeRunId}. The pipeline may not have completed any phases.\n`);
+			else process.stdout.write(`\nExported ${filesWritten.length} file(s) from run ${activeRunId}.\n`);
+			const skippedPhases = [];
+			if (!phasesExported.includes("analysis")) skippedPhases.push("analysis");
+			if (!phasesExported.includes("planning")) skippedPhases.push("planning");
+			if (!phasesExported.includes("solutioning")) skippedPhases.push("solutioning");
+			if (skippedPhases.length > 0) process.stdout.write(`Phases with no data (skipped): ${skippedPhases.join(", ")}\n`);
+		}
+		return 0;
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		if (outputFormat === "json") process.stdout.write(JSON.stringify({ error: msg }) + "\n");
+		else process.stderr.write(`Error: ${msg}\n`);
+		logger$1.error({ err }, "export action failed");
+		return 1;
+	} finally {
+		if (dbWrapper !== void 0) try {
+			dbWrapper.close();
+		} catch {}
+	}
+}
+function registerExportCommand(program, _version = "0.0.0", projectRoot = process.cwd()) {
+	program.command("export").description("Export decision store contents as human-readable markdown files").option("--run-id <id>", "Pipeline run ID to export (defaults to latest run)").option("--output-dir <path>", "Directory to write exported files to", "_bmad-output/planning-artifacts/").option("--project-root <path>", "Project root directory", projectRoot).option("--output-format <format>", "Output format: human (default) or json", "human").action(async (opts) => {
+		if (opts.outputFormat !== "json" && opts.outputFormat !== "human") process.stderr.write(`Warning: unknown --output-format '${opts.outputFormat}', defaulting to 'human'\n`);
+		const outputFormat = opts.outputFormat === "json" ? "json" : "human";
+		const exitCode = await runExportAction({
+			runId: opts.runId,
+			outputDir: opts.outputDir,
+			projectRoot: opts.projectRoot,
+			outputFormat
+		});
+		process.exitCode = exitCode;
+	});
+}
+
 //#endregion
 //#region src/cli/index.ts
 process.setMaxListeners(20);
@@ -5863,6 +6438,7 @@ async function createProgram() {
 	registerMergeCommand(program);
 	registerWorktreesCommand(program, version);
 	registerBrainstormCommand(program, version);
+	registerExportCommand(program, version);
 	registerUpgradeCommand(program);
 	return program;
 }