@nextcommerce/campaigns-os 1.55.0 → 1.59.0

package/src/cli.mjs

@@ -21,9 +21,10 @@ import { homedir } from "node:os";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { shellToken } from "./shell-token.mjs";
 import { declaredOrderBumps, declaredSelectorTiers } from "./commercial-journey.mjs";
+import { checkoutPathFrom, entryPages, isCheckoutFlowPage, paymentPageForFunnel, upgradeCampaignSpec } from "../campaign-spec/dist/index.js";
 import { diagnosticExport, diagnosticTextLines } from "./diagnostic.mjs";
 import { observeProgress, PROGRESS_OBSERVATION } from "./progress-node.mjs";
-import { HIDDEN_EAGER_MEDIA_ACTIONS, requiredActionText, substitutePacket } from "./gate-actions.mjs";
+import { HIDDEN_EAGER_MEDIA_ACTIONS, qaRunCommand, requiredActionText, substitutePacket } from "./gate-actions.mjs";
 import { orderPathDepthDriftText, orderPathDepthReconcileAction, orderPathDepthsDisagree, parseOrderPathDepthFlag } from "./proof-policy.mjs";
 import { specMaterialHash, specHashesMatch } from "./spec-identity.mjs";
 // The same predicate stage-ledger.mjs judges a mutator's result with, imported
@@ -252,6 +253,7 @@ import {
   readStoreProfile,
 } from "./spec-derive-store.mjs";
 import { ROOT, cmd, asInvocation } from "./install-invocation.mjs";
+import { hostedTemplateNeedsPreviewUrl, hostedTemplateNeedsUsablePreview } from "./local-preview-policy.mjs";
 import {
   requireArg,
   isObject,
@@ -263,6 +265,7 @@ import {
   sha256File,
   relFromDir,
   isLocalAbsolutePath,
+  portableArtifactPaths,
   resolveFromFile,
   extractFrontmatterValue,
   addIssue,
@@ -302,6 +305,7 @@ const HELP = `Campaigns OS toolkit
 
 Usage:
   campaigns-os help
+  campaigns-os --version   # print the installed package version; -v is equivalent
   campaigns-os demo --target <new-directory>   # offline inert sample; open landing/index.html; no campaign evidence
   campaigns-os start (--spec <json> | --map-id <id>) --source <html-dir> --target <page-kit-dir> --template-family <family>
                      [--brief <yaml|json>] [--proxy-base <url>] [--cached-spec] [--theme-policy <inspect_only|auto|off>]
@@ -339,7 +343,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]
@@ -476,6 +480,12 @@ function closestCommand(input) {
 // (src/qc-test-factories.mjs). The bin entry point never passes it, and no
 // flag, environment variable or file can supply one.
 export async function main(argv, { authentication, qcStandIns } = {}) {
+  // Global version flags bypass invocation policy, including session reads and
+  // lifecycle capture, just as help bypasses campaign effects.
+  if (argv[0] === "--version" || argv[0] === "-v") {
+    console.log(packageVersion());
+    return;
+  }
   return runInvocation(parseArgs(argv), {
     dispatch: (command, args, context) => dispatch(command, args, { ...context, argv, authentication, qcStandIns }),
     closeOutStaleRunSessions,
@@ -729,7 +739,7 @@ export function recordQaStageOutcome(args, result) {
         disposition: verdict.disposition,
         timestamp: verdict.completed_at,
         command: `campaigns-os ${QA_RUN_PRODUCER}`,
-        outputs: [result.local_path, result.qa_sidecar?.path].filter(isNonEmptyString),
+        outputs: portableArtifactPaths([result.local_path, result.qa_sidecar?.path].filter(isNonEmptyString), workspace.targetRepo),
         blockers: verdict.disposition === "blocked" ? failed : [],
         warnings: verdict.disposition === "ready_with_exceptions"
           ? ["QA passed with explicitly attributed exceptions. Report them to the operator; do not clear or waive them, or change markup just to make them pass."]
@@ -4217,11 +4227,11 @@ const RUN_RECORD_QA_DIGEST_LIMIT = 8;
 // Digests of the verdicts the report records, best-effort: an unreadable
 // hint contributes no digest, which fails open to "outdated" rather than to
 // a false match.
-function currentQaVerdictDigestsForReport(report, reportPath) {
+function currentQaVerdictDigestsForReport(report, reportPath, targetRepo) {
   const digests = new Set();
   // Lazy on purpose, and the check follows the add: once the limit is
   // reached the next candidate is never pulled, read or hashed.
-  for (const candidate of iterateQaVerdicts({ report, reportPath, withDigest: true })) {
+  for (const candidate of iterateQaVerdicts({ report, reportPath, roots: [targetRepo], withDigest: true })) {
     if (candidate.source === "assembly_report" && candidate.sha256) digests.add(candidate.sha256);
     if (digests.size >= RUN_RECORD_QA_DIGEST_LIMIT) break;
   }
@@ -4302,7 +4312,7 @@ export function nextStage(stage, args, ambient = null, { qcStandIns = null, qcRe
       // Atomic like the assembly report: a torn sidecar would be a corrupted
       // freshness artifact — the exact green-lie shape this refresh exists to
       // prevent (Kilo review, PR #176). Stamped generated_by: "next" (#312).
-      writeDoctorSidecar(doctorOutPath, doctor, { command: NEXT_PRODUCER });
+      writeDoctorSidecar(doctorOutPath, doctor, { command: NEXT_PRODUCER, targetRepo });
     } catch {
       // sidecar refresh is best-effort; orchestration must not fail on it
     }
@@ -4318,7 +4328,10 @@ export function nextStage(stage, args, ambient = null, { qcStandIns = null, qcRe
   // participate in divergence detection or override prepare-only recovery.
   const divergences = prepareBuildGate?.binding_failure
     ? []
-    : detectLedgerDivergence(report, packet, targetRepo);
+    : detectLedgerDivergence(report, packet, targetRepo, {
+      allowUnrecordedHostedPreview: polishCheckpointGate?.carried_forward?.policy === "hosted_template_preview"
+        || hostedTemplateNeedsPreviewUrl(packet, polishCheckpointGate),
+    });
   // Every return path runs through this finalizer so the machine-readable
   // contract is uniform: `gates` (pass/blocked/waived/not_applicable per
   // gate) and `next_actions` (exact commands — not prose) are always present,
@@ -4342,7 +4355,7 @@ export function nextStage(stage, args, ambient = null, { qcStandIns = null, qcRe
       records: readRunRecordsForTarget(dirname(packetPath)),
       packet,
       report,
-      currentQaVerdictDigests: currentQaVerdictDigestsForReport(report, report ? reportPath : null),
+      currentQaVerdictDigests: currentQaVerdictDigestsForReport(report, report ? reportPath : null, targetRepo),
       qaVerdictRecorded: qaVerdictPathHints(report).length > 0,
     });
   } catch {
@@ -4475,7 +4488,7 @@ export function nextStage(stage, args, ambient = null, { qcStandIns = null, qcRe
     if (!assemblyStatus.startsWith("completed")) addIssue(errors, "next.polish.assembly", `Assembly status is "${assemblyStatus || "missing"}"; polish expects completed assembly or an explicit blocked/skipped handoff.`);
     if (polishGateRequiresBuild(polishGate)) addPolishGateErrors(errors, polishGate, "polish");
     addThemeGateErrors(errors, themeGate, "polish");
-    prompt = polishPrompt(packetPath, reportPath, packet, intentSummary);
+    prompt = polishPrompt(packetPath, reportPath, packet, intentSummary, polishCheckpointGate);
   } else if (stage === "deploy") {
     addPrepareBuildGateErrors(errors, report);
     // Slice 3 Phase 2: deploy is an out-of-band step (Netlify / CF Pages /
@@ -4485,7 +4498,7 @@ export function nextStage(stage, args, ambient = null, { qcStandIns = null, qcRe
     addPolishGateErrors(errors, polishGate, "deploy");
     addPolishCheckpointGateErrors(errors, polishCheckpointGate, "deploy");
     addThemeGateErrors(errors, themeGate, "deploy");
-    prompt = deployPrompt(packetPath, reportPath, packet);
+    prompt = deployPrompt(packetPath, reportPath, packet, polishGate, polishCheckpointGate);
   } else if (stage === "qa") {
     addPrepareBuildGateErrors(errors, report);
     if (!report) addIssue(errors, "next.qa.report", "Assembly report is required before QA.");
@@ -4494,7 +4507,7 @@ export function nextStage(stage, args, ambient = null, { qcStandIns = null, qcRe
     addPolishGateErrors(errors, polishGate, "qa");
     addPolishCheckpointGateErrors(errors, polishCheckpointGate, "qa");
     addThemeGateErrors(errors, themeGate, "qa");
-    prompt = qaPrompt(packetPath, reportPath, packet, spec, intentSummary);
+    prompt = qaPrompt(packetPath, reportPath, packet, spec, intentSummary, polishCheckpointGate);
   }
   const status = errors.length
     ? "blocked"
@@ -4743,18 +4756,18 @@ function quoteDivergences(divergences) {
     .join(" ");
 }
 
-function divergenceInspectAction(divergences, packetPath) {
+function divergenceInspectAction(divergences, packetPath, { packet = null, polishCheckpointGate = null } = {}) {
   const divergedStages = divergences.map((divergence) => divergence.stage);
   const forwardHint = divergedStages.includes("qa")
     ? "The artifacts include a QA verdict for this campaign, so the campaign may already be built, deployed, and QA'd — verify the artifacts before redoing any stage."
     : divergedStages.includes("deploy")
-      ? `If the recorded deploy URL is real and current, the forward path is QA (${cmd("next")} qa --packet ${packetPath}), not re-running earlier stages.`
+      ? `If the recorded deploy URL is real and current, the forward path is QA (${cmd("next")} qa --packet ${shellToken(packetPath)}), not re-running earlier stages.`
       : "If the built output is real and current, the forward path is polish/deploy/QA, not re-running setup or build.";
   return {
     id: "divergence_inspect",
     kind: "manual",
     command: null,
-    description: `Ledger and artifacts disagree — ${divergences.length} divergence(s): ${quoteDivergences(divergences)} The same entries are the divergences[] field of \`${cmd("next")} --json\` output; they are not written to any file. This is the ONLY next action: stage actions are suppressed while the disagreement stands, because every one of them would be derived from the same contradictory evidence. Inspect both sides and decide which is right; update the assembly report only after inspection. Do not rerun start/prepare-build or redo completed-looking work on the strength of the ledger alone, and do not treat artifact presence as proof a stage is complete. ${forwardHint} Re-run \`${cmd("next")} --packet ${packetPath} --json\` once the report matches the artifacts to get the normal action list.`,
+    description: `Ledger and artifacts disagree — ${divergences.length} divergence(s): ${quoteDivergences(divergences)} The same entries are the divergences[] field of \`${cmd("next")} --json\` output; they are not written to any file. This is the ONLY next action: stage actions are suppressed while the disagreement stands, because every one of them would be derived from the same contradictory evidence. Inspect both sides and decide which is right; update the assembly report only after inspection. Do not rerun start/prepare-build or redo completed-looking work on the strength of the ledger alone, and do not treat artifact presence as proof a stage is complete. ${forwardHint}${hostedTemplateNeedsUsablePreview(packet, polishCheckpointGate) ? ` After reconciliation, set a hosted preview URL that differs from the production URL with \`${cmd("qa")} policy set --packet ${shellToken(packetPath)} --preview-url <url>\`.` : ""} Re-run \`${cmd("next")} --packet ${shellToken(packetPath)} --json\` once the report matches the artifacts to get the normal action list.`,
     required: true,
   };
 }
@@ -4785,7 +4798,7 @@ export function buildNextActions({ result, packetPath, packet, themeGate, polish
     // of the stale ledger. Suppressing branch-by-branch would leave the next
     // branch someone adds unguarded; returning here cannot rot that way.
     // The operator reconciles, then re-runs `next` for the normal list.
-    const inspect = divergenceInspectAction(divergences, packetPath);
+    const inspect = divergenceInspectAction(divergences, packetPath, { packet, polishCheckpointGate });
     push(inspect.id, inspect.kind, asInvocation(inspect.command), inspect.description, { required: inspect.required });
     return actions;
   }
@@ -4811,7 +4824,7 @@ export function buildNextActions({ result, packetPath, packet, themeGate, polish
         );
       }
     }
-    push("doctor_recheck", "command", `${cmd("doctor")} --packet ${packetPath} --write --json`, "Record a fresh doctor result after resolving the listed errors.");
+    push("doctor_recheck", "command", `${cmd("doctor")} --packet ${shellToken(packetPath)} --write --json`, "Record a fresh doctor result after resolving the listed errors.");
     return actions;
   }
   if (result.stage === "prepare-build") {
@@ -4845,16 +4858,30 @@ export function buildNextActions({ result, packetPath, packet, themeGate, polish
     for (const action of themeGate.required_actions) {
       push(`theme_gate.${action.id}`, action.kind, asInvocation(action.command), action.description);
     }
-    push("recheck", "command", `${cmd("next")} --packet ${packetPath} --json`, "Re-run next after resolving the theme gate to advance.");
+    push("recheck", "command", `${cmd("next")} --packet ${shellToken(packetPath)} --json`, "Re-run next after resolving the theme gate to advance.");
     return actions;
   }
   if (polishGateRequiresBuild(polishGate) && ["build", "polish", "deploy", "qa"].includes(result.stage)) {
     for (const action of polishGate?.required_actions || []) {
       push(`polish_gate.${action.id}`, action.kind, asInvocation(action.command), action.description);
     }
-    push("recheck", "command", `${cmd("next")} --packet ${packetPath} --json`, "Re-run next after rebuilding against the current Design Source Package.");
+    push("recheck", "command", `${cmd("next")} --packet ${shellToken(packetPath)} --json`, "Re-run next after rebuilding against the current Design Source Package.");
     return actions;
   }
+  const hostedTemplate = packet?.deploy?.target && packet.deploy.target !== LOCAL_SERVE_DEPLOY_TARGET
+    && polishCheckpointGate?.code === "polish.hidden_eager_media.no_capturable_routes";
+  if (hostedTemplate && ["polish", "deploy", "qa"].includes(result.stage)) {
+    if (hostedTemplateNeedsUsablePreview(packet, polishCheckpointGate)) {
+      pushPolishCheckpointActions();
+      push("recheck", "command", `${cmd("next")} --packet ${shellToken(packetPath)} --json`, "Re-run next after recording a hosted preview URL that differs from the production URL.");
+      return actions;
+    }
+    if (result.stage === "polish" && polishGate?.carried_forward?.policy === "hosted_template_preview") {
+      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;
+    }
+  }
   if ((polishGate?.status === "blocked" || polishCheckpointGate?.status === "blocked")
     && ["deploy", "qa"].includes(result.stage)) {
     const checkpointActionIds = new Set(
@@ -4867,7 +4894,7 @@ export function buildNextActions({ result, packetPath, packet, themeGate, polish
       push(`polish_gate.${action.id}`, action.kind, asInvocation(action.command), action.description);
     }
     pushPolishCheckpointActions();
-    push("recheck", "command", `${cmd("next")} --packet ${packetPath} --json`, "Re-run next after recording valid Polish evidence.");
+    push("recheck", "command", `${cmd("next")} --packet ${shellToken(packetPath)} --json`, "Re-run next after recording valid Polish evidence.");
     return actions;
   }
   // Ahead of every stage that still has QA in front of it, say what QA will do
@@ -4888,9 +4915,9 @@ export function buildNextActions({ result, packetPath, packet, themeGate, polish
     }
   }
   if (result.stage === "setup") {
-    push("setup_skill", "skill", "next-campaigns-os-setup", `Prepare the target page-kit structure and agent context, then record setup with ${cmd("record")} setup --packet ${packetPath}.`);
+    push("setup_skill", "skill", "next-campaigns-os-setup", `Prepare the target page-kit structure and agent context, then record setup with ${cmd("record")} setup --packet ${shellToken(packetPath)}.`);
   } else if (result.stage === "build") {
-    const recordBuild = `${cmd("record")} build --packet ${packetPath}${isLocalServePacket(packet) ? ` --build-environment ${LOCAL_PROOF_BUILD_ENVIRONMENT}` : ""}`;
+    const recordBuild = `${cmd("record")} build --packet ${shellToken(packetPath)}${isLocalServePacket(packet) ? ` --build-environment ${LOCAL_PROOF_BUILD_ENVIRONMENT}` : ""}`;
     push("build_skill", "skill", "next-campaigns-build", `Assemble the campaign per the build prompt, run the page-kit build, then record build with ${recordBuild}.`);
     if (isLocalServePacket(packet)) {
       push("build_local_proof", "command", LOCAL_PROOF_BUILD_COMMAND, `Local proof mode (deploy.target is local-serve): build page-kit in the ${LOCAL_PROOF_BUILD_ENVIRONMENT} environment into _site/, then record it with ${recordBuild}, which sets ${LOCAL_PROOF_BUILD_ENVIRONMENT_FIELD} to "${LOCAL_PROOF_BUILD_ENVIRONMENT}" (never hand-edit it). Vendor loaders are environment-gated out of this render (their protocol-relative //host/... URLs fail over a plain-HTTP local serve); SDK dl_* events still fire. ${LOCAL_PROOF_NEVER_EDIT_RULE}`);
@@ -4902,16 +4929,18 @@ export function buildNextActions({ result, packetPath, packet, themeGate, polish
       }
     }
   } else if (result.stage === "polish") {
-    push("polish_skill", "skill", "next-campaigns-polish", `Run the visual polish pass and ${cmd("polish")} capture, then record polish with ${cmd("record")} polish --packet ${packetPath} --evidence <polish-evidence.json>.`);
+    push("polish_skill", "skill", "next-campaigns-polish", polishCheckpointGate?.code === "polish.hidden_eager_media.no_capturable_routes"
+      ? "Every mapped page is template stock, so there is no design route to capture. Follow the preview guidance for missing Polish evidence."
+      : `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 (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 ${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.`);
+      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.`);
+      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 ${packetPath} --json`, "Advance to QA once the deploy URL is recorded.");
+    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).");
@@ -5072,7 +5101,8 @@ 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.
-- For two-step package-selection flows, treat the selector page as the pre-checkout step and pass the selected cart to checkout with forcePackageId; preserve normal tracking params and strip forcePackageId from visible checkout URLs after SDK initialization.
+- 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)}`;
@@ -5143,8 +5173,22 @@ When copying a starter template family, copy the family as an atomic page-kit sl
 Do not wire checkout, upsell, receipt, payment, package, voucher, or shipping behavior during setup.`;
 }
 
-function polishPrompt(packetPath, reportPath, packet, intent) {
+function polishPrompt(packetPath, reportPath, packet, intent, polishCheckpointGate = null) {
   const briefPath = packet.build_brief?.normalized_path || "(missing)";
+  if (polishCheckpointGate?.code === "polish.hidden_eager_media.no_capturable_routes") {
+    if (packet.deploy?.target === LOCAL_SERVE_DEPLOY_TARGET && polishCheckpointGate?.status !== "carried_forward") {
+      return `Every mapped page is template stock, so there is no design route to capture. Missing Polish evidence is carried forward only on the local preview served from a loopback host (localhost, 127.0.0.1 or [::1]); this packet's deploy.preview_url is not one. Serve the build locally and record it with \`${cmd("record")} deploy --packet ${shellToken(packetPath)} --base-url <served url>\`, then run \`${cmd("next")} --packet ${shellToken(packetPath)}\`.`;
+    }
+    if (packet.deploy?.target === LOCAL_SERVE_DEPLOY_TARGET) {
+      return `Every mapped page is template stock, so there is no design route to capture. On the local loopback preview, missing Polish evidence is carried forward as a warning. Run \`${cmd("next")} --packet ${shellToken(packetPath)}\` to continue to deploy and QA. Production QA still requires the evidence.`;
+    }
+    if (polishCheckpointGate?.status !== "carried_forward" && packet.deploy?.preview_url) {
+      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("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.
 
 Read first:
@@ -5203,7 +5247,12 @@ function localServePlan(packet) {
   };
 }
 
-function deployPrompt(packetPath, reportPath, 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)}\`.`;
+  }
   const target = packet.deploy?.target || "unknown";
   const liveUrlPath = packet.deploy?.live_url_path || packet.campaign?.live_url_path || campaignRouteRoot(packet) || "/<slug>/";
   if (target === LOCAL_SERVE_DEPLOY_TARGET) {
@@ -5225,6 +5274,9 @@ 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("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}.
 
 Read first:
@@ -5236,10 +5288,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.`;
 }
@@ -5247,36 +5298,40 @@ If the deploy is blocked (non-localhost allowed-domain not yet added, CI permiss
 // The QA command the QA stage hands over. Given a bump cart it is the
 // order-bump run: the same command with --cart selecting the base tier and
 // toggling each declared bump.
-function qaRunCommand(packetPath, url, bumpCart = null) {
-  return `${cmd("qa")} run --packet ${packetPath} --base-url ${url} --browser --test-order common${bumpCart ? ` --cart ${shellToken(bumpCart.cart)}` : ""}`;
-}
-
 // `qa run --test-order common` never puts a checkout order bump in a test
 // order: the tier planner skips bump rows by design and bump coverage comes
 // from --cart. So when the spec declares one, `next` names a second run with
-// the bump in the cart. It reads the one checkout QA drives, with QA's own row
-// classifiers: QA's test orders run on findPage(topologies, "checkout"), the
-// first checkout across funnels in array order, each funnel's pages filtered
-// to enabled and sorted by `order || 0` (extractTopologies). This picks the
-// same page, and when that checkout declares no bump it returns null rather
-// than looking at a later funnel: QA never drives a later funnel's checkout,
-// so that funnel's bump ref in --cart would land on a checkout without it. The base is the first selector tier QA would plan: QA's default
-// keeps the page's pre-selected card, which a spec does not name. A checkout
-// that declares no tier (the cart is filled on an entry page) gets the bump
-// alone, on whatever selection the entry page made.
+// the bump in the cart. It reads the one checkout path QA drives, with QA's own
+// row classifiers: QA's test orders run on the Checkout (the page that takes
+// payment) of the first entry path of the first funnel that has one, each
+// funnel's pages filtered to enabled and sorted by `order || 0`
+// (extractTopologies, findPaymentPage). The rows are read from every
+// checkout-flow page on that path — the select page or first step of a
+// multi-step checkout declares the cart, not the Checkout (campaigns-os#641).
+// When that path declares no bump it returns null rather than looking at a
+// later funnel: QA never drives a later funnel's checkout, so that funnel's
+// bump ref in --cart would land on a checkout without it. The base is the
+// first selector tier QA would plan: QA's default keeps the page's
+// pre-selected card, which a spec does not name. A path that declares no tier
+// (the cart is filled on an entry page) gets the bump alone, on whatever
+// selection the entry page made.
 export function checkoutOrderBumpCart(spec) {
-  const funnels = Array.isArray(spec?.funnels)
-    ? spec.funnels
-    : Array.isArray(spec?.funnel_pages) ? [{ pages: spec.funnel_pages }] : [];
+  const upgraded = upgradeCampaignSpec(spec);
+  const funnels = Array.isArray(upgraded?.funnels)
+    ? upgraded.funnels
+    : Array.isArray(upgraded?.funnel_pages) ? [{ pages: upgraded.funnel_pages }] : [];
   for (const funnel of funnels) {
-    const checkout = (Array.isArray(funnel?.pages) ? funnel.pages : [])
+    const pages = (Array.isArray(funnel?.pages) ? funnel.pages : [])
       .filter((page) => page && page.enabled !== false)
-      .sort((a, b) => (a.order || 0) - (b.order || 0))
-      .find((page) => page.type === "checkout");
+      .sort((a, b) => (a.order || 0) - (b.order || 0));
+    const sorted = { ...funnel, pages };
+    const checkout = paymentPageForFunnel(sorted);
     if (!checkout) continue;
-    const bumps = declaredOrderBumps(checkout);
+    const entryPath = entryPages(sorted).map((entry) => checkoutPathFrom(pages, entry)).find((path) => path?.includes(checkout));
+    const pathPages = (entryPath || [checkout]).filter((page) => isCheckoutFlowPage(page));
+    const bumps = [...new Set(pathPages.flatMap((page) => declaredOrderBumps(page)))];
     if (!bumps.length) return null;
-    const base = declaredSelectorTiers(checkout)[0]?.ref || null;
+    const base = pathPages.map((page) => declaredSelectorTiers(page)[0]?.ref).find(Boolean) || null;
     return { base, bumps, cart: [base, ...bumps].filter(Boolean).map((ref) => `${ref}:1`).join(",") };
   }
   return null;
@@ -5288,7 +5343,12 @@ function orderBumpRunReason(bumpCart) {
   return `The checkout declares order bump ${bumpCart.bumps.join(", ")} (is_order_bump or is_upsell), and the default run never puts it in a test order. This run repeats QA with ${cart} in the cart.`;
 }
 
-function qaPrompt(packetPath, reportPath, packet, spec = null, intent) {
+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)}\`.`;
+  }
   const url = packet.deploy?.preview_url || packet.deploy?.production_url || "<preview-url>";
   const briefPath = packet.build_brief?.normalized_path || "(missing)";
   const bumpCart = checkoutOrderBumpCart(spec);
@@ -5356,7 +5416,7 @@ function qaVerdictArtifactsForCampaign(packet, targetRepo) {
 // Presence-based only: a stale built output still diverges from a pending
 // ledger, and the entry says the two disagree — it never asserts the stage
 // is complete or the artifact current. This function writes nothing.
-export function detectLedgerDivergence(report, packet, targetRepo) {
+export function detectLedgerDivergence(report, packet, targetRepo, { allowUnrecordedHostedPreview = false } = {}) {
   const divergences = [];
   const stages = report?.stages;
   if (!isObject(stages) || !isNonEmptyString(targetRepo)) return divergences;
@@ -5389,7 +5449,7 @@ export function detectLedgerDivergence(report, packet, targetRepo) {
     const packetPreviewUrl = optionalString(packet?.deploy?.preview_url);
     const packetProductionUrl = optionalString(packet?.deploy?.production_url);
     const url = reportUrl || packetPreviewUrl || packetProductionUrl;
-    if (url) {
+    if (url && !(allowUnrecordedHostedPreview && !reportUrl)) {
       const source = reportUrl
         ? "report.stages.deploy.outputs"
         : packetPreviewUrl

package/src/commercial-journey.mjs

@@ -11,6 +11,7 @@
  */
 
 import { specHashOf, specHashesMatch } from "./spec-hash.mjs";
+import { CHECKOUT_FLOW_PAGE_TYPES, upgradeCampaignSpec } from "../campaign-spec/dist/index.js";
 
 export const CALC_LABEL = "Campaigns-calculated · before tax";
 export const CALCULATED_PAIR_EVIDENCE = "calculated_pair";
@@ -213,6 +214,20 @@ function catalogImportedAt(mapDoc) {
     ?? null;
 }
 
+// The page's type in the v5 vocabulary: a v4 Map's `checkout → checkout` chain
+// reads as `checkout_step` pages ahead of the one Checkout (campaigns-os#641).
+const upgradedMaps = new WeakMap();
+function v5PageType(mapDoc, page) {
+  if (!mapDoc || typeof mapDoc !== "object") return page?.type ?? null;
+  if (!upgradedMaps.has(mapDoc)) upgradedMaps.set(mapDoc, upgradeCampaignSpec(mapDoc));
+  const upgraded = upgradedMaps.get(mapDoc);
+  for (const funnel of array(upgraded?.funnels)) {
+    const hit = array(funnel?.pages).find((candidate) => present(page?.id) && String(candidate?.id) === String(page.id));
+    if (hit) return hit.type ?? null;
+  }
+  return page?.type ?? null;
+}
+
 function descriptor(page, mapDoc, role, lines, options = {}) {
   const funnel = findFunnel(mapDoc, page);
   const suffix = options.id_suffix ? `:${options.id_suffix}` : "";
@@ -221,7 +236,7 @@ function descriptor(page, mapDoc, role, lines, options = {}) {
     upsell: page?.type === "upsell" || page?.type === "downsell",
     context: {
       page_id: page?.id ?? null,
-      page_type: page?.type ?? null,
+      page_type: v5PageType(mapDoc, page),
       page_label: page?.label ?? page?.name ?? page?.id ?? null,
       page_order: Number(page?.order) || 0,
       funnel_id: funnel?.id ?? null,
@@ -1045,8 +1060,16 @@ function acceptDelta(page) {
   return moneyFact(signedCents(cents), total.state);
 }
 
+// The checkout total is the cart the shopper pays for at the Checkout. That cart
+// is priced on whichever checkout-flow page carries it: the select page of a
+// two-step flow, the first step of a split checkout, or the Checkout itself
+// (campaigns-os#641). The Checkout of a multi-step path carries no packages, so
+// looking for the page typed "checkout" priced nothing on those flows. Only
+// pages that declare packages are planned, so every page here carries a cart;
+// pages arrive sorted by page_order, and with several paths the first is
+// summarized.
 function journeySummary(pages) {
-  const checkout = pages.find((page) => page.page_type === "checkout");
+  const checkout = pages.find((page) => CHECKOUT_FLOW_PAGE_TYPES.includes(page.page_type));
   const checkoutTotal = checkout?.representative_total
     || unresolvedFact("Unresolved: checkout scenario unavailable");
   const bumps = pages.flatMap((page) => page.bumps.map((bump) => ({ ...bump, page_id: page.page_id })));

package/src/design-source-package.mjs

@@ -2085,7 +2085,7 @@ function sourceReferenceKindForManifestFile(file) {
 function normalizedPageRole(type) {
   const normalized = slugify(type || "page");
   if (["landing", "product", "presell", "advertorial"].includes(normalized)) return "landing";
-  if (["checkout", "select", "cart"].includes(normalized)) return "checkout";
+  if (["checkout", "checkout-step", "checkout_step", "select", "cart"].includes(normalized)) return "checkout";
   if (["upsell", "oto", "one-time-offer"].includes(normalized)) return "upsell";
   if (["downsell", "downsell-offer"].includes(normalized)) return "downsell";
   if (["receipt", "thank-you", "thankyou", "confirmation"].includes(normalized)) return "receipt";

package/src/design-source-publication.mjs

@@ -4,7 +4,7 @@ import { randomUUID } from "node:crypto";
 import { accessSync, constants as fsConstants, existsSync, linkSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { writeThemeArtifacts } from "./brand-theme.mjs";
-import { cloneJson, filesystemPathsMatch, isObject, isNonEmptyString, optionalString, readJson, resolveFromFile, sha256File } from "./cli-helpers.mjs";
+import { cloneJson, filesystemPathsMatch, isObject, isNonEmptyString, optionalString, portableArtifactPaths, readJson, resolveFromFile, sha256File } from "./cli-helpers.mjs";
 import { DESIGN_SOURCE_PACKAGE_REL_PATH, createDesignSourcePackageArtifactReference, hashSerializedDesignSourcePackage, serializeDesignSourcePackage, synthesizeHtmlFunnelDesignSourcePackage, validateDesignSourcePackage } from "./design-source-package.mjs";
 import { stampDoctorProducer } from "./doctor-sidecar.mjs";
 import { stageWriteInputs } from "./input-currency.mjs";
@@ -21,7 +21,7 @@ import { resolveTemplateFamilyDesignSource } from "./template-reference.mjs";
 // states never count as accumulated agent evidence. setup's seed state may
 // legitimately be "skipped" (scaffold already present); every other stage is
 // seeded "pending" with empty ledger arrays.
-function assemblyReportStagesWithEvidence(existingReport) {
+export function assemblyReportStagesWithEvidence(existingReport) {
   const stages = existingReport?.stages;
   if (!isObject(stages)) return [];
   const withEvidence = [];
@@ -979,10 +979,10 @@ export async function withDesignSourcePublication({ targetRepo, outputs, force =
             : [],
         );
         publishPrepareBuildJsonOutputs([
-          { label: "Build Packet", path: packetPath, value: packet },
-          { label: "Campaign Build Brief", path: briefPath, value: brief },
-          { label: "Build Context", path: contextPath, value: context },
-          { label: "Assembly Report", path: reportPath, value: report },
+          { label: "Build Packet", path: packetPath, value: portableArtifactPaths(packet, targetRepo, { artifactPath: packetPath }) },
+          { label: "Campaign Build Brief", path: briefPath, value: portableArtifactPaths(brief, targetRepo, { artifactPath: briefPath }) },
+          { label: "Build Context", path: contextPath, value: portableArtifactPaths(context, targetRepo, { artifactPath: contextPath }) },
+          { label: "Assembly Report", path: reportPath, value: portableArtifactPaths(report, targetRepo, { artifactPath: reportPath }) },
         ], prepareBuildCollisionPaths, {
           beforePublish: recheckStageEvidence,
         });
@@ -997,7 +997,7 @@ export async function withDesignSourcePublication({ targetRepo, outputs, force =
         // stamped with the intake command that ran doctor (`start` or `build`,
         // #312) without a second write path for it.
         publishPrepareBuildJsonOutputs([
-          { label: "Doctor Output", path: doctorOutPath, value: stampDoctorProducer(doctor, command) },
+          { label: "Doctor Output", path: doctorOutPath, value: portableArtifactPaths(stampDoctorProducer(doctor, command), targetRepo) },
         ], prepareBuildCollisionPaths);
       },
     }));