@nextcommerce/campaigns-os 1.55.0 → 1.59.0

package/skills/campaign-run-evidence/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: campaign-run-evidence
-version: 1.0.32
+version: 1.0.37
 description: Interpret existing Campaigns OS doctor, QA and proof-depth evidence without claiming more proof than the artifacts contain.
 ---
 
-Bundle revision: 1.55.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.0+skills.1`
+Bundle revision: 1.59.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read

package/skills/contribution-intake/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: contribution-intake
-version: 1.0.32
+version: 1.0.37
 description: Turn a suggestion about the agent surface into a classified, evidence-checked proposal and, only with attended approval, one issue on this repository's tracker.
 ---
 
-Bundle revision: 1.55.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.0+skills.1`
+Bundle revision: 1.59.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read

package/skills/next-campaigns-build/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-build
-version: 1.0.37
+version: 1.0.42
 description: Assemble a NEXT campaign from a doctor-cleared Build Packet, CampaignSpec/API values, prepared HTML/assets, page-kit, and starter-template contracts.
 ---
 
-Bundle revision: 1.55.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.0+skills.1`
+Bundle revision: 1.59.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read
@@ -100,7 +100,9 @@ Build rules:
 - If setup/build needs starter-template files, copy the template family atomically with its dependent pages, `_includes/`, `_layouts/`, `assets/css/`, and `assets/js/`; copying only checkout/receipt pages is incomplete.
 - Resolve SDK routing meta tags to deployed campaign-root paths, not spec literals. For example, `next-success-url: upsell/` in the spec should become `/<public_route_slug>/upsell/` in built HTML.
 - If an order bump package comes from `packages.prepurchase_*` and is not one of the main `bundles[]`, default `package_sync=false` and `show_line_total_price=false` unless the CampaignSpec explicitly says the add-on quantity must sync with the main bundle.
-- For two-step package-selection-before-checkout flows, use the selector page as the pre-checkout step, encode the selected cart with `forcePackageId`, preserve attribution/tracking params, and strip `forcePackageId` from the visible checkout URL after SDK initialization.
+- Multi-step checkout paths run `select` → `checkout_step`… → `checkout`; only the `checkout` page takes payment. On a `select` page the swap-mode bundle selector (`data-next-bundle-selector` with `data-next-selection-mode="swap"`) writes the cart and the SDK persists it between pages; a checkout button or link (`href` from the page's `next_step`) goes to the next page. Use `forcePackageId` only on a page with no selector, such as a landing call-to-action into a checkout that renders none.
+- Each `checkout_step` page's checkout form (`<form data-next-checkout="form">`) carries `data-next-checkout-step="<its next_step>"` and `data-next-step-number="<step_number>"` (frontmatter `next_step` and `step_number`, 1 for the first step on its path). The `checkout` page's form carries neither.
+- On `select` and `checkout_step` pages, frontmatter `next_url` is the Checkout's post-payment destination, the same meaning it has on the `checkout` page, and the layout renders it as the `next-success-url` meta tag: the SDK reads that tag for express orders placed on the page. `next_step` is the page's forward link. A landing page keeps `next_url` as its call-to-action target; if it has express checkout buttons, set its `next-success-url` to the Checkout's own `next_url` from the Build Context `page_map`, never to the landing page's `next_url`. Forward navigation uses the step form attribute or a plain link, never that meta tag. Page Kit frontmatter has no `success_url` key; `success_url` stays a CampaignSpec field on `checkout` pages.
 - Record intentional drops from source HTML in the assembly report, especially payment/provider changes such as "PayPal removed because CampaignSpec available_payment_methods excludes it." Polish must inherit these decisions.
 - Preserve any existing Build Context `theme` inspection state and Assembly Report `theme` application state. If build applies, skips, or invalidates generated theme CSS, update `report.theme` rather than leaving stale evidence.
 - After page-kit build, inspect rendered `_site` output: body exists, Campaign Cart runtime markers exist, `sdk_hints.meta_tags` rendered, route meta points at the campaign root, and copied funnel attribution/runtime baggage is gone.

package/skills/next-campaigns-os/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-os
-version: 1.0.52
+version: 1.0.57
 description: Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth.
 ---
 
-Bundle revision: 1.55.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.0+skills.1`
+Bundle revision: 1.59.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read

package/skills/next-campaigns-os-setup/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-os-setup
-version: 2.0.35
+version: 2.0.40
 description: Bootstrap or prepare a target page-kit campaign repo from a doctor-cleared Campaigns OS Build Packet before full build wiring. Formerly installed as next-campaigns-setup; renamed 2026-08 to stop colliding with the published NextCommerceCo/skills scaffolder of that name.
 ---
 
-Bundle revision: 1.55.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.0+skills.1`
+Bundle revision: 1.59.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read

package/skills/next-campaigns-polish/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-polish
-version: 1.1.36
+version: 1.1.42
 description: Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign.
 ---
 
-Bundle revision: 1.55.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.0+skills.1`
+Bundle revision: 1.59.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read
@@ -71,14 +71,29 @@ Responsibilities:
 - For bundle selectors and order bumps, verify active/inactive visual state after interaction, mobile label wrapping, badge placement, and selected/unchecked state. A native hidden input state that disagrees with the SDK class state is a polish blocker. So is a selected/active visual driven by a *non-SDK static attribute the SDK never clears* — e.g. a hardcoded `data-selected="true"` left on the initial card. (The native `selected` attribute on `<option>`/custom selects *is* SDK/browser-managed, so do not flag that.) The selected style must follow the SDK-managed class (e.g. `.next-selected` — see the family's bundle-selector selectors in `contracts/template-brand-contract.<family>.v0.json`) so a single-select swap clears the previous selection. Verify by interaction that the previously-selected item deselects after another is picked — a selector that only ever paints "selected" on click is a blocker.
 - For exit-intent pops and promo-code inputs, polish the wrapper/copy states without breaking SDK coupon/voucher apply hooks or `cart.hasCoupon("CODE")` conditional labels.
 - If `report.theme` or `context.theme` exists, verify brand-theme load order after `next-core.css`, source-token parity for primary color/CTA/surface/text/font/radius when present, and SDK safety. When the brand layer is missing, stale, low-confidence, or unsafe to apply, record the first repair-loop defect or an explicit skipped reason.
-- Before recording a terminal Polish status, install the package-owned browser
-  once with `npx --no-install campaigns-os qa install-browser`, serve the
-  current build, and run `campaigns-os polish capture --packet <packet> --base-url <served-build-url>`
+- When at least one mapped page has a design route, before recording a terminal
+  Polish status, install the package-owned browser once with
+  `npx --no-install campaigns-os qa install-browser`, serve the current build,
+  and run `campaigns-os polish capture --packet <packet> --base-url <served-build-url>`
   (tier `A`: it writes the polish evidence and assembly report under the target
   and fetches the served build at `--base-url`).
   The package captures every mapped route at fixed desktop/mobile viewports and
   attaches `stages.polish.evidence.visual_review.page_load`. Never hand-author,
   copy, or repair that object directly.
+- If every mapped page is template stock (`skip_reason`), there is no design
+  route for that capture. On a local loopback preview, or a hosted preview at
+  the packet's non-loopback HTTP(S) `deploy.preview_url` that differs from
+  `deploy.production_url` by origin or route path, doctor carries the missing
+  evidence forward as a warning. Query or fragment text on the production
+  page does not make it a distinct preview. If the hosted preview URL is not
+  yet recorded, run
+  `campaigns-os qa policy set --packet <packet> --preview-url <url>` first,
+  then `campaigns-os next --packet <packet>`. Run
+  `campaigns-os next qa --packet <packet>`, then
+  `campaigns-os qa run --packet <packet> --base-url <preview-url> --browser
+  --test-order common`. The hosted preview URL satisfies the deploy handoff;
+  after QA records its verdict, run `campaigns-os next --packet <packet>` for
+  closeout. QA against the packet's production URL keeps the checkpoint blocked.
 - When a readability warning appears, report it with its colours, ratio, requirement and pages. Offer the operator options inside the brand palette (a darker or lighter shade of the same hue, the palette's text colour, or a larger, bold label where the design allows). Do not recolour the merchant's design until the operator chooses. Accept a warning only with the refs, reason and name the operator gives you at the QC handoff.
 - Record Polish as `completed`, `skipped`, or `blocked` with
   `campaigns-os record polish --packet <packet> --evidence <polish-evidence.json>`

package/skills/next-campaigns-qa/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-qa
-version: 1.3.36
+version: 1.3.41
 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.
 ---
 
-Bundle revision: 1.55.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.55.0+skills.1`
+Bundle revision: 1.59.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read
@@ -110,6 +110,7 @@ Rules:
 - After the base checkout test order redirects to upsell, click the rendered SDK upsell accept/decline controls to prove the live upsell path. Do not fabricate upsell lines with a direct API call.
 - Valid test-order modes are `common`, `checkout`, `accept`, `decline`, `both`, `full`, `off`, and explicit accept/decline paths such as `accept-decline-accept`.
 - Browser test orders default to `--max-test-orders 6` (an accidental-flood guard, not a permission gate). Planning happens before browser launch; when `full` exceeds the cap, use explicit sample paths or rerun with the exact larger cap printed by the command (a linear three-offer graph plans nine orders, so use `--max-test-orders 9`). That cap bounds planned paths; `--max-order-creations` bounds real order creations, defaults to the planned path count, and is reserved before each submit click. A run that hits it stops that path with an explicit budget assertion — read it as a safety stop, not as a checkout defect, and account for the orders already created before raising it.
+- The checkout a test order drives is the Checkout on the tested path: the page typed `checkout`, which takes payment, never the first page typed checkout. On a multi-step path (`select` → `checkout_step`… → `checkout`) the runner enters the cart on the select page (bundle cards plus a checkout button; `--select-package` clicks the matching `data-next-bundle-card`) or on the first step, submits each `checkout_step` form and asserts it lands on the step's declared next page (`checkout_step_submitted`), and submits the order only on the Checkout. A campaign may hold several Checkouts, one per split-test path.
 - Resolve paths from the selected checkout's `expected_next_url`, then follow reachable offer `expected_accept_url` / `expected_decline_url` edges. Treat only declared receipt/thank-you pages and genuine cross-origin handoffs as terminals; an absent same-origin route is unresolved, not an external handoff.
 - `--test-order common` is the default depth. When every actual terminal path fits under the flood cap (`--max-test-orders`, 6 by default), it runs them all and records effective depth `full`, reason `under_cap`. Above the cap it runs checkout, first-offer accept/decline and the shortest real receipt path, then adds the shortest path that clicks the decline on each offer or downsell page no planned path declines yet, until the cap is reached, and names any page left out. It never trims the checkout/accept/decline/receipt sample to fit a lower cap, and it must not synthesize a receipt path from offer count.
 - A page counts as exercised only when an order of its own funnel clicked its decline control. Reaching the page, or clicking only its accept, does not count. `browser-test-order:upsell-action-coverage` reports this for every page with upsell actions in every funnel of the run, and is `pass` or `warn` only when coverage is certain (orders placed, every offer page listed with its own unshared URL, every plan matched to one funnel, every click on a declared page of the order's funnel): `warn` names each page whose decline no order clicked and each funnel no order ran through, `pass` means every page's decline was clicked. Anything uncertain is `manual_review` naming the pages and why (`evidence.reason`, `evidence.not_assessable`, `evidence.uncertainty`), including a `--test-order off` run or attempts that all failed before an order reference. Read `warn` and `manual_review` as missing proof, not as a defect.

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.55.0+skills.1",
+  "bundle_revision": "1.59.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.52",
+      "version": "1.0.57",
       "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.35",
+      "version": "2.0.40",
       "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.37",
+      "version": "1.0.42",
       "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.36",
+      "version": "1.1.42",
       "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.36",
+      "version": "1.3.41",
       "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.32",
+      "version": "1.0.37",
       "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.32",
+      "version": "1.0.37",
       "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.32",
+      "version": "1.0.37",
       "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.32",
+      "version": "1.0.37",
       "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."

package/src/adapter-decision-contract.mjs

@@ -38,7 +38,7 @@ export const TEMPLATE_SLICE_REQUIRED_GROUPS = Object.freeze([
 ]);
 
 const TEMPLATE_FILES_COPIED_REQUIRED_FIELDS = Object.freeze(["status", "required_groups", "groups", "paths"]);
-const RUNTIME_PAGE_TYPES = new Set(["checkout", "select", "upsell", "downsell", "thankyou", "receipt"]);
+const RUNTIME_PAGE_TYPES = new Set(["checkout", "checkout_step", "select", "upsell", "downsell", "thankyou", "receipt"]);
 const RAW_HTML_CONVERSION_STATUSES = new Set(["pending", "in_progress", "completed", "not_required", "blocked"]);
 const SOURCE_ASSET_STRATEGIES = new Set(["pagekit_campaign_asset_root", "external_cdn", "raw_passthrough", "not_applicable", "unknown"]);
 const ROUTE_REWRITE_POLICIES = new Set(["campaignspec_routes_via_campaign_link", "pagekit_public_routes", "raw_passthrough", "not_applicable", "unknown"]);

package/src/build-brief.mjs

@@ -3,6 +3,7 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { basename, extname, join, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
 
+import { CHECKOUT_FLOW_PAGE_TYPES } from "../campaign-spec/dist/index.js";
 import { cmd } from "./install-invocation.mjs";
 import { canonicalJson } from "./polish-capture.mjs";
 import { escapeRegExp } from "./repo-scan.mjs";
@@ -537,7 +538,7 @@ function draftCampaignBuildBrief({ spec, activePages, pageMappings, templateFami
 
   const variantSignals = collectVariantSignals(spec, sourceAssetCrawl);
   const paymentMethods = collectSpecPaymentMethods(spec);
-  const hasExitPop = activePages?.some((page) => page?.type === "checkout" && page?.exit_intent?.enabled === true) === true;
+  const hasExitPop = activePages?.some((page) => isCheckoutFlowPage(page) && page?.exit_intent?.enabled === true) === true;
   const hasOrderBump = hasOrderBumpSignals(spec);
   // With no CampaignSpec surface to fill them, the template's promo
   // placeholders are removed: "none" for both.
@@ -718,8 +719,15 @@ function addQuestion(questions, id, { detail = null, options = [] } = {}) {
   });
 }
 
+// select, checkout_step and checkout all render the SDK checkout surface, so
+// payment-page features (exit pop, promo input) and the conversion goal apply
+// to each of them (campaigns-os#641).
+function isCheckoutFlowPage(page) {
+  return CHECKOUT_FLOW_PAGE_TYPES.includes(page?.type);
+}
+
 function inferConversionGoal(activePages = []) {
-  const hasCheckout = activePages.some((page) => page?.type === "checkout");
+  const hasCheckout = activePages.some((page) => isCheckoutFlowPage(page));
   const hasUpsell = activePages.some((page) => /upsell|downsell/i.test(String(page?.type || "")));
   if (hasCheckout && hasUpsell) return "direct response funnel with post-purchase offers";
   if (hasCheckout) return "single-product direct response funnel";
@@ -837,9 +845,10 @@ function templatePromoSurfaces({ spec = null, activePages = [] } = {}) {
     surfaces.push("promo codes (funnels[].promo_codes)");
   }
   const pages = Array.isArray(activePages) ? activePages : [];
-  // Checkout-only and enabled: true, the rule hasExitPop, doctor's exit-pop
-  // contract and QA's coupon orders use for these surfaces.
-  const checkoutSurface = (page, key) => page?.type === "checkout" && page?.[key]?.enabled === true;
+  // Checkout-flow pages only (select, checkout_step, checkout) and enabled:
+  // true, the rule hasExitPop, doctor's exit-pop contract and QA's coupon
+  // orders use for these surfaces.
+  const checkoutSurface = (page, key) => isCheckoutFlowPage(page) && page?.[key]?.enabled === true;
   if (pages.some((page) => checkoutSurface(page, "exit_intent"))) {
     surfaces.push("an exit-intent offer (exit_intent)");
   }

package/src/built-site-scope.mjs

@@ -355,3 +355,94 @@ export function computeBuildFingerprint(outputDir, { exclude = [] } = {}) {
     error: null,
   };
 }
+
+// The manifest as `{ path, sha256 }` entries, the shape `record build` keeps
+// on stages.assembly.build_manifest beside build_fingerprint so a later
+// mismatch can name the files that differ instead of only two hashes.
+export function buildManifestEntries(fingerprint) {
+  const lines = String(fingerprint?.manifest || "").split("\n");
+  const entries = [];
+  for (let index = 0; index + 1 < lines.length; index += 2) {
+    if (lines[index]) entries.push({ path: lines[index], sha256: lines[index + 1] });
+  }
+  return entries;
+}
+
+const SHA256_HEX = /^[a-f0-9]{64}$/;
+
+// The recorded manifest, only when it is evidence about the recorded build:
+// well-formed entries whose canonical manifest hashes to the recorded
+// fingerprint. A record made before build kept a manifest, or one rewritten
+// by hand, reads as unavailable (null) rather than as a misleading diff.
+export function recordedBuildManifest(assembly) {
+  const entries = assembly?.build_manifest;
+  const recorded = assembly?.build_fingerprint;
+  if (!Array.isArray(entries) || typeof recorded !== "string") return null;
+  if (!entries.every((entry) => typeof entry?.path === "string" && entry.path && typeof entry?.sha256 === "string" && SHA256_HEX.test(entry.sha256))) return null;
+  const manifest = entries.map((entry) => `${entry.path}\n${entry.sha256}\n`).join("");
+  return `sha256:${sha256Hex(Buffer.from(manifest, "utf8"))}` === recorded ? entries : null;
+}
+
+// macOS and iCloud name a sync conflict copy `<name> 2.<ext>` (then ` 3`,
+// ...), on files and on folders. A trailing " N" alone is too common in real
+// names ("chapter 12.md"), so a path counts as a copy only when the same path
+// without the suffix also exists. The flag is a hint, never a verdict.
+const CONFLICT_COPY_SEGMENT = /^(.+) (?:[2-9]|[1-9]\d+)(\.[^.]+)?$/;
+export function isSyncConflictCopyPath(path, knownPaths) {
+  const segments = String(path).split("/");
+  const known = [...knownPaths];
+  return segments.some((segment, index) => {
+    const match = CONFLICT_COPY_SEGMENT.exec(segment);
+    if (!match) return false;
+    const original = [...segments.slice(0, index), `${match[1]}${match[2] ?? ""}`].join("/");
+    return index === segments.length - 1
+      ? known.includes(original)
+      : known.some((candidate) => candidate.startsWith(`${original}/`));
+  });
+}
+
+export const BUILD_DRIFT_PATH_LIMIT = 20;
+
+/**
+ * Compare the output on disk (a computeBuildFingerprint result) with the
+ * manifest stages.assembly recorded. Returns
+ *   { manifest: "recorded", extra, missing, changed, conflict_copies, summary }
+ * with sorted path lists, or { manifest: "unavailable", summary } when the
+ * record carries no usable manifest. `summary` is one sentence for a
+ * refusal: each list capped at BUILD_DRIFT_PATH_LIMIT with "+N more".
+ */
+export function describeBuildOutputDrift(assembly, current) {
+  const recorded = recordedBuildManifest(assembly);
+  if (!recorded) {
+    return {
+      manifest: "unavailable",
+      summary: "The build record carries no file manifest (it was recorded before record build kept one), so the differing paths cannot be named; re-run record build to record one.",
+    };
+  }
+  const before = new Map(recorded.map((entry) => [entry.path, entry.sha256]));
+  const now = new Map(buildManifestEntries(current).map((entry) => [entry.path, entry.sha256]));
+  const extra = [...now.keys()].filter((path) => !before.has(path));
+  const missing = [...before.keys()].filter((path) => !now.has(path));
+  const changed = [...now.keys()].filter((path) => before.has(path) && before.get(path) !== now.get(path));
+  const knownPaths = new Set([...before.keys(), ...now.keys()]);
+  const isCopy = (path) => isSyncConflictCopyPath(path, knownPaths);
+  const conflictCopies = extra.filter(isCopy);
+  const list = (label, paths) => {
+    if (paths.length === 0) return null;
+    const shown = paths.slice(0, BUILD_DRIFT_PATH_LIMIT).map((path) => (isCopy(path) ? `${path} [sync conflict copy]` : path));
+    const more = paths.length > BUILD_DRIFT_PATH_LIMIT ? ` (+${paths.length - BUILD_DRIFT_PATH_LIMIT} more)` : "";
+    return `${paths.length} ${label}: ${shown.join(", ")}${more}`;
+  };
+  const parts = [list("extra", extra), list("missing", missing), list("changed", changed)].filter(Boolean);
+  const hint = conflictCopies.length
+    ? ` ${conflictCopies.length} extra file name(s) look like macOS/iCloud sync conflict copies ("<name> 2.<ext>" beside "<name>.<ext>"); if they are, remove them (or move the repo out of the synced folder) and rebuild.`
+    : "";
+  return {
+    manifest: "recorded",
+    extra,
+    missing,
+    changed,
+    conflict_copies: conflictCopies,
+    summary: `Against the manifest build recorded: ${parts.length ? parts.join("; ") : "no path differs"}.${hint}`,
+  };
+}

package/src/cli-helpers.mjs

@@ -79,6 +79,134 @@ function isLocalAbsolutePath(value) {
   return isNonEmptyString(value) && !isAbsoluteHttpUrl(value) && isAbsolute(value);
 }
 
+// Commit-ready JSON has a finite set of filesystem fields. Route roots and URL
+// paths are deliberately absent: a leading slash does not make one a file.
+function portableArtifactPath(targetRepo, path, { baseDir = targetRepo } = {}) {
+  const rel = relative(resolve(baseDir), resolve(path));
+  return !rel ? "." : rel.startsWith(".") ? rel : `./${rel}`;
+}
+
+const ARTIFACT_PATH_FIELDS = Object.freeze({
+  "campaign-runtime-build-packet/v0": [
+    "spec.local_path", "design_source_package.path", "source_html.root",
+    "source_html.pages.*.path", "source_html.pages.*.page_kit.target_path",
+    "source_html.pages.*.page_kit.output_path", "build_brief.input_path",
+    "build_brief.normalized_path", "assembly.target_repo", "assembly.output_dir",
+    "assembly.commerce_catalog.path",
+  ],
+  "campaign-runtime-build-context/v0": [
+    "packet_path", "report_path", "intake.spec_path", "intake.source_root",
+    "intake.target_repo", "intake.brief_path", "intake.design_manifest_path",
+    "intake.packet_path", "design_source_package.path", "spec.path", "source.root",
+    "build_brief.input_path", "build_brief.normalized_path",
+    "page_map.*.source_path", "page_map.*.output_path",
+    "page_map.*.page_kit.target_path", "page_map.*.page_kit.output_path",
+    "scaffold.target_repo", "scaffold.output_dir", "scaffold.handoff_artifact",
+    "theme.source_files.*.path", "theme.generated.css_path", "theme.generated.report_path",
+  ],
+  "campaign-runtime-assembly-report/v0": [
+    "inputs.packet_path", "inputs.context_path", "inputs.build_brief_path",
+    "inputs.spec_path", "inputs.source.root", "inputs.target_repo",
+    "design_source_package.path", "build_brief.input_path", "build_brief.normalized_path",
+    // `**` also reaches each stage's archived entries.
+    "theme.css_path", "stages.**.inputs.*", "stages.**.outputs.*",
+  ],
+  "campaigns-os-doctor-output/v0": [
+    "packet_path", "assembly_report_path", "spec_path", "emitted_packet_path",
+    "derived.packet_path", "derived.assembly_report_path", "derived.spec_path",
+    "derived.target_repo", "derived.source_root", "derived.output_dir", "derived.target_output_dir",
+    "errors.*.detail.spec_path", "errors.*.detail.input_path",
+    "warnings.*.detail.spec_path", "warnings.*.detail.input_path",
+  ],
+  "campaigns-os-build-brief/v1": ["_meta.input_path"],
+});
+
+const ARTIFACT_COMMAND_FIELDS = Object.freeze({
+  "campaign-runtime-build-packet/v0": ["source_html.pages.*.skip_reason"],
+  "campaign-runtime-build-context/v0": [
+    "decisions.*.decision", "decisions.*.evidence.*",
+    "prompts_required.*.message", "page_map.*.skip_reason", "source.manifest_warnings.*",
+  ],
+  "campaign-runtime-assembly-report/v0": [
+    "next.command", "stages.**.commands.*",
+    "decisions.*.decision", "decisions.*.evidence.*",
+    "**.message", "**.blockers.*", "**.warnings.*",
+  ],
+  "campaigns-os-doctor-output/v0": [
+    "next.command", "next.actions.*", "next_actions.*.command", "**.message", "**.blockers.*", "**.warnings.*",
+  ],
+});
+
+function fieldMatches(pattern, segments) {
+  const parts = pattern.split(".");
+  function matches(at, index) {
+    if (at === parts.length) return index === segments.length;
+    if (parts[at] === "**") return matches(at + 1, index) || (index < segments.length && matches(at, index + 1));
+    return index < segments.length && (parts[at] === "*" || parts[at] === segments[index]) && matches(at + 1, index + 1);
+  }
+  return matches(0, 0);
+}
+
+function portableArtifactPaths(value, targetRepo, { artifactPath = null } = {}) {
+  const schema = isObject(value) ? value.schema_version : null;
+  const pathFields = ARTIFACT_PATH_FIELDS[schema] || [];
+  const commandFields = ARTIFACT_COMMAND_FIELDS[schema] || [];
+  const artifactDir = artifactPath ? dirname(resolve(artifactPath)) : null;
+  const packet = schema === "campaign-runtime-build-packet/v0";
+  const context = schema === "campaign-runtime-build-context/v0";
+  const report = schema === "campaign-runtime-assembly-report/v0";
+  const sourceField = packet ? value.source_html?.root : context ? value.source?.root : report ? value.inputs?.source?.root : null;
+  const sourceBase = packet ? artifactDir : targetRepo;
+  const sourceRoot = isNonEmptyString(sourceField) && sourceBase ? resolve(sourceBase, sourceField) : null;
+  const outputField = packet ? value.assembly?.output_dir : context ? value.scaffold?.output_dir : null;
+  const outputBase = targetRepo;
+  const outputDir = isNonEmptyString(outputField) && outputBase ? resolve(outputBase, outputField) : null;
+  const roots = [...new Set([targetRepo, sourceRoot].filter(Boolean).flatMap((root) => [resolve(root), canonicalPath(root)]))]
+    .filter((root) => root !== "/")
+    .sort((left, right) => right.length - left.length);
+  function fieldBase(segments) {
+    const path = segments.join(".");
+    if (packet) {
+      if (path === "source_html.pages.*.path") return sourceRoot;
+      if (path === "source_html.pages.*.page_kit.target_path") return outputDir;
+      if (path === "source_html.pages.*.page_kit.output_path") return targetRepo;
+      if (path === "assembly.output_dir") return targetRepo;
+      return artifactDir;
+    }
+    if (context) {
+      if (path === "page_map.*.source_path") return sourceRoot;
+      if (path === "page_map.*.page_kit.target_path") return outputDir;
+      if (path === "design_source_package.path") return artifactDir;
+    }
+    if (report && path === "design_source_package.path") return artifactDir;
+    if (schema === "campaigns-os-build-brief/v1") return artifactDir;
+    return targetRepo;
+  }
+  function portableCommand(command) {
+    let output = command;
+    for (const root of roots) {
+      const escaped = root.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const replacement = portableArtifactPath(targetRepo, root);
+      output = output.replace(new RegExp(`(^|[\\s"'\`(=,;\\[<])${escaped}(?=$|[/\\s"'\`.,:;)\\]>])`, "g"),
+        (_match, prefix) => `${prefix}${replacement}`);
+    }
+    return output;
+  }
+  function visit(entry, segments = []) {
+    if (Array.isArray(entry)) return entry.map((item) => visit(item, [...segments, "*"]));
+    if (isObject(entry)) return Object.fromEntries(Object.entries(entry).map(([field, item]) => [field, visit(item, [...segments, field])]));
+    if (typeof entry !== "string") return entry;
+    if (Array.isArray(value) && segments.length === 1 && isLocalAbsolutePath(entry)) return portableArtifactPath(targetRepo, entry);
+    if (pathFields.some((pattern) => fieldMatches(pattern, segments)) && isLocalAbsolutePath(entry)) {
+      const baseDir = fieldBase(segments);
+      return baseDir ? portableArtifactPath(targetRepo, entry, { baseDir }) : entry;
+    }
+    if (commandFields.some((pattern) => fieldMatches(pattern, segments))) return portableCommand(entry);
+    return entry;
+  }
+  return visit(value);
+}
+
 function resolveFromFile(filePath, targetPath) {
   if (!isNonEmptyString(targetPath)) return null;
   if (isAbsoluteHttpUrl(targetPath)) return targetPath;
@@ -111,6 +239,7 @@ export {
   sha256File,
   relFromDir,
   isLocalAbsolutePath,
+  portableArtifactPaths,
   resolveFromFile,
   filesystemPathsMatch,
   extractFrontmatterValue,