@nextcommerce/campaigns-os 1.53.0 → 1.55.0

package/contracts/supported-surface.json

@@ -1,6 +1,6 @@
 {
   "_note": "The downstream contract manifest. Everything listed here is SUPPORTED SURFACE: consumers (campaigns-agent, campaign-builder, the private ops repo, page-kit campaign repos) may depend on it, and changing it is a deliberate act — hashed entries require a surface_version bump in the same change (check-supported-surface.mjs --base, mirroring the skills.json bump gate), named entries must keep existing at their path, cli_commands must keep resolving in the CLI dispatch, package_exports must stay exported, and every entry must ship in the npm pack (files[] coverage). Anything NOT listed here — src/** internals, scripts/** checkers, examples/**, prompts/**, contracts/** other than this file and the entries named[] below (the orientation contract, the release ledger, and the consumer-facing orientation fixtures) — is implementation: consumers may read it for context but must not build on it, and it can change without notice. Rationale and the compatibility promise: docs/supported-surface.md.",
-  "surface_version": "1.53.0",
+  "surface_version": "1.55.0",
   "package_exports": [
     "./commercial-journey",
     "./commercial-parity",
@@ -60,7 +60,7 @@
       "sha256": "65bcd8b5f41f1e9ecfc36f3b8838cd4ed531bd74c5a318ee5147131f6c9b4a1c"
     },
     "schemas/campaign-runtime-assembly-report.v0.schema.json": {
-      "sha256": "8a0d37be9a4bb34d0ed073c9d6bfa4406a7b499c801c34c5fbb26646e2665c0b"
+      "sha256": "625a6f2ed6bee726f9cddad750e64a54a7e03744c777f5a70afe4a39afdd9848"
     },
     "schemas/campaign-runtime-build-context.v0.schema.json": {
       "sha256": "f310c1b7844d9b1994864d15858ff0c6f17efc1e5285ba193d181bdb2dd4be2f"
@@ -96,7 +96,7 @@
       "sha256": "d7521fe0ab4deb62485f92286cb890ee548ea290793a6ce7444ecc42ba336d49"
     },
     "schemas/campaigns-os-run-record.v0.schema.json": {
-      "sha256": "00dc9bcec79c12ea22a27f636188bcc33c6811df2d646ac7b49d4cc076e97355"
+      "sha256": "390cbc9debacfbfb17d999961baa041a2138fa20a116ec463fbbefbbb05f622d"
     },
     "schemas/campaigns-os-runtime-recipe.v1.schema.json": {
       "sha256": "f8a2ab5eadbb71fb6d5653b670ee71e4471c3df74dd04000d3dbd3d9ae9e71fc"
@@ -120,7 +120,7 @@
       "sha256": "dfc9abed38d456969e47a21f606d308a03bdf036f3466f7d6e47a602747dacf4"
     },
     "contracts/effects.v1.json": {
-      "sha256": "8282f7ffe91aaf12c4b79e4431b5ddc35cce82e42f1746d4a0ea44f54bd7fb8e"
+      "sha256": "10a9020aaba5780e2ee2f3ddf6d81127047f6caec0de774c48540d9b664e0a6a"
     },
     "schemas/campaigns-os-effects.v1.schema.json": {
       "sha256": "3eadd22169ab98bc7c2f682af2751267605170581182158d96be035b0cfe44dc"

package/contracts/template-brand-contract.shared-commerce.v0.json

@@ -55,7 +55,7 @@
       },
       "asset_pin": {
         "repo": "NextCommerceCo/campaign-cart-starter-templates",
-        "sha": "2c618942391ae398fb4812f36fc93e6632054874",
+        "sha": "783329017c6994a94d11e46580c33bd052aabdb0",
         "path": "src/<family>/assets/<asset>",
         "note": "asset_sha256 is the sha256 of each shipped starter asset at this commit (the commerce-surface-catalog _synced_from_sha pin; the bytes are identical across every family). A served asset whose bytes hash to the shipped value is the untouched starter asset and counts as residue even though its markup names no method; different bytes mean it was edited in place. check-template-doctrine verifies these hashes against the pinned checkout."
       },

package/docs/brand-theme-bridge.md

@@ -22,6 +22,16 @@ It compares source tokens against known `figma-sections-export` scaffold
 defaults, maps real brand values onto a local versioned next-core target-token
 contract, and writes evidence into a theme report.
 
+A rule whose selector subject has a whole sale, discount, badge, rating, star,
+strike, border or announcement name part does not supply primary or CTA unless
+that subject also has a brand, primary, cta, button or btn part, or is a `button`
+element or a submit input. In comma lists,
+the other selectors still count. Primary keeps the header, navigation, brand
+and hero matching used on main, including element selectors and ancestors;
+button backgrounds keep the same CTA matching, including cart, buy, order and
+submit names and IDs. If no CTA token or button background exists, the CTA uses
+the accent fallback and the warning asks the operator to confirm it.
+
 `campaigns-os theme generate` writes:
 
 ```text

package/docs/build-packet.md

@@ -827,12 +827,19 @@ Blockers (not waivable — the markup provably does not do what it says):
 - `CHECKOUT_NOT_FORM` — `data-next-checkout` on an element that is not `<form>`.
 - `WRONG_FIELD_NAME` — `data-next-checkout-field` with a value the SDK does not
   map. The set is vendored from the SDK at a named tag
-  (`src/sdk-attribute-index.mjs`, currently v0.4.38: `email`, `fname`, `lname`,
+  (`src/sdk-attribute-index.mjs`, currently v0.4.41: `email`, `fname`, `lname`,
   `phone`, `address1`, `address2`, `city`, `province`, `postal`, `country`,
   `payment-method`, `accepts_marketing`, `cc-number`, `cc-month`, `cc-year`,
   `exp-month`, `exp-year`, `cvv`, the legacy `card-*` spellings, and any
   `billing-` prefixed name). The message names the SDK spelling for the usual
-  offenders (`firstName` → `fname`, `zip` → `postal`).
+  offenders (`firstName` → `fname`, `zip` → `postal`). Three names depend on
+  the page's SDK version: `first_name` and `last_name` are mapped from v0.4.39
+  and `phone_number` from v0.4.41. The version is the page's own exact loader
+  pin, else the campaign's `sdk_version` in `_data/campaigns.json`. Below the
+  name's version, or when neither gives an exact released version, the name
+  blocks, and the message names `fname`, `lname` or `phone`, which every
+  version maps. Each finding carries `sdk_version` and `sdk_version_source`
+  (`loader` or `campaigns_json`) in its detail.
 - `MISSING_SELECTOR_ID_MATCH` — an `add-to-cart` button whose
   `data-next-selector-id` names no selector on the page (an element that is a
   bundle, package, cart or upsell selector; another element echoing the id
@@ -1246,25 +1253,39 @@ coverage blocks source readiness.
 
 ## Adapter And Proof Fields
 
-Fresh packets now include `source_html.adapter_contract`. Build Context and
-Assembly Report carry the same values as `adapter_decisions`, and build agents
-should update the report as they complete work.
+Fresh packets include `source_html.adapter_contract`. Build Context and
+Assembly Report carry the same values as `adapter_decisions`. After building,
+record the true scalar decisions with `record build --adapter-decision
+<key>=<value>[,<key>=<value>...]` (one flag, comma-separated `key=value`
+pairs). For example, set `raw_html_conversion_status=completed` after source
+HTML conversion, or `not_required` when there is no source HTML to convert.
+A repeated `--adapter-decision` flag keeps only the last list. The command
+writes the Assembly Report only. Doctor's adapter gates and leftover-wrapper
+check read the effective decisions in report → Build Context → packet order;
+doctor still validates each copy's shape separately. Source preparation reads
+the packet's `wrapper_policy`, which is selected at intake with
+`prepare-build --wrapper-policy` or the source-html manifest's `wrapper_policy`
+option. The record flag refuses that key, an unknown key, or a value outside
+the allowed values below. The object-valued
+`template_files_copied` has no flag: its `status`, `required_groups`, `groups`,
+and `paths` remain required proof in the report and keep their existing doctor
+checks.
 
 Required adapter decisions:
 
-| Field | Purpose |
-| --- | --- |
-| `raw_html_conversion_status` | Whether prepared HTML has been converted into page-kit-ready source. |
-| `source_asset_strategy` | How images/fonts/CSS/JS are moved and referenced. Prefer `pagekit_campaign_asset_root`. |
-| `commerce_shell_adoption` | Whether checkout/upsell/downsell/receipt use a template-clone-first SDK surface. |
-| `route_rewrite_policy` | How page links, CTAs, and SDK routing values were rewritten from CampaignSpec routes. |
-| `template_files_copied` | Whether the selected template family was copied/verified as one atomic page-kit slice. |
-| `config_script_strategy` | How campaign config scripts are loaded. |
-| `wrapper_policy` | Whether document wrappers are stripped, preserved, or not required. |
-| `frontmatter_policy` | How Page Kit YAML frontmatter is created or preserved. |
-| `script_style_reference_policy` | How scripts/styles move into frontmatter, campaign assets, inline blocks, or passthrough. |
-| `cta_rewrite_policy` | How CTA destinations are rewritten from CampaignSpec routes. |
-| `layout_choice` | Which Page Kit layout strategy wraps the prepared source. |
+| Field | Purpose | `record build` allowed values |
+| --- | --- | --- |
+| `raw_html_conversion_status` | Whether prepared HTML has been converted into page-kit-ready source. | `pending`, `in_progress`, `completed`, `not_required`, `blocked` |
+| `source_asset_strategy` | How images/fonts/CSS/JS are moved and referenced. | `pagekit_campaign_asset_root`, `external_cdn`, `raw_passthrough`, `not_applicable`, `unknown` |
+| `commerce_shell_adoption` | Whether checkout/upsell/downsell/receipt use a template-clone-first SDK surface. | `not_required`, `template_clone_first_required`, `template_clone_first_verified`, `sdk_surfaces_preserved`, `custom_html_experimental` |
+| `route_rewrite_policy` | How page links, CTAs, and SDK routing values were rewritten from CampaignSpec routes. | `campaignspec_routes_via_campaign_link`, `pagekit_public_routes`, `raw_passthrough`, `not_applicable`, `unknown` |
+| `template_files_copied` | Whether the selected template family was copied/verified as one atomic page-kit slice. | Object-valued proof; no flag |
+| `config_script_strategy` | How campaign config scripts are loaded. | `campaign_asset`, `frontmatter_script`, `inline`, `not_required`, `unknown` |
+| `wrapper_policy` | Whether document wrappers are stripped, preserved, or not required. | Intake only: `strip_document_wrappers`, `preserve_document_wrappers`, `not_required`, `unknown` |
+| `frontmatter_policy` | How Page Kit YAML frontmatter is created or preserved. | `pagekit_yaml_frontmatter`, `raw_passthrough`, `not_required`, `unknown` |
+| `script_style_reference_policy` | How scripts/styles move into frontmatter, campaign assets, inline blocks, or passthrough. | `frontmatter_or_campaign_asset`, `frontmatter`, `campaign_asset`, `inline`, `raw_passthrough`, `not_required`, `unknown` |
+| `cta_rewrite_policy` | How CTA destinations are rewritten from CampaignSpec routes. | `campaignspec_routes_via_campaign_link`, `pagekit_public_routes`, `raw_passthrough`, `not_applicable`, `unknown` |
+| `layout_choice` | Which Page Kit layout strategy wraps the prepared source. | `campaign_layout`, `page_layout`, `raw_passthrough`, `not_applicable`, `unknown` |
 
 Fresh build context also includes `source.asset_crawl`
 (`source-asset-crawl/v0`). `prepare-build` scans the source HTML files and
@@ -1730,10 +1751,10 @@ hand-editing `.campaign-runtime/` JSON:
 | Command | Writes | Refused (nothing written) when |
 |---|---|---|
 | `campaigns-os record setup --packet <p>` | Build Context `scaffold.required=false` (`handoff_skill` next-campaigns-build) and `stages.setup` completed | the campaign output directory (`assembly.output_dir`) does not exist, or there is no Build Context or Assembly Report |
-| `campaigns-os record build --packet <p> [--build-environment <development\|production>]` | `stages.assembly` completed with `build_fingerprint` = doctor's `derived.build_output_fingerprint.value`, `source_package_material_fingerprint` = the report's Design Source Package material fingerprint when present, `evidence.build_environment` = the `--build-environment` value when given (kept from the last record otherwise), and `stages.polish` reset to `required` (`required_by` build, `required_for` qa) unless its evidence is bound to this exact output | doctor cannot compute the fingerprint (no `_site/<public_route_slug>/`), setup is still required, or `stages.setup` is not terminal |
+| `campaigns-os record build --packet <p> [--build-environment <development\|production>] [--adapter-decision <key>=<value>[,<key>=<value>...]]` | `stages.assembly` completed with `build_fingerprint` = doctor's `derived.build_output_fingerprint.value`, `source_package_material_fingerprint` = the report's Design Source Package material fingerprint when present, `evidence.build_environment` = the `--build-environment` value when given (kept from the last record otherwise), and the specified scalar `report.adapter_decisions`; all recordable decisions go in one comma-separated flag (a repeated flag keeps only the last list); `wrapper_policy` stays an intake choice. `stages.polish` resets to `required` (`required_by` build, `required_for` qa) unless its evidence is bound to this exact output; a completed `stages.deploy` whose `source_build_fingerprint` names other output resets to `required` the same way, without the old probe's `outputs` and `evidence`, and its prior record is kept in `stages.deploy.history` (a deploy with no `source_build_fingerprint`, recorded before deploy stamped it, is kept) | doctor cannot compute the fingerprint (no `_site/<public_route_slug>/`), setup is still required, `stages.setup` is not terminal, or an adapter decision key/value is invalid |
 | `campaigns-os record polish --packet <p> --evidence <file>` | `stages.polish` from the file (`docs/polish-evidence.md` §7: completed, blocked or skipped), bound to doctor's current fingerprint; `report.theme.repair_loop_defect` when the file sets it | build is not recorded for the current output, the file has a shape error (named by field), or, for a completed status, the polish gate doctor evaluates would not pass on the result |
 | `campaigns-os record theme --packet <p>` | `report.theme`: status `applied`, `load_order` `after-next-core`, `css_path`, `commerce_pages` and per-page evidence read from each built commerce page's stylesheet links; any earlier theme waiver is cleared | build is not recorded for the current output, the campaign ships no commerce pages, a built commerce page that loads `next-core.css` does not load `brand-theme.css` (or `checkout-brand.css`) after it or links one missing from the built output, or no built commerce page loads `next-core.css` |
-| `campaigns-os record deploy --packet <p> --base-url <url>` | the packet's `deploy.preview_url` and `stages.deploy` completed with the URL in `outputs` and one evidence line per built page that answered (each page is requested under the URL first) | the packet is not `local-serve`, the URL is not a loopback origin naming the campaign's route root, a built page does not answer 2xx, polish is not recorded, the built output changed since build was recorded, or the theme gate is blocked |
+| `campaigns-os record deploy --packet <p> --base-url <url>` | the packet's `deploy.preview_url` and `stages.deploy` completed with the URL in `outputs`, one evidence line per built page that answered (each page is requested under the URL first), and `source_build_fingerprint` = the recorded `stages.assembly.build_fingerprint` it probed, so a later `record build` of different output makes deploy owed again and `next` routes back to `record deploy` before QA; a byte-identical rebuild keeps it current | the packet is not `local-serve`, the URL is not a loopback origin naming the campaign's route root, a built page does not answer 2xx, polish is not recorded, the built output changed since build was recorded, or the theme gate is blocked |
 
 Each command also refuses a stage `next` has not reached: while doctor's
 prepare-build gate is set (`next` answers prepare-build) or while an earlier
@@ -1766,7 +1787,9 @@ check exits non-zero with the problems listed, one per line; a value outside a
 schema enum (for example an `adapter_decisions` policy) is listed with the
 values the schema allows and the value it got. Re-run `record
 build` after every page-kit build; a rebuild that changes the output needs
-`polish capture` and `record polish` again.
+`polish capture` and `record polish` again. After deploy is recorded for the
+rebuilt output, `next` asks for QA again if the last QA record names the
+previous build fingerprint, even while its stage status still says completed.
 
 Stage order: `setup → build → polish → deploy → qa`. The picker walks this list and returns the first stage whose recorded status isn't terminal (`completed`, `completed_with_warnings`, `skipped`). During Polish, install the package-owned browser first, then run `campaigns-os polish capture` against the served current build before recording a terminal `stages.polish.status` or proceeding to deploy/QA; the producer attaches package-owned `visual_review.page_load` evidence and never marks the stage complete itself.
 
@@ -1801,7 +1824,7 @@ Result shape (with `--json`):
 Terminal states:
 
 - **`stage: "doctor-blocked"`** — doctor returned errors. Resolve the blockers and re-run `campaigns-os doctor` to confirm before calling `next` again.
-- **`stage: "done"`** — every stage is in a terminal status. Pipeline is complete. To re-run a specific stage, set its status back to `"pending"` in the assembly report and call `next` again.
+- **`stage: "done"`** — every stage is in a terminal status. Pipeline is complete. To repeat build work, do the work and use `record build`; it makes downstream stages owed as needed. Use `record setup` or `record polish` after repeating those stages, and `qa run` for QA. `record deploy` records a local-serve target; for a hosted deploy, record the URL and stage outcome as the deploy prompt describes. Then call `next` again.
 - **`stage_blocked: true`** — the picker returned a stage whose recorded status is `blocked`. Don't run the prompt as-is; clear the blocker first.
 
 The legacy form `campaigns-os next <stage>` (e.g. `next build`) still works and is the way to force a specific stage when you want to override the picker.

package/docs/campaign-standardization-report.md

@@ -170,12 +170,34 @@ version discovery), `checkout_fields` (every
 script evidence, and `proof_state`), `runtime_contract`, `findings`, and
 `remediation`.
 
+Three names in the field contract depend on the SDK version
+(`version_gated_aliases`): `first_name` and `last_name` from 0.4.39 and
+`phone_number` from 0.4.41. Each is `supported` only when the binding's SDK
+version is an exact release at or after that version; otherwise it is
+classified as on an earlier SDK (`first_name` and `last_name` as stale aliases,
+`phone_number` as unknown). Each binding records the `sdk_version` it was
+judged against and its `sdk_version_source`: `loader` (the file's own exact
+loader pin), `campaign` (for a file with no loader of its own, the lowest of
+the root's exact loader pins and its bundled dependency's floor: an exact pin,
+or `^`, `~` or `>=` on a released version; any other range leaves the version
+unknown), or
+`campaigns_json` (a Page Kit campaign's `sdk_version`; a shared file takes the
+lowest across campaigns). An unpinned loader or a missing pin leaves
+`sdk_version` null, judged as an earlier SDK, because `fname`, `lname` and
+`phone` work on every version.
+
 `sdk_loader.references` records pinned and unpinned loader refs alike
 (`version` is null for `@latest`/branch/commit pins, which raise
 `version.sdk_loader_unpinned` instead of a policy evaluation). Only URLs that
 point at a loader/dist artifact count; incidental `campaign-cart@x.y.z`
 strings elsewhere in source are ignored.
 
+In a static repo (no `_data/campaigns.json`), `campaigns-os sdk repin --target
+<repo> [--target-sdk <x.y.z>] [--apply]` rewrites the semver-pinned references
+in this list that are below the target version, changing only the version
+segment of each URL. It previews by default and leaves the unpinned refs
+alone. See `sdk-storage-compatibility.md`.
+
 `payment.proof_state` is one of `runtime_proof_required` (custom-control
 evidence found), `undetermined` (radios exist; static scanning cannot exclude
 externally-styled custom controls), or `not_applicable` (no `payment_method`
@@ -216,6 +238,16 @@ Page Kit root that inlines them gets the same `checkout_fields` block and the
 same `checkout.unsupported_field_binding` / `checkout.unknown_field_binding`
 findings as an application root.
 
+A bundled dependency is judged by its floor, the lowest version its
+`package.json` spec lets npm install, recorded as
+`sdk_loader.bundled_dependency.floor_version`. Only an exact pin (`0.4.30`,
+`=0.4.30`, `v0.4.30`) or one `^`, `~` or `>=` range on a released version has
+a certain floor; `^0.4.25` is evaluated as `0.4.25`. Any other spec (`<0.4.39`,
+an `||`, hyphen or x-range, a tag) has none, so it gets no evaluation and
+raises the warning `version.sdk_dependency_floor_unknown` instead; a
+prerelease pin raises `version.sdk_prerelease_pin`. `resolved_version` stays
+the version text extracted from the spec, for reference.
+
 Both are also injectable from the CLI: pass
 `--sdk-support-policy <path-to-json>` and/or `--field-contract <path-to-json>`
 to `standardize`. Each file is read and JSON-parsed

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

@@ -12,7 +12,7 @@ The happy path is intentionally tight:
 8. Run polish, serve the current built output, and run `campaigns-os polish capture --packet <packet> --base-url <served-current-build-url>`. Do not mark Polish terminal or begin deploy/QA until this package-owned page-load evidence passes or has an exact finding waiver.
 9. Deploy a preview.
 10. Run `campaigns-os qa resolve --packet <packet>`, then `campaigns-os qa run --packet <packet> --browser --test-order common` with the tested URL. Saved-Map QA uses the existing consent and publication controls; pass `--no-post-verdict` to keep its verdict local. Local-spec QA always keeps verdicts and progress local, even with `--post-verdict`, and `qa publish` refuses local-spec packets. Run Telemetry retains its consent controls.
-11. Treat test-order depth as the control: global test cards bypass the gateway and create no transactions, so no approval is needed. Localhost on any port is a Campaigns App Development domain (SDK allowed, analytics suppressed); non-localhost preview/production origins must still be allowlisted for the campaign API key so the SDK loads.
+11. Global test cards bypass the gateway and create no transactions, but each test order leaves a real store order record. Unless the operator has already said test orders are fine for this campaign, ask once, up front, before placing test orders; then proceed. There is no permission flag; test-order depth controls coverage. Localhost on any port is a Campaigns App Development domain (SDK allowed, analytics suppressed); non-localhost preview/production origins must still be allowlisted for the campaign API key so the SDK loads.
 12. Promote, block, or iterate from the recorded build, polish, deploy, QA, and test-order evidence.
 
 Pause only for missing inputs, doctor blockers, blocked deploys, out-of-scope runtime pages that block checkout proof, or merchant-specific uncertainty. The default path should not branch into external browser skills or hand-built backend order creation.

package/docs/design-source-package.md

@@ -396,9 +396,13 @@ a minute. The lock directory and its owner record appear together, so a lock
 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. 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.
+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.
 
 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

@@ -42,6 +42,7 @@ CLI exempts from lifecycle capture (the converse does not hold: `demo` and the
 `doctor` inspection and `doctor --no-write` skip it and write nothing but may
 send the one live campaign read): `help`, `readback`,
 `run status`, `doctor --no-live-refs` inspection, `sdk storage-check`,
+the `sdk repin` preview (without `--apply`),
 `tooling diagnose`, a refused invocation, `run-record --no-write`, and every
 `--dry-run` form on the commands that implement the flag. Everything else
 appends an entry when a journal is selected — an active run session,
@@ -160,7 +161,7 @@ Both rows are tier C, because a change makes recorded stages owed again, and eac
 
 There is **one row per command and per effect-changing flag combination**. The
 flags that change what the invocation does to the world are listed once, in
-`vocabulary.effect_changing_flags`: `--browser`, `--built`, `--dry-run`,
+`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
@@ -208,9 +209,7 @@ template family is certified, and whether a named brief can be read, depend on
 file content: those checks still run in the handler and are journaled.
 The operator-facing `run-record` and `run end` commands refuse bare, empty, or
 whitespace-only values for every value-taking inherited run-record flag before
-packet work. The five agent
-token and elapsed-time flags retain their non-negative-integer diagnostics;
-`--surfaces` rejects unknown values, and `--dry-run` rejects a value. The
+packet work. `--surfaces` rejects unknown values, and `--dry-run` rejects a value. The
 inherited boolean flags (`--no-remit`, `--no-write`, `--dry-run`, and `--json`)
 retain their bare-flag behavior. `run end` also rejects `--new-run` and
 `--run-id` because the saved session fixes its run ID. `run-record` also
@@ -224,8 +223,7 @@ literal relative path, so the default context file is not read. Bare or empty
 `--context` or `--report` still makes QA auto-end fail and leaves the session
 open; bare or empty `--qa-verdict` fails a Run Record closeout when inherited,
 though QA auto-end supplies its own verdict path. The underlying run-record
-handler still rejects invalid agent
-integers, unknown `--surfaces`, and any valued `--dry-run` that reaches it. QA
+handler still rejects unknown `--surfaces` and any valued `--dry-run` that reaches it. QA
 auto-end drops `--dry-run` from inherited flags; if another inherited value
 fails in the handler, auto-end is skipped and the session stays open. QA's own
 journal entry is unaffected because auto-end runs after QA persistence. A named

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.2.0 && npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.53.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
+npm init -y && npm install --save-exact next-campaign-page-kit@0.2.0 && npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.55.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.53.0`
+Supported surface at generation time: `1.55.0`
 
 ## Forward compatibility
 

package/docs/progress-snapshots.md

@@ -65,7 +65,9 @@ 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`. Do not remove a lock while a writer is active. Do not run an
+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.
 
 An unchanged projection reuses its ID, timestamp and sequence. Identity

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

@@ -59,8 +59,10 @@ the toolkit runs that loop in a fixed order:
 2. **Serve and prove.** Serve `_site/` on localhost (the `next deploy` handoff
    names the directory and any root-route rewrite) and run `polish capture`
    against it. Once polish is recorded, `record deploy --packet <p> --base-url
-   <url>` records the URL on `deploy.preview_url` and the deploy stage; then run
-   `qa run --browser` and the typed-card order paths against it.
+   <url>` records the URL on `deploy.preview_url` and the deploy stage, bound
+   to the build it probed (a `record build` of different output makes it owed
+   again and keeps the old record in the deploy stage's history); then run `qa run --browser` and the typed-card order paths against
+   it.
 3. **Prove the pin on the production output.** Before committing, run
 
    ```bash
@@ -339,6 +341,24 @@ npm run campaigns-os -- qa run \
 
 The runner fetches deployed pages, checks route availability, verifies CampaignSpec `sdk_hints.meta_tags` (a key the Campaign Cart SDK does not read, `next-currency` or `next-predictive-address` from `src/sdk-meta-tags.mjs`, is a `warn` row at severity `warn` carrying the shared note, never `manual_review` and never a blocker, whether or not the tag rendered; doctor reports the same key as `sdk_hints.meta_tags.ignored_by_sdk`), writes a local verdict JSON under `<target-repo>/qa-output/<qa-storage-key>/<run-id>.json` (the packet's `assembly.target_repo`, else the packet's directory; `--output-dir` overrides it, and a packet-less run uses `qa-output/` under the current directory), and returns exit code `4` when the verdict is blocked. The storage key is the Map ID for saved-Map QA and `local-spec-<local_spec_id>` for local-spec packet QA. The target's managed ignore block lists `qa-output/`, because full verdicts carry live storefront URLs; the committed form is the `.campaign-runtime/qa-verdict.json` projection.
 
+`--currency <code>` proves one currency per run: the runner adds
+`?currency=<CODE>` to each funnel's entry URL (the HTTP fetch, the browser load
+and `entry_urls`) and to the first page load of each test-order path (the
+checkout probe, or the entry page or checkout when that load comes first),
+keeping any query or tracking params already there. Campaign Cart keeps the URL
+currency for the rest of that tab's session, so the runner adds it to no other
+load (upsell pages and the receipt reload in recovery go without it); a later
+load of the entry URL still carries it, because that URL is tagged. The flag takes one code per run (the
+shared parser keeps the last one if it is given twice). The code must be three
+letters (upper-cased: `gbp` runs as `GBP`); anything else is refused before any
+request. A campaign set up for three currencies takes three runs. `qa parity`
+refuses `--currency`, and so does a run whose orders come from
+`--legacy-api-test-order`, since a direct API order would be placed in the
+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.
+
 ### Automatic commercial parity
 
 When the CampaignSpec has enabled pages with package rows, the same `qa run`
@@ -726,6 +746,16 @@ spec resolved from the portal for the run — keep publish-by-default regardless
 of consent: those verdicts are the QA tab's product surface, not telemetry.
 Explicit flags always win in both directions for saved-Map QA.
 
+A run whose base URL is a local address (`localhost` or any `*.localhost`
+name, any `127.x.x.x` address, `0.0.0.0`, `[::1]` or an IPv4-mapped loopback,
+from `--base-url` or the packet's `deploy.preview_url`) keeps its verdict local
+by default, whatever the spec source. Those runs are checks on your own
+machine, and people watching the Map's QA tab should not see them. The output
+names the destination and how to publish: `qa publish` for the stored verdict,
+or `--post-verdict` on the next run. `--post-verdict` publishes a local-address
+run, and `publish_decision.reason` reads `loopback_base_url` when the default
+kept it local.
+
 A packet with `local_spec_id` always keeps its verdict and progress local.
 `qa run` suppresses portal publication even with `--post-verdict`; the flag
 does not turn a local ID into a Map destination. `qa publish` refuses such a
@@ -792,7 +822,7 @@ prints the portal link.
 The outcome lands on the run's Run Record as the `qa_verdict_publish` block —
 `verdict_run_id`, `publisher` (`qa run` or `qa publish`), `state`
 (`skipped` / `ok` / `failed`), `result` in the remit vocabulary, `base_kind`,
-`published_at` — on the record whose `qa_verdict` artifact references the
+`published_at`, and the nullable publish decision `reason` — on the record whose `qa_verdict` artifact references the
 verdict under the packet's campaign. `qa run` records its own publish (or
 its `--no-post-verdict` skip) the same way when the run session closes, which
 is what `already_published` reads. A stored `ok` is never downgraded: a
@@ -1171,8 +1201,8 @@ Fixture essentials:
 
 Test Orders use **global test cards** that work on any live store and integration.
 They **bypass the payment gateway and create no transactions** (and no fulfillment),
-so they are safe to run any time and need **no permission flags, packet policy,
-merchant sandbox routing, or test-order approval** — you just pick a mode. They leave a small,
+but each creates a real order record on the store. Unless the operator has already said test orders are fine for this campaign, ask once, up front, before placing test orders; then proceed. No permission flag,
+packet policy, or merchant sandbox routing is required. They leave a small,
 easy-to-clean footprint: Test orders are deletable in bulk, and the resulting
 Customer record is reused (see the test email note below) rather than multiplied.
 
@@ -1554,17 +1584,43 @@ Two flags target funnels the default-tier drive cannot prove:
 
 - `--select-package <ref[:qty],...>` — **strict** package/bundle card selection.
   Each ref is matched against rendered selector/bundle cards
-  (`[data-next-package-id]`, `[data-next-bundle-card][data-next-bundle-id]`) and
-  clicked. An explicit quantity requires one unambiguous rendered card whose
+  (`[data-next-package-id]`, `[data-next-bundle-card][data-next-bundle-id]`, and
+  the package a bundle card's `data-next-bundle-items` declares, so
+  `--select-package 1:2` finds the card declaring
+  `[{"packageId":1,"quantity":2}]` whether or not an inner node repeats the
+  package id) and clicked. An explicit quantity requires one unambiguous rendered card whose
   `data-next-bundle-items` composition contains exactly that package and
-  quantity; package identity alone is not enough. The card must then expose a
+  quantity; package identity alone is not enough. A card declaring several
+  items matches by any one of them (`4:1` finds a kit declaring
+  `[{"packageId":1,"quantity":2},{"packageId":4,"quantity":1}]`); a card
+  declaring the item alone is preferred over one declaring it among others. The card must then expose a
   selected-state marker (`data-next-selected="true"` / `.next-selected`) after
   the click. A missing card, ambiguous composition, wrong quantity, or
   unverifiable/refused selection **fails the `selected_bundle` step** instead
   of silently driving the pre-selected default tier. A bundle ref remains an
   authoritative identity when exactly one rendered card declares it. Use this
   flag to traverse non-default tiers of a multi-tier selector. `--cart` remains
-  the best-effort variant.
+  the best-effort variant. For a package that bundle cards declare, `--cart
+  <ref:qty>` clicks the card whose items carry that package at that quantity,
+  and clicks nothing when the selected card already does; refs no bundle card
+  declares (an order bump) are clicked as before. The cards are read again
+  before each ref, so a selector that re-renders after a click is clicked as
+  it now stands. Beside `--select-package`,
+  `--cart` never clicks another card in the chosen card's selector group, and
+  a card in no recognised selector container
+  (`[data-next-bundle-selector]`, `[data-next-selector-id]`,
+  `[data-next-cart-selector]`) counts as in that group: a
+  ref the chosen card carries is left as it is, a ref an order bump or a card
+  in another selector group carries is applied through that control, and any
+  other ref is left unapplied and named in the `selected_bundle` detail
+  (`--cart 3:1 not applied: ...`). The display-parity row reconciles the order
+  against the packages and quantities every selected bundle card declares, not
+  its `data-next-bundle-id`. Without `--select-package` it also fails when an
+  explicit `--cart <ref:qty>` is not in the order at that quantity: a
+  different quantity (`--cart 1:2` that ordered one unit) or no line for the
+  package at all (`--cart 1:2,3:1` on a swap-mode selector that kept only the
+  `3:1` card); beside `--select-package` it judges the order against the card
+  that flag chose.
 - `--apply-coupon <code>` — types the code into the rendered coupon/promo input
   (the SDK's `[data-next-checkout-field="coupon"]` or
   `input[data-next-coupon="input"]`, then hand-rolled `coupon`/`voucher`/`promo`
@@ -1697,7 +1753,7 @@ browser launch, prints the planned count, lists the planned paths (up to 40 ids;
 past that the remainder is counted, never cut silently, and `--select-package
 <ref[:qty]>` lists one tier's paths), and names the exact `--max-test-orders <count>` raise. For example, a linear three-offer graph has
 eight terminal paths plus the checkout baseline, so it requires
-`--max-test-orders 9`. No approval step is involved.
+`--max-test-orders 9`. Unless the operator has already said test orders are fine for this campaign, ask once, up front, before placing these real store order records; then proceed. The command has no permission flag.
 
 `--max-test-orders` bounds **planned paths**, which is not the same as real
 purchases. `--max-order-creations` bounds **actual order creations**, defaults to
@@ -1810,7 +1866,12 @@ The browser driver intentionally behaves like a user:
   proven against the persisted-order voucher read-back
 - checkout is advanced through the visible cart/checkout button
 - address autocomplete is settled or closed before submit
-- Spreedly card and CVV iframes are filled with sequential keystrokes
+- the card and CVV iframes are filled with sequential keystrokes: Spreedly's
+  iFrame fields on SDK 0.4.40 and earlier, and on 0.4.41 and later the
+  Spreedly-hosted fields that NEXT's `payments.29next.com` script mounts.
+  Typing starts once the checkout form drops `next-loading-spreedly` (the
+  fields are ready), and both fields are read back and retyped, up to three
+  attempts in all, before `card_fields_filled` passes
 - the real submit button is clicked without fabricating SDK state
 
 The intended QA order matrix is:
@@ -1832,7 +1893,7 @@ and hardcoded phone numbers that differ from CampaignSpec `campaign.store_phone`
 If a static claim is intentionally preserved, wrap it in an element with
 `data-skip-market-lint="true"` and record why in the assembly report.
 
-Test orders themselves need no allowlist or approval. A separate concern is the
+Test orders need no allowlist and no permission flag; unless the operator has already said test orders are fine for this campaign, ask once, up front, before the first one (each is a real order record). A separate concern is the
 **SDK origin allowlist**: the Campaign Cart SDK must be allowed to load on the
 tested origin for the campaign API key, or runtime checks (and the live page
 itself) may not initialize. Localhost on any port is globally available as a
@@ -1847,8 +1908,8 @@ npm run campaigns-os -- qa policy set \
   --allowed-domains-confirmed true
 ```
 
-There is no permission flag for test orders — they run from `--test-order
-<mode>` alone. The former `--test-orders-allowed` /
+There is no permission flag for test orders; unless the operator has already said test orders are fine for this campaign, ask once, up front, before placing these real store order records, then run `--test-order
+<mode>`. The former `--test-orders-allowed` /
 `--sandbox-test-card-confirmed` flags and the `qa.test_orders_allowed` /
 `qa.sandbox_test_card_confirmed` packet fields they set were removed in
 supported surface 1.28.0: nothing had read their values since the gate itself
@@ -1962,6 +2023,14 @@ placeholder-text blocker and the other residue gates still run. The emitted
 minimal packet is marked `_synthesized` — it points doctor/QA at the built
 output and family, and is not a substitute for a real Build Packet.
 
+`doctor --built` reads the local built files only. `--base-url` is not
+fetched: it fills `deploy.preview_url` in the minimal packet, and the output
+says so (`derived.base_url.fetched: false` in JSON). A clean `doctor --built`
+run with a preview URL says nothing about the preview. To check the served
+pages, run `qa run --site <repo> --base-url <url> --family <family> --browser`.
+The emitted minimal packet does not drive packet QA: `qa resolve` and
+`qa run --packet` block on it, because it carries no local CampaignSpec.
+
 **Trade-off — non-packet QA is narrower than packet-driven QA.** It runs the
 built-output gates (residue, placeholder text, demo-asset, pricing-CSS, brand
 contract) but **skips the CampaignSpec/source-HTML-driven checks** a packet

package/docs/runtime-readiness.md

@@ -8,7 +8,7 @@
 
 How a checkout of this repository at one commit becomes a usable installed runtime, and how a consumer decides whether a prepared one is still trustworthy. Everything below is generated from `contracts/runtime-recipe.campaigns-os-node-v1.json`, which is the only authority for these values.
 
-Recipe kind `campaigns-os-node-v1`, revision `1.0.2`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.53.0`.
+Recipe kind `campaigns-os-node-v1`, revision `1.0.2`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.55.0`.
 
 ## What this is
 

package/docs/sdk-storage-compatibility.md

@@ -17,3 +17,18 @@ Acorn parses JavaScript ASTs; parse5 identifies executable inline HTML scripts a
 Dynamic storage keys, unresolved storage methods, shadowed storage names, missing migration release evidence, unsupported target versions, and JavaScript parse failures report unknown. This bounded analysis does not execute merchant code or prove computed keys correct. It does not follow arbitrary data flow, dynamic imports, event-handler attributes, generated code or runtime-loaded script graphs. Inspect unresolved findings and include all campaign sources in scope; a clean result is only static tracked source compatibility evidence. Browser behavior, order creation, tracking and analytics still require their own proof, especially where multiple campaigns share an origin. Use the SDK public store API where the manifest recommends it; do not invent a prefix-first merchant repair.
 
 Storage `length` property reads are unaffected metadata (`storage-metadata-read`). Storage `key()` enumeration, extracted method references, and mutations of reserved members remain unknown; enumeration cannot prove an SDK key lookup safe. Git discovery failures return one bounded CLI error. Local script diagnostics retain repository-relative spellings from HTML source, including `../` paths; excluded/outside sources are not read. The Git root and operator target are compared by filesystem device/inode identity, so supported case aliases and symlinks can name the same root. Source containment uses realpaths below the Git root without case folding. Extra positional CLI arguments are rejected so an accidental scope or version value cannot silently disappear.
+
+## Rewriting hardcoded pins in a static repo
+
+A static campaign repo (no `_data/campaigns.json`) pins the SDK in its HTML: `loader.js@v0.4.x` in script tags and `campaign-cart.css@v0.4.x` in link tags. Once the storage check is clean, `sdk repin` updates those pins:
+
+```sh
+npx --no-install campaigns-os sdk repin --target . --target-sdk 0.4.38            # preview: path:line, old URL -> new URL; writes nothing
+npx --no-install campaigns-os sdk repin --target . --target-sdk 0.4.38 --apply    # writes the files and the change record
+```
+
+It reads the same references `standardize` reports under `sdk_loader.references`: every Campaign Cart URL that points at a loader or dist artifact, in HTML and script files, with HTML comments, `_site/`, `node_modules/`, `dist/`, `build/` and `.campaign-runtime/` left out. Only a semver pin (`@vX.Y.Z` or `@X.Y.Z`) below the target is rewritten, and only the version segment of the URL changes; a leading `v` stays as written. These are reported and left alone: `@latest`, `@main`, commit refs, prerelease refs, and pins already at or above the target (repin never moves a pin down). Without `--target-sdk` the target is the SDK support policy's `preferred_minimum`, the version `standardize` evaluates pins against.
+
+The default is a preview that writes nothing. `--apply` writes the files, then writes a change record to `.campaign-runtime/sdk-repin.json` (`campaigns-os-sdk-repin/v0`). The record holds the files touched, the reference count, the from and to versions, each rewrite with its path, line and artifact (`loader` or `css`), and the refs left alone. It uses repo-relative paths only, so you can commit it, and a Run Record can cite it by path and sha256 (`--json` prints the sha256). After writing, repin scans again and reports whether any pin below the target remains. Running it a second time with the same target finds nothing to change and writes nothing. `--json` prints the full result: `status` is `changes`, `nothing_to_change`, `no_references` or `refused_page_kit`.
+
+A repo with `_data/campaigns.json`, at its root or in any folder the scan walks, is refused with exit 2 and nothing written: page-kit owns that pin, so use `campaigns-os page-kit sync --packet <campaign-runtime.build.json>` there. An invalid `--target-sdk` is refused with exit 1. Repin does not prove that the new SDK works. After rewriting, run the campaign's browser QA against the new pin.

package/docs/skills-revision.md

@@ -16,7 +16,7 @@ that the copy on disk moved.
 `skills.json` carries one top-level field:
 
 ```json
-"bundle_revision": "1.53.0+skills.2"
+"bundle_revision": "1.55.0+skills.1"
 ```
 
 The spelling is `<package version>+skills.<n>`:
@@ -25,7 +25,7 @@ The spelling is `<package version>+skills.<n>`:
   skills ship with (`check-skill-versions.mjs` fails if the two disagree);
 - `<n>` is a plain counter, not a semver component. It says "this is the *n*th
   skill-text revision published against that package version" and it **resets
-  with the prefix**. `1.53.0+skills.1` is therefore ahead of `1.40.0+skills.7`.
+  with the prefix**. `1.55.0+skills.1` is therefore ahead of `1.40.0+skills.7`.
 
 It is one identity for the bundle as a whole, on purpose. Per-skill versions
 still exist and still gate per-skill changes, but an agent that loaded one skill
@@ -37,7 +37,7 @@ The first body line of every bundled `SKILL.md`, immediately after the
 frontmatter, is exactly:
 
 ```
-Bundle revision: 1.53.0+skills.2
+Bundle revision: 1.55.0+skills.1
 ```
 
 followed by a short paragraph telling the agent to run the check below at the
@@ -48,7 +48,7 @@ text the agent is actually reading, not from a file it would have to go and open
 ## The check
 
 ```bash
-npx --no-install campaigns-os tooling status --skills-revision 1.53.0+skills.2
+npx --no-install campaigns-os tooling status --skills-revision 1.55.0+skills.1
 ```
 
 The value is compared against the bundle revision of the **CLI the command runs
@@ -90,20 +90,20 @@ reports the choice as `skills.scope` (`requested`, `installed_platforms`, or
 "revision_check": "match",
 "skills_revision": {
   "status": "match",
-  "requested": "1.53.0+skills.2",
+  "requested": "1.55.0+skills.1",
   "spelling": "bundle",
-  "on_disk": "1.53.0+skills.2",
+  "on_disk": "1.55.0+skills.1",
   "on_disk_skill": null,
-  "message": "match (1.53.0+skills.2)"
+  "message": "match (1.55.0+skills.1)"
 }
 ```
 
 The text view prints one named line, as a header above the rest of the status:
 
 ```
-Skills revision: match (1.53.0+skills.2)
-Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.53.0+skills.2 — start a fresh session
-Skills revision: unchecked (on disk 1.53.0+skills.2)
+Skills revision: match (1.55.0+skills.1)
+Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.55.0+skills.1 — start a fresh session
+Skills revision: unchecked (on disk 1.55.0+skills.1)
 ```
 
 `unchecked` is the state when the flag is absent. It is not an error — an