@nextcommerce/campaigns-os 1.60.0 → 1.62.0

package/src/doctor/checks.mjs

@@ -14,6 +14,7 @@ import {
 } from "../adapter-decision-contract.mjs";
 import { createDoctorCheckRegistry, runDoctorCheckRegistry } from "../doctor-check-registry.mjs";
 import { evaluateSourcePreparation } from "../source-prep.mjs";
+import { staleRoutingHints } from "../spec-derive.mjs";
 import { isLoopbackHostname } from "../remit.mjs";
 import {
   HOST_STRIPPED_CODE,
@@ -23,10 +24,10 @@ import {
 } from "../source-html-intake.mjs";
 import {
   readSourceHtmlManifestFile,
-  SOURCE_HASH_PATTERN,
   SOURCE_HTML_MANIFEST_SCHEMA,
 } from "../source-html-manifest.mjs";
 import { validateAssemblyReportThemeBlock, validateThemeContextBlock } from "../brand-theme.mjs";
+import { packetRuntimeRelPath } from "../campaign-workspace.mjs";
 import { singleLineDetail, singleLineField } from "../text-safety.mjs";
 import {
   campaignRouteRoot,
@@ -35,6 +36,7 @@ import {
   normalizePublicRouteSlug,
   packetRouteRoot,
   runtimeRelativeRouteForSpecValue,
+  specPublicRouteSlug,
   stripPublicRoutePrefix,
 } from "../route-identity.mjs";
 import { evaluatePageKitBuildSummary } from "../page-kit-build-summary.mjs";
@@ -89,7 +91,8 @@ import { SCRIPT_SYNTAX, collectBuiltScriptSyntaxInputs, evaluateBuiltScriptSynta
 import { CART_PLACEHOLDERS, CART_PLACEHOLDERS_LIMITS, evaluateCartPlaceholders, isFileReadFailure } from "../cart-placeholders.mjs";
 import { SMOKE_QC, SMOKE_QC_LIMITS, builtFileOf, evaluateSmokeQc, insideRoot, isBuiltPageReadFailure, pageScriptSources, parseBuiltPage, realPathOf } from "../built-smoke-qc.mjs";
 import { recordQcResults } from "../qc-results.mjs";
-import { FIGMA_EXPORT_FILE_CODES, SOURCE_PROVENANCE_SCOPE, evaluateSourceProvenanceGates, generatorClaimsFigmaExport, isSourceProvenanceCode } from "./source-provenance.mjs";
+import { evaluateDesignAccess } from "../parity/design-access.mjs";
+import { collectFigmaProvenanceFindings, FIGMA_EXPORT_FILE_CODES, SOURCE_PROVENANCE_SCOPE, evaluateSourceProvenanceGates, generatorClaimsFigmaExport, isSourceProvenanceCode } from "./source-provenance.mjs";
 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";
@@ -102,6 +105,7 @@ import {
 import { loadPageKitCampaignEntry, pageKitIgnoresAssetsHtml, projectPageKitCampaignLoad } from "../page-kit-campaign-config.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";
+import { evaluatePageKitAnalyticsVendors, PAGE_KIT_ANALYTICS_VENDORS_SCOPE } from "../page-kit-analytics-vendors.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
 // spec check is authored once and reaches internal teams and agencies alike.
@@ -382,6 +386,11 @@ const SPEC_DOCTOR_CHECKS = createDoctorCheckRegistry([
     phase: "target",
     run: ({ spec, errors, warnings, ready, derived, buildState }) => validateTargetStoreProfile(spec, errors, warnings, ready, derived, buildState),
   },
+  {
+    id: PAGE_KIT_ANALYTICS_VENDORS_SCOPE,
+    phase: "target",
+    run: ({ spec, warnings, ready, buildState }) => validateTargetAnalyticsVendors(spec, warnings, ready, buildState),
+  },
   {
     id: "spec.shipping_countries",
     phase: "spec",
@@ -392,6 +401,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_hint_stale",
+    phase: "spec",
+    run: ({ spec, packet, errors, ready }) => validateSpecRoutingHintsCurrent(spec, packet, errors, ready),
+  },
   {
     id: "spec.routing_host_prefix",
     phase: "spec",
@@ -1416,6 +1430,18 @@ function validateTargetStoreProfile(spec, errors, warnings, ready, derived, buil
     + storeProfileIntentionallyEmptyNote(intentionallyEmpty));
 }
 
+// The starter-template vendor keys against analytics.vendors: advisory only,
+// one warning per vendor the two sides disagree on (#689).
+function validateTargetAnalyticsVendors(spec, warnings, ready, buildState) {
+  const result = evaluatePageKitAnalyticsVendors({ spec, targetLoad: buildState?.pageKitCampaignConfig });
+  for (const finding of result.findings) {
+    addIssue(warnings, finding.code, finding.message, { vendor: finding.vendor, id_key: finding.id_key, repair: finding.repair });
+  }
+  if (result.status === "ok" && result.vendors.length) {
+    ready.push(`Target campaigns.json vendor keys match the CampaignSpec analytics.vendors (${result.vendors.join(", ")}).`);
+  }
+}
+
 function validateSpecShippingCountries(spec, warnings, ready) {
   const countries = spec?.campaign?.available_shipping_countries;
   if (countries === "all" || (Array.isArray(countries) && countries.length === 0)) {
@@ -1557,11 +1583,7 @@ export function validateRouteSlugIdentity(spec, packet, errors, ready) {
   const mapId = optionalString(spec?.spec_identity?.map_id)
     || optionalString(spec?.map_id)
     || optionalString(packet?.spec?.map_id);
-  const specSlug = normalizePublicRouteSlug(
-    optionalString(spec?.spec_identity?.public_route_slug)
-    || optionalString(spec?.campaign?.slug)
-    || optionalString(spec?.campaign?.id)
-  );
+  const specSlug = specPublicRouteSlug(spec);
   const specDeclaresMapIdSlug = Boolean(specSlug) && Boolean(mapId) && specSlug === mapId;
 
   if (mapId && packetSlug === mapId && !specDeclaresMapIdSlug) {
@@ -1692,6 +1714,31 @@ export function validateSpecRoutingMetaTags(spec, packet, warnings, ready, deriv
   );
 }
 
+// #531: a routing hint (`sdk_hints.meta_tags` next-success-url and the upsell
+// accept/decline urls) that does not match the route of the page its routing
+// field names. Nothing else catches it once the build exists: the built meta
+// check compares the built page against the hint, and QA derives its
+// expectation from the hint, so a moved upsell with checkout still pointing
+// at the old path passes both and sends shoppers to a 404 after payment. It
+// blocks on every read, before and after the build, and record spec refuses a
+// routes-only bind on the same function (spec-derive.mjs staleRoutingHints).
+export function validateSpecRoutingHintsCurrent(spec, packet, errors, ready) {
+  const publicRouteSlug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
+  const stale = staleRoutingHints(spec, { publicRouteSlug });
+  if (!stale.length) {
+    if (activeSpecPages(spec).some((page) => isObject(page.sdk_hints?.meta_tags))) ready.push("CampaignSpec routing hints match the routes of the pages they name");
+    return;
+  }
+  const sample = stale.slice(0, 5).map((hint) => `${hint.page_id}:${hint.tag} ${JSON.stringify(hint.value)} but page "${hint.target_page_id}" routes to ${JSON.stringify(hint.derived_route)}`).join("; ");
+  const more = stale.length > 5 ? `; plus ${stale.length - 5} more` : "";
+  addIssue(
+    errors,
+    "spec.routing_hint_stale",
+    `CampaignSpec routing hint(s) name a route the page they point at no longer has: ${sample}${more}. The built meta tag follows the hint, so the SDK would send shoppers to the old path. Edit each hint to the route shown in the spec (or, while the Map is still the spec's source, re-save the Map, which regenerates them), then run record spec.`,
+    { hints: stale },
+  );
+}
+
 // #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.
@@ -3264,6 +3311,12 @@ function scanMarketSensitiveCopy(spec, warnings, ready, derived) {
   }
 }
 
+// CampaignSpec owns `campaign.available_currencies`: every currency the
+// campaign sells in, the default included (the CampaignCurrencies rule checks
+// its codes). `additional_currencies` is the Campaigns App API's name for the
+// same list without the default and is not a spec field; both market scopes
+// still read it, and its camelCase spelling, so a spec copied from an API body
+// gets the copy review it needs.
 function deriveMarketScope(spec) {
   const campaign = spec?.campaign || {};
   const defaultCurrency = normalizeCurrency(campaign.currency);
@@ -3674,6 +3727,12 @@ function validateSourceCoverage(packet, packetPath, spec, errors, warnings, read
     derived,
   });
   const active = activeSpecPages(spec);
+  const designPackagePath = resolveFromFile(packetPath, packet?.design_source_package?.path);
+  let designSourcePackage = null;
+  try { if (designPackagePath) designSourcePackage = JSON.parse(readFileSync(designPackagePath, "utf8")); } catch { /* Missing or unreadable package is checked separately. */ }
+  const designManifest = isNonEmptyString(sourceRoot) && existsSync(sourceRoot) && statSync(sourceRoot).isDirectory()
+    ? readSourceHtmlManifestFile(sourceRoot, { manifestPath: recordedDesignManifestPath(packet, packetPath) }).manifest : null;
+  recordQcResults({ derived, warnings, results: evaluateDesignAccess({ activePages: active, mappings: pages, manifest: designManifest, designSourcePackage, measured_at: new Date().toISOString() }) });
   const specPartialScope = spec?.build_scope?.mode === "partial";
   const specPartialReasons = Array.isArray(spec?.build_scope?.reasons) ? spec.build_scope.reasons.filter(isNonEmptyString) : [];
   const activeIds = new Set(active.map((page) => page.id));
@@ -3706,6 +3765,25 @@ function validateSourceCoverage(packet, packetPath, spec, errors, warnings, read
     if (!activeIds.has(page.page_id)) {
       addIssue(warnings, "source_html.pages.extra", `Source mapping "${page.page_id}" is not an active CampaignSpec page.`);
     }
+    // A page added from the repo's page tree after handoff (#721): its source
+    // is the target page file itself, so it is mapped and, once that file
+    // exists, a build candidate like any other.
+    if (page.origin === "repo") {
+      const repoFile = optionalString(page.page_kit?.output_path) && derived.target_repo ? resolve(derived.target_repo, page.page_kit.output_path) : null;
+      if (!repoFile || !existsSync(repoFile) || !statSync(repoFile).isFile()) {
+        addIssue(errors, "source_html.pages.repo_page_missing", `Page "${page.page_id}" was added from the repo's page tree, but its page file ${page.page_kit?.output_path || "(no page_kit.output_path)"} is not in the target repo. Restore the file, or run spec derive and record spec to remove the page.`, { page_id: page.page_id, output_path: page.page_kit?.output_path || null });
+      } else if (specPage) {
+        builtPages.push({
+          page_id: specPage.id,
+          type: specPage.type || "page",
+          role: pageRole(specPage.type),
+          route: builtRoute,
+          source_path: null,
+          repo_source: page.page_kit.output_path,
+        });
+      }
+      continue;
+    }
     if (page.path) {
       const fullPath = resolve(sourceRoot, page.path);
       if (!existsSync(fullPath) || !statSync(fullPath).isFile()) {
@@ -3988,78 +4066,6 @@ function validateSourceProducerProvenance(manifest, { spec, errors, warnings, re
   }
 }
 
-// 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) {
-    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") {
-    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) {
-    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) {
-    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 || ""))) {
-    add(
-      "provenance",
-      "source_html.producer_provenance.material_fingerprint",
-      "Figma source manifest must include a 64-character material_fingerprint over the handed-off source package."
-    );
-  }
-
-  const files = Array.isArray(manifest?.files) ? manifest.files : [];
-  if (!files.some((entry) => entry.role === "partial")) {
-    add("provenance", "source_html.files.partial", "Figma source manifest files[] must include section partials.");
-  }
-  if (!files.some((entry) => entry.role === "asset")) {
-    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) {
-    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) => {
-        const nodeIds = isObject(entry?.node_ids) ? entry.node_ids : null;
-        return !nodeIds || !Object.keys(nodeIds).length;
-      })
-      .map((entry) => entry?.section || "unknown");
-    if (withoutNodeIds.length) {
-      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 ? ", ..." : ""}.`
-      );
-    }
-  }
-
-  return findings;
-}
 
 function hasFigmaDesignSource(page) {
   const designSource = page && isObject(page.design_source) ? page.design_source : null;
@@ -4691,7 +4697,7 @@ export function validateBuiltContentResidue(packet, errors, warnings, ready, der
   const publicRouteSlug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
   const siteRoot = derived.target_repo && publicRouteSlug ? join(derived.target_repo, "_site", publicRouteSlug) : null;
   if (!siteRoot || !existsSync(siteRoot) || !statSync(siteRoot).isDirectory()) return;
-  const brief = loadBriefPayload(derived.target_repo);
+  const brief = loadBriefPayload(derived.target_repo, packetRuntimeRelPath(packet));
   const urgencyVerified = briefUrgencyVerified(brief?.payload);
   const findings = scanBuiltOutputContentResidue(siteRoot, { urgencyVerified });
   if (!findings.length) {
@@ -4760,7 +4766,7 @@ export function validateBuiltContentResidue(packet, errors, warnings, ready, der
 // non-shipped, non-usable assets stay warnings (the attestation queue), so a
 // producer that correctly excluded them is not blocked.
 export function validateProofAttestation(packet, errors, warnings, ready, derived, buildState = {}) {
-  const brief = loadBriefPayload(derived.target_repo);
+  const brief = loadBriefPayload(derived.target_repo, packetRuntimeRelPath(packet));
   if (!brief) return; // not an AI-assembled run — no brief payload, no gate
   if (brief.error) {
     // Fail closed: the brief payload is the source of attestation state. If

package/src/doctor/ci.mjs

@@ -0,0 +1,177 @@
+import { worseChangeKind } from "../change-scope.mjs";
+import { assessEvidenceDebt } from "../evidence-debt.mjs";
+import { REFUSED_INVOCATION } from "../lifecycle.mjs";
+
+export const DOCTOR_CI_EXIT_CODES = Object.freeze({ current: 0, owed: 3, unknown: 4, usage: 2 });
+
+export function assessDoctorCi(inputs) {
+  const debt = assessEvidenceDebt(inputs);
+  // Advisory Polish (a page-only change) is reported, never required.
+  const stages = [debt.polish, debt.qa].filter((stage) => !stage.advisory);
+  // Any known debt is owed; otherwise incomplete evidence remains unknown.
+  const status = stages.some((stage) => stage.status === "owed") ? "owed"
+    : stages.some((stage) => stage.status === "unknown") ? "unknown" : "current";
+  return { status, exit_code: DOCTOR_CI_EXIT_CODES[status], ...debt };
+}
+
+// What the change owes, from the stages it left owed: "pages" when the only
+// required stage is QA on the changed pages (Polish advisory or current),
+// "full" when a full stage is owed, null when nothing is owed. `kind` is the
+// worst change kind among the owed stages.
+export function ciChangeScope(ci) {
+  const owed = ["polish", "qa"].filter((stage) => ci[stage]?.status === "owed");
+  if (!owed.length) return { scope: null, kind: null };
+  const kind = owed.map((stage) => ci[stage].change?.kind || "unknown").reduce(worseChangeKind, "none");
+  const required = owed.filter((stage) => !ci[stage].advisory);
+  const scope = required.every((stage) => stage === "qa" && ci.qa.scope === "pages") ? "pages" : "full";
+  return { scope, kind };
+}
+
+// Page ids come from built routes ([A-Za-z0-9_-]); anything else is encoded.
+const pageArg = (id) => (/^[A-Za-z0-9_-]+$/.test(String(id)) ? String(id) : text(id));
+
+const commerceReasonText = new Map([
+  ["unmapped_file", "a file outside any page changed"],
+  ["page_added", "a page was added"],
+  ["page_removed", "a page was removed"],
+  ["checkout_page", "a checkout page changed"],
+  ["commerce_markup_changed", "package, offer, shipping, upsell, route or script markup changed"],
+  ["commerce_signature_unavailable", "the recorded build has no commerce signature to compare against"],
+  ["campaign_config_changed", "the campaign's Page Kit config (SDK pin, analytics ids, store fields) changed"],
+  ["campaign_config_unavailable", "the campaign's Page Kit config entry could not be read"],
+  ["change_history_unavailable", "the rebuilds since the reviewed build were not kept"],
+]);
+
+// Values can come from campaign files and will be rendered in a PR comment.
+// Encode punctuation as well as HTML: diagnostics are plain text, and may
+// contain Markdown, autolinks, code fences or line breaks from campaign files.
+const text = (value) => String(value).replace(/\s/g, " ")
+  .replace(/[!-/:-@\[-`{-~]/g, (char) => `&#${char.charCodeAt(0)};`);
+// Inline code already protects ordinary path punctuation; preserve those
+// bytes for readable page paths and issue codes, while preventing breakouts.
+const code = (value) => `\`${String(value).replace(/\s/g, " ")
+  .replace(/[!-/:-@\[-`{-~]/g, (char) => "./_-".includes(char) ? char : `&#${char.charCodeAt(0)};`)}\``;
+
+const unavailablePageChanges = new Map([
+  ["packet_unavailable", "the build packet or its path is unavailable."],
+  ["build_output_location_unknown", "the built output location cannot be determined."],
+  ["build_output_missing", "the built output is missing."],
+  ["build_output_unreadable", "the built output could not be read."],
+  ["assembly_build_fingerprint_missing", "the assembly build fingerprint is missing."],
+  ["build_output_pages_unresolved", "the built output could not be mapped to pages."],
+  ["build_manifest_unavailable", "no usable assembly manifest is available."],
+]);
+
+const requiredStageReasons = new Map([
+  ["stage_required_by_build", "the build requires this stage again"],
+  ["stage_required_by_brief", "the brief requires this stage again"],
+  ["stage_required_by_spec", "the spec requires this stage again"],
+  ["stage_required", "the lifecycle requires this stage again"],
+]);
+
+export function doctorCiFailure(error, { usage = false, code = usage ? "doctor.ci.packet" : "doctor.ci.failed" } = {}) {
+  return {
+    ok: false, status: "blocked",
+    errors: [{ code, message: String(error?.message ?? error) }],
+    warnings: [], exit_code: usage ? DOCTOR_CI_EXIT_CODES.usage : DOCTOR_CI_EXIT_CODES.unknown,
+  };
+}
+
+// Presentation boundary only: invocation policy still decides session and
+// lifecycle behavior. Setup can throw before doctor's dispatch branch runs.
+export async function withDoctorCiReport(args, invoke) {
+  const command = args._[0] === "campaigns-os" ? args._[1] : args._[0];
+  try {
+    return await invoke(args);
+  } catch (error) {
+    if (command !== "doctor" || args.ci !== true) throw error;
+    // A flag refused up front (such as --packet=<path>) is a usage error.
+    const result = error?.code === REFUSED_INVOCATION ? doctorCiFailure(error, { usage: true, code: "doctor.ci.usage" }) : doctorCiFailure(error);
+    console.log(args.json ? JSON.stringify(result, null, 2) : formatDoctorCi(result));
+    process.exitCode = result.exit_code;
+  }
+}
+
+export function formatDoctorCi(result) {
+  const ci = result.ci;
+  if (!ci) {
+    return [
+      `## Campaign evidence: could not evaluate (exit ${result.exit_code ?? DOCTOR_CI_EXIT_CODES.usage})`, "",
+      ...(result.errors || []).map((issue) => `- ${code(issue.code)}: ${text(issue.message)}`), "",
+      result.errors?.[0]?.code === "doctor.ci.usage"
+        ? "Remedy: correct the command's flags (each value as the next argument, `--flag value`) and re-run `campaigns-os doctor --packet <packet> --ci --no-live-refs`."
+        : "Remedy: correct the packet or inspection failure and re-run `campaigns-os doctor --packet <packet> --ci --no-live-refs`.",
+    ].join("\n");
+  }
+  const lines = [`## Campaign evidence: ${text(ci.status)} (exit ${ci.exit_code})`, ""];
+  const advisory = ["polish", "qa"].filter((stage) => ci[stage].status === "owed" && ci[stage].advisory);
+  const owed = ["polish", "qa"].filter((stage) => ci[stage].status === "owed" && !ci[stage].advisory);
+  const change = ciChangeScope(ci);
+  const pageScoped = change.scope === "pages";
+  if (pageScoped) {
+    lines.push(`Change found: page-only. ${owed.length ? `It owes QA on ${ci.qa.owed_pages.map((page) => code(page.page_id)).join(", ")}` : "QA is current"}; Polish is advisory.`);
+  } else if (change.scope === "full") {
+    const reasons = [...new Set((ci.polish.change?.reasons || []).concat(ci.qa.change?.reasons || [])
+      .map((reason) => commerceReasonText.get(reason.code)).filter(Boolean))];
+    const found = change.kind === "commerce_affecting" ? "commerce-affecting"
+      : change.kind === "page_only" ? "page-only, but an input change or a Polish or QA that did not complete requires the full stages" : "not classified";
+    // Name only the stages that count, each at the scope it is owed: an
+    // advisory Polish is not owed, and QA can still be owed on pages only.
+    const qaPages = ci.qa.scope === "pages" ? `QA on ${ci.qa.owed_pages.map((page) => code(page.page_id)).join(", ")}` : null;
+    const owes = owed.length === 2 ? (qaPages ? `the full Polish, and ${qaPages}` : "the full Polish and QA")
+      : owed[0] === "polish" ? "the full Polish" : qaPages || "a full QA run";
+    lines.push(`Change found: ${found}${reasons.length ? ` (${reasons.join("; ")})` : ""}. It owes ${owes}${advisory.includes("polish") ? "; Polish is advisory" : ""}.`);
+  }
+  lines.push(`Owed stages: ${owed.length ? owed.map((stage) => stage === "qa" && ci.qa.scope === "pages" ? "qa (changed pages only)" : stage).join(", ") : "none"}.`);
+  for (const stage of owed) {
+    const reason = ci[stage].reason === "build_fingerprint_changed"
+      ? "the recorded build fingerprint differs from the current build"
+      : requiredStageReasons.get(ci[stage].reason) ?? "the recorded stage evidence is owed";
+    lines.push(`- Owed ${stage}: ${reason}.`);
+  }
+  for (const stage of advisory) {
+    lines.push(`- Advisory ${stage}: the change since its last review is page-only, so it is reported and not required.`);
+  }
+  // The pages changed since the builds the owed stages reviewed, which
+  // record build keeps; without them, the drift from the assembly manifest.
+  const sincePages = new Map();
+  for (const stage of [...owed, ...advisory]) {
+    for (const page of ci[stage].change?.changed_pages || []) sincePages.set(page.built_path, page);
+  }
+  const changedPages = sincePages.size ? [...sincePages.values()] : ci.changes.changed_pages;
+  for (const page of changedPages) {
+    lines.push(`- Changed page: ${code(page.page_id)} (${code(page.built_path)})`);
+  }
+  if (!changedPages.length && (owed.length || ci.changes.status === "unknown")) {
+    lines.push(ci.changes.status === "unknown"
+      ? `Changed pages unavailable: ${unavailablePageChanges.get(ci.changes.reason) ?? "the page-change reason is unrecognized."}`
+      : "Changed page ids unavailable: the retained assembly manifest may already describe the rebuilt output.");
+  }
+  for (const stage of ["polish", "qa"]) {
+    if (ci[stage].status === "unknown") lines.push(`- Unknown ${stage}: ${code(ci[stage].reason)}`);
+  }
+  if (ci.changes.status === "unknown") lines.push(`- Unknown page changes: ${code(ci.changes.reason)}`);
+  if (ci.status === "owed" && pageScoped && owed.length) {
+    const pages = ci.qa.owed_pages.map((page) => ` --page ${pageArg(page.page_id)}`).join("");
+    const recorded = ci.changes.recorded_build_fingerprint && ci.changes.recorded_build_fingerprint === ci.changes.current_build_fingerprint;
+    lines.push("", `Remedy: ${recorded ? "" : "run `campaigns-os record build --packet <packet>` for the rebuilt output, then "}run \`campaigns-os qa run --packet <packet>${pages}\` against that build. Polish capture is optional for a page-only change.`);
+  } else if (ci.status === "owed" || ci.status === "unknown") {
+    const matchingRequired = owed.length > 0
+      && owed.every((stage) => requiredStageReasons.has(ci[stage].reason) && ci[stage].matches_current_build === true)
+      && ["polish", "qa"].every((stage) => ci[stage].status !== "unknown");
+    if (matchingRequired) {
+      const commands = [];
+      if (owed.includes("polish")) commands.push("`campaigns-os polish capture --packet <packet> --base-url <served-current-build-url>` for the whole route", "`campaigns-os record polish --packet <packet> --evidence <polish-evidence.json>`");
+      if (owed.includes("qa")) commands.push("`campaigns-os qa run --packet <packet>`");
+      lines.push("", `Remedy: re-run the required stages against the existing build: ${commands.join(", then ")}.`);
+    } else {
+      lines.push("", "Remedy: rebuild, then run `campaigns-os record build --packet <packet>`, `campaigns-os polish capture --packet <packet> --base-url <served-current-build-url>` for the whole route, and `campaigns-os record polish --packet <packet> --evidence <polish-evidence.json>`, in that order. When QA is owed, run `campaigns-os qa run --packet <packet>` against that build.");
+    }
+  }
+  lines.push("", `Doctor inspection: ${(result.errors || []).length} error(s), ${(result.warnings || []).length} warning(s); CI exit status depends only on evidence debt.`);
+  if (result.errors?.length) {
+    lines.push(`Doctor errors: ${[...new Set(result.errors.map((issue) => issue.code))].map(code).join(", ")}.`);
+  }
+  lines.push("Use ordinary `doctor` or `--ci --json` for full inspection details.");
+  return lines.join("\n");
+}

package/src/doctor/inspect.mjs

@@ -1,6 +1,8 @@
 // Doctor entry points: the doctor command, packet inspection and built-output inspection.
 import { resolveCampaignIdentity } from "../spec-source-identity.mjs";
-import { applyLocalPreviewToCheckpoint, applyLocalPreviewToPolishGate, carriedForwardMessage, CARRIED_FORWARD } from "../local-preview-policy.mjs";
+import { assessDoctorCi, doctorCiFailure } from "./ci.mjs";
+import { applyLocalPreviewToCheckpoint, applyLocalPreviewToPolishGate, applyPageOnlyChangeToCheckpoint, applyPageOnlyChangeToPolishGate, carriedForwardMessage, CARRIED_FORWARD } from "../local-preview-policy.mjs";
+import { assessEvidenceDebt } from "../evidence-debt.mjs";
 import { withHtmlScanSnapshot } from "../html-scan.mjs";
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
@@ -10,7 +12,7 @@ import { commitAssemblyReport, recordProducerStageOutcome } from "../stage-ledge
 import { annotateDoctorIssueCauses } from "../finding-cause.mjs";
 import { DOCTOR_SIDECAR_SCHEMA } from "../doctor-sidecar.mjs";
 import { recordQcResults } from "../qc-results.mjs";
-import { resolveCampaignWorkspace } from "../campaign-workspace.mjs";
+import { packetRuntimeRelPath, resolveCampaignWorkspace } from "../campaign-workspace.mjs";
 import { normalizePublicRouteSlug } from "../route-identity.mjs";
 import { DEFAULT_PROXY_BASE } from "../spec-fetch.mjs";
 import { disabledLiveRead, liveRefsDisabled, readLiveCampaignForPacket } from "../live-campaign-refs.mjs";
@@ -132,6 +134,13 @@ export async function readDoctorLiveCampaign(args, { fetchImpl = globalThis.fetc
 }
 
 export function doctorCommand(args, { runDoctor = doctorPacket, liveCampaign = undefined, qcStandIns = undefined } = {}) {
+  if (args.ci === true) {
+    try {
+      JSON.parse(readFileSync(resolve(requireArg(args, "packet")), "utf8"));
+    } catch (error) {
+      return doctorCiFailure(error, { usage: true });
+    }
+  }
   // Non-packet mode (learnings L7): doctor a `campaign-build`'d page-kit
   // campaign that has only a built _site/ and no full Build Packet. Resolves
   // scope from the built output and runs the built-output residue/text/
@@ -153,6 +162,16 @@ export function doctorCommand(args, { runDoctor = doctorPacket, liveCampaign = u
     ...(qcStandIns !== undefined ? { qcStandIns } : {}),
   };
   const result = runDoctor(packetPath, doctorOptions);
+  if (args.ci === true) {
+    // Use precisely the context/report selection that inspection used,
+    // including explicit sidecar suppression and the context's report binding.
+    const workspace = resolveCampaignWorkspace(packetPath, {
+      contextPath: doctorOptions.contextPath,
+      reportPath: doctorOptions.reportPath,
+      followContextPointer: true,
+    });
+    result.ci = assessDoctorCi({ packet: workspace.packet, packetPath, report: readJsonIfExists(workspace.reportPath) });
+  }
   // Inspection and recording are separate operations. A laptop's untracked
   // built output can be stale while the delivered build's evidence is valid.
   // Only an explicit producer action may replace the retained proof artifacts;
@@ -440,6 +459,16 @@ export function doctorBuiltOutput(args) {
   };
 }
 
+// Inspection already refused a packet whose runtime directory is unreadable;
+// the history lookup then falls back to the project-level directory.
+function packetRuntimeRelPathOrDefault(packetPath) {
+  try {
+    return packetRuntimeRelPath(JSON.parse(readFileSync(resolve(packetPath), "utf8")));
+  } catch {
+    return undefined;
+  }
+}
+
 export function doctorPacket(packetPath, options = {}) {
   const result = withHtmlScanSnapshot(() => inspectDoctorPacket(packetPath, options));
   // Per-finding cause classification lives HERE, at the single production
@@ -469,6 +498,7 @@ export function doctorPacket(packetPath, options = {}) {
     errors: result.errors,
     warnings: result.warnings,
     baseDir: comparableIdentity ? dirname(resolve(packetPath)) : null,
+    runtimeRelPath: comparableIdentity ? packetRuntimeRelPathOrDefault(packetPath) : undefined,
     mapId: result.derived?.map_id || null,
     localSpecId: result.derived?.local_spec_id || null,
   });
@@ -569,16 +599,21 @@ function inspectDoctorPacket(packetPath, { contextPath = undefined, reportPath =
 
   // The local preview policy (local-preview-policy.mjs) carries missing
   // polish and page-load evidence forward as warnings on a local-serve packet.
-  const polishCheckpointGate = applyLocalPreviewToCheckpoint(
+  // A page-only change since Polish last reviewed the campaign carries its
+  // stale evidence on any target: Polish is advisory for it (#720). The
+  // evidence debt is the one readback and doctor --ci assess.
+  const evidenceDebt = assessEvidenceDebt({ packet, packetPath, report });
+  derived.evidence_debt = evidenceDebt;
+  const polishCheckpointGate = applyPageOnlyChangeToCheckpoint(applyLocalPreviewToCheckpoint(
     evaluateRecordedHiddenEagerMediaCheckpoint({ packet, report }),
     { packet, report },
-  );
+  ), evidenceDebt);
   derived.polish_checkpoint_gate = polishCheckpointGate;
-  const polishGate = applyLocalPreviewToPolishGate(evaluatePolishGate({
+  const polishGate = applyPageOnlyChangeToPolishGate(applyLocalPreviewToPolishGate(evaluatePolishGate({
     report,
     hiddenEagerMediaGate: polishCheckpointGate,
     currentOutputFingerprint: derived.build_output_fingerprint?.value || null,
-  }), { packet, checkpointGate: polishCheckpointGate });
+  }), { packet, checkpointGate: polishCheckpointGate }), { debt: evidenceDebt, checkpointGate: polishCheckpointGate });
   derived.polish_gate = polishGate;
   if (polishGate.status === "blocked" && !polishGate.owned_checkpoint_only) {
     pushGateIssue({ errors, warnings }, gateIssue("polish_gate", polishGate));

package/src/doctor/next-step.mjs

@@ -503,6 +503,13 @@ function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate
     }
     if (cliStage === "qa" && qaRecordedBuildFingerprint(report) && currentBuildFingerprint(report)
       && !qaRecordedForCurrentBuild(report, currentBuildFingerprint(report))) {
+      // A page-only change since the build QA reviewed owes QA on the
+      // changed pages only (#720); qa run --page pays it.
+      const qaDebt = derived?.evidence_debt?.qa;
+      if (qaDebt?.scope === "pages" && qaDebt.owed_pages?.length) {
+        const pages = qaDebt.owed_pages.map((page) => `--page ${page.page_id}`).join(" ");
+        return { stage: "qa", reason: `QA was recorded for a different build, and the change since then is page-only: run QA on the changed pages with ${cmd("qa")} run --packet <packet> ${pages}.` };
+      }
       return { stage: "qa", reason: "QA was recorded for a different build; run QA against the current build." };
     }
     // A terminal QA status is not the same claim as purchase proof. QA finalizes

package/src/doctor/source-provenance.mjs

@@ -18,6 +18,7 @@
 // validity, wrapper policy, screenshot proof) is evaluated elsewhere and is
 // untouched by this gate.
 
+import { SOURCE_HASH_PATTERN } from "../source-html-manifest.mjs";
 import {
   assessCheckpointWaivers,
   checkpointStateFingerprint,
@@ -182,3 +183,76 @@ export function evaluateSourceProvenanceGates({ pages = [], blockingCodes = [],
 
   return { gates, inert: { counts, pages: inertPages } };
 }
+
+// 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".
+export function collectFigmaProvenanceFindings(manifest, provenance = manifest?.producer_provenance || {}, rawProvenance = manifest?.producer_provenance) {
+  const findings = [];
+  const add = (severity, code, message) => findings.push({ severity, code, message });
+  if (!rawProvenance) {
+    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") {
+    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) {
+    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) {
+    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 || ""))) {
+    add(
+      "provenance",
+      "source_html.producer_provenance.material_fingerprint",
+      "Figma source manifest must include a 64-character material_fingerprint over the handed-off source package."
+    );
+  }
+
+  const files = Array.isArray(manifest?.files) ? manifest.files : [];
+  if (!files.some((entry) => entry.role === "partial")) {
+    add("provenance", "source_html.files.partial", "Figma source manifest files[] must include section partials.");
+  }
+  if (!files.some((entry) => entry.role === "asset")) {
+    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) {
+    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) => {
+        const nodeIds = isPlainObject(entry?.node_ids) ? entry.node_ids : null;
+        return !nodeIds || !Object.keys(nodeIds).length;
+      })
+      .map((entry) => entry?.section || "unknown");
+    if (withoutNodeIds.length) {
+      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 ? ", ..." : ""}.`
+      );
+    }
+  }
+
+  return findings;
+}