@nextcommerce/campaigns-os 1.60.0 → 1.62.0

package/docs/readback.md

@@ -8,7 +8,9 @@ most once, plus two fixed Git metadata files (the nearest `.git` entry at the
 target or an ancestor, and that Git directory's `logs/HEAD` reflog) for the
 freshness comparison, and the CampaignSpec and normalized Campaign Build Brief
 the Build Packet names, whose current content decides each stage's effective
-status.
+status. It also reads and hashes regular files in the packet's built output
+at `_site/<public_route_slug>/` to assess build-bound evidence debt. Symlinks
+are skipped by the build fingerprint machinery.
 
 The safety contract is the point of the command. The readback **writes nothing**
 under the target — not even a lifecycle journal entry, which every other command
@@ -21,7 +23,7 @@ For the same reason the readback resolves **no run session** and sweeps no stale
 one. Its `--packet` names the Build Packet to *project*, not a Build Packet to
 act on, so an active run session — here, at the target, or bound to some other
 packet entirely — never changes what this command reads or what it exits with.
-That also keeps every read bounded: the only reader of a `--packet` file is the
+The only reader of a `--packet` file is the
 readback's own 32 MiB-bounded one, which refuses an oversized packet as an
 `unreadable` artifact row rather than loading it.
 
@@ -41,8 +43,8 @@ campaigns-os readback --example [--json]
 The default output is the rendered human view. `--json` emits the same
 projection as one `campaigns-os-readback/v2` object on stdout so a caller can
 gate on it; `schemas/campaigns-os-readback.v2.schema.json` is that object's
-shape, and this document is its prose twin. The two modes share one computation
-path: the JSON serializes what the text view already computes and adds no
+shape, including the additive `evidence_debt` field. The two modes share one
+computation path: the JSON serializes what the text view already computes and adds no
 interpretation the text view does not also carry.
 
 ## Exit codes
@@ -118,6 +120,15 @@ STAGES  [assembly report; report status: prepared; effective: prepared]
   deploy         pending
   qa             pending
 
+EVIDENCE DEBT  [the readback's own projection layer: recorded build bindings versus built output]
+  polish: unknown — evidence currency is unknown (build_output_missing); absence of proof is not no debt
+    recorded: unknown; current: unknown
+  qa: unknown — evidence currency is unknown (build_output_missing); absence of proof is not no debt
+    recorded: unknown; current: unknown
+  changes against assembly manifest: unknown (build_output_missing)
+    recorded: unknown; current: unknown
+  Page changes use the assembly baseline; older stage manifests are not reconstructed.
+
 BUILD CONTEXT  [build context; source adapter: html_funnel, status: prepared]
 
 DOCTOR  [doctor output; status: ready_with_warnings]
@@ -182,6 +193,23 @@ STAGES  [assembly report; report status: completed; effective: prepared]
   },
   "skip_cascades": [{ "blocked_by": "polish.evidence_incomplete", "families": ["meta-tags"] }],
   "divergences": [{ "stage": "polish", "assertion_ids": ["polish.evidence_incomplete"] }],
+  "evidence_debt": {
+    "polish": {
+      "status": "unknown", "matches_current_build": null,
+      "recorded_build_fingerprint": null, "current_build_fingerprint": null,
+      "reason": "build_output_missing"
+    },
+    "qa": {
+      "status": "unknown", "matches_current_build": null,
+      "recorded_build_fingerprint": null, "current_build_fingerprint": null,
+      "reason": "build_output_missing"
+    },
+    "changes": {
+      "status": "unknown", "reason": "build_output_missing",
+      "recorded_build_fingerprint": null, "current_build_fingerprint": null,
+      "changed_pages": [], "unmapped_files": [], "extra": [], "missing": [], "changed": []
+    }
+  },
   "clean": false
 }
 ```
@@ -267,6 +295,20 @@ carries no parseable value — the readback does not choose. It names the
 candidates on stderr, says `--packet` is required, and exits `2`. No JSON object
 is emitted in that case.
 
+**Freshness chooses among runs of one funnel, never among funnels.** A project
+that holds several funnels has one packet per funnel
+(`campaign-runtime-<route>.build.json` beside the default; see
+[Several funnels in one project](build-packet.md#several-funnels-in-one-project)).
+When the valid candidates name more than one `campaign.public_route_slug`, the
+readback refuses the same way, naming each packet with its route, and exits
+`2`. Pass `--packet` to project one funnel. The doctor output, Build Context,
+Assembly Report, QA verdict and findings export rows then read from the runtime
+directory that packet records (`assembly.runtime_dir`), or from
+`.campaign-runtime/` when it records none. A packet whose `assembly.runtime_dir`
+is not its own funnel's directory is refused with exit `2`, since the readback
+cannot tell whose records to show. An explicit `--doctor`, `--context`,
+`--report`, `--qa-verdict` or `--findings` path still wins.
+
 Values are compared at **microsecond precision** — the precision Python's
 `datetime.fromisoformat` keeps, and the precision the Python readback this
 command ports compared at; a seventh or later fractional digit is truncated, not
@@ -397,6 +439,106 @@ in first-seen order:
 Empty when no QA verdict loaded or none of its assertions were skipped. This
 grouping is the readback's own projection layer.
 
+### `evidence_debt`
+
+An additive top-level object in `campaigns-os-readback/v2`, emitted in JSON and
+as an **EVIDENCE DEBT** text section. This assessment reads built bytes; it uses
+no timestamps or reflog entries, starts no process, and writes nothing. It
+does not rerun doctor, Polish, or QA and does not reinterpret their verdicts.
+
+`polish` and `qa` each carry:
+
+- `status`: the closed set `current`, `owed`, `unknown`;
+- `matches_current_build`: fingerprint equality only (`true` or `false`), or `null`
+  when either fingerprint is absent;
+- `recorded_build_fingerprint`: the stage's build binding, or `null`;
+- `current_build_fingerprint`: the fingerprint computed from current built
+  output with `computeBuildFingerprint`, or `null`;
+- `reason`: `null` for `current`; `build_fingerprint_changed`,
+  `stage_required_by_build`, `stage_required_by_brief`,
+  `stage_required_by_spec`, or `stage_required` for `owed`; or an explicit
+  reason for `unknown`.
+
+Polish uses `stages.polish.source_build_fingerprint`, falling back to
+`stages.polish.evidence.source_build_fingerprint`, with the same precedence as
+the Polish gate. QA uses `stages.qa.evidence.qc_build_fingerprint`, falling back
+to `source_build_fingerprint`, and the same build-binding comparison as `next`.
+It does not require uncommitted capture files to be present.
+
+`current` means the stage's binding equals the bytes on disk and the assembly
+fingerprint is available and the stage is not recorded as `required`. `owed`
+means that binding differs from the current build, or the lifecycle recorded
+the stage as `required`, even without a stage fingerprint. Its `required_by`
+selects `stage_required_by_build`, `stage_required_by_brief`, or
+`stage_required_by_spec`; an absent or unrecognized source gives
+`stage_required`. Both comparisons work without a manifest, including reports recorded
+before manifests existed. **`unknown` never means no debt.** Missing or unreadable
+built output or a missing assembly fingerprint still makes the affected stage
+explicitly `unknown`; a missing stage fingerprint does too unless the stage is
+`required`. The unknown stage reason codes are
+`packet_unavailable`, `build_output_location_unknown`, `build_output_missing`,
+`build_output_unreadable`, `assembly_build_fingerprint_missing`, and
+`stage_build_fingerprint_missing`.
+When both stage and disk fingerprints are available, `matches_current_build`
+reports their equality even if a missing assembly fingerprint makes status unknown.
+`matches_current_build: true` together with `status: owed` means the lifecycle
+requires the stage again over matching evidence. Consumers decide whether
+evidence is owed from `status`, never from `matches_current_build`.
+
+`changes` compares current output to **the retained assembly manifest**, using
+the existing file drift machinery. It carries:
+
+- `status`: `known` or `unknown`, with `reason` (`null` when known);
+- `recorded_build_fingerprint` and `current_build_fingerprint`: the assembly
+  manifest baseline and the disk fingerprint;
+- `extra`, `missing`, `changed`: complete file path lists from the manifest
+  comparison, without the human drift summary's truncation;
+- `changed_pages`: `{ "page_id": "landing", "built_path": "landing/index.html" }`
+  entries for added, removed, or modified HTML in the built-site page map;
+- `unmapped_files`: every differing path outside that map, including shared
+  CSS, scripts and assets. These changes still make build-bound evidence owed.
+
+Paths are relative to `_site/<public_route_slug>/` and sorted; page IDs use
+`resolveBuiltSiteScope`'s route-derived identities (nested routes use hyphens).
+Removed HTML uses that same route/ID projection. Empty lists with
+`changes.status: unknown` do not establish that no pages changed.
+A missing or unusable manifest makes only `changes.status` unknown, with
+`build_manifest_unavailable` as its reason. A manifest is usable only if its
+entries hash to the assembly's recorded fingerprint.
+If the built page map cannot be resolved (for example, output contains assets
+but no HTML), page changes are unknown with `build_output_pages_unresolved`;
+stage bindings still follow the fingerprint comparison.
+
+`changes.kind` classifies this drift (`none`, `page_only`,
+`commerce_affecting` or `unknown`) and `changes.reasons` lists why it counts as
+commerce, each `{ "code", "path"? }`. The rule is in
+[what a change owes](campaigns-os-build-flow.md#what-a-change-owes).
+
+The assembly baseline is explicit because it need not equal an older stage's
+binding. If a later `record build` replaced that manifest, `changes` can be
+empty while older Polish/QA bindings are still owed. An empty **known** list then means only that
+no files differ from the retained assembly manifest. The pages changed since
+the build a stage reviewed are on that stage instead. An owed stage carries:
+
+- `change`: `{ "kind", "since_build_fingerprint", "changed_pages",
+  "unmapped_files", "reasons" }`, read from the rebuilds `record build` kept in
+  `stages.assembly.build_changes` plus the drift on disk. `kind` is `unknown`
+  when that history does not reach the reviewed build (reason
+  `change_history_unavailable`) or the drift cannot be read. `null` on a stage
+  that is not owed.
+- Polish only, `advisory`: `true` when the change is `page_only` and no brief or
+  spec change requires Polish. Advisory Polish is reported; `next`, `doctor
+  --ci` and the QA gate do not require it.
+- QA only, `scope` and `owed_pages`: `pages` with the changed pages when the
+  change is `page_only` (`qa run --page` pays it), `full` otherwise, `null`
+  when QA is not owed.
+
+If recording removed a
+stage binding entirely, that stage reads unknown unless its recorded status is
+`required`, which reports owed. `current` is a build-binding
+assessment only; input currency, stage completion, waivers and verdicts remain
+separate.
+
 ### `divergences`
 
 Where two artifacts record different states for the same stage: the assembly
@@ -413,7 +555,7 @@ failure lines up with a completed stage. This too is the readback's own layer.
 
 ## `clean`
 
-`clean` is true if and only if **all five** of the following hold:
+`clean` is true if and only if **all six** of the following hold:
 
 1. **Every artifact the readback found is loaded and recognized.** Formally: no
    artifact is in state `unreadable` or `unrecognized`. An `absent` artifact
@@ -439,6 +581,12 @@ failure lines up with a completed stage. This too is the readback's own layer.
    failed to check.
 4. **`divergences` is empty.**
 5. **`doctor.error_count` is zero.**
+6. **Neither `evidence_debt.polish.status` nor `evidence_debt.qa.status` is
+   `owed`**, except Polish marked `advisory` for a page-only change. Built
+   output that moved since recorded evidence cannot read clean.
+   An `unknown` status does not independently make this integrity flag false;
+   it remains unknown, never a claim that no evidence is owed. Callers must
+   inspect `evidence_debt` even when `clean` is true.
 
 Doctor warnings — of either group — do not affect `clean`. Neither does a
 blocked QA verdict, a blocked assembly report, or a non-empty `skip_cascades`.
@@ -449,7 +597,7 @@ blocked QA verdict, a blocked assembly report, or a non-empty `skip_cascades`.
 campaign. It means: the readback read every artifact that was there, understood
 all of them, can show — for every artifact that recorded an age — that none of
 them is older than the checkout, found no contradiction between them, and saw no
-doctor error. Campaigns OS remains the
+doctor error, and found no known build-bound evidence debt. Campaigns OS remains the
 lifecycle and verdict authority; the readback never reinterprets a verdict.
 
 The practical consequence for a caller: `clean: true` says the artifacts are

package/docs/runtime-readiness.md

@@ -8,7 +8,7 @@
 
 How a checkout of this repository at one commit becomes a usable installed runtime, and how a consumer decides whether a prepared one is still trustworthy. Everything below is generated from `contracts/runtime-recipe.campaigns-os-node-v1.json`, which is the only authority for these values.
 
-Recipe kind `campaigns-os-node-v1`, revision `1.0.3`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.60.0`.
+Recipe kind `campaigns-os-node-v1`, revision `1.0.3`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.62.0`.
 
 ## What this is
 
@@ -81,8 +81,9 @@ Not redundant with the install step. Because install runs with lifecycle scripts
 
 The complete input set, enumerated explicitly rather than globbed. The compiler's configured include globs are NOT the input set: two root modules enter the compilation transitively through imports from the entry module and are emitted, so a fingerprint derived from the globs would cover 36 of the 38 compiled sources and miss one of the larger emitted surfaces. Test fixtures and the package's own tests are not inputs; nothing under them is emitted. A checker resolves the compiler's actual file list and asserts it equals this enumeration, so this list cannot rot silently.
 
-Fingerprint algorithm `sha256`, over 47 enumerated files:
+Fingerprint algorithm `sha256`, over 50 enumerated files:
 
+- `campaign-spec/analytics-vendors.ts`
 - `campaign-spec/analytics-vocabulary.ts`
 - `campaign-spec/checkout-flow.ts`
 - `campaign-spec/index.ts`
@@ -91,9 +92,11 @@ Fingerprint algorithm `sha256`, over 47 enumerated files:
 - `campaign-spec/routing.ts`
 - `campaign-spec/rules/analytics-contract-shape.ts`
 - `campaign-spec/rules/assembly-hints-shape.ts`
+- `campaign-spec/rules/campaign-currencies.ts`
 - `campaign-spec/rules/campaign-metadata.ts`
 - `campaign-spec/rules/checkout-forward-target.ts`
 - `campaign-spec/rules/checkout-has-success-url.ts`
+- `campaign-spec/rules/checkout-path-has-packages.ts`
 - `campaign-spec/rules/checkout-step-reaches-checkout.ts`
 - `campaign-spec/rules/cycle-detection.ts`
 - `campaign-spec/rules/design-source-shape.ts`
@@ -137,7 +140,7 @@ The output directory is a build product. It is untracked and git-ignored, no com
 
 Directory `campaign-spec/dist`. Committed: `false`. Type entry `campaign-spec/dist/index.d.ts`.
 
-Expected inventory is derived, never listed twice. For every enumerated input under module_source_root whose path ends in .ts, the build is expected to emit campaign-spec/dist/<path relative to module_source_root, with .ts replaced> once per entry in emitted_extensions. The expected inventory is exactly that set: nothing missing, nothing extra. Emitted extensions: `.js`, `.d.ts`. At this revision that derivation yields 86 files.
+Expected inventory is derived, never listed twice. For every enumerated input under module_source_root whose path ends in .ts, the build is expected to emit campaign-spec/dist/<path relative to module_source_root, with .ts replaced> once per entry in emitted_extensions. The expected inventory is exactly that set: nothing missing, nothing extra. Emitted extensions: `.js`, `.d.ts`. At this revision that derivation yields 92 files.
 
 ### Mandatory checks
 

package/docs/sdk-storage-compatibility.md

@@ -8,7 +8,7 @@ npx --no-install campaigns-os sdk storage-check --target . --target-sdk 0.4.38 -
 
 Omit `--json` for the concise human report. Exit 0 means source-compatible; exit 2 means incompatible or unknown; invalid arguments or manifests exit 1. No merchant files or pins are rewritten. This is independent of doctor's built HTML markup check.
 
-The manifest is generated and owned by Campaign Cart, from its storage registry. The scanner has no independent SDK key list and fetches no remote code. Supply `docs/compatibility/storage-migrations.v1.json` from an unmodified checkout of a Campaign Cart release tag, v0.4.40 or later. The report records the full file SHA-256, SDK version, supported target range, registry/extractor/input digest, and Git provenance. When the supplied bytes equal their repository HEAD blob, provenance is `verified-git-blob` with commit and repository path. Proposed, modified, or copied manifests are labeled `unverified-local-file`; the label never certifies a release. Review/pin SDK provenance separately before acting on findings. A release manifest covers the target range it declares, which may end below its own SDK version: the v0.4.40 manifest, for example, covers 0.4.38 only. Targets outside the manifest's supported SDK range report unknown. A manifest whose SDK version is below its supported maximum is invalid.
+The manifest is generated and owned by Campaign Cart, from its storage registry. The scanner has no independent SDK key list and fetches no remote code. Supply `docs/compatibility/storage-migrations.v1.json` from an unmodified checkout of a Campaign Cart release tag, v0.4.40 or later. The report records the full file SHA-256, SDK version, supported target range, registry/extractor/input digest, and Git provenance. When the supplied bytes equal their repository HEAD blob, provenance is `verified-git-blob` with commit and repository path. Proposed, modified, or copied manifests are labeled `unverified-local-file`; the label never certifies a release. Review/pin SDK provenance separately before acting on findings. A release manifest covers the target range it declares, which may end below its own SDK version: the v0.4.40 manifest, for example, covers 0.4.38 only. Targets outside the manifest's supported SDK range report unknown (exit 2), and the human report says so before anything else: its first line names the range the manifest covers and the requested target it does not, and the count line repeats it. With a v0.4.43 manifest, `--target-sdk 0.4.43` reads `checked against SDK 0.4.38, not the requested target 0.4.43`. `--json` carries `targetCovered: false`. A manifest whose SDK version is below its supported maximum is invalid.
 
 `--target` must name the Git root. `--scope` is mandatory: comma-separated literal repository-relative directory/file paths; use `.` only when the complete repository is intended. Add shared JavaScript directories explicitly. `--exclude` uses the same syntax and records explicit exclusions. Archives receive no implicit exemption. Only Git-tracked `.html`, `.htm`, `.js`, `.mjs`, and `.cjs` files in the selected scope are scanned, using current working-tree bytes and per-file digests; untracked files and built dependencies are outside this evidence. A selected HTML page's local script outside the selected files reports unknown. In a Page Kit campaign (a page under `src/<slug>/`), a script src written `{{ 'js/x.js' | campaign_asset }}` resolves to `src/<slug>/assets/js/x.js`, as Page Kit serves it, and a page's frontmatter `scripts:` entries resolve the same way, since a layout's `{% for script in scripts %}` loop loads them through that filter. Any other `campaign_asset` value, a path that resolves outside the assets folder, and frontmatter that is not valid YAML or whose `scripts` is not a list of paths report unknown. Relative scripts affected by an HTML `<base href>` also report unknown; review their actual dependency paths. Remote SDK and third-party scripts are not fetched or analyzed.
 
@@ -16,7 +16,9 @@ Acorn parses JavaScript ASTs; parse5 identifies executable inline HTML scripts a
 
 Dynamic storage keys, unresolved storage methods, shadowed storage names, missing migration release evidence, unsupported target versions, and JavaScript parse failures report unknown. This bounded analysis does not execute merchant code or prove computed keys correct. It does not follow arbitrary data flow, dynamic imports, event-handler attributes, generated code or runtime-loaded script graphs. Inspect unresolved findings and include all campaign sources in scope; a clean result is only static tracked source compatibility evidence. Browser behavior, order creation, tracking and analytics still require their own proof, especially where multiple campaigns share an origin. Use the SDK public store API where the manifest recommends it; do not invent a prefix-first merchant repair.
 
-Storage `length` property reads are unaffected metadata (`storage-metadata-read`). Storage `key()` enumeration, extracted method references, and mutations of reserved members remain unknown; enumeration cannot prove an SDK key lookup safe. Git discovery failures return one bounded CLI error. Local script diagnostics retain repository-relative spellings from HTML source, including `../` paths; excluded/outside sources are not read. The Git root and operator target are compared by filesystem device/inode identity, so supported case aliases and symlinks can name the same root. Source containment uses realpaths below the Git root without case folding. Extra positional CLI arguments are rejected so an accidental scope or version value cannot silently disappear.
+A `dynamic-key`, `unsupported-storage-method` or `storage-object-escape` line inside a loop, or an array callback such as `filter` or `forEach`, that tests a key it read from storage (a `k = sessionStorage.key(i)` variable, a `for…of Object.keys(sessionStorage)` or `for…in sessionStorage` variable, or the element parameter, the second for `reduce`, of a callback chained on `Object.keys(sessionStorage)`) with `k.indexOf('<prefix>') === 0` (or `!== 0`) or `k.startsWith('<prefix>')`, where the prefix is a scoped SDK key from the manifest (`next-cart-state` for `next-cart-state{__scope}`), ends in `[prefix loop: <prefix>]` and carries `prefixScan` in `--json`, when the line is where that key came from or reads that key by name. Other storage use in the loop, such as passing `sessionStorage` to a function, is not marked: the prefix test does not explain it. One note below the findings explains them all. Such a loop finds the SDK key with or without its scope suffix, so scoping alone does not break it. The lines still report unknown: Campaign Cart scopes these keys so campaigns on one origin cannot read each other's copy, and a prefix match reads whichever copy it meets first. Where the manifest names a public store for the key, as it does `useOrderStore` for `next-order`, the note names it too.
+
+Storage `length` property reads are unaffected metadata (`storage-metadata-read`). Storage `key()` enumeration, extracted method references, and mutations of reserved members remain unknown; enumeration cannot prove an SDK key lookup safe. Git discovery failures return one bounded CLI error. The tracked-file inventory lists only the paths under `--scope`, so repository size does not limit it; when it fails, the error reads `Cannot inventory tracked Git source files: <reason>` with Git's own first stderr line as the reason, or, when Git printed nothing, how it ended (its exit status, the signal that stopped it, or a spawn error code), or a request to narrow a scope whose list passes 256 MiB. npm 1.61.0 and earlier listed the whole repository and stopped with `Cannot inventory tracked Git source files.` once that list passed 1 MiB (about 25,000 paths); update the install rather than running the check on a copy, which can lose tracked files. Local script diagnostics retain repository-relative spellings from HTML source, including `../` paths; excluded/outside sources are not read. The Git root and operator target are compared by filesystem device/inode identity, so supported case aliases and symlinks can name the same root. Source containment uses realpaths below the Git root without case folding. Extra positional CLI arguments are rejected so an accidental scope or version value cannot silently disappear.
 
 ## Rewriting hardcoded pins in a static repo
 

package/docs/skills-revision.md

@@ -16,7 +16,7 @@ that the copy on disk moved.
 `skills.json` carries one top-level field:
 
 ```json
-"bundle_revision": "1.60.0+skills.1"
+"bundle_revision": "1.62.0+skills.1"
 ```
 
 The spelling is `<package version>+skills.<n>`:
@@ -25,7 +25,7 @@ The spelling is `<package version>+skills.<n>`:
   skills ship with (`check-skill-versions.mjs` fails if the two disagree);
 - `<n>` is a plain counter, not a semver component. It says "this is the *n*th
   skill-text revision published against that package version" and it **resets
-  with the prefix**. `1.60.0+skills.1` is therefore ahead of `1.40.0+skills.7`.
+  with the prefix**. `1.62.0+skills.1` is therefore ahead of `1.40.0+skills.7`.
 
 It is one identity for the bundle as a whole, on purpose. Per-skill versions
 still exist and still gate per-skill changes, but an agent that loaded one skill
@@ -37,7 +37,7 @@ The first body line of every bundled `SKILL.md`, immediately after the
 frontmatter, is exactly:
 
 ```
-Bundle revision: 1.60.0+skills.1
+Bundle revision: 1.62.0+skills.1
 ```
 
 followed by a short paragraph telling the agent to run the check below at the
@@ -48,7 +48,7 @@ text the agent is actually reading, not from a file it would have to go and open
 ## The check
 
 ```bash
-npx --no-install campaigns-os tooling status --skills-revision 1.60.0+skills.1
+npx --no-install campaigns-os tooling status --skills-revision 1.62.0+skills.1
 ```
 
 The value is compared against the bundle revision of the **CLI the command runs
@@ -90,20 +90,20 @@ reports the choice as `skills.scope` (`requested`, `installed_platforms`, or
 "revision_check": "match",
 "skills_revision": {
   "status": "match",
-  "requested": "1.60.0+skills.1",
+  "requested": "1.62.0+skills.1",
   "spelling": "bundle",
-  "on_disk": "1.60.0+skills.1",
+  "on_disk": "1.62.0+skills.1",
   "on_disk_skill": null,
-  "message": "match (1.60.0+skills.1)"
+  "message": "match (1.62.0+skills.1)"
 }
 ```
 
 The text view prints one named line, as a header above the rest of the status:
 
 ```
-Skills revision: match (1.60.0+skills.1)
-Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.60.0+skills.1 — start a fresh session
-Skills revision: unchecked (on disk 1.60.0+skills.1)
+Skills revision: match (1.62.0+skills.1)
+Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.62.0+skills.1 — start a fresh session
+Skills revision: unchecked (on disk 1.62.0+skills.1)
 ```
 
 `unchecked` is the state when the flag is absent. It is not an error — an

package/docs/source-adapters.md

@@ -0,0 +1,213 @@
+# Source Adapters
+
+The current release uses `html_funnel`: prepared HTML/CSS/assets provided by the developer.
+
+The adapter is deliberately explicit so the Build Packet, doctor, build, polish, deploy, and QA gates can reason about the source pages the same way every time.
+
+> **Where does the source HTML come from?** That's the entry-point question, covered in a separate doc: [docs/entry-points.md](./entry-points.md) names the five recognized shapes (template-stock, Figma-driven, AI-generated, hand-authored, mixed) and explains how each populates the inputs this adapter consumes.
+
+Source adapter inputs are compatibility contracts, not the final design-source
+contract. `prepare-build` may translate them into Design Source Contributions in
+the public Design Source Package while keeping the existing source-html manifest
+available for current producers.
+
+## `html_funnel`
+
+Input:
+
+- local folder
+- one or more `.html` pages
+- assets referenced by those pages
+- explicit or inferred page mapping to CampaignSpec pages
+- Page Kit target projection in `source_html.pages[].page_kit` after
+  `prepare-build`
+
+When no source-html manifest exists, `prepare-build` may infer page mappings
+from filenames. If more than one HTML file can satisfy the same active
+CampaignSpec page, or if every matching file was already assigned to a sibling
+page, Campaigns OS blocks `prepare_build`, records
+`context.source.ambiguous_candidates`, and drafts
+`context.source.manifest_draft`. Copy that draft to
+`.campaigns-os/source-html-manifest.json`, choose the intended candidate path for
+each ambiguous page, and rerun `start`/`prepare-build`. The fallback matcher
+should not silently choose among ambiguous source or asset-mirror pages.
+
+The `.html` files should be prepared for page-kit ingestion. This does not mean
+"rewrite everything into Liquid." Page Kit source files are HTML files with
+optional YAML frontmatter and optional Liquid filters/includes. Liquid is only
+needed where the page must call page-kit helpers such as `campaign_link`,
+`campaign_asset`, or `campaign_include`.
+
+`source_html.pages[].path` is the source file path relative to the source root.
+For mixed producers it may point at `figma-export/landing.html` or
+`checkout/index.html`. Build agents should use the sibling `page_kit` block for
+the target Page Kit file, route, CPK `page_type`, and frontmatter projection.
+
+## Adapter Decisions
+
+`prepare-build` records the reusable conversion contract in three places:
+
+- `packet.source_html.adapter_contract`
+- `context.adapter_decisions`
+- `report.adapter_decisions`
+
+These fields are intentionally machine-readable so doctor can name unfinished
+work instead of relying on chat history. After the build, record each true
+scalar choice with `record build --adapter-decision <key>=<value>`; put several
+choices in one comma-separated flag. A repeated flag keeps only the last list.
+`wrapper_policy` is selected at intake, not through this record flag.
+
+- `raw_html_conversion_status`: wrapper stripping, frontmatter, asset moves,
+  script/style refs, CTA rewrites, route policy, and layout choice are still
+  `pending` until build records `completed` or `not_required` with
+  `record build --adapter-decision raw_html_conversion_status=<value>`.
+- `source_asset_strategy`: page-kit campaigns should normally use
+  `pagekit_campaign_asset_root`, where `src/<slug>/assets/*` publishes as
+  `/<slug>/*`.
+- `commerce_shell_adoption`: runtime commerce pages should be
+  `template_clone_first_verified` or `sdk_surfaces_preserved` before a completed
+  build handoff. `custom_html_experimental` is a doctor blocker on runtime
+  pages.
+- `route_rewrite_policy`: record whether CampaignSpec routes and CTAs were
+  rewritten through campaign-aware routes/helpers.
+- `template_files_copied`: records the selected template family as an atomic
+  slice. A complete/verified slice covers `pages`, `_includes`, `_layouts`,
+  `assets/css`, `assets/js`, and `frontmatter_vocabulary`; its `paths` are
+  target-repo-relative proof paths that doctor checks once assembly is complete.
+- `config_script_strategy`: records how campaign config scripts load
+  (`campaign_asset`, `frontmatter_script`, `inline`, or `not_required`).
+- `wrapper_policy`: records whether document wrappers were stripped, preserved,
+  or not required (`strip_document_wrappers`, `preserve_document_wrappers`,
+  `not_required`, `unknown`). Unlike the other decisions here, this one is
+  selectable before the build stage runs — see
+  [Selecting the wrapper policy at intake](#selecting-the-wrapper-policy-at-intake).
+- `frontmatter_policy`: records whether Page Kit YAML frontmatter was created,
+  preserved, or intentionally not required.
+- `script_style_reference_policy`: records whether scripts/styles were moved to
+  frontmatter, campaign assets, inline blocks, or raw passthrough.
+- `cta_rewrite_policy`: records how CTA destinations were rewritten from
+  CampaignSpec routes.
+- `layout_choice`: records the Page Kit layout strategy used for the prepared
+  source.
+
+Raw AI-generated HTML normally needs this conversion pass before build:
+
+1. Keep the page-owned body markup that represents the design intent.
+2. Remove document wrappers such as `<!doctype>`, `<html>`, `<head>`, and `<body>` so the page can be wrapped by the campaign layout.
+3. Add YAML frontmatter for `title`, the `page_kit.frontmatter.page_type`, route/permalink or `next_url`, and any `styles`/`scripts`.
+4. Move reusable `<style>` blocks into `src/<slug>/assets/css/...` and reference them from frontmatter; keep tiny page-specific styles inline only when that matches the target campaign style.
+5. Move referenced images/fonts/assets into the campaign asset tree and use `campaign_asset` when paths need to be campaign-rooted. Page Kit copies `src/<slug>/assets/*` to the campaign root in built output: `src/<slug>/assets/config.js` renders as `/<slug>/config.js`, and `src/<slug>/assets/products/foo.png` renders as `/<slug>/products/foo.png`. Do not leave raw `/assets/...` or `/<slug>/assets/...` references in rendered pages unless that nested `assets/` directory exists intentionally.
+6. Replace internal page links and CTA destinations with CampaignSpec-derived routes, usually through `campaign_link`.
+7. For checkout, upsell, downsell, receipt, payment, totals, and submit controls, preserve or recreate the starter-template SDK contract rather than trusting raw source commerce markup.
+8. Run page-kit build and inspect `_site/<slug>/` for a complete body, expected meta tags, campaign-rooted links, and SDK runtime markers.
+
+A single-file static landing page is a good source artifact, but it is not
+automatically a complete page-kit page.
+
+## Source preparation check
+
+The preparation steps above used to be tacit knowledge; the doctor now checks
+them deterministically (#262). The check runs as the `source_html.preparation`
+slot in the Doctor Check Registry (phase `source`) on every mapped
+`source_html.pages[].path` file, so `start` and `build` — which embed doctor —
+gate on it before assembly, and a plain `campaigns-os doctor` re-checks the
+current files after source edits. Blocking findings are doctor **errors**: they
+set status `blocked` and make doctor's `next` block name the same stage the
+`next` command would (`prepare-build` while the prepare-build stage records
+the blockers, `doctor-blocked` otherwise), like any other unprepared input. The check is scoped to the certified template families'
+page-kit ingestion expectations; it is not a general HTML linter.
+
+| Code | Severity | Meaning and fix |
+| --- | --- | --- |
+| `source_html.prep.document_wrapper` | error (warning under a recorded `wrapper_policy: "preserve_document_wrappers"`) | A mapped source page is still a full browser document. Once the converted page-kit page exists at the page's `page_kit.output_path`, that page is checked instead of the design, since it is the file page-kit builds. Strip `<!doctype>`, `<html>`, `<head>`, and `<body>` so the campaign layout can wrap the page (conversion step 2; [docs/quickstart.md](./quickstart.md) "Prepare Raw HTML Source"), or record `preserve_document_wrappers` as an explicit adapter decision — the manifest `wrapper_policy` key or `--wrapper-policy`, see [Selecting the wrapper policy at intake](#selecting-the-wrapper-policy-at-intake). |
+| `source_html.prep.frontmatter_residue` | error | Leftover or broken YAML frontmatter: a leading `---` fence that never closes, or a frontmatter block (page-kit keys such as `page_type:`, `next_url:`) embedded below content where page-kit would render it literally. Keep exactly one closed frontmatter block at the very top of the file, or none when the packet's `page_kit.frontmatter` projection supplies it (conversion step 3). |
+| `source_html.prep.internal_link_unrooted` | warning | An internal link/CTA still targets a source file (`checkout.html`) instead of a CampaignSpec-derived route. Replace it, usually via `campaign_link` (conversion step 6). Warning rather than error because CTA rewrites are sanctioned build-stage work recorded under `cta_rewrite_policy`; the adapter gates own the completed-assembly block. |
+
+### Selecting the wrapper policy at intake
+
+`preserve_document_wrappers` is a real choice, so whoever hands over the source
+can make it — without editing the Build Packet the build stage writes. Two
+channels select it, both in the vocabulary above:
+
+**The source-html manifest.** Declare it once, next to the pages it applies to,
+in `.campaigns-os/source-html-manifest.json`:
+
+```json
+{
+  "schema_version": "source-html-manifest/v0",
+  "wrapper_policy": "preserve_document_wrappers",
+  "pages": [{ "page_id": "landing", "path": "landing.html" }]
+}
+```
+
+**The CLI flag.** Select it per run on the command that prepares the build:
+
+```bash
+campaigns-os prepare-build --spec <spec.json> --source <html-dir> \
+  --target <page-kit-dir> --template-family <family> \
+  --wrapper-policy preserve_document_wrappers
+```
+
+`start` and `build` take the same flag, since both run the prepare step.
+
+**Order of operations.** Decide the wrapper policy before you capture
+`source_screenshot` proof or record `source_hash`, because both describe the
+file as it is handed over. `source_hash` is the sha256 of the source file at
+manifest generation time; `doctor` recomputes it and reports
+`source_html.pages.source_hash` when the file no longer matches. So under the
+default `strip_document_wrappers` policy, strip first, then capture the
+screenshots and compute the hashes of the stripped files. Under
+`preserve_document_wrappers` nothing is stripped, the existing screenshots and
+hashes stay valid, and the design-source gate and the preparation check read
+the same file. Stripping after the manifest was written invalidates its hashes
+and its screenshots, and a stripped page is no longer the standalone document
+its `source_screenshot` proof was captured from.
+
+**Precedence.** The flag wins over the manifest key, and with neither the
+default is `strip_document_wrappers` — the same order the template family uses
+for its CLI override and its spec hint (see
+[docs/build-packet.md](./build-packet.md), "Authoring-Time Hints"). The
+resolved value is written to
+`source_html.adapter_contract.wrapper_policy` on the packet, and a non-default
+selection is echoed on stderr with the channel that set it. A value outside the
+vocabulary fails the run when it comes from the flag. From the manifest key it
+does not: the manifest is used as written — `pages[]`, `producer_provenance`
+and `files[]` all survive — the key alone is ignored, the default policy
+applies, and one warning names the key, the value, and the accepted values.
+Dropping a whole manifest over one optional hint would cost far more than the
+hint is worth.
+
+Selecting `preserve_document_wrappers` does not silence the finding: the
+document wrappers are still reported on every page that carries them, as a
+warning rather than a blocking error.
+
+Asset-path rooting (raw `/assets/...` references, missing or out-of-root
+files) stays owned by the prepare-build source asset crawl and its
+`source_asset.*` codes (conversion step 5); the preparation check does not
+duplicate them.
+
+Known-unprepared and prepared reference fixtures live at
+`fixtures/source-prep/`; `src/source-prep.test.mjs` and
+`src/doctor-source-prep.test.mjs` pin each code and the pass path.
+
+Wedge relevance: the Stage 0 wedge run protocol (#259) includes this check —
+wedge runs treat a `source_html.prep.*` blocker as a classified workflow
+signal at the source-preparation handoff, not founder-interpretation territory.
+
+Checkout, cart, upsell, receipt, payment, totals, and submit behavior should remain governed by starter-template contracts and SDK wiring. Source files can carry page design, but live commerce behavior comes from the campaign setup and runtime surfaces.
+
+If a source page marks a region as SDK-owned, for example with
+`data-commerce-zone="checkout-form"` or comments like `SDK-OWNED: ... provided
+by the limos checkout commerce surface`, treat that as an instruction to adopt
+the selected starter-template family shell for that runtime surface. It is not
+permission to invent a custom checkout shell and paste only borrowed partials
+inside it. `prepare-build` records these regions in the Build Context, and
+doctor warns until the build path has a clear shell-adoption decision.
+
+Template families are not single-file dependencies. If setup copies a starter
+family into a target campaign, copy the matching pages together with their
+family `_includes/`, `_layouts/`, `assets/css/`, and `assets/js/` dependencies.
+Copying only `checkout.html` and `receipt.html` can leave Liquid includes,
+layouts, CSS, or JavaScript unresolved. Record the copied or verified target
+paths in `template_files_copied.paths`; a completed report with missing paths is
+not doctor-clean.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextcommerce/campaigns-os",
-  "version": "1.60.0",
+  "version": "1.62.0",
   "description": "Toolkit for agent-assisted NEXT campaign builds.",
   "license": "Apache-2.0",
   "repository": {
@@ -104,7 +104,9 @@
     "yaml": "^2.9.1"
   },
   "optionalDependencies": {
-    "playwright": "^1.63.0"
+    "pixelmatch": "^7.2.0",
+    "playwright": "^1.63.0",
+    "pngjs": "^7.0.0"
   },
   "devDependencies": {
     "typescript": "^5.9.3"
@@ -153,6 +155,11 @@
     "docs/progress-snapshots.md",
     "demo",
     "docs/demo-preview.md",
-    "docs/local-setup.md"
+    "docs/local-setup.md",
+    "docs/quickstart.md",
+    "docs/access-model.md",
+    "docs/entry-points.md",
+    "docs/source-adapters.md",
+    "docs/campaignspec-authoring-examples.md"
   ]
 }

package/schemas/campaign-design-source-package.v0.schema.json

@@ -272,8 +272,15 @@
         "sha256": { "$ref": "#/$defs/sha256" },
         "role": { "type": "string", "minLength": 1 },
         "media_type": { "type": "string", "minLength": 1 },
+        "design_file_type": { "type": "string", "minLength": 1, "pattern": "\\S" },
         "notes": { "type": ["string", "null"] }
       },
+      "allOf": [
+        {
+          "if": { "properties": { "design_file_type": true }, "required": ["design_file_type"] },
+          "then": { "properties": { "role": { "const": "design_file" } }, "required": ["role"] }
+        }
+      ],
       "anyOf": [
         { "properties": { "path": true }, "required": ["path"] },
         { "properties": { "url": true }, "required": ["url"] }
@@ -460,6 +467,7 @@
         "screenshot_refs": { "$ref": "#/$defs/stringList" },
         "reference_refs": { "$ref": "#/$defs/stringList" },
         "template_reference_id": { "type": "string", "minLength": 1 },
+        "derived_from": { "type": "string", "minLength": 1, "pattern": "\\S" },
         "notes": { "type": ["string", "null"] }
       },
       "allOf": [