substrate-ai 0.20.12 → 0.20.13

package/dist/{health-0jqPFBEL.js → health-CxBbduMn.js}

@@ -4210,6 +4210,12 @@ const RunManifestSchema = z.object({
 	run_id: z.string(),
 	cli_flags: CliFlagsSchema.transform((v) => v),
 	story_scope: z.array(z.string()),
+	run_status: z.enum([
+		"running",
+		"completed",
+		"failed",
+		"stopped"
+	]).optional(),
 	supervisor_pid: z.number().nullable(),
 	supervisor_session_id: z.string().nullable(),
 	per_story_state: z.record(z.string(), PerStoryStateSchema),
@@ -4219,6 +4225,8 @@ const RunManifestSchema = z.object({
 		run_total: 0
 	}),
 	pending_proposals: z.array(ProposalSchema),
+	stopped_reason: z.string().optional(),
+	stopped_at: z.string().optional(),
 	generation: z.number().int().nonnegative(),
 	created_at: z.string(),
 	updated_at: z.string()
@@ -4560,6 +4568,55 @@ var RunManifest = class RunManifest {
 	/**
 	* Raw implementation — must only be called from within `_enqueue`.
 	*/
+	async _patchRunStatusImpl(updates) {
+		let existingData;
+		try {
+			const read = await RunManifest.read(this.runId, this.baseDir, this.doltAdapter);
+			const { generation: _gen, updated_at: _ts,...rest } = read;
+			existingData = rest;
+		} catch {
+			const now = new Date().toISOString();
+			existingData = {
+				run_id: this.runId,
+				cli_flags: {},
+				story_scope: [],
+				supervisor_pid: null,
+				supervisor_session_id: null,
+				per_story_state: {},
+				recovery_history: [],
+				cost_accumulation: {
+					per_story: {},
+					run_total: 0
+				},
+				pending_proposals: [],
+				created_at: now
+			};
+		}
+		const merged = { ...existingData };
+		if (updates.run_status !== void 0) merged.run_status = updates.run_status;
+		if (updates.stopped_reason !== void 0) merged.stopped_reason = updates.stopped_reason;
+		if (updates.stopped_at !== void 0) merged.stopped_at = updates.stopped_at;
+		await this._writeImpl(merged);
+	}
+	/**
+	* Atomically update the run-level status fields in the manifest.
+	*
+	* Reads the current manifest (or creates a minimal default if absent),
+	* merges the provided status updates at the top level, and writes the
+	* result atomically via a single `write()` call.
+	*
+	* Enqueues the operation via `_enqueue` so concurrent calls are serialized
+	* (preserves the single-writer guarantee from Epic 57-1).
+	* Non-fatal: callers MUST wrap in `.catch((err) => logger.warn(...))`.
+	*
+	* @param updates - Top-level status fields to merge (run_status, stopped_reason, stopped_at)
+	*/
+	async patchRunStatus(updates) {
+		return this._enqueue(() => this._patchRunStatusImpl(updates));
+	}
+	/**
+	* Raw implementation — must only be called from within `_enqueue`.
+	*/
 	async _appendRecoveryEntryImpl(entry) {
 		let existingData;
 		try {
@@ -5477,4 +5534,4 @@ function registerHealthCommand(program, _version = "0.0.0", projectRoot = proces
 
 //#endregion
 export { BMAD_BASELINE_TOKENS_FULL, DEFAULT_STALL_THRESHOLD_SECONDS, DoltMergeConflict, FileStateStore, FindingsInjector, RunManifest, STOP_AFTER_VALID_PHASES, STORY_KEY_PATTERN$1 as STORY_KEY_PATTERN, SUBSTRATE_OWNED_SETTINGS_KEYS, SupervisorLock, VALID_PHASES, WorkGraphRepository, ZERO_FINDING_COUNTS, __commonJS, __require, __toESM, applyConfigToGraph, buildPipelineStatusOutput, createDatabaseAdapter$1 as createDatabaseAdapter, createDefaultVerificationPipeline, createGraphOrchestrator, createSdlcCodeReviewHandler, createSdlcCreateStoryHandler, createSdlcDevStoryHandler, createSdlcPhaseHandler, createStateStore, detectCycles, extractTargetFilesFromStoryContent, findPackageRoot, formatOutput, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getAllDescendantPids, getAutoHealthData, getSubstrateDefaultSettings, inspectProcessTree, isOrchestratorProcessLine, parseDbTimestampAsUtc, registerHealthCommand, renderFindings, resolveBmadMethodSrcPath, resolveBmadMethodVersion, resolveGraphPath, resolveMainRepoRoot, resolveRunManifest, rollupFindingCounts, runHealthAction, validateStoryKey };
-//# sourceMappingURL=health-0jqPFBEL.js.map
+//# sourceMappingURL=health-CxBbduMn.js.map

package/dist/{health-C401hYzi.js → health-RIYFKE9U.js}

@@ -1,4 +1,4 @@
-import { DEFAULT_STALL_THRESHOLD_SECONDS, getAllDescendantPids, getAutoHealthData, inspectProcessTree, isOrchestratorProcessLine, registerHealthCommand, runHealthAction } from "./health-0jqPFBEL.js";
+import { DEFAULT_STALL_THRESHOLD_SECONDS, getAllDescendantPids, getAutoHealthData, inspectProcessTree, isOrchestratorProcessLine, registerHealthCommand, runHealthAction } from "./health-CxBbduMn.js";
 import "./logger-KeHncl-f.js";
 import "./dist-CqtWS9wF.js";
 import "./decisions-C0pz9Clx.js";

package/dist/index.d.ts

@@ -2286,6 +2286,20 @@ interface OrchestratorEvents {
     /** Retry attempt number (always 2 — first retry after initial timeout) */
     attempt: number;
   };
+  /**
+   * Emitted when an existing story artifact's stored source-AC hash differs
+   * from the current source epic's AC hash, or when the artifact carries no
+   * hash at all (legacy artifact). Causes the orchestrator to re-run
+   * create-story instead of reusing the stale artifact.
+   */
+  'story:ac-source-drift': {
+    /** Story key whose artifact is stale */
+    storyKey: string;
+    /** Hash stored in the artifact's HTML comment (null if absent — legacy artifact) */
+    storedHash: string | null;
+    /** Hash computed from the current source epic's AC section */
+    currentHash: string;
+  };
 }
 
 //#endregion

package/dist/{run-DEyd1p7U.js → run-BDQLMeWK.js}

@@ -1,8 +1,8 @@
-import "./health-0jqPFBEL.js";
+import "./health-CxBbduMn.js";
 import "./logger-KeHncl-f.js";
 import "./helpers-CElYrONe.js";
 import "./dist-CqtWS9wF.js";
-import { normalizeGraphSummaryToStatus, registerRunCommand, resolveMaxReviewCycles, runRunAction, wireNdjsonEmitter } from "./run-B6qbsy-F.js";
+import { normalizeGraphSummaryToStatus, registerRunCommand, resolveMaxReviewCycles, runRunAction, wireNdjsonEmitter } from "./run-D5VAkItq.js";
 import "./routing-CcBOCuC9.js";
 import "./decisions-C0pz9Clx.js";
 

package/dist/{run-B6qbsy-F.js → run-D5VAkItq.js}

@@ -1,4 +1,4 @@
-import { BMAD_BASELINE_TOKENS_FULL, DoltMergeConflict, FileStateStore, FindingsInjector, RunManifest, STOP_AFTER_VALID_PHASES, STORY_KEY_PATTERN, VALID_PHASES, WorkGraphRepository, __commonJS, __require, __toESM, applyConfigToGraph, buildPipelineStatusOutput, createDatabaseAdapter, createDefaultVerificationPipeline, createGraphOrchestrator, createSdlcCodeReviewHandler, createSdlcCreateStoryHandler, createSdlcDevStoryHandler, createSdlcPhaseHandler, detectCycles, extractTargetFilesFromStoryContent, formatOutput, formatPipelineSummary, formatTokenTelemetry, inspectProcessTree, parseDbTimestampAsUtc, renderFindings, resolveGraphPath, resolveMainRepoRoot, validateStoryKey } from "./health-0jqPFBEL.js";
+import { BMAD_BASELINE_TOKENS_FULL, DoltMergeConflict, FileStateStore, FindingsInjector, RunManifest, STOP_AFTER_VALID_PHASES, STORY_KEY_PATTERN, VALID_PHASES, WorkGraphRepository, __commonJS, __require, __toESM, applyConfigToGraph, buildPipelineStatusOutput, createDatabaseAdapter, createDefaultVerificationPipeline, createGraphOrchestrator, createSdlcCodeReviewHandler, createSdlcCreateStoryHandler, createSdlcDevStoryHandler, createSdlcPhaseHandler, detectCycles, extractTargetFilesFromStoryContent, formatOutput, formatPipelineSummary, formatTokenTelemetry, inspectProcessTree, parseDbTimestampAsUtc, renderFindings, resolveGraphPath, resolveMainRepoRoot, validateStoryKey } from "./health-CxBbduMn.js";
 import { createLogger } from "./logger-KeHncl-f.js";
 import { TypedEventBusImpl, createEventBus, createTuiApp, isTuiCapable, printNonTtyWarning, sleep } from "./helpers-CElYrONe.js";
 import { ADVISORY_NOTES, Categorizer, ConsumerAnalyzer, DEFAULT_GLOBAL_SETTINGS, DispatcherImpl, DoltClient, ESCALATION_DIAGNOSIS, EXPERIMENT_RESULT, EfficiencyScorer, IngestionServer, LogTurnAnalyzer, OPERATIONAL_FINDING, Recommender, RoutingRecommender, RoutingResolver, RoutingTelemetry, RoutingTokenAccumulator, RoutingTuner, STORY_METRICS, STORY_OUTCOME, SubstrateConfigSchema, TEST_EXPANSION_FINDING, TEST_PLAN, TelemetryNormalizer, TelemetryPipeline, TurnAnalyzer, addTokenUsage, aggregateTokenUsageForRun, aggregateTokenUsageForStory, callLLM, createConfigSystem, createDatabaseAdapter$1, createDecision, createPipelineRun, createRequirement, detectInterfaceChanges, getArtifactByTypeForRun, getArtifactsByRun, getDecisionsByCategory, getDecisionsByPhase, getDecisionsByPhaseForRun, getLatestRun, getPipelineRunById, getRunMetrics, getRunningPipelineRuns, getStoryMetricsForRun, getTokenUsageSummary, initSchema, listRequirements, loadModelRoutingConfig, registerArtifact, updatePipelineRun, updatePipelineRunConfig, upsertDecision, writeRunMetrics, writeStoryMetrics } from "./dist-CqtWS9wF.js";
@@ -5676,6 +5676,21 @@ function getTokenCeiling(workflowType, tokenCeilings) {
 //#region src/modules/compiled-workflows/create-story.ts
 const logger$18 = createLogger("compiled-workflows:create-story");
 /**
+* Compute a hex SHA-256 of the normalized source AC section text.
+*
+* Normalization (minimal — avoids spurious regen from editor whitespace noise):
+*   1. Split on `\n`
+*   2. Strip trailing whitespace from each line (`.trimEnd()`)
+*   3. Rejoin with `\n`
+*   4. Trim the whole result (`.trim()`)
+*
+* Pure function: no I/O, no side effects. Safe to call from tests with zero setup.
+*/
+function hashSourceAcSection(section) {
+	const normalized = section.split("\n").map((line) => line.trimEnd()).join("\n").trim();
+	return createHash("sha256").update(normalized, "utf8").digest("hex");
+}
+/**
 * Execute the compiled create-story workflow.
 *
 * Steps:
@@ -5693,7 +5708,7 @@ const logger$18 = createLogger("compiled-workflows:create-story");
 * @returns Promise resolving to CreateStoryResult
 */
 async function runCreateStory(deps, params) {
-	const { epicId, storyKey, pipelineRunId } = params;
+	const { epicId, storyKey, pipelineRunId, source_ac_hash } = params;
 	logger$18.debug({
 		epicId,
 		storyKey,
@@ -5764,7 +5779,12 @@ async function runCreateStory(deps, params) {
 			name: "story_template",
 			content: storyTemplateContent,
 			priority: "important"
-		}
+		},
+		...source_ac_hash !== void 0 ? [{
+			name: "source_ac_hash",
+			content: source_ac_hash,
+			priority: "required"
+		}] : []
 	], TOKEN_CEILING);
 	logger$18.debug({
 		tokenCount,
@@ -11367,6 +11387,10 @@ function createImplementationOrchestrator(deps) {
 	let _costWarningEmitted = false;
 	let _budgetExhausted = false;
 	let _otlpEndpoint;
+	let _shutdownRequested = false;
+	let _inFlightCount = 0;
+	let _drainResolve = null;
+	let _drainPromise = Promise.resolve();
 	const verificationStore = new VerificationStore();
 	const verificationPipeline = createDefaultVerificationPipeline(toSdlcEventBus(eventBus));
 	const _stateStoreCache = new Map();
@@ -12004,6 +12028,7 @@ function createImplementationOrchestrator(deps) {
 			startedAt: new Date().toISOString()
 		});
 		let storyFilePath;
+		let sourceAcHash;
 		const artifactsDir = projectRoot ? join$1(projectRoot, "_bmad-output", "implementation-artifacts") : void 0;
 		if (artifactsDir && existsSync(artifactsDir)) try {
 			const files = readdirSync(artifactsDir);
@@ -12017,22 +12042,52 @@ function createImplementationOrchestrator(deps) {
 					reason: validation.reason
 				}, `Existing story file for ${storyKey} is invalid (${validation.reason}) — re-creating`);
 				else {
-					storyFilePath = candidatePath;
-					logger$24.info({
-						storyKey,
-						storyFilePath
-					}, "Found existing story file — skipping create-story");
-					endPhase(storyKey, "create-story");
-					eventBus.emit("orchestrator:story-phase-complete", {
-						storyKey,
-						phase: "IN_STORY_CREATION",
-						result: {
-							result: "success",
-							story_file: storyFilePath,
-							story_key: storyKey
+					let isDrift = false;
+					try {
+						const epicsPath = projectRoot ? findEpicsFile(projectRoot) : void 0;
+						if (epicsPath !== void 0) {
+							const epicContent = readFileSync(epicsPath, "utf-8");
+							const sourceSection = extractStorySection(epicContent, storyKey);
+							if (sourceSection != null) {
+								const currentHash = hashSourceAcSection(sourceSection);
+								sourceAcHash = currentHash;
+								const artifactContent = await readFile$1(candidatePath, "utf-8");
+								const hashMatch = /<!--\s*source-ac-hash:\s*([0-9a-f]{64})\s*-->/.exec(artifactContent);
+								const storedHash = hashMatch?.[1] ?? null;
+								if (storedHash !== currentHash) {
+									isDrift = true;
+									eventBus.emit("story:ac-source-drift", {
+										storyKey,
+										storedHash,
+										currentHash
+									});
+									logger$24.info({
+										storyKey,
+										storedHash,
+										currentHash
+									}, `[orchestrator] story ${storyKey}: source AC hash mismatch, regenerating story artifact`);
+								}
+							}
 						}
-					});
-					await persistState();
+					} catch {}
+					if (!isDrift) {
+						storyFilePath = candidatePath;
+						logger$24.info({
+							storyKey,
+							storyFilePath
+						}, "Found existing story file — skipping create-story");
+						endPhase(storyKey, "create-story");
+						eventBus.emit("orchestrator:story-phase-complete", {
+							storyKey,
+							phase: "IN_STORY_CREATION",
+							result: {
+								result: "success",
+								story_file: storyFilePath,
+								story_key: storyKey
+							}
+						});
+						await persistState();
+					}
 				}
 			}
 		} catch {}
@@ -12069,7 +12124,8 @@ function createImplementationOrchestrator(deps) {
 			}, {
 				epicId: storyKey.split("-")[0] ?? storyKey,
 				storyKey,
-				pipelineRunId: config.pipelineRunId
+				pipelineRunId: config.pipelineRunId,
+				source_ac_hash: sourceAcHash
 			});
 			endPhase(storyKey, "create-story");
 			eventBus.emit("orchestrator:story-phase-complete", {
@@ -13898,6 +13954,10 @@ function createImplementationOrchestrator(deps) {
 	async function processConflictGroup(group) {
 		const completedStoryKeys = [];
 		for (const storyKey of group) {
+			if (_shutdownRequested) {
+				logger$24.info({ storyKey }, "shutdown requested — skipping dispatch");
+				return;
+			}
 			if (runManifest !== null && runManifest !== void 0) try {
 				const manifestData = await runManifest.read();
 				const ceiling = manifestData.cli_flags.cost_ceiling;
@@ -13956,11 +14016,15 @@ function createImplementationOrchestrator(deps) {
 		const running = new Set();
 		function enqueue() {
 			if (_budgetExhausted) return;
+			if (_shutdownRequested) return;
 			const group = queue.shift();
 			if (group === void 0) return;
+			_inFlightCount++;
 			const p = processConflictGroup(group).finally(() => {
 				running.delete(p);
-				while (running.size < maxConcurrency && queue.length > 0) enqueue();
+				_inFlightCount--;
+				if (_inFlightCount === 0 && _shutdownRequested) _drainResolve?.();
+				while (running.size < maxConcurrency && queue.length > 0 && !_shutdownRequested && !_budgetExhausted) enqueue();
 			});
 			running.add(p);
 			if (running.size > _maxConcurrentActual) _maxConcurrentActual = running.size;
@@ -13969,6 +14033,47 @@ function createImplementationOrchestrator(deps) {
 		for (let i = 0; i < initial; i++) enqueue();
 		while (running.size > 0) await Promise.race(running);
 	}
+	/**
+	* Gracefully shut down the pipeline in response to a POSIX signal.
+	*
+	* 1. Sets the in-memory `_shutdownRequested` flag so the dispatch loop stops
+	*    scheduling new stories.
+	* 2. Awaits any in-flight dispatches for up to `config.shutdownGracePeriodMs` ms
+	*    (default 5000).
+	* 3. Writes `run_status: 'stopped'` and `stopped_reason` to the run manifest.
+	* 4. Best-effort: updates `pipeline_runs.status = 'stopped'` in Dolt and
+	*    transitions active wg_stories to 'cancelled'.
+	* 5. Calls `process.exit(130)` for SIGINT or `process.exit(143)` for SIGTERM.
+	*/
+	async function shutdownGracefully(reason, signal) {
+		if (_shutdownRequested) return;
+		_shutdownRequested = true;
+		logger$24.info({
+			reason,
+			signal
+		}, "Graceful shutdown initiated");
+		const gracePeriod = config.shutdownGracePeriodMs ?? 5e3;
+		if (_inFlightCount === 0) _drainResolve?.();
+		await Promise.race([_drainPromise, new Promise((resolve$6) => setTimeout(resolve$6, gracePeriod))]);
+		if (runManifest !== null && runManifest !== void 0) await runManifest.patchRunStatus({
+			run_status: "stopped",
+			stopped_reason: reason,
+			stopped_at: new Date().toISOString()
+		}).catch((err) => logger$24.warn({ err }, "patchRunStatus failed during shutdown (best-effort)"));
+		if (config.pipelineRunId !== void 0) try {
+			await updatePipelineRun(db, config.pipelineRunId, { status: "stopped" });
+		} catch (err) {
+			logger$24.warn({ err }, "updatePipelineRun(stopped) failed during shutdown (best-effort)");
+		}
+		for (const [storyKey, storyState] of _stories) {
+			const isActive = storyState.phase === "PENDING" || storyState.phase === "IN_STORY_CREATION" || storyState.phase === "IN_TEST_PLANNING" || storyState.phase === "IN_DEV" || storyState.phase === "IN_REVIEW" || storyState.phase === "NEEDS_FIXES" || storyState.phase === "CHECKPOINT";
+			if (isActive) wgRepo.updateStoryStatus(storyKey, "cancelled").catch((err) => logger$24.warn({
+				err,
+				storyKey
+			}, "updateStoryStatus(cancelled) failed during shutdown (best-effort)"));
+		}
+		process.exit(signal === "SIGINT" ? 130 : 143);
+	}
 	async function run(storyKeys) {
 		if (_state === "RUNNING" || _state === "PAUSED") {
 			logger$24.warn({ state: _state }, "run() called while orchestrator is already running or paused — ignoring");
@@ -13980,6 +14085,20 @@ function createImplementationOrchestrator(deps) {
 		}
 		_state = "RUNNING";
 		_startedAt = new Date().toISOString();
+		_shutdownRequested = false;
+		_inFlightCount = 0;
+		_drainResolve = null;
+		_drainPromise = new Promise((resolve$6) => {
+			_drainResolve = resolve$6;
+		});
+		const sigtermHandler = () => {
+			shutdownGracefully("killed_by_user", "SIGTERM");
+		};
+		const sigintHandler = () => {
+			shutdownGracefully("killed_by_user", "SIGINT");
+		};
+		process.on("SIGTERM", sigtermHandler);
+		process.on("SIGINT", sigintHandler);
 		for (const key of storyKeys) {
 			const pendingState = {
 				phase: "PENDING",
@@ -14264,6 +14383,8 @@ function createImplementationOrchestrator(deps) {
 			await persistState();
 			return getStatus();
 		} finally {
+			process.off("SIGTERM", sigtermHandler);
+			process.off("SIGINT", sigintHandler);
 			if (stateStore !== void 0) await stateStore.close().catch((err) => logger$24.warn({ err }, "StateStore.close() failed (best-effort)"));
 			if (ingestionServer !== void 0) await ingestionServer.stop().catch((err) => logger$24.warn({ err }, "IngestionServer.stop() failed (best-effort)"));
 		}
@@ -43858,4 +43979,4 @@ function registerRunCommand(program, _version = "0.0.0", projectRoot = process.c
 
 //#endregion
 export { AdapterTelemetryPersistence, AppError, DoltRepoMapMetaRepository, DoltSymbolRepository, ERR_REPO_MAP_STORAGE_WRITE, EpicIngester, GitClient, GrammarLoader, RepoMapInjector, RepoMapModule, RepoMapQueryEngine, RepoMapStorage, SymbolParser, createContextCompiler, createDispatcher, createEventEmitter, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, createTelemetryAdvisor, formatPhaseCompletionSummary, getFactoryRunSummaries, getScenarioResultsForRun, getTwinRunsForRun, listGraphRuns, normalizeGraphSummaryToStatus, registerExportCommand, registerFactoryCommand, registerRunCommand, registerScenariosCommand, resolveMaxReviewCycles, resolveStoryKeys, runAnalysisPhase, runPlanningPhase, runRunAction, runSolutioningPhase, validateStopAfterFromConflict, wireNdjsonEmitter };
-//# sourceMappingURL=run-B6qbsy-F.js.map
+//# sourceMappingURL=run-D5VAkItq.js.map

package/package.json

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

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

@@ -38,6 +38,7 @@ a different story from the epic scope. The story key, title, and core scope are
 5. **Fill out the story template** with:
    - A clear user story (As a / I want / So that)
    - Acceptance criteria: preserve the hard-clause text from the Story Definition verbatim. BDD Given/When/Then phrasing is **optional** — permitted for behavior-oriented criteria where it adds clarity, not mandatory. Never let BDD reshape a MUST / MUST NOT / SHALL clause; copy those clauses literally and, if BDD adds clarity, append the Given/When/Then alongside the original clause rather than replacing it. Aim for the same number of ACs as the source — do not condense clauses into fewer items to hit a target count.
+   - Immediately after the `## Acceptance Criteria` heading in the rendered story file, emit the line `<!-- source-ac-hash: {{source_ac_hash}} -->` on its own line. When the hash value is empty or blank (the `{{source_ac_hash}}` placeholder resolved to nothing), omit the comment entirely — do not write `<!-- source-ac-hash:  -->` or any comment with an empty or missing hash value.
    - Concrete tasks broken into 2–4 hour subtasks, each tied to specific ACs
    - Dev Notes with file paths, import patterns, testing requirements
 6. **Apply the scope cap** — see Scope Cap Guidance below