@nextcommerce/campaigns-os 1.63.0 → 1.66.0

package/src/doctor/checks.mjs

@@ -6,7 +6,7 @@ import { accessSync, constants as fsConstants, existsSync, readdirSync, readFile
 import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { describeSdkIgnoredMetaTags, isSdkIgnoredMetaTag } from "../sdk-meta-tags.mjs";
 import { ORDER_PATH_DEPTH_DRIFT_CODE, orderPathDepthDriftText, orderPathDepthsDisagree } from "../proof-policy.mjs";
-import { QA_GATE_PLACEHOLDER_TEXT_RESIDUE, qaGatePassedForCurrentBuild } from "../stage-ledger.mjs";
+import { QA_GATE_PLACEHOLDER_TEXT_RESIDUE, qaGatePassedForCurrentBuild, qaRestsOnBaseline } from "../stage-ledger.mjs";
 import {
   validateAdapterDecisionGates,
   validateAdapterDecisionShape,
@@ -436,6 +436,15 @@ const SPEC_DOCTOR_CHECKS = createDoctorCheckRegistry([
     phase: "built-output",
     run: ({ packet, errors, warnings, ready, derived, buildState }) => validateBuildOutputFingerprint(packet, errors, warnings, ready, derived, buildState),
   },
+  {
+    id: "qa.baseline_accepted",
+    phase: "built-output",
+    run: ({ warnings, buildState }) => {
+      const baseline = qaRestsOnBaseline(buildState.report);
+      if (!baseline) return;
+      addIssue(warnings, "qa.baseline_accepted", `QA rests on a baseline ${baseline.accepted_by} accepted at ${baseline.accepted_at}, not a test. No purchase has been tested since; a completed full \`campaigns-os qa run\` ends it.`, { accepted_by: baseline.accepted_by, accepted_at: baseline.accepted_at });
+    },
+  },
   {
     id: "built_output.pages",
     phase: "built-output",
@@ -742,7 +751,10 @@ function validatePacket(packet, packetPath, errors, warnings, ready, derived, bu
     } else if (!isNonEmptyString(localSpecPath)) {
       addIssue(errors, "spec.local_path", "No local CampaignSpec path is present. Assembly must use a local exported CampaignSpec JSON so page coverage, routing, meta tags, and commerce refs are not guessed.");
     } else if (!existsSync(specPath)) {
-      addIssue(errors, "spec.local_path", `CampaignSpec local_path does not exist: ${localSpecPath}`);
+      // A saved-Map copy is not on this machine: a checkout made before it was
+      // committed, or a machine that never ran the intake.
+      const restorable = isNonEmptyString(packet.spec?.map_id) && localSpecPath.includes(".campaign-runtime/fetched-specs/");
+      addIssue(errors, "spec.local_path", `CampaignSpec local_path does not exist: ${localSpecPath}${restorable ? `. Restore it from the saved Map with \`campaigns-os spec fetch --packet <packet>\`, then commit it.` : ""}`);
     } else {
       try {
         const loaded = readJson(specPath);
@@ -1910,7 +1922,20 @@ export function validateBuildOutputFingerprint(packet, errors, warnings, ready,
   const publicRouteSlug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
   if (!targetRepo || !publicRouteSlug) return;
   const siteRoot = join(targetRepo, "_site", publicRouteSlug);
-  if (!existsSync(siteRoot) || !statSync(siteRoot).isDirectory()) return;
+  if (!existsSync(siteRoot) || !statSync(siteRoot).isDirectory()) {
+    // Nothing to compare, which is not the same as nothing changed: a fresh
+    // checkout has committed records and no _site/, and would otherwise read
+    // as finished however much source has moved since they were made.
+    if (isStageComplete(buildState.report, "assembly")) {
+      addIssue(
+        warnings,
+        "built_output.absent",
+        `_site/${publicRouteSlug}/ is not built here, so the recorded build, Polish and QA were not compared with this checkout. Build it, then run this again.`,
+        { root: `_site/${publicRouteSlug}/` },
+      );
+    }
+    return;
+  }
 
   const current = computeBuildFingerprint(siteRoot);
   // The root was a directory a moment ago; if it is not one now (removed

package/src/doctor/ci.mjs

@@ -36,7 +36,7 @@ const commerceReasonText = new Map([
   ["page_removed", "a page was removed"],
   ["checkout_page", "a checkout page changed"],
   ["commerce_markup_changed", "package, offer, shipping, upsell, route or script markup changed"],
-  ["commerce_signature_unavailable", "the recorded build has no commerce signature to compare against"],
+  ["commerce_signature_unavailable", "the recorded build predates the markup hashes page-only changes are read from (Campaigns OS 1.62), so this change cannot be shown to be page-only"],
   ["campaign_config_changed", "the campaign's Page Kit config (SDK pin, analytics ids, store fields) changed"],
   ["campaign_config_unavailable", "the campaign's Page Kit config entry could not be read"],
   ["change_history_unavailable", "the rebuilds since the reviewed build were not kept"],
@@ -62,6 +62,34 @@ const unavailablePageChanges = new Map([
   ["build_manifest_unavailable", "no usable assembly manifest is available."],
 ]);
 
+// What an owed stage's change was read against, for a report that can disagree
+// with the last `record build` because it counts every rebuild since that
+// stage's own review.
+const shortBuild = (value) => String(value).replace(/^sha256:/, "").slice(0, 12);
+const stageNames = { polish: "Polish", qa: "QA" };
+function changeBasisLine(stage, record) {
+  const since = record?.change?.since_build_fingerprint;
+  if (!since) return null;
+  const at = /^\d{4}-\d{2}-\d{2}/.exec(String(record.reviewed_at ?? ""))?.[0];
+  return `- ${stageNames[stage]} change is read against the build it last checked (${code(shortBuild(since))}${at ? `, ${at}` : ""}), counting every rebuild since.`;
+}
+
+// Polish and QA read back along one chain of rebuilds, so when both have a
+// commerce rebuild behind a page-only edit it is the same one.
+function uncoveredRebuildLine(ci, stages) {
+  const behind = stages.filter((stage) => ci[stage].change?.commerce_rebuild?.latest_change_kind === "page_only");
+  if (!behind.length) return null;
+  const rebuild = ci[behind[0]].change.commerce_rebuild;
+  const at = /^\d{4}-\d{2}-\d{2}/.exec(String(rebuild.recorded_at ?? ""))?.[0];
+  const names = behind.map((stage) => stageNames[stage]).join(" and ");
+  return `- The latest change alone is page-only. ${names} still ${behind.length > 1 ? "owe" : "owes"} the full stage for an earlier rebuild${at ? ` recorded ${at}` : ""} (${code(shortBuild(rebuild.build_fingerprint))}) since that check.`;
+}
+
+function baselineLine(baseline) {
+  const at = /^\d{4}-\d{2}-\d{2}/.exec(String(baseline.accepted_at ?? ""))?.[0];
+  return `QA rests on a baseline ${text(baseline.accepted_by)} accepted${at ? ` on ${at}` : ""}, not a test. No purchase has been tested since.`;
+}
+
 const requiredStageReasons = new Map([
   ["stage_required_by_build", "the build requires this stage again"],
   ["stage_required_by_brief", "the brief requires this stage again"],
@@ -132,6 +160,12 @@ export function formatDoctorCi(result) {
   for (const stage of advisory) {
     lines.push(`- Advisory ${stage}: the change since its last review is page-only, so it is reported and not required.`);
   }
+  for (const stage of [...owed, ...advisory]) {
+    const basis = changeBasisLine(stage, ci[stage]);
+    if (basis) lines.push(basis);
+  }
+  const uncovered = uncoveredRebuildLine(ci, owed);
+  if (uncovered) lines.push(uncovered);
   // The pages changed since the builds the owed stages reviewed, which
   // record build keeps; without them, the drift from the assembly manifest.
   const sincePages = new Map();
@@ -168,6 +202,7 @@ export function formatDoctorCi(result) {
       lines.push("", "Remedy: rebuild, then run `campaigns-os record build --packet <packet>`, `campaigns-os polish capture --packet <packet> --base-url <served-current-build-url>` for the whole route, and `campaigns-os record polish --packet <packet> --evidence <polish-evidence.json>`, in that order. When QA is owed, run `campaigns-os qa run --packet <packet>` against that build.");
     }
   }
+  if (ci.qa.baseline) lines.push("", baselineLine(ci.qa.baseline));
   lines.push("", `Doctor inspection: ${(result.errors || []).length} error(s), ${(result.warnings || []).length} warning(s); CI exit status depends only on evidence debt.`);
   if (result.errors?.length) {
     lines.push(`Doctor errors: ${[...new Set(result.errors.map((issue) => issue.code))].map(code).join(", ")}.`);

package/src/evidence-debt.mjs

@@ -12,7 +12,7 @@ import {
 import { changeSince, classifyDrift } from "./change-scope.mjs";
 import { normalizePublicRouteSlug } from "./route-identity.mjs";
 import { isFileReadFailure } from "./cart-placeholders.mjs";
-import { polishReviewedBuild, qaExtendedBuildFingerprint, qaRecordedBuildFingerprint, qaRecordedForCurrentBuild } from "./stage-ledger.mjs";
+import { polishReviewedBuild, qaExtendedBuildFingerprint, qaRecordedBuildFingerprint, qaRecordedForCurrentBuild, qaRestsOnBaseline } from "./stage-ledger.mjs";
 
 export const EVIDENCE_DEBT_STATUSES = Object.freeze(["current", "owed", "unknown"]);
 
@@ -148,6 +148,9 @@ export function assessEvidenceDebt({ packet = null, packetPath = null, report =
   if (qa.status === "owed") {
     const extended = qaExtendedBuildFingerprint(report);
     qa.change = changeFor(extended || qaBuild);
+    // Only a completed QA dates its own review: a blocked full run reviewed
+    // nothing, and a blocked page-scoped run is read from the QA it extended.
+    if (extended && extended === qaBuild && fingerprint(qaRecord?.checked_at)) qa.reviewed_at = qaRecord.checked_at.trim();
     qa.scope = extended && qaRecord?.status !== "required" && qa.change.kind === "page_only" ? "pages" : "full";
     qa.owed_pages = qa.scope === "pages" ? qa.change.changed_pages : [];
   } else {
@@ -155,5 +158,10 @@ export function assessEvidenceDebt({ packet = null, packetPath = null, report =
     qa.scope = null;
     qa.owed_pages = [];
   }
+  const baseline = qaRestsOnBaseline(report);
+  if (baseline) {
+    const { accepted_by, accepted_at, reason: acceptedFor, build_fingerprint } = baseline;
+    qa.baseline = { accepted_by, accepted_at, reason: acceptedFor, build_fingerprint };
+  }
   return { polish, qa, changes };
 }

package/src/input-currency.mjs

@@ -16,8 +16,10 @@ import { isObject, optionalString, resolveFromFile } from "./cli-helpers.mjs";
 import { specMaterialHash } from "./spec-identity.mjs";
 
 // Every raw stage status the lifecycle writes. Any other value reads unknown.
-export const RECOGNIZED_STAGE_STATUSES = Object.freeze(["pending", "blocked", "required", "completed", "completed_with_warnings", "completed_partial", "skipped"]);
-const COMPLETED_STATUSES = Object.freeze(["completed", "completed_with_warnings", "completed_partial"]);
+export const RECOGNIZED_STAGE_STATUSES = Object.freeze(["pending", "blocked", "required", "completed", "completed_with_warnings", "completed_partial", "skipped", "baseline_accepted"]);
+// Read for currency, not for proof: a baseline carries input stamps, so a later
+// spec or brief change owes the stage again.
+const COMPLETED_STATUSES = Object.freeze(["completed", "completed_with_warnings", "completed_partial", "baseline_accepted"]);
 const NOT_APPLICABLE_STATUSES = Object.freeze(["pending", "blocked", "required", "skipped"]);
 const TERMINAL_EFFECTIVE_STATUSES = Object.freeze([...COMPLETED_STATUSES, "skipped"]);
 

package/src/input-refresh.mjs

@@ -63,7 +63,7 @@ const BRIEF_MAX_BYTES = 1024 * 1024;
 const BRIEF_MAX_DESIGN_AUTHORITY_ENTRIES = 512;
 const BRIEF_PROMPT_PREFIX = "BUILD_BRIEF_";
 const BRIEF_GATE_PREFIX = "build_brief.";
-const COMPLETED_STATUSES = Object.freeze(["completed", "completed_with_warnings", "completed_partial"]);
+const COMPLETED_STATUSES = Object.freeze(["completed", "completed_with_warnings", "completed_partial", "baseline_accepted"]);
 
 const isBriefBlocker = (entry) => typeof entry?.code === "string" && (entry.code.startsWith(BRIEF_PROMPT_PREFIX) || entry.code.startsWith(BRIEF_GATE_PREFIX));
 

package/src/invocation.mjs

@@ -65,12 +65,12 @@ const COMMANDS = frozen({
   theme: { subcommands: ["generate", "inspect", "waive"] },
   checkpoint: { subcommands: ["accept", "waive"] },
   polish: { subcommands: ["capture"] },
-  record: { subcommands: ["brief", "build", "deploy", "polish", "setup", "spec", "theme"] },
+  record: { subcommands: ["baseline", "brief", "build", "deploy", "polish", "setup", "spec", "theme"] },
   "validate-assembly-report": {},
   "install-agent-context": { dryRun: true },
   "install-skills": { dryRun: true },
   "page-kit": { subcommands: ["parity", "sync"] },
-  spec: { subcommands: ["derive"] },
+  spec: { subcommands: ["derive", "fetch"] },
   next: { subcommands: ["build", "deploy", "polish", "qa", "setup"] },
   qa: { subcommands: ["install-browser", "parity", "policy", "promote", "publish", "resolve", "run", "waive"] },
   findings: { subcommands: ["add", "export", "harvest", "list"] },
@@ -100,6 +100,7 @@ const SUBCOMMAND_OVERRIDES = frozen({
   "record polish": { dryRun: true },
   "record setup": { dryRun: true },
   "record spec": { dryRun: true },
+  "record baseline": { dryRun: true },
   "record theme": { dryRun: true },
   "qa run": { autoEnd: true },
   "run start": { sweepRoot: "session" },

package/src/orchestration-stage-contract.mjs

@@ -56,8 +56,10 @@ export function reportKeyForCliStage(cliStage) {
  * decided on its effective status (src/input-currency.mjs), which the `next`
  * picker and the Assembly Report's derived summary (src/stage-ledger.mjs)
  * read: a stage owed again is not done, whatever status it records.
+ * "baseline_accepted" is terminal without being completed: a named person
+ * accepted the build (`record baseline`), and nothing tested it.
  */
-export const STAGE_TERMINAL_STATUS_PREFIXES = Object.freeze(["completed", "skipped"]);
+export const STAGE_TERMINAL_STATUS_PREFIXES = Object.freeze(["completed", "skipped", "baseline_accepted"]);
 
 export function stageIsTerminal(status) {
   const normalized = String(status || "");

package/src/polish-gate.mjs

@@ -393,6 +393,16 @@ function evaluateStructuredPolishGate({ report, required = false, now = Date.now
   }
 
   const buildFingerprint = currentBuildFingerprint(report);
+  // A baseline reviewed nothing, so it grants no pass; it only stands for its
+  // own build. The stale check below handles it once the build has moved on.
+  if (report.stages?.polish?.status === "baseline_accepted" && normalizeString(report.stages.polish.source_build_fingerprint) === buildFingerprint) {
+    return {
+      status: "not_applicable",
+      code: "polish.baseline_accepted",
+      reason: "Polish was not run for this build: a named person accepted it as a baseline.",
+      build_fingerprint: buildFingerprint,
+    };
+  }
   const currentSourcePackageFingerprint = currentSourcePackageMaterialFingerprint(report);
   const assemblySourcePackageFingerprint = assemblySourcePackageMaterialFingerprint(report);
   const waiverAssessment = assessAssemblySourcePackageFreshnessWaivers(report, now);

package/src/qa-browser.mjs

@@ -1130,6 +1130,12 @@ async function runPageBrowserChecks(context, page, args, options = {}, policyLin
     assertions.push(...await templatePlaceholderTextAssertions(browserPage, page, options));
     assertions.push(...await templateDemoAssetAssertions(browserPage, page, options));
     assertions.push(...await pricingVisibilityAssertions(browserPage, page, options));
+    // Commercial parity compares these with calculated prices once the browser
+    // pass is over; a page never read here stays unresolved there.
+    if (options.renderedPackagePrices && !options.renderedPackagePrices.has(String(page.page_id))) {
+      const rendered = await readRenderedPackagePrices(browserPage);
+      if (rendered) options.renderedPackagePrices.set(String(page.page_id), rendered);
+    }
     observation.inspection_ms = elapsedMilliseconds(inspectionStarted);
     const debuggerStarted = performance.now();
     assertions.push(...await sdkDebuggerAssertions(context, page, args));
@@ -3104,6 +3110,45 @@ async function pricingVisibilityAssertions(browserPage, page, options = {}) {
   return [];
 }
 
+// Runs in the page. Every visible package.price node as the shopper reads it. The
+// SDK adds `display-visible` when it writes a node, and nothing else does, so a
+// node without it still holds the template's placeholder, whatever that says.
+// Same package scope as the SDK: the id in the path, then the nearest package id.
+// A price the page multiplies by a live quantity is not a unit price: it keeps no
+// text, so it stays unresolved instead of being compared.
+function collectRenderedPackagePrices() {
+  const claims = new Map();
+  for (const element of document.querySelectorAll('[data-next-display^="package."]')) {
+    const binding = (element.getAttribute("data-next-display") || "").trim();
+    const match = /^package\.(?:([1-9]\d*)\.)?price$/.exec(binding);
+    if (!match) continue;
+    const format = (element.getAttribute("data-next-format") || "currency").trim().toLowerCase();
+    if (format !== "currency" || element.closest("del, s, strike")) continue;
+    if (!element.checkVisibility({ checkVisibilityCSS: true })) continue;
+    let packageId = match[1] ? Number(match[1]) : null;
+    for (let current = element; packageId === null && current; current = current.parentElement) {
+      for (const attribute of ["data-next-package-id", "data-next-package", "data-package-id"]) {
+        const value = (current.getAttribute(attribute) || "").trim();
+        if (packageId === null && /^[1-9]\d*$/.test(value)) packageId = Number(value);
+      }
+    }
+    const filled = element.classList.contains("display-visible");
+    const multiplied = element.hasAttribute("data-next-multiply-quantity");
+    const text = filled && !multiplied ? element.textContent.replace(/\s+/g, " ").trim() : null;
+    claims.set(`${binding}|${packageId}|${filled}|${text}`, { binding, package_id: packageId, filled, text });
+  }
+  return [...claims.values()];
+}
+
+async function readRenderedPackagePrices(browserPage, { timeoutMs = DEFAULT_SETTLE_TIMEOUT_MS } = {}) {
+  await browserPage.waitForFunction(
+    `(${collectRenderedPackagePrices.toString()})().every((claim) => claim.filled)`,
+    null,
+    { timeout: timeoutMs },
+  ).catch(() => {});
+  return browserPage.evaluate(collectRenderedPackagePrices).catch(() => null);
+}
+
 // The SDK renders a bundle or upsell price through data-next-bundle-display as
 // well as data-next-display (#532). A contract surface that lists price rows
 // also counts that attribute; an empty list stays empty so a contract that
@@ -9028,6 +9073,7 @@ export const __qaBrowserTestHooks = Object.freeze({
   ASSET_FETCH_MAX_BYTES,
   paymentChromeResidueAssertion,
   pricingVisibilityAssertions,
+  readRenderedPackagePrices,
   upsellPriceVisibilityAssertion,
   checkoutPriceVisibilityAssertion,
   assessReceiptRendering,

package/src/qa-commercial-parity.mjs

@@ -9,8 +9,12 @@ import {
 import {
   COMMERCIAL_PARITY_SCHEMA_VERSION,
   CommercialParityLimitError,
+  PACKAGE_PRICE_NOT_FILLED,
+  PACKAGE_PRICE_NOT_RENDERED,
+  PACKAGE_PRICE_UNRESOLVED,
   createCommercialParityReport,
   extractCommercialClaims,
+  packagePriceClaimCount,
   recurringClaimAbsences,
   recurringClaimAbsentAssertions,
 } from "./commercial-parity.mjs";
@@ -450,6 +454,7 @@ function catalogImportedAt(spec) {
 
 function captureClaimCount(capture) {
   return array(capture?.price_claims).length
+    + packagePriceClaimCount(capture)
     + array(capture?.recurrence_claims).length
     + array(capture?.vouchers).length;
 }
@@ -466,6 +471,108 @@ function captureIssues(captures) {
   return issues;
 }
 
+// One reason a run's commercial proof stopped short: what was not compared and
+// what to do about it, for an agent that reads only the exceptions list. Text
+// only, never a key or a URL: it is persisted.
+function cause(code, summary, fix, count = 1) {
+  return { code, count, summary, fix };
+}
+
+// What each reason a package.price went uncompared means for the operator.
+const PACKAGE_PRICE_CAUSES = Object.freeze({
+  [PACKAGE_PRICE_NOT_RENDERED]: {
+    summary: (count) => `${count} package.price claim(s) in the page source were not read from a rendered page, so they were not compared.`,
+    fix: "Run qa run with --browser. If it did, check that the tested URL served this page; prices hidden on purpose need no repair.",
+  },
+  [PACKAGE_PRICE_NOT_FILLED]: {
+    summary: (count) => `The SDK never filled ${count} visible package.price node(s), so a shopper may be reading the template's placeholder price.`,
+    fix: "Check that the SDK loaded and that the package ref is on the campaign, then re-run qa run.",
+  },
+  [PACKAGE_PRICE_UNRESOLVED]: {
+    summary: (count) => `${count} package.price claim(s) could not be tied to one calculated price: no package id around the node, no single exact row for the package on the page, or text that is not a money amount.`,
+    fix: "Put data-next-package-id around the price, or check it by hand.",
+  },
+});
+
+const OVER_LIMITS_FIX = "This funnel is over the check's limits, so no re-run will cover it: check these prices by hand and tell the operator.";
+
+/**
+ * The causes of an incomplete proof, the ones found while running first. Later
+ * causes stay quiet when an earlier one explains them, so a missing key does not
+ * also report every page as unpriced. Not every cause has a repair: a store
+ * coupon or a run in another currency only says what was not compared.
+ */
+function incompleteCauses(stopped, commercial, journey) {
+  const causes = [...stopped];
+  // A page whose capture was refused also counts as missing from the comparison.
+  const refused = new Set(array(commercial.invalid_captures).map((capture) => capture.page_id));
+  const unread = [
+    ...array(commercial.invalid_captures),
+    ...array(commercial.missing_pages).filter((page) => !refused.has(page.page_id)),
+  ];
+  if (unread.length) {
+    causes.push(cause(
+      "commercial_pages_unread",
+      `${unread.length} page(s) could not be read for commercial claims: ${unread.map((page) => page.page_id ?? "(no id)").join(", ")}.`,
+      "Fix the page's fetch failure, its URL in the spec or its malformed markup, then re-run qa run. A page over the claim limit needs its prices checked by hand.",
+      unread.length,
+    ));
+  }
+  if (causes.length) return causes;
+
+  const inexact = array(journey?.pages).filter((page) => page?.state !== PricingState.Exact);
+  if (inexact.length) {
+    const named = inexact.map((page) => `${page.page_id} (${page.reason || page.representative_total?.reason || page.state})`);
+    return [cause(
+      "commercial_page_not_exact",
+      `Calculate gave no exact total for ${inexact.length} page(s): ${named.join(", ")}.`,
+      "Correct the spec where the reason names it. A store coupon cannot be previewed, so check that page's prices by hand. Re-run qa run if the reason is Stale.",
+      inexact.length,
+    )];
+  }
+  if (present(commercial.unresolved_money_claims_reason)) {
+    const count = commercial.unresolved_price_claims + commercial.unresolved_recurrence_claims;
+    return [cause(
+      String(commercial.unresolved_money_claims_reason),
+      `${count} price claim(s) in the page source hold the Map currency's fallback text, so they were not compared with totals in the run currency.`,
+      "No page repair is owed. A qa run in the campaign's own currency compares them.",
+      count,
+    )];
+  }
+  const packagePrices = Object.entries(commercial.package_price_claims?.unresolved || {});
+  packagePrices.forEach(([code, count]) => {
+    causes.push(cause(code, PACKAGE_PRICE_CAUSES[code].summary(count), PACKAGE_PRICE_CAUSES[code].fix, count));
+  });
+  const unresolvedPrices = commercial.unresolved_price_claims - packagePrices.reduce((sum, [, count]) => sum + count, 0);
+  const unresolved = unresolvedPrices + commercial.unresolved_recurrence_claims + commercial.unresolved_voucher_claims;
+  if (unresolved > 0) {
+    causes.push(cause(
+      "commercial_claims_unresolved",
+      `${unresolved} claim(s) could not be tied to one calculated value (${unresolvedPrices} price, ${commercial.unresolved_recurrence_claims} recurring, ${commercial.unresolved_voucher_claims} voucher).`,
+      "A page with more than one bound bundle price, or a voucher the plan cannot price, stays uncompared: check these by hand, or declare the voucher in the spec.",
+      unresolved,
+    ));
+  }
+  return causes;
+}
+
+/** One warn row per named cause: what `exceptions[]` carries and the sidecar keeps. */
+function commercialIncompleteAssertions(reasons) {
+  return array(reasons).map((entry) => ({
+    id: `commercial-parity:incomplete:${entry.code}`,
+    family: "pricing",
+    page: "campaign",
+    status: "warn",
+    severity: "warn",
+    expected: "the page's commercial claims compared with calculated totals",
+    actual: `${entry.summary} Fix: ${entry.fix}`,
+    evidence: {
+      code: entry.code,
+      count: entry.count,
+    },
+  }));
+}
+
 function compactReport(report, journey, plan, executed, issues, observedClaims, claimLimit, plannedScenarioCount = plan.length) {
   const exactPages = array(journey?.pages).filter((page) => page?.state === PricingState.Exact).length;
   const stalePages = array(journey?.pages).filter((page) => page?.state === PricingState.Stale).length;
@@ -498,6 +605,7 @@ function compactReport(report, journey, plan, executed, issues, observedClaims,
     extracted_price_claims: report.extracted_price_claims,
     compared_price_claims: report.compared_price_claims,
     unresolved_price_claims: report.unresolved_price_claims,
+    package_price_claims: report.package_price_claims,
     extracted_recurrence_claims: report.extracted_recurrence_claims,
     compared_recurrence_claims: report.compared_recurrence_claims,
     unresolved_recurrence_claims: report.unresolved_recurrence_claims,
@@ -568,6 +676,7 @@ export function unavailableCommercialReport(code, { status = "not_run" } = {}) {
     extracted_price_claims: 0,
     compared_price_claims: 0,
     unresolved_price_claims: 0,
+    package_price_claims: { extracted: 0, compared: 0, unresolved: {} },
     extracted_recurrence_claims: 0,
     compared_recurrence_claims: 0,
     unresolved_recurrence_claims: 0,
@@ -586,6 +695,19 @@ export function unavailableCommercialReport(code, { status = "not_run" } = {}) {
   };
 }
 
+/** What a crash in the check reports: the same warn row as any other stop. */
+export function crashedCommercialResult() {
+  const reason = cause(
+    "commercial_runner_error",
+    "The commercial parity check crashed before it finished, so no price was compared.",
+    "Re-run qa run. If it crashes again, record it with findings add and tell the operator.",
+  );
+  return {
+    assertions: commercialIncompleteAssertions([reason]),
+    commercial: { ...unavailableCommercialReport(reason.code, { status: "incomplete" }), incomplete_reasons: [reason] },
+  };
+}
+
 // One blocker row per currency the calculate endpoint answered in other than
 // the run's: expected totals were asked for in `currency` and came back priced
 // in another one. Answered codes are compared and named upper-cased, so `usd`
@@ -641,13 +763,15 @@ export async function runCommercialParity({
   const observedClaims = array(captures).reduce((sum, capture) => sum + captureClaimCount(capture), 0);
   const aggregateClaimOverflow = observedClaims > limits.max_aggregate_claims;
   const orderedPreflightIssues = [
-    { exceeded: aggregateClaimOverflow, code: "commercial_aggregate_claim_limit" },
-    { exceeded: scenarioOverflow, code: "commercial_scenario_limit" },
-  ];
+    { exceeded: aggregateClaimOverflow, code: "commercial_aggregate_claim_limit", summary: `The funnel carries ${observedClaims} commercial claims, over the limit of ${limits.max_aggregate_claims}, so none were compared.` },
+    { exceeded: scenarioOverflow, code: "commercial_scenario_limit", summary: "The funnel plans more calculate scenarios than the limit, so none ran." },
+  ].filter((issue) => issue.exceeded);
   const issues = [
     ...captureIssues(captures),
-    ...orderedPreflightIssues.filter((issue) => issue.exceeded).map(({ code }) => ({ code })),
+    ...orderedPreflightIssues.map(({ code }) => ({ code })),
   ];
+  // Why calculate did not give this run its answers, said where it is found.
+  const stopped = orderedPreflightIssues.map(({ code, summary }) => cause(code, summary, OVER_LIMITS_FIX));
   const apiKeyResolution = resolveCommercialApiKey(resolved);
   const apiKey = apiKeyResolution.value;
   let executed = [];
@@ -657,8 +781,18 @@ export async function runCommercialParity({
     // preflight issues above remain visible when multiple ceilings are hit.
   } else if (apiKeyResolution.unsupported) {
     issues.push({ code: "unsupported_campaigns_api_key_source" });
+    stopped.push(cause(
+      "unsupported_campaigns_api_key_source",
+      `The packet's campaign.api_key_source names an environment variable QA refuses to read, so 0 of ${plan.length} planned calculate scenarios ran.`,
+      "Use env:CAMPAIGNS_API_KEY, or set campaign.campaigns_api_key in the CampaignSpec, then re-run qa run.",
+    ));
   } else if (plan.some((descriptor) => !descriptor?.unresolved) && !present(apiKey)) {
     issues.push({ code: "missing_campaigns_api_key" });
+    stopped.push(cause(
+      "missing_campaigns_api_key",
+      `No campaign key was resolved, so 0 of ${plan.length} planned calculate scenarios ran and no price was compared.`,
+      "Set campaign.campaigns_api_key in the CampaignSpec (or the Build Packet) to the campaign's API key, then re-run qa run.",
+    ));
   } else if (typeof fetchImpl !== "function") {
     issues.push({ code: "price_preview_fetch_unavailable" });
   } else {
@@ -669,9 +803,17 @@ export async function runCommercialParity({
       fetchImpl,
       limits,
     }));
-    executed.filter((entry) => entry?.ok === false).forEach((entry) => {
-      issues.push({ code: entry.error_code || "price_preview_failed" });
-    });
+    const failures = executed.filter((entry) => entry?.ok === false)
+      .map((entry) => entry.error_code || "price_preview_failed");
+    failures.forEach((code) => issues.push({ code }));
+    if (failures.length) {
+      stopped.push(cause(
+        "price_preview_failed",
+        `The calculate endpoint failed for ${failures.length} of ${plan.length} planned scenarios (${[...new Set(failures)].join(", ")}).`,
+        "Check that the key belongs to this campaign and that the proxy is reachable, then re-run qa run.",
+        failures.length,
+      ));
+    }
   }
 
   const journey = normalizeJourney(
@@ -715,17 +857,30 @@ export async function runCommercialParity({
     maxAssertions: Math.max(0, maxAssertions - parity.assertions.length),
   });
   parity.recurring_claim_absences = absences;
+  const commercial = compactReport(
+    parity,
+    parityJourney,
+    plan,
+    executed,
+    issues,
+    observedClaims,
+    limits.max_aggregate_claims,
+    commercialPlanning.observed_scenarios ?? plan.length,
+  );
+  const assertions = [...currencyAssertions, ...parity.assertions, ...absentAssertions];
+  if (commercial.status !== "incomplete") return { assertions, commercial };
+  // An incomplete run always names a cause in the exceptions list. A currency
+  // blocker or an absent rebill claim already wrote its own row.
+  const reasons = incompleteCauses(stopped, commercial, parityJourney);
+  if (!reasons.length && !currencyAssertions.length && !absentAssertions.length) {
+    reasons.push(cause(
+      "commercial_coverage_incomplete",
+      `Commercial parity stopped short: issues ${array(commercial.issues).map((issue) => issue.code).join(", ") || "none"}.`,
+      "Read verdict.commercial for what was and was not compared, and tell the operator.",
+    ));
+  }
   return {
-    assertions: [...currencyAssertions, ...parity.assertions, ...absentAssertions],
-    commercial: compactReport(
-      parity,
-      parityJourney,
-      plan,
-      executed,
-      issues,
-      observedClaims,
-      limits.max_aggregate_claims,
-      commercialPlanning.observed_scenarios ?? plan.length,
-    ),
+    assertions: [...assertions, ...commercialIncompleteAssertions(reasons)],
+    commercial: { ...commercial, incomplete_reasons: reasons },
   };
 }

package/src/qa-node.mjs

@@ -103,6 +103,7 @@ import {
 import {
   captureCommercialClaims,
   COMMERCIAL_QA_LIMITS,
+  crashedCommercialResult,
   mapConcurrent,
   createPageSourceLoader,
   planCommercialParity,
@@ -2609,8 +2610,10 @@ async function runResolvedQa(args, resolvedInputs, { runSessionActive = false, l
   const vendorBeacons = vendorBeaconRun ? createVendorBeaconLedger({ mode: vendorBeaconRun, analytics: resolved.spec?.analytics }) : null;
   if (vendorBeacons) args = { ...args, [QA_VENDOR_BEACONS]: vendorBeacons };
   const qcResults = [];
+  const renderedPackagePrices = new Map();
   if (args.browser === true) {
     const browserAssertions = await runBrowserChecks(resolved.topologies, args, {
+      renderedPackagePrices,
       brandContract: resolved.brandContract,
       // With no generatable brand theme on the local preview, the starter
       // template is the design: its residue is a warning (local-preview-policy.mjs).
@@ -2649,16 +2652,15 @@ async function runResolvedQa(args, resolvedInputs, { runSessionActive = false, l
   try {
     commercialResult = await runCommercialParity({
       resolved,
-      captures: [...capturesByPageId.values()],
+      captures: [...capturesByPageId.entries()].map(([pageId, capture]) => (renderedPackagePrices.has(pageId)
+        ? { ...capture, rendered_package_prices: renderedPackagePrices.get(pageId) }
+        : capture)),
       planning: commercialPlanning,
       maxAssertions: remainingAssertionBudget,
       currency,
     });
   } catch (error) {
-    commercialResult = {
-      assertions: [],
-      commercial: unavailableCommercialReport("commercial_runner_error"),
-    };
+    commercialResult = crashedCommercialResult();
     reportCommercialRunnerError(args, error);
   }
   assertions.push(...commercialResult.assertions);
@@ -3795,6 +3797,9 @@ function output(value, args) {
     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)`);
+      for (const entry of value.commercial.incomplete_reasons || []) {
+        console.log(`  ${entry.code}: ${entry.summary} Fix: ${entry.fix}`);
+      }
     }
     console.log(`Local copy: ${value.local_path}`);
     if (value.posted?.ok && value.dashboard_url) {

package/src/qa-verdict.mjs

@@ -88,7 +88,9 @@ export function computeDisposition(assertions) {
 function dispositionWithCommercial(assertions, commercial) {
   const disposition = computeDisposition(assertions);
   if (disposition === "blocked") return disposition;
-  return commercial?.status === "mismatch"
+  // Warn-only either way: a proven mismatch and a proof that stopped short are
+  // both things the operator has to hear about, and neither ever blocks.
+  return commercial?.status === "mismatch" || commercial?.status === "incomplete"
     ? "ready_with_exceptions"
     : disposition;
 }

package/src/readback.mjs

@@ -1310,6 +1310,7 @@ function renderEvidenceDebt(debt, lines) {
         : `evidence currency is unknown (${stage.reason}); absence of proof is not no debt`;
     lines.push(`  ${name}: ${stage.status} — ${explanation}`);
     lines.push(`    recorded: ${stage.recorded_build_fingerprint ?? "unknown"}; current: ${stage.current_build_fingerprint ?? "unknown"}`);
+    if (stage.baseline) lines.push(`    baseline: accepted by ${oneLine(stage.baseline.accepted_by)} at ${oneLine(stage.baseline.accepted_at)}, not tested; no purchase tested since`);
     if (stage.change) {
       const owes = stage.advisory ? "advisory: reported, not required"
         : stage.scope === "pages" ? `owed on ${stage.owed_pages.map((page) => oneLine(page.page_id)).join(", ")} (qa run --page)` : "the full stage is owed";