scrumrun 2.1.1 → 2.3.0

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) {