scrumrun 2.2.0 → 2.4.0

package/CHANGELOG.md

@@ -4,6 +4,45 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+## 2.4.0 - 2026-07-23
+
+### Added
+
+- `method.json` now carries a canonical `paths` block plus `paths_schema: 1`. The block declares the exact relative location of every artifact family (`guardrails`, `config`, `project`, `core`, `state_view`, `map_view`, `tasks`, `sprints`, `features`, `runs`, `reviews`, `memory.{knowledge,decisions,insights,dossiers}`, `vault_local`, `cache`) so ScrumRun-aware agents navigate by index instead of grep. Powered by a new `lib/v2/paths` module used by init, migration, and conformance so drift is impossible.
+- Invariant **I-23** — *method.json declares canonical paths so agents navigate by index, not by search*. `doctor --strict` flags `METHOD_PATHS_MISSING`, `METHOD_PATHS_DRIFT`, and `METHOD_PATHS_SCHEMA` findings; a `high` severity blocks conformance until `update --migrate` regenerates the block.
+- CORE and the shared SKILL now open with a hard instruction: read `.scrumrun/method.json` **before** any grep, and never search for legacy paths (`goals/`, `backlog.md`, `sprint.md`, `history.md`). Directory listing is a fallback, never a first step.
+
+### Changed
+
+- Migration output writes `method.json` through the shared `renderMethodJson` helper, so v1→v2 migrations backfill the `paths` block automatically.
+- SPEC.md conformance range extended to `I-01 through I-23`.
+- Test suite grew from 170 to 177 passing.
+
+## 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/CORE.md

@@ -82,6 +82,8 @@ AGENTS.md
     contexts/
 ```
 
+**Before querying project state, read `.scrumrun/method.json`.** Its `paths` block is the authoritative index of every canonical location in this project. Navigate by that index; if a path is not declared there, it is not canonical truth. Directory listing and grep are fallbacks — never the first step. A ScrumRun-aware agent must never search for `goals/`, `backlog.md`, `sprint.md`, or any legacy layout: those are absent by design once migration completes and are surfaced only through `.scrumrun/.migration-backup/`.
+
 Canonical truth is Markdown. SQLite/cache data stores only rebuildable indexes, symbol projections, relations, and bounded context packages. Deleting `.cache/` must never delete authored truth.
 
 `state.md` and the semantic index use two-tier freshness checks. Matching path/stat watch fingerprints avoid rereading unchanged sources; any metadata drift falls back to complete content hashing. A cache schema mismatch rebuilds the disposable index once. Watch metadata is only an optimization and never authority.

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.4.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,8 @@ 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.
+- **I-23** `method.json` declares the canonical path index for every artifact family so agents navigate by declaration, not by search. Missing or drifted paths fail conformance; grep and directory scans are fallbacks, never the first step.
 
 ## 11. Command grammar
 
@@ -325,7 +327,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-23;
 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.