@geraldmaron/construct 1.1.0 → 1.2.0

package/lib/beads/drift.mjs

@@ -37,6 +37,10 @@ function daysAgo(value) {
   return (Date.now() - ts) / (24 * 60 * 60 * 1000);
 }
 
+function beadUpdatedAt(bead) {
+  return bead?.updated || bead?.updatedAt || bead?.updated_at || bead?.created || bead?.createdAt || bead?.created_at || null;
+}
+
 function listBeadsJson({ status, runner = spawnSync } = {}) {
   const args = ['list', '--json'];
   if (status) args.push(`--status=${status}`);
@@ -78,6 +82,20 @@ function titleAppearsInSubject(beadTitle, commitSubject) {
   return hits >= 3;
 }
 
+/**
+ * Oracle auto-raised meta beads must not feed back into hygiene drift counts.
+ */
+export function isOracleMetaBead(bead) {
+  const title = String(bead?.title ?? '');
+  const labels = Array.isArray(bead?.labels) ? bead.labels : [];
+  return title.startsWith('[oracle/') || labels.includes('oracle');
+}
+
+function filterOracleMeta(beads, excludeOracleMeta) {
+  if (!excludeOracleMeta) return beads;
+  return beads.filter((b) => !isOracleMetaBead(b));
+}
+
 /**
  * Run the three drift checks against the live tracker + git state.
  * Pure-ish — accepts a runner injection for tests.
@@ -86,14 +104,17 @@ export function detectBeadsDrift({
   staleOpenDays = DEFAULT_STALE_OPEN_DAYS,
   stuckInProgressDays = DEFAULT_STUCK_IN_PROGRESS_DAYS,
   mergeLookback = DEFAULT_MERGE_LOOKBACK,
+  excludeOracleMeta = true,
   runner = spawnSync,
 } = {}) {
-  const open = listBeadsJson({ status: 'open', runner });
-  const inProgress = listBeadsJson({ status: 'in_progress', runner });
+  const openRaw = listBeadsJson({ status: 'open', runner });
+  const inProgressRaw = listBeadsJson({ status: 'in_progress', runner });
+  const open = filterOracleMeta(openRaw, excludeOracleMeta);
+  const inProgress = filterOracleMeta(inProgressRaw, excludeOracleMeta);
   const commits = recentCommitSubjects(mergeLookback, { runner });
 
-  const staleOpen = open.filter((b) => daysAgo(b.updated || b.updatedAt) > staleOpenDays);
-  const stuckInProgress = inProgress.filter((b) => daysAgo(b.updated || b.updatedAt) > stuckInProgressDays);
+  const staleOpen = open.filter((b) => daysAgo(beadUpdatedAt(b)) > staleOpenDays);
+  const stuckInProgress = inProgress.filter((b) => daysAgo(beadUpdatedAt(b)) > stuckInProgressDays);
 
   const mergeDrift = [];
   for (const bead of open) {
@@ -106,8 +127,8 @@ export function detectBeadsDrift({
   }
 
   return {
-    staleOpen: staleOpen.map((b) => ({ id: b.id, title: b.title, ageDays: Math.round(daysAgo(b.updated || b.updatedAt)) })),
-    stuckInProgress: stuckInProgress.map((b) => ({ id: b.id, title: b.title, ageDays: Math.round(daysAgo(b.updated || b.updatedAt)) })),
+    staleOpen: staleOpen.map((b) => ({ id: b.id, title: b.title, ageDays: Math.round(daysAgo(beadUpdatedAt(b))) })),
+    stuckInProgress: stuckInProgress.map((b) => ({ id: b.id, title: b.title, ageDays: Math.round(daysAgo(beadUpdatedAt(b))) })),
     mergeDrift,
     thresholds: { staleOpenDays, stuckInProgressDays, mergeLookback },
     counts: {

package/lib/beads-client.mjs

@@ -1,15 +1,9 @@
 /**
  * lib/beads-client.mjs — Wrapper for bd commands with lock‑management and queueing.
  *
- * VERSION 2.0: Now uses optimistic locking by default for better concurrency.
- * All external bd calls should go through `runBd()` to ensure serialized access
- * to the embedded Dolt database.
- * 
- * Changes:
- * - Reads are now lock-free (concurrent safe)
- * - Writes use optimistic locking with automatic retry
- * - Legacy file-based lock is fallback only
- * - Better error messages and conflict resolution
+ * VERSION 2.0: optimistic locking by default; the exclusive file-lock fallback
+ * was retired after zero telemetry firings (construct-nhn5). Writes retry via
+ * Dolt versioning; reads are lock-free.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -18,14 +12,10 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import {
-  acquireLock,
-  releaseLock,
   getLockStatus,
   cleanupStaleLock,
-  enqueueRequest,
-  removeFromQueue,
-  readQueue,
   cleanupStaleQueue,
+  readQueue,
 } from './beads-lock.mjs';
 
 // Anchored bead-ID format. IDs reaching the bd shell boundary must match this;
@@ -67,7 +57,7 @@ const DEFAULT_OPTIONS = {
   queuePollMs: 100,       // How often to check for lock release when queued
   maxQueueWaitSeconds: 300, // Max total time allowed in queue
   useOptimisticLocking: true, // NEW: Use optimistic locking by default
-  fallbackToLegacy: true, // NEW: Fall back to legacy locking on failure
+  fallbackToLegacy: false,
   maxRetries: 5,          // NEW: Max retries for optimistic locking
 };
 
@@ -237,122 +227,50 @@ export async function runBd(args, options = {}) {
     
     if (!opts.silent) {
       console.error(`[beads] ⚠ Optimistic locking failed: ${result.error}`);
-      console.error(`[beads] ↘ Falling back to legacy lock...`);
     }
-  }
-  
-  // ==========================================================================
-  // PATH 3: Legacy file-based locking (fallback, most conservative)
-  // ==========================================================================
-  return runWithLegacyLock(args, opts, cwd, commandDesc);
-}
-
-/**
- * Legacy locking implementation (original behavior).
- * Used as fallback when optimistic locking fails.
- */
-async function runWithLegacyLock(args, opts, cwd, commandDesc) {
-  // Telemetry: every legacy-fallback firing is recorded so the lock+queue removal
-  // decision rests on observed data — if this never fires over a representative
-  // window, the whole exclusive-lock path is removable; if it fires, the entries
-  // name the bd errors that actually need handling (bead construct-nhn5).
-  try {
-    const { logBeadsFallback } = await import('./telemetry/beads-fallback.mjs');
-    logBeadsFallback({ command: commandDesc || args[0] || 'unknown' });
-  } catch { /* telemetry is best-effort */ }
-
-  // Clean up any stale locks before trying
-  cleanupStaleLock({ cwd });
-  cleanupStaleQueue({ cwd });
-
-  // Try to acquire the lock
-  const startWait = Date.now();
-  const lock = await acquireLock({
-    actor: opts.actor,
-    command: commandDesc,
-    timeoutSeconds: opts.timeoutSeconds,
-    cwd,
-  });
-
-  if (!lock) {
-    // Failed to get lock; add to queue if allowed
-    const maxQueueWaitMs = opts.maxQueueWaitSeconds * 1000;
-    if (Date.now() - startWait > maxQueueWaitMs) {
-      return {
-        success: false,
-        error: `Timeout waiting for lock after ${opts.timeoutSeconds}s`,
-        queued: false,
-        method: 'legacy-lock',
-      };
-    }
-
-    const queueEntry = enqueueRequest({
-      actor: opts.actor,
-      command: commandDesc,
-      args,
-      cwd,
-    });
-
-    if (!opts.silent) {
-      console.error(`[beads] ↘ Added to queue (position ${readQueue({ cwd }).length})`);
-    }
-
-    // Wait in queue, polling periodically
-    while (Date.now() - startWait < opts.maxQueueWaitSeconds * 1000) {
-      await new Promise((resolve) => setTimeout(resolve, opts.queuePollMs));
-
-      cleanupStaleLock({ cwd });
-      const status = getLockStatus({ cwd });
-      if (!status.locked) {
-        // Lock free, remove from queue and try again
-        removeFromQueue(queueEntry.timestamp || queueEntry.pid, { cwd });
-        return await runBd(args, { ...opts, silent: true });
-      }
-    }
-
-    // Queue timeout
-    removeFromQueue(queueEntry.timestamp || queueEntry.pid, { cwd });
     return {
       success: false,
-      error: `Timeout in queue after ${opts.maxQueueWaitSeconds}s`,
-      queued: true,
-      waitTimeMs: Date.now() - startWait,
-      method: 'legacy-lock',
+      error: result.error,
+      attempts: result.attempts,
+      method: 'optimistic-locking',
     };
   }
 
-  const execStart = Date.now();
-  let result;
-  try {
-    result = spawnSync('bd', args, {
+  // ==========================================================================
+  // PATH 3: Legacy exclusive lock (retired — bead construct-nhn5 stage 2)
+  // ==========================================================================
+  if (!isRead && !shouldUseOptimisticLocking()) {
+    const startTime = Date.now();
+    const result = spawnSync('bd', args, {
       cwd,
       encoding: 'utf8',
       env: { ...process.env, BEADS_ACTOR: opts.actor },
-      killSignal: 'SIGTERM',
       timeout: Math.max(1, Math.round(opts.commandTimeoutSeconds * 1000)),
     });
-  } finally {
-    releaseLock({ cwd });
-  }
-
-  const totalTime = Date.now() - startWait;
-  const execTime = Date.now() - execStart;
-
-  if (!opts.silent) {
-    console.error(`[beads] ✓ Executed in ${execTime}ms (legacy lock, total: ${totalTime}ms)`);
+    const execTime = Date.now() - startTime;
+    if (result.error?.code === 'ETIMEDOUT') {
+      return {
+        success: false,
+        error: `bd ${commandDesc} timed out after ${opts.commandTimeoutSeconds}s`,
+        exitCode: null,
+        execTimeMs: execTime,
+        method: 'direct-write',
+      };
+    }
+    return {
+      success: result.status === 0 && !result.error,
+      output: result.stdout,
+      error: result.stderr || result.error?.message,
+      exitCode: result.status,
+      execTimeMs: execTime,
+      method: 'direct-write',
+    };
   }
 
   return {
-    success: result.status === 0 && !result.error,
-    output: result.stdout,
-    error: result.error?.code === 'ETIMEDOUT'
-      ? `bd ${commandDesc} timed out after ${opts.commandTimeoutSeconds}s`
-      : (result.stderr || result.error?.message),
-    exitCode: result.status,
-    waitTimeMs: execStart - startWait,
-    execTimeMs: execTime,
-    totalTimeMs: totalTime,
-    method: 'legacy-lock',
+    success: false,
+    error: 'Unexpected beads routing state',
+    method: 'unknown',
   };
 }
 
@@ -405,9 +323,8 @@ export async function claimIssue(id, options = {}) {
   if (result.success) {
     return { success: true, output: JSON.stringify(result.result) };
   }
-  
-  // Fall back to legacy
-  return runBd(['update', id, '--claim'], { ...options, useOptimisticLocking: false });
+
+  return runBd(['update', id, '--claim'], { ...options, useOptimisticLocking: true });
 }
 
 /**
@@ -498,7 +415,18 @@ export async function getHumanStatus(cwd = process.cwd()) {
   
   // Optimistic locking status
   out += 'Locking Strategy:\n';
-  out += `  Mode: ${shouldUseOptimisticLocking() ? 'Optimistic (concurrent reads + versioned writes)' : 'Legacy (exclusive locks)'}\n`;
+  out += `  Mode: ${shouldUseOptimisticLocking() ? 'Optimistic (concurrent reads + versioned writes)' : 'Direct writes (optimistic disabled via CONSTRUCT_BEADS_LEGACY_LOCK=1)'}\n`;
+  out += '  Exclusive file-lock fallback: retired (construct-nhn5)\n';
+
+  try {
+    const { readBeadsFallbacks } = await import('./telemetry/beads-fallback.mjs');
+    const history = readBeadsFallbacks();
+    if (history.length > 0) {
+      out += `  Historical fallback log entries: ${history.length} (~/.cx/beads-fallback.jsonl)\n`;
+    }
+  } catch {
+    /* optional archaeology */
+  }
   
   // Try to get stats if available
   try {

package/lib/beads-optimistic.mjs

@@ -280,7 +280,7 @@ export async function runBeadsOperation(operation, options = {}) {
     type = 'read', // 'read' | 'write' | 'claim' | 'update'
     beadId,
     execute,
-    fallbackToLegacy = true,
+    fallbackToLegacy = false,
     cwd = process.cwd(),
   } = options;
   
@@ -302,16 +302,9 @@ export async function runBeadsOperation(operation, options = {}) {
     if (result.success || !fallbackToLegacy) {
       return result;
     }
-    
-    // Fall back to legacy locking on persistent failure
-    console.error(`[beads] Optimistic locking failed, falling back to legacy lock: ${result.error}`);
-  }
-  
-  // Legacy path: use the file-based lock
-  if (fallbackToLegacy) {
-    const { runBd } = await import('./beads-client.mjs');
-    return runBd([operation], { cwd });
+
+    return { success: false, error: result.error || 'Optimistic write failed' };
   }
-  
-  return { success: false, error: 'Operation failed and fallback disabled' };
+
+  return { success: false, error: 'Operation failed' };
 }

package/lib/brand-fonts.mjs

@@ -0,0 +1,93 @@
+/**
+ * lib/brand-fonts.mjs — bundled Space Grotesk / JetBrains Mono paths and PPTX font embedding.
+ *
+ * PDF/Typst reads TTF from templates/distribution/fonts/. HTML/deck templates load
+ * the same families from Google Fonts. PPTX uses pptx-embed-fonts when available so
+ * PowerPoint renders the bundled faces without a local install. Space Grotesk ships
+ * as a single weight-axis variable file; JetBrains Mono as discrete cuts.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { BRAND_TOKENS } from './brand-tokens.mjs';
+
+const require = createRequire(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+export const BRAND_SANS_FAMILY = BRAND_TOKENS.typography.fontSans;
+export const BRAND_MONO_FAMILY = BRAND_TOKENS.typography.fontMono;
+
+export const BUNDLED_SANS_FILES = Object.freeze([
+  'SpaceGrotesk-Variable.ttf',
+]);
+
+export const BUNDLED_MONO_FILES = Object.freeze([
+  'JetBrainsMono-Regular.ttf',
+  'JetBrainsMono-Medium.ttf',
+  'JetBrainsMono-SemiBold.ttf',
+]);
+
+export function distributionFontsDir(repoRoot = REPO_ROOT) {
+  return path.join(repoRoot, 'templates', 'distribution', 'fonts');
+}
+
+export function bundledSansFontPaths(repoRoot = REPO_ROOT) {
+  const dir = distributionFontsDir(repoRoot);
+  return BUNDLED_SANS_FILES.map((file) => path.join(dir, file)).filter((p) => fs.existsSync(p));
+}
+
+export function bundledMonoFontPaths(repoRoot = REPO_ROOT) {
+  const dir = distributionFontsDir(repoRoot);
+  return BUNDLED_MONO_FILES.map((file) => path.join(dir, file)).filter((p) => fs.existsSync(p));
+}
+
+export function createPptxGenerator() {
+  const PptxGenJS = require('pptxgenjs');
+  try {
+    const { withPPTXEmbedFonts } = require('pptx-embed-fonts/pptxgenjs');
+    return { PptxClass: withPPTXEmbedFonts(PptxGenJS), embedFonts: true };
+  } catch {
+    return { PptxClass: PptxGenJS, embedFonts: false };
+  }
+}
+
+async function embedFamilyInPptx(pptx, family, paths) {
+  let count = 0;
+  for (const fontPath of paths) {
+    const buf = fs.readFileSync(fontPath);
+    await pptx.addFont({
+      fontFace: family,
+      fontFile: buf,
+      fontType: 'ttf',
+    });
+    count += 1;
+  }
+  return count;
+}
+
+export async function embedBundledSansInPptx(pptx, repoRoot = REPO_ROOT) {
+  if (typeof pptx?.addFont !== 'function') return { embedded: false, count: 0 };
+  const count = await embedFamilyInPptx(pptx, BRAND_SANS_FAMILY, bundledSansFontPaths(repoRoot));
+  return { embedded: count > 0, count };
+}
+
+export async function embedBundledMonoInPptx(pptx, repoRoot = REPO_ROOT) {
+  if (typeof pptx?.addFont !== 'function') return { embedded: false, count: 0 };
+  const count = await embedFamilyInPptx(pptx, BRAND_MONO_FAMILY, bundledMonoFontPaths(repoRoot));
+  return { embedded: count > 0, count };
+}
+
+export function googleFontsSansHref() {
+  return 'https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&family=Space+Grotesk:wght@400;500;600;700&display=swap';
+}
+
+export function pdfUsesBundledBrandSans(pdfPath) {
+  try {
+    const text = fs.readFileSync(pdfPath).toString('latin1');
+    return /SpaceGrotesk|Space Grotesk|JetBrainsMono|JetBrains Mono/.test(text);
+  } catch {
+    return false;
+  }
+}

package/lib/brand-prose.mjs

@@ -0,0 +1,214 @@
+/**
+ * lib/brand-prose.mjs — marketing voice, retired typography, and Construct naming lint.
+ *
+ * Shared by scripts/audit/03d-brand.mjs, lib/hooks/brand-prose-lint.mjs, and
+ * `construct lint:brand`. Scans markdown prose only (skips fenced code and inline code).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const MARKETING_VOICE_RE =
+  /\b(robust|enterprise-grade|best-in-class|world-class|cutting-edge|powerful|battle-tested|seamless)\b/i;
+
+export const RETIRED_FONT_RE =
+  /Plus\s+Jakarta|PlusJakarta|Geist(?:Mono)?|IBM\s+Plex|Libertinus|font-family:\s*["']?Inter["']?/i;
+
+const CLI_SUBCOMMANDS =
+  'doctor|init|sync|dev|stop|status|intake|chat|install|drop|search|prune|upgrade|config|list|graph|beads|export|publish|artifact|demo|oracle|ci|acp|profile|models|uninstall|reconcile|embed|ingest|classify|workflow|capability';
+
+const PRODUCT_NOUN_PHRASES =
+  /\bConstruct (?:install|MCP server|MCP tools?|workflow|chat|package|repo|surfaces?|integration|orchestrator|daemon|specialists?|persona|brand|tooling|standards|config|adapters?|platform|version|release|hooks?|memory|loop|Dashboard|Chat|capability)\b/i;
+
+const UNBACKTICKED_CLI_RE = new RegExp(
+  `(?<![\`~/])construct\\s+(${CLI_SUBCOMMANDS})(?:\\s+[\\w:-]+)*\\b`,
+  'i',
+);
+
+const MISCAPITALIZED_CLI_RE = new RegExp(
+  `\\bConstruct\\s+(${CLI_SUBCOMMANDS})(?:\\s+[\\w:-]+)*\\b`,
+);
+
+const MARKETING_SCAN_ROOTS = ['docs', 'skills', 'specialists', 'personas', 'templates', 'rules'];
+const MARKETING_SCAN_EXTS = ['.md', '.mdx'];
+const FONT_SCAN_EXTS = ['.mjs', '.js', '.md', '.mdx', '.json', '.html', '.css', '.tsx', '.ts', '.jsx', '.typ'];
+
+const EXCLUDE_PATH =
+  /(node_modules|\.git|audit-artifacts|scripts\/audit|CHANGELOG\.md|fonts\/legacy\/|\.next\/|\/out\/|tests\/e2e\/reports\/|package-lock\.json)/;
+
+const DOC_EXEMPT =
+  /(?:^|\/)(docs\/STYLE\.md|docs\/reference\/branding\.md|templates\/distribution\/fonts\/README\.md)$/;
+
+const HOOK_SCOPED =
+  /^(docs\/|skills\/|specialists\/|personas\/|templates\/|rules\/|apps\/(dashboard|docs|chat)\/)/;
+
+export function isBrandHookPath(relPath) {
+  if (!relPath || EXCLUDE_PATH.test(relPath) || DOC_EXEMPT.test(relPath)) return false;
+  return HOOK_SCOPED.test(relPath.replace(/\\/g, '/'));
+}
+
+export function splitProseLines(content) {
+  const prose = [];
+  let inFence = false;
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (trimmed.startsWith('```')) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    prose.push({ line: i + 1, text: line });
+  }
+  return prose;
+}
+
+function stripInlineCode(text) {
+  return text.replace(/`[^`]*`/g, '');
+}
+
+function isMarketingAllowlisted(relPath, lineText) {
+  if (/skills\/roles\//.test(relPath) && /["']robust["']|POUR|Symptom/i.test(lineText)) return true;
+  if (/<!--/.test(lineText)) return true;
+  if (/\b(WCAG|Perceivable, Operable)/i.test(lineText) && /\bRobust\b/.test(lineText)) return true;
+  return false;
+}
+
+function isNamingAllowlisted(relPath, lineText) {
+  const trimmed = lineText.trim();
+  if (/^#+\s+construct\s+/i.test(trimmed)) return true;
+  if (/^title:\s/i.test(trimmed)) return true;
+  if (/^description:\s/i.test(trimmed)) return true;
+  if (/node\s+bin\/construct/.test(lineText)) return true;
+  if (/CONSTRUCT_[A-Z_]+=/.test(lineText) && /construct\s+sync/.test(lineText)) return true;
+  if ((lineText.match(/\|/g) || []).length >= 2) return true;
+  if (/cli:construct/.test(lineText)) return true;
+  if (/mcp:.*construct/.test(lineText)) return true;
+  if (/\{\s*label:\s*['`]construct/.test(lineText)) return true;
+  if (PRODUCT_NOUN_PHRASES.test(lineText)) return true;
+  if (/verified_by:\s*construct\b/.test(lineText)) return true;
+  if (/construct_schema_migrations/.test(lineText)) return true;
+  if (/non-Construct/.test(lineText)) return true;
+  return false;
+}
+
+export function lintMarketingVoiceLine(relPath, lineNumber, lineText) {
+  const prose = stripInlineCode(lineText);
+  if (!MARKETING_VOICE_RE.test(prose)) return null;
+  if (isMarketingAllowlisted(relPath, lineText)) return null;
+  const match = prose.match(MARKETING_VOICE_RE);
+  return {
+    kind: 'marketing-voice',
+    line: lineNumber,
+    token: match?.[0] ?? 'marketing',
+    text: lineText.trim().slice(0, 140),
+  };
+}
+
+export function lintRetiredFontLine(relPath, lineNumber, lineText) {
+  if (!RETIRED_FONT_RE.test(lineText)) return null;
+  return {
+    kind: 'retired-font',
+    line: lineNumber,
+    text: lineText.trim().slice(0, 140),
+  };
+}
+
+export function lintConstructNamingLine(relPath, lineNumber, lineText) {
+  if (!/\.mdx?$/.test(relPath)) return null;
+  if (isNamingAllowlisted(relPath, lineText)) return null;
+  const prose = stripInlineCode(lineText);
+  const miscap = prose.match(MISCAPITALIZED_CLI_RE);
+  if (miscap) {
+    return {
+      kind: 'construct-naming',
+      line: lineNumber,
+      text: lineText.trim().slice(0, 140),
+      detail: `Use lowercase CLI form: \`construct ${miscap[1]}\``,
+    };
+  }
+  if (/^\s*\d+\.\s/.test(lineText) || /^\s*-\s/.test(lineText)) {
+    const unback = prose.match(UNBACKTICKED_CLI_RE);
+    if (unback) {
+      return {
+        kind: 'construct-naming',
+        line: lineNumber,
+        text: lineText.trim().slice(0, 140),
+        detail: `Backtick CLI invocations: \`construct ${unback[1]}...\``,
+      };
+    }
+  }
+  return null;
+}
+
+export function lintMarkdownBrand(content, { relPath = '', checks = ['marketing', 'naming', 'font'] } = {}) {
+  const violations = [];
+  for (const { line, text } of splitProseLines(content)) {
+    if (checks.includes('marketing')) {
+      const hit = lintMarketingVoiceLine(relPath, line, text);
+      if (hit) violations.push(hit);
+    }
+    if (checks.includes('naming')) {
+      const hit = lintConstructNamingLine(relPath, line, text);
+      if (hit) violations.push(hit);
+    }
+    if (checks.includes('font')) {
+      const hit = lintRetiredFontLine(relPath, line, text);
+      if (hit) violations.push(hit);
+    }
+  }
+  return violations;
+}
+
+function walk(dir, exts, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, e.name);
+    if (EXCLUDE_PATH.test(full)) continue;
+    if (e.isDirectory()) walk(full, exts, out);
+    else if (exts.some((x) => e.name.endsWith(x))) out.push(full);
+  }
+  return out;
+}
+
+export function scanRepoBrandProse(rootDir, { checks = ['marketing', 'naming', 'font'] } = {}) {
+  const hits = [];
+  for (const base of MARKETING_SCAN_ROOTS) {
+    const abs = path.join(rootDir, base);
+    for (const file of walk(abs, [...MARKETING_SCAN_EXTS, ...(checks.includes('font') ? FONT_SCAN_EXTS : [])])) {
+      const rel = path.relative(rootDir, file).replace(/\\/g, '/');
+      if (DOC_EXEMPT.test(rel)) continue;
+      const ext = path.extname(file);
+      const fileChecks = checks.filter((c) => c !== 'font' || FONT_SCAN_EXTS.includes(ext));
+      const content = fs.readFileSync(file, 'utf8');
+      for (const v of lintMarkdownBrand(content, { relPath: rel, checks: fileChecks })) {
+        hits.push({ file: rel, ...v });
+      }
+    }
+  }
+  return hits;
+}
+
+export function lintFile(absPath, { rootDir = process.cwd() } = {}) {
+  const rel = path.relative(rootDir, absPath).replace(/\\/g, '/');
+  if (!isBrandHookPath(rel)) return { rel, violations: [] };
+  const ext = path.extname(absPath).toLowerCase();
+  if (!['.md', '.mdx', '.html', '.css', '.tsx', '.ts', '.jsx', '.typ'].includes(ext)) {
+    return { rel, violations: [] };
+  }
+  const content = fs.readFileSync(absPath, 'utf8');
+  const checks = ['.md', '.mdx'].includes(ext) ? ['marketing', 'naming', 'font'] : ['font'];
+  return { rel, violations: lintMarkdownBrand(content, { relPath: rel, checks }) };
+}
+
+export function formatBrandViolations(results) {
+  const lines = [];
+  for (const { rel, violations } of results) {
+    for (const v of violations) {
+      const detail = v.detail ? ` — ${v.detail}` : '';
+      lines.push(`${rel}:${v.line} [${v.kind}] ${v.text}${detail}`);
+    }
+  }
+  return lines.join('\n');
+}