@nextcommerce/campaigns-os 1.52.0 → 1.54.0

package/src/cli.mjs

@@ -120,6 +120,7 @@ import {
   SOURCE_HTML_MANIFEST_REL_PATH,
 } from "./source-html-manifest.mjs";
 import { crawlSourceAssetPaths } from "./source-asset-crawl.mjs";
+import { summarizeCampaignBrief } from "./brief-summary.mjs";
 import {
   THEME_POLICIES,
   inspectBrandTheme,
@@ -174,6 +175,8 @@ import {
   createCampaignBuildBriefArtifact,
   inferBuildBriefPath,
 } from "./build-brief.mjs";
+import { briefIntakeBindings, currentPacketInputs, inputRefreshCommands, inputStamps, stageWriteInputs } from "./input-currency.mjs";
+import { prepareBuildStageStatus, priorBriefInputsForIntake } from "./input-refresh.mjs";
 import {
   DESIGN_SOURCE_PACKAGE_REL_PATH,
 } from "./design-source-package.mjs";
@@ -315,9 +318,10 @@ Usage:
                      [--allow-uncertified-template "<reason>"] [--order-path-depth <off|common|full>]
                      [--deploy-target <target>] [--preview-url <url>] [--production-url <url>] [--no-run-session] [--force]   # intake alias for prepare-build + doctor
   campaigns-os doctor --packet <campaign-runtime.build.json> [--context <json>] [--report <json>] [--strip-paths] [--write] [--no-write] [--doctor-out <path>] [--proxy-base <url>] [--no-live-refs] [--json]   # inspection by default; --doctor-out requires --write; --no-write wins. When the packet's built _site/<route>/ exists and a public Campaigns API key resolves (packet, its local CampaignSpec, or the declared campaign-key env var), doctor makes one read-only GET of {proxy-base}/api/campaign under X-Campaign-Key to check each built page's shipping and package refs against the live campaign; --proxy-base overrides the canonical proxy (https, or a loopback host over http). --no-live-refs skips the read and records not_run with reason disabled. No key, no built page, or a failed read records derived.live_campaign_refs as not_run with its reason. Only doctor and qa run make this read; other commands that run doctor record not_read
-  campaigns-os doctor --built <page-kit-target-repo> --family <family> [--slug <slug>] [--base-url <url>] [--emit-packet [path]] [--json]   # L7: doctor a built _site/ with no Build Packet
+  campaigns-os doctor --built <page-kit-target-repo> --family <family> [--slug <slug>] [--base-url <url>] [--emit-packet [path]] [--json]   # L7: doctor a built _site/ with no Build Packet. Reads the local files only: --base-url is not fetched, it fills deploy.preview_url in the minimal packet (check served pages with qa run --site)
   campaigns-os bundle check --packet <campaign-runtime.build.json> [--require-qa] [--json]   # validate the canonical migration/readback JSON bundle; never substitutes markdown
   campaigns-os sdk storage-check --target <git-root> --target-sdk <x.y.z> --manifest <SDK-manifest.json> --scope <dir,file> [--exclude <dir,file>] [--json]
+  campaigns-os sdk repin --target <static-campaign-repo> [--target-sdk <x.y.z>] [--apply] [--json]   # rewrite the version segment of each semver-pinned Campaign Cart loader.js / campaign-cart.css URL (the references standardize's scan finds, @vX.Y.Z or @X.Y.Z) below the target, default the SDK support policy's preferred_minimum; @latest, @main, commit and prerelease refs, and pins at or above the target, are reported and left alone. Preview by default (path:line, old -> new URL, nothing written); --apply writes the files and a change record at .campaign-runtime/sdk-repin.json (campaigns-os-sdk-repin/v0: files touched, reference count, from/to versions) a Run Record can cite. A repo with _data/campaigns.json is refused (exit 2): page-kit sync owns that pin
   campaigns-os standardize --target <campaign-repo> [--family <family>] [--slug <slug>] [--sdk-support-policy <path.json>] [--field-contract <path.json>] [--no-doctor] [--json]
   campaigns-os theme inspect --packet <campaign-runtime.build.json> [--context <json>] [--theme-policy <inspect_only|auto|off>] [--json]
   campaigns-os theme generate --packet <campaign-runtime.build.json> [--context <json>] [--out-dir <dir>] [--force] [--json]
@@ -328,11 +332,13 @@ Usage:
   campaigns-os spec derive --packet <campaign-runtime.build.json> [--dry-run] [--json] [--report <json>] [--from-store <subdomain> [--store-token-source env:<VAR>]] [--write-map] [--proxy-base <url>]   # write the fields the target repo already states into the packet's local CampaignSpec (spec.local_path): the SDK pin from _data/campaigns.json[<route>].sdk_version (global_config.sdk_version, and the runtime.sdk_version alias when declared), each page's page_url from the page tree under src/<route>/ (filename or permalink), and the analytics ids the entry carries (gtm_id -> analytics.providers.gtm.containerId, fb_pixel_id -> analytics.providers.facebook.pixelId); prints a field-by-field before -> after diff and writes nothing else. Repo-derived fields only and no network by default; --from-store <subdomain> (the <store> of <store>.29next.store) also reads through campaigns-os login gateway credentials (--store-token-source env:<VAR> explicitly selects the warned break-glass Admin path; a token never goes on the command line) and writes the nine campaign.store_* Store Profile fields: store_name and store_url (primary domain) and store_phone/store_phone_tel from GET /store/, and store_terms/privacy/contact/returns/shipping as https://<primary domain>/<slug>/ from the one storefront page (GET /pages/) whose slug or title names each policy; an empty store field, no page or several never empties the spec's value. A field the repo or store cannot state (a scaffold's seeded pin, an unbound page, an empty or malformed id, an active page_kit.sdk_version waiver, an empty store field, an unbound policy page) is reported as not derived, status PARTIAL; exit 2 when the packet, the spec or the target entry is missing, the spec identifies another campaign, or the store cannot be read (credential missing, 401/403, no such store, unreachable). --write-map also records the derived pin into the saved Map's Build hints (Campaign Cart SDK version) through the proxy Worker (PUT /api/maps/<spec.map_id> under X-Campaign-Key, the packet's Campaigns API key, with the Map's spec_hash as the X-Spec-Hash precondition): written when the Map declares no pin or one behind the repo, unchanged when equal, refused (warning, exit 0) when the Map pin is ahead or cannot be ordered, failed (error, exit 2) when the key is missing or mismatched, the Map is gone, was saved in between, or the proxy refuses the body; the write is recorded on the Assembly Report evidence[] and in the result's map object. --proxy-base overrides the canonical proxy (https, or a loopback host over http); --dry-run reads the Map and reports would_write without a PUT.
   campaigns-os page-kit parity --packet <campaign-runtime.build.json> [--report <json>] [--json]   # local proof mode (deploy.target local-serve): render the current source in development and production through the target's page-kit into temp dirs, assert the served _site/ is the current development render and that production differs from it only in environment-gated output (same page set, same route slugs, same Campaign Cart pin and next-api-key); records stages.assembly.evidence.local_proof.production_parity, which doctor reads as local_proof.production_parity. Exit 2 on a non-gated difference.
   campaigns-os polish capture --packet <campaign-runtime.build.json> --base-url <url> [--report <json>] [--headed] [--auth-cookie <cookie>] [--json]
+  campaigns-os record brief --packet <campaign-runtime.build.json> [--brief <yaml|json>] [--context <json>] [--report <json>] [--dry-run] [--json]
+  campaigns-os record spec --packet <campaign-runtime.build.json> [--context <json>] [--report <json>] [--dry-run] [--json]
   campaigns-os record setup --packet <campaign-runtime.build.json> [--context <json>] [--report <json>] [--dry-run] [--json]   # record setup complete once the campaign output directory exists: Build Context scaffold.required=false and stages.setup completed, validated against their schemas before either is written
   campaigns-os record build --packet <campaign-runtime.build.json> [--build-environment <development|production>] [--context <json>] [--report <json>] [--dry-run] [--json]   # after page-kit build (--build-environment records stages.assembly.evidence.build_environment; local proof mode records development): stages.assembly completed with build_fingerprint = doctor's derived.build_output_fingerprint.value (and the Design Source Package material fingerprint when the report has one); stages.polish becomes required unless its evidence is bound to this exact output
   campaigns-os record polish --packet <campaign-runtime.build.json> --evidence <polish-evidence.json> [--context <json>] [--report <json>] [--dry-run] [--json]   # after polish capture: stages.polish from the file's status (completed, completed_with_warnings, blocked with blockers, or skipped with skip_reason), evidence and optional repair_loop_defect, bound to doctor's current fingerprint; a completed status is refused, writing nothing, unless the polish gate doctor evaluates would pass. --dry-run runs every check and writes nothing
   campaigns-os record theme --packet <campaign-runtime.build.json> [--context <json>] [--report <json>] [--dry-run] [--json]   # after the brand layer is linked and build is recorded: report.theme becomes applied with load_order after-next-core, css_path, commerce_pages and per-page evidence, only when each built commerce page that loads next-core.css loads brand-theme.css (or checkout-brand.css) after it and at least one does; a page loading neither is left out as the design's own markup; refused, writing nothing, otherwise. --dry-run runs every check and writes nothing
-  campaigns-os record deploy --packet <campaign-runtime.build.json> --base-url <served url> [--context <json>] [--report <json>] [--dry-run] [--json]   # a local preview (deploy.target local-serve) after polish is recorded: GETs every built page under the loopback URL (the campaign route root), then records deploy.preview_url on the packet and stages.deploy completed with the URL in outputs; refused, writing nothing, when the URL is not loopback or not the route root, a page does not answer 2xx, the build changed since it was recorded, or the theme gate is blocked. --dry-run runs every check, the requests included, and writes nothing
+  campaigns-os record deploy --packet <campaign-runtime.build.json> --base-url <served url> [--context <json>] [--report <json>] [--dry-run] [--json]   # a local preview (deploy.target local-serve) after polish is recorded: GETs every built page under the loopback URL (the campaign route root), then records deploy.preview_url on the packet and stages.deploy completed with the URL in outputs and the build fingerprint it probed (a later record build of other output makes deploy required again); refused, writing nothing, when the URL is not loopback or not the route root, a page does not answer 2xx, the build changed since it was recorded, or the theme gate is blocked. --dry-run runs every check, the requests included, and writes nothing
   campaigns-os readback <target-repo-root> [--json] [--packet <path>] [--doctor <path>] [--context <path>] [--report <path>] [--qa-verdict <path>] [--findings <path>]   # read-only projection of one run's emitted artifacts (packet, doctor output, build context, assembly report, QA verdict, findings export): artifact states, per-artifact freshness against the checkout's HEAD reflog, doctor warning grouping, skip cascades and cross-artifact divergences. Writes nothing, starts no process, touches no network, and records no lifecycle entry; --json emits one campaigns-os-readback/v2 object (docs/readback.md). Exit 2 for a missing target root or a Build Packet set freshness cannot single out.
   campaigns-os readback --example [--json]                                # project the bundled synthetic sample; freshness is not computable for it by design
   campaigns-os validate-assembly-report --report <json> [--json]
@@ -709,6 +715,10 @@ export function recordQaStageOutcome(args, result) {
     const failed = (Array.isArray(verdict.assertions) ? verdict.assertions : [])
       .filter((assertion) => assertion?.status === "fail")
       .map((assertion) => `${assertion.id}: ${assertion.actual || "assertion failed"}`);
+    // The QA stamps are the verdict's: the brief material qa run bound at run
+    // start and the spec material it judged, never the inputs at write time.
+    const qaStamps = inputStamps({ briefMaterial: verdict.source_brief_material, specMaterial: verdict.spec_hash });
+    const qaInputs = stageWriteInputs("qa", currentPacketInputs({ packet, packetPath }));
     const committed = commitAssemblyReport(workspace, (report) => {
       if (hasLocalIdentity && !specHashesMatch(verdict.spec_hash, report.identity?.spec_material_hash)) {
         throw new Error("Local-spec QA verdict belongs to a different material revision; report evidence was not changed.");
@@ -734,6 +744,8 @@ export function recordQaStageOutcome(args, result) {
         // summarizePurchaseProof). This is what lets `next` tell a real purchase
         // path from a `--test-order off` diagnostic.
         proof: summarizePurchaseProof({ verdict, proofPolicy: packet.qa?.proof_policy }),
+        stamps: qaStamps,
+        inputs: qaInputs,
       });
     }, {
       stage: "qa",
@@ -1041,7 +1053,25 @@ async function dispatch(command, args, { recorder = NOOP_RECORDER, ambient = nul
   }
 
   if (command === "sdk") {
-    if (args._[1] !== "storage-check" || args._.length !== 2) throw refused("Use: campaigns-os sdk storage-check --target <git-root> --target-sdk <x.y.z> --manifest <SDK-manifest.json> --scope <dir,file> [--exclude <dir,file>] [--json].");
+    if (args._[1] === "repin" && args._.length === 2) {
+      const known = new Set(["_", "target", "target-sdk", "apply", "json"]);
+      for (const key of Object.keys(args)) if (!known.has(key)) throw refused(`Unknown SDK repin flag: --${key}`);
+      for (const flag of ["apply", "json"]) {
+        if (args[flag] !== undefined && args[flag] !== true) throw refused(`--${flag} is a boolean flag and takes no value.`);
+      }
+      const { runSdkRepin, formatSdkRepinReport, isRepinTargetVersion } = await import("./sdk-repin.mjs");
+      const targetSdk = args["target-sdk"] === undefined ? null : requireArg(args, "target-sdk");
+      if (targetSdk !== null && !isRepinTargetVersion(targetSdk)) throw refused(`--target-sdk ${targetSdk} is not a released SDK version (x.y.z).`);
+      const result = runSdkRepin({
+        targetRepo: requireArg(args, "target"),
+        targetSdk,
+        apply: args.apply === true,
+      });
+      console.log(args.json ? JSON.stringify(result, null, 2) : formatSdkRepinReport(result));
+      process.exitCode = result.ok ? 0 : 2;
+      return;
+    }
+    if (args._[1] !== "storage-check" || args._.length !== 2) throw refused("Use: campaigns-os sdk storage-check --target <git-root> --target-sdk <x.y.z> --manifest <SDK-manifest.json> --scope <dir,file> [--exclude <dir,file>] [--json], or campaigns-os sdk repin --target <static-campaign-repo> [--target-sdk <x.y.z>] [--apply] [--json].");
     const known = new Set(["_", "target", "target-sdk", "manifest", "scope", "exclude", "json"]);
     if (args.json !== undefined && args.json !== true) throw refused("--json is a boolean flag and takes no value.");
     for (const key of Object.keys(args)) if (!known.has(key)) throw refused(`Unknown SDK storage-check flag: --${key}`);
@@ -1438,8 +1468,7 @@ function createInitialAssemblyReportStages({ scaffoldRequired, blockers, outputs
   // (STAGE_TERMINAL_STATUS_PREFIXES): declared out-of-scope pages do not hold
   // the ladder, they are recorded on the stage so downstream consumers can see
   // exactly which pages assemble from the template family instead of source HTML.
-  const terminalStatus = declaredScopeSkips.length ? "completed_partial" : "completed";
-  stages.prepare_build = createStage("prepare_build", blockers.length ? "blocked" : terminalStatus, {
+  stages.prepare_build = createStage("prepare_build", prepareBuildStageStatus({ blockers, declaredScopeSkips }), {
     outputs,
     blockers,
     ...(declaredScopeSkips.length ? { declared_out_of_scope: declaredScopeSkips } : {}),
@@ -1790,6 +1819,10 @@ function prepareBuildUnderLock({
     sourceRoot,
     targetRepo,
   });
+  // The report and normalized brief this run replaces: the report's brief
+  // mode keeps an existing prepared campaign prepared (when it is this
+  // campaign's report), and the previous brief carries field provenance.
+  const priorBriefInputs = priorBriefInputsForIntake({ reportPath, briefPath, identity: { spec: { map_id: mapId, ...(localSpecId ? { local_spec_id: localSpecId } : {}) }, campaign: { public_route_slug: publicRouteSlug } } });
   const buildBrief = createCampaignBuildBriefArtifact({
     inputPath: briefDiscovery?.path || null,
     inputSource: briefDiscovery?.source || null,
@@ -1799,10 +1832,19 @@ function prepareBuildUnderLock({
     templateFamily,
     sourceAssetCrawl,
     commerceZoneFindings,
+    boundReportMode: priorBriefInputs.boundReportMode,
+    previousNormalizedBrief: priorBriefInputs.previousNormalizedBrief,
   });
   if (buildBrief.inputPath && buildBrief.artifact?._meta) {
     buildBrief.artifact._meta.input_path = relFromFile(briefPath, buildBrief.inputPath);
   }
+  const briefBindings = briefIntakeBindings(buildBrief);
+  // The packet settings this run writes, checked against the packet on disk
+  // before anything is published.
+  const deploySettings = {
+    target: optionalString(args["deploy-target"], "unknown"),
+    preview_url: optionalString(args["preview-url"]),
+  };
   const buildBriefPrompts = buildBrief.mode === "prepared" ? [] : buildBrief.questions.map((question) => ({
     code: `BUILD_BRIEF_${toConstantCase(question.id)}`,
     stage: "prepare_build",
@@ -1836,6 +1878,11 @@ function prepareBuildUnderLock({
       }))
     : [];
   const designSourcePackage = publication.package({
+    plannedPacket: {
+      campaign: { allowed_domains_confirmed: args["allowed-domains-confirmed"] === true },
+      deploy: { ...deploySettings, production_url: optionalString(args["production-url"]) },
+      qa: { proof_policy: { order_path_depth: orderPathDepthFlag || "common" } },
+    },
     activePages,
     mappings: matched.mappings,
     manifestResult,
@@ -1887,6 +1934,7 @@ function prepareBuildUnderLock({
       normalized_path: relFromFile(packetPath, briefPath),
       question_count: buildBrief.questions.length,
       gate_count: buildBrief.gates.length,
+      ...briefBindings,
     },
     assembly: {
       implementation: "next-campaigns-build",
@@ -1914,8 +1962,7 @@ function prepareBuildUnderLock({
       compatible_outputs: ["static-html", "campaign-cart-sdk"],
     },
     deploy: {
-      target: optionalString(args["deploy-target"], "unknown"),
-      preview_url: optionalString(args["preview-url"]),
+      ...deploySettings,
       production_url: optionalString(args["production-url"]),
       live_url_path: liveUrlPath,
     },
@@ -2002,6 +2049,7 @@ function prepareBuildUnderLock({
       gate_count: buildBrief.gates.length,
       questions: buildBrief.questions,
       gates: buildBrief.gates,
+      ...briefBindings,
     },
     page_map: matched.mappings.map((mapping) => ({
       page_id: mapping.page_id,
@@ -2055,7 +2103,8 @@ function prepareBuildUnderLock({
 
   // The top-level status/next/blockers are derived from the stages by the same
   // function every later commit of the report runs (stage-ledger.mjs), so
-  // prepare-build's first write and a producer's last write spell them alike.
+  // prepare-build's first write and a producer's last write spell them alike,
+  // against the brief and CampaignSpec material this run binds.
   const report = applyDerivedAssemblyReportSummary(createAssemblyReport({
     packetPath,
     contextPath,
@@ -2072,7 +2121,7 @@ function prepareBuildUnderLock({
     buildScopeReasonsInvalid,
     templateSelection,
     evidence: strippedSpecBytes == null ? [] : hostStripped.evidence,
-  }));
+  }), { briefMaterial: briefBindings.material, specMaterial: specMaterialHash(spec) });
 
   // Values a spec left as it is still holds that doctor blocks on. An
   // absolute http(s) page_url is not among them: projection takes its path.
@@ -2643,7 +2692,7 @@ export function commitWaiverToAssemblyReport(workspace, mutate, options, { dryRu
     // run's own "do not write" is this wrapper's null below, not the mutator's.
     if (!isPlainObject(mutated)) throw new TypeError("commitAssemblyReport mutate(report) must return an Assembly Report object.");
     if (!dryRun) return mutated;
-    applyDerivedAssemblyReportSummary(mutated);
+    applyDerivedAssemblyReportSummary(mutated, currentPacketInputs({ packet: workspace.packet, packetPath: workspace.packetPath }));
     return null;
   };
   // A preview writes nothing, so it does not take the target lock either: the
@@ -2698,7 +2747,19 @@ export async function polishCaptureCommand(args, options = {}) {
     throw new Error(`polish capture needs an existing Assembly Report at ${reportPath}; run prepare-build/start first.`);
   }
   requireValidPolishCaptureReport(report, reportPath);
-  const plan = planPolishCapture({ packet, baseUrl });
+  // A campaign whose every mapping is template stock has no page_load route
+  // to capture: its plan error is held, and the capture measures readability
+  // on the built pages only, leaving page_load and media_weight as they are.
+  const { capturePolishReadability, isNoCapturableRoutesError } = await import("./polish-node.mjs");
+  const planOrHeld = (currentPacket) => {
+    try {
+      return { plan: planPolishCapture({ packet: currentPacket, baseUrl }), held: null };
+    } catch (error) {
+      if (!isNoCapturableRoutesError(error)) throw error;
+      return { plan: null, held: error };
+    }
+  };
+  const { plan, held: heldPlanError } = planOrHeld(packet);
   const initialBinding = createPolishCaptureBinding({
     packet,
     report,
@@ -2711,7 +2772,7 @@ export async function polishCaptureCommand(args, options = {}) {
   if (typeof createBrowserAdapter !== "function") {
     ({ createPolishBrowserAdapter: createBrowserAdapter } = await import("./polish-browser.mjs"));
   }
-  const capture = await capturePolishPageLoad({
+  const capture = await (heldPlanError ? capturePolishReadability : capturePolishPageLoad)({
     packet,
     report,
     baseUrl,
@@ -2721,7 +2782,11 @@ export async function polishCaptureCommand(args, options = {}) {
     adapterStartupDeadlineMs: options.adapterStartupDeadlineMs,
     captureCellDeadlineMs: options.captureCellDeadlineMs,
     adapterCloseDeadlineMs: options.adapterCloseDeadlineMs,
+    probeClock: options.probeClock,
+    targetRepo,
   });
+  // Nothing was measured: the held plan error stands.
+  if (heldPlanError && !capture.readability) throw heldPlanError;
 
   if (typeof options.afterCapture === "function") {
     await options.afterCapture({ packetPath, reportPath, targetRepo, capture });
@@ -2734,7 +2799,7 @@ export async function polishCaptureCommand(args, options = {}) {
   let checkpoint = null;
   commitAssemblyReport(workspace, (currentReport) => {
     requireValidPolishCaptureReport(currentReport, reportPath);
-    const currentPlan = planPolishCapture({ packet: currentPacket, baseUrl });
+    const { plan: currentPlan } = planOrHeld(currentPacket);
     const currentBinding = createPolishCaptureBinding({
       packet: currentPacket,
       report: currentReport,
@@ -2744,7 +2809,12 @@ export async function polishCaptureCommand(args, options = {}) {
     });
     assertPolishCaptureBindingUnchanged(initialBinding, currentBinding);
 
-    const merged = mergePolishCaptureEvidence(currentReport, { pageLoad: capture.page_load, mediaWeight: capture.media_weight });
+    const merged = mergePolishCaptureEvidence(currentReport, {
+      pageLoad: capture.page_load,
+      mediaWeight: capture.media_weight,
+      readability: capture.readability,
+      now: options.now ?? new Date(),
+    });
     checkpoint = evaluateRecordedHiddenEagerMediaCheckpoint({
       packet: currentPacket,
       report: merged,
@@ -2755,19 +2825,39 @@ export async function polishCaptureCommand(args, options = {}) {
     staleReason: `Package-owned polish page-load evidence changed after this doctor snapshot. Re-run ${cmd("doctor")} (or next) for current state.`,
   });
 
+  if (heldPlanError) {
+    // The readability capture completed; page_load's own outcome stays the
+    // held no_capturable_routes message, reported as a warning.
+    return {
+      ok: true,
+      status: "captured_with_warnings",
+      action: "polish-capture",
+      report_path: reportPath,
+      measurement: null,
+      checkpoint,
+      observed_findings: [],
+      warnings: [{ code: heldPlanError.code, message: heldPlanError.message }],
+      capture: {
+        route_scope: null,
+        routes: [],
+        viewports: [],
+        readability_routes: capture.readability?.subject?.routes ?? [],
+      },
+    };
+  }
   const ok = checkpoint.status === "pass" || checkpoint.status === "waived";
   return {
     ok,
     status: ok ? (checkpoint.status === "waived" ? "ready_with_waivers" : "ready") : "blocked",
     action: "polish-capture",
     report_path: reportPath,
-    measurement: capture.page_load.measurement,
+    measurement: capture.page_load?.measurement ?? null,
     checkpoint,
-    observed_findings: capture.page_load.findings,
+    observed_findings: capture.page_load?.findings ?? [],
     capture: {
-      route_scope: capture.plan.route_scope,
-      routes: capture.plan.routes.map((route) => route.requested_route),
-      viewports: capture.plan.viewports.map((viewport) => viewport.key),
+      route_scope: capture.plan?.route_scope ?? null,
+      routes: (capture.plan?.routes ?? []).map((route) => route.requested_route),
+      viewports: (capture.plan?.viewports ?? []).map((viewport) => viewport.key),
     },
   };
 }
@@ -3509,7 +3599,6 @@ export function specDeriveCommand(args, { store: storeRead = null } = {}) {
     store: storeFlags
       ? { subdomain: storeFlags.subdomain, admin_api: adminApiBaseForStore(storeFlags.subdomain), ...(storeFlags.token_env ? {} : { transport: "gateway", endpoint: "https://mcp.nextcommerce.com/admin/" }), token_source: storeFlags.token_env ? `env:${storeFlags.token_env}` : "gateway:login", store_read: null, pages_read: null, primary_domain: null }
       : null,
-    rebound: { build_context: null, assembly_report: null },
     errors: [],
     warnings: [],
     next: `${cmd("doctor")} --packet ${shellToken(packetPath)}`,
@@ -3743,17 +3832,15 @@ export function specDeriveCommand(args, { store: storeRead = null } = {}) {
       addIssue(result.warnings, "spec.derive.projection_stale", `A page route ${dryRun ? "would move" : "moved"}, and the packet's page-kit projection (source_html.pages[].page_kit) and the Build Context were prepared from the old routes. Re-run ${cmd("prepare-build")} (or start) before the next build so they describe the routes the spec carries.`);
     }
     if (stageIsTerminal(report?.stages?.assembly?.status)) {
-      addIssue(result.warnings, "spec.derive.build_stale", `The Assembly Report records a terminal build (stages.assembly.status ${report.stages.assembly.status}) rendered from the spec ${dryRun ? "this would rewrite" : "just rewritten"}. Re-run the build stage before polish, deploy or QA if a route or the pin moved; QA correlates its verdict against the spec identity the sidecars carry.`);
-      result.next = `${cmd("doctor")} --packet ${shellToken(packetPath)}, then rebuild: set stages.assembly.status back to "pending" on the Assembly Report and run ${cmd("next")} --packet ${shellToken(packetPath)}`;
+      addIssue(result.warnings, "spec.derive.build_stale", `The Assembly Report records a terminal build (stages.assembly.status ${report.stages.assembly.status}) rendered from the spec ${dryRun ? "this would rewrite" : "just rewritten"}. Bind the rewritten spec with ${cmd("record")} spec (it keeps stage history); next then routes back to the build, and Polish and QA are owed again.`);
     }
+    // spec derive writes the spec alone: the Build Context and the Assembly
+    // Report keep the identity they bound, so every recorded stage reads its
+    // stamps against the new content and `record spec` is what binds it.
+    if (report) result.next = `${cmd("record")} spec --packet ${shellToken(packetPath)} ${dryRun ? "after the write " : ""}to bind the derived spec (it keeps stage history), then ${cmd("next")} --packet ${shellToken(packetPath)}`;
   }
 
   if (plan.changes.length && !dryRun) {
-    // The identity the sidecars bound to the spec BEFORE this write, so the
-    // re-bind below can tell "bound to the spec being replaced" from "already
-    // drifted" and only ever moves the former.
-    const beforeRawHash = createHash("sha256").update(text).digest("hex");
-    const beforeMaterialHash = specMaterialHash(spec);
     // The plan already refused every path its containers cannot take, so a
     // throw here is a defect in this toolkit rather than in the spec; it is
     // still a structured error, never a crash past the --json contract.
@@ -3791,82 +3878,7 @@ export function specDeriveCommand(args, { store: storeRead = null } = {}) {
       rmSync(tmpPath, { force: true });
     }
     result.written = true;
-    // The Build Context and the Assembly Report carry the spec's identity
-    // (raw and material hashes) from prepare-build, and QA's verdict is
-    // correlated against the material hash by the bundle check. Each sidecar
-    // that was bound to the spec just replaced is re-bound to the new one;
-    // one that already carried another identity is left as it is and named.
-    const afterRawHash = createHash("sha256").update(serialized).digest("hex");
-    const afterMaterialHash = specMaterialHash(spec);
-    const boundToOld = (raw, material) => raw === beforeRawHash || material === beforeMaterialHash;
-    // A sidecar is re-bound only when it names the spec being written: two
-    // packets sharing a target repo can carry byte-identical spec exports,
-    // and a matching hash alone would let one packet's derive re-bind the
-    // other's sidecar to a spec it never used.
-    const namesThisSpec = (recorded) => {
-      if (!isNonEmptyString(recorded)) return false;
-      try {
-        return realpathSync(resolve(targetRepo, recorded)) === realSpecPath;
-      } catch {
-        return false;
-      }
-    };
-    const contextPath = workspace?.contextPath || null;
-    let context = null;
-    try {
-      context = contextPath ? readJsonIfExists(contextPath) : null;
-    } catch (error) {
-      result.rebound.build_context = false;
-      addIssue(result.warnings, "spec.derive.identity_not_rebound", `The Build Context could not be read (${singleLineDetail(error.message)}); its spec identity was not updated. Re-run prepare-build before QA so the bundle correlates.`);
-    }
-    if (isObject(context?.spec)) {
-      if (!namesThisSpec(context.spec.path)) {
-        result.rebound.build_context = false;
-        addIssue(result.warnings, "spec.derive.identity_not_rebound", "The Build Context names a different spec file than the one derive wrote (another packet's, or a moved export); it was left as it is. Re-run prepare-build before QA so the bundle correlates.");
-      } else if (boundToOld(context.spec.hash, context.spec.material_hash)) {
-        try {
-          writeJsonAtomic(contextPath, { ...context, spec: { ...context.spec, hash: afterRawHash, material_hash: afterMaterialHash } });
-          result.rebound.build_context = true;
-        } catch (error) {
-          result.rebound.build_context = false;
-          addIssue(result.warnings, "spec.derive.identity_not_rebound", `The Build Context's spec identity could not be updated (${singleLineDetail(error.message)}); re-run prepare-build before QA so the bundle correlates.`);
-        }
-      } else {
-        result.rebound.build_context = false;
-        addIssue(result.warnings, "spec.derive.identity_not_rebound", `The Build Context's spec identity was already bound to a different spec than the one derive replaced; it was left as it is. Re-run prepare-build before QA so the bundle correlates.`);
-      }
-    }
-    if (report && isObject(report.identity) && workspace) {
-      if (!namesThisSpec(report.inputs?.spec_path)) {
-        result.rebound.assembly_report = false;
-        addIssue(result.warnings, "spec.derive.identity_not_rebound", "The Assembly Report names a different spec file than the one derive wrote (another packet's, or a moved export); it was left as it is. Re-run prepare-build before QA so the bundle correlates.");
-      } else if (boundToOld(report.identity.spec_hash, report.identity.spec_material_hash)) {
-        try {
-          // The identity is re-checked on the report as it is re-read for
-          // the commit, so a prepare-build that re-bound it in the meantime
-          // is left alone.
-          const committed = commitAssemblyReport(workspace, (current) => (
-            isObject(current.identity) && boundToOld(current.identity.spec_hash, current.identity.spec_material_hash)
-              ? { ...current, identity: { ...current.identity, spec_hash: afterRawHash, spec_material_hash: afterMaterialHash } }
-              : null
-          ), {
-            command: "spec derive",
-            staleReason: `spec derive rewrote the CampaignSpec after this doctor snapshot. Re-run ${cmd("doctor")} (or next) for current state.`,
-          });
-          result.rebound.assembly_report = committed.written;
-          if (!committed.written) addIssue(result.warnings, "spec.derive.identity_not_rebound", "The Assembly Report's spec identity moved while spec derive was running; it was left as it is. Re-run prepare-build before QA so the bundle correlates.");
-        } catch (error) {
-          result.rebound.assembly_report = false;
-          addIssue(result.warnings, "spec.derive.identity_not_rebound", `The Assembly Report's spec identity could not be updated (${singleLineDetail(error.message)}); re-run prepare-build before QA so the bundle correlates.`);
-        }
-      } else {
-        result.rebound.assembly_report = false;
-        addIssue(result.warnings, "spec.derive.identity_not_rebound", `The Assembly Report's spec identity was already bound to a different spec than the one derive replaced; it was left as it is. Re-run prepare-build before QA so the bundle correlates.`);
-      }
-    }
     // The retained doctor snapshot (if any) now predates the spec it judged.
-    // commitAssemblyReport stamps it when the report was re-bound; every
-    // other path stamps it here.
     try {
       markDoctorSidecarStale(targetRepo, {
         command: "spec derive",
@@ -4245,6 +4257,8 @@ export function nextStage(stage, args, ambient = null, { qcStandIns = null, qcRe
     followContextPointer: true,
   });
   const report = readJsonIfExists(reportPath);
+  // The campaign intent summary, computed once per call and only printed.
+  const intentSummary = readIntentSummary(packetPath, packet, contextPath);
   // Doctor reads the same sidecars through the same resolver (an operator's
   // explicit --context / --report passed through, the defaults derived), so
   // its prepare-build gate and its stage pick are this command's: `next`
@@ -4330,6 +4344,7 @@ export function nextStage(stage, args, ambient = null, { qcStandIns = null, qcRe
     } });
     if (divergences.length) result.divergences = divergences;
     result.gates = buildNextGates({ doctor, report, themeGate, polishGate, prepareBuildGate, packetPath });
+    if (doctor.derived?.input_currency) result.input_currency = doctor.derived.input_currency;
     result.next_actions = buildNextActions({ result, packetPath, packet, themeGate, polishGate, polishCheckpointGate, prepareBuildGate, ambient, runRecordCloseout, purchaseProof, brandContract: doctor.derived?.brand_contract || null, context: readJsonIfExists(contextPath), targetRepo, spec });
     // The QC handoff: read from data already loaded plus the
     // full QA verdict the QA stage names. It adds nothing to errors[],
@@ -4338,7 +4353,11 @@ export function nextStage(stage, args, ambient = null, { qcStandIns = null, qcRe
     // one (from --report or the Build Context pointer), so it records there.
     const qc = readCurrentQcResults({ report, doctor, spec, targetRepo, packetPath, reportPath, qcStandIns, rederivers: qcRederivers });
     result.qc_handoff = buildQcHandoff({ results: qc.results, coverage: qc.coverage, accepts: report?.qc_accepts, packetPath, reportPath: explicitReportPath(reportPath, targetRepo) });
+    // One note per operator decision that kept the build output unchanged
+    // after an input change, quoting the operator's reason.
+    for (const issue of doctor.warnings) if (issue.code === "assembly.output_unchanged_by_operator_decision") (result.qc_handoff.notes ||= []).push(`Build output kept unchanged after an input change by the operator's decision: "${issue.detail.reason}"`);
     recordNextRecommendation(ambient, result);
+    result.intent_summary = intentSummary;
     return result;
   };
   const doctorHasOnlyPolishGateErrors = doctorErrorsAreOnlyPolishGate(doctor.errors);
@@ -4430,12 +4449,12 @@ export function nextStage(stage, args, ambient = null, { qcStandIns = null, qcRe
   if (stage === "setup") {
     addPrepareBuildGateErrors(errors, report);
     if (!doctor.ok && !doctorHasOnlyPolishGateErrors) addIssue(errors, "next.setup.doctor", "Doctor is blocked; resolve packet errors before setup.");
-    prompt = setupPrompt(packetPath, contextPath, reportPath, packet);
+    prompt = setupPrompt(packetPath, contextPath, reportPath, packet, intentSummary);
   } else if (stage === "build") {
     addPrepareBuildGateErrors(errors, report);
     if (!doctor.ok && !doctorHasOnlyPolishGateErrors) addIssue(errors, "next.build.doctor", "Doctor is blocked; resolve packet errors before build.");
     if (doctor.derived?.scaffold_required) addIssue(errors, "next.build.setup", doctor.derived.scaffold_reason || "Setup is required before build.");
-    prompt = buildPrompt(packetPath, contextPath, reportPath, packet, doctor.derived);
+    prompt = buildPrompt(packetPath, contextPath, reportPath, packet, doctor.derived, intentSummary);
   } else if (stage === "polish") {
     addPrepareBuildGateErrors(errors, report);
     if (!report) addIssue(errors, "next.polish.report", "Assembly report is required before polish.");
@@ -4443,7 +4462,7 @@ export function nextStage(stage, args, ambient = null, { qcStandIns = null, qcRe
     if (!assemblyStatus.startsWith("completed")) addIssue(errors, "next.polish.assembly", `Assembly status is "${assemblyStatus || "missing"}"; polish expects completed assembly or an explicit blocked/skipped handoff.`);
     if (polishGateRequiresBuild(polishGate)) addPolishGateErrors(errors, polishGate, "polish");
     addThemeGateErrors(errors, themeGate, "polish");
-    prompt = polishPrompt(packetPath, reportPath, packet);
+    prompt = polishPrompt(packetPath, reportPath, packet, intentSummary);
   } else if (stage === "deploy") {
     addPrepareBuildGateErrors(errors, report);
     // Slice 3 Phase 2: deploy is an out-of-band step (Netlify / CF Pages /
@@ -4462,7 +4481,7 @@ export function nextStage(stage, args, ambient = null, { qcStandIns = null, qcRe
     addPolishGateErrors(errors, polishGate, "qa");
     addPolishCheckpointGateErrors(errors, polishCheckpointGate, "qa");
     addThemeGateErrors(errors, themeGate, "qa");
-    prompt = qaPrompt(packetPath, reportPath, packet, spec);
+    prompt = qaPrompt(packetPath, reportPath, packet, spec, intentSummary);
   }
   const status = errors.length
     ? "blocked"
@@ -4757,6 +4776,11 @@ export function buildNextActions({ result, packetPath, packet, themeGate, polish
     push(inspect.id, inspect.kind, asInvocation(inspect.command), inspect.description, { required: inspect.required });
     return actions;
   }
+  for (const subcommand of inputRefreshCommands(result.input_currency)) {
+    push("refresh_inputs", "command", `${cmd("record")} ${subcommand} --packet ${shellToken(packetPath)} --json`, subcommand === "brief"
+      ? "A recorded stage was made against earlier Campaign Build Brief content: save the brief with record brief (keeps stage history), then re-run next."
+      : "A recorded stage was made against earlier CampaignSpec content: bind it with record spec (keeps stage history), then re-run next.");
+  }
   if (result.stage === "doctor-blocked") {
     const checkpointGates = (result.gates || []).filter(
       (gate) => gate?.status === "blocked" && Object.hasOwn(CHECKPOINT_EVALUATORS, gate?.id || ""),
@@ -5008,9 +5032,9 @@ function templateStockPromptLine(packet, derived = {}) {
   return `\n- Template-stock pages (declared out of source scope; no design source exists for them): ${pages.join(", ")}. Keep these routes unbuilt by default, especially presell/landing pages staying on another host; never publish stock placeholder copy to fill a partial build. Materialise a page only with explicit operator opt-in for that page (including a pre-checkout select stand-in required by the runtime). For opted-in pages, use the ${packet.assembly.template_family} family's own page for that role with its dependent _includes, _layouts, and assets, wire it from CampaignSpec, and build a required select step first. Once its built HTML exists, doctor lists it among the previewable routes.`;
 }
 
-function buildPrompt(packetPath, contextPath, reportPath, packet, derived = {}) {
+function buildPrompt(packetPath, contextPath, reportPath, packet, derived = {}, intent) {
   const briefPath = packet.build_brief?.normalized_path || "(missing; generate or confirm Campaign Build Brief before business-sensitive assembly)";
-  return `Use next-campaigns-build for this Campaigns OS handoff.
+  return `${campaignIntentPromptHeader(intent)}Use next-campaigns-build for this Campaigns OS handoff.
 
 Read first:
 - Build Packet: ${packetPath}
@@ -5023,6 +5047,7 @@ Read first:
 Rules:
 - Treat CampaignSpec/API as the source for package, shipping, voucher, payment, tracking, footer, and SEO values.
 - Treat the Campaign Build Brief as the merchandising/design presentation truth: page authority, palette/CTA style, variant media rules, pricing display strategy, the template's own promo placeholders, payment/trust surfaces, display-name policy, residue policy, and QA expectations. Agents may resolve implementation uncertainty; unresolved brief questions are business uncertainty and should be asked or recorded, not guessed.
+- Refresh a changed Campaign Build Brief with \`${cmd("record")} brief --packet ${packetPath}\` and a changed CampaignSpec with \`${cmd("record")} spec --packet ${packetPath}\` before building on the change.
 - Read the selected template family's agentContract and sharedFrontmatterVocabulary before commerce wiring.
 - Prepared AI/exported HTML must be converted into page-kit-ready source first: keep page-owned body markup, strip document wrappers, add YAML frontmatter, move shared CSS/assets into the campaign structure, and use Liquid helpers only for page-kit links/assets/includes. Page Kit publishes src/<slug>/assets/config.js as /<slug>/config.js and src/<slug>/assets/products/foo.png as /<slug>/products/foo.png; do not leave raw /assets/... or /<slug>/assets/... references in rendered pages.
 - Preserve prepared source HTML for landing/presell pages when it is a real standalone design.
@@ -5049,9 +5074,44 @@ function localProofPromptLines(packet, packetPath = "<packet>") {
 - Local proof mode (deploy.target is local-serve): run the page-kit build in the ${LOCAL_PROOF_BUILD_ENVIRONMENT} environment — \`${LOCAL_PROOF_BUILD_COMMAND}\` — so _site/ is the development render, and record it with \`${cmd("record")} build --packet ${packetPath} --build-environment ${LOCAL_PROOF_BUILD_ENVIRONMENT}\`, which sets ${LOCAL_PROOF_BUILD_ENVIRONMENT_FIELD} to "${LOCAL_PROOF_BUILD_ENVIRONMENT}" on the assembly report (never hand-edit it). The starter templates gate every vendor loader on the environment and several loaders are protocol-relative (//host/...), which fail over a plain-HTTP local serve; the SDK's dl_* events still fire in development. Polish capture, browser QA and typed-card orders run against this served output. Before committing, run \`${asInvocation(LOCAL_PROOF_PARITY_COMMAND)}\` to prove the production render differs only in environment-gated output and pins the same Campaign Cart version; the PR preview is the second check. ${LOCAL_PROOF_NEVER_EDIT_RULE}`;
 }
 
-function setupPrompt(packetPath, contextPath, reportPath, packet) {
+// Read the normalized brief the packet records, resolved against the packet
+// file as doctor resolves it, and summarize it over the Build Context's active
+// pages in recorded order. A missing, unreadable or invalid brief reads
+// unavailable; this never fails `next`. Each read or summarising failure is
+// named on stderr, one line per failure, never on stdout.
+function readIntentSummary(packetPath, packet, contextPath) {
+  const reportFailure = (error) => process.stderr.write(`campaigns-os: intent summary unavailable: ${singleLineFragment(error?.message ?? error, "unknown error")}\n`);
+  const normalizedPath = resolveFromFile(packetPath, packet?.build_brief?.normalized_path);
+  let brief = null;
+  try {
+    brief = readJsonIfExists(normalizedPath);
+  } catch (error) {
+    reportFailure(error);
+    brief = null;
+  }
+  let activePageIds = [];
+  try {
+    const activePages = readJsonIfExists(contextPath)?.spec?.active_pages;
+    activePageIds = Array.isArray(activePages) ? activePages.map((page) => page?.id) : [];
+  } catch (error) {
+    reportFailure(error);
+    activePageIds = [];
+  }
+  return { ...summarizeCampaignBrief({ brief, activePageIds, onError: reportFailure }), normalized_path: normalizedPath };
+}
+
+// The setup, build, Polish and QA prompts start with the campaign intent
+// summary, framed as orientation only.
+function campaignIntentPromptHeader(intent) {
+  return `Campaign intent (from the Campaign Build Brief at ${intent.normalized_path || "(not recorded)"}; orientation only, never a source of prices or commerce behaviour):
+${intent.text}
+
+`;
+}
+
+function setupPrompt(packetPath, contextPath, reportPath, packet, intent) {
   const briefPath = packet.build_brief?.normalized_path || "(missing)";
-  return `Use next-campaigns-os-setup for this Campaigns OS handoff.
+  return `${campaignIntentPromptHeader(intent)}Use next-campaigns-os-setup for this Campaigns OS handoff.
 
 Read first:
 - Build Packet: ${packetPath}
@@ -5070,9 +5130,9 @@ When copying a starter template family, copy the family as an atomic page-kit sl
 Do not wire checkout, upsell, receipt, payment, package, voucher, or shipping behavior during setup.`;
 }
 
-function polishPrompt(packetPath, reportPath, packet) {
+function polishPrompt(packetPath, reportPath, packet, intent) {
   const briefPath = packet.build_brief?.normalized_path || "(missing)";
-  return `Use next-campaigns-polish for this built campaign.
+  return `${campaignIntentPromptHeader(intent)}Use next-campaigns-polish for this built campaign.
 
 Read first:
 - Build Packet: ${packetPath}
@@ -5215,14 +5275,14 @@ function orderBumpRunReason(bumpCart) {
   return `The checkout declares order bump ${bumpCart.bumps.join(", ")} (is_order_bump or is_upsell), and the default run never puts it in a test order. This run repeats QA with ${cart} in the cart.`;
 }
 
-function qaPrompt(packetPath, reportPath, packet, spec = null) {
+function qaPrompt(packetPath, reportPath, packet, spec = null, intent) {
   const url = packet.deploy?.preview_url || packet.deploy?.production_url || "<preview-url>";
   const briefPath = packet.build_brief?.normalized_path || "(missing)";
   const bumpCart = checkoutOrderBumpCart(spec);
   const bumpCommand = bumpCart
     ? `\n\nOrder bump QA command (proves the charged add-on):\n${qaRunCommand(packetPath, url, bumpCart)}\n${orderBumpRunReason(bumpCart)}`
     : "";
-  return `Use next-campaigns-qa for this deployed campaign.
+  return `${campaignIntentPromptHeader(intent)}Use next-campaigns-qa for this deployed campaign.
 
 ${packet.spec.local_spec_id ? "Local spec ID" : "Map ID"}: ${packet.spec.local_spec_id || packet.spec.map_id}
 Base URL: ${url}
@@ -6396,7 +6456,7 @@ function safePolishByteCount(value) {
 }
 
 export function formatPolishCaptureText(result) {
-  const status = ["ready", "ready_with_waivers", "blocked"].includes(result?.status)
+  const status = ["ready", "ready_with_waivers", "captured_with_warnings", "blocked"].includes(result?.status)
     ? result.status
     : "unknown";
   const measurementStatus = ["complete", "incomplete"].includes(result?.measurement?.status)
@@ -6410,6 +6470,11 @@ export function formatPolishCaptureText(result) {
     `Status: ${status.toUpperCase()}`,
     `Measurement: ${measurementStatus.toUpperCase()}`,
   ];
+  // Outcomes that did not stop the capture, printed with their own message
+  // (the held page-load plan message on a campaign with no mapped pages).
+  for (const warning of Array.isArray(result?.warnings) ? result.warnings : []) {
+    if (warning?.code === "no_capturable_routes" && typeof warning.message === "string") lines.push(`Warning: ${warning.message}`);
+  }
   const incomplete = Array.isArray(result?.measurement?.incomplete)
     ? result.measurement.incomplete
     : [];
@@ -8411,6 +8476,8 @@ const WAIVE_ACTIONS = new Set(["theme-waive", "checkpoint-waive"]);
 // check's readiness line); they are text-only and never enter the JSON result.
 export function resultTextLines(result, { headerLines = [] } = {}) {
   const lines = [`Status: ${String(result.status || "unknown").toUpperCase()}`, ...headerLines];
+  // `next` only: the campaign intent summary, directly under the status.
+  if (result.intent_summary) lines.push("Campaign intent:", ...result.intent_summary.text.split("\n"));
   // A waive command's second line names what it recorded; the third is the
   // stage doctor now picks for the report the waiver was written to.
   if (WAIVE_ACTIONS.has(result.action) && result.gate) {