@nextcommerce/campaigns-os 1.50.0 → 1.52.0

package/src/cli.mjs

@@ -20,6 +20,7 @@ import {
 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 { diagnosticExport, diagnosticTextLines } from "./diagnostic.mjs";
 import { observeProgress, PROGRESS_OBSERVATION } from "./progress-node.mjs";
 import { HIDDEN_EAGER_MEDIA_ACTIONS, requiredActionText, substitutePacket } from "./gate-actions.mjs";
@@ -75,7 +76,10 @@ import {
   isWrapperPolicy,
 } from "./adapter-decision-contract.mjs";
 import { markDoctorSidecarStale, writeDoctorSidecar, writeJsonAtomic } from "./doctor-sidecar.mjs";
-import { campaignSidecarPaths, resolveCampaignWorkspace, targetRepoFor } from "./campaign-workspace.mjs";
+import { QcAcceptRefusal, buildQcHandoff, parseQcResultRef, planQcAccepts, projectQcAccept, qcAcceptAttribution, qcHandoffTextLines } from "./qc-accept.mjs";
+import { loadQcRederivers } from "./qc-check-registry.mjs";
+import { fingerprint12, readCurrentQcResults } from "./qc-results.mjs";
+import { campaignSidecarPaths, explicitReportPath, resolveCampaignWorkspace, targetRepoFor } from "./campaign-workspace.mjs";
 import { canonicalPath, sameFile } from "./fs-identity.mjs";
 import { DEFAULT_PROXY_BASE, fetchSpecByMapId } from "./spec-fetch.mjs";
 import { writeMapSdkPin } from "./map-pin-writeback.mjs";
@@ -119,6 +123,7 @@ import { crawlSourceAssetPaths } from "./source-asset-crawl.mjs";
 import {
   THEME_POLICIES,
   inspectBrandTheme,
+  themeIssueForReport,
   writeThemeArtifacts,
 } from "./brand-theme.mjs";
 import {
@@ -144,6 +149,7 @@ import {
   LOCAL_PROOF_BUILD_ENVIRONMENT_SCOPE,
   LOCAL_PROOF_NEVER_EDIT_RULE,
   LOCAL_PROOF_PARITY_COMMAND,
+  LOCAL_PROOF_RECORD_BUILD_COMMAND,
   LOCAL_PROOF_PARITY_FIELD,
   LOCAL_PROOF_PARITY_SCOPE,
   recordedBuildEnvironment,
@@ -194,7 +200,7 @@ import {
   capturePolishPageLoad,
   createPolishCaptureBinding,
   evaluateRecordedHiddenEagerMediaCheckpoint,
-  mergePolishPageLoadEvidence,
+  mergePolishCaptureEvidence,
   planPolishCapture,
 } from "./polish-node.mjs";
 import { HIDDEN_EAGER_MEDIA_SCOPE, POLISH_CAPTURE_PROBLEM_CODES } from "./polish-page-load.mjs";
@@ -317,12 +323,13 @@ Usage:
   campaigns-os theme generate --packet <campaign-runtime.build.json> [--context <json>] [--out-dir <dir>] [--force] [--json]
   campaigns-os theme waive --packet <campaign-runtime.build.json> --reason "<why>" --waived-by "<named human>" [--expires-at <ISO>] [--report <json>] [--dry-run] [--json]   # record an explicit theme-gate waiver on the assembly report; placeholders such as "operator" are refused. --dry-run validates the same way and prints the waiver it would write, without touching the report
   campaigns-os checkpoint waive --packet <campaign-runtime.build.json> --gate <checkpoint-id> [--page <page_id>] --reason "<why>" --waived-by "<named human>" [--expires-at <ISO>] [--review-condition "<trigger>"] [--report <json>] [--dry-run] [--json]   # one bound is required; registered gates: page_kit.store_profile, page_kit.sdk_version, polish.hidden_eager_media, built_output.upsell_selector_scope, source_html.producer_provenance (per page: --page <page_id> is required, for a Figma-typed page whose approved source is hand-written HTML). --dry-run runs every check (named human, bounds, registered and waivable gate) and prints the waiver it would write, without touching the report
+  campaigns-os checkpoint accept --packet <campaign-runtime.build.json> --result <result_id>@<fingerprint12> [--result ...] --reason "<the operator's reason>" --accepted-by "<named human>" [--expires-at <ISO>] [--review-condition "<trigger>"] [--report <json>] [--dry-run] [--json]   # record the operator's accept of a measured QC warning, as the QC handoff of next prints it; changes no readiness and lapses when the measured state or the build changes. --dry-run runs every check and prints the accepts it would record, without touching the report
   campaigns-os page-kit sync --packet <campaign-runtime.build.json> [--dry-run] [--json]   # write the CampaignSpec's Store Profile fields (campaign.store_*) and SDK pin (global_config.sdk_version, runtime.sdk_version alias) into the target's _data/campaigns.json entry for the packet's route, printing a field-by-field diff; the recovery for a doctor blocked on page_kit.store_profile / page_kit.sdk_version after a fresh scaffold. Writes only those ten fields, only from usable spec values (a bad pin, a non-http URL, a non-tel: phone URI or the demo value itself is reported as not synced, status PARTIAL); exit 2 when the entry or the spec is missing, or the spec identifies another campaign.
   campaigns-os spec derive --packet <campaign-runtime.build.json> [--dry-run] [--json] [--report <json>] [--from-store <subdomain> [--store-token-source env:<VAR>]] [--write-map] [--proxy-base <url>]   # write the fields the target repo already states into the packet's local CampaignSpec (spec.local_path): the SDK pin from _data/campaigns.json[<route>].sdk_version (global_config.sdk_version, and the runtime.sdk_version alias when declared), each page's page_url from the page tree under src/<route>/ (filename or permalink), and the analytics ids the entry carries (gtm_id -> analytics.providers.gtm.containerId, fb_pixel_id -> analytics.providers.facebook.pixelId); prints a field-by-field before -> after diff and writes nothing else. Repo-derived fields only and no network by default; --from-store <subdomain> (the <store> of <store>.29next.store) also reads through campaigns-os login gateway credentials (--store-token-source env:<VAR> explicitly selects the warned break-glass Admin path; a token never goes on the command line) and writes the nine campaign.store_* Store Profile fields: store_name and store_url (primary domain) and store_phone/store_phone_tel from GET /store/, and store_terms/privacy/contact/returns/shipping as https://<primary domain>/<slug>/ from the one storefront page (GET /pages/) whose slug or title names each policy; an empty store field, no page or several never empties the spec's value. A field the repo or store cannot state (a scaffold's seeded pin, an unbound page, an empty or malformed id, an active page_kit.sdk_version waiver, an empty store field, an unbound policy page) is reported as not derived, status PARTIAL; exit 2 when the packet, the spec or the target entry is missing, the spec identifies another campaign, or the store cannot be read (credential missing, 401/403, no such store, unreachable). --write-map also records the derived pin into the saved Map's Build hints (Campaign Cart SDK version) through the proxy Worker (PUT /api/maps/<spec.map_id> under X-Campaign-Key, the packet's Campaigns API key, with the Map's spec_hash as the X-Spec-Hash precondition): written when the Map declares no pin or one behind the repo, unchanged when equal, refused (warning, exit 0) when the Map pin is ahead or cannot be ordered, failed (error, exit 2) when the key is missing or mismatched, the Map is gone, was saved in between, or the proxy refuses the body; the write is recorded on the Assembly Report evidence[] and in the result's map object. --proxy-base overrides the canonical proxy (https, or a loopback host over http); --dry-run reads the Map and reports would_write without a PUT.
   campaigns-os page-kit parity --packet <campaign-runtime.build.json> [--report <json>] [--json]   # local proof mode (deploy.target local-serve): render the current source in development and production through the target's page-kit into temp dirs, assert the served _site/ is the current development render and that production differs from it only in environment-gated output (same page set, same route slugs, same Campaign Cart pin and next-api-key); records stages.assembly.evidence.local_proof.production_parity, which doctor reads as local_proof.production_parity. Exit 2 on a non-gated difference.
   campaigns-os polish capture --packet <campaign-runtime.build.json> --base-url <url> [--report <json>] [--headed] [--auth-cookie <cookie>] [--json]
   campaigns-os record setup --packet <campaign-runtime.build.json> [--context <json>] [--report <json>] [--dry-run] [--json]   # record setup complete once the campaign output directory exists: Build Context scaffold.required=false and stages.setup completed, validated against their schemas before either is written
-  campaigns-os record build --packet <campaign-runtime.build.json> [--context <json>] [--report <json>] [--dry-run] [--json]   # after page-kit build: stages.assembly completed with build_fingerprint = doctor's derived.build_output_fingerprint.value (and the Design Source Package material fingerprint when the report has one); stages.polish becomes required unless its evidence is bound to this exact output
+  campaigns-os record build --packet <campaign-runtime.build.json> [--build-environment <development|production>] [--context <json>] [--report <json>] [--dry-run] [--json]   # after page-kit build (--build-environment records stages.assembly.evidence.build_environment; local proof mode records development): stages.assembly completed with build_fingerprint = doctor's derived.build_output_fingerprint.value (and the Design Source Package material fingerprint when the report has one); stages.polish becomes required unless its evidence is bound to this exact output
   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; 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
@@ -458,9 +465,12 @@ function closestCommand(input) {
 // invocation policy: src/invocation.mjs owns it and main() only hands over the
 // mechanisms. The raw argv rides along for the handlers that must see it
 // (authentication, and the two raw-token validators).
-export async function main(argv, { authentication } = {}) {
+// `qcStandIns` is the in-process QC stand-in override the QC tests pass
+// (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 } = {}) {
   return runInvocation(parseArgs(argv), {
-    dispatch: (command, args, context) => dispatch(command, args, { ...context, argv, authentication }),
+    dispatch: (command, args, context) => dispatch(command, args, { ...context, argv, authentication, qcStandIns }),
     closeOutStaleRunSessions,
     ambientRunSession,
     lifecycleIdentity,
@@ -719,7 +729,7 @@ export function recordQaStageOutcome(args, result) {
         // Which build this verdict judged, and the gates whose browser outcome
         // the doctor's static scan defers to (qaGatePassedForCurrentBuild). A
         // gate that never ran is left out, so silence never reads as a pass.
-        evidence: qaStageGateEvidence(verdict, report),
+        evidence: qaStageGateEvidence(verdict, report, result),
         // Counts-only: never order ids, refs, emails or URLs (see
         // summarizePurchaseProof). This is what lets `next` tell a real purchase
         // path from a `--test-order off` diagnostic.
@@ -755,12 +765,21 @@ export function recordQaStageOutcome(args, result) {
   }
 }
 
-function qaStageGateEvidence(verdict, report) {
+// QC results are written on every QA record, with the build
+// they were measured against, whether or not a gate outcome is recorded: a
+// record without qc_results reads as captured by an earlier version. The rows
+// come from the QA run's own result; readers re-derive them from the full
+// verdict's qc.* assertions.
+function qaStageGateEvidence(verdict, report, result = null) {
   const gates = {};
   const placeholderText = summarizePlaceholderTextGate(verdict);
   if (placeholderText) gates[QA_GATE_PLACEHOLDER_TEXT_RESIDUE] = placeholderText;
-  if (!Object.keys(gates).length) return null;
-  return { source_build_fingerprint: currentBuildFingerprint(report), gates };
+  const qc = {
+    qc_results: Array.isArray(result?.qc_results) ? result.qc_results : [],
+    qc_build_fingerprint: currentBuildFingerprint(report),
+  };
+  if (!Object.keys(gates).length) return qc;
+  return { source_build_fingerprint: currentBuildFingerprint(report), gates, ...qc };
 }
 
 // What the auto-end says when the attempt does NOT end the session. Every
@@ -892,7 +911,7 @@ const PREPARE_MODES = Object.freeze({
 // no ambient session, and ahead of help routing, so `login --help`, `demo
 // --help` and `tooling setup --help` reach their own handlers. `argv` is the
 // unparsed argv, for the handlers that must see repeated tokens.
-async function dispatch(command, args, { recorder = NOOP_RECORDER, ambient = null, sessionHolder = null, argv, authentication } = {}) {
+async function dispatch(command, args, { recorder = NOOP_RECORDER, ambient = null, sessionHolder = null, argv, authentication, qcStandIns } = {}) {
   // Authentication never recovers/remits run sessions or records argv in a
   // lifecycle journal. Credentials belong only in the user credential store.
   if (command === "login" || command === "logout") {
@@ -1000,7 +1019,7 @@ async function dispatch(command, args, { recorder = NOOP_RECORDER, ambient = nul
     // The live campaign ref check's one read (#533), made before the
     // synchronous inspection; see readDoctorLiveCampaign.
     const liveCampaign = await readDoctorLiveCampaign(args);
-    const result = doctorCommand(args, { liveCampaign });
+    const result = doctorCommand(args, { liveCampaign, qcStandIns });
     writeResult(result, args, result.ok ? 0 : 2);
     printDoctorTinyPrompt(result, args);
     return;
@@ -1055,6 +1074,12 @@ async function dispatch(command, args, { recorder = NOOP_RECORDER, ambient = nul
   }
 
   if (command === "checkpoint") {
+    if (args._[1] === "accept") {
+      const result = await checkpointAcceptCommand(args, { argv, qcStandIns });
+      if (!result) return;
+      writeResult(result, args, result.ok ? 0 : 2);
+      return;
+    }
     const result = waiveOrRefuse(args, () => checkpointCommand(args), {
       gate: optionalString(args.gate) || null,
       registeredGates: Object.keys(CHECKPOINT_EVALUATORS),
@@ -1154,7 +1179,10 @@ async function dispatch(command, args, { recorder = NOOP_RECORDER, ambient = nul
     // stage from the current report + doctor state. Existing form with an
     // explicit stage (`next build`, `next polish`, etc.) is unchanged.
     const stage = args._[1] || null;
-    const result = nextStage(stage, args, ambient);
+    // The QC handoff re-derives QA and Polish results through the check
+    // registry, whose check modules load lazily, so they are loaded here.
+    const qcRederivers = await loadQcRederivers();
+    const result = nextStage(stage, args, ambient, { qcStandIns, qcRederivers });
     await observeProgress(args, result, { packageVersion: packageVersion(), resolveKey: resolveCampaignsApiKeySource });
     writeResult(result, args, result.ok ? 0 : 2);
     printNextTinyPrompt(result, args);
@@ -1893,7 +1921,7 @@ function prepareBuildUnderLock({
     },
     qa: {
       proof_policy: proofPolicy,
-      test_order_policy_notes: "Test Orders use global test cards that bypass the gateway and create no transactions. Run them any time with `qa run --test-order common`: when every actual terminal path in the selected checkout topology fits under the flood cap, common runs them all (effective depth `full`, reason `under_cap`); above the cap it runs checkout, first-offer accept/decline and a deduplicated shortest real receipt path, then adds the shortest path that clicks the decline on each offer or downsell page no planned path declines yet, up to the cap, and names any page left out. The `browser-test-order:upsell-action-coverage` verdict row warns naming each offer page whose decline no executed order clicked. Use `--test-order full` for every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. Use `--test-order tiers` (or `tiers:common` / `tiers:full`) to drive one strict-selection order per selector tier the CampaignSpec declares on the checkout page, crossed with those path shapes; order-bump rows marked `is_upsell` are add-ons, not tiers, so a three-tier checkout with one bump plans 3 tiers, and `--select-package <ref[:qty],...>` narrows a tiers run to the listed tiers. The default accidental-flood cap is 6, and an overflow names the exact explicit `--max-test-orders` raise and lists the planned paths (up to 40 ids, the remainder counted). That cap bounds planned paths; `--max-order-creations` bounds actual order creations, defaults to the planned path count, and is reserved before each submit. Localhost on any port is a globally allowed Development domain; non-localhost preview/production origins still need SDK origin allowlist confirmation. There is no permission flag: depth is the only control.",
+      test_order_policy_notes: "Test Orders use global test cards that bypass the gateway and create no transactions. Run them any time with `qa run --test-order common`: when every actual terminal path in the selected checkout topology fits under the flood cap, common runs them all (effective depth `full`, reason `under_cap`); above the cap it runs checkout, first-offer accept/decline and a deduplicated shortest real receipt path, then adds the shortest path that clicks the decline on each offer or downsell page no planned path declines yet, up to the cap, and names any page left out. The `browser-test-order:upsell-action-coverage` verdict row warns naming each offer page whose decline no executed order clicked. Use `--test-order full` for every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. Use `--test-order tiers` (or `tiers:common` / `tiers:full`) to drive one strict-selection order per selector tier the CampaignSpec declares on the checkout page, crossed with those path shapes; order-bump rows marked `is_order_bump` or `is_upsell` are add-ons, not tiers, so a three-tier checkout with one bump plans 3 tiers, and `--select-package <ref[:qty],...>` narrows a tiers run to the listed tiers. The default accidental-flood cap is 6, and an overflow names the exact explicit `--max-test-orders` raise and lists the planned paths (up to 40 ids, the remainder counted). That cap bounds planned paths; `--max-order-creations` bounds actual order creations, defaults to the planned path count, and is reserved before each submit. Localhost on any port is a globally allowed Development domain; non-localhost preview/production origins still need SDK origin allowlist confirmation. There is no permission flag: depth is the only control.",
     },
     notes: "Generated by campaigns-os prepare-build. Replace demo refs from CampaignSpec/API before launch.",
   };
@@ -2021,7 +2049,7 @@ function prepareBuildUnderLock({
   if (!writtenTheme.ok && Array.isArray(writtenTheme.errors) && writtenTheme.errors.length > 0) {
     context.theme.warnings = [
       ...(context.theme.warnings || []),
-      ...writtenTheme.errors.map((error) => ({ code: error.code, message: error.message, detail: error.detail || null })),
+      ...writtenTheme.errors.map(themeIssueForReport),
     ];
   }
 
@@ -2716,7 +2744,7 @@ export async function polishCaptureCommand(args, options = {}) {
     });
     assertPolishCaptureBindingUnchanged(initialBinding, currentBinding);
 
-    const merged = mergePolishPageLoadEvidence(currentReport, capture.page_load);
+    const merged = mergePolishCaptureEvidence(currentReport, { pageLoad: capture.page_load, mediaWeight: capture.media_weight });
     checkpoint = evaluateRecordedHiddenEagerMediaCheckpoint({
       packet: currentPacket,
       report: merged,
@@ -2811,7 +2839,7 @@ function waiveOrRefuse(args, run, { gate = null, registeredGates = [] } = {}) {
 function checkpointCommand(args) {
   const subcommand = args._[1] || "help";
   if (subcommand !== "waive") {
-    throw refused(`Unknown checkpoint subcommand. Use: ${cmd("checkpoint")} waive --packet <campaign-runtime.build.json> --gate <checkpoint-id> [--page <page_id>] --reason "<why>" --waived-by "<named human>" [--expires-at <ISO>] [--review-condition "<trigger>"]. Registered gates: ${Object.keys(CHECKPOINT_EVALUATORS).join(", ")}.`);
+    throw refused(`Unknown checkpoint subcommand. Use: ${cmd("checkpoint")} waive --packet <campaign-runtime.build.json> --gate <checkpoint-id> [--page <page_id>] --reason "<why>" --waived-by "<named human>" [--expires-at <ISO>] [--review-condition "<trigger>"]. Registered gates: ${Object.keys(CHECKPOINT_EVALUATORS).join(", ")}. Or: ${cmd("checkpoint")} accept --packet <campaign-runtime.build.json> --result <result_id>@<fingerprint12> [--result …] --reason "<the operator's reason>" --accepted-by "<operator's name>" [--expires-at <ISO>] [--review-condition "<trigger>"] [--report <json>] [--dry-run].`);
   }
   return checkpointWaive(args);
 }
@@ -2934,6 +2962,170 @@ export function checkpointWaive(args) {
   };
 }
 
+// `checkpoint accept`: records an operator's accept of a
+// measured QC warning in report.qc_accepts[], beside the unchanged
+// measurement. It reads only what is already on disk (doctor recomputed
+// offline, the persisted doctor sidecar, the Assembly Report and the full QA
+// verdict the QA stage names) and sends nothing. Every listed result must be a
+// current accept-eligible warning that was on record before this command;
+// the check runs again under the report lock immediately before the one
+// write, and if any ref fails nothing is written.
+const CHECKPOINT_ACCEPT_VALUE_FLAGS = Object.freeze({
+  packet: "<campaign-runtime.build.json>",
+  result: "<result_id>@<fingerprint12>",
+  reason: "\"<the operator's reason>\"",
+  "expires-at": "<ISO>",
+  "review-condition": "\"<trigger>\"",
+  report: "<json>",
+});
+
+// Every value of a flag the operator may repeat, from the raw argv: the shared
+// parser keeps only the last.
+function repeatedFlagValues(argv, flag) {
+  const values = [];
+  const tokens = Array.isArray(argv) ? argv : [];
+  for (let index = 0; index < tokens.length; index += 1) {
+    if (tokens[index] !== `--${flag}`) continue;
+    const next = tokens[index + 1];
+    values.push(next === undefined || next.startsWith("--") ? null : next);
+  }
+  return values;
+}
+
+function qcAcceptRefusalEnvelope(error) {
+  return {
+    ok: false,
+    refusal_code: error.code,
+    error: error.message,
+    ...(error.refused?.length ? { refused: error.refused.map(({ result_ref, refusal_code }) => ({ result_ref, refusal_code })) } : {}),
+  };
+}
+
+export async function checkpointAcceptCommand(args, { argv = [], qcStandIns = null } = {}) {
+  try {
+    const qcRederivers = await loadQcRederivers();
+    return checkpointAccept(args, { argv, qcStandIns, qcRederivers });
+  } catch (error) {
+    // A typed refusal is an invocation refusal like every untyped one
+    // (refused() marks this invocation's refusal scope), so a refused accept
+    // journals nothing, rendered under --json or thrown without it.
+    const refusal = error instanceof QcAcceptRefusal ? refused(`${error.message} (${error.code})`) : error;
+    if (args.json !== true) throw refusal;
+    const envelope = error instanceof QcAcceptRefusal ? qcAcceptRefusalEnvelope(error) : { ok: false, error: String(error?.message ?? error) };
+    console.log(JSON.stringify(envelope, null, 2));
+    console.error(`campaigns-os: ${envelope.error}`);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+export function checkpointAccept(args, { argv = [], qcStandIns = null, qcRederivers = null } = {}) {
+  // The command clock; no flag sets accepted_at.
+  const now = new Date().toISOString();
+  const acceptedByValues = repeatedFlagValues(argv, "accepted-by");
+  const acceptedBy = acceptedByValues.length === 1 && isNonEmptyString(args["accepted-by"]) ? args["accepted-by"] : null;
+  if (acceptedByValues.length > 1) throw refused("checkpoint accept takes one --accepted-by: one operator decides one accept command.");
+  for (const [key, placeholder] of Object.entries(CHECKPOINT_ACCEPT_VALUE_FLAGS)) {
+    if (!Object.hasOwn(args, key) || args[key] == null) continue;
+    if (!isNonEmptyString(args[key])) throw refused(`--${key} needs a value: pass --${key} ${placeholder}.`);
+  }
+  if (repeatedFlagValues(argv, "reason").length > 1) throw refused("checkpoint accept takes one --reason per invocation: the operator's reason, verbatim.");
+  const packetPath = resolve(requireArg(args, "packet"));
+  const dryRun = isDryRun(args);
+  const refValues = repeatedFlagValues(argv, "result");
+  if (!refValues.length) throw refused(`checkpoint accept needs at least one --result <result_id>@<fingerprint12>, as the QC handoff of \`${cmd("next")}\` prints it.`);
+  const refs = refValues.map((value) => {
+    const parsed = parseQcResultRef(value);
+    if (!parsed) throw refused(`--result ${JSON.stringify(value)} is not <result_id>@<fingerprint12>; copy the ref the QC handoff of \`${cmd("next")}\` prints.`);
+    return parsed;
+  });
+  const duplicate = refs.find((ref, index) => refs.findIndex((other) => other.id === ref.id) !== index);
+  if (duplicate) throw refused(`--result names "${duplicate.id}" more than once; list each result once.`);
+  const attribution = qcAcceptAttribution({
+    reason: args.reason,
+    acceptedBy,
+    now,
+    expiresAt: args["expires-at"] ?? null,
+    reviewCondition: args["review-condition"] ?? null,
+  });
+
+  const packet = readJson(packetPath);
+  const workspace = resolveCampaignWorkspace(packetPath, {
+    packet,
+    reportPath: args.report == null ? undefined : resolve(args.report),
+    followContextPointer: false,
+  });
+  const { reportPath, targetRepo, doctorOutPath } = workspace;
+  if (!existsSync(reportPath)) throw refused(`checkpoint accept needs an assembly report at ${reportPath}; run prepare-build/start first.`);
+  // An accept only appends. A qc_accepts or evidence value that is not an
+  // array is refused, never replaced, so the value already there stays as it
+  // is (checked on the read before the lock and again under it).
+  const refuseUnappendable = (report) => {
+    for (const field of ["qc_accepts", "evidence"]) {
+      if (isPlainObject(report) && Object.hasOwn(report, field) && !Array.isArray(report[field])) {
+        throw refused(`checkpoint accept refused; nothing was written: report.${field} in ${reportPath} is not an array, and an accept only appends to it. It was left as it is; repair it before accepting.`);
+      }
+    }
+  };
+
+  // Doctor is recomputed offline (no live refs), the spec read the way `next`
+  // reads it, and every leg's results taken from its reader site.
+  const plan = (report) => {
+    const doctor = doctorPacket(packetPath, { reportPath, ...(qcStandIns ? { qcStandIns } : {}) });
+    let spec = null;
+    try {
+      spec = readJsonIfExists(doctor.derived?.spec_path || null);
+    } catch {
+      spec = null;
+    }
+    const { results } = readCurrentQcResults({ report, doctor, spec, targetRepo, packetPath, reportPath, qcStandIns, rederivers: qcRederivers });
+    return planQcAccepts({ refs, results, sidecarPath: doctorOutPath, now, attribution });
+  };
+  // Checked once before taking the lock, so a refusal touches nothing, and
+  // again on the report read under the lock, immediately before the write.
+  const unlocked = readJson(reportPath);
+  refuseUnappendable(unlocked);
+  plan(unlocked);
+  let records = [];
+  const recordAccepts = (report) => {
+    refuseUnappendable(report);
+    records = plan(report);
+    return {
+      ...report,
+      qc_accepts: [...(report.qc_accepts ?? []), ...records],
+      evidence: [
+        ...(report.evidence ?? []),
+        ...records.map((record) => `QC accept: ${record.result_id}@${fingerprint12(record.state_fingerprint)} (${record.leg}) accepted by ${record.accepted_by} at ${record.accepted_at}: ${record.reason}`),
+      ],
+    };
+  };
+  commitWaiverToAssemblyReport(workspace, recordAccepts, {
+    command: "checkpoint accept",
+    staleReason: `A QC accept was recorded after this doctor snapshot. Re-run ${cmd("doctor")} (or next) for current state.`,
+  }, { dryRun });
+  const accepts = records.map(projectQcAccept);
+  if (dryRun) {
+    return {
+      ok: true,
+      status: "dry_run",
+      dry_run: true,
+      action: "checkpoint-accept",
+      accepts,
+      report_path: reportPath,
+      would_write: reportPath,
+      note: "Dry run: nothing was written and the doctor sidecar was not marked stale. Re-run without --dry-run to record these accepts.",
+    };
+  }
+  return {
+    ok: true,
+    status: "recorded",
+    action: "checkpoint-accept",
+    accepts,
+    report_path: reportPath,
+    note: "Each accept changes only the result's disposition to operator_accepted. The warning, doctor status, next status and QA disposition are unchanged, and the accept lapses when the measured state or the build changes.",
+  };
+}
+
 // `page-kit sync`: write the CampaignSpec's Store Profile fields and SDK pin
 // into the target's _data/campaigns.json entry for the packet's route. This is
 // the recovery the two page-kit gates name: a fresh scaffold seeds the entry
@@ -3810,8 +4002,8 @@ export function pageKitParityCommand(args, options = {}) {
   const environment = recordedBuildEnvironment(report);
   if (environment !== LOCAL_PROOF_BUILD_ENVIRONMENT) {
     addIssue(result.warnings, LOCAL_PROOF_BUILD_ENVIRONMENT_SCOPE, environment
-      ? `${LOCAL_PROOF_BUILD_ENVIRONMENT_FIELD} is "${singleLineField(environment)}", not "${LOCAL_PROOF_BUILD_ENVIRONMENT}". If _site/ is a production build, the comparison below fails as proven_output_stale on the first environment-gated line; rebuild with ${LOCAL_PROOF_BUILD_COMMAND} and record the environment.`
-      : `${LOCAL_PROOF_BUILD_ENVIRONMENT_FIELD} is not recorded. The build stage under local-serve renders the development environment (${LOCAL_PROOF_BUILD_COMMAND}) and records it there; the comparison below assumes _site/ is that render.`);
+      ? `${LOCAL_PROOF_BUILD_ENVIRONMENT_FIELD} is "${singleLineField(environment)}", not "${LOCAL_PROOF_BUILD_ENVIRONMENT}". If _site/ is a production build, the comparison below fails as proven_output_stale on the first environment-gated line; rebuild with ${LOCAL_PROOF_BUILD_COMMAND} and record it with ${asInvocation(substitutePacket(LOCAL_PROOF_RECORD_BUILD_COMMAND, packetPath))}.`
+      : `${LOCAL_PROOF_BUILD_ENVIRONMENT_FIELD} is not recorded. The build stage under local-serve renders the development environment (${LOCAL_PROOF_BUILD_COMMAND}) and records it with ${asInvocation(substitutePacket(LOCAL_PROOF_RECORD_BUILD_COMMAND, packetPath))}; the comparison below assumes _site/ is that render.`);
   }
   const load = loadPageKitCampaignEntry({ targetRepo, publicRouteSlug });
   const expectedSdkVersion = load.status === "ok" && typeof load.entry?.sdk_version === "string" ? load.entry.sdk_version : null;
@@ -4038,7 +4230,7 @@ function describeDeclaredDepth(purchaseProof) {
   return `The declared order path depth is "${purchaseProof?.declared_depth || "unspecified"}"`;
 }
 
-export function nextStage(stage, args, ambient = null) {
+export function nextStage(stage, args, ambient = null, { qcStandIns = null, qcRederivers = null } = {}) {
   if (stage !== null && !NEXT_STAGE_ORDER.includes(stage)) {
     throw refused(`Unknown next stage: ${stage}. Accepted stages: ${NEXT_STAGE_ORDER.join(", ")}.`);
   }
@@ -4060,8 +4252,19 @@ export function nextStage(stage, args, ambient = null) {
   const doctor = doctorPacket(packetPath, {
     contextPath: args.context ? resolve(args.context) : undefined,
     reportPath: args.report ? resolve(args.report) : undefined,
+    ...(qcStandIns ? { qcStandIns } : {}),
   });
   const prepareBuildGate = doctor.derived?.prepare_build_gate || null;
+  // The CampaignSpec doctor just read (spec.local_path), for the QA stage's
+  // order-bump command. Best-effort: doctor reports an unreadable spec itself.
+  let spec = null;
+  let specReadError = null;
+  try {
+    spec = readJsonIfExists(doctor.derived?.spec_path || null);
+  } catch (error) {
+    spec = null;
+    specReadError = error;
+  }
   // #171: `next` recomputes doctor state on every call; persist that fresh
   // snapshot so the retained sidecar can never stay a green lie from an
   // earlier stage while the campaign degrades (the dogfood target sat
@@ -4127,13 +4330,26 @@ export function nextStage(stage, args, ambient = null) {
     } });
     if (divergences.length) result.divergences = divergences;
     result.gates = buildNextGates({ doctor, report, themeGate, polishGate, prepareBuildGate, packetPath });
-    result.next_actions = buildNextActions({ result, packetPath, packet, themeGate, polishGate, polishCheckpointGate, prepareBuildGate, ambient, runRecordCloseout, purchaseProof, brandContract: doctor.derived?.brand_contract || null, context: readJsonIfExists(contextPath), targetRepo });
+    result.next_actions = buildNextActions({ result, packetPath, packet, themeGate, polishGate, polishCheckpointGate, prepareBuildGate, ambient, runRecordCloseout, purchaseProof, brandContract: doctor.derived?.brand_contract || null, context: readJsonIfExists(contextPath), targetRepo, spec });
+    // The QC handoff: read from data already loaded plus the
+    // full QA verdict the QA stage names. It adds nothing to errors[],
+    // warnings[] or ready[], and `status` above never reads it. Its accept
+    // command names the report this run read when that is not the default
+    // one (from --report or the Build Context pointer), so it records there.
+    const qc = readCurrentQcResults({ report, doctor, spec, targetRepo, packetPath, reportPath, qcStandIns, rederivers: qcRederivers });
+    result.qc_handoff = buildQcHandoff({ results: qc.results, coverage: qc.coverage, accepts: report?.qc_accepts, packetPath, reportPath: explicitReportPath(reportPath, targetRepo) });
     recordNextRecommendation(ambient, result);
     return result;
   };
   const doctorHasOnlyPolishGateErrors = doctorErrorsAreOnlyPolishGate(doctor.errors);
   const errors = [];
   const warnings = doctor.warnings.map((issue) => withPacketSubstitutedIssue(issue, packetPath));
+  if (specReadError) {
+    warnings.push({
+      code: "next.order_bump_spec_unreadable",
+      message: `The CampaignSpec at ${doctor.derived?.spec_path} could not be read (${singleLineField(specReadError.message)}), so next cannot tell whether the checkout declares an order bump and names no order-bump QA command. Fix the spec and run next again.`,
+    });
+  }
   const ready = [...doctor.ready];
   if (!doctor.ok && !doctorHasOnlyPolishGateErrors) errors.push(...doctor.errors.map((issue) => withPacketSubstitutedIssue(issue, packetPath)));
 
@@ -4246,7 +4462,7 @@ export function nextStage(stage, args, ambient = null) {
     addPolishGateErrors(errors, polishGate, "qa");
     addPolishCheckpointGateErrors(errors, polishCheckpointGate, "qa");
     addThemeGateErrors(errors, themeGate, "qa");
-    prompt = qaPrompt(packetPath, reportPath, packet);
+    prompt = qaPrompt(packetPath, reportPath, packet, spec);
   }
   const status = errors.length
     ? "blocked"
@@ -4513,7 +4729,7 @@ function divergenceInspectAction(divergences, packetPath) {
 
 // Executable next actions: exact commands (or explicitly-manual steps), never
 // prose-only guidance. Ordering is the execution order an agent should follow.
-export function buildNextActions({ result, packetPath, packet, themeGate, polishGate, polishCheckpointGate, prepareBuildGate, ambient, runRecordCloseout = null, purchaseProof = null, brandContract = null, context = null, targetRepo = null }) {
+export function buildNextActions({ result, packetPath, packet, themeGate, polishGate, polishCheckpointGate, prepareBuildGate, ambient, runRecordCloseout = null, purchaseProof = null, brandContract = null, context = null, targetRepo = null, spec = null }) {
   const actions = [];
   const push = (id, kind, command, description, extras = {}) => actions.push({ id, kind, command, description, stage: result.stage, ...extras });
   const pushPolishCheckpointActions = () => {
@@ -4637,9 +4853,10 @@ 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}.`);
   } else if (result.stage === "build") {
-    push("build_skill", "skill", "next-campaigns-build", `Assemble the campaign per the build prompt, run the page-kit build, then record build with ${cmd("record")} build --packet ${packetPath}.`);
+    const recordBuild = `${cmd("record")} build --packet ${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/ and record ${LOCAL_PROOF_BUILD_ENVIRONMENT_FIELD} as "${LOCAL_PROOF_BUILD_ENVIRONMENT}". 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}`);
+      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}`);
       push("build_production_parity", "command", asInvocation(substitutePacket(LOCAL_PROOF_PARITY_COMMAND, packetPath)), "After the development build is proven, assert the production render differs from it only in environment-gated output (same pages, route slugs, Campaign Cart pin and next-api-key) before committing; the PR preview is the second check.");
     }
     if (themeGate?.status === "blocked") {
@@ -4661,7 +4878,9 @@ export function buildNextActions({ result, packetPath, packet, themeGate, polish
   } 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).");
-    push("qa_run", "command", `${cmd("qa")} run --packet ${packetPath} --base-url ${url} --browser --test-order common`, "Run browser + typed-card QA and publish the verdict.");
+    push("qa_run", "command", qaRunCommand(packetPath, url), "Run browser + typed-card QA and publish the verdict.");
+    const bumpCart = checkoutOrderBumpCart(spec);
+    if (bumpCart) push("qa_run_bump", "command", qaRunCommand(packetPath, url, bumpCart), `Prove the charged add-on. ${orderBumpRunReason(bumpCart)}`);
   } else if (result.stage === "done") {
     // #171: run-record closeout is a REQUIRED terminal action, not an
     // optional nicety — the dogfood run ended at a terminal stage with the
@@ -4803,7 +5022,7 @@ Read first:
 
 Rules:
 - Treat CampaignSpec/API as the source for package, shipping, voucher, payment, tracking, footer, and SEO values.
-- Treat the Campaign Build Brief as the merchandising/design presentation truth: page authority, palette/CTA style, variant media rules, pricing display strategy, promo/urgency language, payment/trust surfaces, display-name policy, residue policy, and QA expectations. Agents may resolve implementation uncertainty; unresolved brief questions are business uncertainty and should be asked or recorded, not guessed.
+- Treat the Campaign Build Brief as the merchandising/design presentation truth: page authority, palette/CTA style, variant media rules, pricing display strategy, the template's own promo placeholders, payment/trust surfaces, display-name policy, residue policy, and QA expectations. Agents may resolve implementation uncertainty; unresolved brief questions are business uncertainty and should be asked or recorded, not guessed.
 - Read the selected template family's agentContract and sharedFrontmatterVocabulary before commerce wiring.
 - Prepared AI/exported HTML must be converted into page-kit-ready source first: keep page-owned body markup, strip document wrappers, add YAML frontmatter, move shared CSS/assets into the campaign structure, and use Liquid helpers only for page-kit links/assets/includes. Page Kit publishes src/<slug>/assets/config.js as /<slug>/config.js and src/<slug>/assets/products/foo.png as /<slug>/products/foo.png; do not leave raw /assets/... or /<slug>/assets/... references in rendered pages.
 - Preserve prepared source HTML for landing/presell pages when it is a real standalone design.
@@ -4817,17 +5036,17 @@ Rules:
 - 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.
 - 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}\`. 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)}`;
+- 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}` : ""}\`. 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)}`;
 }
 
 // Local proof mode lines for the build prompt: under local-serve the build is
 // the development render, recorded as such, and the production render is
 // proven by parity before commit.
-function localProofPromptLines(packet) {
+function localProofPromptLines(packet, packetPath = "<packet>") {
   if (!isLocalServePacket(packet)) return "";
   return `
-- Local proof mode (deploy.target is local-serve): run the page-kit build in the ${LOCAL_PROOF_BUILD_ENVIRONMENT} environment — \`${LOCAL_PROOF_BUILD_COMMAND}\` — so _site/ is the development render, and record ${LOCAL_PROOF_BUILD_ENVIRONMENT_FIELD} as "${LOCAL_PROOF_BUILD_ENVIRONMENT}" on the assembly report. The starter templates gate every vendor loader on the environment and several loaders are protocol-relative (//host/...), which fail over a plain-HTTP local serve; the SDK's dl_* events still fire in development. Polish capture, browser QA and typed-card orders run against this served output. Before committing, run \`${asInvocation(LOCAL_PROOF_PARITY_COMMAND)}\` to prove the production render differs only in environment-gated output and pins the same Campaign Cart version; the PR preview is the second check. ${LOCAL_PROOF_NEVER_EDIT_RULE}`;
+- Local proof mode (deploy.target is local-serve): run the page-kit build in the ${LOCAL_PROOF_BUILD_ENVIRONMENT} environment — \`${LOCAL_PROOF_BUILD_COMMAND}\` — so _site/ is the development render, and record it with \`${cmd("record")} build --packet ${packetPath} --build-environment ${LOCAL_PROOF_BUILD_ENVIRONMENT}\`, which sets ${LOCAL_PROOF_BUILD_ENVIRONMENT_FIELD} to "${LOCAL_PROOF_BUILD_ENVIRONMENT}" on the assembly report (never hand-edit it). The starter templates gate every vendor loader on the environment and several loaders are protocol-relative (//host/...), which fail over a plain-HTTP local serve; the SDK's dl_* events still fire in development. Polish capture, browser QA and typed-card orders run against this served output. Before committing, run \`${asInvocation(LOCAL_PROOF_PARITY_COMMAND)}\` to prove the production render differs only in environment-gated output and pins the same Campaign Cart version; the PR preview is the second check. ${LOCAL_PROOF_NEVER_EDIT_RULE}`;
 }
 
 function setupPrompt(packetPath, contextPath, reportPath, packet) {
@@ -4952,9 +5171,57 @@ After deploy succeeds:
 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.`;
 }
 
-function qaPrompt(packetPath, reportPath, packet) {
+// 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.
+export function checkoutOrderBumpCart(spec) {
+  const funnels = Array.isArray(spec?.funnels)
+    ? spec.funnels
+    : Array.isArray(spec?.funnel_pages) ? [{ pages: spec.funnel_pages }] : [];
+  for (const funnel of funnels) {
+    const checkout = (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");
+    if (!checkout) continue;
+    const bumps = declaredOrderBumps(checkout);
+    if (!bumps.length) return null;
+    const base = declaredSelectorTiers(checkout)[0]?.ref || null;
+    return { base, bumps, cart: [base, ...bumps].filter(Boolean).map((ref) => `${ref}:1`).join(",") };
+  }
+  return null;
+}
+
+// Why the order-bump run exists, as one sentence for the action and the prompt.
+function orderBumpRunReason(bumpCart) {
+  const cart = bumpCart.base ? `base tier ${bumpCart.base} plus the bump` : "the bump";
+  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) {
   const url = packet.deploy?.preview_url || packet.deploy?.production_url || "<preview-url>";
   const briefPath = packet.build_brief?.normalized_path || "(missing)";
+  const bumpCart = checkoutOrderBumpCart(spec);
+  const bumpCommand = bumpCart
+    ? `\n\nOrder bump QA command (proves the charged add-on):\n${qaRunCommand(packetPath, url, bumpCart)}\n${orderBumpRunReason(bumpCart)}`
+    : "";
   return `Use next-campaigns-qa for this deployed campaign.
 
 ${packet.spec.local_spec_id ? "Local spec ID" : "Map ID"}: ${packet.spec.local_spec_id || packet.spec.map_id}
@@ -4966,9 +5233,9 @@ Browser install command:
 ${cmd("qa")} install-browser
 
 Node QA command:
-${cmd("qa")} run --packet ${packetPath} --base-url ${url} --browser --test-order common
+${qaRunCommand(packetPath, url)}${bumpCommand}
 
-Run the browser install once after install/update before --browser or --test-order. Test-order proof must exercise the campaign through the Campaign Cart SDK with the browser typed-card flow. Do not create hand-built backend API orders as launch proof. Compare visible placeholders, payment methods, variant media, promo/urgency copy, pricing presentation, and trust/guarantee claims against the Campaign Build Brief. Test Orders use global test cards that bypass the payment gateway and create no transactions, so they are safe to run any time and need no permission flags, packet policy, or merchant setup. Localhost on any port is a globally allowed Development domain for SDK initialization and suppresses Campaigns analytics events; non-localhost preview/production origins still need the SDK origin allowlist. Use --test-order common for the default depth: every actual terminal path when they fit under the flood cap, otherwise checkout, first-offer accept/decline and a deduplicated shortest real receipt path plus the shortest path that clicks the decline on each offer or downsell page not yet declined, up to the cap (the verdict row browser-test-order:upsell-action-coverage warns naming each offer page whose decline no order clicked); use an explicit path such as accept-decline-accept for a targeted matrix; or use --test-order full for every actual terminal path in the selected checkout topology. Cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The default accidental-flood cap is 6, and an overflow names the exact explicit --max-test-orders raise. That cap bounds planned paths; --max-order-creations bounds actual order creations and is reserved before each submit click, defaulting to the planned path count. A path whose failure is classified as created (the order is already placed) is inspected read-only and never resubmitted. A not_created failure may be re-run once, if the creation budget has a slot no still-unrun planned path needs; an ambiguous failure stops that path with an explicit operator check instead of buying again. Read evidence.recovery to tell a recovered pass from a first-attempt pass. Click rendered SDK upsell accept/decline controls for upsell proof. For multi-tier package selectors, drive a specific card with --select-package <ref[:qty],...> (strict: the path fails if the requested card cannot be found or selected, unlike best-effort --cart), or use --test-order tiers / tiers:common / tiers:full to drive every selector tier the CampaignSpec declares on the checkout page in one run (order-bump rows marked is_upsell are add-ons, not tiers; --select-package narrows a tiers run to the listed tiers); prove coupon-bearing orders with --apply-coupon <code> (typed into the rendered promo input, verified against the persisted-order voucher read-back). Reuse one test customer email via --test-email or CAMPAIGNS_OS_QA_TEST_EMAIL (a real monitored inbox in internal runs) so repeated QA does not litter the customer list.
+Run the browser install once after install/update before --browser or --test-order. Test-order proof must exercise the campaign through the Campaign Cart SDK with the browser typed-card flow. Do not create hand-built backend API orders as launch proof. Compare visible placeholders, payment methods and template trust badges, variant media, the template's own promo placeholders (demo timers, promo banners, placeholder voucher codes, exit-pop offers), and pricing presentation against the Campaign Build Brief. Do not flag the source design's own proof, urgency or guarantee elements: they are the merchant's content. Test Orders use global test cards that bypass the payment gateway and create no transactions, so they are safe to run any time and need no permission flags, packet policy, or merchant setup. Localhost on any port is a globally allowed Development domain for SDK initialization and suppresses Campaigns analytics events; non-localhost preview/production origins still need the SDK origin allowlist. Use --test-order common for the default depth: every actual terminal path when they fit under the flood cap, otherwise checkout, first-offer accept/decline and a deduplicated shortest real receipt path plus the shortest path that clicks the decline on each offer or downsell page not yet declined, up to the cap (the verdict row browser-test-order:upsell-action-coverage warns naming each offer page whose decline no order clicked); use an explicit path such as accept-decline-accept for a targeted matrix; or use --test-order full for every actual terminal path in the selected checkout topology. Cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The default accidental-flood cap is 6, and an overflow names the exact explicit --max-test-orders raise. That cap bounds planned paths; --max-order-creations bounds actual order creations and is reserved before each submit click, defaulting to the planned path count. A path whose failure is classified as created (the order is already placed) is inspected read-only and never resubmitted. A not_created failure may be re-run once, if the creation budget has a slot no still-unrun planned path needs; an ambiguous failure stops that path with an explicit operator check instead of buying again. Read evidence.recovery to tell a recovered pass from a first-attempt pass. Click rendered SDK upsell accept/decline controls for upsell proof. For multi-tier package selectors, drive a specific card with --select-package <ref[:qty],...> (strict: the path fails if the requested card cannot be found or selected, unlike best-effort --cart), or use --test-order tiers / tiers:common / tiers:full to drive every selector tier the CampaignSpec declares on the checkout page in one run (order-bump rows marked is_order_bump or is_upsell are add-ons, not tiers; --select-package narrows a tiers run to the listed tiers); prove coupon-bearing orders with --apply-coupon <code> (typed into the rendered promo input, verified against the persisted-order voucher read-back). Reuse one test customer email via --test-email or CAMPAIGNS_OS_QA_TEST_EMAIL (a real monitored inbox in internal runs) so repeated QA does not litter the customer list.
 
 Launch readiness note: Campaigns OS can prove the campaign build, SDK wiring, browser behavior, and typed-card order paths. It does not prove the merchant is ready for real shoppers. Before launch, confirm the production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and any merchant-side configuration. Treat those as real-shopper readiness items, not Campaigns OS build blockers.
 
@@ -5800,7 +6067,8 @@ export async function toolingStatusCommand(args, options = {}) {
   const auth = result.gateway_login;
   if (!auth.accounts.length) result.warnings.push(auth.state === "unavailable"
     ? "Gateway credential storage is unavailable or busy. Check user credential directory permissions and keychain access; wait for another campaigns-os process to finish. See docs/gateway-login.md for interrupted-process recovery."
-    : `Gateway login: ${auth.state}. Use ${result.cli.invocation_prefix} login --store <subdomain>.`);
+    : `Gateway login: ${auth.state}. Optional: ${result.cli.invocation_prefix} login --store <subdomain> only lets spec derive --from-store fill the Store Profile fields (campaign.store_*).`);
+  if (!auth.accounts.length && auth.state !== "unavailable") result.warnings.push(`Package, offer and shipping refs never come from the gateway login: read them with the campaign's public Campaigns API key (docs/build-packet.md, "Reading package, offer and shipping refs").`);
   for (const account of auth.accounts) (account.state === "logged_in" ? result.ready : result.warnings).push(`Gateway login: ${account.state}; store ${account.store}; access remaining ${account.remaining_seconds}s; gateway ${auth.gateway}; reported version ${account.gateway_version || "unavailable"} (local credential metadata only).`);
   return result;
 }
@@ -8038,6 +8306,8 @@ export function nextTinyPromptLines(result) {
   if (result.stage !== "qa") return lines;
   lines.push("");
   lines.push(`Next expected proof: browser QA + typed-card proof. Run: ${cmd("qa")} run --packet <packet> --base-url <url> --browser --test-order common`);
+  const bumpRun = (result.next_actions || []).find((action) => action?.id === "qa_run_bump");
+  if (bumpRun) lines.push(`That run never orders the checkout order bump. Prove the charged add-on with: ${bumpRun.command}`);
   lines.push("Localhost on any port is a Development domain (SDK allowed, analytics suppressed). Non-localhost origins still need SDK allowlist confirmation.");
   lines.push(`Build/polish done but no QA verdict yet is a Completeness Signal, not a build failure: ${cmd("findings")} add --stage qa --kind missing_prompt --summary "..."`);
   return lines;
@@ -8148,6 +8418,10 @@ export function resultTextLines(result, { headerLines = [] } = {}) {
     if (result.dry_run) lines.push(`Would write: ${result.would_write} (nothing was written)`);
     if (result.next_stage) lines.push(`Next stage: ${result.next_stage}${result.next_stage_reason ? ` (${result.next_stage_reason})` : ""}`);
   }
+  if (result.action === "checkpoint-accept") {
+    for (const accept of result.accepts || []) lines.push(`${result.dry_run ? "Would accept" : "Accepted"}: ${accept.result_ref} by ${accept.accepted_by}${accept.expires_at ? ` until ${accept.expires_at}` : ""}`);
+    if (result.dry_run) lines.push(`Would write: ${result.would_write} (nothing was written)`);
+  }
   if (result.action === "record") {
     lines.push(`${result.dry_run ? "Would record" : "Recorded"}: ${result.stage}`);
     for (const path of result.dry_run ? result.would_write : result.written) lines.push(`${result.dry_run ? "Would write" : "Wrote"}: ${path}${result.dry_run ? " (nothing was written)" : ""}`);
@@ -8189,6 +8463,8 @@ export function resultTextLines(result, { headerLines = [] } = {}) {
   // Directly under the findings they remediate, above the stage picker's
   // `Next:` block: the operator reads what is wrong, then what clears it.
   lines.push(...doctorRequiredActionLines(result));
+  // `next` only: the QC handoff, after the issues and before the stage picker.
+  if (result.qc_handoff) lines.push(...qcHandoffTextLines(result.qc_handoff));
   if (result.next) {
     lines.push("Next:");
     lines.push(`- ${result.next.stage || "unknown"} (${result.next.owner || result.next.default_skill || "owner unknown"})`);