@nextcommerce/campaigns-os 1.41.2 → 1.43.2

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
@@ -196,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).
@@ -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/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

@@ -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.",
@@ -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."
+      "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",
@@ -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",