ai-delivery-workflow 0.2.2 → 0.4.0

package/lib/stable-value.mjs

@@ -0,0 +1,15 @@
+import crypto from "node:crypto";
+
+export 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])]));
+}
+
+export function sameStableValue(left, right) {
+  return JSON.stringify(stableValue(left)) === JSON.stringify(stableValue(right));
+}
+
+export function stableValueChecksum(value) {
+  return crypto.createHash("sha256").update(JSON.stringify(stableValue(value))).digest("hex");
+}

package/lib/toml-hooks.mjs

@@ -49,6 +49,55 @@ function replaceFeatureHooksFalse(text) {
   return `${text.slice(0, sectionStart)}${section.replace(assignment, "$1true$2")}${text.slice(sectionEnd)}`;
 }
 
+function removeDeliveryHandlerBlocks(text) {
+  const newline = text.includes("\r\n") ? "\r\n" : "\n";
+  const lines = text.split(/\r?\n/);
+  const groups = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    if (!/^\s*\[\[hooks\.[^.\]]+\]\]\s*$/.test(lines[index])) continue;
+    const end = lines.findIndex((line, candidate) =>
+      candidate > index && /^\s*\[\[hooks\.[^.\]]+\]\]\s*$/.test(line));
+    groups.push({ start: index, end: end === -1 ? lines.length : end });
+    index = (end === -1 ? lines.length : end) - 1;
+  }
+  let changed = false;
+  const output = [];
+  let cursor = 0;
+  for (const group of groups) {
+    output.push(...lines.slice(cursor, group.start));
+    const groupLines = lines.slice(group.start, group.end);
+    const remove = new Set();
+    for (let index = 0; index < groupLines.length; index += 1) {
+      if (!/^\s*\[\[hooks\.[^.\]]+\.hooks\]\]\s*$/.test(groupLines[index])) continue;
+      let end = index + 1;
+      while (end < groupLines.length && !/^\s*\[\[/.test(groupLines[end])) end += 1;
+      const handlerLines = groupLines.slice(index, end);
+      if (handlerLines.some((line) =>
+        /^\s*command(?:Windows)?\s*=/.test(line) && line.includes(`"${HOOK_COMMAND}"`))) {
+        for (let candidate = index; candidate < end; candidate += 1) {
+          if (candidate === index
+            || (groupLines[candidate].trim() && !/^\s*#/.test(groupLines[candidate]))) {
+            remove.add(candidate);
+          }
+        }
+        changed = true;
+      }
+      index = end - 1;
+    }
+    const retained = groupLines.filter((_, index) => !remove.has(index));
+    const onlyEmptyManagedMatcher = retained.every((line) =>
+      !line.trim()
+      || /^\s*#/.test(line)
+      || /^\s*\[\[hooks\.[^.\]]+\]\]\s*$/.test(line)
+      || /^\s*matcher\s*=\s*""\s*$/.test(line));
+    const hasUserComment = retained.some((line) => /^\s*#/.test(line));
+    if (!onlyEmptyManagedMatcher || hasUserComment || !remove.size) output.push(...retained);
+    cursor = group.end;
+  }
+  output.push(...lines.slice(cursor));
+  return { text: output.join(newline), changed };
+}
+
 export function mergeHookConfig(existing, { force = false } = {}) {
   const newline = existing.includes("\r\n") ? "\r\n" : "\n";
   let text = existing.trimEnd();
@@ -57,6 +106,11 @@ export function mergeHookConfig(existing, { force = false } = {}) {
     text = text.replaceAll(LEGACY_HOOK_COMMAND, HOOK_COMMAND);
     actions.push("migrate AI delivery Hook command into .workflow/tools");
   }
+  if (force) {
+    const refreshed = removeDeliveryHandlerBlocks(text);
+    text = refreshed.text.trimEnd();
+    if (refreshed.changed) actions.push("refresh AI delivery Hook handlers");
+  }
   let config = text ? parse(text) : {};
 
   if (config.features?.hooks === false && !force) {
@@ -95,3 +149,18 @@ export function inspectHookConfig(text) {
     registeredEvents: HOOK_EVENTS.filter((event) => hasDeliveryHandler(config, event)),
   };
 }
+
+export function managedHookConfigProjection(text) {
+  const config = parse(text);
+  return {
+    hooks_enabled: config.features?.hooks ?? null,
+    events: HOOK_EVENTS.map((event) => ({
+      event,
+      handlers: (config.hooks?.[event] || []).flatMap((matcher) =>
+        (matcher.hooks || [])
+          .filter((handler) => handler?.command === HOOK_COMMAND
+            || handler?.commandWindows === HOOK_COMMAND)
+          .map((handler) => ({ matcher: matcher.matcher ?? null, handler }))),
+    })),
+  };
+}

package/lib/ui-acceptance.mjs

@@ -0,0 +1,565 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  readYamlMapping,
+  requireSha256,
+  resolveContainedPath,
+  sha256File,
+} from "./artifact-files.mjs";
+import { parsePrototypeCatalogCsv } from "./prototype-revision.mjs";
+import { buildPrototypeReviewTarget } from "./prototype-review-target.mjs";
+import { validateFrozenMockScenarioPack } from "./mock-scenario-pack.mjs";
+import { mockProtocolExpectation, validateMockDefinition } from "./mock-system.mjs";
+import { verifyVisualPngEvidence } from "./png-evidence.mjs";
+import { sameStableValue, stableValueChecksum } from "./stable-value.mjs";
+
+const candidateAssuranceNode = "05-candidate-assurance";
+const defaultViewports = [
+  { viewport_id: "mobile", width: 390, height: 844 },
+  { viewport_id: "tablet", width: 768, height: 1024 },
+  { viewport_id: "desktop", width: 1440, height: 900 },
+];
+const traceabilityHeader = [
+  "task_id", "prototype_revision_id", "source_revision", "terminal_id", "page_id",
+  "review_scene_id", "prototype_element_id", "ui_mapping_id", "ui_component_id",
+  "frontend_source_ref", "acceptance_id",
+].join(",");
+
+function boundFile(root, binding, label) {
+  if (binding?.algorithm !== "sha256") throw new Error(`${label} must use sha256.`);
+  const file = resolveContainedPath(root, binding.ref, label);
+  const checksum = requireSha256(binding.checksum, label);
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile() || sha256File(file) !== checksum) {
+    throw new Error(`${label} checksum mismatch.`);
+  }
+  return { file, checksum };
+}
+
+function registeredArtifact(projectRoot, registry, artifactId, type, checksum, status) {
+  const artifact = (registry.artifacts || []).find((item) =>
+    (item.artifact_id || item.id) === artifactId);
+  if (!artifact || artifact.artifact_type !== type || artifact.status !== status
+      || artifact.checksum_algorithm !== "sha256" || artifact.checksum !== checksum) {
+    throw new Error(`${type} ${artifactId} is not registered as ${status} with the exact checksum.`);
+  }
+  const file = resolveContainedPath(projectRoot, artifact.path, `${type} registry path`);
+  if (!fs.existsSync(file) || sha256File(file) !== checksum) {
+    throw new Error(`${type} ${artifactId} registry path checksum mismatch.`);
+  }
+  return { artifact, file };
+}
+
+function candidateBinding(projectRoot, request) {
+  const state = readYamlMapping(
+    path.join(projectRoot, ".workflow", "delivery", "workflow-state.yaml"),
+    "Workflow state",
+  );
+  const scope = state.schema_version >= 2 ? state.development_state : state;
+  const attempt = Number(scope?.node_attempts?.[candidateAssuranceNode] || 0);
+  const binding = scope?.node_candidate_bindings?.[candidateAssuranceNode];
+  if (scope?.scope_id !== request.iteration_id
+      || !scope?.active_nodes?.includes(candidateAssuranceNode)
+      || attempt !== Number(request.node_attempt)
+      || Number(binding?.node_attempt) !== attempt
+      || binding?.candidate_id !== request.candidate_id) {
+    throw new Error("UI Acceptance request does not bind the active Candidate Assurance attempt.");
+  }
+  const registry = readYamlMapping(
+    path.join(projectRoot, ".workflow", "delivery", "artifact-registry.yaml"),
+    "Artifact registry",
+  );
+  const candidateEntry = (registry.artifacts || []).find((item) =>
+    (item.artifact_id || item.id) === request.candidate_id);
+  if (!candidateEntry || candidateEntry.status !== "immutable"
+      || candidateEntry.artifact_type !== "candidate-manifest"
+      || candidateEntry.checksum_algorithm !== "sha256") {
+    throw new Error(`Candidate ${request.candidate_id} is not registered as immutable.`);
+  }
+  const candidateFile = resolveContainedPath(
+    projectRoot,
+    candidateEntry.path,
+    "Candidate manifest registry path",
+  );
+  const candidateChecksum = requireSha256(candidateEntry.checksum, "Candidate manifest");
+  if (!fs.existsSync(candidateFile) || sha256File(candidateFile) !== candidateChecksum) {
+    throw new Error("Immutable candidate manifest checksum mismatch.");
+  }
+  const candidate = readYamlMapping(candidateFile, "Candidate manifest");
+  if (candidate.candidate_id !== request.candidate_id
+      || candidate.iteration_id !== request.iteration_id
+      || candidate.status !== "immutable") {
+    throw new Error("Candidate manifest identity or immutable status is invalid.");
+  }
+  return { state, scope, registry, candidate, candidateFile, candidateChecksum, attempt };
+}
+
+function readTraceability(candidateBindingValue, target, revision) {
+  const { candidate, candidateFile } = candidateBindingValue;
+  const file = resolveContainedPath(
+    path.dirname(candidateFile),
+    candidate.task_prototype_traceability_ref,
+    "Candidate Prototype traceability",
+  );
+  const checksum = requireSha256(
+    candidate.task_prototype_traceability_checksum,
+    "Candidate Prototype traceability",
+  );
+  if (!fs.existsSync(file) || sha256File(file) !== checksum) {
+    throw new Error("Candidate Prototype traceability checksum mismatch.");
+  }
+  const parsed = parsePrototypeCatalogCsv(
+    fs.readFileSync(file, "utf8"),
+    "Candidate Prototype traceability",
+  );
+  if (parsed.header !== traceabilityHeader || !parsed.rows.length) {
+    throw new Error("Candidate Prototype traceability is empty or has an invalid header.");
+  }
+  const mappingFile = resolveContainedPath(
+    target.contentRoot,
+    revision.catalogs.ui_mapping.ref,
+    "Prototype UI Mapping catalog",
+  );
+  if (sha256File(mappingFile) !== requireSha256(
+    revision.catalogs.ui_mapping.checksum,
+    "Prototype UI Mapping catalog",
+  ) || candidate.ui_mapping_checksum !== revision.catalogs.ui_mapping.checksum) {
+    throw new Error("Candidate UI Mapping checksum mismatch.");
+  }
+  const mappings = parsePrototypeCatalogCsv(
+    fs.readFileSync(mappingFile, "utf8"),
+    "Prototype UI Mapping catalog",
+  ).rows.filter((item) => item.lifecycle_status === "active");
+  const mappingById = new Map(mappings.map((item) => [item.ui_mapping_id, item]));
+  const pageIds = new Set();
+  const explicitSceneIds = new Set();
+  for (const row of parsed.rows) {
+    const mapping = mappingById.get(row.ui_mapping_id);
+    if (row.prototype_revision_id !== target.targetId
+        || row.source_revision !== revision.source.revision
+        || !mapping
+        || mapping.page_id !== row.page_id
+        || mapping.review_scene_id !== row.review_scene_id) {
+      throw new Error(`Candidate Prototype traceability row is inconsistent: ${row.task_id}.`);
+    }
+    pageIds.add(row.page_id);
+    if (row.review_scene_id) explicitSceneIds.add(row.review_scene_id);
+  }
+  const scenes = target.reviewScenes.filter((scene) => pageIds.has(scene.page_id));
+  if (explicitSceneIds.size && scenes.some((scene) => !explicitSceneIds.has(scene.review_scene_id))) {
+    throw new Error("Candidate Prototype traceability does not cover every Scene of an affected Page.");
+  }
+  return {
+    checksum,
+    pageIds: [...pageIds].sort(),
+    scenes: scenes.sort((left, right) => left.review_scene_id.localeCompare(right.review_scene_id)),
+    mappings,
+  };
+}
+
+function acceptancePolicy(experienceRoot) {
+  const confirmation = readYamlMapping(
+    path.join(experienceRoot, "visual-system-confirmation.yaml"),
+    "Visual Standard confirmation",
+  );
+  const directionBinding = boundFile(experienceRoot, {
+    ref: confirmation.visual_direction_ref,
+    algorithm: "sha256",
+    checksum: confirmation.visual_direction_checksum,
+  }, "Visual direction");
+  const direction = readYamlMapping(directionBinding.file, "Visual direction");
+  const configured = direction.responsive_breakpoints;
+  const viewports = Array.isArray(configured) && configured.length ? configured : defaultViewports;
+  const normalized = viewports.map((item) => ({
+    viewport_id: String(item?.viewport_id || ""),
+    width: Number(item?.width),
+    height: Number(item?.height),
+  }));
+  if (normalized.some((item) => !/^[a-z][a-z0-9-]*$/.test(item.viewport_id)
+      || !Number.isInteger(item.width) || item.width <= 0
+      || !Number.isInteger(item.height) || item.height <= 0)
+      || new Set(normalized.map((item) => item.viewport_id)).size !== normalized.length) {
+    throw new Error("Approved Visual Standard responsive breakpoints are invalid.");
+  }
+  const maxDiff = direction.ui_acceptance?.max_diff_pixel_ratio ?? 0.001;
+  if (typeof maxDiff !== "number" || maxDiff < 0 || maxDiff > 1) {
+    throw new Error("Approved maxDiffPixelRatio is invalid.");
+  }
+  return { viewports: normalized, max_diff_pixel_ratio: maxDiff };
+}
+
+function pinnedRunner(runner) {
+  if (runner?.engine !== "playwright"
+      || !/^\d+\.\d+\.\d+$/.test(String(runner.package_version || ""))
+      || !new Set(["chromium", "firefox", "webkit"]).has(runner.browser)
+      || !/^\d+(?:\.\d+)+$/.test(String(runner.browser_version || ""))
+      || !String(runner.environment_image || "")
+      || !/^sha256:[a-f0-9]{64}$/.test(String(runner.environment_digest || ""))) {
+    throw new Error("UI Acceptance requires an exact pinned Playwright environment.");
+  }
+  return {
+    engine: runner.engine,
+    package_version: runner.package_version,
+    browser: runner.browser,
+    browser_version: runner.browser_version,
+    environment_image: runner.environment_image,
+    environment_digest: runner.environment_digest,
+  };
+}
+
+export function planUiAcceptance(projectRoot, options = {}) {
+  const root = path.resolve(projectRoot);
+  const requestFile = resolveContainedPath(root, options.request, "UI Acceptance request");
+  const request = readYamlMapping(requestFile, "UI Acceptance request");
+  if (request.schema_version !== 1 || request.artifact_type !== "ui-acceptance-request"
+      || !request.iteration_id || !request.candidate_id || !Number.isInteger(request.node_attempt)) {
+    throw new Error("UI Acceptance request identity or Candidate Assurance binding is invalid.");
+  }
+  const candidate = candidateBinding(root, request);
+  const experienceRef = String(request.experience_ref || "");
+  const experienceRoot = resolveContainedPath(root, experienceRef, "UI Acceptance experience");
+  const target = buildPrototypeReviewTarget(root, {
+    experience: experienceRef,
+    revision: request.prototype_revision_ref,
+    now: options.now,
+  });
+  if (target.mode !== "prototype-revision" || target.iterationId !== request.iteration_id) {
+    throw new Error("UI Acceptance requires the exact frozen Prototype revision.");
+  }
+  const revision = readYamlMapping(target.revisionFile, "Prototype revision");
+  if (candidate.candidate.prototype_revision_ref
+        !== `${revision.artifact_id}@${revision.version}`
+      || candidate.candidate.prototype_revision_checksum !== target.targetChecksum
+      || candidate.candidate.prototype_source_revision !== revision.source.revision
+      || candidate.candidate.prototype_source_checksum !== revision.source.checksum
+      || candidate.candidate.prototype_review_bundle_checksum !== revision.review_bundle.checksum) {
+    throw new Error("Candidate Prototype revision binding is missing or inconsistent.");
+  }
+  const currentVisualStandardFile = path.join(experienceRoot, "visual-system-confirmation.yaml");
+  if (sha256File(currentVisualStandardFile) !== requireSha256(
+    revision.visual_standard?.checksum,
+    "Frozen Prototype Visual Standard",
+  )) {
+    throw new Error("Current Visual Standard does not match the frozen Prototype revision.");
+  }
+  registeredArtifact(
+    root,
+    candidate.registry,
+    revision.artifact_id,
+    "prototype-revision",
+    target.targetChecksum,
+    "frozen",
+  );
+  const traceability = readTraceability(candidate, target, revision);
+  for (const page of target.pages.filter((item) => traceability.pageIds.includes(item.page_id))) {
+    if (page.review_status !== "approved") {
+      throw new Error(`UI Acceptance requires a current approved Page receipt: ${page.page_id}.`);
+    }
+  }
+
+  const packValidation = validateFrozenMockScenarioPack(root, {
+    experience: experienceRef,
+    scenarioPack: request.mock_scenario_pack_ref,
+  }, {
+    validateMockDefinition,
+    protocolExpectation: mockProtocolExpectation,
+  });
+  const { pack } = packValidation;
+  const packChecksum = packValidation.checksum;
+  if (pack.artifact_type !== "mock-scenario-pack" || pack.status !== "frozen"
+      || pack.iteration_id !== request.iteration_id
+      || pack.prototype_revision?.artifact_id !== target.targetId
+      || pack.prototype_revision?.checksum !== target.targetChecksum
+      || pack.prototype_revision?.source_checksum !== revision.source.checksum
+      || pack.prototype_revision?.review_bundle_checksum !== revision.review_bundle.checksum
+      || candidate.candidate.mock_scenario_pack_ref !== `${pack.artifact_id}@${pack.version}`
+      || candidate.candidate.mock_scenario_pack_checksum !== packChecksum) {
+    throw new Error("Candidate Mock Scenario Pack binding is missing, stale, or inconsistent.");
+  }
+  registeredArtifact(
+    root,
+    candidate.registry,
+    pack.artifact_id,
+    "mock-scenario-pack",
+    packChecksum,
+    "frozen",
+  );
+  const scenarioByScene = new Map();
+  for (const mapping of Array.isArray(pack.scenario_mappings) ? pack.scenario_mappings : []) {
+    if (!mapping.review_scene_id || !mapping.scenario_id
+        || !new Set(["external-dependency", "product-backend"]).has(mapping.mock_kind)
+        || scenarioByScene.has(mapping.review_scene_id)) {
+      throw new Error("Mock Scenario Pack contains an invalid or duplicate Scene mapping.");
+    }
+    scenarioByScene.set(mapping.review_scene_id, mapping);
+  }
+  if (traceability.scenes.some((scene) => !scenarioByScene.has(scene.review_scene_id))) {
+    throw new Error("Mock Scenario Pack does not cover every affected Review Scene.");
+  }
+  const strategyBinding = boundFile(root, request.test_strategy, "Approved test strategy");
+  const strategy = readYamlMapping(strategyBinding.file, "Approved test strategy");
+  if (strategy.decision !== "approved") throw new Error("Candidate test strategy is not approved.");
+  const mockKinds = new Set(traceability.scenes.map((scene) =>
+    scenarioByScene.get(scene.review_scene_id).mock_kind));
+  if (mockKinds.has("external-dependency")
+      && strategy.external_dependency_mock_allowed_in_candidate_assurance !== true) {
+    throw new Error("External Dependency Mock is not allowed by the approved test strategy.");
+  }
+  const policy = acceptancePolicy(experienceRoot);
+  const runner = pinnedRunner(request.runner);
+  const mappingByScene = new Map(traceability.mappings
+    .filter((item) => item.target_kind === "review-scene")
+    .map((item) => [item.review_scene_id, item]));
+  const executions = [];
+  for (const scene of traceability.scenes) {
+    const scenario = scenarioByScene.get(scene.review_scene_id);
+    const mapping = mappingByScene.get(scene.review_scene_id);
+    for (const viewport of policy.viewports) {
+      executions.push({
+        execution_id: `${scene.page_id}/${scene.review_scene_id}/${viewport.viewport_id}`,
+        terminal_id: scene.terminal_id,
+        page_id: scene.page_id,
+        review_scene_id: scene.review_scene_id,
+        viewport_id: viewport.viewport_id,
+        prototype_route: scene.prototype_route,
+        production_route: scene.production_route,
+        trigger_condition_id: scene.trigger_condition_id,
+        fixture_ref: scene.trigger?.fixture_ref || null,
+        ui_mapping_id: mapping.ui_mapping_id,
+        acceptance_id: mapping.acceptance_id,
+        mock_id: scenario.mock_id,
+        mock_kind: scenario.mock_kind,
+        scenario_id: scenario.scenario_id,
+        protocol: scenario.protocol,
+        operation_or_channel: scenario.operation_or_channel,
+        protocol_expectation: packValidation.expectations.get(scene.review_scene_id),
+      });
+    }
+  }
+  const plan = {
+    valid: true,
+    action: "plan",
+    iteration_id: request.iteration_id,
+    candidate: {
+      candidate_id: request.candidate_id,
+      manifest_checksum: candidate.candidateChecksum,
+      node_attempt: candidate.attempt,
+    },
+    prototype_revision: {
+      artifact_id: target.targetId,
+      checksum: target.targetChecksum,
+      source_revision: revision.source.revision,
+      review_bundle_checksum: revision.review_bundle.checksum,
+      ui_mapping_checksum: revision.catalogs.ui_mapping.checksum,
+    },
+    visual_standard: {
+      ref: revision.visual_standard.ref,
+      checksum: revision.visual_standard.checksum,
+    },
+    mock_scenario_pack: {
+      artifact_id: pack.artifact_id,
+      checksum: packChecksum,
+    },
+    test_strategy: {
+      ref: request.test_strategy.ref,
+      checksum: strategyBinding.checksum,
+    },
+    runner,
+    policy,
+    affected_page_ids: traceability.pageIds,
+    affected_review_scene_ids: traceability.scenes.map((scene) => scene.review_scene_id),
+    real_product_backend_evidence_required: mockKinds.has("product-backend"),
+    executions,
+  };
+  return { ...plan, plan_checksum: stableValueChecksum(plan) };
+}
+
+function requirePassingCheck(projectRoot, check, label) {
+  if (check?.status !== "passed") throw new Error(`${label} did not pass.`);
+  boundFile(projectRoot, check.evidence, `${label} evidence`);
+}
+
+function readJsonEvidence(file, label) {
+  try {
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw new Error("expected an object");
+    }
+    return value;
+  } catch (error) {
+    throw new Error(`${label} is not valid JSON evidence: ${error.message}`);
+  }
+}
+
+function validateRealProductBackendEvidence(projectRoot, real, plan) {
+  const environment = real?.environment;
+  if (real?.status !== "passed" || real?.source !== "real-product-backend"
+      || !sameStableValue(real.candidate, plan.candidate)
+      || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(String(environment?.environment_id || ""))
+      || !String(environment?.deployment_ref || "").trim()
+      || !/^sha256:[a-f0-9]{64}$/.test(String(environment?.deployment_digest || ""))
+      || environment?.product_backend_mock_enabled !== false) {
+    throw new Error(
+      "Product Backend Mock cannot replace real product backend acceptance evidence: candidate or environment binding is invalid.",
+    );
+  }
+  const binding = boundFile(projectRoot, real.evidence, "Real product backend acceptance evidence");
+  const evidence = readJsonEvidence(binding.file, "Real product backend acceptance evidence");
+  const expected = {
+    schema_version: 1,
+    artifact_type: "real-product-backend-acceptance-evidence",
+    status: "passed",
+    source: "real-product-backend",
+    candidate: plan.candidate,
+    environment,
+    checks: {
+      contract: "passed",
+      end_to_end: "passed",
+    },
+  };
+  if (!sameStableValue(evidence, expected)) {
+    throw new Error("Real product backend evidence does not bind the candidate and non-Mock environment.");
+  }
+}
+
+export function verifyUiAcceptance(projectRoot, options = {}) {
+  const root = path.resolve(projectRoot);
+  const plan = planUiAcceptance(root, options);
+  const resultsFile = resolveContainedPath(root, options.results, "UI Acceptance results");
+  const results = readYamlMapping(resultsFile, "UI Acceptance results");
+  if (results.schema_version !== 1 || results.artifact_type !== "ui-acceptance-results"
+      || results.iteration_id !== plan.iteration_id
+      || results.status !== "passed" || results.decision !== "pass") {
+    throw new Error("UI Acceptance results identity or passing decision is invalid.");
+  }
+  if (results.plan_checksum !== plan.plan_checksum
+      || !sameStableValue(results.candidate, plan.candidate)
+      || !sameStableValue(results.prototype_revision, plan.prototype_revision)
+      || !sameStableValue(results.mock_scenario_pack, plan.mock_scenario_pack)
+      || !sameStableValue(results.runner, plan.runner)) {
+    throw new Error("UI Acceptance results do not bind the current immutable plan.");
+  }
+  if (results.candidate_assurance?.node !== candidateAssuranceNode
+      || Number(results.candidate_assurance?.node_attempt) !== plan.candidate.node_attempt
+      || results.candidate_assurance?.candidate_id !== plan.candidate.candidate_id) {
+    throw new Error("UI Acceptance results do not bind the active Candidate Assurance attempt.");
+  }
+  const expectedById = new Map(plan.executions.map((item) => [item.execution_id, item]));
+  const executions = Array.isArray(results.executions) ? results.executions : [];
+  if (executions.length !== expectedById.size
+      || new Set(executions.map((item) => item?.execution_id)).size !== executions.length
+      || executions.some((item) => !expectedById.has(item?.execution_id))) {
+    throw new Error("UI Acceptance execution coverage is incomplete or contains unexpected entries.");
+  }
+  const viewportById = new Map(plan.policy.viewports.map((item) => [item.viewport_id, item]));
+  for (const execution of executions) {
+    const expected = expectedById.get(execution.execution_id);
+    if (execution.status !== "passed" || execution.scenario_id !== expected.scenario_id
+        || execution.deterministic_rendering?.status !== "passed"
+        || execution.deterministic_rendering?.scenario_id !== expected.scenario_id
+        || (execution.deterministic_rendering?.fixture_ref || null) !== expected.fixture_ref) {
+      throw new Error(`Deterministic rendering did not pass: ${execution.execution_id}.`);
+    }
+    const visual = execution.visual;
+    const viewport = viewportById.get(expected.viewport_id);
+    const expectedPixels = viewport.width * viewport.height;
+    const changedPixels = Number(visual?.changed_pixels);
+    const totalPixels = Number(visual?.total_pixels);
+    const ratio = totalPixels > 0 ? changedPixels / totalPixels : Number.NaN;
+    if (visual?.status !== "passed" || !Number.isInteger(changedPixels) || changedPixels < 0
+        || !Number.isInteger(totalPixels) || totalPixels !== expectedPixels
+        || changedPixels > totalPixels
+        || Math.abs(Number(visual.changed_pixel_ratio) - ratio) > Number.EPSILON
+        || visual.max_diff_pixel_ratio !== plan.policy.max_diff_pixel_ratio
+        || ratio > plan.policy.max_diff_pixel_ratio) {
+      throw new Error(`Visual diff exceeds or misreports the approved policy: ${execution.execution_id}.`);
+    }
+    const prototypeEvidence = boundFile(
+      root,
+      visual.prototype,
+      `Prototype screenshot ${execution.execution_id}`,
+    );
+    const candidateEvidence = boundFile(
+      root,
+      visual.candidate,
+      `Candidate screenshot ${execution.execution_id}`,
+    );
+    const diffEvidence = boundFile(root, visual.diff, `Visual diff ${execution.execution_id}`);
+    const measured = verifyVisualPngEvidence({
+      prototype: prototypeEvidence.file,
+      candidate: candidateEvidence.file,
+      diff: diffEvidence.file,
+    }, viewport, `UI Acceptance ${execution.execution_id}`);
+    if (measured.changedPixels !== changedPixels || measured.totalPixels !== totalPixels) {
+      throw new Error(
+        `Visual diff pixel counts do not match the PNG evidence: ${execution.execution_id}.`,
+      );
+    }
+    for (const name of [
+      "interaction", "keyboard", "focus", "touch_target", "text_overflow", "responsive", "recovery",
+    ]) {
+      requirePassingCheck(root, execution[name], `${name} check ${execution.execution_id}`);
+    }
+    requirePassingCheck(root, execution.accessibility, `accessibility check ${execution.execution_id}`);
+    if (execution.accessibility.standard !== "WCAG 2.2 AA"
+        || !Array.isArray(execution.accessibility.violations)
+        || execution.accessibility.violations.length) {
+      throw new Error(`WCAG 2.2 AA acceptance failed: ${execution.execution_id}.`);
+    }
+    requirePassingCheck(root, execution.protocol, `protocol check ${execution.execution_id}`);
+    if (execution.protocol.scenario_id !== expected.scenario_id
+        || execution.protocol.operation_or_channel !== expected.operation_or_channel) {
+      throw new Error(`Protocol evidence does not match the frozen Scenario: ${execution.execution_id}.`);
+    }
+    const protocolRequest = boundFile(
+      root,
+      execution.protocol.request,
+      `Protocol request ${execution.execution_id}`,
+    );
+    const protocolResponse = boundFile(
+      root,
+      execution.protocol.response,
+      `Protocol response ${execution.execution_id}`,
+    );
+    const actualRequest = readJsonEvidence(
+      protocolRequest.file,
+      `Protocol request ${execution.execution_id}`,
+    );
+    const actualResponse = readJsonEvidence(
+      protocolResponse.file,
+      `Protocol response ${execution.execution_id}`,
+    );
+    if (!sameStableValue(actualRequest, expected.protocol_expectation?.request)
+        || !sameStableValue(actualResponse, expected.protocol_expectation?.response)) {
+      throw new Error(
+        `Protocol response or request contradicts the frozen Scenario: ${execution.execution_id}.`,
+      );
+    }
+  }
+  const expectedProductBackendMock = plan.real_product_backend_evidence_required;
+  if (results.mock_boundary?.product_backend_mock_used_for_rendering !== expectedProductBackendMock
+      || results.mock_boundary?.product_backend_mock_accepted_as_real_backend_evidence !== false) {
+    throw new Error("Product Backend Mock authority is misrepresented in UI Acceptance results.");
+  }
+  if (expectedProductBackendMock) {
+    const real = results.real_product_backend_acceptance;
+    validateRealProductBackendEvidence(root, real, plan);
+  }
+  return {
+    valid: true,
+    action: "verify",
+    decision: "pass",
+    candidate: plan.candidate,
+    plan_checksum: plan.plan_checksum,
+    results_checksum: sha256File(resultsFile),
+    execution_count: executions.length,
+    affected_page_ids: plan.affected_page_ids,
+    affected_review_scene_ids: plan.affected_review_scene_ids,
+    real_product_backend_evidence_verified: expectedProductBackendMock,
+  };
+}
+
+export function runUiAcceptanceCommand(projectRoot, action, options = {}) {
+  if (action === "plan") return planUiAcceptance(projectRoot, options);
+  if (action === "verify") return verifyUiAcceptance(projectRoot, options);
+  throw new Error(`Unknown ui-acceptance action: ${action}`);
+}