scrumrun 2.7.11 → 3.0.0

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes follow Semantic Versioning.
 
 ## Unreleased
 
+## 3.0.0 - 2026-08-31
+
+### Changed
+
+- **Lightweight execution is now the default.** After approval, agents work directly in application files and the linked Task Markdown, then close the Run with one `scrumrun sc plan run --finalize RUN-NNN` checkpoint.
+- **Finalization is fail-closed.** It audits the complete workspace delta, policy fingerprint, protected paths, symlink safety, scannability, secret boundary, Run ledger, and every Guardrail before completing the Task.
+- **Guardrail proof is co-located with work.** Non-automatic rules use a compact `## Guardrail Evidence` section in the Task and are validated together at finalization; missing evidence blocks completion.
+- **No network command loop.** Generated agent instructions prohibit repeated `npx scrumrun@latest` calls during execution. `npx` remains for one-off installation, migration, and recovery.
+- **Strict mode remains available.** Path-scoped Mutation Gateway permits and individual Run transitions are retained for owners who explicitly request per-edit control.
+
 ## 2.7.7 - 2026-08-24
 
 ### Added

package/CORE.md

@@ -84,7 +84,7 @@ AGENTS.md
 
 **Before querying project state, read `.scrumrun/method.json`.** Its `paths` block is the authoritative index of every canonical location in this project. Navigate by that index; if a path is not declared there, it is not canonical truth. Directory listing and grep are fallbacks — never the first step. A ScrumRun-aware agent must never search for `goals/`, `backlog.md`, `sprint.md`, or any legacy layout: those are absent by design once migration completes and are surfaced only through `.scrumrun/.migration-backup/`.
 
-**Never write Run events by hand.** Runs are only mutated through the CLI: `sc plan run --validate | --learn | --complete | --resume | --fail | --block | --satisfy-guardrail | --authorize-mutation | --record-mutation`. Editing `runs/RUN-NNN.md` directly bypasses schema validation, produces invalid ledger events (invalid `type`, unknown evidence `kind`, missing snapshot, wrong `from`), and breaks conformance for the entire project. If the CLI does not expose the shape you need, propose a spec change through an ADR — do not invent event vocabulary. Existing hand-written Runs can be recovered with `sc plan run --normalize-legacy` (byte-exact original preserved in `.scrumrun/.migration-backup/runs/`).
+**Never write Run events by hand.** After approval, work directly in code and in the linked Task Markdown. Finish the normal session once with `scrumrun sc plan run --finalize RUN-NNN`; the CLI then audits the complete workspace delta, verifies Guardrails and evidence, and writes the validated Run event chain. Do not use `npx scrumrun@latest` during execution. The older `--validate | --learn | --complete | --satisfy-guardrail | --authorize-mutation | --record-mutation` operations remain available only for an owner-requested strict path. Existing hand-written Runs can be recovered with `sc plan run --normalize-legacy` (byte-exact original preserved in `.scrumrun/.migration-backup/runs/`).
 
 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.
 

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.7.11` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
+**Package:** `3.0.0` · **Method target:** `2.0.0` · **Runtime:** Node.js `>=22.13.0` · **License:** MIT
 
 **New here?** Read the [Quickstart](docs/QUICKSTART.md) — first Run in under 10 minutes, no `SPEC.md` reading required. Full docs map in [`docs/INDEX.md`](docs/INDEX.md).
 
@@ -48,7 +48,7 @@ npm i -g scrumrun@latest
 scrumrun update
 ```
 
-`npx scrumrun@latest <command>` also works if you prefer not to install globally, but pin the version explicitly (`@latest` or `@2.6.1`) — `npx scrumrun` alone will happily reuse a stale cached version.
+Use the installed `scrumrun` command for project work. `npx` is appropriate for one-off installation, migration, or recovery only; agents must never invoke `npx scrumrun@latest` repeatedly while executing a Task, because that adds network dependency and latency to the work loop.
 
 `install` adds the client integration; `init` creates the project tree. Initialization is local by default: `.scrumrun/` and the generated agent hint are added to `.git/info/exclude`. Use `--shared` when the team wants to commit the project memory.
 
@@ -85,7 +85,13 @@ Explicit approval atomically materializes the required plan artifacts and always
 EXECUTING → VALIDATING → LEARNING → COMPLETED | FAILED | BLOCKED
 ```
 
-Every approved Task carries an `## Acceptance Criteria` section so "done" is defined before work begins; `--complete --summary "…"` stores a `## Technical Summary` on the Run so the next agent inherits what was actually done. Failed retries remain available as separate Runs.
+Every approved Task carries an `## Acceptance Criteria` section so "done" is defined before work begins. After approval, the agent works directly in code and the Task Markdown. It adds `## Technical Summary` and, when a non-automatic rule needs proof, a compact `## Guardrail Evidence` section. One final checkpoint closes the work:
+
+```bash
+scrumrun sc plan run --finalize RUN-001
+```
+
+The checkpoint validates the complete delta, policy, protected paths, secret boundary, acceptance evidence, and every Guardrail before writing the Run ledger and synchronizing the Task. 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.
 
@@ -211,7 +217,7 @@ 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.
+Approved Runs persist every deferred result as an append-only obligation and bind the exact policy plus workspace baseline. The normal final checkpoint verifies all workspace changes at once: owner/read-only scope, symlinks, new secret-like content, policy drift, and required Guardrail evidence. Completion fails closed when any verification is missing or fails. The 15-minute path-scoped Mutation Gateway remains available for teams that explicitly choose strict per-edit control.
 
 ### Owner-controlled allowlist for descriptive files
 
@@ -243,43 +249,42 @@ Rules:
 
 ```bash
 # inspect the grammar
-npx scrumrun@latest commands
+scrumrun commands
 
 # plan without writes, then approve the emitted token
-npx scrumrun@latest sc plan intake "Fix pricing rounding" --type fix --preview "Rounding moved after tax calc"
-npx scrumrun@latest sc plan intake --approve <token>
+scrumrun sc plan intake "Fix pricing rounding" --type fix --preview "Rounding moved after tax calc"
+scrumrun sc plan intake --approve <token>
 
 # record what was done at completion, so the next agent inherits it
-npx scrumrun@latest sc plan run --complete RUN-001 --note "Done" --evidence "npm test: passed" --summary "Moved rounding after tax calc in checkout/pricing.ts"
+scrumrun sc plan run --finalize RUN-001 --summary "Moved rounding after tax calc in checkout/pricing.ts"
 
 # auto-sequencing: surface and start the next backlog Task
-npx scrumrun@latest sc plan task --next
-npx scrumrun@latest sc plan task --start TASK-009
+scrumrun sc plan task --next
+scrumrun sc plan task --start TASK-009
 
 # 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"
+scrumrun sc plan run --authorize-mutation RUN-001 --path src/pricing.ts  # strict mode only
+scrumrun 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
+scrumrun sc review artifact --run
+scrumrun sc review artifact --record --task TASK-001 --run RUN-001 --evidence "npm test: passed"
 
 # 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
-npx scrumrun@latest sc knowledge study calculateFinalPrice
+scrumrun sc knowledge insight --propose "Pricing stays in backend" --evidence src/pricing.ts
+scrumrun sc knowledge insight --confirm INS-001
+scrumrun sc knowledge study calculateFinalPrice
 
 # rebuild or inspect the derived graph
-npx scrumrun@latest sc knowledge map --build
-npx scrumrun@latest sc knowledge map --show
+scrumrun sc knowledge map --build
+scrumrun sc knowledge map --show
 
 # read a Run as a human timeline instead of raw ledger JSON
-npx scrumrun@latest sc plan run --render RUN-001
+scrumrun sc plan run --render RUN-001
 
 # aggregate every Run in the project (p50/p95 durations, retries, guardrail counts)
-npx scrumrun@latest sc plan run --stats
-npx scrumrun@latest sc plan run --stats --task TASK-001 --json
+scrumrun sc plan run --stats
+scrumrun sc plan run --stats --task TASK-001 --json
 
 # preview a canonical-transaction recovery before touching disk
 npx scrumrun@latest sc config doctor --recover --dry-run

package/SPEC.md

@@ -202,11 +202,11 @@ 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.
 
-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.
+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. In the normal session path, agents work directly and one final checkpoint verifies the complete baseline-to-final delta: policy freshness, read-only boundaries, symlink safety, scannability, newly introduced secret-like content, and evidence for every Guardrail. Missing or unverifiable evidence fails closed. Strict teams may opt into short-lived, path-scoped permits and per-edit recording; those commands add stronger intermediate control but are not required for normal execution.
 
 The agent may assert the classification explicitly (`--type fix|task|feature|docs|discovery`), overriding keyword inference with validation and a stable reason. It may attach a short technical preview (`--preview`), rendered in the terminal, bound into the approval token, and stored as `## Preview` on the approved Task. A Task declares its `## Acceptance Criteria` before execution; completion is measured against them, never against elapsed time or token budget.
 
-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. On completion, an optional `## Technical Summary` section records what was actually done, surfaced to later intake through the briefing. 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.
+Run transitions synchronously update the linked Task and append exactly one structured event to the Run ledger. The normal `--finalize` checkpoint writes the required validating, learning, and completed transitions together after its audit; strict mode may write them individually. Task status changes without receiving a duplicate narrative history. Completion requires a `## Technical Summary` and evidenced validation/learning. 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.
 
 Backlog is a queue view of Tasks with `status: backlog`, ordered oldest-first by id. Starting a backlog Task (`--next` to surface, `--start` to promote) transitions `backlog → running`, creates the Task's first Run, re-evaluates policy, and records the agent identity. Starting is itself the explicit approval required by I-01.
 

package/bin/scrumrun.js

@@ -31,7 +31,7 @@ const { ARTIFACT_TYPES, ArtifactRepository } = require(path.join(root, "lib", "v
 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 { addPlanArtifact, approveRequest, nextBacklogTask, refreshErrors, refreshState, retryTask, startBacklogTask, transitionRun } = require(path.join(root, "lib", "runtime", "orchestrator"));
+const { addPlanArtifact, approveRequest, finalizeRun, nextBacklogTask, refreshErrors, refreshState, retryTask, startBacklogTask, 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"));
@@ -1562,6 +1562,15 @@ function executeRootRoute(route) {
     return;
   }
   if (noun === "plan" && subject === "run") {
+    if (routeArgs[0] === "--finalize") {
+      const runId = routeArgs[1];
+      if (!runId) throw new Error("--finalize requires RUN-NNN.");
+      const result = finalizeRun(process.cwd(), runId, runTransitionOptions(routeArgs.slice(2)));
+      console.log(`${result.run.id}: completed; ${result.task.id}: completed. Final session audit verified ${result.changes} change(s).`);
+      if (result.resolved.length) console.log(`Guardrails verified: ${result.resolved.join(", ")}.`);
+      if (result.learning && result.learning.created.length) console.log(`Learning candidates: ${result.learning.created.join(", ")}.`);
+      return;
+    }
     if (routeArgs[0] === "--authorize-mutation") {
       const paths = optionValues(routeArgs.slice(2), "--path");
       const result = authorizeMutation(process.cwd(), routeArgs[1], paths);

package/docs/COMMANDS.md

@@ -1,4 +1,4 @@
-# ScrumRun 2.0 Command Reference
+# ScrumRun 3.0 Command Reference
 
 The canonical grammar is:
 
@@ -6,7 +6,7 @@ The canonical grammar is:
 /sc <noun> <subject> <action> [args]
 ```
 
-Use `/sc` inside a supported AI client. The equivalent CLI form is `npx scrumrun@latest sc ...`. CLI-native workflows execute immediately; reasoning-heavy routes tell the installed agent to execute the validated workflow.
+Use `/sc` inside a supported AI client. The equivalent CLI form is `scrumrun sc ...`. Use `npx scrumrun@latest` only for one-off installation or recovery, never inside an agent's normal execution loop.
 
 ## Plan
 
@@ -17,13 +17,14 @@ 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 --finalize RUN-NNN [--summary "technical recap"] [--note]
 /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, 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.
+Normal execution is Markdown-first: after approval, work in code and the linked Task, then use one `--finalize` checkpoint. It verifies every workspace change and all Guardrail evidence before writing the Run transitions. A retry requires a failed, blocked, or partial Task and creates a new Run. Mutation permits are available only for explicitly requested strict mode.
 
 ## Knowledge
 
@@ -72,4 +73,4 @@ Top-level CLI aliases (`init`, `update`, `migrate`, `doctor`, `uninstall`, `stat
 
 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.
+Run `scrumrun commands` for grammar rendered directly from the current manifest.

package/lib/commands/manifest.js

@@ -15,6 +15,7 @@ const nouns = Object.freeze({
         "--render <RUN-NNN>",
         "--stats [--task <TASK-NNN>] [--feature <FEAT-NNN>] [--sprint <SPRINT-NNN>] [--json]",
         "--normalize-legacy [--dry-run]",
+        "--finalize <RUN-NNN> [--summary \"technical recap\"] [--note]",
         "--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]",

package/lib/commands/render.js

@@ -35,7 +35,8 @@ ${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.
+- The normal path is one session checkpoint: after approval, work directly in code and the linked Task Markdown; finish once with \`sc plan run --finalize RUN-NNN\`. It verifies the complete workspace delta, policy, secrets, protected paths, and all Guardrail evidence together. Do not invoke \`npx scrumrun@latest\` during execution.
+- Strict per-path Mutation Gateway permits remain available only when the owner explicitly requests strict execution.
 - 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.

package/lib/runtime/mutation-gateway.js

@@ -419,9 +419,82 @@ function prepareCompletion(projectRoot, runArtifact, options = {}) {
   return { record, body, resolved, status: "passed" };
 }
 
+// The normal v3 path is session based: an agent works freely after approval
+// and the kernel verifies the complete workspace delta once, at completion.
+// The older permit chain remains available for strict teams, but is no longer
+// required to produce trustworthy evidence for ordinary work.
+function prepareSessionCompletion(projectRoot, runArtifact, options = {}) {
+  if (runArtifact.record.guardrails !== 1 || runArtifact.record.workspace !== 1) {
+    return { record: runArtifact.record, body: runArtifact.body, changes: [], resolved: [], status: "legacy" };
+  }
+  const policy = policyState(projectRoot);
+  assertPolicyBound(runArtifact, policy);
+  const baseline = expectedWorkspace(runArtifact);
+  if (!baseline) throw new Error(`${runArtifact.record.id} has no workspace baseline; retry the Task before finalizing.`);
+  const actual = workspaceState(projectRoot);
+  const changes = changesBetween(baseline, actual);
+  const readOnly = readOnlyPaths(policy.config).map((value) => normalizedRelative(projectRoot, value));
+  const protectedChanges = changes.filter((change) => readOnly.some((item) => change.path === item || change.path.startsWith(`${item}/`)));
+  if (protectedChanges.length) throw new Error(`READ_ONLY_PATH: final workspace check found changes in ${protectedChanges.map((item) => item.path).join(", ")}.`);
+  const unsafeKinds = changes.filter((change) => !["file", "missing", "clean"].includes(change.after_kind));
+  if (unsafeKinds.length) throw new Error(`UNSAFE_MUTATION_TYPE: final workspace check found ${unsafeKinds.map((item) => item.path).join(", ")}.`);
+  const unscannable = changes.filter((change) => change.after_kind === "file" && change.after_scan !== "text");
+  if (unscannable.length) throw new Error(`UNSCANNABLE_MUTATION: final workspace check cannot inspect ${unscannable.map((item) => item.path).join(", ")}.`);
+  const leaked = changes.filter((change) => change.new_secret_fingerprints.length);
+  if (leaked.length) throw new Error(`SECRET_BOUNDARY: final workspace check found secret-like content in ${leaked.map((item) => item.path).join(", ")}.`);
+
+  let record = runArtifact.record;
+  let body = runArtifact.body;
+  if (changes.length) {
+    const appended = appendMutationEvent(record, body, {
+      mutation_id: `MUT-${sha256(`${runArtifact.record.id}:${baseline.fingerprint}:${actual.fingerprint}`).slice(0, 16)}`,
+      paths: changes.map((change) => change.path).sort(),
+      changes: changes.map(({ new_secret_fingerprints, ...change }) => change),
+      workspace_before: baseline.fingerprint,
+      workspace_after: publicWorkspace(actual),
+      policy_fingerprint: policy.fingerprint
+    }, {
+      note: options.note || `Final session audit verified ${changes.length} workspace change(s).`,
+      actor: options.actor || "agent",
+      evidence: [{ kind: "mutation", summary: `${changes.length} changed path(s) passed the final workspace audit.` }]
+    });
+    record = appended.record;
+    body = appended.body;
+  }
+  const resolved = [];
+  const repository = new ArtifactRepository(path.join(projectRoot, ".scrumrun"));
+  const supplied = options.guardrailEvidence || {};
+  const automatic = new Set(["builtin:owner-work", "builtin:read-only-path", "builtin:secret-boundary"]);
+  for (const obligation of guardrailState(record, body).filter((item) => item.status !== "passed")) {
+    const evidence = automatic.has(obligation.enforcement)
+      ? [{ kind: "mutation", summary: "Verified by the final workspace audit." }]
+      : Array.isArray(supplied[obligation.guardrail]) ? supplied[obligation.guardrail] : [];
+    if (!evidence.length) {
+      throw new Error(`GUARDRAILS_PENDING: ${obligation.guardrail} needs final evidence in the Task's ## Guardrail Evidence section.`);
+    }
+    assertGateEvidence(projectRoot, repository, requiredEvidenceKind(obligation.enforcement), evidence, obligation.guardrail);
+    const appended = appendGuardrailEvent(record, body, obligation, "passed", {
+      note: `${obligation.guardrail} passed at the final session checkpoint.`,
+      actor: "finalize",
+      occurredAt: options.occurredAt,
+      evidence
+    });
+    record = appended.record;
+    body = appended.body;
+    resolved.push(obligation.guardrail);
+  }
+  const transactions = pendingTransactionStatus(path.join(projectRoot, ".scrumrun"));
+  if (transactions.error || transactions.pending.length) throw new Error(`TRANSACTION_GATE: ${transactions.error || "pending canonical transaction"}.`);
+  return { record, body, changes, resolved, status: "passed", policy: policy.fingerprint };
+}
+
 function auditActiveWorkspace(projectRoot, runArtifact) {
   try {
     if (!runArtifact.record || runArtifact.record.workspace !== 1 || ["completed", "failed", "blocked"].includes(runArtifact.record.status)) return null;
+    // Session Runs intentionally accumulate unrecorded workspace changes until
+    // their single final checkpoint. Those changes are audited by --finalize,
+    // not reported as a strict-mode bypass while work is still in progress.
+    if (runArtifact.record.execution === "session") return null;
     verifyWorkspaceIntegrity(projectRoot, runArtifact);
     return null;
   } catch (error) {
@@ -440,6 +513,7 @@ module.exports = {
   permitsOverlap,
   policyState,
   prepareCompletion,
+  prepareSessionCompletion,
   publicWorkspace,
   recordMutation,
   satisfyGuardrail,

package/lib/runtime/orchestrator.js

@@ -23,7 +23,7 @@ const { currentBranch } = require("./workspace-state");
 const { extractLearningCandidates } = require("../code-intel/learning");
 const { appendRunEvent, appendTechnicalSummary, createRunBody, instant } = require("./run-ledger");
 const { generateBriefing, generateErrorsReport } = require("./briefing");
-const { assertCanonicalWrite, policyState, prepareCompletion, publicWorkspace, verifyWorkspaceIntegrity, workspaceState } = require("./mutation-gateway");
+const { assertCanonicalWrite, policyState, prepareCompletion, prepareSessionCompletion, publicWorkspace, verifyWorkspaceIntegrity, workspaceState } = require("./mutation-gateway");
 const { recoverPendingTransactions, runKernelTransaction } = require("../v2/transaction");
 
 const TERMINAL = new Set(["completed", "failed", "cancelled", "resolved", "rejected", "deprecated", "invalidated", "archived", "passed"]);
@@ -164,6 +164,7 @@ function approveRequestUnlocked(projectRoot, token, { failurePoint = null, inter
     ledger: 1,
     guardrails: 1,
     workspace: 1,
+    execution: "session",
     approval_id: approvalId
   };
   const taskLinks = { feature: featureId, sprint: sprintId };
@@ -267,6 +268,94 @@ function transitionedRunContent(content, nextStatus, options = {}) {
   };
 }
 
+function sectionBody(markdown, heading) {
+  const match = new RegExp(`^## ${heading}[ \\t]*\\r?\\n\\r?\\n([\\s\\S]*?)(?=^## |(?![\\s\\S]))`, "m").exec(markdown || "");
+  return match ? match[1].trim() : null;
+}
+
+// Human-authored evidence stays beside the work in the Task, rather than
+// forcing a separate CLI invocation for every guardrail. The single final
+// checkpoint parses it deterministically and rejects malformed entries.
+//
+// - GR-005 | review | REV-001 | Scoped architecture review passed.
+// - GR-006 | migration | db/migrations/20260831.sql | Migration verified.
+// - GR-007 | note | Request authorization confirmed.
+function finalGuardrailEvidence(taskBody) {
+  const content = sectionBody(taskBody, "Guardrail Evidence");
+  if (!content) return {};
+  const result = {};
+  for (const line of content.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    const raw = line.match(/^\s*-\s*(GR-\d{3,})\s*\|\s*([a-z-]+)\s*\|\s*(.*?)\s*$/i);
+    if (!raw) throw new Error(`Invalid Guardrail Evidence entry: ${line.trim()}`);
+    const [, guardrail, kind, remainder] = raw;
+    const parts = remainder.split("|").map((part) => part.trim()).filter(Boolean);
+    if (!parts.length) throw new Error(`${guardrail} needs evidence content.`);
+    const allowed = new Set(["approval", "command", "test", "file", "review", "decision", "insight", "risk", "note", "migration", "legacy", "guardrail", "mutation"]);
+    if (!allowed.has(kind)) throw new Error(`${guardrail} has unsupported evidence kind: ${kind}.`);
+    const evidence = { kind };
+    if (parts.length > 1) evidence.ref = parts.shift();
+    evidence.summary = parts.join(" | ") || (evidence.ref ? `${kind} evidence: ${evidence.ref}` : null);
+    if (!evidence.summary) throw new Error(`${guardrail} needs an evidence summary.`);
+    if (!result[guardrail]) result[guardrail] = [];
+    result[guardrail].push(evidence);
+  }
+  return result;
+}
+
+function finalizeRunUnlocked(projectRoot, runId, { note = null, summary = null, actor = "agent", occurredAt = null } = {}) {
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  recoverPendingTransactions(scrumDir);
+  const repository = new ArtifactRepository(scrumDir);
+  const runArtifact = repository.read("run", runId);
+  if (!runArtifact || runArtifact.errors.length) throw new Error(`Run not found or invalid: ${runId}`);
+  if (runArtifact.record.status !== "executing") throw new Error(`Lightweight finalization requires an executing Run; ${runId} is ${runArtifact.record.status}.`);
+  const taskArtifact = repository.read("task", runArtifact.record.task);
+  if (!taskArtifact || taskArtifact.errors.length) throw new Error(`Task not found or invalid for ${runId}.`);
+  const technicalSummary = summary || sectionBody(taskArtifact.body, "Technical Summary");
+  if (!technicalSummary) throw new Error(`TASK_SUMMARY_REQUIRED: add ## Technical Summary to ${taskArtifact.record.id}, or pass --summary.`);
+  const effectiveActor = actor === "agent" ? (agentIdentity(scrumDir) || "agent") : actor;
+  const prepared = prepareSessionCompletion(projectRoot, runArtifact, {
+    note,
+    actor: effectiveActor,
+    occurredAt,
+    guardrailEvidence: finalGuardrailEvidence(taskArtifact.body)
+  });
+  let runContent = serializeArtifact(prepared.record, prepared.body);
+  for (const [status, evidence] of [
+    ["validating", [{ kind: "test", summary: "Final session integrity audit passed." }]],
+    ["learning", [{ kind: "insight", summary: "Learning extraction scheduled from the completed session." }]],
+    ["completed", [{ kind: "note", summary: note || "Completed through the final session checkpoint." }]]
+  ]) {
+    runContent = transitionedRunContent(runContent, status, { actor: effectiveActor, occurredAt, note, evidence }).content;
+  }
+  runContent = appendTechnicalSummary(parseArtifact(runContent).record, runContent, technicalSummary);
+  const taskPrevious = fs.readFileSync(taskArtifact.file, "utf8");
+  let taskContent = taskPrevious;
+  let taskNext = null;
+  for (const status of ["validating", "learning", "completed"]) {
+    taskNext = transitionedArtifactContent(taskContent, "task", status, new Date().toISOString().slice(0, 10));
+    taskContent = taskNext.content;
+  }
+  runKernelTransaction(scrumDir, "finalize-lightweight-session", [
+    { file: runArtifact.file, previous: fs.readFileSync(runArtifact.file, "utf8"), next: runContent },
+    { file: taskArtifact.file, previous: taskPrevious, next: taskNext.content }
+  ]);
+  refreshState(scrumDir);
+  let learning = null;
+  try {
+    learning = extractLearningCandidates(projectRoot, runId);
+  } catch (error) {
+    learning = { created: [], warnings: [`Learning extraction did not block finalization: ${error.message}`] };
+  }
+  refreshState(scrumDir);
+  return { run: parseArtifact(runContent).record, task: taskNext.record, changes: prepared.changes.length, resolved: prepared.resolved, learning };
+}
+
+function finalizeRun(projectRoot, runId, options = {}) {
+  return withArtifactLock(path.join(projectRoot, ".scrumrun"), `run-${String(runId).toLowerCase()}`, () => finalizeRunUnlocked(projectRoot, runId, options));
+}
+
 function transitionRunUnlocked(projectRoot, runId, nextStatus, { note = null, evidence = [], actor = "agent", occurredAt = null, summary = null, failurePoint = null, interruptPoint = null } = {}) {
   const scrumDir = path.join(projectRoot, ".scrumrun");
   const effectiveActor = actor === "agent" ? (agentIdentity(scrumDir) || "agent") : actor;
@@ -376,6 +465,7 @@ function retryTaskUnlocked(projectRoot, taskId, { note = "Retry explicitly appro
     ledger: 1,
     guardrails: 1,
     workspace: 1,
+    execution: "session",
     approval_id: taskArtifact.record.approval_id || null
   };
   const runBody = createRunBody(run, {
@@ -447,6 +537,7 @@ function startBacklogTaskUnlocked(projectRoot, taskId, { note = "Backlog Task st
     ledger: 1,
     guardrails: 1,
     workspace: 1,
+    execution: "session",
     approval_id: taskArtifact.record.approval_id || null
   };
   const runBody = createRunBody(run, {
@@ -598,4 +689,4 @@ function addPlanArtifact(projectRoot, kind, label, options = {}) {
   return withArtifactLock(scrumDir, "create", () => addPlanArtifactUnlocked(projectRoot, kind, label, options));
 }
 
-module.exports = { addPlanArtifact, approveRequest, nextBacklogTask, nextId, refreshErrors, refreshState, renderState, retryTask, startBacklogTask, stateFingerprint, stateIsStale, transitionRun };
+module.exports = { addPlanArtifact, approveRequest, finalizeRun, nextBacklogTask, nextId, refreshErrors, refreshState, renderState, retryTask, startBacklogTask, stateFingerprint, stateIsStale, transitionRun };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scrumrun",
-  "version": "2.7.11",
+  "version": "3.0.0",
   "description": "Evidence-driven Agile runtime and semantic project memory for AI coding agents.",
   "bin": {
     "scrumrun": "bin/scrumrun.js",

package/templates/project/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md - {{PROJECT_NAME}}
 
-## ScrumRun 2.0
+## ScrumRun 3.0
 
 This project uses ScrumRun. The method is mandatory; `/sc` is its single optional shortcut.
 
@@ -20,9 +20,11 @@ After approval:
 - Run is one execution attempt and follows `executing → validating → learning → completed|failed|blocked`;
 - a retry creates a new Run and preserves the old one;
 - record a `## Technical Summary` at completion so the next agent inherits what was done;
+- work directly in code and the linked Task Markdown after approval; do not call `npx scrumrun@latest` during execution;
+- record one `## Guardrail Evidence` line per non-automatic guardrail in the Task, then run `scrumrun sc plan run --finalize RUN-NNN` once to validate and close the Run;
 - when a Run completes and work remains queued, surface it with `sc plan task --next` and start it with `sc plan task --start` — starting is explicit approval;
 - learning proposes evidence-backed Knowledge, Decisions, or candidate Insights;
-- every application/source edit requires a path-scoped Mutation Gateway permit, immediate hash recording, and resolution of the Run's Guardrail obligations before completion.
+- the final checkpoint verifies all Guardrails, workspace changes, protected paths, and secret boundaries before completion; use the path-scoped Mutation Gateway only when the owner requests strict execution.
 
 Never bypass guardrails or edit around the Mutation Gateway, overwrite owner work, treat generated state/cache as truth, auto-confirm AI knowledge, auto-migrate a v1 project, or print vault values.
 

package/templates/shared/skills/scrumrun/SKILL.md

@@ -36,7 +36,7 @@ Normal hot path:
 5. follow the briefing's pointers to only the relevant canonical artifacts; go deeper only when the briefing lacks what you need (`## Where to look`, `sc knowledge study "<topic>"`);
 6. load `.scrumrun/core.md` when the method contract or an exceptional transition is needed.
 
-**Never write Run events by hand.** Only the CLI mutates `runs/RUN-NNN.md`: `sc plan run --validate | --learn | --complete | --resume | --fail | --block | --satisfy-guardrail | --authorize-mutation | --record-mutation`. Direct edits produce invalid ledger events (unknown `type` like `execution`/`validation`/`learning`, unknown evidence `kind` like `guardrail-check`/`build`/`task-status`, missing snapshot invariant) and break project conformance. If the CLI does not expose the shape you need, propose a spec change instead of inventing vocabulary. Recover hand-written Runs via `sc plan run --normalize-legacy` — originals are preserved byte-exact under `.scrumrun/.migration-backup/runs/`.
+**Never write Run events by hand.** Work directly in code and the linked Task Markdown after approval, then let the one final CLI checkpoint mutate `runs/RUN-NNN.md`: `scrumrun sc plan run --finalize RUN-NNN`. It creates the validated transition ledger, audits the full workspace delta, and records the Guardrail results together. Do not invoke `npx scrumrun@latest` during normal execution. The older `--validate | --learn | --complete | --satisfy-guardrail | --authorize-mutation | --record-mutation` commands remain only for owner-requested strict mode. Recover hand-written Runs via `sc plan run --normalize-legacy` — originals are preserved byte-exact under `.scrumrun/.migration-backup/runs/`.
 
 Lean mode is a read policy, not an incomplete store. Generated files and `.scrumrun/.cache/` are never authoritative.
 
@@ -101,19 +101,17 @@ During execution:
 1. keep the change inside the approved Task scope;
 2. preserve existing owner work and unrelated dirty files;
 3. define or confirm the Task's `## Acceptance Criteria` before execution and check them off as evidence;
-4. enforce guardrails before every material mutation: obtain a short-lived path-scoped Mutation Gateway permit before editing and record its verified before/after hashes immediately afterward;
+4. work normally: edit code and update the Task's `## Technical Summary` and, for non-automatic rules, `## Guardrail Evidence` as evidence becomes available;
 5. validate in proportion to risk and against the acceptance criteria;
-6. record exactly one structured `RUN-NNN-EVT-NNN` event per state transition, with RFC3339 time, actor, reason, and typed evidence;
-7. run configured reviewers;
-8. extract candidate learning only after validation;
-9. record a `## Technical Summary` at completion (`sc plan run --complete --summary "…"`) so the next agent inherits what was actually done;
-10. complete the Run, then Task, and only then the Sprint when its whole batch is done.
+6. run configured reviewers when a Guardrail requires one;
+7. finish once with `scrumrun sc plan run --finalize RUN-NNN`; it verifies every changed path, policy, secret boundary, and guardrail evidence before creating the structured Run events and completing the Task;
+8. use path-scoped Mutation Gateway commands only when the owner explicitly requests strict execution.
 
 Never overwrite a prior attempt. Never mark work complete because time/token budget ended.
 
 When a Run completes and work remains queued, the briefing's `## Next Up` names the next backlog Task. Surface it with `sc plan task --next` and start it with `sc plan task --start [TASK-NNN]` — starting is the explicit approval; the owner can always decline. Each agent declares its identity via `SCRUMRUN_AGENT` (or `Agent Identity` in `config.md`); it is recorded as the Task `assignee` and the Run event `actor`.
 
-Every deferred policy result is an append-only Run obligation. Unrecorded workspace drift, policy drift, an expired/missing permit, out-of-scope changes, unsafe symlinks, newly introduced secret-like content, or an unresolved obligation blocks validation/completion. The ignored permit cache is disposable; deleting it invalidates outstanding permits and never creates authority.
+Every deferred policy result is an append-only Run obligation. The final checkpoint fails closed on policy drift, protected-path changes, unsafe symlinks, unscannable content, newly introduced secret-like content, or missing Guardrail Evidence. In strict mode it additionally requires the permit chain. The ignored permit cache is disposable; deleting it invalidates outstanding strict-mode permits and never creates authority.
 
 Run is the sole operational-history authority. Task synchronizes current status without copying Run events. Validation, learning, completion, failure, block, and resume require a reason or structured evidence; completion also requires evidenced validation and learning. Early v2 prose Runs are migrated explicitly, with deterministic chains recovered and uncertain history represented as an evidenced snapshot.