substrate-ai 0.20.70 → 0.20.71

package/README.md

@@ -101,6 +101,30 @@ substrate resume
 substrate cancel
 ```
 
+### Autonomy Modes
+
+Substrate exposes a three-step autonomy gradient. Pick the mode that matches how much operator attention the run gets.
+
+| Mode | Invocation | Halts on |
+|---|---|---|
+| Attended | `substrate run --halt-on all` | Every decision (info, warning, critical, fatal) |
+| Supervised *(default)* | `substrate run` | Critical + fatal (cost-ceiling, build-fail, scope-violation) |
+| Autonomous | `substrate run --halt-on none --non-interactive --events --output-format json` | Only fatal — scope violations always halt regardless |
+
+Exit codes from autonomous runs: `0` = all stories succeeded or auto-recovered; `1` = some stories escalated (run completed); `2` = run-level failure (cost ceiling, fatal halt, orchestrator died). Combine with the canonical post-run review flow:
+
+```bash
+# Canonical CI / overnight pattern:
+substrate run --halt-on none --non-interactive --events --output-format json
+
+# Then review the result:
+substrate report --run latest                  # per-story outcomes + escalation diagnostics
+substrate report --run latest --verify-ac      # adds AC-to-Test traceability matrix
+substrate reconcile-from-disk --dry-run        # if pipeline reported failed but tree is coherent
+```
+
+Behind the scenes, the **Recovery Engine** runs a 3-tier auto-fix ladder before any halt — Tier A retries with extra context (build-fail, missing test coverage, AC missing evidence), Tier B drafts a re-scope proposal, Tier C halts for an operator prompt. Re-scope proposals collect on the run manifest as `pending_proposals[]` for next-morning review; back-pressure pauses dispatching at `>= 2` proposals (work-graph-aware) or `>= 5` (safety valve). When a halt is required, the Recovery Engine writes an operator notification to `.substrate/notifications/<run-id>-<timestamp>.json`; `substrate report` reads and clears those.
+
 ## The Pipeline
 
 When you tell Substrate to build something, it runs through up to **six phases** — auto-detecting which phase to start from based on what artifacts already exist.
@@ -290,6 +314,25 @@ After the pipeline completes, the supervisor:
 3. **Runs A/B experiments** — applies each recommendation in an isolated worktree, re-runs affected stories, compares metrics
 4. **Verdicts**: IMPROVED changes are kept and auto-PRed; REGRESSED changes are discarded
 
+### Post-Run Review
+
+Two commands turn a finished run into actionable operator output:
+
+```bash
+# Structured per-run completion report
+substrate report --run latest                    # per-story outcomes + escalation diagnostics
+substrate report --run latest --verify-ac        # appends AC-to-Test traceability matrix
+substrate report --run latest --output-format json
+
+# Path A reconciliation — when pipeline reports failed but tree is coherent
+substrate reconcile-from-disk --dry-run          # report without mutating Dolt
+substrate reconcile-from-disk --yes              # mark stories complete without prompting
+```
+
+`substrate report` resolves the active run via the canonical chain — explicit `--run-id` → `.substrate/current-run-id` → Dolt fallback — and surfaces story outcomes (verified / recovered / escalated / failed), cost vs ceiling, escalation diagnostics, and any operator halt notifications written to `.substrate/notifications/`. `--verify-ac` runs heuristic word-overlap matching between AC text and test names to expose ACs without test coverage.
+
+`substrate reconcile-from-disk` is the Path A primitive. When a pipeline reports failure but `git status` + the project gates show the implementation is on disk and passing (a class of false-failures the cross-story-race auto-recovery in Epic 70 addresses but doesn't fully eliminate), this command detects working-tree changes since the run started, runs the gates, and prompts to mark stories complete in Dolt.
+
 ### Metrics, Cost, and Diff
 
 ```bash
@@ -495,7 +538,10 @@ These commands are typically invoked by your AI assistant during pipeline operat
 | `substrate run --from <phase>` | Start from a specific phase |
 | `substrate run --stop-after <phase>` | Stop pipeline after this phase |
 | `substrate run --engine graph` | Use the graph execution engine |
-| `substrate run --halt-on <severity>` | Halt on escalation severity (`all`/`critical`/`none`) |
+| `substrate run --halt-on <severity>` | Decision Router halt policy (`all` / `critical` / `none`) — see [Autonomy Modes](#autonomy-modes) |
+| `substrate run --non-interactive` | Suppress all stdin prompts and apply default actions; required for CI/CD |
+| `substrate run --verify-ac` | On-demand AC-to-Test traceability matrix |
+| `substrate run --cost-ceiling <usd>` | Halt run when cumulative cost crosses this threshold |
 | `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 --help-agent` | Print agent instruction prompt fragment |
@@ -534,6 +580,9 @@ These commands are typically invoked by your AI assistant during pipeline operat
 
 | Command | Description |
 |---|---|
+| `substrate report [--run <id\|latest>]` | Per-run completion report — outcomes, cost, escalation diagnostics, halt notifications |
+| `substrate report --verify-ac` | Append heuristic AC-to-Test traceability matrix to the report |
+| `substrate reconcile-from-disk [--dry-run] [--yes]` | Path A reconciliation — gates green + tree coherent ⇒ mark stories complete in Dolt |
 | `substrate annotate` | Tag verification finding as confirmed-defect / false-positive / probe-bug |
 | `substrate probe-author dispatch` | Manually invoke probe-author phase against a single story file |
 | `substrate contracts` | Show contract declarations and verification status |

package/dist/cli/index.js

@@ -5,7 +5,7 @@ import { createEventBus } from "../helpers-CElYrONe.js";
 import { AdapterRegistry$1 as AdapterRegistry, BudgetConfigSchema, CURRENT_CONFIG_FORMAT_VERSION, CURRENT_TASK_GRAPH_VERSION, ConfigError$1 as 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, createDoltClient, createPipelineRun, getActiveDecisions, getAllCostEntriesFiltered, getBaselineRunMetrics, getDecisionsByCategory, getDecisionsByPhaseForRun, getLatestCompletedRun, getLatestRun, getPipelineRunById, getPlanningCostTotal, getRetryableEscalations, getRunMetrics, getRunningPipelineRuns, getSessionCostSummary, getSessionCostSummaryFiltered, getStoryMetricsForRun, getTokenUsageSummary, incrementRunRestarts, initSchema, initializeDolt, listRunMetrics, loadParentRunDecisions, supersedeDecision, tagRunAsBaseline, updatePipelineRun } from "../dist-K_RRWnBX.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-BFN1ujjW.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-Dg4GbCA7.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-UrEvbpcE.js";
 import "../errors-pSiZbn6e.js";
 import "../routing-DFxoKHDt.js";
 import { WorkGraphRepository } from "../work-graph-repository-DZyJv5pV.js";
@@ -9037,7 +9037,7 @@ async function runSupervisorAction(options, deps = {}) {
 								await initSchema(expAdapter);
 								const { runRunAction: runPipeline } = await import(
 									/* @vite-ignore */
-									"../run-CFYkkZ8e.js"
+									"../run-e-pS5Tv5.js"
 );
 								const runStoryFn = async (opts) => {
 									const exitCode = await runPipeline({

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

@@ -38,16 +38,33 @@ Check process health:
 substrate health --output-format json
 ```
 
+### Autonomy Modes
+
+Three-step gradient. Choose by how much operator attention the run gets:
+
+| Mode | Invocation | Halts on |
+|---|---|---|
+| Attended | `substrate run --halt-on all` | Every decision |
+| Supervised (default) | `substrate run` | Critical + fatal (cost-ceiling, build-fail, scope-violation) |
+| Autonomous | `substrate run --halt-on none --non-interactive --events --output-format json` | Only fatal |
+
+Exit codes from autonomous runs: 0 = succeeded or auto-recovered, 1 = some escalated (run completed), 2 = run-level failure.
+
+The Recovery Engine runs a 3-tier auto-fix ladder before any halt — Tier A retries with extra context, Tier B drafts a re-scope proposal, Tier C halts for an operator prompt. Re-scope proposals collect on the run manifest as `pending_proposals[]`. When a halt is required, an operator notification is written to `.substrate/notifications/<run-id>-<timestamp>.json` and surfaced by `substrate report`.
+
 ### After Pipeline Completes
 
 1. Summarize results: X succeeded, Y failed, Z escalated
-2. Check metrics: `substrate metrics --output-format json`
+2. Run the post-run report: `substrate report --run latest` (per-story outcomes + escalation diagnostics + halt notifications). Add `--verify-ac` for AC-to-Test traceability.
+3. If pipeline reported failed but tree looks coherent: `substrate reconcile-from-disk --dry-run` (Path A reconciliation). If gates green, run without `--dry-run` to mark stories complete.
+4. Check historical metrics: `substrate metrics --output-format json`
 
 ### Handling Escalations
 
 - On story escalation: read the flagged files and issues, propose a fix, ask the user before applying
 - On minor fix verdict (NEEDS_MINOR_FIXES): offer to fix automatically
 - On build verification failure: read the build output, diagnose the error, propose a fix
+- On reported failure with coherent working tree: run `substrate reconcile-from-disk --dry-run` first; treat its output as source of truth before re-dispatching
 - Never re-run a failed story without explicit user confirmation
 
 ### Key Commands
@@ -55,9 +72,20 @@ substrate health --output-format json
 | Command | Purpose |
 |---|---|
 | `substrate run --events` | Run pipeline with NDJSON event stream |
+| `substrate run --halt-on <severity>` | Halt policy: `all` / `critical` (default) / `none` |
+| `substrate run --non-interactive` | Suppress stdin prompts |
+| `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 |
 | `substrate status --output-format json` | Poll current pipeline state |
 | `substrate health --output-format json` | Check process health |
 | `substrate metrics --output-format json` | View historical run metrics |
 | `substrate resume` | Resume an interrupted pipeline run |
 | `substrate run --help-agent` | Full agent instruction reference |
+
+### Operator Files (`.substrate/`)
+
+- `.substrate/runs/<run-id>.json` — per-run manifest (one file per run; not an aggregate)
+- `.substrate/current-run-id` — plain text file with the latest run ID
+- `.substrate/notifications/<run-id>-<timestamp>.json` — operator halt notifications (deleted by `substrate report` after read)
 <!-- substrate:end -->

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

@@ -48,11 +48,27 @@ substrate supervisor --output-format json
 
 **Interpreting silence:** No output for 5 minutes = normal (agent is working). No output for 15+ minutes = likely stalled. Use `substrate health` to confirm, then consider killing and resuming.
 
+### Autonomy Modes
+
+Substrate has a three-step autonomy gradient. Choose mode by how much operator attention the run gets:
+
+| Mode | Invocation | Halts on |
+|---|---|---|
+| Attended | `substrate run --halt-on all` | Every decision (info, warning, critical, fatal) |
+| Supervised *(default)* | `substrate run` | Critical + fatal (cost-ceiling, build-fail, scope-violation) |
+| Autonomous | `substrate run --halt-on none --non-interactive --events --output-format json` | Only fatal — scope violations always halt regardless |
+
+Exit codes from autonomous runs: `0` = all stories succeeded or auto-recovered; `1` = some escalated (run completed); `2` = run-level failure (cost ceiling, fatal halt, orchestrator died).
+
+The Recovery Engine runs a 3-tier auto-fix ladder before any halt — Tier A retries with extra context (build-fail, missing test coverage, AC missing evidence), Tier B drafts a re-scope proposal, Tier C halts for an operator prompt. Re-scope proposals collect on the run manifest as `pending_proposals[]` for next-morning review; back-pressure pauses dispatching at `>= 2` (work-graph-aware) or `>= 5` (safety valve). When a halt is required, an operator notification is written to `.substrate/notifications/<run-id>-<timestamp>.json` and surfaced by `substrate report`.
+
 ### After Pipeline Completes
 
 1. **Summarize results** conversationally: X succeeded, Y failed, Z escalated
-2. **Check metrics**: `substrate metrics --output-format json`
-3. **Read analysis** (if supervisor was attached): `substrate metrics --analysis <run_id> --output-format json`
+2. **Run the post-run report**: `substrate report --run latest` (per-story outcomes + escalation diagnostics + halt notifications). Add `--verify-ac` for AC-to-Test traceability.
+3. **If pipeline reported failed but tree looks coherent**: `substrate reconcile-from-disk --dry-run` — Path A reconciliation. If gates green and the working tree shows the implementation is on disk, run without `--dry-run` (or with `--yes`) to mark stories complete in Dolt.
+4. **Check historical metrics**: `substrate metrics --output-format json`
+5. **Read analysis** (if supervisor was attached): `substrate metrics --analysis <run_id> --output-format json`
 
 ### Handling Escalations and Failures
 
@@ -60,6 +76,7 @@ substrate supervisor --output-format json
 - **On minor fix verdict** (`NEEDS_MINOR_FIXES`): offer to fix automatically
 - **On build verification failure**: read the build output, diagnose the compiler error, propose a fix
 - **On contract mismatch** (`pipeline:contract-mismatch`): cross-story interface conflict — read both stories' files, reconcile types manually
+- **On reported failure with coherent working tree**: run `substrate reconcile-from-disk --dry-run` first; treat the dry-run output as the source of truth before re-dispatching the story
 - **Never re-run a failed story** without explicit user confirmation
 
 ### Key Commands Reference
@@ -67,15 +84,27 @@ substrate supervisor --output-format json
 | Command | Purpose |
 |---|---|
 | `substrate run --events` | Run pipeline with NDJSON event stream |
+| `substrate run --halt-on <severity>` | Decision Router halt policy: `all` / `critical` (default) / `none` |
+| `substrate run --non-interactive` | Suppress stdin prompts; combine with `--halt-on none` for fully autonomous |
+| `substrate run --verify-ac` | On-demand AC-to-Test traceability matrix |
+| `substrate report [--run <id\|latest>]` | Per-run completion report — outcomes, cost, escalation diagnostics, halt notifications |
+| `substrate report --verify-ac` | Append AC-to-Test traceability matrix to the report |
+| `substrate reconcile-from-disk [--dry-run] [--yes]` | Path A reconciliation when pipeline reports failed but tree is coherent |
 | `substrate supervisor --output-format json` | Monitor active run with auto-recovery and post-run analysis |
 | `substrate status --output-format json` | Poll current pipeline state |
 | `substrate health --output-format json` | Check process health and stall detection |
 | `substrate metrics --output-format json` | View historical run metrics |
 | `substrate resume` | Resume an interrupted pipeline run |
-| `substrate run --help-agent` | Full agent instruction reference (487 lines) |
+| `substrate run --help-agent` | Full agent instruction reference |
 | `substrate diff <story>` | Show row-level state changes for a story (requires Dolt) |
 | `substrate history` | View Dolt commit log for pipeline state changes (requires Dolt) |
 
+### Operator Files (`.substrate/`)
+
+- `.substrate/runs/<run-id>.json` — per-run manifest (one file per run; NOT an aggregate `manifest.json` — that file does not exist)
+- `.substrate/current-run-id` — plain text file with the latest run ID; consulted by canonical run-discovery
+- `.substrate/notifications/<run-id>-<timestamp>.json` — operator halt notifications written by the Recovery Engine; deleted by `substrate report` after read
+
 ### State Backend
 
 Substrate uses Dolt for versioned pipeline state by default. Run `substrate init` to set it up automatically if Dolt is on PATH. Features that require Dolt: `substrate diff`, `substrate history`, OTEL observability persistence, and context engineering repo-map storage.

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

@@ -38,16 +38,33 @@ Check process health:
 substrate health --output-format json
 ```
 
+### Autonomy Modes
+
+Three-step gradient. Choose by how much operator attention the run gets:
+
+| Mode | Invocation | Halts on |
+|---|---|---|
+| Attended | `substrate run --halt-on all` | Every decision |
+| Supervised (default) | `substrate run` | Critical + fatal (cost-ceiling, build-fail, scope-violation) |
+| Autonomous | `substrate run --halt-on none --non-interactive --events --output-format json` | Only fatal |
+
+Exit codes from autonomous runs: 0 = succeeded or auto-recovered, 1 = some escalated (run completed), 2 = run-level failure.
+
+The Recovery Engine runs a 3-tier auto-fix ladder before any halt — Tier A retries with extra context, Tier B drafts a re-scope proposal, Tier C halts for an operator prompt. Re-scope proposals collect on the run manifest as `pending_proposals[]`. When a halt is required, an operator notification is written to `.substrate/notifications/<run-id>-<timestamp>.json` and surfaced by `substrate report`.
+
 ### After Pipeline Completes
 
 1. Summarize results: X succeeded, Y failed, Z escalated
-2. Check metrics: `substrate metrics --output-format json`
+2. Run the post-run report: `substrate report --run latest` (per-story outcomes + escalation diagnostics + halt notifications). Add `--verify-ac` for AC-to-Test traceability.
+3. If pipeline reported failed but tree looks coherent: `substrate reconcile-from-disk --dry-run` (Path A reconciliation). If gates green, run without `--dry-run` to mark stories complete.
+4. Check historical metrics: `substrate metrics --output-format json`
 
 ### Handling Escalations
 
 - On story escalation: read the flagged files and issues, propose a fix, ask the user before applying
 - On minor fix verdict (NEEDS_MINOR_FIXES): offer to fix automatically
 - On build verification failure: read the build output, diagnose the error, propose a fix
+- On reported failure with coherent working tree: run `substrate reconcile-from-disk --dry-run` first; treat its output as source of truth before re-dispatching
 - Never re-run a failed story without explicit user confirmation
 
 ### Key Commands
@@ -55,9 +72,20 @@ substrate health --output-format json
 | Command | Purpose |
 |---|---|
 | `substrate run --events` | Run pipeline with NDJSON event stream |
+| `substrate run --halt-on <severity>` | Halt policy: `all` / `critical` (default) / `none` |
+| `substrate run --non-interactive` | Suppress stdin prompts |
+| `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 |
 | `substrate status --output-format json` | Poll current pipeline state |
 | `substrate health --output-format json` | Check process health |
 | `substrate metrics --output-format json` | View historical run metrics |
 | `substrate resume` | Resume an interrupted pipeline run |
 | `substrate run --help-agent` | Full agent instruction reference |
+
+### Operator Files (`.substrate/`)
+
+- `.substrate/runs/<run-id>.json` — per-run manifest (one file per run; not an aggregate)
+- `.substrate/current-run-id` — plain text file with the latest run ID
+- `.substrate/notifications/<run-id>-<timestamp>.json` — operator halt notifications (deleted by `substrate report` after read)
 <!-- substrate:end -->

package/dist/{run-Dg4GbCA7.js → run-UrEvbpcE.js}

@@ -1831,6 +1831,7 @@ async function resolvePackageVersion(startDir) {
 	const __dirname = dirname(__filename);
 	const base = startDir ?? __dirname;
 	const paths = [
+		join(base, "../package.json"),
 		join(base, "../../package.json"),
 		join(base, "../../../package.json"),
 		join(base, "../../../../package.json")
@@ -1887,6 +1888,12 @@ Options:
 - \`--from <phase>\` — Start from this phase: research, analysis, planning, solutioning, implementation
 - \`--stop-after <phase>\` — Stop pipeline after this phase completes
 - \`--concurrency <n>\` — Maximum parallel conflict groups (default: 3)
+- \`--engine <linear|graph>\` — Pipeline execution engine (default: linear)
+- \`--max-review-cycles <n>\` — Per-story review cycles (default: 2; use 3 for migrations / interface extraction)
+- \`--cost-ceiling <usd>\` — Halt the pipeline when cumulative cost crosses this threshold
+- \`--halt-on <severity>\` — Decision Router halt policy: \`all\` halts on every decision, \`critical\` (default) halts only on cost-ceiling / build-fail / scope-violation, \`none\` halts only on fatal
+- \`--non-interactive\` — Suppress all stdin prompts and apply default actions; required for CI/CD. Combine with \`--halt-on none\` for fully autonomous overnight runs
+- \`--verify-ac\` — On-demand AC-to-Test traceability matrix (heuristic word-overlap matching between AC text and test names)
 - \`--output-format <format>\` — Output format: human (default) or json
 - \`--concept <text>\` — Inline concept text (required when --from analysis)
 - \`--research\` — Enable the research phase even if not set in the pack config
@@ -1904,8 +1911,28 @@ substrate run --events --stories 7-1,7-2
 
 # Run pipeline with human-readable output (default)
 substrate run
+
+# Fully autonomous (CI/CD canonical pattern):
+substrate run --halt-on none --non-interactive --events --output-format json
 \`\`\`
 
+#### Autonomy Modes
+
+Pick the operator-attention level for the run:
+
+| Mode | Invocation | Halts on |
+|---|---|---|
+| Attended | \`substrate run --halt-on all\` | Every decision (info, warning, critical, fatal) |
+| Supervised (default) | \`substrate run\` | Critical + fatal (cost-ceiling, build-fail, scope-violation) |
+| Autonomous | \`substrate run --halt-on none --non-interactive --events --output-format json\` | Only fatal — scope violations always halt regardless |
+
+Exit codes from autonomous runs:
+- \`0\` — all stories succeeded or were auto-recovered.
+- \`1\` — some stories escalated; the run completed.
+- \`2\` — run-level failure (cost ceiling, fatal halt, orchestrator died).
+
+After every autonomous run, review the result with \`substrate report --run latest\`.
+
 ### substrate status
 Show status of the most recent pipeline run.
 
@@ -2000,6 +2027,44 @@ substrate brainstorm [options]
 
 Session commands: \`!wrap\` (save & exit), \`!quit\` (exit without saving), \`!help\`
 
+### substrate report
+Structured per-run completion report — story outcomes, cost vs ceiling, escalation diagnostics, and operator halt notifications. Resolves the active run via the canonical chain (explicit \`--run-id\` → \`.substrate/current-run-id\` → Dolt fallback).
+
+\`\`\`
+substrate report [--run <id|latest>] [--output-format human|json] [--verify-ac]
+\`\`\`
+
+Options:
+- \`--run <id|latest>\` — Run ID, or \`latest\` (default) to resolve via the canonical chain
+- \`--output-format <format>\` — Output format: human (default) or json
+- \`--verify-ac\` — Append an AC-to-Test traceability matrix (heuristic word-overlap matching between AC text and test names)
+
+When \`substrate run\` is invoked with \`--halt-on\`, the Recovery Engine writes operator halt notifications to \`.substrate/notifications/<run-id>-<timestamp>.json\`. \`substrate report\` reads and clears those files, surfacing each one in its output.
+
+### substrate reconcile-from-disk
+Path A reconciliation primitive — when the pipeline reports failure but the working tree is coherent (gates green, files durable), this command detects working-tree changes since the run started, runs the project's gates, and prompts to mark stories complete in Dolt.
+
+\`\`\`
+substrate reconcile-from-disk [--run-id <id>] [--dry-run] [--yes] [--output-format json]
+\`\`\`
+
+Options:
+- \`--run-id <id>\` — Run ID to reconcile (defaults to latest)
+- \`--dry-run\` — Report what would change without mutating Dolt
+- \`--yes\` — Skip the confirmation prompt (e.g., for non-interactive use after \`--dry-run\` review)
+- \`--output-format <format>\` — Output format: human (default) or json
+
+Use this when \`substrate report\` shows stories \`failed\` but \`git status\` + the project gates indicate the implementation is on disk and passing. The pipeline's failure verdict can be misleading after auto-recovery races; reconcile-from-disk codifies the manual fix.
+
+## Operator Files (\`.substrate/\`)
+
+These on-disk files back the new autonomy commands. External monitors (dashboards, Slack bots) can also tail them.
+
+- \`.substrate/runs/<run-id>.json\` — per-run manifest (one file per run; NOT an aggregate \`manifest.json\`). Production format: do not invent an aggregate file — it does not exist.
+- \`.substrate/current-run-id\` — plain text file containing the latest run ID; consulted by the canonical run-discovery chain.
+- \`.substrate/notifications/<run-id>-<timestamp>.json\` — operator halt notifications written by the Recovery Engine when \`--halt-on\` triggers; deleted by \`substrate report\` after read.
+- \`pending_proposals[]\` field in the run manifest — Recovery Engine Tier B re-scope proposals collected here for next-morning operator review. Back-pressure pauses dispatching at \`>= 2\` proposals (work-graph-aware) or \`>= 5\` (safety valve).
+
 ## Environment Variables
 
 - \`SUBSTRATE_MEMORY_THRESHOLD_MB\` — Override the free-memory threshold (in MB) for agent dispatch. Default: 512. On macOS, the conservative memory detection may report low availability even when ample RAM exists. Lower this (e.g., 256) if pipelines stall due to memory pressure false positives.
@@ -46042,4 +46107,4 @@ function registerRunCommand(program, _version = "0.0.0", projectRoot = process.c
 
 //#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-Dg4GbCA7.js.map
+//# sourceMappingURL=run-UrEvbpcE.js.map

package/dist/{run-CFYkkZ8e.js → run-e-pS5Tv5.js}

@@ -3,7 +3,7 @@ import "./logger-KeHncl-f.js";
 import "./helpers-CElYrONe.js";
 import "./dist-K_RRWnBX.js";
 import "./manifest-read-BFN1ujjW.js";
-import { normalizeGraphSummaryToStatus, registerRunCommand, resolveMaxReviewCycles, resolveProbeAuthorStateIntegrating, runRunAction, wireNdjsonEmitter } from "./run-Dg4GbCA7.js";
+import { normalizeGraphSummaryToStatus, registerRunCommand, resolveMaxReviewCycles, resolveProbeAuthorStateIntegrating, runRunAction, wireNdjsonEmitter } from "./run-UrEvbpcE.js";
 import "./routing-DFxoKHDt.js";
 import "./work-graph-repository-DZyJv5pV.js";
 import "./decisions-CzSIEeGP.js";

package/package.json

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