@nextcommerce/campaigns-os 1.50.0 → 1.52.0

package/CHANGELOG.md

@@ -2,6 +2,432 @@
 
 Notable supported-surface changes are recorded here.
 
+## [1.52.0+agent.1] - 2026-10-05
+
+### Added
+
+- Doctor now reports built-page smoke warnings: missing in-page anchor targets, missing favicon and Open Graph tags, unresolved `og:image`, the Tailwind CDN script in production builds, `cdn.29next.store` asset references, and loopback URLs.
+
+## [1.52.0] - 2026-10-05
+
+### Added
+
+- QA now checks that configured store policy links are rendered and reachable, recording link presence and availability separately. QA now sends bounded header-only requests to the configured policy URLs; the effects contract declares them.
+
+### Changed
+
+- The effects contract now states that `qa run --browser` sends the header-only GET requests to the configured store policy URLs, rather than declaring them ahead of the check that sends them.
+
+## [1.51.0+agent.4] - 2026-10-05
+
+### Added
+
+- QA now checks at runtime that declared content parameters hide their content, comparing fresh contexts with and without `?<name>=n`.
+
+## [1.51.0+agent.3] - 2026-10-05
+
+### Added
+
+- QA browser test orders now report URL preservation and order attribution for synthetic tracking parameters as separate results. QA order evidence no longer stores query strings in `checkout_url`, `final_url` or request URLs.
+
+## [1.51.0+agent.2] - 2026-10-05
+
+### Added
+
+- Polish capture now records image geometry and redirect chains, and reports origin and weight warnings for video and large images served from the page's own origin, plus oversized images.
+
+### Changed
+
+- `polish capture` now records media weight beside page load evidence in the Assembly Report, so `next` reads the image weight and oversize results of a fresh capture.
+
+## [1.51.0+agent.1] - 2026-10-04
+
+### Added
+
+- Doctor now warns on SDK cart placeholders printed in live built HTML (`built_output.cart_placeholders`), ported from the public starter-template lint.
+
+## [1.51.0] - 2026-10-04
+
+### Added
+
+- Adds `checkpoint accept`, which records an operator's accept of a measured warning next to the unchanged measurement, and a QC handoff section in `next` that lists open, review, lapsed, unexercised and excluded results. Accepts never change readiness, and `checkpoint waive` still refuses gates that are not blocked.
+- The effects contract now declares bounded header-only GET requests to the store policy URLs a CampaignSpec configures, for `qa run --browser`, ahead of the check that sends them; QA does not send them yet.
+
+## [1.50.0+agent.20] - 2026-10-04
+
+### Changed
+
+- `scripts/refresh-certified-family-fixtures.mjs` now sets `og_image` to
+  `https://example.com/og-image.png` on each certified family's
+  `_data/campaigns.json` entry before it renders, and records that in the
+  fixture manifest as `render_inputs`. The starters leave `og:image` out until
+  a campaign sets one, so without it every certified page would report a
+  missing `og:image` to the coming built-output smoke checks. The value is on a
+  reserved domain, so it is plainly synthetic, and doctor `--built` neither
+  maps nor fetches it. The committed fixture tree is unchanged until the next
+  regeneration.
+
+## [1.50.0+agent.19] - 2026-10-03
+
+### Fixed
+
+- A campaign-identity finding (`funnel_drift`, `funnel_missing`,
+  `api_key_drift`, `attribution_drift`) that names a built file no active
+  CampaignSpec page builds to now says so, and lists the file on the finding as
+  `stray_files`. The message says to remove the source file if there is one,
+  delete the built file, and rebuild and record the build again. Before, a
+  design `index.html` copied under `assets/` built as its own page and blocked
+  as funnel drift, with the message telling the agent to retag a page it never
+  meant to ship. The gate still blocks, because the file is still served.
+
+## [1.50.0+agent.18] - 2026-10-03
+
+### Fixed
+
+- Commercial parity no longer warns `price-claim-mismatch` on a page that shows
+  a voucher the normalized plan cannot price. An upsell priced by a live
+  voucher showed the voucher price, and QA compared it with the list-price
+  total. Those price claims now count as unresolved, as the page's voucher
+  claims already did, so coverage reads incomplete instead.
+- `browser-order-bump-state` reads a `✓` glyph marker as checked only when its
+  text is painted. A tick that stays in the marker and is hidden with
+  `color: transparent` read checked before, so a declined bump failed as
+  misaligned.
+
+## [1.50.0+agent.17] - 2026-10-03
+
+### Fixed
+
+- Three CampaignSpec validation messages that doctor and `start` print now say
+  which field to change:
+  - The missing-`payment_env_key` warning keeps "No campaign loaded — campaign
+    key required for spec export." and adds that `campaign.payment_env_key` is
+    empty, where its value comes from, and that a Campaigns API key in the spec
+    does not fill it. Before, it printed next to doctor's "Campaigns API key
+    available via the packet-local CampaignSpec" line and read as if the key
+    were missing.
+  - The missing SDK version error keeps "SDK version is required for spec
+    export." and names `global_config.sdk_version` and the form it takes.
+  - The missing `design_source.file_url` warning, for a page whose
+    `design_source.type` is not `figma` or `ai-generated`, and doctor's
+    matching no-source-mapping error, say that hand-written or template HTML
+    leaves `design_source` off the page. Before, a plain HTML page with a
+    `design_source` block was told only to add a design-tool URL.
+
+## [1.50.0+agent.16] - 2026-10-03
+
+### Fixed
+
+- `prepare-build` (and `start`) no longer write an Assembly Report that fails
+  its own schema. When the brand-theme write failed, each error was copied
+  onto `theme.warnings[]` as `{ code, message, detail: error.detail || null }`.
+  The schema's `themeIssue.detail` is an object, so an error with no detail
+  (`theme.generate.not_ready`, `theme.generate.empty`) left `detail: null`.
+  `record setup` and `record build` then refused the report with
+  "Assembly Report theme.warnings.0.detail must be object". `detail` is now
+  written only when the error carries an object. The schema is unchanged.
+
+## [1.50.0+agent.15] - 2026-10-03
+
+### Fixed
+
+- `record setup|build|polish|theme|deploy` accept `--deviation-reason`, as
+  every other command does. The deviation notice tells an agent that departs
+  from `next` to "Declare intent with --deviation-reason". `record` checks its
+  flags against a strict allowlist, which held only its own flags and the global
+  `--run-id` and `--lifecycle-journal`, so it refused the flag as unknown on
+  every stage. It is now a global flag there too. A bare `--deviation-reason`
+  with no value is refused as before.
+
+## [1.50.0+agent.14] - 2026-10-03
+
+### Fixed
+
+- QA's placeholder text-residue gate (`template-residue:<page>:placeholder-text`,
+  and doctor's built-output warning) now also matches the starter templates'
+  own icon-grid placeholders, `Benefit one`, `Benefit two`, `Benefit three` and
+  `Benefit four`. The olympus checkouts ship them, and a campaign that kept
+  them passed QA with no failures, because the shared-commerce term list held
+  only `Lorem`, `lorem ipsum`, `Placeholder`, `TODO` and `Product Name`.
+  - The terms live in `contracts/template-brand-contract.shared-commerce.v0.json`,
+    so every family inherits them.
+  - Matching is word-bounded, so "Benefit once" does not fire.
+  - Doctor's next-step hint and `docs/template-family-contracts.md` list them.
+
+## [1.50.0+agent.13] - 2026-10-03
+
+### Fixed
+
+- The source preparation check `source_html.prep.document_wrapper` reads a
+  page's converted page-kit file once it exists at `page_kit.output_path`, not
+  the design it was converted from. Wrappers are stripped during conversion,
+  and the converted page is what page-kit builds. The check only ever read the
+  mapped design, so a correctly stripped build still failed. To clear it,
+  agents copied built pages over the design source (breaking the Design Source
+  Package hashes) or recorded `preserve_document_wrappers` for pages they had
+  stripped. A converted page that still carries wrappers is reported under its
+  own path. Before conversion the design is checked as before. The frontmatter
+  and source-link checks are unchanged. `docs/source-adapters.md` says so.
+
+## [1.50.0+agent.12] - 2026-10-03
+
+### Fixed
+
+- `record deploy` follows `next` past a polish carried forward on the local
+  preview. On a `local-serve` packet with a loopback preview, `next`'s stage
+  picker skips a polish that was never recorded for this build (the
+  local-preview policy carries it forward as a warning), so after
+  `record build` it answers deploy. `record deploy` checked every earlier
+  stage strictly and refused with "stages.polish.status is "required", so next
+  answers polish", which contradicted `next`. Sessions hand-wrote a polish skip
+  record to get past it. Both now read the same rule, from doctor's
+  `polish_gate`. Polish stays owed on the report and QA still reports it.
+  `record polish` and the waiver commands keep the strict gates.
+  `docs/build-packet.md` names the exception.
+
+## [1.50.0+agent.11] - 2026-10-03
+
+### Added
+
+- Doctor warns `spec.material_stale` when a local-spec campaign's CampaignSpec
+  no longer has the material hash prepare-build bound on the Assembly Report
+  (`identity.spec_material_hash`). `next` prints the warning with the rest of
+  doctor's. QA already refused such a run ("Re-run prepare-build after a
+  material revision"). Until now it was the only command that checked, so a
+  spec edited after `start` was accepted by doctor, `next` and every `record`
+  command, and the problem surfaced only after the build, polish and deploy
+  stages had been recorded against the old spec. The warning names both hashes
+  and says to re-run prepare-build from the edited spec.
+  `docs/build-packet.md` says so.
+
+## [1.50.0+agent.10] - 2026-10-03
+
+### Fixed
+
+- A checkout row marked `is_order_bump: true` is now read as an order bump.
+  The CampaignSpec schema and the authoring guide mark a checkout add-on with
+  that flag, and the certified fixtures use it alone, but the one bump
+  predicate the toolkit shares read only `is_upsell`. Such a row was treated
+  as a main package:
+  - the QA tier planner made it a selector tier of its own;
+  - `next` named no bump-cart QA command (`qa_run_bump`);
+  - commercial-journey priced the bump into the representative checkout and
+    planned no with/without-bump scenarios.
+
+  Either flag now marks a bump, and a row carrying `is_upsell: true` behaves as
+  before. On the certified fixtures, the five checkouts that declare a bump now
+  plan only their real tiers, and their bumps get the bump-cart command.
+- Messages that named a bump `(is_upsell)` now say
+  `(is_order_bump or is_upsell)`: the tier planner's warning and refusal, the
+  `next` bump-command description, the `qa run --help` text and the QA
+  test-order notes. `docs/qa-and-test-orders.md` says the same.
+
+## [1.50.0+agent.9] - 2026-10-03
+
+### Added
+
+- `record build --build-environment <development|production>` records the
+  page-kit environment the built output was rendered in, on
+  `stages.assembly.evidence.build_environment`. A later `record build` without
+  the flag keeps the recorded value. Before this, local proof mode
+  (`deploy.target: local-serve`) asked the agent to record the field, but no
+  command wrote it, so it was hand-edited into the Assembly Report.
+  - Under local-serve, `next` now names
+    `record build --packet <packet> --build-environment development` in the
+    build action and the build prompt.
+  - Doctor's `local_proof.build_environment` warning, the parity messages and
+    the local-proof rebuild hint name the same command.
+  - `docs/build-packet.md` and `docs/qa-and-test-orders.md` describe it.
+
+### Fixed
+
+- A `record` refused for a value outside a schema enum now lists the values the
+  schema allows and the value it got. For example,
+  `adapter_decisions.wrapper_policy must be equal to one of the allowed values:
+  "strip_document_wrappers", "preserve_document_wrappers", "not_required",
+  "unknown" (got "strip")`; before, it stopped at "allowed values".
+- Doctor's adapter-decision warning for an unknown value lists the allowed
+  values too.
+
+## [1.50.0+agent.8] - 2026-10-03
+
+### Changed
+
+- The vendored commerce-surface catalog is re-synced to
+  campaign-cart-starter-templates `02ffc61`, from `37a8d94`. That brings in
+  three starter changes:
+  - the single-offer upsell keeps a hidden in-offer skip, so its closing-card
+    decline works in every family (#205);
+  - `payment-methods.html` takes `method_order` and `default_method` (#202);
+  - fresh SDK 0.4.40 verification evidence (#203).
+
+  The upstream order-bump notes were consolidated, and the vendored copy
+  follows them.
+- `fixtures/certified-families/` is regenerated at the new pin. Every
+  `upsell-single` fixture now carries the in-offer skip, so QA's static
+  `route-link:<page>:decline` check, which fails a proxy decline with no
+  target, passes on all eight families instead of failing on each.
+- The shared commerce payment-chrome `asset_pin` moves to the new pin. The
+  asset bytes are unchanged.
+
+## [1.50.0+agent.7] - 2026-10-03
+
+### Fixed
+
+- `sdk storage-check` resolves Page Kit's `campaign_asset` script srcs. A
+  page under `src/<slug>/` that loads `{{ 'js/checkout.js' | campaign_asset }}`
+  is read as `src/<slug>/assets/js/checkout.js`, where Page Kit serves it from,
+  and a page's frontmatter `scripts:` entries resolve the same way, since a
+  layout's `{% for script in scripts %}` loop loads them through that filter.
+  Until now every such tag read as a relative path that was never in scope and
+  reported `shared-script-outside-scope`, so every Page Kit campaign came back
+  `unknown` even when nothing was incompatible (#582). A resolved script left
+  out of `--scope`, or excluded, is still reported, under its real path; a
+  `campaign_asset` value the scan cannot resolve stays unknown.
+  `docs/sdk-storage-compatibility.md` says so.
+
+## [1.50.0+agent.6] - 2026-10-03
+
+### Fixed
+
+- QA no longer passes an upsell decline or accept that does nothing. Some
+  upsell pages show a `data-upsell-proxy="skip"` (or `"add"`) button that
+  forwards its click to the SDK's `data-next-upsell-action` inside the offer.
+  When the offer has no such action, the static `route-link:<page>:decline`
+  (or `:accept`) check used to pass on the decline URL in the page's meta tag,
+  and only browser QA, after placing the order, found the control missing. The
+  static check now fails as a blocker and says the proxy has nothing to
+  forward to. The starter templates' single-offer upsell shipped this way in
+  every family until the templates kept a hidden in-offer skip.
+- Browser QA declines (and accepts) through the control a shopper sees. When
+  the page's `data-next-upsell-action` is hidden and a visible
+  `data-upsell-proxy` button forwards to it, QA clicks the proxy instead of
+  failing with `Element is not visible` on the hidden action. A proxy with no
+  in-offer action is still reported as a missing upsell control.
+
+## [1.50.0+agent.5] - 2026-10-03
+
+### Changed
+
+- The agent context the toolkit installs (`agents/claude/CLAUDE.md`,
+  `agents/codex/AGENTS.md`, `agents/cursor/campaigns-os.mdc`,
+  `agents/copilot/copilot-instructions.md`) and the `next-campaigns-os` and
+  `next-campaigns-qa` skills no longer say test orders need no permission or
+  approval, or are safe to fire any time. They say `qa run` has no permission
+  flag and coverage is its only control, and that test orders still land in
+  the store as real orders (global test cards: no charge, no transaction) that
+  someone may have to cancel. Unless the operator has already said test orders
+  are fine for the campaign, the agent asks once, up front in its first turn
+  with its other setup questions, so the answer covers the whole build and QA
+  and neither stops for it later. The skill's session-intake reference says
+  the same in its test-order proof policy.
+- The QA skill follows an answer the operator already gave and does not pause
+  QA to ask again. When nobody asked earlier, it asks once before the first
+  test order.
+- `qa run` is unchanged: it has no permission flag and none is added. Its
+  help text and the docs are unchanged.
+- Bundled skills carry revision `1.50.0+skills.2`, with each skill version
+  advanced one patch.
+
+## [1.50.0+agent.4] - 2026-10-02
+
+### Changed
+
+- At the QA stage, `next` lists a second QA command when the CampaignSpec's
+  checkout declares an order bump (`is_upsell: true` rows). `qa_run_bump`,
+  beside `qa_run`, is the same `qa run --browser --test-order common` with
+  `--cart <base>:1,<bump>:1`, so its test orders carry the add-on and prove
+  its charge. Until now `next` named only the default run. Its test orders
+  never toggle a bump, because the tier planner skips bump rows by design and
+  bump coverage comes from `--cart`, so a verdict could read ready with the
+  add-on never ordered. The base is the first selector tier the checkout
+  declares; a checkout that declares no tier gets the bump alone, and several
+  declared bumps share one cart. The QA stage prompt and the human `next`
+  output name the same command, and `docs/qa-and-test-orders.md` says so
+  under its launch-grade proof list. The bump is read from the one checkout
+  QA's test orders run on, the first enabled checkout across funnels, so a
+  bump declared only on a later funnel's checkout gets no command. When the
+  CampaignSpec does not parse, `next` warns
+  (`next.order_bump_spec_unreadable`) instead of silently naming no bump
+  command.
+- A progress snapshot records `qa_run_bump` as `qa_run`. The snapshot's
+  action vocabulary is unchanged, and a ready QA continuation does not read
+  as blocked.
+- The QA tier planner reads its bump and tier helpers from the
+  commercial-journey module, where `next` reads them too. Tier planning is
+  unchanged.
+
+## [1.50.0+agent.3] - 2026-10-02
+
+### Changed
+
+- The Campaign Build Brief question `promo_urgency_copy` now asks only about
+  the starter template's own promo placeholders: demo countdown timers, promo
+  banners, placeholder voucher codes and exit-pop offers. It asks whether to
+  fill them from the campaign's promo codes and offers or remove them. It no
+  longer asks which promo, savings and urgency language is approved, which
+  read as a request to approve the source design's own copy; that copy is the
+  merchant's content and is built as designed.
+- The question is asked only when the CampaignSpec maps a surface that fills
+  those placeholders: a `funnels[].promo_codes` roster, or a checkout page's
+  enabled `exit_intent` or `promo_code_input`. It used to be asked for any CampaignSpec
+  key naming an offer, discount, timer or urgency, so the offer catalog,
+  before-discount prices and design slot names all raised it. Without such a
+  surface the guided draft sets `promo_urgency.header_claim_source` and
+  `promo_urgency.timer_label` to `"none"` (the template's promo placeholders
+  are removed). The draft used to set `timer_label` to "Limited-time offer".
+- Doctor's `build_brief.guided_questions` warning names the brief fields that
+  close each open question and says how to record the answers: copy the
+  normalized draft to `campaign-build-brief.json` in the target repo, set the
+  fields, and re-run `start` or `prepare-build`. It also says the re-run needs
+  `--force`, which clears stage evidence, once a stage has recorded evidence.
+  `build_brief.questions_unanswered` names the fields too. An answer given
+  only in conversation was never recorded, so a later session asked again.
+- `next`'s QA prompt compares the template's own promo placeholders and trust
+  badges with the brief and says not to flag the source design's own proof,
+  urgency or guarantee elements. It used to ask for promo/urgency copy and
+  trust/guarantee claims to be compared. The build prompt names the template's
+  promo placeholders where it named promo/urgency language.
+- `docs/campaign-build-brief.md` rewords question 5 and adds "Answering The
+  Questions", with the fields that close each question.
+
+## [1.50.0+agent.2] - 2026-10-02
+
+### Changed
+
+- `docs/build-packet.md` says how to read a campaign's package, offer and
+  shipping refs for a local CampaignSpec. Its new "Reading package, offer and
+  shipping refs" section, under "Local-spec entry", gives the read doctor and
+  QA already make against the live campaign: one GET of NEXT's proxy,
+  `https://campaign-map.nextcommerce.com/api/campaign`, with the public
+  Campaigns API key in the `X-Campaign-Key` header. It shows a `node` and a
+  `curl` form, describes the envelope, and maps the campaign retrieve body's
+  `id`, `packages[]`, `offers[]` and `shipping_methods[]` to
+  `campaign.ref_id`, `funnels[].pages[].packages[]`, root `offers[]` and root
+  `shipping_methods[]`. It also notes that the proxy refuses some default user
+  agents, Python `urllib`'s and Perl `libwww-perl`'s among them. No command
+  writes these refs, as before.
+- With no saved gateway login, `tooling status` no longer only says to run
+  `login`. Its warning says login is optional and only lets `spec derive
+  --from-store` fill the Store Profile fields, and a second warning says
+  package, offer and shipping refs never come from the gateway login and
+  where the public-key read is documented. Both lines are under `warnings`,
+  and the exit code is unchanged.
+
+## [1.50.0+agent.1] - 2026-10-02
+
+### Changed
+
+- No command behaves differently. A comment in the QA browser module that
+  explains how repeated package declarations become purchase multipliers
+  named an internal store as its example; it now gives a neutral one (a 1x
+  and a 2x package). Two QA test files swap the same name in a fixture SKU
+  and a hosted-checkout URL for neutral placeholders, and the same fixture's
+  product title becomes "Demo Bag". Comment and test fixtures only; every
+  message and every exit code is unchanged.
+- The private-string check adds that store name to its hashed list, so it
+  cannot return.
+
 ## [1.50.0] - 2026-10-02
 
 ### Changed

package/agents/claude/CLAUDE.md

@@ -28,12 +28,12 @@ Core rules:
 - Do not copy Olympus-style `shipping_methods` frontmatter into `shop-three-step`; it uses dynamic shipping through `window.next.getShippingMethods()`.
 - Run build/lint checks and record evidence in the assembly report, then hand off to polish. Before Polish becomes terminal or hands off to deploy/QA, install the package-owned Playwright browser with `npm run qa:install-browser`, serve the current build, and run `npx --no-install campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>`.
 - After that checkpoint clears, QA uses the Campaigns OS Node/npm runner: run `npx --no-install campaigns-os qa resolve --packet campaign-runtime.build.json`, then run `npx --no-install campaigns-os qa run --packet campaign-runtime.build.json --base-url <url> --browser --test-order common`.
-- Typed-card test-order proof uses `npx --no-install campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the deployed checkout and rendered upsell controls. `common` runs every actual terminal path when they fit under the flood cap (`--max-test-orders`, 6 by default); above the cap it runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path, then adds one decline path per offer or downsell page not yet declined, up to the cap, and names any page left out. A page counts as covered only when an order clicks its decline; the `browser-test-order:upsell-action-coverage` verdict row warns naming each page whose decline no order clicked. `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Coverage is the only control — there is no permission/approval step.
+- Typed-card test-order proof uses `npx --no-install campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the deployed checkout and rendered upsell controls. `common` runs every actual terminal path when they fit under the flood cap (`--max-test-orders`, 6 by default); above the cap it runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path, then adds one decline path per offer or downsell page not yet declined, up to the cap, and names any page left out. A page counts as covered only when an order clicks its decline; the `browser-test-order:upsell-action-coverage` verdict row warns naming each page whose decline no order clicked. `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. `qa run` has no permission flag: coverage is its only control.
 - Analytics correctness is two-phase: the campaign-root visit inventories declared providers/tags only, and the same canonical typed-card run proves Purchase only from the topology-recognized final receipt document after `--analytics-settle`. Missing/unrecognized receipts are manual-review warnings; recognized receipt no-signal and capture/settle errors block. Only the genuine recognized-receipt/no-signal failure is waivable; capture/settle errors are not. Checkout/upsell signals remain whole-journey parity evidence and cannot satisfy a silent receipt.
 - Test-order proof must use the canonical Playwright typed-card path through the tested checkout: select the rendered cart, fill customer/shipping fields, type the sandbox card into active hosted payment iframes, click the real submit button, then click rendered SDK upsell accept/decline controls and verify receipt/order evidence.
 - Do not use `next.getCartData().cartLines` as cart-populated proof; use typed-card order read-back, `cart:updated` payload `items` / `summary.lines`, and rendered bundle DOM evidence.
 - Do not use external browser skills, the SDK test-mode event, or hand-built backend API orders as launch proof. Those are diagnostic fallbacks only when explicitly requested.
-- Test orders are safe to fire any time: global test cards bypass the gateway, create no transactions, and need no merchant-specific routing confirmation. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; 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.
+- Test orders still land in the store as real orders that someone may have to cancel (global test cards bypass the gateway: no charge, no transaction, no merchant-specific routing to confirm). Unless the operator has already said test orders are fine for this campaign, ask once, up front in your first turn with your other setup questions, so the answer covers the whole build and QA and neither stops for it later. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; 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.
 - Campaigns OS proof is not merchant launch readiness. Before launch, confirm production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration.
 
 Current source adapter: prepared HTML/assets (`html_funnel`).

package/agents/codex/AGENTS.md

@@ -22,7 +22,7 @@ Use this context when working in a target campaign repo with Campaigns OS artifa
 - For `shop-three-step`, keep dynamic shipping via `window.next.getShippingMethods()` and do not add Olympus-style static `shipping_methods` frontmatter.
 - Build hands off to polish. Before Polish becomes terminal or hands off to deploy/QA, install the package-owned Playwright browser with `npm run qa:install-browser`, serve the current build, and run `npx --no-install campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>`.
 - After that checkpoint clears, QA uses the Campaigns OS Node/npm runner: run `npx --no-install campaigns-os qa resolve`, then `npx --no-install campaigns-os qa run --browser --test-order common` against the tested URL.
-- Typed-card test-order proof uses `npx --no-install campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the tested checkout and rendered upsell controls. Global test cards bypass the gateway and create no transactions, so no permission/approval is needed — coverage is the only control. `common` runs every actual terminal path when they fit under the flood cap (`--max-test-orders`, 6 by default); above the cap it runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path, then adds one decline path per offer or downsell page not yet declined, up to the cap, and names any page left out. A page counts as covered only when an order clicks its decline; the `browser-test-order:upsell-action-coverage` verdict row warns naming each page whose decline no order clicked. `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; non-localhost preview/production origins still need SDK origin allowlist confirmation. Do not use external browser skills, the SDK test-mode event, or hand-built backend API orders as launch proof.
+- Typed-card test-order proof uses `npx --no-install campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the tested checkout and rendered upsell controls. `qa run` has no permission flag: coverage is its only control. Test orders still land in the store as real orders (global test cards: no charge, no transaction) that someone may have to cancel. Unless the operator has already said test orders are fine for this campaign, ask once, up front in your first turn with your other setup questions, so the answer covers the whole build and QA and neither stops for it later. `common` runs every actual terminal path when they fit under the flood cap (`--max-test-orders`, 6 by default); above the cap it runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path, then adds one decline path per offer or downsell page not yet declined, up to the cap, and names any page left out. A page counts as covered only when an order clicks its decline; the `browser-test-order:upsell-action-coverage` verdict row warns naming each page whose decline no order clicked. `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; non-localhost preview/production origins still need SDK origin allowlist confirmation. Do not use external browser skills, the SDK test-mode event, or hand-built backend API orders as launch proof.
 - Analytics correctness is two-phase: the campaign-root visit inventories declared providers/tags only, and the same canonical typed-card run proves Purchase only from the topology-recognized final receipt document after `--analytics-settle`. Missing/unrecognized receipts are manual-review warnings; recognized receipt no-signal and capture/settle errors block. Only the genuine recognized-receipt/no-signal failure is waivable; capture/settle errors are not. Checkout/upsell signals remain whole-journey parity evidence and cannot satisfy a silent receipt.
 - Do not use `next.getCartData().cartLines` as cart-populated proof; use typed-card order read-back, `cart:updated` payload `items` / `summary.lines`, and rendered bundle DOM evidence.
 - Campaigns OS proof is not merchant launch readiness. Before launch, confirm production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration.

package/agents/copilot/copilot-instructions.md

@@ -12,4 +12,4 @@ CampaignSpec validation is owned by the public `@nextcommerce/campaigns-os/campa
 
 Preserve Campaign Cart SDK-owned commerce surfaces. Replace starter demo refs from CampaignSpec/API. Prepared AI/exported HTML must be converted into page-kit-ready source first: keep page-owned body markup, strip document wrappers, add YAML frontmatter, move shared CSS/assets into the campaign structure, and use Liquid helpers only for page-kit links/assets/includes. Landing/presell pages can preserve source design; checkout/upsell/downsell/receipt should use starter-template commerce surfaces as SDK contract references while campaign/source owns visual chrome. Reproduce the source design's own proof and urgency elements as designed (reviews, ratings, stock counters, countdowns, guarantees). They are the merchant's content; Campaigns OS does not review them, so do not remove, soften or flag them. Copy starter template families atomically with dependent pages, `_includes/`, `_layouts/`, `assets/css/`, and `assets/js/`; do not copy only checkout/receipt pages. Do not claim launch readiness until build, polish, deploy, and QA evidence are recorded.
 
-Before Polish becomes terminal or hands off to deploy/QA, install the package-owned Playwright browser with `npm run qa:install-browser`, serve the current build, and run `npx --no-install campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>`. After that checkpoint clears, QA must use the Campaigns OS Node/npm runner: run `npx --no-install campaigns-os qa resolve`, then run `npx --no-install campaigns-os qa run --browser --test-order common` against the tested URL. Typed-card test-order proof must use `npx --no-install campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the tested checkout and rendered upsell controls; global test cards bypass the gateway and create no transactions, so no permission/approval is needed. `common` runs every actual terminal path when they fit under the flood cap (`--max-test-orders`, 6 by default); above the cap it runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path, then adds one decline path per offer or downsell page not yet declined, up to the cap, and names any page left out. A page counts as covered only when an order clicks its decline; the `browser-test-order:upsell-action-coverage` verdict row warns naming each page whose decline no order clicked. `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Analytics correctness is two-phase: the campaign-root visit inventories declared providers/tags only, and the same canonical typed-card run proves Purchase only from the topology-recognized final receipt document after `--analytics-settle`. Missing/unrecognized receipts are manual-review warnings; recognized receipt no-signal and capture/settle errors block. Only the genuine recognized-receipt/no-signal failure is waivable; capture/settle errors are not. Checkout/upsell signals remain whole-journey parity evidence and cannot satisfy a silent receipt. Do not use `next.getCartData().cartLines` as cart-populated proof; use typed-card order read-back, `cart:updated` payload `items` / `summary.lines`, and rendered bundle DOM evidence. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; non-localhost preview/production origins still need SDK origin allowlist confirmation. Do not use external browser skills, SDK test-mode events, or direct backend orders as launch proof. Campaigns OS proof is not merchant launch readiness; before launch, confirm production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration.
+Before Polish becomes terminal or hands off to deploy/QA, install the package-owned Playwright browser with `npm run qa:install-browser`, serve the current build, and run `npx --no-install campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>`. After that checkpoint clears, QA must use the Campaigns OS Node/npm runner: run `npx --no-install campaigns-os qa resolve`, then run `npx --no-install campaigns-os qa run --browser --test-order common` against the tested URL. Typed-card test-order proof must use `npx --no-install campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the tested checkout and rendered upsell controls. `qa run` has no permission flag: coverage is its only control. Test orders still land in the store as real orders (global test cards: no charge, no transaction) that someone may have to cancel. Unless the operator has already said test orders are fine for this campaign, ask once, up front in your first turn with your other setup questions, so the answer covers the whole build and QA and neither stops for it later. `common` runs every actual terminal path when they fit under the flood cap (`--max-test-orders`, 6 by default); above the cap it runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path, then adds one decline path per offer or downsell page not yet declined, up to the cap, and names any page left out. A page counts as covered only when an order clicks its decline; the `browser-test-order:upsell-action-coverage` verdict row warns naming each page whose decline no order clicked. `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Analytics correctness is two-phase: the campaign-root visit inventories declared providers/tags only, and the same canonical typed-card run proves Purchase only from the topology-recognized final receipt document after `--analytics-settle`. Missing/unrecognized receipts are manual-review warnings; recognized receipt no-signal and capture/settle errors block. Only the genuine recognized-receipt/no-signal failure is waivable; capture/settle errors are not. Checkout/upsell signals remain whole-journey parity evidence and cannot satisfy a silent receipt. Do not use `next.getCartData().cartLines` as cart-populated proof; use typed-card order read-back, `cart:updated` payload `items` / `summary.lines`, and rendered bundle DOM evidence. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; non-localhost preview/production origins still need SDK origin allowlist confirmation. Do not use external browser skills, SDK test-mode events, or direct backend orders as launch proof. Campaigns OS proof is not merchant launch readiness; before launch, confirm production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration.

package/agents/cursor/campaigns-os.mdc

@@ -10,4 +10,4 @@ Read Campaigns OS artifacts before editing campaign pages. To pick up an existin
 
 Do not carry over demo package, shipping, voucher, payment, tracking, footer, or SEO values. Prepared AI/exported HTML must be converted into page-kit-ready source first: keep page-owned body markup, strip document wrappers, add YAML frontmatter, move shared CSS/assets into the campaign structure, and use Liquid helpers only for page-kit links/assets/includes. Preserve prepared landing/presell source HTML when it is a real standalone design. For checkout/upsell/downsell/receipt, use starter-template commerce surfaces as SDK contract references while campaign/source owns visual chrome. Reproduce the source design's own proof and urgency elements as designed (reviews, ratings, stock counters, countdowns, guarantees). They are the merchant's content; Campaigns OS does not review them, so do not remove, soften or flag them. Copy starter template families atomically with dependent pages, `_includes/`, `_layouts/`, `assets/css/`, and `assets/js/`; do not copy only checkout/receipt pages. Emit SDK routing meta tags as campaign-root paths such as `/campaign-slug/upsell/`. Preserve SDK-owned checkout/cart/upsell/receipt surfaces. For `shop-three-step`, shipping is dynamic via `window.next.getShippingMethods()`.
 
-Before Polish becomes terminal or hands off to deploy/QA, install the package-owned Playwright browser with `npm run qa:install-browser`, serve the current build, and run `npx --no-install campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>`. After that checkpoint clears, QA uses the Campaigns OS Node/npm runner: `npx --no-install campaigns-os qa resolve`, then `npx --no-install campaigns-os qa run --browser --test-order common` against the tested URL. Test-order proof uses `npx --no-install campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the tested checkout and rendered upsell controls; global test cards bypass the gateway and create no transactions, so no permission/approval is needed. `common` runs every actual terminal path when they fit under the flood cap (`--max-test-orders`, 6 by default); above the cap it runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path, then adds one decline path per offer or downsell page not yet declined, up to the cap, and names any page left out. A page counts as covered only when an order clicks its decline; the `browser-test-order:upsell-action-coverage` verdict row warns naming each page whose decline no order clicked. `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Analytics correctness is two-phase: the campaign-root visit inventories declared providers/tags only, and the same canonical typed-card run proves Purchase only from the topology-recognized final receipt document after `--analytics-settle`. Missing/unrecognized receipts are manual-review warnings; recognized receipt no-signal and capture/settle errors block. Only the genuine recognized-receipt/no-signal failure is waivable; capture/settle errors are not. Checkout/upsell signals remain whole-journey parity evidence and cannot satisfy a silent receipt. Do not use `next.getCartData().cartLines` as cart-populated proof; use typed-card order read-back, `cart:updated` payload `items` / `summary.lines`, and rendered bundle DOM evidence. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; non-localhost preview/production origins still need SDK origin allowlist confirmation. External browser skills, SDK test-mode events, and direct backend orders are not launch proof. Campaigns OS proof is not merchant launch readiness; before launch, confirm production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration.
+Before Polish becomes terminal or hands off to deploy/QA, install the package-owned Playwright browser with `npm run qa:install-browser`, serve the current build, and run `npx --no-install campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>`. After that checkpoint clears, QA uses the Campaigns OS Node/npm runner: `npx --no-install campaigns-os qa resolve`, then `npx --no-install campaigns-os qa run --browser --test-order common` against the tested URL. Test-order proof uses `npx --no-install campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the tested checkout and rendered upsell controls. `qa run` has no permission flag: coverage is its only control. Test orders still land in the store as real orders (global test cards: no charge, no transaction) that someone may have to cancel. Unless the operator has already said test orders are fine for this campaign, ask once, up front in your first turn with your other setup questions, so the answer covers the whole build and QA and neither stops for it later. `common` runs every actual terminal path when they fit under the flood cap (`--max-test-orders`, 6 by default); above the cap it runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path, then adds one decline path per offer or downsell page not yet declined, up to the cap, and names any page left out. A page counts as covered only when an order clicks its decline; the `browser-test-order:upsell-action-coverage` verdict row warns naming each page whose decline no order clicked. `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Analytics correctness is two-phase: the campaign-root visit inventories declared providers/tags only, and the same canonical typed-card run proves Purchase only from the topology-recognized final receipt document after `--analytics-settle`. Missing/unrecognized receipts are manual-review warnings; recognized receipt no-signal and capture/settle errors block. Only the genuine recognized-receipt/no-signal failure is waivable; capture/settle errors are not. Checkout/upsell signals remain whole-journey parity evidence and cannot satisfy a silent receipt. Do not use `next.getCartData().cartLines` as cart-populated proof; use typed-card order read-back, `cart:updated` payload `items` / `summary.lines`, and rendered bundle DOM evidence. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; non-localhost preview/production origins still need SDK origin allowlist confirmation. External browser skills, SDK test-mode events, and direct backend orders are not launch proof. Campaigns OS proof is not merchant launch readiness; before launch, confirm production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration.

package/campaign-spec/dist/rules/campaign-metadata.d.ts

@@ -8,7 +8,11 @@
  * a need to subset them. If that need shows up, split into
  * CampaignPaymentKey and CampaignRefId.
  *
- * Message text inherited verbatim from the pre-#110 validator at migration time.
+ * The ref_id message is inherited verbatim from the pre-#110 validator. The
+ * payment_env_key message keeps that validator's first sentence, which
+ * consumers match, and adds which field is empty and where its value comes
+ * from: a Campaigns API key in the spec (campaign.campaigns_api_key) is a
+ * different field and does not satisfy it.
  */
 import type { Rule } from '../types.ts';
 export declare const CampaignMetadata: Rule;

package/campaign-spec/dist/rules/campaign-metadata.js

@@ -8,7 +8,11 @@
  * a need to subset them. If that need shows up, split into
  * CampaignPaymentKey and CampaignRefId.
  *
- * Message text inherited verbatim from the pre-#110 validator at migration time.
+ * The ref_id message is inherited verbatim from the pre-#110 validator. The
+ * payment_env_key message keeps that validator's first sentence, which
+ * consumers match, and adds which field is empty and where its value comes
+ * from: a Campaigns API key in the spec (campaign.campaigns_api_key) is a
+ * different field and does not satisfy it.
  */
 export const CampaignMetadata = {
     id: 'CampaignMetadata',
@@ -21,7 +25,10 @@ export const CampaignMetadata = {
             violations.push({
                 ruleId: 'CampaignMetadata',
                 severity: 'warning',
-                message: 'No campaign loaded — campaign key required for spec export.',
+                message: 'No campaign loaded — campaign key required for spec export. ' +
+                    'campaign.payment_env_key is empty: copy it from the campaign retrieve body ' +
+                    '(docs/build-packet.md, "Reading package, offer and shipping refs"). ' +
+                    'A Campaigns API key in the spec does not fill this field.',
                 path: '/campaign/payment_env_key',
                 data: { missing: 'payment_env_key' },
             });

package/campaign-spec/dist/rules/design-source-shape.js

@@ -25,6 +25,10 @@
  * a build blocker. The export tool itself is the real validator at handoff
  * time; this rule keeps Map Builder authors honest while editing.
  */
+// design_source.type values with a producer (docs/entry-points.md). A page of
+// one of these types needs its file_url; any other type gets the hand-written
+// HTML way out as well.
+const DESIGN_TOOL_PRODUCERS = new Set(['figma', 'ai-generated']);
 const FIGMA_URL_PATTERN = /^https:\/\/(?:www\.)?figma\.com\//i;
 const ANY_URL_PATTERN = /^https?:\/\/\S+/i;
 function isNonEmptyString(value) {
@@ -44,6 +48,9 @@ export const DesignSourceShape = {
                     return;
                 const basePath = `/funnels/${funnelIdx}/pages/${pageIdx}/design_source`;
                 const pageLabel = page.label || page.id || '(unnamed page)';
+                // One normalization for every type comparison below, so "Figma" and
+                // " figma " are the same producer everywhere in this rule.
+                const designType = String(design.type ?? '').trim().toLowerCase();
                 // 1. type
                 if (!isNonEmptyString(design.type)) {
                     violations.push({
@@ -59,7 +66,10 @@ export const DesignSourceShape = {
                     violations.push({
                         ruleId: 'DesignSourceShape',
                         severity: 'warning',
-                        message: `"${pageLabel}" — design_source.file_url is missing; expected the design-tool file URL.`,
+                        message: `"${pageLabel}" — design_source.file_url is missing; expected the design-tool file URL.` +
+                            (DESIGN_TOOL_PRODUCERS.has(designType)
+                                ? ''
+                                : ' Hand-written or template HTML has no design tool: remove design_source from the page (see docs/entry-points.md).'),
                         path: `${basePath}/file_url`,
                         data: { pageId: page.id, check: 'file-url-missing' },
                     });
@@ -73,7 +83,7 @@ export const DesignSourceShape = {
                         data: { pageId: page.id, check: 'file-url-shape', value: design.file_url },
                     });
                 }
-                else if (design.type === 'figma' && !FIGMA_URL_PATTERN.test(design.file_url)) {
+                else if (designType === 'figma' && !FIGMA_URL_PATTERN.test(design.file_url)) {
                     // 3. figma-specific: must be a figma.com URL
                     violations.push({
                         ruleId: 'DesignSourceShape',
@@ -121,7 +131,7 @@ export const DesignSourceShape = {
                             });
                             continue;
                         }
-                        if (design.type === 'figma' && !FIGMA_URL_PATTERN.test(value)) {
+                        if (designType === 'figma' && !FIGMA_URL_PATTERN.test(value)) {
                             violations.push({
                                 ruleId: 'DesignSourceShape',
                                 severity: 'warning',

package/campaign-spec/dist/rules/sdk-version.js

@@ -47,7 +47,8 @@ export const SdkVersion = {
                 {
                     ruleId: 'SdkVersion',
                     severity: 'error',
-                    message: 'SDK version is required for spec export.',
+                    message: 'SDK version is required for spec export. Set global_config.sdk_version ' +
+                        'to the released Campaign Cart SDK version the pages load, in MAJOR.MINOR.PATCH form.',
                     path: '/global_config/sdk_version',
                 },
             ];

package/compatibility.json

@@ -1,6 +1,6 @@
 {
   "package": "@nextcommerce/campaigns-os",
-  "version": "1.50.0",
+  "version": "1.52.0",
   "status": "developer-preview",
   "contracts": {
     "campaign_spec": "4.2-4.3",