@nextcommerce/campaigns-os 1.54.0 → 1.55.0

package/contracts/release-ledger.json

@@ -6530,6 +6530,447 @@
         }
       ],
       "entry_sha256": "5ab33ca302fa671ac78c3e9b752ed7b251e756b05256f97ff75acd08c58ad5ba"
+    },
+    {
+      "id": "RL-0246",
+      "sequence": 235,
+      "date": "2026-10-07",
+      "kind": "release",
+      "surface_version": null,
+      "changelog_section": "1.54.0+agent.2",
+      "changelog_sha256": "55155add247bb47b07b43252e374b504ac85aef51f6b3315b8b21e85c615df15",
+      "agent_impact": "None for package consumers: this changes repository CI and contributor scripts only. A contributor can run npm run check:fast before pushing, or install it as a pre-push hook with npm run hooks:install; CI runs the same gates on every pull request.",
+      "compatibility": "compatible",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "workflow",
+          "path": ".github/workflows/ci.yml",
+          "surface_entry": null,
+          "summary": "Run the unit and browser lanes as two shards each on separate runners, and cancel a pull request's older run when a newer push arrives; pushes to main are never cancelled."
+        },
+        {
+          "class": "package_export",
+          "path": "package.json",
+          "surface_entry": null,
+          "summary": "Add the contributor scripts check:fast and hooks:install; exports, bin, files and dependencies are unchanged."
+        }
+      ],
+      "entry_sha256": "ea7360b560411019e58bf65a1b389cbed5ec9589b7da6f09b7cee1b08b46aed8"
+    },
+    {
+      "id": "RL-0247",
+      "sequence": 236,
+      "date": "2026-10-07",
+      "kind": "release",
+      "surface_version": null,
+      "changelog_section": "1.54.0+agent.4",
+      "changelog_sha256": "320b31d293424ab65875a6b05f1d1f2b79ace291914e8311e69fb52738f584b1",
+      "agent_impact": "Treat ready_with_exceptions as passing QA proof and report every exception to the operator without clearing or waiving it or changing markup just to make it pass. Keep the done closeout action. Repeat build work with record build; follow the deploy prompt for hosted deploy recording. A recorded theme waive needs --waived-by with a named human; qa run --theme-waive is one-run only. Unless the operator has already said test orders are fine for this campaign, ask once, up front, before typed-card test orders because they create real store order records, although no transaction or money movement occurs. No command, gate, flag or verdict-schema behavior changes.",
+      "compatibility": "compatible",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "documentation",
+          "path": "CONTEXT.md",
+          "surface_entry": "CONTEXT.md",
+          "summary": "Explain that typed-card test orders create real store order records and require a once-up-front operator question."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/build-packet.md",
+          "surface_entry": "docs/build-packet.md",
+          "summary": "The done guidance names record build for repeat build work and distinguishes local-serve recording from hosted deploy instructions."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/campaigns-os-build-flow.md",
+          "surface_entry": "docs/campaigns-os-build-flow.md",
+          "summary": "Explain the real order record and once-up-front operator question before typed-card test orders."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/qa-and-test-orders.md",
+          "surface_entry": "docs/qa-and-test-orders.md",
+          "summary": "Explain the real store order record and the once-up-front operator question before test orders."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/skills-revision.md",
+          "surface_entry": "docs/skills-revision.md",
+          "summary": "Publish the 1.54.0+skills.2 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills.json",
+          "surface_entry": null,
+          "summary": "Publish the 1.54.0+skills.2 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/campaign-lifecycle-orientation/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.54.0+skills.2 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/campaign-readback-classification/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.54.0+skills.2 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/campaign-run-evidence/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.54.0+skills.2 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/contribution-intake/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.54.0+skills.2 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-build/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.54.0+skills.2 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-os-setup/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.54.0+skills.2 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-os/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.54.0+skills.2 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-polish/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.54.0+skills.2 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-qa/SKILL.md",
+          "surface_entry": null,
+          "summary": "Name the recorded theme waiver with the named-human argument and distinguish the one-run ephemeral QA form."
+        },
+        {
+          "class": "cli_surface",
+          "path": "src/cli.mjs",
+          "surface_entry": "next",
+          "summary": "Clarify passing QA exceptions, stage re-recording, recorded versus ephemeral theme waivers, and the test-order operator question in prompts and notices."
+        },
+        {
+          "class": "cli_surface",
+          "path": "src/doctor/next-step.mjs",
+          "surface_entry": "next",
+          "summary": "Keep the done closeout action alongside the passing-QA exception report instruction."
+        }
+      ],
+      "entry_sha256": "05712ef5b61b5e84a2937c2528612206dffde439f2929bb853bd72c015538514"
+    },
+    {
+      "id": "RL-0248",
+      "sequence": 237,
+      "date": "2026-10-07",
+      "kind": "release",
+      "surface_version": null,
+      "changelog_section": "1.54.0+agent.5",
+      "changelog_sha256": "b76dfa416d6d20c2ec5e9c94802e2b811ba7133bf248e9430c283f06e3882398",
+      "agent_impact": "qa run --test-order now drives a bundle-card checkout by each card's data-next-bundle-items. --select-package <pkg>:<qty> and --cart <pkg>:<qty> select the card one of whose declared items is that package at that quantity, preferring a card that declares it alone, even when no inner node repeats the package id; a kit card declaring several items is found by any of them. --cart reads the cards again before each ref. Beside --select-package, --cart never clicks another card in the chosen card's selector group (bundle or plain package cards; a card in no recognised selector container counts as in that group): a ref the chosen card carries is left alone, a ref an order bump or a card in another selector group carries is applied through that control, and any other ref is left unapplied and named in the selected_bundle detail as '--cart <ref:qty> not applied: <reason>'. Read that note as a conflict between the two flags; the order and its reconciliation are those of the card --select-package chose. The browser-order-display-parity row reconciles against the packages and quantities every selected bundle card declares, not its data-next-bundle-id, and, without --select-package, fails when an explicit --cart <ref:qty> is not in the order at that quantity, naming requested and persisted units or saying the order carries no line for the package. Read a failing row whose message says the ordered quantity differs from the request as a wrong-tier order, not a stray charge.",
+      "compatibility": "compatible",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "named_surface",
+          "path": "docs/qa-and-test-orders.md",
+          "surface_entry": "docs/qa-and-test-orders.md",
+          "summary": "Say that --select-package and --cart resolve a bundle card by any one of its data-next-bundle-items, that --cart reads the cards again before each ref, that --cart beside --select-package never clicks another card in the chosen card's selector group (a card in no recognised selector container counts as in it) and names a ref it leaves unapplied, and that display parity reconciles against every selected card's declared packages and, without --select-package, fails on an explicit --cart <ref:qty> the order did not carry at that quantity."
+        }
+      ],
+      "entry_sha256": "dbb47405a3d96886de22e8ad85dcf9a703da0ef122eccb33b6c64ecb66ea4b38"
+    },
+    {
+      "id": "RL-0249",
+      "sequence": 238,
+      "date": "2026-10-07",
+      "kind": "release",
+      "surface_version": null,
+      "changelog_section": "1.54.0+agent.6",
+      "changelog_sha256": "e49fec365f247824e1af1863ce8124a8ec62dbda64c8c94c68fc7734b83833f0",
+      "agent_impact": "Doctor blocks receipt order lines hidden by cart state, including when the CampaignSpec alone identifies the receipt page. When the Build Packet or CampaignSpec supplies the campaign API key directly, or Build Packet campaign.api_key_source names an environment variable, doctor compares it with built keys even when all pages agree. Correct these findings before test orders.",
+      "compatibility": "compatible",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "cli_surface",
+          "path": "src/doctor/checks.mjs",
+          "surface_entry": "doctor",
+          "summary": "Block receipt order items hidden by cart-state visibility and compare built API keys with the packet, spec, or environment key declared by the packet."
+        }
+      ],
+      "entry_sha256": "b56a454c0160f664fd473cbc834146630c207885c2cbf5c2c8e37d294208da4e"
+    },
+    {
+      "id": "RL-0250",
+      "sequence": 239,
+      "date": "2026-10-07",
+      "kind": "release",
+      "surface_version": null,
+      "changelog_section": "1.54.0+agent.7",
+      "changelog_sha256": "8c43339dac5e7fc33ad1bdff344c5db50b2e7b7f8a5d7b631f309676d70e79ce",
+      "agent_impact": "qa run takes --currency <code> to run QA in one currency of a multi-currency campaign: the run adds ?currency=<CODE> to each funnel entry URL it fetches and loads and to the first page load of each test-order path, keeping the existing query; later loads in that tab and a receipt reload carry none, because Campaign Cart keeps the currency for the tab's session. The code must be three letters and is upper-cased; anything else, an empty value included, is refused before any request. The flag takes one code per run (given twice, the last is used): run qa run once per currency. qa parity --currency, and --currency with --legacy-api-test-order, are refused. Read the run currency from evidence.currency on the entry page http:<page_id> assertion of the full verdict; the stored verdict removes URL queries. An entry URL that does not parse carries evidence.currency_not_applied with the reason instead. A run without the flag is unchanged.",
+      "compatibility": "compatible",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "cli_surface",
+          "path": "src/cli.mjs",
+          "surface_entry": "qa",
+          "summary": "The qa run usage line lists --currency <code>; keep the existing QA recommendation command set while next routes owed Polish and QA stages; show an open adapter-decision template in the build prompt and document the single-list behavior, local proof environment, and build fingerprint source in help."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/qa-and-test-orders.md",
+          "surface_entry": "docs/qa-and-test-orders.md",
+          "summary": "Describe qa run --currency: one code per run, ?currency=<CODE> on the entry URL and on each test-order path's first load with the existing query kept, the three-letter refusal, the qa parity and legacy-order refusals, and evidence.currency (or evidence.currency_not_applied) on the entry page http row."
+        }
+      ],
+      "entry_sha256": "ca7d3c91091fd6c5c857820ffe3ea6b9a62a9f428c0eab26cbf0b1df098fc942"
+    },
+    {
+      "id": "RL-0251",
+      "sequence": 240,
+      "date": "2026-10-07",
+      "kind": "release",
+      "surface_version": null,
+      "changelog_section": "1.54.0+agent.8",
+      "changelog_sha256": "57049338b1514529ff826c0477082d1f9e31de77f0a1308473ab0d7cafb8c01b",
+      "agent_impact": "Next asks for Polish when a local preview theme waiver or changed build leaves it owed, and asks for QA again when the last recorded QA build differs from the current output. A packet preview URL does not replace record deploy. Help invocations never journal, and later start is valid re-intake. Follow next before recording downstream work.",
+      "compatibility": "compatible",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "cli_surface",
+          "path": "src/doctor/next-step.mjs",
+          "surface_entry": "next",
+          "summary": "Pick Polish after a local theme waiver or rebuild, and re-owe QA for a different build while still requiring recorded deploy."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/build-packet.md",
+          "surface_entry": "docs/build-packet.md",
+          "summary": "Explain the deploy record and QA order after a changed build; list recordable values, explain wrapper_policy intake and read precedence, and document one-list behavior and the report-only write."
+        }
+      ],
+      "entry_sha256": "7ffb028e273e591d224628ceea618df57233286a273e7813ec3a1fb0e47479c4"
+    },
+    {
+      "id": "RL-0252",
+      "sequence": 241,
+      "date": "2026-10-07",
+      "kind": "release",
+      "surface_version": null,
+      "changelog_section": "1.54.0+agent.9",
+      "changelog_sha256": "14a10e9c78458f100c075cff330d5a72364dcd5b00c720a3bf5809843269f542",
+      "agent_impact": "After a page-kit build, record the true scalar adapter choices in one record build --adapter-decision list; a repeated flag keeps only the last list. wrapper_policy remains an intake choice. Doctor reads the effective report, context, then packet conversion status for leftover wrappers and its adapter warnings name the recording command. The Build Packet and Build Context are not written by record build.",
+      "compatibility": "additive",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "cli_surface",
+          "path": "src/doctor/checks.mjs",
+          "surface_entry": "doctor",
+          "summary": "Check leftover source document wrappers against the effective report, context, then packet conversion status."
+        }
+      ],
+      "entry_sha256": "2604e105b3c308004f617b3fd839acc01f32e75dbe4ebf28324f23569aebc5db"
+    },
+    {
+      "id": "RL-0253",
+      "sequence": 242,
+      "date": "2026-10-07",
+      "kind": "release",
+      "surface_version": null,
+      "changelog_section": "1.54.0+agent.10",
+      "changelog_sha256": "c693a2482b40ae5bc570dc591927fc60c2193d339a2c36df8489c885d0028fdd",
+      "agent_impact": "Theme inspection excludes decorative selector subjects from primary and CTA selection while keeping the primary and CTA matching used on main. An accent-only CTA fallback asks the operator to confirm its colour.",
+      "compatibility": "compatible",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "named_surface",
+          "path": "docs/brand-theme-bridge.md",
+          "surface_entry": "docs/brand-theme-bridge.md",
+          "summary": "Explain decorative subject exclusions, main-compatible primary and CTA matching, and the accent-only fallback warning."
+        }
+      ],
+      "entry_sha256": "446b7cc41c5af2352fecedebc543e9bb38a31b025afe2b60848d912e615f902b"
+    },
+    {
+      "id": "RL-0254",
+      "sequence": 243,
+      "date": "2026-10-07",
+      "kind": "release",
+      "surface_version": "1.55.0",
+      "changelog_section": "1.55.0",
+      "changelog_sha256": "cfd5709d45e917e8e4ee92e42b8ceb09d560c9fbf023ca4c6552a55874877e7b",
+      "agent_impact": "Run Records carry QA publish reason, closing path, QA verdict/build binding, prompt wait, bounded doctor/QA codes, and separate needs-input/failure invocation counts. Legacy journal entries keep wait unknown. Agent usage input is gone. Re-emitting a record with agent_usage replaces it with a fresh record without carrying its prior remit state; qa publish posts but cannot stamp that older record as published.",
+      "compatibility": "breaking",
+      "migration": "Stop passing agent usage flags. Re-emitting a legacy agent_usage record replaces it and drops its prior remit state; qa publish posts but cannot stamp it.",
+      "changes": [
+        {
+          "class": "compatibility_policy",
+          "path": "contracts/supported-surface.json",
+          "surface_entry": "contracts/supported-surface.json",
+          "summary": "Advance surface_version to 1.55.0 and record the Run Record schema hash, including lifecycle telemetry fields."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/effects.md",
+          "surface_entry": "docs/effects.md",
+          "summary": "Remove the obsolete agent usage flag validation description."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/qa-and-test-orders.md",
+          "surface_entry": "docs/qa-and-test-orders.md",
+          "summary": "Name the nullable QA publish decision reason in the Run Record."
+        },
+        {
+          "class": "compatibility_policy",
+          "path": "docs/supported-surface.md",
+          "surface_entry": "docs/supported-surface.md",
+          "summary": "Mark 1.55.0 breaking: add publish, closeout, QA observation, lifecycle stage wait and finding-code, and run-level exit-count fields; remove agent_usage."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/workflow-findings-sidecar.md",
+          "surface_entry": "docs/workflow-findings-sidecar.md",
+          "summary": "Document the publish reason, closing path, QA verdict/build binding, prompt wait, code sources, and exit buckets."
+        },
+        {
+          "class": "generated_runtime",
+          "path": "package-lock.json",
+          "surface_entry": null,
+          "summary": "Advance the package version to 1.55.0."
+        },
+        {
+          "class": "package_export",
+          "path": "package.json",
+          "surface_entry": null,
+          "summary": "Advance the package version to 1.55.0 with exports unchanged."
+        },
+        {
+          "class": "schema",
+          "path": "schemas/campaigns-os-run-record.v0.schema.json",
+          "surface_entry": "schemas/campaigns-os-run-record.v0.schema.json",
+          "summary": "Add optional QA publish, closeout, and currency fields plus lifecycle wait, finding codes, and exit buckets; remove agent_usage."
+        },
+        {
+          "class": "cli_surface",
+          "path": "src/cli.mjs",
+          "surface_entry": "run-record",
+          "summary": "Pass each closer through internal options, route prompt wait and finding codes to lifecycle capture, and remove agent usage flags."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/runtime-readiness.md",
+          "surface_entry": "docs/runtime-readiness.md",
+          "summary": "Regenerate at surface 1.55.0."
+        },
+        {
+          "class": "documentation",
+          "path": "docs/orientation-contract-reference.md",
+          "surface_entry": "docs/orientation-contract-reference.md",
+          "summary": "Regenerate at surface 1.55.0."
+        },
+        {
+          "class": "compatibility_policy",
+          "path": "compatibility.json",
+          "surface_entry": null,
+          "summary": "Advance the declared version to 1.55.0."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/local-setup.md",
+          "surface_entry": "docs/local-setup.md",
+          "summary": "Pin the 1.55.0 package in the local setup install command."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/skills-revision.md",
+          "surface_entry": "docs/skills-revision.md",
+          "summary": "Restamp to skills bundle 1.55.0+skills.1."
+        },
+        {
+          "class": "skill",
+          "path": "skills.json",
+          "surface_entry": null,
+          "summary": "Advance bundle_revision to 1.55.0+skills.1 and the patch version of each restamped skill."
+        },
+        {
+          "class": "skill",
+          "path": "skills/campaign-lifecycle-orientation/SKILL.md",
+          "surface_entry": null,
+          "summary": "Restamp to skills bundle 1.55.0+skills.1."
+        },
+        {
+          "class": "skill",
+          "path": "skills/campaign-readback-classification/SKILL.md",
+          "surface_entry": null,
+          "summary": "Restamp to skills bundle 1.55.0+skills.1."
+        },
+        {
+          "class": "skill",
+          "path": "skills/campaign-run-evidence/SKILL.md",
+          "surface_entry": null,
+          "summary": "Restamp to skills bundle 1.55.0+skills.1."
+        },
+        {
+          "class": "skill",
+          "path": "skills/contribution-intake/SKILL.md",
+          "surface_entry": null,
+          "summary": "Restamp to skills bundle 1.55.0+skills.1."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-build/SKILL.md",
+          "surface_entry": null,
+          "summary": "Restamp to skills bundle 1.55.0+skills.1."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-os-setup/SKILL.md",
+          "surface_entry": null,
+          "summary": "Restamp to skills bundle 1.55.0+skills.1."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-os/SKILL.md",
+          "surface_entry": null,
+          "summary": "Restamp to skills bundle 1.55.0+skills.1."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-polish/SKILL.md",
+          "surface_entry": null,
+          "summary": "Restamp to skills bundle 1.55.0+skills.1."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-qa/SKILL.md",
+          "surface_entry": null,
+          "summary": "Restamp to skills bundle 1.55.0+skills.1."
+        }
+      ],
+      "entry_sha256": "cdd823b095d9a05eb39d751c20396d25303dcc00dc1a2c12baeb15ac580e6819"
     }
   ]
 }

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.55.0",
   "package_exports": [
     "./commercial-journey",
     "./commercial-parity",
@@ -96,7 +96,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

@@ -1253,25 +1253,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
@@ -1737,7 +1751,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 |
@@ -1773,7 +1787,9 @@ 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.
 
@@ -1808,7 +1824,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 in a terminal status. 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; for a hosted deploy, 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.55.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.55.0`
 
 ## Forward compatibility