@nextcommerce/campaigns-os 1.33.0

package/src/consent.mjs

@@ -0,0 +1,347 @@
+// Run Telemetry consent — machine/user-level opt-OUT, resolved through one
+// shared resolver that EVERY remitting command calls (not a start-only
+// prompt). See docs/workflow-findings-sidecar.md (Consent).
+//
+// Consent gates REMIT only. Local capture (the Run Record) always happens.
+// Resolution precedence: env override > user-level config file > default.
+// The DEFAULT is ON for the canonical NEXT endpoint only (announced at remit
+// time with the endpoint and the opt-out command); any other endpoint stays
+// fail-closed until explicitly consented. An unknown env value fails closed
+// (no remit) with a warning, never a silent guess; a malformed config file
+// also resolves OFF — an unreadable prior choice is never overridden by the
+// default.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const TELEMETRY_ENV_VAR = "CAMPAIGNS_OS_TELEMETRY";
+export const TELEMETRY_CONFIG_SCHEMA = "campaigns-os-telemetry-config/v0";
+const PACKAGE_NAME = "@nextcommerce/campaigns-os";
+
+// Env override accepts exactly these tokens. Anything else is "unknown" and
+// fails closed — strictness is the point (an env typo must not silently remit).
+const ENV_TRUE = new Set(["1", "true", "on"]);
+const ENV_FALSE = new Set(["0", "false", "off"]);
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+export function normalizeConsentScope(value) {
+  if (!isNonEmptyString(value)) return null;
+  const raw = value.trim();
+  const normalizeUrl = (input) => {
+    try {
+      const url = new URL(input);
+      const path = url.pathname.replace(/\/+$/, "");
+      return `${url.origin}${path}`;
+    } catch {
+      return null;
+    }
+  };
+  const direct = normalizeUrl(raw);
+  if (direct) return direct;
+  if (!/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(raw)) {
+    return normalizeUrl(`https://${raw}`);
+  }
+  return null;
+}
+
+// The canonical NEXT remit endpoint. Default-on consent applies ONLY to this
+// scope; any other proxy base needs an explicit operator choice. Stored in
+// NORMALIZED form (and asserted at module load) so a scheme change, typo, or
+// trailing slash here cannot silently flip the default; compare requested
+// scopes against this export, never against a string literal.
+export const CANONICAL_REMIT_SCOPE = normalizeConsentScope("https://campaign-map.nextcommerce.com");
+if (!CANONICAL_REMIT_SCOPE) {
+  throw new Error("CANONICAL_REMIT_SCOPE failed to normalize; default-on consent would misfire.");
+}
+
+function assertConsentState(state) {
+  if (state !== "on" && state !== "off") {
+    throw new Error('Telemetry consent state must be "on" or "off".');
+  }
+}
+
+function defaultWarn(message) {
+  process.stderr.write(`${message}\n`);
+}
+
+function configState(state) {
+  assertConsentState(state);
+  return state === "on";
+}
+
+/**
+ * Parse the CAMPAIGNS_OS_TELEMETRY env value.
+ * Returns `{ state: "on"|"off"|null, present, unknown }`.
+ * - absent/empty: `{ state: null, present: false, unknown: false }`
+ * - recognized:   `{ state, present: true, unknown: false }`
+ * - anything else:`{ state: null, present: true, unknown: true }` (fail closed)
+ */
+export function parseEnvConsent(raw) {
+  if (raw == null) return { state: null, present: false, unknown: false };
+  const normalized = String(raw).trim().toLowerCase();
+  if (normalized === "") return { state: null, present: false, unknown: false };
+  if (ENV_TRUE.has(normalized)) return { state: "on", present: true, unknown: false };
+  if (ENV_FALSE.has(normalized)) return { state: "off", present: true, unknown: false };
+  return { state: null, present: true, unknown: true };
+}
+
+/**
+ * User-level config path. Consent belongs to the operator/machine, not the
+ * campaign. Honors XDG_CONFIG_HOME, else ~/.config/campaigns-os/config.json.
+ */
+export function resolveConfigPath({ env = process.env, home = homedir() } = {}) {
+  const base = isNonEmptyString(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : join(home, ".config");
+  return join(base, "campaigns-os", "config.json");
+}
+
+/**
+ * Read the config file. Never throws — a missing file is `{ ok: false }`, a
+ * malformed file is `{ malformed: true }` (the resolver treats that as OFF).
+ */
+export function readConfig(configPath) {
+  if (!isNonEmptyString(configPath) || !existsSync(configPath)) {
+    return { ok: false, config: null, malformed: false };
+  }
+  try {
+    const config = JSON.parse(readFileSync(configPath, "utf8"));
+    if (!config || typeof config !== "object" || Array.isArray(config)) {
+      return { ok: false, config: null, malformed: true };
+    }
+    return { ok: true, config, malformed: false };
+  } catch {
+    return { ok: false, config: null, malformed: true };
+  }
+}
+
+function fileConsentState(config) {
+  const telemetry = config?.telemetry;
+  if (telemetry && typeof telemetry === "object") {
+    if (telemetry.enabled === true) return "on";
+    if (telemetry.enabled === false) return "off";
+  }
+  return null;
+}
+
+function fileConsentScope(config) {
+  return normalizeConsentScope(config?.telemetry?.scope);
+}
+
+function scopeMatches(storedScope, requestedScope) {
+  const requested = normalizeConsentScope(requestedScope);
+  if (!requested) return true;
+  const stored = normalizeConsentScope(storedScope);
+  return Boolean(stored && stored === requested);
+}
+
+/**
+ * Persist consent at user level. Records its own schema_version, the package
+ * name, the proxy/endpoint scope (ON only — an OFF record is unscoped), a
+ * timestamp, and the value source — so the decision is auditable. A named
+ * `proxyBase` that is not a URL is refused for either state. Returns
+ * `{ configPath, config }`.
+ */
+export function writeConsentConfig(state, {
+  configPath = resolveConfigPath(),
+  proxyBase = null,
+  source = "telemetry-command",
+  now = new Date(),
+} = {}) {
+  const enabled = configState(state);
+  const normalizedScope = normalizeConsentScope(proxyBase);
+  // A named base that does not normalize is refused for either state: on an
+  // ON grant it would be stored as `scope: null`, which matches no endpoint
+  // and turns the grant into a silent OFF at every remit; on an OFF record
+  // it would be dropped without a word, hiding a typo the caller meant to
+  // be honoured. (An absent base still writes `scope: null`: an unscoped
+  // record, matched only by a caller that names no endpoint.)
+  if (isNonEmptyString(proxyBase) && !normalizedScope) {
+    throw new Error(`Telemetry consent scope is not a URL: ${proxyBase.trim()}`);
+  }
+  // An OFF choice is machine-wide — it disables remit to every endpoint — so
+  // the record carries no scope: `enabled: false, scope: <url>` would read
+  // as a still-granted endpoint on disk and in `telemetry status`.
+  const scope = enabled ? normalizedScope : null;
+  const config = {
+    schema_version: TELEMETRY_CONFIG_SCHEMA,
+    package: PACKAGE_NAME,
+    telemetry: {
+      enabled,
+      scope,
+      updated_at: now.toISOString(),
+      source,
+    },
+  };
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+  return { configPath, config };
+}
+
+/**
+ * The command that records file consent for one endpoint. The canonical
+ * endpoint needs no flag; any other base is named explicitly so the grant is
+ * visibly scoped to it.
+ */
+export function scopedConsentCommand(scope) {
+  const normalized = normalizeConsentScope(scope);
+  if (!normalized || normalized === CANONICAL_REMIT_SCOPE) return "campaigns-os telemetry on";
+  return `campaigns-os telemetry on --proxy-base ${shellArgument(normalized)}`;
+}
+
+// The generated command is meant to be pasted into a shell. A URL made of
+// the characters below passes through every common shell as one word; any
+// other character (the brackets of an IPv6 loopback such as http://[::1]:4399
+// glob in zsh) gets single quotes so the copy still grants the endpoint.
+const SHELL_SAFE_ARGUMENT = /^[A-Za-z0-9._~:/@%+=,-]+$/;
+
+function shellArgument(value) {
+  if (SHELL_SAFE_ARGUMENT.test(value)) return value;
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * The shared resolver every remitting command calls. Returns
+ * `{ state: "on"|"off", source: "env"|"file"|"default", resolved }`.
+ * With no env and no usable file, the CANONICAL endpoint resolves to the
+ * announced default: `{ state: "on", source: "default", resolved: true,
+ * default_on: true }`. `resolved` is false only for the remaining
+ * fail-closed defaults — a malformed config file, a scope mismatch, or a
+ * non-canonical endpoint with no explicit choice — where an interactive
+ * command may then prompt to set it.
+ */
+export function resolveConsent({
+  env = process.env,
+  configPath = resolveConfigPath(),
+  proxyBase = null,
+  warn = defaultWarn,
+} = {}) {
+  const raw = env[TELEMETRY_ENV_VAR];
+  const parsed = parseEnvConsent(raw);
+  // Normalized once; both the file-scope branch and the default branch
+  // compare against this same value.
+  const requestedScope = normalizeConsentScope(proxyBase);
+  if (parsed.unknown) {
+    warn(`[campaigns-os] ${TELEMETRY_ENV_VAR}="${raw}" is not a recognized value (use 1|true|on|0|false|off). Telemetry remit is OFF for safety.`);
+    return { state: "off", source: "env", resolved: true };
+  }
+  if (parsed.state) {
+    // The env override is a machine-wide answer with no scope: it applies to
+    // whatever endpoint the command names. When that is not the canonical
+    // endpoint, say so — the operator gets the persistent, scoped route.
+    if (parsed.state === "on" && requestedScope && requestedScope !== CANONICAL_REMIT_SCOPE) {
+      warn(`[campaigns-os] ${TELEMETRY_ENV_VAR}=${raw} bypasses consent scope checking: remitting to ${requestedScope} because the env override is set, not because this endpoint was consented to. To consent to it on this machine instead, run: ${scopedConsentCommand(requestedScope)}`);
+      return { state: "on", source: "env", resolved: true, scope: requestedScope, scope_bypassed: true };
+    }
+    if (parsed.state === "on") {
+      return { state: "on", source: "env", resolved: true, scope: requestedScope || CANONICAL_REMIT_SCOPE };
+    }
+    return { state: "off", source: "env", resolved: true };
+  }
+
+  const { ok, config, malformed } = readConfig(configPath);
+  if (malformed) {
+    warn(`[campaigns-os] telemetry config at ${configPath} is malformed; treating telemetry as OFF.`);
+    return { state: "off", source: "default", resolved: false };
+  }
+  if (ok) {
+    const fileState = fileConsentState(config);
+    if (fileState === "off") return { state: "off", source: "file", resolved: true };
+    if (fileState === "on") {
+      const storedScope = fileConsentScope(config);
+      if (scopeMatches(storedScope, requestedScope)) {
+        return { state: "on", source: "file", resolved: true, scope: storedScope };
+      }
+      warn(`[campaigns-os] telemetry consent at ${configPath} is scoped to ${storedScope || "(unscoped)"}, not ${requestedScope}; treating telemetry as OFF for this endpoint. To consent to it on this machine, run: ${scopedConsentCommand(requestedScope)}`);
+      return {
+        state: "off",
+        source: "default",
+        resolved: false,
+        scope_mismatch: true,
+        consent_scope: storedScope,
+        requested_scope: requestedScope,
+      };
+    }
+  }
+
+  // No env, no usable file → default ON for the canonical NEXT endpoint.
+  // Run Telemetry is how the toolchain improves (capture is always local;
+  // this gates only the remit), so an operator who never expressed a choice
+  // shares by default and opts out with `campaigns-os telemetry off` or
+  // CAMPAIGNS_OS_TELEMETRY=off. The grant is exactly two cases:
+  //   1. proxyBase ABSENT (null/undefined/empty) — remitting commands fall
+  //      back to the canonical default endpoint, so the scope IS canonical;
+  //   2. proxyBase normalizes to the canonical scope.
+  // A non-empty proxyBase that fails to normalize is NOT canonical — it
+  // stays fail-closed like any other unapproved endpoint. The remit-time
+  // announcement names the endpoint explicitly.
+  // (An absent proxyBase always normalizes to a null requestedScope, so the
+  // two cases below are disjoint: absent → canonical fallback; present →
+  // must normalize to the canonical scope exactly.)
+  const proxyBaseAbsent = !isNonEmptyString(proxyBase);
+  if (proxyBaseAbsent || requestedScope === CANONICAL_REMIT_SCOPE) {
+    return { state: "on", source: "default", resolved: true, default_on: true, scope: CANONICAL_REMIT_SCOPE };
+  }
+  return { state: "off", source: "default", resolved: false };
+}
+
+// Announce default-on telemetry at most once per process, naming the exact
+// endpoint so the operator knows where the data goes before it goes there.
+// Once-per-PROCESS is the designed semantic: the CLI is one-shot, so this is
+// once per command for normal usage, while a long-lived harness importing
+// remitting commands directly gets one announcement per process instead of
+// stderr noise on every record. The injectable `write` keeps the contract
+// testable without exposing the latch.
+let defaultOnAnnounced = false;
+export function announceDefaultOnTelemetry(endpoint, { write = (line) => process.stderr.write(line) } = {}) {
+  if (defaultOnAnnounced) return false;
+  defaultOnAnnounced = true;
+  write(`[campaigns-os] Run telemetry is ON by default: anonymized run records are sent to ${endpoint || CANONICAL_REMIT_SCOPE} to improve templates, tooling, and guidance. Disable with \`campaigns-os telemetry off\` or CAMPAIGNS_OS_TELEMETRY=off.\n`);
+  return true;
+}
+
+async function defaultAsk(question) {
+  const { createInterface } = await import("node:readline/promises");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * The up-front, ask-once prompt. Only prompts when interactive (TTY) AND no
+ * resolved state exists yet — which, under default-on for the canonical
+ * endpoint, means the prompt effectively fires only for NON-canonical remit
+ * scopes (staging/self-hosted) that need an explicit yes. Persists the
+ * answer so later runs don't re-ask. Non-interactive unresolved callers stay
+ * fail-closed OFF without blocking — telemetry never blocks a build. `ask`
+ * is injectable for tests.
+ *
+ * The [Y/n] capitalization makes "on" the default for an empty Enter, matching
+ * the design's plainly-worded prompt.
+ */
+export async function promptAndPersistConsent({
+  configPath = resolveConfigPath(),
+  env = process.env,
+  proxyBase = null,
+  isTTY = Boolean(process.stdin && process.stdin.isTTY),
+  ask = defaultAsk,
+  now = new Date(),
+} = {}) {
+  // An explicit env/file decision is never overridden by a prompt.
+  const existing = resolveConsent({ env, configPath, proxyBase, warn: () => {} });
+  if (existing.resolved) return { ...existing, prompted: false };
+  if (!isTTY) return { state: "off", source: "default", resolved: false, prompted: false };
+
+  const answer = await ask(
+    "Campaigns OS can send build telemetry to Next Commerce to improve templates, tools, and guidance. Share telemetry from this machine? [Y/n] (change any time): ",
+  );
+  const normalized = String(answer || "").trim().toLowerCase();
+  const state = (normalized === "" || ["y", "yes", "1", "true", "on"].includes(normalized)) ? "on" : "off";
+  writeConsentConfig(state, { configPath, proxyBase, source: "prompt", now });
+  return { state, source: "file", resolved: true, prompted: true };
+}

package/src/content-residue.mjs

@@ -0,0 +1,322 @@
+// Rendered-output content-residue scan + proof-attestation gate.
+//
+// Scans BUILT campaign output (_site HTML), not frontmatter: layout- or
+// script-rendered proof/urgency chrome only exists after the build, which is
+// why frontmatter-level checks missed the hardcoded rating/countdown chrome.
+//
+// Pattern provenance: the generic anti-pattern classes distilled from the
+// 2026-07 winning-campaign content audit (invented counts, fabricated
+// verified-buyer chrome, fictional bylines, borrowed authority, science
+// theater, scarcity theater, fake comparisons, unlinked press marquees).
+// Only GENERIC patterns and the public starter-template demo strings live
+// here; merchant-specific residue fingerprints are deliberately not carried
+// in this public package.
+//
+// Posture (fail closed, two tiers):
+// - hard: the literal needs-merchant-input marker, and urgency chrome
+//   rendered without verified offer urgency — blockers (collect-inputs).
+// - review: anti-pattern hits and demo/placeholder residue — warnings that
+//   feed the review/attestation queue; a hit means "remove or demand
+//   brief/source evidence", never "make it more plausible".
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+export const NEEDS_INPUT_MARKER = /NEEDS[ -]MERCHANT[ -]INPUT/i;
+
+// Countdown chrome as rendered by the starter presell templates.
+export const COUNTDOWN_CHROME = /data-countdown-(?:hrs|min|sec)/;
+
+// Bracket-style demo stubs ("[Product]", "[Author Name]", "[Real Review
+// Proof Goes Here]"). Requires a capitalized first word so CSS/JS attribute
+// selectors ([data-x], [href]) never match.
+export const BRACKET_STUB = /\[(?:[A-Z][A-Za-z0-9/&().,'’-]*)(?:\s+[A-Za-z0-9/&().,'’-]+)*\]/;
+
+// Public starter-template demo values that must never survive into a built
+// campaign. The templates deliberately keep realistic, proof-shaped demo
+// content (demo teaches the SHAPE of typical content); this exact-string list
+// is what keeps that demo content from silently shipping — a hit means an
+// unreplaced demo slot or a stale template.
+export const DEMO_RESIDUE_TERMS = Object.freeze([
+  "Sarah Mitchell",
+  "Wellness Insider",
+  "10 Reasons Why You Need This",
+  "10 Reasons Why Thousands Are Switching",
+  "Backed by Over 1,200 Five-Star Reviews",
+  "Trusted by 50,000+ Happy Customers",
+  "Doctor-Formulated for Real Results",
+  "Made in an FDA-Registered Facility",
+  "Lowest Price of the Year",
+  "DEAL ENDING IN:",
+  "1,247 reviews",
+  "48,312",
+  "48,000+",
+  "Sandra M.",
+  "Derek H.",
+  "Sell-Out Risk: High",
+]);
+
+// Generic anti-pattern classes (review tier). Each id is stable so the
+// attestation/review UX can key on it.
+export const CONTENT_ANTI_PATTERNS = Object.freeze([
+  {
+    id: "invented_counts",
+    antiPattern: 1,
+    rule: "Counts/ratings/percent-recommend claims require a real, brief-sourced basis.",
+    // Count branch requires a proof-scaled number (comma groups, 4+ digits, or
+    // a trailing +) so ordinary commerce quantities ("Choose 3 pairs and
+    // save") never enter the review queue; "pairs"/"sold" dropped as nouns
+    // for the same reason. Small invented counts are a knowingly accepted gap.
+    regex: /\b(?:\d{1,3}(?:,\d{3})+|\d{4,}|\d+\+)\s+(?:reviews?|ratings?|customers?|users?|famil(?:y|ies)|wearers?|people)\b|\b(?:4\.[5-9]|5\.0)\s*(?:\/\s*5|stars?)|\b(?:9[0-9]|100)%\b[^<]{0,60}\b(?:recommend|reported|said|would)\b/i,
+  },
+  {
+    id: "verified_buyer_chrome",
+    antiPattern: 2,
+    rule: "'Verified' labels must resolve to a real approved review source.",
+    regex: /Verified\s+(?:Buyer|Customer|Purchase)|What\s+(?:Our\s+)?Customers\s+(?:Think|Say)|Real\s+(?:People|Customers)[^<]{0,20}Real\s+(?:Results|Relief)|5[- ]Star\s+Review/i,
+  },
+  {
+    id: "byline_persona",
+    antiPattern: 3,
+    rule: "Advertorial identities must be real, brief-supplied, and authorized.",
+    regex: /Mom\s+of\s+Two|Consumer\s+Report|Review\s+Team|Wellness\s+Educator|Licensed\s+(?:Physiotherapist|Professional)/i,
+  },
+  {
+    id: "borrowed_authority",
+    antiPattern: 4,
+    rule: "Expert/clinician/institution references require name, credential, permission, and source.",
+    regex: /\bDr\.\s+[A-Z]|\bM\.?D\.?\b|doctor[- ]recommended|clinically\s+(?:recognized|recommended)|expert\s+(?:says|recommends)/i,
+  },
+  {
+    id: "press_marquee",
+    antiPattern: 8,
+    rule: "Press mentions require a brief-supplied working URL for the exact merchant and product.",
+    regex: /As\s+Seen\s+(?:On|In)|Featured\s+(?:On|In)/i,
+  },
+  {
+    id: "science_theater",
+    antiPattern: 9,
+    rule: "Study/clinical/certification claims require citation metadata and approved wording.",
+    regex: /peer[- ]reviewed|science[- ]backed|backed\s+by\s+science|stud(?:y|ies)\s+(?:show|prove|confirm)|researchers\s+found|clinically\s+(?:proven|shown|tested)|NASA[- ]developed/i,
+  },
+  {
+    id: "scarcity_theater",
+    antiPattern: 10,
+    rule: "Urgency renders only from a real, approved promotion window or live inventory source.",
+    regex: /ENDS\s+AT\s+MIDNIGHT|Offer\s+Expires|Deal\s+Ending|Only\s+\d+\s+(?:Units\s+)?Left|Stock\s+(?:Levels?\s+)?Low|\d+%\s+Sold|Sell[- ]?Out\s+Risk|supplies\s+are\s+limited/i,
+  },
+  {
+    id: "fake_comparison",
+    antiPattern: 11,
+    rule: "Tested-N/showdown framing requires a brief-supplied comparison matrix and test record.",
+    regex: /(?:we\s+)?tested\s+\d+\s+(?:contenders|products|devices|gloves|combinations|brands)|only\s+one\s+(?:survived|worked|stood)|Competitor\s+[12]\b/i,
+  },
+]);
+
+const ENTITIES = new Map([
+  ["&amp;", "&"], ["&lt;", "<"], ["&gt;", ">"], ["&quot;", '"'],
+  ["&#39;", "'"], ["&apos;", "'"], ["&nbsp;", " "], ["&#8217;", "’"], ["&#8212;", "—"],
+]);
+
+function decodeEntities(value) {
+  return String(value)
+    .replace(/&#(\d+);/g, (_, n) => String.fromCodePoint(Number(n)))
+    .replace(/&#x([0-9a-f]+);/gi, (_, n) => String.fromCodePoint(parseInt(n, 16)))
+    .replace(/&[a-z]+;/gi, (m) => ENTITIES.get(m.toLowerCase()) ?? m);
+}
+
+// Markup view: comments and script/style BODIES removed, tags and attributes
+// kept. The scan surface for hard checks — a `<!-- NEEDS MERCHANT INPUT -->`
+// note or a `querySelector('[data-countdown-hrs]')` reference must not block,
+// but a marker in an alt attribute is shipped content and must.
+//
+// `keepLines`: every removed span leaves its newlines behind, so a match index
+// in the view still maps to the source line number (the doctor reports
+// file:line). The default view collapses whitespace and is index-free.
+export function markupView(html, { keepLines = false } = {}) {
+  const newlines = (span) => span.replace(/[^\n]/g, "");
+  return String(html)
+    .replace(/<!--[\s\S]*?-->/g, keepLines ? (m) => ` ${newlines(m)} ` : " ")
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, keepLines ? (m) => `<script>${newlines(m)}</script>` : "<script></script>")
+    .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, keepLines ? (m) => `<style>${newlines(m)}</style>` : "<style></style>");
+}
+
+// Visible-text view: markup view with tags stripped and entities decoded —
+// what a shopper (or screen reader, via appended alt text) actually reads.
+// Attribute values (a `placeholder="…"` input hint, a data-* hook) are not
+// visible text and never reach this view, which is what lets a static scan
+// agree with a browser's body.innerText.
+//
+// `keepLines` keeps source newlines (see markupView) and inlines each alt text
+// where its tag stood instead of appending it, so every index maps to a line.
+export function visibleText(html, { keepLines = false } = {}) {
+  if (keepLines) {
+    const text = markupView(html, { keepLines: true }).replace(/<[^>]*>/g, (tag) => {
+      const alt = /\balt="([^"]*)"/i.exec(tag);
+      const newlines = tag.replace(/[^\n]/g, "");
+      return alt ? ` ${alt[1].replace(/\n/g, " ")} ${newlines}` : ` ${newlines}`;
+    });
+    return decodeEntities(text).replace(/[^\S\n]+/g, " ");
+  }
+  const markup = markupView(html);
+  const altText = [...markup.matchAll(/\balt="([^"]*)"/gi)].map((m) => m[1]).join(" ");
+  return decodeEntities(`${markup.replace(/<[^>]*>/g, " ")} ${altText}`).replace(/\s+/g, " ");
+}
+
+function excerptAt(html, index, span = 80) {
+  const start = Math.max(0, index - 20);
+  return html.slice(start, start + span).replace(/\s+/g, " ").trim();
+}
+
+// Pure scan of one rendered HTML document. Returns { hard: [], review: [] };
+// each finding: { id, tier, rule?, excerpt }. Hard checks run on the markup
+// view (attributes count, comments/scripts do not); review checks run on the
+// visible-text view for precision, except exact-string demo terms and bracket
+// stubs which run on markup so attribute residue is still caught.
+export function scanRenderedHtml(html, { urgencyVerified = false } = {}) {
+  const markup = markupView(typeof html === "string" ? html : "");
+  const text = visibleText(typeof html === "string" ? html : "");
+  const hard = [];
+  const review = [];
+
+  const marker = NEEDS_INPUT_MARKER.exec(markup);
+  if (marker) {
+    hard.push({ id: "needs_merchant_input_marker", tier: "hard", excerpt: excerptAt(markup, marker.index) });
+  }
+
+  const countdown = COUNTDOWN_CHROME.exec(markup);
+  if (countdown && !urgencyVerified) {
+    hard.push({
+      id: "unverified_urgency_countdown",
+      tier: "hard",
+      rule: "Countdown chrome rendered without verified offer urgency (offer.urgency.verified).",
+      excerpt: excerptAt(markup, countdown.index),
+    });
+  }
+
+  const bracket = BRACKET_STUB.exec(markup.replace(/<[^>]*>/g, " "));
+  if (bracket) {
+    review.push({ id: "bracket_placeholder_stub", tier: "review", excerpt: bracket[0] });
+  }
+
+  for (const term of DEMO_RESIDUE_TERMS) {
+    const index = markup.indexOf(term);
+    if (index !== -1) {
+      review.push({ id: "demo_residue_term", tier: "review", term, excerpt: excerptAt(markup, index) });
+    }
+  }
+
+  for (const pattern of CONTENT_ANTI_PATTERNS) {
+    if (pattern.id === "scarcity_theater" && urgencyVerified) continue;
+    const match = pattern.regex.exec(text);
+    if (match) {
+      review.push({
+        id: pattern.id,
+        tier: "review",
+        antiPattern: pattern.antiPattern,
+        rule: pattern.rule,
+        excerpt: excerptAt(text, match.index),
+      });
+    }
+  }
+  return { hard, review };
+}
+
+// Walk a built output dir for rendered pages (same skip rules as the
+// placeholder-residue walker: page HTML only, never _includes/_layouts).
+export function collectRenderedHtmlFiles(rootDir) {
+  const files = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir)) {
+      if (entry === "_includes" || entry === "_layouts" || entry.startsWith(".")) continue;
+      const full = join(dir, entry);
+      const stat = statSync(full);
+      if (stat.isDirectory()) walk(full);
+      else if (entry.endsWith(".html")) files.push(full);
+    }
+  };
+  if (existsSync(rootDir) && statSync(rootDir).isDirectory()) walk(rootDir);
+  return files;
+}
+
+export function scanBuiltOutputContentResidue(outputDir, { urgencyVerified = false } = {}) {
+  const findings = [];
+  for (const file of collectRenderedHtmlFiles(outputDir)) {
+    const { hard, review } = scanRenderedHtml(readFileSync(file, "utf8"), { urgencyVerified });
+    for (const finding of [...hard, ...review]) {
+      findings.push({ ...finding, file: relative(outputDir, file) });
+    }
+  }
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// Proof-attestation gate over the copy-gen brief payload's proof_assets.
+//
+// The brief payload (layer-2 intake contract) is written by the assembly
+// write path at .campaign-runtime/input/brief-payload.json. Each proof asset:
+// { id, modality, content, source, verified, attestable, attestation_status }.
+// Usable = verified:true OR attestation_status:"accepted". A non-usable asset
+// only blocks when its content actually appears in the built output —
+// producers are expected to exclude it, and the corpus brief deliberately
+// seeds non-usable candidates to test exactly that.
+export const BRIEF_PAYLOAD_REL_PATH = ".campaign-runtime/input/brief-payload.json";
+
+export function loadBriefPayload(targetRepo) {
+  if (!targetRepo) return null;
+  const path = join(targetRepo, BRIEF_PAYLOAD_REL_PATH);
+  if (!existsSync(path)) return null;
+  try {
+    return { path, payload: JSON.parse(readFileSync(path, "utf8")) };
+  } catch (error) {
+    return { path, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+export function briefUrgencyVerified(payload) {
+  return payload?.offer?.urgency?.verified === true;
+}
+
+function normalizeForMatch(value) {
+  return String(value || "").toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+// Pure: attestation findings for one set of proof assets against the
+// rendered output. Pass the RAW built HTML (or a concatenation of pages);
+// matching happens against the decoded visible-text view so entity encoding
+// (`&amp;`) and inline tags (`<strong>` inside a claim) cannot hide shipped
+// proof. Returns findings: { id, assetId, modality, state, shipped } where
+// state is "verified" | "accepted" | "pending" | "non_attestable".
+export function evaluateProofAssets(proofAssets, renderedHtml) {
+  const findings = [];
+  const haystack = normalizeForMatch(visibleText(renderedHtml || ""));
+  for (const asset of Array.isArray(proofAssets) ? proofAssets : []) {
+    const verified = asset?.verified === true;
+    const accepted = asset?.attestation_status === "accepted";
+    const attestable = asset?.attestable === true;
+    const state = verified ? "verified" : accepted ? "accepted" : attestable ? "pending" : "non_attestable";
+    // Match on the whole normalized content, falling back to a distinctive
+    // 60-char prefix for long assets. Fail-closed direction: a false
+    // "shipped" costs a review, a false "absent" ships unapproved proof.
+    // Short claims ("4.9/5", "89%") still count, but match on token
+    // boundaries so "4.9" cannot fire inside "$14.99" — a bare substring
+    // scan over the whole visible-text haystack would flag noise.
+    const normalized = normalizeForMatch(asset?.content);
+    const needle = normalized.slice(0, 60);
+    let shipped = false;
+    if (needle.length >= 8) {
+      shipped = haystack.includes(needle);
+    } else if (needle.length >= 3) {
+      const escaped = needle.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      shipped = new RegExp(`(?<![\\w.$])${escaped}(?![\\w.%])`).test(haystack);
+    }
+    findings.push({ assetId: asset?.id ?? null, modality: asset?.modality ?? null, state, shipped });
+  }
+  return findings;
+}
+
+export function attestationBlockers(findings) {
+  return {
+    shippedNonAttestable: findings.filter((f) => f.state === "non_attestable" && f.shipped),
+    shippedPending: findings.filter((f) => f.state === "pending" && f.shipped),
+  };
+}