@rigour-labs/cli 1.0.0 → 1.2.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Rigour Contributors
+Copyright (c) 2026 Ashutosh (https://github.com/erashu212), Rigour Labs.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/cli.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const init_js_1 = require("./commands/init.js");
 const check_js_1 = require("./commands/check.js");
+const explain_js_1 = require("./commands/explain.js");
 const run_js_1 = require("./commands/run.js");
 const program = new commander_1.Command();
 program
@@ -12,22 +13,40 @@ program
     .version('1.0.0');
 program
     .command('init')
-    .description('Initialize VibeGuard in the current directory')
-    .action(async () => {
-    await (0, init_js_1.initCommand)(process.cwd());
+    .description('Initialize Rigour in the current directory')
+    .option('-p, --preset <name>', 'Project preset (ui, api, infra, data)')
+    .option('--paradigm <name>', 'Coding paradigm (oop, functional, minimal)')
+    .option('--dry-run', 'Show detected configuration without writing files')
+    .option('--explain', 'Show detection markers for roles and paradigms')
+    .action(async (options) => {
+    await (0, init_js_1.initCommand)(process.cwd(), options);
 });
 program
     .command('check')
     .description('Run quality gate checks')
+    .option('--ci', 'CI mode (minimal output, non-zero exit on fail)')
+    .option('--json', 'Output report in JSON format')
+    .action(async (options) => {
+    await (0, check_js_1.checkCommand)(process.cwd(), options);
+});
+program
+    .command('explain')
+    .description('Explain the last quality gate report with actionable bullets')
     .action(async () => {
-    await (0, check_js_1.checkCommand)(process.cwd());
+    await (0, explain_js_1.explainCommand)(process.cwd());
 });
 program
     .command('run')
     .description('Execute an agent command in a loop until quality gates pass')
     .argument('[command...]', 'The agent command to run (e.g., cursor-agent ...)')
-    .option('-i, --iterations <number>', 'Maximum number of loop iterations', '3')
+    .option('-i, --iterations <number>', 'Maximum number of loop iterations (deprecated, use --max-cycles)', '3')
+    .option('-c, --max-cycles <number>', 'Maximum number of loop iterations', '3')
+    .option('--fail-fast', 'Abort loop immediately on first gate failure')
     .action(async (args, options) => {
-    await (0, run_js_1.runLoop)(process.cwd(), args, { iterations: parseInt(options.iterations) });
+    const maxCycles = parseInt(options.maxCycles || options.iterations);
+    await (0, run_js_1.runLoop)(process.cwd(), args, {
+        iterations: maxCycles,
+        failFast: !!options.failFast
+    });
 });
 program.parse();

package/dist/commands/check.d.ts

@@ -1 +1,5 @@
-export declare function checkCommand(cwd: string): Promise<void>;
+export interface CheckOptions {
+    ci?: boolean;
+    json?: boolean;
+}
+export declare function checkCommand(cwd: string, options?: CheckOptions): Promise<void>;

package/dist/commands/check.js

@@ -9,43 +9,90 @@ const path_1 = __importDefault(require("path"));
 const chalk_1 = __importDefault(require("chalk"));
 const yaml_1 = __importDefault(require("yaml"));
 const core_1 = require("@rigour-labs/core");
-async function checkCommand(cwd) {
+// Exit codes per spec
+const EXIT_PASS = 0;
+const EXIT_FAIL = 1;
+const EXIT_CONFIG_ERROR = 2;
+const EXIT_INTERNAL_ERROR = 3;
+async function checkCommand(cwd, options = {}) {
     const configPath = path_1.default.join(cwd, 'rigour.yml');
     if (!(await fs_extra_1.default.pathExists(configPath))) {
-        console.error(chalk_1.default.red('Error: rigour.yml not found. Run `rigour init` first.'));
-        process.exit(1);
-    }
-    const configContent = await fs_extra_1.default.readFile(configPath, 'utf-8');
-    const rawConfig = yaml_1.default.parse(configContent);
-    const config = core_1.ConfigSchema.parse(rawConfig);
-    console.log(chalk_1.default.blue('Running Rigour checks...\n'));
-    const runner = new core_1.GateRunner(config);
-    const report = await runner.run(cwd);
-    // Write machine report
-    const reportPath = path_1.default.join(cwd, config.output.report_path);
-    await fs_extra_1.default.writeJson(reportPath, report, { spaces: 2 });
-    // Print human summary
-    if (report.status === 'PASS') {
-        console.log(chalk_1.default.green.bold('✔ PASS - All quality gates satisfied.'));
+        if (options.json) {
+            console.log(JSON.stringify({ error: 'CONFIG_ERROR', message: 'rigour.yml not found' }));
+        }
+        else if (!options.ci) {
+            console.error(chalk_1.default.red('Error: rigour.yml not found. Run `rigour init` first.'));
+        }
+        process.exit(EXIT_CONFIG_ERROR);
     }
-    else {
-        console.log(chalk_1.default.red.bold('✘ FAIL - Quality gate violations found.\n'));
-        for (const failure of report.failures) {
-            console.log(chalk_1.default.red(`[${failure.id}] ${failure.title}`));
-            console.log(chalk_1.default.dim(`  Details: ${failure.details}`));
-            if (failure.files && failure.files.length > 0) {
-                console.log(chalk_1.default.dim('  Files:'));
-                failure.files.forEach((f) => console.log(chalk_1.default.dim(`    - ${f}`)));
+    try {
+        const configContent = await fs_extra_1.default.readFile(configPath, 'utf-8');
+        const rawConfig = yaml_1.default.parse(configContent);
+        const config = core_1.ConfigSchema.parse(rawConfig);
+        if (!options.ci && !options.json) {
+            console.log(chalk_1.default.blue('Running Rigour checks...\n'));
+        }
+        const runner = new core_1.GateRunner(config);
+        const report = await runner.run(cwd);
+        // Write machine report
+        const reportPath = path_1.default.join(cwd, config.output.report_path);
+        await fs_extra_1.default.writeJson(reportPath, report, { spaces: 2 });
+        // Generate Fix Packet v2 on failure
+        if (report.status === 'FAIL') {
+            const { FixPacketService } = await import('@rigour-labs/core');
+            const fixPacketService = new FixPacketService();
+            const fixPacket = fixPacketService.generate(report, config);
+            const fixPacketPath = path_1.default.join(cwd, 'rigour-fix-packet.json');
+            await fs_extra_1.default.writeJson(fixPacketPath, fixPacket, { spaces: 2 });
+        }
+        // JSON output mode
+        if (options.json) {
+            console.log(JSON.stringify(report, null, 2));
+            process.exit(report.status === 'PASS' ? EXIT_PASS : EXIT_FAIL);
+        }
+        // CI mode: minimal output
+        if (options.ci) {
+            if (report.status === 'PASS') {
+                console.log('PASS');
             }
-            if (failure.hint) {
-                console.log(chalk_1.default.cyan(`  Hint: ${failure.hint}`));
+            else {
+                console.log(`FAIL: ${report.failures.length} violation(s)`);
+                report.failures.forEach((f) => {
+                    console.log(`  - [${f.id}] ${f.title}`);
+                });
             }
-            console.log('');
+            process.exit(report.status === 'PASS' ? EXIT_PASS : EXIT_FAIL);
         }
-        console.log(chalk_1.default.yellow(`See ${config.output.report_path} for full details.`));
+        // Normal human-readable output
+        if (report.status === 'PASS') {
+            console.log(chalk_1.default.green.bold('✔ PASS - All quality gates satisfied.'));
+        }
+        else {
+            console.log(chalk_1.default.red.bold('✘ FAIL - Quality gate violations found.\n'));
+            for (const failure of report.failures) {
+                console.log(chalk_1.default.red(`[${failure.id}] ${failure.title}`));
+                console.log(chalk_1.default.dim(`  Details: ${failure.details}`));
+                if (failure.files && failure.files.length > 0) {
+                    console.log(chalk_1.default.dim('  Files:'));
+                    failure.files.forEach((f) => console.log(chalk_1.default.dim(`    - ${f}`)));
+                }
+                if (failure.hint) {
+                    console.log(chalk_1.default.cyan(`  Hint: ${failure.hint}`));
+                }
+                console.log('');
+            }
+            console.log(chalk_1.default.yellow(`See ${config.output.report_path} for full details.`));
+        }
+        console.log(chalk_1.default.dim(`\nFinished in ${report.stats.duration_ms}ms`));
+        process.exit(report.status === 'PASS' ? EXIT_PASS : EXIT_FAIL);
     }
-    console.log(chalk_1.default.dim(`\nFinished in ${report.stats.duration_ms}ms`));
-    if (report.status !== 'PASS') {
-        process.exit(1);
+    catch (error) {
+        if (options.json) {
+            console.log(JSON.stringify({ error: 'INTERNAL_ERROR', message: error.message }));
+        }
+        else if (!options.ci) {
+            console.error(chalk_1.default.red(`Internal error: ${error.message}`));
+        }
+        process.exit(EXIT_INTERNAL_ERROR);
     }
 }

package/dist/commands/explain.d.ts

@@ -0,0 +1 @@
+export declare function explainCommand(cwd: string): Promise<void>;

package/dist/commands/explain.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.explainCommand = explainCommand;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+async function explainCommand(cwd) {
+    const configPath = path_1.default.join(cwd, 'rigour.yml');
+    let reportPath = path_1.default.join(cwd, 'rigour-report.json');
+    // Try to read custom path from config
+    if (await fs_extra_1.default.pathExists(configPath)) {
+        try {
+            const yaml = await import('yaml');
+            const configContent = await fs_extra_1.default.readFile(configPath, 'utf-8');
+            const config = yaml.parse(configContent);
+            if (config?.output?.report_path) {
+                reportPath = path_1.default.join(cwd, config.output.report_path);
+            }
+        }
+        catch (e) { }
+    }
+    if (!(await fs_extra_1.default.pathExists(reportPath))) {
+        console.error(chalk_1.default.red(`Error: No report found at ${reportPath}`));
+        console.error(chalk_1.default.dim('Run `rigour check` first to generate a report.'));
+        process.exit(2);
+    }
+    try {
+        const reportContent = await fs_extra_1.default.readFile(reportPath, 'utf-8');
+        const report = JSON.parse(reportContent);
+        console.log(chalk_1.default.bold('\n📋 Rigour Report Explanation\n'));
+        console.log(chalk_1.default.bold('Status: ') + (report.status === 'PASS'
+            ? chalk_1.default.green.bold('✅ PASS')
+            : chalk_1.default.red.bold('🛑 FAIL')));
+        console.log(chalk_1.default.bold('\nGate Summary:'));
+        for (const [gate, status] of Object.entries(report.summary || {})) {
+            const icon = status === 'PASS' ? '✅' : status === 'FAIL' ? '❌' : '⏭️';
+            console.log(`  ${icon} ${gate}: ${status}`);
+        }
+        if (report.failures && report.failures.length > 0) {
+            console.log(chalk_1.default.bold.red(`\n🔧 ${report.failures.length} Violation(s) to Fix:\n`));
+            report.failures.forEach((failure, index) => {
+                console.log(chalk_1.default.white(`${index + 1}. `) + chalk_1.default.bold.yellow(`[${failure.id.toUpperCase()}]`) + chalk_1.default.white(` ${failure.title}`));
+                console.log(chalk_1.default.dim(`   └─ ${failure.details}`));
+                if (failure.files && failure.files.length > 0) {
+                    console.log(chalk_1.default.cyan(`   📁 Files: ${failure.files.join(', ')}`));
+                }
+                if (failure.hint) {
+                    console.log(chalk_1.default.green(`   💡 Hint: ${failure.hint}`));
+                }
+                console.log('');
+            });
+        }
+        else if (report.status === 'PASS') {
+            console.log(chalk_1.default.green('\n✨ All quality gates passed! No violations found.\n'));
+        }
+        if (report.stats) {
+            console.log(chalk_1.default.dim(`Duration: ${report.stats.duration_ms}ms`));
+        }
+    }
+    catch (error) {
+        console.error(chalk_1.default.red(`Error reading report: ${error.message}`));
+        process.exit(3);
+    }
+}

package/dist/commands/init.d.ts

@@ -1 +1,7 @@
-export declare function initCommand(cwd: string): Promise<void>;
+export interface InitOptions {
+    preset?: string;
+    paradigm?: string;
+    dryRun?: boolean;
+    explain?: boolean;
+}
+export declare function initCommand(cwd: string, options?: InitOptions): Promise<void>;

package/dist/commands/init.js

@@ -9,14 +9,70 @@ const path_1 = __importDefault(require("path"));
 const chalk_1 = __importDefault(require("chalk"));
 const yaml_1 = __importDefault(require("yaml"));
 const core_1 = require("@rigour-labs/core");
-async function initCommand(cwd) {
+async function initCommand(cwd, options = {}) {
     const discovery = new core_1.DiscoveryService();
-    const recommendedConfig = await discovery.discover(cwd);
+    const result = await discovery.discover(cwd);
+    let recommendedConfig = result.config;
+    // Override with user options if provided and re-apply template logic if necessary
+    if (options.preset || options.paradigm) {
+        const core = await import('@rigour-labs/core');
+        let customBase = { ...core.UNIVERSAL_CONFIG };
+        if (options.preset) {
+            const t = core.TEMPLATES.find((t) => t.name === options.preset);
+            if (t)
+                customBase = discovery.mergeConfig(customBase, t.config);
+        }
+        else if (recommendedConfig.preset) {
+            const t = core.TEMPLATES.find((t) => t.name === recommendedConfig.preset);
+            if (t)
+                customBase = discovery.mergeConfig(customBase, t.config);
+        }
+        if (options.paradigm) {
+            const t = core.PARADIGM_TEMPLATES.find((t) => t.name === options.paradigm);
+            if (t)
+                customBase = discovery.mergeConfig(customBase, t.config);
+        }
+        else if (recommendedConfig.paradigm) {
+            const t = core.PARADIGM_TEMPLATES.find((t) => t.name === recommendedConfig.paradigm);
+            if (t)
+                customBase = discovery.mergeConfig(customBase, t.config);
+        }
+        recommendedConfig = customBase;
+        if (options.preset)
+            recommendedConfig.preset = options.preset;
+        if (options.paradigm)
+            recommendedConfig.paradigm = options.paradigm;
+    }
+    if (options.dryRun || options.explain) {
+        console.log(chalk_1.default.bold.blue('\n🔍 Rigour Auto-Discovery (Dry Run):'));
+        if (recommendedConfig.preset) {
+            console.log(chalk_1.default.cyan(`   Role: `) + chalk_1.default.bold(recommendedConfig.preset.toUpperCase()));
+            if (options.explain && result.matches.preset) {
+                console.log(chalk_1.default.dim(`         (Marker found: ${result.matches.preset.marker})`));
+            }
+        }
+        if (recommendedConfig.paradigm) {
+            console.log(chalk_1.default.cyan(`   Paradigm: `) + chalk_1.default.bold(recommendedConfig.paradigm.toUpperCase()));
+            if (options.explain && result.matches.paradigm) {
+                console.log(chalk_1.default.dim(`             (Marker found: ${result.matches.paradigm.marker})`));
+            }
+        }
+        console.log(chalk_1.default.yellow('\n[DRY RUN] No files will be written.'));
+        return;
+    }
     const configPath = path_1.default.join(cwd, 'rigour.yml');
     if (await fs_extra_1.default.pathExists(configPath)) {
         console.log(chalk_1.default.yellow('rigour.yml already exists. Skipping initialization.'));
         return;
     }
+    console.log(chalk_1.default.bold.blue('\n🔍 Rigour Auto-Discovery:'));
+    if (recommendedConfig.preset) {
+        console.log(chalk_1.default.cyan(`   Role: `) + chalk_1.default.bold(recommendedConfig.preset.toUpperCase()));
+    }
+    if (recommendedConfig.paradigm) {
+        console.log(chalk_1.default.cyan(`   Paradigm: `) + chalk_1.default.bold(recommendedConfig.paradigm.toUpperCase()));
+    }
+    console.log('');
     await fs_extra_1.default.writeFile(configPath, yaml_1.default.stringify(recommendedConfig));
     console.log(chalk_1.default.green('✔ Created rigour.yml'));
     // Create required directories and files
@@ -28,33 +84,51 @@ async function initCommand(cwd) {
             console.log(chalk_1.default.dim(`  - Created ${file}`));
         }
     }
-    // Agent Handshake (Cursor/AntiGravity)
+    // Agent Handshake (Universal / AntiGravity / Cursor)
+    const rigourDocsDir = path_1.default.join(cwd, 'docs');
+    await fs_extra_1.default.ensureDir(rigourDocsDir);
+    const instructionsPath = path_1.default.join(rigourDocsDir, 'AGENT_INSTRUCTIONS.md');
+    const ruleContent = `# 🛡️ Rigour: Engineering Excellence Protocol
+
+You are an Elite Software Engineer. You do not just write code that "works"; you write code that is **modular, maintainable, and rigorously verified.**
+
+## 🚦 The Rigour Loop (Mandatory)
+Before claiming "Done" for any task, you MUST follow this loop:
+
+1.  **Check**: Run \`npx @rigour-labs/cli check\` to verify compliance.
+2.  **Analyze**: If it fails, read \`rigour-fix-packet.json\` (V2 High-Fidelity) for exact failure points and constraints.
+3.  **Refactor**: Apply **SOLID** and **DRY** principles to resolve the violations according to constraints.
+4.  **Repeat**: Continue until \`npx @rigour-labs/cli check\` returns **PASS**.
+
+## 🧩 Engineering Standards
+- **Single Responsibility**: Keep files small and focused (max 500 lines).
+- **DRY (Don't Repeat Yourself)**: Extract common logic into utilities.
+- **Done is Done**: No \`TODO\` or \`FIXME\` comments allowed in the final state.
+- **Memory Preservation**: Always update docs/SPEC.md, docs/ARCH.md, docs/DECISIONS.md.
+
+## 🛠️ Commands
+\`\`\`bash
+# Verify current state
+npx @rigour-labs/cli check
+
+# Self-healing agent loop
+npx @rigour-labs/cli run -- <agent-command>
+\`\`\`
+`;
+    // 1. Create Universal Instructions
+    await fs_extra_1.default.writeFile(instructionsPath, ruleContent);
+    console.log(chalk_1.default.green('✔ Initialized Universal Agent Handshake (docs/AGENT_INSTRUCTIONS.md)'));
+    // 2. Create Cursor Specific Rules (.mdc)
     const cursorRulesDir = path_1.default.join(cwd, '.cursor', 'rules');
     await fs_extra_1.default.ensureDir(cursorRulesDir);
-    const rulePath = path_1.default.join(cursorRulesDir, 'rigour.mdc');
-    const ruleContent = `---
+    const mdcPath = path_1.default.join(cursorRulesDir, 'rigour.mdc');
+    const mdcContent = `---
 description: Enforcement of Rigour quality gates and best practices.
 globs: **/*
 ---
 
-# Rigour Enforcement
-
-You are operating under Rigour engineering discipline.
-
-## Core Rules
-- **Never claim done** until you run \`rigour check\` and it returns PASS.
-- If checks FAIL, fix **only** the listed failures. Do not add new features or refactor unrelated code.
-- Maintain project memory in \`docs/SPEC.md\`, \`docs/ARCH.md\`, and \`docs/DECISIONS.md\`.
-- Keep files modular. If a file exceeds 500 lines, you MUST break it into smaller components.
-- No \`TODO\` or \`FIXME\` comments allowed in the final submission.
-
-## Workflow
-1. Write/Modify code.
-2. Run \`rigour check\`.
-3. If FAIL: Read \`rigour-report.json\` for exact failure points and fix them.
-4. If PASS: You may claim task completion.
-`;
-    await fs_extra_1.default.writeFile(rulePath, ruleContent);
-    console.log(chalk_1.default.green('✔ Initialized Agent Handshake (.cursor/rules/rigour.mdc)'));
-    console.log(chalk_1.default.blue('\nRigour is ready. Run `rigour check` to verify your project.'));
+${ruleContent}`;
+    await fs_extra_1.default.writeFile(mdcPath, mdcContent);
+    console.log(chalk_1.default.green('✔ Initialized Cursor Handshake (.cursor/rules/rigour.mdc)'));
+    console.log(chalk_1.default.blue('\nRigour is ready. Run `npx @rigour-labs/cli check` to verify your project.'));
 }

package/dist/commands/run.d.ts

@@ -1,3 +1,4 @@
 export declare function runLoop(cwd: string, agentArgs: string[], options: {
     iterations: number;
+    failFast?: boolean;
 }): Promise<void>;

package/dist/commands/run.js

@@ -10,11 +10,16 @@ const chalk_1 = __importDefault(require("chalk"));
 const yaml_1 = __importDefault(require("yaml"));
 const execa_1 = require("execa");
 const core_1 = require("@rigour-labs/core");
+// Exit codes per spec
+const EXIT_PASS = 0;
+const EXIT_FAIL = 1;
+const EXIT_CONFIG_ERROR = 2;
+const EXIT_INTERNAL_ERROR = 3;
 async function runLoop(cwd, agentArgs, options) {
     const configPath = path_1.default.join(cwd, 'rigour.yml');
     if (!(await fs_extra_1.default.pathExists(configPath))) {
         console.error(chalk_1.default.red('Error: rigour.yml not found. Run `rigour init` first.'));
-        process.exit(1);
+        process.exit(EXIT_CONFIG_ERROR);
     }
     try {
         const configContent = await fs_extra_1.default.readFile(configPath, 'utf-8');
@@ -28,42 +33,81 @@ async function runLoop(cwd, agentArgs, options) {
             console.log(chalk_1.default.bold.blue(`\n══════════════════════════════════════════════════════════════════`));
             console.log(chalk_1.default.bold.blue(`  RIGOUR LOOP: Iteration ${iteration}/${maxIterations}`));
             console.log(chalk_1.default.bold.blue(`══════════════════════════════════════════════════════════════════`));
-            // 1. Run the agent command
-            if (agentArgs.length > 0) {
+            // 1. Prepare Command
+            let currentArgs = [...agentArgs];
+            if (iteration > 1 && agentArgs.length > 0) {
+                // Iteration contract: In later cycles, we focus strictly on the fix packet
+                console.log(chalk_1.default.yellow(`\n🔄 REFINEMENT CYCLE - Instructing agent to fix specific violations...`));
+                // We keep the first part of the command (the agent) but can append or wrap
+                // For simplicity, we assume the agent can read the JSON file we generate
+            }
+            // Snapshot changed files before agent runs
+            let beforeFiles = [];
+            try {
+                const { stdout } = await (0, execa_1.execa)('git', ['status', '--porcelain'], { cwd });
+                beforeFiles = stdout.split('\n').filter(l => l.trim()).map(l => l.slice(3).trim());
+            }
+            catch (e) { }
+            // 2. Run the agent command
+            if (currentArgs.length > 0) {
                 console.log(chalk_1.default.cyan(`\n🚀 DEPLOYING AGENT:`));
-                console.log(chalk_1.default.dim(`   Command: ${agentArgs.join(' ')}`));
+                console.log(chalk_1.default.dim(`   Command: ${currentArgs.join(' ')}`));
                 try {
-                    await (0, execa_1.execa)(agentArgs[0], agentArgs.slice(1), { shell: true, stdio: 'inherit', cwd });
+                    await (0, execa_1.execa)(currentArgs[0], currentArgs.slice(1), { shell: true, stdio: 'inherit', cwd });
                 }
                 catch (error) {
                     console.warn(chalk_1.default.yellow(`\n⚠️  Agent command finished with non-zero exit code. Rigour will now verify state...`));
                 }
             }
-            // 2. Run Rigour Check
+            // Snapshot changed files after agent runs
+            let afterFiles = [];
+            try {
+                const { stdout } = await (0, execa_1.execa)('git', ['status', '--porcelain'], { cwd });
+                afterFiles = stdout.split('\n').filter(l => l.trim()).map(l => l.slice(3).trim());
+            }
+            catch (e) { }
+            const changedThisCycle = afterFiles.filter(f => !beforeFiles.includes(f));
+            const maxFiles = config.gates.safety?.max_files_changed_per_cycle || 10;
+            if (changedThisCycle.length > maxFiles) {
+                console.log(chalk_1.default.red.bold(`\n🛑 SAFETY RAIL ABORT: Agent changed ${changedThisCycle.length} files (max: ${maxFiles}).`));
+                console.log(chalk_1.default.red(`   This looks like explosive behavior. Check your agent's instructions.`));
+                process.exit(EXIT_FAIL);
+            }
+            // 3. Run Rigour Check
             console.log(chalk_1.default.magenta('\n🔍 AUDITING QUALITY GATES...'));
             const report = await runner.run(cwd);
+            // Write report
+            const reportPath = path_1.default.join(cwd, config.output.report_path);
+            await fs_extra_1.default.writeJson(reportPath, report, { spaces: 2 });
             if (report.status === 'PASS') {
                 console.log(chalk_1.default.green.bold('\n✨ PASS - All quality gates satisfied.'));
                 console.log(chalk_1.default.green(`   Your solution meets the required Engineering Rigour criteria.\n`));
                 return;
             }
-            // 3. Generate and print Fix Packet for next iteration
+            // 4. Generate Fix Packet v2
+            const { FixPacketService } = await import('@rigour-labs/core');
+            const fixPacketService = new FixPacketService();
+            const fixPacket = fixPacketService.generate(report, config);
+            const fixPacketPath = path_1.default.join(cwd, 'rigour-fix-packet.json');
+            await fs_extra_1.default.writeJson(fixPacketPath, fixPacket, { spaces: 2 });
             console.log(chalk_1.default.red.bold(`\n🛑 FAIL - Found ${report.failures.length} engineering violations.`));
-            const fixPacket = report.failures.map((f, i) => {
-                let msg = chalk_1.default.white(`${i + 1}. `) + chalk_1.default.bold.red(`[${f.id.toUpperCase()}] `) + chalk_1.default.white(f.title);
-                msg += `\n   ├─ ` + chalk_1.default.dim(`Details: ${f.details}`);
-                if (f.hint)
-                    msg += `\n   └─ ` + chalk_1.default.yellow(`FIX: ${f.hint}`);
-                return msg;
-            }).join('\n\n');
-            console.log(chalk_1.default.bold.white('\n📋 ACTIONABLE FIX PACKET:'));
-            console.log(fixPacket);
-            console.log(chalk_1.default.dim('\nReturning control to agent for the next refinement cycle...'));
+            console.log(chalk_1.default.dim(`   Fix Packet generated: rigour-fix-packet.json`));
+            if (options.failFast) {
+                console.log(chalk_1.default.red.bold(`\n🛑 FAIL-FAST: Aborting loop as requested.`));
+                process.exit(EXIT_FAIL);
+            }
+            // Print summary
+            const summary = report.failures.map((f, i) => {
+                return chalk_1.default.white(`${i + 1}. `) + chalk_1.default.bold.red(`[${f.id.toUpperCase()}] `) + chalk_1.default.white(f.title);
+            }).join('\n');
+            console.log(chalk_1.default.bold.white('\n📋 VIOLATIONS SUMMARY:'));
+            console.log(summary);
             if (iteration === maxIterations) {
                 console.log(chalk_1.default.red.bold(`\n❌ CRITICAL: Reached maximum iterations (${maxIterations}).`));
                 console.log(chalk_1.default.red(`   Quality gates remain unfulfilled. Refactor manually or check agent logs.`));
-                process.exit(1);
+                process.exit(EXIT_FAIL);
             }
+            console.log(chalk_1.default.dim('\nReturning control to agent for the next refinement cycle...'));
         }
     }
     catch (error) {
@@ -71,6 +115,6 @@ async function runLoop(cwd, agentArgs, options) {
         if (error.issues) {
             console.error(chalk_1.default.dim(JSON.stringify(error.issues, null, 2)));
         }
-        process.exit(1);
+        process.exit(EXIT_INTERNAL_ERROR);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigour-labs/cli",
-  "version": "1.0.0",
+  "version": "1.2.1",
   "bin": {
     "rigour": "dist/cli.js"
   },
@@ -20,7 +20,7 @@
     "fs-extra": "^11.2.0",
     "globby": "^14.0.1",
     "yaml": "^2.8.2",
-    "@rigour-labs/core": "1.0.0"
+    "@rigour-labs/core": "1.2.1"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",

package/src/cli.ts

@@ -2,6 +2,7 @@
 import { Command } from 'commander';
 import { initCommand } from './commands/init.js';
 import { checkCommand } from './commands/check.js';
+import { explainCommand } from './commands/explain.js';
 import { runLoop } from './commands/run.js';
 
 const program = new Command();
@@ -13,25 +14,44 @@ program
 
 program
     .command('init')
-    .description('Initialize VibeGuard in the current directory')
-    .action(async () => {
-        await initCommand(process.cwd());
+    .description('Initialize Rigour in the current directory')
+    .option('-p, --preset <name>', 'Project preset (ui, api, infra, data)')
+    .option('--paradigm <name>', 'Coding paradigm (oop, functional, minimal)')
+    .option('--dry-run', 'Show detected configuration without writing files')
+    .option('--explain', 'Show detection markers for roles and paradigms')
+    .action(async (options: any) => {
+        await initCommand(process.cwd(), options);
     });
 
 program
     .command('check')
     .description('Run quality gate checks')
+    .option('--ci', 'CI mode (minimal output, non-zero exit on fail)')
+    .option('--json', 'Output report in JSON format')
+    .action(async (options: any) => {
+        await checkCommand(process.cwd(), options);
+    });
+
+program
+    .command('explain')
+    .description('Explain the last quality gate report with actionable bullets')
     .action(async () => {
-        await checkCommand(process.cwd());
+        await explainCommand(process.cwd());
     });
 
 program
     .command('run')
     .description('Execute an agent command in a loop until quality gates pass')
     .argument('[command...]', 'The agent command to run (e.g., cursor-agent ...)')
-    .option('-i, --iterations <number>', 'Maximum number of loop iterations', '3')
-    .action(async (args, options) => {
-        await runLoop(process.cwd(), args, { iterations: parseInt(options.iterations) });
+    .option('-i, --iterations <number>', 'Maximum number of loop iterations (deprecated, use --max-cycles)', '3')
+    .option('-c, --max-cycles <number>', 'Maximum number of loop iterations', '3')
+    .option('--fail-fast', 'Abort loop immediately on first gate failure')
+    .action(async (args: string[], options: any) => {
+        const maxCycles = parseInt(options.maxCycles || options.iterations);
+        await runLoop(process.cwd(), args, {
+            iterations: maxCycles,
+            failFast: !!options.failFast
+        });
     });
 
 program.parse();

package/src/commands/check.ts

@@ -4,52 +4,105 @@ import chalk from 'chalk';
 import yaml from 'yaml';
 import { GateRunner, ConfigSchema, Failure } from '@rigour-labs/core';
 
-export async function checkCommand(cwd: string) {
+// Exit codes per spec
+const EXIT_PASS = 0;
+const EXIT_FAIL = 1;
+const EXIT_CONFIG_ERROR = 2;
+const EXIT_INTERNAL_ERROR = 3;
+
+export interface CheckOptions {
+    ci?: boolean;
+    json?: boolean;
+}
+
+export async function checkCommand(cwd: string, options: CheckOptions = {}) {
     const configPath = path.join(cwd, 'rigour.yml');
 
     if (!(await fs.pathExists(configPath))) {
-        console.error(chalk.red('Error: rigour.yml not found. Run `rigour init` first.'));
-        process.exit(1);
+        if (options.json) {
+            console.log(JSON.stringify({ error: 'CONFIG_ERROR', message: 'rigour.yml not found' }));
+        } else if (!options.ci) {
+            console.error(chalk.red('Error: rigour.yml not found. Run `rigour init` first.'));
+        }
+        process.exit(EXIT_CONFIG_ERROR);
     }
 
-    const configContent = await fs.readFile(configPath, 'utf-8');
-    const rawConfig = yaml.parse(configContent);
-    const config = ConfigSchema.parse(rawConfig);
+    try {
+        const configContent = await fs.readFile(configPath, 'utf-8');
+        const rawConfig = yaml.parse(configContent);
+        const config = ConfigSchema.parse(rawConfig);
 
-    console.log(chalk.blue('Running Rigour checks...\n'));
+        if (!options.ci && !options.json) {
+            console.log(chalk.blue('Running Rigour checks...\n'));
+        }
+
+        const runner = new GateRunner(config);
+        const report = await runner.run(cwd);
 
-    const runner = new GateRunner(config);
-    const report = await runner.run(cwd);
+        // Write machine report
+        const reportPath = path.join(cwd, config.output.report_path);
+        await fs.writeJson(reportPath, report, { spaces: 2 });
 
-    // Write machine report
-    const reportPath = path.join(cwd, config.output.report_path);
-    await fs.writeJson(reportPath, report, { spaces: 2 });
+        // Generate Fix Packet v2 on failure
+        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(cwd, 'rigour-fix-packet.json');
+            await fs.writeJson(fixPacketPath, fixPacket, { spaces: 2 });
+        }
 
-    // Print human summary
-    if (report.status === 'PASS') {
-        console.log(chalk.green.bold('✔ PASS - All quality gates satisfied.'));
-    } else {
-        console.log(chalk.red.bold('✘ FAIL - Quality gate violations found.\n'));
+        // JSON output mode
+        if (options.json) {
+            console.log(JSON.stringify(report, null, 2));
+            process.exit(report.status === 'PASS' ? EXIT_PASS : EXIT_FAIL);
+        }
 
-        for (const failure of report.failures as Failure[]) {
-            console.log(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: string) => console.log(chalk.dim(`    - ${f}`)));
+        // CI mode: minimal output
+        if (options.ci) {
+            if (report.status === 'PASS') {
+                console.log('PASS');
+            } else {
+                console.log(`FAIL: ${report.failures.length} violation(s)`);
+                report.failures.forEach((f: Failure) => {
+                    console.log(`  - [${f.id}] ${f.title}`);
+                });
             }
-            if (failure.hint) {
-                console.log(chalk.cyan(`  Hint: ${failure.hint}`));
+            process.exit(report.status === 'PASS' ? EXIT_PASS : EXIT_FAIL);
+        }
+
+        // Normal human-readable output
+        if (report.status === 'PASS') {
+            console.log(chalk.green.bold('✔ PASS - All quality gates satisfied.'));
+        } else {
+            console.log(chalk.red.bold('✘ FAIL - Quality gate violations found.\n'));
+
+            for (const failure of report.failures as Failure[]) {
+                console.log(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: string) => console.log(chalk.dim(`    - ${f}`)));
+                }
+                if (failure.hint) {
+                    console.log(chalk.cyan(`  Hint: ${failure.hint}`));
+                }
+                console.log('');
             }
-            console.log('');
+
+            console.log(chalk.yellow(`See ${config.output.report_path} for full details.`));
         }
 
-        console.log(chalk.yellow(`See ${config.output.report_path} for full details.`));
-    }
+        console.log(chalk.dim(`\nFinished in ${report.stats.duration_ms}ms`));
 
-    console.log(chalk.dim(`\nFinished in ${report.stats.duration_ms}ms`));
+        process.exit(report.status === 'PASS' ? EXIT_PASS : EXIT_FAIL);
 
-    if (report.status !== 'PASS') {
-        process.exit(1);
+    } catch (error: any) {
+        if (options.json) {
+            console.log(JSON.stringify({ error: 'INTERNAL_ERROR', message: error.message }));
+        } else if (!options.ci) {
+            console.error(chalk.red(`Internal error: ${error.message}`));
+        }
+        process.exit(EXIT_INTERNAL_ERROR);
     }
 }

package/src/commands/explain.ts

@@ -0,0 +1,68 @@
+import fs from 'fs-extra';
+import path from 'path';
+import chalk from 'chalk';
+
+export async function explainCommand(cwd: string) {
+    const configPath = path.join(cwd, 'rigour.yml');
+    let reportPath = path.join(cwd, 'rigour-report.json');
+
+    // Try to read custom path from config
+    if (await fs.pathExists(configPath)) {
+        try {
+            const yaml = await import('yaml');
+            const configContent = await fs.readFile(configPath, 'utf-8');
+            const config = yaml.parse(configContent);
+            if (config?.output?.report_path) {
+                reportPath = path.join(cwd, config.output.report_path);
+            }
+        } catch (e) { }
+    }
+
+    if (!(await fs.pathExists(reportPath))) {
+        console.error(chalk.red(`Error: No report found at ${reportPath}`));
+        console.error(chalk.dim('Run `rigour check` first to generate a report.'));
+        process.exit(2);
+    }
+
+    try {
+        const reportContent = await fs.readFile(reportPath, 'utf-8');
+        const report = JSON.parse(reportContent);
+
+        console.log(chalk.bold('\n📋 Rigour Report Explanation\n'));
+        console.log(chalk.bold('Status: ') + (report.status === 'PASS'
+            ? chalk.green.bold('✅ PASS')
+            : chalk.red.bold('🛑 FAIL')));
+
+        console.log(chalk.bold('\nGate Summary:'));
+        for (const [gate, status] of Object.entries(report.summary || {})) {
+            const icon = status === 'PASS' ? '✅' : status === 'FAIL' ? '❌' : '⏭️';
+            console.log(`  ${icon} ${gate}: ${status}`);
+        }
+
+        if (report.failures && report.failures.length > 0) {
+            console.log(chalk.bold.red(`\n🔧 ${report.failures.length} Violation(s) to Fix:\n`));
+
+            report.failures.forEach((failure: any, index: number) => {
+                console.log(chalk.white(`${index + 1}. `) + chalk.bold.yellow(`[${failure.id.toUpperCase()}]`) + 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(', ')}`));
+                }
+                if (failure.hint) {
+                    console.log(chalk.green(`   💡 Hint: ${failure.hint}`));
+                }
+                console.log('');
+            });
+        } else if (report.status === 'PASS') {
+            console.log(chalk.green('\n✨ All quality gates passed! No violations found.\n'));
+        }
+
+        if (report.stats) {
+            console.log(chalk.dim(`Duration: ${report.stats.duration_ms}ms`));
+        }
+
+    } catch (error: any) {
+        console.error(chalk.red(`Error reading report: ${error.message}`));
+        process.exit(3);
+    }
+}

package/src/commands/init.ts

@@ -4,9 +4,62 @@ import chalk from 'chalk';
 import yaml from 'yaml';
 import { DiscoveryService } from '@rigour-labs/core';
 
-export async function initCommand(cwd: string) {
+export interface InitOptions {
+    preset?: string;
+    paradigm?: string;
+    dryRun?: boolean;
+    explain?: boolean;
+}
+
+export async function initCommand(cwd: string, options: InitOptions = {}) {
     const discovery = new DiscoveryService();
-    const recommendedConfig = await discovery.discover(cwd);
+    const result = await discovery.discover(cwd);
+    let recommendedConfig = result.config;
+
+    // Override with user options if provided and re-apply template logic if necessary
+    if (options.preset || options.paradigm) {
+        const core = await import('@rigour-labs/core');
+
+        let customBase = { ...core.UNIVERSAL_CONFIG };
+
+        if (options.preset) {
+            const t = core.TEMPLATES.find((t: any) => t.name === options.preset);
+            if (t) customBase = (discovery as any).mergeConfig(customBase, t.config);
+        } else if (recommendedConfig.preset) {
+            const t = core.TEMPLATES.find((t: any) => t.name === recommendedConfig.preset);
+            if (t) customBase = (discovery as any).mergeConfig(customBase, t.config);
+        }
+
+        if (options.paradigm) {
+            const t = core.PARADIGM_TEMPLATES.find((t: any) => t.name === options.paradigm);
+            if (t) customBase = (discovery as any).mergeConfig(customBase, t.config);
+        } else if (recommendedConfig.paradigm) {
+            const t = core.PARADIGM_TEMPLATES.find((t: any) => t.name === recommendedConfig.paradigm);
+            if (t) customBase = (discovery as any).mergeConfig(customBase, t.config);
+        }
+
+        recommendedConfig = customBase;
+        if (options.preset) recommendedConfig.preset = options.preset;
+        if (options.paradigm) recommendedConfig.paradigm = options.paradigm;
+    }
+
+    if (options.dryRun || options.explain) {
+        console.log(chalk.bold.blue('\n🔍 Rigour Auto-Discovery (Dry Run):'));
+        if (recommendedConfig.preset) {
+            console.log(chalk.cyan(`   Role: `) + chalk.bold(recommendedConfig.preset.toUpperCase()));
+            if (options.explain && result.matches.preset) {
+                console.log(chalk.dim(`         (Marker found: ${result.matches.preset.marker})`));
+            }
+        }
+        if (recommendedConfig.paradigm) {
+            console.log(chalk.cyan(`   Paradigm: `) + chalk.bold(recommendedConfig.paradigm.toUpperCase()));
+            if (options.explain && result.matches.paradigm) {
+                console.log(chalk.dim(`             (Marker found: ${result.matches.paradigm.marker})`));
+            }
+        }
+        console.log(chalk.yellow('\n[DRY RUN] No files will be written.'));
+        return;
+    }
 
     const configPath = path.join(cwd, 'rigour.yml');
 
@@ -15,6 +68,15 @@ export async function initCommand(cwd: string) {
         return;
     }
 
+    console.log(chalk.bold.blue('\n🔍 Rigour Auto-Discovery:'));
+    if (recommendedConfig.preset) {
+        console.log(chalk.cyan(`   Role: `) + chalk.bold(recommendedConfig.preset.toUpperCase()));
+    }
+    if (recommendedConfig.paradigm) {
+        console.log(chalk.cyan(`   Paradigm: `) + chalk.bold(recommendedConfig.paradigm.toUpperCase()));
+    }
+    console.log('');
+
     await fs.writeFile(configPath, yaml.stringify(recommendedConfig));
     console.log(chalk.green('✔ Created rigour.yml'));
 
@@ -28,36 +90,56 @@ export async function initCommand(cwd: string) {
         }
     }
 
-    // Agent Handshake (Cursor/AntiGravity)
-    const cursorRulesDir = path.join(cwd, '.cursor', 'rules');
-    await fs.ensureDir(cursorRulesDir);
-    const rulePath = path.join(cursorRulesDir, 'rigour.mdc');
+    // Agent Handshake (Universal / AntiGravity / Cursor)
+    const rigourDocsDir = path.join(cwd, 'docs');
+    await fs.ensureDir(rigourDocsDir);
+    const instructionsPath = path.join(rigourDocsDir, 'AGENT_INSTRUCTIONS.md');
 
-    const ruleContent = `---
-description: Enforcement of Rigour quality gates and best practices.
-globs: **/*
----
+    const ruleContent = `# 🛡️ Rigour: Engineering Excellence Protocol
+
+You are an Elite Software Engineer. You do not just write code that "works"; you write code that is **modular, maintainable, and rigorously verified.**
+
+## 🚦 The Rigour Loop (Mandatory)
+Before claiming "Done" for any task, you MUST follow this loop:
 
-# Rigour Enforcement
+1.  **Check**: Run \`npx @rigour-labs/cli check\` to verify compliance.
+2.  **Analyze**: If it fails, read \`rigour-fix-packet.json\` (V2 High-Fidelity) for exact failure points and constraints.
+3.  **Refactor**: Apply **SOLID** and **DRY** principles to resolve the violations according to constraints.
+4.  **Repeat**: Continue until \`npx @rigour-labs/cli check\` returns **PASS**.
 
-You are operating under Rigour engineering discipline.
+## 🧩 Engineering Standards
+- **Single Responsibility**: Keep files small and focused (max 500 lines).
+- **DRY (Don't Repeat Yourself)**: Extract common logic into utilities.
+- **Done is Done**: No \`TODO\` or \`FIXME\` comments allowed in the final state.
+- **Memory Preservation**: Always update docs/SPEC.md, docs/ARCH.md, docs/DECISIONS.md.
 
-## Core Rules
-- **Never claim done** until you run \`rigour check\` and it returns PASS.
-- If checks FAIL, fix **only** the listed failures. Do not add new features or refactor unrelated code.
-- Maintain project memory in \`docs/SPEC.md\`, \`docs/ARCH.md\`, and \`docs/DECISIONS.md\`.
-- Keep files modular. If a file exceeds 500 lines, you MUST break it into smaller components.
-- No \`TODO\` or \`FIXME\` comments allowed in the final submission.
+## 🛠️ Commands
+\`\`\`bash
+# Verify current state
+npx @rigour-labs/cli check
 
-## Workflow
-1. Write/Modify code.
-2. Run \`rigour check\`.
-3. If FAIL: Read \`rigour-report.json\` for exact failure points and fix them.
-4. If PASS: You may claim task completion.
+# Self-healing agent loop
+npx @rigour-labs/cli run -- <agent-command>
+\`\`\`
 `;
 
-    await fs.writeFile(rulePath, ruleContent);
-    console.log(chalk.green('✔ Initialized Agent Handshake (.cursor/rules/rigour.mdc)'));
+    // 1. Create Universal Instructions
+    await fs.writeFile(instructionsPath, ruleContent);
+    console.log(chalk.green('✔ Initialized Universal Agent Handshake (docs/AGENT_INSTRUCTIONS.md)'));
+
+    // 2. Create Cursor Specific Rules (.mdc)
+    const cursorRulesDir = path.join(cwd, '.cursor', 'rules');
+    await fs.ensureDir(cursorRulesDir);
+    const mdcPath = path.join(cursorRulesDir, 'rigour.mdc');
+    const mdcContent = `---
+description: Enforcement of Rigour quality gates and best practices.
+globs: **/*
+---
+
+${ruleContent}`;
+
+    await fs.writeFile(mdcPath, mdcContent);
+    console.log(chalk.green('✔ Initialized Cursor Handshake (.cursor/rules/rigour.mdc)'));
 
-    console.log(chalk.blue('\nRigour is ready. Run `rigour check` to verify your project.'));
+    console.log(chalk.blue('\nRigour is ready. Run `npx @rigour-labs/cli check` to verify your project.'));
 }

package/src/commands/run.ts

@@ -5,12 +5,18 @@ import yaml from 'yaml';
 import { execa } from 'execa';
 import { GateRunner, ConfigSchema } from '@rigour-labs/core';
 
-export async function runLoop(cwd: string, agentArgs: string[], options: { iterations: number }) {
+// Exit codes per spec
+const EXIT_PASS = 0;
+const EXIT_FAIL = 1;
+const EXIT_CONFIG_ERROR = 2;
+const EXIT_INTERNAL_ERROR = 3;
+
+export async function runLoop(cwd: string, agentArgs: string[], options: { iterations: number, failFast?: boolean }) {
     const configPath = path.join(cwd, 'rigour.yml');
 
     if (!(await fs.pathExists(configPath))) {
         console.error(chalk.red('Error: rigour.yml not found. Run `rigour init` first.'));
-        process.exit(1);
+        process.exit(EXIT_CONFIG_ERROR);
     }
 
     try {
@@ -28,52 +34,98 @@ export async function runLoop(cwd: string, agentArgs: string[], options: { itera
             console.log(chalk.bold.blue(`  RIGOUR LOOP: Iteration ${iteration}/${maxIterations}`));
             console.log(chalk.bold.blue(`══════════════════════════════════════════════════════════════════`));
 
-            // 1. Run the agent command
-            if (agentArgs.length > 0) {
+            // 1. Prepare Command
+            let currentArgs = [...agentArgs];
+            if (iteration > 1 && agentArgs.length > 0) {
+                // Iteration contract: In later cycles, we focus strictly on the fix packet
+                console.log(chalk.yellow(`\n🔄 REFINEMENT CYCLE - Instructing agent to fix specific violations...`));
+                // We keep the first part of the command (the agent) but can append or wrap
+                // For simplicity, we assume the agent can read the JSON file we generate
+            }
+
+            // Snapshot changed files before agent runs
+            let beforeFiles: string[] = [];
+            try {
+                const { stdout } = await execa('git', ['status', '--porcelain'], { cwd });
+                beforeFiles = stdout.split('\n').filter(l => l.trim()).map(l => l.slice(3).trim());
+            } catch (e) { }
+
+            // 2. Run the agent command
+            if (currentArgs.length > 0) {
                 console.log(chalk.cyan(`\n🚀 DEPLOYING AGENT:`));
-                console.log(chalk.dim(`   Command: ${agentArgs.join(' ')}`));
+                console.log(chalk.dim(`   Command: ${currentArgs.join(' ')}`));
                 try {
-                    await execa(agentArgs[0], agentArgs.slice(1), { shell: true, stdio: 'inherit', cwd });
+                    await execa(currentArgs[0], currentArgs.slice(1), { shell: true, stdio: 'inherit', cwd });
                 } catch (error: any) {
                     console.warn(chalk.yellow(`\n⚠️  Agent command finished with non-zero exit code. Rigour will now verify state...`));
                 }
             }
 
-            // 2. Run Rigour Check
+            // Snapshot changed files after agent runs
+            let afterFiles: string[] = [];
+            try {
+                const { stdout } = await execa('git', ['status', '--porcelain'], { cwd });
+                afterFiles = stdout.split('\n').filter(l => l.trim()).map(l => l.slice(3).trim());
+            } catch (e) { }
+
+            const changedThisCycle = afterFiles.filter(f => !beforeFiles.includes(f));
+            const maxFiles = config.gates.safety?.max_files_changed_per_cycle || 10;
+
+            if (changedThisCycle.length > maxFiles) {
+                console.log(chalk.red.bold(`\n🛑 SAFETY RAIL ABORT: Agent changed ${changedThisCycle.length} files (max: ${maxFiles}).`));
+                console.log(chalk.red(`   This looks like explosive behavior. Check your agent's instructions.`));
+                process.exit(EXIT_FAIL);
+            }
+
+            // 3. Run Rigour Check
             console.log(chalk.magenta('\n🔍 AUDITING QUALITY GATES...'));
             const report = await runner.run(cwd);
 
+            // Write report
+            const reportPath = path.join(cwd, config.output.report_path);
+            await fs.writeJson(reportPath, report, { spaces: 2 });
+
             if (report.status === 'PASS') {
                 console.log(chalk.green.bold('\n✨ PASS - All quality gates satisfied.'));
                 console.log(chalk.green(`   Your solution meets the required Engineering Rigour criteria.\n`));
                 return;
             }
 
-            // 3. Generate and print Fix Packet for next iteration
+            // 4. Generate Fix Packet v2
+            const { FixPacketService } = await import('@rigour-labs/core');
+            const fixPacketService = new FixPacketService();
+            const fixPacket = fixPacketService.generate(report, config);
+            const fixPacketPath = path.join(cwd, 'rigour-fix-packet.json');
+            await fs.writeJson(fixPacketPath, fixPacket, { spaces: 2 });
+
             console.log(chalk.red.bold(`\n🛑 FAIL - Found ${report.failures.length} engineering violations.`));
+            console.log(chalk.dim(`   Fix Packet generated: rigour-fix-packet.json`));
 
-            const fixPacket = report.failures.map((f, i) => {
-                let msg = chalk.white(`${i + 1}. `) + chalk.bold.red(`[${f.id.toUpperCase()}] `) + chalk.white(f.title);
-                msg += `\n   ├─ ` + chalk.dim(`Details: ${f.details}`);
-                if (f.hint) msg += `\n   └─ ` + chalk.yellow(`FIX: ${f.hint}`);
-                return msg;
-            }).join('\n\n');
+            if (options.failFast) {
+                console.log(chalk.red.bold(`\n🛑 FAIL-FAST: Aborting loop as requested.`));
+                process.exit(EXIT_FAIL);
+            }
 
-            console.log(chalk.bold.white('\n📋 ACTIONABLE FIX PACKET:'));
-            console.log(fixPacket);
-            console.log(chalk.dim('\nReturning control to agent for the next refinement cycle...'));
+            // Print summary
+            const summary = report.failures.map((f, i) => {
+                return chalk.white(`${i + 1}. `) + chalk.bold.red(`[${f.id.toUpperCase()}] `) + chalk.white(f.title);
+            }).join('\n');
+            console.log(chalk.bold.white('\n📋 VIOLATIONS SUMMARY:'));
+            console.log(summary);
 
             if (iteration === maxIterations) {
                 console.log(chalk.red.bold(`\n❌ CRITICAL: Reached maximum iterations (${maxIterations}).`));
                 console.log(chalk.red(`   Quality gates remain unfulfilled. Refactor manually or check agent logs.`));
-                process.exit(1);
+                process.exit(EXIT_FAIL);
             }
+
+            console.log(chalk.dim('\nReturning control to agent for the next refinement cycle...'));
         }
     } catch (error: any) {
         console.error(chalk.red(`\n❌ FATAL ERROR: ${error.message}`));
         if (error.issues) {
             console.error(chalk.dim(JSON.stringify(error.issues, null, 2)));
         }
-        process.exit(1);
+        process.exit(EXIT_INTERNAL_ERROR);
     }
 }