claude-git-hooks 2.19.0 → 2.21.0

package/CHANGELOG.md

@@ -5,6 +5,52 @@ 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.21.0] - 2026-03-10
+
+### ✨ Added
+- New `analyze-pr` command to analyze GitHub PRs with team guidelines and post review comments (#86)
+- Linear ticket enrichment for PR analysis - automatically fetches ticket context when `[AUT-1234]` pattern found in PR title
+- New `setup-linear` command for interactive Linear token configuration
+- Centralized token persistence via `token-store.js` utility for managing settings.local.json
+- PR statistics tracking with write-only JSONL analytics at `.claude/statistics/pr/stats.jsonl`
+- Interactive comment workflow for PR analysis - confirm, select, or skip findings before posting
+- Auto-detection of preset from PR labels, Linear ticket labels, or file extensions
+- New `ANALYZE_PR.md` prompt template for GitHub PR review with category injection
+- Category normalization with fuzzy alias mapping for analysis results
+
+### 🔧 Changed
+- Extended `github-api.js` with PR fetch, review creation, and URL parsing capabilities
+- Updated documentation (README, README-NPM, CLAUDE.md) with analyze-pr usage and architecture
+
+
+## [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

@@ -10,7 +10,8 @@
 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 creation**: `claude-hooks create-pr [branch]` creates the PR on GitHub with automatic metadata (reviewers from CODEOWNERS, labels by preset)
+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)
 
 ## Architecture
 
@@ -54,8 +55,10 @@ claude-git-hooks/
 │   │   ├── install.js                # Install command - dependencies, hooks, templates
 │   │   ├── 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
 │   │   ├── create-pr.js              # PR creation - full Octokit workflow
 │   │   ├── setup-github.js           # Token setup - interactive GitHub configuration
+│   │   ├── setup-linear.js           # Token setup - interactive Linear configuration
 │   │   ├── presets.js                # Preset management - list, set, show current
 │   │   ├── update.js                 # Self-update - check and install latest version
 │   │   ├── migrate-config.js         # Config migration - legacy to v2.8.0 format
@@ -63,23 +66,29 @@ 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
 │       ├── logger.js                 # Logging system - centralized output, debug mode
 │       ├── preset-loader.js          # Preset system - load tech-stack configurations
 │       ├── pr-metadata-engine.js     # PR metadata generation - branch context, diff reduction, metadata (v2.14.0)
-│       ├── github-api.js             # Octokit integration - PR creation, token validation
+│       ├── github-api.js             # Octokit integration - PR creation, PR analysis, token validation
 │       ├── github-client.js          # GitHub helpers - CODEOWNERS parsing, reviewers
+│       ├── token-store.js            # Token persistence - centralized settings.local.json read/write
+│       ├── linear-connector.js       # Linear API - ticket context fetching with retry
+│       ├── pr-statistics.js          # PR statistics - write-only JSONL analytics
 │       ├── 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 +104,11 @@ 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
+│   ├── ANALYZE_PR.md                 # PR analysis - GitHub PR review template with category injection
 │   ├── 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 +137,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 +177,36 @@ 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):**
-
-| 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)|
+**Hardcoded defaults (v2.8.0+):**
+
+| 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             | sonnet  | Default, configurable via `config.judge.model`     |
+| 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                           |
+
+**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 +219,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:
+
+| Files | Strategy |
+|-------|----------|
+| 1–2   | Sequential — single Claude call |
+| **3+** | **Intelligent orchestration** — Opus orchestrator, semantic grouping, per-batch model, shared context |
 
-When 3+ files are present, the system divides into batches and executes multiple `claude` CLI processes in parallel:
+**Orchestration flow (3+ files):**
 
 ```
-4 files + batchSize=2
+staged files (N ≥ 3)
   ↓
-Batch 1: [file1, file2] → claude CLI process #1 (parallel)
-Batch 2: [file3, file4] → claude CLI process #2 (parallel)
+[ORCHESTRATOR — Opus, 60s timeout]
+  Input: file overview table + detected cross-file deps (JS/TS/Java/Python regex)
+  Output: { batches: [{ filePaths, rationale, model }] }
   ↓
-Wait for both → consolidate results
+For each batch:
+  → buildAnalysisPrompt(batchFiles + commonContext + batchRationale)
+  → analyzeCode(prompt, { model: batch.model })     ← per-batch model
+  [all batches run in parallel via Promise.all]
+  ↓
+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
 
@@ -221,15 +261,18 @@ Wait for both → consolidate results
 | `hooks.js`              | Hook management           | `runEnable()`, `runDisable()`, `runStatus()`, `runUninstall()`                |
 | `analyze.js`            | Interactive code analysis | `runAnalyze()`                                                                |
 | `analyze-diff.js`       | Diff analysis             | `runAnalyzeDiff()`                                                            |
+| `analyze-pr.js`         | PR analysis from URL      | `runAnalyzePr()`, `normalizeCategory()`                                       |
 | `create-pr.js`          | PR creation               | `runCreatePr()`                                                               |
 | `bump-version.js`       | Version management        | `runBumpVersion()`                                                            |
 | `generate-changelog.js` | CHANGELOG generation      | `runGenerateChangelog()`                                                      |
-| `setup-github.js`       | Token setup               | `runSetupGitHub()`                                                            |
+| `setup-github.js`       | Token setup (GitHub)      | `runSetupGitHub()`                                                            |
+| `setup-linear.js`       | Token setup (Linear)      | `runSetupLinear()`                                                            |
 | `presets.js`            | Preset management         | `runShowPresets()`, `runSetPreset()`, `runCurrentPreset()`                    |
 | `update.js`             | Self-update               | `runUpdate()`                                                                 |
 | `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,20 +281,25 @@ 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) |
 | `git-tag-manager.js`     | Git tag operations    | `createTag()`, `pushTags()`, `getLocalTags()`, `getRemoteTags()`, `compareLocalAndRemoteTags()`, `tagExists()` (v2.12.0)                                                       |
 | `version-manager.js`     | Version management    | `discoverVersionFiles()`, `getDiscoveryResult()`, `readVersionFromFile()`, `writeVersionToFile()`, `updateVersionFiles()`, `modifySuffix()`, `incrementVersion()`, `parseVersion()`, `validateVersionFormat()`, `compareVersions()`, `validateVersionAlignment()` (v2.15.5)                             |
 | `changelog-generator.js` | CHANGELOG generation  | `generateChangelogEntry()`, `updateChangelogFile()`, `getLastFinalVersionTag()`, `getCommitsSinceTag()`, `discoverChangelogFiles()`, `selectChangelogFile()` (v2.12.0)         |
-| `github-api.js`          | Octokit integration   | `createPullRequest()`, `validateToken()`, `saveGitHubToken()`, `fetchFileContent()`, `fetchDirectoryListing()`, `createIssue()`                                                |
+| `github-api.js`          | Octokit integration   | `createPullRequest()`, `fetchPullRequest()`, `fetchPullRequestFiles()`, `createPullRequestReview()`, `parseGitHubPRUrl()`, `validateToken()`, `saveGitHubToken()`, `fetchFileContent()`, `fetchDirectoryListing()`, `createIssue()` |
 | `github-client.js`       | GitHub helpers        | `getReviewersForFiles()`, `parseGitHubRepo()`                                                                                                                                  |
+| `token-store.js`         | Token persistence     | `loadToken()`, `saveToken()`, `hasToken()`, `loadLocalSettings()`                                                                                                              |
+| `linear-connector.js`    | Linear integration    | `loadLinearToken()`, `testConnection()`, `fetchTicket()`, `extractLinearTicketFromTitle()`, `parseLinearIdentifier()`, `LinearConnectorError`                                   |
+| `pr-statistics.js`       | PR statistics         | `recordPRAnalysis()` — write-only JSONL at `.claude/statistics/pr/stats.jsonl`                                                                                                  |
 | `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 +310,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 +324,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)**
@@ -320,6 +375,21 @@ claude-hooks analyze-diff develop
   → saves to .claude/out/pr-analysis.json
 ```
 
+**Flow 3.5: Analyze PR from GitHub URL**
+
+```
+claude-hooks analyze-pr https://github.com/owner/repo/pull/123
+  → parseGitHubPRUrl() → { owner, repo, number }
+  → fetchPullRequest() + fetchPullRequestFiles() via Octokit
+  → extractLinearTicketFromTitle() → fetchTicket() (optional enrichment)
+  → resolvePreset(): CLI flag → PR labels → ticket labels → auto-detect from extensions → 'default'
+  → loadPrompt('ANALYZE_PR.md') with preset guidelines + category injection
+  → executeClaudeWithRetry() → extractJSON() → normalizeCategory() with fuzzy aliases
+  → interactive comment workflow: post all / select / skip
+  → createPullRequestReview() with inline comments + review body
+  → recordPRAnalysis() → .claude/statistics/pr/stats.jsonl
+```
+
 **Flow 4: PR creation (with auto-push v2.11.0, engine v2.14.0)**
 
 ```
@@ -632,8 +702,11 @@ claude-hooks preset current           # View current preset
 
 # Analysis and PRs
 claude-hooks analyze-diff [branch]    # Analyze diff for PR
+claude-hooks analyze-pr <pr-url>      # Analyze GitHub PR with team guidelines
+claude-hooks analyze-pr <url> --dry-run  # Analyze without posting comments
 claude-hooks create-pr [branch]       # Create PR on GitHub
 claude-hooks setup-github             # Configure GitHub token
+claude-hooks setup-linear             # Configure Linear token
 
 # Version management
 claude-hooks bump-version patch       # Bump version (commits, tags locally)
@@ -648,6 +721,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

@@ -41,10 +41,11 @@ claude-hooks create-pr develop
 - Prompts for confirmation (configurable)
 - Handles diverged branches gracefully
 
-### GitHub Token Setup
+### Token Setup
 
 ```bash
-claude-hooks setup-github  # Shows status and configuration options
+claude-hooks setup-github  # Configure GitHub token for PR creation
+claude-hooks setup-linear  # Configure Linear token for ticket enrichment
 ```
 
 **Option 1 - Settings file (recommended):**
@@ -94,6 +95,24 @@ claude-hooks analyze-diff develop
 # Generates PR metadata without creating
 ```
 
+### Analyze PR from GitHub URL
+
+```bash
+claude-hooks analyze-pr https://github.com/owner/repo/pull/123
+# Fetches PR, applies preset guidelines, posts review comments
+
+claude-hooks analyze-pr https://github.com/owner/repo/pull/123 --dry-run
+# Analyze without posting comments
+
+claude-hooks analyze-pr https://github.com/owner/repo/pull/123 --preset backend --model opus
+# Override preset and model
+```
+
+- Auto-detects preset from PR labels, Linear ticket labels, or file extensions
+- Enriches with Linear ticket context when `[AUT-1234]` found in PR title
+- Interactive comment workflow: confirm/skip each finding before posting
+- Classifies into inline (file:line) and general (review-level) categories
+
 ### Bump Version
 
 Automatic version management with CHANGELOG generation and Git tagging:
@@ -218,6 +237,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
@@ -253,15 +280,18 @@ claude-hooks update   # Update to latest version
 | `hooks.js` | **Hook management** - enable, disable, status, uninstall | `runEnable()`, `runDisable()`, `runStatus()`, `runUninstall()` |
 | `analyze.js` | **Interactive code analysis** - analyze before committing | `runAnalyze()` |
 | `analyze-diff.js` | **Diff analysis** - generate PR metadata from git diff | `runAnalyzeDiff()` |
+| `analyze-pr.js` | **PR analysis** - analyze GitHub PR with team guidelines | `runAnalyzePr()` |
 | `create-pr.js` | **PR creation** - full workflow via Octokit | `runCreatePr()` |
 | `bump-version.js` | **Version management** - bump with CHANGELOG and Git tag | `runBumpVersion()` |
 | `generate-changelog.js` | **CHANGELOG generation** - standalone command | `runGenerateChangelog()` |
 | `setup-github.js` | **Token setup** - interactive GitHub configuration | `runSetupGitHub()` |
+| `setup-linear.js` | **Token setup** - interactive Linear configuration | `runSetupLinear()` |
 | `presets.js` | **Preset management** - list, set, show current | `runShowPresets()`, `runSetPreset()`, `runCurrentPreset()` |
 | `update.js` | **Self-update** - check and install latest version | `runUpdate()` |
 | `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 +299,19 @@ 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-api.js` | **Octokit integration** - PR creation, PR analysis, token validation, content fetching | `createPullRequest()`, `fetchPullRequest()`, `fetchPullRequestFiles()`, `createPullRequestReview()`, `parseGitHubPRUrl()`, `validateToken()`, `saveGitHubToken()`, `fetchFileContent()`, `fetchDirectoryListing()`, `createIssue()` |
+| `token-store.js` | **Token persistence** - centralized settings.local.json read/write | `loadToken()`, `saveToken()`, `hasToken()`, `loadLocalSettings()` |
+| `linear-connector.js` | **Linear integration** - ticket context fetching with retry | `fetchTicket()`, `extractLinearTicketFromTitle()`, `testConnection()`, `loadLinearToken()` |
+| `pr-statistics.js` | **PR statistics** - write-only JSONL analytics | `recordPRAnalysis()` |
 | `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 +327,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.
@@ -323,6 +362,21 @@ claude-hooks analyze-diff|create-pr → bin/claude-hooks (router)
   → create-pr: additionally creates PR via Octokit API
 ```
 
+#### PR Analysis (analyze-pr)
+
+```
+claude-hooks analyze-pr <url> → bin/claude-hooks (router)
+  → lib/commands/analyze-pr.js
+  → parseGitHubPRUrl() → fetchPullRequest() + fetchPullRequestFiles()
+  → extractLinearTicketFromTitle() → fetchTicket() (optional enrichment)
+  → resolvePreset() (labels → ticket → auto-detect → default)
+  → loadPrompt('ANALYZE_PR.md') with preset guidelines + categories
+  → executeClaudeWithRetry() → extractJSON() → normalizeCategory()
+  → interactive comment workflow (confirm/skip)
+  → createPullRequestReview() → inline + general comments
+  → recordPRAnalysis() (JSONL statistics)
+```
+
 ### Config Priority
 
 ```
@@ -350,7 +404,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 +412,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
 
@@ -370,6 +423,7 @@ Preset always wins - tech-stack specific has priority over user preferences.
 | CLI argument parsing | `bin/claude-hooks` |
 | Install workflow | `lib/commands/install.js` |
 | PR creation flow | `lib/commands/create-pr.js` |
+| PR analysis from URL | `lib/commands/analyze-pr.js` |
 | Analysis logic | `lib/hooks/pre-commit.js` |
 | Message generation | `lib/hooks/prepare-commit-msg.js` |
 | Prompt templates | `templates/*.md` or `.claude/prompts/*.md` |
@@ -377,6 +431,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
 
@@ -390,40 +447,60 @@ claude-git-hooks/
 │   │   ├── install.js            # Install command - hooks, templates
 │   │   ├── hooks.js              # Hook management - enable/disable
 │   │   ├── analyze-diff.js       # Diff analysis - PR metadata
+│   │   ├── analyze-pr.js         # PR analysis - GitHub PR review
 │   │   ├── create-pr.js          # PR creation - Octokit workflow
-│   │   ├── setup-github.js       # Token setup - interactive config
+│   │   ├── setup-github.js       # Token setup - interactive GitHub config
+│   │   ├── setup-linear.js       # Token setup - interactive Linear config
 │   │   ├── presets.js            # Preset commands - list/set
 │   │   ├── update.js             # Self-update - npm latest
 │   │   ├── 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)
+│       └── token-store.js               # Token persistence - settings.local.json
 ├── 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)
 
-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
+Two-tier strategy based on file count:
+
+| 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

@@ -93,6 +93,7 @@ async function main() {
         [
             'install',
             'analyze-diff',
+            'analyze-pr',
             'create-pr',
             'bump-version',
             'generate-changelog',