scrumrun 2.1.0 → 2.1.1

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+### Security
+
+- Added fail-closed, 15-minute, path-scoped Mutation Gateway permits with policy/workspace binding, before/after hashes, read-only and symlink checks, new-secret detection, and append-only Run evidence.
+- Deferred Guardrails now become persisted Run obligations; unresolved obligations, policy drift, workspace bypass, and pending canonical transactions block completion.
+- Fresh and explicitly migrated projects require structured `Status`, `Enforcement`, `Scope`, and `Rule` fields and advertise Guardrail, obligation, and Mutation Gateway schemas in `method.json`.
+
+### Changed
+
+- Project conformance now covers 21 executable invariants and detects active Run mutation bypasses.
+
+## 2.1.1 - 2026-07-22
+
+### Fixed
+
+- Semantic indexing now detects whether the current `node:sqlite` build provides FTS5 instead of assuming the optional module exists.
+- Node.js 22.13 uses a deterministic, parameterized lexical fallback for artifact and code search while runtimes with FTS5 retain BM25 retrieval.
+- Semantic cache schema 4 records the selected search backend and safely rebuilds an FTS5 cache when it is opened by a runtime without FTS5.
+
+### Validation
+
+- Added explicit automatic-backend and forced-fallback tests, including multi-token matching, code-symbol retrieval, cache metadata, and absence of FTS virtual tables.
+- The complete 143-test suite passes in the exact `node:22.13.0` runtime that exposed the release regression.
+
 ## 2.1.0 - 2026-07-22
 
 ### Added

package/CORE.md

@@ -150,7 +150,7 @@ Intake must:
 
 Policy evaluation is structured per active `GR-NNN`: `passed`, `blocked`, or `deferred`. A block must cite the exact Guardrail id and reason code. Deferred checks must be visible in the plan and re-evaluated at their named execution boundary; they are never silently counted as passed. Invalid/duplicate Guardrails or configuration that weakens approval block conformance and intake.
 
-Before approval, do not create canonical files, update status, edit application code, or retain request content outside ignored disposable context cache. Ambiguous acknowledgement is not approval.
+Before approval, do not create canonical files, update status, edit application code, or retain request content outside ignored disposable context cache. The approval token binds both canonical context and the workspace fingerprint; drift in either requires a new intake. Ambiguous acknowledgement is not approval.
 
 ## Execution lifecycle
 
@@ -174,6 +174,9 @@ Rules:
 - validation, learning, completion, failure, block, and resume require a reason or evidence;
 - validation must match the risk and acceptance criteria;
 - configured reviews run before completion;
+- every deferred policy result is persisted as a Run Guardrail obligation;
+- before changing application/source files, issue a short-lived path-scoped mutation permit and record the verified before/after hashes in the Run;
+- unrecorded workspace drift, policy drift, out-of-scope paths, unsafe symlinks, new secret-like content, or unresolved obligations block validation/completion;
 - learning proposes memory candidates after validation and never auto-confirms AI inference;
 - complete a Sprint only when all its included Tasks meet the Sprint exit gate;
 - do not mark work complete merely because time or token budget ended.
@@ -248,7 +251,7 @@ Legacy sprint plan entries normally become Tasks. History attempts become Runs w
 - `task --add|--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|--record-mutation|--satisfy-guardrail|--validate|--learn|--complete|--resume|--fail|--block`
 - `intake <request>`
 - `challenge <question>`
 
@@ -293,6 +296,7 @@ Review is read-only unless fixes are separately authorized. Report findings by s
 - No execution without explicit valid approval.
 - Guardrails cannot be bypassed; they may only be superseded/retired with history.
 - Active Guardrails produce explicit passed/blocked/deferred evaluations; blocks cite stable ids and deferred checks remain visible until their execution gate.
+- Material mutations require path-scoped permits and append-only hash evidence; completion fails closed on policy/workspace drift or unresolved obligations.
 - Task is atomic; Sprint is grouping; Run is an attempt.
 - Retries preserve prior Runs.
 - History is append-only.

package/MIGRATION-1-to-2.md

@@ -34,14 +34,14 @@ npx scrumrun@latest update --migrate
 
 ### Early v2 Run upgrade
 
-Projects created by the first 2.0.0 build may contain prose-based Run transitions. The same ongoing-project commands detect this layout without writes and, after explicit `--migrate`, upgrade it to ledger schema 1:
+Projects created by earlier 2.x builds may contain prose-based Run transitions or inferred Guardrail fields. The same ongoing-project commands detect this layout without writes and, after explicit `--migrate`, upgrade the Run ledger and security schemas:
 
 ```text
 .scrumrun/.migration/run-ledger-v1/manifest.json
 .scrumrun/.migration/run-ledger-v1/backup/runs/RUN-NNN.md
 ```
 
-Every changed Run and `method.json` is hashed and backed up byte-exactly. Proven transition chains become ordered `RUN-NNN-EVT-NNN` events. When only the recorded status is provable, migration emits one evidenced `snapshot`; it does not invent the missing path. Replay is idempotent, an interrupted apply restores prepared sources, and rollback refuses when a Run changed after migration.
+Every changed Run, `guardrails.md`, and `method.json` is hashed and backed up byte-exactly. Inferred legacy Guardrail fields become explicit without deleting the original prose. Proven transition chains become ordered `RUN-NNN-EVT-NNN` events. When only the recorded status is provable, migration emits one evidenced `snapshot`; it does not invent the missing path. Existing terminal Runs remain historical; new/retried Runs bind policy obligations and the Mutation Gateway. Replay is idempotent, an interrupted apply restores prepared sources, and rollback refuses when a changed artifact moved after migration.
 
 ## Standalone flow
 

package/README.md

@@ -4,7 +4,7 @@
 
 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.0` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
+**Package:** `2.1.1` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
 
 ## The model
 
@@ -94,7 +94,7 @@ The agent can answer questions such as:
 
 AI extraction creates candidates only. Confirmation requires resolvable evidence. Stale and invalidated memory is labeled; rejected/deprecated/invalidated records are excluded from active truth by default.
 
-The fast graph/search layer is `.scrumrun/.cache/semantic-index.sqlite`. It is ignored and disposable: deleting it never deletes knowledge. Unchanged queries use a metadata-only freshness check; metadata drift falls back to complete content fingerprints before rebuilding. Cache-schema upgrades force one safe disposable rebuild. The current JavaScript/TypeScript adapter derives qualified symbols plus `defined_in`, `depends_on`, `used_by`, and `protected_by` relations.
+The fast graph/search layer is `.scrumrun/.cache/semantic-index.sqlite`. It is ignored and disposable: deleting it never deletes knowledge. The index selects FTS5/BM25 when the current Node.js SQLite build provides it and otherwise uses a deterministic, parameterized lexical fallback; both backends preserve bounded graph retrieval without changing canonical Markdown. Unchanged queries use a metadata-only freshness check; metadata drift falls back to complete content fingerprints before rebuilding. Cache-schema upgrades force one safe disposable rebuild. The current JavaScript/TypeScript adapter derives qualified symbols plus `defined_in`, `depends_on`, `used_by`, and `protected_by` relations.
 
 `map.md` is shown only when its source fingerprint matches the current semantic index. A fresh placeholder or stale map is rejected with an explicit rebuild instruction instead of being presented as project truth.
 
@@ -157,6 +157,8 @@ npx scrumrun@latest doctor codex --strict
 
 `guardrails.md` is canonical project policy. Active `GR-NNN` rules are evaluated into explicit `passed`, `blocked`, or `deferred` results; blocks identify the exact Guardrail and deferred checks stay visible for their execution-time gate. `config.md` contains preferences and cannot weaken policy. Duplicate/unknown Guardrails, disabled approval, and unsafe read-only paths fail conformance. `state.md`, `map.md`, context packages, and SQLite are generated navigation aids, never authority. `state.md` carries the same source fingerprint used by intake, an RFC3339 generation time, and a watch fingerprint for fast verified staleness checks.
 
+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.
+
 ## Useful commands
 
 ```bash
@@ -167,8 +169,14 @@ npx scrumrun@latest commands
 npx scrumrun@latest sc plan intake "Fix pricing rounding"
 npx scrumrun@latest sc plan intake --approve <token>
 
-# verify canonical policy and all twenty executable invariants
+# authorize and record a material source mutation
+npx scrumrun@latest sc plan run --authorize-mutation RUN-001 --path src/pricing.ts
+npx scrumrun@latest sc plan run --record-mutation RUN-001 --permit MUT-... --note "Pricing change recorded"
+
+# record an audit-derived Review, then resolve a persisted completion gate
 npx scrumrun@latest sc review artifact --run
+npx scrumrun@latest sc review artifact --record --task TASK-001 --run RUN-001 --evidence "npm test: passed"
+npx scrumrun@latest sc plan run --satisfy-guardrail RUN-001 --guardrail GR-003 --review REV-001
 
 # memory lifecycle
 npx scrumrun@latest sc knowledge insight --propose "Pricing stays in backend" --evidence src/pricing.ts
@@ -180,7 +188,7 @@ npx scrumrun@latest sc knowledge map --build
 npx scrumrun@latest sc knowledge map --show
 ```
 
-The command manifest in `lib/commands/manifest.js` generates help and compatibility adapters, preventing client grammar drift.
+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.
 
 ## Documentation
 

package/SPEC.md

@@ -196,10 +196,12 @@ RECEIVED
   → COMPLETED | FAILED | BLOCKED
 ```
 
-Everything through `AWAITING_APPROVAL` is read-only. It may exist in process memory or ignored cache only. A valid approval token binds the normalized request, policy result, classification, risk, issuance time, and canonical context fingerprint.
+Everything through `AWAITING_APPROVAL` is read-only. It may exist in process memory or ignored cache only. A valid approval token binds the normalized request, policy result, classification, risk, issuance time, canonical context fingerprint, and complete workspace fingerprint. Canonical or source drift after planning invalidates approval.
 
 Approval atomically creates one Task and its first Run. If either write fails, neither may remain. Project changes after planning invalidate the token. Reusing a successfully consumed token is idempotent.
 
+The approved Run binds the exact Guardrail-policy fingerprint and a canonical workspace baseline. Every post-approval `deferred` check becomes an append-only Guardrail obligation. A material source mutation requires a short-lived, path-scoped permit issued from that baseline; recording it verifies before/after hashes, policy freshness, path scope, read-only boundaries, symlink safety, and newly introduced secret-like content. Unrecorded workspace drift fails closed. A Run cannot complete while an obligation is unresolved or the workspace differs from its last recorded mutation.
+
 Run transitions synchronously update the linked Task and append exactly one structured event to the Run ledger. Validation, learning, completion, failure, block, and resume transitions require a reason or typed evidence. Task status changes without receiving a duplicate narrative history. Multi-file mutations use a durable local transaction journal: `prepared` operations roll back byte-exactly after failure/interruption, while `committed` journals are verified and finalized. Ordinary audit is read-only and reports pending recovery; `doctor --recover` or retrying the approved mutation performs recovery explicitly. Entering `learning` may extract structured candidates from the Run, but extraction failure never blocks Run progress.
 
 ## 6. Policy and precedence
@@ -303,6 +305,7 @@ Legacy sprint entries become Tasks. History entries become Runs only with an evi
 - **I-18** Partial/interrupted writes, conflicting overwrites, unsafe paths, and symlink traversal fail or recover without corrupting canonical state or overwriting later owner work.
 - **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.
 
 ## 11. Command grammar
 
@@ -320,7 +323,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-20;
+1. passes positive and negative tests for I-01 through I-21;
 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

@@ -20,6 +20,8 @@ const { aliases: COMMAND_ALIASES, resolveAlias, resolveRoute } = require(path.jo
 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, mapStatus, queryIndex, rebuildIndex, writeMap } = require(path.join(root, "lib", "memory", "index"));
 const { auditProject } = require(path.join(root, "lib", "v2", "conformance"));
@@ -1236,6 +1238,19 @@ function runTransitionOptions(args) {
   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));
@@ -1373,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",
@@ -1403,6 +1445,20 @@ 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";

package/docs/COMMANDS.md

@@ -17,10 +17,13 @@ Use `/sc` inside a supported AI client. The equivalent CLI form is `npx scrumrun
 /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 [--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
 

package/docs/RELEASE-SCORECARD.md

@@ -1,9 +1,9 @@
-# ScrumRun 2.1.0 Local Release Scorecard
+# ScrumRun 2.1.1 Local Release Scorecard
 
-Date: 2026-07-22  
-Package: `2.1.0`  
-Method contract: `2.0.0`  
-Scope: local implementation and package readiness; external registry/tag/release verification remains owner-gated.
+- 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
 
@@ -16,17 +16,17 @@ A score of 9.5 or higher requires a single documented contract, machine enforcem
 | 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.6 | 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; stale map display is refused. |
-| Overall operation | 9.6 | Read-only intake, explicit approval, atomic Task/Run creation, Policy Engine ids, migration preflight/apply/rollback, package E2E, installed-asset doctor, Node 22/24/26 CI definition, and release budgets. |
+| 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.6/10**.
+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 invariants, zero findings at the release checkpoint.
+- 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.
@@ -35,9 +35,9 @@ The exact final tarball checksum belongs in the owner-gated release Review/Run a
 
 ## Residual risks and gates
 
-- Registry smoke, npm dist-tags, `v2.1.0` tag, push, and GitHub release are not proven by local tests and require explicit owner authorization.
+- 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 even though the same matrix is declared locally in `.github/workflows/ci.yml`.
+- 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

@@ -2,7 +2,7 @@
 
 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.0` implements method `2.0.0`. Published package `2.0.0` is immutable and must never be overwritten or reused.
+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
 
@@ -14,13 +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 metadata, README, changelog, tarball filename, checksum, and Git tag agree on `2.1.0`; SPEC, CORE, artifact frontmatter, migration, and installed skill continue to declare method `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.
 
 ## Optional registry candidate (separate owner approval required)
 
-1. Set a new unpublished prerelease such as `2.1.0-rc.1` 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`:
 
@@ -36,16 +36,16 @@ An RC is immutable. Fixes create `rc.2`, `rc.3`, and so on. Skipping an RC does
 
 ## Final release (new owner approval required)
 
-1. Set `2.1.0`, rerun every local gate, inspect the exact tarball, and create the final local metadata commit.
+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.0` to `next` using the reviewed tarball/source commit (`npm publish --tag next`); never publish from a changed worktree and do not move `latest` yet.
+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.0`, promote/verify `latest` with an explicit dist-tag command, and create the GitHub release from `CHANGELOG.md` with the migration guide and checksum.
+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 a new patch after correction because `2.1.0` cannot be replaced.
+- 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

@@ -47,6 +47,8 @@ Task is the atomic unit. A Task may have zero or one Sprint. A Task may have man
 |---|---|---|---|---|
 | `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.
 
@@ -54,7 +56,7 @@ Native creation uses the declared initial statuses. Migration may restore a hist
 
 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`. Evidence kinds are `approval`, `command`, `test`, `file`, `review`, `decision`, `insight`, `risk`, `note`, `migration`, `legacy`.
+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.
 

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

@@ -71,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

@@ -12,6 +12,9 @@ const nouns = Object.freeze({
       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]",
@@ -47,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"]
     }

package/lib/commands/render.js

@@ -35,6 +35,7 @@ ${grammarLines().join("\n")}
 - 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.