@nextcommerce/campaigns-os 1.52.0 → 1.53.0

package/contracts/release-ledger.json

@@ -5870,6 +5870,333 @@
         }
       ],
       "entry_sha256": "e9063da2788630cb0017eedc0b2e77b717b290bae0e7cb5d6bcdbbb6e6b7368e"
+    },
+    {
+      "id": "RL-0233",
+      "sequence": 225,
+      "date": "2026-10-05",
+      "kind": "release",
+      "surface_version": "1.53.0",
+      "changelog_section": "1.53.0",
+      "changelog_sha256": "b5e6bbfd3ab22a16b715fbd574128715ab5a9a70d76c1e09f8f91c1d25ce72f6",
+      "agent_impact": "Surface 1.53.0. Adds record brief, which saves Campaign Build Brief answers without re-running intake, and record spec, which binds a CampaignSpec change without discarding operator state; their --dry-run forms write nothing and append no lifecycle entry. A brief file is guided unless it sets \"brief_mode\": \"prepared\" (a campaign whose report already records a prepared brief stays prepared). An unchanged or reformatted save keeps every stage's evidence and status. A material brief or CampaignSpec change makes build, Polish and QA owed again (QA alone for a qa_policy change), keeps the last five superseded records per stage as history that is never current proof, and next, doctor, progress, readback and the Assembly Report status report the owed stage; next offers refresh_inputs (record brief or record spec) when a recorded stage was made against earlier content. Build, Polish and QA records now stamp the brief and CampaignSpec content they were made against; records without stamps read unconfirmed. Re-recording an unchanged build after an input change keeps the build owed unless the operator's --deviation-reason records that the change needs no output change; Polish stays owed until a new capture postdates the change. Intake refuses, without --force, to discard recorded waivers, warning accepts, stage history, an applied theme, or a recorded deploy target, preview URL, production URL, order-path depth or allowed-domains confirmation; --force archives the build, Polish and QA records it clears and keeps stage history. spec derive no longer rebinds report identity and its --json result no longer carries rebound; run record spec after it. Bundled skills carry revision 1.53.0+skills.1: an agent that loaded an earlier revision should start a fresh session. Install the 1.53.0 package with the documented local setup command.",
+      "compatibility": "breaking",
+      "migration": "After upgrading, next routes each in-flight campaign back to build once, because build, Polish and QA records made before 1.53.0 do not record which brief and CampaignSpec content they used: re-record build and Polish, and run QA again for a new verdict. Add \"brief_mode\": \"prepared\" to a hand-written brief file whose open questions should block. Save brief answers with record brief and CampaignSpec changes with record spec instead of re-running start, prepare-build or build, which now refuse without --force to discard recorded waivers, warning accepts, stage history, an applied theme, or a recorded deploy target, preview URL, production URL, order-path depth or allowed-domains confirmation. Run record spec after spec derive, and stop reading rebound from spec derive --json.",
+      "changes": [
+        {
+          "class": "compatibility_policy",
+          "path": "compatibility.json",
+          "surface_entry": null,
+          "summary": "Advance the declared version to 1.53.0."
+        },
+        {
+          "class": "compatibility_policy",
+          "path": "contracts/effects.v1.json",
+          "surface_entry": "contracts/effects.v1.json",
+          "summary": "Declare the record brief and record spec rows (tier C) and their --dry-run rows (tier none); correct the start, prepare-build and build notes (refused without --force when the report carries stage evidence, stage history or operator decisions) and their --force notes (completed build, Polish and QA records are archived into stage history, which is kept); state that record build writes input_change and makes Polish and QA owed when it detects a brief or CampaignSpec change; and state that record polish, record theme and record deploy are refused while an earlier stage is owed again."
+        },
+        {
+          "class": "compatibility_policy",
+          "path": "contracts/supported-surface.json",
+          "surface_entry": "contracts/supported-surface.json",
+          "summary": "Advance surface_version to 1.53.0 and record the effects contract hash."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/build-packet.md",
+          "surface_entry": "docs/build-packet.md",
+          "summary": "Describe CampaignSpec material changes for local-spec, saved-Map and gateway packets, record spec, spec derive no longer rebinding identity, and the brief and CampaignSpec dependency map."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/campaign-build-brief.md",
+          "surface_entry": "docs/campaign-build-brief.md",
+          "summary": "Replace Answering The Questions with saving answers through record brief, the brief_mode rule, which changes make which stages owed again, stage history, --deviation-reason, and the one-time re-proof of records made before 1.53.0."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/effects.md",
+          "surface_entry": "docs/effects.md",
+          "summary": "Describe what record brief and record spec write and refuse, their dry runs, and the intake refusal and --force archive."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/local-setup.md",
+          "surface_entry": "docs/local-setup.md",
+          "summary": "Pin the 1.53.0 package in the local setup install command."
+        },
+        {
+          "class": "documentation",
+          "path": "docs/orientation-contract-reference.md",
+          "surface_entry": "docs/orientation-contract-reference.md",
+          "summary": "Regenerate at surface 1.53.0."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/progress-snapshots.md",
+          "surface_entry": "docs/progress-snapshots.md",
+          "summary": "Stage records carry each stage's effective status: a stage owed again by a brief or CampaignSpec change reads required, and one whose inputs cannot be confirmed reads unknown."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/readback.md",
+          "surface_entry": "docs/readback.md",
+          "summary": "The STAGES header prints the recorded and the effective report status, and a stage line whose effective status differs adds the recorded status and the reason."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/runtime-readiness.md",
+          "surface_entry": "docs/runtime-readiness.md",
+          "summary": "Regenerate at surface 1.53.0."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/skills-revision.md",
+          "surface_entry": "docs/skills-revision.md",
+          "summary": "Use the current 1.53.0+skills.1 bundle in executable examples."
+        },
+        {
+          "class": "generated_runtime",
+          "path": "package-lock.json",
+          "surface_entry": null,
+          "summary": "Advance the package version to 1.53.0."
+        },
+        {
+          "class": "package_export",
+          "path": "package.json",
+          "surface_entry": null,
+          "summary": "Advance the package version to 1.53.0."
+        },
+        {
+          "class": "skill",
+          "path": "skills.json",
+          "surface_entry": "skills.json",
+          "summary": "Advance the bundled skill revision to 1.53.0+skills.1 and each skill version one patch."
+        },
+        {
+          "class": "skill",
+          "path": "skills/campaign-lifecycle-orientation/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.53.0+skills.1 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/campaign-readback-classification/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.53.0+skills.1 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/campaign-run-evidence/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.53.0+skills.1 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/contribution-intake/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.53.0+skills.1 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-build/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.53.0+skills.1 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-os-setup/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.53.0+skills.1 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-os/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.53.0+skills.1 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-polish/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.53.0+skills.1 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-qa/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.53.0+skills.1 bundle revision."
+        },
+        {
+          "class": "cli_surface",
+          "path": "src/cli.mjs",
+          "surface_entry": "record",
+          "summary": "Add record brief and record spec to the usage text; intake binds the brief material and refuses to discard operator state without --force; QA records stamp their inputs; next carries input_currency, offers refresh_inputs and notes an operator's unchanged-output decision in the QC handoff; spec derive no longer rebinds report identity, drops the rebound result field and names record spec."
+        },
+        {
+          "class": "cli_surface",
+          "path": "src/doctor/checks.mjs",
+          "surface_entry": "doctor",
+          "summary": "Doctor reports input currency in derived.input_currency and warns spec.material_stale, spec.binding_unknown, build_brief.material_changed, build_brief.binding_unknown, build_brief.input_unsaved, assembly.output_unchanged_after_input_change and assembly.output_unchanged_by_operator_decision; a normalized brief that is not valid JSON, or not a JSON object, is the build_brief.normalized_path error, not a crash."
+        },
+        {
+          "class": "cli_surface",
+          "path": "src/doctor/next-step.mjs",
+          "surface_entry": "next",
+          "summary": "The stage picker reads each stage's effective status, so a stage owed again by a brief or CampaignSpec change, or one whose inputs cannot be confirmed, is the stage next recommends."
+        }
+      ],
+      "entry_sha256": "85e37bd6392dcfa8415a654897eb8dbe8ab417fc9c92ec21732d2fff5a5f5f5b"
+    },
+    {
+      "id": "RL-0234",
+      "sequence": 226,
+      "date": "2026-10-05",
+      "kind": "release",
+      "surface_version": null,
+      "changelog_section": "1.53.0+agent.1",
+      "changelog_sha256": "b865a430b924ff48016930621ba3905deb7861516d9dfdabfd797ed5aaebf6db",
+      "agent_impact": "polish capture now measures text readability on every built page at desktop and mobile widths and attaches it as stages.polish.evidence.visual_review.readability; next lists readability.contrast warnings, review and coverage results in its QC handoff, grouping each warning colour pair across pages and widths for one checkpoint accept. On a campaign whose every mapped page is template stock, polish capture measures readability, prints the page-load no_capturable_routes message as a warning, and exits 0 with status captured_with_warnings; record polish still refuses a completed Polish record there. Polish media weight and readability results read as stale when doctor reports the built output changed since record build. Readability results never block Polish or change readiness. QA's browser-primary-cta check now runs on every page with an expected_next_url, whatever its page type, and measures every visible route-matching CTA (not only the most readable one) and each piece of text inside it, unrounded, with the same measurement Polish uses, against the requirement for its own size; its evidence lists each candidate's elements[] with contrast_ratio_exact and required_ratio. A CTA observed incompletely (the SDK, stylesheets, fonts or its text not ready, a review trigger, text generated by ::before or ::after, or disabled controls) reads manual_review at severity warn, never pass, and so does a page whose inspection script errors (inspection_error, earlier a fail). So browser-primary-cta results on existing campaigns can change in either direction: pages that were skipped are now checked, a second CTA or child text can now fail, large bold text at 3:1 can now pass, and incomplete observations read manual_review instead of pass or fail. The brand theme generator compares contrast unrounded, so a declared colour in [4.495, 4.5) now adds theme.foreground.low_contrast; generated CSS and colour choices are unchanged.",
+      "compatibility": "additive",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "cli_surface",
+          "path": "src/cli.mjs",
+          "surface_entry": "polish",
+          "summary": "polish capture attaches the readability record beside page_load (which now carries captured_at), and on a campaign with no mapped pages measures readability only, reports the held page-load message as a warning and exits 0."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/qa-and-test-orders.md",
+          "surface_entry": "docs/qa-and-test-orders.md",
+          "summary": "Describe accepting a readability warning: one colour pair and size class per page and width, what orphans or lapses the accept, and that it never hides review, unexercised or excluded results."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/brand-theme-bridge.md",
+          "surface_entry": "docs/brand-theme-bridge.md",
+          "summary": "State that theme contrast uses the same unrounded measurement as Polish and QA, so a declared colour at 4.495:1 now warns, and that the generator's colour choices are unchanged."
+        }
+      ],
+      "entry_sha256": "b75e489a53ea7b60a3a9b3037f6f17c96b13c2960a1cbd34eb7a3cc69b54f617"
+    },
+    {
+      "id": "RL-0235",
+      "sequence": 227,
+      "date": "2026-10-05",
+      "kind": "release",
+      "surface_version": null,
+      "changelog_section": "1.53.0+agent.2",
+      "changelog_sha256": "a7fc7d90ee83e6ad44d310d77942e00de56656259e9c754eec14cd5bd8d124d4",
+      "agent_impact": "next prints a campaign intent summary, generated from the normalized Campaign Build Brief, on every result (intent_summary in JSON, a Campaign intent section in text) and at the top of the setup, build, Polish and QA prompts. Each value carries its origin (stated, from the source, default, not stated, or source not recorded); values are quoted data, purpose and palette source inferred from page types or names read not stated, and nothing reads the summary, so it never sets prices or commerce behaviour. The four agent context files and the setup, build, Polish and QA skills tell agents to read .campaign-runtime/input/campaign-build-brief.normalized.json and the recorded assembly decisions. Bundled skills carry revision 1.53.0+skills.2: an agent that loaded an earlier revision should start a fresh session. The lifecycle skill returns the single compact brief in references/session-intake.md (Intent: is now Work:, with a new Campaign: field and Proof policy:) and saves brief answers with record brief after asking the operator; the build skill passes --deviation-reason only on the operator's explicit decision, the Polish skill records a skipped Polish only on the operator's decision, and the Polish and QA skills report readability warnings and offer repairs inside the brand palette. tooling setup refuses an installed agent context from an earlier release and names install-agent-context --target . in its refusal.",
+      "compatibility": "breaking",
+      "migration": "From each existing campaign folder: install the exact 1.53.0 package, run npx --no-install campaigns-os install-agent-context --target . (it overwrites all four files under .campaign-runtime/agent-context/; local edits there are lost), review and commit the diff, rerun npx --no-install campaigns-os tooling setup --target . --platform claude, and restart the agent session. Codex, Cursor and Copilot users run install-agent-context and reinstall skills with install-skills --platform codex (or agents).",
+      "changes": [
+        {
+          "class": "documentation",
+          "path": "agents/claude/CLAUDE.md",
+          "surface_entry": "agents/claude/CLAUDE.md",
+          "summary": "Add the generic campaign paragraph: what a NEXT campaign is, who owns creative intent and commerce behaviour, read the normalized brief and the recorded decisions before changing a campaign, treat the intent summary as orientation only, and ask the operator before saving brief answers."
+        },
+        {
+          "class": "documentation",
+          "path": "agents/codex/AGENTS.md",
+          "surface_entry": "agents/codex/AGENTS.md",
+          "summary": "Add the generic campaign paragraph: what a NEXT campaign is, who owns creative intent and commerce behaviour, read the normalized brief and the recorded decisions before changing a campaign, treat the intent summary as orientation only, and ask the operator before saving brief answers."
+        },
+        {
+          "class": "documentation",
+          "path": "agents/copilot/copilot-instructions.md",
+          "surface_entry": "agents/copilot/copilot-instructions.md",
+          "summary": "Add the generic campaign paragraph: what a NEXT campaign is, who owns creative intent and commerce behaviour, read the normalized brief and the recorded decisions before changing a campaign, treat the intent summary as orientation only, and ask the operator before saving brief answers."
+        },
+        {
+          "class": "documentation",
+          "path": "agents/cursor/campaigns-os.mdc",
+          "surface_entry": "agents/cursor/campaigns-os.mdc",
+          "summary": "Add the generic campaign paragraph: what a NEXT campaign is, who owns creative intent and commerce behaviour, read the normalized brief and the recorded decisions before changing a campaign, treat the intent summary as orientation only, and ask the operator before saving brief answers."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/skills-revision.md",
+          "surface_entry": "docs/skills-revision.md",
+          "summary": "Use the current 1.53.0+skills.2 bundle in executable examples."
+        },
+        {
+          "class": "skill",
+          "path": "skills.json",
+          "surface_entry": "skills.json",
+          "summary": "Advance the bundled skill revision to 1.53.0+skills.2 and each skill version one patch."
+        },
+        {
+          "class": "skill",
+          "path": "skills/campaign-lifecycle-orientation/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.53.0+skills.2 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/campaign-readback-classification/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.53.0+skills.2 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/campaign-run-evidence/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.53.0+skills.2 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/contribution-intake/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.53.0+skills.2 bundle revision."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-build/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.53.0+skills.2 bundle revision; read the normalized brief and the recorded decisions; rebuild after an input change and pass --deviation-reason to record build only on the operator's explicit decision, quoting their reason."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-os-setup/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.53.0+skills.2 bundle revision; read the normalized brief and the recorded decisions."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-os/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.53.0+skills.2 bundle revision; return the compact brief defined in references/session-intake.md instead of a second copy, rename the Intent and Proof depth fields to Work and Proof policy, save brief answers with record brief after asking the operator, and declare a detour with --deviation-reason only when the operator has decided on it in the conversation, quoting their reason, including on record build after an input change."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-os/references/session-intake.md",
+          "surface_entry": null,
+          "summary": "The single compact brief: Intent becomes Work, a Campaign field takes the Campaign intent lines from next, Missing inputs covers only choices that affect this revision, and brief answers are saved with record brief after asking the operator."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-polish/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.53.0+skills.2 bundle revision; read the normalized brief and the recorded decisions; record a skipped Polish only on the operator's decision, quoting their reason as skip_reason; report readability warnings and offer repairs inside the brand palette, accepting one only with the operator's refs, reason and name."
+        },
+        {
+          "class": "skill",
+          "path": "skills/next-campaigns-qa/SKILL.md",
+          "surface_entry": null,
+          "summary": "Publish the 1.53.0+skills.2 bundle revision; read the normalized brief and the recorded decisions; report readability warnings and offer repairs inside the brand palette, accepting one only with the operator's refs, reason and name."
+        },
+        {
+          "class": "cli_surface",
+          "path": "src/cli.mjs",
+          "surface_entry": "next",
+          "summary": "next carries intent_summary on every result and prints a Campaign intent section under the status; the setup, build, Polish and QA prompts start with the summary and the absolute normalized brief path, and the build prompt names record brief and record spec for refreshing a changed brief or CampaignSpec."
+        }
+      ],
+      "entry_sha256": "197929e76610b701b015cac7ee37f1f8a75b18e350a8268b679b8ca51a9b7f14"
     }
   ]
 }

package/contracts/supported-surface.json

@@ -1,6 +1,6 @@
 {
   "_note": "The downstream contract manifest. Everything listed here is SUPPORTED SURFACE: consumers (campaigns-agent, campaign-builder, the private ops repo, page-kit campaign repos) may depend on it, and changing it is a deliberate act — hashed entries require a surface_version bump in the same change (check-supported-surface.mjs --base, mirroring the skills.json bump gate), named entries must keep existing at their path, cli_commands must keep resolving in the CLI dispatch, package_exports must stay exported, and every entry must ship in the npm pack (files[] coverage). Anything NOT listed here — src/** internals, scripts/** checkers, examples/**, prompts/**, contracts/** other than this file and the entries named[] below (the orientation contract, the release ledger, and the consumer-facing orientation fixtures) — is implementation: consumers may read it for context but must not build on it, and it can change without notice. Rationale and the compatibility promise: docs/supported-surface.md.",
-  "surface_version": "1.52.0",
+  "surface_version": "1.53.0",
   "package_exports": [
     "./commercial-journey",
     "./commercial-parity",
@@ -120,7 +120,7 @@
       "sha256": "dfc9abed38d456969e47a21f606d308a03bdf036f3466f7d6e47a602747dacf4"
     },
     "contracts/effects.v1.json": {
-      "sha256": "f49ac6dcbf441c90b12b51be9bc07805f6228f4143784045c5925e3c155a6181"
+      "sha256": "8282f7ffe91aaf12c4b79e4431b5ddc35cce82e42f1746d4a0ea44f54bd7fb8e"
     },
     "schemas/campaigns-os-effects.v1.schema.json": {
       "sha256": "3eadd22169ab98bc7c2f682af2751267605170581182158d96be035b0cfe44dc"

package/docs/brand-theme-bridge.md

@@ -94,6 +94,8 @@ used and reported with `theme.foreground.low_contrast`. With no declared CTA
 foreground, the output is unchanged. Declarations inside CSS comments are not
 read, so a commented-out token or rule never supplies a CTA or body text colour.
 
+Contrast is computed with the same unrounded measurement Polish and QA use, so a declared colour at 4.495:1 now warns. The generator's colour choices are unchanged. Polish measures the rendered text at its real size and weight: a qualifying large label at 3:1 passes there, and smaller text produces a warning the operator can accept.
+
 ### Body text prefers the darkest declared text token
 
 A declared text token is a `:root` custom property in the selected source whose

package/docs/build-packet.md

@@ -48,8 +48,10 @@ report writes, polish capture, progress, run closeout and QA compare that local
 identity. Material spec hashes still bind the current revision; a changed ID or
 content cannot reuse earlier proof. After a material revision, doctor and
 `next` warn `spec.material_stale` (the spec no longer has the material hash
-prepare-build bound on the Assembly Report, which QA refuses); follow `next` to
-refresh preparation and affected evidence. Keep the spec, source, dependency
+the Assembly Report binds, which QA refuses), and `next` routes to the build
+and names the refresh: run `campaigns-os record spec --packet <packet>` to bind
+the new content and keep stage history (see
+[Refreshing after a CampaignSpec change](#refreshing-after-a-campaignspec-change)). Keep the spec, source, dependency
 pins and canonical sidecars in Git. Use `readback` and `next` after a fresh
 checkout; identity survives the move, but proof freshness is assessed again.
 
@@ -523,16 +525,13 @@ writing it would declare an analytics contract QA then blocks on. A derived
 field the entry does not carry at all is listed under `not_in_target[]` and
 left as it is.
 
-After a write, the sidecars that carry the spec's identity are re-bound. The
+`spec derive` writes the spec alone and no longer rebinds identity: the
 Build Context's `spec.hash` / `spec.material_hash` and the Assembly Report's
-`identity.spec_hash` / `identity.spec_material_hash` move to the new spec
-when they were bound to the one derive replaced and name that spec file
-(`rebound` on the result; two packets sharing a target repo never re-bind
-each other's sidecars);
-QA's verdict and `bundle check` correlate against the material hash, so this
-is what keeps a derive-then-QA run conformant. A sidecar already carrying
-another identity is left alone with a `spec.derive.identity_not_rebound`
-warning naming `prepare-build`. A derived route change also warns
+`identity.spec_hash` / `identity.spec_material_hash` keep the spec they were
+bound to, so every build, Polish and QA record made against the earlier
+content reads owed again. Run `record spec` after it (the result's `next`
+names it) to bind the derived spec; QA's verdict and `bundle check` correlate
+against the bound material hash. A derived route change also warns
 `spec.derive.projection_stale`: the packet's page-kit projection
 (`source_html.pages[].page_kit`) and the Build Context page map were prepared
 from the old routes, and `prepare-build` (or `start`) regenerates them. A
@@ -552,8 +551,8 @@ the spec resolves to, which must lie inside the spec's own directory or the
 target repo (`spec.derive.spec_escapes_boundary` otherwise, so a symlinked
 `spec.local_path` cannot redirect the write); the retained doctor sidecar is
 marked stale after a write, and a terminal build gets a
-`spec.derive.build_stale` warning naming the rebuild (doctor does not
-fingerprint the spec itself; the re-bound sidecar identity is what QA reads). `--dry-run` prints the
+`spec.derive.build_stale` warning naming `record spec`, after which `next`
+routes back to the build. `--dry-run` prints the
 same diff and writes nothing; unknown flags and a valued `--dry-run` are
 rejected. Exit 2 with `spec.derive.*` error codes and nothing written when the
 packet cannot be read, `spec.local_path` is absent or not a file, the spec is
@@ -1058,8 +1057,13 @@ full.
 and auto-discover `campaign-build-brief.yaml`, `.yml`, or `.json` from the
 source root or target repo. When none is present, Campaigns OS creates a guided
 draft at `.campaign-runtime/input/campaign-build-brief.normalized.json`.
-See [Campaign Build Brief](./campaign-build-brief.md) for the schema and
-prepared/guided behavior.
+A brief file is guided unless it sets `"brief_mode": "prepared"` (a campaign
+whose Assembly Report already records a prepared brief stays prepared). Save
+answers later with `record brief`, which keeps stage evidence unless the brief's
+material content changes; a presentation change makes build, Polish and QA
+owed again, and a `qa_policy` change makes QA alone owed again. See
+[Campaign Build Brief](./campaign-build-brief.md) for the schema, the mode
+rule and the stage map.
 
 `start` / `prepare-build` also prepares the normalized Design Source Package at
 `.campaign-runtime/input/design-source-package.json`. When that path is absent,
@@ -1681,6 +1685,43 @@ records it (`campaigns-os record setup|build|polish`; deploy and QA record their
 own stages) → calls `next` again → repeat until stage="done"
 ```
 
+### Refreshing after a CampaignSpec change
+
+When the CampaignSpec's material content changes, every build, Polish and QA record made against the earlier content stops counting as current, in local-spec, saved-Map and gateway packets alike. For a saved Map or gateway packet, Campaigns OS compares the copy intake fetched; it does not check whether that copy is the latest remote revision, and reports the remote as unconfirmed. Doctor warns `spec.material_stale`, and `next`, progress, readback, the Assembly Report's own status and the QA gate show the stages that are owed again; `next` routes to the first one. Run `campaigns-os record spec --packet <packet>` to bind the new content: it updates the build context and report identity, re-reads the brief file last saved (by intake or `record brief`), keeps waivers, warning accepts, the applied theme and deploy settings, and moves each superseded stage record into that stage's `history`, which is never used as current proof. `spec derive` no longer rebinds identity; run `record spec` after it. A change to the set, order or routes of active pages still needs intake. Re-recording an unchanged build after a spec change keeps the build owed, because the change has not reached the pages, unless the operator records a reason with `--deviation-reason`; this holds even when `record spec` was not run, and that `record build` also marks Polish and QA owed again. Polish stays owed until a new `polish capture`, and QA must produce a new verdict against the current content. Polish measurements of byte-identical output keep their values, but the Polish stage is owed again. These checks are tamper evidence, not proof: a hand-written record that copies the current values, or a packet pointed at an older copy of the spec, is not detected.
+
+The CampaignSpec's material content is the whole spec except `spec_identity`,
+`slug`, `map_id` and `saved_at`; a page `label` edit is material. A spec
+change affects the stages as follows:
+
+| Stage | After a spec material change |
+|---|---|
+| `prepare_build` | unchanged (`record spec` refuses a page-scope change, which needs intake) |
+| `doctor` | recomputed on every read |
+| `setup` | kept |
+| `assembly` | owed: `required`, `required_by: "spec"`, `required_for: ["polish", "qa"]` |
+| `polish` | owed: `required`, `required_by: "spec"`, `required_for: ["qa"]` |
+| `deploy` | kept |
+| `qa` | owed: `required`, `required_by: "spec"`, `required_for: []` |
+
+`record spec` refuses, writing nothing, in this order: `spec_unreadable` (the
+spec does not parse), `spec_identity_changed` (its map id or local spec id
+names another campaign than the packet or the report), `page_scope_changed`,
+then, for the brief file last saved (by intake or `record brief`), `brief_too_large`,
+`brief_source_is_package_artifact` and `brief_file_missing` (the recorded
+path is missing or is not a readable regular file: a directory, a pipe or
+socket, a symlink to nothing, or a file without read permission). When it must
+re-derive the brief, it also refuses `brief_inputs_unavailable` (the Build
+Context lacks an intake product re-deriving the brief needs). It reads
+`unchanged` and writes nothing when the bound material equals the spec and no
+stage's spec or brief stamp differs from the current content; a stage that
+does not record which content it was made against is named in a
+`binding_unknown` notice instead. Otherwise it refreshes, re-deriving the
+normalized brief from the brief file last saved, so an edit made to the
+normalized brief itself is replaced by what its source gives. A stage whose spec
+stamp already equals the new content (a build recorded after the edit) is not
+demoted. `record spec` does not write the Build Packet. `--dry-run` runs every
+check and writes nothing.
+
 ### Recording stage completion
 
 Setup, build and polish completion is recorded with one command each, never by

package/docs/campaign-build-brief.md

@@ -35,7 +35,7 @@ The Build Packet, Build Context, and Assembly Report all reference that normaliz
 
 ## Modes
 
-Prepared mode is for veteran users. A complete brief should let the build proceed without business questions. If a supplied brief is incomplete or contradictory, doctor blocks with `build_brief.*` errors.
+Prepared mode is for veteran users, and a brief file selects it with `"brief_mode": "prepared"` (see [Brief mode](#brief-mode)). A complete brief should let the build proceed without business questions. If a prepared brief is incomplete or contradictory, doctor blocks with `build_brief.*` errors.
 
 Guided mode is for new or partial inputs. Campaigns OS drafts a brief from CampaignSpec, page mappings, template family, source assets, and available runtime hints. It records only high-impact unresolved questions as warnings so existing builds still run while the business uncertainty is visible.
 
@@ -56,27 +56,58 @@ The CLI avoids SDK/page-kit jargon in questions. The implementation can resolve
 
 Question 5 is asked only when the CampaignSpec maps a surface that fills the template's promo placeholders: a `funnels[].promo_codes` roster, or a checkout page's enabled `exit_intent` or `promo_code_input`. It never asks for approval of the source design's own promo, proof or urgency copy, which is built as designed (see below). Without such a surface the guided draft sets `header_claim_source` and `timer_label` to `"none"`: the template's promo placeholders are removed.
 
-## Answering The Questions
+## Saving Answers
 
-An answer counts only once it is in a brief file that `start` or `prepare-build` reads. The guided draft is regenerated on every run, so an answer given in conversation, or typed into the normalized draft, does not stick.
+Save brief answers with `campaigns-os record brief --packet <packet>`. Copy the normalized draft to `campaign-build-brief.json` in the target repository, set the fields named in the open questions, and run `record brief`. You do not need to re-run `start` or `prepare-build`, and no stage evidence is cleared unless the saved answers change the brief's material content. `record brief` refuses a path that points at one of the files Campaigns OS writes itself, such as the normalized brief.
 
-1. Copy `.campaign-runtime/input/campaign-build-brief.normalized.json` to `campaign-build-brief.json` in the target repo. A brief file replaces the guided draft whole, so starting from the copy keeps the fields the draft already filled; any question the file leaves open blocks as a prepared brief.
-2. Set the fields that close each open question:
+A brief is prepared, where every open question blocks, only when the file sets `"brief_mode": "prepared"`. A brief file without `brief_mode` is guided: questions you leave open remain warnings. One exception keeps existing campaigns as they were built: when the campaign's Assembly Report already records a prepared brief, a file without `brief_mode` stays prepared. Set `"brief_mode": "guided"` to make it guided.
 
-   | Question | Fields |
-   |---|---|
-   | `page_design_authority` | `design_authority.<page_id>.source` for each page named in the question |
-   | `brand_palette_cta` | `brand.commerce_palette_source`, `brand.cta_style` |
-   | `variant_media_rules` | `media.sold_variants`, `media.allow_other_variant_colors` |
-   | `bundle_pricing_presentation` | `offer_presentation.bundle_cards.primary_price` |
-   | `promo_urgency_copy` | `promo_urgency.header_claim_source` (`campaign_offers` or `none`), `promo_urgency.timer_label` (the template timer's label, or `none`) |
-   | `payment_methods_trust` | `commerce_surfaces.payment_methods_allowed` |
-   | `canonical_display_names` | `canonical_display.product_name_source` |
-   | `regulated_claims` | one of `campaign_intent.compliance.approved_benefit_language`, `.forbidden_claims`, `.approved_claims`, `.copy_rules` |
+Saving a brief whose content is unchanged keeps all stage evidence and statuses. Reformatting, reordering keys, writing a default value explicitly, or changing only `_meta` also keeps all stage evidence and statuses; the save may rewrite the brief files. When the presentation sections change (`campaign_intent`, `design_authority`, `brand`, `media`, `offer_presentation`, `promo_urgency`, `commerce_surfaces`, `canonical_display`, `template_residue_policy`, or any section you add), build, Polish and QA are owed again. When only `qa_policy` changes, QA alone is owed again. Setup and deploy records are kept. Each affected stage records when its inputs changed. Each replaced record is kept under the stage's `history`; the last five superseded records per stage are kept, and older ones are dropped. History is display only and is never used as current proof.
 
-3. Re-run `start` or `prepare-build` with the same arguments. The file is found in the target repo automatically, or pass `--brief <file>`. Doctor's `build_brief.guided_questions` warning names the open questions and their fields.
+Recording build again over output that has not changed since the brief or CampaignSpec changed does not make the build current: `next` keeps asking for a build, because the change has not reached the pages. If the operator decides the change needs no change to the built pages, record build with `--deviation-reason "<the operator's reason>"`; the build is then recorded with a warning, and the reason is shown in `next` and the QC handoff. `--deviation-reason` is a general flag any caller can pass: Campaigns OS records the reason, but cannot tell whether the operator chose it. A CampaignSpec change that was never saved with `record spec` is recorded by the next `record build`, `record polish` or QA run, with the same effect; `record build` then also marks Polish and QA owed again. An edit to the brief file is not read until it is saved with `record brief`: until then the build reads the saved brief, and doctor warns `build_brief.input_unsaved`. The same applies after `prepare-build --force`, which now keeps stage history, archives the build, Polish and QA records it clears, and keeps the record that the inputs changed. Recording Polish again does not make it current until a new `polish capture` runs after the change. Recording Polish as skipped, with a skip reason, while it is owed is the operator's decision to skip it: the input change no longer makes Polish owed. The Polish gate still passes only a completed Polish, so `next` stays at Polish until one is recorded (see `docs/polish-evidence.md`).
 
-Re-running regenerates the Assembly Report. Before any stage has recorded evidence, that costs nothing. Once a stage has recorded evidence (setup, build, polish or later), the re-run is refused unless you pass `--force`, which resets those stages and clears their evidence. Answer the questions right after `start`.
+A build, Polish or QA record that does not say which brief and CampaignSpec content it was made against counts as unconfirmed, not current. Records made by earlier releases are unconfirmed, so after upgrading, `next` routes back to build once; record build and Polish again and run QA again. These checks are tamper evidence, not proof: a record written by hand that copies the current values or removes the record of an input change, or a packet pointed at an older copy of the spec or brief, is not detected.
+
+The fields that close each open question (doctor's `build_brief.guided_questions` warning names the open questions and their fields):
+
+| Question | Fields |
+|---|---|
+| `page_design_authority` | `design_authority.<page_id>.source` for each page named in the question |
+| `brand_palette_cta` | `brand.commerce_palette_source`, `brand.cta_style` |
+| `variant_media_rules` | `media.sold_variants`, `media.allow_other_variant_colors` |
+| `bundle_pricing_presentation` | `offer_presentation.bundle_cards.primary_price` |
+| `promo_urgency_copy` | `promo_urgency.header_claim_source` (`campaign_offers` or `none`), `promo_urgency.timer_label` (the template timer's label, or `none`) |
+| `payment_methods_trust` | `commerce_surfaces.payment_methods_allowed` |
+| `canonical_display_names` | `canonical_display.product_name_source` |
+| `regulated_claims` | one of `campaign_intent.compliance.approved_benefit_language`, `.forbidden_claims`, `.approved_claims`, `.copy_rules` |
+
+### Brief mode
+
+The mode is decided in this order:
+
+1. `"brief_mode": "prepared"` in the file: prepared.
+2. `"brief_mode": "guided"` in the file: guided.
+3. No `brief_mode`, and the campaign's Assembly Report on disk records a prepared brief: prepared.
+4. No `brief_mode` otherwise, including the generated draft and every new hand-written file: guided.
+5. Any other `brief_mode` value is the error `build_brief.brief_mode`, and the brief reads `invalid`.
+
+The file's own `_meta` (including a copied draft's `_meta.mode`) is never read for the mode; the normalized brief records how the mode was decided in `_meta.mode_source` (`field`, `legacy_report` or `generated`). Input errors block in both modes. In guided mode, open questions and evaluation gates stay warnings.
+
+### What a brief change makes owed
+
+The brief's material content is the normalized brief without `_meta`, `status`, `questions`, `gates`, `confidence`, `schema_version`, `brief_mode` and `qa_policy.enforcement`, in two parts: `qa_policy`, and every other section (presentation).
+
+| Stage | Presentation changed | `qa_policy` changed |
+|---|---|---|
+| `prepare_build` | brief blockers re-derived; other blockers kept | re-derived |
+| `doctor` | recomputed on every read | recomputed on every read |
+| `setup` | kept | kept |
+| `assembly` | owed (`required`, `required_by: "brief"`) | kept |
+| `polish` | owed (`required`, `required_by: "brief"`) | kept |
+| `deploy` | kept | kept |
+| `qa` | owed (`required`, `required_by: "brief"`) | owed |
+
+Only completed records are made owed. A skipped stage stays skipped.
 
 ## Risky Defaults
 

package/docs/effects.md

@@ -127,6 +127,14 @@ itself carries QA's own read).
 
 **Accepting a warning.** `campaigns-os checkpoint accept` records an operator's decision about a warning that a Campaigns OS check measured. It does not change readiness, does not remove the warning, does not change the status `next` reports, and cannot be used on review, unexercised, or excluded results. The warning must already be on record (in the doctor snapshot `next` writes, the Polish capture, or the full QA verdict) before it can be accepted. The accept is bound to the exact measured state and lapses when that state changes, or when its evidence is stale or cannot be reproduced. An optional expiry or review condition adds a second bound. Run it only with the operator's explicit decision, made after the warning was shown to them. A plausible name is not authorization. The command refuses placeholder and automation identities. Results are re-derived from the package's raw captures on every read, and a result whose capture is missing or does not match is listed as unexercised. These checks are tamper evidence, not proof of authorship: a hand-written record that copies every value and recomputes the checksum, or a hand-written result written together with a matching capture, is not detected.
 
+### `record brief` and `record spec`
+
+**Saving brief answers.** `campaigns-os record brief --packet <packet>` saves Campaign Build Brief answers without re-running `start` or `prepare-build`. It writes the normalized brief under `{target}/.campaign-runtime/input/`, the Build Packet, the build context, the Assembly Report and the doctor-sidecar stale stamp, and sends nothing. It refuses a path that points at one of the files Campaigns OS writes itself, such as the normalized brief. Saving a brief whose content is unchanged keeps all stage evidence and statuses. Reformatting, reordering keys, writing a default value explicitly, or changing only `_meta` also keeps all stage evidence and statuses; the save may rewrite the brief files. When the presentation sections change, build, Polish and QA are owed again. When only `qa_policy` changes, QA alone is owed again. Setup and deploy records are kept. Each replaced record is kept under the stage's `history`; the last five superseded records per stage are kept, and history is never used as current proof.
+
+**Binding a CampaignSpec change.** `campaigns-os record spec --packet <packet>` binds the new CampaignSpec content: it updates the build context and report identity, re-reads the brief file last saved (by intake or `record brief`), keeps waivers, warning accepts, the applied theme and deploy settings, and moves each superseded stage record into that stage's `history`. It writes the build context, the Assembly Report, the normalized brief and the doctor-sidecar stale stamp; it does not write the Build Packet, and it sends nothing. `spec derive` no longer rebinds identity; run `record spec` after it. A change to the set, order or routes of active pages still needs intake.
+
+Both rows are tier C, because a change makes recorded stages owed again, and each `--dry-run` form is tier none: it writes nothing and appends no lifecycle entry. A CampaignSpec change that was never saved with `record spec` is recorded by the next `record build`, `record polish` or QA run, with the same effect; `record build` then also marks Polish and QA owed again. An edit to the brief file is not read until it is saved with `record brief`: until then the build reads the saved brief, and doctor warns `build_brief.input_unsaved`. Intake now also refuses, without `--force`, to discard recorded waivers, warning accepts, stage history, an applied theme, or a recorded deploy target, preview URL, production URL, order-path depth or allowed-domains confirmation; with `--force`, it keeps stage history, archives the build, Polish and QA records it clears, and keeps the record that the inputs changed.
+
 ## How to read a row
 
 ```jsonc

package/docs/local-setup.md

@@ -3,7 +3,7 @@
 For a new campaign, create an empty working folder and run this from it:
 
 ```sh
-npm init -y && npm install --save-exact next-campaign-page-kit@0.2.0 && npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.52.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
+npm init -y && npm install --save-exact next-campaign-page-kit@0.2.0 && npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.53.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
 ```
 
 `npm init -y` gives the folder its own `package.json`. Without one, npm

package/docs/orientation-contract-reference.md

@@ -26,7 +26,7 @@ Ledger schema id: `campaigns-os-release-ledger/v1`
 Change policy version: `1.0.0`  
 Reason-code vocabulary version: `1.0.0`  
 Limits version: `1.0.0`  
-Supported surface at generation time: `1.52.0`
+Supported surface at generation time: `1.53.0`
 
 ## Forward compatibility