guardlink 1.1.0 → 1.3.0

package/dist/cli/index.js

@@ -3,37 +3,49 @@
  * GuardLink CLI — Reference Implementation
  *
  * Usage:
- *   guardlink init [dir]        Initialize GuardLink in a project
- *   guardlink parse [dir]       Parse annotations, output ThreatModel JSON
- *   guardlink status [dir]      Show annotation coverage summary
- *   guardlink validate [dir]    Check for syntax errors and dangling refs
- *   guardlink analyze [framework] AI-powered threat analysis (STRIDE, DREAD, etc.)
- *   guardlink annotate <prompt>  Launch coding agent for annotation
- *   guardlink config <action>    Manage LLM provider configuration
+ *   guardlink init [dir]              Initialize GuardLink in a project
+ *   guardlink parse [dir]             Parse annotations, output ThreatModel JSON
+ *   guardlink status [dir]            Show annotation coverage summary
+ *   guardlink validate [dir]          Check for syntax errors and dangling refs
+ *   guardlink report [dir]            Generate markdown + JSON threat model report
+ *   guardlink diff [ref]              Compare threat model against a git ref
+ *   guardlink sarif [dir]             Export SARIF 2.1.0 for GitHub / VS Code
+ *   guardlink threat-report <prompt>  AI-powered threat analysis (STRIDE, DREAD, PASTA, etc.)
+ *   guardlink threat-reports          List saved AI threat reports
+ *   guardlink annotate <prompt>       Launch coding agent to add annotations
+ *   guardlink config <action>         Manage LLM provider configuration
+ *   guardlink dashboard [dir]         Generate interactive HTML dashboard
+ *   guardlink mcp                     Start MCP server (stdio) for Claude Code, Cursor, etc.
+ *   guardlink tui [dir]               Interactive TUI with slash commands + AI chat
+ *   guardlink gal                     Display GAL annotation language quick reference
  *
- * @exposes #cli to #path-traversal [high] cwe:CWE-22 -- "Accepts directory paths from command line arguments"
- * @exposes #cli to #arbitrary-write [high] cwe:CWE-73 -- "Writes reports and SARIF to user-specified output paths"
- * @accepts #arbitrary-write on #cli -- "Intentional feature: users specify output paths for reports"
- * @mitigates #cli against #path-traversal using #path-validation -- "resolve() normalizes paths before passing to submodules"
- * @boundary between #cli and #parser (#cli-parser-boundary) -- "CLI is the primary user input trust boundary"
- * @flows User -> #cli via argv -- "User provides directory paths and options via command line"
- * @flows #cli -> #parser via parseProject -- "CLI dispatches parsed commands to parser"
- * @flows #cli -> #report via generateReport -- "CLI writes report output"
- * @flows #cli -> #init via initProject -- "CLI initializes project structure"
+ * @exposes #cli to #path-traversal [high] cwe:CWE-22 -- "User-supplied dir argument resolved via path.resolve"
+ * @mitigates #cli against #path-traversal using #path-validation -- "resolve() canonicalizes paths; cwd-relative by design"
+ * @exposes #cli to #arbitrary-write [high] cwe:CWE-73 -- "init/report/sarif/dashboard write files to user-specified paths"
+ * @mitigates #cli against #arbitrary-write using #path-validation -- "Output paths resolved relative to project root"
+ * @exposes #cli to #api-key-exposure [high] cwe:CWE-798 -- "API keys handled in config set/show commands"
+ * @mitigates #cli against #api-key-exposure using #key-redaction -- "maskKey() redacts keys in show output"
+ * @exposes #cli to #cmd-injection [critical] cwe:CWE-78 -- "Agent launcher spawns child processes"
+ * @audit #cli -- "Child process spawning delegated to agents/launcher.ts with explicit args"
+ * @flows UserArgs -> #cli via process.argv -- "CLI argument input path"
+ * @flows #cli -> FileSystem via writeFile -- "Report/config output path"
+ * @boundary #cli and UserInput (#cli-input-boundary) -- "Trust boundary at CLI argument parsing"
+ * @handles secrets on #cli -- "Processes API keys via config commands"
  */
 import { Command } from 'commander';
 import { resolve, basename } from 'node:path';
-import { readFileSync, existsSync } from 'node:fs';
-import { parseProject, findDanglingRefs, findUnmitigatedExposures } from '../parser/index.js';
-import { initProject, detectProject, promptAgentSelection } from '../init/index.js';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { parseProject, findDanglingRefs, findUnmitigatedExposures, findAcceptedWithoutAudit, findAcceptedExposures, clearAnnotations } from '../parser/index.js';
+import { initProject, detectProject, promptAgentSelection, syncAgentFiles } from '../init/index.js';
 import { generateReport, generateMermaid } from '../report/index.js';
 import { diffModels, formatDiff, formatDiffMarkdown, parseAtRef } from '../diff/index.js';
 import { generateSarif } from '../analyzer/index.js';
 import { startStdioServer } from '../mcp/index.js';
 import { generateThreatReport, listThreatReports, loadThreatReportsForDashboard, buildConfig, FRAMEWORK_LABELS, FRAMEWORK_PROMPTS, serializeModel, buildUserMessage } from '../analyze/index.js';
 import { generateDashboardHTML } from '../dashboard/index.js';
-import { AGENTS, agentFromOpts, launchAgent, buildAnnotatePrompt } from '../agents/index.js';
+import { AGENTS, agentFromOpts, launchAgent, launchAgentInline, buildAnnotatePrompt } from '../agents/index.js';
 import { resolveConfig, saveProjectConfig, saveGlobalConfig, loadProjectConfig, loadGlobalConfig, maskKey, describeConfigSource } from '../agents/config.js';
+import { getReviewableExposures, applyReviewAction, formatExposureForReview, summarizeReview } from '../review/index.js';
 import gradient from 'gradient-string';
 const program = new Command();
 const ASCII_LOGO = `
@@ -178,11 +190,22 @@ program
     .description('Show annotation coverage summary')
     .argument('[dir]', 'Project directory to scan', '.')
     .option('-p, --project <n>', 'Project name', 'unknown')
+    .option('--not-annotated', 'List source files with no GuardLink annotations')
     .action(async (dir, opts) => {
     const root = resolve(dir);
     const { model, diagnostics } = await parseProject({ root, project: opts.project });
     printDiagnostics(diagnostics);
     printStatus(model);
+    if (opts.notAnnotated) {
+        printUnannotatedFiles(model);
+    }
+    // Auto-sync agent instruction files with updated model
+    if (model.annotations_parsed > 0) {
+        const syncResult = syncAgentFiles({ root, model });
+        if (syncResult.updated.length > 0) {
+            console.error(`↻ Synced ${syncResult.updated.length} agent instruction file(s)`);
+        }
+    }
 });
 // ─── validate ────────────────────────────────────────────────────────
 program
@@ -196,9 +219,13 @@ program
     const { model, diagnostics } = await parseProject({ root, project: opts.project });
     // Check for dangling refs
     const danglingDiags = findDanglingRefs(model);
-    const allDiags = [...diagnostics, ...danglingDiags];
+    // Check for @accepts without @audit (governance concern)
+    const acceptAuditDiags = findAcceptedWithoutAudit(model);
+    const allDiags = [...diagnostics, ...danglingDiags, ...acceptAuditDiags];
     // Check for unmitigated exposures
     const unmitigated = findUnmitigatedExposures(model);
+    // Check for accepted-but-unmitigated exposures (risk acceptance without real controls)
+    const acceptedOnly = findAcceptedExposures(model);
     printDiagnostics(allDiags);
     if (unmitigated.length > 0) {
         console.error(`\n⚠  ${unmitigated.length} unmitigated exposure(s):`);
@@ -206,14 +233,30 @@ program
             console.error(`   ${u.asset} → ${u.threat} [${u.severity || 'unset'}] (${u.location.file}:${u.location.line})`);
         }
     }
+    if (acceptedOnly.length > 0) {
+        console.error(`\n⚡ ${acceptedOnly.length} accepted-but-unmitigated exposure(s) (risk accepted, no control in code):`);
+        for (const a of acceptedOnly) {
+            console.error(`   ${a.asset} → ${a.threat} [${a.severity || 'unset'}] (${a.location.file}:${a.location.line})`);
+        }
+    }
     const errorCount = allDiags.filter(d => d.level === 'error').length;
     const hasUnmitigated = unmitigated.length > 0;
-    if (errorCount === 0 && !hasUnmitigated) {
+    if (errorCount === 0 && !hasUnmitigated && acceptedOnly.length === 0) {
         console.error('\n✓ All annotations valid, no unmitigated exposures.');
     }
+    else if (errorCount === 0 && !hasUnmitigated && acceptedOnly.length > 0) {
+        console.error(`\nValidation passed. ${acceptedOnly.length} exposure(s) accepted without mitigation — ensure these are intentional human decisions.`);
+    }
     else if (errorCount === 0 && hasUnmitigated) {
         console.error(`\nValidation passed with ${unmitigated.length} unmitigated exposure(s).`);
     }
+    // Auto-sync agent instruction files with updated model
+    if (model.annotations_parsed > 0) {
+        const syncResult = syncAgentFiles({ root, model });
+        if (syncResult.updated.length > 0) {
+            console.error(`↻ Synced ${syncResult.updated.length} agent instruction file(s)`);
+        }
+    }
     // Exit 1 on errors always; also on unmitigated if --strict
     process.exit(errorCount > 0 || (opts.strict && hasUnmitigated) ? 1 : 0);
 });
@@ -340,32 +383,33 @@ program
 // ─── threat-report ───────────────────────────────────────────────────
 program
     .command('threat-report')
-    .description('Generate an AI threat report using a security framework (STRIDE, DREAD, PASTA, etc.)')
-    .argument('[framework]', 'Framework: stride, dread, pasta, attacker, rapid, general', 'general')
-    .argument('[dir]', 'Project directory', '.')
+    .description('Generate an AI threat report using a framework or custom prompt')
+    .argument('[prompt...]', 'Framework (stride, dread, pasta, attacker, rapid, general) or custom prompt text')
+    .option('-d, --dir <dir>', 'Project directory', '.')
     .option('-p, --project <n>', 'Project name', 'unknown')
-    .option('--provider <provider>', 'LLM provider: anthropic, openai, openrouter, deepseek (auto-detected from env)')
+    .option('--provider <provider>', 'LLM provider: anthropic, openai, google, openrouter, deepseek (auto-detected from env)')
     .option('--model <model>', 'Model name (default: provider-specific)')
     .option('--api-key <key>', 'API key (default: from env variable)')
     .option('--no-stream', 'Disable streaming output')
-    .option('--custom <prompt>', 'Custom analysis prompt (replaces framework prompt header)')
-    .option('--claude-code', 'Launch Claude Code in foreground')
-    .option('--codex', 'Launch Codex CLI in foreground')
-    .option('--gemini', 'Launch Gemini CLI in foreground')
+    .option('--web-search', 'Enable web search grounding (OpenAI only)')
+    .option('--thinking', 'Enable extended thinking / reasoning (Anthropic, DeepSeek only)')
+    .option('--claude-code', 'Run via Claude Code (inline)')
+    .option('--codex', 'Run via Codex CLI (inline)')
+    .option('--gemini', 'Run via Gemini CLI (inline)')
     .option('--cursor', 'Open Cursor IDE with prompt on clipboard')
     .option('--windsurf', 'Open Windsurf IDE with prompt on clipboard')
     .option('--clipboard', 'Copy threat report prompt to clipboard only')
-    .action(async (framework, dir, opts) => {
-    const root = resolve(dir);
+    .action(async (promptParts, opts) => {
+    const root = resolve(opts.dir);
     const project = detectProjectName(root, opts.project);
-    // Validate framework
+    const input = promptParts.join(' ').trim();
+    // Determine framework vs custom prompt
     const validFrameworks = ['stride', 'dread', 'pasta', 'attacker', 'rapid', 'general'];
-    if (!validFrameworks.includes(framework)) {
-        console.error(`Unknown framework: ${framework}`);
-        console.error(`Available: ${validFrameworks.join(', ')}`);
-        process.exit(1);
-    }
-    const fw = framework;
+    const inputLower = input.toLowerCase();
+    const isStandard = validFrameworks.includes(inputLower);
+    const fw = (isStandard ? inputLower : 'general');
+    const customPrompt = isStandard ? undefined : (input || undefined);
+    const reportLabel = customPrompt ? 'Custom Threat Analysis' : FRAMEWORK_LABELS[fw];
     // Parse project
     const { model, diagnostics } = await parseProject({ root, project });
     const errors = diagnostics.filter(d => d.level === 'error');
@@ -375,34 +419,74 @@ program
         console.error('No annotations found. Run: guardlink init . && add annotations first.');
         process.exit(1);
     }
-    // Resolve agent (same pattern as annotate)
-    const agent = agentFromOpts(opts);
-    // ── Agent path: build prompt, launch agent ──
-    if (agent) {
-        const serialized = serializeModel(model);
-        const systemPrompt = FRAMEWORK_PROMPTS[fw] || FRAMEWORK_PROMPTS.general;
-        const userMessage = buildUserMessage(serialized, fw, opts.custom);
-        const fullPrompt = `${systemPrompt}\n\n${userMessage}\n\nAlso read the source files to understand code context. Save the report to .guardlink/threat-reports/ as a markdown file.`;
-        console.log(`Generating ${FRAMEWORK_LABELS[fw]} via ${agent.name}...`);
-        if (agent.cmd) {
-            console.log(`${agent.name} will take over this terminal. Exit the agent to return.\n`);
-        }
-        const result = launchAgent(agent, fullPrompt, root);
-        if (result.clipboardCopied) {
-            console.log(`✓ Prompt copied to clipboard (${fullPrompt.length.toLocaleString()} chars)`);
+    // Build analysis prompt (shared by agent and API paths)
+    const serialized = serializeModel(model);
+    const { buildProjectContext, extractCodeSnippets } = await import('../analyze/index.js');
+    const projectContext = buildProjectContext(root);
+    const codeSnippets = extractCodeSnippets(root, model);
+    const systemPrompt = FRAMEWORK_PROMPTS[fw];
+    const userMessage = buildUserMessage(serialized, fw, customPrompt, projectContext || undefined, codeSnippets || undefined);
+    const analysisPrompt = `You are analyzing a codebase with GuardLink security annotations.
+You have access to the full source code in the current directory.
+
+${systemPrompt}
+
+## Task
+Read the source code and GuardLink annotations, then produce a thorough ${reportLabel}.
+
+## Threat Model (serialized from annotations)
+${userMessage}
+
+## Instructions
+1. Read the actual source files to understand the code — don't just rely on the serialized model above
+2. Cross-reference the annotations with the real code to validate findings
+3. Produce the full report as markdown
+4. Be specific — reference actual files, functions, and line numbers from the codebase
+5. Output ONLY the markdown report content — do NOT add any metadata comments, save confirmations, or file path messages
+6. Do NOT include lines like "Generated by...", "Agent:", "Project:", or "The report file write was blocked..."`;
+    // Resolve agent: explicit flag > project config CLI agent
+    let agent = agentFromOpts(opts);
+    if (!agent) {
+        const projCfg = loadProjectConfig(root);
+        if (projCfg?.aiMode === 'cli-agent' && projCfg?.cliAgent) {
+            agent = AGENTS.find(a => a.id === projCfg.cliAgent) || null;
         }
+    }
+    // ── Path 1: CLI Agent (inline, non-interactive) ──
+    if (agent && agent.cmd) {
+        console.error(`\n🔍 ${reportLabel}`);
+        console.error(`   Agent: ${agent.name} (inline)`);
+        console.error(`   Annotations: ${model.annotations_parsed} | Exposures: ${model.exposures.length}\n`);
+        const result = await launchAgentInline(agent, analysisPrompt, root, (text) => process.stdout.write(text), { autoYes: true });
         if (result.error) {
-            console.error(`✗ ${result.error}`);
-            if (result.clipboardCopied) {
-                console.log('Prompt is on your clipboard — paste it manually.');
-            }
+            console.error(`\n✗ ${result.error}`);
             process.exit(1);
         }
-        if (agent.cmd && result.launched) {
-            console.log(`\n✓ ${agent.name} session ended.`);
-            console.log('  Run: guardlink threat-reports  to see saved reports.');
+        process.stdout.write('\n');
+        // Save the agent's output as a report
+        if (result.content.trim()) {
+            const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+            const reportsDir = resolve(root, '.guardlink', 'threat-reports');
+            if (!existsSync(reportsDir))
+                mkdirSync(reportsDir, { recursive: true });
+            const filename = `${timestamp}-${fw}.md`;
+            const filepath = resolve(reportsDir, filename);
+            // Clean ANSI codes and CLI artifacts from the output before saving
+            const { cleanCliArtifacts } = await import('../tui/format.js');
+            const cleanedContent = cleanCliArtifacts(result.content);
+            const header = `---\nframework: ${fw}\nlabel: ${FRAMEWORK_LABELS[fw]}\nmodel: ${agent.name}\ntimestamp: ${new Date().toISOString()}\nproject: ${project}\nannotations: ${model.annotations_parsed}\n---\n\n# ${FRAMEWORK_LABELS[fw]}\n\n> Generated by \`guardlink threat-report ${fw}\` on ${new Date().toISOString().slice(0, 10)}\n> Agent: ${agent.name} | Project: ${project} | Annotations: ${model.annotations_parsed}\n\n`;
+            writeFileSync(filepath, header + cleanedContent + '\n');
+            console.error(`\n✓ Report saved to .guardlink/threat-reports/${filename}`);
         }
-        else if (agent.app && result.launched) {
+        return;
+    }
+    // ── Path 2: Clipboard / IDE agent ──
+    if (agent && !agent.cmd) {
+        const result = launchAgent(agent, analysisPrompt, root);
+        if (result.clipboardCopied) {
+            console.log(`✓ Prompt copied to clipboard (${analysisPrompt.length.toLocaleString()} chars)`);
+        }
+        if (result.launched && agent.app) {
             console.log(`✓ ${agent.name} launched with project: ${project}`);
             console.log('\nPaste (Cmd+V) the prompt in the AI chat panel.');
             console.log('When done, run: guardlink threat-reports');
@@ -411,26 +495,26 @@ program
             console.log('\nPaste the prompt into your preferred AI tool.');
             console.log('When done, run: guardlink threat-reports');
         }
+        else if (result.error) {
+            console.error(`✗ ${result.error}`);
+            process.exit(1);
+        }
         return;
     }
-    // ── API path: direct LLM call (no agent flag) ──
+    // ── Path 3: Direct API call ──
     const llmConfig = buildConfig({
         provider: opts.provider,
         model: opts.model,
         apiKey: opts.apiKey,
-    });
+    }) || resolveConfig(root);
     if (!llmConfig) {
-        // No agent, no API key — show usage like annotate does
-        console.error('No agent or API key specified. Use one of:');
-        for (const a of AGENTS) {
-            console.error(`  ${a.flag.padEnd(16)} ${a.name}`);
-        }
-        console.error('');
-        console.error('Or set an API key: ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.');
-        console.error('Or use: --provider anthropic --api-key sk-...');
+        console.error('No AI provider configured. Use one of:');
+        console.error('  guardlink config          Configure API provider');
+        console.error('  --claude-code / --codex   Use a CLI agent');
+        console.error('  ANTHROPIC_API_KEY=...     Set env var');
         process.exit(1);
     }
-    console.error(`\n🔍 ${FRAMEWORK_LABELS[fw]}`);
+    console.error(`\n🔍 ${reportLabel}`);
     console.error(`   Provider: ${llmConfig.provider} | Model: ${llmConfig.model}`);
     console.error(`   Annotations: ${model.annotations_parsed} | Exposures: ${model.exposures.length}\n`);
     try {
@@ -439,9 +523,11 @@ program
             model,
             framework: fw,
             llmConfig,
-            customPrompt: opts.custom,
+            customPrompt,
             stream: opts.stream !== false,
             onChunk: opts.stream !== false ? (text) => process.stdout.write(text) : undefined,
+            webSearch: opts.webSearch,
+            extendedThinking: opts.thinking,
         });
         if (opts.stream !== false) {
             process.stdout.write('\n');
@@ -453,6 +539,9 @@ program
         if (result.inputTokens || result.outputTokens) {
             console.error(`  Tokens: ${result.inputTokens || '?'} in / ${result.outputTokens || '?'} out`);
         }
+        if (result.thinkingTokens) {
+            console.error(`  Thinking: ${result.thinkingTokens} tokens`);
+        }
     }
     catch (err) {
         console.error(`\n✗ Threat report generation failed: ${err.message}`);
@@ -547,12 +636,203 @@ program
         console.log('When done, run: guardlink parse');
     }
 });
+// ─── clear ───────────────────────────────────────────────────────────
+program
+    .command('clear')
+    .description('Remove all GuardLink annotations from source files — start fresh')
+    .argument('[dir]', 'Project directory', '.')
+    .option('--dry-run', 'Show what would be removed without modifying files')
+    .option('--include-definitions', 'Also clear .guardlink/definitions files')
+    .option('-y, --yes', 'Skip confirmation prompt')
+    .action(async (dir, opts) => {
+    const root = resolve(dir);
+    // First, show what will be cleared
+    const preview = await clearAnnotations({
+        root,
+        dryRun: true,
+        includeDefinitions: opts.includeDefinitions,
+    });
+    if (preview.totalRemoved === 0) {
+        console.log('No GuardLink annotations found in source files.');
+        return;
+    }
+    console.log(`\nFound ${preview.totalRemoved} annotation line(s) across ${preview.modifiedFiles.length} file(s):\n`);
+    for (const [file, count] of preview.perFile) {
+        console.log(`  ${file}  (${count} line${count > 1 ? 's' : ''})`);
+    }
+    console.log('');
+    if (opts.dryRun) {
+        console.log('(dry run) No files were modified.');
+        return;
+    }
+    // Confirmation prompt
+    if (!opts.yes) {
+        if (!process.stdin.isTTY) {
+            console.error('Use --yes to confirm in non-interactive mode.');
+            process.exit(1);
+        }
+        const readline = await import('node:readline');
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise(resolve => {
+            rl.question('⚠  This will remove all annotations from source files. Continue? (y/N): ', resolve);
+        });
+        rl.close();
+        if (answer.trim().toLowerCase() !== 'y') {
+            console.log('Cancelled.');
+            return;
+        }
+    }
+    // Actually clear
+    const result = await clearAnnotations({
+        root,
+        dryRun: false,
+        includeDefinitions: opts.includeDefinitions,
+    });
+    console.log(`\n✓ Removed ${result.totalRemoved} annotation line(s) from ${result.modifiedFiles.length} file(s).`);
+    console.log('  Run: guardlink annotate  to re-annotate from scratch.');
+});
+// ─── sync ────────────────────────────────────────────────────────────
+program
+    .command('sync')
+    .description('Sync agent instruction files with current threat model — keeps ALL coding agents up to date')
+    .argument('[dir]', 'Project directory', '.')
+    .option('--dry-run', 'Show what would be updated without modifying files')
+    .action(async (dir, opts) => {
+    const root = resolve(dir);
+    // Parse the current model
+    const { model } = await parseProject({ root, project: basename(root) });
+    if (model.annotations_parsed === 0) {
+        console.log('No annotations found. Run: guardlink annotate  to add annotations first.');
+        console.log('Syncing agent files with base instructions (no model context)...\n');
+    }
+    const result = syncAgentFiles({ root, model, dryRun: opts.dryRun });
+    if (result.updated.length > 0) {
+        console.log(`${opts.dryRun ? '(dry run) Would update' : '✓ Updated'} ${result.updated.length} agent instruction file(s):\n`);
+        for (const f of result.updated) {
+            console.log(`  ${f}`);
+        }
+    }
+    if (result.skipped.length > 0) {
+        console.log(`\nSkipped: ${result.skipped.join(', ')}`);
+    }
+    if (!opts.dryRun && model.annotations_parsed > 0) {
+        console.log(`\n✓ All agent instruction files now include live threat model context.`);
+        console.log(`  ${model.assets.length} assets, ${model.threats.length} threats, ${model.controls.length} controls, ${model.exposures.length} exposures.`);
+        console.log('  Any coding agent (Cursor, Claude, Copilot, Windsurf, etc.) will see these IDs.');
+    }
+});
+// ─── unannotated ─────────────────────────────────────────────────────
+program
+    .command('unannotated')
+    .description('List source files with no GuardLink annotations')
+    .argument('[dir]', 'Project directory to scan', '.')
+    .option('-p, --project <n>', 'Project name', 'unknown')
+    .action(async (dir, opts) => {
+    const root = resolve(dir);
+    const { model } = await parseProject({ root, project: opts.project });
+    printUnannotatedFiles(model);
+});
+// ─── review ──────────────────────────────────────────────────────────
+program
+    .command('review')
+    .description('Interactive governance review of unmitigated exposures — accept, remediate, or skip')
+    .argument('[dir]', 'Project directory to scan', '.')
+    .option('-p, --project <n>', 'Project name', 'unknown')
+    .option('--severity <levels>', 'Filter by severity: critical,high,medium,low', undefined)
+    .option('--list', 'Just list reviewable exposures without prompting')
+    .action(async (dir, opts) => {
+    const root = resolve(dir);
+    const { model } = await parseProject({ root, project: opts.project });
+    let exposures = getReviewableExposures(model);
+    // Filter by severity if requested
+    if (opts.severity) {
+        const allowed = new Set(opts.severity.split(',').map(s => s.trim().toLowerCase()));
+        exposures = exposures.filter(e => allowed.has(e.exposure.severity || 'low'));
+        // Re-index after filtering
+        exposures = exposures.map((e, i) => ({ ...e, index: i + 1 }));
+    }
+    if (exposures.length === 0) {
+        console.error('✓ No unmitigated exposures to review.');
+        return;
+    }
+    // List-only mode
+    if (opts.list) {
+        console.error(`\n${exposures.length} unmitigated exposure(s):\n`);
+        for (const r of exposures) {
+            const e = r.exposure;
+            console.error(`  ${r.index}. ${e.asset} → ${e.threat} [${e.severity || '?'}]  (${e.location.file}:${e.location.line})`);
+        }
+        console.error('');
+        return;
+    }
+    // Interactive review
+    const { createInterface } = await import('node:readline');
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    const ask = (q) => new Promise(resolve => rl.question(q, resolve));
+    console.error(`\n  guardlink review — ${exposures.length} unmitigated exposure(s)\n`);
+    const results = [];
+    for (const reviewable of exposures) {
+        console.error(formatExposureForReview(reviewable, exposures.length));
+        console.error('');
+        console.error('  (a) Accept — risk acknowledged and intentional');
+        console.error('  (r) Remediate — mark as planned fix');
+        console.error('  (s) Skip — leave open for now');
+        console.error('  (q) Quit review');
+        console.error('');
+        const choice = (await ask('  Choice [a/r/s/q]: ')).trim().toLowerCase();
+        if (choice === 'q') {
+            console.error('\n  Review ended.\n');
+            break;
+        }
+        if (choice === 'a') {
+            let justification = '';
+            while (!justification) {
+                justification = (await ask('  Justification (required): ')).trim();
+                if (!justification)
+                    console.error('  ⚠  Justification is mandatory for acceptance.');
+            }
+            const result = await applyReviewAction(root, reviewable, { decision: 'accept', justification });
+            results.push(result);
+            console.error(`  ✓ Accepted — ${result.linesInserted} line(s) written to ${reviewable.exposure.location.file}\n`);
+        }
+        else if (choice === 'r') {
+            let note = '';
+            while (!note) {
+                note = (await ask('  Remediation note (required): ')).trim();
+                if (!note)
+                    console.error('  ⚠  Remediation note is mandatory.');
+            }
+            const result = await applyReviewAction(root, reviewable, { decision: 'remediate', justification: note });
+            results.push(result);
+            console.error(`  ✓ Marked for remediation — ${result.linesInserted} line(s) written to ${reviewable.exposure.location.file}\n`);
+        }
+        else {
+            results.push({ exposure: reviewable, action: { decision: 'skip', justification: '' }, linesInserted: 0 });
+            console.error('  — Skipped\n');
+        }
+    }
+    rl.close();
+    if (results.length > 0) {
+        console.error(summarizeReview(results));
+        // Auto-sync agent files if any annotations were written
+        if (results.some(r => r.linesInserted > 0)) {
+            try {
+                // Re-parse to get updated model
+                const { model: newModel } = await parseProject({ root, project: opts.project });
+                const syncResult = syncAgentFiles({ root, model: newModel });
+                if (syncResult.updated.length > 0)
+                    console.error(`↻ Synced ${syncResult.updated.length} agent instruction file(s)`);
+            }
+            catch { }
+        }
+    }
+});
 // ─── config ──────────────────────────────────────────────────────────
 program
     .command('config')
     .description('Manage LLM provider configuration')
     .argument('<action>', 'Action: set, show, clear')
-    .argument('[key]', 'Config key: provider, api-key, model')
+    .argument('[key]', 'Config key: provider, api-key, model, ai-mode, cli-agent')
     .argument('[value]', 'Value to set')
     .option('--global', 'Use global config (~/.config/guardlink/) instead of project')
     .action(async (action, key, value, opts) => {
@@ -562,17 +842,24 @@ program
         case 'show': {
             const config = resolveConfig(root);
             const source = describeConfigSource(root);
+            const projCfg = isGlobal ? loadGlobalConfig() : loadProjectConfig(root);
+            const aiMode = projCfg?.aiMode || 'api';
+            const cliAgent = projCfg?.cliAgent;
+            console.log(`AI Mode:   ${aiMode}${cliAgent ? ` (${cliAgent})` : ''}`);
             if (config) {
                 console.log(`Provider:  ${config.provider}`);
                 console.log(`Model:     ${config.model}`);
                 console.log(`API Key:   ${maskKey(config.apiKey)}`);
                 console.log(`Source:    ${source}`);
             }
-            else {
+            else if (aiMode !== 'cli-agent') {
                 console.log('No LLM configuration found.');
                 console.log('\nSet one with:');
                 console.log('  guardlink config set provider anthropic');
                 console.log('  guardlink config set api-key sk-ant-...');
+                console.log('\nOr use a CLI agent:');
+                console.log('  guardlink config set ai-mode cli-agent');
+                console.log('  guardlink config set cli-agent claude-code');
                 console.log('\nOr set environment variables:');
                 console.log('  export GUARDLINK_LLM_KEY=sk-ant-...');
                 console.log('  export GUARDLINK_LLM_PROVIDER=anthropic');
@@ -582,17 +869,19 @@ program
         case 'set': {
             if (!key || !value) {
                 console.error('Usage: guardlink config set <key> <value>');
-                console.error('Keys: provider, api-key, model');
+                console.error('Keys: provider, api-key, model, ai-mode, cli-agent');
                 process.exit(1);
             }
             const existing = isGlobal
                 ? loadGlobalConfig() || {}
                 : loadProjectConfig(root) || {};
+            const validProviders = ['anthropic', 'openai', 'google', 'openrouter', 'deepseek', 'ollama'];
+            const validAgentIds = AGENTS.map(a => a.id);
             switch (key) {
                 case 'provider':
-                    if (!['anthropic', 'openai', 'openrouter', 'deepseek'].includes(value)) {
+                    if (!validProviders.includes(value)) {
                         console.error(`Unknown provider: ${value}`);
-                        console.error('Available: anthropic, openai, openrouter, deepseek');
+                        console.error(`Available: ${validProviders.join(', ')}`);
                         process.exit(1);
                     }
                     existing.provider = value;
@@ -603,8 +892,25 @@ program
                 case 'model':
                     existing.model = value;
                     break;
+                case 'ai-mode':
+                    if (!['api', 'cli-agent'].includes(value)) {
+                        console.error(`Unknown ai-mode: ${value}`);
+                        console.error('Available: api, cli-agent');
+                        process.exit(1);
+                    }
+                    existing.aiMode = value;
+                    break;
+                case 'cli-agent':
+                    if (!validAgentIds.includes(value)) {
+                        console.error(`Unknown cli-agent: ${value}`);
+                        console.error(`Available: ${validAgentIds.join(', ')}`);
+                        process.exit(1);
+                    }
+                    existing.cliAgent = value;
+                    existing.aiMode = 'cli-agent';
+                    break;
                 default:
-                    console.error(`Unknown config key: ${key}. Use: provider, api-key, model`);
+                    console.error(`Unknown config key: ${key}. Use: provider, api-key, model, ai-mode, cli-agent`);
                     process.exit(1);
             }
             if (isGlobal) {
@@ -676,7 +982,7 @@ program
     .command('tui')
     .description('Interactive TUI — slash commands, AI chat, exposure triage')
     .argument('[dir]', 'project directory', '.')
-    .option('--provider <provider>', 'LLM provider for this session (anthropic, openai, openrouter, deepseek)')
+    .option('--provider <provider>', 'LLM provider for this session (anthropic, openai, google, openrouter, deepseek)')
     .option('--api-key <key>', 'LLM API key for this session (not persisted)')
     .option('--model <model>', 'LLM model override')
     .action(async (dir, opts) => {
@@ -693,31 +999,132 @@ program
     .description('Display GuardLink Annotation Language (GAL) quick reference')
     .action(() => {
     import('chalk').then(({ default: c }) => {
+        const H = (s) => c.bold.cyan(s);
+        const V = (s) => c.bold.cyanBright(s);
+        const K = (s) => c.yellow(s);
+        const D = (s) => c.dim(s);
+        const EX = (s) => c.green(s);
         console.log(gradient(['#00ff41', '#00d4ff'])(ASCII_LOGO));
-        console.log(`${c.bold.bgCyan.black(' GUARDLINK ANNOTATION LANGUAGE (GAL) ')}\n`);
-        console.log(`${c.bold('Syntax:')}`);
-        console.log(`  // @verb <args> [qualifiers] [refs] -- "description"\n`);
-        console.log(`${c.bold('Definition Verbs:')}`);
-        console.log(`  ${c.green('@asset')}    <path> (#id)         ${c.gray('Declare a component')}`);
-        console.log(`  ${c.green('@threat')}   <name> (#id) [sev]   ${c.gray('Declare a threat')}`);
-        console.log(`  ${c.green('@control')}  <name> (#id)         ${c.gray('Declare a security control')}\n`);
-        console.log(`${c.bold('Relationship Verbs:')}`);
-        console.log(`  ${c.green('@mitigates')} <asset> against <threat> using <control>`);
-        console.log(`  ${c.green('@exposes')}   <asset> to <threat> [severity]`);
-        console.log(`  ${c.green('@flows')}     <source> -> <target> via <mechanism>`);
-        console.log(`  ${c.green('@boundary')}  between <asset-a> and <asset-b> (#id)\n`);
-        console.log(`${c.bold('Lifecycle & Metadata:')}`);
-        console.log(`  ${c.green('@handles')}   <data> on <asset>    ${c.gray('Data classification')}`);
-        console.log(`  ${c.green('@owns')}      <owner> for <asset>  ${c.gray('Security ownership')}`);
-        console.log(`  ${c.green('@assumes')}   <asset>              ${c.gray('Security assumption')}`);
-        console.log(`  ${c.green('@shield')}    [-- "reason"]        ${c.gray('AI exclusion marker')}\n`);
-        console.log(`${c.bold('Severity Levels:')}`);
-        console.log(`  [critical] | [high] | [medium] | [low]`);
-        console.log(`  [P0]       | [P1]   | [P2]     | [P3]\n`);
-        console.log(`${c.bold('Data Classifications:')}`);
-        console.log(`  pii | secrets | financial | phi | internal | public\n`);
-        console.log(`${c.bold('Example:')}`);
-        console.log(`  ${c.gray('// @mitigates #api against #sqli using #prepared-stmts -- "Parameterized query"')}\n`);
+        console.log('');
+        console.log(H('  ══════════════════════════════════════════════════════════'));
+        console.log(H('  GAL — GuardLink Annotation Language'));
+        console.log(H('  ══════════════════════════════════════════════════════════'));
+        console.log('');
+        console.log(D('  Annotations live in source code comments. GuardLink parses'));
+        console.log(D('  them to build a live threat model from your codebase.'));
+        console.log('');
+        console.log(D('  Syntax:  @verb  subject  [preposition  object]  [: description]'));
+        console.log('');
+        // ── DEFINITIONS ──
+        console.log(H('  ── Definitions ─────────────────────────────────────────────'));
+        console.log('');
+        console.log(`  ${V('@asset')}  ${K('<path>')}  ${D('[: description]')}`);
+        console.log(D('    Declare a named asset (component, service, data store).'));
+        console.log(D('    Path uses dot notation for hierarchy.'));
+        console.log(EX('    // @asset  api.auth.token_store  : Stores JWT refresh tokens'));
+        console.log(EX('    // @asset  db.users'));
+        console.log('');
+        console.log(`  ${V('@threat')}  ${K('<name>')}  ${D('[severity: critical|high|medium|low]  [: description]')}`);
+        console.log(D('    Declare a named threat. Severity aliases: P0=critical P1=high P2=medium P3=low.'));
+        console.log(EX('    // @threat  SQL Injection  severity:high  : Unsanitized input reaches DB'));
+        console.log(EX('    // @threat  Token Theft  severity:P0'));
+        console.log('');
+        console.log(`  ${V('@control')}  ${K('<name>')}  ${D('[: description]')}`);
+        console.log(D('    Declare a security control (mitigation mechanism).'));
+        console.log(EX('    // @control  Input Validation  : Sanitize all user-supplied strings'));
+        console.log(EX('    // @control  Rate Limiting'));
+        console.log('');
+        // ── RELATIONSHIPS ──
+        console.log(H('  ── Relationships ───────────────────────────────────────────'));
+        console.log('');
+        console.log(`  ${V('@exposes')}  ${K('<asset>')}  ${D('to')}  ${K('<threat>')}  ${D('[severity: ...]  [: description]')}`);
+        console.log(D('    Mark an asset as exposed to a threat at this code location.'));
+        console.log(D('    This is the primary annotation — every exposure creates a finding.'));
+        console.log(EX('    // @exposes  api.auth  to  SQL Injection  severity:high'));
+        console.log(EX('    // @exposes  db.users  to  Token Theft  severity:critical  : No token rotation'));
+        console.log('');
+        console.log(`  ${V('@mitigates')}  ${K('<asset>')}  ${D('against')}  ${K('<threat>')}  ${D('[with')}  ${K('<control>')}${D(']  [: description]')}`);
+        console.log(D('    Mark that a control mitigates a threat on an asset.'));
+        console.log(D('    Closes the exposure — removes it from open findings.'));
+        console.log(EX('    // @mitigates  api.auth  against  SQL Injection  with  Input Validation'));
+        console.log(EX('    // @mitigates  db.users  against  Token Theft  : Rotation implemented in v2'));
+        console.log('');
+        console.log(`  ${V('@accepts')}  ${K('<threat>')}  ${D('on')}  ${K('<asset>')}  ${D('[: reason]')}`);
+        console.log(D('    Explicitly accept a risk. Removes it from open findings.'));
+        console.log(D('    Use when the risk is known and intentionally not mitigated.'));
+        console.log(EX('    // @accepts  Timing Attack  on  api.auth  : Acceptable for current threat model'));
+        console.log('');
+        console.log(`  ${V('@transfers')}  ${K('<threat>')}  ${D('from')}  ${K('<source>')}  ${D('to')}  ${K('<target>')}  ${D('[: description]')}`);
+        console.log(D('    Transfer responsibility for a threat to another asset/team.'));
+        console.log(EX('    // @transfers  DDoS  from  api.gateway  to  cdn.cloudflare  : Handled by CDN layer'));
+        console.log('');
+        // ── DATA FLOWS ──
+        console.log(H('  ── Data Flows & Boundaries ─────────────────────────────────'));
+        console.log('');
+        console.log(`  ${V('@flows')}  ${K('<source>')}  ${D('to')}  ${K('<target>')}  ${D('[via')}  ${K('<mechanism>')}${D(']  [: description]')}`);
+        console.log(D('    Document data movement between components.'));
+        console.log(D('    Appears in the Data Flow Diagram.'));
+        console.log(EX('    // @flows  api.auth  to  db.users  via  TLS 1.3'));
+        console.log(EX('    // @flows  mobile.app  to  api.gateway  via  HTTPS  : User credentials'));
+        console.log('');
+        console.log(`  ${V('@boundary')}  ${K('<asset_a>')}  ${D('and')}  ${K('<asset_b>')}  ${D('[: description]')}`);
+        console.log(D('    Declare a trust boundary between two assets.'));
+        console.log(D('    Groups assets in the Data Flow Diagram.'));
+        console.log(EX('    // @boundary  internet  and  api.gateway  : Public-facing edge'));
+        console.log(EX('    // @boundary  api.gateway  and  db.users  : Internal network boundary'));
+        console.log('');
+        // ── LIFECYCLE ──
+        console.log(H('  ── Lifecycle & Governance ──────────────────────────────────'));
+        console.log('');
+        console.log(`  ${V('@handles')}  ${K('<classification>')}  ${D('on')}  ${K('<asset>')}  ${D('[: description]')}`);
+        console.log(D('    Declare data classification handled by an asset.'));
+        console.log(D('    Classifications: pii  phi  financial  secrets  internal  public'));
+        console.log(EX('    // @handles  pii  on  db.users  : Stores name, email, phone'));
+        console.log(EX('    // @handles  secrets  on  api.auth.token_store'));
+        console.log('');
+        console.log(`  ${V('@owns')}  ${K('<owner>')}  ${K('<asset>')}  ${D('[: description]')}`);
+        console.log(D('    Assign ownership of an asset to a team or person.'));
+        console.log(EX('    // @owns  platform-team  api.auth'));
+        console.log('');
+        console.log(`  ${V('@validates')}  ${K('<control>')}  ${D('on')}  ${K('<asset>')}  ${D('[: description]')}`);
+        console.log(D('    Assert that a control has been validated/tested on an asset.'));
+        console.log(EX('    // @validates  Input Validation  on  api.auth  : Pen-tested 2024-Q3'));
+        console.log('');
+        console.log(`  ${V('@audit')}  ${K('<asset>')}  ${D('[: description]')}`);
+        console.log(D('    Mark that this code path is an audit trail point.'));
+        console.log(EX('    // @audit  db.users  : All writes logged to audit_log table'));
+        console.log('');
+        console.log(`  ${V('@assumes')}  ${K('<asset>')}  ${D('[: description]')}`);
+        console.log(D('    Document a security assumption about an asset.'));
+        console.log(EX('    // @assumes  api.gateway  : Upstream WAF filters malformed requests'));
+        console.log('');
+        console.log(`  ${V('@comment')}  ${D('[: description]')}`);
+        console.log(D('    Free-form developer security note (no structural effect).'));
+        console.log(EX('    // @comment  : TODO — add rate limiting before v2 launch'));
+        console.log('');
+        // ── SHIELD BLOCKS ──
+        console.log(H('  ── Shield Blocks ───────────────────────────────────────────'));
+        console.log('');
+        console.log(`  ${V('@shield:begin')}  ${D('/')}  ${V('@shield:end')}`);
+        console.log(D('    Wrap a code block to mark it as security-sensitive.'));
+        console.log(D('    GuardLink will flag unannotated symbols inside the block.'));
+        console.log(EX('    // @shield:begin'));
+        console.log(EX('    function verifyToken(token: string) { ... }'));
+        console.log(EX('    // @shield:end'));
+        console.log('');
+        // ── TIPS ──
+        console.log(H('  ── Tips ────────────────────────────────────────────────────'));
+        console.log('');
+        console.log(D('  • Annotations work in any comment style: // /* # -- <!-- -->'));
+        console.log(D('  • Place annotations on the line ABOVE the code they describe'));
+        console.log(D('  • Asset names are case-insensitive and normalized (spaces→underscores)'));
+        console.log(D('  • Threat/control names can reference IDs with #id syntax'));
+        console.log(D('  • Run guardlink parse after adding annotations to update the threat model'));
+        console.log(D('  • Run guardlink validate to check for syntax errors and dangling references'));
+        console.log(D('  • Run guardlink annotate to have an AI agent add annotations automatically'));
+        console.log('');
+        console.log(H('  ══════════════════════════════════════════════════════════'));
+        console.log('');
     });
 });
 // If no subcommand given, launch TUI
@@ -745,6 +1152,8 @@ function printStatus(model) {
     console.log(`GuardLink Status: ${model.project}`);
     console.log(`${'─'.repeat(40)}`);
     console.log(`Files scanned:    ${model.source_files}`);
+    console.log(`  Annotated:      ${model.annotated_files.length}`);
+    console.log(`  Not annotated:  ${model.unannotated_files.length}`);
     console.log(`Annotations:      ${model.annotations_parsed}`);
     console.log(`${'─'.repeat(40)}`);
     console.log(`Assets:           ${model.assets.length}`);
@@ -764,4 +1173,14 @@ function printStatus(model) {
     console.log(`Comments:         ${model.comments.length}`);
     console.log(`Shields:          ${model.shields.length}`);
 }
+function printUnannotatedFiles(model) {
+    if (model.unannotated_files.length === 0) {
+        console.log(`\n✓ All source files have GuardLink annotations.`);
+        return;
+    }
+    console.log(`\n⚠  ${model.unannotated_files.length} source file(s) with no annotations:`);
+    for (const f of model.unannotated_files) {
+        console.log(`   ${f}`);
+    }
+}
 //# sourceMappingURL=index.js.map