@nextcommerce/campaigns-os 1.52.0 → 1.54.0

package/docs/sdk-storage-compatibility.md

@@ -17,3 +17,18 @@ Acorn parses JavaScript ASTs; parse5 identifies executable inline HTML scripts a
 Dynamic storage keys, unresolved storage methods, shadowed storage names, missing migration release evidence, unsupported target versions, and JavaScript parse failures report unknown. This bounded analysis does not execute merchant code or prove computed keys correct. It does not follow arbitrary data flow, dynamic imports, event-handler attributes, generated code or runtime-loaded script graphs. Inspect unresolved findings and include all campaign sources in scope; a clean result is only static tracked source compatibility evidence. Browser behavior, order creation, tracking and analytics still require their own proof, especially where multiple campaigns share an origin. Use the SDK public store API where the manifest recommends it; do not invent a prefix-first merchant repair.
 
 Storage `length` property reads are unaffected metadata (`storage-metadata-read`). Storage `key()` enumeration, extracted method references, and mutations of reserved members remain unknown; enumeration cannot prove an SDK key lookup safe. Git discovery failures return one bounded CLI error. Local script diagnostics retain repository-relative spellings from HTML source, including `../` paths; excluded/outside sources are not read. The Git root and operator target are compared by filesystem device/inode identity, so supported case aliases and symlinks can name the same root. Source containment uses realpaths below the Git root without case folding. Extra positional CLI arguments are rejected so an accidental scope or version value cannot silently disappear.
+
+## Rewriting hardcoded pins in a static repo
+
+A static campaign repo (no `_data/campaigns.json`) pins the SDK in its HTML: `loader.js@v0.4.x` in script tags and `campaign-cart.css@v0.4.x` in link tags. Once the storage check is clean, `sdk repin` updates those pins:
+
+```sh
+npx --no-install campaigns-os sdk repin --target . --target-sdk 0.4.38            # preview: path:line, old URL -> new URL; writes nothing
+npx --no-install campaigns-os sdk repin --target . --target-sdk 0.4.38 --apply    # writes the files and the change record
+```
+
+It reads the same references `standardize` reports under `sdk_loader.references`: every Campaign Cart URL that points at a loader or dist artifact, in HTML and script files, with HTML comments, `_site/`, `node_modules/`, `dist/`, `build/` and `.campaign-runtime/` left out. Only a semver pin (`@vX.Y.Z` or `@X.Y.Z`) below the target is rewritten, and only the version segment of the URL changes; a leading `v` stays as written. These are reported and left alone: `@latest`, `@main`, commit refs, prerelease refs, and pins already at or above the target (repin never moves a pin down). Without `--target-sdk` the target is the SDK support policy's `preferred_minimum`, the version `standardize` evaluates pins against.
+
+The default is a preview that writes nothing. `--apply` writes the files, then writes a change record to `.campaign-runtime/sdk-repin.json` (`campaigns-os-sdk-repin/v0`). The record holds the files touched, the reference count, the from and to versions, each rewrite with its path, line and artifact (`loader` or `css`), and the refs left alone. It uses repo-relative paths only, so you can commit it, and a Run Record can cite it by path and sha256 (`--json` prints the sha256). After writing, repin scans again and reports whether any pin below the target remains. Running it a second time with the same target finds nothing to change and writes nothing. `--json` prints the full result: `status` is `changes`, `nothing_to_change`, `no_references` or `refused_page_kit`.
+
+A repo with `_data/campaigns.json`, at its root or in any folder the scan walks, is refused with exit 2 and nothing written: page-kit owns that pin, so use `campaigns-os page-kit sync --packet <campaign-runtime.build.json>` there. An invalid `--target-sdk` is refused with exit 1. Repin does not prove that the new SDK works. After rewriting, run the campaign's browser QA against the new pin.

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

package/docs/supported-surface.md

@@ -16,6 +16,7 @@ implementation detail, however stable it looks.
 | `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). |
 | 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. |
 | `bin/campaigns-os.mjs` (`campaigns-os`) | The CLI entry itself. | Declared in `package.json` `bin`; the gate fails if it disappears. |
 | Package export `./campaign-spec` | The versioned campaign-spec rule registry, consumed as `@nextcommerce/campaigns-os` (pinned by consumers' lockfiles; lockstep policy — ADR-003 in the ops repo). | Behavior-guarded from the consumer side by their contract tests; the export path itself is gated here. |
 | Package exports `./commercial-journey` and `./commercial-parity` | Portable scenario planning, response normalization, contract-governed source extraction, Exact-only parity comparison, and deterministic QA assertion serialization. These modules own no network transport and do not calculate prices locally. | Consumers execute descriptors through a supported calculate transport, then pass captured envelopes into the pure normalizer. Existing export paths are gated and may not be renamed or removed without a breaking surface change. |

package/package.json

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

package/schemas/campaign-runtime-assembly-report.v0.schema.json

@@ -329,7 +329,11 @@
           "items": { "type": "string", "minLength": 1 }
         },
         "performed_by": { "type": "string", "minLength": 1 },
-        "source_build_fingerprint": { "type": "string", "minLength": 1 },
+        "source_build_fingerprint": {
+          "description": "The build output fingerprint (stages.assembly.build_fingerprint) this stage was recorded against. stages.polish and stages.deploy carry it; record build makes a completed stage that names other output required again (a demoted stages.deploy keeps its prior record, with that record's outputs and evidence, in its history). A stages.deploy without it was recorded before deploy stamped its build and is kept as recorded.",
+          "type": "string",
+          "minLength": 1
+        },
         "source_package_material_fingerprint": { "type": "string", "minLength": 1 },
         "build_fingerprint": { "type": "string", "minLength": 1 },
         "artifact_fingerprint": { "type": "string", "minLength": 1 },

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

@@ -1,11 +1,11 @@
 ---
 name: campaign-lifecycle-orientation
-version: 1.0.27
+version: 1.0.30
 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.52.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.52.0+skills.1`
+Bundle revision: 1.54.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.54.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.27
+version: 1.0.30
 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.52.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.52.0+skills.1`
+Bundle revision: 1.54.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.54.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.27
+version: 1.0.30
 description: Interpret existing Campaigns OS doctor, QA and proof-depth evidence without claiming more proof than the artifacts contain.
 ---
 
-Bundle revision: 1.52.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.52.0+skills.1`
+Bundle revision: 1.54.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.54.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.27
+version: 1.0.30
 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.52.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.52.0+skills.1`
+Bundle revision: 1.54.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.54.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.32
+version: 1.0.35
 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.52.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.52.0+skills.1`
+Bundle revision: 1.54.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.54.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,6 +75,7 @@ Inputs:
 - prepared HTML/assets source
 - target page-kit repo
 - starter-template commerce catalog
+- Read the normalized Campaign Build Brief at `.campaign-runtime/input/campaign-build-brief.normalized.json` and the recorded decisions (`adapter_decisions`, `decisions` and `theme` in `.campaign-runtime/assembly-report.json`, and `assembly.template_decision_notes` in the Build Packet) before working on the campaign. The campaign intent summary at the top of the setup, build, Polish and QA prompts and in every `next` result is orientation, never a source of prices or commerce behaviour.
 
 Build rules:
 
@@ -106,6 +107,7 @@ Build rules:
 - For `shop-three-step`, shipping methods are dynamic through `window.next.getShippingMethods()`; do not add static Olympus-style `shipping_methods` frontmatter.
 - Run page-kit build and SDK/template lint available in the target repo.
 - Record build with `campaigns-os record build --packet <packet>` after every page-kit build (tier `C`: it overwrites `stages.assembly` and, when the output changed, resets `stages.polish` to `required` in the assembly report, and stamps the doctor output stale; `--dry-run` is tier `none`). It stamps `stages.assembly.build_fingerprint` with the fingerprint doctor computes from `_site/<slug>/` and the Design Source Package material fingerprint when the report has one. Never type or copy these fields by hand.
+- If `next` reports that the build output is unchanged after a brief or CampaignSpec change, rebuild so the change reaches the pages. Pass `--deviation-reason` to `record build` only when the operator explicitly decides in this conversation that the change needs no change to the built pages, and quote their reason.
 - Capture the machine-readable build summary as an artifact: `npx campaign-build --json > .campaign-runtime/page-kit-build-summary.json` (requires `next-campaign-page-kit` >= 0.1.4). Doctor's `built_output.build_summary` check verifies per-page build status and Page Kit shape warnings (`NESTED_NO_PERMALINK`, `DUPLICATE_OUTPUT`, `MISSING_FRONTMATTER`, `LAYOUT_NOT_FOUND`, `NO_CAMPAIGN`) from this artifact. If the installed page-kit predates `--json`, record that in the assembly report instead of skipping silently.
 - Update the assembly report with commands, evidence, warnings, blockers, and next owner. If a brand theme was applied, run `campaigns-os record theme --packet <p>` (tier `C`) after `record build`: it reads each built commerce page's stylesheet links and records `report.theme` (status applied, `load_order=after-next-core`, `css_path`, `commerce_pages`, evidence). It refuses, writing nothing, when a page that loads `next-core.css` does not load the brand layer after it. Don't hand-edit `report.theme`; a first repair-loop defect goes through `record polish`.
 

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

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-os
-version: 1.0.47
+version: 1.0.50
 description: Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth.
 ---
 
-Bundle revision: 1.52.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.52.0+skills.1`
+Bundle revision: 1.54.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.54.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
@@ -103,31 +103,22 @@ Map and run endpoints) with a local CampaignSpec, prepared HTML/assets source, t
 When a Campaigns OS session starts, classify the starting path before handing
 off to setup, build, polish, QA, or promotion. The operator should separate:
 
-- Intent: build, partial page update, existing campaign update, QA only, repair from verdict, design/source assembly, or promotion.
+- Work: build, partial page update, existing campaign update, QA only, repair from verdict, design/source assembly, or promotion.
 - Source truth: CampaignSpec/Map Builder export, Figma/design file, prepared HTML, existing campaign repo, deployed URL, or target deployment system.
 - Runtime truth: Build Packet, Build Context, Assembly Report, doctor JSON, tested URL, API key source, and SDK origin allowlist state (localhost is already a Development domain; non-localhost origins still need confirmation).
 - Change policy: what may change and what must be preserved, especially checkout, offer logic, routes, legal copy, and live campaign behavior.
-- Proof depth: visual preview, doctor, browser QA, QA portal/local verdict policy, typed-card test-order depth, market coverage, and repair routing.
+- Proof policy: visual preview, doctor, browser QA, QA portal/local verdict policy, typed-card test-order depth, market coverage, and repair routing.
 
-Return a compact brief before acting:
-
-```text
-Mode:
-Intent:
-Source truth:
-Runtime truth:
-Change policy:
-Proof depth:
-Next skill/command:
-Missing inputs:
-```
+Return the compact brief defined in `references/session-intake.md` before acting.
 
 Use `references/session-intake.md` when the mode, allowed changes, or proof
-depth is unclear. Ask only for fields needed by the selected starting path; a
+policy is unclear. Ask only for fields needed by the selected starting path; a
 QA-only session should not require design files, and a partial landing update
 should not force full checkout/test-order depth unless commerce or routing can be
 affected.
 
+Save the operator's brief answers with `campaigns-os record brief --packet <packet>` (tier `C`: when the brief changes it rewrites the Build Packet's brief binding, the normalized brief, the Build Context and the assembly report and stamps the doctor output stale, and a material change makes build, Polish and QA owed again; `--dry-run` is tier `none`). Ask the operator before saving brief answers. Put the answers in the brief file as `docs/campaign-build-brief.md` describes, then run `record brief`; do not re-run `start` or `prepare-build` to save them.
+
 Rules:
 
 - This is contract-backed guidance and preflight, not full automated readiness.
@@ -140,7 +131,7 @@ Rules:
 - Promoted starter-template families must also have `contracts/template-brand-contract.<family>.v0.json` with family inventory, brand/residue, pricing, and exit-pop rules. Missing family contracts are gates, not advisory gaps.
 - Designed source owns visual composition and page-level content.
 - Brand-theme evidence is workflow-order neutral. Do not assume a Figma export came first; consume `context.theme` and `.campaign-runtime/theme/theme-report.json` when present. A truly missing/ungeneratable theme stays a warning, but a generatable-and-unapplied theme on a commerce-page campaign is a gate: apply it or waive it explicitly before polish/deploy/QA.
-- Follow `campaigns-os next` literally. Every `next` response carries its applicable Store Profile, SDK, hidden eager-media, theme, and broad Polish gates plus `next_actions` with exact commands — execute those instead of improvising. With an active run session, pipeline-advancing commands that don't match the last `next` recommendation are recorded to `.campaign-runtime/agent-deviations.jsonl`; declare an intentional detour with `--deviation-reason "<why>"`.
+- Follow `campaigns-os next` literally. Every `next` response carries its applicable Store Profile, SDK, hidden eager-media, theme, and broad Polish gates plus `next_actions` with exact commands — execute those instead of improvising. With an active run session, pipeline-advancing commands that don't match the last `next` recommendation are recorded to `.campaign-runtime/agent-deviations.jsonl`; declare a detour with `--deviation-reason "<the operator's reason>"` only when the operator has decided on that detour in this conversation, and quote their reason; never pass the flag on your own judgement. On `record build` after a brief or CampaignSpec change the flag records that the change needs no change to the built pages, so pass it there only on the operator's explicit decision, as `next-campaigns-build` says.
 - Close the loop: when `next` reports `done` (or QA has published its verdict and the PR is up), finish with `campaigns-os run end` (tier `C`; `--no-write` still clears the session file) so the Run Record is assembled and the run session clears. `campaigns-os run status` (tier `none`: read-only) shows incomplete stages and the exact next command at any point.
 - Do not copy demo refs or unsupported optional surfaces into the target campaign.
 - Use SDK conditionals such as `cart.hasCoupon("CODE")` for code-specific presentation; do not mutate visible prices from campaign-specific JavaScript.

package/skills/next-campaigns-os/references/session-intake.md

@@ -2,7 +2,7 @@
 
 Use this reference when a Campaigns OS session begins without an already-clear
 Build Packet, QA verdict, or promotion task. The goal is to make the operator
-separate intent, source truth, runtime truth, change policy, and proof policy.
+separate the work, source truth, runtime truth, change policy, and proof policy.
 
 ## Intake Envelope
 
@@ -10,27 +10,31 @@ Return this compact brief before running a specialist skill or command:
 
 ```text
 Mode:
-Intent:
+Work:                 (build, update, QA, repair, promote — the session's task; formerly "Intent")
+Campaign:             (paste the "Campaign intent" lines from the latest `next` output; do not write your own)
 Source truth:
 Runtime truth:
 Change policy:
 Proof policy:
 Next skill/command:
-Missing inputs:
+Missing inputs:       (only choices that affect this revision)
 ```
 
 Definitions:
 
-- Intent: what the user wants done, such as build, update, QA, repair, or promote.
+- Work: what the user wants done, such as build, update, QA, repair, or promote.
+- Campaign: the "Campaign intent" lines from the latest `next` output, pasted as printed. They come from the normalized Campaign Build Brief; do not write your own.
 - Source truth: CampaignSpec/Map Builder export, Figma/design file, prepared HTML, existing campaign, target repo, or deployed URL.
 - Runtime truth: Build Packet, Build Context, Assembly Report, optional `context.theme` / `.campaign-runtime/theme/theme-report.json`, doctor JSON, repo state, tested URL, Campaigns API key source, SDK origin state (localhost is a Development domain; non-localhost origins need allowlist confirmation), and test-order depth choice.
 - Change policy: what may change and what must be preserved, especially checkout, offer logic, live campaign routes, and legal/merchant copy.
-- Proof depth: visual preview, doctor, browser QA, QA portal/local verdict policy, typed-card test-order depth, market coverage, and repair routing.
+- Proof policy: visual preview, doctor, browser QA, QA portal/local verdict policy, typed-card test-order depth, market coverage, and repair routing.
 
 Ask only for the fields needed by the selected mode. Do not force a full-funnel
 build prompt when the user only needs QA, a partial page update, or repair from
 an existing verdict.
 
+Save the operator's brief answers with `npx --no-install campaigns-os record brief --packet <packet>` (tier `C`: when the brief changes it rewrites the Build Packet's brief binding, the normalized brief, the Build Context and the assembly report and stamps the doctor output stale, and a material change makes build, Polish and QA owed again; `--dry-run` is tier `none`). Ask the operator before saving brief answers. Put the answers in the brief file as `docs/campaign-build-brief.md` describes, then run `record brief`; do not re-run `start` or `prepare-build` to save them.
+
 ## Starting Paths
 
 ### Full Campaign Build
@@ -45,7 +49,7 @@ Required before build:
 - Source type and source files: Figma, exported HTML, prepared HTML, existing campaign, or other.
 - Pages in scope and any pages to preserve.
 - Template family if known; otherwise infer and ask before locking commerce surfaces.
-- Proof depth, including browser QA and the typed-card test-order depth to run.
+- Proof policy, including browser QA and the typed-card test-order depth to run.
 
 Route to Build Packet preparation, doctor, setup when scaffold is missing,
 build, polish, then QA.

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

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-os-setup
-version: 2.0.30
+version: 2.0.33
 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.52.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.52.0+skills.1`
+Bundle revision: 1.54.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.54.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
@@ -52,6 +52,7 @@ Responsibilities:
 - When copying a selected starter template family, copy the family as an atomic page-kit slice: pages plus required `_includes/`, `_layouts/`, `assets/css/`, and `assets/js/`. Do not copy only `checkout.html` and `receipt.html`.
 - Public families resolve from the default `public` starter-templates source. A **private** family (one whose source lives in an access-controlled repo, e.g. a certified family not present in the public picker) is scaffolded via page-kit's template-source mechanism (`next-campaign-page-kit` >= 0.2.0): add a named source to the target repo's `_data/template-sources.json` (a `git` source with the SSH `url` + optional `ref`, or a `local` source `path`), then `campaign-init --source <name> --template <slug>`. The source repo must expose a root `templates.json` catalog + `src/<slug>/` tree. page-kit holds no family→repo mapping; the source config lives in the (private) consuming repo, and this skill (plus the family's certified contract) is where that source is known.
 - Install or reference `.campaign-runtime/agent-context` without overwriting existing root agent files.
+- Read the normalized Campaign Build Brief at `.campaign-runtime/input/campaign-build-brief.normalized.json` and the recorded decisions (`adapter_decisions`, `decisions` and `theme` in `.campaign-runtime/assembly-report.json`, and `assembly.template_decision_notes` in the Build Packet) before working on the campaign. The campaign intent summary at the top of the setup, build, Polish and QA prompts and in every `next` result is orientation, never a source of prices or commerce behaviour.
 - Record setup with `campaigns-os record setup --packet <packet>` once the campaign output directory exists (tier `C`: it overwrites `stages.setup` in `.campaign-runtime/assembly-report.json` and the `scaffold` block of `.campaign-runtime/build-context.json`, and stamps the doctor output stale; `--dry-run` is tier `none`). It sets `scaffold.required` to false and `stages.setup` to completed, validates both files against their schemas, and writes nothing when a check fails. Do not hand-edit either file.
 - Preserve existing Build Context `theme` inspection data and Assembly Report `theme` application data when setup is rerun against an existing campaign directory.
 - Hand off to `next-campaigns-build`.

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

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-polish
-version: 1.1.31
+version: 1.1.34
 description: Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign.
 ---
 
-Bundle revision: 1.52.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.52.0+skills.1`
+Bundle revision: 1.54.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.54.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
@@ -59,6 +59,7 @@ Responsibilities:
 - Scan **visible** rendered text inside the family's content/commerce surfaces (the selectors enumerated in `contracts/template-brand-contract.<family>.v0.json`) for placeholder/residue copy the build should have replaced — the *literal starter defaults*: lorem-ipsum, the unmodified starter headings (`Product Name` / `Package Title` / `Your headline`), `[VERIFY …]` author notes, `TODO` markers. Match the literal starter strings, not any authored copy that merely contains those words, and skip `<script>` / `<style>` / JSON-LD / `data-*` attributes. Treat a surviving literal starter default on a content/commerce surface as a polish blocker — replace it from the prepared source / CampaignSpec; do not draft substitute copy (if the design's authored copy is genuinely missing, flag it rather than invent it). This is *copy* residue, complementary to the computed-style / asset residue gated by `next-campaigns-qa` + the brand contract — not a duplicate of it.
 - Flag template *defaults* left where they disagree with the prepared design — e.g. the same benefit icon repeated across a grid *when the design uses distinct icons*, or a guarantee badge/term that disagrees with the design — as polish defects, not just logos. Judge against the prepared source, not taste: copy or imagery the source/CampaignSpec does not supply (e.g. a placeholder testimonial name/quote/role) is residue; "looks generic" on its own is not. Copy the source does supply, including its proof and urgency elements (reviews, "Verified Purchase" labels, recent-purchase popups, stock counters, countdowns, guarantees), is the merchant's content: keep it as designed and do not record it as an issue or an unconfirmed claim.
 - **Brand-bleed (cloned-source de-brand) pass.** When a campaign is cloned from a proven sibling, the sibling's brand defaults ride along. Inspect the built pages and assets for residual cross-brand bleed and clear it before recording: (1) a residual promo/sale banner or coupon code/copy from the source campaign (including a baked-in *fake* code); (2) a prior-campaign / sibling favicon left in place; (3) scaffold or non-design fonts the design did not specify (e.g. starter `Plus Jakarta`); (4) hardcoded non-token colors — any brand color literal that should be a token, such as next-core's `#C670FE` "Most Popular" pill. Clear each from the prepared source / CampaignSpec and brand theme (tokens, not literals); flag — do not invent — anything the design genuinely doesn't supply. Treat surviving bleed as a polish blocker. This complements the favicon/logo and copy-residue checks above; it is the cross-brand contamination angle, not a duplicate.
+- Read the normalized Campaign Build Brief at `.campaign-runtime/input/campaign-build-brief.normalized.json` and the recorded decisions (`adapter_decisions`, `decisions` and `theme` in `.campaign-runtime/assembly-report.json`, and `assembly.template_decision_notes` in the Build Packet) before working on the campaign. The campaign intent summary at the top of the setup, build, Polish and QA prompts and in every `next` result is orientation, never a source of prices or commerce behaviour.
 - Read the assembly report decisions before polishing. Do not reintroduce source-HTML elements that build intentionally dropped because CampaignSpec/API did not support them, such as unavailable payment methods.
 - **Remove or rename a contract-listed payment-chrome asset; never edit one in place.** The assets named in `contracts/template-brand-contract.<family>.v0.json` under `default_residue.payment_chrome.assets` are keyed by QA on the *referenced basename*, not on their contents. Stripping the unsupported marks from inside a shared file such as `upsell-payment-logos.svg` leaves the reference in place, so QA reports residue for an asset that no longer carries any — and on 2026-09-06 the repair loop's remedy for that report deleted a cards-only trust strip that was correct. Delete the asset, or write a new one under a new name and repoint the reference. QA downgrades an edited-in-place asset to `manual_review` rather than a blocker, but that is a safety net for a mistake, not the supported way to do this.
 - Preserve existing `report.theme` data. If polish changes generated theme CSS, load order, commerce-page coverage, theme warnings, or the first repair-loop defect, update the Assembly Report `theme` block rather than leaving stale evidence.
@@ -78,13 +79,14 @@ Responsibilities:
   The package captures every mapped route at fixed desktop/mobile viewports and
   attaches `stages.polish.evidence.visual_review.page_load`. Never hand-author,
   copy, or repair that object directly.
+- When a readability warning appears, report it with its colours, ratio, requirement and pages. Offer the operator options inside the brand palette (a darker or lighter shade of the same hue, the palette's text colour, or a larger, bold label where the design allows). Do not recolour the merchant's design until the operator chooses. Accept a warning only with the refs, reason and name the operator gives you at the QC handoff.
 - Record Polish as `completed`, `skipped`, or `blocked` with
   `campaigns-os record polish --packet <packet> --evidence <polish-evidence.json>`
   (tier `C`: it overwrites `stages.polish` in the assembly report and stamps the
   doctor output stale; `--dry-run` is tier `none`). A nonzero capture result keeps
   Polish blocked until repair and recapture. The
   producer persists bounded incomplete evidence for diagnosis and does not mark
-  the stage complete.
+  the stage complete. Record Polish as `skipped` only when the operator decides in this conversation to skip it, and quote their reason as `skip_reason`.
 - Use `npm run smoke:polish-capture` only as an optional local producer smoke
   after browser installation. It opens a loopback fixture server and is not
   part of `npm run check` or the CI browser lane.
@@ -138,7 +140,7 @@ A Polish that cannot complete is recorded with the same command: a file with
 `"status": "blocked"` and `blockers` (a non-empty array of `{"code", "message"}`
 objects), or `"status": "skipped"` and a `skip_reason` string. `evidence` is
 optional for both; the captured evidence stays. Either keeps `next` at Polish
-and QA blocked until a completed Polish is recorded.
+and QA blocked until a completed Polish is recorded. Record Polish as `skipped` only when the operator decides in this conversation to skip it, and quote their reason as `skip_reason`.
 
 The `polish.hidden_eager_media` checkpoint blocks on nonwaivable missing,
 malformed, stale, integrity-invalid, route-mismatched, or incomplete package

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

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-qa
-version: 1.3.31
+version: 1.3.34
 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.52.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.52.0+skills.1`
+Bundle revision: 1.54.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.54.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
@@ -70,6 +70,7 @@ Inputs:
 - tested base URL (localhost dev URL, preview URL, or production URL)
 - assembly report
 - Test-order coverage choice (`common` default vs explicit paths vs topology-complete `full`) and SDK origin state (localhost is a Development domain; non-localhost origins need allowlist confirmation so the SDK loads)
+- Read the normalized Campaign Build Brief at `.campaign-runtime/input/campaign-build-brief.normalized.json` and the recorded decisions (`adapter_decisions`, `decisions` and `theme` in `.campaign-runtime/assembly-report.json`, and `assembly.template_decision_notes` in the Build Packet) before working on the campaign. The campaign intent summary at the top of the setup, build, Polish and QA prompts and in every `next` result is orientation, never a source of prices or commerce behaviour.
 
 Rules:
 
@@ -121,6 +122,7 @@ Rules:
 - For multi-market campaigns, verify at least one non-default currency/country path: currency display, shipping method names/prices, available payment methods, and market-specific copy.
 - Treat missing deploy URL, missing polish status, or unresolved doctor blockers as launch blockers.
 - Report blockers, warnings, and residual risks.
+- When a readability warning appears, report it with its colours, ratio, requirement and pages. Offer the operator options inside the brand palette (a darker or lighter shade of the same hue, the palette's text colour, or a larger, bold label where the design allows). Do not recolour the merchant's design until the operator chooses. Accept a warning only with the refs, reason and name the operator gives you at the QC handoff.
 - At the end of QA, run `next` and present the QC handoff once. Ask the operator which open warnings to accept and why. Run `checkpoint accept` only with the refs, reason, and name the operator gave you in this conversation. Never write `qc_accepts`, `qc_results`, or QA verdict files by hand. The up-front test-order permission does not cover accepts.
 - QA follows build and polish; it does not edit campaign code.
 

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.52.0+skills.1",
+  "bundle_revision": "1.54.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.47",
+      "version": "1.0.50",
       "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.30",
+      "version": "2.0.33",
       "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.32",
+      "version": "1.0.35",
       "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.31",
+      "version": "1.1.34",
       "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.31",
+      "version": "1.3.34",
       "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.27",
+      "version": "1.0.30",
       "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.27",
+      "version": "1.0.30",
       "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.27",
+      "version": "1.0.30",
       "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.27",
+      "version": "1.0.30",
       "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."