@nextcommerce/campaigns-os 1.50.0 → 1.53.0

package/CHANGELOG.md

@@ -2,6 +2,480 @@
 
 Notable supported-surface changes are recorded here.
 
+## [1.53.0+agent.2] - 2026-10-05
+
+### Changed
+
+`next` now prints a short campaign intent summary, generated from the normalized Campaign Build Brief, in every result (`intent_summary` in JSON) and at the top of the setup, build, Polish and QA prompts. Each value is marked as set in the saved brief file, taken from the source, a generated default, or not stated; a value whose origin was not recorded, or that changed since it was recorded, says so. These marks are tamper evidence, not proof of who wrote a value. Values are shown as quoted data. The summary never shows a purpose or palette source that Campaigns OS inferred from page types or page names: unless the brief file states them, they read "not stated". The summary is output only: nothing reads it, and it cannot change prices or commerce behaviour. Bundled skills and the agent context files now tell agents to read the brief and the recorded assembly decisions.
+
+The build stage prompt that `next` returns now tells the agent to save a changed Campaign Build Brief with `record brief` or a changed CampaignSpec with `record spec` before building on the change.
+
+Bundled skills are at revision `1.53.0+skills.2`. The lifecycle skill saves brief answers with `record brief` and returns the single compact brief defined in `references/session-intake.md`, whose work-type field is now `Work:` beside a new `Campaign:` field. The build skill passes `--deviation-reason` to `record build` only on the operator's explicit decision, the Polish skill records a skipped Polish only on the operator's decision, and the Polish and QA skills say how to report a readability warning and offer repairs inside the brand palette.
+
+### Migration
+
+**Migration.** The agent context files changed, so `tooling setup` refuses until each existing campaign refreshes its installed copy. From the campaign folder:
+
+1. `npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.53.0`
+2. `npx --no-install campaigns-os install-agent-context --target .` (overwrites all four files under `.campaign-runtime/agent-context/`; local edits there are lost)
+3. Review and commit `git diff .campaign-runtime/agent-context/`
+4. `npx --no-install campaigns-os tooling setup --target . --platform claude`
+5. Restart the agent session so it loads the new skills and context.
+
+Codex, Cursor and Copilot users run step 2 and reinstall skills with `install-skills --platform codex` (or `agents`).
+
+## [1.53.0+agent.1] - 2026-10-05
+
+### Added
+
+- Polish now measures text readability on every built page at desktop and mobile widths and reports warnings, review and coverage results in the QC handoff. QA's primary-CTA check and the theme generator use the same unrounded WCAG 2.x measurement. Results change on some campaigns: ratios in [4.495, 4.5), translucent text or backgrounds, and child text now warn; large bold text at 3:1 and Tailwind v4 `oklch()` colours are measured correctly; gradients, unreadable colours, and opacity, filters, blend modes or masks on surrounding elements become manual review instead of a contrast result. QA's primary-CTA check no longer skips pages by page type: every page with an expected next route is checked, every route-matching CTA is measured (not only the most readable one), each piece of text inside a CTA is compared with the requirement for its own size, and a CTA measured before its text, the SDK, stylesheets or fonts are ready is reported for manual review, never as a pass. The primary-CTA check also reports manual review, not a failure or a pass, when the page inspection itself errors (earlier releases reported a failure), when every route-matching CTA is disabled, and when a CTA's text includes text generated by CSS `::before` or `::after` (earlier releases reported a contrast pass or failure for both). `polish capture` on a campaign with no mapped pages now measures readability and exits successfully, printing the page-load message as a warning. Polish media weight and readability results now read as stale when the built output changed without a new `record build`.
+
+## [1.53.0] - 2026-10-05
+
+### Added
+
+- Adds `record brief`, which saves Campaign Build Brief answers without re-running intake. A brief file is guided unless it sets `"brief_mode": "prepared"` (a campaign whose report already records a prepared brief stays prepared). An unchanged or reformatted save keeps all stage evidence and statuses. A material change marks build, Polish and QA (or QA alone for `qa_policy`) as owed again and keeps the last five superseded records per stage as history. `next` routes to the owed stage. Re-recording an unchanged build after an input change keeps the build owed unless the operator records a reason, including when a CampaignSpec change was never saved with `record spec`; an edit to the brief file is read only once it is saved with `record brief`. Intake now also refuses, without `--force`, to discard recorded waivers, warning accepts, stage history, an applied theme, or a recorded deploy target, preview URL, production URL, order-path depth or allowed-domains confirmation; with `--force`, it keeps stage history and archives the records it clears.
+- Adds `record spec`, a non-destructive refresh after a CampaignSpec change. Superseded build, Polish and QA records move to stage history, and `next`, progress, readback and the Assembly Report status now report the owed stage instead of recommending QA. Spec material changes are detected for saved-Map and gateway packets too (against the fetched copy; remote currency is reported as unconfirmed). `spec derive` no longer rebinds report identity on its own; run `record spec` after it. Re-recording an unchanged build or replaying a Polish record after an input change no longer makes them current, whether or not the change was saved with `record spec`.
+
+### Changed
+
+- `spec derive --json` no longer carries the `rebound` field, because `spec derive` no longer rebinds report identity.
+- A stage status outside the recognized list (`pending`, `blocked`, `required`, `completed`, `completed_with_warnings`, `completed_partial`, `skipped`) now reads as unknown and stops `next`, where earlier releases accepted any status beginning `completed` or `skipped`.
+- The effects contract declares the `record brief` and `record spec` rows (tier C) and their `--dry-run` rows (tier none, with no lifecycle entry). It corrects the intake rows: `start`, `prepare-build` and `build` are refused without `--force` when the report carries stage evidence, stage history or operator decisions, and their `--force` forms archive completed build, Polish and QA records into stage history, which is kept. It also states that `record build` writes `input_change` and makes Polish and QA owed when it detects a brief or CampaignSpec change, and that `record polish`, `record theme` and `record deploy` are refused while an earlier stage is owed again.
+
+### Migration
+
+**Migration.** Build, Polish and QA records made before this release do not record which brief and CampaignSpec content they used, so they read as unconfirmed. After upgrading, `next` routes each in-flight campaign back to build once: re-record build and Polish, and run QA again for a new verdict. Hand-written brief files without `brief_mode` are now guided for new campaigns; add `"brief_mode": "prepared"` if you want open questions to block.
+
+- Re-running `start`, `prepare-build` or `build` over a campaign with recorded waivers, warning accepts, stage history, an applied theme, or a recorded deploy target, preview URL, production URL, order-path depth or allowed-domains confirmation is now refused without `--force`. Save brief answers with `record brief` and a CampaignSpec change with `record spec` instead; pass `--force` only to clear that state on purpose.
+- Scripts that read `rebound` from `spec derive --json` must stop: run `record spec` after `spec derive` to bind the new CampaignSpec content.
+
+## [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

@@ -8,6 +8,8 @@ project copy. Do not use private runtime source as the campaign's starting point
 
 To pick up an existing campaign, run `npx --no-install campaigns-os readback .` and `npx --no-install campaigns-os next --packet campaign-runtime.build.json` before reading artifacts by hand; `next` blocks polish and QA again whenever the built output changes. The committed `.campaign-runtime/qa-verdict.json` keeps no order records or URLs: its `browser-test-order:<path>` assertions are the typed-card proof, and the full verdict is under `qa-output/`.
 
+A NEXT campaign is one connected commerce journey: the pages the CampaignSpec declares, in its order, through product choice, checkout, post-purchase offers and receipt. Creative intent — audience, purpose, layout, imagery, approved copy, visual style — belongs to the operator, the Campaign Build Brief and the accepted design source. Commerce behaviour — products, package IDs, prices, offers, shipping, routes, cart, checkout, payment and post-purchase — belongs to CampaignSpec/API values and the SDK. Before changing a campaign, read the normalized 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. The setup, build, Polish and QA prompts begin with a campaign intent summary, and every `next` result carries it (`intent_summary` in JSON); treat it as orientation, never as a source of prices or behaviour. When a revision is narrow, keep the recorded intent and ask only about missing choices that affect that revision. Ask the operator before saving brief answers.
+
 Core rules:
 
 - Treat CampaignSpec as campaign intent and the Campaigns API as live commerce truth.
@@ -28,12 +30,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

@@ -2,6 +2,8 @@
 
 Use this context when working in a target campaign repo with Campaigns OS artifacts.
 
+A NEXT campaign is one connected commerce journey: the pages the CampaignSpec declares, in its order, through product choice, checkout, post-purchase offers and receipt. Creative intent — audience, purpose, layout, imagery, approved copy, visual style — belongs to the operator, the Campaign Build Brief and the accepted design source. Commerce behaviour — products, package IDs, prices, offers, shipping, routes, cart, checkout, payment and post-purchase — belongs to CampaignSpec/API values and the SDK. Before changing a campaign, read the normalized 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. The setup, build, Polish and QA prompts begin with a campaign intent summary, and every `next` result carries it (`intent_summary` in JSON); treat it as orientation, never as a source of prices or behaviour. When a revision is narrow, keep the recorded intent and ask only about missing choices that affect that revision. Ask the operator before saving brief answers.
+
 - Read `campaign-runtime.build.json` first.
 - To pick up an existing campaign, run `npx --no-install campaigns-os readback .` and `npx --no-install campaigns-os next --packet campaign-runtime.build.json` before reading artifacts by hand; `next` blocks polish and QA again whenever the built output changes. The committed `.campaign-runtime/qa-verdict.json` keeps no order records or URLs: its `browser-test-order:<path>` assertions are the typed-card proof, and the full verdict is under `qa-output/`.
 - If `.campaign-runtime/build-context.json` or `.campaign-runtime/assembly-report.json` exists, read them before editing campaign files.
@@ -22,7 +24,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

@@ -8,8 +8,10 @@ When this repository contains Campaigns OS artifacts, use them as the build hand
 - To pick up an existing campaign, run `npx --no-install campaigns-os readback .` and `npx --no-install campaigns-os next --packet campaign-runtime.build.json` before reading artifacts by hand; `next` blocks polish and QA again whenever the built output changes. The committed `.campaign-runtime/qa-verdict.json` keeps no order records or URLs: its `browser-test-order:<path>` assertions are the typed-card proof, and the full verdict is under `qa-output/`.
 - `.campaign-runtime/theme/theme-report.json`, when present, is optional brand-theme evidence. Generated `brand-theme.css` must load after `next-core.css`; missing or low-confidence theme is a warning/skipped reason, not permission to edit SDK-owned runtime surfaces.
 
+A NEXT campaign is one connected commerce journey: the pages the CampaignSpec declares, in its order, through product choice, checkout, post-purchase offers and receipt. Creative intent — audience, purpose, layout, imagery, approved copy, visual style — belongs to the operator, the Campaign Build Brief and the accepted design source. Commerce behaviour — products, package IDs, prices, offers, shipping, routes, cart, checkout, payment and post-purchase — belongs to CampaignSpec/API values and the SDK. Before changing a campaign, read the normalized 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. The setup, build, Polish and QA prompts begin with a campaign intent summary, and every `next` result carries it (`intent_summary` in JSON); treat it as orientation, never as a source of prices or behaviour. When a revision is narrow, keep the recorded intent and ask only about missing choices that affect that revision. Ask the operator before saving brief answers.
+
 CampaignSpec validation is owned by the public `@nextcommerce/campaigns-os/campaign-spec` rules surfaced through doctor `spec.validation` findings; use structured rule/path detail when available.
 
 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

@@ -8,6 +8,8 @@ alwaysApply: false
 
 Read Campaigns OS artifacts before editing campaign pages. To pick up an existing campaign, run `npx --no-install campaigns-os readback .` and `npx --no-install campaigns-os next --packet campaign-runtime.build.json` before reading artifacts by hand; `next` blocks polish and QA again whenever the built output changes. The committed `.campaign-runtime/qa-verdict.json` keeps no order records or URLs: its `browser-test-order:<path>` assertions are the typed-card proof, and the full verdict is under `qa-output/`. Treat CampaignSpec/API values as live commerce truth, starter-template contracts as SDK surface truth, and designed HTML/assets as visual/content intent. Treat CampaignSpec validation as owned by the public `@nextcommerce/campaigns-os/campaign-spec` rules surfaced through doctor `spec.validation` findings; use structured rule/path detail when available. If `context.theme` or `.campaign-runtime/theme/theme-report.json` exists, use it as optional brand-theme evidence; generated `brand-theme.css` must load after `next-core.css`, and missing/low-confidence theme is a warning or skipped reason, not permission to edit SDK-owned runtime surfaces.
 
+A NEXT campaign is one connected commerce journey: the pages the CampaignSpec declares, in its order, through product choice, checkout, post-purchase offers and receipt. Creative intent — audience, purpose, layout, imagery, approved copy, visual style — belongs to the operator, the Campaign Build Brief and the accepted design source. Commerce behaviour — products, package IDs, prices, offers, shipping, routes, cart, checkout, payment and post-purchase — belongs to CampaignSpec/API values and the SDK. Before changing a campaign, read the normalized 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. The setup, build, Polish and QA prompts begin with a campaign intent summary, and every `next` result carries it (`intent_summary` in JSON); treat it as orientation, never as a source of prices or behaviour. When a revision is narrow, keep the recorded intent and ask only about missing choices that affect that revision. Ask the operator before saving brief answers.
+
 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;