@nextcommerce/campaigns-os 1.60.0 → 1.61.0

package/src/cli.mjs

@@ -1,5 +1,7 @@
 import { campaignSpecIdentity, resolveCampaignIdentity, campaignIdentitiesMatch, localSpecIdentityFields } from "./spec-source-identity.mjs";
+import { withDoctorCiReport } from "./doctor/ci.mjs";
 import { createHash, randomUUID } from "node:crypto";
+import { resolveDesignFileReferences } from "./design-file-reference.mjs";
 import { withDesignSourcePublication } from "./design-source-publication.mjs";
 import { createDemo, demoArguments } from "./demo.mjs";
 import { execFileSync } from "node:child_process";
@@ -320,7 +322,7 @@ Usage:
                      [--wrapper-policy <strip_document_wrappers|preserve_document_wrappers|not_required|unknown>] [--design-manifest <path>]
                      [--allow-uncertified-template "<reason>"] [--order-path-depth <off|common|full>]
                      [--deploy-target <target>] [--preview-url <url>] [--production-url <url>] [--no-run-session] [--force]   # intake alias for prepare-build + doctor
-  campaigns-os doctor --packet <campaign-runtime.build.json> [--context <json>] [--report <json>] [--strip-paths] [--write] [--no-write] [--doctor-out <path>] [--proxy-base <url>] [--no-live-refs] [--json]   # inspection by default; --doctor-out requires --write; --no-write wins. When the packet's built _site/<route>/ exists and a public Campaigns API key resolves (packet, its local CampaignSpec, or the declared campaign-key env var), doctor makes one read-only GET of {proxy-base}/api/campaign under X-Campaign-Key to check each built page's shipping and package refs against the live campaign; --proxy-base overrides the canonical proxy (https, or a loopback host over http). --no-live-refs skips the read and records not_run with reason disabled. No key, no built page, or a failed read records derived.live_campaign_refs as not_run with its reason. Only doctor and qa run make this read; other commands that run doctor record not_read
+  campaigns-os doctor --packet <campaign-runtime.build.json> [--context <json>] [--report <json>] [--strip-paths] [--write] [--no-write] [--doctor-out <path>] [--proxy-base <url>] [--no-live-refs] [--ci] [--json]   # inspection by default; --doctor-out requires --write; --no-write wins. --ci: Markdown (or JSON ci object), exits 0 current / 3 owed / 4 unknown / 2 packet usage error; other doctor errors do not affect the CI exit. Without --ci: 0 ok / 2 errors. When the packet's built _site/<route>/ exists and a public Campaigns API key resolves (packet, its local CampaignSpec, or the declared campaign-key env var), doctor makes one read-only GET of {proxy-base}/api/campaign under X-Campaign-Key to check each built page's shipping and package refs against the live campaign; --proxy-base overrides the canonical proxy (https, or a loopback host over http). --no-live-refs skips the read and records not_run with reason disabled. No key, no built page, or a failed read records derived.live_campaign_refs as not_run with its reason. Only doctor and qa run make this read; other commands that run doctor record not_read
   campaigns-os doctor --built <page-kit-target-repo> --family <family> [--slug <slug>] [--base-url <url>] [--emit-packet [path]] [--json]   # L7: doctor a built _site/ with no Build Packet. Reads the local files only: --base-url is not fetched, it fills deploy.preview_url in the minimal packet (check served pages with qa run --site)
   campaigns-os bundle check --packet <campaign-runtime.build.json> [--require-qa] [--json]   # validate the canonical migration/readback JSON bundle; never substitutes markdown
   campaigns-os sdk storage-check --target <git-root> --target-sdk <x.y.z> --manifest <SDK-manifest.json> --scope <dir,file> [--exclude <dir,file>] [--json]
@@ -351,7 +353,7 @@ Usage:
   campaigns-os logout [--store <subdomain>]
   campaigns-os tooling status [--platform <claude|codex|agents|all>] [--target <skills-dir>] [--skills-revision <bundle-revision|skill-id@version>] [--packet <campaign-runtime.build.json>] [--force] [--json]   # install-mode, git, skill freshness, and local gateway login/store/expiry/reported version. --skills-revision checks the bundle revision the skill you loaded states on its first body line (or that one skill's <skill-id>@<version>) against the bundle THIS CLI ships: revision_check is match, mismatch or unchecked, and a mismatch prints the full status and exits 2 because skill text already in context cannot be refreshed by re-running — start a fresh session. The pin check reports one executable per project: the project pin first — the first exact spec for this package (x.y.z, =x.y.z or vx.y.z) on the walk up from the nearest package.json, devDependencies then dependencies in each, entering a workspace root and stopping there, never peerDependencies or optionalDependencies — then the Build Packet's campaigns_os_version (the project's campaign-runtime.build.json, or --packet <path>); the Pin: line names the key and manifest (or packet) each version came from; pin.status is match, stale_pin (the pin is not the running version), conflicting_pin (the two sources disagree) or unpinned (neither, or only a range; exit 0). stale_pin and conflicting_pin exit 2 with the file to change; --force (bare) overrides them, is reported as pin.forced and lands on the lifecycle journal entry. See docs/skills-revision.md
   campaigns-os tooling diagnose [--packet <packet>] [--platform <claude|codex|agents|all>] [--json]   # read-only redacted support summary
-  campaigns-os install-agent-context --target <page-kit-dir> [--dry-run]
+  campaigns-os install-agent-context --target <page-kit-dir> [--dry-run] [--json]
   campaigns-os next [${NEXT_STAGE_ORDER.join("|")}] --packet <json> [--no-write] [--no-remit] [--proxy-base <url>] [--json]   # no stage self-decides; returns gates[] + next_actions[] alongside the prompt
   campaigns-os next setup --packet <json> [--context <json>] [--report <json>] [--json]
   campaigns-os next build --packet <json> [--context <json>] [--report <json>] [--json]
@@ -359,7 +361,7 @@ Usage:
   campaigns-os next deploy --packet <json> --report <json> [--json]
   campaigns-os next qa --packet <json> --report <json> [--json]
   campaigns-os qa resolve --packet <json> [--base-url <url>] [--no-probe] [--probe-timeout-ms <ms>] [--json]   # probes the derived entry URLs; a dead route set reports routes_unresolved, an unprobed one ready_unprobed
-  campaigns-os qa run --packet <json> [--base-url <url>] [--currency <code>] [--browser] [--test-order <mode>] [--select-package <ref[:qty],...>] [--apply-coupon <code>] [--no-post-verdict] [--no-remit] [--no-live-refs] [--output-dir <dir>] [--json]
+  campaigns-os qa run --packet <json> [--base-url <url>] [--currency <code>] [--browser] [--test-order <mode>] [--select-package <ref[:qty],...>] [--apply-coupon <code>] [--test-email <email>] [--test-country <code> --test-address1 <line> --test-city <city> --test-province <code> --test-postal <code>] [--no-post-verdict] [--no-remit] [--no-live-refs] [--output-dir <dir>] [--json]
   campaigns-os qa promote --packet <json> --verdict <full-verdict.json> [--json]   # project one explicit qa-output verdict to the committed .campaign-runtime/qa-verdict.json sidecar
   campaigns-os qa publish --packet <json> [--verdict <full-verdict.json>] [--republish] [--proxy-base <url>] [--dry-run] [--json]   # post an already-stored verdict (the sidecar's run, or --verdict) to the QA portal without a re-run or an order; refuses a stale spec_hash or an already-published verdict. --dry-run runs every one of those refusal checks and prints what would be posted (endpoint, verdict run id, payload bytes) without the POST
   campaigns-os qa policy set --packet <json> [--allowed-domains-confirmed true|false] [--deploy-target <target>] [--preview-url <url>] [--production-url <url>] [--order-path-depth <off|common|full>] [--json]   # --order-path-depth writes qa.proof_policy.order_path_depth and refreshes the assembly report's proof_policy mirror
@@ -484,14 +486,14 @@ export async function main(argv, { authentication, qcStandIns } = {}) {
     console.log(packageVersion());
     return;
   }
-  return runInvocation(parseArgs(argv), {
+  return withDoctorCiReport(parseArgs(argv), (args) => runInvocation(args, {
     dispatch: (command, args, context) => dispatch(command, args, { ...context, argv, authentication, qcStandIns }),
     closeOutStaleRunSessions,
     ambientRunSession,
     lifecycleIdentity,
     persistLifecycle: persistLifecycleIfRequested,
     autoEndAfterQa: autoEndRunSessionAfterTerminalQa,
-  });
+  }));
 }
 
 // The lifecycle entry's identity (T6): its argv shape and its run_id. Ambient
@@ -1049,8 +1051,15 @@ async function dispatch(command, args, { recorder = NOOP_RECORDER, ambient = nul
     const liveCampaign = await readDoctorLiveCampaign(args);
     const result = doctorCommand(args, { liveCampaign, qcStandIns });
     if (!result.ok) recorder.recordFindingCodes(result.errors?.map((issue) => issue.code));
-    writeResult(result, args, result.ok ? 0 : 2);
-    printDoctorTinyPrompt(result, args);
+    if (args.ci === true) {
+      const { formatDoctorCi, DOCTOR_CI_EXIT_CODES } = await import("./doctor/ci.mjs");
+      if (!args.json) console.log(formatDoctorCi(result));
+      else writeResult(result, args, 0);
+      process.exitCode = result.ci?.exit_code ?? result.exit_code ?? DOCTOR_CI_EXIT_CODES.usage;
+    } else {
+      writeResult(result, args, result.ok ? 0 : 2);
+      printDoctorTinyPrompt(result, args);
+    }
     return;
   }
 
@@ -1172,8 +1181,15 @@ async function dispatch(command, args, { recorder = NOOP_RECORDER, ambient = nul
 
   if (command === "install-agent-context") {
     const target = requireArg(args, "target");
-    const result = installAgentContext(resolve(target), Boolean(args["dry-run"]));
-    writeResult(result, args, 0);
+    const dryRun = isDryRun(args);
+    const result = installAgentContext(resolve(target), dryRun);
+    if (dryRun && !args.json) {
+      for (const file of result.file_contents) {
+        console.log(`Destination: ${file.destination}\n${file.content}`);
+      }
+    } else {
+      writeResult(result, args, 0);
+    }
     return;
   }
 
@@ -1845,6 +1861,7 @@ function prepareBuildUnderLock({
   // campaign's report), and the previous brief carries field provenance.
   const priorBriefInputs = priorBriefInputsForIntake({ reportPath, briefPath, identity: { spec: { map_id: mapId, ...(localSpecId ? { local_spec_id: localSpecId } : {}) }, campaign: { public_route_slug: publicRouteSlug } } });
   const buildBrief = createCampaignBuildBriefArtifact({
+    designFiles: resolveDesignFileReferences({ activePages, mappings: matched.mappings, manifest: manifestResult.manifest }).pages,
     inputPath: briefDiscovery?.path || null,
     inputSource: briefDiscovery?.source || null,
     spec,
@@ -2285,7 +2302,7 @@ function assemblyThemeFromContext(theme) {
     load_order: "unknown",
     commerce_pages: [],
     evidence: wroteCss
-      ? ["prepare-build auto-generated .campaign-runtime/theme/brand-theme.css; build should copy that existing artifact into campaign assets and load it after next-core.css on commerce pages."]
+      ? ["prepare-build auto-generated .campaign-runtime/theme/brand-theme.css; build should copy that existing artifact (and brand-fonts.css, when written) into campaign assets and load it after next-core.css on commerce pages."]
       : theme.generated?.can_generate
         ? ["theme inspect found a generatable brand theme; run theme generate or explicit auto policy before applying."]
         : ["theme inspect completed; no generated brand theme was applied during prepare-build."],
@@ -2805,6 +2822,8 @@ export async function polishCaptureCommand(args, options = {}) {
     adapterCloseDeadlineMs: options.adapterCloseDeadlineMs,
     probeClock: options.probeClock,
     targetRepo,
+    visual: { packetPath, targetRepo, ...options.visual },
+    onFrozen: options.onFrozen,
   });
   // Nothing was measured: the held plan error stands.
   if (heldPlanError && !capture.readability) throw heldPlanError;
@@ -2834,6 +2853,8 @@ export async function polishCaptureCommand(args, options = {}) {
       pageLoad: capture.page_load,
       mediaWeight: capture.media_weight,
       readability: capture.readability,
+      captures: capture.captures,
+      elementParity: capture.element_parity,
       now: options.now ?? new Date(),
     });
     checkpoint = evaluateRecordedHiddenEagerMediaCheckpoint({
@@ -2879,6 +2900,15 @@ export async function polishCaptureCommand(args, options = {}) {
       route_scope: capture.plan?.route_scope ?? null,
       routes: (capture.plan?.routes ?? []).map((route) => route.requested_route),
       viewports: (capture.plan?.viewports ?? []).map((viewport) => viewport.key),
+      visual: capture.captures ? { cells: capture.captures.cells.length,
+        rendered: capture.captures.cells.filter((cell) => cell.status === "rendered").length,
+        comparisons_compared: capture.captures.comparisons.filter((comparison) => comparison.status === "compared").length,
+        comparisons_unsupported: capture.captures.comparisons.filter((comparison) => comparison.status === "unsupported").length,
+        dependencies: capture.captures.dependencies, adapters: capture.captures.adapters,
+        // A run budget spent: a cell never rendered, or a decode or diff never ran (§2.4).
+        budget_exhausted: capture.captures.cells.some((cell) => cell.status === "run_budget_exhausted")
+          || capture.captures.references.some((reference) => reference.verification?.reason === "verify_budget_exhausted")
+          || capture.captures.comparisons.some((comparison) => comparison.reason === "diff_budget_exhausted") } : null,
     },
   };
 }
@@ -5071,7 +5101,7 @@ Rules:
 - Prepared AI/exported HTML must be converted into page-kit-ready source first: keep page-owned body markup, strip document wrappers, add YAML frontmatter, move shared CSS/assets into the campaign structure, and use Liquid helpers only for page-kit links/assets/includes. Page Kit publishes src/<slug>/assets/config.js as /<slug>/config.js and src/<slug>/assets/products/foo.png as /<slug>/products/foo.png; do not leave raw /assets/... or /<slug>/assets/... references in rendered pages.
 - Preserve prepared source HTML for landing/presell pages when it is a real standalone design.
 - For checkout/upsell/downsell/receipt, use the starter template as the SDK contract reference only: preserve required data-next controls and runtime wiring, but let the campaign/source own visual chrome, copy hierarchy, imagery, and brand layer.
-- Read context.theme and .campaign-runtime/theme/theme-report.json when present. If a fresh brand-theme.css exists, copy it into the campaign assets/css folder and list it after next-core.css in checkout/upsell/downsell/receipt frontmatter styles; if policy is inspect_only, generate or skip explicitly before applying a new brand layer.
+- Read context.theme and .campaign-runtime/theme/theme-report.json when present. If a fresh brand-theme.css exists, copy it into the campaign assets/css folder and list it after next-core.css in checkout/upsell/downsell/receipt frontmatter styles; when theme generate also wrote brand-fonts.css (the design's own faces), copy it beside brand-theme.css and list it on the same pages; if policy is inspect_only, generate or skip explicitly before applying a new brand layer.
 - Generated brand-theme.css v0 is root-variable-only. Do not edit SDK-owned selectors, package controls, payment fields, totals, submit controls, receipt templates, route meta tags, or SDK JavaScript as part of theme application.
 - If you copy starter-template files, copy the selected family atomically with dependent pages, _includes, _layouts, assets/css, and assets/js; do not copy only checkout.html and receipt.html.
 - Resolve SDK routing meta tags to campaign-root paths such as ${campaignRouteRoot(packet) || `/${packet.campaign.public_route_slug}/`}upsell/, not source filenames or unrooted spec literals.
@@ -5466,10 +5496,13 @@ function installAgentContext(targetRepo, dryRun = false) {
     ["copilot-instructions.md", join(ROOT, "agents/copilot/copilot-instructions.md")],
   ];
   const written = [];
+  const fileContents = [];
   if (!dryRun) mkdirSync(outDir, { recursive: true });
   for (const [name, source] of files) {
     const dest = join(outDir, name);
-    if (!dryRun) writeFileSync(dest, readFileSync(source, "utf8"));
+    const content = readFileSync(source, "utf8");
+    if (!dryRun) writeFileSync(dest, content);
+    else fileContents.push({ destination: dest, content });
     written.push(dest);
   }
   const gitignore = ensureRuntimeStateIgnored(targetRepo, { dryRun });
@@ -5479,6 +5512,7 @@ function installAgentContext(targetRepo, dryRun = false) {
     target_repo: targetRepo,
     directory: outDir,
     files: written,
+    ...(dryRun ? { file_contents: fileContents } : {}),
     gitignore,
     note: "Context files are staged under .campaign-runtime/agent-context and do not overwrite root agent files.",
   };
@@ -6080,7 +6114,12 @@ function toolingCommand(args) {
         ? stalePlatforms.map((platform) => ["--platform", platform])
         : [["--platform", args.platform || "all"]];
     const commands = invocations.map((skillArgs) => `${cli.invocation_prefix} install-skills ${skillArgs.join(" ")}`);
-    actions.push(`Refresh installed skills: ${commands.join(" and ")}. ${SKILLS_READ_NOW_FOLLOW_UP}`);
+    // A per-platform refresh names the harnesses it is for, so a session in
+    // another harness does not read it as its own required step (#683).
+    const forHarnesses = !args.target && skillScope.scope === "installed_platforms" && stalePlatforms.length < SKILL_PLATFORMS.length
+      ? ` (for ${stalePlatforms.map((id) => SKILL_PLATFORMS.find((platform) => platform.id === id)?.label || id).join(" and ")}; not needed in a session that uses another harness)`
+      : "";
+    actions.push(`Refresh installed skills: ${commands.join(" and ")}${forHarnesses}. ${SKILLS_READ_NOW_FOLLOW_UP}`);
   }
 
   if (install.mode === "checkout" && cli.global_binary.status === "not_found") {

package/src/design-file-reference.mjs

@@ -0,0 +1,93 @@
+import { collectFigmaProvenanceFindings } from "./doctor/source-provenance.mjs";
+import { createHash } from "node:crypto";
+import { canonicalJson } from "./polish-capture.mjs";
+
+const VIEWPORTS = ["desktop", "tablet", "mobile"];
+const nonEmpty = (value) => typeof value === "string" && value.trim().length > 0;
+const object = (value) => value && typeof value === "object" && !Array.isArray(value);
+const absoluteHttps = (value) => {
+  if (!nonEmpty(value)) return null;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" ? url : null;
+  } catch { return null; }
+};
+
+// Declared links are data. No design-file reader or network access lives here.
+export function normalizeDesignFileReference(value) {
+  const warnings = [];
+  const url = object(value) && absoluteHttps(value.file_url);
+  if (!url) return { declaration: null, warnings: ["file_url must be a non-empty absolute https: URL"] };
+  const type = nonEmpty(value.type) ? value.type.toLowerCase() : (url.hostname === "figma.com" || url.hostname.endsWith(".figma.com")) ? "figma" : "other";
+  let fileKey = null;
+  if (type === "figma") {
+    const parts = url.pathname.split("/");
+    const index = parts.findIndex((part) => ["file", "design", "proto", "board"].includes(part));
+    let candidate = index < 0 ? null : parts[index + 1];
+    const branch = parts.indexOf("branch", index + 2);
+    if (index >= 0 && branch >= 0 && /^[A-Za-z0-9]+$/.test(parts[branch + 1] ?? "")) candidate = parts[branch + 1];
+    if (typeof candidate === "string" && /^[A-Za-z0-9]+$/.test(candidate)) fileKey = candidate;
+  }
+  const identity = fileKey == null ? { type, url: url.origin + url.pathname } : { type, file_key: fileKey };
+  const file_identity_sha256 = createHash("sha256").update(canonicalJson(identity)).digest("hex");
+  const frames = {};
+  for (const viewport of VIEWPORTS) {
+    if (!object(value.breakpoints) || !Object.hasOwn(value.breakpoints, viewport)) continue;
+    const link = value.breakpoints[viewport];
+    let frame;
+    try { frame = nonEmpty(link) ? new URL(link) : null; } catch { frame = null; }
+    if (!frame) { warnings.push(`breakpoints.${viewport} must be an absolute frame URL`); continue; }
+    frames[viewport] = { url: link, node_id: frame.searchParams.get("node-id")?.replaceAll("-", ":") ?? null };
+  }
+  return { declaration: { type, file_url: value.file_url, file_key: fileKey, identity, file_identity_sha256, frames }, warnings };
+}
+
+export function resolveDesignFileReferences({ activePages = [], mappings = [], manifest = null, specChannel = { mode: "intake" } } = {}) {
+  const pages = [];
+  const files = new Map();
+  // Intake records only Figma spec pointers backed by #534's provenance test.
+  // Doctor first uses today's intake declaration. Only a page with recorded
+  // design-file lineage can fall back to its Figma spec without provenance.
+  // Manifest declarations stand alone; a shared file's producer is not per-page.
+  const exportProvenance = manifest != null && !collectFigmaProvenanceFindings(manifest).some((finding) => finding.severity === "provenance");
+  const producer = manifest?.producer_provenance;
+  const producerKeys = new Set([producer?.figma_file_key, ...(Array.isArray(producer?.figma_file_keys) ? producer.figma_file_keys : [])].filter(nonEmpty));
+  for (const page of activePages) {
+    const mapping = mappings.find((entry) => entry?.page_id === page.id);
+    if (!nonEmpty(mapping?.path)) continue;
+    const matches = (Array.isArray(manifest?.pages) ? manifest.pages : []).filter((entry) => entry?.page_id === page.id && entry.path === mapping.path);
+    const manifestValue = matches.length === 1 ? matches[0].design_file : null;
+    const specDeclaration = normalizeDesignFileReference(page.design_source).declaration;
+    const fromManifest = normalizeDesignFileReference(manifestValue);
+    const intakeSpec = specDeclaration?.type === "figma" && exportProvenance ? specDeclaration : null;
+    const fallbackSpec = !intakeSpec && !fromManifest.declaration
+      && specChannel.mode === "doctor" && specChannel.recordedPageIds?.has(page.id)
+      && specDeclaration?.type === "figma" ? specDeclaration : null;
+    const fromSpec = intakeSpec || fallbackSpec;
+    const declaration = fromSpec || fromManifest.declaration;
+    if (!declaration) continue;
+    const declared_by = fromSpec ? "campaign_spec" : "source_html_manifest";
+    let conflict = null;
+    // Provenance decides which declaration records lineage, never whether a
+    // Figma spec that disagrees with the manifest is reported.
+    const specNamed = fromSpec || (specDeclaration?.type === "figma" ? specDeclaration : null);
+    if (specNamed && fromManifest.declaration) {
+      const other = fromManifest.declaration;
+      const frames = VIEWPORTS.filter((viewport) => specNamed.frames[viewport] && other.frames[viewport] && specNamed.frames[viewport].node_id !== other.frames[viewport].node_id).sort();
+      if (specNamed.file_identity_sha256 !== other.file_identity_sha256 || frames.length) {
+        conflict = { kind: "spec_vs_manifest", identities: [specNamed.file_identity_sha256, other.file_identity_sha256].sort(), ...(frames.length ? { frames } : {}) };
+      }
+    }
+    if (!conflict && declaration.type === "figma" && declaration.file_key && producerKeys.size && !producerKeys.has(declaration.file_key)) {
+      conflict = { kind: "producer_file_key", identities: [declaration.file_identity_sha256] };
+    }
+    pages.push({ page_id: page.id, declaration, declared_by, conflict, warnings: manifestValue == null ? [] : fromManifest.warnings });
+    const sha = declaration.file_identity_sha256;
+    if (!files.has(sha)) files.set(sha, { contribution_id: `design-file-${sha.slice(0, 12)}`, identity: declaration.identity, file_url: declaration.file_url, producer: declared_by, pages: [] });
+    const file = files.get(sha);
+    // A shared file keeps the manifest's provenance if any page declared it there.
+    if (declared_by === "source_html_manifest") file.producer = declared_by;
+    file.pages.push(page.id);
+  }
+  return { pages, files: [...files.values()] };
+}

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";
@@ -3674,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));
@@ -3988,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");
+}