@nextcommerce/campaigns-os 1.57.0 → 1.60.0

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

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-os-setup
-version: 2.0.38
+version: 2.0.44
 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.57.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.57.0+skills.1`
+Bundle revision: 1.60.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.60.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.40
+version: 1.1.46
 description: Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign.
 ---
 
-Bundle revision: 1.57.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.57.0+skills.1`
+Bundle revision: 1.60.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.60.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
@@ -87,13 +87,12 @@ Responsibilities:
   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.
+  `campaigns-os qa policy set --packet <packet> --preview-url <url>` first.
+  Then follow `campaigns-os next --packet <packet>`: it hands off
+  `campaigns-os record deploy --packet <packet> --base-url
+  <preview route root>`, then `campaigns-os qa run --packet <packet>
+  --base-url <preview-url> --browser --test-order common`, then 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.39
+version: 1.3.45
 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.57.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.57.0+skills.1`
+Bundle revision: 1.60.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.60.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-sdk-bump/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: next-campaigns-sdk-bump
+version: 1.0.1
+description: Bump a live campaign's Campaign Cart SDK from one 0.4.x release to a later 0.4.x on a page-kit or static repo. Use for any request to bump, upgrade or move a campaign to SDK 0.4.x, including when the repository has its own BUMP.md. Find every pin, check the release diff and storage against the campaign's own code, prove on a preview with approved test orders, and report what is not proven.
+---
+
+Bundle revision: 1.60.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.60.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
+while the CLI on disk can move under it. If the output has no `Skills revision:`
+line (no `revision_check` under `--json`), a campaigns-os older than this check
+answered; follow none of its actions and run the pinned copy.
+
+# Next Campaigns SDK Bump
+
+Use this when someone says "bump this campaign to SDK 0.4.x". The developer
+installs the toolkit, asks for the bump, approves each push, the pull request
+and each test order, then reviews and merges. Everything here uses existing
+commands; there is no new write or order capability.
+
+If `tooling status` prints `Refresh installed skills` for `--platform codex` or
+`--platform agents` only, that refresh is for those harnesses; it is not
+required in a session that uses neither.
+
+In the instructions below, bare `campaigns-os …` means `npx --no-install
+campaigns-os …` from the campaign folder. The effect class in each
+parenthetical is the declared row of `contracts/effects.v1.json`.
+
+## Scope: a current-SDK bump only
+
+A bump moves a funnel from one Campaign Cart 0.4.x release to a later 0.4.x.
+Before anything else, confirm every page in scope loads a 0.4.x loader. Stop
+and say so if you find a 0.3.x pin or a legacy page: one whose own code calls
+the Campaigns JS or the Campaigns API directly for cart and checkout. Moving
+those changes bundle selection, cart calculation and more, and is migration
+work, not a bump.
+
+Judge a legacy page by what drives its cart and checkout, not by a script URL.
+The 0.4.x SDK loads the Campaigns analytics script (`/js/v1/campaign/`) itself
+for analytics, and some layouts also load it by hand; on a page the 0.4.x SDK
+drives, that script alone is not a reason to stop.
+
+A bump does not adopt new SDK components. Hand-written address or phone fields
+stay hand-written; adopting `data-next-address` or another new component is
+separate work.
+
+## Approval gates
+
+Ask before every push, before opening the pull request, and before test
+orders. Test orders are real orders in the store that someone may have to
+cancel; follow the `next-campaigns-qa` rule: ask once up front, then follow the
+answer. Never write evidence or notes into the served tree: many static repos
+publish from the repository root. The hand-back goes on the ticket or the pull
+request.
+
+`qa run` against a preview that is not a local address posts its verdict to the
+QA portal on campaign-map.nextcommerce.com and prints the link. Say so when you
+ask about test orders, and pass `--local-only` unless the developer wants the
+verdict there. `qa run` writes its local verdict under `qa-output/` in the
+current folder (or `--output-dir <path>`). Keep `qa-output/` out of commits:
+check `.gitignore`, and never stage it.
+
+## 1. Branch
+
+Branch from an up-to-date `main`. List open pull requests that touch the
+campaign folder and ask the developer about merge order before branching.
+
+## 2. Find every pin
+
+**Page-kit repo** (`_data/campaigns.json` exists):
+
+- `sdk_version` on each slug's entry in `_data/campaigns.json`.
+- Pages that type the version into their own loader. Search with
+  `grep -rn "campaign-cart@v" src`. Switch each one to
+  `campaign-cart@v{{ campaign.sdk_version }}` so the data file is the only pin.
+  A data-file-only bump leaves those pages on the old SDK. The starter
+  templates render with Liquid and expose the entry as `campaign`; on a page
+  that does not, keep a literal version instead and say so. Step 5 checks the
+  built pages for an unrendered `{{`.
+- With a Build Packet, `campaigns-os page-kit sync --packet <packet>` (tier `B`)
+  writes the CampaignSpec's pin into the entry; without one, edit the entry.
+
+**Static repo** (no `_data/campaigns.json` anywhere in the repository, root
+included):
+
+- Preview with `campaigns-os sdk repin --target <funnel folder> --target-sdk <x.y.z>`
+  (tier `none` without `--apply`). It lists every loader and CSS pin with path
+  and line.
+- Scope it to the funnel folder, not the repository root. Repin rewrites every
+  semver pin below `--target`, so in a repository where funnels sit side by
+  side, a root-level `--apply` moves pages outside the bump. Check every listed
+  file belongs to the funnel, then run the same command with `--apply` (tier
+  `B`). It writes `.campaign-runtime/sdk-repin.json` under the target; that file
+  is served if the publish root includes it, so say so or keep it out of the
+  deploy.
+- `sdk repin` refuses a target with `_data/campaigns.json` at or below it,
+  but it does not look above `--target`. A funnel folder inside a page-kit
+  repository is not refused, so never point `sdk repin` at one; use the
+  page-kit steps above.
+
+## 3. Read the release diff against the campaign
+
+Read the release notes and the source diff between the two Campaign Cart tags.
+For each change, search the campaign's own JavaScript, includes and markup, and
+report file and line where the campaign depends on the changed behaviour. In
+particular:
+
+- Trace where the funnel's purchase event comes from before the bump. Static
+  funnels often hand-wire `order:completed` listeners and their own `dataLayer`
+  pushes; check that event's page and timing against the release you are
+  moving to.
+- If a page shows a discount before the SDK confirms a coupon, check that the
+  coupon exists on every campaign the funnel uses.
+- Note whether the range changes the card fields or the 3-D Secure flow; if it
+  does, plan a 3-D Secure test order in step 6.
+- When the range removes a feature the campaign uses, say so, and do not just
+  delete the call: that silently drops the feature from a live funnel. Look for
+  a documented replacement in the repository's own docs (`CLAUDE.md`,
+  `BUMP.md`) and the release notes. If none is documented, stop and ask.
+- Classify every `next:initialized` listener. From 0.4.42 the SDK fires that
+  event once and does not replay it, so a deferred script that only listens for
+  it can miss it on a cached reload. Guard each one in the bump: run now if
+  `window.next` exists and `document.body.dataset.nextSdkLoading === "false"`,
+  otherwise wait for the event, and run once either way. Step 6 proves it.
+
+## 4. Storage check
+
+Run `campaigns-os sdk storage-check --target <git-root> --target-sdk <x.y.z> --manifest <storage-migrations.v1.json> --scope <funnel folder,shared js>`
+(tier `none`). Take the manifest from an unmodified checkout of the target
+Campaign Cart tag (`docs/compatibility/storage-migrations.v1.json`, v0.4.40 or
+later), at the highest version its supported range declares. Read each
+`incompatible` and `unknown` line and say whose key it is. See
+`docs/sdk-storage-compatibility.md`.
+
+The manifest's `supportedSdkVersions` can stop below the tag it ships in: tags
+v0.4.39 to v0.4.42 declare 0.4.38 to 0.4.38, so `--target-sdk 0.4.42` returns
+`target-outside-manifest-range`. Run the check at the manifest's highest
+version and report that it does not speak for the versions above it.
+
+## 5. Build and check
+
+**Page-kit:** run a development build, confirm every built page loads only the
+target version and that no built loader URL still holds an unrendered `{{`,
+then `campaigns-os doctor --built <repo> --family <family> --slug <slug>`
+(tier `none`) for a repository with no Build Packet, or `campaigns-os doctor --packet <packet>`
+with one. Errors that are already on `main` are recorded, not fixed. Report doctor's
+advisories with the rest; an attribute flagged as missing from the SDK's index
+that the page does set (for example `data-next-page-type` on `<body>`) goes in
+the hand-back as unchecked, not fixed by guesswork.
+
+**Static:** there is no build and no doctor. Re-run the repin preview (it
+should list nothing below the target) and search the served pages for any
+remaining old version.
+
+## 6. Preview proof
+
+Deploy a preview and prove the bump with browser test orders under the
+approval rule above. `qa run --browser` needs the browser once per machine:
+`campaigns-os qa install-browser` downloads about 100 MB, so ask before running
+it. Pin the browser to the store's main market: a run
+geolocated elsewhere can order in another currency and skip a currency-gated
+upsell.
+
+- With a Build Packet: `campaigns-os qa run --packet <packet> --base-url <preview-url> --browser --test-order common`
+  (tier `C`; see `next-campaigns-qa`).
+- A built page-kit repo with no packet: `campaigns-os qa run --site <repo> --base-url <preview-url> --family <family> --browser`
+  (tier `C`) checks the served pages. Place the approved test orders in the
+  browser and record each order number.
+- A static repo: place the approved test orders in the browser on the preview
+  and record each order number.
+
+Cover:
+
+- one card order per live checkout;
+- PayPal cancelled, then a card order, where PayPal is offered;
+- an upsell at quantity 2 or more on a page that shows a quantity picker;
+- a 3-D Secure card when step 3 found card-field or 3-D Secure changes, and whether it challenged;
+- the coupon path, if the funnel has one;
+- the purchase event fires once, on the page the release says it should;
+- each SDK page on a fresh load and on a cached reload, with every
+  `next:initialized` listener from step 3 running once on both.
+
+Read each order back in the store admin (the packet run's verdict under
+`qa-output/` also lists the orders it created) and keep the order numbers for
+the hand-back.
+
+## 7. Hand back
+
+On the ticket or the pull request, not in the repository: what changed (pins,
+loader rewrites), the storage-check and doctor results, a table of test orders,
+what is not proven, and which orders to cancel.

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.57.0+skills.1",
+  "bundle_revision": "1.60.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.55",
+      "version": "1.0.61",
       "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.38",
+      "version": "2.0.44",
       "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.40",
+      "version": "1.0.46",
       "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.40",
+      "version": "1.1.46",
       "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.39",
+      "version": "1.3.45",
       "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.35",
+      "version": "1.0.41",
       "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.35",
+      "version": "1.0.41",
       "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.35",
+      "version": "1.0.41",
       "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,10 +80,18 @@
     {
       "id": "contribution-intake",
       "name": "Contribution Intake",
-      "version": "1.0.35",
+      "version": "1.0.41",
       "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."
+    },
+    {
+      "id": "next-campaigns-sdk-bump",
+      "name": "Campaign SDK Bump",
+      "version": "1.0.1",
+      "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/built-site-scope.mjs

@@ -290,9 +290,8 @@ export function synthesizeMinimalBuildPacket({
 // the same build. The manifest is `<path>\n<sha256>\n` per file, paths
 // relative to the output root with `/` separators and sorted by code point,
 // so directory walk order and the absolute location never leak into the
-// value. Page Kit (0.2.0) writes only rendered HTML and copied assets into
-// _site/, nothing it timestamps, so nothing is excluded by default; `exclude`
-// takes root-relative paths for a consumer whose build does stamp a file.
+// value. Page Kit (0.2.x and 0.3.x) writes only rendered HTML and copied
+// assets into _site/, nothing it timestamps, so every file is hashed.
 // Symbolic links are never build output and are skipped, not followed.
 export const BUILD_FINGERPRINT_ALGORITHM = "sha256-manifest/v1";
 
@@ -326,22 +325,17 @@ function sha256Hex(buffer) {
  * hand (`sha256sum` over each file, sort by path, hash the lines). `ok: false`
  * with `error` when the root is not a directory; an empty tree still hashes
  * (the empty manifest) so a wiped _site/ reads as a changed build, not a
- * missing one.
+ * missing one. `excluded` is always empty; doctor's build_output_fingerprint
+ * still reports it.
  */
-export function computeBuildFingerprint(outputDir, { exclude = [] } = {}) {
+export function computeBuildFingerprint(outputDir) {
   const root = String(outputDir || "");
   const base = { ok: false, algorithm: BUILD_FINGERPRINT_ALGORITHM, root, fingerprint: null, file_count: 0, excluded: [], manifest: null };
   if (!root || !existsSync(root) || !statSync(root).isDirectory()) {
     return { ...base, error: `Build output directory does not exist: ${root || "(empty)"}` };
   }
-  const excludeSet = new Set((Array.isArray(exclude) ? exclude : []).map((path) => String(path).split(sep).join("/")));
-  const excluded = [];
   const lines = [];
   for (const path of listFilesRelative(root)) {
-    if (excludeSet.has(path)) {
-      excluded.push(path);
-      continue;
-    }
     lines.push(`${path}\n${sha256Hex(readFileSync(join(root, path)))}\n`);
   }
   const manifest = lines.join("");
@@ -350,8 +344,98 @@ export function computeBuildFingerprint(outputDir, { exclude = [] } = {}) {
     ok: true,
     fingerprint: `sha256:${sha256Hex(Buffer.from(manifest, "utf8"))}`,
     file_count: lines.length,
-    excluded,
     manifest,
     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/campaign-identity.mjs

@@ -263,9 +263,11 @@ function gateBase(subject) {
  * A page marked `spec_page: false` is built output that no CampaignSpec page
  * builds to. It is still scanned, because it is still served, but a finding
  * that names it says so: such a file is usually left in `_site/` by an earlier
- * build, or built from an HTML file copied into the source (a design export's
- * `index.html` under `assets/`), and the repair is to remove it, not to retag
- * it.
+ * build, or built from an HTML file copied into the source, and the repair is
+ * to remove it, not to retag it. Both are page-kit 0.2.x behaviour (no
+ * `_site/` pruning; a design export's `index.html` under `assets/` builds as
+ * a page). 0.3.0 cleans `_site/<slug>/` and ignores `.html` under `assets/`,
+ * so there a stray is a source page no spec page claims.
  *
  * @param {{ subject: object, pages: Array<{ page_id: string, route?: string|null,
  *   file?: string|null, content: string, spec_page?: boolean,
@@ -415,7 +417,7 @@ export function evaluateCampaignIdentity({ subject, pages = [], expectedApiKey =
     // own instruction (retag, or add a missing tag to a real page) is dropped:
     // that edit would land on the wrong file.
     const named = stray.length > 2 ? `${stray.slice(0, -1).join(", ")}, and ${stray.at(-1)}` : stray.join(" and ");
-    finding.message = `${named} ${stray.length === 1 ? "is" : "are"} not the built page of any CampaignSpec page: built output left by an earlier build, or an HTML file copied into the source (a design export's index.html under assets/ builds as its own page). Remove the source file if there is one, delete the built file, then rebuild and record the build again; do not retag either page. What it causes: ${finding.evidence}`;
+    finding.message = `${named} ${stray.length === 1 ? "is" : "are"} not the built page of any CampaignSpec page: built output left by an earlier build, or an HTML file copied into the source (on page-kit 0.2.x a design export's index.html under assets/ builds as its own page). Remove the source file if there is one, delete the built file, then rebuild and record the build again; do not retag either page. What it causes: ${finding.evidence}`;
   }
 
   // evidence is the message's first sentence, kept apart only so a stray