@nextcommerce/campaigns-os 1.37.3 → 1.43.1

package/CHANGELOG.md

@@ -2,6 +2,714 @@
 
 Notable supported-surface changes are recorded here.
 
+## [1.43.1] - 2026-09-24
+
+### Fixed
+
+- Restamp the local setup install command to the 1.43.1 package and check its
+  documented toolkit pin against `package.json` during CI.
+- In 1.42.1, `run end` journaled several inherited flag refusals that 1.41.x
+  refused without a journal entry, including unknown `--surfaces` and valued
+  `--dry-run`. `run end` and `run-record` now refuse bare, empty, or
+  whitespace-only values for every value-taking inherited run-record flag
+  before packet work. The agent token and elapsed-time flags keep their integer
+  diagnostics; unknown `--surfaces` and valued `--dry-run` are refused. `run end`
+  also refuses `--new-run` and `--run-id`, since the saved session fixes its run
+  ID. `run-record` also refuses bare, empty, or whitespace-only `--run-id` and
+  valued `--new-run`. These argv-only refusals append no lifecycle entry.
+- `start`, `prepare-build`, and `build` refuse bare, empty, or whitespace-only
+  values of `--spec`, `--map-id`, `--source`, `--target`, `--source-kind`,
+  `--proxy-base`, `--wrapper-policy`, `--design-manifest`, and
+  `--order-path-depth` before local spec reads, Map fetches, or cache writes on
+  the `--spec`, `--map-id`, and `--map-id --cached-spec` paths.
+- Internal stale-session and QA closeouts retain their prior handling of
+  inherited flags. A bare, empty, or whitespace-only `--proxy-base` on a
+  sweeping command still writes the stale session's Run Record. Terminal QA
+  still auto-ends with a whitespace-only inherited `--context`, `--report`, or
+  `--proxy-base`; a whitespace-only `--context` resolves as a literal relative
+  path, so the default context file is not read. Bare or empty `--context` or
+  `--report` still makes QA auto-end fail and leaves the session open. A bare
+  or empty `--qa-verdict` still fails a Run Record closeout when inherited;
+  QA auto-end supplies its own verdict path.
+- Correct the 1.42.1 note: QA with a named packet yielding no Map ID after
+  checkpoint preflight changed from a refusal to a journaled handler failure
+  in that release; it did not *remain* journaled. A named packet now satisfies
+  QA identity with a Map ID or a valid local-spec identity. If preflight yields
+  neither or finds conflicting local and Map identities, QA journals a handler
+  failure.
+
+### Changed
+
+- Package and supported-surface version advance to 1.43.1. Bundled skills
+  carry revision `1.43.1+skills.1`, with each skill version advanced one patch.
+
+## [1.43.0+agent.4] - 2026-09-24
+
+### Fixed
+
+- Run Record validation and its schema treat a null `local_spec_id` as absent,
+  preserving saved-Map records and best-effort capture with partial identity.
+  Non-null malformed or conflicting local IDs still fail before persistence.
+
+## [1.43.0+agent.3] - 2026-09-24
+
+### Fixed
+
+- Invalid campaign identities cannot select prior doctor history, including
+  when a malformed local ID would otherwise leave a Map-only or unfiltered
+  lookup. Such findings retain unknown cause instead of borrowing evidence.
+- Integrate the 1.42.1 argument-refusal fixes: local-spec packet QA remains
+  supported, while identity failures discovered from packet content remain
+  journaled handler failures. Advance bundled skill versions beyond 1.42.1.
+
+## [1.43.0+agent.2] - 2026-09-24
+
+### Fixed
+
+- Evidence identity projection and Run Record writes reject malformed or
+  conflicting local IDs instead of propagating them. Doctor keeps malformed
+  input diagnosable with `spec.local_identity`; saved-Map errors retain their
+  existing code and normalization. Local IDs remain exact canonical tokens.
+- Declare the optional local progress identity inline without mutating the
+  portable schema after construction.
+
+## [1.43.0+agent.1] - 2026-09-24
+
+### Fixed
+
+- Entry-point and QA instructions distinguish saved-Map builds from local-spec
+  builds, including local verdict storage, evidence identity and publication
+  suppression. Bundled QA and evidence skills follow the same distinction.
+- Page Kit sync and spec derivation retain the saved-Map mismatch diagnostic
+  while refusing mismatched local identities before writes.
+
+## [1.43.0] - 2026-09-24
+
+### Added
+
+- Agent-authored CampaignSpecs can use a stable `spec_identity.local_spec_id`
+  instead of a saved Map. Preparation preserves that identity in packets and
+  reports; doctor, polish, QA, progress, readback and run closeout distinguish it
+  from both the public route and saved Map identity. Material hashes continue
+  to bind each spec revision, including across fresh checkouts.
+- Packet-based local QA writes full verdicts and committed sidecars with the
+  local ID, refuses foreign or stale local reports, and never publishes them to
+  the Map portal. `qa publish` refuses local-spec packets. Existing saved-Map
+  workflows retain their identity and publication behavior.
+- Local setup and intake instructions let the coding agent author the spec
+  from prepared HTML, a brief and verified configured commerce. Existing
+  certification, source, runtime, polish and checkout proof gates still apply.
+
+## [1.42.1] - 2026-09-24
+
+### Fixed
+
+- `start`, `prepare-build`, and `build` now refuse missing or invalid argument
+  values for source, target, source kind, wrapper policy, design-manifest value,
+  and order-path depth before spec resolution or preparation. `run-record`
+  refuses conflicting `--new-run`/`--run-id` and invalid agent token counts
+  before reading its packet or journal. These argv-only refusals append no
+  lifecycle entry.
+- `qa run` and `qa resolve` refuse empty campaign selectors and selector flags
+  without values before checkpoint or site reads. Built-site QA also refuses
+  missing `--base-url` or `--family` before scanning the site. An unknown
+  `next` stage refuses before the handler reads the packet or runs doctor,
+  names the accepted stages (`setup`, `build`, `polish`, `deploy`, `qa`), and
+  appends no lifecycle entry. The `next` help line now shows those stages.
+- Three state-dependent decisions remain journaled handler failures: `polish
+  capture` when `packet.assembly.target_repo` does not resolve to a local target
+  repo; `run end` with no packet in argv or the saved session; and `qa run` or
+  `qa resolve` with a named packet that yields no Map ID after checkpoint
+  preflight. The polish check currently cannot fire through the CLI because
+  the workspace resolver supplies a local path. Separately, a named design
+  manifest that is missing, not a file, or invalid is a journaled handler
+  failure. A nested run-record refusal during `run end` or QA auto-closeout
+  stays within the closeout attempt, so it does not turn the invoking command's
+  journal verdict into a refusal. The ambient run-session lookup may still
+  read a named `--packet` before the handler runs.
+
+### Changed
+
+- Package and supported-surface version advance to 1.42.1. The bundled skills
+  carry revision `1.42.1+skills.1`, with each skill version advanced one patch
+  so an agent can detect instructions loaded from an older release.
+
+## [1.42.0+agent.2] - 2026-09-24
+
+### Fixed
+
+- The effects guide names both `qa install-browser` and `tooling setup` as
+  browser downloaders, matching the declared effects contract.
+
+## [1.42.0+agent.1] - 2026-09-24
+
+### Fixed
+
+- Setup recovery preserves an existing project's dependency choices instead
+  of recommending a fixed page-kit version. New projects use the install
+  instructions bundled with the release.
+- Setup explicitly confines managed destinations to the selected project;
+  regression coverage proves files and dangling symlinks cannot stand in for
+  context directories.
+- Receipt-analytics deadline tests advance a controlled clock after entering
+  the phase under test, avoiding a CI scheduling race between settle and capture.
+
+## [1.42.0] - 2026-09-23
+
+### Added
+
+- `tooling setup --target <campaign-directory> --platform claude` composes the
+  existing skill, project context and QA-browser installers after checking the
+  selected project's exact toolkit pin and installed page-kit dependency.
+  npm installs the dependencies first; setup runs from the project copy through
+  `npx --no-install campaigns-os`. It preserves campaign pages and existing
+  project instructions, appends the Claude context import once, and refuses
+  conflicting pins, edited context and symlink destinations before writes.
+  `--dry-run` writes nothing and downloads no browser. Browser-install failure
+  reports an incomplete setup that can be rerun. Setup bypasses campaign-session
+  recovery, gateway credential reads, lifecycle capture and telemetry.
+- Bundled local-setup guide documents the initial npm install, context import,
+  browser step and required agent restart. Setup reports `restart_required`;
+  installation is not proof that an agent loaded the matching skill revision.
+
+### Changed
+
+- Skills bundle revision `1.42.0+skills.1`; each bundled skill version advances
+  one patch so a session holding previous instructions must restart.
+- Declared effects include setup and its read-only dry run. Offline effects
+  tests cover every campaign-session/consent condition; browser archive download
+  remains preflight-proved, alongside focused preservation and recovery tests.
+
+## [1.41.2] - 2026-09-23
+
+### Fixed
+
+- Every command Campaigns OS prints for a project-local install is spelled
+  `npx --no-install campaigns-os …`, and so is every command in the bundled
+  skills, the README, `AGENTS.md` and the docs. 1.41.1 made this change only
+  for the revision check in the skill header. `campaigns-os` is only the bin
+  name of `@nextcommerce/campaigns-os`. In a folder where the package is not
+  installed (another folder, or one where `npm install` has not run yet), a
+  plain `npx campaigns-os …` looks the bin name up as a registry package and,
+  with no terminal to ask, installs whatever it finds and runs it. With
+  `--no-install`, npx runs the pinned copy or stops with an error.
+  - For a `node_modules` install, `tooling status` reports
+    `cli.invocation_prefix` as `npx --no-install campaigns-os` and
+    `cli.invocation` as `npx --no-install campaigns-os <command>`.
+  - Every command spelled with that prefix follows: `next` text and `--json`,
+    doctor required actions, gate and checkpoint remediations, the
+    skill-refresh and gateway login actions of `tooling status`, and the
+    browser-missing hints.
+  - The PATH warnings of `tooling status` and its action for a stale project
+    pin name the same spelling.
+  - A checkout, a global install and an npx cache keep their spellings.
+  - Run-session deviation tracking reads the command word through the new
+    prefix, and still through the old one in sessions recorded by earlier
+    versions.
+
+  Commands printed or documented by earlier releases lack the flag; add
+  `--no-install` after `npx` when you reuse one.
+- Skills bundle revision `1.41.2+skills.1`. Every skill's version advances by
+  one patch.
+
+## [1.41.1] - 2026-09-23
+
+### Fixed
+
+- `tooling status` without `--platform` or `--target` checks skill freshness
+  only on the platform directories where Campaigns OS skills are installed. A
+  directory counts when a skill sits under one of the bundled names or under a
+  retired name when it is our own copy. Before this, a Claude Code only install (the
+  documented path) was read as stale for Codex and the shared directory, so
+  the revision check the skills ask for exited 2 and printed an action to
+  install skills for every platform. Now:
+  - A `Ready:` line names the skipped platforms.
+  - The refresh action names each stale installed platform (`install-skills
+    --platform claude`), or `--platform all` when all three are installed and
+    stale.
+  - When no platform has Campaigns OS skills, the action asks for an install
+    on the harness in use (`install-skills --platform claude`, with `codex` and
+    `agents` named as the alternatives)
+    rather than on all three.
+  - `--platform all` still checks every platform.
+  - `--json` adds `skills.scope` (`requested`, `installed_platforms` or
+    `no_platform_installed`) and `skills.not_installed_platforms`.
+  - `tooling diagnose` forwards `--platform` only when one is given, and its
+    export reports the unnamed scope as `platform: installed`.
+  - The gateway login hint uses the printed invocation prefix.
+- Every bundled skill header now tells the agent to run the check as `npx
+  --no-install campaigns-os tooling status --skills-revision <revision>` from
+  the campaign's Page Kit folder. There it runs the project's pinned copy, and
+  it never installs one. The header change fixes two problems:
+  - A bare `campaigns-os` resolves through PATH. On a machine with an older
+    global install, a copy from before 1.40.0 answers instead. That copy
+    ignores `--skills-revision`, prints no `Skills revision:` line, and lists
+    an `install-skills --platform all` action. Following it replaces five of
+    the nine bundled skills with older text. The revision comparison cannot
+    see that result; only the pinned copy's freshness check reports it.
+  - `campaigns-os` is only the bin name of `@nextcommerce/campaigns-os`.
+    Outside a pinned folder, a plain `npx campaigns-os` looks the bin name up
+    as a registry package, and with no terminal to ask, it would install
+    whatever it found.
+
+  The header also says that output with no `Skills revision:` line (no
+  `revision_check` under `--json`) did not come from the pinned copy, and that
+  none of its actions should be followed. `docs/skills-revision.md`, the
+  README, the quickstart and `docs/diagnostics.md` describe the new
+  behaviour.
+- Refusals that happen before a command's first effect are tagged, so they
+  write no lifecycle journal entry (campaigns-os#465). This covers:
+  - `theme waive` without `--reason`, or with a waiver attribution it rejects
+    (a missing or placeholder `--waived-by`, or a bad `--expires-at`).
+  - `qa waive` without `--assertion`, with an assertion outside the waiver
+    lane, or without `--reason`.
+  - `qa policy set` with a removed flag, a string flag given no value, a
+    non-boolean `--allowed-domains-confirmed`, or an unsupported
+    `--order-path-depth`.
+
+  Every other plain throw in `src/cli.mjs` and `src/qa-node.mjs` was reviewed
+  against the rule in `docs/effects.md` and left as a journaled handler
+  failure. Those throws follow a read of the target (spec, source, report,
+  session state or built site), an effect, or a request, or they are internal
+  defect checks. Each newly tagged site has a refusal-table row in
+  `src/lifecycle-effects.test.mjs`. Each touched handler has a positive
+  control: the same invocation, when it passes every refusal and then fails,
+  still appends exactly one entry. No effects row changes.
+- Skills bundle revision `1.41.1+skills.1`. Every skill's version advances by
+  one patch.
+
+## [1.41.0] - 2026-09-23
+
+### Added
+
+- `tooling status` reports the pin checks (ADR 0002, campaigns-os#466): one
+  executable per project. The project pin — the first exact
+  `@nextcommerce/campaigns-os` spec (`x.y.z`, `=x.y.z` or `vx.y.z`) in
+  `devDependencies`, then `dependencies`, of each `package.json` walking up from
+  the working directory, through manifests that name nothing, to the workspace
+  root — comes first; a range counts only
+  when no exact spec exists on that walk, and `peerDependencies` /
+  `optionalDependencies` are never a pin. The Build Packet's recorded kernel
+  version comes second (the project's `campaign-runtime.build.json`, or
+  `--packet <path>`). `--json` carries `pin: { source, version, running,
+  status, range, packet_version, packet_version_ignored, project_version,
+  project_manifest, project_key, forced, message }` and the text view a `Pin:` line under the
+  skills revision line. The line names, for every status, the key and manifest
+  of each project version or range it quotes (`devDependencies in
+  <project>/package.json`), the nearest manifest when there is no project pin,
+  and the packet file of each packet version it quotes; every action names the
+  manifest and key to change; a packet value with an `=` or `v` prefix is
+  named as ignored (`packet_version_ignored`), not as absent. An installed
+  package's own manifest (`node_modules/<name>` or `node_modules/@<scope>/<name>`)
+  is never the project, so a run from inside an install resolves the enclosing
+  project, while a project whose own path passes through a `node_modules`
+  directory still resolves its own manifest; a leading BOM is accepted, and an
+  unreadable or malformed ancestor manifest ends the walk with a warning.
+  `pin.status` is `match`; `stale_pin` (the pin is not the
+  running version); `conflicting_pin` (both sources present and different); or
+  `unpinned` (neither present — a range or tag is not a pin and is reported
+  under `range`). `stale_pin` and `conflicting_pin` exit 2 with an action
+  naming the file to change; `unpinned` exits 0 and is always reported.
+- `tooling status --force`: a bare flag that overrides `stale_pin` and
+  `conflicting_pin`, so the command exits as the rest of the status dictates.
+  The override is reported as `pin.forced: true` and recorded on the
+  command-lifecycle journal entry through `argv_shape`. `--force true` is
+  refused. Declared as its own row in `contracts/effects.v1.json`
+  (`effects: tooling status --force`, 92 rows): it changes the exit status only
+  and writes nothing the plain row does not.
+- Build Packet: optional top-level `campaigns_os_version` (a bare `x.y.z` version) in
+  `schemas/campaign-runtime-build-packet.v0.schema.json`, stamped by
+  `prepare-build` with the version that prepared the packet. Additive: the
+  packet schema stays `campaign-runtime-build-packet/v0`, and packets without
+  the field stay valid (they are no packet pin source).
+
+### Changed
+
+- `docs/skills-revision.md`: the "Not yet built" section is replaced by the pin
+  check as built — sources and precedence, the four statuses, exit codes,
+  `--force`, and JSON and text output from real runs. The `tooling status` help
+  line gains `[--packet <campaign-runtime.build.json>] [--force]`.
+- `tooling status` refuses `--no-force` up front (`--force` is bare and off by
+  default), journaling nothing, where the shared parser had let it pass as a
+  no-op; and an empty or whitespace-only project spec is absent, never a
+  `range`.
+- Skills: `bundle_revision` moves to `1.41.0+skills.1` with the package
+  version, and every bundled skill's `Bundle revision:` header and its
+  `--skills-revision` instruction follow (each skill version patch-bumped).
+- `contracts/supported-surface.json`: `surface_version` 1.41.0, with the
+  sha256 of the hashed `contracts/effects.v1.json` and
+  `schemas/campaign-runtime-build-packet.v0.schema.json` entries recomputed. No
+  entry, command, export or bin moved.
+- `package.json` and `package-lock.json`: version 1.41.0; no dependency moved.
+- `docs/orientation-contract-reference.md` and `docs/runtime-readiness.md`:
+  regenerated for surface version 1.41.0.
+
+## [1.40.0] - 2026-09-22
+
+### Added
+
+- `contracts/effects.v1.json`: the declared effect of every supported
+  invocation — 91 rows, one per command, per subcommand and per effect-changing
+  flag, stating what the invocation **writes** (with location tokens, so a write
+  to your home directory or your machine config is not mistaken for a write to
+  the campaign) and what it **sends**, alongside the four MCP-style annotations
+  (`readOnlyHint`, `destructiveHint`, `openWorldHint`, `idempotentHint`) and an
+  effect tier (`none` < `B` writes < `A` sends < `C` destructive). One row is
+  not a command: `{"command": "*refused*"}` declares what an invocation refused
+  before its handler runs costs. Its shape is published as
+  `schemas/campaigns-os-effects.v1.schema.json` and its prose as
+  `docs/effects.md`.
+- Every row is proved by a case in `src/effects.test.mjs`, which runs the real
+  CLI in a disposable target under five conditions — no run session, an active
+  ambient session, a session idle past the 12 h TTL,
+  `CAMPAIGNS_OS_LIFECYCLE_LOG`, and **Run Telemetry consent persisted for a
+  loopback receiver's scope** — snapshotting the whole tree (paths plus sha256)
+  before and after while a loopback receiver counts requests. The assertion runs
+  both ways: nothing the row does not declare may change in any condition, and
+  every declared effect whose `observed_in` names a condition must be seen in
+  it. The fifth condition is the one that does not take the row's word for
+  whether consent is on — under the other four, consent is switched on only for
+  rows that declare a consent-gated send, so a send nobody declared ran with
+  consent off and left no trace. It is also what pins the send declarations of
+  `next`, its five stage forms and the three `qa run` rows, each of which POSTs
+  under persisted consent: the stage progress observation to
+  `{proxy-base}/api/progress`, and for `qa run` the verdict to
+  `{proxy-base}/api/qa/verdicts`, on blocked attempts included. 79 rows are
+  proved end to end; 12 whose command cannot execute past its preflight offline
+  (`login`, `logout`, `page-kit parity`, `polish capture`,
+  `qa install-browser`, `qa parity`, `qa parity --no-post-verdict`,
+  `qa resolve`, `qa run --browser`, `spec derive --from-store`,
+  `spec derive --write-map`, `telemetry list`) carry `test_scope: "preflight"`
+  and a `preflight` allowance
+  — the exact paths the refusal may write and the exact request paths it may
+  contact — so a home-directory write or an undeclared endpoint fails the row
+  even when the row declares that path or destination for its success path.
+- `npm run check:effects` (`scripts/check-effects.mjs`, in `npm run check` and
+  `npm run check:contracts`): every command on the supported CLI surface, every
+  subcommand **any** help block teaches **and every effect-changing flag a help
+  usage line carries** (`vocabulary.effect_changing_flags`) has a row. "Any help
+  block" is the point: `campaigns-os qa` prints its own from `src/qa-node.mjs`,
+  and a scan that read only `src/cli.mjs` never required a row for the three
+  subcommands documented there alone — `qa parity`, `qa waive` and
+  `qa install-browser`, all three of which the QA skill tells an agent to run.
+  Every module that owns a usage block is now scanned, and a test derives that
+  list from the source so a command that grows its own help cannot leave the
+  scan quietly. Beyond that: every row names
+  the test case the per-row generator gives it and has argv in the test's
+  invocation table; every effect the offline fixture cannot reach states why;
+  every preflight row declares allowances that name no whole location and no
+  home-directory subtree; every declared condition is one the suite runs; and
+  the annotations have to agree with the row. **A row without its test is not
+  publishable, and a flag without its row is not either.**
+
+- `skills.json` carries `bundle_revision` (`1.40.0+skills.1`, spelled
+  `<package version>+skills.<n>`): one identity for the five bundled skills
+  together, stated on the first body line of every `SKILL.md` as
+  `Bundle revision: 1.40.0+skills.1`. It exists because a skill's text enters an
+  agent's context once and is never re-read, while the CLI underneath that
+  session can be replaced by an `npm install`, an `npx` cache refresh or a
+  `git pull` — an agent following one release's instructions against another
+  release's CLI. `<n>` is a counter, not a semver component, and resets with the
+  prefix, so `1.41.0+skills.1` is ahead of `1.40.0+skills.7`. Every bundled skill
+  is versioned up in this release (the header line changed in all five), and each
+  kernel command a skill names now carries its declared effect class from
+  `contracts/effects.v1.json` in one short parenthetical.
+- `campaigns-os tooling status --skills-revision <bundle-revision|skill-id@version>`
+  compares the value an agent read against the bundle revision of the CLI the
+  command runs from. `--json` reports `revision_check` as `match`, `mismatch` or
+  `unchecked` beside a `skills_revision` object (`requested`, `spelling`,
+  `on_disk`, `on_disk_skill`, `message`); the text view prints one named header
+  line — `Skills revision: match (1.40.0+skills.1)`, `Skills revision: mismatch:
+  loaded 1.39.0+skills.1, on disk 1.40.0+skills.1 — start a fresh session`, or
+  `Skills revision: unchecked (on disk 1.40.0+skills.1)`. A mismatch prints the
+  **full** status and then exits `2`, and adds an action naming the remedy: a
+  fresh session, because re-running cannot refresh skill text already in
+  context. That asymmetry is why the reported revision is named `on_disk` — the
+  requested value is what you are still reading, the reported one is what is
+  installed and is the side that moved. `<skill-id>@<version>` is accepted as a
+  fallback for an agent carrying only one skill's frontmatter, and a skill id
+  this bundle does not ship reports `mismatch` rather than refusing. The flag is
+  refused when given without a value. Prose: `docs/skills-revision.md`.
+- `scripts/check-skill-versions.mjs` gains the bundle gate. Without `--base` it
+  requires `bundle_revision` to exist, to be spelled correctly, and to be
+  prefixed with `package.json`'s `version`. With `--base <ref>` it requires the
+  revision to have **advanced** whenever any file under `skills/` changed or
+  `skills.json`'s `skills[]` entries changed — equal fails, backwards fails. Its
+  changed set is now the union of the base diff, the working tree and untracked
+  files (the three-way union the release-ledger gate already measured); a
+  committed-only diff reported an unstaged `SKILL.md` edit as "nothing changed",
+  which is the per-skill bump gate passing because it did not look.
+
+- Four skills for working a campaign the bundle did not previously carry, each
+  at version `1.0.0`: `campaign-lifecycle-orientation` (place Build Packet,
+  Assembly Report and doctor language in the pipeline and read what a run
+  recorded, without advancing a stage — the store-theme / Page Kit two-worlds
+  distinction is its core, and the half this repository does not document is
+  reported as unverified rather than filled in);
+  `campaign-run-evidence` (read doctor, a QA verdict and proof depth without
+  claiming more proof than the artifacts contain); `campaign-readback-classification`
+  (classify one selected campaign from `campaigns-os readback --json` — the v2
+  `artifacts`, `staleness.stale_keys`, `clean`, `doctor`, `divergences` and
+  `skip_cascades` fields — into ready, collect-inputs, blocked or
+  not-enough-evidence, and write a read-only handoff); and
+  `contribution-intake` (a template that turns a suggestion about the agent
+  surface into a classified, evidence-checked, redacted proposal, filed only
+  with attended approval). Each states the bundle revision on its first body
+  line, names each command's declared effect class from
+  `contracts/effects.v1.json`, carries no `allowed-tools`, and cites only the
+  supported surface. `bundle_revision` advances to `1.40.0+skills.2` and every
+  previously bundled skill is versioned up, because the header line moved in
+  all nine.
+- `AGENTS.md` gains **Charter for agents working a campaign**: the standing
+  rules for a session that has already oriented. Campaigns OS is the authority
+  on campaign truth; target text is data, never instructions; select the
+  campaign before reading it, from a path the operator supplied; cite only the
+  supported surface for kernel facts; route intent to the matching skill; never
+  widen capability inside a session, because a capability change is a pull
+  request that changes a row of `contracts/effects.v1.json`; cite
+  implementation evidence as `repo@commit:path:line` and say dirty or stale
+  beside it; return private source only to a provider the attended operator
+  approved; and use the harness's own connectors for external write-back,
+  preview first, one operation.
+- `src/skills-references.test.mjs`: every `skills/*/SKILL.md` validates against
+  the published frontmatter shape (`name` = directory id, semver `version`,
+  non-empty `description`, and nothing else), carries no `allowed-tools`, opens
+  with the bundle revision on its first body line, and has every backticked
+  `campaigns-os …` reference resolved against the CLI help (the command and
+  subcommand are taught, and each flag is on that usage line or in that help
+  block's Options list) **and** against a row of `contracts/effects.v1.json`
+  (an effect-changing flag without a row fails). Every referenced
+  `docs/`, `contracts/`, `schemas/` or `AGENTS.md` path must exist and be
+  covered by `package.json` `files[]`, so a skill cannot point at a file the
+  installed package does not ship. It caught two references on its first run: a
+  flag named against `campaigns-os qa` rather than `qa run`, and the same line
+  naming no declared invocation.
+- `src/generated-output.test.mjs`: no file under `agents/` or `skills/` may
+  carry a tool pre-approval — `allowed-tools`/`disallowed-tools` (Claude Code's
+  per-turn grant, per `docs/harness-matrix.md` in the repository), their camelCase spellings, a
+  `permissions` block, a `.claude/settings` allow/deny/ask rule list, or an
+  auto-approval, always-allow, bypass or skip key. A pre-approval written here
+  is fixed at publish time and cannot see the operator, target or session that
+  decide whether an invocation is acceptable: this repository declares what a
+  command does, and granting permission to run it belongs to the harness and
+  its operator. Each pattern is exercised against a sample that must fail it,
+  so a regex that stopped matching cannot leave the guard green.
+
+### Changed
+
+- `contracts/agent-relevant-change-policy.v1.json` classifies three more paths.
+  `contracts/effects.v1.json` is `compatibility_policy`. The `agents/` prefix is
+  `documentation` — it was ignored as "illustrative" while nothing consumed it,
+  and the four per-platform instruction files are now named supported surface.
+  The `src/agent/` prefix is `cli_surface`, declared ahead of the subtree
+  existing and ahead of the broad `src/` ignore, so its first change cannot be
+  born unclassified.
+- `contracts/supported-surface.json` advances to `1.40.0` and adds
+  `contracts/effects.v1.json` and `schemas/campaigns-os-effects.v1.schema.json`
+  as hashed entries, plus `docs/effects.md` and the four `agents/**` files as
+  named entries.
+
+## [1.39.0] - 2026-09-22
+
+### Added
+
+- `campaigns-os readback <target-repo-root> [--json] [--packet <path>]
+  [--doctor <path>] [--context <path>] [--report <path>] [--qa-verdict <path>]
+  [--findings <path>]`: a read-only projection of the artifacts a run has
+  already emitted into a target — the Build Packet, doctor output, build
+  context, assembly report, QA verdict and findings export. It reports each
+  artifact's state, per-artifact freshness against the checkout's HEAD reflog,
+  doctor warning grouping, fail-to-skip cascades and cross-artifact
+  divergences. The command writes nothing under the target, starts no process,
+  touches no network, and records no lifecycle entry even when a journal is
+  configured; exit `0` for any projection it can form, `2` for a request that
+  cannot form one (missing target root, a Build Packet set freshness cannot
+  single out, `--example` combined with a target or an override).
+- Output contract `campaigns-os-readback/v2`, published as
+  `schemas/campaigns-os-readback.v2.schema.json` with prose in
+  `docs/readback.md`: field semantics, the exact `clean` rule, exit codes, and
+  the migration for a consumer that read the previous projection. Staleness is
+  assessed **per artifact** — `staleness.artifacts` carries each loaded
+  artifact's own verdict, `staleness.stale_keys` names the stale ones in render
+  order, and the aggregate `staleness.stale` is true when ANY loaded artifact
+  is stale. The earlier projection compared only the newest artifact, so one
+  freshly regenerated artifact reported a whole stale set as fresh and
+  `clean: true`; that is a change of meaning in a published field, hence the
+  new schema version rather than an edit in place. `newest_key` is kept as
+  information only and `artifact_times` is unchanged. An artifact that recorded
+  a `generated_at` this readback cannot parse has an age it never established,
+  so it is not left to a fresh sibling to speak for: `staleness.unparseable_keys`
+  names such artifacts in render order, their artifact rows carry the shape of
+  the refused value (never the value itself), the text view lists them under
+  `*** UNKNOWN ARTIFACT AGE ***`, and `clean` is false whenever that list is
+  non-empty. `computable` and `stale` keep their meanings, and an artifact with
+  no `generated_at` key at all is unchanged — it recorded no age to check, so it
+  stays out of the comparison and is not by itself unclean.
+- `campaigns-os readback --example [--json]` projects the synthetic sample
+  bundled at `contracts/fixtures/sidecar-bundle/production-shaped/` with no
+  target argument. The sample is a packaged fixture directory rather than a Git
+  checkout, so it reports freshness as not computable by design and
+  `clean: false`; artifact rows are package-relative so the sample's output is
+  identical wherever it is installed.
+- `--dry-run` on the four mutating commands that lacked it: `run-record`,
+  `qa publish`, `checkpoint waive` and `theme waive`. Each one does everything
+  the real command does except the write and the send, and exits as the real
+  command would: every validation on the route from argv to the first effect
+  runs under the flag, by the same code and with the same message and exit
+  code, including the ones that live inside the effect itself — the Run Record
+  validator that refuses a record before it is written, the committing path's
+  check on what a waiver mutator returns, and the transport's destination gate.
+  A dry run therefore never previews an invocation that could not have
+  happened. `run-record --dry-run` assembles the Run Record and prints it
+  (`--json`: `dry_run: true`, `would_write`, `would_remit`, and
+  `would_remit_refused` naming the gate's refusal when the proxy base is one
+  the transport declines before any request) without writing the file or
+  remitting — where `--no-write` skips the assembly's reads as well; an invalid
+  record is refused with the writer's own message and exit 1; `run end` hands
+  the flag on and leaves the run session open. `qa publish --dry-run` runs
+  every refusal check (stale `spec_hash`, already published, untrusted,
+  campaign mismatch) and reports `status: "dry_run"` with `would_publish` and
+  `would_post` (endpoint, base kind, verdict run id, payload bytes) instead of
+  posting; a refusal still exits 2, and a `--proxy-base` the transport refuses
+  before it opens a socket (a non-URL, or plain http to anything but a loopback
+  host) still reports `publish_failed` and exits 1. `checkpoint waive
+  --dry-run` and `theme waive --dry-run` run the same validation (named human,
+  bounds, registered and waivable gate) through the committing path itself over
+  the same Assembly Report — one that is torn, or that is not an Assembly
+  Report object, is refused identically on both paths — and report the waiver
+  they would record with `would_write`, leaving the report and the doctor
+  sidecar untouched. No `--dry-run`
+  invocation writes under the target and none opens a network connection. That
+  covers the command-lifecycle journal, which the commands that implement the
+  flag skip the way doctor's inspection mode does, and the pre-dispatch
+  stale-session sweep, which such an invocation skips entirely instead of
+  assembling, remitting and deleting an idle session behind the flag: a stale
+  session is left on disk for a real invocation to close out, so `run end
+  --dry-run` at a root whose only session is stale reports `No active run
+  session to end` rather than a closeout. Both exemptions are scoped to the
+  commands that implement the flag: the shared parser accepts `--dry-run` on
+  any command, and one that does not implement it (`qa run`, say) records its
+  lifecycle entry, sweeps as usual, and behaves exactly as before.
+
+### Changed
+
+- Supported surface 1.39.0: `cli_commands` gains `readback`, `hashed{}` gains
+  `schemas/campaigns-os-readback.v2.schema.json`, and `named[]` gains
+  `docs/readback.md`. Additive — no existing command, schema, export or
+  document changed.
+## [1.38.0+agent.2] - 2026-09-22
+
+### Fixed
+
+- `--no-write` now writes nothing, the lifecycle journal included. A command run
+  with `--no-write` no longer appends its command-lifecycle entry, whether the
+  journal was selected by `--lifecycle-journal`, by `CAMPAIGNS_OS_LIFECYCLE_LOG`
+  or by an active run session; previously `run status --no-write` under an
+  ambient session created `.campaign-runtime/command-lifecycle.jsonl` in the
+  target (issue #459). Capture still happens in process; only the append is
+  skipped, so no command's output or exit status changes.
+- A refused invocation (unknown command, an unknown subcommand refused before
+  its handler runs, or a flag the command refuses up front) writes nothing of
+  its own. `frobnicate`, `tooling statuss`, `qa publishh` and `standardize
+  --dryrun` are rejected with the same message and exit status as before, and
+  now record no lifecycle entry and create no file of their own under the
+  target, with or without `--no-write`, with or without a run session, and with
+  `CAMPAIGNS_OS_LIFECYCLE_LOG` set. A typo can no longer materialize a journal.
+  A command that fails INSIDE its handler — `qa run` with a missing packet, or
+  `next <unknown-stage>`, which resolves the workspace before it rejects the
+  stage — still journals, as before.
+- Scope note, not a change: `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. That closeout — Run Record assembled and remitted
+  under the usual consent, session file cleared — is a declared effect of those
+  commands, so a refused invocation of one of them can still perform it. It is
+  the only effect that precedes refusal.
+- `--no-write` now also suppresses that stale-session closeout. Previously the
+  flag was inherited by the closeout (no Run Record was written) but the stale
+  session file was removed anyway, so `--no-write` did not leave the tree
+  byte-identical; it now does, and the stale session is left for the next run
+  that writes. A `run end --no-write` whose only session at the root is stale
+  therefore reports no active session to end instead of reporting a closeout it
+  did not perform.
+- `run status` is read-only: it never sweeps stale sessions and never appends a
+  lifecycle entry, with or without `--no-write`. The help text says so.
+- Unchanged: a known command run without `--no-write` under an active run
+  session still journals to the session's journal, and `doctor`'s existing
+  inspection rule still applies.
+
+### Added
+
+- `docs/harness-matrix.md`: where each agent harness reads instruction files,
+  skills, plugin manifests and MCP servers. Claude Code, Codex and Cursor cells
+  cite first-party vendor documentation (verified 2026-09-22); every other cell
+  is marked `unverified`. The preamble states what "first-party" and "tested"
+  mean, names the two first-release skill placements (`.claude/skills`,
+  `.agents/skills`), and records that Codex lists a same-name skill found in two
+  directories twice.
+- `AGENTS.md` now states the Run Telemetry default in one place: remit is on by
+  default for the canonical endpoint and the CLI announces it on stderr the
+  first time a process remits; capture is local and opt-in (a journal selected
+  by flag, by env or by an active run session); `campaigns-os telemetry off`,
+  `CAMPAIGNS_OS_TELEMETRY=off` or per-command `--no-remit` turn remit off.
+
+## [1.38.0+agent.1] - 2026-09-21
+
+### Changed
+
+- Correct the packaged `next-campaigns-os` skill step 5 to use gateway login
+  credentials by default for store derivation within the admitted owned-store
+  private pilot. Existing direct Admin callers must explicitly select
+  `--store-token-source env:<VAR>`; there is no implicit environment lookup or
+  fallback after gateway failure. Bump this skill to 1.0.18 and align its manifest.
+  This documents the 1.38.0 migration already implemented; no runtime behavior,
+  package version or supported-surface version changes.
+
+## [1.38.0] - 2026-09-21
+
+### Added
+
+- `login [--store <subdomain>]` and `logout [--store <subdomain>]` for the
+  admitted owned-store gateway pilot. Browser consent saves gateway credentials
+  in the user keychain or private user files outside the project. Failed login
+  preserves the prior login. Logout reports local cleanup separately from
+  confirmed remote revocation.
+- Local-only gateway metadata in `tooling status`: saved store bindings,
+  access expiry and reported gateway version, with no credential values.
+
+### Changed
+
+- **Breaking:** `spec derive --from-store` now defaults to gateway credentials.
+  Existing direct Admin callers must explicitly pass
+  `--store-token-source env:<VAR>` using their existing variable, or use an
+  admitted gateway login. The explicit direct path warns that it bypasses
+  gateway custody; a gateway failure never falls back to it.
+- Gateway reads preserve the nine-field Store Profile derivation rules and
+  identify the actual transport endpoint alongside the logical upstream source.
+  Refresh is serialized and durably marked before consumption; an uncertain
+  refresh requires login rather than replay on the next invocation.
+- Document the migration, storage recovery, separate telemetry admin key and
+  pilot limits. This is a release candidate: publication, general merchant
+  rollout and external client trials remain separately gated.
+
+## [1.37.3+agent.1] - 2026-09-19
+
+### Changed
+
+- Stop restating the package version in prose. `docs/versioning.md` said the
+  package version was `1.34.0` while `package.json` and
+  `contracts/supported-surface.json` said `1.37.3`; the gate compares those two
+  files to each other, never to the sentence, so the literal rotted through
+  four releases. The document now says where the number lives (`package.json`,
+  `surface_version`, or `npm view @nextcommerce/campaigns-os version`) and
+  states the rule that a version with a changelog section but no tag ships
+  inside the next published release. No number to drift.
+- Stop calling 1.36.0 a candidate. `docs/progress-snapshots.md`, `AGENTS.md`
+  and `docs/supported-surface.md` still described the progress export as
+  "candidate 1.36.0", and the progress reference said the published install
+  example did not include it. 1.36.0 was never tagged on its own; its surface
+  ships in 1.37.1 and every later release, and the wording now says so, as the
+  1.37.2+agent.1 pass already did for 1.37.0. (#457)
+
 ## [1.37.3] - 2026-09-19
 
 ### Changed