@nextcommerce/campaigns-os 1.50.0 → 1.53.0

package/skills/next-campaigns-qa/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-qa
-version: 1.3.28
+version: 1.3.33
 description: Run spec-aware QA from a saved Map or local-spec Build Packet and tested campaign URL after build, polish, and deploy/local evidence exist, including Playwright typed-card test-order proof.
 ---
 
-Bundle revision: 1.50.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.50.0+skills.1`
+Bundle revision: 1.53.0+skills.2
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.53.0+skills.2`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read
@@ -70,6 +70,7 @@ Inputs:
 - tested base URL (localhost dev URL, preview URL, or production URL)
 - assembly report
 - Test-order coverage choice (`common` default vs explicit paths vs topology-complete `full`) and SDK origin state (localhost is a Development domain; non-localhost origins need allowlist confirmation so the SDK loads)
+- Read the normalized Campaign Build Brief at `.campaign-runtime/input/campaign-build-brief.normalized.json` and the recorded decisions (`adapter_decisions`, `decisions` and `theme` in `.campaign-runtime/assembly-report.json`, and `assembly.template_decision_notes` in the Build Packet) before working on the campaign. The campaign intent summary at the top of the setup, build, Polish and QA prompts and in every `next` result is orientation, never a source of prices or commerce behaviour.
 
 Rules:
 
@@ -89,7 +90,7 @@ Rules:
 - A typed-card path that fails is classified by **what it did to the store** before the runner decides what to do about it. A failure the runner can prove happened before submit (`not_created`) is **re-run once, if the creation budget has a slot no still-unrun planned path needs** — so a transient miss is not reported as a defect in the build, without an early path eating budget the last planned paths need. Under the default budget a path whose submit was *rejected* has already spent its own slot, so it is not re-run and records `evidence.order_creation.rerun_skipped` instead. When the re-run does happen, both attempts appear in `test_orders[]` and `evidence.retry` names the first attempt's error and ref id. A failure that happened **after** the order was created (`created` — most often a receipt that did not render) is **never resubmitted**: the runner reloads that order's receipt and re-runs only the read-only checks, and `evidence.recovery` carries the original failure, the checks re-run, and whether it cleared. Read `evidence.order_creation` for two separate counts: `submissions_reserved` (platform-side creation slots charged to this path — reserved before a submit click, or charged for a hosted-checkout redirect where no submit click happens — which stand even when the create then failed) and `orders_confirmed_created` (creates the platform was observed to accept) — a spent slot with no confirmed order is the ambiguous case, not an order to reconcile. Recovery clears only on persisted evidence it re-read on that pass: a failed or absent order read-back stops it honestly rather than re-deciding against the original attempt's numbers. An outcome it cannot prove either way (`ambiguous` — an unusable read-back, a lost create response, a network-failed create, a 4xx after an earlier 2xx) stops the path and names the operator check instead of buying again. A pass that only came back after recovery is never indistinguishable from a first-attempt pass, and a failure that survives recovery still blocks.
 - Analytics correctness is two-phase in the same run: the campaign-root visit inventories declared providers/tags only, then the one canonical typed-card run proves Purchase for each topology-recognized receipt from the signals emitted across every page the path loaded after checkout, read after the full `--analytics-settle` window. The receipt qualifies the order; the journey is measured, because the SDK fires `dl_purchase` (and the outbound Purchase) on the first `?ref_id=` page — the upsell page when the funnel has one — and dedupes it on the receipt. It never places a second analytics order. The receipt document's own reading stays in evidence (`receipt_signals`, `fired_on`) as the diagnostic of which document fired.
 - A missing or topology-unrecognized receipt is `MANUAL_REVIEW`/`WARN`; a recognized receipt with no dataLayer, outbound Meta, or outbound GA4 Purchase is `FAIL`/`BLOCKER`. Capture, unreadable-page, and settle-deadline errors on a recognized receipt are explicit non-waivable blockers. The `analytics-correctness:purchase-fires` waiver applies only to a genuine recognized-receipt/no-signal failure, and is recorded with `campaigns-os qa waive --assertion analytics-correctness:purchase-fires --reason "<why>"` (tier `C`: it overwrites the assembly report and doctor output; the lane is scoped to that one assertion and every other is refused).
-- Keep QA in a tight sequence: install the Playwright browser, resolve topology, run browser QA plus typed-card proof with `--test-order common` by default. Test orders need no permission step. Pause only for missing inputs, out-of-scope runtime pages that block checkout proof, or merchant-specific uncertainty.
+- Keep QA in a tight sequence: install the Playwright browser, resolve topology, run browser QA plus typed-card proof with `--test-order common` by default. `qa run` has no permission flag: coverage is its only control. Test orders still land in the store as real orders that someone may have to cancel, so unless the operator has already said test orders are fine for this campaign, ask once, up front in your first turn with your other setup questions. When the operator has answered, at the start of this session or earlier in the build, follow that answer and do not pause QA to ask again. When nobody asked, ask once before the first test order rather than skip the question. Otherwise pause only for missing inputs, out-of-scope runtime pages that block checkout proof, or merchant-specific uncertainty.
 - Use `--browser` for rendered browser evidence. Browser QA must use the package-owned Playwright flow, not external agent/browser skills.
 - Saved-Map QA publishes to the QA portal under the existing consent and flag controls; report the portal link only when publication succeeds. Pass `--no-post-verdict` (or `--local-only`) to keep that verdict local. This stays tier `C`: served-page probes, requested orders, Run Telemetry and progress retain their own controls. See `docs/qa-and-test-orders.md` for the saved-Map publication policy.
 - Local-spec QA always keeps verdicts and progress local. `qa run` suppresses portal publication even with `--post-verdict`; `qa publish` refuses local-spec packets with `local_spec`. Report the local verdict/sidecar as evidence, never a dashboard link. A matching route cannot replace a matching `local_spec_id`, and QA refuses a foreign or stale local Assembly Report. Run Telemetry still follows its consent controls.
@@ -116,11 +117,13 @@ Rules:
 - A path with remaining actions may stop cleanly only at a terminal recognized in that selected topology. Missing accept/decline controls on any other page are blockers. A cross-origin handoff is a valid terminal navigation but is not receipt-rendering or persisted-receipt proof.
 - Keep multi-funnel and `tiers:common` / `tiers:full` plans isolated to each selected checkout's own funnel graph, tiers, and recognized terminals; never borrow an unrelated funnel's receipt page.
 - Accepted-upsell proof is valid only when the browser observes the order upsell API mutation and the final order evidence contains the selected upsell package. A checkout bump line marked `is_upsell` is not accepted-upsell proof.
-- Test orders are safe to fire any time: global test cards bypass the gateway, create no transactions, and need no merchant-specific sandbox routing confirmation. Localhost on any port is globally available as a Campaigns App Development domain and suppresses Campaigns analytics; non-localhost preview/production origins must be allowlisted for the campaign API key so the SDK loads — that is about SDK initialization, not test-order permission.
+- Test orders are real orders in the store, but global test cards bypass the gateway: no charge, no transaction, and no merchant-specific sandbox routing to confirm. Localhost on any port is globally available as a Campaigns App Development domain and suppresses Campaigns analytics; non-localhost preview/production origins must be allowlisted for the campaign API key so the SDK loads — that is about SDK initialization, not test-order permission.
 - Launch readiness is separate from Campaigns OS proof. If QA passes on local/preview, still surface production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration as real-shopper readiness items before launch.
 - For multi-market campaigns, verify at least one non-default currency/country path: currency display, shipping method names/prices, available payment methods, and market-specific copy.
 - Treat missing deploy URL, missing polish status, or unresolved doctor blockers as launch blockers.
 - Report blockers, warnings, and residual risks.
+- When a readability warning appears, report it with its colours, ratio, requirement and pages. Offer the operator options inside the brand palette (a darker or lighter shade of the same hue, the palette's text colour, or a larger, bold label where the design allows). Do not recolour the merchant's design until the operator chooses. Accept a warning only with the refs, reason and name the operator gives you at the QC handoff.
+- At the end of QA, run `next` and present the QC handoff once. Ask the operator which open warnings to accept and why. Run `checkpoint accept` only with the refs, reason, and name the operator gave you in this conversation. Never write `qc_accepts`, `qc_results`, or QA verdict files by hand. The up-front test-order permission does not cover accepts.
 - QA follows build and polish; it does not edit campaign code.
 
 Canonical test-order flow:

package/skills.json

@@ -1,7 +1,7 @@
 {
   "name": "campaigns-os-skills",
   "description": "Skills bundled with Campaigns OS. `skills.sh` installs these into the shared agent skill directories (~/.claude/skills, ~/.codex/skills), so each one is a versioned package: bump the version whenever a package changes. `bundle_revision` identifies the bundle as a whole — `<package version>+skills.<n>`, where the prefix is this package's version and `<n>` counts the skill-text revisions published against it. It advances whenever ANY bundled skill changes, every SKILL.md states it on its first body line, and `campaigns-os tooling status --skills-revision <value>` compares the value an agent read from a skill against the bundle on disk. See docs/skills-revision.md.",
-  "bundle_revision": "1.50.0+skills.1",
+  "bundle_revision": "1.53.0+skills.2",
   "homepage": "https://github.com/NextCommerceCo/campaigns-os",
   "retired_skills": [
     {
@@ -16,7 +16,7 @@
     {
       "id": "next-campaigns-os",
       "name": "Campaigns OS Lifecycle",
-      "version": "1.0.44",
+      "version": "1.0.49",
       "path": "skills/next-campaigns-os/SKILL.md",
       "domain": "campaigns",
       "description": "Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth."
@@ -24,7 +24,7 @@
     {
       "id": "next-campaigns-os-setup",
       "name": "Campaigns OS Setup",
-      "version": "2.0.27",
+      "version": "2.0.32",
       "path": "skills/next-campaigns-os-setup/SKILL.md",
       "domain": "campaigns",
       "description": "Bootstrap or prepare a target page-kit campaign repo from a doctor-cleared Campaigns OS Build Packet before full build wiring. Formerly next-campaigns-setup; renamed to release that name to the published NextCommerceCo/skills scaffolder."
@@ -32,7 +32,7 @@
     {
       "id": "next-campaigns-build",
       "name": "Campaign Build",
-      "version": "1.0.29",
+      "version": "1.0.34",
       "path": "skills/next-campaigns-build/SKILL.md",
       "domain": "campaigns",
       "description": "Assemble a NEXT campaign from a doctor-cleared Build Packet, CampaignSpec/API values, prepared HTML/assets, page-kit, and starter-template contracts."
@@ -40,7 +40,7 @@
     {
       "id": "next-campaigns-polish",
       "name": "Campaign Polish",
-      "version": "1.1.28",
+      "version": "1.1.33",
       "path": "skills/next-campaigns-polish/SKILL.md",
       "domain": "campaigns",
       "description": "Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign."
@@ -48,7 +48,7 @@
     {
       "id": "next-campaigns-qa",
       "name": "Campaign QA",
-      "version": "1.3.28",
+      "version": "1.3.33",
       "path": "skills/next-campaigns-qa/SKILL.md",
       "domain": "campaigns",
       "description": "Run spec-aware QA from a saved Map or local-spec Build Packet and tested campaign URL after build, polish, and deploy/local evidence exist, including Playwright typed-card test-order proof."
@@ -56,7 +56,7 @@
     {
       "id": "campaign-lifecycle-orientation",
       "name": "Campaign Lifecycle Orientation",
-      "version": "1.0.24",
+      "version": "1.0.29",
       "path": "skills/campaign-lifecycle-orientation/SKILL.md",
       "domain": "campaigns",
       "description": "Orient a reader to the Campaigns OS lifecycle artifacts a run has already emitted, without advancing their state: the shared vocabulary, doctor as a gate, the stage record, and the store-theme/Page Kit two-worlds trap."
@@ -64,7 +64,7 @@
     {
       "id": "campaign-run-evidence",
       "name": "Campaign Run Evidence",
-      "version": "1.0.24",
+      "version": "1.0.29",
       "path": "skills/campaign-run-evidence/SKILL.md",
       "domain": "campaigns",
       "description": "Interpret existing doctor, QA verdict and proof-depth evidence without claiming more proof than the artifacts contain, and keep funnel proof apart from merchant launch readiness."
@@ -72,7 +72,7 @@
     {
       "id": "campaign-readback-classification",
       "name": "Campaign Readback Classification",
-      "version": "1.0.24",
+      "version": "1.0.29",
       "path": "skills/campaign-readback-classification/SKILL.md",
       "domain": "campaigns",
       "description": "Classify a selected campaign from the campaigns-os-readback/v2 fields (artifacts, staleness.stale_keys, clean, doctor, divergences, skip_cascades) and write a read-only handoff without turning diagnosis into permission."
@@ -80,7 +80,7 @@
     {
       "id": "contribution-intake",
       "name": "Contribution Intake",
-      "version": "1.0.24",
+      "version": "1.0.29",
       "path": "skills/contribution-intake/SKILL.md",
       "domain": "campaigns",
       "description": "Turn a suggestion about the agent surface into a classified, evidence-checked and redacted proposal, filed on this repository tracker only with attended approval."

package/src/adapter-decision-contract.mjs

@@ -317,7 +317,7 @@ function validateTemplateSlicePaths(copied, location, targetRepo, warnings, read
 
 function checkEnum(value, allowed, code, warnings, addIssue) {
   if (value == null) return;
-  if (!allowed.has(value)) addIssue(warnings, code, `${code} has unknown value "${value}".`);
+  if (!allowed.has(value)) addIssue(warnings, code, `${code} has unknown value ${JSON.stringify(value)}; allowed values: ${[...allowed].join(", ")}.`);
 }
 
 function isObject(value) {

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,
@@ -88,6 +89,18 @@ function loadContracts(repoRoot = ROOT) {
   };
 }
 
+// A theme write error as the Assembly Report's theme.warnings[] carries it
+// (schema $defs.themeIssue): detail, when present, must be an object, so an
+// issue without one omits the key rather than writing null.
+export function themeIssueForReport(error) {
+  const detail = error?.detail;
+  return {
+    code: error?.code,
+    message: error?.message,
+    ...(detail && typeof detail === "object" && !Array.isArray(detail) ? { detail } : {}),
+  };
+}
+
 function issue(code, message, detail = null) {
   return detail ? { code, message, detail } : { code, message };
 }
@@ -665,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
@@ -696,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",
   };
 }
@@ -720,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",
   };
 }
@@ -756,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
@@ -767,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,
@@ -881,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 ?? [],
+  };
+}