scrumrun 2.0.0 → 2.1.1

package/bin/scrumrun.js

@@ -9,14 +9,23 @@ const root = path.resolve(__dirname, "..");
 const templates = path.join(root, "templates");
 const { version } = require(path.join(root, "package.json"));
 const { applyMigration, dryRunMigration, rollbackMigration } = require(path.join(root, "lib", "v2", "migration"));
+const {
+  applyRunLedgerMigration,
+  planRunLedgerMigration,
+  reportRunLedgerMigration,
+  rollbackRunLedgerMigration
+} = require(path.join(root, "lib", "v2", "run-ledger-migration"));
 const { ARTIFACT_TYPES, ArtifactRepository } = require(path.join(root, "lib", "v2", "artifacts"));
 const { aliases: COMMAND_ALIASES, resolveAlias, resolveRoute } = require(path.join(root, "lib", "commands", "manifest"));
 const { renderCommandHelp, renderCompatibilityPrompt, renderRootPrompt } = require(path.join(root, "lib", "commands", "render"));
 const { planRequest } = require(path.join(root, "lib", "runtime", "request-engine"));
 const { approveRequest, refreshState, retryTask, transitionRun } = require(path.join(root, "lib", "runtime", "orchestrator"));
+const { authorizeMutation, recordMutation, satisfyGuardrail } = require(path.join(root, "lib", "runtime", "mutation-gateway"));
+const { recordArtifactReview } = require(path.join(root, "lib", "runtime", "review-service"));
 const { createMemory, listMemory, showMemory, transitionMemory } = require(path.join(root, "lib", "memory", "service"));
-const { indexPath, indexStatus, queryIndex, rebuildIndex, writeMap } = require(path.join(root, "lib", "memory", "index"));
+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 { containsSecret } = require(path.join(root, "lib", "security", "secrets"));
 
 const COMMANDS = ["sc"];
@@ -39,7 +48,7 @@ Usage:
   scrumrun migrate --to 2 --dry-run
   scrumrun migrate --to 2 --apply
   scrumrun migrate --to 2 --rollback
-  scrumrun doctor [all|codex|opencode|claude] [--strict]
+  scrumrun doctor [all|codex|opencode|claude] [--strict] [--recover]
   scrumrun uninstall [--force]
 
 Examples:
@@ -267,7 +276,27 @@ function migrationPreflightOnUpdate({ apply = false } = {}) {
   const marker = path.join(scrumDir, "method.json");
   if (fs.existsSync(marker)) {
     try {
-      if (JSON.parse(fs.readFileSync(marker, "utf8")).method === "2.0.0") return { status: "already-v2" };
+      if (JSON.parse(fs.readFileSync(marker, "utf8")).method === "2.0.0") {
+        const preview = planRunLedgerMigration(process.cwd());
+        if (preview.status === "current") return { status: "already-v2" };
+        console.log("\n## Project schema migration preflight\n");
+        console.log(reportRunLedgerMigration(preview).trimEnd());
+        if (preview.status === "blocked") {
+          for (const error of preview.errors) console.error(`BLOCKED: ${error}`);
+          process.exitCode = 1;
+          return { status: "blocked" };
+        }
+        if (!apply) {
+          console.log("\nThe project remains unchanged. Apply the verified plan with: npx scrumrun@latest update --migrate");
+          return { status: "ready" };
+        }
+        const result = applyRunLedgerMigration(process.cwd());
+        refreshState(path.join(process.cwd(), ".scrumrun"));
+        console.log("\nApplied the verified ScrumRun Run ledger schema migration.");
+        console.log(`Source fingerprint: ${result.plan.fingerprint}`);
+        console.log("Rollback remains available with: npx scrumrun@latest migrate --to 2 --rollback");
+        return { status: result.status, result };
+      }
     } catch {
       console.error("Project migration preflight failed: .scrumrun/method.json is malformed.");
       process.exitCode = 1;
@@ -1167,6 +1196,61 @@ function memoryOptions(args) {
   };
 }
 
+function runTransitionOptions(args) {
+  const evidenceFlags = new Map([
+    ["--command", "command"],
+    ["--test", "test"],
+    ["--file", "file"],
+    ["--review", "review"],
+    ["--decision", "decision"],
+    ["--insight", "insight"],
+    ["--risk", "risk"]
+  ]);
+  const referenceKinds = new Set(["file", "review", "decision", "insight"]);
+  const evidence = [];
+  const noteParts = [];
+  let note = null;
+  let actor = "agent";
+  let occurredAt = null;
+  for (let index = 2; index < args.length; index++) {
+    const token = args[index];
+    const value = args[index + 1] && !args[index + 1].startsWith("--") ? args[index + 1] : null;
+    if (token === "--note" || token === "--actor" || token === "--at" || token === "--evidence" || evidenceFlags.has(token)) {
+      if (!value) throw new Error(`${token} requires a value.`);
+      index++;
+      if (token === "--note") note = value;
+      else if (token === "--actor") actor = value;
+      else if (token === "--at") occurredAt = value;
+      else if (token === "--evidence") {
+        const separator = value.indexOf(":");
+        const kind = separator > 0 ? value.slice(0, separator) : "note";
+        const content = separator > 0 ? value.slice(separator + 1) : value;
+        evidence.push(referenceKinds.has(kind) ? { kind, ref: content } : { kind, summary: content });
+      } else {
+        const kind = evidenceFlags.get(token);
+        evidence.push(referenceKinds.has(kind) ? { kind, ref: value } : { kind, summary: value });
+      }
+      continue;
+    }
+    if (token.startsWith("--")) throw new Error(`Unknown Run evidence option: ${token}`);
+    noteParts.push(token);
+  }
+  return { note: note || noteParts.join(" ").trim() || null, evidence, actor, occurredAt };
+}
+
+function removeOptionPairs(args, names) {
+  const hidden = new Set(names);
+  const next = [];
+  for (let index = 0; index < args.length; index++) {
+    if (hidden.has(args[index])) {
+      index++;
+      continue;
+    }
+    next.push(args[index]);
+  }
+  return next;
+}
+
 function printMemoryArtifact(artifact) {
   if (!artifact) return false;
   console.log(readIfExists(artifact.file));
@@ -1233,9 +1317,8 @@ function runSemanticContext(subject, args) {
       return;
     }
     const mapFile = path.join(process.cwd(), ".scrumrun", "map.md");
-    if (!fs.existsSync(mapFile)) throw new Error("Generated map.md is missing; run /sc knowledge map --build.");
-    const status = indexStatus(process.cwd());
-    if (status.stale) console.warn("WARNING: map.md is stale; rebuild it before relying on the view.");
+    const status = mapStatus(process.cwd());
+    if (status.stale) throw new Error(`Generated map.md is stale (${status.reason || status.error || "unknown reason"}); run /sc knowledge map --build.`);
     console.log(fs.readFileSync(mapFile, "utf8"));
     return;
   }
@@ -1272,8 +1355,11 @@ function executeRootRoute(route) {
     console.log(`State: ${plan.state}`);
     console.log(`Classification: ${plan.classification.type} (${plan.classification.reason})`);
     console.log(`Risk: ${plan.risk.level} — ${plan.risk.reasons.join("; ")}`);
-    console.log(`Policy: ${plan.policy.status}`);
+    console.log(`Policy: ${plan.policy.status} (${plan.policy.checked.length} checked; ${plan.policy.deferred.length} deferred)`);
     for (const violation of plan.policy.violations) console.log(`BLOCKED: ${violation}`);
+    for (const result of plan.policy.evaluations.filter((item) => item.status === "deferred")) {
+      console.log(`DEFERRED: ${result.guardrail} ${result.code}: ${result.message}`);
+    }
     for (const warning of plan.context.warnings) console.log(`WARNING: ${warning}`);
     if (plan.approvalToken) {
       console.log(`Approval: scrumrun sc plan intake --approve ${plan.approvalToken}`);
@@ -1302,6 +1388,33 @@ function executeRootRoute(route) {
     return;
   }
   if (noun === "plan" && subject === "run") {
+    if (routeArgs[0] === "--authorize-mutation") {
+      const paths = optionValues(routeArgs.slice(2), "--path");
+      const result = authorizeMutation(process.cwd(), routeArgs[1], paths);
+      console.log(`Authorized ${result.permit} for ${result.run} until ${result.expiresAt}.`);
+      console.log(`Paths: ${result.paths.join(", ")}`);
+      return;
+    }
+    if (routeArgs[0] === "--record-mutation") {
+      const permit = optionValue(routeArgs.slice(2), "--permit");
+      if (!permit) throw new Error("--record-mutation requires --permit MUT-id.");
+      const parsed = runTransitionOptions(removeOptionPairs(routeArgs, ["--permit"]));
+      const result = recordMutation(process.cwd(), routeArgs[1], permit, parsed);
+      refreshState(projectFile());
+      console.log(`Recorded ${result.mutation} for ${result.run.id}: ${result.changes.length} verified change(s).`);
+      return;
+    }
+    if (routeArgs[0] === "--satisfy-guardrail") {
+      const guardrail = optionValue(routeArgs.slice(2), "--guardrail");
+      if (!guardrail) throw new Error("--satisfy-guardrail requires --guardrail GR-NNN.");
+      const migration = optionValues(routeArgs.slice(2), "--migration").map((ref) => ({ kind: "migration", ref }));
+      const parsed = runTransitionOptions(removeOptionPairs(routeArgs, ["--guardrail", "--migration"]));
+      parsed.evidence.push(...migration);
+      const result = satisfyGuardrail(process.cwd(), routeArgs[1], guardrail, parsed);
+      refreshState(projectFile());
+      console.log(`${result.run.id}: ${result.guardrail} ${result.status}.`);
+      return;
+    }
     const transitions = {
       "--validate": "validating",
       "--learn": "learning",
@@ -1311,7 +1424,7 @@ function executeRootRoute(route) {
       "--block": "blocked"
     };
     if (transitions[routeArgs[0]]) {
-      const result = transitionRun(process.cwd(), routeArgs[1], transitions[routeArgs[0]], { note: routeArgs.slice(2).join(" ") || null });
+      const result = transitionRun(process.cwd(), routeArgs[1], transitions[routeArgs[0]], runTransitionOptions(routeArgs));
       console.log(`${result.run.id}: ${result.run.status}; ${result.task.id}: ${result.task.status}.`);
       if (result.learning) {
         if (result.learning.created.length) console.log(`Learning candidates: ${result.learning.created.join(", ")}.`);
@@ -1332,10 +1445,24 @@ function executeRootRoute(route) {
     if (!audit.passed) process.exitCode = 1;
     return;
   }
+  if (noun === "review" && subject === "artifact" && routeArgs[0] === "--record") {
+    const task = optionValue(routeArgs.slice(1), "--task");
+    if (!task) throw new Error("--record requires --task TASK-NNN.");
+    const result = recordArtifactReview(process.cwd(), {
+      task,
+      run: optionValue(routeArgs.slice(1), "--run"),
+      title: optionValue(routeArgs.slice(1), "--title"),
+      evidence: optionValues(routeArgs.slice(1), "--evidence")
+    });
+    refreshState(projectFile());
+    console.log(`${result.review.record.id}: ${result.review.record.status}; ${result.audit.invariants} invariants; ${result.audit.findings.length} finding(s).`);
+    if (!result.audit.passed) process.exitCode = 1;
+    return;
+  }
   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);
+    return doctor(target, { strict: routeArgs.includes("--strict"), recover: routeArgs.includes("--recover") });
   }
   if (noun === "config" && subject === "update") {
     const target = ["all", "codex", "opencode", "claude"].includes(routeArgs[0]) ? routeArgs[0] : "all";
@@ -2097,6 +2224,33 @@ function runMigration(parts) {
     return;
   }
   try {
+    const ledgerManifest = path.join(process.cwd(), ".scrumrun", ".migration", "run-ledger-v1", "manifest.json");
+    if (v2Project() && actions[0] !== "--rollback") {
+      if (actions[0] === "--dry-run") {
+        const plan = planRunLedgerMigration(process.cwd());
+        console.log(reportRunLedgerMigration(plan).trimEnd());
+        if (plan.status === "blocked") process.exitCode = 1;
+      } else {
+        const result = applyRunLedgerMigration(process.cwd());
+        if (result.status === "current") {
+          console.log("ScrumRun project is already migrated to method 2.0.0 and the current Run ledger; no files changed.");
+        } else {
+          refreshState(path.join(process.cwd(), ".scrumrun"));
+          console.log(result.output.trimEnd());
+          console.log("Rollback remains available with: scrumrun migrate --to 2 --rollback");
+        }
+      }
+      return;
+    }
+    if (actions[0] === "--rollback" && fs.existsSync(ledgerManifest)) {
+      const manifest = JSON.parse(fs.readFileSync(ledgerManifest, "utf8"));
+      if (["applied", "prepared"].includes(manifest.status)) {
+        const result = rollbackRunLedgerMigration(process.cwd());
+        refreshState(path.join(process.cwd(), ".scrumrun"));
+        console.log(`Rolled back ScrumRun Run ledger migration: ${result.status}.`);
+        return;
+      }
+    }
     if (actions[0] === "--dry-run") {
       const result = dryRunMigration(process.cwd());
       console.log(result.output.trimEnd());
@@ -2125,12 +2279,22 @@ function runMigration(parts) {
   }
 }
 
-function doctor(target = "all", { compatibility = false, strict = false } = {}) {
+function doctor(target = "all", { compatibility = false, strict = false, recover = false } = {}) {
   const home = os.homedir();
   const checks = [];
   const commands = compatibility ? [...COMMANDS, ...COMPATIBILITY_COMMANDS] : COMMANDS;
   const skillContent = fs.readFileSync(path.join(templates, "shared", "skills", "scrumrun", "SKILL.md"), "utf8");
 
+  if (recover) {
+    const scrumDir = path.join(process.cwd(), ".scrumrun");
+    if (!fs.existsSync(scrumDir)) throw new Error("Cannot recover transactions outside a ScrumRun project.");
+    const recovered = recoverPendingTransactions(scrumDir);
+    console.log(recovered.length
+      ? `recovered ${recovered.map((item) => `${item.id}:${item.action}`).join(", ")}`
+      : "recovered no pending kernel transactions");
+    refreshState(scrumDir);
+  }
+
   function commandContent(command) {
     return command === "sc" ? renderRootPrompt() : renderCompatibilityPrompt(command);
   }
@@ -2245,7 +2409,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") });
+  doctor(target, { compatibility: args.includes("--compat"), strict: args.includes("--strict"), recover: args.includes("--recover") });
 } else if (command === "claude") {
   const sub = args[1];
   if (sub === "install" || sub === "update") {

package/docs/COMMANDS.md

@@ -16,11 +16,14 @@ Use `/sc` inside a supported AI client. The equivalent CLI form is `npx scrumrun
 /sc plan task --add|--list|--show|--run|--audit|--cancel|--retry
 /sc plan sprint --add|--list|--show|--start|--complete|--block
 /sc plan feature --add|--list|--show|--activate|--complete
-/sc plan run --list|--show|--validate|--learn|--complete|--resume|--fail|--block
+/sc plan run --list|--show|--validate|--learn|--complete|--resume|--fail|--block [--note] [typed evidence flags]
+/sc plan run --authorize-mutation RUN-NNN --path <relative-path> [--path ...]
+/sc plan run --record-mutation RUN-NNN --permit MUT-id [--note] [--actor]
+/sc plan run --satisfy-guardrail RUN-NNN --guardrail GR-NNN [typed evidence flags]
 /sc plan challenge <question>
 ```
 
-CLI-native: intake/approval, Task/Run list/show, Task retry, and Run transitions. A retry requires a failed, blocked, or partial Task and creates a new Run.
+CLI-native: intake/approval, Task/Run list/show, Task retry, Mutation Gateway actions, Guardrail satisfaction, and Run transitions. A retry requires a failed, blocked, or partial Task and creates a new Run. Mutation permits expire after 15 minutes, authorize explicit relative paths only, and must be recorded immediately after the edit.
 
 ## Knowledge
 
@@ -46,11 +49,12 @@ Creation options include `--title`, `--content`, repeated `--evidence`, repeated
 /sc rules reviewer --add|--list|--show|--run
 /sc review code --run
 /sc review artifact --run
+/sc review artifact --record --task TASK-NNN [--run RUN-NNN] [--title "..."] [--evidence "..."]
 /sc review migration --run
 /sc review release --run
 ```
 
-`review artifact --run` is CLI-native and returns a machine-readable 20-invariant project audit. Other review routes require repository reasoning and remain read-only unless fixes receive separate approval.
+`review artifact --run` is read-only and returns a machine-readable 21-invariant project audit. `--record` reruns that audit and persists its exact pass/fail result as a canonical `REV-NNN`; supplied evidence is additive and cannot turn a failed audit into a pass. Other review routes require repository reasoning and remain read-only unless fixes receive separate approval.
 
 ## Config and lifecycle
 
@@ -59,11 +63,13 @@ Creation options include `--title`, `--content`, repeated `--evidence`, repeated
 /sc config init --local|--shared|--lean|--no-agent-hint|--force
 /sc config update [all|codex|opencode|claude] [--migrate]
 /sc config migrate --to 2 --dry-run|--apply|--rollback
-/sc config doctor [all|codex|opencode|claude] [--strict]
+/sc config doctor [all|codex|opencode|claude] [--strict] [--recover]
 /sc config uninstall --force
 /sc config help <topic>
 ```
 
 Top-level CLI aliases (`init`, `update`, `migrate`, `doctor`, `uninstall`, `status`) remain available for shell automation. Ordinary update runs only a read-only migration preflight; `--migrate` is explicit application consent.
 
+Run transitions accept typed evidence through `--command`, `--test`, `--file`, `--review`, `--decision`, `--insight`, `--risk`, or generic `--evidence kind:value`. `doctor --recover` is an explicit write that resolves only safe pending kernel transactions; doctor without it remains read-only.
+
 Run `npx scrumrun@latest commands` for grammar rendered directly from the current manifest.

package/docs/ENTITY-MODEL.md

@@ -35,4 +35,4 @@ Feature and Sprint provide context/grouping and do not own execution history. Re
 
 ## Generated projections
 
-`state.md` summarizes active work/memory. `map.md` summarizes bounded nodes/edges. SQLite stores the complete derived graph/search index. All are fingerprinted or explicitly stale and can be rebuilt from Markdown plus source code.
+`state.md` summarizes active work/memory. `map.md` summarizes bounded nodes/edges. SQLite stores the complete derived graph/search index. All are fingerprinted or explicitly stale and can be rebuilt from Markdown plus source code. Freshness uses a metadata watch fast path and content-hash fallback; the watch is disposable evidence, never truth.

package/docs/RELEASE-SCORECARD.md

@@ -0,0 +1,43 @@
+# ScrumRun 2.1.1 Local Release Scorecard
+
+- Date: 2026-07-22
+- Package: `2.1.1`
+- Method contract: `2.0.0`
+- Scope: local implementation and package readiness; external registry/tag/release verification remains owner-gated.
+
+## Scoring rule
+
+A score of 9.5 or higher requires a single documented contract, machine enforcement on the critical path, adversarial/failure tests, deterministic recovery where mutation is involved, bounded performance, and an explicit residual-risk statement. Documentation alone cannot earn 9.5.
+
+| Area | Score | Executable evidence |
+|---|---:|---|
+| Conceptual model | 9.7 | Frozen Feature → Task → Sprint → Run → Memory schema; Task/Sprint and retry invariants; ADR-015 and ADR-018. |
+| Documentation architecture | 9.7 | SPEC is normative, CORE is operational, ADRs explain trade-offs, generated SCHEMA is drift-checked, README/skill/templates are conformance-tested. |
+| Artifact kernel | 9.7 | One executable schema, safe-path checks, lossless frontmatter transitions, conflict refusal, fsync atomic writes, and durable multi-file transactions with failure injection. |
+| Run history and audit | 9.8 | Stable ordered event ids, RFC3339 timestamps, typed evidence, state reconstruction, completion gates, retry preservation, explicit early-v2 migration, and byte-exact rollback. |
+| Real conformance | 9.7 | Twenty normative invariants point to executable tests; clean-project audit, malformed artifacts, secrets, symlinks, migration interruption, transaction interruption, and cache corruption are exercised. |
+| Local state and retrieval | 9.7 | Intake/state share one canonical fingerprint; state/map/SQLite expose staleness; metadata fast path falls back to full content hashes; cache schema mismatch rebuilds once; FTS5 capability is detected and a deterministic parameterized fallback preserves Node 22.13 retrieval. |
+| Overall operation | 9.7 | Read-only intake, explicit approval, atomic Task/Run creation, Policy Engine ids, migration preflight/apply/rollback, package E2E, installed-asset doctor, exact Node 22.13 regression coverage, Node 22/24/26 CI definition, and release budgets. |
+
+Minimum local score: **9.7/10**.
+
+## Release evidence
+
+- Full suite: `npm test`.
+- Performance suite: `npm run benchmark`.
+- Contract drift: `scripts/generate-contract-docs.js --check` runs before tests.
+- Project conformance: `/sc review artifact --run`, twenty-one invariants, zero findings at the release checkpoint.
+- Installed integration: `doctor codex --strict`, exact prompt/skill hashes and zero project findings.
+- Package boundary: `npm pack --dry-run --json`, explicit file inventory, no repository-local `.scrumrun/`, tests, vault, backup, migration state, or cache.
+- Tarball E2E: install, v2 memory, ongoing v1 migration, rollback, doctor, and uninstall run from the packed package in the test suite.
+
+The exact final tarball checksum belongs in the owner-gated release Review/Run after all included files are frozen; embedding a tarball's own checksum inside an included document would change that checksum.
+
+## Residual risks and gates
+
+- Registry smoke, npm dist-tags, `v2.1.1` tag, push, and GitHub release are not proven by local tests and require explicit owner authorization.
+- The built-in code-intelligence adapter currently covers JavaScript/TypeScript; other languages require replaceable adapters.
+- Remote Node 22/24/26 CI must pass on the release commit; the exact Node 22.13 container passes locally but does not replace the external gate.
+- Semantic retrieval is intentionally lexical/structural rather than a probabilistic embedding system; confirmed Markdown evidence remains the authority.
+
+These are bounded release or extension risks, not hidden correctness claims. A failed external gate stops promotion and results in a new immutable SemVer; it never rewrites an existing npm version.

package/docs/RELEASE.md

@@ -1,7 +1,9 @@
-# ScrumRun 2.0 Release Procedure
+# ScrumRun Package Release Procedure
 
 Publication is owner-gated. Tests, packaging, local commits, and release metadata preparation do not authorize npm publication, git push, tags, GitHub releases, or dist-tag changes.
 
+The npm package/CLI follows SemVer independently from the ScrumRun method contract. For this release, package `2.1.1` implements method `2.0.0`. Published packages `2.0.0` and `2.1.0` are immutable and must never be overwritten or reused.
+
 ## Local release gate
 
 ```bash
@@ -12,11 +14,13 @@ npm pack --dry-run
 npx scrumrun@latest sc review artifact --run   # in a clean v2 fixture/current package equivalent
 ```
 
-Confirm package contents exclude repository-local `.scrumrun/` state, caches, migration records, backups, vaults, tests, and secrets. The `.scrumrun/` directory inside project templates is expected. Confirm `package.json`, README, changelog, SPEC, CORE, skill, migration guide, and tag all name 2.0.0.
+Confirm package contents exclude repository-local `.scrumrun/` state, caches, migration records, backups, vaults, tests, and secrets. The `.scrumrun/` directory inside project templates is expected. Confirm package metadata, README, changelog, tarball filename, checksum, and Git tag agree on `2.1.1`; SPEC, CORE, artifact frontmatter, migration, and installed skill continue to declare method `2.0.0`.
+
+Record the local evidence and residual risks against [`RELEASE-SCORECARD.md`](./RELEASE-SCORECARD.md). Scores describe local readiness only and never replace registry smoke or owner approval.
 
-## Release candidate (owner approval required)
+## Optional registry candidate (separate owner approval required)
 
-1. Set `2.0.0-rc.1` metadata and create a reviewed commit.
+1. Set a new unpublished prerelease such as `2.1.1-rc.1` and create a reviewed commit.
 2. `npm pack`; record tarball SHA-256/integrity.
 3. Publish to `next`, never `latest`:
 
@@ -28,17 +32,20 @@ Confirm package contents exclude repository-local `.scrumrun/` state, caches, mi
 5. Run init, intake/approval, memory confirmation/query, v1 update preflight/apply/rollback, doctor, and uninstall.
 6. Fix findings in a new RC; never replace an already-published version.
 
-## Final promotion (new owner approval required)
+An RC is immutable. Fixes create `rc.2`, `rc.3`, and so on. Skipping an RC does not skip any local, tarball, owner, registry-smoke, or final-promotion gate.
+
+## Final release (new owner approval required)
 
-1. Set `2.0.0`, rerun every local/registry gate, and create the final metadata commit.
-2. Create/push tag `v2.0.0` and publish npm `2.0.0`.
-3. Promote `latest` only after registry smoke tests pass.
-4. Create the GitHub release from `CHANGELOG.md` and link the migration guide.
-5. Verify npm metadata, Git tag/commit, GitHub release, README, and checksums agree.
+1. Set `2.1.1`, rerun every local gate, inspect the exact tarball, and create the final local metadata commit.
+2. Stop and request explicit owner authorization for each external boundary.
+3. Publish npm `2.1.1` to `next` using the reviewed tarball/source commit (`npm publish --tag next`); never publish from a changed worktree and do not move `latest` yet.
+4. Install the registry artifact in a clean fixture and run init, intake/approval, Run lifecycle, memory query, v1 migration apply/rollback, doctor, and uninstall.
+5. Only after registry smoke passes, create/push tag `v2.1.1`, promote/verify `latest` with an explicit dist-tag command, and create the GitHub release from `CHANGELOG.md` with the migration guide and checksum.
+6. Verify npm metadata, dist-tags, Git tag/commit, GitHub release, README, and checksums all agree.
 
 ## Recovery
 
 - RC defect: publish another RC; keep `latest` unchanged.
-- Final package defect before `latest`: do not promote; publish `2.0.1` after correction if 2.0.0 already exists.
-- Defect after `latest`: assess deprecation vs immediate 2.0.1; never overwrite/unpublish without explicit owner decision and npm-policy review.
+- Final package defect before `latest`: do not promote; publish a new patch after correction because `2.1.1` cannot be replaced.
+- Defect after `latest`: assess deprecation vs immediate patch; never overwrite/unpublish without explicit owner decision and current npm-policy review.
 - Migration issue: stop promotion, preserve registry artifact/checksum, use the documented rollback fixture, and publish a corrected version.

package/docs/SCHEMA.md

@@ -46,9 +46,20 @@ Task is the atomic unit. A Task may have zero or one Sprint. A Task may have man
 | Field | Kinds | Presence | Type | Meaning |
 |---|---|---|---|---|
 | `attempt` | run | required | positive integer | monotonic execution-attempt number within one Task |
+| `ledger` | run | optional | integer 1 | canonical Run event-ledger schema; required for newly authored Runs |
+| `guardrails` | run | optional | integer 1 | append-only Guardrail obligation schema |
+| `workspace` | run | optional | integer 1 | workspace mutation-gateway schema |
 
 Native creation uses the declared initial statuses. Migration may restore a historical non-initial status only with provenance and validation.
 
+## Run event ledger
+
+Newly authored Runs use `ledger: 1`. Their `## Events` section contains append-only JSON event blocks with stable ids in the form `RUN-NNN-EVT-NNN`.
+
+Every event requires `schema`, `id`, contiguous `sequence`, RFC3339 `occurred_at`, `timestamp_precision`, `actor`, `from`, `to`, `reason`, and structured `evidence`. Event types are `transition`, `snapshot`, `guardrail`, `mutation`. Evidence kinds are `approval`, `command`, `test`, `file`, `review`, `decision`, `insight`, `risk`, `note`, `migration`, `legacy`, `guardrail`, `mutation`.
+
+A native ledger begins with `created → executing`; an evidenced migration `snapshot` may establish one historical baseline without inventing missing transitions. Event order, transition legality, final status, updated date, and completion evidence are machine-validated. Run owns the event history; Task stores its intended scope and synchronized current status without copying Run events.
+
 ## Truth questions
 
 - **feature:** Why does this initiative exist?

package/docs/SEMANTIC-MEMORY.md

@@ -65,4 +65,4 @@ npx scrumrun@latest sc knowledge study calculateFinalPrice
 npx scrumrun@latest sc knowledge context --clear
 ```
 
-SQLite is ignored and disposable. Queries default to 10 records/40 relations and hard-cap at 100/100. Match type, truth state, warnings, relation counts, and evidence are returned so recommendations remain explainable.
+SQLite is ignored and disposable. The derived index records its search backend: FTS5/BM25 is selected when the current Node.js SQLite build supports it; otherwise ScrumRun uses deterministic parameterized token matching over the same artifact, code, and relation tables. Queries default to 10 records/40 relations and hard-cap at 100/100. Match type, truth state, warnings, relation counts, and evidence are returned so recommendations remain explainable.

package/docs/TROUBLESHOOTING.md

@@ -25,8 +25,20 @@ Rollback detected post-migration work that it would erase. Copy/export wanted ch
 npx scrumrun@latest sc knowledge map --build
 ```
 
+Fresh projections include a source fingerprint and a watch fingerprint. A matching watch avoids a full read. If file metadata changed, ScrumRun hashes canonical/source content before deciding whether the projection is actually stale. `check: "schema"` means the disposable SQLite format changed and one rebuild is required; `check: "hash"` means the safe fallback was used.
+
 Stale generated views are warnings, not canonical corruption.
 
+## Doctor reports `TRANSACTION_PENDING`
+
+An approved multi-file mutation was interrupted after its durable journal was prepared. Ordinary doctor/audit is read-only and leaves the evidence untouched. Either retry the same approved operation, which recovers before writing, or explicitly run:
+
+```bash
+npx scrumrun@latest doctor codex --recover --strict
+```
+
+Prepared transactions restore their original bytes; committed transactions verify the applied bytes and finalize. Recovery refuses if a target changed to content matching neither journal side, because that would overwrite later owner work. Receipts contain hashes and outcomes, not file contents.
+
 ## SQLite is missing/corrupt
 
 Delete or clear only the disposable cache:
@@ -59,7 +71,7 @@ Use `doctor --compat` only while validating one-cycle v1 adapters.
 
 ## Node.js is unsupported
 
-ScrumRun 2.0 requires Node.js `>=22.13.0` because semantic indexing uses native `node:sqlite`. Upgrade Node, then rerun doctor.
+ScrumRun 2.0 requires Node.js `>=22.13.0` because semantic indexing uses native `node:sqlite`. FTS5/BM25 is used when the runtime provides it; Node builds without FTS5 use the deterministic lexical fallback. Upgrade Node, then rerun doctor.
 
 ## Safe uninstall
 

package/lib/commands/manifest.js

@@ -9,7 +9,19 @@ const nouns = Object.freeze({
       task: ["--add [--type fix] [--status backlog]", "--list", "--show", "--run", "--audit", "--cancel", "--retry"],
       sprint: ["--add", "--list", "--show", "--start", "--complete", "--block"],
       feature: ["--add", "--list", "--show", "--activate", "--complete"],
-      run: ["--list", "--show", "--validate", "--learn", "--complete", "--resume", "--fail", "--block"],
+      run: [
+        "--list",
+        "--show",
+        "--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]",
+        "--validate [--note] [--evidence] [--command] [--test] [--file] [--review] [--actor] [--at]",
+        "--learn [--note] [--evidence] [--decision] [--insight] [--file] [--actor] [--at]",
+        "--complete [--note] [--evidence] [--review] [--test] [--file] [--actor] [--at]",
+        "--resume [--note] [--evidence] [--risk] [--actor] [--at]",
+        "--fail [--note] [--evidence] [--risk] [--test] [--actor] [--at]",
+        "--block [--note] [--evidence] [--risk] [--actor] [--at]"
+      ],
       intake: ["<request>", "--request", "--approve"],
       challenge: ["<question>"]
     }
@@ -38,7 +50,7 @@ const nouns = Object.freeze({
     description: "run scoped evidence-based quality gates",
     subjects: {
       code: ["--run"],
-      artifact: ["--run"],
+      artifact: ["--run", "--record --task <TASK-NNN> [--run <RUN-NNN>] [--title] [--evidence]"],
       migration: ["--run"],
       release: ["--run"]
     }
@@ -50,7 +62,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]", "codex [--strict]", "opencode [--strict]", "claude [--strict]"],
+      doctor: ["all [--strict] [--recover]", "codex [--strict] [--recover]", "opencode [--strict] [--recover]", "claude [--strict] [--recover]"],
       uninstall: ["--force"],
       help: ["<topic>"]
     }

package/lib/commands/render.js

@@ -31,7 +31,11 @@ ${grammarLines().join("\n")}
 - Intake, contextualization, policy, risk, classification, and planning are read-only until explicit approval.
 - Approved work creates/updates a Task and creates a Run; a Sprint only groups Tasks when a real timebox/batch exists.
 - Run execution follows \`executing → validating → learning → completed|failed|blocked\`.
+- Run owns one structured, evidenced event ledger; Task synchronizes current status without copying Run history.
+- Linked Task/Run writes use a durable recovery journal; audit reports pending recovery and never repairs without explicit authorization.
 - \`guardrails.md\` is canonical project policy; \`golden-rules.md\` is v1 compatibility only.
+- Evaluate active Guardrails as \`passed\`, \`blocked\`, or \`deferred\`; cite exact \`GR-NNN\` ids and keep deferred execution gates visible.
+- Persist deferred checks as Run obligations. Every material source edit requires a short-lived path-scoped Mutation Gateway permit and immediate hash recording; policy/workspace drift or unresolved obligations block completion.
 - Knowledge/Decision/Insight records require evidence; AI-proposed Insights remain \`candidate\` until confirmed.
 - Never print vault values or write before approval.
 - Unknown nouns, subjects, actions, ids, or ambiguous approval must produce a deterministic explanation, never a guessed mutation.