@nextcommerce/campaigns-os 1.43.1 → 1.46.0

package/docs/build-packet.md

@@ -69,7 +69,7 @@ localhost readiness is not production approval.
 
 Most campaigns are served under a slug prefix (`/<public_route_slug>/...`), and
 that stays the default. A campaign whose whole funnel is served from the **site
-root** — pages at `/checkout-v2`, `/oto-ruggie`, `/receipt` with no slug prefix,
+root** — pages at `/checkout-v2`, `/oto-rootfunnel`, `/receipt` with no slug prefix,
 the normal shape for a single-campaign site or an in-place static deploy —
 declares `campaign.route_root: "/"`. Rules:
 
@@ -85,7 +85,10 @@ declares `campaign.route_root: "/"`. Rules:
 - Doctor's routing-meta checks (`routing_meta.runtime_root`,
   `sdk_hints.meta_tags.route_mismatch`) and route displays validate against the
   declared route root instead of assuming slug-as-prefix, so a root-served
-  funnel's correct `/receipt`-style metas pass without waivers.
+  funnel's correct `/receipt`-style metas pass without waivers. A routing
+  meta value with a bare or `//` host in front of its path is not a
+  `runtime_root` warning; it is the `routing_meta.host_prefixed` blocker (see "Page Kit
+  Target Projection" below).
 - The CampaignSpec may carry the same declaration at `campaign.route_root` (or
   `spec_identity.route_root`); `prepare-build` copies it onto the packet and
   defaults `live_url_path` to `/`.
@@ -112,6 +115,22 @@ Before scaffold, a missing target entry is `not_applicable`; once setup or
 assembly is terminal, or the target output already exists, missing or malformed
 target evidence is a non-waivable blocker. Target-only values remain warnings.
 Mismatches, missing required target values, and known demo residue block.
+An absent or null spec field means "not provided". An explicit empty (or
+whitespace-only) string in one of the eight optional fields (`store_name`,
+`store_terms`, `store_privacy`, `store_contact`, `store_returns`,
+`store_shipping`, `store_phone`, `store_phone_tel`) means the merchant has no
+such value: `page-kit sync` blanks a recognised starter demo value with it
+(the placeholder storefront URLs and phone number; the starter's demo store
+name is not recognised and stays a `target_only` warning), and a blank or
+absent target field then reads as `intentionally_empty` (clean, and named in
+the gate reason and the doctor line). `campaign.store_url` stays required: a
+`""` there still raises doctor's `spec.store_profile` error, and the gate
+reason says so. A real, non-demo target value against a spec `""` is left as
+it is and stays a `target_only` warning, because Maps saved `""` for every
+cleared store field before it meant empty; the warning and the sync output
+(`spec_empty_not_applied[]`) say the `""` was not applied, so remove that value
+by hand if the merchant has none. An empty string outside these fields
+carries no such meaning.
 Demo residue (a `demo.29next.com` URL or the demo phone number still in the
 target) is never waivable: the gate names the residue fields, offers no waive
 command for them, and `checkpoint waive` refuses with those fields until the
@@ -142,9 +161,15 @@ re-saving the Map). The repo pin is the authority for what ships and the Map
 field is a build hint, so that state is a doctor warning, not a blocker (see
 the SDK version checkpoint below). Both go into `_data/campaigns.json[public_route_slug]`,
 prints a field-by-field before/after diff, and touches nothing else: a
-governed field the spec does not carry is left as it is (doctor's
-`target_only` warning still applies), non-governed keys keep their values and
-order, other routes and other files are not written. The file is edited in
+governed field the spec does not carry (absent or null) is left as it is
+(doctor's `target_only` warning still applies), a field the spec sets to `""`
+(or whitespace only) blanks a recognised starter demo value (the placeholder
+storefront URLs and phone number; the starter's demo store name is not
+recognised and stays a `target_only` warning) and otherwise leaves the target
+value as it is (listed in `not_in_spec[]` as before and also in
+`spec_empty_not_applied[]`, printed as `Spec "" not applied`), non-governed
+keys keep their values and order, other routes and other files are not
+written. The file is edited in
 place and re-serialized with its own top-level indentation, line ending and
 trailing newline; when that round trip would not have reproduced the file
 byte for byte (a minified file, mixed indentation), a
@@ -724,13 +749,14 @@ built-output gate now carries.
 ### Built-output SDK markup gate (`built_output.sdk_markup`)
 
 Every doctor run that sees built output also runs the static SDK markup
-family: six shapes of `data-next-*` markup that the Campaign Cart SDK binds
+family: seven shapes of `data-next-*` markup that the Campaign Cart SDK binds
 without complaint and that then either do nothing (a field that never reaches
 the order, a button that never enables) or write the cart twice. They sit
 beside `built_output.upsell_selector_scope`, which is the same kind of check
-for one shape. The codes are the ones a partner Campaign Cart kit used, kept so
-the two vocabularies line up; each doctor issue is `built_output.sdk_markup.`
-plus the code lower-cased, and its message leads with the code.
+for one shape. The first six codes are the ones a partner Campaign Cart kit
+used, kept so the two vocabularies line up; each doctor issue is
+`built_output.sdk_markup.` plus the code lower-cased, and its message leads
+with the code.
 
 Blockers (not waivable — the markup provably does not do what it says):
 
@@ -752,6 +778,12 @@ Blockers (not waivable — the markup provably does not do what it says):
   `data-next-selector-id` names no selector on the page (an element that is a
   bundle, package, cart or upsell selector; another element echoing the id
   does not count). One finding per dead id, however many buttons link to it.
+- `ORPHANED_UPSELL_ACTION` — an element carrying `data-next-upsell-action` with
+  no ancestor carrying `data-next-upsell`. The SDK binds upsell actions only
+  inside that container, so a "No thanks" link placed beside the offer
+  container, not inside it, goes nowhere and the shopper cannot decline.
+  Checked on every page type, not only upsell and downsell pages. Move the
+  element inside its `data-next-upsell` container.
 
 Warnings (advisory):
 
@@ -783,6 +815,64 @@ advisories, `unknown_attributes[]`, `pages_scanned`,
 It passes, with no advisory, on the canonical rendered output of every
 certified starter family (`fixtures/certified-families/`).
 
+### Built-output script syntax gate (`built_output.script_syntax`)
+
+Every doctor run that sees built output (the packet path and `doctor --built`
+alike) parses each campaign-owned `.js` file a built page loads by a local
+`<script src>`. A script that does not parse throws a `SyntaxError` on every
+load of every page that references it, and nothing it defines runs; every
+HTML-reading gate passes over it. The shape that shipped was a template-family
+checkout script, copied and hand-edited, left with one closing `});` too many.
+
+Parsing uses Acorn at the latest `ecmaVersion`: `sourceType: 'script'` for
+classic scripts and `'module'` for `type="module"`, which is how the browser
+reads each. Remote scripts (an `http(s):` URL, a protocol-relative `//` URL,
+`data:`) are not campaign-owned and are not read, and neither are data blocks
+such as JSON-LD. The type is compared as the browser compares it, with
+surrounding ASCII whitespace stripped and case ignored. A classic `nomodule`
+script is skipped: a module-capable browser never fetches or runs it. A
+`type="module"` script ignores `nomodule` and is still parsed. Each src
+resolves the way the browser resolves it: against the base in effect when the
+parser prepares the script at its end tag, which is the first HTML `<base
+href>` in tree order among those already parsed, or else the page. A `<base>`
+parsed after a script does not move it, whether it is async, deferred or a
+module: its URL is fixed when it is prepared, not when it is fetched. Parse
+order decides, not final tree position, so a base that table foster parenting
+moves ahead of an earlier script still does not apply to it. A `base` inside
+SVG or MathML is not a base element, and only HTML-namespace `<script>`
+elements are read: an SVG `<script>` never loads a `src` attribute. The href is read as the URL parser reads
+it: only leading and trailing ASCII control characters and spaces are
+stripped. A base
+the browser refuses (one that does not parse, or a `data:` or `javascript:`
+URL) falls back to the page, as the HTML "set the frozen base URL" steps
+require. The percent-decoded path maps under the site root first, then the
+campaign directory, never outside either. A base on another origin makes
+relative srcs remote. Imports inside a module are not followed.
+
+A parse failure blocks (not waivable — a script that cannot be parsed cannot be
+intended to ship) under `built_output.script_syntax.parse_failure`, one error
+per file. The message leads with `<file>:<line>:<column>` and a fixed
+diagnostic category (for example `Unexpected token` or `Invalid regular
+expression`), never text from the script, and names the pages that load the
+file. A referenced local script that is not in the built output is a warning,
+not a blocker, under `built_output.script_syntax.missing_script`, one warning
+per src naming the pages that load it: the browser gets a 404 for it and
+nothing it would define runs, but whether the page needs it is not known here.
+The src is also listed in `scripts_unresolved[]`. While a parse failure blocks
+the gate, the missing scripts stay on the gate's `warned[]` rather than also
+surfacing as warnings.
+
+The gate's evidence lands beside the other checkpoint gates at
+`derived.checkpoint_gates[]` (`id: built_output.script_syntax`, status `pass` |
+`blocked` | `not_applicable`, `findings[]` with `file`, `line`, `column`,
+`source_type` and `pages`, `warned[]` with `src` and `pages`,
+`scripts_scanned`, `scripts_unresolved[]`, `pages_scanned`). Fixtures: `fixtures/script-syntax/{good,bad}`. It passes, parsing every
+local script the pages load and with no missing-script warning, on the
+canonical rendered output of every certified starter family
+(`fixtures/certified-families/`). QA applies the same rule to the page scripts
+it reads for credential declarations (`script-parse:<page_id>`; see
+[QA and test orders](qa-and-test-orders.md)).
+
 > **Where does the source HTML come from?** See [docs/entry-points.md](./entry-points.md) for the five recognized entry points (template-stock, Figma-driven, AI-generated, hand-authored, mixed) and how each populates `source_html.pages[]` + `design_source`.
 
 ## Artifact Locations
@@ -980,9 +1070,9 @@ fingerprint is `sha256:` plus the SHA-256 of that manifest. Nothing is excluded
 default (Page Kit writes only rendered HTML and copied assets into `_site/`, nothing
 it timestamps); `.campaign-runtime/page-kit-build-summary.json` lives outside the
 root and is not hashed. Build does not type the value: after page-kit build it runs
-`campaigns-os doctor --packet <packet> --json` and copies
-`derived.build_output_fingerprint.value` (with `.file_count` and `.status`) onto
-`stages.assembly.build_fingerprint`. Doctor recomputes the value on every run
+`campaigns-os record build --packet <packet>`, which stamps doctor's
+`derived.build_output_fingerprint.value` onto `stages.assembly.build_fingerprint`
+(see "Recording stage completion" below). Doctor recomputes the value on every run
 (`built_output.fingerprint`): a match is a ready line, a missing record is the
 warning `built_output.fingerprint_missing` carrying the value to record, and a
 recorded value the output no longer matches is `built_output.fingerprint_stale`
@@ -1006,9 +1096,11 @@ Design Source Package exists. The waiver must remain visible in Campaign
 Readiness Readback and downstream QA evidence; it is not a silent pass.
 In v0, write accepted Source Freshness Waivers directly into `waivers[]`.
 `campaigns-os checkpoint waive` is a staged generic registry and currently
-accepts four gates: `page_kit.store_profile`, `page_kit.sdk_version`,
-`polish.hidden_eager_media`, and `built_output.upsell_selector_scope`; an
-unregistered gate id is refused with that list. `theme waive` applies the same
+accepts five gates: `page_kit.store_profile`, `page_kit.sdk_version`,
+`polish.hidden_eager_media`, `built_output.upsell_selector_scope`, and
+`source_html.producer_provenance`, which is waived per page with
+`--page <page_id>` (see the [Design Source Package](./design-source-package.md)
+hand-written HTML route); an unregistered gate id is refused with that list. `theme waive` applies the same
 attribution rule (a named human, no placeholder, an optional future
 `--expires-at`) on its own lane. Within Polish, only the broader Source Freshness
 waiver retains its existing report path; theme and QA decisions retain their
@@ -1167,12 +1259,13 @@ and report proof policy fields above.
 | `--spec <path>` | Local JSON file | Agent-authored local specs, saved-Map exports, offline work or CI fixtures |
 | `--map-id <id>` | Map Builder proxy (KV-backed) | Saved-Map intake from the current KV revision |
 
-When `--map-id <id>` is set, the CLI fetches `GET <proxy>/api/spec/<id>` (default `<proxy>` is `https://campaign-map.nextcommerce.com`) and caches the response to `<target>/.campaign-runtime/fetched-specs/<id>.json`. The cached file is what downstream stages read, so the packet's `spec.local_path` always resolves to an on-disk artifact regardless of intake mode.
+When `--map-id <id>` is set, the CLI fetches `GET <proxy>/api/spec/<id>` (default `<proxy>` is `https://campaign-map.nextcommerce.com`) and caches the response to `<target>/.campaign-runtime/fetched-specs/<id>.json`. The cached file is what downstream stages read, so the packet's `spec.local_path` always resolves to an on-disk artifact regardless of intake mode. When the Map holds routes with a host in front of the path, the cached file holds the rooted routes and that run's Assembly Report `evidence[]` holds the values as fetched (see "Page Kit Target Projection" below). The cache is written only inside a real `fetched-specs/` directory: if `.campaign-runtime/`, `fetched-specs/` or the cache file is a symlink, the command stops with an error before fetching and writes nothing. Each write goes to a new file renamed over the cache file, so a hard link to the old file keeps its bytes.
 
 Saved-Map retrieval behavior (`--map-id`):
 
 - **Re-fetch by default.** Every `start` / `prepare-build` invocation re-fetches from KV. KV is the source of truth; the cache file is a debug/inspection artifact, not a performance optimization.
-- **`--cached-spec`** reuses the cache without a network call. Use for offline iteration or when the proxy is temporarily unreachable.
+- **One writer at a time.** The fetch happens first, but the fetched spec is written to the cache file only once the run holds the per-target prepare-build lock. A second run against the same target, fetching a newer Map revision, waits for the lock before replacing the cache, so the run holding it records the hash of the revision it actually parsed.
+- **`--cached-spec`** reuses the cache without a network call. Use for offline iteration or when the proxy is temporarily unreachable. The cached copy is read as it is and never rewritten.
 - **`--proxy-base <url>`** overrides the default origin. Use for staging environments or local Worker dev (`wrangler dev`). Spec retrieval carries no credential, so any reachable origin works here — but the same flag also aims the credential-bearing rails (Run Telemetry remit, QA verdict publish, `telemetry list`), and those require `https:` unless the host is loopback (`localhost`, `127.0.0.1`, `[::1]`), which is allowed over plain http with a stderr warning. A plain-http remote proxy is refused before the request. See docs/workflow-findings-sidecar.md (Remit Channel).
 - Failure modes (HTTP error, `{ok: false}` response, network timeout) surface as clean CLI errors before any packet is written.
 
@@ -1180,7 +1273,7 @@ The fetched spec is treated identically to a `--spec`-supplied local file from t
 
 ## Source HTML Manifest Auto-Population
 
-When the source HTML root carries a source-html manifest at `<source>/.campaigns-os/source-html-manifest.json` (schema `source-html-manifest/v0`, published at `schemas/source-html-manifest.v0.schema.json`) — or `--design-manifest <path>` names a manifest of that schema anywhere else, for a source root nobody can write to — `campaigns-os prepare-build` reads it and uses its `pages[]` block to populate `packet.source_html.pages[]` directly — bypassing the legacy filesystem-name slug matching. Wherever the manifest lives, its `pages[].path` entries stay relative to `--source`. A `pages[]` entry with `skip_reason` and no `path` declares a template-stock page: its assembly decision carries `template_stock: true` and the locked family, and intake demands no design source for it ([Template-stock pages](design-source-package.md#template-stock-pages-the-family-decides)).
+When the source HTML root carries a source-html manifest at `<source>/.campaigns-os/source-html-manifest.json` (schema `source-html-manifest/v0`, published at `schemas/source-html-manifest.v0.schema.json`) — or `--design-manifest <path>` names a manifest of that schema anywhere else, for a source root nobody can write to — `campaigns-os prepare-build` reads it and uses its `pages[]` block to populate `packet.source_html.pages[]` directly — bypassing the legacy filesystem-name slug matching. Wherever the manifest lives, its `pages[].path` entries stay relative to `--source`. Each `pages[]` entry carries exactly one of `path` or `skip_reason`: an entry with both is invalid, and an invalid entry makes prepare-build ignore the whole manifest and fall back to filesystem matching. A `pages[]` entry with `skip_reason` and no `path` declares a template-stock page: its assembly decision carries `template_stock: true` and the locked family, and intake demands no design source for it ([Template-stock pages](design-source-package.md#template-stock-pages-the-family-decides)).
 
 The source-html manifest remains a producer/source-HTML adapter input. It is not
 renamed into the Design Source Package. In the normalized source workflow,
@@ -1190,7 +1283,10 @@ contributions, coverage, gaps/TODOs, Surface Identity, references, and readback.
 When source-html data is the available input and the default package path is
 missing, current v0 `prepare-build` synthesizes the package. If a package already
 exists, it is validated against the current material inputs and reused byte for
-byte or refused; it is never silently regenerated. Downstream Build and Polish
+byte or refused; it is never silently regenerated. The one exception is a stale
+package an earlier `prepare-build` synthesized and nobody has changed since:
+`--force` regenerates it from the current inputs
+([Design Source Package: stale packages](design-source-package.md#prepare-build-emit-validate-or-refuse)). Downstream Build and Polish
 consume the package concept rather than branching back to
 `packet.source_html` as a second source model. The emitted package lives at
 `.campaign-runtime/input/design-source-package.json` by default and is referenced
@@ -1259,6 +1355,70 @@ routes during projection. That normalization strips `.html`/`index.html`,
 removes query/fragment values, converts absolute preview URLs to their path, and
 normalizes trailing slashes before deriving target files and frontmatter routes.
 
+A route value with a host in front of its path (an older saved Map stored
+`shop.example.com/route/upsell/` where the route is `/route/upsell/`) is
+reduced to its rooted path before anything reads a spec that `prepare-build`,
+`start` or `build` fetched with `--map-id` in the same run. This covers every
+`page_url` and every `next-success-url`, `next-upsell-accept-url` and
+`next-upsell-decline-url` meta tag value in `funnels[].pages[]` and
+`funnel_pages[]`:
+
+- The host is removed and the path is kept with its query and fragment
+  (`shop.example.com/route/x/?v=b#top` becomes `/route/x/?v=b#top`). An
+  absolute `http(s)` `page_url` is rooted the same way; an absolute `http(s)`
+  routing meta value is a valid SDK target and is kept.
+- The fetched copy at `<target>/.campaign-runtime/fetched-specs/<map-id>.json`
+  then holds the rooted values, not the bytes as fetched. It is replaced only
+  after the Assembly Report recording the changes has been published, so if
+  publishing fails the copy is left exactly as fetched. The rooted spec is
+  written to a new file in `fetched-specs/` and renamed over the copy, so
+  another name for the old file (a hard link) is never changed. A spec with
+  no host-prefixed value is written exactly as fetched, as before.
+- Each changed value is recorded on that run's Assembly Report `evidence[]` as
+  `{ "code": "routing_meta.host_stripped", "page_id", "field", "from", "to" }`;
+  `from` is the value exactly as the Map returned it. The raw values are kept
+  only there and in the Map itself: a later run with `--cached-spec` reads the
+  rooted copy, finds nothing to strip, and records no evidence. One line on
+  stderr lists the changes.
+- `intake.saved_map_revision.local_spec_material_hash` in the Build Context is
+  the material hash of the rooted copy, while `hash` stays the fetched Map
+  revision. A progress snapshot's `saved_revision_alignment: "aligned"`
+  therefore means the local spec matches that Map revision after host
+  stripping, not byte for byte.
+
+A local `--spec` file and a copy reused with `--cached-spec` are never
+rewritten. When either holds a value doctor blocks on (below), intake reads it
+as it is and prints one line on stderr naming each value and its rooted form:
+for a local file, that the file must be edited; for `--cached-spec`, to re-run
+without `--cached-spec` so the Map is fetched and normalised.
+
+A value reads as host-prefixed when it is one of:
+
+- an `http://` or `https://` URL, with any host (stripped from a fresh fetch;
+  never blocked);
+- `//<host>/...`, where `<host>` is one of the bare host forms below;
+- `<host>/...`, where `<host>` is `localhost`, a valid IPv4 address (four
+  dot-separated numbers, each 0-255), any name with a `:port`
+  (`localhost:8080`, `shop.example.com:8443`), or a dotted name whose last
+  label is 2-63 letters and is not a page or script extension: `html`, `htm`,
+  `shtml`, `php`, `asp`, `aspx`, `jsp` or `cgi` (`shop.example.com`,
+  any case).
+
+Everything else stays a route for the existing checks: a rooted `/...` value,
+a first segment with no dot (`route/x/`), a dotted segment whose last label is
+not all letters (`v1.2/offer/`), a dotted quad with a number over 255
+(`300.1.2.3/offer/`), a page or script filename (`checkout.html`,
+`index.php/checkout/`, `upsell.aspx/`), `//` followed by something that is not
+a host (`//route/x/`), a bare host with no path, and an empty or missing value.
+
+If a bare or `//` host-prefixed value still reaches doctor (a local spec that
+holds one, a copy reused with `--cached-spec`, or a spec edited after intake),
+doctor blocks with `routing_meta.host_prefixed`, naming each value and its
+rooted form. An absolute `http(s)` value never raises it: projection converts
+an absolute `page_url` to its path, as above. `page_url` is checked whether or
+not the site is built; routing meta values follow the same built-output
+deferral as `routing_meta.runtime_root`.
+
 This prevents mixed-source manifests such as `checkout/index.html` from leaking producer folder structure into `src/<slug>/checkout/index.html`. Campaigns OS owns the Adapter from source/manifest/CampaignSpec into Page Kit shape; Page Kit remains the target.
 
 `target_path` intentionally uses the terminal route segment (`checkout/step-1/`
@@ -1415,10 +1575,49 @@ The motion:
 
 ```text
 agent calls `next` → gets { stage, prompt, picked_reason } → does the work →
-updates assembly report's stages.<name>.status → calls `next` again →
-repeat until stage="done"
+records it (`campaigns-os record setup|build|polish`; deploy and QA record their
+own stages) → calls `next` again → repeat until stage="done"
 ```
 
+### Recording stage completion
+
+Setup, build and polish completion is recorded with one command each, never by
+hand-editing `.campaign-runtime/` JSON:
+
+| Command | Writes | Refused (nothing written) when |
+|---|---|---|
+| `campaigns-os record setup --packet <p>` | Build Context `scaffold.required=false` (`handoff_skill` next-campaigns-build) and `stages.setup` completed | the campaign output directory (`assembly.output_dir`) does not exist, or there is no Build Context or Assembly Report |
+| `campaigns-os record build --packet <p>` | `stages.assembly` completed with `build_fingerprint` = doctor's `derived.build_output_fingerprint.value`, `source_package_material_fingerprint` = the report's Design Source Package material fingerprint when present, and `stages.polish` reset to `required` (`required_by` build, `required_for` qa) unless its evidence is bound to this exact output | doctor cannot compute the fingerprint (no `_site/<public_route_slug>/`), setup is still required, or `stages.setup` is not terminal |
+| `campaigns-os record polish --packet <p> --evidence <file>` | `stages.polish` from the file (`docs/polish-evidence.md` §7: completed, blocked or skipped), bound to doctor's current fingerprint; `report.theme.repair_loop_defect` when the file sets it | build is not recorded for the current output, the file has a shape error (named by field), or, for a completed status, the polish gate doctor evaluates would not pass on the result |
+
+Each command also refuses a stage `next` has not reached: while doctor's
+prepare-build gate is set (`next` answers prepare-build) or while an earlier
+stage in the order below is not terminal.
+
+Each command reads the same packet, Build Context and Assembly Report `next`
+reads (`--context` / `--report` override them the same way), validates what it
+would write against `schemas/campaign-runtime-build-context.v0.schema.json` and
+`schemas/campaign-runtime-assembly-report.v0.schema.json` plus doctor's report
+checks, and then writes under the target lock, stamping any retained doctor
+output stale. The packet is read once first, only to name the target lock, and
+re-read and re-checked under it: which report the Build Context binds, the
+report itself, the Build Context and doctor's reading (the fingerprint and the
+binding) are all read inside the same target lock as the write, and the
+fingerprint is computed once more just before the write; output
+that changed in between is refused, never recorded with the old value. Every
+command refuses a report that is not bound to the packet: whenever doctor's
+prepare-build binding gate fails (`next.prepare_build.context_missing`,
+`context_packet_mismatch`, `context_dsp_mismatch`, `context_report_missing`,
+`report_packet_mismatch`, `report_context_mismatch`, `report_campaign_mismatch`
+or `report_dsp_mismatch`, the refusals `next` answers with prepare-build), and
+whenever the report's campaign identity does not match the packet, including
+for packets with no Design Source Package. Every command also adds
+`recorded_by`, and `completed_at` unless it records a blocked Polish, to the
+stage it records. `--dry-run` runs every check, takes no lock and writes nothing. A failed
+check exits non-zero with the problems listed, one per line. Re-run `record
+build` after every page-kit build; a rebuild that changes the output needs
+`polish capture` and `record polish` again.
+
 Stage order: `setup → build → polish → deploy → qa`. The picker walks this list and returns the first stage whose recorded status isn't terminal (`completed`, `completed_with_warnings`, `skipped`). During Polish, install the package-owned browser first, then run `campaigns-os polish capture` against the served current build before recording a terminal `stages.polish.status` or proceeding to deploy/QA; the producer attaches package-owned `visual_review.page_load` evidence and never marks the stage complete itself.
 
 | Stage | Report key | Owner |
@@ -1461,8 +1660,8 @@ The legacy form `campaigns-os next <stage>` (e.g. `next build`) still works and
 
 CampaignSpec pages may carry an optional `design_source` block on `Page` — a pointer to the design artifact (Figma file + per-breakpoint selection URLs) that supplies prepared HTML for that page. When doctor detects an active spec page with no source mapping, the `source_html.pages.coverage` error now carries a hint that points the operator at the design source:
 
-- `design_source.type === "figma"` with `file_url`: doctor calls out the Figma file and the figma-sections-export handoff command (`npm run handoff -- <slug>`).
+- `design_source.type === "figma"` with `file_url`: doctor calls out the Figma file and says the Figma provenance gate (`source_html.producer_provenance`) needs the figma-sections-export handoff manifest (`npm run handoff -- <slug>`); a hand-written manifest cannot pass that gate.
 - `design_source` set without `file_url`: doctor flags the missing `file_url` so the spec can be corrected.
-- `design_source` unset: doctor keeps the original generic coverage error.
+- `design_source` unset, `ai-generated`, or another producer type: the message names the manifest path (`<source-root>/.campaigns-os/source-html-manifest.json`), the schema, and a minimal page entry to write by hand (no exporter is needed), plus `"wrapper_policy": "preserve_document_wrappers"` for standalone documents kept whole. When any active page's `design_source` is Figma, it instead says the manifest must pass the Figma provenance gate.
 
 The error code (`source_html.pages.coverage`) is unchanged so existing doctor consumers do not need to be updated; only the human-readable `message` and an optional `detail.design_source` payload are added.

package/docs/campaigns-os-build-flow.md

@@ -83,9 +83,10 @@ the assembly report.
 - Landing and presell pages should preserve prepared HTML when it is a real standalone design. Use page-kit passthrough structure, inject the SDK/config requirements, and repoint CTAs into the CampaignSpec flow.
 - **Pre-checkout pages must ship the same SDK bootstrap as the checkout layout.** Presell and landing pages are SDK `page_type: product`; they need `config.js` (before the loader), the `campaign-cart@v{sdk_version}/dist/loader.js` module script, and the `next-funnel` + `next-page-type` meta tags — not just inert `data-next-*` attributes. Without the loader the SDK silently no-ops: `data-next-hide` conditional visibility (`param.banner` / `param.seen`), `utmTransfer` UTM/query carry-through to checkout (top-of-funnel ad attribution), and SDK analytics never fire. Treat `param.banner` / `param.seen` visibility and `utmTransfer` as standard pre-checkout wiring, not per-campaign discoveries. Doctor enforces this with `built_output.pre_checkout_sdk_bootstrap`.
 - **Every page names the same campaign.** A page borrowed from another funnel (a copied upsell or receipt) must not keep the other campaign's `next-api-key` / `config.js` API key, `next-funnel` meta, or `setAttribution({ funnel })` call; the SDK reads these per page and reconciles nothing, so the order lands on or attributes to the wrong campaign with no visible error. Doctor blocks this, unwaivably, with `built_output.campaign_identity` (one error per drift, naming both files and both values).
-- **SDK markup must do what it says.** `data-next-checkout` goes on the `<form>`; `data-next-checkout-field` values are the SDK's fixed names (`fname`, `lname`, `postal` — never `firstName`, `lastName`, `zip`); an `add-to-cart` button linked by `data-next-selector-id` needs a selector with that id and that selector in `select` mode (swap mode plus the button writes the cart twice); one default-selected card per selector; single-brace tokens inside SDK templates. Doctor enforces the first four as blockers and the last two as warnings under `built_output.sdk_markup` (codes `SWAP_WITH_ADD_TO_CART`, `CHECKOUT_NOT_FORM`, `WRONG_FIELD_NAME`, `MISSING_SELECTOR_ID_MATCH`, `DOUBLE_SELECTED`, `TEMPLATE_DOUBLE_BRACE`).
+- **SDK markup must do what it says.** `data-next-checkout` goes on the `<form>`; `data-next-checkout-field` values are the SDK's fixed names (`fname`, `lname`, `postal` — never `firstName`, `lastName`, `zip`); an `add-to-cart` button linked by `data-next-selector-id` needs a selector with that id and that selector in `select` mode (swap mode plus the button writes the cart twice); every `data-next-upsell-action` sits inside its `data-next-upsell` container, on any page type; one default-selected card per selector; single-brace tokens inside SDK templates. Doctor enforces the first five as blockers and the last two as warnings under `built_output.sdk_markup` (codes `SWAP_WITH_ADD_TO_CART`, `CHECKOUT_NOT_FORM`, `WRONG_FIELD_NAME`, `MISSING_SELECTOR_ID_MATCH`, `ORPHANED_UPSELL_ACTION`, `DOUBLE_SELECTED`, `TEMPLATE_DOUBLE_BRACE`).
+- **Campaign scripts must parse.** A hand-edited script with a stray or missing bracket throws a `SyntaxError` on every page that loads it, and nothing in it runs. Doctor parses every campaign-owned `.js` file a built page loads by a local `<script src>` and blocks, unwaivably, with `built_output.script_syntax.parse_failure`, naming the file, line and column.
 - Checkout, upsell, downsell, and receipt pages should preserve starter-template SDK contracts while keeping the campaign/source visual language. Treat starter templates as the reference for required `data-next-*` controls and wiring, not as a mandate to carry their visual chrome into the final campaign.
-- If source HTML declares SDK-owned zones such as `data-commerce-zone="checkout-form"` or `data-commerce-zone="order-summary"`, adopt the selected starter-template family shell for that runtime page. Do not build a custom checkout/upsell structure around a few borrowed includes; browser QA will check declared family structure where `agentContract.qaStructure` exists.
+- If source HTML declares SDK-owned zones such as `data-commerce-zone="checkout-form"` or `data-commerce-zone="order-summary"`, keep the selected starter-template family's SDK wiring for that zone (the checkout form, bound fields, payment submit and cart summary). The wrapper and page composition around it stay source-owned; do not add family class names to the campaign's own layout to satisfy QA.
 - If `context.theme` names a generated `brand-theme.css`, copy it into campaign assets and load it after `next-core.css` on checkout, upsell, downsell, and receipt pages. Generated brand-theme v0 is root-variable-only; do not use it as permission to edit SDK-owned selectors or runtime structure.
 - Buy-more-save-more selectors should use selected quantity plus Offer-aware price displays. Do not swap in stale package-per-tier IDs unless the CampaignSpec explicitly represents an older campaign that still owns separate packages for each option.
 - SDK routing meta tags should be emitted as campaign-root paths, for example `/campaign-slug/upsell/`, even when the CampaignSpec source value is slug-relative like `upsell/`.
@@ -94,7 +95,7 @@ the assembly report.
 - Any source element dropped because the spec does not support it, such as PayPal when `available_payment_methods` excludes PayPal, should be recorded in the assembly report for polish.
 - After page-kit build, doctor checks rendered local script references plus rendered package and shipping refs against the CampaignSpec. Missing built scripts, stale package IDs, stale shipping IDs, and unavailable package refs must be fixed or intentionally blocked before QA.
 - Browser QA opens SDK-owned runtime pages once as a shopper and once with `?debugger=true`. The debugger pass should prove the Campaign Cart debugger overlay and selector controls mount without changing the normal checkout/test-order flow.
-- Browser QA also checks template-family commerce structure when the family contract declares machine-checkable selectors. Missing required Limos checkout shell markers, for example, are treated as a warning-severity failure: the checkout may load, but it is not proven as a conformant Limos checkout.
+- Browser QA also checks template-family commerce structure when the family contract declares machine-checkable selectors. It checks what the checkout does, not family class names: a missing family shell selector (a wrapper or column class, or the shipping field row marker) is a warning when the checkout form, its bound fields and a visible total all pass, and a failure when any of them does not. A missing SDK selector is always a warning-severity failure. See [QA and test orders](qa-and-test-orders.md).
 
 ## Synthetic Campaigns
 

package/docs/design-source-package.md

@@ -335,14 +335,80 @@ If any current campaign, active/mapped page, source material, manifest or crawl
 provenance, coverage, template family/reference, material fingerprint,
 readiness, or readback check fails, `prepare-build` refuses. It leaves the
 existing package and packet/context/report/brief sidecars byte-identical. It
-does not silently regenerate or overwrite the package; source preparation must
-reconcile the package and its references explicitly before retrying.
+does not silently regenerate or overwrite the package. The refusal names the
+package file and says which recovery applies:
+
+- **A package `prepare-build` synthesized itself.** The Assembly Report's
+  `design_source_package` reference records `origin`: `"synthesized"` when
+  `prepare-build` wrote the package bytes (or reused bytes it had written), and
+  `"adopted"` when it validated and reused a package it did not write. When the
+  previous report at this run's report path says `"synthesized"` and the
+  package bytes still hash to that report's `sha256`, the stale package is the
+  producer's own output: rerun with `--force` and `prepare-build` regenerates
+  it from the current inputs (mode `regenerated`), announcing the replacement
+  on stderr. `--force` also resets any stage evidence the Assembly Report
+  carries, exactly as it does for the report alone.
+- **Any other package** — placed by an operator, edited by hand after it was
+  written, adopted by an earlier run, or recorded by a report that predates
+  `origin` — is never overwritten, `--force` or not. Reconcile it with the
+  current inputs, or, if no downstream stage has consumed it, delete it and
+  rerun so `prepare-build` synthesizes a fresh one.
+
+Only the Assembly Report carries `origin`; the packet and context references
+keep their four strict fields.
+
+The package is published before the report that records it. So that a run
+which fails or dies between the two does not leave its own package unprovable,
+`prepare-build` first writes a pending provenance record beside the package
+(`.campaign-runtime/input/.design-source-package.json.pending-provenance.json`)
+naming the sha256 of the bytes it is about to publish, and removes it once the
+Assembly Report is written. A `--force` run that replaces a stale package it
+proved its own keeps that package's sha256 in the record too, so a
+regeneration that fails or dies part way leaves whichever package is on disk
+provable. A run that finds another writer's package at the path and adopts it
+instead of publishing drops its own candidate from the record. A retry that
+finds the record treats a package whose bytes still hash to one of its entries
+as `"synthesized"`, exactly as if the report had recorded it; bytes changed
+since are not vouched for, and a malformed record vouches for nothing. Just
+before the report is published the record is narrowed to what the report
+records (the package's hash when synthesized, nothing when adopted), so no
+unpublished candidate outlives the report. The record's path is
+reserved like the other outputs, so no configurable output may point at it.
+
+Runs against the same target take turns. From the stage-evidence check and
+the reading of its inputs (CampaignSpec, source manifest, page mappings, asset
+crawl) through the packet, context and report that record them,
+`prepare-build` holds a lock directory beside the package
+(`.campaign-runtime/input/.design-source-package.json.lock`), so each run judges
+provenance against the report and package the previous run left, and records
+the inputs it actually read. With `--map-id`, the fetched spec is written to the
+shared `fetched-specs/` cache file inside the same lock, so a run waiting for
+the lock cannot replace the spec the lock holder is reading. The source-html
+manifest is read once: the `manifest_sha256` the package records is the hash of
+the exact bytes source intake parsed. Every command that edits the Assembly Report
+(`doctor`, `qa run`, waivers, the polish merge and the other stage producers)
+takes the same lock for its read-modify-write, so no stage evidence lands
+between `prepare-build`'s final stage-evidence check and its publication; a
+producer that `prepare-build` reaches from inside its own run enters directly.
+Of several concurrent `--force` runs, the first regenerates the package and the
+rest reuse it as `"synthesized"`. A command that finds the lock held waits up to
+a minute. The lock directory and its owner record appear together, so a lock
+left by a process that died is recovered automatically, and a lock directory
+without an owner record (only an older release leaves one) is never taken
+over: the command refuses it after about a second and names it. Confirm no
+campaigns-os process is working on the target, then remove it. Do not run an
+older Campaigns OS release against the same target at the same time. A
+waiver's `--dry-run` preview takes no lock.
 
 Before writing any output, `prepare-build` also requires distinct paths for the
 Build Packet, Build Context, Assembly Report, Doctor output, normalized Build
 Brief, and fixed Design Source Package. Equal paths and filesystem aliases are
 rejected, including symlinks, hard links, dangling leaf symlinks, and symlinked
-parent directories.
+parent directories. No output may be placed inside the lock directory, or
+inside the staging and tomb directories the lock creates beside it
+(`.lock.staging-*`, `.lock.recovery-staging-*`, `.lock.released-*`,
+`.lock.abandoned-*`), directly or through a directory alias: they are removed
+with their contents when the run finishes.
 
 This behavior is the implemented v0 compatibility boundary. It does not promise
 that a separate future workflow command will generate, repair, approve, or
@@ -504,10 +570,12 @@ Either declaration records the page on the assembly report's
 `template_family` set to the family the packet locks, lists it under
 `stages.prepare_build.declared_out_of_scope`, and reaches
 `stages.prepare_build.status: "completed_partial"`. Intake demands no design
-source for the page: no `capture-*` TODO, no `link-*` TODO. The build stage
-materialises it from the locked family's own page of that role — the `next
-build` prompt names every template-stock page and the family to copy it from —
-and the family decides only *how* the package records its coverage:
+source for the page: no `capture-*` TODO, no `link-*` TODO. This source-scope
+classification does **not** authorize publishing a stock page. `next build`
+keeps these routes unbuilt by default and requires explicit operator opt-in
+per page before materializing a stand-in from the locked family. In particular,
+presell and landing pages staying on another host must not be replaced with
+placeholder copy. The family decides only *how* intake records coverage:
 
 - **A family that publishes complete Template Reference proof — today `apollo`
   alone** — covers the page with synthesized `template_baseline` coverage from
@@ -533,10 +601,10 @@ not built yet`, and keeps checkout launch and test-order proof blocked while a
 runtime page (`select`, `checkout`, `upsell`, `receipt`) is among them. You get
 a terminal, honest intake — not a fully proven campaign.
 
-The build stage lifts those limits page by page. `next-campaigns-build`
-materialises each template-stock page from the locked family's own page of
-that role (the pre-checkout `select` step first, because it seeds the cart the
-runtime pages read). Once the page's built HTML exists at its route under
+The build stage lifts those limits page by page for opted-in pages. It uses
+the locked family's own page of that role (an opted-in pre-checkout `select`
+stand-in first, because it seeds the cart the runtime pages read).
+Once the page's built HTML exists at its route under
 `_site/<slug>/`, doctor reads the `template_stock` marker on the scope decision
 and counts the page as built: it moves into `derived.scope.built_pages` (with
 `template_stock: true`, `template_family`, and no `source_path`), joins the
@@ -565,10 +633,10 @@ family the `template-baseline` contribution's `presentation_intent` names.
 
 ### Recovery after a blocked first run
 
-A blocked run still emits the package, and `prepare-build` never refreshes a
-package it did not just create. So a first run that blocked leaves a package
-whose provenance names the *old* manifest, and simply rerunning with a new
-manifest fails closed:
+A blocked run still emits the package, and a plain `prepare-build` never
+refreshes a package it did not just create. So a first run that blocked leaves a
+package whose provenance names the *old* manifest, and simply rerunning with a
+new manifest fails closed:
 
 ```
 campaigns-os: Design Source Package at <target>/.campaign-runtime/input/design-source-package.json
@@ -597,6 +665,12 @@ npm run campaigns-os -- start \
   --template-family <family>
 ```
 
+When the refusal says the package was synthesized by an earlier
+`prepare-build` and is unchanged since, skip step 2 and add `--force` to step 3
+instead: `prepare-build` (and `start` and `build`, which run the same intake)
+then regenerates the package itself. `--force` resets any stage evidence the
+Assembly Report carries, so the same caution applies.
+
 Step 2 is only ever correct for a package emitted by a blocked run that no
 downstream stage has consumed. Once Build or Polish has bound its evidence to a
 package fingerprint, deleting it invalidates that evidence; reconcile through
@@ -654,6 +728,79 @@ the packet file, so a packet resolves its source from the location it was
 written at: replay a run from the same place, or expect doctor to report
 `source_html.root` as missing.
 
+### Hand-written HTML behind a Figma design source
+
+A saved Map page with `design_source.type: figma` (or a `figma.com` file URL)
+makes doctor demand figma-sections-export provenance from the source-html
+manifest: a semantic `producer_provenance` block, section exports, a
+material fingerprint, and the export's section partials and assets in
+`files[]`. When the approved source for that page is hand-written HTML and the
+Figma file only renders it, no export exists, and doctor reports the
+`source_html.producer_provenance*`, `source_html.files.partial` and
+`source_html.files.asset` errors. Leave `design_source` on the Map and take
+this route instead:
+
+1. Write the source-html manifest by hand (the record shape and the
+   `screenshots[]` proof are above). Give each page its `page_id` and `path`
+   and its desktop and mobile screenshot records, and list the page files in
+   `files[]` with `role: "page"`. Do not add `partial` or `asset` entries the
+   HTML does not have: the waiver covers their absence. Set `generator` to
+   the tool or person that wrote the HTML, never to `figma-sections-export`.
+2. If the HTML files are full documents (`<!doctype>`, `<html>`, `<head>`,
+   `<body>`), set `"wrapper_policy": "preserve_document_wrappers"` in the
+   manifest so the wrapper finding is a recorded decision, not a blocker (see
+   [docs/source-adapters.md](./source-adapters.md#selecting-the-wrapper-policy-at-intake)).
+3. Record a named-human waiver for each such page:
+
+   ```bash
+   campaigns-os checkpoint waive \
+     --packet campaign-runtime.build.json \
+     --gate source_html.producer_provenance \
+     --page <page_id> \
+     --reason "<why the approved source is hand-written HTML>" \
+     --waived-by "<named human>" \
+     --expires-at <ISO timestamp>
+   ```
+
+   `--page` is required, and it must name an active CampaignSpec page with a
+   Figma design source; any other id is refused and the refusal lists the pages
+   that qualify. The `<gate>:<page_id>` spelling is refused too. As with every
+   `checkpoint waive` gate, a placeholder name is refused, one bound
+   (`--expires-at` or `--review-condition`) is required, and `--dry-run`
+   validates the waiver and writes nothing. A value-taking flag given without
+   a value is refused, never read as the text `true`.
+
+Doctor reports the Figma-export findings (the `source_html.producer_provenance*`
+codes, `source_html.files.partial` and `source_html.files.asset`) once for each
+Figma-typed page, with the page in `detail.page_id`. While a page's waiver is
+active, its findings are reported as warnings carrying `waived: true`, its
+checkpoint gate reports `waived`, and doctor and `next` report
+`ready_with_waivers`, never clean. A waiver covers only its own page: another
+Figma-typed page without one still gets the findings as errors, and doctor
+stays blocked.
+
+When the manifest's `generator` names `figma-sections-export` in any form
+(with or without an `@<version>`, in any case), the manifest claims to be a
+real export, so the missing provenance is the export's own defect: doctor
+reports the findings once, manifest-wide, as errors, and each page's
+checkpoint gate reports `blocked` with the code
+`source_html.producer_provenance.exporter_claim` and the repair action.
+`checkpoint waive` refuses the gate in that state, and a waiver recorded
+before the generator changed is reported as inert.
+
+The waiver covers the Figma-export findings only. Manifest validation, the
+wrapper policy, source-preparation findings, page mappings and the screenshot
+proof at `prepare-build` keep their own severity.
+
+The waiver is recorded against the page's exact state: its design source and
+the provenance findings doctor reported when it was recorded. A change to either
+makes it stale, an expired waiver no longer applies, and doctor blocks again. A
+waiver for a page that no longer has a Figma design source (its `design_source`
+changed, or it left the spec), or one under a manifest whose generator claims
+figma-sections-export, is reported as
+`source_html.producer_provenance.waiver_inert`, a warning, like the other
+checkpoint gates' inert waiver history.
+
 ## Lifecycle ownership and freshness
 
 Prepare owns source normalization and the three package references. It records