scrumrun 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+## 2.3.0 - 2026-07-23
+
+### Added
+
+- Stable error catalog in [`lib/errors.js`](lib/errors.js) exposing a `ScrumRunError` class plus `describe`/`codes` accessors, and a human view in [`docs/ERROR-CODES.md`](docs/ERROR-CODES.md). Codes follow `SR-E-NNN` with reserved ranges per subsystem and are guaranteed stable once assigned.
+- `sc config doctor --recover --dry-run` previews every pending kernel transaction, describes each planned rollback or commit-verification, warns about unsafe paths, journal integrity failures, or owner-touched files, and exits non-zero when at least one transaction cannot be recovered safely — never writes.
+- Invariant `I-22`: the semantic index's declared search backend must match the runtime's actual capabilities. Conformance now emits a `high` `SEARCH_BACKEND_MISMATCH` finding when a cache advertises `fts5` on a runtime that cannot execute it, replacing the previous lazy-rebuild-only behaviour that hid the drift.
+- `previewPendingRecovery` exported from `lib/v2/transaction` for library consumers.
+- Property-based intake tests: 200 adversarial inputs per run (NUL bytes, ANSI escapes, homoglyphs, injection shapes, oversize strings) proving `planRequest` is total, never throws unclassified errors, and does not mutate `.scrumrun/`.
+
+### Changed
+
+- `sc plan run --render RUN-NNN` prints the ledger as a chronological, human-readable timeline with actors, transitions, reasons, evidence, and total span. Complements the existing `--show` (raw Markdown) so auditing no longer requires reading JSON blocks by hand.
+- `sc plan run --stats [--task TASK-NNN] [--feature FEAT-NNN] [--sprint SPRINT-NNN] [--json]` aggregates every Run in the project into status mix, p50/p95/max time in `VALIDATING` and `EXECUTING`, retry counts per Task, completions after prior failure, and guardrail/mutation event totals — computed straight over the canonical ledger, no separate index.
+- New modules `lib/commands/run-render` and `lib/commands/run-stats` expose `renderRun`, `renderRunFromDisk`, `computeStats`, and `renderStats` for library consumers.
+
+### Documentation
+
+- Added [`docs/QUICKSTART.md`](docs/QUICKSTART.md): first Run in under 10 minutes, no `SPEC.md` reading required. Now includes the new `sc plan run --render` and `sc plan run --stats` commands.
+- Added [`docs/DEMO.md`](docs/DEMO.md) with the exact asciinema script for a 40-second intake → approve → render → stats demo the owner can record and embed in the README and LP.
+- Added [`docs/INDEX.md`](docs/INDEX.md) with reading-order recommendations by intent (fresh install, integrating a client, upgrading from v1, browsing rationale, troubleshooting).
+- Added a **Terminology quick reference** in the README that maps internal names (`Mutation Gateway`, `Policy Engine`, `Guardrail obligation`, `Canonical projection`, `Executable schema`) to friendlier user-facing forms; both are treated as synonyms.
+- Bumped README package badge to `2.2.0` and linked the Quickstart from the top.
+- Created `.scrumrun/features/FEAT-001.md` to record the ongoing "Method 2.x — Onboarding, Visible Auditability, and Stable Diagnostics" initiative and its four-wave scope.
+
 ## 2.2.0 - 2026-07-23
 
 ### Security

package/README.md

@@ -4,7 +4,9 @@
 
 ScrumRun gives an agent a small command surface and a precise project memory: what should be done, how each attempt happened, which decisions constrain the code, and why the architecture exists in its current form.
 
-**Package:** `2.1.1` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
+**Package:** `2.3.0` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
+
+**New here?** Read the [Quickstart](docs/QUICKSTART.md) — first Run in under 10 minutes, no `SPEC.md` reading required. Full docs map in [`docs/INDEX.md`](docs/INDEX.md).
 
 ## The model
 
@@ -75,6 +77,20 @@ Each Run contains a machine-validated event ledger. Events have stable ids such
 
 Linked Task/Run writes use a durable ignored transaction journal. Captured failures roll back immediately; interrupted operations are recovered byte-exactly on retry or through explicit `doctor --recover`. Read-only audit reports pending recovery and never repairs state silently.
 
+## Terminology quick reference
+
+Internal names in the code and spec are precise but occasionally heavy. When they surface in CLI output or docs, the shorter form works too.
+
+| Internal (SPEC/CORE) | User-facing (docs, output) | What it means |
+|---|---|---|
+| Mutation Gateway | edit permit | The 15-minute, path-scoped permission an approved Run needs to edit source files. |
+| Policy Engine | guardrail check | The executable evaluation of every active `GR-NNN` rule before planning and before execution. |
+| Guardrail obligation | pending guardrail | A deferred guardrail check persisted on a Run; must resolve before completion. |
+| Canonical projection | derived view | Generated navigation files such as `state.md` and `map.md` — always regenerable, never authority. |
+| Executable schema | frozen contract | The single machine-checked shape for ids, transitions, and cardinalities. |
+
+The short forms are synonyms — safe to use in issues, PRs, and everyday conversation.
+
 ## Semantic project memory
 
 Canonical memory is human-readable Markdown:
@@ -159,6 +175,32 @@ npx scrumrun@latest doctor codex --strict
 
 Approved Runs persist every deferred result as an append-only obligation and bind the exact policy plus workspace baseline. Material source edits use a 15-minute, path-scoped Mutation Gateway permit. Recording verifies before/after hashes, owner/read-only scope, symlinks, new secret-like content, and workspace drift. Validation and completion fail closed when edits bypass that chain or obligations remain unresolved.
 
+### Owner-controlled allowlist for descriptive files
+
+Secret-like content detection is canonical-policy-level and applies to every file outside `vault.local.md`. Owners can exempt specific **non-canonical descriptive paths** from the keyword heuristic by adding frontmatter to `.scrumrun/config.md`:
+
+```yaml
+---
+allow_secrets_in:
+  - goals/main/history.md
+  - goals/main/sprint.md
+  - docs/migration-notes/
+  - "*.legacy.md"
+---
+```
+
+Supported matchers per entry:
+
+- exact path (`goals/main/history.md`)
+- directory prefix ending in `/` (`docs/legacy/`)
+- glob pattern (`*.legacy.md`)
+
+Rules:
+
+- Canonical artifacts (Task, Sprint, Run, Feature, Review, Memory) are **never** eligible — a secret in a canonical file always fails conformance.
+- High-confidence shapes (`sk-…`, `AKIA…`, JWT three-part tokens, PEM private keys, long bearer tokens) are never exempted regardless of path.
+- The allowlist is recorded as evidence of an explicit owner decision and is reviewed by `doctor`.
+
 ## Useful commands
 
 ```bash
@@ -186,19 +228,35 @@ npx scrumrun@latest sc knowledge study calculateFinalPrice
 # rebuild or inspect the derived graph
 npx scrumrun@latest sc knowledge map --build
 npx scrumrun@latest sc knowledge map --show
+
+# read a Run as a human timeline instead of raw ledger JSON
+npx scrumrun@latest sc plan run --render RUN-001
+
+# aggregate every Run in the project (p50/p95 durations, retries, guardrail counts)
+npx scrumrun@latest sc plan run --stats
+npx scrumrun@latest sc plan run --stats --task TASK-001 --json
+
+# preview a canonical-transaction recovery before touching disk
+npx scrumrun@latest sc config doctor --recover --dry-run
 ```
 
 The command manifest in `lib/commands/manifest.js` generates help and compatibility adapters, preventing client grammar drift. A recorded artifact Review cannot self-declare success: ScrumRun reruns the audit and derives the `REV-NNN` verdict from the result.
 
+Every user-facing failure carries a stable [`SR-E-NNN` code](docs/ERROR-CODES.md) with a permanent meaning, a short summary, and an exact remediation.
+
 ## Documentation
 
 | File | Purpose |
 |---|---|
+| [`docs/QUICKSTART.md`](docs/QUICKSTART.md) | First Run in under 10 minutes, no `SPEC.md` reading required. |
+| [`docs/INDEX.md`](docs/INDEX.md) | Reading-order recommendations across every doc, by intent. |
 | [`CORE.md`](./CORE.md) | Operational runtime guide for agents. |
 | [`SPEC.md`](./SPEC.md) | Normative 2.0 state machines, invariants, and conformance rules. |
 | [`DECISIONS.md`](./DECISIONS.md) | Architectural decisions and trade-offs. |
+| [`docs/ERROR-CODES.md`](docs/ERROR-CODES.md) | Stable `SR-E-NNN` catalog with remediation for every failure. |
 | `MIGRATION-1-to-2.md` | Upgrade, verification, rollback, and recovery guide. |
 | [`docs/RELEASE-SCORECARD.md`](docs/RELEASE-SCORECARD.md) | Evidence-backed local readiness scores and residual release risks. |
+| [`docs/DEMO.md`](docs/DEMO.md) | Script for a 40-second asciinema demo of the full intake → approve → render → stats loop. |
 
 ScrumRun remains client-independent: any agent that reads Markdown can follow `CORE.md`; Codex, Claude Code, and OpenCode integrations are accelerators.
 

package/SPEC.md

@@ -308,6 +308,7 @@ Legacy sprint entries become Tasks. History entries become Runs only with an evi
 - **I-19** Code intelligence is derived, adapter-based, fingerprinted, and cannot silently confirm memory.
 - **I-20** Post-validation learning proposes candidates and never blocks Task/Run completion.
 - **I-21** Material mutations are policy-bound, path-scoped, hash-verified, append-only, and fail closed on bypass; unresolved Guardrail obligations block completion.
+- **I-22** The semantic index's declared search backend must match the runtime capabilities of the current Node.js SQLite build; conformance flags a mismatch instead of relying on lazy runtime fallback.
 
 ## 11. Command grammar
 
@@ -325,7 +326,7 @@ Unknown syntax fails deterministically and never guesses a mutation.
 
 An implementation may claim ScrumRun method 2.0.0 only when it:
 
-1. passes positive and negative tests for I-01 through I-21;
+1. passes positive and negative tests for I-01 through I-22;
 2. enforces every exposed state machine and schema;
 3. proves read-only intake and dry-run migration through full-tree fingerprints;
 4. proves migration failure recovery, rollback safety, and vault exclusion;

package/bin/scrumrun.js

@@ -25,7 +25,7 @@ const { recordArtifactReview } = require(path.join(root, "lib", "runtime", "revi
 const { createMemory, listMemory, showMemory, transitionMemory } = require(path.join(root, "lib", "memory", "service"));
 const { indexPath, indexStatus, mapStatus, queryIndex, rebuildIndex, writeMap } = require(path.join(root, "lib", "memory", "index"));
 const { auditProject } = require(path.join(root, "lib", "v2", "conformance"));
-const { recoverPendingTransactions } = require(path.join(root, "lib", "v2", "transaction"));
+const { recoverPendingTransactions, previewPendingRecovery } = require(path.join(root, "lib", "v2", "transaction"));
 const { containsSecret } = require(path.join(root, "lib", "security", "secrets"));
 
 const COMMANDS = ["sc"];
@@ -1371,6 +1371,37 @@ function executeRootRoute(route) {
     console.log(`Created retry ${result.run.id} for ${result.task.id} (attempt ${result.run.attempt}).`);
     return;
   }
+  if (noun === "plan" && subject === "run" && routeArgs[0] === "--render") {
+    const { renderRunFromDisk } = require(path.join(root, "lib", "commands", "run-render"));
+    const runId = routeArgs[1];
+    if (!runId) {
+      console.error("--render requires a RUN-NNN id.");
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      console.log(renderRunFromDisk(process.cwd(), runId));
+    } catch (error) {
+      console.error(error.message);
+      process.exitCode = 1;
+    }
+    return;
+  }
+  if (noun === "plan" && subject === "run" && routeArgs[0] === "--stats") {
+    const { computeStats, renderStats } = require(path.join(root, "lib", "commands", "run-stats"));
+    const filters = {
+      task: optionValue(routeArgs.slice(1), "--task"),
+      feature: optionValue(routeArgs.slice(1), "--feature"),
+      sprint: optionValue(routeArgs.slice(1), "--sprint")
+    };
+    const summary = computeStats(process.cwd(), filters);
+    if (routeArgs.includes("--json")) {
+      console.log(JSON.stringify({ filters, summary }, null, 2));
+    } else {
+      console.log(renderStats(summary, filters));
+    }
+    return;
+  }
   if (noun === "plan" && ["task", "run"].includes(subject) && ["--list", "--show"].includes(routeArgs[0])) {
     const repository = new ArtifactRepository(projectFile());
     if (routeArgs[0] === "--list") {
@@ -1462,7 +1493,7 @@ function executeRootRoute(route) {
   if (noun === "config" && subject === "migrate") return runMigration(routeArgs);
   if (noun === "config" && subject === "doctor") {
     const target = ["all", "codex", "opencode", "claude"].includes(routeArgs[0]) ? routeArgs[0] : "all";
-    return doctor(target, { strict: routeArgs.includes("--strict"), recover: routeArgs.includes("--recover") });
+    return doctor(target, { strict: routeArgs.includes("--strict"), recover: routeArgs.includes("--recover"), dryRun: routeArgs.includes("--dry-run") });
   }
   if (noun === "config" && subject === "update") {
     const target = ["all", "codex", "opencode", "claude"].includes(routeArgs[0]) ? routeArgs[0] : "all";
@@ -2279,7 +2310,7 @@ function runMigration(parts) {
   }
 }
 
-function doctor(target = "all", { compatibility = false, strict = false, recover = false } = {}) {
+function doctor(target = "all", { compatibility = false, strict = false, recover = false, dryRun = false } = {}) {
   const home = os.homedir();
   const checks = [];
   const commands = compatibility ? [...COMMANDS, ...COMPATIBILITY_COMMANDS] : COMMANDS;
@@ -2288,6 +2319,33 @@ function doctor(target = "all", { compatibility = false, strict = false, recover
   if (recover) {
     const scrumDir = path.join(process.cwd(), ".scrumrun");
     if (!fs.existsSync(scrumDir)) throw new Error("Cannot recover transactions outside a ScrumRun project.");
+    if (dryRun) {
+      const preview = previewPendingRecovery(scrumDir);
+      if (preview.errors.length) {
+        for (const err of preview.errors) console.error(`dry-run: ${err}`);
+        process.exitCode = 1;
+        return;
+      }
+      if (!preview.plans.length) {
+        console.log("dry-run: no pending kernel transactions to recover");
+      } else {
+        console.log(`dry-run: ${preview.plans.length} pending transaction(s) would be handled as follows:`);
+        for (const plan of preview.plans) {
+          const header = `  ${plan.id} (${plan.status}) → ${plan.action}${plan.name ? `  [${plan.name}]` : ""}`;
+          console.log(header);
+          for (const warning of plan.warnings) console.log(`    ! ${warning}`);
+          for (const file of plan.files) console.log(`    · ${file.relative} (${file.from} → ${file.to})`);
+        }
+        const blocked = preview.plans.filter((plan) => plan.action === "blocked").length;
+        if (blocked) {
+          console.log(`dry-run: ${blocked} transaction(s) cannot be recovered automatically.`);
+          process.exitCode = 1;
+        } else {
+          console.log("dry-run: safe to re-run without --dry-run to apply.");
+        }
+      }
+      return;
+    }
     const recovered = recoverPendingTransactions(scrumDir);
     console.log(recovered.length
       ? `recovered ${recovered.map((item) => `${item.id}:${item.action}`).join(", ")}`
@@ -2409,7 +2467,7 @@ if (!command || command === "--help" || command === "-h") {
   runMigration(args.slice(1));
 } else if (command === "doctor") {
   const target = ["all", "codex", "opencode", "claude"].includes(args[1]) ? args[1] : "all";
-  doctor(target, { compatibility: args.includes("--compat"), strict: args.includes("--strict"), recover: args.includes("--recover") });
+  doctor(target, { compatibility: args.includes("--compat"), strict: args.includes("--strict"), recover: args.includes("--recover"), dryRun: args.includes("--dry-run") });
 } else if (command === "claude") {
   const sub = args[1];
   if (sub === "install" || sub === "update") {

package/docs/DEMO.md

@@ -0,0 +1,67 @@
+# Demo recording script
+
+40-second asciicast that shows a real intake → approve → run → memory
+loop. Aim for a public URL you can embed in the README under the pitch.
+
+## Setup
+
+```bash
+brew install asciinema             # or: sudo apt install asciinema
+asciinema --version                # confirm >= 2.4
+```
+
+Optional but recommended: `agg` to convert the `.cast` file to an SVG or
+animated GIF for wider viewer support.
+
+## Recording
+
+```bash
+# 1. Start a clean throwaway project
+mkdir /tmp/scrumrun-demo && cd /tmp/scrumrun-demo
+git init -q
+
+# 2. Start recording
+asciinema rec -c "zsh" --idle-time-limit 2 --title "ScrumRun in 40 seconds" demo.cast
+```
+
+Inside the recording, run these commands slowly (about 5 seconds of
+reading between each), typing them yourself so viewers see the cadence:
+
+```bash
+npx scrumrun@latest install --client claude
+npx scrumrun@latest init
+npx scrumrun@latest sc plan intake "Fix duplicate charges after refresh"
+# copy the approval token printed above
+npx scrumrun@latest sc plan intake --approve <token>
+npx scrumrun@latest sc plan run --render RUN-001
+npx scrumrun@latest sc plan run --stats
+```
+
+Exit the shell (`exit`) to stop the recording.
+
+## Publishing
+
+```bash
+asciinema upload demo.cast         # returns a URL like https://asciinema.org/a/<id>
+```
+
+Or, for a self-hosted, browser-friendly SVG:
+
+```bash
+agg demo.cast demo.svg
+```
+
+## Where to link it
+
+- `README.md`, immediately after the tagline and before "The model".
+- LP hero on `scrumrun.dev`, as a small "Watch (40s)" link near the
+  `Start with ScrumRun` CTA.
+
+## Script notes
+
+- Keep it under 45 seconds. Cut any dead air on export with
+  `asciinema play --idle-time-limit 1`.
+- Use a light-on-dark terminal theme that matches the LP palette
+  (`#08090a` background, `#c9ff5c` cursor if possible).
+- Do not record real secrets — the throwaway project keeps
+  `.scrumrun/vault.local.md` empty.

package/docs/ERROR-CODES.md

@@ -0,0 +1,141 @@
+# Error codes
+
+Every failure that ScrumRun surfaces to the user carries a stable
+`SR-E-NNN` code. Codes never change meaning once assigned; retired
+entries stay in the catalog with `retired: true` so historical logs
+remain resolvable.
+
+The canonical source is [`lib/errors.js`](../lib/errors.js). This document
+is a human view of the same catalog, grouped by area.
+
+Roll-out is incremental: high-visibility error sites (intake, approval,
+run transitions, doctor, edit permits, transactions) adopt the codes
+first. Uncoded errors are still valid — they simply do not carry an
+`SR-E-NNN` prefix yet.
+
+## How to use them
+
+When a CLI output looks like:
+
+```
+SR-E-102 Run transition rejected: missing validation or learning evidence.
+```
+
+- The **code** is a stable anchor for logs, dashboards, and support
+  conversations. Grep it. Link to it.
+- The **summary** describes what went wrong.
+- The **remediation** describes what to try next; the CLI copy is
+  identical to the entry in this document.
+
+## Ranges
+
+| Range | Area |
+|---|---|
+| `SR-E-001..049` | Request and intake |
+| `SR-E-050..099` | Approvals, tokens |
+| `SR-E-100..149` | Runs and ledger |
+| `SR-E-150..199` | Guardrails, policy, obligations |
+| `SR-E-200..249` | Edit permits (Mutation Gateway) |
+| `SR-E-250..299` | Transactions and recovery |
+| `SR-E-300..349` | Memory (facts, decisions, insights, dossiers, vault) |
+| `SR-E-350..399` | Semantic index and code intelligence |
+| `SR-E-400..449` | Migration and update |
+| `SR-E-450..499` | Conformance and doctor |
+| `SR-E-500..549` | Configuration and installation |
+
+## Catalog
+
+### Request and intake
+
+| Code | Summary | Remediation |
+|---|---|---|
+| `SR-E-001` | Intake request is missing. | Provide a natural-language request or use `--request "..."`. |
+| `SR-E-002` | Intake payload contains secret-like content. | Remove the secret from the request or reference a vault entry by path. |
+| `SR-E-003` | Intake classification could not be produced. | Rephrase the request in one sentence describing the observable problem. |
+
+### Approvals
+
+| Code | Summary | Remediation |
+|---|---|---|
+| `SR-E-050` | Approval token is malformed. | Re-run the intake and copy the token exactly as printed after `Approval:`. |
+| `SR-E-051` | Approval token signature does not match this repository. | Tokens are bound to the project fingerprint. Re-run intake from the repo the change targets. |
+| `SR-E-052` | Approval token expired. | Re-run intake to obtain a fresh token before approving. |
+
+### Runs and ledger
+
+| Code | Summary | Remediation |
+|---|---|---|
+| `SR-E-100` | Run not found. | Check the RUN-NNN id with `sc plan run --list`. |
+| `SR-E-101` | Run ledger contains an invalid event. | Inspect the reported event id; use `sc plan run --render` for a human view or restore from git history. |
+| `SR-E-102` | Run transition rejected: missing validation or learning evidence. | Complete `--validate` and `--learn` with typed evidence before `--complete`. |
+| `SR-E-103` | Retry rejected because the previous Run is still active. | Complete, fail, or block the current Run before creating a retry. |
+
+### Guardrails
+
+| Code | Summary | Remediation |
+|---|---|---|
+| `SR-E-150` | Guardrail check blocked the operation. | Read the reported GR-NNN, satisfy or retire it explicitly; guardrails never bypass silently. |
+| `SR-E-151` | Guardrail obligation is still pending. | Resolve each pending guardrail via `sc plan run --satisfy-guardrail` before completing the Run. |
+| `SR-E-152` | Guardrail declaration is malformed. | Every active guardrail requires Status, Enforcement, Scope, and Rule fields; check `.scrumrun/guardrails.md`. |
+
+### Edit permits (Mutation Gateway)
+
+| Code | Summary | Remediation |
+|---|---|---|
+| `SR-E-200` | No edit permit for this path. | Request one with `sc plan run --authorize-mutation RUN-NNN --path <path>` before editing canonical or source files. |
+| `SR-E-201` | Edit permit expired. | Permits last 15 minutes. Authorize a new one and record the change immediately. |
+| `SR-E-202` | Edit permit path scope mismatch. | The permit does not cover the modified path. Request a new permit that lists it. |
+| `SR-E-203` | File hash changed unexpectedly since the permit was issued. | Someone else modified the file. Re-plan the change and request a fresh permit. |
+
+### Transactions and recovery
+
+| Code | Summary | Remediation |
+|---|---|---|
+| `SR-E-250` | Pending kernel transaction cannot be recovered automatically. | Run `sc config doctor --recover --dry-run` to preview; if it shows "would overwrite owner changes", reconcile the file manually before applying. |
+| `SR-E-251` | Journal fails integrity check. | Inspect `.scrumrun/.transactions/pending`. Do not delete; contact support or restore from backup. |
+
+### Memory
+
+| Code | Summary | Remediation |
+|---|---|---|
+| `SR-E-300` | Memory candidate rejected: missing resolvable evidence. | Attach at least one `--evidence` path or `sc knowledge <subject> --propose` before `--confirm`. |
+| `SR-E-301` | Attempt to write into vault via canonical channel. | `vault.local.md` is local-only and never indexed. Edit the file directly. |
+
+### Semantic index and code intelligence
+
+| Code | Summary | Remediation |
+|---|---|---|
+| `SR-E-350` | Semantic index is stale. | Rebuild with `sc knowledge map --build`. Cache is disposable; canonical memory is unaffected. |
+| `SR-E-351` | Search backend advertised in the cache does not match this runtime. | Delete `.scrumrun/.cache/semantic-index.sqlite` and re-run any `sc knowledge` query to rebuild against the current runtime. |
+
+### Migration
+
+| Code | Summary | Remediation |
+|---|---|---|
+| `SR-E-400` | Migration preflight failed. | Run `npx scrumrun@latest update` (dry) to see blockers, resolve them, then apply with `--migrate`. |
+| `SR-E-401` | Migration rollback requested but no backup was found. | Rollback needs the ignored byte-exact backup created during `--migrate`. Restore from version control if the backup is gone. |
+
+### Conformance and doctor
+
+| Code | Summary | Remediation |
+|---|---|---|
+| `SR-E-450` | Conformance check failed. | The reported invariant identifies the exact violation; the message includes the file and expected shape. |
+| `SR-E-451` | Installed client asset is stale. | Re-run `npx scrumrun@latest update` for the specific client. `doctor --strict` shows which files diverge. |
+
+### Configuration and installation
+
+| Code | Summary | Remediation |
+|---|---|---|
+| `SR-E-500` | ScrumRun project not initialized. | Run `npx scrumrun@latest init` in the repository root. |
+| `SR-E-501` | Unsupported Node.js runtime. | ScrumRun requires Node.js >=22.13.0 for native SQLite. Upgrade Node and retry. |
+
+## Adding a new code
+
+1. Reserve the next number in the appropriate range.
+2. Add an entry to `CATALOG` in `lib/errors.js` with `summary` and
+   `remediation`.
+3. Throw `new ScrumRunError("SR-E-XYZ", "...")` from the site that
+   raises it.
+4. Add or update the row in this document.
+5. Never rename or reassign an existing code. If a code is no longer
+   thrown, mark it `retired: true` and keep the entry.

package/docs/INDEX.md

@@ -0,0 +1,53 @@
+# Documentation index
+
+Read in the order that matches how deep you want to go.
+
+## Start here
+
+| Doc | For | Time |
+|---|---|---|
+| [`QUICKSTART.md`](QUICKSTART.md) | Your first Run in under 10 minutes. Zero jargon. | 5 min |
+| [`../README.md`](../README.md) | Pitch, install, useful commands. | 8 min |
+
+## Understand the method
+
+| Doc | For | Time |
+|---|---|---|
+| [`../CORE.md`](../CORE.md) | The operational guide agents follow at runtime. Portable across clients. | 15 min |
+| [`SEMANTIC-MEMORY.md`](SEMANTIC-MEMORY.md) | How facts, decisions, insights, and dossiers fit together. | 10 min |
+| [`SCHEMA.md`](SCHEMA.md) | The generated executable schema: ids, cardinalities, initial states, transitions. | 10 min |
+
+## Verify and troubleshoot
+
+| Doc | For | Time |
+|---|---|---|
+| [`TROUBLESHOOTING.md`](TROUBLESHOOTING.md) | Install, migration, and daily-use issues with fixes. | as needed |
+| [`ERROR-CODES.md`](ERROR-CODES.md) | Catalog of stable `SR-E-NNN` codes with summary + remediation for every user-facing failure. | as needed |
+| [`RELEASE-SCORECARD.md`](RELEASE-SCORECARD.md) | Evidence-backed local readiness signals per release. | 5 min |
+
+## Go deep
+
+| Doc | For | Time |
+|---|---|---|
+| [`../SPEC.md`](../SPEC.md) | The normative specification: state machines, invariants, composition, precedence, conformance. | 30 min |
+| [`../DECISIONS.md`](../DECISIONS.md) | Architecture Decision Records: why the method is the way it is. Every ADR carries context, decision, alternatives considered, consequences. | browse |
+| [`../CHANGELOG.md`](../CHANGELOG.md) | What shipped, what broke, what got safer. | as needed |
+| [`../MIGRATION-1-to-2.md`](../MIGRATION-1-to-2.md) | Upgrade, verify, rollback, and recover for existing v1 projects. | as needed |
+
+## Reading order recommendations
+
+**You just installed ScrumRun.**
+`QUICKSTART.md` → `README.md` → `CORE.md` when you want more.
+
+**You are integrating ScrumRun with a new AI client.**
+`CORE.md` → `SCHEMA.md` → `SPEC.md`.
+
+**You are upgrading from v1.**
+`../MIGRATION-1-to-2.md` → `../CHANGELOG.md` → `TROUBLESHOOTING.md`.
+
+**You want to know why a design choice exists.**
+`../DECISIONS.md`. Search for the topic; every ADR is self-contained.
+
+**Something broke.**
+`TROUBLESHOOTING.md` first. If the code shown starts with `SR-E-`, the
+message points to the exact remediation step.

package/docs/QUICKSTART.md

@@ -0,0 +1,156 @@
+# Quickstart
+
+Get from "never heard of it" to your first approved Run in under 10 minutes.
+No `SPEC.md` reading required.
+
+## The three-minute mental model
+
+ScrumRun gives an AI coding agent a small vocabulary and a project memory.
+
+- **Task** — one atomic piece of work.
+- **Sprint** — a batch of Tasks grouped by time or theme. Optional.
+- **Run** — one attempt at executing a Task. Retries create new Runs; the
+  previous one is never overwritten.
+- **Feature** — a bigger initiative that groups Tasks and its own decisions.
+- **Memory** — what the project learned: facts, decisions, insights, dossiers.
+
+Everything lives as Markdown under `.scrumrun/`. Any Markdown-capable agent
+can follow it.
+
+## Install
+
+You need Node.js 22.13 or newer.
+
+```bash
+npx scrumrun@latest install    # installs the agent integration for your client
+npx scrumrun@latest init       # creates the .scrumrun/ tree in the current repo
+```
+
+By default `.scrumrun/` is added to `.git/info/exclude` — the methodology
+stays local to your machine. Add `--shared` to `init` if your team wants
+to commit it.
+
+## Your first intake
+
+You do not have to remember any commands. Just describe the problem in
+natural language to your AI client. ScrumRun classifies it before writing
+anything.
+
+```
+Owner: The checkout charges twice when the page is refreshed.
+```
+
+The agent responds with an intake summary:
+
+```
+Classification: Task (fix)
+Risk: high — financial path
+Why: Payment behavior changed after completed work; corrective Task
+     linked to the original Run history.
+Next: /sc plan intake "double charge on refresh"
+Awaiting owner approval.
+```
+
+Nothing has been written yet. The classification, risk, and plan are
+proposals. Approving is one command:
+
+```bash
+npx scrumrun@latest sc plan intake --approve <token>
+```
+
+Only then does a Task and a Run get created.
+
+## Watching the Run
+
+The agent executes inside the approved scope. Every step lands in an
+append-only ledger under `.scrumrun/runs/RUN-NNN.md` with a stable event
+id, timestamp, actor, reason, and typed evidence.
+
+```
+RUN-001-EVT-001  planned by owner       reason: "checkout double-charge fix"
+RUN-001-EVT-002  executed               command: npm test  → 132 passed
+RUN-001-EVT-003  validated (REV-001)    guardrail checks: passed
+RUN-001-EVT-004  learned (INS-001)      "refresh triggers duplicate submit"
+RUN-001-EVT-005  completed
+```
+
+A retry does not overwrite `RUN-001`. It creates `RUN-002` beside it. The
+old attempt stays as evidence.
+
+You can render a Run's ledger as a human timeline instead of reading the
+raw JSON:
+
+```bash
+npx scrumrun@latest sc plan run --render RUN-001
+```
+
+For aggregate signal across every Run in the project — status mix, p50
+and p95 time in `VALIDATING`, retries per Task, guardrail check counts —
+use `--stats`:
+
+```bash
+npx scrumrun@latest sc plan run --stats
+npx scrumrun@latest sc plan run --stats --task TASK-001
+npx scrumrun@latest sc plan run --stats --json
+```
+
+## Reading the memory
+
+As you work, the project accumulates:
+
+- **Facts** (`K-NNN`) — reviewed truths about the code.
+- **Decisions** (`DEC-NNN`) — normative choices that constrain future work.
+- **Insights** (`INS-NNN`) — context, rationale, warnings, trade-offs.
+- **Dossiers** (`DOS-NNN`) — curated topic or module deep-dives.
+
+Nothing becomes canonical without confirmation. AI extraction creates
+candidates; you promote them with evidence.
+
+```bash
+npx scrumrun@latest sc knowledge insight --propose "..." --evidence src/foo.ts
+npx scrumrun@latest sc knowledge insight --confirm INS-001
+```
+
+Ask the agent things like *"why is calculateFinalPrice in checkout?"* or
+*"which decision constrains the pricing module?"* — it answers by reading
+the memory index, not by guessing.
+
+## What to read next
+
+- [`docs/INDEX.md`](INDEX.md) — the full documentation map.
+- [`CORE.md`](../CORE.md) — the operational guide agents follow at runtime.
+- [`docs/SEMANTIC-MEMORY.md`](SEMANTIC-MEMORY.md) — how facts, decisions,
+  insights, and dossiers fit together.
+- [`docs/TROUBLESHOOTING.md`](TROUBLESHOOTING.md) — for common install and
+  migration issues.
+- [`SPEC.md`](../SPEC.md) — the formal specification, when you want the
+  invariants and state machines.
+
+## Common questions
+
+**Do I have to type `/sc` commands?** No. Natural language is the primary
+entry point. The `/sc` grammar exists for scripting and reproducibility.
+
+**What if I already use v1?** Run `npx scrumrun@latest update` for a
+read-only migration preflight, then `update --migrate` when you are
+satisfied with the plan.
+
+**Can I hide the `.scrumrun/` tree from Git?** It is hidden by default
+(local mode). Use `--shared` if you want to commit it.
+
+**Where do secrets live?** Never in canonical artifacts. Use
+`.scrumrun/vault.local.md` for local-only plaintext that is never indexed
+and never migrated.
+
+**How do I add my own project rules?** Edit `.scrumrun/guardrails.md`.
+Each rule has `Status`, `Enforcement`, `Scope`, and `Rule` fields and gets
+a stable `GR-NNN` id.
+
+**What if something goes wrong?** Every user-facing failure carries a
+stable `SR-E-NNN` code. Grep it in [`docs/ERROR-CODES.md`](ERROR-CODES.md)
+for the exact remediation. If a canonical transaction was interrupted,
+preview the repair before running it:
+
+```bash
+npx scrumrun@latest sc config doctor --recover --dry-run
+```

package/lib/commands/manifest.js

@@ -12,6 +12,8 @@ const nouns = Object.freeze({
       run: [
         "--list",
         "--show",
+        "--render <RUN-NNN>",
+        "--stats [--task <TASK-NNN>] [--feature <FEAT-NNN>] [--sprint <SPRINT-NNN>] [--json]",
         "--authorize-mutation <RUN-NNN> --path <relative-path>",
         "--record-mutation <RUN-NNN> --permit <MUT-id> [--note] [--actor]",
         "--satisfy-guardrail <RUN-NNN> --guardrail <GR-NNN> [--note] [--evidence] [--review] [--migration] [--actor]",
@@ -62,7 +64,7 @@ const nouns = Object.freeze({
       init: ["--local", "--shared", "--lean", "--no-agent-hint", "--force"],
       update: ["all [--migrate]", "codex [--migrate]", "opencode [--migrate]", "claude [--migrate]"],
       migrate: ["--to 2 --dry-run", "--to 2 --apply", "--to 2 --rollback"],
-      doctor: ["all [--strict] [--recover]", "codex [--strict] [--recover]", "opencode [--strict] [--recover]", "claude [--strict] [--recover]"],
+      doctor: ["all [--strict] [--recover] [--dry-run]", "codex [--strict] [--recover] [--dry-run]", "opencode [--strict] [--recover] [--dry-run]", "claude [--strict] [--recover] [--dry-run]"],
       uninstall: ["--force"],
       help: ["<topic>"]
     }

package/lib/commands/run-render.js

@@ -0,0 +1,161 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const { parseRunLedger } = require("../runtime/run-ledger");
+
+const RULE = "─".repeat(72);
+
+function formatInstant(iso) {
+  if (!iso) return "                     ";
+  const date = new Date(iso);
+  if (Number.isNaN(date.valueOf())) return String(iso);
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())} ${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())} UTC`;
+}
+
+function humanDuration(startIso, endIso) {
+  if (!startIso || !endIso) return null;
+  const delta = new Date(endIso).valueOf() - new Date(startIso).valueOf();
+  if (!Number.isFinite(delta) || delta < 0) return null;
+  const seconds = Math.round(delta / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const rem = seconds % 60;
+  if (minutes < 60) return rem ? `${minutes}m ${rem}s` : `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  const mrem = minutes % 60;
+  return mrem ? `${hours}h ${mrem}m` : `${hours}h`;
+}
+
+function readFrontmatter(body) {
+  const match = String(body || "").match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  const result = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const kv = line.match(/^([a-z_][a-z0-9_]*):\s*(.*)$/i);
+    if (!kv) continue;
+    let value = kv[2].trim();
+    if (value === "null") value = null;
+    else if (/^-?\d+$/.test(value)) value = Number(value);
+    result[kv[1]] = value;
+  }
+  return result;
+}
+
+function readTitle(body) {
+  const match = String(body || "").match(/^#\s+([^\r\n]+)/m);
+  return match ? match[1].trim() : null;
+}
+
+function summarizeEvidence(evidence) {
+  if (!Array.isArray(evidence) || !evidence.length) return [];
+  return evidence.map((item) => {
+    if (!item || typeof item !== "object") return String(item);
+    const kind = item.kind || "evidence";
+    if (item.ref && item.summary) return `${kind}: ${item.ref} — ${item.summary}`;
+    if (item.ref) return `${kind}: ${item.ref}`;
+    if (item.command) return `${kind}: ${item.command}${item.result ? ` → ${item.result}` : ""}`;
+    if (item.test) return `${kind}: ${item.test}${item.result ? ` → ${item.result}` : ""}`;
+    if (item.summary) return `${kind}: ${item.summary}`;
+    return kind;
+  });
+}
+
+function headline(event) {
+  const type = event.type || "event";
+  if (type === "transition") {
+    const from = event.from || "?";
+    const to = event.to || "?";
+    return `${from} → ${to}`;
+  }
+  if (type === "snapshot") return "snapshot (baseline)";
+  if (type === "guardrail") {
+    const status = event.status || event.result || "recorded";
+    return `guardrail ${event.guardrail || event.code || ""} ${status}`.trim();
+  }
+  if (type === "mutation") {
+    const permit = event.mutation || event.permit || "";
+    return `mutation ${permit}`.trim();
+  }
+  return type;
+}
+
+function renderEvent(event, indent = "  ") {
+  const lines = [];
+  const time = formatInstant(event.occurred_at);
+  const actor = String(event.actor || "?").padEnd(8, " ");
+  lines.push(`${time}  ${actor}${event.id || ""}  ${headline(event)}`);
+  if (event.reason) {
+    lines.push(`${indent}reason    ${event.reason}`);
+  }
+  const evidence = summarizeEvidence(event.evidence);
+  if (evidence.length) {
+    lines.push(`${indent}evidence  ${evidence[0]}`);
+    for (let i = 1; i < evidence.length; i++) {
+      lines.push(`${indent}          ${evidence[i]}`);
+    }
+  }
+  if (event.type === "mutation" && Array.isArray(event.paths) && event.paths.length) {
+    lines.push(`${indent}paths     ${event.paths.join(", ")}`);
+  }
+  if (event.type === "guardrail" && event.gate) {
+    lines.push(`${indent}gate      ${event.gate}`);
+  }
+  return lines.join("\n");
+}
+
+function renderRun({ id, file, body }) {
+  const frontmatter = readFrontmatter(body);
+  const title = readTitle(body) || id;
+  const { events, errors } = parseRunLedger(body);
+
+  const header = [
+    `${id}  ${title}`,
+    `status ${frontmatter.status || "unknown"}   task ${frontmatter.task || "-"}   attempt ${frontmatter.attempt ?? "-"}   sprint ${frontmatter.sprint || "-"}`,
+    file ? `file   ${path.relative(process.cwd(), file)}` : null,
+    RULE
+  ].filter(Boolean);
+
+  const body_lines = [];
+  if (!events.length) {
+    body_lines.push("(no ledger events found)");
+  } else {
+    for (let i = 0; i < events.length; i++) {
+      body_lines.push(renderEvent(events[i]));
+      if (i < events.length - 1) body_lines.push("");
+    }
+  }
+
+  const first = events[0]?.occurred_at;
+  const last = events[events.length - 1]?.occurred_at;
+  const duration = humanDuration(first, last);
+
+  const footer = [
+    RULE,
+    `${events.length} event${events.length === 1 ? "" : "s"}${duration ? `   span ${duration}` : ""}`
+  ];
+
+  if (errors.length) {
+    footer.push("");
+    footer.push("Ledger validation warnings:");
+    for (const err of errors) footer.push(`  - ${err}`);
+  }
+
+  return [...header, ...body_lines, ...footer].join("\n");
+}
+
+function locateRun(cwd, runId) {
+  const file = path.join(cwd, ".scrumrun", "runs", `${runId}.md`);
+  if (!fs.existsSync(file)) return null;
+  return { id: runId, file, body: fs.readFileSync(file, "utf8") };
+}
+
+function renderRunFromDisk(cwd, runId) {
+  const run = locateRun(cwd, runId);
+  if (!run) throw new Error(`Run not found: ${runId}`);
+  return renderRun(run);
+}
+
+module.exports = { renderRun, renderRunFromDisk, formatInstant, humanDuration, summarizeEvidence };

package/lib/commands/run-stats.js

@@ -0,0 +1,206 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const { parseRunLedger } = require("../runtime/run-ledger");
+
+function readFrontmatter(body) {
+  const match = String(body || "").match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  const result = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const kv = line.match(/^([a-z_][a-z0-9_]*):\s*(.*)$/i);
+    if (!kv) continue;
+    let value = kv[2].trim();
+    if (value === "null" || value === "") value = null;
+    else if (/^-?\d+$/.test(value)) value = Number(value);
+    result[kv[1]] = value;
+  }
+  return result;
+}
+
+function loadRuns(cwd) {
+  const dir = path.join(cwd, ".scrumrun", "runs");
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((name) => /^RUN-\d{3,}\.md$/.test(name))
+    .sort()
+    .map((name) => {
+      const file = path.join(dir, name);
+      const body = fs.readFileSync(file, "utf8");
+      return { id: name.replace(/\.md$/, ""), file, body, frontmatter: readFrontmatter(body) };
+    });
+}
+
+function transitions(events) {
+  return events.filter((event) => event && event.type === "transition");
+}
+
+function firstEntryInto(events, status) {
+  for (const event of transitions(events)) {
+    if (event.to === status) return event.occurred_at;
+  }
+  return null;
+}
+
+function lastExitFrom(events, status) {
+  let last = null;
+  for (const event of transitions(events)) {
+    if (event.from === status) last = event.occurred_at;
+  }
+  return last;
+}
+
+function durationMs(startIso, endIso) {
+  if (!startIso || !endIso) return null;
+  const delta = new Date(endIso).valueOf() - new Date(startIso).valueOf();
+  return Number.isFinite(delta) && delta >= 0 ? delta : null;
+}
+
+function percentile(sortedMs, p) {
+  if (!sortedMs.length) return null;
+  const rank = Math.min(sortedMs.length - 1, Math.max(0, Math.floor((p / 100) * sortedMs.length)));
+  return sortedMs[rank];
+}
+
+function humanMs(ms) {
+  if (ms === null || ms === undefined || !Number.isFinite(ms)) return "-";
+  const seconds = Math.round(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const rem = seconds % 60;
+  if (minutes < 60) return rem ? `${minutes}m ${rem}s` : `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  const mrem = minutes % 60;
+  return mrem ? `${hours}h ${mrem}m` : `${hours}h`;
+}
+
+function computeStats(cwd, filters = {}) {
+  const runs = loadRuns(cwd).filter((run) => {
+    if (filters.task && run.frontmatter.task !== filters.task) return false;
+    if (filters.feature && run.frontmatter.feature !== filters.feature) return false;
+    if (filters.sprint && run.frontmatter.sprint !== filters.sprint) return false;
+    return true;
+  });
+
+  const summary = {
+    total: runs.length,
+    byStatus: {},
+    validating: { count: 0, samples: [], p50: null, p95: null, max: null },
+    executing: { count: 0, samples: [], p50: null, p95: null, max: null },
+    attempts: { max: 0, byTask: {} },
+    guardrails: { passed: 0, deferred: 0, blocked: 0 },
+    mutations: 0,
+    completionsWithFailurePredecessor: 0
+  };
+
+  const failedTaskIds = new Set();
+
+  for (const run of runs) {
+    const status = run.frontmatter.status || "unknown";
+    summary.byStatus[status] = (summary.byStatus[status] || 0) + 1;
+
+    const attempt = Number(run.frontmatter.attempt) || 1;
+    if (attempt > summary.attempts.max) summary.attempts.max = attempt;
+    if (run.frontmatter.task) {
+      summary.attempts.byTask[run.frontmatter.task] = Math.max(summary.attempts.byTask[run.frontmatter.task] || 0, attempt);
+    }
+
+    if (status === "failed" && run.frontmatter.task) failedTaskIds.add(run.frontmatter.task);
+    if (status === "completed" && run.frontmatter.task && failedTaskIds.has(run.frontmatter.task)) {
+      summary.completionsWithFailurePredecessor += 1;
+    }
+
+    const { events } = parseRunLedger(run.body);
+    const enterValidating = firstEntryInto(events, "validating");
+    const exitValidating = lastExitFrom(events, "validating");
+    const validatingMs = durationMs(enterValidating, exitValidating);
+    if (validatingMs !== null) {
+      summary.validating.count += 1;
+      summary.validating.samples.push(validatingMs);
+    }
+
+    const enterExecuting = firstEntryInto(events, "executing");
+    const exitExecuting = lastExitFrom(events, "executing");
+    const executingMs = durationMs(enterExecuting, exitExecuting);
+    if (executingMs !== null) {
+      summary.executing.count += 1;
+      summary.executing.samples.push(executingMs);
+    }
+
+    for (const event of events) {
+      if (event.type === "guardrail") {
+        const state = String(event.status || event.result || "").toLowerCase();
+        if (state === "passed") summary.guardrails.passed += 1;
+        else if (state === "deferred") summary.guardrails.deferred += 1;
+        else if (state === "blocked") summary.guardrails.blocked += 1;
+      } else if (event.type === "mutation") {
+        summary.mutations += 1;
+      }
+    }
+  }
+
+  for (const key of ["validating", "executing"]) {
+    const samples = summary[key].samples.slice().sort((a, b) => a - b);
+    summary[key].p50 = percentile(samples, 50);
+    summary[key].p95 = percentile(samples, 95);
+    summary[key].max = samples[samples.length - 1] ?? null;
+    delete summary[key].samples;
+  }
+
+  return summary;
+}
+
+function renderStats(summary, filters = {}) {
+  const lines = [];
+  const scope = [];
+  if (filters.task) scope.push(`task=${filters.task}`);
+  if (filters.feature) scope.push(`feature=${filters.feature}`);
+  if (filters.sprint) scope.push(`sprint=${filters.sprint}`);
+  lines.push(`Run statistics${scope.length ? ` (${scope.join(", ")})` : ""}`);
+  lines.push("─".repeat(72));
+  lines.push(`total runs                       ${summary.total}`);
+
+  const statusEntries = Object.entries(summary.byStatus).sort((a, b) => b[1] - a[1]);
+  if (statusEntries.length) {
+    lines.push("");
+    lines.push("by status");
+    for (const [status, count] of statusEntries) {
+      lines.push(`  ${status.padEnd(30, " ")} ${count}`);
+    }
+  }
+
+  lines.push("");
+  lines.push("time in VALIDATING");
+  lines.push(`  runs sampled                   ${summary.validating.count}`);
+  lines.push(`  p50                            ${humanMs(summary.validating.p50)}`);
+  lines.push(`  p95                            ${humanMs(summary.validating.p95)}`);
+  lines.push(`  max                            ${humanMs(summary.validating.max)}`);
+
+  lines.push("");
+  lines.push("time in EXECUTING");
+  lines.push(`  runs sampled                   ${summary.executing.count}`);
+  lines.push(`  p50                            ${humanMs(summary.executing.p50)}`);
+  lines.push(`  p95                            ${humanMs(summary.executing.p95)}`);
+  lines.push(`  max                            ${humanMs(summary.executing.max)}`);
+
+  lines.push("");
+  lines.push("retries and recovery");
+  lines.push(`  highest attempt observed       ${summary.attempts.max}`);
+  const retriedTasks = Object.entries(summary.attempts.byTask).filter(([, n]) => n > 1);
+  lines.push(`  tasks that retried             ${retriedTasks.length}`);
+  lines.push(`  completions after prior fail   ${summary.completionsWithFailurePredecessor}`);
+
+  lines.push("");
+  lines.push("guardrails and edit permits");
+  lines.push(`  guardrail events passed        ${summary.guardrails.passed}`);
+  lines.push(`  guardrail events deferred      ${summary.guardrails.deferred}`);
+  lines.push(`  guardrail events blocked       ${summary.guardrails.blocked}`);
+  lines.push(`  recorded mutation events       ${summary.mutations}`);
+
+  return lines.join("\n");
+}
+
+module.exports = { computeStats, renderStats, loadRuns };

package/lib/errors.js

@@ -0,0 +1,98 @@
+"use strict";
+
+// Stable ScrumRun error catalog.
+//
+// Codes are permanent once assigned. Never reuse a retired code. When
+// removing an error site, keep its entry with { retired: true } instead
+// of deleting it so external logs stay resolvable.
+//
+// Ranges (soft, for readability):
+//   SR-E-001..049  request/intake and approval
+//   SR-E-050..099  approvals, tokens, and secrets
+//   SR-E-100..149  runs, task/run transitions, ledger
+//   SR-E-150..199  guardrails, policy, obligations
+//   SR-E-200..249  edit permits (Mutation Gateway)
+//   SR-E-250..299  transactions and recovery
+//   SR-E-300..349  memory (facts, decisions, insights, dossiers, vault)
+//   SR-E-350..399  semantic index, code intelligence
+//   SR-E-400..449  migration and update
+//   SR-E-450..499  conformance and doctor
+//   SR-E-500..549  configuration and installation
+
+const CATALOG = Object.freeze({
+  // Request / intake
+  "SR-E-001": { summary: "Intake request is missing.", remediation: "Provide a natural-language request or use --request \"...\"." },
+  "SR-E-002": { summary: "Intake payload contains secret-like content.", remediation: "Remove the secret from the request or reference a vault entry by path." },
+  "SR-E-003": { summary: "Intake classification could not be produced.", remediation: "Rephrase the request in one sentence describing the observable problem." },
+
+  // Approvals
+  "SR-E-050": { summary: "Approval token is malformed.", remediation: "Re-run the intake and copy the token exactly as printed after 'Approval:'." },
+  "SR-E-051": { summary: "Approval token signature does not match this repository.", remediation: "Tokens are bound to the project fingerprint. Re-run intake from the repo the change targets." },
+  "SR-E-052": { summary: "Approval token expired.", remediation: "Re-run intake to obtain a fresh token before approving." },
+
+  // Runs and ledger
+  "SR-E-100": { summary: "Run not found.", remediation: "Check the RUN-NNN id with `sc plan run --list`." },
+  "SR-E-101": { summary: "Run ledger contains an invalid event.", remediation: "Inspect the reported event id; use `sc plan run --render` for a human view or restore from git history." },
+  "SR-E-102": { summary: "Run transition rejected: missing validation or learning evidence.", remediation: "Complete `--validate` and `--learn` with typed evidence before `--complete`." },
+  "SR-E-103": { summary: "Retry rejected because the previous Run is still active.", remediation: "Complete, fail, or block the current Run before creating a retry." },
+
+  // Guardrails
+  "SR-E-150": { summary: "Guardrail check blocked the operation.", remediation: "Read the reported GR-NNN, satisfy or retire it explicitly; guardrails never bypass silently." },
+  "SR-E-151": { summary: "Guardrail obligation is still pending.", remediation: "Resolve each `pending guardrail` via `sc plan run --satisfy-guardrail` before completing the Run." },
+  "SR-E-152": { summary: "Guardrail declaration is malformed.", remediation: "Every active guardrail requires Status, Enforcement, Scope, and Rule fields; check .scrumrun/guardrails.md." },
+
+  // Edit permits (Mutation Gateway)
+  "SR-E-200": { summary: "No edit permit for this path.", remediation: "Request one with `sc plan run --authorize-mutation RUN-NNN --path <path>` before editing canonical or source files." },
+  "SR-E-201": { summary: "Edit permit expired.", remediation: "Permits last 15 minutes. Authorize a new one and record the change immediately." },
+  "SR-E-202": { summary: "Edit permit path scope mismatch.", remediation: "The permit does not cover the modified path. Request a new permit that lists it." },
+  "SR-E-203": { summary: "File hash changed unexpectedly since the permit was issued.", remediation: "Someone else modified the file. Re-plan the change and request a fresh permit." },
+
+  // Transactions and recovery
+  "SR-E-250": { summary: "Pending kernel transaction cannot be recovered automatically.", remediation: "Run `sc config doctor --recover --dry-run` to preview; if it shows 'would overwrite owner changes', reconcile the file manually before applying." },
+  "SR-E-251": { summary: "Journal fails integrity check.", remediation: "Inspect .scrumrun/.transactions/pending. Do not delete; contact support or restore from backup." },
+
+  // Memory
+  "SR-E-300": { summary: "Memory candidate rejected: missing resolvable evidence.", remediation: "Attach at least one --evidence path or `sc knowledge <subject> --propose` before `--confirm`." },
+  "SR-E-301": { summary: "Attempt to write into vault via canonical channel.", remediation: "vault.local.md is local-only and never indexed. Edit the file directly." },
+
+  // Semantic index / code intel
+  "SR-E-350": { summary: "Semantic index is stale.", remediation: "Rebuild with `sc knowledge map --build`. Cache is disposable; canonical memory is unaffected." },
+  "SR-E-351": { summary: "Search backend advertised in the cache does not match this runtime.", remediation: "Delete .scrumrun/.cache/semantic-index.sqlite and re-run any `sc knowledge` query to rebuild against the current runtime." },
+
+  // Migration
+  "SR-E-400": { summary: "Migration preflight failed.", remediation: "Run `npx scrumrun@latest update` (dry) to see blockers, resolve them, then apply with `--migrate`." },
+  "SR-E-401": { summary: "Migration rollback requested but no backup was found.", remediation: "Rollback needs the ignored byte-exact backup created during --migrate. Restore from version control if the backup is gone." },
+
+  // Conformance / doctor
+  "SR-E-450": { summary: "Conformance check failed.", remediation: "The reported invariant identifies the exact violation; the message includes the file and expected shape." },
+  "SR-E-451": { summary: "Installed client asset is stale.", remediation: "Re-run `npx scrumrun@latest update` for the specific client. `doctor --strict` shows which files diverge." },
+
+  // Configuration / install
+  "SR-E-500": { summary: "ScrumRun project not initialized.", remediation: "Run `npx scrumrun@latest init` in the repository root." },
+  "SR-E-501": { summary: "Unsupported Node.js runtime.", remediation: "ScrumRun requires Node.js >=22.13.0 for native SQLite. Upgrade Node and retry." }
+});
+
+class ScrumRunError extends Error {
+  constructor(code, message, options = {}) {
+    const entry = CATALOG[code];
+    if (!entry) throw new Error(`Unknown ScrumRun error code: ${code}`);
+    const composed = message || entry.summary;
+    super(`${code} ${composed}`);
+    this.name = "ScrumRunError";
+    this.code = code;
+    this.summary = entry.summary;
+    this.remediation = entry.remediation;
+    if (options.cause) this.cause = options.cause;
+    if (options.details) this.details = options.details;
+  }
+}
+
+function describe(code) {
+  return CATALOG[code] || null;
+}
+
+function codes() {
+  return Object.keys(CATALOG).sort();
+}
+
+module.exports = { ScrumRunError, describe, codes, CATALOG };

package/lib/memory/index.js

@@ -499,7 +499,7 @@ function indexStatus(projectRoot) {
       return { exists: true, stale: true, file, stored, check: "schema", reason: `semantic index schema ${INDEX_SCHEMA_VERSION} rebuild required` };
     }
     if (searchBackend === "fts5" && !runtimeSupportsFts5(database)) {
-      return { exists: true, stale: true, file, stored, searchBackend, check: "schema", reason: "semantic index requires unavailable FTS5; fallback rebuild required" };
+      return { exists: true, stale: true, file, stored, searchBackend, check: "backend", backendMismatch: true, reason: "declared search backend fts5 is not available in this Node.js runtime; disposable rebuild required" };
     }
     const watch = sourceWatchSnapshot(projectRoot);
     if (metadata.get("source_watch_fingerprint") === watch.fingerprint) {

package/lib/v2/conformance.js

@@ -35,7 +35,8 @@ const INVARIANTS = Object.freeze([
   { id: "I-18", summary: "unsafe and partial writes fail safely", tests: ["canonical writes reject traversal and symlink paths", "repository refuses conflicting overwrite", "interrupted kernel transaction is recovered"] },
   { id: "I-19", summary: "code intelligence is derived and fingerprinted", tests: ["language adapters are replaceable", "moves remap by fingerprint"] },
   { id: "I-20", summary: "learning candidates never block execution", tests: ["post-validation extraction creates candidate insights"] },
-  { id: "I-21", summary: "material mutations are scoped, policy-bound, and fail closed", tests: ["Mutation Gateway rejects bypass and out-of-scope writes", "Run completion rejects unresolved Guardrail obligations"] }
+  { id: "I-21", summary: "material mutations are scoped, policy-bound, and fail closed", tests: ["Mutation Gateway rejects bypass and out-of-scope writes", "Run completion rejects unresolved Guardrail obligations"] },
+  { id: "I-22", summary: "declared search backend matches observed runtime capabilities", tests: ["conformance detects a semantic index that declares fts5 when the runtime does not provide it"] }
 ]);
 
 function finding(severity, code, message, file = null) {
@@ -213,7 +214,11 @@ function auditProject(projectRoot) {
   }
   try {
     const semantic = indexStatus(projectRoot);
-    if (semantic.exists && semantic.stale) findings.push(finding("warning", "INDEX_STALE", "semantic-index.sqlite is stale and will be rebuilt on query."));
+    if (semantic.exists && semantic.backendMismatch) {
+      findings.push(finding("high", "SEARCH_BACKEND_MISMATCH", `semantic index declares search_backend=${semantic.searchBackend} but the current Node.js runtime does not provide it; delete .scrumrun/.cache/semantic-index.sqlite to rebuild against the observed capabilities.`));
+    } else if (semantic.exists && semantic.stale) {
+      findings.push(finding("warning", "INDEX_STALE", "semantic-index.sqlite is stale and will be rebuilt on query."));
+    }
     const map = mapStatus(projectRoot, { semanticStatus: semantic });
     if (semantic.exists && map.stale) findings.push(finding("warning", "MAP_STALE", `map.md is stale: ${map.reason || map.error || "unknown reason"}.`));
   } catch (error) {

package/lib/v2/transaction.js

@@ -236,6 +236,64 @@ function runKernelTransaction(scrumDir, name, changes, options = {}) {
   });
 }
 
+function previewPendingRecovery(scrumDir) {
+  const preview = { plans: [], errors: [] };
+  let entries;
+  try {
+    entries = pendingTransactions(scrumDir);
+  } catch (error) {
+    preview.errors.push(error.message);
+    return preview;
+  }
+  for (const { file, transaction } of entries) {
+    const plan = { id: transaction.id, name: transaction.name || null, journal: path.basename(file), status: transaction.status, action: null, files: [], warnings: [] };
+    const journalErrors = validateJournal(transaction);
+    if (journalErrors.length) {
+      plan.action = "blocked";
+      plan.warnings.push(`journal validation failed: ${journalErrors.join("; ")}`);
+      preview.plans.push(plan);
+      continue;
+    }
+    let unsafePath = null;
+    for (const change of transaction.changes) {
+      const target = relativeTarget(scrumDir, path.join(scrumDir, change.relative));
+      if (target.relative !== change.relative) {
+        unsafePath = change.relative;
+        break;
+      }
+    }
+    if (unsafePath) {
+      plan.action = "blocked";
+      plan.warnings.push(`unsafe transaction target: ${unsafePath}`);
+      preview.plans.push(plan);
+      continue;
+    }
+    const current = transaction.changes.map((change) => ({ change, value: fileSnapshot(scrumDir, change.relative) }));
+    const unexpected = current.filter(({ change, value }) => !sameSnapshot(value, change.before) && !sameSnapshot(value, change.after));
+    if (unexpected.length) {
+      plan.action = "blocked";
+      plan.warnings.push(`would overwrite owner changes at: ${unexpected.map(({ change }) => change.relative).join(", ")}`);
+      preview.plans.push(plan);
+      continue;
+    }
+    if (transaction.status === "prepared") {
+      plan.action = "rollback";
+      plan.files = transaction.changes.map((change) => ({ relative: change.relative, from: "current", to: "pre-transaction" }));
+    } else {
+      const incomplete = current.filter(({ change, value }) => !sameSnapshot(value, change.after));
+      if (incomplete.length) {
+        plan.action = "blocked";
+        plan.warnings.push(`committed transaction is incomplete: ${incomplete.map(({ change }) => change.relative).join(", ")}`);
+      } else {
+        plan.action = "verify-commit";
+        plan.files = transaction.changes.map((change) => ({ relative: change.relative, from: "current", to: "verified-commit" }));
+      }
+    }
+    preview.plans.push(plan);
+  }
+  return preview;
+}
+
 function pendingTransactionStatus(scrumDir) {
   try {
     return { pending: pendingTransactions(scrumDir).map(({ transaction }) => ({ id: transaction.id, name: transaction.name, status: transaction.status })) };
@@ -247,6 +305,7 @@ function pendingTransactionStatus(scrumDir) {
 module.exports = {
   TRANSACTION_SCHEMA,
   pendingTransactionStatus,
+  previewPendingRecovery,
   recoverPendingTransactions,
   recoverPendingTransactionsUnlocked,
   runKernelTransaction,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scrumrun",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Evidence-driven Agile runtime and semantic project memory for AI coding agents.",
   "bin": {
     "scrumrun": "bin/scrumrun.js",