@nextcommerce/campaigns-os 1.41.2 → 1.43.1

package/CHANGELOG.md

@@ -2,6 +2,184 @@
 
 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

package/README.md

@@ -5,8 +5,8 @@ Campaigns OS is the developer toolkit for agent-assisted campaign builds on [Nex
 This toolkit gives campaign developers and AI coding tools a clear path for assembling one from prepared page files:
 
 1. Configure the campaign in the Next Commerce dashboard (Campaigns App).
-2. Create or review the Campaign Map in [Campaign Map Builder](https://campaign-map.nextcommerce.com).
-3. Export a local CampaignSpec JSON.
+2. Use the current saved Map in [Campaign Map Builder](https://campaign-map.nextcommerce.com), or have the coding agent author a [local CampaignSpec](docs/build-packet.md#local-spec-entry) from the brief and verified campaign values.
+3. Keep the CampaignSpec JSON with its saved Map ID or stable `local_spec_id`, plus its public route slug.
 4. Bring prepared HTML/CSS/assets for the campaign pages.
 5. Provide or generate a [Campaign Build Brief](./docs/campaign-build-brief.md) for merchandising/design presentation decisions.
 6. Create and doctor a Build Packet.
@@ -119,7 +119,9 @@ npx --no-install campaigns-os next --packet ./campaign-runtime.build.json --json
 
 `--map-id <id>` starts from a map saved in Campaign Map Builder (add
 `--proxy-base <origin>` when the map was saved on a non-production map store);
-`--spec <campaignspec.json>` starts from a local export instead. `--source` is
+`--spec <campaignspec.json>` starts from a local export or an agent-authored
+[local spec](docs/build-packet.md#local-spec-entry) instead. Local-spec identity
+requires a reviewed 1.43.0-or-later release. `--source` is
 always required: the folder of prepared HTML/CSS/assets for the pages you are
 building, with a source manifest that carries desktop and mobile screenshot
 proof for each designed page
@@ -228,7 +230,7 @@ Then ask your AI tool to continue from the emitted handoff. Fresh target repos u
 
 ## Source Files
 
-The current source adapter is `html_funnel`: bring prepared HTML/CSS/assets for the campaign pages, plus a local exported CampaignSpec from Campaign Map Builder.
+The current source adapter is `html_funnel`: bring prepared HTML/CSS/assets for the campaign pages, plus a CampaignSpec exported from Campaign Map Builder or authored by the coding agent through the [local-spec entry](docs/build-packet.md#local-spec-entry).
 
 For raw AI-generated or exported static HTML, "prepared" means page-kit-ready
 source, not a browser document dropped in unchanged and not a wholesale Liquid

package/agents/claude/CLAUDE.md

@@ -1,6 +1,10 @@
 # Campaigns OS Agent Context
 
-You are helping assemble a NEXT campaign through Campaigns OS. Start from the Build Packet, not from private runtime source.
+You are helping assemble a NEXT campaign through Campaigns OS. Use the
+`next-campaigns-os` skill from this project's pinned toolkit. When a Build
+Packet exists, read it and follow `next`. Check the loaded skill's bundle
+revision and restart the session if it differs from the
+project copy. Do not use private runtime source as the campaign's starting point.
 
 Core rules:
 

package/campaign-spec/dist/types.d.ts

@@ -593,6 +593,8 @@ export interface AnalyticsContract {
  * local-experimental.
  */
 export interface SpecIdentity {
+    /** Stable agent-authored identity when there is no saved Map. */
+    local_spec_id?: string;
     map_id?: string;
     source?: string;
     id?: string;

package/contracts/effects.v1.json

@@ -1,7 +1,7 @@
 {
   "schema": "campaigns-os-effects/v1",
   "_note": "The declared effect of every supported invocation: what it writes, what it sends, and the test case that proves it. One row per command, per subcommand and per effect-changing flag (vocabulary.effect_changing_flags). A row is not publishable without its effect test — scripts/check-effects.mjs refuses one, and refuses a flag from that list that a help usage line carries and no row declares. Read this with docs/effects.md.",
-  "contract_version": "1.1.0",
+  "contract_version": "1.2.0",
   "vocabulary": {
     "annotations": {
       "readOnlyHint": "The invocation changes nothing: no file under the target, the working directory or the user's machine, and no request off the machine. The command-lifecycle journal counts — a journal append is a write like any other, so every readOnlyHint: true row is an invocation the CLI exempts from lifecycle capture (the converse does not hold: some journal-exempt invocations, such as demo and the --no-write forms, still write other declared files).",
@@ -26,7 +26,7 @@
       "{proxy-base}": "The endpoint --proxy-base names, or the canonical NEXT endpoint when it does not.",
       "{base-url}": "The campaign under test, as --base-url names it or as the packet derives it.",
       "{map-id}": "The saved Map the CampaignSpec identifies.",
-      "{playwright-download-host}": "Where Playwright fetches browser builds from: PLAYWRIGHT_DOWNLOAD_HOST when set, else the Playwright CDN (cdn.playwright.dev). The one destination in this file that is not a Campaigns OS endpoint — `qa install-browser` is the one supported invocation that downloads from a third party."
+      "{playwright-download-host}": "Where Playwright fetches browser builds from: PLAYWRIGHT_DOWNLOAD_HOST when set, else the Playwright CDN (cdn.playwright.dev). The third-party browser download used by `qa install-browser` and `tooling setup`."
     },
     "conditions": {
       "no_session": "No run session at the target or the working directory.",
@@ -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."
+      "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."
     },
     {
       "command": "checkpoint",
@@ -2066,7 +2066,7 @@
         {
           "destination": "{proxy-base}/api/qa/verdicts",
           "what": "the QA verdict for the attempt, published to the QA portal",
-          "when": "publish is not opted out (--no-post-verdict) and the consent seam allows it — Run Telemetry consent on for the endpoint, or a portal-managed campaign",
+          "when": "publish is not opted out (--no-post-verdict) and the consent seam allows it — Run Telemetry consent on for the endpoint, or a portal-managed campaign; never for a local-spec packet",
           "requires_consent": true,
           "observed_in": [
             "persisted_consent"
@@ -2091,7 +2091,7 @@
         {
           "destination": "{proxy-base}/api/progress",
           "what": "the stage progress observation — the snapshot just captured locally, POSTed under X-Campaign-Key",
-          "when": "Run Telemetry consent is on for the endpoint, --no-remit was not given, and the packet's campaign key resolves",
+          "when": "Run Telemetry consent is on for the endpoint, --no-remit was not given, and the packet's campaign key resolves; never for a local-spec packet",
           "requires_consent": true,
           "observed_in": [
             "persisted_consent"
@@ -2100,7 +2100,7 @@
       ],
       "effect_test": "effects: qa run",
       "test_scope": "full",
-      "notes": "Destructive and not idempotent: each attempt overwrites the committed verdict sidecar and the report's QA stage, and a ready verdict clears the ambient run session. It SENDS on a blocked attempt too: the verdict is published to {proxy-base}/api/qa/verdicts and the QA stage progress observation to {proxy-base}/api/progress, both under persisted consent for the endpoint. Publishing rides the telemetry consent seam rather than a flag of its own, so the four consent-off conditions saw neither request."
+      "notes": "Destructive and not idempotent: each attempt overwrites the committed verdict sidecar and the report's QA stage, and a ready verdict clears the ambient run session. It SENDS on a blocked attempt too: the verdict is published to {proxy-base}/api/qa/verdicts and the QA stage progress observation to {proxy-base}/api/progress, both under persisted consent for the endpoint. Publishing rides the telemetry consent seam rather than a flag of its own, so the four consent-off conditions saw neither request. Local-spec packets retain verdicts in the repository and never send a QA verdict or progress to the Map portal, even with --post-verdict."
     },
     {
       "command": "qa",
@@ -2191,7 +2191,7 @@
         {
           "destination": "{proxy-base}/api/qa/verdicts",
           "what": "the QA verdict for the attempt, published to the QA portal",
-          "when": "publish is not opted out (--no-post-verdict) and the consent seam allows it — Run Telemetry consent on for the endpoint, or a portal-managed campaign",
+          "when": "publish is not opted out (--no-post-verdict) and the consent seam allows it — Run Telemetry consent on for the endpoint, or a portal-managed campaign; never for a local-spec packet",
           "requires_consent": true,
           "observed_in": [
             "persisted_consent"
@@ -2216,7 +2216,7 @@
       ],
       "effect_test": "effects: qa run --no-remit",
       "test_scope": "full",
-      "notes": "The base `qa run` row's writes, without any remit: --no-remit stops the progress observation and the Run Record remit. The verdict publish is NOT a remit and is not gated by the flag — it still posts to the QA portal under the consent seam, which --no-post-verdict is the opt-out from."
+      "notes": "The base `qa run` row's writes, without any remit: --no-remit stops the progress observation and the Run Record remit. The verdict publish is NOT a remit and is not gated by the flag — it still posts to the QA portal under the consent seam, which --no-post-verdict is the opt-out from. Local-spec packets retain verdicts in the repository and never send a QA verdict or progress to the Map portal, even with --post-verdict."
     },
     {
       "command": "qa",
@@ -2323,7 +2323,7 @@
         {
           "destination": "{proxy-base}/api/progress",
           "what": "the stage progress observation — the snapshot just captured locally, POSTed under X-Campaign-Key",
-          "when": "Run Telemetry consent is on for the endpoint, --no-remit was not given, and the packet's campaign key resolves",
+          "when": "Run Telemetry consent is on for the endpoint, --no-remit was not given, and the packet's campaign key resolves; never for a local-spec packet",
           "requires_consent": true,
           "observed_in": [
             "persisted_consent"
@@ -2332,7 +2332,7 @@
       ],
       "effect_test": "effects: qa run --no-post-verdict",
       "test_scope": "full",
-      "notes": "The base `qa run` row's writes, without the verdict publish: --no-post-verdict is the opt-out from posting the verdict to the QA portal. The progress observation is a separate delivery and still leaves under persisted consent; --no-remit is the flag that stops that one."
+      "notes": "The base `qa run` row's writes, without the verdict publish: --no-post-verdict is the opt-out from posting the verdict to the QA portal. The progress observation is a separate delivery and still leaves under persisted consent; --no-remit is the flag that stops that one. Local-spec packets retain verdicts in the repository and never send a QA verdict or progress to the Map portal, even with --post-verdict."
     },
     {
       "command": "qa",
@@ -2423,7 +2423,7 @@
         {
           "destination": "{proxy-base}/api/qa/verdicts",
           "what": "the QA verdict for the attempt, published to the QA portal",
-          "when": "publish is not opted out (--no-post-verdict) and the consent seam allows it — Run Telemetry consent on for the endpoint, or a portal-managed campaign",
+          "when": "publish is not opted out (--no-post-verdict) and the consent seam allows it — Run Telemetry consent on for the endpoint, or a portal-managed campaign; never for a local-spec packet",
           "requires_consent": true,
           "observed_in": [
             "persisted_consent"
@@ -2448,7 +2448,7 @@
         {
           "destination": "{proxy-base}/api/progress",
           "what": "the stage progress observation — the snapshot just captured locally, POSTed under X-Campaign-Key",
-          "when": "Run Telemetry consent is on for the endpoint, --no-remit was not given, and the packet's campaign key resolves",
+          "when": "Run Telemetry consent is on for the endpoint, --no-remit was not given, and the packet's campaign key resolves; never for a local-spec packet",
           "requires_consent": true,
           "observed_in": [
             "persisted_consent"
@@ -2457,7 +2457,7 @@
       ],
       "effect_test": "effects: qa run --test-order",
       "test_scope": "full",
-      "notes": "The most consequential row in the file: --test-order places REAL orders against the store under test. Destructive, open-world, not idempotent. It SENDS on a blocked attempt too: the verdict is published to {proxy-base}/api/qa/verdicts and the QA stage progress observation to {proxy-base}/api/progress, both under persisted consent for the endpoint. Publishing rides the telemetry consent seam rather than a flag of its own, so the four consent-off conditions saw neither request."
+      "notes": "The most consequential row in the file: --test-order places REAL orders against the store under test. Destructive, open-world, not idempotent. It SENDS on a blocked attempt too: the verdict is published to {proxy-base}/api/qa/verdicts and the QA stage progress observation to {proxy-base}/api/progress, both under persisted consent for the endpoint. Publishing rides the telemetry consent seam rather than a flag of its own, so the four consent-off conditions saw neither request. Local-spec packets retain verdicts in the repository and never send a QA verdict or progress to the Map portal, even with --post-verdict."
     },
     {
       "command": "qa",
@@ -2548,7 +2548,7 @@
         {
           "destination": "{proxy-base}/api/qa/verdicts",
           "what": "the QA verdict for the attempt, published to the QA portal",
-          "when": "publish is not opted out (--no-post-verdict) and the consent seam allows it — Run Telemetry consent on for the endpoint, or a portal-managed campaign",
+          "when": "publish is not opted out (--no-post-verdict) and the consent seam allows it — Run Telemetry consent on for the endpoint, or a portal-managed campaign; never for a local-spec packet",
           "requires_consent": true,
           "observed_in": [
             "persisted_consent"
@@ -2573,7 +2573,7 @@
         {
           "destination": "{proxy-base}/api/progress",
           "what": "the stage progress observation — the snapshot just captured locally, POSTed under X-Campaign-Key",
-          "when": "Run Telemetry consent is on for the endpoint, --no-remit was not given, and the packet's campaign key resolves",
+          "when": "Run Telemetry consent is on for the endpoint, --no-remit was not given, and the packet's campaign key resolves; never for a local-spec packet",
           "requires_consent": true,
           "observed_in": [
             "persisted_consent"
@@ -2582,7 +2582,7 @@
       ],
       "effect_test": "effects: qa run --browser (preflight)",
       "test_scope": "preflight",
-      "notes": "PREFLIGHT-PROVED: --browser needs an installed Chromium and a reachable campaign, neither of which exists offline. The case proves the attempt is blocked at the same gate as the node run and writes exactly the blocked-attempt evidence. It SENDS on a blocked attempt too: the verdict is published to {proxy-base}/api/qa/verdicts and the QA stage progress observation to {proxy-base}/api/progress, both under persisted consent for the endpoint. Publishing rides the telemetry consent seam rather than a flag of its own, so the four consent-off conditions saw neither request.",
+      "notes": "PREFLIGHT-PROVED: --browser needs an installed Chromium and a reachable campaign, neither of which exists offline. The case proves the attempt is blocked at the same gate as the node run and writes exactly the blocked-attempt evidence. It SENDS on a blocked attempt too: the verdict is published to {proxy-base}/api/qa/verdicts and the QA stage progress observation to {proxy-base}/api/progress, both under persisted consent for the endpoint. Publishing rides the telemetry consent seam rather than a flag of its own, so the four consent-off conditions saw neither request. Local-spec packets retain verdicts in the repository and never send a QA verdict or progress to the Map portal, even with --post-verdict.",
       "preflight": {
         "may_write": [
           "{target}/qa-output/**",
@@ -2637,7 +2637,7 @@
       ],
       "effect_test": "effects: qa publish",
       "test_scope": "full",
-      "notes": "Posts an already-stored verdict without a re-run and without an order. It is NOT gated by Run Telemetry consent — the publish is the operator's explicit act."
+      "notes": "Posts an already-stored verdict without a re-run and without an order. It is NOT gated by Run Telemetry consent — the publish is the operator's explicit act. Local-spec packets are refused before publication because they have no saved Map destination."
     },
     {
       "command": "qa",
@@ -2679,7 +2679,7 @@
       ],
       "effect_test": "effects: qa publish --republish",
       "test_scope": "full",
-      "notes": "--republish lifts the already-published refusal: the same POST to the QA portal for a verdict that was already delivered. Not destructive locally — nothing under the target is overwritten — and not gated by Run Telemetry consent."
+      "notes": "--republish lifts the already-published refusal: the same POST to the QA portal for a verdict that was already delivered. Not destructive locally — nothing under the target is overwritten — and not gated by Run Telemetry consent. Local-spec packets are refused before publication because they have no saved Map destination."
     },
     {
       "command": "qa",
@@ -4789,6 +4789,99 @@
         "may_write": [],
         "may_contact": []
       }
+    },
+    {
+      "command": "tooling",
+      "subcommand": "setup",
+      "flags": [],
+      "annotations": {
+        "readOnlyHint": false,
+        "destructiveHint": false,
+        "openWorldHint": true,
+        "idempotentHint": true
+      },
+      "tier": "A",
+      "writes": [
+        {
+          "path": "{target}/.campaign-runtime/agent-context/*",
+          "when": "the four bundled context files are installed after preservation preflight",
+          "observed_in": [],
+          "not_observed_reason": "The offline preflight fails the browser download before shared skills or project files are changed. Existing installer effects are proved in their own rows; focused setup tests cover composition and preservation."
+        },
+        {
+          "path": "{target}/.gitignore",
+          "when": "the managed runtime ignore block is absent",
+          "observed_in": [],
+          "not_observed_reason": "The offline preflight fails the browser download before shared skills or project files are changed. Existing installer effects are proved in their own rows; focused setup tests cover composition and preservation."
+        },
+        {
+          "path": "{target}/CLAUDE.md",
+          "when": "the context import is absent; preserve all existing text and append the import once",
+          "observed_in": [],
+          "not_observed_reason": "The offline preflight fails the browser download before shared skills or project files are changed. Existing installer effects are proved in their own rows; focused setup tests cover composition and preservation."
+        },
+        {
+          "path": "{home}/.claude/skills/**",
+          "when": "the selected Claude skill bundle is installed with the existing installer",
+          "observed_in": [],
+          "not_observed_reason": "The offline preflight fails the browser download before shared skills or project files are changed. Existing installer effects are proved in their own rows; focused setup tests cover composition and preservation."
+        },
+        {
+          "path": "{home}/ms-playwright/.links/*",
+          "when": "always — Playwright records this package's installation in the browser registry as one link entry, named for the installing package's path, before it looks at what is already downloaded",
+          "observed_in": [
+            "no_session",
+            "ambient_session",
+            "stale_session",
+            "lifecycle_log",
+            "persisted_consent"
+          ]
+        },
+        {
+          "path": "{home}/ms-playwright/**",
+          "when": "the download completes — the Chromium build (a ~150 MB archive) is unpacked into a revision directory of the same registry",
+          "observed_in": [],
+          "not_observed_reason": "the effect fixture pins PLAYWRIGHT_DOWNLOAD_HOST at a closed loopback port, so the archive is never fetched and no browser directory is created"
+        }
+      ],
+      "sends": [
+        {
+          "destination": "{playwright-download-host}",
+          "what": "a GET of the Chromium build archive (~150 MB) and of the headless shell beside it",
+          "when": "the registry does not already hold the revision this package's Playwright pins",
+          "requires_consent": false,
+          "observed_in": [],
+          "not_observed_reason": "the effect fixture pins PLAYWRIGHT_DOWNLOAD_HOST at a closed loopback port, so the fetch fails at connect; the NODE_DEBUG=net trace the case asserts on names no host but 127.0.0.1"
+        }
+      ],
+      "effect_test": "effects: tooling setup (preflight)",
+      "test_scope": "preflight",
+      "notes": "PREFLIGHT-PROVED: checks the selected project copy, exact pin, installed page-kit and context preservation before attempting the package-owned browser download. The closed-loopback fixture fails that download before global skills, context or project instructions change. After a successful download, setup composes the existing installers and appends the context import once. Does not read gateway credentials, resolve or close campaign run sessions, append journals, remit telemetry, scaffold pages or create campaign evidence. Focused tests prove rerun preservation, refusal-before-write and browser-failure recovery.",
+      "preflight": {
+        "may_write": [
+          "{home}/ms-playwright/.links/*"
+        ],
+        "may_contact": []
+      }
+    },
+    {
+      "command": "tooling",
+      "subcommand": "setup",
+      "flags": [
+        "--dry-run"
+      ],
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "openWorldHint": false,
+        "idempotentHint": true
+      },
+      "tier": "none",
+      "writes": [],
+      "sends": [],
+      "effect_test": "effects: tooling setup --dry-run",
+      "test_scope": "full",
+      "notes": "Checks the selected project and previews the existing skill/context installers and instruction import without downloading a browser, touching credentials or recovering/remitting a run session."
     }
   ]
 }

package/contracts/migration-sidecar-bundle.v0.json

@@ -59,6 +59,15 @@
   "identity_fields": [
     {
       "name": "map_id",
+      "local_spec_alternative": {
+        "name": "local_spec_id",
+        "artifact_paths": {
+          "build_packet": "spec.local_spec_id",
+          "assembly_report": "identity.local_spec_id",
+          "doctor_output": "derived.local_spec_id",
+          "qa_verdict": "local_spec_id"
+        }
+      },
       "artifact_paths": {
         "build_packet": "spec.map_id",
         "assembly_report": "identity.map_id",