@nextcommerce/campaigns-os 1.37.1 → 1.37.2

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 Notable supported-surface changes are recorded here.
 
+## [1.37.2] - 2026-09-18
+
+### Fixed
+
+- Refresh the public starter catalog, per-family SDK verification and CampaignSpec
+  examples from template commit `11352c30`. The vendored SDK policy now records
+  released SDK 0.4.38, so freshness compares older certification against that
+  release instead of reporting SDK 0.4.37 as current.
+- Carry forward private families and local QA structure. Refresh Apollo Template
+  Reference provenance and upsell shipping-copy guidance from the same source.
+  Reconcile certified fixture and payment-chrome provenance with the catalog;
+  rendered pages, config files and payment asset hashes remain unchanged.
+- Preserve the toolkit's established pre-checkout select role and authored
+  forward routes when refreshing the known public examples. Narrow adapters
+  retain unrelated source updates and leave distinct future contracts unchanged.
+
+## [1.37.1+agent.1] - 2026-09-18
+
+### Changed
+
+- Document the page-kit change procedure after handoff: PM proposals are
+  reconciled against a known baseline and the current reviewed repository spec.
+  Conflicting authored edits require a recorded decision; generated and API-owned
+  fields retain their own authority. The worked example preserves a developer's
+  SDK upgrade and new page URL while accepting an authored upsell change.
+- Keep Map pin write-back explicit and store refresh with the authorized operator.
+  The procedure names the review and evidence requirements for the next build,
+  including fresh fingerprints after authored-only changes. It adds no automatic
+  synchronization, portal writes or spec prerequisite for static SDK upgrades.
+
 ## [1.37.1] - 2026-09-18
 
 ### Fixed

package/README.md

@@ -139,7 +139,15 @@ states (the SDK pin, page routes, analytics ids) into the local CampaignSpec,
 and with `--write-map` records the pin in the saved Map's Build hints too, so
 a bump in the repo is one edit followed by a derive rather than a hand edit
 in two tools; with `--from-store <subdomain>` and the store's Admin API read
-token in the environment it derives the store profile from the store as well. Everything after `start` is agent-driven: after `start`
+token in the environment it derives the store profile from the store as well.
+Map write-back stays explicit and pin-only.
+
+For changes after handoff, follow the
+[spec review procedure](docs/build-packet.md#changing-a-campaign-after-handoff):
+apply the PM's authored changes to the current repository spec, preserve derived
+fields, and resolve competing edits before the next build.
+
+Everything after `start` is agent-driven: after `start`
 and after every stage, run `next` and do what it prints — it names the skill
 and the exact commands for the next stage, already spelled `npx campaigns-os
 …` for this install, which is why `install-skills` comes first. The browser

package/contracts/campaign-cart-sdk-support-policy.v0.json

@@ -2,8 +2,8 @@
   "schema_version": "campaign-cart-sdk-support-policy/v0",
   "provenance": {
     "source": "NextCommerceCo/campaign-cart release tags",
-    "latest_known_release": "0.4.36",
-    "captured_at": "2026-08-18"
+    "latest_known_release": "0.4.38",
+    "captured_at": "2026-09-18"
   },
   "source": "contracts/campaign-cart-sdk-support-policy.v0.json",
   "minimum_supported": "0.4.20",

package/contracts/commerce-surface-catalog.json

@@ -166,13 +166,15 @@
         "items_json",
         "vouchers_json",
         "accept_text",
-        "decline_text"
+        "decline_text",
+        "retail_shipping",
+        "offer_shipping"
       ],
       "sourceOfTruth": [
         "CampaignSpec upsell/downsell pages",
         "Campaigns API package refs and vouchers/offers"
       ],
-      "agentRule": "Post-purchase upsells do not use shipping_methods. Package refs and vouchers must come from the upsell page contract."
+      "agentRule": "Post-purchase upsells do not use shipping_methods. Package refs and vouchers must come from the upsell page contract. `retail_shipping` and `offer_shipping` are display copy for the offer price block (the struck retail shipping line and the offer shipping line), not shipping method refs. The starter defaults claim `+$4.95 SHIPPING` and `+ FREE SHIPPING`; set both from the target campaign's real shipping figures whenever they differ."
     },
     "upsell_bundle_tiers": {
       "purpose": "Tiered post-purchase bundle upsell rows.",
@@ -493,9 +495,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.37",
-        "verified_at": "2026-08-21T15:26:00Z",
-        "evidence": "sdk-0.4.37-2026-08-21",
+        "sdk_version": "0.4.38",
+        "verified_at": "2026-09-15T16:51:10Z",
+        "evidence": "sdk-0.4.38-2026-09-15",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -505,8 +507,8 @@
       "templateReference": {
         "id": "template-reference-apollo",
         "family": "apollo",
-        "version": "sdk-0.4.37-2026-08-21",
-        "source_commit": "e9a2fc17beefe572b8ddc0c4f9b1b8e2f97f9a59",
+        "version": "sdk-0.4.38-revalidated-2026-09-03",
+        "source_commit": "84a63fe7af8cf49cd8cfdaaa66eb00ef6dd9bc4a",
         "provenance_url": "https://raw.githubusercontent.com/NextCommerceCo/campaign-cart-starter-templates/main/docs/template-references/apollo/README.md",
         "contract_path": "contracts/commerce-surface-catalog.json",
         "standard_viewport_refs": [
@@ -832,9 +834,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.37",
-        "verified_at": "2026-08-21T15:26:00Z",
-        "evidence": "sdk-0.4.37-2026-08-21",
+        "sdk_version": "0.4.38",
+        "verified_at": "2026-09-15T16:51:10Z",
+        "evidence": "sdk-0.4.38-2026-09-15",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -1038,9 +1040,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.37",
-        "verified_at": "2026-08-21T15:26:00Z",
-        "evidence": "sdk-0.4.37-2026-08-21",
+        "sdk_version": "0.4.38",
+        "verified_at": "2026-09-15T16:51:10Z",
+        "evidence": "sdk-0.4.38-2026-09-15",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -1235,9 +1237,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.37",
-        "verified_at": "2026-08-21T15:26:00Z",
-        "evidence": "sdk-0.4.37-2026-08-21",
+        "sdk_version": "0.4.38",
+        "verified_at": "2026-09-15T16:51:10Z",
+        "evidence": "sdk-0.4.38-2026-09-15",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -1469,9 +1471,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.37",
-        "verified_at": "2026-08-21T15:26:00Z",
-        "evidence": "sdk-0.4.37-2026-08-21",
+        "sdk_version": "0.4.38",
+        "verified_at": "2026-09-15T16:51:10Z",
+        "evidence": "sdk-0.4.38-2026-09-15",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -1802,9 +1804,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.37",
-        "verified_at": "2026-08-21T15:26:00Z",
-        "evidence": "sdk-0.4.37-2026-08-21",
+        "sdk_version": "0.4.38",
+        "verified_at": "2026-09-15T16:51:10Z",
+        "evidence": "sdk-0.4.38-2026-09-15",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -2052,9 +2054,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.37",
-        "verified_at": "2026-08-21T15:26:00Z",
-        "evidence": "sdk-0.4.37-2026-08-21",
+        "sdk_version": "0.4.38",
+        "verified_at": "2026-09-15T16:51:10Z",
+        "evidence": "sdk-0.4.38-2026-09-15",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -2236,9 +2238,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.37",
-        "verified_at": "2026-08-21T15:26:00Z",
-        "evidence": "sdk-0.4.37-2026-08-21",
+        "sdk_version": "0.4.38",
+        "verified_at": "2026-09-15T16:51:10Z",
+        "evidence": "sdk-0.4.38-2026-09-15",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -2448,5 +2450,5 @@
   },
   "_synced_from_repo": "NextCommerceCo/campaign-cart-starter-templates",
   "_synced_from_ref": "main",
-  "_synced_from_sha": "a7cc8beaf9d332c5d8e501d36fb9d4d7e3667468"
+  "_synced_from_sha": "11352c30c596db258679fd3a552b906086b11bb9"
 }

package/contracts/release-ledger.json

@@ -5207,6 +5207,72 @@
         }
       ],
       "entry_sha256": "76423be9a8624b8a3b398f4a4bfd47ff17b48f45d6a3bc44a22e122172684c6a"
+    },
+    {
+      "id": "RL-0127",
+      "sequence": 127,
+      "date": "2026-09-18",
+      "kind": "release",
+      "surface_version": null,
+      "changelog_section": "1.37.1+agent.1",
+      "changelog_sha256": "4eef81fac283eb699daff04ea5de96a4ad768099f8b9e0556f57e671435479ca",
+      "agent_impact": "For page-kit campaigns after handoff, reconcile PM proposals against their baseline and the current reviewed repository spec. Record authored conflicts and regenerate build evidence for the accepted revision. Map pin write-back remains explicit; static SDK upgrades do not gain a spec requirement.",
+      "compatibility": "compatible",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "named_surface",
+          "path": "docs/build-packet.md",
+          "surface_entry": "docs/build-packet.md",
+          "summary": "Document PM/developer ownership, authored reconciliation, reviewed build evidence and the boundary for future Git-backed portal saves."
+        }
+      ],
+      "entry_sha256": "7a643454252eff345d8015246440a037f69dab2041aee2f8fbafe1367caef087"
+    },
+    {
+      "id": "RL-0128",
+      "sequence": 128,
+      "date": "2026-09-18",
+      "kind": "release",
+      "surface_version": "1.37.2",
+      "changelog_section": "1.37.2",
+      "changelog_sha256": "96345150e314126c0b639cedebd4359085cb841af80cbf6e4ba0fb4554ce6d4c",
+      "agent_impact": "Use released SDK 0.4.38 for freshness comparisons. Public family verification, Apollo reference and upsell shipping-copy guidance now follow the pinned September 15 template source; older SDK evidence remains stale. Private overlays and rendered fixture bytes are preserved. Catalog refresh preserves the established select role and authored forward routes in exact known examples without overriding distinct future source contracts.",
+      "compatibility": "compatible",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "compatibility_policy",
+          "path": "contracts/supported-surface.json",
+          "surface_entry": "contracts/supported-surface.json",
+          "summary": "Advance the compatible package patch to 1.37.2."
+        },
+        {
+          "class": "package_export",
+          "path": "package.json",
+          "surface_entry": null,
+          "summary": "Ship refreshed template evidence, SDK release policy and controlled refresh adapters that preserve established example roles and routes as package 1.37.2."
+        },
+        {
+          "class": "generated_runtime",
+          "path": "package-lock.json",
+          "surface_entry": null,
+          "summary": "Keep the exact lockfile package identity at 1.37.2."
+        },
+        {
+          "class": "documentation",
+          "path": "docs/orientation-contract-reference.md",
+          "surface_entry": "docs/orientation-contract-reference.md",
+          "summary": "Regenerate the orientation reference for surface version 1.37.2."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/runtime-readiness.md",
+          "surface_entry": "docs/runtime-readiness.md",
+          "summary": "Regenerate the runtime reference for package version 1.37.2."
+        }
+      ],
+      "entry_sha256": "174e0bac2ba34b94fbb7b30257d0baf4e417440cdbcfdc5685b9f48fa565ce26"
     }
   ]
 }

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 \u2014 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 \u2014 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) \u2014 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.37.1",
+  "surface_version": "1.37.2",
   "package_exports": [
     "./commercial-journey",
     "./commercial-parity",

package/contracts/template-brand-contract.shared-commerce.v0.json

@@ -55,7 +55,7 @@
       },
       "asset_pin": {
         "repo": "NextCommerceCo/campaign-cart-starter-templates",
-        "sha": "a7cc8beaf9d332c5d8e501d36fb9d4d7e3667468",
+        "sha": "11352c30c596db258679fd3a552b906086b11bb9",
         "path": "src/<family>/assets/<asset>",
         "note": "asset_sha256 is the sha256 of each shipped starter asset at this commit (the commerce-surface-catalog _synced_from_sha pin; the bytes are identical across every family). A served asset whose bytes hash to the shipped value is the untouched starter asset and counts as residue even though its markup names no method; different bytes mean it was edited in place. check-template-doctrine verifies these hashes against the pinned checkout."
       },

package/docs/build-packet.md

@@ -220,6 +220,113 @@ action. A configured campaign whose pin is newer than the spec's is the
 advisory case above: no required action, and sync never moves that pin
 backwards; `spec derive` is the command that closes it from the spec side.
 
+### Changing a campaign after handoff
+
+For page-kit campaigns, the reviewed repository spec determines the next build.
+New handoffs use `.campaigns-os/campaign.spec.json`; existing packets keep their
+`spec.local_path` until a separate, reviewed migration. Static campaigns do not
+need a spec or packet for an SDK upgrade. This procedure implements the operating
+agreement in [#432](https://github.com/NextCommerceCo/campaigns-os/issues/432)
+and [#447](https://github.com/NextCommerceCo/campaigns-os/issues/447). It is a
+review procedure, not an automatic Map import or a portal editing lock.
+
+A PM can keep using Map Builder to propose a change. Saving the Map does not
+change the campaign repository or approve that change for the next build.
+
+| Responsibility | Owner |
+|---|---|
+| Propose offers, copy, page sequence and other authored intent; confirm the intended result | Campaign PM or named campaign owner |
+| Compare the proposal with the current repository, prepare the spec/code change and run checks | Developer, assisted by an agent where useful |
+| Resolve competing edits to the same authored field | PM confirms intent; developer checks the resulting implementation |
+| Review and merge the repository change | The campaign's existing authorized reviewer, under its normal PR rules |
+| Refresh store-derived data requiring an Admin token | Authorized operator or PM; never a routine developer SDK-bump prerequisite |
+
+Record the actual PM and developer/reviewer in the campaign change request. An
+agent can prepare a diff and evidence, but cannot supply a missing human decision.
+This procedure does not grant new merge, store-write or deployment authority.
+
+#### Propose and reconcile a change
+
+1. **Identify the starting revision.** Record the campaign repo, Git commit and
+   packet's spec path that the PM reviewed. Keep that spec as the baseline. A Map
+   ID identifies lineage, not the revision: also retain the proposed Map export
+   and its save/hash evidence. Do not overwrite the repository spec with it.
+2. **Compare three versions.** Compare the baseline with the PM's proposal, then
+   with the current repository spec. Match pages and packages by their stable
+   identifiers, not array position. Explain additions, removals and routing
+   changes as well as changed values. The
+   [field-class contract](https://github.com/NextCommerceCo/campaigns-os/issues/432#issuecomment-5707550439)
+   identifies what a PM can author and what the repo, API or editor owns.
+3. **Apply the intended change to the current spec on a branch.** Transfer only
+   the PM's authored changes. Keep current repo-derived SDK pins, page URLs and
+   analytics IDs; preserve API/store records and editor metadata under their own
+   authority. An offer selection may change, but a proposed price does not
+   rewrite an API-owned price: route that commercial setup change to its owner
+   and obtain refreshed readback before building it.
+4. **Resolve conflicts before accepting the change.** If PM and developer changed
+   the same authored field differently, neither value wins automatically. Record
+   the chosen value and PM confirmation in the PR. If the baseline is missing,
+   pause the import: ask the PM to restate the change against the current spec.
+   Do not infer intent from every difference in a stale export. If the repository
+   advances during review, repeat the comparison against the new revision.
+5. **Refresh and validate the result.** Preview `spec derive --dry-run`, inspect
+   every refused or unresolved field, then apply the accepted derivation. Plain
+   derive is local; it does not merge authored intent. Follow the packet's normal
+   `page-kit sync`, build, doctor and relevant QA steps. Resolve stale routing
+   hints and rebuild affected pages. A successful derive exit alone is not build
+   or QA approval. After an authored-only edit, derive may return `unchanged`
+   and leave the Assembly Report's spec hash at the previous build. Record fresh
+   build evidence and verify its spec fingerprint before accepting it. A changed
+   spec must not reuse evidence for the older build.
+6. **Review the intended result and record the revision.** The PM confirms the
+   commercial change and the developer supplies the checked diff and preview
+   evidence. Record the reviewed spec's exact-byte SHA-256, the tested repository
+   revision, and the doctor/QA evidence in the PR. Build or deploy from that
+   reviewed revision under the campaign's existing rules; rerun affected checks
+   if the spec or code changes afterwards. Tell the PM which proposal was accepted
+   and identify any remaining Map differences, so the saved Map is not mistaken
+   for a synchronized copy.
+
+A change request needs only: baseline commit/spec path, the proposal or requested
+field changes, current repository revision, conflict decisions, named reviewers,
+and the final spec hash with build/QA evidence. Use existing PRs and campaign
+records for this; there is no additional sidecar schema or new CLI command.
+
+#### Example: the PM changes an upsell while the developer upgrades the SDK
+
+The PM starts from reviewed revision A and replaces the first upsell's selected
+package with package B, already present in the campaign API. Meanwhile the
+repository reaches revision R with a newer SDK pin and a changed page permalink.
+The PM's export still contains A's SDK pin and generated page URL.
+
+| Value | PM proposal | Current repo R | Reviewed result |
+|---|---|---|---|
+| Selected upsell package (authored) | B | Original package | B, after PM confirmation |
+| SDK pin (repo-derived) | Old pin from A | Newer pin | Newer pin |
+| Page URL (repo-derived) | Old URL from A | New permalink | URL derived from the new permalink |
+| Package price (API-owned) | Copied API value | Current API value | Current API value; selection does not change the price |
+
+Start from R, change the selected package, and derive the repo-owned fields. Review
+routing references and rebuild the affected upsell page. If the developer also
+changed the selected package to C, record a conflict and obtain a choice before
+merging. Do not apply B merely because the Map was saved later.
+
+#### Map write-back and future portal saves
+
+`spec derive --write-map` remains an explicit, pin-only action. A developer or
+operator may request it when updating the Map's SDK hint is part of their task;
+it is not a default SDK-bump or reconciliation step. It retains the existing
+hash precondition and refusal to overwrite a newer Map pin. It does not mark a
+PM proposal accepted or synchronize offers, routes or other authored content.
+Store refresh through `--from-store` remains a separate authorized operator step.
+
+A future Git-backed portal save can replace the manual transfer only when it
+identifies the repository/spec and base revision, shows the authored diff,
+preserves each field's authority, detects concurrent changes, and submits the
+change through the same review process. It must show whether a change is merely
+proposed, reviewed or used by a build. That is separate portal work; this
+agreement does not enable portal writes.
+
 ### Deriving the spec from the repo (`spec derive`)
 
 Every CampaignSpec field has a class: **authored** (a human writes it: offers,

package/docs/orientation-contract-reference.md

@@ -25,7 +25,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.37.1`
+Supported surface at generation time: `1.37.2`
 
 ## Forward compatibility
 

package/docs/runtime-readiness.md

@@ -8,7 +8,7 @@
 
 How a checkout of this repository at one commit becomes a usable installed runtime, and how a consumer decides whether a prepared one is still trustworthy. Everything below is generated from `contracts/runtime-recipe.campaigns-os-node-v1.json`, which is the only authority for these values.
 
-Recipe kind `campaigns-os-node-v1`, revision `1.0.2`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.37.1`.
+Recipe kind `campaigns-os-node-v1`, revision `1.0.2`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.37.2`.
 
 ## What this is
 

package/package.json

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