@rigour-labs/cli 4.2.2 → 4.3.0

package/dist/cli.js

@@ -14,6 +14,7 @@ import { demoCommand } from './commands/demo.js';
 import { hooksInitCommand, hooksCheckCommand } from './commands/hooks.js';
 import { settingsShowCommand, settingsSetKeyCommand, settingsRemoveKeyCommand, settingsSetCommand, settingsGetCommand, settingsResetCommand, settingsPathCommand } from './commands/settings.js';
 import { doctorCommand } from './commands/doctor.js';
+import { brainCommand } from './commands/brain.js';
 import { checkForUpdates } from './utils/version.js';
 import { getCliVersion } from './utils/cli-version.js';
 import chalk from 'chalk';
@@ -21,6 +22,7 @@ const CLI_VERSION = getCliVersion();
 const program = new Command();
 program.addCommand(indexCommand);
 program.addCommand(studioCommand);
+program.addCommand(brainCommand);
 program
     .name('rigour')
     .description('🛡️ Rigour: The Quality Gate Loop for AI-Assisted Engineering')
@@ -91,12 +93,23 @@ program
     .option('--ci', 'CI mode (minimal output, non-zero exit on fail)')
     .option('--json', 'Output report in JSON format')
     .option('-c, --config <path>', 'Path to custom rigour.yml configuration (optional)')
+    .option('--deep', 'Enable deep LLM-powered analysis (local, 350MB one-time download)')
+    .option('--pro', 'Use larger model for deep analysis (900MB, higher quality)')
+    .option('-k, --api-key <key>', 'Use cloud API key instead of local model (BYOK)')
+    .option('--provider <name>', 'Cloud provider: claude, openai, gemini, groq, mistral, together, deepseek, ollama')
+    .option('--api-base-url <url>', 'Custom API base URL')
+    .option('--model-name <name>', 'Override cloud model name')
+    .option('--agents <count>', 'Number of parallel agents for deep scan (cloud-only)', '1')
     .addHelpText('after', `
 Examples:
-  $ rigour scan                       # Zero-config scan in current repo
-  $ rigour scan ./src                 # Scan only src
-  $ rigour scan --json                # Machine-readable output
-  $ rigour scan --ci                  # CI-friendly output
+  $ rigour scan                                     # Zero-config AST scan
+  $ rigour scan --deep                              # Zero-config + local LLM deep analysis
+  $ rigour scan --deep --pro                        # Zero-config + larger local model
+  $ rigour scan --deep -k sk-ant-xxx                # Zero-config + Claude API
+  $ rigour scan --deep --provider groq -k gsk_xxx   # Zero-config + Groq
+  $ rigour scan ./src --deep                        # Deep scan specific directory
+  $ rigour scan --json                              # Machine-readable output
+  $ rigour scan --ci                                # CI-friendly output
     `)
     .action(async (files, options) => {
     await scanCommand(process.cwd(), files, options);
@@ -150,19 +163,22 @@ program
     .option('--cinematic', 'Screen-recording mode: typewriter effects, simulated AI agent, before/after scores')
     .option('--hooks', 'Focus on real-time hooks catching issues as AI writes code')
     .option('--speed <speed>', 'Pacing: fast, normal, slow (default: normal)', 'normal')
+    .option('--repo <url>', 'Clone a real GitHub repo and inject drift into it (festival mode)')
     .addHelpText('after', `
 Examples:
-  $ rigour demo                          # Run the flagship demo
-  $ rigour demo --cinematic              # Screen-recording optimized (great for GIFs)
-  $ rigour demo --cinematic --speed slow # Slower pacing for presentations
-  $ rigour demo --hooks                  # Focus on hooks catching issues
-  $ npx @rigour-labs/cli demo            # Try without installing
+  $ rigour demo                                              # Flagship demo (synthetic project)
+  $ rigour demo --cinematic                                  # Screen-recording optimized
+  $ rigour demo --cinematic --speed slow                     # Slower pacing for presentations
+  $ rigour demo --cinematic --repo https://github.com/fastapi/fastapi  # Live demo on real repo
+  $ rigour demo --hooks                                      # Focus on real-time hooks
+  $ npx @rigour-labs/cli demo                                # Try without installing
     `)
     .action(async (options) => {
     await demoCommand({
         cinematic: !!options.cinematic,
         hooks: !!options.hooks,
         speed: options.speed || 'normal',
+        repo: options.repo,
     });
 });
 program

package/dist/commands/brain.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const brainCommand: Command;

package/dist/commands/brain.js

@@ -0,0 +1,107 @@
+/**
+ * Brain Command — inspect, compact, and reset the local project memory.
+ * Storage lives at ~/.rigour/rigour.db (SQLite, WAL mode).
+ */
+import chalk from 'chalk';
+import { Command } from 'commander';
+export const brainCommand = new Command('brain')
+    .description('Manage Rigour Brain — local project memory (SQLite)')
+    .addHelpText('after', `
+Examples:
+  $ rigour brain                          # Show memory status
+  $ rigour brain --compact                # Prune old data, reclaim disk
+  $ rigour brain --compact --retain 30    # Keep only last 30 days
+  $ rigour brain --reset                  # Wipe all memory and start fresh
+    `)
+    .option('--compact', 'Prune old findings, weak patterns, and reclaim disk space')
+    .option('--retain <days>', 'Days of findings to keep during compact (default: 90)', '90')
+    .option('--reset', 'Delete the entire database and start fresh')
+    .action(async (options) => {
+    const core = await import('@rigour-labs/core');
+    if (options.reset) {
+        await handleReset(core);
+        return;
+    }
+    if (options.compact) {
+        await handleCompact(core, parseInt(options.retain, 10));
+        return;
+    }
+    await handleStatus(core);
+});
+/** Show brain status: DB size, scan count, patterns, hard rules. */
+async function handleStatus(core) {
+    const sizeBytes = core.getDatabaseSize();
+    if (sizeBytes === 0) {
+        console.log(chalk.yellow('No Rigour Brain database found.'));
+        console.log(chalk.dim('Run `rigour scan` or `rigour check` to start building local memory.'));
+        return;
+    }
+    console.log(chalk.bold.cyan('\n🧠 Rigour Brain — Local Memory Status\n'));
+    console.log(chalk.dim(`   Database: ~/.rigour/rigour.db`));
+    console.log(chalk.dim(`   Size:     ${formatBytes(sizeBytes)}\n`));
+    const cwd = process.cwd();
+    const stats = core.getProjectStats(cwd);
+    if (!stats) {
+        console.log(chalk.yellow('   SQLite not available (better-sqlite3 not installed).'));
+        console.log(chalk.dim('   Run: npm install better-sqlite3'));
+        return;
+    }
+    if (stats.totalScans === 0) {
+        console.log(chalk.dim('   No scans recorded for this project yet.'));
+        console.log(chalk.dim('   Run `rigour scan` to start learning.\n'));
+        return;
+    }
+    console.log(`   Scans recorded:    ${chalk.green(stats.totalScans)}`);
+    console.log(`   Learned patterns:  ${chalk.green(stats.learnedPatterns)}`);
+    console.log(`   Hard rules (≥0.9): ${chalk.green(stats.hardRules)}`);
+    if (stats.topPatterns.length > 0) {
+        console.log(chalk.bold('\n   Top Patterns:'));
+        for (const p of stats.topPatterns) {
+            const bar = strengthBar(p.strength);
+            console.log(`   ${bar} ${p.name} ${chalk.dim(`(seen ${p.timesSeen}x)`)}`);
+        }
+    }
+    console.log('');
+}
+/** Compact: prune old findings, weak patterns, VACUUM. */
+async function handleCompact(core, retainDays) {
+    console.log(chalk.bold.cyan(`\n🧠 Compacting Rigour Brain (retain ${retainDays} days)...\n`));
+    const result = core.compactDatabase(retainDays);
+    console.log(`   Findings pruned:   ${chalk.yellow(result.pruned)}`);
+    console.log(`   Patterns removed:  ${chalk.yellow(result.patternsDecayed)}`);
+    console.log(`   Size before:       ${formatBytes(result.sizeBefore)}`);
+    console.log(`   Size after:        ${chalk.green(formatBytes(result.sizeAfter))}`);
+    const saved = result.sizeBefore - result.sizeAfter;
+    if (saved > 0) {
+        console.log(`   Space saved:       ${chalk.green(formatBytes(saved))}`);
+    }
+    console.log('');
+}
+/** Reset: delete the entire database. */
+async function handleReset(core) {
+    const sizeBytes = core.getDatabaseSize();
+    if (sizeBytes === 0) {
+        console.log(chalk.yellow('No Rigour Brain database found. Nothing to reset.'));
+        return;
+    }
+    console.log(chalk.bold.red(`\n⚠️  Resetting Rigour Brain`));
+    console.log(chalk.dim(`   This will delete all scan history, patterns, and learned rules.`));
+    console.log(chalk.dim(`   Database size: ${formatBytes(sizeBytes)}\n`));
+    core.resetDatabase();
+    console.log(chalk.green('   ✓ Brain reset complete. All memory cleared.\n'));
+}
+/** Format bytes as human-readable string. */
+function formatBytes(bytes) {
+    if (bytes === 0)
+        return '0 B';
+    const units = ['B', 'KB', 'MB', 'GB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(1024));
+    return `${(bytes / Math.pow(1024, i)).toFixed(1)} ${units[i]}`;
+}
+/** Visual strength bar for patterns. */
+function strengthBar(strength) {
+    const filled = Math.round(strength * 10);
+    const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);
+    const color = strength >= 0.9 ? chalk.green : strength >= 0.7 ? chalk.yellow : chalk.dim;
+    return color(`[${bar}]`);
+}

package/dist/commands/demo-helpers.d.ts

@@ -2,6 +2,7 @@ export interface DemoOptions {
     cinematic?: boolean;
     hooks?: boolean;
     speed?: 'fast' | 'normal' | 'slow';
+    repo?: string;
 }
 export declare function getMultiplier(options: DemoOptions): number;
 export declare function sleep(ms: number): Promise<void>;

package/dist/commands/demo-injections.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Drift injection patterns for live demo on real repos.
+ * Each injection is a file to write with intentional code issues.
+ */
+export interface DriftInjection {
+    filename: string;
+    description: string;
+    gate: string;
+    severity: 'critical' | 'high' | 'medium';
+    hookMessage: string;
+    code: string;
+}
+/**
+ * Universal injections that work in any TypeScript/JavaScript repo.
+ */
+export declare const TS_INJECTIONS: DriftInjection[];
+/**
+ * Python/FastAPI injections.
+ */
+export declare const PYTHON_INJECTIONS: DriftInjection[];
+/**
+ * Fixed versions of TS injections (for before/after demo).
+ */
+export declare const TS_FIXES: Record<string, string>;
+/**
+ * Detect which injection set to use based on repo contents.
+ */
+export declare function detectInjectionSet(languages: string[]): DriftInjection[];

package/dist/commands/demo-injections.js

@@ -0,0 +1,186 @@
+/**
+ * Drift injection patterns for live demo on real repos.
+ * Each injection is a file to write with intentional code issues.
+ */
+/**
+ * Universal injections that work in any TypeScript/JavaScript repo.
+ */
+export const TS_INJECTIONS = [
+    {
+        filename: 'src/auth-handler.ts',
+        description: 'AI writes authentication with hardcoded secret',
+        gate: 'security-patterns',
+        severity: 'critical',
+        hookMessage: 'Possible hardcoded secret or API key detected',
+        code: [
+            'import express from \'express\';',
+            '',
+            'const API_SECRET = "sk-live-4f3c2b1a0987654321abcdef";',
+            'const DB_PASSWORD = "super_secret_p@ssw0rd!";',
+            '',
+            'export function authenticate(req: express.Request) {',
+            '    const token = req.headers.authorization;',
+            '    if (token === API_SECRET) {',
+            '        return { authenticated: true, role: \'admin\' };',
+            '    }',
+            '    return { authenticated: false };',
+            '}',
+        ].join('\n'),
+    },
+    {
+        filename: 'src/ai-data-loader.ts',
+        description: 'AI hallucinates a non-existent package',
+        gate: 'hallucinated-imports',
+        severity: 'critical',
+        hookMessage: "Import 'ai-data-magic' does not resolve to any installed or known package",
+        code: [
+            'import { z } from \'zod\';',
+            'import { magicParser } from \'ai-data-magic\';',
+            'import { ultraCache } from \'quantum-cache-pro\';',
+            '',
+            'const schema = z.object({',
+            '    name: z.string(),',
+            '    email: z.string().email(),',
+            '});',
+            '',
+            'export function loadData(raw: unknown) {',
+            '    return schema.parse(raw);',
+            '}',
+        ].join('\n'),
+    },
+    {
+        filename: 'src/api-handler.ts',
+        description: 'AI forgets to await an async function',
+        gate: 'promise-safety',
+        severity: 'high',
+        hookMessage: 'Unhandled promise — fetchUser() called without await or .catch()',
+        code: [
+            'export async function fetchUser(id: string) {',
+            '    const res = await fetch(`/api/users/${id}`);',
+            '    return res.json();',
+            '}',
+            '',
+            'export function handleRequest(req: any, res: any) {',
+            '    fetchUser(req.params.id);  // floating promise!',
+            '    res.send(\'Processing...\');',
+            '}',
+        ].join('\n'),
+    },
+];
+/**
+ * Python/FastAPI injections.
+ */
+export const PYTHON_INJECTIONS = [
+    {
+        filename: 'src/middleware/cors_config.py',
+        description: 'AI sets wildcard CORS with credentials',
+        gate: 'security-patterns',
+        severity: 'critical',
+        hookMessage: 'Wildcard CORS with allow_credentials=True — any origin can steal session tokens',
+        code: [
+            'from fastapi.middleware.cors import CORSMiddleware',
+            '',
+            'def setup_cors(app):',
+            '    app.add_middleware(',
+            '        CORSMiddleware,',
+            '        allow_origins=["*"],',
+            '        allow_credentials=True,',
+            '        allow_methods=["*"],',
+            '        allow_headers=["*"],',
+            '    )',
+        ].join('\n'),
+    },
+    {
+        filename: 'src/middleware/logging_middleware.py',
+        description: 'AI logs full request bodies including passwords',
+        gate: 'security-patterns',
+        severity: 'high',
+        hookMessage: 'Request body logged — passwords, tokens, PII exposed in log output',
+        code: [
+            'import logging',
+            'from starlette.middleware.base import BaseHTTPMiddleware',
+            'from starlette.requests import Request',
+            '',
+            'logger = logging.getLogger(__name__)',
+            '',
+            'class LoggingMiddleware(BaseHTTPMiddleware):',
+            '    async def dispatch(self, request: Request, call_next):',
+            '        body = await request.body()',
+            '        logger.info("Body: %s Headers: %s", body, dict(request.headers))',
+            '        response = await call_next(request)',
+            '        return response',
+        ].join('\n'),
+    },
+    {
+        filename: 'src/config.py',
+        description: 'AI hardcodes secrets in config class',
+        gate: 'security-patterns',
+        severity: 'critical',
+        hookMessage: 'Hardcoded SECRET_KEY and database credentials in source code',
+        code: [
+            'class Config:',
+            '    SECRET_KEY = "super-secret-key-12345"',
+            '    DATABASE_URL = "postgresql://admin:p@ssw0rd@prod-db:5432/app"',
+            '    DEBUG = True',
+            '    SESSION_COOKIE_SECURE = False',
+            '    SESSION_COOKIE_HTTPONLY = False',
+        ].join('\n'),
+    },
+];
+/**
+ * Fixed versions of TS injections (for before/after demo).
+ */
+export const TS_FIXES = {
+    'src/auth-handler.ts': [
+        'import express from \'express\';',
+        '',
+        'export function authenticate(req: express.Request) {',
+        '    const token = req.headers.authorization;',
+        '    if (!token) return { authenticated: false };',
+        '    return { authenticated: validateToken(token) };',
+        '}',
+        '',
+        'function validateToken(token: string): boolean {',
+        '    return token.startsWith(\'Bearer \') && token.length > 20;',
+        '}',
+    ].join('\n'),
+    'src/ai-data-loader.ts': [
+        'import { z } from \'zod\';',
+        '',
+        'const schema = z.object({',
+        '    name: z.string(),',
+        '    email: z.string().email(),',
+        '});',
+        '',
+        'export function loadData(raw: unknown) {',
+        '    return schema.parse(raw);',
+        '}',
+    ].join('\n'),
+    'src/api-handler.ts': [
+        'import express from \'express\';',
+        '',
+        'export async function fetchUser(id: string) {',
+        '    const res = await fetch(`/api/users/${id}`);',
+        '    if (!res.ok) throw new Error(`HTTP ${res.status}`);',
+        '    return res.json();',
+        '}',
+        '',
+        'export async function handleRequest(req: express.Request, res: express.Response) {',
+        '    try {',
+        '        const data = await fetchUser(req.params.id);',
+        '        res.json(data);',
+        '    } catch (error) {',
+        '        res.status(500).json({ error: \'Failed to fetch user\' });',
+        '    }',
+        '}',
+    ].join('\n'),
+};
+/**
+ * Detect which injection set to use based on repo contents.
+ */
+export function detectInjectionSet(languages) {
+    if (languages.includes('Python')) {
+        return PYTHON_INJECTIONS;
+    }
+    return TS_INJECTIONS;
+}

package/dist/commands/demo-scaffold.d.ts

@@ -0,0 +1,6 @@
+export declare function scaffoldDemoProject(dir: string): Promise<void>;
+export declare function buildDemoConfig(): Record<string, unknown>;
+export declare function buildDemoPackageJson(): Record<string, unknown>;
+export declare function writeIssueFiles(dir: string): Promise<void>;
+export declare function writeGodFile(dir: string): Promise<void>;
+export declare function generateDemoAudit(dir: string, report: any, outputPath: string): Promise<void>;

package/dist/commands/demo-scaffold.js

@@ -0,0 +1,170 @@
+import fs from 'fs-extra';
+import path from 'path';
+import yaml from 'yaml';
+// ── Scaffold demo project ───────────────────────────────────────────
+export async function scaffoldDemoProject(dir) {
+    const config = buildDemoConfig();
+    await fs.writeFile(path.join(dir, 'rigour.yml'), yaml.stringify(config));
+    await fs.writeJson(path.join(dir, 'package.json'), buildDemoPackageJson(), { spaces: 2 });
+    await fs.ensureDir(path.join(dir, 'src'));
+    await fs.ensureDir(path.join(dir, 'docs'));
+    await writeIssueFiles(dir);
+    await writeGodFile(dir);
+    await fs.writeFile(path.join(dir, 'README.md'), '# Demo Project\n\nThis is a demo project for Rigour.\n');
+}
+export function buildDemoConfig() {
+    return {
+        version: 1,
+        preset: 'api',
+        gates: {
+            max_file_lines: 300,
+            forbid_todos: true,
+            forbid_fixme: true,
+            ast: { complexity: 10, max_params: 5 },
+            security: { enabled: true, block_on_severity: 'high' },
+            hallucinated_imports: { enabled: true, severity: 'critical' },
+            promise_safety: { enabled: true, severity: 'high' },
+        },
+        hooks: { enabled: true, tools: ['claude'] },
+        ignore: ['.git/**', 'node_modules/**'],
+        output: { report_path: 'rigour-report.json' },
+    };
+}
+export function buildDemoPackageJson() {
+    return {
+        name: 'rigour-demo',
+        version: '1.0.0',
+        dependencies: { express: '^4.18.0', zod: '^3.22.0' },
+    };
+}
+export async function writeIssueFiles(dir) {
+    await writeAuthFile(dir);
+    await writeApiHandlerFile(dir);
+    await writeDataLoaderFile(dir);
+    await writeUtilsFile(dir);
+}
+async function writeAuthFile(dir) {
+    await fs.writeFile(path.join(dir, 'src', 'auth.ts'), `
+import express from 'express';
+
+const API_KEY = "sk-live-4f3c2b1a0987654321abcdef";
+const DB_PASSWORD = "super_secret_p@ssw0rd!";
+
+export function authenticate(req: express.Request) {
+    const token = req.headers.authorization;
+    if (token === API_KEY) {
+        return { authenticated: true };
+    }
+    return { authenticated: false };
+}
+
+export function connectDatabase() {
+    return { host: 'prod-db.internal', password: DB_PASSWORD };
+}
+`.trim());
+}
+async function writeApiHandlerFile(dir) {
+    await fs.writeFile(path.join(dir, 'src', 'api-handler.ts'), `
+import express from 'express';
+
+export async function fetchUserData(userId: string) {
+    const response = await fetch(\`https://api.example.com/users/\${userId}\`);
+    return response.json();
+}
+
+export function handleRequest(req: express.Request, res: express.Response) {
+    fetchUserData(req.params.id);
+    res.send('Processing...');
+}
+
+export function batchProcess(ids: string[]) {
+    ids.forEach(id => fetchUserData(id));
+}
+`.trim());
+}
+async function writeDataLoaderFile(dir) {
+    await fs.writeFile(path.join(dir, 'src', 'data-loader.ts'), `
+import { z } from 'zod';
+import { magicParser } from 'ai-data-magic';
+import { ultraCache } from 'quantum-cache-pro';
+
+const schema = z.object({
+    name: z.string(),
+    email: z.string().email(),
+});
+
+export function loadData(raw: unknown) {
+    const parsed = schema.parse(raw);
+    return parsed;
+}
+`.trim());
+}
+async function writeUtilsFile(dir) {
+    await fs.writeFile(path.join(dir, 'src', 'utils.ts'), `
+// NOTE: Claude suggested this but I need to review
+// NOTE: This function has edge cases
+export function formatDate(date: Date): string {
+    return date.toISOString().split('T')[0];
+}
+
+export function sanitizeInput(input: string): string {
+    // NOTE: Add proper sanitization
+    return input.trim();
+}
+`.trim());
+}
+export async function writeGodFile(dir) {
+    const lines = [
+        '// Auto-generated data processing module',
+        'export class DataProcessor {',
+    ];
+    for (let i = 0; i < 60; i++) {
+        lines.push(`    process${i}(data: any) {`);
+        lines.push(`        const result = data.map((x: any) => x * ${i + 1});`);
+        lines.push(`        if (result.length > ${i * 10}) {`);
+        lines.push(`            return result.slice(0, ${i * 10});`);
+        lines.push(`        }`);
+        lines.push(`        return result;`);
+        lines.push(`    }`);
+    }
+    lines.push('}');
+    await fs.writeFile(path.join(dir, 'src', 'god-file.ts'), lines.join('\n'));
+}
+// ── Audit report generator ──────────────────────────────────────────
+export async function generateDemoAudit(dir, report, outputPath) {
+    const stats = report.stats || {};
+    const failures = report.failures || [];
+    const lines = [];
+    lines.push('# Rigour Audit Report — Demo');
+    lines.push('');
+    lines.push(`**Generated:** ${new Date().toISOString()}`);
+    lines.push(`**Status:** ${report.status}`);
+    lines.push(`**Score:** ${stats.score ?? 100}/100`);
+    if (stats.ai_health_score !== undefined) {
+        lines.push(`**AI Health:** ${stats.ai_health_score}/100`);
+    }
+    if (stats.structural_score !== undefined) {
+        lines.push(`**Structural:** ${stats.structural_score}/100`);
+    }
+    lines.push('');
+    lines.push('## Violations');
+    lines.push('');
+    for (let i = 0; i < failures.length; i++) {
+        const f = failures[i];
+        lines.push(`### ${i + 1}. [${(f.severity || 'medium').toUpperCase()}] ${f.title}`);
+        lines.push(`- **ID:** \`${f.id}\``);
+        lines.push(`- **Provenance:** ${f.provenance || 'traditional'}`);
+        lines.push(`- **Details:** ${f.details}`);
+        if (f.files?.length) {
+            lines.push(`- **Files:** ${f.files.join(', ')}`);
+        }
+        if (f.hint) {
+            lines.push(`- **Hint:** ${f.hint}`);
+        }
+        lines.push('');
+    }
+    lines.push('---');
+    lines.push('*Generated by Rigour — https://rigour.run*');
+    lines.push('*Research: https://zenodo.org/records/18673564*');
+    await fs.writeFile(outputPath, lines.join('\n'));
+}

package/dist/commands/demo-scenarios.d.ts

@@ -1,11 +1,7 @@
 import type { DemoOptions } from './demo-helpers.js';
+import { scaffoldDemoProject, generateDemoAudit } from './demo-scaffold.js';
+export { scaffoldDemoProject, generateDemoAudit };
 export declare function runHooksDemo(demoDir: string, options: DemoOptions): Promise<void>;
 export declare function simulateAgentWrite(filename: string, codeLines: string[], gate: string, file: string, message: string, severity: string, options: DemoOptions): Promise<void>;
 export declare function runFullGates(demoDir: string, options: DemoOptions): Promise<void>;
 export declare function runBeforeAfterDemo(demoDir: string, options: DemoOptions): Promise<void>;
-export declare function scaffoldDemoProject(dir: string): Promise<void>;
-export declare function buildDemoConfig(): Record<string, unknown>;
-export declare function buildDemoPackageJson(): Record<string, unknown>;
-export declare function writeIssueFiles(dir: string): Promise<void>;
-export declare function writeGodFile(dir: string): Promise<void>;
-export declare function generateDemoAudit(dir: string, report: any, outputPath: string): Promise<void>;

package/dist/commands/demo-scenarios.js

@@ -6,6 +6,9 @@ import { GateRunner, ConfigSchema } from '@rigour-labs/core';
 import { recordScore } from '@rigour-labs/core';
 import { pause, typewrite } from './demo-helpers.js';
 import { simulateCodeWrite, simulateHookCatch, renderScoreBar, renderTrendChart, displayGateResults, } from './demo-display.js';
+import { scaffoldDemoProject, generateDemoAudit } from './demo-scaffold.js';
+// Re-export scaffolding functions for backward compatibility
+export { scaffoldDemoProject, generateDemoAudit };
 // ── Hooks demo: simulate AI agent → hook catches ────────────────────
 export async function runHooksDemo(demoDir, options) {
     const divider = chalk.cyan('━'.repeat(50));
@@ -195,162 +198,3 @@ export async function handleRequest(req: express.Request, res: express.Response)
         console.error(chalk.red(`Re-check error: ${msg}`));
     }
 }
-// ── Scaffold demo project ───────────────────────────────────────────
-export async function scaffoldDemoProject(dir) {
-    const config = buildDemoConfig();
-    await fs.writeFile(path.join(dir, 'rigour.yml'), yaml.stringify(config));
-    await fs.writeJson(path.join(dir, 'package.json'), buildDemoPackageJson(), { spaces: 2 });
-    await fs.ensureDir(path.join(dir, 'src'));
-    await fs.ensureDir(path.join(dir, 'docs'));
-    await writeIssueFiles(dir);
-    await writeGodFile(dir);
-    await fs.writeFile(path.join(dir, 'README.md'), '# Demo Project\n\nThis is a demo project for Rigour.\n');
-}
-export function buildDemoConfig() {
-    return {
-        version: 1,
-        preset: 'api',
-        gates: {
-            max_file_lines: 300,
-            forbid_todos: true,
-            forbid_fixme: true,
-            ast: { complexity: 10, max_params: 5 },
-            security: { enabled: true, block_on_severity: 'high' },
-            hallucinated_imports: { enabled: true, severity: 'critical' },
-            promise_safety: { enabled: true, severity: 'high' },
-        },
-        hooks: { enabled: true, tools: ['claude'] },
-        ignore: ['.git/**', 'node_modules/**'],
-        output: { report_path: 'rigour-report.json' },
-    };
-}
-export function buildDemoPackageJson() {
-    return {
-        name: 'rigour-demo',
-        version: '1.0.0',
-        dependencies: { express: '^4.18.0', zod: '^3.22.0' },
-    };
-}
-export async function writeIssueFiles(dir) {
-    // Issue 1: Hardcoded API key
-    await fs.writeFile(path.join(dir, 'src', 'auth.ts'), `
-import express from 'express';
-
-const API_KEY = "sk-live-4f3c2b1a0987654321abcdef";
-const DB_PASSWORD = "super_secret_p@ssw0rd!";
-
-export function authenticate(req: express.Request) {
-    const token = req.headers.authorization;
-    if (token === API_KEY) {
-        return { authenticated: true };
-    }
-    return { authenticated: false };
-}
-
-export function connectDatabase() {
-    return { host: 'prod-db.internal', password: DB_PASSWORD };
-}
-`.trim());
-    // Issue 2: Unhandled promise
-    await fs.writeFile(path.join(dir, 'src', 'api-handler.ts'), `
-import express from 'express';
-
-export async function fetchUserData(userId: string) {
-    const response = await fetch(\`https://api.example.com/users/\${userId}\`);
-    return response.json();
-}
-
-export function handleRequest(req: express.Request, res: express.Response) {
-    fetchUserData(req.params.id);
-    res.send('Processing...');
-}
-
-export function batchProcess(ids: string[]) {
-    ids.forEach(id => fetchUserData(id));
-}
-`.trim());
-    // Issue 3: Hallucinated import
-    await fs.writeFile(path.join(dir, 'src', 'data-loader.ts'), `
-import { z } from 'zod';
-import { magicParser } from 'ai-data-magic';
-import { ultraCache } from 'quantum-cache-pro';
-
-const schema = z.object({
-    name: z.string(),
-    email: z.string().email(),
-});
-
-export function loadData(raw: unknown) {
-    const parsed = schema.parse(raw);
-    return parsed;
-}
-`.trim());
-    // Issue 4: Placeholder markers
-    await fs.writeFile(path.join(dir, 'src', 'utils.ts'), `
-// NOTE: Claude suggested this but I need to review
-// NOTE: This function has edge cases
-export function formatDate(date: Date): string {
-    return date.toISOString().split('T')[0];
-}
-
-export function sanitizeInput(input: string): string {
-    // NOTE: Add proper sanitization
-    return input.trim();
-}
-`.trim());
-}
-export async function writeGodFile(dir) {
-    const lines = [
-        '// Auto-generated data processing module',
-        'export class DataProcessor {',
-    ];
-    for (let i = 0; i < 60; i++) {
-        lines.push(`    process${i}(data: any) {`);
-        lines.push(`        const result = data.map((x: any) => x * ${i + 1});`);
-        lines.push(`        if (result.length > ${i * 10}) {`);
-        lines.push(`            return result.slice(0, ${i * 10});`);
-        lines.push(`        }`);
-        lines.push(`        return result;`);
-        lines.push(`    }`);
-    }
-    lines.push('}');
-    await fs.writeFile(path.join(dir, 'src', 'god-file.ts'), lines.join('\n'));
-}
-// ── Audit report generator ──────────────────────────────────────────
-export async function generateDemoAudit(dir, report, outputPath) {
-    const stats = report.stats || {};
-    const failures = report.failures || [];
-    const lines = [];
-    lines.push('# Rigour Audit Report — Demo');
-    lines.push('');
-    lines.push(`**Generated:** ${new Date().toISOString()}`);
-    lines.push(`**Status:** ${report.status}`);
-    lines.push(`**Score:** ${stats.score ?? 100}/100`);
-    if (stats.ai_health_score !== undefined) {
-        lines.push(`**AI Health:** ${stats.ai_health_score}/100`);
-    }
-    if (stats.structural_score !== undefined) {
-        lines.push(`**Structural:** ${stats.structural_score}/100`);
-    }
-    lines.push('');
-    lines.push('## Violations');
-    lines.push('');
-    for (let i = 0; i < failures.length; i++) {
-        const f = failures[i];
-        lines.push(`### ${i + 1}. [${(f.severity || 'medium').toUpperCase()}] ${f.title}`);
-        lines.push(`- **ID:** \`${f.id}\``);
-        lines.push(`- **Provenance:** ${f.provenance || 'traditional'}`);
-        lines.push(`- **Details:** ${f.details}`);
-        if (f.files?.length) {
-            lines.push(`- **Files:** ${f.files.join(', ')}`);
-        }
-        if (f.hint) {
-            lines.push(`- **Hint:** ${f.hint}`);
-        }
-        lines.push('');
-    }
-    lines.push('---');
-    lines.push('*Generated by Rigour — https://rigour.run*');
-    lines.push('*Research: https://zenodo.org/records/18673564*');
-    await fs.writeFile(outputPath, lines.join('\n'));
-}

package/dist/commands/demo.d.ts

@@ -1,9 +1,9 @@
 /**
  * rigour demo
  *
- * Creates a temp project with intentional AI-generated code issues,
- * runs Rigour against it, and shows the full experience.
- * @since v2.17.0 (extended v3.0.0)
+ * Creates a temp project (or clones a real repo) with intentional
+ * AI-generated code issues, runs Rigour against it in real time.
+ * @since v2.17.0 (extended v3.0.0, repo mode v3.1.0)
  */
 import type { DemoOptions } from './demo-helpers.js';
 export type { DemoOptions } from './demo-helpers.js';

package/dist/commands/demo.js

@@ -1,22 +1,31 @@
 /**
  * rigour demo
  *
- * Creates a temp project with intentional AI-generated code issues,
- * runs Rigour against it, and shows the full experience.
- * @since v2.17.0 (extended v3.0.0)
+ * Creates a temp project (or clones a real repo) with intentional
+ * AI-generated code issues, runs Rigour against it in real time.
+ * @since v2.17.0 (extended v3.0.0, repo mode v3.1.0)
  */
 import path from 'path';
 import fs from 'fs-extra';
 import os from 'os';
 import chalk from 'chalk';
+import { execSync } from 'child_process';
 import { pause, typewrite } from './demo-helpers.js';
-import { printBanner, printPlantedIssues, printClosing } from './demo-display.js';
+import { printBanner, printPlantedIssues, printClosing, simulateCodeWrite, simulateHookCatch } from './demo-display.js';
 import { runHooksDemo, runFullGates, runBeforeAfterDemo, scaffoldDemoProject } from './demo-scenarios.js';
-// ── Main demo command ───────────────────────────────────────────────
+import { TS_INJECTIONS, PYTHON_INJECTIONS, TS_FIXES } from './demo-injections.js';
 export async function demoCommand(options = {}) {
     const isCinematic = !!options.cinematic;
     const showHooks = !!options.hooks || isCinematic;
     printBanner(isCinematic);
+    if (options.repo) {
+        await runRepoDemo(options);
+        return;
+    }
+    // Original synthetic demo flow
+    await runSyntheticDemo(options, isCinematic, showHooks);
+}
+async function runSyntheticDemo(options, isCinematic, showHooks) {
     if (isCinematic) {
         await typewrite(chalk.bold('Rigour Demo — Watch AI code governance in real time.\n'), options);
         await pause(800, options);
@@ -24,7 +33,6 @@ export async function demoCommand(options = {}) {
     else {
         console.log(chalk.bold('Rigour Demo — See AI code governance in action.\n'));
     }
-    // 1. Create temp project
     const demoDir = path.join(os.tmpdir(), `rigour-demo-${Date.now()}`);
     await fs.ensureDir(demoDir);
     if (isCinematic) {
@@ -36,19 +44,97 @@ export async function demoCommand(options = {}) {
     }
     await scaffoldDemoProject(demoDir);
     console.log(chalk.green('✓ Demo project scaffolded.\n'));
-    // 2. Simulate AI agent writing flawed code (cinematic/hooks mode)
     if (showHooks) {
         await runHooksDemo(demoDir, options);
     }
     else {
         printPlantedIssues();
     }
-    // 3. Run full quality gates
     await runFullGates(demoDir, options);
-    // 4. Show "after fix" improvement (cinematic only)
     if (isCinematic) {
         await runBeforeAfterDemo(demoDir, options);
     }
-    // 5. Closing
     printClosing(isCinematic);
 }
+async function runRepoDemo(options) {
+    const repoUrl = options.repo;
+    const repoName = extractRepoName(repoUrl);
+    await typewrite(chalk.bold(`Rigour Live Demo — Real repo, real issues, real-time.\n`), options);
+    await pause(600, options);
+    // 1. Clone
+    const demoDir = path.join(os.tmpdir(), `rigour-demo-${repoName}-${Date.now()}`);
+    await typewrite(chalk.dim(`Cloning ${repoUrl}...`), options);
+    if (!/^https?:\/\/[^\s;|&]+$/.test(repoUrl)) {
+        console.error(chalk.red('Invalid repo URL. Use https://github.com/owner/repo format.'));
+        return;
+    }
+    execSync(`git clone --depth 1 ${repoUrl} ${demoDir}`, { stdio: 'pipe' });
+    console.log(chalk.green(`✓ Cloned ${repoName}\n`));
+    await pause(400, options);
+    // 2. Detect language, ensure rigour.yml, pick injections
+    const isPython = await detectPythonRepo(demoDir);
+    const injections = isPython ? PYTHON_INJECTIONS : TS_INJECTIONS;
+    // Ensure a rigour.yml exists (real repos may not have one)
+    if (!await fs.pathExists(path.join(demoDir, 'rigour.yml'))) {
+        const { buildDemoConfig } = await import('./demo-scaffold.js');
+        const yaml = await import('yaml');
+        await fs.writeFile(path.join(demoDir, 'rigour.yml'), yaml.default.stringify(buildDemoConfig()));
+    }
+    // 3. Show "AI agent modifying codebase..."
+    const divider = chalk.cyan('━'.repeat(50));
+    console.log(divider);
+    await typewrite(chalk.bold.magenta('  Simulating AI agent writing code with hooks active...\n'), options);
+    await pause(600, options);
+    // 4. Inject drift and simulate hook catches
+    for (const injection of injections) {
+        await injectAndCatch(demoDir, injection, options);
+    }
+    console.log('');
+    console.log(chalk.magenta.bold(`  Hooks caught ${injections.length} issues in real time — before the commit.`));
+    console.log(divider);
+    console.log('');
+    await pause(1000, options);
+    // 5. Run full gates
+    await runFullGates(demoDir, options);
+    // 6. Fix and show improvement (cinematic)
+    if (options.cinematic && !isPython) {
+        await runRepoBeforeAfter(demoDir, options);
+    }
+    // 7. Closing
+    printClosing(true);
+}
+async function injectAndCatch(demoDir, injection, options) {
+    const filePath = path.join(demoDir, injection.filename);
+    await fs.ensureDir(path.dirname(filePath));
+    console.log(chalk.blue.bold(`  Agent: Write → ${injection.filename}`));
+    await simulateCodeWrite(injection.filename, injection.code.split('\n'), options);
+    await fs.writeFile(filePath, injection.code);
+    await simulateHookCatch(injection.gate, injection.filename, injection.hookMessage, injection.severity, options);
+    console.log('');
+}
+async function runRepoBeforeAfter(demoDir, options) {
+    console.log(chalk.bold.green('Simulating agent fixing issues...\n'));
+    await pause(600, options);
+    for (const [filename, fixedCode] of Object.entries(TS_FIXES)) {
+        await typewrite(chalk.dim(`  Agent: Fixing ${filename}...`), options);
+        await fs.writeFile(path.join(demoDir, filename), fixedCode);
+        console.log(chalk.green(`  ✓ Fixed: ${filename}`));
+        await pause(300, options);
+    }
+    console.log('');
+    await pause(500, options);
+    console.log(chalk.bold.blue('Re-running quality gates after fixes...\n'));
+    await runFullGates(demoDir, options);
+}
+function extractRepoName(url) {
+    const match = url.match(/([^/]+?)(?:\.git)?$/);
+    return match ? match[1] : 'repo';
+}
+async function detectPythonRepo(dir) {
+    const pyFiles = ['requirements.txt', 'setup.py', 'pyproject.toml', 'Pipfile'];
+    for (const f of pyFiles) {
+        if (await fs.pathExists(path.join(dir, f)))
+            return true;
+    }
+    return false;
+}

package/dist/commands/scan-deep.d.ts

@@ -0,0 +1,8 @@
+import type { Report, Config } from '@rigour-labs/core';
+import type { DeepOptions } from '@rigour-labs/core';
+import type { ScanOptions, StackSignals } from './scan.js';
+export declare function buildDeepOpts(options: ScanOptions, isSilent: boolean): DeepOptions & {
+    onProgress?: (msg: string) => void;
+};
+export declare function persistDeepResults(cwd: string, report: Report, isDeep: boolean, options: ScanOptions): void;
+export declare function renderDeepScanResults(report: Report, stackSignals: StackSignals, config: Config, cwd: string): void;

package/dist/commands/scan-deep.js

@@ -0,0 +1,164 @@
+import chalk from 'chalk';
+import { getScoreTrend, resolveDeepOptions } from '@rigour-labs/core';
+import { extractHallucinatedImports, renderCoverageWarnings } from './scan.js';
+export function buildDeepOpts(options, isSilent) {
+    const resolved = resolveDeepOptions({
+        apiKey: options.apiKey,
+        provider: options.provider,
+        apiBaseUrl: options.apiBaseUrl,
+        modelName: options.modelName,
+    });
+    const hasApiKey = !!resolved.apiKey;
+    const agentCount = Math.max(1, parseInt(options.agents || '1', 10) || 1);
+    return {
+        enabled: true,
+        pro: !!options.pro,
+        apiKey: resolved.apiKey,
+        provider: hasApiKey ? (resolved.provider || 'claude') : 'local',
+        apiBaseUrl: resolved.apiBaseUrl,
+        modelName: resolved.modelName,
+        agents: agentCount > 1 ? agentCount : undefined,
+        onProgress: isSilent ? undefined : (msg) => {
+            process.stderr.write(msg + '\n');
+        },
+    };
+}
+export function persistDeepResults(cwd, report, isDeep, options) {
+    if (!isDeep)
+        return;
+    try {
+        import('@rigour-labs/core').then(({ openDatabase, insertScan, insertFindings }) => {
+            const db = openDatabase();
+            if (!db)
+                return;
+            const repoName = require('path').basename(cwd);
+            const scanId = insertScan(db, repoName, report, {
+                deepTier: report.stats.deep?.tier || (options.pro ? 'pro' : 'deep'),
+                deepModel: report.stats.deep?.model,
+            });
+            insertFindings(db, scanId, report.failures);
+            db.close();
+        }).catch(() => { });
+    }
+    catch { /* silent */ }
+}
+function severityIcon(s) {
+    switch (s) {
+        case 'critical': return chalk.red.bold('CRIT');
+        case 'high': return chalk.red('HIGH');
+        case 'medium': return chalk.yellow('MED ');
+        case 'low': return chalk.dim('LOW ');
+        case 'info': return chalk.dim('INFO');
+        default: return chalk.yellow('MED ');
+    }
+}
+export function renderDeepScanResults(report, stackSignals, config, cwd) {
+    const stats = report.stats;
+    const aiHealth = stats.ai_health_score ?? 100;
+    const codeQuality = stats.code_quality_score ?? stats.structural_score ?? 100;
+    const overall = stats.score ?? 100;
+    const scoreColor = (s) => s >= 80 ? chalk.green : s >= 60 ? chalk.yellow : chalk.red;
+    console.log(`  ${chalk.bold('AI Health:')}     ${scoreColor(aiHealth).bold(aiHealth + '/100')}`);
+    console.log(`  ${chalk.bold('Code Quality:')}  ${scoreColor(codeQuality).bold(codeQuality + '/100')}`);
+    console.log(`  ${chalk.bold('Overall:')}       ${scoreColor(overall).bold(overall + '/100')}`);
+    console.log('');
+    const isLocal = stats.deep?.tier ? stats.deep.tier !== 'cloud' : true;
+    if (isLocal) {
+        console.log(chalk.green('  🔒 Local sidecar execution. Code remains on this machine.'));
+    }
+    else {
+        console.log(chalk.yellow(`  ☁️  Cloud execution. Code context sent to ${stats.deep?.tier || 'cloud'} API.`));
+    }
+    if (stats.deep) {
+        const model = stats.deep.model || 'unknown';
+        const ms = stats.deep.total_ms ? ` ${(stats.deep.total_ms / 1000).toFixed(1)}s` : '';
+        console.log(chalk.dim(`  Model: ${model} (${stats.deep.tier})${ms}`));
+    }
+    console.log('');
+    renderScaryHeadlines(report.failures);
+    renderCategorizedFindings(report.failures);
+    renderCoverageWarnings(stackSignals);
+    const trend = getScoreTrend(cwd);
+    if (trend && trend.recentScores.length >= 3) {
+        const arrow = trend.direction === 'improving' ? '↑' : trend.direction === 'degrading' ? '↓' : '→';
+        const color = trend.direction === 'improving' ? chalk.green : trend.direction === 'degrading' ? chalk.red : chalk.dim;
+        console.log(color(`\nTrend: ${trend.recentScores.join(' → ')} ${arrow}`));
+    }
+    console.log(chalk.yellow(`\nFull report: ${config.output.report_path}`));
+    if (report.status === 'FAIL') {
+        console.log(chalk.yellow('Fix packet:  rigour-fix-packet.json'));
+    }
+    console.log(chalk.dim(`Finished in ${(stats.duration_ms / 1000).toFixed(1)}s | Score: ${overall}/100`));
+    console.log('');
+    if (report.status === 'FAIL') {
+        console.log(chalk.bold('Next steps:'));
+        console.log(`  ${chalk.cyan('rigour explain')}      — plain-English fix suggestions`);
+        console.log(`  ${chalk.cyan('rigour init')}         — add quality gates to your project`);
+    }
+    else {
+        console.log(chalk.green.bold('✓ This repo is clean.'));
+    }
+}
+function renderScaryHeadlines(failures) {
+    const secrets = failures.filter(f => f.id === 'security-patterns' && f.severity === 'critical');
+    const fakeImports = extractHallucinatedImports(failures);
+    const phantoms = failures.filter(f => f.id === 'phantom-apis');
+    let count = 0;
+    if (secrets.length > 0) {
+        console.log(chalk.red.bold(`🔑 HARDCODED SECRETS: ${secrets.length} credential(s) exposed`));
+        count++;
+    }
+    if (fakeImports.length > 0) {
+        const unique = [...new Set(fakeImports)];
+        console.log(chalk.red.bold(`📦 HALLUCINATED PACKAGES: ${unique.length} import(s) don't exist`));
+        count++;
+    }
+    if (phantoms.length > 0) {
+        console.log(chalk.red.bold(`👻 PHANTOM APIs: ${phantoms.length} call(s) to non-existent methods`));
+        count++;
+    }
+    if (count > 0)
+        console.log('');
+}
+function renderCategorizedFindings(failures) {
+    const deep = failures.filter((f) => f.provenance === 'deep-analysis');
+    const aiDrift = failures.filter((f) => f.provenance === 'ai-drift');
+    const security = failures.filter((f) => f.provenance === 'security');
+    const other = failures.filter((f) => f.provenance !== 'deep-analysis' && f.provenance !== 'ai-drift' && f.provenance !== 'security');
+    if (deep.length > 0) {
+        console.log(chalk.bold(`  ── Deep Analysis (${deep.length} verified) ──\n`));
+        for (const f of deep.slice(0, 6)) {
+            const desc = (f.details || f.title).substring(0, 120);
+            console.log(`  ${severityIcon(f.severity)} [${f.id}] ${f.files?.[0] || ''}`);
+            console.log(`       ${desc}`);
+            if (f.hint)
+                console.log(`       → ${f.hint}`);
+            console.log('');
+        }
+    }
+    if (aiDrift.length > 0) {
+        console.log(chalk.bold(`  ── AI Drift (${aiDrift.length}) ──\n`));
+        for (const f of aiDrift.slice(0, 5)) {
+            console.log(`  ${severityIcon(f.severity)} ${f.title}`);
+            if (f.files?.length)
+                console.log(chalk.dim(`       ${f.files.slice(0, 2).join(', ')}`));
+            console.log('');
+        }
+    }
+    if (security.length > 0) {
+        console.log(chalk.bold(`  ── Security (${security.length}) ──\n`));
+        for (const f of security.slice(0, 5)) {
+            console.log(`  ${severityIcon(f.severity)} ${f.title}`);
+            if (f.hint)
+                console.log(chalk.cyan(`       ${f.hint}`));
+            console.log('');
+        }
+    }
+    if (other.length > 0) {
+        console.log(chalk.bold(`  ── Quality (${other.length}) ──\n`));
+        for (const f of other.slice(0, 5)) {
+            console.log(`  ${severityIcon(f.severity)} [${f.id}] ${f.title}`);
+            console.log('');
+        }
+    }
+}

package/dist/commands/scan.d.ts

@@ -1,6 +1,22 @@
+import { type Failure } from '@rigour-labs/core';
 export interface ScanOptions {
     ci?: boolean;
     json?: boolean;
     config?: string;
+    deep?: boolean;
+    pro?: boolean;
+    apiKey?: string;
+    provider?: string;
+    apiBaseUrl?: string;
+    modelName?: string;
+    agents?: string;
+}
+export interface StackSignals {
+    languages: string[];
+    hasDocker: boolean;
+    hasTerraform: boolean;
+    hasSql: boolean;
 }
 export declare function scanCommand(cwd: string, files?: string[], options?: ScanOptions): Promise<void>;
+export declare function renderCoverageWarnings(stackSignals: StackSignals): void;
+export declare function extractHallucinatedImports(failures: Failure[]): string[];

package/dist/commands/scan.js

@@ -4,6 +4,7 @@ import chalk from 'chalk';
 import yaml from 'yaml';
 import { globby } from 'globby';
 import { GateRunner, ConfigSchema, DiscoveryService, FixPacketService, recordScore, getScoreTrend, } from '@rigour-labs/core';
+import { buildDeepOpts, persistDeepResults, renderDeepScanResults } from './scan-deep.js';
 // Exit codes per spec
 const EXIT_PASS = 0;
 const EXIT_FAIL = 1;
@@ -48,43 +49,30 @@ export async function scanCommand(cwd, files = [], options = {}) {
     try {
         const scanCtx = await resolveScanConfig(cwd, options);
         const stackSignals = await detectStackSignals(cwd);
-        if (!options.ci && !options.json) {
-            renderScanHeader(scanCtx, stackSignals);
+        const isDeep = !!options.deep || !!options.pro || !!options.apiKey;
+        const isSilent = !!options.ci || !!options.json;
+        if (!isSilent) {
+            renderScanHeader(scanCtx, stackSignals, isDeep);
         }
         const runner = new GateRunner(scanCtx.config);
-        const report = await runner.run(cwd, files.length > 0 ? files : undefined);
-        // Write machine report and score history
-        const reportPath = path.join(cwd, scanCtx.config.output.report_path);
-        await fs.writeJson(reportPath, report, { spaces: 2 });
-        recordScore(cwd, report);
-        // Generate fix packet on failure
-        if (report.status === 'FAIL') {
-            const fixPacketService = new FixPacketService();
-            const fixPacket = fixPacketService.generate(report, scanCtx.config);
-            const fixPacketPath = path.join(cwd, 'rigour-fix-packet.json');
-            await fs.writeJson(fixPacketPath, fixPacket, { spaces: 2 });
-        }
+        const deepOpts = isDeep ? buildDeepOpts(options, isSilent) : undefined;
+        const report = await runner.run(cwd, files.length > 0 ? files : undefined, deepOpts);
+        await writeReportArtifacts(cwd, report, scanCtx.config);
+        persistDeepResults(cwd, report, isDeep, options);
         if (options.json) {
-            process.stdout.write(JSON.stringify({
-                mode: scanCtx.mode,
-                preset: scanCtx.detectedPreset ?? scanCtx.config.preset,
-                paradigm: scanCtx.detectedParadigm ?? scanCtx.config.paradigm,
-                stack: stackSignals,
-                report,
-            }, null, 2) + '\n');
-            process.exit(report.status === 'PASS' ? EXIT_PASS : EXIT_FAIL);
+            outputJson(scanCtx, stackSignals, report);
+            return;
         }
         if (options.ci) {
-            const score = report.stats.score ?? 0;
-            if (report.status === 'PASS') {
-                console.log(`PASS (${score}/100)`);
-            }
-            else {
-                console.log(`FAIL: ${report.failures.length} violation(s) | Score: ${score}/100`);
-            }
-            process.exit(report.status === 'PASS' ? EXIT_PASS : EXIT_FAIL);
+            outputCi(report);
+            return;
+        }
+        if (isDeep) {
+            renderDeepScanResults(report, stackSignals, scanCtx.config, cwd);
+        }
+        else {
+            renderScanResults(report, stackSignals, scanCtx.config.output.report_path, cwd);
         }
-        renderScanResults(report, stackSignals, scanCtx.config.output.report_path, cwd);
         process.exit(report.status === 'PASS' ? EXIT_PASS : EXIT_FAIL);
     }
     catch (error) {
@@ -99,6 +87,36 @@ export async function scanCommand(cwd, files = [], options = {}) {
         process.exit(EXIT_INTERNAL_ERROR);
     }
 }
+async function writeReportArtifacts(cwd, report, config) {
+    const reportPath = path.join(cwd, config.output.report_path);
+    await fs.writeJson(reportPath, report, { spaces: 2 });
+    recordScore(cwd, report);
+    if (report.status === 'FAIL') {
+        const fixPacketService = new FixPacketService();
+        const fixPacket = fixPacketService.generate(report, config);
+        await fs.writeJson(path.join(cwd, 'rigour-fix-packet.json'), fixPacket, { spaces: 2 });
+    }
+}
+function outputJson(scanCtx, stackSignals, report) {
+    process.stdout.write(JSON.stringify({
+        mode: scanCtx.mode,
+        preset: scanCtx.detectedPreset ?? scanCtx.config.preset,
+        paradigm: scanCtx.detectedParadigm ?? scanCtx.config.paradigm,
+        stack: stackSignals,
+        report,
+    }, null, 2) + '\n');
+    process.exit(report.status === 'PASS' ? EXIT_PASS : EXIT_FAIL);
+}
+function outputCi(report) {
+    const score = report.stats.score ?? 0;
+    if (report.status === 'PASS') {
+        console.log(`PASS (${score}/100)`);
+    }
+    else {
+        console.log(`FAIL: ${report.failures.length} violation(s) | Score: ${score}/100`);
+    }
+    process.exit(report.status === 'PASS' ? EXIT_PASS : EXIT_FAIL);
+}
 async function resolveScanConfig(cwd, options) {
     const explicitConfig = options.config ? path.resolve(cwd, options.config) : undefined;
     const defaultConfig = path.join(cwd, 'rigour.yml');
@@ -142,9 +160,12 @@ async function detectStackSignals(cwd) {
         hasSql: sqlMatches.length > 0,
     };
 }
-function renderScanHeader(scanCtx, stackSignals) {
-    console.log(chalk.bold.cyan('\nRigour Scan'));
-    console.log(chalk.dim('Zero-config security and AI-drift sweep using existing Rigour gates.\n'));
+function renderScanHeader(scanCtx, stackSignals, isDeep = false) {
+    console.log(chalk.bold.cyan('\nRigour Scan') + (isDeep ? chalk.blue.bold(' + Deep Analysis') : ''));
+    const desc = isDeep
+        ? 'Zero-config sweep with LLM-powered deep analysis.'
+        : 'Zero-config security and AI-drift sweep using existing Rigour gates.';
+    console.log(chalk.dim(desc + '\n'));
     const modeLabel = scanCtx.mode === 'existing-config'
         ? `Using existing config: ${path.basename(scanCtx.configPath || 'rigour.yml')}`
         : 'Auto-discovered config (no rigour.yml required)';
@@ -244,7 +265,7 @@ function renderScanResults(report, stackSignals, reportPath, cwd) {
         console.log(`  ${chalk.cyan('rigour init')}  — write quality gates to rigour.yml + CI config`);
     }
 }
-function renderCoverageWarnings(stackSignals) {
+export function renderCoverageWarnings(stackSignals) {
     const gaps = [];
     for (const language of stackSignals.languages) {
         const supportedBy = Object.entries(HEADLINE_GATE_SUPPORT)
@@ -265,7 +286,7 @@ function renderCoverageWarnings(stackSignals) {
         gaps.forEach(gap => console.log(chalk.yellow(`  - ${gap}`)));
     }
 }
-function extractHallucinatedImports(failures) {
+export function extractHallucinatedImports(failures) {
     const fakeImports = [];
     for (const failure of failures) {
         if (failure.id !== 'hallucinated-imports')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigour-labs/cli",
-  "version": "4.2.2",
+  "version": "4.3.0",
   "description": "CLI quality gates for AI-generated code. Forces AI agents (Claude, Cursor, Copilot) to meet strict engineering standards with PASS/FAIL enforcement.",
   "license": "MIT",
   "homepage": "https://rigour.run",
@@ -44,7 +44,7 @@
     "inquirer": "9.2.16",
     "ora": "^8.0.1",
     "yaml": "^2.8.2",
-    "@rigour-labs/core": "4.2.2"
+    "@rigour-labs/core": "4.3.0"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",