ai-delivery-workflow 0.2.2 → 0.4.0

package/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs

@@ -3,6 +3,7 @@ import path from "node:path";
 import crypto from "node:crypto";
 import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
 
 const moduleRequire = createRequire(import.meta.url);
 
@@ -12,13 +13,48 @@ const VALID_STATUS = new Set([
 ]);
 const FINISH_STATUS = new Set(["completed", "blocked", "interrupted", "failed", "abandoned"]);
 const CLOSED_STATUS = new Set(["completed", "failed", "abandoned"]);
+const RECOVERY_COMPLETE_STATUS = new Set(["completed", "abandoned"]);
 const RESUMABLE_STATUS = new Set([
   "preparing", "running", "checkpointed", "pending-review", "blocked", "interrupted",
 ]);
 const VALID_NEXT_ACTION_OWNER = new Set(["agent", "user", "external"]);
+const VALID_PHASE = new Set([
+  "planning", "implementation", "review", "triage", "repair", "test", "verification", "handoff",
+]);
+const VALID_PHASE_STATUS = new Set([
+  "active", "completed", "failed", "blocked", "interrupted", "abandoned",
+]);
+const VALID_FINDING_SEVERITY = new Set(["info", "warning", "blocking"]);
+const VALID_FINDING_STATUS = new Set(["open", "resolved", "accepted"]);
+const VALID_COLLECTION_DECISION = new Set(["pass", "fail", "blocked"]);
+const VALID_TIME_CATEGORY = new Set([
+  "implementation", "test", "review", "workflow", "user-wait", "external-wait", "rework",
+]);
+const TASK_STATUS_PROJECTION = new Map([
+  ["completed", { attempt: "completed", phase: "completed" }],
+  ["failed", { attempt: "failed", phase: "failed" }],
+  ["abandoned", { attempt: "abandoned", phase: "abandoned" }],
+  ["blocked", { attempt: "paused", phase: "blocked" }],
+  ["interrupted", { attempt: "paused", phase: "interrupted" }],
+]);
 const REPEATABLE_ARGS = new Set([
   "scope", "input-artifact", "standard", "planned-output", "actual-output",
-  "completed-step", "blocker", "evidence", "depends-on",
+  "completed-step", "blocker", "evidence", "depends-on", "acceptance", "finding-json",
+  "change-set-json",
+]);
+const LEGACY_DEVELOPMENT_NODE_IDS = new Set([
+  "01-product-discovery",
+  "02-product-definition",
+  "03-architecture-initial",
+  "04-experience-design",
+  "05-architecture-reconcile",
+  "06-platform-preparation",
+  "07-iteration-planning",
+  "08-test-design",
+  "09-development",
+  "10-change-review",
+  "11-candidate-verification",
+  "12-version-closeout",
 ]);
 
 function parseArgs(argv) {
@@ -47,6 +83,13 @@ function requireValue(args, key) {
   return value;
 }
 
+function assertNotLegacyDevelopmentNode(node) {
+  if (LEGACY_DEVELOPMENT_NODE_IDS.has(node)) {
+    throw new Error(`Legacy workflow node is read-only: ${node}`);
+  }
+  return node;
+}
+
 function now() {
   return new Date().toISOString();
 }
@@ -67,6 +110,265 @@ function parseSequence(value) {
   return sequence;
 }
 
+function parsePhase(value, fallback = null) {
+  const phase = value === undefined || value === null || value === "" ? fallback : value;
+  if (phase !== null && !VALID_PHASE.has(phase)) {
+    throw new Error(`Invalid attempt phase: ${phase}; use ${[...VALID_PHASE].join(", ")}.`);
+  }
+  return phase;
+}
+
+function parseElapsedMinutes(value) {
+  if (value === undefined || value === null || value === "") return null;
+  const minutes = Number(value);
+  if (!Number.isFinite(minutes) || minutes < 0) {
+    throw new Error(`Invalid non-negative elapsed minutes: ${value}`);
+  }
+  return minutes;
+}
+
+function normalizeRelativeFiles(values, label) {
+  if (!Array.isArray(values)) return [];
+  return [...new Set(values.map((value) => {
+    const normalized = String(value).trim().replaceAll("\\", "/");
+    if (!normalized || path.posix.isAbsolute(normalized) || normalized.split("/").includes("..")) {
+      throw new Error(`${label} must contain repository-relative file paths.`);
+    }
+    return normalized;
+  }))];
+}
+
+function normalizeFinding(value) {
+  let finding;
+  try {
+    finding = typeof value === "string" ? JSON.parse(value) : value;
+  } catch {
+    throw new Error("--finding-json must be valid JSON.");
+  }
+  if (!finding || typeof finding !== "object" || Array.isArray(finding)) {
+    throw new Error("--finding-json must contain one finding object.");
+  }
+  const findingId = sanitizeId(String(finding.finding_id || ""));
+  const summary = typeof finding.summary === "string" ? finding.summary.trim() : "";
+  if (!summary) throw new Error(`Finding ${findingId} requires a non-empty summary.`);
+  const severity = finding.severity || "warning";
+  if (!VALID_FINDING_SEVERITY.has(severity)) {
+    throw new Error(`Finding ${findingId} has invalid severity: ${severity}`);
+  }
+  const status = finding.status || "open";
+  if (!VALID_FINDING_STATUS.has(status)) {
+    throw new Error(`Finding ${findingId} has invalid status: ${status}`);
+  }
+  const evidence = Array.isArray(finding.evidence)
+    ? [...new Set(finding.evidence.map((item) => String(item).trim()).filter(Boolean))]
+    : [];
+  const changedFiles = normalizeRelativeFiles(finding.changed_files, `Finding ${findingId} changed_files`);
+  const changeSetId = finding.change_set_id ? sanitizeId(String(finding.change_set_id)) : null;
+  return {
+    finding_id: findingId,
+    severity,
+    status,
+    summary,
+    evidence,
+    ...(changedFiles.length ? { changed_files: changedFiles } : {}),
+    ...(changeSetId ? { change_set_id: changeSetId } : {}),
+  };
+}
+
+function normalizeChangeSet(value, approvalTimestamp = null) {
+  let changeSet;
+  try {
+    changeSet = typeof value === "string" ? JSON.parse(value) : value;
+  } catch {
+    throw new Error("--change-set-json must be valid JSON.");
+  }
+  if (!changeSet || typeof changeSet !== "object" || Array.isArray(changeSet)) {
+    throw new Error("--change-set-json must contain one change-set object.");
+  }
+  const changeSetId = sanitizeId(String(changeSet.change_set_id || ""));
+  const suppliedCollectionChecksum = changeSet.collection_checksum
+    ? String(changeSet.collection_checksum).toLowerCase()
+    : null;
+  if (suppliedCollectionChecksum && !/^[a-f0-9]{64}$/.test(suppliedCollectionChecksum)) {
+    throw new Error(`Change set ${changeSetId} collection_checksum must be a SHA-256 checksum.`);
+  }
+  const approvalActor = typeof changeSet.approval_actor === "string" ? changeSet.approval_actor.trim() : "";
+  if (!approvalActor) throw new Error(`Change set ${changeSetId} requires approval_actor.`);
+  const rationale = typeof changeSet.rationale === "string" ? changeSet.rationale.trim() : "";
+  if (!rationale) throw new Error(`Change set ${changeSetId} requires rationale.`);
+  const findingIds = Array.isArray(changeSet.finding_ids)
+    ? [...new Set(changeSet.finding_ids.map((item) => sanitizeId(String(item))))]
+    : [];
+  if (!findingIds.length) throw new Error(`Change set ${changeSetId} requires finding_ids.`);
+  const allowedFiles = normalizeRelativeFiles(changeSet.allowed_files, `Change set ${changeSetId} allowed_files`);
+  if (!allowedFiles.length) throw new Error(`Change set ${changeSetId} requires allowed_files.`);
+  const expectedEvidence = Array.isArray(changeSet.expected_evidence)
+    ? [...new Set(changeSet.expected_evidence.map((item) => String(item).trim()).filter(Boolean))]
+    : [];
+  if (!expectedEvidence.length) throw new Error(`Change set ${changeSetId} requires expected_evidence.`);
+  const common = {
+    change_set_id: changeSetId,
+    approval_actor: approvalActor,
+    rationale,
+    finding_ids: findingIds,
+    allowed_files: allowedFiles,
+    expected_evidence: expectedEvidence,
+  };
+  if (approvalTimestamp) {
+    const reviewAxes = Array.isArray(changeSet.review_axes)
+      ? [...new Set(changeSet.review_axes.map((item) => String(item).trim()).filter(Boolean))]
+      : [];
+    if (!reviewAxes.length) throw new Error(`Change set ${changeSetId} requires review_axes.`);
+    const collectionDecision = String(changeSet.collection_decision || "").trim();
+    if (!VALID_COLLECTION_DECISION.has(collectionDecision)) {
+      throw new Error(`Change set ${changeSetId} collection_decision must be pass, fail, or blocked.`);
+    }
+    return {
+      ...common,
+      review_axes: reviewAxes,
+      collection_decision: collectionDecision,
+      supplied_collection_checksum: suppliedCollectionChecksum,
+      approved_at: approvalTimestamp,
+    };
+  }
+
+  const repairBaseline = normalizeCodeBaseline(
+    changeSet.repair_baseline,
+    `Change set ${changeSetId} repair_baseline`,
+  );
+  const feedbackCollection = normalizeFeedbackCollection(changeSet.feedback_collection, changeSetId);
+  if (feedbackCollection.subject_checksum !== repairBaseline.subject_checksum) {
+    throw new Error(`Change set ${changeSetId} feedback collection does not match its repair baseline subject_checksum.`);
+  }
+  const collectionChecksum = checksumJson(feedbackCollection);
+  if (suppliedCollectionChecksum !== collectionChecksum) {
+    throw new Error(`Change set ${changeSetId} collection_checksum does not match its persisted feedback collection.`);
+  }
+  const collectionFindingIds = feedbackCollection.findings.map((finding) => finding.finding_id);
+  if (!sameStringSet(findingIds, collectionFindingIds)) {
+    throw new Error(`Change set ${changeSetId} finding_ids do not match its persisted feedback collection.`);
+  }
+  const approvedAt = changeSet.approved_at;
+  if (!approvedAt) throw new Error(`Change set ${changeSetId} requires approved_at.`);
+  return {
+    ...common,
+    feedback_collection: feedbackCollection,
+    collection_checksum: collectionChecksum,
+    repair_baseline: repairBaseline,
+    approved_at: approvedAt,
+  };
+}
+
+function normalizeCodeBaseline(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object.`);
+  }
+  const codeCommit = String(value.code_commit || "").toLowerCase();
+  if (!/^[a-f0-9]{40,64}$/.test(codeCommit)) {
+    throw new Error(`${label} requires a Git code_commit.`);
+  }
+  const dirtyFiles = Array.isArray(value.dirty_files) ? value.dirty_files.map((file) => {
+    if (!file || typeof file !== "object" || Array.isArray(file)) {
+      throw new Error(`${label} dirty_files must contain objects.`);
+    }
+    const [relativePath] = normalizeRelativeFiles([file.path], `${label} dirty_files`);
+    const checksum = file.checksum === null ? null : String(file.checksum || "").toLowerCase();
+    if (checksum !== null && !/^[a-f0-9]{64}$/.test(checksum)) {
+      throw new Error(`${label} has an invalid checksum for ${relativePath}.`);
+    }
+    return { path: relativePath, checksum };
+  }) : [];
+  dirtyFiles.sort((left, right) => left.path.localeCompare(right.path));
+  if (new Set(dirtyFiles.map((file) => file.path)).size !== dirtyFiles.length) {
+    throw new Error(`${label} contains duplicate dirty files.`);
+  }
+  const baseline = { code_commit: codeCommit, dirty_files: dirtyFiles };
+  const subjectChecksum = checksumJson(baseline);
+  if (String(value.subject_checksum || "").toLowerCase() !== subjectChecksum) {
+    throw new Error(`${label} subject_checksum does not match its persisted baseline.`);
+  }
+  return { ...baseline, subject_checksum: subjectChecksum };
+}
+
+function normalizeFeedbackCollection(value, changeSetId) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Change set ${changeSetId} requires feedback_collection.`);
+  }
+  const subjectChecksum = String(value.subject_checksum || "").toLowerCase();
+  if (!/^[a-f0-9]{64}$/.test(subjectChecksum)) {
+    throw new Error(`Change set ${changeSetId} feedback_collection requires subject_checksum.`);
+  }
+  const reviewAxes = Array.isArray(value.review_axes)
+    ? [...new Set(value.review_axes.map((item) => String(item).trim()).filter(Boolean))]
+    : [];
+  if (!reviewAxes.length) throw new Error(`Change set ${changeSetId} feedback_collection requires review_axes.`);
+  const decision = String(value.decision || "").trim();
+  if (!VALID_COLLECTION_DECISION.has(decision)) {
+    throw new Error(`Change set ${changeSetId} feedback_collection decision must be pass, fail, or blocked.`);
+  }
+  const findings = Array.isArray(value.findings) ? value.findings.map(normalizeFinding) : [];
+  if (!findings.length || findings.some((finding) => finding.status !== "open")) {
+    throw new Error(`Change set ${changeSetId} feedback_collection requires open findings.`);
+  }
+  findings.sort((left, right) => left.finding_id.localeCompare(right.finding_id));
+  if (new Set(findings.map((finding) => finding.finding_id)).size !== findings.length) {
+    throw new Error(`Change set ${changeSetId} feedback_collection contains duplicate findings.`);
+  }
+  return { subject_checksum: subjectChecksum, review_axes: reviewAxes, decision, findings };
+}
+
+function projectedTaskStatus(status, target) {
+  return TASK_STATUS_PROJECTION.get(status)?.[target] || "active";
+}
+
+function normalizeAttempt(taskId, attempt, fallbackNumber) {
+  const number = Number(attempt?.number || fallbackNumber);
+  const phases = Array.isArray(attempt?.phases) ? attempt.phases.map((phase, index) => {
+    const sequence = Number(phase?.sequence || index + 1);
+    const phaseName = parsePhase(phase?.phase, "implementation");
+    const normalized = {
+      sequence,
+      phase: phaseName,
+      status: VALID_PHASE_STATUS.has(phase?.status) ? phase.status : "active",
+      started_at: phase?.started_at || null,
+      finished_at: phase?.finished_at || null,
+      findings: Array.isArray(phase?.findings) ? phase.findings.map(normalizeFinding) : [],
+    };
+    if (phase?.review_subject_baseline) {
+      if (phaseName !== "review") {
+        throw new Error(`Task ${taskId} phase ${sequence} stores a review subject outside review.`);
+      }
+      normalized.review_subject_baseline = normalizeCodeBaseline(
+        phase.review_subject_baseline,
+        `Task ${taskId} review phase ${sequence} review_subject_baseline`,
+      );
+    }
+    return normalized;
+  }) : [];
+  const timeEntries = Array.isArray(attempt?.time_entries) ? attempt.time_entries.map((entry) => ({
+    category: VALID_TIME_CATEGORY.has(entry?.category) ? entry.category : "workflow",
+    elapsed_minutes: parseElapsedMinutes(entry?.elapsed_minutes) || 0,
+    phase: parsePhase(entry?.phase, phases.at(-1)?.phase || "implementation"),
+    recorded_at: entry?.recorded_at || null,
+  })) : [];
+  const timeByCategory = {};
+  for (const entry of timeEntries) {
+    timeByCategory[entry.category] = (timeByCategory[entry.category] || 0) + entry.elapsed_minutes;
+  }
+  return {
+    attempt_id: attempt?.attempt_id || `${taskId}/A${number}`,
+    number,
+    status: new Set(["active", "paused", "completed", "failed", "abandoned"]).has(attempt?.status)
+      ? attempt.status
+      : "active",
+    started_at: attempt?.started_at || null,
+    finished_at: attempt?.finished_at || null,
+    phases,
+    time_entries: timeEntries,
+    time_by_category: timeByCategory,
+  };
+}
+
 function parseNextActionOwner(value, fallback = "agent") {
   const owner = value === undefined ? fallback : value;
   if (!VALID_NEXT_ACTION_OWNER.has(owner)) {
@@ -137,10 +439,82 @@ function statePaths(args) {
   return { projectRoot, stateRoot, workflowRoot, runtime, marker };
 }
 
+let activeWriteTransaction = null;
+
+function stagedContent(file) {
+  const staged = activeWriteTransaction?.entries.get(path.resolve(file));
+  if (staged?.action === "write") return staged.content;
+  if (staged?.action === "delete") return null;
+  return fs.existsSync(file) ? fs.readFileSync(file) : null;
+}
+
+function stageWrite(file, content) {
+  if (!activeWriteTransaction) return false;
+  const target = path.resolve(file);
+  activeWriteTransaction.entries.set(target, {
+    action: "write", file: target, content: Buffer.from(content),
+  });
+  return true;
+}
+
+function stageDelete(file) {
+  if (!activeWriteTransaction) return false;
+  const target = path.resolve(file);
+  activeWriteTransaction.entries.set(target, { action: "delete", file: target });
+  return true;
+}
+
+function commitWriteTransaction() {
+  if (!activeWriteTransaction) throw new Error("Task Writer transaction is not active");
+  const entries = [...activeWriteTransaction.entries.values()];
+  const snapshots = entries.map((entry) => {
+    if (fs.existsSync(entry.file) && !fs.statSync(entry.file).isFile()) {
+      throw new Error(`Task Writer transaction target must be a file: ${entry.file}`);
+    }
+    return {
+      file: entry.file,
+      existed: fs.existsSync(entry.file),
+      content: fs.existsSync(entry.file) ? fs.readFileSync(entry.file) : null,
+    };
+  });
+  const temporary = new Map();
+  try {
+    for (const entry of entries.filter((item) => item.action === "write")) {
+      fs.mkdirSync(path.dirname(entry.file), { recursive: true });
+      const temp = `${entry.file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+      fs.writeFileSync(temp, entry.content, { flag: "wx" });
+      temporary.set(entry.file, temp);
+    }
+    for (const entry of entries) {
+      if (entry.action === "write") fs.renameSync(temporary.get(entry.file), entry.file);
+      else fs.rmSync(entry.file, { force: true });
+      if (process.env.AI_DELIVERY_TEST_TASK_TRANSACTION_FAILURE_SUFFIX
+          && entry.file.endsWith(process.env.AI_DELIVERY_TEST_TASK_TRANSACTION_FAILURE_SUFFIX)) {
+        throw new Error("injected task transaction failure");
+      }
+    }
+  } catch (error) {
+    for (const temp of temporary.values()) fs.rmSync(temp, { force: true });
+    for (const snapshot of snapshots.reverse()) {
+      if (snapshot.existed) {
+        fs.mkdirSync(path.dirname(snapshot.file), { recursive: true });
+        fs.writeFileSync(snapshot.file, snapshot.content);
+      } else {
+        fs.rmSync(snapshot.file, { force: true });
+      }
+    }
+    throw error;
+  } finally {
+    activeWriteTransaction = null;
+  }
+}
+
 function atomicWrite(file, value) {
+  const content = `${JSON.stringify(value, null, 2)}\n`;
+  if (stageWrite(file, content)) return;
   fs.mkdirSync(path.dirname(file), { recursive: true });
   const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
-  fs.writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+  fs.writeFileSync(temp, content, "utf8");
   fs.renameSync(temp, file);
 }
 
@@ -212,17 +586,20 @@ function portablePath(root, target) {
     : target;
 }
 
-function parseWorkspaceConfiguration(workflowRoot) {
-  const workspaceFile = path.join(workflowRoot, "config", "workspace.yaml");
-  if (!fs.existsSync(workspaceFile)) return null;
-  let yaml;
+function yamlLibrary(workflowRoot) {
   try {
-    yaml = moduleRequire("yaml");
+    return moduleRequire("yaml");
   } catch {
     const vendorRoot = path.join(workflowRoot, "tools", "state", "vendor", "yaml");
     const vendorRequire = createRequire(path.join(vendorRoot, "package.json"));
-    yaml = vendorRequire("./");
+    return vendorRequire("./");
   }
+}
+
+function parseWorkspaceConfiguration(workflowRoot) {
+  const workspaceFile = path.join(workflowRoot, "config", "workspace.yaml");
+  if (!fs.existsSync(workspaceFile)) return null;
+  const yaml = yamlLibrary(workflowRoot);
   return { file: workspaceFile, configuration: yaml.parse(fs.readFileSync(workspaceFile, "utf8")) };
 }
 
@@ -253,7 +630,97 @@ function configuredCodeState(workflowRoot) {
   return code;
 }
 
+function workingTreeChecksum(repositoryRoot, relativePath) {
+  const absolute = path.resolve(repositoryRoot, ...relativePath.split("/"));
+  const relative = path.relative(repositoryRoot, absolute);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`Git path escapes the configured code repository: ${relativePath}`);
+  }
+  if (!fs.existsSync(absolute)) return null;
+  const stat = fs.lstatSync(absolute);
+  if (stat.isSymbolicLink()) return sha256Content(`symlink:${fs.readlinkSync(absolute)}`);
+  if (stat.isFile()) return sha256Content(fs.readFileSync(absolute));
+  return sha256Content(`non-file:${relativePath}`);
+}
+
+function captureCodeBaseline(workflowRoot) {
+  const code = configuredCodeState(workflowRoot);
+  if (!code.head) throw new Error("Configured code repository requires a HEAD before approving a change set.");
+  const dirtyFiles = code.dirty_paths
+    .map((relativePath) => ({
+      path: relativePath,
+      checksum: workingTreeChecksum(code.root, relativePath),
+    }))
+    .sort((left, right) => left.path.localeCompare(right.path));
+  const baseline = { code_commit: code.head.toLowerCase(), dirty_files: dirtyFiles };
+  return { ...baseline, subject_checksum: checksumJson(baseline) };
+}
+
+function approveChangeSet(candidate, openFindings, reviewSubjectBaseline, workflowRoot) {
+  const currentSubject = captureCodeBaseline(workflowRoot);
+  if (currentSubject.subject_checksum !== reviewSubjectBaseline.subject_checksum) {
+    throw new Error(
+      `Change set ${candidate.change_set_id} review subject changed during feedback collection.`,
+    );
+  }
+  const repairBaseline = reviewSubjectBaseline;
+  const feedbackCollection = {
+    subject_checksum: repairBaseline.subject_checksum,
+    review_axes: candidate.review_axes,
+    decision: candidate.collection_decision,
+    findings: [...openFindings].sort((left, right) => left.finding_id.localeCompare(right.finding_id)),
+  };
+  const collectionChecksum = checksumJson(feedbackCollection);
+  if (candidate.supplied_collection_checksum && candidate.supplied_collection_checksum !== collectionChecksum) {
+    throw new Error(
+      `Change set ${candidate.change_set_id} collection_checksum does not match the computed feedback collection.`,
+    );
+  }
+  return {
+    change_set_id: candidate.change_set_id,
+    feedback_collection: feedbackCollection,
+    collection_checksum: collectionChecksum,
+    repair_baseline: repairBaseline,
+    approval_actor: candidate.approval_actor,
+    rationale: candidate.rationale,
+    finding_ids: candidate.finding_ids,
+    allowed_files: candidate.allowed_files,
+    expected_evidence: candidate.expected_evidence,
+    approved_at: candidate.approved_at,
+  };
+}
+
+function gitPathList(cwd, args, label) {
+  const result = spawnSync("git", args, { cwd, encoding: "utf8", windowsHide: true });
+  if (result.status !== 0) {
+    throw new Error(`${label}: ${(result.stderr || result.error?.message || "Git command failed.").trim()}`);
+  }
+  return result.stdout.split("\0").filter(Boolean).map((item) => item.replaceAll("\\", "/"));
+}
+
+function repairChangesSinceBaseline(workflowRoot, baseline) {
+  const code = configuredCodeState(workflowRoot);
+  const committedOrTracked = gitPathList(
+    code.root,
+    ["diff", "--name-only", "-z", baseline.code_commit, "--"],
+    `Cannot compare the repair baseline ${baseline.code_commit}`,
+  );
+  const candidates = new Set([
+    ...committedOrTracked,
+    ...code.dirty_paths,
+    ...baseline.dirty_files.map((file) => file.path),
+  ]);
+  const baselineDirty = new Map(baseline.dirty_files.map((file) => [file.path, file.checksum]));
+  return [...candidates].filter((relativePath) => {
+    const currentChecksum = workingTreeChecksum(code.root, relativePath);
+    return baselineDirty.has(relativePath)
+      ? currentChecksum !== baselineDirty.get(relativePath)
+      : true;
+  }).sort((left, right) => left.localeCompare(right));
+}
+
 function writeSharedTask(runtime, workflowRoot, task) {
+  assertNotLegacyDevelopmentNode(task.node);
   const sharedFile = sharedTaskFile(workflowRoot, task.task_id);
   let previousRevision = 0;
   if (fs.existsSync(sharedFile)) {
@@ -313,22 +780,267 @@ function readTask(runtime, taskId) {
 function normalizeTask(task) {
   for (const key of [
     "scope", "input_artifacts", "standards", "planned_outputs", "actual_outputs",
-    "completed_steps", "blockers", "evidence", "depends_on",
+    "completed_steps", "blockers", "evidence", "depends_on", "acceptance",
   ]) {
     if (!Array.isArray(task[key])) task[key] = [];
     task[key] = [...new Set(task[key])];
   }
   task.sequence = parseSequence(task.sequence);
   task.next_action_owner = parseNextActionOwner(task.next_action_owner);
+  task.responsibility = task.responsibility || task.skill || "agent";
+  task.derived_from = task.derived_from || null;
+  task.supersedes = task.supersedes || null;
+  if (!Array.isArray(task.attempts)) {
+    const legacyNumber = Number(task.attempt || 0);
+    task.attempts = legacyNumber > 0 && (task.started_at || task.status !== "queued")
+      ? [normalizeAttempt(task.task_id, {
+        number: legacyNumber,
+        status: projectedTaskStatus(task.status, "attempt"),
+        started_at: task.started_at || task.created_at || null,
+        finished_at: CLOSED_STATUS.has(task.status) ? task.finished_at || task.updated_at || null : null,
+      }, legacyNumber)]
+      : [];
+  } else {
+    task.attempts = task.attempts.map((attempt, index) => normalizeAttempt(task.task_id, attempt, index + 1));
+  }
+  task.change_sets = Array.isArray(task.change_sets) ? task.change_sets.map((item) => normalizeChangeSet(item)) : [];
+  task.attempt = task.attempts.at(-1)?.number || 0;
   return task;
 }
 
+function logicalContract(task) {
+  return {
+    iteration_id: task.iteration_id,
+    node: task.node,
+    skill: task.skill,
+    goal: task.goal,
+    responsibility: task.responsibility,
+    scope: [...task.scope].sort(),
+    depends_on: [...task.depends_on].sort(),
+    acceptance: [...task.acceptance].sort(),
+  };
+}
+
+function logicalContractChanges(existing, candidate) {
+  const before = logicalContract(existing);
+  const after = logicalContract(candidate);
+  return Object.keys(before).filter((key) => JSON.stringify(before[key]) !== JSON.stringify(after[key]));
+}
+
+function currentAttempt(task) {
+  return task.attempts.at(-1) || null;
+}
+
+function createAttemptPhase(sequence, phase, timestamp) {
+  return {
+    sequence,
+    phase: parsePhase(phase, "implementation"),
+    status: "active",
+    started_at: timestamp,
+    finished_at: null,
+    findings: [],
+  };
+}
+
+function startAttempt(task, phase, timestamp) {
+  const number = (currentAttempt(task)?.number || 0) + 1;
+  const attempt = normalizeAttempt(task.task_id, {
+    number,
+    status: "active",
+    started_at: timestamp,
+    phases: [createAttemptPhase(1, phase, timestamp)],
+    time_entries: [],
+  }, number);
+  task.attempts.push(attempt);
+  task.attempt = number;
+  return attempt;
+}
+
+function enterAttemptPhase(attempt, phase, timestamp) {
+  const selected = parsePhase(phase, attempt.phases.at(-1)?.phase || "implementation");
+  let current = attempt.phases.at(-1);
+  if (!current || current.phase !== selected) {
+    if (current && current.status === "active") {
+      current.status = "completed";
+      current.finished_at = timestamp;
+    }
+    current = createAttemptPhase(attempt.phases.length + 1, selected, timestamp);
+    attempt.phases.push(current);
+  }
+  return current;
+}
+
+function recordAttemptProgress(task, args, taskStatus, finish, timestamp, workflowRoot) {
+  if (args["phase-status"] !== undefined) {
+    throw new Error("--phase-status is not supported; phase status is derived from the task transition.");
+  }
+  const priorFindings = new Map(currentFindings(task).map((finding) => [finding.finding_id, finding]));
+  let attempt = currentAttempt(task);
+  if (!attempt) attempt = startAttempt(task, args.phase, task.started_at || timestamp);
+  const phase = enterAttemptPhase(attempt, args.phase, timestamp);
+  if (phase.phase === "review" && !phase.review_subject_baseline) {
+    phase.review_subject_baseline = captureCodeBaseline(workflowRoot);
+  }
+  const submittedFindings = (args["finding-json"] || []).map(normalizeFinding);
+  const currentFindingStates = new Map(priorFindings);
+  for (const finding of submittedFindings) {
+    if (finding.status === "resolved" && !finding.change_set_id) {
+      throw new Error(`Resolved finding ${finding.finding_id} requires change_set_id.`);
+    }
+    if (finding.status === "resolved" && !finding.evidence.length) {
+      throw new Error(`Resolved finding ${finding.finding_id} requires evidence.`);
+    }
+    if (finding.status === "resolved" && priorFindings.get(finding.finding_id)?.status !== "open") {
+      throw new Error(`Resolved finding ${finding.finding_id} requires an existing open finding.`);
+    }
+    currentFindingStates.set(finding.finding_id, finding);
+  }
+  for (const rawChangeSet of args["change-set-json"] || []) {
+    if (phase.phase !== "review") {
+      throw new Error("Approved change sets must be recorded in the review phase.");
+    }
+    const candidate = normalizeChangeSet(rawChangeSet, timestamp);
+    if (task.change_sets.some((item) => item.change_set_id === candidate.change_set_id)) {
+      throw new Error(`Change set ${candidate.change_set_id} is already recorded and immutable.`);
+    }
+    const unavailable = candidate.finding_ids.filter((findingId) => currentFindingStates.get(findingId)?.status !== "open");
+    if (unavailable.length) {
+      throw new Error(`Change set ${candidate.change_set_id} requires open collected findings: ${unavailable.join(", ")}.`);
+    }
+    const openFindings = [...currentFindingStates.values()].filter((finding) => finding.status === "open");
+    const omitted = openFindings
+      .map((finding) => finding.finding_id)
+      .filter((findingId) => !candidate.finding_ids.includes(findingId));
+    if (omitted.length) {
+      throw new Error(
+        `Change set ${candidate.change_set_id} must include the complete feedback collection; missing: ${omitted.join(", ")}.`,
+      );
+    }
+    const changeSet = approveChangeSet(candidate, openFindings, phase.review_subject_baseline, workflowRoot);
+    task.change_sets.push(changeSet);
+  }
+  const approvedChangeSets = new Map(task.change_sets.map((item) => [item.change_set_id, item]));
+  for (const finding of submittedFindings) {
+    if (finding.status !== "resolved") continue;
+    const changeSet = approvedChangeSets.get(finding.change_set_id);
+    if (!changeSet) {
+      throw new Error(`Resolved finding ${finding.finding_id} references change set ${finding.change_set_id}, which is not approved.`);
+    }
+    if (!changeSet.finding_ids.includes(finding.finding_id)) {
+      throw new Error(`Resolved finding ${finding.finding_id} is not included in approved change set ${finding.change_set_id}.`);
+    }
+    if (phase.phase !== "review") {
+      throw new Error(`Resolved finding ${finding.finding_id} must be recorded during concentrated rereview.`);
+    }
+    if (!finding.changed_files?.length) {
+      throw new Error(`Resolved finding ${finding.finding_id} requires changed_files from its approved change set.`);
+    }
+    const actualChanges = repairChangesSinceBaseline(workflowRoot, changeSet.repair_baseline);
+    if (!sameStringSet(finding.changed_files, actualChanges)) {
+      const undeclared = actualChanges.filter((file) => !finding.changed_files.includes(file));
+      const notActual = finding.changed_files.filter((file) => !actualChanges.includes(file));
+      const details = [
+        ...(undeclared.length ? [`undeclared: ${undeclared.join(", ")}`] : []),
+        ...(notActual.length ? [`not actual: ${notActual.join(", ")}`] : []),
+      ].join("; ");
+      throw new Error(
+        `Resolved finding ${finding.finding_id} changed_files must exactly match actual Git changes since approval${details ? `; ${details}` : ""}.`,
+      );
+    }
+    const outsideFiles = finding.changed_files.filter((file) => !changeSet.allowed_files.includes(file));
+    if (outsideFiles.length) {
+      throw new Error(
+        `Resolved finding ${finding.finding_id} changed files outside approved change set ${finding.change_set_id}: ${outsideFiles.join(", ")}.`,
+      );
+    }
+    const missingEvidence = changeSet.expected_evidence.filter((item) => !finding.evidence.includes(item));
+    if (missingEvidence.length) {
+      throw new Error(
+        `Resolved finding ${finding.finding_id} is missing expected evidence for ${finding.change_set_id}: ${missingEvidence.join(", ")}.`,
+      );
+    }
+  }
+  phase.findings.push(...submittedFindings);
+  const elapsedMinutes = parseElapsedMinutes(args["elapsed-minutes"]);
+  const timeCategory = args["time-category"];
+  if ((elapsedMinutes === null) !== (timeCategory === undefined)) {
+    throw new Error("--time-category and --elapsed-minutes must be provided together.");
+  }
+  if (timeCategory !== undefined) {
+    if (!VALID_TIME_CATEGORY.has(timeCategory)) {
+      throw new Error(`Invalid time category: ${timeCategory}; use ${[...VALID_TIME_CATEGORY].join(", ")}.`);
+    }
+    attempt.time_entries.push({
+      category: timeCategory,
+      elapsed_minutes: elapsedMinutes,
+      phase: phase.phase,
+      recorded_at: timestamp,
+    });
+    attempt.time_by_category[timeCategory] = (attempt.time_by_category[timeCategory] || 0) + elapsedMinutes;
+  }
+  phase.status = finish ? projectedTaskStatus(taskStatus, "phase") : "active";
+  phase.finished_at = phase.status === "active" ? null : timestamp;
+  attempt.status = finish ? projectedTaskStatus(taskStatus, "attempt") : "active";
+  attempt.finished_at = new Set(["completed", "failed", "abandoned"]).has(attempt.status) ? timestamp : null;
+  return attempt;
+}
+
+function summarizeAttempts(task) {
+  const timeByCategory = {};
+  for (const attempt of task.attempts) {
+    for (const [category, minutes] of Object.entries(attempt.time_by_category || {})) {
+      timeByCategory[category] = (timeByCategory[category] || 0) + Number(minutes || 0);
+    }
+  }
+  return {
+    total: task.attempts.length,
+    active: task.attempts.filter((attempt) => attempt.status === "active").length,
+    paused: task.attempts.filter((attempt) => attempt.status === "paused").length,
+    completed: task.attempts.filter((attempt) => attempt.status === "completed").length,
+    failed: task.attempts.filter((attempt) => attempt.status === "failed").length,
+    abandoned: task.attempts.filter((attempt) => attempt.status === "abandoned").length,
+    current_attempt_id: currentAttempt(task)?.attempt_id || null,
+    current_phase: currentAttempt(task)?.phases.at(-1)?.phase || null,
+    time_by_category: timeByCategory,
+  };
+}
+
+function currentFindings(task) {
+  const findingsById = new Map();
+  for (const attempt of task.attempts) {
+    for (const phase of attempt.phases) {
+      for (const finding of phase.findings) findingsById.set(finding.finding_id, finding);
+    }
+  }
+  return [...findingsById.values()];
+}
+
+function assertNoOpenBlockingFindings(task) {
+  const blocking = currentFindings(task)
+    .filter((finding) => finding.severity === "blocking" && finding.status === "open")
+    .map((finding) => finding.finding_id);
+  if (blocking.length) {
+    throw new Error(`Task ${task.task_id} has open blocking findings: ${blocking.join(", ")}.`);
+  }
+}
+
 function stableValue(value) {
   if (Array.isArray(value)) return value.map(stableValue);
   if (!value || typeof value !== "object") return value;
   return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableValue(value[key])]));
 }
 
+function checksumJson(value) {
+  return sha256Content(JSON.stringify(stableValue(value)));
+}
+
+function sameStringSet(left, right) {
+  if (left.length !== right.length) return false;
+  const sortedLeft = [...left].sort();
+  const sortedRight = [...right].sort();
+  return sortedLeft.every((item, index) => item === sortedRight[index]);
+}
+
 function comparableTaskState(task) {
   const comparable = { ...task };
   const stateRoot = path.resolve(comparable.state_root || ".");
@@ -370,8 +1082,11 @@ function taskSources(runtime, workflowRoot, stateRoot, taskId) {
 
 function appendEvent(runtime, taskId, type, details = {}) {
   const file = path.join(runtime, "events", `${taskId}.jsonl`);
+  const previous = stagedContent(file)?.toString("utf8") || "";
+  const content = `${previous}${JSON.stringify({ at: now(), type, task_id: taskId, ...details })}\n`;
+  if (stageWrite(file, content)) return;
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.appendFileSync(file, `${JSON.stringify({ at: now(), type, task_id: taskId, ...details })}\n`, "utf8");
+  fs.writeFileSync(file, content, "utf8");
 }
 
 function copyIfExists(source, destination) {
@@ -393,7 +1108,9 @@ function clearTaskMarker(task) {
   if (!fs.existsSync(markerFile)) return;
   try {
     const marker = JSON.parse(fs.readFileSync(markerFile, "utf8"));
-    if (marker.task_id === task.task_id) fs.unlinkSync(markerFile);
+    if (marker.task_id === task.task_id) {
+      if (!stageDelete(markerFile)) fs.unlinkSync(markerFile);
+    }
   } catch {
     // Preserve an invalid marker for explicit reconciliation.
   }
@@ -446,12 +1163,87 @@ function copyTaskToPortableArchive(stateRoot, workflowRoot, task, archiveDirecto
   return portableTask;
 }
 
+function sha256Content(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function formalVersionArchiveReferences(stateRoot, workflowRoot, iterationId, requestedCandidateId) {
+  const stateCli = path.join(workflowRoot, "tools", "state", "state.mjs");
+  if (!fs.existsSync(stateCli)) {
+    throw new Error(`Formal-state CLI is missing: ${stateCli}`);
+  }
+  const command = [
+    stateCli,
+    "snapshot", "references",
+    "--project", stateRoot,
+    "--iteration-id", iterationId,
+  ];
+  if (requestedCandidateId) command.push("--candidate-id", requestedCandidateId);
+  const result = spawnSync(process.execPath, command, {
+    cwd: stateRoot,
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  if (result.status !== 0) {
+    const message = (result.stderr || result.error?.message || "Formal-state reference projection failed.")
+      .trim()
+      .replace(/^ai-delivery-state:\s*/, "");
+    throw new Error(message);
+  }
+  let projection;
+  try {
+    projection = JSON.parse(result.stdout);
+  } catch {
+    throw new Error("Formal-state reference projection returned invalid JSON.");
+  }
+  if (projection?.command !== "snapshot references" || !projection.references) {
+    throw new Error("Formal-state reference projection is incomplete.");
+  }
+  return projection.references;
+}
+
+function archivedTaskReferences(stateRoot, archivedTasks) {
+  const taskSummaries = [];
+  const attemptReceipts = [];
+  for (const task of archivedTasks) {
+    const taskRef = `${task.archive_path}/task.json`;
+    const taskFile = path.resolve(stateRoot, ...taskRef.split("/"));
+    taskSummaries.push({
+      task_id: task.task_id,
+      status: task.status,
+      finished_at: task.finished_at,
+      ref: taskRef,
+      checksum_algorithm: "sha256",
+      checksum: sha256Content(fs.readFileSync(taskFile)),
+    });
+    for (const [index, attempt] of (task.attempts || []).entries()) {
+      const receipt = stableValue({
+        task_id: task.task_id,
+        attempt_id: attempt.attempt_id,
+        number: attempt.number,
+        status: attempt.status,
+        started_at: attempt.started_at,
+        finished_at: attempt.finished_at,
+        phase_count: Array.isArray(attempt.phases) ? attempt.phases.length : 0,
+      });
+      attemptReceipts.push({
+        ...receipt,
+        ref: `${taskRef}#/attempts/${index}`,
+        checksum_algorithm: "sha256",
+        receipt_checksum: sha256Content(JSON.stringify(stableValue(attempt))),
+      });
+    }
+  }
+  return { task_summaries: taskSummaries, attempt_receipts: attemptReceipts };
+}
+
 function writeCheckpoint(runtime, task) {
   const stamp = now().replaceAll(":", "-");
   atomicWrite(path.join(runtime, "checkpoints", task.task_id, `${stamp}.json`), task);
 }
 
 function writeResume(runtime, task, reconciliation = null) {
+  const attemptSummary = summarizeAttempts(task);
   const lines = [
     `# Task Recovery: ${task.task_id}`,
     "",
@@ -459,6 +1251,9 @@ function writeResume(runtime, task, reconciliation = null) {
     "## Recorded State", "", `- Status: ${task.status}`, `- Node: ${task.node}`, `- Skill: ${task.skill}`,
     `- Sequence: ${task.sequence || "not recorded"}`,
     `- Dependencies: ${task.depends_on.length ? task.depends_on.join(", ") : "none"}`,
+    `- Attempts: ${attemptSummary.total}`,
+    `- Current attempt: ${attemptSummary.current_attempt_id || "not started"}`,
+    `- Current phase: ${attemptSummary.current_phase || "not started"}`,
     `- Next action owner: ${task.next_action_owner}`,
     `- Branch: ${task.branch || "not recorded"}`, `- Worktree: ${task.worktree || "not recorded"}`, "",
     "## Completed Work And Evidence", "",
@@ -473,6 +1268,7 @@ function writeResume(runtime, task, reconciliation = null) {
     lines.push("## Reconciled Workspace And Git State", "", "```json", JSON.stringify(reconciliation, null, 2), "```", "");
   }
   const file = path.join(runtime, "resumes", `${task.task_id}.md`);
+  if (stageWrite(file, `${lines.join("\n")}\n`)) return;
   fs.mkdirSync(path.dirname(file), { recursive: true });
   fs.writeFileSync(file, `${lines.join("\n")}\n`, "utf8");
 }
@@ -483,13 +1279,26 @@ function gitState(cwd) {
   if (root.status !== 0) return { repository: false };
   const branch = run(["branch", "--show-current"]);
   const head = run(["rev-parse", "HEAD"]);
-  const status = run(["status", "--porcelain=v1"]);
+  const status = run(["status", "--porcelain=v1", "-z", "--untracked-files=all"]);
+  const statusFields = status.stdout.split("\0");
+  const dirtyPaths = [];
+  for (let index = 0; index < statusFields.length; index += 1) {
+    const record = statusFields[index];
+    if (!record) continue;
+    const state = record.slice(0, 2);
+    dirtyPaths.push(record.slice(3).replaceAll("\\", "/"));
+    if (state.includes("R") || state.includes("C")) {
+      const source = statusFields[index + 1];
+      if (source) dirtyPaths.push(source.replaceAll("\\", "/"));
+      index += 1;
+    }
+  }
   return {
     repository: true,
     root: root.stdout.trim(),
     branch: branch.stdout.trim(),
     head: head.status === 0 ? head.stdout.trim() : null,
-    dirty_paths: status.stdout.split(/\r?\n/).filter(Boolean).map((line) => line.slice(3)),
+    dirty_paths: [...new Set(dirtyPaths)].sort((left, right) => left.localeCompare(right)),
   };
 }
 
@@ -507,6 +1316,19 @@ function readRuntimeTasks(runtime) {
     .map((name) => normalizeTask(JSON.parse(fs.readFileSync(path.join(tasksDir, name), "utf8"))));
 }
 
+function readReconciledTasks(runtime, workflowRoot, stateRoot) {
+  const localById = new Map(readRuntimeTasks(runtime).map((task) => [task.task_id, task]));
+  const sharedById = new Map(readSharedTasks(workflowRoot, stateRoot).map((task) => [task.task_id, task]));
+  const taskIds = [...new Set([...localById.keys(), ...sharedById.keys()])].sort();
+  const tasks = taskIds.map((taskId) => {
+    const local = localById.get(taskId) || null;
+    const shared = sharedById.get(taskId) || null;
+    if (local && shared) assertTaskSourcesMatch(local, shared);
+    return local || shared;
+  });
+  return { localById, sharedById, tasks };
+}
+
 function dependencyState(task, tasksById) {
   const missing = [];
   const incomplete = [];
@@ -526,19 +1348,24 @@ function summarizeIteration(tasks, iterationId) {
   const completed = iterationTasks.filter((task) => task.status === "completed");
   const closed = iterationTasks.filter((task) => CLOSED_STATUS.has(task.status));
   const active = iterationTasks.filter((task) => RESUMABLE_STATUS.has(task.status));
+  const retryable = iterationTasks.filter((task) => task.status === "failed");
   const queued = iterationTasks.filter((task) => task.status === "queued");
   const ready = queued.filter((task) => dependencyState(task, tasksById).satisfied);
   const waiting = queued
     .filter((task) => !ready.includes(task))
     .map((task) => ({ task_id: task.task_id, ...dependencyState(task, tasksById) }));
-  const recommended = [...active, ...ready].sort(compareTasks)[0] || null;
+  const recommended = active.sort(compareTasks)[0]
+    || retryable.sort(compareTasks)[0]
+    || ready.sort(compareTasks)[0]
+    || null;
   return {
     iteration_id: iterationId,
     total_tasks: iterationTasks.length,
     completed_tasks: completed.length,
     closed_tasks: closed.length,
-    remaining_tasks: iterationTasks.length - closed.length,
+    remaining_tasks: iterationTasks.filter((task) => !RECOVERY_COMPLETE_STATUS.has(task.status)).length,
     active_task_ids: active.map((task) => task.task_id),
+    retryable_task_ids: retryable.map((task) => task.task_id),
     queued_task_ids: queued.map((task) => task.task_id),
     ready_task_ids: ready.map((task) => task.task_id),
     waiting_tasks: waiting,
@@ -552,6 +1379,7 @@ function summarizeIteration(tasks, iterationId) {
 function commandInit(args) {
   const taskId = sanitizeId(requireValue(args, "task-id"));
   const iterationId = sanitizeId(requireValue(args, "iteration-id"));
+  const node = assertNotLegacyDevelopmentNode(requireValue(args, "node"));
   const { projectRoot, stateRoot, workflowRoot, runtime } = statePaths(args);
   return withTaskLock(runtime, `version.${iterationId}`, () => withTaskLock(runtime, taskId, () => {
     if (fs.existsSync(archivedTaskIndexFile(runtime, taskId))) {
@@ -561,32 +1389,83 @@ function commandInit(args) {
       throw new Error(`Version is already archived and cannot accept new tasks: ${iterationId}`);
     }
     const file = taskFile(runtime, taskId);
-    const existing = fs.existsSync(file)
+    const local = fs.existsSync(file)
       ? normalizeTask(JSON.parse(fs.readFileSync(file, "utf8")))
       : null;
+    const shared = readSharedTasks(workflowRoot, stateRoot).find((item) => item.task_id === taskId) || null;
+    if (local && shared) assertTaskSourcesMatch(local, shared);
+    const existing = local || shared;
     if (existing && existing.iteration_id !== iterationId) {
       throw new Error(`Task ${taskId} already belongs to iteration ${existing.iteration_id}`);
     }
-    const shared = readSharedTasks(workflowRoot, stateRoot).find((item) => item.task_id === taskId);
-    if (existing && shared) assertTaskSourcesMatch(existing, shared);
     if (existing) assertWaitStateTransfer(existing, args, "init");
-    const status = args.status || "preparing";
+    const status = args.status || "queued";
+    if (!VALID_STATUS.has(status)) throw new Error(`Invalid status: ${status}`);
+    if (CLOSED_STATUS.has(status)) {
+      throw new Error(`init cannot set closed status ${status}; initialize, activate, and finish the task instead.`);
+    }
+    if (status !== "queued") {
+      throw new Error(`init creates queued tasks only, not ${status}; use activate to start the task.`);
+    }
     const dependsOn = (args["depends-on"] || existing?.depends_on || []).map(sanitizeId);
     if (dependsOn.includes(taskId)) throw new Error(`Task cannot depend on itself: ${taskId}`);
-    const timestamp = now();
-    const task = {
+    const responsibility = args.responsibility || existing?.responsibility || requireValue(args, "skill");
+    const contractFields = {
       task_id: taskId,
       iteration_id: iterationId,
-      node: requireValue(args, "node"),
+      node,
       skill: requireValue(args, "skill"),
-      status,
-      sequence: parseSequence(args.sequence ?? existing?.sequence),
-      depends_on: dependsOn,
-      attempt: existing ? Number(existing.attempt || 0) + 1 : 1,
       goal: requireValue(args, "goal"),
+      responsibility,
       scope: args.scope || existing?.scope || [],
+      depends_on: dependsOn,
+      acceptance: args.acceptance || existing?.acceptance || [],
+    };
+    const candidateContract = normalizeTask({
+      ...(existing || {}),
+      ...contractFields,
+      next_action_owner: existing?.next_action_owner || "agent",
+    });
+    if (existing) {
+      const changed = logicalContractChanges(existing, candidateContract);
+      if (changed.length) {
+        throw new Error(
+          `Logical task contract changed for ${taskId}: ${changed.join(", ")}. Use a new task ID and link it with --derived-from or --supersedes.`,
+        );
+      }
+      return { ...existing, idempotent: true };
+    }
+    const knownTasks = readReconciledTasks(runtime, workflowRoot, stateRoot).tasks;
+    const duplicateContract = knownTasks.find((task) => logicalContractChanges(task, candidateContract).length === 0);
+    if (duplicateContract) {
+      throw new Error(
+        `Task ${taskId} has the same logical contract as ${duplicateContract.task_id}; reuse ${duplicateContract.task_id}.`,
+      );
+    }
+    const derivedFrom = args["derived-from"] && args["derived-from"] !== true
+      ? sanitizeId(args["derived-from"])
+      : null;
+    const supersedes = args.supersedes && args.supersedes !== true ? sanitizeId(args.supersedes) : null;
+    if (derivedFrom && supersedes) throw new Error("Use only one of --derived-from or --supersedes.");
+    if (derivedFrom === taskId || supersedes === taskId) throw new Error(`Task ${taskId} cannot relate to itself.`);
+    const relationTarget = derivedFrom || supersedes;
+    if (relationTarget) {
+      const known = knownTasks.some((task) => task.task_id === relationTarget)
+        || fs.existsSync(archivedTaskIndexFile(runtime, relationTarget));
+      if (!known) throw new Error(`Related task not found: ${relationTarget}`);
+    }
+    const timestamp = now();
+    const task = {
+      ...contractFields,
+      status,
+      sequence: parseSequence(args.sequence ?? existing?.sequence),
+      attempt: 0,
+      attempts: [],
+      change_sets: [],
       input_artifacts: args["input-artifact"] || existing?.input_artifacts || [],
       standards: args.standard || existing?.standards || [],
+      derived_from: derivedFrom,
+      supersedes,
       branch: args.branch || existing?.branch || null,
       worktree: path.resolve(args.worktree || projectRoot),
       state_root: stateRoot,
@@ -598,19 +1477,19 @@ function commandInit(args) {
       next_action_owner: parseNextActionOwner(args["next-action-owner"], existing?.next_action_owner),
       evidence: existing?.evidence || [],
       created_at: existing?.created_at || timestamp,
-      started_at: status === "queued" ? existing?.started_at || null : existing?.started_at || timestamp,
+      started_at: null,
       updated_at: timestamp,
-      finished_at: CLOSED_STATUS.has(status) ? existing?.finished_at || timestamp : null,
+      finished_at: null,
     };
-    if (!VALID_STATUS.has(task.status)) throw new Error(`Invalid status: ${task.status}`);
     writeSharedTask(runtime, workflowRoot, task);
     writeResume(runtime, task);
-    if (RESUMABLE_STATUS.has(status)) {
-      atomicWrite(taskMarkerFile(stateRoot), { task_id: taskId, state_root: stateRoot });
-    } else {
-      clearTaskMarker(task);
-    }
-    appendEvent(runtime, taskId, "task-initialized", { status: task.status, attempt: task.attempt });
+    clearTaskMarker(task);
+    appendEvent(runtime, taskId, "task-initialized", {
+      status: task.status,
+      attempt: task.attempt,
+      derived_from: task.derived_from,
+      supersedes: task.supersedes,
+    });
     return task;
   }));
 }
@@ -634,7 +1513,14 @@ function commandActivate(args) {
     const currentSources = taskSources(runtime, workflowRoot, stateRoot, taskId);
     const task = currentSources.task;
     if (!task) throw new Error(`Task not found: ${taskId}`);
-    if (!new Set(["queued", "preparing", "checkpointed", "blocked", "interrupted"]).has(task.status)) {
+    const newAttempt = Boolean(args["new-attempt"]);
+    if (task.status === "failed" && !newAttempt) {
+      throw new Error(`Task ${taskId} failed; retry the same logical task with --new-attempt.`);
+    }
+    if (newAttempt && task.status !== "failed") {
+      throw new Error(`--new-attempt is only valid when retrying a failed logical task; ${taskId} is ${task.status}.`);
+    }
+    if (!new Set(["queued", "preparing", "checkpointed", "blocked", "interrupted", "failed"]).has(task.status)) {
       throw new Error(`Task ${taskId} cannot be activated from status ${task.status}`);
     }
     const sharedTasks = readSharedTasks(workflowRoot, stateRoot);
@@ -660,11 +1546,20 @@ function commandActivate(args) {
     if (task.next_action_owner === "agent" && requestedOwner && requestedOwner !== "agent") {
       throw new Error("activate --next-action-owner may only be agent; use checkpoint or finish to enter a wait state.");
     }
-    const firstStart = !task.started_at;
+    const timestamp = now();
     task.status = status;
-    task.attempt = firstStart ? Number(task.attempt || 1) : Number(task.attempt || 0) + 1;
-    task.started_at ||= now();
-    task.updated_at = now();
+    let attempt = currentAttempt(task);
+    if (!attempt || newAttempt) attempt = startAttempt(task, args.phase, timestamp);
+    else {
+      attempt.status = "active";
+      attempt.finished_at = null;
+      const phase = enterAttemptPhase(attempt, args.phase, timestamp);
+      phase.status = "active";
+      phase.finished_at = null;
+    }
+    task.attempt = attempt.number;
+    task.started_at ||= timestamp;
+    task.updated_at = timestamp;
     task.finished_at = null;
     task.blockers = [];
     if (args["next-action"] && args["next-action"] !== true) task.next_action = args["next-action"];
@@ -676,7 +1571,13 @@ function commandActivate(args) {
       iteration_id: task.iteration_id,
       state_root: task.state_root,
     });
-    appendEvent(runtime, taskId, "task-activated", { status, attempt: task.attempt });
+    appendEvent(runtime, taskId, "task-activated", {
+      status,
+      attempt: task.attempt,
+      attempt_id: attempt.attempt_id,
+      phase: attempt.phases.at(-1)?.phase || null,
+      new_attempt: newAttempt,
+    });
     return task;
   }));
 }
@@ -691,12 +1592,21 @@ function commandUpdate(args, finish = false) {
     const task = readTask(runtime, taskId);
     const shared = readSharedTasks(workflowRoot, stateRoot).find((item) => item.task_id === taskId);
     if (shared) assertTaskSourcesMatch(task, shared);
+    if (!RESUMABLE_STATUS.has(task.status)) {
+      throw new Error(`Task ${taskId} is ${task.status}; activate it before checkpoint or finish.`);
+    }
     const requestedOwner = assertWaitStateTransfer(task, args, finish ? "finish" : "checkpoint");
     const status = requireValue(args, "status");
     if (!VALID_STATUS.has(status)) throw new Error(`Invalid status: ${status}`);
     if (finish && !FINISH_STATUS.has(status)) {
       throw new Error(`finish requires one of: ${[...FINISH_STATUS].join(", ")}`);
     }
+    if (!finish && CLOSED_STATUS.has(status)) {
+      throw new Error(`checkpoint cannot set closed status ${status}; use finish instead.`);
+    }
+    if (!finish && status === "queued") {
+      throw new Error("checkpoint cannot return an activated task to queued; queued tasks must be started through activate.");
+    }
     task.status = status;
     task.next_action = requireValue(args, "next-action");
     task.next_action_owner = requestedOwner || task.next_action_owner;
@@ -708,16 +1618,54 @@ function commandUpdate(args, finish = false) {
     for (const output of args["actual-output"] || []) {
       if (!task.actual_outputs.includes(output)) task.actual_outputs.push(output);
     }
-    task.updated_at = now();
-    task.finished_at = finish ? now() : null;
+    const timestamp = now();
+    const attempt = recordAttemptProgress(task, args, status, finish, timestamp, workflowRoot);
+    if (finish && status === "completed") assertNoOpenBlockingFindings(task);
+    task.updated_at = timestamp;
+    task.finished_at = finish ? timestamp : null;
     writeSharedTask(runtime, workflowRoot, task);
     writeResume(runtime, task);
-    appendEvent(runtime, taskId, finish ? "task-finished" : "task-checkpointed", { status });
+    appendEvent(runtime, taskId, finish ? "task-finished" : "task-checkpointed", {
+      status,
+      attempt: attempt.number,
+      attempt_id: attempt.attempt_id,
+      phase: attempt.phases.at(-1)?.phase || null,
+    });
     if (finish && CLOSED_STATUS.has(status)) clearTaskMarker(task);
     return task;
   });
 }
 
+function commandInspect(args) {
+  const { runtime, workflowRoot, stateRoot } = statePaths(args);
+  const requestedTask = args["task-id"] ? sanitizeId(args["task-id"]) : null;
+  const requestedIteration = args["iteration-id"] ? sanitizeId(args["iteration-id"]) : null;
+  const includeClosed = Boolean(args["include-closed"]);
+  const { localById, sharedById, tasks: allTasks } = readReconciledTasks(runtime, workflowRoot, stateRoot);
+  if (requestedTask && !allTasks.some((task) => task.task_id === requestedTask)) {
+    throw new Error(`Task not found: ${requestedTask}`);
+  }
+  const tasksById = new Map(allTasks.map((task) => [task.task_id, task]));
+  const selected = allTasks
+    .filter((task) => !requestedTask || task.task_id === requestedTask)
+    .filter((task) => !requestedIteration || task.iteration_id === requestedIteration)
+    .filter((task) => includeClosed || !CLOSED_STATUS.has(task.status))
+    .sort(compareTasks);
+  const iterationIds = [...new Set(selected.map((task) => task.iteration_id))].sort();
+  return {
+    read_only: true,
+    tasks: selected.map((task) => ({
+      task,
+      source: localById.has(task.task_id) && sharedById.has(task.task_id)
+        ? "local-and-shared"
+        : localById.has(task.task_id) ? "local" : "shared",
+      dependency_state: dependencyState(task, tasksById),
+      attempt_summary: summarizeAttempts(task),
+    })),
+    iterations: iterationIds.map((iterationId) => summarizeIteration(allTasks, iterationId)),
+  };
+}
+
 function commandArchiveVersion(args) {
   const { runtime, stateRoot, workflowRoot } = statePaths(args);
   const iterationId = sanitizeId(requireValue(args, "iteration-id"));
@@ -748,6 +1696,7 @@ function commandArchiveVersion(args) {
       .map((name) => normalizeTask(JSON.parse(fs.readFileSync(path.join(tasksDir, name), "utf8"))))
       .filter((task) => task.iteration_id === iterationId);
     if (!tasks.length) throw new Error(`No tasks found for version: ${iterationId}`);
+    for (const task of tasks) assertNotLegacyDevelopmentNode(task.node);
     const sharedById = new Map(readSharedTasks(workflowRoot, stateRoot).map((task) => [task.task_id, task]));
     for (const task of tasks) {
       const shared = sharedById.get(task.task_id);
@@ -758,6 +1707,9 @@ function commandArchiveVersion(args) {
     if (notClosed.length) {
       throw new Error(`Version ${iterationId} is not closed; active tasks: ${notClosed.map((task) => `${task.task_id}:${task.status}`).join(", ")}`);
     }
+    const formalReferences = formalVersionArchiveReferences(
+      stateRoot, workflowRoot, iterationId, candidateId,
+    );
 
     const archivedAt = now();
     const writeRuntimeArchive = !Boolean(args["portable-only"]);
@@ -767,6 +1719,7 @@ function commandArchiveVersion(args) {
     }
     const archivedTasks = tasks.map((task) =>
       copyTaskToPortableArchive(stateRoot, workflowRoot, task, portableArchiveDirectory, archivedAt));
+    const taskReferences = archivedTaskReferences(stateRoot, archivedTasks);
     const relativeArchive = path.relative(stateRoot, portableArchiveDirectory).replaceAll("\\", "/");
     const manifest = {
       iteration_id: iterationId,
@@ -777,6 +1730,13 @@ function commandArchiveVersion(args) {
       task_count: archivedTasks.length,
       archived_at: archivedAt,
       archive_path: relativeArchive,
+      references: {
+        ...taskReferences,
+        history_anchor: formalReferences?.history_anchor || null,
+        scope: formalReferences?.scope || null,
+        candidate: formalReferences?.candidate || null,
+        gates: formalReferences?.gates || [],
+      },
       tasks: archivedTasks.map((task) => ({
         task_id: task.task_id,
         node: task.node,
@@ -816,11 +1776,12 @@ function commandRecover(args) {
   const includeClosed = Boolean(args["include-closed"]);
   const localTasks = readRuntimeTasks(runtime);
   const localById = new Map(localTasks.map((task) => [task.task_id, task]));
+  const missingLocalTaskIds = new Set();
   for (const shared of readSharedTasks(workflowRoot, stateRoot)) {
     const local = localById.get(shared.task_id);
     if (!local) {
       localById.set(shared.task_id, shared);
-      if (shared.next_action_owner === "agent") atomicWrite(taskFile(runtime, shared.task_id), shared);
+      if (shared.next_action_owner === "agent") missingLocalTaskIds.add(shared.task_id);
     } else {
       assertTaskSourcesMatch(local, shared);
     }
@@ -831,10 +1792,15 @@ function commandRecover(args) {
     ? allTasks.filter((task) => task.iteration_id === requestedIteration)
     : allTasks;
   const iterationIds = [...new Set(selectedTasks.map((task) => task.iteration_id))].sort();
+  const reportableTasks = selectedTasks
+    .filter((task) => !requested || task.task_id === requested)
+    .filter((task) => includeClosed || !RECOVERY_COMPLETE_STATUS.has(task.status));
+  for (const task of reportableTasks) assertNotLegacyDevelopmentNode(task.node);
+  for (const task of reportableTasks) {
+    if (missingLocalTaskIds.has(task.task_id)) atomicWrite(taskFile(runtime, task.task_id), task);
+  }
   const reports = [];
-  for (const task of selectedTasks.sort(compareTasks)) {
-    if (requested && task.task_id !== requested) continue;
-    if (!includeClosed && CLOSED_STATUS.has(task.status)) continue;
+  for (const task of reportableTasks.sort(compareTasks)) {
     const heartbeatFile = path.join(runtime, "heartbeats", `${task.task_id}.json`);
     const heartbeat = fs.existsSync(heartbeatFile) ? JSON.parse(fs.readFileSync(heartbeatFile, "utf8")) : null;
     const latest = new Date(heartbeat?.updated_at || task.updated_at).getTime();
@@ -886,6 +1852,8 @@ function commandPublish(args) {
   const sharedFile = sharedTaskFile(workflowRoot, taskId);
   const checkpointDirectory = path.join(workflowRoot, "control", "checkpoints", taskId);
   if (!fs.existsSync(sharedFile)) throw new Error(`Shared task state not found: ${taskId}`);
+  const shared = JSON.parse(fs.readFileSync(sharedFile, "utf8"));
+  assertNotLegacyDevelopmentNode(shared.node);
 
   const repository = gitState(stateRoot);
   if (!repository.repository || path.resolve(repository.root).toLowerCase() !== path.resolve(stateRoot).toLowerCase()) {
@@ -926,7 +1894,6 @@ function commandPublish(args) {
   if (upstream.status === 0 && upstream.stdout.trim() !== `origin/${expectedBranch}`) {
     throw new Error(`Workflow upstream must be origin/${expectedBranch}, found ${upstream.stdout.trim()}.`);
   }
-  const shared = JSON.parse(fs.readFileSync(sharedFile, "utf8"));
   const workflowDocumentRoot = path.join(stateRoot, ".workflow");
   const taskOwnedArtifacts = [...(shared.actual_outputs || []), ...(shared.evidence || [])]
     .map((value) => String(value).replaceAll("\\", "/"))
@@ -1007,6 +1974,32 @@ function taskEvolutionContext(args, command) {
   };
 }
 
+function assertWritableEvolutionTarget(args, command) {
+  if (!new Set(["init", "activate", "checkpoint", "finish", "archive-version"]).has(command)) return;
+  if (command === "init") {
+    const node = args.node && args.node !== true ? String(args.node) : null;
+    if (node) assertNotLegacyDevelopmentNode(node);
+    return;
+  }
+  const { runtime, workflowRoot, stateRoot } = statePaths(args);
+  if (command === "archive-version") {
+    const iterationId = args["iteration-id"] && args["iteration-id"] !== true
+      ? sanitizeId(args["iteration-id"])
+      : null;
+    const tasksDir = path.join(runtime, "tasks");
+    if (!iterationId || !fs.existsSync(tasksDir)) return;
+    for (const name of fs.readdirSync(tasksDir).filter((item) => item.endsWith(".json"))) {
+      const task = normalizeTask(JSON.parse(fs.readFileSync(path.join(tasksDir, name), "utf8")));
+      if (task.iteration_id === iterationId) assertNotLegacyDevelopmentNode(task.node);
+    }
+    return;
+  }
+  const taskId = args["task-id"] && args["task-id"] !== true ? sanitizeId(args["task-id"]) : null;
+  if (!taskId) return;
+  const task = taskSources(runtime, workflowRoot, stateRoot, taskId).task;
+  if (task) assertNotLegacyDevelopmentNode(task.node);
+}
+
 function dispatchTaskEvolution(context, phase, result = null, error = null) {
   if (!context) return { decision: "pass" };
   const identity = context.taskId || context.iterationId || "unspecified";
@@ -1049,24 +2042,66 @@ function dispatchTaskEvolution(context, phase, result = null, error = null) {
 
 const args = parseArgs(process.argv.slice(2));
 const command = args._[0];
-const evolutionContext = taskEvolutionContext(args, command);
+let evolutionContext = null;
 try {
+  assertWritableEvolutionTarget(args, command);
+  evolutionContext = taskEvolutionContext(args, command);
   const before = dispatchTaskEvolution(evolutionContext, "before");
   if (before.decision === "block") {
     throw new Error(`Evolution Hook blocked ${command}: ${(before.messages || []).join("; ") || "no rationale"}`);
   }
+  let managerTransactionDescriptor = null;
+  if (args["manager-transaction"]) {
+    if (!new Set(["init", "activate", "checkpoint", "finish"]).has(command)) {
+      throw new Error("Manager task transaction is limited to task mutation commands");
+    }
+    try {
+      managerTransactionDescriptor = JSON.parse(fs.readFileSync(0, "utf8"));
+    } catch {
+      throw new Error("Manager task transaction descriptor must be valid JSON");
+    }
+    activeWriteTransaction = { entries: new Map() };
+  }
   let result;
   if (command === "init") result = commandInit(args);
   else if (command === "activate") result = commandActivate(args);
   else if (command === "checkpoint") result = commandUpdate(args, false);
   else if (command === "finish") result = commandUpdate(args, true);
+  else if (command === "inspect") result = commandInspect(args);
   else if (command === "archive-version") result = commandArchiveVersion(args);
   else if (command === "recover") result = commandRecover(args);
   else if (command === "publish") result = commandPublish(args);
-  else throw new Error("Use init, activate, checkpoint, finish, archive-version, recover, or publish.");
+  else throw new Error("Use init, activate, checkpoint, finish, inspect, archive-version, recover, or publish.");
+  if (managerTransactionDescriptor) {
+    const managerRuntime = path.join(
+      path.resolve(args["state-root"] || args.root || findProjectRoot()),
+      ".workflow", "tools", "manager", "workflow-manager-transaction.mjs",
+    );
+    if (!fs.existsSync(managerRuntime)) {
+      throw new Error(`Workflow Manager transaction runtime is missing: ${managerRuntime}`);
+    }
+    const { prepareWorkflowManagerTaskTransactionWrites } = await import(pathToFileURL(managerRuntime).href);
+    const prepared = prepareWorkflowManagerTaskTransactionWrites(
+      path.resolve(args["state-root"] || args.root || findProjectRoot()),
+      managerTransactionDescriptor,
+      result,
+    );
+    for (const write of prepared.writes) stageWrite(write.file, write.content);
+    commitWriteTransaction();
+    result = {
+      ...result,
+      manager_transaction: {
+        outcome: prepared.outcome,
+        result: prepared.result,
+        receipt: prepared.receipt,
+        event: prepared.event,
+      },
+    };
+  }
   dispatchTaskEvolution(evolutionContext, "after", result);
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
 } catch (error) {
+  activeWriteTransaction = null;
   dispatchTaskEvolution(evolutionContext, "failed", null, error);
   process.stderr.write(`${error.message}\n`);
   process.exitCode = 1;