@nextcommerce/campaigns-os 1.54.0 → 1.57.0

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

@@ -101,7 +101,7 @@ recapture. A hosted target (`netlify`, `cloudflare-pages`, …) is unaffected:
 its build stage renders production as before and `page-kit parity` refuses the
 packet (`local_proof.parity.not_local_serve`).
 
-### Missing evidence carried forward on the local preview
+### Missing evidence carried forward on previews
 
 On a `local-serve` packet served from a loopback host (`localhost`,
 `127.0.0.1`, `[::1]`, for both `deploy.preview_url` and `--base-url`), some
@@ -110,20 +110,28 @@ loop. The campaign must still prove its commerce there: store and campaign
 binding, routes, SDK loading, prices and a typed-card order. Only these
 checks are carried forward:
 
-| Check | When |
-| --- | --- |
-| `polish.evidence_missing`, `polish.report_missing` | Polish was never recorded for this build. |
-| `polish.hidden_eager_media.no_capturable_routes` | Every mapped page is template stock (`skip_reason`), so polish capture has no design route to capture. |
-| `polish.hidden_eager_media.capture_malformed` | Only when no page-load capture was recorded at all. |
-| Template-residue severity | With `theme_gate.nothing_generatable`, the starter template is the design, so residue findings are warnings rather than blockers. |
+| Check | Local loopback preview | Hosted preview |
+| --- | --- | --- |
+| `polish.evidence_missing`, `polish.report_missing` | Carried when Polish was never recorded. | Carried only with the all-template `no_capturable_routes` checkpoint. |
+| `polish.hidden_eager_media.no_capturable_routes` | Carried when every mapped page is template stock (`skip_reason`). | Carried when every mapped page is template stock and QA uses the packet's non-loopback `deploy.preview_url`, distinct from `deploy.production_url` by origin or QA-resolved campaign route path. |
+| `polish.hidden_eager_media.capture_malformed` | Carried only when no page-load capture was recorded at all. | Blocked. |
+| Template-residue severity | With `theme_gate.nothing_generatable`, residue findings warn. | Unchanged. |
 
 A carried-forward gate has status `carried_forward`. Doctor reports it as a
-warning starting "Carried forward on the local preview"; `next` moves past
-polish to deploy and QA; QA records it as a `warn` row, so the verdict is at
+warning starting "Carried forward on the local preview" or "Carried forward on the hosted preview"; `next` moves past
+polish to deploy and QA, and the recorded all-template hosted preview satisfies deploy without a deploy record; QA records it as a `warn` row, so the verdict is at
 best `ready_with_exceptions`. The evidence is reported as missing, never as
-passed. Any other check keeps its meaning. A hosted preview or production
-packet, and a `local-serve` packet served from any other host, gets the strict
-gates. `record polish` and the waiver commands also keep them strict. Progress
+passed. On a hosted all-template preview, first record an unset preview URL
+with `campaigns-os qa policy set --packet <packet> --preview-url <url>`, then
+run `campaigns-os next --packet <packet>`. Run `campaigns-os next qa --packet <packet>`
+then `campaigns-os qa run --packet <packet> --base-url <preview-url> --browser --test-order common` directly. After QA records the current-build verdict, run `campaigns-os next --packet <packet>` for closeout;
+`record deploy` only accepts loopback local-serve URLs; a pending hosted deploy
+record does not suppress these QA actions when the all-template checkpoint is
+carried forward. The hosted exception
+requires a distinct packet `deploy.preview_url`; a query or fragment on the production page does not count as distinct. QA with `--base-url` equal to
+the packet's `deploy.production_url` stays blocked. A `local-serve` packet
+served from any other host also gets strict gates. `record polish` and the
+waiver commands keep them strict. Progress
 snapshots record a carried-forward gate as `not_applicable`, because their
 schema has no carried-forward state.
 
@@ -179,8 +187,9 @@ line and the printed per-URL rows say which URLs those were rather than leaving
 an operator to infer it from `counts.unreachable`. It is `null` only when every
 probed URL resolved, or when nothing was probed at all.
 
-Resolve appends `campaign.public_route_slug` unconditionally — the packet is
-the authority on where a campaign is served, and no flag overrides it. When
+Resolve appends `campaign.public_route_slug` to the preview base for `base_url`
+and page URLs, including when `campaign.route_root` is `/`. A subpath on
+`--base-url` stays ahead of the slug. When
 every derived route is dead, one extra probe of the host without that slug
 separates the two causes and says which it found:
 `route_probe.route_root_mismatch` (the host serves the campaign under a
@@ -308,6 +317,21 @@ for that entry URL. If Entry URLs are empty, still point at a deleted preview, o
 fail their own HTTP assertion, fix `--base-url` or the packet deploy URL before
 continuing.
 
+For an `is_entry` page with `page_url` empty, `/`, `/<slug>/`, or `<slug>`, `qa resolve` uses that page's
+explicit Page Kit permalink first, then the campaign root when
+`_site/<slug>/index.html` exists. If neither applies and Page Kit emitted the
+entry at its recorded page-file route, the printed Entry URL uses that locally
+emitted route. Doctor warns that the Map still points at the unserved root;
+add a redirect from the root to the emitted route or set `permalink: /<slug>/`
+on the entry page. A non-root permalink also gets the warning when root output
+is absent; QA keeps that permalink as its Entry URL. A present root output
+suppresses the warning. The default
+probe checks the printed URL on the host. For either `campaign.route_root: "/"`
+or the default route root, the file route is joined under `base_url` as
+`/<slug>/<file-route>/` (after any preview subpath). The root output, when
+present, uses `base_url` itself. The route-root declaration still determines
+the public route named in doctor's unserved-root warning.
+
 `--base-url` can be either the deploy host or the campaign root. If the Build Packet says `campaign.public_route_slug = "roadside-ready"`, both of these resolve pages under `/roadside-ready/`:
 
 ```bash
@@ -341,6 +365,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 +846,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 +1225,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.
 
@@ -1428,7 +1470,21 @@ timeout still leaves the ladder up to the point of failure. Ladder entries carry
 object. Evidence is resolved even when the step fails or times out, because the
 failing path is the one worth reading.
 
-Four steps write structured evidence today.
+Five steps write structured evidence today.
+
+**Multi-step checkout paths (campaigns-os#641).** The ladder drives the
+Checkout — the page that takes payment (`type: "checkout"`) — on the tested
+path, never the first page typed checkout. When `checkout_step` pages lead
+into it, the runner lands on the first step: through a `select` page ahead of
+it when there is one (`entered_via_landing` with `control_kind:
+checkout_button`), otherwise the step fills the cart itself.
+`customer_fields_filled` fills only the fields that step renders, one
+`checkout_step_submitted` rung per step follows, and the order is submitted
+only on the Checkout. With
+split-test paths in one campaign, each Checkout reached from an entry page is
+its own path; `tiers` plans read declared tiers and bumps from every page of
+that path (the select page or first step declares the cart), and coupons from
+its steps and Checkout.
 
 **`entered_via_landing` — cart entry.** The first rung of the ladder, before
 `opened_checkout`. A checkout renders its customer form whether or not the SDK
@@ -1472,7 +1528,13 @@ checkout — never a receipt or an offer page), navigates there, waits for the
 SDK, and clicks the cart-entry control: an SDK add-to-cart control
 (`[data-next-action="add-to-cart"]`, the only attribute the SDK activates the
 feature on), or a link into the checkout URL carrying `?forcePackageId=`,
-which is what the certified `shop-single-step` landing renders. A control
+which is what the certified `shop-single-step` landing renders, or, on a
+page with bundle cards (`[data-next-bundle-card]`, a `select` page), a checkout
+button: the SDK's `[data-next-action="checkout"]` or a plain link into the
+checkout URL. There the swap-mode selector already wrote the cart and the SDK
+persists it, so the runner keeps the pre-selected card, or with
+`--select-package <ref>` clicks the bundle card carrying that ref first,
+strictly, before the button. A control
 spelled any other way is not a cart entry, so a page that offers nothing else
 fails the step by name (`cart_entry_control_missing`) rather than clicking a
 control the SDK never wired and waiting out the navigation budget. A visible
@@ -1490,8 +1552,9 @@ cart away. `opened_checkout` then records the arrival instead of re-opening.
 
 Evidence: `landing_url`, `landing_page_id`, `landing_page_type`,
 `landing_resolution` (`routes_into_checkout`, `entry_page_fallback`,
-`first_page_fallback`), `control_text`, `control_kind` (`add_to_cart` or
-`checkout_link`), `package_id`, `sdk_ready`, `arrived_url`, the
+`first_page_fallback`), `control_text`, `control_kind` (`add_to_cart`,
+`checkout_link`, or `checkout_button`), `package_id`, `bundle_card_selection`
+when `--select-package` clicked a bundle card, `sdk_ready`, `arrived_url`, the
 `checkout_selection_surface` probe result, `selection_surface_probe`
 (`loaded`, `reused`, or `failed`), and `selection_surface_probe_error` when it
 failed. The failure codes are
@@ -1527,6 +1590,21 @@ own 30s default, so a caller-supplied budget only ever tightens the ceiling. A
 stuck required field fails as that field rather than as an anonymous step
 timeout; a slow-but-working funnel waits no longer than it did before.
 
+**`checkout_step_submitted` — one rung per `checkout_step`.** On a path whose
+Checkout is preceded by `checkout_step` pages, each step's rung checks the page
+is on that step, clicks the submit control of its
+`form[data-next-checkout-step]` (the SDK validates the step's fields, keeps the
+answers and navigates), and waits for the page to land on the step's declared
+next page (`expected_next_url`). It then fills whatever fields the arrived page
+renders. A step whose form carries no `data-next-checkout-step`, or whose
+submit never reaches the declared next page (usually a required field the
+step validates), fails the rung by name; nothing is reserved or submitted, so
+the creation classifier reads it as `not_created`. Evidence: `step_page_id`,
+`step_number`, `expected_next_url`, `arrived_url` and the arrived page's
+`fields` trace. A path that starts on its first step, with no page routing into
+it, skips `entered_via_landing`: the step page fills the cart and the guard
+before submit checks it.
+
 **`cart_created` — cart-API observation.** The step reports what the cart API
 actually returned: the most recent `POST /api/v1/carts/` response's `status`, an
 `ok` flag, `line_count` when the response body exposes lines, `response_count`,
@@ -1566,17 +1644,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 +1813,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 +1953,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 +1968,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.3`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.57.0`.
 
 ## What this is
 
@@ -81,9 +81,10 @@ Not redundant with the install step. Because install runs with lifecycle scripts
 
 The complete input set, enumerated explicitly rather than globbed. The compiler's configured include globs are NOT the input set: two root modules enter the compilation transitively through imports from the entry module and are emitted, so a fingerprint derived from the globs would cover 36 of the 38 compiled sources and miss one of the larger emitted surfaces. Test fixtures and the package's own tests are not inputs; nothing under them is emitted. A checker resolves the compiler's actual file list and asserts it equals this enumeration, so this list cannot rot silently.
 
-Fingerprint algorithm `sha256`, over 42 enumerated files:
+Fingerprint algorithm `sha256`, over 47 enumerated files:
 
 - `campaign-spec/analytics-vocabulary.ts`
+- `campaign-spec/checkout-flow.ts`
 - `campaign-spec/index.ts`
 - `campaign-spec/normalize.ts`
 - `campaign-spec/package.json`
@@ -91,7 +92,9 @@ Fingerprint algorithm `sha256`, over 42 enumerated files:
 - `campaign-spec/rules/analytics-contract-shape.ts`
 - `campaign-spec/rules/assembly-hints-shape.ts`
 - `campaign-spec/rules/campaign-metadata.ts`
+- `campaign-spec/rules/checkout-forward-target.ts`
 - `campaign-spec/rules/checkout-has-success-url.ts`
+- `campaign-spec/rules/checkout-step-reaches-checkout.ts`
 - `campaign-spec/rules/cycle-detection.ts`
 - `campaign-spec/rules/design-source-shape.ts`
 - `campaign-spec/rules/downsell-without-upsell.ts`
@@ -102,9 +105,11 @@ Fingerprint algorithm `sha256`, over 42 enumerated files:
 - `campaign-spec/rules/funnel-weight-sum.ts`
 - `campaign-spec/rules/index.ts`
 - `campaign-spec/rules/offer-ref-integrity.ts`
+- `campaign-spec/rules/one-checkout-per-path.ts`
 - `campaign-spec/rules/package-pricing-sanity.ts`
 - `campaign-spec/rules/page-count.ts`
 - `campaign-spec/rules/page-id-uniqueness.ts`
+- `campaign-spec/rules/pre-payment-forward-target.ts`
 - `campaign-spec/rules/promo-code-input-validation.ts`
 - `campaign-spec/rules/promo-codes-shape.ts`
 - `campaign-spec/rules/route-field-ignored-for-page-type.ts`
@@ -132,7 +137,7 @@ The output directory is a build product. It is untracked and git-ignored, no com
 
 Directory `campaign-spec/dist`. Committed: `false`. Type entry `campaign-spec/dist/index.d.ts`.
 
-Expected inventory is derived, never listed twice. For every enumerated input under module_source_root whose path ends in .ts, the build is expected to emit campaign-spec/dist/<path relative to module_source_root, with .ts replaced> once per entry in emitted_extensions. The expected inventory is exactly that set: nothing missing, nothing extra. Emitted extensions: `.js`, `.d.ts`. At this revision that derivation yields 76 files.
+Expected inventory is derived, never listed twice. For every enumerated input under module_source_root whose path ends in .ts, the build is expected to emit campaign-spec/dist/<path relative to module_source_root, with .ts replaced> once per entry in emitted_extensions. The expected inventory is exactly that set: nothing missing, nothing extra. Emitted extensions: `.js`, `.d.ts`. At this revision that derivation yields 86 files.
 
 ### Mandatory checks
 

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.57.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.57.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.57.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.57.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.57.0+skills.1",
   "spelling": "bundle",
-  "on_disk": "1.54.0+skills.1",
+  "on_disk": "1.57.0+skills.1",
   "on_disk_skill": null,
-  "message": "match (1.54.0+skills.1)"
+  "message": "match (1.57.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.57.0+skills.1)
+Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.57.0+skills.1 — start a fresh session
+Skills revision: unchecked (on disk 1.57.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. 1.56.0 (breaking) adds `schemas/campaign-spec.v5.schema.json` (CampaignSpec `5.0`: the `checkout_step` page type, and `checkout` meaning the page that takes payment; 4.2/4.3 specs still validate against the v4 schema and are upgraded on read) and the `success_url` and `step_number` keys to the closed `page_kit.frontmatter` object of the Build Packet and Build Context v0 schemas, so a validator holding the 1.55.0 schemas refuses a packet that carries them (campaigns-os#641). |
 | 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/versioning.md

@@ -23,7 +23,10 @@ This repo uses independent compatibility versions:
 - QA Verdict sidecar projection: same `"1.0"` literal, projection guarantees in
   `schemas/campaigns-os-qa-verdict-sidecar.v0.schema.json` (one contract, two
   schema files — the sidecar is an allowlist projection, never a second lineage)
-- CampaignSpec: `4.2`–`4.3` (JSON Schema: `schemas/campaign-spec.v4.schema.json`)
+- CampaignSpec: `5.0` (JSON Schema: `schemas/campaign-spec.v5.schema.json`), with
+  `4.2`–`4.3` still read (`schemas/campaign-spec.v4.schema.json`) and upgraded on
+  read: each `checkout` page whose resolved forward target is another `checkout`
+  becomes `checkout_step`
 - starter-template agent contract: `1`
 - commerce surface catalog: `2`
 - Tooling Orientation: `campaigns-os-tooling-orientation/v1`

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.57.0",
   "description": "Toolkit for agent-assisted NEXT campaign builds.",
   "license": "Apache-2.0",
   "repository": {
@@ -44,6 +44,7 @@
       "default": "./src/legacy-migration.mjs"
     },
     "./schemas/campaign-spec.v4.schema.json": "./schemas/campaign-spec.v4.schema.json",
+    "./schemas/campaign-spec.v5.schema.json": "./schemas/campaign-spec.v5.schema.json",
     "./schemas/campaigns-os-legacy-migration-inventory.v0.schema.json": "./schemas/campaigns-os-legacy-migration-inventory.v0.schema.json",
     "./schemas/campaigns-os-legacy-provisioning-plan.v0.schema.json": "./schemas/campaigns-os-legacy-provisioning-plan.v0.schema.json",
     "./schemas/campaigns-os-legacy-provisioning-receipt.v0.schema.json": "./schemas/campaigns-os-legacy-provisioning-receipt.v0.schema.json",
@@ -66,6 +67,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/campaign-runtime-build-context.v0.schema.json

@@ -191,7 +191,9 @@
                   },
                   "permalink": { "type": "string", "minLength": 1 },
                   "next_url": { "type": "string", "minLength": 1 },
-                  "decline_url": { "type": "string", "minLength": 1 }
+                  "decline_url": { "type": "string", "minLength": 1 },
+                  "success_url": { "type": "string", "minLength": 1, "description": "On a page that leads into a Checkout (select, checkout_step, or a landing page whose forward links reach one): that Checkout's post-payment destination, for the next-success-url meta tag the SDK reads for express orders. Never the next step (campaigns-os#641)." },
+                  "step_number": { "type": "integer", "minimum": 1, "description": "On a checkout_step page: its position among its path's steps, from 1, for the step form's data-next-step-number." }
                 }
               }
             },

package/schemas/campaign-runtime-build-packet.v0.schema.json

@@ -193,7 +193,9 @@
                       },
                       "permalink": { "type": "string", "minLength": 1 },
                       "next_url": { "type": "string", "minLength": 1 },
-                      "decline_url": { "type": "string", "minLength": 1 }
+                      "decline_url": { "type": "string", "minLength": 1 },
+                      "success_url": { "type": "string", "minLength": 1, "description": "On a page that leads into a Checkout (select, checkout_step, or a landing page whose forward links reach one): that Checkout's post-payment destination, for the next-success-url meta tag the SDK reads for express orders. Never the next step (campaigns-os#641)." },
+                      "step_number": { "type": "integer", "minimum": 1, "description": "On a checkout_step page: its position among its path's steps, from 1, for the step form's data-next-step-number." }
                     }
                   }
                 },