scrumrun 2.0.0 → 2.1.1

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 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
+
+- Canonical Run ledger schema with stable event ids, RFC3339 timestamps, actors, reasons, and typed evidence.
+- Explicit early-v2 Run-ledger preflight/apply/rollback through `migrate --to 2` and `update --migrate`.
+- Conformance checks that reconstruct Run state and detect event-order, evidence, timestamp, and frontmatter drift.
+- Durable multi-file mutation journal with byte-exact rollback, interruption recovery, hash-only receipts, and explicit `doctor --recover`.
+- Executable Policy Engine with stable Guardrail ids, explicit passed/blocked/deferred results, and deterministic conformance checks.
+- Shared canonical projection fingerprint plus metadata-watch/content-hash freshness checks for `state.md`, `map.md`, and semantic SQLite.
+- Evidence-backed release scorecard separating local readiness from external registry/tag gates.
+
+### Changed
+
+- Run is now the sole operational-history authority; Task status is synchronized without duplicated transition prose.
+- Run completion requires evidenced validation, learning, and completion transitions.
+- Intake classification and risk detection now recognize multilingual runtime, schema, migration, transaction, release, and cross-cutting signals.
+- Semantic cache schema 3 removes commit-only invalidation and performs a one-time disposable rebuild from older cache schemas.
+- `map --show` now refuses missing or stale fingerprints instead of presenting an unverified projection.
+
 ## 2.0.0 - 2026-07-21
 
 ### Breaking

package/CORE.md

@@ -84,6 +84,8 @@ AGENTS.md
 
 Canonical truth is Markdown. SQLite/cache data stores only rebuildable indexes, symbol projections, relations, and bounded context packages. Deleting `.cache/` must never delete authored truth.
 
+`state.md` and the semantic index use two-tier freshness checks. Matching path/stat watch fingerprints avoid rereading unchanged sources; any metadata drift falls back to complete content hashing. A cache schema mismatch rebuilds the disposable index once. Watch metadata is only an optimization and never authority.
+
 `vault.local.md`, migration backups, and caches are local-only. Their values never appear in logs, history, reviews, memory, reports, commits, or normal responses.
 
 ## Authority and read policy
@@ -146,7 +148,9 @@ Intake must:
 5. recommend one route and, in guided mode, at most two useful alternatives;
 6. ask one explicit approval question before execution; config may change presentation, never remove the gate.
 
-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.
+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. 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
 
@@ -165,15 +169,22 @@ Rules:
 
 - one Run belongs to one Task;
 - one Task may have multiple immutable attempts;
-- every state transition writes exactly one append-only history event;
+- every state transition writes exactly one append-only `RUN-NNN-EVT-NNN` JSON event with RFC3339 time, actor, reason, and typed evidence;
+- the Run ledger is operational history; Task synchronizes current status without copying the Run event;
+- 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.
 
 Canonical mutations are schema-validated, lossless, and atomic. Preserve unknown fields, prose, and unrelated owner edits. A failed mutation must leave canonical state unchanged or recoverable.
 
+Task/Run pair mutations use an ignored durable journal under `.scrumrun/.backup/transactions/`. A captured failure rolls back immediately; an interrupted `prepared` transaction is rolled back before the next approved mutation, while an interrupted `committed` transaction is verified and finalized. Audit only reports `TRANSACTION_PENDING`. Recovery writes occur only when the approved operation is retried or `doctor --recover` is explicitly invoked, and recovery refuses to overwrite bytes that match neither side of the journal.
+
 ## Semantic memory
 
 ### Knowledge
@@ -220,6 +231,7 @@ scrumrun migrate --to 2 --rollback
 ```
 
 - ordinary install/update never applies a migration; update performs a read-only v1 preflight, and only explicit `update --migrate` applies its verified plan;
+- early v2 Run prose is also preflighted read-only and upgraded explicitly to ledger schema 1 with byte-exact backup and safe rollback;
 - dry-run writes no project data;
 - apply inventories source hashes, creates a byte-exact local backup, transforms in staging, validates, and activates by atomic directory swap;
 - incomplete hybrid v1/v2 trees reuse existing evidenced canonical relations instead of creating duplicate Tasks/Runs;
@@ -239,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>`
 
@@ -283,6 +295,8 @@ Review is read-only unless fixes are separately authorized. Report findings by s
 - Intake is read-only.
 - 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/DECISIONS.md

@@ -294,3 +294,59 @@ Date: 2026-07-21
 **Consequences** — Ongoing projects cannot silently miss the required migration, while automation and cautious users retain a zero-write default. Cost: update output is longer inside a v1 project and the update command must remain migration-aware.
 
 **Alternatives considered** — Automatically applying during every update: rejected because updating client integrations is not implicit consent to rewrite project state. Keeping update unaware: safer in isolation but makes partial upgrades easy and confusing.
+
+---
+
+## ADR-021 — Run owns a structured append-only event ledger
+Status: accepted
+Date: 2026-07-22
+
+**Context** — A prose `history.md` made operational truth expensive to parse and allowed two incompatible event formats, ambiguous same-day entries, duplicated Task/Run history, and status derived from punctuation-sensitive text.
+
+**Decision** — Run is the sole operational-history authority. Every native Run stores schema-versioned `RUN-NNN-EVT-NNN` JSON events with RFC3339 time, actor, ordered `from`/`to`, reason, and typed evidence. Task synchronizes current status without copying event prose. Early-v2 Runs migrate explicitly: deterministic chains are recovered; ambiguity becomes an evidenced snapshot rather than an invented transition.
+
+**Consequences** — Status reconstruction and audit are deterministic, retries preserve attempts, and agents can retrieve a bounded Run instead of rereading a global log. Cost: event/schema migrations and stricter evidence gates become release obligations.
+
+**Alternatives considered** — Keep one append-only Markdown history with a better template: simpler storage, but still global, token-heavy, and vulnerable to parser drift. Duplicate transitions into Task: convenient locally but creates two authorities.
+
+---
+
+## ADR-022 — Canonical multi-file mutations use durable local transactions
+Status: accepted
+Date: 2026-07-22
+
+**Context** — Approval, Run transitions, and retries update linked artifacts. Per-file atomic rename prevents partial bytes but cannot prevent a crash after only one file has committed.
+
+**Decision** — Linked canonical mutations use an ignored durable transaction journal with prepared/committed states, byte-exact before images, content hashes, fsync-backed writes, deterministic recovery, and hash-only receipts. Prepared work rolls back; committed work is verified and finalized. Recovery refuses to overwrite owner changes made after interruption. Ordinary audit reports pending recovery but remains read-only.
+
+**Consequences** — Task/Run pairs cannot silently diverge after an interrupted mutation. Failure injection proves rollback and recovery. Cost: more local I/O and a transaction schema that must be validated as hostile input.
+
+**Alternatives considered** — Best-effort compensating writes: cannot distinguish interruption from later owner edits. SQLite as canonical transaction store: violates Markdown portability and creates another authority.
+
+---
+
+## ADR-023 — Guardrails are evaluated by an executable Policy Engine
+Status: accepted
+Date: 2026-07-22
+
+**Context** — Canonical Guardrails without deterministic evaluation could be present in context yet silently ignored or described as passed. Migrated prose also makes aggressive inference unsafe.
+
+**Decision** — Active stable-id Guardrails produce structured `passed`, `blocked`, or `deferred` evaluations. Blocks cite the exact `GR-NNN` id and reason code. Deferred checks remain visible for their mutation, migration, review, or owner boundary. Fresh rules declare enforcement explicitly; migrated prose uses conservative inference and ambiguous rules stay manual. Configuration cannot disable approval or weaken active policy.
+
+**Consequences** — Policy advice is traceable to project authority instead of model opinion, while uncertainty stays explicit. Cost: not every project rule can be automated; manual/deferred enforcement remains a first-class result.
+
+**Alternatives considered** — Treat every loaded rule as passed unless a keyword matches: false assurance. Block all manual rules at intake: safe but makes legitimate project-specific policy unusable.
+
+---
+
+## ADR-024 — Derived freshness uses metadata fast path and content-hash fallback
+Status: accepted
+Date: 2026-07-22
+
+**Context** — Recomputing every artifact hash and reparsing the entire code graph before each status or semantic query makes a disposable index defeat its purpose. Trusting timestamps alone would make cache metadata an accidental authority.
+
+**Decision** — `state.md` and semantic SQLite store a source fingerprint plus a watch fingerprint over path/stat identity. An unchanged watch avoids source reads. Any metadata drift triggers a complete canonical/source content fingerprint before staleness is asserted. Cache schemas are explicit and mismatches force one rebuild. Commit-only changes do not invalidate semantically unchanged code.
+
+**Consequences** — Normal queries stay fast while content remains the final verifier. State and intake share one canonical fingerprint implementation. Cost: metadata-only touches may trigger one full verification, and scanner changes require a cache-schema bump.
+
+**Alternatives considered** — Hash every source on every query: maximally simple but O(project) on the hot path. Timestamp-only cache validity: faster but allows derived metadata to masquerade as truth.

package/MIGRATION-1-to-2.md

@@ -32,6 +32,17 @@ npx scrumrun@latest update --migrate
 
 `--migrate` is explicit consent. Ordinary update never changes canonical project data.
 
+### Early v2 Run upgrade
+
+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, `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
 
 ```bash

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.
 
-**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
 
@@ -71,6 +71,10 @@ EXECUTING → VALIDATING → LEARNING → COMPLETED | FAILED | BLOCKED
 
 Nothing canonical is persisted before approval. Failed retries remain available as separate Runs.
 
+Each Run contains a machine-validated event ledger. Events have stable ids such as `RUN-044-EVT-003`, RFC3339 timestamps, actors, reasons, and typed evidence for commands, tests, files, reviews, decisions, insights, and risks. Run is the only operational history; Task keeps its approved scope and synchronized current status without duplicating those events. Completion is rejected when validation or learning evidence is missing.
+
+Linked Task/Run writes use a durable ignored transaction journal. Captured failures roll back immediately; interrupted operations are recovered byte-exactly on retry or through explicit `doctor --recover`. Read-only audit reports pending recovery and never repairs state silently.
+
 ## Semantic project memory
 
 Canonical memory is human-readable Markdown:
@@ -90,7 +94,9 @@ 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. 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.
 
 ## Migrating an ongoing v1 project
 
@@ -114,7 +120,7 @@ npx scrumrun@latest migrate --to 2 --apply
 npx scrumrun@latest migrate --to 2 --rollback
 ```
 
-Migration uses content hashes, a byte-exact ignored backup, staging validation, an atomic directory switch, a source-to-destination report, idempotent replay, and rollback protection. It also recognizes incomplete hybrid v1/v2 trees, reuses already-linked canonical work, and normalizes only deterministic schema aliases. Legacy-only files leave the active tree but remain byte-exact in the ignored backup; vault contents remain local. Ambiguous history remains an explicit warning, and the migrator never invents a Sprint or Run.
+Migration uses content hashes, a byte-exact ignored backup, staging validation, an atomic directory switch, a source-to-destination report, idempotent replay, and rollback protection. It also recognizes incomplete hybrid v1/v2 trees, reuses already-linked canonical work, and normalizes only deterministic schema aliases. Early v2 Run prose is preflighted and upgraded to the structured ledger by the same explicit `update --migrate` gate; ambiguous paths become evidenced snapshots instead of invented transitions. Legacy-only files leave the active tree but remain byte-exact in the ignored backup; vault contents remain local. Ambiguous history remains an explicit warning, and the migrator never invents a Sprint or Run.
 
 After migration or an integration update, verify both installed assets and project state:
 
@@ -149,7 +155,9 @@ npx scrumrun@latest doctor codex --strict
   vault.local.md                   # optional, ignored, never indexed
 ```
 
-`guardrails.md` is canonical project policy. `config.md` contains preferences and cannot weaken it. `state.md`, `map.md`, context packages, and SQLite are generated navigation aids, never authority.
+`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
 
@@ -161,6 +169,15 @@ npx scrumrun@latest commands
 npx scrumrun@latest sc plan intake "Fix pricing rounding"
 npx scrumrun@latest sc plan intake --approve <token>
 
+# 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
 npx scrumrun@latest sc knowledge insight --confirm INS-001
@@ -171,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
 
@@ -181,6 +198,7 @@ The command manifest in `lib/commands/manifest.js` generates help and compatibil
 | [`SPEC.md`](./SPEC.md) | Normative 2.0 state machines, invariants, and conformance rules. |
 | [`DECISIONS.md`](./DECISIONS.md) | Architectural decisions and trade-offs. |
 | `MIGRATION-1-to-2.md` | Upgrade, verification, rollback, and recovery guide. |
+| [`docs/RELEASE-SCORECARD.md`](docs/RELEASE-SCORECARD.md) | Evidence-backed local readiness scores and residual release risks. |
 
 ScrumRun remains client-independent: any agent that reads Markdown can follow `CORE.md`; Codex, Claude Code, and OpenCode integrations are accelerators.
 

package/SPEC.md

@@ -1,6 +1,6 @@
 # ScrumRun Method Specification
 
-Version: `2.0.0` · Status: release candidate
+Version: `2.0.0` · Status: stable
 
 `SPEC.md` defines normative meanings and invariants. `lib/v2/schema.js` defines the machine-enforced ids, paths, statuses, transitions, structural relations, and truth ownership metadata; `lib/commands/manifest.js` defines command grammar. `CORE.md` is the operational runtime guide. Generated `docs/SCHEMA.md` must match the executable schema byte-for-byte. A conflict is a conformance failure: semantics defer to SPEC, mechanically enforced values defer to the schema, grammar defers to the command manifest, and the conflicting representation must be corrected.
 
@@ -108,6 +108,14 @@ FEAT-003
           └── generated → INS-041
 ```
 
+### 3.3 Run event ledger
+
+A newly authored Run declares `ledger: 1` and owns exactly one append-only operational event stream under `## Events`. Event ids are stable and scoped to the Run (`RUN-044-EVT-001`, `RUN-044-EVT-002`, ...). Each JSON event records a contiguous sequence, RFC3339 timestamp, timestamp precision, actor, source and destination states, reason, and typed evidence.
+
+Native Runs begin with `created → executing`. A migration may instead create one evidenced `snapshot` as the historical baseline when the source proves a recorded status but not its full transition path. A snapshot exposes that uncertainty and never fabricates intermediate states.
+
+The ledger is the execution authority. Task retains approved scope and synchronized current status, but does not copy Run events. Conformance reconstructs the Run state from its ledger and rejects missing or duplicate ids, invalid ordering, time reversal, illegal transitions, frontmatter drift, missing evidence, and unevidenced completion.
+
 ## 4. State machines
 
 Only the following transitions are valid.
@@ -188,11 +196,13 @@ 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.
 
-Run transitions synchronously update the linked Task and append transition evidence. A paired write failure restores both files. Entering `learning` may extract structured candidates from the Run, but extraction failure never blocks Run progress.
+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
 
@@ -208,6 +218,10 @@ When guidance conflicts, apply this order:
 
 Configuration controls preferences but cannot weaken higher levels. Missing or stale context must be surfaced, never rendered as certainty.
 
+Every project Guardrail has a stable `GR-NNN` identity, lifecycle status, rule text, enforcement mode, and optional scope/source. Intake evaluates active Guardrails into structured `passed`, `blocked`, or `deferred` results. A block names the responsible Guardrail and machine-readable reason code; a deferred result is shown explicitly and must be enforced at the mutation, migration, review, or owner gate it names. Deferred checks do not become evidence of a pass.
+
+The executable Policy Engine may infer enforcement for migrated prose, but fresh v2 policy declares it explicitly. Unknown enforcement, duplicate ids, inactive-only policy, configuration that disables approval, and unsafe read-only paths fail conformance. Configuration can tune presentation and workflow preferences; it cannot retire, bypass, or weaken active Guardrails.
+
 ## 7. Semantic memory and code intelligence
 
 Memory records include subject, source, evidence, validity window, confidence where useful, review trigger, and last-verified commit. Insight types may include placement rationale, design constraint, known trade-off, failure history, usage warning, compatibility reason, business rule, performance reason, security reason, and testing note.
@@ -234,7 +248,9 @@ The agreed v1 control-context baseline is 48,000 characters. A fresh lean v2 int
 
 ## 8. Generated views and cache
 
-`state.md`, `map.md`, context packages, and `.cache/semantic-index.sqlite` are non-authoritative projections. They carry source fingerprints or are treated as stale. Deleting `.cache/` must not remove authored knowledge, and rebuilding it from unchanged sources must yield equivalent query results.
+`state.md`, `map.md`, context packages, and `.cache/semantic-index.sqlite` are non-authoritative projections. They carry source fingerprints or are treated as stale. `state.md` uses the exact canonical fingerprint bound into intake, plus a projection schema, RFC3339 generation time, and a disposable watch fingerprint. SQLite stores its source and watch fingerprints with an explicit cache schema.
+
+Freshness checks use a two-tier strategy: unchanged path/stat identity proves that no source read or reparse is needed; changed metadata triggers a complete canonical/source content fingerprint before staleness is asserted. Cache metadata may optimize verification but never supplies project truth. A cache-schema mismatch forces one disposable rebuild. Deleting `.cache/` must not remove authored knowledge, and rebuilding it from unchanged sources must yield equivalent query results.
 
 The index must never scan or store `vault.local.md`. Source scanning is bounded, skips dependencies/build output and symlinks, and uses replaceable language adapters.
 
@@ -250,6 +266,8 @@ scrumrun migrate --to 2 --rollback
 
 `npx scrumrun@latest update` performs the same read-only preflight when run inside a v1 project and leaves project data untouched. `update --migrate` is an explicit request to apply the verified plan; it is not implicit migration.
 
+Inside an early v2 project, the same commands preflight and explicitly upgrade legacy Run prose to ledger schema 1. Deterministic transition chains are recovered; incomplete history becomes an evidenced snapshot. Apply keeps byte-exact ignored backups, verifies hashes, is idempotent, and supports rollback that refuses to erase later Run changes.
+
 The migrator must:
 
 - hash every source file and block;
@@ -271,7 +289,7 @@ Legacy sprint entries become Tasks. History entries become Runs only with an evi
 - **I-02** Approval creates a linked Task/Run pair atomically or creates nothing.
 - **I-03** Task is atomic work; Sprint only groups Tasks with real batch/timebox evidence.
 - **I-04** Every retry creates a new Run and preserves earlier attempts.
-- **I-05** Only declared state transitions are accepted and paired transitions are recoverable.
+- **I-05** Only declared, ordered, evidenced state transitions are accepted; Run event ids are unique and paired transitions are recoverable.
 - **I-06** `guardrails.md` is canonical project policy and configuration cannot weaken it.
 - **I-07** Markdown is canonical; SQLite and generated views are disposable projections.
 - **I-08** AI-created facts/insights remain candidates until explicit human confirmation.
@@ -284,9 +302,10 @@ Legacy sprint entries become Tasks. History entries become Runs only with an evi
 - **I-15** Migration is explicit; dry-run and ordinary update perform no project writes.
 - **I-16** Migration preserves hashed source coverage, backup, mapping, idempotency, and safe rollback.
 - **I-17** Migration warnings preserve ambiguity; they never invent Sprints, Runs, approval, or truth.
-- **I-18** Partial writes, conflicting overwrites, unsafe paths, and symlink traversal fail without corrupting canonical state.
+- **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
 
@@ -304,12 +323,13 @@ 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;
-5. proves cache deletion/rebuild equivalence and inactive-memory filtering;
-6. bounds context/retrieval and records benchmark budgets;
-7. declares method `2.0.0` and requires Node.js `>=22.13.0` for the native SQLite index.
+5. reconstructs every native Run status from a valid, evidenced ledger and detects tampering;
+6. proves cache deletion/rebuild equivalence and inactive-memory filtering;
+7. bounds context/retrieval and records benchmark budgets;
+8. declares method `2.0.0` and requires Node.js `>=22.13.0` for the native SQLite index.
 
 Method changes follow semantic versioning. Breaking entity, path, invariant, or state changes require a major version and a migration guide.