@nextcommerce/campaigns-os 1.59.0 → 1.60.0

package/src/built-site-scope.mjs

@@ -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

@@ -193,13 +193,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 +217,7 @@ import {
 import {
   loadPageKitCampaignEntry,
   PAGE_KIT_CAMPAIGNS_REL_PATH,
+  pageKitIgnoresAssetsHtml,
 } from "./page-kit-campaign-config.mjs";
 import {
   evaluatePageKitStoreProfile,
@@ -240,6 +237,7 @@ import {
   applySpecDerive,
   formatDeriveValue,
   isPageTreeIgnoredDir,
+  isPageTreeIgnoredPath,
   frontmatterPermalink,
   pageRouteForFile,
   permalinkRoute,
@@ -293,7 +291,7 @@ import {
   addPrepareBuildGateErrors,
   assessPurchaseProofCoverage,
   deployUrlFromReportOutputs,
-  checkpointExceptionPresent,
+  readinessStatus,
 } from "./doctor/next-step.mjs";
 
 export { derivePackagePin, localInstallStatus };
@@ -3546,10 +3544,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 +3561,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 +3770,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 +4315,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 +4395,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 +4439,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 +4492,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,
@@ -5105,7 +5082,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 +5225,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 +5319,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)";
@@ -7117,6 +7090,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 +7105,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 +7114,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/doctor/checks.mjs

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

package/src/doctor/inspect.mjs

@@ -63,7 +63,7 @@ import {
   nextPrepareBuildBindingIssues,
   prepareBuildGateIssue,
   addPrepareBuildGateErrors,
-  checkpointExceptionPresent,
+  readinessStatus,
   buildNextStep,
 } from "./next-step.mjs";
 
@@ -664,13 +664,7 @@ function inspectDoctorPacket(packetPath, { contextPath = undefined, reportPath =
       }
     }
   }
-  const status = errors.length
-    ? "blocked"
-    : checkpointExceptionPresent(derived)
-      ? "ready_with_waivers"
-      : warnings.length
-        ? "ready_with_warnings"
-        : "ready";
+  const status = errors.length ? "blocked" : readinessStatus(warnings, derived);
   const result = {
     schema_version: DOCTOR_SIDECAR_SCHEMA,
     generated_at: new Date().toISOString(),

package/src/doctor/next-step.mjs

@@ -413,7 +413,7 @@ export function assessPurchaseProofCoverage({ packet = null, report = null } = {
   };
 }
 
-function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate, purchaseProof = null, packet = null) {
+function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate, purchaseProof = null) {
   const polishGate = derived?.polish_gate || evaluatePolishGate({ report });
   const polishCheckpointGate = derived?.polish_checkpoint_gate || null;
   // prepare-build is the earliest lifecycle prerequisite. Surface its
@@ -542,6 +542,9 @@ function checkpointExceptionPresent(derived) {
     || derived?.polish_checkpoint_gate?.status === "waived";
 }
 
+// The readiness ladder below "blocked", written once: doctor's status, the
+// `next` command's status and doctor's `next` block each decide "blocked"
+// first, then call it with their own warnings.
 function readinessStatus(warnings, derived) {
   if (checkpointExceptionPresent(derived)) return "ready_with_waivers";
   return warnings.length ? "ready_with_warnings" : "ready";
@@ -664,7 +667,7 @@ function buildNextStep(errors, warnings, derived, report = null, packet = null,
     && (polishGate.status === "blocked" || polishCheckpointGate?.status === "blocked");
   const codes = new Set([...errors, ...warnings].map((issue) => issue.code));
   const purchaseProof = report ? assessPurchaseProofCoverage({ packet, report }) : null;
-  const picked = pickNextStage(report, { errors, derived }, prepareBuildGate, purchaseProof, packet);
+  const picked = pickNextStage(report, { errors, derived }, prepareBuildGate, purchaseProof);
   // The picker's vocabulary and this table must not drift apart: a stage the
   // table does not know would otherwise be relabelled as an operator step and
   // sliced into the whole ladder. Fail loudly instead.
@@ -758,6 +761,6 @@ export {
   prepareBuildGateIssue,
   addPrepareBuildGateErrors,
   deployUrlFromReportOutputs,
-  checkpointExceptionPresent,
+  readinessStatus,
   buildNextStep,
 };

package/src/orchestration-stage-contract.mjs

@@ -50,9 +50,12 @@ export function reportKeyForCliStage(cliStage) {
  * "completed", "completed_with_warnings", and "completed_partial" all
  * count as terminal under "completed". This matches how the existing
  * stages already report sub-statuses (see report.stages.assembly.status
- * shapes in src/cli.mjs and qa/shared/qa-verdict.js). Shared here so the
- * `next` picker, the session progress summary and the Assembly Report's own
- * derived summary (src/stage-ledger.mjs) read one definition of "done".
+ * shapes in src/cli.mjs and qa/shared/qa-verdict.js). This is the rule for a
+ * RECORDED status only (the session progress summary's incomplete stages,
+ * the prepare-build gate, doctor's checks). Whether a stage is done is
+ * decided on its effective status (src/input-currency.mjs), which the `next`
+ * picker and the Assembly Report's derived summary (src/stage-ledger.mjs)
+ * read: a stage owed again is not done, whatever status it records.
  */
 export const STAGE_TERMINAL_STATUS_PREFIXES = Object.freeze(["completed", "skipped"]);
 

package/src/page-kit-build-summary.mjs

@@ -165,9 +165,29 @@ export function evaluatePageKitBuildSummary({
     }
   }
 
+  // page-kit >= 0.3.0 neither builds nor copies .html under assets/ and lists
+  // each such file in a top-level assetWarnings array (ASSET_IGNORED), never
+  // in pages[].warnings. A link or iframe to one 404s on the built site, and
+  // this is the only signal, so it is surfaced, but never escalated: removing
+  // or moving the file is the author's call. Entries carry no campaignSlug;
+  // the file path (src/<slug>/assets/...) names the campaign.
+  const assetWarnings = Array.isArray(summary.assetWarnings)
+    ? summary.assetWarnings.filter((warning) => typeof warning?.file === "string" && `/${warning.file.replace(/\\/g, "/")}`.includes(`/${publicRouteSlug}/assets/`))
+    : [];
+  for (const warning of assetWarnings) {
+    flagged += 1;
+    warnings.push({
+      code: "built_output.build_asset_warning",
+      message:
+        `Page Kit did not build or copy "${warning.file}": [${warning.code}] ${warning.message}. ` +
+        `A link or iframe to it 404s on the built site; move it out of assets/ if it is a page, or remove it.`,
+      detail: { file: warning.file, warning_code: warning.code },
+    });
+  }
+
   if (failed === 0 && flagged === 0) {
     ready.push(
-      `Page Kit build summary verified for "${publicRouteSlug}": ${campaignPages.length} page(s) built, no build errors or shape warnings`
+      `Page Kit build summary verified for "${publicRouteSlug}": ${campaignPages.length} page(s) built, no build errors, shape warnings or asset warnings`
     );
   }
 

package/src/page-kit-campaign-config.mjs

@@ -1,9 +1,28 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { compareVersions, extractVersion } from "./repo-scan.mjs";
 import { normalizePublicRouteSlug } from "./route-identity.mjs";
 
 export const PAGE_KIT_CAMPAIGNS_REL_PATH = "_data/campaigns.json";
 
+// next-campaign-page-kit 0.3.0 stopped building or copying .html under a
+// campaign's top-level assets/. Source-page discovery follows the target's
+// installed page-kit, read from node_modules the way tooling setup reads it;
+// a missing, unreadable or malformed install keeps the 0.2.x rule. That is
+// deliberate: doctor's built-page lookup calls this from about ten checks, so
+// throwing would take doctor down over a broken install that the build itself
+// fails on loudly, and tooling setup already refuses a declared page-kit that
+// is not installed.
+export const PAGE_KIT_ASSETS_HTML_IGNORED_FROM = "0.3.0";
+export function pageKitIgnoresAssetsHtml(targetRepo) {
+  try {
+    const { version } = JSON.parse(readFileSync(join(targetRepo, "node_modules", "next-campaign-page-kit", "package.json"), "utf8"));
+    return extractVersion(version) !== null && compareVersions(version, PAGE_KIT_ASSETS_HTML_IGNORED_FROM) >= 0;
+  } catch {
+    return false;
+  }
+}
+
 // Public doctor/next/verdict evidence must never inherit arbitrary merchant
 // configuration from campaigns.json. The raw entry is validation-local; this
 // fixed projection is the only loader metadata safe to retain in artifacts.

package/src/polish-gate.mjs

@@ -45,11 +45,7 @@ function terminalAssembly(report) {
 }
 
 export function currentBuildFingerprint(report) {
-  return normalizeString(report?.stages?.assembly?.build_fingerprint)
-    || normalizeString(report?.stages?.assembly?.artifact_fingerprint)
-    || normalizeString(report?.build_fingerprint)
-    || normalizeString(report?.artifact_fingerprint)
-    || null;
+  return normalizeString(report?.stages?.assembly?.build_fingerprint) || null;
 }
 
 export function currentSourcePackageMaterialFingerprint(report) {

package/src/progress-node.mjs

@@ -6,6 +6,7 @@ import {join,resolve,dirname} from 'node:path';
 import {PROGRESS_SCHEMA_VERSION,PROGRESS_STAGES,PROGRESS_STAGE_STATUSES,PROGRESS_CONTINUATIONS,PROGRESS_ACTION_IDS,PROGRESS_GATE_IDS,canonicalProgressJson,progressSnapshotId,verifyProgressSnapshot} from './progress.mjs';
 import {specMaterialHash} from './spec-identity.mjs';
 import {effectiveStageStatus} from './input-currency.mjs';
+import {qaRecordedBuildFingerprint} from './stage-ledger.mjs';
 import {sameFile} from './fs-identity.mjs';
 import {withDirectoryLock} from './directory-lock.mjs';
 import {resolveConsent,CANONICAL_REMIT_SCOPE,normalizeConsentScope,announceDefaultOnTelemetry} from './consent.mjs';
@@ -64,7 +65,7 @@ export function projectProgressObservation({workspace,context,report,doctor,cont
   // The report is also bound to the spec material on disk now, so output and
   // verdict evidence recorded against it can match.
   const reportBound=stagesBound&&localHash===hash(report?.identity?.spec_material_hash);
-  const qaSource=hash(report?.stages?.qa?.evidence?.source_build_fingerprint);
+  const qaSource=hash(qaRecordedBuildFingerprint(report));
   const verdict=qaResult?.verdict;
   const qa=verdict?{
     verdict_id:id(verdict.run_id),disposition:accepted(verdict.disposition,['ready','ready_with_exceptions','blocked']),

package/src/spec-derive.mjs

@@ -56,15 +56,29 @@ const ROUTING_HINT_FIELDS = Object.freeze({
 });
 
 // The directories page-kit's own discovery ignores (`_layouts`, `_includes`;
-// everything else under the campaign root, `assets/` and `_data/` included,
-// is rendered when it is .html), plus the two no build reads. The CLI walker
-// prunes with this and pageRouteForFile filters with it, so the list lives
-// in one place.
+// on 0.2.x everything else under the campaign root, `assets/` and `_data/`
+// included, is rendered when it is .html), plus the two no build reads. The
+// CLI walker prunes with this and pageRouteForFile filters with it, so the
+// list lives in one place.
 export const PAGE_TREE_IGNORED_DIRS = Object.freeze(["_layouts", "_includes", "node_modules", ".git"]);
 export function isPageTreeIgnoredDir(name) {
   return PAGE_TREE_IGNORED_DIRS.includes(name);
 }
 
+// Whether a campaign-relative file sits where page-kit renders no page. From
+// 0.3.0 page-kit also skips the campaign's top-level `assets/` (its
+// `*/assets/**` glob; a nested `offers/assets/` still renders), so the caller
+// says which rule the target's installed page-kit follows. Backslashes and
+// leading slashes read as pageRouteForFile reads them.
+export function isPageTreeIgnoredPath(relativePath, { assetsHtmlIgnored = false } = {}) {
+  const dirs = normalizePageTreePath(relativePath).split("/").slice(0, -1);
+  return dirs.some(isPageTreeIgnoredDir) || (assetsHtmlIgnored && dirs[0] === "assets");
+}
+
+function normalizePageTreePath(relativePath) {
+  return String(relativePath || "").replace(/\\/g, "/").replace(/^\/+/, "");
+}
+
 function isPlainObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -114,13 +128,14 @@ function containerProblem(spec, path) {
 // `upsell/`, intermediate directories ignored with its NESTED_NO_PERMALINK
 // warning), and `index.html` is the entry route "". A nested `index.html`
 // would collide with the campaign root (page-kit's DUPLICATE_OUTPUT), so it
-// is not a page this reads. Files under `_layouts/` or `_includes/` return
-// null, as page-kit never renders them.
-export function pageRouteForFile(relativePath) {
-  const path = String(relativePath || "").replace(/\\/g, "/").replace(/^\/+/, "");
+// is not a page this reads. Files under `_layouts/` or `_includes/` (and,
+// with assetsHtmlIgnored, the top-level `assets/`) return null, as page-kit
+// never renders them.
+export function pageRouteForFile(relativePath, { assetsHtmlIgnored = false } = {}) {
+  const path = normalizePageTreePath(relativePath);
   if (!path || !/\.html$/i.test(path)) return null;
   const segments = path.split("/");
-  if (segments.slice(0, -1).some(isPageTreeIgnoredDir)) return null;
+  if (isPageTreeIgnoredPath(path, { assetsHtmlIgnored })) return null;
   const basename = segments[segments.length - 1].replace(/\.html$/i, "");
   if (basename === "index") return segments.length === 1 ? "" : null;
   return `${basename}/`;

package/src/stage-ledger.mjs

@@ -11,7 +11,6 @@ import {
   NEXT_STAGE_CONTRACTS,
   NEXT_STAGE_OWNERS,
   stageIsBlocked,
-  stageIsTerminal,
 } from "./orchestration-stage-contract.mjs";
 
 const PRODUCER_STAGES = new Set(["doctor", "qa"]);
@@ -200,6 +199,33 @@ export function archiveSupersededRecord(stage, previous, { by, reason, at }) {
   return appendHistoryEntry(isPlainObject(stage) ? { ...stage } : {}, historyEntry(previous, { by, reason, at }));
 }
 
+/**
+ * #668: the Polish record a CampaignSpec change moved to `polish.history`,
+ * restored as the live record stamped with `stamps` (the current inputs), or
+ * null. It is the same review of the same pages, so it is restored only when
+ * the live record's input_change is a CampaignSpec change over exactly
+ * `fingerprint`, the newest history entry is the completed Polish that change
+ * archived (same build fingerprint and source package fingerprint), and the
+ * brief's presentation stamp is unchanged: a presentation change still owes a
+ * new review. The caller decides that the operator kept this output.
+ */
+export function restorePolishKeptWithOutput(polish, { fingerprint, sourcePackageFingerprint = null, stamps = {}, completedStatuses }) {
+  const change = isPlainObject(polish) ? polish.input_change : null;
+  if (!isPlainObject(change) || change.reason !== "spec_material_changed" || change.superseded_build_fingerprint !== fingerprint) return null;
+  const history = Array.isArray(polish.history) ? polish.history : [];
+  const superseded = history[history.length - 1];
+  if (!isPlainObject(superseded) || superseded.archived_at !== change.at || !completedStatuses.includes(superseded.status)) return null;
+  if (superseded.source_build_fingerprint !== fingerprint) return null;
+  if ((superseded.source_package_material_fingerprint ?? null) !== (sourcePackageFingerprint ?? null)) return null;
+  if ((superseded.source_brief_material?.presentation ?? null) !== (stamps.source_brief_material?.presentation ?? null)) return null;
+  const restored = { ...polish };
+  for (const field of ["required_by", "required_for", "input_change", "source_brief_material", "source_spec_material_hash"]) delete restored[field];
+  for (const field of ["status", "completed_at", "recorded_by", "performed_by", "source_build_fingerprint", "source_package_material_fingerprint", "outputs", "evidence"]) {
+    if (Object.hasOwn(superseded, field)) restored[field] = JSON.parse(JSON.stringify(superseded[field]));
+  }
+  return { ...restored, stage: "polish", ...stamps };
+}
+
 /**
  * True when any stage of `report` carries a non-empty history: recorded
  * operator-visible state an intake must not silently drop.