@nextcommerce/campaigns-os 1.52.0 → 1.53.0

package/src/brand-theme.mjs

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 
+import { contrastToolkit } from "./contrast.mjs";
 import { shellToken } from "./shell-token.mjs";
 import {
   existsSync,
@@ -677,18 +678,15 @@ function mixColor(value, target, amount) {
   });
 }
 
-function relativeLuminance({ r, g, b }) {
-  const channel = (value) => {
-    const c = value / 255;
-    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
-  };
-  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
-}
+// Luminance and ratio are the shared WCAG 2.x measurement Polish and QA use.
+// Ratios are compared unrounded; only recorded values are rounded, for
+// display.
+const contrast = contrastToolkit();
+const { contrastRatio, displayRatio } = contrast;
 
-function contrastRatio(luminanceA, luminanceB) {
-  const lighter = Math.max(luminanceA, luminanceB);
-  const darker = Math.min(luminanceA, luminanceB);
-  return (lighter + 0.05) / (darker + 0.05);
+// The 8-bit channels colorToRgb reads, as the [0,1] sRGB the helper takes.
+function relativeLuminance({ r, g, b }) {
+  return contrast.relativeLuminance([r / 255, g / 255, b / 255]);
 }
 
 // Pick the foreground color (dark vs light) most legible on `bgValue`. A light
@@ -708,9 +706,11 @@ function readableForeground(bgValue, choices = {}) {
   const darkContrast = contrastRatio(bgLuminance, relativeLuminance(colorToRgb(darkValue)));
   const lightContrast = contrastRatio(bgLuminance, relativeLuminance(colorToRgb(lightValue)));
   const useDark = darkContrast >= lightContrast;
+  const ratio = Math.max(darkContrast, lightContrast);
   return {
     value: useDark ? darkValue : lightValue,
-    contrast: Math.round(Math.max(darkContrast, lightContrast) * 100) / 100,
+    ratio,
+    contrast: displayRatio(ratio),
     on: useDark ? "dark" : "light",
   };
 }
@@ -732,11 +732,12 @@ function declaredForeground(bgValue, declaredValue) {
   if (!bgRgb || !declared) return null;
   const bgLuminance = relativeLuminance(bgRgb);
   const declaredLuminance = relativeLuminance(colorToRgb(declared));
-  const contrast = contrastRatio(bgLuminance, declaredLuminance);
-  if (contrast < DECLARED_CTA_FOREGROUND_MIN_CONTRAST) return null;
+  const ratio = contrastRatio(bgLuminance, declaredLuminance);
+  if (ratio < DECLARED_CTA_FOREGROUND_MIN_CONTRAST) return null;
   return {
     value: declared,
-    contrast: Math.round(contrast * 100) / 100,
+    ratio,
+    contrast: displayRatio(ratio),
     on: declaredLuminance < bgLuminance ? "dark" : "light",
   };
 }
@@ -768,7 +769,7 @@ function deriveForegroundMappings(existingMappings, targetTokens, { ctaForegroun
     const declared = backgroundTarget === CTA_BACKGROUND_TARGET ? declaredForeground(backgroundValue, ctaForeground) : null;
     const readable = declared || readableForeground(backgroundValue, choices);
     if (!readable) continue;
-    if (minContrast && readable.contrast < minContrast) {
+    if (minContrast && readable.ratio < minContrast) {
       warnings.push(issue(
         "theme.foreground.low_contrast",
         declared
@@ -779,7 +780,7 @@ function deriveForegroundMappings(existingMappings, targetTokens, { ctaForegroun
     }
     // Scale confidence by the achieved contrast so a strong derivation reads as
     // trustworthy as a direct mapping (AAA >= 7:1 high, AA >= 4.5:1 medium).
-    const confidence = readable.contrast >= 7 ? "high" : readable.contrast >= 4.5 ? "medium" : "low";
+    const confidence = readable.ratio >= 7 ? "high" : readable.ratio >= 4.5 ? "medium" : "low";
     mappings.push({
       source: backgroundTarget,
       target: foregroundTarget,
@@ -893,9 +894,9 @@ function darkestDeclaredBodyText(rootTokens, bodyBackground) {
     if (!value) continue;
     const luminance = relativeLuminance(colorToRgb(value));
     if (luminance >= bgLuminance) continue;
-    const contrast = contrastRatio(bgLuminance, luminance);
-    if (contrast < BODY_TEXT_MIN_CONTRAST) continue;
-    if (!best || luminance < best.luminance) best = { name, value, luminance, contrast: Math.round(contrast * 100) / 100 };
+    const ratio = contrastRatio(bgLuminance, luminance);
+    if (ratio < BODY_TEXT_MIN_CONTRAST) continue;
+    if (!best || luminance < best.luminance) best = { name, value, luminance, contrast: displayRatio(ratio) };
   }
   return best;
 }

package/src/brief-summary.mjs

@@ -0,0 +1,275 @@
+// The campaign intent summary: a short, deterministic orientation rendered
+// from the normalized Campaign Build Brief for the stage prompts and every
+// `next` result. It is output only: nothing persists it and no routing,
+// gate, price or commerce decision reads it.
+//
+// Every displayed brief value carries the marker its `_meta.field_sources`
+// entry proves, and nothing stronger: an entry counts only when build-brief's
+// fieldSourceEntryMatches accepts it (exactly {kind, value_fingerprint}, a
+// recorded kind, and the fingerprint of the current value). Values are
+// rendered as quoted data and never interpreted. A collection the summary
+// cannot read as its expected shape is said to be not recorded, and a blank
+// value reads not stated; neither is ever presented as complete.
+//
+// Pure: equal inputs give byte-identical output. No file, clock or
+// environment access; a failure is handed to the caller's onError.
+import { fieldSourceEntryMatches, SUMMARY_FIELDS } from "./build-brief.mjs";
+import { canonicalJson } from "./polish-capture.mjs";
+
+export const SUMMARY_WORD_LIMIT = 150;
+
+const NO_BRIEF_TEXT = "No Campaign Build Brief is recorded for this campaign. Ask the operator for purpose and audience before business-sensitive choices; never assume them.";
+const NOT_SUMMARISED_TEXT = "The Campaign Build Brief could not be summarised.";
+const COMMERCE_TEXT = "products, prices and offers come from CampaignSpec/API values; cart, checkout and post-purchase behaviour stay with the SDK.";
+
+// The provenance-stamped fields, in the order build-brief exports them. The
+// page-keyed field names a concrete page id in place of "<page>", joined by
+// plain concatenation so no character of the id is interpreted.
+const [AUDIENCE, CONVERSION_GOAL, TONE, PALETTE_SOURCE, PRIMARY_ACCENT, CTA_STYLE, AVOID, PAGE_SOURCE, BLOCK_PLACEHOLDERS] = SUMMARY_FIELDS;
+const [PAGE_SOURCE_PREFIX, PAGE_SOURCE_SUFFIX, ...PAGE_SOURCE_REST] = PAGE_SOURCE.split("<page>");
+if (PAGE_SOURCE_SUFFIX === undefined || PAGE_SOURCE_REST.length) {
+  throw new Error(`SUMMARY_FIELDS must name the page-keyed design authority field with exactly one "<page>" placeholder; got ${JSON.stringify(PAGE_SOURCE)}.`);
+}
+const pageSourceField = (pageId) => PAGE_SOURCE_PREFIX + pageId + PAGE_SOURCE_SUFFIX;
+
+const NOT_RECORDED = "not_recorded";
+// An active page whose id is missing or blank keeps its place in the journey.
+const PAGE_ID_NOT_RECORDED = "(page id not recorded)";
+const MARKERS = Object.freeze({ stated: "[stated]", source: "[from source]", default: "[default]", [NOT_RECORDED]: "[source not recorded]" });
+// Weakest first: a value whose origin was not recorded claims the least of
+// the marks; a part that reads not stated (null) claims less than any mark.
+const STRENGTH = Object.freeze([NOT_RECORDED, "default", "source", "stated"]);
+
+// design_authority.<page>.source values the generator writes; any other
+// non-null value is shown verbatim in its own group.
+const SUPPLIED_DESIGN = "provided_design_export";
+const TEMPLATE = "template";
+
+const VALUE_WORDS = 12;
+const FINAL_CUT_WORDS = 8;
+const LIST_CUT_LINES = Object.freeze([7, 4, 3]);
+
+const isPlainObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const own = (object, key) => (isPlainObject(object) && Object.hasOwn(object, key) ? object[key] : undefined);
+const valueAt = (brief, path) => path.split(".").reduce((value, key) => own(value, key), brief);
+const singleLine = (text) => text.replace(/\r\n|[\n\r\u2028\u2029]/g, " ");
+// Whitespace only, counting NEL (U+0085), which String.prototype.trim keeps.
+const isBlank = (value) => typeof value === "string" && !value.replace(/\u0085/g, "").trim();
+const notStated = (value) => value == null || isBlank(value);
+
+// C0, DEL and C1 control characters (ESC and NEL among them) written as \t or
+// \uXXXX escapes, so none reaches a prompt or terminal raw.
+const escapeControls = (text) => text.replace(/[\u0000-\u001f\u007f-\u009f]/g, (char) => (char === "\t" ? "\\t" : `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`));
+// Inside quotes, `\` and `"` are escaped first, so no value can close them.
+const escapeQuoted = (text) => escapeControls(text.replace(/[\\"]/g, "\\$&"));
+
+// stated | source | default | not_recorded, or null for an absent value.
+function provenanceOf(brief, field, value) {
+  if (value == null) return null;
+  const entry = own(own(own(brief, "_meta"), "field_sources"), field);
+  if (!fieldSourceEntryMatches(entry, value)) return NOT_RECORDED;
+  return entry.kind;
+}
+
+// The weakest mark among the parts a line or group shows; a part that reads
+// not stated makes it null, so it never claims a mark that part lacks.
+function weakest(provenances) {
+  if (!provenances.length || provenances.some((provenance) => provenance == null)) return null;
+  return STRENGTH[Math.min(...provenances.map((provenance) => STRENGTH.indexOf(provenance)))];
+}
+
+// A brief value as quoted data: line breaks collapse to spaces, the value is
+// trimmed and cut to `maxWords` words with "…", and escaped.
+function quoted(value, maxWords, cut) {
+  const text = singleLine(typeof value === "string" ? value : canonicalJson(value)).trim();
+  const words = text.split(/\s+/).filter(Boolean);
+  if (words.length > maxWords) cut.happened = true;
+  const kept = words.length > maxWords ? `${words.slice(0, maxWords).join(" ")}…` : text;
+  return `"${escapeQuoted(kept)}"`;
+}
+
+// A list cut to its first k items plus "+N more", where N counts what the
+// dropped items stand for (one each by default).
+function listItems(items, k, render, cut, weight = () => 1) {
+  if (k == null || items.length <= k) return items.map(render);
+  cut.happened = true;
+  const more = items.slice(k).reduce((sum, item) => sum + weight(item), 0);
+  return [...items.slice(0, k).map(render), `+${more} more`];
+}
+// A page id as displayed: unquoted, with line breaks collapsed to spaces and
+// control characters escaped.
+const pageIdText = (id) => (id == null ? PAGE_ID_NOT_RECORDED : escapeControls(singleLine(id)));
+
+function marked(value, provenance, maxWords, cut) {
+  return `${quoted(value, maxWords, cut)} ${MARKERS[provenance]}`;
+}
+
+// A blank string reads not stated, like an absent value.
+function field(brief, path) {
+  const raw = valueAt(brief, path);
+  const value = notStated(raw) ? null : raw;
+  return { value, provenance: provenanceOf(brief, path, value) };
+}
+
+// Line 1 and the line-5 palette clause have page-keyed generator values, so
+// they show a value only when the brief file states it.
+function statedOnly({ value, provenance }) {
+  return provenance === "stated" ? { value, provenance } : { value: null, provenance: null };
+}
+
+// Line 4: each active page in exactly one group, in the fixed group order;
+// each group carries the weakest marker among its pages. Authority and stamp
+// are read with the page id exactly as recorded; a page without one, or with
+// a blank source, reads not stated.
+function authorityGroups(brief, pageIds) {
+  const authority = own(brief, "design_authority");
+  const supplied = { kind: "supplied", source: SUPPLIED_DESIGN, pages: [], provenances: [] };
+  const template = { kind: "template", source: TEMPLATE, pages: [], provenances: [] };
+  const others = new Map();
+  const unstated = { kind: "not_stated", source: null, pages: [], provenances: [] };
+  for (const pageId of pageIds) {
+    const recorded = pageId == null ? null : own(own(authority, pageId), "source");
+    const source = notStated(recorded) ? null : recorded;
+    const provenance = pageId == null ? null : provenanceOf(brief, pageSourceField(pageId), source);
+    let group = unstated;
+    if (source === SUPPLIED_DESIGN) group = supplied;
+    else if (source === TEMPLATE) group = template;
+    else if (source != null) {
+      const key = canonicalJson(source);
+      if (!others.has(key)) others.set(key, { kind: "other", source, pages: [], provenances: [] });
+      group = others.get(key);
+    }
+    group.pages.push(pageId);
+    group.provenances.push(provenance);
+  }
+  return [supplied, template, ...others.values(), unstated]
+    .filter((group) => group.pages.length)
+    .map(({ provenances, ...group }) => ({ ...group, provenance: weakest(provenances) }));
+}
+
+function readModel(brief, activePageIds) {
+  // Page ids stay as recorded and are escaped only when rendered; a missing,
+  // non-string or blank id is null and keeps its place.
+  const pageIds = (Array.isArray(activePageIds) ? activePageIds : []).map((id) => (typeof id === "string" && !isBlank(id) ? id : null));
+  const avoid = field(brief, AVOID);
+  const avoidItems = avoid.value == null ? [] : Array.isArray(avoid.value) ? avoid.value : [avoid.value];
+  // Questions not recorded as a list are null, never read as none.
+  const questions = own(brief, "questions");
+  return {
+    purpose: statedOnly(field(brief, CONVERSION_GOAL)),
+    audience: field(brief, AUDIENCE),
+    journey: pageIds,
+    authority: authorityGroups(brief, pageIds),
+    palette: statedOnly(field(brief, PALETTE_SOURCE)),
+    buttons: field(brief, CTA_STYLE),
+    accent: field(brief, PRIMARY_ACCENT),
+    tone: field(brief, TONE),
+    avoid: { ...avoid, items: avoidItems, itemNotStated: avoidItems.some(notStated) },
+    placeholders: field(brief, BLOCK_PLACEHOLDERS),
+    questions: Array.isArray(questions) ? questions.map((question) => (typeof question?.id === "string" && !isBlank(question.id) ? singleLine(question.id.trim()) : "unnamed question")) : null,
+  };
+}
+
+// The nine lines, with the line-3/4/7 lists cut to `cuts[line]` items and the
+// line-1/2/5/6 values cut to `valueWords` words. Line 4 cut to k keeps its
+// first k groups, each with its first k page ids; "+N more" counts pages.
+function renderLines(model, cuts, valueWords) {
+  const cut = { happened: false };
+  const value = (item, fallback) => (item.value == null ? fallback : marked(item.value, item.provenance, valueWords, cut));
+  const group = (entry) => {
+    const ids = listItems(entry.pages, cuts[4], pageIdText, cut).join(", ");
+    if (entry.kind === "supplied") return `${ids} follow the supplied design ${MARKERS[entry.provenance]}`;
+    if (entry.kind === "template") return `${ids} follow the template ${MARKERS[entry.provenance]}`;
+    if (entry.kind === "other") return `${ids} use ${marked(entry.source, entry.provenance, VALUE_WORDS, cut)}`;
+    return `${ids} not stated`;
+  };
+  const avoid = model.avoid.value == null
+    ? "avoid not stated"
+    : `avoid ${model.avoid.items.length ? listItems(model.avoid.items, cuts[7], (item) => (notStated(item) ? "not stated" : quoted(item, VALUE_WORDS, cut)), cut).join("; ") : "none"} ${MARKERS[model.avoid.provenance]}`;
+  const placeholders = model.placeholders.value == null
+    ? "not stated"
+    : typeof model.placeholders.value === "boolean"
+      ? `${model.placeholders.value ? "yes" : "no"} ${MARKERS[model.placeholders.provenance]}`
+      : marked(model.placeholders.value, model.placeholders.provenance, VALUE_WORDS, cut);
+  const lines = [
+    `Purpose: ${value(model.purpose, "not stated")}.`,
+    `Audience: ${value(model.audience, "not stated")}.`,
+    model.journey.length ? `Journey: ${listItems(model.journey, cuts[3], pageIdText, cut).join(" → ")} (CampaignSpec).` : "Journey: not stated.",
+    model.authority.length ? `Visual authority: ${listItems(model.authority, cuts[4], group, cut, (entry) => entry.pages.length).join("; ")}.` : "Visual authority: not stated.",
+    `Palette and buttons: ${model.palette.value == null ? "palette source not stated" : `palette from ${marked(model.palette.value, "stated", valueWords, cut)}`}; button style ${value(model.buttons, "not stated")}; accent ${value(model.accent, "not stated")}.`,
+    `Tone: ${value(model.tone, "not stated")}.`,
+    `Preserve: ${avoid}; template placeholders removed: ${placeholders}.`,
+    `Commerce: ${COMMERCE_TEXT}`,
+    `Open brief questions: ${model.questions == null ? "not recorded" : model.questions.length ? model.questions.map(escapeControls).join(", ") : "none"}.`,
+  ];
+  const text = lines.join("\n");
+  return { text, wordCount: wordCount(text), cut: cut.happened };
+}
+
+function wordCount(text) {
+  return text.split(/\s+/).filter(Boolean).length;
+}
+
+// Within the word bound: cut one list at a time, in order, to its first k
+// items (k from 5 down to 1) until the bound holds: line 7, then line 4, then
+// line 3. Only if it still fails, cut the line-1/2/5/6 values to 8 words.
+// Lines 8 and 9 are never cut, and nothing is padded.
+function renderWithinBound(model) {
+  const cuts = {};
+  let rendered = renderLines(model, cuts, VALUE_WORDS);
+  for (const line of LIST_CUT_LINES) {
+    for (let k = 5; k >= 1 && rendered.wordCount > SUMMARY_WORD_LIMIT; k -= 1) {
+      cuts[line] = k;
+      rendered = renderLines(model, cuts, VALUE_WORDS);
+    }
+  }
+  if (rendered.wordCount > SUMMARY_WORD_LIMIT) rendered = renderLines(model, cuts, FINAL_CUT_WORDS);
+  return rendered;
+}
+
+function isPartial(model, cut) {
+  const values = [model.purpose, model.audience, model.palette, model.buttons, model.accent, model.tone, model.avoid, model.placeholders];
+  const missing = values.some((item) => item.value == null) || model.avoid.itemNotStated || !model.journey.length || model.journey.includes(null) || !model.authority.length;
+  const unrecorded = [...values, ...model.authority].some((item) => item.provenance === NOT_RECORDED);
+  const ungrouped = model.authority.some((group) => group.kind === "other" || group.kind === "not_stated");
+  return missing || unrecorded || ungrouped || model.questions == null || model.questions.length > 0 || cut;
+}
+
+const unavailable = (text) => ({ status: "unavailable", text, lines: [], word_count: wordCount(text), open_questions: [] });
+
+// Never throws. No brief reads the fixed no-brief text. A brief the summary
+// cannot be computed from (for example a value nested too deeply to
+// fingerprint) reads unavailable with its own text, and the error is passed
+// to `onError` so the caller can name it.
+export function summarizeCampaignBrief({ brief, activePageIds = [], onError } = {}) {
+  if (!isPlainObject(brief)) return unavailable(NO_BRIEF_TEXT);
+  try {
+    return summarize(brief, activePageIds);
+  } catch (error) {
+    onError?.(error);
+    return unavailable(NOT_SUMMARISED_TEXT);
+  }
+}
+
+function summarize(brief, activePageIds) {
+  const model = readModel(brief, activePageIds);
+  const rendered = renderWithinBound(model);
+  const line = (label, value, provenance) => ({ label, value, provenance });
+  return {
+    status: isPartial(model, rendered.cut) ? "partial" : "available",
+    text: rendered.text,
+    lines: [
+      line("Purpose", model.purpose.value, model.purpose.provenance),
+      line("Audience", model.audience.value, model.audience.provenance),
+      line("Journey", model.journey, null),
+      line("Visual authority", model.authority.map(({ pages, source, provenance }) => ({ page_ids: pages, source, provenance })), weakest(model.authority.map((group) => group.provenance))),
+      line("Palette and buttons", { commerce_palette_source: model.palette.value, cta_style: model.buttons.value, primary_accent: model.accent.value }, weakest([model.palette.provenance, model.buttons.provenance, model.accent.provenance])),
+      line("Tone", model.tone.value, model.tone.provenance),
+      line("Preserve", { avoid: model.avoid.value, block_placeholders: model.placeholders.value }, weakest([model.avoid.itemNotStated ? null : model.avoid.provenance, model.placeholders.provenance])),
+      line("Commerce", COMMERCE_TEXT, null),
+      line("Open brief questions", model.questions, null),
+    ],
+    word_count: rendered.wordCount,
+    open_questions: model.questions ?? [],
+  };
+}

package/src/build-brief.mjs

@@ -1,10 +1,27 @@
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { basename, extname, join, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
 
+import { cmd } from "./install-invocation.mjs";
+import { canonicalJson } from "./polish-capture.mjs";
 import { escapeRegExp } from "./repo-scan.mjs";
 
 export const BUILD_BRIEF_SCHEMA = "campaigns-os-build-brief/v1";
+// The brief value of a packet that carries no Campaign Build Brief, for both
+// material partitions and for every stage stamp made against it.
+export const BRIEF_ABSENT = "absent";
+// The fields the campaign intent summary prints, in its order. `<page>` stands
+// for each page id present in design_authority; _meta.field_sources keys use
+// the concrete id (design_authority.checkout.source).
+export const SUMMARY_FIELDS = Object.freeze(["campaign_intent.audience", "campaign_intent.conversion_goal", "campaign_intent.tone", "brand.commerce_palette_source", "brand.primary_accent", "brand.cta_style", "brand.avoid", "design_authority.<page>.source", "template_residue_policy.block_placeholders"]);
+const BRIEF_MODE_SOURCES = Object.freeze({ FIELD: "field", LEGACY_REPORT: "legacy_report", GENERATED: "generated" });
+// Codes of the errors normalization itself raises. They block in either mode;
+// evaluation gates block only a prepared brief.
+const NORMALIZATION_ERROR_CODES = Object.freeze(new Set(["build_brief.type", "build_brief.schema_version", "build_brief.brief_mode"]));
+// Top-level keys that never count as material: normalization and evaluation
+// output, and the declared mode. qa_policy.enforcement is fixed package text.
+const NON_MATERIAL_BRIEF_KEYS = Object.freeze(new Set(["_meta", "status", "questions", "gates", "confidence", "schema_version", "brief_mode"]));
 export const BUILD_BRIEF_NORMALIZED_REL_PATH = ".campaign-runtime/input/campaign-build-brief.normalized.json";
 export const BUILD_BRIEF_CANDIDATE_FILENAMES = Object.freeze([
   "campaign-build-brief.yaml",
@@ -169,6 +186,32 @@ export function loadCampaignBuildBriefFile(path) {
   return { path: resolvedPath, format, value: parsed };
 }
 
+// The mode a brief file declares, in rule order: brief_mode "prepared" or
+// "guided"; without brief_mode, prepared only when the report this write
+// replaces already recorded a prepared brief for the campaign (so it keeps the
+// blocking it was built under); otherwise guided. Any other brief_mode value
+// is a normalization error. The file's own _meta is never read.
+function briefModeFor(loaded, boundReportMode, errors) {
+  if (!loaded) return { mode: "guided_draft", source: BRIEF_MODE_SOURCES.GENERATED };
+  const declared = isObject(loaded.value) && Object.hasOwn(loaded.value, "brief_mode");
+  if (declared && loaded.value.brief_mode === "prepared") return { mode: "prepared", source: BRIEF_MODE_SOURCES.FIELD };
+  if (declared && loaded.value.brief_mode === "guided") return { mode: "guided_draft", source: BRIEF_MODE_SOURCES.FIELD };
+  if (declared) {
+    errors.push({
+      code: "build_brief.brief_mode",
+      field: "brief_mode",
+      message: `Campaign Build Brief brief_mode must be "prepared" or "guided" (got ${JSON.stringify(loaded.value.brief_mode)}); omit it for a guided brief.`,
+    });
+    return { mode: "guided_draft", source: BRIEF_MODE_SOURCES.FIELD };
+  }
+  if (boundReportMode === "prepared") return { mode: "prepared", source: BRIEF_MODE_SOURCES.LEGACY_REPORT };
+  return { mode: "guided_draft", source: BRIEF_MODE_SOURCES.GENERATED };
+}
+
+// `boundReportMode`: build_brief.mode on the Assembly Report this write
+// replaces, when that report belongs to the same campaign (mode rule 3).
+// `previousNormalizedBrief`: the normalized brief on disk before this write,
+// read for field provenance only.
 export function createCampaignBuildBriefArtifact({
   inputPath = null,
   inputSource = null,
@@ -178,19 +221,24 @@ export function createCampaignBuildBriefArtifact({
   templateFamily = null,
   sourceAssetCrawl = null,
   commerceZoneFindings = [],
+  boundReportMode = null,
+  previousNormalizedBrief = null,
 } = {}) {
   const loaded = inputPath ? loadCampaignBuildBriefFile(inputPath) : null;
-  const mode = loaded ? "prepared" : "guided_draft";
+  const errors = [];
+  const { mode, source: modeSource } = briefModeFor(loaded, boundReportMode, errors);
   const baseBrief = loaded
     ? cloneJsonOrEmpty(loaded.value)
     : draftCampaignBuildBrief({ spec, activePages, pageMappings, templateFamily, sourceAssetCrawl });
 
-  const errors = [];
   const normalized = normalizeCampaignBuildBrief(baseBrief, {
     mode,
+    modeSource,
     inputPath: loaded?.path || null,
     inputFormat: loaded?.format || "generated",
     inputSource,
+    fileValue: loaded ? loaded.value : null,
+    previousNormalizedBrief,
     spec,
     activePages,
     pageMappings,
@@ -222,9 +270,11 @@ export function createCampaignBuildBriefArtifact({
   normalized.questions = evaluation.questions;
   normalized.gates = gates;
 
+  // A prepared brief blocks on every blocker gate; a guided one only on the
+  // gates its normalization errors produced (the first errors.length gates).
   const blocking = mode === "prepared"
     ? blockerGates
-    : [];
+    : gates.slice(0, errors.length);
 
   return {
     mode,
@@ -278,24 +328,26 @@ export function validateCampaignBuildBriefArtifact(brief, { spec = null, normali
     if (questions.length) {
       errors.push({
         code: "build_brief.questions_unanswered",
-        message: `Prepared Campaign Build Brief has ${questions.length} unresolved business question(s): ${describeOpenQuestions(questions)}. Set those fields in the brief file and re-run start or prepare-build.`,
+        message: `Prepared Campaign Build Brief has ${questions.length} unresolved business question(s): ${describeOpenQuestions(questions)}. Set those fields in the brief file and save it with ${cmd("record")} brief --packet <packet>.`,
       });
     }
   } else {
     if (questions.length) {
       // An answer given in conversation is not recorded until it is in a
-      // brief file that start/prepare-build reads: the guided draft is
-      // regenerated on every run, and a brief file replaces it whole.
+      // brief file saved with record brief: the guided draft is regenerated
+      // on every intake, and a brief file replaces it whole.
       warnings.push({
         code: "build_brief.guided_questions",
-        message: `Generated Campaign Build Brief draft has ${questions.length} high-impact business question(s) to confirm: ${describeOpenQuestions(questions)}. `
-          + `An answer counts only once it is in a brief file: copy ${normalizedPath} to campaign-build-brief.json in the target repo, set those fields, and re-run start or prepare-build with the same arguments `
+        message: `Guided Campaign Build Brief has ${questions.length} high-impact business question(s) to confirm: ${describeOpenQuestions(questions)}. `
+          + `An answer counts only once it is saved: copy ${normalizedPath} to campaign-build-brief.json in the target repo, set those fields, and run ${cmd("record")} brief --packet <packet> `
           + "(the file is found there automatically, or pass --brief <file>). The file replaces the draft, so start from the copy to keep the fields the draft already filled. "
-          + "Once a stage has recorded evidence, that re-run needs --force, which clears the evidence.",
+          + "Saving keeps every stage's recorded evidence unless the brief's content changes.",
       });
     }
+    // Input errors block in both modes; evaluation gates stay warnings here.
     for (const gate of blockerGates) {
-      warnings.push({ code: gate.code || "build_brief.blocker", message: gate.message || "Generated Campaign Build Brief draft has an unresolved blocker." });
+      const target = brief.status === "invalid" && NORMALIZATION_ERROR_CODES.has(gate.code) ? errors : warnings;
+      target.push({ code: gate.code || "build_brief.blocker", message: gate.message || "Guided Campaign Build Brief has an unresolved blocker." });
     }
   }
 
@@ -351,6 +403,7 @@ function normalizeCampaignBuildBrief(value, meta, errors) {
   brief._meta = {
     generated_at: new Date().toISOString(),
     mode: meta.mode,
+    mode_source: meta.modeSource,
     input_path: meta.inputPath || null,
     input_format: meta.inputFormat || null,
     input_source: meta.inputSource || null,
@@ -368,20 +421,119 @@ function normalizeCampaignBuildBrief(value, meta, errors) {
   brief.template_residue_policy = normalizeResiduePolicy(brief.template_residue_policy);
   brief.qa_policy = normalizeQaPolicy(brief.qa_policy);
   brief.confidence = objectOrEmpty(brief.confidence);
+  brief._meta.field_sources = summaryFieldSources(brief, meta);
 
   return brief;
 }
 
+// The concrete summary field paths of a normalized brief: one
+// design_authority.<page>.source per page the brief lists.
+function summaryFieldPaths(brief) {
+  return SUMMARY_FIELDS.flatMap((path) => (path === "design_authority.<page>.source"
+    ? Object.keys(objectOrEmpty(brief.design_authority)).map((page) => `design_authority.${page}.source`)
+    : [path]));
+}
+
+// The value at a dotted path, reading the segment after `design_authority`
+// as one page id (a page id may itself contain a dot).
+function valueAtPath(value, path) {
+  const parts = path.startsWith("design_authority.") && path.endsWith(".source")
+    ? ["design_authority", path.slice("design_authority.".length, -".source".length), "source"]
+    : path.split(".");
+  let node = value;
+  for (const part of parts) {
+    if (!isObject(node) || !Object.hasOwn(node, part)) return undefined;
+    node = node[part];
+  }
+  return node;
+}
+
+function valueFingerprint(value) {
+  return `sha256:${createHash("sha256").update(canonicalJson(value)).digest("hex")}`;
+}
+
+// Whether `path` is one of the answer_fields of a question still open in the
+// previous normalized brief (design_authority.<page_id>.source matches any page).
+function answersOpenQuestion(path, previous) {
+  const questions = Array.isArray(previous?.questions) ? previous.questions : [];
+  return questions.some((question) => {
+    const entry = REQUIRED_HIGH_IMPACT_FIELDS.find((candidate) => candidate.id === question?.id);
+    return (entry?.answer_fields || []).some((field) => field === path
+      || (field === "design_authority.<page_id>.source" && path.startsWith("design_authority.") && path.endsWith(".source")));
+  });
+}
+
+// _meta.field_sources: {kind, value_fingerprint} per summary field. A
+// generated draft stamps every non-null value `default` (no draft value is
+// copied verbatim from a structured source field). From a file: a value absent
+// or null in the file is `default` when normalization filled one; a value the
+// file sets is `stated` when it answers an open question of the previous
+// brief or differs from the previous value (or there is no previous brief),
+// and otherwise keeps the previous entry. A null value gets no entry.
+function summaryFieldSources(brief, meta) {
+  const previous = isObject(meta.previousNormalizedBrief) ? meta.previousNormalizedBrief : null;
+  const previousSources = isObject(previous?._meta?.field_sources) ? previous._meta.field_sources : {};
+  const fromFile = isObject(meta.fileValue);
+  const sources = {};
+  for (const path of summaryFieldPaths(brief)) {
+    const value = valueAtPath(brief, path);
+    if (value === undefined || value === null) continue;
+    const entry = (kind) => ({ kind, value_fingerprint: valueFingerprint(value) });
+    const inFile = fromFile ? valueAtPath(meta.fileValue, path) : undefined;
+    if (!fromFile || inFile === undefined || inFile === null) {
+      sources[path] = entry("default");
+    } else if (answersOpenQuestion(path, previous) || !previous || canonicalJson(valueAtPath(previous, path) ?? null) !== canonicalJson(value)) {
+      sources[path] = entry("stated");
+    } else if (Object.hasOwn(previousSources, path) && fieldSourceEntryMatches(previousSources[path], value)) {
+      sources[path] = { kind: previousSources[path].kind, value_fingerprint: previousSources[path].value_fingerprint };
+    }
+  }
+  return sources;
+}
+
+const FIELD_SOURCE_KINDS = Object.freeze(["stated", "source", "default"]);
+
+/**
+ * Whether a _meta.field_sources entry can be read for `value`: exactly
+ * {kind, value_fingerprint}, a known kind, and the fingerprint of `value`.
+ * Any other entry is ignored.
+ */
+export function fieldSourceEntryMatches(entry, value) {
+  return isObject(entry)
+    && Object.keys(entry).length === 2
+    && FIELD_SOURCE_KINDS.includes(entry.kind)
+    && entry.value_fingerprint === valueFingerprint(value);
+}
+
+// The brief's material content, from the normalized artifact: `qa_policy`
+// (without its fixed enforcement note) and `presentation`, every other
+// top-level key that is not normalization output or the declared mode,
+// including keys the operator added.
+export function briefMaterialProjection(normalized) {
+  const brief = isObject(normalized) ? normalized : {};
+  // Entry-wise copies, so an operator key named __proto__ stays data.
+  const presentation = Object.fromEntries(Object.entries(brief).filter(([key]) => !NON_MATERIAL_BRIEF_KEYS.has(key) && key !== "qa_policy"));
+  const qaPolicy = Object.fromEntries(Object.entries(objectOrEmpty(brief.qa_policy)).filter(([key]) => key !== "enforcement"));
+  return { presentation, qa_policy: qaPolicy };
+}
+
+// Each partition as "sha256:<hex>" of its canonical JSON: key order,
+// whitespace, an explicit default and _meta never change it.
+export function briefMaterialFingerprint(normalized) {
+  const projection = briefMaterialProjection(normalized);
+  return { presentation: valueFingerprint(projection.presentation), qa_policy: valueFingerprint(projection.qa_policy) };
+}
+
 function draftCampaignBuildBrief({ spec, activePages, pageMappings, templateFamily, sourceAssetCrawl }) {
   const pageMap = new Map((pageMappings || []).map((page) => [page.page_id, page]));
-  const designAuthority = {};
-  for (const page of activePages || []) {
+  // Entry-wise, so a page id named __proto__ stays a page.
+  const designAuthority = Object.fromEntries((activePages || []).map((page) => {
     const mapped = pageMap.get(page.id);
-    designAuthority[page.id] = {
+    return [page.id, {
       source: mapped?.path ? "provided_design_export" : "template",
       reference: mapped?.path || mapped?.skip_reason || `${page.type || "page"} from selected template`,
-    };
-  }
+    }];
+  }));
 
   const variantSignals = collectVariantSignals(spec, sourceAssetCrawl);
   const paymentMethods = collectSpecPaymentMethods(spec);