@wix/agent-skills 1.35.1 → 1.36.1

package/skills/wix-headless-replatform/references/control-and-visual-fidelity-contract.md

@@ -1,43 +0,0 @@
-# Control and Visual Fidelity Contract
-
-This layer sits beside the scene and layout contracts. It is deliberately modular:
-
-- `control-state-contract.json` owns representative control states and transition owners;
-- `visual-assets.json` owns identity-bearing logos/icons, their variants, usage, and size;
-- `layout-blueprint.json` owns text geometry and wrapping;
-- `scene-contract.json` owns initial interactive state, item separation, and motion scope.
-
-## Control terminology
-
-Use `rest`, `hover`, `focus-visible`, `pressed`, `activated`, `current`, and `disabled`.
-Implement the recorded delta on the element that owns it: target, `::before`, `::after`, or
-nested icon. Source-observed states outrank normalization defaults. If source focus evidence
-is absent, add a perceivable `:focus-visible` treatment without replacing source hover or
-current styling.
-
-## Text geometry
-
-Important text records include `inlineSize`, `blockSize`, `lineCount`, `wrapPolicy`,
-`maxWidth`, `fontSize`, and `lineHeight`. At the canonical desktop viewport, a captured
-`single-line` heading is an identity lock. Match its container width before shrinking type.
-
-## Stateful collections
-
-Respect `initialState` and `initialActiveIndexes`. `all-collapsed` means no item may be
-opened during runtime initialization. Reproduce `separation.mechanism`: it distinguishes
-track gaps, geometric gaps, margins, dividers, inner insets, and flush items.
-
-## Motion ownership
-
-`data-rp-visual` marks the measured visual transform owner. `data-rp-content` marks copy
-whose geometry is verified separately. Never nest static content inside a scaling visual
-wrapper unless source evidence explicitly says the content scales.
-
-## Logos and icons
-
-Logo priority is exact source file or materialized source SVG. Preserve all observed
-variants and usage sizes. Never recreate a logo as text or substitute a library mark.
-
-Icon priority is exact source asset, then the source sprite/library, then a style-matched
-established library such as Iconify. Library fallback is only allowed when no source icon
-exists and never applies to logos.

package/skills/wix-headless-replatform/references/extraction-schema.md

@@ -1,187 +0,0 @@
-# Extraction-first artifact contract
-
-Schema family: `0083.1`. The hand-authored JSON Schema 2020-12 files under
-`schemas/` are authoritative. `scripts/generate-extraction-validators.mjs`
-mechanically generates the dependency-free runtime validator committed at
-`scripts/lib/extraction-validators.generated.mjs`; `--check` rejects schema and
-validator drift. Semantic and cross-artifact checks remain in
-`scripts/lib/extraction-contract.mjs`. Product runs do not download a validator.
-
-## Scope and order
-
-This workflow resolves and reconstructs one home page. Do not accept non-home
-scope or explicit additional URLs until a later approved workflow defines their
-resolution and shared-evidence rules.
-
-1. Resolve the home page and `/` destination route.
-2. Capture browser evidence across the required viewports and safe states.
-3. Segment visible regions and assign exactly one owner.
-4. Extract the foundation, metadata, and shared chrome.
-5. Recursively extract section/component units.
-6. Enforce the rendered-content boundary, then validate and freeze accepted or provisional specs.
-
-Content-bearing fields come from browser-rendered text, never raw parent `textContent`.
-`script`, `style`, `noscript`, and `template` descendants are non-content even when a
-parent section is visible. Visible `pre`/`code` remains valid authored content and carries
-visible-code provenance. A strong source-code contamination signal omits only the affected
-strings, creates an owned local gap, and makes that unit provisional without blocking the
-rest of the home-page workflow. The content-extraction semantics version participates in
-the capture fingerprint so a capture made under older text semantics is not reused as the
-same capture.
-7. Derive a build plan only from the frozen manifest.
-8. Build, verify, recover bounded gaps, and issue the final report.
-
-## Canonical tree
-
-```text
-docs/site-clone/
-  page-resolution.spec.json          # early durable resolution checkpoint
-  extraction/
-    latest.json                      # capture id + frozen manifest hash only
-    <capture-id>/
-      page-resolution.spec.json
-      page-capture.spec.json
-      observations/
-        page.json
-        assets.json
-        seo.json
-        tokens.json
-        interaction-map.json
-        scene-contract.json
-        control-state-contract.json
-        visual-assets.json
-        layout-blueprint.json
-        ui-normalization.json
-        recursive-jobs.json
-        packets/*.packet.json         # typed, sanitized replay inputs
-      foundation.spec.json
-      metadata.spec.json
-      shared-chrome.spec.json
-      sections/<section-id>/section.spec.json
-      sections/<section-id>/components/<component-id>.spec.json
-      extraction-gaps.json
-      spec-index.json
-      extraction-manifest.json
-      replay-report.json              # replay captures only
-  build/
-    build-plan.json
-    component-selection.json
-    registry-installation.json
-    section-implementation.json
-  qa/
-    visual-qa.json
-    font-validation.json
-    registry-opportunities.json
-  final-report.json
-  final-report.md
-```
-
-Observation files are retained inputs to deterministic projection. Their sanitized,
-typed packet forms are the only replay inputs, and every packet/reference is paired
-with a semantic hash in the manifest. Packet tampering therefore invalidates the
-manifest before replay. Builders must not read observations or packets.
-`spec-index.json` maps stable unit IDs to frozen spec paths;
-`extraction-manifest.json` is the only authority for planning a build.
-
-## Frozen specs
-
-Every foundation, metadata, shared-chrome, section, and component spec has:
-
-- `schemaVersion`, `kind`, stable `id`, and `pageKey: "home"`;
-- `status: "accepted" | "provisional"`;
-- source-neutral content/layout/style/behavior/reconstruction/acceptance fields
-  appropriate to its kind;
-- evidence/provenance references;
-- direct dependency hashes;
-- owned `gapRefs`;
-- an immutable SHA-256 semantic hash.
-
-An accepted spec supplies every required fact. A provisional spec supplies every
-reliably observed fact and references at least one local gap naming every omitted
-required field, assumption, dependency, and affected acceptance check. Builders
-may implement the reliable portion but may not invent exact copy, assets, links,
-business actions, or unobserved behavior.
-
-## Serialization and hashing
-
-Use RFC 8785 canonical JSON and SHA-256. Semantic hashes include schema version,
-semantic fields, evidence references, detector versions, and direct dependency
-hashes. They exclude timestamps, formatting, logs, and machine-specific absolute
-path prefixes. A changed spec or dependency gets a new hash and invalidates stale
-downstream ledger entries. A hash proves identity/integrity, not confidence.
-
-All product artifact schemas reject unknown top-level fields. Extension data is
-allowed only in the explicitly named `extensions` object with a namespaced key.
-
-## Acceptance authority
-
-Hard gates are deterministic and cannot be waived by the agent: schema validity,
-referential integrity, exact ownership or explicit ignore/gap, required
-provenance, safe-probe compliance, dependency closure, hash integrity, and no
-unresolved global blocker.
-
-Per-detector confidence is calibrated on the approved corpus. A high band must
-meet at least 95% precision and may freeze automatically. Medium candidates become
-compact typed decision requests for the orchestrating agent. Low confidence,
-agent abstention, or invalid patches become gaps. The agent chooses only among
-the typed choices and cannot override hard gates.
-
-## Anti-stuck gaps
-
-Each gap declares owner, local/global scope, missing fields, reason, confidence,
-evidence, dependency closure, acceptance impact, attempts, remaining budget,
-assumptions, omissions, and user decision.
-
-- A local gap never stops unrelated extraction, freeze, build, or QA.
-- Affected work receives at most two distinct targeted attempts. Repeating the
-  same tactic without new evidence is rejected as no progress.
-- After the budget is exhausted, the affected dependency closure freezes and
-  builds provisionally.
-- Only unresolved home identity, unusable page-wide capture, corrupt integrity,
-  unisolatable safety failure, or inability to assemble/build/serve any viable
-  shell is a global blocker.
-- Local gaps remaining at handoff produce `done_with_gaps` and a final report;
-  they do not produce a blocked run.
-
-After assembly the user may accept, retry/fix, provide material, replace, omit,
-or leave each provisional unit unresolved. Human acceptance does not relabel an
-unverified unit as verified.
-
-## Safe behavior evidence
-
-Probe only public unauthenticated pages. Allow scrolling, hover, focus, keyboard
-navigation, resize, bounded waits, and controls confidently classified as local
-presentation changes (tabs, disclosures, menus, carousel controls). Block form
-submission, authentication, cart/checkout, purchase/booking, uploads, account or
-admin state, destructive controls, navigation, mutating requests, and any
-unclassified click. Record blocked actions/requests and hard action/time budgets.
-
-## Evidence lifecycle
-
-Keep evidence local until explicit cleanup. Redact authorization/cookie headers,
-secrets, sensitive query values, and form values before persistence. Content-hash
-and deduplicate downloaded assets. Full browser traces/video are opt-in diagnostic
-artifacts. Cap retained evidence at 250 MB, frozen specs and manifests at 10 MB, typed
-agent decisions at 30, agent input at 50,000 tokens, and p95 extraction at ten
-minutes on the approved benchmark.
-
-Replay retained packets unless source fingerprint, required observation kind,
-viewport/state set, capture semantics, or packet integrity changed. Detector,
-schema projection, or typed-decision changes alone do not require recapture.
-
-## Registry boundary
-
-The shadcn-format registry under `registry/` contains only pinned, human-approved
-runtime revisions. Candidate intake and review happen outside the published
-skill under the repository's `registry-candidates/` workspace; deterministic
-promotion copies only approved source, capabilities, the compact agent contract,
-license, and approval record into `registry/`.
-
-Selection code filters hard license/accessibility/responsive/SSR/RTL/reduced-
-motion/runtime requirements and the hash-pinned generic `capabilities.json`
-axes, slots, states, compositions, and constraints. It records rejection
-evidence and the resolved typed binding in `build/component-selection.json`.
-The building agent reads that selection record and, only for a selected item,
-the referenced `contract.md`. It does not scan the registry or read capability
-JSON, approvals, licenses, source provenance, candidate reviews, or live
-documentation. When nothing qualifies, use the bounded custom builder.

package/skills/wix-headless-replatform/references/interaction-runtime-contract.md

@@ -1,137 +0,0 @@
-# Interaction Runtime Contract
-
-Use this contract after `interaction-map.json` and `scene-contract.json` identify one or
-more core scenes.
-
-## Principle
-
-Implement the observed state machine, not the source library. A source may use GSAP,
-Framer Motion, Web Animations, CSS transitions, or custom JavaScript. The clone may use a
-different mechanism as long as its content, visual states, transition shape, responsive
-behavior, and interaction invariants match the evidence.
-
-Do not translate a scene contract to more descriptive prose. Start from the declared
-primitive, bind extracted content and media to it, and expose the QA markers below.
-
-## Required markers
-
-Every core scene:
-
-```html
-<section data-rp-scene="home-home-section-002" data-rp-initialized="active-card-rail">...</section>
-```
-
-Active-card rail:
-
-```html
-<section data-rp-scene="..." data-rp-initial-state="all-collapsed">
-<div data-rp-viewport>
-  <div data-rp-track>
-    <article data-rp-item data-rp-hover-target data-rp-active="true">
-      <button data-rp-activate>...</button>
-    </article>
-  </div>
-</div>
-</section>
-```
-
-Content switcher:
-
-```html
-<button data-rp-item data-rp-activate data-rp-active="true">...</button>
-<div data-rp-panel>...</div>
-```
-
-Scroll scene:
-
-```html
-<section data-rp-scene="..." data-rp-phase="approach">
-  <div data-rp-visual>...</div>
-  <div data-rp-content>...</div>
-  <div data-rp-curtain="left"></div>
-  <div data-rp-curtain="right"></div>
-  <div data-rp-panel>...</div>
-</section>
-```
-
-Markers are implementation instrumentation. Do not copy source selectors into them.
-
-`site-clone.mjs` installs framework-source copies and browser-ready public copies. The
-default and safest startup is the exact contract bootstrap, included once by the page:
-
-```html
-<script type="module" src="/site-clone/rp-interactions-bootstrap.mjs"></script>
-```
-
-Do not use an inline raw-browser import of `../lib/rp-interactions.mjs`; a browser URL is
-not resolved from `src/`. The bootstrap auto-binds complete marker contracts after DOM
-readiness. `data-rp-initialized` is runtime evidence, not a marker to hard-code in markup.
-Source-specific CSS and content still belong in the page/component implementation.
-
-## Primitive rules
-
-### `active-card-rail`
-
-- Render every captured repeated item in source order.
-- Keep a real horizontal track inside a separate scroll viewport; do not substitute a grid.
-- Put `overflow-x` and scrolling on `data-rp-viewport`; put `width: max-content` or the
-  equivalent row sizing on `data-rp-track`. A max-content track cannot be its own viewport.
-- Use the exact captured initial active indexes. Set `data-rp-initial-state="all-collapsed"`
-  when source has none; runtime initialization must not auto-open an item.
-- Reproduce the measured separation mechanism: track gap, geometric gap, item margin,
-  divider, inner inset, or flush.
-- Preserve the observed expanded/collapsed width ratio within the contract tolerance.
-- Controls and direct item activation must update the same state.
-- Mark the source hover surface with `data-rp-hover-target` and reproduce its visual hover
-  treatment with keyboard-equivalent focus styling.
-- Reproduce nested reveal order and approximate settle time from the captured timeline.
-
-### `content-switcher`
-
-- Use visible controls with one current state.
-- Keep all captured state content in the implementation.
-- Change the visible `data-rp-panel` content and active marker on activation.
-- Preserve keyboard access and relevant ARIA state.
-- Give controls and panels matching `data-rp-state` values so `bindContentSwitcher` can
-  manage state deterministically.
-
-### `scroll-scene`
-
-- Derive progress from the scene's own scroll range.
-- Preserve entry/approach phases and internal pinned phases in their captured order.
-- Keep `data-rp-phase` synchronized with the visual state.
-- Expose continuous `--rp-entry-progress` and `--rp-scroll-progress` custom properties.
-- Mark only the measured pinned/cropped/scaled visual wrapper with `data-rp-visual`.
-- Mark independently positioned copy with `data-rp-content` and keep it outside visual
-  scaling unless source content geometry explicitly scales.
-- Reproduce large sibling reveal layers from `sceneLayers`, including paired curtains or
-  masks. Mark observed curtains with `data-rp-curtain` so reveal distance is verified even
-  when the media itself stays full-width.
-- Do not flatten the scene into static columns when source evidence includes pinning.
-- Pass captured phase names/progress thresholds to `bindScrollScene`; combine it with
-  `bindContentSwitcher` when tabs share the same scene.
-
-### `sticky-header` and `media-scene`
-
-- Preserve the captured trigger threshold and material chrome changes.
-- Keep source-backed media interactive with the recorded URL and playback flags.
-- Treat a poster or background with `fallbackPolicy: "fallback-only"` as mutually exclusive
-  with a successfully loaded video/iframe. Do not leave it as a visible layer behind media.
-
-## Runtime QA
-
-Start the clone locally, then run:
-
-```bash
-node scripts/verify-interactions.mjs \
-  --out projects/<project-name> \
-  --clone-url http://127.0.0.1:4321 \
-  --project-root <project-root> \
-  --viewports 375,768,1440
-```
-
-The command writes `docs/site-clone/interaction-qa.json` and exits non-zero if a core
-scene is absent, lacks its runtime initialization token, or violates its assertions at
-**any** of the listed viewports — a layout correct at 1440 and broken at 375 is a failure,
-not a pass. Fix failures before final visual polish. Omitting `--viewports` checks only
-the historical 1440px viewport.

package/skills/wix-headless-replatform/references/layout-blueprint-contract.md

@@ -1,41 +0,0 @@
-# Section Layout Blueprint Contract
-
-`layout-blueprint.json` is the source of truth for how every section is composed. It sits
-between source/scene extraction and UI normalization. Implement one section at a time in
-this order:
-
-1. canvas width, height, positioning context, overflow, and pinning;
-2. ordered background layers (`base`, `media`, `scrim`, `decoration`);
-3. foreground container;
-4. semantic regions and their normalized rectangles;
-5. important text geometry, observed line count, and wrapping policy;
-6. region relationships and responsive reflow;
-7. interaction mechanics, then UI normalization.
-
-## Controlled vocabulary
-
-Use the vocabulary embedded in the artifact. Composition is one of `layered-overlay`,
-`split`, `stack`, `grid`, `rail`, `scroll-narrative`, or `freeform`. Background is `none`,
-`color`, `gradient`, `image`, `video`, or `composite`. Regions use roles such as `heading`,
-`body-copy`, `media`, `action`, and `tabs`, with a nine-position placement anchor.
-Text wrapping uses `single-line`, `wrapped`, or `clipped-or-overflowing`.
-
-The terms make implementation consistent; normalized rectangles preserve distinctive
-source geometry. Do not replace the measurements with a generic layout merely because its
-name sounds similar.
-
-## Identity rules
-
-- Composition, background-media role, layer order, and declared relationships are identity
-  locks.
-- `layered-overlay` and `scroll-narrative` media must not become a peer column beside copy.
-- `fallback-only` posters disappear when primary video/iframe media is ready.
-- Scene evidence overrides static DOM evidence for animated or pinned phases.
-- A measured single-line desktop heading must remain one line at the canonical desktop
-  viewport; preserve its inline-size constraint before adjusting typography.
-- Responsive reflow may stack a declared split, but it must retain content hierarchy and
-  media role.
-
-New best-practice rules should consume this artifact from UI normalization. Extend
-`scripts/lib/layout-blueprint/` classifiers or vocabulary independently; bump the vocabulary
-version when controlled terms change.

package/skills/wix-headless-replatform/references/output-contract.md

@@ -1,93 +0,0 @@
-# Output contract
-
-## Project and recovery boundary
-
-The default output is `projects/<project-name>` using Wix CLI Headless, Astro,
-TypeScript, and Tailwind. Standalone build mode must provision a real Wix project
-before writing clone artifacts. Migration mode reuses the handoff-owned project;
-it never creates or retargets a second site.
-
-Browser extraction requires the host preflight. Retry shell/PATH/tool resolution in
-the compatible interactive login shell, then request browser/network escalation and
-retry. Sandboxed browser-launch or network failures are not terminal on first occurrence
-in one-click mode.
-
-## Implemented scope
-
-The output owns one resolved home page at `/`. Additional static pages, explicit URL
-scope, and multi-page shared-evidence conflict resolution are not implemented. Wix
-business routes from a migration handoff may remain linked/preserved, but this skill does
-not reconstruct their visual pages.
-
-## Required artifact tree
-
-The durable source contract is:
-
-- `docs/site-clone/page-resolution.spec.json`;
-- `docs/site-clone/extraction/latest.json`;
-- the referenced capture directory with observations, frozen specs, gaps, index,
-  and manifest;
-- `docs/site-clone/build/build-plan.json` and `component-selection.json`;
-- `docs/site-clone/build/section-implementation.json`;
-- `docs/site-clone/qa/` verification artifacts;
-- `docs/site-clone/final-report.json` and `.md`.
-
-Old flat `source-map.json`, `tokens.json`, `seo.json`, page/component handoffs, and
-their resume semantics are not builder contracts. Extractors may produce equivalent
-signals internally, but they are frozen under the capture's `observations/` directory
-and only projected specs cross into building.
-
-## Generated home page
-
-- Verify the frozen manifest and build-plan hash before writing UI.
-- Install the frozen foundation and metadata, then shared chrome, recursive
-  components, and sections in declared dependency/source order.
-- Preserve exact observed text, links, source media/logos/fonts, layers, layout,
-  responsive behavior, accessibility, and safe observed interaction end states.
-- Never invent missing copy, asset identity, navigation, business action, or
-  behavior. Implement the reliable portion provisionally and link it to its gaps.
-- Use Astro for static/content-heavy UI and React only for useful interactive
-  islands with deliberate hydration.
-- Select only pinned, human-approved items from the local registry. Record why an
-  item was selected/rejected and the exact approved capability-manifest hash and
-  agent-contract hash plus the resolved binding. Use only declared variations;
-  expose only the generated selection and selected `contract.md` to the builder,
-  and use the bounded custom path when none qualifies.
-- Add stable `data-rp-unit`, manifest-hash, classification, state, and runtime
-  markers needed by generated acceptance tests.
-- Keep the implementation ledger keyed to frozen spec hashes. Code inspection
-  cannot mark a unit verified.
-
-## Gap and completion status
-
-A local gap never blocks unrelated units. It receives at most two distinct targeted
-recovery attempts and then becomes provisional. The assembled page is handed to the
-user with choices to accept, retry/fix, provide material, replace, omit, or leave the
-unit unresolved.
-
-`final-report.json` and `.md` must identify what could not be imported reliably and
-why, its evidence/confidence/attempts, assumptions/omissions, affected checks and
-dependencies, provisional output, and user decision. Remaining local gaps produce
-`done_with_gaps`; only a genuine global blocker produces blocked. A provisional or
-user-accepted limitation is never described as verified.
-
-## Migration terminal receipt
-
-For `management_and_website`, `website/completion.json` is valid only after the
-latest browser comparison/review has no unresolved critical/high identity finding,
-the final report is present, and any requested facelift has its separate acceptance.
-A successful build or backend import is not frontend completion. The receipt records
-the handoff fingerprint, frozen manifest hash, release URL, final status, and evidence
-references.
-
-For a migration with public source URLs, the build also writes the **final route manifest**
-`state/url-preservation/final-routes.json` in the migration project: `siteId`,
-`deploymentId`, and per routed entity `sourceKey` (the URL ledger's `sourceStableKey`),
-`targetEntityType`, `targetEntityId`, final site-relative `relativeUrl` and a stable
-`pageMarker` string that the rendered page contains (for example a `data-entity-id`
-attribute). Record the referenced entity itself, not a page that merely contains it. The
-receipt references this manifest and the current `execution/url-preservation-report.json`
-status. A successful build never implies that old URLs are preserved: old-link planning,
-redirect application and public verification are separate helper runs
-(`skills/wix-replatform/scripts/url-redirects.js`) that the cutover step schedules. Until
-they run, the receipt shows the pending URL work instead of a substitute launch flow.

package/skills/wix-headless-replatform/references/post-build-gap-contract.md

@@ -1,125 +0,0 @@
-# Post-build gap analysis and fix contract
-
-The first successful build is a comparison candidate, not the end of the clone.
-
-## Run the result extraction
-
-Start the generated project and keep its local URL available, then run:
-
-```bash
-node scripts/post-build-gap.mjs <source-url> \
-  --out projects/<project-name> \
-  --result-url http://localhost:<port>/
-```
-
-The command reuses the capture primitives for the home result route. It captures the result's
-desktop/tablet/mobile screenshots, page and section evidence, assets, fonts, SEO, interactions,
-design tokens, scene contract, control-state contract, visual assets, layout blueprint, and UI
-normalization evidence. Source contracts are read through `extraction/latest.json` and its
-immutable frozen manifest; builders and QA do not read or recapture source observations as a
-substitute for a missing spec fact. Result evidence is isolated under the numbered gap iteration
-and never replaces the frozen extraction.
-
-If Chromium launch is blocked by the execution environment, that is a recovery case before
-it is a blocker: rerun the command with the required browser-launch escalation (or from a
-normal local shell/session that permits Playwright to launch) before treating the gap run
-as failed.
-
-## Deterministic comparison vocabulary
-
-Findings use these categories:
-
-- `dimensions`: full-page/section height, normalized region geometry, important text width,
-  line count, and logo size;
-- `images`: source image/video/logo identity, count, role, and placement;
-- `layout`: route and section coverage, section order, composition, background model, and
-  media ownership;
-- `text`: visible headings, body copy, labels, tabs, and CTAs;
-- `interactions`: source core behavior not observed in the running result.
-
-Severity means:
-
-- `critical`: missing route or identity-bearing brand media;
-- `high`: source intent or a major layout/interaction is wrong;
-- `medium`: meaningful supporting geometry/style differs beyond tolerance;
-- `low`: review or cleanup that does not materially change identity.
-
-Exact requirements and tolerance ranges are embedded in `gap-analysis.json`. Do not turn
-this into a universal pixel-diff gate. Consent infrastructure, different video frames,
-font antialiasing, timestamps, and small crop/compositing differences are non-blocking unless
-they change layout or page intent.
-
-## Required screenshot judgment
-
-The deterministic report creates `screenshotPairs[]` with source and result paths. Open every
-pair at original size, at all captured viewports. Review the page section by section and add
-only identity-affecting visual findings to the canonical iteration report referenced by
-`latest.json.paths.reportJson`, using the same finding schema.
-
-Write `iterations/<NNN>/visual-review.json` using this shape (one record for every pair):
-
-```json
-{
-  "pairs": [
-    {
-      "pairId": "home-desktop",
-      "viewport": "desktop",
-      "observation": "Hero dog is substantially larger than the source and obscures the title.",
-      "verdict": "findings-recorded",
-      "findingIds": ["gap-041"]
-    },
-    {
-      "pairId": "home-mobile",
-      "viewport": "mobile",
-      "observation": "Header hierarchy, hero composition, and visible section order match source identity.",
-      "verdict": "no-identity-gap",
-      "rationale": "Only harmless antialiasing differences remain."
-    }
-  ]
-}
-```
-
-After review, run:
-
-```bash
-node scripts/finalize-gap-review.mjs <source-url> \
-  --out projects/<project-name>
-```
-
-The finalizer rejects missing, duplicate, unknown, or incomplete records; verifies linked
-finding IDs against the canonical report; synchronizes the canonical report, latest pointers,
-and iteration manifest; and recomputes acceptance.
-
-## Gap fix phase
-
-Use `gap-fix-plan.md` in this order:
-
-1. missing page/section;
-2. text, logos, and source media;
-3. major section composition and background/media ownership;
-4. important dimensions, line counts, and responsive geometry;
-5. core interactions and initial states;
-6. supporting spacing and styling.
-
-Fix the implementation rather than weakening tolerances or editing extracted result evidence.
-For a new iteration following open critical/high findings, complete the generated
-`visual-progress.json`. It must give every prior blocking finding a named section target plus
-the matching canonical source, prior-result, and current-result screenshot paths; record visible
-before/after observations and an `improved`, `no-visible-improvement`, or `regressed` verdict.
-The finalizer rejects incomplete or untraceable proof, and an accepted resolution requires
-`improved`. Build again, rerun `post-build-gap.mjs` to create the next immutable iteration,
-inspect its new screenshot queue, and finalize the review. Run at most two fix passes by default.
-Each owned extraction gap receives at most two distinct targeted recovery attempts. Repeating
-the same tactic without new evidence is not progress. After exhaustion, keep the unit
-provisional and continue unrelated work. Report what could not be imported reliably, why, and
-the user's post-assembly choices instead of treating a local gap as a global blocker.
-
-Completion requires:
-
-- the latest build succeeds;
-- visual review is `reviewed` (or legitimately `not-applicable`);
-- no open critical or high findings remain;
-- interaction QA passes for core scenes;
-- residual medium/low and provisional extraction gaps are summarized rather than hidden;
-- `final-report.json` and `.md` identify every unresolved/user-accepted gap;
-- local gaps end as `done_with_gaps`; only a global blocker ends as blocked.