@nextcommerce/campaigns-os 1.63.0 → 1.66.0

package/docs/build-packet.md

@@ -1339,7 +1339,7 @@ than hand-adding the field. Note that a committed artifact set always reads
 stale to the readback once HEAD moves past it — freshness proof is a
 regeneration at HEAD, not a property a commit can preserve.
 
-Commit durable packet/context/report artifacts when they represent a real build handoff. The rest of `.campaign-runtime/` is machine-local and is not for the campaign repository: `run-session.json`, `command-lifecycle.jsonl`, `agent-deviations.jsonl`, `workflow-findings.jsonl`, `run-records/`, `fetched-specs/`, `progress/`, `polish-evidence/`, `evidence/`, and `*.log`/`*.tmp` are per-machine, append-only, or carry live URLs and absolute paths, and so are the full QA verdicts `qa run` writes under the target's `qa-output/`. `start`, `prepare-build`, `install-agent-context`, and `run start` write a managed ignore block for that set into the target's `.gitignore` (keyed on its marker line; edit the list beneath it freely). The block also lists `.campaign-runtime/funnels/*/run-records/` for the Run Records of a project's second and later funnels. An existing block gains `qa-output/`, `.campaign-runtime/progress/` and `.campaign-runtime/funnels/*/run-records/` when they are missing, since those hold live URLs, order references and remit records. The readback bundle (`build-context.json`, `assembly-report.json`, `doctor-output.json`, `qa-verdict.json`), `input/`, `theme/`, `agent-context/`, and `setup-handoff.json` are deliberately not ignored, at the top level or under `funnels/<route>/`. The Campaigns API key is a public, browser-side, domain-allowlisted key and may already be present in the local CampaignSpec as `campaign.campaigns_api_key`; do not duplicate it into the packet unless the spec is unavailable. Do not commit raw private API responses, backend secrets, or temporary media exports.
+Commit durable packet/context/report artifacts when they represent a real build handoff. The rest of `.campaign-runtime/` is machine-local and is not for the campaign repository: `run-session.json`, `command-lifecycle.jsonl`, `agent-deviations.jsonl`, `workflow-findings.jsonl`, `run-records/`, `progress/`, `polish-evidence/`, `evidence/`, and `*.log`/`*.tmp` are per-machine, append-only, or carry live URLs and absolute paths, and so are the full QA verdicts `qa run` writes under the target's `qa-output/`. `start`, `prepare-build`, `install-agent-context`, and `run start` write a managed ignore block for that set into the target's `.gitignore` (keyed on its marker line; edit the list beneath it freely). The block also lists `.campaign-runtime/funnels/*/run-records/` for the Run Records of a project's second and later funnels. An existing block gains `qa-output/`, `.campaign-runtime/progress/` and `.campaign-runtime/funnels/*/run-records/` when they are missing, since those hold live URLs, order references and remit records. An existing block also loses `.campaign-runtime/fetched-specs/`, which earlier versions listed. The readback bundle (`build-context.json`, `assembly-report.json`, `doctor-output.json`, `qa-verdict.json`), `fetched-specs/`, `input/`, `theme/`, `agent-context/`, and `setup-handoff.json` are deliberately not ignored, at the top level or under `funnels/<route>/`. The Campaigns API key is a public, browser-side, domain-allowlisted key and may already be present in the local CampaignSpec as `campaign.campaigns_api_key`; do not duplicate it into the packet unless the spec is unavailable. Do not commit raw private API responses, backend secrets, or temporary media exports.
 
 Packet-mode `doctor` is inspection-only by default and preserves retained evidence and active run journals, even when lifecycle capture is configured. Use `--write` to intentionally record fresh evidence; `--no-write` takes precedence. Inspection still reports current blockers and keeps the same exit status.
 
@@ -1527,7 +1527,9 @@ root and is not hashed. Build does not type the value: after page-kit build it r
 `campaigns-os record build --packet <packet>`, which stamps doctor's
 `derived.build_output_fingerprint.value` onto `stages.assembly.build_fingerprint`
 (see "Recording stage completion" below). Doctor recomputes the value on every run
-(`built_output.fingerprint`): a match is a ready line, a missing record is the
+(`built_output.fingerprint`): a match is a ready line, no built output after a
+completed build is the warning `built_output.absent` (nothing was compared with
+this checkout, so build it before reading the records as current), a missing record is the
 warning `built_output.fingerprint_missing` carrying the value to record, and a
 recorded value the output no longer matches is `built_output.fingerprint_stale`
 (blocking once assembly is complete). The polish gate, QA, and `polish capture`
@@ -1580,8 +1582,11 @@ change from a commerce-affecting one
 
 Readback's `evidence_debt.<stage>.change` and `doctor --ci` read these, so the
 changed-page list survives `record build`. A record made before these fields
-existed has no signature, and its next change reads as unknown (full Polish and
-QA) until `record build` records one.
+existed has no signature, and its next change reads as commerce-affecting, with
+the reason `commerce_signature_unavailable`, whatever the change was. `record
+build` keeps a signature from then on, but the QA it would extend is still
+anchored before that rebuild. So page-only changes start after one full QA on
+1.62.0 or later, or after [a baseline](campaigns-os-build-flow.md#accepting-a-funnel-from-before-1620).
 
 A stale or missing Assembly Source Package Fingerprint is waivable only as an
 exceptional Source Freshness Waiver. The waiver must be structured in
@@ -1779,7 +1784,8 @@ When `--map-id <id>` is set, the CLI fetches `GET <proxy>/api/spec/<id>` (defaul
 
 Saved-Map retrieval behavior (`--map-id`):
 
-- **Re-fetch by default.** Every `start` / `prepare-build` invocation re-fetches from KV. KV is the source of truth; the cache file is a debug/inspection artifact, not a performance optimization.
+- **Re-fetch by default.** Every `start` / `prepare-build` invocation re-fetches from KV and replaces the copy, including any `spec derive` edits in it.
+- **Commit the copy.** The packet, the Build Context and the Assembly Report are bound to it, and `spec derive` writes into it, so it is the campaign's spec until the next intake. A checkout without it fails doctor with `spec.local_path`. [Restore it with `spec fetch`](#restoring-a-saved-map-spec-spec-fetch).
 - **One writer at a time.** The fetch happens first, but the fetched spec is written to the cache file only once the run holds the per-target prepare-build lock. A second run against the same target, fetching a newer Map revision, waits for the lock before replacing the cache, so the run holding it records the hash of the revision it actually parsed.
 - **`--cached-spec`** reuses the cache without a network call. Use for offline iteration or when the proxy is temporarily unreachable. The cached copy is read as it is and never rewritten.
 - **`--proxy-base <url>`** overrides the default origin. Use for staging environments or local Worker dev (`wrangler dev`). Spec retrieval carries no credential, so any reachable origin works here — but the same flag also aims the credential-bearing rails (Run Telemetry remit, QA verdict publish, `telemetry list`), and those require `https:` unless the host is loopback (`localhost`, `127.0.0.1`, `[::1]`), which is allowed over plain http with a stderr warning. A plain-http remote proxy is refused before the request. See docs/workflow-findings-sidecar.md (Remit Channel).
@@ -2114,6 +2120,26 @@ records it (`campaigns-os record setup|build|polish`; deploy and QA record their
 own stages) → calls `next` again → repeat until stage="done"
 ```
 
+### Restoring a saved-Map spec (`spec fetch`)
+
+Before 1.64.0 the fetched copy was ignored by Git, so a fresh clone of those repositories doesn't have it. On that checkout, run:
+
+```bash
+campaigns-os spec fetch --packet campaign-runtime.build.json [--proxy-base <url>] [--json]
+```
+
+It fetches the Map named by the packet, writes the copy to `spec.local_path`, and takes `fetched-specs/` out of an older managed `.gitignore` block. Commit the file so the next checkout has it. A copy already on disk is never replaced and nothing is sent. The packet and the records are not written.
+
+The result's `bound` compares the copy with the spec the records were made against:
+
+| `bound` | Meaning |
+|---|---|
+| `matches` | The records still apply. |
+| `differs` | The Map changed since they were made, or the earlier copy held `spec derive` edits the Map doesn't have. Doctor shows build, Polish and QA owed until `record spec` binds it (warning `spec.fetch.differs_from_records`). |
+| `unknown` | The report records no spec material to compare with. |
+
+The command exits 2 for a packet that names no saved Map, for one whose `spec.local_path` is not the Map's copy, when the Map returns a spec for another campaign (`spec.fetch.identity_mismatch`), and when the fetch fails.
+
 ### Refreshing after a CampaignSpec change
 
 When the CampaignSpec's material content changes, every build, Polish and QA record made against the earlier content stops counting as current, in local-spec, saved-Map and gateway packets alike. For a saved Map or gateway packet, Campaigns OS compares the copy intake fetched; it does not check whether that copy is the latest remote revision, and reports the remote as unconfirmed. Doctor warns `spec.material_stale`, and `next`, progress, readback, the Assembly Report's own status and the QA gate show the stages that are owed again; `next` routes to the first one. Run `campaigns-os record spec --packet <packet>` to bind the new content: it updates the build context and report identity, re-reads the brief file last saved (by intake or `record brief`), keeps waivers, warning accepts, the applied theme and deploy settings, and moves each superseded stage record into that stage's `history`, which is never used as current proof. `spec derive` no longer rebinds identity; run `record spec` after it. A move of page routes binds with `record spec`, and so does a page added or removed after handoff (see [Binding a page change](#binding-a-page-change)); a change to the order of active pages, or a page added or removed before handoff, still needs intake. Re-recording an unchanged build after a spec change keeps the build owed, because the change has not reached the pages, unless the operator records a reason with `--deviation-reason`; this holds even when `record spec` was not run, and that `record build` also marks Polish and QA owed again. Polish stays owed until a new `polish capture`, with one exception: when `record build --deviation-reason` records the very output a completed Polish reviewed (same build fingerprint and source package) and only the CampaignSpec changed, not the brief's presentation, that `record build` restores the Polish record the change moved to history, stamped with the current inputs. It is the same review of the same pages. QA must produce a new verdict against the current content. Polish measurements of byte-identical output keep their values, but the Polish stage is owed again. These checks are tamper evidence, not proof: a hand-written record that copies the current values, or a packet pointed at an older copy of the spec, is not detected.

package/docs/campaigns-os-build-flow.md

@@ -89,6 +89,44 @@ or when it was a page-scoped run that did not complete, in which case the
 pages are counted from the full QA that run extended, so its unpaid pages stay
 owed. A blocked or pending full QA owes a full run.
 
+A change is read against the build each stage last checked, counting every
+rebuild since, not just the latest. So a copy edit that `record build` calls
+`page_only` still owes the full stages when an earlier rebuild since then was
+commerce-affecting. The report names that build and that rebuild, and gives a
+date for a QA that completed.
+
+Page-only changes start after one full QA on 1.62.0 or later, or after a
+baseline. A build recorded before 1.62.0 has no markup hashes to compare with,
+so the first change on it reads as commerce-affecting.
+
+### Accepting a funnel from before 1.62.0
+
+A funnel handed off before 1.62.0 owes the full Polish and QA on its first
+change, whatever the change. To start from where it is instead, a named person
+can accept it:
+
+```bash
+campaigns-os record build --packet <packet>
+campaigns-os record baseline --packet <packet> --accepted-by "<named person>" --reason "<why>"
+```
+
+This tests nothing and places no orders. Polish and QA read `baseline_accepted`,
+which is never `completed`. What they held moves to history, so its purchase
+proof stops counting. After that:
+
+- A page-only change owes QA on that page only. A passing `qa run --page` leaves
+  QA at `baseline_accepted`, because it proved those pages and not the funnel.
+- A commerce-affecting change owes the full Polish and QA.
+- A CampaignSpec or brief change owes the stages again.
+- Doctor warns `qa.baseline_accepted`, and `doctor --ci`, readback and `next` all
+  say QA rests on a baseline and no purchase has been tested since.
+- A completed full `qa run` ends it. A blocked one leaves the baseline in place.
+
+A funnel gets one baseline. The command refuses a funnel whose last QA was
+blocked, one where no QA ever completed, one whose records have markup hashes,
+and one where no full QA is owed. For the first two, run a full `qa run`. Once it
+passes, page-only changes work without a baseline.
+
 The PR comment opens with the kind it found and what that owes, for example
 "Change found: page-only. It owes QA on `upsell1`; Polish is advisory." A
 commerce-affecting change names its reasons.

package/docs/campaignspec-authoring-examples.md

@@ -138,8 +138,9 @@ A page package row can also carry its price in each currency, as `prices[]`:
   fills `prices[]` when it refreshes from the API; set prices in the
   Campaigns App, not in the spec. `campaigns-os spec derive` refreshes `price`
   and `price_retail` from one default-currency read and leaves `prices[]` as
-  it was, so after changing a non-default price, refresh the Map in Map
-  Builder.
+  it was, so after changing any price, refresh the Map in Map Builder: a
+  default-currency change otherwise leaves `price` and the default currency's
+  `prices[]` entry disagreeing.
 - `prices[]` is optional. A row without it says nothing about other
   currencies and is not checked. A row with it should list every currency in
   `available_currencies` and `campaign.currency`; the `PackageCurrencyPrices`

package/docs/effects.md

@@ -98,6 +98,14 @@ are on every row for those three commands. The effect test runs each row with
 the one condition whose `--proxy-base` is the loopback receiver, so the fetch
 and the write are observed rather than taken on trust.
 
+`spec fetch` sends the same request and writes the same file, only when the
+packet's copy is missing, and it never replaces one. It also writes the target's
+`.gitignore` when the managed block is missing or still lists `fetched-specs/`.
+
+`record baseline` writes only the Assembly Report and sends nothing. It is tier C
+because it replaces the live Polish and QA records, so any purchase proof they
+held stops counting. History keeps them.
+
 ### The live campaign read
 
 `doctor --packet` (with or without `--write` / `--no-write`) and every `qa run`

package/docs/local-setup.md

@@ -3,7 +3,7 @@
 For a new campaign, create an empty working folder and run this from it:
 
 ```sh
-npm init -y && npm install --save-exact next-campaign-page-kit@0.3.0 && npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.63.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
+npm init -y && npm install --save-exact next-campaign-page-kit@0.3.0 && npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.66.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
 ```
 
 `npm init -y` gives the folder its own `package.json`. Without one, npm

package/docs/orientation-contract-reference.md

@@ -26,7 +26,7 @@ Ledger schema id: `campaigns-os-release-ledger/v1`
 Change policy version: `1.0.0`  
 Reason-code vocabulary version: `1.0.0`  
 Limits version: `1.0.0`  
-Supported surface at generation time: `1.63.0`
+Supported surface at generation time: `1.66.0`
 
 ## Forward compatibility
 

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

@@ -421,10 +421,11 @@ can load with `?currency=GBP` and still take a USD order:
   price and recurring-price claims are not compared with the run-currency
   totals: they count as unresolved, and the commercial report records
   `unresolved_money_claims_reason: "static_source_not_in_run_currency"`. A
-  correctly built multi-currency page gets no `price-claim-mismatch` warning,
-  and the commercial status reads `incomplete` instead of `pass`. With
-  `--currency` set to the Map's own currency, the claims are compared as
-  before.
+  correctly built multi-currency page gets no `price-claim-mismatch` warning.
+  The commercial status reads `incomplete` instead of `pass`, and a
+  `commercial-parity:incomplete:static_source_not_in_run_currency` warn row says
+  what was not compared. With `--currency` set to the Map's own currency, the
+  claims are compared as before.
 
 Either blocker makes the verdict `blocked` and the command exit `4`. Without
 `--currency` neither row is written and expected totals use
@@ -480,16 +481,49 @@ claims per document, 256 claims across the run, 1 MiB per price-preview
 response, 256 calculate scenarios, four concurrent proxy requests, and 20
 seconds per request. A limit, missing key, malformed response,
 or unavailable page records incomplete commercial evidence; it never invents
-a mismatch. `commercial.status = "incomplete"` preserves the disposition
-derived from the ordinary QA assertions; it does not create an exception by
-itself. QA dispositions remain `ready`, `ready_with_exceptions`, or `blocked` —
-`ready_with_waivers` is the doctor/`next` checkpoint-readiness term.
+a mismatch. QA dispositions remain `ready`, `ready_with_exceptions`, or
+`blocked` — `ready_with_waivers` is the doctor/`next` checkpoint-readiness term.
+
+`commercial.status = "incomplete"` makes the verdict at least
+`ready_with_exceptions`. It stays warn-only: it never makes a run `blocked` and
+never changes the exit code. Each cause writes one warn row in family `pricing`,
+`commercial-parity:incomplete:<code>`, for example
+`commercial-parity:incomplete:missing_campaigns_api_key`. The row's `actual` says
+what was not compared and how to fix it, so an agent reading only `exceptions[]`
+sees the gap. The committed sidecar keeps the id, which names the cause. The report
+repeats the causes as `commercial.incomplete_reasons`, and `qa run` prints them under
+its commercial line. A cause an earlier one explains writes no second row, so a
+missing key does not also report every page as unpriced.
+
+Read the row for what to do, not the code: the set of codes is not a contract and
+can change. Not every cause has a repair. A store coupon, two bound prices on one
+page, a run in another currency and a funnel over the check's limits only say what
+this run did not compare. A `commercial-currency:<RUN>:<ANSWERED>` blocker and a
+`commercial_parity.recurring_claim_absent` warning are their own rows and add no
+`commercial-parity:incomplete:` row.
+
+Bound prices are read two ways, because the two bindings mean different things in
+the source. `bundle.<id>.price` is compared as authored in the source HTML, against
+the page's calculated total. `package.price` and `package.<ref>.price` are compared
+as rendered, because what the source holds there is the template's placeholder (a
+starter upsell ships `$9.99`). Under `qa run --browser`, QA reads each visible node
+once the SDK has written it, which it knows by the `display-visible` class the SDK
+adds, and compares it with calculate's `unit_price` for that package's row on the
+page: one unit, after offers. So a page printing `package.price`, which is the list
+price, beside a live offer gets a `price-claim-mismatch` warning. The package is the
+id in the path, or else the nearest `data-next-package-id`, `data-next-package` or
+`data-package-id`, which is how the SDK scopes it. The source is only read to learn
+that these claims exist, so a run without `--browser` reports them as
+`package_price_not_rendered`. `verdict.commercial.package_price_claims` counts them.
+Under a `--currency` that is not the Map's they stay unresolved, like the source
+prices above, because the browser pass does not load pages in the run currency.
 
 Only contract-governed claims are compared, and only against `Exact` normalized
 truth. Proven differences emit warn-severity `pricing` assertions named
 `price-claim-mismatch`, `cadence-disclosure-mismatch`, or
-`voucher-not-applied`. Decorative, ambiguous, stale, unresolved, or malformed
-claims remain silent. A page showing a voucher the normalized plan cannot price
+`voucher-not-applied`. Decorative claims are ignored, and ambiguous, stale,
+unresolved, or malformed claims never read as a mismatch: they leave the proof
+incomplete, as above. A page showing a voucher the normalized plan cannot price
 (no calculated pair for its code, for example a live voucher on an upsell)
 leaves that page's price claims unresolved: the plan's only Exact truth for
 the page is then the list price, which a voucher-priced page is expected to

package/docs/readback.md

@@ -525,13 +525,20 @@ the build a stage reviewed are on that stage instead. An owed stage carries:
   `stages.assembly.build_changes` plus the drift on disk. `kind` is `unknown`
   when that history does not reach the reviewed build (reason
   `change_history_unavailable`) or the drift cannot be read. `null` on a stage
-  that is not owed.
+  that is not owed. It also carries `commerce_rebuild` when a recorded rebuild
+  since that build was not page-only: `{ "recorded_at", "build_fingerprint",
+  "kind", "latest_change_kind" }`.
 - Polish only, `advisory`: `true` when the change is `page_only` and no brief or
   spec change requires Polish. Advisory Polish is reported; `next`, `doctor
   --ci` and the QA gate do not require it.
 - QA only, `scope` and `owed_pages`: `pages` with the changed pages when the
   change is `page_only` (`qa run --page` pays it), `full` otherwise, `null`
   when QA is not owed.
+- QA only, `reviewed_at`: when the completed QA the change is read from was
+  checked. Absent when QA did not complete.
+- QA only, `baseline`: `{ "accepted_by", "accepted_at", "reason",
+  "build_fingerprint" }` while QA rests on a baseline (`record baseline`), which
+  is not a test. Present on a QA that is current as well as one that is owed.
 
 If recording removed a
 stage binding entirely, that stage reads unknown unless its recorded status is

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.63.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.66.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.63.0+skills.1"
+"bundle_revision": "1.66.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.63.0+skills.1` is therefore ahead of `1.40.0+skills.7`.
+  with the prefix**. `1.66.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.63.0+skills.1
+Bundle revision: 1.66.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.63.0+skills.1
+npx --no-install campaigns-os tooling status --skills-revision 1.66.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.63.0+skills.1",
+  "requested": "1.66.0+skills.1",
   "spelling": "bundle",
-  "on_disk": "1.63.0+skills.1",
+  "on_disk": "1.66.0+skills.1",
   "on_disk_skill": null,
-  "message": "match (1.63.0+skills.1)"
+  "message": "match (1.66.0+skills.1)"
 }
 ```
 
 The text view prints one named line, as a header above the rest of the status:
 
 ```
-Skills revision: match (1.63.0+skills.1)
-Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.63.0+skills.1 — start a fresh session
-Skills revision: unchecked (on disk 1.63.0+skills.1)
+Skills revision: match (1.66.0+skills.1)
+Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.66.0+skills.1 — start a fresh session
+Skills revision: unchecked (on disk 1.66.0+skills.1)
 ```
 
 `unchecked` is the state when the flag is absent. It is not an error — an

package/docs/supported-surface.md

@@ -14,7 +14,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. 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. |
+| 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; 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. `record baseline` (added in 1.66.0) accepts a handed-off funnel from before markup hashes as the starting point for page-only changes, one time per funnel, without testing it. `spec fetch` (added in 1.64.0) puts a saved-Map packet's CampaignSpec back on a checkout that lacks it, never replacing a copy on disk. `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. |
 | `bin/campaigns-os.mjs` (`campaigns-os`) | The CLI entry itself. | Declared in `package.json` `bin`; the gate fails if it disappears. |

package/package.json

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

package/schemas/campaigns-os-qa-verdict.v0.schema.json

@@ -94,7 +94,7 @@
     "disposition": {
       "type": "string",
       "enum": ["ready", "ready_with_exceptions", "blocked"],
-      "description": "Derived from the assertions (and the commercial section's status): any unwaived failing blocker => blocked; any warn/manual_review/waived assertion or a proven commercial mismatch => ready_with_exceptions; otherwise ready. Waived is never clean. ready_with_waivers is the doctor/next checkpoint term, never a verdict disposition."
+      "description": "Derived from the assertions (and the commercial section's status): any unwaived failing blocker => blocked; any warn/manual_review/waived assertion, a proven commercial mismatch or incomplete commercial coverage => ready_with_exceptions; otherwise ready. Waived is never clean. ready_with_waivers is the doctor/next checkpoint term, never a verdict disposition."
     },
     "assertions": {
       "type": "array",
@@ -417,7 +417,7 @@
         "status": {
           "type": "string",
           "enum": ["pass", "mismatch", "incomplete", "not_applicable", "not_run"],
-          "description": "mismatch keeps the verdict at ready_with_exceptions; incomplete preserves the disposition derived from ordinary assertions and never invents an exception."
+          "description": "mismatch and incomplete each keep the verdict at ready_with_exceptions at least, and neither blocks it. incomplete also writes a warn commercial-parity:incomplete:<code> assertion for each named cause, and never invents a mismatch."
         },
         "coverage_complete": { "type": "boolean" },
         "findings": {
@@ -436,6 +436,21 @@
             }
           },
           "description": "Sanitized capture/proxy/limit issue codes with counts. An issue records incomplete evidence; it never invents a mismatch."
+        },
+        "incomplete_reasons": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["code", "summary", "fix"],
+            "properties": {
+              "code": { "type": "string", "minLength": 1 },
+              "count": { "type": "integer" },
+              "summary": { "type": "string", "description": "What this run did not compare, and why." },
+              "fix": { "type": "string", "description": "What to do about it. Some causes have nothing to repair and say so." }
+            }
+          },
+          "description": "Present when status is incomplete: one entry per named cause, the same causes the commercial-parity:incomplete:<code> assertions carry. Empty when every cause already has a row of its own. Absent on verdicts emitted before the field existed."
         }
       },
       "description": "The compact commercial-parity report: counters over checked pages, scenarios, and claims, plus findings and issues. Counter fields are additive and not individually contracted here."

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

@@ -1,11 +1,11 @@
 ---
 name: campaign-lifecycle-orientation
-version: 1.0.49
+version: 1.0.52
 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.63.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.63.0+skills.1`
+Bundle revision: 1.66.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.66.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.49
+version: 1.0.52
 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.63.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.63.0+skills.1`
+Bundle revision: 1.66.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.66.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.49
+version: 1.0.52
 description: Interpret existing Campaigns OS doctor, QA and proof-depth evidence without claiming more proof than the artifacts contain.
 ---
 
-Bundle revision: 1.63.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.63.0+skills.1`
+Bundle revision: 1.66.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.66.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.49
+version: 1.0.52
 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.63.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.63.0+skills.1`
+Bundle revision: 1.66.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.66.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.54
+version: 1.0.57
 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.63.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.63.0+skills.1`
+Bundle revision: 1.66.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.66.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read

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

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-os
-version: 1.0.69
+version: 1.0.72
 description: Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth.
 ---
 
-Bundle revision: 1.63.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.63.0+skills.1`
+Bundle revision: 1.66.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.66.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.52
+version: 2.0.55
 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.63.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.63.0+skills.1`
+Bundle revision: 1.66.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.66.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.54
+version: 1.1.57
 description: Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign.
 ---
 
-Bundle revision: 1.63.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.63.0+skills.1`
+Bundle revision: 1.66.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.66.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.53
+version: 1.3.56
 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.63.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.63.0+skills.1`
+Bundle revision: 1.66.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.66.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
@@ -75,7 +75,7 @@ Inputs:
 Rules:
 
 - Use the public Node/npm `campaigns-os qa` commands for campaign QA runs.
-- Canonical `qa run` automatically runs commercial parity for enabled pages with package rows when their source evidence is available. It reuses each page's read-only source fetch and the existing read-only `POST /api/price-preview`; neither creates carts, orders, or transactions. The lane is warn-first: proven price, recurring-cadence, and voucher mismatches become warn-severity `pricing` assertions, with compact coverage and findings at top-level `verdict.commercial`. Omitted or otherwise unprovable claims emit no mismatch assertion and do not change an otherwise-ready disposition; incomplete coverage remains visible in `verdict.commercial`.
+- Canonical `qa run` automatically runs commercial parity for enabled pages with package rows when their source evidence is available. It reuses each page's read-only source fetch and the existing read-only `POST /api/price-preview`; neither creates carts, orders, or transactions. The lane is warn-first: proven price, recurring-cadence, and voucher mismatches become warn-severity `pricing` assertions, with compact coverage and findings at top-level `verdict.commercial`. Unprovable claims never read as a mismatch. Incomplete coverage (for example a spec with no `campaign.campaigns_api_key`, so no scenario ran) keeps the run at `ready_with_exceptions` at least, never `blocked`, with a warn row `commercial-parity:incomplete:<code>` in `exceptions[]` that names the cause and the fix. Report it to the operator, and do not call a run whose commercial status is `incomplete` fully proven.
 - Use `qa parity` for migration cells that carry a parity fixture; select the fixture scenario and drive that offer through the candidate funnel.
 - 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.

package/skills/next-campaigns-sdk-bump/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-sdk-bump
-version: 1.0.9
+version: 1.0.12
 description: Bump a live campaign's Campaign Cart SDK from one 0.4.x release to a later 0.4.x on a page-kit or static repo. Use for any request to bump, upgrade or move a campaign to SDK 0.4.x, including when the repository has its own BUMP.md. Find every pin, check the release diff and storage against the campaign's own code, prove on a preview with approved test orders, and report what is not proven.
 ---
 
-Bundle revision: 1.63.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.63.0+skills.1`
+Bundle revision: 1.66.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.66.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