@nextcommerce/campaigns-os 1.50.0 → 1.52.0

package/skills/next-campaigns-os/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-os
-version: 1.0.44
+version: 1.0.47
 description: Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth.
 ---
 
-Bundle revision: 1.50.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.50.0+skills.1`
+Bundle revision: 1.52.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.52.0+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
@@ -95,7 +95,7 @@ Map and run endpoints) with a local CampaignSpec, prepared HTML/assets source, t
    retains each attributed exception as `ready_with_exceptions`, and one
    exception never suppresses another blocker.
 10. Run the package-owned proof path in sequence: ensure `npx --no-install campaigns-os qa install-browser` has completed, run `campaigns-os qa resolve --packet <packet>` (tier `A`: it fetches `--base-url`; `--no-probe` is tier `B` and local), then `campaigns-os qa run --packet <packet> --base-url <url> --browser --test-order common` (tier `C`: it overwrites the stored verdict and assembly report, places real typed-card test orders against the campaign, and posts the verdict and progress; `--no-post-verdict` drops the verdict POST and `--no-remit` the Run Record remit, but both stay tier `C`).
-11. Treat typed-card proof coverage as the control. 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 checkout, 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.
+11. Treat typed-card proof coverage as the control: `qa run` has no permission flag. Test orders still land in the store as real orders (global test cards: no charge, no transaction) that someone may have to cancel. Unless the operator has already said test orders are fine for this campaign, ask once, up front in your first turn with your other setup questions, so the answer covers the whole build and QA and neither stops for it later. `common` runs every actual terminal path when they fit under the flood cap (`--max-test-orders`, 6 by default); above the cap it runs checkout, 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.
 12. Discuss launch only from recorded build, polish, deploy, browser QA, and test-order evidence, or from explicit blockers.
 
 ## Session Intake

package/skills/next-campaigns-os/references/session-intake.md

@@ -141,9 +141,13 @@ hand-edit deployed routing config as the primary promotion path.
 
 ## Test-Order Proof Policy
 
-Treat test orders as cheap, repeatable proof: global test cards bypass the
-gateway and create no transactions, so they need no permission or approval. The
-only real choice is coverage. Record:
+Treat test orders as repeatable proof. `qa run` has no permission flag:
+coverage is its only control. Test orders still land in the store as real
+orders (global test cards: no charge, no transaction) that someone may have to
+cancel. Unless the operator has already said test orders are fine for this
+campaign, ask once, up front in your first turn with your other setup questions,
+so the answer covers the whole build and QA and neither stops for it later.
+Record:
 
 - Coverage: `common` (every actual terminal path when they fit under the flood cap; above it, checkout, first-offer accept/decline, a deduplicated shortest real receipt path, and one decline path per offer or downsell page not yet declined, up to the cap), `off`, `checkout`, `decline`, `accept`, `both`, `full`, or explicit paths such as `decline-decline-accept`.
 - Cart matrix: base cart, base plus bump, specific package refs/quantities.

package/skills/next-campaigns-os-setup/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-os-setup
-version: 2.0.27
+version: 2.0.30
 description: Bootstrap or prepare a target page-kit campaign repo from a doctor-cleared Campaigns OS Build Packet before full build wiring. Formerly installed as next-campaigns-setup; renamed 2026-08 to stop colliding with the published NextCommerceCo/skills scaffolder of that name.
 ---
 
-Bundle revision: 1.50.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.50.0+skills.1`
+Bundle revision: 1.52.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.52.0+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

package/skills/next-campaigns-polish/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-polish
-version: 1.1.28
+version: 1.1.31
 description: Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign.
 ---
 
-Bundle revision: 1.50.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.50.0+skills.1`
+Bundle revision: 1.52.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.52.0+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

package/skills/next-campaigns-qa/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-qa
-version: 1.3.28
+version: 1.3.31
 description: Run spec-aware QA from a saved Map or local-spec Build Packet and tested campaign URL after build, polish, and deploy/local evidence exist, including Playwright typed-card test-order proof.
 ---
 
-Bundle revision: 1.50.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.50.0+skills.1`
+Bundle revision: 1.52.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.52.0+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
@@ -89,7 +89,7 @@ Rules:
 - A typed-card path that fails is classified by **what it did to the store** before the runner decides what to do about it. A failure the runner can prove happened before submit (`not_created`) is **re-run once, if the creation budget has a slot no still-unrun planned path needs** — so a transient miss is not reported as a defect in the build, without an early path eating budget the last planned paths need. Under the default budget a path whose submit was *rejected* has already spent its own slot, so it is not re-run and records `evidence.order_creation.rerun_skipped` instead. When the re-run does happen, both attempts appear in `test_orders[]` and `evidence.retry` names the first attempt's error and ref id. A failure that happened **after** the order was created (`created` — most often a receipt that did not render) is **never resubmitted**: the runner reloads that order's receipt and re-runs only the read-only checks, and `evidence.recovery` carries the original failure, the checks re-run, and whether it cleared. Read `evidence.order_creation` for two separate counts: `submissions_reserved` (platform-side creation slots charged to this path — reserved before a submit click, or charged for a hosted-checkout redirect where no submit click happens — which stand even when the create then failed) and `orders_confirmed_created` (creates the platform was observed to accept) — a spent slot with no confirmed order is the ambiguous case, not an order to reconcile. Recovery clears only on persisted evidence it re-read on that pass: a failed or absent order read-back stops it honestly rather than re-deciding against the original attempt's numbers. An outcome it cannot prove either way (`ambiguous` — an unusable read-back, a lost create response, a network-failed create, a 4xx after an earlier 2xx) stops the path and names the operator check instead of buying again. A pass that only came back after recovery is never indistinguishable from a first-attempt pass, and a failure that survives recovery still blocks.
 - Analytics correctness is two-phase in the same run: the campaign-root visit inventories declared providers/tags only, then the one canonical typed-card run proves Purchase for each topology-recognized receipt from the signals emitted across every page the path loaded after checkout, read after the full `--analytics-settle` window. The receipt qualifies the order; the journey is measured, because the SDK fires `dl_purchase` (and the outbound Purchase) on the first `?ref_id=` page — the upsell page when the funnel has one — and dedupes it on the receipt. It never places a second analytics order. The receipt document's own reading stays in evidence (`receipt_signals`, `fired_on`) as the diagnostic of which document fired.
 - A missing or topology-unrecognized receipt is `MANUAL_REVIEW`/`WARN`; a recognized receipt with no dataLayer, outbound Meta, or outbound GA4 Purchase is `FAIL`/`BLOCKER`. Capture, unreadable-page, and settle-deadline errors on a recognized receipt are explicit non-waivable blockers. The `analytics-correctness:purchase-fires` waiver applies only to a genuine recognized-receipt/no-signal failure, and is recorded with `campaigns-os qa waive --assertion analytics-correctness:purchase-fires --reason "<why>"` (tier `C`: it overwrites the assembly report and doctor output; the lane is scoped to that one assertion and every other is refused).
-- Keep QA in a tight sequence: install the Playwright browser, resolve topology, run browser QA plus typed-card proof with `--test-order common` by default. Test orders need no permission step. Pause only for missing inputs, out-of-scope runtime pages that block checkout proof, or merchant-specific uncertainty.
+- Keep QA in a tight sequence: install the Playwright browser, resolve topology, run browser QA plus typed-card proof with `--test-order common` by default. `qa run` has no permission flag: coverage is its only control. Test orders still land in the store as real orders that someone may have to cancel, so unless the operator has already said test orders are fine for this campaign, ask once, up front in your first turn with your other setup questions. When the operator has answered, at the start of this session or earlier in the build, follow that answer and do not pause QA to ask again. When nobody asked, ask once before the first test order rather than skip the question. Otherwise pause only for missing inputs, out-of-scope runtime pages that block checkout proof, or merchant-specific uncertainty.
 - Use `--browser` for rendered browser evidence. Browser QA must use the package-owned Playwright flow, not external agent/browser skills.
 - Saved-Map QA publishes to the QA portal under the existing consent and flag controls; report the portal link only when publication succeeds. Pass `--no-post-verdict` (or `--local-only`) to keep that verdict local. This stays tier `C`: served-page probes, requested orders, Run Telemetry and progress retain their own controls. See `docs/qa-and-test-orders.md` for the saved-Map publication policy.
 - Local-spec QA always keeps verdicts and progress local. `qa run` suppresses portal publication even with `--post-verdict`; `qa publish` refuses local-spec packets with `local_spec`. Report the local verdict/sidecar as evidence, never a dashboard link. A matching route cannot replace a matching `local_spec_id`, and QA refuses a foreign or stale local Assembly Report. Run Telemetry still follows its consent controls.
@@ -116,11 +116,12 @@ Rules:
 - A path with remaining actions may stop cleanly only at a terminal recognized in that selected topology. Missing accept/decline controls on any other page are blockers. A cross-origin handoff is a valid terminal navigation but is not receipt-rendering or persisted-receipt proof.
 - Keep multi-funnel and `tiers:common` / `tiers:full` plans isolated to each selected checkout's own funnel graph, tiers, and recognized terminals; never borrow an unrelated funnel's receipt page.
 - Accepted-upsell proof is valid only when the browser observes the order upsell API mutation and the final order evidence contains the selected upsell package. A checkout bump line marked `is_upsell` is not accepted-upsell proof.
-- Test orders are safe to fire any time: global test cards bypass the gateway, create no transactions, and need no merchant-specific sandbox routing confirmation. Localhost on any port is globally available as a Campaigns App Development domain and suppresses Campaigns analytics; non-localhost preview/production origins must be allowlisted for the campaign API key so the SDK loads — that is about SDK initialization, not test-order permission.
+- Test orders are real orders in the store, but global test cards bypass the gateway: no charge, no transaction, and no merchant-specific sandbox routing to confirm. Localhost on any port is globally available as a Campaigns App Development domain and suppresses Campaigns analytics; non-localhost preview/production origins must be allowlisted for the campaign API key so the SDK loads — that is about SDK initialization, not test-order permission.
 - Launch readiness is separate from Campaigns OS proof. If QA passes on local/preview, still surface production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration as real-shopper readiness items before launch.
 - For multi-market campaigns, verify at least one non-default currency/country path: currency display, shipping method names/prices, available payment methods, and market-specific copy.
 - Treat missing deploy URL, missing polish status, or unresolved doctor blockers as launch blockers.
 - Report blockers, warnings, and residual risks.
+- At the end of QA, run `next` and present the QC handoff once. Ask the operator which open warnings to accept and why. Run `checkpoint accept` only with the refs, reason, and name the operator gave you in this conversation. Never write `qc_accepts`, `qc_results`, or QA verdict files by hand. The up-front test-order permission does not cover accepts.
 - QA follows build and polish; it does not edit campaign code.
 
 Canonical test-order flow:

package/skills.json

@@ -1,7 +1,7 @@
 {
   "name": "campaigns-os-skills",
   "description": "Skills bundled with Campaigns OS. `skills.sh` installs these into the shared agent skill directories (~/.claude/skills, ~/.codex/skills), so each one is a versioned package: bump the version whenever a package changes. `bundle_revision` identifies the bundle as a whole — `<package version>+skills.<n>`, where the prefix is this package's version and `<n>` counts the skill-text revisions published against it. It advances whenever ANY bundled skill changes, every SKILL.md states it on its first body line, and `campaigns-os tooling status --skills-revision <value>` compares the value an agent read from a skill against the bundle on disk. See docs/skills-revision.md.",
-  "bundle_revision": "1.50.0+skills.1",
+  "bundle_revision": "1.52.0+skills.1",
   "homepage": "https://github.com/NextCommerceCo/campaigns-os",
   "retired_skills": [
     {
@@ -16,7 +16,7 @@
     {
       "id": "next-campaigns-os",
       "name": "Campaigns OS Lifecycle",
-      "version": "1.0.44",
+      "version": "1.0.47",
       "path": "skills/next-campaigns-os/SKILL.md",
       "domain": "campaigns",
       "description": "Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth."
@@ -24,7 +24,7 @@
     {
       "id": "next-campaigns-os-setup",
       "name": "Campaigns OS Setup",
-      "version": "2.0.27",
+      "version": "2.0.30",
       "path": "skills/next-campaigns-os-setup/SKILL.md",
       "domain": "campaigns",
       "description": "Bootstrap or prepare a target page-kit campaign repo from a doctor-cleared Campaigns OS Build Packet before full build wiring. Formerly next-campaigns-setup; renamed to release that name to the published NextCommerceCo/skills scaffolder."
@@ -32,7 +32,7 @@
     {
       "id": "next-campaigns-build",
       "name": "Campaign Build",
-      "version": "1.0.29",
+      "version": "1.0.32",
       "path": "skills/next-campaigns-build/SKILL.md",
       "domain": "campaigns",
       "description": "Assemble a NEXT campaign from a doctor-cleared Build Packet, CampaignSpec/API values, prepared HTML/assets, page-kit, and starter-template contracts."
@@ -40,7 +40,7 @@
     {
       "id": "next-campaigns-polish",
       "name": "Campaign Polish",
-      "version": "1.1.28",
+      "version": "1.1.31",
       "path": "skills/next-campaigns-polish/SKILL.md",
       "domain": "campaigns",
       "description": "Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign."
@@ -48,7 +48,7 @@
     {
       "id": "next-campaigns-qa",
       "name": "Campaign QA",
-      "version": "1.3.28",
+      "version": "1.3.31",
       "path": "skills/next-campaigns-qa/SKILL.md",
       "domain": "campaigns",
       "description": "Run spec-aware QA from a saved Map or local-spec Build Packet and tested campaign URL after build, polish, and deploy/local evidence exist, including Playwright typed-card test-order proof."
@@ -56,7 +56,7 @@
     {
       "id": "campaign-lifecycle-orientation",
       "name": "Campaign Lifecycle Orientation",
-      "version": "1.0.24",
+      "version": "1.0.27",
       "path": "skills/campaign-lifecycle-orientation/SKILL.md",
       "domain": "campaigns",
       "description": "Orient a reader to the Campaigns OS lifecycle artifacts a run has already emitted, without advancing their state: the shared vocabulary, doctor as a gate, the stage record, and the store-theme/Page Kit two-worlds trap."
@@ -64,7 +64,7 @@
     {
       "id": "campaign-run-evidence",
       "name": "Campaign Run Evidence",
-      "version": "1.0.24",
+      "version": "1.0.27",
       "path": "skills/campaign-run-evidence/SKILL.md",
       "domain": "campaigns",
       "description": "Interpret existing doctor, QA verdict and proof-depth evidence without claiming more proof than the artifacts contain, and keep funnel proof apart from merchant launch readiness."
@@ -72,7 +72,7 @@
     {
       "id": "campaign-readback-classification",
       "name": "Campaign Readback Classification",
-      "version": "1.0.24",
+      "version": "1.0.27",
       "path": "skills/campaign-readback-classification/SKILL.md",
       "domain": "campaigns",
       "description": "Classify a selected campaign from the campaigns-os-readback/v2 fields (artifacts, staleness.stale_keys, clean, doctor, divergences, skip_cascades) and write a read-only handoff without turning diagnosis into permission."
@@ -80,7 +80,7 @@
     {
       "id": "contribution-intake",
       "name": "Contribution Intake",
-      "version": "1.0.24",
+      "version": "1.0.27",
       "path": "skills/contribution-intake/SKILL.md",
       "domain": "campaigns",
       "description": "Turn a suggestion about the agent surface into a classified, evidence-checked and redacted proposal, filed on this repository tracker only with attended approval."

package/src/adapter-decision-contract.mjs

@@ -317,7 +317,7 @@ function validateTemplateSlicePaths(copied, location, targetRepo, warnings, read
 
 function checkEnum(value, allowed, code, warnings, addIssue) {
   if (value == null) return;
-  if (!allowed.has(value)) addIssue(warnings, code, `${code} has unknown value "${value}".`);
+  if (!allowed.has(value)) addIssue(warnings, code, `${code} has unknown value ${JSON.stringify(value)}; allowed values: ${[...allowed].join(", ")}.`);
 }
 
 function isObject(value) {

package/src/brand-theme.mjs

@@ -88,6 +88,18 @@ function loadContracts(repoRoot = ROOT) {
   };
 }
 
+// A theme write error as the Assembly Report's theme.warnings[] carries it
+// (schema $defs.themeIssue): detail, when present, must be an object, so an
+// issue without one omits the key rather than writing null.
+export function themeIssueForReport(error) {
+  const detail = error?.detail;
+  return {
+    code: error?.code,
+    message: error?.message,
+    ...(detail && typeof detail === "object" && !Array.isArray(detail) ? { detail } : {}),
+  };
+}
+
 function issue(code, message, detail = null) {
   return detail ? { code, message, detail } : { code, message };
 }

package/src/build-brief.mjs

@@ -12,11 +12,15 @@ export const BUILD_BRIEF_CANDIDATE_FILENAMES = Object.freeze([
   "campaign-build-brief.json",
 ]);
 
+// answer_fields: the brief fields whose values close the question, as
+// evaluateCampaignBuildBrief reads them. The guided-questions warning names
+// them so an answer given in conversation can be written where it counts.
 const REQUIRED_HIGH_IMPACT_FIELDS = Object.freeze([
   {
     id: "page_design_authority",
     priority: 1,
     field: "design_authority",
+    answer_fields: ["design_authority.<page_id>.source"],
     question: "Which source controls each campaign page: the provided design export, the selected template, or a template adapted to another page?",
     reason: "Page-by-page authority prevents checkout, OTO, and receipt pages from drifting into unrelated starter-template composition.",
   },
@@ -24,6 +28,7 @@ const REQUIRED_HIGH_IMPACT_FIELDS = Object.freeze([
     id: "brand_palette_cta",
     priority: 2,
     field: "brand",
+    answer_fields: ["brand.commerce_palette_source", "brand.cta_style"],
     question: "Which palette and CTA style should commerce pages use?",
     reason: "Commerce pages need a business-approved brand layer instead of silent template defaults.",
   },
@@ -31,6 +36,7 @@ const REQUIRED_HIGH_IMPACT_FIELDS = Object.freeze([
     id: "variant_media_rules",
     priority: 3,
     field: "media",
+    answer_fields: ["media.sold_variants", "media.allow_other_variant_colors"],
     question: "Which product variants or colors are actually sold, and may media show other variants?",
     reason: "Variant ambiguity often creates wrong-color carousels and unavailable-product claims.",
   },
@@ -38,6 +44,7 @@ const REQUIRED_HIGH_IMPACT_FIELDS = Object.freeze([
     id: "bundle_pricing_presentation",
     priority: 4,
     field: "offer_presentation.bundle_cards",
+    answer_fields: ["offer_presentation.bundle_cards.primary_price"],
     question: "How should bundle cards present pricing: simple unit price, savings-led, or full accounting?",
     reason: "CampaignSpec owns prices; the brief owns which shopper-facing price story is appropriate.",
   },
@@ -45,13 +52,16 @@ const REQUIRED_HIGH_IMPACT_FIELDS = Object.freeze([
     id: "promo_urgency_copy",
     priority: 5,
     field: "promo_urgency",
-    question: "Which promo, savings, and urgency language is approved for timers, banners, and exit-pop surfaces?",
-    reason: "Promo placeholders and unsupported scarcity claims are business decisions, not implementation details.",
+    answer_fields: ["promo_urgency.header_claim_source", "promo_urgency.timer_label"],
+    answer_hint: 'promo_urgency.header_claim_source "campaign_offers" and promo_urgency.timer_label the template timer\'s label to fill them, or both "none" to remove them',
+    question: "Should the starter template's own promo placeholders (demo countdown timers, promo banners, placeholder voucher codes, exit-pop offers) be filled from this campaign's promo codes and offers, or removed?",
+    reason: "Template promo placeholders must not go live with demo values. The source design's own promo, proof and urgency copy is the merchant's content: it is built as designed and is not part of this question.",
   },
   {
     id: "payment_methods_trust",
     priority: 6,
     field: "commerce_surfaces.payment_methods_allowed",
+    answer_fields: ["commerce_surfaces.payment_methods_allowed"],
     question: "Which payment methods and trust badges may appear?",
     reason: "Templates often carry demo wallets or badges that must not survive without approval.",
   },
@@ -59,6 +69,7 @@ const REQUIRED_HIGH_IMPACT_FIELDS = Object.freeze([
     id: "canonical_display_names",
     priority: 7,
     field: "canonical_display.product_name_source",
+    answer_fields: ["canonical_display.product_name_source"],
     question: "Should CampaignSpec display names win, or may runtime/catalog names override them?",
     reason: "Name drift across source, spec, and runtime data is hard to spot after assembly.",
   },
@@ -66,6 +77,7 @@ const REQUIRED_HIGH_IMPACT_FIELDS = Object.freeze([
     id: "regulated_claims",
     priority: 8,
     field: "campaign_intent.compliance",
+    answer_fields: ["campaign_intent.compliance.approved_benefit_language", "campaign_intent.compliance.forbidden_claims"],
     question: "Are there regulated claims, forbidden phrases, or approved benefit statements the build must follow?",
     reason: "Health, financial, and other regulated offers need explicit copy boundaries.",
     conditional: "regulated",
@@ -227,7 +239,18 @@ export function createCampaignBuildBriefArtifact({
   };
 }
 
-export function validateCampaignBuildBriefArtifact(brief, { spec = null } = {}) {
+// "brand_palette_cta (brand.commerce_palette_source, brand.cta_style)": each
+// open question with the brief fields that close it.
+function describeOpenQuestions(questions) {
+  return questions.map((question) => {
+    const entry = REQUIRED_HIGH_IMPACT_FIELDS.find((candidate) => candidate.id === question?.id);
+    if (isNonEmptyString(entry?.answer_hint)) return `${question?.id} (${entry.answer_hint})`;
+    const fields = entry?.answer_fields || (isNonEmptyString(question?.field) ? [question.field] : []);
+    return fields.length ? `${question?.id} (${fields.join(", ")})` : String(question?.id);
+  }).join(", ");
+}
+
+export function validateCampaignBuildBriefArtifact(brief, { spec = null, normalizedPath = BUILD_BRIEF_NORMALIZED_REL_PATH } = {}) {
   const errors = [];
   const warnings = [];
   const ready = [];
@@ -255,14 +278,20 @@ export function validateCampaignBuildBriefArtifact(brief, { spec = null } = {})
     if (questions.length) {
       errors.push({
         code: "build_brief.questions_unanswered",
-        message: `Prepared Campaign Build Brief has ${questions.length} unresolved business question(s): ${questions.map((question) => question.id).join(", ")}.`,
+        message: `Prepared Campaign Build Brief has ${questions.length} unresolved business question(s): ${describeOpenQuestions(questions)}. Set those fields in the brief file and re-run start or prepare-build.`,
       });
     }
   } else {
     if (questions.length) {
+      // An answer given in conversation is not recorded until it is in a
+      // brief file that start/prepare-build reads: the guided draft is
+      // regenerated on every run, and a brief file replaces it whole.
       warnings.push({
         code: "build_brief.guided_questions",
-        message: `Generated Campaign Build Brief draft has ${questions.length} high-impact business question(s) to confirm: ${questions.map((question) => question.id).join(", ")}.`,
+        message: `Generated Campaign Build Brief draft has ${questions.length} high-impact business question(s) to confirm: ${describeOpenQuestions(questions)}. `
+          + `An answer counts only once it is in a brief file: copy ${normalizedPath} to campaign-build-brief.json in the target repo, set those fields, and re-run start or prepare-build with the same arguments `
+          + "(the file is found there automatically, or pass --brief <file>). The file replaces the draft, so start from the copy to keep the fields the draft already filled. "
+          + "Once a stage has recorded evidence, that re-run needs --force, which clears the evidence.",
       });
     }
     for (const gate of blockerGates) {
@@ -358,6 +387,9 @@ function draftCampaignBuildBrief({ spec, activePages, pageMappings, templateFami
   const paymentMethods = collectSpecPaymentMethods(spec);
   const hasExitPop = activePages?.some((page) => page?.type === "checkout" && page?.exit_intent?.enabled === true) === true;
   const hasOrderBump = hasOrderBumpSignals(spec);
+  // With no CampaignSpec surface to fill them, the template's promo
+  // placeholders are removed: "none" for both.
+  const fillsTemplatePromo = templatePromoSurfaces({ spec, activePages }).length > 0;
 
   return {
     schema_version: BUILD_BRIEF_SCHEMA,
@@ -394,8 +426,8 @@ function draftCampaignBuildBrief({ spec, activePages, pageMappings, templateFami
       },
     },
     promo_urgency: {
-      header_claim_source: hasPromoSignals(spec) ? "campaign_offers" : "none",
-      timer_label: hasPromoSignals(spec) ? null : "Limited-time offer",
+      header_claim_source: fillsTemplatePromo ? "campaign_offers" : "none",
+      timer_label: fillsTemplatePromo ? null : "none",
       show_promo_code_in_timer: false,
       exit_pop: {
         enabled: hasExitPop,
@@ -427,7 +459,7 @@ function draftCampaignBuildBrief({ spec, activePages, pageMappings, templateFami
       brand: "low",
       media: variantSignals.length === 1 ? "medium" : "low",
       offer_presentation: "low",
-      promo_urgency: hasPromoSignals(spec) ? "low" : "medium",
+      promo_urgency: fillsTemplatePromo ? "low" : "medium",
       commerce_surfaces: paymentMethods.length ? "medium" : "low",
       template_family: templateFamily || null,
     },
@@ -466,10 +498,11 @@ function evaluateCampaignBuildBrief(brief, { spec, activePages, pageMappings, so
       options: ["discounted unit price", "savings-led", "full accounting"],
     });
   }
-  if (hasPromoSignals(spec) && (!isNonEmptyString(brief.promo_urgency?.header_claim_source) || !isNonEmptyString(brief.promo_urgency?.timer_label))) {
+  const promoSurfaces = templatePromoSurfaces({ spec, activePages });
+  if (promoSurfaces.length && (!isNonEmptyString(brief.promo_urgency?.header_claim_source) || !isNonEmptyString(brief.promo_urgency?.timer_label))) {
     addQuestion(questions, "promo_urgency_copy", {
-      detail: "CampaignSpec appears to include promo/offer signals, but promo copy authority is incomplete.",
-      options: ["actual voucher code", "bundle savings claim", "no promo banner"],
+      detail: `CampaignSpec maps ${promoSurfaces.join(" and ")}, which would fill the template's promo placeholders. Missing promo_urgency.header_claim_source ("campaign_offers" or "none") or promo_urgency.timer_label (the template timer's label, or "none").`,
+      options: ["fill from the campaign's promo codes and offers", "remove the template's promo placeholders"],
     });
   }
   if (!normalizePaymentList(brief.commerce_surfaces?.payment_methods_allowed).length) {
@@ -638,16 +671,30 @@ export function collectSpecPaymentMethods(spec) {
   return [...methods].sort();
 }
 
-function hasPromoSignals(spec) {
-  let found = false;
-  visitValues(spec, (value, keyPath) => {
-    if (found) return;
-    const path = keyPath.join(".").toLowerCase();
-    if (/(promo|voucher|coupon|discount|offer|timer|urgency|exit_intent)/.test(path) && value != null && value !== false) {
-      found = true;
-    }
-  });
-  return found;
+// The CampaignSpec surfaces that fill a starter template's own promo
+// placeholders: the template's promo banner and countdown timer read
+// funnels[].promo_codes, and its exit-pop offer reads a page's exit_intent or
+// promo_code_input. The campaign's offer catalog and discount pricing are not
+// among them (bundle_pricing_presentation covers those), and neither is any
+// promo, proof or urgency copy of the source design: that is the merchant's
+// content, built as designed.
+function templatePromoSurfaces({ spec = null, activePages = [] } = {}) {
+  const surfaces = [];
+  const funnels = Array.isArray(spec?.funnels) ? spec.funnels : [];
+  if (funnels.some((funnel) => Array.isArray(funnel?.promo_codes) && funnel.promo_codes.length > 0)) {
+    surfaces.push("promo codes (funnels[].promo_codes)");
+  }
+  const pages = Array.isArray(activePages) ? activePages : [];
+  // Checkout-only and enabled: true, the rule hasExitPop, doctor's exit-pop
+  // contract and QA's coupon orders use for these surfaces.
+  const checkoutSurface = (page, key) => page?.type === "checkout" && page?.[key]?.enabled === true;
+  if (pages.some((page) => checkoutSurface(page, "exit_intent"))) {
+    surfaces.push("an exit-intent offer (exit_intent)");
+  }
+  if (pages.some((page) => checkoutSurface(page, "promo_code_input"))) {
+    surfaces.push("a promo-code input (promo_code_input)");
+  }
+  return surfaces;
 }
 
 function hasOrderBumpSignals(value, keyPath = []) {

package/src/built-site-scope.mjs

@@ -16,6 +16,8 @@ import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, join, relative, sep } from "node:path";
 
+import { isFileReadFailure } from "./cart-placeholders.mjs";
+
 const HTML_EXT = ".html";
 
 // The route tokens inferPageType reads for the funnel roles, exported so a
@@ -56,7 +58,26 @@ export function inferPageType(routeOrName) {
   return "page";
 }
 
-function listHtmlFiles(root) {
+// Whether a symbolic link may stand for a built page: its name ends in .html,
+// or its target is a directory, or its target cannot be inspected (missing,
+// EACCES, ELOOP, any file-system error). A link to a regular file (or any
+// other non-directory) not named .html is no page. Only file-system errors
+// are caught; anything else throws.
+function linkMayBePage(full, name) {
+  if (name.toLowerCase().endsWith(HTML_EXT)) return true;
+  try {
+    return statSync(full).isDirectory();
+  } catch (error) {
+    if (!isFileReadFailure(error)) throw error;
+    return true;
+  }
+}
+
+// `links`, when given, collects every symbolic link that may stand for a page
+// (see linkMayBePage). They are never pages themselves (build output holds no
+// links, and a link is not followed), but a caller that must account for every
+// built page can name them.
+function listHtmlFiles(root, links = null) {
   const files = [];
   if (!existsSync(root) || !statSync(root).isDirectory()) return files;
   const walk = (dir) => {
@@ -67,9 +88,11 @@ function listHtmlFiles(root) {
       const full = join(dir, entry.name);
       if (entry.isDirectory()) walk(full);
       else if (entry.isFile() && entry.name.toLowerCase().endsWith(HTML_EXT)) files.push(full);
+      else if (links && entry.isSymbolicLink() && linkMayBePage(full, entry.name)) links.push(full);
     }
   };
   walk(root);
+  links?.sort();
   return files.sort();
 }
 
@@ -101,7 +124,13 @@ function resolveSiteRoot(targetRepo) {
  *
  * @param {string} targetRepo Absolute path to the page-kit target repo (or a
  *   `_site/` directory, or a campaign directory).
- * @param {{ slug?: string|null }} [options]
+ * @param {{ slug?: string|null, includeLinkedPages?: boolean }} [options]
+ *   `includeLinkedPages` adds `linked_pages`: every symbolic link under the
+ *   campaign directory that may stand for a page (named .html, or its target
+ *   a directory, or its target not inspectable; each one entry, its
+ *   `built_path` the link itself; skipped as pages, not followed), in the
+ *   same shape as `pages`. A link to a regular file not named .html is
+ *   dropped. Off by default; without it the result is unchanged.
  * @returns {{
  *   ok: boolean,
  *   error?: string,
@@ -114,7 +143,7 @@ function resolveSiteRoot(targetRepo) {
  *   slug_candidates?: string[],
  * }}
  */
-export function resolveBuiltSiteScope(targetRepo, { slug = null } = {}) {
+export function resolveBuiltSiteScope(targetRepo, { slug = null, includeLinkedPages = false } = {}) {
   const base = { ok: false, target_repo: targetRepo, site_root: null, slug: "", campaign_dir: null, pages: [], html_count: 0 };
   if (!targetRepo || !existsSync(targetRepo) || !statSync(targetRepo).isDirectory()) {
     return { ...base, error: `Built campaign directory does not exist: ${targetRepo}` };
@@ -149,7 +178,7 @@ export function resolveBuiltSiteScope(targetRepo, { slug = null } = {}) {
     return { ...base, site_root: siteRoot, slug: resolvedSlug, error: `Campaign directory does not exist: ${campaignDir}` };
   }
 
-  const pages = listHtmlFiles(campaignDir).map((file) => {
+  const toPage = (file) => {
     const route = routeForFile(campaignDir, file);
     return {
       page_id: pageIdForRoute(route),
@@ -157,10 +186,13 @@ export function resolveBuiltSiteScope(targetRepo, { slug = null } = {}) {
       route,
       built_path: file,
     };
-  });
+  };
+  const links = includeLinkedPages ? [] : null;
+  const pages = listHtmlFiles(campaignDir, links).map(toPage);
+  const linked = links ? { linked_pages: links.map(toPage) } : {};
 
   if (!pages.length) {
-    return { ...base, site_root: siteRoot, slug: resolvedSlug, campaign_dir: campaignDir, error: `No built HTML pages found under ${campaignDir}.` };
+    return { ...base, site_root: siteRoot, slug: resolvedSlug, campaign_dir: campaignDir, ...linked, error: `No built HTML pages found under ${campaignDir}.` };
   }
 
   return {
@@ -171,6 +203,7 @@ export function resolveBuiltSiteScope(targetRepo, { slug = null } = {}) {
     campaign_dir: campaignDir,
     pages,
     html_count: pages.length,
+    ...linked,
   };
 }