@nextcommerce/campaigns-os 1.41.2 → 1.43.2

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.2`
 
 ## Forward compatibility
 

package/docs/progress-snapshots.md

@@ -59,12 +59,16 @@ across them. A progress stream is independent of a run-session ID.
 
 Sanitized immutable snapshots are written under the target repository's
 `.campaign-runtime/progress/` before any request. Allocation uses an exclusive
-local lock with a process owner. Dead owners are recovered through an exclusive
-recovery claim and an atomic rename; a live process is never evicted. An ownerless
-crash gap is recoverable after ten seconds. If recovery itself is interrupted,
-capture fails closed: stop all Campaigns OS writers for that target, then remove
-the abandoned `.allocation-lock` directory in the affected progress scope before
-retrying `next`. Do not remove a lock while a writer is active.
+local lock with a process owner; the lock directory and its owner record are
+published together in one rename, so a lock never exists without its owner.
+Dead owners are recovered through an exclusive recovery claim and an atomic
+rename; a live process is never evicted. A lock directory with no owner record
+(left by an older release) is never taken over: capture refuses it after about
+a second. If one is found, or if recovery itself is interrupted, capture fails
+closed and the warning names the affected `.allocation-lock` directory: stop
+all Campaigns OS writers for that target, then remove that directory before
+retrying `next`. Do not remove a lock while a writer is active. Do not run an
+older Campaigns OS release against the same target at the same time.
 
 An unchanged projection reuses its ID, timestamp and sequence. Identity
 changes start a new stream. Each local scope retains at most 32 snapshots and
@@ -140,3 +144,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

@@ -1,5 +1,13 @@
 # QA And Test Orders
 
+For packet-based partial builds, QA honors the Assembly Report's recorded
+`stages.prepare_build.declared_out_of_scope` declarations together with the
+packet's skip mappings. Unbuilt declared pages emit `skipped` evidence with
+reason `out_of_build_scope`; HTTP, browser and commercial checks do not request
+those routes, and entry URLs come from the remaining pages. A materialized
+stock page rejoins QA. Missing in-scope pages still fail normally. A raw skip
+mapping without a recorded declaration does not suppress checks.
+
 The public v0 QA runner is Node/npm-based and does not require access to a private runtime repo.
 
 > **Commerce QA requires network; it cannot run in a no-outbound sandbox.** The SDK, product images, fonts, the Netlify preview, and the Playwright typed-card test order all need outbound network. A build environment without it can only validate markup/build/CSS — the commerce runtime and the typed-card test order (the Campaigns OS control) must be deferred to a deployed preview. Always run the QA runner against a `--base-url` preview/production origin (e.g. `npm run campaigns-os -- qa run --packet campaign-runtime.build.json --base-url https://deploy-preview-7--your-site.netlify.app/ --browser --test-order common`); never report commerce-runtime QA as passed from an offline build.
@@ -98,6 +106,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 +302,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 +366,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 +394,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 +527,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 +640,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 +652,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 +669,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 +701,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. |
@@ -777,9 +801,12 @@ retire that guard once #36 ships and `cartLines` is populated.
 Analytics correctness has two deliberately separate evidence phases in one QA
 run:
 
-1. The campaign-root visit inventories declared providers, containers, pixels,
-   and other observable tags. It does not prove or disprove Purchase, even if a
-   stray Purchase-shaped event appears there.
+1. The inventory visit inventories declared providers, containers, pixels,
+   and other observable tags on one page: the campaign root, or a built entry
+   when the root cannot be captured (see
+   [Which page the inventory captures](#which-page-the-inventory-captures)).
+   It does not prove or disprove Purchase, even if a stray Purchase-shaped
+   event appears there.
 2. The existing canonical typed-card order run supplies Purchase evidence. For
    each planned order, the topology classifier must recognize the final URL as
    that plan's receipt, then the runner waits the full `--analytics-settle`
@@ -823,6 +850,98 @@ analytics block to gate. The SDK's own data layer is a separate, always-on
 reading taken on the same order — see [Purchase data layer](#purchase-data-layer-dl_purchase)
 under Test Orders.
 
+### Which page the inventory captures
+
+The inventory starts at the campaign root composed from the campaign identity
+(`public_route_slug` plus `route_root`). A partial build (a topology with a
+partial build scope, or pages excluded from the build) may have no page there:
+the root is then whatever the host answers, such as a directory index or a
+generic fallback. So the root is visited only when it is in scope. On a full
+build it always is; on a partial build it is in scope only when a built,
+in-scope topology page is served at the root. When the root is out of scope,
+answers non-2xx, or fails to load (a timeout, a refused connection), the leg
+tries each funnel's built entry in turn: the first in-scope page on a partial
+build (the same entry the partial-scope planner selects), otherwise the first
+entry-like page. It captures the first page that answers 2xx. A response with no
+HTTP status counts as an answer. A closed page or a disconnected browser is not
+a per-page failure: it is the `analytics-correctness:runner` blocker.
+
+`analytics-correctness:capture` records the page it used:
+`evidence.capture_page` holds `url` (the URL requested, query redacted),
+`source` (`campaign_root` or `built_entry`), `page_id`, `funnel_id` and
+`http_status`. `evidence.final_url` is the page URL after redirects and
+settling. When a built entry was used, `evidence.root_fallback` says why the
+root was not: `reason` is `out_of_built_scope`, `non_2xx` (with the root's
+`http_status`), or `navigation_error` (with its `error_code`).
+
+When no page is captured, the leg emits `analytics-correctness:capture` alone,
+with no per-vendor assertion measured against an empty page. There are two
+outcomes, and `evidence.attempts` lists each page tried:
+
+| `evidence.reason` | When | Result |
+|---|---|---|
+| `no_in_scope_page_captured` | The root is out of the built scope and no built entry other than the root is left to try, so nothing was loaded | `skipped`: there is no page whose tags could be measured |
+| `no_capture_page_answered` | At least one page was tried, and every one answered non-2xx or failed to load | `FAIL`/`BLOCKER`: the declared analytics went unmeasured, so a later passing order cannot report the run ready |
+
+Step routing is path-based in every certified family. Page-kit builds each
+page to its own `<route>/index.html`, and QA strips the query string from a
+CampaignSpec route. So `/campaign`, `/campaign/` and `/campaign/index.html` are
+one page, and a query string does not name a different page. A topology page
+whose own URL declares a query (for example `/campaign/?step=checkout`) is
+still never merged into the root on its path alone. Unless its query is
+exactly the root's own (parameter order aside), it does not put the root in
+scope, it is captured as its own entry, and its `capture_page` carries
+`query_routed: true`, since the redacted URL alone would read as the root. An
+entry on a different path is never marked `query_routed`, whatever query it
+carries. A URL with no query of its own names the page at that path whatever
+query the other URL carries.
+
+### Local-serve review (`manual_review`)
+
+A local proof run renders the development environment on purpose (see
+[Local proof mode](#local-proof-mode-deploytarget-local-serve)), and the
+starter templates gate every vendor loader out of that render. A pixel that
+did not fire there is the render's design, not a campaign defect. So on a
+local-serve run, a failing fire-dependent check becomes `manual_review` at
+`warn` instead of a blocker. The fire-dependent checks are
+`analytics-correctness:tag:*`, `analytics-correctness:oob:*` and
+`analytics-correctness:purchase-fires`.
+
+The run qualifies only when all of these hold:
+
+- the packet's `deploy.target` is `local-serve`;
+- the analytics capture target (else the base URL) is a loopback URL;
+- the Assembly Report records the development render:
+  `stages.assembly.evidence.build_environment` is `development`. A production
+  build served on localhost, or a build whose environment was never recorded,
+  keeps its blockers.
+
+Each failing check is then downgraded only when the page it measured is on
+record as loopback. For `tag:*` and `oob:*`, the check's own URL, the passing
+capture's `capture_page.url` and its `final_url` must all be loopback, so a
+built-entry fallback on a remote host, or a localhost root that redirected to
+a production host, keeps the blocker. For `purchase-fires`, there must be at
+least one judged receipt, and every one needs a loopback `receipt_url` and
+`receipt_document_url` (the page URL read after the receipt analytics
+settled). A missing or unparseable URL keeps the blocker.
+
+What always stays a blocker:
+
+- `analytics-correctness:data-layer-purchase:<path>`. It counts the SDK's own
+  `dl_purchase`, which the development render still pushes, so a miss on
+  localhost can be a real defect.
+- A capture or runner failure: `analytics-correctness:runner`, a check whose
+  evidence carries an `error_code`, and a `purchase-fires` reading whose
+  `capture_error_plan_ids` is missing or not empty. The environment explains a
+  silent pixel, not an unmeasured one.
+
+A downgraded check keeps its evidence and adds `reason:
+local_serve_development_render`, `local_serve_status: fail`, the recorded
+`build_environment`, the recorded `production_parity` (`status:
+not_recorded` when none is on the report, with a note unless it passed), and a
+`follow_up`: re-run `qa run` against the PR preview (a production render) with
+`--base-url <preview-url>`. That run gates these checks.
+
 ## Analytics parity (dataLayer / GTM)
 
 The analytics-parity leg proves the live **dataLayer event stream + GTM/pixel
@@ -842,14 +961,22 @@ npm run campaigns-os -- qa run \
 ```
 
 This receipt-to-receipt parity example names `--analytics-candidate`
-explicitly. When that flag is omitted, the candidate is the campaign identity's
-composed root (`public_route_slug` plus `route_root`), not the raw
-`--base-url` value.
+explicitly, and that URL is captured as given. When that flag is omitted, the
+candidate is chosen the same way as the correctness inventory (see
+[Which page the inventory captures](#which-page-the-inventory-captures)): the
+campaign identity's composed root (`public_route_slug` plus `route_root`), not
+the raw `--base-url` value, when it is in scope and answers 2xx, else the first
+built entry that does. `analytics-parity:capture` then records the same
+`capture_page` and `root_fallback` evidence. The candidate is captured before
+the baseline, and when no candidate page is captured the leg emits
+`analytics-parity:capture` alone, without loading the baseline:
+`no_in_scope_page_captured` (skipped) or `no_capture_page_answered`
+(`FAIL`/`BLOCKER`).
 
 | Flag | Meaning |
 |---|---|
 | `--analytics-baseline <url>` | Legacy funnel URL to capture as the parity baseline (enables the leg) |
-| `--analytics-candidate <url>` | Migrated URL to capture; defaults to the identity-composed campaign root |
+| `--analytics-candidate <url>` | Migrated URL to capture as given; defaults to the identity-composed campaign root, or the first built entry when that root is out of the built scope or does not answer |
 | `--analytics-hosts a,b` | Extra host substrings to treat as analytics tag-fires (Everflow is built in) |
 | `--analytics-settle <ms>` | Wait after analytics page loads and after a recognized typed-order receipt for async tags to fire (default 5000); receipt settling must fit inside the order deadline |
 
@@ -1674,6 +1801,19 @@ review. Nested Google Maps/payment keys and inert HTML do not count as campaign
 credentials. This small static grammar deliberately leaves many real pages
 unknown; a literal inside arbitrary code is not proof of effective configuration.
 
+A page script that does not parse is not treated as dynamic. The browser throws
+a `SyntaxError` on it and nothing in it runs, so the binding reads its
+declarations as unavailable (`script_unavailable_or_limit`) and QA adds a
+separate `script-parse:<page_id>` blocker in the same `api-metadata` family.
+Its `actual` names each script by path (inline scripts as `inline script`)
+with the line and column, and its evidence lists a fixed diagnostic category
+per script, never text from the script. Classic scripts are parsed as scripts
+and `type="module"` scripts as modules, with the type stripped of surrounding
+ASCII whitespace and compared case-insensitively as the browser does; classic
+`nomodule` scripts are not fetched or parsed (a module script ignores
+`nomodule` and is parsed), and script srcs resolve against the page's first `<base href>`. Doctor runs the same parse over the built output before deploy; see
+`built_output.script_syntax` in [the Build Packet doc](build-packet.md).
+
 External executable scripts other than the recognized jsDelivr Campaign Cart
 loader/index are inspected only on the page's origin. Each page admits at most
 6 such references; each run fetches at most 24 distinct URLs (deduplicated),

package/docs/release-ledger-authoring-guide.md

@@ -118,7 +118,8 @@ be recorded without the bytes actually moving somewhere.
 ### Fixes that touch only policy-ignored paths
 
 A fix living entirely in paths the policy ignores — `src/` other than
-`src/cli.mjs`, `scripts/`, tests and fixtures — carries a same-surface CHANGELOG
+`src/cli.mjs`, `src/agent/` and `src/doctor/`, `scripts/`, tests and
+fixtures — carries a same-surface CHANGELOG
 section (`X.Y.Z+agent.N`) and **no ledger entry**. There is nothing for an entry
 to claim: every change item must map to a classified changed path in the range,
 and an ignored path is never classified, so an entry written for such a PR is
@@ -127,9 +128,10 @@ path-less item fails the same way, because no classified change of its class
 exists in the range. The ignore list and its stated reasons are in
 [`contracts/agent-relevant-change-policy.v1.json`](../contracts/agent-relevant-change-policy.v1.json).
 
-The dividing line inside `src/` is `src/cli.mjs`: an explicit rule classifies it
-as `cli_surface`, so any change to it is agent-relevant and owes an entry, even
-when the behaviour change originates in a helper module beside it.
+The classified paths inside `src/` are `src/cli.mjs`, `src/agent/` and
+`src/doctor/`: an explicit rule classifies each as `cli_surface`, so any change
+there is agent-relevant and owes an entry, even when the behaviour change
+originates in a helper module beside it.
 
 ### Amendments
 

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.2`.
 
 ## 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.2+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.2+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.2+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.2+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.2+skills.1",
   "spelling": "bundle",
-  "on_disk": "1.41.2+skills.1",
+  "on_disk": "1.43.2+skills.1",
   "on_disk_skill": null,
-  "message": "match (1.41.2+skills.1)"
+  "message": "match (1.43.2+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.2+skills.1)
+Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.43.2+skills.1 — start a fresh session
+Skills revision: unchecked (on disk 1.43.2+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.2",
   "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."
         },

package/schemas/campaign-spec.v4.schema.json

@@ -6,6 +6,8 @@
   "type": "object",
   "additionalProperties": true,
   "required": ["schema_version", "funnels"],
+  "if": { "required": ["spec_identity"], "properties": { "spec_identity": { "required": ["local_spec_id"] } } },
+  "then": { "not": { "required": ["map_id"] } },
   "properties": {
     "schema_version": {
       "enum": ["4.2", "4.3"],
@@ -364,8 +366,10 @@
     "specIdentity": {
       "type": "object",
       "additionalProperties": true,
+      "not": { "required": ["map_id", "local_spec_id"] },
       "properties": {
         "source": { "type": "string", "description": "Observed values: campaign-map-builder, hand-authored-simulation, local-experimental." },
+        "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" },
         "id": { "type": "string" },
         "map_url": { "type": "string" },

package/schemas/campaigns-os-progress-snapshot.v0.schema.json

@@ -71,6 +71,7 @@
         "build_fingerprint_algorithm"
       ],
       "properties": {
+        "local_spec_id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" },
         "map_id": {
           "type": [
             "string",

package/schemas/campaigns-os-qa-verdict-sidecar.v0.schema.json

@@ -29,6 +29,7 @@
       "description": "Same literal as the full verdict — the sidecar is the same contract projected, not a second schema lineage."
     },
     "run_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." },
     "campaign_slug": {
       "type": "string",
       "minLength": 1,

package/schemas/campaigns-os-qa-verdict.v0.schema.json

@@ -29,6 +29,7 @@
       "minLength": 1,
       "description": "The QA run identity, also the verdict filename under qa-output/<map-id>/. The portal receiver additionally restricts it to [A-Za-z0-9_-]{1,64}."
     },
+    "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." },
     "campaign_slug": {
       "type": "string",
       "minLength": 1,

package/schemas/campaigns-os-run-record.v0.schema.json

@@ -155,6 +155,7 @@
       "additionalProperties": false,
       "description": "Best-effort run identity — the join keys that make telemetry useful. Missing identity never blocks capture.",
       "properties": {
+        "local_spec_id": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "Stable repository-owned CampaignSpec identity; never a saved Map ID. Keep unchanged across local revisions. Null or omitted means no local identity." },
         "map_id": { "type": ["string", "null"] },
         "campaign_slug": { "type": ["string", "null"] },
         "template_family": { "type": ["string", "null"] },

package/skills/campaign-lifecycle-orientation/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: campaign-lifecycle-orientation
-version: 1.0.3
+version: 1.0.9
 description: Orient a reader to the Campaigns OS lifecycle artifacts a run has already emitted, without advancing any stage or changing any state.
 ---
 
-Bundle revision: 1.41.2+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.41.2+skills.1`
+Bundle revision: 1.43.2+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.43.2+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read
@@ -70,9 +70,13 @@ output sidecar, theme evidence and normalized inputs
 separate system, and QA then tests a deployed URL
 (`docs/qa-and-test-orders.md`).
 
-Keep the two identities apart. The **Map ID** identifies the saved campaign map
-and keys QA evidence storage; the **public route slug** is the shopper-facing
-path segment. Read both from the packet and never substitute one for the other.
+Keep stable campaign identity separate from routing. The **Map ID** identifies
+a saved campaign map and keys its QA evidence storage. A local-spec packet
+instead carries **local_spec_id**, keeps `map_id` null, and stores QA under
+`local-spec-<local_spec_id>`. The **public route slug** is the shopper-facing
+path segment. Read the packet's identity kind and route separately; a shared
+route cannot make evidence from another local spec belong to this campaign
+(`docs/build-packet.md`, "Local-spec entry").
 
 Campaign pages are typed. The page-type vocabulary is `presell`, `landing`,
 `select`, `checkout`, `upsell`, `downsell` and `thankyou`; `select` is where a
@@ -95,8 +99,9 @@ only from implementation files this skill may not cite, so do not branch on one.
 ## Read the stage record
 
 `campaigns-os next --packet <packet> --json` (tier `A`: it captures a progress
-snapshot under the target and, under Run Telemetry consent, POSTs that
-observation off the machine) reads the recorded state and names the next
+snapshot under the target and, for saved-Map packets under Run Telemetry
+consent, can POST that observation off the machine; local-spec observations
+stay local) reads the recorded state and names the next
 incomplete stage among `setup`, `build`, `polish`, `deploy` and `qa`. That is a
 writing, potentially sending command. If all you need is where the run stands,
 prefer the readback below.

package/skills/campaign-readback-classification/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: campaign-readback-classification
-version: 1.0.3
+version: 1.0.9
 description: Classify a selected campaign from the readback projection's v2 fields and write a read-only handoff without turning diagnosis into permission.
 ---
 
-Bundle revision: 1.41.2+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.41.2+skills.1`
+Bundle revision: 1.43.2+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.43.2+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read