@wix/agent-skills 1.33.1 → 1.34.0

package/skills/wix-replatform/resources/rp-telemetry/lib/transcript-digest.js

@@ -0,0 +1,318 @@
+'use strict';
+
+// Deterministic digest of a Claude Code session transcript.
+//
+// Pure function over JSONL already on disk: no model call, no network, no
+// judgment. Given the same transcript files it must return byte-identical
+// output, so every derived number here comes straight from fields Claude Code
+// itself writes to the transcript — never from a guess or a heuristic that
+// could drift between runs.
+//
+// Two loci write the identical JSONL shape: a local run
+// under `~/.claude/projects/<escaped-cwd>/<sessionId>.jsonl`, and a sandbox
+// run under `.persist/claude/projects/` inside the checkpoint (the sandbox
+// symlinks `~/.claude` into the checkpointed tree). This module only ever
+// reads a list of file paths, so it does not care which locus produced them.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// A repeated identical tool call is the signature of the unbounded-retry hang
+// class — this is the threshold at which a streak counts as a
+// loop rather than ordinary retry-with-backoff.
+const RETRY_LOOP_MIN_REPEATS = 3;
+// A gap this long between two timestamped transcript records is time the
+// human or an external system held the run, not active agent work — mirrors
+// the recorder's own IMPLICIT_WAIT_MIN_MS (telemetry-recorder.js) so the two
+// idle notions agree on the same threshold.
+const IDLE_GAP_MIN_MS = 60 * 1000;
+const TOP_FAILING_MAX = 10;
+const RETRY_LOOPS_MAX = 10;
+
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  if (value && typeof value === 'object') {
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+// Claude Code's own project-directory escaping: every character outside
+// [A-Za-z0-9] becomes `-` (verified against this repo's own
+// ~/.claude/projects/<escaped-cwd> directory names).
+function escapeCwd(cwd) {
+  return String(cwd).replace(/[^A-Za-z0-9]/g, '-');
+}
+
+function readSessionRecords(file) {
+  const raw = fs.readFileSync(file, 'utf8');
+  const records = [];
+  let malformed = 0;
+  for (const line of raw.split('\n')) {
+    if (line.trim() === '') continue;
+    try {
+      records.push(JSON.parse(line));
+    } catch {
+      malformed += 1;
+    }
+  }
+  return { records, malformed };
+}
+
+// First/last top-level `timestamp` and the `cwd` of a session file, without
+// holding the whole parse result — used to decide which sibling sessions
+// belong to this run before paying for the full digest pass.
+function peekSession(file) {
+  const { records } = readSessionRecords(file);
+  let firstTs = null;
+  let lastTs = null;
+  let cwd = null;
+  for (const record of records) {
+    if (typeof record.timestamp !== 'string') continue;
+    const ms = Date.parse(record.timestamp);
+    if (!Number.isFinite(ms)) continue;
+    if (firstTs === null) firstTs = ms;
+    lastTs = ms;
+    if (cwd === null && typeof record.cwd === 'string') cwd = record.cwd;
+  }
+  return { firstTs, lastTs, cwd };
+}
+
+// Every sibling `.jsonl` in the same project directory as `anchorTranscript`
+// whose recorded `cwd` matches and whose time range overlaps
+// [windowStartMs, windowEndMs]. A resumed run spans several sessionIds —
+// this is the correlation the manifest then writes
+// down once so a later reader never has to re-derive it.
+function discoverRunSessions(anchorTranscript, { windowStartMs, windowEndMs }) {
+  const dir = path.dirname(anchorTranscript);
+  const anchor = peekSession(anchorTranscript);
+  const cwd = anchor.cwd;
+  const entries = fs.readdirSync(dir).filter((name) => name.endsWith('.jsonl'));
+  const included = [];
+  for (const name of entries) {
+    const file = path.join(dir, name);
+    const info = peekSession(file);
+    if (info.firstTs === null) continue;
+    if (cwd !== null && info.cwd !== null && info.cwd !== cwd) continue;
+    if (info.lastTs < windowStartMs || info.firstTs > windowEndMs) continue;
+    included.push({
+      sessionId: path.basename(name, '.jsonl'),
+      path: file,
+      firstTs: info.firstTs,
+      lastTs: info.lastTs,
+    });
+  }
+  included.sort((a, b) => a.firstTs - b.firstTs);
+  if (included.length === 0) {
+    // The anchor transcript itself always counts, even if its own window
+    // check above (identical file) somehow fails a boundary comparison.
+    included.push({ sessionId: path.basename(anchorTranscript, '.jsonl'), path: anchorTranscript, ...anchor });
+  }
+  return included;
+}
+
+function toolUseBlocks(message) {
+  const content = message && message.content;
+  if (!Array.isArray(content)) return [];
+  return content.filter((c) => c && c.type === 'tool_use');
+}
+
+function toolResultBlocks(message) {
+  const content = message && message.content;
+  if (!Array.isArray(content)) return [];
+  return content.filter((c) => c && c.type === 'tool_result');
+}
+
+// A genuine human turn, as distinct from a tool result: both travel as
+// `type: "user"` records in Claude Code's transcript (matching the
+// Anthropic Messages API, where a tool_result is also role:"user"). A tool
+// result carries `toolUseResult` and/or tool_result content blocks; a
+// sidechain user record is the orchestrator's prompt *to* a subagent, not a
+// person. Excluding both is what makes this the friction half of
+// adoption-vs-friction rather than an inflated turn count.
+function isHumanTurn(record) {
+  if (record.type !== 'user' || record.isSidechain || record.isMeta) return false;
+  if (record.toolUseResult !== undefined) return false;
+  if (toolResultBlocks(record.message).length > 0) return false;
+  return true;
+}
+
+function topN(counts, n) {
+  return [...counts.entries()]
+    .map(([tool, count]) => ({ tool, n: count }))
+    .sort((a, b) => b.n - a.n || a.tool.localeCompare(b.tool))
+    .slice(0, n);
+}
+
+// The deterministic digest itself: counts, durations, tool
+// names — never client data, never free text. `stageForTs(ms)` is an
+// optional pure lookup (typically built from the telemetry journal's
+// stage_start/stage_end intervals) used only to label which stage a retry
+// loop or edit fell in; omitting it leaves `stage: null` rather than guessing.
+function computeDigest(sessionFiles, { tailComplete = true, stageForTs = () => null } = {}) {
+  if (!Array.isArray(sessionFiles) || sessionFiles.length === 0) {
+    throw new Error('computeDigest requires at least one session file');
+  }
+
+  let ccVersion = null;
+  let transcriptTurns = 0;
+  let humanTurns = 0;
+  let agentTurns = 0;
+  let sidechainTurns = 0;
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let cacheReadTokens = 0;
+  let cacheCreationTokens = 0;
+  let toolCalls = 0;
+  let toolFailures = 0;
+  const toolFailureCounts = new Map();
+  const toolNameById = new Map();
+  const editedFiles = new Set();
+  let hookBlocks = 0;
+  let hookErrors = 0;
+  const retryLoops = [];
+  const timestampsMs = [];
+
+  let streakKey = null;
+  let streakTool = null;
+  let streakLen = 0;
+  let streakStartTs = null;
+  const flushStreak = () => {
+    if (streakLen >= RETRY_LOOP_MIN_REPEATS) {
+      retryLoops.push({ tool: streakTool, repeats: streakLen, stage: stageForTs(streakStartTs) });
+    }
+    streakKey = null;
+    streakTool = null;
+    streakLen = 0;
+    streakStartTs = null;
+  };
+
+  for (const session of [...sessionFiles].sort((a, b) => (a.firstTs || 0) - (b.firstTs || 0))) {
+    const { records } = readSessionRecords(session.path);
+    for (const record of records) {
+      if (typeof record.version === 'string') ccVersion = record.version;
+      const tsMs = typeof record.timestamp === 'string' ? Date.parse(record.timestamp) : NaN;
+      if (Number.isFinite(tsMs)) timestampsMs.push(tsMs);
+
+      if (record.type === 'assistant') {
+        transcriptTurns += 1;
+        if (record.isSidechain) sidechainTurns += 1;
+        else agentTurns += 1;
+        const usage = record.message && record.message.usage;
+        if (usage) {
+          inputTokens += usage.input_tokens || 0;
+          outputTokens += usage.output_tokens || 0;
+          cacheReadTokens += usage.cache_read_input_tokens || 0;
+          cacheCreationTokens += usage.cache_creation_input_tokens || 0;
+        }
+        for (const block of toolUseBlocks(record.message)) {
+          toolNameById.set(block.id, block.name);
+          toolCalls += 1;
+          const key = `${block.name}:${stableStringify(block.input)}`;
+          if (key === streakKey) {
+            streakLen += 1;
+          } else {
+            flushStreak();
+            streakKey = key;
+            streakTool = block.name;
+            streakLen = 1;
+            streakStartTs = Number.isFinite(tsMs) ? tsMs : streakStartTs;
+          }
+        }
+        continue;
+      }
+
+      if (record.type === 'user') {
+        if (isHumanTurn(record)) {
+          transcriptTurns += 1;
+          humanTurns += 1;
+        }
+        for (const result of toolResultBlocks(record.message)) {
+          const name = toolNameById.get(result.tool_use_id) || 'unknown';
+          if (result.is_error) {
+            toolFailures += 1;
+            toolFailureCounts.set(name, (toolFailureCounts.get(name) || 0) + 1);
+            // A tool call whose result is an error breaks any retry streak it
+            // was part of only if the NEXT call changes shape; a genuine retry
+            // loop is agent-driven (repeated tool_use), so failures are
+            // counted but do not themselves reset the streak tracker above.
+          }
+        }
+        continue;
+      }
+
+      if (record.type === 'system') {
+        if (Array.isArray(record.hookErrors)) hookErrors += record.hookErrors.length;
+        if (record.preventedContinuation === true) hookBlocks += 1;
+        continue;
+      }
+
+      if (record.type === 'file-history-snapshot' && record.isSnapshotUpdate === true) {
+        const backups = record.snapshot && record.snapshot.trackedFileBackups;
+        if (backups && typeof backups === 'object') {
+          for (const filePath of Object.keys(backups)) editedFiles.add(filePath);
+        }
+      }
+    }
+  }
+  flushStreak();
+
+  timestampsMs.sort((a, b) => a - b);
+  const wallMs = timestampsMs.length > 1 ? timestampsMs[timestampsMs.length - 1] - timestampsMs[0] : 0;
+  let idleMs = 0;
+  let longestGapMs = 0;
+  for (let i = 1; i < timestampsMs.length; i += 1) {
+    const gap = timestampsMs[i] - timestampsMs[i - 1];
+    if (gap > longestGapMs) longestGapMs = gap;
+    if (gap >= IDLE_GAP_MIN_MS) idleMs += gap;
+  }
+  const activeMs = Math.max(0, wallMs - idleMs);
+
+  retryLoops.sort((a, b) => b.repeats - a.repeats);
+
+  return {
+    source: {
+      sessions: sessionFiles.length,
+      transcript_turns: transcriptTurns,
+      cc_version: ccVersion,
+      tail_complete: tailComplete,
+    },
+    cost: {
+      input_tokens: inputTokens,
+      output_tokens: outputTokens,
+      cache_read_input_tokens: cacheReadTokens,
+      cache_creation_input_tokens: cacheCreationTokens,
+    },
+    interaction: {
+      human_turns: humanTurns,
+      agent_turns: agentTurns,
+      sidechain_turns: sidechainTurns,
+    },
+    time: {
+      wall_ms: wallMs,
+      active_ms: activeMs,
+      idle_ms: idleMs,
+      longest_gap_ms: longestGapMs,
+    },
+    tools: {
+      calls: toolCalls,
+      failures: toolFailures,
+      top_failing: topN(toolFailureCounts, TOP_FAILING_MAX),
+    },
+    signals: {
+      retry_loops: retryLoops.slice(0, RETRY_LOOPS_MAX),
+      hook_blocks: hookBlocks,
+      hook_errors: hookErrors,
+      files_edited_mid_run: editedFiles.size,
+    },
+  };
+}
+
+module.exports = {
+  RETRY_LOOP_MIN_REPEATS,
+  IDLE_GAP_MIN_MS,
+  escapeCwd,
+  discoverRunSessions,
+  computeDigest,
+};

package/skills/wix-replatform/resources/rp-telemetry/scripts/meter-from-audit.js

@@ -9,8 +9,8 @@
 //
 // TRAP this deliberately handles: a bulk write logs ONE audit row PER ITEM, each carrying the
 // BATCH's total latency. Summing `latencyMs` across rows therefore multiplies one call's latency by
-// its item count — on a real run that turned 346s of elapsed import into 1,050,992ms of "API time",
-// three times longer than the stage existed. Rows are collapsed per distinct
+// its item count — the "API time" total can come out many times longer than the stage itself
+// lasted. Rows are collapsed per distinct
 // (runId, endpoint, batch, latencyMs) so a batch counts once, while genuinely separate calls
 // (category creates, link calls) each count individually.
 

package/skills/wix-replatform/resources/rp-telemetry/scripts/rp-telemetry.js

@@ -14,17 +14,30 @@
 //   node scripts/rp-telemetry.js meter '{"model_ms":42000,"output_tokens":18000}'
 //   node scripts/rp-telemetry.js wait start [--halt <subtype> --skill <s> [--what '<text>']]
 //   node scripts/rp-telemetry.js wait end
+//   node scripts/rp-telemetry.js digest --transcript <path to CC session jsonl> [--offline]
 //   node scripts/rp-telemetry.js finalize '<rollup-json>'
 //   node scripts/rp-telemetry.js rebuild [--attempt <n>] [--push]
 //   node scripts/rp-telemetry.js status
 //
+// `digest`: call it just before `finalize`. It parses the Claude
+// Code session transcript that produced this run — no model, no network, so a
+// failure here must never abort the migration (`|| true` it). Pass `--offline`
+// when re-running it later against a checkpointed or local transcript to
+// produce the digest for a run that died before ever calling it; omitted, the
+// digest is the in-run call and necessarily misses the final few turns it is
+// itself part of (`source.tail_complete: false`). Also copies this run's
+// sessions into telemetry/transcripts/<sessionId>.jsonl.gz + manifest.json.
+//
 // Output: one JSON object on stdout. {"ok":true,...} on success; on rejection
 // {"ok":false,"errors":[...],"hint":...} with exit code 1 — fix and retry.
 
 const fs = require('node:fs');
+const path = require('node:path');
+const zlib = require('node:zlib');
 const recorder = require('../lib/telemetry-recorder.js');
+const transcriptDigestLib = require('../lib/transcript-digest.js');
 
-const VALUE_FLAGS = new Set(['--project', '--outcome', '--halt', '--skill', '--what', '--attempt', '--stage']);
+const VALUE_FLAGS = new Set(['--project', '--outcome', '--halt', '--skill', '--what', '--attempt', '--stage', '--transcript']);
 // Meter measurements are accepted as kebab-case flags so a shell script can report its own timing
 // without composing JSON: --api-ms 1234 --api-calls 73.
 const METER_FLAGS = new Map(
@@ -32,12 +45,36 @@ const METER_FLAGS = new Map(
     .map((key) => [`--${key.replace(/_/g, '-')}`, key]),
 );
 
+const SOURCE_READ_FLAGS = new Map(
+  ['discovery_queries', 'scoped_queries', 'tier_refusals', 'redacted_values']
+    .map((key) => [`--${key.replace(/_/g, '-')}`, key]),
+);
+// Repeatable, because a run touches several tables: --discovery-table postmeta --discovery-table wc_orders_meta
+const SOURCE_READ_LIST_FLAGS = new Map([['--discovery-table', 'discovery_tables'], ['--scoped-table', 'scoped_tables']]);
+
 function parseArgs(argv) {
   const positional = [];
   const flags = {};
   const meter = {};
+  const sourceRead = {};
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
+    if (SOURCE_READ_FLAGS.has(arg)) {
+      const raw = argv[i + 1];
+      const value = Number(raw);
+      if (!Number.isFinite(value)) fail([`${arg} expects a number (got: ${raw === undefined ? '(none)' : raw})`]);
+      sourceRead[SOURCE_READ_FLAGS.get(arg)] = value;
+      i += 1;
+      continue;
+    }
+    if (SOURCE_READ_LIST_FLAGS.has(arg)) {
+      const key = SOURCE_READ_LIST_FLAGS.get(arg);
+      const raw = argv[i + 1];
+      if (raw === undefined) fail([`${arg} expects a bare table name`]);
+      sourceRead[key] = [...(sourceRead[key] || []), raw];
+      i += 1;
+      continue;
+    }
     if (VALUE_FLAGS.has(arg)) {
       flags[arg.slice(2)] = argv[i + 1];
       i += 1;
@@ -49,13 +86,15 @@ function parseArgs(argv) {
       i += 1;
     } else if (arg === '--push') {
       flags.push = true;
+    } else if (arg === '--offline') {
+      flags.offline = true;
     } else if (arg.startsWith('--')) {
       fail([`unknown flag: ${arg}`]);
     } else {
       positional.push(arg);
     }
   }
-  return { positional, flags, meter };
+  return { positional, flags, meter, sourceRead };
 }
 
 function fail(errors, hint) {
@@ -73,8 +112,58 @@ function parseJsonArg(raw, label) {
   return undefined;
 }
 
+// Locates a `stage` for a timestamp from this run's own journal, so a retry
+// loop or hook block in the digest can be attributed to the stage it fell in
+// without the pure parser having to know anything about telemetry stages.
+function stageIntervalsFor(state, nowMs) {
+  const intervals = state.entries.map((e) => ({ stage: e.stage, start: Date.parse(e.start), end: Date.parse(e.end) }));
+  if (state.openStage) {
+    intervals.push({ stage: state.openStage, start: Date.parse(state.openStageStart), end: nowMs });
+  }
+  return (ms) => {
+    if (!Number.isFinite(ms)) return null;
+    const hit = intervals.find((iv) => ms >= iv.start && ms <= iv.end);
+    return hit ? hit.stage : null;
+  };
+}
+
+async function runDigest(projectDir, transcriptPath, { offline }) {
+  const journal = recorder.readJournal(projectDir);
+  if (!journal) fail(['no active telemetry run in this project'], "call `rp-telemetry.js start` first");
+  const state = recorder.replay(journal.records);
+  if (!state.runStart) fail(['telemetry journal is corrupt: missing run-start record']);
+
+  const windowStartMs = Date.parse(state.runStart.ts);
+  const nowMs = Date.now();
+  const sessions = transcriptDigestLib.discoverRunSessions(transcriptPath, { windowStartMs, windowEndMs: nowMs });
+  const digest = transcriptDigestLib.computeDigest(sessions, {
+    tailComplete: offline === true,
+    stageForTs: stageIntervalsFor(state, nowMs),
+  });
+
+  // Copy, never move — Claude Code owns the original.
+  const transcriptsDir = path.join(projectDir, 'telemetry', 'transcripts');
+  fs.mkdirSync(transcriptsDir, { recursive: true });
+  const manifestPath = path.join(transcriptsDir, 'manifest.json');
+  const manifest = fs.existsSync(manifestPath) ? JSON.parse(fs.readFileSync(manifestPath, 'utf8')) : {};
+  const runId = state.runStart.run_id;
+  const sessionIds = new Set(manifest[runId] || []);
+  for (const session of sessions) {
+    const dest = path.join(transcriptsDir, `${session.sessionId}.jsonl.gz`);
+    if (!fs.existsSync(dest)) fs.writeFileSync(dest, zlib.gzipSync(fs.readFileSync(session.path)));
+    sessionIds.add(session.sessionId);
+  }
+  manifest[runId] = [...sessionIds];
+  const manifestTemp = `${manifestPath}.${process.pid}.tmp`;
+  fs.writeFileSync(manifestTemp, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+  fs.renameSync(manifestTemp, manifestPath);
+
+  const recorded = await recorder.transcriptDigest(projectDir, digest);
+  return { ...recorded, sessions_included: sessions.length, tail_complete: digest.source.tail_complete };
+}
+
 async function main() {
-  const { positional, flags, meter } = parseArgs(process.argv.slice(2));
+  const { positional, flags, meter, sourceRead } = parseArgs(process.argv.slice(2));
   const [command, ...rest] = positional;
   const projectDir = flags.project || process.cwd();
   if (!fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) {
@@ -104,6 +193,14 @@ async function main() {
       result = recorder.meter(projectDir, payload);
       break;
     }
+    case 'source-read': {
+      // Counts key/value source reads; accumulates across calls, so a reader can
+      // report per batch. Table lists come as repeated --discovery-table/--scoped-table flags.
+      const fromJson = rest[0] === undefined ? {} : parseJsonArg(rest[0], 'source-read');
+      const payload = { ...fromJson, ...sourceRead };
+      result = recorder.sourceRead(projectDir, payload);
+      break;
+    }
     case 'wait':
       result = await recorder.wait(projectDir, rest[0], {
         haltSubtype: flags.halt,
@@ -111,6 +208,11 @@ async function main() {
         what: flags.what,
       });
       break;
+    case 'digest':
+      if (!flags.transcript) fail(['--transcript <path to Claude Code session jsonl> is required']);
+      if (!fs.existsSync(flags.transcript)) fail([`transcript not found: ${flags.transcript}`]);
+      result = await runDigest(projectDir, flags.transcript, { offline: flags.offline === true });
+      break;
     case 'finalize':
       result = await recorder.finalize(projectDir, parseJsonArg(rest[0], 'rollup'));
       break;
@@ -126,7 +228,7 @@ async function main() {
     default:
       fail(
         [`unknown command: ${command || '(none)'}`],
-        'commands: start, dims, record, stage start|end, meter, wait start|end, finalize, rebuild, status',
+        'commands: start, dims, record, stage start|end, meter, wait start|end, digest, finalize, rebuild, status',
       );
       return;
   }

package/skills/wix-replatform/resources/rp-website-continuation/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: rp-website-continuation
+description: >-
+  Continues a website-mode migration from the validated backend handoff through frontend
+  build, post-build gap analysis/fixing, release, and a durable frontend completion receipt.
+---
+
+# rp-website-continuation
+
+Use this resource only when the orchestration router returns
+`nextResource: resources/rp-website-continuation/`.
+
+## Contract
+
+**Editor destinations.** When `targetSiteType` is `studio` or `harmony`, there is no
+supported automatic website migration: never invoke `wix-headless-replatform`, never scaffold
+`frontend/`, and never publish the site. The router reports
+`editor_website_handoff_outstanding`; keep the website obligation outstanding as the
+completion report's `editor_website_unfinished` / `editor_publication_outstanding` operator
+actions (site owner/designer, then Cutover Operator) and do not claim combined completion until
+a valid released `website/completion.json` exists for the bound site.
+
+For `deliveryMode=website`, this is a frontend-only run — but it still needs a destination,
+and that destination is still `rp-destination`'s job, not this skill's or
+`wix-headless-replatform`'s. Do not let `wix-headless-replatform` scaffold its own site here:
+its only safeguard against a duplicate is "does a local folder already have a
+`package.json`," which is not the same account-confirmation gate, `WIX_SITE_ID`
+persistence, and dashboard-URL report that every other delivery mode gets.
+
+1. Resolve the destination via `rp-destination` first, scaffolding into
+   `<projectDir>/frontend` with `--site-template blank` (there is no backend catalog to
+   provision for, and this matches `wix-headless-replatform`'s own default template choice
+   for the home-scope clone this invocation performs). Persist `WIX_SITE_ID` in
+   `config/wix.env` and report the dashboard URL, same as any other mode.
+2. Then invoke `wix-headless-replatform` with the source URL and
+   `--out <projectDir>/frontend`; do not run backend discovery, mapping, setup, or import.
+   Because `<projectDir>/frontend` already contains a valid scaffold from step 1,
+   `wix-headless-replatform`'s own standalone reuse check finds it and continues from
+   there instead of scaffolding a second site.
+
+Finish its build and gap loop. Only when the user explicitly requested facelift at intake,
+run the separate post-clone UI/UX Pro Max facelift and acceptance review; otherwise do not
+load that stage. Then release and write `website/completion.json` with
+`finalize-migration-website.mjs --project-dir <projectDir> --out <projectDir>/frontend
+--release-url <public-url>`.
+
+`execution/completion-report.json` means backend import accounting. It is not the terminal
+result of a `deliveryMode=management_and_website` migration.
+
+**Two different documents, two different jobs.** `website/handoff.json` is the
+backend-to-frontend package: a website build needs its bindings contract *before* it starts, so
+it keeps being produced when it is, from the plan. It is **not** the run's account of the
+migration. That is `execution/review/migration-handoff.md`, generated after the last write from
+`execution/completion-report.json` — never hand `handoff-summary.md` to anyone as the account of
+what the migration did.
+
+The freshness check composes with this: once the backend import writes its completion report,
+`liveImportSummary` or `recoveryLog`, the recorded fingerprint moves and the router returns
+`stale_website_handoff`, forcing the package to be regenerated from the finished run before the
+frontend build consumes it.
+
+When the route reason is `missing_website_handoff` or `stale_website_handoff`, first run
+`node skills/wix-replatform/scripts/website-handoff-generate.js <projectDir>` and route
+again. Otherwise load the current `website/handoff.json`, then invoke
+`wix-headless-replatform` in migration mode via its `--handoff` flag:
+
+```bash
+node scripts/site-clone.mjs <source-url> --handoff <projectDir>/website/handoff.json
+```
+
+**`--handoff` is required here, not optional.** It is the only thing that puts
+`wix-headless-replatform` into migration-phase mode; without it the skill falls back to
+standalone mode and unconditionally scaffolds and executes a new `@wix/new headless` call —
+a second, orphaned site, which is exactly the failure "never create a second destination
+site" (see `rp-destination`) exists to prevent. Continue its actual build, post-build gap
+analysis, bounded fix loop, and release sequence. Do not stop after implementation or a
+successful build.
+
+The frontend skill must atomically write `website/completion.json` before this resource can
+finish. A successful receipt has the current `handoffFingerprint`, completed screenshot
+review, zero unresolved critical/high gaps, and a released (or explicitly not-applicable)
+release state.
+
+If a genuine blocker remains after required 1-click recovery/escalation retries, persist a
+`status: "blocked"` receipt with the blocker code, evidence, attempted recovery, owner,
+and exact unblock action. Then route again. Do not describe a pending storefront as a
+completed migration.
+
+After the gap loop has passed and the storefront is released, write the receipt with:
+
+```bash
+node skills/wix-headless-replatform/scripts/finalize-migration-website.mjs \
+  --handoff <projectDir>/website/handoff.json --release-url <public-url>
+```

package/skills/wix-replatform/scripts/census-reconciliation.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+const {
+  buildReconciliation
+} = require('../lib/census-reconciliation.js');
+async function main(args = process.argv.slice(2)) {
+  if (args.length !== 2 || args[0] !== 'build') throw new Error('Usage: census-reconciliation.js build <projectDir>');
+  const result = await buildReconciliation(path.resolve(args[1]));
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  if (result.errors.length) process.exitCode = 1;
+  return result;
+}
+if (require.main === module) main().catch(error => {
+  process.stderr.write(`${JSON.stringify({
+    ok: false,
+    code: error.code || 'census_reconciliation_failed',
+    message: error.message
+  })}\n`);
+  process.exitCode = 1;
+});
+module.exports = {
+  main
+};