@nextcommerce/campaigns-os 1.61.0 → 1.63.0

package/docs/campaign-standardization-report.md

@@ -81,10 +81,10 @@ field before attributing the file.
 `--template-family`), `--slug`, `--sdk-support-policy`, `--field-contract`,
 `--no-doctor`, `--json`, and the two flags every command accepts,
 `--run-id` and `--lifecycle-journal`. Any other flag is refused before the
-scan starts, with the known list in the message — including the
-`--flag=value` spelling, which the parser would otherwise store as an unknown
-key (`--no-doctor=maybe` used to run the doctor anyway). Values follow the
-flag as the next argument.
+scan starts, with the known list in the message. Values follow the flag as
+the next argument: like every Campaigns OS command, standardize refuses the
+`--flag=value` spelling before the scan starts (`--no-doctor=maybe` used to
+run the doctor anyway).
 
 ### Exit codes
 

package/docs/campaigns-os-build-flow.md

@@ -33,8 +33,8 @@ a production render instead. Environment differences also change fingerprints.
 
 | CI status | Exit code | Meaning |
 |---|---|---|
-| `current` | `0` | Polish and QA both bind to the build on disk and neither is lifecycle-required. |
-| `owed` | `3` | Polish or QA binds to another build or is lifecycle-required; evidence is owed. |
+| `current` | `0` | Polish and QA both bind to the build on disk and neither is lifecycle-required, or the only owed stage is advisory Polish for a page-only change. |
+| `owed` | `3` | Polish or QA binds to another build or is lifecycle-required; evidence is owed. For a page-only change only QA on the changed pages counts. |
 | `unknown` | `4` | Output or assembly fingerprints are missing, a stage fingerprint is missing without a lifecycle requirement, output is unreadable, or inspection throws; debt cannot be determined. |
 | `usage` | `2` | The packet is missing, unreadable or invalid JSON. |
 
@@ -53,6 +53,46 @@ The check reads recorded fingerprints, not machine-local capture files.
 Readback's `evidence_debt` uses the same assessment, showing an agent this debt
 before it edits; its separate time-based staleness assessment is not the CI signal.
 
+### What a change owes
+
+Each owed stage carries `change`: what changed since the build that stage
+last reviewed. It is read from the rebuilds `record build` keeps
+(`stages.assembly.build_changes`) plus the drift on disk, so the changed pages
+stay listed after `record build`. A change is one of two kinds:
+
+- **Page-only.** Only the HTML of some pages changed (copy, image references,
+  inline styling), and none of them is a checkout page or changed its commerce markup:
+  `data-next-*`, `os-checkout-*` and other package, offer, shipping or upsell
+  attributes, inline event handlers (`onclick` and the like), `next-*` meta
+  tags (the upsell accept and decline routes among them), scripts, link
+  targets or form actions. A checkout page is one whose type is checkout,
+  checkout step or select, or one that carries checkout or payment markup
+  (`data-next-checkout*`, `data-next-payment*`, `data-next-express-checkout*`,
+  `os-checkout*`). The campaign's own entry in
+  `_data/campaigns.json` (SDK pin, analytics ids, store fields) is unchanged.
+  It owes QA on the changed pages only: `qa.scope` is `pages` and
+  `qa.owed_pages` lists them. Polish is advisory (`polish.advisory: true`): it
+  is reported, and `next`, the CI check and the QA gate do not require it.
+- **Commerce-affecting.** Anything else: a checkout page, commerce markup or
+  the config entry changed, a page was added or removed (a route change), or a
+  built file other than a page's HTML changed (a script, stylesheet or image
+  file cannot be mapped to one page). It owes the full Polish and QA, as
+  does a change that cannot be read (a record made before `record build`
+  kept a commerce signature, or a rebuild history that no longer reaches the
+  reviewed build). A Polish or QA requirement a brief or spec change made is
+  always full.
+
+A page-only change extends only a review that completed. Polish is advisory
+only when the last Polish completed or was skipped; a blocked Polish owes the
+full stage. QA is owed on the changed pages only when the last QA completed,
+or when it was a page-scoped run that did not complete, in which case the
+pages are counted from the full QA that run extended, so its unpaid pages stay
+owed. A blocked or pending full QA owes a full run.
+
+The PR comment opens with the kind it found and what that owes, for example
+"Change found: page-only. It owes QA on `upsell1`; Polish is advisory." A
+commerce-affecting change names its reasons.
+
 Copy the [workflow example](https://github.com/NextCommerceCo/campaigns-os/blob/main/docs/examples/campaign-repo-evidence-check.yml) into the
 campaign repository and adjust the packet path. It posts or updates one PR
 comment using the fixed `<!-- campaign-evidence-check -->` marker. Evidence
@@ -67,7 +107,18 @@ Fork pull requests may lack comment-write permission; comment failures are
 nonfatal and the report remains in the job log. The example uses `pull_request`
 and does not run untrusted code with `pull_request_target` privileges.
 
-To repay fingerprint-drift debt, rebuild and record the output, re-run `polish capture` against
+To repay a page-only change, rebuild, run `record build`, then run
+`qa run --packet <packet> --page <page_id>` against that build, repeating
+`--page` for each changed page the report names. A page-scoped run checks only
+those pages and places no test orders; the QA stage it records keeps the
+purchase proof of the full run it extends. It refuses, before checking
+anything, when the output on disk is not the recorded build, when the change
+is commerce-affecting, when a changed page is left out, when the QA it would
+extend did not complete, or when QA's inputs (the brief's `qa_policy` and the
+CampaignSpec) changed or cannot be confirmed current. Running Polish for a
+page-only change is optional.
+
+To repay fingerprint-drift debt for any other change, rebuild and record the output, re-run `polish capture` against
 that served build, record Polish with `record polish --evidence <evidence.json>`,
 then run `qa run` to record QA for the current build. For lifecycle-required
 stages with matching build bindings, re-run the required stages against the

package/docs/campaignspec-authoring-examples.md

@@ -27,7 +27,9 @@ Authoring guidance:
   - `packages[]` entries use `ref_id` + `qty` (the real export key is `qty`,
     not `quantity`). A plain entry is the main package; add-ons carry the
     boolean role flags `is_order_bump: true` / `is_upsell: true` — there is
-    no `role` field in exports.
+    no `role` field in exports. The flags mean "add-on" on `checkout`,
+    `checkout_step` and `select` pages only. On an upsell or downsell page
+    they mark nothing (see the upsell page below).
   - `sdk_hints.template_family` names the intended starter family only as a
     hint; the Build Packet still locks the family.
   - `sdk_hints.meta_tags.next-success-url` points to the next runtime route.
@@ -65,9 +67,12 @@ Authoring guidance:
   - `type: "upsell"` or `type: "downsell"`, with
     `sdk_hints.sdk_page_type: "upsell"`
   - `page_url` is a Page Kit route, not a source filename.
-  - `packages[]` (with `is_upsell: true`) or `offers[]` names the
-    post-purchase offer refs. Offers are identified by `ref_id` into the
-    root `offers[]` catalog (`package_ref_id` is not part of the contract).
+  - `packages[]` or `offers[]` names the post-purchase offer refs. Write each
+    package as a plain `{ ref_id, qty }` entry. On an upsell or downsell page
+    every package row is the page's offer and never an order bump, so
+    `is_upsell: true` on that row is accepted and changes nothing about
+    its role. Offers are identified by `ref_id` into the root `offers[]` catalog
+    (`package_ref_id` is not part of the contract).
   - `on_accept` and `on_decline` hold the next PAGE IDs; route paths live
     in `page_url` / derived `resolved_routing`.
 
@@ -91,6 +96,56 @@ Generator checklist:
 - Keep checkout/upsell/downsell/receipt runtime surfaces template-clone-first;
   source HTML can own visual composition and copy, not payment/order mutation.
 
+## Campaign Currencies
+
+- `campaign.currency` is the default currency: a three-letter upper-case
+  ISO 4217 code such as `"USD"`. A lower-case code (`"usd"`) or a symbol
+  (`"US$"`) is an error, because Campaign Cart can fall back to a cached USD
+  campaign and price the page in the wrong currency.
+- `campaign.available_currencies` lists every currency the campaign sells in,
+  the default included, as code strings: `["USD", "EUR", "GBP"]`. The
+  Campaigns API returns this list as `{ code, label }` objects; Map Builder
+  writes the codes, and a hand-written spec should too.
+- The Campaigns App API also has `additional_currencies`, which is the same
+  list without the default. It is not a CampaignSpec field: put every
+  currency in `available_currencies`.
+- When `available_currencies` is non-empty and does not contain
+  `campaign.currency`, the validator warns. An empty list states nothing and
+  is not checked.
+
+These checks are the `CampaignCurrencies` validator rule, which
+`campaigns-os doctor` runs with the rest of the spec rules.
+
+A page package row can also carry its price in each currency, as `prices[]`:
+
+```json
+{
+  "ref_id": 101, "qty": 1, "price": "49.99", "price_retail": "79.99",
+  "prices": [
+    { "currency": "USD", "price": "49.99", "price_retail": "79.99" },
+    { "currency": "EUR", "price": "46.99", "price_retail": "74.99" }
+  ]
+}
+```
+
+- `price` and `price_retail` stay the default currency's. Each `prices[]`
+  entry has a `currency` code and a `price`, plus `price_retail` and, for a
+  subscription package, `price_recurring` when the Campaigns App has them.
+- The values come from the Campaigns API read in each currency
+  (`GET /campaigns/?currency=EUR`). That read returns only the packages the
+  Campaigns App has a price for in that currency, so a package with no EUR
+  price is missing from the campaign for a shopper paying in EUR. Map Builder
+  fills `prices[]` when it refreshes from the API; set prices in the
+  Campaigns App, not in the spec. `campaigns-os spec derive` refreshes `price`
+  and `price_retail` from one default-currency read and leaves `prices[]` as
+  it was, so after changing a non-default price, refresh the Map in Map
+  Builder.
+- `prices[]` is optional. A row without it says nothing about other
+  currencies and is not checked. A row with it should list every currency in
+  `available_currencies` and `campaign.currency`; the `PackageCurrencyPrices`
+  rule warns on a missing currency, a malformed entry and a currency listed
+  twice.
+
 ## Order Bump Notes
 
 An order bump is still a checkout package/offer surface. It should be encoded as

package/docs/design-source-package.md

@@ -439,12 +439,24 @@ left by a process that died is recovered automatically, and a lock directory
 without an owner record (only an older release leaves one) is never taken
 over: the command refuses it after about a second and names it. Confirm no
 campaigns-os process is working on the target, then remove it. Anything else
-at the lock path (a file, a symbolic link, or a directory with no owner record
-that holds other entries) is not a lock: once the wait ends the command names
-what is there and never removes it. The holder of the lock removes staging and
-released directories beside it whose recorded owner process no longer exists.
-Do not run an older Campaigns OS release against the same target at the same
-time. A waiver's `--dry-run` preview takes no lock.
+at the lock path (a file, a symbolic link, a directory the command cannot read,
+or a directory with no owner record that holds other entries) is not a lock:
+once the wait ends the command names what is there and never removes it. The
+holder of the lock removes staging, recovery, released and abandoned
+directories beside it whose recorded owner process no longer exists.
+
+Run one Campaigns OS release against a target at a time. Each owner record
+carries a `lock_format` number (the lock layout the writing release uses).
+Releases before 1.43.2 took the lock in two steps, creating the directory and
+then writing its owner, and a later release can replace that directory in the
+gap between them, so both runs enter. A command that finds the lock held by a
+live process whose owner record has no `lock_format`, or a different one,
+refuses at once and names that process instead of waiting for it. Every
+release before `lock_format` existed writes no number, so a holder from one of
+those is refused too, even though only releases before 1.43.2 can race. The
+check only sees a release that already holds the lock: two releases that start
+at the same instant can still meet in that gap. A dead holder from any release
+is recovered as usual. A waiver's `--dry-run` preview takes no lock.
 
 Before writing any output, `prepare-build` also requires distinct paths for the
 Build Packet, Build Context, Assembly Report, Doctor output, normalized Build

package/docs/effects.md

@@ -70,10 +70,12 @@ with one of these:
 | Token | Resolves to |
 | --- | --- |
 | `{target}` | The target the invocation names: the directory given to `--target`, or the Page Kit target repository the Build Packet points at. |
+| `{runtime}` | The funnel's runtime directory under `{target}`: `{target}/.campaign-runtime` for a Build Packet that records no `assembly.runtime_dir` (every packet before per-funnel records, and the first funnel of a project), else `{target}/<assembly.runtime_dir>`, which is `.campaign-runtime/funnels/<public_route_slug>` for each later funnel of the same project. The funnel's Build Context, Assembly Report, doctor output, theme output and intake inputs live here. |
 | `{cwd}` | The working directory the invocation runs in. |
 | `{spec}` | The CampaignSpec file the Build Packet names (`spec.local_path`), which need not live inside the target repository. |
 | `{home}` | Your machine: the home directory and the config root under it (`XDG_CONFIG_HOME` when set). |
 | `{packet}` | The Build Packet the invocation names (`--packet`), wherever it lives — it need not be the copy inside the target repository. |
+| `{packet-runtime}` | The same funnel runtime directory beside the Build Packet: `<packet directory>/.campaign-runtime`, or `<packet directory>/<assembly.runtime_dir>` when the packet records one. The committed QA verdict sidecar and the Run Records live here. |
 | `{lifecycle-journal}` | The command-lifecycle journal wherever it was selected for this invocation. |
 | `{proxy-base}` | The endpoint `--proxy-base` names, or the canonical NEXT endpoint when it does not. |
 | `{base-url}` | The campaign under test, as `--base-url` names it or as the packet derives it. |
@@ -81,8 +83,8 @@ with one of these:
 
 The tokens matter because effects are not all under the target. `install-skills`
 writes your **home** directory, not the campaign. `telemetry on` writes your
-**machine** config. `run-record` writes beside the **working directory**, not the
-target repo. A row that said "writes the target" would be wrong about all three.
+**machine** config. `run-record` writes beside the **Build Packet**
+(`{packet-runtime}`), not the target repo. A row that said "writes the target" would be wrong about all three.
 
 ### The Map Builder fetch
 
@@ -109,14 +111,14 @@ campaign. No store or Admin credential is used. The proxy's answer is an
 envelope whose `data` field holds the campaign. A failed read, an `ok: false`
 envelope, one with an `error` and no campaign, or several campaigns with no
 `campaign.ref_id` to pick one is recorded as `not_run` with its reason, never
-as a pass. `--no-live-refs` on `doctor` or `qa run` skips only this read and
+as a pass. `--no-live-refs` on `doctor`, `qa run` or `spec derive` skips only this read and
 records `not_run` with reason `disabled`; every other declared write and send
 is unchanged. Each form has its own row, including `doctor --write
 --no-live-refs` and `qa run --no-live-refs` with each `qa run` modifier.
 `doctor --no-write --no-live-refs` has the effects of the `doctor
 --no-live-refs` row.
 
-Only `doctor` and `qa run` make this read. The other commands that run doctor
+Only `doctor`, `qa run` and `spec derive` (see `spec derive` and the live campaign, below) make this read. The other commands that run doctor
 internally make no request and record `derived.live_campaign_refs` as
 `not_run` with reason `not_read`, with no warning: `start`, `prepare-build`
 and `build` (the intake alias for prepare-build + doctor), `theme waive`,
@@ -130,11 +132,13 @@ itself carries QA's own read).
 
 ### `record brief` and `record spec`
 
-**Saving brief answers.** `campaigns-os record brief --packet <packet>` saves Campaign Build Brief answers without re-running `start` or `prepare-build`. It writes the normalized brief under `{target}/.campaign-runtime/input/`, the Build Packet, the build context, the Assembly Report and the doctor-sidecar stale stamp, and sends nothing. It refuses a path that points at one of the files Campaigns OS writes itself, such as the normalized brief. Saving a brief whose content is unchanged keeps all stage evidence and statuses. Reformatting, reordering keys, writing a default value explicitly, or changing only `_meta` also keeps all stage evidence and statuses; the save may rewrite the brief files. When the presentation sections change, build, Polish and QA are owed again. When only `qa_policy` changes, QA alone is owed again. Setup and deploy records are kept. Each replaced record is kept under the stage's `history`; the last five superseded records per stage are kept, and history is never used as current proof.
+**Saving brief answers.** `campaigns-os record brief --packet <packet>` saves Campaign Build Brief answers without re-running `start` or `prepare-build`. It writes the normalized brief under the funnel's runtime directory (`{runtime}/input/`), the Build Packet, the build context, the Assembly Report and the doctor-sidecar stale stamp, and sends nothing. It refuses a path that points at one of the files Campaigns OS writes itself, such as the normalized brief. Saving a brief whose content is unchanged keeps all stage evidence and statuses. Reformatting, reordering keys, writing a default value explicitly, or changing only `_meta` also keeps all stage evidence and statuses; the save may rewrite the brief files. When the presentation sections change, build, Polish and QA are owed again. When only `qa_policy` changes, QA alone is owed again. Setup and deploy records are kept. Each replaced record is kept under the stage's `history`; the last five superseded records per stage are kept, and history is never used as current proof.
 
-**Binding a CampaignSpec change.** `campaigns-os record spec --packet <packet>` binds the new CampaignSpec content: it updates the build context and report identity, re-reads the brief file last saved (by intake or `record brief`), keeps waivers, warning accepts, the applied theme and deploy settings, and moves each superseded stage record into that stage's `history`. It writes the build context, the Assembly Report, the normalized brief and the doctor-sidecar stale stamp; it does not write the Build Packet, and it sends nothing. `spec derive` no longer rebinds identity; run `record spec` after it. A change to the set, order or routes of active pages still needs intake.
+**Binding a CampaignSpec change.** `campaigns-os record spec --packet <packet>` binds the new CampaignSpec content: it updates the build context and report identity, re-reads the brief file last saved (by intake or `record brief`), keeps waivers, warning accepts, the applied theme and deploy settings, and moves each superseded stage record into that stage's `history`. It writes the build context, the Assembly Report, the normalized brief and the doctor-sidecar stale stamp, and it sends nothing. It writes the Build Packet and the Design Source Package only when it binds a page change: a move of routes alone, or on a handed-off campaign (deploy or QA completed) a page added or removed; then a deploy recorded without a build fingerprint is owed again too when the set of built pages changes (a fingerprint-bound deploy is made owed by the next `record build`). A rerun after a run that stopped part way moves the Design Source Package references that run left behind. `spec derive` no longer rebinds identity; run `record spec` after it. A change to the order of active pages, or a page added or removed before handoff, still needs intake.
 
-Both rows are tier C, because a change makes recorded stages owed again, and each `--dry-run` form is tier none: it writes nothing and appends no lifecycle entry. A CampaignSpec change that was never saved with `record spec` is recorded by the next `record build`, `record polish` or QA run, with the same effect; `record build` then also marks Polish and QA owed again. An edit to the brief file is not read until it is saved with `record brief`: until then the build reads the saved brief, and doctor warns `build_brief.input_unsaved`. 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, archives the build, Polish and QA records it clears, and keeps the record that the inputs changed.
+Both `record` rows are tier C, because a change makes recorded stages owed again, and each `--dry-run` form is tier none: it writes nothing and appends no lifecycle entry. A CampaignSpec change that was never saved with `record spec` is recorded by the next `record build`, `record polish` or QA run, with the same effect; `record build` then also marks Polish and QA owed again. An edit to the brief file is not read until it is saved with `record brief`: until then the build reads the saved brief, and doctor warns `build_brief.input_unsaved`. 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, archives the build, Polish and QA records it clears, and keeps the record that the inputs changed.
+
+**`spec derive` and the live campaign.** Once the campaign is built (its `_site/<route>/` exists) and a public Campaigns API key resolves, `spec derive` makes the same read-only `GET {proxy-base}/api/campaign` doctor makes and refreshes the offer and package fields the spec mirrors from the Campaigns App; `--dry-run` makes it too, so the diff shows those fields. `--no-live-refs` sends nothing (its own row, tier B). `spec derive` and its `--dry-run` are tier A.
 
 ## How to read a row
 
@@ -164,8 +168,9 @@ flags that change what the invocation does to the world are listed once, in
 `vocabulary.effect_changing_flags`: `--apply`, `--browser`, `--built`, `--dry-run`,
 `--emit-packet`, `--example`, `--force`, `--from-store`, `--list`,
 `--no-live-refs`, `--no-post-verdict`, `--no-probe`, `--no-remit`, `--no-run-session`,
-`--no-write`, `--republish`, `--test-order`, `--write`, `--write-map`. Flags
-that only change the output shape (`--json`, `--report`) deliberately do not.
+`--no-write`, `--republish`, `--test-order`, `--vendor-beacons`, `--write`,
+`--write-map`. Flags that only change the output shape (`--json`, `--report`)
+deliberately do not.
 
 **"The help text" is every help block the CLI prints**, not one file's.
 `campaigns-os qa` prints its own from `src/qa-node.mjs`, and while the coverage
@@ -253,6 +258,9 @@ input resolution. They append no lifecycle entry. Accepted modes remain
 `accept`, `decline`, and `both` (case-insensitive); browser `--test-order` still
 takes precedence and does not require the legacy cart. API credentials are
 still checked only inside the legacy handler and failures there are journaled.
+A `qa run --vendor-beacons` value other than `live`, or `--vendor-beacons` on
+a run without browser `--test-order`, is likewise an argv-only refusal before
+QA input resolution.
 The nested run-record refusal scope in session closeout guards against future
 changes. No internal closeout can currently create a refusal before its
 invoking command journals.

package/docs/local-setup.md

@@ -3,7 +3,7 @@
 For a new campaign, create an empty working folder and run this from it:
 
 ```sh
-npm init -y && npm install --save-exact next-campaign-page-kit@0.3.0 && npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.61.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
+npm init -y && npm install --save-exact next-campaign-page-kit@0.3.0 && npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.63.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
 ```
 
 `npm init -y` gives the folder its own `package.json`. Without one, npm

package/docs/orientation-contract-reference.md

@@ -26,7 +26,7 @@ Ledger schema id: `campaigns-os-release-ledger/v1`
 Change policy version: `1.0.0`  
 Reason-code vocabulary version: `1.0.0`  
 Limits version: `1.0.0`  
-Supported surface at generation time: `1.61.0`
+Supported surface at generation time: `1.63.0`
 
 ## Forward compatibility
 

package/docs/polish-evidence.md

@@ -121,6 +121,8 @@ The size check covers `<img>` elements in the page, including those inside open
 
 **Readability.** `polish capture` also measures text contrast on every page under `_site/<slug>/` (up to 128 pages per run), at desktop (1440×1200) and mobile (390×844) widths, device pixel ratio 1, including campaigns whose pages are all template stock: the Polish route plan now covers the mapped pages plus every built page, while the page-load capture keeps its own page set. On a campaign with no mapped pages, `polish capture` measures readability, prints the page-load message as a warning, and exits successfully. The text it reads: purchase, accept and decline controls; submit buttons and submit-type inputs; SDK action controls; bundle cards (names, prices, badges and the card selected at load); order bumps; prices; checkout labels and placeholder hints; and other body text. Ratios follow WCAG 2.x and are compared unrounded: 4.5:1 for normal text, 3:1 for large text (at least 24 CSS px, or at least 18.66 CSS px at weight 700 or more; semibold does not qualify). Colours in any CSS Color 4 form the browser reports are converted to sRGB; values outside sRGB are clipped and marked. Backgrounds are composited through transparent layers. SVG text is measured with its fill colour, and placeholder hints with their own colour, size and weight. Gradients, background images, pseudo-element backgrounds, a `::first-line` or `::first-letter` style that changes the text's colour, background or opacity, overlapping positioned layers or images (and the shapes of an SVG drawing under its text), text clipped to a background, colours that cannot be read (including a text fill colour, and an SVG fill that is not a plain colour or is combined with a stroke), and controls marked disabled only by the SDK's `next-disabled` class produce a review result with a reason and a crop; so do opacity, filters, blend modes and masks on the text or on any element around it. `clip-path` is ignored. Disabled controls (`disabled` or `aria-disabled="true"`) are listed as excluded (inactive control) and are never accepted; `readonly` is not disabled. Polish measures the states present when the page loads — default, selected, active, and open panels — without clicking, scrolling or typing. Text that has not rendered, controls still loading, controls hidden at load, text supplied by CSS `content`, selection states and collapsed panels not present at load, text inside closed shadow roots or cross-origin frames, pages measured before the SDK, stylesheets or fonts were ready, and pages not captured are listed as unexercised. Overlapping layers are detected by box intersection: a layer the page paints over text in another way is not detected. A ratio under the requirement is a warning. Warnings never block Polish or change readiness. The probe reads the page without changing it, and adds at most about five minutes of work per run; pages it could not reach in that time are listed as unexercised. The stored measurements are re-derived on every read, and the page set, widths and campaign are checked against the current build; but the colours the browser reported are tamper-evident only, like other Polish captures. Readability and media weight results read as stale when the built output differs from the recorded build, even before a new `record build`.
 
+**Layout conventions.** In the same pass as readability, at the mobile width, `polish capture` checks two layout conventions from the `layout_conventions` block of `contracts/template-brand-contract.shared-commerce.v0.json`. Each reports as a `layout.conventions` row, keyed by convention, on every built page. The first, `floating_cta`, covers floating CTA containers. A floating CTA container is the nearest box around a visible link or button whose computed position is `fixed` or `sticky`. Headers, navigation, dialogs, the announcement bar, boxes that hold a visible form field, and boxes taller than half the viewport do not count. Such a container should hold its control alone: one link or button and no other visible text. A container with a second control, or with text outside its control (rendered or CSS-generated), is a `floating_cta_extra_content` warning that names the container, its controls and up to ten of the other text elements. The record keeps the container's box and each control's box. The second, `cta_label_size`, reads the readability record's own measurements. Every rendered, enabled text element of a purchase or accept control or a submit button (readability roles `add_to_cart`, `upsell_accept` and `submit_control`) should be at least 16 CSS px. A smaller one is a `cta_label_too_small` warning with its measured size. A CTA that is a plain link with no SDK action reads as body text in the readability record and is not checked for label size. A page that meets both conventions reads pass. Both warnings can be accepted with `checkpoint accept`; neither blocks Polish, changes readiness, or reads the merchant's copy. A readability record captured before this check holds no layout, and the check reads `not_captured_by_this_version` until the next `polish capture`.
+
 **Element parity.** For each page built from provided source HTML, `polish capture` reads the source HTML render and the built page that the package capture already makes, with the same browser at the same width, height and pixel ratio (desktop 1440×1200 and mobile 390×844). On both it reads every visible element that holds text: its box, its text, its computed font family, size, weight, style, line height, letter spacing and text transform, and its text and background colour. Elements are matched by their text: exact matches that occur once on each side first, then the nearest exact match after removing the page's median offset, then text split across child elements, then close wording (at least 60% of words shared). A design text of four or more characters is reported missing only when it appears nowhere in the built page's visible text; where part of the built page could not be read (very long text, closed components, frames), it is listed for review instead. Differences become warnings when they exceed: 6 px for horizontal position, width and height, and for the vertical gap to the previous matched element (so one inserted band reports once, where the layout changed); 0.6 px font size; 2 px line height; 0.2 px letter spacing; 3 of 255 in any colour channel; any change of font family, weight, style or text transform. A web font that loaded for the source but not for the build is a warning even when the CSS names the same family. The font each glyph was actually drawn with is not read, and the handoff says so. Colour that cannot be measured on either side is listed for review. A source with no text, a source or build that could not be rendered or was not ready in time, a width or pixel-ratio mismatch (never resized), a source file that differs from the one recorded at intake, pages over the run's limits (1 500 elements per page, 32 pages, 200 font faces, about one minute of probing), and pages with unread parts are listed as unexercised or for review, never as a match. The probe's time counts against the package capture's own time budget. Both measurements are saved as local, git-ignored files, hashed and bound to the record. That makes an edit to part of the evidence detectable, but a process that rewrites the files and both records consistently is not detected. The source is measured again on every capture, so changed stylesheets or fonts are always seen; an unchanged source produces the same saved file. Warnings can be accepted with `checkpoint accept` and lapse when the measured values change; they never block Polish or change readiness. The comparison uses the HTML export as the design; a design file recorded for the page is not read by this version.
 
 ### Package captures and design comparison

package/docs/progress-snapshots.md

@@ -65,10 +65,13 @@ rename; a live process is never evicted. A lock directory with no owner record
 a second. If one is found, or if recovery itself is interrupted, capture fails
 closed and the warning names the affected `.allocation-lock` directory: stop
 all Campaigns OS writers for that target, then remove that directory before
-retrying `next`. A file or other non-lock entry at the lock path is named in
-the warning and never removed: move it out of the way. Do not remove a lock
-while a writer is active. Do not run an
-older Campaigns OS release against the same target at the same time.
+retrying `next`. A file, an unreadable directory or other non-lock entry at
+the lock path is named in the warning and never removed: move it out of the
+way. Do not remove a lock while a writer is active. Run one Campaigns OS
+release against a target at a time: a lock held by a live process of another
+release (its owner record has no `lock_format`, or a different one) is refused
+at once and the warning names that process. Two releases that start at the
+same instant are not detected.
 
 An unchanged projection reuses its ID, timestamp and sequence. Identity
 changes start a new stream. Each local scope retains at most 32 snapshots and

package/docs/qa-and-test-orders.md

@@ -134,6 +134,21 @@ waiver commands keep them strict. Progress
 snapshots record a carried-forward gate as `not_applicable`, because their
 schema has no carried-forward state.
 
+### Polish advisory for a page-only change
+
+After launch, a change that touches only some pages' HTML and leaves checkout,
+commerce markup, routes, scripts and the campaign's Page Kit config alone is a
+page-only change ([what a change owes](campaigns-os-build-flow.md#what-a-change-owes)).
+On any target, its stale Polish evidence (`polish.evidence_missing` after
+`record build`, `polish.stale`, `polish.output_drift`, and the
+`polish.hidden_eager_media.capture_stale` checkpoint) is carried forward with
+the `page_only_change` policy. Doctor reports it as a warning starting
+"Advisory for a page-only change"; `next` and `record deploy` move past Polish;
+QA records it as a `skipped` row, so it does not hold the verdict to
+`ready_with_exceptions`. A Polish recorded as blocked, incomplete or
+self-certified stays blocking, and so does a stage a brief or spec change
+requires.
+
 ## Resolve
 
 Use resolve before a full run:
@@ -381,6 +396,40 @@ default currency. The persisted verdict redacts every URL query, so the
 currency is recorded as `evidence.currency` on the entry page's
 `http:<page_id>` assertion; an entry URL that does not parse gets no currency,
 and its row records `evidence.currency_not_applied` with the reason instead.
+
+The run also checks that the currency took. Campaign Cart falls back to the
+campaign's default currency when the requested one is not available, so a page
+can load with `?currency=GBP` and still take a USD order:
+
+- Each test order gets a `browser-order-currency:<path>` row comparing the
+  created order's `currency` (read from the order API response) with the run
+  currency. An order in any other currency fails as a blocker, and so does a
+  verified order whose currency was not recorded. The row's evidence is
+  `{ requested, order_currency }`.
+- Automatic commercial parity (below) asks the calculate endpoint for expected
+  totals in the run currency, in place of the Map's `campaign.currency`. When
+  the endpoint answers in another currency, the campaign does not price in the
+  run currency: a `commercial-currency:<RUN>:<ANSWERED>` row (family `pricing`)
+  fails as a blocker, and the commercial report lists the
+  `calculate_currency_mismatch` issue, so its status reads `incomplete`. The
+  row's id names the answered code upper-cased, one row per answered currency,
+  and it is written even when the verdict's assertion budget is used up.
+- Commercial parity reads prices from each page's source HTML, where a bound
+  price such as `data-next-display="bundle.main.price"` holds the authored
+  fallback text in the Map's `campaign.currency` (Campaign Cart replaces it at
+  runtime). When the run currency is not the Map's `campaign.currency`, those
+  price and recurring-price claims are not compared with the run-currency
+  totals: they count as unresolved, and the commercial report records
+  `unresolved_money_claims_reason: "static_source_not_in_run_currency"`. A
+  correctly built multi-currency page gets no `price-claim-mismatch` warning,
+  and the commercial status reads `incomplete` instead of `pass`. With
+  `--currency` set to the Map's own currency, the claims are compared as
+  before.
+
+Either blocker makes the verdict `blocked` and the command exit `4`. Without
+`--currency` neither row is written and expected totals use
+`campaign.currency`, as before.
+
 `--currency` sets the currency only. Test orders still ship to the address the
 `--test-*` flags give, a US address by default (see
 [Test customer and shipping address](#test-customer-and-shipping-address)). A
@@ -390,6 +439,25 @@ checked: a currency such as EUR covers many countries, so an explicit
 `--test-country` is taken as meant. `qa run --site` takes `--currency` the same
 way and tags the slug's entry page.
 
+`--page <page_id>` (repeatable) checks only the named pages. It pays the QA a
+page-only change owes: `doctor --ci` and `next` name the changed pages by
+their route ids (`upsell1` for `upsell1/index.html`), and the CampaignSpec page
+id is accepted too. It needs `--packet`, places no test orders (it refuses
+`--test-order` and `--legacy-api-test-order` other than `off`, and
+`--vendor-beacons`), and refuses before checking anything when the
+output on disk is not the recorded build (run `record build` first), when the
+change since the build QA reviewed touches commerce, when a changed page is
+left out, when the QA it would extend did not complete (a blocked full run
+owes a full run), or when QA's inputs (the brief's `qa_policy` and the
+CampaignSpec) changed or cannot be confirmed current. Every other page gets a
+`page-scope:<page_id>` row, `skipped` with `outside_page_scope`. The QA stage
+it records carries `evidence.page_scope` (`pages`, `owed_pages`,
+`base_build_fingerprint`) and keeps the `purchase_proof` of the full run it
+extends. Its `evidence.qc_results` holds the rows for the scoped pages only,
+so until the next full run the QC handoff coverage reports the earlier full
+run's other QA checks (order paths and tracking among them) as not captured.
+QA already recorded in full for the current build is re-run without `--page`.
+
 ### Automatic commercial parity
 
 When the CampaignSpec has enabled pages with package rows, the same `qa run`
@@ -440,7 +508,11 @@ readback consumes. It is written for every finalized disposition, blocked
 included: the sidecar records what QA concluded, it is not a pass mark. A run
 that dies before verdict finalization or fails local validation never touches
 an existing sidecar. Packet-less runs (`--site`, raw map-id) have no packet
-home and write no sidecar.
+home and write no sidecar. For a project's second and later funnels the sidecar
+is `.campaign-runtime/funnels/<route>/qa-verdict.json` beside that funnel's
+packet, the runtime directory its `assembly.runtime_dir` names (see
+[Several funnels in one project](build-packet.md#several-funnels-in-one-project));
+`qa promote` and `qa publish` read and write the same file.
 
 The sidecar is an allowlist **projection** of the full verdict, same schema
 (`1.0`), stamped with its own `generated_at` at promotion time. Full verdicts
@@ -1337,6 +1409,80 @@ controls on an ordinary or unknown page remain blockers; they are not treated
 as evidence that a receipt was reached. Cross-origin handoffs count as terminal
 navigation, but not as Campaigns OS receipt rendering or persisted-receipt proof.
 
+### Analytics vendor beacons (`--vendor-beacons live`)
+
+A test order is a real purchase on the page, so the page reports it to every
+analytics vendor the campaign loads. To keep test orders out of vendor data, a
+`qa run --test-order` run answers the vendors' beacon requests locally. A
+beacon is the request a vendor script sends to report a page view or an event,
+as opposed to the loader, the request that downloads the vendor script. Every
+browser context the run opens (page checks, analytics capture and the orders)
+answers a request to a listed beacon endpoint with an empty `204` response, so
+nothing reaches the vendor. Those contexts also block service workers, because
+a request a page's service worker makes on the page's behalf would bypass the
+local answer. Loader scripts load normally: a blocked loader would leave the
+vendor script undefined, and the page would send nothing to observe.
+
+| Vendor | Beacon endpoints answered locally | Loaders that still load |
+|---|---|---|
+| GA4 (`ga4`) | `*.google-analytics.com/g/…`, `analytics.google.com/g/…`, `stats.g.doubleclick.net/g/…`, `www.google.com/g/collect` | `www.googletagmanager.com/gtag/js` |
+| Meta (`meta`) | `www.facebook.com/tr`, `www.facebook.com/privacy_sandbox/…` | `connect.facebook.net` |
+| TikTok (`tiktok`) | `analytics.tiktok.com/api/v2/…`, `analytics-ipv6.tiktokw.us` | `analytics.tiktok.com/i18n/pixel/…` |
+| Snap (`snap`) | `tr.snapchat.com`, `tr6.snapchat.com`, `tr-shadow.snapchat.com` | `sc-static.net` |
+| Pinterest (`pinterest`) | `ct.pinterest.com/v3/…`, `/user/…`, `/stats/…` | `s.pinimg.com`, `ct.pinterest.com/static/…` and `/ct.html` |
+| Taboola (`taboola`) | `trc.taboola.com` | `cdn.taboola.com` |
+| Triple Whale (`triplewhale`) | `api.config-security.com` (all but `/first`), `api.whaledb.io/keep-alive` | `api.config-security.com/first`, `conf.config-security.com` |
+| AppLovin Axon (`axon`) | `b.applovin.com/v1/pixel` | `s.axon.ai`, `c.albss.com`, `res4.applovin.com` |
+
+Each endpoint was read from the vendor's public loader script or public
+documentation; the source is recorded per vendor in
+`src/qa-vendor-endpoints.mjs`. Two vendor keys are not intercepted, and the
+verdict names them:
+
+- `northbeam`: its beacon host could not be confirmed (the loader is per client
+  and the public docs name no beacon host), so Northbeam still receives what
+  the page sends it, test purchases included.
+- `gtm`: Google Tag Manager sends nothing of its own. The tags it loads send to
+  their own vendors, held back only when that vendor is in the table. A GTM tag
+  for any other vendor (Google Ads, an affiliate pixel) still sends.
+
+`qa parity` orders are not intercepted.
+
+Every request to a listed endpoint is recorded, and the verdict carries one
+informational row, `browser-test-order:vendor-beacons` (status `pass`, severity
+`info`). Its `evidence` gives, per vendor seen, the request count, whether one
+of the requests named a purchase event (`purchase_seen`; `null` for Axon, whose
+event field could not be confirmed), and the ids, event names and endpoints
+(origin and path only, never a query string); `configured_not_seen` lists the
+vendors the CampaignSpec analytics block declares that sent nothing to a listed
+endpoint; `configured_not_observable` lists the declared vendors with no listed
+endpoint (GTM, Northbeam), which the row cannot see either way; and
+`not_intercepted` lists the two vendors above with the reason for each (with
+`live`, every vendor). The row is evidence only. A
+request the page sent proves the page sent it, not that the vendor received it,
+so it never counts as vendor purchase proof and never blocks the run. Purchase
+proof stays with `analytics-correctness:purchase-fires` (the dataLayer
+purchase, a Meta Purchase pixel request, or a GA4 purchase hit); with
+interception on, the Meta and GA4 requests behind it are still observed, just
+answered locally. The same requests feed the analytics inventory and parity
+legs as tag fires.
+
+To send the beacons to the vendors, pass `--vendor-beacons live`. `live` is
+the only value; any other value is refused before anything runs, and so is the
+flag on a run without `--test-order`, where it would change nothing. The row
+then records the requests as sent.
+
+```bash
+npm run campaigns-os -- qa run \
+  --packet campaign-runtime.build.json \
+  --test-order common \
+  --vendor-beacons live
+```
+
+Do not hold beacons back with `?ignore=true` on the campaign URL: from SDK
+0.4.42 it stops the SDK's `dl_*` events entirely, so the run would prove no
+purchase event at all.
+
 ### Purchase-proof coverage (`--test-order off` is a diagnostic)
 
 A QA run finalizes a verdict and records a terminal stage status whether or not

package/docs/readback.md

@@ -295,6 +295,20 @@ carries no parseable value — the readback does not choose. It names the
 candidates on stderr, says `--packet` is required, and exits `2`. No JSON object
 is emitted in that case.
 
+**Freshness chooses among runs of one funnel, never among funnels.** A project
+that holds several funnels has one packet per funnel
+(`campaign-runtime-<route>.build.json` beside the default; see
+[Several funnels in one project](build-packet.md#several-funnels-in-one-project)).
+When the valid candidates name more than one `campaign.public_route_slug`, the
+readback refuses the same way, naming each packet with its route, and exits
+`2`. Pass `--packet` to project one funnel. The doctor output, Build Context,
+Assembly Report, QA verdict and findings export rows then read from the runtime
+directory that packet records (`assembly.runtime_dir`), or from
+`.campaign-runtime/` when it records none. A packet whose `assembly.runtime_dir`
+is not its own funnel's directory is refused with exit `2`, since the readback
+cannot tell whose records to show. An explicit `--doctor`, `--context`,
+`--report`, `--qa-verdict` or `--findings` path still wins.
+
 Values are compared at **microsecond precision** — the precision Python's
 `datetime.fromisoformat` keeps, and the precision the Python readback this
 command ports compared at; a seventh or later fractional digit is truncated, not
@@ -495,11 +509,31 @@ If the built page map cannot be resolved (for example, output contains assets
 but no HTML), page changes are unknown with `build_output_pages_unresolved`;
 stage bindings still follow the fingerprint comparison.
 
+`changes.kind` classifies this drift (`none`, `page_only`,
+`commerce_affecting` or `unknown`) and `changes.reasons` lists why it counts as
+commerce, each `{ "code", "path"? }`. The rule is in
+[what a change owes](campaigns-os-build-flow.md#what-a-change-owes).
+
 The assembly baseline is explicit because it need not equal an older stage's
-binding. If a later `record build` replaced that manifest, readback can still
-report older Polish/QA bindings as owed, but cannot reconstruct which pages
-changed from those older builds. An empty **known** list then means only that
-no files differ from the retained assembly manifest. If recording removed a
+binding. If a later `record build` replaced that manifest, `changes` can be
+empty while older Polish/QA bindings are still owed. An empty **known** list then means only that
+no files differ from the retained assembly manifest. The pages changed since
+the build a stage reviewed are on that stage instead. An owed stage carries:
+
+- `change`: `{ "kind", "since_build_fingerprint", "changed_pages",
+  "unmapped_files", "reasons" }`, read from the rebuilds `record build` kept in
+  `stages.assembly.build_changes` plus the drift on disk. `kind` is `unknown`
+  when that history does not reach the reviewed build (reason
+  `change_history_unavailable`) or the drift cannot be read. `null` on a stage
+  that is not owed.
+- Polish only, `advisory`: `true` when the change is `page_only` and no brief or
+  spec change requires Polish. Advisory Polish is reported; `next`, `doctor
+  --ci` and the QA gate do not require it.
+- QA only, `scope` and `owed_pages`: `pages` with the changed pages when the
+  change is `page_only` (`qa run --page` pays it), `full` otherwise, `null`
+  when QA is not owed.
+
+If recording removed a
 stage binding entirely, that stage reads unknown unless its recorded status is
 `required`, which reports owed. `current` is a build-binding
 assessment only; input currency, stage completion, waivers and verdicts remain
@@ -548,7 +582,8 @@ failure lines up with a completed stage. This too is the readback's own layer.
 4. **`divergences` is empty.**
 5. **`doctor.error_count` is zero.**
 6. **Neither `evidence_debt.polish.status` nor `evidence_debt.qa.status` is
-   `owed`.** Built output that moved since recorded evidence cannot read clean.
+   `owed`**, except Polish marked `advisory` for a page-only change. Built
+   output that moved since recorded evidence cannot read clean.
    An `unknown` status does not independently make this integrity flag false;
    it remains unknown, never a claim that no evidence is owed. Callers must
    inspect `evidence_debt` even when `clean` is true.