substrate-ai 0.2.39 → 0.3.0

package/dist/cli/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { DEFAULT_CONFIG, DEFAULT_ROUTING_POLICY, DatabaseWrapper, SUBSTRATE_OWNED_SETTINGS_KEYS, VALID_PHASES, buildPipelineStatusOutput, createConfigSystem, createContextCompiler, createDispatcher, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, findPackageRoot, formatOutput, formatPhaseCompletionSummary, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getAllDescendantPids, getAutoHealthData, getSubstrateDefaultSettings, parseDbTimestampAsUtc, registerHealthCommand, registerRunCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion, resolveMainRepoRoot, resolveStoryKeys, runAnalysisPhase, runMigrations, runPlanningPhase, runSolutioningPhase, validateStopAfterFromConflict } from "../run-RJ0EHbfM.js";
+import { DEFAULT_CONFIG, DEFAULT_ROUTING_POLICY, DatabaseWrapper, DoltNotInstalled, FileStateStore, SUBSTRATE_OWNED_SETTINGS_KEYS, VALID_PHASES, buildPipelineStatusOutput, checkDoltInstalled, createConfigSystem, createContextCompiler, createDispatcher, createDoltClient, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStateStore, createStopAfterGate, findPackageRoot, formatOutput, formatPhaseCompletionSummary, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getAllDescendantPids, getAutoHealthData, getSubstrateDefaultSettings, initializeDolt, parseDbTimestampAsUtc, registerHealthCommand, registerRunCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion, resolveMainRepoRoot, resolveStoryKeys, runAnalysisPhase, runMigrations, runPlanningPhase, runSolutioningPhase, validateStopAfterFromConflict } from "../run-DO9n3cwy.js";
 import { createLogger } from "../logger-D2fS2ccL.js";
 import { AdapterRegistry } from "../adapter-registry-PsWhP_1Q.js";
 import { CURRENT_CONFIG_FORMAT_VERSION, CURRENT_TASK_GRAPH_VERSION, PartialSubstrateConfigSchema } from "../config-migrator-DSi8KhQC.js";
@@ -18,11 +18,11 @@ import yaml from "js-yaml";
 import { createRequire } from "node:module";
 import * as path$1 from "node:path";
 import { isAbsolute, join as join$1 } from "node:path";
-import BetterSqlite3 from "better-sqlite3";
+import Database from "better-sqlite3";
+import { access as access$1 } from "node:fs/promises";
 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";
 import { randomUUID } from "crypto";
 import { createInterface as createInterface$1 } from "readline";
 
@@ -662,13 +662,37 @@ async function runInitAction(options) {
 		await scaffoldStatuslineScript(projectRoot);
 		await scaffoldClaudeSettings(projectRoot);
 		await scaffoldClaudeCommands(projectRoot, outputFormat);
+		const doltMode = options.doltMode ?? "auto";
+		let doltInitialized = false;
+		if (doltMode !== "skip") try {
+			if (doltMode === "auto") await checkDoltInstalled();
+			await initializeDolt({ projectRoot });
+			doltInitialized = true;
+		} catch (err) {
+			if (err instanceof DoltNotInstalled) {
+				if (doltMode === "force") {
+					process.stderr.write(`${err.message}\n`);
+					return INIT_EXIT_ERROR;
+				}
+				logger$16.debug("Dolt not installed, skipping auto-init");
+			} else {
+				const msg = err instanceof Error ? err.message : String(err);
+				if (doltMode === "force") {
+					process.stderr.write(`✗ Dolt initialization failed: ${msg}\n`);
+					return INIT_EXIT_ERROR;
+				}
+				logger$16.warn("Dolt auto-init failed (non-blocking)", { error: msg });
+			}
+		}
+		else logger$16.debug("Dolt step was skipped (--no-dolt)");
 		const successMsg = `Pack '${packName}' and database initialized successfully at ${dbPath}`;
 		if (outputFormat === "json") process.stdout.write(formatOutput({
 			pack: packName,
 			dbPath,
 			scaffolded,
 			configPath,
-			routingPolicyPath
+			routingPolicyPath,
+			doltInitialized
 		}, "json", true) + "\n");
 		else {
 			process.stdout.write(`\n  Substrate initialized successfully!\n\n`);
@@ -683,6 +707,7 @@ async function runInitAction(options) {
 			process.stdout.write(`    CLAUDE.md             pipeline instructions for Claude Code\n`);
 			process.stdout.write(`    .claude/commands/     /substrate-run, /substrate-supervisor, /substrate-metrics\n`);
 			process.stdout.write(`    .substrate/           config, database, routing policy\n`);
+			if (doltInitialized) process.stdout.write(`✓ Dolt state store initialized at .substrate/state/\n`);
 			process.stdout.write("\n  Next steps:\n    1. Start a Claude Code session in this project\n    2. Tell Claude: \"Run the substrate pipeline\"\n    3. Or use the /substrate-run slash command for a guided run\n");
 		}
 		return INIT_EXIT_SUCCESS;
@@ -695,14 +720,16 @@ async function runInitAction(options) {
 	}
 }
 function registerInitCommand(program, _version, registry) {
-	program.command("init").description("Initialize Substrate — creates config, scaffolds methodology pack, and sets up database").option("--pack <name>", "Methodology pack name", "bmad").option("--project-root <path>", "Project root directory", process.cwd()).option("-y, --yes", "Skip all interactive prompts and use defaults", false).option("--force", "Overwrite existing files and packs", false).option("--output-format <format>", "Output format: human (default) or json", "human").action(async (opts) => {
+	program.command("init").description("Initialize Substrate — creates config, scaffolds methodology pack, and sets up database").option("--pack <name>", "Methodology pack name", "bmad").option("--project-root <path>", "Project root directory", process.cwd()).option("-y, --yes", "Skip all interactive prompts and use defaults", false).option("--force", "Overwrite existing files and packs", false).option("--output-format <format>", "Output format: human (default) or json", "human").option("--dolt", "Initialize Dolt state database as part of init (forces Dolt bootstrapping)", false).option("--no-dolt", "Skip Dolt state store initialization even if Dolt is installed").action(async (opts) => {
 		const outputFormat = opts.outputFormat === "json" ? "json" : "human";
+		const doltMode = opts.noDolt ? "skip" : opts.dolt ? "force" : "auto";
 		const exitCode = await runInitAction({
 			pack: opts.pack,
 			projectRoot: opts.projectRoot,
 			outputFormat,
 			force: opts.force,
 			yes: opts.yes,
+			doltMode,
 			...registry !== void 0 && { registry }
 		});
 		process.exitCode = exitCode;
@@ -1281,7 +1308,32 @@ function registerResumeCommand(program, _version = "0.0.0", projectRoot = proces
 //#region src/cli/commands/status.ts
 const logger$13 = createLogger("status-cmd");
 async function runStatusAction(options) {
-	const { outputFormat, runId, projectRoot } = options;
+	const { outputFormat, runId, projectRoot, stateStore, history } = options;
+	if (history === true) {
+		if (!stateStore) {
+			process.stdout.write("History not available with file backend. Use Dolt backend for state history.\n");
+			return 0;
+		}
+		try {
+			const entries = await stateStore.getHistory(20);
+			if (outputFormat === "json") {
+				process.stdout.write(JSON.stringify(entries, null, 2) + "\n");
+				return 0;
+			}
+			process.stdout.write("TIMESTAMP            HASH     MESSAGE\n");
+			for (const entry of entries) {
+				const ts = (entry.timestamp ?? "").padEnd(20);
+				const hash = (entry.hash ?? "").padEnd(8);
+				process.stdout.write(`${ts} ${hash} ${entry.message}\n`);
+			}
+			return 0;
+		} catch (err) {
+			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`);
+			return 1;
+		}
+	}
 	const dbRoot = await resolveMainRepoRoot(projectRoot);
 	const dbPath = join(dbRoot, ".substrate", "substrate.db");
 	if (!existsSync(dbPath)) {
@@ -1306,6 +1358,12 @@ async function runStatusAction(options) {
 		const tokenSummary = getTokenUsageSummary(db, run.id);
 		const decisionsCount = db.prepare(`SELECT COUNT(*) as cnt FROM decisions WHERE pipeline_run_id = ?`).get(run.id)?.cnt ?? 0;
 		const storiesCount = db.prepare(`SELECT COUNT(*) as cnt FROM requirements WHERE pipeline_run_id = ? AND source = 'solutioning-phase'`).get(run.id)?.cnt ?? 0;
+		let storeStories = [];
+		if (stateStore) try {
+			storeStories = await stateStore.queryStories({});
+		} catch (err) {
+			logger$13.debug("StateStore query failed, continuing without store data", { err });
+		}
 		if (outputFormat === "json") {
 			const statusOutput = buildPipelineStatusOutput(run, tokenSummary, decisionsCount, storiesCount);
 			const storyMetricsRows = getStoryMetricsForRun(db, run.id);
@@ -1352,7 +1410,8 @@ async function runStatusAction(options) {
 					total_output_tokens: totalOutputTokens,
 					stories_per_hour: storiesPerHour,
 					cost_usd: totalCostUsd
-				}
+				},
+				story_states: storeStories
 			};
 			process.stdout.write(formatOutput(enhancedOutput, "json", true) + "\n");
 		} else {
@@ -1394,6 +1453,10 @@ async function runStatusAction(options) {
 					}
 				}
 			}
+			if (storeStories.length > 0) {
+				process.stdout.write("\nStateStore Story States:\n");
+				for (const s of storeStories) process.stdout.write(`  ${s.storyKey}: ${s.phase} (${s.reviewCycles} review cycles)\n`);
+			}
 			process.stdout.write("\n");
 			process.stdout.write(formatTokenTelemetry(tokenSummary) + "\n");
 		}
@@ -1411,14 +1474,34 @@ async function runStatusAction(options) {
 	}
 }
 function registerStatusCommand(program, _version = "0.0.0", projectRoot = process.cwd()) {
-	program.command("status").description("Show status of the most recent (or specified) pipeline run").option("--run-id <id>", "Pipeline run ID to query (defaults to latest)").option("--project-root <path>", "Project root directory", projectRoot).option("--output-format <format>", "Output format: human (default) or json", "human").action(async (opts) => {
+	program.command("status").description("Show status of the most recent (or specified) pipeline run").option("--run-id <id>", "Pipeline run ID to query (defaults to latest)").option("--project-root <path>", "Project root directory", projectRoot).option("--output-format <format>", "Output format: human (default) or json", "human").option("--history", "Show Dolt commit history for the state store").action(async (opts) => {
 		const outputFormat = opts.outputFormat === "json" ? "json" : "human";
-		const exitCode = await runStatusAction({
-			outputFormat,
-			runId: opts.runId,
-			projectRoot: opts.projectRoot
-		});
-		process.exitCode = exitCode;
+		const root = opts.projectRoot;
+		let stateStore;
+		const doltStatePath = join(root, ".substrate", "state", ".dolt");
+		if (existsSync(doltStatePath)) try {
+			stateStore = createStateStore({
+				backend: "dolt",
+				basePath: join(root, ".substrate", "state")
+			});
+			await stateStore.initialize();
+		} catch {
+			stateStore = void 0;
+		}
+		try {
+			const exitCode = await runStatusAction({
+				outputFormat,
+				runId: opts.runId,
+				projectRoot: root,
+				stateStore,
+				history: opts.history
+			});
+			process.exitCode = exitCode;
+		} finally {
+			try {
+				await stateStore?.close();
+			} catch {}
+		}
 	});
 }
 
@@ -2581,7 +2664,7 @@ async function runSupervisorAction(options, deps = {}) {
 								const expDb = expDbWrapper.db;
 								const { runRunAction: runPipeline } = await import(
 									/* @vite-ignore */
-									"../run-Q-rgJf4a.js"
+									"../run-DP932Mmn.js"
 );
 								const runStoryFn = async (opts) => {
 									const exitCode = await runPipeline({
@@ -2826,7 +2909,7 @@ function registerSupervisorCommand(program, _version = "0.0.0", projectRoot = pr
 //#region src/cli/commands/metrics.ts
 const logger$11 = createLogger("metrics-cmd");
 async function runMetricsAction(options) {
-	const { outputFormat, projectRoot, limit = 10, compare, tagBaseline, analysis } = options;
+	const { outputFormat, projectRoot, limit = 10, compare, tagBaseline, analysis, sprint, story, taskType, since, aggregate } = options;
 	if (analysis !== void 0) {
 		const dbRoot$1 = await resolveMainRepoRoot(projectRoot);
 		const reportBase = join(dbRoot$1, "_bmad-output", "supervisor-reports", `${analysis}-analysis`);
@@ -2906,6 +2989,26 @@ async function runMetricsAction(options) {
 			return 0;
 		}
 		const runs = listRunMetrics(db, limit);
+		let doltMetrics;
+		const doltStatePath = join(dbRoot, ".substrate", "state", ".dolt");
+		const hasDoltFilters = sprint !== void 0 || story !== void 0 || taskType !== void 0 || since !== void 0 || aggregate === true;
+		if (existsSync(doltStatePath) && hasDoltFilters) try {
+			const stateStore = createStateStore({
+				backend: "dolt",
+				basePath: join(dbRoot, ".substrate", "state")
+			});
+			await stateStore.initialize();
+			const doltFilter = {};
+			if (sprint !== void 0) doltFilter.sprint = sprint;
+			if (story !== void 0) doltFilter.storyKey = story;
+			if (taskType !== void 0) doltFilter.taskType = taskType;
+			if (since !== void 0) doltFilter.since = since;
+			if (aggregate !== void 0) doltFilter.aggregate = aggregate;
+			doltMetrics = await stateStore.queryMetrics(doltFilter);
+			await stateStore.close();
+		} catch (doltErr) {
+			logger$11.warn({ err: doltErr }, "StateStore query failed — falling back to SQLite metrics only");
+		}
 		const storyMetricDecisions = getDecisionsByCategory(db, STORY_METRICS);
 		const storyMetrics = storyMetricDecisions.map((d) => {
 			const colonIdx = d.key.indexOf(":");
@@ -2935,12 +3038,31 @@ async function runMetricsAction(options) {
 				};
 			}
 		});
-		if (outputFormat === "json") process.stdout.write(formatOutput({
-			runs,
-			story_metrics: storyMetrics
-		}, "json", true) + "\n");
-		else {
-			if (runs.length === 0 && storyMetrics.length === 0) {
+		if (outputFormat === "json") {
+			const jsonPayload = {
+				runs,
+				story_metrics: storyMetrics
+			};
+			if (doltMetrics !== void 0) if (aggregate) {
+				const aggregateResults = doltMetrics.map((m) => ({
+					task_type: m.taskType,
+					count: m.count ?? 0,
+					avg_cost_usd: m.costUsd ?? 0,
+					sum_tokens_in: m.tokensIn ?? 0,
+					sum_tokens_out: m.tokensOut ?? 0
+				}));
+				const aggregateTotals = {
+					total_count: aggregateResults.reduce((sum, r) => sum + r.count, 0),
+					total_avg_cost_usd: aggregateResults.reduce((sum, r) => sum + r.avg_cost_usd, 0),
+					total_tokens_in: aggregateResults.reduce((sum, r) => sum + r.sum_tokens_in, 0),
+					total_tokens_out: aggregateResults.reduce((sum, r) => sum + r.sum_tokens_out, 0)
+				};
+				jsonPayload.aggregate_metrics = aggregateResults;
+				jsonPayload.aggregate_totals = aggregateTotals;
+			} else jsonPayload.dolt_metrics = doltMetrics;
+			process.stdout.write(formatOutput(jsonPayload, "json", true) + "\n");
+		} else {
+			if (runs.length === 0 && storyMetrics.length === 0 && (doltMetrics === void 0 || doltMetrics.length === 0)) {
 				process.stdout.write("No run metrics recorded yet. Run `substrate run` to generate metrics.\n");
 				return 0;
 			}
@@ -2970,6 +3092,41 @@ async function runMetricsAction(options) {
 					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`);
 				}
 			}
+			if (doltMetrics !== void 0 && doltMetrics.length > 0) if (aggregate) {
+				process.stdout.write(`\nStateStore Aggregate Metrics (by task type)\n`);
+				process.stdout.write("─".repeat(80) + "\n");
+				process.stdout.write(`  ${"Task Type".padEnd(20)} ${"Count".padStart(8)} ${"Avg Cost".padStart(12)} ${"Sum Tokens In".padStart(14)} ${"Sum Tokens Out".padStart(15)}\n`);
+				process.stdout.write("  " + "─".repeat(72) + "\n");
+				let totalCount = 0;
+				let totalCost = 0;
+				let totalTokensIn = 0;
+				let totalTokensOut = 0;
+				for (const m of doltMetrics) {
+					const count = m.count ?? 0;
+					const avgCost = m.costUsd !== void 0 ? `$${m.costUsd.toFixed(4)}` : "-";
+					const sumIn = m.tokensIn !== void 0 ? m.tokensIn.toLocaleString() : "-";
+					const sumOut = m.tokensOut !== void 0 ? m.tokensOut.toLocaleString() : "-";
+					totalCount += count;
+					totalCost += m.costUsd ?? 0;
+					totalTokensIn += m.tokensIn ?? 0;
+					totalTokensOut += m.tokensOut ?? 0;
+					process.stdout.write(`  ${m.taskType.padEnd(20)} ${String(count).padStart(8)} ${avgCost.padStart(12)} ${sumIn.padStart(14)} ${sumOut.padStart(15)}\n`);
+				}
+				process.stdout.write("  " + "─".repeat(72) + "\n");
+				process.stdout.write(`  ${"TOTAL".padEnd(20)} ${String(totalCount).padStart(8)} ${`$${totalCost.toFixed(4)}`.padStart(12)} ${totalTokensIn.toLocaleString().padStart(14)} ${totalTokensOut.toLocaleString().padStart(15)}\n`);
+			} else {
+				process.stdout.write(`\nStateStore Metrics (${doltMetrics.length} records)\n`);
+				process.stdout.write("─".repeat(80) + "\n");
+				process.stdout.write(`  ${"Story".padEnd(16)} ${"Task Type".padEnd(16)} ${"Tokens In".padStart(10)} ${"Tokens Out".padStart(11)} ${"Wall(ms)".padStart(10)} ${"Result".padEnd(12)}\n`);
+				process.stdout.write("  " + "─".repeat(76) + "\n");
+				for (const m of doltMetrics) {
+					const tokIn = m.tokensIn !== void 0 ? m.tokensIn.toLocaleString() : "-";
+					const tokOut = m.tokensOut !== void 0 ? m.tokensOut.toLocaleString() : "-";
+					const wall = m.wallClockMs !== void 0 ? String(m.wallClockMs) : "-";
+					const res = m.result ?? "-";
+					process.stdout.write(`  ${m.storyKey.padEnd(16)} ${m.taskType.padEnd(16)} ${tokIn.padStart(10)} ${tokOut.padStart(11)} ${wall.padStart(10)} ${res.padEnd(12)}\n`);
+				}
+			}
 		}
 		return 0;
 	} catch (err) {
@@ -2985,7 +3142,7 @@ async function runMetricsAction(options) {
 	}
 }
 function registerMetricsCommand(program, _version = "0.0.0", projectRoot = process.cwd()) {
-	program.command("metrics").description("Show historical pipeline run metrics and cross-run comparison").option("--project-root <path>", "Project root directory", projectRoot).option("--output-format <format>", "Output format: human (default) or json", "human").option("--limit <n>", "Number of runs to show (default: 10)", (v) => parseInt(v, 10), 10).option("--compare <run-id-a,run-id-b>", "Compare two runs side-by-side (comma-separated IDs, e.g. abc123,def456)").option("--tag-baseline <run-id>", "Mark a run as the performance baseline").option("--analysis <run-id>", "Read and output the analysis report for the specified run (AC5 of Story 17-3)").action(async (opts) => {
+	program.command("metrics").description("Show historical pipeline run metrics and cross-run comparison").option("--project-root <path>", "Project root directory", projectRoot).option("--output-format <format>", "Output format: human (default) or json", "human").option("--limit <n>", "Number of runs to show (default: 10)", (v) => parseInt(v, 10), 10).option("--compare <run-id-a,run-id-b>", "Compare two runs side-by-side (comma-separated IDs, e.g. abc123,def456)").option("--tag-baseline <run-id>", "Mark a run as the performance baseline").option("--analysis <run-id>", "Read and output the analysis report for the specified run (AC5 of Story 17-3)").option("--sprint <sprint>", "Filter StateStore metrics by sprint (e.g. sprint-1)").option("--story <story-key>", "Filter StateStore metrics by story key (e.g. 26-1)").option("--task-type <type>", "Filter StateStore metrics by task type (e.g. dev-story)").option("--since <iso-date>", "Filter StateStore metrics at or after this ISO timestamp").option("--aggregate", "Aggregate StateStore metrics grouped by task_type").action(async (opts) => {
 		const outputFormat = opts.outputFormat === "json" ? "json" : "human";
 		let compareIds;
 		if (opts.compare !== void 0) {
@@ -2998,12 +3155,165 @@ function registerMetricsCommand(program, _version = "0.0.0", projectRoot = proce
 			limit: opts.limit,
 			compare: compareIds,
 			tagBaseline: opts.tagBaseline,
-			analysis: opts.analysis
+			analysis: opts.analysis,
+			sprint: opts.sprint,
+			story: opts.story,
+			taskType: opts.taskType,
+			since: opts.since,
+			aggregate: opts.aggregate
 		});
 		process.exitCode = exitCode;
 	});
 }
 
+//#endregion
+//#region src/cli/commands/migrate.ts
+/**
+* Open the SQLite database at `dbPath` (read-only) and return a snapshot of
+* the story_metrics rows.  Returns an empty snapshot if the file does not
+* exist or the table is missing.
+*/
+function readSqliteSnapshot(dbPath) {
+	let db = null;
+	try {
+		db = new Database(dbPath, { readonly: true });
+	} catch {
+		return { storyMetrics: [] };
+	}
+	try {
+		const rows = db.prepare(`SELECT story_key, result, completed_at, created_at,
+                wall_clock_seconds, input_tokens, output_tokens,
+                cost_usd, review_cycles
+         FROM story_metrics`).all();
+		return { storyMetrics: rows };
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		process.stderr.write(`Warning: could not read story_metrics from SQLite: ${msg}\n`);
+		return { storyMetrics: [] };
+	} finally {
+		db.close();
+	}
+}
+const BATCH_SIZE = 100;
+/**
+* Upsert story_metrics rows into the Dolt `metrics` table.
+* When `dryRun` is `true`, no queries are executed.
+*/
+async function migrateDataToDolt(client, rows, dryRun) {
+	let metricsWritten = 0;
+	let skipped = 0;
+	const valid = [];
+	for (const row of rows) {
+		if (!row.story_key) {
+			skipped++;
+			continue;
+		}
+		const recordedAt = row.completed_at ?? row.created_at;
+		if (!recordedAt) {
+			skipped++;
+			continue;
+		}
+		valid.push(row);
+	}
+	if (dryRun) return {
+		metricsWritten: valid.length,
+		skipped
+	};
+	for (let i = 0; i < valid.length; i += BATCH_SIZE) {
+		const batch = valid.slice(i, i + BATCH_SIZE);
+		const placeholderRow = "(?,?,?,?,?,?,?,?,?,?,?,?)";
+		const placeholders = batch.map(() => placeholderRow).join(", ");
+		const sql = `INSERT INTO metrics (story_key, task_type, recorded_at, model, tokens_in, tokens_out, cache_read_tokens, cost_usd, wall_clock_ms, review_cycles, stall_count, result) VALUES ${placeholders} ON DUPLICATE KEY UPDATE cost_usd = VALUES(cost_usd), wall_clock_ms = VALUES(wall_clock_ms), result = VALUES(result)`;
+		const params = [];
+		for (const row of batch) params.push(row.story_key, "pipeline-run", row.completed_at ?? row.created_at, null, row.input_tokens ?? 0, row.output_tokens ?? 0, 0, row.cost_usd ?? 0, Math.round((row.wall_clock_seconds ?? 0) * 1e3), row.review_cycles ?? 0, 0, row.result);
+		await client.query(sql, params);
+		metricsWritten += batch.length;
+	}
+	return {
+		metricsWritten,
+		skipped
+	};
+}
+function registerMigrateCommand(program) {
+	program.command("migrate").description("Migrate historical SQLite data into Dolt").option("--dry-run", "Show counts without writing any data", false).option("--output-format <format>", "Output format: text or json", "text").option("--project-root <path>", "Project root directory (defaults to cwd)", process.cwd()).action(async (options) => {
+		const projectRoot = await resolveMainRepoRoot(options.projectRoot ?? process.cwd());
+		const statePath = join$1(projectRoot, ".substrate", "state");
+		const doltStatePath = join$1(statePath, ".dolt");
+		const doltNotInitializedMsg = "Dolt not initialized. Run 'substrate init --dolt' first.";
+		try {
+			await checkDoltInstalled();
+		} catch (err) {
+			if (err instanceof DoltNotInstalled) {
+				if (options.outputFormat === "json") console.log(JSON.stringify({
+					error: "ERR_DOLT_NOT_INITIALIZED",
+					message: doltNotInitializedMsg
+				}));
+				else process.stderr.write(doltNotInitializedMsg + "\n");
+				process.exitCode = 1;
+				return;
+			}
+			process.stderr.write(`Unexpected error checking Dolt: ${err instanceof Error ? err.message : String(err)}\n`);
+			process.exitCode = 2;
+			return;
+		}
+		if (!existsSync$1(doltStatePath)) {
+			if (options.outputFormat === "json") console.log(JSON.stringify({
+				error: "ERR_DOLT_NOT_INITIALIZED",
+				message: doltNotInitializedMsg
+			}));
+			else process.stderr.write(doltNotInitializedMsg + "\n");
+			process.exitCode = 1;
+			return;
+		}
+		const dbPath = join$1(projectRoot, ".substrate", "substrate.db");
+		const snapshot = readSqliteSnapshot(dbPath);
+		if (snapshot.storyMetrics.length === 0) {
+			if (options.outputFormat === "json") console.log(JSON.stringify({
+				migrated: false,
+				reason: "no-sqlite-data"
+			}));
+			else console.log("No SQLite data found — nothing to migrate");
+			return;
+		}
+		const repoPath = statePath;
+		const client = createDoltClient({ repoPath });
+		try {
+			await client.connect();
+			if (options.dryRun) {
+				const result$1 = await migrateDataToDolt(client, snapshot.storyMetrics, true);
+				if (options.outputFormat === "json") console.log(JSON.stringify({
+					migrated: false,
+					dryRun: true,
+					counts: { metrics: result$1.metricsWritten }
+				}));
+				else console.log(`Would migrate ${result$1.metricsWritten} story metrics (dry run — no changes written)`);
+				return;
+			}
+			const result = await migrateDataToDolt(client, snapshot.storyMetrics, false);
+			if (result.metricsWritten > 0) try {
+				await client.exec("add .");
+				await client.exec("commit -m \"Migrate historical data from SQLite\"");
+			} catch (execErr) {
+				const msg = execErr instanceof Error ? execErr.message : String(execErr);
+				process.stderr.write(`Warning: Dolt commit failed (non-fatal): ${msg}\n`);
+			}
+			if (result.skipped > 0) process.stderr.write(`Warning: Skipped ${result.skipped} row(s) — missing story_key or recorded_at.\n`);
+			if (options.outputFormat === "json") console.log(JSON.stringify({
+				migrated: true,
+				counts: { metrics: result.metricsWritten },
+				skipped: result.skipped
+			}));
+			else console.log(`Migrated ${result.metricsWritten} story metrics.`);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`Migration failed: ${msg}\n`);
+			process.exitCode = 2;
+		} finally {
+			await client.close();
+		}
+	});
+}
+
 //#endregion
 //#region src/persistence/queries/cost.ts
 const stmtCache = new WeakMap();
@@ -3590,7 +3900,7 @@ var MonitorDatabaseImpl = class {
 	}
 	_open() {
 		logger$9.info({ path: this._path }, "Opening monitor database");
-		this._db = new BetterSqlite3(this._path);
+		this._db = new Database(this._path);
 		const walResult = this._db.pragma("journal_mode = WAL");
 		if (walResult?.[0]?.journal_mode !== "wal") logger$9.warn({ result: walResult?.[0]?.journal_mode }, "Monitor DB: WAL pragma did not confirm wal mode");
 		this._db.pragma("synchronous = NORMAL");
@@ -6597,6 +6907,257 @@ function registerRetryEscalatedCommand(program, _version = "0.0.0", projectRoot
 	});
 }
 
+//#endregion
+//#region src/cli/commands/contracts.ts
+function registerContractsCommand(program) {
+	program.command("contracts").description("Show contract declarations and verification status").option("--output-format <format>", "Output format: text or json", "text").action(async (options) => {
+		const dbRoot = await resolveMainRepoRoot(process.cwd());
+		const statePath = join$1(dbRoot, ".substrate", "state");
+		const doltStatePath = join$1(statePath, ".dolt");
+		const storeConfig = existsSync$1(doltStatePath) ? {
+			backend: "dolt",
+			basePath: statePath
+		} : {
+			backend: "file",
+			basePath: statePath
+		};
+		const store = createStateStore(storeConfig);
+		try {
+			await store.initialize();
+			const contracts = await store.queryContracts();
+			if (contracts.length === 0) {
+				console.log("No contracts stored. Run a pipeline to populate contract data.");
+				return;
+			}
+			const storyKeys = [...new Set(contracts.map((c) => c.storyKey))];
+			const verificationMap = new Map();
+			for (const sk of storyKeys) {
+				const verifications = await store.getContractVerification(sk);
+				const contractVerdicts = new Map();
+				for (const v of verifications) contractVerdicts.set(v.contractName, v.verdict);
+				verificationMap.set(sk, contractVerdicts);
+			}
+			const mergedRecords = contracts.map((c) => {
+				const verdicts = verificationMap.get(c.storyKey);
+				const verdict = verdicts?.get(c.contractName);
+				return {
+					storyKey: c.storyKey,
+					contractName: c.contractName,
+					direction: c.direction,
+					schemaPath: c.schemaPath,
+					verificationStatus: verdict === "pass" ? "✓ pass" : verdict === "fail" ? "✗ fail" : "? pending",
+					verdict: verdict ?? "pending"
+				};
+			});
+			if (options.outputFormat === "json") {
+				console.log(JSON.stringify(mergedRecords, null, 2));
+				return;
+			}
+			const headers = [
+				"Story Key",
+				"Contract Name",
+				"Direction",
+				"Schema Path",
+				"Status"
+			];
+			const rows = mergedRecords.map((r) => [
+				r.storyKey,
+				r.contractName,
+				r.direction,
+				r.schemaPath,
+				r.verificationStatus
+			]);
+			const colWidths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)));
+			const formatRow = (cells) => cells.map((c, i) => c.padEnd(colWidths[i])).join("  ");
+			console.log(formatRow(headers));
+			console.log(colWidths.map((w) => "-".repeat(w)).join("  "));
+			for (const row of rows) console.log(formatRow(row));
+		} finally {
+			await store.close();
+		}
+	});
+}
+
+//#endregion
+//#region src/utils/degraded-mode-hint.ts
+/**
+* Determine the appropriate degraded-mode hint message based on whether Dolt
+* is installed and/or initialized at the given state path.
+*
+* @param statePath - Absolute path to the substrate state directory
+*                    (e.g. `/project/.substrate/state`).
+*/
+async function getDegradedModeHint(statePath) {
+	try {
+		await checkDoltInstalled();
+		if (!existsSync$1(join$1(statePath, ".dolt"))) return {
+			hint: "Note: Dolt is installed but not initialized. Run `substrate init --dolt` to enable diff and history features.",
+			doltInstalled: true
+		};
+		return {
+			hint: "Note: Running on file backend. Diff and history require Dolt.",
+			doltInstalled: true
+		};
+	} catch (err) {
+		if (err instanceof DoltNotInstalled) return {
+			hint: "Note: Dolt is not installed. Install it from https://docs.dolthub.com/introduction/installation, then run `substrate init --dolt` to enable diff and history features.",
+			doltInstalled: false
+		};
+		throw err;
+	}
+}
+/**
+* Emit a degraded-mode hint for the given command.
+*
+* - **Text mode**: writes the hint to `process.stderr` (not stdout).
+* - **JSON mode**: does NOT write to stderr; the caller is responsible for
+*   writing the returned `hint` field to stdout as part of its JSON envelope.
+*
+* @param options - Hint options including output format, command name, and
+*                  the resolved state directory path.
+* @returns The hint message and a flag indicating whether Dolt is installed.
+*/
+async function emitDegradedModeHint(options) {
+	const { hint, doltInstalled } = await getDegradedModeHint(options.statePath);
+	if (options.outputFormat !== "json") process.stderr.write(`\n${hint}\n`);
+	return {
+		hint,
+		doltInstalled
+	};
+}
+
+//#endregion
+//#region src/cli/commands/diff.ts
+function registerDiffCommand(program) {
+	program.command("diff [storyKey]").description("Show stat-based diff of database changes for a story or sprint").option("--sprint <sprintId>", "Diff all stories in the specified sprint").option("--output-format <format>", "Output format: text or json", "text").action(async (storyKey, options) => {
+		if (storyKey === void 0 && options.sprint === void 0) {
+			console.error("Error: provide a story key or --sprint <sprintId>");
+			process.exitCode = 1;
+			return;
+		}
+		const dbRoot = await resolveMainRepoRoot(process.cwd());
+		const statePath = join$1(dbRoot, ".substrate", "state");
+		const doltStatePath = join$1(statePath, ".dolt");
+		const storeConfig = existsSync$1(doltStatePath) ? {
+			backend: "dolt",
+			basePath: statePath
+		} : {
+			backend: "file",
+			basePath: statePath
+		};
+		const store = createStateStore(storeConfig);
+		try {
+			await store.initialize();
+			if (store instanceof FileStateStore) {
+				const result = await emitDegradedModeHint({
+					outputFormat: options.outputFormat,
+					command: "diff",
+					statePath
+				});
+				if (options.outputFormat === "json") console.log(JSON.stringify({
+					backend: "file",
+					hint: result.hint,
+					diff: null
+				}));
+				return;
+			}
+			if (storyKey !== void 0) {
+				const diff = await store.diffStory(storyKey);
+				if (options.outputFormat === "json") {
+					console.log(JSON.stringify(diff, null, 2));
+					return;
+				}
+				console.log(`Diff for story ${storyKey}:`);
+				if (diff.tables.length === 0) console.log("  (no changes)");
+				else for (const t of diff.tables) console.log(`  ${t.table}: +${t.added.length} -${t.deleted.length} ~${t.modified.length}`);
+			} else {
+				const stories = await store.queryStories({ sprint: options.sprint });
+				const tableMap = new Map();
+				for (const story of stories) {
+					const diff = await store.diffStory(story.storyKey);
+					for (const t of diff.tables) {
+						const existing = tableMap.get(t.table);
+						if (existing === void 0) tableMap.set(t.table, {
+							table: t.table,
+							added: [...t.added],
+							deleted: [...t.deleted],
+							modified: [...t.modified]
+						});
+						else {
+							existing.added = [...existing.added, ...t.added];
+							existing.deleted = [...existing.deleted, ...t.deleted];
+							existing.modified = [...existing.modified, ...t.modified];
+						}
+					}
+				}
+				const aggregated = Array.from(tableMap.values());
+				if (options.outputFormat === "json") {
+					console.log(JSON.stringify({
+						sprint: options.sprint,
+						tables: aggregated
+					}, null, 2));
+					return;
+				}
+				console.log(`Diff for sprint ${options.sprint}:`);
+				if (aggregated.length === 0) console.log("  (no changes)");
+				else for (const t of aggregated) console.log(`  ${t.table}: +${t.added.length} -${t.deleted.length} ~${t.modified.length}`);
+			}
+		} finally {
+			await store.close();
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/commands/history.ts
+function registerHistoryCommand(program) {
+	program.command("history").description("Show Dolt commit history for the state repository").option("--limit <n>", "Maximum number of commits to show", "20").option("--output-format <format>", "Output format: text or json", "text").action(async (options) => {
+		const limit = parseInt(options.limit, 10);
+		const dbRoot = await resolveMainRepoRoot(process.cwd());
+		const statePath = join$1(dbRoot, ".substrate", "state");
+		const doltStatePath = join$1(statePath, ".dolt");
+		const storeConfig = existsSync$1(doltStatePath) ? {
+			backend: "dolt",
+			basePath: statePath
+		} : {
+			backend: "file",
+			basePath: statePath
+		};
+		const store = createStateStore(storeConfig);
+		try {
+			await store.initialize();
+			if (store instanceof FileStateStore) {
+				const result = await emitDegradedModeHint({
+					outputFormat: options.outputFormat,
+					command: "history",
+					statePath
+				});
+				if (options.outputFormat === "json") console.log(JSON.stringify({
+					backend: "file",
+					hint: result.hint,
+					entries: []
+				}));
+				return;
+			}
+			const entries = await store.getHistory(limit);
+			if (entries.length === 0) {
+				console.log("No history available.");
+				return;
+			}
+			if (options.outputFormat === "json") {
+				console.log(JSON.stringify(entries, null, 2));
+				return;
+			}
+			for (const entry of entries) {
+				const storyKeyCol = (entry.storyKey ?? "-").padEnd(8);
+				console.log(`${entry.hash}  ${entry.timestamp}  ${storyKeyCol}  ${entry.message}`);
+			}
+		} finally {
+			await store.close();
+		}
+	});
+}
+
 //#endregion
 //#region src/cli/index.ts
 process.setMaxListeners(20);
@@ -6645,6 +7206,10 @@ async function createProgram() {
 	registerSupervisorCommand(program, version);
 	registerMetricsCommand(program, version);
 	registerRetryEscalatedCommand(program, version, process.cwd(), registry);
+	registerContractsCommand(program);
+	registerDiffCommand(program);
+	registerHistoryCommand(program);
+	registerMigrateCommand(program);
 	registerCostCommand(program, version);
 	registerMonitorCommand(program, version);
 	registerMergeCommand(program);