@kernlang/cli 2.0.0 → 3.1.0

package/dist/cli.js

@@ -2,16 +2,18 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from 'fs';
 import { resolve, basename, dirname, relative } from 'path';
 import { createJiti } from 'jiti';
-import { parse, decompile, resolveConfig, VALID_TARGETS, VALID_STRUCTURES, generateCoreNode, isCoreNode, detectVersionsFromPackageJson, scanProject, generateConfigSource, formatScanSummary, registerTemplate, isTemplateNode, expandTemplateNode, clearTemplates, detectTemplates, COMMON_TEMPLATES } from '@kernlang/core';
+import { parse, decompile, resolveConfig, VALID_TARGETS, VALID_STRUCTURES, generateCoreNode, isCoreNode, detectVersionsFromPackageJson, scanProject, generateConfigSource, formatScanSummary, registerTemplate, isTemplateNode, expandTemplateNode, clearTemplates, detectTemplates, COMMON_TEMPLATES, collectCoverageGaps, writeCoverageGaps, NODE_TYPES } from '@kernlang/core';
 import { generateReactNode, isReactNode } from '@kernlang/react';
 import { transpile } from '@kernlang/native';
 import { transpileWeb, transpileTailwind, transpileNextjs } from '@kernlang/react';
 import { transpileExpress } from '@kernlang/express';
+import { transpileFastAPI } from '@kernlang/fastapi';
 import { transpileCliApp } from './transpiler-cli.js';
-import { transpileTerminal } from '@kernlang/terminal';
+import { transpileTerminal, transpileInk } from '@kernlang/terminal';
 import { transpileVue, transpileNuxt } from '@kernlang/vue';
 import { collectLanguageMetrics } from '@kernlang/metrics';
-import { reviewFile, reviewDirectory, formatReport, formatSummary, checkEnforcement, formatEnforcement, exportKernIR, buildLLMPrompt, dedup, runESLint, runTSCDiagnosticsFromPaths, linkToNodes } from '@kernlang/review';
+import { reviewFile, reviewGraph, resolveImportGraph, formatReport, formatSARIF, formatSummary, checkEnforcement, formatEnforcement, exportKernIR, buildLLMPrompt, dedup, runESLint, runTSCDiagnosticsFromPaths, linkToNodes, runLLMReview, isLLMAvailable, analyzeTaint, checkSpecFiles, specViolationsToFindings } from '@kernlang/review';
+import { evolve, loadBuiltinDetectors, listStaged, updateStagedStatus, promoteLocal, cleanRejected, formatSplitView, loadEvolvedNodes, runGoldenTests, formatGoldenTestResults, rollbackNode, restoreNode, readEvolvedManifest, buildDiscoveryPrompt, parseDiscoveryResponse, selectRepresentativeFiles, collectTsFiles, estimateTokens, createLLMProvider, TokenBudget, validateEvolveProposal, graduateNode, compileCodegenToJS, stageEvolveV4Proposal, listStagedEvolveV4, getStagedEvolveV4, updateStagedEvolveV4Status, cleanRejectedEvolveV4, cleanApprovedEvolveV4, formatEvolveV4SplitView, promoteNode, pruneNodes, detectCollisions, renameEvolvedNode, readNodeDefinition, buildBackfillPrompt, buildRetryPrompt, rebuildEvolvedManifest } from '@kernlang/evolve';
 const args = process.argv.slice(2);
 const GENERATED_HEADER = '// Generated by KERN — do not edit. Source: ';
 // ── kern dev <dir|file> [--target=...] [--outdir=...] ─────────────────
@@ -57,10 +59,17 @@ if (args[0] === 'dev') {
                 console.log(`  Auto-detected: ${parts.join(', ')}`);
             }
         }
-        catch { }
+        catch {
+            // Intentional: package.json detection is optional — build continues without it
+        }
     }
     // Load templates before compilation
     loadTemplates(devConfig);
+    // Load evolved nodes (v4) — graduated nodes from .kern/evolved/
+    const evolvedResult = loadEvolvedNodes(process.cwd(), args.includes('--verify'));
+    if (evolvedResult.loaded > 0) {
+        console.log(`  Evolved nodes: ${evolvedResult.loaded} loaded`);
+    }
     console.log(`\n  KERN dev — watching for changes`);
     console.log(`  Target: ${devConfig.target}`);
     console.log(`  Watch:  ${relative(process.cwd(), watchDir) || '.'}`);
@@ -68,7 +77,7 @@ if (args[0] === 'dev') {
     // Initial build of all .kern files
     const initialFiles = findKernFiles(watchDir, watchPattern);
     for (const file of initialFiles) {
-        transpileAndWrite(file, devConfig, devOutDir);
+        transpileAndWrite(file, devConfig, devOutDir, watchDir);
     }
     if (initialFiles.length > 0) {
         console.log(`  ${initialFiles.length} file(s) compiled.\n`);
@@ -86,7 +95,7 @@ if (args[0] === 'dev') {
             const rel = relative(process.cwd(), filePath);
             const start = performance.now();
             try {
-                transpileAndWrite(filePath, devConfig, devOutDir);
+                transpileAndWrite(filePath, devConfig, devOutDir, watchDir);
                 const ms = Math.round(performance.now() - start);
                 console.log(`  ${rel} → compiled (${ms}ms)`);
             }
@@ -98,7 +107,7 @@ if (args[0] === 'dev') {
             const rel = relative(process.cwd(), filePath);
             const start = performance.now();
             try {
-                transpileAndWrite(filePath, devConfig, devOutDir);
+                transpileAndWrite(filePath, devConfig, devOutDir, watchDir);
                 const ms = Math.round(performance.now() - start);
                 console.log(`  ${rel} → compiled (${ms}ms)`);
             }
@@ -110,9 +119,12 @@ if (args[0] === 'dev') {
             const rel = relative(process.cwd(), filePath);
             const ext = filePath.endsWith('.kern') ? '.kern' : '.ir';
             const fileBaseName = basename(filePath, ext);
-            const outDir = resolve(devOutDir ? resolve(devOutDir) : dirname(filePath), devConfig.output.outDir);
-            const outExt = (devConfig.target === 'vue' || devConfig.target === 'nuxt') ? '.vue'
-                : (devConfig.target === 'express' || devConfig.target === 'cli' || devConfig.target === 'terminal') ? '.ts' : '.tsx';
+            const unlinkRelDir = relative(resolve(watchDir), dirname(filePath));
+            const unlinkBaseDir = devOutDir ? resolve(resolve(devOutDir), unlinkRelDir) : dirname(filePath);
+            const outDir = resolve(unlinkBaseDir, devConfig.output.outDir);
+            const outExt = devConfig.target === 'fastapi' ? '.py'
+                : (devConfig.target === 'vue' || devConfig.target === 'nuxt') ? '.vue'
+                    : (devConfig.target === 'express' || devConfig.target === 'cli' || devConfig.target === 'terminal') ? '.ts' : '.tsx';
             const outFile = resolve(outDir, `${fileBaseName}${outExt}`);
             try {
                 if (existsSync(outFile)) {
@@ -169,7 +181,7 @@ function findKernFiles(dir, singleFile) {
     walk(dir);
     return files;
 }
-function transpileAndWrite(file, cfg, outDirOverride) {
+function transpileAndWrite(file, cfg, outDirOverride, inputBase) {
     const source = readFileSync(file, 'utf-8');
     const ast = parse(source);
     const ext = file.endsWith('.kern') ? '.kern' : '.ir';
@@ -177,6 +189,13 @@ function transpileAndWrite(file, cfg, outDirOverride) {
     const target = cfg.target;
     const relSource = relative(process.cwd(), file);
     const header = GENERATED_HEADER + relSource + '\n\n';
+    // Emit coverage gaps unless --no-gaps
+    if (!args.includes('--no-gaps')) {
+        const gaps = collectCoverageGaps(ast, file);
+        if (gaps.length > 0) {
+            writeCoverageGaps(gaps, resolve(process.cwd(), '.kern-gaps'));
+        }
+    }
     const result = target === 'native'
         ? transpile(ast, cfg)
         : target === 'web'
@@ -185,16 +204,24 @@ function transpileAndWrite(file, cfg, outDirOverride) {
                 ? transpileTailwind(ast, cfg)
                 : target === 'express'
                     ? transpileExpress(ast, cfg)
-                    : target === 'cli'
-                        ? transpileCliApp(ast, cfg)
-                        : target === 'terminal'
-                            ? transpileTerminal(ast, cfg)
-                            : target === 'vue'
-                                ? transpileVue(ast, cfg)
-                                : target === 'nuxt'
-                                    ? transpileNuxt(ast, cfg)
-                                    : transpileNextjs(ast, cfg);
-    const outDir = resolve(outDirOverride ? resolve(outDirOverride) : dirname(file), cfg.output.outDir);
+                    : target === 'fastapi'
+                        ? transpileFastAPI(ast, cfg)
+                        : target === 'cli'
+                            ? transpileCliApp(ast, cfg)
+                            : target === 'terminal'
+                                ? transpileTerminal(ast, cfg)
+                                : target === 'ink'
+                                    ? transpileInk(ast, cfg)
+                                    : target === 'vue'
+                                        ? transpileVue(ast, cfg)
+                                        : target === 'nuxt'
+                                            ? transpileNuxt(ast, cfg)
+                                            : transpileNextjs(ast, cfg);
+    // Preserve relative directory structure when outDirOverride is set
+    // e.g. kern/llm/patterns.kern with --outdir=app/ → app/llm/page.tsx (not app/page.tsx)
+    const relDir = inputBase ? relative(resolve(inputBase), dirname(file)) : '';
+    const baseDir = outDirOverride ? resolve(resolve(outDirOverride), relDir) : dirname(file);
+    const outDir = resolve(baseDir, cfg.output.outDir);
     mkdirSync(outDir, { recursive: true });
     if (result.artifacts && result.artifacts.length > 0 && cfg.structure !== 'flat') {
         for (const artifact of result.artifacts) {
@@ -204,14 +231,18 @@ function transpileAndWrite(file, cfg, outDirOverride) {
         }
     }
     else {
-        const outExt = (target === 'vue' || target === 'nuxt') ? '.vue'
-            : (target === 'express' || target === 'cli' || target === 'terminal') ? '.ts' : '.tsx';
+        const outExt = target === 'fastapi' ? '.py'
+            : (target === 'vue' || target === 'nuxt') ? '.vue'
+                : (target === 'express' || target === 'cli' || target === 'terminal') ? '.ts'
+                    : '.tsx';
         // For Next.js target, use the file convention name from the transpiler result (page.tsx, layout.tsx, etc.)
         const resultWithFiles = result;
         const outFileName = (target === 'nextjs' && resultWithFiles.files && resultWithFiles.files.length > 0)
             ? resultWithFiles.files[0].path
             : `${name}${outExt}`;
-        writeFileSync(resolve(outDir, outFileName), header + result.code);
+        const outFilePath = resolve(outDir, outFileName);
+        mkdirSync(dirname(outFilePath), { recursive: true });
+        writeFileSync(outFilePath, header + result.code);
         if (result.artifacts) {
             for (const artifact of result.artifacts) {
                 const artifactPath = resolve(outDir, artifact.path);
@@ -232,10 +263,41 @@ function loadConfig() {
         }
         catch (err) {
             console.error(`Warning: Failed to load kern.config.ts: ${err.message}`);
-            return resolveConfig({});
         }
     }
-    return resolveConfig({});
+    // No kern.config.ts — auto-detect target from package.json
+    const autoDetected = autoDetectTarget();
+    return resolveConfig(autoDetected ? { target: autoDetected } : {});
+}
+function autoDetectTarget() {
+    const pkgPath = resolve(process.cwd(), 'package.json');
+    if (!existsSync(pkgPath))
+        return null;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+        // Priority: most specific first
+        if (allDeps['next'])
+            return 'nextjs';
+        if (allDeps['nuxt'])
+            return 'nuxt';
+        if (allDeps['vue'])
+            return 'vue';
+        if (allDeps['react-native'])
+            return 'native';
+        if (allDeps['fastapi'] || allDeps['flask'] || allDeps['django'])
+            return 'express'; // Python web → express rules are closest
+        if (allDeps['express'] || allDeps['fastify'] || allDeps['koa'] || allDeps['hono'])
+            return 'express';
+        if (allDeps['tailwindcss'] && allDeps['react'])
+            return 'tailwind';
+        if (allDeps['react'])
+            return 'web';
+        return null;
+    }
+    catch {
+        return null;
+    }
 }
 function loadTemplates(cfg) {
     clearTemplates();
@@ -448,17 +510,42 @@ if (args[0] === 'init-templates') {
     console.log('');
     process.exit(0);
 }
-// ── kern review <file|dir|--diff base> [--json] [--recursive] [--enforce] [--min-coverage=N] [--export-kern] [--llm] [--fix] [--lint] ──
+// ── kern review <file|dir|--diff base> [--json] [--sarif] [--recursive] [--enforce] [--min-coverage=N] [--max-complexity=N] [--export-kern] [--llm] [--fix] [--lint] ──
 if (args[0] === 'review') {
     const jsonOutput = args.includes('--json');
+    const sarifOutput = args.includes('--sarif') || args.includes('--format=sarif');
     const recursive = args.includes('--recursive') || args.includes('-r');
     const enforce = args.includes('--enforce');
     const exportKern = args.includes('--export-kern');
     const llmMode = args.includes('--llm');
+    const cloudMode = args.includes('--cloud');
+    const securityMode = args.includes('--security');
+    const mcpMode = args.includes('--mcp');
+    const specMode = args.includes('--spec');
+    const specFile = args.find(a => a.endsWith('.kern') && a !== 'review');
     const fixMode = args.includes('--fix');
     const lintMode = args.includes('--lint');
+    const graphMode = args.includes('--graph');
+    const batchMode = args.includes('--batch');
+    const maxDepthArg = args.find(a => a.startsWith('--max-depth='))?.split('=')[1];
+    const maxDepth = maxDepthArg ? Number(maxDepthArg) : 3;
+    const batchSizeArg = args.find(a => a.startsWith('--batch-size='))?.split('=')[1];
+    const batchSize = batchSizeArg ? Number(batchSizeArg) : 20;
+    const tsconfigPath = args.find(a => a.startsWith('--tsconfig='))?.split('=')[1];
     const minCoverageArg = args.find(a => a.startsWith('--min-coverage='))?.split('=')[1];
     const minCoverage = minCoverageArg ? Number(minCoverageArg) : undefined;
+    const maxComplexityArg = args.find(a => a.startsWith('--max-complexity='))?.split('=')[1];
+    const maxComplexity = maxComplexityArg ? Number(maxComplexityArg) : 15;
+    const maxErrorsArg = args.find(a => a.startsWith('--max-errors='))?.split('=')[1];
+    const maxErrors = maxErrorsArg ? Number(maxErrorsArg) : 0;
+    const maxWarningsArg = args.find(a => a.startsWith('--max-warnings='))?.split('=')[1];
+    const maxWarnings = maxWarningsArg ? Number(maxWarningsArg) : undefined;
+    const showConfidence = args.includes('--confidence');
+    const minConfidenceArg = args.find(a => a.startsWith('--min-confidence='))?.split('=')[1];
+    const minConfidence = minConfidenceArg ? Number(minConfidenceArg) : undefined;
+    const disableRuleArgs = args.filter(a => a.startsWith('--disable-rule=')).map(a => a.split('=')[1]);
+    const strictArg = args.find(a => a === '--strict' || a.startsWith('--strict='));
+    const strict = strictArg === '--strict' ? 'inline' : strictArg === '--strict=all' ? 'all' : false;
     const diffBase = args.find(a => a.startsWith('--diff'))
         ? (args.find(a => a.startsWith('--diff='))?.split('=')[1] || args[args.indexOf('--diff') + 1] || 'origin/main')
         : undefined;
@@ -467,8 +554,9 @@ if (args[0] === 'review') {
     let reviewInput = reviewInputs[0];
     if (diffBase && !reviewInput) {
         try {
-            const { execSync } = await import('child_process');
-            const diffFiles = execSync(`git diff --name-only --diff-filter=ACMR ${diffBase}`, { encoding: 'utf-8' })
+            const { execFileSync } = await import('child_process');
+            const sanitizedBase = diffBase.replace(/[^a-zA-Z0-9_.\/\-~]/g, '');
+            const diffFiles = execFileSync('git', ['diff', '--name-only', '--diff-filter=ACMR', sanitizedBase], { encoding: 'utf-8' })
                 .trim()
                 .split('\n')
                 .filter(f => f.endsWith('.ts') || f.endsWith('.tsx'))
@@ -488,7 +576,8 @@ if (args[0] === 'review') {
         }
     }
     if (!reviewInput) {
-        console.error('Usage: kern review <file.ts|dir> [--diff base] [--json] [--recursive] [--enforce] [--min-coverage=N] [--export-kern] [--llm] [--fix]');
+        console.error('Usage: kern review <file.ts|dir> [--security] [--mcp] [--llm] [--spec file.kern] [--cloud]');
+        console.error('       [--diff base] [--json] [--sarif] [--recursive] [--enforce] [--fix]');
         process.exit(1);
     }
     // Skip stat check for --diff mode (files are resolved individually below)
@@ -501,12 +590,29 @@ if (args[0] === 'review') {
         }
     }
     // Load kern.config.ts to get registered templates and target
+    // Auto-detects target from package.json if no config exists
     const reviewCfg = loadConfig();
+    if (!jsonOutput && !sarifOutput) {
+        const configExists = existsSync(resolve(process.cwd(), 'kern.config.ts'));
+        if (!configExists) {
+            console.log(`  Target: ${reviewCfg.target} (auto-detected from package.json)`);
+        }
+    }
+    // Merge disabledRules from config + CLI flags
+    const cfgDisabledRules = reviewCfg.review.disabledRules ?? [];
+    const mergedDisabledRules = [...new Set([...cfgDisabledRules, ...disableRuleArgs])];
     const reviewConfig = {
         registeredTemplates: [],
         minCoverage: minCoverage ?? 0,
         enforceTemplates: enforce,
+        maxComplexity: maxComplexity ?? reviewCfg.review.maxComplexity,
+        maxErrors,
+        maxWarnings,
         target: reviewCfg.target,
+        showConfidence: showConfidence || reviewCfg.review.showConfidence,
+        minConfidence: minConfidence ?? reviewCfg.review.minConfidence,
+        disabledRules: mergedDisabledRules.length > 0 ? mergedDisabledRules : undefined,
+        strict,
     };
     // Load templates and collect their names
     if (reviewCfg.templates && reviewCfg.templates.length > 0) {
@@ -538,7 +644,9 @@ if (args[0] === 'review') {
                         registerTemplate(node, file);
                     }
                 }
-                catch { }
+                catch (e) {
+                    console.error(`  Warning: Failed to parse template ${basename(file)}: ${e.message}`);
+                }
             }
         }
         if (reviewConfig.registeredTemplates.length > 0) {
@@ -547,20 +655,13 @@ if (args[0] === 'review') {
     }
     // Collect reports from diff, directory, or single file
     let reports = [];
+    // Collect entry file paths for --graph mode
+    let entryFilePaths = [];
     if (reviewInput === '__diff__') {
         const diffFiles = globalThis.__diffFiles;
-        for (const f of diffFiles) {
-            const fullPath = resolve(f);
-            if (existsSync(fullPath)) {
-                try {
-                    reports.push(reviewFile(fullPath, reviewConfig));
-                }
-                catch { }
-            }
-        }
+        entryFilePaths = diffFiles.map(f => resolve(f)).filter(f => existsSync(f));
     }
     else {
-        // Support multiple positional paths: kern review file1.ts file2.ts dir/
         const paths = reviewInputs.length > 0 ? reviewInputs : [reviewInput];
         for (const p of paths) {
             const rPath = resolve(p);
@@ -568,20 +669,78 @@ if (args[0] === 'review') {
                 continue;
             const rStat = statSync(rPath);
             if (rStat.isDirectory()) {
-                reports.push(...reviewDirectory(rPath, recursive, reviewConfig));
+                // Collect files from directory for graph seeding
+                entryFilePaths.push(...collectTsFilesFlat(rPath, recursive));
             }
             else {
+                entryFilePaths.push(rPath);
+            }
+        }
+    }
+    if (graphMode && entryFilePaths.length > 0) {
+        // --graph: resolve import graph, review all files with provenance
+        const graphOpts = { maxDepth, tsConfigFilePath: tsconfigPath ? resolve(tsconfigPath) : undefined };
+        const graph = resolveImportGraph(entryFilePaths, graphOpts);
+        console.log(`  Graph: ${graph.totalFiles} files resolved (${graph.skipped} skipped, depth ${maxDepth})`);
+        reports = reviewGraph(entryFilePaths, reviewConfig, graphOpts);
+    }
+    else if (batchMode && entryFilePaths.length > batchSize) {
+        // --batch: process in chunks for large repos
+        const totalBatches = Math.ceil(entryFilePaths.length / batchSize);
+        for (let i = 0; i < entryFilePaths.length; i += batchSize) {
+            const batch = entryFilePaths.slice(i, i + batchSize);
+            const batchNum = Math.floor(i / batchSize) + 1;
+            for (const f of batch) {
                 try {
-                    reports.push(reviewFile(rPath, reviewConfig));
+                    reports.push(reviewFile(f, reviewConfig));
+                }
+                catch (e) {
+                    console.error(`  Review error in ${f}: ${e.message}`);
                 }
-                catch { }
+            }
+            const batchFindings = reports.slice(-batch.length).reduce((sum, r) => sum + r.findings.length, 0);
+            console.log(`  Batch ${batchNum}/${totalBatches}: ${batch.length} files reviewed (${batchFindings} findings)`);
+        }
+    }
+    else {
+        // Standard mode: review each file individually
+        for (const f of entryFilePaths) {
+            try {
+                reports.push(reviewFile(f, reviewConfig));
+            }
+            catch (e) {
+                console.error(`  Review error in ${f}: ${e.message}`);
             }
         }
     }
     if (reports.length === 0) {
-        console.log('  No .ts/.tsx files found to review.');
+        console.log('  No reviewable files found (.ts/.tsx/.py/.kern).');
         process.exit(0);
     }
+    // MCP security review — --mcp flag or auto-detect MCP server files
+    try {
+        const { reviewIfMCP, reviewMCPSource } = await import('@kernlang/review-mcp');
+        let mcpFileCount = 0;
+        for (const report of reports) {
+            const source = readFileSync(report.filePath, 'utf-8');
+            const mcpFindings = mcpMode
+                ? reviewMCPSource(source, report.filePath)
+                : reviewIfMCP(source, report.filePath);
+            if (mcpFindings && mcpFindings.length > 0) {
+                report.findings.push(...mcpFindings);
+                mcpFileCount++;
+            }
+        }
+        if (mcpFileCount > 0 && !jsonOutput && !sarifOutput) {
+            console.log(`  MCP security: ${mcpFileCount} server file(s) scanned`);
+        }
+    }
+    catch {
+        // @kernlang/review-mcp not installed — skip silently
+        if (mcpMode) {
+            console.error('  @kernlang/review-mcp not installed. Run: pnpm add @kernlang/review-mcp');
+        }
+    }
     // --export-kern: output KERN IR for AI review (v1 compat)
     if (exportKern) {
         for (const report of reports) {
@@ -590,15 +749,186 @@ if (args[0] === 'review') {
         }
         process.exit(0);
     }
-    // --llm: output structured LLM prompt with nodeId aliases
-    if (llmMode) {
+    // --spec: verify .kern spec contracts against .ts implementation
+    if (specMode && specFile) {
+        const kernFilePath = resolve(specFile);
+        if (!existsSync(kernFilePath)) {
+            console.error(`  .kern spec file not found: ${specFile}`);
+            process.exit(1);
+        }
+        console.log(`\n  KERN spec check: ${specFile} → ${reports.length} implementation files\n`);
+        let totalViolations = 0;
         for (const report of reports) {
-            console.log(`\n// ── ${report.filePath} ──`);
-            console.log(buildLLMPrompt(report.inferred, report.templateMatches));
+            const result = checkSpecFiles(kernFilePath, report.filePath);
+            if (result.violations.length > 0) {
+                const findings = specViolationsToFindings(result);
+                totalViolations += findings.length;
+                report.findings.push(...findings);
+                report.findings = dedup(report.findings);
+                for (const v of result.violations) {
+                    const icon = v.kind.includes('missing') || v.kind === 'spec-unimplemented' ? '✗' : '~';
+                    const sev = v.kind === 'spec-auth-missing' || v.kind === 'spec-unimplemented' ? 'ERROR' : v.kind === 'spec-undeclared' ? 'INFO' : 'WARN';
+                    console.log(`    ${icon} [${sev}] ${v.kind}: ${v.detail}`);
+                    if (v.suggestion)
+                        console.log(`      → ${v.suggestion}`);
+                }
+            }
+            if (result.matched.length > 0) {
+                const satisfied = result.matched.length - result.violations.filter(v => v.kind !== 'spec-undeclared' && v.kind !== 'spec-unimplemented').length;
+                console.log(`\n  Matched: ${result.matched.length} routes | Satisfied: ${satisfied} | Violations: ${totalViolations}`);
+                if (result.unmatchedSpecs.length > 0)
+                    console.log(`  Unimplemented: ${result.unmatchedSpecs.map(s => s.routeKey).join(', ')}`);
+                if (result.unmatchedImpls.length > 0)
+                    console.log(`  Undeclared: ${result.unmatchedImpls.map(i => i.routeKey).join(', ')}`);
+            }
+        }
+        if (totalViolations === 0) {
+            console.log('  All spec contracts satisfied.');
+        }
+        console.log('');
+        // Fall through to normal output
+    }
+    // --security: show only security-related findings
+    if (securityMode) {
+        const SECURITY_RULES = new Set([
+            'xss-unsafe-html', 'hardcoded-secret', 'command-injection', 'no-eval',
+            'insecure-random', 'cors-wildcard', 'helmet-missing', 'open-redirect',
+            'jwt-weak-verification', 'cookie-hardening', 'csrf-detection', 'csp-strength',
+            'path-traversal', 'weak-password-hashing', 'regex-dos', 'missing-input-validation',
+            'prototype-pollution', 'information-exposure', 'prompt-injection',
+            'taint-command', 'taint-fs', 'taint-sql', 'taint-redirect', 'taint-eval',
+            'taint-insufficient-sanitizer', 'taint-crossfile-command', 'taint-crossfile-fs',
+            'taint-crossfile-sql', 'taint-crossfile-redirect', 'taint-crossfile-eval',
+            'spec-auth-missing', 'spec-validate-missing', 'spec-guard-missing',
+            'spec-middleware-missing', 'spec-unimplemented',
+        ]);
+        console.log('\n  KERN Security Report\n');
+        let totalSec = 0;
+        for (const report of reports) {
+            const secFindings = report.findings.filter(f => SECURITY_RULES.has(f.ruleId));
+            if (secFindings.length === 0)
+                continue;
+            totalSec += secFindings.length;
+            const rel = relative(process.cwd(), report.filePath);
+            console.log(`  ${rel}:`);
+            for (const f of secFindings) {
+                const icon = f.severity === 'error' ? '✗' : f.severity === 'warning' ? '~' : '-';
+                console.log(`    ${icon} L${f.primarySpan.startLine}: [${f.ruleId}] ${f.message}`);
+                if (f.suggestion)
+                    console.log(`      → ${f.suggestion}`);
+            }
+            console.log('');
+        }
+        if (totalSec === 0) {
+            console.log('  No security issues found.');
         }
-        console.log('\n// Paste the JSON response from your AI to validate and map findings back to TS.');
+        else {
+            const errors = reports.flatMap(r => r.findings).filter(f => SECURITY_RULES.has(f.ruleId) && f.severity === 'error').length;
+            const warnings = reports.flatMap(r => r.findings).filter(f => SECURITY_RULES.has(f.ruleId) && f.severity === 'warning').length;
+            console.log(`  Total: ${totalSec} security findings (${errors} errors, ${warnings} warnings)`);
+        }
+        console.log('  Rules: OWASP Top 10, OWASP LLM Top 10, Taint Tracking, Spec Contracts');
+        console.log('');
+        process.exit(0);
+    }
+    // --cloud: KERN Pro cloud review (coming soon)
+    if (cloudMode) {
+        console.log('');
+        console.log('  KERN Pro — Cloud-powered AI review');
+        console.log('');
+        console.log('  Coming soon. Cloud review will provide:');
+        console.log('    • LLM-powered security analysis without an AI IDE');
+        console.log('    • Team dashboard with trend tracking');
+        console.log('    • Custom rule engine for enterprise');
+        console.log('    • CI/CD integration with quality gates');
+        console.log('');
+        console.log('  For now, use --llm with your AI assistant (Claude Code, Cursor, etc.)');
+        console.log('  The assistant reads the KERN IR output and performs the AI review.');
+        console.log('');
+        console.log('  → kern review src/ --llm');
+        console.log('');
+        console.log('  Join the waitlist: https://kernlang.dev/pro');
+        console.log('');
         process.exit(0);
     }
+    // --llm: LLM-assisted security review (batch file check)
+    if (llmMode) {
+        // Build graph context for LLM markers if --graph is active
+        const llmGraphContext = graphMode ? (() => {
+            const fileDistances = new Map();
+            for (const report of reports) {
+                const finding = report.findings[0];
+                const distance = finding?.distance ?? 0;
+                fileDistances.set(report.filePath, distance);
+            }
+            for (const ep of entryFilePaths) {
+                fileDistances.set(ep, 0);
+            }
+            return { fileDistances };
+        })() : undefined;
+        if (isLLMAvailable()) {
+            // Phase 3: actual LLM API call with taint context
+            console.log('  LLM review: calling API...');
+            const llmInputs = reports.map(report => ({
+                filePath: report.filePath,
+                inferred: report.inferred,
+                templateMatches: report.templateMatches,
+                taintResults: analyzeTaint(report.inferred, report.filePath),
+                graphContext: llmGraphContext,
+            }));
+            try {
+                const llmFindings = await runLLMReview(llmInputs);
+                console.log(`  LLM review: ${llmFindings.length} findings from AI`);
+                // Merge LLM findings into reports
+                for (const f of llmFindings) {
+                    const report = reports.find(r => r.filePath === f.primarySpan.file);
+                    if (report) {
+                        report.findings.push(f);
+                    }
+                    else if (reports.length > 0) {
+                        reports[0].findings.push(f);
+                    }
+                }
+                // Dedup after merge
+                for (const report of reports) {
+                    report.findings = dedup(report.findings);
+                }
+            }
+            catch (err) {
+                console.error(`  LLM review failed: ${err.message}`);
+            }
+            // Fall through to normal output (don't exit — show merged findings)
+        }
+        else {
+            // No cloud API key — output static findings + KERN IR for the AI assistant
+            // The LLM running this command (Claude Code, Cursor, etc.) IS the reviewer
+            console.log('\n  ── KERN IR for LLM review ──\n');
+            for (const report of reports) {
+                console.log(`// ── ${report.filePath} ──`);
+                console.log(buildLLMPrompt(report.inferred, report.templateMatches, llmGraphContext));
+                // Include taint analysis context
+                const taintResults = analyzeTaint(report.inferred, report.filePath);
+                if (taintResults.length > 0) {
+                    console.log('\n// Taint analysis:');
+                    for (const t of taintResults) {
+                        for (const p of t.paths) {
+                            const status = p.sanitized ? `SANITIZED (${p.sanitizer})` : 'UNSANITIZED';
+                            console.log(`//   ${t.fnName}: ${p.source.origin} → ${p.sink.name}() [${status}]`);
+                        }
+                    }
+                }
+                console.log('');
+            }
+            // Show static findings summary
+            const totalFindings = reports.reduce((sum, r) => sum + r.findings.length, 0);
+            const errors = reports.reduce((sum, r) => sum + r.findings.filter(f => f.severity === 'error').length, 0);
+            const warnings = reports.reduce((sum, r) => sum + r.findings.filter(f => f.severity === 'warning').length, 0);
+            console.log(`  Static analysis: ${totalFindings} findings (${errors} errors, ${warnings} warnings)`);
+            console.log('  Review the KERN IR above for security issues the static rules may have missed.');
+            console.log('');
+        }
+        // Fall through to normal output — show full report with static findings
+    }
     // --fix: auto-migration — write .kern files from template suggestions, verify roundtrip
     if (fixMode) {
         let fixed = 0;
@@ -665,30 +995,42 @@ if (args[0] === 'review') {
         }
     }
     if (jsonOutput) {
-        console.log(JSON.stringify(reports.length === 1 ? reports[0] : reports, null, 2));
+        // Include KERN IR + LLM prompt in JSON so the calling AI can review
+        const enriched = reports.map(report => {
+            const llmPrompt = buildLLMPrompt(report.inferred, report.templateMatches);
+            const kernIR = exportKernIR(report.inferred, report.templateMatches);
+            return { ...report, kernIR, llmPrompt };
+        });
+        console.log(JSON.stringify(enriched.length === 1 ? enriched[0] : enriched, null, 2));
+    }
+    else if (sarifOutput) {
+        console.log(formatSARIF(reports));
     }
     else {
         for (const report of reports) {
             console.log('');
-            console.log(formatReport(report));
+            console.log(formatReport(report, reviewConfig));
         }
         if (reports.length > 1) {
             console.log('');
             console.log(formatSummary(reports));
         }
         // Enforcement
-        if (enforce || minCoverage !== undefined) {
+        const hasThresholds = minCoverage !== undefined || maxComplexityArg !== undefined || maxErrorsArg !== undefined || maxWarningsArg !== undefined;
+        if (enforce || hasThresholds) {
             console.log('');
             let allPassed = true;
             for (const report of reports) {
                 const result = checkEnforcement(report, reviewConfig);
                 if (!result.passed) {
                     allPassed = false;
+                    console.log(`  File: ${report.filePath}`);
                     console.log(formatEnforcement(result));
+                    console.log('');
                 }
             }
             if (allPassed) {
-                console.log(`  Enforcement: PASS (all files)`);
+                console.log(`  Enforcement: PASS (all files checked against thresholds)`);
             }
             else {
                 process.exit(1);
@@ -697,6 +1039,886 @@ if (args[0] === 'review') {
     }
     process.exit(0);
 }
+// ── kern evolve <dir|file> [options] ──────────────────────────────────
+if (args[0] === 'evolve' && args[1] !== undefined && !args[1].startsWith('evolve:')) {
+    const evolveInput = args[1];
+    if (!evolveInput || evolveInput.startsWith('--')) {
+        console.error('Usage: kern evolve <dir|file> [--recursive] [--preview] [--min-confidence=N] [--min-support=N] [--json]');
+        process.exit(1);
+    }
+    const evolvePath = resolve(evolveInput);
+    const stat = existsSync(evolvePath) ? statSync(evolvePath) : null;
+    if (!stat) {
+        console.error(`Not found: ${evolveInput}`);
+        process.exit(1);
+    }
+    const recursive = args.includes('--recursive') || args.includes('-r');
+    const preview = args.includes('--preview');
+    const jsonOutput = args.includes('--json');
+    const minConfArg = args.find(a => a.startsWith('--min-confidence='))?.split('=')[1];
+    const minSupportArg = args.find(a => a.startsWith('--min-support='))?.split('=')[1];
+    const enableNodes = args.includes('--nodes') || args.includes('--from-gaps');
+    const evolveOptions = {
+        recursive,
+        preview,
+        enableNodeProposals: enableNodes,
+        thresholds: {
+            ...(minConfArg ? { minConfidence: Number(minConfArg) } : {}),
+            ...(minSupportArg ? { minSupport: Number(minSupportArg) } : {}),
+        },
+    };
+    // Load built-in detectors
+    await loadBuiltinDetectors();
+    console.log(`\n  KERN evolve — scanning for template gaps\n`);
+    console.log(`  Input: ${relative(process.cwd(), evolvePath) || '.'}`);
+    console.log(`  Mode:  ${preview ? 'preview (no staging)' : 'detect + stage'}`);
+    console.log('');
+    const result = evolve(evolvePath, evolveOptions);
+    if (jsonOutput) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        console.log(`  Gaps detected:       ${result.gaps.length}`);
+        if (result.conceptSummary) {
+            console.log(`  ${result.conceptSummary.formatted}`);
+        }
+        console.log(`  Patterns analyzed:   ${result.analyzed.length}`);
+        console.log(`  Templates proposed:  ${result.proposals.length}`);
+        console.log(`  Validated:           ${result.validated.filter(v => v.validation.parseOk && v.validation.expansionOk).length}/${result.validated.length}`);
+        if (!preview && result.staged.length > 0) {
+            console.log(`  Staged for review:   ${result.staged.length}`);
+            console.log(`\n  Run 'kern evolve:review --list' to review proposals.`);
+        }
+        if (result.proposals.length > 0 && !jsonOutput) {
+            console.log('\n  Proposed templates:');
+            for (const p of result.proposals) {
+                const v = result.validated.find(v => v.proposal.id === p.id);
+                const status = v ? (v.validation.parseOk && v.validation.expansionOk ? '✓' : '✗') : '?';
+                console.log(`    ${status} ${p.templateName} (${p.namespace}) — score: ${p.qualityScore.overallScore}, instances: ${p.instanceCount}`);
+            }
+        }
+        // v3: Node proposals
+        if (result.nodeProposals && result.nodeProposals.length > 0 && !jsonOutput) {
+            console.log(`\n  Node proposals (v3): ${result.nodeProposals.length}`);
+            for (const np of result.nodeProposals) {
+                const nv = result.nodeValidated?.find(v => v.proposal.id === np.id);
+                const status = nv ? (nv.validation.parseOk && nv.validation.codegenOk ? '✓' : '✗') : '?';
+                console.log(`    ${status} ${np.nodeName} — express: ${np.expressibilityScore.overall}, freq: ${np.frequency}, score: ${np.qualityScore}`);
+            }
+            if (result.stagedNodes && result.stagedNodes.length > 0) {
+                console.log(`  Staged nodes:        ${result.stagedNodes.length}`);
+            }
+        }
+    }
+    console.log('');
+    process.exit(0);
+}
+// ── kern evolve:review [options] ─────────────────────────────────────
+if (args[0] === 'evolve:review') {
+    const listMode = args.includes('--list') || args.length === 1;
+    const approveId = (() => {
+        const eqArg = args.find(a => a.startsWith('--approve='));
+        if (eqArg)
+            return eqArg.split('=')[1];
+        const idx = args.indexOf('--approve');
+        return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : undefined;
+    })();
+    const rejectId = (() => {
+        const eqArg = args.find(a => a.startsWith('--reject='));
+        if (eqArg)
+            return eqArg.split('=')[1];
+        const idx = args.indexOf('--reject');
+        return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : undefined;
+    })();
+    const promoteMode = args.includes('--promote');
+    const isLocal = args.includes('--local') || !args.includes('--catalog');
+    if (approveId) {
+        const updated = updateStagedStatus(approveId, 'approved');
+        if (updated) {
+            console.log(`  Approved: ${approveId}`);
+        }
+        else {
+            console.error(`  Not found: ${approveId}`);
+            process.exit(1);
+        }
+        process.exit(0);
+    }
+    if (rejectId) {
+        const updated = updateStagedStatus(rejectId, 'rejected');
+        if (updated) {
+            console.log(`  Rejected: ${rejectId}`);
+            cleanRejected();
+        }
+        else {
+            console.error(`  Not found: ${rejectId}`);
+            process.exit(1);
+        }
+        process.exit(0);
+    }
+    if (promoteMode) {
+        if (!isLocal) {
+            console.log('  Catalog promotion is for contributors who want to upstream templates.');
+            console.log('  Use --local (default) to write templates to your project.');
+            process.exit(0);
+        }
+        const promoted = promoteLocal();
+        if (promoted.length === 0) {
+            console.log('  No approved proposals to promote.');
+        }
+        else {
+            console.log(`  Promoted ${promoted.length} template(s) to templates/:`);
+            for (const name of promoted) {
+                console.log(`    ${name}`);
+            }
+        }
+        process.exit(0);
+    }
+    // Default: list mode
+    const staged = listStaged();
+    if (staged.length === 0) {
+        console.log('  No staged proposals. Run \'kern evolve <dir>\' to detect gaps.');
+        process.exit(0);
+    }
+    console.log(`\n  KERN evolve:review — ${staged.length} proposal(s)\n`);
+    for (const s of staged) {
+        console.log(formatSplitView(s));
+        console.log('');
+    }
+    process.exit(0);
+}
+// ── kern evolve:discover <dir> [--recursive] [--provider=openai|ollama] [--max-tokens=N] ──
+if (args[0] === 'evolve:discover') {
+    const discoverInput = args[1];
+    if (!discoverInput || discoverInput.startsWith('--')) {
+        console.error('Usage: kern evolve:discover <dir> [--recursive] [--provider=openai|anthropic|ollama] [--max-tokens=N]');
+        process.exit(1);
+    }
+    const discoverPath = resolve(discoverInput);
+    if (!existsSync(discoverPath)) {
+        console.error(`Not found: ${discoverInput}`);
+        process.exit(1);
+    }
+    const recursive = args.includes('--recursive') || args.includes('-r');
+    const providerArg = args.find(a => a.startsWith('--provider='))?.split('=')[1];
+    const maxTokensArg = args.find(a => a.startsWith('--max-tokens='))?.split('=')[1];
+    const maxTokens = maxTokensArg ? Number(maxTokensArg) : 100000;
+    console.log(`\n  KERN evolve:discover — LLM pattern discovery\n`);
+    console.log(`  Input: ${relative(process.cwd(), discoverPath) || '.'}`);
+    // Collect files and batch
+    const tsFiles = collectTsFiles(discoverPath, recursive);
+    console.log(`  Files found: ${tsFiles.length}`);
+    if (tsFiles.length === 0) {
+        console.log('  No TypeScript files to analyze.');
+        process.exit(0);
+    }
+    const batches = selectRepresentativeFiles(tsFiles);
+    console.log(`  Batches: ${batches.length} (sampling representative files)`);
+    // Load existing evolved keywords for dedup
+    const manifest = readEvolvedManifest();
+    const evolvedKeywords = manifest ? Object.keys(manifest.nodes) : [];
+    // Create LLM provider
+    let provider;
+    try {
+        provider = createLLMProvider({ provider: providerArg });
+    }
+    catch (err) {
+        console.error(`  ${err.message}`);
+        process.exit(1);
+    }
+    console.log(`  Provider: ${provider.name}`);
+    const budget = new TokenBudget(maxTokens);
+    const allProposals = [];
+    const runId = `run-${Date.now()}`;
+    for (let i = 0; i < batches.length; i++) {
+        if (budget.exhausted) {
+            console.log(`  Token budget exhausted (${budget}). Stopping.`);
+            break;
+        }
+        const batch = batches[i];
+        const files = batch.map(fp => ({
+            path: relative(process.cwd(), fp),
+            content: readFileSync(fp, 'utf-8'),
+        }));
+        const prompt = buildDiscoveryPrompt(files, NODE_TYPES, evolvedKeywords);
+        budget.add(estimateTokens(prompt));
+        console.log(`  Batch ${i + 1}/${batches.length}: ${files.map(f => f.path).join(', ')}`);
+        try {
+            const response = await provider.complete(prompt);
+            budget.add(estimateTokens(response));
+            const proposals = parseDiscoveryResponse(response, runId);
+            allProposals.push(...proposals);
+            if (proposals.length > 0) {
+                console.log(`    → ${proposals.length} pattern(s) found: ${proposals.map(p => p.keyword).join(', ')}`);
+            }
+        }
+        catch (err) {
+            console.error(`    → Error: ${err.message}`);
+        }
+    }
+    // Dedup across batches
+    const seen = new Set();
+    const uniqueProposals = allProposals.filter(p => {
+        if (seen.has(p.keyword))
+            return false;
+        seen.add(p.keyword);
+        return true;
+    });
+    console.log(`\n  Discovery complete.`);
+    console.log(`  Tokens used: ${budget}`);
+    console.log(`  Proposals: ${uniqueProposals.length}\n`);
+    // Validate and stage proposals (with LLM retry on failure, max 2 retries)
+    const existingKw = [...NODE_TYPES, ...evolvedKeywords];
+    let stagedCount = 0;
+    const maxRetries = 2;
+    for (let pi = 0; pi < uniqueProposals.length; pi++) {
+        let proposal = uniqueProposals[pi];
+        // Assign ID if missing
+        if (!proposal.id) {
+            proposal.id = `${proposal.keyword}-${Date.now()}`;
+        }
+        let validation = validateEvolveProposal(proposal, existingKw);
+        let allOk = validation.schemaOk && validation.keywordOk && validation.parseOk && validation.codegenCompileOk && validation.codegenRunOk;
+        // Retry on fixable failures (parse, codegen, typescript, golden diff)
+        const isFixable = validation.schemaOk && validation.keywordOk && !allOk;
+        if (!allOk && isFixable && provider) {
+            for (let retry = 1; retry <= maxRetries; retry++) {
+                console.log(`  \u21BB ${proposal.keyword} — retry ${retry}/${maxRetries} (feeding errors to LLM)`);
+                try {
+                    const retryPrompt = buildRetryPrompt(proposal, validation.errors);
+                    budget.add(estimateTokens(retryPrompt));
+                    const retryResponse = await provider.complete(retryPrompt);
+                    if (!retryResponse || typeof retryResponse !== 'string')
+                        throw new Error('LLM returned empty or invalid response');
+                    budget.add(estimateTokens(retryResponse));
+                    // Parse retry response as single object
+                    let json = retryResponse.trim();
+                    const fenceMatch = json.match(/```(?:json)?\s*\n?([\s\S]*?)```/);
+                    if (fenceMatch)
+                        json = fenceMatch[1].trim();
+                    const objStart = json.indexOf('{');
+                    const objEnd = json.lastIndexOf('}');
+                    if (objStart !== -1 && objEnd > objStart)
+                        json = json.slice(objStart, objEnd + 1);
+                    const fixed = JSON.parse(json);
+                    if (typeof fixed !== 'object' || fixed === null)
+                        throw new Error('LLM retry response is not a JSON object');
+                    // Merge fixes into proposal
+                    if (typeof fixed.kernExample === 'string')
+                        proposal.kernExample = fixed.kernExample;
+                    if (typeof fixed.expectedOutput === 'string')
+                        proposal.expectedOutput = fixed.expectedOutput;
+                    if (typeof fixed.codegenSource === 'string')
+                        proposal.codegenSource = fixed.codegenSource;
+                    validation = validateEvolveProposal(proposal, existingKw);
+                    allOk = validation.schemaOk && validation.keywordOk && validation.parseOk && validation.codegenCompileOk && validation.codegenRunOk;
+                    if (allOk)
+                        break;
+                }
+                catch (e) {
+                    console.error(`    Retry ${retry} failed: ${e.message}`);
+                }
+            }
+        }
+        const status = allOk ? '\u2713' : '\u2717';
+        console.log(`  ${status} ${proposal.keyword} — ${proposal.reason.observation}`);
+        if (validation.errors.length > 0) {
+            for (const err of validation.errors.slice(0, 3)) {
+                console.log(`    ${err}`);
+            }
+        }
+        // Stage proposals for review (including failed ones — user can inspect)
+        validation.retryCount = allOk ? 0 : maxRetries;
+        stageEvolveV4Proposal(proposal, validation);
+        stagedCount++;
+    }
+    if (stagedCount > 0) {
+        console.log(`\n  Staged ${stagedCount} proposal(s).`);
+        console.log(`  Run 'kern evolve:review-v4' to review and graduate proposals.`);
+    }
+    console.log('');
+    process.exit(0);
+}
+// ── kern evolve:review-v4 [--list] [--approve=<id>] [--reject=<id>] [--detail=<id>] ──
+if (args[0] === 'evolve:review-v4') {
+    const approveV4Id = (() => {
+        const eqArg = args.find(a => a.startsWith('--approve='));
+        if (eqArg)
+            return eqArg.split('=')[1];
+        const idx = args.indexOf('--approve');
+        return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : undefined;
+    })();
+    const rejectV4Id = (() => {
+        const eqArg = args.find(a => a.startsWith('--reject='));
+        if (eqArg)
+            return eqArg.split('=')[1];
+        const idx = args.indexOf('--reject');
+        return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : undefined;
+    })();
+    const detailV4Id = (() => {
+        const eqArg = args.find(a => a.startsWith('--detail='));
+        if (eqArg)
+            return eqArg.split('=')[1];
+        const idx = args.indexOf('--detail');
+        return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : undefined;
+    })();
+    if (approveV4Id) {
+        // Approve → validate → compile → graduate
+        const staged = getStagedEvolveV4(approveV4Id);
+        if (!staged) {
+            console.error(`  Not found: ${approveV4Id}`);
+            process.exit(1);
+        }
+        const { proposal, validation } = staged;
+        const allOk = validation.schemaOk && validation.keywordOk && validation.parseOk && validation.codegenCompileOk && validation.codegenRunOk;
+        if (!allOk) {
+            console.error(`  Cannot approve — validation failed for '${proposal.keyword}':`);
+            for (const err of validation.errors) {
+                console.error(`    ${err}`);
+            }
+            process.exit(1);
+        }
+        // Compile codegen source to JS
+        let compiledJs;
+        try {
+            compiledJs = compileCodegenToJS(proposal.codegenSource);
+        }
+        catch (err) {
+            console.error(`  Failed to compile codegen for '${proposal.keyword}': ${err.message}`);
+            process.exit(1);
+        }
+        // Graduate the node
+        const result = graduateNode(proposal, compiledJs);
+        if (result.success) {
+            updateStagedEvolveV4Status(approveV4Id, 'approved');
+            cleanApprovedEvolveV4(approveV4Id);
+            console.log(`  Graduated '${proposal.keyword}' → ${result.path}`);
+            console.log(`  The node is now available in kern compile and kern dev.`);
+        }
+        else {
+            console.error(`  Graduation failed: ${result.error}`);
+            process.exit(1);
+        }
+        process.exit(0);
+    }
+    if (rejectV4Id) {
+        const updated = updateStagedEvolveV4Status(rejectV4Id, 'rejected');
+        if (updated) {
+            console.log(`  Rejected: ${updated.proposal.keyword} (${rejectV4Id})`);
+            cleanRejectedEvolveV4();
+        }
+        else {
+            console.error(`  Not found: ${rejectV4Id}`);
+            process.exit(1);
+        }
+        process.exit(0);
+    }
+    if (detailV4Id) {
+        const staged = getStagedEvolveV4(detailV4Id);
+        if (!staged) {
+            console.error(`  Not found: ${detailV4Id}`);
+            process.exit(1);
+        }
+        const { proposal, validation } = staged;
+        console.log(`\n  DETAIL: ${proposal.keyword} (${proposal.displayName})\n`);
+        console.log(`  Description: ${proposal.description}`);
+        console.log(`  Props: ${proposal.props.map(p => `${p.name}:${p.type}${p.required ? '*' : ''}`).join(', ')}`);
+        console.log(`  Child types: ${proposal.childTypes.join(', ') || '(none)'}`);
+        console.log(`  Codegen tier: ${proposal.codegenTier}`);
+        console.log(`  Run ID: ${proposal.evolveRunId}`);
+        if (proposal.parserHints) {
+            console.log(`  Parser hints: ${JSON.stringify(proposal.parserHints)}`);
+        }
+        console.log(`\n  --- Codegen Source ---`);
+        console.log(proposal.codegenSource);
+        console.log(`  --- Instances (${proposal.reason.instances.length}) ---`);
+        for (const inst of proposal.reason.instances.slice(0, 10)) {
+            console.log(`    ${inst}`);
+        }
+        if (validation.errors.length > 0) {
+            console.log(`\n  --- Validation Errors ---`);
+            for (const err of validation.errors) {
+                console.log(`    ${err}`);
+            }
+        }
+        console.log('');
+        process.exit(0);
+    }
+    // Default: interactive review or list mode
+    const stagedV4 = listStagedEvolveV4();
+    const pendingV4 = stagedV4.filter(s => s.status === 'pending');
+    if (pendingV4.length === 0) {
+        console.log('  No pending v4 proposals. Run \'kern evolve:discover <dir>\' to find patterns.');
+        process.exit(0);
+    }
+    const listOnly = args.includes('--list');
+    if (listOnly) {
+        console.log(`\n  KERN evolve:review-v4 — ${pendingV4.length} proposal(s)\n`);
+        for (const s of pendingV4) {
+            console.log(formatEvolveV4SplitView(s));
+            console.log('');
+        }
+        process.exit(0);
+    }
+    // Interactive review — walk through each proposal
+    const { createInterface } = await import('readline');
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (q) => new Promise(res => rl.question(q, res));
+    console.log(`\n  KERN evolve:review-v4 — ${pendingV4.length} proposal(s)\n`);
+    for (const staged of pendingV4) {
+        console.log(formatEvolveV4SplitView(staged));
+        console.log('');
+        let decided = false;
+        while (!decided) {
+            const answer = (await ask('  [a]pprove  [r]eject  [s]kip  [d]etail  [q]uit > ')).trim().toLowerCase();
+            if (answer === 'a' || answer === 'approve') {
+                const { proposal, validation } = staged;
+                const allOk = validation.schemaOk && validation.keywordOk && validation.parseOk && validation.codegenCompileOk && validation.codegenRunOk;
+                if (!allOk) {
+                    console.log(`  Cannot approve — validation failed. Use [d]etail to see errors.\n`);
+                    continue;
+                }
+                try {
+                    const compiledJs = compileCodegenToJS(proposal.codegenSource);
+                    const result = graduateNode(proposal, compiledJs);
+                    if (result.success) {
+                        updateStagedEvolveV4Status(staged.id, 'approved');
+                        cleanApprovedEvolveV4(staged.id);
+                        console.log(`  \u2713 Graduated '${proposal.keyword}'\n`);
+                    }
+                    else {
+                        console.log(`  Graduation failed: ${result.error}\n`);
+                    }
+                }
+                catch (err) {
+                    console.log(`  Error: ${err.message}\n`);
+                }
+                decided = true;
+            }
+            else if (answer === 'r' || answer === 'reject') {
+                updateStagedEvolveV4Status(staged.id, 'rejected');
+                cleanRejectedEvolveV4();
+                console.log(`  \u2717 Rejected '${staged.proposal.keyword}'\n`);
+                decided = true;
+            }
+            else if (answer === 's' || answer === 'skip') {
+                console.log(`  Skipped.\n`);
+                decided = true;
+            }
+            else if (answer === 'd' || answer === 'detail') {
+                const { proposal, validation } = staged;
+                console.log(`\n  --- Codegen Source ---`);
+                console.log(proposal.codegenSource);
+                console.log(`  --- Instances (${proposal.reason.instances.length}) ---`);
+                for (const inst of proposal.reason.instances.slice(0, 5)) {
+                    console.log(`    ${inst}`);
+                }
+                if (validation.errors.length > 0) {
+                    console.log(`  --- Errors ---`);
+                    for (const err of validation.errors) {
+                        console.log(`    ${err}`);
+                    }
+                }
+                console.log('');
+            }
+            else if (answer === 'q' || answer === 'quit') {
+                rl.close();
+                process.exit(0);
+            }
+        }
+    }
+    rl.close();
+    console.log('  Review complete.\n');
+    process.exit(0);
+}
+// ── kern evolve:test ─────────────────────────────────────────────────
+if (args[0] === 'evolve:test') {
+    console.log('\n  KERN evolve:test — golden test runner\n');
+    const results = runGoldenTests();
+    console.log(formatGoldenTestResults(results));
+    const failed = results.filter(r => !r.pass).length;
+    console.log('');
+    process.exit(failed > 0 ? 1 : 0);
+}
+// ── kern evolve:rollback <keyword> [--force] ─────────────────────────
+if (args[0] === 'evolve:rollback') {
+    const keyword = args[1];
+    if (!keyword || keyword.startsWith('--')) {
+        console.error('Usage: kern evolve:rollback <keyword> [--force]');
+        process.exit(1);
+    }
+    const force = args.includes('--force');
+    const result = rollbackNode(keyword, process.cwd(), force);
+    if (result.success) {
+        console.log(`  Rolled back '${keyword}' (moved to .trash/).`);
+        console.log(`  Restore with: kern evolve:restore ${keyword}`);
+    }
+    else {
+        console.error(`  Failed: ${result.error}`);
+        if (result.usageFiles) {
+            console.error('  Used in:');
+            for (const f of result.usageFiles.slice(0, 5)) {
+                console.error(`    ${relative(process.cwd(), f)}`);
+            }
+        }
+        process.exit(1);
+    }
+    process.exit(0);
+}
+// ── kern evolve:restore <keyword> ────────────────────────────────────
+if (args[0] === 'evolve:restore') {
+    const keyword = args[1];
+    if (!keyword) {
+        console.error('Usage: kern evolve:restore <keyword>');
+        process.exit(1);
+    }
+    const result = restoreNode(keyword);
+    if (result.success) {
+        console.log(`  Restored '${keyword}'.`);
+    }
+    else {
+        console.error(`  Failed: ${result.error}`);
+        process.exit(1);
+    }
+    process.exit(0);
+}
+// ── kern evolve:list ─────────────────────────────────────────────────
+if (args[0] === 'evolve:list') {
+    const manifest = readEvolvedManifest();
+    if (!manifest || Object.keys(manifest.nodes).length === 0) {
+        console.log('\n  No evolved nodes graduated. Run \'kern evolve:discover\' to start.\n');
+        process.exit(0);
+    }
+    console.log(`\n  KERN evolved nodes — ${Object.keys(manifest.nodes).length} graduated\n`);
+    for (const [keyword, entry] of Object.entries(manifest.nodes)) {
+        console.log(`  ${keyword} — ${entry.displayName} (graduated ${entry.graduatedAt.split('T')[0]} by ${entry.graduatedBy})`);
+    }
+    console.log('');
+    process.exit(0);
+}
+// ── kern evolve:promote <keyword> ────────────────────────────────────
+if (args[0] === 'evolve:promote') {
+    const promoteKeyword = args[1];
+    if (!promoteKeyword || promoteKeyword.startsWith('--')) {
+        console.error('Usage: kern evolve:promote <keyword>');
+        console.error('  Reads codegen from .kern/evolved/<keyword>/ and outputs what to add to core.');
+        process.exit(1);
+    }
+    const result = promoteNode(promoteKeyword);
+    if (!result.success) {
+        console.error(`  Failed: ${result.error}`);
+        process.exit(1);
+    }
+    const fnName = 'generate' + promoteKeyword.split('-').map(w => w[0].toUpperCase() + w.slice(1)).join('');
+    console.log(`\n  KERN evolve:promote — ${promoteKeyword}\n`);
+    console.log('  To promote this node to core, apply these changes:\n');
+    console.log(`  1. Add '${promoteKeyword}' to NODE_TYPES in packages/core/src/spec.ts`);
+    console.log(`  2. Create packages/core/src/generators/${fnName}.ts with:`);
+    console.log(`     ──────────────────────────────`);
+    for (const line of (result.codegenTs || '').split('\n').slice(0, 20)) {
+        console.log(`     ${line}`);
+    }
+    if ((result.codegenTs || '').split('\n').length > 20) {
+        console.log(`     ... (${(result.codegenTs || '').split('\n').length - 20} more lines)`);
+    }
+    console.log(`     ──────────────────────────────`);
+    console.log(`  3. Add case '${promoteKeyword}': return ${fnName}(node); to generateCoreNode() in codegen-core.ts`);
+    if (result.goldenKern) {
+        console.log(`  4. Move golden test to packages/core/tests/`);
+    }
+    console.log(`  5. Run: kern evolve:rollback ${promoteKeyword} --force`);
+    console.log('');
+    process.exit(0);
+}
+// ── kern evolve:backfill <keyword> --target=<target> [--provider=...] ──
+if (args[0] === 'evolve:backfill') {
+    const backfillKeyword = args[1];
+    if (!backfillKeyword || backfillKeyword.startsWith('--')) {
+        console.error('Usage: kern evolve:backfill <keyword> --target=<target> [--provider=openai|anthropic|ollama]');
+        process.exit(1);
+    }
+    const backfillTarget = args.find(a => a.startsWith('--target='))?.split('=')[1];
+    if (!backfillTarget) {
+        console.error('  --target=<target> is required');
+        process.exit(1);
+    }
+    const def = readNodeDefinition(backfillKeyword);
+    if (!def) {
+        console.error(`  Node '${backfillKeyword}' is not graduated.`);
+        process.exit(1);
+    }
+    // Read current codegen source
+    const codegenTsPath = resolve('.kern', 'evolved', backfillKeyword, 'codegen.ts');
+    if (!existsSync(codegenTsPath)) {
+        console.error(`  Missing codegen.ts for '${backfillKeyword}'`);
+        process.exit(1);
+    }
+    const codegenSource = readFileSync(codegenTsPath, 'utf-8');
+    const templateKernPath = resolve('.kern', 'evolved', backfillKeyword, 'template.kern');
+    const kernExample = existsSync(templateKernPath) ? readFileSync(templateKernPath, 'utf-8') : '';
+    const expectedOutputPath = resolve('.kern', 'evolved', backfillKeyword, 'expected-output.ts');
+    const expectedOutput = existsSync(expectedOutputPath) ? readFileSync(expectedOutputPath, 'utf-8') : '';
+    console.log(`\n  KERN evolve:backfill — ${backfillKeyword} → ${backfillTarget}\n`);
+    const providerArg = args.find(a => a.startsWith('--provider='))?.split('=')[1];
+    let provider;
+    try {
+        provider = createLLMProvider({ provider: providerArg });
+    }
+    catch (err) {
+        console.error(`  ${err.message}`);
+        process.exit(1);
+    }
+    console.log(`  Provider: ${provider.name}`);
+    const prompt = buildBackfillPrompt(backfillKeyword, {
+        props: def.props,
+        childTypes: def.childTypes,
+        kernExample,
+        codegenSource,
+        expectedOutput,
+    }, backfillTarget);
+    try {
+        const response = await provider.complete(prompt);
+        // Parse JSON response
+        let json = response.trim();
+        const fenceMatch = json.match(/```(?:json)?\s*\n?([\s\S]*?)```/);
+        if (fenceMatch)
+            json = fenceMatch[1].trim();
+        const objStart = json.indexOf('{');
+        const objEnd = json.lastIndexOf('}');
+        if (objStart !== -1 && objEnd > objStart)
+            json = json.slice(objStart, objEnd + 1);
+        const parsed = JSON.parse(json);
+        if (typeof parsed !== 'object' || parsed === null) {
+            console.error('  LLM response is not a JSON object');
+            process.exit(1);
+        }
+        const targetCodegen = typeof parsed.codegenSource === 'string' ? parsed.codegenSource : undefined;
+        if (!targetCodegen) {
+            console.error('  LLM did not return codegenSource');
+            process.exit(1);
+        }
+        // Write target override
+        const targetsDir = resolve('.kern', 'evolved', backfillKeyword, 'targets');
+        mkdirSync(targetsDir, { recursive: true });
+        writeFileSync(resolve(targetsDir, `${backfillTarget}.js`), targetCodegen);
+        console.log(`  Written: .kern/evolved/${backfillKeyword}/targets/${backfillTarget}.js`);
+        if (parsed.expectedOutput) {
+            console.log(`  Expected output preview:`);
+            for (const line of parsed.expectedOutput.split('\n').slice(0, 10)) {
+                console.log(`    ${line}`);
+            }
+        }
+        console.log(`\n  Review the generated codegen before using in production.`);
+    }
+    catch (err) {
+        console.error(`  Error: ${err.message}`);
+        process.exit(1);
+    }
+    console.log('');
+    process.exit(0);
+}
+// ── kern evolve:prune [--dry-run] [--days=N] ─────────────────────────
+if (args[0] === 'evolve:prune') {
+    const dryRun = args.includes('--dry-run');
+    const daysArg = args.find(a => a.startsWith('--days='))?.split('=')[1];
+    const thresholdDays = daysArg ? Number(daysArg) : 90;
+    console.log(`\n  KERN evolve:prune — removing unused nodes (>${thresholdDays}d)\n`);
+    const results = pruneNodes(process.cwd(), thresholdDays, dryRun);
+    if (results.length === 0) {
+        console.log('  No nodes eligible for pruning.');
+        process.exit(0);
+    }
+    for (const r of results) {
+        if (dryRun) {
+            console.log(`  Would prune: ${r.keyword} (${r.daysUnused}d unused)`);
+        }
+        else if (r.pruned) {
+            console.log(`  Pruned: ${r.keyword} (${r.daysUnused}d unused) → .trash/`);
+        }
+        else {
+            console.log(`  Failed: ${r.keyword} — ${r.error}`);
+        }
+    }
+    if (dryRun) {
+        console.log(`\n  Dry run — no changes made. Remove --dry-run to prune.`);
+    }
+    console.log('');
+    process.exit(0);
+}
+// ── kern evolve:migrate ──────────────────────────────────────────────
+if (args[0] === 'evolve:migrate') {
+    console.log(`\n  KERN evolve:migrate — checking for keyword collisions\n`);
+    const collisions = detectCollisions(NODE_TYPES);
+    if (collisions.length === 0) {
+        console.log('  No collisions. All evolved nodes are compatible with core.');
+        process.exit(0);
+    }
+    console.log(`  Found ${collisions.length} collision(s):\n`);
+    for (const c of collisions) {
+        console.log(`  ${c.keyword} (graduated ${c.graduatedAt.split('T')[0]})`);
+        console.log(`    This keyword now exists in core NODE_TYPES.`);
+        console.log(`    Options:`);
+        console.log(`      kern evolve:migrate --rename=${c.keyword} --to=<new-name>`);
+        console.log(`      kern evolve:migrate --remove=${c.keyword}  (core version supersedes)`);
+        console.log('');
+    }
+    // Handle --rename and --remove flags
+    const renameArg = args.find(a => a.startsWith('--rename='))?.split('=')[1];
+    const toArg = args.find(a => a.startsWith('--to='))?.split('=')[1];
+    const removeArg = args.find(a => a.startsWith('--remove='))?.split('=')[1];
+    if (renameArg && toArg) {
+        const result = renameEvolvedNode(renameArg, toArg);
+        if (result.success) {
+            console.log(`  Renamed '${renameArg}' → '${toArg}'`);
+            console.log(`  Update your .kern files: replace '${renameArg}' with '${toArg}'.`);
+        }
+        else {
+            console.error(`  Rename failed: ${result.error}`);
+            process.exit(1);
+        }
+    }
+    if (removeArg) {
+        const result = rollbackNode(removeArg, process.cwd(), true);
+        if (result.success) {
+            console.log(`  Removed evolved '${removeArg}' — core version will be used.`);
+        }
+        else {
+            console.error(`  Remove failed: ${result.error}`);
+            process.exit(1);
+        }
+    }
+    console.log('');
+    process.exit(0);
+}
+// ── kern evolve:rebuild ─────────────────────────────────────────────
+if (args[0] === 'evolve:rebuild') {
+    console.log(`\n  KERN evolve:rebuild — rebuilding manifest from disk\n`);
+    const result = rebuildEvolvedManifest();
+    if (result.errors.length > 0) {
+        for (const err of result.errors) {
+            console.log(`  ⚠  ${err}`);
+        }
+        console.log('');
+    }
+    if (result.rebuilt === 0 && result.errors.length > 0) {
+        console.error('  No nodes rebuilt.');
+        process.exit(1);
+    }
+    console.log(`  manifest.json rebuilt with ${result.rebuilt} node(s).`);
+    console.log('');
+    process.exit(0);
+}
+// ── kern confidence <file.kern|dir> ──────────────────────────────────
+if (args[0] === 'confidence') {
+    const confInput = args[1];
+    if (!confInput) {
+        console.error('Usage: kern confidence <file.kern|dir>');
+        console.error('  Builds and displays the confidence graph for .kern file(s).');
+        process.exit(1);
+    }
+    const confPath = resolve(confInput);
+    if (!existsSync(confPath)) {
+        console.error(`Not found: ${confInput}`);
+        process.exit(1);
+    }
+    const { buildConfidenceGraph, buildMultiFileConfidenceGraph, flattenIR, lintMultiFileConfidenceGraph } = await import('@kernlang/review');
+    const confStat = statSync(confPath);
+    const isDir = confStat.isDirectory();
+    // Collect .kern files
+    const kernFiles = isDir ? findKernFiles(confPath) : [confPath];
+    if (kernFiles.length === 0) {
+        console.log('  No .kern files found.');
+        process.exit(0);
+    }
+    // Parse all files, skip those without confidence (fast early exit)
+    const fileMap = new Map();
+    for (const file of kernFiles.sort()) {
+        const source = readFileSync(file, 'utf-8');
+        if (!source.includes('confidence='))
+            continue;
+        const ast = parse(source);
+        fileMap.set(file, flattenIR(ast));
+    }
+    if (fileMap.size === 0) {
+        console.log(`\n  No confidence declarations found in ${isDir ? confInput : basename(confInput)}`);
+        process.exit(0);
+    }
+    // Build graph (single-file or multi-file)
+    const graph = fileMap.size === 1
+        ? buildConfidenceGraph([...fileMap.values()][0])
+        : buildMultiFileConfidenceGraph(fileMap);
+    const isMulti = fileMap.size > 1;
+    console.log(`\n  Confidence Graph (${graph.nodes.size} nodes, ${graph.topoOrder.length} resolved${isMulti ? `, ${fileMap.size} files` : ''}):\n`);
+    if (isMulti) {
+        // Group by source file
+        const byFile = new Map();
+        for (const cnode of graph.nodes.values()) {
+            const file = cnode.sourceFile || 'unknown';
+            if (!byFile.has(file))
+                byFile.set(file, []);
+            byFile.get(file).push(cnode);
+        }
+        for (const [file, nodes] of byFile) {
+            const rel = relative(process.cwd(), file) || file;
+            console.log(`  ${rel} (${nodes.length} nodes):`);
+            for (const cnode of nodes) {
+                const resolvedStr = cnode.resolved !== null ? cnode.resolved.toFixed(2) : 'null';
+                const specStr = cnode.spec.kind === 'literal'
+                    ? 'declared'
+                    : `from: ${cnode.spec.sources?.join(', ')}, ${cnode.spec.strategy}`;
+                const crossFile = cnode.spec.sources?.some(s => {
+                    const src = graph.nodes.get(s);
+                    return src && src.sourceFile !== cnode.sourceFile;
+                });
+                const crossTag = crossFile ? ' [cross-file]' : '';
+                const cycleTag = cnode.inCycle ? ' [CYCLE]' : '';
+                console.log(`    ${cnode.name.padEnd(20)} ${resolvedStr.padEnd(8)} (${specStr})${crossTag}${cycleTag}`);
+            }
+            console.log('');
+        }
+    }
+    else {
+        for (const [name, cnode] of graph.nodes) {
+            const resolvedStr = cnode.resolved !== null ? cnode.resolved.toFixed(2) : 'null';
+            const specStr = cnode.spec.kind === 'literal'
+                ? 'declared'
+                : `from: ${cnode.spec.sources?.join(', ')}, ${cnode.spec.strategy}`;
+            const cycleTag = cnode.inCycle ? ' [CYCLE]' : '';
+            console.log(`    ${name.padEnd(20)} ${resolvedStr.padEnd(8)} (${specStr})${cycleTag}`);
+        }
+    }
+    // Unresolved needs
+    const unresolvedNeeds = [];
+    for (const [name, cnode] of graph.nodes) {
+        for (const need of cnode.needs) {
+            if (!need.resolved) {
+                unresolvedNeeds.push({ name, what: need.what, wouldRaiseTo: need.wouldRaiseTo });
+            }
+        }
+    }
+    if (unresolvedNeeds.length > 0) {
+        console.log(`  Unresolved needs (${unresolvedNeeds.length}):`);
+        for (const n of unresolvedNeeds) {
+            const raise = n.wouldRaiseTo !== undefined ? ` → would raise to ${n.wouldRaiseTo}` : '';
+            console.log(`    ${n.name}: "${n.what}"${raise}`);
+        }
+    }
+    if (graph.cycles.length > 0) {
+        console.log(`\n  Cycles (${graph.cycles.length}):`);
+        for (const cycle of graph.cycles) {
+            console.log(`    ${cycle.join(' → ')}`);
+        }
+    }
+    // Duplicates (multi-file only)
+    const dupes = 'duplicates' in graph ? graph.duplicates : [];
+    if (dupes.length > 0) {
+        console.log(`\n  Duplicate names (${dupes.length}):`);
+        for (const dup of dupes) {
+            console.log(`    ${dup.name}: ${dup.files.map((f) => relative(process.cwd(), f) || f).join(', ')}`);
+        }
+    }
+    console.log('');
+    process.exit(0);
+}
 // ── Standard transpile mode ────────────────────────────────────────────
 const inputFile = args.find(a => !a.startsWith('--'));
 if (!inputFile) {
@@ -707,7 +1929,16 @@ if (!inputFile) {
     console.log('  compile <dir|file> --outdir=<dir>             Compile .kern → .ts (core nodes)');
     console.log('  scan [--force] [--dry-run]                    Detect project → generate kern.config.ts');
     console.log('  init-templates [--force] [--dry-run]          Scan deps → scaffold template .kern files');
-    console.log('  review <file.ts|dir> [options]                Analyze TS → infer .kern coverage + review');
+    console.log('  review <file.ts|dir> [options]                Static analysis, Cognitive Complexity & CI Gate');
+    console.log('  evolve <dir|file> [options]                   Detect gaps → propose templates');
+    console.log('  evolve:review [options]                       Review staged template proposals');
+    console.log('  evolve:review-v4 [options]                    Review & graduate v4 node proposals');
+    console.log('  evolve:promote <keyword>                      Show steps to move evolved → core');
+    console.log('  evolve:backfill <kw> --target=<t>             LLM generates target-specific codegen');
+    console.log('  evolve:prune [--dry-run] [--days=N]           Remove unused nodes (default 90d)');
+    console.log('  evolve:migrate                                Detect & resolve keyword collisions');
+    console.log('  evolve:rebuild                                Rebuild manifest.json from disk definitions');
+    console.log('  confidence <file.kern>                        Display confidence graph for a .kern file');
     console.log('');
     console.log('Targets:');
     console.log('  nextjs    Next.js App Router (default)');
@@ -754,6 +1985,8 @@ else {
 }
 // Load templates before transpile
 loadTemplates(config);
+// Load evolved nodes (v4) — graduated nodes from .kern/evolved/
+loadEvolvedNodes(process.cwd(), args.includes('--verify'));
 // CLI flags override config — target
 const cliTarget = args.find(a => a.startsWith('--target='))?.split('=')[1];
 if (cliTarget) {
@@ -834,15 +2067,19 @@ const result = target === 'native'
             ? transpileTailwind(ast, config)
             : target === 'express'
                 ? transpileExpress(ast, config)
-                : target === 'cli'
-                    ? transpileCliApp(ast, config)
-                    : target === 'terminal'
-                        ? transpileTerminal(ast, config)
-                        : target === 'vue'
-                            ? transpileVue(ast, config)
-                            : target === 'nuxt'
-                                ? transpileNuxt(ast, config)
-                                : transpileNextjs(ast, config);
+                : target === 'fastapi'
+                    ? transpileFastAPI(ast, config)
+                    : target === 'cli'
+                        ? transpileCliApp(ast, config)
+                        : target === 'terminal'
+                            ? transpileTerminal(ast, config)
+                            : target === 'ink'
+                                ? transpileInk(ast, config)
+                                : target === 'vue'
+                                    ? transpileVue(ast, config)
+                                    : target === 'nuxt'
+                                        ? transpileNuxt(ast, config)
+                                        : transpileNextjs(ast, config);
 const outDir = resolve(dirname(inputFile), config.output.outDir);
 const isStructured = config.structure !== 'flat' && result.artifacts && result.artifacts.length > 0;
 if (isStructured) {
@@ -859,8 +2096,10 @@ if (isStructured) {
 }
 else {
     // Flat output: single file
-    const outExt = (target === 'vue' || target === 'nuxt') ? '.vue'
-        : (target === 'express' || target === 'cli' || target === 'terminal') ? '.ts' : '.tsx';
+    const outExt = target === 'fastapi' ? '.py'
+        : (target === 'vue' || target === 'nuxt') ? '.vue'
+            : (target === 'express' || target === 'cli' || target === 'terminal') ? '.ts'
+                : '.tsx';
     const outFile = resolve(outDir, `${name}${outExt}`);
     mkdirSync(dirname(outFile), { recursive: true });
     writeFileSync(outFile, result.code);
@@ -873,7 +2112,7 @@ else {
     }
     console.log(`Transpiled: ${inputFile} → ${outFile}`);
 }
-const targetNames = { native: 'React Native', web: 'React (inline)', tailwind: 'React + Tailwind', nextjs: 'Next.js App Router', express: 'Express TypeScript', cli: 'Commander.js CLI', terminal: 'ANSI Terminal', vue: 'Vue 3 SFC', nuxt: 'Nuxt 3' };
+const targetNames = { native: 'React Native', web: 'React (inline)', tailwind: 'React + Tailwind', nextjs: 'Next.js App Router', express: 'Express TypeScript', fastapi: 'FastAPI Python', cli: 'Commander.js CLI', terminal: 'ANSI Terminal', ink: 'Ink (React for Terminals)', vue: 'Vue 3 SFC', nuxt: 'Nuxt 3' };
 console.log(`Target:     ${targetNames[target] || target}`);
 if (config.structure !== 'flat') {
     const structureNames = { bulletproof: 'Bulletproof React', atomic: 'Atomic Design', kern: 'KERN Native' };
@@ -934,6 +2173,26 @@ function minifyKern(node) {
     }
     return head;
 }
+function collectTsFilesFlat(dirPath, recursive) {
+    const files = [];
+    for (const entry of readdirSync(dirPath)) {
+        const full = resolve(dirPath, entry);
+        const s = statSync(full);
+        if (s.isDirectory() && recursive && !entry.startsWith('.') && entry !== 'node_modules' && entry !== 'dist') {
+            files.push(...collectTsFilesFlat(full, true));
+        }
+        else if ((entry.endsWith('.ts') || entry.endsWith('.tsx')) && !entry.endsWith('.d.ts') && !entry.endsWith('.test.ts')) {
+            files.push(full);
+        }
+        else if (entry.endsWith('.kern')) {
+            files.push(full);
+        }
+        else if (entry.endsWith('.py') && !entry.startsWith('test_') && !entry.endsWith('_test.py')) {
+            files.push(full);
+        }
+    }
+    return files;
+}
 function prettyKern(node, indent = '') {
     const type = node.type;
     const props = node.props || {};