@delegance/claude-autopilot 2.4.0 → 5.0.0-alpha.1

package/src/core/schema-alignment/detector.ts

@@ -0,0 +1,59 @@
+// src/core/schema-alignment/detector.ts
+import type { SchemaAlignmentConfig } from './types.ts';
+
+const DEFAULT_PATTERNS: RegExp[] = [
+  /data[/\\]deltas[/\\].+\.sql$/,
+  /supabase[/\\]migrations[/\\].+\.sql$/,
+  /prisma[/\\]migrations[/\\].+\.sql$/,
+  /prisma[/\\]schema\.prisma$/,
+  /db[/\\]migrate[/\\].+\.rb$/,
+  /drizzle[/\\].+\.ts$/,
+  /[/\\]migrations[/\\].+\.py$/,
+];
+
+function globToPattern(glob: string): RegExp {
+  let escaped = glob;
+
+  // Escape regex special chars except * and /
+  escaped = escaped.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+
+  // Replace **/ with placeholder (matches zero or more intermediate directories)
+  escaped = escaped.replace(/\*\*\//g, '___DSTAR_SLASH___');
+
+  // Replace remaining ** with placeholder
+  escaped = escaped.replace(/\*\*/g, '___DSTAR___');
+
+  // Replace / with placeholder BEFORE handling * so we don't mess up character classes
+  escaped = escaped.replace(/\//g, '___SLASH___');
+
+  // Replace single * with placeholder (to preserve it before / restoration)
+  escaped = escaped.replace(/\*/g, '___STAR___');
+
+  // Now restore placeholders in the right order
+  // Restore / as [/\\\\] to match both forward and back slashes
+  // NOTE: In RegExp constructor, \\ becomes \, so [/\\] needs to be [/\\\\]
+  escaped = escaped.replace(/___SLASH___/g, '[/\\\\]');
+
+  // Restore * as [^/]* (matches anything except /)
+  escaped = escaped.replace(/___STAR___/g, '[^/]*');
+
+  // Restore **/ as optional directory segments with trailing separator
+  escaped = escaped.replace(/___DSTAR_SLASH___/g, '(?:.*[/\\\\])?');
+
+  // Restore remaining ** as .* (matches anything including /)
+  escaped = escaped.replace(/___DSTAR___/g, '.*');
+
+  const re = new RegExp(escaped + '$');
+  return re;
+}
+
+export function detect(touchedFiles: string[], config?: SchemaAlignmentConfig): string[] {
+  if (config?.enabled === false) return [];
+
+  const patterns = [...DEFAULT_PATTERNS];
+  for (const glob of config?.migrationGlobs ?? []) {
+    patterns.push(globToPattern(glob));
+  }
+
+  return touchedFiles.filter(f => patterns.some(re => re.test(f)));
+}

package/src/core/schema-alignment/extractor/index.ts

@@ -0,0 +1,24 @@
+// src/core/schema-alignment/extractor/index.ts
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { SchemaEntity } from '../types.ts';
+import { extractFromSql } from './sql.ts';
+import { extractFromPrisma } from './prisma.ts';
+
+export function extract(filePath: string): SchemaEntity[] {
+  let content: string;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return [];
+  }
+
+  const ext = path.extname(filePath).toLowerCase();
+  const base = path.basename(filePath).toLowerCase();
+
+  if (ext === '.sql') return extractFromSql(content);
+  if (base === 'schema.prisma' || ext === '.prisma') return extractFromPrisma(content);
+
+  process.stderr.write(`[schema-alignment] no extractor for ${ext} files — skipping ${path.basename(filePath)}\n`);
+  return [];
+}

package/src/core/schema-alignment/extractor/prisma.ts

@@ -0,0 +1,21 @@
+// src/core/schema-alignment/extractor/prisma.ts
+import type { SchemaEntity } from '../types.ts';
+
+export function extractFromPrisma(content: string): SchemaEntity[] {
+  const entities: SchemaEntity[] = [];
+  // Match model blocks: model Name { ... }
+  const modelRe = /^model\s+(\w+)\s*\{([^}]+)\}/gm;
+  for (const modelMatch of content.matchAll(modelRe)) {
+    const table = modelMatch[1]!;
+    entities.push({ table, operation: 'create_table' });
+    const body = modelMatch[2]!;
+    // Match field lines: fieldName TypeName ...
+    const fieldRe = /^\s+(\w+)\s+\S/gm;
+    for (const fieldMatch of body.matchAll(fieldRe)) {
+      const column = fieldMatch[1]!;
+      if (column.startsWith('@') || column === 'id') continue;
+      entities.push({ table, column, operation: 'add_column' });
+    }
+  }
+  return entities;
+}

package/src/core/schema-alignment/extractor/sql.ts

@@ -0,0 +1,99 @@
+// src/core/schema-alignment/extractor/sql.ts
+import type { SchemaEntity } from '../types.ts';
+
+function unquote(s: string | undefined): string {
+  if (!s) return '';
+  return s.replace(/^["'`]|["'`]$/g, '');
+}
+
+// Identifier: quoted or unquoted word (no schema prefix captured)
+const ID = /(?:"([^"]+)"|`([^`]+)`|(\w+))/;
+const SCHEMA_OPT = /(?:\w+\.)?/;
+
+// Keywords that can follow ADD/DROP but are NOT columns
+const NON_COLUMN_KEYWORDS = new Set([
+  'CONSTRAINT', 'INDEX', 'PRIMARY', 'FOREIGN', 'UNIQUE', 'CHECK',
+  'KEY', 'EXCLUDE', 'REFERENCES',
+]);
+
+export function extractFromSql(content: string): SchemaEntity[] {
+  // Strip comments before processing
+  const normalized = content
+    .replace(/--[^\n]*/g, ' ')
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/\s+/g, ' ');
+
+  const entities: SchemaEntity[] = [];
+
+  // CREATE TABLE [IF NOT EXISTS] [schema.]name
+  const createTableRe = new RegExp(
+    `CREATE\\s+(?:OR\\s+REPLACE\\s+)?TABLE\\s+(?:IF\\s+NOT\\s+EXISTS\\s+)?${SCHEMA_OPT.source}${ID.source}`,
+    'gi',
+  );
+  for (const m of normalized.matchAll(createTableRe)) {
+    const table = unquote(m[1] ?? m[2] ?? m[3]);
+    if (table && table.toUpperCase() !== 'EXISTS') entities.push({ table, operation: 'create_table' });
+  }
+
+  // ALTER TABLE [schema.]name ADD [COLUMN] [IF NOT EXISTS] col
+  const addColRe = new RegExp(
+    `ALTER\\s+TABLE\\s+(?:ONLY\\s+)?${SCHEMA_OPT.source}${ID.source}\\s+ADD\\s+(?:COLUMN\\s+)?(?:IF\\s+NOT\\s+EXISTS\\s+)?${ID.source}`,
+    'gi',
+  );
+  for (const m of normalized.matchAll(addColRe)) {
+    const table = unquote(m[1] ?? m[2] ?? m[3]);
+    const column = unquote(m[4] ?? m[5] ?? m[6]);
+    if (!table || !column) continue;
+    // Skip non-column ADD operations (CONSTRAINT, INDEX, PRIMARY KEY, FOREIGN KEY, UNIQUE, CHECK)
+    if (NON_COLUMN_KEYWORDS.has(column.toUpperCase())) continue;
+    entities.push({ table, column, operation: 'add_column' });
+  }
+
+  // ALTER TABLE [schema.]name DROP [COLUMN] [IF EXISTS] col
+  const dropColRe = new RegExp(
+    `ALTER\\s+TABLE\\s+(?:ONLY\\s+)?${SCHEMA_OPT.source}${ID.source}\\s+DROP\\s+(?:COLUMN\\s+)?(?:IF\\s+EXISTS\\s+)?${ID.source}`,
+    'gi',
+  );
+  for (const m of normalized.matchAll(dropColRe)) {
+    const table = unquote(m[1] ?? m[2] ?? m[3]);
+    const column = unquote(m[4] ?? m[5] ?? m[6]);
+    if (!table || !column) continue;
+    // Skip non-column DROP operations (CONSTRAINT, INDEX, PRIMARY KEY, FOREIGN KEY)
+    if (NON_COLUMN_KEYWORDS.has(column.toUpperCase())) continue;
+    entities.push({ table, column, operation: 'drop_column' });
+  }
+
+  // ALTER TABLE [schema.]name RENAME [COLUMN] old TO new
+  const renameColRe = new RegExp(
+    `ALTER\\s+TABLE\\s+(?:ONLY\\s+)?${SCHEMA_OPT.source}${ID.source}\\s+RENAME\\s+(?:COLUMN\\s+)?${ID.source}\\s+TO\\s+${ID.source}`,
+    'gi',
+  );
+  for (const m of normalized.matchAll(renameColRe)) {
+    const table = unquote(m[1] ?? m[2] ?? m[3]);
+    const oldName = unquote(m[4] ?? m[5] ?? m[6]);
+    const column = unquote(m[7] ?? m[8] ?? m[9]);
+    if (table && column) entities.push({ table, column, operation: 'rename_column', oldName });
+  }
+
+  // CREATE TYPE [schema.]name
+  const createTypeRe = new RegExp(
+    `CREATE\\s+TYPE\\s+${SCHEMA_OPT.source}${ID.source}`,
+    'gi',
+  );
+  for (const m of normalized.matchAll(createTypeRe)) {
+    const table = unquote(m[1] ?? m[2] ?? m[3]);
+    if (table) entities.push({ table, operation: 'create_type' });
+  }
+
+  // ALTER TYPE [schema.]name ADD VALUE ...
+  const alterTypeRe = new RegExp(
+    `ALTER\\s+TYPE\\s+${SCHEMA_OPT.source}${ID.source}\\s+ADD\\s+VALUE`,
+    'gi',
+  );
+  for (const m of normalized.matchAll(alterTypeRe)) {
+    const table = unquote(m[1] ?? m[2] ?? m[3]);
+    if (table) entities.push({ table, operation: 'create_type' });
+  }
+
+  return entities;
+}

package/src/core/schema-alignment/llm-check.ts

@@ -0,0 +1,91 @@
+// src/core/schema-alignment/llm-check.ts
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { ReviewEngine } from '../../adapters/review-engine/types.ts';
+import type { SchemaEntity, LayerScanResult, AlignmentFinding } from './types.ts';
+
+const TOTAL_CHAR_BUDGET = 6000;
+
+function truncateTop(text: string, maxChars: number): string {
+  if (text.length <= maxChars) return text;
+  const dropped = text.length - maxChars;
+  return `<!-- [schema-alignment: truncated ${dropped} chars] -->\n` + text.slice(dropped);
+}
+
+export async function runLlmCheck(
+  migrationFiles: string[],
+  gapResults: LayerScanResult[],
+  engine: ReviewEngine,
+): Promise<AlignmentFinding[]> {
+  let budget = TOTAL_CHAR_BUDGET;
+  const migrationSnippets: string[] = [];
+
+  for (const f of migrationFiles) {
+    if (budget <= 0) break;
+    let content: string;
+    try { content = fs.readFileSync(f, 'utf8'); } catch { continue; }
+    const snippet = truncateTop(content, Math.floor(budget * 0.6));
+    migrationSnippets.push(`### Migration: ${path.basename(f)}\n\`\`\`sql\n${snippet}\n\`\`\``);
+    budget -= snippet.length;
+  }
+
+  const entitySummary = gapResults.map(r => {
+    const isDestructive = r.entity.operation === 'drop_column' || r.entity.operation === 'rename_column';
+    const gaps = isDestructive
+      ? [r.typeLayer, r.apiLayer, r.uiLayer]
+          .map((e, i) => e !== null ? (['type', 'api', 'ui'][i]) : null)
+          .filter(Boolean).join(', ')
+      : [r.typeLayer === null ? 'type' : null, r.apiLayer === null ? 'api' : null, r.uiLayer === null ? 'ui' : null]
+          .filter(Boolean).join(', ');
+    return `- ${r.entity.operation} ${r.entity.table}${r.entity.column ? '.' + r.entity.column : ''}: ${isDestructive ? 'stale ref in' : 'missing in'} [${gaps}]`;
+  }).join('\n');
+
+  const prompt = [
+    'You are reviewing schema-layer alignment for a software project.',
+    '',
+    migrationSnippets.length > 0
+      ? `The following migration files were changed:\n\n${migrationSnippets.join('\n\n')}`
+      : '(no readable migration files)',
+    '',
+    `The structural scan found these potential alignment gaps:\n${entitySummary || '(none)'}`,
+    '',
+    'For each gap, determine if it is a real problem. Return findings as a JSON array:',
+    '[{ "table": "name", "column": "name_or_null", "operation": "add_column", "layer": "type", "file": "path/to/relevant/file.ts (optional)", "message": "explanation", "severity": "warning", "confidence": "high" }]',
+    'Return only valid JSON, no prose.',
+  ].join('\n');
+
+  let rawOutput: string;
+  try {
+    const result = await engine.review({ content: prompt, kind: 'file-batch' });
+    rawOutput = result.rawOutput;
+  } catch {
+    return [];
+  }
+
+  const jsonMatch = rawOutput.match(/\[[\s\S]*\]/);
+  if (!jsonMatch) return [];
+
+  try {
+    const parsed = JSON.parse(jsonMatch[0]) as Array<{
+      table: string; column?: string; operation: string;
+      layer: string; message: string; severity: string; confidence: string;
+      file?: string;
+    }>;
+    return parsed
+      .filter(item => item.table && item.layer && item.message)
+      .map(item => ({
+        entity: {
+          table: item.table,
+          column: item.column,
+          operation: item.operation as SchemaEntity['operation'],
+        },
+        layer: item.layer as AlignmentFinding['layer'],
+        message: item.message,
+        file: item.file,
+        severity: (item.severity === 'error' ? 'error' : 'warning') as AlignmentFinding['severity'],
+        confidence: (['high', 'medium', 'low'].includes(item.confidence) ? item.confidence : 'medium') as AlignmentFinding['confidence'],
+      }));
+  } catch {
+    return [];
+  }
+}

package/src/core/schema-alignment/scanner.ts

@@ -0,0 +1,107 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { SchemaEntity, Evidence, LayerScanResult, SchemaAlignmentConfig } from './types.ts';
+
+const DEFAULT_ROOTS = {
+  types: ['types/', 'src/types/', 'lib/types/'],
+  api: ['app/api/', 'lib/', 'services/', 'src/routes/'],
+  ui: ['app/', 'src/', 'components/'],
+};
+
+function* walkFiles(dir: string): Generator<string> {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (IGNORED_DIRS.has(entry.name)) continue;
+      yield* walkFiles(path.join(dir, entry.name));
+    } else if (entry.isFile()) {
+      const ext = path.extname(entry.name).toLowerCase();
+      if (CODE_EXTS.has(ext)) yield path.join(dir, entry.name);
+    }
+  }
+}
+
+const IGNORED_DIRS = new Set([
+  'node_modules', '.next', 'dist', 'build', 'coverage', '.git',
+  '.turbo', '.cache', '.vercel', 'out', '.nuxt', 'target',
+]);
+
+const CODE_EXTS = new Set([
+  '.ts', '.tsx', '.js', '.jsx', '.mts', '.cts', '.mjs', '.cjs',
+  '.vue', '.svelte', '.astro', '.py', '.rb', '.go', '.rs',
+]);
+
+function resolveRoots(roots: string[], cwd: string): string[] {
+  return roots.map(r => path.isAbsolute(r) ? r : path.join(cwd, r));
+}
+
+function isUnder(filePath: string, dir: string): boolean {
+  const rel = path.relative(dir, filePath);
+  return !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+function searchLayer(
+  roots: string[],
+  pattern: RegExp,
+  cwd: string,
+  excludedDirs: string[] = [],
+): Evidence | null {
+  for (const root of roots) {
+    const dir = path.isAbsolute(root) ? root : path.join(cwd, root);
+    for (const filePath of walkFiles(dir)) {
+      // Skip files that belong to an excluded layer's root (avoids UI root
+      // `app/` reporting API evidence from `app/api/`, etc.)
+      if (excludedDirs.some(excl => isUnder(filePath, excl))) continue;
+      let content: string;
+      try { content = fs.readFileSync(filePath, 'utf8'); } catch { continue; }
+      const lines = content.split('\n');
+      for (let i = 0; i < lines.length; i++) {
+        if (pattern.test(lines[i]!)) {
+          return {
+            file: filePath,
+            line: i + 1,
+            snippet: lines[i]!.trim().slice(0, 120),
+            confidence: 'high',
+          };
+        }
+      }
+    }
+  }
+  return null;
+}
+
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function scanLayers(
+  entities: SchemaEntity[],
+  cwd: string,
+  config?: SchemaAlignmentConfig,
+): LayerScanResult[] {
+  const roots = {
+    types: config?.layerRoots?.types ?? DEFAULT_ROOTS.types,
+    api: config?.layerRoots?.api ?? DEFAULT_ROOTS.api,
+    ui: config?.layerRoots?.ui ?? DEFAULT_ROOTS.ui,
+  };
+  const resolvedTypeRoots = resolveRoots(roots.types, cwd);
+  const resolvedApiRoots = resolveRoots(roots.api, cwd);
+
+  return entities.map(entity => {
+    const isDestructive = entity.operation === 'drop_column' || entity.operation === 'rename_column';
+    const searchName = isDestructive
+      ? (entity.oldName ?? entity.column ?? entity.table)
+      : (entity.column ?? entity.table);
+
+    const pattern = new RegExp(`\\b${escapeRe(searchName)}\\b`);
+
+    return {
+      entity,
+      typeLayer: searchLayer(roots.types, pattern, cwd),
+      // API search excludes type roots (prevents lib/ from picking up lib/types/ matches)
+      apiLayer: searchLayer(roots.api, pattern, cwd, resolvedTypeRoots),
+      // UI search excludes both type and API roots (prevents app/ from picking up app/api/)
+      uiLayer: searchLayer(roots.ui, pattern, cwd, [...resolvedTypeRoots, ...resolvedApiRoots]),
+    };
+  });
+}

package/src/core/schema-alignment/types.ts

@@ -0,0 +1,43 @@
+// src/core/schema-alignment/types.ts
+
+export interface SchemaEntity {
+  table: string;
+  column?: string;
+  operation: 'create_table' | 'add_column' | 'drop_column' | 'rename_column' | 'create_type';
+  oldName?: string; // rename_column only: the previous column name
+}
+
+export interface Evidence {
+  file: string;
+  line: number;
+  snippet: string;
+  confidence: 'high' | 'medium' | 'low';
+}
+
+export interface LayerScanResult {
+  entity: SchemaEntity;
+  typeLayer: Evidence | null;
+  apiLayer: Evidence | null;
+  uiLayer: Evidence | null;
+}
+
+export interface AlignmentFinding {
+  entity: SchemaEntity;
+  layer: 'type' | 'api' | 'ui';
+  message: string;
+  file?: string;
+  severity: 'warning' | 'error';
+  confidence: 'high' | 'medium' | 'low';
+}
+
+export interface SchemaAlignmentConfig {
+  enabled?: boolean;
+  migrationGlobs?: string[];
+  layerRoots?: {
+    types?: string[];
+    api?: string[];
+    ui?: string[];
+  };
+  llmCheck?: boolean;
+  severity?: 'warning' | 'error';
+}

package/src/core/shell.ts

@@ -1,7 +1,7 @@
 // src/core/shell.ts
 
 import { execFileSync } from 'node:child_process';
-import { AutopilotError, type ErrorCode } from './errors.ts';
+import { GuardrailError, type ErrorCode } from './errors.ts';
 
 export interface RunOptions {
   timeout?: number;
@@ -27,7 +27,7 @@ export function runSafe(cmd: string, args: string[], options: RunOptions = {}):
   }
 }
 
-/** Run a command; throw AutopilotError on failure. */
+/** Run a command; throw GuardrailError on failure. */
 export function runThrowing(cmd: string, args: string[], options: RunOptions & { errorCode?: ErrorCode; provider?: string } = {}): string {
   try {
     return execFileSync(cmd, args, {
@@ -39,7 +39,7 @@ export function runThrowing(cmd: string, args: string[], options: RunOptions & {
       env: options.env,
     }).toString();
   } catch (err) {
-    throw new AutopilotError(`Command failed: ${cmd} ${args.join(' ')}`, {
+    throw new GuardrailError(`Command failed: ${cmd} ${args.join(' ')}`, {
       code: options.errorCode ?? 'transient_network',
       provider: options.provider,
       details: { cmd, args, cause: err instanceof Error ? err.message : String(err) },

package/src/core/static-rules/registry.ts

@@ -3,13 +3,22 @@ import type { StaticRuleReference } from '../config/types.ts';
 
 // Built-in cross-stack rules
 const BUILTIN: Record<string, () => Promise<StaticRule>> = {
-  'hardcoded-secrets': () => import('./rules/hardcoded-secrets.ts').then(m => m.hardcodedSecretsRule),
-  'npm-audit':         () => import('./rules/npm-audit.ts').then(m => m.npmAuditRule),
-  'package-lock-sync': () => import('./rules/package-lock-sync.ts').then(m => m.packageLockSyncRule),
-  'console-log':       () => import('./rules/console-log.ts').then(m => m.consoleLogRule),
-  'todo-fixme':        () => import('./rules/todo-fixme.ts').then(m => m.todoFixmeRule),
-  'large-file':        () => import('./rules/large-file.ts').then(m => m.largeFileRule),
-  'missing-tests':     () => import('./rules/missing-tests.ts').then(m => m.missingTestsRule),
+  'hardcoded-secrets':  () => import('./rules/hardcoded-secrets.ts').then(m => m.hardcodedSecretsRule),
+  'npm-audit':          () => import('./rules/npm-audit.ts').then(m => m.npmAuditRule),
+  'package-lock-sync':  () => import('./rules/package-lock-sync.ts').then(m => m.packageLockSyncRule),
+  'console-log':        () => import('./rules/console-log.ts').then(m => m.consoleLogRule),
+  'todo-fixme':         () => import('./rules/todo-fixme.ts').then(m => m.todoFixmeRule),
+  'large-file':         () => import('./rules/large-file.ts').then(m => m.largeFileRule),
+  'missing-tests':      () => import('./rules/missing-tests.ts').then(m => m.missingTestsRule),
+  // Security rules
+  'sql-injection':      () => import('./rules/sql-injection.ts').then(m => m.sqlInjectionRule),
+  'missing-auth':       () => import('./rules/missing-auth.ts').then(m => m.missingAuthRule),
+  'ssrf':               () => import('./rules/ssrf.ts').then(m => m.ssrfRule),
+  'insecure-redirect':  () => import('./rules/insecure-redirect.ts').then(m => m.insecureRedirectRule),
+  // Brand rules
+  'brand-tokens':       () => import('./rules/brand-tokens.ts').then(m => m.brandTokensRule),
+  // Schema alignment
+  'schema-alignment':   () => import('./rules/schema-alignment.ts').then(m => m.schemaAlignmentRule),
 };
 
 // Preset-specific rules registered by name
@@ -31,7 +40,7 @@ export async function loadRulesFromConfig(refs: StaticRuleReference[]): Promise<
     if (loader) {
       rules.push(await loader());
     } else {
-      process.stderr.write(`[autopilot] Unknown static rule: "${name}" — skipping\n`);
+      process.stderr.write(`[guardrail] Unknown static rule: "${name}" — skipping\n`);
     }
   }
   return rules;

package/src/core/static-rules/rules/brand-tokens.ts

@@ -0,0 +1,145 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { StaticRule } from '../../phases/static-rules.ts';
+import type { Finding } from '../../findings/types.ts';
+import { extractTailwindColors } from '../tailwind-extractor.ts';
+
+const UI_EXTS = new Set(['.tsx', '.jsx', '.ts', '.js', '.css', '.scss', '.sass', '.less', '.html', '.vue', '.svelte']);
+const HEX_RE = /#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})\b/g;
+const TAILWIND_ARBITRARY_HEX = /(?:bg|text|border|ring|fill|stroke|from|to|via)-\[#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})\]/g;
+// Matches the hex portion inside a Tailwind arbitrary color bracket so we can strip it before plain HEX_RE scan
+const TAILWIND_ARBITRARY_HEX_STRIP = /(?:bg|text|border|ring|fill|stroke|from|to|via)-\[#[0-9a-fA-F]{3,6}\]/g;
+const FONT_FAMILY_RE = /font-family\s*:\s*([^;}\n]+)/g;
+const CSS_EXTS = new Set(['.css', '.scss', '.sass', '.less']);
+
+function normalizeHex(hex: string): string {
+  const h = hex.toLowerCase();
+  if (h.length === 4) {
+    const r = h[1]!, g = h[2]!, b = h[3]!;
+    return `#${r}${r}${g}${g}${b}${b}`;
+  }
+  return h;
+}
+
+function buildPalette(
+  brandCfg: { colorsFrom?: string; colors?: string[] },
+  cwd: string,
+): Set<string> | null {
+  const hasColorsFrom = !!brandCfg.colorsFrom;
+  const hasColors = Array.isArray(brandCfg.colors) && brandCfg.colors.length > 0;
+  if (!hasColorsFrom && !hasColors) return null;
+
+  const palette = new Set<string>();
+  if (hasColorsFrom) {
+    const cfgPath = path.isAbsolute(brandCfg.colorsFrom!)
+      ? brandCfg.colorsFrom!
+      : path.resolve(cwd, brandCfg.colorsFrom!);
+    for (const c of extractTailwindColors(cfgPath)) palette.add(normalizeHex(c));
+  }
+  for (const c of brandCfg.colors ?? []) palette.add(normalizeHex(c));
+  return palette;
+}
+
+export const brandTokensRule: StaticRule = {
+  name: 'brand-tokens',
+  severity: 'warning',
+
+  async check(touchedFiles: string[], config: Record<string, unknown> = {}): Promise<Finding[]> {
+    const brandCfg = config.brand as
+      | { colorsFrom?: string; colors?: string[]; fonts?: string[] }
+      | undefined;
+
+    if (!brandCfg) return [];
+
+    const cwd = process.cwd();
+    const palette = buildPalette(brandCfg, cwd);
+    const canonicalFonts = brandCfg.fonts?.map(f => f.toLowerCase()) ?? [];
+    const findings: Finding[] = [];
+
+    for (const file of touchedFiles) {
+      const ext = path.extname(file);
+      if (!UI_EXTS.has(ext)) continue;
+
+      let content: string;
+      try { content = fs.readFileSync(file, 'utf8'); } catch { continue; }
+
+      const lines = content.split('\n');
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i]!;
+        const trimmed = line.trim();
+        if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) continue;
+
+        if (palette && palette.size > 0) {
+          // Check Tailwind arbitrary color classes first, then scan remaining line for plain hex
+          TAILWIND_ARBITRARY_HEX.lastIndex = 0;
+          let m: RegExpExecArray | null;
+          while ((m = TAILWIND_ARBITRARY_HEX.exec(line)) !== null) {
+            const hex = normalizeHex(`#${m[1]!}`);
+            if (!palette.has(hex)) {
+              findings.push({
+                id: `brand-tokens:tailwind:${file}:${i + 1}`,
+                source: 'static-rules',
+                severity: 'warning',
+                category: 'brand-tokens',
+                file,
+                line: i + 1,
+                message: `Off-brand Tailwind arbitrary color ${hex} is not in the canonical palette`,
+                suggestion: `Replace with a Tailwind token from your brand palette (e.g. bg-primary, text-brand)`,
+                protectedPath: false,
+                createdAt: new Date().toISOString(),
+              });
+            }
+          }
+
+          // Strip Tailwind arbitrary color brackets before plain hex scan to avoid double-reporting
+          const lineWithoutTailwindArbitrary = line.replace(TAILWIND_ARBITRARY_HEX_STRIP, '');
+          HEX_RE.lastIndex = 0;
+          while ((m = HEX_RE.exec(lineWithoutTailwindArbitrary)) !== null) {
+            const hex = normalizeHex(m[0]!);
+            if (!palette.has(hex)) {
+              const palettePreview = [...palette].slice(0, 5).join(', ');
+              findings.push({
+                id: `brand-tokens:${file}:${i + 1}`,
+                source: 'static-rules',
+                severity: 'warning',
+                category: 'brand-tokens',
+                file,
+                line: i + 1,
+                message: `Off-brand color ${hex} is not in the canonical palette`,
+                suggestion: `Use a brand token. Canonical colors: ${palettePreview}${palette.size > 5 ? ` (+${palette.size - 5} more)` : ''}`,
+                protectedPath: false,
+                createdAt: new Date().toISOString(),
+              });
+            }
+          }
+        }
+
+        if (canonicalFonts.length > 0 && CSS_EXTS.has(ext)) {
+          FONT_FAMILY_RE.lastIndex = 0;
+          let fm: RegExpExecArray | null;
+          while ((fm = FONT_FAMILY_RE.exec(line)) !== null) {
+            const declaration = fm[1]!;
+            const declared = declaration.split(',').map(f => f.trim().replace(/['"]/g, '').toLowerCase());
+            const hasCanonical = declared.some(f => canonicalFonts.some(cf => f.includes(cf)));
+            if (!hasCanonical) {
+              findings.push({
+                id: `brand-tokens:font:${file}:${i + 1}`,
+                source: 'static-rules',
+                severity: 'warning',
+                category: 'brand-tokens',
+                file,
+                line: i + 1,
+                message: `Off-brand font-family "${declaration.trim()}" — not in canonical fonts list`,
+                suggestion: `Use one of the canonical fonts: ${canonicalFonts.join(', ')}`,
+                protectedPath: false,
+                createdAt: new Date().toISOString(),
+              });
+            }
+          }
+        }
+      }
+    }
+
+    return findings;
+  },
+};