@nextcommerce/campaigns-os 1.52.0 → 1.53.0

package/src/design-source-publication.mjs

@@ -7,7 +7,11 @@ import { writeThemeArtifacts } from "./brand-theme.mjs";
 import { cloneJson, filesystemPathsMatch, isObject, isNonEmptyString, optionalString, readJson, resolveFromFile, sha256File } from "./cli-helpers.mjs";
 import { DESIGN_SOURCE_PACKAGE_REL_PATH, createDesignSourcePackageArtifactReference, hashSerializedDesignSourcePackage, serializeDesignSourcePackage, synthesizeHtmlFunnelDesignSourcePackage, validateDesignSourcePackage } from "./design-source-package.mjs";
 import { stampDoctorProducer } from "./doctor-sidecar.mjs";
+import { stageWriteInputs } from "./input-currency.mjs";
+import { cmd } from "./install-invocation.mjs";
 import { ASSEMBLY_REPORT_STAGE_KEYS } from "./orchestration-stage-contract.mjs";
+import { HOST_STRIPPED_CODE } from "./source-html-intake.mjs";
+import { archiveForForceReset, stageHistoryPresent } from "./stage-ledger.mjs";
 import { targetLockPath, withTargetLock } from "./target-lock.mjs";
 import { resolveTemplateFamilyDesignSource } from "./template-reference.mjs";
 
@@ -71,12 +75,93 @@ function guardAssemblyReportOverwrite(reportPath, args, { announced = null } = {
   const unannounced = announced ? stageKeys.filter((key) => !announced.includes(key)) : stageKeys;
   if (unannounced.length > 0) {
     console.warn(
-      `[campaigns-os prepare-build] --force: overwriting assembly report at ${reportPath}; clearing stage evidence for: ${unannounced.join(", ")}.`,
+      `[campaigns-os prepare-build] --force: overwriting assembly report at ${reportPath}; clearing stage evidence for: ${unannounced.join(", ")}. Completed build, Polish and QA records are archived into their stage history, which is kept.`,
     );
   }
   return stageKeys;
 }
 
+// Operator state on the report an intake would replace, one line per item:
+// recorded waivers and warning accepts, stage history, an applied theme, and
+// report evidence other than intake's own host-strip lines.
+function assemblyReportOperatorState(existingReport) {
+  if (!isObject(existingReport)) return [];
+  const items = [];
+  const count = (value) => (Array.isArray(value) ? value.length : 0);
+  if (count(existingReport.waivers)) items.push(`waivers (${count(existingReport.waivers)} recorded waiver${count(existingReport.waivers) === 1 ? "" : "s"})`);
+  if (count(existingReport.qc_accepts)) items.push(`qc_accepts (${count(existingReport.qc_accepts)} recorded warning accept${count(existingReport.qc_accepts) === 1 ? "" : "s"})`);
+  if (stageHistoryPresent(existingReport)) items.push("stage history (superseded build, Polish or QA records)");
+  if (existingReport.theme?.status === "applied") items.push("theme (status applied)");
+  const evidence = Array.isArray(existingReport.evidence) ? existingReport.evidence.filter((entry) => !(isObject(entry) && entry.code === HOST_STRIPPED_CODE)) : [];
+  if (evidence.length) items.push(`evidence (${evidence.length} recorded line${evidence.length === 1 ? "" : "s"})`);
+  return items;
+}
+
+// Packet settings recorded since the last intake that this run would
+// overwrite (every setting `qa policy set` records): each named with the
+// value on disk and the value this run writes.
+const INTAKE_PACKET_SETTINGS = Object.freeze([
+  ["deploy.target", (packet) => packet?.deploy?.target],
+  ["deploy.preview_url", (packet) => packet?.deploy?.preview_url],
+  ["deploy.production_url", (packet) => packet?.deploy?.production_url],
+  ["qa.proof_policy.order_path_depth", (packet) => packet?.qa?.proof_policy?.order_path_depth],
+  ["campaign.allowed_domains_confirmed", (packet) => packet?.campaign?.allowed_domains_confirmed],
+]);
+
+function packetSettingChanges(packetPath, planned) {
+  if (!isObject(planned) || !existsSync(packetPath)) return [];
+  let existing;
+  try {
+    existing = readJson(packetPath);
+  } catch {
+    return [];
+  }
+  const items = [];
+  for (const [field, read] of INTAKE_PACKET_SETTINGS) {
+    const onDisk = read(existing) ?? null;
+    const written = read(planned) ?? null;
+    if (onDisk !== written) items.push(`${field} (recorded ${JSON.stringify(onDisk)}; this run would write ${JSON.stringify(written)})`);
+  }
+  return items;
+}
+
+// Intake replaces the report and packet whole, so recorded operator state
+// would be lost silently. Without --force it refuses and names each item;
+// with --force it names each item as cleared (once).
+function guardIntakeOperatorState(reportPath, packetPath, { force, planned = null, announced = [] }) {
+  let existingReport = null;
+  try {
+    existingReport = existsSync(reportPath) ? readJson(reportPath) : null;
+  } catch {
+    existingReport = null;
+  }
+  const items = [...assemblyReportOperatorState(existingReport), ...packetSettingChanges(packetPath, planned)];
+  if (!items.length) return announced;
+  if (force !== true) {
+    throw new Error(
+      `Rerunning prepare-build/start/build would discard recorded operator state: ${items.join("; ")}. `
+      + `To save brief answers or a CampaignSpec change without discarding anything, run ${cmd("record")} brief or ${cmd("record")} spec instead. `
+      + "To rerun intake anyway, pass the original deploy and order-path flags, or --force to clear the listed state (destructive; completed build, Polish and QA records are archived into stage history). "
+      + `After --force, record a cleared packet setting again with ${cmd("qa")} policy set.`,
+    );
+  }
+  const unannounced = items.filter((item) => !announced.includes(item));
+  if (unannounced.length) {
+    console.warn(`[campaigns-os prepare-build] --force: clearing recorded operator state: ${unannounced.join("; ")}.`);
+  }
+  return [...announced, ...unannounced];
+}
+
+// The report this run replaces, read for the --force archive; null when there
+// is none or it cannot be read.
+function readReplacedReport(reportPath) {
+  try {
+    return existsSync(reportPath) ? readJson(reportPath) : null;
+  } catch {
+    return null;
+  }
+}
+
 function artifactRelativePath(artifactPath, targetPath) {
   const rel = relative(dirname(resolve(artifactPath)), resolve(targetPath)).replaceAll("\\", "/");
   return rel || ".";
@@ -806,12 +891,20 @@ export async function withDesignSourcePublication({ targetRepo, outputs, force =
     // fetched, and a run waiting here cannot replace it meanwhile.
     publishSpec?.();
     let announcedStageEvidence = guardAssemblyReportOverwrite(reportPath, { force });
+    // Operator state is checked once the run knows the packet settings it
+    // would write, before the package.
+    let plannedPacketSettings = null;
+    let announcedOperatorState = null;
+    const checkOperatorState = () => {
+      announcedOperatorState = guardIntakeOperatorState(reportPath, packetPath, { force, planned: plannedPacketSettings, announced: announcedOperatorState || [] });
+    };
     // Stage producers commit the report without this lock, so evidence can land
     // while the run works. Re-check before each write that is not rolled back:
     // the theme artifacts, then the JSON outputs. --force names a stage once.
     const recheckStageEvidence = () => {
       const found = guardAssemblyReportOverwrite(reportPath, { force }, { announced: announcedStageEvidence });
       announcedStageEvidence = [...new Set([...announcedStageEvidence, ...found])];
+      checkOperatorState();
     };
     let completed = 0;
     const enter = (index, { once = false } = {}) => {
@@ -821,8 +914,13 @@ export async function withDesignSourcePublication({ targetRepo, outputs, force =
     let designSourcePackage = null;
     return fn(Object.freeze({
       paths,
-      package(inputs) {
+      // `plannedPacket`: the part of the packet this run would write that
+      // carries the settings INTAKE_PACKET_SETTINGS names, checked against
+      // the packet on disk.
+      package({ plannedPacket = null, ...inputs }) {
         enter(0, { once: true });
+        plannedPacketSettings = plannedPacket;
+        checkOperatorState();
         // Reject deterministic destination failures before publishing the fixed
         // DSP. The DSP intentionally precedes the theme and JSON artifacts that
         // reference it; a later I/O race may therefore leave a valid DSP for a
@@ -858,8 +956,17 @@ export async function withDesignSourcePublication({ targetRepo, outputs, force =
         completed = Math.max(completed, 2);
         return written;
       },
-      publish({ packet, brief, context, report }) {
+      publish({ packet, brief, context, report: reseeded }) {
         enter(2, { once: true });
+        // The records this run replaces stay visible: completed build, Polish
+        // and QA records go to their stage history (only --force reaches here
+        // with any), and each stage's history and input change carry over.
+        const now = new Date().toISOString();
+        const bound = { briefMaterial: reseeded?.build_brief?.material ?? null, specMaterial: reseeded?.identity?.spec_material_hash ?? null };
+        const report = archiveForForceReset(readReplacedReport(reportPath), reseeded, {
+          now,
+          detectChange: (key, record) => stageWriteInputs(key, bound).detectChange(record),
+        });
         // Before the report goes out, narrow the pending record to exactly what the
         // report will say: the package's own hash when it is synthesized, nothing
         // when it is adopted. A candidate this run or an earlier failed one never

package/src/doctor/checks.mjs

@@ -1,6 +1,7 @@
 // Doctor checks: the check registries, validatePacket and the validators they run.
 import { campaignSpecIdentity, resolveCampaignIdentity, campaignIdentitiesMatch } from "../spec-source-identity.mjs";
 import { withHtmlScanSnapshot, readHtmlScanText } from "../html-scan.mjs";
+import { createHash } from "node:crypto";
 import { accessSync, constants as fsConstants, existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { describeSdkIgnoredMetaTags, isSdkIgnoredMetaTag } from "../sdk-meta-tags.mjs";
@@ -90,6 +91,7 @@ import { SMOKE_QC, SMOKE_QC_LIMITS, builtFileOf, evaluateSmokeQc, insideRoot, is
 import { recordQcResults } from "../qc-results.mjs";
 import { FIGMA_EXPORT_FILE_CODES, SOURCE_PROVENANCE_SCOPE, evaluateSourceProvenanceGates, generatorClaimsFigmaExport, isSourceProvenanceCode } from "./source-provenance.mjs";
 import { validateCampaignBuildBriefArtifact } from "../build-brief.mjs";
+import { briefFileUnusable, deriveInputCurrency, wellFormedBriefMaterial } from "../input-currency.mjs";
 import { ASSEMBLY_REPORT_STAGE_KEYS, stageIsTerminal } from "../orchestration-stage-contract.mjs";
 import {
   assemblySourcePackageFingerprintMissing,
@@ -511,7 +513,10 @@ const PACKET_DOCTOR_CHECKS = createDoctorCheckRegistry([
   {
     id: "build_brief.artifact",
     phase: "brief",
-    run: ({ packet, packetPath, spec, context, errors, warnings, ready }) => validateBuildBrief(packet, packetPath, spec, context, errors, warnings, ready),
+    run: ({ packet, packetPath, spec, context, report, errors, warnings, ready, derived }) => {
+      validateBuildBrief(packet, packetPath, spec, context, errors, warnings, ready);
+      validateInputCurrency({ packet, packetPath, spec, report, warnings, derived });
+    },
   },
 ], { registryId: "packet.always" });
 
@@ -731,22 +736,20 @@ function validatePacket(packet, packetPath, errors, warnings, ready, derived, bu
     }
     buildState.specStatus = specStatus;
     if (specStatus === "ok") {
-      const specMapId = spec.spec_identity?.map_id || spec.map_id;
-      if ((specMapId && specMapId !== packet.spec.map_id)
-        || ((spec.spec_identity?.local_spec_id != null || packet.spec?.local_spec_id != null)
-          && !campaignIdentitiesMatch(campaignSpecIdentity(spec), packet.spec))) {
-        const localIdentity = spec.spec_identity?.local_spec_id != null || packet.spec?.local_spec_id != null;
-        addIssue(errors, localIdentity ? "spec.local_identity" : "spec.map_id", "Packet identity does not match the CampaignSpec map_id/local_spec_id.", { kind: localIdentity ? "local_spec" : "saved_map" });
+      const identityKind = specIdentityMismatch(spec, packet.spec);
+      if (identityKind) {
+        addIssue(errors, identityKind === "local_spec" ? "spec.local_identity" : "spec.map_id", "Packet identity does not match the CampaignSpec map_id/local_spec_id.", { kind: identityKind });
       }
       ready.push("Local CampaignSpec parsed");
-      // QA refuses a local-spec run whose spec no longer has the material hash
-      // prepare-build bound on the Assembly Report; doctor (and next, which
-      // prints doctor's warnings) name it at the first read instead.
+      // The spec no longer has the material hash the Assembly Report binds:
+      // a local spec, or the copy a saved-Map or gateway packet fetched.
+      // Doctor (and next, which prints doctor's warnings) name it at the
+      // first read.
       const boundMaterialHash = buildState.report?.identity?.spec_material_hash;
-      if (packet.spec?.local_spec_id != null && isNonEmptyString(boundMaterialHash)) {
+      if (isNonEmptyString(boundMaterialHash)) {
         const currentMaterialHash = specMaterialHash(spec);
         if (!specHashesMatch(boundMaterialHash, currentMaterialHash)) {
-          addIssue(warnings, "spec.material_stale", `The CampaignSpec at ${localSpecPath} changed materially since prepare-build bound it (Assembly Report identity.spec_material_hash ${boundMaterialHash}; the spec now hashes to ${currentMaterialHash}). The build and its recorded evidence predate the edit, and QA refuses a stale spec. Re-run ${cmd("prepare-build")} from the edited spec before building on it further.`, { spec_path: localSpecPath, bound_material_hash: boundMaterialHash, current_material_hash: currentMaterialHash });
+          addIssue(warnings, "spec.material_stale", SPEC_MATERIAL_STALE_MESSAGE, { spec_path: localSpecPath, bound_material_hash: boundMaterialHash, current_material_hash: currentMaterialHash });
         }
       }
       runDoctorChecks(SPEC_DOCTOR_CHECKS, { packet, packetPath, spec, targetRepo, errors, warnings, ready, derived, buildState });
@@ -762,6 +765,9 @@ function validatePacket(packet, packetPath, errors, warnings, ready, derived, bu
   if (synthesizedBuiltSite) {
     ready.push("Packet source/proof checks skipped for synthesized built-site packet");
   } else {
+    // Computed once, before the checks that read it (the QA gate pass the
+    // built-output residue scan defers to) and the input warnings below.
+    derived.input_currency = deriveInputCurrency({ packet, packetPath, report: buildState.report, spec: isObject(spec) ? spec : null });
     runDoctorChecks(PACKET_DOCTOR_CHECKS, { packet, packetPath, spec, context: buildState.context, report: buildState.report, errors, warnings, ready, derived, buildState });
   }
 
@@ -781,6 +787,25 @@ function validatePacket(packet, packetPath, errors, warnings, ready, derived, bu
   // stage progression.
 }
 
+// A stage's spec stamp, as record build, record polish and the QA write store it.
+const SPEC_STAMP = /^sha256:[0-9a-f]{64}$/;
+const SPEC_MATERIAL_STALE_MESSAGE = "CampaignSpec material changed since it was bound; run `record spec` (keeps history). `prepare-build --force` resets every stage and archives their records.";
+
+/**
+ * Whether a parsed CampaignSpec names another campaign than `bound` (the
+ * packet's spec block, or an Assembly Report identity): null when they
+ * agree, otherwise the kind of identity that differs ("local_spec" when
+ * either side carries a local spec id, else "saved_map").
+ */
+export function specIdentityMismatch(spec, bound) {
+  const specMapId = spec?.spec_identity?.map_id || spec?.map_id;
+  const localIdentity = spec?.spec_identity?.local_spec_id != null || bound?.local_spec_id != null;
+  if ((specMapId && specMapId !== bound?.map_id) || (localIdentity && !campaignIdentitiesMatch(campaignSpecIdentity(spec), bound))) {
+    return localIdentity ? "local_spec" : "saved_map";
+  }
+  return null;
+}
+
 function validateCampaignSpecRuleRegistry(spec, errors, warnings) {
   // ADR-003: run the shared campaign-spec rule registry — the single public
   // source of CampaignSpec validation. specOnlyRules is the right preset here:
@@ -876,7 +901,17 @@ function validateBuildBrief(packet, packetPath, spec, context, errors, warnings,
     return;
   }
 
-  const brief = readJson(resolvedPath);
+  let brief;
+  try {
+    brief = readJson(resolvedPath);
+  } catch {
+    addIssue(errors, "build_brief.normalized_path", `Campaign Build Brief normalized artifact is not valid JSON: ${normalizedPath}. Restore it, or save the brief again with ${cmd("record")} brief --packet <packet>.`);
+    return;
+  }
+  if (!isObject(brief)) {
+    addIssue(errors, "build_brief.normalized_path", `Campaign Build Brief normalized artifact is not a valid brief object: ${normalizedPath}. Restore it, or save the brief again with ${cmd("record")} brief --packet <packet>.`);
+    return;
+  }
   const result = validateCampaignBuildBriefArtifact(brief, { spec, normalizedPath });
   for (const issue of result.errors) errors.push(issue);
   for (const issue of result.warnings) warnings.push(issue);
@@ -887,6 +922,86 @@ function validateBuildBrief(packet, packetPath, spec, context, errors, warnings,
   }
 }
 
+// derived.input_currency, computed once per doctor read, and the warnings it
+// gives: a stage owed on the brief or on the CampaignSpec, a completed stage
+// with no valid brief or spec stamp, or read against a brief or CampaignSpec
+// that cannot be read, a brief file edited (or unreadable) since it was saved,
+// and the build replay after an input change (owed, or kept by the
+// operator's recorded decision). None is an error; `next` routes to the owed
+// stage itself.
+function validateInputCurrency({ packet, packetPath, spec, report, warnings, derived }) {
+  const currency = derived.input_currency || deriveInputCurrency({ packet, packetPath, report, spec: isObject(spec) ? spec : null });
+  derived.input_currency = currency;
+  if (!isObject(report?.stages)) return;
+  // A stage stamped with other spec content than the file holds now, while
+  // the report identity already names the file's content (an identity edited
+  // by hand): the same warning the identity comparison gives.
+  const owedOnSpec = Object.keys(currency.reasons).filter((key) => currency.reasons[key] === "spec_material_changed");
+  if (owedOnSpec.length && !warnings.some((issue) => issue.code === "spec.material_stale")) {
+    addIssue(warnings, "spec.material_stale", SPEC_MATERIAL_STALE_MESSAGE, { stages: owedOnSpec, bound_material_hash: currency.spec.bound, current_material_hash: currency.spec.current });
+  }
+  const specUnstamped = Object.keys(currency.stages).filter((key) => currency.reasons[key] === "input_binding_unknown" && !SPEC_STAMP.test(String(report.stages[key]?.source_spec_material_hash ?? "")));
+  if (specUnstamped.length) {
+    addIssue(warnings, "spec.binding_unknown", `Recorded ${specUnstamped.join(", ")} ${specUnstamped.length === 1 ? "does" : "do"} not say which CampaignSpec content ${specUnstamped.length === 1 ? "it was" : "they were"} made against, so ${specUnstamped.length === 1 ? "it reads" : "they read"} unconfirmed, not current. Record ${specUnstamped.join(", ")} again (${specUnstamped.map((key) => (key === "assembly" ? "record build" : key === "polish" ? "record polish" : "qa run")).join(", ")}).`, { stages: specUnstamped });
+  }
+  const owedOnBrief = Object.keys(currency.reasons).filter((key) => currency.reasons[key] === "brief_material_changed");
+  if (owedOnBrief.length) {
+    addIssue(warnings, "build_brief.material_changed", `The Campaign Build Brief's content changed since ${owedOnBrief.join(", ")} ${owedOnBrief.length === 1 ? "was" : "were"} recorded, so ${owedOnBrief.length === 1 ? "it is" : "they are"} owed again. Save the brief with ${cmd("record")} brief --packet <packet> (it keeps stage history), then record ${owedOnBrief.join(", ")} again.`, { stages: owedOnBrief });
+  }
+  const unstamped = Object.keys(currency.stages).filter((key) => {
+    const stage = report.stages[key];
+    if (currency.reasons[key] !== "input_binding_unknown") return false;
+    const stamp = stage?.source_brief_material;
+    return !wellFormedBriefMaterial(stamp);
+  });
+  if (unstamped.length) {
+    addIssue(warnings, "build_brief.binding_unknown", `Recorded ${unstamped.join(", ")} ${unstamped.length === 1 ? "does" : "do"} not say which Campaign Build Brief content ${unstamped.length === 1 ? "it was" : "they were"} made against, so ${unstamped.length === 1 ? "it reads" : "they read"} unconfirmed, not current. Record ${unstamped.join(", ")} again (${unstamped.map((key) => (key === "assembly" ? "record build" : key === "polish" ? "record polish" : "qa run")).join(", ")}).`, { stages: unstamped });
+  }
+  // A completed stage with a well-formed stamp also reads unknown when the
+  // current brief or CampaignSpec cannot be read: there is nothing to compare
+  // that stamp with. The warning names the file to restore; a stage whose
+  // stamp is missing or malformed is named by the stamp warning above only.
+  const unknownStages = Object.keys(currency.stages).filter((key) => currency.reasons[key] === "input_binding_unknown");
+  const unconfirmed = (stages) => `recorded ${stages.join(", ")} ${stages.length === 1 ? "reads" : "read"} unconfirmed, not current`;
+  const briefUnreadable = unknownStages.filter((key) => !unstamped.includes(key));
+  if (briefUnreadable.length && currency.brief.current === null) {
+    const normalizedPath = optionalString(packet?.build_brief?.normalized_path);
+    addIssue(warnings, "build_brief.binding_unknown", `${normalizedPath ? `The normalized Campaign Build Brief ${normalizedPath} cannot be read as a brief object` : "The Build Packet names no build_brief.normalized_path, so the current Campaign Build Brief cannot be read"}, so ${unconfirmed(briefUnreadable)}. Restore it, or save the brief again with ${cmd("record")} brief --packet <packet>.`, { stages: briefUnreadable, ...(normalizedPath ? { normalized_path: normalizedPath } : {}) });
+  }
+  const specPath = optionalString(packet?.spec?.local_path);
+  const specUnreadable = unknownStages.filter((key) => !specUnstamped.includes(key));
+  if (specUnreadable.length && currency.spec.current === null && specPath) {
+    addIssue(warnings, "spec.binding_unknown", `The CampaignSpec ${specPath} cannot be read as a JSON object, so ${unconfirmed(specUnreadable)}. Restore it, then run doctor again.`, { stages: specUnreadable, spec_path: specPath });
+  }
+  const inputPath = optionalString(packet?.build_brief?.input_path);
+  const savedSha = optionalString(report.build_brief?.input_sha256);
+  const briefFile = inputPath ? resolveFromFile(packetPath, inputPath) : null;
+  if (briefFile && savedSha && existsSync(briefFile)) {
+    // Read only a readable regular file: a pipe would block, a directory throws.
+    const unusable = briefFileUnusable(briefFile);
+    let bytes = null;
+    if (!unusable) {
+      try {
+        bytes = `sha256:${createHash("sha256").update(readFileSync(briefFile)).digest("hex")}`;
+      } catch {
+        bytes = null;
+      }
+    }
+    if (bytes === null) {
+      addIssue(warnings, "build_brief.input_unsaved", `The brief file ${inputPath} ${unusable || "cannot be read"}, so doctor cannot tell whether it changed since it was saved; the build reads the saved brief. Restore it, or save a readable brief file with ${cmd("record")} brief --packet <packet> --brief <file>.`, { input_path: inputPath });
+    } else if (bytes !== savedSha) {
+      addIssue(warnings, "build_brief.input_unsaved", `The brief file ${inputPath} changed since it was saved. Save it with ${cmd("record")} brief --packet <packet>; until then the build reads the saved brief.`, { input_path: inputPath });
+    }
+  }
+  if (currency.reasons.assembly === "output_unchanged_after_input_change") {
+    addIssue(warnings, "assembly.output_unchanged_after_input_change", `The build output is unchanged since the brief or CampaignSpec change was recorded, so the change has not reached the pages and build is owed again. Rebuild, or, only on the operator's explicit decision that the change needs no output change, record build with --deviation-reason "<the operator's reason>".`);
+  }
+  const keptReason = report.stages.assembly?.unchanged_output_reason;
+  if (currency.stages.assembly === "current" && isObject(keptReason) && typeof keptReason.text === "string") {
+    addIssue(warnings, "assembly.output_unchanged_by_operator_decision", `The build output was kept unchanged after an input change by the operator's recorded decision: "${keptReason.text}".`, { reason: keptReason.text });
+  }
+}
+
 function validateProofPolicyObject(policy, location, warnings, ready, { requireBrowserQa = false } = {}) {
   if (!isObject(policy)) {
     addIssue(warnings, location, `${location} must be an object when present.`);
@@ -4257,7 +4372,7 @@ export function validateBuiltPlaceholderTextResidue(brandContract, warnings, rea
     return;
   }
   const terms = [...new Set(hits.map((hit) => hit.label))].join(", ");
-  if (report && qaGatePassedForCurrentBuild(report, QA_GATE_PLACEHOLDER_TEXT_RESIDUE, { buildFingerprint: currentBuildFingerprint(report) })) {
+  if (report && qaGatePassedForCurrentBuild(report, QA_GATE_PLACEHOLDER_TEXT_RESIDUE, { buildFingerprint: currentBuildFingerprint(report), qaCurrency: derived.input_currency?.stages?.qa ?? "unknown" })) {
     ready.push(`Static scan still sees placeholder-term text (${terms}: ${summarizeCopyMatches(hits)}), but the browser residue gate passed on this build; QA's rendered-text verdict stands.`);
     return;
   }

package/src/doctor/next-step.mjs

@@ -12,12 +12,12 @@ import {
 import {
   NEXT_STAGE_ORDER,
   NEXT_STAGE_OWNERS,
-  STAGE_TERMINAL_STATUS_PREFIXES,
   reportKeyForCliStage,
   stageIsBlocked,
   stageIsTerminal,
 } from "../orchestration-stage-contract.mjs";
 import { evaluatePolishGate } from "../polish-gate.mjs";
+import { effectiveStageStatus, effectiveStatusIsTerminal } from "../input-currency.mjs";
 import { cmd } from "../install-invocation.mjs";
 import { isObject, isNonEmptyString, optionalString, resolveFromFile, addIssue, filesystemPathsMatch } from "../cli-helpers.mjs";
 import { orderPathDepthDrift } from "./checks.mjs";
@@ -440,6 +440,16 @@ function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate
     };
   }
 
+  // A build made against earlier brief or CampaignSpec content, or one whose
+  // inputs cannot be confirmed, is owed before anything downstream of it.
+  const inputCurrency = derived?.input_currency || null;
+  if (["owed", "unknown"].includes(inputCurrency?.stages?.assembly)) {
+    return {
+      stage: "build",
+      reason: inputCurrency.reasons?.assembly || "input_binding_unknown",
+    };
+  }
+
   if (polishGate.status === "blocked") {
     if (polishGateRequiresBuild(polishGate)) {
       return {
@@ -474,7 +484,9 @@ function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate
         reason: `Stage "${reportKey}" is not recorded in the assembly report; run "${cliStage}" next.`,
       };
     }
-    const status = String(stage.status || "");
+    // The effective status: a stage owed again by an input change reads
+    // required, and one whose inputs or raw status cannot be read, unknown.
+    const status = effectiveStageStatus(reportKey, stage, inputCurrency);
     if (stageIsBlocked(status)) {
       return {
         stage: cliStage,
@@ -482,10 +494,7 @@ function pickNextStage(report, { errors = [], derived = null }, prepareBuildGate
         blocked: true,
       };
     }
-    // Match by prefix so "completed_with_warnings" and future suffixes
-    // (e.g. "completed_partial") count as terminal.
-    const isTerminal = STAGE_TERMINAL_STATUS_PREFIXES.some((t) => status.startsWith(t));
-    if (!isTerminal) {
+    if (!effectiveStatusIsTerminal(status)) {
       return {
         stage: cliStage,
         reason: `Stage "${reportKey}" has status "${status || "(unset)"}"; run "${cliStage}" next.`,