@wix/agent-skills 1.33.1 → 1.35.0

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

@@ -0,0 +1,187 @@
+# 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

@@ -0,0 +1,137 @@
+# 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

@@ -0,0 +1,41 @@
+# 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

@@ -0,0 +1,93 @@
+# 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

@@ -0,0 +1,125 @@
+# 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.

package/skills/wix-headless-replatform/references/qa-checklist.md

@@ -0,0 +1,83 @@
+# Home-page QA checklist
+
+Run QA after manifest-derived implementation. A build is not acceptance.
+
+## Frozen boundary
+
+- `extraction/latest.json` matches the frozen manifest hash.
+- Every spec and dependency hash verifies before QA.
+- Every typed replay packet/reference hash verifies; a changed packet rejects replay.
+- Every build-plan unit has a matching implementation-ledger entry and spec hash.
+- `qa/visual-qa.json` contains one `unitAcceptance` record per planned unit and every
+  required frozen criterion is verified, pending, failed, or explicitly gap-backed.
+- Accepted units contain every classification-required field; every provisional
+  omission is represented by an owned local gap.
+- No builder/QA code rediscovered a source fact or read observations to fill a spec gap.
+
+## Unit fidelity
+
+For foundation, metadata, shared chrome, each recursive component, and every section:
+
+- Run the spec's content/order, asset, layer, layout, responsive, behavior,
+  accessibility, and visual/geometry acceptance checks at every required viewport.
+- Preserve exact visible copy, menu/footer hierarchy, links, logos/media/font tuples,
+  background/media role, positioned layers, and important text geometry.
+- Preserve observed control states, keyboard semantics, initial state, interaction end
+  states, reduced motion, and runtime initialization markers.
+- Keep each finding on its smallest owning unit. Do not compensate through unrelated
+  global CSS or another section.
+- Mark status `verified` only from rendered/browser evidence. Keep gap-backed work
+  `provisional`; human acceptance is `user-accepted`, not verified.
+
+## Page fidelity
+
+- The home route builds and serves in the actual Wix Headless Astro project.
+- Foundation/global CSS is installed once and shared chrome remains a first-class unit.
+- Section order, full-page rhythm, desktop/tablet/mobile reflow, first viewport, and
+  page-level behavior match the frozen page contract.
+- SEO metadata is applied without leaking metadata-only text into visible hero content.
+- Consent infrastructure marked ignored is not cloned as content.
+- No placeholder, clone-process, migration, or development copy appears.
+- External links remain absolute and preserved internal links behave honestly.
+
+## Registry
+
+- `build/component-selection.json` names the frozen manifest.
+- Every selected item is a pinned local registry revision with a valid human approval,
+  license record, runtime class, source hash, capability-manifest hash, agent-contract hash,
+  and quality evidence.
+- The resolved binding uses only manifest-declared axes/values, slots, states, and
+  compositions; unsupported requirements have deterministic rejection evidence.
+- The builder read only `component-selection.json` and the selected item's `contract.md`;
+  candidate reviews/provenance and registry internals were not added to agent context.
+- Astro/static versus React-island use is deliberate; interactive islands declare
+  hydration and accessible no-JavaScript behavior.
+- Items pass accessibility, keyboard, focus, responsive, SSR, RTL, reduced-motion,
+  dependency, styling-isolation, and state/variant checks.
+- When no item qualifies, rejection evidence exists and the bounded custom path is used.
+- `build/registry-installation.json` proves each selected local file hash and exact
+  dependency/capability binding; `qa/registry-opportunities.json` records reusable custom gaps.
+
+## Browser comparison and recovery
+
+- Run interaction verification and `post-build-gap.mjs` against the running home page.
+- Open every desktop/tablet/mobile screenshot pair at original size and write one complete
+  `visual-review.json` record per pair.
+- Fix missing structure/content/media first, then composition/geometry, core behavior,
+  and supporting polish.
+- For prior critical/high findings, `visual-progress.json` links canonical source,
+  before-result, and after-result screenshots and proves visible improvement.
+- A local evidence gap uses at most two distinct targeted recovery attempts. Repeating a
+  tactic without new evidence is no progress. After exhaustion, preserve the unit
+  provisionally and continue unrelated QA.
+- Only unresolved home identity, unusable page-wide capture, corrupt integrity,
+  unisolatable safety failure, or inability to assemble/build/serve any shell is blocked.
+
+## Final report
+
+- `final-report.json` and `.md` name every unresolved/user-accepted gap, visible location,
+  unavailable fact and reason, evidence/confidence/attempts, provisional implementation,
+  assumptions/omissions, affected checks/dependencies, and user choices.
+- No gaps plus reviewed passing browser evidence may become `done`.
+- Remaining local gaps become `done_with_gaps`.
+- Only a global blocker becomes `blocked`.