@delegance/claude-autopilot 5.0.0 → 5.0.2

package/src/cli/autoregress-bridge.ts

@@ -1,30 +0,0 @@
-// src/cli/autoregress-bridge.ts
-import * as path from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const SCRIPT = path.resolve(__dirname, '../../scripts/autoregress.ts');
-
-const VALID_MODES = ['run', 'update', 'generate', 'diff'];
-
-export function buildAutoregressArgs(args: string[]): string[] {
-  const mode = args[0] && VALID_MODES.includes(args[0]) ? args[0] : 'run';
-  const rest = args[0] && VALID_MODES.includes(args[0]) ? args.slice(1) : args;
-  return [mode, ...rest];
-}
-
-export function runAutoregress(args: string[]): number {
-  const resolvedArgs = buildAutoregressArgs(args);
-  const result = spawnSync(
-    process.execPath,
-    ['--import', 'tsx', SCRIPT, ...resolvedArgs],
-    { stdio: 'inherit', cwd: process.cwd() },
-  );
-  if (result.error) {
-    console.error(`[autoregress] failed to launch: ${result.error.message}`);
-    console.error(`  script: ${SCRIPT}`);
-    return 1;
-  }
-  return result.status ?? 1;
-}

package/src/cli/baseline.ts

@@ -1,125 +0,0 @@
-import * as path from 'node:path';
-import * as fs from 'node:fs';
-import {
-  loadBaseline, saveBaseline, clearBaseline, diffAgainstBaseline,
-  baselineFilePath,
-} from '../core/persist/baseline.ts';
-import { loadCachedFindings } from '../core/persist/findings-cache.ts';
-
-const C = {
-  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
-  green: '\x1b[32m', yellow: '\x1b[33m', red: '\x1b[31m', cyan: '\x1b[36m',
-};
-const fmt = (c: keyof typeof C, t: string) => `${C[c]}${t}${C.reset}`;
-
-export interface BaselineCommandOptions {
-  cwd?: string;
-  note?: string;
-  baselinePath?: string;
-}
-
-export async function runBaseline(sub: string, options: BaselineCommandOptions = {}): Promise<number> {
-  const cwd = options.cwd ?? process.cwd();
-  const bPath = baselineFilePath(cwd, options.baselinePath);
-  const relPath = path.relative(cwd, bPath);
-
-  switch (sub) {
-    case 'create': {
-      if (fs.existsSync(bPath)) {
-        console.log(fmt('yellow', `[baseline] ${relPath} already exists — use \`guardrail baseline update\` to refresh, or \`guardrail baseline clear\` to reset`));
-        return 1;
-      }
-      return createOrUpdate(cwd, bPath, relPath, options.note, 'Created');
-    }
-
-    case 'update': {
-      return createOrUpdate(cwd, bPath, relPath, options.note, 'Updated');
-    }
-
-    case 'show': {
-      const baseline = loadBaseline(cwd, options.baselinePath);
-      if (!baseline) {
-        console.log(fmt('yellow', `[baseline] No baseline found at ${relPath}`));
-        console.log(fmt('dim', '  Run: guardrail baseline create'));
-        return 0;
-      }
-      console.log(`\n${fmt('bold', '[baseline]')} ${fmt('dim', relPath)}`);
-      console.log(fmt('dim', `  Created: ${baseline.createdAt}  Updated: ${baseline.updatedAt}`));
-      if (baseline.note) console.log(fmt('dim', `  Note: ${baseline.note}`));
-      console.log(`  ${baseline.entries.length} pinned finding${baseline.entries.length !== 1 ? 's' : ''}\n`);
-      for (const e of baseline.entries) {
-        const sev = e.severity === 'critical' ? fmt('red', 'CRIT') : e.severity === 'warning' ? fmt('yellow', 'WARN') : fmt('dim', 'NOTE');
-        console.log(`  [${sev}] ${fmt('dim', `${e.file}${e.line ? `:${e.line}` : ''}`)} ${e.message.slice(0, 70)}`);
-      }
-      console.log('');
-      return 0;
-    }
-
-    case 'diff': {
-      const baseline = loadBaseline(cwd, options.baselinePath);
-      if (!baseline) {
-        console.log(fmt('yellow', `[baseline] No baseline found — run: guardrail baseline create`));
-        return 1;
-      }
-      const current = loadCachedFindings(cwd);
-      if (current.length === 0) {
-        console.log(fmt('yellow', '[baseline] No cached findings — run `guardrail run` or `guardrail scan` first'));
-        return 1;
-      }
-      const diff = diffAgainstBaseline(current, baseline);
-      console.log(`\n${fmt('bold', '[guardrail baseline diff]')} vs ${fmt('dim', relPath)}\n`);
-
-      if (diff.added.length > 0) {
-        console.log(fmt('red', `  ${diff.added.length} new finding${diff.added.length !== 1 ? 's' : ''} (not in baseline):`));
-        for (const f of diff.added) {
-          const sev = f.severity === 'critical' ? fmt('red', 'CRIT') : f.severity === 'warning' ? fmt('yellow', 'WARN') : fmt('dim', 'NOTE');
-          console.log(`    [${sev}] ${fmt('dim', `${f.file}${f.line ? `:${f.line}` : ''}`)} ${f.message.slice(0, 70)}`);
-        }
-        console.log('');
-      }
-      if (diff.resolved.length > 0) {
-        console.log(fmt('green', `  ${diff.resolved.length} resolved (in baseline but not in current):`));
-        for (const e of diff.resolved) {
-          console.log(`    ${fmt('dim', `${e.file}${e.line ? `:${e.line}` : ''}`)} ${e.message.slice(0, 70)}`);
-        }
-        console.log('');
-      }
-      if (diff.added.length === 0 && diff.resolved.length === 0) {
-        console.log(fmt('green', `  ✓ No changes vs baseline (${diff.unchanged.length} pinned findings unchanged)\n`));
-      } else {
-        console.log(fmt('dim', `  ${diff.unchanged.length} unchanged · run \`guardrail baseline update\` to pin new state\n`));
-      }
-      return diff.added.some(f => f.severity === 'critical') ? 1 : 0;
-    }
-
-    case 'clear': {
-      if (!fs.existsSync(bPath)) {
-        console.log(fmt('dim', `[baseline] No baseline at ${relPath} — nothing to clear`));
-        return 0;
-      }
-      clearBaseline(cwd, options.baselinePath);
-      console.log(fmt('green', `[baseline] Cleared ${relPath}`));
-      return 0;
-    }
-
-    default:
-      console.error(fmt('red', `[baseline] Unknown subcommand: "${sub}"`));
-      console.error(fmt('dim', '  Usage: guardrail baseline <create|update|show|diff|clear> [--note "..."]'));
-      return 1;
-  }
-}
-
-function createOrUpdate(cwd: string, bPath: string, relPath: string, note: string | undefined, verb: string): number {
-  const findings = loadCachedFindings(cwd);
-  if (findings.length === 0) {
-    console.log(fmt('yellow', '[baseline] No cached findings to snapshot — run `guardrail run` or `guardrail scan` first'));
-    return 1;
-  }
-  const baseline = saveBaseline(cwd, findings, { note, overridePath: bPath === path.join(cwd, '.guardrail-baseline.json') ? undefined : bPath });
-  console.log(`\n${fmt('green', `[baseline] ${verb}`)} ${fmt('dim', relPath)}`);
-  console.log(`  ${baseline.entries.length} finding${baseline.entries.length !== 1 ? 's' : ''} pinned as accepted baseline`);
-  if (note) console.log(`  Note: ${note}`);
-  console.log(fmt('dim', `\n  Commit this file to share the baseline with your team:`));
-  console.log(fmt('cyan', `    git add ${relPath} && git commit -m "chore: update guardrail baseline"\n`));
-  return 0;
-}

package/src/cli/ci.ts

@@ -1,45 +0,0 @@
-import { runCommand } from './run.ts';
-
-export interface CiCommandOptions {
-  cwd?: string;
-  configPath?: string;
-  base?: string;
-  postComments?: boolean;
-  sarifOutput?: string;
-  diff?: boolean;
-  inlineComments?: boolean;
-  newOnly?: boolean;
-  failOn?: 'critical' | 'warning' | 'note' | 'none';
-}
-
-/**
- * `guardrail ci` — opinionated single-command CI entrypoint.
- *
- * Defaults:
- *   base          GITHUB_BASE_REF → HEAD~1
- *   output        guardrail.sarif
- *   post-comments true
- *   fail-on       critical (or policy.failOn from config)
- *   new-only      false (or policy.newOnly from config)
- */
-export async function runCi(options: CiCommandOptions = {}): Promise<number> {
-  const base = options.base
-    ?? process.env.GITHUB_BASE_REF
-    ?? process.env.CI_MERGE_REQUEST_TARGET_BRANCH_NAME  // GitLab
-    ?? 'HEAD~1';
-
-  const sarifOutput = options.sarifOutput ?? 'guardrail.sarif';
-
-  return runCommand({
-    cwd: options.cwd,
-    configPath: options.configPath,
-    base,
-    postComments: options.postComments ?? true,
-    format: 'sarif',
-    outputPath: sarifOutput,
-    diff: options.diff,
-    inlineComments: options.inlineComments ?? true,
-    newOnly: options.newOnly,
-    failOn: options.failOn,
-  });
-}

package/src/cli/costs.ts

@@ -1,80 +0,0 @@
-import { readCostLog } from '../core/persist/cost-log.ts';
-import type { CostLogEntry } from '../core/persist/cost-log.ts';
-
-const C = {
-  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
-  green: '\x1b[32m', yellow: '\x1b[33m', cyan: '\x1b[36m',
-};
-const fmt = (c: keyof typeof C, t: string) => `${C[c]}${t}${C.reset}`;
-
-function formatDate(iso: string): string {
-  try {
-    const d = new Date(iso);
-    return `${d.toLocaleDateString()} ${d.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })}`;
-  } catch { return iso; }
-}
-
-function fmtUSD(n: number): string {
-  return n === 0 ? fmt('dim', '$0.0000') : `$${n.toFixed(4)}`;
-}
-
-function fmtTokens(n: number): string {
-  return n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n);
-}
-
-export async function runCosts(cwd = process.cwd()): Promise<number> {
-  const log = readCostLog(cwd);
-
-  if (log.length === 0) {
-    console.log(fmt('yellow', '[costs] No run history found — run `guardrail run` first.'));
-    return 0;
-  }
-
-  // 7-day window
-  const sevenDaysAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;
-  const recent = log.filter(e => new Date(e.timestamp).getTime() >= sevenDaysAgo);
-  const last10 = log.slice(-10).reverse();
-
-  const totalCost = log.reduce((s, e) => s + e.costUSD, 0);
-  const totalInput = log.reduce((s, e) => s + e.inputTokens, 0);
-  const totalOutput = log.reduce((s, e) => s + e.outputTokens, 0);
-  const recentCost = recent.reduce((s, e) => s + e.costUSD, 0);
-
-  console.log(`\n${fmt('bold', '[costs]')}\n`);
-
-  // Summary row
-  console.log(fmt('bold', 'Summary'));
-  console.log(`  All-time runs:   ${log.length}`);
-  console.log(`  All-time cost:   ${fmtUSD(totalCost)}  (${fmtTokens(totalInput)} in / ${fmtTokens(totalOutput)} out)`);
-  console.log(`  Last 7 days:     ${fmtUSD(recentCost)}  (${recent.length} run${recent.length !== 1 ? 's' : ''})`);
-  console.log('');
-
-  // Last 10 runs table
-  console.log(fmt('bold', `Recent runs (last ${last10.length})`));
-  const COL = { date: 22, files: 7, input: 8, output: 8, cost: 10, dur: 8 };
-  const header = [
-    'Date'.padEnd(COL.date),
-    'Files'.padStart(COL.files),
-    'In tok'.padStart(COL.input),
-    'Out tok'.padStart(COL.output),
-    'Cost'.padStart(COL.cost),
-    'Time'.padStart(COL.dur),
-  ].join('  ');
-  console.log(fmt('dim', '  ' + header));
-  console.log(fmt('dim', '  ' + '─'.repeat(header.length)));
-
-  for (const e of last10) {
-    const row = [
-      formatDate(e.timestamp).padEnd(COL.date),
-      String(e.files).padStart(COL.files),
-      fmtTokens(e.inputTokens).padStart(COL.input),
-      fmtTokens(e.outputTokens).padStart(COL.output),
-      fmtUSD(e.costUSD).padStart(COL.cost + 9), // +9 for ANSI codes in dim
-      `${e.durationMs}ms`.padStart(COL.dur),
-    ].join('  ');
-    console.log('  ' + row);
-  }
-
-  console.log('');
-  return 0;
-}

package/src/cli/council.ts

@@ -1,96 +0,0 @@
-// src/cli/council.ts
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import { loadConfig } from '../core/config/loader.ts';
-import { parseCouncilConfig } from '../core/council/config.ts';
-import { runCouncil } from '../core/council/runner.ts';
-import { makeClaudeCouncilAdapter } from '../adapters/council/claude.ts';
-import { makeOpenAICouncilAdapter } from '../adapters/council/openai.ts';
-import type { CouncilAdapter } from '../adapters/council/types.ts';
-import type { CouncilModelEntry } from '../core/council/types.ts';
-import { GuardrailError } from '../core/errors.ts';
-
-function makeAdapter(entry: CouncilModelEntry): CouncilAdapter {
-  switch (entry.adapter) {
-    case 'claude': return makeClaudeCouncilAdapter(entry.model, entry.label);
-    case 'openai': return makeOpenAICouncilAdapter(entry.model, entry.label);
-  }
-}
-
-export async function runCouncilCmd(opts: {
-  prompt?: string;
-  contextFile?: string;
-  configPath?: string;
-  dryRun?: boolean;
-  noSynthesize?: boolean;
-}): Promise<number> {
-  const cwd = process.cwd();
-  const configPath = opts.configPath ?? path.join(cwd, 'guardrail.config.yaml');
-
-  let config;
-  try {
-    config = await loadConfig(configPath);
-  } catch (err) {
-    console.error(err instanceof GuardrailError ? err.message : String(err));
-    return 1;
-  }
-
-  if (!config.council) {
-    console.error('[council] No "council" section in guardrail.config.yaml — add council.models and council.synthesizer');
-    return 1;
-  }
-
-  let councilConfig;
-  try {
-    councilConfig = parseCouncilConfig(config.council as Record<string, unknown>);
-  } catch (err) {
-    console.error(err instanceof GuardrailError ? err.message : String(err));
-    return 1;
-  }
-
-  if (opts.dryRun) {
-    process.stdout.write(JSON.stringify({ schema_version: 1, status: 'dry_run', config: councilConfig }, null, 2) + '\n');
-    return 0;
-  }
-
-  if (!opts.prompt) {
-    console.error('[council] --prompt is required');
-    return 1;
-  }
-  if (!opts.contextFile) {
-    console.error('[council] --context-file is required');
-    return 1;
-  }
-
-  let contextDoc: string;
-  try {
-    contextDoc = fs.readFileSync(opts.contextFile, 'utf8');
-  } catch {
-    console.error(`[council] Cannot read context file: ${opts.contextFile}`);
-    return 1;
-  }
-
-  const adapters = councilConfig.models.map(makeAdapter);
-  const synthesizer = opts.noSynthesize
-    ? { label: 'none', consult: async () => '' } as CouncilAdapter
-    : makeAdapter(councilConfig.synthesizer);
-
-  const result = await runCouncil(
-    councilConfig,
-    adapters,
-    synthesizer,
-    opts.prompt,
-    contextDoc,
-  );
-
-  // When no-synthesize, clear the empty synthesis object
-  if (opts.noSynthesize && result.synthesis?.text === '') {
-    delete (result as unknown as Record<string, unknown>)['synthesis'];
-  }
-
-  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
-
-  if (result.status === 'failed') return 2;
-  if (result.status === 'partial') return 1;
-  return 0;
-}

package/src/cli/detector.ts

@@ -1,92 +0,0 @@
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-
-export interface DetectionResult {
-  preset: string;
-  testCommand: string;
-  confidence: 'high' | 'low';
-  evidence: string;
-}
-
-function readJson(filePath: string): Record<string, unknown> | null {
-  try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-function fileContains(filePath: string, needle: string): boolean {
-  try {
-    return fs.readFileSync(filePath, 'utf8').includes(needle);
-  } catch {
-    return false;
-  }
-}
-
-const DEFAULT_TEST_PLACEHOLDER = /^echo .error: no test specified/i;
-
-function nodeTestCommand(cwd: string): string {
-  const pkg = readJson(path.join(cwd, 'package.json'));
-  const scripts = pkg?.['scripts'] as Record<string, string> | undefined;
-  const cmd = scripts?.['test'];
-  if (!cmd || DEFAULT_TEST_PLACEHOLDER.test(cmd)) return 'npm test';
-  return cmd;
-}
-
-// Detects Supabase signals beyond package.json deps — env vars, config files, or client
-// usage. Required because many Next.js projects reference Supabase via the CLI/SSR tooling
-// before installing the JS client.
-function hasSupabaseSignals(cwd: string, deps: Record<string, string>): boolean {
-  if ('@supabase/supabase-js' in deps) return true;
-  if ('@supabase/ssr' in deps) return true;
-  if ('@supabase/auth-helpers-nextjs' in deps) return true;
-  if (fs.existsSync(path.join(cwd, 'supabase', 'config.toml'))) return true;
-  for (const envFile of ['.env', '.env.local', '.env.development']) {
-    const p = path.join(cwd, envFile);
-    if (fs.existsSync(p) && fileContains(p, 'SUPABASE_')) return true;
-  }
-  return false;
-}
-
-export function detectProject(cwd: string): DetectionResult {
-  if (fs.existsSync(path.join(cwd, 'go.mod'))) {
-    return { preset: 'go', testCommand: 'go test ./...', confidence: 'high', evidence: 'found go.mod' };
-  }
-
-  const gemfile = path.join(cwd, 'Gemfile');
-  if (fs.existsSync(gemfile) && fileContains(gemfile, 'rails')) {
-    return { preset: 'rails-postgres', testCommand: 'bundle exec rails test', confidence: 'high', evidence: "found Gemfile with 'rails'" };
-  }
-
-  const reqTxt = path.join(cwd, 'requirements.txt');
-  const pyproject = path.join(cwd, 'pyproject.toml');
-  if ((fs.existsSync(reqTxt) && fileContains(reqTxt, 'fastapi')) ||
-      (fs.existsSync(pyproject) && fileContains(pyproject, 'fastapi'))) {
-    return { preset: 'python-fastapi', testCommand: 'pytest', confidence: 'high', evidence: 'found fastapi in requirements' };
-  }
-
-  const pkgPath = path.join(cwd, 'package.json');
-  if (fs.existsSync(pkgPath)) {
-    const pkg = readJson(pkgPath);
-    const deps = {
-      ...(pkg?.['dependencies'] as Record<string, string> ?? {}),
-      ...(pkg?.['devDependencies'] as Record<string, string> ?? {}),
-    };
-    const testCmd = nodeTestCommand(cwd);
-
-    if ('@trpc/server' in deps) {
-      return { preset: 't3', testCommand: testCmd, confidence: 'high', evidence: 'found @trpc/server in package.json' };
-    }
-    if ('next' in deps && hasSupabaseSignals(cwd, deps)) {
-      return { preset: 'nextjs-supabase', testCommand: testCmd, confidence: 'high', evidence: 'found next + supabase signals (deps/env/config)' };
-    }
-    if ('next' in deps) {
-      // Plain Next.js — fall through to generic rather than mislabel as nextjs-supabase.
-      return { preset: 'generic', testCommand: testCmd, confidence: 'low', evidence: 'found next in package.json but no Supabase signals — using generic preset (pass --preset nextjs-supabase if you do use Supabase)' };
-    }
-    return { preset: 'generic', testCommand: testCmd, confidence: 'low', evidence: 'found package.json (no strong framework signals) — using generic preset' };
-  }
-
-  return { preset: 'generic', testCommand: 'npm test', confidence: 'low', evidence: 'no project signals found — using generic preset' };
-}

package/src/cli/explain.ts

@@ -1,197 +0,0 @@
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import { loadCachedFindings } from '../core/persist/findings-cache.ts';
-import { loadConfig } from '../core/config/loader.ts';
-import { loadAdapter } from '../adapters/loader.ts';
-import type { Finding } from '../core/findings/types.ts';
-import type { ReviewEngine } from '../adapters/review-engine/types.ts';
-
-const C = {
-  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
-  green: '\x1b[32m', yellow: '\x1b[33m', red: '\x1b[31m', cyan: '\x1b[36m',
-};
-const fmt = (c: keyof typeof C, t: string) => `${C[c]}${t}${C.reset}`;
-
-const CONTEXT_LINES = 30;
-
-const SECTION_ORDER = ['Root Cause', 'Risk', 'How to Fix', 'Example', 'When to Suppress'] as const;
-type SectionName = typeof SECTION_ORDER[number];
-
-export interface ExplainCommandOptions {
-  cwd?: string;
-  configPath?: string;
-  target?: string;   // "file:line" or finding index (1-based) or finding id
-  index?: number;    // 1-based index into cached findings
-}
-
-function pickFinding(findings: Finding[], target: string): Finding | null {
-  // Try "file:line" format
-  const colonIdx = target.lastIndexOf(':');
-  if (colonIdx > 0) {
-    const file = target.slice(0, colonIdx);
-    const line = parseInt(target.slice(colonIdx + 1), 10);
-    if (!isNaN(line)) {
-      const match = findings.find(f => f.file.endsWith(file) && f.line === line);
-      if (match) return match;
-    }
-  }
-  // Try numeric index (1-based)
-  const n = parseInt(target, 10);
-  if (!isNaN(n) && n >= 1 && n <= findings.length) return findings[n - 1]!;
-  // Try finding id prefix
-  const byId = findings.find(f => f.id.startsWith(target));
-  if (byId) return byId;
-  return null;
-}
-
-/** Parse LLM output into named sections by ## headers. */
-function parseSections(text: string): Map<string, string> {
-  const map = new Map<string, string>();
-  const parts = text.split(/^##\s+/m);
-  for (const part of parts) {
-    const newline = part.indexOf('\n');
-    if (newline < 0) continue;
-    const header = part.slice(0, newline).trim();
-    const body = part.slice(newline + 1).trim();
-    if (header && body) map.set(header, body);
-  }
-  return map;
-}
-
-function printSection(label: SectionName, body: string): void {
-  const icon: Record<SectionName, string> = {
-    'Root Cause':    '🔍',
-    'Risk':          '⚠️ ',
-    'How to Fix':    '🔧',
-    'Example':       '📝',
-    'When to Suppress': '✅',
-  };
-  console.log(`\n${fmt('bold', `${icon[label]}  ${label}`)}`);
-  console.log(fmt('dim', '─'.repeat(50)));
-  console.log(body);
-}
-
-export async function runExplain(options: ExplainCommandOptions = {}): Promise<number> {
-  const cwd = options.cwd ?? process.cwd();
-  const configPath = options.configPath ?? path.join(cwd, 'guardrail.config.yaml');
-
-  const findings = loadCachedFindings(cwd);
-  if (findings.length === 0) {
-    console.log(fmt('yellow', '[explain] No cached findings — run `guardrail run` or `guardrail scan` first.'));
-    return 0;
-  }
-
-  let finding: Finding | null = null;
-
-  if (options.target) {
-    finding = pickFinding(findings, options.target);
-    if (!finding) {
-      console.error(fmt('red', `[explain] No finding matching "${options.target}"`));
-      console.error(fmt('dim', '  Use file:line, finding index (1–' + findings.length + '), or rule id'));
-      return 1;
-    }
-  } else {
-    // No target — list findings and prompt
-    console.log(`\n${fmt('bold', '[explain]')} ${findings.length} cached finding${findings.length !== 1 ? 's' : ''}:\n`);
-    findings.forEach((f, i) => {
-      const sev = f.severity === 'critical' ? fmt('red', 'CRIT') : f.severity === 'warning' ? fmt('yellow', 'WARN') : fmt('dim', 'NOTE');
-      const loc = f.file !== '<unspecified>' ? fmt('dim', ` ${f.file}${f.line ? `:${f.line}` : ''}`) : '';
-      console.log(`  ${String(i + 1).padStart(2)}. [${sev}]${loc} ${f.message.slice(0, 70)}`);
-    });
-    console.log(fmt('dim', '\n  Run: guardrail explain <index|file:line|rule-id>\n'));
-    return 0;
-  }
-
-  // Load engine
-  let engine;
-  try {
-    const config = fs.existsSync(configPath) ? await loadConfig(configPath) : { configVersion: 1 as const };
-    const ref = typeof config.reviewEngine === 'string' ? config.reviewEngine
-      : (config.reviewEngine?.adapter ?? 'auto');
-    engine = await loadAdapter({ point: 'review-engine', ref,
-      options: typeof config.reviewEngine === 'object' ? config.reviewEngine.options : undefined });
-  } catch (err) {
-    console.error(fmt('red', `[explain] Could not load review engine: ${err instanceof Error ? err.message : String(err)}`));
-    return 1;
-  }
-
-  // Read file context
-  let codeContext = '';
-  if (finding.file && finding.file !== '<unspecified>' && finding.file !== '<pipeline>' && finding.line) {
-    const absPath = path.resolve(cwd, finding.file);
-    if (fs.existsSync(absPath)) {
-      const lines = fs.readFileSync(absPath, 'utf8').split('\n');
-      const lineIdx = finding.line - 1;
-      const start = Math.max(0, lineIdx - CONTEXT_LINES);
-      const end = Math.min(lines.length - 1, lineIdx + CONTEXT_LINES);
-      const numbered = lines.slice(start, end + 1).map((l, i) => {
-        const n = start + i + 1;
-        return `${n === finding!.line ? '>>>' : '   '} ${String(n).padStart(4)}: ${l}`;
-      }).join('\n');
-      codeContext = `\n\nRelevant code from ${finding.file} (>>> marks the finding):\n\`\`\`\n${numbered}\n\`\`\``;
-    }
-  }
-
-  const prompt = [
-    `I need a structured explanation of this code finding:`,
-    ``,
-    `Rule:     ${finding.id}`,
-    `Severity: ${finding.severity.toUpperCase()}`,
-    `File:     ${finding.file}${finding.line ? `:${finding.line}` : ''}`,
-    `Message:  ${finding.message}`,
-    finding.suggestion ? `Suggestion: ${finding.suggestion}` : '',
-    codeContext,
-    ``,
-    `Respond using EXACTLY these five section headers (no other headers):`,
-    ``,
-    `## Root Cause`,
-    `[technical explanation of why this problem exists]`,
-    ``,
-    `## Risk`,
-    `[real-world impact, exploitability, and severity rationale]`,
-    ``,
-    `## How to Fix`,
-    `[concrete, code-level remediation steps]`,
-    ``,
-    `## Example`,
-    `[before/after code snippet showing the fix, in a fenced code block]`,
-    ``,
-    `## When to Suppress`,
-    `[legitimate cases where this finding can be safely ignored]`,
-  ].filter(s => s !== undefined && s !== null).join('\n');
-
-  const sev = finding.severity === 'critical' ? fmt('red', 'CRITICAL')
-    : finding.severity === 'warning' ? fmt('yellow', 'WARNING') : fmt('dim', 'NOTE');
-
-  console.log(`\n${fmt('bold', '[explain]')}`);
-  console.log(`  [${sev}] ${fmt('dim', `${finding.file}${finding.line ? `:${finding.line}` : ''}`)} — ${finding.message}`);
-  if (finding.suggestion) console.log(`  ${fmt('dim', `→ ${finding.suggestion}`)}`);
-  console.log('');
-
-  try {
-    const output = await (engine as unknown as ReviewEngine).review({ content: prompt, kind: 'file-batch' });
-    const text = output.rawOutput.trim();
-    const sections = parseSections(text);
-
-    let printed = false;
-    for (const label of SECTION_ORDER) {
-      const body = sections.get(label);
-      if (body) {
-        printSection(label, body);
-        printed = true;
-      }
-    }
-
-    if (!printed) {
-      // LLM didn't follow the structure — print raw
-      console.log(text);
-    }
-
-    console.log('');
-  } catch (err) {
-    console.error(fmt('red', `[explain] LLM error: ${err instanceof Error ? err.message : String(err)}`));
-    return 1;
-  }
-
-  return 0;
-}