@nextcommerce/campaigns-os 1.33.0

package/src/qa-node.mjs

@@ -0,0 +1,3620 @@
+import { expectedBinding, createBindingScriptLoader, observeBinding, bindingAssertion } from './qa-binding-evidence.mjs';
+import { shellToken } from "./shell-token.mjs";
+import { requiredActionText } from "./gate-actions.mjs";
+import { parseOrderPathDepthFlag } from "./proof-policy.mjs";
+import {
+  isAbsoluteHttpUrl,
+  normalizePageKitRoute,
+  normalizePublicRouteSlug,
+  resolveRouteRoot,
+  runtimeRelativeRouteForSpecValue,
+  stripPublicRoutePrefix,
+} from "./route-identity.mjs";
+import { singleLineFragment } from "./text-safety.mjs";
+import { absentOrMalformed } from "./fs-identity.mjs";
+import { DEFAULT_PROXY_BASE, fetchSpecByMapId } from "./spec-fetch.mjs";
+import { specMaterialHash } from "./spec-identity.mjs";
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { PLAYWRIGHT_INSTALL_HINT } from "./browser-launch.mjs";
+import { dirname, join, relative, resolve, isAbsolute } from "node:path";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { invocationPrefixFor } from "./install-mode.mjs";
+import { dirname as installModeDirname, resolve as installModeResolve } from "node:path";
+import { fileURLToPath as installModeFileUrl } from "node:url";
+const PACKAGE_ROOT = installModeResolve(installModeDirname(installModeFileUrl(import.meta.url)), "..");
+// Commands this module produces are spelled for the install they come from
+// (see install-mode.mjs), once, at the producer.
+function cmd(verb, rest = "") {
+  return `${invocationPrefixFor(PACKAGE_ROOT)} ${verb}${rest ? ` ${rest}` : ""}`;
+}
+import { runAnalyticsCorrectnessChecks, runAnalyticsParityChecks, runBrowserChecks, runBrowserTestOrders, testEmail, validatedOrderCreationLimit } from "./qa-browser.mjs";
+import { assessReceiptPurchase } from "./qa-analytics-correctness.mjs";
+import { createVerdict, isFindingAssertion, QA_ASSERTION_FAMILY_VOCABULARY, SESSION_ENDING_DISPOSITIONS, SEVERITY, STATUS, validateVerdict } from "./qa-verdict.mjs";
+import { normalizeSdkMetaName, lookupSdkIgnoredMetaTag } from "./sdk-meta-tags.mjs";
+import { annotateQaAssertionCauses, formatCauseReportLines, formatCauseTag } from "./finding-cause.mjs";
+import { promoteQaVerdict, writeQaSidecar } from "./qa-sidecar.mjs";
+import { publishQaVerdict, qaPortalUrl, qaVerdictPublishBlock, QA_VERDICT_PUBLISHERS, skippedQaVerdictPublish } from "./qa-verdict-publish.mjs";
+import { publishStoredVerdict, qaPublishTextLines, QA_PUBLISH_EXIT_CODES } from "./qa-publish.mjs";
+// Shared outgoing-edge resolver, so QA expectations and build-time wiring
+// cannot drift on which declared routing field wins.
+import {
+  acceptRouteTarget,
+  applicableForwardFields,
+  declineRouteTarget,
+  forwardRouteTarget,
+  inapplicableForwardFields,
+} from "../campaign-spec/dist/index.js";
+import { evaluateThemeGate } from "./theme-gate.mjs";
+import { probeRouteUrls, ROUTE_PROBE_DEFAULT_TIMEOUT_MS } from "./qa-route-probe.mjs";
+import { resolveCommerceCatalog, resolvePacketCommerceCatalogPath, resolveTemplateBrandContract } from "./private-template-source.mjs";
+import { computeBuildFingerprint, resolveBuiltSiteScope, topologiesFromBuiltSiteScope } from "./built-site-scope.mjs";
+import { evaluatePolishGate } from "./polish-gate.mjs";
+import { evaluateRecordedHiddenEagerMediaCheckpoint } from "./polish-node.mjs";
+import { HIDDEN_EAGER_MEDIA_SCOPE, POLISH_CAPTURE_PROBLEM_CODES } from "./polish-page-load.mjs";
+import {
+  normalizePageLoadRoute,
+  POLISH_PRELOAD_ATTRIBUTES,
+  redactCaptureUrl,
+} from "./polish-capture.mjs";
+import { resolveConsent } from "./consent.mjs";
+import { markDoctorSidecarStale } from "./doctor-sidecar.mjs";
+import { commitAssemblyReport } from "./stage-ledger.mjs";
+import { campaignSidecarPaths, explicitReportPath, resolveCampaignWorkspace, targetRepoFor } from "./campaign-workspace.mjs";
+import { loadParityFixture } from "./qa-parity-fixture.mjs";
+import { assessParityCapture, resolveParityScenario, runParityCapture } from "./qa-parity-capture.mjs";
+import { loadPageKitCampaignEntry, PAGE_KIT_CAMPAIGNS_REL_PATH } from "./page-kit-campaign-config.mjs";
+import {
+  evaluatePageKitStoreProfile,
+  PAGE_KIT_STORE_PROFILE_FIELDS,
+  PAGE_KIT_STORE_PROFILE_SCOPE,
+} from "./page-kit-store-profile.mjs";
+import {
+  evaluatePageKitSdkVersion,
+  PAGE_KIT_SDK_VERSION_SCOPE,
+} from "./page-kit-sdk-version.mjs";
+import {
+  captureCommercialClaims,
+  COMMERCIAL_QA_LIMITS,
+  mapConcurrent,
+  createPageSourceLoader,
+  planCommercialParity,
+  runCommercialParity,
+  unavailableCommercialCapture,
+  unavailableCommercialReport,
+} from "./qa-commercial-parity.mjs";
+
+// The producing runtime identity on every verdict. Read from package.json so
+// a verdict names the release that made it; a literal here outlived three
+// hundred releases as `0.1.0-alpha.0`.
+const RUNTIME = `campaigns-os-node-qa@${JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version}`;
+const QA_VERDICT_ASSERTION_LIMIT = 500;
+
+const HELP = `campaigns-os qa — Node/npm spec-aware QA
+
+Usage:
+  campaigns-os qa parity --fixture <parity-fixture.json> --scenario <scenario-id> [--base-url <override>] [--baseline <url>] [--parity-order-json <file>] [--no-post-verdict]
+  campaigns-os qa resolve --packet <campaign-runtime.build.json> [--base-url <url>] [--no-probe] [--probe-timeout-ms <ms>] [--json]
+  campaigns-os qa run --packet <campaign-runtime.build.json> [--base-url <url>] [--output-dir <dir>] [--no-remit] [--json]
+  campaigns-os qa policy set --packet <campaign-runtime.build.json> [--allowed-domains-confirmed true|false] [--deploy-target <target>] [--preview-url <url>] [--production-url <url>] [--order-path-depth <off|common|full>] [--json]
+  campaigns-os qa waive --packet <campaign-runtime.build.json> --assertion analytics-correctness:purchase-fires --reason "<why>" [--waived-by <who>] [--report <assembly-report.json>] [--json]
+  campaigns-os qa promote --packet <campaign-runtime.build.json> --verdict <full-verdict.json> [--json]   # project one explicit qa-output verdict to the committed .campaign-runtime/qa-verdict.json sidecar
+  campaigns-os qa publish --packet <campaign-runtime.build.json> [--verdict <full-verdict.json>] [--republish] [--proxy-base <url>] [--json]   # post an already-stored verdict to the QA portal; no re-run, no orders
+  campaigns-os qa resolve <map-id> --spec <campaign-spec.json> [--base-url <url>]
+  campaigns-os qa run <map-id> --spec <campaign-spec.json> --base-url <url>
+  campaigns-os qa run --site <page-kit-target-repo> --base-url <url> --family <family> [--slug <slug>] [--browser]   # L7: QA a built _site/ with no packet/spec
+  campaigns-os qa install-browser [--json]   # one-time: install the package-owned Playwright Chromium (same as npm run qa:install-browser from a checkout)
+
+Options:
+  --fixture <path>                Parity-capture fixture (required by qa parity).
+  --scenario <id|offer>           Fixture scenario_id or unique offer selector (required by qa parity).
+  --baseline <url>                Optional live analytics baseline for qa parity.
+  --parity-order-json <path>      Assessment-only saved order + analytics capture bundle; skips Playwright.
+  --packet <path>                 Read Map ID, local CampaignSpec, deploy URL, and QA metadata from a Build Packet.
+  --site <path>                   L7 non-packet QA: resolve scope (pages + funnel types) from a built page-kit _site/.
+                                  Requires --base-url and --family. No Map ID / CampaignSpec needed.
+  --spec <path>                   Local exported CampaignSpec JSON for the non-packet Map ID flow.
+                                  Packet QA always uses packet.spec.local_path and rejects this override.
+  --proxy-base <url>              Campaign Map proxy base for /api/spec, /api/price-preview, and verdict publishing.
+  --base-url <url>                Deployed campaign root. Packet deploy URL is used when omitted.
+                                  Commercial pages are checked automatically against /api/price-preview;
+                                  no commercial sidecar or extra catalog flag is required.
+                                  HTML/proxy bodies, parser work, claims, and scenarios are hard-bounded;
+                                  unavailable proof is recorded as incomplete rather than a guessed mismatch.
+  --no-probe                      qa resolve: skip the reachability probe of the derived entry URLs.
+                                  resolve probes them by default, because a route set derived from the
+                                  packet is not evidence that the deployment serves it: a dead route set
+                                  reports status routes_unresolved and names the first URL that failed.
+                                  Probing needs no flag to survive an offline run — a transport failure
+                                  degrades to status ready_unprobed rather than failing — so use this only
+                                  for hermetic runs that must make no outbound request at all.
+  --probe-timeout-ms <ms>         qa resolve: per-URL reachability probe timeout. Default: 5000.
+  --output-dir <path>             Local verdict directory. Default: qa-output under the packet's
+                                  target repo (assembly.target_repo, else the packet's directory);
+                                  qa-output under the current directory for packet-less runs.
+                                  qa publish reads the same directory when looking up the sidecar's run.
+  --post-verdict                  (default) Publish the verdict to the QA portal at
+                                  <proxy-base>/api/qa/verdicts and print the QA portal link.
+                                  Publishing is automatic; this flag is retained for clarity.
+  --no-post-verdict, --local-only Skip publishing; write only the local verdict copy (offline / dev / CI).
+                                  Publish it later, without a re-run, with qa publish.
+  --verdict <path>                qa promote / qa publish: the full verdict file under qa-output/. qa publish
+                                  defaults to the run the committed .campaign-runtime/qa-verdict.json names,
+                                  preferring that run's full verdict under <target-repo>/qa-output/ and falling
+                                  back to the projection itself. Refuses a verdict whose spec_hash no longer
+                                  matches the packet's spec (spec_hash_mismatch), one the portal already holds
+                                  per the Run Record (already_published), an untrusted one, or one for another
+                                  campaign. Exit 2 on a refusal, 1 on a failed post, 0 when published.
+  --republish                     qa publish: post a verdict its Run Record already records as published.
+  --no-remit                     When an ambient run session is active, write the local Run Record but skip Run Telemetry remit.
+  --auth-cookie <cookie>          Cookie header for protected previews.
+  --browser                       Run Playwright-rendered browser checks after static Node checks.
+                                  Requires one-time setup: campaigns-os qa install-browser
+                                  (npm run qa:install-browser from a checkout).
+  --headed                        Show the Playwright browser window when --browser is set.
+  --browser-width <px>            Browser viewport width. Default: 1440.
+  --browser-height <px>           Browser viewport height. Default: 1200.
+  --browser-timeout <ms>          Browser navigation timeout. Default: 30000.
+  --test-order <off|common|checkout|accept|decline|both|full|tiers[:checkout|common|full]|accept-decline[-accept...]>
+                                  Create Playwright typed-card test orders through the tested checkout page.
+                                  Test cards bypass the gateway and create no transactions, so no permission
+                                  flags or packet policy are needed — just pick a mode. Default mode (bare
+                                  --test-order, or "common") runs checkout, first-offer accept/decline, and a
+                                  deduplicated shortest real receipt path when needed (at most 4 orders). "full" walks
+                                  every actual terminal path; cycles, missing routes, and reachable nonterminals
+                                  block before browser launch. The default cap is 6; overflow names the exact raise.
+                                  "tiers" is spec-driven: one strict-selection order per selector tier the
+                                  CampaignSpec declares on the checkout page (order-bump rows marked
+                                  is_upsell are add-ons, never tiers), plus one coupon order per declared
+                                  offer code (checkout exit_intent / promo_code_input); "tiers:common" and
+                                  "tiers:full" cross every tier with those path shapes. --select-package
+                                  <ref[:qty],...> narrows a tiers run to the listed declared tiers;
+                                  --apply-coupon is incompatible (tiers derives coupons from the spec).
+                                  Requires one-time setup: campaigns-os qa install-browser
+                                  (npm run qa:install-browser from a checkout).
+  --max-test-orders <n>           Accidental-flood guard for planned browser order paths (not a permission gate). Default: 6.
+  --max-order-creations <n>       Hard bound on REAL order creations in this run, reserved before each submit
+                                  click. Default: the planned path count. A path whose failure is confirmed to
+                                  have created an order is inspected read-only, never resubmitted.
+  --allowed-domains-confirmed <bool>
+                                  qa policy set: persist non-localhost SDK-origin confirmation.
+                                  Localhost on any port is a global Development domain with analytics suppressed.
+  --preview-url <url>             qa policy set: persist packet deploy.preview_url.
+  --production-url <url>          qa policy set: persist packet deploy.production_url.
+  --deploy-target <target>        qa policy set: persist packet deploy.target.
+  --order-path-depth <depth>      qa policy set: persist packet qa.proof_policy.order_path_depth (off, common or full)
+                                  and refresh the assembly report's proof_policy mirror when one exists, so the
+                                  two never disagree. "off" declares an intentional no-order run: a
+                                  --test-order off pass then owes no purchase proof and next can reach done.
+  --step-timeout-ms <ms>          Typed-card test-order per-step timeout. Default: 45000.
+  --order-timeout-ms <ms>         Typed-card test-order per-path overall timeout. Default: 240000.
+  --theme-waive <reason>          Waive a blocked theme gate for this run with an explicit operator reason
+                                  (recorded in the verdict; downgrades template-residue blockers to warnings).
+  --test-card <number>            Test card number for browser checkout. Default: Discover sandbox card 6011...1117.
+  --test-cvv <cvv>                Test card CVV. Default: 123.
+  --test-exp-month <mm>           Test card expiration month. Default: 12.
+  --test-exp-year <yyyy>          Test card expiration year. Default: 2030.
+  --test-email <email>            Customer email for browser test orders. Env CAMPAIGNS_OS_QA_TEST_EMAIL is also recognized.
+  --test-email-prefix <prefix>    Legacy unique email prefix override.
+  --legacy-api-test-order <off|accept|decline|both>
+                                  Diagnostic-only direct Campaigns API order creation; bypasses deployed checkout.
+  --api-key <key>                 Campaigns API key for legacy direct API diagnostics. Env QA_CAMPAIGNS_API_KEY is also recognized.
+  --campaigns-api-base <url>      Campaigns API base URL for legacy direct API diagnostics. Env CAMPAIGNS_API_BASE is also recognized.
+  --cart <package-ref:qty,...>    Optional target cart/package selector for browser or legacy diagnostics.
+  --analytics-baseline <url>      Analytics-parity leg (opt-in): URL of the legacy funnel to diff against (e.g. the
+                                  legacy receipt/thank-you page). Launches a Playwright browser to capture the live
+                                  dataLayer + GTM/pixel tag-fires on both URLs and diffs them into parity assertions.
+                                  Requires one-time setup: campaigns-os qa install-browser
+                                  (npm run qa:install-browser from a checkout).
+  --analytics-candidate <url>     Analytics-PARITY leg only: explicit candidate receipt URL paired with the
+                                  --analytics-baseline legacy receipt (receipt-capture pairing). When omitted,
+                                  the parity candidate and correctness root-inventory phase capture the URL
+                                  resolved from campaign identity, never a raw --base-url. Correctness Purchase
+                                  proof reuses the canonical typed-card order's settled receipt capture.
+  --assertion <id>                qa waive: the blocking assertion to waive. The waiver lane is scoped to
+                                  analytics-correctness:purchase-fires — other assertions are refused.
+  --reason <text>                 qa waive: REQUIRED — why this blocker is acceptable for this campaign.
+                                  Recorded verbatim on the Assembly Report and carried into the verdict.
+  --waived-by <who>               qa waive: named human accepting the blocker. Default: $USER@local
+                                  (or "operator" when $USER is unset), matching themeWaive's default lane.
+  --report <path>                 qa waive: explicit Assembly Report path. Default: the packet target repo's
+                                  .campaign-runtime/assembly-report.json.
+  --analytics-settle <ms>         Settle time after analytics page loads and recognized typed-order receipts.
+                                  Receipt settling must fit inside the order deadline. Default: 5000.
+  --analytics-hosts <h1,h2,...>   Extra third-party host patterns to intercept for tag-fire capture (comma-separated).
+`;
+
+export async function runQaCli(args, { ambient = null } = {}) {
+  const subcommand = args._[1] || "help";
+  if (subcommand === "help" || args.help) {
+    console.log(HELP);
+    return null;
+  }
+  if (subcommand === "resolve") {
+    const resolved = await resolveQaInputs(args);
+    const routeProbe = await resolveRouteProbe(resolved, args);
+    const result = resolvePayload(resolved, { routeProbe });
+    output(result, args);
+    return result;
+  }
+  if (subcommand === "run") {
+    const result = await runQa(args, { runSessionActive: Boolean(ambient?.session?.run_id) });
+    output(result, args);
+    process.exitCode = result.verdict.disposition === "blocked" ? 4 : 0;
+    return result;
+  }
+  if (subcommand === "parity") {
+    const result = await runParityQa(args);
+    output(result, args);
+    process.exitCode = result.verdict.disposition === "blocked" ? 4 : 0;
+    return result;
+  }
+  if (subcommand === "policy") {
+    if (args._[2] !== "set") throw new Error(`Unknown qa policy command. Use: ${cmd("qa")} policy set --packet <campaign-runtime.build.json>`);
+    const result = updateQaPolicy(args);
+    output(result, args);
+    return result;
+  }
+  if (subcommand === "waive") {
+    const result = qaWaive(args);
+    output(result, args);
+    return result;
+  }
+  if (subcommand === "promote") {
+    const result = promoteQaVerdict({ verdictPath: args.verdict, packetPath: args.packet });
+    output(result, args);
+    return result;
+  }
+  if (subcommand === "publish") {
+    const result = await publishStoredVerdict(args);
+    output(result, args);
+    process.exitCode = QA_PUBLISH_EXIT_CODES[result.status] ?? 1;
+    return result;
+  }
+  if (subcommand === "install-browser") {
+    const result = installQaBrowser({ json: Boolean(args.json) });
+    if (args.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      for (const line of installBrowserTextLines(result)) console.log(line);
+    }
+    process.exitCode = result.ok ? 0 : 1;
+    return result;
+  }
+  throw new Error(`Unknown qa command: ${subcommand}`);
+}
+
+// The package-owned browser install, runnable from any install mode. It is
+// the same step as `npm run qa:install-browser` (a checkout script), but a
+// global or npx install has no checkout to run scripts in, and the printed
+// recovery commands must work where the operator actually is. It drives the
+// Playwright CLI bundled with THIS package so the browser matches the
+// Playwright version the QA and polish producers load.
+export function installBrowserTextLines(result) {
+  const lines = [`Status: ${String(result.status || "unknown").toUpperCase()}`];
+  if (result.command) lines.push(`Command: ${result.command}`);
+  if (Number.isInteger(result.exit_code) && !result.ok) lines.push(`Exit code: ${result.exit_code}`);
+  if (result.note) lines.push(result.note);
+  return lines;
+}
+
+export function installQaBrowser({ spawn = spawnSync, json = false } = {}) {
+  const require = createRequire(import.meta.url);
+  let playwrightCli;
+  try {
+    // playwright's exports map does not expose cli.js; its package.json is
+    // exported, and the CLI lives beside it (package.json "bin": "cli.js").
+    playwrightCli = join(dirname(require.resolve("playwright/package.json")), "cli.js");
+    if (!existsSync(playwrightCli)) throw Object.assign(new Error("playwright/cli.js is missing"), { code: "MODULE_NOT_FOUND" });
+  } catch (error) {
+    if (error?.code !== "MODULE_NOT_FOUND") throw error;
+    return {
+      ok: false,
+      status: "playwright_missing",
+      command: null,
+      note: PLAYWRIGHT_INSTALL_HINT,
+    };
+  }
+  // Playwright reports download progress on stdout. In --json mode stdout is
+  // the result document, so the child's stdout is routed to stderr (fd 2);
+  // otherwise the operator sees the progress inline.
+  const run = spawn(process.execPath, [playwrightCli, "install", "chromium"], {
+    stdio: json ? ["inherit", 2, "inherit"] : "inherit",
+  });
+  const ok = run.status === 0;
+  return {
+    ok,
+    status: ok ? "installed" : "install_failed",
+    command: `${process.execPath} ${playwrightCli} install chromium`,
+    exit_code: run.status,
+    note: ok
+      ? "Playwright Chromium is installed for this package; browser QA and polish capture can run."
+      : `Playwright browser install exited ${run.status}; rerun ${cmd("qa")} install-browser after fixing the reported error.`,
+  };
+}
+
+async function resolveQaInputs(args, {
+  readJsonFile = readJson,
+  loadCampaignEntry = loadPageKitCampaignEntry,
+} = {}) {
+  if (args.packet && args.spec) {
+    throw new Error("Packet QA does not accept --spec; it always uses packet.spec.local_path.");
+  }
+  // Non-packet mode (learnings L7): QA a `campaign-build`'d page-kit campaign
+  // that has only a built _site/ and a served URL — no Build Packet, no Map ID,
+  // no CampaignSpec. Scope (pages + funnel types) is resolved from the built
+  // output; the residue/placeholder/demo gates run against --family.
+  if ((args.site || args.built) && !args.packet) {
+    return resolveQaInputsFromSite(args);
+  }
+  const checkpointPreflight = args.packet
+    ? resolvePacketCheckpointPreflight(args, { readJsonFile, loadCampaignEntry })
+    : null;
+  if (checkpointPreflight && checkpointPreflight.specStatus !== "ok") {
+    return resolvedFromBlockedCheckpointPreflight(checkpointPreflight, args);
+  }
+  // Packet mode owns one immutable local snapshot: every checkpoint, runtime
+  // identity/topology decision, theme/polish gate, and QA waiver consumes the
+  // same packet, local spec, target campaign entry, and Assembly Report read by
+  // preflight. A later file generation must never authorize work that the
+  // checkpoint generation did not evaluate (or vice versa).
+  const packetPath = checkpointPreflight?.packetPath || (args.packet ? resolve(args.packet) : null);
+  const packet = checkpointPreflight?.packet || (packetPath ? readJsonFile(packetPath) : null);
+  const mapId = stringArg(args["map-id"])
+    || stringArg(args._[2])
+    || stringArg(packet?.spec?.map_id);
+  if (!mapId) throw new Error("QA requires a Map ID. Provide --packet or positional <map-id>.");
+
+  const proxyBase = stringArg(args["proxy-base"]) || DEFAULT_PROXY_BASE;
+  const inputBaseUrl = normalizeBaseUrl(stringArg(args["base-url"]) || packet?.deploy?.preview_url || packet?.deploy?.production_url || null);
+  const specPath = checkpointPreflight
+    ? checkpointPreflight.specPath
+    : args.spec
+      ? resolve(args.spec)
+      : packetPath && packet?.spec?.local_path
+        ? resolveFromFile(packetPath, packet.spec.local_path)
+        : null;
+
+  let rawSpec;
+  let specSource;
+  if (checkpointPreflight) {
+    rawSpec = checkpointPreflight.rawSpec;
+    specSource = specPath;
+  } else if (specPath) {
+    rawSpec = readJsonFile(specPath);
+    specSource = specPath;
+  } else {
+    rawSpec = await fetchSpecByMapId(mapId, { proxyBase });
+    specSource = `${proxyBase.replace(/\/+$/, "")}/api/spec/${encodeURIComponent(mapId)}`;
+  }
+
+  const normalized = normalizeSpec(rawSpec);
+  const publicRouteSlug = resolvePublicRouteSlug({ packet, spec: normalized, rawSpec });
+  const baseUrl = normalizeQaBaseUrl(inputBaseUrl, publicRouteSlug);
+  // Packet 01: the analytics legs capture ONE URL derived from resolved
+  // identity (public_route_slug + route_root), composed here where the raw
+  // operator/deploy base is still in hand.
+  const routeRootNotes = [];
+  const analyticsCaptureTarget = resolveAnalyticsCaptureTarget({
+    inputBaseUrl,
+    publicRouteSlug,
+    routeRoot: resolveCampaignRouteRoot({ packet, spec: normalized, rawSpec, publicRouteSlug, notes: routeRootNotes }),
+    routeRootNote: routeRootNotes[0] || null,
+  });
+  const specHash = computeSpecHash(rawSpec);
+  const templateFamily = stringArg(packet?.assembly?.template_family)
+    || stringArg(normalized?.spec_identity?.preferred_template_family)
+    || stringArg(normalized?.campaign?.preferred_template_family)
+    || null;
+  const commerceStructureContract = loadCommerceStructureContract({ packet, packetPath, templateFamily });
+  const topologies = extractTopologies(normalized, { baseUrl, publicRouteSlug, templateFamily, commerceStructureContract });
+  const themeGate = resolveThemeGate({
+    packetPath,
+    topologies,
+    waive: stringArg(args["theme-waive"]),
+    report: checkpointPreflight?.runtimeReport,
+  });
+  const hiddenEagerMediaGate = checkpointPreflight?.checkpointGates
+    ?.find((gate) => gate?.id === HIDDEN_EAGER_MEDIA_SCOPE);
+  const polishGate = resolvePolishGate({
+    packetPath,
+    report: checkpointPreflight?.runtimeReport,
+    hiddenEagerMediaGate,
+  });
+  const qaWaivers = resolveQaWaivers({ packetPath, report: checkpointPreflight?.runtimeReport });
+  const brandContract = loadBrandContract(templateFamily);
+  return {
+    themeGate,
+    polishGate,
+    qaWaivers,
+    analyticsCaptureTarget,
+    brandContract: brandContract.contract,
+    brandContractStatus: brandContract.status,
+    packetPath,
+    packet,
+    mapId,
+    publicRouteSlug,
+    proxyBase,
+    baseUrl,
+    specPath,
+    specSource,
+    // Portal-managed: the spec was fetched from the portal for this run, so
+    // the verdict belongs on the portal QA tab by default (#172).
+    portalManaged: specPath == null,
+    rawSpec,
+    spec: normalized,
+    specVersion: String(rawSpec.schema_version || rawSpec.schemaVersion || "unknown"),
+    specHash,
+    templateFamily,
+    commerceStructureContract,
+    topologies,
+    checkpointGates: checkpointPreflight?.checkpointGates || nonPacketCheckpointGates(),
+    // The report the checkpoint gates were evaluated on, and the target repo
+    // whose default it may or may not be: what the printed remediation names.
+    reportPath: checkpointPreflight?.reportPath || null,
+    targetRepo: checkpointPreflight?.targetRepo || null,
+  };
+}
+
+function resolvePacketCheckpointPreflight(args, {
+  readJsonFile = readJson,
+  loadCampaignEntry = loadPageKitCampaignEntry,
+} = {}) {
+  const packetPath = resolve(String(args.packet));
+  const packet = readJsonFile(packetPath);
+  const specPath = stringArg(args.spec)
+    ? resolve(String(args.spec))
+    : stringArg(packet?.spec?.local_path)
+      ? resolveFromFile(packetPath, packet.spec.local_path)
+      : null;
+  let rawSpec = null;
+  let specStatus = "missing";
+  if (specPath && existsSync(specPath)) {
+    try {
+      rawSpec = readJsonFile(specPath);
+      specStatus = isPlainObject(rawSpec) ? "ok" : "root_not_object";
+    } catch {
+      specStatus = "invalid_json";
+    }
+  }
+  const publicRouteSlug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
+  // Follows the Build Context's report_path, like `next` and the QA stage
+  // record: a `prepare-build --report-out` campaign's report is the bound one,
+  // not the default sidecar.
+  const { targetRepo, reportPath } = resolveCampaignWorkspace(packetPath, {
+    packet,
+    contextPath: stringArg(args.context) ? resolve(String(args.context)) : undefined,
+    reportPath: stringArg(args.report) ? resolve(String(args.report)) : undefined,
+    followContextPointer: true,
+  });
+  const targetLoad = loadCampaignEntry({ targetRepo, publicRouteSlug });
+  let report = null;
+  if (existsSync(reportPath)) {
+    try {
+      const loaded = readJsonFile(reportPath);
+      report = isPlainObject(loaded) ? loaded : null;
+    } catch {
+      report = null;
+    }
+  }
+  const checkpointGates = [
+    evaluatePageKitStoreProfile({
+      specCampaign: rawSpec?.campaign || null,
+      specStatus,
+      targetLoad,
+      waivers: report?.waivers,
+      required: true,
+    }),
+    evaluatePageKitSdkVersion({
+      spec: rawSpec,
+      specStatus,
+      targetLoad,
+      waivers: report?.waivers,
+      required: true,
+    }),
+    evaluateRecordedHiddenEagerMediaCheckpoint({ packet, report }),
+  ];
+  const runtimeReport = reportMatchesPacketIdentity(report, packet) ? report : null;
+  return {
+    packetPath,
+    packet,
+    specPath,
+    rawSpec,
+    specStatus,
+    targetLoad,
+    targetRepo,
+    reportPath,
+    report,
+    runtimeReport,
+    checkpointGates,
+  };
+}
+
+function reportMatchesPacketIdentity(report, packet) {
+  if (!isPlainObject(report) || !isPlainObject(report.identity)) return false;
+  const packetMapId = stringArg(packet?.spec?.map_id);
+  const reportMapId = stringArg(report.identity.map_id);
+  const packetSlug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
+  const reportSlug = normalizePublicRouteSlug(report.identity.public_route_slug);
+  return !!packetMapId
+    && packetMapId === reportMapId
+    && !!packetSlug
+    && packetSlug === reportSlug;
+}
+
+function nonPacketStoreProfileGate(slug = "") {
+  const gate = evaluatePageKitStoreProfile({
+    specCampaign: {},
+    targetLoad: {
+      status: "file_missing",
+      public_route_slug: normalizePublicRouteSlug(slug),
+      target_path: PAGE_KIT_CAMPAIGNS_REL_PATH,
+      entry: null,
+    },
+    required: false,
+  });
+  return {
+    ...gate,
+    code: "page_kit.store_profile.not_applicable",
+    reason: "Non-packet QA has no Build Packet target/config pair; Store Profile parity is not applicable.",
+  };
+}
+
+function nonPacketSdkVersionGate(slug = "") {
+  const gate = evaluatePageKitSdkVersion({
+    spec: { runtime: { sdk_version: "0.0.0" } },
+    targetLoad: {
+      status: "file_missing",
+      public_route_slug: normalizePublicRouteSlug(slug),
+      target_path: PAGE_KIT_CAMPAIGNS_REL_PATH,
+      entry: null,
+    },
+    required: false,
+  });
+  return {
+    ...gate,
+    code: "page_kit.sdk_version.not_applicable",
+    reason: "Non-packet QA has no Build Packet spec/target pair; SDK-pin parity is not applicable.",
+    expected_sdk_version: null,
+    observed_sdk_version: null,
+    expected_source: null,
+  };
+}
+
+function nonPacketCheckpointGates(slug = "") {
+  const hiddenGate = evaluateRecordedHiddenEagerMediaCheckpoint();
+  return [
+    nonPacketStoreProfileGate(slug),
+    nonPacketSdkVersionGate(slug),
+    {
+      ...hiddenGate,
+      reason: "Non-packet QA has no Build Packet and Assembly Report pair; recorded page-load evidence is not applicable.",
+    },
+  ];
+}
+
+function resolvedFromBlockedCheckpointPreflight(preflight, args) {
+  const rawSpec = isPlainObject(preflight.rawSpec) ? preflight.rawSpec : {};
+  const spec = normalizeSpec(rawSpec);
+  const publicRouteSlug = normalizePublicRouteSlug(preflight.packet?.campaign?.public_route_slug) || null;
+  const inputBaseUrl = normalizeBaseUrl(stringArg(args["base-url"])
+    || preflight.packet?.deploy?.preview_url
+    || preflight.packet?.deploy?.production_url
+    || null);
+  const topologies = [];
+  const themeGate = resolveThemeGate({
+    packetPath: preflight.packetPath,
+    topologies,
+    waive: stringArg(args["theme-waive"]),
+    report: preflight.runtimeReport,
+  });
+  const hiddenEagerMediaGate = preflight.checkpointGates
+    .find((gate) => gate?.id === HIDDEN_EAGER_MEDIA_SCOPE);
+  const polishGate = resolvePolishGate({
+    packetPath: preflight.packetPath,
+    report: preflight.runtimeReport,
+    hiddenEagerMediaGate,
+  });
+  return {
+    themeGate,
+    polishGate,
+    qaWaivers: resolveQaWaivers({ packetPath: preflight.packetPath, report: preflight.runtimeReport }),
+    analyticsCaptureTarget: { url: null, source: "unresolved" },
+    brandContract: null,
+    brandContractStatus: "not_evaluated",
+    packetPath: preflight.packetPath,
+    packet: preflight.packet,
+    mapId: stringArg(preflight.packet?.spec?.map_id) || "unknown-map",
+    publicRouteSlug,
+    proxyBase: stringArg(args["proxy-base"]) || DEFAULT_PROXY_BASE,
+    baseUrl: inputBaseUrl,
+    specPath: preflight.specPath,
+    specSource: `packet_local_${preflight.specStatus}`,
+    portalManaged: false,
+    rawSpec,
+    spec,
+    specVersion: String(rawSpec.schema_version || rawSpec.schemaVersion || "unavailable"),
+    specHash: computeSpecHash(rawSpec),
+    templateFamily: stringArg(preflight.packet?.assembly?.template_family) || null,
+    commerceStructureContract: null,
+    topologies,
+    checkpointGates: preflight.checkpointGates,
+    reportPath: preflight.reportPath || null,
+    targetRepo: preflight.targetRepo || null,
+  };
+}
+
+// L7 non-packet QA: resolve QA inputs from a built _site/ + served base URL,
+// with no Build Packet / Map ID / CampaignSpec. The theme gate is evaluated
+// from the derived topology scope alone (no theme artifacts exist), which
+// yields "not_applicable" rather than blocking, so browser QA still runs the
+// residue/placeholder/demo gates. Test orders are not attempted (no policy).
+export function resolveQaInputsFromSite(args) {
+  const targetRepo = resolve(String(args.site || args.built));
+  const scope = resolveBuiltSiteScope(targetRepo, { slug: stringArg(args.slug) });
+  if (!scope.ok) {
+    throw new Error(scope.error || `Could not resolve a built campaign from ${targetRepo}.`);
+  }
+  const baseUrl = normalizeBaseUrl(stringArg(args["base-url"]));
+  if (!baseUrl) {
+    throw new Error("Non-packet site QA requires --base-url <served-campaign-root> so built pages have a fetchable URL.");
+  }
+  const templateFamily = stringArg(args.family);
+  if (!templateFamily) {
+    throw new Error("Non-packet site QA requires --family <template-family> so residue, placeholder, and demo-asset gates can load the family brand contract.");
+  }
+  const brandContract = loadBrandContract(templateFamily);
+  if (brandContract.status !== "loaded" || !brandContract.contract) {
+    throw new Error(`Non-packet site QA requires a loadable template brand contract for --family "${templateFamily}" (got ${brandContract.status}).`);
+  }
+  const topologies = topologiesFromBuiltSiteScope(scope, baseUrl);
+  const mapId = stringArg(args["map-id"]) || scope.slug || "local-site";
+  const themeGate = resolveThemeGate({ packetPath: null, topologies, waive: stringArg(args["theme-waive"]) });
+  const polishGate = { status: "not_applicable", code: "polish.not_applicable", reason: "Non-packet built-site QA has no Assembly Report polish gate." };
+  // Include family + target_repo so two built sites with the same slug/route
+  // structure but different families or locations do not hash identically
+  // (run-identity dedupe / idempotent remit must tell them apart).
+  const specHash = computeSpecHash({
+    built_site: scope.slug,
+    family: templateFamily || null,
+    target_repo: scope.campaign_dir,
+    pages: scope.pages.map((page) => `${page.page_type}:${page.route}`),
+  });
+  return {
+    themeGate,
+    polishGate,
+    // Non-packet site QA has no Assembly Report, so no recorded waivers.
+    qaWaivers: {},
+    // Non-packet site QA: --base-url IS the served campaign root by this
+    // mode's contract (no spec identity exists to compose from).
+    analyticsCaptureTarget: buildAnalyticsCaptureTarget({
+      url: ensureUrlTrailingSlash(baseUrl),
+      publicRouteSlug: scope.slug || null,
+      routeRoot: null,
+      source: "built_site_base_url",
+    }),
+    brandContract: brandContract.contract,
+    brandContractStatus: brandContract.status,
+    packetPath: null,
+    packet: null,
+    mapId,
+    proxyBase: DEFAULT_PROXY_BASE,
+    baseUrl,
+    specPath: null,
+    specSource: `built-site:${scope.campaign_dir}`,
+    rawSpec: {},
+    spec: { campaign: {} },
+    specVersion: "built-site",
+    specHash,
+    templateFamily,
+    commerceStructureContract: null,
+    topologies,
+    checkpointGates: nonPacketCheckpointGates(scope.slug),
+    builtSite: { slug: scope.slug, campaign_dir: scope.campaign_dir, html_count: scope.html_count },
+  };
+}
+
+function loadCommerceStructureContract({ packet, packetPath, templateFamily }) {
+  if (!packet || !packetPath || !templateFamily) return null;
+  // A null path is the toolkit's own catalog; a recorded path that is dead
+  // here but names the catalog file also falls back to it (see
+  // resolvePacketCommerceCatalogPath).
+  const catalogResolution = resolvePacketCommerceCatalogPath(packetPath, packet.assembly?.commerce_catalog);
+  const catalogPathValue = catalogResolution.recorded;
+  const catalogPath = catalogResolution.path;
+  if (!catalogPath || !existsSync(catalogPath)) return { family: templateFamily, status: "missing_catalog", pages: {} };
+  try {
+    const catalog = resolveCommerceCatalog(catalogPath);
+    const qaStructure = catalog?.families?.[templateFamily]?.agentContract?.qaStructure;
+    return {
+      family: templateFamily,
+      status: qaStructure && typeof qaStructure === "object" ? "loaded" : "missing_family_qa_structure",
+      pages: qaStructure && typeof qaStructure === "object" ? qaStructure : {},
+      catalog_path: catalogPathValue,
+    };
+  } catch (error) {
+    return {
+      family: templateFamily,
+      status: "catalog_parse_error",
+      pages: {},
+      catalog_path: catalogPathValue,
+      error: serializeThrownValue(error),
+    };
+  }
+}
+
+// Theme gate pre-flight: the deterministic stage gate QA shares with doctor/next.
+// Packet QA supplies the canonical Assembly Report snapshot from checkpoint
+// preflight; build-context and doctor-output remain separate sidecar reads. When
+// doctor output is missing, commerce scope comes from the spec topologies in hand.
+function resolveThemeGate({ packetPath, topologies, waive, report: reportOverride = undefined }) {
+  const report = reportOverride === undefined
+    ? loadRuntimeArtifact(packetPath, "assembly-report.json")
+    : reportOverride;
+  const context = loadRuntimeArtifact(packetPath, "build-context.json");
+  const doctor = loadRuntimeArtifact(packetPath, "doctor-output.json");
+  const specScope = themeGateScopeFromTopologies(topologies);
+  const scope = mergeThemeGateScope(doctor?.derived?.scope || null, specScope);
+  const gate = evaluateThemeGate({
+    reportTheme: report?.theme || null,
+    contextTheme: context?.theme || null,
+    scope,
+    packetPath,
+    waive: waive || null,
+  });
+  // Audit the scope source: a direct `qa run` without a prior doctor run is a
+  // legitimate CI path, but its commerce-page scope comes from spec
+  // topologies rather than the doctor's richer derived scope. Make that
+  // visible in the gate (and therefore in the verdict) instead of deciding
+  // from an unstated source.
+  gate.scope_source = themeGateScopeSource(doctor?.derived?.scope || null, specScope);
+  return gate;
+}
+
+// The declared funnel is the authority on WHETHER a campaign ships commerce
+// pages; the doctor's derived scope is the authority on what this build
+// produced. Preferring the doctor's scope outright meant a thin one — a
+// partial build, or a doctor-output.json written before the commerce pages
+// existed — could retire the gate on a funnel whose own route listing, printed
+// two lines above, enumerated a checkout and five upsells (#274). Union the two
+// so a commerce page declared in either source keeps the gate live, and record
+// which sources contributed rather than deciding from an unstated one.
+function mergeThemeGateScope(doctorScope, specScope) {
+  if (!doctorScope) return specScope;
+  const pageKey = (page) => String(page?.page_id || page?.route || page?.type || "");
+  const known = new Set([
+    ...(Array.isArray(doctorScope.built_pages) ? doctorScope.built_pages : []),
+    ...(Array.isArray(doctorScope.out_of_scope_pages) ? doctorScope.out_of_scope_pages : []),
+  ].map(pageKey));
+  const missing = (specScope?.built_pages || []).filter((page) => !known.has(pageKey(page)));
+  if (!missing.length) return doctorScope;
+  return {
+    ...doctorScope,
+    built_pages: [...(Array.isArray(doctorScope.built_pages) ? doctorScope.built_pages : []), ...missing],
+  };
+}
+
+function themeGateScopeSource(doctorScope, specScope) {
+  if (!doctorScope) return "spec_topologies";
+  const merged = mergeThemeGateScope(doctorScope, specScope);
+  return merged === doctorScope ? "doctor_derived_scope" : "doctor_derived_scope+spec_topologies";
+}
+
+// The sidecars live where the producers write them — under the target repo,
+// with the report the Build Context binds — never merely beside the packet. A
+// packet that cannot be read at this moment costs the target-repo resolution,
+// not the read: the workspace then falls back to the packet's directory, which
+// is what this reader always used.
+// A missing or malformed packet or artifact is absent (null); any other read
+// failure is not and reaches the caller.
+function loadRuntimeArtifact(packetPath, name) {
+  if (!packetPath) return null;
+  try {
+    let packet = null;
+    try {
+      packet = readJson(packetPath);
+    } catch (error) {
+      if (!absentOrMalformed(error)) throw error;
+    }
+
+    const workspace = resolveCampaignWorkspace(packetPath, { packet, followContextPointer: true });
+    const path = {
+      "assembly-report.json": workspace.reportPath,
+      "build-context.json": workspace.contextPath,
+      "doctor-output.json": workspace.doctorOutPath,
+    }[name];
+    if (!path || !existsSync(path)) return null;
+    return readJson(path);
+  } catch (error) {
+    if (absentOrMalformed(error)) return null;
+    throw error;
+  }
+}
+
+// The fingerprint of the built output on disk right now (null when the packet
+// or the built route root cannot be resolved), so the polish gate binds QA to
+// the output QA is about to test rather than to the string build recorded.
+function currentBuiltOutputFingerprint(packetPath) {
+  if (!packetPath) return null;
+  try {
+    const packet = readJson(packetPath);
+    const slug = stringArg(packet?.campaign?.public_route_slug);
+    if (!slug) return null;
+    const current = computeBuildFingerprint(join(targetRepoFor(packetPath, packet), "_site", slug));
+    return current.ok ? current.fingerprint : null;
+  } catch (error) {
+    if (absentOrMalformed(error)) return null;
+    throw error;
+  }
+}
+
+function resolvePolishGate({
+  packetPath,
+  report: reportOverride = undefined,
+  hiddenEagerMediaGate = undefined,
+}) {
+  const report = reportOverride === undefined
+    ? loadRuntimeArtifact(packetPath, "assembly-report.json")
+    : reportOverride;
+  const gate = evaluatePolishGate({
+    report,
+    required: true,
+    hiddenEagerMediaGate,
+    currentOutputFingerprint: currentBuiltOutputFingerprint(packetPath),
+  });
+  gate.scope_source = report ? "assembly_report" : "missing_assembly_report";
+  return gate;
+}
+
+const THEME_GATE_COMMERCE_TYPES = new Set(["checkout", "upsell", "downsell", "receipt", "thankyou"]);
+
+function themeGateScopeFromTopologies(topologies = []) {
+  const built_pages = [];
+  for (const topology of topologies) {
+    for (const page of topology?.pages || []) {
+      const type = String(page?.page_type || "").toLowerCase();
+      if (!THEME_GATE_COMMERCE_TYPES.has(type)) continue;
+      built_pages.push({ page_id: page.page_id, type, role: "runtime" });
+    }
+  }
+  return { built_pages };
+}
+
+function loadBrandContract(templateFamily) {
+  if (!templateFamily) return { contract: null, status: "no_template_family" };
+  try {
+    const contract = resolveTemplateBrandContract(templateFamily);
+    return { contract, status: contract ? "loaded" : "none" };
+  } catch (error) {
+    return { contract: null, status: `error: ${error instanceof Error ? error.message : String(error)}` };
+  }
+}
+
+// Map a theme gate result to its verdict assertion. Blocked gates produce the
+// single blocker assertion the verdict carries; every other status produces an
+// audit-trail pass assertion so the gate decision is visible in the verdict.
+function themeGateAssertion(gate) {
+  const page = { page_id: "campaign" };
+  if (gate.status === "blocked") {
+    return assertion({
+      id: gate.code,
+      family: "theme_gate",
+      page,
+      status: STATUS.FAIL,
+      severity: SEVERITY.BLOCKER,
+      expected: "brand layer applied to commerce pages, or an explicit operator waiver",
+      actual: gate.reason,
+      evidence: {
+        reason: gate.reason,
+        commerce_pages: gate.commerce_pages,
+        required_actions: gate.required_actions,
+        scope_source: gate.scope_source || null,
+      },
+    });
+  }
+  if (gate.status === "waived") {
+    return assertion({
+      id: gate.code,
+      family: "theme_gate",
+      page,
+      status: STATUS.PASS,
+      expected: "brand layer applied to commerce pages, or an explicit operator waiver",
+      actual: gate.reason,
+      evidence: { waiver: gate.waiver, commerce_pages: gate.commerce_pages, scope_source: gate.scope_source || null },
+    });
+  }
+  return assertion({
+    id: gate.code,
+    family: "theme_gate",
+    page,
+    status: STATUS.PASS,
+    expected: "theme gate pass or not applicable",
+    actual: gate.reason,
+    evidence: { code: gate.code, commerce_pages: gate.commerce_pages, scope_source: gate.scope_source || null },
+  });
+}
+
+function polishGateAssertion(gate) {
+  const page = { page_id: "campaign" };
+  const evidence = {
+    build_fingerprint: gate.build_fingerprint || null,
+    source_build_fingerprint: gate.source_build_fingerprint || null,
+    source_package_material_fingerprint: gate.source_package_material_fingerprint || null,
+    current_source_package_material_fingerprint: gate.current_source_package_material_fingerprint || null,
+    assembly_source_package_material_fingerprint: gate.assembly_source_package_material_fingerprint || null,
+    performed_by: gate.performed_by || null,
+    waiver: gate.waiver || null,
+    expired_waiver: gate.expired_waiver || null,
+    scope_source: gate.scope_source || null,
+  };
+  if (gate.status === "blocked") {
+    return assertion({
+      id: gate.code,
+      family: "polish_gate",
+      page,
+      status: STATUS.FAIL,
+      severity: SEVERITY.BLOCKER,
+      expected: "current structured Polish evidence produced by next-campaigns-polish",
+      actual: gate.reason,
+      // blocked carries the same evidence as pass/waived, plus reason/problems/actions
+      evidence: {
+        ...evidence,
+        reason: gate.reason,
+        problems: gate.problems || [],
+        required_actions: gate.required_actions || [],
+      },
+    });
+  }
+  if (gate.status === "not_applicable") {
+    return assertion({
+      id: gate.code,
+      family: "polish_gate",
+      page,
+      status: STATUS.SKIPPED,
+      expected: "Polish gate evaluated only when an assembly report is available after build completion",
+      actual: gate.reason,
+      evidence,
+    });
+  }
+  if (gate.status === "waived") {
+    return assertion({
+      id: gate.code,
+      family: "polish_gate",
+      page,
+      status: STATUS.SKIPPED,
+      expected: "current structured Polish evidence with an explicit source-freshness waiver",
+      actual: gate.reason,
+      evidence,
+    });
+  }
+  return assertion({
+    id: gate.code,
+    family: "polish_gate",
+    page,
+    status: STATUS.PASS,
+    expected: "current structured Polish evidence produced by next-campaigns-polish, with any source-freshness exception explicitly waived",
+    actual: gate.reason,
+    evidence,
+  });
+}
+
+// Template-residue findings stay blockers while the gate is live; a waived (or
+// inapplicable) gate means the operator accepted the starter palette, so the
+// same findings downgrade to warnings rather than re-blocking the run.
+function residueSeverityForThemeGate(status) {
+  return status === "waived" || status === "not_applicable" ? SEVERITY.WARN : SEVERITY.BLOCKER;
+}
+
+function templateBrandContractAssertion(resolved) {
+  const family = stringArg(resolved?.templateFamily);
+  if (!family) return null;
+  const page = { page_id: "campaign" };
+  if (family === "undecided" || family === "custom") {
+    return assertion({
+      id: `template-brand-contract:${family}`,
+      family: "template_residue",
+      page,
+      status: STATUS.SKIPPED,
+      expected: "selected template family has a brand/residue/pricing contract, or is intentionally exempt",
+      actual: `family is ${family}; brand/residue/pricing contract not asserted`,
+      evidence: { template_family: family, reason: "doctor exempts undecided/custom template families" },
+    });
+  }
+  if (resolved.brandContractStatus === "loaded") {
+    return assertion({
+      id: `template-brand-contract:${family}`,
+      family: "template_residue",
+      page,
+      status: STATUS.PASS,
+      expected: "selected template family has a brand/residue/pricing contract",
+      actual: `loaded for ${family}`,
+      evidence: { template_family: family },
+    });
+  }
+  return assertion({
+    id: `template-brand-contract:${family}`,
+    family: "template_residue",
+    page,
+    status: STATUS.FAIL,
+    severity: SEVERITY.BLOCKER,
+    expected: "selected template family has a brand/residue/pricing contract",
+    actual: resolved.brandContractStatus || "none",
+    evidence: {
+      template_family: family,
+      next_step: `Add contracts/template-brand-contract.${family}.v0.json before treating this family as promoted/agent-ready.`,
+    },
+  });
+}
+
+function supportedPaymentMethodsFromSpec(spec) {
+  const campaign = spec?.campaign || {};
+  const normalizeMethod = (method) =>
+    String(method && typeof method === "object" ? method.code : method).toLowerCase().replace(/[\s-]+/g, "_");
+  const declared = [
+    ...(Array.isArray(campaign.available_payment_methods) ? campaign.available_payment_methods : []),
+    ...(Array.isArray(campaign.available_express_payment_methods) ? campaign.available_express_payment_methods : []),
+  ].map(normalizeMethod).filter(Boolean);
+  // null means the spec does not declare its methods (unknown != empty); chrome
+  // residue checks only run against an explicit declaration, like doctor R2-B5.
+  return declared.length ? [...new Set(declared)] : null;
+}
+
+function themeGateSummary(gate) {
+  return {
+    status: gate.status,
+    code: gate.code,
+    reason: gate.reason,
+    ...(gate.waiver ? { waiver: gate.waiver } : {}),
+    ...(gate.required_actions?.length ? { required_actions: gate.required_actions } : {}),
+  };
+}
+
+function polishGateSummary(gate) {
+  return {
+    status: gate.status,
+    code: gate.code,
+    reason: gate.reason,
+    ...(gate.waiver ? { waiver: gate.waiver } : {}),
+    ...(gate.required_actions?.length ? { required_actions: gate.required_actions } : {}),
+  };
+}
+
+function polishBlockedAssertions(polishGate, themeGate) {
+  const skippedByGate = (family, id) => assertion({
+    id,
+    family,
+    page: { page_id: "campaign" },
+    status: STATUS.SKIPPED,
+    expected: `${family} checks executed`,
+    actual: "Skipped: polish gate is blocked; no browser or test-order checks ran.",
+    evidence: { blocked_by: polishGate.code },
+  });
+  return [
+    ...(polishGate?.owned_checkpoint_only ? [] : [polishGateAssertion(polishGate)]),
+    themeGateAssertion(themeGate),
+    ...GATE_SUPPRESSED_FAMILIES
+      .filter((family) => family !== "polish_gate")
+      .map((family) => skippedByGate(family, `${family}.blocked_by_polish_gate`)),
+  ];
+}
+
+function themeBlockedAssertions(themeGate, polishGate) {
+  const skippedByGate = (family, id) => assertion({
+    id,
+    family,
+    page: { page_id: "campaign" },
+    status: STATUS.SKIPPED,
+    expected: `${family} checks executed`,
+    actual: "Skipped: theme gate is blocked; no browser or test-order checks ran.",
+    evidence: { blocked_by: themeGate.code },
+  });
+  return [
+    ...(polishGate?.owned_checkpoint_only ? [] : [polishGateAssertion(polishGate)]),
+    themeGateAssertion(themeGate),
+    ...GATE_SUPPRESSED_FAMILIES
+      .filter((family) => family !== "polish_gate")
+      .map((family) => skippedByGate(family, `${family}.blocked_by_gate`)),
+  ];
+}
+
+const HIDDEN_EAGER_MEDIA_VIEWPORTS = new Set(["desktop", "mobile"]);
+const HIDDEN_EAGER_MEDIA_PRELOAD_ATTRIBUTES = new Set(POLISH_PRELOAD_ATTRIBUTES);
+const HIDDEN_EAGER_MEDIA_HIDDEN_BY = new Set([
+  "display_none",
+  "visibility_collapse",
+  "visibility_hidden",
+]);
+const MAX_HIDDEN_EAGER_MEDIA_SUMMARY_RESOURCES = 64;
+
+function safeNonnegativeInteger(value) {
+  return Number.isInteger(value) && value >= 0 ? value : null;
+}
+
+function hiddenEagerMediaSubject(subject) {
+  const fingerprint = stringArg(subject?.build_fingerprint);
+  const slug = stringArg(subject?.campaign_slug);
+  const routeScope = stringArg(subject?.route_scope)?.toLowerCase();
+  const routes = [...new Set((Array.isArray(subject?.routes) ? subject.routes : [])
+    .map(normalizePageLoadRoute)
+    .filter(Boolean))].sort();
+  const viewports = [...new Set((Array.isArray(subject?.viewports) ? subject.viewports : [])
+    .map((viewport) => stringArg(viewport)?.toLowerCase())
+    .filter((viewport) => HIDDEN_EAGER_MEDIA_VIEWPORTS.has(viewport)))].sort();
+  return {
+    build_fingerprint: /^sha256:[a-f0-9]{64}$/.test(fingerprint || "") ? fingerprint : null,
+    campaign_slug: /^[a-z0-9][a-z0-9_-]{0,127}$/i.test(slug || "") ? slug : null,
+    route_scope: routeScope === "all" || routeScope === "selected" ? routeScope : null,
+    routes,
+    viewports,
+  };
+}
+
+function hiddenEagerMediaFinding(finding) {
+  const route = normalizePageLoadRoute(finding?.route);
+  const viewport = stringArg(finding?.viewport)?.toLowerCase();
+  const tagName = stringArg(finding?.tag_name)?.toLowerCase();
+  const preload = stringArg(finding?.preload_attribute)?.toLowerCase();
+  const allSources = [...new Set((Array.isArray(finding?.sources) ? finding.sources : [])
+    .map((source) => redactCaptureUrl(source))
+    .filter((source) => typeof source === "string" && /^https?:\/\//.test(source)))].sort();
+  const allResourceIds = [...new Set((Array.isArray(finding?.resource_ids) ? finding.resource_ids : [])
+    .filter((resourceId) => /^sha256:[a-f0-9]{64}$/.test(resourceId)))].sort();
+  return {
+    code: finding?.code === HIDDEN_EAGER_MEDIA_SCOPE ? HIDDEN_EAGER_MEDIA_SCOPE : null,
+    route,
+    viewport: HIDDEN_EAGER_MEDIA_VIEWPORTS.has(viewport) ? viewport : null,
+    tag_name: tagName === "video" || tagName === "audio" ? tagName : null,
+    element_index: safeNonnegativeInteger(finding?.element_index),
+    sources: allSources.slice(0, MAX_HIDDEN_EAGER_MEDIA_SUMMARY_RESOURCES),
+    source_count: Math.max(allSources.length, safeNonnegativeInteger(finding?.source_count) || 0),
+    resource_ids: allResourceIds.slice(0, MAX_HIDDEN_EAGER_MEDIA_SUMMARY_RESOURCES),
+    resource_id_count: Math.max(allResourceIds.length, safeNonnegativeInteger(finding?.resource_id_count) || 0),
+    resource_identity_fingerprint: /^sha256:[a-f0-9]{64}$/.test(finding?.resource_identity_fingerprint || "")
+      ? finding.resource_identity_fingerprint
+      : null,
+    transferred_bytes: safeNonnegativeInteger(finding?.transferred_bytes),
+    threshold_bytes: safeNonnegativeInteger(finding?.threshold_bytes),
+    preload_attribute: HIDDEN_EAGER_MEDIA_PRELOAD_ATTRIBUTES.has(preload) ? preload : "other",
+    hidden_by: [...new Set((Array.isArray(finding?.hidden_by) ? finding.hidden_by : [])
+      .filter((kind) => HIDDEN_EAGER_MEDIA_HIDDEN_BY.has(kind)))].sort(),
+  };
+}
+
+function hiddenEagerMediaFindings(gate) {
+  const findings = Array.isArray(gate?.state?.findings)
+    ? gate.state.findings
+    : Array.isArray(gate?.findings)
+      ? gate.findings
+      : [];
+  return findings
+    .filter(isPlainObject)
+    .map(hiddenEagerMediaFinding)
+    .sort((left, right) => String(left.route).localeCompare(String(right.route))
+      || String(left.viewport).localeCompare(String(right.viewport))
+      || (left.element_index ?? -1) - (right.element_index ?? -1));
+}
+
+const HIDDEN_EAGER_MEDIA_PROBLEM_CODES = new Set(POLISH_CAPTURE_PROBLEM_CODES);
+// planPolishCapture allows 128 routes; two viewports per route is the full
+// supported matrix, so a run inside the limits never truncates. The cap is
+// applied once across all four cell lists together; anything past it, and
+// any record that does not conform to the closed vocabularies, is counted
+// per list, never dropped silently.
+const MAX_HIDDEN_EAGER_MEDIA_MEASUREMENT_CELLS = 256;
+const HIDDEN_EAGER_MEDIA_MEASUREMENT_LISTS = Object.freeze(["missing", "duplicate", "unexpected", "incomplete"]);
+
+// A cell is kept only when it conforms: a path-only route and a viewport
+// from the closed vocabulary. Anything else is omitted and counted.
+function hiddenEagerMediaMeasurementCell(cell, { withProblemCodes = false } = {}) {
+  if (!isPlainObject(cell)) return null;
+  const route = normalizePageLoadRoute(cell.route);
+  const viewport = stringArg(cell.viewport)?.toLowerCase();
+  if (!route || !HIDDEN_EAGER_MEDIA_VIEWPORTS.has(viewport)) return null;
+  const projected = { route, viewport };
+  if (withProblemCodes) {
+    projected.problem_codes = [...new Set((Array.isArray(cell.problem_codes) ? cell.problem_codes : [])
+      .filter((code) => HIDDEN_EAGER_MEDIA_PROBLEM_CODES.has(code)))].sort();
+  }
+  return projected;
+}
+
+// The per-route, per-viewport measurement a blocked checkpoint carries: which
+// cells are missing, duplicated, unexpected, or incomplete and on which
+// problem codes. Routes are path-only, viewports and codes come from the
+// closed vocabularies, so nothing here can carry a URL or an operator string.
+// Counts are integers (0 when the input carries none).
+function hiddenEagerMediaMeasurement(gate) {
+  const measurement = gate?.measurement;
+  if (!isPlainObject(measurement)) return null;
+  const lists = {};
+  const omittedByList = {};
+  let budget = MAX_HIDDEN_EAGER_MEDIA_MEASUREMENT_CELLS;
+  for (const name of HIDDEN_EAGER_MEDIA_MEASUREMENT_LISTS) {
+    const cells = [];
+    let omitted = 0;
+    for (const raw of (Array.isArray(measurement[name]) ? measurement[name] : [])) {
+      const cell = hiddenEagerMediaMeasurementCell(raw, { withProblemCodes: name === "incomplete" });
+      if (!cell || budget === 0) {
+        omitted += 1;
+        continue;
+      }
+      cells.push(cell);
+      budget -= 1;
+    }
+    lists[name] = cells;
+    omittedByList[name] = omitted;
+  }
+  return {
+    status: measurement.status === "complete" ? "complete" : "incomplete",
+    expected_capture_count: safeNonnegativeInteger(measurement.expected_capture_count) ?? 0,
+    captured_count: safeNonnegativeInteger(measurement.captured_count) ?? 0,
+    ...lists,
+    omitted_cell_count: Object.values(omittedByList).reduce((total, count) => total + count, 0),
+    omitted_cell_count_by_list: omittedByList,
+  };
+}
+
+function hiddenEagerMediaGateAssertion(gate) {
+  const summary = checkpointGateSummary(gate);
+  const page = { page_id: "campaign" };
+  const common = {
+    id: HIDDEN_EAGER_MEDIA_SCOPE,
+    family: "polish_gate",
+    page,
+    expected: "complete package-owned page-load evidence with no hidden eager media above 1,048,576 bytes, or an exact named-human checkpoint waiver",
+    actual: `${summary.code}: ${summary.reason}`,
+    evidence: summary,
+  };
+  if (summary.status === "blocked") {
+    return assertion({ ...common, status: STATUS.FAIL, severity: SEVERITY.BLOCKER });
+  }
+  if (summary.status === "waived") {
+    return assertion({ ...common, status: STATUS.WARN, severity: SEVERITY.WARN, waiver: summary.waiver });
+  }
+  if (summary.status === "not_applicable") {
+    return assertion({ ...common, status: STATUS.SKIPPED });
+  }
+  return assertion({ ...common, status: STATUS.PASS });
+}
+
+function storeProfileGateAssertion(gate) {
+  const page = { page_id: "campaign" };
+  const evidence = {
+    code: gate.code,
+    subject: gate.subject,
+    state: gate.state,
+    state_fingerprint: gate.state_fingerprint,
+    matrix: gate.matrix,
+    blocker_fields: gate.blocker_fields,
+    warning_fields: gate.warning_fields,
+    waivable: gate.waivable,
+    waiver: gate.waiver,
+    waiver_assessment: gate.waiver_assessment,
+    required_actions: gate.required_actions,
+  };
+  if (gate.status === "blocked") {
+    return assertion({
+      id: PAGE_KIT_STORE_PROFILE_SCOPE,
+      family: "api-metadata",
+      page,
+      status: STATUS.FAIL,
+      severity: SEVERITY.BLOCKER,
+      expected: `CampaignSpec and target ${PAGE_KIT_CAMPAIGNS_REL_PATH} match across all ${PAGE_KIT_STORE_PROFILE_FIELDS.length} governed Store Profile fields`,
+      actual: `${gate.code}: ${gate.reason}`,
+      evidence,
+    });
+  }
+  if (gate.status === "waived") {
+    return assertion({
+      id: PAGE_KIT_STORE_PROFILE_SCOPE,
+      family: "api-metadata",
+      page,
+      status: STATUS.WARN,
+      severity: SEVERITY.WARN,
+      expected: "Store Profile parity passes, or an explicit named-human I-16 exception accepts the exact blocked state",
+      actual: gate.reason,
+      evidence,
+      waiver: gate.waiver,
+    });
+  }
+  if (gate.status === "not_applicable") {
+    return assertion({
+      id: PAGE_KIT_STORE_PROFILE_SCOPE,
+      family: "api-metadata",
+      page,
+      status: STATUS.SKIPPED,
+      expected: "Packet QA evaluates Store Profile parity before runtime work",
+      actual: gate.reason,
+      evidence,
+    });
+  }
+  if (gate.warning_fields?.length) {
+    return assertion({
+      id: PAGE_KIT_STORE_PROFILE_SCOPE,
+      family: "api-metadata",
+      page,
+      status: STATUS.WARN,
+      severity: SEVERITY.WARN,
+      expected: "Target-only Store Profile values remain visible for operator review",
+      actual: gate.reason,
+      evidence,
+    });
+  }
+  return assertion({
+    id: PAGE_KIT_STORE_PROFILE_SCOPE,
+    family: "api-metadata",
+    page,
+    status: STATUS.PASS,
+    expected: `CampaignSpec and target ${PAGE_KIT_CAMPAIGNS_REL_PATH} match across all ${PAGE_KIT_STORE_PROFILE_FIELDS.length} governed Store Profile fields`,
+    actual: gate.reason,
+    evidence,
+  });
+}
+
+function sdkVersionGateAssertion(gate) {
+  const page = { page_id: "campaign" };
+  const evidence = {
+    code: gate.code,
+    subject: gate.subject,
+    state: gate.state,
+    state_fingerprint: gate.state_fingerprint,
+    expected_sdk_version: gate.expected_sdk_version,
+    observed_sdk_version: gate.observed_sdk_version,
+    expected_source: gate.expected_source,
+    waivable: gate.waivable,
+    waiver: gate.waiver,
+    waiver_assessment: gate.waiver_assessment,
+    required_actions: gate.required_actions,
+    ...(Array.isArray(gate.advisory_actions) ? { advisory_actions: gate.advisory_actions } : {}),
+  };
+  if (gate.status === "blocked") {
+    return assertion({
+      id: PAGE_KIT_SDK_VERSION_SCOPE,
+      family: "api-metadata",
+      page,
+      status: STATUS.FAIL,
+      severity: SEVERITY.BLOCKER,
+      expected: `CampaignSpec and target ${PAGE_KIT_CAMPAIGNS_REL_PATH} declare the same released SDK version`,
+      actual: `${gate.code}: ${gate.reason}`,
+      evidence,
+    });
+  }
+  if (gate.status === "waived") {
+    return assertion({
+      id: PAGE_KIT_SDK_VERSION_SCOPE,
+      family: "api-metadata",
+      page,
+      status: STATUS.WARN,
+      severity: SEVERITY.WARN,
+      expected: "SDK-pin parity passes, or a bounded named-human decision accepts the exact expected/observed pair",
+      actual: gate.reason,
+      evidence,
+      waiver: gate.waiver,
+    });
+  }
+  if (gate.status === "not_applicable") {
+    return assertion({
+      id: PAGE_KIT_SDK_VERSION_SCOPE,
+      family: "api-metadata",
+      page,
+      status: STATUS.SKIPPED,
+      expected: "Packet QA evaluates SDK-pin parity before runtime work",
+      actual: gate.reason,
+      evidence,
+    });
+  }
+  if (gate.code === "page_kit.sdk_version.repo_newer") {
+    return assertion({
+      id: PAGE_KIT_SDK_VERSION_SCOPE,
+      family: "api-metadata",
+      page,
+      status: STATUS.WARN,
+      severity: SEVERITY.WARN,
+      expected: `Target ${PAGE_KIT_CAMPAIGNS_REL_PATH} declares the released SDK version that ships; a CampaignSpec pin behind it is a stale build hint`,
+      actual: gate.reason,
+      evidence,
+    });
+  }
+  return assertion({
+    id: PAGE_KIT_SDK_VERSION_SCOPE,
+    family: "api-metadata",
+    page,
+    status: STATUS.PASS,
+    expected: `CampaignSpec and target ${PAGE_KIT_CAMPAIGNS_REL_PATH} declare the same released SDK version`,
+    actual: gate.reason,
+    evidence,
+  });
+}
+
+function checkpointGateAssertion(gate) {
+  if (gate?.id === PAGE_KIT_STORE_PROFILE_SCOPE) return storeProfileGateAssertion(gate);
+  if (gate?.id === PAGE_KIT_SDK_VERSION_SCOPE) return sdkVersionGateAssertion(gate);
+  if (gate?.id === HIDDEN_EAGER_MEDIA_SCOPE) return hiddenEagerMediaGateAssertion(gate);
+  throw new Error(`QA cannot project unknown checkpoint gate ${JSON.stringify(gate?.id)}.`);
+}
+
+function checkpointBlockedAssertions(checkpointGates, polishGate, themeGate) {
+  const blockedIds = checkpointGates
+    .filter((gate) => gate?.status === "blocked")
+    .map((gate) => gate.id);
+  const blockedLabel = blockedIds.join(", ");
+  const skippedByCheckpoint = (family) => assertion({
+    id: `${family}.blocked_by_checkpoint`,
+    family,
+    page: { page_id: "campaign" },
+    status: STATUS.SKIPPED,
+    expected: `${family} checks executed`,
+    actual: `Skipped: checkpoint gate(s) ${blockedLabel} blocked; no HTTP, browser, analytics, or test-order work ran.`,
+    evidence: { blocked_by: blockedIds },
+  });
+  return [
+    ...(polishGate?.owned_checkpoint_only ? [] : [polishGateAssertion(polishGate)]),
+    themeGateAssertion(themeGate),
+    ...checkpointGates.map(checkpointGateAssertion),
+    ...GATE_SUPPRESSED_FAMILIES
+      .filter((family) => family !== "polish_gate" && family !== "api-metadata")
+      .map(skippedByCheckpoint),
+  ];
+}
+
+function serializeThrownValue(error) {
+  const diagnostic = { message: String(error) };
+  if (error && typeof error === "object") {
+    const record = error;
+    if (typeof record.name === "string" && record.name) diagnostic.name = record.name;
+    if (typeof record.message === "string" && record.message) diagnostic.message = record.message;
+    if (typeof record.stack === "string" && record.stack) diagnostic.stack = record.stack;
+  }
+  return diagnostic;
+}
+
+// `report_path` is carried only when the report the gates were evaluated on
+// is not the packet-inferred default — the same rule as doctor's
+// `derived.assembly_report_path` handling — so the printed remediations can
+// name it and a default-report campaign's output is unchanged.
+function reportPathField(resolved) {
+  const reportPath = explicitReportPath(resolved?.reportPath, resolved?.targetRepo);
+  return reportPath ? { report_path: reportPath } : {};
+}
+
+function resolvePayload(resolved, { routeProbe = null } = {}) {
+  const entryUrls = deriveEntryUrls(resolved.topologies);
+  const pageUrls = derivePageUrls(resolved.topologies);
+  const checkpointGates = Array.isArray(resolved.checkpointGates)
+    ? resolved.checkpointGates.map(checkpointGateSummary)
+    : [];
+  const hasBlockedCheckpoint = checkpointGates.some((gate) => gate.status === "blocked");
+  const hasCheckpointWarning = checkpointGates.some(checkpointGateHasWarning);
+  const status = resolveStatus({ hasBlockedCheckpoint, hasCheckpointWarning, routeProbe });
+  return {
+    ok: status !== "blocked" && status !== "routes_unresolved",
+    status,
+    map_id: resolved.mapId,
+    ...(resolved.packetPath ? { packet_path: resolved.packetPath } : {}),
+    ...reportPathField(resolved),
+    ...(resolved.proxyBase && resolved.proxyBase !== DEFAULT_PROXY_BASE ? { proxy_base: resolved.proxyBase } : {}),
+    spec_source: resolved.specSource,
+    spec_version: resolved.specVersion,
+    spec_hash: resolved.specHash,
+    base_url: resolved.baseUrl,
+    entry_urls: entryUrls,
+    page_urls: pageUrls,
+    tested_urls: [],
+    campaign: {
+      name: resolved.spec.campaign?.name || null,
+      slug: resolved.spec.campaign?.slug || null,
+      ref_id: resolved.spec.campaign?.ref_id || null,
+    },
+    checkpoint_gates: checkpointGates,
+    theme_gate: themeGateSummary(resolved.themeGate),
+    polish_gate: polishGateSummary(resolved.polishGate),
+    ...(routeProbe ? { route_probe: routeProbe } : {}),
+    funnels: resolved.topologies,
+  };
+}
+
+// The resolve status ladder, ordered by how much of the deployment this run
+// actually verified rather than by which axis complained. Before #273 the top
+// two rungs did not exist, so a route set that was 100% dead reported `ready`
+// and printed a next command that could not succeed.
+//
+//   blocked            a checkpoint gate blocks; the routes were not probed.
+//   routes_unresolved  the routes were probed and at least one did not resolve.
+//   ready_unprobed     there were routes to probe and none produced a response.
+//   ready_with_exceptions / ready   as before, now over probed-and-resolved routes.
+//
+// `ready_unprobed` sits above `ready_with_exceptions` on purpose: a checkpoint
+// warning is a known, named exception an operator can read, while an unprobed
+// route set means the deployment half of the run was never checked at all. The
+// checkpoint warnings stay fully visible in checkpoint_gates[] either way.
+function resolveStatus({ hasBlockedCheckpoint, hasCheckpointWarning, routeProbe }) {
+  if (hasBlockedCheckpoint) return "blocked";
+  if (routeProbe?.status === "failed") return "routes_unresolved";
+  if (routeProbe?.status === "not_probed" && routeProbe.code !== "route_probe.no_routes") {
+    return "ready_unprobed";
+  }
+  return hasCheckpointWarning ? "ready_with_exceptions" : "ready";
+}
+
+// Probing is opt-out, not opt-in: the silent `ready` in #273 happened because
+// nothing checked by default. `--no-probe` exists for hermetic runs that must
+// make no outbound request at all; an ordinary offline run needs no flag,
+// because a transport failure already degrades to `ready_unprobed`.
+async function resolveRouteProbe(resolved, args, { fetchImpl = fetch } = {}) {
+  const entryUrls = deriveEntryUrls(resolved.topologies);
+  const blocked = (resolved.checkpointGates || []).some((gate) => gate?.status === "blocked");
+  const disabled = args["no-probe"] === true;
+  const timeout = Number(args["probe-timeout-ms"]);
+  return probeRouteUrls({
+    entryUrls,
+    baseUrl: resolved.baseUrl,
+    publicRouteSlug: resolved.publicRouteSlug,
+    enabled: !disabled && !blocked,
+    timeoutMs: Number.isFinite(timeout) && timeout > 0 ? timeout : ROUTE_PROBE_DEFAULT_TIMEOUT_MS,
+    fetchImpl,
+    skippedReason: blocked && !disabled ? "a checkpoint gate blocks this run" : disabled ? "--no-probe" : null,
+  });
+}
+
+function checkpointGateHasWarning(gate) {
+  return gate?.status === "waived"
+    || (Array.isArray(gate?.warning_fields) && gate.warning_fields.length > 0);
+}
+
+function checkpointGateSummary(gate) {
+  const hiddenEagerMedia = gate?.id === HIDDEN_EAGER_MEDIA_SCOPE;
+  const subject = hiddenEagerMedia
+    ? hiddenEagerMediaSubject(gate?.subject)
+    : {
+        public_route_slug: stringArg(gate?.subject?.public_route_slug) || "",
+        target_path: stringArg(gate?.subject?.target_path) || PAGE_KIT_CAMPAIGNS_REL_PATH,
+      };
+  const waiver = checkpointWaiverSummary(gate?.waiver, subject);
+  const waiverAssessment = {
+    active: checkpointWaiverSummary(gate?.waiver_assessment?.active, subject),
+    inert_counts: Object.fromEntries(
+      ["stale", "foreign", "malformed", "expired"].map((kind) => [
+        kind,
+        Number.isInteger(gate?.waiver_assessment?.inert_counts?.[kind])
+          ? gate.waiver_assessment.inert_counts[kind]
+          : 0,
+      ]),
+    ),
+  };
+  const requiredActions = Array.isArray(gate?.required_actions)
+    ? gate.required_actions
+      .filter(isPlainObject)
+      .map((action) => ({
+        id: stringArg(action.id),
+        kind: stringArg(action.kind),
+        command: stringArg(action.command),
+        description: stringArg(action.description),
+      }))
+    : [];
+  const summary = {
+    id: stringArg(gate?.id),
+    scope: stringArg(gate?.scope),
+    status: stringArg(gate?.status),
+    code: stringArg(gate?.code),
+    reason: stringArg(gate?.reason),
+    waivable: gate?.waivable === true,
+    subject,
+    state_fingerprint: stringArg(gate?.state_fingerprint),
+    waiver,
+    waiver_assessment: waiverAssessment,
+    required_actions: requiredActions,
+  };
+  if (hiddenEagerMedia) {
+    const findings = hiddenEagerMediaFindings(gate);
+    return {
+      ...summary,
+      state: { findings },
+      findings,
+      measurement: hiddenEagerMediaMeasurement(gate),
+    };
+  }
+  if (gate?.id === PAGE_KIT_STORE_PROFILE_SCOPE) {
+    return {
+      ...summary,
+      state: {
+        ...(stringArg(gate?.state?.spec_status) ? { spec_status: stringArg(gate.state.spec_status) } : {}),
+        ...(stringArg(gate?.state?.target_status) ? { target_status: stringArg(gate.state.target_status) } : {}),
+        discrepancies: Array.isArray(gate?.state?.discrepancies)
+          ? gate.state.discrepancies.map((row) => ({
+            field: stringArg(row?.field),
+            kind: stringArg(row?.kind),
+            spec: typeof row?.spec === "string" ? row.spec : null,
+            target: typeof row?.target === "string" ? row.target : null,
+          }))
+          : [],
+      },
+      matrix: Array.isArray(gate?.matrix)
+        ? gate.matrix.map((row) => ({
+          field: stringArg(row?.field),
+          kind: stringArg(row?.kind),
+          spec: typeof row?.spec === "string" ? row.spec : null,
+          target: typeof row?.target === "string" ? row.target : null,
+          severity: stringArg(row?.severity),
+        }))
+        : [],
+      blocker_fields: Array.isArray(gate?.blocker_fields) ? gate.blocker_fields.filter((field) => typeof field === "string") : [],
+      warning_fields: Array.isArray(gate?.warning_fields) ? gate.warning_fields.filter((field) => typeof field === "string") : [],
+    };
+  }
+  if (gate?.id === PAGE_KIT_SDK_VERSION_SCOPE) {
+    return {
+      ...summary,
+      state: {
+        ...(stringArg(gate?.state?.spec_status) ? { spec_status: stringArg(gate.state.spec_status) } : {}),
+        ...(stringArg(gate?.state?.target_status) ? { target_status: stringArg(gate.state.target_status) } : {}),
+        ...(Array.isArray(gate?.state?.invalid_declarations)
+          ? { invalid_declarations: gate.state.invalid_declarations.filter((field) => typeof field === "string") }
+          : {}),
+        ...(typeof gate?.state?.expected === "string" ? { expected: gate.state.expected } : {}),
+        ...(typeof gate?.state?.observed === "string" ? { observed: gate.state.observed } : {}),
+      },
+      expected_sdk_version: typeof gate?.expected_sdk_version === "string" ? gate.expected_sdk_version : null,
+      observed_sdk_version: typeof gate?.observed_sdk_version === "string" ? gate.observed_sdk_version : null,
+      expected_source: typeof gate?.expected_source === "string" ? gate.expected_source : null,
+    };
+  }
+  throw new Error(`QA cannot project unknown checkpoint gate ${JSON.stringify(gate?.id)}.`);
+}
+
+function checkpointWaiverSummary(waiver, subject) {
+  if (!isPlainObject(waiver)) return null;
+  return {
+    scope: stringArg(waiver.scope),
+    subject,
+    state_fingerprint: stringArg(waiver.state_fingerprint),
+    reason: stringArg(waiver.reason),
+    waived_by: stringArg(waiver.waived_by),
+    waived_at: stringArg(waiver.waived_at),
+    ...(stringArg(waiver.expires_at) ? { expires_at: stringArg(waiver.expires_at) } : {}),
+    ...(stringArg(waiver.review_condition) ? { review_condition: stringArg(waiver.review_condition) } : {}),
+  };
+}
+
+// Run-record closeout is required for every QA workflow. With an active run
+// session, blocked attempts stay attached to that session while repair
+// continues; the first ready outcome auto-closes with all attempt references.
+// This action is the explicit contract for sessionless or manually ended paths.
+// Packetless modes (qa --site, parity fixtures) get no action: run-record
+// requires a Build Packet, and a required-but-impossible command is worse
+// than none (Kilo review, PR #176). Paths are shell-quoted when needed.
+export function buildQaCloseoutActions({ packetPath = null, localPath = null, runSessionActive = false, disposition = null } = {}) {
+  if (!packetPath) return [];
+  const verdictRef = localPath ? ` --qa-verdict ${shellToken(localPath)}` : "";
+  // Will the session STILL hold this run_id by the time the operator runs the
+  // printed command? Only when this attempt does not end the session — a
+  // blocked one, which stays open for repair, or any disposition this version
+  // does not recognise. Both sides read SESSION_ENDING_DISPOSITIONS, so the
+  // answer here and the auto-end's own answer cannot drift apart.
+  // A session that stays open closes later — the eventual ready auto-end, or
+  // `run end` — assembling and remitting under this same run_id. Remit is a plain POST with no replace verb
+  // and the receiver refuses a second POST for a stored run_id with 409, so a
+  // command printed without `--no-remit` spends the id on the interim record
+  // and leaves the session's final record — the one carrying every QA attempt
+  // and the aggregated lifecycle — refused at the door.
+  //
+  // A session-ending disposition auto-ends the session IN THIS SAME PROCESS, before
+  // the operator can type anything: the record is already assembled and the
+  // session cleared, so the printed command mints its own run_id and there is
+  // nothing to collide with. Printing `--no-remit` there would be worse than
+  // useless — it would write a local-only record that never reaches the
+  // receiver, and if the auto-end's own remit had failed, that newer closed
+  // record would bury the failure the operator still has to recover from. The
+  // auto-end prints that recovery command itself; see autoEndCloseoutNotice.
+  const sessionRetainsRunId = runSessionActive && !SESSION_ENDING_DISPOSITIONS.has(disposition);
+  const remitRef = sessionRetainsRunId ? " --no-remit" : "";
+  const sessionNote = sessionRetainsRunId
+    ? " This attempt does not end the run session, so the session stays open and this writes the local record only (--no-remit): it shares the session's run id, and the session's own close is what remits that id once."
+    : "";
+  return [
+    {
+      id: "run_record_closeout",
+      kind: "command",
+      required: true,
+      stage: "qa",
+      command: `${cmd("run-record")} --packet ${shellToken(packetPath)}${verdictRef}${remitRef} --json`,
+      description: `Assemble the durable Run Record closeout for this QA workflow, including blocked outcomes. If an active session remains open after a blocked attempt, repair and re-test first (or use run end to close manually); a ready attempt auto-assembles one record that references every attempt.${sessionNote}`,
+    },
+  ];
+}
+
+const REMOVED_QA_POLICY_FLAGS = ["test-orders-allowed", "sandbox-test-card-confirmed"];
+
+function updateQaPolicy(args) {
+  const packetPath = args.packet ? resolve(args.packet) : null;
+  if (!packetPath) throw new Error("qa policy set requires --packet <campaign-runtime.build.json>.");
+  const packet = readJson(packetPath);
+  packet.campaign ||= {};
+  packet.deploy ||= {};
+  packet.qa ||= {};
+
+  // Test Orders have no permission flag. The two flags that once set one
+  // were removed with their packet fields in supported surface 1.28.0; a
+  // script still passing them gets told so instead of a silent no-op.
+  const removedFlags = REMOVED_QA_POLICY_FLAGS.filter((flag) => flag in args);
+  if (removedFlags.length) {
+    throw new Error(`qa policy set: ${removedFlags.map((flag) => `--${flag}`).join(" and ")} ${removedFlags.length > 1 ? "were" : "was"} removed in supported surface 1.28.0 (test orders run from --test-order <mode> alone; there is no permission flag). Drop the flag${removedFlags.length > 1 ? "s" : ""}. Accepted: --allowed-domains-confirmed, --deploy-target, --preview-url, --production-url, --order-path-depth.`);
+  }
+  // Validated with the other argv checks, before anything is written.
+  const orderPathDepth = parseOrderPathDepthFlag(args, { command: "qa policy set" });
+
+  const changed = [];
+  setOptionalBoolean(packet.campaign, "allowed_domains_confirmed", args, "allowed-domains-confirmed", changed);
+  setOptionalString(packet.deploy, "preview_url", args, "preview-url", changed);
+  setOptionalString(packet.deploy, "production_url", args, "production-url", changed);
+  setOptionalString(packet.deploy, "target", args, "deploy-target", changed);
+  if (orderPathDepth) {
+    packet.qa.proof_policy = isPlainObject(packet.qa.proof_policy) ? packet.qa.proof_policy : {};
+    setIfChanged(packet.qa.proof_policy, "order_path_depth", orderPathDepth, changed);
+  }
+
+  const staleReason = `The Build Packet changed after this doctor snapshot (qa policy set). Re-run ${cmd("doctor")} (or next) for current state.`;
+  if (changed.length) {
+    writeJson(packetPath, packet);
+    // #171: packet edits change what doctor would conclude; the retained
+    // doctor sidecar (if any) now predates them.
+    markDoctorSidecarStale(targetRepoFor(packetPath, packet), {
+      command: "qa policy set",
+      reason: staleReason,
+    });
+  }
+  // The assembly report mirrors qa.proof_policy from prepare-build, and
+  // assessPurchaseProofCoverage reads a packet/report disagreement as an
+  // unknown depth that holds `next` short of done. Whenever a depth is set,
+  // the mirror is refreshed through the same ledger write every other report
+  // edit uses — even when the packet already held that value, so a hand-edited
+  // packet whose mirror lags is reconciled by re-stating the packet's value.
+  // A packet with no report yet (pre-prepare-build) is left alone.
+  let reportMirror = null;
+  if (orderPathDepth) {
+    const workspace = resolveCampaignWorkspace(packetPath, { packet, followContextPointer: true });
+    if (existsSync(workspace.reportPath)) {
+      const outcome = commitAssemblyReport(workspace, (report) => {
+        const mirror = isPlainObject(report.proof_policy) ? report.proof_policy : {};
+        if (mirror.order_path_depth === orderPathDepth) return null;
+        report.proof_policy = { ...mirror, order_path_depth: orderPathDepth };
+        return report;
+      }, { command: "qa policy set", staleReason });
+      reportMirror = { report_path: outcome.reportPath, written: outcome.written, order_path_depth: orderPathDepth };
+      if (outcome.written) changed.push("report.proof_policy.order_path_depth");
+    }
+  }
+  return {
+    ok: true,
+    action: "qa-policy-set",
+    packet_path: packetPath,
+    changed,
+    policy: policySnapshot(packet),
+    ...(reportMirror ? { report_mirror: reportMirror } : {}),
+  };
+}
+
+// The complete set of QA assertions `qa waive` accepts today. Deliberately a
+// one-element list (packet 01, ratified I-9/I-16): analytics-correctness:
+// purchase-fires is the one unwaivable blocker in the estate that gained a
+// named-human lane. Extending the lane to another assertion is a design
+// decision with its own ratification, not a flag — refuse anything else.
+const WAIVABLE_QA_ASSERTIONS = Object.freeze(["analytics-correctness:purchase-fires"]);
+
+// `qa waive`: the ONLY sanctioned way to accept a failing
+// analytics-correctness:purchase-fires blocker. Modeled on `theme waive`
+// (cli.mjs themeWaive): refuses without --reason, records waived_by, stamps
+// waived_at, and writes ONE explicit decision onto the Assembly Report's qa
+// stage ($defs/stage is additionalProperties:true — no schema change, no
+// surface_version bump) so the correctness leg reads a named human's decision
+// instead of an agent improvising past a blocker. The waiver record mirrors
+// report.theme.waiver: { reason, waived_by, waived_at }.
+export function qaWaive(args) {
+  const packetPath = args.packet ? resolve(args.packet) : null;
+  if (!packetPath) throw new Error("qa waive requires --packet <campaign-runtime.build.json>.");
+  const packet = readJson(packetPath);
+  const assertionId = stringArg(args.assertion);
+  if (!assertionId) {
+    throw new Error(`qa waive requires --assertion <id>. Waivable assertions: ${WAIVABLE_QA_ASSERTIONS.join(", ")}.`);
+  }
+  if (!WAIVABLE_QA_ASSERTIONS.includes(assertionId)) {
+    throw new Error(
+      `qa waive does not accept --assertion "${assertionId}". The waiver lane is scoped to exactly: ${WAIVABLE_QA_ASSERTIONS.join(", ")}. `
+      + "Extending the lane to another assertion is a design decision, not a flag.",
+    );
+  }
+  const reason = stringArg(args.reason);
+  if (!reason) {
+    throw new Error("qa waive requires --reason \"<why this failing blocker is acceptable for this campaign>\".");
+  }
+  const workspace = resolveCampaignWorkspace(packetPath, {
+    packet,
+    reportPath: args.report ? resolve(String(args.report)) : undefined,
+    followContextPointer: true,
+  });
+  const { reportPath } = workspace;
+  if (!existsSync(reportPath)) {
+    throw new Error(`qa waive needs an assembly report at ${reportPath}; run prepare-build/start first.`);
+  }
+  const waiver = {
+    reason,
+    // Named-human lane: default to the operator identity the QA verdict
+    // already records ($USER@local), falling back to themeWaive's "operator".
+    waived_by: stringArg(args["waived-by"]) || (process.env.USER ? `${process.env.USER}@local` : "operator"),
+    waived_at: new Date().toISOString(),
+  };
+  commitAssemblyReport(workspace, (report) => {
+    const stages = isPlainObject(report.stages) ? report.stages : {};
+    const stageQa = isPlainObject(stages.qa) ? stages.qa : { stage: "qa", status: "pending" };
+    stageQa.waivers = { ...(isPlainObject(stageQa.waivers) ? stageQa.waivers : {}), [assertionId]: waiver };
+    stages.qa = stageQa;
+    report.stages = stages;
+    if (Array.isArray(report.evidence)) {
+      report.evidence.push(`QA waiver: ${assertionId} waived by ${waiver.waived_by} at ${waiver.waived_at}: ${reason}`);
+    }
+    return report;
+  }, {
+    // #171: the waiver changes what the next qa run concludes; the retained
+    // doctor sidecar (if any) now predates this report edit.
+    command: "qa waive",
+    staleReason: `A QA assertion waiver was recorded after this doctor snapshot. Re-run ${cmd("doctor")} (or next) for current state.`,
+  });
+  return {
+    ok: true,
+    action: "qa-waive",
+    assertion: assertionId,
+    waiver,
+    report_path: reportPath,
+    note: `The next qa run downgrades a FAILING ${assertionId} blocker to a warning with this attribution; the disposition becomes ready_with_exceptions, never plain ready. A passing run ignores the waiver.`,
+  };
+}
+
+// Read the recorded `qa waive` decisions off the Assembly Report for a run.
+// Only assertions inside the sanctioned lane with a non-empty reason count —
+// anything else on the report is inert data (reverting the waiver feature
+// must leave recorded waivers harmless, per packet 01's revert contract).
+function resolveQaWaivers({ packetPath, report: reportOverride = undefined }) {
+  const report = reportOverride === undefined
+    ? loadRuntimeArtifact(packetPath, "assembly-report.json")
+    : reportOverride;
+  const recorded = report?.stages?.qa?.waivers;
+  if (!isPlainObject(recorded)) return {};
+  const waivers = {};
+  for (const [assertionId, waiver] of Object.entries(recorded)) {
+    if (!WAIVABLE_QA_ASSERTIONS.includes(assertionId)) continue;
+    if (!isPlainObject(waiver)) continue;
+    if (typeof waiver.reason !== "string" || !waiver.reason.trim()) continue;
+    waivers[assertionId] = {
+      reason: waiver.reason.trim(),
+      waived_by: stringArg(waiver.waived_by) || "operator",
+      waived_at: stringArg(waiver.waived_at) || null,
+    };
+  }
+  return waivers;
+}
+
+function isPlainObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+// Every assertion family a non-blocked run can emit beyond theme_gate. A
+// gate-blocked verdict carries one skipped audit assertion per family so the
+// verdict shape never drifts for consumers walking assertions[] by family.
+// Derived from the canonical vocabulary in qa-verdict.mjs (which preserves
+// this list's emission order); drift against the actual emitters is enforced
+// by tests that collect `family:` literals and assert set equality — adding
+// an emitter without updating the vocabulary fails CI.
+export const GATE_SUPPRESSED_FAMILIES = Object.freeze(
+  QA_ASSERTION_FAMILY_VOCABULARY.filter((family) => family !== "theme_gate"),
+);
+
+// A requested browser pass a blocked gate refused.
+//
+// `qa run --browser` behind a blocked gate finalizes the blocked verdict before
+// any page is rendered — the gate decision is the point, and neither it nor the
+// exit code changes here. What used to be missing is any trace of the
+// downgrade: the verdict was byte-identical to the same run without the flag
+// (no browser-runtime assertions, `tested_urls: []`), and stderr said nothing,
+// so an operator who asked for browser QA got none and had no way to tell.
+// The stamp below rides the verdict for machine readers and
+// `reportBrowserSkippedByGate` says it once for the human.
+export const BROWSER_SKIPPED_GATE_BLOCKED = "skipped_gate_blocked";
+
+// How many of a gate's required actions the one-line notice quotes before it
+// defers to the verdict. Exported so a test pins the number rather than
+// re-deriving it from the behaviour it governs.
+export const MAX_BROWSER_SKIP_ACTIONS = 3;
+
+// What actually clears this gate, taken from the gate itself.
+//
+// Deliberately not prose written here: "re-run Polish" is wrong for
+// polish.assembly_source_package_stale (only a fresh Build refreshes the
+// assembly fingerprint), and "record a waiver" is wrong for every non-waivable
+// checkpoint state — checkpointWaive refuses those outright. The evaluators
+// already publish the correct repair for the exact state they blocked on, and
+// the waive command appears among them only when the gate is waivable, so the
+// notice quotes required_actions and invents nothing.
+function gateClearingHint(gates) {
+  const actions = (Array.isArray(gates) ? gates : [gates])
+    .filter(isPlainObject)
+    .flatMap((gate) => (Array.isArray(gate.required_actions) ? gate.required_actions.filter(isPlainObject) : []));
+  const unique = [];
+  for (const action of actions) {
+    // The rendering rule doctor and next use, minus the packet: the verdict
+    // is a public artifact that never carries a local path, so the
+    // `--packet <packet>` placeholder stays and only the install prefix is
+    // applied; a kind: "manual" action falls back to its instruction.
+    const text = singleLineFragment(requiredActionText(action));
+    if (text && !unique.includes(text)) unique.push(text);
+  }
+  // Deduplicated BEFORE the cap, and truncation is measured against that count:
+  // two identical actions are one repair, and claiming a "rest" the reader
+  // would not find on the verdict is worse than saying nothing.
+  const named = unique.slice(0, MAX_BROWSER_SKIP_ACTIONS);
+  if (!named.length) {
+    // Two different silences. A gate that published nothing has nothing for the
+    // reader to look up beyond its own reason; a gate that published actions
+    // this notice could not render (no command, no readable description) has
+    // repair steps ON the verdict, and calling that "no actions" would hide
+    // them.
+    return actions.length
+      ? "The gate published repair steps this notice could not render; read its required_actions on the verdict for what clears it, then re-run with --browser."
+      : "Read the gate's own reason and required_actions on the verdict for what clears it, then re-run with --browser.";
+  }
+  const more = unique.length > named.length ? " (and the rest of the gate's required_actions on the verdict)" : "";
+  return `The gate's required actions clear it: ${named.join("; ")}${more}. Then re-run with --browser.`;
+}
+
+function browserSkippedByGate({ args, blockedBy, gateLabel, gates }) {
+  // No flag, no claim: a run that never asked for a browser pass is not
+  // "skipping" one, and stamping it would make the field unreadable.
+  if (args?.browser !== true) return null;
+  const codes = (Array.isArray(blockedBy) ? blockedBy : [blockedBy])
+    .filter((code) => typeof code === "string" && code.length > 0);
+  const named = codes.length ? ` (${codes.join(", ")})` : "";
+  return {
+    requested: true,
+    status: BROWSER_SKIPPED_GATE_BLOCKED,
+    blocked_by: codes,
+    reason: `Browser QA was requested with --browser but no browser launched: the ${gateLabel}${named} blocked this run before any page was rendered. ${gateClearingHint(gates)}`,
+  };
+}
+
+// One stderr line, on the same seam as reportCommercialRunnerError: suppressed
+// under --json, where the stamp itself is already in the emitted verdict.
+function reportBrowserSkippedByGate(args, browser, write = (message) => process.stderr.write(message)) {
+  if (!browser || browser.status !== BROWSER_SKIPPED_GATE_BLOCKED) return false;
+  if (args?.json === true) return false;
+  write(`[campaigns-os] ${browser.reason}\n`);
+  return true;
+}
+
+function parityReplayEvidence(bundle) {
+  const order = bundle?.order || bundle?.orders?.[0] || null;
+  const capture = bundle?.capture || bundle?.candidate_capture || bundle?.captures?.candidate || null;
+  const baselineCapture = bundle?.baseline_capture || bundle?.baselineCapture || bundle?.captures?.baseline || null;
+  if (!order || !capture) {
+    throw new Error("--parity-order-json must contain order + capture evidence (or orders[0] + captures.candidate).");
+  }
+  return { order, capture, baselineCapture, orders: Array.isArray(bundle.orders) ? bundle.orders : [order] };
+}
+
+async function runParityQa(args) {
+  // Checked here as well as on the budget itself: the budget is built after a
+  // browser has launched, and a flag the operator typed wrong should cost them
+  // nothing. The budget stays the authority — this is fail-fast, not the gate.
+  validatedOrderCreationLimit(args);
+  const fixturePath = stringArg(args.fixture);
+  const scenarioId = stringArg(args.scenario) || stringArg(args._[2]);
+  if (!fixturePath) throw new Error("QA parity requires --fixture <parity-fixture.json>.");
+  if (!scenarioId) throw new Error("QA parity requires --scenario <scenario-id>.");
+
+  const fixture = await loadParityFixture(resolve(fixturePath));
+  const scenario = resolveParityScenario(fixture, scenarioId);
+  const baseUrl = normalizeBaseUrl(stringArg(args["base-url"]) || fixture.candidate_base_url);
+  const startedAt = new Date().toISOString();
+  const runId = generateRunId();
+  let result;
+
+  if (stringArg(args["parity-order-json"])) {
+    const replay = parityReplayEvidence(readJson(resolve(args["parity-order-json"])));
+    result = {
+      assertions: assessParityCapture({
+        fixture,
+        scenario,
+        order: replay.order,
+        capture: replay.capture,
+        baselineCapture: replay.baselineCapture,
+      }),
+      orders: replay.orders,
+      captures: { candidate: replay.capture, ...(replay.baselineCapture ? { baseline: replay.baselineCapture } : {}) },
+    };
+  } else {
+    result = await runParityCapture({ fixture, scenarioId, args: { ...args, "base-url": baseUrl, run_id: runId } });
+    // Persist the live evidence bundle beside the verdict: replay runs
+    // (--parity-order-json) and negative controls assess the exact same
+    // order + capture the live traversal produced.
+    const bundleDir = campaignOutputDir(args["output-dir"] || "qa-output", fixture.campaign.slug);
+    mkdirSync(bundleDir, { recursive: true });
+    writeJson(join(bundleDir, `${runId}.parity-bundle.json`), {
+      scenario_id: scenario.scenario_id,
+      // Both shapes on purpose: `order` is the assessed primary,
+      // `orders` mirrors the in-memory result so bundle readers and
+      // parityReplayEvidence see the same array shape as the live run.
+      order: result.orders[0] || null,
+      orders: result.orders,
+      capture: result.captures?.candidate || null,
+      ...(result.captures?.baseline ? { baseline_capture: result.captures.baseline } : {}),
+    });
+  }
+
+  const page = { page_id: "parity", page_type: "checkout", url: baseUrl };
+  const resolved = {
+    themeGate: { status: "not_applicable", code: "theme_gate.not_applicable", reason: "Parity capture is fixture-driven." },
+    polishGate: { status: "not_applicable", code: "polish.not_applicable", reason: "Parity capture is fixture-driven." },
+    mapId: fixture.campaign.slug,
+    proxyBase: stringArg(args["proxy-base"]) || DEFAULT_PROXY_BASE,
+    baseUrl,
+    spec: { campaign: { ref_id: String(scenario.shadow_campaign_id) } },
+    specVersion: `parity-fixture-${fixture.schema_version}`,
+    specHash: computeSpecHash(fixture),
+    topologies: [{ topology_id: `parity-${scenario.scenario_id}`, pages: [page] }],
+  };
+  return finalizeQaRun({
+    args,
+    resolved,
+    runId,
+    startedAt,
+    assertions: result.assertions,
+    testOrders: result.orders,
+  });
+}
+
+async function runQa(args, options = {}) {
+  // Fail-fast before anything resolves or launches. The authoritative check
+  // lives on the creation budget itself, which every browser path builds.
+  validatedOrderCreationLimit(args);
+  const resolved = await resolveQaInputs(args);
+  return runResolvedQa(args, resolved, options);
+}
+
+// `runSessionActive` is threaded in from the CLI's single ambient-session read
+// rather than re-discovered here, so the closeout command this run prints and
+// the run_id the session will close under come from the same observation.
+async function runResolvedQa(args, resolved, { runSessionActive = false } = {}) {
+  const startedAt = new Date().toISOString();
+  const runId = generateRunId();
+  const gate = resolved.themeGate;
+  const polishGate = resolved.polishGate;
+  const checkpointGates = Array.isArray(resolved.checkpointGates)
+    ? resolved.checkpointGates
+    : nonPacketCheckpointGates(resolved.publicRouteSlug);
+  const blockedCheckpoints = checkpointGates.filter((checkpoint) => checkpoint?.status === "blocked");
+  if (blockedCheckpoints.length) {
+    return finalizeQaRun({
+      args,
+      resolved,
+      runId,
+      startedAt,
+      assertions: checkpointBlockedAssertions(checkpointGates, polishGate, gate),
+      testOrders: [],
+      commercial: unavailableCommercialReport("checkpoint_gate_blocked"),
+      runSessionActive,
+      browser: browserSkippedByGate({
+        args,
+        blockedBy: blockedCheckpoints.map((checkpoint) => checkpoint.id),
+        gateLabel: "checkpoint gate",
+        gates: blockedCheckpoints,
+      }),
+    });
+  }
+  const checkpointAssertions = checkpointGates.map(checkpointGateAssertion);
+  if (polishGate.status === "blocked") {
+    return finalizeQaRun({
+      args,
+      resolved,
+      runId,
+      startedAt,
+      assertions: [...checkpointAssertions, ...polishBlockedAssertions(polishGate, gate).filter((item) => item.family !== "api-metadata")],
+      testOrders: [],
+      commercial: unavailableCommercialReport("polish_gate_blocked"),
+      runSessionActive,
+      browser: browserSkippedByGate({
+        args,
+        blockedBy: [polishGate.code],
+        gateLabel: "polish gate",
+        gates: [polishGate],
+      }),
+    });
+  }
+  // Blocked theme gate refuses the whole run: the verdict carries the gate
+  // blocker plus skipped audit assertions for every suppressed check family,
+  // so the verdict shape stays stable for consumers (exit code 4).
+  if (gate.status === "blocked") {
+    return finalizeQaRun({
+      args,
+      resolved,
+      runId,
+      startedAt,
+      assertions: [...checkpointAssertions, ...themeBlockedAssertions(gate, polishGate).filter((item) => item.family !== "api-metadata")],
+      testOrders: [],
+      commercial: unavailableCommercialReport("theme_gate_blocked"),
+      runSessionActive,
+      browser: browserSkippedByGate({
+        args,
+        blockedBy: [gate.code],
+        gateLabel: "theme gate",
+        gates: [gate],
+      }),
+    });
+  }
+
+  const assertions = [
+    ...checkpointAssertions,
+    ...(polishGate?.owned_checkpoint_only ? [] : [polishGateAssertion(polishGate)]),
+    themeGateAssertion(gate),
+  ];
+  const contractAssertion = templateBrandContractAssertion(resolved);
+  if (contractAssertion) assertions.push(contractAssertion);
+  const commercialPlanning = planCommercialParity(resolved.rawSpec || resolved.spec);
+  const sourceLoader = createPageSourceLoader({ authCookie: args["auth-cookie"] });
+  const commercialIds = new Set(commercialPlanning.pages
+    .filter((page) => page?.id !== undefined && page?.id !== null)
+    .map((page) => String(page.id)));
+  const capturesByPageId = new Map();
+  const bindingExpected = expectedBinding(resolved);
+  const bindingScriptLoader = createBindingScriptLoader();
+  const pages = resolved.topologies.flatMap(topology => topology.pages);
+  const pageResults = await mapConcurrent(pages, COMMERCIAL_QA_LIMITS.concurrency, page =>
+    runPageChecks(page, args, { sourceLoader, bindingExpected, bindingScriptLoader, captureCommercial: commercialIds.has(String(page.page_id)) }));
+  for (const [index, page] of pages.entries()) {
+    const pageResult = pageResults[index];
+    assertions.push(...pageResult.assertions);
+    if (commercialIds.has(String(page.page_id)) && pageResult.commercialCapture && !capturesByPageId.has(String(page.page_id))) {
+      capturesByPageId.set(String(page.page_id), pageResult.commercialCapture);
+    }
+  }
+  if (args.browser === true) {
+    assertions.push(...await runBrowserChecks(resolved.topologies, args, {
+      brandContract: resolved.brandContract,
+      residueSeverity: residueSeverityForThemeGate(gate.status),
+      supportedPaymentMethods: supportedPaymentMethodsFromSpec(resolved.spec),
+    }));
+  }
+
+  const testOrders = await runAnalyticsOrderSequence({ args, resolved, runId, assertions });
+  const remainingAssertionBudget = Math.max(0, QA_VERDICT_ASSERTION_LIMIT - assertions.length);
+  let commercialResult;
+  try {
+    commercialResult = await runCommercialParity({
+      resolved,
+      captures: [...capturesByPageId.values()],
+      planning: commercialPlanning,
+      maxAssertions: remainingAssertionBudget,
+    });
+  } catch (error) {
+    commercialResult = {
+      assertions: [],
+      commercial: unavailableCommercialReport("commercial_runner_error"),
+    };
+    reportCommercialRunnerError(args, error);
+  }
+  assertions.push(...commercialResult.assertions);
+  return finalizeQaRun({
+    args,
+    resolved,
+    runId,
+    startedAt,
+    assertions,
+    testOrders,
+    commercial: commercialResult.commercial,
+    runSessionActive,
+  });
+}
+
+function reportCommercialRunnerError(args, error, write = (message) => process.stderr.write(message)) {
+  if (args?.json === true) return false;
+  write(`[campaigns-os] Commercial parity could not complete: ${error instanceof Error ? error.message : String(error)}\n`);
+  return true;
+}
+
+// Keep the correctness/order chronology in one testable seam. Root inventory
+// happens first, parity remains between the two correctness phases, then the
+// one canonical typed-card run captures its settled terminal and only then do
+// we finalize the stable purchase-fires assertion. There is no receipt replay
+// and no second order.
+async function runAnalyticsOrderSequence({ args, resolved, runId, assertions }, overrides = {}) {
+  const operations = {
+    runInventory: runAnalyticsCorrectnessChecks,
+    runParity: runAnalyticsParityChecks,
+    runOrders: maybeRunTestOrders,
+    assessReceipt: assessReceiptPurchase,
+    ...overrides,
+  };
+  const analyticsContract = resolved.spec?.analytics;
+  const analyticsLeg = analyticsCorrectnessLegDecision(forcedAnalyticsCorrectness(args), analyticsContract);
+
+  // Packet 04 Stage A / IC-2: the flag remains tri-state. Explicit false is a
+  // visible skip; true forces both phases; absent defers to the spec.
+  if (analyticsLeg === "disabled") {
+    assertions.push(analyticsCorrectnessDisabledAssertion(analyticsContract));
+  } else if (analyticsLeg === "run") {
+    assertions.push(...await operations.runInventory(args, analyticsContract || {}, {
+      target: resolved.analyticsCaptureTarget,
+    }));
+  }
+
+  // Analytics parity is unchanged and remains opt-in between root inventory
+  // and typed-card receipt capture.
+  if (stringArg(args["analytics-baseline"])) {
+    assertions.push(...await operations.runParity(args, { target: resolved.analyticsCaptureTarget }));
+  }
+
+  const result = await operations.runOrders({
+    args,
+    resolved,
+    runId,
+    assertions,
+    captureAnalytics: analyticsLeg === "run",
+  });
+  if (analyticsLeg === "run") {
+    assertions.push(operations.assessReceipt(result.receiptAnalytics, { waivers: resolved.qaWaivers }));
+  }
+  return result.orders;
+}
+
+async function finalizeQaRun({ args, resolved, runId, startedAt, assertions, testOrders, commercial = null, runSessionActive = false, browser = null }) {
+  const entryUrls = deriveEntryUrls(resolved.topologies);
+  const pageUrls = derivePageUrls(resolved.topologies);
+  const testedUrls = deriveTestedUrlsFromAssertions(assertions, pageUrls);
+  // Per-finding cause classification happens BEFORE the verdict is assembled,
+  // so the assertions, the derived exceptions, the committed sidecar and the
+  // printed report all carry the same labels. The comparison root is the Build
+  // Packet directory — the same root the Run Record writes under — so the
+  // previous run is found through the existing Run Record discovery rather
+  // than a second scan of qa-output/. The target repo rides along because the
+  // previous run's full verdict lives under ITS qa-output/ (the same default
+  // this run writes to below), which the record references only as
+  // `external:qa_verdict` whenever that is not the packet directory.
+  const causeSummary = annotateQaAssertionCauses(assertions, {
+    baseDir: resolved.packetPath ? dirname(resolved.packetPath) : null,
+    targetRepo: resolved.packetPath ? targetRepoFor(resolved.packetPath, resolved.packet) : null,
+    mapId: resolved.mapId,
+    currentRunId: runId,
+    isFinding: isFindingAssertion,
+  });
+  const verdict = createVerdict({
+    runId,
+    mapId: resolved.mapId,
+    publicRouteSlug: resolved.publicRouteSlug || null,
+    campaignRefId: resolved.spec.campaign?.ref_id || null,
+    specVersion: resolved.specVersion,
+    specHash: resolved.specHash,
+    startedAt,
+    completedAt: new Date().toISOString(),
+    runtime: RUNTIME,
+    operator: process.env.USER ? `${process.env.USER}@local` : "",
+    baseUrl: resolved.baseUrl,
+    entryUrls,
+    pageUrls,
+    testedUrls,
+    assertions,
+    testOrders,
+    commercial,
+    causeSummary,
+    browser,
+  });
+
+  const validationErrors = validateVerdict(verdict);
+  if (validationErrors.length) throw new Error(`QA verdict failed local validation:\n- ${validationErrors.join("\n- ")}`);
+  // Said before the verdict is written and published: a publish that hangs or
+  // fails must not be what decides whether the operator hears about the
+  // downgrade they asked for.
+  reportBrowserSkippedByGate(args, verdict.browser);
+  // The full verdict lands beside the campaign, not beside the caller. The
+  // Run Record reads verdicts back from <target-repo>/qa-output/<slug>/ by
+  // convention, so a default rooted at cwd wrote the file where nothing
+  // would find it and left the record with no path. Packet-less runs
+  // (--site / raw map-id) have no target repo and keep the cwd default;
+  // --output-dir is explicit and always wins.
+  const outputDir = args["output-dir"]
+    ? resolve(args["output-dir"])
+    : resolved.packetPath
+      ? campaignSidecarPaths(targetRepoFor(resolved.packetPath, resolved.packet)).qaOutputDir
+      : resolve("qa-output");
+  const localPath = writeLocalVerdict(verdict, outputDir);
+  // The committed sidecar lands beside the Build Packet regardless of
+  // --output-dir, for every finalized disposition including blocked: it is
+  // what campaigns-agent's readback consumes, and a blocked run the agent can
+  // read faithfully beats a missing artifact. Packet-less runs (--site / raw
+  // map-id) have no packet home, so there is nowhere contracted to write.
+  const sidecar = resolved.packetPath ? writeQaSidecar({ verdict, packetPath: resolved.packetPath }) : null;
+  // Publish to the QA portal by default so runs land in the Campaign Map QA tab without the
+  // operator needing to know a flag (LLM/agent UIs are the primary interface). Opt out with
+  // --no-post-verdict / --local-only / --post-verdict false. Never fail the run if publish is unreachable.
+  // #172: the default rides the telemetry consent seam — consent off means
+  // local-only for non-portal-managed runs; portal-managed campaigns keep
+  // publish-by-default; explicit flags always win.
+  // resolveConsent's default warn stays on: a malformed env value, malformed
+  // config, or scope mismatch should be visible on the QA path too, not just
+  // on remit (Kilo review, PR #177).
+  const consent = resolveConsent({ proxyBase: resolved.proxyBase });
+  const publishDecision = decidePublishVerdict({ args, portalManaged: resolved.portalManaged === true, consent });
+  if (publishDecision.flag_invalid) {
+    process.stderr.write(`[campaigns-os] --post-verdict "${args["post-verdict"]}" is not a recognized value (use true|1|yes|y|on or false|0|no|n|off); the flag was ignored and the default publish decision applied.\n`);
+  }
+  const shouldPublish = publishDecision.publish;
+  const publishDestination = `${resolved.proxyBase.replace(/\/+$/, "")}/api/qa/verdicts`;
+  // One rail with `qa publish`: the outcome is classified by what the portal
+  // answered (a 409 is already_stored, an ok), and the block the Run Record
+  // carries is built here so the auto-end can stamp it without re-deriving.
+  const publishOutcome = shouldPublish ? await publishQaVerdict(verdict, resolved.proxyBase) : skippedQaVerdictPublish();
+  const postResult = publishOutcome.ok ? (publishOutcome.response ?? { ok: true }) : null;
+  const postError = publishOutcome.attempted && !publishOutcome.ok ? publishOutcome.error : null;
+  const dashboardUrl = publishOutcome.ok
+    ? qaPortalUrl(resolved.proxyBase, resolved.mapId, verdict.run_id)
+    : null;
+  return {
+    ok: verdict.disposition !== "blocked",
+    status: verdict.disposition,
+    run_id: verdict.run_id,
+    map_id: resolved.mapId,
+    public_route_slug: resolved.publicRouteSlug || null,
+    ...reportPathField(resolved),
+    base_url: resolved.baseUrl,
+    entry_urls: entryUrls,
+    page_urls: pageUrls,
+    tested_urls: testedUrls,
+    dashboard_url: dashboardUrl,
+    local_path: localPath,
+    qa_sidecar: sidecar,
+    posted: postResult,
+    post_error: postError,
+    publish_skipped: !shouldPublish,
+    // The classified outcome (attempted, ok, error, endpoint, result,
+    // http_status, base_kind) and the Run Record block derived from it.
+    publish: { ...publishOutcome, response: undefined },
+    qa_verdict_publish: qaVerdictPublishBlock(publishOutcome, { verdictRunId: verdict.run_id, publisher: QA_VERDICT_PUBLISHERS.run, publishedAt: new Date().toISOString() }),
+    publish_decision: { ...publishDecision, destination: publishDestination, consent_state: consent?.state ?? null },
+    counts: countAssertions(verdict.assertions),
+    theme_gate: themeGateSummary(resolved.themeGate),
+    polish_gate: polishGateSummary(resolved.polishGate),
+    browser: verdict.browser || null,
+    commercial: verdict.commercial || null,
+    next_actions: buildQaCloseoutActions({ packetPath: resolved.packetPath, localPath, runSessionActive, disposition: verdict.disposition }),
+    verdict,
+  };
+}
+
+const ENTRY_PAGE_TYPES = new Set([
+  "entry",
+  "presell",
+  "landing",
+  "lander",
+  "opt-in",
+  "optin",
+  "advertorial",
+  "listicle",
+  "review",
+]);
+
+function deriveEntryUrls(topologies) {
+  const entries = [];
+  for (const topology of topologyList(topologies)) {
+    const pages = Array.isArray(topology?.pages) ? topology.pages.filter((page) => page?.url) : [];
+    if (!pages.length) continue;
+    const page = pages.find(isEntryLikePage) || pages[0];
+    entries.push({
+      funnel_id: topology.funnel_id || "default",
+      funnel_name: topology.funnel_name || topology.funnel_id || "default",
+      page_id: page.page_id || null,
+      page_type: page.page_type || null,
+      label: page.label || null,
+      url: page.url,
+    });
+  }
+  return entries;
+}
+
+function isEntryLikePage(page) {
+  const type = String(page?.page_type || "").toLowerCase().trim();
+  return ENTRY_PAGE_TYPES.has(type);
+}
+
+function derivePageUrls(topologies) {
+  const seen = new Set();
+  const urls = [];
+  for (const topology of topologyList(topologies)) {
+    for (const page of Array.isArray(topology?.pages) ? topology.pages : []) {
+      if (!page?.url || seen.has(page.url)) continue;
+      seen.add(page.url);
+      urls.push({
+        funnel_id: topology.funnel_id || "default",
+        page_id: page.page_id || null,
+        page_type: page.page_type || null,
+        label: page.label || null,
+        url: page.url,
+      });
+    }
+  }
+  return urls;
+}
+
+function deriveTestedUrlsFromAssertions(assertions, pageUrls = []) {
+  const knownByUrl = new Map();
+  const knownByPageId = new Map();
+  for (const entry of Array.isArray(pageUrls) ? pageUrls : []) {
+    if (entry?.url && !knownByUrl.has(entry.url)) knownByUrl.set(entry.url, entry);
+    if (entry?.page_id && !knownByPageId.has(entry.page_id)) knownByPageId.set(entry.page_id, entry);
+  }
+
+  const seen = new Set();
+  const tested = [];
+  for (const assertion of Array.isArray(assertions) ? assertions : []) {
+    if (!String(assertion?.id || "").startsWith("http:") || !assertion?.url || seen.has(assertion.url)) continue;
+    seen.add(assertion.url);
+    const known = knownByUrl.get(assertion.url) || knownByPageId.get(String(assertion.id).slice("http:".length));
+    tested.push(known || {
+      funnel_id: null,
+      page_id: String(assertion.id).slice("http:".length) || assertion.page || null,
+      page_type: null,
+      label: null,
+      url: assertion.url,
+    });
+  }
+  return tested;
+}
+
+function topologyList(topologies) {
+  return Array.isArray(topologies) ? topologies : [];
+}
+
+async function runPageChecks(page, args, {
+  sourceLoader = createPageSourceLoader({ authCookie: args["auth-cookie"] }),
+  captureCommercial = false,
+  bindingExpected = { value: null },
+  bindingScriptLoader = createBindingScriptLoader(),
+} = {}) {
+  const assertions = [];
+  if (!page.url) {
+    assertions.push(bindingAssertion(page, await observeBinding({ source: null, page, expected: bindingExpected, scriptLoader: bindingScriptLoader })));
+    assertions.push(assertion({
+      id: `route-url:${page.page_id}`,
+      family: "funnel-flow",
+      page,
+      status: STATUS.FAIL,
+      severity: SEVERITY.BLOCKER,
+      expected: "deployed URL",
+      actual: null,
+      evidence: { transport_error: { code: "missing_url", message: "No page URL could be resolved. Provide --base-url or explicit spec page URLs." } },
+    }));
+    return {
+      assertions,
+      commercialCapture: captureCommercial
+        ? unavailableCommercialCapture(page, new Error("No page URL was resolved."))
+        : null,
+    };
+  }
+
+  const source = await sourceLoader(page);
+  assertions.push(bindingAssertion(page, await observeBinding({ source, page, expected: bindingExpected, scriptLoader: bindingScriptLoader })));
+  if (!source.ok) {
+    const isHttpStatus = source.error_code === "http_status";
+    assertions.push(assertion({
+      id: `http:${page.page_id}`,
+      family: "funnel-flow",
+      page,
+      status: STATUS.FAIL,
+      severity: SEVERITY.BLOCKER,
+      expected: isHttpStatus ? "2xx HTTP response" : "fetchable bounded deployed page",
+      actual: isHttpStatus ? `${source.status} ${source.status_text}`.trim() : null,
+      evidence: { transport_error: { code: source.error_code, message: source.error } },
+    }));
+    return {
+      assertions,
+      commercialCapture: captureCommercial
+        ? unavailableCommercialCapture(page, new Error(`${source.error_code}: ${source.error}`))
+        : null,
+    };
+  }
+  const html = source.html;
+  const commercialCapture = captureCommercial ? captureCommercialClaims(page, html) : null;
+  assertions.push(assertion({
+    id: `http:${page.page_id}`,
+    family: "funnel-flow",
+    page,
+    status: STATUS.PASS,
+    expected: "2xx HTTP response",
+    actual: `${source.status} ${source.status_text}`.trim(),
+  }));
+
+  const expectedMeta = page.expected_meta_tags || {};
+  const actualMeta = extractMetaTags(html);
+  for (const [name, expected] of Object.entries(expectedMeta)) {
+    // Redact both credential-shaped hints from this generic serializer. The legacy
+    // next-campaign-api-key alias can be authored here, but is not SDK binding evidence.
+    if (["next-api-key", "next-campaign-api-key"].includes(name)) continue;
+    const actual = actualMeta[name] || null;
+    const unsupportedHint = unsupportedSdkMetaHint(name);
+    if (unsupportedHint) {
+      // A spec key the SDK does not read is a stale Map page hint, whether or
+      // not the tag rendered: nothing for a human to review, so `warn`, never
+      // `manual_review`. Doctor reports the same key as
+      // sdk_hints.meta_tags.ignored_by_sdk from the same list.
+      assertions.push(assertion({
+        id: `meta:${page.page_id}:${name}`,
+        family: "meta-tags",
+        page,
+        status: STATUS.WARN,
+        severity: SEVERITY.WARN,
+        expected: unsupportedHint.expected,
+        actual: actual
+          ? `${actual} (present but ignored by Campaign Cart)`
+          : unsupportedHint.actual,
+        evidence: {
+          expected,
+          actual,
+          note: unsupportedHint.note,
+        },
+      }));
+      continue;
+    }
+    const matches = metaTagMatches(name, actual, expected);
+    assertions.push(assertion({
+      id: `meta:${page.page_id}:${name}`,
+      family: "meta-tags",
+      page,
+      status: matches ? STATUS.PASS : STATUS.FAIL,
+      severity: matches ? undefined : SEVERITY.BLOCKER,
+      expected,
+      actual,
+      evidence: matches ? undefined : { expected, actual },
+    }));
+  }
+
+  // A page that declared a forward step and resolved to nothing is a dead end:
+  // the shopper reaches it and cannot continue. Asserted BEFORE the loop below,
+  // because that loop skips on a falsy URL — which is correct for a page that
+  // terminates on purpose and silently wrong for this one. Without this, the
+  // funnel-flow family emits ZERO assertions for the broken page and the run
+  // comes back clean.
+  const ignoredForwardFields = Array.isArray(page.ignored_forward_fields) ? page.ignored_forward_fields : [];
+  if (!page.expected_next_url && ignoredForwardFields.length) {
+    const fields = ignoredForwardFields.join(", ");
+    const applicable = Array.isArray(page.applicable_forward_fields) ? page.applicable_forward_fields : [];
+    // Name the fields this page type can actually route from. `next_page` is
+    // right for a selector step and wrong for an upsell, whose forward step is
+    // `on_accept` — a hint that named one field for every page type would send
+    // an upsell author straight past their own offer.
+    const remedy = applicable.length
+      ? `Declare one of the forward fields this page type can route from: ${applicable.join(", ")}.`
+      : "Declare a forward route this page type can satisfy.";
+    assertions.push(assertion({
+      id: `forward-route:${page.page_id}:resolves`,
+      family: "funnel-flow",
+      page,
+      status: STATUS.FAIL,
+      severity: SEVERITY.BLOCKER,
+      expected: "a forward route the shopper can follow",
+      actual: `none — "${fields}" declared but ignored on a "${page.page_type}" page`,
+      evidence: {
+        ignored_forward_fields: ignoredForwardFields,
+        applicable_forward_fields: applicable,
+        note: `"${fields}" cannot route from a "${page.page_type}" page, and no other forward field is declared, so the built page has no next link. ${remedy}`,
+      },
+    }));
+  }
+
+  for (const [kind, expectedUrl] of [
+    ["next", page.expected_next_url],
+    ["accept", page.expected_accept_url],
+    ["decline", page.expected_decline_url],
+  ]) {
+    if (!expectedUrl) continue;
+    const staticFound = htmlIncludesRouteReference(html, expectedUrl);
+    const sdkAction = staticFound ? null : findSdkRouteAction(html, kind, page);
+    const found = staticFound || Boolean(sdkAction);
+    assertions.push(assertion({
+      id: `route-link:${page.page_id}:${kind}`,
+      family: "funnel-flow",
+      page,
+      status: found ? STATUS.PASS : STATUS.MANUAL_REVIEW,
+      severity: found ? undefined : SEVERITY.WARN,
+      expected: expectedUrl,
+      actual: staticFound ? expectedUrl : sdkAction || "not found in static HTML",
+      evidence: found ? (sdkAction ? { expected: expectedUrl, sdk_action: sdkAction } : undefined) : { expected: expectedUrl, note: "Route may be SDK/runtime-derived; verify manually if absent from static HTML." },
+    }));
+  }
+
+  return { assertions, commercialCapture };
+}
+
+async function maybeRunTestOrders(
+  { args, resolved, runId, assertions, captureAnalytics = false },
+  overrides = {},
+) {
+  const operations = {
+    runBrowser: runBrowserTestOrders,
+    runLegacy: maybeRunLegacyApiTestOrders,
+    ...overrides,
+  };
+  const mode = String(args["test-order"] || "off").toLowerCase();
+  const legacyMode = String(args["legacy-api-test-order"] || "off").toLowerCase();
+  const emptyReceiptAnalytics = () => ({ plannedPlanIds: [], attempts: [] });
+  if ((!mode || mode === "off") && (!legacyMode || legacyMode === "off")) {
+    return { orders: [], receiptAnalytics: emptyReceiptAnalytics() };
+  }
+  if (mode && mode !== "off") {
+    // Test Orders use global test cards: they bypass the payment gateway, create
+    // no transactions, and need no merchant setup or approval. `--test-order
+    // <mode>` is sufficient intent — no permission flags or packet policy gate.
+    const result = await operations.runBrowser(resolved.topologies, args, runId, { captureAnalytics });
+    assertions.push(...result.assertions);
+    return { orders: result.orders, receiptAnalytics: result.receiptAnalytics || emptyReceiptAnalytics() };
+  }
+
+  const orders = await operations.runLegacy({ args: { ...args, "test-order": legacyMode }, resolved, runId, assertions });
+  // Direct API diagnostics never qualify as canonical receipt proof.
+  return { orders, receiptAnalytics: emptyReceiptAnalytics() };
+}
+
+async function maybeRunLegacyApiTestOrders({ args, resolved, runId, assertions }) {
+  const mode = String(args["test-order"] || "off").toLowerCase();
+  if (!mode || mode === "off") return [];
+  // Diagnostic-only legacy path. Like the browser path, it needs no permission
+  // flags or packet policy gate — test cards bypass the gateway. It still needs
+  // API credentials because it talks to the Campaigns API directly.
+  const apiKey = stringArg(args["api-key"]) || process.env.QA_CAMPAIGNS_API_KEY;
+  const apiBase = stringArg(args["campaigns-api-base"]) || process.env.CAMPAIGNS_API_BASE;
+  if (!apiKey || !apiBase) throw new Error("Legacy direct API test orders require --api-key/QA_CAMPAIGNS_API_KEY and --campaigns-api-base/CAMPAIGNS_API_BASE.");
+  const cart = parseCart(args.cart);
+  if (!cart.length) throw new Error("--test-order requires --cart package_id:quantity pairs.");
+  const checkout = findPage(resolved.topologies, "checkout");
+  if (!checkout?.url) throw new Error("--test-order requires a checkout page URL.");
+  const upsell = findPage(resolved.topologies, "upsell");
+  const paths = mode === "both" ? ["accept", "decline"] : [mode];
+  const orders = [];
+  for (const path of paths) {
+    if (!["accept", "decline"].includes(path)) throw new Error(`Unknown --test-order mode: ${mode}`);
+    const create = await createTestOrder({ apiBase, apiKey, cart, runId, successUrl: checkout.expected_next_url || upsell?.url || checkout.url, spec: resolved.spec, args });
+    const verification = { expected_line_count: cart.length, actual_line_count: 0, diff: [], verified: false };
+    if (!create.ok) {
+      verification.error = create.error || "order create failed";
+      assertions.push(assertion({
+        id: `test-order:${path}`,
+        family: "api-metadata",
+        page: checkout,
+        status: STATUS.FAIL,
+        severity: SEVERITY.BLOCKER,
+        expected: "test order created",
+        actual: create.error || create.status,
+      }));
+    } else {
+      assertions.push(assertion({
+        id: `test-order:${path}`,
+        family: "api-metadata",
+        page: checkout,
+        status: STATUS.PASS,
+        expected: "test order created",
+        actual: create.number || create.ref_id,
+      }));
+      verification.actual_line_count = Array.isArray(create.raw?.lines) ? create.raw.lines.length : cart.length;
+      verification.verified = true;
+    }
+    orders.push({
+      path,
+      next_order_id: create.number,
+      qa_run_id_tag: runId,
+      cart_state: { packages: cart.map((item) => ({ ref_id: item.packageId, quantity: item.quantity })) },
+      receipt_line_items: extractReceiptLines(create.raw),
+      verification,
+    });
+  }
+  return orders;
+}
+
+async function createTestOrder({ apiBase, apiKey, cart, runId, successUrl, spec, args = {} }) {
+  const shippingMethod = firstShippingMethod(spec);
+  const body = {
+    user: { email: testEmail(args), first_name: "QA", last_name: "Test" },
+    lines: cart.map((item) => ({ package_id: Number(item.packageId), quantity: item.quantity })),
+    shipping_address: {
+      first_name: "QA",
+      last_name: "Test",
+      line1: "123 Test St",
+      line4: "Austin",
+      state: "TX",
+      postcode: "78701",
+      phone_number: "+14807581224",
+      country: "US",
+    },
+    billing_same_as_shipping_address: true,
+    payment_detail: { payment_method: "card_token", card_token: "test_card" },
+    shipping_method: shippingMethod,
+    success_url: successUrl,
+    payment_failed_url: `${successUrl}${successUrl.includes("?") ? "&" : "?"}payment_failed=true`,
+    attribution: { utm_source: "agentic_qa", qa_run_id: runId },
+  };
+  try {
+    const response = await fetch(`${apiBase.replace(/\/+$/, "")}/orders/`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Accept: "application/json", Authorization: apiKey },
+      body: JSON.stringify(body),
+    });
+    const raw = await response.json().catch(() => null);
+    return {
+      ok: response.ok,
+      status: response.status,
+      raw,
+      ref_id: typeof raw?.ref_id === "string" ? raw.ref_id : null,
+      number: Number.isFinite(Number(raw?.number || raw?.id)) ? Number(raw?.number || raw?.id) : null,
+      error: response.ok ? null : extractApiError(raw) || `${response.status} ${response.statusText}`,
+    };
+  } catch (error) {
+    return { ok: false, status: null, raw: null, ref_id: null, number: null, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function normalizeSpec(raw) {
+  if (Array.isArray(raw?.funnels)) return raw;
+  if (Array.isArray(raw?.funnel_pages)) {
+    return { ...raw, funnels: [{ id: "default", name: "Default", weight: 100, pages: raw.funnel_pages }] };
+  }
+  return { ...raw, funnels: [] };
+}
+
+function extractTopologies(spec, { baseUrl = null, publicRouteSlug = null, templateFamily = null, commerceStructureContract = null } = {}) {
+  const pageById = new Map();
+  for (const funnel of spec.funnels || []) {
+    for (const page of funnel.pages || []) pageById.set(page.id, page);
+  }
+  const urlById = new Map();
+  for (const [id, page] of pageById) {
+    urlById.set(id, resolvePageUrl(page, baseUrl, publicRouteSlug));
+  }
+  return (spec.funnels || []).map((funnel) => ({
+    funnel_id: funnel.id || "default",
+    funnel_name: funnel.name || funnel.id || "Default",
+    weight: Number(funnel.weight) || 0,
+    pages: (funnel.pages || [])
+      .filter((page) => page.enabled !== false)
+      .slice()
+      .sort((a, b) => (a.order || 0) - (b.order || 0))
+      .map((page) => ({
+        page_id: page.id,
+        page_type: page.type || "page",
+        order: page.order || 0,
+        label: page.label || page.id,
+        url: urlById.get(page.id) || null,
+        is_entry: Boolean(page.is_entry),
+        expected_meta_tags: extractExpectedMetaTags(page, { baseUrl, pageById, urlById, publicRouteSlug }),
+        // Same resolver as build-time wiring. This previously read
+        // `next_page || success_url` and ignored on_accept entirely, so the QA
+        // expectation and the built page could disagree about which declared
+        // field wins on any page carrying more than one.
+        expected_next_url: resolveSibling(pageById, urlById, forwardRouteTarget(page), baseUrl, publicRouteSlug),
+        // acceptRouteTarget, never `page.on_accept` raw. Reading the field
+        // directly outlived its correctness: since #234 gated `on_accept` to
+        // offer pages, a `select` page's inert on_accept produced an
+        // expected_accept_url, so QA hunted for an accept link the built page
+        // correctly does not have and flagged a correct build.
+        expected_accept_url: resolveSibling(pageById, urlById, acceptRouteTarget(page), baseUrl, publicRouteSlug),
+        expected_decline_url: resolveSibling(pageById, urlById, declineRouteTarget(page), baseUrl, publicRouteSlug),
+        // Forward fields the author declared that routing skipped because this
+        // page type cannot satisfy them. Carried into the topology so QA can
+        // tell "terminates on purpose" (a thank-you page, a partial-scope
+        // hand-off) apart from "meant to continue and lost its only edge",
+        // which are indistinguishable from a null expected_next_url alone.
+        ...(inapplicableForwardFields(page).length
+          ? {
+              ignored_forward_fields: inapplicableForwardFields(page),
+              // The fields this page TYPE could route from, so the remediation
+              // hint can name the right one. Derived from the resolver, never
+              // hardcoded: telling an upsell author to "set next_page" would
+              // route the shopper past the offer entirely.
+              applicable_forward_fields: applicableForwardFields(page),
+            }
+          : {}),
+        packages: page.packages || [],
+        ...(page.exit_intent !== undefined ? { exit_intent: page.exit_intent } : {}),
+        ...(page.promo_code_input !== undefined ? { promo_code_input: page.promo_code_input } : {}),
+        template_family: templateFamily || undefined,
+        commerce_structure_contract: commerceStructureContract?.pages?.[page.type || "page"] || undefined,
+        commerce_structure_contract_status: commerceStructureContract?.status || undefined,
+      })),
+  }));
+}
+
+function resolvePageUrl(page, baseUrl, publicRouteSlug = null) {
+  if (typeof page.url === "string" && page.url.trim()) return page.url.trim();
+  if (!baseUrl) return null;
+  const route = typeof page.page_url === "string" && page.page_url.trim()
+    ? runtimeRelativeRouteForSpecValue(page.page_url, publicRouteSlug)
+    : page.is_entry
+      ? ""
+      : defaultRouteForType(page.type);
+  if (isAbsoluteHttpUrl(route)) return route;
+  try {
+    return joinBaseUrl(baseUrl, route);
+  } catch {
+    return null;
+  }
+}
+
+function defaultRouteForType(type) {
+  if (type === "thankyou") return "receipt/";
+  if (["presell", "landing", "checkout", "upsell", "downsell"].includes(type)) return `${type}/`;
+  return `${type || "page"}/`;
+}
+
+function resolveSibling(pageById, urlById, ref, baseUrl, publicRouteSlug = null) {
+  if (typeof ref !== "string" || !ref.trim()) return undefined;
+  if (urlById.has(ref)) return urlById.get(ref) || null;
+  if (isAbsoluteHttpUrl(ref)) return ref;
+  if (baseUrl && (ref.startsWith("/") || ref.includes(".") || ref.endsWith("/"))) {
+    try {
+      return joinBaseUrl(baseUrl, runtimeRelativeRouteForSpecValue(ref, publicRouteSlug) || ref);
+    } catch {
+      return ref;
+    }
+  }
+  return ref;
+}
+
+function joinBaseUrl(baseUrl, route) {
+  const base = new URL(baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
+  const normalizedRoute = route.replace(/^\/+/, "");
+  const baseSegments = base.pathname.split("/").filter(Boolean);
+  const routeSegments = normalizedRoute.split("/").filter(Boolean);
+  if (baseSegments.length && routeSegments.length && baseSegments.at(-1) === routeSegments[0]) {
+    return new URL(normalizedRoute, `${base.origin}/`).toString();
+  }
+  return new URL(normalizedRoute, base).toString();
+}
+
+function extractExpectedMetaTags(page, { baseUrl, pageById, urlById, publicRouteSlug } = {}) {
+  const source = page.sdk_hints?.meta_tags;
+  if (!source || typeof source !== "object") return undefined;
+  const out = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (typeof value !== "string") continue;
+    if (isRoutingMetaTag(key)) {
+      const resolved = resolveSibling(pageById || new Map(), urlById || new Map(), value, baseUrl, publicRouteSlug);
+      out[key] = stripOrigin(resolved || value);
+    } else {
+      out[key] = value;
+    }
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+function extractMetaTags(html) {
+  const meta = {};
+  const tagPattern = /<meta\b[^>]*>/gi;
+  const attrPattern = /([a-zA-Z_:.-]+)\s*=\s*["']([^"']*)["']/g;
+  for (const tag of html.match(tagPattern) || []) {
+    const attrs = {};
+    for (const match of tag.matchAll(attrPattern)) attrs[match[1].toLowerCase()] = decodeHtml(match[2]);
+    const key = attrs.name || attrs.property;
+    if (key && attrs.content !== undefined) meta[key] = attrs.content;
+  }
+  return meta;
+}
+
+// Packet 04 Stage A / IC-2 dispatch table for the analytics-correctness leg.
+// forced is the tri-state from forcedAnalyticsCorrectness():
+//   false     → "disabled"       (explicit opt-out wins, even over a declared analytics block)
+//   true      → "run"            (forced, with or without a block)
+//   undefined → "run" iff the spec declares an analytics block, else "not-applicable"
+function analyticsCorrectnessLegDecision(forced, analyticsContract) {
+  if (forced === false) return "disabled";
+  if (analyticsContract || forced === true) return "run";
+  return "not-applicable";
+}
+
+// The visible marker for an explicit opt-out — same skipped-assertion
+// convention the polish/theme gates use. SKIPPED is disposition-neutral
+// (computeDisposition ignores it), so the marker records the decision without
+// gating the run.
+function analyticsCorrectnessDisabledAssertion(analyticsContract) {
+  return assertion({
+    id: "analytics-correctness:disabled-by-flag",
+    family: "analytics-correctness",
+    page: { page_id: "campaign" },
+    status: STATUS.SKIPPED,
+    expected: "analytics-correctness leg runs when the spec declares an analytics block",
+    actual: "--analytics-correctness false — leg explicitly disabled by operator flag",
+    evidence: {
+      flag: "analytics-correctness=false",
+      spec_declares_analytics: !!analyticsContract,
+    },
+  });
+}
+
+function assertion({ id, family, page, status, severity, expected, actual, evidence, waiver }) {
+  return {
+    id,
+    family,
+    page: page.page_id || page.label || "campaign",
+    url: page.url || undefined,
+    status,
+    ...(severity ? { severity } : {}),
+    ...(expected !== undefined ? { expected } : {}),
+    ...(actual !== undefined ? { actual } : {}),
+    ...(evidence ? { evidence } : {}),
+    ...(waiver ? { waiver } : {}),
+  };
+}
+
+// Every QA artifact lands in <output-dir>/<campaign-slug>/. The slug can come
+// from fixture or spec data, so containment is asserted here rather than
+// trusted: a run refuses to write outside the directory the operator named.
+function campaignOutputDir(outputDir, slug) {
+  const root = resolve(outputDir);
+  const dir = resolve(root, String(slug || ""));
+  const rel = relative(root, dir);
+  if (!rel || rel.startsWith("..") || isAbsolute(rel)) {
+    throw new Error(`QA output slug "${slug}" escapes the output directory ${root}.`);
+  }
+  return dir;
+}
+
+function writeLocalVerdict(verdict, outputDir) {
+  const dir = campaignOutputDir(outputDir, verdict.campaign_slug);
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, `${verdict.run_id}.json`);
+  writeFileSync(path, `${JSON.stringify(verdict, null, 2)}\n`);
+  return path;
+}
+
+function output(value, args) {
+  if (args.json) {
+    console.log(JSON.stringify(value, null, 2));
+    return;
+  }
+  if (value.action === "qa-publish") {
+    for (const line of qaPublishTextLines(value, { cmd })) console.log(line);
+    return;
+  }
+  if (value.action === "qa-policy-set") {
+    console.log(`QA metadata updated.`);
+    console.log(`Packet: ${value.packet_path}`);
+    console.log(`Changed: ${value.changed.length ? value.changed.join(", ") : "(none)"}`);
+    return;
+  }
+  if (value.verdict) {
+    console.log(`QA run complete.`);
+    console.log(`Map ID: ${value.map_id}`);
+    console.log(`Base URL: ${value.base_url || "(missing)"}`);
+    printEntryUrlLines(value.entry_urls);
+    console.log(`Run ID: ${value.run_id}`);
+    console.log(`Disposition: ${value.verdict.disposition}`);
+    console.log(`Counts: ${Object.entries(value.counts).map(([status, count]) => `${count} ${status}`).join(", ")}`);
+    printCauseLines(value.verdict);
+    printThemeGateLines(value.theme_gate, value.packet_path, value.report_path);
+    if (value.commercial) {
+      console.log(`Commercial parity: ${value.commercial.status} (${value.commercial.finding_count || 0} findings, ${value.commercial.checked_pages || 0} pages checked)`);
+    }
+    console.log(`Local copy: ${value.local_path}`);
+    if (value.posted?.ok && value.dashboard_url) {
+      console.log(`QA portal: ${value.dashboard_url}`);
+    } else if (value.publish_skipped && value.publish_decision?.reason === "consent_off") {
+      console.log(`QA portal: publish skipped — telemetry consent is off, so this non-portal-managed verdict stays local.`);
+      console.log(`  Destination would be ${value.publish_decision.destination}. Opt in for this run with --post-verdict, or enable with \`${cmd("telemetry")} on\`.`);
+    } else if (value.publish_skipped) {
+      console.log(`QA portal: publish skipped (--no-post-verdict); local verdict only.`);
+    } else {
+      console.log(`QA portal: publish failed${value.post_error ? ` (${value.post_error})` : ""}; local verdict kept at ${value.local_path}. Re-run with network access, or pass --no-post-verdict to silence.`);
+    }
+    for (const action of value.next_actions || []) {
+      if (action.required) {
+        console.log(`Required next: ${action.command}`);
+        console.log(`  ${action.description}`);
+      }
+    }
+    console.log(`Workflow finding? ${cmd("findings")} add --stage qa --kind missing_prompt --summary "..." --qa-run-id ${value.run_id}`);
+    return;
+  }
+  console.log(`QA resolve complete.`);
+  console.log(`Status: ${value.status}`);
+  console.log(`Map ID: ${value.map_id}`);
+  console.log(`Spec: ${value.spec_source}`);
+  console.log(`Base URL: ${value.base_url || "(missing)"}`);
+  printEntryUrlLines(value.entry_urls);
+  for (const funnel of value.funnels) {
+    console.log(`\n${funnel.funnel_name} (${funnel.funnel_id}, ${funnel.weight}%)`);
+    for (const page of funnel.pages) console.log(`- [${page.page_type}] ${page.label}: ${page.url || "(missing)"}`);
+  }
+  console.log("");
+  printCheckpointGateLines(value.checkpoint_gates, value.packet_path, value.report_path);
+  printThemeGateLines(value.theme_gate, value.packet_path, value.report_path);
+  printRouteProbeLines(value.route_probe);
+  const nextProofLines = qaResolveNextProofLines(value);
+  if (nextProofLines.length) {
+    console.log("");
+    for (const line of nextProofLines) console.log(line);
+  }
+}
+
+// The checkpoint block of the `qa resolve` text report. Returns the lines in
+// order so the text is assertable without a subprocess; the printer prints
+// the join. Each action is rendered by the one rule doctor uses (the packet
+// substituted, else the description, and `--report` carried into a
+// packet-scoped command when the gates were evaluated on a non-default
+// report), so the same blocked gate reads the same way in both reports.
+export function checkpointGateLines(checkpointGates, packetPath, reportPath = null) {
+  const lines = [];
+  for (const gate of checkpointGates || []) {
+    lines.push(`Checkpoint ${gate.id}: ${gate.status} (${gate.code}) — ${gate.reason}`);
+    if (gate.waiver) {
+      lines.push(`  Waiver: ${gate.waiver.waived_by} at ${gate.waiver.waived_at} — ${gate.waiver.reason}`);
+      if (gate.waiver.expires_at) lines.push(`  Expires: ${gate.waiver.expires_at}`);
+      if (gate.waiver.review_condition) lines.push(`  Review condition: ${gate.waiver.review_condition}`);
+    }
+    const counts = gate.waiver_assessment?.inert_counts || {};
+    lines.push(`  Inert waiver decisions: stale=${counts.stale || 0}, foreign=${counts.foreign || 0}, malformed=${counts.malformed || 0}, expired=${counts.expired || 0}`);
+    if (gate.required_actions?.length) {
+      lines.push("  Required actions:");
+      for (const action of gate.required_actions) {
+        lines.push(`    - ${requiredActionText(action, { packetPath, reportPath })}`);
+      }
+    }
+  }
+  return lines;
+}
+
+function printCheckpointGateLines(checkpointGates, packetPath, reportPath = null) {
+  for (const line of checkpointGateLines(checkpointGates, packetPath, reportPath)) console.log(line);
+}
+
+function printEntryUrlLines(entryUrls) {
+  if (!Array.isArray(entryUrls) || !entryUrls.length) return;
+  console.log("Entry URLs:");
+  for (const entry of entryUrls) {
+    const label = [entry.funnel_name || entry.funnel_id, entry.page_type, entry.label]
+      .filter(Boolean)
+      .join(" / ");
+    console.log(`- ${label || entry.page_id || "entry"}: ${entry.url}`);
+  }
+}
+
+function printRouteProbeLines(routeProbe) {
+  if (!routeProbe) return;
+  console.log(`Route probe: ${routeProbe.status} (${routeProbe.code}) — ${routeProbe.reason}`);
+  if (routeProbe.route_root_hint) {
+    console.log(`  Diagnosis (${routeProbe.route_root_hint.code}): ${routeProbe.route_root_hint.reason}`);
+  }
+  // Per-URL evidence for anything that did not cleanly resolve, on EVERY status
+  // rather than only on failure: a `pass` reached over some unreachable URLs is
+  // partial reachability an operator should be able to read, not infer from an
+  // aggregate count. The single-row case is skipped because every reason line
+  // that can produce one already names that URL.
+  const rows = (routeProbe.results || [])
+    .filter((result) => result.outcome === "unresolved" || result.outcome === "unreachable");
+  if (!rows.length) return;
+  if (rows.length === 1 && rows[0].url === routeProbe.first_failure?.url) return;
+  console.log("  Entry URLs that did not resolve:");
+  for (const row of rows) {
+    console.log(`    - ${row.url} (${row.outcome === "unresolved" ? `HTTP ${row.http_status}` : row.error})`);
+  }
+}
+
+// The cause read: one summary line, then one line per finding carrying its
+// class. This is the answer to "are these findings related to the change I am
+// testing?" — the question a bump run left unanswerable before the label
+// existed. Printed right under the status counts, above the gate lines,
+// because it is what the operator is looking for.
+function printCauseLines(verdict) {
+  // One formatter, shared with the doctor report: a prior record that exists
+  // but has no usable QA verdict is not the same state as no prior record, and
+  // the two commands must not describe it differently.
+  for (const line of formatCauseReportLines(verdict?.cause_summary)) console.log(line);
+  const exceptions = Array.isArray(verdict.exceptions) ? verdict.exceptions : [];
+  if (!exceptions.length) return;
+  console.log("Findings:");
+  for (const exception of exceptions) {
+    const identity = [exception.id, exception.page].filter(Boolean).join(" @ ") || "(unidentified finding)";
+    const tag = formatCauseTag(exception);
+    console.log(`- ${identity} (${exception.status || "unknown"})${tag ? ` ${tag}` : ""}`);
+  }
+}
+
+// The theme-gate block of the `qa resolve` / `qa run` text report, as lines.
+// The gate bakes the packet into its commands when it is evaluated, so the
+// substitution here is the same rule applied uniformly, not a change of text.
+export function themeGateLines(themeGate, packetPath = null, reportPath = null) {
+  if (!themeGate) return [];
+  const lines = [`Theme gate: ${themeGate.status} (${themeGate.code}) — ${themeGate.reason}`];
+  if (themeGate.status !== "blocked") return lines;
+  lines.push("Required actions:");
+  for (const action of themeGate.required_actions || []) {
+    lines.push(`  - ${requiredActionText(action, { packetPath, reportPath })}`);
+  }
+  lines.push("Or rerun with --theme-waive \"<reason>\" to record an ephemeral waiver for this run.");
+  return lines;
+}
+
+function printThemeGateLines(themeGate, packetPath = null, reportPath = null) {
+  for (const line of themeGateLines(themeGate, packetPath, reportPath)) console.log(line);
+}
+
+export function qaResolveNextProofLines(value) {
+  if (value?.status === "blocked") return [];
+  // #273: the printed next command was the most misleading part of a `ready`
+  // over a dead route set — `qa run` against those URLs cannot succeed. Name
+  // the route set as the thing to fix instead of suggesting the run.
+  if (value?.status === "routes_unresolved") {
+    const failure = value.route_probe?.first_failure;
+    const hint = value.route_probe?.route_root_hint;
+    const remedy = hint?.code === "route_probe.route_root_mismatch"
+      ? "Correct campaign.public_route_slug (or declare campaign.route_root) in the packet so the derived routes match this host, then resolve again."
+      : hint?.code === "route_probe.host_also_dead"
+        ? "Confirm the preview is live, then resolve again."
+        : "Confirm the preview is live and that --base-url names the host serving this packet's campaign, then resolve again.";
+    return [
+      `Next expected proof: none — the derived route set does not resolve on ${value.base_url || "(missing base URL)"}.`,
+      `First failure: ${failure?.url || "(unknown)"}${failure?.http_status ? ` (HTTP ${failure.http_status})` : ""}.`,
+      remedy,
+    ];
+  }
+  if (!value?.base_url) {
+    return [
+      "Next expected proof: provide --base-url with the preview/local campaign URL, then run browser QA + typed-card proof with --browser --test-order common.",
+      "Localhost on any port is SDK-allowed with analytics suppressed; non-localhost preview/production origins still need SDK origin allowlist confirmation.",
+    ];
+  }
+
+  return [
+    `Next expected proof: ${qaRunCommandFromResolve(value)}`,
+    `Entry URL(s) resolved: ${formatEntryUrlsForProof(value.entry_urls)}`,
+    "Typed-card test orders use global test cards (no transactions/no permission gate); QA publishes to the portal by default.",
+  ];
+}
+
+function formatEntryUrlsForProof(entryUrls) {
+  if (!Array.isArray(entryUrls) || !entryUrls.length) return "(none)";
+  return entryUrls.map((entry) => entry.url).filter(Boolean).join(", ") || "(none)";
+}
+
+function qaRunCommandFromResolve(value) {
+  const base = shellToken(value.base_url);
+  const proxy = value.proxy_base ? ` --proxy-base ${shellToken(value.proxy_base)}` : "";
+  if (value.packet_path) {
+    return `${cmd("qa")} run --packet ${shellToken(value.packet_path)}${proxy} --base-url ${base} --browser --test-order common`;
+  }
+  if (isLocalFilePath(value.spec_source)) {
+    return `${cmd("qa")} run ${shellToken(value.map_id)} --spec ${shellToken(value.spec_source)}${proxy} --base-url ${base} --browser --test-order common`;
+  }
+  return `${cmd("qa")} run ${shellToken(value.map_id)}${proxy} --base-url ${base} --browser --test-order common`;
+}
+
+function isLocalFilePath(value) {
+  return typeof value === "string" && value.trim() && !isAbsoluteHttpUrl(value);
+}
+
+
+function countAssertions(assertions) {
+  const counts = {};
+  for (const assertion of assertions) counts[assertion.status] = (counts[assertion.status] || 0) + 1;
+  return counts;
+}
+
+function computeSpecHash(spec) {
+  return specMaterialHash(spec);
+}
+
+function generateRunId() {
+  const timestamp = Date.now().toString(36).toUpperCase().padStart(8, "0");
+  const alphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUV";
+  const suffix = Array.from({ length: 18 }, () => alphabet[Math.floor(Math.random() * alphabet.length)]).join("");
+  return `${timestamp}${suffix}`;
+}
+
+function resolveFromFile(filePath, targetPath) {
+  if (!targetPath) return null;
+  if (isAbsoluteHttpUrl(targetPath) || targetPath.startsWith("/")) return targetPath;
+  return resolve(dirname(resolve(filePath)), targetPath);
+}
+
+function readJson(path) {
+  if (!existsSync(path)) {
+    const error = new Error(`File does not exist: ${path}`);
+    error.code = "ENOENT";
+    throw error;
+  }
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function writeJson(path, value) {
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function stringArg(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function setOptionalBoolean(target, property, args, key, changed) {
+  if (!(key in args)) return;
+  const value = booleanArg(args[key], key);
+  setIfChanged(target, property, value, changed);
+}
+
+function setOptionalString(target, property, args, key, changed) {
+  if (!(key in args)) return;
+  const value = stringArg(args[key]);
+  if (!value) throw new Error(`--${key} requires a value.`);
+  setIfChanged(target, property, value, changed);
+}
+
+function setIfChanged(target, property, value, changed) {
+  if (target[property] === value) return;
+  target[property] = value;
+  changed.push(property);
+}
+
+function booleanArg(value, key) {
+  if (value === true) return true;
+  const normalized = String(value || "").trim().toLowerCase();
+  if (["true", "1", "yes", "y", "on"].includes(normalized)) return true;
+  if (["false", "0", "no", "n", "off"].includes(normalized)) return false;
+  throw new Error(`--${key} must be true or false.`);
+}
+
+// Tri-state (packet 04 Stage A / IC-2): `undefined` means the flag was not
+// supplied — defer to the spec; `true` forces the leg; `false` explicitly
+// DISABLES it. Absent must stay non-throwing: before NEXT-114 (dogfood finding
+// wf_1785565103144), a spec with no analytics block made booleanArg(undefined)
+// throw on every qa run that omitted --analytics-correctness. Explicit garbage
+// values still error.
+export function forcedAnalyticsCorrectness(args) {
+  if (args?.["analytics-correctness"] == null) return undefined;
+  return booleanArg(args["analytics-correctness"], "analytics-correctness");
+}
+
+// #172: the default verdict POST sits inside the telemetry consent seam.
+// Precedence: explicit flags > portal-managed default > consent state >
+// legacy publish-by-default. Portal-managed means the spec for this run was
+// resolved FROM the portal (no local spec file) — those verdicts are the
+// product surface of the QA tab and keep publish-by-default. For everything
+// else (client projects, fixtures, local shakeouts on a local spec), consent
+// off (CAMPAIGNS_OS_TELEMETRY=off / `campaigns-os telemetry off`) means the
+// verdict stays local, with the destination and the opt-in flag named in the
+// run output. Publishing for the portal path is never weakened.
+export function decidePublishVerdict({ args = {}, portalManaged = false, consent = null } = {}) {
+  if (args["no-post-verdict"] === true || args["local-only"] === true) {
+    return { publish: false, reason: "flag_opt_out" };
+  }
+  let flagInvalid = false;
+  if ("post-verdict" in args) {
+    const value = args["post-verdict"];
+    if (value === true) return { publish: true, reason: "flag_opt_in" };
+    const normalized = String(value).trim().toLowerCase();
+    if (["true", "1", "yes", "y", "on"].includes(normalized)) return { publish: true, reason: "flag_opt_in" };
+    if (["false", "0", "no", "n", "off"].includes(normalized)) return { publish: false, reason: "flag_opt_out" };
+    // Unrecognized value: never a silent opt-in (Kilo review, PR #177) —
+    // ignore the flag, continue the precedence chain, and surface the
+    // garbage value on the decision so the run summary shows the signal.
+    flagInvalid = true;
+  }
+  const decorate = (decision) => (flagInvalid ? { ...decision, flag_invalid: true } : decision);
+  if (portalManaged) return decorate({ publish: true, reason: "portal_managed_default" });
+  if (consent?.state === "off") return decorate({ publish: false, reason: "consent_off" });
+  return decorate({ publish: true, reason: "default" });
+}
+
+function policySnapshot(packet) {
+  return {
+    campaign: {
+      allowed_domains_confirmed: packet.campaign?.allowed_domains_confirmed ?? null,
+    },
+    deploy: {
+      target: packet.deploy?.target ?? null,
+      preview_url: packet.deploy?.preview_url ?? null,
+      production_url: packet.deploy?.production_url ?? null,
+    },
+    qa: {
+      order_path_depth: packet.qa?.proof_policy?.order_path_depth ?? null,
+    },
+  };
+}
+
+function normalizeBaseUrl(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function normalizeQaBaseUrl(value, publicRouteSlug) {
+  const baseUrl = normalizeBaseUrl(value);
+  if (!baseUrl) return null;
+  const slug = normalizePublicRouteSlug(publicRouteSlug);
+  if (!slug) return ensureUrlTrailingSlash(baseUrl);
+  try {
+    const url = new URL(ensureUrlTrailingSlash(baseUrl));
+    const segments = url.pathname.split("/").filter(Boolean);
+    if (segments.at(-1) === slug) return ensureUrlTrailingSlash(url.toString());
+    return new URL(`${slug}/`, url).toString();
+  } catch {
+    return ensureUrlTrailingSlash(baseUrl);
+  }
+}
+
+// The campaign's served route root — "/", "/<slug>/", or null — read by the
+// one rule every stage shares (route-identity.mjs): the packet under its exact
+// canonical form, the spec under prepare-build's intake form. A declaration
+// that rule does not honour NEVER roots a check; it falls through to the
+// slug-prefixed default, exactly like doctor. What QA adds is the record: the
+// slug default then audits a DIFFERENT page than the one declared — a
+// hand-edited packet ("/<slug>" without its slash, which doctor blocks by
+// name), a multi-segment root like "/<slug>/offer/", or a foreign root — so
+// the discard is written onto the evidence rather than swallowed.
+function resolveCampaignRouteRoot({ packet, spec, rawSpec, publicRouteSlug, notes = null }) {
+  const slug = normalizePublicRouteSlug(publicRouteSlug);
+  const resolved = resolveRouteRoot({ packet, spec, rawSpec, publicRouteSlug });
+  if (notes && resolved.accepted === false) {
+    notes.push({
+      code: "route_root.declared_discarded",
+      declared: resolved.declared,
+      resolved: resolved.route_root,
+      reason: slug
+        ? `Declared route_root "${resolved.declared}" is neither "/" nor "/${slug}/", so QA fell back to the slug default "/${slug}/". If the campaign really is served at "${resolved.declared}", QA is auditing the wrong page.`
+        : `Declared route_root "${resolved.declared}" could not be checked against a public_route_slug (no slug resolved), so QA fell back to no route root.`,
+    });
+  }
+  return resolved.route_root;
+}
+
+// The ONE place the analytics capture-target shape is defined. Every producer
+// of a capture target — identity-composed (resolveAnalyticsCaptureTarget) and
+// built-site (resolveQaInputsFromSite) — constructs through here, so a new
+// diagnostic field or a new `source` value cannot land on one path and
+// silently skip the other. The shape is enforced by construction, not by a
+// test that happens to cover one branch.
+function buildAnalyticsCaptureTarget({ url, publicRouteSlug, routeRoot, source, routeRootNote = null }) {
+  return {
+    url: url || null,
+    public_route_slug: publicRouteSlug || null,
+    route_root: routeRoot || null,
+    source,
+    // Loud-not-silent: set only when a declared route_root was discarded in
+    // favour of the slug default, so the discard rides on the evidence
+    // instead of vanishing. Null on the overwhelmingly common clean path.
+    route_root_note: routeRootNote || null,
+  };
+}
+
+// Packet 01 / INV-2: the ONE URL both analytics legs visit derives from the
+// campaign's resolved identity — public_route_slug AND route_root — never
+// from a raw operator argument.
+//
+// Composition mirrors doctor's served-route rule (validateBuiltRouteDrift):
+//   route_root "/"        → the funnel lives at the SITE ROOT, so the target
+//                           is the base URL's origin root; the slug stays
+//                           identity, not a path prefix, and any stray path
+//                           on --base-url is discarded. The query string and
+//                           fragment go with it: the capture target is the
+//                           canonical page identity both legs must agree on,
+//                           and an operator's debugging query (?utm_source=qa)
+//                           would otherwise ride into the parity comparison as
+//                           if it were part of the campaign's address. Pass
+//                           such parameters to the browser leg, not here.
+//   route_root "/<slug>/" → the slug-prefixed default: the slug is appended
+//                           to the operator/deploy base unless its last
+//                           segment already is the slug (normalizeQaBaseUrl
+//                           semantics, subdirectory deploys preserved).
+function resolveAnalyticsCaptureTarget({ inputBaseUrl, publicRouteSlug, routeRoot, routeRootNote = null }) {
+  const slug = normalizePublicRouteSlug(publicRouteSlug) || null;
+  const target = buildAnalyticsCaptureTarget({
+    url: null,
+    publicRouteSlug: slug,
+    routeRoot: routeRoot || (slug ? `/${slug}/` : null),
+    source: "unresolved",
+    routeRootNote,
+  });
+  const base = normalizeBaseUrl(inputBaseUrl);
+  if (!base) return target;
+  if (target.route_root === "/") {
+    try {
+      target.url = new URL("/", base).toString();
+      target.source = "resolved_identity:route_root";
+      return target;
+    } catch {
+      target.url = ensureUrlTrailingSlash(base);
+      target.source = "base_url:unparseable";
+      return target;
+    }
+  }
+  if (slug) {
+    target.url = normalizeQaBaseUrl(base, slug);
+    target.source = "resolved_identity:public_route_slug";
+    return target;
+  }
+  // No slug, no route root (parity fixtures / degenerate specs): the base URL
+  // is the only identity available.
+  target.url = ensureUrlTrailingSlash(base);
+  target.source = "base_url";
+  return target;
+}
+
+function resolvePublicRouteSlug({ packet, spec, rawSpec }) {
+  return stringArg(packet?.campaign?.public_route_slug)
+    || stringArg(packet?.deploy?.live_url_path)?.replace(/^\/+|\/+$/g, "")
+    || stringArg(spec?.spec_identity?.public_route_slug)
+    || stringArg(rawSpec?.spec_identity?.public_route_slug)
+    || stringArg(spec?.campaign?.slug)
+    || stringArg(rawSpec?.campaign?.slug)
+    || null;
+}
+
+function ensureUrlTrailingSlash(value) {
+  return value.endsWith("/") ? value : `${value}/`;
+}
+
+function stripOrigin(value) {
+  try {
+    const url = new URL(value);
+    return `${url.pathname}${url.search}${url.hash}`;
+  } catch {
+    return value;
+  }
+}
+
+function isRoutingMetaTag(name) {
+  return [
+    "next-success-url",
+    "next-upsell-accept-url",
+    "next-upsell-decline-url",
+    "next-failure-url",
+  ].includes(normalizeMetaName(name));
+}
+
+// Meta names reach these matchers from spec-declared keys and from
+// extractMetaTags, which does not trim the parsed `name` value. Normalize case
+// and surrounding whitespace so a stray-space tag lands on the intended branch
+// instead of falling through to the strict comparison as a BLOCKER.
+function normalizeMetaName(name) {
+  return normalizeSdkMetaName(name);
+}
+
+// The SDK-ignored list lives in sdk-meta-tags.mjs and doctor reads the same
+// map, so QA and doctor can never disagree about which spec keys the SDK
+// reads. Returns the map entry ({ expected, actual, note }) or null.
+function unsupportedSdkMetaHint(name) {
+  return lookupSdkIgnoredMetaTag(name);
+}
+
+function metaTagMatches(name, actual, expected) {
+  if (actual === expected) return true;
+  if (!isRoutingMetaTag(name)) return false;
+  return comparableRoute(actual) === comparableRoute(expected);
+}
+
+function comparableRoute(value) {
+  if (typeof value !== "string" || !value.trim()) return "";
+  const raw = value.trim();
+  try {
+    const url = new URL(raw);
+    return normalizeRoutePath(`${url.pathname}${url.search}${url.hash}`);
+  } catch {
+    return normalizeRoutePath(raw);
+  }
+}
+
+function normalizeRoutePath(value) {
+  const raw = String(value || "").trim();
+  if (!raw) return "";
+  if (raw.startsWith("/")) return normalizePathTrailingSlash(raw);
+  return normalizePathTrailingSlash(normalizePageKitRoute(raw) || raw);
+}
+
+function normalizePathTrailingSlash(value) {
+  if (!value || /[?#]/.test(value) || value.endsWith("/")) return value;
+  return `${value}/`;
+}
+
+function htmlIncludesRouteReference(html, expectedUrl) {
+  if (!expectedUrl) return false;
+  const path = stripOrigin(expectedUrl);
+  return html.includes(expectedUrl) || html.includes(path);
+}
+
+function findSdkRouteAction(html, kind, page) {
+  if (page.page_type !== "upsell") return null;
+  if (kind === "accept" && /\bdata-next-upsell-action\s*=\s*["']add["']/i.test(html)) {
+    return 'SDK upsell accept control: data-next-upsell-action="add"';
+  }
+  if (kind === "decline" && /\bdata-next-upsell-action\s*=\s*["']skip["']/i.test(html)) {
+    return 'SDK upsell decline control: data-next-upsell-action="skip"';
+  }
+  return null;
+}
+
+function decodeHtml(value) {
+  return value
+    .replace(/&quot;/g, "\"")
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">");
+}
+
+function parseCart(value) {
+  if (!value) return [];
+  return String(value).split(",").map((part) => {
+    const [packageId, quantity] = part.split(":").map((item) => item.trim());
+    return { packageId, quantity: Number.parseInt(quantity || "1", 10) || 1 };
+  }).filter((item) => item.packageId);
+}
+
+function findPage(topologies, type) {
+  for (const topology of topologies) {
+    const page = topology.pages.find((candidate) => candidate.page_type === type);
+    if (page) return page;
+  }
+  return null;
+}
+
+function firstShippingMethod(spec) {
+  const first = Array.isArray(spec.shipping_methods) ? spec.shipping_methods[0] : null;
+  return Number(first?.ref_id || first?.id || 1);
+}
+
+function extractReceiptLines(raw) {
+  const lines = Array.isArray(raw?.lines) ? raw.lines : [];
+  return lines.map((line) => ({
+    ref_id: line.package_id || line.ref_id || line.id || "",
+    name: line.name || line.title || "Line item",
+    quantity: Number(line.quantity || 1),
+    price_cents: Number(line.price_cents || line.total_cents || 0),
+  }));
+}
+
+function extractApiError(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  if (typeof raw.detail === "string") return raw.detail;
+  if (typeof raw.error === "string") return raw.error;
+  if (typeof raw.message === "string") return raw.message;
+  return null;
+}
+
+export const __qaNodeTestHooks = Object.freeze({
+  extractTopologies,
+  validatedOrderCreationLimit,
+  resolveQaInputs,
+  runResolvedQa,
+  runPageChecks,
+  analyticsCorrectnessLegDecision,
+  analyticsCorrectnessDisabledAssertion,
+  runAnalyticsOrderSequence,
+  maybeRunTestOrders,
+  campaignOutputDir,
+  polishBlockedAssertions,
+  polishGateAssertion,
+  themeBlockedAssertions,
+  themeGateAssertion,
+  themeGateScopeFromTopologies,
+  residueSeverityForThemeGate,
+  supportedPaymentMethodsFromSpec,
+  themeGateSummary,
+  templateBrandContractAssertion,
+  deriveEntryUrls,
+  derivePageUrls,
+  deriveTestedUrlsFromAssertions,
+  resolvePayload,
+  resolveThemeGate,
+  resolveStatus,
+  resolveRouteProbe,
+  mergeThemeGateScope,
+  themeGateScopeSource,
+  checkpointGateSummary,
+  hiddenEagerMediaGateAssertion,
+  checkpointBlockedAssertions,
+  resolveQaInputsFromSite,
+  resolveQaWaivers,
+  resolveCampaignRouteRoot,
+  resolveAnalyticsCaptureTarget,
+  buildAnalyticsCaptureTarget,
+  isRoutingMetaTag,
+  unsupportedSdkMetaHint,
+  reportCommercialRunnerError,
+  browserSkippedByGate,
+  reportBrowserSkippedByGate,
+  gateClearingHint,
+});