substrate-ai 0.19.53 → 0.20.0

package/README.md

@@ -340,6 +340,33 @@ substrate factory twins status
 substrate factory twins down
 ```
 
+## Using as a Library
+
+Substrate ships as a family of npm packages. Most users just want the CLI (`substrate-ai`); the scoped packages are for downstream projects that want to embed substrate pieces directly.
+
+| Package | Use when you want... |
+|---------|----------------------|
+| `substrate-ai` | The full CLI — installed globally |
+| `@substrate-ai/core` | Transport-agnostic primitives — event bus, adapters, cost tracker, telemetry, config schema |
+| `@substrate-ai/sdlc` | SDLC orchestration — phase handlers, graph orchestrator, verification pipeline, learning loop |
+| `@substrate-ai/factory` | Graph engine, scenario runner, convergence loop, digital twin helpers, LLM client |
+
+All four packages release in lockstep on every `v*` tag push — pick a version and mix any combination:
+
+```bash
+npm install @substrate-ai/core @substrate-ai/factory
+```
+
+```typescript
+import { createEventBus } from '@substrate-ai/core'
+import { parseGraph, createGraphExecutor } from '@substrate-ai/factory'
+import { createSdlcEventBridge } from '@substrate-ai/sdlc'
+
+// Compose these primitives in your own orchestrator.
+```
+
+TypeScript declaration files are bundled in each package. Published tarballs carry an npm provenance attestation you can verify with `npm audit signatures`.
+
 ## Configuration
 
 Substrate reads configuration from `.substrate/config.yaml` in your project root. Run `substrate init` to generate defaults.
@@ -461,17 +488,11 @@ git clone https://github.com/johnplanow/substrate.git
 cd substrate
 npm install
 npm run build
-npm test
+npm run test:fast   # ~50s unit suite for iteration
+npm test            # full suite with coverage — run before merging
 ```
 
-### Monorepo Structure
-
-| Package | Purpose |
-|---------|---------|
-| `substrate-ai` | CLI entry point, pipeline orchestrators, methodology packs |
-| `@substrate-ai/core` | Transport-agnostic infrastructure — adapters, dispatch, routing, persistence, telemetry |
-| `@substrate-ai/sdlc` | SDLC graph orchestrator, DOT pipeline topology, event handlers |
-| `@substrate-ai/factory` | Software factory — scenarios, convergence, direct API backend, digital twins |
+The repo is an npm workspaces monorepo — see [Using as a Library](#using-as-a-library) for the four packages it publishes. Release mechanics live in `scripts/sync-workspace-versions.mjs` and `.github/workflows/publish.yml`: every `v*` tag push syncs the workspace package versions to the root, dry-runs all four tarballs, and publishes via npm OIDC trusted publishing.
 
 ## License
 

package/dist/cli/index.js

@@ -4,7 +4,7 @@ import { createLogger } from "../logger-KeHncl-f.js";
 import { createEventBus } from "../helpers-CElYrONe.js";
 import { AdapterRegistry, BudgetConfigSchema, CURRENT_CONFIG_FORMAT_VERSION, CURRENT_TASK_GRAPH_VERSION, ConfigError, CostTrackerConfigSchema, DEFAULT_CONFIG, DoltClient, DoltNotInstalled, GlobalSettingsSchema, IngestionServer, MonitorDatabaseImpl, OPERATIONAL_FINDING, PartialGlobalSettingsSchema, PartialProviderConfigSchema, ProvidersSchema, RoutingRecommender, STORY_METRICS, TelemetryConfigSchema, addTokenUsage, aggregateTokenUsageForRun, checkDoltInstalled, compareRunMetrics, createAmendmentRun, createConfigSystem, createDecision, createDoltClient, createPipelineRun, getActiveDecisions, getAllCostEntriesFiltered, getBaselineRunMetrics, getDecisionsByCategory, getDecisionsByPhaseForRun, getLatestCompletedRun, getLatestRun, getPipelineRunById, getPlanningCostTotal, getRetryableEscalations, getRunMetrics, getRunningPipelineRuns, getSessionCostSummary, getSessionCostSummaryFiltered, getStoryMetricsForRun, getTokenUsageSummary, incrementRunRestarts, initSchema, initializeDolt, listRunMetrics, loadParentRunDecisions, supersedeDecision, tagRunAsBaseline, updatePipelineRun } from "../dist-sNh9XQ6V.js";
 import "../adapter-registry-DXLMTmfD.js";
-import { 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, registerExportCommand, registerFactoryCommand, registerRunCommand, registerScenariosCommand, resolveStoryKeys, runAnalysisPhase, runPlanningPhase, runSolutioningPhase, validateStopAfterFromConflict } from "../run-BUKozIHS.js";
+import { 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, registerExportCommand, registerFactoryCommand, registerRunCommand, registerScenariosCommand, resolveStoryKeys, runAnalysisPhase, runPlanningPhase, runSolutioningPhase, validateStopAfterFromConflict } from "../run-dCGeboq9.js";
 import "../errors-RupuC-ES.js";
 import "../routing-CcBOCuC9.js";
 import "../decisions-C0pz9Clx.js";
@@ -5191,7 +5191,7 @@ async function runSupervisorAction(options, deps = {}) {
 								await initSchema(expAdapter);
 								const { runRunAction: runPipeline } = await import(
 									/* @vite-ignore */
-									"../run-BwMDKH66.js"
+									"../run-D41_ttBq.js"
 );
 								const runStoryFn = async (opts) => {
 									const exitCode = await runPipeline({

package/dist/{run-BwMDKH66.js → run-D41_ttBq.js}

@@ -2,7 +2,7 @@ import "./health-DrZiqv4h.js";
 import "./logger-KeHncl-f.js";
 import "./helpers-CElYrONe.js";
 import "./dist-sNh9XQ6V.js";
-import { normalizeGraphSummaryToStatus, registerRunCommand, resolveMaxReviewCycles, runRunAction, wireNdjsonEmitter } from "./run-BUKozIHS.js";
+import { normalizeGraphSummaryToStatus, registerRunCommand, resolveMaxReviewCycles, runRunAction, wireNdjsonEmitter } from "./run-dCGeboq9.js";
 import "./routing-CcBOCuC9.js";
 import "./decisions-C0pz9Clx.js";
 

package/dist/{run-BUKozIHS.js → run-dCGeboq9.js}

@@ -6501,6 +6501,142 @@ var TrivialOutputCheck = class {
 	}
 };
 
+//#endregion
+//#region packages/sdlc/dist/verification/checks/acceptance-criteria-evidence-check.js
+/**
+* AcceptanceCriteriaEvidenceCheck.
+*
+* Tier A verification check that compares a story's declared acceptance
+* criteria against structured dev-story output. The check is intentionally
+* deterministic: no LLM calls, no shell commands, no repository inspection.
+*/
+const EXPLICIT_AC_REF = /\bAC\s*:?\s*#?\s*(\d+)\b/gi;
+const NUMBERED_CRITERION = /^\s*(?:[-*]\s*)?(?:\[[ xX]\]\s*)?(\d+)[.)]\s+\S/;
+function normalizeAcId(value) {
+	const parsed = Number.parseInt(value, 10);
+	if (!Number.isFinite(parsed) || parsed <= 0) return void 0;
+	return `AC${parsed}`;
+}
+function sortAcIds(ids) {
+	return Array.from(ids).sort((a, b) => {
+		const aNum = Number.parseInt(a.replace(/^AC/i, ""), 10);
+		const bNum = Number.parseInt(b.replace(/^AC/i, ""), 10);
+		return aNum - bNum;
+	});
+}
+function addExplicitAcRefs(text, ids) {
+	EXPLICIT_AC_REF.lastIndex = 0;
+	let match$1;
+	while ((match$1 = EXPLICIT_AC_REF.exec(text)) !== null) {
+		const id = normalizeAcId(match$1[1] ?? "");
+		if (id !== void 0) ids.add(id);
+	}
+}
+function extractAcceptanceSection(storyContent) {
+	const lines = storyContent.split(/\r?\n/);
+	const start = lines.findIndex((line) => /^##\s+Acceptance Criteria\s*$/i.test(line.trim()));
+	if (start === -1) return void 0;
+	let end = lines.length;
+	for (let i = start + 1; i < lines.length; i += 1) if (/^##\s+\S/.test(lines[i] ?? "")) {
+		end = i;
+		break;
+	}
+	return lines.slice(start + 1, end).join("\n");
+}
+/**
+* Extract normalized AC ids from story markdown.
+*
+* Supports the BMAD default format (`### AC1:`), explicit references such as
+* `AC: #1`, and plain numbered criteria inside the Acceptance Criteria section.
+*/
+function extractAcceptanceCriteriaIds(storyContent) {
+	const ids = new Set();
+	const acceptanceSection = extractAcceptanceSection(storyContent);
+	const textToScan = acceptanceSection ?? storyContent;
+	addExplicitAcRefs(textToScan, ids);
+	if (acceptanceSection !== void 0) for (const line of acceptanceSection.split(/\r?\n/)) {
+		const match$1 = line.match(NUMBERED_CRITERION);
+		if (match$1?.[1] !== void 0) {
+			const id = normalizeAcId(match$1[1]);
+			if (id !== void 0) ids.add(id);
+		}
+	}
+	return sortAcIds(ids);
+}
+function extractClaimedAcceptanceCriteriaIds(values) {
+	const ids = new Set();
+	for (const value of values ?? []) {
+		addExplicitAcRefs(value, ids);
+		const bareNumber = value.trim().match(/^#?(\d+)\b/);
+		if (bareNumber?.[1] !== void 0) {
+			const id = normalizeAcId(bareNumber[1]);
+			if (id !== void 0) ids.add(id);
+		}
+	}
+	return sortAcIds(ids);
+}
+function normalizeTestOutcome(value) {
+	if (value === void 0) return void 0;
+	return value.toLowerCase().includes("fail") ? "fail" : "pass";
+}
+function formatIds(ids) {
+	return ids.join(", ");
+}
+var AcceptanceCriteriaEvidenceCheck = class {
+	name = "acceptance-criteria-evidence";
+	tier = "A";
+	async run(context) {
+		const start = Date.now();
+		const storyContent = context.storyContent?.trim();
+		if (!storyContent) return {
+			status: "warn",
+			details: "acceptance-criteria-evidence: story content unavailable - skipping AC evidence check",
+			duration_ms: Date.now() - start
+		};
+		const expectedIds = extractAcceptanceCriteriaIds(storyContent);
+		if (expectedIds.length === 0) return {
+			status: "warn",
+			details: "acceptance-criteria-evidence: no numbered acceptance criteria found in story",
+			duration_ms: Date.now() - start
+		};
+		const devResult = context.devStoryResult;
+		if (devResult === void 0) return {
+			status: "warn",
+			details: `acceptance-criteria-evidence: dev-story result unavailable for ${formatIds(expectedIds)}`,
+			duration_ms: Date.now() - start
+		};
+		const acFailures = devResult.ac_failures ?? [];
+		if (acFailures.length > 0) return {
+			status: "fail",
+			details: `acceptance-criteria-evidence: dev-story reported AC failures: ${acFailures.join("; ")}`,
+			duration_ms: Date.now() - start
+		};
+		const testOutcome = normalizeTestOutcome(devResult.tests);
+		if (testOutcome === "fail") return {
+			status: "fail",
+			details: "acceptance-criteria-evidence: dev-story reported failing tests",
+			duration_ms: Date.now() - start
+		};
+		const claimedIds = new Set(extractClaimedAcceptanceCriteriaIds(devResult.ac_met));
+		const missingIds = expectedIds.filter((id) => !claimedIds.has(id));
+		if (missingIds.length > 0) return {
+			status: "fail",
+			details: `acceptance-criteria-evidence: missing dev-story AC evidence for ${formatIds(missingIds)}; expected ${formatIds(expectedIds)}, claimed ${formatIds(sortAcIds(claimedIds)) || "none"}`,
+			duration_ms: Date.now() - start
+		};
+		if (testOutcome === void 0) return {
+			status: "warn",
+			details: `acceptance-criteria-evidence: AC evidence covers ${formatIds(expectedIds)} but test outcome is unavailable`,
+			duration_ms: Date.now() - start
+		};
+		return {
+			status: "pass",
+			details: `acceptance-criteria-evidence: AC evidence covers ${formatIds(expectedIds)}; tests=${testOutcome}`,
+			duration_ms: Date.now() - start
+		};
+	}
+};
+
 //#endregion
 //#region packages/sdlc/dist/verification/checks/build-check.js
 /** Hard timeout for the build command in milliseconds (FR-V11). */
@@ -6705,7 +6841,8 @@ var VerificationPipeline = class {
 * Canonical Tier A check order (architecture section 3.5):
 *   1. PhantomReviewCheck — story 51-2  (runs first: unreviewed stories skipped)
 *   2. TrivialOutputCheck — story 51-3
-*   3. BuildCheck         — story 51-4
+*   3. AcceptanceCriteriaEvidenceCheck
+*   4. BuildCheck         — story 51-4
 *
 * @param bus    Typed event bus for verification events.
 * @param config Optional config (used to forward threshold to TrivialOutputCheck).
@@ -6714,6 +6851,7 @@ function createDefaultVerificationPipeline(bus, config) {
 	const checks = [
 		new PhantomReviewCheck(),
 		new TrivialOutputCheck(config),
+		new AcceptanceCriteriaEvidenceCheck(),
 		new BuildCheck()
 	];
 	return new VerificationPipeline(bus, checks);
@@ -10764,6 +10902,8 @@ function assembleVerificationContext(opts) {
 		commitSha,
 		timeout: 6e4,
 		reviewResult: opts.reviewResult,
+		storyContent: opts.storyContent,
+		devStoryResult: opts.devStoryResult,
 		outputTokenCount: opts.outputTokenCount
 	};
 }
@@ -12597,6 +12737,37 @@ function createImplementationOrchestrator(deps) {
 		const batchFileGroups = [];
 		let devStoryWasSuccess = false;
 		let devOutputTokenCount;
+		let storyContentForVerification;
+		let devStorySignals;
+		const normalizeDevStorySignals = (result) => {
+			if (result == null) return void 0;
+			return {
+				result: result.result,
+				ac_met: result.ac_met ?? [],
+				ac_failures: result.ac_failures ?? [],
+				files_modified: result.files_modified ?? [],
+				tests: result.tests
+			};
+		};
+		const replaceDevStorySignals = (result) => {
+			const normalized = normalizeDevStorySignals(result);
+			if (normalized !== void 0) devStorySignals = normalized;
+		};
+		const mergeDevStorySignals = (result) => {
+			const normalized = normalizeDevStorySignals(result);
+			if (normalized === void 0) return;
+			if (devStorySignals === void 0) {
+				devStorySignals = normalized;
+				return;
+			}
+			devStorySignals = {
+				result: devStorySignals.result === "failed" || normalized.result === "failed" ? "failed" : normalized.result ?? devStorySignals.result,
+				ac_met: Array.from(new Set([...devStorySignals.ac_met ?? [], ...normalized.ac_met ?? []])),
+				ac_failures: Array.from(new Set([...devStorySignals.ac_failures ?? [], ...normalized.ac_failures ?? []])),
+				files_modified: Array.from(new Set([...devStorySignals.files_modified ?? [], ...normalized.files_modified ?? []])),
+				tests: devStorySignals.tests === "fail" || normalized.tests === "fail" ? "fail" : normalized.tests ?? devStorySignals.tests
+			};
+		};
 		let baselineHeadSha;
 		try {
 			baselineHeadSha = execSync("git rev-parse HEAD", {
@@ -12614,6 +12785,7 @@ function createImplementationOrchestrator(deps) {
 			let storyContentForAnalysis = "";
 			try {
 				storyContentForAnalysis = await readFile$1(storyFilePath ?? "", "utf-8");
+				storyContentForVerification = storyContentForAnalysis;
 			} catch (err) {
 				logger$24.error({
 					storyKey,
@@ -12681,6 +12853,7 @@ function createImplementationOrchestrator(deps) {
 					}
 					const batchDurationMs = Date.now() - batchStartMs;
 					const batchFilesModified = batchResult.files_modified ?? [];
+					mergeDevStorySignals(batchResult);
 					const batchMetrics = {
 						batchIndex: batch.batchIndex,
 						taskIds: batch.taskIds,
@@ -12950,6 +13123,7 @@ function createImplementationOrchestrator(deps) {
 						return;
 					}
 					const retryParsed = checkpointRetryResult.parsed;
+					replaceDevStorySignals(retryParsed);
 					devFilesModified = retryParsed?.files_modified ?? checkGitDiffFiles(projectRoot ?? process.cwd());
 					if (checkpointRetryResult.status === "completed" && retryParsed?.result === "success") devStoryWasSuccess = true;
 					else logger$24.warn({
@@ -12958,22 +13132,25 @@ function createImplementationOrchestrator(deps) {
 					}, "Checkpoint retry completed with failure — proceeding to code review");
 					checkpointHandled = true;
 				}
-				if (!checkpointHandled) if (devResult.result === "success") devStoryWasSuccess = true;
-				else {
-					logger$24.warn({
-						storyKey,
-						error: devResult.error,
-						filesModified: devFilesModified.length
-					}, "Dev-story reported failure, proceeding to code review");
-					if (!devResult.error?.startsWith("dispatch_timeout")) {
+				if (!checkpointHandled) {
+					replaceDevStorySignals(devResult);
+					if (devResult.result === "success") devStoryWasSuccess = true;
+					else {
 						logger$24.warn({
 							storyKey,
-							error: devResult.error
-						}, "Agent process failure (non-timeout) — story will proceed to code review with partial work");
-						eventBus.emit("orchestrator:story-warn", {
-							storyKey,
-							msg: "agent process failure (non-timeout)"
-						});
+							error: devResult.error,
+							filesModified: devFilesModified.length
+						}, "Dev-story reported failure, proceeding to code review");
+						if (!devResult.error?.startsWith("dispatch_timeout")) {
+							logger$24.warn({
+								storyKey,
+								error: devResult.error
+							}, "Agent process failure (non-timeout) — story will proceed to code review with partial work");
+							eventBus.emit("orchestrator:story-warn", {
+								storyKey,
+								msg: "agent process failure (non-timeout)"
+							});
+						}
 					}
 				}
 			}
@@ -13551,6 +13728,8 @@ function createImplementationOrchestrator(deps) {
 						storyKey,
 						workingDir: projectRoot ?? process.cwd(),
 						reviewResult: latestReviewSignals,
+						storyContent: storyContentForVerification,
+						devStoryResult: devStorySignals,
 						outputTokenCount: devOutputTokenCount
 					});
 					const verifSummary = await verificationPipeline.run(verifContext, "A");
@@ -13791,6 +13970,37 @@ function createImplementationOrchestrator(deps) {
 					}, "Auto-approve fix dispatch failed — approving anyway (issues were minor)");
 				}
 				endPhase(storyKey, "code-review");
+				if (config.skipVerification !== true) {
+					const latestReviewSignals = reviewResult != null ? {
+						dispatchFailed: reviewResult.dispatchFailed,
+						error: reviewResult.error,
+						rawOutput: reviewResult.rawOutput
+					} : void 0;
+					const verifContext = assembleVerificationContext({
+						storyKey,
+						workingDir: projectRoot ?? process.cwd(),
+						reviewResult: latestReviewSignals,
+						storyContent: storyContentForVerification,
+						devStoryResult: devStorySignals,
+						outputTokenCount: devOutputTokenCount
+					});
+					const verifSummary = await verificationPipeline.run(verifContext, "A");
+					verificationStore.set(storyKey, verifSummary);
+					persistVerificationResult(storyKey, verifSummary, runManifest);
+					if (verifSummary.status === "fail") {
+						updateStory(storyKey, {
+							phase: "VERIFICATION_FAILED",
+							completedAt: new Date().toISOString()
+						});
+						persistStoryState(storyKey, _stories.get(storyKey)).catch((err) => logger$24.warn({
+							err,
+							storyKey
+						}, "StateStore write failed after verification-failed"));
+						await writeStoryMetricsBestEffort(storyKey, "verification-failed", finalReviewCycles);
+						await persistState();
+						return;
+					}
+				}
 				eventBus.emit("story:auto-approved", {
 					storyKey,
 					verdict,
@@ -14038,6 +14248,7 @@ function createImplementationOrchestrator(deps) {
 						exitCode: fixResult.exitCode
 					}, "Fix dispatch failed");
 				}
+				if (isMajorRework) replaceDevStorySignals(fixResult.parsed);
 			} catch (err) {
 				logger$24.warn({
 					storyKey,
@@ -43077,4 +43288,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-BUKozIHS.js.map
+//# sourceMappingURL=run-dCGeboq9.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "substrate-ai",
-  "version": "0.19.53",
+  "version": "0.20.0",
   "description": "Substrate — multi-agent orchestration daemon for AI coding agents",
   "type": "module",
   "license": "MIT",
@@ -65,7 +65,8 @@
     "typecheck": "tsc --noEmit",
     "typecheck:gate": "tsc --noEmit -p tsconfig.typecheck.json",
     "clean": "rm -rf dist",
-    "substrate:dev": "node dist/cli/index.js"
+    "substrate:dev": "node dist/cli/index.js",
+    "version:sync": "node scripts/sync-workspace-versions.mjs"
   },
   "dependencies": {
     "bmad-method": "^6.2.2",