scrumrun 2.0.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

@@ -111,6 +111,12 @@ function validateArtifact(record, expectedKind = null) {
     if (field === "attempt" && (!Number.isInteger(record[field]) || record[field] < 1)) {
       errors.push(`${record.kind}.${field} must be a positive integer`);
     }
+    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;
 }
@@ -162,10 +168,27 @@ function assertNoSymlinkPath(root, target) {
 function atomicWrite(file, content) {
   fs.mkdirSync(path.dirname(file), { recursive: true });
   const temp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.tmp`);
+  let descriptor = null;
   try {
-    fs.writeFileSync(temp, content);
+    const mode = fs.existsSync(file) ? fs.lstatSync(file).mode & 0o777 : 0o666;
+    descriptor = fs.openSync(temp, "wx", mode);
+    fs.writeFileSync(descriptor, content);
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = null;
     fs.renameSync(temp, file);
+    try {
+      const directory = fs.openSync(path.dirname(file), "r");
+      try {
+        fs.fsyncSync(directory);
+      } finally {
+        fs.closeSync(directory);
+      }
+    } catch (error) {
+      if (!["EINVAL", "ENOTSUP", "EBADF"].includes(error.code)) throw error;
+    }
   } catch (error) {
+    if (descriptor !== null) fs.closeSync(descriptor);
     if (fs.existsSync(temp)) fs.rmSync(temp, { force: true });
     throw error;
   }

package/lib/v2/conformance.js

@@ -3,34 +3,39 @@
 const fs = require("node:fs");
 const path = require("node:path");
 const { ArtifactRepository } = require("./artifacts");
-const { ARTIFACT_TYPES, METHOD_VERSION } = require("./schema");
+const { ARTIFACT_TYPES, METHOD_VERSION, RUN_LEDGER_VERSION } = require("./schema");
 const { stateIsStale } = require("../runtime/orchestrator");
-const { indexStatus } = require("../memory/index");
+const { validateRunLedger } = require("../runtime/run-ledger");
+const { indexStatus, mapStatus } = require("../memory/index");
 const { extractEvidence } = require("../memory/markdown");
 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"] },
   { id: "I-02", summary: "approval creates Task and Run atomically", tests: ["explicit approval creates exactly one linked Task and Run", "approval failure injection rolls back"] },
   { id: "I-03", summary: "Task is atomic and Sprint only groups evidenced batches", tests: ["migration apply creates linked v2 artifacts", "artifact repository builds explicit Feature Task Sprint Run graph"] },
   { id: "I-04", summary: "retry preserves prior Runs", tests: ["retry creates a new Run and preserves"] },
-  { id: "I-05", summary: "state transitions are declared and recoverable", tests: ["run state machine follows", "paired transition failure restores"] },
-  { id: "I-06", summary: "guardrails are canonical and cannot be weakened", tests: ["guardrails build preserves canonical v2 rules"] },
+  { id: "I-05", summary: "state transitions are declared, evidenced, ordered, and recoverable", tests: ["run state machine follows", "Run ledger uses stable event ids", "paired transition failure restores"] },
+  { id: "I-06", summary: "guardrails are canonical and cannot be weakened", tests: ["guardrails build preserves canonical v2 rules", "Policy Engine reports exact Guardrail ids"] },
   { id: "I-07", summary: "Markdown is canonical and indexes are disposable", tests: ["SQLite index is disposable"] },
   { id: "I-08", summary: "AI memory remains candidate", tests: ["AI insights stay candidate"] },
   { id: "I-09", summary: "confirmed claims require evidence", tests: ["confirmed facts reject missing"] },
   { id: "I-10", summary: "inactive memory is not active truth", tests: ["stale and expired memory are labeled"] },
   { id: "I-11", summary: "vault values never leave the vault boundary", tests: ["migration dry-run is read-only and never renders vault", "SQLite index is disposable"] },
   { id: "I-12", summary: "canonical schemas and identities are valid", tests: ["v2 artifact schemas round-trip", "malformed and mismatched artifacts are rejected"] },
-  { id: "I-13", summary: "generated state exposes staleness", tests: ["generated state includes structured decisions", "approval rejects tampered or stale plans"] },
-  { id: "I-14", summary: "context and retrieval are bounded", tests: ["lean context stays within twenty-five percent", "semantic query caps relation output"] },
+  { id: "I-13", summary: "generated state exposes staleness", tests: ["generated state includes structured decisions", "approval rejects tampered or stale plans", "state staleness uses metadata fast path", "generated map status refuses stale projection"] },
+  { id: "I-14", summary: "context and retrieval are bounded", tests: ["lean context stays within twenty-five percent", "semantic query caps relation output", "semantic index staleness uses metadata fast path"] },
   { id: "I-15", summary: "migration and ordinary update are read-only by default", tests: ["migration dry-run is read-only", "update preflights an ongoing v1 project"] },
-  { id: "I-16", summary: "migration is hashed, idempotent, and reversible", tests: ["migration apply is idempotent and rollback restores"] },
+  { id: "I-16", summary: "migration is hashed, idempotent, and reversible", tests: ["migration apply is idempotent and rollback restores", "Run ledger migration failure and rollback restore"] },
   { 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"] },
+  { 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) {
@@ -45,10 +50,11 @@ function auditProject(projectRoot) {
     return { method: METHOD_VERSION, passed: false, findings, counts: {} };
   }
   const marker = path.join(scrumDir, "method.json");
+  let methodMarker = null;
   try {
     if (!fs.existsSync(marker) || !fs.lstatSync(marker).isFile()) throw new Error("marker is missing, not a regular file, or is a symbolic link");
-    const value = JSON.parse(fs.readFileSync(marker, "utf8"));
-    if (value.method !== METHOD_VERSION) findings.push(finding("critical", "METHOD_VERSION", `method.json must declare ${METHOD_VERSION}.`, marker));
+    methodMarker = JSON.parse(fs.readFileSync(marker, "utf8"));
+    if (methodMarker.method !== METHOD_VERSION) findings.push(finding("critical", "METHOD_VERSION", `method.json must declare ${METHOD_VERSION}.`, marker));
   } catch (error) {
     findings.push(finding("critical", "METHOD_MARKER", `method.json is missing or malformed: ${error.message}`, marker));
   }
@@ -58,7 +64,21 @@ function auditProject(projectRoot) {
   }
   const guardrailsFile = path.join(scrumDir, "guardrails.md");
   const guardrails = fs.existsSync(guardrailsFile) && fs.lstatSync(guardrailsFile).isFile() ? fs.readFileSync(guardrailsFile, "utf8") : "";
-  if (!/^## GR-\d{3,}/m.test(guardrails)) findings.push(finding("high", "GUARDRAILS_EMPTY", "No stable-id Guardrail is defined."));
+  const guardrailValidation = validateGuardrailDocument(guardrails);
+  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));
 
   const repository = new ArtifactRepository(scrumDir);
   const counts = {};
@@ -85,6 +105,22 @@ function auditProject(projectRoot) {
     if (run.record && task && !task.errors.length && (run.record.sprint || null) !== (task.record.sprint || null)) {
       findings.push(finding("high", "RUN_SPRINT_MISMATCH", `${run.record.id}.sprint must match ${task.record.id}.sprint.`, run.file));
     }
+    if (run.record && run.record.ledger === RUN_LEDGER_VERSION) {
+      const ledger = validateRunLedger(run.record, run.body);
+      for (const error of ledger.errors) findings.push(finding("high", "RUN_LEDGER_INVALID", `${run.record.id}: ${error}`, run.file));
+    } else if (run.record) {
+      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 || []) {
@@ -110,6 +146,26 @@ function auditProject(projectRoot) {
       findings.push(finding("high", "RUN_ATTEMPT_SEQUENCE", `${taskId} Run attempts must be unique and contiguous from 1; found ${ordered.join(", ")}.`));
     }
   }
+  for (const task of records.task || []) {
+    if (!task.record || task.errors.length) continue;
+    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;
+    const latest = attempts[0].record;
+    const taskStatuses = {
+      executing: "running",
+      validating: "validating",
+      learning: "learning",
+      completed: "completed",
+      failed: "failed",
+      blocked: "blocked",
+      partial: "partial"
+    };
+    if (taskStatuses[latest.status] && task.record.status !== taskStatuses[latest.status]) {
+      findings.push(finding("high", "TASK_RUN_STATUS_MISMATCH", `${task.record.id}.status ${task.record.status} disagrees with latest ${latest.id}.status ${latest.status}.`, task.file));
+    }
+  }
   for (const sprint of records.sprint || []) {
     if (!sprint.record || sprint.errors.length) continue;
     const heading = /^## Tasks[ \t]*$/m.exec(sprint.body);
@@ -157,9 +213,19 @@ function auditProject(projectRoot) {
   try {
     const semantic = indexStatus(projectRoot);
     if (semantic.exists && semantic.stale) findings.push(finding("warning", "INDEX_STALE", "semantic-index.sqlite is stale and will be rebuilt on query."));
+    const map = mapStatus(projectRoot, { semanticStatus: semantic });
+    if (semantic.exists && map.stale) findings.push(finding("warning", "MAP_STALE", `map.md is stale: ${map.reason || map.error || "unknown reason"}.`));
   } catch (error) {
     findings.push(finding("high", "INDEX_UNSAFE", `semantic index cannot inspect canonical sources safely: ${error.message}`));
   }
+  const transactions = pendingTransactionStatus(scrumDir);
+  if (transactions.error) {
+    findings.push(finding("high", "TRANSACTION_JOURNAL_UNSAFE", transactions.error));
+  } else {
+    for (const transaction of transactions.pending) {
+      findings.push(finding("high", "TRANSACTION_PENDING", `${transaction.id} (${transaction.name}) is ${transaction.status}; run the approved operation again or recover explicitly before trusting canonical state.`));
+    }
+  }
   const blocking = findings.filter((item) => ["critical", "high"].includes(item.severity));
   return { method: METHOD_VERSION, passed: blocking.length === 0, findings, counts, invariants: INVARIANTS.length };
 }

package/lib/v2/migration.js

@@ -16,6 +16,9 @@ const {
   sha256,
   validateArtifact
 } = require("./artifacts");
+const { inferEnforcement, normalizeGuardrailDocument } = require("../runtime/policy-engine");
+const { RUN_LEDGER_VERSION } = require("./schema");
+const { migrateLegacyRun } = require("../runtime/run-ledger");
 
 const MIGRATION_NAME = "v1-to-v2";
 const MANIFEST_PATH = path.join(".migration", MIGRATION_NAME, "manifest.json");
@@ -322,19 +325,30 @@ function migrationPlan(projectRoot) {
   const created = today();
 
   function addArtifact(record, body, source = null) {
-    const validation = validateArtifact(record);
+    let canonicalRecord = record;
+    let canonicalBody = body;
+    if (record.kind === "run" && record.ledger !== RUN_LEDGER_VERSION) {
+      const legacyHash = sha256(source ? source.raw : body);
+      const backupRef = source
+        ? `.scrumrun/${backupRelative(source.path)}`
+        : `.scrumrun/${backupRelative(relativeArtifactPath(record))}`;
+      const migrated = migrateLegacyRun(record, body, { legacyHash, backupRef });
+      canonicalRecord = migrated.record;
+      canonicalBody = migrated.body;
+    }
+    const validation = validateArtifact(canonicalRecord);
     if (validation.length) {
-      errors.push(`${record.id || "unknown"}: ${validation.join("; ")}`);
+      errors.push(`${canonicalRecord.id || "unknown"}: ${validation.join("; ")}`);
       return null;
     }
-    const relative = posix(relativeArtifactPath(record));
-    const content = serializeArtifact(record, body);
+    const relative = posix(relativeArtifactPath(canonicalRecord));
+    const content = serializeArtifact(canonicalRecord, canonicalBody);
     if (generated.has(relative) && generated.get(relative) !== content) {
       errors.push(`Generated artifact collision: ${relative}`);
       return null;
     }
     generated.set(relative, content);
-    artifacts.push({ id: record.id, kind: record.kind, status: record.status, relative, record });
+    artifacts.push({ id: canonicalRecord.id, kind: canonicalRecord.kind, status: canonicalRecord.status, relative, record: canonicalRecord });
     if (source) {
       mappings.push({
         source: source.path,
@@ -342,10 +356,10 @@ function migrationPlan(projectRoot) {
         sourceSha256: sha256(source.raw),
         outcome: "transformed",
         destination: relative,
-        id: record.id
+        id: canonicalRecord.id
       });
     }
-    return { record, relative };
+    return { record: canonicalRecord, relative };
   }
 
   function normalizeExistingArtifacts() {
@@ -367,6 +381,18 @@ function migrationPlan(projectRoot) {
         const record = { ...artifact.record };
         let body = artifact.body;
         let changed = false;
+        if (kind === "run" && record.ledger !== RUN_LEDGER_VERSION) {
+          const relative = posix(path.relative(scrumDir, artifact.file));
+          const legacyContent = fs.readFileSync(artifact.file, "utf8");
+          const migrated = migrateLegacyRun(record, body, {
+            legacyHash: sha256(legacyContent),
+            backupRef: `.scrumrun/${backupRelative(relative)}`
+          });
+          Object.assign(record, migrated.record);
+          body = migrated.body;
+          changed = true;
+          warnings.push(`${record.id}: migrated the existing Run to ledger ${RUN_LEDGER_VERSION} using ${migrated.mode}.`);
+        }
         const alias = aliases[kind] && aliases[kind][record.status];
         if (alias) {
           record.status = alias;
@@ -487,6 +513,33 @@ function migrationPlan(projectRoot) {
     return candidates.length ? candidates[0][1] : null;
   }
 
+  function synchronizeGeneratedTask(task, status) {
+    const mapped = {
+      executing: "running",
+      validating: "validating",
+      learning: "learning",
+      completed: "completed",
+      failed: "failed",
+      blocked: "blocked",
+      partial: "partial"
+    }[status];
+    if (!mapped || task.status === mapped) return;
+    const relative = posix(relativeArtifactPath(task));
+    const content = generated.get(relative);
+    if (!content) return;
+    const parsed = parseArtifact(content);
+    if (!parsed.record || parsed.errors.length) return;
+    task.status = mapped;
+    task.updated = created;
+    generated.set(relative, serializeArtifact({ ...parsed.record, status: mapped, updated: created }, parsed.body));
+    const entry = artifacts.find((artifact) => artifact.id === task.id);
+    if (entry) {
+      entry.status = mapped;
+      entry.record.status = mapped;
+      entry.record.updated = created;
+    }
+  }
+
   function migrateHistory(relative, { lane = "main" } = {}) {
     const content = readText(scrumDir, relative);
     if (!content) return;
@@ -512,10 +565,11 @@ function migrationPlan(projectRoot) {
         continue;
       }
       const id = allocator.claim("run");
+      const status = runStatus(block.raw);
       addArtifact({
         id,
         kind: "run",
-        status: runStatus(block.raw),
+        status,
         created,
         updated: created,
         method: METHOD_VERSION,
@@ -524,6 +578,7 @@ function migrationPlan(projectRoot) {
         attempt,
         legacy_source: relative
       }, sourceBody(block.heading, relative, block.heading, block.raw), { path: relative, anchor: block.heading, raw: block.raw });
+      synchronizeGeneratedTask(task, status);
     }
   }
 
@@ -763,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);
@@ -794,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}\``,
         ""
       ]),
@@ -868,7 +926,13 @@ function migrationPlan(projectRoot) {
   }
 
   const sourceLayout = existingIds.size ? "hybrid-v1-v2" : "1.x";
-  generated.set("method.json", `${JSON.stringify({ method: METHOD_VERSION, layout: "v2", migrated_from: sourceLayout, migration: MIGRATION_NAME }, null, 2)}\n`);
+  generated.set("method.json", `${JSON.stringify({
+    method: METHOD_VERSION,
+    layout: "v2",
+    schemas: { run_ledger: RUN_LEDGER_VERSION, guardrails: 1, run_obligations: 1, mutation_gateway: 1 },
+    migrated_from: sourceLayout,
+    migration: MIGRATION_NAME
+  }, null, 2)}\n`);
 
   const counts = {};
   for (const artifact of artifacts) counts[artifact.kind] = (counts[artifact.kind] || 0) + 1;