scrumrun 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes follow Semantic Versioning.
 
+## Unreleased
+
+## 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,6 +148,8 @@ 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.
 
+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.
 
 ## Execution lifecycle
@@ -165,7 +169,9 @@ 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;
 - learning proposes memory candidates after validation and never auto-confirms AI inference;
@@ -174,6 +180,8 @@ Rules:
 
 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 +228,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;
@@ -283,6 +292,7 @@ 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.
 - 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 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:
+
+```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.
+
 ## 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.0` · **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. 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,7 @@ 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.
 
 ## Useful commands
 
@@ -161,6 +167,9 @@ 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
+npx scrumrun@latest sc review artifact --run
+
 # 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
@@ -181,6 +190,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.
@@ -192,7 +200,7 @@ Everything through `AWAITING_APPROVAL` is read-only. It may exist in process mem
 
 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.
+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 +216,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 +246,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 +264,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 +287,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,7 +300,7 @@ 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.
 
@@ -308,8 +324,9 @@ An implementation may claim ScrumRun method 2.0.0 only when it:
 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.

package/bin/scrumrun.js

@@ -9,14 +9,21 @@ 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 { 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 +46,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 +274,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 +1194,48 @@ 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 printMemoryArtifact(artifact) {
   if (!artifact) return false;
   console.log(readIfExists(artifact.file));
@@ -1233,9 +1302,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 +1340,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}`);
@@ -1311,7 +1382,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(", ")}.`);
@@ -1335,7 +1406,7 @@ function executeRootRoute(route) {
   if (noun === "config" && subject === "migrate") return runMigration(routeArgs);
   if (noun === "config" && subject === "doctor") {
     const target = ["all", "codex", "opencode", "claude"].includes(routeArgs[0]) ? routeArgs[0] : "all";
-    return doctor(target);
+    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 +2168,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 +2223,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 +2353,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,7 +16,7 @@ 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 challenge <question>
 ```
 
@@ -59,11 +59,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.0 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.
+
+## 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.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. |
+
+Minimum local score: **9.6/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.
+- 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.0` 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`.
+- 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.