claude-git-hooks 2.18.1 → 2.20.0

package/CHANGELOG.md

@@ -5,6 +5,58 @@ 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.20.0] - 2026-03-09
+
+### ✨ Added
+- Intelligent batch orchestration for commits with 3+ files using Opus to semantically group files, assign per-batch models, and inject shared commit context
+- Auto-fix judge that evaluates all issues at any severity level, auto-applies search/replace fixes, and dismisses false positives - any unresolved issue blocks the commit (#85)
+- New `batch-info` command to display orchestration configuration and per-model average analysis speed from telemetry
+- Per-call model override capability in `analyzeCode()` for different Claude models per analysis batch
+- New `diff-analysis-orchestrator.js` module for semantic batch grouping via Opus
+- New `judge.js` module for LLM verdict and search/replace auto-fixes
+- Cross-file dependency detection for JavaScript, TypeScript, Java, and Python files
+- DIFF_ANALYSIS_ORCHESTRATION_PROMPT.md template for Opus batch grouping
+
+### 🔧 Changed
+- Analysis routing now uses three-tier strategy: 1-2 files use sequential single call, 3+ files trigger intelligent orchestration
+- Judge now runs on all issues regardless of severity (previously only CRITICAL/BLOCKER blocked commits)
+- Resolution prompt file is only generated if issues remain after judge evaluation
+- Updated documentation to clarify that judge blocks commits when any issue remains unresolved
+- Orchestrator threshold set to 3 files as internal constant in `analysis-engine.js`
+- Each batch prompt now includes commit overview, dependency graph, and batch rationale for better cross-file reasoning
+- Judge failures (timeout, JSON parse error, module load) now warn user and block commit
+- Configurable judge model via `config.judge.model` (default: opus)
+- Judge can be disabled via `config.judge.enabled: false` to fall back to original quality gate
+
+### 🗑️ Removed
+- Removed `subagents.batchSize` configuration option (orchestration now handled by Opus intelligence)
+- Removed `analyzeCodeParallel()` function from `claude-client.js` (replaced by orchestration-driven parallel execution)
+
+
+## [2.19.0] - 2026-03-06
+
+### ✨ Added
+- Shell autocompletion for all CLI commands, flags, and arguments — Bash, Zsh, Fish, and PowerShell (#78)
+- Command registry (`lib/cli-metadata.js`) — single source of truth for commands, flags, descriptions, and completion metadata
+- Four shell completion generators with per-command flag/arg awareness and dynamic branch completion for `analyze-diff` and `create-pr`
+- Completions auto-install during `claude-hooks install` and auto-remove during `claude-hooks uninstall`
+- Self-healing RC file updates — reinstall detects and replaces stale source lines (e.g., Windows backslash paths) automatically
+
+### 🔧 Changed
+- Refactored `bin/claude-hooks` — replaced 130-line switch/case with declarative command registry lookup via `buildCommandMap()`
+- Shell source lines now use `$HOME`-relative paths for cross-platform compatibility (MINGW64, WSL, native Linux/macOS)
+- Completion source lines written to both `~/.bashrc` and `~/.bash_profile` (MINGW64 reads `.bash_profile` first)
+- PowerShell profile detection now queries `$PROFILE` directly via `powershell.exe`/`pwsh`, handling OneDrive-redirected and locale-specific Documents folders
+- PowerShell completion script uses fully qualified .NET type names (`System.Management.Automation.CompletionResult`) for compatibility with dot-sourced scripts
+- Updated CLAUDE.md with cli-metadata.js documentation, exports table, and Command Registry design pattern
+
+### 🐛 Fixed
+- Bash completions failing on MINGW64/Git Bash due to Windows backslash paths in source lines
+- PowerShell completions failing due to hardcoded Unix profile paths on Windows
+- PowerShell 5.1 `-Native` completers not firing for npm `.ps1` shims — added proxy function wrapper that re-exposes the command as `Function` type
+- PowerShell `[CompletionResult]` type accelerator not resolving in dot-sourced profile scripts
+
+
 ## [2.18.1] - 2026-03-04
 
 ### ✨ Added

package/CLAUDE.md

@@ -45,8 +45,9 @@ This separation enables:
 ```
 claude-git-hooks/
 ├── bin/
-│   └── claude-hooks                  # Thin CLI router - argument parsing, command dispatch
+│   └── claude-hooks                  # Thin CLI router - uses cli-metadata.js registry for dispatch
 ├── lib/
+│   ├── cli-metadata.js               # Command registry - single source of truth for CLI commands, flags, descriptions
 │   ├── config.js                     # Config system - load/merge with priority
 │   ├── commands/                     # Command modules - one file per CLI command
 │   │   ├── helpers.js                # Shared CLI utilities - colors, output, platform
@@ -62,13 +63,15 @@ claude-git-hooks/
 │   │   ├── telemetry-cmd.js          # Telemetry commands - show/clear statistics
 │   │   ├── 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)
 │   │   └── 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
-│       ├── analysis-engine.js        # Shared analysis logic - file data, orchestration, results (v2.13.0)
-│       ├── claude-client.js          # Claude CLI wrapper - spawn, retry, parallel
+│       ├── 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
 │       ├── prompt-builder.js         # Prompt construction - load templates, replace vars
 │       ├── git-operations.js         # Git abstractions - staged files, diff, repo root, push, commit
 │       ├── file-utils.js             # File operations - repo-relative paths
@@ -79,6 +82,7 @@ claude-git-hooks/
 │       ├── github-client.js          # GitHub helpers - CODEOWNERS parsing, reviewers
 │       ├── task-id.js                # Task ID extraction - Jira, GitHub, Linear patterns
 │       ├── interactive-ui.js         # CLI UI components - previews, prompts, spinners
+│       ├── judge.js                  # Auto-fix judge - LLM verdict + search/replace fixes (v2.20.0)
 │       ├── resolution-prompt.js      # Issue resolution - AI-friendly fix prompts
 │       ├── installation-diagnostics.js # Installation diagnostics - error context
 │       ├── claude-diagnostics.js     # Claude errors - rate limit, auth, formatting
@@ -94,9 +98,10 @@ claude-git-hooks/
 │   ├── check-version.sh              # Version check - auto-update prompt
 │   ├── CLAUDE_PRE_COMMIT.md          # Analysis criteria - evaluation guidelines
 │   ├── CLAUDE_ANALYSIS_PROMPT.md     # Analysis prompt - code review template
-│   ├── CLAUDE_RESOLUTION_PROMPT.md   # Resolution prompt - issue fix template
+│   ├── CLAUDE_RESOLUTION_PROMPT.md   # Resolution prompt - structured JSON output for judge + manual use
 │   ├── ANALYZE_DIFF.md               # PR analysis - diff review template
 │   ├── GENERATE_CHANGELOG.md         # CHANGELOG generation - commit analysis template (v2.12.0)
+│   ├── DIFF_ANALYSIS_ORCHESTRATION_PROMPT.md  # Orchestration prompt - Opus batch grouping (v2.20.0)
 │   ├── HELP_QUERY.md                 # AI help - question answering with NEED_MORE_CONTEXT protocol (v2.18.0)
 │   ├── HELP_REPORT_ISSUE.md          # Report issue - question generation from templates (v2.18.0)
 │   ├── HELP_COMPOSE_ISSUE.md         # Report issue - issue body composition from answers (v2.18.0)
@@ -125,8 +130,9 @@ lib/utils/git-operations.js → getStagedFiles()
 lib/utils/file-operations.js → filterFiles()
   ↓ (builds file data + runs analysis)
 lib/utils/analysis-engine.js → buildFilesData(), runAnalysis()
-  ↓ (orchestrates parallel/sequential Claude CLI calls)
-lib/utils/claude-client.js → analyzeCode() or analyzeCodeParallel()
+  ↓ (2-tier routing: 1-2 files→sequential, 3+→Opus orchestration)
+lib/utils/diff-analysis-orchestrator.js → orchestrateBatches() [if N ≥ 3]
+lib/utils/claude-client.js → analyzeCode(prompt, { model }) per batch [parallel]
   ↓ (displays results)
 lib/utils/analysis-engine.js → displayResults()
   ↓ (if blocking issues found)
@@ -164,23 +170,34 @@ preset config (.claude/presets/{name}/config.json)  ← HIGHEST PRIORITY
                 "verifyRemote": true // Verify remote exists (v2.11.0)
             }
         },
-        "subagents": { "batchSize": 2 }
     }
 }
 ```
 
-**Hardcoded defaults (v2.8.0):**
+**Hardcoded defaults (v2.8.0+):**
 
-| Parameter            | Value   | Notes                        |
-| -------------------- | ------- | ---------------------------- |
-| Max file size        | 1MB     | Files larger are skipped     |
-| Max files per commit | 20      | Excess files trigger warning |
-| Parallel analysis    | enabled | Always on for 3+ files       |
-| Parallel model       | haiku   | Fast, cost-effective         |
-| Parallel batch size  | 3       | Files per Claude process     |
-| Analysis timeout     | 300s    | Per-batch timeout            |
-| Commit msg timeout   | 300s    | Message generation timeout   |
-| PR metadata timeout  | 180s    | Engine default (reads config)|
+| Parameter               | Value   | Notes                                              |
+| ----------------------- | ------- | -------------------------------------------------- |
+| Max file size           | 1MB     | Files larger are skipped                           |
+| Max files per commit    | 30      | Excess files trigger warning                       |
+| Orchestrator threshold  | 3 files | Commits with ≥3 files use Opus orchestration       |
+| Orchestrator model      | opus    | Internal constant — not user-configurable          |
+| Orchestrator timeout    | 60s     | Lightweight call (file overview only)              |
+| Analysis timeout        | 300s    | Per-batch timeout                                  |
+| Commit msg timeout      | 300s    | Message generation timeout                         |
+| PR metadata timeout     | 180s    | Engine default (reads config)                      |
+| Judge model             | opus    | Default, configurable via `config.judge.model`     |
+| Judge timeout           | 120s    | Per-judge call timeout                             |
+
+**Judge behavior (v2.20.0):**
+
+- Enabled by default (`config.judge?.enabled !== false`)
+- Runs on **all issues** (any severity), not just blockers
+- **Any unresolved issue blocks the commit** — no issue passes without judge approval
+- Judge failure (timeout, JSON parse error, module load) → user warned → commit blocked
+- No retries — failed fixes stay as unresolved issues
+- When disabled (`config.judge.enabled: false`), falls back to original quality gate (blocks on CRITICAL/BLOCKER only)
+- Resolution prompt file is only generated if issues remain after the judge
 
 **3. Presets System**
 
@@ -193,21 +210,36 @@ preset config (.claude/presets/{name}/config.json)  ← HIGHEST PRIORITY
 | `ai`        | `.js`, `.json`, `.md`, `.sh`                                               | Node.js + Claude API     | Prompts, API key security, cross-platform           |
 | `default`   | `.js`, `.sh`, `.py`, `.rb`, `.pl`, `.sql`, `.yaml`, `.json`, `.xml`, `.md` | Multiple                 | Quality and security fundamentals                   |
 
-**4. Parallel Analysis (v2.2.0+)**
+**4. Analysis Routing (v2.20.0)**
+
+Three-tier strategy based on file count:
 
-When 3+ files are present, the system divides into batches and executes multiple `claude` CLI processes in parallel:
+| Files | Strategy |
+|-------|----------|
+| 1–2   | Sequential — single Claude call |
+| **3+** | **Intelligent orchestration** — Opus orchestrator, semantic grouping, per-batch model, shared context |
+
+**Orchestration flow (3+ files):**
 
 ```
-4 files + batchSize=2
+staged files (N ≥ 3)
+  ↓
+[ORCHESTRATOR — Opus, 60s timeout]
+  Input: file overview table + detected cross-file deps (JS/TS/Java/Python regex)
+  Output: { batches: [{ filePaths, rationale, model }] }
   ↓
-Batch 1: [file1, file2] → claude CLI process #1 (parallel)
-Batch 2: [file3, file4] → claude CLI process #2 (parallel)
+For each batch:
+  → buildAnalysisPrompt(batchFiles + commonContext + batchRationale)
+  → analyzeCode(prompt, { model: batch.model })     ← per-batch model
+  [all batches run in parallel via Promise.all]
   ↓
-Wait for both → consolidate results
+consolidateResults()
 ```
 
-- **Configuration**: `.claude/config.json` → `subagents.batchSize`, `subagents.model` (haiku/sonnet/opus)
-- **Speed-up**: ~4x faster with batch=1 (1 file per process)
+- **Orchestration model**: `opus` — hardcoded internal constant, not user-configurable
+- **Threshold**: `ORCHESTRATOR_THRESHOLD = 3` — internal constant in `analysis-engine.js`
+- **Fallback**: any orchestration failure → one-file-per-batch with haiku
+- **Common context**: each batch prompt prefixed with commit overview, dep graph, and batch rationale
 
 ### Key Module Exports
 
@@ -229,16 +261,19 @@ Wait for both → consolidate results
 | `migrate-config.js`     | Config migration          | `runMigrateConfig()`                                                          |
 | `debug.js`              | Debug toggle              | `runSetDebug()`                                                               |
 | `telemetry-cmd.js`      | Telemetry commands        | `runShowTelemetry()`, `runClearTelemetry()`                                   |
+| `diff-batch-info.js`    | Batch info display        | `runDiffBatchInfo()`                                                          |
 | `help.js`               | Help, AI help, report-issue | `runShowHelp()`, `showStaticHelp()`, `runShowVersion()`                     |
 
 **Utility Modules (`lib/utils/`):**
 
 | Module                   | Purpose               | Key Exports                                                                                                                                                                    |
 | ------------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `lib/cli-metadata.js`    | Command registry      | `commands`, `buildCommandMap()`, `generateCompletionData()`, `PRESET_NAMES`, `HOOK_NAMES`, `BUMP_TYPES`                                                                        |
 | `lib/config.js`          | Config system         | `getConfig()`                                                                                                                                                                  |
-| `analysis-engine.js`     | Shared analysis logic | `buildFileData()`, `buildFilesData()`, `runAnalysis()`, `consolidateResults()`, `hasBlockingIssues()`, `hasAnyIssues()`, `displayResults()`, `displayIssueSummary()` (v2.13.0) |
-| `claude-client.js`       | Claude CLI wrapper    | `analyzeCode()`, `analyzeCodeParallel()`, `executeClaudeWithRetry()`                                                                                                           |
-| `prompt-builder.js`      | Prompt construction   | `buildAnalysisPrompt()`, `loadPrompt()`                                                                                                                                        |
+| `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 |
+| `prompt-builder.js`      | Prompt construction   | `buildAnalysisPrompt()`, `loadPrompt()` — accepts `commonContext`, `batchRationale`                                                                                            |
 | `git-operations.js`      | Git abstractions      | `getStagedFiles()`, `getUnstagedFiles()`, `getAllTrackedFiles()`, `getDiff()`, `getRepoRoot()`, `getBranchPushStatus()`, `pushBranch()`, `createCommit()`, `fetchRemote()`, `branchExists()`, `getRemoteBranches()`, `resolveBaseBranch()`, `getChangedFilesBetweenRefs()`, `getDiffBetweenRefs()`, `getCommitsBetweenRefs()` |
 | `file-utils.js`          | File operations       | `ensureDir()`, `ensureOutputDir()`, `writeOutputFile()`, `walkDirectoryTree()`                                                                                                                                                                                                                                                |
 | `pr-metadata-engine.js`  | PR metadata generation | `getBranchContext()`, `buildDiffPayload()`, `generatePRMetadata()`, `analyzeBranchForPR()` (v2.14.0) |
@@ -250,18 +285,21 @@ Wait for both → consolidate results
 | `preset-loader.js`       | Preset system         | `loadPreset()`, `listPresets()`                                                                                                                                                |
 | `task-id.js`             | Task ID extraction    | `getOrPromptTaskId()`, `formatWithTaskId()`                                                                                                                                    |
 | `logger.js`              | Logging system        | `info()`, `warning()`, `error()`, `debug()`                                                                                                                                    |
+| `judge.js`               | Auto-fix judge        | `judgeAndFix()`, `applyFix()` — LLM verdict + search/replace fixes (v2.20.0)                                                                                                  |
 | `resolution-prompt.js`   | Issue resolution      | `generateResolutionPrompt()`                                                                                                                                                   |
 | `interactive-ui.js`      | CLI UI components     | `showPRPreview()`, `promptConfirmation()`, `promptMenu()`, `promptToggleList()`, `promptEditField()`, `promptUserConfirmation()`                                                                                          |
 | `telemetry.js`           | Local telemetry       | `recordEvent()`, `displayStatistics()`                                                                                                                                         |
 
 ### Design Patterns
 
-1. **Command Pattern**: `lib/commands/*.js` - each CLI command is a self-contained module
-2. **Factory Pattern**: `preset-loader.js` loads configurations dynamically per tech-stack
-3. **Template Method**: `prompt-builder.js` builds prompts from markdown templates
-4. **Strategy Pattern**: `claude-client.js` selects between sequential or parallel analysis
-5. **Adapter Pattern**: `git-operations.js` abstracts git commands into JS functions
-6. **Singleton Pattern**: `config.js` loads configuration once per execution
+1. **Command Registry**: `lib/cli-metadata.js` - single source of truth for CLI commands, flags, and descriptions. When adding CLI commands, add an entry to `lib/cli-metadata.js` — routing, completions, and help derive from it.
+2. **Command Pattern**: `lib/commands/*.js` - each CLI command is a self-contained module
+3. **Factory Pattern**: `preset-loader.js` loads configurations dynamically per tech-stack
+4. **Template Method**: `prompt-builder.js` builds prompts from markdown templates
+5. **Strategy Pattern**: `analysis-engine.js` selects between sequential (1–2 files) or orchestrated (3+ files) analysis based on file count threshold
+6. **Orchestrator Pattern**: `diff-analysis-orchestrator.js` — Opus decides semantic grouping and model assignment; workers (analyzeCode per batch) execute in parallel
+7. **Adapter Pattern**: `git-operations.js` abstracts git commands into JS functions
+8. **Singleton Pattern**: `config.js` loads configuration once per execution
 
 ### Key Data Flows
 
@@ -272,9 +310,15 @@ git commit
   → hook reads staged files
   → filters by preset extensions
   → builds prompt with diff
-  → Claude analyzes → detects SQL injection (CRITICAL)
-  → generates resolution prompt
-  → exit 1 → COMMIT BLOCKED
+  → Claude analyzes → detects issues
+  → judge evaluates ALL issues (any severity):
+    → TRUE_ISSUE: applies search/replace fix + git add
+    → FALSE_POSITIVE: dismissed
+    → if ALL resolved: exit 0 → COMMIT PROCEEDS
+    → if ANY unresolved: generates resolution prompt → exit 1 → COMMIT BLOCKED
+    → if judge fails (timeout, parse error): user warned → exit 1 → COMMIT BLOCKED
+  → judge disabled (config.judge.enabled: false):
+    → falls back to original quality gate (blocks on CRITICAL/BLOCKER only)
 ```
 
 **Flow 1.5: Interactive analysis command (v2.13.0)**
@@ -645,6 +689,9 @@ claude-hooks generate-changelog       # Generate CHANGELOG only
 claude-hooks help "how do presets work?"  # AI-powered help (uses CLAUDE.md)
 claude-hooks help --report-issue          # Interactive issue creation
 
+# Orchestration diagnostics
+claude-hooks batch-info               # Orchestration config + per-model speed telemetry
+
 # Debugging
 claude-hooks --debug true             # Enable debug mode
 claude-hooks --debug false            # Disable debug mode

package/README.md

@@ -218,6 +218,14 @@ claude-hooks help --report-issue          # Interactive GitHub issue creation
 claude-hooks --help                       # Static command reference
 ```
 
+### Batch Info
+
+```bash
+claude-hooks batch-info
+# Shows: orchestration model, threshold, default analysis model
+# Shows: per-model average analysis time and orchestration overhead (from telemetry)
+```
+
 ### Other Commands
 
 ```bash
@@ -262,6 +270,7 @@ claude-hooks update   # Update to latest version
 | `migrate-config.js` | **Config migration** - legacy to v2.8.0 format | `runMigrateConfig()` |
 | `debug.js` | **Debug toggle** - enable/disable verbose logging | `runSetDebug()` |
 | `telemetry-cmd.js` | **Telemetry commands** - show/clear statistics | `runShowTelemetry()`, `runClearTelemetry()` |
+| `diff-batch-info.js` | **Batch info** - orchestration config + per-model speed telemetry | `runDiffBatchInfo()` |
 | `help.js` | **Help, AI help, report-issue** | `runShowHelp()`, `showStaticHelp()`, `runShowVersion()` |
 
 ### Utility Modules (`lib/utils/`)
@@ -269,14 +278,16 @@ claude-hooks update   # Update to latest version
 | Module | Purpose | Key Exports |
 |--------|---------|-------------|
 | `analysis-engine.js` | **Shared analysis logic** - file data, orchestration, results (v2.13.0) | `buildFilesData()`, `runAnalysis()`, `consolidateResults()`, `displayResults()` |
-| `claude-client.js` | **Claude CLI wrapper** - spawn, retry, parallel execution | `analyzeCode()`, `analyzeCodeParallel()`, `executeClaudeWithRetry()` |
-| `prompt-builder.js` | **Prompt construction** - load templates, replace variables | `buildAnalysisPrompt()`, `loadPrompt()` |
+| `diff-analysis-orchestrator.js` | **Intelligent orchestration** - semantic batch grouping via Opus (v2.20.0) | `orchestrateBatches()`, `buildFileOverview()`, `detectDependencies()` |
+| `claude-client.js` | **Claude CLI wrapper** - spawn, retry, model override | `analyzeCode()`, `executeClaudeWithRetry()`, `extractJSON()` |
+| `prompt-builder.js` | **Prompt construction** - load templates, replace variables, inject commit context | `buildAnalysisPrompt()`, `loadPrompt()` |
 | `git-operations.js` | **Git abstractions** - staged files, diff, branch comparison | `getStagedFiles()`, `getDiff()`, `getRepoRoot()`, `resolveBaseBranch()`, `getDiffBetweenRefs()` |
 | `pr-metadata-engine.js` | **PR metadata generation** - branch context, diff reduction (v2.14.0) | `getBranchContext()`, `buildDiffPayload()`, `generatePRMetadata()`, `analyzeBranchForPR()` |
 | `github-api.js` | **Octokit integration** - PR creation, token validation, content fetching | `createPullRequest()`, `validateToken()`, `saveGitHubToken()`, `fetchFileContent()`, `fetchDirectoryListing()`, `createIssue()` |
 | `github-client.js` | **GitHub helpers** - CODEOWNERS parsing, reviewers | `getReviewersForFiles()`, `parseGitHubRepo()` |
 | `preset-loader.js` | **Preset system** - load tech-stack configurations | `loadPreset()`, `listPresets()` |
 | `task-id.js` | **Task ID extraction** - Jira, GitHub, Linear patterns | `getOrPromptTaskId()`, `formatWithTaskId()` |
+| `judge.js` | **Auto-fix judge** - LLM verdict + search/replace fixes (v2.20.0) | `judgeAndFix()`, `applyFix()` |
 | `resolution-prompt.js` | **Issue resolution** - AI-friendly fix prompts | `generateResolutionPrompt()` |
 | `logger.js` | **Logging system** - centralized output with debug mode | `info()`, `warning()`, `error()`, `debug()` |
 | `interactive-ui.js` | **CLI UI components** - previews, prompts, spinners | `showPRPreview()`, `promptConfirmation()`, `promptMenu()` |
@@ -292,9 +303,13 @@ git commit → templates/pre-commit (bash wrapper)
   → getStagedFiles() → filterFiles() by preset extensions + size
   → buildFilesData() → runAnalysis() (via analysis-engine.js)
   → displayResults() → show quality gate status
-  → if blocking issues (critical/blocker):
-      generates claude_resolution_prompt.md → exit 1 (block)
-  → if non-blocking or no issues: exit 0 (pass)
+  → judge evaluates ALL issues (any severity):
+    → TRUE_ISSUE: auto-fix via search/replace + git add
+    → FALSE_POSITIVE: dismissed
+    → ALL resolved: exit 0 (pass)
+    → ANY unresolved: generates resolution prompt → exit 1 (block)
+    → judge failure: user warned → exit 1 (block)
+  → judge disabled: original quality gate (blocks on critical/blocker only)
 ```
 
 **Note:** For interactive review of non-blocking issues, use `claude-hooks analyze` before committing.
@@ -350,7 +365,6 @@ Preset always wins - tech-stack specific has priority over user preferences.
         "verifyRemote": true     // Verify remote exists (v2.11.0)
       }
     },
-    "subagents": { "batchSize": 2 }
   }
 }
 ```
@@ -359,7 +373,7 @@ Preset always wins - tech-stack specific has priority over user preferences.
 
 - **Factory**: `preset-loader.js` - dynamic config per tech-stack
 - **Template Method**: `prompt-builder.js` - prompts from .md templates
-- **Strategy**: `claude-client.js` - sequential vs parallel analysis
+- **Strategy**: `analysis-engine.js` - sequential vs orchestrated analysis
 - **Adapter**: `git-operations.js` - git commands to JS functions
 - **Command**: `lib/commands/*.js` - one module per CLI command
 
@@ -377,6 +391,9 @@ Preset always wins - tech-stack specific has priority over user preferences.
 | Config defaults | `lib/config.js` |
 | GitHub integration | `lib/utils/github-api.js` |
 | Claude CLI calls | `lib/utils/claude-client.js` |
+| Batch orchestration logic | `lib/utils/diff-analysis-orchestrator.js` |
+| Orchestration prompt | `templates/DIFF_ANALYSIS_ORCHESTRATION_PROMPT.md` |
+| Auto-fix judge logic | `lib/utils/judge.js` |
 
 ### File Structure
 
@@ -397,33 +414,50 @@ claude-git-hooks/
 │   │   ├── migrate-config.js     # Migration - legacy to v2.8.0
 │   │   ├── debug.js              # Debug mode - toggle verbose
 │   │   ├── telemetry-cmd.js      # Telemetry - show/clear stats
+│   │   ├── diff-batch-info.js    # Batch info - orchestration config
 │   │   └── help.js               # Help display - usage info
 │   ├── hooks/                    # Git hooks - Node.js logic
 │   │   ├── pre-commit.js         # Pre-commit analysis
 │   │   └── prepare-commit-msg.js # Message generation
 │   └── utils/                    # Reusable modules - shared logic
+│       ├── diff-analysis-orchestrator.js  # Intelligent batch orchestration
+│       └── judge.js                      # Auto-fix judge (v2.20.0)
 ├── templates/
 │   ├── pre-commit                # Bash wrapper - invokes Node.js
 │   ├── prepare-commit-msg        # Bash wrapper - invokes Node.js
-│   ├── *.md                      # Prompt templates
+│   ├── DIFF_ANALYSIS_ORCHESTRATION_PROMPT.md  # Opus orchestration prompt
+│   ├── *.md                      # Other prompt templates
 │   └── presets/                  # Preset configurations
 └── test/unit/                    # Jest tests
 ```
 
-### Parallel Analysis (3+ files)
+### Analysis Routing (v2.20.0)
+
+Two-tier strategy based on file count:
 
-Files split into batches, each batch runs in separate Claude CLI process:
-- `batchSize: 1` → Maximum parallelism (1 file per process)
-- `batchSize: 2` → Balanced (2 files per process)
-- Results consolidated automatically
+| Files | Strategy | Details |
+|-------|----------|---------|
+| 1–2 | Sequential | Single Claude call, full context |
+| 3+ | **Intelligent orchestration** | Opus groups files semantically, assigns model per batch, shared commit context |
+
+**Orchestration flow (3+ files):**
+1. Opus reads a lightweight file overview + detected cross-file dependencies
+2. Groups related files into semantically coherent batches
+3. Assigns model per batch: `haiku` (config/docs), `sonnet` (business logic), `opus` (security-critical)
+4. All batches run in parallel; each receives a shared commit overview header
+5. Falls back to one-file-per-batch if orchestration fails
+
+**Inspect orchestration settings:**
+```bash
+claude-hooks batch-info   # Shows config + per-model avg speed from telemetry
+```
 
-### Hardcoded Defaults (v2.8.0)
+### Hardcoded Defaults (v2.8.0+)
 
 - Max file size: 1MB
-- Max files per commit: 20
-- Parallel analysis: enabled
-- Parallel model: haiku
-- Parallel batch size: 3
+- Max files per commit: 30
+- Orchestrator threshold: 3 files
+- Orchestrator model: opus (internal, not configurable)
 
 ---
 

package/bin/claude-hooks

@@ -4,27 +4,12 @@
  * File: claude-hooks
  * Purpose: Main CLI entry point - thin router to command modules
  *
+ * Routes commands via cli-metadata.js registry.
  * All command implementations are in lib/commands/
- * This file only handles argument parsing and routing.
  */
 
 import { error } from '../lib/commands/helpers.js';
-
-// Import commands
-import { runInstall } from '../lib/commands/install.js';
-import { runEnable, runDisable, runStatus, runUninstall } from '../lib/commands/hooks.js';
-import { runAnalyze } from '../lib/commands/analyze.js';
-import { runAnalyzeDiff } from '../lib/commands/analyze-diff.js';
-import { runCreatePr } from '../lib/commands/create-pr.js';
-import { runSetupGitHub } from '../lib/commands/setup-github.js';
-import { runShowPresets, runSetPreset, runCurrentPreset } from '../lib/commands/presets.js';
-import { runUpdate } from '../lib/commands/update.js';
-import { runMigrateConfig } from '../lib/commands/migrate-config.js';
-import { runSetDebug } from '../lib/commands/debug.js';
-import { runShowTelemetry, runClearTelemetry } from '../lib/commands/telemetry-cmd.js';
-import { runShowHelp, runShowVersion } from '../lib/commands/help.js';
-import { runBumpVersion } from '../lib/commands/bump-version.js';
-import { runGenerateChangelog } from '../lib/commands/generate-changelog.js';
+import { buildCommandMap } from '../lib/cli-metadata.js';
 
 /**
  * Main CLI router
@@ -33,97 +18,98 @@ async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
 
-    switch (command) {
-    case 'install':
-        await runInstall(args.slice(1));
-        break;
-    case 'update':
-        await runUpdate();
-        break;
-    case 'uninstall':
-        runUninstall();
-        break;
-    case 'enable':
-        runEnable(args[1]);
-        break;
-    case 'disable':
-        runDisable(args[1]);
-        break;
-    case 'status':
-        runStatus();
-        break;
-    case 'analyze':
-        await runAnalyze({
+    const commandMap = buildCommandMap();
+    const entry = commandMap.get(command);
+
+    // help / --help / -h / no command
+    if (command === undefined || command === '--help' || command === '-h') {
+        const { runShowHelp } = await import('../lib/commands/help.js');
+        await runShowHelp();
+        return;
+    }
+
+    if (!entry) {
+        error(`Unknown command: ${command}`);
+        const { runShowHelp } = await import('../lib/commands/help.js');
+        runShowHelp();
+        return;
+    }
+
+    // --- Commands with special argument handling ---
+
+    // analyze: translate flags to options object
+    if (entry.name === 'analyze') {
+        const handler = await entry.handler();
+        await handler({
             staged: !args.includes('--unstaged') && !args.includes('--all'),
             unstaged: args.includes('--unstaged'),
             all: args.includes('--all')
         });
-        break;
-    case 'analyze-diff':
-        await runAnalyzeDiff(args.slice(1));
-        break;
-    case 'create-pr':
-        await runCreatePr(args.slice(1));
-        break;
-    case 'setup-github':
-        await runSetupGitHub();
-        break;
-    case 'presets':
-        await runShowPresets();
-        break;
-    case '--set-preset':
-        await runSetPreset(args[1]);
-        break;
-    case 'preset':
-        // Handle subcommands: preset current
+        return;
+    }
+
+    // preset: subcommand routing
+    if (entry.name === 'preset') {
         if (args[1] === 'current') {
+            const { runCurrentPreset } = await import('../lib/commands/presets.js');
             await runCurrentPreset();
         } else {
             error(`Unknown preset subcommand: ${args[1]}`);
         }
-        break;
-    case 'migrate-config':
-        await runMigrateConfig();
-        break;
-    case 'bump-version':
-        await runBumpVersion(args.slice(1));
-        break;
-    case 'generate-changelog':
-        await runGenerateChangelog(args.slice(1));
-        break;
-    case 'telemetry':
-        // Handle subcommands: telemetry show, telemetry clear
+        return;
+    }
+
+    // telemetry: subcommand routing
+    if (entry.name === 'telemetry') {
         if (args[1] === 'show' || args[1] === undefined) {
+            const { runShowTelemetry } = await import('../lib/commands/telemetry-cmd.js');
             await runShowTelemetry();
         } else if (args[1] === 'clear') {
+            const { runClearTelemetry } = await import('../lib/commands/telemetry-cmd.js');
             await runClearTelemetry();
         } else {
             error(`Unknown telemetry subcommand: ${args[1]}`);
         }
-        break;
-    case '--debug':
-        await runSetDebug(args[1]);
-        break;
-    case '--version':
-    case '-v':
-    case 'version':
-        runShowVersion();
-        break;
-    case 'help':
-        await runShowHelp(args.slice(1));
-        break;
-    case '--help':
-    case '-h':
-    case undefined:
-        runShowHelp();
-        break;
-    default:
-        error(`Unknown command: ${command}`);
-        runShowHelp();
+        return;
+    }
+
+    // --- Commands that take args[1] as single argument ---
+    // enable/disable take optional hook name
+    if (entry.name === 'enable' || entry.name === 'disable') {
+        const handler = await entry.handler();
+        handler(args[1]);
+        return;
     }
+
+    // --set-preset takes preset name, --debug takes value
+    if (entry.name === '--set-preset' || entry.name === '--debug') {
+        const handler = await entry.handler();
+        await handler(args[1]);
+        return;
+    }
+
+    // --- Commands that take args.slice(1) ---
+    if (
+        [
+            'install',
+            'analyze-diff',
+            'create-pr',
+            'bump-version',
+            'generate-changelog',
+            'help'
+        ].includes(entry.name)
+    ) {
+        const handler = await entry.handler();
+        await handler(args.slice(1));
+        return;
+    }
+
+    // --- Commands with no arguments ---
+    const handler = await entry.handler();
+    await handler();
 }
 
 // Execute main
-main().catch(err => {
+main().catch((err) => {
     error(`Unexpected error: ${err.message}`);
 });