@design-ai/cli 4.55.0 → 4.56.0

package/cli/lib/site-bundle-compare.mjs

@@ -0,0 +1,157 @@
+import { SITE_BUNDLE_CHECKSUM_FILES } from "./site-content.mjs";
+import { IMPLEMENTATION_EVIDENCE_KEYS } from "./site-evidence.mjs";
+import {
+  addIssue,
+  statusFromIssues,
+} from "./site-analysis.mjs";
+import { buildSiteBundleCheckReport } from "./site-bundle-check.mjs";
+
+export function summarizeBundleForCompare(report) {
+  return {
+    directory: report.directory,
+    status: report.status,
+    valid: report.valid,
+    siteName: report.summary.siteName || "",
+    source: report.summary.source || "",
+    workspaceStatus: report.workspaceStatus || "unknown",
+    mcpStatus: report.mcpStatus || "unknown",
+    mcpProbeStatus: report.mcpProbeStatus || "unknown",
+    mcpProbeCounts: { ...report.mcpProbeCounts },
+    totalTasks: report.summary.totalTasks || 0,
+    implementationEvidence: { ...report.summary.implementationEvidence },
+    checksumAlgorithm: report.summary.checksumAlgorithm || "",
+    checksumBundleDigest: report.summary.checksumBundleDigest || "",
+    checksumFailures: report.counts.checksumFailures,
+    generatedFailures: report.counts.generatedFailures,
+    verifiedGeneratedFiles: report.counts.verifiedGeneratedFiles,
+    generatedDriftFiles: [...report.generatedContract.driftFiles],
+    issueCount: report.issues.length,
+  };
+}
+
+export function buildBundleMetadataChanges(left, right) {
+  const pairs = [
+    ["siteName", "Site name", left.summary.siteName || "", right.summary.siteName || ""],
+    ["source", "Source", left.summary.source || "", right.summary.source || ""],
+    ["workspaceStatus", "Workspace status", left.workspaceStatus || "unknown", right.workspaceStatus || "unknown"],
+    ["mcpStatus", "MCP status", left.mcpStatus || "unknown", right.mcpStatus || "unknown"],
+    ["mcpProbeStatus", "MCP probe status", left.mcpProbeStatus || "unknown", right.mcpProbeStatus || "unknown"],
+    ...["count", "pass", "warn", "fail"].map((key) => [
+      `mcpProbeCounts.${key}`,
+      `MCP probe ${key}`,
+      String(left.summary.mcpProbeCounts[key] || 0),
+      String(right.summary.mcpProbeCounts[key] || 0),
+    ]),
+    ["totalTasks", "Task count", String(left.summary.totalTasks || 0), String(right.summary.totalTasks || 0)],
+    ...IMPLEMENTATION_EVIDENCE_KEYS.map((key) => [
+      `implementationEvidence.${key}`,
+      `Evidence ${key}`,
+      String(left.summary.implementationEvidence[key] || 0),
+      String(right.summary.implementationEvidence[key] || 0),
+    ]),
+  ];
+  return pairs
+    .filter(([, , leftValue, rightValue]) => leftValue !== rightValue)
+    .map(([key, label, leftValue, rightValue]) => ({ key, label, leftValue, rightValue }));
+}
+
+export function buildBundleFileChanges(left, right) {
+  return SITE_BUNDLE_CHECKSUM_FILES
+    .map((filePath) => ({
+      path: filePath,
+      leftChecksum: String(left.summary.checksumFiles[filePath] || ""),
+      rightChecksum: String(right.summary.checksumFiles[filePath] || ""),
+    }))
+    .filter((file) => file.leftChecksum !== file.rightChecksum);
+}
+
+export function buildSiteBundleCompareReport({ target, compareTarget }) {
+  const left = buildSiteBundleCheckReport({ target });
+  const right = buildSiteBundleCheckReport({ target: compareTarget });
+  const issues = [];
+
+  if (left.status === "fail") {
+    addIssue(issues, "fail", "bundle-compare-left-invalid", "Primary bundle must pass bundle-check before comparison can be trusted");
+  } else if (left.status === "warn") {
+    addIssue(issues, "warn", "bundle-compare-left-warn", "Primary bundle has bundle-check warnings; review them before target-repo handoff");
+  }
+  if (right.status === "fail") {
+    addIssue(issues, "fail", "bundle-compare-right-invalid", "Comparison bundle must pass bundle-check before comparison can be trusted");
+  } else if (right.status === "warn") {
+    addIssue(issues, "warn", "bundle-compare-right-warn", "Comparison bundle has bundle-check warnings; review them before target-repo handoff");
+  }
+
+  const leftDigest = left.summary.checksumBundleDigest || "";
+  const rightDigest = right.summary.checksumBundleDigest || "";
+  const digestMatch = Boolean(leftDigest && rightDigest && leftDigest === rightDigest);
+  const changedFiles = buildBundleFileChanges(left, right);
+  const metadataChanges = buildBundleMetadataChanges(left, right);
+  const hasDifferences = !digestMatch || changedFiles.length > 0 || metadataChanges.length > 0;
+  const hasFailures = issues.some((issue) => issue.level === "fail");
+
+  if (issues.length === 0 && !hasDifferences) {
+    addIssue(issues, "pass", "bundle-compare-identical", "Handoff bundles have the same bundle digest and checksum manifest");
+  } else if (!hasFailures && hasDifferences) {
+    addIssue(issues, "warn", "bundle-compare-different", "Handoff bundles differ; review changed files before target-repo handoff");
+  }
+
+  const status = statusFromIssues(issues);
+  return {
+    status,
+    valid: left.valid && right.valid,
+    sameBundle: !hasDifferences,
+    digestMatch,
+    left: summarizeBundleForCompare(left),
+    right: summarizeBundleForCompare(right),
+    counts: {
+      changedFiles: changedFiles.length,
+      metadataChanges: metadataChanges.length,
+      leftIssues: left.issues.length,
+      rightIssues: right.issues.length,
+      issues: issues.length,
+      warnings: issues.filter((issue) => issue.level === "warn").length,
+      failures: issues.filter((issue) => issue.level === "fail").length,
+    },
+    changedFiles,
+    metadataChanges,
+    issues,
+  };
+}
+
+export function formatSiteBundleCompareJson(report) {
+  return JSON.stringify(report, null, 2);
+}
+
+function formatMcpProbeCounts(counts = {}) {
+  return `${counts.pass || 0}/${counts.count || 0} passing, ${counts.warn || 0} warning, ${counts.fail || 0} failing`;
+}
+
+export function formatSiteBundleCompareHuman(report) {
+  return [
+    `Website Improvement handoff bundle compare: ${report.left.directory} -> ${report.right.directory}`,
+    "",
+    `Status: ${report.status}`,
+    `Same bundle: ${report.sameBundle ? "yes" : "no"}`,
+    `Digest match: ${report.digestMatch ? "yes" : "no"}`,
+    `Left digest: ${report.left.checksumBundleDigest || "not recorded"}`,
+    `Right digest: ${report.right.checksumBundleDigest || "not recorded"}`,
+    `Changed files: ${report.counts.changedFiles}`,
+    `Metadata changes: ${report.counts.metadataChanges}`,
+    `Generated contract: left ${report.left.verifiedGeneratedFiles}/${SITE_BUNDLE_CHECKSUM_FILES.length}, right ${report.right.verifiedGeneratedFiles}/${SITE_BUNDLE_CHECKSUM_FILES.length}`,
+    `Generated drift files: left ${report.left.generatedDriftFiles.length ? report.left.generatedDriftFiles.join(", ") : "none"}, right ${report.right.generatedDriftFiles.length ? report.right.generatedDriftFiles.join(", ") : "none"}`,
+    `MCP probes: left ${formatMcpProbeCounts(report.left.mcpProbeCounts)}, right ${formatMcpProbeCounts(report.right.mcpProbeCounts)}`,
+    "",
+    "Changed files:",
+    ...(report.changedFiles.length
+      ? report.changedFiles.map((file) => `- ${file.path}`)
+      : ["- none"]),
+    "",
+    "Metadata changes:",
+    ...(report.metadataChanges.length
+      ? report.metadataChanges.map((item) => `- ${item.label}: ${item.leftValue || "not recorded"} -> ${item.rightValue || "not recorded"}`)
+      : ["- none"]),
+    "",
+    "Issues:",
+    ...report.issues.map((issue) => `- [${issue.level}] ${issue.id}: ${issue.message}`),
+  ].join("\n");
+}

package/cli/lib/site-bundle-contract.mjs

@@ -0,0 +1,79 @@
+// Generated bundle contract helpers for Website Improvement handoff bundles.
+
+import {
+  existsSync,
+  readFileSync,
+  statSync,
+} from "node:fs";
+import path from "node:path";
+
+import { addIssue } from "./site-analysis.mjs";
+import { buildSiteHandoffBundle } from "./site-bundle-build.mjs";
+import { SITE_BUNDLE_CHECKSUM_FILES } from "./site-content.mjs";
+import {
+  sha256Hex,
+  shortDigest,
+} from "./site-bundle-files.mjs";
+
+export function emptyBundleGeneratedContract(source = "") {
+  return {
+    available: false,
+    source: source || "",
+    expectedFiles: SITE_BUNDLE_CHECKSUM_FILES.length,
+    verifiedFiles: 0,
+    driftFiles: [],
+    files: [],
+  };
+}
+
+export function buildBundleGeneratedContract(directory, workspace, source) {
+  const contractSource = source || "website-workspace.tasks.json";
+  const expectedBundle = buildSiteHandoffBundle(workspace, { filePath: contractSource });
+  const expectedFiles = new Map(expectedBundle.files.map((file) => [file.path, file.content]));
+  const files = SITE_BUNDLE_CHECKSUM_FILES.map((filePath) => {
+    const expectedContent = expectedFiles.get(filePath);
+    const expectedDigest = typeof expectedContent === "string" ? sha256Hex(expectedContent) : "";
+    const targetPath = path.join(directory, filePath);
+    const present = existsSync(targetPath) && statSync(targetPath).isFile();
+    const actualDigest = present ? sha256Hex(readFileSync(targetPath, "utf8")) : "";
+    return {
+      path: filePath,
+      present,
+      matches: Boolean(present && expectedDigest && actualDigest === expectedDigest),
+      expectedDigest,
+      actualDigest,
+    };
+  });
+  return {
+    available: true,
+    source: contractSource,
+    expectedFiles: SITE_BUNDLE_CHECKSUM_FILES.length,
+    verifiedFiles: files.filter((file) => file.matches).length,
+    driftFiles: files.filter((file) => file.present && !file.matches).map((file) => file.path),
+    files,
+  };
+}
+
+export function addBundleGeneratedContractIssues(generatedContract, issues) {
+  if (!generatedContract.available) return;
+  for (const file of generatedContract.files) {
+    if (!file.present || file.matches) continue;
+    addIssue(
+      issues,
+      "fail",
+      `bundle-generated-${file.path}`,
+      `${file.path} does not match the current CLI-generated bundle contract (expected ${shortDigest(file.expectedDigest)}, actual ${shortDigest(file.actualDigest)})`,
+    );
+  }
+}
+
+export function formatGeneratedContractDriftLines(generatedContract) {
+  const driftFiles = generatedContract.files.filter((file) => file.present && !file.matches);
+  if (driftFiles.length === 0) return ["- none"];
+  return driftFiles.map((file) => `- ${file.path}: expected ${shortDigest(file.expectedDigest)}, actual ${shortDigest(file.actualDigest)}`);
+}
+
+export function formatGeneratedContractDriftSummary(generatedContract) {
+  if (!generatedContract.driftFiles.length) return "none";
+  return generatedContract.driftFiles.join(", ");
+}

package/cli/lib/site-bundle-files.mjs

@@ -0,0 +1,87 @@
+// File, digest, and validation helpers for Website Improvement handoff bundles.
+
+import {
+  existsSync,
+  readFileSync,
+  statSync,
+} from "node:fs";
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+import { SITE_BUNDLE_CHECKSUM_FILES } from "./site-content.mjs";
+
+function addIssue(issues, level, id, message) {
+  issues.push({ level, id, message });
+}
+
+export function sha256Hex(content) {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}
+
+export function shortDigest(digest) {
+  return digest ? String(digest).slice(0, 12) : "missing";
+}
+
+export function buildBundleDigest(checksumFiles) {
+  const manifest = SITE_BUNDLE_CHECKSUM_FILES.map((filePath) => `${filePath}\t${checksumFiles[filePath] || ""}`).join("\n");
+  return sha256Hex(`${manifest}\n`);
+}
+
+export function buildBundleChecksums(files) {
+  const checksumFiles = Object.fromEntries(
+    files
+      .filter((file) => file.path !== "summary.json")
+      .map((file) => [file.path, sha256Hex(file.content)]),
+  );
+  return {
+    algorithm: "sha256",
+    bundleDigest: buildBundleDigest(checksumFiles),
+    files: checksumFiles,
+  };
+}
+
+export function readBundleFile(directory, relativePath, issues) {
+  const target = path.join(directory, relativePath);
+  if (!existsSync(target)) {
+    addIssue(issues, "fail", `bundle-missing-${relativePath}`, `Bundle file is missing: ${relativePath}`);
+    return null;
+  }
+  if (!statSync(target).isFile()) {
+    addIssue(issues, "fail", `bundle-file-${relativePath}`, `Bundle path must be a file: ${relativePath}`);
+    return null;
+  }
+  return readFileSync(target, "utf8");
+}
+
+export function parseBundleJson(directory, relativePath, issues) {
+  const text = readBundleFile(directory, relativePath, issues);
+  if (text === null) return null;
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    addIssue(issues, "fail", `bundle-json-${relativePath}`, `Bundle JSON is invalid in ${relativePath}: ${error.message}`);
+    return null;
+  }
+}
+
+export function arraysEqual(left, right) {
+  if (!Array.isArray(left) || !Array.isArray(right)) return false;
+  if (left.length !== right.length) return false;
+  return left.every((item, index) => item === right[index]);
+}
+
+export function addBundleMarkdownIssue(directory, relativePath, fragments, issues) {
+  const text = readBundleFile(directory, relativePath, issues);
+  if (text === null) return;
+  for (const fragment of fragments) {
+    if (!text.includes(fragment)) {
+      addIssue(issues, "fail", `bundle-markdown-${relativePath}`, `${relativePath} is missing required text: ${fragment}`);
+    }
+  }
+}
+
+export function readBundleTextIfPresent(directory, relativePath) {
+  const targetPath = path.join(directory, relativePath);
+  if (!existsSync(targetPath) || !statSync(targetPath).isFile()) return "";
+  return readFileSync(targetPath, "utf8").trim();
+}

package/cli/lib/site-bundle-handoff-runbook-actions.mjs

@@ -0,0 +1,113 @@
+// Action metadata helpers for Website Improvement bundle handoff runbooks.
+
+export function getStageActionType(stage) {
+  if (stage.commandCount > 0 && stage.writesLocalFile) return "write-local-output";
+  if (stage.commandCount > 0 && stage.required) return "run-local-gate";
+  if (stage.commandCount > 0) return "refresh-local-preview";
+  if (stage.kind === "manual-target-repo") return "manual-target-repo";
+  if (stage.kind === "manual-reporting") return "manual-evidence";
+  return "review-stage";
+}
+
+export function getStageActionLabel(stage) {
+  return {
+    verifySourceBundle: "Run strict bundle check",
+    refreshHandoffSnapshot: "Refresh strict handoff JSON",
+    writeEffectiveTaskPrompt: "Write selected task prompt",
+    executeInTargetRepo: "Implement in target repo",
+    recordEvidence: "Record verification evidence",
+  }[stage.key] || stage.label;
+}
+
+export function getStageActionInstruction(stage) {
+  return {
+    verifySourceBundle: "Run the strict local bundle check and resolve any checksum or generated-file drift before handoff.",
+    refreshHandoffSnapshot: "Optional: regenerate the strict handoff JSON snapshot when a wrapper or GUI needs the latest contract.",
+    writeEffectiveTaskPrompt: "Write the selected task prompt to a local Markdown file before switching into the target website repo.",
+    executeInTargetRepo: "Manual: open the generated prompt in the target website repo, inspect architecture, implement the scoped task, and run target-repo verification.",
+    recordEvidence: "Manual: record changed files, verification commands, viewport checks, accessibility checks, remaining risks, and the bundle digest.",
+  }[stage.key] || stage.reason;
+}
+
+export function getStageActionButtonLabel(stage) {
+  return {
+    verifySourceBundle: "Run Check",
+    refreshHandoffSnapshot: "Refresh JSON",
+    writeEffectiveTaskPrompt: "Write Prompt",
+    executeInTargetRepo: "Open Target Repo",
+    recordEvidence: "Record Evidence",
+  }[stage.key] || getStageActionLabel(stage);
+}
+
+export function getStageActionAffordance(stage) {
+  if (stage.commandCount > 0 && stage.writesLocalFile) return "local-output-button";
+  if (stage.commandCount > 0 && stage.required) return "primary-command-button";
+  if (stage.commandCount > 0) return "secondary-command-button";
+  if (stage.kind === "manual-target-repo") return "manual-target-repo-step";
+  if (stage.kind === "manual-reporting") return "manual-evidence-step";
+  return "review-step";
+}
+
+export function getStageActionEnabled(stage) {
+  return stage.commandCount > 0;
+}
+
+export function getStageActionStatus(stage) {
+  if (stage.commandCount > 0 && stage.required) return "ready";
+  if (stage.commandCount > 0) return "optional";
+  if (stage.kind === "manual-target-repo" || stage.kind === "manual-reporting") return "manual";
+  return "blocked";
+}
+
+export function getStageActionStatusLabel(stage) {
+  return {
+    ready: "Ready",
+    optional: "Optional",
+    manual: "Manual",
+    blocked: "Blocked",
+  }[getStageActionStatus(stage)];
+}
+
+export function getStageActionStatusTone(stage) {
+  return {
+    ready: "success",
+    optional: "neutral",
+    manual: "info",
+    blocked: "danger",
+  }[getStageActionStatus(stage)];
+}
+
+export function getStageActionDisabledReasonCode(stage) {
+  if (getStageActionEnabled(stage)) return "";
+  if (stage.kind === "manual-target-repo") return "manual-target-repo-step";
+  if (stage.kind === "manual-reporting") return "manual-evidence-step";
+  return "missing-local-command";
+}
+
+export function getStageActionDisabledReason(stage) {
+  return {
+    "manual-target-repo-step": "No local design-ai command is available for this stage; execute the generated prompt inside the target website repo.",
+    "manual-evidence-step": "No local design-ai command is available for this stage; record evidence after target-repo implementation and verification.",
+    "missing-local-command": "No local command is available for this stage.",
+  }[getStageActionDisabledReasonCode(stage)] || "";
+}
+
+export function getStageActionEvidenceTarget(stage) {
+  return {
+    verifySourceBundle: "local-command-output",
+    refreshHandoffSnapshot: "local-command-output",
+    writeEffectiveTaskPrompt: "local-output-file",
+    executeInTargetRepo: "target-repo-working-tree",
+    recordEvidence: "handoff-evidence-record",
+  }[stage.key] || "not-applicable";
+}
+
+export function getStageActionEvidenceTargetLabel(stage) {
+  return {
+    "local-command-output": "Local command output",
+    "local-output-file": "Local output file",
+    "target-repo-working-tree": "Target repo working tree",
+    "handoff-evidence-record": "Handoff evidence record",
+    "not-applicable": "Not applicable",
+  }[getStageActionEvidenceTarget(stage)];
+}

package/cli/lib/site-bundle-handoff-runbook-evidence-fields.mjs

@@ -0,0 +1,164 @@
+// Stage-specific evidence capture fields for Website Improvement bundle handoff runbooks.
+
+import {
+  getStageActionEvidenceTarget,
+} from "./site-bundle-handoff-runbook-actions.mjs";
+import {
+  getEvidenceCaptureFieldAriaLabel,
+  getEvidenceCaptureFieldEmptyValue,
+  getEvidenceCaptureFieldHelpText,
+  getEvidenceCaptureFieldPayloadNamespace,
+  getEvidenceCaptureFieldPayloadPath,
+  getEvidenceCaptureFieldRequirementLabel,
+  getEvidenceCaptureFieldSectionKey,
+  getEvidenceCaptureFieldSectionLabel,
+  getEvidenceCaptureFieldValueShape,
+} from "./site-bundle-handoff-runbook-evidence.mjs";
+
+export function getStageActionEvidenceCaptureFields(stage) {
+  return ({
+    verifySourceBundle: [
+      {
+        key: "strictBundleCheckOutput",
+        label: "Strict bundle-check output",
+        inputType: "textarea",
+        required: true,
+        evidenceTarget: getStageActionEvidenceTarget(stage),
+        placeholder: "Paste the strict bundle-check pass output or JSON status.",
+        validationRule: "non-empty-text",
+        minLength: 20,
+        example: "Status: pass; checksumFailures: 0; generatedFailures: 0",
+        validationHint: "Required: paste a passing strict bundle-check result.",
+      },
+      {
+        key: "bundleDigest",
+        label: "Bundle digest",
+        inputType: "text",
+        required: true,
+        evidenceTarget: getStageActionEvidenceTarget(stage),
+        placeholder: "Record the bundle digest or checksum summary.",
+        validationRule: "checksum-or-digest-text",
+        minLength: 8,
+        example: "7685113af4744990fadf301b220b4739066e5f6ec2c40857825211e1167241aa",
+        validationHint: "Required: record a digest, checksum, or equivalent bundle integrity summary.",
+      },
+    ],
+    refreshHandoffSnapshot: [
+      {
+        key: "handoffJsonSnapshot",
+        label: "Strict handoff JSON snapshot",
+        inputType: "textarea",
+        required: false,
+        evidenceTarget: getStageActionEvidenceTarget(stage),
+        placeholder: "Paste or link the refreshed strict handoff JSON snapshot when used.",
+        validationRule: "optional-json-snapshot",
+        minLength: 0,
+        example: "{ \"status\": \"pass\", \"operatorRunbook\": { ... } }",
+        validationHint: "Optional: paste the refreshed strict handoff JSON snapshot when available.",
+      },
+    ],
+    writeEffectiveTaskPrompt: [
+      {
+        key: "promptOutputFile",
+        label: "Prompt output file",
+        inputType: "file-path",
+        required: true,
+        evidenceTarget: getStageActionEvidenceTarget(stage),
+        placeholder: "target-repo-task-...-handoff.md",
+        validationRule: "local-markdown-file-path",
+        minLength: 12,
+        example: "target-repo-task-accessibility-handoff.md",
+        validationHint: "Required: record the local Markdown prompt file path generated for the selected task.",
+      },
+      {
+        key: "selectedTaskId",
+        label: "Selected task id",
+        inputType: "text",
+        required: true,
+        evidenceTarget: getStageActionEvidenceTarget(stage),
+        placeholder: "task-...",
+        validationRule: "task-id",
+        minLength: 5,
+        example: "task-accessibility",
+        validationHint: "Required: record the bundle task id used for the target-repo handoff prompt.",
+      },
+    ],
+    executeInTargetRepo: [
+      {
+        key: "targetRepoChangedFiles",
+        label: "Target repo changed files",
+        inputType: "list",
+        required: true,
+        evidenceTarget: getStageActionEvidenceTarget(stage),
+        placeholder: "List changed files from the target website repo.",
+        validationRule: "non-empty-file-list",
+        minLength: 1,
+        example: "src/components/Header.tsx",
+        validationHint: "Required: list at least one changed target-repo file or a no-change justification.",
+      },
+      {
+        key: "targetRepoVerificationResults",
+        label: "Target repo verification results",
+        inputType: "textarea",
+        required: true,
+        evidenceTarget: getStageActionEvidenceTarget(stage),
+        placeholder: "Record lint, typecheck, build, test, or equivalent command results.",
+        validationRule: "verification-results",
+        minLength: 20,
+        example: "npm test: pass; npm run build: pass",
+        validationHint: "Required: record target-repo verification commands and results.",
+      },
+      {
+        key: "viewportAccessibilityNotes",
+        label: "Viewport and accessibility notes",
+        inputType: "textarea",
+        required: true,
+        evidenceTarget: getStageActionEvidenceTarget(stage),
+        placeholder: "Record desktop/tablet/mobile checks, keyboard focus, contrast, and screen-reader notes.",
+        validationRule: "viewport-accessibility-notes",
+        minLength: 20,
+        example: "desktop/tablet/mobile checked; focus visible; contrast AA",
+        validationHint: "Required: document viewport coverage plus keyboard, contrast, and screen-reader notes.",
+      },
+    ],
+    recordEvidence: [
+      {
+        key: "finalEvidenceRecord",
+        label: "Final evidence record",
+        inputType: "textarea",
+        required: true,
+        evidenceTarget: getStageActionEvidenceTarget(stage),
+        placeholder: "Summarize changed files, verification, viewport/accessibility checks, risks, and digest.",
+        validationRule: "final-evidence-record",
+        minLength: 30,
+        example: "Changed files recorded; verification passed; digest captured",
+        validationHint: "Required: summarize changes, verification, viewport/accessibility checks, risks, and digest.",
+      },
+      {
+        key: "remainingRisks",
+        label: "Remaining risks",
+        inputType: "textarea",
+        required: true,
+        evidenceTarget: getStageActionEvidenceTarget(stage),
+        placeholder: "List unresolved risks, skipped checks, or follow-up tasks.",
+        validationRule: "risk-notes",
+        minLength: 10,
+        example: "Stakeholder copy review still pending",
+        validationHint: "Required: record unresolved risks, skipped checks, or confirm none remain.",
+      },
+    ],
+  }[stage.key] || []).map((field) => ({
+    ...field,
+    valueShape: getEvidenceCaptureFieldValueShape(field),
+    acceptsMultiple: field.inputType === "list",
+    defaultValue: getEvidenceCaptureFieldEmptyValue(field),
+    emptyValue: getEvidenceCaptureFieldEmptyValue(field),
+    requirementLabel: getEvidenceCaptureFieldRequirementLabel(field),
+    ariaLabel: getEvidenceCaptureFieldAriaLabel(field),
+    helpText: getEvidenceCaptureFieldHelpText(field),
+    sectionKey: getEvidenceCaptureFieldSectionKey(field),
+    sectionLabel: getEvidenceCaptureFieldSectionLabel(field),
+    payloadNamespace: getEvidenceCaptureFieldPayloadNamespace(field),
+    payloadPath: getEvidenceCaptureFieldPayloadPath(field),
+  }));
+}