@nextcommerce/campaigns-os 1.54.0 → 1.55.0

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

@@ -341,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`
@@ -804,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
@@ -1183,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.
 
@@ -1566,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`
@@ -1709,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
@@ -1849,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
@@ -1864,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

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.54.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/skills-revision.md

@@ -16,7 +16,7 @@ that the copy on disk moved.
 `skills.json` carries one top-level field:
 
 ```json
-"bundle_revision": "1.54.0+skills.1"
+"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.54.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.54.0+skills.1
+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.54.0+skills.1
+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.54.0+skills.1",
+  "requested": "1.55.0+skills.1",
   "spelling": "bundle",
-  "on_disk": "1.54.0+skills.1",
+  "on_disk": "1.55.0+skills.1",
   "on_disk_skill": null,
-  "message": "match (1.54.0+skills.1)"
+  "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.54.0+skills.1)
-Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.54.0+skills.1 — start a fresh session
-Skills revision: unchecked (on disk 1.54.0+skills.1)
+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

package/docs/supported-surface.md

@@ -13,7 +13,7 @@ implementation detail, however stable it looks.
 
 | Surface | Contract | Change discipline |
 |---|---|---|
-| `schemas/*.schema.json` (all of them) | The portable contract catalog: CampaignSpec, Design Source Package, Build Packet, Build Context, Assembly Report, Doctor Output, sidecar-bundle conformance, Run Record, Workflow Finding, Build Brief, Source-HTML Manifest, Tooling Orientation, Release Ledger, QA Verdict, the QA Verdict sidecar projection, Runtime Recipe, and the legacy-migration inventory/plan/receipt trio. | Hashed. Any content change requires updating the recorded hash **and** bumping `surface_version` in the same PR. A shape change that alters meaning gets a new schema-version const — one version identifier must never cover two shapes (the 2026-08 assembly-report drift is the incident this rule encodes). Additions to an open `v0` schema are expected and consumers must tolerate unknown fields; the security-sensitive legacy-migration schemas are closed, so additions there require a new lineage. 1.28.0 (RL entry `surface_version: 1.28.0`, breaking) removed the two required Build Packet booleans `qa.test_orders_allowed` and `qa.sandbox_test_card_confirmed` (nothing read them; test orders run from `--test-order <mode>` alone), added `local-serve` to the `deploy.target` enum, and added the optional `remit_result` / `remit_base_kind` fields to the Run Record. 1.30.0 (additive) added the optional `data_layer` record to the QA Verdict's `test_orders[]` entries — the order's `dl_purchase` reading (#325). 1.33.0 (additive) added the optional `qa_verdict_publish` block to the Run Record — which verdict was posted to the QA portal, by `qa run` or `qa publish`, and what the portal answered, in the `remit_result` vocabulary (#328). |
+| `schemas/*.schema.json` (all of them) | The portable contract catalog: CampaignSpec, Design Source Package, Build Packet, Build Context, Assembly Report, Doctor Output, sidecar-bundle conformance, Run Record, Workflow Finding, Build Brief, Source-HTML Manifest, Tooling Orientation, Release Ledger, QA Verdict, the QA Verdict sidecar projection, Runtime Recipe, and the legacy-migration inventory/plan/receipt trio. | Hashed. Any content change requires updating the recorded hash **and** bumping `surface_version` in the same PR. A shape change that alters meaning gets a new schema-version const — one version identifier must never cover two shapes (the 2026-08 assembly-report drift is the incident this rule encodes). Additions to an open `v0` schema are expected and consumers must tolerate unknown fields; the security-sensitive legacy-migration schemas are closed, so additions there require a new lineage. 1.28.0 (RL entry `surface_version: 1.28.0`, breaking) removed the two required Build Packet booleans `qa.test_orders_allowed` and `qa.sandbox_test_card_confirmed` (nothing read them; test orders run from `--test-order <mode>` alone), added `local-serve` to the `deploy.target` enum, and added the optional `remit_result` / `remit_base_kind` fields to the Run Record. 1.30.0 (additive) added the optional `data_layer` record to the QA Verdict's `test_orders[]` entries — the order's `dl_purchase` reading (#325). 1.33.0 (additive) added the optional `qa_verdict_publish` block to the Run Record — which verdict was posted to the QA portal, by `qa run` or `qa publish`, and what the portal answered, in the `remit_result` vocabulary (#328). 1.55.0 (breaking) adds the optional publish decision `reason`, record `closed_by` closer, QA observation `verdict_run_id`, `build_fingerprint`, and `stale`, lifecycle `stages[].wait_ms` and `stages[].finding_codes`, and run-level `needs_input_count` and `failure_count` while removing the unused `agent_usage` field from the same v0 Run Record shape. |
 | CLI commands: `start`, `prepare-build`, `build`, `polish`, `checkpoint`, `page-kit`, `spec`, `doctor`, `bundle`, `next`, `theme`, `tooling`, `install-skills`, `install-agent-context`, `validate-assembly-report`, `telemetry`, `standardize`, `qa`, `findings`, `run-record`, `run`, `sdk`, `demo`, `login`, `logout` | Scriptable entry points. The founding list (1.0.0) was the argv surface Campaigns Agent's remit fixture pins; 1.25.0 adds the partner entry path the public guides instruct — `install-skills` (skill install), `tooling status` (preflight), `next --packet` (the runtime cursor) — plus `theme`, `install-agent-context`, `validate-assembly-report`, and `telemetry`, since consent is part of the partner contract. `validate-build-packet`, formerly an undocumented and unsupported alias of `doctor`, was removed in 1.25.0+agent.7 (RL-0036) and now gets the unknown-command error; use `doctor`. `standardization-report`, a supported but redundant second spelling of `standardize` — same flags, same output, same exit codes — was removed in 1.27.0 and now gets the same unknown-command error; use `standardize`. Removing a supported command is a breaking change and is why that release moved the minor. `bundle check` validates the canonical JSON readback set and makes QA required only under `--require-qa`. `polish capture` owns page-load evidence production. `checkpoint waive` currently accepts five registered gates: `page_kit.store_profile`, `page_kit.sdk_version`, `polish.hidden_eager_media`, `built_output.upsell_selector_scope`, and `source_html.producer_provenance` (per page, with `--page <page_id>`). `page-kit sync` (added in 1.29.0) writes the CampaignSpec's Store Profile fields and SDK pin into the target's `_data/campaigns.json` entry — the repair the first two gates name — and is the only `page-kit` subcommand. `spec derive` (added in 1.31.0) is the reverse write for the repo-derived field class (#432): the target's SDK pin, page routes and analytics ids into the packet's local CampaignSpec; it is the only `spec` subcommand, and the `page_kit.sdk_version.repo_newer` advisory names it; its `--write-map` flag (1.33.0+agent.2) also records the derived pin in the saved Map's Build hints field through the proxy Worker, never moving a Map pin backwards. `qa publish` (added in 1.33.0) posts an already-stored verdict to the QA portal without a re-run or an order, refusing a stale `spec_hash` or a verdict its Run Record already records as published (#328). Within Polish, only the broader Source Freshness waiver remains on its existing report lane; theme and QA decisions also retain their existing lanes. | Any change to this list — adding, renaming, or removing a command — bumps `surface_version` in the same PR, and since 1.25.0 `check-supported-surface.mjs --base` enforces that (before, only hashed and named entries owed a bump, so `checkpoint` landed unbumped). Subcommands, registered gates, and flags may grow freely beneath a listed command. Removing a listed command from dispatch fails the gate outright. Do not infer support for an unregistered checkpoint from the top-level command. |
 | `sdk storage-check` and `docs/sdk-storage-compatibility.md` | Read-only AST compatibility report for explicitly scoped tracked campaign HTML/JS before an SDK bump; consumes the supplied SDK-owned manifest and records its SHA-256 and verified or unverified local Git provenance. Incompatible and unknown findings exit 2; a clean scan is static source evidence only. | Additive supported CLI and named documentation; no automatic merchant integration repair. |
 | `sdk repin` | Rewrites the version segment of semver-pinned Campaign Cart loader.js / campaign-cart.css URLs in a static repo (no `_data/campaigns.json`) to a target version, default the SDK support policy's `preferred_minimum`. It previews by default. `--apply` writes the files and the change record `.campaign-runtime/sdk-repin.json` (`campaigns-os-sdk-repin/v0`). `@latest`, `@main`, commit and prerelease refs, and pins at or above the target, are reported and never rewritten. A page-kit repo is refused with exit 2. Usage is in `docs/sdk-storage-compatibility.md`. | Additive supported subcommand under the listed `sdk` command. It never changes anything in a URL except the version segment. |

package/docs/workflow-findings-sidecar.md

@@ -51,7 +51,8 @@ own schemas and evolve independently). Instead it carries:
 
 - **Stable envelope** — `schema_version` (`campaigns-os-run-record/v0`),
   `run_id`, package version, the command that ran, an `argv` *shape* (flag names
-  present, not raw values), `created_at`, consent state, and remit status.
+  present, not raw values), `created_at`, consent state, remit status, and
+  optional `closed_by` (`run_end`, `qa_auto_end`, `stale_sweep`, or `manual`).
 - **Run identity** — `map_id`, `campaign_slug`, `template_family`,
   `entry_point_shape`. (Best-effort; missing identity never blocks capture.)
 - **Source artifact refs** — for the Build Packet, Build Context, Assembly
@@ -64,6 +65,17 @@ own schemas and evolve independently). Instead it carries:
   this run.
 - **Findings snapshot** — this run's Workflow Findings (see channel below).
 
+When a QA verdict is present, `observations.qa.verdict_run_id` names the same
+verdict that supplies `disposition`. `build_fingerprint` is the QA stage's
+recorded build fingerprint only when the Assembly Report binds that stage to
+the same verdict; otherwise it is `null`. `stale` compares that fingerprint
+with the Assembly Report's recorded build fingerprint using the same comparison
+as `next`: `true` when they differ, `false` when they match, and `null` when
+either fingerprint is unknown. A rebuild without `record build` therefore reads
+`stale: false` when the recorded fingerprints still match; doctor's
+`built_output.fingerprint_stale` checks the output on disk. All three fields
+are optional for older records; without a verdict, `observations.qa` is absent.
+
 ### Run identity
 
 A single canonical `campaigns_os_run_id` is minted at the run boundary and
@@ -78,6 +90,45 @@ Stage timings and repair-loop count are captured from the command lifecycle
 journal when a run session or explicit lifecycle journal is active. They remain
 best-effort signal: telemetry records the commands Campaigns OS can observe, not
 every thought, browser click, or external editor action in an agent session.
+Each new journal entry records `wait_ms` as non-negative whole milliseconds
+blocked on terminal input; an invocation without a prompt records 0. Legacy
+entries may omit it or hold null, and Run Record stages preserve unknown wait
+as absent or null rather than inventing 0. `duration_ms` still includes prompt
+wait, so observed command work is `duration_ms - wait_ms` when wait is known. Tier-2 phases carry their
+own measured wait when the prompt occurs while that phase is active; the journal
+also retains the invocation total. Nested prompt hooks count their outer wait
+interval once. Authentication prompts are outside lifecycle capture by policy.
+
+On a non-zero doctor or QA exit, optional `finding_codes` is an array of at most
+five distinct string codes in first-seen order; null is invalid. Codes belong
+to the phase active when they were recorded. Codes recorded outside any phase,
+and codes in a legacy entry, are invocation-level only; aggregation assigns them
+to the entry's last phase. A successful stage has no finding codes. The optional run-level
+`needs_input_count` and `failure_count` are non-negative integer counts; null is
+invalid and absence means a legacy record did not report the count.
+`needs_input_count` counts journal entries with exit 2 and `failure_count`
+counts entries with any other non-zero exit. Current command
+paths use 0 for success, 1 for operational errors, 2 for missing or blocked
+inputs, and 4 for blocked QA; the other-non-zero rule also covers a future
+status without reclassifying exit 2. Both counts are per command invocation,
+including a command that emits multiple Tier-2 stages. `repair_loop_count`
+continues to count repeated commands plus explicit repair-loop hooks.
+
+| Terminal input site | Wait hook | Capture context |
+|---|---|---|
+| Consent question (`src/consent.mjs`) | Around the injectable `ask` call | Active command, including `run-record` |
+| Store question (`src/login.mjs`) | Around readline `question` | Authentication runs outside lifecycle capture |
+| Finding stage, kind, summary, details (`src/cli.mjs`) | Around each readline `question` | Active `findings add` command; omitted fields do not prompt |
+
+| Non-zero finding source | Codes recorded |
+|---|---|
+| `doctor` | `result.errors[].code` before rendering and exit 2 |
+| `start` and `build` | Their embedded doctor `errors[].code` before the prepare result sets exit 2 |
+| `qa run` and `qa parity` | Blocked verdict assertions: `evidence.code`, or assertion `id` when no code is present, before returning from QA dispatch with exit 4 |
+
+Spec resolution exceptions and prepare-build without a doctor result do not
+expose doctor or QA codes. They keep their existing exit and timing evidence,
+with no invented finding code.
 
 ### Validation
 
@@ -246,7 +297,11 @@ remit(path, payload, proxyBase)   // mirrors qa-node.mjs postVerdict
   for a later post of the stored verdict), `attempted` / `ok` / `error` /
   `endpoint` (`/api/qa/verdicts`), a `state` (`skipped` when the run's
   publish was off, `ok`, `failed`), the `result` in the same vocabulary as
-  `remit_result`, the `base_kind`, and `published_at`. `qa run` hands the
+  `remit_result`, the `base_kind`, `published_at`, and optional `reason`.
+  The reason records the actual QA publish decision: `loopback_base_url`,
+  `portal_managed_default`, `consent_off`, `flag_opt_out`, `flag_opt_in`,
+  `default`, or `local_spec`. A later `qa publish` has no QA run decision and
+  records a null reason. `qa run` hands the
   block to the session through its QA attempt, so `run end` and the auto-end
   stamp it; `qa publish` stamps the record whose `qa_verdict` artifact
   references the verdict, reads `state: "ok"` as already published, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextcommerce/campaigns-os",
-  "version": "1.54.0",
+  "version": "1.55.0",
   "description": "Toolkit for agent-assisted NEXT campaign builds.",
   "license": "Apache-2.0",
   "repository": {
@@ -66,6 +66,8 @@
     "check:spec": "node --test \"campaign-spec/test/**/*.test.ts\"",
     "check": "npm run check:provenance && npm run check:workflows && npm run check:changelog-structure && npm run build:spec && npm run check:tests && npm run check:spec && npm run check:fixtures && npm run check:legacy-migration && npm run check:spec-conformance && npm run check:private-strings && npm run check:template-doctrine && npm run check:slot-manifest && npm run check:skill-versions && npm run check:cart-readiness && npm run check:sidecar-bundle && npm run check:supported-surface && npm run check:effects && npm run check:release-ledger && npm run check:runtime-recipe && npm run check:orientation-docs && npm run check:runtime-docs && npm run check:pack -- --skip-prepare",
     "check:tests": "node ./scripts/check-tests.mjs",
+    "check:fast": "node ./scripts/check-fast.mjs",
+    "hooks:install": "node ./scripts/install-git-hooks.mjs",
     "check:legacy-migration": "node ./scripts/check-legacy-migration.mjs",
     "check:fixtures": "node ./scripts/check-fixtures.mjs",
     "check:spec-conformance": "node ./scripts/check-campaign-spec-conformance.mjs",

package/schemas/campaigns-os-run-record.v0.schema.json

@@ -134,6 +134,11 @@
           "enum": ["skipped", "ok", "failed"],
           "description": "skipped: publish was off for the run (no send). ok: the receiver's answer counts as stored. failed: refused or never answered."
         },
+        "reason": {
+          "type": ["string", "null"],
+          "enum": ["loopback_base_url", "portal_managed_default", "consent_off", "flag_opt_out", "flag_opt_in", "default", "local_spec", null],
+          "description": "The QA publish decision's reason. null when no decision was recorded, such as a later qa publish of a stored verdict."
+        },
         "result": {
           "type": ["string", "null"],
           "enum": ["stored", "already_stored", "ok_unparsed_ack", "refused", "transport_error", null],
@@ -226,6 +231,9 @@
           "additionalProperties": false,
           "properties": {
             "disposition": { "type": ["string", "null"] },
+            "verdict_run_id": { "type": ["string", "null"], "minLength": 1, "description": "Run ID of the verdict supplying disposition." },
+            "build_fingerprint": { "type": ["string", "null"], "minLength": 1, "description": "QA build fingerprint from the Assembly Report stage bound to that verdict." },
+            "stale": { "type": ["boolean", "null"], "description": "Whether that QA fingerprint differs from the current recorded build; null when either fingerprint is unknown." },
             "gap_classes": {
               "type": "array",
               "items": { "type": "string" },
@@ -286,19 +294,10 @@
       "type": ["string", "null"],
       "description": "Optional free-form confidence hint for primary_surface, e.g. \"low\"."
     },
-    "agent_usage": {
-      "type": "object",
-      "additionalProperties": false,
-      "description": "Optional host-supplied agent runtime usage. Campaigns OS does not infer these values; outer runners provide them when available.",
-      "properties": {
-        "input_tokens": { "type": "integer", "minimum": 0 },
-        "output_tokens": { "type": "integer", "minimum": 0 },
-        "tool_output_tokens": { "type": "integer", "minimum": 0 },
-        "total_tokens": { "type": "integer", "minimum": 0 },
-        "elapsed_ms": { "type": "integer", "minimum": 0 },
-        "model": { "type": "string" },
-        "source": { "type": "string" }
-      }
+    "closed_by": {
+      "type": "string",
+      "enum": ["run_end", "qa_auto_end", "stale_sweep", "manual"],
+      "description": "The command path that closed this Run Record. Absent on records written before this field existed."
     },
     "lifecycle": {
       "type": ["object", "null"],
@@ -327,17 +326,23 @@
             "type": "object",
             "additionalProperties": false,
             "required": ["name"],
+            "if": { "required": ["finding_codes"], "properties": { "finding_codes": {} } },
+            "then": { "required": ["exit_status"], "properties": { "exit_status": { "type": "integer", "not": { "const": 0 } } } },
             "properties": {
               "name": { "type": "string" },
               "duration_ms": { "type": ["number", "null"] },
-              "exit_status": { "type": ["integer", "null"] }
+              "exit_status": { "type": ["integer", "null"] },
+              "wait_ms": { "type": ["integer", "null"], "minimum": 0, "description": "Whole milliseconds blocked on operator input. Absent or null means unknown for legacy entries; duration_ms includes it." },
+              "finding_codes": { "type": "array", "maxItems": 5, "uniqueItems": true, "items": { "type": "string" }, "description": "First five distinct doctor or QA finding codes, only on a non-zero exit." }
             }
           }
         },
         "repair_loop_count": {
           "type": ["integer", "null"],
           "description": "Re-runs of any command within the run (a re-run is a repair loop: doctor -> fix -> doctor). 0 when each command ran once."
-        }
+        },
+        "needs_input_count": { "type": "integer", "minimum": 0, "description": "Number of command invocations with exit_status 2." },
+        "failure_count": { "type": "integer", "minimum": 0, "description": "Number of command invocations with a non-zero exit_status other than 2." }
       }
     }
   }

package/skills/campaign-lifecycle-orientation/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: campaign-lifecycle-orientation
-version: 1.0.30
+version: 1.0.32
 description: Orient a reader to the Campaigns OS lifecycle artifacts a run has already emitted, without advancing any stage or changing any state.
 ---
 
-Bundle revision: 1.54.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.54.0+skills.1`
+Bundle revision: 1.55.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read

package/skills/campaign-readback-classification/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: campaign-readback-classification
-version: 1.0.30
+version: 1.0.32
 description: Classify a selected campaign from the readback projection's v2 fields and write a read-only handoff without turning diagnosis into permission.
 ---
 
-Bundle revision: 1.54.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.54.0+skills.1`
+Bundle revision: 1.55.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read

package/skills/campaign-run-evidence/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: campaign-run-evidence
-version: 1.0.30
+version: 1.0.32
 description: Interpret existing Campaigns OS doctor, QA and proof-depth evidence without claiming more proof than the artifacts contain.
 ---
 
-Bundle revision: 1.54.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.54.0+skills.1`
+Bundle revision: 1.55.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read

package/skills/contribution-intake/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: contribution-intake
-version: 1.0.30
+version: 1.0.32
 description: Turn a suggestion about the agent surface into a classified, evidence-checked proposal and, only with attended approval, one issue on this repository's tracker.
 ---
 
-Bundle revision: 1.54.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.54.0+skills.1`
+Bundle revision: 1.55.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read

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

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-build
-version: 1.0.35
+version: 1.0.37
 description: Assemble a NEXT campaign from a doctor-cleared Build Packet, CampaignSpec/API values, prepared HTML/assets, page-kit, and starter-template contracts.
 ---
 
-Bundle revision: 1.54.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.54.0+skills.1`
+Bundle revision: 1.55.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read

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

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-os
-version: 1.0.50
+version: 1.0.52
 description: Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth.
 ---
 
-Bundle revision: 1.54.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.54.0+skills.1`
+Bundle revision: 1.55.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read

package/skills/next-campaigns-os-setup/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-os-setup
-version: 2.0.33
+version: 2.0.35
 description: Bootstrap or prepare a target page-kit campaign repo from a doctor-cleared Campaigns OS Build Packet before full build wiring. Formerly installed as next-campaigns-setup; renamed 2026-08 to stop colliding with the published NextCommerceCo/skills scaffolder of that name.
 ---
 
-Bundle revision: 1.54.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.54.0+skills.1`
+Bundle revision: 1.55.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read

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

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-polish
-version: 1.1.34
+version: 1.1.36
 description: Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign.
 ---
 
-Bundle revision: 1.54.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.54.0+skills.1`
+Bundle revision: 1.55.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read

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

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-qa
-version: 1.3.34
+version: 1.3.36
 description: Run spec-aware QA from a saved Map or local-spec Build Packet and tested campaign URL after build, polish, and deploy/local evidence exist, including Playwright typed-card test-order proof.
 ---
 
-Bundle revision: 1.54.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.54.0+skills.1`
+Bundle revision: 1.55.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read
@@ -80,7 +80,7 @@ Rules:
 - Parity capture blocking proof is the voucher-adjusted persisted line from typed-card order readback. Browser totals and client state do not replace the persisted-line voucher guard.
 - Read client purchase values per event. A whole-cart `dl_purchase` must not mask or supply an offer-level upsell purchase expectation.
 - Live `qa parity` runs publish to the QA portal by default like other QA runs. Pass `--no-post-verdict` for dev, replay, negative-control, and other local proof runs.
-- Theme gate: `qa run` refuses to run when a generatable brand theme is not applied to commerce pages and no waiver exists. Apply the brand layer or record a waiver (`campaigns-os theme waive`, tier `C`: it overwrites the assembly report and doctor output / `qa run --theme-waive "<reason>"`); do not bypass the gate another way. A waived run still reports template-residue findings at warn severity.
+- Theme gate: `qa run` refuses to run when a generatable brand theme is not applied to commerce pages and no waiver exists. Apply the brand layer or use the recorded waiver `campaigns-os theme waive --packet <p> --reason "<why>" --waived-by "<named human>"` (tier `C`: it overwrites the assembly report and doctor output). `qa run --theme-waive "<reason>"` is the one-run ephemeral form. Do not bypass the gate another way. A waived run still reports template-residue findings at warn severity.
 - Template residue is a QA dimension, not advice: promoted starter families must have a brand/residue/pricing contract (`contracts/template-brand-contract.<family>.v0.json`). Browser QA inspects computed styles on commerce surfaces and fails pages that still render starter defaults (`#3c7dff`/`#0a265c`, starter `next-logo.png`, paypal/klarna chrome absent from the spec).
 - Pricing visibility is a blocker: an upsell/downsell offer with zero visible price rows fails QA. Pricing surfaces render via template pricing modes (`full_price`, `compare_at_current`, `unit_price_plus_total`, `savings_badge_amount`, `code_discounted_post_checkout`), never via campaign CSS `display:none` on price wrappers.
 - The upsell and checkout bundle price checks count the SDK's `data-next-bundle-display` price as a price row when it is visible and not empty.