claude-git-hooks 2.19.0 → 2.20.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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

package/CLAUDE.md

@@ -63,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
@@ -80,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
@@ -95,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)
@@ -126,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)
@@ -165,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**
 
@@ -194,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
 
@@ -230,6 +261,7 @@ 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/`):**
@@ -238,9 +270,10 @@ Wait for both → consolidate results
 | ------------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `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) |
@@ -252,6 +285,7 @@ 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()`                                                                                                                                         |
@@ -262,9 +296,10 @@ Wait for both → consolidate results
 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**: `claude-client.js` selects between sequential or parallel analysis
-6. **Adapter Pattern**: `git-operations.js` abstracts git commands into JS functions
-7. **Singleton Pattern**: `config.js` loads configuration once per execution
+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
 
@@ -275,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)**
@@ -648,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/lib/cli-metadata.js

@@ -184,6 +184,11 @@ export const commands = [
             '--release': { description: 'Mark as released' }
         }
     },
+    {
+        name: 'batch-info',
+        description: 'Show intelligent diff-analysis orchestration configuration and speed telemetry',
+        handler: async () => (await import('./commands/diff-batch-info.js')).runDiffBatchInfo
+    },
     {
         name: 'telemetry',
         description: 'View or clear telemetry data',

package/lib/commands/diff-batch-info.js

@@ -0,0 +1,105 @@
+/**
+ * File: diff-batch-info.js
+ * Purpose: Display intelligent diff-analysis orchestration config and speed telemetry
+ *
+ * Shows:
+ * - Orchestration model and threshold
+ * - Default analysis model from config
+ * - Per-model avg analysis times from telemetry
+ * - Avg orchestration overhead
+ * - Overall failure rate
+ */
+
+import { getStatistics } from '../utils/telemetry.js';
+import logger from '../utils/logger.js';
+
+/**
+ * Runs the batch-info command
+ * Why: Surfaces orchestration configuration and speed telemetry so users can
+ * understand the adaptive batch system behavior without needing debug mode.
+ */
+export async function runDiffBatchInfo() {
+    console.log(
+        '\n╔════════════════════════════════════════════════════════════════════╗'
+    );
+    console.log(
+        '║              INTELLIGENT ANALYSIS ORCHESTRATION INFO               ║'
+    );
+    console.log(
+        '╚════════════════════════════════════════════════════════════════════╝\n'
+    );
+
+    console.log('━━━ ORCHESTRATION CONFIGURATION ━━━');
+    console.log('  Orchestration model:     opus (internal, not user-configurable)');
+    console.log('  Orchestrator threshold:  3 files (commits with ≥3 files use intelligent grouping)');
+    console.log();
+
+    console.log('━━━ HOW IT WORKS ━━━');
+    console.log('  < 3 files:  Sequential analysis (single Claude call)');
+    console.log('  ≥ 3 files:  Orchestrator groups files semantically,');
+    console.log('              assigns model per batch, injects shared context');
+    console.log();
+
+    try {
+        const stats = await getStatistics(7);
+
+        if (!stats.enabled) {
+            console.log('  Telemetry is disabled — no speed data available.');
+            console.log(
+                '  To enable, ensure "system.telemetry" is not set to false in .claude/config.json'
+            );
+            console.log();
+            return;
+        }
+
+        if (stats.totalEvents === 0) {
+            console.log('━━━ SPEED TELEMETRY (last 7 days) ━━━');
+            console.log('  No telemetry data yet.');
+            console.log(
+                '  Run an analysis with ≥3 files to start collecting per-model timing data.'
+            );
+            console.log();
+            return;
+        }
+
+        console.log('━━━ SPEED TELEMETRY (last 7 days) ━━━');
+        console.log(`  Total events:       ${stats.totalEvents}`);
+        console.log(`  Successful batches: ${stats.batchSuccesses}`);
+        console.log(`  Failure rate:       ${stats.failureRate}%`);
+        console.log();
+
+        if (Object.keys(stats.avgAnalysisTimeByModel).length > 0) {
+            console.log('  Average analysis time by model:');
+            for (const [model, ms] of Object.entries(stats.avgAnalysisTimeByModel)) {
+                const seconds = (ms / 1000).toFixed(1);
+                console.log(`    ${model.padEnd(8)}: ${seconds}s`);
+            }
+            console.log();
+        }
+
+        if (stats.avgOrchestrationTime > 0) {
+            const orchSeconds = (stats.avgOrchestrationTime / 1000).toFixed(1);
+            console.log(`  Avg orchestration overhead: ${orchSeconds}s`);
+            console.log(
+                '  (Orchestrator call for semantic grouping — one-time per commit)'
+            );
+            console.log();
+        }
+
+        if (Object.keys(stats.successesByHook).length > 0) {
+            console.log('  Successes by hook:');
+            for (const [hook, count] of Object.entries(stats.successesByHook)) {
+                console.log(`    ${hook}: ${count}`);
+            }
+            console.log();
+        }
+    } catch (err) {
+        logger.debug('diff-batch-info - runDiffBatchInfo', 'Failed to load telemetry', err);
+        console.log('  Could not load telemetry data.');
+        console.log();
+    }
+
+    console.log('📂 Telemetry files: .claude/telemetry/');
+    console.log('💡 Use --debug true to see orchestrator decisions in real time');
+    console.log();
+}

package/lib/commands/install.js

@@ -327,11 +327,6 @@ export function extractLegacySettings(rawConfig) {
         }
     }
 
-    // Subagent batchSize (allowed)
-    if (rawConfig.subagents?.batchSize !== undefined) {
-        allowedOverrides.subagents = { batchSize: rawConfig.subagents.batchSize };
-    }
-
     // Advanced params (preserved with warning in manual migration)
     if (rawConfig.analysis?.ignoreExtensions !== undefined) {
         if (!allowedOverrides.analysis) allowedOverrides.analysis = {};
@@ -343,11 +338,6 @@ export function extractLegacySettings(rawConfig) {
         allowedOverrides.commitMessage.taskIdPattern = rawConfig.commitMessage.taskIdPattern;
     }
 
-    if (rawConfig.subagents?.model !== undefined) {
-        if (!allowedOverrides.subagents) allowedOverrides.subagents = {};
-        allowedOverrides.subagents.model = rawConfig.subagents.model;
-    }
-
     return allowedOverrides;
 }
 

package/lib/config.js

@@ -6,9 +6,8 @@
  *
  * v2.8.0 Changes:
  * - Removed 21 redundant parameters (hardcoded sensible defaults)
- * - Only 5 user-configurable parameters remain
- * - Preset can override: subagents.batchSize
- * - User can override: github.pr.*, subagents.batchSize
+ * - Only 4 user-configurable parameters remain
+ * - User can override: github.pr.*
  * - Advanced params moved to config.advanced.example.json
  *
  * User-configurable:
@@ -16,12 +15,10 @@
  * - github.pr.defaultBase
  * - github.pr.reviewers
  * - github.pr.labelRules
- * - subagents.batchSize
  *
  * Advanced (in example file only):
  * - analysis.ignoreExtensions
  * - commitMessage.taskIdPattern
- * - subagents.model
  */
 
 import fs from 'fs';
@@ -35,7 +32,7 @@ import logger from './utils/logger.js';
 const HARDCODED = {
     analysis: {
         maxFileSize: 1000000, // 1MB - sufficient for most files
-        maxFiles: 20, // Reasonable limit per commit
+        maxFiles: 30, // Reasonable limit per commit
         timeout: 300000, // 5 minutes - adequate for Claude API
         contextLines: 3, // Git default
         ignoreExtensions: [] // Can be set in advanced config only
@@ -46,9 +43,7 @@ const HARDCODED = {
         taskIdPattern: '([A-Z]{1,3}[-\\s]\\d{3,5})' // Jira/GitHub/Linear pattern
     },
     subagents: {
-        enabled: true, // Enable by default (faster analysis)
-        model: 'haiku', // Fast and cost-effective
-        batchSize: 3 // Reasonable parallelization
+        enabled: true // Enable by default (faster analysis via orchestration)
     },
     templates: {
         baseDir: '.claude/prompts',
@@ -57,7 +52,6 @@ const HARDCODED = {
         commitMessage: 'COMMIT_MESSAGE.md',
         analyzeDiff: 'ANALYZE_DIFF.md',
         resolution: 'CLAUDE_RESOLUTION_PROMPT.md',
-        subagentInstruction: 'SUBAGENT_INSTRUCTION.md',
         createGithubPR: 'CREATE_GITHUB_PR.md'
     },
     output: {
@@ -106,10 +100,6 @@ const defaults = {
         }
     },
 
-    // Subagent configuration (preset can override)
-    subagents: {
-        batchSize: 3 // Files per parallel batch
-    }
 };
 
 /**
@@ -196,8 +186,8 @@ const loadUserConfig = async (baseDir = process.cwd()) => {
 
 /**
  * Extracts only allowed parameters from legacy config
- * v2.8.0 only allows: github.pr.*, subagents.batchSize
- * Advanced: analysis.ignoreExtensions, commitMessage.taskIdPattern, subagents.model
+ * Allowed: github.pr.*
+ * Advanced: analysis.ignoreExtensions, commitMessage.taskIdPattern
  *
  * @param {Object} legacyConfig - Legacy format config
  * @returns {Object} Allowed parameters only
@@ -219,11 +209,6 @@ const extractAllowedParams = (legacyConfig) => {
         }
     }
 
-    // Subagent batchSize (allowed)
-    if (legacyConfig.subagents?.batchSize !== undefined) {
-        allowed.subagents = { batchSize: legacyConfig.subagents.batchSize };
-    }
-
     // Advanced params (allowed but warn)
     if (legacyConfig.analysis?.ignoreExtensions !== undefined) {
         if (!allowed.analysis) allowed.analysis = {};
@@ -237,12 +222,6 @@ const extractAllowedParams = (legacyConfig) => {
         logger.warning('ℹ️  Using advanced parameter: commitMessage.taskIdPattern');
     }
 
-    if (legacyConfig.subagents?.model !== undefined) {
-        if (!allowed.subagents) allowed.subagents = {};
-        allowed.subagents.model = legacyConfig.subagents.model;
-        logger.warning('ℹ️  Using advanced parameter: subagents.model');
-    }
-
     return allowed;
 };