claude-git-hooks 2.33.0 → 2.34.0

package/CHANGELOG.md

@@ -5,6 +5,38 @@ 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
+- Improved WSL Claude CLI detection to resolve Claude's path via login shell when installed via nvm or user-scoped npm prefix
+- Added support for detecting Claude CLI in non-default WSL distros when the default distro is docker-desktop or similar
+- Switched to execFileSync for WSL distro listing to avoid cmd.exe quote mangling issues
+- Updated README-NPM with release workflow commands documentation and WSL troubleshooting guide
+
+### 🐛 Fixed
+- Fixed Claude CLI not being detected on Windows when running from Git Bash with Claude installed inside WSL via nvm (#120)
+- Fixed WSL distro detection failing due to UTF-16LE encoding from wsl.exe output
+
+
 ## [2.33.0] - 2026-03-20
 
 ### ✨ Added

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/helpers.js

@@ -18,6 +18,7 @@ import os from 'os';
 import https from 'https';
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
+import { getRunningWSLDistros } from '../utils/claude-client.js';
 
 // Why: ES6 modules don't have __dirname, need to recreate it
 const __filename = fileURLToPath(import.meta.url);
@@ -130,9 +131,46 @@ export function isWindows() {
     return os.platform() === 'win32' || process.env.OS === 'Windows_NT';
 }
 
+/**
+ * Resolve Claude's absolute path inside WSL via login shell
+ * Why: If Claude is installed via nvm or user-scoped npm prefix in WSL,
+ * it's only in PATH when .bashrc/.profile is sourced (login/interactive shell).
+ * A bare `wsl claude` runs a non-interactive shell that skips profile loading.
+ *
+ * @param {string|null} distro - WSL distro name (null = default distro)
+ * @returns {string|null} Absolute Linux path to claude binary, or null
+ */
+export function resolveClaudePathInWSL(distro = null) {
+    const distroFlag = distro ? `-d "${distro}" ` : '';
+    try {
+        const resolvedPath = execSync(`wsl ${distroFlag}bash -lc "which claude"`, {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'ignore'],
+            timeout: 10000
+        }).trim();
+
+        if (resolvedPath && resolvedPath.startsWith('/')) {
+            // Verify the resolved path actually works
+            execSync(`wsl ${distroFlag}${resolvedPath} --version`, {
+                stdio: 'ignore',
+                timeout: 10000
+            });
+            return resolvedPath;
+        }
+        return null;
+    } catch (e) {
+        return null;
+    }
+}
+
 /**
  * Get Claude command based on platform
  * Why: On Windows, try native Claude first, then WSL as fallback
+ * Strategy:
+ *   1. Native Windows `claude` (installed via npm/scoop/choco on Windows)
+ *   2. Direct `wsl claude` (Claude in WSL default PATH)
+ *   3. WSL login-shell resolution (Claude installed via nvm or custom PATH in WSL)
+ *   4. Non-default distro scan (default may be docker-desktop, not Ubuntu)
  * @returns {string}
  */
 export function getClaudeCommand() {
@@ -142,8 +180,37 @@ export function getClaudeCommand() {
             execSync('claude --version', { stdio: 'ignore', timeout: 3000 });
             return 'claude';
         } catch (e) {
-            // Fallback to WSL
-            return 'wsl claude';
+            // Try direct WSL (Claude in default non-interactive PATH)
+            try {
+                execSync('wsl claude --version', { stdio: 'ignore', timeout: 10000 });
+                return 'wsl claude';
+            } catch (e2) {
+                // Try WSL with login shell (Claude installed via nvm or custom PATH)
+                const resolvedPath = resolveClaudePathInWSL();
+                if (resolvedPath) {
+                    return `wsl ${resolvedPath}`;
+                }
+
+                // Strategy 4: Non-default WSL distro (e.g., default is docker-desktop)
+                const distros = getRunningWSLDistros('wsl');
+                for (const distro of distros) {
+                    try {
+                        execSync(`wsl -d "${distro}" claude --version`, {
+                            stdio: 'ignore',
+                            timeout: 10000
+                        });
+                        return `wsl -d "${distro}" claude`;
+                    } catch (distroError) {
+                        const resolved = resolveClaudePathInWSL(distro);
+                        if (resolved) {
+                            return `wsl -d "${distro}" ${resolved}`;
+                        }
+                    }
+                }
+
+                // All attempts failed — return best-effort fallback
+                return 'wsl claude';
+            }
         }
     }
     return 'claude';

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
     }
 };