claude-git-hooks 2.33.1 → 2.34.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ Todos los cambios notables en este proyecto se documentarán en este archivo.
 El formato está basado en [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.34.0] - 2026-03-27
+
+### ✨ Added
+- Pre-commit linting with ESLint, Spotless, and sqlfluff - runs before Claude analysis with auto-fix and re-stage
+- `lint` command - run linters on staged files, directories, or specific files (`claude-hooks lint [paths...]`)
+- Linter availability check during installation - verifies linter presence per preset and shows install instructions
+- Generic tool executor infrastructure (`tool-runner.js`) for linters and future formatters
+- Linter orchestration system (`linter-runner.js`) with preset-to-linter mapping
+- Maven availability check during installation with install instructions for backend/fullstack presets
+
+### 🔧 Changed
+- Pre-commit flow now runs linting before Claude analysis - fast, deterministic checks first
+- Unfixable lint issues are forwarded to the judge for semantic resolution
+- Updated documentation to reflect new linting workflow and command usage
+
+### 🐛 Fixed
+- WSL Claude CLI detection in non-default distros (#120, #121)
+
+
 ## [2.33.1] - 2026-03-26
 
 ### 🔧 Changed

package/CLAUDE.md

@@ -6,17 +6,19 @@
 
 **Main use cases:**
 
-1. **Pre-commit analysis**: Detects security issues, bugs, and code smells before each commit (blocks on CRITICAL/BLOCKER only)
-2. **Interactive analysis**: `claude-hooks analyze` - review all issues (INFO to BLOCKER) interactively before committing
-3. **Automatic messages**: Write `git commit -m "auto"` and Claude generates the message in Conventional Commits format with task-id extracted from branch
-4. **PR analysis**: `claude-hooks analyze-diff [branch]` generates title, description, and test plan for PRs
-5. **PR review**: `claude-hooks analyze-pr <url>` analyzes a GitHub PR with preset guidelines, Linear ticket enrichment, and posts review comments
-6. **PR creation**: `claude-hooks create-pr [branch]` creates the PR on GitHub with automatic metadata (reviewers from CODEOWNERS, labels by preset, merge strategy auto-detected from branch naming)
-7. **Coupling detection**: `claude-hooks check-coupling` scans open PRs targeting a base branch, computes file overlap, and reports which features are coupled (share modified files) — helps TL make informed decisions before cutting a release
-8. **Shadow management**: `claude-hooks shadow <analyze|reset|sync>` manages the shadow branch lifecycle — analyze divergence vs main and active RC, reset shadow to a clean copy of main, or sync shadow with a source branch (RC, develop, feature)
-9. **Release creation**: `claude-hooks create-release <major|minor|patch>` creates a release-candidate branch from develop, bumps version files, commits, pushes, and deploys to shadow — replaces the 8 manual steps executed every Tuesday by the Tech Lead
-10. **Feature revert**: `claude-hooks revert-feature <task-id>` finds a squash-merged feature commit by task ID in the current release-candidate, checks coupling with other RC features, reverts it, pushes, and optionally re-deploys shadow
-11. **Release closure**: `claude-hooks close-release [description]` finalizes the active release-candidate — soft-resets onto main, creates a single clean commit, force-pushes, and creates a PR to main with the merge-commit strategy
+1. **Pre-commit linting**: Runs linters (ESLint, Spotless, sqlfluff) on staged files before Claude analysis — fast, deterministic, auto-fix enabled by default
+2. **Pre-commit analysis**: Detects security issues, bugs, and code smells before each commit (blocks on CRITICAL/BLOCKER only)
+3. **Interactive analysis**: `claude-hooks analyze` - review all issues (INFO to BLOCKER) interactively before committing
+4. **Automatic messages**: Write `git commit -m "auto"` and Claude generates the message in Conventional Commits format with task-id extracted from branch
+5. **PR analysis**: `claude-hooks analyze-diff [branch]` generates title, description, and test plan for PRs
+6. **PR review**: `claude-hooks analyze-pr <url>` analyzes a GitHub PR with preset guidelines, Linear ticket enrichment, and posts review comments
+7. **PR creation**: `claude-hooks create-pr [branch]` creates the PR on GitHub with automatic metadata (reviewers from CODEOWNERS, labels by preset, merge strategy auto-detected from branch naming)
+8. **Linting**: `claude-hooks lint [paths...]` runs linters on staged files, directories, or specific files — supports ESLint, Spotless, sqlfluff per preset
+9. **Coupling detection**: `claude-hooks check-coupling` scans open PRs targeting a base branch, computes file overlap, and reports which features are coupled (share modified files) — helps TL make informed decisions before cutting a release
+10. **Shadow management**: `claude-hooks shadow <analyze|reset|sync>` manages the shadow branch lifecycle — analyze divergence vs main and active RC, reset shadow to a clean copy of main, or sync shadow with a source branch (RC, develop, feature)
+11. **Release creation**: `claude-hooks create-release <major|minor|patch>` creates a release-candidate branch from develop, bumps version files, commits, pushes, and deploys to shadow — replaces the 8 manual steps executed every Tuesday by the Tech Lead
+12. **Feature revert**: `claude-hooks revert-feature <task-id>` finds a squash-merged feature commit by task ID in the current release-candidate, checks coupling with other RC features, reverts it, pushes, and optionally re-deploys shadow
+13. **Release closure**: `claude-hooks close-release [description]` finalizes the active release-candidate — soft-resets onto main, creates a single clean commit, force-pushes, and creates a PR to main with the merge-commit strategy
 
 ## Architecture
 
@@ -57,7 +59,7 @@ claude-git-hooks/
 │   ├── config.js                     # Config system - load/merge with priority
 │   ├── commands/                     # Command modules - one file per CLI command
 │   │   ├── helpers.js                # Shared CLI utilities - colors, output, platform
-│   │   ├── install.js                # Install command - dependencies, hooks, templates
+│   │   ├── install.js                # Install command - dependencies, hooks, templates, linter check
 │   │   ├── hooks.js                  # Hook management - enable, disable, status, uninstall
 │   │   ├── analyze-diff.js           # Diff analysis - generate PR metadata from git diff
 │   │   ├── analyze-pr.js             # PR analysis - analyze GitHub PR with team guidelines
@@ -77,11 +79,14 @@ claude-git-hooks/
 │   │   ├── bump-version.js           # Version management - bump with commit, CHANGELOG and tags
 │   │   ├── generate-changelog.js     # CHANGELOG generation - standalone command
 │   │   ├── diff-batch-info.js        # Batch info - orchestration config + speed telemetry (v2.20.0)
+│   │   ├── lint.js                    # Lint command - run linters on staged files, dirs, or files
 │   │   └── help.js                   # Help, AI help, and report-issue commands
 │   ├── hooks/                        # Git hooks - Node.js implementations
 │   │   ├── pre-commit.js             # Pre-commit analysis - code quality gate
 │   │   └── prepare-commit-msg.js     # Message generation - auto commit messages
 │   └── utils/                        # Reusable modules - shared logic
+│       ├── tool-runner.js            # Generic tool executor - resolve, spawn, parse, auto-fix (v2.34.0)
+│       ├── linter-runner.js          # Linter orchestration - preset mapping, ESLint/Spotless/sqlfluff (v2.34.0)
 │       ├── analysis-engine.js        # Shared analysis logic - file data, 3-tier routing, results (v2.13.0+)
 │       ├── diff-analysis-orchestrator.js  # Intelligent batch orchestration via Opus (v2.20.0)
 │       ├── claude-client.js          # Claude CLI wrapper - spawn, retry, model override
@@ -218,6 +223,11 @@ preset config (.claude/presets/{name}/config.json)  ← HIGHEST PRIORITY
 | Judge timeout          | 120s    | Per-judge call timeout                              |
 | PR analysis model      | sonnet  | Default, configurable via `config.prAnalysis.model` |
 | PR analysis timeout    | 300s    | Per-analysis Claude call                            |
+| Linting enabled        | true    | Runs linters before Claude analysis                 |
+| Linting auto-fix       | true    | Auto-fix and re-stage files                         |
+| Linting fail on error  | true    | Block commit on linting errors                      |
+| Linting fail on warn   | false   | Do not block on warnings                            |
+| Linting timeout        | 30s     | Per-linter timeout                                  |
 
 **Judge behavior (v2.20.0):**
 
@@ -299,6 +309,7 @@ consolidateResults()
 | `debug.js`              | Debug toggle                | `runSetDebug()`                                                                                    |
 | `telemetry-cmd.js`      | Telemetry commands          | `runShowTelemetry()`, `runClearTelemetry()`                                                        |
 | `diff-batch-info.js`    | Batch info display          | `runDiffBatchInfo()`                                                                               |
+| `lint.js`               | Lint command                | `runLint()`, `resolvePaths()`                                                                      |
 | `help.js`               | Help, AI help, report-issue | `runShowHelp()`, `showStaticHelp()`, `runShowVersion()`                                            |
 
 **Utility Modules (`lib/utils/`):**
@@ -307,6 +318,8 @@ consolidateResults()
 | ------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `lib/cli-metadata.js`           | Command registry                | `commands`, `buildCommandMap()`, `generateCompletionData()`, `PRESET_NAMES`, `HOOK_NAMES`, `BUMP_TYPES`                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `lib/config.js`                 | Config system                   | `getConfig()`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `tool-runner.js`                | Generic tool executor           | `isToolAvailable()`, `filterFilesByTool()`, `runTool()`, `runToolFix()`, `runToolWithAutoFix()`, `displayToolResult()` (v2.34.0)                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `linter-runner.js`              | Linter orchestration            | `runLinters()`, `displayLintResults()`, `checkLinterAvailability()`, `getLinterToolsForPreset()`, `LINTER_TOOLS`, `PRESET_LINTERS`, `parseEslintOutput()`, `parseSpotlessOutput()`, `parseSqlfluffOutput()`, `filesToSpotlessRegex()` (v2.34.0)                                                                                                                                                                                                                                                                                                            |
 | `analysis-engine.js`            | Shared analysis logic           | `buildFileData()`, `buildFilesData()`, `runAnalysis()`, `consolidateResults()`, `hasBlockingIssues()`, `hasAnyIssues()`, `displayResults()`, `displayIssueSummary()` (v2.13.0+)                                                                                                                                                                                                                                                                                                                                                                            |
 | `diff-analysis-orchestrator.js` | Intelligent batch orchestration | `orchestrateBatches()`, `buildFileOverview()`, `detectDependencies()` (v2.20.0)                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `claude-client.js`              | Claude CLI wrapper              | `analyzeCode()`, `executeClaudeWithRetry()`, `extractJSON()` — spawn, retry, model override                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
@@ -347,15 +360,36 @@ consolidateResults()
 8. **Singleton Pattern**: `config.js` loads configuration once per execution
 9. **Guard Pattern**: `authorization.js` — fail-closed gate in `bin/claude-hooks` before command dispatch; static `PROTECTED_COMMANDS` set avoids API calls for unprotected commands; permissions sourced from `mscope-S-L/git-hooks-config/permissions.json`
 10. **Remote Config Pattern**: `remote-config.js` — fetches JSON from `mscope-S-L/git-hooks-config`, caches per-process (including nulls), graceful degradation (warn + return null); `label-resolver.js` — callers receive config via dependency injection and decide fallback
+11. **Pipeline Pattern**: `tool-runner.js` + `linter-runner.js` — generic tool execution infrastructure; linters (and future formatters) share the same resolve → spawn → parse → fix → re-stage pipeline. Tool definitions are data objects, not classes.
 
 ### Key Data Flows
 
+**Flow 0: Pre-commit linting (v2.34.0)**
+
+```
+git commit
+  → hook reads staged files
+  → filters by preset extensions + size
+  ↓
+  → LINTING STEP (fast, deterministic)
+    → getLinterToolsForPreset(presetName) → applicable linters
+    → for each linter:
+        isToolAvailable() → not found? warn + install hint → skip
+        filterFilesByTool() → matching files
+        runToolWithAutoFix() → check → auto-fix → re-stage → re-check
+    → if failOnError && errors remain → exit 1 (COMMIT BLOCKED)
+    → if failOnWarning && warnings → exit 1 (COMMIT BLOCKED)
+  ↓
+  → continues to Claude analysis
+```
+
 **Flow 1: Pre-commit with blocking**
 
 ```
 git commit
   → hook reads staged files
   → filters by preset extensions
+  → [linting step — see Flow 0]
   → builds prompt with diff
   → Claude analyzes → detects issues
   → judge evaluates ALL issues (any severity):
@@ -1107,6 +1141,13 @@ claude-hooks presets                  # List available presets
 claude-hooks --set-preset backend     # Change preset
 claude-hooks preset current           # View current preset
 
+# Linting
+claude-hooks lint                     # Lint staged files
+claude-hooks lint src/                # Lint all files in directory
+claude-hooks lint src/ lib/utils/     # Multiple directories
+claude-hooks lint file1.js file2.js   # Specific files
+claude-hooks lint src/ file.js lib/   # Mix of dirs and files
+
 # Analysis and PRs
 claude-hooks analyze-diff [branch]    # Analyze diff for PR
 claude-hooks analyze-pr <pr-url>      # Analyze GitHub PR with team guidelines

package/bin/claude-hooks

@@ -187,6 +187,7 @@ async function main() {
     if (
         [
             'install',
+            'lint',
             'analyze-diff',
             'analyze-pr',
             'back-merge',

package/lib/cli-metadata.js

@@ -97,6 +97,15 @@ export const commands = [
         description: 'Show hook status',
         handler: async () => (await import('./commands/hooks.js')).runStatus
     },
+    {
+        name: 'lint',
+        description: 'Run linters on staged files, directories, or specific files',
+        handler: async () => (await import('./commands/lint.js')).runLint,
+        args: {
+            name: 'paths',
+            completion: "find . -maxdepth 3 -type d -not -path '*/\\.*' -not -path '*/node_modules/*'"
+        }
+    },
     {
         name: 'analyze',
         description: 'Analyze code interactively before committing',

package/lib/commands/install.js

@@ -32,6 +32,7 @@ import {
 } from './helpers.js';
 import { runSetupGitHub } from './setup-github.js';
 import { generateCompletionData } from '../cli-metadata.js';
+import { getConfig } from '../config.js';
 
 /**
  * Function to check version (used by hooks)
@@ -186,6 +187,17 @@ async function checkAndInstallDependencies(skipAuth = false) {
         error('npm is not installed.');
     }
 
+    // Check Maven (optional — needed for backend/fullstack presets with Spotless)
+    try {
+        const mvnVersion = execSync('mvn --version', { encoding: 'utf8', timeout: 5000 })
+            .split('\n')[0].trim();
+        success(`${mvnVersion}`);
+    } catch {
+        warning('Maven (mvn) not found — required for Spotless linting in backend/fullstack presets');
+        info('   Install: https://maven.apache.org/install.html');
+        info('   Or via package manager: brew install maven / choco install maven / apt install maven');
+    }
+
     // v2.0.0+: jq and curl are no longer needed (pure Node.js implementation)
 
     // Check Git
@@ -655,6 +667,18 @@ export async function runInstall(args) {
     // Install shell completions
     installCompletions();
 
+    // Check linter toolchain availability for the selected preset
+    try {
+        const config = await getConfig();
+        const presetName = config.preset || 'default';
+        if (config.linting?.enabled !== false) {
+            const { checkLinterAvailability } = await import('../utils/linter-runner.js');
+            checkLinterAvailability(presetName);
+        }
+    } catch {
+        // Non-fatal — linter check failure should not block installation
+    }
+
     success('Claude Git Hooks installed successfully! 🎉');
     console.log('\nRun claude-hooks --help to see all available commands.');
 

package/lib/commands/lint.js

@@ -0,0 +1,187 @@
+/**
+ * File: lint.js
+ * Purpose: CLI command to run linters on files or directories
+ *
+ * Usage:
+ *   claude-hooks lint                          # lint staged files
+ *   claude-hooks lint src/                     # lint all files in src/
+ *   claude-hooks lint src/ lib/utils/          # multiple directories
+ *   claude-hooks lint file1.js file2.java      # specific files
+ *   claude-hooks lint src/ file3.js lib/       # mix of dirs and files
+ *
+ * Path resolution (like git add):
+ * - Directories → walk and collect files matching preset extensions
+ * - Files → use directly
+ * - No args → fall back to staged files
+ *
+ * Dependencies:
+ * - linter-runner: Linter orchestration
+ * - git-operations: Staged files, repo root
+ * - file-utils: Directory walking
+ * - preset-loader: Extension filtering
+ * - config: Linting configuration
+ * - helpers: checkGitRepo, colors
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { checkGitRepo, error, info } from './helpers.js';
+import { getConfig } from '../config.js';
+import { loadPreset } from '../utils/preset-loader.js';
+import { getStagedFiles, getRepoRoot } from '../utils/git-operations.js';
+import { runLinters, displayLintResults } from '../utils/linter-runner.js';
+import logger from '../utils/logger.js';
+
+/**
+ * Resolve user-provided paths into a flat list of files
+ * Handles directories (walked recursively), individual files, and mixtures.
+ *
+ * @param {string[]} paths - User-provided paths (files and/or directories)
+ * @param {string[]} extensions - Allowed file extensions from preset
+ * @param {string} repoRoot - Repository root for relative path resolution
+ * @returns {string[]} Resolved file paths (relative to cwd)
+ */
+export function resolvePaths(paths, extensions, _repoRoot) {
+    const files = new Set();
+    const extSet = new Set(extensions.map((e) => e.toLowerCase()));
+
+    for (const userPath of paths) {
+        const resolved = path.resolve(userPath);
+
+        if (!fs.existsSync(resolved)) {
+            logger.warning(`Path not found: ${userPath}`);
+            continue;
+        }
+
+        const stat = fs.statSync(resolved);
+
+        if (stat.isFile()) {
+            // Accept file if it matches preset extensions, or if no extensions filter
+            const ext = path.extname(resolved).toLowerCase();
+            if (extSet.size === 0 || extSet.has(ext)) {
+                files.add(path.relative(process.cwd(), resolved));
+            } else {
+                logger.debug('lint - resolvePaths', `Skipping ${userPath}: extension ${ext} not in preset`);
+            }
+        } else if (stat.isDirectory()) {
+            // Walk directory and collect matching files
+            _walkForFiles(resolved, extSet, files);
+        }
+    }
+
+    return Array.from(files);
+}
+
+/**
+ * Recursively walk a directory collecting files that match extensions
+ *
+ * @param {string} dir - Directory to walk
+ * @param {Set<string>} extSet - Allowed extensions
+ * @param {Set<string>} files - Accumulator set of relative file paths
+ * @param {number} [depth] - Current depth (max 10)
+ */
+function _walkForFiles(dir, extSet, files, depth = 0) {
+    if (depth > 10) return;
+
+    try {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+        for (const entry of entries) {
+            // Skip hidden dirs, node_modules, target, build
+            if (
+                entry.name.startsWith('.') ||
+                entry.name === 'node_modules' ||
+                entry.name === 'target' ||
+                entry.name === 'build' ||
+                entry.name === 'dist'
+            ) {
+                continue;
+            }
+
+            const fullPath = path.join(dir, entry.name);
+
+            if (entry.isDirectory()) {
+                _walkForFiles(fullPath, extSet, files, depth + 1);
+            } else if (entry.isFile()) {
+                const ext = path.extname(entry.name).toLowerCase();
+                if (extSet.size === 0 || extSet.has(ext)) {
+                    files.add(path.relative(process.cwd(), fullPath));
+                }
+            }
+        }
+    } catch (err) {
+        logger.debug('lint - _walkForFiles', `Cannot read directory: ${dir}`, {
+            error: err.message
+        });
+    }
+}
+
+/**
+ * Main lint command handler
+ *
+ * @param {string[]} args - CLI arguments (paths and flags)
+ */
+export async function runLint(args = []) {
+    if (!checkGitRepo()) {
+        error('Not a git repository');
+        process.exit(1);
+    }
+
+    const config = await getConfig();
+
+    if (config.system?.debug) {
+        logger.setDebugMode(true);
+    }
+
+    if (config.linting?.enabled === false) {
+        info('Linting is disabled in configuration');
+        return;
+    }
+
+    const repoRoot = getRepoRoot();
+    const presetName = config.preset || 'default';
+    const { metadata } = await loadPreset(presetName);
+
+    // Separate flags from paths
+    const paths = args.filter((a) => !a.startsWith('--'));
+
+    let filesToLint;
+
+    if (paths.length === 0) {
+        // No paths → lint staged files
+        info('No paths specified — linting staged files');
+        const stagedFiles = getStagedFiles({ extensions: metadata.fileExtensions });
+
+        if (stagedFiles.length === 0) {
+            info('No staged files to lint');
+            return;
+        }
+
+        filesToLint = stagedFiles;
+    } else {
+        // Resolve user-provided paths
+        filesToLint = resolvePaths(paths, metadata.fileExtensions, repoRoot);
+
+        if (filesToLint.length === 0) {
+            info('No matching files found in specified paths');
+            return;
+        }
+    }
+
+    info(`🎯 Linting ${filesToLint.length} file(s) with '${metadata.displayName}' preset`);
+
+    const lintResult = runLinters(filesToLint, config, presetName);
+    displayLintResults(lintResult);
+
+    // Exit with error code if linting failed
+    const failOnError = config.linting?.failOnError !== false;
+    const failOnWarning = config.linting?.failOnWarning === true;
+
+    if (failOnError && lintResult.totalErrors > 0) {
+        process.exit(1);
+    }
+
+    if (failOnWarning && lintResult.totalWarnings > 0) {
+        process.exit(1);
+    }
+}

package/lib/config.js

@@ -84,6 +84,13 @@ const HARDCODED = {
             'documentation',
             'testing'
         ]
+    },
+    linting: {
+        enabled: true, // Run linters before Claude analysis
+        autoFix: true, // Auto-fix and re-stage
+        failOnError: true, // Block commit on linting errors
+        failOnWarning: false, // Do not block on warnings
+        timeout: 30000 // 30s per linter
     }
 };
 

package/lib/hooks/pre-commit.js

@@ -33,6 +33,7 @@ import { getVersion } from '../utils/package-info.js';
 import logger from '../utils/logger.js';
 import { getConfig } from '../config.js';
 import { recordMetric } from '../utils/metrics.js';
+import { runLinters, displayLintResults, lintIssuesToAnalysisDetails } from '../utils/linter-runner.js';
 
 /**
  * Configuration loaded from lib/config.js
@@ -144,11 +145,45 @@ const main = async () => {
             process.exit(0);
         }
 
-        // Step 3: Build file data using shared engine
+        // Step 3: Run linters (fast, deterministic — before Claude analysis)
+        // Unfixable lint issues are forwarded to the judge for semantic resolution
+        let unfixableLintDetails = [];
+        if (config.linting?.enabled !== false) {
+            logger.info('🔍 Running linters...');
+            const lintStartTime = Date.now();
+            const filePaths = validFiles.map((f) => (typeof f === 'string' ? f : f.path));
+            const lintResult = runLinters(filePaths, config, presetName);
+            displayLintResults(lintResult);
+
+            // Record lint metric
+            recordMetric('linting.completed', {
+                preset: presetName,
+                fileCount: filePaths.length,
+                totalErrors: lintResult.totalErrors,
+                totalWarnings: lintResult.totalWarnings,
+                totalFixed: lintResult.totalFixed,
+                toolsRun: lintResult.results.filter((r) => !r.skipped).length,
+                toolsSkipped: lintResult.results.filter((r) => r.skipped).length,
+                duration: Date.now() - lintStartTime
+            }).catch((err) => {
+                logger.debug('pre-commit - main', 'Lint metrics recording failed', err);
+            });
+
+            // Forward all remaining lint issues (errors + warnings) to the judge
+            // The judge decides whether to fix, dismiss, or block — no hard exit here
+            if (lintResult.totalErrors > 0 || lintResult.totalWarnings > 0) {
+                unfixableLintDetails = lintIssuesToAnalysisDetails(lintResult);
+                logger.debug('pre-commit - main', 'Forwarding unfixable lint issues to judge', {
+                    count: unfixableLintDetails.length
+                });
+            }
+        }
+
+        // Step 4: Build file data using shared engine
         logger.debug('pre-commit - main', 'Building file data for analysis');
         const filesData = buildFilesData(validFiles, { staged: true });
 
-        // Step 4: Log analysis configuration
+        // Step 5: Log analysis configuration
         logger.info(`Sending ${filesData.length} files for review...`);
 
         // Display analysis routing hint
@@ -156,51 +191,82 @@ const main = async () => {
             logger.info('⚡ Intelligent orchestration: grouping files and assigning models');
         }
 
-        // Step 5: Run analysis using shared engine
+        // Step 6: Run analysis using shared engine
         const result = await runAnalysis(filesData, config, {
             hook: 'pre-commit',
             saveDebug: config.system.debug
         });
 
-        // Step 6: Display results using shared function
+        // Step 7: Display results using shared function
         displayResults(result);
 
-        // Step 6.5: Judge — auto-fix all issues
+        // Step 8: Merge unfixable lint issues into analysis result for the judge
+        if (unfixableLintDetails.length > 0) {
+            if (!Array.isArray(result.details)) {
+                result.details = [];
+            }
+            result.details.push(...unfixableLintDetails);
+
+            // Update issue counts
+            for (const detail of unfixableLintDetails) {
+                const sev = (detail.severity || 'minor').toLowerCase();
+                if (result.issues[sev] !== undefined) {
+                    result.issues[sev]++;
+                }
+            }
+
+            logger.info(`📋 ${unfixableLintDetails.length} unfixable lint issue(s) forwarded to judge`);
+        }
+
+        // Step 9: Judge — auto-fix all issues (Claude + lint)
         if (config.judge?.enabled !== false && hasAnyIssues(result)) {
+            let judgeModule;
             try {
-                const { judgeAndFix } = await import('../utils/judge.js');
-                const judgeResult = await judgeAndFix(result, filesData, config);
+                judgeModule = await import('../utils/judge.js');
+            } catch (importErr) {
+                logger.warning(`Judge module import failed: ${importErr.message}`);
+                logger.warning('Commit blocked — judge module unavailable');
+                result.QUALITY_GATE = 'FAILED';
+                result.approved = false;
+                judgeModule = null;
+            }
 
-                // Update result with remaining issues (fixed + false positives removed)
-                result.blockingIssues = judgeResult.remainingIssues.filter((i) =>
-                    ['blocker', 'critical'].includes((i.severity || '').toLowerCase())
-                );
-                result.details = judgeResult.remainingIssues;
-
-                // Recalculate quality gate — pass only if ALL issues resolved
-                if (judgeResult.remainingIssues.length === 0) {
-                    result.issues = {
-                        blocker: 0,
-                        critical: 0,
-                        major: 0,
-                        minor: 0,
-                        info: 0
-                    };
-                    result.QUALITY_GATE = 'PASSED';
-                    result.approved = true;
-                } else {
+            if (judgeModule) {
+                try {
+                    const { judgeAndFix } = judgeModule;
+                    const judgeResult = await judgeAndFix(result, filesData, config);
+
+                    // Update result with remaining issues (fixed + false positives removed)
+                    result.blockingIssues = judgeResult.remainingIssues.filter((i) =>
+                        ['blocker', 'critical'].includes((i.severity || '').toLowerCase())
+                    );
+                    result.details = judgeResult.remainingIssues;
+
+                    // Recalculate quality gate — pass only if ALL issues resolved
+                    if (judgeResult.remainingIssues.length === 0) {
+                        result.issues = {
+                            blocker: 0,
+                            critical: 0,
+                            major: 0,
+                            minor: 0,
+                            info: 0
+                        };
+                        result.QUALITY_GATE = 'PASSED';
+                        result.approved = true;
+                    } else {
+                        result.QUALITY_GATE = 'FAILED';
+                        result.approved = false;
+                    }
+                } catch (err) {
+                    logger.warning(`Judge execution failed: ${err.message}`);
+                    logger.warning('Commit blocked — judge could not verify issues');
                     result.QUALITY_GATE = 'FAILED';
                     result.approved = false;
                 }
-            } catch (err) {
-                logger.warning(`Judge failed: ${err.message}`);
-                logger.warning('Commit blocked — judge could not verify issues');
-                result.QUALITY_GATE = 'FAILED';
-                result.approved = false;
             }
         }
 
-        // Step 7: Check quality gate
+        // Step 10: Check quality gate
         const qualityGatePassed = result.QUALITY_GATE === 'PASSED';
         const approved = result.approved !== false;
 

package/lib/utils/judge.js

@@ -182,17 +182,19 @@ const judgeAndFix = async (analysisResult, filesData, config) => {
     const resolvedIndices = new Set();
     const verdicts = [];
 
-    for (let i = 0; i < fixes.length; i++) {
+    // Cap at allIssues.length — LLM may hallucinate extra fixes beyond the input count
+    const fixCount = Math.min(fixes.length, allIssues.length);
+
+    if (fixes.length > allIssues.length) {
+        logger.debug('judge', `LLM returned ${fixes.length} fixes for ${allIssues.length} issues — ignoring ${fixes.length - allIssues.length} extra entries`);
+    }
+
+    for (let i = 0; i < fixCount; i++) {
         const verdict = fixes[i];
         const num = i + 1;
-        // Find matching issue by index or use verdict data if index exceeds allIssues length
-        const matchedIssue = i < allIssues.length ? allIssues[i] : null;
-        const severity = matchedIssue
-            ? (matchedIssue.severity || 'unknown').toUpperCase()
-            : 'UNKNOWN';
-        const desc = matchedIssue
-            ? matchedIssue.description || matchedIssue.message || 'No description'
-            : verdict.explanation || 'Unknown issue';
+        const matchedIssue = allIssues[i];
+        const severity = (matchedIssue.severity || 'unknown').toUpperCase();
+        const desc = matchedIssue.description || matchedIssue.message || 'No description';
 
         if (verdict.assessment === 'FALSE_POSITIVE') {
             falsePositiveCount++;