@nextcommerce/campaigns-os 1.41.2 → 1.43.1

package/contracts/supported-surface.json

@@ -1,6 +1,6 @@
 {
   "_note": "The downstream contract manifest. Everything listed here is SUPPORTED SURFACE: consumers (campaigns-agent, campaign-builder, the private ops repo, page-kit campaign repos) may depend on it, and changing it is a deliberate act — hashed entries require a surface_version bump in the same change (check-supported-surface.mjs --base, mirroring the skills.json bump gate), named entries must keep existing at their path, cli_commands must keep resolving in the CLI dispatch, package_exports must stay exported, and every entry must ship in the npm pack (files[] coverage). Anything NOT listed here — src/** internals, scripts/** checkers, examples/**, prompts/**, contracts/** other than this file and the entries named[] below (the orientation contract, the release ledger, and the consumer-facing orientation fixtures) — is implementation: consumers may read it for context but must not build on it, and it can change without notice. Rationale and the compatibility promise: docs/supported-surface.md.",
-  "surface_version": "1.41.2",
+  "surface_version": "1.43.1",
   "package_exports": [
     "./commercial-journey",
     "./commercial-parity",
@@ -47,7 +47,7 @@
   ],
   "hashed": {
     "contracts/migration-sidecar-bundle.v0.json": {
-      "sha256": "f5097f6cccaf211d442c1ebc584d2c76d5a07a44e587df130de02117a9412db0"
+      "sha256": "53269453dfdaac4b286124d445b60b0c46205dfbaf8037ac61b30254a32df53a"
     },
     "contracts/runtime-recipe.campaigns-os-node-v1.json": {
       "sha256": "90aaaaade90cf2525ea1aa05be5cb2d02b57e6e59f9278a946efa8a087946fd3"
@@ -59,16 +59,16 @@
       "sha256": "65bcd8b5f41f1e9ecfc36f3b8838cd4ed531bd74c5a318ee5147131f6c9b4a1c"
     },
     "schemas/campaign-runtime-assembly-report.v0.schema.json": {
-      "sha256": "3fa085f2ad368567983cdc9c01e7c712682d02df9c28e69a2b7befb45d444468"
+      "sha256": "8a0d37be9a4bb34d0ed073c9d6bfa4406a7b499c801c34c5fbb26646e2665c0b"
     },
     "schemas/campaign-runtime-build-context.v0.schema.json": {
       "sha256": "f310c1b7844d9b1994864d15858ff0c6f17efc1e5285ba193d181bdb2dd4be2f"
     },
     "schemas/campaign-runtime-build-packet.v0.schema.json": {
-      "sha256": "886fb59b58787a3fd7a9c43ce4c676aeebbd52fd789269cfac700fcae42106d1"
+      "sha256": "47c2899f409ed5927cf410bddd63e7bb8a9d154eabf7a07455777aed118212e9"
     },
     "schemas/campaign-spec.v4.schema.json": {
-      "sha256": "12b57573739357acb2b007d00a737cd86face441c47f2719fc51b041dc8ea4a5"
+      "sha256": "af56c3de638d3c4e1fd5df8c2d733754d9ad16caa23b5bec92ce3a6f71bd0271"
     },
     "schemas/campaigns-os-legacy-migration-inventory.v0.schema.json": {
       "sha256": "d6edc4572900d15fdaf6b8c59916b0d885303c1d398bdadeb7c58285522c9049"
@@ -80,10 +80,10 @@
       "sha256": "1405c32bb9698030e9a40d754191e413cdd505dde91ac7de2e41c8887700f8f2"
     },
     "schemas/campaigns-os-qa-verdict-sidecar.v0.schema.json": {
-      "sha256": "1bc53b9a75a6c19c89aee6e9664574980b09d2e13eb8826b157f5ab6ba82d0b0"
+      "sha256": "3c40fd79f218d1b95f0424f9a2b67db140a306329e2ca02793e2740d3afded59"
     },
     "schemas/campaigns-os-qa-verdict.v0.schema.json": {
-      "sha256": "f7ce00e4f814d0ab7659b11fb2a14d3e4fafbf7c8e353449f25d7e87e1627acc"
+      "sha256": "ec4514e81a791a63bc0b358d7977aa823f3c5524e0f5caaba2712e66f262e18a"
     },
     "schemas/campaigns-os-doctor-output.v0.schema.json": {
       "sha256": "87866e619d2a18f01a208a1682cb14a2079f61df51c642f4e1902b6e6bce0ce5"
@@ -95,7 +95,7 @@
       "sha256": "08ca132134b9e4610370e88082a5e888d09ddec0d5ee4512d84cc57181da722e"
     },
     "schemas/campaigns-os-run-record.v0.schema.json": {
-      "sha256": "2a073874ab6081dd6db48e90f1a9b2c3c7c3ae4af70779c604701d70bb12b46d"
+      "sha256": "00dc9bcec79c12ea22a27f636188bcc33c6811df2d646ac7b49d4cc076e97355"
     },
     "schemas/campaigns-os-runtime-recipe.v1.schema.json": {
       "sha256": "f8a2ab5eadbb71fb6d5653b670ee71e4471c3df74dd04000d3dbd3d9ae9e71fc"
@@ -110,7 +110,7 @@
       "sha256": "841c1f884260ce3eb3ddb518960a127bc915992a9539c818e5986ce156acff1f"
     },
     "schemas/campaigns-os-progress-snapshot.v0.schema.json": {
-      "sha256": "c572756be7df03351843ffc361fc657e3fd819702b4e6f0a78a3c8efd0b0f046"
+      "sha256": "ef31b4f20e39dfc1614dd4b45e4cf1692a51760b008cb51d133659307bd2a954"
     },
     "demo/apollo-v0/provenance.json": {
       "sha256": "2e440be6513fe06b351c3a72c35424a04f807792621cb01e89803441fd925e06"
@@ -119,7 +119,7 @@
       "sha256": "dfc9abed38d456969e47a21f606d308a03bdf036f3466f7d6e47a602747dacf4"
     },
     "contracts/effects.v1.json": {
-      "sha256": "37c54f75731541f763aedac7b067506b3d0aa98e1083f285de87b9b32b027664"
+      "sha256": "121779835c14d8d48390c57268b50a60fe808f5d9ba91ea2dde5df22a64f8aaf"
     },
     "schemas/campaigns-os-effects.v1.schema.json": {
       "sha256": "3eadd22169ab98bc7c2f682af2751267605170581182158d96be035b0cfe44dc"
@@ -212,6 +212,7 @@
     "agents/codex/AGENTS.md",
     "agents/copilot/copilot-instructions.md",
     "agents/cursor/campaigns-os.mdc",
-    "docs/skills-revision.md"
+    "docs/skills-revision.md",
+    "docs/local-setup.md"
   ]
 }

package/docs/build-packet.md

@@ -4,7 +4,7 @@ The Build Packet is the campaign assembly handoff. It wraps, but does not replac
 
 It answers:
 
-- Which CampaignSpec and Map ID are we building?
+- Which CampaignSpec and saved Map ID or local-spec ID are we building?
 - Which public route slug and campaign directory are expected?
 - Where are the prepared HTML/assets?
 - Which Campaign Build Brief is the merchandising/design presentation truth?
@@ -15,6 +15,56 @@ It answers:
 
 The current schema is `schemas/campaign-runtime-build-packet.v0.schema.json`.
 
+## Local-spec entry
+
+A saved Map is optional for a prepared-HTML build. The coding agent authors an
+ordinary CampaignSpec from the brief, source design and configured campaign's
+real commerce values, following `schemas/campaign-spec.v4.schema.json`. The
+operator supplies the selected store/campaign, public Campaigns API key, intended
+pages and commercial choices, plus store contact details and policy URLs. Verify
+the store/campaign binding and package/offer references; do not guess commerce
+values. No gateway or Map provisioning is required for this entry.
+
+Set `spec_identity.local_spec_id` to a new UUID once, commit it with the spec,
+and keep it unchanged through revisions and fresh checkouts. It accepts 1–64
+letters, digits, underscores or hyphens, with no surrounding whitespace. Local
+IDs are checked exactly; the legacy normalization of saved Map IDs does not
+apply. Malformed or conflicting local identities cannot be adopted into campaign
+evidence; blocked diagnostic reports may still be written. Doctor reports local
+identity failures as `spec.local_identity`, while
+saved-Map failures retain `spec.map_id`. Set `spec_identity.public_route_slug`
+to the intended route. Omit `map_id`, saved-Map URLs and saved-Map revision
+metadata; a local ID is never a Map ID. A spec declaring both kinds is refused.
+A separately authored campaign gets a new local ID even if its route matches.
+
+```sh
+npx --no-install campaigns-os start --spec campaign-spec.json --source source-html --target . --template-family <certified-family> --deploy-target local-serve
+npx --no-install campaigns-os next --packet campaign-runtime.build.json
+```
+
+The packet and report retain `map_id: null` and carry `local_spec_id`. Doctor,
+report writes, polish capture, progress, run closeout and QA compare that local
+identity. Material spec hashes still bind the current revision; a changed ID or
+content cannot reuse earlier proof. After a material revision, follow `next` to
+refresh preparation and affected evidence. Keep the spec, source, dependency
+pins and canonical sidecars in Git. Use `readback` and `next` after a fresh
+checkout; identity survives the move, but proof freshness is assessed again.
+
+Run QA through `--packet`. Local verdicts use the storage key
+`local-spec-<local_spec_id>` and carry the explicit ID in the full verdict and
+committed sidecar. A matching route alone cannot adopt a verdict. Local QA is
+never posted to the Map portal: `qa run` suppresses publication even with
+`--post-verdict`, while `qa publish` refuses with `local_spec`. Progress remains
+local with `map_id_missing`. Run Telemetry retains
+its existing consent controls. `spec derive --write-map` requires a real saved
+Map. Moving to a saved Map requires fresh preparation and evidence; this entry
+does not claim saved-Map revision alignment.
+
+Existing saved-Map specs and packets continue to work. The identity change does
+not relax template certification, source proof, store/SDK parity, polish,
+commerce checks, or typed-card checkout proof. Resolve their reported gates;
+localhost readiness is not production approval.
+
 ## Root-Served Campaigns (`campaign.route_root`)
 
 Most campaigns are served under a slug prefix (`/<public_route_slug>/...`), and
@@ -78,7 +128,7 @@ campaigns-os page-kit sync --packet campaign-runtime.build.json [--dry-run] [--j
 ```
 
 The CampaignSpec is the authority for the Store Profile: those values are
-authored in the Map, never in the repo, so `page-kit sync` writes the nine
+authored in the saved Map or the repository-owned local spec, so `page-kit sync` writes the nine
 fields the spec carries (`campaign.store_*`) unconditionally. The SDK pin is
 different. On an existing campaign the repo pin moves first and the Map/spec
 is stale until someone re-saves it, so a spec → repo write would undo a bump
@@ -103,7 +153,7 @@ covers only the governed fields. `--dry-run` prints the same diff without
 writing. Exit 0 on success (including a no-op re-run); exit 2 with
 `page_kit.sync.*` error codes and nothing written when the packet cannot be
 read, the target entry or the spec is missing or not an object, the spec
-identifies another campaign (`spec_identity.public_route_slug` or `map_id`
+identifies another campaign (`spec_identity.public_route_slug`, `map_id` or `local_spec_id`
 disagreeing with the packet: `page_kit.sync.spec_identity_mismatch`), or the
 resolved `_data/campaigns.json` lies outside the target repo through a symlink
 (`page_kit.sync.target_escapes_repo`).
@@ -1114,12 +1164,12 @@ and report proof policy fields above.
 
 | Flag | Source | When to use |
 | --- | --- | --- |
-| `--spec <path>` | Local JSON file | Offline work, CI runs against a fixture, or hand-edited spec drafts |
-| `--map-id <id>` | Map Builder proxy (KV-backed) | Default agentic flow — KV is the source of truth, no file shuttling |
+| `--spec <path>` | Local JSON file | Agent-authored local specs, saved-Map exports, offline work or CI fixtures |
+| `--map-id <id>` | Map Builder proxy (KV-backed) | Saved-Map intake from the current KV revision |
 
 When `--map-id <id>` is set, the CLI fetches `GET <proxy>/api/spec/<id>` (default `<proxy>` is `https://campaign-map.nextcommerce.com`) and caches the response to `<target>/.campaign-runtime/fetched-specs/<id>.json`. The cached file is what downstream stages read, so the packet's `spec.local_path` always resolves to an on-disk artifact regardless of intake mode.
 
-Retrieval behavior:
+Saved-Map retrieval behavior (`--map-id`):
 
 - **Re-fetch by default.** Every `start` / `prepare-build` invocation re-fetches from KV. KV is the source of truth; the cache file is a debug/inspection artifact, not a performance optimization.
 - **`--cached-spec`** reuses the cache without a network call. Use for offline iteration or when the proxy is temporarily unreachable.

package/docs/campaigns-os-build-flow.md

@@ -2,7 +2,7 @@
 
 The happy path is intentionally tight:
 
-1. Export a saved local CampaignSpec JSON from Campaign Map Builder, including Map ID and public route slug.
+1. Use a saved Map export, or have the coding agent author a CampaignSpec from the brief and verified campaign values through the [local-spec entry](build-packet.md#local-spec-entry). Preserve its Map ID or stable `local_spec_id`, plus its public route slug.
 2. Run `campaigns-os start` with the CampaignSpec, prepared source files, target page-kit repo, and template family.
 3. Treat doctor as the first gate. If its `next` block says `doctor-blocked` or `prepare-build` (the same stage names `campaigns-os next` uses), stop and resolve the named blocker.
 4. Run setup when doctor asks for setup; otherwise continue to assembly.
@@ -11,7 +11,7 @@ The happy path is intentionally tight:
 7. Install the package-owned Playwright browser with `npm run qa:install-browser`.
 8. Run polish, serve the current built output, and run `campaigns-os polish capture --packet <packet> --base-url <served-current-build-url>`. Do not mark Polish terminal or begin deploy/QA until this package-owned page-load evidence passes or has an exact finding waiver.
 9. Deploy a preview.
-10. Run `campaigns-os qa resolve`, then `campaigns-os qa run --browser --test-order common` with the tested URL. QA runs publish to the QA portal by default (the QA tab records browser QA plus typed-card proof and the run prints its portal link); pass `--no-post-verdict` only for offline / dev / CI runs.
+10. Run `campaigns-os qa resolve --packet <packet>`, then `campaigns-os qa run --packet <packet> --browser --test-order common` with the tested URL. Saved-Map QA uses the existing consent and publication controls; pass `--no-post-verdict` to keep its verdict local. Local-spec QA always keeps verdicts and progress local, even with `--post-verdict`, and `qa publish` refuses local-spec packets. Run Telemetry retains its consent controls.
 11. Treat test-order depth as the control: global test cards bypass the gateway and create no transactions, so no approval is needed. Localhost on any port is a Campaigns App Development domain (SDK allowed, analytics suppressed); non-localhost preview/production origins must still be allowlisted for the campaign API key so the SDK loads.
 12. Promote, block, or iterate from the recorded build, polish, deploy, QA, and test-order evidence.
 

package/docs/effects.md

@@ -9,6 +9,13 @@ The point of the file is not the prose. It is that **every row is proved by a
 test** (`src/effects.test.mjs`), and a row without its test cannot be published:
 `npm run check:effects` refuses it.
 
+`tooling setup` composes the existing skill/context/browser installers after a
+project-pin and preservation preflight. It also appends a project `CLAUDE.md`
+import. It bypasses session recovery, gateway credential reads and lifecycle
+capture; `--dry-run` is read-only. Like `qa install-browser`, its browser download
+has preflight-only effects proof offline; setup's preservation and recovery
+behavior has focused tests.
+
 - The contract: [`contracts/effects.v1.json`](../contracts/effects.v1.json)
 - Its shape: [`schemas/campaigns-os-effects.v1.schema.json`](../schemas/campaigns-os-effects.v1.schema.json)
 - The proof: `src/effects.test.mjs`
@@ -67,7 +74,7 @@ with one of these:
 | `{lifecycle-journal}` | The command-lifecycle journal wherever it was selected for this invocation. |
 | `{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. |
-| `{playwright-download-host}` | Where Playwright fetches browser builds from: `PLAYWRIGHT_DOWNLOAD_HOST` when set, else the Playwright CDN. The one destination in the 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. The third-party browser download used by `qa install-browser` and `tooling setup`. |
 
 The tokens matter because effects are not all under the target. `install-skills`
 writes your **home** directory, not the campaign. `telemetry on` writes your
@@ -129,6 +136,63 @@ declared on the rows it belongs to: `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.
 
+A refusal is decided by argv alone. When file content or state on disk decides
+the outcome, the command has reached a handler failure and journals it.
+
+For intake, run-record, built-site QA, and `next`, argv-only checks run before
+their handler reads the target; invalid values are refused without a journal
+entry. For `start`, `prepare-build`, and `build`, bare, empty, and whitespace-only
+values of `--spec`, `--map-id`, `--source`, `--target`, `--source-kind`,
+`--proxy-base`, `--wrapper-policy`, `--design-manifest`, and
+`--order-path-depth` are refused before local spec reads, Map fetches, or cache
+writes on the `--spec`, `--map-id`, and `--map-id --cached-spec` paths.
+The operator-facing `run-record` and `run end` commands refuse bare, empty, or
+whitespace-only values for every value-taking inherited run-record flag before
+packet work. The five agent
+token and elapsed-time flags retain their non-negative-integer diagnostics;
+`--surfaces` rejects unknown values, and `--dry-run` rejects a value. The
+inherited boolean flags (`--no-remit`, `--no-write`, `--dry-run`, and `--json`)
+retain their bare-flag behavior. `run end` also rejects `--new-run` and
+`--run-id` because the saved session fixes its run ID. `run-record` also
+rejects bare, empty, or whitespace-only `--run-id` and valued `--new-run`.
+Internal stale-session and QA closeouts retain the previous handling of values
+inherited from their invoking commands. A bare, empty, or whitespace-only
+`--proxy-base` on a sweeping command still writes the stale Run Record.
+Terminal QA auto-end tolerates 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; bare or empty `--qa-verdict` fails a Run Record closeout when inherited,
+though QA auto-end supplies its own verdict path. The underlying run-record
+handler still rejects invalid agent
+integers, unknown `--surfaces`, and any valued `--dry-run` that reaches it. QA
+auto-end drops `--dry-run` from inherited flags; if another inherited value
+fails in the handler, auto-end is skipped and the session stays open. QA's own
+journal entry is unaffected because auto-end runs after QA persistence. A named
+`--design-manifest` that is missing or is not a file is checked
+against the filesystem after intake has begun, so that failure is journaled.
+An invalid manifest's contents are likewise a handler failure. A `next` stage
+must be one of the stages in the orchestration stage contract; an unknown name
+is refused before the `next` handler reads the packet, runs doctor, or writes
+doctor output. The ambient run-session lookup in `main()` may read a named
+`--packet` before the handler runs.
+
+`polish capture --packet` would report "polish capture requires
+packet.assembly.target_repo to resolve to a local target repo" as a journaled
+handler failure because packet content would decide it. Today the workspace
+resolver always yields a local path, so this check does not fire through the
+CLI. `run end` reports "run end needs a build packet" as a journaled handler failure
+when the saved session has no packet and argv names none. For `qa run` and `qa
+resolve`, "QA requires a Map ID" is a refusal when argv carries no non-empty
+`--packet`, `--site`, `--built`, positional Map ID, or `--map-id` value. A selector
+flag without a value is refused with "Missing value for --<flag>". If a named
+packet yields neither a Map ID nor a valid local-spec identity after checkpoint
+preflight reads the packet, spec, and report, the requirement is a journaled
+handler failure. A conflicting local/Map identity is also a handler failure.
+The nested run-record refusal scope in session closeout guards against future
+changes. No internal closeout can currently create a refusal before its
+invoking command journals.
+
 ## How a row is proved
 
 `src/effects.test.mjs` runs the real CLI in a disposable target seeded from
@@ -279,3 +343,8 @@ reason. What it may not be is silent.
 Change the effect, change the row, in the same PR. The effect test will tell you
 which row is wrong before review does: it names the path that moved and the row
 that failed to declare it.
+
+Local-spec QA retains its artifacts locally. It never sends a verdict or progress
+to the Map portal, even when `--post-verdict` is supplied; `qa publish` refuses
+local-spec packets. Commerce API reads, served-page probes and requested typed-card
+orders keep their existing effects. Run Telemetry still follows its consent controls.

package/docs/local-setup.md

@@ -0,0 +1,51 @@
+# Local campaign setup
+
+For a new campaign, choose its working folder and run this from that folder:
+
+```sh
+npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.43.1 next-campaign-page-kit@0.2.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
+```
+
+Review the release source/provenance before installation as described in
+`AGENTS.md`. npm installs the dependencies first; `--no-install` then runs only
+the project's installed CLI. Keep `package.json` and `package-lock.json` in
+Git. For an existing project, preserve its reviewed pin: run `npm ci`, then
+`npx --no-install campaigns-os tooling setup --target . --platform claude`
+on a release that supports setup. Changing the pin is a separate update.
+
+Setup checks the exact toolkit pin, its lockfile version and the installed
+page-kit dependency before it changes files. It composes the existing
+installers to:
+
+1. Install the QA browser through this toolkit's own Playwright package.
+2. Install the bundled skills into `~/.claude/skills` (same-name skills are
+   refreshed just as with `install-skills`).
+3. Install the four context files under `.campaign-runtime/agent-context`
+   and the managed runtime ignore block.
+4. Append one import to the project's `CLAUDE.md`, preserving existing text.
+
+The import uses Claude Code's documented
+[`@path` syntax](https://code.claude.com/docs/en/memory#import-additional-files).
+Existing context that differs from the bundle and symlink destinations require
+reconciliation before setup; setup does not overwrite them. A repeated run
+preserves campaign pages, authored decisions and project instructions. If the
+browser download fails, fix that error and rerun setup; shared skills and
+project files have not been changed. If the runtime ignore block cannot be
+written, setup reports `context_install_failed`; fix `.gitignore` and rerun.
+`--dry-run --json` previews setup without any writes or browser download.
+
+Restart Claude Code in the campaign folder. Use the `next-campaigns-os` skill
+and provide the configured campaign details, HTML/assets and brief. The agent
+authors a local CampaignSpec if there is no saved Map export; follow the
+[local-spec entry](build-packet.md#local-spec-entry). The skill checks its
+loaded bundle revision against the project copy.
+`restart_required` means the files are installed; it does not prove that the
+running agent has loaded them. Check Claude's `/context` view if the project
+instructions are missing.
+
+Setup does not scaffold template pages, create a CampaignSpec, connect the
+gateway, change a saved Map, run a campaign session, remit telemetry, or prove
+checkout. The agent performs intake and chooses the template before assembly.
+A local spec uses `spec_identity.local_spec_id` and keeps its evidence in the
+repository. Existing doctor/QA gates still apply. This entry is Claude Code first; other agents retain their existing
+manual installation path.

package/docs/migration-sidecar-bundle.md

@@ -55,12 +55,17 @@ contract. A packet found only at
 remedy; conformance does not silently widen discovery.
 
 The checker validates canonical paths, declared schema versions, strict UTC
-timestamps, cross-artifact Map ID, public slug, campaign directory, live URL
+timestamps, cross-artifact Map ID or local-spec ID, public slug, campaign directory, live URL
 path, template family, and spec identity, doctor freshness, and the URL/order-
 free QA projection. Safe repository-relative spellings such as
 `campaign-runtime.build.json` and `./campaign-runtime.build.json` are
 equivalent; absolute paths, URIs, backslashes, and parent traversal are not.
 
+Local-spec bundles compare `local_spec_id` across the packet, report, doctor
+output and QA sidecar. Their Map IDs remain null; the QA verdict's
+`campaign_slug` is the storage key `local-spec-<local_spec_id>`. Mixing local
+and saved-Map identities fails conformance; a shared public route is not enough.
+
 Spec identity has two deliberately separate meanings. Build Context
 `spec.hash` and Assembly Report `identity.spec_hash` retain exact raw-byte
 integrity. Build Context `spec.material_hash`, Assembly Report

package/docs/orientation-contract-reference.md

@@ -25,7 +25,7 @@ Ledger schema id: `campaigns-os-release-ledger/v1`
 Change policy version: `1.0.0`  
 Reason-code vocabulary version: `1.0.0`  
 Limits version: `1.0.0`  
-Supported surface at generation time: `1.41.2`
+Supported surface at generation time: `1.43.1`
 
 ## Forward compatibility
 

package/docs/progress-snapshots.md

@@ -140,3 +140,9 @@ The planned immutable receiver key is
 revision. A key match identifies scope; it is not authentication or trust. The
 receiver must verify the digest and authorized Map scope and stamp its own trust.
 Unknown, incomplete or conflicted histories must never yield a ready workspace.
+
+Local-spec packets add optional `identity.local_spec_id`. Report binding compares
+that ID and the local material hash, so local stages can be observed without a
+saved Map. `map_id` and `map_revision_hash` remain null and
+`saved_revision_alignment` remains `unconfirmed`; these observations stay on disk
+with `map_id_missing` and have no portal storage key.

package/docs/qa-and-test-orders.md

@@ -98,6 +98,11 @@ npm run campaigns-os -- qa resolve --packet campaign-runtime.build.json
 
 Resolve reads the packet, loads the local CampaignSpec when available, derives deployed page URLs from the packet deploy URL or `--base-url`, probes the entry URLs it derived, and prints the funnel topology. It does not create a verdict.
 
+Local-spec QA requires `--packet` and matching `local_spec_id` values in the
+packet, CampaignSpec and Assembly Report, with a current report material hash.
+A Map ID override is refused. See the [local-spec entry](build-packet.md#local-spec-entry)
+for preparation and identity rules.
+
 ### Route reachability
 
 A route set derived from the packet is not evidence that the deployment serves
@@ -289,7 +294,7 @@ npm run campaigns-os -- qa run \
   --base-url https://preview.example.com/campaign/
 ```
 
-The runner fetches deployed pages, checks route availability, verifies CampaignSpec `sdk_hints.meta_tags` (a key the Campaign Cart SDK does not read, `next-currency` or `next-predictive-address` from `src/sdk-meta-tags.mjs`, is a `warn` row at severity `warn` carrying the shared note, never `manual_review` and never a blocker, whether or not the tag rendered; doctor reports the same key as `sdk_hints.meta_tags.ignored_by_sdk`), writes a local verdict JSON under `<target-repo>/qa-output/<map-id>/<run-id>.json` (the packet's `assembly.target_repo`, else the packet's directory; `--output-dir` overrides it, and a packet-less run uses `qa-output/` under the current directory), and returns exit code `4` when the verdict is blocked. The target's managed ignore block lists `qa-output/`, because full verdicts carry live storefront URLs; the committed form is the `.campaign-runtime/qa-verdict.json` projection.
+The runner fetches deployed pages, checks route availability, verifies CampaignSpec `sdk_hints.meta_tags` (a key the Campaign Cart SDK does not read, `next-currency` or `next-predictive-address` from `src/sdk-meta-tags.mjs`, is a `warn` row at severity `warn` carrying the shared note, never `manual_review` and never a blocker, whether or not the tag rendered; doctor reports the same key as `sdk_hints.meta_tags.ignored_by_sdk`), writes a local verdict JSON under `<target-repo>/qa-output/<qa-storage-key>/<run-id>.json` (the packet's `assembly.target_repo`, else the packet's directory; `--output-dir` overrides it, and a packet-less run uses `qa-output/` under the current directory), and returns exit code `4` when the verdict is blocked. The storage key is the Map ID for saved-Map QA and `local-spec-<local_spec_id>` for local-spec packet QA. The target's managed ignore block lists `qa-output/`, because full verdicts carry live storefront URLs; the committed form is the `.campaign-runtime/qa-verdict.json` projection.
 
 ### Automatic commercial parity
 
@@ -353,7 +358,7 @@ nothing is ever selected by mtime or "latest":
 ```bash
 campaigns-os qa promote \
   --packet campaign-runtime.build.json \
-  --verdict qa-output/<map-id>/<run-id>.json \
+  --verdict qa-output/<qa-storage-key>/<run-id>.json \
   --json
 ```
 
@@ -381,10 +386,12 @@ Report's `identity.spec_material_hash` and the Build Context's
 raw-byte digest of the spec file (the two meanings are deliberate; see
 [docs/migration-sidecar-bundle.md](./migration-sidecar-bundle.md)).
 `campaign_ref_id` is copied from the CampaignSpec's `campaign.ref_id` and
-identifies the platform campaign the spec was exported from, not this build:
-two specs exported from one platform campaign share it by design, and it is
-`null` when the spec carries none. Use `campaign_slug` (the Map ID) and
-`public_route_slug` to tell builds apart.
+identifies the configured platform campaign, not this build: two specs for one
+platform campaign share it by design, and it is `null` when the spec carries
+none. `campaign_slug` carries the Map ID for saved-Map verdicts. Local-spec
+verdicts carry explicit `local_spec_id` and use
+`campaign_slug: "local-spec-<local_spec_id>"`; both survive sidecar projection.
+`public_route_slug` is the route, not a substitute for either stable identity.
 
 **Trust is stamped by the receiver, never by this CLI.** The QA portal
 receiver accepts verdict posts publicly (after shape/size/rate checks) and
@@ -512,7 +519,8 @@ Exactly one comparison, against exactly one earlier run:
 
 1. **Find the previous run.** The most recent Run Record under the Build
    Packet's `.campaign-runtime/run-records/` whose `identity.map_id` matches
-   this campaign. Only the first match counts — walking further back to find a
+   this saved Map, or whose `identity.local_spec_id` matches this local spec
+   with no Map ID. Only the first match counts — walking further back to find a
    record that happens to carry usable evidence would compare this run against
    a non-adjacent one and report anything introduced in between as
    pre-existing.
@@ -624,7 +632,7 @@ QA evidence redacts checkout request bodies and generated QA emails. Verdict art
 keep method, URL, response summaries, order refs, line-item summaries, and card last4,
 but they should not contain full customer address/payment payloads.
 
-QA runs **publish to the QA portal by default** — they appear in the Campaign Map
+Saved-Map QA runs **publish to the QA portal by default** — they appear in the Campaign Map
 QA tab and the run picker, and the command prints the portal link. No flag needed.
 Pass `--no-post-verdict` (or `--local-only`) for offline / dev / CI runs that should
 stay local-only; publishing never fails the QA run if the portal is unreachable.
@@ -636,7 +644,14 @@ local-only, and the output names the destination plus the opt-in
 (`--post-verdict`, or `campaigns-os telemetry on`). Portal-managed campaigns —
 spec resolved from the portal for the run — keep publish-by-default regardless
 of consent: those verdicts are the QA tab's product surface, not telemetry.
-Explicit flags always win in both directions.
+Explicit flags always win in both directions for saved-Map QA.
+
+A packet with `local_spec_id` always keeps its verdict and progress local.
+`qa run` suppresses portal publication even with `--post-verdict`; the flag
+does not turn a local ID into a Map destination. `qa publish` refuses such a
+packet with `refusal.code: local_spec`, including under `--dry-run` or
+`--republish`. Commerce reads, served-page probes and requested typed-card
+orders still run; Run Telemetry follows its existing consent controls.
 
 ```bash
 npm run campaigns-os -- qa run \
@@ -646,7 +661,7 @@ npm run campaigns-os -- qa run \
 
 ### Publish a stored verdict (`qa publish`)
 
-"Run local, publish when clean" is one command, not a rerun. A run kept local
+For saved-Map packets, "run local, publish when clean" is one command, not a rerun. A run kept local
 with `--no-post-verdict` writes the same full verdict under `qa-output/` and
 the same committed sidecar as a publishing run; `qa publish` posts that stored
 verdict to the QA portal through the rail `qa run` uses, without re-running
@@ -678,6 +693,7 @@ order placed — with a named `refusal.code`:
 
 | `refusal.code` | What it means |
 |---|---|
+| `local_spec` | The packet has `local_spec_id` and no saved Map destination. Keep the verdict local; moving to a saved Map requires fresh preparation and evidence. |
 | `spec_hash_mismatch` | The verdict's `spec_hash` is not the packet's current spec (`spec.local_path`, hashed the way every spec-identity check hashes it, so `sha256:` prefix and case do not matter). A verdict for a spec that has since changed is not evidence about the current one: re-run `qa run`, which publishes by default. The result carries both hashes. |
 | `spec_hash_absent` | The verdict carries no `spec_hash`. Re-run `qa run`. |
 | `already_published` | The run's Run Record records this verdict's `run_id` as published (by the run itself, or by an earlier `qa publish`). Pass `--republish` to post it again; the existing portal link is in the output either way. |

package/docs/runtime-readiness.md

@@ -8,7 +8,7 @@
 
 How a checkout of this repository at one commit becomes a usable installed runtime, and how a consumer decides whether a prepared one is still trustworthy. Everything below is generated from `contracts/runtime-recipe.campaigns-os-node-v1.json`, which is the only authority for these values.
 
-Recipe kind `campaigns-os-node-v1`, revision `1.0.2`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.41.2`.
+Recipe kind `campaigns-os-node-v1`, revision `1.0.2`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.43.1`.
 
 ## What this is
 

package/docs/skills-revision.md

@@ -16,7 +16,7 @@ that the copy on disk moved.
 `skills.json` carries one top-level field:
 
 ```json
-"bundle_revision": "1.41.2+skills.1"
+"bundle_revision": "1.43.1+skills.1"
 ```
 
 The spelling is `<package version>+skills.<n>`:
@@ -25,7 +25,7 @@ The spelling is `<package version>+skills.<n>`:
   skills ship with (`check-skill-versions.mjs` fails if the two disagree);
 - `<n>` is a plain counter, not a semver component. It says "this is the *n*th
   skill-text revision published against that package version" and it **resets
-  with the prefix**. `1.41.2+skills.1` is therefore ahead of `1.40.0+skills.7`.
+  with the prefix**. `1.43.1+skills.1` is therefore ahead of `1.40.0+skills.7`.
 
 It is one identity for the bundle as a whole, on purpose. Per-skill versions
 still exist and still gate per-skill changes, but an agent that loaded one skill
@@ -37,7 +37,7 @@ The first body line of every bundled `SKILL.md`, immediately after the
 frontmatter, is exactly:
 
 ```
-Bundle revision: 1.41.2+skills.1
+Bundle revision: 1.43.1+skills.1
 ```
 
 followed by a short paragraph telling the agent to run the check below at the
@@ -48,7 +48,7 @@ text the agent is actually reading, not from a file it would have to go and open
 ## The check
 
 ```bash
-npx --no-install campaigns-os tooling status --skills-revision 1.41.2+skills.1
+npx --no-install campaigns-os tooling status --skills-revision 1.43.1+skills.1
 ```
 
 The value is compared against the bundle revision of the **CLI the command runs
@@ -90,20 +90,20 @@ reports the choice as `skills.scope` (`requested`, `installed_platforms`, or
 "revision_check": "match",
 "skills_revision": {
   "status": "match",
-  "requested": "1.41.2+skills.1",
+  "requested": "1.43.1+skills.1",
   "spelling": "bundle",
-  "on_disk": "1.41.2+skills.1",
+  "on_disk": "1.43.1+skills.1",
   "on_disk_skill": null,
-  "message": "match (1.41.2+skills.1)"
+  "message": "match (1.43.1+skills.1)"
 }
 ```
 
 The text view prints one named line, as a header above the rest of the status:
 
 ```
-Skills revision: match (1.41.2+skills.1)
-Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.41.2+skills.1 — start a fresh session
-Skills revision: unchecked (on disk 1.41.2+skills.1)
+Skills revision: match (1.43.1+skills.1)
+Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.43.1+skills.1 — start a fresh session
+Skills revision: unchecked (on disk 1.43.1+skills.1)
 ```
 
 `unchecked` is the state when the flag is absent. It is not an error — an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextcommerce/campaigns-os",
-  "version": "1.41.2",
+  "version": "1.43.1",
   "description": "Toolkit for agent-assisted NEXT campaign builds.",
   "license": "Apache-2.0",
   "repository": {
@@ -149,6 +149,7 @@
     "docs/diagnostics.md",
     "docs/progress-snapshots.md",
     "demo",
-    "docs/demo-preview.md"
+    "docs/demo-preview.md",
+    "docs/local-setup.md"
   ]
 }

package/schemas/campaign-runtime-assembly-report.v0.schema.json

@@ -28,8 +28,13 @@
       "type": "object",
       "additionalProperties": true,
       "required": ["map_id", "public_route_slug", "campaign_directory", "live_url_path", "spec_hash"],
+      "oneOf": [
+        { "properties": { "map_id": { "type": "string", "minLength": 1 } }, "not": { "required": ["local_spec_id"] } },
+        { "required": ["local_spec_id", "spec_material_hash"], "properties": { "map_id": { "type": "null" } } }
+      ],
       "properties": {
-        "map_id": { "type": "string", "minLength": 1 },
+        "local_spec_id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "Stable repository-owned CampaignSpec identity; never a saved Map ID. Keep unchanged across local revisions." },
+        "map_id": { "type": ["string", "null"], "minLength": 1 },
         "public_route_slug": { "type": "string", "minLength": 1 },
         "campaign_directory": { "type": "string", "minLength": 1 },
         "live_url_path": { "type": "string", "minLength": 1 },

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

@@ -66,9 +66,14 @@
       "type": "object",
       "additionalProperties": false,
       "required": ["map_id"],
+      "oneOf": [
+        { "properties": { "map_id": { "type": "string", "minLength": 1 } }, "not": { "required": ["local_spec_id"] } },
+        { "required": ["local_spec_id", "local_path"], "properties": { "map_id": { "type": "null" }, "local_path": { "type": "string", "minLength": 1 }, "spec_url": { "type": "null" } } }
+      ],
       "properties": {
+        "local_spec_id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "Stable repository-owned CampaignSpec identity; never a saved Map ID. Keep unchanged across local revisions." },
         "map_id": {
-          "type": "string",
+          "type": ["string", "null"],
           "minLength": 1,
           "description": "Saved Map Builder identity used for reopen, /api/spec/<map-id>, QA verdicts, and provenance."
         },