@nextcommerce/campaigns-os 1.60.0 → 1.61.0

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,6 +16,8 @@ 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.
 
+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. 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.61.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.61.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.61.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.61.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.61.0+skills.1",
   "spelling": "bundle",
-  "on_disk": "1.60.0+skills.1",
+  "on_disk": "1.61.0+skills.1",
   "on_disk_skill": null,
-  "message": "match (1.60.0+skills.1)"
+  "message": "match (1.61.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.61.0+skills.1)
+Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.61.0+skills.1 — start a fresh session
+Skills revision: unchecked (on disk 1.61.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.61.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": [

package/schemas/campaigns-os-readback.v2.schema.json

@@ -44,12 +44,188 @@
       "description": "Where two artifacts record different states for one stage: the assembly report calls a stage completed while the QA verdict fails an assertion whose id is namespaced to that stage. One record per stage, in the order the failures were seen. The readback reports the disagreement and does not adjudicate it. This too is the readback's own layer.",
       "items": { "$ref": "#/$defs/divergence" }
     },
+    "evidence_debt": {
+      "description": "Optional additive build-binding assessment emitted by current readback in JSON and text. Reads built bytes without timestamps, processes, writes or network. It does not rerun stages or reinterpret verdicts; unknown never establishes no debt.",
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "polish",
+        "qa",
+        "changes"
+      ],
+      "properties": {
+        "polish": {
+          "$ref": "#/$defs/evidence_debt_stage"
+        },
+        "qa": {
+          "$ref": "#/$defs/evidence_debt_stage"
+        },
+        "changes": {
+          "$ref": "#/$defs/evidence_debt_changes"
+        }
+      }
+    },
     "clean": {
       "type": "boolean",
-      "description": "True only when every artifact the readback found is loaded or absent (never unreadable or unrecognized), staleness is computable and NO loaded artifact is stale, staleness.unparseable_keys is empty (no loaded artifact recorded an age the readback could not read), divergences is empty, and doctor.error_count is zero. A readback-integrity flag, not a verdict: a blocked QA verdict whose artifacts all read cleanly is still clean, because the readback saw exactly what Campaigns OS recorded. docs/readback.md states the rule and its limits."
+      "description": "True only when every artifact the readback found is loaded or absent (never unreadable or unrecognized), staleness is computable and NO loaded artifact is stale, staleness.unparseable_keys is empty (no loaded artifact recorded an age the readback could not read), divergences is empty, doctor.error_count is zero, and neither evidence_debt stage is owed (any owed Polish or QA stage makes clean false). Unknown debt alone does not make clean false; consumers must inspect evidence_debt even when clean is true. A readback-integrity flag, not a verdict: a blocked QA verdict whose artifacts all read cleanly is still clean, because the readback saw exactly what Campaigns OS recorded. docs/readback.md states the rule and its limits."
     }
   },
   "$defs": {
+    "build_fingerprint": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "minLength": 1
+    },
+    "evidence_debt_stage": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "status",
+        "matches_current_build",
+        "recorded_build_fingerprint",
+        "current_build_fingerprint",
+        "reason"
+      ],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": [
+            "current",
+            "owed",
+            "unknown"
+          ],
+          "description": "current: the stage binding matches current built bytes, the assembly fingerprint is available, and the stage is not required. owed: the binding differs or the lifecycle requires the stage again. unknown: the packet, the built output or the assembly fingerprint is unavailable, which takes precedence over owed even for a required stage, or the stage fingerprint is missing on a stage that is not required; unknown never means no debt."
+        },
+        "matches_current_build": {
+          "type": [
+            "boolean",
+            "null"
+          ],
+          "description": "Fingerprint equality, or null when either fingerprint is absent. A true value does not cancel lifecycle debt."
+        },
+        "recorded_build_fingerprint": {
+          "$ref": "#/$defs/build_fingerprint",
+          "description": "The stage binding: Polish source_build_fingerprint (top-level before evidence); QA evidence.qc_build_fingerprint before source_build_fingerprint."
+        },
+        "current_build_fingerprint": {
+          "$ref": "#/$defs/build_fingerprint"
+        },
+        "reason": {
+          "enum": [
+            null,
+            "build_fingerprint_changed",
+            "stage_required_by_build",
+            "stage_required_by_brief",
+            "stage_required_by_spec",
+            "stage_required",
+            "packet_unavailable",
+            "build_output_location_unknown",
+            "build_output_missing",
+            "build_output_unreadable",
+            "assembly_build_fingerprint_missing",
+            "stage_build_fingerprint_missing"
+          ],
+          "description": "Null for current. Owed names a changed binding or the recorded required_by cause (build, brief, spec, or unspecified). Unknown names the unavailable input or fingerprint."
+        }
+      }
+    },
+    "evidence_debt_changes": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Current built output compared with the retained assembly manifest, which need not be the build an older stage reviewed. Empty lists under unknown do not establish that no files changed; older stage manifests are not reconstructed.",
+      "required": [
+        "status",
+        "reason",
+        "recorded_build_fingerprint",
+        "current_build_fingerprint",
+        "changed_pages",
+        "unmapped_files",
+        "extra",
+        "missing",
+        "changed"
+      ],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": [
+            "known",
+            "unknown"
+          ]
+        },
+        "reason": {
+          "enum": [
+            null,
+            "packet_unavailable",
+            "build_output_location_unknown",
+            "build_output_missing",
+            "build_output_unreadable",
+            "assembly_build_fingerprint_missing",
+            "build_output_pages_unresolved",
+            "build_manifest_unavailable"
+          ],
+          "description": "Null when known. Missing or unusable manifest and unresolved page map make changes unknown independently of stage binding status."
+        },
+        "recorded_build_fingerprint": {
+          "$ref": "#/$defs/build_fingerprint",
+          "description": "The retained assembly baseline fingerprint."
+        },
+        "current_build_fingerprint": {
+          "$ref": "#/$defs/build_fingerprint"
+        },
+        "changed_pages": {
+          "type": "array",
+          "description": "Added, removed or modified HTML pages in sorted built-path order, using route-derived page identities. Removed HTML uses the same route projection. Paths are relative to _site/<public_route_slug>/.",
+          "items": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": [
+              "page_id",
+              "built_path"
+            ],
+            "properties": {
+              "page_id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "built_path": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        },
+        "unmapped_files": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Sorted differing paths outside the built page map, including shared CSS, scripts and assets."
+        },
+        "extra": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Complete sorted paths added since the retained manifest, relative to the built output root."
+        },
+        "missing": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Complete sorted paths removed since the retained manifest, relative to the built output root."
+        },
+        "changed": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Complete sorted paths modified since the retained manifest, relative to the built output root."
+        }
+      }
+    },
     "artifact_key": {
       "type": "string",
       "enum": ["packet", "doctor", "context", "report", "qa_verdict", "findings"]

package/schemas/source-html-manifest.v0.schema.json

@@ -139,6 +139,9 @@
             "minLength": 1,
             "description": "Active CampaignSpec page id. This is the primary join key."
           },
+          "design_file": {
+            "description": "Optional design-file authority behind this page's HTML export, normally {type?, file_url, breakpoints?: {desktop?, tablet?, mobile?}}. Deliberately unconstrained: the runtime accepts every JSON value here, warns on unusable declarations or frame links and ignores them without rejecting the manifest. Usable file_url values parse as absolute HTTPS URLs (scheme case-insensitive)."
+          },
           "path": {
             "type": "string",
             "minLength": 1,

package/skills/campaign-lifecycle-orientation/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: campaign-lifecycle-orientation
-version: 1.0.41
+version: 1.0.46
 description: Orient a reader to the Campaigns OS lifecycle artifacts a run has already emitted, without advancing any stage or changing any state.
 ---
 
-Bundle revision: 1.60.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.60.0+skills.1`
+Bundle revision: 1.61.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.61.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/campaign-readback-classification/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: campaign-readback-classification
-version: 1.0.41
+version: 1.0.46
 description: Classify a selected campaign from the readback projection's v2 fields and write a read-only handoff without turning diagnosis into permission.
 ---
 
-Bundle revision: 1.60.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.60.0+skills.1`
+Bundle revision: 1.61.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.61.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/campaign-run-evidence/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: campaign-run-evidence
-version: 1.0.41
+version: 1.0.46
 description: Interpret existing Campaigns OS doctor, QA and proof-depth evidence without claiming more proof than the artifacts contain.
 ---
 
-Bundle revision: 1.60.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.60.0+skills.1`
+Bundle revision: 1.61.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.61.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.41
+version: 1.0.46
 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.60.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.60.0+skills.1`
+Bundle revision: 1.61.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.61.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