@nextcommerce/campaigns-os 1.43.1 → 1.43.2

package/AGENTS.md

@@ -117,8 +117,10 @@ appends no lifecycle entry and creates no file of its own. One effect does
 precede argument refusal: `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, which is a declared effect of those commands and is
-suppressed by `--no-write`. Every remitting command's effect declaration, when
-published, names its destination as open-world, and the agent onboarding skill
+suppressed by `--no-write`. Commands implementing `--dry-run` also suppress
+that closeout whenever the flag is present, including a value that will be
+refused (such as `run end --dry-run yes`). Every remitting command's effect
+declaration, when published, names its destination as open-world, and the agent onboarding skill
 records an explicit telemetry choice before the first remitting command.
 
 1.37.0 adds `demo --target <new-directory>`, an offline visual sample

package/CHANGELOG.md

@@ -2,6 +2,457 @@
 
 Notable supported-surface changes are recorded here.
 
+## [1.43.2] - 2026-09-28
+
+### Changed
+
+- Stabilization release. Package and supported-surface version advance to
+  1.43.2 and ship every same-surface change recorded since 1.43.1
+  (`1.43.1+agent.1` through `1.43.1+agent.23`). No command, message, or exit
+  code changes in this release itself.
+- `contracts/effects.v1.json` notes for the eight `--dry-run` invocations now
+  say the command is declared `dryRun` in `src/invocation.mjs` instead of
+  naming the removed `DRY_RUN_COMMANDS` set. The declared effects are
+  unchanged.
+- The local setup install command pins the 1.43.2 package. Bundled skills
+  carry revision `1.43.2+skills.1`, with each skill version advanced one patch.
+
+## [1.43.1+agent.23] - 2026-09-28
+
+### Changed
+
+- No command behaves differently. The comment in the doctor's `route_root`
+  declaration check now uses a neutral placeholder for its near-miss route
+  examples and states the canonical form (`"/"` or `"/<public_route_slug>/"`)
+  outright. Comment-only; every message and every exit code is unchanged.
+
+## [1.43.1+agent.22] - 2026-09-28
+
+### Changed
+
+- No command behaves differently. Follow-ups the 1.43.1+agent.21 review
+  recorded: the filesystem path-identity helper the doctor's next-step picker
+  and the Design Source Package publication share moved from `src/doctor/`
+  to the shared helper module (one definition; the doctor module now imports
+  it), stale comments in the publication module that still named
+  `prepare-build` as the target-lock holder now name the publication entry
+  that holds it, the Campaign Build Brief's private JSON clone (which maps a
+  nullish brief to an empty object, unlike the shared clone) is renamed so it
+  no longer shadows the shared helper, and the CLI drops three imports
+  nothing used. Every message and every exit code is unchanged.
+
+## [1.43.1+agent.21] - 2026-09-27
+
+### Changed
+
+- No command behaves differently. Design Source Package publication for
+  `prepare-build`, `start` and `build` now has one owner instead of being
+  restated inside `prepare-build`: the pending provenance record, the target
+  lock's critical section, the output collision checks, the stage-evidence
+  re-checks and the staged publication order. The on-disk names, the
+  publication order, every message and every exit code are unchanged.
+
+## [1.43.1+agent.20] - 2026-09-27
+
+### Changed
+
+- No command behaves differently. The doctor checks, the Build Packet and
+  built-output inspection, and the next-step picker that `doctor` and `next`
+  share now live under `src/doctor/` instead of inside the CLI module. Every
+  check, its order, its messages and its exit codes are unchanged.
+- `contracts/agent-relevant-change-policy.v1.json` classifies a change under
+  `src/doctor/` as a CLI-surface change, so a later change there owes a
+  release-ledger entry. The shared helper modules `src/install-invocation.mjs`,
+  `src/cli-helpers.mjs` and `src/campaigns-api-key.mjs` are classified as
+  implementation, so a change confined to them owes a CHANGELOG section but no
+  release-ledger entry, even where a doctor message reads through them.
+- The general helpers the CLI and the doctor share (the install-aware command
+  spelling, small value and JSON-file helpers, and Campaigns API key
+  resolution) moved to their own modules under `src/`. They are internal
+  implementation, not package exports.
+- The repository's tests and performance worker import the moved functions from
+  their new modules.
+
+## [1.43.1+agent.19] - 2026-09-27
+
+### Changed
+
+- No command behaves differently. The CLI's invocation policy now has one
+  owner instead of being restated at each step: which commands run outside
+  session recovery and lifecycle capture, where the stale run-session
+  closeout runs before `start`, `prepare-build`, `build`, `run start` and
+  `run end` and what suppresses it (`--no-write`, `--no-run-session`, and
+  `--dry-run` on a command that implements it), which invocations append no
+  lifecycle entry, which commands implement `--dry-run`, and when `qa run`
+  ends its run session. Every declared effect, every argument refusal and its
+  order, and the valued `--dry-run` and bare `run` behaviours are unchanged.
+- The command list behind the did-you-mean suggestion for an unknown command
+  now comes from that same declaration instead of being read out of the
+  dispatch code's text. The list, its order and the suggestions are
+  unchanged.
+
+## [1.43.1+agent.18] - 2026-09-27
+
+### Fixed
+
+- `prepare-build` no longer loses track of a Design Source Package it
+  synthesized when the run fails or is killed after publishing the package
+  but before writing the Assembly Report that records it. Before the package
+  goes out, the run writes a pending provenance record beside it
+  (`.campaign-runtime/input/.design-source-package.json.pending-provenance.json`)
+  with the sha256 of the bytes it is publishing, and removes it once the
+  report is written. A retry that finds the record treats a package that
+  still hashes to it as `origin: "synthesized"`, so a later `--force` after a
+  manifest edit regenerates the package instead of refusing it as someone
+  else's. A `--force` regeneration keeps the replaced package's hash in the
+  record until the replacement is recorded, so a regeneration that fails or
+  dies part way leaves the package on disk provable, and a run that adopts
+  another writer's package instead of publishing drops its own candidate from
+  the record. Just before the report is published the record is narrowed to
+  the package the report records. Bytes changed since the failure, and a
+  malformed record, are not vouched for. The record's path is reserved: no
+  configurable output may point at it.
+- The `manifest_sha256` the Design Source Package records is now the hash of
+  the exact source-html manifest bytes source intake parsed. The file was
+  read twice, once to parse and once to hash, so an edit between the two
+  recorded a hash that did not describe the parsed manifest.
+- With `--map-id`, `start`, `prepare-build` and `build` still fetch the Map
+  first, but write the fetched spec to the shared
+  `.campaign-runtime/fetched-specs/<map-id>.json` cache file only once they
+  hold the per-target prepare-build lock. A run waiting for the lock could
+  previously overwrite the cache with a newer revision while the lock holder
+  was still recording it, so the holder recorded mappings from one revision
+  beside hashes of the other. Argv-only intake refusals still happen before
+  any spec read, fetch or cache write, and a failed fetch still writes
+  nothing.
+## [1.43.1+agent.17] - 2026-09-27
+
+### Fixed
+
+- The per-target lock that `prepare-build` holds, and the progress allocation
+  lock, can no longer be held by two processes at once. A process suspended
+  after creating the lock directory but before recording its owner used to
+  lose the lock to a waiter after ten seconds, and then both ran. The lock
+  directory and its owner record are now published together by one rename,
+  each holder confirms its own token before entering, and release only ever
+  removes a lock that still carries the holder's token. A lock directory with
+  no owner record, which only an older release leaves, is never taken over:
+  the command refuses it after about a second with a message naming the lock
+  directory (for progress capture, the warning now names the affected
+  `.allocation-lock`); remove it by hand once no campaigns-os process is
+  working on the target. A waiter that loses the publishing rename to a
+  holder that has already released now retries instead of failing. Do not run
+  an older release against the same target at the same time.
+- Commands that edit the Assembly Report (`doctor`, `qa run`, waivers, the
+  polish merge and the other stage producers) now take the same per-target
+  lock as `prepare-build` for their read-modify-write, so stage evidence can
+  no longer land between `prepare-build`'s final stage-evidence check and its
+  publication. A producer reached from inside `prepare-build`'s own run enters
+  without waiting on itself. A waiver `--dry-run` preview writes nothing and
+  takes no lock.
+- `prepare-build` refuses a `--out`, `--context-out`, `--report-out`,
+  `--doctor-out` or `--brief-out` path inside the lock directory
+  (`.campaign-runtime/input/.design-source-package.json.lock`) or the
+  staging and tomb directories the lock creates beside it (`.lock.staging-*`,
+  `.lock.recovery-staging-*`, `.lock.released-*`, `.lock.abandoned-*`),
+  including through a symlinked directory or a case-only alias. Such an output was written and then deleted with the lock, leaving
+  the packet and context pointing at a missing file.
+## [1.43.1+agent.16] - 2026-09-27
+
+### Fixed
+
+- QA's optional analytics comparison against a legacy funnel
+  (`--analytics-baseline`) now measures a partial build's first built page
+  when the campaign root is not part of the build or does not answer, the same
+  way the analytics correctness check has since #493. It used to measure the
+  campaign root only, which a partial build does not have. The comparison
+  records which page it measured. When no built page answers, it is skipped
+  if there was nothing to try, and blocks if every page it tried failed; in
+  both cases the legacy funnel is not loaded. An explicit
+  `--analytics-candidate` URL is still measured as given.
+- A funnel entry whose URL differs from the campaign root only by its query
+  string (for example `/campaign/?step=checkout`) is no longer treated as the
+  root. On a partial build, the root counted as built and the entry was
+  dropped as a duplicate, so the root's generic page was measured instead of
+  that entry. The entry is now measured itself and marked `query_routed`.
+  Step routing stays path-based in every certified family.
+- `docs/qa-and-test-orders.md` now describes which page the analytics checks
+  measure on a partial build, the `no_in_scope_page_captured` and
+  `no_capture_page_answered` outcomes, how query strings affect page identity,
+  and when a local-serve run turns a silent pixel into `manual_review`: a
+  recorded development render and a page measured on localhost, with
+  `data-layer-purchase` still blocking.
+## [1.43.1+agent.15] - 2026-09-27
+
+### Fixed
+
+- The doctor `built_output.script_syntax` gate and the QA `script-parse`
+  check now resolve each `<script src>` against the base in effect when the
+  parser prepares that script at its end tag: the first HTML `<base href>` in
+  tree order among those already parsed, or else the page. A `<base>` parsed
+  after a script no longer moves it, whether it is async, deferred or a
+  module, and parse order decides even when table foster parenting reorders
+  the tree. An SVG `base` no longer counts, and the href is no longer trimmed
+  of non-ASCII whitespace the URL parser keeps. Only HTML-namespace
+  `<script>` elements are page scripts: an SVG `<script src>` is no longer
+  read or parsed by doctor, and QA leaves a page with an SVG script dynamic
+  instead of fetching it. Only an empty `src` is skipped, as the browser
+  skips it; a `src` of other whitespace is resolved and read. QA recognises
+  the Campaign Cart SDK by its URL as the parser reads it, so a tab or
+  newline inside the attribute no longer makes the SDK look like an
+  unavailable config script. A base
+  the browser refuses (a `data:` or `javascript:` URL, or one that does not
+  parse) now falls back to the page, as the HTML "set the frozen base URL"
+  steps require, so the local script is read and a parse failure in it blocks
+  instead of the script being listed as unresolved (#502).
+
+### Changed
+
+- A local script a built page loads that is not in the built output is now a
+  doctor warning, `built_output.script_syntax.missing_script`, one per src
+  naming the pages that load it. It was information on the gate only. It does
+  not block. While a parse failure blocks the gate, the missing scripts stay
+  on the gate's `warned[]` (#502).
+- `fixtures/certified-families/` now carries every local script the rendered
+  pages load (each family's `js/*.js` beside `config.js`), refreshed from the
+  same templates commit. `scripts/refresh-certified-family-fixtures.mjs`
+  copies them, resolved the way the gate resolves them, and fails when a
+  referenced script is not in the render, or a copied file is a symlink or
+  resolves outside the family's render. The reachability test reads the
+  expected scripts from the HTML independently of the gate and requires the
+  gate to read exactly that set on every certified family (#502).
+## [1.43.1+agent.14] - 2026-09-27
+
+### Fixed
+
+- An accepted upsell whose mutation body loads late is now matched to the
+  request its own click made, not to any response on the order-upsells URL.
+  Every upsell step in a path posts to the same `/orders/<ref>/upsells/` URL,
+  whether the steps share a page or sit on separate pages, so an earlier
+  step's slow body could land while a later step waited for its own and be
+  judged as the later step's evidence: failing it when that body lacked its
+  line, or passing it on the earlier step's line. The runner keeps the
+  Playwright request of each captured response and of each step's mutation
+  and accepts a late body only when the two are the same request. A step
+  whose own body never arrived and that no later read-back settled is
+  unverified even when the stale lines on hand would have matched. The
+  step's mutation watch also ignores any order-upsells response whose
+  request started before the watch was armed at the click, so an earlier
+  step's response that arrives late, after its own watch expired, is no
+  longer taken as this step's.
+- A test-order path whose only open question is an unverified accepted upsell
+  is no longer `ok` on its result. The result carries `upsell_unverified`
+  instead, the order's `verification.verified` is `false` (so the purchase
+  proof summary no longer counts it in `orders_verified`; it still counts in
+  `orders_created`), and the path is neither re-run (a second order) nor
+  passed through read-only recovery (which cannot re-check an upsell). The
+  `browser-test-order` assertion still reports it as `manual_review`. A path
+  with an unverified upsell and another failure is recovered as before, but
+  a recovery that clears the other failure leaves the upsell unverified: the
+  result goes to `manual_review`, not `pass`, and the order stays unverified.
+## [1.43.1+agent.13] - 2026-09-27
+
+### Changed
+
+- The lifecycle effects tests now prove that `start`, `prepare-build` and
+  `build` refuse a bare, empty or whitespace `--template-family`,
+  `--allow-uncertified-template`, `--theme-policy` or `--brief`, and an
+  unsupported `--theme-policy`, before the CampaignSpec is looked at. The
+  earlier refusal tests seeded a valid spec, so a check that ran after the
+  spec was read would still have passed them. The new cases make the local
+  `--spec` file and the `--cached-spec` cache file missing, a directory, or
+  malformed JSON, and require the flag refusal with no journal entry, no fetch
+  and an unchanged tree. The tree snapshot these tests compare now lists
+  directories as well as files, so a refusal that only creates an empty
+  directory is caught too. Tests only; CLI behavior is unchanged (#504).
+
+## [1.43.1+agent.12] - 2026-09-26
+
+### Fixed
+
+- QA no longer blocks every local proof run on analytics. Under
+  `deploy.target: local-serve` the build renders the development environment,
+  which leaves out the vendor loaders on purpose, so a declared pixel could
+  never fire on localhost. When the run is served from localhost and the build
+  recorded `stages.assembly.evidence.build_environment: development`, the tag,
+  out-of-band vendor and receipt Purchase (`purchase-fires`) checks that did
+  not fire on a page measured on localhost are now `manual_review` with the
+  reason `local_serve_development_render` instead of blockers. Each one says
+  to re-run QA against the PR preview with `--base-url <preview-url>`, which
+  is a production render and still gates them, and cites the recorded
+  `page-kit parity` result when there is one. A production build, or a build
+  with no recorded environment, keeps its blockers on localhost. The exception
+  covers only pages measured on localhost: the tracking capture now records
+  the page URL it settled on after redirects (`final_url`), and a capture that
+  landed on another host, such as a built entry page whose URL is a production
+  preview or a localhost root that redirects to production, keeps its
+  blockers. So does a receipt Purchase check whose receipt page is not on
+  localhost, judged both by the order's final URL and by the page URL read
+  after the receipt's analytics settled (`receipt_document_url`), so a
+  localhost receipt that redirects to a hosted page while analytics settle
+  keeps its blocker, as does any check whose measured page was not recorded.
+  So does a capture that failed: a `purchase-fires` failure that lists
+  unmeasured receipts in `capture_error_plan_ids` still blocks, and a tracking
+  capture whose page could not be read (for example, a page that reloaded
+  while the capture read it) now fails as the analytics runner blocker instead
+  of reading as a page where nothing fired. The data-layer Purchase
+  check (`data-layer-purchase`) still blocks too: the SDK pushes `dl_purchase`
+  in the development render as well.
+
+## [1.43.1+agent.11] - 2026-09-26
+
+### Fixed
+
+- `start`, `prepare-build` and `build` now refuse a bare, empty or
+  whitespace-only `--template-family`, `--allow-uncertified-template`,
+  `--theme-policy` or `--brief`, and a `--theme-policy` other than
+  `inspect_only`, `auto` or `off`, before reading the spec, fetching the Map or
+  writing the spec cache. Before, these four were read only after the spec was
+  resolved: a blank value was quietly ignored (or, for `--theme-policy`, fell
+  back to `inspect_only`), and an unknown theme policy failed partway through
+  intake and was journaled as a handler failure. A refused invocation writes
+  no journal entry. Whether a named family is certified, and whether a named
+  brief can be read, still depend on file content, so those failures are still
+  journaled.
+## [1.43.1+agent.10] - 2026-09-26
+
+### Fixed
+
+- Browser QA no longer hangs on an upsell accept when the page moves on before
+  the upsell response body has loaded. The runner read that body with no time
+  limit, and a page that redirected as soon as the response headers arrived
+  could leave the read waiting forever. The read now gives up after a few
+  seconds: the step still reports the response and its status, with no order
+  body, and records that the read timed out. Checkout event capture keeps its
+  unbounded read, since nothing waits on it: an order body that loads late
+  still counts as order evidence.
+- A slow but successful upsell accept is no longer failed as "no new upsell
+  line". When the upsell body read times out on a successful response, the
+  step waits up to 15 seconds, inside its own time budget, for the late body
+  or an order read-back that shows the accepted line. If neither arrives, the
+  upsell is reported as unverified and the test order goes to manual review,
+  not to a blocker. A late body, or an order read-back captured after the
+  click, that lacks the line still fails.
+## [1.43.1+agent.9] - 2026-09-26
+
+### Fixed
+
+- Doctor no longer reports a build ready when a campaign script has a syntax
+  error. Every doctor run that sees built output, `doctor --built` and the
+  packet path alike, now parses each campaign-owned `.js` file a built page
+  loads by a local `<script src>`, and blocks under
+  `built_output.script_syntax.parse_failure` when one does not parse. The error
+  names the file, line and column, for example a hand-edited checkout script
+  left with one closing `});` too many. Remote scripts such as CDN URLs are not
+  read, `type="module"` scripts are parsed as modules, and classic `nomodule`
+  scripts are skipped. Script types are read as the browser reads them, trimmed
+  of surrounding whitespace and case-insensitive, and a module script is parsed
+  even when it carries `nomodule`, since the browser still runs it. Script paths resolve against the page's `<base href>` and are
+  percent-decoded, as the browser loads them. The gate is not waivable and
+  passes on every certified starter family.
+- QA no longer reads a page script that does not parse as "dynamic". The
+  credential binding treats its declarations as unavailable, and QA adds a
+  `script-parse:<page_id>` blocker naming the script, line and column. Both
+  report a fixed diagnostic category, never text from the script. QA
+  classifies script types the same way doctor does.
+## [1.43.1+agent.8] - 2026-09-26
+
+### Fixed
+
+- `prepare-build --force` (and `start --force` and `build --force`) now
+  regenerates a stale Design Source Package that an earlier `prepare-build`
+  synthesized, instead of refusing it. Previously, editing the source manifest
+  after a first run left `.campaign-runtime/input/design-source-package.json`
+  stale, and every rerun failed until the file was deleted by hand, with nothing
+  in the output saying so. The Assembly Report now records the package's
+  `origin` (`synthesized` or `adopted`), and a package counts as the producer's
+  own only when that report says `synthesized` and the bytes on disk still match
+  its hash. A package placed by an operator, edited by hand, or recorded by an
+  older report is still refused, `--force` or not. Every refusal now names the
+  file and the recovery: rerun with `--force` for the producer's own package,
+  otherwise reconcile it or delete it and rerun.
+- The manifest docs now say up front that a source-html manifest `pages[]`
+  entry with both `path` and `skip_reason` is invalid.
+## [1.43.1+agent.7] - 2026-09-26
+
+### Fixed
+
+- QA's analytics tracking check works on partial builds. It used to capture the
+  campaign root (`/<slug>/`) even when the build starts deeper, such as at
+  `checkout/`, so it read an empty page and failed every declared pixel as
+  absent. On a partial build the root now counts as in scope only when a
+  built, in-scope page is served there, so a host's directory index or
+  generic fallback at the root is never measured. When the root is out of
+  scope, answers with a non-2xx status, or fails to load (a navigation timeout
+  or network error), the check captures the first built in-scope page, the same entry partial-scope QA starts from, and records the
+  page it used and why on the `analytics-correctness:capture` evidence. If the
+  build has no capturable page at all, the check is skipped with the reason
+  `no_in_scope_page_captured`. If pages existed but none answered 2xx or
+  loaded at all, the check fails as a blocker with the reason `no_capture_page_answered` and
+  lists each attempt, because the declared vendors went unmeasured.
+
+## [1.43.1+agent.6] - 2026-09-26
+
+### Fixed
+
+- Browser QA no longer misses the upsell accept on a control that pulses
+  forever, such as a stock `pb-animate="pulse-upsell"` button. The runner used
+  to wait about 30 seconds for the control to settle before scrolling to it and
+  another 10 before forcing the click, so the upsell POST landed after its
+  20-second watch had expired. That reported `api_response_seen: false` for an
+  accept that had worked, and could time out deep accept paths. Controls are now
+  scrolled into view without a settle wait, a control that animates forever is
+  clicked straight away, and the watch starts at the click. Cart-entry,
+  package-card, checkout-submit and text-matched clicks use the same bounded
+  scroll.
+
+## [1.43.1+agent.5] - 2026-09-26
+
+### Fixed
+
+- Payment-logo residue checks ignore starter `payment-logos.html` logos that
+  are still `hidden`. The template hides each method's logo until the campaign
+  offers it, so doctor and browser QA no longer flag PayPal or Klarna on pages
+  built from the new templates. A logo left visible is still checked; when a
+  page forces one on, doctor's warning points at the `payment_flags.show_<method>`
+  frontmatter flag.
+
+## [1.43.1+agent.4] - 2026-09-26
+
+### Fixed
+
+- Partial-build QA skips recorded, unbuilt out-of-scope pages with explicit
+  `out_of_build_scope` evidence and starts at the first in-scope page. Built
+  stock pages rejoin QA; missing in-scope pages still fail. Commercial checks
+  share the same scope as HTTP and browser checks.
+- Build handoffs keep skipped routes unbuilt by default. Materializing a stock
+  stand-in requires explicit per-page operator opt-in, so upstream pages on
+  another host are not replaced with placeholder copy.
+## [1.43.1+agent.3] - 2026-09-26
+
+### Fixed
+
+- Legacy direct-API QA rejects missing or unusable carts and unknown test-order
+  modes before resolving campaign inputs, without appending a lifecycle entry.
+  Browser QA precedence and legacy API credential checks are unchanged.
+
+## [1.43.1+agent.2] - 2026-09-26
+
+### Fixed
+
+- `run end --dry-run yes` now refuses the valued flag without closing a stale
+  session first. No Run Record, lifecycle entry, remit, or session deletion
+  occurs. Bare `--dry-run` and ordinary run closeout keep their existing behavior.
+
+## [1.43.1+agent.1] - 2026-09-25
+
+### Fixed
+
+- Doctor recognizes numeric package, shipping and offer references exported by
+  the Map, so declared commerce IDs no longer trigger false undeclared-package
+  blockers or starter-demo warnings. Reference fallback fields now use the same
+  string-or-finite-number rule; other types are ignored instead of stringified.
+
 ## [1.43.1] - 2026-09-24
 
 ### Fixed

package/README.md

@@ -198,8 +198,8 @@ are template stock instead — no bespoke design, the starter family *is* the
 design — there is no screenshot to honestly supply. Declare those pages out of
 source scope (a manifest `skip_reason` entry, or CampaignSpec
 `build_scope.mode: "partial"`): intake records them as template stock, demands
-no design source for them, and the build stage materialises each from the
-locked family's own page. A family that publishes Template Reference proof
+no design source for them, and leaves them unbuilt unless the operator opts in
+per page to materializing the locked family's stock. A family that publishes Template Reference proof
 (today `apollo`) covers them with `template_baseline`; every other family
 records an accepted Source Gap and intake lands at `ready_with_gaps`. See
 [Template-stock pages: the family decides](docs/design-source-package.md#template-stock-pages-the-family-decides).

package/contracts/agent-relevant-change-policy.v1.json

@@ -67,6 +67,11 @@
       "class": "cli_surface",
       "_note": "The agent-facing entry points (skill install, agent context, the tooling-status revision check) are reachable from the supported argv surface, so a change under src/agent/ is a CLI-surface change even though the rest of src/ is unsupported implementation. This rule sits ahead of the broad src/ ignore on purpose: the ignore's reason is 'implementation reachable only through declared package exports', which is exactly what this subtree is not."
     },
+    {
+      "match": { "kind": "prefix", "value": "src/doctor/" },
+      "class": "cli_surface",
+      "_note": "Doctor checks are kernel-declared behavior reachable from the supported argv surface (`doctor`, `next`, `start`, `prepare-build` and `qa run` read them), so a change under src/doctor/ is a CLI-surface change even though the rest of src/ is unsupported implementation. This rule sits ahead of the broad src/ ignore on purpose, as the src/agent/ rule does. The shared helper modules beside it under src/ (src/install-invocation.mjs, src/cli-helpers.mjs, src/campaigns-api-key.mjs) remain implementation under the broad src/ ignore."
+    },
     {
       "match": { "kind": "prefix", "value": "agents/" },
       "class": "documentation",

package/contracts/effects.v1.json

@@ -236,7 +236,7 @@
       "sends": [],
       "effect_test": "effects: page-kit sync --dry-run",
       "test_scope": "full",
-      "notes": "page-kit sync --dry-run runs every check the real invocation runs and prints what it would do; it writes nothing under the target, appends no lifecycle entry (DRY_RUN_COMMANDS) and runs no stale-session closeout."
+      "notes": "page-kit sync --dry-run runs every check the real invocation runs and prints what it would do; it writes nothing under the target, appends no lifecycle entry (the command is declared `dryRun` in src/invocation.mjs) and runs no stale-session closeout."
     },
     {
       "command": "spec",
@@ -255,7 +255,7 @@
       "sends": [],
       "effect_test": "effects: spec derive --dry-run",
       "test_scope": "full",
-      "notes": "spec derive --dry-run runs every check the real invocation runs and prints what it would do; it writes nothing under the target, appends no lifecycle entry (DRY_RUN_COMMANDS) and runs no stale-session closeout."
+      "notes": "spec derive --dry-run runs every check the real invocation runs and prints what it would do; it writes nothing under the target, appends no lifecycle entry (the command is declared `dryRun` in src/invocation.mjs) and runs no stale-session closeout."
     },
     {
       "command": "install-skills",
@@ -274,7 +274,7 @@
       "sends": [],
       "effect_test": "effects: install-skills --dry-run",
       "test_scope": "full",
-      "notes": "install-skills --dry-run runs every check the real invocation runs and prints what it would do; it writes nothing under the target, appends no lifecycle entry (DRY_RUN_COMMANDS) and runs no stale-session closeout."
+      "notes": "install-skills --dry-run runs every check the real invocation runs and prints what it would do; it writes nothing under the target, appends no lifecycle entry (the command is declared `dryRun` in src/invocation.mjs) and runs no stale-session closeout."
     },
     {
       "command": "install-agent-context",
@@ -293,7 +293,7 @@
       "sends": [],
       "effect_test": "effects: install-agent-context --dry-run",
       "test_scope": "full",
-      "notes": "install-agent-context --dry-run runs every check the real invocation runs and prints what it would do; it writes nothing under the target, appends no lifecycle entry (DRY_RUN_COMMANDS) and runs no stale-session closeout."
+      "notes": "install-agent-context --dry-run runs every check the real invocation runs and prints what it would do; it writes nothing under the target, appends no lifecycle entry (the command is declared `dryRun` in src/invocation.mjs) and runs no stale-session closeout."
     },
     {
       "command": "qa",
@@ -312,7 +312,7 @@
       "sends": [],
       "effect_test": "effects: qa publish --dry-run",
       "test_scope": "full",
-      "notes": "qa publish --dry-run runs every check the real invocation runs and prints what it would do; it writes nothing under the target, appends no lifecycle entry (DRY_RUN_COMMANDS) and runs no stale-session closeout. Local-spec packets are refused before publication because they have no saved Map destination."
+      "notes": "qa publish --dry-run runs every check the real invocation runs and prints what it would do; it writes nothing under the target, appends no lifecycle entry (the command is declared `dryRun` in src/invocation.mjs) and runs no stale-session closeout. Local-spec packets are refused before publication because they have no saved Map destination."
     },
     {
       "command": "checkpoint",
@@ -331,7 +331,7 @@
       "sends": [],
       "effect_test": "effects: checkpoint waive --dry-run",
       "test_scope": "full",
-      "notes": "checkpoint waive --dry-run runs every check the real invocation runs and prints what it would do; it writes nothing under the target, appends no lifecycle entry (DRY_RUN_COMMANDS) and runs no stale-session closeout."
+      "notes": "checkpoint waive --dry-run runs every check the real invocation runs and prints what it would do; it writes nothing under the target, appends no lifecycle entry (the command is declared `dryRun` in src/invocation.mjs) and runs no stale-session closeout."
     },
     {
       "command": "theme",
@@ -350,7 +350,7 @@
       "sends": [],
       "effect_test": "effects: theme waive --dry-run",
       "test_scope": "full",
-      "notes": "theme waive --dry-run runs every check the real invocation runs and prints what it would do; it writes nothing under the target, appends no lifecycle entry (DRY_RUN_COMMANDS) and runs no stale-session closeout."
+      "notes": "theme waive --dry-run runs every check the real invocation runs and prints what it would do; it writes nothing under the target, appends no lifecycle entry (the command is declared `dryRun` in src/invocation.mjs) and runs no stale-session closeout."
     },
     {
       "command": "run-record",
@@ -369,7 +369,7 @@
       "sends": [],
       "effect_test": "effects: run-record --dry-run",
       "test_scope": "full",
-      "notes": "run-record --dry-run runs every check the real invocation runs and prints what it would do; it writes nothing under the target, appends no lifecycle entry (DRY_RUN_COMMANDS) and runs no stale-session closeout."
+      "notes": "run-record --dry-run runs every check the real invocation runs and prints what it would do; it writes nothing under the target, appends no lifecycle entry (the command is declared `dryRun` in src/invocation.mjs) and runs no stale-session closeout."
     },
     {
       "command": "run-record",