@nextcommerce/campaigns-os 1.54.0 → 1.57.0

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.35
 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.57.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.57.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
@@ -53,9 +53,9 @@ from Git HEAD, from the word "latest", or from prose in a checkout.
 
 `CONTEXT.md` is the glossary kept reconciled against the code, and it separates
 public lifecycle language from internal implementation language. A
-**CampaignSpec** is the JSON campaign contract; current packets use CampaignSpec
-4.2, whose funnel structure lives in `funnels[]`
-(`schemas/campaign-spec.v4.schema.json`). A **Build Packet** is the assembly
+**CampaignSpec** is the JSON campaign contract; current specs use CampaignSpec
+5.0, whose funnel structure lives in `funnels[]`
+(`schemas/campaign-spec.v5.schema.json`; 4.2 and 4.3 specs are upgraded on read). A **Build Packet** is the assembly
 handoff that wraps the spec without replacing it (`docs/build-packet.md`). An
 **Assembly Report** is the machine-readable record of lifecycle progress.
 
@@ -88,8 +88,10 @@ route cannot make evidence from another local spec belong to this campaign
 (`docs/build-packet.md`, "Local-spec entry").
 
 Campaign pages are typed. The page-type vocabulary is `presell`, `landing`,
-`select`, `checkout`, `upsell`, `downsell` and `thankyou`; `select` is where a
-shopper chooses a package before checkout. Use the spec's own term for a page
+`select`, `checkout_step`, `checkout`, `upsell`, `downsell` and `thankyou`;
+`select` is where a shopper chooses a package before checkout, a
+`checkout_step` collects checkout details without placing an order, and
+`checkout` is the page that takes payment. Use the spec's own term for a page
 rather than describing it.
 
 ## Read doctor as a gate

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

@@ -1,11 +1,11 @@
 ---
 name: campaign-readback-classification
-version: 1.0.30
+version: 1.0.35
 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.57.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.57.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.35
 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.57.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.57.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.35
 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.57.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.57.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.40
 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.57.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.57.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
@@ -100,7 +100,9 @@ Build rules:
 - If setup/build needs starter-template files, copy the template family atomically with its dependent pages, `_includes/`, `_layouts/`, `assets/css/`, and `assets/js/`; copying only checkout/receipt pages is incomplete.
 - Resolve SDK routing meta tags to deployed campaign-root paths, not spec literals. For example, `next-success-url: upsell/` in the spec should become `/<public_route_slug>/upsell/` in built HTML.
 - If an order bump package comes from `packages.prepurchase_*` and is not one of the main `bundles[]`, default `package_sync=false` and `show_line_total_price=false` unless the CampaignSpec explicitly says the add-on quantity must sync with the main bundle.
-- For two-step package-selection-before-checkout flows, use the selector page as the pre-checkout step, encode the selected cart with `forcePackageId`, preserve attribution/tracking params, and strip `forcePackageId` from the visible checkout URL after SDK initialization.
+- Multi-step checkout paths run `select` → `checkout_step`… → `checkout`; only the `checkout` page takes payment. On a `select` page the swap-mode bundle selector (`data-next-bundle-selector` with `data-next-selection-mode="swap"`) writes the cart and the SDK persists it between pages; a checkout button or link (`href` from the page's `next_url`) goes to the next page. Use `forcePackageId` only on a page with no selector, such as a landing call-to-action into a checkout that renders none.
+- Each `checkout_step` page's checkout form (`<form data-next-checkout="form">`) carries `data-next-checkout-step="<its next_url>"` and `data-next-step-number="<step_number>"` (frontmatter `step_number`, 1 for the first step on its path). The `checkout` page's form carries neither.
+- On every page that feeds a Checkout (`select`, `checkout_step`, or a landing page with express checkout buttons), the `next-success-url` meta tag is that Checkout's post-payment destination (frontmatter `success_url`), not the next step: the SDK reads it for express orders placed on that page. Forward navigation uses the step form attribute or a plain link, never that meta tag.
 - Record intentional drops from source HTML in the assembly report, especially payment/provider changes such as "PayPal removed because CampaignSpec available_payment_methods excludes it." Polish must inherit these decisions.
 - Preserve any existing Build Context `theme` inspection state and Assembly Report `theme` application state. If build applies, skips, or invalidates generated theme CSS, update `report.theme` rather than leaving stale evidence.
 - After page-kit build, inspect rendered `_site` output: body exists, Campaign Cart runtime markers exist, `sdk_hints.meta_tags` rendered, route meta points at the campaign root, and copied funnel attribution/runtime baggage is gone.

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

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-os
-version: 1.0.50
+version: 1.0.55
 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.57.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.57.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.38
 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.57.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.57.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.40
 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.57.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.57.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
@@ -71,14 +71,29 @@ Responsibilities:
 - For bundle selectors and order bumps, verify active/inactive visual state after interaction, mobile label wrapping, badge placement, and selected/unchecked state. A native hidden input state that disagrees with the SDK class state is a polish blocker. So is a selected/active visual driven by a *non-SDK static attribute the SDK never clears* — e.g. a hardcoded `data-selected="true"` left on the initial card. (The native `selected` attribute on `<option>`/custom selects *is* SDK/browser-managed, so do not flag that.) The selected style must follow the SDK-managed class (e.g. `.next-selected` — see the family's bundle-selector selectors in `contracts/template-brand-contract.<family>.v0.json`) so a single-select swap clears the previous selection. Verify by interaction that the previously-selected item deselects after another is picked — a selector that only ever paints "selected" on click is a blocker.
 - For exit-intent pops and promo-code inputs, polish the wrapper/copy states without breaking SDK coupon/voucher apply hooks or `cart.hasCoupon("CODE")` conditional labels.
 - If `report.theme` or `context.theme` exists, verify brand-theme load order after `next-core.css`, source-token parity for primary color/CTA/surface/text/font/radius when present, and SDK safety. When the brand layer is missing, stale, low-confidence, or unsafe to apply, record the first repair-loop defect or an explicit skipped reason.
-- Before recording a terminal Polish status, install the package-owned browser
-  once with `npx --no-install campaigns-os qa install-browser`, serve the
-  current build, and run `campaigns-os polish capture --packet <packet> --base-url <served-build-url>`
+- When at least one mapped page has a design route, before recording a terminal
+  Polish status, install the package-owned browser once with
+  `npx --no-install campaigns-os qa install-browser`, serve the current build,
+  and run `campaigns-os polish capture --packet <packet> --base-url <served-build-url>`
   (tier `A`: it writes the polish evidence and assembly report under the target
   and fetches the served build at `--base-url`).
   The package captures every mapped route at fixed desktop/mobile viewports and
   attaches `stages.polish.evidence.visual_review.page_load`. Never hand-author,
   copy, or repair that object directly.
+- If every mapped page is template stock (`skip_reason`), there is no design
+  route for that capture. On a local loopback preview, or a hosted preview at
+  the packet's non-loopback HTTP(S) `deploy.preview_url` that differs from
+  `deploy.production_url` by origin or route path, doctor carries the missing
+  evidence forward as a warning. Query or fragment text on the production
+  page does not make it a distinct preview. If the hosted preview URL is not
+  yet recorded, run
+  `campaigns-os qa policy set --packet <packet> --preview-url <url>` first,
+  then `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`. The hosted preview URL satisfies the deploy handoff;
+  after QA records its verdict, run `campaigns-os next --packet <packet>` for
+  closeout. QA against the packet's production URL keeps the checkpoint blocked.
 - When a readability warning appears, report it with its colours, ratio, requirement and pages. Offer the operator options inside the brand palette (a darker or lighter shade of the same hue, the palette's text colour, or a larger, bold label where the design allows). Do not recolour the merchant's design until the operator chooses. Accept a warning only with the refs, reason and name the operator gives you at the QC handoff.
 - Record Polish as `completed`, `skipped`, or `blocked` with
   `campaigns-os record polish --packet <packet> --evidence <polish-evidence.json>`

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

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-qa
-version: 1.3.34
+version: 1.3.39
 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.57.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.57.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.
@@ -110,6 +110,7 @@ Rules:
 - After the base checkout test order redirects to upsell, click the rendered SDK upsell accept/decline controls to prove the live upsell path. Do not fabricate upsell lines with a direct API call.
 - Valid test-order modes are `common`, `checkout`, `accept`, `decline`, `both`, `full`, `off`, and explicit accept/decline paths such as `accept-decline-accept`.
 - Browser test orders default to `--max-test-orders 6` (an accidental-flood guard, not a permission gate). Planning happens before browser launch; when `full` exceeds the cap, use explicit sample paths or rerun with the exact larger cap printed by the command (a linear three-offer graph plans nine orders, so use `--max-test-orders 9`). That cap bounds planned paths; `--max-order-creations` bounds real order creations, defaults to the planned path count, and is reserved before each submit click. A run that hits it stops that path with an explicit budget assertion — read it as a safety stop, not as a checkout defect, and account for the orders already created before raising it.
+- The checkout a test order drives is the Checkout on the tested path: the page typed `checkout`, which takes payment, never the first page typed checkout. On a multi-step path (`select` → `checkout_step`… → `checkout`) the runner enters the cart on the select page (bundle cards plus a checkout button; `--select-package` clicks the matching `data-next-bundle-card`) or on the first step, submits each `checkout_step` form and asserts it lands on the step's declared next page (`checkout_step_submitted`), and submits the order only on the Checkout. A campaign may hold several Checkouts, one per split-test path.
 - Resolve paths from the selected checkout's `expected_next_url`, then follow reachable offer `expected_accept_url` / `expected_decline_url` edges. Treat only declared receipt/thank-you pages and genuine cross-origin handoffs as terminals; an absent same-origin route is unresolved, not an external handoff.
 - `--test-order common` is the default depth. When every actual terminal path fits under the flood cap (`--max-test-orders`, 6 by default), it runs them all and records effective depth `full`, reason `under_cap`. Above the cap it runs checkout, first-offer accept/decline and the shortest real receipt path, then adds the shortest path that clicks the decline on each offer or downsell page no planned path declines yet, until the cap is reached, and names any page left out. It never trims the checkout/accept/decline/receipt sample to fit a lower cap, and it must not synthesize a receipt path from offer count.
 - A page counts as exercised only when an order of its own funnel clicked its decline control. Reaching the page, or clicking only its accept, does not count. `browser-test-order:upsell-action-coverage` reports this for every page with upsell actions in every funnel of the run, and is `pass` or `warn` only when coverage is certain (orders placed, every offer page listed with its own unshared URL, every plan matched to one funnel, every click on a declared page of the order's funnel): `warn` names each page whose decline no order clicked and each funnel no order ran through, `pass` means every page's decline was clicked. Anything uncertain is `manual_review` naming the pages and why (`evidence.reason`, `evidence.not_assessable`, `evidence.uncertainty`), including a `--test-order off` run or attempts that all failed before an order reference. Read `warn` and `manual_review` as missing proof, not as a defect.

package/skills.json

@@ -1,7 +1,7 @@
 {
   "name": "campaigns-os-skills",
   "description": "Skills bundled with Campaigns OS. `skills.sh` installs these into the shared agent skill directories (~/.claude/skills, ~/.codex/skills), so each one is a versioned package: bump the version whenever a package changes. `bundle_revision` identifies the bundle as a whole — `<package version>+skills.<n>`, where the prefix is this package's version and `<n>` counts the skill-text revisions published against it. It advances whenever ANY bundled skill changes, every SKILL.md states it on its first body line, and `campaigns-os tooling status --skills-revision <value>` compares the value an agent read from a skill against the bundle on disk. See docs/skills-revision.md.",
-  "bundle_revision": "1.54.0+skills.1",
+  "bundle_revision": "1.57.0+skills.1",
   "homepage": "https://github.com/NextCommerceCo/campaigns-os",
   "retired_skills": [
     {
@@ -16,7 +16,7 @@
     {
       "id": "next-campaigns-os",
       "name": "Campaigns OS Lifecycle",
-      "version": "1.0.50",
+      "version": "1.0.55",
       "path": "skills/next-campaigns-os/SKILL.md",
       "domain": "campaigns",
       "description": "Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth."
@@ -24,7 +24,7 @@
     {
       "id": "next-campaigns-os-setup",
       "name": "Campaigns OS Setup",
-      "version": "2.0.33",
+      "version": "2.0.38",
       "path": "skills/next-campaigns-os-setup/SKILL.md",
       "domain": "campaigns",
       "description": "Bootstrap or prepare a target page-kit campaign repo from a doctor-cleared Campaigns OS Build Packet before full build wiring. Formerly next-campaigns-setup; renamed to release that name to the published NextCommerceCo/skills scaffolder."
@@ -32,7 +32,7 @@
     {
       "id": "next-campaigns-build",
       "name": "Campaign Build",
-      "version": "1.0.35",
+      "version": "1.0.40",
       "path": "skills/next-campaigns-build/SKILL.md",
       "domain": "campaigns",
       "description": "Assemble a NEXT campaign from a doctor-cleared Build Packet, CampaignSpec/API values, prepared HTML/assets, page-kit, and starter-template contracts."
@@ -40,7 +40,7 @@
     {
       "id": "next-campaigns-polish",
       "name": "Campaign Polish",
-      "version": "1.1.34",
+      "version": "1.1.40",
       "path": "skills/next-campaigns-polish/SKILL.md",
       "domain": "campaigns",
       "description": "Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign."
@@ -48,7 +48,7 @@
     {
       "id": "next-campaigns-qa",
       "name": "Campaign QA",
-      "version": "1.3.34",
+      "version": "1.3.39",
       "path": "skills/next-campaigns-qa/SKILL.md",
       "domain": "campaigns",
       "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."
@@ -56,7 +56,7 @@
     {
       "id": "campaign-lifecycle-orientation",
       "name": "Campaign Lifecycle Orientation",
-      "version": "1.0.30",
+      "version": "1.0.35",
       "path": "skills/campaign-lifecycle-orientation/SKILL.md",
       "domain": "campaigns",
       "description": "Orient a reader to the Campaigns OS lifecycle artifacts a run has already emitted, without advancing their state: the shared vocabulary, doctor as a gate, the stage record, and the store-theme/Page Kit two-worlds trap."
@@ -64,7 +64,7 @@
     {
       "id": "campaign-run-evidence",
       "name": "Campaign Run Evidence",
-      "version": "1.0.30",
+      "version": "1.0.35",
       "path": "skills/campaign-run-evidence/SKILL.md",
       "domain": "campaigns",
       "description": "Interpret existing doctor, QA verdict and proof-depth evidence without claiming more proof than the artifacts contain, and keep funnel proof apart from merchant launch readiness."
@@ -72,7 +72,7 @@
     {
       "id": "campaign-readback-classification",
       "name": "Campaign Readback Classification",
-      "version": "1.0.30",
+      "version": "1.0.35",
       "path": "skills/campaign-readback-classification/SKILL.md",
       "domain": "campaigns",
       "description": "Classify a selected campaign from the campaigns-os-readback/v2 fields (artifacts, staleness.stale_keys, clean, doctor, divergences, skip_cascades) and write a read-only handoff without turning diagnosis into permission."
@@ -80,7 +80,7 @@
     {
       "id": "contribution-intake",
       "name": "Contribution Intake",
-      "version": "1.0.30",
+      "version": "1.0.35",
       "path": "skills/contribution-intake/SKILL.md",
       "domain": "campaigns",
       "description": "Turn a suggestion about the agent surface into a classified, evidence-checked and redacted proposal, filed on this repository tracker only with attended approval."

package/src/adapter-decision-contract.mjs

@@ -38,7 +38,7 @@ export const TEMPLATE_SLICE_REQUIRED_GROUPS = Object.freeze([
 ]);
 
 const TEMPLATE_FILES_COPIED_REQUIRED_FIELDS = Object.freeze(["status", "required_groups", "groups", "paths"]);
-const RUNTIME_PAGE_TYPES = new Set(["checkout", "select", "upsell", "downsell", "thankyou", "receipt"]);
+const RUNTIME_PAGE_TYPES = new Set(["checkout", "checkout_step", "select", "upsell", "downsell", "thankyou", "receipt"]);
 const RAW_HTML_CONVERSION_STATUSES = new Set(["pending", "in_progress", "completed", "not_required", "blocked"]);
 const SOURCE_ASSET_STRATEGIES = new Set(["pagekit_campaign_asset_root", "external_cdn", "raw_passthrough", "not_applicable", "unknown"]);
 const ROUTE_REWRITE_POLICIES = new Set(["campaignspec_routes_via_campaign_link", "pagekit_public_routes", "raw_passthrough", "not_applicable", "unknown"]);
@@ -66,6 +66,20 @@ const SCRIPT_STYLE_REFERENCE_POLICIES = new Set(["frontmatter_or_campaign_asset"
 const CTA_REWRITE_POLICIES = ROUTE_REWRITE_POLICIES;
 const LAYOUT_CHOICES = new Set(["campaign_layout", "page_layout", "raw_passthrough", "not_applicable", "unknown"]);
 
+// The scalar choices record build can set; the object-valued template slice
+// stays with its existing proof fields and doctor checks.
+export const ADAPTER_DECISION_SCALAR_VALUES = Object.freeze(Object.assign(Object.create(null), {
+  raw_html_conversion_status: [...RAW_HTML_CONVERSION_STATUSES],
+  source_asset_strategy: [...SOURCE_ASSET_STRATEGIES],
+  commerce_shell_adoption: [...COMMERCE_SHELL_ADOPTIONS],
+  route_rewrite_policy: [...ROUTE_REWRITE_POLICIES],
+  config_script_strategy: [...CONFIG_SCRIPT_STRATEGIES],
+  frontmatter_policy: [...FRONTMATTER_POLICIES],
+  script_style_reference_policy: [...SCRIPT_STYLE_REFERENCE_POLICIES],
+  cta_rewrite_policy: [...CTA_REWRITE_POLICIES],
+  layout_choice: [...LAYOUT_CHOICES],
+}));
+
 /**
  * Seeds the adapter decision record written onto a new Build Packet.
  *
@@ -170,7 +184,7 @@ export function validateAdapterSourceFiles({ decisions, sourceRoot, pages = [],
   addIssue(
     warnings,
     "source_html.raw_html_wrappers",
-    `source_html.adapter_contract.raw_html_conversion_status is "${status}", but mapped source HTML still contains document wrapper tags: ${sample}${more}. Strip <!doctype>, <html>, <head>, and <body> before treating the page as page-kit-ready source.`
+    `Effective raw_html_conversion_status is "${status}", but mapped source HTML still contains document wrapper tags: ${sample}${more}. Strip <!doctype>, <html>, <head>, and <body> before treating the page as page-kit-ready source.`
   );
 }
 
@@ -184,32 +198,32 @@ export function validateAdapterDecisionGates({ decisions, location, specPages =
       addIssue(
         warnings,
         "adapter.raw_html_conversion_status",
-        `Assembly is recorded complete, but ${location}.raw_html_conversion_status is "${decisions.raw_html_conversion_status}". Record completed/not_required after wrapper stripping, frontmatter, asset moves, script/style refs, CTA rewrites, route policy, and layout choice are settled.`
+        `Assembly is recorded complete, but ${location}.raw_html_conversion_status is "${decisions.raw_html_conversion_status}". Use record build --adapter-decision raw_html_conversion_status=<value> to record completed/not_required after wrapper stripping, frontmatter, asset moves, script/style refs, CTA rewrites, route policy, and layout choice are settled.`
       );
     }
     if (["raw_passthrough", "unknown"].includes(decisions.source_asset_strategy)) {
-      addIssue(warnings, "adapter.source_asset_strategy", `Assembly is recorded complete with ${location}.source_asset_strategy="${decisions.source_asset_strategy}". Page-kit builds should normally use pagekit_campaign_asset_root so src/<slug>/assets/* publishes at /<slug>/*.`);
+      addIssue(warnings, "adapter.source_asset_strategy", `Assembly is recorded complete with ${location}.source_asset_strategy="${decisions.source_asset_strategy}". Use record build --adapter-decision source_asset_strategy=<value> to record pagekit_campaign_asset_root when src/<slug>/assets/* publishes at /<slug>/*.`);
     }
     if (["raw_passthrough", "unknown"].includes(decisions.route_rewrite_policy)) {
-      addIssue(warnings, "adapter.route_rewrite_policy", `Assembly is recorded complete with ${location}.route_rewrite_policy="${decisions.route_rewrite_policy}". Record how CampaignSpec routes and CTA destinations were rewritten before QA.`);
+      addIssue(warnings, "adapter.route_rewrite_policy", `Assembly is recorded complete with ${location}.route_rewrite_policy="${decisions.route_rewrite_policy}". Use record build --adapter-decision route_rewrite_policy=<value> to record how CampaignSpec routes and CTA destinations were rewritten before QA.`);
     }
     if (decisions.config_script_strategy === "unknown") {
-      addIssue(warnings, "adapter.config_script_strategy", `Assembly is recorded complete but ${location}.config_script_strategy is unknown. Record whether config scripts load via campaign assets, frontmatter scripts, inline config, or not_required.`);
+      addIssue(warnings, "adapter.config_script_strategy", `Assembly is recorded complete but ${location}.config_script_strategy is unknown. Use record build --adapter-decision config_script_strategy=<value> to record whether config scripts load via campaign assets, frontmatter scripts, inline config, or not_required.`);
     }
     if (["preserve_document_wrappers", "unknown"].includes(decisions.wrapper_policy)) {
-      addIssue(warnings, "adapter.wrapper_policy", `Assembly is recorded complete with ${location}.wrapper_policy="${decisions.wrapper_policy}". Page-kit source should normally strip document wrappers unless preserving them is explicitly not_required.`);
+      addIssue(warnings, "adapter.wrapper_policy", `Assembly is recorded complete with ${location}.wrapper_policy="${decisions.wrapper_policy}". Select wrapper_policy at intake with prepare-build --wrapper-policy or the source-html manifest's wrapper_policy option; page-kit source should normally strip document wrappers unless preserving them is explicitly not_required.`);
     }
     if (["raw_passthrough", "unknown"].includes(decisions.frontmatter_policy)) {
-      addIssue(warnings, "adapter.frontmatter_policy", `Assembly is recorded complete with ${location}.frontmatter_policy="${decisions.frontmatter_policy}". Record how Page Kit YAML frontmatter was created or why it is not_required.`);
+      addIssue(warnings, "adapter.frontmatter_policy", `Assembly is recorded complete with ${location}.frontmatter_policy="${decisions.frontmatter_policy}". Use record build --adapter-decision frontmatter_policy=<value> to record how Page Kit YAML frontmatter was created or why it is not_required.`);
     }
     if (["raw_passthrough", "unknown"].includes(decisions.script_style_reference_policy)) {
-      addIssue(warnings, "adapter.script_style_reference_policy", `Assembly is recorded complete with ${location}.script_style_reference_policy="${decisions.script_style_reference_policy}". Record how scripts/styles load via frontmatter, campaign assets, inline blocks, or not_required.`);
+      addIssue(warnings, "adapter.script_style_reference_policy", `Assembly is recorded complete with ${location}.script_style_reference_policy="${decisions.script_style_reference_policy}". Use record build --adapter-decision script_style_reference_policy=<value> to record how scripts/styles load via frontmatter, campaign assets, inline blocks, or not_required.`);
     }
     if (["raw_passthrough", "unknown"].includes(decisions.cta_rewrite_policy)) {
-      addIssue(warnings, "adapter.cta_rewrite_policy", `Assembly is recorded complete with ${location}.cta_rewrite_policy="${decisions.cta_rewrite_policy}". Record how CTA destinations were rewritten from CampaignSpec routes before QA.`);
+      addIssue(warnings, "adapter.cta_rewrite_policy", `Assembly is recorded complete with ${location}.cta_rewrite_policy="${decisions.cta_rewrite_policy}". Use record build --adapter-decision cta_rewrite_policy=<value> to record how CTA destinations were rewritten from CampaignSpec routes before QA.`);
     }
     if (["raw_passthrough", "unknown"].includes(decisions.layout_choice)) {
-      addIssue(warnings, "adapter.layout_choice", `Assembly is recorded complete with ${location}.layout_choice="${decisions.layout_choice}". Record the Page Kit layout strategy before handoff.`);
+      addIssue(warnings, "adapter.layout_choice", `Assembly is recorded complete with ${location}.layout_choice="${decisions.layout_choice}". Use record build --adapter-decision layout_choice=<value> to record the Page Kit layout strategy before handoff.`);
     }
   }
 
@@ -219,13 +233,13 @@ export function validateAdapterDecisionGates({ decisions, location, specPages =
       addIssue(
         errors,
         "adapter.commerce_shell_adoption",
-        `Runtime commerce pages (${runtimePages.map((page) => page.id).join(", ")}) are marked custom_html_experimental for template family "${family}". Use template_clone_first_verified or sdk_surfaces_preserved before treating checkout/upsell/downsell/receipt as build-ready.`
+        `Runtime commerce pages (${runtimePages.map((page) => page.id).join(", ")}) are marked custom_html_experimental for template family "${family}". Use record build --adapter-decision commerce_shell_adoption=<value> to record template_clone_first_verified or sdk_surfaces_preserved before treating checkout/upsell/downsell/receipt as build-ready.`
       );
     } else if (assemblyComplete && !["template_clone_first_verified", "sdk_surfaces_preserved"].includes(adoption)) {
       addIssue(
         warnings,
         "adapter.commerce_shell_adoption",
-        `Assembly is recorded complete, but ${location}.commerce_shell_adoption is "${adoption || "missing"}" for runtime commerce pages (${runtimePages.map((page) => page.id).join(", ")}). Commerce pages should be template-clone-first, then styled, with SDK-owned surfaces preserved.`
+        `Assembly is recorded complete, but ${location}.commerce_shell_adoption is "${adoption || "missing"}" for runtime commerce pages (${runtimePages.map((page) => page.id).join(", ")}). Use record build --adapter-decision commerce_shell_adoption=<value> after commerce pages are template-clone-first, then styled, with SDK-owned surfaces preserved.`
       );
     }
   }