@nextcommerce/campaigns-os 1.59.0 → 1.61.0

package/src/design-source-package.mjs

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { resolveDesignFileReferences } from "./design-file-reference.mjs";
 
 export const DESIGN_SOURCE_PACKAGE_SCHEMA = "campaign-design-source-package/v0";
 export const DESIGN_SOURCE_PACKAGE_REL_PATH = ".campaign-runtime/input/design-source-package.json";
@@ -166,7 +167,7 @@ const PRESENTATION_INTENT_FIELDS = new Set([
   "brand",
   "responsive_behavior",
 ]);
-const SOURCE_REF_FIELDS = new Set(["id", "kind", "path", "url", "sha256", "role", "media_type", "notes"]);
+const SOURCE_REF_FIELDS = new Set(["id", "kind", "path", "url", "sha256", "role", "media_type", "notes", "design_file_type"]);
 const VISUAL_REF_FIELDS = new Set([
   "id",
   "kind",
@@ -195,6 +196,7 @@ const TEMPLATE_REFERENCE_FIELDS = new Set([
   "standard_viewport_refs",
 ]);
 const COVERAGE_MAPPING_FIELDS = new Set([
+  "derived_from",
   "id",
   "surface_id",
   "coverage_role",
@@ -337,6 +339,7 @@ export function synthesizeHtmlFunnelDesignSourcePackage({
   });
 
   const manifestInput = normalizeManifestInput(manifest, manifestPath);
+  const designFiles = resolveDesignFileReferences({ activePages, mappings: resolvedMappings, manifest: manifestInput.value });
   const crawl = isObject(sourceAssetCrawl) ? sourceAssetCrawl : isObject(assetCrawl) ? assetCrawl : null;
   const crawlInputName = isObject(sourceAssetCrawl) ? "sourceAssetCrawl" : "assetCrawl";
   assertOptionalInputArray(manifestInput.value?.files, "manifest.files");
@@ -480,6 +483,9 @@ export function synthesizeHtmlFunnelDesignSourcePackage({
     htmlCoverage.push({
       id: `html-${surfaceId}-coverage`,
       surface_id: surfaceId,
+      ...(designFiles.pages.some((entry) => entry.page_id === page.pageId) ? {
+        derived_from: designFiles.files.find((file) => file.pages.includes(page.pageId)).contribution_id,
+      } : {}),
       coverage_role: explicitRole || "primary_design",
       confidence: normalizeConfidence(mapping?.confidence)
         || confidenceForHtmlMapping(mapping, manifestPage),
@@ -525,6 +531,37 @@ export function synthesizeHtmlFunnelDesignSourcePackage({
   };
 
   const contributions = [htmlContribution];
+  for (const file of [...designFiles.files].sort((a, b) => a.contribution_id.localeCompare(b.contribution_id))) {
+    const id = file.contribution_id;
+    // kind collapses non-Figma tools to "other". Use a new field so existing
+    // source-reference notes remain nonmaterial, including design_file refs.
+    const sourceRefs = [{ id: `${id}-file`, kind: "url", url: file.file_url, role: "design_file",
+      ...(!["figma", "other"].includes(file.identity.type) ? { design_file_type: file.identity.type } : {}),
+    }];
+    const mappings = file.pages.map((pageId) => {
+      const surfaceId = surfaceByPageId.get(pageId);
+      const declaration = designFiles.pages.find((page) => page.page_id === pageId).declaration;
+      const frameRefs = Object.entries(declaration.frames).map(([viewport, frame]) => ({
+        id: `${id}-${surfaceId}-frame-${viewport}`, kind: "url", url: frame.url, role: `design_frame:${viewport}`,
+      }));
+      sourceRefs.push(...frameRefs);
+      return { id: `${id}-${surfaceId}-coverage`, surface_id: surfaceId, coverage_role: "reference_only", confidence: "high", source_refs: [`${id}-file`, ...frameRefs.map((ref) => ref.id)], screenshot_refs: [], reference_refs: [] };
+    });
+    const fromManifest = file.producer === "source_html_manifest";
+    contributions.push({
+      id, kind: file.identity.type === "figma" ? "figma_frames" : "other", trust: file.identity.type === "figma" ? "native" : "opaque", renderable: false,
+      provenance: {
+        source_type: "design_file", adapter: "design-file-reference", producer: file.producer,
+        generator: null, generator_version: null, source_root: null,
+        manifest_schema_version: fromManifest ? optionalString(manifestInput.value?.schema_version) : null,
+        manifest_path: fromManifest ? optionalString(manifestInput.path) : null,
+        manifest_sha256: fromManifest ? validSha(manifestInput.value?.sha256) : null,
+        producer_material_fingerprint: null, asset_crawl_schema_version: null,
+      },
+      presentation_intent: { summary: "Design file the page's HTML export was produced from. Recorded as the design authority; this version does not read it." },
+      source_refs: sourceRefs, screenshot_refs: [], reference_refs: [], mappings,
+    });
+  }
   const template = normalizeTemplateFamily(templateFamily);
   const qualifyingHtmlSurfaces = new Set(
     htmlCoverage
@@ -998,6 +1035,15 @@ export function validateDesignSourcePackage(value, {
     if (contributionIds.has(contribution.id)) add("design_source_package.contribution_id_duplicate", `${path}.id`, `Duplicate contribution id "${contribution.id}".`);
     contributionIds.add(contribution.id);
   });
+  contributions.forEach((contribution, index) => {
+    arrayOrEmpty(contribution?.mappings).forEach((mapping, mappingIndex) => {
+      if (!Object.hasOwn(mapping || {}, "derived_from")) return;
+      const target = contributions.find((entry) => entry?.id === mapping.derived_from && entry !== contribution);
+      if (!target || !["figma_frames", "figma_sections", "other"].includes(target.kind) || !arrayOrEmpty(target.mappings).some((entry) => entry?.surface_id === mapping.surface_id)) {
+        add("design_source_package.derived_from_ref", `$.contributions[${index}].mappings[${mappingIndex}].derived_from`, "derived_from must name another design contribution mapped to the same surface_id.");
+      }
+    });
+  });
 
   validateRecordArray(value.source_gaps, "$.source_gaps", GAP_FIELDS,
     ["id", "kind", "scope", "applies_to", "reason", "status", "attributed_by"], add,
@@ -1394,6 +1440,8 @@ function projectContribution(contribution) {
 function projectSourceRef(ref) {
   return compactDefined({
     ...pickFields(ref, ["id", "kind", "path", "url", "role", "media_type"]),
+    // Absent from every BASE-valid package; never project existing prose notes.
+    design_file_type: ref?.design_file_type,
     sha256: canonicalHashSpelling(ref?.sha256),
   });
 }
@@ -1451,6 +1499,7 @@ function projectProvenance(provenance) {
 
 function projectCoverageMapping(mapping) {
   return compactDefined({
+    derived_from: mapping?.derived_from,
     id: mapping?.id,
     surface_id: mapping?.surface_id,
     coverage_role: mapping?.coverage_role,
@@ -2252,6 +2301,10 @@ function validateSourceReference(value, path, add) {
   if (!checkStrictObject(value, path, SOURCE_REF_FIELDS, ["id", "kind"], add)) return;
   checkNonEmptyString(value.id, `${path}.id`, add);
   checkEnum(value.kind, SOURCE_REF_KINDS, `${path}.kind`, add);
+  if (Object.hasOwn(value, "design_file_type")) {
+    checkNonEmptyString(value.design_file_type, `${path}.design_file_type`, add);
+    if (value.role !== "design_file") add("design_source_package.design_file_type", `${path}.design_file_type`, "design_file_type requires role design_file.");
+  }
   if (!isNonEmptyString(value.path) && !isNonEmptyString(value.url)) add("design_source_package.source_ref_location", path, "Source reference requires path or url.");
   for (const field of ["path", "url", "role", "media_type"]) if (value[field] != null) checkNonEmptyString(value[field], `${path}.${field}`, add);
   if (value.sha256 != null && !SHA256_PATTERN.test(value.sha256)) add("design_source_package.sha256", `${path}.sha256`, "sha256 must be 64 lowercase hex, with optional sha256: prefix.");
@@ -2293,6 +2346,7 @@ function validateCoverageMapping(value, path, add) {
     "id", "surface_id", "coverage_role", "confidence", "source_refs", "screenshot_refs", "reference_refs",
   ], add)) return false;
   checkNonEmptyString(value.id, `${path}.id`, add);
+  if (Object.hasOwn(value, "derived_from")) checkNonEmptyString(value.derived_from, `${path}.derived_from`, add);
   checkNonEmptyString(value.surface_id, `${path}.surface_id`, add);
   checkEnum(value.coverage_role, new Set(COVERAGE_ROLES), `${path}.coverage_role`, add);
   checkEnum(value.confidence, new Set(MAPPING_CONFIDENCE_LEVELS), `${path}.confidence`, add);

package/src/doctor/checks.mjs

@@ -23,7 +23,6 @@ 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";
@@ -89,7 +88,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";
@@ -99,7 +99,7 @@ import {
   assessAssemblySourcePackageFreshnessWaivers,
   currentBuildFingerprint,
 } from "../polish-gate.mjs";
-import { loadPageKitCampaignEntry, projectPageKitCampaignLoad } from "../page-kit-campaign-config.mjs";
+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";
 // ADR-003: the public, canonical CampaignSpec rule registry. The doctor and any
@@ -3039,7 +3039,7 @@ function builtHtmlPathForPage(targetRepo, publicRouteSlug, page, derived = {}) {
     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 sourcePermalink = sourcePermalinkForPage(derived?.target_output_dir, publicRouteSlug, page, { assetsHtmlIgnored: pageKitIgnoresAssetsHtml(targetRepo) });
   const route = sourcePermalink || runtimeRelativeRouteForSpecValue(publicRouteForPage(page), publicRouteSlug);
   if (!route) return join(targetRepo, "_site", publicRouteSlug, "index.html");
   const clean = route.replace(/^\/+|\/+$/g, "");
@@ -3103,13 +3103,16 @@ export function entryPageKitFileRoute(targetRepo, publicRouteSlug, page, { targe
   return routes[0] ?? null;
 }
 
-function sourcePermalinkForPage(targetOutputDir, publicRouteSlug, page) {
+// page-kit 0.3.0 renders no .html under the campaign's top-level assets/, so
+// a permalink stated there is no route on that version (assetsHtmlIgnored).
+function sourcePermalinkForPage(targetOutputDir, publicRouteSlug, page, { assetsHtmlIgnored = false } = {}) {
   if (!targetOutputDir || !existsSync(targetOutputDir) || !statSync(targetOutputDir).isDirectory()) return null;
 
   const expectedTerminal = terminalRouteSegment(publicRouteForPage(page));
   const candidates = [];
   for (const file of collectHtmlFiles(targetOutputDir)) {
     if (file.path.includes("_includes/") || file.path.includes("_layouts/")) continue;
+    if (assetsHtmlIgnored && file.path.split(sep)[0] === "assets") continue;
     const fullPath = join(targetOutputDir, file.path);
     const content = readFileSync(fullPath, "utf8");
     const permalink = extractFrontmatterValue(content, "permalink");
@@ -3671,6 +3674,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));
@@ -3985,78 +3994,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;

package/src/doctor/ci.mjs

@@ -0,0 +1,112 @@
+import { assessEvidenceDebt } from "../evidence-debt.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);
+  const stages = [debt.polish, debt.qa];
+  // 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 };
+}
+
+// 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 } = {}) {
+  return {
+    ok: false, status: "blocked",
+    errors: [{ code: usage ? "doctor.ci.packet" : "doctor.ci.failed", 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;
+    const result = 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)}`), "",
+      "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 owed = ["polish", "qa"].filter((stage) => ci[stage].status === "owed");
+  lines.push(`Owed stages: ${owed.length ? owed.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 page of ci.changes.changed_pages) {
+    lines.push(`- Changed page: ${code(page.page_id)} (${code(page.built_path)})`);
+  }
+  if (!ci.changes.changed_pages.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" || 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,5 +1,6 @@
 // Doctor entry points: the doctor command, packet inspection and built-output inspection.
 import { resolveCampaignIdentity } from "../spec-source-identity.mjs";
+import { assessDoctorCi, doctorCiFailure } from "./ci.mjs";
 import { applyLocalPreviewToCheckpoint, applyLocalPreviewToPolishGate, carriedForwardMessage, CARRIED_FORWARD } from "../local-preview-policy.mjs";
 import { withHtmlScanSnapshot } from "../html-scan.mjs";
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -63,7 +64,7 @@ import {
   nextPrepareBuildBindingIssues,
   prepareBuildGateIssue,
   addPrepareBuildGateErrors,
-  checkpointExceptionPresent,
+  readinessStatus,
   buildNextStep,
 } from "./next-step.mjs";
 
@@ -132,6 +133,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 +161,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;
@@ -664,13 +682,7 @@ function inspectDoctorPacket(packetPath, { contextPath = undefined, reportPath =
       }
     }
   }
-  const status = errors.length
-    ? "blocked"
-    : checkpointExceptionPresent(derived)
-      ? "ready_with_waivers"
-      : warnings.length
-        ? "ready_with_warnings"
-        : "ready";
+  const status = errors.length ? "blocked" : readinessStatus(warnings, derived);
   const result = {
     schema_version: DOCTOR_SIDECAR_SCHEMA,
     generated_at: new Date().toISOString(),

package/src/doctor/next-step.mjs

@@ -413,7 +413,7 @@ export function assessPurchaseProofCoverage({ packet = null, report = null } = {
   };
 }
 
-function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate, purchaseProof = null, packet = null) {
+function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate, purchaseProof = null) {
   const polishGate = derived?.polish_gate || evaluatePolishGate({ report });
   const polishCheckpointGate = derived?.polish_checkpoint_gate || null;
   // prepare-build is the earliest lifecycle prerequisite. Surface its
@@ -542,6 +542,9 @@ function checkpointExceptionPresent(derived) {
     || derived?.polish_checkpoint_gate?.status === "waived";
 }
 
+// The readiness ladder below "blocked", written once: doctor's status, the
+// `next` command's status and doctor's `next` block each decide "blocked"
+// first, then call it with their own warnings.
 function readinessStatus(warnings, derived) {
   if (checkpointExceptionPresent(derived)) return "ready_with_waivers";
   return warnings.length ? "ready_with_warnings" : "ready";
@@ -664,7 +667,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, packet);
+  const picked = pickNextStage(report, { errors, derived }, prepareBuildGate, purchaseProof);
   // 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.
@@ -758,6 +761,6 @@ export {
   prepareBuildGateIssue,
   addPrepareBuildGateErrors,
   deployUrlFromReportOutputs,
-  checkpointExceptionPresent,
+  readinessStatus,
   buildNextStep,
 };

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;
+}