scrumrun 2.1.0 → 2.1.1

package/lib/runtime/workspace-state.js

@@ -0,0 +1,146 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { execFileSync } = require("node:child_process");
+const { assertNoSymlinkPath, sha256 } = require("../v2/artifacts");
+const { secretFingerprints } = require("../security/secrets");
+
+const SKIP_DIRECTORIES = new Set([".git", ".scrumrun", "node_modules"]);
+
+function posix(value) {
+  return value.split(path.sep).join("/");
+}
+
+function stable(value) {
+  if (Array.isArray(value)) return `[${value.map(stable).join(",")}]`;
+  if (value && typeof value === "object") return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stable(value[key])}`).join(",")}}`;
+  return JSON.stringify(value);
+}
+
+function normalizedRelative(projectRoot, value) {
+  const root = path.resolve(projectRoot);
+  const text = String(value || "").trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/$/, "");
+  if (!text || text === "." || path.posix.isAbsolute(text) || text.split("/").includes("..")) throw new Error(`Unsafe mutation path: ${value || "missing"}`);
+  if (text === ".git" || text.startsWith(".git/") || text === ".scrumrun" || text.startsWith(".scrumrun/")) {
+    throw new Error(`Mutation Gateway cannot authorize control path: ${text}`);
+  }
+  const target = path.resolve(root, text);
+  if (!target.startsWith(`${root}${path.sep}`)) throw new Error(`Mutation path escapes project: ${text}`);
+  assertNoSymlinkPath(root, target);
+  return posix(path.relative(root, target));
+}
+
+function fileValue(projectRoot, relative) {
+  const target = path.join(projectRoot, relative);
+  let stat;
+  try {
+    stat = fs.lstatSync(target);
+  } catch (error) {
+    if (error.code === "ENOENT") return { path: relative, sha256: null, kind: "missing", mode: null, scan: "not-applicable", secrets: [] };
+    throw error;
+  }
+  if (stat.isSymbolicLink()) {
+    const link = fs.readlinkSync(target);
+    return { path: relative, sha256: sha256(`symlink\0${link}`), kind: "symlink", mode: stat.mode & 0o777, scan: "not-applicable", secrets: [] };
+  }
+  if (!stat.isFile()) return { path: relative, sha256: sha256(`non-file\0${stat.mode}`), kind: "other", mode: stat.mode & 0o777, scan: "not-applicable", secrets: [] };
+  const content = fs.readFileSync(target);
+  const scan = content.length > 10 * 1024 * 1024 ? "too-large" : content.includes(0) ? "binary" : "text";
+  const secrets = scan === "text" ? secretFingerprints(content.toString("utf8")) : [];
+  return { path: relative, sha256: sha256(content), kind: "file", mode: stat.mode & 0o777, scan, secrets };
+}
+
+function gitOutput(projectRoot, args) {
+  return execFileSync("git", args, { cwd: projectRoot, encoding: "buffer", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 64 * 1024 * 1024 });
+}
+
+function gitState(projectRoot) {
+  let top;
+  try {
+    top = gitOutput(projectRoot, ["rev-parse", "--show-toplevel"]).toString("utf8").trim();
+  } catch {
+    return null;
+  }
+  if (path.resolve(top) !== path.resolve(projectRoot)) return null;
+  const head = gitOutput(projectRoot, ["rev-parse", "--verify", "HEAD"]).toString("utf8").trim();
+  const flagged = gitOutput(projectRoot, ["ls-files", "-v", "-z", "--", "."]).toString("utf8").split("\0").filter(Boolean)
+    .filter((entry) => /^[a-zS] /.test(entry));
+  if (flagged.length) throw new Error(`Git workspace contains hidden index flags (assume-unchanged or skip-worktree): ${flagged.slice(0, 10).map((entry) => entry.slice(2)).join(", ")}.`);
+  const tracked = gitOutput(projectRoot, ["diff", "--name-only", "-z", "--no-renames", "HEAD", "--", "."]);
+  const untracked = gitOutput(projectRoot, ["ls-files", "--others", "--exclude-standard", "-z", "--", "."]);
+  const ignored = gitOutput(projectRoot, ["ls-files", "--others", "--ignored", "--exclude-standard", "-z", "--", "."]);
+  const paths = new Set(Buffer.concat([tracked, untracked, ignored]).toString("utf8").split("\0").filter(Boolean)
+    .map((entry) => entry.replace(/\\/g, "/"))
+    .filter((entry) => {
+      const segments = entry.split("/");
+      return entry !== ".scrumrun" && !entry.startsWith(".scrumrun/") && !segments.includes("node_modules") && !segments.includes(".git");
+    }));
+  if (paths.size > 20000) throw new Error("Git workspace exceeds the 20,000-file Mutation Gateway limit after ignored-file coverage.");
+  const files = [...paths].sort().map((relative) => fileValue(projectRoot, relative));
+  return { schema: 1, mode: "git", head, files };
+}
+
+function fileState(projectRoot) {
+  const files = [];
+  function visit(directory, relative = "") {
+    const entries = fs.readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      if (entry.isDirectory() && SKIP_DIRECTORIES.has(entry.name)) continue;
+      const next = relative ? `${relative}/${entry.name}` : entry.name;
+      const target = path.join(directory, entry.name);
+      if (entry.isDirectory()) visit(target, next);
+      else files.push(fileValue(projectRoot, next));
+      if (files.length > 20000) throw new Error("Non-git workspace exceeds the 20,000-file Mutation Gateway limit.");
+    }
+  }
+  visit(projectRoot);
+  return { schema: 1, mode: "files", head: null, files };
+}
+
+function workspaceState(projectRoot) {
+  const root = path.resolve(projectRoot);
+  const state = gitState(root) || fileState(root);
+  const canonical = {
+    schema: state.schema,
+    mode: state.mode,
+    head: state.head,
+    files: state.files.map(({ path: file, sha256: hash, kind, mode, scan }) => ({ path: file, sha256: hash, kind, mode, scan }))
+  };
+  return { ...state, fingerprint: sha256(stable(canonical)) };
+}
+
+function changesBetween(before, after) {
+  if (!before || !after || before.mode !== after.mode || before.head !== after.head) throw new Error("Workspace baseline mode or Git HEAD changed during the Run.");
+  const left = new Map(before.files.map((item) => [item.path, item]));
+  const right = new Map(after.files.map((item) => [item.path, item]));
+  return [...new Set([...left.keys(), ...right.keys()])].sort().flatMap((file) => {
+    const previous = left.get(file) || { sha256: null, kind: "clean", mode: null, scan: "not-applicable", secrets: [] };
+    const next = right.get(file) || { sha256: null, kind: "clean", mode: null, scan: "not-applicable", secrets: [] };
+    if (previous.sha256 === next.sha256 && previous.kind === next.kind && previous.mode === next.mode) return [];
+    return [{
+      path: file,
+      before_sha256: previous.sha256,
+      after_sha256: next.sha256,
+      before_kind: previous.kind,
+      after_kind: next.kind,
+      before_mode: previous.mode,
+      after_mode: next.mode,
+      before_scan: previous.scan,
+      after_scan: next.scan,
+      new_secret_fingerprints: (next.secrets || []).filter((value) => !(previous.secrets || []).includes(value))
+    }];
+  });
+}
+
+function pathAuthorized(relative, allowed) {
+  return allowed.some((entry) => relative === entry || relative.startsWith(`${entry}/`));
+}
+
+module.exports = {
+  changesBetween,
+  normalizedRelative,
+  pathAuthorized,
+  stable,
+  workspaceState
+};

package/lib/security/secrets.js

@@ -1,5 +1,7 @@
 "use strict";
 
+const crypto = require("node:crypto");
+
 const SECRET_PATTERNS = Object.freeze([
   /\bsk-[A-Za-z0-9_-]{16,}\b/,
   /\bAKIA[0-9A-Z]{16}\b/,
@@ -20,4 +22,16 @@ function assertNoSecret(values, message = "Secret-like content is forbidden outs
   if (list.some(containsSecret)) throw new Error(message);
 }
 
-module.exports = { SECRET_PATTERNS, assertNoSecret, containsSecret };
+function secretFingerprints(value) {
+  const text = String(value || "");
+  const found = new Set();
+  for (const pattern of SECRET_PATTERNS) {
+    const matcher = new RegExp(pattern.source, `${pattern.flags.replace(/g/g, "")}g`);
+    for (const match of text.matchAll(matcher)) {
+      found.add(crypto.createHash("sha256").update(match[0]).digest("hex"));
+    }
+  }
+  return [...found].sort();
+}
+
+module.exports = { SECRET_PATTERNS, assertNoSecret, containsSecret, secretFingerprints };

package/lib/v2/artifacts.js

@@ -114,6 +114,9 @@ function validateArtifact(record, expectedKind = null) {
     if (field === "ledger" && record[field] !== undefined && record[field] !== 1) {
       errors.push(`${record.kind}.${field} must be 1`);
     }
+    if (["guardrails", "workspace"].includes(field) && record[field] !== undefined && record[field] !== 1) {
+      errors.push(`${record.kind}.${field} must be 1`);
+    }
   }
   return errors;
 }

package/lib/v2/conformance.js

@@ -12,6 +12,7 @@ const { resolveEvidence } = require("../memory/service");
 const { containsSecret } = require("../security/secrets");
 const { pendingTransactionStatus } = require("./transaction");
 const { configWeakeningAttempts, validateGuardrailDocument } = require("../runtime/policy-engine");
+const { auditActiveWorkspace } = require("../runtime/mutation-gateway");
 
 const INVARIANTS = Object.freeze([
   { id: "I-01", summary: "pre-approval work is read-only", tests: ["intake builds bounded context without writing"] },
@@ -33,7 +34,8 @@ const INVARIANTS = Object.freeze([
   { id: "I-17", summary: "ambiguous migration is preserved and warned", tests: ["partial v1 layout is preserved"] },
   { id: "I-18", summary: "unsafe and partial writes fail safely", tests: ["canonical writes reject traversal and symlink paths", "repository refuses conflicting overwrite", "interrupted kernel transaction is recovered"] },
   { id: "I-19", summary: "code intelligence is derived and fingerprinted", tests: ["language adapters are replaceable", "moves remap by fingerprint"] },
-  { id: "I-20", summary: "learning candidates never block execution", tests: ["post-validation extraction creates candidate insights"] }
+  { id: "I-20", summary: "learning candidates never block execution", tests: ["post-validation extraction creates candidate insights"] },
+  { id: "I-21", summary: "material mutations are scoped, policy-bound, and fail closed", tests: ["Mutation Gateway rejects bypass and out-of-scope writes", "Run completion rejects unresolved Guardrail obligations"] }
 ]);
 
 function finding(severity, code, message, file = null) {
@@ -66,6 +68,14 @@ function auditProject(projectRoot) {
   if (!guardrailValidation.records.length) findings.push(finding("high", "GUARDRAILS_EMPTY", "No stable-id Guardrail is defined."));
   if (!guardrailValidation.records.some((record) => record.status === "active")) findings.push(finding("high", "GUARDRAILS_INACTIVE", "No active stable-id Guardrail is defined."));
   for (const error of guardrailValidation.errors) findings.push(finding("high", "GUARDRAIL_INVALID", error, guardrailsFile));
+  const strictGuardrails = methodMarker && methodMarker.schemas && methodMarker.schemas.guardrails === 1;
+  if (strictGuardrails) {
+    for (const record of guardrailValidation.records) {
+      for (const field of ["status", "enforcement", "scope", "rule"]) {
+        if (!record.explicit[field]) findings.push(finding("high", "GUARDRAIL_FIELD_INFERRED", `${record.id} must explicitly declare ${field}.`, guardrailsFile));
+      }
+    }
+  }
   const configFile = path.join(scrumDir, "config.md");
   const config = fs.existsSync(configFile) && fs.lstatSync(configFile).isFile() ? fs.readFileSync(configFile, "utf8") : "";
   for (const error of configWeakeningAttempts(config)) findings.push(finding("high", "CONFIG_WEAKENS_POLICY", error, configFile));
@@ -102,6 +112,15 @@ function auditProject(projectRoot) {
       const declared = methodMarker && methodMarker.schemas && methodMarker.schemas.run_ledger === RUN_LEDGER_VERSION;
       findings.push(finding(declared ? "high" : "warning", "RUN_LEDGER_LEGACY", `${run.record.id} requires the Run ledger ${RUN_LEDGER_VERSION} migration.`, run.file));
     }
+    const secureRuns = methodMarker && methodMarker.schemas && methodMarker.schemas.run_obligations === 1 && methodMarker.schemas.mutation_gateway === 1;
+    const active = run.record && !["completed", "failed", "blocked"].includes(run.record.status);
+    if (secureRuns && active && (run.record.guardrails !== 1 || run.record.workspace !== 1)) {
+      findings.push(finding("high", "RUN_SECURITY_SCHEMA", `${run.record.id} must be retried or migrated to Guardrail/workspace schema 1.`, run.file));
+    }
+    if (run.record && run.record.workspace === 1) {
+      const bypass = auditActiveWorkspace(projectRoot, run);
+      if (bypass) findings.push(finding("critical", "MUTATION_BYPASS", `${run.record.id}: ${bypass}`, run.file));
+    }
   }
   const byId = new Map(Object.values(records).flat().filter((artifact) => artifact.record).map((artifact) => [artifact.record.id, artifact]));
   for (const task of records.task || []) {

package/lib/v2/migration.js

@@ -16,6 +16,7 @@ const {
   sha256,
   validateArtifact
 } = require("./artifacts");
+const { inferEnforcement, normalizeGuardrailDocument } = require("../runtime/policy-engine");
 const { RUN_LEDGER_VERSION } = require("./schema");
 const { migrateLegacyRun } = require("../runtime/run-ledger");
 
@@ -817,7 +818,7 @@ function migrationPlan(projectRoot) {
     const golden = readText(scrumDir, "golden-rules.md");
     const current = readText(scrumDir, "guardrails.md");
     if (/^# ScrumRun Project Guardrails\b/m.test(current) && /^#{2,6} GR-\d{3,}\b/m.test(current)) {
-      const canonical = current.replace(/^#{3,6}(?= GR-\d{3,}\b)/gm, "##");
+      const canonical = normalizeGuardrailDocument(current.replace(/^#{3,6}(?= GR-\d{3,}\b)/gm, "##"));
       if (canonical !== current) {
         generated.set("guardrails.md", canonical.endsWith("\n") ? canonical : `${canonical}\n`);
         const mapping = mappings.find((item) => item.source === "guardrails.md" && !item.anchor);
@@ -848,6 +849,9 @@ function migrationPlan(projectRoot) {
         `## GR-${String(index + 1).padStart(3, "0")} - ${rule}`,
         "",
         "Status: active",
+        `Enforcement: ${inferEnforcement(rule, rule)}`,
+        "Scope: all",
+        `Rule: ${rule}`,
         `Source: \`${source}\``,
         ""
       ]),
@@ -925,7 +929,7 @@ function migrationPlan(projectRoot) {
   generated.set("method.json", `${JSON.stringify({
     method: METHOD_VERSION,
     layout: "v2",
-    schemas: { run_ledger: RUN_LEDGER_VERSION },
+    schemas: { run_ledger: RUN_LEDGER_VERSION, guardrails: 1, run_obligations: 1, mutation_gateway: 1 },
     migrated_from: sourceLayout,
     migration: MIGRATION_NAME
   }, null, 2)}\n`);

package/lib/v2/run-ledger-migration.js

@@ -15,6 +15,7 @@ const {
 } = require("./artifacts");
 const { RUN_LEDGER_VERSION } = require("./schema");
 const { migrateLegacyRun, validateRunLedger } = require("../runtime/run-ledger");
+const { normalizeGuardrailDocument, validateGuardrailDocument } = require("../runtime/policy-engine");
 
 const MIGRATION_NAME = "run-ledger-v1";
 const MIGRATION_DIR = path.join(".migration", MIGRATION_NAME);
@@ -49,6 +50,27 @@ function planRunLedgerMigration(projectRoot) {
   const warnings = [];
   const errors = [];
 
+  const guardrailsFile = assertNoSymlinkPath(scrumDir, path.join(scrumDir, "guardrails.md"));
+  if (fs.existsSync(guardrailsFile) && fs.lstatSync(guardrailsFile).isFile()) {
+    const before = fs.readFileSync(guardrailsFile, "utf8");
+    const after = normalizeGuardrailDocument(before);
+    const validation = validateGuardrailDocument(after);
+    if (validation.errors.length) errors.push(`guardrails.md: ${validation.errors.join("; ")}`);
+    else if (before !== after) {
+      changes.push({
+        relative: "guardrails.md",
+        before,
+        after,
+        beforeSha256: sha256(before),
+        afterSha256: sha256(after),
+        mode: "guardrail-schema"
+      });
+      warnings.push("guardrails.md: inferred legacy policy fields were made explicit without deleting source prose.");
+    }
+  } else {
+    errors.push("guardrails.md is missing or unsafe.");
+  }
+
   for (const artifact of repository.list("run")) {
     if (!artifact.record || artifact.errors.length) {
       errors.push(`${path.relative(scrumDir, artifact.file)}: ${artifact.errors.join("; ")}`);
@@ -79,7 +101,13 @@ function planRunLedgerMigration(projectRoot) {
 
   const markerValue = {
     ...marker.value,
-    schemas: { ...(marker.value.schemas || {}), run_ledger: RUN_LEDGER_VERSION }
+    schemas: {
+      ...(marker.value.schemas || {}),
+      run_ledger: RUN_LEDGER_VERSION,
+      guardrails: 1,
+      run_obligations: 1,
+      mutation_gateway: 1
+    }
   };
   const markerAfter = `${JSON.stringify(markerValue, null, 2)}\n`;
   if (marker.content !== markerAfter) {
@@ -112,7 +140,7 @@ function reportRunLedgerMigration(plan, status = plan.status) {
     : "- No changes required.";
   const warnings = plan.warnings.length ? plan.warnings.map((warning) => `- ${warning}`).join("\n") : "- None.";
   const errors = plan.errors.length ? plan.errors.map((error) => `- ${error}`).join("\n") : "- None.";
-  return `# ScrumRun Run Ledger Migration\n\nStatus: ${status}\nSchema: ${RUN_LEDGER_VERSION}\nSource fingerprint: \`${plan.fingerprint}\`\nChanged files: ${plan.changes.length}\n\n## Mappings\n\n${mappings}\n\n## Warnings\n\n${warnings}\n\n## Blockers\n\n${errors}\n`;
+  return `# ScrumRun Kernel Schema Migration\n\nStatus: ${status}\nRun ledger schema: ${RUN_LEDGER_VERSION}\nGuardrail schema: 1\nMutation Gateway schema: 1\nSource fingerprint: \`${plan.fingerprint}\`\nChanged files: ${plan.changes.length}\n\n## Mappings\n\n${mappings}\n\n## Warnings\n\n${warnings}\n\n## Blockers\n\n${errors}\n`;
 }
 
 function manifestFile(scrumDir) {

package/lib/v2/schema.js

@@ -9,7 +9,7 @@ function deepFreeze(value) {
 const METHOD_VERSION = "2.0.0";
 const RUN_LEDGER_VERSION = 1;
 
-const RUN_EVENT_TYPES = deepFreeze(["transition", "snapshot"]);
+const RUN_EVENT_TYPES = deepFreeze(["transition", "snapshot", "guardrail", "mutation"]);
 const RUN_EVIDENCE_KINDS = deepFreeze([
   "approval",
   "command",
@@ -21,9 +21,13 @@ const RUN_EVIDENCE_KINDS = deepFreeze([
   "risk",
   "note",
   "migration",
-  "legacy"
+  "legacy",
+  "guardrail",
+  "mutation"
 ]);
 
+const GUARDRAIL_RESULTS = deepFreeze(["pending", "passed", "blocked"]);
+
 const ARTIFACT_TYPES = deepFreeze({
   feature: {
     prefix: "FEAT",
@@ -109,7 +113,9 @@ const STRUCTURAL_RELATIONS = deepFreeze({
 
 const SCALAR_FIELDS = deepFreeze({
   attempt: { kinds: ["run"], required: true, type: "positive integer", meaning: "monotonic execution-attempt number within one Task" },
-  ledger: { kinds: ["run"], required: false, type: `integer ${RUN_LEDGER_VERSION}`, meaning: "canonical Run event-ledger schema; required for newly authored Runs" }
+  ledger: { kinds: ["run"], required: false, type: `integer ${RUN_LEDGER_VERSION}`, meaning: "canonical Run event-ledger schema; required for newly authored Runs" },
+  guardrails: { kinds: ["run"], required: false, type: "integer 1", meaning: "append-only Guardrail obligation schema" },
+  workspace: { kinds: ["run"], required: false, type: "integer 1", meaning: "workspace mutation-gateway schema" }
 });
 
 const TRUTH_OWNERSHIP = deepFreeze({
@@ -137,6 +143,7 @@ module.exports = {
   ARTIFACT_TRANSITIONS,
   ARTIFACT_TYPES,
   AUTHORITY,
+  GUARDRAIL_RESULTS,
   METHOD_VERSION,
   RUN_EVENT_TYPES,
   RUN_EVIDENCE_KINDS,

package/package.json

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

package/templates/project/.scrumrun/method.json

@@ -2,6 +2,9 @@
   "method": "2.0.0",
   "layout": "v2",
   "schemas": {
-    "run_ledger": 1
+    "run_ledger": 1,
+    "guardrails": 1,
+    "run_obligations": 1,
+    "mutation_gateway": 1
   }
 }

package/templates/project/AGENTS.md

@@ -20,7 +20,8 @@ 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;
 - 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.
 
-Never bypass guardrails, overwrite owner work, treat generated state/cache as truth, auto-confirm AI knowledge, auto-migrate a v1 project, or print vault values.
+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.

package/templates/project-lean/AGENTS.md

@@ -13,6 +13,8 @@ Do not scan every Task, Run, Sprint, Feature, or Memory file by default. Generat
 
 Natural-language product work begins as read-only intake. Explicit approval creates/updates a Task and creates one Run. A Sprint exists only for a real batch/timebox. Run state is `executing → validating → learning → completed|failed|blocked`; retries preserve prior Runs.
 
-`.scrumrun/guardrails.md` is canonical policy. Never bypass it, overwrite owner work, auto-confirm AI knowledge, auto-migrate v1 state, or print vault values.
+Every application/source edit requires a short-lived path-scoped Mutation Gateway permit and immediate hash recording in the active Run. Resolve all persisted Guardrail obligations before completion; policy/workspace drift fails closed.
+
+`.scrumrun/guardrails.md` is canonical policy. Never bypass it or the Mutation Gateway, overwrite owner work, auto-confirm AI knowledge, auto-migrate v1 state, or print vault values.
 
 Use `/sc <noun> <subject> <action> [args]`; if `/sc` is unavailable, follow `.scrumrun/core.md` manually.

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

@@ -80,6 +80,8 @@ Evaluate every active Guardrail into a structured `passed`, `blocked`, or `defer
 
 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.
 
+The approval token binds both canonical context and a complete workspace fingerprint. Any canonical or source change after planning invalidates it and requires a new intake.
+
 ## Approved execution
 
 Explicit approval creates/updates the Task and creates a Run. The Run follows:
@@ -93,7 +95,7 @@ During execution:
 
 1. keep the change inside the approved Task scope;
 2. preserve existing owner work and unrelated dirty files;
-3. enforce guardrails before every material mutation;
+3. 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. validate in proportion to risk;
 5. record exactly one structured `RUN-NNN-EVT-NNN` event per state transition, with RFC3339 time, actor, reason, and typed evidence;
 6. run configured reviewers;
@@ -102,6 +104,8 @@ During execution:
 
 Never overwrite a prior attempt. Never mark work complete because time/token budget ended.
 
+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.
+
 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.
 
 Linked canonical writes use the ignored durable transaction journal. An interrupted prepared mutation rolls back before the next approved mutation; a committed journal is verified and finalized. Audit remains read-only and reports pending recovery. Use `doctor --recover` only when explicitly requested, and never overwrite bytes changed after interruption.
@@ -155,7 +159,7 @@ Dry-run must not write project data. Apply requires a hashed inventory, byte-exa
 - `task`: add/list/show/run/audit/cancel/retry atomic work; use `type: fix` for fixes and `status: backlog` for parked work.
 - `sprint`: add/list/show/start/complete/block a real Task batch/timebox.
 - `feature`: add/list/show/activate/complete long-lived initiatives.
-- `run`: list/show/validate/learn/complete/resume/fail/block concrete Task attempts.
+- `run`: list/show/authorize-mutation/record-mutation/satisfy-guardrail/validate/learn/complete/resume/fail/block concrete Task attempts.
 - `intake <request>`: execute the read-only request pipeline.
 - `challenge <question>`: deep read-only analysis with evidence, risks, options, and recommendation.