@nextcommerce/campaigns-os 1.53.0 → 1.55.0

package/docs/supported-surface.md

@@ -13,9 +13,10 @@ 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). |
+| `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. |
 | 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/docs/workflow-findings-sidecar.md

@@ -51,7 +51,8 @@ own schemas and evolve independently). Instead it carries:
 
 - **Stable envelope** — `schema_version` (`campaigns-os-run-record/v0`),
   `run_id`, package version, the command that ran, an `argv` *shape* (flag names
-  present, not raw values), `created_at`, consent state, and remit status.
+  present, not raw values), `created_at`, consent state, remit status, and
+  optional `closed_by` (`run_end`, `qa_auto_end`, `stale_sweep`, or `manual`).
 - **Run identity** — `map_id`, `campaign_slug`, `template_family`,
   `entry_point_shape`. (Best-effort; missing identity never blocks capture.)
 - **Source artifact refs** — for the Build Packet, Build Context, Assembly
@@ -64,6 +65,17 @@ own schemas and evolve independently). Instead it carries:
   this run.
 - **Findings snapshot** — this run's Workflow Findings (see channel below).
 
+When a QA verdict is present, `observations.qa.verdict_run_id` names the same
+verdict that supplies `disposition`. `build_fingerprint` is the QA stage's
+recorded build fingerprint only when the Assembly Report binds that stage to
+the same verdict; otherwise it is `null`. `stale` compares that fingerprint
+with the Assembly Report's recorded build fingerprint using the same comparison
+as `next`: `true` when they differ, `false` when they match, and `null` when
+either fingerprint is unknown. A rebuild without `record build` therefore reads
+`stale: false` when the recorded fingerprints still match; doctor's
+`built_output.fingerprint_stale` checks the output on disk. All three fields
+are optional for older records; without a verdict, `observations.qa` is absent.
+
 ### Run identity
 
 A single canonical `campaigns_os_run_id` is minted at the run boundary and
@@ -78,6 +90,45 @@ Stage timings and repair-loop count are captured from the command lifecycle
 journal when a run session or explicit lifecycle journal is active. They remain
 best-effort signal: telemetry records the commands Campaigns OS can observe, not
 every thought, browser click, or external editor action in an agent session.
+Each new journal entry records `wait_ms` as non-negative whole milliseconds
+blocked on terminal input; an invocation without a prompt records 0. Legacy
+entries may omit it or hold null, and Run Record stages preserve unknown wait
+as absent or null rather than inventing 0. `duration_ms` still includes prompt
+wait, so observed command work is `duration_ms - wait_ms` when wait is known. Tier-2 phases carry their
+own measured wait when the prompt occurs while that phase is active; the journal
+also retains the invocation total. Nested prompt hooks count their outer wait
+interval once. Authentication prompts are outside lifecycle capture by policy.
+
+On a non-zero doctor or QA exit, optional `finding_codes` is an array of at most
+five distinct string codes in first-seen order; null is invalid. Codes belong
+to the phase active when they were recorded. Codes recorded outside any phase,
+and codes in a legacy entry, are invocation-level only; aggregation assigns them
+to the entry's last phase. A successful stage has no finding codes. The optional run-level
+`needs_input_count` and `failure_count` are non-negative integer counts; null is
+invalid and absence means a legacy record did not report the count.
+`needs_input_count` counts journal entries with exit 2 and `failure_count`
+counts entries with any other non-zero exit. Current command
+paths use 0 for success, 1 for operational errors, 2 for missing or blocked
+inputs, and 4 for blocked QA; the other-non-zero rule also covers a future
+status without reclassifying exit 2. Both counts are per command invocation,
+including a command that emits multiple Tier-2 stages. `repair_loop_count`
+continues to count repeated commands plus explicit repair-loop hooks.
+
+| Terminal input site | Wait hook | Capture context |
+|---|---|---|
+| Consent question (`src/consent.mjs`) | Around the injectable `ask` call | Active command, including `run-record` |
+| Store question (`src/login.mjs`) | Around readline `question` | Authentication runs outside lifecycle capture |
+| Finding stage, kind, summary, details (`src/cli.mjs`) | Around each readline `question` | Active `findings add` command; omitted fields do not prompt |
+
+| Non-zero finding source | Codes recorded |
+|---|---|
+| `doctor` | `result.errors[].code` before rendering and exit 2 |
+| `start` and `build` | Their embedded doctor `errors[].code` before the prepare result sets exit 2 |
+| `qa run` and `qa parity` | Blocked verdict assertions: `evidence.code`, or assertion `id` when no code is present, before returning from QA dispatch with exit 4 |
+
+Spec resolution exceptions and prepare-build without a doctor result do not
+expose doctor or QA codes. They keep their existing exit and timing evidence,
+with no invented finding code.
 
 ### Validation
 
@@ -246,7 +297,11 @@ remit(path, payload, proxyBase)   // mirrors qa-node.mjs postVerdict
   for a later post of the stored verdict), `attempted` / `ok` / `error` /
   `endpoint` (`/api/qa/verdicts`), a `state` (`skipped` when the run's
   publish was off, `ok`, `failed`), the `result` in the same vocabulary as
-  `remit_result`, the `base_kind`, and `published_at`. `qa run` hands the
+  `remit_result`, the `base_kind`, `published_at`, and optional `reason`.
+  The reason records the actual QA publish decision: `loopback_base_url`,
+  `portal_managed_default`, `consent_off`, `flag_opt_out`, `flag_opt_in`,
+  `default`, or `local_spec`. A later `qa publish` has no QA run decision and
+  records a null reason. `qa run` hands the
   block to the session through its QA attempt, so `run end` and the auto-end
   stamp it; `qa publish` stamps the record whose `qa_verdict` artifact
   references the verdict, reads `state: "ok"` as already published, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextcommerce/campaigns-os",
-  "version": "1.53.0",
+  "version": "1.55.0",
   "description": "Toolkit for agent-assisted NEXT campaign builds.",
   "license": "Apache-2.0",
   "repository": {
@@ -66,6 +66,8 @@
     "check:spec": "node --test \"campaign-spec/test/**/*.test.ts\"",
     "check": "npm run check:provenance && npm run check:workflows && npm run check:changelog-structure && npm run build:spec && npm run check:tests && npm run check:spec && npm run check:fixtures && npm run check:legacy-migration && npm run check:spec-conformance && npm run check:private-strings && npm run check:template-doctrine && npm run check:slot-manifest && npm run check:skill-versions && npm run check:cart-readiness && npm run check:sidecar-bundle && npm run check:supported-surface && npm run check:effects && npm run check:release-ledger && npm run check:runtime-recipe && npm run check:orientation-docs && npm run check:runtime-docs && npm run check:pack -- --skip-prepare",
     "check:tests": "node ./scripts/check-tests.mjs",
+    "check:fast": "node ./scripts/check-fast.mjs",
+    "hooks:install": "node ./scripts/install-git-hooks.mjs",
     "check:legacy-migration": "node ./scripts/check-legacy-migration.mjs",
     "check:fixtures": "node ./scripts/check-fixtures.mjs",
     "check:spec-conformance": "node ./scripts/check-campaign-spec-conformance.mjs",

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/schemas/campaigns-os-run-record.v0.schema.json

@@ -134,6 +134,11 @@
           "enum": ["skipped", "ok", "failed"],
           "description": "skipped: publish was off for the run (no send). ok: the receiver's answer counts as stored. failed: refused or never answered."
         },
+        "reason": {
+          "type": ["string", "null"],
+          "enum": ["loopback_base_url", "portal_managed_default", "consent_off", "flag_opt_out", "flag_opt_in", "default", "local_spec", null],
+          "description": "The QA publish decision's reason. null when no decision was recorded, such as a later qa publish of a stored verdict."
+        },
         "result": {
           "type": ["string", "null"],
           "enum": ["stored", "already_stored", "ok_unparsed_ack", "refused", "transport_error", null],
@@ -226,6 +231,9 @@
           "additionalProperties": false,
           "properties": {
             "disposition": { "type": ["string", "null"] },
+            "verdict_run_id": { "type": ["string", "null"], "minLength": 1, "description": "Run ID of the verdict supplying disposition." },
+            "build_fingerprint": { "type": ["string", "null"], "minLength": 1, "description": "QA build fingerprint from the Assembly Report stage bound to that verdict." },
+            "stale": { "type": ["boolean", "null"], "description": "Whether that QA fingerprint differs from the current recorded build; null when either fingerprint is unknown." },
             "gap_classes": {
               "type": "array",
               "items": { "type": "string" },
@@ -286,19 +294,10 @@
       "type": ["string", "null"],
       "description": "Optional free-form confidence hint for primary_surface, e.g. \"low\"."
     },
-    "agent_usage": {
-      "type": "object",
-      "additionalProperties": false,
-      "description": "Optional host-supplied agent runtime usage. Campaigns OS does not infer these values; outer runners provide them when available.",
-      "properties": {
-        "input_tokens": { "type": "integer", "minimum": 0 },
-        "output_tokens": { "type": "integer", "minimum": 0 },
-        "tool_output_tokens": { "type": "integer", "minimum": 0 },
-        "total_tokens": { "type": "integer", "minimum": 0 },
-        "elapsed_ms": { "type": "integer", "minimum": 0 },
-        "model": { "type": "string" },
-        "source": { "type": "string" }
-      }
+    "closed_by": {
+      "type": "string",
+      "enum": ["run_end", "qa_auto_end", "stale_sweep", "manual"],
+      "description": "The command path that closed this Run Record. Absent on records written before this field existed."
     },
     "lifecycle": {
       "type": ["object", "null"],
@@ -327,17 +326,23 @@
             "type": "object",
             "additionalProperties": false,
             "required": ["name"],
+            "if": { "required": ["finding_codes"], "properties": { "finding_codes": {} } },
+            "then": { "required": ["exit_status"], "properties": { "exit_status": { "type": "integer", "not": { "const": 0 } } } },
             "properties": {
               "name": { "type": "string" },
               "duration_ms": { "type": ["number", "null"] },
-              "exit_status": { "type": ["integer", "null"] }
+              "exit_status": { "type": ["integer", "null"] },
+              "wait_ms": { "type": ["integer", "null"], "minimum": 0, "description": "Whole milliseconds blocked on operator input. Absent or null means unknown for legacy entries; duration_ms includes it." },
+              "finding_codes": { "type": "array", "maxItems": 5, "uniqueItems": true, "items": { "type": "string" }, "description": "First five distinct doctor or QA finding codes, only on a non-zero exit." }
             }
           }
         },
         "repair_loop_count": {
           "type": ["integer", "null"],
           "description": "Re-runs of any command within the run (a re-run is a repair loop: doctor -> fix -> doctor). 0 when each command ran once."
-        }
+        },
+        "needs_input_count": { "type": "integer", "minimum": 0, "description": "Number of command invocations with exit_status 2." },
+        "failure_count": { "type": "integer", "minimum": 0, "description": "Number of command invocations with a non-zero exit_status other than 2." }
       }
     }
   }

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

@@ -1,11 +1,11 @@
 ---
 name: campaign-lifecycle-orientation
-version: 1.0.29
+version: 1.0.32
 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.53.0+skills.2
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.53.0+skills.2`
+Bundle revision: 1.55.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.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.29
+version: 1.0.32
 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.53.0+skills.2
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.53.0+skills.2`
+Bundle revision: 1.55.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.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.29
+version: 1.0.32
 description: Interpret existing Campaigns OS doctor, QA and proof-depth evidence without claiming more proof than the artifacts contain.
 ---
 
-Bundle revision: 1.53.0+skills.2
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.53.0+skills.2`
+Bundle revision: 1.55.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.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.29
+version: 1.0.32
 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.53.0+skills.2
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.53.0+skills.2`
+Bundle revision: 1.55.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.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.34
+version: 1.0.37
 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.53.0+skills.2
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.53.0+skills.2`
+Bundle revision: 1.55.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.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.49
+version: 1.0.52
 description: Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth.
 ---
 
-Bundle revision: 1.53.0+skills.2
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.53.0+skills.2`
+Bundle revision: 1.55.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.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.32
+version: 2.0.35
 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.53.0+skills.2
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.53.0+skills.2`
+Bundle revision: 1.55.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.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.33
+version: 1.1.36
 description: Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign.
 ---
 
-Bundle revision: 1.53.0+skills.2
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.53.0+skills.2`
+Bundle revision: 1.55.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.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.33
+version: 1.3.36
 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.53.0+skills.2
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.53.0+skills.2`
+Bundle revision: 1.55.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read
@@ -80,7 +80,7 @@ Rules:
 - Parity capture blocking proof is the voucher-adjusted persisted line from typed-card order readback. Browser totals and client state do not replace the persisted-line voucher guard.
 - Read client purchase values per event. A whole-cart `dl_purchase` must not mask or supply an offer-level upsell purchase expectation.
 - Live `qa parity` runs publish to the QA portal by default like other QA runs. Pass `--no-post-verdict` for dev, replay, negative-control, and other local proof runs.
-- Theme gate: `qa run` refuses to run when a generatable brand theme is not applied to commerce pages and no waiver exists. Apply the brand layer or record a waiver (`campaigns-os theme waive`, tier `C`: it overwrites the assembly report and doctor output / `qa run --theme-waive "<reason>"`); do not bypass the gate another way. A waived run still reports template-residue findings at warn severity.
+- Theme gate: `qa run` refuses to run when a generatable brand theme is not applied to commerce pages and no waiver exists. Apply the brand layer or use the recorded waiver `campaigns-os theme waive --packet <p> --reason "<why>" --waived-by "<named human>"` (tier `C`: it overwrites the assembly report and doctor output). `qa run --theme-waive "<reason>"` is the one-run ephemeral form. Do not bypass the gate another way. A waived run still reports template-residue findings at warn severity.
 - Template residue is a QA dimension, not advice: promoted starter families must have a brand/residue/pricing contract (`contracts/template-brand-contract.<family>.v0.json`). Browser QA inspects computed styles on commerce surfaces and fails pages that still render starter defaults (`#3c7dff`/`#0a265c`, starter `next-logo.png`, paypal/klarna chrome absent from the spec).
 - Pricing visibility is a blocker: an upsell/downsell offer with zero visible price rows fails QA. Pricing surfaces render via template pricing modes (`full_price`, `compare_at_current`, `unit_price_plus_total`, `savings_badge_amount`, `code_discounted_post_checkout`), never via campaign CSS `display:none` on price wrappers.
 - The upsell and checkout bundle price checks count the SDK's `data-next-bundle-display` price as a price row when it is visible and not empty.

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.53.0+skills.2",
+  "bundle_revision": "1.55.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.49",
+      "version": "1.0.52",
       "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.32",
+      "version": "2.0.35",
       "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.34",
+      "version": "1.0.37",
       "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.33",
+      "version": "1.1.36",
       "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.33",
+      "version": "1.3.36",
       "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.29",
+      "version": "1.0.32",
       "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.29",
+      "version": "1.0.32",
       "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.29",
+      "version": "1.0.32",
       "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.29",
+      "version": "1.0.32",
       "path": "skills/contribution-intake/SKILL.md",
       "domain": "campaigns",
       "description": "Turn a suggestion about the agent surface into a classified, evidence-checked and redacted proposal, filed on this repository tracker only with attended approval."

package/src/adapter-decision-contract.mjs

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