@nextcommerce/campaigns-os 1.54.0 → 1.57.0

package/contracts/runtime-recipe.campaigns-os-node-v1.json

@@ -3,7 +3,7 @@
   "_growth_note": "When a bound below is genuinely reached, the answer is to find out why before raising it. A dependency install that exceeds its bound on a warm machine is a supply-chain change, not a slow morning; an output inventory that exceeds its file or byte bound is a build that went wrong, not a package that grew 50x overnight. Raising a bound is the fallback, it advances recipe_revision, and it owes a release-ledger entry. Widening the accepted npm range follows the same path, and its trigger is external and checkable: widen when a Node release line ships that npm major by default, not when a particular machine happens to have it installed.",
   "schema": "campaigns-os-runtime-recipe/v1",
   "recipe_kind": "campaigns-os-node-v1",
-  "recipe_revision": "1.0.2",
+  "recipe_revision": "1.0.3",
   "refusal_reason_code": "runtime_recipe_refused",
   "fail_closed": true,
   "unperformable_check_disposition": "failed",
@@ -106,6 +106,7 @@
     "fingerprint_algorithm": "sha256",
     "files": [
       "campaign-spec/analytics-vocabulary.ts",
+      "campaign-spec/checkout-flow.ts",
       "campaign-spec/index.ts",
       "campaign-spec/normalize.ts",
       "campaign-spec/package.json",
@@ -113,7 +114,9 @@
       "campaign-spec/rules/analytics-contract-shape.ts",
       "campaign-spec/rules/assembly-hints-shape.ts",
       "campaign-spec/rules/campaign-metadata.ts",
+      "campaign-spec/rules/checkout-forward-target.ts",
       "campaign-spec/rules/checkout-has-success-url.ts",
+      "campaign-spec/rules/checkout-step-reaches-checkout.ts",
       "campaign-spec/rules/cycle-detection.ts",
       "campaign-spec/rules/design-source-shape.ts",
       "campaign-spec/rules/downsell-without-upsell.ts",
@@ -124,9 +127,11 @@
       "campaign-spec/rules/funnel-weight-sum.ts",
       "campaign-spec/rules/index.ts",
       "campaign-spec/rules/offer-ref-integrity.ts",
+      "campaign-spec/rules/one-checkout-per-path.ts",
       "campaign-spec/rules/package-pricing-sanity.ts",
       "campaign-spec/rules/page-count.ts",
       "campaign-spec/rules/page-id-uniqueness.ts",
+      "campaign-spec/rules/pre-payment-forward-target.ts",
       "campaign-spec/rules/promo-code-input-validation.ts",
       "campaign-spec/rules/promo-codes-shape.ts",
       "campaign-spec/rules/route-field-ignored-for-page-type.ts",

package/contracts/supported-surface.json

@@ -1,6 +1,6 @@
 {
   "_note": "The downstream contract manifest. Everything listed here is SUPPORTED SURFACE: consumers (campaigns-agent, campaign-builder, the private ops repo, page-kit campaign repos) may depend on it, and changing it is a deliberate act — hashed entries require a surface_version bump in the same change (check-supported-surface.mjs --base, mirroring the skills.json bump gate), named entries must keep existing at their path, cli_commands must keep resolving in the CLI dispatch, package_exports must stay exported, and every entry must ship in the npm pack (files[] coverage). Anything NOT listed here — src/** internals, scripts/** checkers, examples/**, prompts/**, contracts/** other than this file and the entries named[] below (the orientation contract, the release ledger, and the consumer-facing orientation fixtures) — is implementation: consumers may read it for context but must not build on it, and it can change without notice. Rationale and the compatibility promise: docs/supported-surface.md.",
-  "surface_version": "1.54.0",
+  "surface_version": "1.57.0",
   "package_exports": [
     "./commercial-journey",
     "./commercial-parity",
@@ -8,6 +8,7 @@
     "./campaign-spec",
     "./legacy-migration",
     "./schemas/campaign-spec.v4.schema.json",
+    "./schemas/campaign-spec.v5.schema.json",
     "./schemas/campaigns-os-legacy-migration-inventory.v0.schema.json",
     "./schemas/campaigns-os-legacy-provisioning-plan.v0.schema.json",
     "./schemas/campaigns-os-legacy-provisioning-receipt.v0.schema.json",
@@ -51,7 +52,7 @@
       "sha256": "53269453dfdaac4b286124d445b60b0c46205dfbaf8037ac61b30254a32df53a"
     },
     "contracts/runtime-recipe.campaigns-os-node-v1.json": {
-      "sha256": "90aaaaade90cf2525ea1aa05be5cb2d02b57e6e59f9278a946efa8a087946fd3"
+      "sha256": "ab0537a4756310d3a35b400d3932e46695a820f1b8b398f52f6fd0906098bc1d"
     },
     "schemas/campaign-build-brief.v1.schema.json": {
       "sha256": "d524003184131398dc15fdb84385af1be0de0c69d6c5ede7278689a5b6101b81"
@@ -63,14 +64,17 @@
       "sha256": "625a6f2ed6bee726f9cddad750e64a54a7e03744c777f5a70afe4a39afdd9848"
     },
     "schemas/campaign-runtime-build-context.v0.schema.json": {
-      "sha256": "f310c1b7844d9b1994864d15858ff0c6f17efc1e5285ba193d181bdb2dd4be2f"
+      "sha256": "1f9bd6cced44a8ba6b29cc650f2b071db67ad710c5a9e9dfe47287eac11e0ebf"
     },
     "schemas/campaign-runtime-build-packet.v0.schema.json": {
-      "sha256": "5002529c5979c4d8fef7e298de82ebdf625ffbd11f5284ba684d96d173788d62"
+      "sha256": "f0952f64fe9f5ae6147649e5e99b24f215c8d080fca4e330d73f54e49a00d0e2"
     },
     "schemas/campaign-spec.v4.schema.json": {
       "sha256": "af56c3de638d3c4e1fd5df8c2d733754d9ad16caa23b5bec92ce3a6f71bd0271"
     },
+    "schemas/campaign-spec.v5.schema.json": {
+      "sha256": "2923382e94ac51f6a19a3f9dfd0993d8c30fab33cd9be3d6901f314e02f5d960"
+    },
     "schemas/campaigns-os-legacy-migration-inventory.v0.schema.json": {
       "sha256": "d6edc4572900d15fdaf6b8c59916b0d885303c1d398bdadeb7c58285522c9049"
     },
@@ -96,7 +100,7 @@
       "sha256": "d7521fe0ab4deb62485f92286cb890ee548ea290793a6ce7444ecc42ba336d49"
     },
     "schemas/campaigns-os-run-record.v0.schema.json": {
-      "sha256": "00dc9bcec79c12ea22a27f636188bcc33c6811df2d646ac7b49d4cc076e97355"
+      "sha256": "390cbc9debacfbfb17d999961baa041a2138fa20a116ec463fbbefbbb05f622d"
     },
     "schemas/campaigns-os-runtime-recipe.v1.schema.json": {
       "sha256": "f8a2ab5eadbb71fb6d5653b670ee71e4471c3df74dd04000d3dbd3d9ae9e71fc"

package/docs/brand-theme-bridge.md

@@ -22,6 +22,16 @@ It compares source tokens against known `figma-sections-export` scaffold
 defaults, maps real brand values onto a local versioned next-core target-token
 contract, and writes evidence into a theme report.
 
+A rule whose selector subject has a whole sale, discount, badge, rating, star,
+strike, border or announcement name part does not supply primary or CTA unless
+that subject also has a brand, primary, cta, button or btn part, or is a `button`
+element or a submit input. In comma lists,
+the other selectors still count. Primary keeps the header, navigation, brand
+and hero matching used on main, including element selectors and ancestors;
+button backgrounds keep the same CTA matching, including cart, buy, order and
+submit names and IDs. If no CTA token or button background exists, the CTA uses
+the accent fallback and the warning asks the operator to confirm it.
+
 `campaigns-os theme generate` writes:
 
 ```text

package/docs/build-packet.md

@@ -19,7 +19,8 @@ The current schema is `schemas/campaign-runtime-build-packet.v0.schema.json`.
 
 A saved Map is optional for a prepared-HTML build. The coding agent authors an
 ordinary CampaignSpec from the brief, source design and configured campaign's
-real commerce values, following `schemas/campaign-spec.v4.schema.json`. The
+real commerce values, following `schemas/campaign-spec.v5.schema.json` (a 4.2/4.3
+spec still reads, upgraded on read; see `docs/versioning.md`). The
 operator supplies the selected store/campaign, public Campaigns API key, intended
 pages and commercial choices, plus store contact details and policy URLs. Verify
 the store/campaign binding, and read the package, offer and shipping references
@@ -1020,13 +1021,25 @@ than hand-adding the field. Note that a committed artifact set always reads
 stale to the readback once HEAD moves past it — freshness proof is a
 regeneration at HEAD, not a property a commit can preserve.
 
-Commit durable packet/context/report artifacts when they represent a real build handoff. The rest of `.campaign-runtime/` is machine-local and is not for the campaign repository: `run-session.json`, `command-lifecycle.jsonl`, `agent-deviations.jsonl`, `workflow-findings.jsonl`, `run-records/`, `fetched-specs/`, `polish-evidence/`, `evidence/`, and `*.log`/`*.tmp` are per-machine, append-only, or carry live URLs and absolute paths, and so are the full QA verdicts `qa run` writes under the target's `qa-output/`. `start`, `prepare-build`, `install-agent-context`, and `run start` write a managed ignore block for exactly that set into the target's `.gitignore` once (keyed on its marker line; edit the list beneath it freely). The readback bundle (`build-context.json`, `assembly-report.json`, `doctor-output.json`, `qa-verdict.json`), `input/`, `theme/`, `agent-context/`, and `setup-handoff.json` are deliberately not ignored. The Campaigns API key is a public, browser-side, domain-allowlisted key and may already be present in the local CampaignSpec as `campaign.campaigns_api_key`; do not duplicate it into the packet unless the spec is unavailable. Do not commit raw private API responses, backend secrets, or temporary media exports.
+Commit durable packet/context/report artifacts when they represent a real build handoff. The rest of `.campaign-runtime/` is machine-local and is not for the campaign repository: `run-session.json`, `command-lifecycle.jsonl`, `agent-deviations.jsonl`, `workflow-findings.jsonl`, `run-records/`, `fetched-specs/`, `progress/`, `polish-evidence/`, `evidence/`, and `*.log`/`*.tmp` are per-machine, append-only, or carry live URLs and absolute paths, and so are the full QA verdicts `qa run` writes under the target's `qa-output/`. `start`, `prepare-build`, `install-agent-context`, and `run start` write a managed ignore block for that set into the target's `.gitignore` (keyed on its marker line; edit the list beneath it freely). An existing block gains `qa-output/` and `.campaign-runtime/progress/` when they are missing, since those hold live URLs, order references and remit records. The readback bundle (`build-context.json`, `assembly-report.json`, `doctor-output.json`, `qa-verdict.json`), `input/`, `theme/`, `agent-context/`, and `setup-handoff.json` are deliberately not ignored. The Campaigns API key is a public, browser-side, domain-allowlisted key and may already be present in the local CampaignSpec as `campaign.campaigns_api_key`; do not duplicate it into the packet unless the spec is unavailable. Do not commit raw private API responses, backend secrets, or temporary media exports.
 
 Packet-mode `doctor` is inspection-only by default and preserves retained evidence and active run journals, even when lifecycle capture is configured. Use `--write` to intentionally record fresh evidence; `--no-write` takes precedence. Inspection still reports current blockers and keeps the same exit status.
 
 `campaigns-os doctor --packet <packet> --write` restates its outcome on the Assembly Report's `stages.doctor` (status, command, outputs, blockers, warnings, `checked_at`). A re-run that reaches the same outcome leaves the report's bytes unchanged rather than refreshing the timestamp alone, so a digest taken of the report — a Run Record's `assembly_report` sha256 — keeps verifying across repeated doctor runs; a changed outcome still rewrites the file.
 
-`campaigns-os start` / `campaigns-os prepare-build` writes packet, context, report, and generated doctor-output paths as relative paths by default, including sibling CampaignSpec/source directories such as `../campaign-source`. `campaigns-os doctor` continues to accept older absolute-path packets; use `campaigns-os doctor --packet <packet> --write --strip-paths` when regenerating a commit-ready doctor output from an older packet. Committed handoff artifacts should not contain machine-local absolute paths unless no relative form is possible.
+`campaigns-os start` / `campaigns-os prepare-build` writes portable packet, context, report, and generated doctor-output paths. Resolve each path from its reader's base:
+
+| Field | Base | Writer |
+|---|---|---|
+| Build Packet `spec.local_path`, `design_source_package.path`, `source_html.root`, `build_brief.input_path`, `build_brief.normalized_path`, `assembly.target_repo`, `assembly.commerce_catalog.path` | Build Packet file's directory, including when `--out` places it under `config/` | `start` / `prepare-build`; `record brief` and stage records retain this base for older absolute values |
+| Build Packet `source_html.pages[].path`; Build Context `page_map[].source_path` | Source HTML root | `start` / `prepare-build`; later context writes retain it |
+| Build Packet and Build Context `source_html.pages[].page_kit.target_path` / `page_map[].page_kit.target_path` | Page Kit output directory | `start` / `prepare-build`; later packet/context writes retain it |
+| Build Packet `assembly.output_dir` and `source_html.pages[].page_kit.output_path`; Build Context `page_map[].output_path` and `page_map[].page_kit.output_path` | Target repository root | `start` / `prepare-build`; later packet/context writes retain it |
+| Build Context and Assembly Report `design_source_package.path` | Directory of that context or report file (normally `.campaign-runtime/`) | `start` / `prepare-build`; later report writes retain it |
+| Normalized Campaign Build Brief `_meta.input_path` | Directory of the normalized brief file | `start` / `prepare-build`; `record brief` and `record spec` retain it |
+| Other listed Build Context, Assembly Report, and doctor-output filesystem paths | Target repository root | Intake, `doctor --write`, `next`, and stage writes |
+
+Outside source inputs use ordinary relative paths from the applicable base; keep them at the recorded locations when moving the repository. Manifest paths embedded in decision evidence use relative paths from the target repository root. A stored command such as `next.command` uses a relative packet path and runs from the target repository root. `campaigns-os doctor` continues to accept older absolute-path packets; `--strip-paths` remains available when inspecting an older packet. Machine-local run sessions and journals remain ignored and may use absolute paths.
 
 `start` / `prepare-build` also run the [Brand Theme Bridge](./brand-theme-bridge.md)
 in `inspect_only` mode. The optional theme evidence lives in `context.theme`,
@@ -1253,25 +1266,39 @@ coverage blocks source readiness.
 
 ## Adapter And Proof Fields
 
-Fresh packets now include `source_html.adapter_contract`. Build Context and
-Assembly Report carry the same values as `adapter_decisions`, and build agents
-should update the report as they complete work.
+Fresh packets include `source_html.adapter_contract`. Build Context and
+Assembly Report carry the same values as `adapter_decisions`. After building,
+record the true scalar decisions with `record build --adapter-decision
+<key>=<value>[,<key>=<value>...]` (one flag, comma-separated `key=value`
+pairs). For example, set `raw_html_conversion_status=completed` after source
+HTML conversion, or `not_required` when there is no source HTML to convert.
+A repeated `--adapter-decision` flag keeps only the last list. The command
+writes the Assembly Report only. Doctor's adapter gates and leftover-wrapper
+check read the effective decisions in report → Build Context → packet order;
+doctor still validates each copy's shape separately. Source preparation reads
+the packet's `wrapper_policy`, which is selected at intake with
+`prepare-build --wrapper-policy` or the source-html manifest's `wrapper_policy`
+option. The record flag refuses that key, an unknown key, or a value outside
+the allowed values below. The object-valued
+`template_files_copied` has no flag: its `status`, `required_groups`, `groups`,
+and `paths` remain required proof in the report and keep their existing doctor
+checks.
 
 Required adapter decisions:
 
-| Field | Purpose |
-| --- | --- |
-| `raw_html_conversion_status` | Whether prepared HTML has been converted into page-kit-ready source. |
-| `source_asset_strategy` | How images/fonts/CSS/JS are moved and referenced. Prefer `pagekit_campaign_asset_root`. |
-| `commerce_shell_adoption` | Whether checkout/upsell/downsell/receipt use a template-clone-first SDK surface. |
-| `route_rewrite_policy` | How page links, CTAs, and SDK routing values were rewritten from CampaignSpec routes. |
-| `template_files_copied` | Whether the selected template family was copied/verified as one atomic page-kit slice. |
-| `config_script_strategy` | How campaign config scripts are loaded. |
-| `wrapper_policy` | Whether document wrappers are stripped, preserved, or not required. |
-| `frontmatter_policy` | How Page Kit YAML frontmatter is created or preserved. |
-| `script_style_reference_policy` | How scripts/styles move into frontmatter, campaign assets, inline blocks, or passthrough. |
-| `cta_rewrite_policy` | How CTA destinations are rewritten from CampaignSpec routes. |
-| `layout_choice` | Which Page Kit layout strategy wraps the prepared source. |
+| Field | Purpose | `record build` allowed values |
+| --- | --- | --- |
+| `raw_html_conversion_status` | Whether prepared HTML has been converted into page-kit-ready source. | `pending`, `in_progress`, `completed`, `not_required`, `blocked` |
+| `source_asset_strategy` | How images/fonts/CSS/JS are moved and referenced. | `pagekit_campaign_asset_root`, `external_cdn`, `raw_passthrough`, `not_applicable`, `unknown` |
+| `commerce_shell_adoption` | Whether checkout/upsell/downsell/receipt use a template-clone-first SDK surface. | `not_required`, `template_clone_first_required`, `template_clone_first_verified`, `sdk_surfaces_preserved`, `custom_html_experimental` |
+| `route_rewrite_policy` | How page links, CTAs, and SDK routing values were rewritten from CampaignSpec routes. | `campaignspec_routes_via_campaign_link`, `pagekit_public_routes`, `raw_passthrough`, `not_applicable`, `unknown` |
+| `template_files_copied` | Whether the selected template family was copied/verified as one atomic page-kit slice. | Object-valued proof; no flag |
+| `config_script_strategy` | How campaign config scripts are loaded. | `campaign_asset`, `frontmatter_script`, `inline`, `not_required`, `unknown` |
+| `wrapper_policy` | Whether document wrappers are stripped, preserved, or not required. | Intake only: `strip_document_wrappers`, `preserve_document_wrappers`, `not_required`, `unknown` |
+| `frontmatter_policy` | How Page Kit YAML frontmatter is created or preserved. | `pagekit_yaml_frontmatter`, `raw_passthrough`, `not_required`, `unknown` |
+| `script_style_reference_policy` | How scripts/styles move into frontmatter, campaign assets, inline blocks, or passthrough. | `frontmatter_or_campaign_asset`, `frontmatter`, `campaign_asset`, `inline`, `raw_passthrough`, `not_required`, `unknown` |
+| `cta_rewrite_policy` | How CTA destinations are rewritten from CampaignSpec routes. | `campaignspec_routes_via_campaign_link`, `pagekit_public_routes`, `raw_passthrough`, `not_applicable`, `unknown` |
+| `layout_choice` | Which Page Kit layout strategy wraps the prepared source. | `campaign_layout`, `page_layout`, `raw_passthrough`, `not_applicable`, `unknown` |
 
 Fresh build context also includes `source.asset_crawl`
 (`source-asset-crawl/v0`). `prepare-build` scans the source HTML files and
@@ -1449,10 +1476,29 @@ Fresh `prepare-build` output also writes `source_html.pages[].page_kit` for mapp
 - `target_path` is the page file relative to `assembly.output_dir` (`checkout.html`, `receipt.html`, etc.).
 - `output_path` is the same target file relative to `assembly.target_repo`.
 - `public_route` is the rendered campaign-rooted route Page Kit should produce.
-- `page_type` is the CPK runtime/analytics vocabulary (`product`, `checkout`, `upsell`, `receipt`), not the richer CampaignSpec or producer page type. CampaignSpec `select` pages project as CPK `checkout` because they are pre-checkout runtime selection surfaces.
-- `frontmatter` names the Page Kit frontmatter fields the build should write or preserve.
+- `page_type` is the CPK runtime/analytics vocabulary (`product`, `checkout`, `upsell`, `receipt`), not the richer CampaignSpec or producer page type. CampaignSpec `select` and `checkout_step` pages project as CPK `checkout` because they render the SDK checkout surface ahead of the page that takes payment.
+- `frontmatter` names the Page Kit frontmatter fields the build should write or preserve. Beside `page_type`, `permalink`, `next_url` and `decline_url`, two keys wire multi-step checkout paths: `success_url`, on every page that leads into a Checkout (a `select` page, a `checkout_step`, or a landing page whose forward links reach one), is that Checkout's post-payment destination and feeds the page's `next-success-url` meta tag, which the SDK reads for express orders; `step_number`, on a `checkout_step` only, is its position on its path from 1, for the step form's `data-next-step-number`. The step form's `data-next-checkout-step` is the page's `next_url`.
 - `permalink_required` is true when Page Kit's filename-derived route would not match `public_route`.
 
+An entry page (`is_entry: true`) declares the campaign root when `page_url` is
+empty, `/`, `/<slug>/`, or `<slug>`.
+If Page Kit emits its mapped target file, or a materialised template-stock
+family page, at that file's route without a root output, doctor recognizes the
+built page and warns that the root is unserved. The warning names both routes:
+add a redirect from the root to the emitted route or set
+`permalink: /<slug>/` on the entry page, the campaign root as Page Kit emits it.
+It uses `campaign.route_root`: a root-served campaign names `/` and
+`/<file-route>/`; a slug-served campaign names `/<slug>/` and
+`/<slug>/<file-route>/`. The built files stay under `_site/<slug>/` in both cases.
+`qa resolve --packet campaign-runtime.build.json --base-url <preview-url>` then
+prints the locally emitted entry route. An explicit permalink on that entry's
+Page Kit source file takes precedence, even if stale output remains at the
+file route. Doctor still warns if that permalink serves a non-root route and
+the root output is absent. With no permalink, a root `index.html` takes
+precedence over the recorded file route; with a non-root permalink, a present
+root output suppresses the warning while QA keeps the permalink Entry URL.
+Another page's `index.html` cannot stand in for the entry.
+
 The Design Source Package should reference this projection without confusing it
 with Surface Identity. Surface Identity is the campaign-facing join key; Page Kit
 `page_type`, public routes, output paths, CampaignSpec/Map Builder page IDs,
@@ -1737,7 +1783,7 @@ hand-editing `.campaign-runtime/` JSON:
 | Command | Writes | Refused (nothing written) when |
 |---|---|---|
 | `campaigns-os record setup --packet <p>` | Build Context `scaffold.required=false` (`handoff_skill` next-campaigns-build) and `stages.setup` completed | the campaign output directory (`assembly.output_dir`) does not exist, or there is no Build Context or Assembly Report |
-| `campaigns-os record build --packet <p> [--build-environment <development\|production>]` | `stages.assembly` completed with `build_fingerprint` = doctor's `derived.build_output_fingerprint.value`, `source_package_material_fingerprint` = the report's Design Source Package material fingerprint when present, `evidence.build_environment` = the `--build-environment` value when given (kept from the last record otherwise), and `stages.polish` reset to `required` (`required_by` build, `required_for` qa) unless its evidence is bound to this exact output; a completed `stages.deploy` whose `source_build_fingerprint` names other output is reset to `required` the same way, without the old probe's `outputs` and `evidence`, and its prior record is kept in `stages.deploy.history` (a deploy with no `source_build_fingerprint`, recorded before deploy stamped it, is kept) | doctor cannot compute the fingerprint (no `_site/<public_route_slug>/`), setup is still required, or `stages.setup` is not terminal |
+| `campaigns-os record build --packet <p> [--build-environment <development\|production>] [--adapter-decision <key>=<value>[,<key>=<value>...]]` | `stages.assembly` completed with `build_fingerprint` = doctor's `derived.build_output_fingerprint.value`, `source_package_material_fingerprint` = the report's Design Source Package material fingerprint when present, `evidence.build_environment` = the `--build-environment` value when given (kept from the last record otherwise), and the specified scalar `report.adapter_decisions`; all recordable decisions go in one comma-separated flag (a repeated flag keeps only the last list); `wrapper_policy` stays an intake choice. `stages.polish` resets to `required` (`required_by` build, `required_for` qa) unless its evidence is bound to this exact output; a completed `stages.deploy` whose `source_build_fingerprint` names other output resets to `required` the same way, without the old probe's `outputs` and `evidence`, and its prior record is kept in `stages.deploy.history` (a deploy with no `source_build_fingerprint`, recorded before deploy stamped it, is kept) | doctor cannot compute the fingerprint (no `_site/<public_route_slug>/`), setup is still required, `stages.setup` is not terminal, or an adapter decision key/value is invalid |
 | `campaigns-os record polish --packet <p> --evidence <file>` | `stages.polish` from the file (`docs/polish-evidence.md` §7: completed, blocked or skipped), bound to doctor's current fingerprint; `report.theme.repair_loop_defect` when the file sets it | build is not recorded for the current output, the file has a shape error (named by field), or, for a completed status, the polish gate doctor evaluates would not pass on the result |
 | `campaigns-os record theme --packet <p>` | `report.theme`: status `applied`, `load_order` `after-next-core`, `css_path`, `commerce_pages` and per-page evidence read from each built commerce page's stylesheet links; any earlier theme waiver is cleared | build is not recorded for the current output, the campaign ships no commerce pages, a built commerce page that loads `next-core.css` does not load `brand-theme.css` (or `checkout-brand.css`) after it or links one missing from the built output, or no built commerce page loads `next-core.css` |
 | `campaigns-os record deploy --packet <p> --base-url <url>` | the packet's `deploy.preview_url` and `stages.deploy` completed with the URL in `outputs`, one evidence line per built page that answered (each page is requested under the URL first), and `source_build_fingerprint` = the recorded `stages.assembly.build_fingerprint` it probed, so a later `record build` of different output makes deploy owed again and `next` routes back to `record deploy` before QA; a byte-identical rebuild keeps it current | the packet is not `local-serve`, the URL is not a loopback origin naming the campaign's route root, a built page does not answer 2xx, polish is not recorded, the built output changed since build was recorded, or the theme gate is blocked |
@@ -1747,7 +1793,19 @@ prepare-build gate is set (`next` answers prepare-build) or while an earlier
 stage in the order below is not terminal. The exception is the one `next`
 makes: on the local preview, a polish doctor carries forward (never recorded
 for this build) does not hold `record deploy` back, as it does not hold `next`;
-polish stays owed and QA reports it.
+polish stays owed and QA reports it. If every mapped page is template stock on
+a hosted preview, doctor carries the same missing-evidence shape forward.
+`record deploy` remains local-only: record an unset hosted preview URL with
+`campaigns-os qa policy set --packet <p> --preview-url <url>`, then run
+`campaigns-os next --packet <p>`. The hosted preview must be a non-loopback
+HTTP(S) URL whose origin or QA-resolved campaign route path differs from `deploy.production_url`;
+query and fragment text does not make the production page a preview. With
+`deploy.preview_url` recorded, run `campaigns-os next qa --packet <p>` and
+`campaigns-os qa run --packet <p> --base-url <preview-url> --browser
+--test-order common`. The recorded hosted preview satisfies the deploy step
+for this all-template shape. After QA records a verdict for the current build,
+`campaigns-os next --packet <p>` reaches closeout without a hosted deploy
+record. QA against the packet's production URL retains the strict gate.
 
 Each command reads the same packet, Build Context and Assembly Report `next`
 reads (`--context` / `--report` override them the same way), validates what it
@@ -1773,9 +1831,11 @@ check exits non-zero with the problems listed, one per line; a value outside a
 schema enum (for example an `adapter_decisions` policy) is listed with the
 values the schema allows and the value it got. Re-run `record
 build` after every page-kit build; a rebuild that changes the output needs
-`polish capture` and `record polish` again.
+`polish capture` and `record polish` again. After deploy is recorded for the
+rebuilt output, `next` asks for QA again if the last QA record names the
+previous build fingerprint, even while its stage status still says completed.
 
-Stage order: `setup → build → polish → deploy → qa`. The picker walks this list and returns the first stage whose recorded status isn't terminal (`completed`, `completed_with_warnings`, `skipped`). During Polish, install the package-owned browser first, then run `campaigns-os polish capture` against the served current build before recording a terminal `stages.polish.status` or proceeding to deploy/QA; the producer attaches package-owned `visual_review.page_load` evidence and never marks the stage complete itself.
+Stage order: `setup → build → polish → deploy → qa`. The picker walks this list and returns the first stage whose recorded status isn't terminal (`completed`, `completed_with_warnings`, `skipped`), except that a carried-forward all-template hosted preview with a recorded `deploy.preview_url` satisfies deploy without a report record. During Polish, when a design route exists, install the package-owned browser first, then run `campaigns-os polish capture` against the served current build before recording a terminal `stages.polish.status` or proceeding to deploy/QA; the producer attaches package-owned `visual_review.page_load` evidence and never marks the stage complete itself. Template-stock campaigns with no design route have no capture to run and follow the preview policy above.
 
 | Stage | Report key | Owner |
 |---|---|---|
@@ -1808,7 +1868,7 @@ Result shape (with `--json`):
 Terminal states:
 
 - **`stage: "doctor-blocked"`** — doctor returned errors. Resolve the blockers and re-run `campaigns-os doctor` to confirm before calling `next` again.
-- **`stage: "done"`** — every stage is in a terminal status. Pipeline is complete. To re-run a specific stage, set its status back to `"pending"` in the assembly report and call `next` again.
+- **`stage: "done"`** — every stage is terminal, or a carried-forward all-template hosted preview satisfies deploy with a recorded `deploy.preview_url` and current-build QA verdict. Pipeline is complete. To repeat build work, do the work and use `record build`; it makes downstream stages owed as needed. Use `record setup` or `record polish` after repeating those stages, and `qa run` for QA. `record deploy` records a local-serve target; other hosted deploys record the URL and stage outcome as the deploy prompt describes. Then call `next` again.
 - **`stage_blocked: true`** — the picker returned a stage whose recorded status is `blocked`. Don't run the prompt as-is; clear the blocker first.
 
 The legacy form `campaigns-os next <stage>` (e.g. `next build`) still works and is the way to force a specific stage when you want to override the picker.

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

@@ -12,7 +12,7 @@ The happy path is intentionally tight:
 8. Run polish, serve the current built output, and run `campaigns-os polish capture --packet <packet> --base-url <served-current-build-url>`. Do not mark Polish terminal or begin deploy/QA until this package-owned page-load evidence passes or has an exact finding waiver.
 9. Deploy a preview.
 10. Run `campaigns-os qa resolve --packet <packet>`, then `campaigns-os qa run --packet <packet> --browser --test-order common` with the tested URL. Saved-Map QA uses the existing consent and publication controls; pass `--no-post-verdict` to keep its verdict local. Local-spec QA always keeps verdicts and progress local, even with `--post-verdict`, and `qa publish` refuses local-spec packets. Run Telemetry retains its consent controls.
-11. Treat test-order depth as the control: global test cards bypass the gateway and create no transactions, so no approval is needed. Localhost on any port is a Campaigns App Development domain (SDK allowed, analytics suppressed); non-localhost preview/production origins must still be allowlisted for the campaign API key so the SDK loads.
+11. Global test cards bypass the gateway and create no transactions, but each test order leaves a real store order record. Unless the operator has already said test orders are fine for this campaign, ask once, up front, before placing test orders; then proceed. There is no permission flag; test-order depth controls coverage. Localhost on any port is a Campaigns App Development domain (SDK allowed, analytics suppressed); non-localhost preview/production origins must still be allowlisted for the campaign API key so the SDK loads.
 12. Promote, block, or iterate from the recorded build, polish, deploy, QA, and test-order evidence.
 
 Pause only for missing inputs, doctor blockers, blocked deploys, out-of-scope runtime pages that block checkout proof, or merchant-specific uncertainty. The default path should not branch into external browser skills or hand-built backend order creation.

package/docs/effects.md

@@ -209,9 +209,7 @@ template family is certified, and whether a named brief can be read, depend on
 file content: those checks still run in the handler and are journaled.
 The operator-facing `run-record` and `run end` commands refuse bare, empty, or
 whitespace-only values for every value-taking inherited run-record flag before
-packet work. The five agent
-token and elapsed-time flags retain their non-negative-integer diagnostics;
-`--surfaces` rejects unknown values, and `--dry-run` rejects a value. The
+packet work. `--surfaces` rejects unknown values, and `--dry-run` rejects a value. The
 inherited boolean flags (`--no-remit`, `--no-write`, `--dry-run`, and `--json`)
 retain their bare-flag behavior. `run end` also rejects `--new-run` and
 `--run-id` because the saved session fixes its run ID. `run-record` also
@@ -225,8 +223,7 @@ literal relative path, so the default context file is not read. Bare or empty
 `--context` or `--report` still makes QA auto-end fail and leaves the session
 open; bare or empty `--qa-verdict` fails a Run Record closeout when inherited,
 though QA auto-end supplies its own verdict path. The underlying run-record
-handler still rejects invalid agent
-integers, unknown `--surfaces`, and any valued `--dry-run` that reaches it. QA
+handler still rejects unknown `--surfaces` and any valued `--dry-run` that reaches it. QA
 auto-end drops `--dry-run` from inherited flags; if another inherited value
 fails in the handler, auto-end is skipped and the session stays open. QA's own
 journal entry is unaffected because auto-end runs after QA persistence. A named

package/docs/local-setup.md

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

package/docs/orientation-contract-reference.md

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