substrate-ai 0.3.7 → 0.4.0

package/dist/cli/index.js

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
-import { DEFAULT_CONFIG, DEFAULT_ROUTING_POLICY, DatabaseWrapper, DoltNotInstalled, FileStateStore, IngestionServer, SUBSTRATE_OWNED_SETTINGS_KEYS, TelemetryPersistence, 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-N7voPS_k.js";
+import { DEFAULT_CONFIG, DEFAULT_ROUTING_POLICY, DatabaseWrapper, DoltClient, DoltNotInstalled, DoltRepoMapMetaRepository, DoltSymbolRepository, FileStateStore, GitClient, GrammarLoader, IngestionServer, RepoMapInjector, RepoMapModule, RepoMapQueryEngine, RepoMapStorage, SUBSTRATE_OWNED_SETTINGS_KEYS, SymbolParser, TelemetryPersistence, 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-cqQmW8wL.js";
 import { createLogger } from "../logger-D2fS2ccL.js";
 import { AdapterRegistry } from "../adapter-registry-rSOJ9Kvz.js";
 import { CURRENT_CONFIG_FORMAT_VERSION, CURRENT_TASK_GRAPH_VERSION, PartialSubstrateConfigSchema } from "../config-migrator-DtZW1maj.js";
 import { ConfigError, createEventBus } from "../helpers-BihqWgVe.js";
-import { addTokenUsage, createDecision, createPipelineRun, getDecisionsByCategory, getDecisionsByPhaseForRun, getLatestRun, getTokenUsageSummary, listRequirements, updatePipelineRun } from "../decisions-CdpiJIm5.js";
-import { ESCALATION_DIAGNOSIS, EXPERIMENT_RESULT, OPERATIONAL_FINDING, STORY_METRICS, aggregateTokenUsageForRun, compareRunMetrics, getBaselineRunMetrics, getRunMetrics, getStoryMetricsForRun, incrementRunRestarts, listRunMetrics, tagRunAsBaseline } from "../operational-DisxqtjC.js";
-import { abortMerge, createWorktree, getConflictingFiles, getMergedFiles, getOrphanedWorktrees, performMerge, removeBranch, removeWorktree, simulateMerge, verifyGitVersion } from "../git-utils-UbKLSGsD.js";
-import "../version-manager-impl-zsJjBhak.js";
-import { registerUpgradeCommand } from "../upgrade-DTzeenA-.js";
+import { RoutingRecommender } from "../routing-CZfJB3y9.js";
+import { addTokenUsage, createDecision, createPipelineRun, getDecisionsByCategory, getDecisionsByPhaseForRun, getLatestRun, getTokenUsageSummary, listRequirements, updatePipelineRun } from "../decisions-Db8GTbH2.js";
+import { ESCALATION_DIAGNOSIS, EXPERIMENT_RESULT, OPERATIONAL_FINDING, STORY_METRICS, aggregateTokenUsageForRun, compareRunMetrics, getBaselineRunMetrics, getRunMetrics, getStoryMetricsForRun, incrementRunRestarts, listRunMetrics, tagRunAsBaseline } from "../operational-C0_y8DAs.js";
+import { abortMerge, createWorktree, getConflictingFiles, getMergedFiles, getOrphanedWorktrees, performMerge, removeBranch, removeWorktree, simulateMerge, verifyGitVersion } from "../git-utils-C-fdrHF_.js";
+import "../version-manager-impl-DTlmGvHb.js";
+import { registerUpgradeCommand } from "../upgrade-C8_VcI8B.js";
 import { Command } from "commander";
 import { fileURLToPath } from "url";
 import { dirname, join, resolve } from "path";
@@ -19,7 +20,7 @@ import { createRequire } from "node:module";
 import * as path$1 from "node:path";
 import { isAbsolute, join as join$1 } from "node:path";
 import Database from "better-sqlite3";
-import { access as access$1 } from "node:fs/promises";
+import { access as access$1, readFile as readFile$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";
@@ -259,7 +260,7 @@ function registerAdaptersCommand(program, version, registry) {
 
 //#endregion
 //#region src/cli/commands/init.ts
-const logger$16 = createLogger("init");
+const logger$18 = createLogger("init");
 const __dirname = dirname(new URL(import.meta.url).pathname);
 const INIT_EXIT_SUCCESS = 0;
 const INIT_EXIT_ERROR = 1;
@@ -280,7 +281,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$18.info({
 		version,
 		dest: bmadDest
 	}, "Scaffolding BMAD framework");
@@ -290,7 +291,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$18.info({
 				dir,
 				dest: destDir
 			}, "Scaffolded BMAD framework directory");
@@ -309,7 +310,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$18.info({ configFile }, "Generated _bmad/_config/config.yaml stub");
 	}
 }
 const CLAUDE_MD_START_MARKER = "<!-- substrate:start -->";
@@ -324,7 +325,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$18.warn({ templatePath }, "CLAUDE.md substrate section template not found; skipping");
 		return;
 	}
 	if (!sectionContent.endsWith("\n")) sectionContent += "\n";
@@ -342,7 +343,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$18.info({ claudeMdPath }, "Wrote substrate section to CLAUDE.md");
 }
 async function scaffoldStatuslineScript(projectRoot) {
 	const pkgRoot = findPackageRoot(__dirname);
@@ -353,7 +354,7 @@ async function scaffoldStatuslineScript(projectRoot) {
 	try {
 		content = await readFile(templatePath, "utf8");
 	} catch {
-		logger$16.warn({ templatePath }, "statusline.sh template not found; skipping");
+		logger$18.warn({ templatePath }, "statusline.sh template not found; skipping");
 		return;
 	}
 	const claudeDir = join(projectRoot, ".claude");
@@ -361,7 +362,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$18.info({ statuslinePath }, "Wrote .claude/statusline.sh");
 }
 async function scaffoldClaudeSettings(projectRoot) {
 	const claudeDir = join(projectRoot, ".claude");
@@ -377,7 +378,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$18.info({ settingsPath }, "Wrote substrate settings to .claude/settings.json");
 }
 function resolveBmadMethodInstallerLibPath(fromDir = __dirname) {
 	try {
@@ -447,7 +448,7 @@ async function compileBmadAgents(bmadDir) {
 				writeFileSync(mdPath, result.xml, "utf-8");
 				compiled++;
 			} catch (compileErr) {
-				logger$16.debug({
+				logger$18.debug({
 					err: compileErr,
 					file
 				}, "Failed to compile agent YAML");
@@ -468,9 +469,9 @@ async function scaffoldClaudeCommands(projectRoot, outputFormat) {
 		const _require = createRequire(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$18.info({ compiledCount }, "Compiled agent YAML files to MD");
 		} catch (compileErr) {
-			logger$16.warn({ err: compileErr }, "Agent compilation failed; agent commands may be incomplete");
+			logger$18.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"));
@@ -482,7 +483,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$18.warn({ err: manifestErr }, "ManifestGenerator failed; workflow/task commands may be incomplete");
 		}
 		const commandsDir = join(projectRoot, ".claude", "commands");
 		mkdirSync(commandsDir, { recursive: true });
@@ -498,7 +499,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$18.info({
 			agentCount,
 			workflowCount,
 			taskToolCount,
@@ -508,7 +509,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$18.warn({ err }, "scaffoldClaudeCommands failed; init continues");
 	}
 }
 const PROVIDER_DEFAULTS = DEFAULT_CONFIG.providers;
@@ -583,7 +584,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$18.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;
@@ -632,12 +633,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$18.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$18.info({
 				pack: packName,
 				dest: packPath
 			}, "Scaffolded methodology pack");
@@ -674,17 +675,17 @@ async function runInitAction(options) {
 					process.stderr.write(`${err.message}\n`);
 					return INIT_EXIT_ERROR;
 				}
-				logger$16.debug("Dolt not installed, skipping auto-init");
+				logger$18.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({ error: msg }, "Dolt auto-init failed (non-blocking)");
+				logger$18.warn({ error: msg }, "Dolt auto-init failed (non-blocking)");
 			}
 		}
-		else logger$16.debug("Dolt step was skipped (--no-dolt)");
+		else logger$18.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,
@@ -708,6 +709,7 @@ async function runInitAction(options) {
 			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`);
+			else if (doltMode !== "skip") process.stdout.write(`ℹ  Dolt not detected — install Dolt for versioned state, \`substrate diff\`, and observability persistence. See: https://docs.dolthub.com/introduction/installation\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;
@@ -715,7 +717,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$18.error({ err }, "init failed");
 		return INIT_EXIT_ERROR;
 	}
 }
@@ -738,7 +740,7 @@ function registerInitCommand(program, _version, registry) {
 
 //#endregion
 //#region src/cli/commands/config.ts
-const logger$15 = createLogger("config-cmd");
+const logger$17 = createLogger("config-cmd");
 const CONFIG_EXIT_SUCCESS = 0;
 const CONFIG_EXIT_ERROR = 1;
 const CONFIG_EXIT_INVALID = 2;
@@ -764,7 +766,7 @@ async function runConfigShow(opts = {}) {
 			return CONFIG_EXIT_INVALID;
 		}
 		const message = err instanceof Error ? err.message : String(err);
-		logger$15.error({ err }, "Failed to load configuration");
+		logger$17.error({ err }, "Failed to load configuration");
 		process.stderr.write(`  Error loading configuration: ${message}\n`);
 		return CONFIG_EXIT_ERROR;
 	}
@@ -838,7 +840,7 @@ async function runConfigExport(opts = {}) {
 			return CONFIG_EXIT_INVALID;
 		}
 		const message = err instanceof Error ? err.message : String(err);
-		logger$15.error({ err }, "Failed to load configuration");
+		logger$17.error({ err }, "Failed to load configuration");
 		process.stderr.write(`Error loading configuration: ${message}\n`);
 		return CONFIG_EXIT_ERROR;
 	}
@@ -992,7 +994,7 @@ function registerConfigCommand(program, _version) {
 
 //#endregion
 //#region src/cli/commands/resume.ts
-const logger$14 = createLogger("resume-cmd");
+const logger$16 = createLogger("resume-cmd");
 async function runResumeAction(options) {
 	const { runId: specifiedRunId, stopAfter, outputFormat, projectRoot, concurrency, pack: packName, registry } = options;
 	if (stopAfter !== void 0 && !VALID_PHASES.includes(stopAfter)) {
@@ -1075,7 +1077,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$14.error({ err }, "auto resume failed");
+		logger$16.error({ err }, "auto resume failed");
 		return 1;
 	} finally {
 		try {
@@ -1240,7 +1242,7 @@ async function runFullPipelineFromPhase(options) {
 							});
 						}
 					} catch (err) {
-						logger$14.warn({ err }, "Failed to record token usage");
+						logger$16.warn({ err }, "Failed to record token usage");
 					}
 				});
 				const storyKeys = resolveStoryKeys(db, projectRoot, { pipelineRunId: runId });
@@ -1295,7 +1297,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$14.error({ err }, "pipeline from phase failed");
+		logger$16.error({ err }, "pipeline from phase failed");
 		return 1;
 	} finally {
 		try {
@@ -1321,7 +1323,7 @@ function registerResumeCommand(program, _version = "0.0.0", projectRoot = proces
 
 //#endregion
 //#region src/cli/commands/status.ts
-const logger$13 = createLogger("status-cmd");
+const logger$15 = createLogger("status-cmd");
 async function runStatusAction(options) {
 	const { outputFormat, runId, projectRoot, stateStore, history } = options;
 	if (history === true) {
@@ -1377,7 +1379,7 @@ async function runStatusAction(options) {
 		if (stateStore) try {
 			storeStories = await stateStore.queryStories({});
 		} catch (err) {
-			logger$13.debug({ err }, "StateStore query failed, continuing without store data");
+			logger$15.debug({ err }, "StateStore query failed, continuing without store data");
 		}
 		if (outputFormat === "json") {
 			const statusOutput = buildPipelineStatusOutput(run, tokenSummary, decisionsCount, storiesCount);
@@ -1480,7 +1482,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$13.error({ err }, "status action failed");
+		logger$15.error({ err }, "status action failed");
 		return 1;
 	} finally {
 		try {
@@ -1924,7 +1926,7 @@ Analyze thoroughly and return ONLY the JSON array with no additional text.`;
 
 //#endregion
 //#region src/cli/commands/amend.ts
-const logger$12 = createLogger("amend-cmd");
+const logger$14 = createLogger("amend-cmd");
 /**
 * Detect and apply supersessions after a phase completes in an amendment run.
 *
@@ -1955,7 +1957,7 @@ function runPostPhaseSupersessionDetection(db, amendmentRunId, currentPhase, han
 			});
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
-			logger$12.warn({
+			logger$14.warn({
 				err,
 				originalId: parentMatch.id,
 				supersedingId: newDec.id
@@ -2089,7 +2091,7 @@ async function runAmendAction(options) {
 		for (let i = startIdx; i < phaseOrder.length; i++) {
 			const currentPhase = phaseOrder[i];
 			const amendmentContext = handler.loadContextForPhase(currentPhase);
-			logger$12.info({
+			logger$14.info({
 				phase: currentPhase,
 				amendmentContextLen: amendmentContext.length
 			}, "Amendment context loaded for phase");
@@ -2209,7 +2211,7 @@ async function runAmendAction(options) {
 	} catch (err) {
 		const msg = err instanceof Error ? err.message : String(err);
 		process.stderr.write(`Error: ${msg}\n`);
-		logger$12.error({ err }, "amend failed");
+		logger$14.error({ err }, "amend failed");
 		return 1;
 	} finally {
 		try {
@@ -2682,11 +2684,11 @@ async function runSupervisorAction(options, deps = {}) {
 						try {
 							const { createExperimenter } = await import(
 								/* @vite-ignore */
-								"../experimenter-jto3orYl.js"
+								"../experimenter-CvxtqzXz.js"
 );
 							const { getLatestRun: getLatest } = await import(
 								/* @vite-ignore */
-								"../decisions-CbysnTi5.js"
+								"../decisions-D7Ao_KcL.js"
 );
 							const dbPath = join(projectRoot, ".substrate", "substrate.db");
 							const expDbWrapper = new DatabaseWrapper(dbPath);
@@ -2696,7 +2698,7 @@ async function runSupervisorAction(options, deps = {}) {
 								const expDb = expDbWrapper.db;
 								const { runRunAction: runPipeline } = await import(
 									/* @vite-ignore */
-									"../run-C_hKt2wY.js"
+									"../run-CQJP37ZC.js"
 );
 								const runStoryFn = async (opts) => {
 									const exitCode = await runPipeline({
@@ -2943,7 +2945,7 @@ function registerSupervisorCommand(program, _version = "0.0.0", projectRoot = pr
 
 //#endregion
 //#region src/cli/commands/metrics.ts
-const logger$11 = createLogger("metrics-cmd");
+const logger$13 = createLogger("metrics-cmd");
 async function openTelemetryDb(dbPath) {
 	if (!existsSync(dbPath)) return null;
 	try {
@@ -3015,7 +3017,7 @@ function printCategoryTable(stats, label) {
 	}
 }
 async function runMetricsAction(options) {
-	const { outputFormat, projectRoot, limit = 10, compare, tagBaseline, analysis, sprint, story, taskType, since, aggregate, efficiency, recommendations, turns, consumers, categories, compareStories } = options;
+	const { outputFormat, projectRoot, limit = 10, compare, tagBaseline, analysis, sprint, story, taskType, since, aggregate, efficiency, recommendations, turns, consumers, categories, compareStories, routingRecommendations } = options;
 	const telemetryModes = [
 		efficiency,
 		recommendations,
@@ -3154,6 +3156,59 @@ async function runMetricsAction(options) {
 			} catch {}
 		}
 	}
+	if (routingRecommendations === true) {
+		const dbRoot$1 = await resolveMainRepoRoot(projectRoot);
+		const dbDir = join(dbRoot$1, ".substrate");
+		const doltStatePath = join(dbDir, "state", ".dolt");
+		const doltExists = existsSync(doltStatePath);
+		const stateBackend = doltExists ? "dolt" : "file";
+		const stateBasePath = join(dbDir, "state");
+		const stateStore = createStateStore({
+			backend: stateBackend,
+			basePath: stateBasePath
+		});
+		await stateStore.initialize();
+		try {
+			const runIndexRaw = await stateStore.getMetric("__global__", "phase_token_breakdown_runs");
+			const runIds = Array.isArray(runIndexRaw) ? runIndexRaw : [];
+			const recentRunIds = runIds.slice(-20);
+			const breakdowns = [];
+			for (const runId of recentRunIds) try {
+				const raw = await stateStore.getMetric(runId, "phase_token_breakdown");
+				if (raw !== void 0 && raw !== null) {
+					const parsed = typeof raw === "string" ? JSON.parse(raw) : raw;
+					breakdowns.push(parsed);
+				}
+			} catch {}
+			const routingConfigPath = join(dbDir, "routing.yml");
+			let routingConfig = null;
+			if (existsSync(routingConfigPath)) try {
+				const { loadModelRoutingConfig } = await import("../routing-DWCBjrt7.js");
+				routingConfig = loadModelRoutingConfig(routingConfigPath);
+			} catch {}
+			if (routingConfig === null) routingConfig = {
+				version: 1,
+				phases: {},
+				baseline_model: "claude-sonnet"
+			};
+			const recommender = new RoutingRecommender(createLogger("routing:recommender"));
+			const analysis$1 = recommender.analyze(breakdowns, routingConfig);
+			if (outputFormat === "json") process.stdout.write(formatOutput({
+				recommendations: analysis$1.recommendations,
+				analysisRuns: analysis$1.analysisRuns,
+				insufficientData: analysis$1.insufficientData
+			}, "json", true) + "\n");
+			else {
+				process.stdout.write(`Routing Recommendations:\n`);
+				if (analysis$1.insufficientData) process.stdout.write(`No recommendations yet — need at least 3 pipeline runs\n`);
+				else if (analysis$1.recommendations.length === 0) process.stdout.write(`  No recommendations — all phases are in the neutral zone\n`);
+				else for (const rec of analysis$1.recommendations) process.stdout.write(`  ${rec.phase} | ${rec.currentModel} → ${rec.suggestedModel} | est. savings: ${Math.round(rec.estimatedSavingsPct)}%\n`);
+			}
+		} finally {
+			await stateStore.close().catch(() => {});
+		}
+		return 0;
+	}
 	if (analysis !== void 0) {
 		const dbRoot$1 = await resolveMainRepoRoot(projectRoot);
 		const reportBase = join(dbRoot$1, "_bmad-output", "supervisor-reports", `${analysis}-analysis`);
@@ -3251,7 +3306,7 @@ async function runMetricsAction(options) {
 			doltMetrics = await stateStore.queryMetrics(doltFilter);
 			await stateStore.close();
 		} catch (doltErr) {
-			logger$11.warn({ err: doltErr }, "StateStore query failed — falling back to SQLite metrics only");
+			logger$13.warn({ err: doltErr }, "StateStore query failed — falling back to SQLite metrics only");
 		}
 		const storyMetricDecisions = getDecisionsByCategory(db, STORY_METRICS);
 		const storyMetrics = storyMetricDecisions.map((d) => {
@@ -3282,9 +3337,21 @@ async function runMetricsAction(options) {
 				};
 			}
 		});
+		const phaseBreakdownMap = {};
+		try {
+			const kvStore = new FileStateStore({ basePath: join(dbRoot, ".substrate") });
+			for (const run of runs) {
+				const raw = await kvStore.getMetric(run.run_id, "phase_token_breakdown");
+				phaseBreakdownMap[run.run_id] = raw !== void 0 ? raw : null;
+			}
+		} catch {}
 		if (outputFormat === "json") {
+			const runsWithBreakdown = runs.map((run) => ({
+				...run,
+				phase_token_breakdown: phaseBreakdownMap[run.run_id] ?? null
+			}));
 			const jsonPayload = {
-				runs,
+				runs: runsWithBreakdown,
 				story_metrics: storyMetrics
 			};
 			if (doltMetrics !== void 0) if (aggregate) {
@@ -3322,6 +3389,11 @@ async function runMetricsAction(options) {
 					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`);
+					const breakdown = phaseBreakdownMap[run.run_id];
+					if (breakdown !== null && breakdown !== void 0 && breakdown.entries.length > 0) {
+						process.stdout.write("  Phase Token Breakdown:\n");
+						for (const entry of breakdown.entries) process.stdout.write(`    ${entry.phase.padEnd(10)} | ${entry.model.padEnd(30)} | in: ${entry.inputTokens} | out: ${entry.outputTokens} | dispatches: ${entry.dispatchCount}\n`);
+					}
 				}
 			}
 			if (storyMetrics.length > 0) {
@@ -3377,7 +3449,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$11.error({ err }, "metrics action failed");
+		logger$13.error({ err }, "metrics action failed");
 		return 1;
 	} finally {
 		try {
@@ -3386,7 +3458,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)").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").option("--efficiency", "Show telemetry efficiency scores for recent stories").option("--recommendations", "Show all telemetry recommendations across stories").option("--turns <storyKey>", "Show per-turn analysis for a specific story").option("--consumers <storyKey>", "Show consumer stats for a specific story").option("--categories", "Show category stats (optionally scoped by --story <storyKey>)").option("--compare-stories <storyA,storyB>", "Compare efficiency scores of two stories side-by-side (comma-separated keys)").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").option("--efficiency", "Show telemetry efficiency scores for recent stories").option("--recommendations", "Show all telemetry recommendations across stories").option("--turns <storyKey>", "Show per-turn analysis for a specific story").option("--consumers <storyKey>", "Show consumer stats for a specific story").option("--categories", "Show category stats (optionally scoped by --story <storyKey>)").option("--compare-stories <storyA,storyB>", "Compare efficiency scores of two stories side-by-side (comma-separated keys)").option("--routing-recommendations", "Show routing recommendations derived from phase token breakdown history").action(async (opts) => {
 		const outputFormat = opts.outputFormat === "json" ? "json" : "human";
 		let compareIds;
 		if (opts.compare !== void 0) {
@@ -3420,7 +3492,8 @@ function registerMetricsCommand(program, _version = "0.0.0", projectRoot = proce
 			...opts.turns !== void 0 && { turns: opts.turns },
 			...opts.consumers !== void 0 && { consumers: opts.consumers },
 			...opts.categories !== void 0 && { categories: opts.categories },
-			...compareStoriesIds !== void 0 && { compareStories: compareStoriesIds }
+			...compareStoriesIds !== void 0 && { compareStories: compareStoriesIds },
+			...opts.routingRecommendations !== void 0 && { routingRecommendations: opts.routingRecommendations }
 		};
 		const exitCode = await runMetricsAction(metricsOpts);
 		process.exitCode = exitCode;
@@ -3805,7 +3878,7 @@ function getPlanningCostTotal(db, sessionId) {
 function getLatestSessionId(_db) {
 	return null;
 }
-const logger$10 = createLogger("cost-cmd");
+const logger$12 = createLogger("cost-cmd");
 const COST_EXIT_SUCCESS = 0;
 const COST_EXIT_ERROR = 1;
 /**
@@ -4051,7 +4124,7 @@ async function runCostAction(options) {
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		process.stderr.write(`Error: ${message}\n`);
-		logger$10.error({ err }, "runCostAction failed");
+		logger$12.error({ err }, "runCostAction failed");
 		return COST_EXIT_ERROR;
 	} finally {
 		if (wrapper !== null) try {
@@ -4153,7 +4226,7 @@ function applyMonitorSchema(db) {
 
 //#endregion
 //#region src/persistence/monitor-database.ts
-const logger$9 = createLogger("persistence:monitor-db");
+const logger$11 = createLogger("persistence:monitor-db");
 var MonitorDatabaseImpl = class {
 	_db = null;
 	_path;
@@ -4164,10 +4237,10 @@ var MonitorDatabaseImpl = class {
 		this._open();
 	}
 	_open() {
-		logger$9.info({ path: this._path }, "Opening monitor database");
+		logger$11.info({ path: this._path }, "Opening monitor database");
 		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");
+		if (walResult?.[0]?.journal_mode !== "wal") logger$11.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");
@@ -4202,7 +4275,7 @@ var MonitorDatabaseImpl = class {
         total_retries       = total_retries + @retries,
         last_updated        = @lastUpdated
     `);
-		logger$9.info({ path: this._path }, "Monitor database ready");
+		logger$11.info({ path: this._path }, "Monitor database ready");
 	}
 	_assertOpen() {
 		if (this._db === null) throw new Error("MonitorDatabase: connection is closed");
@@ -4351,7 +4424,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$9.info({
+		logger$11.info({
 			cutoff,
 			deleted: result.changes
 		}, "Pruned old task_metrics rows");
@@ -4390,13 +4463,13 @@ var MonitorDatabaseImpl = class {
 			db.exec("ROLLBACK");
 			throw err;
 		}
-		logger$9.info("Rebuilt performance_aggregates from task_metrics");
+		logger$11.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$9.info({ path: this._path }, "Monitor data reset — all rows deleted");
+		logger$11.info({ path: this._path }, "Monitor data reset — all rows deleted");
 	}
 	getTaskMetricsDateRange() {
 		const db = this._assertOpen();
@@ -4413,7 +4486,7 @@ var MonitorDatabaseImpl = class {
 		if (this._db === null) return;
 		this._db.close();
 		this._db = null;
-		logger$9.info({ path: this._path }, "Monitor database closed");
+		logger$11.info({ path: this._path }, "Monitor database closed");
 	}
 	/**
 	* Access the raw underlying database for testing purposes only.
@@ -4426,7 +4499,7 @@ var MonitorDatabaseImpl = class {
 
 //#endregion
 //#region src/modules/monitor/recommendation-engine.ts
-const logger$8 = createLogger("monitor:recommendations");
+const logger$10 = createLogger("monitor:recommendations");
 var RecommendationEngine = class {
 	_monitorDb;
 	_filters;
@@ -4459,7 +4532,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$8.debug("No performance aggregates found — no recommendations to generate");
+			logger$10.debug("No performance aggregates found — no recommendations to generate");
 			return [];
 		}
 		const byTaskType = new Map();
@@ -4524,7 +4597,7 @@ var RecommendationEngine = class {
 			if (confDiff !== 0) return confDiff;
 			return b.improvement_percentage - a.improvement_percentage;
 		});
-		logger$8.debug({ count: recommendations.length }, "Generated routing recommendations");
+		logger$10.debug({ count: recommendations.length }, "Generated routing recommendations");
 		return recommendations;
 	}
 	/**
@@ -4690,7 +4763,7 @@ function generateMonitorReport(monitorDb, options = {}) {
 
 //#endregion
 //#region src/cli/commands/monitor.ts
-const logger$7 = createLogger("monitor-cmd");
+const logger$9 = createLogger("monitor-cmd");
 const MONITOR_EXIT_SUCCESS = 0;
 const MONITOR_EXIT_ERROR = 1;
 /**
@@ -4893,7 +4966,7 @@ async function runMonitorReportAction(options) {
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		process.stderr.write(`Error: ${message}\n`);
-		logger$7.error({ err }, "runMonitorReportAction failed");
+		logger$9.error({ err }, "runMonitorReportAction failed");
 		return MONITOR_EXIT_ERROR;
 	} finally {
 		if (monitorDb !== null) try {
@@ -4955,7 +5028,7 @@ async function runMonitorStatusAction(options) {
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		process.stderr.write(`Error: ${message}\n`);
-		logger$7.error({ err }, "runMonitorStatusAction failed");
+		logger$9.error({ err }, "runMonitorStatusAction failed");
 		return MONITOR_EXIT_ERROR;
 	} finally {
 		if (monitorDb !== null) try {
@@ -4990,7 +5063,7 @@ async function runMonitorResetAction(options) {
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		process.stderr.write(`Error: ${message}\n`);
-		logger$7.error({ err }, "runMonitorResetAction failed");
+		logger$9.error({ err }, "runMonitorResetAction failed");
 		return MONITOR_EXIT_ERROR;
 	} finally {
 		if (monitorDb !== null) try {
@@ -5038,7 +5111,7 @@ async function runMonitorRecommendationsAction(options) {
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		process.stderr.write(`Error: ${message}\n`);
-		logger$7.error({ err }, "runMonitorRecommendationsAction failed");
+		logger$9.error({ err }, "runMonitorRecommendationsAction failed");
 		return MONITOR_EXIT_ERROR;
 	} finally {
 		if (monitorDb !== null) try {
@@ -5116,7 +5189,7 @@ function registerMonitorCommand(program, version = "0.0.0", projectRoot = proces
 
 //#endregion
 //#region src/modules/git-worktree/git-worktree-manager-impl.ts
-const logger$6 = createLogger("git-worktree");
+const logger$8 = createLogger("git-worktree");
 const BRANCH_PREFIX = "substrate/task-";
 const DEFAULT_WORKTREE_BASE = ".substrate-worktrees";
 var GitWorktreeManagerImpl = class {
@@ -5135,7 +5208,7 @@ var GitWorktreeManagerImpl = class {
 		this._db = db;
 		this._onTaskReady = ({ taskId }) => {
 			this._handleTaskReady(taskId).catch((err) => {
-				logger$6.error({
+				logger$8.error({
 					taskId,
 					err
 				}, "Unhandled error in _handleTaskReady");
@@ -5149,40 +5222,40 @@ var GitWorktreeManagerImpl = class {
 		};
 	}
 	async initialize() {
-		logger$6.info({ projectRoot: this._projectRoot }, "GitWorktreeManager.initialize()");
+		logger$8.info({ projectRoot: this._projectRoot }, "GitWorktreeManager.initialize()");
 		await this.verifyGitVersion();
 		const cleaned = await this.cleanupAllWorktrees();
-		if (cleaned > 0) logger$6.info({ cleaned }, "Recovered orphaned worktrees on startup");
+		if (cleaned > 0) logger$8.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$6.info("GitWorktreeManager initialized");
+		logger$8.info("GitWorktreeManager initialized");
 	}
 	async shutdown() {
-		logger$6.info("GitWorktreeManager.shutdown()");
+		logger$8.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$6.info("GitWorktreeManager shutdown complete");
+		logger$8.info("GitWorktreeManager shutdown complete");
 	}
 	async _handleTaskReady(taskId) {
-		logger$6.debug({ taskId }, "task:ready — creating worktree");
+		logger$8.debug({ taskId }, "task:ready — creating worktree");
 		try {
 			await this.createWorktree(taskId);
 		} catch (err) {
-			logger$6.error({
+			logger$8.error({
 				taskId,
 				err
 			}, "Failed to create worktree for task");
 		}
 	}
 	async _handleTaskDone(taskId) {
-		logger$6.debug({ taskId }, "task done — cleaning up worktree");
+		logger$8.debug({ taskId }, "task done — cleaning up worktree");
 		try {
 			await this.cleanupWorktree(taskId);
 		} catch (err) {
-			logger$6.warn({
+			logger$8.warn({
 				taskId,
 				err
 			}, "Failed to cleanup worktree for task");
@@ -5192,7 +5265,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$6.debug({
+		logger$8.debug({
 			taskId,
 			branchName,
 			worktreePath,
@@ -5212,7 +5285,7 @@ var GitWorktreeManagerImpl = class {
 			worktreePath,
 			createdAt
 		};
-		logger$6.info({
+		logger$8.info({
 			taskId,
 			branchName,
 			worktreePath
@@ -5222,7 +5295,7 @@ var GitWorktreeManagerImpl = class {
 	async cleanupWorktree(taskId) {
 		const branchName = BRANCH_PREFIX + taskId;
 		const worktreePath = this.getWorktreePath(taskId);
-		logger$6.debug({
+		logger$8.debug({
 			taskId,
 			branchName,
 			worktreePath
@@ -5232,7 +5305,7 @@ var GitWorktreeManagerImpl = class {
 			await access$1(worktreePath);
 			worktreeExists = true;
 		} catch {
-			logger$6.debug({
+			logger$8.debug({
 				taskId,
 				worktreePath
 			}, "cleanupWorktree: worktree does not exist, skipping removal");
@@ -5240,7 +5313,7 @@ var GitWorktreeManagerImpl = class {
 		if (worktreeExists) try {
 			await removeWorktree(worktreePath, this._projectRoot);
 		} catch (err) {
-			logger$6.warn({
+			logger$8.warn({
 				taskId,
 				worktreePath,
 				err
@@ -5249,7 +5322,7 @@ var GitWorktreeManagerImpl = class {
 		try {
 			await removeBranch(branchName, this._projectRoot);
 		} catch (err) {
-			logger$6.warn({
+			logger$8.warn({
 				taskId,
 				branchName,
 				err
@@ -5259,13 +5332,13 @@ var GitWorktreeManagerImpl = class {
 			taskId,
 			branchName
 		});
-		logger$6.info({
+		logger$8.info({
 			taskId,
 			branchName
 		}, "Worktree cleaned up");
 	}
 	async cleanupAllWorktrees() {
-		logger$6.debug({ projectRoot: this._projectRoot }, "cleanupAllWorktrees");
+		logger$8.debug({ projectRoot: this._projectRoot }, "cleanupAllWorktrees");
 		const orphanedPaths = await getOrphanedWorktrees(this._projectRoot, this._baseDirectory);
 		let cleaned = 0;
 		for (const worktreePath of orphanedPaths) {
@@ -5274,12 +5347,12 @@ var GitWorktreeManagerImpl = class {
 			try {
 				await removeWorktree(worktreePath, this._projectRoot);
 				worktreeRemoved = true;
-				logger$6.debug({
+				logger$8.debug({
 					taskId,
 					worktreePath
 				}, "cleanupAllWorktrees: removed orphaned worktree");
 			} catch (err) {
-				logger$6.warn({
+				logger$8.warn({
 					taskId,
 					worktreePath,
 					err
@@ -5289,12 +5362,12 @@ var GitWorktreeManagerImpl = class {
 			let branchRemoved = false;
 			try {
 				branchRemoved = await removeBranch(branchName, this._projectRoot);
-				if (branchRemoved) logger$6.debug({
+				if (branchRemoved) logger$8.debug({
 					taskId,
 					branchName
 				}, "cleanupAllWorktrees: removed orphaned branch");
 			} catch (err) {
-				logger$6.warn({
+				logger$8.warn({
 					taskId,
 					branchName,
 					err
@@ -5302,14 +5375,14 @@ var GitWorktreeManagerImpl = class {
 			}
 			if (worktreeRemoved) cleaned++;
 		}
-		if (cleaned > 0) logger$6.info({ cleaned }, "cleanupAllWorktrees: recovered orphaned worktrees");
+		if (cleaned > 0) logger$8.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$6.debug({
+		logger$8.debug({
 			taskId,
 			branchName,
 			targetBranch
@@ -5337,7 +5410,7 @@ var GitWorktreeManagerImpl = class {
 			branch: branchName,
 			conflictingFiles: report.conflictingFiles
 		});
-		logger$6.info({
+		logger$8.info({
 			taskId,
 			hasConflicts: report.hasConflicts,
 			conflictCount: conflictingFiles.length
@@ -5347,14 +5420,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$6.debug({
+		logger$8.debug({
 			taskId,
 			branchName,
 			targetBranch
 		}, "mergeWorktree");
 		const conflictReport = await this.detectConflicts(taskId, targetBranch);
 		if (conflictReport.hasConflicts) {
-			logger$6.info({
+			logger$8.info({
 				taskId,
 				conflictCount: conflictReport.conflictingFiles.length
 			}, "Merge skipped due to conflicts");
@@ -5376,7 +5449,7 @@ var GitWorktreeManagerImpl = class {
 			success: true,
 			mergedFiles
 		};
-		logger$6.info({
+		logger$8.info({
 			taskId,
 			branchName,
 			mergedFileCount: mergedFiles.length
@@ -5384,7 +5457,7 @@ var GitWorktreeManagerImpl = class {
 		return result;
 	}
 	async listWorktrees() {
-		logger$6.debug({
+		logger$8.debug({
 			projectRoot: this._projectRoot,
 			baseDirectory: this._baseDirectory
 		}, "listWorktrees");
@@ -5408,7 +5481,7 @@ var GitWorktreeManagerImpl = class {
 				createdAt
 			});
 		}
-		logger$6.debug({ count: results.length }, "listWorktrees: found worktrees");
+		logger$8.debug({ count: results.length }, "listWorktrees: found worktrees");
 		return results;
 	}
 	getWorktreePath(taskId) {
@@ -5428,7 +5501,7 @@ function createGitWorktreeManager(options) {
 
 //#endregion
 //#region src/cli/commands/merge.ts
-const logger$5 = createLogger("merge-cmd");
+const logger$7 = createLogger("merge-cmd");
 const MERGE_EXIT_SUCCESS = 0;
 const MERGE_EXIT_CONFLICT = 1;
 const MERGE_EXIT_ERROR = 2;
@@ -5466,7 +5539,7 @@ async function mergeTask(taskId, targetBranch, projectRoot) {
 		projectRoot
 	});
 	try {
-		logger$5.info({
+		logger$7.info({
 			taskId,
 			targetBranch
 		}, "Running conflict detection...");
@@ -5488,7 +5561,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$5.error({
+		logger$7.error({
 			taskId,
 			err
 		}, "merge --task failed");
@@ -5542,7 +5615,7 @@ async function mergeAll(targetBranch, projectRoot, taskIds) {
 			error: message
 		});
 		console.log(`  Error for task "${taskId}": ${message}`);
-		logger$5.error({
+		logger$7.error({
 			taskId,
 			err
 		}, "merge --all: task failed");
@@ -5595,7 +5668,7 @@ function registerMergeCommand(program, projectRoot = process.cwd()) {
 
 //#endregion
 //#region src/cli/commands/worktrees.ts
-const logger$4 = createLogger("worktrees-cmd");
+const logger$6 = createLogger("worktrees-cmd");
 const WORKTREES_EXIT_SUCCESS = 0;
 const WORKTREES_EXIT_ERROR = 1;
 /** Valid task statuses for filtering */
@@ -5722,7 +5795,7 @@ async function listWorktreesAction(options) {
 		try {
 			worktreeInfos = await manager.listWorktrees();
 		} catch (err) {
-			logger$4.error({ err }, "Failed to list worktrees");
+			logger$6.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;
@@ -5749,7 +5822,7 @@ async function listWorktreesAction(options) {
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		process.stderr.write(`Error: ${message}\n`);
-		logger$4.error({ err }, "listWorktreesAction failed");
+		logger$6.error({ err }, "listWorktreesAction failed");
 		return WORKTREES_EXIT_ERROR;
 	}
 }
@@ -5790,7 +5863,7 @@ function registerWorktreesCommand(program, version = "0.0.0", projectRoot = proc
 
 //#endregion
 //#region src/cli/commands/brainstorm.ts
-const logger$3 = createLogger("brainstorm-cmd");
+const logger$5 = createLogger("brainstorm-cmd");
 /**
 * Detect whether the project has existing planning artifacts that indicate
 * this is an amendment session (vs. a brand-new project brainstorm).
@@ -5836,13 +5909,13 @@ async function loadAmendmentContextDocuments(projectRoot) {
 	try {
 		brief = await readFile(briefPath, "utf-8");
 	} catch {
-		logger$3.warn({ briefPath }, "product-brief.md not found — continuing without brief context");
+		logger$5.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$3.warn({ prdPath }, "requirements.md not found — continuing without PRD context");
+		logger$5.warn({ prdPath }, "requirements.md not found — continuing without PRD context");
 		process.stderr.write(`Warning: requirements.md not found at ${prdPath}\n`);
 	}
 	return {
@@ -6051,7 +6124,7 @@ async function dispatchToPersonas(userPrompt, context, llmDispatch) {
 		}
 	];
 	const defaultDispatch = async (prompt, personaName) => {
-		logger$3.debug({
+		logger$5.debug({
 			personaName,
 			promptLength: prompt.length
 		}, "Dispatching to persona (stub mode)");
@@ -6068,7 +6141,7 @@ async function dispatchToPersonas(userPrompt, context, llmDispatch) {
 			};
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
-			logger$3.error({
+			logger$5.error({
 				err,
 				personaName: persona.name
 			}, "Persona dispatch failed");
@@ -6220,7 +6293,7 @@ async function runBrainstormSession(options, llmDispatch, rlInterface) {
 			}
 		});
 		rl.on("error", (err) => {
-			logger$3.error({ err }, "readline error");
+			logger$5.error({ err }, "readline error");
 			if (!sessionEnded) endSession(false);
 		});
 	});
@@ -6810,7 +6883,7 @@ function renderReadinessReport(decisions) {
 
 //#endregion
 //#region src/cli/commands/export.ts
-const logger$2 = createLogger("export-cmd");
+const logger$4 = createLogger("export-cmd");
 /**
 * Execute the export action.
 * Returns an exit code (0 = success, 1 = error).
@@ -6937,7 +7010,7 @@ async function runExportAction(options) {
 		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$2.error({ err }, "export action failed");
+		logger$4.error({ err }, "export action failed");
 		return 1;
 	} finally {
 		if (dbWrapper !== void 0) try {
@@ -7024,7 +7097,7 @@ function getRetryableEscalations(db, runId) {
 
 //#endregion
 //#region src/cli/commands/retry-escalated.ts
-const logger$1 = createLogger("retry-escalated-cmd");
+const logger$3 = createLogger("retry-escalated-cmd");
 async function runRetryEscalatedAction(options) {
 	const { runId, dryRun, outputFormat, projectRoot, concurrency, pack: packName, registry: injectedRegistry } = options;
 	const dbRoot = await resolveMainRepoRoot(projectRoot);
@@ -7122,7 +7195,7 @@ async function runRetryEscalatedAction(options) {
 					});
 				}
 			} catch (err) {
-				logger$1.warn({ err }, "Failed to record token usage");
+				logger$3.warn({ err }, "Failed to record token usage");
 			}
 		});
 		if (outputFormat === "human") {
@@ -7144,7 +7217,7 @@ async function runRetryEscalatedAction(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$1.error({ err }, "retry-escalated failed");
+		logger$3.error({ err }, "retry-escalated failed");
 		return 1;
 	} finally {
 		try {
@@ -7423,6 +7496,170 @@ function registerHistoryCommand(program) {
 	});
 }
 
+//#endregion
+//#region src/cli/commands/repo-map.ts
+const logger$2 = createLogger("cli:repo-map");
+/** Validate that a symbol name contains only safe identifier characters. */
+function isValidSymbolName(name) {
+	return /^[a-zA-Z0-9_]+$/.test(name);
+}
+function registerRepoMapCommand(program) {
+	program.command("repo-map").description("Show, update, or query the repo-map symbol index").option("--show", "Show repo-map staleness status").option("--update", "Trigger an incremental repo-map update (Dolt backend only)").option("--query <symbol>", "Query the repo-map for a specific symbol name").option("--dry-run <storyFile>", "Preview repo-map context that would be injected for a story file").option("--output-format <format>", "Output format: text or json", "text").action(async (options) => {
+		if (options.query !== void 0 && !isValidSymbolName(options.query)) {
+			process.stderr.write(`Error: --query value must match /^[a-zA-Z0-9_]+$/ (got: ${options.query})\n`);
+			process.exitCode = 1;
+			return;
+		}
+		const dbRoot = await resolveMainRepoRoot(process.cwd());
+		const statePath = join$1(dbRoot, ".substrate", "state");
+		const doltStatePath = join$1(statePath, ".dolt");
+		const isDolt = existsSync$1(doltStatePath);
+		const notDoltError = (flag) => {
+			if (options.outputFormat === "json") console.log(JSON.stringify({
+				backend: "file",
+				status: "unavailable",
+				hint: "Repo-map requires the Dolt backend. Run `substrate init --dolt` to enable."
+			}));
+			else process.stderr.write(`Error: ${flag} requires the Dolt backend. Run \`substrate init --dolt\` to enable.\n`);
+			process.exitCode = 1;
+		};
+		if (!isDolt) {
+			const flag = options.update ? "--update" : options.query ? "--query" : options.dryRun ? "--dry-run" : "--show";
+			notDoltError(flag);
+			return;
+		}
+		const doltClient = new DoltClient({ repoPath: statePath });
+		const symbolRepo = new DoltSymbolRepository(doltClient, logger$2);
+		const metaRepo = new DoltRepoMapMetaRepository(doltClient);
+		const repoMapModule = new RepoMapModule(metaRepo, logger$2);
+		const queryEngine = new RepoMapQueryEngine(symbolRepo, logger$2);
+		if (options.show === true || !options.update && !options.query && !options.dryRun) {
+			const meta = await metaRepo.getMeta();
+			const staleResult = await repoMapModule.checkStaleness();
+			let staleness = "unknown";
+			if (meta === null) staleness = "unknown";
+			else if (staleResult !== null) staleness = "stale";
+			else staleness = "current";
+			const symbolCount = meta !== null ? (await symbolRepo.getSymbols()).length : 0;
+			if (options.outputFormat === "json") console.log(JSON.stringify({
+				symbolCount,
+				commitSha: meta?.commitSha ?? null,
+				fileCount: meta?.fileCount ?? 0,
+				updatedAt: meta?.updatedAt?.toISOString() ?? null,
+				staleness
+			}));
+			else if (meta !== null) {
+				console.log(`Repo-map: ${symbolCount} symbols, ${meta.fileCount} files`);
+				console.log(`Commit: ${meta.commitSha}`);
+				console.log(`Updated: ${meta.updatedAt.toISOString()}`);
+				if (staleness === "stale") console.log("Status: STALE (run `substrate repo-map --update` to refresh)");
+				else console.log("Status: UP TO DATE");
+			} else console.log("Repo-map: no data stored yet");
+			return;
+		}
+		if (options.update === true) {
+			logger$2.info("repo-map --update: triggering incremental update");
+			const gitClient = new GitClient(logger$2);
+			const grammarLoader = new GrammarLoader(logger$2);
+			const parser = new SymbolParser(grammarLoader, logger$2);
+			const storage = new RepoMapStorage(symbolRepo, metaRepo, gitClient, logger$2);
+			await storage.incrementalUpdate(dbRoot, parser);
+			const meta = await metaRepo.getMeta();
+			const symbolCount = (await symbolRepo.getSymbols()).length;
+			if (options.outputFormat === "json") console.log(JSON.stringify({
+				result: "updated",
+				symbolCount,
+				fileCount: meta?.fileCount ?? 0,
+				commitSha: meta?.commitSha ?? null,
+				updatedAt: meta?.updatedAt?.toISOString() ?? null
+			}));
+			else console.log(`Repo-map updated: ${symbolCount} symbols across ${meta?.fileCount ?? 0} files`);
+			return;
+		}
+		if (options.query !== void 0) {
+			logger$2.debug({ symbol: options.query }, "repo-map --query");
+			const result = await queryEngine.query({
+				symbols: [options.query],
+				maxTokens: 4e3
+			});
+			if (options.outputFormat === "json") console.log(JSON.stringify(result, null, 2));
+			else if (result.symbolCount === 0) console.log(`No symbols found matching '${options.query}'.`);
+			else {
+				console.log(`Found ${result.symbolCount} symbol(s) for '${options.query}':`);
+				for (const sym of result.symbols) console.log(`  ${sym.filePath}:${sym.lineNumber}  ${sym.symbolType} ${sym.symbolName}`);
+			}
+			return;
+		}
+		if (options.dryRun !== void 0) {
+			let storyContent;
+			try {
+				storyContent = await readFile$1(options.dryRun, "utf-8");
+			} catch {
+				process.stderr.write(`Error: Cannot read story file: ${options.dryRun}\n`);
+				process.exitCode = 1;
+				return;
+			}
+			const injector = new RepoMapInjector(queryEngine, logger$2);
+			const injectionResult = await injector.buildContext(storyContent, 2e3);
+			console.log(JSON.stringify({
+				text: injectionResult.text,
+				symbolCount: injectionResult.symbolCount,
+				truncated: injectionResult.truncated
+			}));
+			return;
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/commands/routing.ts
+const logger$1 = createLogger("cli:routing");
+function registerRoutingCommand(program) {
+	program.command("routing").description("Show routing configuration and auto-tune history").option("--history", "Show the routing auto-tune log (model changes applied)").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();
+			if (options.history === true) {
+				logger$1.debug("routing --history: fetching tune log");
+				const raw$1 = await store.getMetric("global", "routing_tune_log");
+				let entries = [];
+				if (Array.isArray(raw$1)) entries = raw$1.sort((a, b) => b.appliedAt.localeCompare(a.appliedAt));
+				if (options.outputFormat === "json") {
+					console.log(JSON.stringify({ entries }, null, 2));
+					return;
+				}
+				if (entries.length === 0) {
+					console.log("No routing auto-tune history found.");
+					return;
+				}
+				console.log("Routing auto-tune history:");
+				for (const entry of entries) console.log(`  ${entry.appliedAt}  phase=${entry.phase}  ${entry.oldModel} → ${entry.newModel}  savings=${entry.estimatedSavingsPct.toFixed(1)}%  run=${entry.runId}`);
+				return;
+			}
+			const raw = await store.getMetric("global", "routing_tune_log");
+			const entryCount = Array.isArray(raw) ? raw.length : 0;
+			if (options.outputFormat === "json") console.log(JSON.stringify({ tuneLogEntries: entryCount }));
+			else {
+				console.log(`Routing auto-tune log: ${entryCount} entr${entryCount === 1 ? "y" : "ies"}`);
+				if (entryCount === 0) console.log("No auto-tune changes applied yet. Use --history for details.");
+				else console.log("Run `substrate routing --history` to see full history.");
+			}
+		} finally {
+			await store.close();
+		}
+	});
+}
+
 //#endregion
 //#region src/cli/index.ts
 process.setMaxListeners(20);
@@ -7475,6 +7712,8 @@ async function createProgram() {
 	registerDiffCommand(program);
 	registerHistoryCommand(program);
 	registerMigrateCommand(program);
+	registerRepoMapCommand(program);
+	registerRoutingCommand(program);
 	registerCostCommand(program, version);
 	registerMonitorCommand(program, version);
 	registerMergeCommand(program);
@@ -7487,8 +7726,8 @@ async function createProgram() {
 /** Fire-and-forget startup version check (story 8.3, AC3/AC5) */
 function checkForUpdatesInBackground(currentVersion) {
 	if (process.env.SUBSTRATE_NO_UPDATE_CHECK === "1") return;
-	import("../upgrade-BlJKjr6I.js").then(async () => {
-		const { createVersionManager } = await import("../version-manager-impl-BsHqAeGT.js");
+	import("../upgrade-njy4XENS.js").then(async () => {
+		const { createVersionManager } = await import("../version-manager-impl-QwroczYS.js");
 		const vm = createVersionManager();
 		const result = await vm.checkForUpdates();
 		if (result.updateAvailable) {