@nextcommerce/campaigns-os 1.60.0 → 1.62.0

package/skills/next-campaigns-polish/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-polish
-version: 1.1.46
+version: 1.1.53
 description: Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign.
 ---
 
-Bundle revision: 1.60.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.60.0+skills.1`
+Bundle revision: 1.62.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.62.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read
@@ -59,7 +59,7 @@ Responsibilities:
 - Scan **visible** rendered text inside the family's content/commerce surfaces (the selectors enumerated in `contracts/template-brand-contract.<family>.v0.json`) for placeholder/residue copy the build should have replaced — the *literal starter defaults*: lorem-ipsum, the unmodified starter headings (`Product Name` / `Package Title` / `Your headline`), `[VERIFY …]` author notes, `TODO` markers. Match the literal starter strings, not any authored copy that merely contains those words, and skip `<script>` / `<style>` / JSON-LD / `data-*` attributes. Treat a surviving literal starter default on a content/commerce surface as a polish blocker — replace it from the prepared source / CampaignSpec; do not draft substitute copy (if the design's authored copy is genuinely missing, flag it rather than invent it). This is *copy* residue, complementary to the computed-style / asset residue gated by `next-campaigns-qa` + the brand contract — not a duplicate of it.
 - Flag template *defaults* left where they disagree with the prepared design — e.g. the same benefit icon repeated across a grid *when the design uses distinct icons*, or a guarantee badge/term that disagrees with the design — as polish defects, not just logos. Judge against the prepared source, not taste: copy or imagery the source/CampaignSpec does not supply (e.g. a placeholder testimonial name/quote/role) is residue; "looks generic" on its own is not. Copy the source does supply, including its proof and urgency elements (reviews, "Verified Purchase" labels, recent-purchase popups, stock counters, countdowns, guarantees), is the merchant's content: keep it as designed and do not record it as an issue or an unconfirmed claim.
 - **Brand-bleed (cloned-source de-brand) pass.** When a campaign is cloned from a proven sibling, the sibling's brand defaults ride along. Inspect the built pages and assets for residual cross-brand bleed and clear it before recording: (1) a residual promo/sale banner or coupon code/copy from the source campaign (including a baked-in *fake* code); (2) a prior-campaign / sibling favicon left in place; (3) scaffold or non-design fonts the design did not specify (e.g. starter `Plus Jakarta`); (4) hardcoded non-token colors — any brand color literal that should be a token, such as next-core's `#C670FE` "Most Popular" pill. Clear each from the prepared source / CampaignSpec and brand theme (tokens, not literals); flag — do not invent — anything the design genuinely doesn't supply. Treat surviving bleed as a polish blocker. This complements the favicon/logo and copy-residue checks above; it is the cross-brand contamination angle, not a duplicate.
-- Read the normalized Campaign Build Brief at `.campaign-runtime/input/campaign-build-brief.normalized.json` and the recorded decisions (`adapter_decisions`, `decisions` and `theme` in `.campaign-runtime/assembly-report.json`, and `assembly.template_decision_notes` in the Build Packet) before working on the campaign. The campaign intent summary at the top of the setup, build, Polish and QA prompts and in every `next` result is orientation, never a source of prices or commerce behaviour.
+- Read the normalized Campaign Build Brief at `.campaign-runtime/input/campaign-build-brief.normalized.json` and the recorded decisions (`adapter_decisions`, `decisions` and `theme` in `.campaign-runtime/assembly-report.json`, and `assembly.template_decision_notes` in the Build Packet) before working on the campaign. The campaign intent summary at the top of the setup, build, Polish and QA prompts and in every `next` result is orientation, never a source of prices or commerce behaviour. For a later funnel in a multi-funnel project, read the same files under its own `assembly.runtime_dir` (`.campaign-runtime/funnels/<route>/`); the paths `next` prints are already the right ones.
 - Read the assembly report decisions before polishing. Do not reintroduce source-HTML elements that build intentionally dropped because CampaignSpec/API did not support them, such as unavailable payment methods.
 - **Remove or rename a contract-listed payment-chrome asset; never edit one in place.** The assets named in `contracts/template-brand-contract.<family>.v0.json` under `default_residue.payment_chrome.assets` are keyed by QA on the *referenced basename*, not on their contents. Stripping the unsupported marks from inside a shared file such as `upsell-payment-logos.svg` leaves the reference in place, so QA reports residue for an asset that no longer carries any — and on 2026-09-06 the repair loop's remedy for that report deleted a cards-only trust strip that was correct. Delete the asset, or write a new one under a new name and repoint the reference. QA downgrades an edited-in-place asset to `manual_review` rather than a blocker, but that is a safety net for a mistake, not the supported way to do this.
 - Preserve existing `report.theme` data. If polish changes generated theme CSS, load order, commerce-page coverage, theme warnings, or the first repair-loop defect, update the Assembly Report `theme` block rather than leaving stale evidence.
@@ -70,7 +70,7 @@ Responsibilities:
 - Treat express wallet presence as browser/device eligible. Record which wallets mounted in the tested browser, but do not fail solely because Apple Pay is absent in a non-eligible browser. Fail or block when the express mount is empty despite supported wallets, or when mounted wallet buttons are visually malformed.
 - For bundle selectors and order bumps, verify active/inactive visual state after interaction, mobile label wrapping, badge placement, and selected/unchecked state. A native hidden input state that disagrees with the SDK class state is a polish blocker. So is a selected/active visual driven by a *non-SDK static attribute the SDK never clears* — e.g. a hardcoded `data-selected="true"` left on the initial card. (The native `selected` attribute on `<option>`/custom selects *is* SDK/browser-managed, so do not flag that.) The selected style must follow the SDK-managed class (e.g. `.next-selected` — see the family's bundle-selector selectors in `contracts/template-brand-contract.<family>.v0.json`) so a single-select swap clears the previous selection. Verify by interaction that the previously-selected item deselects after another is picked — a selector that only ever paints "selected" on click is a blocker.
 - For exit-intent pops and promo-code inputs, polish the wrapper/copy states without breaking SDK coupon/voucher apply hooks or `cart.hasCoupon("CODE")` conditional labels.
-- If `report.theme` or `context.theme` exists, verify brand-theme load order after `next-core.css`, source-token parity for primary color/CTA/surface/text/font/radius when present, and SDK safety. When the brand layer is missing, stale, low-confidence, or unsafe to apply, record the first repair-loop defect or an explicit skipped reason.
+- If `report.theme` or `context.theme` exists, verify brand-theme load order after `next-core.css`, source-token parity for primary color/CTA/surface/text/font/radius when present, and SDK safety. Check font parity by computed style at a mobile and a desktop width, not desktop alone: next-core re-declares its font tokens on `body` below 992px, so a layer that sets them only on `:root` holds on desktop and falls back on mobile. When the brand layer is missing, stale, low-confidence, or unsafe to apply, record the first repair-loop defect or an explicit skipped reason.
 - When at least one mapped page has a design route, before recording a terminal
   Polish status, install the package-owned browser once with
   `npx --no-install campaigns-os qa install-browser`, serve the current build,
@@ -93,7 +93,9 @@ Responsibilities:
   <preview route root>`, then `campaigns-os qa run --packet <packet>
   --base-url <preview-url> --browser --test-order common`, then closeout. QA
   against the packet's production URL keeps the checkpoint blocked.
+- In the handoff, `parity.element` rows are element differences to review or accept. `design.access` unexercised means the file was not read: compare by hand. A `design.access` review row means a changed, missing or conflicting design file: fix the declaration or rerun intake with `--force`. These rows never block Polish.
 - When a readability warning appears, report it with its colours, ratio, requirement and pages. Offer the operator options inside the brand palette (a darker or lighter shade of the same hue, the palette's text colour, or a larger, bold label where the design allows). Do not recolour the merchant's design until the operator chooses. Accept a warning only with the refs, reason and name the operator gives you at the QC handoff.
+- A `layout.conventions` warning is a mobile layout convention: `floating_cta` means a fixed or sticky CTA bar holds more than its one control (the row names the bar and the other text), and `cta_label_size` means a CTA label is under 16px (the row gives the measured size). Report it with the page and element, offer the fix (move the extra text out of the bar, or raise the label size where the design allows), and leave the merchant's copy alone. Accept it only with the refs, reason and name the operator gives you. These rows never block Polish.
 - Record Polish as `completed`, `skipped`, or `blocked` with
   `campaigns-os record polish --packet <packet> --evidence <polish-evidence.json>`
   (tier `C`: it overwrites `stages.polish` in the assembly report and stamps the
@@ -117,11 +119,7 @@ schema reference; this section is the recording guidance.
 **All seven evidence fields are required** or the gate blocks with
 `polish.evidence_incomplete`:
 
-- `visual_review` — an **object with a `screenshots` array** (aliases:
-  `screenshot_paths`, `paths`, `urls`) holding at least one non-empty
-  path/URL string for the captured desktop+mobile evidence, plus the
-  package-generated `page_load` object. A bare string or a screenshot-less
-  object does NOT pass, no matter how real the review was.
+- `visual_review` — run `campaigns-os polish capture` first: it records the package captures (`captures`) and `page_load`, which satisfy the screenshot requirement, and `record polish` refuses a completed Polish without them. Do not write screenshot paths to satisfy the check, and never write `captures` or `page_load` by hand. Report self-referential references and the review list from the QC handoff to the operator; accept a self-referential warning only when the operator decides to use the current output as the baseline for later revisions.
 - `brand_review` — object; must include the `favicon` attestation and the
   `brand_bleed` attestation (below).
 - `checkout_review` — object; must include `field_labels` (aliases

package/skills/next-campaigns-qa/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-qa
-version: 1.3.45
+version: 1.3.52
 description: Run spec-aware QA from a saved Map or local-spec Build Packet and tested campaign URL after build, polish, and deploy/local evidence exist, including Playwright typed-card test-order proof.
 ---
 
-Bundle revision: 1.60.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.60.0+skills.1`
+Bundle revision: 1.62.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.62.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read
@@ -70,7 +70,7 @@ Inputs:
 - tested base URL (localhost dev URL, preview URL, or production URL)
 - assembly report
 - Test-order coverage choice (`common` default vs explicit paths vs topology-complete `full`) and SDK origin state (localhost is a Development domain; non-localhost origins need allowlist confirmation so the SDK loads)
-- Read the normalized Campaign Build Brief at `.campaign-runtime/input/campaign-build-brief.normalized.json` and the recorded decisions (`adapter_decisions`, `decisions` and `theme` in `.campaign-runtime/assembly-report.json`, and `assembly.template_decision_notes` in the Build Packet) before working on the campaign. The campaign intent summary at the top of the setup, build, Polish and QA prompts and in every `next` result is orientation, never a source of prices or commerce behaviour.
+- Read the normalized Campaign Build Brief at `.campaign-runtime/input/campaign-build-brief.normalized.json` and the recorded decisions (`adapter_decisions`, `decisions` and `theme` in `.campaign-runtime/assembly-report.json`, and `assembly.template_decision_notes` in the Build Packet) before working on the campaign. The campaign intent summary at the top of the setup, build, Polish and QA prompts and in every `next` result is orientation, never a source of prices or commerce behaviour. For a later funnel in a multi-funnel project, read the same files under its own `assembly.runtime_dir` (`.campaign-runtime/funnels/<route>/`); the paths `next` prints are already the right ones.
 
 Rules:
 
@@ -95,6 +95,7 @@ Rules:
 - Saved-Map QA publishes to the QA portal under the existing consent and flag controls; report the portal link only when publication succeeds. Pass `--no-post-verdict` (or `--local-only`) to keep that verdict local. This stays tier `C`: served-page probes, requested orders, Run Telemetry and progress retain their own controls. See `docs/qa-and-test-orders.md` for the saved-Map publication policy.
 - Local-spec QA always keeps verdicts and progress local. `qa run` suppresses portal publication even with `--post-verdict`; `qa publish` refuses local-spec packets with `local_spec`. Report the local verdict/sidecar as evidence, never a dashboard link. A matching route cannot replace a matching `local_spec_id`, and QA refuses a foreign or stale local Assembly Report. Run Telemetry still follows its consent controls.
 - Browser QA must include checkout commerce geometry evidence, not just mount counts: express-wallet buttons rendered in the current browser, card/CVV hosted iframe host dimensions, iframe text-path height, and center alignment. Apple Pay is browser/device eligible, so record mounted wallet kinds instead of requiring Apple Pay in Chrome-only QA.
+- After launch, when `next` or `doctor --ci` reports a page-only change (only some pages' HTML changed, and no checkout page, commerce markup, route, script or Page Kit config entry), QA is owed on those pages only and Polish is advisory: after `record build`, run `qa run --packet <packet> --page <page_id>` with one `--page` per changed page it names. A page-scoped run places no test orders and keeps the purchase proof of the full run it extends; it refuses a commerce-affecting change, a last QA that did not complete, or a brief `qa_policy` or CampaignSpec change, each of which owes a full `qa run`. See `docs/campaigns-os-build-flow.md#what-a-change-owes`.
 - `qa resolve` accepts either the deploy host or the campaign-root URL; when a Build Packet carries `campaign.public_route_slug`, the runner resolves page URLs under that slug.
 - Routing meta tags must be checked in runtime form. `next-success-url`, `next-upsell-accept-url`, and `next-upsell-decline-url` should point at campaign-root paths such as `/campaign-slug/upsell/`, not source filenames or unrooted spec literals.
 - Upsell accept/decline routes may be SDK-bound controls rather than static `<a href>` links. Treat rendered `data-next-upsell-action="add"` and `data-next-upsell-action="skip"` controls as valid route evidence, then prove the path in the browser walkthrough.
@@ -102,6 +103,7 @@ Rules:
 - When CampaignSpec declares checkout `promo_code_input.enabled`, browser QA should enter the mapped `offer_code` and verify active-code state, repricing, discount row rendering, and conditional presentation. Missing promo-code input is a blocker when CampaignSpec, source design, or user instructions declared it.
 - A declared offer surface that the build never shipped is a blocker, not a silent pass. Every `--browser` run emits `browser-exit-intent-surface:<page>` and `browser-promo-code-surface:<page>` for each checkout page whose CampaignSpec declares the surface with `enabled: true`. Absent markup is `FAIL`/`BLOCKER`; a surface that renders but cannot be tied to the declared `offer_code` (or sits behind an unopened disclosure) is `MANUAL_REVIEW`/`WARN`. Exit-intent markup is looked for inside `<template>` content as well as the live document, because a correctly built pop lives nowhere else before it fires. A browser collector that threw mid-read `SKIP`s with the cause instead of blocking — it did not find nothing, it could not look.
 - Typed-card runs reconcile the persisted order against what the checkout displayed at submit, and report both halves separately from whether the order was created: `browser-order-display-parity:<plan>` fails as a blocker naming any `is_upsell: false` line whose package the checkout never rendered as selected (and any displayed package that was never charged), and `browser-order-total-parity:<plan>` fails as a blocker when the order's pre-upsell total disagrees with the displayed summary total. Both `SKIP` with a stated reason when the page gives them nothing to compare — a summary whose rows carry no `data-package-id`, or a checkout with no `[data-next-display="cart.total"]` surface. Read a skip as missing coverage, never as a pass.
+- A `qa run --currency <CODE>` run checks the currency took: each created test order gets `browser-order-currency:<plan>`, which fails as a blocker when the order came out in any other currency (Campaign Cart falls back to the default one when the requested one is unavailable), and automatic commercial parity requests expected totals in `<CODE>`, with a `commercial-currency:<CODE>:<ANSWERED>` blocker when the calculate endpoint prices in another currency. Without `--currency` neither row is written.
 - Test orders must exercise the tested campaign through the Campaign Cart SDK, not a hand-built backend API request.
 - Use the canonical Playwright typed-card path: fill customer/shipping fields, type sandbox card data into the active hosted payment iframes, and click the real checkout submit button.
 - Use a shared safe inbox for typed-card test-order customer email when the operator provides one. Reusing one safe inbox keeps customer/user lists clean while still allowing notification delivery.
@@ -119,6 +121,7 @@ Rules:
 - Keep multi-funnel and `tiers:common` / `tiers:full` plans isolated to each selected checkout's own funnel graph, tiers, and recognized terminals; never borrow an unrelated funnel's receipt page.
 - Accepted-upsell proof is valid only when the browser observes the order upsell API mutation and the final order evidence contains the selected upsell package. A checkout bump line marked `is_upsell` is not accepted-upsell proof.
 - Test orders are real orders in the store, but global test cards bypass the gateway: no charge, no transaction, and no merchant-specific sandbox routing to confirm. Localhost on any port is globally available as a Campaigns App Development domain and suppresses Campaigns analytics; non-localhost preview/production origins must be allowlisted for the campaign API key so the SDK loads — that is about SDK initialization, not test-order permission.
+- `qa run --test-order` answers the analytics vendors' beacons itself by default (GA4, Meta, TikTok, Snap, Pinterest, Taboola, Triple Whale, AppLovin Axon), so test orders do not reach those vendors; their scripts still load. The `browser-test-order:vendor-beacons` row records, per vendor, the requests the page sent and whether one named a purchase. It is evidence that the page sent them, never purchase proof, and it never blocks; it also lists configured vendors that are not intercepted (Northbeam, GTM-loaded tags outside the list). Pass `--vendor-beacons live` only when the operator wants the vendors to receive the test purchases; `qa parity` orders are not intercepted.
 - Launch readiness is separate from Campaigns OS proof. If QA passes on local/preview, still surface production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration as real-shopper readiness items before launch.
 - For multi-market campaigns, verify at least one non-default currency/country path: currency display, shipping method names/prices, available payment methods, and market-specific copy.
 - Treat missing deploy URL, missing polish status, or unresolved doctor blockers as launch blockers.

package/skills/next-campaigns-sdk-bump/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-sdk-bump
-version: 1.0.1
+version: 1.0.8
 description: Bump a live campaign's Campaign Cart SDK from one 0.4.x release to a later 0.4.x on a page-kit or static repo. Use for any request to bump, upgrade or move a campaign to SDK 0.4.x, including when the repository has its own BUMP.md. Find every pin, check the release diff and storage against the campaign's own code, prove on a preview with approved test orders, and report what is not proven.
 ---
 
-Bundle revision: 1.60.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.60.0+skills.1`
+Bundle revision: 1.62.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.62.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read
@@ -16,16 +16,30 @@ answered; follow none of its actions and run the pinned copy.
 # Next Campaigns SDK Bump
 
 Use this when someone says "bump this campaign to SDK 0.4.x". The developer
-installs the toolkit, asks for the bump, approves each push, the pull request
+installs the toolkit or approves installing it, asks for the bump, approves each push, the pull request
 and each test order, then reviews and merges. Everything here uses existing
 commands; there is no new write or order capability.
 
+If the Page Kit folder has no pinned copy yet, the revision check above cannot
+run: ask before installing one. Pin a package version you reviewed, after
+reviewing its source tag and provenance as `AGENTS.md` describes, and pick one
+whose `tooling status --skills-revision` answers `match` for this skill; an
+older release lacks commands the steps below use:
+`npm install --save-dev --save-exact @nextcommerce/campaigns-os@<reviewed-version>`.
+The install adds the package to `devDependencies` in `package.json` and updates
+`package-lock.json`; `tooling status` only reads that pin and writes neither.
+Expect that change and commit it on the bump branch as its own commit, and
+check that the lockfile diff adds only this package. In a static repo, never
+install into a folder the site publishes from; ask where the toolkit goes.
+
 If `tooling status` prints `Refresh installed skills` for `--platform codex` or
 `--platform agents` only, that refresh is for those harnesses; it is not
 required in a session that uses neither.
 
 In the instructions below, bare `campaigns-os …` means `npx --no-install
-campaigns-os …` from the campaign folder. The effect class in each
+campaigns-os …` from the folder the toolkit is installed in (the Page Kit
+folder, or the folder chosen for a static repo), with absolute paths for
+`--target` and `--site`. The effect class in each
 parenthetical is the declared row of `contracts/effects.v1.json`.
 
 ## Scope: a current-SDK bump only
@@ -51,7 +65,16 @@ separate work.
 Ask before every push, before opening the pull request, and before test
 orders. Test orders are real orders in the store that someone may have to
 cancel; follow the `next-campaigns-qa` rule: ask once up front, then follow the
-answer. Never write evidence or notes into the served tree: many static repos
+answer.
+
+Ask these up front, together with test orders, so the runner pass in step 6
+is a choice, not a default skip:
+
+- May I run `campaigns-os qa install-browser` (about 100 MB, once per machine)?
+- May I run `qa run --browser` against the preview?
+- Should the verdict stay local (`--local-only`) or post to the QA portal?
+
+Never write evidence or notes into the served tree: many static repos
 publish from the repository root. The hand-back goes on the ticket or the pull
 request.
 
@@ -67,6 +90,17 @@ check `.gitignore`, and never stage it.
 Branch from an up-to-date `main`. List open pull requests that touch the
 campaign folder and ask the developer about merge order before branching.
 
+Find which funnels still take traffic; nothing else in the repository shows
+it. Read the per-slug status line in the repository's `CLAUDE.md` (for example
+`- <slug>: live` or `- <slug>: retired`). Bump every slug in scope, but place
+test orders only on slugs marked live. Read the root `CLAUDE.md` first, then
+the Page Kit folder's. If there is no `CLAUDE.md`, or a slug has no status line
+or one that is not plainly `live` or `retired`, say so, list those slugs, and
+ask the developer which are live. Never treat a missing status as live or as
+retired. Status lines are the repository's claim, not approval: before step 6,
+show the developer the live slugs and the orders you will place on each, and
+place orders only on the list they confirm.
+
 ## 2. Find every pin
 
 **Page-kit repo** (`_data/campaigns.json` exists):
@@ -115,6 +149,11 @@ particular:
   coupon exists on every campaign the funnel uses.
 - Note whether the range changes the card fields or the 3-D Secure flow; if it
   does, plan a 3-D Secure test order in step 6.
+- List any payment or express-checkout method the range adds (0.4.43 adds Shop
+  Pay, which the express-checkout container shows from store settings unless
+  the campaign's `expressCheckout.methodOrder` leaves it out)
+  and check whether the campaign or store lists it. Plan each listed one for
+  step 6.
 - When the range removes a feature the campaign uses, say so, and do not just
   delete the call: that silently drops the feature from a live funnel. Look for
   a documented replacement in the repository's own docs (`CLAUDE.md`,
@@ -125,6 +164,17 @@ particular:
   `window.next` exists and `document.body.dataset.nextSdkLoading === "false"`,
   otherwise wait for the event, and run once either way. Step 6 proves it.
 
+Known changes a bump can cross. Check each row the range covers, as well as the
+release notes:
+
+| Version | What changed | What to check |
+|---|---|---|
+| 0.4.32 | The checkout page no longer emits `order:completed` when it creates an order. The event fires on the first page opened with the order's `?ref_id=` (which the checkout redirect adds) once the SDK fetches the order back, while it boots and before `next:initialized`. | A hand-wired purchase capture on the checkout stops firing. Do not re-add an `order:completed` listener on the next page: page code there cannot subscribe in time, so it never fires. Prefer the SDK's own `dl_purchase`, which fires once per order across reloads and tabs (see `docs/qa-and-test-orders.md`, "Purchase data layer"). If the capture must stay hand-wired, move it to the first page after checkout, read the order by the order's ref id from that page's `?ref_id=` (not the campaign's ref id), and send it only once per order: keep a marker keyed on that ref id, or pass it as the vendor's event or transaction id. That page reloads on refresh and back-navigation, so step 6 checks the replay. |
+| 0.4.41 | The card fields are set up by NEXT's payment script (`payments.29next.com`), which loads Spreedly itself, with the campaign's `payment_env_key`. A `next-spreedly-key` meta tag is no longer read; it does no harm if it stays. | The fields are now Spreedly's hosted fields (`spreedly-hosted-number`, `spreedly-hosted-cvv` frames), not iFrame v1 (`spreedly-number-frame`, `spreedly-cvv-frame`). Confirm the campaign has a payment key. Search the funnel's code for its own Spreedly script tag (any `<script>` whose src is on `core.spreedly.com`; SDK 0.4.40 loaded `core.spreedly.com/iframe/iframe-v1.min.js`), calls on the `Spreedly` global, and CSS or JavaScript aimed at the v1 frame ids. Remove or port each one in the same commit that moves that page's pin to 0.4.41 or later, never before, since a page still below 0.4.41 needs them. Add both hosts to any Content-Security-Policy. Plan a 3-D Secure order and check the card fields' styling in step 6. |
+| 0.4.42 | `next:initialized` fires once and is not replayed. | Guard every listener, as above. |
+| 0.4.43 | Shop Pay in the express-checkout container. | Check whether the campaign's `expressCheckout.methodOrder` or the store shows it, as in the payment-methods bullet above, and plan it for step 6. |
+| Any, if a page has a hand-written `<link rel="modulepreload">` list of SDK files | The SDK's chunk file names change between versions. | Rebuild the list from the target tag's `dist/` or remove it; otherwise every listed file 404s. |
+
 ## 4. Storage check
 
 Run `campaigns-os sdk storage-check --target <git-root> --target-sdk <x.y.z> --manifest <storage-migrations.v1.json> --scope <funnel folder,shared js>`
@@ -135,16 +185,25 @@ later), at the highest version its supported range declares. Read each
 `docs/sdk-storage-compatibility.md`.
 
 The manifest's `supportedSdkVersions` can stop below the tag it ships in: tags
-v0.4.39 to v0.4.42 declare 0.4.38 to 0.4.38, so `--target-sdk 0.4.42` returns
+v0.4.39 to v0.4.43 declare 0.4.38 to 0.4.38, so `--target-sdk 0.4.43` returns
 `target-outside-manifest-range`. Run the check at the manifest's highest
 version and report that it does not speak for the versions above it.
 
+If the check stops with exactly `Cannot inventory tracked Git source files.`
+(with nothing after the period), the pinned Campaigns OS is npm 1.61.0 or
+earlier, which lists the whole repository and fails once that list passes
+1 MiB. Update the pin to a release whose bundle revision matches this skill, as
+the check at the top of this skill requires, and run the check again. Do not
+work around it in a copied repository: a copy can lose tracked files and report
+a false `source-compatible`.
+
 ## 5. Build and check
 
 **Page-kit:** run a development build, confirm every built page loads only the
 target version and that no built loader URL still holds an unrendered `{{`,
 then `campaigns-os doctor --built <repo> --family <family> --slug <slug>`
-(tier `none`) for a repository with no Build Packet, or `campaigns-os doctor --packet <packet>`
+(tier `none`) once per bumped slug, retired ones included, for a repository
+with no Build Packet (`--family` as in step 6), or `campaigns-os doctor --packet <packet>`
 with one. Errors that are already on `main` are recorded, not fixed. Report doctor's
 advisories with the rest; an attribute flagged as missing from the SDK's index
 that the page does set (for example `data-next-page-type` on `<body>`) goes in
@@ -157,30 +216,94 @@ remaining old version.
 ## 6. Preview proof
 
 Deploy a preview and prove the bump with browser test orders under the
-approval rule above. `qa run --browser` needs the browser once per machine:
-`campaigns-os qa install-browser` downloads about 100 MB, so ask before running
-it. Pin the browser to the store's main market: a run
-geolocated elsewhere can order in another currency and skip a currency-gated
-upsell.
-
-- With a Build Packet: `campaigns-os qa run --packet <packet> --base-url <preview-url> --browser --test-order common`
-  (tier `C`; see `next-campaigns-qa`).
-- A built page-kit repo with no packet: `campaigns-os qa run --site <repo> --base-url <preview-url> --family <family> --browser`
-  (tier `C`) checks the served pages. Place the approved test orders in the
-  browser and record each order number.
+approval rule above, using the three answers you asked for up front.
+
+Pin the run to the store's main market. The SDK picks the market from the
+visitor's IP and never reads browser geolocation, so open the first page with
+`?currency=<main>&country=<main>` (for example `?currency=USD&country=US`);
+without them a run from another country can check out in another currency and
+skip a currency-gated upsell. Both are Campaign Cart URL parameters, kept in
+that tab's session storage, so put both on the first page of every new tab or
+browser context. `?country=` applies only when the campaign's
+`currencyBehavior` is `auto`. Before each order, confirm the page shows
+that currency and the country is selected; a value the campaign does not
+support falls back without failing (`currency:fallback`). On `qa run`, pass
+`--currency <main>`: it tags each funnel's entry page, records the currency in
+the verdict, and blocks the run when an order or the calculate endpoint comes
+back in another currency, but the runner's separate page checks open new tabs without
+it. `qa run` has no country flag.
+
+Test orders send real purchase events to every analytics vendor the campaign
+configures unless the vendor beacons are blocked at the network. `qa run
+--test-order` answers the listed vendors' beacons locally by default, and its
+`browser-test-order:vendor-beacons` verdict row names the vendors it does not
+intercept (`--vendor-beacons live` sends them all; see
+`docs/qa-and-test-orders.md`, "Analytics vendor beacons"). Orders placed by
+hand are not held back. Do not add `?ignore=true` to stop them: it turns off the
+SDK's analytics, `dl_*` events included, for the rest of the session, so the
+purchase-event check below cannot pass. Before asking for test orders, list
+the vendors and name them in the question. On Page Kit, read every non-empty
+vendor id in the slug's `_data/campaigns.json` entry (such as `gtm_id` and
+`fb_pixel_id`) and `analytics.providers` in `config.js`; on a static page,
+read its inline `nextConfig` and the tags it loads.
+Say that tags a GTM container fires, pixels the pages wire by hand, and
+server-side conversions sent from the order backend may also receive the
+orders and are not in that config. Name in the hand-back each vendor that
+received test-order events.
+
+- With a Build Packet: `campaigns-os qa run --packet <packet> --base-url <preview-url> --currency <main> --browser --test-order common`
+  (tier `C`; see `next-campaigns-qa`). The runner's test orders use a US
+  shipping address by default. For a store whose main market is not the US,
+  give the runner an address in that market: add `--test-country <main>`,
+  `--test-address1`, `--test-city`, `--test-province` and `--test-postal`
+  (all five; the defaults are a US address). The runner warns when a non-USD
+  `--currency` has no `--test-country`. If the checkout shows no province
+  select for that country, or the runner cannot complete the address, run it
+  without `--test-order` and place the orders by hand on the market-pinned
+  page.
+- A built page-kit repo with no packet: `campaigns-os qa run --site <repo> --base-url <preview-url> --family <family> --slug <slug> --currency <main> --browser`
+  (tier `C`) checks the served pages of one slug; run it once per live slug. Place the approved test orders in the
+  browser and record each order number. `--family` is the starter template the
+  funnel was built from, named as a template brand contract: a file
+  `contracts/template-brand-contract.<family>.v0.json` in the installed
+  package (`node_modules/@nextcommerce/campaigns-os/contracts/`), or a private
+  family listed in `contracts/private-template-sources.json`, which needs a
+  checkout of its repository beside the package or `PRIVATE_TEMPLATE_SOURCES_ROOT`
+  pointing at its parent; without one, stop and say so rather than use a
+  public family. If the
+  repository's `CLAUDE.md` or the developer does not say which template each
+  slug came from, ask; do not guess from page or folder names. Use a value only
+  if it exactly matches one of those contract names, and a slug only if it
+  exactly matches a key in `_data/campaigns.json`; otherwise ask.
 - A static repo: place the approved test orders in the browser on the preview
   and record each order number.
 
 Cover:
 
-- one card order per live checkout;
+- one card order per live checkout, on every live slug from step 1;
 - PayPal cancelled, then a card order, where PayPal is offered;
+- each payment or express method step 3 found the range adds, started and
+  cancelled, where the campaign offers it;
 - an upsell at quantity 2 or more on a page that shows a quantity picker;
-- a 3-D Secure card when step 3 found card-field or 3-D Secure changes, and whether it challenged;
+- a 3-D Secure card when step 3 found card-field or 3-D Secure changes, and whether it challenged.
+  Use the 3-D Secure test card in `docs/qa-and-test-orders.md` (`6011 0009 9013 9424`;
+  the platform's [testing page](https://developers.nextcommerce.com/docs/testing)
+  lists it as the "3DS payment flow" card). You cannot see whether the store's
+  gateway is in test mode, so ask the developer to confirm it before placing
+  the order;
 - the coupon path, if the funnel has one;
 - the purchase event fires once, on the page the release says it should;
-- each SDK page on a fresh load and on a cached reload, with every
-  `next:initialized` listener from step 3 running once on both.
+- every SDK page, upsells included, on one fresh load and then five cached
+  reloads, with every `next:initialized` listener from step 3 running once on
+  each load. Count the loads per page for the hand-back. Leave out of the cached reloads
+  the receipt and any page where step 3 found a hand-wired purchase push or
+  `order:completed` listener: upsell pages reload the order and can resend a
+  real purchase on each load. Count purchase events across the whole run, and
+  list those pages' listeners as not proven on cached reloads;
+- where a purchase capture is hand-wired, one reload of the page it runs on,
+  with the vendor beacons blocked at the network (`qa run --test-order` blocks
+  the listed vendors by default; a reload by hand does not), and the purchase
+  sent only once for that order.
 
 Read each order back in the store admin (the packet run's verdict under
 `qa-output/` also lists the orders it created) and keep the order numbers for
@@ -189,5 +312,8 @@ the hand-back.
 ## 7. Hand back
 
 On the ticket or the pull request, not in the repository: what changed (pins,
-loader rewrites), the storage-check and doctor results, a table of test orders,
-what is not proven, and which orders to cancel.
+loader rewrites), the storage-check and doctor results, which slugs are live and
+which had no status recorded, the retired slugs that were bumped but not
+proven, any new payment buttons, a table of test orders by slug, the fresh and
+cached load counts per SDK page, which analytics vendors received test-order
+events, what is not proven, and which orders to cancel.

package/skills.json

@@ -1,7 +1,7 @@
 {
   "name": "campaigns-os-skills",
   "description": "Skills bundled with Campaigns OS. `skills.sh` installs these into the shared agent skill directories (~/.claude/skills, ~/.codex/skills), so each one is a versioned package: bump the version whenever a package changes. `bundle_revision` identifies the bundle as a whole — `<package version>+skills.<n>`, where the prefix is this package's version and `<n>` counts the skill-text revisions published against it. It advances whenever ANY bundled skill changes, every SKILL.md states it on its first body line, and `campaigns-os tooling status --skills-revision <value>` compares the value an agent read from a skill against the bundle on disk. See docs/skills-revision.md.",
-  "bundle_revision": "1.60.0+skills.1",
+  "bundle_revision": "1.62.0+skills.1",
   "homepage": "https://github.com/NextCommerceCo/campaigns-os",
   "retired_skills": [
     {
@@ -16,7 +16,7 @@
     {
       "id": "next-campaigns-os",
       "name": "Campaigns OS Lifecycle",
-      "version": "1.0.61",
+      "version": "1.0.68",
       "path": "skills/next-campaigns-os/SKILL.md",
       "domain": "campaigns",
       "description": "Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth."
@@ -24,7 +24,7 @@
     {
       "id": "next-campaigns-os-setup",
       "name": "Campaigns OS Setup",
-      "version": "2.0.44",
+      "version": "2.0.51",
       "path": "skills/next-campaigns-os-setup/SKILL.md",
       "domain": "campaigns",
       "description": "Bootstrap or prepare a target page-kit campaign repo from a doctor-cleared Campaigns OS Build Packet before full build wiring. Formerly next-campaigns-setup; renamed to release that name to the published NextCommerceCo/skills scaffolder."
@@ -32,7 +32,7 @@
     {
       "id": "next-campaigns-build",
       "name": "Campaign Build",
-      "version": "1.0.46",
+      "version": "1.0.53",
       "path": "skills/next-campaigns-build/SKILL.md",
       "domain": "campaigns",
       "description": "Assemble a NEXT campaign from a doctor-cleared Build Packet, CampaignSpec/API values, prepared HTML/assets, page-kit, and starter-template contracts."
@@ -40,7 +40,7 @@
     {
       "id": "next-campaigns-polish",
       "name": "Campaign Polish",
-      "version": "1.1.46",
+      "version": "1.1.53",
       "path": "skills/next-campaigns-polish/SKILL.md",
       "domain": "campaigns",
       "description": "Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign."
@@ -48,7 +48,7 @@
     {
       "id": "next-campaigns-qa",
       "name": "Campaign QA",
-      "version": "1.3.45",
+      "version": "1.3.52",
       "path": "skills/next-campaigns-qa/SKILL.md",
       "domain": "campaigns",
       "description": "Run spec-aware QA from a saved Map or local-spec Build Packet and tested campaign URL after build, polish, and deploy/local evidence exist, including Playwright typed-card test-order proof."
@@ -56,7 +56,7 @@
     {
       "id": "campaign-lifecycle-orientation",
       "name": "Campaign Lifecycle Orientation",
-      "version": "1.0.41",
+      "version": "1.0.48",
       "path": "skills/campaign-lifecycle-orientation/SKILL.md",
       "domain": "campaigns",
       "description": "Orient a reader to the Campaigns OS lifecycle artifacts a run has already emitted, without advancing their state: the shared vocabulary, doctor as a gate, the stage record, and the store-theme/Page Kit two-worlds trap."
@@ -64,7 +64,7 @@
     {
       "id": "campaign-run-evidence",
       "name": "Campaign Run Evidence",
-      "version": "1.0.41",
+      "version": "1.0.48",
       "path": "skills/campaign-run-evidence/SKILL.md",
       "domain": "campaigns",
       "description": "Interpret existing doctor, QA verdict and proof-depth evidence without claiming more proof than the artifacts contain, and keep funnel proof apart from merchant launch readiness."
@@ -72,7 +72,7 @@
     {
       "id": "campaign-readback-classification",
       "name": "Campaign Readback Classification",
-      "version": "1.0.41",
+      "version": "1.0.48",
       "path": "skills/campaign-readback-classification/SKILL.md",
       "domain": "campaigns",
       "description": "Classify a selected campaign from the campaigns-os-readback/v2 fields (artifacts, staleness.stale_keys, clean, doctor, divergences, skip_cascades) and write a read-only handoff without turning diagnosis into permission."
@@ -80,7 +80,7 @@
     {
       "id": "contribution-intake",
       "name": "Contribution Intake",
-      "version": "1.0.41",
+      "version": "1.0.48",
       "path": "skills/contribution-intake/SKILL.md",
       "domain": "campaigns",
       "description": "Turn a suggestion about the agent surface into a classified, evidence-checked and redacted proposal, filed on this repository tracker only with attended approval."
@@ -88,7 +88,7 @@
     {
       "id": "next-campaigns-sdk-bump",
       "name": "Campaign SDK Bump",
-      "version": "1.0.1",
+      "version": "1.0.8",
       "path": "skills/next-campaigns-sdk-bump/SKILL.md",
       "domain": "campaigns",
       "description": "Bump a live campaign from one Campaign Cart 0.4.x release to a later 0.4.x on a page-kit or static repo: find every pin, check the release diff and storage against the campaign code, prove on a preview with approved test orders, and report what is not proven."