@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-headless-replatform/scripts/extract-seo.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { docsDir, fetchText, normalizeUrl, parseArgs, resolveOutputDir, writeJson } from "./lib/common.mjs";
+import { extractSeo } from "./lib/html-extract.mjs";
+
+async function main() {
+  const args = parseArgs();
+  const url = normalizeUrl(args._[0] || args.url).toString();
+  const outputDir = resolveOutputDir(url, args.out);
+  const seo = await extractSeoForUrl(url);
+  await writeJson(path.join(docsDir(outputDir), "seo.json"), seo);
+  if (args.json) process.stdout.write(`${JSON.stringify(seo, null, 2)}\n`);
+}
+
+export async function extractSeoForUrl(url) {
+  const html = await fetchText(url);
+  return extractSeo(html, url);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error.stack || error.message);
+    process.exit(1);
+  });
+}

package/skills/wix-headless-replatform/scripts/extract-tokens.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { docsDir, normalizeUrl, parseArgs, readJson, resolveOutputDir, writeJson } from "./lib/common.mjs";
+
+async function main() {
+  const args = parseArgs();
+  const url = normalizeUrl(args._[0] || args.url).toString();
+  const outputDir = resolveOutputDir(url, args.out);
+  const tokens = await extractTokens({ outputDir });
+  await writeJson(path.join(docsDir(outputDir), "tokens.json"), tokens);
+  if (args.json) process.stdout.write(`${JSON.stringify(tokens, null, 2)}\n`);
+}
+
+export async function extractTokens({ outputDir }) {
+  const sourceMapPath = path.join(docsDir(outputDir), "source-map.json");
+  let sourceMap = { pages: [] };
+  try {
+    sourceMap = await readJson(sourceMapPath);
+  } catch {
+    // Allow standalone use before source-map exists.
+  }
+  const colors = new Set();
+  const fonts = new Set();
+  const radii = new Set();
+  const shadows = new Set();
+  const fontSizes = new Set();
+
+  for (const page of sourceMap.pages || []) {
+    for (const color of page.tokens?.colors || []) colors.add(color);
+    for (const font of page.tokens?.fontFamilies || []) fonts.add(font);
+    for (const radius of page.tokens?.radii || []) radii.add(radius);
+    for (const shadow of page.tokens?.shadows || []) shadows.add(shadow);
+    for (const item of page.tokens?.computed || []) {
+      if (item.color && item.color !== "rgba(0, 0, 0, 0)") colors.add(item.color);
+      if (item.backgroundColor && item.backgroundColor !== "rgba(0, 0, 0, 0)") colors.add(item.backgroundColor);
+      if (item.fontFamily) fonts.add(item.fontFamily);
+      if (item.fontSize) fontSizes.add(item.fontSize);
+      if (item.borderRadius && item.borderRadius !== "0px") radii.add(item.borderRadius);
+      if (item.boxShadow && item.boxShadow !== "none") shadows.add(item.boxShadow);
+    }
+  }
+
+  return {
+    colors: Array.from(colors).slice(0, 32),
+    fontFamilies: Array.from(fonts).slice(0, 16),
+    fontSizes: Array.from(fontSizes).slice(0, 16),
+    radii: Array.from(radii).slice(0, 16),
+    shadows: Array.from(shadows).slice(0, 16),
+    recommendedTailwindTokens: {
+      colors: "Map primary, secondary, background, foreground, muted, accent, border from extracted colors.",
+      fonts: "Map sans/display/body from extracted font families and local downloaded fonts.",
+      spacing: "Infer from section rhythm; start with Tailwind defaults and add container widths.",
+    },
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error.stack || error.message);
+    process.exit(1);
+  });
+}

package/skills/wix-headless-replatform/scripts/finalize-extraction-report.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { docsDir, parseArgs, readJson, writeJson, writeText } from "./lib/common.mjs";
+import { EXTRACTION_SCHEMA_VERSION, assertValidArtifact } from "./lib/extraction-contract.mjs";
+
+export async function finalizeExtractionReport({ outputDir }) {
+  const docs = docsDir(outputDir);
+  const latest = await readJson(path.join(docs, "extraction", "latest.json"));
+  const extractionDir = path.join(docs, "extraction", latest.captureId);
+  const manifest = await readJson(path.join(extractionDir, "extraction-manifest.json"));
+  const gapArtifact = await readJson(path.join(extractionDir, "extraction-gaps.json"));
+  const decisionArtifact = await optionalJson(path.join(docs, "gap-decisions.json"), { manifestHash: latest.manifestHash, decisions: [] });
+  if (decisionArtifact.manifestHash !== latest.manifestHash) throw new Error("Gap decisions refer to a stale frozen manifest");
+  const decisions = new Map((decisionArtifact.decisions || []).map((decision) => [decision.gapId, decision]));
+  const ledger = await optionalJson(path.join(docs, "build", "section-implementation.json"), { units: [] });
+  const qa = await optionalJson(path.join(docs, "qa", "visual-qa.json"), null);
+  const gapReview = await optionalJson(path.join(docs, "gap-analysis", "latest.json"), null);
+  const gaps = (gapArtifact.gaps || []).filter((gap) => gap.status !== "resolved").map((gap) => {
+    const implementation = ledger.units?.find((unit) => unit.id === gap.ownerUnitId);
+    return {
+      id: gap.id,
+      unitId: gap.ownerUnitId,
+      scope: gap.scope,
+      status: gap.status,
+      reason: gap.reason,
+      missingFields: gap.missingFields,
+      confidence: gap.confidence,
+      evidenceRefs: gap.evidenceRefs,
+      recoveryAttempts: gap.attempts,
+      remainingAttempts: gap.remainingAttempts,
+      assumptions: gap.assumptions,
+      omissions: gap.omissions,
+      affectedAcceptance: gap.affectedAcceptance,
+      dependencyClosure: gap.dependencyClosure,
+      implementation: implementation ? { status: implementation.status, cloneRoot: implementation.cloneRoot } : null,
+      userDecision: decisions.get(gap.id) || gap.userDecision,
+      choices: ["accept-as-is", "retry-or-fix", "provide-material", "replace", "omit", "leave-unresolved"],
+      unblockAction: gap.unblockAction,
+    };
+  });
+  const unresolvedGlobal = gaps.filter((gap) => gap.scope === "global");
+  const provisional = gaps.filter((gap) => gap.scope === "local" && !["accept-as-is", "replace", "omit"].includes(gap.userDecision?.decision));
+  const browserVerified = Boolean(gapReview?.acceptance?.passed && ["reviewed", "not-applicable"].includes(gapReview?.visualReview?.status));
+  const implementationExists = Boolean(ledger.units?.length);
+  const status = unresolvedGlobal.length ? "blocked" : provisional.length ? "done_with_gaps" : browserVerified ? "done" : qa || implementationExists ? "verification_pending" : "implementation_pending";
+  const report = {
+    schemaVersion: EXTRACTION_SCHEMA_VERSION,
+    kind: "final-report",
+    captureId: latest.captureId,
+    manifestHash: manifest.manifestHash,
+    status,
+    summary: {
+      totalGaps: gaps.length,
+      provisionalGaps: provisional.length,
+      globalBlockers: unresolvedGlobal.length,
+      acceptedUnits: manifest.specs.filter((spec) => spec.status === "accepted").length,
+      provisionalUnits: manifest.specs.filter((spec) => spec.status === "provisional").length,
+    },
+    gaps,
+    qa: qa || gapReview ? {
+      preflightScore: qa?.score ?? null,
+      warnings: qa?.warnings || [],
+      provisionalUnits: qa?.provisionalUnits || [],
+      browserReview: gapReview ? { iteration: gapReview.iteration, passed: Boolean(gapReview.acceptance?.passed), status: gapReview.visualReview?.status, blockingCount: gapReview.summary?.blockingCount } : null,
+    } : null,
+  };
+  assertValidArtifact(report, "final-report");
+  await writeJson(path.join(docs, "final-report.json"), report);
+  await writeText(path.join(docs, "final-report.md"), renderFinalReport(report));
+  return report;
+}
+
+export function renderFinalReport(report) {
+  const lines = [
+    "# Home-page reconstruction report",
+    "",
+    `- Status: \`${report.status}\``,
+    `- Frozen manifest: \`${report.manifestHash}\``,
+    `- Accepted units: ${report.summary.acceptedUnits}`,
+    `- Provisional units: ${report.summary.provisionalUnits}`,
+    `- Unresolved local gaps: ${report.summary.provisionalGaps}`,
+    `- Global blockers: ${report.summary.globalBlockers}`,
+    "",
+  ];
+  if (!report.gaps.length) {
+    lines.push("No extraction gaps remain. Browser-backed verification is still required before final clone acceptance.", "");
+  } else {
+    lines.push("## Gaps requiring review", "");
+    for (const gap of report.gaps) {
+      lines.push(
+        `### ${gap.unitId}`,
+        "",
+        `This unit could not be imported reliably because ${lowerFirst(gap.reason)}`,
+        "",
+        `- Gap: \`${gap.id}\` (${gap.scope}, ${gap.status}, confidence: ${gap.confidence})`,
+        `- Missing: ${gap.missingFields.join(", ") || "unspecified evidence"}`,
+        `- Attempts: ${gap.recoveryAttempts.length}; remaining budget: ${gap.remainingAttempts}`,
+        `- Provisional implementation: ${gap.implementation?.status || "not implemented"}${gap.implementation?.cloneRoot ? ` at \`${gap.implementation.cloneRoot}\`` : ""}`,
+        `- Assumptions: ${gap.assumptions.join("; ") || "none"}`,
+        `- Omissions: ${gap.omissions.join("; ") || "none"}`,
+        `- Affected checks: ${gap.affectedAcceptance.join(", ") || "none recorded"}`,
+        `- User decision: ${gap.userDecision ? `\`${gap.userDecision.decision}\`${gap.userDecision.note ? ` — ${gap.userDecision.note}` : ""}` : "pending"}`,
+        `- Available decisions: ${gap.choices.map((choice) => `\`${choice}\``).join(", ")}`,
+        "",
+      );
+    }
+  }
+  return `${lines.join("\n").trim()}\n`;
+}
+
+function lowerFirst(value) {
+  const text = String(value || "evidence was incomplete");
+  return `${text.charAt(0).toLowerCase()}${text.slice(1)}`;
+}
+
+async function optionalJson(filePath, fallback) {
+  try { return await readJson(filePath); } catch { return fallback; }
+}
+
+async function main() {
+  const args = parseArgs();
+  if (!args.out) throw new Error("--out is required");
+  console.log(JSON.stringify(await finalizeExtractionReport({ outputDir: path.resolve(String(args.out)) }), null, 2));
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) main().catch((error) => { console.error(error.stack || error.message); process.exit(1); });

package/skills/wix-headless-replatform/scripts/finalize-gap-review.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { docsDir, normalizeUrl, parseArgs, readJson, resolveOutputDir, writeJson, writeText } from "./lib/common.mjs";
+import { renderGapAnalysisMarkdown, renderGapFixPlan } from "./lib/gap-analysis.mjs";
+import { finalizeExtractionReport } from "./finalize-extraction-report.mjs";
+
+async function main() {
+  const args = parseArgs();
+  const sourceUrl = normalizeUrl(args._[0] || args.url).toString();
+  const outputDir = resolveOutputDir(sourceUrl, args.out);
+  if (args.reviewed === true || args.reviewed === "true") throw new Error("--reviewed is no longer supported; write the required visual-review.json evidence beside the canonical iteration report");
+  const report = await finalizeGapReview({ outputDir });
+  if (args.json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  else console.log(`[gap-analysis] visual review ${report.visualReview.status}; final acceptance ${report.acceptance.passed ? "passed" : "not yet passed"}`);
+}
+
+function requireNonEmptyString(value, label) {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${label} must be a non-empty string`);
+  return value.trim();
+}
+
+function validateVisualReview({ review, report, reviewPath }) {
+  if (!review || typeof review !== "object" || Array.isArray(review)) throw new Error(`Visual review must be a JSON object: ${reviewPath}`);
+  if (!Array.isArray(review.pairs)) throw new Error(`Visual review must include a pairs array: ${reviewPath}`);
+  const expectedPairs = new Map((report.screenshotPairs || []).map((pair) => [pair.id, pair]));
+  const findingIds = new Set((report.findings || []).map((finding) => finding.id));
+  const seen = new Set();
+  const normalized = review.pairs.map((entry, index) => {
+    const prefix = `visual review pair ${index + 1}`;
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw new Error(`${prefix} must be an object`);
+    const pairId = requireNonEmptyString(entry.pairId, `${prefix}.pairId`);
+    const pair = expectedPairs.get(pairId);
+    if (!pair) throw new Error(`${prefix} references unknown screenshot pair: ${pairId}`);
+    if (seen.has(pairId)) throw new Error(`Visual review has duplicate screenshot pair: ${pairId}`);
+    seen.add(pairId);
+    const viewport = requireNonEmptyString(entry.viewport, `${prefix}.viewport`);
+    if (viewport !== pair.viewport) throw new Error(`${prefix}.viewport must match ${pairId} (${pair.viewport})`);
+    const observation = requireNonEmptyString(entry.observation, `${prefix}.observation`);
+    const verdict = requireNonEmptyString(entry.verdict, `${prefix}.verdict`);
+    const entryFindingIds = Array.isArray(entry.findingIds) ? entry.findingIds.map((id) => requireNonEmptyString(id, `${prefix}.findingIds`)) : [];
+    if (new Set(entryFindingIds).size !== entryFindingIds.length) throw new Error(`${prefix}.findingIds contains duplicates`);
+    for (const id of entryFindingIds) if (!findingIds.has(id)) throw new Error(`${prefix} links unknown finding: ${id}`);
+    const rationale = typeof entry.rationale === "string" ? entry.rationale.trim() : "";
+    if (verdict === "no-identity-gap") {
+      if (entryFindingIds.length) throw new Error(`${prefix} cannot link findings for no-identity-gap`);
+      if (!rationale) throw new Error(`${prefix}.rationale is required for no-identity-gap`);
+    } else if (verdict === "findings-recorded") {
+      if (!entryFindingIds.length) throw new Error(`${prefix}.findingIds is required for findings-recorded`);
+    } else {
+      throw new Error(`${prefix}.verdict must be findings-recorded or no-identity-gap`);
+    }
+    return { pairId, viewport, observation, verdict, findingIds: entryFindingIds, rationale: rationale || null };
+  });
+  const missing = [...expectedPairs.keys()].filter((pairId) => !seen.has(pairId));
+  if (missing.length) throw new Error(`Visual review is incomplete: ${missing.join(", ")}`);
+  return normalized;
+}
+
+async function validateVisualProgress({ progress, report, progressPath }) {
+  if (!progress || typeof progress !== "object" || Array.isArray(progress)) throw new Error(`Visual progress proof must be a JSON object: ${progressPath}`);
+  if (!Array.isArray(progress.entries)) throw new Error(`Visual progress proof must include an entries array: ${progressPath}`);
+  const expectedFindingIds = new Set(report.visualProgress?.previousBlockingFindingIds || []);
+  const currentPairs = new Map((report.screenshotPairs || []).map((pair) => [pair.id, pair]));
+  const previousReportPath = report.visualProgress?.previousReportPath;
+  if (!previousReportPath) throw new Error("Visual progress proof is missing the prior canonical report path");
+  const previousReport = await readJson(previousReportPath);
+  const previousPairs = new Map((previousReport.screenshotPairs || []).map((pair) => [pair.id, pair]));
+  const seen = new Set();
+  const records = progress.entries.map((entry, index) => {
+    const prefix = `visual progress entry ${index + 1}`;
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw new Error(`${prefix} must be an object`);
+    const priorFindingId = requireNonEmptyString(entry.priorFindingId, `${prefix}.priorFindingId`);
+    if (!expectedFindingIds.has(priorFindingId)) throw new Error(`${prefix} references unknown prior blocking finding: ${priorFindingId}`);
+    if (seen.has(priorFindingId)) throw new Error(`Visual progress proof has duplicate prior finding: ${priorFindingId}`);
+    seen.add(priorFindingId);
+    const target = requireNonEmptyString(entry.target, `${prefix}.target`);
+    const pairId = requireNonEmptyString(entry.pairId, `${prefix}.pairId`);
+    const currentPair = currentPairs.get(pairId);
+    const previousPair = previousPairs.get(pairId);
+    if (!currentPair || !previousPair) throw new Error(`${prefix}.pairId must exist in both the prior and current screenshot queues`);
+    const sourceScreenshotPath = requireNonEmptyString(entry.sourceScreenshotPath, `${prefix}.sourceScreenshotPath`);
+    const beforeResultScreenshotPath = requireNonEmptyString(entry.beforeResultScreenshotPath, `${prefix}.beforeResultScreenshotPath`);
+    const afterResultScreenshotPath = requireNonEmptyString(entry.afterResultScreenshotPath, `${prefix}.afterResultScreenshotPath`);
+    if (sourceScreenshotPath !== currentPair.source.path) throw new Error(`${prefix}.sourceScreenshotPath must match the canonical source screenshot for ${pairId}`);
+    if (beforeResultScreenshotPath !== previousPair.result.path) throw new Error(`${prefix}.beforeResultScreenshotPath must match the prior iteration result screenshot for ${pairId}`);
+    if (afterResultScreenshotPath !== currentPair.result.path) throw new Error(`${prefix}.afterResultScreenshotPath must match the current iteration result screenshot for ${pairId}`);
+    const beforeObservation = requireNonEmptyString(entry.beforeObservation, `${prefix}.beforeObservation`);
+    const afterObservation = requireNonEmptyString(entry.afterObservation, `${prefix}.afterObservation`);
+    const evidence = requireNonEmptyString(entry.evidence, `${prefix}.evidence`);
+    const verdict = requireNonEmptyString(entry.verdict, `${prefix}.verdict`);
+    if (!["improved", "no-visible-improvement", "regressed"].includes(verdict)) throw new Error(`${prefix}.verdict must be improved, no-visible-improvement, or regressed`);
+    return { priorFindingId, target, pairId, sourceScreenshotPath, beforeResultScreenshotPath, afterResultScreenshotPath, beforeObservation, afterObservation, verdict, evidence };
+  });
+  const missing = [...expectedFindingIds].filter((findingId) => !seen.has(findingId));
+  if (missing.length) throw new Error(`Visual progress proof is incomplete: ${missing.join(", ")}`);
+  return records;
+}
+
+export async function finalizeGapReview({ outputDir } = {}) {
+  const gapRoot = path.join(docsDir(outputDir), "gap-analysis");
+  const latest = await readJson(path.join(gapRoot, "latest.json"));
+  const reportPath = latest.paths?.reportJson;
+  if (!reportPath) throw new Error("Latest gap report does not include its canonical report path");
+  const report = await readJson(reportPath);
+  const reviewPath = path.join(path.dirname(reportPath), "visual-review.json");
+  const reviewRequired = Boolean(report.visualReview?.required || report.screenshotPairs?.length);
+  let reviewPairs = [];
+  let progressRecords = [];
+  if (reviewRequired) {
+    let review;
+    try {
+      review = await readJson(reviewPath);
+    } catch (error) {
+      throw new Error(`Missing required visual review evidence at ${reviewPath}. Open every source/result pair and write visual-review.json before finalizing. (${error.message})`);
+    }
+    reviewPairs = validateVisualReview({ review, report, reviewPath });
+    for (const pair of report.screenshotPairs || []) pair.reviewStatus = "reviewed";
+    report.visualReview.status = "reviewed";
+    report.visualReview.reviewedPairs = reviewPairs.map((entry) => entry.pairId);
+    report.visualReview.records = reviewPairs;
+    report.visualReview.artifactPath = reviewPath;
+    report.visualReview.reviewedAt = new Date().toISOString();
+  } else {
+    report.visualReview.status = "not-applicable";
+    report.visualReview.reviewedPairs = [];
+    report.visualReview.records = [];
+  }
+  if (report.visualProgress?.required) {
+    const progressPath = report.paths?.visualProgress || path.join(path.dirname(reportPath), "visual-progress.json");
+    let progress;
+    try {
+      progress = await readJson(progressPath);
+    } catch (error) {
+      throw new Error(`Missing required visual progress proof at ${progressPath}. Compare the prior and current result screenshots before finalizing. (${error.message})`);
+    }
+    progressRecords = await validateVisualProgress({ progress, report, progressPath });
+    report.visualProgress.status = "reviewed";
+    report.visualProgress.records = progressRecords;
+    report.visualProgress.artifactPath = progressPath;
+    report.visualProgress.reviewedAt = new Date().toISOString();
+  }
+  const open = (report.findings || []).filter((finding) => finding.status !== "resolved" && finding.status !== "accepted");
+  const counts = { critical: 0, high: 0, medium: 0, low: 0 };
+  for (const finding of open) counts[finding.severity] = (counts[finding.severity] || 0) + 1;
+  report.summary.counts = counts;
+  report.summary.blockingCount = counts.critical + counts.high;
+  report.summary.findingCount = open.length;
+  report.summary.score = Math.max(0, Math.round(100 - counts.critical * 25 - counts.high * 10 - counts.medium * 3 - counts.low));
+  report.summary.finalAcceptance = report.summary.blockingCount === 0 && (!report.visualReview.required || report.visualReview.status === "reviewed");
+  if (report.summary.finalAcceptance && report.visualProgress?.required && progressRecords.some((record) => record.verdict !== "improved")) {
+    throw new Error("Cannot accept the iteration: a prior blocking finding was not proven improved by its before/after screenshot evidence");
+  }
+  report.acceptance.passed = report.summary.finalAcceptance;
+  report.acceptance.finalizedAt = new Date().toISOString();
+  await writeJson(reportPath, report);
+  await writeText(report.paths.reportMarkdown, renderGapAnalysisMarkdown(report));
+  await writeText(report.paths.fixPlan, renderGapFixPlan(report));
+  await writeJson(path.join(gapRoot, "latest.json"), report);
+  await writeText(path.join(gapRoot, "latest.md"), renderGapAnalysisMarkdown(report));
+  const manifestPath = path.join(path.dirname(reportPath), "iteration-manifest.json");
+  const manifest = await readJson(manifestPath);
+  manifest.status = "visual-review-complete";
+  manifest.visualReview = { artifactPath: reviewRequired ? reviewPath : null, reviewedPairs: reviewPairs.map((entry) => entry.pairId), reviewedAt: report.visualReview.reviewedAt || null };
+  manifest.visualProgress = { artifactPath: report.visualProgress?.artifactPath || null, reviewedAt: report.visualProgress?.reviewedAt || null, verdicts: progressRecords.map((entry) => ({ priorFindingId: entry.priorFindingId, verdict: entry.verdict })) };
+  await writeJson(manifestPath, manifest);
+  try {
+    await readJson(path.join(docsDir(outputDir), "extraction", "latest.json"));
+    await finalizeExtractionReport({ outputDir });
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  return report;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error.stack || error.message);
+    process.exit(1);
+  });
+}

package/skills/wix-headless-replatform/scripts/finalize-gap-review.test.mjs

@@ -0,0 +1,98 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { finalizeGapReview } from "./finalize-gap-review.mjs";
+
+async function writeJson(filePath, value) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+async function fixture() {
+  const outputDir = await mkdtemp(path.join(os.tmpdir(), "gap-review-"));
+  const iterationDir = path.join(outputDir, "docs", "site-clone", "gap-analysis", "iterations", "001");
+  const reportPath = path.join(iterationDir, "gap-analysis.json");
+  const report = {
+    iteration: 1,
+    summary: { score: 90, findingCount: 1, counts: { critical: 0, high: 0, medium: 1, low: 0 }, blockingCount: 0, finalAcceptance: false },
+    findings: [{ id: "gap-001", severity: "medium", status: "open", category: "layout", message: "Example", scope: {}, repairHint: "Fix" }],
+    screenshotPairs: [{ id: "home-desktop", page: "/", viewport: "desktop", source: { path: "source.png" }, result: { path: "result.png" } }],
+    visualReview: { status: "pending", required: true, reviewedPairs: [], notes: [] },
+    fixOrder: [],
+    acceptance: { passed: false },
+    paths: { reportJson: reportPath, reportMarkdown: path.join(iterationDir, "gap-analysis.md"), fixPlan: path.join(iterationDir, "gap-fix-plan.md") },
+  };
+  await writeJson(reportPath, report);
+  await writeJson(path.join(outputDir, "docs", "site-clone", "gap-analysis", "latest.json"), report);
+  await writeJson(path.join(iterationDir, "iteration-manifest.json"), { iteration: 1, status: "comparison-complete-visual-review-pending" });
+  return { outputDir, iterationDir };
+}
+
+test("finalizeGapReview rejects a missing visual review artifact", async () => {
+  const { outputDir } = await fixture();
+  try {
+    await assert.rejects(() => finalizeGapReview({ outputDir }), /Missing required visual review evidence/);
+  } finally {
+    await rm(outputDir, { recursive: true, force: true });
+  }
+});
+
+test("finalizeGapReview records evidence and synchronizes the iteration manifest", async () => {
+  const { outputDir, iterationDir } = await fixture();
+  try {
+    await writeJson(path.join(iterationDir, "visual-review.json"), {
+      pairs: [{ pairId: "home-desktop", viewport: "desktop", observation: "The hero composition differs from the source.", verdict: "findings-recorded", findingIds: ["gap-001"] }],
+    });
+    const report = await finalizeGapReview({ outputDir });
+    assert.equal(report.visualReview.status, "reviewed");
+    assert.equal(report.visualReview.records[0].findingIds[0], "gap-001");
+    const manifest = JSON.parse(await (await import("node:fs/promises")).readFile(path.join(iterationDir, "iteration-manifest.json"), "utf8"));
+    assert.equal(manifest.status, "visual-review-complete");
+  } finally {
+    await rm(outputDir, { recursive: true, force: true });
+  }
+});
+
+test("finalizeGapReview requires traceable before/after proof after a prior blocking finding", async () => {
+  const { outputDir, iterationDir } = await fixture();
+  try {
+    const reportPath = path.join(iterationDir, "gap-analysis.json");
+    const report = JSON.parse(await (await import("node:fs/promises")).readFile(reportPath, "utf8"));
+    const previousDir = path.join(outputDir, "docs", "site-clone", "gap-analysis", "iterations", "000");
+    const previousReportPath = path.join(previousDir, "gap-analysis.json");
+    await writeJson(previousReportPath, {
+      iteration: 0,
+      findings: [{ id: "gap-previous", severity: "high", status: "open" }],
+      screenshotPairs: [{ id: "home-desktop", page: "/", viewport: "desktop", source: { path: "source.png" }, result: { path: "before.png" } }],
+      paths: { reportJson: previousReportPath },
+    });
+    report.visualProgress = { required: true, status: "pending", previousIteration: 0, previousReportPath, previousBlockingFindingIds: ["gap-previous"] };
+    report.paths.visualProgress = path.join(iterationDir, "visual-progress.json");
+    await writeJson(reportPath, report);
+    await writeJson(path.join(outputDir, "docs", "site-clone", "gap-analysis", "latest.json"), report);
+    await writeJson(path.join(iterationDir, "visual-review.json"), {
+      pairs: [{ pairId: "home-desktop", viewport: "desktop", observation: "The hero now matches.", verdict: "no-identity-gap", rationale: "No identity gap remains." }],
+    });
+    await assert.rejects(() => finalizeGapReview({ outputDir }), /Missing required visual progress proof/);
+    await writeJson(report.paths.visualProgress, {
+      entries: [{
+        priorFindingId: "gap-previous",
+        target: "Hero section",
+        pairId: "home-desktop",
+        sourceScreenshotPath: "source.png",
+        beforeResultScreenshotPath: "before.png",
+        afterResultScreenshotPath: "result.png",
+        beforeObservation: "The hero heading was misplaced.",
+        afterObservation: "The hero heading now aligns with the source.",
+        verdict: "improved",
+        evidence: "The same desktop screenshot pair shows the corrected heading alignment.",
+      }],
+    });
+    const finalized = await finalizeGapReview({ outputDir });
+    assert.equal(finalized.visualProgress.records[0].verdict, "improved");
+  } finally {
+    await rm(outputDir, { recursive: true, force: true });
+  }
+});

package/skills/wix-headless-replatform/scripts/finalize-migration-website.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { mkdir, rename, writeFile } from "node:fs/promises";
+import { parseArgs, readJson } from "./lib/common.mjs";
+
+async function writeJsonAtomic(filePath, value) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+  await rename(tempPath, filePath);
+}
+
+export async function createMigrationWebsiteCompletion({ handoffPath = null, projectDir = null, outputDir, releaseUrl, releaseNotApplicable = false, doneWithGaps = false, iteration = null }) {
+  if (!handoffPath && !projectDir) throw new Error("--handoff or --project-dir is required");
+  if (!outputDir) throw new Error("A migration frontend output directory is required");
+  const handoff = handoffPath ? await readJson(handoffPath) : null;
+  if (handoffPath && !handoff?.handoffFingerprint) throw new Error("website/handoff.json is missing handoffFingerprint; refresh the handoff first");
+  const gapPath = iteration
+    ? path.join(outputDir, "docs", "site-clone", "gap-analysis", "iterations", String(iteration).padStart(3, "0"), "gap-analysis.json")
+    : path.join(outputDir, "docs", "site-clone", "gap-analysis", "latest.json");
+  const gap = await readJson(gapPath);
+  const finalReportPath = path.join(outputDir, "docs", "site-clone", "final-report.json");
+  const finalReport = await readOptionalJson(finalReportPath);
+  if (finalReport?.status === "blocked") throw new Error("The frozen extraction final report contains a global blocker");
+  const effectiveDoneWithGaps = doneWithGaps || finalReport?.status === "done_with_gaps";
+  if (gap?.visualReview?.status !== "reviewed") {
+    throw new Error("Post-build gap review has not passed; run/finalize the gap loop before finalizing the website");
+  }
+  const findings = Array.isArray(gap.findings) ? gap.findings : [];
+  const unresolved = findings.filter((finding) => finding.status !== "resolved" && finding.status !== "accepted");
+  const unresolvedCritical = unresolved.filter((finding) => finding.severity === "critical").length;
+  const unresolvedHigh = unresolved.filter((finding) => finding.severity === "high").length;
+  if (!effectiveDoneWithGaps && (!gap?.acceptance?.passed || unresolvedCritical || unresolvedHigh)) throw new Error("Post-build gap review still has unresolved critical/high findings");
+  if (doneWithGaps && !iteration && !finalReport) throw new Error("--done-with-gaps requires --iteration or a frozen final report so the terminal evidence is explicit");
+  const automationState = await readJson(path.join(outputDir, "docs", "site-clone", "frontend-automation-state.json"));
+  const facelift = automationState?.checkpoints?.facelift;
+  if (!effectiveDoneWithGaps && facelift?.requested && facelift.status !== "accepted") {
+    throw new Error("Optional facelift was requested but has not been accepted; complete the separate facelift review first");
+  }
+  if (!releaseUrl && !releaseNotApplicable) throw new Error("--release-url is required unless --release-not-applicable is explicitly set");
+
+  const receipt = {
+    schemaVersion: 1,
+    status: effectiveDoneWithGaps ? "done_with_gaps" : unresolved.length ? "complete_with_warnings" : "complete",
+    handoffFingerprint: handoff?.handoffFingerprint || null,
+    extractionManifestHash: finalReport?.manifestHash || null,
+    frontendProjectDir: path.relative(projectDir || path.dirname(path.dirname(handoffPath)), outputDir) || ".",
+    phase: effectiveDoneWithGaps ? finalReport?.status === "done_with_gaps" ? "provisional_handoff" : "gap_cycle_cap" : "release",
+    gapAnalysis: {
+      latestIteration: gap.iteration,
+      cycleCap: doneWithGaps ? 5 : null,
+      screenshotReview: "complete",
+      unresolvedCritical,
+      unresolvedHigh,
+      residualFindings: unresolved.map((finding) => ({ id: finding.id, severity: finding.severity, message: finding.message })),
+    },
+    facelift: effectiveDoneWithGaps ? { status: "not_run", reason: finalReport?.status === "done_with_gaps" ? "provisional_units_remain" : "maximum_gap_cycles_reached" } : facelift?.requested ? { status: "accepted" } : { status: "not_requested" },
+    release: releaseNotApplicable ? { status: "not_applicable", url: null } : { status: "released", url: releaseUrl },
+    artifactRefs: [path.relative(projectDir || path.dirname(path.dirname(handoffPath)), gapPath), ...(finalReport ? [path.relative(projectDir || path.dirname(path.dirname(handoffPath)), finalReportPath)] : []), ...(gap.paths?.visualProgress ? [gap.paths.visualProgress] : []), ...(gap.visualReview?.artifactPath ? [gap.visualReview.artifactPath] : [])],
+    updatedAt: new Date().toISOString(),
+  };
+  const receiptPath = handoffPath
+    ? path.join(path.dirname(handoffPath), "completion.json")
+    : path.join(projectDir, "website", "completion.json");
+  await writeJsonAtomic(receiptPath, receipt);
+  return { receiptPath, receipt };
+}
+
+async function readOptionalJson(filePath) {
+  try { return await readJson(filePath); } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function main() {
+  const args = parseArgs();
+  const handoffPath = args.handoff ? path.resolve(String(args.handoff)) : null;
+  const projectDir = args["project-dir"] ? path.resolve(String(args["project-dir"])) : null;
+  const handoff = handoffPath ? await readJson(handoffPath) : null;
+  const outputDir = args.out
+    ? path.resolve(String(args.out))
+    : handoff?.destination?.frontendProjectDir
+      ? path.resolve(String(handoff.destination.frontendProjectDir))
+      : null;
+  const result = await createMigrationWebsiteCompletion({
+    handoffPath,
+    projectDir,
+    outputDir,
+    releaseUrl: args["release-url"] ? String(args["release-url"]) : null,
+    releaseNotApplicable: args["release-not-applicable"] === true || args["release-not-applicable"] === "true",
+    doneWithGaps: args["done-with-gaps"] === true || args["done-with-gaps"] === "true",
+    iteration: args.iteration ? Number(args.iteration) : null,
+  });
+  console.log(JSON.stringify({ ok: true, ...result }, null, 2));
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error.stack || error.message);
+    process.exit(1);
+  });
+}