@nextcommerce/campaigns-os 1.37.2 → 1.41.2

package/docs/skills-revision.md

@@ -0,0 +1,364 @@
+# Skills bundle revision
+
+The skills Campaigns OS bundles (nine as of 1.40.0) are installed into shared agent skill
+directories and then **read into an agent's context once**, at the start of a
+task. They are not re-read afterwards. The CLI underneath that session, however,
+can be replaced at any moment — an `npm install` in the campaign folder, an
+`npx` cache refresh, a `git pull` in a toolkit checkout.
+
+That is the drift this document is about: an agent following instructions from
+one release while calling a CLI from another. Nothing in the per-skill versions
+catches it, because the agent has no reason to look at them and no way to notice
+that the copy on disk moved.
+
+## The identity
+
+`skills.json` carries one top-level field:
+
+```json
+"bundle_revision": "1.41.2+skills.1"
+```
+
+The spelling is `<package version>+skills.<n>`:
+
+- the **prefix** is this package's `version`, so a revision names the release its
+  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.41.2+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
+cannot reconcile five versions; it can quote back one string.
+
+## The header line
+
+The first body line of every bundled `SKILL.md`, immediately after the
+frontmatter, is exactly:
+
+```
+Bundle revision: 1.41.2+skills.1
+```
+
+followed by a short paragraph telling the agent to run the check below at the
+start of each task, through the project's pinned copy, and what an older copy's
+answer looks like. This line is the value an agent has in hand: it comes from the
+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.41.2+skills.1
+```
+
+The value is compared against the bundle revision of the **CLI the command runs
+from** — the `skills.json` inside the installed package, not the working
+directory, which in a campaign repo has no `skills.json` at all.
+
+Run it from the campaign's Page Kit folder, where `npx --no-install campaigns-os`
+resolves the project's exact devDependency. `--no-install` keeps it there: the published
+package is `@nextcommerce/campaigns-os` and `campaigns-os` is only its bin, so
+outside a pinned folder a plain `npx campaigns-os` looks the bin name up as a
+package on the registry and, without a terminal to ask, installs whatever it
+finds. With `--no-install` it stops instead. A bare `campaigns-os` resolves
+through PATH, and a machine that once installed the toolkit globally can answer
+with that older copy.
+A copy older than 1.40.0 does not know `--skills-revision`: it ignores the flag,
+prints no `Skills revision:` line (and no `revision_check` under `--json`), and
+may list actions of its own, such as an `install-skills` that replaces part of
+this bundle with its older text. The revision comparison cannot see the result,
+because the header an agent quotes still names this bundle; the pinned copy's
+own freshness check does, and reports the replaced skills as stale. The skill
+header says so: no `Skills revision:` line (no `revision_check` under `--json`)
+means the pinned copy did not answer, and none of that output's actions should
+be followed.
+
+Without `--platform` or `--target`, the skill freshness part of the report checks
+only the platform directories where Campaigns OS skills are installed (a skill
+under one of the bundled names, or our own copy under a retired name), and a `Ready:`
+line names the platforms it skipped. A Claude Code only install is therefore not
+reported stale for Codex or the shared directory, and a stale install's refresh
+action names each stale platform. `--platform all` checks all three, as it always
+has. When no platform has Campaigns OS skills, the action asks for an install on
+the harness in use (`install-skills --platform claude`, or `codex` / `agents`). `--json`
+reports the choice as `skills.scope` (`requested`, `installed_platforms`, or
+`no_platform_installed`) with `skills.not_installed_platforms`.
+
+`--json` reports a bare status string alongside the detail:
+
+```json
+"revision_check": "match",
+"skills_revision": {
+  "status": "match",
+  "requested": "1.41.2+skills.1",
+  "spelling": "bundle",
+  "on_disk": "1.41.2+skills.1",
+  "on_disk_skill": null,
+  "message": "match (1.41.2+skills.1)"
+}
+```
+
+The text view prints one named line, as a header above the rest of the status:
+
+```
+Skills revision: match (1.41.2+skills.1)
+Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.41.2+skills.1 — start a fresh session
+Skills revision: unchecked (on disk 1.41.2+skills.1)
+```
+
+`unchecked` is the state when the flag is absent. It is not an error — an
+operator running preflight by hand has no revision to offer — and the on-disk
+revision is reported anyway, so the run still says what is installed.
+
+## Why the reported revision is named "on disk"
+
+Because the two sides of the comparison are not symmetric, and naming them
+symmetrically would hide the remedy.
+
+The requested value is text **already in context**. Re-running the command
+cannot change it; nothing can, short of a new session. The reported value is
+what is **installed right now**, and it is the side that moved. So the field is
+`on_disk`, the mismatch line says "on disk", and the remedy is not "update
+something" but "start a fresh session" — a fresh session is what re-reads the
+skill text.
+
+This also explains why a mismatch is not merely a warning. A session that keeps
+going is following instructions for a CLI that is no longer there.
+
+## Fallback spelling
+
+An agent that carries only the frontmatter of the single skill it loaded can
+pass that instead:
+
+```bash
+npx --no-install campaigns-os tooling status --skills-revision next-campaigns-qa@1.3.4
+```
+
+The version is checked against that skill's entry in the manifest, and the
+bundle revision is still reported beside it. A skill id this bundle does not
+ship reports `mismatch`, not a refusal: an agent quoting a skill that is not here
+is reading text from some other bundle, which is the condition the flag exists to
+catch.
+
+## Exit codes
+
+| Outcome | Exit |
+| --- | --- |
+| `match` (and the rest of the status is clean) | `0` |
+| `unchecked` (and the rest of the status is clean) | `0` |
+| `mismatch` | `2`, after the full status has printed |
+| `--skills-revision` given with no value | refused, non-zero, nothing inspected |
+
+A mismatch prints the whole status first and sets the exit code afterwards: the
+revision line is a header on the report, never a replacement for it. It also
+adds an explicit action naming the fresh session, so a reader of `actions[]`
+sees the remedy without parsing the header.
+
+`tooling status` exits `2` for other reasons too (skills needing a refresh, a
+checkout behind its upstream). Branch on `revision_check`, not on the exit code,
+when you need to know which one happened.
+
+## The gate
+
+`scripts/check-skill-versions.mjs` enforces both halves:
+
+- **without `--base`** (this runs inside `npm run check`): `bundle_revision`
+  exists, is spelled correctly, and its prefix is `package.json`'s `version`.
+- **with `--base <ref>`**: if any file under `skills/` changed since the base, or
+  if `skills.json`'s `skills[]` entries changed, `bundle_revision` must have
+  **advanced** — a newer prefix, or the same prefix with a higher counter. Equal
+  fails, and so does backwards.
+
+The changed set is the union of what changed since the base, what is in the
+working tree, and what is untracked, the same three-way union the release-ledger
+gate measures. A committed-only diff answers the wrong question for a bump gate:
+an unstaged `SKILL.md` edit is exactly the state a local run is asked about.
+
+The failure this produces is the point of the whole mechanism: skill text moved,
+the identity an agent quotes back did not, and a stale agent would have been told
+it was current.
+
+## The pin check
+
+The skills revision says which **text** an agent is reading. The pin says which
+**executable** the project runs. ADR 0002 allows one executable per project,
+and `tooling status` reports it on every run, alongside the revision check.
+
+### Sources and precedence
+
+1. **The project pin.** An entry for `@nextcommerce/campaigns-os` in
+   `devDependencies` or `dependencies`. Only an exact version is a pin:
+   `1.41.0`, and the forms npm reads as the same exact version, `=1.41.0` and
+   `v1.41.0` (reported as `project_version: "1.41.0"`). A range or a tag
+   (`^1.40.0`, `latest`, a git spec) names no single executable, so it is
+   reported under `range` and counts as no project pin. An empty or
+   whitespace-only spec names nothing at all: it is treated as absent, never
+   as a range, so it neither sets `range` nor hides a spec in the other key.
+   A `git+https://…#v1.0.0` or `file:../x` spec is likewise `unpinned`, with
+   the spec in `range`, and an exact spec in `dependencies` beside such a
+   `devDependencies` spec still wins.
+   `peerDependencies` and `optionalDependencies` are never a pin: ADR 0002 puts
+   the pin in `devDependencies`, and `dependencies` is read because it installs
+   the same executable.
+
+   The resolver starts at the nearest `package.json` above the working
+   directory (or above the packet's target repository when `--packet` is
+   given) and walks up toward the filesystem root. In each manifest it reads
+   `devDependencies`, then `dependencies`; the **first exact spec wins** and
+   ends the walk. A range does not end it: it is remembered, and
+   reported as `range` only if no exact spec turns up anywhere on the walk. So
+   a range in `devDependencies` never hides an exact pin in `dependencies`,
+   and a workspace package without an exact spec resolves its workspace root's
+   pin. A manifest that names the package in neither key and declares no
+   `workspaces` is neutral: it cannot supply a pin, so the walk goes on
+   through it, and a package nested inside a workspace package still reaches
+   the root's pin. The walk ends after a workspace root (a manifest declaring
+   `workspaces`, as an array or as `{ "packages": [...] }`), so a
+   `package.json` above a workspace root, even one with an exact pin, is never
+   read. It also ends at the filesystem root. One residual: outside a
+   workspace, a stray ancestor manifest that names the package (a
+   `package.json` in a home directory, say) is read when nothing exact turns
+   up below it, because the walk cannot tell it from the project's own root.
+
+   An installed package's own manifest is never the project: a `package.json`
+   whose directory sits directly in `node_modules`
+   (`node_modules/<name>/package.json`) or in a scope inside it
+   (`node_modules/@<scope>/<name>/package.json`) is skipped, so a run from
+   inside an install (for example
+   `<project>/node_modules/@nextcommerce/campaigns-os`) resolves the enclosing
+   project, packet home included, as if the working directory were that
+   project. Any other manifest is a candidate, even when a directory higher up
+   its path is named `node_modules` (`…/node_modules/work/site/package.json`
+   is its own project). A leading UTF-8 BOM is accepted, as npm accepts it. A
+   manifest on the walk that cannot be read, is not valid JSON or is not a
+   JSON object ends the walk with a warning naming the file (`Project pin
+   walk stopped at <path>: it is not valid JSON.`; for the nearest manifest,
+   `Project pin unavailable: <path> …`), since it might have held the pin.
+
+   `pin.project_manifest` is the manifest the pin (or range) came from, or the
+   nearest manifest when there is neither; `pin.project_key` is
+   `"devDependencies"`, `"dependencies"` or `null`. The `Pin:` line
+   (`pin.message`) names the key and manifest of every project version or
+   range it quotes (`devDependencies in <project>/package.json`), the nearest
+   manifest when it reports no project pin, and the packet file of every packet
+   version it quotes (`campaigns_os_version in
+   <project>/campaign-runtime.build.json`). Every action names the same
+   manifest and key: a pin read from `dependencies` says `set
+   dependencies[...]`.
+2. **The packet's recorded kernel version.** The Build Packet's optional
+   top-level `campaigns_os_version`, which `prepare-build` stamps with the
+   version that prepared it. The field is a bare `x.y.z` version (a
+   prerelease or build suffix allowed): the packet schema admits no `=` or `v`
+   prefix, so a packet value such as `=1.41.0` or `v1.41.0` is ignored with a
+   warning, reported verbatim as `pin.packet_version_ignored` (otherwise
+   `null`; a non-string value as its JSON text), and, when there is no project
+   pin, named on the `Pin:` line as ignored rather than absent. The
+   packet read is the project's `campaign-runtime.build.json` beside that
+   `package.json` (its contracted home), or the file `--packet <path>` names.
+   A missing packet, or one written before the field existed, is no packet
+   source.
+
+The packet is read from beside the nearest `package.json`, whichever manifest
+the project pin came from. The **running** version is the `package.json` of the
+CLI the command runs from.
+When both sources are present and equal, `source` is `"project"`.
+
+### The four statuses
+
+| `pin.status` | When | Exit |
+| --- | --- | --- |
+| `match` | the pin (project first, packet second) is the running version | `0` (if the rest of the status is clean) |
+| `stale_pin` | the pin is not the running version | `2`, with an action naming the file to change |
+| `conflicting_pin` | the project pin and the packet version are both present and differ | `2`, with an action naming both files |
+| `unpinned` | neither source is present (a range alone is not a pin) | `0` (if the rest of the status is clean), always reported |
+
+`conflicting_pin` wins over `stale_pin`: two sources that disagree are reported
+as a disagreement even when one of them is the running version.
+
+### `--force`
+
+`--force` overrides `stale_pin` and `conflicting_pin`: the command then exits as
+the rest of the status dictates, the pin line and `pin.message` say
+`(overridden by --force)`, `pin.forced` is `true`, and a warning replaces the
+action. `forced` is `true` only when the flag overrode something; on `match` or
+`unpinned` it stays `false`. The override is recorded on the command-lifecycle
+journal entry: `--force` appears in its `argv_shape` whenever a journal is
+selected (an active run session, `--lifecycle-journal`, or
+`CAMPAIGNS_OS_LIFECYCLE_LOG`). It is a bare flag and off by default. `--force true`
+and `--no-force` are refused before anything is inspected, and a refused
+invocation writes no journal entry.
+
+```bash
+campaigns-os tooling status --json
+campaigns-os tooling status --packet ./campaign-runtime.build.json --force
+```
+
+### Output
+
+Taken from real runs of a 1.41.0 install inside a fixture project. `--json`
+carries the full object:
+
+```json
+"pin": {
+  "source": "project",
+  "version": "1.41.0",
+  "running": "1.41.0",
+  "status": "conflicting_pin",
+  "range": null,
+  "packet_version": "1.40.0",
+  "packet_version_ignored": null,
+  "project_version": "1.41.0",
+  "project_manifest": "<project>/package.json",
+  "project_key": "devDependencies",
+  "forced": false,
+  "message": "conflicting_pin — project pins 1.41.0 (devDependencies in <project>/package.json), packet records 1.40.0 (campaigns_os_version in <project>/campaign-runtime.build.json)"
+}
+```
+
+```json
+"pin": {
+  "source": null,
+  "version": null,
+  "running": "1.41.0",
+  "status": "unpinned",
+  "range": "^1.40.0",
+  "packet_version": null,
+  "packet_version_ignored": null,
+  "project_version": null,
+  "project_manifest": "<project>/package.json",
+  "project_key": "devDependencies",
+  "forced": false,
+  "message": "unpinned (project range ^1.40.0 (devDependencies in <project>/package.json) is not an exact version; no packet version)"
+}
+```
+
+The text view prints one named line under the skills revision line, naming
+where each version it quotes was read:
+
+```
+Pin: match (1.41.0 — devDependencies in <project>/package.json)
+Pin: match (1.41.0 — dependencies in <project>/package.json)
+Pin: match (1.41.0 — campaigns_os_version in <project>/campaign-runtime.build.json)
+Pin: stale_pin — project pins 1.40.0 (devDependencies in <project>/package.json), running 1.41.0
+Pin: stale_pin — packet records 1.40.0 (campaigns_os_version in <project>/campaign-runtime.build.json), running 1.41.0
+Pin: stale_pin — project pins 1.40.0 (devDependencies in <project>/package.json), running 1.41.0 (overridden by --force)
+Pin: conflicting_pin — project pins 1.41.0 (devDependencies in <project>/package.json), packet records 1.40.0 (campaigns_os_version in <project>/campaign-runtime.build.json)
+Pin: unpinned (no project pin in <project>/package.json; no packet version)
+Pin: unpinned (no project pin in <project>/package.json; no campaigns_os_version in <project>/campaign-runtime.build.json)
+Pin: unpinned (no project pin in <project>/package.json; campaigns_os_version "v1.41.0" in <project>/campaign-runtime.build.json is not a bare x.y.z version and was ignored)
+Pin: unpinned (project range ^1.40.0 (devDependencies in <project>/package.json) is not an exact version; no packet version)
+```
+
+and, for a blocking status, an action such as:
+
+```
+- Align the project pin: set devDependencies["@nextcommerce/campaigns-os"] in <project>/package.json to 1.40.0, or re-run prepare-build with 1.41.0 so <project>/campaign-runtime.build.json records it. Pass --force to proceed anyway (recorded).
+```
+
+Branch on `pin.status`, not on the exit code: `tooling status` exits `2` for the
+other reasons above as well.
+
+This document is an entry in
+[`contracts/supported-surface.json`](../contracts/supported-surface.json)
+`named[]` as of 1.40.0: it ships in the npm pack, the CLI help points at it,
+and a consumer may depend on it at this path.

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` | 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 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. |
 | `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. |
@@ -22,7 +22,7 @@ implementation detail, however stable it looks.
 | Package export `./legacy-migration` and its three schema exports | Portable SDK 0.3.x migration inventory, preview-plan, receipt, Offer request/readback, and token-free evidence helpers. Guide: [`docs/legacy-migration.md`](legacy-migration.md). | Pure contract only: no authenticated transport, write executor, audit store, receipt store, sessions, deletes, or rollback. Consumers own execution and must retain the guarded apply protocol. |
 | Package export `./text-safety` | `singleLineField`, `singleLineFragment` and `singleLineDetail`: flatten a value this toolkit did not author to one line with no control characters before it is rendered into a single-line notice. `singleLineField` is for a value printed as its own field (a run id, a target path): every control character becomes U+FFFD and nothing else changes. `singleLineFragment` is for a value folded into a sentence (a gate's repair command or instruction): line breaks and tabs become spaces, runs of whitespace collapse, the ends are trimmed, and every other control character becomes U+FFFD. `singleLineDetail` is `singleLineFragment` plus Markdown escaping, a length cap and a placeholder for an empty value (a quoted loader message). | Pure string functions, no imports, no I/O. Added at surface 1.27.0; `singleLineFragment` added at 1.27.0+agent.2. The escape set may widen; a value that was already safe stays unchanged. |
 | 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. |
+| `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 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. |
@@ -83,14 +83,22 @@ the package a consumer installs."
    `public-contracts.manifest.json`) update on their own cadence against a
    version they can see move.
 
-Candidate 1.36.0 adds the portable `./progress` export, its strict v0 JSON schema,
+1.36.0 (published in 1.37.1 and later) adds the portable `./progress` export, its strict v0 JSON schema,
 [progress observation reference](progress-snapshots.md), and supported example
 fixture. Observations preserve canonical continuation and separate Map/spec/build
 identities; consumers must not treat history presence or scope-key matching as
 readiness or trust.
 
-Candidate 1.37.0 adds the `demo` CLI command, [offline sample reference](demo-preview.md),
+1.37.0 adds the `demo` CLI command, [offline sample reference](demo-preview.md),
 a hashed `demo/apollo-v0/provenance.json` and named attribution notice. The command
 exclusively creates a new target with validated inert pages. Its internal static
 files are covered by the provenance output hashes; they are not independent
 consumer interfaces. No campaign proof or session authority is granted.
+
+The 1.38.0 candidate adds `login` and `logout` for the admitted owned-store
+private gateway pilot. It also changes `spec derive --from-store` from an
+implicit Admin-token environment variable to gateway login credentials. This
+is a breaking default change: existing direct callers must explicitly select
+`--store-token-source env:<VAR>` or migrate to an admitted gateway login. See
+[gateway login and migration](gateway-login.md). This candidate does not
+authorize publication, general merchant availability, or external client trials.

package/docs/versioning.md

@@ -2,10 +2,14 @@
 
 This repo uses independent compatibility versions:
 
-- package version: `1.34.0` — equals `surface_version` in
-  `contracts/supported-surface.json` (`check:supported-surface` enforces it)
-  and is the version published to the npm registry; `+agent.N` changelog
-  sections are same-surface changes and are not published on their own
+- package version: the `version` in `package.json`, which equals
+  `surface_version` in `contracts/supported-surface.json`
+  (`check:supported-surface` enforces it) and is the latest release published
+  to the npm registry. This document does not restate the number: read it from
+  either file, or from `npm view @nextcommerce/campaigns-os version`.
+  `+agent.N` changelog sections are same-surface changes and are not published
+  on their own; a version with a changelog section but no tag ships inside the
+  next published release
 - Build Packet: `campaign-runtime-build-packet/v0`
 - Build Context: `campaign-runtime-build-context/v0`
 - Assembly Report: `campaign-runtime-assembly-report/v0`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextcommerce/campaigns-os",
-  "version": "1.37.2",
+  "version": "1.41.2",
   "description": "Toolkit for agent-assisted NEXT campaign builds.",
   "license": "Apache-2.0",
   "repository": {
@@ -64,7 +64,7 @@
     "build:spec": "tsc -p campaign-spec/tsconfig.build.json",
     "prepare": "npm run build:spec",
     "check:spec": "node --test \"campaign-spec/test/**/*.test.ts\"",
-    "check": "npm run check:provenance && npm run check:workflows && npm run check:changelog-structure && npm run build:spec && npm run check:tests && npm run check:spec && npm run check:fixtures && npm run check:legacy-migration && npm run check:spec-conformance && npm run check:private-strings && npm run check:template-doctrine && npm run check:slot-manifest && npm run check:skill-versions && npm run check:cart-readiness && npm run check:sidecar-bundle && npm run check:supported-surface && npm run check:release-ledger && npm run check:runtime-recipe && npm run check:orientation-docs && npm run check:runtime-docs && npm run check:pack -- --skip-prepare",
+    "check": "npm run check:provenance && npm run check:workflows && npm run check:changelog-structure && npm run build:spec && npm run check:tests && npm run check:spec && npm run check:fixtures && npm run check:legacy-migration && npm run check:spec-conformance && npm run check:private-strings && npm run check:template-doctrine && npm run check:slot-manifest && npm run check:skill-versions && npm run check:cart-readiness && npm run check:sidecar-bundle && npm run check:supported-surface && npm run check:effects && npm run check:release-ledger && npm run check:runtime-recipe && npm run check:orientation-docs && npm run check:runtime-docs && npm run check:pack -- --skip-prepare",
     "check:tests": "node ./scripts/check-tests.mjs",
     "check:legacy-migration": "node ./scripts/check-legacy-migration.mjs",
     "check:fixtures": "node ./scripts/check-fixtures.mjs",
@@ -78,6 +78,7 @@
     "check:workflows": "node ./scripts/check-workflow-contracts.mjs",
     "check:skill-versions": "node ./scripts/check-skill-versions.mjs",
     "check:supported-surface": "node ./scripts/check-supported-surface.mjs",
+    "check:effects": "node ./scripts/check-effects.mjs",
     "check:release-ledger": "node ./scripts/check-release-ledger.mjs",
     "check:changelog-structure": "node ./scripts/check-changelog-structure.mjs",
     "check:orientation-docs": "node ./scripts/generate-orientation-reference.mjs --check",
@@ -88,7 +89,7 @@
     "check:sidecar-bundle": "node ./bin/campaigns-os.mjs bundle check --packet contracts/fixtures/sidecar-bundle/production-shaped/campaign-runtime.build.json --require-qa --json",
     "check:browser": "node ./scripts/check-tests.mjs --browser",
     "check:consumer": "node ./scripts/check-playwright-consumer.mjs",
-    "check:contracts": "npm run check:provenance && npm run check:workflows && npm run check:changelog-structure && npm run check:fixtures && npm run check:legacy-migration && npm run check:spec-conformance && npm run check:private-strings && npm run check:template-doctrine && npm run check:slot-manifest && npm run check:skill-versions && npm run check:cart-readiness && npm run check:sidecar-bundle && npm run check:supported-surface && npm run check:release-ledger && npm run check:runtime-recipe && npm run check:orientation-docs && npm run check:runtime-docs"
+    "check:contracts": "npm run check:provenance && npm run check:workflows && npm run check:changelog-structure && npm run check:fixtures && npm run check:legacy-migration && npm run check:spec-conformance && npm run check:private-strings && npm run check:template-doctrine && npm run check:slot-manifest && npm run check:skill-versions && npm run check:cart-readiness && npm run check:sidecar-bundle && npm run check:supported-surface && npm run check:effects && npm run check:release-ledger && npm run check:runtime-recipe && npm run check:orientation-docs && npm run check:runtime-docs"
   },
   "engines": {
     "node": ">=20.19.0"
@@ -112,15 +113,19 @@
     "contracts",
     "docs/brand-theme-bridge.md",
     "docs/build-packet.md",
+    "docs/gateway-login.md",
     "docs/campaign-build-brief.md",
     "docs/campaign-standardization-report.md",
     "docs/campaigns-os-build-flow.md",
     "docs/design-source-package.md",
+    "docs/effects.md",
     "docs/legacy-migration.md",
     "docs/migration-sidecar-bundle.md",
     "docs/orientation-contract-reference.md",
     "docs/polish-evidence.md",
     "docs/qa-and-test-orders.md",
+    "docs/readback.md",
+    "docs/skills-revision.md",
     "docs/release-ledger-authoring-guide.md",
     "docs/runtime-readiness.md",
     "docs/supported-surface.md",

package/schemas/campaign-runtime-build-packet.v0.schema.json

@@ -14,6 +14,11 @@
       "format": "date-time",
       "description": "UTC instant this packet was generated by prepare-build, ISO-8601 with a Z suffix. Optional for packets generated before it existed; always stamped on new packets. Downstream freshness (campaigns-agent readback staleness and multi-packet selection) reads this field, never file mtime."
     },
+    "campaigns_os_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$",
+      "description": "The Campaigns OS package version that prepared this packet, stamped by prepare-build. Optional for packets generated before it existed; always stamped on new packets. A bare x.y.z version (a prerelease or build suffix allowed, no `=` or `v` prefix). `tooling status` reads it as the second pin source, after the project pin (the first exact spec for @nextcommerce/campaigns-os on the walk up from the nearest package.json, devDependencies then dependencies in each, entering a workspace root and stopping there; never peerDependencies or optionalDependencies): both present and different is conflicting_pin, and this alone decides the pin when the project declares none."
+    },
     "campaign": {
       "type": "object",
       "additionalProperties": false,