@nextcommerce/campaigns-os 1.43.1 → 1.46.0

package/README.md

@@ -47,7 +47,7 @@ steps, in this order:
 mkdir "<route>" && cd "<route>"
 npm init -y && npm i next-campaign-page-kit
 npx campaign-init --non-interactive --template <family> --slug "<route>" --name "<campaign name>"
-npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.37.3
+npm install --save-dev --save-exact @nextcommerce/campaigns-os@<version>
 npx --no-install campaigns-os tooling status --platform claude
 npx --no-install campaigns-os install-skills --platform claude
 mkdir -p source
@@ -57,7 +57,7 @@ The toolkit is also published to npm as `@nextcommerce/campaigns-os`, so the
 CLI can be installed once, globally, instead of pinned per campaign:
 
 ```bash
-npm install -g @nextcommerce/campaigns-os@1.37.3
+npm install -g @nextcommerce/campaigns-os@<version>
 campaigns-os tooling status --platform claude
 campaigns-os install-skills --platform claude
 ```
@@ -73,9 +73,11 @@ runs the full check in an unprivileged job and publishes the verified tarball
 with provenance from a second, environment-gated job.
 
 For an existing page-kit campaign, skip the first three lines and `cd` into it
-(its `package.json` already declares `next-campaign-page-kit`). `1.37.3` is
-an exact published example; choose the release you reviewed, never a floating
-dist-tag for a reproducible build. Commit `package.json` and `package-lock.json`.
+(its `package.json` already declares `next-campaign-page-kit`). `<version>` is
+the exact release you reviewed. The newest published release is npm's `latest`
+(`npm view @nextcommerce/campaigns-os version`), and
+`contracts/release-ledger.json` and `CHANGELOG.md` list every release. Pin the
+exact version, never a floating dist-tag, for a reproducible build. Commit `package.json` and `package-lock.json`.
 `tooling diagnose` requires 1.35.0 or later and `demo` requires 1.37.0 or later.
 A Git source pin remains supported when using an unreleased reviewed commit:
 `npm install --save-dev --save-exact "github:NextCommerceCo/campaigns-os#<full-sha>"`.
@@ -94,7 +96,10 @@ check registry currency or establish trust. On a fresh profile, preflight exits
 use `--platform codex` for a Codex-only profile. Without `--platform`, status
 checks every supported agent profile.
 `install-skills` writes `~/.claude/skills` (`--platform codex` writes
-`~/.codex/skills`), replacing same-name folders; restart the agent after.
+`~/.codex/skills`), replacing same-name folders, and lists each `SKILL.md` it
+wrote under `Read now`. A running agent does not load skills installed after it
+started, so read those files now in the same session; a new session loads them
+on its own.
 Run commands from the campaign folder: `npx` selects its local installation
 even when another global copy is on PATH. A global-only installation prints
 bare commands when its binary matches PATH, or an explicit `node` invocation
@@ -198,8 +203,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).
@@ -232,10 +237,25 @@ Then ask your AI tool to continue from the emitted handoff. Fresh target repos u
 
 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
-rewrite. Page Kit source is HTML with YAML frontmatter and optional Liquid
-helpers. Convert standalone HTML into the target page format first: remove outer
+Standalone HTML mockups: keep them whole and set
+`wrapper_policy: preserve_document_wrappers` in the source-html manifest at
+`<source>/.campaigns-os/source-html-manifest.json` (or pass
+`--wrapper-policy preserve_document_wrappers` to `start`). Source screenshot
+proof must be of the standalone document, so a page kept whole needs no
+conversion; doctor reports its document wrappers as a warning that names the
+decision. For pages without a Figma `design_source`, no exporter is required:
+a hand-written manifest is enough (when any active page's `design_source` is
+Figma, the manifest must pass the Figma provenance gate, which needs the
+exporter's handoff manifest), for example
+`{"schema_version": "source-html-manifest/v0", "wrapper_policy": "preserve_document_wrappers", "pages": [{"page_id": "landing", "path": "landing.html"}]}`
+(schema: `schemas/source-html-manifest.v0.schema.json`; see
+[Selecting the wrapper policy at intake](docs/source-adapters.md#selecting-the-wrapper-policy-at-intake)).
+
+Otherwise, 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 rewrite. Page Kit source is HTML with YAML frontmatter and
+optional Liquid helpers. Convert standalone HTML into the target page format
+first: remove outer
 `<html>`, `<head>`, and `<body>` wrappers, add page frontmatter, move shared
 CSS/assets into the campaign asset tree when useful, root links/assets with
 `campaign_link` and `campaign_asset` when needed, and keep landing/presell
@@ -295,7 +315,8 @@ for a package install the pinned commit is the freshness answer, and there is
 no npm dist-tag to compare against. Neither mode makes agent skills current on
 its own: when skills are stale, run the refresh command the status output
 prints (it names each stale platform, through the same prefix you ran
-`tooling status` with) and restart local agent sessions. Without `--platform`,
+`tooling status` with), then read the `SKILL.md` files it lists under `Read now`
+in the running session (new sessions load them on their own). Without `--platform`,
 status checks only the platforms where Campaigns OS skills are installed.
 
 Run `campaigns-os qa install-browser` (`npm run qa:install-browser` from a

package/agents/claude/CLAUDE.md

@@ -25,7 +25,7 @@ Core rules:
 - Do not copy Olympus-style `shipping_methods` frontmatter into `shop-three-step`; it uses dynamic shipping through `window.next.getShippingMethods()`.
 - Run build/lint checks and record evidence in the assembly report, then hand off to polish. Before Polish becomes terminal or hands off to deploy/QA, install the package-owned Playwright browser with `npm run qa:install-browser`, serve the current build, and run `campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>`.
 - After that checkpoint clears, QA uses the Campaigns OS Node/npm runner: run `campaigns-os qa resolve --packet campaign-runtime.build.json`, then run `campaigns-os qa run --packet campaign-runtime.build.json --base-url <url> --browser --test-order common`.
-- Typed-card test-order proof uses `campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the deployed checkout and rendered upsell controls. `common` runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path when that adds coverage (at most four orders). `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Coverage is the only control — there is no permission/approval step.
+- Typed-card test-order proof uses `campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the deployed checkout and rendered upsell controls. `common` runs every actual terminal path when they fit under the flood cap (`--max-test-orders`, 6 by default); above the cap it runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path, then adds one decline path per offer or downsell page not yet declined, up to the cap, and names any page left out. A page counts as covered only when an order clicks its decline; the `browser-test-order:upsell-action-coverage` verdict row warns naming each page whose decline no order clicked. `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Coverage is the only control — there is no permission/approval step.
 - Analytics correctness is two-phase: the campaign-root visit inventories declared providers/tags only, and the same canonical typed-card run proves Purchase only from the topology-recognized final receipt document after `--analytics-settle`. Missing/unrecognized receipts are manual-review warnings; recognized receipt no-signal and capture/settle errors block. Only the genuine recognized-receipt/no-signal failure is waivable; capture/settle errors are not. Checkout/upsell signals remain whole-journey parity evidence and cannot satisfy a silent receipt.
 - Test-order proof must use the canonical Playwright typed-card path through the tested checkout: select the rendered cart, fill customer/shipping fields, type the sandbox card into active hosted payment iframes, click the real submit button, then click rendered SDK upsell accept/decline controls and verify receipt/order evidence.
 - Do not use `next.getCartData().cartLines` as cart-populated proof; use typed-card order read-back, `cart:updated` payload `items` / `summary.lines`, and rendered bundle DOM evidence.

package/agents/codex/AGENTS.md

@@ -20,7 +20,7 @@ Use this context when working in a target campaign repo with Campaigns OS artifa
 - For `shop-three-step`, keep dynamic shipping via `window.next.getShippingMethods()` and do not add Olympus-style static `shipping_methods` frontmatter.
 - Build hands off to polish. Before Polish becomes terminal or hands off to deploy/QA, install the package-owned Playwright browser with `npm run qa:install-browser`, serve the current build, and run `campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>`.
 - After that checkpoint clears, QA uses the Campaigns OS Node/npm runner: run `campaigns-os qa resolve`, then `campaigns-os qa run --browser --test-order common` against the tested URL.
-- Typed-card test-order proof uses `campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the tested checkout and rendered upsell controls. Global test cards bypass the gateway and create no transactions, so no permission/approval is needed — coverage is the only control. `common` runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path when that adds coverage (at most four orders). `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; non-localhost preview/production origins still need SDK origin allowlist confirmation. Do not use external browser skills, the SDK test-mode event, or hand-built backend API orders as launch proof.
+- Typed-card test-order proof uses `campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the tested checkout and rendered upsell controls. Global test cards bypass the gateway and create no transactions, so no permission/approval is needed — coverage is the only control. `common` runs every actual terminal path when they fit under the flood cap (`--max-test-orders`, 6 by default); above the cap it runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path, then adds one decline path per offer or downsell page not yet declined, up to the cap, and names any page left out. A page counts as covered only when an order clicks its decline; the `browser-test-order:upsell-action-coverage` verdict row warns naming each page whose decline no order clicked. `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; non-localhost preview/production origins still need SDK origin allowlist confirmation. Do not use external browser skills, the SDK test-mode event, or hand-built backend API orders as launch proof.
 - Analytics correctness is two-phase: the campaign-root visit inventories declared providers/tags only, and the same canonical typed-card run proves Purchase only from the topology-recognized final receipt document after `--analytics-settle`. Missing/unrecognized receipts are manual-review warnings; recognized receipt no-signal and capture/settle errors block. Only the genuine recognized-receipt/no-signal failure is waivable; capture/settle errors are not. Checkout/upsell signals remain whole-journey parity evidence and cannot satisfy a silent receipt.
 - Do not use `next.getCartData().cartLines` as cart-populated proof; use typed-card order read-back, `cart:updated` payload `items` / `summary.lines`, and rendered bundle DOM evidence.
 - Campaigns OS proof is not merchant launch readiness. Before launch, confirm production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration.

package/agents/copilot/copilot-instructions.md

@@ -11,4 +11,4 @@ CampaignSpec validation is owned by the public `@nextcommerce/campaigns-os/campa
 
 Preserve Campaign Cart SDK-owned commerce surfaces. Replace starter demo refs from CampaignSpec/API. Prepared AI/exported HTML must be converted into page-kit-ready source first: keep page-owned body markup, strip document wrappers, add YAML frontmatter, move shared CSS/assets into the campaign structure, and use Liquid helpers only for page-kit links/assets/includes. Landing/presell pages can preserve source design; checkout/upsell/downsell/receipt should use starter-template commerce surfaces as SDK contract references while campaign/source owns visual chrome. Copy starter template families atomically with dependent pages, `_includes/`, `_layouts/`, `assets/css/`, and `assets/js/`; do not copy only checkout/receipt pages. Do not claim launch readiness until build, polish, deploy, and QA evidence are recorded.
 
-Before Polish becomes terminal or hands off to deploy/QA, install the package-owned Playwright browser with `npm run qa:install-browser`, serve the current build, and run `campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>`. After that checkpoint clears, QA must use the Campaigns OS Node/npm runner: run `campaigns-os qa resolve`, then run `campaigns-os qa run --browser --test-order common` against the tested URL. Typed-card test-order proof must use `campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the tested checkout and rendered upsell controls; global test cards bypass the gateway and create no transactions, so no permission/approval is needed. `common` runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path when that adds coverage (at most four orders). `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Analytics correctness is two-phase: the campaign-root visit inventories declared providers/tags only, and the same canonical typed-card run proves Purchase only from the topology-recognized final receipt document after `--analytics-settle`. Missing/unrecognized receipts are manual-review warnings; recognized receipt no-signal and capture/settle errors block. Only the genuine recognized-receipt/no-signal failure is waivable; capture/settle errors are not. Checkout/upsell signals remain whole-journey parity evidence and cannot satisfy a silent receipt. Do not use `next.getCartData().cartLines` as cart-populated proof; use typed-card order read-back, `cart:updated` payload `items` / `summary.lines`, and rendered bundle DOM evidence. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; non-localhost preview/production origins still need SDK origin allowlist confirmation. Do not use external browser skills, SDK test-mode events, or direct backend orders as launch proof. Campaigns OS proof is not merchant launch readiness; before launch, confirm production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration.
+Before Polish becomes terminal or hands off to deploy/QA, install the package-owned Playwright browser with `npm run qa:install-browser`, serve the current build, and run `campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>`. After that checkpoint clears, QA must use the Campaigns OS Node/npm runner: run `campaigns-os qa resolve`, then run `campaigns-os qa run --browser --test-order common` against the tested URL. Typed-card test-order proof must use `campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the tested checkout and rendered upsell controls; global test cards bypass the gateway and create no transactions, so no permission/approval is needed. `common` runs every actual terminal path when they fit under the flood cap (`--max-test-orders`, 6 by default); above the cap it runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path, then adds one decline path per offer or downsell page not yet declined, up to the cap, and names any page left out. A page counts as covered only when an order clicks its decline; the `browser-test-order:upsell-action-coverage` verdict row warns naming each page whose decline no order clicked. `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Analytics correctness is two-phase: the campaign-root visit inventories declared providers/tags only, and the same canonical typed-card run proves Purchase only from the topology-recognized final receipt document after `--analytics-settle`. Missing/unrecognized receipts are manual-review warnings; recognized receipt no-signal and capture/settle errors block. Only the genuine recognized-receipt/no-signal failure is waivable; capture/settle errors are not. Checkout/upsell signals remain whole-journey parity evidence and cannot satisfy a silent receipt. Do not use `next.getCartData().cartLines` as cart-populated proof; use typed-card order read-back, `cart:updated` payload `items` / `summary.lines`, and rendered bundle DOM evidence. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; non-localhost preview/production origins still need SDK origin allowlist confirmation. Do not use external browser skills, SDK test-mode events, or direct backend orders as launch proof. Campaigns OS proof is not merchant launch readiness; before launch, confirm production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration.

package/agents/cursor/campaigns-os.mdc

@@ -10,4 +10,4 @@ Read Campaigns OS artifacts before editing campaign pages. Treat CampaignSpec/AP
 
 Do not carry over demo package, shipping, voucher, payment, tracking, footer, or SEO values. Prepared AI/exported HTML must be converted into page-kit-ready source first: keep page-owned body markup, strip document wrappers, add YAML frontmatter, move shared CSS/assets into the campaign structure, and use Liquid helpers only for page-kit links/assets/includes. Preserve prepared landing/presell source HTML when it is a real standalone design. For checkout/upsell/downsell/receipt, use starter-template commerce surfaces as SDK contract references while campaign/source owns visual chrome. Copy starter template families atomically with dependent pages, `_includes/`, `_layouts/`, `assets/css/`, and `assets/js/`; do not copy only checkout/receipt pages. Emit SDK routing meta tags as campaign-root paths such as `/campaign-slug/upsell/`. Preserve SDK-owned checkout/cart/upsell/receipt surfaces. For `shop-three-step`, shipping is dynamic via `window.next.getShippingMethods()`.
 
-Before Polish becomes terminal or hands off to deploy/QA, install the package-owned Playwright browser with `npm run qa:install-browser`, serve the current build, and run `campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>`. After that checkpoint clears, QA uses the Campaigns OS Node/npm runner: `campaigns-os qa resolve`, then `campaigns-os qa run --browser --test-order common` against the tested URL. Test-order proof uses `campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the tested checkout and rendered upsell controls; global test cards bypass the gateway and create no transactions, so no permission/approval is needed. `common` runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path when that adds coverage (at most four orders). `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Analytics correctness is two-phase: the campaign-root visit inventories declared providers/tags only, and the same canonical typed-card run proves Purchase only from the topology-recognized final receipt document after `--analytics-settle`. Missing/unrecognized receipts are manual-review warnings; recognized receipt no-signal and capture/settle errors block. Only the genuine recognized-receipt/no-signal failure is waivable; capture/settle errors are not. Checkout/upsell signals remain whole-journey parity evidence and cannot satisfy a silent receipt. Do not use `next.getCartData().cartLines` as cart-populated proof; use typed-card order read-back, `cart:updated` payload `items` / `summary.lines`, and rendered bundle DOM evidence. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; non-localhost preview/production origins still need SDK origin allowlist confirmation. External browser skills, SDK test-mode events, and direct backend orders are not launch proof. Campaigns OS proof is not merchant launch readiness; before launch, confirm production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration.
+Before Polish becomes terminal or hands off to deploy/QA, install the package-owned Playwright browser with `npm run qa:install-browser`, serve the current build, and run `campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>`. After that checkpoint clears, QA uses the Campaigns OS Node/npm runner: `campaigns-os qa resolve`, then `campaigns-os qa run --browser --test-order common` against the tested URL. Test-order proof uses `campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the tested checkout and rendered upsell controls; global test cards bypass the gateway and create no transactions, so no permission/approval is needed. `common` runs every actual terminal path when they fit under the flood cap (`--max-test-orders`, 6 by default); above the cap it runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path, then adds one decline path per offer or downsell page not yet declined, up to the cap, and names any page left out. A page counts as covered only when an order clicks its decline; the `browser-test-order:upsell-action-coverage` verdict row warns naming each page whose decline no order clicked. `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Analytics correctness is two-phase: the campaign-root visit inventories declared providers/tags only, and the same canonical typed-card run proves Purchase only from the topology-recognized final receipt document after `--analytics-settle`. Missing/unrecognized receipts are manual-review warnings; recognized receipt no-signal and capture/settle errors block. Only the genuine recognized-receipt/no-signal failure is waivable; capture/settle errors are not. Checkout/upsell signals remain whole-journey parity evidence and cannot satisfy a silent receipt. Do not use `next.getCartData().cartLines` as cart-populated proof; use typed-card order read-back, `cart:updated` payload `items` / `summary.lines`, and rendered bundle DOM evidence. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; non-localhost preview/production origins still need SDK origin allowlist confirmation. External browser skills, SDK test-mode events, and direct backend orders are not launch proof. Campaigns OS proof is not merchant launch readiness; before launch, confirm production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration.

package/campaign-spec/dist/rules/analytics-contract-shape.d.ts

@@ -1,8 +1,8 @@
 /**
  * AnalyticsContractShape — validates the optional top-level `analytics` block
  * when present. The block declares a campaign's analytics/attribution/param
- * contract so doctor + QA can validate against intent (cf. the Chamelo Shield
- * `?reviews=n`-has-no-handler QA finding and the Walla Sound Redtrack param
+ * contract so doctor + QA can validate against intent (cf. a production
+ * `?reviews=n`-has-no-handler QA finding and a production Redtrack param
  * conflict — both are gaps that had no declared contract to check against).
  *
  * The block is fully OPTIONAL — a spec without `analytics` is silent (SDK

package/campaign-spec/dist/rules/analytics-contract-shape.js

@@ -1,8 +1,8 @@
 /**
  * AnalyticsContractShape — validates the optional top-level `analytics` block
  * when present. The block declares a campaign's analytics/attribution/param
- * contract so doctor + QA can validate against intent (cf. the Chamelo Shield
- * `?reviews=n`-has-no-handler QA finding and the Walla Sound Redtrack param
+ * contract so doctor + QA can validate against intent (cf. a production
+ * `?reviews=n`-has-no-handler QA finding and a production Redtrack param
  * conflict — both are gaps that had no declared contract to check against).
  *
  * The block is fully OPTIONAL — a spec without `analytics` is silent (SDK

package/campaign-spec/dist/rules/store-profile-shape.d.ts

@@ -3,7 +3,11 @@
  * profile fields introduced in Slice 4f.
  *
  * 1. campaign.store_phone_tel must be a `tel:`-prefixed URI containing
- *    a digit-shaped number when present. The build wires this value
+ *    a digit-shaped number when present. Absent or null means "not
+ *    provided" and is silent. An empty (or whitespace-only)
+ *    string is not a defect: for the nine Store Profile fields an explicit
+ *    "" says the merchant has no such value, and `page-kit sync` blanks
+ *    the starter's demo value with it. The build wires this value
  *    into `<a href="tel:...">` attributes; a value without the scheme
  *    renders a broken link, and a value containing HTML metacharacters
  *    or alternative schemes (javascript:, data:) is rejected as a

package/campaign-spec/dist/rules/store-profile-shape.js

@@ -3,7 +3,11 @@
  * profile fields introduced in Slice 4f.
  *
  * 1. campaign.store_phone_tel must be a `tel:`-prefixed URI containing
- *    a digit-shaped number when present. The build wires this value
+ *    a digit-shaped number when present. Absent or null means "not
+ *    provided" and is silent. An empty (or whitespace-only)
+ *    string is not a defect: for the nine Store Profile fields an explicit
+ *    "" says the merchant has no such value, and `page-kit sync` blanks
+ *    the starter's demo value with it. The build wires this value
  *    into `<a href="tel:...">` attributes; a value without the scheme
  *    renders a broken link, and a value containing HTML metacharacters
  *    or alternative schemes (javascript:, data:) is rejected as a
@@ -42,8 +46,8 @@ export const StoreProfileShape = {
     check(spec) {
         const violations = [];
         const campaign = spec.campaign;
-        // 1. tel: prefix on store_phone_tel.
-        if (campaign?.store_phone_tel !== undefined) {
+        // 1. tel: prefix on store_phone_tel. Absent or null means "not provided".
+        if (campaign?.store_phone_tel !== undefined && campaign?.store_phone_tel !== null) {
             const value = campaign.store_phone_tel;
             if (typeof value !== 'string') {
                 violations.push({
@@ -55,13 +59,7 @@ export const StoreProfileShape = {
                 });
             }
             else if (!isNonEmptyString(value)) {
-                violations.push({
-                    ruleId: 'StoreProfileShape',
-                    severity: 'warning',
-                    message: 'campaign.store_phone_tel is set but empty; remove the field or set a tel:-prefixed value (e.g. "tel:+18005551234").',
-                    path: '/campaign/store_phone_tel',
-                    data: { check: 'store-phone-tel-empty' },
-                });
+                // Intentionally empty: the merchant has no phone yet.
             }
             else {
                 const trimmed = value.trim();

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

@@ -496,8 +496,8 @@ export interface Campaign {
 /**
  * Analytics & attribution contract (Slice 4g) — what a campaign's analytics,
  * tag-management, and querystring-param tracking are SUPPOSED to be, so doctor
- * + QA can validate them instead of discovering gaps in QA (cf. the Chamelo
- * Shield `?reviews=n`-has-no-handler finding and the Walla Sound Redtrack/
+ * + QA can validate them instead of discovering gaps in QA (cf. a production
+ * `?reviews=n`-has-no-handler finding and a production Redtrack/
  * campaign.js sub1-6 param conflict).
  *
  * Modeled on real production-funnel usage, NOT the idealized "SDK fires the

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",