substrate-ai 0.2.30 → 0.2.31

package/dist/cli/index.js

@@ -1,11 +1,11 @@
 #!/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, runAnalysisPhase, runMigrations, runPlanningPhase, runSolutioningPhase, validateStopAfterFromConflict } from "../run-Ajt187oE.js";
+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, runAnalysisPhase, runMigrations, runPlanningPhase, runSolutioningPhase, validateStopAfterFromConflict } from "../run-BxXwD2xY.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";
 import { ConfigError, createEventBus } from "../helpers-RL22dYtn.js";
 import { addTokenUsage, createDecision, createPipelineRun, getDecisionsByCategory, getDecisionsByPhaseForRun, getLatestRun, getTokenUsageSummary, listRequirements, updatePipelineRun } from "../decisions-Dq4cAA2L.js";
-import { ESCALATION_DIAGNOSIS, EXPERIMENT_RESULT, OPERATIONAL_FINDING, STORY_METRICS, aggregateTokenUsageForRun, compareRunMetrics, getBaselineRunMetrics, getRunMetrics, getStoryMetricsForRun, incrementRunRestarts, listRunMetrics, tagRunAsBaseline } from "../operational-CnMlvWqc.js";
+import { ESCALATION_DIAGNOSIS, EXPERIMENT_RESULT, OPERATIONAL_FINDING, STORY_METRICS, aggregateTokenUsageForRun, compareRunMetrics, getBaselineRunMetrics, getRunMetrics, getStoryMetricsForRun, incrementRunRestarts, listRunMetrics, tagRunAsBaseline } from "../operational-Bovj4fS-.js";
 import { abortMerge, createWorktree, getConflictingFiles, getMergedFiles, getOrphanedWorktrees, performMerge, removeBranch, removeWorktree, simulateMerge, verifyGitVersion } from "../git-utils-CtmrZrHS.js";
 import "../version-manager-impl-CizNmmLT.js";
 import { registerUpgradeCommand } from "../upgrade-Cvwtnwl4.js";
@@ -2571,7 +2571,7 @@ async function runSupervisorAction(options, deps = {}) {
 						try {
 							const { createExperimenter } = await import(
 								/* @vite-ignore */
-								"../experimenter-f_Y1rreV.js"
+								"../experimenter-Br1-vzYv.js"
 );
 							const { getLatestRun: getLatest } = await import(
 								/* @vite-ignore */
@@ -2585,7 +2585,7 @@ async function runSupervisorAction(options, deps = {}) {
 								const expDb = expDbWrapper.db;
 								const { runRunAction: runPipeline } = await import(
 									/* @vite-ignore */
-									"../run-KBcR3Jpi.js"
+									"../run-CMagiY2Y.js"
 );
 								const runStoryFn = async (opts) => {
 									const exitCode = await runPipeline({

package/dist/{experimenter-f_Y1rreV.js → experimenter-Br1-vzYv.js}

@@ -1,6 +1,6 @@
 import "./logger-D2fS2ccL.js";
 import { createDecision } from "./decisions-Dq4cAA2L.js";
-import { EXPERIMENT_RESULT, getRunMetrics, getStoryMetricsForRun } from "./operational-CnMlvWqc.js";
+import { EXPERIMENT_RESULT, getRunMetrics, getStoryMetricsForRun } from "./operational-Bovj4fS-.js";
 import { spawnGit } from "./git-utils-CtmrZrHS.js";
 import { spawn } from "node:child_process";
 import { join } from "node:path";
@@ -500,4 +500,4 @@ function createExperimenter(config, deps) {
 
 //#endregion
 export { createExperimenter };
-//# sourceMappingURL=experimenter-f_Y1rreV.js.map
+//# sourceMappingURL=experimenter-Br1-vzYv.js.map

package/dist/index.d.ts

@@ -185,6 +185,19 @@ interface StoryZeroDiffEscalationEvent {
   /** Always "zero-diff-on-complete" */
   reason: string;
 }
+/**
+ * Emitted when the pre-flight build check fails before any story is dispatched (Story 25-2).
+ * Pipeline aborts immediately — no stories are processed.
+ */
+interface PipelinePreFlightFailureEvent {
+  type: 'pipeline:pre-flight-failure';
+  /** ISO-8601 timestamp generated at emit time */
+  ts: string;
+  /** Exit code from the build command (-1 for timeout) */
+  exitCode: number;
+  /** Combined stdout+stderr output, truncated to 2000 chars */
+  output: string;
+}
 /**
  * Emitted when the build verification command exits with a non-zero code
  * or times out, before code-review is dispatched (Story 24-2).
@@ -501,6 +514,26 @@ interface SupervisorExperimentErrorEvent {
   /** Error message describing why the experiment failed */
   error: string;
 }
+/**
+ * Emitted when post-sprint contract verification finds a mismatch between
+ * declared export/import contracts (Story 25-6).
+ *
+ * Failures are warnings only — stories already completed. The user should
+ * inspect the mismatch and fix manually.
+ */
+interface PipelineContractMismatchEvent {
+  type: 'pipeline:contract-mismatch';
+  /** ISO-8601 timestamp generated at emit time */
+  ts: string;
+  /** Story key that declared the export for this contract */
+  exporter: string;
+  /** Story key that declared the import for this contract (null if no importer found) */
+  importer: string | null;
+  /** TypeScript interface or Zod schema name (e.g., "JudgeResult") */
+  contractName: string;
+  /** Human-readable description of the mismatch (e.g., missing file, type error) */
+  mismatchDescription: string;
+}
 /**
  * Discriminated union of all pipeline event types.
  *
@@ -513,7 +546,7 @@ interface SupervisorExperimentErrorEvent {
  * }
  * ```
  */
-type PipelineEvent = PipelineStartEvent | PipelineCompleteEvent | StoryPhaseEvent | StoryDoneEvent | StoryEscalationEvent | StoryWarnEvent | StoryLogEvent | PipelineHeartbeatEvent | StoryStallEvent | StoryZeroDiffEscalationEvent | StoryBuildVerificationFailedEvent | StoryBuildVerificationPassedEvent | StoryInterfaceChangeWarningEvent | StoryMetricsEvent | SupervisorPollEvent | SupervisorKillEvent | SupervisorRestartEvent | SupervisorAbortEvent | SupervisorSummaryEvent | SupervisorAnalysisCompleteEvent | SupervisorAnalysisErrorEvent | SupervisorExperimentStartEvent | SupervisorExperimentSkipEvent | SupervisorExperimentRecommendationsEvent | SupervisorExperimentCompleteEvent | SupervisorExperimentErrorEvent; //#endregion
+type PipelineEvent = PipelineStartEvent | PipelineCompleteEvent | PipelinePreFlightFailureEvent | PipelineContractMismatchEvent | StoryPhaseEvent | StoryDoneEvent | StoryEscalationEvent | StoryWarnEvent | StoryLogEvent | PipelineHeartbeatEvent | StoryStallEvent | StoryZeroDiffEscalationEvent | StoryBuildVerificationFailedEvent | StoryBuildVerificationPassedEvent | StoryInterfaceChangeWarningEvent | StoryMetricsEvent | SupervisorPollEvent | SupervisorKillEvent | SupervisorRestartEvent | SupervisorAbortEvent | SupervisorSummaryEvent | SupervisorAnalysisCompleteEvent | SupervisorAnalysisErrorEvent | SupervisorExperimentStartEvent | SupervisorExperimentSkipEvent | SupervisorExperimentRecommendationsEvent | SupervisorExperimentCompleteEvent | SupervisorExperimentErrorEvent; //#endregion
 //#region src/core/errors.d.ts
 
 /**
@@ -1160,6 +1193,23 @@ interface OrchestratorEvents {
       affected_items: string[];
     }>;
   };
+  /** Pre-flight build check failed before any stories were dispatched */
+  'pipeline:pre-flight-failure': {
+    exitCode: number;
+    /** Build output (stdout+stderr), truncated to 2000 chars */
+    output: string;
+  };
+  /** Contract verification found a mismatch between declared export/import contracts */
+  'pipeline:contract-mismatch': {
+    /** Story key that declared the export for this contract */
+    exporter: string;
+    /** Story key that declared the import for this contract (null if no importer found) */
+    importer: string | null;
+    /** TypeScript interface or Zod schema name (e.g., "JudgeResult") */
+    contractName: string;
+    /** Human-readable description of the mismatch */
+    mismatchDescription: string;
+  };
   /** Build verification command failed with non-zero exit or timeout */
   'story:build-verification-failed': {
     storyKey: string;

package/dist/{operational-CnMlvWqc.js → operational-Bovj4fS-.js}

@@ -339,7 +339,21 @@ const TEST_EXPANSION_FINDING = "test-expansion-finding";
 * ```
 */
 const TEST_PLAN = "test-plan";
+/**
+* Category for advisory notes persisted when a code review returns LGTM_WITH_NOTES.
+*
+* Key schema: "{storyKey}:{runId}"
+*
+* Value shape:
+* ```json
+* {
+*   "storyKey": "25-3",
+*   "notes": "Consider extracting the helper into a shared module for reuse."
+* }
+* ```
+*/
+const ADVISORY_NOTES = "advisory-notes";
 
 //#endregion
-export { ESCALATION_DIAGNOSIS, EXPERIMENT_RESULT, OPERATIONAL_FINDING, STORY_METRICS, STORY_OUTCOME, TEST_EXPANSION_FINDING, TEST_PLAN, aggregateTokenUsageForRun, aggregateTokenUsageForStory, compareRunMetrics, getBaselineRunMetrics, getRunMetrics, getStoryMetricsForRun, incrementRunRestarts, listRunMetrics, tagRunAsBaseline, writeRunMetrics, writeStoryMetrics };
-//# sourceMappingURL=operational-CnMlvWqc.js.map
+export { ADVISORY_NOTES, ESCALATION_DIAGNOSIS, EXPERIMENT_RESULT, OPERATIONAL_FINDING, STORY_METRICS, STORY_OUTCOME, TEST_EXPANSION_FINDING, TEST_PLAN, aggregateTokenUsageForRun, aggregateTokenUsageForStory, compareRunMetrics, getBaselineRunMetrics, getRunMetrics, getStoryMetricsForRun, incrementRunRestarts, listRunMetrics, tagRunAsBaseline, writeRunMetrics, writeStoryMetrics };
+//# sourceMappingURL=operational-Bovj4fS-.js.map

package/dist/{run-Ajt187oE.js → run-BxXwD2xY.js}

@@ -2,7 +2,7 @@ import { createLogger, deepMask } from "./logger-D2fS2ccL.js";
 import { CURRENT_CONFIG_FORMAT_VERSION, PartialSubstrateConfigSchema, SUPPORTED_CONFIG_FORMAT_VERSIONS, SubstrateConfigSchema, defaultConfigMigrator } from "./config-migrator-DSi8KhQC.js";
 import { ConfigError, ConfigIncompatibleFormatError, createEventBus, createTuiApp, isTuiCapable, printNonTtyWarning, sleep } from "./helpers-RL22dYtn.js";
 import { addTokenUsage, createDecision, createPipelineRun, createRequirement, getArtifactByTypeForRun, getArtifactsByRun, getDecisionsByCategory, getDecisionsByPhase, getDecisionsByPhaseForRun, getLatestRun, getPipelineRunById, getRunningPipelineRuns, getTokenUsageSummary, registerArtifact, updatePipelineRun, updatePipelineRunConfig, upsertDecision } from "./decisions-Dq4cAA2L.js";
-import { ESCALATION_DIAGNOSIS, OPERATIONAL_FINDING, STORY_METRICS, STORY_OUTCOME, TEST_EXPANSION_FINDING, TEST_PLAN, aggregateTokenUsageForRun, aggregateTokenUsageForStory, getStoryMetricsForRun, writeRunMetrics, writeStoryMetrics } from "./operational-CnMlvWqc.js";
+import { ADVISORY_NOTES, ESCALATION_DIAGNOSIS, OPERATIONAL_FINDING, STORY_METRICS, STORY_OUTCOME, TEST_EXPANSION_FINDING, TEST_PLAN, aggregateTokenUsageForRun, aggregateTokenUsageForStory, getStoryMetricsForRun, writeRunMetrics, writeStoryMetrics } from "./operational-Bovj4fS-.js";
 import { createRequire } from "module";
 import { dirname, join, resolve } from "path";
 import { access, mkdir, readFile, readdir, stat, writeFile } from "fs/promises";
@@ -2521,6 +2521,28 @@ const PIPELINE_EVENT_METADATA = [
 			}
 		]
 	},
+	{
+		type: "pipeline:pre-flight-failure",
+		description: "Pre-flight build check failed before any story was dispatched. Pipeline aborts immediately.",
+		when: "When the build command exits with a non-zero code before the first story dispatch.",
+		fields: [
+			{
+				name: "ts",
+				type: "string",
+				description: "Timestamp."
+			},
+			{
+				name: "exitCode",
+				type: "number",
+				description: "Exit code from the build command (-1 for timeout)."
+			},
+			{
+				name: "output",
+				type: "string",
+				description: "Combined stdout+stderr from the build command (truncated to 2000 chars)."
+			}
+		]
+	},
 	{
 		type: "story:zero-diff-escalation",
 		description: "Dev-story reported COMPLETE but git diff shows no file changes (phantom completion).",
@@ -2652,6 +2674,38 @@ const PIPELINE_EVENT_METADATA = [
 				description: "Dispatch count."
 			}
 		]
+	},
+	{
+		type: "pipeline:contract-mismatch",
+		description: "Post-sprint contract mismatch found. Non-blocking — stories done. Manual fix required.",
+		when: "After all stories complete, before pipeline:complete. When contract declarations exist and mismatch found.",
+		fields: [
+			{
+				name: "ts",
+				type: "string",
+				description: "Timestamp."
+			},
+			{
+				name: "exporter",
+				type: "string",
+				description: "Exporting story key."
+			},
+			{
+				name: "importer",
+				type: "string|null",
+				description: "Importing story key (null if none)."
+			},
+			{
+				name: "contractName",
+				type: "string",
+				description: "Contract name (e.g., \"JudgeResult\")."
+			},
+			{
+				name: "mismatchDescription",
+				type: "string",
+				description: "Mismatch details (missing file, type error)."
+			}
+		]
 	}
 ];
 /**
@@ -4347,6 +4401,9 @@ const AcChecklistEntrySchema = z.object({
 *  - Any blocker → NEEDS_MAJOR_REWORK (security, data loss, architectural breakage)
 *  - Any major or minor issues → NEEDS_MINOR_FIXES (fixable by sonnet with guidance)
 *  - No issues → SHIP_IT
+*
+* Note: LGTM_WITH_NOTES is handled in the transform (not here) because it
+* requires knowledge of the agent's original verdict.
 */
 function computeVerdict(issueList) {
 	const hasBlocker = issueList.some((i) => i.severity === "blocker");
@@ -4386,7 +4443,8 @@ const CodeReviewResultSchema = z.object({
 	verdict: z.enum([
 		"SHIP_IT",
 		"NEEDS_MINOR_FIXES",
-		"NEEDS_MAJOR_REWORK"
+		"NEEDS_MAJOR_REWORK",
+		"LGTM_WITH_NOTES"
 	]),
 	issues: coerceNumber,
 	issue_list: z.array(CodeReviewIssueSchema),
@@ -4403,12 +4461,14 @@ const CodeReviewResultSchema = z.object({
 			file: ""
 		});
 	}
+	const computedVerdict = computeVerdict(augmentedIssueList);
+	const finalVerdict = data.verdict === "LGTM_WITH_NOTES" && computedVerdict === "SHIP_IT" ? "LGTM_WITH_NOTES" : computedVerdict;
 	return {
 		...data,
 		issue_list: augmentedIssueList,
 		issues: augmentedIssueList.length,
 		agentVerdict: data.verdict,
-		verdict: computeVerdict(augmentedIssueList)
+		verdict: finalVerdict
 	};
 });
 /**
@@ -4576,7 +4636,7 @@ async function runCreateStory(deps, params) {
 	const implementationDecisions = getImplementationDecisions(deps);
 	const epicShardContent = getEpicShard(implementationDecisions, epicId, deps.projectRoot, storyKey);
 	const prevDevNotesContent = getPrevDevNotes(implementationDecisions, epicId);
-	const archConstraintsContent = getArchConstraints$2(deps);
+	const archConstraintsContent = getArchConstraints$3(deps);
 	const storyTemplateContent = await getStoryTemplate(deps);
 	const { prompt, tokenCount, truncated } = assemblePrompt(template, [
 		{
@@ -4823,7 +4883,7 @@ function getPrevDevNotes(decisions, epicId) {
 * Looks for decisions with phase='solutioning', category='architecture'.
 * Falls back to reading _bmad-output/architecture/architecture.md on disk if decisions are empty.
 */
-function getArchConstraints$2(deps) {
+function getArchConstraints$3(deps) {
 	try {
 		const decisions = getDecisionsByPhase(deps.db, "solutioning");
 		const constraints = decisions.filter((d) => d.category === "architecture");
@@ -5100,7 +5160,8 @@ function getProjectFindings(db) {
 		const operational = getDecisionsByCategory(db, OPERATIONAL_FINDING);
 		const metrics = getDecisionsByCategory(db, STORY_METRICS);
 		const diagnoses = getDecisionsByCategory(db, ESCALATION_DIAGNOSIS);
-		if (outcomes.length === 0 && operational.length === 0 && metrics.length === 0 && diagnoses.length === 0) return "";
+		const advisoryNotes = getDecisionsByCategory(db, ADVISORY_NOTES);
+		if (outcomes.length === 0 && operational.length === 0 && metrics.length === 0 && diagnoses.length === 0 && advisoryNotes.length === 0) return "";
 		const sections = [];
 		if (outcomes.length > 0) {
 			const patterns = extractRecurringPatterns(outcomes);
@@ -5135,6 +5196,16 @@ function getProjectFindings(db) {
 		}
 		const stalls = operational.filter((o) => o.key.startsWith("stall:"));
 		if (stalls.length > 0) sections.push(`**Prior stalls:** ${stalls.length} stall event(s) recorded`);
+		if (advisoryNotes.length > 0) {
+			sections.push("**Advisory notes from prior reviews (LGTM_WITH_NOTES):**");
+			for (const n of advisoryNotes.slice(-3)) try {
+				const val = JSON.parse(n.value);
+				const storyId = n.key.split(":")[0];
+				if (typeof val.notes === "string" && val.notes.length > 0) sections.push(`- ${storyId}: ${val.notes}`);
+			} catch {
+				sections.push(`- ${n.key}: advisory notes available`);
+			}
+		}
 		if (sections.length === 0) return "";
 		let summary = sections.join("\n");
 		if (summary.length > MAX_CHARS) summary = summary.slice(0, MAX_CHARS - 3) + "...";
@@ -5785,7 +5856,7 @@ async function runCodeReview(deps, params) {
 			output: 0
 		});
 	}
-	const archConstraintsContent = getArchConstraints$1(deps);
+	const archConstraintsContent = getArchConstraints$2(deps);
 	const templateTokens = countTokens(template);
 	const storyTokens = countTokens(storyContent);
 	const constraintTokens = countTokens(archConstraintsContent);
@@ -5994,7 +6065,7 @@ async function runCodeReview(deps, params) {
 * Retrieve architecture constraints from the decision store.
 * Looks for decisions with phase='solutioning', category='architecture'.
 */
-function getArchConstraints$1(deps) {
+function getArchConstraints$2(deps) {
 	try {
 		const decisions = getDecisionsByPhase(deps.db, "solutioning");
 		const constraints = decisions.filter((d) => d.category === "architecture");
@@ -6061,10 +6132,15 @@ async function runTestPlan(deps, params) {
 		}, "Failed to read story file for test planning");
 		return makeTestPlanFailureResult(`story_file_read_error: ${error}`);
 	}
+	const archConstraintsContent = getArchConstraints$1(deps);
 	const { prompt, tokenCount, truncated } = assemblePrompt(template, [{
 		name: "story_content",
 		content: storyContent,
 		priority: "required"
+	}, {
+		name: "architecture_constraints",
+		content: archConstraintsContent,
+		priority: "optional"
 	}], TOKEN_CEILING);
 	logger$10.info({
 		storyKey,
@@ -6181,6 +6257,22 @@ function makeTestPlanFailureResult(error) {
 		}
 	};
 }
+/**
+* Retrieve architecture constraints from the decision store.
+* Looks for decisions with phase='solutioning', category='architecture'.
+* Returns empty string if none found or on error (graceful degradation).
+*/
+function getArchConstraints$1(deps) {
+	try {
+		const decisions = getDecisionsByPhase(deps.db, "solutioning");
+		const constraints = decisions.filter((d) => d.category === "architecture");
+		if (constraints.length === 0) return "";
+		return constraints.map((d) => `${d.key}: ${d.value}`).join("\n");
+	} catch (err) {
+		logger$10.warn({ error: err instanceof Error ? err.message : String(err) }, "Failed to retrieve architecture constraints for test-plan — proceeding without them");
+		return "";
+	}
+}
 
 //#endregion
 //#region src/modules/compiled-workflows/test-expansion.ts
@@ -6695,6 +6787,125 @@ function detectConflictGroups(storyKeys, config) {
 	}
 	return Array.from(moduleToStories.values());
 }
+/**
+* Build a contract dependency graph from a list of contract declarations.
+*
+* Rules:
+*   1. If story A exports contract "FooSchema" and story B imports "FooSchema",
+*      add a directed edge A→B (A must dispatch before B).
+*   2. If story A and story B both export the same contract (dual export),
+*      add a one-way edge between them (alphabetically sorted, to avoid cycles)
+*      so they are serialized and cannot produce conflicting definitions in parallel.
+*
+* @param declarations - Array of contract declarations from all stories
+* @returns List of directed dependency edges
+*/
+function buildContractDependencyGraph(declarations) {
+	const edges = [];
+	const exportsByName = new Map();
+	const importsByName = new Map();
+	for (const decl of declarations) if (decl.direction === "export") {
+		const arr = exportsByName.get(decl.contractName) ?? [];
+		arr.push(decl.storyKey);
+		exportsByName.set(decl.contractName, arr);
+	} else {
+		const arr = importsByName.get(decl.contractName) ?? [];
+		arr.push(decl.storyKey);
+		importsByName.set(decl.contractName, arr);
+	}
+	for (const [contractName, importerKeys] of importsByName) {
+		const exporterKeys = exportsByName.get(contractName) ?? [];
+		for (const from of exporterKeys) for (const to of importerKeys) {
+			if (from === to) continue;
+			edges.push({
+				from,
+				to,
+				contractName,
+				reason: `${from} exports ${contractName}, ${to} imports it`
+			});
+		}
+	}
+	for (const [contractName, exporterKeys] of exportsByName) {
+		if (exporterKeys.length < 2) continue;
+		const sorted = [...exporterKeys].sort();
+		for (let i = 0; i < sorted.length - 1; i++) edges.push({
+			from: sorted[i],
+			to: sorted[i + 1],
+			contractName,
+			reason: `dual export: ${sorted[i]} and ${sorted[i + 1]} both export ${contractName} — serialized to prevent conflicting definitions`
+		});
+	}
+	return edges;
+}
+/**
+* Detect conflict groups with contract-aware dispatch ordering.
+*
+* Combines file-based conflict grouping (via moduleMap) with semantic
+* contract dependency ordering (via ContractDeclaration[]).
+*
+* Ordering rules:
+*   - If story A exports a contract that story B imports, A's conflict group
+*     is placed in an earlier batch than B's conflict group.
+*   - If story A and story B both export the same contract (dual export),
+*     they are serialized into different batches.
+*   - Stories with no contract overlap keep their original grouping
+*     (no regression — all placed in the same single batch).
+*
+* Cycle detection: if contract edges form a cycle at the group level
+* (e.g., A→B and B→A), the affected groups are placed in a single
+* batch together (graceful degradation — serialization within the group
+* still applies via the file-conflict mechanism).
+*
+* @param storyKeys - Array of story key strings
+* @param config - Optional conflict detector configuration (moduleMap)
+* @param declarations - Array of contract declarations from all stories
+* @returns Ordered batches of conflict groups and the edges found
+*/
+function detectConflictGroupsWithContracts(storyKeys, config, declarations) {
+	const groups = detectConflictGroups(storyKeys, config);
+	const edges = buildContractDependencyGraph(declarations);
+	if (edges.length === 0) return {
+		batches: [groups],
+		edges: []
+	};
+	const storyToGroupIdx = new Map();
+	for (let i = 0; i < groups.length; i++) for (const key of groups[i]) storyToGroupIdx.set(key, i);
+	const successors = new Map();
+	const inDegree = new Array(groups.length).fill(0);
+	for (let i = 0; i < groups.length; i++) successors.set(i, new Set());
+	for (const edge of edges) {
+		const fromGroup = storyToGroupIdx.get(edge.from);
+		const toGroup = storyToGroupIdx.get(edge.to);
+		if (fromGroup === void 0 || toGroup === void 0) continue;
+		if (fromGroup === toGroup) continue;
+		if (!successors.get(fromGroup).has(toGroup)) {
+			successors.get(fromGroup).add(toGroup);
+			inDegree[toGroup]++;
+		}
+	}
+	const waves = [];
+	const processed = new Set();
+	while (processed.size < groups.length) {
+		const wave = [];
+		for (let i = 0; i < groups.length; i++) if (!processed.has(i) && inDegree[i] === 0) wave.push(i);
+		if (wave.length === 0) {
+			const remaining = [];
+			for (let i = 0; i < groups.length; i++) if (!processed.has(i)) remaining.push(i);
+			waves.push(remaining);
+			break;
+		}
+		waves.push(wave);
+		for (const idx of wave) {
+			processed.add(idx);
+			for (const successor of successors.get(idx)) inDegree[successor]--;
+		}
+	}
+	const batches = waves.map((wave) => wave.map((idx) => groups[idx]));
+	return {
+		batches,
+		edges
+	};
+}
 
 //#endregion
 //#region src/cli/commands/health.ts
@@ -7416,6 +7627,163 @@ function detectInterfaceChanges(options) {
 	}
 }
 
+//#endregion
+//#region src/modules/compiled-workflows/interface-contracts.ts
+/**
+* Parse the `## Interface Contracts` section from a story file.
+*
+* Looks for lines matching the format:
+*   - **Export**: SchemaName @ src/path/to/file.ts (optional transport)
+*   - **Import**: SchemaName @ src/path/to/file.ts (optional transport)
+*
+* The section is optional — returns empty array when not found or malformed.
+* Parsing stops at the next `##` heading to avoid false positives in other sections.
+*
+* @param storyContent - Full text content of the story markdown file
+* @param storyKey - Story key to associate with each declaration (e.g., "25-4")
+* @returns Array of typed contract declarations (may be empty)
+*/
+function parseInterfaceContracts(storyContent, storyKey) {
+	if (!storyContent || !storyKey) return [];
+	const sectionMatch = /^##\s+Interface\s+Contracts\s*$/im.exec(storyContent);
+	if (!sectionMatch) return [];
+	const sectionStart = sectionMatch.index + sectionMatch[0].length;
+	const afterSection = storyContent.slice(sectionStart);
+	const nextHeading = /^##\s+/m.exec(afterSection);
+	const sectionContent = nextHeading ? afterSection.slice(0, nextHeading.index) : afterSection;
+	const linePattern = /^\s*-\s+\*\*(Export|Import)\*\*:\s+(\S+)\s+@\s+(\S+)(?:\s+\(([^)]+)\))?/gim;
+	const declarations = [];
+	let match;
+	while ((match = linePattern.exec(sectionContent)) !== null) {
+		const [, directionRaw, contractName, filePath, transport] = match;
+		declarations.push({
+			contractName,
+			direction: directionRaw.toLowerCase(),
+			filePath,
+			storyKey,
+			...transport !== void 0 ? { transport } : {}
+		});
+	}
+	return declarations;
+}
+
+//#endregion
+//#region src/modules/implementation-orchestrator/contract-verifier.ts
+/**
+* Verify all declared contract export/import pairs after sprint completion.
+*
+* @param declarations - All ContractDeclaration entries from the decision store
+* @param projectRoot  - Absolute path to the project root for file resolution
+* @returns            - Array of ContractMismatch entries (empty = all passed)
+*/
+function verifyContracts(declarations, projectRoot) {
+	if (declarations.length === 0) return [];
+	const exports = declarations.filter((d) => d.direction === "export");
+	const imports = declarations.filter((d) => d.direction === "import");
+	if (exports.length === 0) return [];
+	const mismatches = [];
+	for (const exp of exports) {
+		if (!exp.filePath) continue;
+		const absPath = join$1(projectRoot, exp.filePath);
+		if (!existsSync$1(absPath)) {
+			const importers = imports.filter((i) => i.contractName === exp.contractName);
+			if (importers.length > 0) for (const imp of importers) mismatches.push({
+				exporter: exp.storyKey,
+				importer: imp.storyKey,
+				contractName: exp.contractName,
+				mismatchDescription: `Exported file not found: ${exp.filePath}`
+			});
+			else mismatches.push({
+				exporter: exp.storyKey,
+				importer: null,
+				contractName: exp.contractName,
+				mismatchDescription: `Exported file not found: ${exp.filePath}`
+			});
+		}
+	}
+	const tsconfigPath = join$1(projectRoot, "tsconfig.json");
+	const tscBinPath = join$1(projectRoot, "node_modules", ".bin", "tsc");
+	if (existsSync$1(tsconfigPath) && existsSync$1(tscBinPath)) {
+		let tscOutput = "";
+		let tscFailed = false;
+		try {
+			execSync(`"${tscBinPath}" --noEmit`, {
+				cwd: projectRoot,
+				timeout: 12e4,
+				encoding: "utf-8",
+				stdio: [
+					"pipe",
+					"pipe",
+					"pipe"
+				]
+			});
+		} catch (err) {
+			tscFailed = true;
+			if (err != null && typeof err === "object") {
+				const e = err;
+				const stdoutStr = typeof e.stdout === "string" ? e.stdout : Buffer.isBuffer(e.stdout) ? e.stdout.toString("utf-8") : "";
+				const stderrStr = typeof e.stderr === "string" ? e.stderr : Buffer.isBuffer(e.stderr) ? e.stderr.toString("utf-8") : "";
+				tscOutput = [stdoutStr, stderrStr].filter((s) => s.length > 0).join("\n");
+				if (!tscOutput && e.message) tscOutput = e.message;
+			}
+		}
+		if (tscFailed) {
+			const truncatedOutput = tscOutput.slice(0, 1e3);
+			const matchedExports = new Set();
+			for (const exp of exports) {
+				if (!exp.filePath) continue;
+				if (tscOutput.includes(exp.filePath)) {
+					matchedExports.add(exp.contractName);
+					const importers = imports.filter((i) => i.contractName === exp.contractName);
+					if (importers.length > 0) for (const imp of importers) mismatches.push({
+						exporter: exp.storyKey,
+						importer: imp.storyKey,
+						contractName: exp.contractName,
+						mismatchDescription: `TypeScript type-check failed for ${exp.filePath}: ${truncatedOutput}`
+					});
+					else mismatches.push({
+						exporter: exp.storyKey,
+						importer: null,
+						contractName: exp.contractName,
+						mismatchDescription: `TypeScript type-check failed for ${exp.filePath}: ${truncatedOutput}`
+					});
+				}
+			}
+			if (matchedExports.size === 0) {
+				const reportedPairs = new Set();
+				for (const exp of exports) {
+					const importers = imports.filter((i) => i.contractName === exp.contractName);
+					if (importers.length > 0) for (const imp of importers) {
+						const pairKey = `${exp.storyKey}:${imp.storyKey}:${exp.contractName}`;
+						if (!reportedPairs.has(pairKey)) {
+							reportedPairs.add(pairKey);
+							mismatches.push({
+								exporter: exp.storyKey,
+								importer: imp.storyKey,
+								contractName: exp.contractName,
+								mismatchDescription: `TypeScript type-check failed: ${truncatedOutput}`
+							});
+						}
+					}
+					else {
+						const pairKey = `${exp.storyKey}:null:${exp.contractName}`;
+						if (!reportedPairs.has(pairKey)) {
+							reportedPairs.add(pairKey);
+							mismatches.push({
+								exporter: exp.storyKey,
+								importer: null,
+								contractName: exp.contractName,
+								mismatchDescription: `TypeScript type-check failed: ${truncatedOutput}`
+							});
+						}
+					}
+				}
+			}
+		}
+	}
+	return mismatches;
+}
+
 //#endregion
 //#region src/modules/implementation-orchestrator/orchestrator-impl.ts
 function createPauseGate() {
@@ -7477,6 +7845,7 @@ function createImplementationOrchestrator(deps) {
 	const _phaseEndMs = new Map();
 	const _storyDispatches = new Map();
 	let _maxConcurrentActual = 0;
+	let _contractMismatches;
 	const MEMORY_PRESSURE_BACKOFF_MS = [
 		3e4,
 		6e4,
@@ -7673,6 +8042,7 @@ function createImplementationOrchestrator(deps) {
 		}
 		if (_decomposition !== void 0) status.decomposition = { ..._decomposition };
 		if (_maxConcurrentActual > 0) status.maxConcurrentActual = _maxConcurrentActual;
+		if (_contractMismatches !== void 0 && _contractMismatches.length > 0) status.contractMismatches = [..._contractMismatches];
 		return status;
 	}
 	function updateStory(storyKey, updates) {
@@ -7947,6 +8317,35 @@ function createImplementationOrchestrator(deps) {
 			persistState();
 			return;
 		}
+		if (storyFilePath) try {
+			const storyContent = await readFile$1(storyFilePath, "utf-8");
+			const contracts = parseInterfaceContracts(storyContent, storyKey);
+			if (contracts.length > 0) {
+				for (const contract of contracts) createDecision(db, {
+					pipeline_run_id: config.pipelineRunId ?? null,
+					phase: "implementation",
+					category: "interface-contract",
+					key: `${storyKey}:${contract.contractName}`,
+					value: JSON.stringify({
+						direction: contract.direction,
+						schemaName: contract.contractName,
+						filePath: contract.filePath,
+						storyKey: contract.storyKey,
+						...contract.transport !== void 0 ? { transport: contract.transport } : {}
+					})
+				});
+				logger$23.info({
+					storyKey,
+					contractCount: contracts.length,
+					contracts
+				}, "Stored interface contract declarations in decision store");
+			}
+		} catch (err) {
+			logger$23.warn({
+				storyKey,
+				error: err instanceof Error ? err.message : String(err)
+			}, "Failed to parse interface contracts — continuing without contract declarations");
+		}
 		await waitIfPaused();
 		if (_state !== "RUNNING") return;
 		startPhase(storyKey, "test-plan");
@@ -8254,9 +8653,9 @@ function createImplementationOrchestrator(deps) {
 			});
 			let verdict;
 			let issueList = [];
+			let reviewResult;
 			try {
 				const useBatchedReview = batchFileGroups.length > 1 && previousIssueList.length === 0;
-				let reviewResult;
 				if (useBatchedReview) {
 					const allIssues = [];
 					let worstVerdict = "SHIP_IT";
@@ -8268,6 +8667,7 @@ function createImplementationOrchestrator(deps) {
 					let lastRawOutput;
 					const verdictRank = {
 						"SHIP_IT": 0,
+						"LGTM_WITH_NOTES": .5,
 						"NEEDS_MINOR_FIXES": 1,
 						"NEEDS_MAJOR_REWORK": 2
 					};
@@ -8334,7 +8734,7 @@ function createImplementationOrchestrator(deps) {
 						...previousIssueList.length > 0 ? { previousIssues: previousIssueList } : {}
 					});
 				}
-				const isPhantomReview = reviewResult.dispatchFailed === true || reviewResult.verdict !== "SHIP_IT" && (reviewResult.issue_list === void 0 || reviewResult.issue_list.length === 0) && reviewResult.error !== void 0;
+				const isPhantomReview = reviewResult.dispatchFailed === true || reviewResult.verdict !== "SHIP_IT" && reviewResult.verdict !== "LGTM_WITH_NOTES" && (reviewResult.issue_list === void 0 || reviewResult.issue_list.length === 0) && reviewResult.error !== void 0;
 				if (isPhantomReview && !timeoutRetried) {
 					timeoutRetried = true;
 					logger$23.warn({
@@ -8407,19 +8807,38 @@ function createImplementationOrchestrator(deps) {
 				persistState();
 				return;
 			}
-			if (verdict === "SHIP_IT") {
+			if (verdict === "SHIP_IT" || verdict === "LGTM_WITH_NOTES") {
 				endPhase(storyKey, "code-review");
 				updateStory(storyKey, {
 					phase: "COMPLETE",
 					completedAt: new Date().toISOString()
 				});
-				writeStoryMetricsBestEffort(storyKey, "success", reviewCycles + 1);
+				writeStoryMetricsBestEffort(storyKey, verdict, reviewCycles + 1);
 				writeStoryOutcomeBestEffort(storyKey, "complete", reviewCycles + 1);
 				eventBus.emit("orchestrator:story-complete", {
 					storyKey,
 					reviewCycles
 				});
 				persistState();
+				if (verdict === "LGTM_WITH_NOTES" && reviewResult.notes && config.pipelineRunId) try {
+					createDecision(db, {
+						pipeline_run_id: config.pipelineRunId,
+						phase: "implementation",
+						category: ADVISORY_NOTES,
+						key: `${storyKey}:${config.pipelineRunId}`,
+						value: JSON.stringify({
+							storyKey,
+							notes: reviewResult.notes
+						}),
+						rationale: `Advisory notes from LGTM_WITH_NOTES review of ${storyKey}`
+					});
+					logger$23.info({ storyKey }, "Advisory notes persisted to decision store");
+				} catch (advisoryErr) {
+					logger$23.warn({
+						storyKey,
+						error: advisoryErr instanceof Error ? advisoryErr.message : String(advisoryErr)
+					}, "Failed to persist advisory notes (best-effort)");
+				}
 				try {
 					const expansionResult = await runTestExpansion({
 						db,
@@ -8566,7 +8985,7 @@ function createImplementationOrchestrator(deps) {
 					reviewCycles: finalReviewCycles,
 					completedAt: new Date().toISOString()
 				});
-				writeStoryMetricsBestEffort(storyKey, "success", finalReviewCycles);
+				writeStoryMetricsBestEffort(storyKey, verdict, finalReviewCycles);
 				writeStoryOutcomeBestEffort(storyKey, "complete", finalReviewCycles);
 				eventBus.emit("orchestrator:story-complete", {
 					storyKey,
@@ -8843,14 +9262,64 @@ function createImplementationOrchestrator(deps) {
 				skippedCategories: seedResult.skippedCategories
 			}, "Methodology context seeded from planning artifacts");
 		}
-		const groups = detectConflictGroups(storyKeys, { moduleMap: pack.manifest.conflictGroups });
+		const interfaceContractDecisions = getDecisionsByCategory(db, "interface-contract");
+		const contractDeclarations = interfaceContractDecisions.map((d) => {
+			try {
+				const parsed = JSON.parse(d.value);
+				const storyKey = typeof parsed.storyKey === "string" ? parsed.storyKey : "";
+				const contractName = typeof parsed.schemaName === "string" ? parsed.schemaName : "";
+				const direction = parsed.direction === "export" ? "export" : "import";
+				const filePath = typeof parsed.filePath === "string" ? parsed.filePath : "";
+				if (!storyKey || !contractName) return null;
+				return {
+					storyKey,
+					contractName,
+					direction,
+					filePath,
+					...typeof parsed.transport === "string" ? { transport: parsed.transport } : {}
+				};
+			} catch {
+				return null;
+			}
+		}).filter((d) => d !== null);
+		const { batches, edges: contractEdges } = detectConflictGroupsWithContracts(storyKeys, { moduleMap: pack.manifest.conflictGroups }, contractDeclarations);
+		if (contractEdges.length > 0) logger$23.info({
+			contractEdges,
+			edgeCount: contractEdges.length
+		}, "Contract dependency edges detected — applying contract-aware dispatch ordering");
 		logger$23.info("Orchestrator starting", {
 			storyCount: storyKeys.length,
-			groupCount: groups.length,
+			groupCount: batches.reduce((sum, b) => sum + b.length, 0),
+			batchCount: batches.length,
 			maxConcurrency: config.maxConcurrency
 		});
+		if (config.skipPreflight !== true) {
+			const preFlightResult = runBuildVerification({
+				verifyCommand: pack.manifest.verifyCommand,
+				verifyTimeoutMs: pack.manifest.verifyTimeoutMs,
+				projectRoot: projectRoot ?? process.cwd()
+			});
+			if (preFlightResult.status === "failed" || preFlightResult.status === "timeout") {
+				stopHeartbeat();
+				const truncatedOutput = (preFlightResult.output ?? "").slice(0, 2e3);
+				const exitCode = preFlightResult.exitCode ?? 1;
+				eventBus.emit("pipeline:pre-flight-failure", {
+					exitCode,
+					output: truncatedOutput
+				});
+				logger$23.error({
+					exitCode,
+					reason: preFlightResult.reason
+				}, "Pre-flight build check failed — aborting pipeline before any story dispatch");
+				_state = "FAILED";
+				_completedAt = new Date().toISOString();
+				persistState();
+				return getStatus();
+			}
+			if (preFlightResult.status !== "skipped") logger$23.info("Pre-flight build check passed");
+		}
 		try {
-			await runWithConcurrency(groups, config.maxConcurrency);
+			for (const batchGroups of batches) await runWithConcurrency(batchGroups, config.maxConcurrency);
 		} catch (err) {
 			stopHeartbeat();
 			_state = "FAILED";
@@ -8862,6 +9331,24 @@ function createImplementationOrchestrator(deps) {
 		stopHeartbeat();
 		_state = "COMPLETE";
 		_completedAt = new Date().toISOString();
+		if (projectRoot !== void 0 && contractDeclarations.length > 0) try {
+			const mismatches = verifyContracts(contractDeclarations, projectRoot);
+			if (mismatches.length > 0) {
+				_contractMismatches = mismatches;
+				for (const mismatch of mismatches) eventBus.emit("pipeline:contract-mismatch", {
+					exporter: mismatch.exporter,
+					importer: mismatch.importer,
+					contractName: mismatch.contractName,
+					mismatchDescription: mismatch.mismatchDescription
+				});
+				logger$23.warn({
+					mismatchCount: mismatches.length,
+					mismatches
+				}, "Post-sprint contract verification found mismatches — manual review required");
+			} else logger$23.info("Post-sprint contract verification passed — all declared contracts satisfied");
+		} catch (err) {
+			logger$23.error({ err }, "Post-sprint contract verification threw an error — skipping");
+		}
 		let completed = 0;
 		let escalated = 0;
 		let failed = 0;
@@ -12927,7 +13414,7 @@ function mapInternalPhaseToEventPhase(internalPhase) {
 	}
 }
 async function runRunAction(options) {
-	const { pack: packName, from: startPhase, stopAfter, concept: conceptArg, conceptFile, stories: storiesArg, concurrency, outputFormat, projectRoot, events: eventsFlag, verbose: verboseFlag, tui: tuiFlag, skipUx, research: researchFlag, skipResearch: skipResearchFlag, registry: injectedRegistry } = options;
+	const { pack: packName, from: startPhase, stopAfter, concept: conceptArg, conceptFile, stories: storiesArg, concurrency, outputFormat, projectRoot, events: eventsFlag, verbose: verboseFlag, tui: tuiFlag, skipUx, research: researchFlag, skipResearch: skipResearchFlag, skipPreflight, registry: injectedRegistry } = options;
 	if (startPhase !== void 0 && !VALID_PHASES.includes(startPhase)) {
 		const errorMsg = `Invalid phase '${startPhase}'. Valid phases: ${VALID_PHASES.join(", ")}`;
 		if (outputFormat === "json") process.stdout.write(formatOutput(null, "json", false, errorMsg) + "\n");
@@ -13014,6 +13501,7 @@ async function runRunAction(options) {
 		...skipUx === true ? { skipUx: true } : {},
 		...researchFlag === true ? { research: true } : {},
 		...skipResearchFlag === true ? { skipResearch: true } : {},
+		...skipPreflight === true ? { skipPreflight: true } : {},
 		...injectedRegistry !== void 0 ? { registry: injectedRegistry } : {}
 	});
 	let storyKeys = [];
@@ -13403,6 +13891,24 @@ async function runRunAction(options) {
 					dispatches: payload.dispatches
 				});
 			});
+			eventBus.on("pipeline:pre-flight-failure", (payload) => {
+				ndjsonEmitter.emit({
+					type: "pipeline:pre-flight-failure",
+					ts: new Date().toISOString(),
+					exitCode: payload.exitCode,
+					output: payload.output
+				});
+			});
+			eventBus.on("pipeline:contract-mismatch", (payload) => {
+				ndjsonEmitter.emit({
+					type: "pipeline:contract-mismatch",
+					ts: new Date().toISOString(),
+					exporter: payload.exporter,
+					importer: payload.importer,
+					contractName: payload.contractName,
+					mismatchDescription: payload.mismatchDescription
+				});
+			});
 		}
 		const orchestrator = createImplementationOrchestrator({
 			db,
@@ -13414,7 +13920,8 @@ async function runRunAction(options) {
 				maxConcurrency: concurrency,
 				maxReviewCycles: 2,
 				pipelineRunId: pipelineRun.id,
-				enableHeartbeat: eventsFlag === true
+				enableHeartbeat: eventsFlag === true,
+				skipPreflight: skipPreflight === true
 			},
 			projectRoot,
 			tokenCeilings
@@ -13513,7 +14020,7 @@ async function runRunAction(options) {
 	}
 }
 async function runFullPipeline(options) {
-	const { packName, packPath, dbDir, dbPath, startPhase, stopAfter, concept, concurrency, outputFormat, projectRoot, events: eventsFlag, skipUx, research: researchFlag, skipResearch: skipResearchFlag, registry: injectedRegistry, tokenCeilings } = options;
+	const { packName, packPath, dbDir, dbPath, startPhase, stopAfter, concept, concurrency, outputFormat, projectRoot, events: eventsFlag, skipUx, research: researchFlag, skipResearch: skipResearchFlag, skipPreflight, registry: injectedRegistry, tokenCeilings } = options;
 	if (!existsSync(dbDir)) mkdirSync(dbDir, { recursive: true });
 	const dbWrapper = new DatabaseWrapper(dbPath);
 	try {
@@ -13718,7 +14225,8 @@ async function runFullPipeline(options) {
 					config: {
 						maxConcurrency: concurrency,
 						maxReviewCycles: 2,
-						pipelineRunId: runId
+						pipelineRunId: runId,
+						skipPreflight: skipPreflight === true
 					},
 					projectRoot,
 					tokenCeilings
@@ -13818,7 +14326,7 @@ async function runFullPipeline(options) {
 	}
 }
 function registerRunCommand(program, _version = "0.0.0", projectRoot = process.cwd(), registry) {
-	program.command("run").description("Run the autonomous pipeline (use --from to start from a specific phase)").option("--pack <name>", "Methodology pack name", "bmad").option("--from <phase>", "Start from this phase: analysis, planning, solutioning, implementation").option("--stop-after <phase>", "Stop pipeline after this phase completes").option("--concept <text>", "Inline concept text (required when --from analysis)").option("--concept-file <path>", "Path to a file containing the concept text").option("--stories <keys>", "Comma-separated story keys (e.g., 10-1,10-2)").option("--concurrency <n>", "Maximum parallel conflict groups", (v) => parseInt(v, 10), 3).option("--project-root <path>", "Project root directory", projectRoot).option("--output-format <format>", "Output format: human (default) or json", "human").option("--events", "Emit structured NDJSON events on stdout for programmatic consumption").option("--verbose", "Show detailed pino log output").option("--help-agent", "Print a machine-optimized prompt fragment for AI agents and exit").option("--tui", "Show TUI dashboard").option("--skip-ux", "Skip the UX design phase even if enabled in the pack manifest").option("--research", "Enable the research phase even if not set in the pack manifest").option("--skip-research", "Skip the research phase even if enabled in the pack manifest").action(async (opts) => {
+	program.command("run").description("Run the autonomous pipeline (use --from to start from a specific phase)").option("--pack <name>", "Methodology pack name", "bmad").option("--from <phase>", "Start from this phase: analysis, planning, solutioning, implementation").option("--stop-after <phase>", "Stop pipeline after this phase completes").option("--concept <text>", "Inline concept text (required when --from analysis)").option("--concept-file <path>", "Path to a file containing the concept text").option("--stories <keys>", "Comma-separated story keys (e.g., 10-1,10-2)").option("--concurrency <n>", "Maximum parallel conflict groups", (v) => parseInt(v, 10), 3).option("--project-root <path>", "Project root directory", projectRoot).option("--output-format <format>", "Output format: human (default) or json", "human").option("--events", "Emit structured NDJSON events on stdout for programmatic consumption").option("--verbose", "Show detailed pino log output").option("--help-agent", "Print a machine-optimized prompt fragment for AI agents and exit").option("--tui", "Show TUI dashboard").option("--skip-ux", "Skip the UX design phase even if enabled in the pack manifest").option("--research", "Enable the research phase even if not set in the pack manifest").option("--skip-research", "Skip the research phase even if enabled in the pack manifest").option("--skip-preflight", "Skip the pre-flight build check (escape hatch for known-broken projects)").action(async (opts) => {
 		if (opts.helpAgent) {
 			process.exitCode = await runHelpAgent();
 			return;
@@ -13851,6 +14359,7 @@ function registerRunCommand(program, _version = "0.0.0", projectRoot = process.c
 			skipUx: opts.skipUx,
 			research: opts.research,
 			skipResearch: opts.skipResearch,
+			skipPreflight: opts.skipPreflight,
 			registry
 		});
 		process.exitCode = exitCode;
@@ -13859,4 +14368,4 @@ function registerRunCommand(program, _version = "0.0.0", projectRoot = process.c
 
 //#endregion
 export { 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, runAnalysisPhase, runMigrations, runPlanningPhase, runRunAction, runSolutioningPhase, validateStopAfterFromConflict };
-//# sourceMappingURL=run-Ajt187oE.js.map
+//# sourceMappingURL=run-BxXwD2xY.js.map

package/dist/{run-KBcR3Jpi.js → run-CMagiY2Y.js}

@@ -1,8 +1,8 @@
-import { registerRunCommand, runRunAction } from "./run-Ajt187oE.js";
+import { registerRunCommand, runRunAction } from "./run-BxXwD2xY.js";
 import "./logger-D2fS2ccL.js";
 import "./config-migrator-DSi8KhQC.js";
 import "./helpers-RL22dYtn.js";
 import "./decisions-Dq4cAA2L.js";
-import "./operational-CnMlvWqc.js";
+import "./operational-Bovj4fS-.js";
 
 export { runRunAction };

package/package.json

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

package/packs/bmad/manifest.yaml

@@ -221,6 +221,8 @@ prompts:
   refine-artifact: prompts/refine-artifact.md
   # Readiness check prompt (Story 16-6)
   readiness-check: prompts/readiness-check.md
+  # Test plan prompt (Story 25-7)
+  test-plan: prompts/test-plan.md
 
 constraints:
   create-story: constraints/create-story.yaml

package/packs/bmad/prompts/code-review.md

@@ -100,6 +100,11 @@ ac_checklist:
 **IMPORTANT**: `ac_checklist` must contain one entry for every AC found in the story. If the story has no parseable ACs (e.g. a refactoring story), `ac_checklist` may be an empty array.
 
 **Verdict rules:**
-- `SHIP_IT` — zero blocker/major issues (minor issues acceptable)
-- `NEEDS_MINOR_FIXES` — minor issues only, or 1-2 major with no blockers
+- `SHIP_IT` — zero issues of any kind
+- `LGTM_WITH_NOTES` — zero correctness/logic/security issues; only advisory or style observations that do not need to be fixed before shipping. Use this when you have optional suggestions but the code is production-ready as-is. Include your suggestions in the `notes` field.
+- `NEEDS_MINOR_FIXES` — one or more minor issues that should be fixed, or 1-2 major issues with no blockers
 - `NEEDS_MAJOR_REWORK` — any blocker issue, or 3+ major issues
+
+**LGTM_WITH_NOTES vs NEEDS_MINOR_FIXES:**
+- Use `LGTM_WITH_NOTES` when: all findings are purely advisory (naming preferences, optional refactors, docs suggestions) and the code ships safely without any changes
+- Use `NEEDS_MINOR_FIXES` when: any finding represents a real gap that should be corrected before the story is considered done (missing error handling, incomplete AC coverage, confusing logic)

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

@@ -35,6 +35,26 @@ Using the context above, write a complete, implementation-ready story file for s
    - Status must be: `ready-for-dev`
    - Dev Agent Record section must be present but left blank (to be filled by dev agent)
 
+## Interface Contracts Guidance
+
+**Identify cross-story dependencies** when the story creates or consumes shared schemas, interfaces, or message contracts.
+
+If the story exports (creates) or imports (consumes from another story) any TypeScript interfaces, Zod schemas, message queue contracts, or API types that are shared across module boundaries, add an `## Interface Contracts` section to the story file.
+
+Use this exact format for each item:
+
+```markdown
+## Interface Contracts
+
+- **Export**: SchemaName @ src/path/to/file.ts (queue: some-queue-name)
+- **Import**: SchemaName @ src/path/to/file.ts (from story 25-X)
+```
+
+- `Export` = this story creates/defines the schema that other stories will consume
+- `Import` = this story consumes a schema defined by another story
+- The transport annotation `(queue: ...)` or `(api: ...)` or `(from story X-Y)` is optional but recommended when applicable
+- **The `## Interface Contracts` section is optional** — omit it entirely if the story has no cross-story schema dependencies
+
 ## Scope Cap Guidance
 
 **Aim for 6-7 acceptance criteria and 7-8 tasks per story.**

package/packs/bmad/prompts/test-plan.md

@@ -2,24 +2,30 @@
 
 ## Mission
 
-Analyze the story's Acceptance Criteria and tasks. Produce a concrete test plan listing the test files to create, the test categories to cover (unit/integration/e2e), and a brief note on AC coverage.
+Analyze the story's Acceptance Criteria and tasks. Produce a concrete test plan listing the test files to create, the test categories to cover (unit/integration/e2e), and comprehensive coverage notes that include: which ACs each test covers, dependencies to mock, and error conditions to assert.
 
 ## Story Content
 
 {{story_content}}
 
+## Architecture Constraints
+
+{{architecture_constraints}}
+
 ## Instructions
 
 1. Read the Acceptance Criteria (AC1, AC2, etc.) and Tasks in the story above.
 2. Identify the source files that will need tests (from Dev Notes, Key File Paths, and Tasks).
 3. For each AC, determine which test file and test function will validate it.
-4. Produce a concise test plan — one or two test files is typical for small stories.
+4. Identify all external dependencies (modules, services, fs, db) that must be mocked or stubbed.
+5. Identify error conditions and edge cases that must be asserted (not just the happy path).
+6. Produce a concise test plan — one or two test files is typical for small stories.
 
 **Rules:**
 - List only test files that will be NEW (not existing ones you'd extend unless necessary).
 - Use the project's test path convention: `src/modules/<module>/__tests__/<file>.test.ts`
 - Test categories: `unit` for isolated function tests, `integration` for multi-module tests, `e2e` for full pipeline tests.
-- Keep `coverage_notes` brief — one sentence per AC is sufficient.
+- `coverage_notes` must include: (a) which test file covers each AC, (b) dependencies to mock (e.g., `vi.mock('node:fs/promises')`), and (c) error conditions to assert (e.g., missing file, schema validation failure, timeout).
 
 ## Output Contract
 
@@ -31,7 +37,7 @@ test_files:
 test_categories:
   - unit
   - integration
-coverage_notes: "AC1 covered by foo.test.ts describe('runFoo'). AC2 covered by..."
+coverage_notes: "AC1: foo.test.ts describe('runFoo') covers the happy path. AC2: same file covers error path (rejects on ENOENT). Mocks needed: vi.mock('node:fs/promises'), vi.mock('../db.js'). Error conditions: file not found returns failed result, schema parse error returns failed with details, timeout triggers fallback."
 
 If you cannot produce a plan (e.g., story content is missing or unreadable), emit: