@nextcommerce/campaigns-os 1.43.2 → 1.47.0

package/src/doctor/checks.mjs

@@ -14,7 +14,12 @@ import {
 import { createDoctorCheckRegistry, runDoctorCheckRegistry } from "../doctor-check-registry.mjs";
 import { evaluateSourcePreparation } from "../source-prep.mjs";
 import { isLoopbackHostname } from "../remit.mjs";
-import { publicRouteForPage } from "../source-html-intake.mjs";
+import {
+  HOST_STRIPPED_CODE,
+  parseHostPrefixedRoute,
+  publicRouteForPage,
+  SDK_ROUTING_META_TAGS,
+} from "../source-html-intake.mjs";
 import {
   readSourceHtmlManifestFile,
   SOURCE_HASH_PATTERN,
@@ -72,12 +77,14 @@ import { assessTemplateFreshness, defaultSdkSupportPolicy, renderTemplateFreshne
 import { computeBuildFingerprint, resolveBuiltSiteScope } from "../built-site-scope.mjs";
 import {
   UPSELL_SELECTOR_SCOPE,
+  builtPageTypeOverRouteGuess,
   evaluateUpsellSelectorScope,
   isPostPurchasePageType,
 } from "../upsell-selector-scope.mjs";
 import { CAMPAIGN_IDENTITY, evaluateCampaignIdentity, externalScriptSources } from "../campaign-identity.mjs";
 import { SDK_MARKUP, evaluateSdkMarkup } from "../sdk-markup.mjs";
 import { SCRIPT_SYNTAX, collectBuiltScriptSyntaxInputs, evaluateBuiltScriptSyntax } from "../built-script-syntax.mjs";
+import { FIGMA_EXPORT_FILE_CODES, SOURCE_PROVENANCE_SCOPE, evaluateSourceProvenanceGates, generatorClaimsFigmaExport, isSourceProvenanceCode } from "./source-provenance.mjs";
 import { validateCampaignBuildBriefArtifact } from "../build-brief.mjs";
 import { ASSEMBLY_REPORT_STAGE_KEYS, stageIsTerminal } from "../orchestration-stage-contract.mjs";
 import {
@@ -86,7 +93,7 @@ import {
   currentBuildFingerprint,
 } from "../polish-gate.mjs";
 import { loadPageKitCampaignEntry, projectPageKitCampaignLoad } from "../page-kit-campaign-config.mjs";
-import { evaluatePageKitStoreProfile, PAGE_KIT_STORE_PROFILE_SCOPE } from "../page-kit-store-profile.mjs";
+import { evaluatePageKitStoreProfile, PAGE_KIT_STORE_PROFILE_SCOPE, storeProfileIntentionallyEmptyNote } from "../page-kit-store-profile.mjs";
 import { evaluatePageKitSdkVersion, PAGE_KIT_SDK_VERSION_SCOPE } from "../page-kit-sdk-version.mjs";
 // ADR-003: the public, canonical CampaignSpec rule registry. The doctor and any
 // campaign authoring UI (e.g. a Map Builder bundle) import the same rules, so a
@@ -110,6 +117,16 @@ import {
   addIssue,
 } from "../cli-helpers.mjs";
 import { resolveCampaignsApiKeySource, describeCampaignKeyRejection } from "../campaigns-api-key.mjs";
+import {
+  LIVE_REF_CODES,
+  campaignDriftMessage,
+  evaluateLiveCampaignRefs,
+  extractRenderedPackageRefs,
+  extractRenderedRefs,
+  extractRenderedShippingRefs,
+  liveRefFindingMessage,
+  liveRefsNotRunMessage,
+} from "../live-campaign-refs.mjs";
 
 const PACKET_SCHEMA = "campaign-runtime-build-packet/v0";
 const CONTEXT_SCHEMA = "campaign-runtime-build-context/v0";
@@ -213,12 +230,6 @@ 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;
 
-const SDK_ROUTING_META_TAGS = [
-  "next-success-url",
-  "next-upsell-accept-url",
-  "next-upsell-decline-url",
-];
-
 function normalizeFunnels(spec) {
   if (Array.isArray(spec?.funnels)) return spec.funnels;
   if (Array.isArray(spec?.funnel_pages)) {
@@ -369,6 +380,11 @@ const SPEC_DOCTOR_CHECKS = createDoctorCheckRegistry([
     phase: "spec",
     run: ({ spec, packet, warnings, ready, derived, buildState }) => validateSpecRoutingMetaTags(spec, packet, warnings, ready, derived, buildState),
   },
+  {
+    id: "spec.routing_host_prefix",
+    phase: "spec",
+    run: ({ spec, packet, errors, ready, derived, buildState }) => validateSpecHostPrefixedRoutes(spec, packet, errors, ready, derived, buildState),
+  },
   {
     id: "source_html.coverage",
     phase: "source",
@@ -399,6 +415,11 @@ const SPEC_DOCTOR_CHECKS = createDoctorCheckRegistry([
     phase: "built-output",
     run: ({ spec, packet, errors, warnings, ready, derived, buildState }) => validateBuiltOutputPages(spec, packet, errors, warnings, ready, derived, buildState),
   },
+  {
+    id: "built_output.live_campaign_refs",
+    phase: "built-output",
+    run: ({ spec, packet, errors, warnings, ready, derived, buildState }) => validateBuiltLiveCampaignRefs(spec, packet, errors, warnings, ready, derived, buildState),
+  },
   {
     id: UPSELL_SELECTOR_SCOPE,
     phase: "built-output",
@@ -884,7 +905,10 @@ export function validateSpecStoreProfile(spec, errors, warnings, ready, { packet
     addIssue(
       errors,
       "spec.store_profile",
-      `CampaignSpec campaign is missing required Store Profile field for page-kit campaigns.json: ${missing.join(", ")}. Add ${missing.map((field) => `campaign.${field}`).join(", ")} to the CampaignSpec Store Profile, then rerun start/prepare-build. Campaigns OS does not infer or silently mutate these storefront/legal values.`,
+      `CampaignSpec campaign is missing required Store Profile field for page-kit campaigns.json: ${missing.join(", ")}. Add ${missing.map((field) => `campaign.${field}`).join(", ")} to the CampaignSpec Store Profile, then rerun start/prepare-build. Campaigns OS does not infer or silently mutate these storefront/legal values.`
+        + (missing.some((field) => typeof campaign[field] === "string")
+          ? ` An explicit "" does not mark a required field as having none; it does so only for the eight optional Store Profile fields.`
+          : ""),
       {
         missing_fields: missing.map((field) => `campaign.${field}`),
         repair: {
@@ -1229,7 +1253,9 @@ function validateTargetStoreProfile(spec, errors, warnings, ready, derived, buil
     addIssue(warnings, gate.code, gate.reason, { checkpoint_gate: gate });
     return;
   }
-  ready.push("Target campaigns.json Store Profile matches the CampaignSpec across all nine governed fields.");
+  const intentionallyEmpty = gate.matrix.filter((row) => row.kind === "intentionally_empty").map((row) => row.field);
+  ready.push("Target campaigns.json Store Profile matches the CampaignSpec across all nine governed fields."
+    + storeProfileIntentionallyEmptyNote(intentionallyEmpty));
 }
 
 function validateSpecShippingCountries(spec, warnings, ready) {
@@ -1284,11 +1310,11 @@ function specPackageRecords(spec) {
   return records;
 }
 
-function specPackageRefs(spec) {
+export function specPackageRefs(spec) {
   return new Set(specPackageRecords(spec).map((record) => String(record.ref)));
 }
 
-function specShippingRefs(spec) {
+export function specShippingRefs(spec) {
   const refs = new Set();
   const add = (method) => {
     const ref = firstCommerceRef(method?.ref_id, method?.id, method?.shipping_method_id);
@@ -1449,26 +1475,31 @@ export function validateBuiltOutputTargetRoot(packet, errors, warnings, ready, d
   );
 }
 
+// R2-B2: the spec only carries unrooted routing-meta *hints*; the page-kit
+// build roots them when it renders _site/<slug>/. Once that built output
+// exists and assembly is complete, validateBuiltSdkMetaTags checks the actual
+// rendered values authoritatively. Re-warning on the spec literal would just
+// repeat a "fix before QA" message the build already satisfied (browser QA
+// later proved the deployed output correct), so the spec-literal checks defer
+// to the built-output check instead of double-flagging.
+function specRoutingMetaDeferred(publicRouteSlug, derived, buildState) {
+  const targetRepo = derived.target_repo;
+  const siteRoot = targetRepo ? join(targetRepo, "_site", publicRouteSlug) : null;
+  return Boolean(isStageComplete(buildState.report, "assembly") && siteRoot && existsSync(siteRoot));
+}
+
 export function validateSpecRoutingMetaTags(spec, packet, warnings, ready, derived = {}, buildState = {}) {
   const publicRouteSlug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
   if (!publicRouteSlug) return;
   const routeRoot = campaignRouteRoot(packet);
 
-  // R2-B2: the spec only carries unrooted routing-meta *hints*; the
-  // page-kit build roots them when it renders _site/<slug>/. Once that built
-  // output exists and assembly is complete, validateBuiltSdkMetaTags checks the
-  // actual rendered values authoritatively. Re-warning on the spec literal here
-  // would just repeat a "fix before QA" message the build already satisfied
-  // (browser QA later proved the deployed output correct), so defer to the
-  // built-output check instead of double-flagging.
-  const targetRepo = derived.target_repo;
-  const siteRoot = targetRepo ? join(targetRepo, "_site", publicRouteSlug) : null;
-  if (isStageComplete(buildState.report, "assembly") && siteRoot && existsSync(siteRoot)) {
+  if (specRoutingMetaDeferred(publicRouteSlug, derived, buildState)) {
     ready.push(`CampaignSpec routing meta deferred to built-output verification (_site/${publicRouteSlug}/).`);
     return;
   }
 
   const hits = [];
+  let hostPrefixed = 0;
   for (const page of activeSpecPages(spec)) {
     const metaTags = page.sdk_hints?.meta_tags;
     if (!isObject(metaTags)) continue;
@@ -1478,11 +1509,18 @@ export function validateSpecRoutingMetaTags(spec, packet, warnings, ready, deriv
       if (!isNonEmptyString(value)) continue;
       const route = value.trim();
       if (isRuntimeRootedRoutingMeta(route, publicRouteSlug, routeRoot)) continue;
+      // A host in front of the path is validateSpecHostPrefixedRoutes'
+      // blocker, not this warning.
+      if (parseHostPrefixedRoute(route, { keepAbsolute: true })) {
+        hostPrefixed += 1;
+        continue;
+      }
       hits.push(`${page.id}:${tag}=${route}`);
     }
   }
 
   if (!hits.length) {
+    if (hostPrefixed) return;
     ready.push(`CampaignSpec SDK routing meta tags are runtime-rooted for ${routeRoot}`);
     return;
   }
@@ -1496,6 +1534,43 @@ export function validateSpecRoutingMetaTags(spec, packet, warnings, ready, deriv
   );
 }
 
+// #531: a route with a host in front of its path ("shop.example.com/route/x/")
+// is nested under the campaign root by every stage that composes a URL
+// (polish capture requested "/route/shop.example.com/route/x/"), so it blocks.
+// prepare-build strips the host from a fresh --map-id fetch at intake but
+// never rewrites a local --spec file or a copy reused with --cached-spec; this
+// catches one that still reaches doctor. An absolute http(s) URL is accepted
+// as before (projection converts a page_url to its path; it is a valid SDK
+// target), so only the bare and protocol-relative forms block. page_url is
+// read by polish and QA whether or not the site is built, so it is always
+// checked; routing meta values follow the spec-literal deferral above.
+export function validateSpecHostPrefixedRoutes(spec, packet, errors, ready, derived = {}, buildState = {}) {
+  const publicRouteSlug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
+  const metaDeferred = publicRouteSlug ? specRoutingMetaDeferred(publicRouteSlug, derived, buildState) : false;
+  const hits = [];
+  for (const page of activeSpecPages(spec)) {
+    const pageUrl = parseHostPrefixedRoute(page.page_url, { keepAbsolute: true });
+    if (pageUrl) hits.push({ page_id: page.id, field: "page_url", value: pageUrl.from, rooted: pageUrl.to });
+    const metaTags = page.sdk_hints?.meta_tags;
+    if (metaDeferred || !isObject(metaTags)) continue;
+    for (const tag of SDK_ROUTING_META_TAGS) {
+      const meta = parseHostPrefixedRoute(metaTags[tag], { keepAbsolute: true });
+      if (meta) hits.push({ page_id: page.id, field: `sdk_hints.meta_tags.${tag}`, value: meta.from, rooted: meta.to });
+    }
+  }
+  if (!hits.length) return;
+
+  const sample = hits.slice(0, 5).map((hit) => `${hit.page_id}:${hit.field} ${JSON.stringify(hit.value)} -> ${JSON.stringify(hit.rooted)}`).join("; ");
+  const more = hits.length > 5 ? `; plus ${hits.length - 5} more` : "";
+  addIssue(
+    errors,
+    "routing_meta.host_prefixed",
+    `CampaignSpec route value(s) carry a host in front of the path, so every page URL built from them nests the host inside the campaign route: ${sample}${more}. `
+      + `Use the rooted form shown after each arrow: edit a local CampaignSpec file to that value (intake never rewrites it); for a saved Map, re-run prepare-build (or start) with --map-id and without --cached-spec so the Map is fetched and normalised (the host is stripped and recorded as ${HOST_STRIPPED_CODE} on the assembly report), or correct the value in the Map.`,
+    { routes: hits }
+  );
+}
+
 // Pages declared out of source scope (#238/#239: a manifest skip_reason entry
 // or CampaignSpec build_scope "partial") assemble from the template family and
 // are not built by a partial-scope build, so their absence from _site/ is the
@@ -1703,6 +1778,94 @@ function validateBuiltOutputPages(spec, packet, errors, warnings, ready, derived
   if (checked > 0) ready.push(`Built HTML structure and commerce refs checked in _site/${publicRouteSlug}/ for ${checked} page(s)`);
 }
 
+// A path from path.relative as the "/"-separated form findings name: on
+// Windows path.relative answers with backslashes, and a page id or file must
+// read the same whichever machine ran doctor. A no-op on POSIX.
+function posixPath(path) {
+  return path.split(sep).join("/");
+}
+
+// Built output under _site/<route>/ that is not a funnel page: the route's
+// 404.html, and anything under a directory whose name starts with "_" or "."
+// (build scratch, hidden directories). The route-root index.html is the
+// landing page and is kept.
+function isLiveRefBuildNoise(routePath) {
+  const segments = routePath.split("/");
+  if (segments.length === 1 && segments[0].toLowerCase() === "404.html") return true;
+  return segments.slice(0, -1).some((segment) => segment.startsWith("_") || segment.startsWith("."));
+}
+
+// Built page refs against the live campaign (#533). The CampaignSpec check
+// above cannot see a campaign that changed after the Map was saved, and skips
+// entirely when the spec lists no shipping methods; this one compares every
+// built page's rendered refs with what the live campaign serves, whatever the
+// spec lists. The read itself happens before doctor runs (it is async and
+// leaves the machine) and arrives as buildState.liveCampaign; without it the
+// check is recorded not_run with its reason, never passed. Page-level misses
+// block at any stage — a page pointing at a method the campaign no longer
+// serves charges the wrong price whether or not assembly is recorded.
+// Unlike the CampaignSpec check, whose scope stays the spec's pages, this one
+// covers every built .html page under _site/<route>/ except build noise that
+// never serves a funnel step: the route's 404.html and anything under a path
+// directory starting with "_" or "." (node_modules is never walked). A page the
+// Map does not list still ships, so it is compared too and named by its path.
+function validateBuiltLiveCampaignRefs(spec, packet, errors, warnings, ready, derived, buildState = {}) {
+  const targetRepo = derived.target_repo;
+  const publicRouteSlug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
+  const siteRoot = targetRepo && publicRouteSlug ? join(targetRepo, "_site", publicRouteSlug) : null;
+  const pages = [];
+  if (siteRoot && existsSync(siteRoot)) {
+    const covered = new Set();
+    for (const page of activeSpecPages(spec)) {
+      const builtPath = builtHtmlPathForPage(targetRepo, publicRouteSlug, page, derived);
+      if (!builtPath || !existsSync(builtPath)) continue;
+      covered.add(resolve(builtPath));
+      pages.push({
+        page_id: page.id,
+        file: posixPath(relFromDir(targetRepo, builtPath)),
+        ...extractRenderedRefs(readFileSync(builtPath, "utf8")),
+      });
+    }
+    for (const html of collectHtmlFiles(siteRoot)) {
+      const builtPath = resolve(siteRoot, html.path);
+      const routePath = posixPath(html.path);
+      if (covered.has(builtPath) || isLiveRefBuildNoise(routePath)) continue;
+      pages.push({
+        page_id: routePath,
+        file: posixPath(relFromDir(targetRepo, builtPath)),
+        in_spec: false,
+        ...extractRenderedRefs(readFileSync(builtPath, "utf8")),
+      });
+    }
+  }
+  if (pages.length === 0) {
+    derived.live_campaign_refs = { status: "not_run", reason_code: "no_built_pages", reason: "No built page to compare against the live campaign.", checked_pages: 0 };
+    return;
+  }
+  const result = evaluateLiveCampaignRefs({
+    pages,
+    map: { package_refs: specPackageRefs(spec), shipping_refs: specShippingRefs(spec) },
+    live: buildState.liveCampaign,
+  });
+  derived.live_campaign_refs = {
+    status: result.status,
+    ...(result.reason_code ? { reason_code: result.reason_code, reason: result.reason } : {}),
+    ...(buildState.liveCampaign?.key_source ? { key_source: buildState.liveCampaign.key_source } : {}),
+    checked_pages: result.checked_pages,
+    page_findings: result.page_findings,
+    drift: result.drift,
+  };
+  if (result.status === "not_run") {
+    if (result.attempted) addIssue(warnings, LIVE_REF_CODES.notRun, liveRefsNotRunMessage(result), { reason_code: result.reason_code, ...(result.http_status !== undefined ? { http_status: result.http_status } : {}) });
+    return;
+  }
+  for (const finding of result.page_findings) {
+    addIssue(errors, finding.code, liveRefFindingMessage(finding), { page_id: finding.page_id, file: finding.file, ...(finding.in_spec === false ? { in_spec: false } : {}), refs: finding.refs });
+  }
+  if (result.drift) addIssue(warnings, LIVE_REF_CODES.drift, campaignDriftMessage(result.drift), { drift: result.drift });
+  if (result.status === "pass") ready.push(`Built page shipping and package refs are served by the live campaign (${result.checked_pages} page(s))`);
+}
+
 // Upsell selector scope (#270). Every doctor invocation, deliberately — not
 // only the one that follows assembly. The real-world instance was introduced by
 // a LATER human review round that layered a correctly-scoped selector on top of
@@ -1733,15 +1896,21 @@ function validateUpsellSelectorScope(spec, packet, errors, warnings, ready, deri
     for (const builtPage of (scope.ok ? scope.pages : [])) {
       const declared = declaredByPath.get(resolve(builtPage.built_path)) || null;
       // Declared type wins only when it is the post-purchase answer; otherwise
-      // the route-inferred type stands. Same fail-closed rule the evaluator
-      // applies between a declared type and the page's own next-page-type meta:
-      // any signal saying "post-purchase" is enough.
+      // the route-inferred type stands, unless the route is ambiguous (an
+      // "oto" route, never an explicit upsell/downsell one) and the page's
+      // own next-page-type meta declares it a checkout (#529). Same
+      // fail-closed rule the evaluator applies between a declared type and the
+      // page's own next-page-type meta: any declaration saying "post-purchase"
+      // is enough.
       const declaredType = declared?.type || null;
+      const content = readFileSync(builtPage.built_path, "utf8");
       pages.push({
         page_id: declared?.id || builtPage.page_id,
-        page_type: isPostPurchasePageType(declaredType) ? declaredType : builtPage.page_type,
+        page_type: isPostPurchasePageType(declaredType)
+          ? declaredType
+          : builtPageTypeOverRouteGuess({ route: builtPage.route, route_type: builtPage.page_type, content }),
         file: relFromDir(targetRepo, builtPage.built_path),
-        content: readFileSync(builtPage.built_path, "utf8"),
+        content,
       });
     }
   }
@@ -2137,7 +2306,7 @@ function validateBuiltHtmlStructure(content, builtPath, targetRepo, page, spec,
 // leg: where QA confirms a content param FIRES on a live page, this confirms the
 // built page even HAS a handler for it — catching the gap before QA runs.
 //
-// Specifically the "?reviews=n with no handler" case from the Chamelo Shield
+// Specifically the "?reviews=n with no handler" case from a production
 // build: the spec (or a synthesized one) declares a content param, but the
 // built page never wired `data-next-hide="param.<name>=='n'"`, so the param
 // silently no-ops. Only fires when the spec declares `analytics.params.content`;
@@ -2168,7 +2337,7 @@ export function validateBuiltAnalyticsContract(content, builtPath, targetRepo, p
       addIssue(
         issueTarget,
         "analytics_contract.content_param_no_handler",
-        `Built page "${page.id}" declares analytics content param "?${name}" but has no data-next-hide/show="param.${name}…" handler. The param will silently no-op — the Chamelo Shield "?reviews=n with no handler" gap.`,
+        `Built page "${page.id}" declares analytics content param "?${name}" but has no data-next-hide/show="param.${name}…" handler. The param will silently no-op — the "?reviews=n with no handler" gap.`,
         { page_id: page.id, file: relPath, param: name },
       );
     }
@@ -2426,30 +2595,6 @@ function validateBuiltCommerceRefs(content, builtPath, targetRepo, page, spec, i
   }
 }
 
-function extractRenderedPackageRefs(content) {
-  const refs = new Set();
-  for (const match of content.matchAll(/\bdata-next-package-id=["']([^"']+)["']/gi)) addRenderedRef(refs, match[1]);
-  for (const match of content.matchAll(/\bdata-package-id=["']([^"']+)["']/gi)) addRenderedRef(refs, match[1]);
-  for (const match of content.matchAll(/["']?packageId["']?\s*:\s*(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_-]+))/gi)) {
-    addRenderedRef(refs, match[1] || match[2] || match[3]);
-  }
-  return refs;
-}
-
-function extractRenderedShippingRefs(content) {
-  const refs = new Set();
-  for (const match of content.matchAll(/\bdata-next-shipping-id=["']([^"']+)["']/gi)) addRenderedRef(refs, match[1]);
-  for (const match of content.matchAll(/["']?shippingId["']?\s*:\s*(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_-]+))/gi)) {
-    addRenderedRef(refs, match[1] || match[2] || match[3]);
-  }
-  return refs;
-}
-
-function addRenderedRef(refs, value) {
-  const ref = String(value || "").trim();
-  if (/^[A-Za-z0-9_-]+$/.test(ref)) refs.add(ref);
-}
-
 function builtHtmlPathForPage(targetRepo, publicRouteSlug, page, derived = {}) {
   if (!targetRepo || !publicRouteSlug) return null;
   const sourcePermalink = sourcePermalinkForPage(derived?.target_output_dir, publicRouteSlug, page);
@@ -2921,25 +3066,43 @@ function summarizeScopePages(pages) {
  * HTML for this page" message so unknown types don't crash the operator's UX.
  *
  * @param {object} page Active spec page (may carry `design_source`).
+ * @param {{ figmaGate?: boolean }} [options] figmaGate: some active page's design_source is
+ *   Figma, so the manifest must pass the Figma producer-provenance gate.
  * @returns {string}
  */
-function coverageErrorMessage(page) {
+function coverageErrorMessage(page, { figmaGate = false } = {}) {
   const designSource = page && isObject(page.design_source) ? page.design_source : null;
   if (designSource) {
     const fileUrl = optionalString(designSource.file_url);
     if (designSource.type === "figma" && fileUrl) {
-      return `Active CampaignSpec page "${page.id}" has no source mapping. Design is in Figma at ${fileUrl}; supply the source-html manifest for the page (see docs/design-source-package.md) — the exporter that produced the design emits it — then rerun prepare-build.`;
+      // A Figma page's manifest must pass the producer-provenance gate
+      // (validateSourceProducerProvenance): the exporter's manifest does, and a
+      // hand-written one needs a recorded named-human waiver.
+      return `Active CampaignSpec page "${page.id}" has no source mapping. Design is in Figma at ${fileUrl}. The Figma provenance gate (source_html.producer_provenance) needs the exporter's handoff manifest (the exporter that produced the design emits it): re-run the figma-sections-export handoff so it writes <source-root>/.campaigns-os/source-html-manifest.json with this page mapped (see docs/design-source-package.md), then rerun prepare-build. If the approved source is hand-written HTML and the Figma file only renders it, write the manifest by hand and record a named-human waiver for the Figma provenance check: campaigns-os checkpoint waive --packet <packet> --gate ${SOURCE_PROVENANCE_SCOPE} --page ${page.id} --reason "<reason>" --waived-by "<named human>" --expires-at <ISO>.`;
     }
     if (designSource.type === "ai-generated") {
       const fileUrlHint = fileUrl ? ` (design reference: ${fileUrl})` : "";
-      return `Active CampaignSpec page "${page.id}" has no source mapping. design_source.type="ai-generated"${fileUrlHint} — re-run the producing agent so the source HTML and source-html manifest land in the source root, then rerun prepare-build. See docs/entry-points.md for the AI-generated entry point contract.`;
+      return `Active CampaignSpec page "${page.id}" has no source mapping. design_source.type="ai-generated"${fileUrlHint} — re-run the producing agent so the source HTML and source-html manifest land in the source root, then rerun prepare-build. ${sourceManifestHint(page, figmaGate)} See docs/entry-points.md for the AI-generated entry point contract.`;
     }
     if (!fileUrl) {
       return `Active CampaignSpec page "${page.id}" has no source mapping. design_source is set but file_url is missing — add file_url to the spec before requesting a build.`;
     }
-    return `Active CampaignSpec page "${page.id}" has no source mapping. design_source.type="${designSource.type}" at ${fileUrl}; produce the source HTML for this page (or update design_source.type to a recognized producer — see docs/entry-points.md) before rerunning prepare-build.`;
+    return `Active CampaignSpec page "${page.id}" has no source mapping. design_source.type="${designSource.type}" at ${fileUrl}; produce the source HTML for this page (or update design_source.type to a recognized producer — see docs/entry-points.md) before rerunning prepare-build. ${sourceManifestHint(page, figmaGate)}`;
   }
-  return `Active CampaignSpec page "${page.id}" has no source mapping.`;
+  return `Active CampaignSpec page "${page.id}" has no source mapping. ${sourceManifestHint(page, figmaGate)} Then rerun prepare-build.`;
+}
+
+// Where a page without a Figma design_source is mapped. Hand-written HTML has
+// no exporter, so the hint gives the path, the schema and an entry to write by
+// hand, unless an active page's design_source is Figma (hasFigmaDesignSource):
+// then the whole manifest is held to the Figma provenance gate, which a
+// hand-written manifest cannot pass.
+function sourceManifestHint(page, figmaGate) {
+  const location = "Map the page in the source-html manifest at <source-root>/.campaigns-os/source-html-manifest.json (schema: schemas/source-html-manifest.v0.schema.json; see docs/build-packet.md#source-html-manifest-auto-population).";
+  if (figmaGate) {
+    return `${location} The CampaignSpec has an active page whose design_source is Figma, so this manifest must also pass the Figma provenance gate (source_html.producer_provenance), which needs the exporter's handoff manifest.`;
+  }
+  return `${location} No exporter is required: for hand-written HTML, write the file yourself. A minimal one: {"schema_version": "source-html-manifest/v0", "pages": [{"page_id": "${page.id}", "path": "<file>.html"}]}; for standalone HTML documents kept whole, add "wrapper_policy": "preserve_document_wrappers".`;
 }
 
 /**
@@ -2992,6 +3155,8 @@ function validateSourceCoverage(packet, packetPath, spec, errors, warnings, read
     warnings,
     ready,
     manifestPath: recordedDesignManifestPath(packet, packetPath),
+    waivers: buildState?.report?.waivers,
+    derived,
   });
   const active = activeSpecPages(spec);
   const specPartialScope = spec?.build_scope?.mode === "partial";
@@ -3092,9 +3257,10 @@ function validateSourceCoverage(packet, packetPath, spec, errors, warnings, read
     ready.push(`Template-stock page(s) materialised by the build stage: ${materialisedTemplateStock.map((entry) => `${entry.page_id} (${entry.family})`).join(", ")}`);
   }
 
+  const figmaGate = active.some(hasFigmaDesignSource);
   for (const page of active) {
     if (!mappedIds.has(page.id)) {
-      addIssue(errors, "source_html.pages.coverage", coverageErrorMessage(page), coverageErrorDetail(page));
+      addIssue(errors, "source_html.pages.coverage", coverageErrorMessage(page, { figmaGate }), coverageErrorDetail(page));
     }
   }
 
@@ -3197,7 +3363,7 @@ function recordedDesignManifestPath(packet, packetPath) {
   return recorded ? resolve(dirname(packagePath), recorded) : null;
 }
 
-function validateSourceHtmlManifestAtRoot(sourceRoot, { spec, errors, warnings, ready, manifestPath = null } = {}) {
+function validateSourceHtmlManifestAtRoot(sourceRoot, { spec, errors, warnings, ready, manifestPath = null, waivers = null, derived = null } = {}) {
   if (!isNonEmptyString(sourceRoot) || !existsSync(sourceRoot) || !statSync(sourceRoot).isDirectory()) return;
   const result = readSourceHtmlManifestFile(sourceRoot, { manifestPath });
   if (!result.path) return;
@@ -3213,49 +3379,123 @@ function validateSourceHtmlManifestAtRoot(sourceRoot, { spec, errors, warnings,
   for (const warning of result.warnings || []) {
     addIssue(warnings, "source_html.manifest", warning);
   }
-  validateSourceProducerProvenance(result.manifest, { spec, errors, warnings, ready });
+  validateSourceProducerProvenance(result.manifest, { spec, errors, warnings, ready, waivers, derived });
   ready.push(`Source-html manifest ${SOURCE_HTML_MANIFEST_SCHEMA} validated`);
 }
 
-function validateSourceProducerProvenance(manifest, { spec, errors, warnings, ready }) {
+function validateSourceProducerProvenance(manifest, { spec, errors, warnings, ready, waivers = null, derived = null }) {
   const generator = optionalString(manifest?.generator) || "";
   const rawProvenance = manifest?.producer_provenance;
   const provenance = isObject(rawProvenance) ? rawProvenance : {};
-  const expectsFigma = generator.startsWith("figma-sections-export@") || activeSpecPages(spec).some(hasFigmaDesignSource);
+  const generatorClaimsFigma = generatorClaimsFigmaExport(generator);
+  const figmaPages = activeSpecPages(spec).filter(hasFigmaDesignSource);
+  const expectsFigma = generatorClaimsFigma || figmaPages.length > 0;
+  const findings = expectsFigma ? collectFigmaProvenanceFindings(manifest, provenance, rawProvenance) : [];
+  const provenanceBlockers = findings.filter((finding) => finding.severity === "provenance");
+
+  // One source-provenance checkpoint per Figma-typed page (#534).
+  const { gates, inert } = evaluateSourceProvenanceGates({
+    pages: figmaPages.map((page) => ({
+      page_id: page.id,
+      design_source: {
+        type: optionalString(page.design_source?.type) || null,
+        file_url: optionalString(page.design_source?.file_url) || null,
+      },
+    })),
+    blockingCodes: provenanceBlockers.map((finding) => finding.code),
+    generatorClaimsExport: generatorClaimsFigma,
+    waivers,
+  });
+  if (Array.isArray(derived?.checkpoint_gates)) derived.checkpoint_gates.push(...gates);
+  const inertTotal = Object.values(inert.counts).reduce((sum, count) => sum + count, 0);
+  if (inertTotal > 0) {
+    addIssue(
+      warnings,
+      `${SOURCE_PROVENANCE_SCOPE}.waiver_inert`,
+      `Source-provenance waiver history contains ${inertTotal} inert record(s); stale, foreign, malformed, and expired decisions, decisions for pages that no longer have a Figma design source${inert.pages.length ? ` (${inert.pages.join(", ")})` : ""}, and decisions under a manifest whose generator claims figma-sections-export never satisfy the current checkpoint.`,
+      { counts: inert.counts, pages: inert.pages },
+    );
+  }
   if (!expectsFigma) return;
 
+  // The waivable family (source_html.producer_provenance* and the export's
+  // file inventory) is reported once per Figma-typed page that demands it:
+  // as errors naming an unwaived page, and as warnings carrying `waived: true`
+  // naming a waived page. When the manifest's own generator claims
+  // figma-sections-export, the manifest demands them itself, so they are
+  // reported once, manifest-wide, as errors no page waiver can clear. Every
+  // other finding keeps its severity.
+  const waived = gates.filter((gate) => gate.status === "waived");
+  for (const finding of findings) {
+    if (finding.severity === "warning") {
+      addIssue(warnings, finding.code, finding.message);
+    } else if (generatorClaimsFigma) {
+      addIssue(errors, finding.code, finding.message, { generator, pages: figmaPages.map((page) => page.id) });
+    } else {
+      for (const gate of gates) {
+        const pageId = gate.subject.page_id;
+        if (gate.status === "waived") {
+          addIssue(
+            warnings,
+            finding.code,
+            `Page "${pageId}": ${finding.message} Waived by ${gate.waiver.waived_by}: the approved source is hand-written HTML.`,
+            { waived: true, page_id: pageId, waiver: gate.waiver },
+          );
+        } else {
+          addIssue(errors, finding.code, `Page "${pageId}" has a Figma design source: ${finding.message}`, { page_id: pageId });
+        }
+      }
+    }
+  }
+
+  if (!generatorClaimsFigma && waived.length > 0) {
+    const waivedPageIds = waived.map((gate) => gate.subject.page_id);
+    const waivedBy = [...new Set(waived.map((gate) => gate.waiver.waived_by))].join(", ");
+    ready.push(`Figma producer provenance accepted under named-human exception for page(s) ${waivedPageIds.join(", ")} (${waivedBy}).`);
+  }
+  if (errors.every((issue) => !isSourceProvenanceCode(issue.code) && !FIGMA_EXPORT_FILE_CODES.includes(issue.code)) && waived.length === 0) {
+    ready.push("Figma producer provenance gate passed: semantic_figma_export with package fingerprint");
+  }
+}
+
+// Returns every Figma-provenance finding in emission order, each tagged with
+// its severity: "provenance" (the waivable source_html.producer_provenance*
+// and source_html.files.partial/asset blockers) or "warning".
+function collectFigmaProvenanceFindings(manifest, provenance, rawProvenance) {
+  const findings = [];
+  const add = (severity, code, message) => findings.push({ severity, code, message });
   if (!rawProvenance) {
-    addIssue(
-      errors,
+    add(
+      "provenance",
       "source_html.producer_provenance",
       "Figma source manifest is missing producer_provenance. Re-run figma-sections-export handoff so Campaigns OS can gate semantic exporter provenance before assembly."
     );
   }
 
   if (provenance.source_type !== "semantic_figma_export") {
-    addIssue(
-      errors,
+    add(
+      "provenance",
       "source_html.producer_provenance.source_type",
       `Figma source manifest source_type is "${provenance.source_type || "missing"}"; expected "semantic_figma_export". Screenshot or hand-authored fallback output cannot satisfy the Figma provenance gate.`
     );
   }
   if (provenance.screenshot_fallback_used !== false) {
-    addIssue(
-      errors,
+    add(
+      "provenance",
       "source_html.producer_provenance.screenshot_fallback_used",
       "Figma source manifest reports screenshot_fallback_used=true. Re-run semantic figma-sections-export before assembly."
     );
   }
   if (!Number.isInteger(provenance.semantic_section_count) || provenance.semantic_section_count <= 0) {
-    addIssue(
-      errors,
+    add(
+      "provenance",
       "source_html.producer_provenance.semantic_section_count",
       "Figma source manifest must report semantic_section_count > 0."
     );
   }
   if (!SOURCE_HASH_PATTERN.test(String(provenance.material_fingerprint || ""))) {
-    addIssue(
-      errors,
+    add(
+      "provenance",
       "source_html.producer_provenance.material_fingerprint",
       "Figma source manifest must include a 64-character material_fingerprint over the handed-off source package."
     );
@@ -3263,15 +3503,15 @@ function validateSourceProducerProvenance(manifest, { spec, errors, warnings, re
 
   const files = Array.isArray(manifest?.files) ? manifest.files : [];
   if (!files.some((entry) => entry.role === "partial")) {
-    addIssue(errors, "source_html.files.partial", "Figma source manifest files[] must include section partials.");
+    add("provenance", "source_html.files.partial", "Figma source manifest files[] must include section partials.");
   }
   if (!files.some((entry) => entry.role === "asset")) {
-    addIssue(errors, "source_html.files.asset", "Figma source manifest files[] must include exported assets.");
+    add("provenance", "source_html.files.asset", "Figma source manifest files[] must include exported assets.");
   }
 
   const sectionExports = Array.isArray(provenance.section_exports) ? provenance.section_exports : [];
   if (!sectionExports.length) {
-    addIssue(errors, "source_html.producer_provenance.section_exports", "Figma source manifest must include section_exports with Figma node IDs and extraction commands.");
+    add("provenance", "source_html.producer_provenance.section_exports", "Figma source manifest must include section_exports with Figma node IDs and extraction commands.");
   } else {
     const withoutNodeIds = sectionExports
       .filter((entry) => {
@@ -3280,17 +3520,15 @@ function validateSourceProducerProvenance(manifest, { spec, errors, warnings, re
       })
       .map((entry) => entry?.section || "unknown");
     if (withoutNodeIds.length) {
-      addIssue(
-        warnings,
+      add(
+        "warning",
         "source_html.producer_provenance.section_exports.node_ids",
         `Some Figma section exports do not list node_ids: ${withoutNodeIds.slice(0, 6).join(", ")}${withoutNodeIds.length > 6 ? ", ..." : ""}.`
       );
     }
   }
 
-  if (errors.every((issue) => !String(issue.code || "").startsWith("source_html.producer_provenance") && !["source_html.files.partial", "source_html.files.asset"].includes(issue.code))) {
-    ready.push("Figma producer provenance gate passed: semantic_figma_export with package fingerprint");
-  }
+  return findings;
 }
 
 function hasFigmaDesignSource(page) {