scrumrun 2.0.0 → 2.1.0

package/lib/runtime/run-ledger.js

@@ -0,0 +1,324 @@
+"use strict";
+
+const {
+  ARTIFACT_TRANSITIONS,
+  RUN_EVENT_TYPES,
+  RUN_EVIDENCE_KINDS,
+  RUN_LEDGER_VERSION
+} = require("../v2/schema");
+const { containsSecret } = require("../security/secrets");
+
+const EVENT_ID = /^(RUN-\d{3,})-EVT-(\d{3,})$/;
+const RFC3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?(?:Z|[+-]\d{2}:\d{2})$/;
+
+function instant(value = new Date()) {
+  const parsed = value instanceof Date ? value : new Date(value);
+  if (!Number.isFinite(parsed.getTime())) throw new Error("Run event timestamp is invalid.");
+  return parsed.toISOString();
+}
+
+function dateInstant(value) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value || "")) throw new Error(`Legacy Run event date is invalid: ${value || "missing"}`);
+  return `${value}T00:00:00.000Z`;
+}
+
+function eventId(runId, sequence) {
+  return `${runId}-EVT-${String(sequence).padStart(3, "0")}`;
+}
+
+function normalizeEvidence(evidence = []) {
+  if (!Array.isArray(evidence)) throw new Error("Run event evidence must be an array.");
+  return evidence.map((item) => {
+    if (typeof item === "string") return { kind: "note", summary: item.trim() };
+    if (!item || typeof item !== "object" || Array.isArray(item)) return item;
+    const normalized = { kind: item.kind };
+    if (item.ref !== undefined && item.ref !== null) normalized.ref = String(item.ref).trim();
+    if (item.summary !== undefined && item.summary !== null) normalized.summary = String(item.summary).trim();
+    return normalized;
+  });
+}
+
+function evidenceForTransition(nextStatus, note, evidence = []) {
+  const normalized = normalizeEvidence(evidence);
+  if (note && !normalized.length) {
+    const kind = nextStatus === "validating" ? "test" : nextStatus === "learning" ? "insight" : nextStatus === "blocked" || nextStatus === "failed" ? "risk" : "note";
+    normalized.push({ kind, summary: String(note).trim() });
+  }
+  return normalized;
+}
+
+function makeRunEvent({
+  runId,
+  sequence,
+  type = "transition",
+  occurredAt = instant(),
+  timestampPrecision = "instant",
+  actor = "agent",
+  from,
+  to,
+  reason,
+  evidence = []
+}) {
+  return {
+    schema: RUN_LEDGER_VERSION,
+    id: eventId(runId, sequence),
+    sequence,
+    type,
+    occurred_at: occurredAt,
+    timestamp_precision: timestampPrecision,
+    actor,
+    from: from === undefined ? null : from,
+    to,
+    reason,
+    evidence: normalizeEvidence(evidence)
+  };
+}
+
+function renderRunEvent(event) {
+  return `### ${event.id}\n\n\`\`\`json\n${JSON.stringify(event, null, 2)}\n\`\`\``;
+}
+
+function eventsSection(events) {
+  return `## Events\n\n${events.map(renderRunEvent).join("\n\n")}`;
+}
+
+function runTitle(body, fallback) {
+  return ((body || "").match(/^# ([^\r\n]+)$/m) || [])[1] || fallback;
+}
+
+function createRunBody(record, {
+  title = `Run for ${record.task}`,
+  approvalId = null,
+  occurredAt = instant(),
+  actor = "owner",
+  reason = "Explicit approval accepted.",
+  evidence = null
+} = {}) {
+  const eventEvidence = evidence || [{
+    kind: "approval",
+    ...(approvalId ? { ref: `approval:${approvalId}` } : {}),
+    summary: reason
+  }];
+  const event = makeRunEvent({
+    runId: record.id,
+    sequence: 1,
+    occurredAt,
+    actor,
+    from: "created",
+    to: "executing",
+    reason,
+    evidence: eventEvidence
+  });
+  return { body: `# ${title}\n\n${eventsSection([event])}`, event };
+}
+
+function parseRunLedger(body) {
+  const events = [];
+  const errors = [];
+  const headings = [...String(body || "").matchAll(/^### (RUN-\d{3,}-EVT-\d{3,})[ \t]*$/gm)];
+  const blocks = [...String(body || "").matchAll(/^### (RUN-\d{3,}-EVT-\d{3,})[ \t]*\r?\n[ \t]*\r?\n```json[ \t]*\r?\n([\s\S]*?)\r?\n```[ \t]*$/gm)];
+  if (headings.length !== blocks.length) errors.push("one or more Run event blocks are malformed");
+  for (const block of blocks) {
+    try {
+      const event = JSON.parse(block[2]);
+      if (!event || typeof event !== "object" || Array.isArray(event)) throw new Error("event payload must be an object");
+      if (event.id !== block[1]) errors.push(`${block[1]} payload id does not match its heading`);
+      events.push(event);
+    } catch (error) {
+      errors.push(`${block[1]} contains invalid JSON: ${error.message}`);
+    }
+  }
+  return { events, errors };
+}
+
+function validateEvidence(event) {
+  const errors = [];
+  if (!Array.isArray(event.evidence)) return [`${event.id}.evidence must be an array`];
+  for (let index = 0; index < event.evidence.length; index++) {
+    const item = event.evidence[index];
+    const label = `${event.id}.evidence[${index}]`;
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      errors.push(`${label} must be an object`);
+      continue;
+    }
+    if (!RUN_EVIDENCE_KINDS.includes(item.kind)) errors.push(`${label}.kind is invalid: ${item.kind || "missing"}`);
+    if (!(typeof item.ref === "string" && item.ref.trim()) && !(typeof item.summary === "string" && item.summary.trim())) {
+      errors.push(`${label} requires ref or summary`);
+    }
+  }
+  return errors;
+}
+
+function validateRunLedger(record, body) {
+  const parsed = parseRunLedger(body);
+  const errors = [...parsed.errors];
+  const events = parsed.events;
+  if (record.ledger !== RUN_LEDGER_VERSION) errors.push(`ledger must be ${RUN_LEDGER_VERSION}`);
+  if (!events.length) errors.push("Run ledger has no events");
+  const ids = new Set();
+  let previous = null;
+  let previousTime = null;
+  for (let index = 0; index < events.length; index++) {
+    const event = events[index];
+    const expectedSequence = index + 1;
+    const match = EVENT_ID.exec(event.id || "");
+    if (!match || match[1] !== record.id) errors.push(`invalid event id for ${record.id}: ${event.id || "missing"}`);
+    if (ids.has(event.id)) errors.push(`duplicate Run event id: ${event.id}`);
+    ids.add(event.id);
+    if (event.schema !== RUN_LEDGER_VERSION) errors.push(`${event.id}.schema must be ${RUN_LEDGER_VERSION}`);
+    if (event.sequence !== expectedSequence || (match && Number(match[2]) !== expectedSequence)) {
+      errors.push(`${event.id}.sequence must be contiguous from 1; expected ${expectedSequence}`);
+    }
+    if (!RUN_EVENT_TYPES.includes(event.type)) errors.push(`${event.id}.type is invalid: ${event.type || "missing"}`);
+    if (!RFC3339.test(event.occurred_at || "") || !Number.isFinite(Date.parse(event.occurred_at))) {
+      errors.push(`${event.id}.occurred_at must be a real RFC3339 timestamp`);
+    } else {
+      const currentTime = Date.parse(event.occurred_at);
+      if (previousTime !== null && currentTime < previousTime) errors.push(`${event.id}.occurred_at precedes the previous event`);
+      previousTime = currentTime;
+    }
+    if (!["instant", "date"].includes(event.timestamp_precision)) errors.push(`${event.id}.timestamp_precision must be instant or date`);
+    if (typeof event.actor !== "string" || !event.actor.trim()) errors.push(`${event.id}.actor is required`);
+    if (typeof event.reason !== "string" || !event.reason.trim()) errors.push(`${event.id}.reason is required`);
+    if (containsSecret(JSON.stringify(event))) errors.push(`${event.id} contains secret-like content`);
+    errors.push(...validateEvidence(event));
+
+    if (index === 0 && event.type === "snapshot") {
+      if (event.from !== null) errors.push(`${event.id} snapshot.from must be null`);
+      if (!event.evidence.some((item) => item && ["migration", "legacy"].includes(item.kind))) {
+        errors.push(`${event.id} snapshot requires migration or legacy evidence`);
+      }
+    } else {
+      const expectedFrom = index === 0 ? "created" : previous.to;
+      if (event.type !== "transition") errors.push(`${event.id} snapshot is allowed only as the first event`);
+      if (event.from !== expectedFrom) errors.push(`${event.id}.from must be ${expectedFrom}`);
+      if (event.from === "created") {
+        if (event.to !== "executing") errors.push(`${event.id} initial transition must enter executing`);
+      } else {
+        const allowed = (ARTIFACT_TRANSITIONS.run[event.from] || []);
+        if (!allowed.includes(event.to)) errors.push(`${event.id} contains invalid Run transition: ${event.from} -> ${event.to}`);
+      }
+    }
+    if (!["snapshot"].includes(event.type) && !event.evidence.length) errors.push(`${event.id} transition requires evidence`);
+    previous = event;
+  }
+  if (previous && previous.to !== record.status) errors.push(`Run status ${record.status} disagrees with final event state ${previous.to}`);
+  if (previous && record.updated !== String(previous.occurred_at || "").slice(0, 10)) {
+    errors.push(`Run updated date ${record.updated} disagrees with final event timestamp`);
+  }
+  if (record.status === "completed" && events[0] && events[0].type !== "snapshot") {
+    for (const required of ["validating", "learning", "completed"]) {
+      const event = events.find((item) => item.type === "transition" && item.to === required);
+      if (!event || !event.evidence.length) errors.push(`completed Run requires evidenced ${required} transition`);
+    }
+  }
+  return { events, errors };
+}
+
+function appendRunEvent(record, body, nextRecord, {
+  note,
+  evidence = [],
+  actor = "agent",
+  occurredAt = instant()
+} = {}) {
+  const current = validateRunLedger(record, body);
+  if (current.errors.length) throw new Error(`Invalid Run ledger: ${current.errors.join("; ")}`);
+  const normalizedEvidence = evidenceForTransition(nextRecord.status, note, evidence);
+  if (!note && !normalizedEvidence.length) throw new Error(`Run transition to ${nextRecord.status} requires a reason or structured evidence.`);
+  const reason = String(note || normalizedEvidence.map((item) => item.summary || item.ref).filter(Boolean).join("; ")).trim();
+  const event = makeRunEvent({
+    runId: record.id,
+    sequence: current.events.length + 1,
+    occurredAt,
+    actor,
+    from: record.status,
+    to: nextRecord.status,
+    reason,
+    evidence: normalizedEvidence
+  });
+  const nextBody = `${String(body).trimEnd()}\n\n${renderRunEvent(event)}\n`;
+  const validated = validateRunLedger(nextRecord, nextBody);
+  if (validated.errors.length) throw new Error(`Run ledger transition failed validation: ${validated.errors.join("; ")}`);
+  return { body: nextBody, event, events: validated.events };
+}
+
+function legacyTransitionEvents(record, body, legacyHash) {
+  const raw = [];
+  const log = String(body || "").match(/^## Transition Log[ \t]*\r?\n([\s\S]*?)(?=^## |(?![\s\S]))/m);
+  if (log) {
+    const initial = log[1].match(/^-\s+(\d{4}-\d{2}-\d{2}):\s*([a-z]+)\s*(?:→|->)\s*([a-z]+)\s*(?:—|-)\s*(.+)$/m);
+    if (initial) raw.push({ date: initial[1], from: initial[2], to: initial[3], note: initial[4].trim() });
+  }
+  for (const match of String(body || "").matchAll(/^## Transition (\d{4}-\d{2}-\d{2}) · ([a-z]+)-to-([a-z]+)[ \t]*\r?\n\r?\n-\s+([^\r\n]+)$/gm)) {
+    raw.push({ date: match[1], from: match[2], to: match[3], note: match[4].trim() });
+  }
+  if (!raw.length) return [];
+  let previous = "created";
+  for (const item of raw) {
+    if (item.from !== previous) return [];
+    const allowed = item.from === "created" ? ["executing"] : (ARTIFACT_TRANSITIONS.run[item.from] || []);
+    if (!allowed.includes(item.to)) return [];
+    previous = item.to;
+  }
+  if (previous !== record.status) return [];
+  return raw.map((item, index) => makeRunEvent({
+    runId: record.id,
+    sequence: index + 1,
+    occurredAt: dateInstant(item.date),
+    timestampPrecision: "date",
+    actor: "migration",
+    from: item.from,
+    to: item.to,
+    reason: item.note,
+    evidence: [
+      { kind: index === 0 ? "approval" : "note", summary: item.note },
+      { kind: "legacy", ref: `sha256:${legacyHash}`, summary: "Recovered from the byte-exact legacy Run record." }
+    ]
+  }));
+}
+
+function migrateLegacyRun(record, body, { legacyHash, backupRef }) {
+  let events = legacyTransitionEvents(record, body, legacyHash);
+  let mode = "transitions";
+  if (!events.length) {
+    mode = "snapshot";
+    events = [makeRunEvent({
+      runId: record.id,
+      sequence: 1,
+      type: "snapshot",
+      occurredAt: dateInstant(record.updated),
+      timestampPrecision: "date",
+      actor: "migration",
+      from: null,
+      to: record.status,
+      reason: "Imported the recorded Run state without inventing missing transitions.",
+      evidence: [{
+        kind: "legacy",
+        ref: `sha256:${legacyHash}`,
+        summary: `Byte-exact source preserved at ${backupRef}.`
+      }]
+    })];
+  }
+  const title = runTitle(body, `Run for ${record.task}`);
+  const provenance = `## Ledger Migration\n\n- Mode: ${mode}\n- Legacy SHA-256: \`${legacyHash}\`\n- Byte-exact backup: \`${backupRef}\``;
+  const nextRecord = { ...record, ledger: RUN_LEDGER_VERSION };
+  const nextBody = `# ${title}\n\n${eventsSection(events)}\n\n${provenance}\n`;
+  const validation = validateRunLedger(nextRecord, nextBody);
+  if (validation.errors.length) throw new Error(`${record.id} ledger migration failed: ${validation.errors.join("; ")}`);
+  return { record: nextRecord, body: nextBody, events, mode };
+}
+
+module.exports = {
+  appendRunEvent,
+  createRunBody,
+  dateInstant,
+  eventId,
+  eventsSection,
+  evidenceForTransition,
+  instant,
+  makeRunEvent,
+  migrateLegacyRun,
+  parseRunLedger,
+  renderRunEvent,
+  validateRunLedger
+};

package/lib/v2/artifacts.js

@@ -111,6 +111,9 @@ 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`);
+    }
   }
   return errors;
 }
@@ -162,10 +165,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,32 +3,35 @@
 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 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"] }
 ]);
@@ -45,10 +48,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 +62,13 @@ 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 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 +95,13 @@ 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 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 +127,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 +194,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,8 @@ const {
   sha256,
   validateArtifact
 } = require("./artifacts");
+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 +324,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 +355,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 +380,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 +512,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 +564,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 +577,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);
     }
   }
 
@@ -868,7 +922,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 },
+    migrated_from: sourceLayout,
+    migration: MIGRATION_NAME
+  }, null, 2)}\n`);
 
   const counts = {};
   for (const artifact of artifacts) counts[artifact.kind] = (counts[artifact.kind] || 0) + 1;