@nextcommerce/campaigns-os 1.55.0 → 1.59.0

package/src/doctor/checks.mjs

@@ -76,7 +76,7 @@ import {
   resolveTemplateBrandContract,
 } from "../private-template-source.mjs";
 import { assessTemplateFreshness, defaultSdkSupportPolicy, renderTemplateFreshness } from "../template-freshness.mjs";
-import { computeBuildFingerprint, resolveBuiltSiteScope } from "../built-site-scope.mjs";
+import { BUILD_DRIFT_PATH_LIMIT, computeBuildFingerprint, describeBuildOutputDrift, resolveBuiltSiteScope } from "../built-site-scope.mjs";
 import {
   UPSELL_SELECTOR_SCOPE,
   builtPageTypeOverRouteGuess,
@@ -93,6 +93,7 @@ import { FIGMA_EXPORT_FILE_CODES, SOURCE_PROVENANCE_SCOPE, evaluateSourceProvena
 import { validateCampaignBuildBriefArtifact } from "../build-brief.mjs";
 import { briefFileUnusable, deriveInputCurrency, wellFormedBriefMaterial } from "../input-currency.mjs";
 import { ASSEMBLY_REPORT_STAGE_KEYS, stageIsTerminal } from "../orchestration-stage-contract.mjs";
+import { assemblyReportStagesWithEvidence } from "../design-source-publication.mjs";
 import {
   assemblySourcePackageFingerprintMissing,
   assessAssemblySourcePackageFreshnessWaivers,
@@ -108,7 +109,7 @@ import { evaluatePageKitSdkVersion, PAGE_KIT_SDK_VERSION_SCOPE } from "../page-k
 // `npm run build:spec` (tsc -> campaign-spec/dist) so the package runs on the
 // node engine in package.json without type-stripping. build runs on `prepare`,
 // so a fresh install (including the git-ref consumer) always has dist.
-import { isReleasedSdkVersion, normalize as normalizeCampaignSpec, runRules, specOnlyRules } from "../../campaign-spec/dist/index.js";
+import { CHECKOUT_FLOW_PAGE_TYPES, checkoutPathFrom, isReleasedSdkVersion, normalize as normalizeCampaignSpec, runRules, specOnlyRules, upgradeCampaignSpec } from "../../campaign-spec/dist/index.js";
 import { cmd, asInvocation } from "../install-invocation.mjs";
 import { specHashesMatch, specMaterialHash } from "../spec-identity.mjs";
 import {
@@ -237,8 +238,12 @@ const US_MARKET_COPY_PATTERNS = [
 const HARDCODED_CURRENCY_REGEX = /\$\s?\d[\d,]*(?:\.\d+)?(?:\/[A-Za-z]+)?/g;
 const HARDCODED_PHONE_REGEX = /\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/g;
 
+// Pages read through here see the v5 vocabulary: a v4 spec's `checkout → checkout`
+// chain is retyped `checkout_step` on read (campaigns-os#641), so every doctor
+// check asks "is this the page that takes payment" of `type === "checkout"`.
 function normalizeFunnels(spec) {
-  if (Array.isArray(spec?.funnels)) return spec.funnels;
+  const upgraded = upgradeCampaignSpec(spec);
+  if (Array.isArray(upgraded?.funnels)) return upgraded.funnels;
   if (Array.isArray(spec?.funnel_pages)) {
     return [{ id: "default", weight: 100, pages: spec.funnel_pages }];
   }
@@ -542,6 +547,11 @@ function validatePacket(packet, packetPath, errors, warnings, ready, derived, bu
     addIssue(errors, "packet.type", "Build Packet must be a JSON object.");
     return;
   }
+  Object.defineProperty(derived, "page_kit_entry_mappings", {
+    value: Object.fromEntries((packet.source_html?.pages || [])
+      .filter((page) => page?.page_kit?.target_path).map((page) => [page.page_id, page])),
+    configurable: true,
+  });
   const synthesizedBuiltSite = isSynthesizedBuiltSitePacket(packet);
   if (packet.schema_version !== PACKET_SCHEMA) addIssue(errors, "schema_version", `Expected ${PACKET_SCHEMA}.`);
   else ready.push(`Build Packet schema ${PACKET_SCHEMA}`);
@@ -1201,17 +1211,20 @@ function paymentLogoForcedOn(html, method) {
 // unless the checkout page passes show_<method>=false.
 export const STARTER_TEMPLATE_DEFAULT_ON_PAYMENT_METHODS = Object.freeze(["paypal", "klarna", "apple_pay", "google_pay"]);
 
-// Built checkout pages on disk for the spec's active checkout pages: the
-// rendered _site/<slug>/<route>/index.html files that exist. Empty before a
-// build (or when the spec declares no checkout page), which is the pre-build
-// state the spec-only advisory covers.
+// Built checkout-flow pages on disk for the spec's active select, checkout_step
+// and checkout pages: the rendered _site/<slug>/<route>/index.html files that
+// exist. Steps and select pages are included on purpose: they carry express
+// payment buttons upstream of the Checkout (campaigns-os#641), and an
+// unsupported method rendered there ships just the same. Empty before a build
+// (or when the spec declares no checkout page), which is the pre-build state
+// the spec-only advisory covers.
 function builtCheckoutPagesForSpec(spec, packet, derived = {}) {
   const targetRepo = derived?.target_repo;
   const publicRouteSlug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
   if (!targetRepo || !publicRouteSlug) return [];
   const built = [];
   for (const page of activeSpecPages(spec)) {
-    if (String(page?.type || page?.page_type || "").toLowerCase().trim() !== "checkout") continue;
+    if (!CHECKOUT_FLOW_PAGE_TYPES.includes(String(page?.type || page?.page_type || "").toLowerCase().trim())) continue;
     const path = builtHtmlPathForPage(targetRepo, publicRouteSlug, page, derived);
     if (!path || !existsSync(path) || !statSync(path).isFile()) continue;
     built.push({ page_id: page.id, path, file: relative(targetRepo, path).split(sep).join("/") });
@@ -1882,12 +1895,33 @@ export function validateBuildOutputFingerprint(packet, errors, warnings, ready,
     );
     return;
   }
+  const drift = describeBuildOutputDrift(buildState.report?.stages?.assembly, current);
+  const capped = (paths) => paths.slice(0, BUILD_DRIFT_PATH_LIMIT);
   addIssue(
     assemblyComplete ? errors : warnings,
     "built_output.fingerprint_stale",
     `Built output under _site/${publicRouteSlug}/ no longer matches stages.assembly.build_fingerprint (recorded ${recorded}, current ${current.fingerprint}, ${current.file_count} file(s)). `
+      + `${drift.summary} `
       + "The output changed after build recorded it; re-run build (page-kit build, then record the current fingerprint) before polish or QA evidence can bind to it.",
-    { root: `_site/${publicRouteSlug}/`, recorded, current: current.fingerprint, file_count: current.file_count, assembly_complete: assemblyComplete }
+    {
+      root: `_site/${publicRouteSlug}/`,
+      recorded,
+      current: current.fingerprint,
+      file_count: current.file_count,
+      assembly_complete: assemblyComplete,
+      drift: drift.manifest === "recorded"
+        ? {
+          manifest: "recorded",
+          extra_count: drift.extra.length,
+          missing_count: drift.missing.length,
+          changed_count: drift.changed.length,
+          extra: capped(drift.extra),
+          missing: capped(drift.missing),
+          changed: capped(drift.changed),
+          conflict_copies: capped(drift.conflict_copies),
+        }
+        : { manifest: "unavailable" },
+    }
   );
 }
 
@@ -2815,7 +2849,7 @@ function bumpDisplaysPresent(block, displays) {
   return displays.some((name) => new RegExp(`data-next-toggle-display\\s*=\\s*["']${name}["']`, "i").test(block));
 }
 
-const CHECKOUT_BUMP_PAGE_TYPES = new Set(["checkout", "select"]);
+const CHECKOUT_BUMP_PAGE_TYPES = new Set(CHECKOUT_FLOW_PAGE_TYPES);
 
 export function validateBuiltBumpPricing(content, builtPath, targetRepo, page, issueTarget) {
   const type = String(page?.type || page?.page_type || "").toLowerCase().trim();
@@ -3000,6 +3034,11 @@ function validateBuiltCommerceRefs(content, builtPath, targetRepo, page, spec, i
 
 function builtHtmlPathForPage(targetRepo, publicRouteSlug, page, derived = {}) {
   if (!targetRepo || !publicRouteSlug) return null;
+  const entryRoute = entryPageKitServingRoute(targetRepo, publicRouteSlug, page, {
+    targetOutputDir: derived?.target_output_dir,
+    mapping: derived?.page_kit_entry_mappings?.[page?.id],
+  });
+  if (entryRoute) return join(targetRepo, "_site", publicRouteSlug, ...(entryRoute.route ? [entryRoute.route] : []), "index.html");
   const sourcePermalink = sourcePermalinkForPage(derived?.target_output_dir, publicRouteSlug, page);
   const route = sourcePermalink || runtimeRelativeRouteForSpecValue(publicRouteForPage(page), publicRouteSlug);
   if (!route) return join(targetRepo, "_site", publicRouteSlug, "index.html");
@@ -3007,6 +3046,63 @@ function builtHtmlPathForPage(targetRepo, publicRouteSlug, page, derived = {}) {
   return clean ? join(targetRepo, "_site", publicRouteSlug, clean, "index.html") : join(targetRepo, "_site", publicRouteSlug, "index.html");
 }
 
+export function isRootRoutedEntryPage(page, publicRouteSlug) {
+  return Boolean(page?.is_entry) && runtimeRelativeRouteForSpecValue(publicRouteForPage(page), publicRouteSlug) === "";
+}
+
+// An explicit permalink belongs to this entry's Page Kit source file. It wins
+// even when an older build left output at the filename-derived route.
+export function entryPageKitServingRoute(targetRepo, publicRouteSlug, page, { targetOutputDir = null, mapping = null } = {}) {
+  if (!targetRepo || !publicRouteSlug || !isRootRoutedEntryPage(page, publicRouteSlug)) return null;
+  const permalink = entrySourcePermalink(targetOutputDir, publicRouteSlug, page, mapping);
+  if (permalink !== null) return { route: permalink, source: "permalink" };
+  const root = join(targetRepo, "_site", publicRouteSlug, "index.html");
+  if (existsSync(root) && statSync(root).isFile()) return { route: "", source: "root" };
+  const fileRoute = entryPageKitFileRoute(targetRepo, publicRouteSlug, page, { targetOutputDir, mapping });
+  return fileRoute ? { route: `${fileRoute}/`, source: "file" } : { route: "", source: "declared" };
+}
+
+function entrySourcePermalink(targetOutputDir, publicRouteSlug, page, mapping) {
+  if (!targetOutputDir || !existsSync(targetOutputDir) || !statSync(targetOutputDir).isDirectory()) return null;
+  const names = mapping?.page_kit?.target_path
+    ? [mapping.page_kit.target_path]
+    : [...new Set([page.id, page.type].filter(isNonEmptyString).map((name) => `${name}.html`))];
+  const routes = names
+    .filter((name) => /^[a-zA-Z0-9][a-zA-Z0-9_-]*\.html$/.test(name))
+    .map((name) => join(targetOutputDir, name))
+    .filter((path) => existsSync(path) && statSync(path).isFile())
+    .map((path) => extractFrontmatterValue(readFileSync(path, "utf8"), "permalink"))
+    .filter(isNonEmptyString)
+    .map((value) => stripPublicRoutePrefix(normalizePageKitRoute(value), publicRouteSlug));
+  return routes[0] ?? null;
+}
+
+// Page Kit serves a page file without a permalink at its basename route.
+// Only the recorded target file (or the family's own materialised stock file)
+// may identify an entry fallback; an unrelated built index is not evidence.
+export function entryPageKitFileRoute(targetRepo, publicRouteSlug, page, { targetOutputDir = null, mapping = null } = {}) {
+  if (!targetRepo || !publicRouteSlug || !isRootRoutedEntryPage(page, publicRouteSlug)) return null;
+  if (entrySourcePermalink(targetOutputDir, publicRouteSlug, page, mapping) !== null) return null;
+  const root = join(targetRepo, "_site", publicRouteSlug, "index.html");
+  if (existsSync(root) && statSync(root).isFile()) return null;
+  let names;
+  if (mapping?.page_kit?.target_path) {
+    names = [mapping.page_kit.target_path];
+  } else {
+    if (!targetOutputDir) return null;
+    names = [...new Set([page.id, page.type].filter(isNonEmptyString).map((name) => `${name}.html`))];
+  }
+  const routes = names
+    .filter((name) => /^[a-zA-Z0-9][a-zA-Z0-9_-]*\.html$/.test(name) && name !== "index.html")
+    .filter((name) => mapping?.page_kit || (existsSync(join(targetOutputDir, name)) && statSync(join(targetOutputDir, name)).isFile()))
+    .map((name) => name.slice(0, -".html".length))
+    .filter((route) => {
+      const built = join(targetRepo, "_site", publicRouteSlug, route, "index.html");
+      return existsSync(built) && statSync(built).isFile();
+    });
+  return routes[0] ?? null;
+}
+
 function sourcePermalinkForPage(targetOutputDir, publicRouteSlug, page) {
   if (!targetOutputDir || !existsSync(targetOutputDir) || !statSync(targetOutputDir).isDirectory()) return null;
 
@@ -3267,7 +3363,7 @@ function collectHardcodedPhoneMatches(scanRoots, storePhone) {
   const matches = [];
   for (const { label: surface, root } of scanRoots) {
     for (const file of collectHtmlFiles(root)) {
-      const content = maskMarketLintIgnoredRegions(readHtmlScanText(join(root, file.path)));
+      const content = maskNonRenderedMarkup(maskMarketLintIgnoredRegions(readHtmlScanText(join(root, file.path))));
       for (const match of content.matchAll(HARDCODED_PHONE_REGEX)) {
         const found = normalizePhoneNumber(match[0]);
         if (!found || found === expected) continue;
@@ -3295,6 +3391,18 @@ function maskMarketLintIgnoredRegions(content) {
     .replace(ignoredTag, preserveNewlinesMask);
 }
 
+// Markup a shopper never reads: HTML comments, <style> blocks, and CSS
+// comments (in style attributes too). Design exports leave long digit runs
+// there, such as a Figma frame name "Group 1000003339", which the phone
+// pattern would otherwise read as a number (campaigns-os#660). Masking keeps
+// offsets and newlines, so reported line numbers stay true.
+function maskNonRenderedMarkup(content) {
+  return content
+    .replace(/<!--[\s\S]*?-->/g, preserveNewlinesMask)
+    .replace(/<style\b[^>]*>[\s\S]*?<\/style\s*>/gi, preserveNewlinesMask)
+    .replace(/\/\*[\s\S]*?\*\//g, preserveNewlinesMask);
+}
+
 function preserveNewlinesMask(value) {
   return value.replace(/[^\n]/g, " ");
 }
@@ -3446,7 +3554,7 @@ function validateSpecPublicRoutes(spec, errors, ready) {
 }
 
 function pageRole(type) {
-  if (["checkout", "upsell", "downsell", "thankyou", "receipt", "select"].includes(type)) return "runtime";
+  if (["checkout", "checkout_step", "upsell", "downsell", "thankyou", "receipt", "select"].includes(type)) return "runtime";
   return "visual";
 }
 
@@ -3550,6 +3658,7 @@ function templateStockDecision(buildState, pageId) {
 function validateSourceCoverage(packet, packetPath, spec, errors, warnings, ready, derived = {}, buildState = {}) {
   const pages = packet.source_html?.pages || [];
   const publicRouteSlug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
+  const routeRoot = campaignRouteRoot(packet);
   const materialisedTemplateStock = [];
   const sourceRoot = resolveFromFile(packetPath, packet.source_html?.root);
   validateSourceHtmlManifestAtRoot(sourceRoot, {
@@ -3577,6 +3686,20 @@ function validateSourceCoverage(packet, packetPath, spec, errors, warnings, read
     }
     mappedIds.add(page.page_id);
     const specPage = activeById.get(page.page_id);
+    const entryRoute = specPage
+      ? entryPageKitServingRoute(derived.target_repo, publicRouteSlug, specPage, {
+        targetOutputDir: derived.target_output_dir,
+        mapping: page,
+      })
+      : null;
+    const builtRoute = entryRoute ? entryRoute.route : specPage ? publicRouteForPage(specPage) : null;
+    const rootOutput = entryRoute?.route ? join(derived.target_repo, "_site", publicRouteSlug, "index.html") : null;
+    if (rootOutput && (entryRoute.source === "file" || entryRoute.source === "permalink")
+      && !(existsSync(rootOutput) && statSync(rootOutput).isFile())) {
+      const emittedRoute = `${routeRoot}${entryRoute.route}`;
+      const pageKitRoot = `/${normalizePublicRouteSlug(publicRouteSlug)}/`;
+      addIssue(warnings, "entry_route.unserved", `CampaignSpec entry page "${specPage.id}" is routed to ${routeRoot}, but Page Kit emitted it at ${emittedRoute} and nothing serves ${routeRoot}. Add a redirect from ${routeRoot} to ${emittedRoute}, or set \`permalink: ${pageKitRoot}\` (the campaign root as Page Kit emits it) on the entry page.`, { page_id: specPage.id, root_route: routeRoot, emitted_route: emittedRoute });
+    }
     if (!activeIds.has(page.page_id)) {
       addIssue(warnings, "source_html.pages.extra", `Source mapping "${page.page_id}" is not an active CampaignSpec page.`);
     }
@@ -3611,7 +3734,7 @@ function validateSourceCoverage(packet, packetPath, spec, errors, warnings, read
             page_id: specPage.id,
             type: specPage.type || "page",
             role: pageRole(specPage.type),
-            route: publicRouteForPage(specPage),
+            route: builtRoute,
             source_path: page.path,
           });
         }
@@ -3627,7 +3750,7 @@ function validateSourceCoverage(packet, packetPath, spec, errors, warnings, read
           page_id: specPage.id,
           type: specPage.type || "page",
           role: pageRole(specPage.type),
-          route: publicRouteForPage(specPage),
+          route: builtRoute,
           source_path: null,
           template_stock: true,
           template_family: family,
@@ -3956,6 +4079,134 @@ function packageRefsFromEntries(entries) {
     .filter((value) => value !== undefined && value !== null && String(value).trim().length > 0)
     .map((value) => String(value));
 }
+
+function supportsCheckoutVariantSlots(agentContract) {
+  const required = frontmatterList(agentContract, "requiredWhenCloning");
+  return required.includes("variant_slots[].id") && required.includes("variant_slots[].quantity");
+}
+
+function selectableVariantMatrixCount(packages) {
+  const selectable = Array.isArray(packages)
+    ? packages.filter((pkg) => pkg && pkg.is_order_bump !== true && pkg.is_upsell !== true)
+    : [];
+  const quantityRows = selectable.filter((pkg) => String(pkg.qty ?? "").trim());
+  if (quantityRows.length <= 1) return 0;
+  const attributeIdentity = (pkg) => {
+    if (!Array.isArray(pkg.variant_attributes) || pkg.variant_attributes.length === 0) return null;
+    const attributes = pkg.variant_attributes.map((attribute) => {
+      const value = String(attribute?.value ?? "").trim();
+      if (!value) return null;
+      return [String(attribute?.code || attribute?.name || "").trim(), value];
+    });
+    return attributes.every(Boolean) ? JSON.stringify(attributes.sort(([a], [b]) => a.localeCompare(b))) : null;
+  };
+  const textIdentity = (key) => (pkg) => {
+    const value = pkg[key];
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+  };
+  for (const identity of [attributeIdentity, textIdentity("product_variant_name")]) {
+    const values = quantityRows.map(identity);
+    if (!values.every(Boolean)) continue;
+    const quantitiesByVariant = new Map();
+    for (const [index, value] of values.entries()) {
+      const qty = String(quantityRows[index].qty).trim();
+      if (!quantitiesByVariant.has(value)) quantitiesByVariant.set(value, new Set());
+      quantitiesByVariant.get(value).add(qty);
+    }
+    return quantitiesByVariant.size > 1 && [...quantitiesByVariant.values()].some((quantities) => quantities.size > 1)
+      ? quantitiesByVariant.size
+      : 0;
+  }
+  return 0;
+}
+
+function warnCheckoutPackageFamilyFit(specPages, family, catalog, warnings, report) {
+  const selectedContract = catalog.families?.[family]?.agentContract;
+  if (
+    !selectedContract ||
+    !isCertifiedTemplateFamily(family, catalog) ||
+    !frontmatterList(selectedContract, "requiredWhenCloning").includes("packages.main_package") ||
+    supportsCheckoutVariantSlots(selectedContract)
+  ) return;
+  const fittingFamilies = [...certifiedTemplateFamilies(catalog)]
+    .filter((candidate) => supportsCheckoutVariantSlots(catalog.families[candidate]?.agentContract))
+    .sort();
+  const checkoutPages = specPages.filter((page) => CHECKOUT_FLOW_PAGE_TYPES.includes(page.type));
+  const byFunnel = new Map();
+  for (const page of checkoutPages) {
+    if (!byFunnel.has(page.funnel_id)) byFunnel.set(page.funnel_id, []);
+    byFunnel.get(page.funnel_id).push(page);
+  }
+  const paths = new Map();
+  for (const page of checkoutPages) {
+    const pages = byFunnel.get(page.funnel_id);
+    const path = checkoutPathFrom(pages, page) || [page];
+    const end = path[path.length - 1];
+    const key = `${page.funnel_id}:${end.id}`;
+    if (!paths.has(key)) paths.set(key, []);
+    const pathPages = paths.get(key);
+    for (const candidate of path) {
+      if (!pathPages.includes(candidate)) pathPages.push(candidate);
+    }
+  }
+  const hasStageEvidence = assemblyReportStagesWithEvidence(report).length > 0;
+  const multiStep = [...paths.values()].some((pathPages) =>
+    pathPages.some((candidate) => candidate.type === "checkout_step" || candidate.type === "select"));
+  for (const pathPages of paths.values()) {
+    const page = pathPages.find((candidate) => selectableVariantMatrixCount(candidate.packages) > 1);
+    if (!page) continue;
+    const variantCount = selectableVariantMatrixCount(page.packages);
+    const shapeMatches = fittingFamilies.filter((candidate) => Boolean(catalog.families[candidate]?.canonicalSurfaces?.selectStep) === multiStep);
+    // The catalog has no base-family field; its family-name prefix is the shared-base convention.
+    const baseMatches = shapeMatches.filter((candidate) => candidate.startsWith(`${family}-`));
+    const ranked = [...baseMatches, ...shapeMatches.filter((candidate) => !baseMatches.includes(candidate))];
+    const action = hasStageEvidence
+      ? "The template family is a build-time decision; changing it requires re-running intake with --force (destructive; clears recorded stage evidence)."
+      : "The family is chosen at intake with --template-family.";
+    addIssue(
+      warnings,
+      "template_contract.checkout_package_fit",
+      `Checkout path through page "${page.id}" has ${variantCount} variants, some offered at several quantities, but template family "${family}" has no configurable variant_slots[] checkout surface. ${ranked.length ? `Families that can present it: ${ranked.join(", ")}.` : "No certified family has a matching configurable variant-slot checkout surface."} ${action}`,
+      { page_id: page.id, funnel_id: page.funnel_id, template_family: family, distinct_product_variants: variantCount, fitting_families: ranked },
+    );
+  }
+}
+// A family that puts package selection on its own `select` page (the catalog
+// names a selectStep surface) and carries no selector on checkout (no
+// mainSelector surface) can only fill the cart from a declared select page.
+// Without one on the path into a Checkout, QA resolves the landing as the
+// entry page, finds no add-to-cart control, and every order path fails after
+// the whole build (campaigns-os#658). Families whose checkout carries its own
+// selector, and families that fill the cart on the landing page, are not
+// affected.
+function warnMissingSelectStep(specPages, family, catalog, warnings) {
+  const surfaces = catalog.families?.[family]?.canonicalSurfaces;
+  if (!surfaces?.selectStep || surfaces.mainSelector) return;
+  const byFunnel = new Map();
+  for (const page of specPages) {
+    if (!byFunnel.has(page.funnel_id)) byFunnel.set(page.funnel_id, []);
+    byFunnel.get(page.funnel_id).push(page);
+  }
+  for (const [funnelId, pages] of byFunnel) {
+    const reachedFromSelect = new Set();
+    for (const select of pages.filter((page) => page.type === "select")) {
+      const path = checkoutPathFrom(pages, select);
+      if (path) reachedFromSelect.add(path[path.length - 1]);
+    }
+    for (const checkout of pages.filter((page) => page.type === "checkout")) {
+      if (reachedFromSelect.has(checkout)) continue;
+      // A split-test path built on another family is judged by that family.
+      const pageFamily = checkout.sdk_hints?.template_family;
+      if (isNonEmptyString(pageFamily) && pageFamily !== family) continue;
+      addIssue(
+        warnings,
+        "template_contract.select_step_missing",
+        `Template family "${family}" puts package selection on a select page, and its checkout carries no selector, but no select page leads to Checkout "${checkout.id}" in funnel "${funnelId}". QA will find no add-to-cart control on the entry page and every order path will fail. Fix: add a Select page between the entry page and checkout in Map Builder.`,
+        { funnel_id: funnelId, checkout_page_id: checkout.id, template_family: family },
+      );
+    }
+  }
+}
 function offerRefsFromEntries(entries) {
   if (!Array.isArray(entries)) return [];
   return entries
@@ -4140,6 +4391,8 @@ export function validateCommerceCatalog(packet, packetPath, spec, errors, warnin
 
     // ADR-003 step 2: template-contract checks ported from the private doctor.
     const specPages = activeSpecPages(spec);
+    warnCheckoutPackageFamilyFit(specPages, family, catalog, warnings, buildState.report);
+    warnMissingSelectStep(specPages, family, catalog, warnings);
 
     const mismatchedFamilies = specPages.filter(
       (page) => isNonEmptyString(page.sdk_hints?.template_family) && page.sdk_hints.template_family !== family
@@ -4153,7 +4406,7 @@ export function validateCommerceCatalog(packet, packetPath, spec, errors, warnin
     }
 
     const checkoutPackageRefs = specPages
-      .filter((page) => page.type === "checkout" || page.type === "select")
+      .filter((page) => CHECKOUT_FLOW_PAGE_TYPES.includes(page.type))
       .flatMap((page) => packageRefsFromEntries(page.packages));
     if (familyAutomatable && contractMentions(contract, /\b(packages\.main_package|single_offer\.package_id|variant_slots)\b/) && checkoutPackageRefs.length === 0) {
       addIssue(
@@ -4268,7 +4521,7 @@ export function validateExitPopContract(contract, spec, family, warnings, ready,
   const exitPop = contract?.exit_pop;
   if (!exitPop || !spec) return;
   const hasGovernedOfferSurface = activeSpecPages(spec).some((page) => (
-    page?.type === "checkout" && (page?.exit_intent?.enabled === true || page?.promo_code_input?.enabled === true)
+    CHECKOUT_FLOW_PAGE_TYPES.includes(page?.type) && (page?.exit_intent?.enabled === true || page?.promo_code_input?.enabled === true)
   ));
   if (hasGovernedOfferSurface) {
     ready.push(`${family} exit-pop/promo-code behavior is governed by CampaignSpec offer-surface fields`);

package/src/doctor/inspect.mjs

@@ -34,6 +34,7 @@ import {
   readJsonIfExists,
   relFromDir,
   isLocalAbsolutePath,
+  portableArtifactPaths,
   addIssue,
 } from "../cli-helpers.mjs";
 import {
@@ -187,18 +188,19 @@ export function doctorCommand(args, { runDoctor = doctorPacket, liveCampaign = u
     commitAssemblyReport(workspace, (report) => recordDoctorStageOutcome(report, result, {
       command: `campaigns-os ${DOCTOR_PRODUCER}`,
       doctorOutPath: workspace.doctorOutPath,
+      targetRepo: workspace.targetRepo,
     }), { stage: "doctor", command: DOCTOR_PRODUCER, refreshDoctor: () => result });
   }
   return result;
 }
 
-function recordDoctorStageOutcome(report, result, { command, doctorOutPath }) {
+function recordDoctorStageOutcome(report, result, { command, doctorOutPath, targetRepo }) {
   return recordProducerStageOutcome(report, {
     stage: "doctor",
     disposition: result.ok ? (result.warnings?.length ? "ready_with_warnings" : "ready") : "blocked",
     timestamp: result.generated_at,
     command,
-    outputs: [doctorOutPath],
+    outputs: portableArtifactPaths([doctorOutPath], targetRepo),
     blockers: (result.errors || []).map((issue) => issue?.message).filter(isNonEmptyString),
     warnings: (result.warnings || []).map((issue) => issue?.message).filter(isNonEmptyString),
   });

package/src/doctor/next-step.mjs

@@ -1,6 +1,6 @@
 // The next step doctor recommends, and the gate issues `next` reads from doctor.
 import { campaignIdentitiesMatch } from "../spec-source-identity.mjs";
-import { polishCarriedForwardForLadder } from "../local-preview-policy.mjs";
+import { NO_CAPTURABLE_ROUTES_CODE, hostedTemplateNeedsUsablePreview, polishCarriedForwardForLadder, polishGateCanCarryPreview } from "../local-preview-policy.mjs";
 import { resolve } from "node:path";
 import { orderPathDepthDriftText } from "../proof-policy.mjs";
 import { anyAssemblyReportStageBlocked, qaRecordedBuildFingerprint, qaRecordedForCurrentBuild } from "../stage-ledger.mjs";
@@ -19,6 +19,7 @@ import {
 import { currentBuildFingerprint, evaluatePolishGate } from "../polish-gate.mjs";
 import { effectiveStageStatus, effectiveStatusIsTerminal } from "../input-currency.mjs";
 import { cmd } from "../install-invocation.mjs";
+import { shellToken } from "../shell-token.mjs";
 import { isObject, isNonEmptyString, optionalString, resolveFromFile, addIssue, filesystemPathsMatch } from "../cli-helpers.mjs";
 import { orderPathDepthDrift } from "./checks.mjs";
 
@@ -412,7 +413,7 @@ export function assessPurchaseProofCoverage({ packet = null, report = null } = {
   };
 }
 
-function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate, purchaseProof = null) {
+function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate, purchaseProof = null, packet = null) {
   const polishGate = derived?.polish_gate || evaluatePolishGate({ report });
   const polishCheckpointGate = derived?.polish_checkpoint_gate || null;
   // prepare-build is the earliest lifecycle prerequisite. Surface its
@@ -519,6 +520,7 @@ function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate
 
   return {
     stage: "done",
+    outcome: "standard_closeout",
     reason: "All stages are in a terminal status (completed / completed_with_warnings / skipped). Pipeline is complete.",
   };
 }
@@ -577,7 +579,7 @@ export const DOCTOR_NEXT_STAGE_OWNERS = NEXT_STAGE_OWNERS;
 // The code -> action strings doctor prints under `Next:`. They describe the
 // repairs the findings ask for and are independent of which stage the picker
 // names, so they survive the picker consolidation unchanged.
-function doctorNextActions(errors, warnings, derived, { polishBlocked, polishGate, polishCheckpointGate, packetRef = derived.packet_path || "<packet>" }) {
+function doctorNextActions(errors, warnings, derived, { polishBlocked, polishGate, polishCheckpointGate, packet = null, packetRef = derived.packet_path || "<packet>" }) {
   const codes = new Set([...errors, ...warnings].map((issue) => issue.code));
   const onlyPolishErrors = doctorErrorsAreOnlyPolishGate(errors);
   const actions = [];
@@ -633,11 +635,17 @@ function doctorNextActions(errors, warnings, derived, { polishBlocked, polishGat
     actions.push(`Target campaign output directory is missing; run ${cmd("next")} setup --packet ${packetRef} before build.`);
   }
   if (polishBlocked) {
-    if (polishGate.status === "blocked") {
+    const needsHostedPreview = hostedTemplateNeedsUsablePreview(packet, polishCheckpointGate);
+    if (needsHostedPreview) {
+      actions.push(`Every mapped page is template stock and needs a hosted preview URL that differs from the production URL. Run ${cmd("qa")} policy set --packet ${packetRef} --preview-url <url>, then run ${cmd("next")} --packet ${packetRef}.`);
+    }
+    if (polishGate.status === "blocked" && (!needsHostedPreview || !polishGateCanCarryPreview(polishGate))) {
       actions.push(`${polishGate.reason} Run next-campaigns-polish and record structured evidence before deploy/QA handoff.`);
     }
-    if (polishCheckpointGate?.status === "blocked") {
-      actions.push(`${polishCheckpointGate.reason} Run ${cmd("polish")} capture before marking Polish complete.`);
+    if (polishCheckpointGate?.status === "blocked" && !needsHostedPreview) {
+      actions.push(polishCheckpointGate.code === NO_CAPTURABLE_ROUTES_CODE
+        ? `${polishCheckpointGate.reason} ${polishCheckpointGate.required_actions?.[0]?.description || "Map a design route and rerun intake before QA."}`
+        : `${polishCheckpointGate.reason} Run ${cmd("polish")} capture before marking Polish complete.`);
     }
   }
   return actions;
@@ -656,7 +664,7 @@ function buildNextStep(errors, warnings, derived, report = null, packet = null,
     && (polishGate.status === "blocked" || polishCheckpointGate?.status === "blocked");
   const codes = new Set([...errors, ...warnings].map((issue) => issue.code));
   const purchaseProof = report ? assessPurchaseProofCoverage({ packet, report }) : null;
-  const picked = pickNextStage(report, { errors, derived }, prepareBuildGate, purchaseProof);
+  const picked = pickNextStage(report, { errors, derived }, prepareBuildGate, purchaseProof, packet);
   // The picker's vocabulary and this table must not drift apart: a stage the
   // table does not know would otherwise be relabelled as an operator step and
   // sliced into the whole ladder. Fail loudly instead.
@@ -665,8 +673,8 @@ function buildNextStep(errors, warnings, derived, report = null, packet = null,
   }
   // An explicit --context / --report is carried into every recommended
   // command, so a recovery reads the same artifacts the recommendation did.
-  const packetRef = `${derived.packet_path || "<packet>"}${sidecarArgs}`;
-  const actions = doctorNextActions(errors, warnings, derived, { polishBlocked, polishGate, polishCheckpointGate, packetRef });
+  const packetRef = `${derived.packet_path ? shellToken(derived.packet_path) : "<packet>"}${sidecarArgs}`;
+  const actions = doctorNextActions(errors, warnings, derived, { polishBlocked, polishGate, polishCheckpointGate, packet, packetRef });
   const deployStatus = String(report?.stages?.deploy?.status || "");
   const deploySatisfied = ["completed", "completed_with_warnings", "ready_with_exceptions"].some((prefix) => deployStatus.startsWith(prefix))
     || Boolean(deployUrlFromReportOutputs(report));
@@ -733,6 +741,7 @@ function buildNextStep(errors, warnings, derived, report = null, packet = null,
     default_skill: owners.default_skill,
     command,
     reason: picked.reason,
+    ...(picked.outcome ? { outcome: picked.outcome } : {}),
     actions: actions.length ? actions : [fallbackAction],
     // Gate-blocked stages stay listed even when the recommended stage is
     // runnable (a Design Source Package change after assembly names build,

package/src/doctor-sidecar.mjs

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { portableArtifactPaths } from "./cli-helpers.mjs";
 
 export const DOCTOR_SIDECAR_REL_PATH = ".campaign-runtime/doctor-output.json";
 export const DOCTOR_SIDECAR_SCHEMA = "campaigns-os-doctor-output/v0";
@@ -61,8 +62,9 @@ export function stampDoctorProducer(doctor, command) {
 // through this (or through `stampDoctorProducer` when its own transactional
 // writer must do the rename), so `generated_by` cannot be skipped by one of
 // them the way #327's cause labels once were.
-export function writeDoctorSidecar(path, doctor, { command } = {}) {
-  writeJsonAtomic(path, stampDoctorProducer(doctor, command));
+export function writeDoctorSidecar(path, doctor, { command, targetRepo = null } = {}) {
+  const stamped = stampDoctorProducer(doctor, command);
+  writeJsonAtomic(path, targetRepo ? portableArtifactPaths(stamped, targetRepo) : stamped);
   return path;
 }
 
@@ -89,7 +91,7 @@ export function markDoctorSidecarStale(targetBaseDir, { command = null, reason =
     stale_reason: reason
       || "A later command changed doctor inputs after this snapshot was written. Re-run campaigns-os doctor (or campaigns-os next) for current state.",
   };
-  writeJsonAtomic(path, stamped);
+  writeJsonAtomic(path, portableArtifactPaths(stamped, targetBaseDir));
   return path;
 }
 

package/src/gate-actions.mjs

@@ -68,10 +68,30 @@ export const HIDDEN_EAGER_MEDIA_ACTIONS = Object.freeze({
     id: "polish.hidden_eager_media.map_design_route",
     kind: "manual",
     command: null,
-    description: "Every mapped page is template stock, so polish capture has nothing to measure. Map at least one page to its design source HTML (source_html.pages[].path) and rerun intake, or prove the campaign on the local preview (deploy.target local-serve served from localhost), where this missing evidence is carried forward as a warning.",
+    description: "Every mapped page is template stock, so there is no design route to measure. Map at least one page to its design source HTML (source_html.pages[].path) and rerun intake, or use a local or hosted preview for QA with the missing evidence carried forward as a warning.",
   }),
 });
 
+export function qaRunCommand(packetPath, url, bumpCart = null) {
+  return `${invocationPrefixFor(PACKAGE_ROOT)} qa run --packet ${packetPath ? shellToken(packetPath) : "<packet>"} --base-url ${url === "<preview-url>" ? url : shellToken(url)} --browser --test-order common${bumpCart ? ` --cart ${shellToken(bumpCart.cart)}` : ""}`;
+}
+
+export function hostedTemplateQaAction(previewUrl) {
+  return {
+    id: "polish.hidden_eager_media.hosted_preview_qa",
+    kind: "command",
+    command: qaRunCommand(null, previewUrl),
+    description: "Run QA against the packet's hosted preview URL; missing Polish evidence remains a warning.",
+  };
+}
+
+export const HOSTED_TEMPLATE_PREVIEW_URL_ACTION = Object.freeze({
+  id: "polish.hidden_eager_media.set_hosted_preview_url",
+  kind: "command",
+  command: "campaigns-os qa policy set --packet <packet> --preview-url <url>",
+  description: "Record a hosted preview URL that differs from the production URL with qa policy set, then run next again; missing Polish evidence can be carried forward on that preview.",
+});
+
 const PACKET_PLACEHOLDER = "--packet <packet>";
 
 // The placeholder becomes the packet this run read, shell-quoted, so the