chati-dev 4.1.5 → 4.2.0

package/src/orchestrator/cli.js

@@ -30,8 +30,11 @@ import {
 import { analyzeDeviationImpact, applyDeviation } from './index.js';
 import { detectQuickFlow, detectStandardFlow } from './index.js';
 import { AGENT_FILE_MAP } from '../terminal/prompt-builder.js';
-import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
 import { join, resolve } from 'path';
+import {
+  initTaskList, readTaskList, getTeamProgress,
+} from '../terminal/team-task-list.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -375,12 +378,27 @@ async function handleNext(projectDir) {
   // Resolve model for next agent
   const modelInfo = resolveAgentModel(nextAgent, projectDir);
 
-  // Check for parallel group
+  // Check for parallel group — with Agent Teams override (Article XXI)
   let action, spawnCommand = null, parallelSpawnCommand = null, parallelAgents = [];
+  let teamData = null;
   if (nextInfo.isParallel && nextInfo.group.length > 1) {
-    action = 'spawn_parallel';
-    parallelAgents = nextInfo.group;
-    parallelSpawnCommand = buildParallelSpawnCommand(nextInfo.group, projectDir, lastAgent, modelInfo.provider, 900000);
+    // When agent_teams is enabled, substitute spawn_parallel with spawn_team
+    if (isAgentTeamsEnabled(projectDir)) {
+      const teamType = nextInfo.group.includes('dev') ? 'build' : 'planning';
+      const teamConfig = TEAM_CONFIGS[teamType];
+      const teamId = generateTeamId(teamConfig.slug);
+      action = 'spawn_team';
+      parallelAgents = teamConfig.members;
+      teamData = {
+        team_id: teamId,
+        team_type: teamType,
+        members: teamConfig.members,
+      };
+    } else {
+      action = 'spawn_parallel';
+      parallelAgents = nextInfo.group;
+      parallelSpawnCommand = buildParallelSpawnCommand(nextInfo.group, projectDir, lastAgent, modelInfo.provider, 900000);
+    }
   } else if (isInteractive) {
     action = 'activate_interactive';
   } else {
@@ -391,7 +409,7 @@ async function handleNext(projectDir) {
   const progress = getPipelineProgress(pipelineState);
   const bracket = estimateContextBracket(completedAgents.length, AGENT_PIPELINE.length);
 
-  return {
+  const result = {
     action,
     agent: nextAgent,
     agent_file: agentFile,
@@ -407,6 +425,15 @@ async function handleNext(projectDir) {
     session: { language: session.language, project_type: session.project_type || session.project?.type, execution_mode: session.execution_mode, user_level: session.user_level || 'auto' },
     status_summary: `${lastAgent} completed. Next: ${nextAgent} (${action.replace('_', ' ')}, ${agentDef?.phase || 'unknown'} phase).`,
   };
+
+  // Include team data when spawn_team action is selected (Article XXI)
+  if (teamData) {
+    result.team_id = teamData.team_id;
+    result.team_type = teamData.team_type;
+    result.members = teamData.members;
+  }
+
+  return result;
 }
 
 async function handleAdvance(projectDir, args) {
@@ -914,14 +941,382 @@ async function handleScan(projectDir, args) {
         const { scanProjectSecurity } = await import('../scanning/security-scanner.js');
         return scanProjectSecurity(projectDir, { language: args.language, dir: args.dir });
       }
+      case 'ui': {
+        const file = args.file;
+        if (!file) return errorResult('Missing --file flag for UI scan', 'MISSING_FILE');
+        const { scanUIQuality } = await import('../scanning/ui-scanner.js');
+        const { join: joinPath } = await import('path');
+        return scanUIQuality(joinPath(projectDir, file));
+      }
       default:
-        return errorResult(`Unknown scan type: ${type}. Valid: placeholders, leakage, density, env, security`, 'UNKNOWN_SCAN_TYPE');
+        return errorResult(`Unknown scan type: ${type}. Valid: placeholders, leakage, density, env, security, ui`, 'UNKNOWN_SCAN_TYPE');
     }
   } catch (err) {
     return errorResult(`Scan failed: ${err.message}`, 'SCAN_ERROR');
   }
 }
 
+// ---------------------------------------------------------------------------
+// Agent Teams Handlers (Article XXI)
+// ---------------------------------------------------------------------------
+
+const TEAM_CONFIGS = {
+  planning: {
+    members: ['detail', 'architect', 'ux'],
+    slug: 'pln',
+    templateFile: 'team-planning-tasks.yaml',
+  },
+  build: {
+    members: ['dev', 'qa-implementation'],
+    slug: 'bld',
+    templateFile: 'team-build-tasks.yaml',
+  },
+};
+
+function generateTeamId(slug) {
+  const date = new Date().toISOString().slice(0, 10).replace(/-/g, '');
+  return `TM-${date}-${slug}`;
+}
+
+function isAgentTeamsEnabled(projectDir) {
+  const configPath = join(projectDir, 'chati.dev', 'config.yaml');
+  if (!existsSync(configPath)) return false;
+  const raw = readFileSync(configPath, 'utf-8');
+  const match = raw.match(/agent_teams:\s*(true|false)/);
+  return match ? match[1] === 'true' : false;
+}
+
+async function handleSpawnTeam(projectDir, args) {
+  const teamType = args['team-type'];
+  if (!teamType || !TEAM_CONFIGS[teamType]) {
+    return errorResult('--team-type required (planning|build)', 'MISSING_TEAM_TYPE');
+  }
+
+  // Check feature flag
+  if (!isAgentTeamsEnabled(projectDir)) {
+    return {
+      action: 'spawn_parallel',
+      fallback_required: true,
+      fallback_reason: 'agent_teams_disabled',
+    };
+  }
+
+  const config = TEAM_CONFIGS[teamType];
+  const teamId = generateTeamId(config.slug);
+  const teamDir = join(projectDir, '.chati', 'teams', teamId);
+  const mailboxDir = join(teamDir, 'mailbox');
+  const taskListPath = join(teamDir, 'tasks.yaml');
+  const templatePath = join(projectDir, 'chati.dev', 'templates', config.templateFile);
+
+  // Create team directories
+  mkdirSync(mailboxDir, { recursive: true });
+
+  // Initialize task list from template
+  try {
+    initTaskList(taskListPath, templatePath, { team_id: teamId });
+
+    // For build teams: dynamically populate tasks from tasks.md (Article XXI §9)
+    if (teamType === 'build') {
+      const tasksArtifact = join(projectDir, 'chati.dev', 'artifacts', '6-Tasks', 'tasks.md');
+      if (existsSync(tasksArtifact)) {
+        const tasksContent = readFileSync(tasksArtifact, 'utf-8');
+        // Extract task IDs (pattern: T{phase}.{seq})
+        const taskMatches = tasksContent.match(/^#+\s*(T\d+\.\d+)[:\s—-]+(.+)$/gm) || [];
+        const dynamicTasks = [];
+        let seq = 1;
+
+        for (const match of taskMatches) {
+          const m = match.match(/^#+\s*(T\d+\.\d+)[:\s—-]+(.+)$/);
+          if (!m) continue;
+          const [, taskRef, title] = m;
+          const seqStr = String(seq).padStart(3, '0');
+
+          // Dev task
+          dynamicTasks.push({
+            id: `TT-BLD-${seqStr}-DEV`,
+            title: `${taskRef}: ${title.trim()}`,
+            assigned_to: 'dev',
+            status: 'pending',
+            score: null,
+            blocker: null,
+            source_task: taskRef,
+            depends_on: seq > 1 ? [`TT-BLD-${String(seq - 1).padStart(3, '0')}-QA`] : [],
+            threshold: 95,
+          });
+
+          // QA review task
+          dynamicTasks.push({
+            id: `TT-BLD-${seqStr}-QA`,
+            title: `${taskRef}: Review + approve`,
+            assigned_to: 'qa-implementation',
+            status: 'pending',
+            score: null,
+            blocker: null,
+            source_task: taskRef,
+            depends_on: [`TT-BLD-${seqStr}-DEV`],
+            threshold: 95,
+          });
+
+          seq++;
+        }
+
+        if (dynamicTasks.length > 0) {
+          const taskList = readTaskList(taskListPath);
+          if (taskList) {
+            taskList.tasks = dynamicTasks;
+            taskList.last_updated = new Date().toISOString();
+            const yaml = await import('js-yaml');
+            writeFileSync(taskListPath, yaml.default.dump(taskList, { lineWidth: -1, noRefs: true }), 'utf-8');
+          }
+        }
+      }
+    }
+  } catch (err) {
+    return errorResult(`Failed to init team task list: ${err.message}`, 'TEAM_INIT_ERROR');
+  }
+
+  // Update session with team entry
+  const previousAgent = args['previous-agent'] || 'none';
+  const provider = args.provider || 'claude';
+
+  try {
+    const { loaded, session } = loadSession(projectDir);
+    if (loaded && session) {
+      if (!session.teams) session.teams = [];
+      session.teams.push({
+        team_id: teamId,
+        phase: teamType === 'planning' ? 'planning' : 'build',
+        mission: teamType === 'planning'
+          ? 'Co-design PRD, architecture, and UX specification with cross-validated alignment'
+          : 'Implement all tasks with per-task QA review and evidence-based quality gates',
+        lead: 'orchestrator',
+        roster: config.members,
+        status: 'forming',
+        task_list_path: `.chati/teams/${teamId}/tasks.yaml`,
+        mailbox_path: `.chati/teams/${teamId}/mailbox/`,
+        formed_at: new Date().toISOString(),
+        dissolved_at: null,
+        team_score: null,
+        member_scores: {},
+        correction_cycles: 0,
+        echo_events: [],
+        fallback_used: false,
+      });
+
+      if (!session.team_events) session.team_events = [];
+      session.team_events.push({
+        timestamp: new Date().toISOString(),
+        event: 'formed',
+        team_id: teamId,
+        trigger: `${teamType} team formation after ${previousAgent}`,
+      });
+
+      await updateSession(projectDir, session);
+    }
+  } catch { /* non-critical: session update may fail, team can still spawn */ }
+
+  // Build spawn command
+  const spawnCmd = [
+    'node', join('packages', 'chati-dev', 'src', 'terminal', 'run-team.js'),
+    '--team-id', teamId,
+    '--team-type', teamType,
+    '--project-dir', resolve(projectDir),
+    '--previous-agent', previousAgent,
+    '--provider', provider,
+    '--timeout', args.timeout || '1800000',
+  ].join(' ');
+
+  return {
+    action: 'spawn_team',
+    team_id: teamId,
+    team_type: teamType,
+    members: config.members,
+    task_list_path: `.chati/teams/${teamId}/tasks.yaml`,
+    mailbox_path: `.chati/teams/${teamId}/mailbox/`,
+    spawn_team_command: spawnCmd,
+    poll_interval_ms: 5000,
+    fallback_required: false,
+  };
+}
+
+async function handleTeamStatus(projectDir, args) {
+  const teamId = args['team-id'];
+  if (!teamId) return errorResult('--team-id required', 'MISSING_TEAM_ID');
+
+  const taskListPath = join(projectDir, '.chati', 'teams', teamId, 'tasks.yaml');
+  const progress = getTeamProgress(taskListPath);
+
+  // Read echo events from session
+  let echoEvents = [];
+  try {
+    const { loaded, session } = loadSession(projectDir);
+    if (loaded && session && session.teams) {
+      const team = session.teams.find(t => t.team_id === teamId);
+      if (team) echoEvents = team.echo_events || [];
+    }
+  } catch { /* non-critical */ }
+
+  return {
+    team_id: teamId,
+    status: progress.done === progress.total ? 'completing' : 'active',
+    member_progress: progress.memberProgress,
+    total_tasks: progress.total,
+    completed_tasks: progress.done,
+    pending_tasks: progress.pending,
+    blocked_tasks: progress.blocked,
+    echo_events: echoEvents,
+  };
+}
+
+async function handleTeamDissolve(projectDir, args) {
+  const teamId = args['team-id'];
+  if (!teamId) return errorResult('--team-id required', 'MISSING_TEAM_ID');
+
+  const taskListPath = join(projectDir, '.chati', 'teams', teamId, 'tasks.yaml');
+  const progress = getTeamProgress(taskListPath);
+
+  // Derive team type from team ID slug (for mailbox checks and tier threshold)
+  const teamType = teamId.includes('-bld') ? 'build' : 'planning';
+
+  // Read echo events from session
+  let echoEvents = [];
+  try {
+    const { loaded: echoLoaded, session: echoSession } = loadSession(projectDir);
+    if (echoLoaded && echoSession && echoSession.teams) {
+      const team = echoSession.teams.find(t => t.team_id === teamId);
+      if (team) echoEvents = team.echo_events || [];
+    }
+  } catch { /* best-effort */ }
+
+  // Calculate team score
+  const memberScores = {};
+  let totalScore = 0;
+  let scoreCount = 0;
+  for (const [member, data] of Object.entries(progress.memberProgress)) {
+    if (data.score !== null) {
+      memberScores[member] = data.score;
+      totalScore += data.score;
+      scoreCount++;
+    }
+  }
+  const teamScore = scoreCount > 0 ? Math.round((totalScore / scoreCount) * 10) / 10 : 0;
+
+  // Team Quality Gate — verify all 6 conditions (Article XXI section 6)
+  const allDone = progress.done === progress.total;
+  // Dynamic tier threshold per Article XXI §6: must meet highest tier in roster
+  // QA agents (qa-planning, qa-implementation) require 95%, standard agents 90%
+  const QA_AGENTS = ['qa-planning', 'qa-implementation'];
+  const teamConfig = TEAM_CONFIGS[teamType];
+  const hasQaAgent = teamConfig ? teamConfig.members.some(m => QA_AGENTS.includes(m)) : false;
+  const tierThreshold = hasQaAgent ? 95 : 90;
+  const allScoresPass = Object.values(memberScores).every(s => s >= tierThreshold);
+  const noBlockers = progress.blocked === 0;
+
+  // Check mailbox cleanliness
+  let mailboxClean = true;
+  try {
+    const { readInbox } = await import('../terminal/team-task-list.js');
+    const mailboxDir = join(projectDir, '.chati', 'teams', teamId, 'mailbox');
+    // Check all members for unresolved messages
+    const dissolveTeamConfig = TEAM_CONFIGS[teamType];
+    if (dissolveTeamConfig) {
+      for (const member of dissolveTeamConfig.members) {
+        const inbox = readInbox(mailboxDir, member);
+        const unresolved = inbox.filter(m => m.type === 'task_review_findings' && m.payload?.verdict === 'block');
+        if (unresolved.length > 0) { mailboxClean = false; break; }
+      }
+    }
+  } catch { /* mailbox check is best-effort */ }
+
+  // Check correction cycles against config limit (Article XXI §6)
+  let correctionCyclesOk = true;
+  let maxCorrectionCycles = 2; // default per constitution
+  try {
+    const configPath = join(projectDir, 'chati.dev', 'config.yaml');
+    if (existsSync(configPath)) {
+      const configRaw = readFileSync(configPath, 'utf-8');
+      const maxMatch = configRaw.match(/team_correction_cycles_max:\s*(\d+)/);
+      if (maxMatch) maxCorrectionCycles = parseInt(maxMatch[1], 10);
+    }
+  } catch { /* use default */ }
+  try {
+    const { loaded, session: sess } = loadSession(projectDir);
+    if (loaded && sess && sess.teams) {
+      const team = sess.teams.find(t => t.team_id === teamId);
+      if (team && team.correction_cycles > maxCorrectionCycles) correctionCyclesOk = false;
+    }
+  } catch { /* best-effort */ }
+
+  // Determine dissolution state based on all conditions
+  const qualityGatePassed = allDone && allScoresPass && mailboxClean && noBlockers && correctionCyclesOk && teamScore >= tierThreshold;
+  const state = qualityGatePassed ? 'clean' : 'degraded';
+  const gateFailures = [];
+  if (!allDone) gateFailures.push('incomplete_tasks');
+  if (!allScoresPass) gateFailures.push('scores_below_threshold');
+  if (!mailboxClean) gateFailures.push('unresolved_mailbox_messages');
+  if (!noBlockers) gateFailures.push('open_blockers');
+  if (!correctionCyclesOk) gateFailures.push('correction_cycles_exceeded');
+  if (teamScore < 90) gateFailures.push('team_score_below_threshold');
+
+  // Update session
+  try {
+    const { loaded, session } = loadSession(projectDir);
+    if (loaded && session && session.teams) {
+      const team = session.teams.find(t => t.team_id === teamId);
+      if (team) {
+        team.status = state === 'clean' ? 'dissolved' : 'degraded';
+        team.dissolved_at = new Date().toISOString();
+        team.team_score = teamScore;
+        team.member_scores = memberScores;
+      }
+
+      if (!session.team_events) session.team_events = [];
+      session.team_events.push({
+        timestamp: new Date().toISOString(),
+        event: state === 'clean' ? 'dissolved' : 'degraded',
+        team_id: teamId,
+        trigger: state === 'clean' ? 'Team Quality Gate passed' : `Degraded dissolution — failures: ${gateFailures.join(', ')}`,
+        state,
+      });
+
+      // Sync member scores to agents block
+      if (session.agents) {
+        for (const [member, score] of Object.entries(memberScores)) {
+          if (session.agents[member]) {
+            session.agents[member].score = score;
+            session.agents[member].status = 'completed';
+            session.agents[member].completed_at = new Date().toISOString();
+          }
+        }
+      }
+
+      await updateSession(projectDir, session);
+    }
+  } catch { /* non-critical */ }
+
+  return {
+    dissolved: true,
+    team_id: teamId,
+    team_score: teamScore,
+    member_scores: memberScores,
+    state,
+    all_tasks_complete: allDone,
+    echo_events: echoEvents,
+    quality_gate: {
+      passed: qualityGatePassed,
+      failures: gateFailures,
+      checks: {
+        all_tasks_complete: allDone,
+        all_scores_pass_threshold: allScoresPass,
+        mailbox_clean: mailboxClean,
+        no_open_blockers: noBlockers,
+        correction_cycles_ok: correctionCyclesOk,
+        team_score_above_threshold: teamScore >= 90,
+      },
+    },
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Main entry point
 // ---------------------------------------------------------------------------
@@ -970,8 +1365,17 @@ export async function runOrchestrate(subCommand, argv, projectDir) {
       case 'scan':
         output(await handleScan(projectDir, args));
         break;
+      case 'spawn-team':
+        output(await handleSpawnTeam(projectDir, args));
+        break;
+      case 'team-status':
+        output(await handleTeamStatus(projectDir, args));
+        break;
+      case 'team-dissolve':
+        output(await handleTeamDissolve(projectDir, args));
+        break;
       default:
-        output(errorResult(`Unknown sub-command: ${subCommand}. Valid: next, advance, init, validate-handoff, status, deviation, exit, providers, detect-flow, backlog, qa-plan-score, qa-impl-score, scan`, 'UNKNOWN_COMMAND'));
+        output(errorResult(`Unknown sub-command: ${subCommand}. Valid: next, advance, init, validate-handoff, status, deviation, exit, providers, detect-flow, backlog, qa-plan-score, qa-impl-score, scan, spawn-team, team-status, team-dissolve`, 'UNKNOWN_COMMAND'));
         break;
     }
   } catch (err) {

package/src/orchestrator/handoff-engine.js

@@ -30,7 +30,7 @@ export function executeHandoff(projectDir, params) {
   const errors = [];
 
   // Validate preconditions
-  const preconditions = validateHandoffPreconditions(params);
+  const preconditions = validateHandoffPreconditions(params, projectDir);
   if (!preconditions.valid) {
     return {
       success: false,
@@ -113,7 +113,7 @@ export function executeHandoff(projectDir, params) {
  * @param {object} params
  * @returns {{ valid: boolean, issues: string[] }}
  */
-export function validateHandoffPreconditions(params) {
+export function validateHandoffPreconditions(params, projectDir = '.') {
   const issues = [];
 
   // Check validation exists and passed
@@ -148,6 +148,19 @@ export function validateHandoffPreconditions(params) {
     issues.push('Handoff summary is required');
   }
 
+  // Deterministic artifact checks for UX agent handoffs
+  const agent = params.fromTask?.agent || params.fromTask?.id?.split('-')[0] || '';
+  if (agent === 'ux') {
+    const brandbookPath = join(projectDir, 'chati.dev', 'artifacts', '4-UX', 'brandbook.html');
+    if (!existsSync(brandbookPath)) {
+      issues.push('brandbook.html is missing — UX handoff requires the visual brandbook file on disk');
+    }
+    const discoveryLogPath = join(projectDir, 'chati.dev', 'artifacts', '4-UX', 'component-discovery-log.md');
+    if (!existsSync(discoveryLogPath)) {
+      issues.push('component-discovery-log.md is missing — UX handoff requires component discovery documentation');
+    }
+  }
+
   return {
     valid: issues.length === 0,
     issues,
@@ -319,6 +332,20 @@ export function validateHandoffIntegrity(handoff, receivingAgent) {
     }
   }
 
+  // Check for screenshot evidence from Dev agent (UI tasks)
+  if (handoff.from_agent === 'dev' || handoff.agent === 'dev') {
+    const hasUIOutputs = handoff.outputs && handoff.outputs.some(o =>
+      /\.(tsx|jsx|vue|svelte|css)$/i.test(o)
+    );
+    if (hasUIOutputs) {
+      const hasVisualEvidence = handoff.summary &&
+        (handoff.summary.includes('Visual review PASSED') || handoff.summary.includes('screenshot'));
+      if (!hasVisualEvidence) {
+        warnings.push('Dev agent produced UI files but no visual review evidence found in handoff — manual visual review recommended');
+      }
+    }
+  }
+
   return {
     valid: missing.length === 0,
     missing,

package/src/scanning/index.js

@@ -5,3 +5,4 @@ export { scanImplementationLeakage, extractFRSection, TECH_NAMES } from './leaka
 export { scanInformationDensity, FILLER_PATTERNS } from './density-scanner.js';
 export { scanEnvSync, parseEnvFile, grepEnvUsage } from './env-scanner.js';
 export { scanProjectSecurity, detectLanguage } from './security-scanner.js';
+export { scanUIQuality, UI_QUALITY_CHECKS } from './ui-scanner.js';

package/src/scanning/ui-scanner.js

@@ -0,0 +1,120 @@
+/**
+ * UI Quality Scanner -- Detects hardcoded visual values in UI files.
+ * Deterministic regex scan. Zero LLM dependency.
+ *
+ * Catches common "vibecoded" patterns:
+ * - Hardcoded hex colors (should use design tokens)
+ * - Inline styles with px values (should use spacing tokens)
+ * - !important in CSS (code smell)
+ * - Images without alt attributes (accessibility)
+ * - Inline style= attributes (should use classes/tokens)
+ */
+
+import { readFileSync } from 'fs';
+
+/**
+ * UI quality patterns. Each has an id, pattern, severity, and description.
+ */
+export const UI_QUALITY_CHECKS = [
+  {
+    id: 'HARDCODED_HEX_COLOR',
+    pattern: /(?<![\\w-])(?:color|background|border|fill|stroke)\s*:\s*#[0-9a-fA-F]{3,8}\b/g,
+    severity: 'high',
+    description: 'Hardcoded hex color in CSS property — use design tokens instead',
+  },
+  {
+    id: 'INLINE_STYLE',
+    pattern: /\bstyle\s*=\s*["'{]/g,
+    severity: 'medium',
+    description: 'Inline style attribute — use CSS classes or design tokens',
+  },
+  {
+    id: 'CSS_IMPORTANT',
+    pattern: /!\s*important/gi,
+    severity: 'medium',
+    description: '!important in CSS — indicates specificity problem',
+  },
+  {
+    id: 'IMG_MISSING_ALT',
+    pattern: /<img(?![^>]*\balt\s*=)[^>]*>/gi,
+    severity: 'high',
+    description: 'Image tag without alt attribute — accessibility violation',
+  },
+  {
+    id: 'HARDCODED_PX_INLINE',
+    pattern: /style\s*=\s*["'][^"']*\d+px[^"']*["']/g,
+    severity: 'medium',
+    description: 'Hardcoded px values in inline style — use spacing tokens',
+  },
+  {
+    id: 'HARDCODED_RGBA',
+    pattern: /(?<![\\w-])(?:color|background|border|fill|stroke)\s*:\s*rgba?\([^)]+\)/g,
+    severity: 'high',
+    description: 'Hardcoded rgba color — use design tokens instead',
+  },
+];
+
+/**
+ * File extensions this scanner targets.
+ */
+const UI_FILE_EXTENSIONS = ['.tsx', '.jsx', '.vue', '.svelte', '.css', '.scss'];
+
+/**
+ * Paths to skip (config files, design token definitions, tailwind config).
+ */
+const SKIP_PATTERNS = [
+  /tailwind\.config/,
+  /globals\.css$/,
+  /tokens?\./,
+  /theme\./,
+  /\.config\./,
+  /node_modules/,
+  /brandbook/,
+];
+
+/**
+ * Check if a file should be scanned.
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function shouldScan(filePath) {
+  const hasUIExtension = UI_FILE_EXTENSIONS.some(ext => filePath.endsWith(ext));
+  const isSkipped = SKIP_PATTERNS.some(p => p.test(filePath));
+  return hasUIExtension && !isSkipped;
+}
+
+/**
+ * Scan a file for UI quality violations.
+ * @param {string} filePath - Path to file to scan
+ * @returns {{ clean: boolean, findings: Array<{id: string, match: string, line: number, severity: string, description: string}>, count: number, skipped: boolean }}
+ */
+export function scanUIQuality(filePath) {
+  if (!shouldScan(filePath)) {
+    return { clean: true, findings: [], count: 0, skipped: true };
+  }
+
+  const content = readFileSync(filePath, 'utf-8');
+  const findings = [];
+
+  for (const check of UI_QUALITY_CHECKS) {
+    const re = new RegExp(check.pattern.source, check.pattern.flags);
+    let match;
+    while ((match = re.exec(content)) !== null) {
+      const line = content.slice(0, match.index).split('\n').length;
+      findings.push({
+        id: check.id,
+        match: match[0].slice(0, 80),
+        line,
+        severity: check.severity,
+        description: check.description,
+      });
+    }
+  }
+
+  return {
+    clean: findings.length === 0,
+    findings,
+    count: findings.length,
+    skipped: false,
+  };
+}