substrate-ai 0.21.1 → 0.21.2

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/cli/index.js

@@ -1,17 +1,17 @@
 #!/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-DvgJ7jj_.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 "../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 { JOURNEY_REGISTRY_PATH, RunManifest, SupervisorLock, ZERO_FINDINGS_BY_AUTHOR, ZERO_FINDING_COUNTS, ZERO_PROBE_AUTHOR_METRICS, aggregateProbeAuthorMetrics, loadJourneyRegistryFromFile, loadJourneyRegistryFromTrustedTree, parseRuntimeProbes, readCurrentRunId, resolveMainRepoRoot, resolveRunManifest, rollupFindingCounts, rollupFindingsByAuthor, rollupProbeAuthorByClass, rollupProbeAuthorMetrics, runAcTraceabilityCheck } from "../manifest-read-DyyFPrJH.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-CAmBrDky.js";
 import "../errors-C7pY6_yQ.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-CPF2GTvV.js";
 import "../recovery-engine-BKGBeBnW.js";
 import "../version-manager-impl-qFBiO4Eh.js";
 import { registerUpgradeCommand } from "../upgrade-S1oUMH5P.js";
@@ -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-DDsjslMy.js");
 			const substrateDirPath = join(projectRoot, ".substrate");
 			const processInfo = inspectProcessTree$1({
 				projectRoot,
@@ -8655,7 +8659,7 @@ async function runSupervisorAction(options, deps = {}) {
 								await initSchema(expAdapter);
 								const { runRunAction: runPipeline } = await import(
 									/* @vite-ignore */
-									"../run-CKM-5T34.js"
+									"../run-CF0qLJAV.js"
 );
 								const runStoryFn = async (opts) => {
 									const exitCode = await runPipeline({
@@ -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,53 @@ 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));
+	});
+}
+
 //#endregion
 //#region src/cli/index.ts
 process.setMaxListeners(20);
@@ -13494,6 +13545,7 @@ async function createProgram() {
 	registerMonitorCommand(program, version);
 	registerMergeCommand(program);
 	registerWorktreesCommand(program, version);
+	registerAcceptanceCommand(program, version);
 	registerBrainstormCommand(program, version);
 	registerExportCommand(program, version);
 	registerIngestEpicCommand(program);

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/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/{health-Coh3BG8W.js → health-DDsjslMy.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-DvgJ7jj_.js";
 import "./logger-KeHncl-f.js";
 import "./dist-BkhYgJWo.js";
-import "./manifest-read-BhNRIiqm.js";
+import "./manifest-read-DyyFPrJH.js";
 import "./work-graph-repository-DZyJv5pV.js";
 import "./decisions-CzSIEeGP.js";
 

package/dist/{health-Cfkv6XoQ.js → health-DvgJ7jj_.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 { resolveMainRepoRoot, resolveRunManifest } from "./manifest-read-DyyFPrJH.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-DvgJ7jj_.js.map

package/dist/{interactive-prompt-BBfPSxyJ.js → interactive-prompt-CPF2GTvV.js}

@@ -1,5 +1,5 @@
 import { createLogger } from "./logger-KeHncl-f.js";
-import { readCurrentRunId, resolveMainRepoRoot } from "./manifest-read-BhNRIiqm.js";
+import { readCurrentRunId, resolveMainRepoRoot } from "./manifest-read-DyyFPrJH.js";
 import { join } from "node:path";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import * as readline from "node:readline";
@@ -180,4 +180,4 @@ async function runInteractivePrompt(decisionContext) {
 
 //#endregion
 export { runInteractivePrompt };
-//# sourceMappingURL=interactive-prompt-BBfPSxyJ.js.map
+//# sourceMappingURL=interactive-prompt-CPF2GTvV.js.map

package/dist/{manifest-read-BhNRIiqm.js → manifest-read-DyyFPrJH.js}

@@ -3087,7 +3087,21 @@ function executeProbeOnHost(probe, options = {}) {
 * registry, os. Open string so novel names don't cause silent skips.
 */
 const ExternalStateDependencySchema = z.string();
-const StoryFrontmatterSchema = z.object({ external_state_dependencies: z.array(ExternalStateDependencySchema).optional().default([]) });
+/**
+* Journey tags (acceptance-gate story A0.2): `journeys: [UJ-x]` declares which
+* registry journeys this story claims to deliver. Tolerant by design — a bare
+* string coerces to a one-element list, and any non-coercible shape falls back
+* to `[]` via `.catch` WITHOUT failing the whole frontmatter block (a malformed
+* journey tag must never silently drop `external_state_dependencies`).
+* Untagged is legal: the epic-close coverage invariant (A0.3) is the backstop;
+* tags only buy earlier detection. Unknown-id validation happens against the
+* trusted-tree registry in the create-story workflow, not here.
+*/
+const JourneyTagsSchema = z.union([z.string().transform((s) => [s]), z.array(z.string())]).catch([]);
+const StoryFrontmatterSchema = z.object({
+	external_state_dependencies: z.array(ExternalStateDependencySchema).optional().default([]),
+	journeys: JourneyTagsSchema.optional().default([])
+});
 /**
 * Parse the optional YAML frontmatter block from a story artifact.
 *
@@ -4963,6 +4977,210 @@ async function runAcTraceabilityCheck(input) {
 	};
 }
 
+//#endregion
+//#region packages/sdlc/dist/acceptance/registry.js
+/** Repo-relative path of the registry — the single canonical location. */
+const JOURNEY_REGISTRY_PATH = ".substrate/acceptance/journeys.yaml";
+const JourneySurfaceSchema = z.enum([
+	"email",
+	"cli",
+	"file",
+	"web"
+]);
+const JourneyEndStateSchema = z.object({
+	id: z.string().min(1, "end-state id must be a non-empty string"),
+	given: z.string().min(1, "given must be a non-empty string"),
+	walk: z.string().min(1, "walk must be a non-empty string"),
+	then: z.string().min(1, "then must be a non-empty string")
+});
+const JourneySchema = z.object({
+	id: z.string().min(1, "journey id must be a non-empty string"),
+	title: z.string().min(1, "title must be a non-empty string"),
+	criticality: z.enum(["critical", "standard"]),
+	surfaces: z.array(JourneySurfaceSchema).min(1, "a journey must declare at least one surface"),
+	epic: z.number().int().positive().optional(),
+	end_states: z.array(JourneyEndStateSchema).min(1, "a journey must declare at least one end_state — a journey with none is unjudgeable")
+});
+const JourneyRegistrySchema = z.object({
+	version: z.number().int().positive("version must be a positive integer"),
+	journeys: z.array(JourneySchema)
+}).superRefine((registry, ctx) => {
+	const seenJourneyIds = new Map();
+	registry.journeys.forEach((journey, i) => {
+		const firstIndex = seenJourneyIds.get(journey.id);
+		if (firstIndex !== void 0) ctx.addIssue({
+			code: "custom",
+			path: [
+				"journeys",
+				i,
+				"id"
+			],
+			message: `duplicate journey id "${journey.id}" (first declared at journeys[${firstIndex}])`
+		});
+		else seenJourneyIds.set(journey.id, i);
+		const seenEndStateIds = new Map();
+		journey.end_states.forEach((endState, j) => {
+			const firstEs = seenEndStateIds.get(endState.id);
+			if (firstEs !== void 0) ctx.addIssue({
+				code: "custom",
+				path: [
+					"journeys",
+					i,
+					"end_states",
+					j,
+					"id"
+				],
+				message: `duplicate end-state id "${endState.id}" in journey "${journey.id}" (first declared at end_states[${firstEs}])`
+			});
+			else seenEndStateIds.set(endState.id, j);
+		});
+	});
+});
+function zodErrorToValidationIssues(error) {
+	return error.issues.map((issue) => ({
+		path: issue.path.length > 0 ? issue.path.map(String).join(".") : "(root)",
+		message: issue.message
+	}));
+}
+/**
+* Parse and validate registry YAML content.
+*
+* Never throws: malformed YAML, non-object documents, and schema violations
+* all come back as named, pathed issues.
+*/
+function parseJourneyRegistry(yamlContent) {
+	let doc;
+	try {
+		doc = load(yamlContent);
+	} catch (err) {
+		const message = err instanceof YAMLException ? err.message : String(err);
+		return {
+			ok: false,
+			issues: [{
+				path: "(root)",
+				message: `malformed YAML: ${message}`
+			}]
+		};
+	}
+	if (doc === null || doc === void 0) return {
+		ok: false,
+		issues: [{
+			path: "(root)",
+			message: "registry file is empty"
+		}]
+	};
+	const result = JourneyRegistrySchema.safeParse(doc);
+	if (!result.success) return {
+		ok: false,
+		issues: zodErrorToValidationIssues(result.error)
+	};
+	return {
+		ok: true,
+		registry: result.data
+	};
+}
+
+//#endregion
+//#region packages/sdlc/dist/acceptance/loader.js
+/** stderr shapes that mean "the path is not in the tree at this ref" (absent, not an error). */
+const GIT_SHOW_ABSENT_PATTERNS = [
+	/does not exist in/i,
+	/exists on disk, but not in/i,
+	/path .* does not exist/i
+];
+/** Array-argv spawn — no shell, no interpolation, injection-safe by construction. */
+function runGitShow(repoRoot, ref, relPath) {
+	return new Promise((resolve$2) => {
+		let stdout = "";
+		let stderr = "";
+		const proc = spawn("git", ["show", `${ref}:${relPath}`], {
+			cwd: repoRoot,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		proc.stdout?.on("data", (chunk) => {
+			stdout += chunk.toString("utf-8");
+		});
+		proc.stderr?.on("data", (chunk) => {
+			stderr += chunk.toString("utf-8");
+		});
+		proc.on("error", (err) => {
+			resolve$2({
+				code: null,
+				stdout,
+				stderr,
+				spawnError: err.message
+			});
+		});
+		proc.on("close", (code) => {
+			resolve$2({
+				code,
+				stdout,
+				stderr
+			});
+		});
+	});
+}
+/**
+* Load the journey registry from the trusted main tree at `ref`.
+*
+* @param repoRoot absolute path of the TRUSTED repo root (the main tree, not a worktree)
+* @param ref git ref to read at — the dispatch snapshot ref (defaults to HEAD)
+*/
+async function loadJourneyRegistryFromTrustedTree(repoRoot, ref = "HEAD") {
+	const result = await runGitShow(repoRoot, ref, JOURNEY_REGISTRY_PATH);
+	if (result.spawnError !== void 0) return {
+		status: "error",
+		message: `git show could not be spawned: ${result.spawnError}`
+	};
+	if (result.code !== 0) {
+		if (GIT_SHOW_ABSENT_PATTERNS.some((p) => p.test(result.stderr))) return { status: "absent" };
+		return {
+			status: "error",
+			message: `git show ${ref}:${JOURNEY_REGISTRY_PATH} failed (exit ${String(result.code)}): ${result.stderr.trim()}`
+		};
+	}
+	const parsed = parseJourneyRegistry(result.stdout);
+	if (!parsed.ok) return {
+		status: "invalid",
+		issues: parsed.issues
+	};
+	return {
+		status: "ok",
+		registry: parsed.registry
+	};
+}
+/**
+* Filesystem read for OPERATOR LINT ONLY (`substrate acceptance validate`).
+* Gate/judge code paths must use `loadJourneyRegistryFromTrustedTree`.
+*/
+async function loadJourneyRegistryFromFile(projectRoot) {
+	const filePath = join$1(projectRoot, JOURNEY_REGISTRY_PATH);
+	let content;
+	try {
+		content = await readFile$1(filePath, "utf-8");
+	} catch (err) {
+		const code = err.code;
+		if (code === "ENOENT" || code === "ENOTDIR") return { status: "absent" };
+		return {
+			status: "error",
+			message: `could not read ${filePath}: ${String(err)}`
+		};
+	}
+	const parsed = parseJourneyRegistry(content);
+	if (!parsed.ok) return {
+		status: "invalid",
+		issues: parsed.issues
+	};
+	return {
+		status: "ok",
+		registry: parsed.registry
+	};
+}
+
 //#endregion
 //#region packages/sdlc/dist/run-model/cli-flags.js
 /**
@@ -6381,5 +6599,5 @@ async function resolveRunManifest(dbRoot, runId) {
 }
 
 //#endregion
-export { FindingsInjector, RunManifest, RuntimeProbeListSchema, SupervisorLock, ZERO_FINDINGS_BY_AUTHOR, ZERO_FINDING_COUNTS, ZERO_PROBE_AUTHOR_METRICS, aggregateProbeAuthorMetrics, applyConfigToGraph, createDefaultVerificationPipeline, createGraphOrchestrator, createSdlcCodeReviewHandler, createSdlcCreateStoryHandler, createSdlcDevStoryHandler, createSdlcPhaseHandler, detectsEventDrivenAC, detectsStateIntegratingAC, extractTargetFilesFromStoryContent, parseRuntimeProbes, readCurrentRunId, renderFindings, resolveGraphPath, resolveMainRepoRoot, resolveRunManifest, rollupFindingCounts, rollupFindingsByAuthor, rollupProbeAuthorByClass, rollupProbeAuthorMetrics, runAcTraceabilityCheck, runStaleVerificationRecovery };
-//# sourceMappingURL=manifest-read-BhNRIiqm.js.map
+export { FindingsInjector, JOURNEY_REGISTRY_PATH, RunManifest, RuntimeProbeListSchema, SupervisorLock, ZERO_FINDINGS_BY_AUTHOR, ZERO_FINDING_COUNTS, ZERO_PROBE_AUTHOR_METRICS, aggregateProbeAuthorMetrics, applyConfigToGraph, createDefaultVerificationPipeline, createGraphOrchestrator, createSdlcCodeReviewHandler, createSdlcCreateStoryHandler, createSdlcDevStoryHandler, createSdlcPhaseHandler, detectsEventDrivenAC, detectsStateIntegratingAC, extractTargetFilesFromStoryContent, loadJourneyRegistryFromFile, loadJourneyRegistryFromTrustedTree, parseRuntimeProbes, parseStoryFrontmatter, readCurrentRunId, renderFindings, resolveGraphPath, resolveMainRepoRoot, resolveRunManifest, rollupFindingCounts, rollupFindingsByAuthor, rollupProbeAuthorByClass, rollupProbeAuthorMetrics, runAcTraceabilityCheck, runStaleVerificationRecovery };
+//# sourceMappingURL=manifest-read-DyyFPrJH.js.map

package/dist/modules/interactive-prompt/index.js

@@ -1,6 +1,6 @@
 import "../../logger-KeHncl-f.js";
 import "../../dist-BkhYgJWo.js";
-import "../../manifest-read-BhNRIiqm.js";
-import { runInteractivePrompt } from "../../interactive-prompt-BBfPSxyJ.js";
+import "../../manifest-read-DyyFPrJH.js";
+import { runInteractivePrompt } from "../../interactive-prompt-CPF2GTvV.js";
 
 export { runInteractivePrompt };

package/dist/{run-JrEnvaB0.js → run-CAmBrDky.js}

@@ -1,11 +1,11 @@
-import { BMAD_BASELINE_TOKENS_FULL, FileKvStore, STOP_AFTER_VALID_PHASES, STORY_KEY_PATTERN, VALID_PHASES, __commonJS, __require, __toESM, buildPipelineStatusOutput, createDatabaseAdapter, formatOutput, formatPipelineSummary, formatTokenTelemetry, inspectProcessTree, parseDbTimestampAsUtc, validateStoryKey } from "./health-Cfkv6XoQ.js";
+import { BMAD_BASELINE_TOKENS_FULL, FileKvStore, STOP_AFTER_VALID_PHASES, STORY_KEY_PATTERN, VALID_PHASES, __commonJS, __require, __toESM, buildPipelineStatusOutput, createDatabaseAdapter, formatOutput, formatPipelineSummary, formatTokenTelemetry, inspectProcessTree, parseDbTimestampAsUtc, validateStoryKey } from "./health-DvgJ7jj_.js";
 import { createLogger } from "./logger-KeHncl-f.js";
 import { TypedEventBusImpl, createEventBus, createTuiApp, isTuiCapable, printNonTtyWarning, sleep } from "./helpers-CElYrONe.js";
 import { ADVISORY_NOTES, BRANCH_PREFIX, CLAUDE_AUTH_FAILURE_HINT, CODEX_SANDBOX_BLOCK_HINT, 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, classifyVersionGap, createConfigSystem, createDatabaseAdapter$1, createDecision, createGitWorktreeManager, createPipelineRun, createRequirement, detectClaudeAuthFailure, detectCodexSandboxBlock, detectInterfaceChanges, getArtifactByTypeForRun, getArtifactsByRun, getDecisionsByCategory, getDecisionsByPhase, getDecisionsByPhaseForRun, getLatestRun, getPipelineRunById, getRunMetrics, getRunningPipelineRuns, getStoryMetricsForRun, getTokenUsageSummary, initSchema, listRequirements, loadModelRoutingConfig, registerArtifact, swallowDebug, updatePipelineRun, updatePipelineRunConfig, upsertDecision, writeRunMetrics, writeStoryMetrics } from "./dist-BkhYgJWo.js";
-import { FindingsInjector, RunManifest, RuntimeProbeListSchema, applyConfigToGraph, createDefaultVerificationPipeline, createGraphOrchestrator, createSdlcCodeReviewHandler, createSdlcCreateStoryHandler, createSdlcDevStoryHandler, createSdlcPhaseHandler, detectsEventDrivenAC, detectsStateIntegratingAC, extractTargetFilesFromStoryContent, parseRuntimeProbes, renderFindings, resolveGraphPath, resolveMainRepoRoot, runAcTraceabilityCheck, runStaleVerificationRecovery } from "./manifest-read-BhNRIiqm.js";
+import { FindingsInjector, RunManifest, RuntimeProbeListSchema, applyConfigToGraph, createDefaultVerificationPipeline, createGraphOrchestrator, createSdlcCodeReviewHandler, createSdlcCreateStoryHandler, createSdlcDevStoryHandler, createSdlcPhaseHandler, detectsEventDrivenAC, detectsStateIntegratingAC, extractTargetFilesFromStoryContent, loadJourneyRegistryFromTrustedTree, parseRuntimeProbes, parseStoryFrontmatter, renderFindings, resolveGraphPath, resolveMainRepoRoot, runAcTraceabilityCheck, runStaleVerificationRecovery } from "./manifest-read-DyyFPrJH.js";
 import { WorkGraphRepository, detectCycles } from "./work-graph-repository-DZyJv5pV.js";
 import { deriveExitCode, routeDecision } from "./decision-router-BAPpON_C.js";
-import { runInteractivePrompt } from "./interactive-prompt-BBfPSxyJ.js";
+import { runInteractivePrompt } from "./interactive-prompt-CPF2GTvV.js";
 import { runRecoveryEngine } from "./recovery-engine-BKGBeBnW.js";
 import { basename, dirname, extname, join } from "path";
 import { access, readFile, readdir, stat } from "fs/promises";
@@ -951,7 +951,7 @@ const PIPELINE_EVENT_METADATA = [
 			{
 				name: "reason",
 				type: "string",
-				description: "Escalation reason. Common values: review-cycles-exhausted (default review-loop max hit); create-story-no-file (create-story phase did not write a story artifact); dev-story-no-commit (substrate auto-commit found no committable changes — agent produced nothing or all changes were outside the worktree); dev-story-commit-failed (substrate auto-commit failed — typically a pre-commit hook rejected the commit; stderr captured in issues); merge-to-main-error (unexpected error in the merge-to-main phase); merge-conflict-detected (story branch could not be merged due to conflicts); parent-tree-dirtied-by-run (uncommitted parent changes intersect the story diff — merge refused, H3.3); ff-only-merge-not-possible (base moved and merge_strategy is ff-only — set finalization.merge_strategy: three-way or integrate manually, H3.3); epic-gate-failed (finalization.epic_gate_command exited non-zero before the last story of an epic integrated, H3.4); story-file-missing (story artifact gone from working tree AND branch HEAD — check wip/feat commits on the story branch, H5.5). v0.20.87+."
+				description: "Escalation reason. Common values: review-cycles-exhausted (default review-loop max hit); create-story-no-file (create-story phase did not write a story artifact); dev-story-no-commit (substrate auto-commit found no committable changes — agent produced nothing or all changes were outside the worktree); dev-story-commit-failed (substrate auto-commit failed — typically a pre-commit hook rejected the commit; stderr captured in issues); merge-to-main-error (unexpected error in the merge-to-main phase); merge-conflict-detected (story branch could not be merged due to conflicts); parent-tree-dirtied-by-run (uncommitted parent changes intersect the story diff — merge refused, H3.3); ff-only-merge-not-possible (base moved and merge_strategy is ff-only — set finalization.merge_strategy: three-way or integrate manually, H3.3); epic-gate-failed (finalization.epic_gate_command exited non-zero before the last story of an epic integrated, H3.4); story-file-missing (story artifact gone from working tree AND branch HEAD — check wip/feat commits on the story branch, H5.5); undisclosed-files-in-merge (a committed implementation file was never in the dev agent's files_modified, so no review cycle inspected it — inspect the branch, then re-dispatch with accurate files_modified or merge manually, H7). v0.20.87+."
 			},
 			{
 				name: "cycles",
@@ -6138,6 +6138,21 @@ async function runCreateStory(deps, params) {
 	} catch {}
 	const archConstraintsContent = await getArchConstraints$3(deps);
 	const storyTemplateContent = await getStoryTemplate(deps);
+	const trustedRoot = deps.parentProjectRoot ?? deps.projectRoot;
+	let journeyRegistry;
+	if (trustedRoot !== void 0) {
+		const registryLoad = await loadJourneyRegistryFromTrustedTree(trustedRoot);
+		if (registryLoad.status === "ok" && registryLoad.registry.journeys.length > 0) journeyRegistry = registryLoad.registry;
+		else if (registryLoad.status === "invalid") logger$21.warn({
+			storyKey,
+			issues: registryLoad.issues
+		}, "A0.2: journey registry present but invalid — stories will be untagged (registry validity is escalated at epic close)");
+		else if (registryLoad.status === "error") logger$21.warn({
+			storyKey,
+			error: registryLoad.message
+		}, "A0.2: journey registry read failed — stories will be untagged");
+	}
+	const journeyRegistryContent = journeyRegistry !== void 0 ? journeyRegistry.journeys.map((j$1) => `- ${j$1.id} [${j$1.criticality}]: ${j$1.title}`).join("\n") : "";
 	const { prompt, tokenCount, truncated } = assemblePrompt(template, [
 		{
 			name: "story_key",
@@ -6182,6 +6197,15 @@ async function runCreateStory(deps, params) {
 			name: "prior_drift_feedback",
 			content: "",
 			priority: "optional"
+		}],
+		...journeyRegistryContent.length > 0 ? [{
+			name: "journey_registry",
+			content: journeyRegistryContent,
+			priority: "required"
+		}] : [{
+			name: "journey_registry",
+			content: "",
+			priority: "optional"
 		}]
 	], TOKEN_CEILING);
 	logger$21.debug({
@@ -6295,6 +6319,38 @@ async function runCreateStory(deps, params) {
 		};
 	}
 	const parsed = parseResult.data;
+	if (journeyRegistry !== void 0 && parsed.story_file !== void 0) {
+		let artifactContent;
+		try {
+			artifactContent = await readFile$1(parsed.story_file, "utf-8");
+		} catch {
+			artifactContent = void 0;
+		}
+		if (artifactContent !== void 0) {
+			const taggedJourneys = parseStoryFrontmatter(artifactContent).journeys;
+			const knownIds = new Set(journeyRegistry.journeys.map((j$1) => j$1.id));
+			const unknown = taggedJourneys.filter((id) => !knownIds.has(id));
+			if (unknown.length > 0) {
+				const details = `story artifact declares unknown journey id(s): ${unknown.join(", ")} — registry v${String(journeyRegistry.version)} defines: ${[...knownIds].join(", ")}`;
+				logger$21.warn({
+					epicId,
+					storyKey,
+					unknown
+				}, "A0.2: journey tag validation failed");
+				return {
+					result: "failed",
+					error: "schema_validation_failed",
+					details,
+					tokenUsage
+				};
+			}
+			if (taggedJourneys.length > 0) logger$21.info({
+				epicId,
+				storyKey,
+				journeys: taggedJourneys
+			}, "A0.2: story tagged with journeys");
+		}
+	}
 	logger$21.info({
 		epicId,
 		storyKey,
@@ -48092,4 +48148,4 @@ function registerRunCommand(program, version = "0.0.0", projectRoot = process.cw
 
 //#endregion
 export { AdapterTelemetryPersistence, AppError, DoltRepoMapMetaRepository, DoltSymbolRepository, ERR_REPO_MAP_STORAGE_WRITE, EpicIngester, GLOBSTAR$1 as GLOBSTAR, GitClient, GrammarLoader, Minimatch$1 as Minimatch, Minipass, RepoMapInjector, RepoMapModule, RepoMapQueryEngine, RepoMapStorage, SymbolParser, createContextCompiler, createDispatcher, createEventEmitter, createImplementationOrchestrator, createPackLoader, createPhaseOrchestrator, createStopAfterGate, createTelemetryAdvisor, escape$1 as escape, formatPhaseCompletionSummary, getFactoryRunSummaries, getScenarioResultsForRun, getTwinRunsForRun, listGraphRuns, normalizeGraphSummaryToStatus, registerExportCommand, registerFactoryCommand, registerRunCommand, registerScenariosCommand, resolveMaxReviewCycles, resolveProbeAuthorStateIntegrating, resolveStoryKeys, runAnalysisPhase, runPlanningPhase, runProbeAuthor, runRunAction, runSolutioningPhase, unescape$1 as unescape, validateStopAfterFromConflict, wireNdjsonEmitter };
-//# sourceMappingURL=run-JrEnvaB0.js.map
+//# sourceMappingURL=run-CAmBrDky.js.map

package/dist/{run-CKM-5T34.js → run-CF0qLJAV.js}

@@ -1,14 +1,14 @@
-import "./health-Cfkv6XoQ.js";
+import "./health-DvgJ7jj_.js";
 import "./logger-KeHncl-f.js";
 import "./helpers-CElYrONe.js";
 import "./dist-BkhYgJWo.js";
-import "./manifest-read-BhNRIiqm.js";
-import { normalizeGraphSummaryToStatus, registerRunCommand, resolveMaxReviewCycles, resolveProbeAuthorStateIntegrating, runRunAction, wireNdjsonEmitter } from "./run-JrEnvaB0.js";
+import "./manifest-read-DyyFPrJH.js";
+import { normalizeGraphSummaryToStatus, registerRunCommand, resolveMaxReviewCycles, resolveProbeAuthorStateIntegrating, runRunAction, wireNdjsonEmitter } from "./run-CAmBrDky.js";
 import "./routing-DFxoKHDt.js";
 import "./work-graph-repository-DZyJv5pV.js";
 import "./decisions-CzSIEeGP.js";
 import "./decision-router-BAPpON_C.js";
-import "./interactive-prompt-BBfPSxyJ.js";
+import "./interactive-prompt-CPF2GTvV.js";
 import "./recovery-engine-BKGBeBnW.js";
 
 export { runRunAction };

package/package.json

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

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

@@ -191,6 +191,28 @@ Suggested values (use as many as apply):
 
 **Omit the field (or leave it empty) only for purely-algorithmic modules** where you also omit `## Runtime Probes` — parse/format/sort/score/calculate transforms, type-only refactors, documentation edits, build-config changes, and unit-test-only stories.
 
+### Journey tags (acceptance gate)
+
+This project's journey registry (empty when the project has none):
+
+{{journey_registry}}
+
+If the registry above is non-empty, decide which journeys this story's acceptance criteria deliver or materially advance, and declare them in the SAME YAML frontmatter block at the top of the story file:
+
+```text
+---
+external_state_dependencies:
+  - subprocess
+journeys:
+  - UJ-2
+---
+```
+
+Rules:
+- Use ONLY journey ids that appear in the registry above — an unknown id fails the story artifact's schema validation.
+- Tag a journey when the story wires, extends, or completes any part of that journey's user-facing path — not merely because it touches nearby code.
+- If no registered journey applies (or the registry above is empty), OMIT the `journeys:` field entirely. Untagged stories are legal; unclaimed journeys are audited separately at epic close.
+
 ### Probe YAML shape
 
 Declare probes as a YAML list inside a single fenced `yaml` block directly under the `## Runtime Probes` heading. Each entry has this shape: