@nextcommerce/campaigns-os 1.63.0 → 1.66.0

package/src/runtime-state-ignore.mjs

@@ -6,7 +6,10 @@
 //      second and later funnels) — current readback truth; docs/migration-sidecar-bundle.md
 //      names it and `bundle check` validates it. Committed by design.
 //   2. Handoff inputs and agent context (input/, theme/, agent-context/,
-//      setup-handoff.json) — durable build handoff. Committed by design.
+//      setup-handoff.json) and the CampaignSpec a Map intake fetched
+//      (fetched-specs/) — durable build handoff. The committed records are
+//      bound to that spec, and spec derive edits it, so another machine cannot
+//      get it back from the Map. Committed by design.
 //   3. Telemetry, sessions, caches, and evidence — per-machine, append-only,
 //      or carrying live URLs and absolute paths. Never meant for the repo, and
 //      nothing wrote a rule for them: three campaign repositories were found
@@ -32,7 +35,6 @@ export const RUNTIME_STATE_IGNORED_PATHS = [
   // A project's second and later funnels keep their Run Records under their
   // own runtime directory (src/campaign-workspace.mjs).
   ".campaign-runtime/funnels/*/run-records/",
-  ".campaign-runtime/fetched-specs/",
   ".campaign-runtime/progress/",
   ".campaign-runtime/polish-evidence/",
   ".campaign-runtime/evidence/",
@@ -53,12 +55,17 @@ export const RUNTIME_STATE_IGNORED_PATHS = [
 // present.
 export const RUNTIME_STATE_REQUIRED_IGNORED_PATHS = ["qa-output/", ".campaign-runtime/progress/", ".campaign-runtime/funnels/*/run-records/"];
 
+// Entries an earlier toolkit wrote into the managed block that are now meant
+// to be committed. They leave the managed block on the next setup command or
+// `spec fetch`; the same line elsewhere in the file is the operator's own.
+export const RUNTIME_STATE_RETIRED_IGNORED_PATHS = [".campaign-runtime/fetched-specs/"];
+
 export const RUNTIME_STATE_IGNORE_BLOCK = [
   RUNTIME_STATE_IGNORE_MARKER,
-  "# Sessions, journals, Run Records, spec caches, capture evidence, and full",
-  "# QA verdicts are per-machine. The readback bundle (build-context, assembly-report,",
-  "# doctor-output, qa-verdict), input/, theme/, and agent-context/ are meant",
-  "# to be committed and are deliberately not listed here.",
+  "# Sessions, journals, Run Records, capture evidence, and full QA verdicts are",
+  "# per-machine. The readback bundle (build-context, assembly-report, doctor-output,",
+  "# qa-verdict), fetched-specs/, input/, theme/, and agent-context/ are meant to be",
+  "# committed and are deliberately not listed here.",
   ...RUNTIME_STATE_IGNORED_PATHS,
 ].join("\n");
 
@@ -66,14 +73,29 @@ function ignoreRuleLines(text) {
   return new Set(text.split("\n").map((line) => line.trim()).filter((line) => line && !line.startsWith("#")));
 }
 
-// Append the missing required entries at the end of the managed block: after
-// the marker, up to the first blank line or the end of the file.
-function withRequiredEntries(existing, missing) {
-  const lines = existing.split("\n");
-  const markerIndex = lines.findIndex((line) => line.trim() === RUNTIME_STATE_IGNORE_MARKER);
+// The managed block spans the marker up to the first blank line or the end of
+// the file.
+function managedBlockEnd(lines, markerIndex) {
   let end = markerIndex + 1;
   while (end < lines.length && lines[end].trim() !== "") end += 1;
-  lines.splice(end, 0, ...missing);
+  return end;
+}
+
+function retiredEntriesInBlock(existing) {
+  const lines = existing.split("\n");
+  const markerIndex = lines.findIndex((line) => line.trim() === RUNTIME_STATE_IGNORE_MARKER);
+  return lines.slice(markerIndex + 1, managedBlockEnd(lines, markerIndex)).map((line) => line.trim())
+    .filter((line) => RUNTIME_STATE_RETIRED_IGNORED_PATHS.includes(line));
+}
+
+// Append the missing required entries at the end of the managed block and drop
+// the retired ones from it.
+function withBlockEntries(existing, missing) {
+  const lines = existing.split("\n");
+  const markerIndex = lines.findIndex((line) => line.trim() === RUNTIME_STATE_IGNORE_MARKER);
+  const end = managedBlockEnd(lines, markerIndex);
+  const block = lines.slice(markerIndex + 1, end).filter((line) => !RUNTIME_STATE_RETIRED_IGNORED_PATHS.includes(line.trim()));
+  lines.splice(markerIndex + 1, end - markerIndex - 1, ...block, ...missing);
   return lines.join("\n");
 }
 
@@ -81,10 +103,11 @@ function withRequiredEntries(existing, missing) {
  * Ensure the target's .gitignore carries the runtime-state block. Idempotent
  * on the marker line: an existing block, however edited beneath it, is left
  * alone — except for RUNTIME_STATE_REQUIRED_IGNORED_PATHS, which are appended
- * to an existing block when the file carries them nowhere. Never throws for
- * an unwritable target — the build must not fail on housekeeping — but
+ * to an existing block when the file carries them nowhere, and
+ * RUNTIME_STATE_RETIRED_IGNORED_PATHS, which are removed from it. Never throws
+ * for an unwritable target — the build must not fail on housekeeping — but
  * reports what happened so callers can surface it.
- * Returns `{ path, action: "added" | "updated" | "present" | "skipped", reason?, added_entries? }`.
+ * Returns `{ path, action: "added" | "updated" | "present" | "skipped", reason?, added_entries?, removed_entries? }`.
  */
 export function ensureRuntimeStateIgnored(targetRepo, { dryRun = false } = {}) {
   const path = join(resolve(targetRepo), ".gitignore");
@@ -98,14 +121,16 @@ export function ensureRuntimeStateIgnored(targetRepo, { dryRun = false } = {}) {
     if (existing.includes(RUNTIME_STATE_IGNORE_MARKER)) {
       const present = ignoreRuleLines(existing);
       const missing = RUNTIME_STATE_REQUIRED_IGNORED_PATHS.filter((entry) => !present.has(entry));
-      if (missing.length === 0) return { path, action: "present" };
-      if (dryRun) return { path, action: "updated", dry_run: true, added_entries: missing };
+      const retired = retiredEntriesInBlock(existing);
+      if (missing.length === 0 && retired.length === 0) return { path, action: "present" };
+      const changes = { added_entries: missing, ...(retired.length ? { removed_entries: retired } : {}) };
+      if (dryRun) return { path, action: "updated", dry_run: true, ...changes };
       try {
-        writeFileSync(path, withRequiredEntries(existing, missing));
+        writeFileSync(path, withBlockEntries(existing, missing));
       } catch (error) {
         return { path, action: "skipped", reason: `unwritable: ${error.message}` };
       }
-      return { path, action: "updated", added_entries: missing };
+      return { path, action: "updated", ...changes };
     }
   }
   if (dryRun) return { path, action: "added", dry_run: true };

package/src/stage-ledger.mjs

@@ -106,20 +106,23 @@ const HISTORY_ENTRY_FIELDS = Object.freeze([
   "build_fingerprint", "source_build_fingerprint", "source_package_material_fingerprint",
   "source_brief_material", "source_spec_material_hash",
   "verdict_run_id", "checked_at", "purchase_proof",
-  "outputs", "evidence",
+  "outputs", "evidence", "baseline_accepted_at",
 ]);
 // The entry fields that say what a record was, rather than when or by whom it
 // was written: a replacement equal on all of them is a re-record, not a new
 // chapter, and archives nothing.
 const HISTORY_IDENTITY_FIELDS = Object.freeze([
   "build_fingerprint", "source_build_fingerprint", "source_package_material_fingerprint",
-  "source_brief_material", "source_spec_material_hash", "verdict_run_id", "purchase_proof", "outputs", "evidence",
+  "source_brief_material", "source_spec_material_hash", "verdict_run_id", "purchase_proof", "outputs", "evidence", "baseline_accepted_at",
 ]);
-export const HISTORY_ARCHIVED_BY = Object.freeze(["record brief", "record spec", "record build", "record polish", "qa run", "prepare-build --force"]);
-export const HISTORY_REASON_CODES = Object.freeze(["brief_presentation_changed", "brief_qa_policy_changed", "spec_material_changed", "rerecorded", "force_reset", "build_output_changed"]);
+export const HISTORY_ARCHIVED_BY = Object.freeze(["record brief", "record spec", "record build", "record polish", "record baseline", "qa run", "prepare-build --force"]);
+export const HISTORY_REASON_CODES = Object.freeze(["brief_presentation_changed", "brief_qa_policy_changed", "spec_material_changed", "rerecorded", "force_reset", "build_output_changed", "baseline_accepted"]);
 const ARCHIVED_STAGE_KEYS = Object.freeze(["assembly", "polish", "qa"]);
 
 const isCompletedStatus = (status) => typeof status === "string" && status.startsWith("completed");
+// A record a later one replaces into history. A baseline counts here, and not
+// as completed: it never hands a campaign off or proves anything.
+const isReplacedRecord = (status) => isCompletedStatus(status) || status === "baseline_accepted";
 
 // What a record says about itself, compared for the dedup. Evidence reads
 // through meaningfulEvidence (an empty block is absent) and a verdict id is
@@ -168,7 +171,7 @@ function historyEntry(previous, { by, reason, at }) {
 // verdict identity or evidence, which the QA producer has always archived.
 function archivable(stageKey, previous) {
   if (!isPlainObject(previous)) return false;
-  if (isCompletedStatus(previous.status)) return true;
+  if (isReplacedRecord(previous.status)) return true;
   return stageKey === "qa" && Boolean(recordIdentity(previous).verdict_run_id || meaningfulEvidence(previous.evidence));
 }
 
@@ -200,6 +203,19 @@ export function archiveSupersededRecord(stage, previous, { by, reason, at }) {
   return appendHistoryEntry(isPlainObject(stage) ? { ...stage } : {}, historyEntry(previous, { by, reason, at }));
 }
 
+// The baseline QA rests on, or null. The marker on the record is the rule, not
+// its status: a blocked page-scoped run or an input change leaves QA resting on
+// the baseline, and only a completed full QA clears the marker.
+export function qaRestsOnBaseline(report) {
+  return report?.stages?.qa?.baseline_accepted_at && isPlainObject(report?.commerce_baseline) ? report.commerce_baseline : null;
+}
+
+// A stage's baseline record, with what the stage held moved to its history.
+export function archiveForBaseline(record, previous, { at }) {
+  const carried = Array.isArray(previous?.history) ? { ...record, history: previous.history } : record;
+  return archiveSupersededRecord(carried, previous, { by: "record baseline", reason: "baseline_accepted", at });
+}
+
 /**
  * #668: the Polish record a CampaignSpec change moved to `polish.history`,
  * restored as the live record stamped with `stamps` (the current inputs), or
@@ -241,6 +257,15 @@ export function campaignHandedOff(report) {
   return completedIn(report?.stages?.deploy) || completedIn(report?.stages?.qa);
 }
 
+// True when QA has ever completed, now or in the stage's history. Not
+// campaignHandedOff: a baseline stands in for a QA result, and a completed
+// deploy is not one.
+export function qaEverCompleted(report) {
+  const qa = report?.stages?.qa;
+  return isPlainObject(qa) && (isCompletedStatus(qa.status)
+    || (Array.isArray(qa.history) && qa.history.some((entry) => isPlainObject(entry) && isCompletedStatus(entry.status))));
+}
+
 /**
  * True when any stage of `report` carries a non-empty history: recorded
  * operator-visible state an intake must not silently drop.
@@ -301,7 +326,7 @@ export function archiveForForceReset(previousReport, nextReport, { now, detectCh
       continue;
     }
     if (Object.hasOwn(previous, "input_change")) reseeded.input_change = JSON.parse(JSON.stringify(previous.input_change));
-    if (isCompletedStatus(previous.status)) {
+    if (isReplacedRecord(previous.status)) {
       reseeded = archiveSupersededRecord(reseeded, previous, { by: "prepare-build --force", reason: "force_reset", at: now });
       const reason = typeof detectChange === "function" ? detectChange(key, previous) : null;
       if (reason) reseeded.input_change = inputChangeFor(key, previous, { at: now, reason });
@@ -405,7 +430,7 @@ export function recordProducerStageOutcome(report, {
     // A replaced completed record whose stamps differ from the current inputs
     // records the change; a verdict stamped with the current inputs then
     // clears it, the one it just recorded included; any other write carries it.
-    const detected = inputs && isCompletedStatus(previous.status) ? inputs.detectChange(previous) : null;
+    const detected = inputs && isReplacedRecord(previous.status) ? inputs.detectChange(previous) : null;
     if (detected) next.input_change = inputChangeFor("qa", previous, { at: timestamp, reason: detected });
     if (inputs && inputs.stampsCurrent(next)) delete next.input_change;
     const archived = archiveStageRecord(next, previous, next, { by: "qa run", reason: detected || "rerecorded", at: timestamp, stageKey: "qa" });
@@ -591,9 +616,10 @@ export function qaRecordedBuildFingerprint(report) {
 // #720: the build whose completed QA a page-scoped run extends. A completed
 // QA record extends its own build. A page-scoped run that did not complete
 // extends the build of the full QA it was based on, which was completed when
-// that run was accepted. Any other record (blocked or pending full QA, a
+// that run was accepted. A baseline extends its own build too, and has no
+// purchase proof to pass on. Any other record (blocked or pending full QA, a
 // skip, a required stage) extends nothing, so it owes a full QA run.
-const QA_EXTENDABLE_STATUSES = Object.freeze(["completed", "completed_with_warnings"]);
+const QA_EXTENDABLE_STATUSES = Object.freeze(["completed", "completed_with_warnings", "baseline_accepted"]);
 export function qaExtendedBuildFingerprint(report) {
   const qa = report?.stages?.qa;
   if (QA_EXTENDABLE_STATUSES.includes(qa?.status)) return qaRecordedBuildFingerprint(report);

package/src/stage-record.mjs

@@ -37,7 +37,9 @@ import { LOCAL_PROOF_BUILD_ENVIRONMENT, LOCAL_PROOF_PRODUCTION_ENVIRONMENT, isLo
 import { polishCarriedForwardForLadder } from "./local-preview-policy.mjs";
 import { isLoopbackHostname } from "./remit.mjs";
 import { campaignRouteRoot, normalizePublicRouteSlug } from "./route-identity.mjs";
-import { buildChangeEntry, buildCommerceSignature, nextBuildChanges } from "./change-scope.mjs";
+import { buildChangeEntry, buildCommerceSignature, nextBuildChanges, rebuiltFromBuildWithoutSignature } from "./change-scope.mjs";
+import { isNamedHuman } from "./checkpoint-waiver.mjs";
+import { singleLineFragment } from "./text-safety.mjs";
 import { assessEvidenceDebt } from "./evidence-debt.mjs";
 import { writeJsonAtomic } from "./doctor-sidecar.mjs";
 import { doctorPacket } from "./doctor/inspect.mjs";
@@ -54,7 +56,7 @@ import {
 import { evaluateRecordedHiddenEagerMediaCheckpoint } from "./polish-node.mjs";
 import { effectiveStageStatus, effectiveStatusIsTerminal, inputStamps, stageWriteInputs } from "./input-currency.mjs";
 import { demoteStages, recordBrief, recordSpec } from "./input-refresh.mjs";
-import { applyDerivedAssemblyReportSummary, archiveStageRecord, archiveSupersededRecord, assemblyReportMatchesPacket, commitAssemblyReport, inputChangeFor, polishReviewedBuild, qaExtendedBuildFingerprint, qaRecordedBuildFingerprint, restorePolishKeptWithOutput } from "./stage-ledger.mjs";
+import { applyDerivedAssemblyReportSummary, archiveStageRecord, archiveForBaseline, archiveSupersededRecord, assemblyReportMatchesPacket, campaignHandedOff, qaEverCompleted, commitAssemblyReport, inputChangeFor, polishReviewedBuild, qaExtendedBuildFingerprint, qaRecordedBuildFingerprint, restorePolishKeptWithOutput } from "./stage-ledger.mjs";
 import { withTargetLockSync } from "./target-lock.mjs";
 import { commerceScopeFromScope } from "./theme-gate.mjs";
 
@@ -71,7 +73,9 @@ const BUILD_RECORD_FLAGS = Object.freeze(["build-environment", "adapter-decision
 // discovery finds it).
 const BRIEF_RECORD_FLAGS = Object.freeze(["brief"]);
 // `record spec` binds the CampaignSpec as it is now; it takes no extra flag.
-const RECORD_SUBCOMMANDS = Object.freeze([...RECORD_STAGES, "brief", "spec"]);
+// `record baseline` accepts the current build as the starting point: who, and why.
+const BASELINE_RECORD_FLAGS = Object.freeze(["accepted-by", "reason"]);
+const RECORD_SUBCOMMANDS = Object.freeze([...RECORD_STAGES, "brief", "spec", "baseline"]);
 // The page-kit environment the built output was rendered in, recorded on
 // stages.assembly.evidence.build_environment (local proof mode builds in
 // development; doctor and page-kit parity read it).
@@ -174,7 +178,7 @@ export function parseRecordArgs(args) {
   if (!RECORD_SUBCOMMANDS.includes(stage) || args._.length !== 2) {
     throw refused(`Use: ${cmd("record")} <${RECORD_SUBCOMMANDS.join("|")}> --packet <campaign-runtime.build.json> [--context <json>] [--report <json>] [--dry-run] [--json]; record polish also takes --evidence <polish-evidence.json>, record deploy --base-url <served url>, record build [--build-environment <${BUILD_ENVIRONMENTS.join("|")}>] [--adapter-decision <key=value[,key=value...]>], and record brief [--brief <yaml|json>].`);
   }
-  const known = new Set([...RECORD_FLAGS, ...(stage === "polish" ? POLISH_RECORD_FLAGS : []), ...(stage === "deploy" ? DEPLOY_RECORD_FLAGS : []), ...(stage === "build" ? BUILD_RECORD_FLAGS : []), ...(stage === "brief" ? BRIEF_RECORD_FLAGS : [])]);
+  const known = new Set([...RECORD_FLAGS, ...(stage === "polish" ? POLISH_RECORD_FLAGS : []), ...(stage === "deploy" ? DEPLOY_RECORD_FLAGS : []), ...(stage === "build" ? BUILD_RECORD_FLAGS : []), ...(stage === "brief" ? BRIEF_RECORD_FLAGS : []), ...(stage === "baseline" ? BASELINE_RECORD_FLAGS : [])]);
   const unknown = Object.keys(args).filter((key) => key !== "_" && !known.has(key));
   if (unknown.length) {
     throw refused(`Unknown flag${unknown.length > 1 ? "s" : ""} for record ${stage}: ${unknown.map((key) => `--${key}`).join(", ")}. Known flags: ${[...known].map((key) => `--${key}`).join(", ")}.`);
@@ -186,6 +190,10 @@ export function parseRecordArgs(args) {
     throw refused(`--dry-run takes no value (got ${JSON.stringify(args["dry-run"])}); write \`--dry-run\` on its own, after the other flags.`);
   }
   if (Object.hasOwn(args, "json") && args.json !== true) throw refused("--json is a boolean flag and takes no value.");
+  if (stage === "baseline") {
+    if (!isNamedHuman(args["accepted-by"])) throw refused("record baseline: --accepted-by needs the named person accepting this build; placeholders and automation identities are not accepted.");
+    if (!optionalString(args.reason)) throw refused("record baseline: --reason needs the reason this build is being accepted untested.");
+  }
   const buildEnvironment = Object.hasOwn(args, "build-environment") ? args["build-environment"] : null;
   if (buildEnvironment !== null && !BUILD_ENVIRONMENTS.includes(buildEnvironment)) {
     throw refused(`--build-environment must be one of: ${BUILD_ENVIRONMENTS.join(", ")} (got ${JSON.stringify(buildEnvironment)}).`);
@@ -201,6 +209,7 @@ export function parseRecordArgs(args) {
     adapterDecisions,
     briefPath: stage === "brief" && Object.hasOwn(args, "brief") ? resolve(args.brief) : null,
     deviationReason: optionalString(args["deviation-reason"]),
+    baseline: stage === "baseline" ? { acceptedBy: args["accepted-by"].trim().replace(/\s+/g, " "), reason: args.reason.trim() } : null,
   };
 }
 
@@ -322,7 +331,7 @@ function composeSetup(report, context, { now, recordedBy }) {
 // operator decision that applies only to the record that carried it.
 const STAMP_FIELDS = Object.freeze(["source_brief_material", "source_spec_material_hash"]);
 // A replaced record in any of these statuses is checked for an input change.
-const REPLACED_COMPLETED_STATUSES = Object.freeze(["completed", "completed_with_warnings", "completed_partial"]);
+const REPLACED_COMPLETED_STATUSES = Object.freeze(["completed", "completed_with_warnings", "completed_partial", "baseline_accepted"]);
 
 // The stamps a completed record writes: the inputs current at this write
 // (the absent brief value for a packet without a brief). A value that cannot
@@ -473,6 +482,73 @@ function deployAfterBuild(previousDeploy, fingerprint, now) {
   return archiveSupersededRecord(demoted, previousDeploy, { by: "record build", reason: "build_output_changed", at: now });
 }
 
+// `record baseline`: a named person accepts a funnel from before markup hashes
+// as the starting point for page-only changes, without testing it. Polish and
+// QA take the status baseline_accepted, which ends the ladder but is never
+// completed; what they held moves to history, so its purchase proof stops
+// counting. One time per funnel: report.commerce_baseline stays after a later
+// full QA, so this can never be a way past QA that a commerce change owes.
+function composeBaseline(report, { now, recordedBy, fingerprint, input, inputs, packet, packetPath }) {
+  const earlier = report.commerce_baseline;
+  if (isObject(earlier)) {
+    throw refuseRecord("baseline", [`${earlier.accepted_by} accepted a baseline for this funnel at ${earlier.accepted_at}, and a funnel gets one. Run ${cmd("qa")} run for what is owed now.`]);
+  }
+  if (!campaignHandedOff(report)) {
+    throw refuseRecord("baseline", ["This funnel has no completed deploy or QA, now or in its history. A baseline is for a funnel already handed off; run the full stages."]);
+  }
+  if (!rebuiltFromBuildWithoutSignature(report.stages?.assembly)) {
+    throw refuseRecord("baseline", [`This funnel's records have markup hashes (Campaigns OS 1.62.0 or later), or ${cmd("record")} build has not run on this toolkit. Page-only changes can be read from a full QA; a baseline is only for records from before those hashes. If you have not, run ${cmd("record")} build first.`]);
+  }
+  // A baseline stands in for a QA that passed on an older toolkit, so it needs
+  // one. A blocked QA found a problem a sign-off cannot vouch for.
+  const lastQa = stageObject(report, "qa");
+  if (lastQa.status === "blocked") {
+    const blockers = (Array.isArray(lastQa.blockers) ? lastQa.blockers : []).slice(0, 3).map((blocker) => singleLineFragment(typeof blocker === "string" ? blocker : blocker?.message || blocker?.code || "")).filter(Boolean);
+    throw refuseRecord("baseline", [`The last QA was blocked${blockers.length ? ` (${blockers.join("; ")})` : ""}, so it cannot be accepted untested. Run a full ${cmd("qa")} run; once it passes, page-only changes work without a baseline.`]);
+  }
+  if (!qaEverCompleted(report)) {
+    throw refuseRecord("baseline", [`No QA has completed on this funnel, so there is no result to start from. Run a full ${cmd("qa")} run; once it passes, page-only changes work without a baseline.`]);
+  }
+  const debt = assessEvidenceDebt({ packet, packetPath, report }).qa;
+  if (debt.status !== "owed" || debt.scope !== "full") {
+    throw refuseRecord("baseline", [`A full QA is not owed (QA reads ${debt.status}${debt.scope ? `, scope ${debt.scope}` : ""}), so there is nothing to accept.`]);
+  }
+  const stamps = currentStamps(inputs);
+  // History keeps no warnings or skip reasons, and a baseline must still say
+  // what it replaced.
+  const replacedRecord = (key) => {
+    const before = stageObject(report, key);
+    return { status: before.status ?? null, blockers: before.blockers ?? [], warnings: before.warnings ?? [], ...(before.skip_reason ? { skip_reason: before.skip_reason } : {}) };
+  };
+  const replace = (key, fields) => {
+    const previous = stageObject(report, key);
+    return archiveForBaseline({
+      stage: key,
+      status: "baseline_accepted",
+      recorded_by: recordedBy,
+      checked_at: now,
+      baseline_accepted_at: now,
+      ...stamps,
+      blockers: [],
+      warnings: [],
+      outputs: [],
+      ...fields,
+    }, previous, { at: now });
+  };
+  return {
+    report: {
+      ...report,
+      commerce_baseline: { accepted_by: input.acceptedBy, accepted_at: now, reason: input.reason, build_fingerprint: fingerprint, replaced_polish: replacedRecord("polish"), replaced_qa: replacedRecord("qa") },
+      stages: {
+        ...report.stages,
+        polish: replace("polish", { source_build_fingerprint: fingerprint }),
+        qa: replace("qa", { evidence: { source_build_fingerprint: fingerprint } }),
+      },
+    },
+    context: null,
+  };
+}
+
 function composePolish(report, { now, recordedBy, fingerprint, input, inputs = {} }) {
   const previous = stageObject(report, "polish");
   const completed = POLISH_COMPLETED_STATUSES.includes(input.status);
@@ -1009,7 +1085,7 @@ function doctorFacts(stage, doctor, report, packet) {
   const binding = bindingProblems(doctor, report, packet);
   if (binding.length) throw refuseRecord(stage, binding);
   // The brand layer is applied to built output, so theme is checked as polish is.
-  const ladder = ladderProblems(stage === "theme" ? "polish" : stage, doctor, report);
+  const ladder = ladderProblems(stage === "theme" || stage === "baseline" ? "polish" : stage, doctor, report);
   if (ladder.length) throw refuseRecord(stage, ladder);
   if (stage === "setup") {
     const outputDir = optionalString(derived.target_output_dir);
@@ -1026,13 +1102,13 @@ function doctorFacts(stage, doctor, report, packet) {
   if (stage === "build" && derived.scaffold_required === true) {
     throw refuseRecord(stage, [`Setup is still required (${derived.scaffold_reason || "Build Context scaffold.required is true"}); run ${cmd("record")} setup first.`]);
   }
-  if (stage === "polish" || stage === "theme" || stage === "deploy") {
+  if (stage === "polish" || stage === "theme" || stage === "deploy" || stage === "baseline") {
     const recorded = optionalString(report?.stages?.assembly?.build_fingerprint);
     if (!String(report?.stages?.assembly?.status || "").startsWith("completed") || !recorded) {
       throw refuseRecord(stage, [`Build is not recorded (stages.assembly needs a completed status and build_fingerprint); run ${cmd("record")} build first.`]);
     }
     if (recorded !== fingerprint) {
-      throw refuseRecord(stage, [stage === "theme" || stage === "deploy"
+      throw refuseRecord(stage, [stage === "theme" || stage === "deploy" || stage === "baseline"
         ? `The built output changed since build was recorded (recorded ${recorded}, current ${fingerprint}); run ${cmd("record")} build, then record ${stage} again.`
         : `The built output changed since build was recorded (recorded ${recorded}, current ${fingerprint}); run ${cmd("record")} build, then ${cmd("polish")} capture, then record polish again.`]);
     }
@@ -1143,12 +1219,12 @@ function readPacketFile(stage, packetPath) {
  * composed or written.
  */
 export function recordStageCommand(args, { now = () => new Date(), beforeLock = null, afterDoctorRead = null, probe = null } = {}) {
-  const { stage, packetPath, evidencePath, dryRun, buildEnvironment, adapterDecisions, deviationReason } = parseRecordArgs(args);
+  const { stage, packetPath, evidencePath, dryRun, buildEnvironment, adapterDecisions, deviationReason, baseline } = parseRecordArgs(args);
   if (!existsSync(packetPath)) throw new Error(`record ${stage}: Build Packet not found at ${packetPath}; run ${cmd("start")} or ${cmd("prepare-build")} first.`);
   if (stage === "deploy" && !probe) throw new Error("record deploy needs the served-route probe; run it through recordCommand.");
   // Operator input, not target state: no campaigns-os writer produces it.
   // For deploy, the probe of the running server (probeLocalPreview).
-  const input = stage === "polish" ? readPolishEvidenceFile(evidencePath) : stage === "deploy" ? probe : null;
+  const input = stage === "polish" ? readPolishEvidenceFile(evidencePath) : stage === "deploy" ? probe : baseline;
   const sidecars = {
     contextPath: args.context ? resolve(args.context) : undefined,
     reportPath: args.report ? resolve(args.report) : undefined,
@@ -1169,7 +1245,7 @@ export function recordStageCommand(args, { now = () => new Date(), beforeLock =
   const recorded = dryRun ? run() : withTargetLockSync(lockedTarget, run, { command: `record ${stage}` });
   const { composed, facts, layer, reportPath, contextPath, after } = recorded;
 
-  const stageKey = stage === "build" ? "assembly" : stage;
+  const stageKey = stage === "build" ? "assembly" : stage === "baseline" ? "qa" : stage;
   const writes = [...(composed.context ? [contextPath] : []), ...(composed.packet ? [packetPath] : []), reportPath];
   const ready = stage === "deploy" ? [
     `stages.deploy.status = completed; deploy.preview_url = ${input.url}`,
@@ -1186,6 +1262,7 @@ export function recordStageCommand(args, { now = () => new Date(), beforeLock =
     ...(stage === "build" && adapterDecisions ? Object.entries(adapterDecisions).map(([key, value]) => `report.adapter_decisions.${key} = ${value}`) : []),
     ...(stage === "build" ? buildChangeReadyLines(composed.report.stages.assembly) : []),
     ...(stage === "build" ? [`stages.polish.status = ${composed.report.stages.polish.status}`] : []),
+    ...(stage === "baseline" ? [`Polish and QA read baseline_accepted: ${baseline.acceptedBy} accepted build ${facts.fingerprint}. Nothing was tested, and no purchase is proven from here until a full ${cmd("qa")} run.`] : []),
     ...(stage === "build" && composed.report.stages.deploy?.required_by === "build" ? [`stages.deploy.status = ${composed.report.stages.deploy.status} (the recorded deploy probed other output; run ${cmd("record")} deploy again)`] : []),
     ...(composed.context ? ["Build Context scaffold.required = false"] : []),
   ];
@@ -1200,7 +1277,7 @@ export function recordStageCommand(args, { now = () => new Date(), beforeLock =
     ...(dryRun ? { would_write: writes } : { written: writes }),
     build_fingerprint: facts.fingerprint || null,
     // The manifest is kept in the report, not echoed: it lists every built file.
-    record: stage === "theme" ? composed.report.theme : stage === "build" ? withoutKeys(composed.report.stages.assembly, ["build_manifest", "commerce_signature"]) : composed.report.stages[stageKey],
+    record: stage === "baseline" ? composed.report.commerce_baseline : stage === "theme" ? composed.report.theme : stage === "build" ? withoutKeys(composed.report.stages.assembly, ["build_manifest", "commerce_signature"]) : composed.report.stages[stageKey],
     ...(stage === "build" ? { polish: composed.report.stages.polish } : {}),
     ...(composed.context ? { scaffold: composed.context.scaffold } : {}),
     ...(stage === "polish" && input.hasRepairLoopDefect ? { repair_loop_defect: input.repairLoopDefect } : {}),
@@ -1273,7 +1350,9 @@ function recordUnderLock({ stage, packetPath, sidecars, lockedTarget, input, dry
           ? composeTheme(report, { now: timestamp, recordedBy, layer })
           : stage === "deploy"
             ? composeDeploy(report, packet, { now: timestamp, recordedBy, probe: input, fingerprint: facts.fingerprint })
-            : composePolish(report, { now: timestamp, recordedBy, fingerprint: facts.fingerprint, input, inputs: recordInputs(doctor) });
+            : stage === "baseline"
+              ? composeBaseline(report, { now: timestamp, recordedBy, fingerprint: facts.fingerprint, input, inputs: recordInputs(doctor), packet, packetPath })
+              : composePolish(report, { now: timestamp, recordedBy, fingerprint: facts.fingerprint, input, inputs: recordInputs(doctor) });
     applyDerivedAssemblyReportSummary(next.report, recordInputs(doctor));
     // The packet's one new value, deploy.preview_url, is checked by
     // deployPreviewUrl; the rest of the packet is as the operator left it.
@@ -1290,7 +1369,7 @@ function recordUnderLock({ stage, packetPath, sidecars, lockedTarget, input, dry
   // Already inside the target lock, which commitAssemblyReport re-enters.
   commitAssemblyReport(workspace, compose, {
     command: `record ${stage}`,
-    staleReason: `${stage === "theme" ? "theme" : `stages.${stage === "build" ? "assembly" : stage}`} was recorded after this doctor snapshot. Re-run ${cmd("doctor")} (or next) for current state.`,
+    staleReason: `${stage === "theme" ? "theme" : stage === "baseline" ? "a baseline" : `stages.${stage === "build" ? "assembly" : stage}`} was recorded after this doctor snapshot. Re-run ${cmd("doctor")} (or next) for current state.`,
     ...(dryRun ? { lock: false } : {}),
   });
   const after = dryRun ? null : doctorPacket(packetPath, sidecars);