@nextcommerce/campaigns-os 1.57.0 → 1.60.0

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 };
@@ -343,7 +341,7 @@ Usage:
   campaigns-os record build --packet <campaign-runtime.build.json> [--build-environment <development|production>] [--adapter-decision <key>=<value>[,<key>=<value>...]] [--context <json>] [--report <json>] [--dry-run] [--json]   # after page-kit build: records scalar adapter decisions on the Assembly Report (all pairs in one flag; a repeated flag keeps only the last), stamps stages.assembly.build_fingerprint from doctor's derived.build_output_fingerprint.value (and the Design Source Package material fingerprint when present), and makes Polish required unless its evidence is bound to this output; --build-environment records stages.assembly.evidence.build_environment (local proof mode records development)
   campaigns-os record polish --packet <campaign-runtime.build.json> --evidence <polish-evidence.json> [--context <json>] [--report <json>] [--dry-run] [--json]   # after polish capture: stages.polish from the file's status (completed, completed_with_warnings, blocked with blockers, or skipped with skip_reason), evidence and optional repair_loop_defect, bound to doctor's current fingerprint; a completed status is refused, writing nothing, unless the polish gate doctor evaluates would pass. --dry-run runs every check and writes nothing
   campaigns-os record theme --packet <campaign-runtime.build.json> [--context <json>] [--report <json>] [--dry-run] [--json]   # after the brand layer is linked and build is recorded: report.theme becomes applied with load_order after-next-core, css_path, commerce_pages and per-page evidence, only when each built commerce page that loads next-core.css loads brand-theme.css (or checkout-brand.css) after it and at least one does; a page loading neither is left out as the design's own markup; refused, writing nothing, otherwise. --dry-run runs every check and writes nothing
-  campaigns-os record deploy --packet <campaign-runtime.build.json> --base-url <served url> [--context <json>] [--report <json>] [--dry-run] [--json]   # a local preview (deploy.target local-serve) after polish is recorded: GETs every built page under the loopback URL (the campaign route root), then records deploy.preview_url on the packet and stages.deploy completed with the URL in outputs and the build fingerprint it probed (a later record build of other output makes deploy required again); refused, writing nothing, when the URL is not loopback or not the route root, a page does not answer 2xx, the build changed since it was recorded, or the theme gate is blocked. --dry-run runs every check, the requests included, and writes nothing
+  campaigns-os record deploy --packet <campaign-runtime.build.json> --base-url <served url> [--context <json>] [--report <json>] [--dry-run] [--json]   # a served deploy after polish is recorded: GETs every built page under the URL (the campaign route root), then records deploy.preview_url on the packet and stages.deploy completed with the URL in outputs and the build fingerprint it probed (a later record build of other output makes deploy required again). A local-serve packet takes a loopback URL and each page must answer 2xx; any other deploy target takes an https URL (plain http only on a loopback host), each page must answer 200, and every script and stylesheet the built pages load from that origin must be served byte-identical (sha256) to the built output (HTML is not compared). Refused, writing nothing, when the URL breaks those rules or is not the route root, a page does not answer, a served asset differs or is missing, the build changed since it was recorded, or the theme gate is blocked. --dry-run runs every check, the requests included, and writes nothing
   campaigns-os readback <target-repo-root> [--json] [--packet <path>] [--doctor <path>] [--context <path>] [--report <path>] [--qa-verdict <path>] [--findings <path>]   # read-only projection of one run's emitted artifacts (packet, doctor output, build context, assembly report, QA verdict, findings export): artifact states, per-artifact freshness against the checkout's HEAD reflog, doctor warning grouping, skip cascades and cross-artifact divergences. Writes nothing, starts no process, touches no network, and records no lifecycle entry; --json emits one campaigns-os-readback/v2 object (docs/readback.md). Exit 2 for a missing target root or a Build Packet set freshness cannot single out.
   campaigns-os readback --example [--json]                                # project the bundled synthetic sample; freshness is not computable for it by design
   campaigns-os validate-assembly-report --report <json> [--json]
@@ -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: `${picked.outcome === "hosted_preview_satisfies_deploy" ? picked.reason : "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.${picked.outcome === "hosted_preview_satisfies_deploy" ? "" : " 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,
@@ -4877,8 +4854,8 @@ export function buildNextActions({ result, packetPath, packet, themeGate, polish
       return actions;
     }
     if (result.stage === "polish" && polishGate?.carried_forward?.policy === "hosted_template_preview") {
-      push("next_qa", "command", `${cmd("next")} qa --packet ${shellToken(packetPath)}`, "Inspect QA for the hosted preview; missing Polish evidence remains a warning.");
-      push("qa_run", "command", qaRunCommand(packetPath, packet.deploy.preview_url), "Run browser and typed-card QA against the hosted preview URL.");
+      push("record_deploy", "command", `${cmd("record")} deploy --packet ${shellToken(packetPath)} --base-url ${shellToken(packet.deploy.preview_url)}`, "Record the hosted preview deploy; missing Polish evidence remains a warning.");
+      push("qa_run", "command", qaRunCommand(packetPath, packet.deploy.preview_url), "Then run browser and typed-card QA against the hosted preview URL.");
       return actions;
     }
   }
@@ -4934,20 +4911,13 @@ export function buildNextActions({ result, packetPath, packet, themeGate, polish
       : `Run the visual polish pass and ${cmd("polish")} capture, then record polish with ${cmd("record")} polish --packet ${shellToken(packetPath)} --evidence <polish-evidence.json>.`);
     if (polishCheckpointGate?.status === "blocked") pushPolishCheckpointActions();
   } else if (result.stage === "deploy") {
-    if (polishGate?.carried_forward?.policy === "hosted_template_preview" && packet.deploy?.preview_url) {
-      push("next_qa", "command", `${cmd("next")} qa --packet ${shellToken(packetPath)}`, "Inspect the QA stage for this hosted preview without recording a hosted deploy.");
-      push("qa_run", "command", qaRunCommand(packetPath, packet.deploy.preview_url), "Run browser and typed-card QA against the hosted preview; its missing Polish evidence remains a warning.");
-    } else if (packet.deploy?.target === LOCAL_SERVE_DEPLOY_TARGET) {
+    if (packet.deploy?.target === LOCAL_SERVE_DEPLOY_TARGET) {
       const plan = localServePlan(packet);
       push("deploy", "manual", null, `Serve the built ${plan.dir} output locally as the origin root (deploy.target is local-serve)${plan.rewrite ? ` — ${plan.rewrite}` : ""}, then run ${cmd("record")} deploy --packet ${shellToken(packetPath)} --base-url <served url>: it checks every built page answers and records deploy.preview_url and stages.deploy. Localhost on any port is a Development domain: SDK allowed, analytics suppressed.`);
     } else {
-      push("deploy", "manual", null, `Deploy _site/ output to ${packet.deploy?.target || "the deploy target"}, then record deploy.preview_url (or production_url) on the packet and stages.deploy in the assembly report.`);
-    }
-    if (polishGate?.carried_forward?.policy === "hosted_template_preview" && packet.deploy?.preview_url) {
-      push("advance", "command", `${cmd("next")} qa --packet ${shellToken(packetPath)}`, "Inspect QA for the hosted preview without a deploy record.");
-    } else {
-      push("advance", "command", `${cmd("next")} --packet ${shellToken(packetPath)} --json`, "Advance to QA once the deploy URL is recorded.");
+      push("deploy", "manual", null, `Deploy _site/ output to ${packet.deploy?.target || "the deploy target"} with _site/ as the origin root, then run ${cmd("record")} deploy --packet ${shellToken(packetPath)} --base-url ${packet.deploy?.preview_url ? shellToken(packet.deploy.preview_url) : "<https preview url>"}: it checks every built page answers HTTP 200 and every script and stylesheet the pages load from that origin is served byte-identical to the build, and records deploy.preview_url and stages.deploy.`);
     }
+    push("advance", "command", `${cmd("next")} --packet ${shellToken(packetPath)} --json`, "Advance to QA once the deploy URL is recorded.");
   } else if (result.stage === "qa") {
     const url = packet.deploy?.preview_url || packet.deploy?.production_url || "<preview-url>";
     push("install_browser", "command", `${cmd("qa")} install-browser`, "Install the Playwright browser once after install/update (npm run qa:install-browser from a checkout).");
@@ -5108,11 +5078,11 @@ Rules:
 - For one-time prepurchase/order-bump packages outside the main bundles, default package_sync=false and show_line_total_price=false unless the spec explicitly requires quantity sync.
 - Record spec-driven removals, especially unsupported payment methods, so polish does not reintroduce them.
 - Replace demo refs; do not copy Olympus-style shipping_methods into shop-three-step.
-- Multi-step checkout paths run select -> checkout_step... -> checkout; only the checkout page takes payment. On a select page the swap-mode bundle selector (data-next-bundle-selector with data-next-selection-mode="swap") writes the cart and the SDK persists it between pages; a checkout button or link (href from the page's next_url) goes to the next page. Use forcePackageId only on a page with no selector, such as a landing call-to-action into a checkout that renders none.
-- Each checkout_step page's checkout form (<form data-next-checkout="form">) carries data-next-checkout-step="<its next_url>" and data-next-step-number="<step_number>" (Build Context page_kit frontmatter step_number); the checkout page's form carries neither. On every page that feeds a Checkout (select, checkout_step, or a landing page with express checkout buttons), next-success-url is that Checkout's post-payment destination (frontmatter success_url), not the next step, because the SDK reads it for express orders; forward navigation uses the step form attribute or a plain link, never that meta tag.
+- Multi-step checkout paths run select -> checkout_step... -> checkout; only the checkout page takes payment. On a select page the swap-mode bundle selector (data-next-bundle-selector with data-next-selection-mode="swap") writes the cart and the SDK persists it between pages; a checkout button or link (href from the page's next_step) goes to the next page. Use forcePackageId only on a page with no selector, such as a landing call-to-action into a checkout that renders none.
+- 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
@@ -5193,7 +5163,7 @@ function polishPrompt(packetPath, reportPath, packet, intent, polishCheckpointGa
       return `Every mapped page is template stock, so there is no design route to capture. Missing Polish evidence is carried forward only on a hosted preview whose deploy.preview_url is a non-loopback http(s) URL different from deploy.production_url; this packet's is not. Set one with \`${cmd("qa")} policy set --packet ${shellToken(packetPath)} --preview-url <url>\`, then \`${cmd("next")} --packet ${shellToken(packetPath)}\`.`;
     }
     return packet.deploy?.preview_url
-      ? `Every mapped page is template stock, so there is no design route to capture. Missing Polish evidence is carried forward on the hosted preview. Run \`${cmd("next")} qa --packet ${shellToken(packetPath)}\`, then \`${qaRunCommand(packetPath, packet.deploy.preview_url)}\`. Production QA remains blocked without the evidence.`
+      ? `Every mapped page is template stock, so there is no design route to capture. Missing Polish evidence is carried forward on the hosted preview. Run \`${cmd("record")} deploy --packet ${shellToken(packetPath)} --base-url ${shellToken(packet.deploy.preview_url)}\`, then \`${qaRunCommand(packetPath, packet.deploy.preview_url)}\`. Production QA remains blocked without the evidence.`
       : `Every mapped page is template stock, so there is no design route to capture. Run \`${cmd("qa")} policy set --packet ${shellToken(packetPath)} --preview-url <url>\` to record the hosted preview URL, then \`${cmd("next")} --packet ${shellToken(packetPath)}\`.`;
   }
   return `${campaignIntentPromptHeader(intent)}Use next-campaigns-polish for this built campaign.
@@ -5255,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)}\`. There is no hosted record deploy command.`;
+  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>/";
@@ -5282,7 +5250,7 @@ Once the server is up:
 If the served build cannot be reached, set stages.deploy.status to "blocked" with a clear reason in outputs so the orchestration loop surfaces it rather than skipping past.`;
   }
   if (polishGate?.carried_forward?.policy === "hosted_template_preview" && packet.deploy?.preview_url) {
-    return `The hosted preview URL is recorded at deploy.preview_url. Every mapped page is template stock, so missing Polish evidence is carried forward as a warning for this preview. Run \`${cmd("next")} qa --packet ${shellToken(packetPath)}\` to inspect the QA stage, then \`${qaRunCommand(packetPath, packet.deploy.preview_url)}\` to test the preview. The recorded hosted preview satisfies this deploy handoff; after QA records its verdict, run \`${cmd("next")} --packet ${shellToken(packetPath)}\` for closeout. Production QA remains strict.`;
+    return `The hosted preview URL is recorded at deploy.preview_url. Every mapped page is template stock, so missing Polish evidence is carried forward as a warning for this preview. Run \`${cmd("record")} deploy --packet ${shellToken(packetPath)} --base-url ${shellToken(packet.deploy.preview_url)}\` to record the deploy, then \`${qaRunCommand(packetPath, packet.deploy.preview_url)}\` to test the preview. Production QA remains strict.`;
   }
   return `Deploy the built campaign to ${target}.
 
@@ -5295,10 +5263,9 @@ Read first:
 Deploy is currently an out-of-band step: the page-kit build produces _site/ output; you (or your CI) ship it to ${target}. Use the deploy target's normal tooling (netlify deploy, wrangler pages deploy, vercel deploy, etc.).
 
 After deploy succeeds:
-1. Record the resulting URL on the packet at deploy.preview_url (preview deploys) or deploy.production_url (production).
-2. Update the assembly report's stages.deploy.status to "completed" with the URL and any relevant notes in outputs.
-3. Verify the SDK initialises on the tested origin. Localhost on any port is globally available as a Campaigns App Development domain (analytics suppressed). Non-localhost preview/production hosts must be in the Campaigns App SDK origin allowlist before QA.
-4. Run \`${cmd("next")} --packet ${packetPath}\` to advance to QA.
+1. Run \`${cmd("record")} deploy --packet ${packetPath} --base-url <https preview origin>${liveUrlPath}\`. It requests every built page under that URL (each must answer HTTP 200) and compares every script and stylesheet the built pages load from that origin with the built output by sha256 (HTML is not compared; hosts inject markup), then records the URL at deploy.preview_url and stages.deploy as completed with the URL in outputs and the build fingerprint it probed. It refuses, writing nothing, naming each page or asset that does not match.
+2. Verify the SDK initialises on the tested origin. Localhost on any port is globally available as a Campaigns App Development domain (analytics suppressed). Non-localhost preview/production hosts must be in the Campaigns App SDK origin allowlist before QA.
+3. Run \`${cmd("next")} --packet ${packetPath}\` to advance to QA.
 
 If the deploy is blocked (non-localhost allowed-domain not yet added, CI permission missing, host-side outage), set stages.deploy.status to "blocked" with a clear reason in outputs so the orchestration loop surfaces it rather than skipping past.`;
 }
@@ -5352,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)";
@@ -7125,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;
@@ -7134,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 });
       }
     }
@@ -7143,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

@@ -76,7 +76,7 @@ import {
   resolveTemplateBrandContract,
 } from "../private-template-source.mjs";
 import { assessTemplateFreshness, defaultSdkSupportPolicy, renderTemplateFreshness } from "../template-freshness.mjs";
-import { computeBuildFingerprint, resolveBuiltSiteScope } from "../built-site-scope.mjs";
+import { BUILD_DRIFT_PATH_LIMIT, computeBuildFingerprint, describeBuildOutputDrift, resolveBuiltSiteScope } from "../built-site-scope.mjs";
 import {
   UPSELL_SELECTOR_SCOPE,
   builtPageTypeOverRouteGuess,
@@ -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
@@ -1895,12 +1895,33 @@ export function validateBuildOutputFingerprint(packet, errors, warnings, ready,
     );
     return;
   }
+  const drift = describeBuildOutputDrift(buildState.report?.stages?.assembly, current);
+  const capped = (paths) => paths.slice(0, BUILD_DRIFT_PATH_LIMIT);
   addIssue(
     assemblyComplete ? errors : warnings,
     "built_output.fingerprint_stale",
     `Built output under _site/${publicRouteSlug}/ no longer matches stages.assembly.build_fingerprint (recorded ${recorded}, current ${current.fingerprint}, ${current.file_count} file(s)). `
+      + `${drift.summary} `
       + "The output changed after build recorded it; re-run build (page-kit build, then record the current fingerprint) before polish or QA evidence can bind to it.",
-    { root: `_site/${publicRouteSlug}/`, recorded, current: current.fingerprint, file_count: current.file_count, assembly_complete: assemblyComplete }
+    {
+      root: `_site/${publicRouteSlug}/`,
+      recorded,
+      current: current.fingerprint,
+      file_count: current.file_count,
+      assembly_complete: assemblyComplete,
+      drift: drift.manifest === "recorded"
+        ? {
+          manifest: "recorded",
+          extra_count: drift.extra.length,
+          missing_count: drift.missing.length,
+          changed_count: drift.changed.length,
+          extra: capped(drift.extra),
+          missing: capped(drift.missing),
+          changed: capped(drift.changed),
+          conflict_copies: capped(drift.conflict_copies),
+        }
+        : { manifest: "unavailable" },
+    }
   );
 }
 
@@ -3018,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, "");
@@ -3082,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");
@@ -3342,7 +3366,7 @@ function collectHardcodedPhoneMatches(scanRoots, storePhone) {
   const matches = [];
   for (const { label: surface, root } of scanRoots) {
     for (const file of collectHtmlFiles(root)) {
-      const content = maskMarketLintIgnoredRegions(readHtmlScanText(join(root, file.path)));
+      const content = maskNonRenderedMarkup(maskMarketLintIgnoredRegions(readHtmlScanText(join(root, file.path))));
       for (const match of content.matchAll(HARDCODED_PHONE_REGEX)) {
         const found = normalizePhoneNumber(match[0]);
         if (!found || found === expected) continue;
@@ -3370,6 +3394,18 @@ function maskMarketLintIgnoredRegions(content) {
     .replace(ignoredTag, preserveNewlinesMask);
 }
 
+// Markup a shopper never reads: HTML comments, <style> blocks, and CSS
+// comments (in style attributes too). Design exports leave long digit runs
+// there, such as a Figma frame name "Group 1000003339", which the phone
+// pattern would otherwise read as a number (campaigns-os#660). Masking keeps
+// offsets and newlines, so reported line numbers stay true.
+function maskNonRenderedMarkup(content) {
+  return content
+    .replace(/<!--[\s\S]*?-->/g, preserveNewlinesMask)
+    .replace(/<style\b[^>]*>[\s\S]*?<\/style\s*>/gi, preserveNewlinesMask)
+    .replace(/\/\*[\s\S]*?\*\//g, preserveNewlinesMask);
+}
+
 function preserveNewlinesMask(value) {
   return value.replace(/[^\n]/g, " ");
 }
@@ -4138,6 +4174,42 @@ function warnCheckoutPackageFamilyFit(specPages, family, catalog, warnings, repo
     );
   }
 }
+// A family that puts package selection on its own `select` page (the catalog
+// names a selectStep surface) and carries no selector on checkout (no
+// mainSelector surface) can only fill the cart from a declared select page.
+// Without one on the path into a Checkout, QA resolves the landing as the
+// entry page, finds no add-to-cart control, and every order path fails after
+// the whole build (campaigns-os#658). Families whose checkout carries its own
+// selector, and families that fill the cart on the landing page, are not
+// affected.
+function warnMissingSelectStep(specPages, family, catalog, warnings) {
+  const surfaces = catalog.families?.[family]?.canonicalSurfaces;
+  if (!surfaces?.selectStep || surfaces.mainSelector) return;
+  const byFunnel = new Map();
+  for (const page of specPages) {
+    if (!byFunnel.has(page.funnel_id)) byFunnel.set(page.funnel_id, []);
+    byFunnel.get(page.funnel_id).push(page);
+  }
+  for (const [funnelId, pages] of byFunnel) {
+    const reachedFromSelect = new Set();
+    for (const select of pages.filter((page) => page.type === "select")) {
+      const path = checkoutPathFrom(pages, select);
+      if (path) reachedFromSelect.add(path[path.length - 1]);
+    }
+    for (const checkout of pages.filter((page) => page.type === "checkout")) {
+      if (reachedFromSelect.has(checkout)) continue;
+      // A split-test path built on another family is judged by that family.
+      const pageFamily = checkout.sdk_hints?.template_family;
+      if (isNonEmptyString(pageFamily) && pageFamily !== family) continue;
+      addIssue(
+        warnings,
+        "template_contract.select_step_missing",
+        `Template family "${family}" puts package selection on a select page, and its checkout carries no selector, but no select page leads to Checkout "${checkout.id}" in funnel "${funnelId}". QA will find no add-to-cart control on the entry page and every order path will fail. Fix: add a Select page between the entry page and checkout in Map Builder.`,
+        { funnel_id: funnelId, checkout_page_id: checkout.id, template_family: family },
+      );
+    }
+  }
+}
 function offerRefsFromEntries(entries) {
   if (!Array.isArray(entries)) return [];
   return entries
@@ -4323,6 +4395,7 @@ export function validateCommerceCatalog(packet, packetPath, spec, errors, warnin
     // ADR-003 step 2: template-contract checks ported from the private doctor.
     const specPages = activeSpecPages(spec);
     warnCheckoutPackageFamilyFit(specPages, family, catalog, warnings, buildState.report);
+    warnMissingSelectStep(specPages, family, catalog, warnings);
 
     const mismatchedFamilies = specPages.filter(
       (page) => isNonEmptyString(page.sdk_hints?.template_family) && page.sdk_hints.template_family !== family

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
@@ -477,12 +477,6 @@ function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate
     // A first local preview may carry missing Polish forward. A theme waiver
     // or prior capture makes the recorded Polish stage owed again.
     if (cliStage === "polish" && polishCarriedForwardForLadder(report, polishGate)) continue;
-    // A hosted all-template preview has no hosted deploy recorder. The
-    // recorded preview URL satisfies this one deploy handoff while the
-    // carried-forward gate identifies the exact preview-only shape.
-    if (cliStage === "deploy" && packet?.deploy?.preview_url
-      && polishGate?.carried_forward?.policy === "hosted_template_preview"
-      && polishCheckpointGate?.carried_forward?.policy === "hosted_template_preview") continue;
     const reportKey = reportKeyForCliStage(cliStage);
     const stage = report.stages[reportKey];
     if (!stage) {
@@ -524,13 +518,10 @@ function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate
     }
   }
 
-  const hostedPreview = Boolean(packet?.deploy?.preview_url && polishGate?.carried_forward?.policy === "hosted_template_preview");
   return {
     stage: "done",
-    outcome: hostedPreview ? "hosted_preview_satisfies_deploy" : "standard_closeout",
-    reason: hostedPreview
-      ? "The recorded hosted preview satisfies deploy, and QA is terminal for the current build. Pipeline is complete."
-      : "All stages are in a terminal status (completed / completed_with_warnings / skipped). Pipeline is complete.",
+    outcome: "standard_closeout",
+    reason: "All stages are in a terminal status (completed / completed_with_warnings / skipped). Pipeline is complete.",
   };
 }
 
@@ -551,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";
@@ -673,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.
@@ -730,9 +724,7 @@ function buildNextStep(errors, warnings, derived, report = null, packet = null,
       ? `${cmd("next")} --packet ${packetRef}`
       : `${cmd("next")} ${picked.stage} --packet ${packetRef}`;
   const fallbackAction = picked.stage === "done"
-    ? (picked.outcome === "hosted_preview_satisfies_deploy"
-      ? `${picked.reason} Run ${cmd("next")} to confirm the closeout actions.`
-      : `All stages are recorded as terminal; run ${cmd("next")} to confirm the closeout actions.`)
+    ? `All stages are recorded as terminal; run ${cmd("next")} to confirm the closeout actions.`
     : `Run ${command}.`;
   if (picked.stage === "done") {
     actions.unshift(fallbackAction);
@@ -769,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"]);