ai-delivery-workflow 0.4.0 → 0.5.1

package/lib/prototype-migration.mjs

@@ -1,713 +0,0 @@
-import crypto from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
-import { resolveContainedPath as containedRef } from "./artifact-files.mjs";
-import { atomicWrite, filesUnder } from "./fs-utils.mjs";
-import { parsePrototypeCatalogCsv } from "./prototype-revision.mjs";
-import { stableValue } from "./stable-value.mjs";
-
-const TARGET_PROTOTYPE_ID = "PROTOTYPE";
-const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-
-function toPosix(value) {
-  return value.replaceAll("\\", "/");
-}
-
-function sha256(value) {
-  return crypto.createHash("sha256").update(value).digest("hex");
-}
-
-function stableJson(value) {
-  return JSON.stringify(stableValue(value));
-}
-
-function readYaml(file, label) {
-  try {
-    const document = parseYaml(fs.readFileSync(file, "utf8"));
-    if (!document || typeof document !== "object" || Array.isArray(document)) {
-      throw new Error("expected a mapping");
-    }
-    return document;
-  } catch (error) {
-    throw new Error(`Cannot read ${label} (${toPosix(file)}): ${error.message}`);
-  }
-}
-
-function currentIterationId(root) {
-  for (const deliveryRoot of [".workflow/delivery", "delivery"]) {
-    const stateFile = path.join(root, ...deliveryRoot.split("/"), "workflow-state.yaml");
-    if (fs.existsSync(stateFile)) {
-      const state = readYaml(stateFile, "workflow state");
-      const active = String(state.development_state?.scope_id || "").trim();
-      if (active) {
-        if (!SAFE_ID.test(active)) throw new Error(`Active iteration ID is unsafe: ${active}.`);
-        return active;
-      }
-    }
-    const projectFile = path.join(root, ...deliveryRoot.split("/"), "project.yaml");
-    if (fs.existsSync(projectFile)) {
-      const project = readYaml(projectFile, "project descriptor");
-      const active = String(project.current_iteration_id || "").trim();
-      if (active) {
-        if (!SAFE_ID.test(active)) throw new Error(`Active iteration ID is unsafe: ${active}.`);
-        return active;
-      }
-    }
-  }
-  return null;
-}
-
-function discoverLegacySets(root, activeIterationId) {
-  const iterationPrefixes = [".workflow/iterations", "iterations"];
-  const experiencePrefixes = [".workflow/experience", "experience"];
-  const archivePrefixes = [".workflow/control/archives/versions", "control/archives/versions"];
-  const designNodes = ["02-solution-design", "04-experience-design"];
-  const sets = [];
-  const addIterationSets = (prefix, scopeForIteration) => {
-    const iterationsRoot = path.join(root, ...prefix.split("/"));
-    if (!fs.existsSync(iterationsRoot)) return;
-    for (const entry of fs.readdirSync(iterationsRoot, { withFileTypes: true })) {
-      if (!entry.isDirectory()) continue;
-      const iterationId = entry.name;
-      for (const node of designNodes) {
-        const file = path.join(iterationsRoot, iterationId, node, "prototype-set.yaml");
-        if (!fs.existsSync(file) || !fs.statSync(file).isFile()) continue;
-        sets.push({ file, iteration_id: iterationId, scope: scopeForIteration(iterationId) });
-      }
-    }
-  };
-  for (const prefix of iterationPrefixes) {
-    addIterationSets(prefix, (iterationId) =>
-      iterationId === activeIterationId ? "open" : "closed");
-  }
-  for (const prefix of experiencePrefixes) {
-    const experienceRoot = path.join(root, ...prefix.split("/"));
-    if (fs.existsSync(experienceRoot)) {
-      for (const entry of fs.readdirSync(experienceRoot, { withFileTypes: true })) {
-        if (!entry.isDirectory()) continue;
-        const file = path.join(experienceRoot, entry.name, "prototype-set.yaml");
-        if (!fs.existsSync(file) || !fs.statSync(file).isFile()) continue;
-        sets.push({
-          file,
-          iteration_id: entry.name,
-          scope: entry.name === activeIterationId ? "open" : "closed",
-        });
-      }
-    }
-    const directFile = path.join(experienceRoot, "prototype-set.yaml");
-    if (fs.existsSync(directFile) && fs.statSync(directFile).isFile()) {
-      sets.push({
-        file: directFile,
-        iteration_id: activeIterationId,
-        scope: activeIterationId ? "open" : "closed",
-      });
-    }
-  }
-  for (const prefix of archivePrefixes) {
-    addIterationSets(prefix, () => "archived");
-  }
-  return sets.sort((left, right) => left.file.localeCompare(right.file));
-}
-
-function setMembers(document) {
-  if (Array.isArray(document.members)) return document.members;
-  if (Array.isArray(document.ordered_members)) return document.ordered_members;
-  return [];
-}
-
-function memberIdentity(value) {
-  return String(value?.prototype_member_id || value?.prototype_artifact_id || value?.artifact_id || "").trim();
-}
-
-function manifestRef(setDirectory, member, memberId) {
-  const explicit = String(member.manifest_ref || "").trim();
-  if (explicit) return explicit;
-  for (const candidate of [`prototype-manifest-${memberId}.yaml`, "prototype-manifest.yaml"]) {
-    if (fs.existsSync(path.join(setDirectory, candidate))) return candidate;
-  }
-  return "";
-}
-
-function catalogBinding(manifest, kind) {
-  const keys = kind === "routes"
-    ? ["prototype_routes", "routes"]
-    : kind === "pages" ? ["page_catalog"] : ["prototype_files"];
-  for (const key of keys) {
-    const ref = manifest[`${key}_ref`];
-    if (!ref) continue;
-    return {
-      ref: String(ref),
-      algorithm: String(manifest[`${key}_algorithm`] || "sha256"),
-      checksum: String(manifest[`${key}_checksum`] || ""),
-    };
-  }
-  return null;
-}
-
-function sourceBinding(manifest) {
-  const ref = manifest.source_path || manifest.prototype?.source_ref;
-  const checksum = manifest.source_checksum || manifest.prototype?.source_checksum;
-  return {
-    ref: String(ref || ""),
-    algorithm: String(manifest.source_algorithm || manifest.prototype?.source_algorithm || "sha256"),
-    checksum: String(checksum || ""),
-  };
-}
-
-function exactSourceFiles(source) {
-  if (!fs.existsSync(source)) return [];
-  if (fs.statSync(source).isFile()) return [source];
-  if (fs.statSync(source).isDirectory()) return filesUnder(source);
-  return [];
-}
-
-function sourceDigest(source) {
-  if (fs.statSync(source).isFile()) return sha256(fs.readFileSync(source));
-  const hash = crypto.createHash("sha256");
-  for (const file of filesUnder(source)) {
-    hash.update(toPosix(path.relative(source, file)));
-    hash.update("\0");
-    hash.update(fs.readFileSync(file));
-    hash.update("\0");
-  }
-  return hash.digest("hex");
-}
-
-function conflict(kind, id, records, reason = "member-definitions-differ") {
-  const memberIds = [...new Set(records.map((record) => record.member_id))].sort();
-  const recordChecksums = records.map((record) => record.record_checksum).sort();
-  const conflictId = `PROTO-CONFLICT-${sha256(stableJson({ kind, id, memberIds, recordChecksums, reason })).slice(0, 16).toUpperCase()}`;
-  return {
-    conflict_id: conflictId,
-    target_kind: kind,
-    target_id: id,
-    member_ids: memberIds,
-    reason,
-    decision_required: reason === "member-definitions-differ",
-  };
-}
-
-function mergeRecords(kind, identityField, records) {
-  const grouped = new Map();
-  const conflicts = [];
-  for (const [index, record] of records.entries()) {
-    const id = String(record[identityField] || "").trim();
-    if (!id) {
-      conflicts.push(conflict(
-        kind,
-        `${record.member_id}:${identityField}:row-${index + 1}`,
-        [record],
-        "missing-stable-identity",
-      ));
-      continue;
-    }
-    if (!grouped.has(id)) grouped.set(id, []);
-    grouped.get(id).push(record);
-  }
-  const merged = [];
-  for (const [id, candidates] of grouped) {
-    const unique = new Set(candidates.map((record) => record.record_checksum));
-    const duplicateMembers = new Set(candidates
-      .map((record) => record.member_id)
-      .filter((memberId, index, memberIds) => memberIds.indexOf(memberId) !== index));
-    if (duplicateMembers.size) {
-      conflicts.push(conflict(
-        kind,
-        id,
-        candidates.filter((record) => duplicateMembers.has(record.member_id)),
-        "duplicate-member-record-id",
-      ));
-    } else if (unique.size > 1) conflicts.push(conflict(kind, id, candidates));
-    const canonical = [...candidates].sort((left, right) =>
-      left.member_id.localeCompare(right.member_id))[0];
-    merged.push({
-      [`${kind === "file" ? "file" : kind}_id`]: id,
-      member_ids: [...new Set(candidates.map((record) => record.member_id))].sort(),
-      record_checksum: canonical.record_checksum,
-      conflict: unique.size > 1,
-    });
-  }
-  return {
-    records: merged.sort((left, right) => String(left[`${kind === "file" ? "file" : kind}_id`])
-      .localeCompare(String(right[`${kind === "file" ? "file" : kind}_id`]))),
-    conflicts,
-  };
-}
-
-function readCatalog(member, kind, conflicts, sourceFiles, required) {
-  const binding = catalogBinding(member.manifest, kind);
-  if (!binding) {
-    if (required) conflicts.push(conflict("catalog", `${member.member_id}:${kind}`, [{
-      member_id: member.member_id,
-      record_checksum: sha256("missing"),
-    }], "catalog-binding-missing"));
-    return [];
-  }
-  let file;
-  try {
-    file = containedRef(member.directory, binding.ref, `Legacy Prototype ${kind} catalog`);
-  } catch (error) {
-    conflicts.push(conflict("catalog", `${member.member_id}:${kind}`, [{
-      member_id: member.member_id,
-      record_checksum: sha256(error.message),
-    }], "invalid-catalog-ref"));
-    return [];
-  }
-  if (binding.algorithm !== "sha256" || !/^[a-f0-9]{64}$/.test(binding.checksum)
-      || !fs.existsSync(file) || sha256(fs.readFileSync(file)) !== binding.checksum) {
-    conflicts.push(conflict("catalog", `${member.member_id}:${kind}`, [{
-      member_id: member.member_id,
-      record_checksum: fs.existsSync(file) ? sha256(fs.readFileSync(file)) : sha256("missing"),
-    }], "catalog-checksum-mismatch"));
-    return [];
-  }
-  sourceFiles.add(file);
-  return parsePrototypeCatalogCsv(
-    fs.readFileSync(file, "utf8"),
-    `Legacy Prototype ${kind} catalog`,
-  ).rows
-    .map((row) => ({
-      ...row,
-      member_id: member.member_id,
-      record_checksum: sha256(stableJson(row)),
-    }));
-}
-
-function loadOpenMembers(root, openSets) {
-  const members = [];
-  const conflicts = [];
-  const sourceFiles = new Set();
-  let declaredMemberCount = 0;
-  for (const set of openSets) {
-    sourceFiles.add(set.file);
-    const document = readYaml(set.file, "legacy Prototype set");
-    const directory = path.dirname(set.file);
-    for (const item of setMembers(document)) {
-      declaredMemberCount += 1;
-      const expectedId = memberIdentity(item);
-      if (!SAFE_ID.test(expectedId)) {
-        conflicts.push(conflict("member", expectedId || "missing", [{
-          member_id: expectedId || "missing",
-          record_checksum: sha256(stableJson(item)),
-        }], "invalid-member-id"));
-        continue;
-      }
-      const ref = manifestRef(directory, item, expectedId);
-      let manifestFile;
-      try {
-        manifestFile = containedRef(directory, ref, "Legacy Prototype member manifest");
-      } catch (error) {
-        conflicts.push(conflict("member", expectedId || "missing", [{
-          member_id: expectedId || "missing",
-          record_checksum: sha256(error.message),
-        }], "invalid-manifest-ref"));
-        continue;
-      }
-      const expectedChecksum = String(item.manifest_checksum || "");
-      if (!expectedId || !fs.existsSync(manifestFile) || !/^[a-f0-9]{64}$/.test(expectedChecksum)
-          || sha256(fs.readFileSync(manifestFile)) !== expectedChecksum) {
-        conflicts.push(conflict("member", expectedId || "missing", [{
-          member_id: expectedId || "missing",
-          record_checksum: fs.existsSync(manifestFile)
-            ? sha256(fs.readFileSync(manifestFile)) : sha256("missing"),
-        }], "manifest-checksum-mismatch"));
-        continue;
-      }
-      sourceFiles.add(manifestFile);
-      const manifest = readYaml(manifestFile, "legacy Prototype member manifest");
-      const actualId = memberIdentity(manifest);
-      if (actualId !== expectedId) {
-        conflicts.push(conflict("member", expectedId, [{
-          member_id: expectedId,
-          record_checksum: sha256(stableJson({ expectedId, actualId })),
-        }], "member-identity-mismatch"));
-        continue;
-      }
-      const binding = sourceBinding(manifest);
-      let source;
-      try {
-        source = containedRef(directory, binding.ref, "Legacy Prototype source");
-      } catch (error) {
-        conflicts.push(conflict("source", expectedId, [{
-          member_id: expectedId,
-          record_checksum: sha256(error.message),
-        }], "invalid-source-ref"));
-        continue;
-      }
-      if (!fs.existsSync(source) || !new Set(["sha256", "sha256-tree-v1"]).has(binding.algorithm)
-          || !/^[a-f0-9]{64}$/.test(binding.checksum)
-          || sourceDigest(source) !== binding.checksum) {
-        conflicts.push(conflict("source", expectedId, [{
-          member_id: expectedId,
-          record_checksum: fs.existsSync(source) ? sourceDigest(source) : sha256("missing"),
-        }], "source-checksum-mismatch"));
-        continue;
-      }
-      for (const file of exactSourceFiles(source)) sourceFiles.add(file);
-      members.push({
-        member_id: expectedId,
-        manifest_ref: toPosix(path.relative(root, manifestFile)),
-        manifest_checksum: expectedChecksum,
-        directory,
-        manifest,
-        source,
-        source_ref: toPosix(path.relative(root, source)),
-        source_checksum: binding.checksum,
-        terminal_ids: [...new Set([
-          ...(Array.isArray(item.terminal_ids) ? item.terminal_ids : []),
-          ...(Array.isArray(manifest.terminal_ids) ? manifest.terminal_ids : []),
-          ...(Array.isArray(manifest.coverage?.terminal_ids) ? manifest.coverage.terminal_ids : []),
-        ].map(String))].sort(),
-      });
-    }
-  }
-  members.sort((left, right) => left.member_id.localeCompare(right.member_id));
-  const duplicateIds = [...new Set(members.map((member) => member.member_id))]
-    .filter((id) => members.filter((member) => member.member_id === id).length > 1);
-  for (const id of duplicateIds) {
-    conflicts.push(conflict("member", id, members.filter((member) => member.member_id === id)
-      .map((member) => ({ member_id: id, record_checksum: member.manifest_checksum })), "duplicate-member-id"));
-  }
-  return { members, conflicts, sourceFiles, declaredMemberCount };
-}
-
-function mergeReport(loaded) {
-  const conflicts = [...loaded.conflicts];
-  const sourceFiles = loaded.sourceFiles;
-  const terminals = loaded.members.flatMap((member) => member.terminal_ids.map((terminalId) => ({
-    terminal_id: terminalId,
-    member_id: member.member_id,
-    record_checksum: sha256(stableJson({ terminal_id: terminalId })),
-  })));
-  const requireCatalogs = loaded.members.length > 0;
-  const pages = loaded.members.flatMap((member) =>
-    readCatalog(member, "pages", conflicts, sourceFiles, requireCatalogs));
-  const routes = loaded.members.flatMap((member) =>
-    readCatalog(member, "routes", conflicts, sourceFiles, requireCatalogs));
-  const files = loaded.members.flatMap((member) =>
-    readCatalog(member, "files", conflicts, sourceFiles, requireCatalogs));
-  const terminalMerge = mergeRecords("terminal", "terminal_id", terminals);
-  const pageMerge = mergeRecords("page", "page_id", pages);
-  const routeMerge = mergeRecords("route", "route_id", routes);
-  const fileMerge = mergeRecords("file", "file_ref", files);
-  conflicts.push(...terminalMerge.conflicts, ...pageMerge.conflicts, ...routeMerge.conflicts, ...fileMerge.conflicts);
-  return {
-    terminals: terminalMerge.records,
-    pages: pageMerge.records,
-    routes: routeMerge.records,
-    files: fileMerge.records,
-    conflicts: conflicts.sort((left, right) => left.conflict_id.localeCompare(right.conflict_id)),
-  };
-}
-
-function applyDecisions(report, decisionsFile, sourceChecksum) {
-  report.decisions = [];
-  report.unresolved_conflicts = report.merge_report.conflicts.map((item) => ({ ...item }));
-  report.decision_template = {
-    schema_version: 1,
-    source_checksum: sourceChecksum || "REPLACE_WITH_MIGRATION_SOURCE_CHECKSUM",
-    actor: "human:<identity>",
-    decisions: [],
-    prototype_decisions: report.merge_report.conflicts.filter((item) => item.decision_required).map((item) => ({
-      conflict_id: item.conflict_id,
-      action: "choose-member",
-      member_id: item.member_ids[0] || "<member-id>",
-      rationale: "<why this member is canonical for the merged identity>",
-    })),
-  };
-  if (!decisionsFile) return;
-  if (!sourceChecksum) throw new Error("Prototype migration decisions require the migration source checksum.");
-  const document = readYaml(path.resolve(decisionsFile), "migration decisions");
-  if (document.schema_version !== 1 || document.source_checksum !== sourceChecksum) {
-    throw new Error("Prototype migration decisions do not match the current source checksum.");
-  }
-  const actor = String(document.actor || "").trim();
-  if (!actor.startsWith("human:")) {
-    throw new Error("Prototype migration decisions require actor human:<identity>.");
-  }
-  if (!Array.isArray(document.prototype_decisions)) {
-    throw new Error("Prototype migration decisions must contain a prototype_decisions list.");
-  }
-  const byId = new Map();
-  for (const decision of document.prototype_decisions) {
-    const id = String(decision?.conflict_id || "");
-    if (!id || byId.has(id)) throw new Error(`Prototype migration conflict decision is missing or duplicated: ${id || "missing"}.`);
-    byId.set(id, decision);
-  }
-  const unresolved = [];
-  for (const item of report.merge_report.conflicts) {
-    const decision = byId.get(item.conflict_id);
-    if (!decision) {
-      unresolved.push(item);
-      continue;
-    }
-    if (!item.decision_required) {
-      throw new Error(
-        `Prototype migration conflict ${item.conflict_id} (${item.reason}) is not human-resolvable; decisions cannot override integrity or structural evidence.`,
-      );
-    }
-    const memberId = String(decision.member_id || "");
-    const rationale = String(decision.rationale || "").trim();
-    if (decision.action !== "choose-member" || !item.member_ids.includes(memberId) || !rationale) {
-      throw new Error(`Prototype migration decision is invalid for ${item.conflict_id}.`);
-    }
-    const normalized = {
-      conflict_id: item.conflict_id,
-      action: "choose-member",
-      member_id: memberId,
-      actor,
-      rationale,
-    };
-    report.decisions.push(normalized);
-    item.decision_required = false;
-    item.resolution = normalized;
-  }
-  for (const id of byId.keys()) {
-    if (!report.merge_report.conflicts.some((item) => item.conflict_id === id)) {
-      throw new Error(`Prototype migration decision does not match a conflict: ${id}.`);
-    }
-  }
-  report.decisions.sort((left, right) => left.conflict_id.localeCompare(right.conflict_id));
-  report.unresolved_conflicts = unresolved;
-}
-
-function generatedContent(report) {
-  const migrationId = `PROTOTYPE-MIGRATION-${report.source_checksum.slice(0, 16).toUpperCase()}`;
-  const migrationRecord = stableValue({
-    schema_version: 1,
-    artifact_id: migrationId,
-    artifact_type: "legacy-prototype-migration",
-    iteration_id: report.iteration_id,
-    status: "applied-pending-ux-ui",
-    source_checksum: report.source_checksum,
-    target_prototype_id: TARGET_PROTOTYPE_ID,
-    legacy_sets: report.legacy_sets,
-    members: report.members,
-    merge_report: report.merge_report,
-    decisions: report.decisions,
-    preserved_history: report.preserved_history,
-    approval: report.approval,
-  });
-  const descriptor = stableValue({
-    schema_version: 1,
-    artifact_type: "prototype-current",
-    prototype_id: TARGET_PROTOTYPE_ID,
-    iteration_id: report.iteration_id,
-    status: "migration-pending-ux-ui",
-    current_source_ref: "prototype/source",
-    current_review_shell_ref: "prototype/review-shell",
-    current_revision_ref: null,
-    migration: {
-      artifact_id: migrationId,
-      ref: "prototype-migration.yaml",
-      algorithm: "sha256",
-      checksum: sha256(stringifyYaml(migrationRecord, { lineWidth: 0 })),
-    },
-  });
-  const links = report.members.map((member) =>
-    `<li><a href="../source/${encodeURIComponent(member.member_id)}/">${member.member_id}</a></li>`).join("");
-  const shell = `<!doctype html>\n<html lang="en"><head><meta charset="utf-8"><title>Legacy Prototype migration</title></head><body><main><h1>Prototype migration pending UX-UI</h1><ul>${links}</ul></main></body></html>\n`;
-  return {
-    descriptor: stringifyYaml(descriptor, { lineWidth: 0 }),
-    migration: stringifyYaml(migrationRecord, { lineWidth: 0 }),
-    shell,
-  };
-}
-
-function buildOperations(root, report) {
-  const generated = generatedContent(report);
-  const writes = [
-    { path: ".workflow/experience/" + report.iteration_id + "/prototype.yaml", kind: "prototype-current", content: Buffer.from(generated.descriptor) },
-    { path: ".workflow/experience/" + report.iteration_id + "/prototype-migration.yaml", kind: "prototype-migration-record", content: Buffer.from(generated.migration) },
-    { path: ".workflow/experience/" + report.iteration_id + "/prototype/review-shell/index.html", kind: "prototype-review-shell", content: Buffer.from(generated.shell) },
-  ];
-  const copies = [];
-  for (const member of report.members) {
-    const source = path.join(root, ...member.source_ref.split("/"));
-    const sourceRoot = fs.statSync(source).isDirectory() ? source : path.dirname(source);
-    for (const file of exactSourceFiles(source)) {
-      const sourceTail = fs.statSync(source).isDirectory()
-        ? toPosix(path.relative(sourceRoot, file)) : path.basename(file);
-      copies.push({
-        source_path: toPosix(path.relative(root, file)),
-        target_path: `.workflow/experience/${report.iteration_id}/prototype/source/${member.member_id}/${sourceTail}`,
-        source_sha256: sha256(fs.readFileSync(file)),
-        target_sha256: sha256(fs.readFileSync(file)),
-        transformation: "byte-for-byte",
-      });
-    }
-  }
-  const targetConflicts = [];
-  for (const operation of [...writes.map((item) => ({ ...item, target_path: item.path, target_sha256: sha256(item.content) })), ...copies]) {
-    const target = path.join(root, ...operation.target_path.split("/"));
-    if (fs.existsSync(target)) {
-      const actual = sha256(fs.readFileSync(target));
-      const reason = actual === operation.target_sha256
-        ? "migration-target-already-exists" : "migration-target-conflict";
-      targetConflicts.push(conflict("target", operation.target_path, [{
-        member_id: "existing-project",
-        record_checksum: actual,
-      }], reason));
-    }
-  }
-  Object.defineProperty(report, "_operations", {
-    enumerable: false,
-    value: { writes, copies },
-  });
-  report.file_changes = {
-    additions: writes.map((item) => ({ path: item.path, kind: item.kind, sha256: sha256(item.content) })),
-    copies,
-  };
-  report.merge_report.conflicts.push(...targetConflicts);
-  report.merge_report.conflicts.sort((left, right) => left.conflict_id.localeCompare(right.conflict_id));
-  report.unresolved_conflicts.push(...targetConflicts);
-}
-
-export function planPrototypeMigration(project, options = {}) {
-  const root = path.resolve(project);
-  const iterationId = currentIterationId(root);
-  const sets = discoverLegacySets(root, iterationId);
-  const openSets = sets.filter((item) => item.scope === "open");
-  const preservedHistory = sets.filter((item) => item.scope !== "open").map((item) => ({
-    iteration_id: item.iteration_id,
-    scope: item.scope,
-    set_ref: toPosix(path.relative(root, item.file)),
-    set_checksum: sha256(fs.readFileSync(item.file)),
-    policy: "byte-for-byte-preserved",
-  }));
-  const targetRelative = iterationId ? `.workflow/experience/${iterationId}/prototype.yaml` : null;
-  const targetFile = targetRelative ? path.join(root, ...targetRelative.split("/")) : null;
-  const existingCurrent = targetFile && fs.existsSync(targetFile) ? readYaml(targetFile, "current Prototype") : null;
-  const loaded = loadOpenMembers(root, openSets);
-  const merged = mergeReport(loaded);
-  const sourceFiles = [...loaded.sourceFiles].sort((left, right) => left.localeCompare(right));
-  const legacySourceChecksum = sha256(stableJson(sourceFiles.map((file) => ({
-    path: toPosix(path.relative(root, file)),
-    sha256: sha256(fs.readFileSync(file)),
-  }))));
-  const report = {
-    schema_version: 1,
-    status: "not-required",
-    applied: false,
-    iteration_id: iterationId,
-    source_checksum: legacySourceChecksum,
-    member_count: loaded.declaredMemberCount,
-    valid_member_count: loaded.members.length,
-    invalid_member_count: loaded.declaredMemberCount - loaded.members.length,
-    legacy_sets: openSets.map((item) => ({
-      iteration_id: item.iteration_id,
-      ref: toPosix(path.relative(root, item.file)),
-      checksum: sha256(fs.readFileSync(item.file)),
-    })),
-    members: loaded.members.map((member) => ({
-      member_id: member.member_id,
-      manifest_ref: member.manifest_ref,
-      manifest_checksum: member.manifest_checksum,
-      source_ref: member.source_ref,
-      source_checksum: member.source_checksum,
-      terminal_ids: member.terminal_ids,
-    })),
-    target: {
-      prototype_id: TARGET_PROTOTYPE_ID,
-      descriptor_ref: targetRelative,
-      experience_ref: iterationId ? `.workflow/experience/${iterationId}` : null,
-    },
-    merge_report: merged,
-    preserved_history: preservedHistory,
-    preserved_sources: sourceFiles.map((file) => ({
-      path: toPosix(path.relative(root, file)),
-      sha256: sha256(fs.readFileSync(file)),
-    })),
-    approval: {
-      required_gate: loaded.declaredMemberCount ? "UX-UI" : null,
-      existing_approval_reused: false,
-      policy: loaded.declaredMemberCount ? "fresh-approval-required" : "not-applicable",
-    },
-    required_follow_up: {
-      command: "ai-delivery migrate",
-      write_planned: false,
-    },
-  };
-  applyDecisions(report, options.decisionsFile, options.sourceChecksum);
-  report.can_apply = report.unresolved_conflicts.length === 0;
-  if (!iterationId || !openSets.length || !loaded.members.length) {
-    report.status = report.unresolved_conflicts.length ? "blocked" : "not-required";
-    report.file_changes = { additions: [], copies: [] };
-    report.can_apply = report.unresolved_conflicts.length === 0;
-    return report;
-  }
-  if (existingCurrent) {
-    if (existingCurrent.artifact_type !== "prototype-current"
-        || existingCurrent.prototype_id !== TARGET_PROTOTYPE_ID) {
-      report.unresolved_conflicts.push(conflict("target", targetRelative, [{
-        member_id: "existing-project",
-        record_checksum: sha256(stableJson(existingCurrent)),
-      }], "incompatible-current-prototype"));
-      report.can_apply = false;
-      report.status = "blocked";
-    } else {
-      report.status = "already-current";
-      report.can_apply = true;
-    }
-    report.file_changes = { additions: [], copies: [] };
-    return report;
-  }
-  if (report.can_apply) buildOperations(root, report);
-  report.can_apply = report.unresolved_conflicts.length === 0;
-  report.status = report.can_apply ? "ready" : "blocked";
-  return report;
-}
-
-export function applyPrototypeMigration(project, report) {
-  const root = path.resolve(project);
-  if (report.status === "not-required" || report.status === "already-current") return report;
-  if (!report.can_apply || !report._operations) {
-    throw new Error("Prototype migration requires checksum-bound human decisions before apply.");
-  }
-  for (const source of report.preserved_sources) {
-    const file = path.join(root, ...source.path.split("/"));
-    if (!fs.existsSync(file) || sha256(fs.readFileSync(file)) !== source.sha256) {
-      throw new Error(`Legacy Prototype source changed during apply: ${source.path}.`);
-    }
-  }
-  const created = [];
-  try {
-    for (const write of report._operations.writes) {
-      const target = path.join(root, ...write.path.split("/"));
-      if (fs.existsSync(target)) throw new Error(`Prototype migration target already exists: ${write.path}.`);
-      atomicWrite(target, write.content);
-      created.push(target);
-    }
-    for (const copy of report._operations.copies) {
-      const source = path.join(root, ...copy.source_path.split("/"));
-      const target = path.join(root, ...copy.target_path.split("/"));
-      if (fs.existsSync(target) || sha256(fs.readFileSync(source)) !== copy.source_sha256) {
-        throw new Error(`Prototype migration copy changed during apply: ${copy.source_path}.`);
-      }
-      atomicWrite(target, fs.readFileSync(source));
-      created.push(target);
-    }
-  } catch (error) {
-    for (const file of created.reverse()) fs.rmSync(file, { force: true });
-    throw error;
-  }
-  report.applied = true;
-  return report;
-}
-
-export function rollbackPrototypeMigration(project, report) {
-  if (!report?.file_changes) return;
-  const root = path.resolve(project);
-  const files = [
-    ...(report.file_changes.copies || []).map((item) => ({ path: item.target_path, sha256: item.target_sha256 })),
-    ...(report.file_changes.additions || []).map((item) => ({ path: item.path, sha256: item.sha256 })),
-  ].reverse();
-  for (const item of files) {
-    const file = path.join(root, ...item.path.split("/"));
-    if (!fs.existsSync(file) || sha256(fs.readFileSync(file)) !== item.sha256) {
-      throw new Error(`Migrated Prototype bytes changed; rollback is blocked: ${item.path}.`);
-    }
-  }
-  for (const item of files) fs.rmSync(path.join(root, ...item.path.split("/")), { force: true });
-}