substrate-ai 0.21.1 → 0.21.3

package/README.md

@@ -157,11 +157,21 @@ Stories run in parallel across your available agents, each in its own git worktr
 
 #### Per-Story Worktree Lifecycle
 
-Each dispatched story runs in a dedicated git worktree at `.substrate-worktrees/story-<key>` on branch `substrate/story-<key>`. After verification produces a SHIP_IT verdict, **substrate auto-commits the dispatched agent's output** to the story branch with a `feat(story-N-M): <title>` message (v0.20.86+ — substrate does NOT rely on the agent running `git commit` itself, since empirical audit found agents don't reliably do so). Pre-commit hooks run on the substrate commit. The branch then merges to the base branch (typically main) and the worktree is removed. If the commit fails (e.g., a pre-commit hook rejects) or the agent's run produced no committable changes, the story escalates with `dev-story-commit-failed` or `dev-story-no-commit` instead of merging an empty branch. After a verification failure, the worktree and branch are preserved so you can inspect the partial implementation via `substrate reconcile-from-disk`. Use `--no-worktree` if your project does not support worktrees (e.g., submodules, bare repos).
+Each dispatched story runs in a dedicated git worktree on branch `substrate/story-<key>`. **Since v0.20.149 the worktree base is external by default** — `~/.substrate/worktrees/<projectname>-<hash8>/<key>/`, outside your repo; set `worktree.base: in-repo` in `.substrate/config.yaml` to restore the legacy `.substrate-worktrees/<key>/` path. **Commit-first (v0.20.139+):** substrate auto-commits the agent's output to the story branch (`feat(story-N-M): <title>`) at **dev-story completion — before review** — so the branch is always the durable copy of the work; failure paths add `wip(story-<key>)` checkpoints. Pre-commit hooks run on the substrate commit. If the commit fails (a hook rejects) or the run produced no committable changes, the story escalates `dev-story-commit-failed` / `dev-story-no-commit`. How the verified branch integrates is controlled by [finalization mode](#finalization). After a verification failure, the worktree and branch are preserved for inspection via `substrate reconcile-from-disk`. Use `--no-worktree` for projects that don't support worktrees (submodules, bare repos).
+
+#### Finalization
+
+`finalization.mode` in `.substrate/config.yaml` (or `--finalization <mode>` per run) decides how a verified story's branch integrates:
+
+- **`merge`** (default) — local merge into the run's start branch, **fast-forward-only by default** (a base that moved during the run escalates `ff-only-merge-not-possible` rather than fabricating a merge commit). `finalization.merge_strategy: three-way` enables merge commits and is **required for concurrent multi-story runs**.
+- **`branch`** — nothing self-merges; the `substrate/story-<key>` branch is the deliverable (safe for brownfield repos).
+- **`pr`** — branch + push + `gh pr create` (one PR per story); degrades to `branch` on push/gh failure, never blocks.
+
+NDJSON lifecycle events `story:committed` → (`story:merged`) → `story:finalized` report the outcome, and `substrate report` lists any unmerged deliverable branches.
 
 ### Verification Pipeline
 
-Six gates run after code review. Each can pass, warn, or fail; failures block SHIP_IT.
+A Tier-A gate sequence runs after code review. Each gate can pass, warn, or fail; failures block SHIP_IT.
 
 | Gate | What it catches |
 |---|---|
@@ -169,6 +179,10 @@ Six gates run after code review. Each can pass, warn, or fail; failures block SH
 | **trivial-output** | Output token count below threshold — likely no real work done |
 | **acceptance-criteria-evidence** | Each AC has demonstrable evidence in dev-story signals (files modified, tests added) |
 | **build** | Project build succeeds against the dev's worktree |
+| **test-suite** | Runs the project's real test command (from the trusted main-tree profile) and fails on a red suite; rejects exit-code-laundering wrappers (`… \|\| true`) |
+| **scope-contamination** | Foreign-language sources / foreign toolchain manifests / build-output droppings vs the project's declared languages |
+| **test-mutation** | Warns when a story modifies or deletes pre-existing tracked test files (reward-hack tripwire), including committed and renamed test files |
+| **net-new-implementation** | A "success" story whose diff is artifact-only, an empty stub, or a whitespace-only edit escalates `no-implementation` |
 | **runtime-probes** | Each declared `## Runtime Probes` section probe runs successfully against real or sandboxed state. Includes auto-detection for error-shape envelopes (`{"isError": true}`, `{"status": "error"}`) and production-trigger requirements for event-driven ACs. Frontmatter `external_state_dependencies` declarations hard-gate when probes section is missing. |
 | **source-ac-fidelity** | AC text in source epic appears verbatim in story artifact (paths, MUST clauses, hard contracts). Includes 4 context-aware heuristics: negation (paths the AC says NOT to deliver), dependency-context (peer packages the implementation imports), operational-path (system install destinations like `.git/hooks/`), and alternative-option groups. |
 
@@ -501,6 +515,20 @@ token_ceilings:
 # Optional: dispatch timeout overrides (ms)
 dispatch_timeouts:
   dev-story: 1800000              # 30 min
+
+# Optional: how verified stories integrate (v0.20.147+)
+finalization:
+  mode: merge                     # merge (default) | branch | pr
+  merge_strategy: ff-only         # ff-only (default) | three-way (needed for concurrent multi-story)
+  # epic_gate_command: "uv run pytest"   # must pass before the last story of an epic integrates
+
+# Optional: per-story worktree location (v0.20.149+)
+worktree:
+  base: external                  # external (default: ~/.substrate/worktrees/...) | in-repo
+
+# Optional: spawned-agent permission profile (v0.20.152+)
+dispatch:
+  permission_profile: skip        # skip (default) | scoped (per-worktree settings; accident-mitigation, not a security boundary)
 ```
 
 ### Configuration Files
@@ -527,7 +555,7 @@ substrate init
 
 Without Dolt, all functionality works except for: `substrate diff`, `substrate history`, persistent OTEL observability tables, and context engineering repo-map storage.
 
-**On-disk operator surface:** Each pipeline run creates per-story worktrees under `.substrate-worktrees/story-<key>/`. Successful stories are merged to main and their worktrees removed. Failed or escalated stories preserve their worktrees for operator inspection via `substrate reconcile-from-disk`.
+**On-disk operator surface:** Each pipeline run creates a per-story worktree — by default under `~/.substrate/worktrees/<project>-<hash>/<key>/` (external base; `worktree.base: in-repo` restores `.substrate-worktrees/<key>/`). Verified stories integrate per the [finalization mode](#finalization) and their worktrees are removed; failed or escalated stories preserve their worktree and branch for operator inspection via `substrate reconcile-from-disk`.
 
 ## CLI Command Reference
 
@@ -551,6 +579,7 @@ These commands are typically invoked by your AI assistant during pipeline operat
 | `substrate run --max-review-cycles <n>` | Cycles per story (default 2; use 3 for migrations / interface extraction) |
 | `substrate run --skip-verification` | Skip post-dispatch verification (use sparingly) |
 | `substrate run --no-worktree` | Disable per-story git worktrees (use for submodule repos or bare repos that don't support worktrees) |
+| `substrate run --finalization <mode>` | How verified work integrates: `merge` (default) / `branch` / `pr` — see [Finalization](#finalization) |
 | `substrate run --help-agent` | Print agent instruction prompt fragment |
 | `substrate resume` | Resume an interrupted run |
 | `substrate cancel` | Cancel a running pipeline |

package/dist/adapter-registry-BSig1zpx.js

@@ -0,0 +1,4 @@
+import { AdapterRegistry } from "./dist-CpnLJuVw.js";
+import "./adapter-registry-DXLMTmfD.js";
+
+export { AdapterRegistry };

package/dist/cli/index.js

@@ -1,20 +1,20 @@
 #!/usr/bin/env node
-import { FileKvStore, SUBSTRATE_OWNED_SETTINGS_KEYS, VALID_PHASES, buildPipelineStatusOutput, createDatabaseAdapter, createDoltOperatorReader, findPackageRoot, formatOutput, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getAllDescendantPids, getAutoHealthData, getSubstrateDefaultSettings, inspectProcessTree, parseDbTimestampAsUtc, registerHealthCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion } from "../health-Cfkv6XoQ.js";
+import { FileKvStore, SUBSTRATE_OWNED_SETTINGS_KEYS, VALID_PHASES, buildPipelineStatusOutput, createDatabaseAdapter, createDoltOperatorReader, findPackageRoot, formatOutput, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getAllDescendantPids, getAutoHealthData, getSubstrateDefaultSettings, inspectProcessTree, parseDbTimestampAsUtc, registerHealthCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion } from "../health-Dnzblihr.js";
 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, InMemoryDatabaseAdapter, IngestionServer, MonitorDatabaseImpl, OPERATIONAL_FINDING, PartialGlobalSettingsSchema, PartialProviderConfigSchema, ProvidersSchema, RoutingRecommender, STORY_METRICS, TelemetryConfigSchema, addTokenUsage, aggregateTokenUsageForRun, checkDoltInstalled, compareRunMetrics, createAmendmentRun, createConfigSystem, createDecision, createGitWorktreeManager, createPipelineRun, createStderrLogger, getActiveDecisions, getAllCostEntriesFiltered, getBaselineRunMetrics, getDecisionsByCategory, getDecisionsByPhaseForRun, getLatestCompletedRun, getLatestRun, getPipelineRunById, getPlanningCostTotal, getRetryableEscalations, getRunMetrics, getRunningPipelineRuns, getSessionCostSummary, getSessionCostSummaryFiltered, getStoryMetricsForRun, getTokenUsageSummary, incrementRunRestarts, initSchema, initWorkGraphSchema, initializeDolt, listRunMetrics, loadParentRunDecisions, supersedeDecision, swallowDebug, tagRunAsBaseline, updatePipelineRun } from "../dist-BkhYgJWo.js";
+import { AdapterRegistry, BudgetConfigSchema, CURRENT_CONFIG_FORMAT_VERSION, CURRENT_TASK_GRAPH_VERSION, ConfigError, CostTrackerConfigSchema, DEFAULT_CONFIG, DoltClient, DoltNotInstalled, GlobalSettingsSchema, InMemoryDatabaseAdapter, IngestionServer, MonitorDatabaseImpl, OPERATIONAL_FINDING, PartialGlobalSettingsSchema, PartialProviderConfigSchema, ProvidersSchema, RoutingRecommender, STORY_METRICS, TelemetryConfigSchema, addTokenUsage, aggregateTokenUsageForRun, checkDoltInstalled, compareRunMetrics, createAmendmentRun, createConfigSystem, createDecision, createGitWorktreeManager, createPipelineRun, createStderrLogger, getActiveDecisions, getAllCostEntriesFiltered, getBaselineRunMetrics, getDecisionsByCategory, getDecisionsByPhaseForRun, getLatestCompletedRun, getLatestRun, getPipelineRunById, getPlanningCostTotal, getRetryableEscalations, getRunMetrics, getRunningPipelineRuns, getSessionCostSummary, getSessionCostSummaryFiltered, getStoryMetricsForRun, getTokenUsageSummary, incrementRunRestarts, initSchema, initWorkGraphSchema, initializeDolt, listRunMetrics, loadParentRunDecisions, supersedeDecision, swallowDebug, tagRunAsBaseline, updatePipelineRun } from "../dist-CpnLJuVw.js";
 import "../adapter-registry-DXLMTmfD.js";
-import { RunManifest, SupervisorLock, ZERO_FINDINGS_BY_AUTHOR, ZERO_FINDING_COUNTS, ZERO_PROBE_AUTHOR_METRICS, aggregateProbeAuthorMetrics, parseRuntimeProbes, readCurrentRunId, resolveMainRepoRoot, resolveRunManifest, rollupFindingCounts, rollupFindingsByAuthor, rollupProbeAuthorByClass, rollupProbeAuthorMetrics, runAcTraceabilityCheck } from "../manifest-read-BhNRIiqm.js";
-import { AdapterTelemetryPersistence, AppError, DoltRepoMapMetaRepository, DoltSymbolRepository, ERR_REPO_MAP_STORAGE_WRITE, EpicIngester, GLOBSTAR, GitClient, GrammarLoader, Minimatch, Minipass, RepoMapInjector, RepoMapModule, RepoMapQueryEngine, RepoMapStorage, SymbolParser, createContextCompiler, createDispatcher, createEventEmitter, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, createTelemetryAdvisor, escape, formatPhaseCompletionSummary, getFactoryRunSummaries, getScenarioResultsForRun, getTwinRunsForRun, listGraphRuns, registerExportCommand, registerFactoryCommand, registerRunCommand, registerScenariosCommand, resolveStoryKeys, runAnalysisPhase, runPlanningPhase, runProbeAuthor, runSolutioningPhase, unescape, validateStopAfterFromConflict } from "../run-JrEnvaB0.js";
-import "../errors-C7pY6_yQ.js";
+import { JOURNEY_DEFERRALS_PATH, JOURNEY_REGISTRY_PATH, RunManifest, SupervisorLock, ZERO_FINDINGS_BY_AUTHOR, ZERO_FINDING_COUNTS, ZERO_PROBE_AUTHOR_METRICS, aggregateProbeAuthorMetrics, loadJourneyRegistryFromFile, loadJourneyRegistryFromTrustedTree, parseJourneyDeferrals, parseRuntimeProbes, readCurrentRunId, resolveMainRepoRoot, resolveRunManifest, rollupFindingCounts, rollupFindingsByAuthor, rollupProbeAuthorByClass, rollupProbeAuthorMetrics, runAcTraceabilityCheck } from "../manifest-read-B3gE46DX.js";
+import { AdapterTelemetryPersistence, AppError, DoltRepoMapMetaRepository, DoltSymbolRepository, ERR_REPO_MAP_STORAGE_WRITE, EpicIngester, GLOBSTAR, GitClient, GrammarLoader, Minimatch, Minipass, RepoMapInjector, RepoMapModule, RepoMapQueryEngine, RepoMapStorage, SymbolParser, createContextCompiler, createDispatcher, createEventEmitter, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, createTelemetryAdvisor, escape, formatPhaseCompletionSummary, getFactoryRunSummaries, getScenarioResultsForRun, getTwinRunsForRun, listGraphRuns, registerExportCommand, registerFactoryCommand, registerRunCommand, registerScenariosCommand, resolveStoryKeys, runAnalysisPhase, runPlanningPhase, runProbeAuthor, runSolutioningPhase, unescape, validateStopAfterFromConflict } from "../run-ZxFHQyE_.js";
+import "../errors-8tVEwG6v.js";
 import "../routing-DFxoKHDt.js";
 import { WorkGraphRepository } from "../work-graph-repository-DZyJv5pV.js";
 import "../decisions-CzSIEeGP.js";
 import "../decision-router-BAPpON_C.js";
-import "../interactive-prompt-BBfPSxyJ.js";
+import "../interactive-prompt-BM5RaXYG.js";
 import "../recovery-engine-BKGBeBnW.js";
 import "../version-manager-impl-qFBiO4Eh.js";
-import { registerUpgradeCommand } from "../upgrade-S1oUMH5P.js";
+import { registerUpgradeCommand } from "../upgrade-BUSzXgnd.js";
 import { Command } from "commander";
 import { fileURLToPath } from "url";
 import { dirname, join, resolve } from "path";
@@ -25,11 +25,11 @@ import * as actualFS from "node:fs";
 import { existsSync, promises, readFileSync, writeFileSync } from "node:fs";
 import { execFile, spawnSync } from "node:child_process";
 import * as path$1 from "node:path";
-import { basename as basename$1, join as join$1, posix, relative, resolve as resolve$1, win32 } from "node:path";
+import { basename as basename$1, dirname as dirname$1, join as join$1, posix, relative, resolve as resolve$1, win32 } from "node:path";
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import * as fs from "node:fs/promises";
-import { lstat, readFile as readFile$1, readdir as readdir$1, readlink, realpath } from "node:fs/promises";
+import { lstat, mkdir as mkdir$1, readFile as readFile$1, readdir as readdir$1, readlink, realpath, writeFile as writeFile$1 } from "node:fs/promises";
 import { chmodSync, cpSync, existsSync as existsSync$1, lstatSync, mkdirSync as mkdirSync$1, readFileSync as readFileSync$1, readdir as readdir$2, readdirSync as readdirSync$1, readlinkSync, realpathSync as realpathSync$1, rmSync as rmSync$1, statSync as statSync$1, unlinkSync as unlinkSync$1, writeFileSync as writeFileSync$1 } from "fs";
 import { homedir } from "os";
 import { createRequire } from "node:module";
@@ -699,6 +699,7 @@ const WHOLESALE_SUBSTRATE_IGNORES = new Set([
 const STAR = ".substrate/*";
 const CONFIG_NEGATION = "!.substrate/config.yaml";
 const PROFILE_NEGATION = "!.substrate/project-profile.yaml";
+const ACCEPTANCE_NEGATION = "!.substrate/acceptance/";
 const CODEX_PROMPTS = ".codex/prompts/";
 const CODEX_SKILLS = ".codex/skills/";
 /**
@@ -717,6 +718,9 @@ function computeSubstrateGitignore(existing) {
 	const profileNegIdx = trimmed.lastIndexOf(PROFILE_NEGATION);
 	const profileNegationEffective = profileNegIdx !== -1 && profileNegIdx > starIdx;
 	if (!profileNegationEffective) append.push(PROFILE_NEGATION);
+	const acceptanceNegIdx = trimmed.lastIndexOf(ACCEPTANCE_NEGATION);
+	const acceptanceNegationEffective = acceptanceNegIdx !== -1 && acceptanceNegIdx > starIdx;
+	if (!acceptanceNegationEffective) append.push(ACCEPTANCE_NEGATION);
 	if (!trimmed.includes(CODEX_PROMPTS)) append.push(CODEX_PROMPTS);
 	if (!trimmed.includes(CODEX_SKILLS)) append.push(CODEX_SKILLS);
 	let content = lines.join("\n");
@@ -7126,7 +7130,7 @@ async function runStatusAction(options) {
 			logger$15.debug({ err }, "Work graph query failed, continuing without work graph data");
 		}
 		if (run === void 0) {
-			const { inspectProcessTree: inspectProcessTree$1 } = await import("../health-Coh3BG8W.js");
+			const { inspectProcessTree: inspectProcessTree$1 } = await import("../health-bhMCTYDO.js");
 			const substrateDirPath = join(projectRoot, ".substrate");
 			const processInfo = inspectProcessTree$1({
 				projectRoot,
@@ -8074,7 +8078,7 @@ function defaultSupervisorDeps() {
 				if (cached === null) {
 					const { AdapterRegistry: AR } = await import(
 						/* @vite-ignore */
-						"../adapter-registry-CZn__637.js"
+						"../adapter-registry-BSig1zpx.js"
 );
 					cached = new AR();
 					await cached.discoverAndRegister();
@@ -8641,11 +8645,11 @@ async function runSupervisorAction(options, deps = {}) {
 						try {
 							const { createExperimenter } = await import(
 								/* @vite-ignore */
-								"../experimenter-BYqALeaE.js"
+								"../experimenter-C7swe92R.js"
 );
 							const { getLatestRun: getLatest } = await import(
 								/* @vite-ignore */
-								"../decisions-BPwrDCTx.js"
+								"../decisions-lxU14pNh.js"
 );
 							const expAdapter = createDatabaseAdapter({
 								backend: "auto",
@@ -8655,7 +8659,7 @@ async function runSupervisorAction(options, deps = {}) {
 								await initSchema(expAdapter);
 								const { runRunAction: runPipeline } = await import(
 									/* @vite-ignore */
-									"../run-CKM-5T34.js"
+									"../run-ChZFveqv.js"
 );
 								const runStoryFn = async (opts) => {
 									const exitCode = await runPipeline({
@@ -9180,7 +9184,7 @@ async function runMetricsAction(options) {
 			const routingConfigPath = join(dbDir, "routing.yml");
 			let routingConfig = null;
 			if (existsSync$1(routingConfigPath)) try {
-				const { loadModelRoutingConfig } = await import("../routing-BS-Q8_2L.js");
+				const { loadModelRoutingConfig } = await import("../routing-CGO2UZyA.js");
 				routingConfig = loadModelRoutingConfig(routingConfigPath);
 			} catch {}
 			if (routingConfig === null) routingConfig = {
@@ -12988,7 +12992,7 @@ function computeReportVerdict(summary, runStatus) {
 	if (summary.total === 0) return "NO STORIES RUN";
 	return "ALL PASSED";
 }
-function renderHuman(output, manifest) {
+function renderHuman$1(output, manifest) {
 	const lines = [];
 	const { runId, summary, stories, escalations, cost, duration, halts } = output;
 	const durationStr = duration.wall_clock_ms != null ? formatDurationMs(duration.wall_clock_ms) : "unknown";
@@ -13411,7 +13415,7 @@ async function runReportAction(options) {
 		output.ac_traceability = acTraceability;
 	}
 	if (outputFormat === "json") process.stdout.write(renderJson(output) + "\n");
-	else process.stdout.write(renderHuman(output, manifest));
+	else process.stdout.write(renderHuman$1(output, manifest));
 	return 0;
 }
 /**
@@ -13435,6 +13439,96 @@ function registerReportCommand(program, _version = "0.0.0", projectRoot = proces
 	});
 }
 
+//#endregion
+//#region src/cli/commands/acceptance.ts
+const ACCEPTANCE_EXIT_SUCCESS = 0;
+const ACCEPTANCE_EXIT_ERROR = 1;
+function summarizeRegistry(registry) {
+	const journeyCount = registry.journeys.length;
+	const endStateCount = registry.journeys.reduce((n, j) => n + j.end_states.length, 0);
+	const criticalCount = registry.journeys.filter((j) => j.criticality === "critical").length;
+	return `journey registry v${String(registry.version)}: ${String(journeyCount)} journeys (${String(criticalCount)} critical), ${String(endStateCount)} end-states`;
+}
+/** Render a load result for humans. Returns the exit code. */
+function renderHuman(result, source) {
+	switch (result.status) {
+		case "ok":
+			process.stdout.write(`OK — ${summarizeRegistry(result.registry)} (${source})\n`);
+			for (const journey of result.registry.journeys) process.stdout.write(`  ${journey.id} [${journey.criticality}] ${journey.title} — ${String(journey.end_states.length)} end-state(s), surfaces: ${journey.surfaces.join(", ")}\n`);
+			return ACCEPTANCE_EXIT_SUCCESS;
+		case "absent":
+			process.stdout.write(`NO REGISTRY — ${JOURNEY_REGISTRY_PATH} not found (${source}).\nAuthor it at planning time; see the acceptance-gate design brief for the schema.\n`);
+			return ACCEPTANCE_EXIT_ERROR;
+		case "invalid":
+			process.stdout.write(`INVALID — ${JOURNEY_REGISTRY_PATH} failed validation (${source}):\n`);
+			for (const issue of result.issues) process.stdout.write(`  ${issue.path}: ${issue.message}\n`);
+			return ACCEPTANCE_EXIT_ERROR;
+		case "error":
+			process.stdout.write(`ERROR — could not read the registry (${source}): ${result.message}\n`);
+			return ACCEPTANCE_EXIT_ERROR;
+	}
+}
+function registerAcceptanceCommand(program, version) {
+	const acceptanceCmd = program.command("acceptance").description("Acceptance Gate — journey registry tools (the missing sprint demo)");
+	acceptanceCmd.command("validate").description(`Lint ${JOURNEY_REGISTRY_PATH} with actionable, pathed errors`).option("--ref <ref>", "validate the COMMITTED registry at a git ref (trusted-tree read) instead of the working tree").option("--output-format <format>", "Output format: text (default) or json", "text").action(async (opts) => {
+		const projectRoot = process.cwd();
+		const source = opts.ref !== void 0 ? `committed @ ${opts.ref}` : "working tree";
+		const result = opts.ref !== void 0 ? await loadJourneyRegistryFromTrustedTree(projectRoot, opts.ref) : await loadJourneyRegistryFromFile(projectRoot);
+		if (opts.outputFormat === "json") {
+			const output = buildJsonOutput("substrate acceptance validate", {
+				source,
+				...result
+			}, version);
+			process.stdout.write(JSON.stringify(output, null, 2) + "\n");
+			process.exit(result.status === "ok" ? ACCEPTANCE_EXIT_SUCCESS : ACCEPTANCE_EXIT_ERROR);
+		}
+		process.exit(renderHuman(result, source));
+	});
+	acceptanceCmd.command("defer <journeyId>").description("Record an operator deferral for a journey — the coverage audit reports it `deferred` instead of unclaimed/unwalked. Writes to the working tree; COMMIT the file for the audit (trusted tree) to honor it.").requiredOption("--reason <text>", "why this journey is deferred (the operator ack is the point)").action(async (journeyId, opts) => {
+		const projectRoot = process.cwd();
+		const registry = await loadJourneyRegistryFromFile(projectRoot);
+		if (registry.status !== "ok") {
+			process.stdout.write(`cannot defer: journey registry is ${registry.status} at ${JOURNEY_REGISTRY_PATH} — fix it first (substrate acceptance validate)\n`);
+			process.exit(ACCEPTANCE_EXIT_ERROR);
+		}
+		if (!registry.registry.journeys.some((j) => j.id === journeyId)) {
+			process.stdout.write(`cannot defer: journey "${journeyId}" is not in the registry. Known ids: ${registry.registry.journeys.map((j) => j.id).join(", ")}\n`);
+			process.exit(ACCEPTANCE_EXIT_ERROR);
+		}
+		const deferralsPath = join$1(projectRoot, JOURNEY_DEFERRALS_PATH);
+		let existingContent = "";
+		try {
+			existingContent = await readFile$1(deferralsPath, "utf-8");
+		} catch {}
+		const existing = parseJourneyDeferrals(existingContent);
+		if (!existing.ok) {
+			process.stdout.write(`cannot defer: ${JOURNEY_DEFERRALS_PATH} is invalid:\n`);
+			for (const issue of existing.issues) process.stdout.write(`  ${issue.path}: ${issue.message}\n`);
+			process.exit(ACCEPTANCE_EXIT_ERROR);
+		}
+		if (existing.deferrals.some((d) => d.journey === journeyId)) {
+			process.stdout.write(`journey ${journeyId} is already deferred — no change\n`);
+			process.exit(ACCEPTANCE_EXIT_SUCCESS);
+		}
+		const deferrals = [...existing.deferrals, {
+			journey: journeyId,
+			reason: opts.reason,
+			deferred_at: new Date().toISOString()
+		}];
+		const rendered = "deferrals:\n" + deferrals.map((d) => `  - journey: ${d.journey}\n    reason: ${JSON.stringify(d.reason)}\n` + (d.deferred_at !== void 0 ? `    deferred_at: ${JSON.stringify(d.deferred_at)}\n` : "")).join("");
+		try {
+			await mkdir$1(dirname$1(deferralsPath), { recursive: true });
+			await writeFile$1(deferralsPath, rendered, "utf-8");
+		} catch (err) {
+			process.stdout.write(`failed to write ${JOURNEY_DEFERRALS_PATH}: ${String(err)}\n`);
+			process.exit(ACCEPTANCE_EXIT_ERROR);
+		}
+		process.stdout.write(`deferred ${journeyId} ("${opts.reason}") → ${JOURNEY_DEFERRALS_PATH}\nCOMMIT this file — the coverage audit reads the trusted (committed) tree.
+`);
+		process.exit(ACCEPTANCE_EXIT_SUCCESS);
+	});
+}
+
 //#endregion
 //#region src/cli/index.ts
 process.setMaxListeners(20);
@@ -13494,6 +13588,7 @@ async function createProgram() {
 	registerMonitorCommand(program, version);
 	registerMergeCommand(program);
 	registerWorktreesCommand(program, version);
+	registerAcceptanceCommand(program, version);
 	registerBrainstormCommand(program, version);
 	registerExportCommand(program, version);
 	registerIngestEpicCommand(program);
@@ -13508,8 +13603,8 @@ async function createProgram() {
 /** Fire-and-forget startup version check (story 8.3, AC3/AC5) */
 function checkForUpdatesInBackground(currentVersion) {
 	if (process.env.SUBSTRATE_NO_UPDATE_CHECK === "1") return;
-	import("../upgrade-BOWLlLbD.js").then(async () => {
-		const { createVersionManager } = await import("../version-manager-impl-BVcsgUtN.js");
+	import("../upgrade-M0UkDCeg.js").then(async () => {
+		const { createVersionManager } = await import("../version-manager-impl-DeEPhQlA.js");
 		const vm = createVersionManager();
 		const result = await vm.checkForUpdates();
 		if (result.updateAvailable) {

package/dist/cli/templates/agents-md-substrate-section.md

@@ -69,7 +69,17 @@ The Recovery Engine runs a 3-tier auto-fix ladder before any halt — Tier A ret
 
 ### Per-Story Worktree Behavior
 
-Each dispatched story runs in `.substrate-worktrees/story-<key>` on its own branch (`substrate/story-<key>`). The agent's auto-commit (e.g., `feat(story-N-M): ...`) lands on the branch, not main. Merge to main happens after verification SHIP_IT; the worktree is then removed. After verification failure, the worktree and branch are preserved for `substrate reconcile-from-disk` inspection. Use `--no-worktree` if your project doesn't support worktrees (submodules, bare repos).
+Each dispatched story runs in an isolated git worktree on its own branch (`substrate/story-<key>`). By default the worktree lives OUTSIDE the repo at `~/.substrate/worktrees/<projectname>-<hash8>/<key>/`; set `worktree.base: in-repo` in `.substrate/config.yaml` to restore the legacy `.substrate-worktrees/<key>/` location. Substrate auto-commits the story's work to the branch (`feat(story-N-M): ...`) at dev-story completion — commit-first, before review — so the branch is always the durable copy; failure paths add `wip(story-<key>)` checkpoints. After verification failure, the worktree and branch are preserved for `substrate reconcile-from-disk` inspection. Use `--no-worktree` if your project doesn't support worktrees (submodules, bare repos).
+
+### Finalization — how verified work integrates
+
+`finalization.mode` in `.substrate/config.yaml` (or `--finalization <mode>` per run):
+
+- **`merge`** (default): local merge into the branch the run started from. The merge is **fast-forward-only by default** — if the base branch moved during the run, the story escalates `ff-only-merge-not-possible` instead of synthesizing a merge commit. Set `finalization.merge_strategy: three-way` to allow merge commits — **required for concurrent multi-story runs** (later stories cannot fast-forward past earlier merges). A dirty parent tree whose changes intersect the story's diff escalates `parent-tree-dirtied-by-run` naming the files.
+- **`branch`**: verified work stays on `substrate/story-<key>` — nothing self-merges; the branch is the deliverable. The safe brownfield mode.
+- **`pr`**: branch + `git push` + `gh pr create` (one PR per story). Degrades to `branch` with a warning when push/gh fail — never blocks the story.
+
+Lifecycle events on the NDJSON stream: `story:committed` -> (`story:merged`) -> `story:finalized {mode, branch, sha, pr_url?}`. `substrate report` lists unmerged deliverable branches under "Finalization". Optional `finalization.epic_gate_command` runs before the LAST story of an epic integrates (non-zero exit -> `epic-gate-failed`, branch preserved).
 
 ### Key Commands
 
@@ -79,6 +89,7 @@ Each dispatched story runs in `.substrate-worktrees/story-<key>` on its own bran
 | `substrate run --halt-on <severity>` | Halt policy: `all` / `critical` (default) / `none` |
 | `substrate run --non-interactive` | Suppress stdin prompts |
 | `substrate run --no-worktree` | Disable per-story git worktrees (use for submodules or bare repos) |
+| `substrate run --finalization <mode>` | Integration mode: `merge` (default) / `branch` (never self-merge) / `pr` |
 | `substrate report [--run <id\|latest>]` | Per-run completion report |
 | `substrate report --verify-ac` | Append AC-to-Test traceability matrix |
 | `substrate reconcile-from-disk [--dry-run] [--yes]` | Path A reconciliation when tree is coherent |

package/dist/cli/templates/claude-md-substrate-section.md

@@ -93,6 +93,12 @@ Each dispatched story runs in an isolated git worktree on its own branch (`subst
 
 Lifecycle events on the NDJSON stream: `story:committed` → (`story:merged`) → `story:finalized {mode, branch, sha, pr_url?}`. `substrate report` lists unmerged deliverable branches under "Finalization". Optional `finalization.epic_gate_command` runs before the LAST story of an epic integrates (non-zero exit → `epic-gate-failed`, branch preserved).
 
+### Acceptance Gate — journey coverage (optional)
+
+If the project declares a journey registry at `.substrate/acceptance/journeys.yaml` (PRD user journeys with concrete end-states — COMMIT the file; substrate reads the committed copy, never an agent-writable worktree copy), the pipeline audits journey coverage at each epic close and at run end: every registered journey lands in exactly one state — `walked-pass`, `walked-fail`, `deferred`, `unclaimed` (NO story claims it — the never-wired-journey class), or `unwalked`. Results stream as `acceptance:coverage` events and land on the run manifest.
+
+`acceptance.mode` in `.substrate/config.yaml`: `advisory` (default — warns, never blocks), `blocking` (an unclaimed/unwalked journey escalates `journey-unclaimed`/`journey-unwalked` on the LAST story of the epic before it integrates), or `off`. Create-story tags stories with the journeys they deliver (`journeys:` frontmatter). To explicitly skip a journey: `substrate acceptance defer <id> --reason "<why>"` and commit the deferral file. Lint the registry with `substrate acceptance validate`.
+
 ### Key Commands Reference
 
 | Command | Purpose |

package/dist/cli/templates/gemini-md-substrate-section.md

@@ -69,7 +69,17 @@ The Recovery Engine runs a 3-tier auto-fix ladder before any halt — Tier A ret
 
 ### Per-Story Worktree Behavior
 
-Each dispatched story runs in `.substrate-worktrees/story-<key>` on its own branch (`substrate/story-<key>`). The agent's auto-commit (e.g., `feat(story-N-M): ...`) lands on the branch, not main. Merge to main happens after verification SHIP_IT; the worktree is then removed. After verification failure, the worktree and branch are preserved for `substrate reconcile-from-disk` inspection. Use `--no-worktree` if your project doesn't support worktrees (submodules, bare repos).
+Each dispatched story runs in an isolated git worktree on its own branch (`substrate/story-<key>`). By default the worktree lives OUTSIDE the repo at `~/.substrate/worktrees/<projectname>-<hash8>/<key>/`; set `worktree.base: in-repo` in `.substrate/config.yaml` to restore the legacy `.substrate-worktrees/<key>/` location. Substrate auto-commits the story's work to the branch (`feat(story-N-M): ...`) at dev-story completion — commit-first, before review — so the branch is always the durable copy; failure paths add `wip(story-<key>)` checkpoints. After verification failure, the worktree and branch are preserved for `substrate reconcile-from-disk` inspection. Use `--no-worktree` if your project doesn't support worktrees (submodules, bare repos).
+
+### Finalization — how verified work integrates
+
+`finalization.mode` in `.substrate/config.yaml` (or `--finalization <mode>` per run):
+
+- **`merge`** (default): local merge into the branch the run started from. The merge is **fast-forward-only by default** — if the base branch moved during the run, the story escalates `ff-only-merge-not-possible` instead of synthesizing a merge commit. Set `finalization.merge_strategy: three-way` to allow merge commits — **required for concurrent multi-story runs** (later stories cannot fast-forward past earlier merges). A dirty parent tree whose changes intersect the story's diff escalates `parent-tree-dirtied-by-run` naming the files.
+- **`branch`**: verified work stays on `substrate/story-<key>` — nothing self-merges; the branch is the deliverable. The safe brownfield mode.
+- **`pr`**: branch + `git push` + `gh pr create` (one PR per story). Degrades to `branch` with a warning when push/gh fail — never blocks the story.
+
+Lifecycle events on the NDJSON stream: `story:committed` -> (`story:merged`) -> `story:finalized {mode, branch, sha, pr_url?}`. `substrate report` lists unmerged deliverable branches under "Finalization". Optional `finalization.epic_gate_command` runs before the LAST story of an epic integrates (non-zero exit -> `epic-gate-failed`, branch preserved).
 
 ### Key Commands
 
@@ -79,6 +89,7 @@ Each dispatched story runs in `.substrate-worktrees/story-<key>` on its own bran
 | `substrate run --halt-on <severity>` | Halt policy: `all` / `critical` (default) / `none` |
 | `substrate run --non-interactive` | Suppress stdin prompts |
 | `substrate run --no-worktree` | Disable per-story git worktrees (use for submodules or bare repos) |
+| `substrate run --finalization <mode>` | Integration mode: `merge` (default) / `branch` (never self-merge) / `pr` |
 | `substrate report [--run <id\|latest>]` | Per-run completion report |
 | `substrate report --verify-ac` | Append AC-to-Test traceability matrix |
 | `substrate reconcile-from-disk [--dry-run] [--yes]` | Path A reconciliation when tree is coherent |

package/dist/{decisions-BPwrDCTx.js → decisions-lxU14pNh.js}

@@ -1,4 +1,4 @@
-import { addTokenUsage, createDecision, createPipelineRun, createRequirement, getArtifactByTypeForRun, getArtifactsByRun, getDecisionsByCategory, getDecisionsByPhase, getDecisionsByPhaseForRun, getLatestRun, getPipelineRunById, getRunningPipelineRuns, getTokenUsageSummary, listRequirements, registerArtifact, updateDecision, updatePipelineRun, updatePipelineRunConfig, upsertDecision } from "./dist-BkhYgJWo.js";
+import { addTokenUsage, createDecision, createPipelineRun, createRequirement, getArtifactByTypeForRun, getArtifactsByRun, getDecisionsByCategory, getDecisionsByPhase, getDecisionsByPhaseForRun, getLatestRun, getPipelineRunById, getRunningPipelineRuns, getTokenUsageSummary, listRequirements, registerArtifact, updateDecision, updatePipelineRun, updatePipelineRunConfig, upsertDecision } from "./dist-CpnLJuVw.js";
 import "./decisions-CzSIEeGP.js";
 
 export { getLatestRun };

package/dist/{dist-BkhYgJWo.js → dist-CpnLJuVw.js}

@@ -6341,7 +6341,12 @@ const SubstrateConfigSchema = z.object({
 		]).optional(),
 		merge_strategy: z.enum(["ff-only", "three-way"]).optional(),
 		epic_gate_command: z.string().optional()
-	}).strict().optional()
+	}).strict().optional(),
+	acceptance: z.object({ mode: z.enum([
+		"off",
+		"advisory",
+		"blocking"
+	]).optional() }).strict().optional()
 }).passthrough();
 const PartialProviderConfigSchema = ProviderConfigSchema.partial();
 const PartialGlobalSettingsSchema = GlobalSettingsSchema.partial();
@@ -6368,7 +6373,12 @@ const PartialSubstrateConfigSchema = z.object({
 		]).optional(),
 		merge_strategy: z.enum(["ff-only", "three-way"]).optional(),
 		epic_gate_command: z.string().optional()
-	}).strict().optional()
+	}).strict().optional(),
+	acceptance: z.object({ mode: z.enum([
+		"off",
+		"advisory",
+		"blocking"
+	]).optional() }).strict().optional()
 }).passthrough();
 
 //#endregion
@@ -12628,4 +12638,4 @@ async function callLLM(params) {
 
 //#endregion
 export { ADVISORY_NOTES, AdapterRegistry, AdtError, BRANCH_PREFIX, BudgetConfigSchema, CLAUDE_AUTH_FAILURE_HINT, CODEX_SANDBOX_BLOCK_HINT, CURRENT_CONFIG_FORMAT_VERSION, CURRENT_TASK_GRAPH_VERSION, Categorizer, ClaudeCodeAdapter, CodexCLIAdapter, ConfigError, ConfigIncompatibleFormatError, ConsumerAnalyzer, CostTrackerConfigSchema, DEFAULT_CONFIG, DEFAULT_GLOBAL_SETTINGS, DispatcherImpl, DoltClient, DoltNotInstalled, DoltQueryError, ESCALATION_DIAGNOSIS, EXPERIMENT_RESULT, EfficiencyScorer, GeminiCLIAdapter, GlobalSettingsSchema, InMemoryDatabaseAdapter, IngestionServer, LEARNING_FINDING, LogTurnAnalyzer, ModelRoutingConfigSchema, MonitorDatabaseImpl, OPERATIONAL_FINDING, PartialGlobalSettingsSchema, PartialProviderConfigSchema, ProviderPolicySchema, ProvidersSchema, Recommender, RoutingConfigError, RoutingRecommender, RoutingResolver, RoutingTelemetry, RoutingTokenAccumulator, RoutingTuner, STORY_METRICS, STORY_OUTCOME, SubstrateConfigSchema, TASK_TYPE_PHASE_MAP, TEST_EXPANSION_FINDING, TEST_PLAN, TelemetryConfigSchema, TelemetryNormalizer, TelemetryPipeline, TurnAnalyzer, VersionManagerImpl, addTokenUsage, aggregateTokenUsageForRun, aggregateTokenUsageForStory, buildAuditLogEntry, buildBranchName, buildModificationDirective, buildPRBody, buildWorktreePath, callLLM, checkDoltInstalled, classifyVersionGap, compareRunMetrics, createAmendmentRun, createConfigSystem, createDatabaseAdapter as createDatabaseAdapter$1, createDecision, createExperimenter, createGitWorktreeManager, createPipelineRun, createRequirement, createStderrLogger, createVersionManager, detectClaudeAuthFailure, detectCodexSandboxBlock, detectInterfaceChanges, determineVerdict, getActiveDecisions, getAllCostEntriesFiltered, getArtifactByTypeForRun, getArtifactsByRun, getBaselineRunMetrics, getDecisionsByCategory, getDecisionsByPhase, getDecisionsByPhaseForRun, getLatestCompletedRun, getLatestRun, getModelTier, getPipelineRunById, getPlanningCostTotal, getRetryableEscalations, getRunMetrics, getRunningPipelineRuns, getSessionCostSummary, getSessionCostSummaryFiltered, getStoryMetricsForRun, getTokenUsageSummary, incrementRunRestarts, initSchema, initWorkGraphSchema, initializeDolt, listRequirements, listRunMetrics, loadModelRoutingConfig, loadParentRunDecisions, registerArtifact, resolvePromptFile, supersedeDecision, swallowDebug, tagRunAsBaseline, updateDecision, updatePipelineRun, updatePipelineRunConfig, upsertDecision, writeRunMetrics, writeStoryMetrics };
-//# sourceMappingURL=dist-BkhYgJWo.js.map
+//# sourceMappingURL=dist-CpnLJuVw.js.map

package/dist/{errors-C7pY6_yQ.js → errors-8tVEwG6v.js}

@@ -1,4 +1,4 @@
-import { AdtError } from "./dist-BkhYgJWo.js";
+import { AdtError } from "./dist-CpnLJuVw.js";
 
 //#region src/core/errors.ts
 /** Error thrown when task configuration is invalid */
@@ -71,4 +71,4 @@ var TaskGraphIncompatibleFormatError = class extends AdtError {
 
 //#endregion
 export { BudgetExceededError, GitError, RecoveryError, TaskConfigError, TaskGraphCycleError, TaskGraphError, TaskGraphIncompatibleFormatError, WorkerError, WorkerNotFoundError };
-//# sourceMappingURL=errors-C7pY6_yQ.js.map
+//# sourceMappingURL=errors-8tVEwG6v.js.map

package/dist/{experimenter-BYqALeaE.js → experimenter-C7swe92R.js}

@@ -1,3 +1,3 @@
-import { buildAuditLogEntry, buildBranchName, buildModificationDirective, buildPRBody, buildWorktreePath, createExperimenter, determineVerdict, resolvePromptFile } from "./dist-BkhYgJWo.js";
+import { buildAuditLogEntry, buildBranchName, buildModificationDirective, buildPRBody, buildWorktreePath, createExperimenter, determineVerdict, resolvePromptFile } from "./dist-CpnLJuVw.js";
 
 export { createExperimenter };

package/dist/{health-Cfkv6XoQ.js → health-Dnzblihr.js}

@@ -1,6 +1,6 @@
 import { createLogger } from "./logger-KeHncl-f.js";
-import { DoltClient, DoltQueryError, createDatabaseAdapter$1 as createDatabaseAdapter, getLatestRun, getPipelineRunById, initSchema } from "./dist-BkhYgJWo.js";
-import { resolveMainRepoRoot, resolveRunManifest } from "./manifest-read-BhNRIiqm.js";
+import { DoltClient, DoltQueryError, createDatabaseAdapter$1 as createDatabaseAdapter, getLatestRun, getPipelineRunById, initSchema } from "./dist-CpnLJuVw.js";
+import { resolveMainRepoRoot, resolveRunManifest } from "./manifest-read-B3gE46DX.js";
 import { createRequire } from "module";
 import { dirname, join } from "path";
 import { existsSync, readFileSync } from "node:fs";
@@ -1000,4 +1000,4 @@ function registerHealthCommand(program, _version = "0.0.0", projectRoot = proces
 
 //#endregion
 export { BMAD_BASELINE_TOKENS_FULL, DEFAULT_STALL_THRESHOLD_SECONDS, FileKvStore, STOP_AFTER_VALID_PHASES, STORY_KEY_PATTERN, SUBSTRATE_OWNED_SETTINGS_KEYS, VALID_PHASES, __commonJS, __require, __toESM, buildPipelineStatusOutput, createDatabaseAdapter$1 as createDatabaseAdapter, createDoltOperatorReader, findPackageRoot, formatOutput, formatPipelineStatusHuman, formatPipelineSummary, formatTokenTelemetry, getAllDescendantPids, getAutoHealthData, getSubstrateDefaultSettings, inspectProcessTree, isOrchestratorProcessLine, parseDbTimestampAsUtc, registerHealthCommand, resolveBmadMethodSrcPath, resolveBmadMethodVersion, runHealthAction, validateStoryKey };
-//# sourceMappingURL=health-Cfkv6XoQ.js.map
+//# sourceMappingURL=health-Dnzblihr.js.map

package/dist/{health-Coh3BG8W.js → health-bhMCTYDO.js}

@@ -1,7 +1,7 @@
-import { DEFAULT_STALL_THRESHOLD_SECONDS, getAllDescendantPids, getAutoHealthData, inspectProcessTree, isOrchestratorProcessLine, registerHealthCommand, runHealthAction } from "./health-Cfkv6XoQ.js";
+import { DEFAULT_STALL_THRESHOLD_SECONDS, getAllDescendantPids, getAutoHealthData, inspectProcessTree, isOrchestratorProcessLine, registerHealthCommand, runHealthAction } from "./health-Dnzblihr.js";
 import "./logger-KeHncl-f.js";
-import "./dist-BkhYgJWo.js";
-import "./manifest-read-BhNRIiqm.js";
+import "./dist-CpnLJuVw.js";
+import "./manifest-read-B3gE46DX.js";
 import "./work-graph-repository-DZyJv5pV.js";
 import "./decisions-CzSIEeGP.js";
 

package/dist/{index-CnV5PcSR.d.ts → index-C31XtSMn.d.ts}

@@ -314,6 +314,13 @@ declare const SubstrateConfigSchema: z.ZodObject<{
     }>>;
     epic_gate_command: z.ZodOptional<z.ZodString>;
   }, z.core.$strict>>;
+  acceptance: z.ZodOptional<z.ZodObject<{
+    mode: z.ZodOptional<z.ZodEnum<{
+      off: "off";
+      advisory: "advisory";
+      blocking: "blocking";
+    }>>;
+  }, z.core.$strict>>;
 }, z.core.$loose>;
 type SubstrateConfig = z.infer<typeof SubstrateConfigSchema>; //#endregion
 //#region packages/core/dist/events/core-events.d.ts
@@ -1622,4 +1629,4 @@ interface Recommendation {
 
 //#endregion
 export { AdapterDiscoveryResult, AdapterRegistry as AdapterRegistry$1, AdtError as AdtError$1, ClaudeCodeAdapter as ClaudeCodeAdapter$1, CodexCLIAdapter as CodexCLIAdapter$1, ConfigError as ConfigError$1, ConfigIncompatibleFormatError as ConfigIncompatibleFormatError$1, CoreEvents, DatabaseAdapter, DiscoveryReport, GeminiCLIAdapter as GeminiCLIAdapter$1, Recommendation, TypedEventBus };
-//# sourceMappingURL=index-CnV5PcSR.d.ts.map
+//# sourceMappingURL=index-C31XtSMn.d.ts.map

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AdapterDiscoveryResult, AdapterRegistry$1 as AdapterRegistry, AdtError$1 as AdtError, ClaudeCodeAdapter$1 as ClaudeCodeAdapter, CodexCLIAdapter$1 as CodexCLIAdapter, ConfigError$1 as ConfigError, ConfigIncompatibleFormatError$1 as ConfigIncompatibleFormatError, DiscoveryReport, GeminiCLIAdapter$1 as GeminiCLIAdapter, Recommendation, TypedEventBus } from "./index-CnV5PcSR.js";
+import { AdapterDiscoveryResult, AdapterRegistry$1 as AdapterRegistry, AdtError$1 as AdtError, ClaudeCodeAdapter$1 as ClaudeCodeAdapter, CodexCLIAdapter$1 as CodexCLIAdapter, ConfigError$1 as ConfigError, ConfigIncompatibleFormatError$1 as ConfigIncompatibleFormatError, DiscoveryReport, GeminiCLIAdapter$1 as GeminiCLIAdapter, Recommendation, TypedEventBus } from "./index-C31XtSMn.js";
 import pino from "pino";
 import { z } from "zod";
 import { Readable, Writable } from "node:stream";
@@ -203,6 +203,32 @@ interface StoryFinalizedEvent {
   /** PR URL (pr mode, only when gh pr create succeeded) */
   pr_url?: string;
 }
+/**
+ * A0.3 (acceptance-gate): journey coverage audit result, emitted at each
+ * epic close and at run end (`scope: "final"`). Every registered journey in
+ * scope lands in exactly one state; `unclaimed` is the never-wired-journey
+ * class (UJ-2) caught structurally. In `blocking` mode an unclaimed/unwalked
+ * journey escalates the LAST story of the epic before it integrates; in
+ * `advisory` mode (the default) this event and a warning are the signal.
+ */
+interface AcceptanceCoverageEvent {
+  type: 'acceptance:coverage';
+  /** ISO-8601 timestamp generated at emit time */
+  ts: string;
+  /** Audited boundary: `epic-<n>` or `final` */
+  scope: string;
+  /** Audit posture the run is under */
+  mode: 'advisory' | 'blocking';
+  /** Per-journey coverage states */
+  entries: {
+    journeyId: string;
+    criticality: 'critical' | 'standard';
+    state: 'walked-pass' | 'walked-fail' | 'deferred' | 'unclaimed' | 'unwalked';
+    ownerStories: string[];
+  }[];
+  /** State counts across `entries` */
+  summary: Record<string, number>;
+}
 /**
  * Emitted when the orchestrator auto-approves a story after exhausting
  * review cycles with only minor issues remaining. Provides transparency
@@ -836,7 +862,7 @@ interface PipelineMergeConflictDetectedEvent {
  * }
  * ```
  */
-type PipelineEvent = PipelineStartEvent | PipelineCompleteEvent | PipelinePreFlightFailureEvent | PipelineProfileStaleEvent | PipelineContractMismatchEvent | PipelineContractVerificationSummaryEvent | StoryPhaseEvent | StoryDoneEvent | StoryCommittedEvent | StoryMergedEvent | StoryFinalizedEvent | StoryEscalationEvent | StoryWarnEvent | StoryLogEvent | PipelineHeartbeatEvent | StoryStallEvent | StoryZeroDiffEscalationEvent | StoryBuildVerificationFailedEvent | StoryBuildVerificationPassedEvent | StoryInterfaceChangeWarningEvent | StoryMetricsEvent | SupervisorPollEvent | SupervisorKillEvent | SupervisorRestartEvent | SupervisorAbortEvent | SupervisorSummaryEvent | SupervisorAnalysisCompleteEvent | SupervisorAnalysisErrorEvent | SupervisorExperimentStartEvent | SupervisorExperimentSkipEvent | SupervisorExperimentRecommendationsEvent | SupervisorExperimentCompleteEvent | SupervisorExperimentErrorEvent | RoutingModelSelectedEvent | PipelinePhaseStartEvent | PipelinePhaseCompleteEvent | StoryAutoApprovedEvent | VerificationCheckCompleteEvent | VerificationStoryCompleteEvent | CostWarningEvent | CostCeilingReachedEvent | DecisionHaltSkippedNonInteractiveEvent | PipelineMergeConflictDetectedEvent; //#endregion
+type PipelineEvent = PipelineStartEvent | PipelineCompleteEvent | PipelinePreFlightFailureEvent | PipelineProfileStaleEvent | PipelineContractMismatchEvent | PipelineContractVerificationSummaryEvent | StoryPhaseEvent | StoryDoneEvent | StoryCommittedEvent | StoryMergedEvent | StoryFinalizedEvent | AcceptanceCoverageEvent | StoryEscalationEvent | StoryWarnEvent | StoryLogEvent | PipelineHeartbeatEvent | StoryStallEvent | StoryZeroDiffEscalationEvent | StoryBuildVerificationFailedEvent | StoryBuildVerificationPassedEvent | StoryInterfaceChangeWarningEvent | StoryMetricsEvent | SupervisorPollEvent | SupervisorKillEvent | SupervisorRestartEvent | SupervisorAbortEvent | SupervisorSummaryEvent | SupervisorAnalysisCompleteEvent | SupervisorAnalysisErrorEvent | SupervisorExperimentStartEvent | SupervisorExperimentSkipEvent | SupervisorExperimentRecommendationsEvent | SupervisorExperimentCompleteEvent | SupervisorExperimentErrorEvent | RoutingModelSelectedEvent | PipelinePhaseStartEvent | PipelinePhaseCompleteEvent | StoryAutoApprovedEvent | VerificationCheckCompleteEvent | VerificationStoryCompleteEvent | CostWarningEvent | CostCeilingReachedEvent | DecisionHaltSkippedNonInteractiveEvent | PipelineMergeConflictDetectedEvent; //#endregion
 //#region src/core/errors.d.ts
 
 /**
@@ -1497,6 +1523,23 @@ interface OrchestratorEvents {
     sha: string;
     prUrl?: string;
   };
+  /**
+   * A0.3 (acceptance-gate): journey coverage audit result — emitted at epic
+   * close and at run end. Mapped to the NDJSON `acceptance:coverage` event.
+   */
+  'orchestrator:acceptance-coverage': {
+    scope: string;
+    mode: 'advisory' | 'blocking';
+    entries: {
+      journeyId: string;
+      title: string;
+      criticality: 'critical' | 'standard';
+      epic?: number;
+      state: 'walked-pass' | 'walked-fail' | 'deferred' | 'unclaimed' | 'unwalked';
+      ownerStories: string[];
+    }[];
+    summary: Record<string, number>;
+  };
   /** A story has been escalated after exceeding max review cycles */
   'orchestrator:story-escalated': {
     storyKey: string;

package/dist/index.js

@@ -1,8 +1,8 @@
 import { childLogger, createLogger, logger } from "./logger-KeHncl-f.js";
 import { assertDefined, createEventBus, createTuiApp, deepClone, formatDuration, generateId, isPlainObject, isTuiCapable, printNonTtyWarning, sleep, withRetry } from "./helpers-CElYrONe.js";
-import { AdapterRegistry, AdtError, ClaudeCodeAdapter, CodexCLIAdapter, ConfigError, ConfigIncompatibleFormatError, GeminiCLIAdapter } from "./dist-BkhYgJWo.js";
+import { AdapterRegistry, AdtError, ClaudeCodeAdapter, CodexCLIAdapter, ConfigError, ConfigIncompatibleFormatError, GeminiCLIAdapter } from "./dist-CpnLJuVw.js";
 import "./adapter-registry-DXLMTmfD.js";
-import { BudgetExceededError, GitError, RecoveryError, TaskConfigError, TaskGraphCycleError, TaskGraphError, TaskGraphIncompatibleFormatError, WorkerError, WorkerNotFoundError } from "./errors-C7pY6_yQ.js";
+import { BudgetExceededError, GitError, RecoveryError, TaskConfigError, TaskGraphCycleError, TaskGraphError, TaskGraphIncompatibleFormatError, WorkerError, WorkerNotFoundError } from "./errors-8tVEwG6v.js";
 
 //#region src/core/di.ts
 /**