scrumrun 2.7.11 → 3.0.1

package/lib/errors.js

@@ -31,44 +31,44 @@ const CATALOG = Object.freeze({
   "SR-E-052": { summary: "Approval token expired.", remediation: "Re-run intake to obtain a fresh token before approving." },
 
   // Runs and ledger
-  "SR-E-100": { summary: "Run not found.", remediation: "Check the RUN-NNN id with `sc plan run --list`." },
-  "SR-E-101": { summary: "Run ledger contains an invalid event.", remediation: "Inspect the reported event id; use `sc plan run --render` for a human view or restore from git history." },
+  "SR-E-100": { summary: "Run not found.", remediation: "Check the RUN-NNN id with `scrumrun plan run --list`." },
+  "SR-E-101": { summary: "Run ledger contains an invalid event.", remediation: "Inspect the reported event id; use `scrumrun plan run --render` for a human view or restore from git history." },
   "SR-E-102": { summary: "Run transition rejected: missing validation or learning evidence.", remediation: "Complete `--validate` and `--learn` with typed evidence before `--complete`." },
   "SR-E-103": { summary: "Retry rejected because the previous Run is still active.", remediation: "Complete, fail, or block the current Run before creating a retry." },
 
   // Guardrails
   "SR-E-150": { summary: "Guardrail check blocked the operation.", remediation: "Read the reported GR-NNN, satisfy or retire it explicitly; guardrails never bypass silently." },
-  "SR-E-151": { summary: "Guardrail obligation is still pending.", remediation: "Resolve each `pending guardrail` via `sc plan run --satisfy-guardrail` before completing the Run." },
+  "SR-E-151": { summary: "Guardrail obligation is still pending.", remediation: "Resolve each `pending guardrail` via `scrumrun plan run --satisfy-guardrail` before completing the Run." },
   "SR-E-152": { summary: "Guardrail declaration is malformed.", remediation: "Every active guardrail requires Status, Enforcement, Scope, and Rule fields; check .scrumrun/guardrails.md." },
 
   // Edit permits (Mutation Gateway)
-  "SR-E-200": { summary: "No edit permit for this path.", remediation: "Request one with `sc plan run --authorize-mutation RUN-NNN --path <path>` before editing canonical or source files." },
+  "SR-E-200": { summary: "No edit permit for this path.", remediation: "Request one with `scrumrun plan run --authorize-mutation RUN-NNN --path <path>` before editing canonical or source files." },
   "SR-E-201": { summary: "Edit permit expired.", remediation: "Permits last 15 minutes. Authorize a new one and record the change immediately." },
   "SR-E-202": { summary: "Edit permit path scope mismatch.", remediation: "The permit does not cover the modified path. Request a new permit that lists it." },
   "SR-E-203": { summary: "File hash changed unexpectedly since the permit was issued.", remediation: "Someone else modified the file. Re-plan the change and request a fresh permit." },
 
   // Transactions and recovery
-  "SR-E-250": { summary: "Pending kernel transaction cannot be recovered automatically.", remediation: "Run `sc config doctor --recover --dry-run` to preview; if it shows 'would overwrite owner changes', reconcile the file manually before applying." },
+  "SR-E-250": { summary: "Pending kernel transaction cannot be recovered automatically.", remediation: "Run `scrumrun config doctor --recover --dry-run` to preview; if it shows 'would overwrite owner changes', reconcile the file manually before applying." },
   "SR-E-251": { summary: "Journal fails integrity check.", remediation: "Inspect .scrumrun/.transactions/pending. Do not delete; contact support or restore from backup." },
 
   // Memory
-  "SR-E-300": { summary: "Memory candidate rejected: missing resolvable evidence.", remediation: "Attach at least one --evidence path or `sc knowledge <subject> --propose` before `--confirm`." },
+  "SR-E-300": { summary: "Memory candidate rejected: missing resolvable evidence.", remediation: "Attach at least one --evidence path or `scrumrun knowledge <subject> --propose` before `--confirm`." },
   "SR-E-301": { summary: "Attempt to write into vault via canonical channel.", remediation: "vault.local.md is local-only and never indexed. Edit the file directly." },
 
   // Semantic index / code intel
-  "SR-E-350": { summary: "Semantic index is stale.", remediation: "Rebuild with `sc knowledge map --build`. Cache is disposable; canonical memory is unaffected." },
-  "SR-E-351": { summary: "Search backend advertised in the cache does not match this runtime.", remediation: "Delete .scrumrun/.cache/semantic-index.sqlite and re-run any `sc knowledge` query to rebuild against the current runtime." },
+  "SR-E-350": { summary: "Semantic index is stale.", remediation: "Rebuild with `scrumrun knowledge map --build`. Cache is disposable; canonical memory is unaffected." },
+  "SR-E-351": { summary: "Search backend advertised in the cache does not match this runtime.", remediation: "Delete .scrumrun/.cache/semantic-index.sqlite and re-run any `scrumrun knowledge` query to rebuild against the current runtime." },
 
   // Migration
-  "SR-E-400": { summary: "Migration preflight failed.", remediation: "Run `npx scrumrun@latest update` (dry) to see blockers, resolve them, then apply with `--migrate`." },
+  "SR-E-400": { summary: "Migration preflight failed.", remediation: "Run `scrumrun update` (dry) to see blockers, resolve them, then apply with `--migrate`." },
   "SR-E-401": { summary: "Migration rollback requested but no backup was found.", remediation: "Rollback needs the ignored byte-exact backup created during --migrate. Restore from version control if the backup is gone." },
 
   // Conformance / doctor
   "SR-E-450": { summary: "Conformance check failed.", remediation: "The reported invariant identifies the exact violation; the message includes the file and expected shape." },
-  "SR-E-451": { summary: "Installed client asset is stale.", remediation: "Re-run `npx scrumrun@latest update` for the specific client. `doctor --strict` shows which files diverge." },
+  "SR-E-451": { summary: "Installed client asset is stale.", remediation: "Re-run `scrumrun update` for the specific client. `doctor --strict` shows which files diverge." },
 
   // Configuration / install
-  "SR-E-500": { summary: "ScrumRun project not initialized.", remediation: "Run `npx scrumrun@latest init` in the repository root." },
+  "SR-E-500": { summary: "ScrumRun project not initialized.", remediation: "Run `scrumrun init` in the repository root." },
   "SR-E-501": { summary: "Unsupported Node.js runtime.", remediation: "ScrumRun requires Node.js >=22.13.0 for native SQLite. Upgrade Node and retry." }
 });
 

package/lib/runtime/briefing.js

@@ -97,8 +97,8 @@ ${backlogTasks.length ? backlogTasks.join("\n") : "- No backlog Tasks."}
 - Guardrails: .scrumrun/guardrails.md
 - Tasks: .scrumrun/tasks/ (${counts.task || 0} total)
 - Runs: .scrumrun/runs/ (${counts.run || 0} total)
-- Semantic: sc knowledge study "<topic>" for deep queries
-- Full state: rebuild with sc config doctor --recover
+- Semantic: scrumrun knowledge study "<topic>" for deep queries
+- Full state: rebuild with scrumrun config doctor --recover
 `;
 
   return { content, sourceFingerprint, watchFingerprint: watch.fingerprint, sourceFiles: watch.files };

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, {
@@ -495,7 +586,7 @@ const ADD_PLAN_INITIAL_STATUS = Object.freeze({
 const TASK_TYPES = new Set(["task", "fix", "docs", "discovery"]);
 
 function planArtifactBody(kind, title, created) {
-  const source = `- ${created}: created via CLI (\`sc plan ${kind} --add\`).`;
+  const source = `- ${created}: created via CLI (\`scrumrun plan ${kind} --add\`).`;
   if (kind === "task") {
     return [
       `# ${title}`,
@@ -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/lib/v2/conformance.js

@@ -79,7 +79,7 @@ function auditProject(projectRoot) {
     if (methodMarker.method !== METHOD_VERSION) findings.push(finding("critical", "METHOD_VERSION", `method.json must declare ${METHOD_VERSION}.`, marker));
     const expectedPaths = canonicalPaths();
     if (!methodMarker.paths || typeof methodMarker.paths !== "object" || Array.isArray(methodMarker.paths)) {
-      findings.push(finding("high", "METHOD_PATHS_MISSING", `method.json must declare a canonical "paths" block so agents navigate by declaration, not by search. Run \`npx scrumrun@latest update --migrate\` to backfill.`, marker));
+      findings.push(finding("high", "METHOD_PATHS_MISSING", `method.json must declare a canonical "paths" block so agents navigate by declaration, not by search. Run \`scrumrun update --migrate\` to backfill.`, marker));
     } else {
       const drift = diffPathIndex(expectedPaths, methodMarker.paths);
       for (const entry of drift) findings.push(finding("high", "METHOD_PATHS_DRIFT", `method.json paths[${entry.label}] is ${entry.actual === undefined ? "missing" : `"${entry.actual}"`}; expected "${entry.expected}". Regenerate via \`update --migrate\`.`, marker));
@@ -152,7 +152,7 @@ function auditProject(projectRoot) {
     if (run.record && run.record.ledger === RUN_LEDGER_VERSION) {
       const ledger = validateRunLedger(run.record, run.body);
       if (ledger.errors.length) {
-        findings.push(finding("high", "RUN_WRITE_BYPASS", `${run.record.id}: ledger has ${ledger.errors.length} validation error(s); this Run was likely written without going through the CLI. Recover with \`sc plan run --normalize-legacy --dry-run\` then re-run without --dry-run.`, run.file));
+        findings.push(finding("high", "RUN_WRITE_BYPASS", `${run.record.id}: ledger has ${ledger.errors.length} validation error(s); this Run was likely written without going through the CLI. Recover with \`scrumrun plan run --normalize-legacy --dry-run\` then re-run without --dry-run.`, run.file));
         for (const error of ledger.errors) findings.push(finding("high", "RUN_LEDGER_INVALID", `${run.record.id}: ${error}`, run.file));
       }
     } else if (run.record) {
@@ -198,7 +198,17 @@ function auditProject(projectRoot) {
     const attempts = (records.run || [])
       .filter((run) => run.record && !run.errors.length && run.record.task === task.record.id)
       .sort((left, right) => right.record.attempt - left.record.attempt);
-    if (!attempts.length) continue;
+    if (!attempts.length) {
+      if (["running", "validating", "learning", "partial"].includes(task.record.status)) {
+        findings.push(finding(
+          "high",
+          "TASK_ORPHANED",
+          `${task.record.id}.status is ${task.record.status}, but no canonical Run references it. Review with \`scrumrun repair --recover-orphan-tasks\`, then apply the explicit recovery and start the Task to create its first Run.`,
+          task.file
+        ));
+      }
+      continue;
+    }
     const latest = attempts[0].record;
     const taskStatuses = {
       executing: "running",

package/package.json

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

package/templates/project/AGENTS.md

@@ -1,8 +1,8 @@
 # AGENTS.md - {{PROJECT_NAME}}
 
-## ScrumRun 2.0
+## ScrumRun 3.0
 
-This project uses ScrumRun. The method is mandatory; `/sc` is its single optional shortcut.
+This project uses ScrumRun. The method is mandatory; the direct CLI is `scrumrun <noun> <subject> <action>`. `/sc` is only an optional client shortcut.
 
 For normal work, read:
 
@@ -20,10 +20,12 @@ 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;
-- 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;
+- 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 plan run --finalize RUN-NNN` once to validate and close the Run;
+- when a Run completes and work remains queued, surface it with `scrumrun plan task --next` and start it with `scrumrun 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.
 
-If `/sc` is unavailable, follow the equivalent workflow in `.scrumrun/core.md` manually.
+Never use `npx scrumrun@latest` in the normal work loop. If the installed CLI is unavailable, stop and report that blocker rather than substituting a network command.

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

@@ -5,13 +5,13 @@ description: Use when initializing or migrating ScrumRun, handling product reque
 
 # ScrumRun 2.0
 
-ScrumRun is an evidence-driven Agile runtime for AI agents. Its canonical command is:
+ScrumRun is an evidence-driven Agile runtime for AI agents. Its canonical shell command is:
 
 ```text
-/sc <noun> <subject> <action> [args]
+scrumrun <noun> <subject> <action> [args]
 ```
 
-The five nouns are `plan`, `knowledge`, `rules`, `review`, and `config`. If the command is incomplete, show only the valid next tokens and do not guess.
+The five nouns are `plan`, `knowledge`, `rules`, `review`, and `config`. `/sc` is an optional AI-client shortcut; `scrumrun sc ...` is a compatibility alias. If the command is incomplete, show only the valid next tokens and do not guess.
 
 When a project contains `.scrumrun/`, use ScrumRun for product work even if the user did not type `/sc`. Natural-language work begins as `plan intake`.
 
@@ -33,10 +33,10 @@ Normal hot path:
 2. read `AGENTS.md`;
 3. read `.scrumrun/guardrails.md`;
 4. read `.scrumrun/state.md` — the **briefing**: active work, recent completions with their technical summaries, open decisions, active memory, backlog queue, and pointers;
-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>"`);
+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`, `scrumrun 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 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 `scrumrun` 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 `scrumrun 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.
 
@@ -81,7 +81,7 @@ At intake:
 
 Evaluate every active Guardrail into a structured `passed`, `blocked`, or `deferred` result. Report blocked results with the exact `GR-NNN` id and reason code. Keep deferred results visible and enforce them at the mutation, migration, review, or owner gate they identify; never describe a deferred check as passed.
 
-Assert the classification explicitly when the keyword inference is wrong: `sc plan intake "…" --type fix|task|feature|docs|discovery`. Attach a short technical explanation before approval with `--preview "…"` (rendered in the terminal, bound into the token, stored as `## Preview` on the Task).
+Assert the classification explicitly when the keyword inference is wrong: `scrumrun plan intake "…" --type fix|task|feature|docs|discovery`. Attach a short technical explanation before approval with `--preview "…"` (rendered in the terminal, bound into the token, stored as `## Preview` on the Task).
 
 Do not create canonical artifacts, change status, edit application code, or treat ambiguous acknowledgement as approval. Temporary context may exist only in ignored disposable cache.
 
@@ -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 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`.
+When a Run completes and work remains queued, the briefing's `## Next Up` names the next backlog Task. Surface it with `scrumrun plan task --next` and start it with `scrumrun 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.
 
@@ -157,13 +155,13 @@ scrumrun migrate --to 2 --apply
 scrumrun migrate --to 2 --rollback
 ```
 
-Inside a v1 project, `npx scrumrun@latest update` runs a read-only preflight. `update --migrate` explicitly approves application of that verified plan and keeps rollback available.
+Inside a v1 project, `scrumrun update` runs a read-only preflight. `update --migrate` explicitly approves application of that verified plan and keeps rollback available.
 
 Dry-run must not write project data. Apply requires a hashed inventory, byte-exact local backup, staged validation, atomic switch, mapping report, and idempotent replay. Incomplete hybrid trees reuse existing evidenced v2 relations rather than duplicating them; early v2 prose Runs upgrade to ledger schema 1 only through the same explicit apply gate. Legacy-only aggregates leave the active tree but remain byte-exact in the ignored backup. Ambiguous records are preserved as warnings or evidenced snapshots, never guessed. Vault content remains local and is never rendered. Rollback must refuse if it would erase post-migration changes.
 
 ## Command grammar
 
-### `/sc plan`
+### `scrumrun plan`
 
 - `task`: add/list/show/run/audit/cancel/retry atomic work; use `type: fix` for fixes and `status: backlog` for parked work. `--next` surfaces the oldest backlog Task; `--start [TASK-NNN]` promotes it and creates its first Run.
 - `sprint`: add/list/show/start/complete/block a real Task batch/timebox.
@@ -172,7 +170,7 @@ Dry-run must not write project data. Apply requires a hashed inventory, byte-exa
 - `intake <request>`: execute the read-only request pipeline; accepts `--type fix|task|feature|docs|discovery` and `--preview "…"`.
 - `challenge <question>`: deep read-only analysis with evidence, risks, options, and recommendation.
 
-### `/sc knowledge`
+### `scrumrun knowledge`
 
 - `fact`: add/list/show/approve/reject/deprecate/invalidate `K-NNN` records.
 - `decision`: add/list/show/resolve/deprecate/invalidate `DEC-NNN` records.
@@ -183,12 +181,12 @@ Dry-run must not write project data. Apply requires a hashed inventory, byte-exa
 - `study <focus>`: deep read-only discovery with precise evidence.
 - `vault`: add/list/show/remove/path for explicitly requested local development values; list redacts values.
 
-### `/sc rules`
+### `scrumrun rules`
 
 - `guardrail`: add/list/show/retire project rules. Adding/retiring requires explicit approval.
 - `reviewer`: add/list/show/run configured review roles.
 
-### `/sc review`
+### `scrumrun review`
 
 - `code --run`: review code changes by severity with file/line evidence.
 - `artifact --run`: validate method artifacts and relations.
@@ -197,7 +195,7 @@ Dry-run must not write project data. Apply requires a hashed inventory, byte-exa
 
 Review is read-only unless the user separately authorizes fixes.
 
-### `/sc config`
+### `scrumrun config`
 
 - `project`: show/set language, interaction, approval, and quick-task preferences.
 - `init`: initialize ScrumRun without overwriting existing state silently.
@@ -209,16 +207,16 @@ Review is read-only unless the user separately authorizes fixes.
 
 ## Compatibility
 
-Upgrade installs may provide thin v1 adapters for one release cycle. An adapter must execute the mapped `/sc` route in the same turn and emit one concise deprecation note; it must not merely ask the user to invoke another command.
+Upgrade installs may provide thin v1 adapters for one release cycle. An adapter must execute the mapped direct route in the same turn and emit one concise deprecation note; it must not merely ask the user to invoke another command.
 
 Important mappings:
 
-- `/sc-sprint` → `/sc plan sprint`
-- `/sc-fix` → `/sc plan task` with `type: fix`
-- `/sc-backlog` → `/sc plan task` with `status: backlog`
-- `/sc-decisions` → `/sc knowledge decision`
-- `/sc-know` → `/sc knowledge fact`
-- `/sc-golden` → `/sc rules guardrail`
-- `/sc-agent` → `/sc rules reviewer`
+- `/sc-sprint` → `scrumrun plan sprint`
+- `/sc-fix` → `scrumrun plan task` with `type: fix`
+- `/sc-backlog` → `scrumrun plan task` with `status: backlog`
+- `/sc-decisions` → `scrumrun knowledge decision`
+- `/sc-know` → `scrumrun knowledge fact`
+- `/sc-golden` → `scrumrun rules guardrail`
+- `/sc-agent` → `scrumrun rules reviewer`
 
-Always generate and recommend the canonical `/sc` grammar.
+Always generate and recommend the canonical direct CLI grammar.