ai-delivery-workflow 0.5.0 → 0.6.0

package/lib/project-installer.mjs

@@ -8,11 +8,10 @@ import { fileURLToPath } from "node:url";
 import { isSeq, parse as parseYaml, parseDocument, stringify as stringifyYaml } from "yaml";
 import { assertPathInside, atomicWrite, filesUnder } from "./fs-utils.mjs";
 import { inspectCodeGraph } from "./codegraph.mjs";
+import { inspectCodebaseDocumentation, inspectConfirmationSummaries } from "./project-bootstrap.mjs";
 import { executeDeliveryStateCommand } from "./delivery-state.mjs";
-import { planPrototypeMigration } from "./prototype-migration.mjs";
 import { inspectHookConfig, managedHookConfigProjection, mergeHookConfig } from "./toml-hooks.mjs";
 import {
-  LEGACY_WORKSPACE_CONFIG,
   WORKSPACE_CONFIG,
   gitCommonDirectory,
   gitTopLevel,
@@ -39,7 +38,6 @@ const GIT_ATTRIBUTE_ENTRIES = [
   "/.gitattributes text eol=lf",
   ...RAW_GIT_ATTRIBUTE_TARGETS.map((file) => `/${file} -text`),
 ];
-const OBSOLETE_IGNORE_ENTRIES = new Set([".ai-delivery-task", ".ai-delivery/backups/"]);
 const INSTALL_MANIFEST = path.join(".workflow", "config", "install-manifest.json");
 const UPGRADE_RUNTIME = path.join(".workflow", "delivery", "runtime", "upgrades");
 const PRESERVED_DETAIL_LIMIT = 200;
@@ -48,32 +46,18 @@ const DOCTOR_ATTRIBUTE_BATCH_SIZE = 5_000;
 const DOCTOR_DETAIL_LIMIT = 200;
 const FORMAL_STATE_INSPECT_MAX_BUFFER = 16 * 1024 * 1024;
 const INSTALL_MANIFEST_SCHEMA = 6;
-const UI_CONTRACT_VERSION = "prototype-first-ui-v1";
-const FORMAL_STATE_YAML = {
-  parse: parseYaml,
-  stringify: (value) => stringifyYaml(value, { lineWidth: 0 }),
-};
 const MERGED_MANAGED_SURFACES = Object.freeze([
   { key: "agents", path: "AGENTS.md" },
   { key: "hook_config", path: ".codex/config.toml" },
   { key: "gitignore", path: ".gitignore" },
   { key: "gitattributes", path: ".gitattributes" },
 ]);
-const ACTIVE_TASK = path.join(".workflow", "delivery", "runtime", "active-task.json");
-const LEGACY_ACTIVE_TASK = ".ai-delivery-task";
 const WORKFLOW_CONTENT_DIRECTORIES = ["product", "architecture", "experience", "iterations", "releases"];
 const CONTROL_DIRECTORIES = [
   "tasks", "checkpoints", "artifacts", "gates", "versions", "releases", "events", "archives",
-  "migrations", "repairs",
+  "repairs",
 ];
-const ENSURED_CONTROL_DIRECTORIES = ["migrations", "repairs"];
-const RETIRED_MANAGED_ASSETS = Object.freeze([
-  {
-    path: ".workflow/tools/viewer",
-    kind: "retired-directory",
-    manifest_key: "viewer",
-  },
-]);
+const ENSURED_CONTROL_DIRECTORIES = ["repairs"];
 const ESSENTIAL_STARTUP_SKILLS = [
   "ai-delivery-assemble-release",
   "ai-delivery-bootstrap",
@@ -138,11 +122,9 @@ const V2_PROTOTYPE_DELIVERY_SURFACE_FILES = Object.freeze([
 const REQUIRED_PACKAGE_SURFACE_FILES = Object.freeze([
   "LICENSE",
   "bin/ai-delivery.mjs",
-  "docs/PROTOTYPE-MIGRATION.zh-CN.md",
   "lib/mock-scenario-pack.mjs",
   "lib/mock-system.mjs",
-  "lib/project-migration.mjs",
-  "lib/prototype-migration.mjs",
+  "lib/project-repair.mjs",
   "lib/prototype-page-review.mjs",
   "lib/prototype-review-target.mjs",
   "skills/ai-delivery-checkpoint-task/scripts/hook-event.mjs",
@@ -344,8 +326,7 @@ function mergeManagedMarkdown(existing, managedTemplate) {
 }
 
 function mergeGitignore(existing, requiredEntries = []) {
-  const lines = existing.split(/\r?\n/)
-    .filter((line) => !OBSOLETE_IGNORE_ENTRIES.has(line.trim()));
+  const lines = existing.split(/\r?\n/);
   const additions = [...IGNORE_ENTRIES, ...requiredEntries]
     .filter((entry) => !lines.some((line) => line.trim() === entry));
   const retained = lines.join("\n").trimEnd();
@@ -542,7 +523,7 @@ function bootstrapRuntimeSources(packageRoot, sourceTemplate) {
       relative: "bootstrap.mjs",
     },
     ...[
-      "project-bootstrap.mjs", "workspace.mjs", "yaml-runtime.mjs", "delivery-state.mjs",
+      "project-bootstrap.mjs", "communication-confirmation.mjs", "workspace.mjs", "yaml-runtime.mjs", "delivery-state.mjs",
       "history-anchor.mjs", "fs-utils.mjs",
     ].map((name) => ({
       source: path.join(packageRoot, "lib", name),
@@ -706,7 +687,7 @@ function mergedSurfaceManagedDigest(key, text, codePath) {
   if (key === "hook_config") return contentDigest(JSON.stringify(managedHookConfigProjection(text)));
   const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
   if (key === "gitignore") {
-    const managedEntries = new Set([...IGNORE_ENTRIES, `/${codePath}/`, ...OBSOLETE_IGNORE_ENTRIES]);
+    const managedEntries = new Set([...IGNORE_ENTRIES, `/${codePath}/`]);
     return contentDigest(JSON.stringify(lines.filter((line) => managedEntries.has(line)).sort()));
   }
   return contentDigest(JSON.stringify(lines.filter((line) => GIT_ATTRIBUTE_ENTRIES.includes(line)).sort()));
@@ -868,10 +849,11 @@ export function initProject(packageRoot, target, options = {}) {
     "backups",
     new Date().toISOString().replaceAll(":", "-"),
   );
-  const legacyRoot = path.join(target, ".ai-delivery");
-  const legacyActiveTask = path.join(target, LEGACY_ACTIVE_TASK);
-  const hasLegacyRoot = fs.existsSync(legacyRoot);
-  const hasLegacyActiveTask = fs.existsSync(legacyActiveTask);
+  const unsupportedRoot = path.join(target, ".ai-delivery");
+  const unsupportedActiveTask = path.join(target, ".ai-delivery-task");
+  if (fs.existsSync(unsupportedRoot) || fs.existsSync(unsupportedActiveTask)) {
+    throw new Error("Unsupported workflow layout detected; install requires the current .workflow contract.");
+  }
   let previousManifest = null;
   try {
     previousManifest = JSON.parse(fs.readFileSync(path.join(target, INSTALL_MANIFEST), "utf8"));
@@ -889,24 +871,9 @@ export function initProject(packageRoot, target, options = {}) {
     throw new Error(`Refusing package downgrade from ${previousManifest.version} to ${packageVersion}; use --force only after explicit approval.`);
   }
   const packageVersionUpgrade = packageVersionComparison > 0;
-  const reinstallManagedRuntime = force || hasLegacyRoot || hasLegacyActiveTask
-    || packageVersionUpgrade || (previousManifest && previousManifest.schema_version < 5);
-  if (!dryRun && hasLegacyRoot) {
-    const legacyBackup = path.join(backupRoot, "legacy-ai-delivery");
-    fs.mkdirSync(path.dirname(legacyBackup), { recursive: true });
-    fs.cpSync(legacyRoot, legacyBackup, { recursive: true });
-  }
-  if (!dryRun && hasLegacyActiveTask) {
-    const taskBackup = path.join(backupRoot, "legacy-active-task.json");
-    fs.mkdirSync(path.dirname(taskBackup), { recursive: true });
-    fs.copyFileSync(legacyActiveTask, taskBackup);
-  }
+  const reinstallManagedRuntime = force || packageVersionUpgrade;
   const currentWorkspace = readWorkspaceConfiguration(target, { optional: true });
-  const legacyWorkspaceFile = path.join(target, LEGACY_WORKSPACE_CONFIG);
-  const legacyWorkspace = !currentWorkspace && fs.existsSync(legacyWorkspaceFile)
-    ? readWorkspaceConfiguration(target, { configurationPath: LEGACY_WORKSPACE_CONFIG })
-    : null;
-  const existingWorkspace = (currentWorkspace || legacyWorkspace)?.configuration;
+  const existingWorkspace = currentWorkspace?.configuration;
   const codePath = options.codePath || existingWorkspace?.code_repository?.path || "code";
   const codeId = options.codeId || existingWorkspace?.code_repository?.repo_id || "app";
   const sharedRemote = options.sharedRemote || null;
@@ -942,23 +909,23 @@ export function initProject(packageRoot, target, options = {}) {
   const sourceStandardsIndex = path.join(sourceWorkflow, "standards", "index.yaml");
   const workflowRoot = path.join(target, ".workflow");
   const standardsIndexFile = path.join(workflowRoot, "standards", "index.yaml");
-  const legacyIndicators = [
+  const unsupportedIndicators = [
     path.join(target, "delivery", "project.yaml"),
     path.join(target, "delivery", "workflow-state.yaml"),
     path.join(target, "delivery", "artifact-registry.yaml"),
     path.join(target, "delivery", "standards-baseline.yaml"),
     path.join(target, "standards", "index.yaml"),
   ].filter((candidate) => fs.existsSync(candidate));
-  if (fs.existsSync(workflowRoot) && legacyIndicators.length) {
+  if (fs.existsSync(workflowRoot) && unsupportedIndicators.length) {
     throw new Error(
-      "Detected both .workflow and legacy delivery/standards directories. "
+      "Detected both .workflow and unsupported delivery/standards directories. "
       + "Resolve the split workflow state before initialization.",
     );
   }
-  if (legacyIndicators.length) {
+  if (unsupportedIndicators.length) {
     throw new Error(
-      "Legacy workflow directories detected at delivery/ or standards/. "
-      + "Move them under .workflow/ before upgrading; refusing to create split workflow state.",
+      "Unsupported workflow directories detected at delivery/ or standards/. "
+      + "Remove them before initialization; refusing to create split workflow state.",
     );
   }
   for (const managedPath of [
@@ -986,8 +953,6 @@ export function initProject(packageRoot, target, options = {}) {
   const hookConflict = fs.existsSync(hookDestination)
     && !managedFilesEqual(hookDestination, sourceHook);
   if (hookConflict && !reinstallManagedRuntime) conflicts.push(path.relative(target, hookDestination));
-  const retiredViewerDestination = path.join(target, ".workflow", "tools", "viewer");
-  const retireLegacyViewer = hasLegacyRoot && fs.existsSync(retiredViewerDestination);
   const designReferenceDestination = path.join(target, "ref", "ui");
   let designReferencePlan = null;
   if (!fs.existsSync(designReferenceDestination)) {
@@ -1064,19 +1029,6 @@ export function initProject(packageRoot, target, options = {}) {
     ? fs.readFileSync(gitattributesFile, "utf8")
     : "";
   const gitattributesText = mergeGitattributes(existingGitattributes);
-  if (hasLegacyRoot || hasLegacyActiveTask) {
-    actions.push("migrate legacy .ai-delivery runtime into .workflow");
-    if (!dryRun) {
-      if (hasLegacyActiveTask) {
-        const activeTask = path.join(target, ACTIVE_TASK);
-        if (!fs.existsSync(activeTask)) {
-          fs.mkdirSync(path.dirname(activeTask), { recursive: true });
-          fs.copyFileSync(legacyActiveTask, activeTask);
-        }
-      }
-    }
-  }
-
   for (const plan of skillPlans) {
     if (plan.type === "copy") {
       actions.push(`install .agents/skills/${plan.name}`);
@@ -1098,9 +1050,6 @@ export function initProject(packageRoot, target, options = {}) {
   } else if (hookConflict) {
     backupAndReplace(target, hookDestination, sourceHook, backupRoot, actions, dryRun);
   }
-  if (retireLegacyViewer) {
-    backupAndRemove(target, retiredViewerDestination, backupRoot, actions, dryRun);
-  }
   if (designReferencePlan?.type === "copy") {
     actions.push("install ref/ui Design Reference Library");
     if (!dryRun) {
@@ -1200,21 +1149,6 @@ export function initProject(packageRoot, target, options = {}) {
     if (!dryRun) atomicWrite(manifestFile, manifestText);
   }
 
-  if (!dryRun && (hasLegacyRoot || hasLegacyActiveTask)) {
-    for (const required of [
-      path.join(target, WORKSPACE_CONFIG),
-      path.join(target, INSTALL_MANIFEST),
-      path.join(target, ".workflow", "tools", "state", "state.mjs"),
-      path.join(target, ".workflow", "tools", "hooks", "hook-event.mjs"),
-    ]) {
-      if (!fs.existsSync(required)) {
-        throw new Error(`Legacy migration is incomplete; preserved .ai-delivery for recovery: ${required}`);
-      }
-    }
-    if (hasLegacyRoot) fs.rmSync(legacyRoot, { recursive: true, force: true });
-    if (hasLegacyActiveTask) fs.rmSync(legacyActiveTask, { force: true });
-  }
-
   return {
     actions: [...workspace.actions, ...actions],
     summary: `${dryRun ? "Dry run" : "Initialized"} ${skillNames.length} workspace-scoped AI delivery skills in ${target}`,
@@ -1456,11 +1390,9 @@ function planUpgrade(packageRoot, target, options) {
     validateManagedPath(target, path.join(target, managedPath));
   }
   const { manifest, manifestFile } = readInstallManifest(target);
-  if (!Number.isInteger(manifest.schema_version)
-    || manifest.schema_version < 5
-    || manifest.schema_version > INSTALL_MANIFEST_SCHEMA) {
+  if (manifest.schema_version !== INSTALL_MANIFEST_SCHEMA) {
     throw new Error(
-      `Installation manifest schema ${manifest.schema_version} is incompatible with upgrade; run the compatible migration or repair command first.`,
+      `Installation manifest schema ${manifest.schema_version} is unsupported; expected current schema ${INSTALL_MANIFEST_SCHEMA}.`,
     );
   }
   const comparison = comparePackageVersions(packageVersion, manifest.version);
@@ -1471,10 +1403,6 @@ function planUpgrade(packageRoot, target, options) {
     throw new Error(`Refusing package downgrade from ${manifest.version} to ${packageVersion}; use --force only after explicit approval.`);
   }
   const workspace = readWorkspaceConfiguration(target);
-  const contractRetirement = executeDeliveryStateCommand([
-    "contract", "retire", "--project", target, "--gate-id", "UX-LF", "--dry-run",
-  ], { yaml: FORMAL_STATE_YAML });
-  const prototypeMigration = planPrototypeMigration(target);
   const codeRepository = workspace.configuration.code_repository;
   if (["path", "repo_id", "remote", "default_branch"].some((key) =>
     (manifest.code_repository?.[key] ?? null) !== (codeRepository[key] ?? null))) {
@@ -1484,18 +1412,12 @@ function planUpgrade(packageRoot, target, options) {
   }
   const sources = installationSources(packageRoot);
   const exactAssets = managedAssetInventory(sources, manifest);
-  const retiredAssets = RETIRED_MANAGED_ASSETS
-    .filter((asset) => manifest.managed_assets?.[asset.manifest_key])
-    .map((asset) => ({
-      ...asset,
-      previous_digest: manifest.managed_assets[asset.manifest_key].sha256 || null,
-    }));
   const mergedAssets = upgradeMergedAssets(
     target,
     sources,
     { ...manifest, code_repository: codeRepository },
   );
-  for (const asset of [...exactAssets, ...retiredAssets, ...mergedAssets]) {
+  for (const asset of [...exactAssets, ...mergedAssets]) {
     validateManagedPath(target, installPath(target, asset.path));
   }
   const additions = [];
@@ -1552,32 +1474,12 @@ function planUpgrade(packageRoot, target, options) {
       replacements.push({ path: asset.path, kind: "merged-file", forced: false });
     }
   }
-  for (const asset of retiredAssets) {
-    const destination = installPath(target, asset.path);
-    asset.destination = destination;
-    const currentDigest = pathDigest(destination);
-    asset.current_digest = currentDigest;
-    if (currentDigest === null) {
-      preserved.push({ path: asset.path, reason: "retired managed asset is already absent" });
-    } else if (asset.previous_digest && currentDigest === asset.previous_digest) {
-      removals.push({ path: asset.path, kind: asset.kind, forced: false });
-    } else {
-      conflicts.push({
-        path: asset.path,
-        reason: asset.previous_digest
-          ? "retired managed asset differs from the installed manifest digest"
-          : "installed manifest does not prove ownership of the retired managed asset",
-      });
-      if (force) removals.push({ path: asset.path, kind: asset.kind, forced: true });
-    }
-  }
   const preservedWorkflow = preservedWorkflowFiles(
     target,
     [
       ...exactAssets
         .filter((asset) => asset.kind !== "ensure-directory")
         .map((asset) => asset.path),
-      ...retiredAssets.map((asset) => asset.path),
       ...mergedAssets.map((asset) => asset.path),
     ],
   );
@@ -1599,7 +1501,6 @@ function planUpgrade(packageRoot, target, options) {
     codeRepository,
     sources,
     exactAssets,
-    retiredAssets,
     mergedAssets,
     additions,
     replacements,
@@ -1609,8 +1510,6 @@ function planUpgrade(packageRoot, target, options) {
     conflicts,
     backups,
     comparison,
-    contractRetirement,
-    prototypeMigration,
   };
 }
 
@@ -1704,17 +1603,6 @@ function applyUpgradePlan(target, plan, packageVersion) {
         apply: () => atomicWrite(asset.destination, asset.desired),
       });
     }
-    for (const asset of plan.retiredAssets) {
-      if (!changes.has(asset.path)) continue;
-      applyReceiptBackedAsset({
-        target,
-        upgradeRoot,
-        asset,
-        operation: "remove",
-        receiptAssets,
-        apply: () => fs.rmSync(asset.destination, { recursive: true, force: true }),
-      });
-    }
     const manifestRelative = INSTALL_MANIFEST.replaceAll("\\", "/");
     const manifestBackup = backupUpgradePath(target, upgradeRoot, manifestRelative);
     const nextManifest = buildInstallManifest(
@@ -1742,30 +1630,10 @@ function applyUpgradePlan(target, plan, packageVersion) {
       to_version: packageVersion,
       applied_at: new Date().toISOString(),
       formal_event_tree_fingerprint: formalEventFingerprint,
-      contract_retirement: {
-        gate_id: plan.contractRetirement.gate_id,
-        contract_version: UI_CONTRACT_VERSION,
-        affected_iterations: plan.contractRetirement.affected_iterations,
-        expected_scope_revisions: plan.contractRetirement.expected_scope_revisions,
-      },
       assets: receiptAssets,
     };
     atomicWrite(path.join(upgradeRoot, "receipt.json"), `${JSON.stringify(receipt, null, 2)}\n`);
-    const retirementArgs = [
-      "contract", "retire", "--project", target,
-      "--gate-id", "UX-LF",
-      "--actor", "system:package-upgrade",
-      "--reason", "prototype-first UI contract",
-      "--contract-version", UI_CONTRACT_VERSION,
-    ];
-    const expectedRevisions = Object.values(plan.contractRetirement.expected_scope_revisions);
-    if (expectedRevisions.length === 1) {
-      retirementArgs.push("--expected-scope-revision", String(expectedRevisions[0]));
-    }
-    const contractRetirement = executeDeliveryStateCommand(retirementArgs, {
-      yaml: FORMAL_STATE_YAML,
-    });
-    return { upgradeId, contractRetirement };
+    return { upgradeId };
   } catch (error) {
     restoreUpgradeAssets(target, upgradeRoot, receiptAssets);
     fs.rmSync(upgradeRoot, { recursive: true, force: true });
@@ -1796,7 +1664,6 @@ function rollbackUpgrade(packageRoot, target, upgradeId) {
   const sources = installationSources(packageRoot);
   const allowedPaths = new Set([
     ...managedAssetInventory(sources).map((asset) => asset.path),
-    ...RETIRED_MANAGED_ASSETS.map((asset) => asset.path),
     ...MERGED_MANAGED_SURFACES.map((surface) => surface.path),
     INSTALL_MANIFEST.replaceAll("\\", "/"),
   ]);
@@ -1866,26 +1733,10 @@ export function upgradeProject(packageRoot, target, options = {}) {
       conflicts: plan.conflicts,
       backups: plan.backups,
     },
-    compatibility: {
-      installation_manifest: "compatible",
-      package_version: plan.comparison > 0 ? "upgrade" : plan.comparison === 0 ? "same-version repair" : "forced downgrade",
-    },
     code_repository: {
       path: plan.codeRepository.path,
       write_planned: false,
     },
-    contract_retirement: {
-      ...plan.contractRetirement,
-      contract_version: UI_CONTRACT_VERSION,
-      write_planned: plan.contractRetirement.affected_iterations.length > 0,
-    },
-    prototype_migration: {
-      ...plan.prototypeMigration,
-      required_follow_up: {
-        command: "ai-delivery migrate",
-        write_planned: false,
-      },
-    },
   };
   if (dryRun) return report;
   const blockingConflicts = plan.conflicts.filter((item) => !force || item.forceable === false);
@@ -1897,12 +1748,6 @@ export function upgradeProject(packageRoot, target, options = {}) {
   }
   const applied = applyUpgradePlan(target, plan, packageVersion);
   report.upgrade_id = applied.upgradeId;
-  report.contract_retirement = {
-    ...report.contract_retirement,
-    ...applied.contractRetirement,
-    contract_version: UI_CONTRACT_VERSION,
-    write_planned: false,
-  };
   report.applied = true;
   return report;
 }
@@ -2074,6 +1919,28 @@ export function doctorProject(target, options = {}) {
 
   const workflowGit = gitTopLevel(target);
   const codeGit = workspace ? gitTopLevel(workspace.codeRoot) : null;
+  if (workspace) {
+    const documentation = inspectCodebaseDocumentation(workspace.codeRoot);
+    checks.push({
+      ok: documentation.status !== "invalid",
+      required: false,
+      scope: "codebase-documentation",
+      message: documentation.status === "missing"
+        ? "code repository handbook/index are not installed; Bootstrap or maintainers may add them"
+        : `code repository handbook/index status: ${documentation.status}`,
+    });
+    const confirmations = inspectConfirmationSummaries(target);
+    checks.push({
+      ok: confirmations.status !== "invalid",
+      required: false,
+      scope: "communication-confirmation",
+      message: confirmations.status === "absent"
+        ? "no communication confirmation summaries are present"
+        : confirmations.status === "invalid"
+          ? `communication confirmation summaries are invalid: ${confirmations.errors.join("; ")}`
+          : `${confirmations.summaries.length} communication confirmation summary(ies) validate; frontier=${confirmations.summaries.flatMap((item) => item.frontier).join(",") || "empty"}`,
+    });
+  }
   const workflowCommonGit = workflowGit ? gitCommonDirectory(target) : null;
   const codeCommonGit = codeGit && workspace ? gitCommonDirectory(workspace.codeRoot) : null;
   checks.push({
@@ -2231,6 +2098,7 @@ export function doctorProject(target, options = {}) {
   const bootstrapFiles = [
     "bootstrap.mjs",
     "project-bootstrap.mjs",
+    "communication-confirmation.mjs",
     "workspace.mjs",
     "yaml-runtime.mjs",
     "delivery-state.mjs",
@@ -2496,8 +2364,8 @@ export function doctorProject(target, options = {}) {
     });
   }
   checks.push({
-    ok: !fs.existsSync(path.join(target, ".ai-delivery")) && !fs.existsSync(path.join(target, LEGACY_ACTIVE_TASK)),
-    message: "legacy .ai-delivery paths are absent",
+    ok: !fs.existsSync(path.join(target, ".ai-delivery")) && !fs.existsSync(path.join(target, ".ai-delivery-task")),
+    message: "unsupported workflow paths are absent",
   });
   checks.push({ ok: fs.existsSync(path.join(target, "AGENTS.md")), message: "project AGENTS.md is present" });
   return { checks, ok: checks.filter((check) => check.required !== false).every((check) => check.ok) };

package/lib/project-repair.mjs

@@ -0,0 +1,217 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { atomicWrite, filesUnder } from "./fs-utils.mjs";
+
+function toPosix(value) {
+  return value.replaceAll("\\", "/");
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function treeDigest(root) {
+  const hash = crypto.createHash("sha256");
+  for (const file of filesUnder(root)) {
+    hash.update(toPosix(path.relative(root, file)));
+    hash.update("\0");
+    hash.update(fs.readFileSync(file));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+function readStructured(file, label) {
+  try {
+    const text = fs.readFileSync(file, "utf8");
+    const value = path.extname(file).toLowerCase() === ".json" ? JSON.parse(text) : parseYaml(text);
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("expected a mapping");
+    return value;
+  } catch (error) {
+    throw new Error(`Cannot read ${label} (${toPosix(file)}): ${error.message}`);
+  }
+}
+
+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 stableJson(value) {
+  return JSON.stringify(stableValue(value));
+}
+
+function uniqueSorted(values) {
+  return [...new Set((Array.isArray(values) ? values : []).map(String))].sort();
+}
+
+function unsignedRepairRecord(record) {
+  const unsigned = { ...record };
+  delete unsigned.record_checksum;
+  return unsigned;
+}
+
+function readRepairTransactions(project) {
+  const directory = path.join(project, ".workflow", "control", "repairs", "transactions");
+  const records = [];
+  let previousChecksum = null;
+  for (const file of filesUnder(directory).filter((item) => item.endsWith(".json"))) {
+    const record = readStructured(file, "repair transaction");
+    if (record.schema_version !== 1
+      || !Number.isInteger(record.sequence)
+      || record.sequence !== records.length + 1
+      || record.previous_checksum !== previousChecksum
+      || record.record_checksum !== sha256(stableJson(unsignedRepairRecord(record)))) {
+      throw new Error(`Repair transaction chain is invalid: ${toPosix(path.relative(project, file))}.`);
+    }
+    records.push(record);
+    previousChecksum = record.record_checksum;
+  }
+  return records;
+}
+
+function archiveIterationId(value) {
+  const iterationId = String(value || "");
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(iterationId)) {
+    throw new Error(`Invalid archive iteration ID: ${iterationId || "missing"}.`);
+  }
+  return iterationId;
+}
+
+function verifiedArchiveInvalidations(project, records) {
+  for (const record of records.filter((item) => item.transaction_type === "archive-invalidation")) {
+    const iterationId = archiveIterationId(record.target?.iteration_id);
+    const expectedArchivePath = `.workflow/control/archives/versions/${iterationId}`;
+    const expectedManifestPath = `${expectedArchivePath}/version-manifest.json`;
+    if (record.target.archive_path !== expectedArchivePath
+      || record.target.manifest_path !== expectedManifestPath
+      || !/^[a-f0-9]{64}$/.test(record.target.archive_sha256 || "")
+      || !/^[a-f0-9]{64}$/.test(record.target.manifest_sha256 || "")) {
+      throw new Error(`Archive invalidation target is invalid: ${record.transaction_id}.`);
+    }
+    const archiveDirectory = path.join(project, ...expectedArchivePath.split("/"));
+    const manifestFile = path.join(project, ...expectedManifestPath.split("/"));
+    if (!fs.existsSync(manifestFile)
+      || treeDigest(archiveDirectory) !== record.target.archive_sha256
+      || sha256(fs.readFileSync(manifestFile)) !== record.target.manifest_sha256) {
+      throw new Error(`Invalidated archive ${iterationId} bytes changed after ${record.transaction_id}.`);
+    }
+  }
+}
+
+function repairTransactionPath(sequence, transactionId) {
+  return `.workflow/control/repairs/transactions/${String(sequence).padStart(6, "0")}-${transactionId}.json`;
+}
+
+export function repairProject(project, options = {}) {
+  const root = path.resolve(project);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    throw new Error(`Project directory does not exist: ${root}`);
+  }
+  const iterationId = archiveIterationId(options.invalidateArchive);
+  const reason = String(options.reason || "").trim();
+  const actor = String(options.actor || "").trim();
+  const evidence = uniqueSorted(options.evidence);
+  if (!reason) throw new Error("Archive invalidation requires --reason.");
+  if (!actor.startsWith("human:")) {
+    throw new Error("Archive invalidation requires an explicit human actor through --actor human:<identity>.");
+  }
+  if (evidence.length < 2) {
+    throw new Error("Archive invalidation requires at least two --evidence values for RCA and recovery evidence.");
+  }
+  const archiveDirectory = path.join(root, ".workflow", "control", "archives", "versions", iterationId);
+  const manifestFile = path.join(archiveDirectory, "version-manifest.json");
+  if (!fs.existsSync(manifestFile)) throw new Error(`Version archive not found: ${iterationId}.`);
+  const manifest = readStructured(manifestFile, "version archive manifest");
+  if (manifest.iteration_id !== iterationId) {
+    throw new Error(`Version archive identity mismatch: expected ${iterationId}, found ${manifest.iteration_id || "missing"}.`);
+  }
+  const target = {
+    iteration_id: iterationId,
+    archive_path: toPosix(path.relative(root, archiveDirectory)),
+    manifest_path: toPosix(path.relative(root, manifestFile)),
+    manifest_sha256: sha256(fs.readFileSync(manifestFile)),
+    archive_sha256: treeDigest(archiveDirectory),
+    original_bytes_preserved: true,
+  };
+  const identity = { transaction_type: "archive-invalidation", target, correction: { actor, reason, evidence } };
+  const idempotencyKey = `archive-invalidation:${iterationId}:${sha256(stableJson(identity))}`;
+  const existingTransactions = readRepairTransactions(root);
+  verifiedArchiveInvalidations(root, existingTransactions);
+  const existing = existingTransactions.find((record) => record.idempotency_key === idempotencyKey);
+  const sequence = existing?.sequence || existingTransactions.length + 1;
+  const transactionId = existing?.transaction_id || `REPAIR-${sha256(idempotencyKey).slice(0, 16).toUpperCase()}`;
+  const transactionPath = repairTransactionPath(sequence, transactionId);
+  const report = {
+    command: "repair",
+    action: "archive-invalidation",
+    dry_run: Boolean(options.dryRun),
+    applied: false,
+    forward_only: true,
+    original_bytes_preserved: true,
+    target,
+    actor,
+    reason,
+    evidence,
+    transaction: {
+      transaction_id: transactionId,
+      path: transactionPath,
+      previous_checksum: existing?.previous_checksum || existingTransactions.at(-1)?.record_checksum || null,
+    },
+    eligibility: existing
+      ? { iteration_id: iterationId, current: "invalidated", source_transaction_id: transactionId }
+      : { iteration_id: iterationId, current: "eligible", source_transaction_id: null },
+  };
+  if (report.dry_run || existing) return report;
+
+  const repairRoot = path.join(root, ".workflow", "control", "repairs");
+  const lockFile = path.join(repairRoot, ".repair.lock");
+  fs.mkdirSync(repairRoot, { recursive: true });
+  let lock;
+  try {
+    lock = fs.openSync(lockFile, "wx");
+  } catch (error) {
+    throw new Error(`Repair transaction is locked by another writer: ${error.message}`);
+  }
+  try {
+    const currentTransactions = readRepairTransactions(root);
+    const duplicate = currentTransactions.find((record) => record.idempotency_key === idempotencyKey);
+    if (duplicate) {
+      report.transaction.transaction_id = duplicate.transaction_id;
+      report.transaction.path = repairTransactionPath(duplicate.sequence, duplicate.transaction_id);
+      report.eligibility = { iteration_id: iterationId, current: "invalidated", source_transaction_id: duplicate.transaction_id };
+      return report;
+    }
+    if (currentTransactions.length !== existingTransactions.length
+      || (currentTransactions.at(-1)?.record_checksum || null) !== (existingTransactions.at(-1)?.record_checksum || null)) {
+      throw new Error("Repair transaction revision changed during apply; rerun the command.");
+    }
+    if (treeDigest(archiveDirectory) !== target.archive_sha256
+      || sha256(fs.readFileSync(manifestFile)) !== target.manifest_sha256) {
+      throw new Error(`Version archive changed during repair apply: ${iterationId}.`);
+    }
+    const transaction = {
+      schema_version: 1,
+      sequence,
+      transaction_id: transactionId,
+      transaction_type: "archive-invalidation",
+      idempotency_key: idempotencyKey,
+      occurred_at: new Date().toISOString(),
+      target,
+      correction: { actor, reason, evidence },
+      previous_checksum: existingTransactions.at(-1)?.record_checksum || null,
+    };
+    transaction.record_checksum = sha256(stableJson(transaction));
+    atomicWrite(path.join(root, ...transactionPath.split("/")), `${JSON.stringify(transaction, null, 2)}\n`);
+    report.applied = true;
+    report.transaction.previous_checksum = transaction.previous_checksum;
+    report.eligibility = { iteration_id: iterationId, current: "invalidated", source_transaction_id: transactionId };
+    return report;
+  } finally {
+    if (lock !== undefined) fs.closeSync(lock);
+    fs.rmSync(lockFile, { force: true });
+  }
+}