@nextcommerce/campaigns-os 1.43.1 → 1.46.0

package/docs/effects.md

@@ -38,8 +38,10 @@ that already understands those hints needs no translation layer.
 **`readOnlyHint` counts the command-lifecycle journal.** A journal append is a
 write like any other, so every `readOnlyHint: true` row is an invocation the
 CLI exempts from lifecycle capture (the converse does not hold: `demo` and the
-`--no-write` forms skip the journal but still write other declared files): `help`, `readback`,
-`run status`, `doctor` inspection, `doctor --no-write`, `sdk storage-check`,
+`--no-write` forms skip the journal but still write other declared files, and
+`doctor` inspection and `doctor --no-write` skip it and write nothing but may
+send the one live campaign read): `help`, `readback`,
+`run status`, `doctor --no-live-refs` inspection, `sdk storage-check`,
 `tooling diagnose`, a refused invocation, `run-record --no-write`, and every
 `--dry-run` form on the commands that implement the flag. Everything else
 appends an entry when a journal is selected — an active run session,
@@ -81,6 +83,46 @@ writes your **home** directory, not the campaign. `telemetry on` writes your
 **machine** config. `run-record` writes beside the **working directory**, not the
 target repo. A row that said "writes the target" would be wrong about all three.
 
+### The Map Builder fetch
+
+`start`, `prepare-build` and `build` take their CampaignSpec from `--spec` or
+from `--map-id`. With `--map-id` (and no `--cached-spec`) the invocation sends
+`{proxy-base}/api/spec/{map-id}` and writes what comes back to
+`{target}/.campaign-runtime/fetched-specs/<map-id>.json`, replacing any earlier
+copy of that Map; the intake then reads the spec from that file. Both effects
+are on every row for those three commands. The effect test runs each row with
+`--spec` under four conditions and with `--map-id` under `persisted_consent`,
+the one condition whose `--proxy-base` is the loopback receiver, so the fetch
+and the write are observed rather than taken on trust.
+
+### The live campaign read
+
+`doctor --packet` (with or without `--write` / `--no-write`) and every `qa run`
+form check each page's shipping and package refs against the live campaign.
+Doctor reads when the packet's built `_site/<route>/` exists; QA reads when it
+has read at least one served page. Both need a public Campaigns API key from
+the packet, its local CampaignSpec or the declared campaign-key env var. The
+read is one `GET {proxy-base}/api/campaign` with the key in `X-Campaign-Key`,
+plus `?ref_id=<id>` when the CampaignSpec's `campaign.ref_id` names the
+campaign. No store or Admin credential is used. The proxy's answer is an
+envelope whose `data` field holds the campaign. A failed read, an `ok: false`
+envelope, one with an `error` and no campaign, or several campaigns with no
+`campaign.ref_id` to pick one is recorded as `not_run` with its reason, never
+as a pass. `--no-live-refs` on `doctor` or `qa run` skips only this read and
+records `not_run` with reason `disabled`; every other declared write and send
+is unchanged. Each form has its own row, including `doctor --write
+--no-live-refs` and `qa run --no-live-refs` with each `qa run` modifier.
+`doctor --no-write --no-live-refs` has the effects of the `doctor
+--no-live-refs` row.
+
+Only `doctor` and `qa run` make this read. The other commands that run doctor
+internally make no request and record `derived.live_campaign_refs` as
+`not_run` with reason `not_read`, with no warning: `start`, `prepare-build`
+and `build` (the intake alias for prepare-build + doctor), `theme waive`,
+`checkpoint`, `findings harvest`, `run-record`, `next`, and the doctor
+sidecar refresh `qa run` makes after it records the QA stage (the verdict
+itself carries QA's own read).
+
 ## How to read a row
 
 ```jsonc
@@ -108,7 +150,7 @@ There is **one row per command and per effect-changing flag combination**. The
 flags that change what the invocation does to the world are listed once, in
 `vocabulary.effect_changing_flags`: `--browser`, `--built`, `--dry-run`,
 `--emit-packet`, `--example`, `--force`, `--from-store`, `--list`,
-`--no-post-verdict`, `--no-probe`, `--no-remit`, `--no-run-session`,
+`--no-live-refs`, `--no-post-verdict`, `--no-probe`, `--no-remit`, `--no-run-session`,
 `--no-write`, `--republish`, `--test-order`, `--write`, `--write-map`. Flags
 that only change the output shape (`--json`, `--report`) deliberately do not.
 
@@ -134,7 +176,9 @@ a flag the command rejects up front. It writes nothing, journals nothing, and is
 the row to read when you want to know what a typo costs. The one exception is
 declared on the rows it belongs to: `start`, `prepare-build`, `build`,
 `run start` and `run end` close out a **stale** run session at the root they are
-about to act on *before* argv is refused.
+about to act on *before* argv is refused. Commands that implement `--dry-run`
+skip this closeout whenever that flag is present, including a valued flag that
+will be refused: `run end --dry-run yes` writes, sends, and deletes nothing.
 
 A refusal is decided by argv alone. When file content or state on disk decides
 the outcome, the command has reached a handler failure and journals it.
@@ -143,9 +187,13 @@ For intake, run-record, built-site QA, and `next`, argv-only checks run before
 their handler reads the target; invalid values are refused without a journal
 entry. For `start`, `prepare-build`, and `build`, bare, empty, and whitespace-only
 values of `--spec`, `--map-id`, `--source`, `--target`, `--source-kind`,
-`--proxy-base`, `--wrapper-policy`, `--design-manifest`, and
-`--order-path-depth` are refused before local spec reads, Map fetches, or cache
-writes on the `--spec`, `--map-id`, and `--map-id --cached-spec` paths.
+`--proxy-base`, `--wrapper-policy`, `--design-manifest`, `--order-path-depth`,
+`--template-family`, `--allow-uncertified-template`, `--theme-policy`, and
+`--brief` are refused before local spec reads, Map fetches, or cache writes on
+the `--spec`, `--map-id`, and `--map-id --cached-spec` paths. So is a
+`--theme-policy` outside `inspect_only`, `auto`, and `off`. Whether a named
+template family is certified, and whether a named brief can be read, depend on
+file content: those checks still run in the handler and are journaled.
 The operator-facing `run-record` and `run end` commands refuse bare, empty, or
 whitespace-only values for every value-taking inherited run-record flag before
 packet work. The five agent
@@ -189,6 +237,12 @@ flag without a value is refused with "Missing value for --<flag>". If a named
 packet yields neither a Map ID nor a valid local-spec identity after checkpoint
 preflight reads the packet, spec, and report, the requirement is a journaled
 handler failure. A conflicting local/Map identity is also a handler failure.
+When `qa run` selects `--legacy-api-test-order`, a missing, bare, empty, or
+unusable `--cart` and an unknown legacy mode are argv-only refusals before QA
+input resolution. They append no lifecycle entry. Accepted modes remain
+`accept`, `decline`, and `both` (case-insensitive); browser `--test-order` still
+takes precedence and does not require the legacy cart. API credentials are
+still checked only inside the legacy handler and failures there are journaled.
 The nested run-record refusal scope in session closeout guards against future
 changes. No internal closeout can currently create a refusal before its
 invoking command journals.
@@ -205,7 +259,7 @@ sha256) before and after while a loopback `node:http` receiver counts requests.
 | `ambient_session` | An active ambient run session opened by `run start` at the target. |
 | `stale_session` | A run session idle past the 12 h TTL, at the target and at the working directory. |
 | `lifecycle_log` | `CAMPAIGNS_OS_LIFECYCLE_LOG` names a journal outside the runtime directory. |
-| `persisted_consent` | Run Telemetry consent **persisted on the machine for the loopback receiver's scope**, a synthetic campaign key in the environment, no run session, and `--proxy-base <loopback>` wherever the command takes it. |
+| `persisted_consent` | Run Telemetry consent **persisted on the machine for the loopback receiver's scope**, a synthetic campaign key in the environment, no run session, and `--proxy-base <loopback>` wherever the command takes it. `start`, `prepare-build` and `build` name their spec by `--map-id` here, and the receiver serves it. |
 
 Five conditions rather than one, because the CLI's effects are not a function of
 argv alone: an ambient session redirects the journal and is itself touched by
@@ -307,10 +361,10 @@ loopback receiver only stands in for (`{base-url}`, the login gateway) matched
   refuses the contradiction rather than letting the test find it.
 
 A `full` row may still carry an individual effect the offline fixture cannot
-reach — the Map Builder spec fetch behind `--map-id`, the `codex` and `agents`
-destinations of `install-skills`. Each such entry has an empty `observed_in`
-**and** a `not_observed_reason`, and `check-effects.mjs` refuses one without the
-reason. What it may not be is silent.
+reach — the `codex` and `agents` destinations of `install-skills`. Each such
+entry has an empty `observed_in` **and** a `not_observed_reason`, and
+`check-effects.mjs` refuses one without the reason. What it may not be is
+silent.
 
 ## The rule
 

package/docs/gateway-login.md

@@ -17,6 +17,9 @@ campaigns-os login --store example
 There is no discovery or guess from the current project. Noninteractive calls
 must supply `--store`. URLs, paths and unrelated hosts are refused before any
 request. Login uses the fixed `https://mcp.nextcommerce.com` gateway.
+It asks for the `https://mcp.nextcommerce.com/mcp` resource and the
+`campaigns.read` capability. A login saved before 1.43.2+agent.3, which named
+the earlier `/campaigns` resource, is refused; sign in again.
 
 Open the displayed device page in one browser tab and enter the displayed code.
 Keep that tab: if installation is needed, follow its Install Campaigns link,

package/docs/local-setup.md

@@ -3,7 +3,7 @@
 For a new campaign, choose its working folder and run this from that folder:
 
 ```sh
-npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.43.1 next-campaign-page-kit@0.2.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
+npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.46.0 next-campaign-page-kit@0.2.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
 ```
 
 Review the release source/provenance before installation as described in

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.1`
+Supported surface at generation time: `1.46.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/progress-snapshots.md

@@ -59,12 +59,16 @@ across them. A progress stream is independent of a run-session ID.
 
 Sanitized immutable snapshots are written under the target repository's
 `.campaign-runtime/progress/` before any request. Allocation uses an exclusive
-local lock with a process owner. Dead owners are recovered through an exclusive
-recovery claim and an atomic rename; a live process is never evicted. An ownerless
-crash gap is recoverable after ten seconds. If recovery itself is interrupted,
-capture fails closed: stop all Campaigns OS writers for that target, then remove
-the abandoned `.allocation-lock` directory in the affected progress scope before
-retrying `next`. Do not remove a lock while a writer is active.
+local lock with a process owner; the lock directory and its owner record are
+published together in one rename, so a lock never exists without its owner.
+Dead owners are recovered through an exclusive recovery claim and an atomic
+rename; a live process is never evicted. A lock directory with no owner record
+(left by an older release) is never taken over: capture refuses it after about
+a second. If one is found, or if recovery itself is interrupted, capture fails
+closed and the warning names the affected `.allocation-lock` directory: stop
+all Campaigns OS writers for that target, then remove that directory before
+retrying `next`. Do not remove a lock while a writer is active. Do not run an
+older Campaigns OS release against the same target at the same time.
 
 An unchanged projection reuses its ID, timestamp and sequence. Identity
 changes start a new stream. Each local scope retains at most 32 snapshots and