@rigour-labs/cli 2.21.2 → 3.0.0

package/README.md

@@ -35,6 +35,7 @@ Agent writes code → Rigour checks → FAIL? → Fix Packet → Agent retries
 
 ## ⚙️ Quality Gates
 
+### Structural & Security Gates
 | Gate | Description |
 |:---|:---|
 | **File Size** | Max lines per file (default: 300-500) |
@@ -42,9 +43,21 @@ Agent writes code → Rigour checks → FAIL? → Fix Packet → Agent retries
 | **Complexity** | Cyclomatic complexity limits (AST-based) |
 | **Required Docs** | SPEC.md, ARCH.md, README must exist |
 | **File Guard** | Protected paths, max files changed |
-| **Security Patterns** | XSS, SQL injection, hardcoded secrets, command injection (enabled by default) |
+| **Security Patterns** | XSS, SQL injection, hardcoded secrets, command injection |
 | **Context Alignment** | Prevents drift by anchoring on project patterns |
 
+### AI-Native Drift Detection (v2.16+)
+| Gate | Description |
+|:---|:---|
+| **Duplication Drift** | Near-identical functions across files — AI re-invents what it forgot |
+| **Hallucinated Imports** | Imports referencing modules that don't exist (JS/TS, Python, Go, Ruby, C#) |
+| **Inconsistent Error Handling** | Same error type handled differently across agent sessions |
+| **Context Window Artifacts** | Quality degradation within a file — clean top, messy bottom |
+| **Async & Error Safety** | Unsafe async/promise patterns, unhandled errors across 6 languages |
+
+### Multi-Language Support
+All gates support **TypeScript, JavaScript, Python, Go, Ruby, and C#/.NET**.
+
 ## 🛠️ Commands
 
 | Command | Purpose |

package/dist/cli.js

@@ -8,6 +8,8 @@ import { guideCommand } from './commands/guide.js';
 import { setupCommand } from './commands/setup.js';
 import { indexCommand } from './commands/index.js';
 import { studioCommand } from './commands/studio.js';
+import { exportAuditCommand } from './commands/export-audit.js';
+import { demoCommand } from './commands/demo.js';
 import { checkForUpdates } from './utils/version.js';
 import chalk from 'chalk';
 const CLI_VERSION = '2.0.0';
@@ -29,7 +31,7 @@ program
 program
     .command('init')
     .description('Initialize Rigour in the current directory')
-    .option('-p, --preset <name>', 'Project preset (ui, api, infra, data)')
+    .option('-p, --preset <name>', 'Project preset (ui, api, infra, data, healthcare, fintech, government)')
     .option('--paradigm <name>', 'Coding paradigm (oop, functional, minimal)')
     .option('--ide <name>', 'Target IDE (cursor, vscode, all). Auto-detects if not specified.')
     .option('--dry-run', 'Show detected configuration without writing files')
@@ -37,10 +39,12 @@ program
     .option('-f, --force', 'Force re-initialization, overwriting existing rigour.yml')
     .addHelpText('after', `
 Examples:
-  $ rigour init                        # Auto-discover role & paradigm
-  $ rigour init --preset api --explain # Force API role and show why
-  $ rigour init --ide vscode           # Only create VS Code compatible files
-  $ rigour init --ide all              # Create files for all IDEs
+  $ rigour init                            # Auto-discover role & paradigm
+  $ rigour init --preset api --explain     # Force API role and show why
+  $ rigour init --preset healthcare        # HIPAA-compliant quality gates
+  $ rigour init --preset fintech           # SOC2/PCI-DSS quality gates
+  $ rigour init --preset government        # FedRAMP/NIST quality gates
+  $ rigour init --ide all                  # Create files for all IDEs
     `)
     .action(async (options) => {
     await initCommand(process.cwd(), options);
@@ -91,6 +95,33 @@ Examples:
         failFast: !!options.failFast
     });
 });
+program
+    .command('export-audit')
+    .description('Generate a compliance audit package from the last check')
+    .option('-f, --format <type>', 'Output format: json or md', 'json')
+    .option('-o, --output <path>', 'Custom output file path')
+    .option('--run', 'Run a fresh rigour check before exporting')
+    .addHelpText('after', `
+Examples:
+  $ rigour export-audit                      # Export JSON audit package
+  $ rigour export-audit --format md          # Export Markdown report
+  $ rigour export-audit --run                # Run check first, then export
+  $ rigour export-audit -o audit.json        # Custom output path
+    `)
+    .action(async (options) => {
+    await exportAuditCommand(process.cwd(), options);
+});
+program
+    .command('demo')
+    .description('Run a live demo — see Rigour catch AI drift, security issues, and structural violations')
+    .addHelpText('after', `
+Examples:
+  $ rigour demo                          # Run the flagship demo
+  $ npx @rigour-labs/cli demo            # Try without installing
+    `)
+    .action(async () => {
+    await demoCommand();
+});
 program
     .command('guide')
     .description('Show the interactive engineering guide')

package/dist/commands/check.js

@@ -2,7 +2,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import chalk from 'chalk';
 import yaml from 'yaml';
-import { GateRunner, ConfigSchema } from '@rigour-labs/core';
+import { GateRunner, ConfigSchema, recordScore, getScoreTrend } from '@rigour-labs/core';
 import inquirer from 'inquirer';
 import { randomUUID } from 'crypto';
 // Exit codes per spec
@@ -57,6 +57,8 @@ export async function checkCommand(cwd, files = [], options = {}) {
         // Write machine report
         const reportPath = path.join(cwd, config.output.report_path);
         await fs.writeJson(reportPath, report, { spaces: 2 });
+        // Record score for trend tracking
+        recordScore(cwd, report);
         await logStudioEvent(cwd, {
             type: "tool_response",
             requestId,
@@ -81,15 +83,18 @@ export async function checkCommand(cwd, files = [], options = {}) {
             });
             return; // Wait for write callback
         }
-        // CI mode: minimal output
+        // CI mode: minimal output with score
         if (options.ci) {
             if (report.status === 'PASS') {
-                console.log('PASS');
+                const scoreStr = report.stats.score !== undefined ? ` (${report.stats.score}/100)` : '';
+                console.log(`PASS${scoreStr}`);
             }
             else {
-                console.log(`FAIL: ${report.failures.length} violation(s)`);
+                const scoreStr = report.stats.score !== undefined ? ` Score: ${report.stats.score}/100` : '';
+                console.log(`FAIL: ${report.failures.length} violation(s)${scoreStr}`);
                 report.failures.forEach((f) => {
-                    console.log(`  - [${f.id}] ${f.title}`);
+                    const sev = (f.severity || 'medium').toUpperCase();
+                    console.log(`  - [${sev}] [${f.id}] ${f.title}`);
                 });
             }
             process.exit(report.status === 'PASS' ? EXIT_PASS : EXIT_FAIL);
@@ -104,21 +109,73 @@ export async function checkCommand(cwd, files = [], options = {}) {
         }
         else {
             console.log(chalk.red.bold('✘ FAIL - Quality gate violations found.\n'));
+            // Score summary line
+            const stats = report.stats;
+            const scoreParts = [];
+            if (stats.score !== undefined)
+                scoreParts.push(`Score: ${stats.score}/100`);
+            if (stats.ai_health_score !== undefined)
+                scoreParts.push(`AI Health: ${stats.ai_health_score}/100`);
+            if (stats.structural_score !== undefined)
+                scoreParts.push(`Structural: ${stats.structural_score}/100`);
+            if (scoreParts.length > 0) {
+                console.log(chalk.bold(scoreParts.join(' | ')) + '\n');
+            }
+            // Severity breakdown
+            if (stats.severity_breakdown) {
+                const parts = Object.entries(stats.severity_breakdown)
+                    .filter(([, count]) => count > 0)
+                    .map(([sev, count]) => {
+                    const color = sev === 'critical' ? chalk.red.bold : sev === 'high' ? chalk.red : sev === 'medium' ? chalk.yellow : chalk.dim;
+                    return color(`${sev}: ${count}`);
+                });
+                if (parts.length > 0) {
+                    console.log('Severity: ' + parts.join(', ') + '\n');
+                }
+            }
+            // Group failures by provenance
+            const 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 ');
+                }
+            };
             for (const failure of report.failures) {
-                console.log(chalk.red(`[${failure.id}] ${failure.title}`));
-                console.log(chalk.dim(`  Details: ${failure.details}`));
+                const sev = severityIcon(failure.severity);
+                const prov = failure.provenance ? chalk.dim(`[${failure.provenance}]`) : '';
+                console.log(`${sev} ${prov} ${chalk.red(`[${failure.id}]`)} ${failure.title}`);
+                console.log(chalk.dim(`      Details: ${failure.details}`));
                 if (failure.files && failure.files.length > 0) {
-                    console.log(chalk.dim('  Files:'));
-                    failure.files.forEach((f) => console.log(chalk.dim(`    - ${f}`)));
+                    console.log(chalk.dim('      Files:'));
+                    failure.files.forEach((f) => console.log(chalk.dim(`        - ${f}`)));
                 }
                 if (failure.hint) {
-                    console.log(chalk.cyan(`  Hint: ${failure.hint}`));
+                    console.log(chalk.cyan(`      Hint: ${failure.hint}`));
                 }
                 console.log('');
             }
             console.log(chalk.yellow(`See ${config.output.report_path} for full details.`));
         }
-        console.log(chalk.dim(`\nFinished in ${report.stats.duration_ms}ms`));
+        // Score trend display
+        const trend = getScoreTrend(cwd);
+        if (trend && trend.recentScores.length >= 3) {
+            const arrow = trend.direction === 'improving' ? chalk.green('↑') :
+                trend.direction === 'degrading' ? chalk.red('↓') : chalk.dim('→');
+            const trendColor = trend.direction === 'improving' ? chalk.green :
+                trend.direction === 'degrading' ? chalk.red : chalk.dim;
+            const scoresStr = trend.recentScores.map(s => String(s)).join(' → ');
+            console.log(trendColor(`\nScore Trend: ${scoresStr} (${trend.direction} ${arrow})`));
+        }
+        // Stats footer
+        const footerParts = [`Finished in ${report.stats.duration_ms}ms`];
+        if (report.status === 'PASS' && report.stats.score !== undefined) {
+            footerParts.push(`Score: ${report.stats.score}/100`);
+        }
+        console.log(chalk.dim('\n' + footerParts.join(' | ')));
         process.exit(report.status === 'PASS' ? EXIT_PASS : EXIT_FAIL);
     }
     catch (error) {

package/dist/commands/demo.d.ts

@@ -0,0 +1,16 @@
+/**
+ * rigour demo
+ *
+ * Creates a temp project with intentional AI-generated code issues,
+ * runs Rigour against it, and shows the full experience:
+ *   1. Scaffolds a broken codebase
+ *   2. Runs quality gates → FAIL with violations
+ *   3. Shows the fix packet
+ *   4. Exports an audit report
+ *   5. Cleans up
+ *
+ * The "flagship demo" — one command to understand Rigour.
+ *
+ * @since v2.17.0
+ */
+export declare function demoCommand(): Promise<void>;

package/dist/commands/demo.js

@@ -0,0 +1,306 @@
+/**
+ * rigour demo
+ *
+ * Creates a temp project with intentional AI-generated code issues,
+ * runs Rigour against it, and shows the full experience:
+ *   1. Scaffolds a broken codebase
+ *   2. Runs quality gates → FAIL with violations
+ *   3. Shows the fix packet
+ *   4. Exports an audit report
+ *   5. Cleans up
+ *
+ * The "flagship demo" — one command to understand Rigour.
+ *
+ * @since v2.17.0
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import chalk from 'chalk';
+import yaml from 'yaml';
+import os from 'os';
+import { GateRunner, ConfigSchema } from '@rigour-labs/core';
+import { recordScore } from '@rigour-labs/core';
+export async function demoCommand() {
+    console.log(chalk.bold.cyan(`
+   ____  _
+  / __ \\(_)____ ___  __  __ _____
+ / /_/ // // __ \`/ / / / / // ___/
+/ _, _// // /_/ // /_/ / / // /
+/_/ |_|/_/ \\__, / \\__,_/_/ /_/
+          /____/
+    `));
+    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()}`);
+    console.log(chalk.dim(`Creating demo project at ${demoDir}...\n`));
+    await fs.ensureDir(demoDir);
+    await scaffoldDemoProject(demoDir);
+    console.log(chalk.green('✓ Demo project scaffolded with intentional issues.\n'));
+    // Show the issues planted
+    console.log(chalk.bold.yellow('📋 Planted issues:'));
+    console.log(chalk.dim('  1. src/auth.ts        — Hardcoded API key (security)'));
+    console.log(chalk.dim('  2. src/api-handler.ts  — Unhandled promise (AI drift)'));
+    console.log(chalk.dim('  3. src/data-loader.ts — Hallucinated import (AI drift)'));
+    console.log(chalk.dim('  4. src/utils.ts       — TODO marker left by AI'));
+    console.log(chalk.dim('  5. src/god-file.ts    — 350+ lines (structural)'));
+    console.log('');
+    // 2. Run quality gates
+    console.log(chalk.bold.blue('🔍 Running Rigour quality gates...\n'));
+    await sleep(500);
+    try {
+        const configContent = await fs.readFile(path.join(demoDir, 'rigour.yml'), 'utf-8');
+        const rawConfig = yaml.parse(configContent);
+        const config = ConfigSchema.parse(rawConfig);
+        const runner = new GateRunner(config);
+        const report = await runner.run(demoDir);
+        // Record score
+        recordScore(demoDir, report);
+        // Write report
+        const reportPath = path.join(demoDir, config.output.report_path);
+        await fs.writeJson(reportPath, report, { spaces: 2 });
+        // Display results
+        const stats = report.stats;
+        if (report.status === 'FAIL') {
+            console.log(chalk.red.bold('✘ FAIL — Quality gate violations found.\n'));
+            // Score display
+            const scoreParts = [];
+            if (stats.score !== undefined)
+                scoreParts.push(`Score: ${stats.score}/100`);
+            if (stats.ai_health_score !== undefined)
+                scoreParts.push(`AI Health: ${stats.ai_health_score}/100`);
+            if (stats.structural_score !== undefined)
+                scoreParts.push(`Structural: ${stats.structural_score}/100`);
+            if (scoreParts.length > 0) {
+                console.log(chalk.bold(scoreParts.join(' | ')) + '\n');
+            }
+            // Severity breakdown
+            if (stats.severity_breakdown) {
+                const parts = Object.entries(stats.severity_breakdown)
+                    .filter(([, count]) => count > 0)
+                    .map(([sev, count]) => {
+                    const color = sev === 'critical' ? chalk.red.bold : sev === 'high' ? chalk.red : sev === 'medium' ? chalk.yellow : chalk.dim;
+                    return color(`${sev}: ${count}`);
+                });
+                if (parts.length > 0) {
+                    console.log('Severity: ' + parts.join(', ') + '\n');
+                }
+            }
+            // Show violations
+            for (const failure of report.failures) {
+                const sevLabel = failure.severity === 'critical' ? chalk.red.bold('CRIT') :
+                    failure.severity === 'high' ? chalk.red('HIGH') :
+                        failure.severity === 'medium' ? chalk.yellow('MED ') : chalk.dim('LOW ');
+                const prov = failure.provenance ? chalk.dim(`[${failure.provenance}]`) : '';
+                console.log(`  ${sevLabel} ${prov} ${chalk.red(`[${failure.id}]`)} ${failure.title}`);
+                if (failure.hint) {
+                    console.log(chalk.cyan(`        💡 ${failure.hint}`));
+                }
+            }
+            console.log('');
+        }
+        else {
+            console.log(chalk.green.bold('✔ PASS — All quality gates satisfied.\n'));
+        }
+        console.log(chalk.dim(`Finished in ${stats.duration_ms}ms\n`));
+        // 3. Generate fix packet
+        if (report.status === 'FAIL') {
+            const { FixPacketService } = await import('@rigour-labs/core');
+            const fixPacketService = new FixPacketService();
+            const fixPacket = fixPacketService.generate(report, config);
+            const fixPacketPath = path.join(demoDir, 'rigour-fix-packet.json');
+            await fs.writeJson(fixPacketPath, fixPacket, { spaces: 2 });
+            console.log(chalk.green(`✓ Fix packet generated: rigour-fix-packet.json`));
+        }
+        // 4. Generate audit report
+        const { exportAuditCommand } = await import('./export-audit.js');
+        // We manually build a mini audit export
+        const auditPath = path.join(demoDir, 'rigour-audit-report.md');
+        await generateDemoAudit(demoDir, report, auditPath);
+        console.log(chalk.green(`✓ Audit report exported: rigour-audit-report.md`));
+        console.log('');
+        console.log(chalk.bold.cyan('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+        console.log(chalk.bold('This is what Rigour does:'));
+        console.log(chalk.dim('  • Catches AI drift (hallucinated imports, unhandled promises)'));
+        console.log(chalk.dim('  • Blocks security issues (hardcoded keys, injection patterns)'));
+        console.log(chalk.dim('  • Enforces structure (file size, complexity, documentation)'));
+        console.log(chalk.dim('  • Generates audit-ready evidence (scores, trends, reports)'));
+        console.log(chalk.bold.cyan('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'));
+        console.log(chalk.bold('Get started:'));
+        console.log(chalk.white('  $ npx @rigour-labs/cli init'));
+        console.log(chalk.white('  $ npx @rigour-labs/cli check'));
+        console.log('');
+        console.log(chalk.dim(`Demo files: ${demoDir}`));
+        console.log(chalk.dim('GitHub: https://github.com/rigour-labs/rigour'));
+        console.log(chalk.dim('Docs:   https://docs.rigour.run\n'));
+        console.log(chalk.dim.italic('If this saved you from a bad commit, star the repo ⭐'));
+    }
+    catch (error) {
+        console.error(chalk.red(`Demo error: ${error.message}`));
+    }
+}
+async function scaffoldDemoProject(dir) {
+    // rigour.yml
+    const config = {
+        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',
+            },
+        },
+        ignore: ['.git/**', 'node_modules/**'],
+        output: {
+            report_path: 'rigour-report.json',
+        },
+    };
+    await fs.writeFile(path.join(dir, 'rigour.yml'), yaml.stringify(config));
+    // package.json (for hallucinated import detection)
+    await fs.writeJson(path.join(dir, 'package.json'), {
+        name: 'rigour-demo',
+        version: '1.0.0',
+        dependencies: {
+            express: '^4.18.0',
+            zod: '^3.22.0',
+        },
+    }, { spaces: 2 });
+    // src directory
+    await fs.ensureDir(path.join(dir, 'src'));
+    // Issue 1: Hardcoded API key (security)
+    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 (AI drift — promise safety)
+    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) {
+    // AI generated this without .catch() — floating promise
+    fetchUserData(req.params.id);
+    res.send('Processing...');
+}
+
+export function batchProcess(ids: string[]) {
+    // Multiple unhandled promises
+    ids.forEach(id => fetchUserData(id));
+}
+`.trim());
+    // Issue 3: Hallucinated import (AI drift)
+    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: TODO marker
+    await fs.writeFile(path.join(dir, 'src', 'utils.ts'), `
+// TODO: Claude suggested this but I need to review
+// FIXME: This function has edge cases
+export function formatDate(date: Date): string {
+    return date.toISOString().split('T')[0];
+}
+
+export function sanitizeInput(input: string): string {
+    // TODO: Add proper sanitization
+    return input.trim();
+}
+`.trim());
+    // Issue 5: God file (350+ lines)
+    const godFileLines = [
+        '// Auto-generated data processing module',
+        'export class DataProcessor {',
+    ];
+    for (let i = 0; i < 60; i++) {
+        godFileLines.push(`    process${i}(data: any) {`);
+        godFileLines.push(`        const result = data.map((x: any) => x * ${i + 1});`);
+        godFileLines.push(`        if (result.length > ${i * 10}) {`);
+        godFileLines.push(`            return result.slice(0, ${i * 10});`);
+        godFileLines.push(`        }`);
+        godFileLines.push(`        return result;`);
+        godFileLines.push(`    }`);
+    }
+    godFileLines.push('}');
+    await fs.writeFile(path.join(dir, 'src', 'god-file.ts'), godFileLines.join('\n'));
+    // docs directory (missing required docs)
+    await fs.ensureDir(path.join(dir, 'docs'));
+    await fs.writeFile(path.join(dir, 'README.md'), '# Demo Project\n\nThis is a demo project for Rigour.\n');
+}
+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*');
+    await fs.writeFile(outputPath, lines.join('\n'));
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}

package/dist/commands/explain.js

@@ -28,6 +28,38 @@ export async function explainCommand(cwd) {
         console.log(chalk.bold('Status: ') + (report.status === 'PASS'
             ? chalk.green.bold('✅ PASS')
             : chalk.red.bold('🛑 FAIL')));
+        // Score summary
+        if (report.stats) {
+            const stats = report.stats;
+            const scoreParts = [];
+            if (stats.score !== undefined)
+                scoreParts.push(`Score: ${stats.score}/100`);
+            if (stats.ai_health_score !== undefined)
+                scoreParts.push(`AI Health: ${stats.ai_health_score}/100`);
+            if (stats.structural_score !== undefined)
+                scoreParts.push(`Structural: ${stats.structural_score}/100`);
+            if (scoreParts.length > 0) {
+                console.log(chalk.bold('\n' + scoreParts.join(' | ')));
+            }
+            // Severity breakdown
+            if (stats.severity_breakdown) {
+                const sevParts = Object.entries(stats.severity_breakdown)
+                    .filter(([, count]) => count > 0)
+                    .map(([sev, count]) => `${sev}: ${count}`);
+                if (sevParts.length > 0) {
+                    console.log(chalk.dim('Severity: ' + sevParts.join(', ')));
+                }
+            }
+            // Provenance breakdown
+            if (stats.provenance_breakdown) {
+                const provParts = Object.entries(stats.provenance_breakdown)
+                    .filter(([, count]) => count > 0)
+                    .map(([prov, count]) => `${prov}: ${count}`);
+                if (provParts.length > 0) {
+                    console.log(chalk.dim('Categories: ' + provParts.join(', ')));
+                }
+            }
+        }
         console.log(chalk.bold('\nGate Summary:'));
         for (const [gate, status] of Object.entries(report.summary || {})) {
             const icon = status === 'PASS' ? '✅' : status === 'FAIL' ? '❌' : '⏭️';
@@ -35,8 +67,21 @@ export async function explainCommand(cwd) {
         }
         if (report.failures && report.failures.length > 0) {
             console.log(chalk.bold.red(`\n🔧 ${report.failures.length} Violation(s) to Fix:\n`));
+            // Severity color helper
+            const sevColor = (s) => {
+                switch (s) {
+                    case 'critical': return chalk.red.bold;
+                    case 'high': return chalk.red;
+                    case 'medium': return chalk.yellow;
+                    case 'low': return chalk.dim;
+                    default: return chalk.dim;
+                }
+            };
             report.failures.forEach((failure, index) => {
-                console.log(chalk.white(`${index + 1}. `) + chalk.bold.yellow(`[${failure.id.toUpperCase()}]`) + chalk.white(` ${failure.title}`));
+                const sev = failure.severity || 'medium';
+                const sevLabel = sevColor(sev)(`[${sev.toUpperCase()}]`);
+                const provLabel = failure.provenance ? chalk.dim(`(${failure.provenance})`) : '';
+                console.log(chalk.white(`${index + 1}. `) + sevLabel + ' ' + chalk.bold.yellow(`[${failure.id.toUpperCase()}]`) + ' ' + provLabel + chalk.white(` ${failure.title}`));
                 console.log(chalk.dim(`   └─ ${failure.details}`));
                 if (failure.files && failure.files.length > 0) {
                     console.log(chalk.cyan(`   📁 Files: ${failure.files.join(', ')}`));

package/dist/commands/export-audit.d.ts

@@ -0,0 +1,16 @@
+/**
+ * export-audit command
+ *
+ * Generates a compliance audit package from the last gate check.
+ * The artifact compliance officers hand to auditors.
+ *
+ * Formats: JSON (structured) or Markdown (human-readable)
+ *
+ * @since v2.17.0
+ */
+export interface ExportAuditOptions {
+    format?: 'json' | 'md';
+    output?: string;
+    run?: boolean;
+}
+export declare function exportAuditCommand(cwd: string, options?: ExportAuditOptions): Promise<void>;