@nextcommerce/campaigns-os 1.43.2 → 1.47.0

package/docs/orientation-contract-reference.md

@@ -9,6 +9,7 @@
     contracts/orientation-reason-codes.v1.json
     contracts/orientation-limits.v1.json
     contracts/supported-surface.json
+    contracts/release-ledger.json (baseline_floor only)
     contracts/fixtures/orientation/canonicalization/v1.json
   Regenerate: node ./scripts/generate-orientation-reference.mjs --write
   CI runs the same script with --check, so a stale copy of this file fails the build.
@@ -25,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.43.2`
+Supported surface at generation time: `1.47.0`
 
 ## Forward compatibility
 
@@ -60,6 +61,43 @@ position, so a consumer reading history in array order reads it in `sequence` or
 its number to `sequence`; the two diverge legitimately, because when concurrent pull requests
 land the later one restamps its `sequence` to follow the earlier while keeping the id it was
 written with. Order by `sequence`, identify by `id`, and do not infer one from the other.
+After a baseline rotation the file starts at `baseline_floor.last_archived_sequence + 1`, not at 1;
+entries are never renumbered, so position plus that offset is still the sequence.
+
+## Baseline rotation
+
+The ledger and the changelog are bounded as whole files, so they are rotated rather than allowed to
+outgrow the limits. A rotation moves every entry up to a reviewed cut, and the changelog from the first section
+those entries link to the end of the file (unlinked sections in that range included), byte-for-byte and in order
+into a dated archive pair under `contracts/archive/`, and declares the cut as
+`baseline_floor` in `contracts/release-ledger.json`. Archived entries keep their `sequence`, `entry_sha256` and
+`changelog_sha256`; each section hash verifies against the archive changelog. The floor names the archive
+files with their SHA-256, the last archived entry and its sequence, the first kept entry, the live entry that
+recorded the rotation, and the reason code to refuse with. The floor only moves forward, only with a new
+rotation entry, and an archive file never changes once merged; the next rotation writes a new dated pair.
+
+Rotation changes no mandatory read. The reading order in `AGENTS.md` is unchanged, and `source_bytes` measures
+exactly its data files (steps 1 to 8):
+
+- `contracts/supported-surface.json`
+- `contracts/release-ledger.json`
+- `CHANGELOG.md`
+- `contracts/orientation-limits.v1.json`
+- `contracts/orientation-reason-codes.v1.json`
+- `schemas/campaigns-os-tooling-orientation.v1.schema.json`
+- `schemas/campaigns-os-release-ledger.v1.schema.json`
+- `contracts/agent-relevant-change-policy.v1.json`
+
+The archive files are not among them: they are optional history reads and count against no limit, and their
+sections and entries are not in `section_count` or `ledger_entries`.
+
+Current floor: last archived entry `RL-0124` (sequence 124), first kept entry
+`RL-0125`, recorded by `RL-0190`. Archives, oldest rotation first:
+
+- [`contracts/archive/release-ledger.2026-09-30.json`](../contracts/archive/release-ledger.2026-09-30.json) and [`contracts/archive/CHANGELOG.2026-09-30.md`](../contracts/archive/CHANGELOG.2026-09-30.md)
+
+A consumer whose reviewed baseline's newest ledger entry is older than `RL-0124` refuses with
+`baseline_below_floor`. Adopt a newer reviewed baseline whose ledger reaches the floor's last_archived_id; every commit at or after the floor's first_kept_id qualifies. Do not orient on the partial live window, and do not stitch the archive in as a substitute: the archive holds the history for reference, not for this read.
 
 ## Release-ledger digest canonicalization
 
@@ -120,6 +158,7 @@ consumer's parser tests.
 |---|---|---|---|---|---|
 | `ahead_of_upstream` | `refused` | campaigns-agent | `TP-D4-ahead-of-upstream` | The checkout carries commits the upstream default branch does not, so its contracts are not a published generation. | Push or drop the local commits, or run against a managed generation at the published OID. |
 | `already_current` | `current` | campaigns-agent | `TP-B3-already-current` | The verified target equals the active generation; nothing changed and no restart is required. | None. |
+| `baseline_below_floor` | `refused` | campaigns-os | `A1-baseline-below-floor` | The target ledger declares a baseline_floor, and the reviewed baseline's newest ledger entry is older than the floor's last archived entry. Part of the baseline-to-target window was rotated into the archive files the floor names, which are not mandatory orientation reads, so the window cannot be read from the live ledger and changelog. | Adopt a newer reviewed baseline whose ledger reaches the floor's last_archived_id; every commit at or after the floor's first_kept_id qualifies. Do not orient on the partial live window, and do not stitch the archive in as a substitute: the archive holds the history for reference, not for this read. |
 | `checkout_acquisition_failed` | `refused` | campaigns-agent | `TP-D1-acquisition-failed` | Managed acquisition did not complete: interrupted clone, remote validation failure, or a broken linked-worktree backpointer. Partial state is quarantined, never exposed as ready. | Rerun acquisition. If it fails repeatedly, inspect the quarantined partial named in the diagnostic and confirm remote reachability. |
 | `checkout_already_exists` | `refused` | campaigns-agent | `TP-D1-checkout-already-exists` | The managed root reserved for acquisition appeared concurrently and is not an empty reservation this run owns. | Rerun so the existing root is validated as a managed store, or remove the unexpected directory after confirming it holds no needed state. |
 | `checkout_missing` | `refused` | campaigns-agent | `TP-D1-checkout-missing` | No checkout exists at the configured location and the mode does not authorize acquiring one. | Supply the operator checkout at the configured path, or switch to managed mode so a generation can be acquired. |
@@ -205,7 +244,7 @@ nowhere in the schemas, or in the schemas and not here, is a generation failure.
 | `$defs.baseline.properties.kind` | `legacy_commit`, `supported_surface` |
 | `$defs.change_class` | `schema`, `hashed_surface`, `named_surface`, `cli_surface`, `skill`, `package_export`, `compatibility_policy`, `documentation`, `workflow`, `generated_runtime` |
 | `$defs.disposition` | `current`, `orientation_available`, `updated`, `restart_required`, `recovered_interrupted_update`, `legacy_baseline`, `freshness_unknown`, `refused` |
-| `$defs.reason_code` | `already_current`, `ahead_of_upstream`, `checkout_acquisition_failed`, `checkout_already_exists`, `checkout_missing`, `checkout_mutation_not_authorized`, `detached_head`, `dirty_checkout`, `diverged_history`, `evidence_budget_exceeded`, `fetch_failed`, `git_environment_unsafe`, `history_incomplete`, `missing_upstream`, `orientation_contract_missing`, `orientation_in_progress`, `orientation_incomplete`, `orientation_rendered`, `orientation_too_large`, `pointer_race`, `runtime_commit_mismatch`, `runtime_refresh_failed`, `runtime_refresh_required`, `surface_incompatible`, `transaction_incomplete`, `transaction_reconciled`, `wrong_remote` |
+| `$defs.reason_code` | `already_current`, `ahead_of_upstream`, `baseline_below_floor`, `checkout_acquisition_failed`, `checkout_already_exists`, `checkout_missing`, `checkout_mutation_not_authorized`, `detached_head`, `dirty_checkout`, `diverged_history`, `evidence_budget_exceeded`, `fetch_failed`, `git_environment_unsafe`, `history_incomplete`, `missing_upstream`, `orientation_contract_missing`, `orientation_in_progress`, `orientation_incomplete`, `orientation_rendered`, `orientation_too_large`, `pointer_race`, `runtime_commit_mismatch`, `runtime_refresh_failed`, `runtime_refresh_required`, `surface_incompatible`, `transaction_incomplete`, `transaction_reconciled`, `wrong_remote` |
 
 ### `schemas/campaigns-os-release-ledger.v1.schema.json`
 
@@ -225,6 +264,7 @@ so a renamed command fails here as well as at the supported-surface gate.
 - `campaigns-os prepare-build`
 - `campaigns-os build`
 - `campaigns-os polish`
+- `campaigns-os record`
 - `campaigns-os checkpoint`
 - `campaigns-os page-kit`
 - `campaigns-os spec`

package/docs/polish-evidence.md

@@ -21,6 +21,11 @@ Three layers must all be satisfied:
    `campaigns-os polish capture` from the current packet, report, served build,
    mapped routes, and fixed desktop/mobile viewports.
 
+Record all three with `campaigns-os record polish` (§7) rather than editing
+the report by hand: it stamps the stage-record fields from doctor's current
+state, keeps the captured `page_load`, and writes nothing unless this gate would
+pass on the result.
+
 ## 1. Stage-record requirements
 
 The gate only applies once assembly is complete
@@ -500,3 +505,72 @@ current value.
 Polish evidence certifies the polish pass only — it is not QA and does not
 certify launch readiness (`docs/qa-and-test-orders.md` owns the QA proof
 stack).
+
+## 7. Recording with `record polish`
+
+```bash
+campaigns-os record polish --packet <campaign-runtime.build.json> --evidence <polish-evidence.json> [--report <json>] [--dry-run] [--json]
+```
+
+Run it after `campaigns-os polish capture`, against the build `campaigns-os
+record build` recorded. The `--evidence` file is a JSON object with these keys;
+any other key is refused:
+
+| Key | Required | Written to |
+|---|---|---|
+| `status` | no (default `completed`) | `stages.polish.status`; `completed`, `completed_with_warnings`, `blocked` or `skipped` |
+| `evidence` | for `completed*` | `stages.polish.evidence`, the seven categories of §2. Leave out `visual_review.page_load`: the value `polish capture` recorded is kept, and a file that carries one is refused. Without it, a `blocked` or `skipped` record keeps the evidence already on the report. |
+| `blockers` | for `blocked` only | `stages.polish.blockers`: a non-empty array of `{"code", "message"}` objects. |
+| `skip_reason` | for `skipped` only | `stages.polish.skip_reason`: a non-empty string. |
+| `repair_loop_defect` | no | `report.theme.repair_loop_defect`: `null`, or the first brand-layer repair-loop defect as an object (`code`, `message`, `path`, `detail`). A non-null defect needs a recorded `report.theme`. |
+
+The command itself stamps `performed_by: "next-campaigns-polish"`,
+`source_build_fingerprint` (doctor's `derived.build_output_fingerprint.value`,
+which must equal the recorded `stages.assembly.build_fingerprint`),
+`source_package_material_fingerprint` when the report fingerprints a Design
+Source Package, and `completed_at` (not for `blocked`). It then validates the
+report it would write against
+`schemas/campaign-runtime-assembly-report.v0.schema.json` and doctor's report
+checks and, for a `completed*` status, evaluates this gate and the hidden
+eager-media checkpoint over it exactly as doctor does. A `blocked` or `skipped`
+record keeps this gate blocked, so `next` stays at Polish and QA stays blocked. Any failure is printed by field or gate code
+(for example `repair_loop_defect must be null or an object ... (got string)`, or
+`polish.evidence_incomplete` with its per-field problems), the command exits
+non-zero, and nothing is written. `--dry-run` runs every check and writes
+nothing. Like `record setup` and `record build`, it refuses a report that is not
+bound to the packet (`docs/build-packet.md`, "Recording stage completion") and
+output that changes while it records.
+
+A complete file:
+
+```json
+{
+  "status": "completed",
+  "evidence": {
+    "visual_review": {
+      "screenshots": ["qa-output/polish/landing-desktop.png", "qa-output/polish/landing-mobile.png"]
+    },
+    "brand_review": {
+      "logo_checked": true,
+      "favicon": { "status": "confirmed_non_template" },
+      "colors": ["#1f4d3a"],
+      "brand_bleed": { "cleared": true }
+    },
+    "checkout_review": {
+      "field_labels": "initial field labels and placeholders are legible on desktop and mobile",
+      "phone_alignment": "checked",
+      "payment_display": "checked",
+      "bump_compare_price_rule": "no equal or no-discount compare price renders"
+    },
+    "template_residue_review": {
+      "next_blue": "not found",
+      "starter_favicon": { "status": "confirmed_non_template" },
+      "lorem": "not found"
+    },
+    "commerce_flow_review": "direct-entry package selection reviewed",
+    "issues": [],
+    "commands": ["next-campaigns-polish", "campaigns-os polish capture"]
+  },
+  "repair_loop_defect": null
+}
+```

package/docs/qa-and-test-orders.md

@@ -246,12 +246,18 @@ before QA with the relevant gate ID:
 ```bash
 campaigns-os checkpoint waive \
   --packet campaign-runtime.build.json \
-  --gate <page_kit.store_profile|page_kit.sdk_version|polish.hidden_eager_media|built_output.upsell_selector_scope> \
+  --gate <page_kit.store_profile|page_kit.sdk_version|polish.hidden_eager_media|built_output.upsell_selector_scope|source_html.producer_provenance> \
+  [--page <page_id>] \
   --reason "<why>" \
   --waived-by "<named human>" \
   --review-condition "<specific re-evaluation trigger>"
 ```
 
+`--page` is required for `source_html.producer_provenance`, which is waived one
+Figma-typed page at a time (see the
+[Design Source Package](./design-source-package.md) hand-written HTML route),
+and refused for the other gates.
+
 Legacy source/theme/QA waiver commands and artifact lanes remain in place until
 those gates are registered. Store Profile evidence includes only the governed
 nine-field matrix plus status, normalized slug, relative target path,
@@ -432,7 +438,8 @@ work that lands with the receiver's connection contract. This section
 documents the semantics of the stamps the receiver already applies.
 
 Add `--browser --test-order common` for the normal proof pass: first-party
-Playwright browser checks plus the default typed-card order sample. If the
+Playwright browser checks plus the default `common` typed-card orders
+(described under "Test Orders" below). If the
 browser binary is missing, the CLI will prompt you to run
 `npm run qa:install-browser`:
 
@@ -452,6 +459,30 @@ machine-checkable `agentContract.qaStructure` selectors in the commerce surface
 catalog. If the family contract is silent, the assertion returns
 `manual_review`, not `pass`; if declared required structure is missing, it
 soft-fails with warning severity so the verdict becomes `ready_with_exceptions`.
+The checkout wrapper and page composition are source-owned, so QA checks what
+the checkout does rather than family class names. Family shell is a fixed list:
+`.checkout-wrapper`, `.checkout-layout__left`, `.checkout-layout__right`,
+`.checkout__layout`, `.checkout__column--left`, `.checkout__column--right` and
+the family include's `[data-next-component="shipping-field-row"]` marker. When
+family shell is all that is missing, the row is `warn` if the checkout also
+passes three behaviour checks: a `<form data-next-checkout="form">` exists;
+`email`, `fname`, `lname`, `country`, `address1`, `city`, `province` and
+`postal` are each an input, select or textarea carrying that
+`data-next-checkout-field` inside the form, not a `type="hidden"` input or a
+disabled control (visibility is not required, so a field hidden until a country
+is chosen still counts); and a cart-summary total
+(`[data-next-display="cart.total"]` or
+`[data-next-cart-summary] .order-totals__value--total`) is visible with text.
+If any behaviour check fails, or no checkout form is found, the row stays
+`fail`. Any other missing selector is always `fail`: the SDK selectors
+(`[data-next-checkout="form"]`, `[os-checkout-payment]`,
+`[data-next-cart-summary]`, `[data-next-bundle-slots-for]`) and any class the
+list does not name, such as a hosted payment field class. `evidence.behaviour` records
+the three checks and each `evidence.checks[]` entry carries `kind`
+(`family_shell` or `sdk_wiring`).
+The upsell and checkout bundle price checks count the SDK's
+`[data-next-bundle-display*='price']` alongside the contract's price rows; a
+hidden, zero-size or empty bundle-display node does not count.
 Promoted template families must also have
 `contracts/template-brand-contract.<family>.v0.json`; QA emits a blocker if the
 selected family is missing its brand/residue/pricing contract instead of
@@ -973,6 +1004,22 @@ the baseline, and when no candidate page is captured the leg emits
 `no_in_scope_page_captured` (skipped) or `no_capture_page_answered`
 (`FAIL`/`BLOCKER`).
 
+The automatic candidate is never a receipt page: the campaign root is not one,
+and a built entry counts as one only when its topology `page_type` is `receipt`
+or `thankyou`. The leg does not substitute the topology's receipt step, because
+a receipt loaded without an order fires no Purchase. So when the automatic
+candidate is not a receipt and fires no Purchase, `purchase-present` is
+`MANUAL_REVIEW`/`WARN` instead of a blocker, and its `evidence.page_mismatch`
+names the mismatch: `reason` (`receipt_baseline_non_receipt_candidate` when the
+baseline fired a Purchase, else `candidate_not_receipt`),
+`baseline_fired_purchase`, `candidate_receipt: false`, `candidate_source`
+(`campaign_root` or `built_entry`) and `candidate_page_type`. To compare
+Purchase, pass the candidate receipt with `--analytics-candidate`. An explicit
+candidate, or an automatic one whose page type is a receipt, still blocks on a
+missing Purchase, and a non-receipt candidate that does fire a Purchase gets the
+full set of Purchase checks, with its page recorded in `evidence.candidate_page`
+on `purchase-present`.
+
 | Flag | Meaning |
 |---|---|
 | `--analytics-baseline <url>` | Legacy funnel URL to capture as the parity baseline (enables the leg) |
@@ -988,7 +1035,9 @@ Point both at the **thank-you / receipt page** for the highest-value `dl_purchas
 check, or drive the same offer through each funnel so client-fired values line up.
 
 What the diff asserts (BLOCKER unless noted):
-- `purchase-present` — candidate fires a purchase event.
+- `purchase-present` — candidate fires a purchase event (`MANUAL_REVIEW`
+  naming the page mismatch when the automatic candidate is not a receipt and
+  fires none; see above).
 - `purchase-value` / `purchase-currency` — match the baseline's **client-fired**
   value (compared client-vs-client; never vs a backend total, since tax is
   computed backend and is not in the client value on headless checkouts).
@@ -1107,13 +1156,64 @@ npm run campaigns-os -- qa run \
   --test-order common
 ```
 
-The default mode is **`common`** (also what bare `--test-order` runs): at most
-four shapes from the selected checkout's declared topology — the checkout
-baseline, first-offer `accept` and `decline` when `expected_next_url` reaches an
-upsell/downsell, and the shortest declared path that actually reaches a
-receipt/thank-you page. The receipt path is deduplicated when it is already
-`accept` or `decline`; Campaigns OS never invents a receipt path from offer
-count alone. This is the everyday QA sample.
+The default mode is **`common`** (also what bare `--test-order` runs). It
+starts from the selected checkout's declared topology:
+
+- When every actual terminal path (the `full` set, checkout baseline included)
+  fits under the flood cap (`--max-test-orders`, default `6`), `common` runs
+  them all. The run says so on stderr, and on a funnel with offer pages the
+  coverage row below records
+  `order_path_depth_effective: "full"` with `order_path_depth_reason:
+  "under_cap"`.
+- Above the cap, or when the topology cannot be walked exhaustively, `common`
+  runs the sample: the checkout baseline, first-offer `accept` and `decline`
+  when `expected_next_url` reaches an upsell/downsell, and the shortest
+  declared path that actually reaches a receipt/thank-you page (deduplicated
+  when it is already `accept` or `decline`; Campaigns OS never invents a
+  receipt path from offer count alone). It then adds, for each offer or
+  downsell page whose decline no planned path clicks yet, the shortest actual
+  terminal path that clicks it, until the plan reaches the cap. Pages still
+  left out are named on stderr and in the coverage row. The sample itself is
+  never trimmed, so a `--max-test-orders` below it is refused before launch as
+  before.
+
+A page counts as covered only when a path clicks its **decline** control.
+Reaching a page, or clicking only its accept, does not count: a broken decline
+link strands the shopper even when accept works.
+
+Every browser test-order run whose funnels include offer pages records
+`browser-test-order:upsell-action-coverage`, read from the clicks the runner
+actually made in orders it placed, not from the plan. It lists the offer pages
+of every funnel in the run, including funnels the orders do not drive, and a
+click credits only the funnel whose order made it, never another funnel's page
+at the same URL. The row is conservative: it is `pass` or `warn` only when
+coverage is certain, and `manual_review` in every other case.
+
+Coverage is certain when all of these hold: at least one order was placed;
+every funnel lists its pages; every page is either a known non-offer type
+(checkout, landing, thank-you and the like) or an upsell/downsell page with its
+own absolute http(s) URL that no other page shares; every planned order belongs
+to exactly one funnel (its checkout is that funnel's checkout and it was
+planned over that funnel's page list); and every click an order recorded lands
+on a declared offer page of that order's own funnel. Then the row is `warn`
+(severity `warn`) naming each page whose decline no order of its funnel
+clicked, and each funnel no order ran through, or `pass` when every page's
+decline was clicked.
+
+Otherwise the row is `manual_review` (severity `warn`) naming the pages not
+proved clicked through, with `evidence.reason`: `test_orders_off` for a
+`--test-order off` run, `no_order_recorded` when no order was placed (an
+attempt that failed before an order reference counts as none), `no_topology`
+when no funnel topology reached the check, or `not_assessable` for the rest.
+`evidence.not_assessable[]` names each page that cannot be matched to a click,
+with a reason: `no_url` or `unresolvable_url`, `shared_url` (the URL belongs to
+another page too), `unknown_page_type` (neither an offer type nor a known
+non-offer type), or `no_pages` (a funnel with no page list).
+`evidence.uncertainty[]` lists the run-level reasons: `unattributed_plan` (a
+plan that does not match exactly one funnel's checkout and page list),
+`unattributed_click` (a click with no usable URL, or from such a plan's order)
+and `undeclared_click` (an order clicked a page its funnel does not declare).
+`evidence.pages[]` gives `accept_clicked` / `decline_clicked` per page.
 
 Other modes: `checkout` (base order redirect only), `accept`/`decline` (click the
 rendered control on the first upsell page), `both` (two fresh orders for those
@@ -1547,8 +1647,11 @@ npm run campaigns-os -- qa run \
 ```
 
 `--max-test-orders` (default `6`) is an **accidental-flood guard, not a permission
-gate**. A single checkout's `common` sample always stays under it, though tier
-expansion can exceed it. If `full` expands past the cap, the command stops before
+gate**. A single checkout's `common` plan always keeps its checkout,
+first-offer accept/decline and shortest-receipt sample. If that sample alone
+exceeds the cap (a `--max-test-orders` below it), the run is refused before
+browser launch, as before. Otherwise the added decline paths stop at the cap.
+Tier expansion can exceed it. If `full` expands past the cap, the command stops before
 browser launch, prints the planned count, lists the planned paths (up to 40 ids;
 past that the remainder is counted, never cut silently, and `--select-package
 <ref[:qty]>` lists one tier's paths), and names the exact `--max-test-orders <count>` raise. For example, a linear three-offer graph has
@@ -1729,8 +1832,9 @@ use the declared topology instead of a single happy path:
 
 1. Checkout-only with the base cart.
 2. Checkout-only with the base cart plus bump when the bump is in scope.
-3. Base cart through the checkout/first-action sample plus the shortest real
-   receipt path (`--test-order common` covers up to four deduplicated shapes).
+3. Base cart through `--test-order common`: every actual terminal path when
+   they fit under the cap, otherwise the checkout/first-action sample, the
+   shortest real receipt path and one decline path per uncovered offer page.
 4. Base plus bump cart through the same sample matrix when bump behavior is
    launch-relevant.
 5. Use `full` when you want every actual terminal path, raising the flood cap to

package/docs/release-ledger-authoring-guide.md

@@ -146,7 +146,7 @@ incomplete, append a correction:
   "amends": "RL-0007",
   "amendment_reason": "RL-0007 was recorded as compatible; it removed a documented guarantee.",
   "surface_version": null,
-  "changelog_section": "1.15.0+agent.1",
+  "changelog_section": "1.16.0+agent.1",
   "compatibility": "breaking",
   "migration": "Stop relying on the removed guarantee; see docs/build-packet.md.",
   "agent_impact": "Treat the 1.15.0 packet doc change as breaking, not compatible.",
@@ -154,6 +154,10 @@ incomplete, append a correction:
 }
 ```
 
+The amendment corrects a 1.15.0 entry, but its own section is a new one at the
+very top of `CHANGELOG.md`, numbered on the release on top when it is written
+(`1.16.0` here). It is never inserted under the older release it corrects.
+
 An amendment is the only entry kind whose change items may map to no changed
 path in its own range, because it corrects meaning rather than moving bytes.
 
@@ -171,13 +175,25 @@ entry currently holding the link, may re-link a section; any other second link
 still fails the one-to-one rule. Say in `amendment_reason` what changed in the
 section and why.
 
+This works only for a section still in the live `CHANGELOG.md`. An archived
+section cannot be corrected in place: archive files are never edited, and each
+is pinned by its SHA-256 in `baseline_floor.archives`, so any change to one
+fails the gate. Correct archived history with a new live amendment entry that
+links its own new section at the top of `CHANGELOG.md`, and say in
+`amendment_reason` what is wrong in the archived section.
+
 `scripts/check-changelog-structure.mjs` (part of `npm run check`) refuses the
 marker lines outright, in `CHANGELOG.md` and under `docs/`, and also holds the
 section layout: identifiers unique, `+agent.N` sections in one run directly
 above their release with N descending (newest first), and every ledger
-`changelog_section` naming a section that exists. Insert a new `+agent.N`
-section at the top of its release's run, not directly above the release
-heading.
+`changelog_section` naming a section that exists.
+
+A new section always goes at the very top of `CHANGELOG.md`: either a new
+release, or a `+agent.N` section numbered on the current top release (one above
+its highest N, or `+agent.1` if it has none). Never add a `+agent.N` section
+under an older release. Given `--base`, both `check-changelog-structure.mjs` and
+the release-ledger gate refuse any new section that sits below a section base
+already had.
 
 ## Running the gate
 
@@ -274,3 +290,47 @@ a quiet raise.
 
 Raising a limit is a reviewed policy change: advance `limits_version`, and the
 change owes its own ledger entry like anything else.
+
+## Rotating the baseline
+
+When the live ledger and changelog approach a bound, rotate them at a reviewed
+cut instead of raising a limit. The first rotation (2026-09-30, `RL-0190`)
+moved `RL-0001` through `RL-0124`; the ledger's `baseline_floor` records it.
+
+1. Pick the cut: the last entry to archive. Everything up to it moves, and so
+   does the changelog from the first section those entries link down to the end
+   of the file, including sections no entry links. If a kept entry amends an
+   archived one, or links a section in that tail, move the cut earlier until the
+   pair is on one side. Never later.
+2. Run the rotation through `rotateLedger` in `scripts/orientation-contract.mjs`
+   with a new dated pair under `contracts/archive/`, e.g.
+   `release-ledger.<date>.json` and `CHANGELOG.<date>.md`. It writes the entries
+   byte-for-byte (original `sequence` and hashes kept) and the changelog tail
+   verbatim, appends the pair and its SHA-256 to `baseline_floor.archives`, and
+   moves `last_archived_id`, `last_archived_sequence` and `first_kept_id`. It
+   refuses a cut that splits a pair.
+3. Never edit an existing archive file, and never reuse a date: each rotation
+   adds a new pair. Add both new files to `named` in
+   `contracts/supported-surface.json`.
+4. Record the rotation as its own entry, named in `baseline_floor.rotation_entry`,
+   with a change item for each new archive file and a CHANGELOG section of its
+   own. Its `agent_impact` tells consumers which baseline is now too old.
+
+The gate accepts a base entry missing from the live ledger only when the head
+floor covers it, the new archive holds it canonical-JSON-identical, and the floor
+moved with a new rotation entry in the same range. Any other deletion, an
+archive copy that differs from base, a floor that moves without a rotation
+entry, a floor that moves back or is rewritten, an edited archive file, and a
+cut that archives an entry while an entry that was live at base stays live and
+amends it (the same refusal `rotateLedger` gives) all fail. A new entry added
+after the rotation may still amend an archived entry, linking its own section
+in the live changelog: that is how archived history is corrected. The live changelog and each archive changelog must each be well-formed on
+their own, a section id may appear in only one of them, a section present
+at base must still be in one of them, and the live changelog followed by the
+archives, newest rotation first, must read as the base's sections in order
+with new sections only at the top of the live file. So every live section is
+newer than every archived one, and an archived section never moves back
+(`check-changelog-structure.mjs --base` and the `--base` release-ledger gate).
+The archive files are not mandatory
+orientation reads and are not measured; a consumer whose reviewed baseline is older than the floor refuses
+with `baseline_below_floor` and adopts a newer reviewed baseline.

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.43.2`.
+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.47.0`.
 
 ## What this is
 

package/docs/sdk-storage-compatibility.md

@@ -8,7 +8,7 @@ npx --no-install campaigns-os sdk storage-check --target . --target-sdk 0.4.38 -
 
 Omit `--json` for the concise human report. Exit 0 means source-compatible; exit 2 means incompatible or unknown; invalid arguments or manifests exit 1. No merchant files or pins are rewritten. This is independent of doctor's built HTML markup check.
 
-The manifest is generated and owned by Campaign Cart, from its storage registry. The scanner has no independent SDK key list and fetches no remote code. Supply the generated `storage-migrations.v1.json` from the SDK contract change (campaign-cart #102); until that change is published, this command does **not** imply a released SDK tag contains that file. The report records the full file SHA-256, SDK version, supported target range, registry/extractor/input digest, and Git provenance. When the supplied bytes equal their repository HEAD blob, provenance is `verified-git-blob` with commit and repository path. Proposed, modified, or copied manifests are labeled `unverified-local-file`; the label never certifies a release. Review/pin SDK provenance separately before acting on findings. Targets outside the manifest's supported SDK range report unknown.
+The manifest is generated and owned by Campaign Cart, from its storage registry. The scanner has no independent SDK key list and fetches no remote code. Supply `docs/compatibility/storage-migrations.v1.json` from an unmodified checkout of a Campaign Cart release tag, v0.4.40 or later. The report records the full file SHA-256, SDK version, supported target range, registry/extractor/input digest, and Git provenance. When the supplied bytes equal their repository HEAD blob, provenance is `verified-git-blob` with commit and repository path. Proposed, modified, or copied manifests are labeled `unverified-local-file`; the label never certifies a release. Review/pin SDK provenance separately before acting on findings. A release manifest covers the target range it declares, which may end below its own SDK version: the v0.4.40 manifest, for example, covers 0.4.38 only. Targets outside the manifest's supported SDK range report unknown. A manifest whose SDK version is below its supported maximum is invalid.
 
 `--target` must name the Git root. `--scope` is mandatory: comma-separated literal repository-relative directory/file paths; use `.` only when the complete repository is intended. Add shared JavaScript directories explicitly. `--exclude` uses the same syntax and records explicit exclusions. Archives receive no implicit exemption. Only Git-tracked `.html`, `.htm`, `.js`, `.mjs`, and `.cjs` files in the selected scope are scanned, using current working-tree bytes and per-file digests; untracked files and built dependencies are outside this evidence. A selected HTML page's local script outside the selected files reports unknown. Relative scripts affected by an HTML `<base href>` also report unknown; review their actual dependency paths. Remote SDK and third-party scripts are not fetched or analyzed.
 

package/docs/skills-revision.md

@@ -16,7 +16,7 @@ that the copy on disk moved.
 `skills.json` carries one top-level field:
 
 ```json
-"bundle_revision": "1.43.2+skills.1"
+"bundle_revision": "1.47.0+skills.1"
 ```
 
 The spelling is `<package version>+skills.<n>`:
@@ -25,7 +25,7 @@ The spelling is `<package version>+skills.<n>`:
   skills ship with (`check-skill-versions.mjs` fails if the two disagree);
 - `<n>` is a plain counter, not a semver component. It says "this is the *n*th
   skill-text revision published against that package version" and it **resets
-  with the prefix**. `1.43.2+skills.1` is therefore ahead of `1.40.0+skills.7`.
+  with the prefix**. `1.47.0+skills.1` is therefore ahead of `1.40.0+skills.7`.
 
 It is one identity for the bundle as a whole, on purpose. Per-skill versions
 still exist and still gate per-skill changes, but an agent that loaded one skill
@@ -37,7 +37,7 @@ The first body line of every bundled `SKILL.md`, immediately after the
 frontmatter, is exactly:
 
 ```
-Bundle revision: 1.43.2+skills.1
+Bundle revision: 1.47.0+skills.1
 ```
 
 followed by a short paragraph telling the agent to run the check below at the
@@ -48,7 +48,7 @@ text the agent is actually reading, not from a file it would have to go and open
 ## The check
 
 ```bash
-npx --no-install campaigns-os tooling status --skills-revision 1.43.2+skills.1
+npx --no-install campaigns-os tooling status --skills-revision 1.47.0+skills.1
 ```
 
 The value is compared against the bundle revision of the **CLI the command runs
@@ -90,20 +90,20 @@ reports the choice as `skills.scope` (`requested`, `installed_platforms`, or
 "revision_check": "match",
 "skills_revision": {
   "status": "match",
-  "requested": "1.43.2+skills.1",
+  "requested": "1.47.0+skills.1",
   "spelling": "bundle",
-  "on_disk": "1.43.2+skills.1",
+  "on_disk": "1.47.0+skills.1",
   "on_disk_skill": null,
-  "message": "match (1.43.2+skills.1)"
+  "message": "match (1.47.0+skills.1)"
 }
 ```
 
 The text view prints one named line, as a header above the rest of the status:
 
 ```
-Skills revision: match (1.43.2+skills.1)
-Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.43.2+skills.1 — start a fresh session
-Skills revision: unchecked (on disk 1.43.2+skills.1)
+Skills revision: match (1.47.0+skills.1)
+Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.47.0+skills.1 — start a fresh session
+Skills revision: unchecked (on disk 1.47.0+skills.1)
 ```
 
 `unchecked` is the state when the flag is absent. It is not an error — an

package/docs/supported-surface.md

@@ -14,7 +14,7 @@ implementation detail, however stable it looks.
 | Surface | Contract | Change discipline |
 |---|---|---|
 | `schemas/*.schema.json` (all of them) | The portable contract catalog: CampaignSpec, Design Source Package, Build Packet, Build Context, Assembly Report, Doctor Output, sidecar-bundle conformance, Run Record, Workflow Finding, Build Brief, Source-HTML Manifest, Tooling Orientation, Release Ledger, QA Verdict, the QA Verdict sidecar projection, Runtime Recipe, and the legacy-migration inventory/plan/receipt trio. | Hashed. Any content change requires updating the recorded hash **and** bumping `surface_version` in the same PR. A shape change that alters meaning gets a new schema-version const — one version identifier must never cover two shapes (the 2026-08 assembly-report drift is the incident this rule encodes). Additions to an open `v0` schema are expected and consumers must tolerate unknown fields; the security-sensitive legacy-migration schemas are closed, so additions there require a new lineage. 1.28.0 (RL entry `surface_version: 1.28.0`, breaking) removed the two required Build Packet booleans `qa.test_orders_allowed` and `qa.sandbox_test_card_confirmed` (nothing read them; test orders run from `--test-order <mode>` alone), added `local-serve` to the `deploy.target` enum, and added the optional `remit_result` / `remit_base_kind` fields to the Run Record. 1.30.0 (additive) added the optional `data_layer` record to the QA Verdict's `test_orders[]` entries — the order's `dl_purchase` reading (#325). 1.33.0 (additive) added the optional `qa_verdict_publish` block to the Run Record — which verdict was posted to the QA portal, by `qa run` or `qa publish`, and what the portal answered, in the `remit_result` vocabulary (#328). |
-| CLI commands: `start`, `prepare-build`, `build`, `polish`, `checkpoint`, `page-kit`, `spec`, `doctor`, `bundle`, `next`, `theme`, `tooling`, `install-skills`, `install-agent-context`, `validate-assembly-report`, `telemetry`, `standardize`, `qa`, `findings`, `run-record`, `run`, `sdk`, `demo`, `login`, `logout` | Scriptable entry points. The founding list (1.0.0) was the argv surface Campaigns Agent's remit fixture pins; 1.25.0 adds the partner entry path the public guides instruct — `install-skills` (skill install), `tooling status` (preflight), `next --packet` (the runtime cursor) — plus `theme`, `install-agent-context`, `validate-assembly-report`, and `telemetry`, since consent is part of the partner contract. `validate-build-packet`, formerly an undocumented and unsupported alias of `doctor`, was removed in 1.25.0+agent.7 (RL-0036) and now gets the unknown-command error; use `doctor`. `standardization-report`, a supported but redundant second spelling of `standardize` — same flags, same output, same exit codes — was removed in 1.27.0 and now gets the same unknown-command error; use `standardize`. Removing a supported command is a breaking change and is why that release moved the minor. `bundle check` validates the canonical JSON readback set and makes QA required only under `--require-qa`. `polish capture` owns page-load evidence production. `checkpoint waive` currently accepts four registered gates: `page_kit.store_profile`, `page_kit.sdk_version`, `polish.hidden_eager_media`, and `built_output.upsell_selector_scope`. `page-kit sync` (added in 1.29.0) writes the CampaignSpec's Store Profile fields and SDK pin into the target's `_data/campaigns.json` entry — the repair the first two gates name — and is the only `page-kit` subcommand. `spec derive` (added in 1.31.0) is the reverse write for the repo-derived field class (#432): the target's SDK pin, page routes and analytics ids into the packet's local CampaignSpec; it is the only `spec` subcommand, and the `page_kit.sdk_version.repo_newer` advisory names it; its `--write-map` flag (1.33.0+agent.2) also records the derived pin in the saved Map's Build hints field through the proxy Worker, never moving a Map pin backwards. `qa publish` (added in 1.33.0) posts an already-stored verdict to the QA portal without a re-run or an order, refusing a stale `spec_hash` or a verdict its Run Record already records as published (#328). Within Polish, only the broader Source Freshness waiver remains on its existing report lane; theme and QA decisions also retain their existing lanes. | Any change to this list — adding, renaming, or removing a command — bumps `surface_version` in the same PR, and since 1.25.0 `check-supported-surface.mjs --base` enforces that (before, only hashed and named entries owed a bump, so `checkpoint` landed unbumped). Subcommands, registered gates, and flags may grow freely beneath a listed command. Removing a listed command from dispatch fails the gate outright. Do not infer support for an unregistered checkpoint from the top-level command. |
+| CLI commands: `start`, `prepare-build`, `build`, `polish`, `checkpoint`, `page-kit`, `spec`, `doctor`, `bundle`, `next`, `theme`, `tooling`, `install-skills`, `install-agent-context`, `validate-assembly-report`, `telemetry`, `standardize`, `qa`, `findings`, `run-record`, `run`, `sdk`, `demo`, `login`, `logout` | Scriptable entry points. The founding list (1.0.0) was the argv surface Campaigns Agent's remit fixture pins; 1.25.0 adds the partner entry path the public guides instruct — `install-skills` (skill install), `tooling status` (preflight), `next --packet` (the runtime cursor) — plus `theme`, `install-agent-context`, `validate-assembly-report`, and `telemetry`, since consent is part of the partner contract. `validate-build-packet`, formerly an undocumented and unsupported alias of `doctor`, was removed in 1.25.0+agent.7 (RL-0036) and now gets the unknown-command error; use `doctor`. `standardization-report`, a supported but redundant second spelling of `standardize` — same flags, same output, same exit codes — was removed in 1.27.0 and now gets the same unknown-command error; use `standardize`. Removing a supported command is a breaking change and is why that release moved the minor. `bundle check` validates the canonical JSON readback set and makes QA required only under `--require-qa`. `polish capture` owns page-load evidence production. `checkpoint waive` currently accepts five registered gates: `page_kit.store_profile`, `page_kit.sdk_version`, `polish.hidden_eager_media`, `built_output.upsell_selector_scope`, and `source_html.producer_provenance` (per page, with `--page <page_id>`). `page-kit sync` (added in 1.29.0) writes the CampaignSpec's Store Profile fields and SDK pin into the target's `_data/campaigns.json` entry — the repair the first two gates name — and is the only `page-kit` subcommand. `spec derive` (added in 1.31.0) is the reverse write for the repo-derived field class (#432): the target's SDK pin, page routes and analytics ids into the packet's local CampaignSpec; it is the only `spec` subcommand, and the `page_kit.sdk_version.repo_newer` advisory names it; its `--write-map` flag (1.33.0+agent.2) also records the derived pin in the saved Map's Build hints field through the proxy Worker, never moving a Map pin backwards. `qa publish` (added in 1.33.0) posts an already-stored verdict to the QA portal without a re-run or an order, refusing a stale `spec_hash` or a verdict its Run Record already records as published (#328). Within Polish, only the broader Source Freshness waiver remains on its existing report lane; theme and QA decisions also retain their existing lanes. | Any change to this list — adding, renaming, or removing a command — bumps `surface_version` in the same PR, and since 1.25.0 `check-supported-surface.mjs --base` enforces that (before, only hashed and named entries owed a bump, so `checkpoint` landed unbumped). Subcommands, registered gates, and flags may grow freely beneath a listed command. Removing a listed command from dispatch fails the gate outright. Do not infer support for an unregistered checkpoint from the top-level command. |
 | `sdk storage-check` and `docs/sdk-storage-compatibility.md` | Read-only AST compatibility report for explicitly scoped tracked campaign HTML/JS before an SDK bump; consumes the supplied SDK-owned manifest and records its SHA-256 and verified or unverified local Git provenance. Incompatible and unknown findings exit 2; a clean scan is static source evidence only. | Additive supported CLI and named documentation; no automatic merchant integration repair. |
 | `bin/campaigns-os.mjs` (`campaigns-os`) | The CLI entry itself. | Declared in `package.json` `bin`; the gate fails if it disappears. |
 | Package export `./campaign-spec` | The versioned campaign-spec rule registry, consumed as `@nextcommerce/campaigns-os` (pinned by consumers' lockfiles; lockstep policy — ADR-003 in the ops repo). | Behavior-guarded from the consumer side by their contract tests; the export path itself is gated here. |
@@ -24,7 +24,7 @@ implementation detail, however stable it looks.
 | Contract docs: `CONTEXT.md`, `docs/campaigns-os-build-flow.md`, `docs/build-packet.md`, `docs/migration-sidecar-bundle.md`, `docs/design-source-package.md`, `docs/campaign-build-brief.md`, `docs/campaign-standardization-report.md`, `docs/brand-theme-bridge.md`, `docs/qa-and-test-orders.md`, `docs/legacy-migration.md`, `docs/versioning.md`, `docs/workflow-findings-sidecar.md`, this file | Named entry points consumers pin for context. | Content evolves freely; the path must keep existing. |
 | `skills.json` + `skills/` + `skills.sh` | Versioned skill packages and their installer. | Governed by `check-skill-versions.mjs` (parity + bump gate + reserved external names). `skills.json` ships in the npm pack as of surface 1.0.0. As of 1.40.0 the manifest also carries `bundle_revision` (`<package version>+skills.<n>`), one identity for the bundle that every `SKILL.md` states on its first body line and that `campaigns-os tooling status --skills-revision <value>` checks against the bundle on disk; it must advance whenever any bundled skill changes (`--base` mode), and `docs/skills-revision.md` is its prose. |
 | `compatibility.json` | The published compatibility statement. | Named; must keep existing. |
-| Orientation contract: `AGENTS.md`, `CHANGELOG.md`, `contracts/release-ledger.json`, `contracts/agent-relevant-change-policy.v1.json`, `contracts/orientation-limits.v1.json`, `contracts/orientation-reason-codes.v1.json`, `docs/orientation-contract-reference.md`, `docs/release-ledger-authoring-guide.md`, `contracts/fixtures/orientation/canonicalization/v1.json` | The declarative data a consumer reads from Git objects to decide whether a commit is safe to work against, without executing anything from this repository. Schema `campaigns-os-tooling-orientation/v1`; ledger schema `campaigns-os-release-ledger/v1`. The canonicalization fixture gives independent implementations exact ledger and changelog bytes plus their expected SHA-256 digests. Entry point: [`AGENTS.md`](../AGENTS.md). | Named. The ledger is append-only: a correction ships as a new amendment entry, never an edit. `scripts/check-release-ledger.mjs` enforces the two-way gate; `docs/orientation-contract-reference.md` and the canonicalization fixture are generated together, and CI fails if either is stale. |
+| Orientation contract: `AGENTS.md`, `CHANGELOG.md`, `contracts/release-ledger.json`, `contracts/archive/release-ledger.2026-09-30.json`, `contracts/archive/CHANGELOG.2026-09-30.md`, `contracts/agent-relevant-change-policy.v1.json`, `contracts/orientation-limits.v1.json`, `contracts/orientation-reason-codes.v1.json`, `docs/orientation-contract-reference.md`, `docs/release-ledger-authoring-guide.md`, `contracts/fixtures/orientation/canonicalization/v1.json` | The declarative data a consumer reads from Git objects to decide whether a commit is safe to work against, without executing anything from this repository. Schema `campaigns-os-tooling-orientation/v1`; ledger schema `campaigns-os-release-ledger/v1`. The canonicalization fixture gives independent implementations exact ledger and changelog bytes plus their expected SHA-256 digests. Entry point: [`AGENTS.md`](../AGENTS.md). | Named. The ledger is append-only: a correction ships as a new amendment entry, never an edit. A baseline rotation moves older entries and changelog sections unchanged into dated files under `contracts/archive/`, which never change once merged and are not mandatory orientation reads. `scripts/check-release-ledger.mjs` enforces the two-way gate; `docs/orientation-contract-reference.md` and the canonicalization fixture are generated together, and CI fails if either is stale. |
 | Orientation fixtures: `contracts/fixtures/orientation/envelope/*.json`, `contracts/fixtures/orientation/hostile-target/**` (as named) | The bytes a consumer's parser validates against: one envelope per terminal outcome, plus a hostile target carrying Git hooks, an executable file, and npm lifecycle scripts for proving a reader executes nothing. The hostile target carries a second invariant for the runtime recipe: preparing it must run the recipe's own two steps and no lifecycle script reachable from them. | Named. Regenerate the envelopes with `npm run generate:orientation-docs`. Fixtures under `contracts/fixtures/` that are **not** named here — including the legacy-migration conformance corpus — are this repo's own test data and are not supported. |
 | Runtime recipe: `contracts/runtime-recipe.campaigns-os-node-v1.json` | The declarative description of how a checkout at one commit becomes a usable installed runtime: exact commands, accepted tool ranges, per-step network policy, the enumerated input set, the mandatory output checks, and the enforced bounds. This repository publishes it; the consumer bootstrap executes it. Guide: [`docs/runtime-readiness.md`](runtime-readiness.md). | **Hashed**, deliberately unlike the orientation policy contracts beside it. Any change to commands, network policy, tool versions, inputs, or output verification is an agent-relevant release event, and only a hashed entry makes such a change require `surface_version` to advance in the same PR. A recipe whose commands can change without a version bump is not a contract. |
 | Runtime-recipe fixtures: `contracts/fixtures/runtime-recipe/**` (as named), `docs/runtime-readiness.md` | Accept and single-mutation reject documents a consumer's parser validates against, the prepared-runtime states its output checks must distinguish, and the generated guide. | Named. All of it is generated — regenerate with `npm run generate:runtime-docs`; CI fails on a stale copy. |

package/docs/versioning.md

@@ -42,7 +42,10 @@ consumer needs to know about an agent-relevant change even when
 `CHANGELOG.md` narrates them, and the two are checked against each other in both
 directions. Reason codes and semantic classes are append-only vocabularies —
 renaming or removing one is a breaking change. Raising a limit advances
-`limits_version` and owes its own ledger entry.
+`limits_version` and owes its own ledger entry. Rotating the baseline (moving
+old entries and their sections into a dated `contracts/archive/` pair under the
+ledger's `baseline_floor`) changes no limit and no schema id; it is recorded as
+its own ledger entry.
 
 The runtime recipe carries two version identifiers because they gate different
 things. The **kind** names what an installed consumer must already understand in

package/package.json

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