@nextcommerce/campaigns-os 1.59.0 → 1.61.0

package/src/built-site-scope.mjs

@@ -96,14 +96,14 @@ function listHtmlFiles(root, links = null) {
   return files.sort();
 }
 
-function routeForFile(campaignDir, file) {
+export function routeForFile(campaignDir, file) {
   const rel = relative(campaignDir, file).split(sep).join("/");
   if (rel === "index.html") return "";
   if (rel.endsWith("/index.html")) return rel.slice(0, -"/index.html".length);
   return rel.replace(/\.html$/i, "");
 }
 
-function pageIdForRoute(route) {
+export function pageIdForRoute(route) {
   if (!route) return "index";
   return route.replace(/\//g, "-").replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "index";
 }
@@ -290,9 +290,8 @@ export function synthesizeMinimalBuildPacket({
 // the same build. The manifest is `<path>\n<sha256>\n` per file, paths
 // relative to the output root with `/` separators and sorted by code point,
 // so directory walk order and the absolute location never leak into the
-// value. Page Kit (0.2.0) writes only rendered HTML and copied assets into
-// _site/, nothing it timestamps, so nothing is excluded by default; `exclude`
-// takes root-relative paths for a consumer whose build does stamp a file.
+// value. Page Kit (0.2.x and 0.3.x) writes only rendered HTML and copied
+// assets into _site/, nothing it timestamps, so every file is hashed.
 // Symbolic links are never build output and are skipped, not followed.
 export const BUILD_FINGERPRINT_ALGORITHM = "sha256-manifest/v1";
 
@@ -326,22 +325,17 @@ function sha256Hex(buffer) {
  * hand (`sha256sum` over each file, sort by path, hash the lines). `ok: false`
  * with `error` when the root is not a directory; an empty tree still hashes
  * (the empty manifest) so a wiped _site/ reads as a changed build, not a
- * missing one.
+ * missing one. `excluded` is always empty; doctor's build_output_fingerprint
+ * still reports it.
  */
-export function computeBuildFingerprint(outputDir, { exclude = [] } = {}) {
+export function computeBuildFingerprint(outputDir) {
   const root = String(outputDir || "");
   const base = { ok: false, algorithm: BUILD_FINGERPRINT_ALGORITHM, root, fingerprint: null, file_count: 0, excluded: [], manifest: null };
   if (!root || !existsSync(root) || !statSync(root).isDirectory()) {
     return { ...base, error: `Build output directory does not exist: ${root || "(empty)"}` };
   }
-  const excludeSet = new Set((Array.isArray(exclude) ? exclude : []).map((path) => String(path).split(sep).join("/")));
-  const excluded = [];
   const lines = [];
   for (const path of listFilesRelative(root)) {
-    if (excludeSet.has(path)) {
-      excluded.push(path);
-      continue;
-    }
     lines.push(`${path}\n${sha256Hex(readFileSync(join(root, path)))}\n`);
   }
   const manifest = lines.join("");
@@ -350,7 +344,6 @@ export function computeBuildFingerprint(outputDir, { exclude = [] } = {}) {
     ok: true,
     fingerprint: `sha256:${sha256Hex(Buffer.from(manifest, "utf8"))}`,
     file_count: lines.length,
-    excluded,
     manifest,
     error: null,
   };

package/src/campaign-identity.mjs

@@ -263,9 +263,11 @@ function gateBase(subject) {
  * A page marked `spec_page: false` is built output that no CampaignSpec page
  * builds to. It is still scanned, because it is still served, but a finding
  * that names it says so: such a file is usually left in `_site/` by an earlier
- * build, or built from an HTML file copied into the source (a design export's
- * `index.html` under `assets/`), and the repair is to remove it, not to retag
- * it.
+ * build, or built from an HTML file copied into the source, and the repair is
+ * to remove it, not to retag it. Both are page-kit 0.2.x behaviour (no
+ * `_site/` pruning; a design export's `index.html` under `assets/` builds as
+ * a page). 0.3.0 cleans `_site/<slug>/` and ignores `.html` under `assets/`,
+ * so there a stray is a source page no spec page claims.
  *
  * @param {{ subject: object, pages: Array<{ page_id: string, route?: string|null,
  *   file?: string|null, content: string, spec_page?: boolean,
@@ -415,7 +417,7 @@ export function evaluateCampaignIdentity({ subject, pages = [], expectedApiKey =
     // own instruction (retag, or add a missing tag to a real page) is dropped:
     // that edit would land on the wrong file.
     const named = stray.length > 2 ? `${stray.slice(0, -1).join(", ")}, and ${stray.at(-1)}` : stray.join(" and ");
-    finding.message = `${named} ${stray.length === 1 ? "is" : "are"} not the built page of any CampaignSpec page: built output left by an earlier build, or an HTML file copied into the source (a design export's index.html under assets/ builds as its own page). Remove the source file if there is one, delete the built file, then rebuild and record the build again; do not retag either page. What it causes: ${finding.evidence}`;
+    finding.message = `${named} ${stray.length === 1 ? "is" : "are"} not the built page of any CampaignSpec page: built output left by an earlier build, or an HTML file copied into the source (on page-kit 0.2.x a design export's index.html under assets/ builds as its own page). Remove the source file if there is one, delete the built file, then rebuild and record the build again; do not retag either page. What it causes: ${finding.evidence}`;
   }
 
   // evidence is the message's first sentence, kept apart only so a stray

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";
@@ -193,13 +195,9 @@ import {
 import {
   ASSEMBLY_REPORT_STAGE_KEYS,
   NEXT_STAGE_ORDER,
-  STAGE_TERMINAL_STATUS_PREFIXES,
   stageIsTerminal,
 } from "./orchestration-stage-contract.mjs";
-import {
-  currentBuildFingerprint,
-  evaluatePolishGate,
-} from "./polish-gate.mjs";
+import { currentBuildFingerprint } from "./polish-gate.mjs";
 import {
   assertPolishCaptureBindingUnchanged,
   capturePolishPageLoad,
@@ -221,6 +219,7 @@ import {
 import {
   loadPageKitCampaignEntry,
   PAGE_KIT_CAMPAIGNS_REL_PATH,
+  pageKitIgnoresAssetsHtml,
 } from "./page-kit-campaign-config.mjs";
 import {
   evaluatePageKitStoreProfile,
@@ -240,6 +239,7 @@ import {
   applySpecDerive,
   formatDeriveValue,
   isPageTreeIgnoredDir,
+  isPageTreeIgnoredPath,
   frontmatterPermalink,
   pageRouteForFile,
   permalinkRoute,
@@ -293,7 +293,7 @@ import {
   addPrepareBuildGateErrors,
   assessPurchaseProofCoverage,
   deployUrlFromReportOutputs,
-  checkpointExceptionPresent,
+  readinessStatus,
 } from "./doctor/next-step.mjs";
 
 export { derivePackagePin, localInstallStatus };
@@ -322,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]
@@ -353,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]
@@ -361,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
@@ -486,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
@@ -1051,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;
   }
 
@@ -1174,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;
   }
 
@@ -1847,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,
@@ -2287,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."],
@@ -2807,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;
@@ -2836,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({
@@ -2881,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,
     },
   };
 }
@@ -3546,10 +3574,10 @@ export async function specDeriveFromStoreCommand(args, { fetchImpl = globalThis.
 // the route each one builds to (filename-derived, or the file's permalink;
 // a permalink derive cannot read as a campaign route carries `problem` and a
 // null route). Discovery follows page-kit's own: every .html outside
-// `_layouts/` and `_includes/`, symlinked entries included. Returns null when
-// the directory does not exist, so the plan can say "no page tree" rather
-// than "no pages".
-function listPageKitPageFiles(outputDir, publicRouteSlug) {
+// `_layouts/` and `_includes/` (and, from page-kit 0.3.0, the top-level
+// `assets/`), symlinked entries included. Returns null when the directory
+// does not exist, so the plan can say "no page tree" rather than "no pages".
+function listPageKitPageFiles(outputDir, publicRouteSlug, { assetsHtmlIgnored = false } = {}) {
   if (!outputDir || !existsSync(outputDir) || !statSync(outputDir).isDirectory()) return null;
   const files = [];
   const walk = (dir) => {
@@ -3563,8 +3591,7 @@ function listPageKitPageFiles(outputDir, publicRouteSlug) {
       }
       if (!stats.isFile() || extname(entry.name).toLowerCase() !== ".html") continue;
       const path = relative(outputDir, fullPath).split(sep).join("/");
-      const segments = path.split("/");
-      if (segments.slice(0, -1).some(isPageTreeIgnoredDir)) continue;
+      if (isPageTreeIgnoredPath(path, { assetsHtmlIgnored })) continue;
       // page-kit honours a permalink before its filename rule, so the
       // frontmatter is read first (quoting, comments, BOM and CRLF as
       // page-kit's reader takes them); only a file with no usable permalink
@@ -3773,7 +3800,7 @@ export function specDeriveCommand(args, { store: storeRead = null } = {}) {
   try {
     if (existsSync(outputDir)) {
       const realOutputDir = realpathSync(outputDir);
-      if (realOutputDir === realTargetRepo || realOutputDir.startsWith(`${realTargetRepo}${sep}`)) pageFiles = listPageKitPageFiles(realOutputDir, publicRouteSlug);
+      if (realOutputDir === realTargetRepo || realOutputDir.startsWith(`${realTargetRepo}${sep}`)) pageFiles = listPageKitPageFiles(realOutputDir, publicRouteSlug, { assetsHtmlIgnored: pageKitIgnoresAssetsHtml(targetRepo) });
       else addIssue(result.warnings, "spec.derive.page_tree_escapes_repo", `${outputDir} resolves to ${realOutputDir}, outside the target repo; routes were not read from it.`);
     }
   } catch (error) {
@@ -4318,7 +4345,7 @@ export function nextStage(stage, args, ambient = null, { qcStandIns = null, qcRe
     }
   }
   const themeGate = doctor.derived?.theme_gate || null;
-  const polishGate = doctor.derived?.polish_gate || evaluatePolishGate({ report });
+  const polishGate = doctor.derived?.polish_gate;
   const polishCheckpointGate = doctor.derived?.polish_checkpoint_gate || null;
   // Packet 03 (INV-5 first slice): compare the ledger's self-report against
   // the repo's artifacts before any recommendation goes out. Additive:
@@ -4398,21 +4425,25 @@ export function nextStage(stage, args, ambient = null, { qcStandIns = null, qcRe
   const ready = [...doctor.ready];
   if (!doctor.ok && !doctorHasOnlyPolishGateErrors) errors.push(...doctor.errors.map((issue) => withPacketSubstitutedIssue(issue, packetPath)));
 
-  // Explicit stage requests are still downstream of prepare-build. Do not
-  // construct the requested stage's prompt or executable actions when the
-  // authoritative prepare gate is blocked or unavailable; return the same
-  // recovery-only shape as automatic stage selection.
-  if (NEXT_STAGE_ORDER.includes(stage) && prepareBuildGate) {
+  // prepare-build is upstream of every stage. While its authoritative gate is
+  // blocked or unavailable, doctor's picker chooses prepare-build, and an
+  // explicit stage request gets the same recovery-only shape (requested_stage
+  // names it) instead of that stage's prompt or executable actions.
+  if (prepareBuildGate) {
     addPrepareBuildGateErrors(errors, report, prepareBuildGate);
     return finalize({
       ok: false,
       status: "blocked",
       stage: "prepare-build",
-      requested_stage: stage,
+      ...(stage ? { requested_stage: stage } : {}),
       reason: prepareBuildGate.reason,
       errors,
       warnings,
       ready,
+      // Packet 03: when the artifacts contradict the ledger, do NOT tell
+      // the operator to start over — rerunning prepare-build/start is the
+      // most destructive documented recovery, and the ledger alone is not
+      // trustworthy evidence that it is needed.
       prompt: prepareBuildRecoveryPrompt,
       stage_blocked: true,
     });
@@ -4438,34 +4469,16 @@ export function nextStage(stage, args, ambient = null, { qcStandIns = null, qcRe
         prompt: `Resolve the doctor errors above before continuing. Re-run \`${cmd("doctor")} --packet <path> --write\` to record the recovery, then \`${cmd("next")} --packet <path>\` to advance.`,
       });
     }
-    if (picked.stage === "prepare-build") {
-      addPrepareBuildGateErrors(errors, report, prepareBuildGate);
-      return finalize({
-        ok: false,
-        status: "blocked",
-        stage: "prepare-build",
-        reason: picked.reason,
-        errors,
-        warnings,
-        ready,
-        // Packet 03: when the artifacts contradict the ledger, do NOT tell
-        // the operator to start over — rerunning prepare-build/start is the
-        // most destructive documented recovery, and the ledger alone is not
-        // trustworthy evidence that it is needed.
-        prompt: prepareBuildRecoveryPrompt,
-        stage_blocked: true,
-      });
-    }
     if (picked.stage === "done") {
       return finalize({
         ok: true,
-        status: checkpointExceptionPresent(doctor.derived) ? "ready_with_waivers" : (warnings.length ? "ready_with_warnings" : "ready"),
+        status: readinessStatus(warnings, doctor.derived),
         stage: "done",
         reason: picked.reason,
         errors,
         warnings,
         ready,
-        prompt: `Pipeline complete. All stages in the assembly report are in a terminal status. To repeat build work, do the work and run \`${cmd("record")} build --packet <path>\`; this makes downstream stages owed as needed. Run \`${cmd("qa")} run\` for QA. For a hosted deploy, record the URL and stage outcome as the deploy prompt describes. Then call \`${cmd("next")}\` again. If a run session is active, finish it with \`${cmd("run")} end\` so the Run Record is assembled and the session closes.${report?.stages?.qa?.status === "completed_with_warnings" ? " QA passed with exceptions; report them to the operator without clearing or waiving them or changing markup just to make them pass." : ""}`,
+        prompt: `Pipeline complete. All stages in the assembly report are in a terminal status. To repeat build work, do the work and run \`${cmd("record")} build --packet <path>\`; this makes downstream stages owed as needed. \`${cmd("record")} deploy\` records the served deploy, a loopback URL for a local-serve target or an https URL for a hosted one. Run \`${cmd("qa")} run\` for QA. Then call \`${cmd("next")}\` again. If a run session is active, finish it with \`${cmd("run")} end\` so the Run Record is assembled and the session closes.${report?.stages?.qa?.status === "completed_with_warnings" ? " QA passed with exceptions; report them to the operator without clearing or waiving them or changing markup just to make them pass." : ""}`,
       });
     }
     stage = picked.stage;
@@ -4509,13 +4522,7 @@ export function nextStage(stage, args, ambient = null, { qcStandIns = null, qcRe
     addThemeGateErrors(errors, themeGate, "qa");
     prompt = qaPrompt(packetPath, reportPath, packet, spec, intentSummary, polishCheckpointGate);
   }
-  const status = errors.length
-    ? "blocked"
-    : checkpointExceptionPresent(doctor.derived)
-      ? "ready_with_waivers"
-      : warnings.length
-        ? "ready_with_warnings"
-        : "ready";
+  const status = errors.length ? "blocked" : readinessStatus(warnings, doctor.derived);
   const result = {
     ok: errors.length === 0,
     status,
@@ -5094,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.
@@ -5105,7 +5112,7 @@ Rules:
 - Each checkout_step page's checkout form (<form data-next-checkout="form">) carries data-next-checkout-step="<its next_step>" and data-next-step-number="<step_number>" (Build Context page_kit frontmatter next_step and step_number); the checkout page's form carries neither. On select and checkout_step pages, frontmatter next_url is the Checkout's post-payment destination, the same meaning it has on the checkout page, and the layout renders it as next-success-url because the SDK reads that tag for express orders; next_step is the forward link. A landing page keeps next_url as its call-to-action target; if it has express checkout buttons, set its next-success-url to the Checkout's own next_url from the Build Context page_map, never to the landing page's next_url. Forward navigation uses the step form attribute or a plain link, never that meta tag. Page Kit frontmatter has no success_url key (success_url remains a CampaignSpec field on checkout pages).
 - After page-kit build, inspect rendered _site output before handoff: each active page should have a body, Campaign Cart runtime markers, SDK meta tags from CampaignSpec sdk_hints.meta_tags, and no stale copied funnel attribution.
 - Run page-kit build and SDK/template lint, then record build before polish: \`${cmd("record")} build --packet ${packetPath}${isLocalServePacket(packet) ? ` --build-environment ${LOCAL_PROOF_BUILD_ENVIRONMENT}` : ""} --adapter-decision <key>=<value>[,<key>=<value>...]\`. Record the value that is true for this build: for example, raw_html_conversion_status=completed once source HTML is converted, or not_required when there is none. Put all scalar adapter decisions in one comma-separated flag; a repeated flag keeps only the last. Use the allowed values in docs/build-packet.md. Record the nine recordable scalar decisions with the command, never by editing those fields in the Assembly Report. wrapper_policy is selected at intake with prepare-build --wrapper-policy or the source-html manifest's wrapper_policy option; the object-valued template_files_copied proof has no flag. It stamps stages.assembly.build_fingerprint with the fingerprint doctor computes from the built output (derived.build_output_fingerprint.value, sha256 over the sorted path+sha256 manifest of _site/<slug>/; doctor reports built_output.fingerprint_stale whenever the output on disk stops matching the recorded value), records report.design_source_package.material_fingerprint on stages.assembly.source_package_material_fingerprint when present, and sets stages.polish to "required" (required_by="build", required_for=["qa"]). Re-run it after every rebuild; never hand-edit these fields. Build must not mark stages.polish as completed/completed_with_warnings/skipped. If you applied a brand theme, run \`${cmd("record")} theme --packet ${packetPath}\` after record build: it reads each built commerce page's stylesheet links and records report.theme (status applied, load_order=after-next-core, css_path, commerce_pages, evidence), and refuses, writing nothing, when a page that loads next-core.css does not load the brand layer after it. Never hand-edit report.theme.
-- Capture the machine-readable build summary as an artifact: \`${PAGE_KIT_BUILD_SUMMARY_CAPTURE_COMMAND}\` (requires next-campaign-page-kit >= 0.1.4). Doctor verifies it for per-page build errors and Page Kit shape warnings (NESTED_NO_PERMALINK, DUPLICATE_OUTPUT, MISSING_FRONTMATTER, LAYOUT_NOT_FOUND). If the installed page-kit predates --json, record that in the assembly report instead of skipping silently.${localProofPromptLines(packet, packetPath)}`;
+- Capture the machine-readable build summary as an artifact: \`${PAGE_KIT_BUILD_SUMMARY_CAPTURE_COMMAND}\` (requires next-campaign-page-kit >= 0.1.4). Doctor verifies it for per-page build errors and Page Kit shape warnings (NESTED_NO_PERMALINK, DUPLICATE_OUTPUT, MISSING_FRONTMATTER, LAYOUT_NOT_FOUND), and on page-kit >= 0.3.0 for its top-level assetWarnings: ASSET_IGNORED names an .html file under assets/ that is neither built nor copied, so a link or iframe to it 404s. If the installed page-kit predates --json, record that in the assembly report instead of skipping silently.${localProofPromptLines(packet, packetPath)}`;
 }
 
 // Local proof mode lines for the build prompt: under local-serve the build is
@@ -5248,10 +5255,8 @@ function localServePlan(packet) {
 }
 
 function deployPrompt(packetPath, reportPath, packet, polishGate = null, polishCheckpointGate = null) {
-  if (packet.deploy?.target !== LOCAL_SERVE_DEPLOY_TARGET
-    && polishCheckpointGate?.code === "polish.hidden_eager_media.no_capturable_routes"
-    && !packet.deploy?.preview_url) {
-    return `Every mapped page is template stock, and the hosted preview URL is not recorded. Run \`${cmd("qa")} policy set --packet ${shellToken(packetPath)} --preview-url <url>\` after the preview is deployed, then \`${cmd("next")} --packet ${shellToken(packetPath)}\`.`;
+  if (hostedTemplateNeedsUsablePreview(packet, polishCheckpointGate)) {
+    return `Every mapped page is template stock, and deploy needs a hosted preview URL that differs from the production URL. Run \`${cmd("qa")} policy set --packet ${shellToken(packetPath)} --preview-url <url>\` after the preview is deployed, then \`${cmd("next")} --packet ${shellToken(packetPath)}\`.`;
   }
   const target = packet.deploy?.target || "unknown";
   const liveUrlPath = packet.deploy?.live_url_path || packet.campaign?.live_url_path || campaignRouteRoot(packet) || "/<slug>/";
@@ -5344,10 +5349,8 @@ function orderBumpRunReason(bumpCart) {
 }
 
 function qaPrompt(packetPath, reportPath, packet, spec = null, intent, polishCheckpointGate = null) {
-  if (packet.deploy?.target !== LOCAL_SERVE_DEPLOY_TARGET
-    && polishCheckpointGate?.code === "polish.hidden_eager_media.no_capturable_routes"
-    && !packet.deploy?.preview_url) {
-    return `Every mapped page is template stock, and QA needs the hosted preview URL. Run \`${cmd("qa")} policy set --packet ${shellToken(packetPath)} --preview-url <url>\`, then \`${cmd("next")} qa --packet ${shellToken(packetPath)}\`.`;
+  if (hostedTemplateNeedsUsablePreview(packet, polishCheckpointGate)) {
+    return `Every mapped page is template stock, and QA needs a hosted preview URL that differs from the production URL. Run \`${cmd("qa")} policy set --packet ${shellToken(packetPath)} --preview-url <url>\`, then \`${cmd("next")} --packet ${shellToken(packetPath)}\`.`;
   }
   const url = packet.deploy?.preview_url || packet.deploy?.production_url || "<preview-url>";
   const briefPath = packet.build_brief?.normalized_path || "(missing)";
@@ -5493,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 });
@@ -5506,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.",
   };
@@ -6107,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") {
@@ -7117,6 +7129,12 @@ function runSessionStatus(args, ambient = null) {
 // Session progress: incomplete assembly-report stages, the deviation count,
 // and the exact next command. Read-only and best-effort; the status command
 // must never fail because an artifact is missing or torn.
+//
+// The incomplete stages are the recorded statuses. Whether every stage is
+// actually done is `next`'s decision, not this one: an input change or a new
+// build owes a stage again while its recorded status still reads completed.
+// So the next command is always `next`, which names `run end` once the
+// campaign is done and a session is active.
 function runSessionProgress(found) {
   const packetPath = found.session.packet;
   if (!isNonEmptyString(packetPath) || !existsSync(packetPath)) return null;
@@ -7126,7 +7144,7 @@ function runSessionProgress(found) {
     const incomplete = [];
     for (const key of ASSEMBLY_REPORT_STAGE_KEYS) {
       const status = String(report?.stages?.[key]?.status || "");
-      if (!STAGE_TERMINAL_STATUS_PREFIXES.some((prefix) => status.startsWith(prefix))) {
+      if (!stageIsTerminal(status)) {
         incomplete.push({ stage: key, status: status || null });
       }
     }
@@ -7135,9 +7153,7 @@ function runSessionProgress(found) {
       incomplete_stages: incomplete,
       deviations,
       qa_attempt_count: Array.isArray(found.session.qa_attempts) ? found.session.qa_attempts.length : 0,
-      next_command: incomplete.length
-        ? `${cmd("next")} --packet ${packetPath} --json`
-        : `${cmd("run")} end --packet ${packetPath}`,
+      next_command: `${cmd("next")} --packet ${packetPath} --json`,
     };
   } catch {
     return null;

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()] };
+}