@nextcommerce/campaigns-os 1.57.0 → 1.59.0

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

@@ -119,15 +119,14 @@ checks are carried forward:
 
 A carried-forward gate has status `carried_forward`. Doctor reports it as a
 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
+polish to deploy and QA; 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. 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
+record the deploy with `campaigns-os record deploy --packet <packet> --base-url <preview-url>`
+(on a hosted target it takes an https URL, requires every built page to answer
+200, and compares the served scripts and stylesheets with the build by sha256),
+then run `campaigns-os qa run --packet <packet> --base-url <preview-url> --browser --test-order common`. After QA records the current-build verdict, run `campaigns-os next --packet <packet>` for closeout. 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
@@ -1345,6 +1344,7 @@ Assembly Report's `stages.qa`:
   "declared_order_path_depth": "common",
   "declared_typed_card_depth": "common",
   "order_paths_executed": 3,
+  "test_order_attempts": 3,
   "orders_created": 3,
   "orders_verified": 3,
   "all_orders_test_mode": true
@@ -1357,7 +1357,9 @@ readback bundle, where the verdict's own order arrays are deliberately emptied
 (see the committed verdict sidecar above) — so the signal that a purchase
 happened has to be numbers, not the orders themselves. `all_orders_test_mode` is
 `null`, not `false`, when nothing ran: "no order left test mode" and "no order
-ran" are different facts.
+ran" are different facts. `order_paths_executed` counts planned paths and
+`test_order_attempts` counts every attempt, so a re-run adds an attempt and not a
+path.
 
 Beside it, `stages.qa.evidence` carries the build the verdict judged and the
 outcome of the gates doctor's static scan can only approximate:
@@ -1554,16 +1556,49 @@ 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`,
 `checkout_link`, or `checkout_button`), `package_id`, `bundle_card_selection`
-when `--select-package` clicked a bundle card, `sdk_ready`, `arrived_url`, the
+when `--select-package` clicked a bundle card, `variant_selections` when the
+runner chose slot variants (below), `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
 `cart_entry_unresolved` (no selection surface on checkout and no entry page
 resolves from the topology), `cart_entry_control_missing` (the entry page
 renders no control, or none carrying the requested ref), and
-`cart_entry_no_navigation` (the click did not reach the checkout URL). Each
-fails the path inside the step budget with the code as the first word of the
-error, never as a step timeout.
+`cart_entry_no_navigation` (the click did not reach the checkout URL), and
+`cart_entry_variant_unfilled` (a bundle slot's variant control has no in-stock
+option or row, or its row could not be clicked, named by slot). Each fails the path inside the step budget with the
+code as the first word of the error, never as a step timeout.
+
+On a select page whose bundle slots each need a variant (size, colour) before
+Next, the runner chooses one per slot after any bundle card click and before
+the checkout control, one field at a time. It looks at every visible, enabled
+slot variant select (`[data-next-variant-selectors] select` or
+`.next-slot-variant-field select`, the native select the SDK renders, counted
+visible when its field is):
+
+- When the field shows a dropdown UI (an `os-dropdown` with a
+  `.os-card__variant-dropdown-toggle` and `os-dropdown-item` rows, as the
+  olympus-mv-two-step starter renders), the runner clicks the toggle and then a
+  row, like a shopper, even when the select is already filled. A page may count
+  a field as chosen only when a row was clicked. It clicks the row matching the
+  select's current value when that row is in stock, so the cart stays what the
+  SDK chose, and otherwise the first in-stock row. After the toggle click it
+  finds the field again by slot identity and the row again by its value, and
+  waits up to 2 s for that row to show, so a menu that opens late or re-renders
+  its rows is handled.
+- With no dropdown UI, an empty select gets its first in-stock option, with
+  `input` and `change` dispatched. A filled native select is left alone.
+
+In stock means enabled, not hidden, and with a non-empty value. For a row it
+also means not `[disabled]`, `aria-disabled`, `.next-oos`,
+`.next-variant-unavailable` or `data-available="false"`, and that the row's
+native option is not disabled. Each choice is recorded in
+`variant_selections` as `{ bundle_id, slot, variant_code, value, via }`, where
+`via` is `dropdown` or `select`, so the ordered variants can be checked against
+the cart lines. A field with nothing to choose, or a row that does not show
+or cannot be clicked, fails the path with `cart_entry_variant_unfilled` before Next is
+clicked. A page whose filled selects have no dropdown UI is left untouched and
+`variant_selections` is omitted.
 
 Which page a funnel enters the cart from is still inferred from topology and
 the rendered checkout. Recording it authoritatively on the spec is the open
@@ -1840,7 +1875,7 @@ deciding what to do next, it classifies what the attempt did to the store:
 
 | Classification | What it means | What the runner does |
 |---|---|---|
-| `not_created` | The path failed before the checkout was submitted (including the runner's own named refusals: `cart_entry_unresolved`, `cart_entry_control_missing`, `cart_entry_no_navigation`, `cart_empty_before_submit`), or the platform rejected every order create it saw. Nothing reached the store. | Re-runs the path once, if the creation budget has a slot no still-unrun planned path needs. This is the bounded retry for a transient miss; the re-run decides the assertion. |
+| `not_created` | The path failed before the checkout was submitted (including the runner's own named refusals: `cart_entry_unresolved`, `cart_entry_control_missing`, `cart_entry_no_navigation`, `cart_entry_variant_unfilled`, `cart_empty_before_submit`), or the platform rejected every order create it saw. Nothing reached the store. | Re-runs the path once, if the creation budget has a slot no still-unrun planned path needs. This is the bounded retry for a transient miss; the re-run decides the assertion. |
 | `created` | An order exists and was read back — the failure happened after the purchase (most often a receipt that did not render its line items). | Runs a **read-only recovery pass**: reloads the receipt the order already produced, re-reads the persisted order, and re-checks the buyer-visible receipt surface and the voucher read-back. It clicks nothing, applies nothing, and submits nothing. |
 | `ambiguous` | The submit may have created an order this runner cannot see: a ref id with an unusable read-back, a lost create response, a network-failed create, or a 4xx that follows an earlier 2xx on the same endpoint. | Stops. It never resubmits, and the assertion names the check an operator should run — look for an existing order against the run's QA email or the observed ref id. |
 
@@ -1865,6 +1900,13 @@ is not re-run and its assertion records why under
 re-runs for those paths. A re-run that stops on the budget never becomes the
 deciding result: it proved nothing, so the first attempt's real failure stands.
 
+Every attempt is its own `test_orders[]` entry, because a re-run can place its
+own real order. Each entry carries `plan_id`, the planned path it belongs to,
+and `attempt`, 1 for the first try and 2 for the re-run, so a run with five
+planned paths that each re-ran once holds ten entries for five paths. The
+`qa run` summary prints the three counts apart, for example
+`Test orders: 5 paths, 10 attempts, 0 orders created`.
+
 Recovery may only clear a failure on evidence it actually re-read. If the
 receipt reload's persisted-order read-back fails or never happens, the pass stops
 honestly: the read-back failure is itself a remaining failure, and the receipt

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.3`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.57.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.59.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.57.0+skills.1"
+"bundle_revision": "1.59.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.57.0+skills.1` is therefore ahead of `1.40.0+skills.7`.
+  with the prefix**. `1.59.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.57.0+skills.1
+Bundle revision: 1.59.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.57.0+skills.1
+npx --no-install campaigns-os tooling status --skills-revision 1.59.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.57.0+skills.1",
+  "requested": "1.59.0+skills.1",
   "spelling": "bundle",
-  "on_disk": "1.57.0+skills.1",
+  "on_disk": "1.59.0+skills.1",
   "on_disk_skill": null,
-  "message": "match (1.57.0+skills.1)"
+  "message": "match (1.59.0+skills.1)"
 }
 ```
 
 The text view prints one named line, as a header above the rest of the status:
 
 ```
-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)
+Skills revision: match (1.59.0+skills.1)
+Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.59.0+skills.1 — start a fresh session
+Skills revision: unchecked (on disk 1.59.0+skills.1)
 ```
 
 `unchecked` is the state when the flag is absent. It is not an error — an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextcommerce/campaigns-os",
-  "version": "1.57.0",
+  "version": "1.59.0",
   "description": "Toolkit for agent-assisted NEXT campaign builds.",
   "license": "Apache-2.0",
   "repository": {

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

@@ -192,7 +192,8 @@
                   "permalink": { "type": "string", "minLength": 1 },
                   "next_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)." },
+                  "next_step": { "type": "string", "minLength": 1, "description": "On a select or checkout_step page on a path to a Checkout: this page's forward link, for the step form's data-next-checkout-step or the select page's checkout link. next_url on such a page is the Checkout's post-payment destination, for the next-success-url meta tag the SDK reads for express orders (campaign-cart-starter-templates#223)." },
+                  "success_url": { "type": "string", "minLength": 1, "description": "No longer emitted: the starter templates read the post-payment destination from next_url and the forward link from next_step. Accepted so packets written by 1.56.0 and 1.57.0 still validate." },
                   "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

@@ -194,7 +194,8 @@
                       "permalink": { "type": "string", "minLength": 1 },
                       "next_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)." },
+                      "next_step": { "type": "string", "minLength": 1, "description": "On a select or checkout_step page on a path to a Checkout: this page's forward link, for the step form's data-next-checkout-step or the select page's checkout link. next_url on such a page is the Checkout's post-payment destination, for the next-success-url meta tag the SDK reads for express orders (campaign-cart-starter-templates#223)." },
+                      "success_url": { "type": "string", "minLength": 1, "description": "No longer emitted: the starter templates read the post-payment destination from next_url and the forward link from next_step. Accepted so packets written by 1.56.0 and 1.57.0 still validate." },
                       "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/skills/campaign-lifecycle-orientation/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: campaign-lifecycle-orientation
-version: 1.0.35
+version: 1.0.37
 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.57.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.57.0+skills.1`
+Bundle revision: 1.59.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.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.35
+version: 1.0.37
 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.57.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.57.0+skills.1`
+Bundle revision: 1.59.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.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.35
+version: 1.0.37
 description: Interpret existing Campaigns OS doctor, QA and proof-depth evidence without claiming more proof than the artifacts contain.
 ---
 
-Bundle revision: 1.57.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.57.0+skills.1`
+Bundle revision: 1.59.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.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.35
+version: 1.0.37
 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.57.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.57.0+skills.1`
+Bundle revision: 1.59.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.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.40
+version: 1.0.42
 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.57.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.57.0+skills.1`
+Bundle revision: 1.59.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.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,9 +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.
-- 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.
+- 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_step`) 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_step>"` and `data-next-step-number="<step_number>"` (frontmatter `next_step` and `step_number`, 1 for the first step on its path). The `checkout` page's form carries neither.
+- On `select` and `checkout_step` pages, frontmatter `next_url` is the Checkout's post-payment destination, the same meaning it has on the `checkout` page, and the layout renders it as the `next-success-url` meta tag: the SDK reads that tag for express orders placed on the page. `next_step` is the page's forward link. A landing page keeps `next_url` as its call-to-action target; if it has express checkout buttons, set its `next-success-url` to the Checkout's own `next_url` from the Build Context `page_map`, never to the landing page's `next_url`. Forward navigation uses the step form attribute or a plain link, never that meta tag. Page Kit frontmatter has no `success_url` key; `success_url` stays a CampaignSpec field on `checkout` pages.
 - 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.55
+version: 1.0.57
 description: Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth.
 ---
 
-Bundle revision: 1.57.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.57.0+skills.1`
+Bundle revision: 1.59.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.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.38
+version: 2.0.40
 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.57.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.57.0+skills.1`
+Bundle revision: 1.59.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.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.40
+version: 1.1.42
 description: Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign.
 ---
 
-Bundle revision: 1.57.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.57.0+skills.1`
+Bundle revision: 1.59.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.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.39
+version: 1.3.41
 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.57.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.57.0+skills.1`
+Bundle revision: 1.59.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.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.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.57.0+skills.1",
+  "bundle_revision": "1.59.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.55",
+      "version": "1.0.57",
       "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.38",
+      "version": "2.0.40",
       "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.40",
+      "version": "1.0.42",
       "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.40",
+      "version": "1.1.42",
       "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.39",
+      "version": "1.3.41",
       "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.35",
+      "version": "1.0.37",
       "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.35",
+      "version": "1.0.37",
       "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.35",
+      "version": "1.0.37",
       "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.35",
+      "version": "1.0.37",
       "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/built-site-scope.mjs

@@ -355,3 +355,94 @@ export function computeBuildFingerprint(outputDir, { exclude = [] } = {}) {
     error: null,
   };
 }
+
+// The manifest as `{ path, sha256 }` entries, the shape `record build` keeps
+// on stages.assembly.build_manifest beside build_fingerprint so a later
+// mismatch can name the files that differ instead of only two hashes.
+export function buildManifestEntries(fingerprint) {
+  const lines = String(fingerprint?.manifest || "").split("\n");
+  const entries = [];
+  for (let index = 0; index + 1 < lines.length; index += 2) {
+    if (lines[index]) entries.push({ path: lines[index], sha256: lines[index + 1] });
+  }
+  return entries;
+}
+
+const SHA256_HEX = /^[a-f0-9]{64}$/;
+
+// The recorded manifest, only when it is evidence about the recorded build:
+// well-formed entries whose canonical manifest hashes to the recorded
+// fingerprint. A record made before build kept a manifest, or one rewritten
+// by hand, reads as unavailable (null) rather than as a misleading diff.
+export function recordedBuildManifest(assembly) {
+  const entries = assembly?.build_manifest;
+  const recorded = assembly?.build_fingerprint;
+  if (!Array.isArray(entries) || typeof recorded !== "string") return null;
+  if (!entries.every((entry) => typeof entry?.path === "string" && entry.path && typeof entry?.sha256 === "string" && SHA256_HEX.test(entry.sha256))) return null;
+  const manifest = entries.map((entry) => `${entry.path}\n${entry.sha256}\n`).join("");
+  return `sha256:${sha256Hex(Buffer.from(manifest, "utf8"))}` === recorded ? entries : null;
+}
+
+// macOS and iCloud name a sync conflict copy `<name> 2.<ext>` (then ` 3`,
+// ...), on files and on folders. A trailing " N" alone is too common in real
+// names ("chapter 12.md"), so a path counts as a copy only when the same path
+// without the suffix also exists. The flag is a hint, never a verdict.
+const CONFLICT_COPY_SEGMENT = /^(.+) (?:[2-9]|[1-9]\d+)(\.[^.]+)?$/;
+export function isSyncConflictCopyPath(path, knownPaths) {
+  const segments = String(path).split("/");
+  const known = [...knownPaths];
+  return segments.some((segment, index) => {
+    const match = CONFLICT_COPY_SEGMENT.exec(segment);
+    if (!match) return false;
+    const original = [...segments.slice(0, index), `${match[1]}${match[2] ?? ""}`].join("/");
+    return index === segments.length - 1
+      ? known.includes(original)
+      : known.some((candidate) => candidate.startsWith(`${original}/`));
+  });
+}
+
+export const BUILD_DRIFT_PATH_LIMIT = 20;
+
+/**
+ * Compare the output on disk (a computeBuildFingerprint result) with the
+ * manifest stages.assembly recorded. Returns
+ *   { manifest: "recorded", extra, missing, changed, conflict_copies, summary }
+ * with sorted path lists, or { manifest: "unavailable", summary } when the
+ * record carries no usable manifest. `summary` is one sentence for a
+ * refusal: each list capped at BUILD_DRIFT_PATH_LIMIT with "+N more".
+ */
+export function describeBuildOutputDrift(assembly, current) {
+  const recorded = recordedBuildManifest(assembly);
+  if (!recorded) {
+    return {
+      manifest: "unavailable",
+      summary: "The build record carries no file manifest (it was recorded before record build kept one), so the differing paths cannot be named; re-run record build to record one.",
+    };
+  }
+  const before = new Map(recorded.map((entry) => [entry.path, entry.sha256]));
+  const now = new Map(buildManifestEntries(current).map((entry) => [entry.path, entry.sha256]));
+  const extra = [...now.keys()].filter((path) => !before.has(path));
+  const missing = [...before.keys()].filter((path) => !now.has(path));
+  const changed = [...now.keys()].filter((path) => before.has(path) && before.get(path) !== now.get(path));
+  const knownPaths = new Set([...before.keys(), ...now.keys()]);
+  const isCopy = (path) => isSyncConflictCopyPath(path, knownPaths);
+  const conflictCopies = extra.filter(isCopy);
+  const list = (label, paths) => {
+    if (paths.length === 0) return null;
+    const shown = paths.slice(0, BUILD_DRIFT_PATH_LIMIT).map((path) => (isCopy(path) ? `${path} [sync conflict copy]` : path));
+    const more = paths.length > BUILD_DRIFT_PATH_LIMIT ? ` (+${paths.length - BUILD_DRIFT_PATH_LIMIT} more)` : "";
+    return `${paths.length} ${label}: ${shown.join(", ")}${more}`;
+  };
+  const parts = [list("extra", extra), list("missing", missing), list("changed", changed)].filter(Boolean);
+  const hint = conflictCopies.length
+    ? ` ${conflictCopies.length} extra file name(s) look like macOS/iCloud sync conflict copies ("<name> 2.<ext>" beside "<name>.<ext>"); if they are, remove them (or move the repo out of the synced folder) and rebuild.`
+    : "";
+  return {
+    manifest: "recorded",
+    extra,
+    missing,
+    changed,
+    conflict_copies: conflictCopies,
+    summary: `Against the manifest build recorded: ${parts.length ? parts.join("; ") : "no path differs"}.${hint}`,
+  };
+}