@nextcommerce/campaigns-os 1.63.0 → 1.66.0

package/skills.json

@@ -1,7 +1,7 @@
 {
   "name": "campaigns-os-skills",
   "description": "Skills bundled with Campaigns OS. `skills.sh` installs these into the shared agent skill directories (~/.claude/skills, ~/.codex/skills), so each one is a versioned package: bump the version whenever a package changes. `bundle_revision` identifies the bundle as a whole — `<package version>+skills.<n>`, where the prefix is this package's version and `<n>` counts the skill-text revisions published against it. It advances whenever ANY bundled skill changes, every SKILL.md states it on its first body line, and `campaigns-os tooling status --skills-revision <value>` compares the value an agent read from a skill against the bundle on disk. See docs/skills-revision.md.",
-  "bundle_revision": "1.63.0+skills.1",
+  "bundle_revision": "1.66.0+skills.1",
   "homepage": "https://github.com/NextCommerceCo/campaigns-os",
   "retired_skills": [
     {
@@ -16,7 +16,7 @@
     {
       "id": "next-campaigns-os",
       "name": "Campaigns OS Lifecycle",
-      "version": "1.0.69",
+      "version": "1.0.72",
       "path": "skills/next-campaigns-os/SKILL.md",
       "domain": "campaigns",
       "description": "Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth."
@@ -24,7 +24,7 @@
     {
       "id": "next-campaigns-os-setup",
       "name": "Campaigns OS Setup",
-      "version": "2.0.52",
+      "version": "2.0.55",
       "path": "skills/next-campaigns-os-setup/SKILL.md",
       "domain": "campaigns",
       "description": "Bootstrap or prepare a target page-kit campaign repo from a doctor-cleared Campaigns OS Build Packet before full build wiring. Formerly next-campaigns-setup; renamed to release that name to the published NextCommerceCo/skills scaffolder."
@@ -32,7 +32,7 @@
     {
       "id": "next-campaigns-build",
       "name": "Campaign Build",
-      "version": "1.0.54",
+      "version": "1.0.57",
       "path": "skills/next-campaigns-build/SKILL.md",
       "domain": "campaigns",
       "description": "Assemble a NEXT campaign from a doctor-cleared Build Packet, CampaignSpec/API values, prepared HTML/assets, page-kit, and starter-template contracts."
@@ -40,7 +40,7 @@
     {
       "id": "next-campaigns-polish",
       "name": "Campaign Polish",
-      "version": "1.1.54",
+      "version": "1.1.57",
       "path": "skills/next-campaigns-polish/SKILL.md",
       "domain": "campaigns",
       "description": "Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign."
@@ -48,7 +48,7 @@
     {
       "id": "next-campaigns-qa",
       "name": "Campaign QA",
-      "version": "1.3.53",
+      "version": "1.3.56",
       "path": "skills/next-campaigns-qa/SKILL.md",
       "domain": "campaigns",
       "description": "Run spec-aware QA from a saved Map or local-spec Build Packet and tested campaign URL after build, polish, and deploy/local evidence exist, including Playwright typed-card test-order proof."
@@ -56,7 +56,7 @@
     {
       "id": "campaign-lifecycle-orientation",
       "name": "Campaign Lifecycle Orientation",
-      "version": "1.0.49",
+      "version": "1.0.52",
       "path": "skills/campaign-lifecycle-orientation/SKILL.md",
       "domain": "campaigns",
       "description": "Orient a reader to the Campaigns OS lifecycle artifacts a run has already emitted, without advancing their state: the shared vocabulary, doctor as a gate, the stage record, and the store-theme/Page Kit two-worlds trap."
@@ -64,7 +64,7 @@
     {
       "id": "campaign-run-evidence",
       "name": "Campaign Run Evidence",
-      "version": "1.0.49",
+      "version": "1.0.52",
       "path": "skills/campaign-run-evidence/SKILL.md",
       "domain": "campaigns",
       "description": "Interpret existing doctor, QA verdict and proof-depth evidence without claiming more proof than the artifacts contain, and keep funnel proof apart from merchant launch readiness."
@@ -72,7 +72,7 @@
     {
       "id": "campaign-readback-classification",
       "name": "Campaign Readback Classification",
-      "version": "1.0.49",
+      "version": "1.0.52",
       "path": "skills/campaign-readback-classification/SKILL.md",
       "domain": "campaigns",
       "description": "Classify a selected campaign from the campaigns-os-readback/v2 fields (artifacts, staleness.stale_keys, clean, doctor, divergences, skip_cascades) and write a read-only handoff without turning diagnosis into permission."
@@ -80,7 +80,7 @@
     {
       "id": "contribution-intake",
       "name": "Contribution Intake",
-      "version": "1.0.49",
+      "version": "1.0.52",
       "path": "skills/contribution-intake/SKILL.md",
       "domain": "campaigns",
       "description": "Turn a suggestion about the agent surface into a classified, evidence-checked and redacted proposal, filed on this repository tracker only with attended approval."
@@ -88,7 +88,7 @@
     {
       "id": "next-campaigns-sdk-bump",
       "name": "Campaign SDK Bump",
-      "version": "1.0.9",
+      "version": "1.0.12",
       "path": "skills/next-campaigns-sdk-bump/SKILL.md",
       "domain": "campaigns",
       "description": "Bump a live campaign from one Campaign Cart 0.4.x release to a later 0.4.x on a page-kit or static repo: find every pin, check the release diff and storage against the campaign code, prove on a preview with approved test orders, and report what is not proven."

package/src/change-scope.mjs

@@ -149,11 +149,12 @@ export function classifyDrift({ changes, baseline, outputRoot, targetRepo, publi
   if (changes?.status !== "known") return { kind: "unknown", reasons: [] };
   if (!changes.changed_pages.length && !changes.unmapped_files.length) return { kind: "none", reasons: [] };
   const reasons = [];
-  for (const path of changes.unmapped_files) reasons.push({ code: "unmapped_file", path });
   const signature = recordedSignature(baseline);
+  // First, so the list's cap never drops it: `record baseline` reads it.
   if (!signature) reasons.push({ code: "commerce_signature_unavailable" });
-  else if (signature.campaign_config.startsWith("unavailable:")
-    || campaignConfigFingerprint(targetRepo, publicRouteSlug) !== signature.campaign_config) {
+  for (const path of changes.unmapped_files) reasons.push({ code: "unmapped_file", path });
+  if (signature && (signature.campaign_config.startsWith("unavailable:")
+    || campaignConfigFingerprint(targetRepo, publicRouteSlug) !== signature.campaign_config)) {
     reasons.push({ code: signature.campaign_config.startsWith("unavailable:") ? "campaign_config_unavailable" : "campaign_config_changed" });
   }
   for (const page of changes.changed_pages) {
@@ -177,6 +178,13 @@ export function classifyDrift({ changes, baseline, outputRoot, targetRepo, publi
   return { kind: reasons.length ? "commerce_affecting" : "page_only", reasons: capped(reasons) };
 }
 
+// True when a kept rebuild was read against a build recorded before markup
+// hashes existed (pre-1.62), the one kind of record `record baseline` is for.
+export function rebuiltFromBuildWithoutSignature(assembly) {
+  return Array.isArray(assembly?.build_changes) && assembly.build_changes.some((entry) => Array.isArray(entry?.reasons)
+    && entry.reasons.some((reason) => reason?.code === "commerce_signature_unavailable" && !reason.path));
+}
+
 /**
  * One build_changes entry for a rebuild from `from` to `to`, from the debt
  * assessment of the new output against the previous record.
@@ -230,8 +238,12 @@ export function worseChangeKind(a, b) {
  * The change a stage that reviewed `anchor` owes for: the recorded rebuilds
  * from `anchor` to the recorded build, then the drift from the recorded build
  * to the output on disk. Returns `{ kind, since_build_fingerprint,
- * changed_pages, unmapped_files, reasons }`; `kind` is unknown when the
- * history does not reach `anchor` or the drift cannot be read.
+ * changed_pages, unmapped_files, reasons, commerce_rebuild }`; `kind` is
+ * unknown when the history does not reach `anchor` or the drift cannot be read.
+ * `commerce_rebuild`, when there is one, is the latest recorded rebuild since
+ * `anchor` that was not page-only, with the kind of the latest change
+ * (`latest_change_kind`), so a page-only edit on top of it can say why it still
+ * owes the full stages.
  */
 export function changeSince(anchor, { assembly, drift, driftClassification }) {
   const recorded = typeof assembly?.build_fingerprint === "string" ? assembly.build_fingerprint : null;
@@ -257,9 +269,16 @@ export function changeSince(anchor, { assembly, drift, driftClassification }) {
     for (const path of part.unmapped_files || []) unmapped.add(path);
     result.reasons.push(...(reasons || []));
   };
-  for (const segment of segments) add(segment, segment.kind, segment.reasons);
+  for (const segment of segments) {
+    add(segment, segment.kind, segment.reasons);
+    if (!["none", "page_only"].includes(segment.kind)) result.commerce_rebuild = { recorded_at: segment.recorded_at ?? null, build_fingerprint: segment.build_fingerprint, kind: segment.kind };
+  }
   if (drift?.status !== "known") kind = "unknown";
   else add(drift, driftClassification?.kind || "unknown", driftClassification?.reasons);
+  if (result.commerce_rebuild) {
+    const driftKind = driftClassification?.kind || "unknown";
+    result.commerce_rebuild.latest_change_kind = driftKind === "none" ? segments.at(-1).kind : driftKind;
+  }
   return {
     ...result,
     kind,

package/src/cli.mjs

@@ -32,7 +32,7 @@ import { routeMaskedSpecMaterialHash, specMaterialHash, specHashesMatch } from "
 // The same predicate stage-ledger.mjs judges a mutator's result with, imported
 // rather than re-stated so the waive preview and the commit agree by identity.
 import { isPlainObject } from "./repo-scan.mjs";
-import { applyDerivedAssemblyReportSummary, campaignHandedOff, commitAssemblyReport, QA_GATE_PLACEHOLDER_TEXT_RESIDUE, recordProducerStageOutcome } from "./stage-ledger.mjs";
+import { applyDerivedAssemblyReportSummary, campaignHandedOff, commitAssemblyReport, QA_GATE_PLACEHOLDER_TEXT_RESIDUE, recordProducerStageOutcome, qaRestsOnBaseline } from "./stage-ledger.mjs";
 import { SESSION_ENDING_DISPOSITIONS, summarizePlaceholderTextGate, summarizePurchaseProof } from "./qa-verdict.mjs";
 import { assessRunRecordCloseout, identityMatches, latestMatchingRunRecord, reasonIsRemitRecovery } from "./run-record-closeout.mjs";
 import {
@@ -190,7 +190,7 @@ import {
   createCampaignBuildBriefArtifact,
   inferBuildBriefPath,
 } from "./build-brief.mjs";
-import { briefIntakeBindings, currentPacketInputs, inputRefreshCommands, inputStamps, stageWriteInputs } from "./input-currency.mjs";
+import { briefIntakeBindings, currentPacketInputs, currentSpecMaterial, inputRefreshCommands, inputStamps, specMaterialStamp, stageWriteInputs } from "./input-currency.mjs";
 import { prepareBuildStageStatus, priorBriefInputsForIntake } from "./input-refresh.mjs";
 import {
   DESIGN_SOURCE_PACKAGE_REL_PATH,
@@ -347,6 +347,7 @@ Usage:
   campaigns-os checkpoint waive --packet <campaign-runtime.build.json> --gate <checkpoint-id> [--page <page_id>] --reason "<why>" --waived-by "<named human>" [--expires-at <ISO>] [--review-condition "<trigger>"] [--report <json>] [--dry-run] [--json]   # one bound is required; registered gates: page_kit.store_profile, page_kit.sdk_version, polish.hidden_eager_media, built_output.upsell_selector_scope, source_html.producer_provenance (per page: --page <page_id> is required, for a Figma-typed page whose approved source is hand-written HTML). --dry-run runs every check (named human, bounds, registered and waivable gate) and prints the waiver it would write, without touching the report
   campaigns-os checkpoint accept --packet <campaign-runtime.build.json> --result <result_id>@<fingerprint12> [--result ...] --reason "<the operator's reason>" --accepted-by "<named human>" [--expires-at <ISO>] [--review-condition "<trigger>"] [--report <json>] [--dry-run] [--json]   # record the operator's accept of a measured QC warning, as the QC handoff of next prints it; changes no readiness and lapses when the measured state or the build changes. --dry-run runs every check and prints the accepts it would record, without touching the report
   campaigns-os page-kit sync --packet <campaign-runtime.build.json> [--dry-run] [--json]   # write the CampaignSpec's Store Profile fields (campaign.store_*) and SDK pin (global_config.sdk_version, runtime.sdk_version alias) into the target's _data/campaigns.json entry for the packet's route, printing a field-by-field diff; the recovery for a doctor blocked on page_kit.store_profile / page_kit.sdk_version after a fresh scaffold. Writes only those ten fields, only from usable spec values (a bad pin, a non-http URL, a non-tel: phone URI or the demo value itself is reported as not synced, status PARTIAL); exit 2 when the entry or the spec is missing, or the spec identifies another campaign.
+  campaigns-os spec fetch --packet <campaign-runtime.build.json> [--proxy-base <url>] [--json]   # restore a saved-Map packet's CampaignSpec to spec.local_path on a checkout that does not have it, then commit it. Sends one GET of {proxy-base}/api/spec/<map-id>. A copy already on disk is never replaced and nothing is sent, because it can hold spec derive edits the Map does not. Takes fetched-specs/ out of an older managed .gitignore block so the file can be committed. Reports whether the content matches the records (bound: matches, differs or unknown); differs means doctor will show build, Polish and QA owed. Exit 2 when the packet is not a saved-Map packet, the Map returns another campaign's spec, or the fetch fails.
   campaigns-os spec derive --packet <campaign-runtime.build.json> [--dry-run] [--json] [--report <json>] [--no-live-refs] [--from-store <subdomain> [--store-token-source env:<VAR>]] [--write-map] [--proxy-base <url>]   # write the fields the target repo already states into the packet's local CampaignSpec (spec.local_path): the SDK pin from _data/campaigns.json[<route>].sdk_version (global_config.sdk_version, and the runtime.sdk_version alias when declared), each page's page_url from the page tree under src/<route>/ (filename or permalink), and the analytics ids the entry carries (gtm_id -> analytics.providers.gtm.containerId, fb_pixel_id -> analytics.providers.facebook.pixelId, and each starter-template vendor's id key, such as ga4_id or triplewhale_name -> analytics.vendors.<vendor>.id); prints a field-by-field before -> after diff and writes nothing else. On a handed-off campaign (deploy or QA completed, now or in the stage's history) the page tree also adds pages (a file with a page-kit page_type no spec page binds; id from the file name, appended to the funnel, routing from its next_url/decline_url/next_step frontmatter) and removes pages (one whose built file the packet named is gone), matched by page id; page order is reported as not derived. When the packet's built _site/<route>/ exists and a public Campaigns API key resolves, it also makes the one read-only GET of {proxy-base}/api/campaign doctor makes and refreshes the fields the spec mirrors from the Campaigns App (each page package's name, price, product, variant and availability; the offer records and each page's offer copies; live offers missing from offers[] are added) — a price is never written from the repo; --no-live-refs sends nothing and leaves those fields as they are; --proxy-base names the proxy. Otherwise repo-derived fields only; --from-store <subdomain> (the <store> of <store>.29next.store) also reads through campaigns-os login gateway credentials (--store-token-source env:<VAR> explicitly selects the warned break-glass Admin path; a token never goes on the command line) and writes the nine campaign.store_* Store Profile fields: store_name and store_url (primary domain) and store_phone/store_phone_tel from GET /store/, and store_terms/privacy/contact/returns/shipping as https://<primary domain>/<slug>/ from the one storefront page (GET /pages/) whose slug or title names each policy; an empty store field, no page or several never empties the spec's value. A field the repo or store cannot state (a scaffold's seeded pin, an unbound page, an empty or malformed id, an active page_kit.sdk_version waiver, an empty store field, an unbound policy page) is reported as not derived, status PARTIAL; exit 2 when the packet, the spec or the target entry is missing, the spec identifies another campaign, or the store cannot be read (credential missing, 401/403, no such store, unreachable). --write-map also records the derived pin into the saved Map's Build hints (Campaign Cart SDK version) through the proxy Worker (PUT /api/maps/<spec.map_id> under X-Campaign-Key, the packet's Campaigns API key, with the Map's spec_hash as the X-Spec-Hash precondition): written when the Map declares no pin or one behind the repo, unchanged when equal, refused (warning, exit 0) when the Map pin is ahead or cannot be ordered, failed (error, exit 2) when the key is missing or mismatched, the Map is gone, was saved in between, or the proxy refuses the body; the write is recorded on the Assembly Report evidence[] and in the result's map object. --proxy-base overrides the canonical proxy (https, or a loopback host over http); --dry-run reads the Map and reports would_write without a PUT.
   campaigns-os page-kit parity --packet <campaign-runtime.build.json> [--report <json>] [--json]   # local proof mode (deploy.target local-serve): render the current source in development and production through the target's page-kit into temp dirs, assert the served _site/ is the current development render and that production differs from it only in environment-gated output (same page set, same route slugs, same Campaign Cart pin and next-api-key); records stages.assembly.evidence.local_proof.production_parity, which doctor reads as local_proof.production_parity. Exit 2 on a non-gated difference.
   campaigns-os polish capture --packet <campaign-runtime.build.json> --base-url <url> [--report <json>] [--headed] [--auth-cookie <cookie>] [--json]
@@ -354,6 +355,7 @@ Usage:
   campaigns-os record spec --packet <campaign-runtime.build.json> [--context <json>] [--report <json>] [--dry-run] [--json]
   campaigns-os record setup --packet <campaign-runtime.build.json> [--context <json>] [--report <json>] [--dry-run] [--json]   # record setup complete once the campaign output directory exists: Build Context scaffold.required=false and stages.setup completed, validated against their schemas before either is written
   campaigns-os record build --packet <campaign-runtime.build.json> [--build-environment <development|production>] [--adapter-decision <key>=<value>[,<key>=<value>...]] [--context <json>] [--report <json>] [--dry-run] [--json]   # after page-kit build: records scalar adapter decisions on the Assembly Report (all pairs in one flag; a repeated flag keeps only the last), stamps stages.assembly.build_fingerprint from doctor's derived.build_output_fingerprint.value (and the Design Source Package material fingerprint when present), and makes Polish required unless its evidence is bound to this output; --build-environment records stages.assembly.evidence.build_environment (local proof mode records development)
+  campaigns-os record baseline --packet <campaign-runtime.build.json> --accepted-by "<named person>" --reason "<why>" [--context <json>] [--report <json>] [--dry-run] [--json]   # one time per funnel, for a handed-off funnel whose records predate markup hashes (before 1.62.0) and whose last QA completed: accept the recorded build as the starting point without testing it, so a later page-only change owes QA on that page alone. Polish and QA read baseline_accepted, never completed, and what they held moves to history. A commerce-affecting change still owes the full stages. Run record build first. Writes the Assembly Report.
   campaigns-os record polish --packet <campaign-runtime.build.json> --evidence <polish-evidence.json> [--context <json>] [--report <json>] [--dry-run] [--json]   # after polish capture: stages.polish from the file's status (completed, completed_with_warnings, blocked with blockers, or skipped with skip_reason), evidence and optional repair_loop_defect, bound to doctor's current fingerprint; a completed status is refused, writing nothing, unless the polish gate doctor evaluates would pass. --dry-run runs every check and writes nothing
   campaigns-os record theme --packet <campaign-runtime.build.json> [--context <json>] [--report <json>] [--dry-run] [--json]   # after the brand layer is linked and build is recorded: report.theme becomes applied with load_order after-next-core, css_path, commerce_pages and per-page evidence, only when each built commerce page that loads next-core.css loads brand-theme.css (or checkout-brand.css) after it and at least one does; a page loading neither is left out as the design's own markup; refused, writing nothing, otherwise. --dry-run runs every check and writes nothing
   campaigns-os record deploy --packet <campaign-runtime.build.json> --base-url <served url> [--context <json>] [--report <json>] [--dry-run] [--json]   # a served deploy after polish is recorded: GETs every built page under the URL (the campaign route root), then records deploy.preview_url on the packet and stages.deploy completed with the URL in outputs and the build fingerprint it probed (a later record build of other output makes deploy required again). A local-serve packet takes a loopback URL and each page must answer 2xx; any other deploy target takes an https URL (plain http only on a loopback host), each page must answer 200, and every script and stylesheet the built pages load from that origin must be served byte-identical (sha256) to the built output (HTML is not compared). Refused, writing nothing, when the URL breaks those rules or is not the route root, a page does not answer, a served asset differs or is missing, the build changed since it was recorded, or the theme gate is blocked. --dry-run runs every check, the requests included, and writes nothing
@@ -720,6 +722,22 @@ function hasDoneRecommendation(session) {
   return session?.last_recommendation?.stage === "done";
 }
 
+// A page-scoped pass on a baseline paid for those pages and proved nothing
+// else, so QA still reads baseline_accepted. Only a completed full QA ends the
+// baseline: a blocked run proved nothing, so it leaves the marker alone.
+function settleQaBaseline(onBaseline, report) {
+  const qa = report.stages?.qa;
+  if (!isObject(qa) || !String(qa.status).startsWith("completed")) return report;
+  if (!onBaseline) {
+    delete qa.baseline_accepted_at;
+    return report;
+  }
+  qa.status = "baseline_accepted";
+  delete qa.completed_at;
+  delete qa.purchase_proof;
+  return report;
+}
+
 export function recordQaStageOutcome(args, result) {
   try {
     const packetArg = optionalString(args.packet);
@@ -757,7 +775,8 @@ export function recordQaStageOutcome(args, result) {
         throw new Error("The build was recorded again during this page-scoped QA run; report evidence was not changed. Re-run qa run --page against the recorded build.");
       }
       const evidence = qaStageGateEvidence(verdict, report, result);
-      return recordProducerStageOutcome(report, {
+      const onBaseline = Boolean(pageScope && report.stages?.qa?.baseline_accepted_at);
+      return settleQaBaseline(onBaseline, recordProducerStageOutcome(report, {
         stage: "qa",
         disposition: verdict.disposition,
         timestamp: verdict.completed_at,
@@ -783,12 +802,14 @@ export function recordQaStageOutcome(args, result) {
         // path from a `--test-order off` diagnostic. A page-scoped run places
         // no orders and the change it pays touches no commerce, so the
         // purchase proof of the full run it extends is kept.
-        proof: pageScope && isObject(report.stages?.qa?.purchase_proof)
+        // On a baseline there is none to keep, and a zero from this run would
+        // read as a purchase that failed, not one nobody tested.
+        proof: pageScope && (isObject(report.stages?.qa?.purchase_proof) || onBaseline)
           ? report.stages.qa.purchase_proof
           : summarizePurchaseProof({ verdict, proofPolicy: packet.qa?.proof_policy }),
         stamps: qaStamps,
         inputs: qaInputs,
-      });
+      }));
     }, {
       stage: "qa",
       // The sidecar names this refresh as its producer (generated_by, #312).
@@ -1251,7 +1272,12 @@ async function dispatch(command, args, { recorder = NOOP_RECORDER, ambient = nul
     // Inequality on purpose: src/invocation.test.mjs harvests top-level
     // command literals by an equality pattern a subcommand equality would
     // also match.
-    if (subcommand !== "derive") throw refused("Unknown spec subcommand. Use: campaigns-os spec derive --packet <campaign-runtime.build.json> [--dry-run] [--json].");
+    if (subcommand !== "derive" && subcommand !== "fetch") throw refused("Unknown spec subcommand. Use: campaigns-os spec derive --packet <campaign-runtime.build.json> [--dry-run] [--json], or campaigns-os spec fetch --packet <campaign-runtime.build.json> [--proxy-base <url>] [--json].");
+    if (subcommand !== "derive") {
+      const fetched = await specFetchCommand(args);
+      writeResult(fetched, args, fetched.ok ? 0 : 2);
+      return;
+    }
     const result = await specDeriveWithMapWriteback(args);
     if (args.json) console.log(JSON.stringify(result, null, 2));
     else for (const line of specDeriveWriteMapTextLines(result)) console.log(line);
@@ -3745,6 +3771,93 @@ function listPageKitPageFiles(outputDir, publicRouteSlug, { assetsHtmlIgnored =
   return files.sort((a, b) => a.path.localeCompare(b.path));
 }
 
+const SPEC_FETCH_FLAGS = ["_", "packet", "proxy-base", "json"];
+
+// `spec fetch`: put a saved-Map packet's CampaignSpec back on a checkout that
+// lacks it. Only ever fills a gap: the copy on disk can hold `spec derive`
+// edits the Map does not, so it is never replaced. The packet and the records
+// are not touched either; a Map that has moved since they were made is
+// reported as `bound: "differs"` for doctor and `record spec` to deal with.
+export async function specFetchCommand(args, { fetchImpl = undefined } = {}) {
+  const unknown = Object.keys(args).filter((key) => !SPEC_FETCH_FLAGS.includes(key));
+  if (unknown.length) {
+    throw refused(`Unknown flag${unknown.length > 1 ? "s" : ""} for spec fetch: ${unknown.map((key) => `--${key}`).join(", ")}. Known flags: --packet, --proxy-base, --json.`);
+  }
+  if (Object.hasOwn(args, "proxy-base") && !optionalString(args["proxy-base"])) throw refused("spec fetch: --proxy-base needs a URL (https, or a loopback host); nothing was written.");
+  const packetPath = resolve(requireArg(args, "packet"));
+  const result = { ok: false, status: "blocked", packet_path: packetPath, spec_path: null, map_id: null, bound: "unknown", gitignore: null, errors: [], warnings: [], ready: [] };
+  const workspace = (() => {
+    try {
+      return resolveCampaignWorkspace(packetPath, { followContextPointer: true });
+    } catch (error) {
+      addIssue(result.errors, "spec.fetch.packet_unreadable", `Could not read the packet: ${singleLineDetail(error.message)}`);
+      return null;
+    }
+  })();
+  if (!workspace) return result;
+  const mapId = optionalString(workspace.packet?.spec?.map_id);
+  const localPath = optionalString(workspace.packet?.spec?.local_path);
+  if (!mapId || !localPath || !workspace.targetRepo) {
+    addIssue(result.errors, "spec.fetch.not_saved_map", "This packet does not name a saved Map and a spec.local_path, so there is nothing to fetch. A local-spec packet's CampaignSpec is restored from wherever it is kept.");
+    return result;
+  }
+  result.map_id = mapId;
+  const cachePath = join(workspace.targetRepo, ".campaign-runtime", "fetched-specs", `${sanitizeMapIdForFilename(mapId)}.json`);
+  const specPath = resolveFromFile(packetPath, localPath);
+  result.spec_path = specPath;
+  if (specPath !== cachePath) {
+    addIssue(result.errors, "spec.fetch.not_saved_map", `spec.local_path is ${localPath}, not this Map's copy (.campaign-runtime/fetched-specs/${basename(cachePath)}), so spec fetch cannot restore it. Restore that file from where it is kept.`);
+    return result;
+  }
+  let boundMaterial;
+  let specMaterial;
+  try {
+    const report = existsSync(workspace.reportPath) ? readJson(workspace.reportPath) : null;
+    boundMaterial = specMaterialStamp(report?.identity?.spec_material_hash);
+    if (existsSync(specPath)) {
+      specMaterial = currentSpecMaterial(readJson(specPath));
+      result.status = "present";
+      result.ready.push(`${localPath} is already here; it was left as it is and nothing was fetched.`);
+    } else {
+      assertFetchedSpecCacheWritable(workspace.targetRepo, cachePath);
+      const fetched = await fetchSpecByMapId(mapId, { proxyBase: optionalString(args["proxy-base"]) || DEFAULT_PROXY_BASE, fetchImpl });
+      // This file is what the records and spec derive read, so it must be this campaign's.
+      const fetchedMapId = optionalString(fetched?.spec_identity?.map_id) || optionalString(fetched?.map_id);
+      const fetchedSlug = specPublicRouteSlug(fetched);
+      const packetSlug = normalizePublicRouteSlug(workspace.packet?.campaign?.public_route_slug);
+      if ((fetchedMapId && fetchedMapId !== mapId) || (fetchedSlug && packetSlug && fetchedSlug !== packetSlug)) {
+        addIssue(result.errors, "spec.fetch.identity_mismatch", `The Map returned a spec for ${singleLineField(fetchedMapId || mapId)} on route "${singleLineField(fetchedSlug || "")}", but this packet is ${singleLineField(mapId)} on route "${singleLineField(packetSlug || "")}"; nothing was written.`);
+        return result;
+      }
+      // The same reduction intake made, so the copy reads as the records' did.
+      const { spec } = stripHostPrefixedRoutes(fetched);
+      // Again at the write: the links can change during the request.
+      assertFetchedSpecCacheWritable(workspace.targetRepo, cachePath);
+      mkdirSync(dirname(cachePath), { recursive: true });
+      replaceFetchedSpec(cachePath, `${JSON.stringify(spec, null, 2)}\n`);
+      specMaterial = currentSpecMaterial(spec);
+      result.status = "restored";
+      result.ready.push(`Restored ${localPath} from the saved Map. Commit it so the next checkout has it.`);
+    }
+  } catch (error) {
+    addIssue(result.errors, "spec.fetch.failed", singleLineDetail(error.message));
+    return result;
+  }
+  result.ok = true;
+  const current = specMaterialStamp(specMaterial);
+  result.bound = boundMaterial && current ? (boundMaterial === current ? "matches" : "differs") : "unknown";
+  if (result.bound === "differs") {
+    addIssue(result.warnings, "spec.fetch.differs_from_records", "This spec differs from the one the campaign's records were made against: the Map changed since then, or the earlier copy held `spec derive` edits the Map does not. Doctor will show build, Polish and QA owed until `record spec` binds it.");
+  }
+  if (result.bound === "matches") result.ready.push("It matches the spec the campaign's records were made against.");
+  if (result.bound === "unknown") result.ready.push("The report records no spec to compare it with.");
+  // The file has to be committable, and older repositories' managed block says otherwise.
+  result.gitignore = ensureRuntimeStateIgnored(workspace.targetRepo);
+  if (result.gitignore.removed_entries?.length) result.ready.push("Took fetched-specs/ out of the managed .gitignore block.");
+  if (result.gitignore.action === "skipped") addIssue(result.warnings, "spec.fetch.gitignore_not_updated", `Could not update .gitignore (${singleLineDetail(result.gitignore.reason)}). If it still lists .campaign-runtime/fetched-specs/, remove that line so this file can be committed.`);
+  return result;
+}
+
 export function specDeriveCommand(args, { store: storeRead = null, liveCampaign = undefined } = {}) {
   // A command that rewrites the spec rejects flags it does not know: a
   // mistyped --dryrun must not fall through to a real write. --report names
@@ -4643,7 +4756,7 @@ export function nextStage(stage, args, ambient = null, { qcStandIns = null, qcRe
         errors,
         warnings,
         ready,
-        prompt: `Pipeline complete. All stages in the assembly report are in a terminal status. To repeat build work, do the work and run \`${cmd("record")} build --packet <path>\`; this makes downstream stages owed as needed. \`${cmd("record")} deploy\` records the served deploy, a loopback URL for a local-serve target or an https URL for a hosted one. Run \`${cmd("qa")} run\` for QA. Then call \`${cmd("next")}\` again. If a run session is active, finish it with \`${cmd("run")} end\` so the Run Record is assembled and the session closes.${report?.stages?.qa?.status === "completed_with_warnings" ? " QA passed with exceptions; report them to the operator without clearing or waiving them or changing markup just to make them pass." : ""}`,
+        prompt: `Pipeline complete. All stages in the assembly report are in a terminal status. To repeat build work, do the work and run \`${cmd("record")} build --packet <path>\`; this makes downstream stages owed as needed. \`${cmd("record")} deploy\` records the served deploy, a loopback URL for a local-serve target or an https URL for a hosted one. Run \`${cmd("qa")} run\` for QA. Then call \`${cmd("next")}\` again. If a run session is active, finish it with \`${cmd("run")} end\` so the Run Record is assembled and the session closes.${report?.stages?.qa?.status === "completed_with_warnings" ? " QA passed with exceptions; report them to the operator without clearing or waiving them or changing markup just to make them pass." : ""}${qaRestsOnBaseline(report) ? ` QA rests on a baseline ${report.commerce_baseline.accepted_by} accepted, not a test; say so when you report this campaign.` : ""}${warnings.some((issue) => issue.code === "built_output.absent") ? " The built output is not on this checkout, so these records were not compared with it; build before treating the campaign as current." : ""}`,
       });
     }
     stage = picked.stage;

package/src/commercial-journey.mjs

@@ -632,6 +632,9 @@ function normalizeLine(echo, state, packages) {
     })),
     final: moneyFact(line.total, state),
     savings: moneyFact(line.total_discount, state),
+    // What one unit costs after offers: the figure a printed per-unit price is
+    // held against. A response without it leaves that claim unresolved.
+    ...(present(line.unit_price) ? { unit_price: moneyFact(line.unit_price, state) } : {}),
   };
 }
 

package/src/commercial-parity.mjs

@@ -1,8 +1,11 @@
 /**
  * Dependency-free extraction and Exact-only commercial parity comparison.
  *
- * Source HTML is intentional: Campaign Cart replaces authored placeholders
- * after readiness, which can hide an authored mismatch in the rendered DOM.
+ * Source HTML is intentional for bundle prices: Campaign Cart replaces authored
+ * placeholders after readiness, which can hide an authored mismatch in the
+ * rendered DOM. package.price is the other way round: its authored text is a
+ * template placeholder no shopper is meant to read, so only its rendered value
+ * is compared and the source merely says the claim exists.
  */
 
 import {
@@ -416,6 +419,48 @@ function governedPriceBinding(value) {
   return typeof value === "string" && /^bundle\.[^.]+\.price$/.test(value.trim());
 }
 
+// The SDK's own package.price paths: an id in the path, or none and the nearest
+// package id around the node. No other package.* field is a price claim here.
+const PACKAGE_PRICE_BINDING = /^package\.(?:([1-9]\d*)\.)?price$/;
+const PACKAGE_CONTEXT_ATTRIBUTES = Object.freeze(["data-next-package-id", "data-next-package", "data-package-id"]);
+
+export const PACKAGE_PRICE_NOT_RENDERED = "package_price_not_rendered";
+export const PACKAGE_PRICE_NOT_FILLED = "package_price_not_filled";
+export const PACKAGE_PRICE_UNRESOLVED = "package_price_unresolved";
+
+function packageContextId(node) {
+  for (let current = node; current; current = current.parent) {
+    for (const attribute of PACKAGE_CONTEXT_ATTRIBUTES) {
+      const id = positiveInteger(current.attrs?.[attribute]);
+      if (id !== null) return id;
+    }
+  }
+  return null;
+}
+
+// Lists the claims, deliberately without their text: what the source holds is
+// the template's placeholder, and comparing it would report every starter page.
+function extractPackagePrices(nodeIndex, consumeClaim) {
+  const seen = new Set();
+  const claims = [];
+  nodeIndex.nodes.forEach((node) => {
+    const binding = String(node.attrs?.["data-next-display"] || "").trim();
+    const match = PACKAGE_PRICE_BINDING.exec(binding);
+    const format = String(node.attrs?.["data-next-format"] || "currency").trim().toLowerCase();
+    if (!match
+      || format !== "currency"
+      || nodeIndex.hidden.get(node) === true
+      || nodeIndex.comparison.get(node) === true) return;
+    const packageId = positiveInteger(match[1]) ?? packageContextId(node);
+    const key = `${binding}\u0000${packageId}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    consumeClaim();
+    claims.push({ binding, package_id: packageId });
+  });
+  return claims;
+}
+
 function extractPrices(nodeIndex, consumeClaim) {
   const seen = new Set();
   const prices = [];
@@ -529,6 +574,7 @@ export function extractCommercialClaims(html, options = {}) {
     }
   };
   const priceClaims = extractPrices(nodeIndex, consumeClaim);
+  const packagePriceClaims = extractPackagePrices(nodeIndex, consumeClaim);
   const recurrenceClaims = extractRecurrences(nodeIndex, extractionErrors, consumeClaim);
   const vouchers = extractVouchers(nodeIndex, extractionErrors, consumeClaim);
   return {
@@ -537,6 +583,7 @@ export function extractCommercialClaims(html, options = {}) {
     price_claims: priceClaims,
     recurrence_claims: recurrenceClaims,
     vouchers,
+    ...(packagePriceClaims.length ? { package_price_claims: packagePriceClaims } : {}),
     ...(extractionErrors.length ? { extraction_errors: extractionErrors } : {}),
   };
 }
@@ -563,8 +610,23 @@ function validVoucherClaim(claim) {
   return record(claim) && typeof claim.code === "string" && present(claim.code);
 }
 
+function validPackagePriceClaim(claim) {
+  return record(claim)
+    && typeof claim.binding === "string"
+    && PACKAGE_PRICE_BINDING.test(claim.binding)
+    && (claim.package_id === null || positiveInteger(claim.package_id) !== null);
+}
+
+function validRenderedPackagePrice(claim) {
+  return validPackagePriceClaim(claim)
+    && typeof claim.filled === "boolean"
+    && (claim.text === null || typeof claim.text === "string");
+}
+
 function validCaptureEnvelope(capture) {
   if (!record(capture)) return false;
+  if (capture.package_price_claims !== undefined && !Array.isArray(capture.package_price_claims)) return false;
+  if (capture.rendered_package_prices !== undefined && !Array.isArray(capture.rendered_package_prices)) return false;
   if (capture.page_id !== undefined
     && capture.page_id !== null
     && (typeof capture.page_id !== "string" || !present(capture.page_id))) return false;
@@ -580,7 +642,9 @@ function validCapture(capture) {
   return validCaptureEnvelope(capture)
     && capture.price_claims.every(validPriceClaim)
     && capture.recurrence_claims.every(validRecurrenceClaim)
-    && capture.vouchers.every(validVoucherClaim);
+    && capture.vouchers.every(validVoucherClaim)
+    && array(capture.package_price_claims).every(validPackagePriceClaim)
+    && array(capture.rendered_package_prices).every(validRenderedPackagePrice);
 }
 
 function captureCandidates(capturesValue) {
@@ -626,6 +690,64 @@ function priceComparisonClaims(capture, page) {
   return { compared, unresolved: claims.length - compared.length };
 }
 
+// Printed money as the SDK formats it: a symbol or code around one amount. A
+// decimal comma or anything else stays unread, so it is unresolved, not wrong.
+function renderedMoney(text) {
+  const match = decodeEntities(String(text ?? "")).replace(/[\u00a0\s]+/g, " ").trim()
+    .match(/^[^\d-]*(\d[\d,]*(?:\.\d{1,2})?)\s*[A-Za-z]*$/);
+  return match ? normalizeMoney(match[1]) : null;
+}
+
+// One distinct Exact per-unit price for the package on this page, or nothing:
+// two rows of one package at different unit prices (quantity tiers, say) do not
+// say which one a generic package.price means.
+function exactPackageUnitPrice(page, packageId) {
+  const prices = new Set(array(page?.rows)
+    .filter((row) => String(row?.package_id) === String(packageId))
+    .map((row) => (row?.state === PricingState.Exact ? exactMoneyFact(row?.unit_price)?.value : null)));
+  return prices.size === 1 ? [...prices][0] ?? null : null;
+}
+
+// The rendered read is the authority once it found any. When it found none, the
+// source still says the claims exist, so they are not allowed to disappear.
+export function packagePriceClaimCount(capture) {
+  const rendered = array(capture?.rendered_package_prices);
+  return rendered.length || array(capture?.package_price_claims).length;
+}
+
+/**
+ * Sort a page's package.price claims into compared and unresolved. Only a
+ * rendered value the SDK filled is ever compared. Each unresolved claim names
+ * its reason, so the run can say what to do about it. Distinct claims only: one
+ * price repeated around an upsell page is one claim.
+ */
+function packagePriceComparisonClaims(capture, page) {
+  const rendered = array(capture?.rendered_package_prices);
+  if (!rendered.length) {
+    return {
+      compared: [],
+      unresolved: array(capture?.package_price_claims).map(() => PACKAGE_PRICE_NOT_RENDERED),
+    };
+  }
+  const compared = [];
+  const unresolved = [];
+  const voucherUnpriced = voucherComparisonClaims(capture, page).unresolved > 0;
+  rendered.forEach((claim) => {
+    if (!claim?.filled) {
+      unresolved.push(PACKAGE_PRICE_NOT_FILLED);
+      return;
+    }
+    const value = renderedMoney(claim.text);
+    const truth = claim.package_id === null || voucherUnpriced ? null : exactPackageUnitPrice(page, claim.package_id);
+    if (!value || !truth) {
+      unresolved.push(PACKAGE_PRICE_UNRESOLVED);
+      return;
+    }
+    compared.push({ package_id: claim.package_id, value, truth });
+  });
+  return { compared, unresolved };
+}
+
 function pageForCapture(capture, journey) {
   const pages = array(journey?.pages);
   if (present(capture?.page_id)) {
@@ -745,6 +867,19 @@ export function diffCommercialParity(capturesValue, journey, options = {}) {
       });
     }
 
+    (compareMoney ? packagePriceComparisonClaims(capture, page).compared : []).forEach(({ package_id: packageId, value, truth }) => {
+      if (moneyToCents(value) === moneyToCents(truth)) return;
+      findings.push({
+        type: "price-claim-mismatch",
+        page_id: pageId,
+        ...source,
+        binding: `package.${packageId}.price`,
+        package_id: packageId,
+        claimed: value,
+        calculated: truth,
+      });
+    });
+
     (compareMoney ? recurrenceComparisonClaims(capture, page).compared : []).forEach(({ claim, truth }) => {
       const packageId = positiveInteger(claim?.package_id);
       const claimed = {
@@ -817,7 +952,11 @@ function assertionForFinding(finding, id) {
       ...common,
       expected: finding.calculated,
       actual: finding.claimed,
-      evidence: { type: finding.type, binding: finding.binding },
+      evidence: {
+        type: finding.type,
+        binding: finding.binding,
+        ...(finding.package_id !== undefined ? { package_id: finding.package_id } : {}),
+      },
     };
   }
   if (finding.type === "cadence-disclosure-mismatch") {
@@ -952,7 +1091,7 @@ export function createCommercialParityReport(capturesValue, journey, options = {
     .filter((page) => !pageKeys.has(String(page?.page_id ?? "page")))
     .map((page) => ({ page_id: present(page?.page_id) ? String(page.page_id) : null }));
   const extractedPriceClaims = matched.reduce(
-    (sum, { capture }) => sum + capture.price_claims.length,
+    (sum, { capture }) => sum + capture.price_claims.length + packagePriceClaimCount(capture),
     0,
   );
   const extractedRecurrenceClaims = matched.reduce(
@@ -963,12 +1102,22 @@ export function createCommercialParityReport(capturesValue, journey, options = {
     (sum, { capture }) => sum + capture.vouchers.length,
     0,
   );
+  const packagePriceCounts = {
+    extracted: matched.reduce((sum, { capture }) => sum + packagePriceClaimCount(capture), 0),
+    compared: 0,
+  };
+  const packagePriceUnresolved = {};
   const priceComparisonCounts = countsOnly || moneyReason
     ? { compared: 0, unresolved: extractedPriceClaims }
     : matched.reduce((counts, { capture, page }) => {
       const comparison = priceComparisonClaims(capture, page);
-      counts.compared += comparison.compared.length;
-      counts.unresolved += comparison.unresolved;
+      const packagePrices = packagePriceComparisonClaims(capture, page);
+      packagePriceCounts.compared += packagePrices.compared.length;
+      packagePrices.unresolved.forEach((code) => {
+        packagePriceUnresolved[code] = (packagePriceUnresolved[code] || 0) + 1;
+      });
+      counts.compared += comparison.compared.length + packagePrices.compared.length;
+      counts.unresolved += comparison.unresolved + packagePrices.unresolved.length;
       return counts;
     }, { compared: 0, unresolved: 0 });
   const recurrenceComparisonCounts = countsOnly || moneyReason
@@ -1007,6 +1156,7 @@ export function createCommercialParityReport(capturesValue, journey, options = {
     extracted_price_claims: extractedPriceClaims,
     compared_price_claims: priceComparisonCounts.compared,
     unresolved_price_claims: priceComparisonCounts.unresolved,
+    package_price_claims: { ...packagePriceCounts, unresolved: packagePriceUnresolved },
     extracted_recurrence_claims: extractedRecurrenceClaims,
     compared_recurrence_claims: recurrenceComparisonCounts.compared,
     unresolved_recurrence_claims: recurrenceComparisonCounts.unresolved,