@nextcommerce/campaigns-os 1.43.2 → 1.46.0

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
@@ -1107,13 +1138,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 +1629,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 +1814,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.46.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. Targets outside the manifest's supported SDK range report unknown.
 
 `--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.46.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.46.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.46.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.46.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.46.0+skills.1",
   "spelling": "bundle",
-  "on_disk": "1.43.2+skills.1",
+  "on_disk": "1.46.0+skills.1",
   "on_disk_skill": null,
-  "message": "match (1.43.2+skills.1)"
+  "message": "match (1.46.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.46.0+skills.1)
+Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.46.0+skills.1 — start a fresh session
+Skills revision: unchecked (on disk 1.46.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.46.0",
   "description": "Toolkit for agent-assisted NEXT campaign builds.",
   "license": "Apache-2.0",
   "repository": {

package/schemas/campaigns-os-release-ledger.v1.schema.json

@@ -16,11 +16,41 @@
     },
     "entries": {
       "type": "array",
-      "description": "Ordered oldest to newest. sequence is strictly increasing by 1 from 1, and date is non-decreasing.",
+      "description": "Ordered oldest to newest. sequence is strictly increasing by 1 from 1, and date is non-decreasing. When baseline_floor is present, the entries up to the floor live in the archive it names and this array starts at baseline_floor.last_archived_sequence + 1.",
       "items": { "$ref": "#/$defs/entry" }
-    }
+    },
+    "baseline_floor": { "$ref": "#/$defs/baseline_floor" }
   },
   "$defs": {
+    "baseline_floor": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Present after a baseline rotation. Entries up to and including last_archived_id moved byte-for-byte, and the changelog from the first section they link to the end of the file moved verbatim, into the dated archive files listed in archives; they keep their original sequence and hashes, so each archived entry's changelog_sha256 verifies against the archive changelog. The archive files are not mandatory orientation reads and count against no orientation limit. A consumer whose reviewed baseline's newest entry is older than last_archived_id refuses with refusal_reason_code and adopts a newer reviewed baseline. The floor only moves forward, only with a new rotation entry, and an archive file never changes once merged; a later rotation appends a new archive pair.",
+      "required": ["archives", "last_archived_id", "last_archived_sequence", "first_kept_id", "rotation_entry", "refusal_reason_code"],
+      "properties": {
+        "archives": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Every archive pair, oldest rotation first. Append-only.",
+          "items": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["ledger_path", "ledger_sha256", "changelog_path", "changelog_sha256"],
+            "properties": {
+              "ledger_path": { "type": "string", "pattern": "^contracts/archive/[^/]+\\.json$", "description": "Archived entries, same schema_version and shape as this file." },
+              "ledger_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 over the exact bytes of ledger_path." },
+              "changelog_path": { "type": "string", "pattern": "^contracts/archive/[^/]+\\.md$", "description": "The changelog tail that starts at the first section the archived entries link, verbatim and in order, same heading format." },
+              "changelog_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 over the exact bytes of changelog_path." }
+            }
+          }
+        },
+        "last_archived_id": { "type": "string", "pattern": "^RL-[0-9]{4}$", "description": "The newest archived entry." },
+        "last_archived_sequence": { "type": "integer", "minimum": 1, "description": "Its sequence. The first live entry's sequence is this plus one." },
+        "first_kept_id": { "type": "string", "pattern": "^RL-[0-9]{4}$", "description": "The first entry still in this file." },
+        "rotation_entry": { "type": "string", "pattern": "^RL-[0-9]{4}$", "description": "The live entry that recorded the rotation which set this floor." },
+        "refusal_reason_code": { "type": "string", "minLength": 1, "description": "The reason code, from contracts/orientation-reason-codes.v1.json, a consumer refuses with when its reviewed baseline is below the floor." }
+      }
+    },
     "entry": {
       "type": "object",
       "additionalProperties": true,

package/schemas/campaigns-os-tooling-orientation.v1.schema.json

@@ -350,6 +350,7 @@
       "enum": [
         "already_current",
         "ahead_of_upstream",
+        "baseline_below_floor",
         "checkout_acquisition_failed",
         "checkout_already_exists",
         "checkout_missing",

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

@@ -1,11 +1,11 @@
 ---
 name: campaign-lifecycle-orientation
-version: 1.0.9
+version: 1.0.17
 description: Orient a reader to the Campaigns OS lifecycle artifacts a run has already emitted, without advancing any stage or changing any state.
 ---
 
-Bundle revision: 1.43.2+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.43.2+skills.1`
+Bundle revision: 1.46.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.46.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read
@@ -34,6 +34,15 @@ cite `src/` or `scripts/`: those are implementation and may change without a
 supported-surface bump, so a reader cannot check them and a rename would not
 reach this text. `docs/supported-surface.md` is the prose twin of that list.
 
+`CHANGELOG.md` and `contracts/release-ledger.json` hold recent history. When
+the ledger declares a `baseline_floor`, the older entries and the sections they
+link sit in the dated `contracts/archive/` files it names: cite those for
+history, but they are not part of an orientation read. An orientation whose
+reviewed baseline is older than the floor is refused with
+`baseline_below_floor`, and the remedy is to adopt a newer reviewed baseline.
+That is a reviewed change for an authorized human, not something to do in a
+session.
+
 Identity comes from the tool, not from a file beside the session.
 `campaigns-os tooling status --json` (tier `B`: its only write is the
 command-lifecycle journal) reports the install mode, the version, and a source
@@ -90,8 +99,10 @@ proceeds. It checks the packet, its CampaignSpec, the artifacts and the built
 output, and its ordered check registry records what ran. When blocking errors
 exist the result is not OK, names the errors, and points the next step at
 collecting or correcting input. `campaigns-os doctor --packet <packet> --json`
-(tier `none`: inspection is the default, and without `--write` it leaves the
-target byte-identical) is the inspection form.
+(tier `A`: inspection is the default, and without `--write` it leaves the
+target byte-identical, but once the site is built and a public campaign key
+resolves it makes one read-only request for the live campaign) is the
+inspection form.
 
 Read doctor's recorded result, not a process exit code. Exit codes are knowable
 only from implementation files this skill may not cite, so do not branch on one.

package/skills/campaign-readback-classification/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: campaign-readback-classification
-version: 1.0.9
+version: 1.0.17
 description: Classify a selected campaign from the readback projection's v2 fields and write a read-only handoff without turning diagnosis into permission.
 ---
 
-Bundle revision: 1.43.2+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.43.2+skills.1`
+Bundle revision: 1.46.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.46.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read