claude-git-hooks 2.33.1 → 2.35.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ 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.35.0] - 2026-03-27
+
+### ✨ Added
+- Prettier formatting support — auto-formats JS/TS/CSS/HTML/JSON/YAML/MD files before linting (format first, then lint)
+- Remote formatter configuration — preset-to-tools mapping fetched from centralized git-hooks-config repo, allowing team-wide control without releasing new versions
+- New `parsePrettierOutput()` function for parsing Prettier --check output into structured issues
+
+### 🔧 Changed
+- Linting pipeline now runs formatters (Prettier) before linters (ESLint) for consistent code style
+- Updated preset-to-tools mapping: frontend, fullstack, ai, and default presets now include Prettier
+- `getLinterToolsForPreset()` now fetches remote config with local fallback instead of using hardcoded mapping only
+- `runLinters()` and `checkLinterAvailability()` converted to async functions to support remote config fetching
+- Unfixable linting issues are now forwarded to the Claude judge for semantic resolution instead of blocking directly
+
+
+## [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 formatters and linters (Prettier, 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 formatters and linters on staged files, directories, or specific files — supports Prettier, ESLint, Spotless, sqlfluff per preset (remote config priority with local fallback)
+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, Prettier/ESLint/Spotless/sqlfluff, remote config (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
@@ -178,6 +183,7 @@ preset config (.claude/presets/{name}/config.json)  ← HIGHEST PRIORITY
 **Team-wide remote config** ([`mscope-S-L/git-hooks-config`](https://github.com/mscope-S-L/git-hooks-config)):
 
 - `labels.json` — PR label rules (fetched by `remote-config.js`, consumed by `label-resolver.js`)
+- `formatters.json` — preset-to-tools mapping for linting/formatting (fetched by `remote-config.js`, consumed by `linter-runner.js`)
 - `permissions.json` — role-based authorization (fetched directly by `authorization.js`, fail-closed)
 - Changes take effect immediately across all governed repos — no tool update needed
 
@@ -218,6 +224,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 +310,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 +319,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`, `parsePrettierOutput()`, `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                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
@@ -346,16 +360,38 @@ consolidateResults()
 7. **Adapter Pattern**: `git-operations.js` abstracts git commands into JS functions
 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
+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` and `linter-runner.js` — callers fetch remote config and decide fallback (`labels.json` for PR labels, `formatters.json` for preset-to-tools mapping)
+11. **Pipeline Pattern**: `tool-runner.js` + `linter-runner.js` — generic tool execution infrastructure; formatters (Prettier) and linters (ESLint, Spotless, sqlfluff) share the same resolve → spawn → parse → fix → re-stage pipeline. Tool definitions are data objects, not classes. Preset-to-tools mapping fetched from `mscope-S-L/git-hooks-config/formatters.json` (remote config priority, local fallback).
 
 ### 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):
+        1. fetchRemoteConfig('formatters.json') → remote presetTools mapping
+        2. fallback to local PRESET_LINTERS if remote unavailable
+    → for each tool (formatters first, then linters):
+        isToolAvailable() → not found? warn + install hint → skip
+        filterFilesByTool() → matching files
+        runToolWithAutoFix() → check → auto-fix → re-stage → re-check
+    → unfixable issues forwarded to judge
+  ↓
+  → 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 +1143,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/README.md

@@ -82,6 +82,43 @@ export GITHUB_TOKEN="ghp_..."
 
 Create token at https://github.com/settings/tokens with scopes: `repo`, `read:org`
 
+### Linting & Formatting
+
+Runs formatters and linters on staged files automatically during pre-commit, or on demand:
+
+```bash
+# Lint staged files (default)
+claude-hooks lint
+
+# Lint all files in a directory
+claude-hooks lint src/
+
+# Lint specific files
+claude-hooks lint file1.js file2.java
+
+# Mix of directories and files
+claude-hooks lint src/ lib/utils/ file.js
+```
+
+**Tools per preset** (configured via [remote config](https://github.com/mscope-S-L/git-hooks-config)):
+
+| Preset      | Tools                         |
+| ----------- | ----------------------------- |
+| `frontend`  | Prettier, ESLint              |
+| `backend`   | Spotless                      |
+| `fullstack` | Prettier, ESLint, Spotless    |
+| `database`  | sqlfluff                      |
+| `ai`        | Prettier, ESLint              |
+| `default`   | Prettier, ESLint              |
+
+**Behavior:**
+
+- Formatters run first (Prettier), then linters (ESLint) — format before lint
+- Auto-fix enabled by default — fixes and re-stages files automatically
+- Missing tools are skipped with install instructions (never blocks)
+- Unfixable issues are forwarded to the Claude judge for semantic resolution
+- Tool-to-preset mapping is fetched from remote config (team-controlled, no release needed)
+
 ### Analyze Code (Interactive Review)
 
 Run interactive code analysis before committing:

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');
+            await 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 = await 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
     }
 };