@nextcommerce/campaigns-os 1.55.0 → 1.59.0

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.55.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.55.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.55.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.55.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.55.0+skills.1",
+  "requested": "1.59.0+skills.1",
   "spelling": "bundle",
-  "on_disk": "1.55.0+skills.1",
+  "on_disk": "1.59.0+skills.1",
   "on_disk_skill": null,
-  "message": "match (1.55.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.55.0+skills.1)
-Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.55.0+skills.1 — start a fresh session
-Skills revision: unchecked (on disk 1.55.0+skills.1)
+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/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). 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. |
+| `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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextcommerce/campaigns-os",
-  "version": "1.55.0",
+  "version": "1.59.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",

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

@@ -191,7 +191,10 @@
                   },
                   "permalink": { "type": "string", "minLength": 1 },
                   "next_url": { "type": "string", "minLength": 1 },
-                  "decline_url": { "type": "string", "minLength": 1 }
+                  "decline_url": { "type": "string", "minLength": 1 },
+                  "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

@@ -193,7 +193,10 @@
                       },
                       "permalink": { "type": "string", "minLength": 1 },
                       "next_url": { "type": "string", "minLength": 1 },
-                      "decline_url": { "type": "string", "minLength": 1 }
+                      "decline_url": { "type": "string", "minLength": 1 },
+                      "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." }
                     }
                   }
                 },