substrate-ai 0.2.14 → 0.2.16

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, parseDbTimestampAsUtc, registerRunCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion, resolveMainRepoRoot, runAnalysisPhase, runMigrations, runPlanningPhase, runSolutioningPhase, validateStopAfterFromConflict } from "../run-CoP8UQU3.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-BrI2xzk7.js";
 import { ConfigError, ConfigIncompatibleFormatError } from "../errors-BPqtzQ4U.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 { addTokenUsage, createDecision, getDecisionsByCategory, getDecisionsByPhaseForRun, getLatestRun, getPipelineRunById, getTokenUsageSummary, listRequirements, updatePipelineRun } from "../decisions-SyswIRKz.js";
+import { EXPERIMENT_RESULT, OPERATIONAL_FINDING, STORY_METRICS, aggregateTokenUsageForRun, compareRunMetrics, getBaselineRunMetrics, getRunMetrics, getStoryMetricsForRun, incrementRunRestarts, listRunMetrics, tagRunAsBaseline } from "../operational-CobuCGbM.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";
@@ -2675,11 +2675,11 @@ function defaultSupervisorDeps() {
 		sleep: (ms) => new Promise((resolve$2) => setTimeout(resolve$2, ms)),
 		incrementRestarts: (() => {
 			let cachedDbWrapper = null;
-			return (runId, projectRoot) => {
+			return async (runId, projectRoot) => {
 				try {
 					if (cachedDbWrapper === null) {
-						const dbDir = join(projectRoot, ".substrate");
-						const dbPath = join(dbDir, "substrate.db");
+						const dbRoot = await resolveMainRepoRoot(projectRoot);
+						const dbPath = join(dbRoot, ".substrate", "substrate.db");
 						cachedDbWrapper = new DatabaseWrapper(dbPath);
 					}
 					incrementRunRestarts(cachedDbWrapper.getDb(), runId);
@@ -2691,9 +2691,10 @@ function defaultSupervisorDeps() {
 				}
 			};
 		})(),
-		getTokenSnapshot: (runId, projectRoot) => {
+		getTokenSnapshot: async (runId, projectRoot) => {
 			try {
-				const dbPath = join(projectRoot, ".substrate", "substrate.db");
+				const dbRoot = await resolveMainRepoRoot(projectRoot);
+				const dbPath = join(dbRoot, ".substrate", "substrate.db");
 				if (!existsSync(dbPath)) return {
 					input: 0,
 					output: 0,
@@ -2722,6 +2723,73 @@ function defaultSupervisorDeps() {
 			}
 		},
 		getAllDescendants: (rootPids) => getAllDescendantPids(rootPids),
+		writeStallFindings: async (opts) => {
+			try {
+				const dbRoot = await resolveMainRepoRoot(opts.projectRoot);
+				const dbPath = join(dbRoot, ".substrate", "substrate.db");
+				if (!existsSync(dbPath)) return;
+				const dbWrapper = new DatabaseWrapper(dbPath);
+				try {
+					dbWrapper.open();
+					const db = dbWrapper.db;
+					const activeStories = Object.entries(opts.storyDetails).filter(([, s]) => s.phase !== "PENDING" && s.phase !== "COMPLETE" && s.phase !== "ESCALATED");
+					const now = Date.now();
+					for (const [storyKey, storyState] of activeStories) createDecision(db, {
+						pipeline_run_id: opts.runId ?? null,
+						phase: "supervisor",
+						category: OPERATIONAL_FINDING,
+						key: `stall:${storyKey}:${now}`,
+						value: JSON.stringify({
+							phase: storyState.phase,
+							staleness_secs: opts.staleness_secs,
+							attempt: opts.attempt,
+							outcome: opts.outcome
+						}),
+						rationale: `Supervisor stall recovery: story ${storyKey} was in phase ${storyState.phase} when pipeline stalled after ${opts.staleness_secs}s. Attempt ${opts.attempt}. Outcome: ${opts.outcome}.`
+					});
+				} finally {
+					try {
+						dbWrapper.close();
+					} catch {}
+				}
+			} catch {}
+		},
+		writeRunSummary: async (opts) => {
+			const totalStories = opts.succeeded.length + opts.failed.length + opts.escalated.length;
+			if (totalStories === 0) return;
+			if (opts.runId === null) return;
+			try {
+				const dbRoot = await resolveMainRepoRoot(opts.projectRoot);
+				const dbPath = join(dbRoot, ".substrate", "substrate.db");
+				if (!existsSync(dbPath)) return;
+				const dbWrapper = new DatabaseWrapper(dbPath);
+				try {
+					dbWrapper.open();
+					const db = dbWrapper.db;
+					const tokenAgg = aggregateTokenUsageForRun(db, opts.runId);
+					createDecision(db, {
+						pipeline_run_id: opts.runId,
+						phase: "supervisor",
+						category: OPERATIONAL_FINDING,
+						key: `run-summary:${opts.runId}`,
+						value: JSON.stringify({
+							succeeded: opts.succeeded,
+							failed: opts.failed,
+							escalated: opts.escalated,
+							total_restarts: opts.total_restarts,
+							elapsed_seconds: opts.elapsed_seconds,
+							total_input_tokens: tokenAgg.input,
+							total_output_tokens: tokenAgg.output
+						}),
+						rationale: `Run summary: ${opts.succeeded.length} succeeded, ${opts.failed.length} failed, ${opts.escalated.length} escalated. ${opts.total_restarts} restarts. Elapsed: ${opts.elapsed_seconds}s.`
+					});
+				} finally {
+					try {
+						dbWrapper.close();
+					} catch {}
+				}
+			} catch {}
+		},
 		runAnalysis: async (runId, projectRoot) => {
 			const dbPath = join(projectRoot, ".substrate", "substrate.db");
 			if (!existsSync(dbPath)) return;
@@ -2799,7 +2867,7 @@ function buildTerminalSummary(storyDetails) {
 */
 async function handleStallRecovery(health, state, config, deps, io) {
 	const { stallThreshold, maxRestarts, pack, outputFormat } = config;
-	const { killPid, resumePipeline, sleep, incrementRestarts, getAllDescendants } = deps;
+	const { killPid, resumePipeline, sleep, incrementRestarts, getAllDescendants, writeStallFindings } = deps;
 	const { emitEvent, log } = io;
 	const { projectRoot } = state;
 	if (health.staleness_seconds < stallThreshold) return null;
@@ -2846,13 +2914,21 @@ async function handleStallRecovery(health, state, config, deps, io) {
 			attempts: state.restartCount
 		});
 		log(`Supervisor: Max restarts (${maxRestarts}) exceeded. Aborting.`);
+		if (writeStallFindings) await writeStallFindings({
+			runId: health.run_id,
+			storyDetails: health.stories.details,
+			staleness_secs: health.staleness_seconds,
+			attempt: state.restartCount,
+			outcome: "max-restarts-escalated",
+			projectRoot
+		});
 		return {
 			state,
 			maxRestartsExceeded: true
 		};
 	}
 	const newRestartCount = state.restartCount + 1;
-	if (health.run_id !== null) incrementRestarts(health.run_id, projectRoot);
+	if (health.run_id !== null) await incrementRestarts(health.run_id, projectRoot);
 	emitEvent({
 		type: "supervisor:restart",
 		run_id: health.run_id,
@@ -2867,6 +2943,14 @@ async function handleStallRecovery(health, state, config, deps, io) {
 			concurrency: 3,
 			pack
 		});
+		if (writeStallFindings) await writeStallFindings({
+			runId: health.run_id,
+			storyDetails: health.stories.details,
+			staleness_secs: health.staleness_seconds,
+			attempt: newRestartCount,
+			outcome: "recovered",
+			projectRoot
+		});
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		log(`Supervisor: Resume error: ${message}`);
@@ -2875,6 +2959,14 @@ async function handleStallRecovery(health, state, config, deps, io) {
 			reason: "resume_failed",
 			message
 		});
+		if (writeStallFindings) await writeStallFindings({
+			runId: health.run_id,
+			storyDetails: health.stories.details,
+			staleness_secs: health.staleness_seconds,
+			attempt: newRestartCount,
+			outcome: "failed",
+			projectRoot
+		});
 	}
 	return {
 		state: {
@@ -2901,7 +2993,7 @@ async function runSupervisorAction(options, deps = {}) {
 		...defaultSupervisorDeps(),
 		...deps
 	};
-	const { getHealth, sleep, runAnalysis, getTokenSnapshot } = resolvedDeps;
+	const { getHealth, sleep, runAnalysis, getTokenSnapshot, writeRunSummary } = resolvedDeps;
 	let state = {
 		projectRoot,
 		runId,
@@ -2927,7 +3019,7 @@ async function runSupervisorAction(options, deps = {}) {
 		});
 		const ts = new Date().toISOString();
 		if (outputFormat === "json") {
-			const tokenSnapshot = health.run_id !== null ? getTokenSnapshot(health.run_id, projectRoot) : {
+			const tokenSnapshot = health.run_id !== null ? await getTokenSnapshot(health.run_id, projectRoot) : {
 				input: 0,
 				output: 0,
 				cost_usd: 0
@@ -2946,6 +3038,15 @@ async function runSupervisorAction(options, deps = {}) {
 				restarts: state.restartCount
 			});
 			log(`\nPipeline reached terminal state. Elapsed: ${elapsedSeconds}s | succeeded: ${summary.succeeded.length} | failed: ${summary.failed.length} | restarts: ${state.restartCount}`);
+			if (writeRunSummary !== void 0) await writeRunSummary({
+				runId: health.run_id,
+				succeeded: summary.succeeded,
+				failed: summary.failed,
+				escalated: summary.escalated,
+				total_restarts: state.restartCount,
+				elapsed_seconds: elapsedSeconds,
+				projectRoot
+			});
 			if (health.run_id !== null && runAnalysis !== void 0) {
 				log(`[supervisor] Running post-run analysis for ${health.run_id}...`);
 				try {
@@ -2994,11 +3095,11 @@ async function runSupervisorAction(options, deps = {}) {
 						try {
 							const { createExperimenter } = await import(
 								/* @vite-ignore */
-								"../experimenter-BSu2ie3J.js"
+								"../experimenter-Cd04gAWQ.js"
 );
 							const { getLatestRun: getLatest } = await import(
 								/* @vite-ignore */
-								"../decisions-DKXc-jnv.js"
+								"../decisions-BmqXQ3Se.js"
 );
 							const dbPath = join(projectRoot, ".substrate", "substrate.db");
 							const expDbWrapper = new DatabaseWrapper(dbPath);
@@ -3008,7 +3109,7 @@ async function runSupervisorAction(options, deps = {}) {
 								const expDb = expDbWrapper.db;
 								const { runRunAction: runPipeline } = await import(
 									/* @vite-ignore */
-									"../run-B9IglY4m.js"
+									"../run-fjuwOUib.js"
 );
 								const runStoryFn = async (opts) => {
 									const exitCode = await runPipeline({
@@ -3078,7 +3179,14 @@ async function runSupervisorAction(options, deps = {}) {
 			maxRestarts,
 			pack,
 			outputFormat
-		}, resolvedDeps, {
+		}, {
+			killPid: resolvedDeps.killPid,
+			resumePipeline: resolvedDeps.resumePipeline,
+			sleep: resolvedDeps.sleep,
+			incrementRestarts: resolvedDeps.incrementRestarts,
+			getAllDescendants: resolvedDeps.getAllDescendants,
+			writeStallFindings: resolvedDeps.writeStallFindings
+		}, {
 			emitEvent,
 			log
 		});
@@ -3147,7 +3255,7 @@ async function runMultiProjectSupervisor(options, deps = {}) {
 			}
 			const state = states.get(projectRoot);
 			if (outputFormat === "json") {
-				const tokenSnapshot = health.run_id !== null ? getTokenSnapshot(health.run_id, projectRoot) : {
+				const tokenSnapshot = health.run_id !== null ? await getTokenSnapshot(health.run_id, projectRoot) : {
 					input: 0,
 					output: 0,
 					cost_usd: 0
@@ -3326,23 +3434,69 @@ async function runMetricsAction(options) {
 			return 0;
 		}
 		const runs = listRunMetrics(db, limit);
-		if (outputFormat === "json") process.stdout.write(formatOutput({ runs }, "json", true) + "\n");
+		const storyMetricDecisions = getDecisionsByCategory(db, STORY_METRICS);
+		const storyMetrics = storyMetricDecisions.map((d) => {
+			const colonIdx = d.key.indexOf(":");
+			const storyKey = colonIdx !== -1 ? d.key.slice(0, colonIdx) : d.key;
+			const runId = colonIdx !== -1 ? d.key.slice(colonIdx + 1) : d.pipeline_run_id ?? "";
+			try {
+				const v = JSON.parse(d.value);
+				return {
+					story_key: storyKey,
+					run_id: runId,
+					wall_clock_seconds: v.wall_clock_seconds ?? 0,
+					input_tokens: v.input_tokens ?? 0,
+					output_tokens: v.output_tokens ?? 0,
+					review_cycles: v.review_cycles ?? 0,
+					stalled: v.stalled ?? false,
+					...v.cost_usd !== void 0 && v.cost_usd > 0 ? { cost_usd: v.cost_usd } : {}
+				};
+			} catch {
+				return {
+					story_key: storyKey,
+					run_id: runId,
+					wall_clock_seconds: 0,
+					input_tokens: 0,
+					output_tokens: 0,
+					review_cycles: 0,
+					stalled: false
+				};
+			}
+		});
+		if (outputFormat === "json") process.stdout.write(formatOutput({
+			runs,
+			story_metrics: storyMetrics
+		}, "json", true) + "\n");
 		else {
-			if (runs.length === 0) {
+			if (runs.length === 0 && storyMetrics.length === 0) {
 				process.stdout.write("No run metrics recorded yet. Run `substrate run` to generate metrics.\n");
 				return 0;
 			}
-			process.stdout.write(`\nPipeline Run Metrics (last ${runs.length} runs)\n`);
-			process.stdout.write("─".repeat(80) + "\n");
-			for (const run of runs) {
-				const isBaseline = run.is_baseline ? " [BASELINE]" : "";
-				process.stdout.write(`\nRun: ${run.run_id}${isBaseline}\n`);
-				process.stdout.write(`  Status:    ${run.status}  |  Methodology: ${run.methodology}\n`);
-				process.stdout.write(`  Started:   ${run.started_at}\n`);
-				if (run.completed_at) process.stdout.write(`  Completed: ${run.completed_at}  (${run.wall_clock_seconds}s)\n`);
-				process.stdout.write(`  Stories:   attempted=${run.stories_attempted} succeeded=${run.stories_succeeded} failed=${run.stories_failed} escalated=${run.stories_escalated}\n`);
-				process.stdout.write(`  Tokens:    ${(run.total_input_tokens ?? 0).toLocaleString()} in / ${(run.total_output_tokens ?? 0).toLocaleString()} out  $${(run.total_cost_usd ?? 0).toFixed(4)}\n`);
-				process.stdout.write(`  Cycles:    ${run.total_review_cycles}  |  Dispatches: ${run.total_dispatches}  |  Concurrency: ${run.concurrency_setting}\n`);
+			if (runs.length > 0) {
+				process.stdout.write(`\nPipeline Run Metrics (last ${runs.length} runs)\n`);
+				process.stdout.write("─".repeat(80) + "\n");
+				for (const run of runs) {
+					const isBaseline = run.is_baseline ? " [BASELINE]" : "";
+					process.stdout.write(`\nRun: ${run.run_id}${isBaseline}\n`);
+					process.stdout.write(`  Status:    ${run.status}  |  Methodology: ${run.methodology}\n`);
+					process.stdout.write(`  Started:   ${run.started_at}\n`);
+					if (run.completed_at) process.stdout.write(`  Completed: ${run.completed_at}  (${run.wall_clock_seconds}s)\n`);
+					process.stdout.write(`  Stories:   attempted=${run.stories_attempted} succeeded=${run.stories_succeeded} failed=${run.stories_failed} escalated=${run.stories_escalated}\n`);
+					process.stdout.write(`  Tokens:    ${(run.total_input_tokens ?? 0).toLocaleString()} in / ${(run.total_output_tokens ?? 0).toLocaleString()} out  $${(run.total_cost_usd ?? 0).toFixed(4)}\n`);
+					process.stdout.write(`  Cycles:    ${run.total_review_cycles}  |  Dispatches: ${run.total_dispatches}  |  Concurrency: ${run.concurrency_setting}\n`);
+				}
+			}
+			if (storyMetrics.length > 0) {
+				process.stdout.write(`\nPer-Story Efficiency Metrics (${storyMetrics.length} stories)\n`);
+				process.stdout.write("─".repeat(80) + "\n");
+				process.stdout.write(`  ${"Story".padEnd(16)} ${"Run".padEnd(12)} ${"Wall(s)".padStart(8)} ${"Tokens In".padStart(10)} ${"Tokens Out".padStart(11)} ${"Cycles".padStart(7)} ${"Stalled".padStart(8)}\n`);
+				process.stdout.write("  " + "─".repeat(76) + "\n");
+				for (const sm of storyMetrics) {
+					const runShort = sm.run_id.slice(0, 8);
+					const stalledStr = sm.stalled ? "yes" : "no";
+					const costStr = sm.cost_usd !== void 0 && sm.cost_usd > 0 ? `  $${sm.cost_usd.toFixed(4)}` : "";
+					process.stdout.write(`  ${sm.story_key.padEnd(16)} ${runShort.padEnd(12)} ${String(sm.wall_clock_seconds).padStart(8)} ${sm.input_tokens.toLocaleString().padStart(10)} ${sm.output_tokens.toLocaleString().padStart(11)} ${String(sm.review_cycles).padStart(7)} ${stalledStr.padStart(8)}${costStr}\n`);
+				}
 			}
 		}
 		return 0;
@@ -6441,6 +6595,100 @@ function renderEpics(decisions) {
 	return parts.join("\n");
 }
 /**
+* Render `operational-finding` category decisions as an "Operational Findings" section.
+*
+* Groups findings by run key (for run-summary decisions) and stall key (for stall decisions).
+* Returns '' if no matching decisions are found.
+*
+* @param decisions - Decisions of any category; filters for 'operational-finding'
+* @returns Formatted markdown content, or '' if empty
+*/
+function renderOperationalFindings(decisions) {
+	const findings = decisions.filter((d) => d.category === "operational-finding");
+	if (findings.length === 0) return "";
+	const parts = ["## Operational Findings", ""];
+	const runSummaries = findings.filter((d) => d.key.startsWith("run-summary:"));
+	const stallFindings = findings.filter((d) => d.key.startsWith("stall:"));
+	const otherFindings = findings.filter((d) => !d.key.startsWith("run-summary:") && !d.key.startsWith("stall:"));
+	if (runSummaries.length > 0) {
+		parts.push("### Run Summaries");
+		parts.push("");
+		for (const d of runSummaries) {
+			const runId = d.key.replace("run-summary:", "");
+			const parsed = safeParseJson(d.value);
+			if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+				const s = parsed;
+				parts.push(`**Run: ${runId}**`);
+				parts.push(`- Succeeded: ${(s.succeeded ?? []).join(", ") || "none"}`);
+				parts.push(`- Failed: ${(s.failed ?? []).join(", ") || "none"}`);
+				parts.push(`- Escalated: ${(s.escalated ?? []).join(", ") || "none"}`);
+				parts.push(`- Total restarts: ${s.total_restarts ?? 0}`);
+				parts.push(`- Elapsed: ${s.elapsed_seconds ?? 0}s`);
+				parts.push(`- Tokens: ${s.total_input_tokens ?? 0} in / ${s.total_output_tokens ?? 0} out`);
+			} else parts.push(`**Run: ${runId}**: ${String(parsed)}`);
+			parts.push("");
+		}
+	}
+	if (stallFindings.length > 0) {
+		parts.push("### Stall Events");
+		parts.push("");
+		for (const d of stallFindings) {
+			const parsed = safeParseJson(d.value);
+			if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+				const s = parsed;
+				const outcome = s.outcome ?? "unknown";
+				parts.push(`- **${d.key}**: phase=${s.phase ?? "?"} staleness=${s.staleness_secs ?? 0}s attempt=${s.attempt ?? 0} outcome=${outcome}`);
+			} else parts.push(`- **${d.key}**: ${String(parsed)}`);
+		}
+		parts.push("");
+	}
+	if (otherFindings.length > 0) {
+		for (const d of otherFindings) parts.push(`- **${d.key}**: ${renderValue(d.value)}`);
+		parts.push("");
+	}
+	return parts.join("\n");
+}
+/**
+* Render `experiment-result` category decisions as an "Experiments" section.
+*
+* Lists each experiment with its verdict, metric delta, and branch name.
+* Returns '' if no matching decisions are found.
+*
+* @param decisions - Decisions of any category; filters for 'experiment-result'
+* @returns Formatted markdown content, or '' if empty
+*/
+function renderExperiments(decisions) {
+	const experiments = decisions.filter((d) => d.category === "experiment-result");
+	if (experiments.length === 0) return "";
+	const parts = ["## Experiments", ""];
+	const improved = experiments.filter((d) => {
+		const p = safeParseJson(d.value);
+		return typeof p === "object" && p !== null && p["verdict"] === "IMPROVED";
+	});
+	const mixed = experiments.filter((d) => {
+		const p = safeParseJson(d.value);
+		return typeof p === "object" && p !== null && p["verdict"] === "MIXED";
+	});
+	const regressed = experiments.filter((d) => {
+		const p = safeParseJson(d.value);
+		return typeof p === "object" && p !== null && p["verdict"] === "REGRESSED";
+	});
+	parts.push(`**Total**: ${experiments.length} | **Improved**: ${improved.length} | **Mixed**: ${mixed.length} | **Regressed**: ${regressed.length}`);
+	parts.push("");
+	for (const d of experiments) {
+		const parsed = safeParseJson(d.value);
+		if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+			const e = parsed;
+			const verdict = e.verdict ?? "UNKNOWN";
+			const metric = e.target_metric ?? "unknown";
+			const branch = e.branch_name ? ` → \`${e.branch_name}\`` : "";
+			parts.push(`- **[${verdict}]** ${metric}: before=${e.before ?? "?"} after=${e.after ?? "?"}${branch}`);
+		} else parts.push(`- ${String(parsed)}`);
+	}
+	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
@@ -6599,6 +6847,28 @@ async function runExportAction(options) {
 				if (outputFormat === "human") process.stdout.write(`  Written: ${filePath}\n`);
 			}
 		}
+		const operationalDecisions = getDecisionsByCategory(db, OPERATIONAL_FINDING);
+		if (operationalDecisions.length > 0) {
+			const operationalContent = renderOperationalFindings(operationalDecisions);
+			if (operationalContent !== "") {
+				const filePath = join$1(resolvedOutputDir, "operational-findings.md");
+				writeFileSync$1(filePath, operationalContent, "utf-8");
+				filesWritten.push(filePath);
+				if (!phasesExported.includes("operational")) phasesExported.push("operational");
+				if (outputFormat === "human") process.stdout.write(`  Written: ${filePath}\n`);
+			}
+		}
+		const experimentDecisions = getDecisionsByCategory(db, EXPERIMENT_RESULT);
+		if (experimentDecisions.length > 0) {
+			const experimentsContent = renderExperiments(experimentDecisions);
+			if (experimentsContent !== "") {
+				const filePath = join$1(resolvedOutputDir, "experiments.md");
+				writeFileSync$1(filePath, experimentsContent, "utf-8");
+				filesWritten.push(filePath);
+				if (!phasesExported.includes("operational")) phasesExported.push("operational");
+				if (outputFormat === "human") process.stdout.write(`  Written: ${filePath}\n`);
+			}
+		}
 		if (outputFormat === "json") {
 			const result = {
 				files_written: filesWritten,

package/dist/decisions-BmqXQ3Se.js

@@ -0,0 +1,3 @@
+import { addTokenUsage, createDecision, createPipelineRun, createRequirement, getArtifactByTypeForRun, getArtifactsByRun, getDecisionsByCategory, getDecisionsByPhase, getDecisionsByPhaseForRun, getLatestRun, getPipelineRunById, getTokenUsageSummary, listRequirements, registerArtifact, updateDecision, updatePipelineRun, updatePipelineRunConfig, upsertDecision } from "./decisions-SyswIRKz.js";
+
+export { getLatestRun };

package/dist/{decisions-DNYByk0U.js → decisions-SyswIRKz.js}

@@ -179,6 +179,13 @@ function getDecisionsByPhaseForRun(db, runId, phase) {
 	return stmt.all(runId, phase);
 }
 /**
+* Get all decisions for a given category, ordered by created_at ascending.
+*/
+function getDecisionsByCategory(db, category) {
+	const stmt = db.prepare("SELECT * FROM decisions WHERE category = ? ORDER BY created_at ASC");
+	return stmt.all(category);
+}
+/**
 * Update a decision's value and/or rationale and set updated_at.
 */
 function updateDecision(db, id, updates) {
@@ -354,5 +361,5 @@ function getTokenUsageSummary(db, runId) {
 }
 
 //#endregion
-export { addTokenUsage, createDecision, createPipelineRun, createRequirement, getArtifactByTypeForRun, getArtifactsByRun, getDecisionsByPhase, getDecisionsByPhaseForRun, getLatestRun, getPipelineRunById, getTokenUsageSummary, listRequirements, registerArtifact, updateDecision, updatePipelineRun, updatePipelineRunConfig, upsertDecision };
-//# sourceMappingURL=decisions-DNYByk0U.js.map
+export { addTokenUsage, createDecision, createPipelineRun, createRequirement, getArtifactByTypeForRun, getArtifactsByRun, getDecisionsByCategory, getDecisionsByPhase, getDecisionsByPhaseForRun, getLatestRun, getPipelineRunById, getTokenUsageSummary, listRequirements, registerArtifact, updateDecision, updatePipelineRun, updatePipelineRunConfig, upsertDecision };
+//# sourceMappingURL=decisions-SyswIRKz.js.map

package/dist/{experimenter-BSu2ie3J.js → experimenter-Cd04gAWQ.js}

@@ -1,5 +1,6 @@
 import "./logger-C6n1g8uP.js";
-import { getRunMetrics, getStoryMetricsForRun } from "./metrics-BSg8VIHd.js";
+import { createDecision } from "./decisions-SyswIRKz.js";
+import { EXPERIMENT_RESULT, getRunMetrics, getStoryMetricsForRun } from "./operational-CobuCGbM.js";
 import { spawnGit } from "./git-utils-BtI5eNoN.js";
 import { spawn } from "node:child_process";
 import { join } from "node:path";
@@ -459,6 +460,24 @@ function createExperimenter(config, deps) {
 			prLink
 		};
 		await appendExperimentLog(finalResult);
+		try {
+			const targetMetricValue = rec.type === "token_regression" ? rec.tokens_actual ?? 0 : rec.type === "review_cycles" ? rec.review_cycles ?? 0 : rec.timing_seconds ?? 0;
+			const afterValue = rec.type === "token_regression" ? deltas.tokens_pct !== null ? Math.round(targetMetricValue * (1 + deltas.tokens_pct / 100)) : targetMetricValue : rec.type === "review_cycles" ? deltas.review_cycles_pct !== null ? Math.round(targetMetricValue * (1 + deltas.review_cycles_pct / 100)) : targetMetricValue : deltas.wall_clock_pct !== null ? Math.round(targetMetricValue * (1 + deltas.wall_clock_pct / 100)) : targetMetricValue;
+			createDecision(db, {
+				pipeline_run_id: baselineRunId,
+				phase: "supervisor",
+				category: EXPERIMENT_RESULT,
+				key: `experiment:${baselineRunId}:${Date.now()}`,
+				value: JSON.stringify({
+					target_metric: rec.type,
+					before: targetMetricValue,
+					after: afterValue,
+					verdict,
+					branch_name: verdict === "IMPROVED" || verdict === "MIXED" ? branchName : null
+				}),
+				rationale: `Experiment for ${rec.story_key}/${rec.phase}: ${rec.description}. Verdict: ${verdict}.`
+			});
+		} catch {}
 		return finalResult;
 	}
 	return { async runExperiments(db, recommendations, baselineRunId) {
@@ -481,4 +500,4 @@ function createExperimenter(config, deps) {
 
 //#endregion
 export { createExperimenter };
-//# sourceMappingURL=experimenter-BSu2ie3J.js.map
+//# sourceMappingURL=experimenter-Cd04gAWQ.js.map

package/dist/{metrics-BSg8VIHd.js → operational-CobuCGbM.js}

@@ -180,5 +180,82 @@ function aggregateTokenUsageForStory(db, runId, storyKey) {
 }
 
 //#endregion
-export { aggregateTokenUsageForRun, aggregateTokenUsageForStory, compareRunMetrics, getBaselineRunMetrics, getRunMetrics, getStoryMetricsForRun, incrementRunRestarts, listRunMetrics, tagRunAsBaseline, writeRunMetrics, writeStoryMetrics };
-//# sourceMappingURL=metrics-BSg8VIHd.js.map
+//#region src/persistence/schemas/operational.ts
+/**
+* Category and key-schema constants for operational findings in the decision store.
+*
+* These constants avoid string literals scattered across supervisor, orchestrator,
+* and experimenter code. Import them wherever you need to insert or query
+* operational decisions.
+*/
+/**
+* Category for supervisor stall events and run-level summaries.
+*
+* Key schemas:
+*   - Stall finding:  "stall:{storyKey}:{timestamp}"
+*   - Run summary:    "run-summary:{runId}"
+*
+* Value shapes:
+*
+* Stall finding:
+* ```json
+* {
+*   "phase": "string",                     // story phase at stall time, e.g. "code-review"
+*   "staleness_secs": 700,
+*   "attempt": 1,                          // restart attempt number (1-based)
+*   "outcome": "recovered"                 // "recovered" | "failed" | "max-restarts-escalated"
+* }
+* ```
+*
+* Run summary:
+* ```json
+* {
+*   "succeeded": ["1-1", "1-2"],
+*   "failed": ["1-3"],
+*   "escalated": [],
+*   "total_restarts": 0,
+*   "elapsed_seconds": 1234,
+*   "total_input_tokens": 50000,
+*   "total_output_tokens": 10000
+* }
+* ```
+*/
+const OPERATIONAL_FINDING = "operational-finding";
+/**
+* Category for supervisor experiment results.
+*
+* Key schema: "experiment:{runId}:{timestamp}"
+*
+* Value shape:
+* ```json
+* {
+*   "target_metric": "token_regression",
+*   "before": 12000,
+*   "after": 9500,
+*   "verdict": "IMPROVED",                // "IMPROVED" | "MIXED" | "REGRESSED"
+*   "branch_name": "supervisor/experiment/abc12345-dev-story-token-regression"
+* }
+* ```
+*/
+const EXPERIMENT_RESULT = "experiment-result";
+/**
+* Category for per-story wall-clock and efficiency metrics.
+*
+* Key schema: "{storyKey}:{runId}"
+*
+* Value shape:
+* ```json
+* {
+*   "wall_clock_seconds": 180,
+*   "input_tokens": 8000,
+*   "output_tokens": 2000,
+*   "review_cycles": 2,
+*   "stalled": false
+* }
+* ```
+*/
+const STORY_METRICS = "story-metrics";
+
+//#endregion
+export { EXPERIMENT_RESULT, OPERATIONAL_FINDING, STORY_METRICS, aggregateTokenUsageForRun, aggregateTokenUsageForStory, compareRunMetrics, getBaselineRunMetrics, getRunMetrics, getStoryMetricsForRun, incrementRunRestarts, listRunMetrics, tagRunAsBaseline, writeRunMetrics, writeStoryMetrics };
+//# sourceMappingURL=operational-CobuCGbM.js.map

package/dist/{run-CoP8UQU3.js → run-BrI2xzk7.js}

@@ -1,7 +1,7 @@
 import { createLogger } from "./logger-C6n1g8uP.js";
 import { AdapterRegistry, createEventBus, createTuiApp, isTuiCapable, printNonTtyWarning } from "./event-bus-J-bw-pkp.js";
-import { addTokenUsage, createDecision, createPipelineRun, createRequirement, getArtifactByTypeForRun, getArtifactsByRun, getDecisionsByPhase, getDecisionsByPhaseForRun, getPipelineRunById, getTokenUsageSummary, registerArtifact, updatePipelineRun, updatePipelineRunConfig, upsertDecision } from "./decisions-DNYByk0U.js";
-import { aggregateTokenUsageForRun, aggregateTokenUsageForStory, getStoryMetricsForRun, writeRunMetrics, writeStoryMetrics } from "./metrics-BSg8VIHd.js";
+import { addTokenUsage, createDecision, createPipelineRun, createRequirement, getArtifactByTypeForRun, getArtifactsByRun, getDecisionsByPhase, getDecisionsByPhaseForRun, getPipelineRunById, getTokenUsageSummary, registerArtifact, updatePipelineRun, updatePipelineRunConfig, upsertDecision } from "./decisions-SyswIRKz.js";
+import { STORY_METRICS, aggregateTokenUsageForRun, aggregateTokenUsageForStory, getStoryMetricsForRun, writeRunMetrics, writeStoryMetrics } from "./operational-CobuCGbM.js";
 import { dirname, join } from "path";
 import { access, readFile, readdir, stat } from "fs/promises";
 import { existsSync, mkdirSync, readFileSync } from "fs";
@@ -5371,6 +5371,7 @@ function createImplementationOrchestrator(deps) {
 	const HEARTBEAT_INTERVAL_MS = 3e4;
 	const WATCHDOG_TIMEOUT_MS = 6e5;
 	const _stalledStories = new Set();
+	const _storiesWithStall = new Set();
 	const _phaseStartMs = new Map();
 	const _phaseEndMs = new Map();
 	const _storyDispatches = new Map();
@@ -5424,6 +5425,28 @@ function createImplementationOrchestrator(deps) {
 				review_cycles: reviewCycles,
 				dispatches: _storyDispatches.get(storyKey) ?? 0
 			});
+			try {
+				const runId = config.pipelineRunId ?? "unknown";
+				createDecision(db, {
+					pipeline_run_id: config.pipelineRunId,
+					phase: "implementation",
+					category: STORY_METRICS,
+					key: `${storyKey}:${runId}`,
+					value: JSON.stringify({
+						wall_clock_seconds: wallClockSeconds,
+						input_tokens: tokenAgg.input,
+						output_tokens: tokenAgg.output,
+						review_cycles: reviewCycles,
+						stalled: _storiesWithStall.has(storyKey)
+					}),
+					rationale: `Story ${storyKey} completed with result=${result} in ${wallClockSeconds}s. Tokens: ${tokenAgg.input}+${tokenAgg.output}. Review cycles: ${reviewCycles}.`
+				});
+			} catch (decisionErr) {
+				logger$16.warn({
+					err: decisionErr,
+					storyKey
+				}, "Failed to write story-metrics decision (best-effort)");
+			}
 		} catch (err) {
 			logger$16.warn({
 				err,
@@ -5490,6 +5513,7 @@ function createImplementationOrchestrator(deps) {
 				for (const [key, s] of _stories) if (s.phase !== "PENDING" && s.phase !== "COMPLETE" && s.phase !== "ESCALATED") {
 					if (_stalledStories.has(key)) continue;
 					_stalledStories.add(key);
+					_storiesWithStall.add(key);
 					logger$16.warn({
 						storyKey: key,
 						phase: s.phase,
@@ -11172,4 +11196,4 @@ function registerRunCommand(program, _version = "0.0.0", projectRoot = process.c
 
 //#endregion
 export { 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, runRunAction, runSolutioningPhase, validateStopAfterFromConflict };
-//# sourceMappingURL=run-CoP8UQU3.js.map
+//# sourceMappingURL=run-BrI2xzk7.js.map

package/dist/run-fjuwOUib.js

@@ -0,0 +1,7 @@
+import "./logger-C6n1g8uP.js";
+import "./event-bus-J-bw-pkp.js";
+import { registerRunCommand, runRunAction } from "./run-BrI2xzk7.js";
+import "./decisions-SyswIRKz.js";
+import "./operational-CobuCGbM.js";
+
+export { runRunAction };

package/package.json

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

package/dist/decisions-DKXc-jnv.js

@@ -1,3 +0,0 @@
-import { addTokenUsage, createDecision, createPipelineRun, createRequirement, getArtifactByTypeForRun, getArtifactsByRun, getDecisionsByPhase, getDecisionsByPhaseForRun, getLatestRun, getPipelineRunById, getTokenUsageSummary, listRequirements, registerArtifact, updateDecision, updatePipelineRun, updatePipelineRunConfig, upsertDecision } from "./decisions-DNYByk0U.js";
-
-export { getLatestRun };

package/dist/run-B9IglY4m.js

@@ -1,7 +0,0 @@
-import "./logger-C6n1g8uP.js";
-import "./event-bus-J-bw-pkp.js";
-import { registerRunCommand, runRunAction } from "./run-CoP8UQU3.js";
-import "./decisions-DNYByk0U.js";
-import "./metrics-BSg8VIHd.js";
-
-export { runRunAction };