@nextcommerce/campaigns-os 1.55.0 → 1.57.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>]
@@ -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 {
@@ -4452,7 +4465,7 @@ export function nextStage(stage, args, ambient = null, { qcStandIns = null, qcRe
         errors,
         warnings,
         ready,
-        prompt: `Pipeline complete. All stages in the assembly report are in a terminal status. To repeat build work, do the work and run \`${cmd("record")} build --packet <path>\`; this makes downstream stages owed as needed. Run \`${cmd("qa")} run\` for QA. For a hosted deploy, record the URL and stage outcome as the deploy prompt describes. Then call \`${cmd("next")}\` again. If a run session is active, finish it with \`${cmd("run")} end\` so the Run Record is assembled and the session closes.${report?.stages?.qa?.status === "completed_with_warnings" ? " QA passed with exceptions; report them to the operator without clearing or waiving them or changing markup just to make them pass." : ""}`,
+        prompt: `${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." : ""}`,
       });
     }
     stage = picked.stage;
@@ -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("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.");
+      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,25 @@ 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) {
+    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) {
       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("advance", "command", `${cmd("next")} --packet ${packetPath} --json`, "Advance to QA once the deploy URL is recorded.");
+    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.");
+    }
   } 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 +5108,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_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.
 - 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 +5180,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("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. 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 +5254,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)}\`. There is no hosted record deploy command.`;
+  }
   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 +5281,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("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 `Deploy the built campaign to ${target}.
 
 Read first:
@@ -5247,36 +5306,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 +5351,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 +5424,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 +5457,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);
       },
     }));