claude-git-hooks 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -5,116 +5,235 @@ 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.5.0] - 2025-11-26
+
+### ✨ Added
+
+- **GitHub Integration - One-Command PR Creation** - Create pull requests with auto-generated metadata
+    - **What's new**: `claude-hooks create-pr [base]` command that creates PRs on GitHub via Octokit (deterministic)
+    - **Architecture**: Claude analyzes diff and generates metadata (brain) → Octokit creates PR (deterministic actions)
+    - **Key features**:
+        - **Task-ID Extraction**: Automatically extracts task identifiers from branch names (Jira: IX-123, GitHub: #456, Linear: LIN-123)
+        - **Smart PR Generation**: Claude analyzes git diff and generates PR title, description, reviewers, and labels
+        - **Deterministic Creation**: Octokit directly creates PR via GitHub REST API (no MCP dependencies)
+        - **Token Management**: 4-level priority (GITHUB_TOKEN env → GITHUB_PERSONAL_ACCESS_TOKEN env → .claude/settings.local.json → Claude Desktop config)
+        - **Auto-Reviewer Detection**: Detects reviewers from CODEOWNERS file, config patterns, or preset-based rules
+        - **Preset-Based Labels**: Automatically adds labels based on tech stack (backend → java/spring-boot, frontend → react/typescript)
+        - **Interactive Preview**: Shows formatted PR preview with confirmation before creating
+        - **Configurable Defaults**: Set default base branch, reviewers, labels, and rules in `.claude/config.json`
+        - **Error Recovery**: Saves PR metadata to .claude/out/pr-metadata.json on failure for manual retry
+        - **Task-ID in Commits**: Auto-detect task-id from branch when using `git commit -m "auto"` with configurable regex pattern
+    - **Task-ID Pattern (Configurable)**:
+        - **Default**: 1-3 uppercase letters + separator + 3-5 digits (e.g., ABC-12345, IX-123, DE 4567)
+        - **Config**: Set custom regex in `.claude/config.json` → `commitMessage.taskIdPattern`
+        - **Avoids false positives**: Won't match hashes (471459f), invalid formats (ABCD-123, IX-12)
+        - **Examples**: `([A-Z]{1,3}[-\\s]\\d{3,5})` (default), `([A-Z]{2,10}-\\d+)` (Jira-style)
+    - **New modules**:
+        - `lib/utils/task-id.js` - Reusable task-id extraction and formatting (29 tests)
+        - `lib/utils/github-api.js` - Direct Octokit integration (token resolution, PR creation, validation)
+        - `lib/utils/github-client.js` - GitHub MCP wrapper (deprecated, kept for compatibility)
+        - `lib/utils/interactive-ui.js` - Terminal UI helpers (preview, prompts, menus, spinners)
+    - **Configuration**: New `github.pr` section in config with reviewers, labels, and pattern rules
+    - **Files created**:
+        - `lib/utils/task-id.js` - Task ID extraction/formatting
+        - `lib/utils/github-api.js` - Octokit integration with token resolution
+        - `lib/utils/github-client.js` - GitHub MCP client wrapper (deprecated)
+        - `lib/utils/interactive-ui.js` - Interactive CLI components
+        - `templates/config.github.example.json` - Example GitHub configuration
+        - `templates/settings.local.example.json` - Local token storage template
+    - **Files updated**:
+        - `bin/claude-hooks:1044-1377` - Rewritten createPr() function with 13-step Octokit workflow
+        - `bin/claude-hooks:1299-1344` - New setupGitHub() function
+        - `bin/claude-hooks:1772-1774` - Added setup-github case statement
+        - `bin/claude-hooks:1515,1537-1548` - Updated help with token configuration
+        - `bin/claude-hooks:488-490` - Added GitHub PR creation to post-install message
+        - `lib/config.js:37-46` - Added commitMessage.taskIdPattern configuration
+        - `lib/config.js:81-102` - Simplified GitHub config, enabled by default
+        - `lib/utils/github-client.js:792-794` - Deprecation notice for MCP-based createPullRequest
+        - `lib/utils/task-id.js:21-55,71-98,107-144` - Made pattern configurable, reads from config
+        - `lib/hooks/prepare-commit-msg.js:27,182-193,280-290` - Added task-id detection with config support
+        - `package.json` - Added @octokit/rest ^21.0.0 dependency
+    - **Requirements**:
+        - GitHub token with repo and read:org scopes
+        - Repository must have GitHub remote origin
+    - **Token configuration**: `claude-hooks setup-github` guides through token setup
+    - **Comprehensive logging**: Debug logs throughout github-api.js and createPr() for troubleshooting
+    - **Dynamic user agent**: Version read from package.json to prevent staleness
+    - **Task-ID Detection**: Auto-extract or prompt for task-id in commit messages (Jira, GitHub, Linear)
+    - **Impact**: Developers can create well-formatted PRs with proper metadata in one command, reducing PR creation friction
+
+### 🎯 User Experience
+
+- **One-Command Workflow**: `claude-hooks create-pr develop` replaces manual PR creation steps
+- **Deterministic & Reliable**: Octokit provides consistent PR creation (no MCP reliability issues)
+- **Flexible Token Configuration**: Four methods to provide token - choose what works best for your setup
+- **Clear Error Messages**: HTTP status codes (401, 403, 404, 422) with actionable suggestions
+- **Setup Wizard**: `claude-hooks setup-github` validates token and guides configuration
+- **Consistency**: All PRs follow same format with task-ids, descriptions, and appropriate reviewers
+- **Interactive**: Preview and edit PR before creation, choose between Create/Edit/Cancel
+- **Recovery Support**: Failed PRs save metadata to .claude/out/pr-metadata.json for manual retry
+
+### 📚 Documentation
+
+- **Help Text**: Added create-pr and setup-github commands to `claude-hooks help`
+- **Token Configuration**: Clear explanation of 4-level token resolution priority
+- **Use Cases**: Documented create-pr workflow with example output
+- **Configuration Example**: Added `templates/config.github.example.json` with reviewer and label rules
+- **Architecture Note**: Claude only for metadata generation (brain), Octokit for PR creation (deterministic actions)
+- **Post-Install Message**: Added GitHub PR creation section with setup-github and create-pr examples
+- **README Updates**:
+    - Quick Setup section for GitHub PR creation
+    - File structure updated with new GitHub modules
+    - Utility modules table includes github-api.js, task-id.js, interactive-ui.js
+    - Task-ID detection in commit messages documented
+
+## [2.4.2] - 2025-11-24
+
+### 🗑️ Removed
+
+- **SKIP_ANALYSIS Feature** - Removed broken/experimental code exclusion feature
+    - **What was removed**: `// SKIP_ANALYSIS_LINE` and `// SKIP_ANALYSIS_BLOCK` comment markers
+    - **Why**: Feature never worked reliably - hooks analyze git diff instead of full files, so markers in previous commits weren't detected
+    - **Impact**: No user action needed - feature was marked EXPERIMENTAL/BROKEN and wasn't functional
+    - **Cleanup**: Removed all code, documentation, and references from README.md, CHANGELOG.md
+
+## [2.4.1] - 2025-11-19
+
+### 🐛 Fixed
+
+- **Git Bash Windows Support** - Claude hooks now works correctly on Git Bash in Windows
+    - **What changed**:
+        - `--skip-auth` now skips both Claude CLI verification AND authentication (previously only auth)
+        - Windows detection now tries native Claude first, WSL as fallback
+        - `spawn()` now uses `shell: true` to resolve `.cmd`/`.bat` executables
+    - **Why**:
+        - Installation with `--skip-auth` was failing before copying `.md` files and presets
+        - Code assumed Claude must always run via WSL on Windows, ignoring native installations
+        - Git Bash runs Node.js natively on Windows, not in WSL
+        - `spawn()` without shell couldn't find Windows batch files
+    - **Files updated**:
+        - `bin/claude-hooks:512-518` - Skip auth now skips Claude CLI check
+        - `bin/claude-hooks:532-544` - Native Windows Claude detection
+        - `lib/utils/claude-client.js:75-115` - Smart platform detection with fallback
+        - `lib/utils/claude-client.js:145-148` - Added `shell: true` for Windows compatibility
+    - **Impact**: Git Bash users on Windows can now use native Claude (via npm/NVM) instead of requiring WSL
+
+### 🎯 User Experience
+
+- **Installation**: `claude-hooks install --skip-auth` now completes successfully, installing all templates and presets
+- **NVM Compatibility**: Works with Claude CLI installed via npm in current Node version (NVM managed)
+- **Flexible Setup**: Automatically detects and uses best available Claude CLI method (native Windows or WSL)
+
 ## [2.4.0] - 2025-11-17
 
 ### ⚠️ BREAKING CHANGES
 
 - **Debug Mode** - Environment variable `DEBUG` no longer supported
-  - **What changed**: Removed `DEBUG` environment variable support from `lib/utils/logger.js`
-  - **Why**: Aligns with project philosophy "no environment variables" and provides better user experience
-  - **Migration**: Use `claude-hooks --debug true` instead of `DEBUG=1 git commit`
-  - **Alternative**: Set `"system": { "debug": true }` in `.claude/config.json`
+    - **What changed**: Removed `DEBUG` environment variable support from `lib/utils/logger.js`
+    - **Why**: Aligns with project philosophy "no environment variables" and provides better user experience
+    - **Migration**: Use `claude-hooks --debug true` instead of `DEBUG=1 git commit`
+    - **Alternative**: Set `"system": { "debug": true }` in `.claude/config.json`
 
 ### 🔄 Changed
 
 - **File Size Limit Increased** - Default `maxFileSize` increased from 100KB to 1MB
-  - **What changed**: `analysis.maxFileSize` now defaults to 1000000 (1MB) instead of 100000 (100KB)
-  - **Why**: Previous 100KB limit was too restrictive, rejected many legitimate source files
-  - **Files updated**:
-    - `lib/config.js:29` - Default configuration
-    - All preset configs in `templates/presets/*/config.json`
-    - `templates/config.example.json`
-  - **Impact**: More files will be analyzed without manual config adjustment
-  - **User action**: If you want stricter limits, set `"maxFileSize": 100000` in `.claude/config.json`
+    - **What changed**: `analysis.maxFileSize` now defaults to 1000000 (1MB) instead of 100000 (100KB)
+    - **Why**: Previous 100KB limit was too restrictive, rejected many legitimate source files
+    - **Files updated**:
+        - `lib/config.js:29` - Default configuration
+        - All preset configs in `templates/presets/*/config.json`
+        - `templates/config.example.json`
+    - **Impact**: More files will be analyzed without manual config adjustment
+    - **User action**: If you want stricter limits, set `"maxFileSize": 100000` in `.claude/config.json`
 
 ### ✨ Added
 
 - **Debug CLI Command** - New `--debug` flag for managing debug mode
-  - **Usage**: `claude-hooks --debug <true|false|status>`
-  - **Purpose**: Enables detailed logging for troubleshooting
-  - **Implementation**: Generic `updateConfig()` function in `bin/claude-hooks:1262`
-  - **Benefits**: Consistent with `--set-preset` pattern, no need to remember env var syntax
+    - **Usage**: `claude-hooks --debug <true|false|status>`
+    - **Purpose**: Enables detailed logging for troubleshooting
+    - **Implementation**: Generic `updateConfig()` function in `bin/claude-hooks:1262`
+    - **Benefits**: Consistent with `--set-preset` pattern, no need to remember env var syntax
 
 - **Generic Config Updater** - Reusable `updateConfig()` function
-  - **Purpose**: Centralized config update logic for all CLI commands
-  - **Location**: `bin/claude-hooks:1262`
-  - **Features**: Dot notation path support, custom validators, custom success messages
-  - **Extensibility**: Easy to add new config commands (`--set-max-files`, `--set-timeout`, etc.)
+    - **Purpose**: Centralized config update logic for all CLI commands
+    - **Location**: `bin/claude-hooks:1262`
+    - **Features**: Dot notation path support, custom validators, custom success messages
+    - **Extensibility**: Easy to add new config commands (`--set-max-files`, `--set-timeout`, etc.)
 
 ### 🔄 Changed
 
 - **setPreset() Refactored** - Now uses generic `updateConfig()` function
-  - **Effect**: Less code duplication, consistent error handling
-  - **Location**: `bin/claude-hooks:1349`
+    - **Effect**: Less code duplication, consistent error handling
+    - **Location**: `bin/claude-hooks:1349`
 
 - **Debug Mode Activation** - Hooks now enable debug from config
-  - **Files**: `lib/hooks/pre-commit.js:185`, `lib/hooks/prepare-commit-msg.js:124`
-  - **Effect**: Debug logs appear when `config.system.debug` is true
+    - **Files**: `lib/hooks/pre-commit.js:185`, `lib/hooks/prepare-commit-msg.js:124`
+    - **Effect**: Debug logs appear when `config.system.debug` is true
 
 ### 📚 Documentation
 
 - **Help Text Updated** - Added `--debug` command documentation
-  - **Location**: `bin/claude-hooks:1170`
-  - **Includes**: Command description, examples, debug mode section
+    - **Location**: `bin/claude-hooks:1170`
+    - **Includes**: Command description, examples, debug mode section
 
 - **README.md Updated** - Debug command documented in multiple sections
-  - **Cheatsheet**: Added debug commands to "Comandos Frecuentes" (line 52-56)
-  - **Tips**: Updated tip #4 with CLI command (line 269)
-  - **Features**: Updated debug mode description (line 492)
+    - **Cheatsheet**: Added debug commands to "Comandos Frecuentes" (line 52-56)
+    - **Tips**: Updated tip #4 with CLI command (line 269)
+    - **Features**: Updated debug mode description (line 492)
 
 ## [2.3.1] - 2025-11-13
 
 ### 🔄 Changed
 
 - **Configuration Priority** - Updated merge order: `defaults < user config < preset config`
-  - **Rationale**: User sets general preferences in `.claude/config.json`, preset provides tech-stack-specific overrides (highest priority)
-  - **Effect**: Presets now correctly override user settings (e.g., preset's `model: sonnet` wins over user's `model: haiku`)
-  - **Files updated**: `lib/config.js:116` (merge logic), README.md:222 (documentation)
+    - **Rationale**: User sets general preferences in `.claude/config.json`, preset provides tech-stack-specific overrides (highest priority)
+    - **Effect**: Presets now correctly override user settings (e.g., preset's `model: sonnet` wins over user's `model: haiku`)
+    - **Files updated**: `lib/config.js:116` (merge logic), README.md:222 (documentation)
 
 ### ✨ Added
 
 - **Installation Diagnostics Utility** - New `lib/utils/installation-diagnostics.js`
-  - **Purpose**: Reusable error diagnostics with actionable remediation steps
-  - **Exports**: `formatError()`, `getInstallationDiagnostics()`, `isInstallationHealthy()`
-  - **Use case**: Detects installation in wrong directory (common cause of "presets not found" errors)
-  - **Extensible**: Documented future enhancements (file permissions, Claude CLI check, etc.)
+    - **Purpose**: Reusable error diagnostics with actionable remediation steps
+    - **Exports**: `formatError()`, `getInstallationDiagnostics()`, `isInstallationHealthy()`
+    - **Use case**: Detects installation in wrong directory (common cause of "presets not found" errors)
+    - **Extensible**: Documented future enhancements (file permissions, Claude CLI check, etc.)
 
 - **Enhanced Error Messages** - Better guidance when installation fails
-  - **Presets not found** (`lib/utils/preset-loader.js:194`): Shows current vs repo root directory
-  - **Hook scripts missing** (`templates/pre-commit:76`, `templates/prepare-commit-msg:76`): Early `.claude/` check with remediation steps
-  - **npm package issues**: Suggests verifying `npm list -g claude-git-hooks`
+    - **Presets not found** (`lib/utils/preset-loader.js:194`): Shows current vs repo root directory
+    - **Hook scripts missing** (`templates/pre-commit:76`, `templates/prepare-commit-msg:76`): Early `.claude/` check with remediation steps
+    - **npm package issues**: Suggests verifying `npm list -g claude-git-hooks`
 
 - **Bash Wrapper Early Validation** - Hooks now check `.claude/` exists before attempting execution
-  - **Why**: Fails fast with helpful message if installation incomplete or performed from wrong directory
-  - **Effect**: Users immediately know to `cd` to repo root and reinstall
+    - **Why**: Fails fast with helpful message if installation incomplete or performed from wrong directory
+    - **Effect**: Users immediately know to `cd` to repo root and reinstall
 
 - **Claude Error Diagnostics** - New `lib/utils/claude-diagnostics.js`
-  - **Purpose**: Detects and formats Claude CLI errors with actionable solutions
-  - **Error types**: Rate limit, authentication, network, invalid response, generic
-  - **Exports**: `detectClaudeError()`, `formatClaudeError()`, `ClaudeErrorType`, `isRecoverableError()`
-  - **Integration**: `lib/utils/claude-client.js:147` automatically detects and formats errors
-  - **Effect**: Users see clear guidance (e.g., "Rate limit resets in 2 hours, switch to haiku model")
+    - **Purpose**: Detects and formats Claude CLI errors with actionable solutions
+    - **Error types**: Rate limit, authentication, network, invalid response, generic
+    - **Exports**: `detectClaudeError()`, `formatClaudeError()`, `ClaudeErrorType`, `isRecoverableError()`
+    - **Integration**: `lib/utils/claude-client.js:147` automatically detects and formats errors
+    - **Effect**: Users see clear guidance (e.g., "Rate limit resets in 2 hours, switch to haiku model")
 
 ### 📚 Documentation
 
 - **CUSTOMIZATION_GUIDE.md** - Comprehensive preset creation guide in `/templates`
-  - Visual flowchart showing prompt assembly (8-step diagram)
-  - Step-by-step preset creation tutorial
-  - Placeholder system reference with examples
-  - Preset kickstart prompt for Claude-assisted generation
-  - **Burst limit warning**: Explains why git hooks hit rate limits when manual CLI doesn't
-  - Referenced in README.md:333 for discoverability
+    - Visual flowchart showing prompt assembly (8-step diagram)
+    - Step-by-step preset creation tutorial
+    - Placeholder system reference with examples
+    - Preset kickstart prompt for Claude-assisted generation
+    - **Burst limit warning**: Explains why git hooks hit rate limits when manual CLI doesn't
+    - Referenced in README.md:333 for discoverability
 
 - **Utility Modules Reference** - New section in README.md:596
-  - Table of all `lib/utils/` modules with purpose and key exports
-  - Usage examples for other Claude instances
-  - Promotes code reuse across projects
+    - Table of all `lib/utils/` modules with purpose and key exports
+    - Usage examples for other Claude instances
+    - Promotes code reuse across projects
 
 - **README-NPM.md** - Complete rewrite for npm package page
-  - **Length**: 266 lines (up from 145 lines, but more focused)
-  - **Updated**: v2.3.0 presets, v2.2.0 config centralization, v2.0.0 cross-platform
-  - **Added**: Configuration priority explanation, troubleshooting, "What's New" section
-  - **Removed**: Outdated v1.x references, environment variable examples
+    - **Length**: 266 lines (up from 145 lines, but more focused)
+    - **Updated**: v2.3.0 presets, v2.2.0 config centralization, v2.0.0 cross-platform
+    - **Added**: Configuration priority explanation, troubleshooting, "What's New" section
+    - **Removed**: Outdated v1.x references, environment variable examples
 
 ### 🎯 User Experience
 
@@ -129,27 +248,27 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 ### ✨ Added
 
 - **Preset System (Phase 3)**
-  - 🎯 6 built-in presets: `backend`, `frontend`, `fullstack`, `database`, `ai`, `default`
-  - 📦 Self-contained preset packages with custom prompts and configurations
-  - 🔍 Smart file filtering per preset (`.java` for backend, `.tsx` for frontend, etc.)
-  - 🎨 Rich metadata: tech stack, focus areas, file extensions, display names
-  - 🔌 Template inheritance with placeholder replacement ({{TECH_STACK}}, {{FOCUS_AREAS}})
-  - 🛠️ Manual preset selection via CLI: `claude-hooks --set-preset <name>`
-  - 📋 Preset management commands: `presets`, `preset current`, `--set-preset`
-  - 📖 See `next-steps/V2.3.0_PHASE3_PRESETS_FINAL.md` for full specification
+    - 🎯 6 built-in presets: `backend`, `frontend`, `fullstack`, `database`, `ai`, `default`
+    - 📦 Self-contained preset packages with custom prompts and configurations
+    - 🔍 Smart file filtering per preset (`.java` for backend, `.tsx` for frontend, etc.)
+    - 🎨 Rich metadata: tech stack, focus areas, file extensions, display names
+    - 🔌 Template inheritance with placeholder replacement ({{TECH_STACK}}, {{FOCUS_AREAS}})
+    - 🛠️ Manual preset selection via CLI: `claude-hooks --set-preset <name>`
+    - 📋 Preset management commands: `presets`, `preset current`, `--set-preset`
+    - 📖 See `next-steps/V2.3.0_PHASE3_PRESETS_FINAL.md` for full specification
 
 - **CLI Enhancements**
-  - 🏷️ Added `--version`, `-v`, and `version` commands to display current version
-  - 📊 Version check on install with interactive update prompt (skippable with `--skip-auth` or `--force`)
+    - 🏷️ Added `--version`, `-v`, and `version` commands to display current version
+    - 📊 Version check on install with interactive update prompt (skippable with `--skip-auth` or `--force`)
 
 ### 🐛 Fixed
 
 - **Critical Bug**: `prepare-commit-msg` now properly loads merged config (preset + user overrides)
-  - Was using sync default import instead of async `getConfig()`
-  - Preset settings were being ignored in commit message generation
+    - Was using sync default import instead of async `getConfig()`
+    - Preset settings were being ignored in commit message generation
 - **Template Name Mismatch**: Fixed config.js template paths
-  - `COMMIT_MESSAGE.md` (was `CLAUDE_COMMIT_MESSAGE.md`)
-  - `ANALYZE_DIFF.md` (was `CLAUDE_ANALYZE_DIFF.md`)
+    - `COMMIT_MESSAGE.md` (was `CLAUDE_COMMIT_MESSAGE.md`)
+    - `ANALYZE_DIFF.md` (was `CLAUDE_ANALYZE_DIFF.md`)
 - **Missing Auto-Update**: `checkVersionAndPromptUpdate()` now called during install
 
 ### 🗑️ Removed
@@ -212,45 +331,45 @@ git commit -m "message"  # Now filters to .java, .xml, .yml only
 ### ✨ Added
 
 - **Configuration Centralization (Phase 1)**
-  - 📁 Created `lib/config.js` - single source of truth for all configurable values
-  - 🔧 User override support via `.claude/config.json` with deep merge
-  - 📊 Structured config: analysis, commitMessage, subagents, templates, output, system, git
-  - 🚫 Eliminated environment variables (except OS for platform detection)
-  - 📖 See `next-steps/V2.2.0_CONFIG_CENTRALIZATION.md` for details
+    - 📁 Created `lib/config.js` - single source of truth for all configurable values
+    - 🔧 User override support via `.claude/config.json` with deep merge
+    - 📊 Structured config: analysis, commitMessage, subagents, templates, output, system, git
+    - 🚫 Eliminated environment variables (except OS for platform detection)
+    - 📖 See `next-steps/V2.2.0_CONFIG_CENTRALIZATION.md` for details
 
 - **Prompt Externalization (Phase 2)**
-  - 📝 Extracted ALL embedded prompts to external .md template files
-  - 🔌 Created `loadPrompt()` utility - combines load + variable replacement
-  - 📄 New templates: `COMMIT_MESSAGE.md`, `ANALYZE_DIFF.md`
-  - 🎯 JavaScript is now completely "prompt-agnostic"
-  - 📖 See `next-steps/V2.2.0_PHASE2_PROMPTS.md` for details
+    - 📝 Extracted ALL embedded prompts to external .md template files
+    - 🔌 Created `loadPrompt()` utility - combines load + variable replacement
+    - 📄 New templates: `COMMIT_MESSAGE.md`, `ANALYZE_DIFF.md`
+    - 🎯 JavaScript is now completely "prompt-agnostic"
+    - 📖 See `next-steps/V2.2.0_PHASE2_PROMPTS.md` for details
 
 - **Parallel Analysis**
-  - 🚀 True OS-level parallel execution using multiple Claude CLI processes simultaneously
-  - ⚡ `analyzeCodeParallel()` function runs batches via Node.js `Promise.all()`
-  - 📊 Configurable `batchSize` for optimal speed/cost balance (default: 2)
-  - 🔀 Automatic result consolidation with worst-case quality gate logic
-  - 📈 Real-time console output showing parallel batch launches and completion
-  - 🎯 Enabled by default for commits with 3+ files
-  - ⏱️ Speed improvement: up to 4x faster with `batchSize: 1`
+    - 🚀 True OS-level parallel execution using multiple Claude CLI processes simultaneously
+    - ⚡ `analyzeCodeParallel()` function runs batches via Node.js `Promise.all()`
+    - 📊 Configurable `batchSize` for optimal speed/cost balance (default: 2)
+    - 🔀 Automatic result consolidation with worst-case quality gate logic
+    - 📈 Real-time console output showing parallel batch launches and completion
+    - 🎯 Enabled by default for commits with 3+ files
+    - ⏱️ Speed improvement: up to 4x faster with `batchSize: 1`
 
 ### 🔄 Changed
 
 - **Configuration Migration**
-  - ♻️ Migrated `lib/hooks/pre-commit.js` to use centralized config
-  - ♻️ Migrated `lib/hooks/prepare-commit-msg.js` to use centralized config
-  - ♻️ Migrated `lib/utils/claude-client.js` to use centralized config
-  - 🔧 `process.env.DEBUG` → `config.system.debug`
-  - 🔧 All hardcoded timeouts now configurable
+    - ♻️ Migrated `lib/hooks/pre-commit.js` to use centralized config
+    - ♻️ Migrated `lib/hooks/prepare-commit-msg.js` to use centralized config
+    - ♻️ Migrated `lib/utils/claude-client.js` to use centralized config
+    - 🔧 `process.env.DEBUG` → `config.system.debug`
+    - 🔧 All hardcoded timeouts now configurable
 
 - **Prompt Migration**
-  - ♻️ `prepare-commit-msg.js`: 40 lines → 15 lines (62% reduction)
-  - ♻️ `bin/claude-hooks`: 30 lines → 10 lines (67% reduction)
-  - 🎨 Prompts now editable without touching JavaScript code
+    - ♻️ `prepare-commit-msg.js`: 40 lines → 15 lines (62% reduction)
+    - ♻️ `bin/claude-hooks`: 30 lines → 10 lines (67% reduction)
+    - 🎨 Prompts now editable without touching JavaScript code
 
 - **Template Loading**
-  - 📂 Enhanced `loadTemplate()` with fallback: `.claude/` → `templates/`
-  - 🔀 Enables per-project customization of prompts
+    - 📂 Enhanced `loadTemplate()` with fallback: `.claude/` → `templates/`
+    - 🔀 Enables per-project customization of prompts
 
 ### 🗑️ Removed
 
@@ -275,6 +394,7 @@ git commit -m "message"  # Now filters to .java, .xml, .yml only
 No breaking changes. All defaults match previous behavior.
 
 **Optional: Customize configuration**
+
 ```bash
 # Create project config
 mkdir -p .claude
@@ -296,6 +416,7 @@ EOF
 ```
 
 **Optional: Customize prompts**
+
 ```bash
 # Override commit message prompt
 cp templates/COMMIT_MESSAGE.md .claude/
@@ -342,6 +463,7 @@ El marcador de bloque `// SKIP_ANALYSIS_BLOCK` permanece sin cambios.
 
 **Why this change?**
 The bash-based hooks created fundamental incompatibilities with Windows Git and IDE workflows (VSCode, IntelliJ), causing:
+
 - Git worktree path conflicts (Windows paths incompatible with WSL)
 - IDE commit failures when using Windows Git
 - Developers forced to use WSL terminal exclusively, abandoning IDE Git features
@@ -349,16 +471,19 @@ The bash-based hooks created fundamental incompatibilities with Windows Git and
 ### ✅ Advantages
 
 **Cross-Platform Native Support**
+
 - ✅ Works with Windows Git, WSL, and Bash
 - ✅ No more worktree path issues
 - ✅ Single codebase for all platforms
 
 **Dramatically Improved Maintainability**
+
 - ✅ JavaScript/Node.js: ~60-70% of developers proficient vs ~1-2% with bash/jq/sed/awk
 - ✅ Modern tooling: ESLint, Prettier, Jest testing framework
 - ✅ VS Code debugging support vs echo statements
 
 **Professional Development Practices**
+
 - ✅ Unit and integration testing with Jest
 - ✅ Type safety optional (TypeScript)
 - ✅ Consistent error handling patterns
@@ -371,6 +496,7 @@ The bash-based hooks created fundamental incompatibilities with Windows Git and
 ### 🏆 Industry Success Cases
 
 **Node.js Git Hooks - Proven Track Record:**
+
 - **Husky**: 43k GitHub stars, 500+ contributors, 7M+ weekly npm downloads
 - **lint-staged**: 12k stars, 200+ contributors
 - **Commitizen**: 16k stars, industry standard
@@ -385,6 +511,7 @@ The bash-based hooks created fundamental incompatibilities with Windows Git and
 ### Migration Guide
 
 Existing installations will continue working. To upgrade:
+
 1. Run `claude-hooks update` to get v2.0.0
 2. Run `claude-hooks install --force` to reinstall with Node.js hooks
 3. No configuration changes needed - works transparently
@@ -394,27 +521,27 @@ Existing installations will continue working. To upgrade:
 ### Added
 
 - 🚀 **Parallel Analysis with Subagents**
-  - New `CLAUDE_USE_SUBAGENTS` environment variable to enable parallel file analysis
-  - Each file analyzed by dedicated Claude subagent for faster processing
-  - Works across all analysis functions: pre-commit, message generation, and analyze-diff
-  - Significantly faster for commits with 3+ files
+    - New `CLAUDE_USE_SUBAGENTS` environment variable to enable parallel file analysis
+    - Each file analyzed by dedicated Claude subagent for faster processing
+    - Works across all analysis functions: pre-commit, message generation, and analyze-diff
+    - Significantly faster for commits with 3+ files
 
 - ⚙️ **Subagent Configuration Options**
-  - `CLAUDE_SUBAGENT_MODEL` - Choose model: haiku (fast), sonnet (balanced), opus (thorough)
-  - `CLAUDE_SUBAGENT_BATCH_SIZE` - Control parallel processing (default: 3 files at once)
-  - Automatic result consolidation across all subagents
+    - `CLAUDE_SUBAGENT_MODEL` - Choose model: haiku (fast), sonnet (balanced), opus (thorough)
+    - `CLAUDE_SUBAGENT_BATCH_SIZE` - Control parallel processing (default: 3 files at once)
+    - Automatic result consolidation across all subagents
 
 - ⏱️ **Execution Time Measurement**
-  - All operations now display execution time in seconds and milliseconds
-  - Pre-commit analysis: Shows time on success and failure
-  - Message generation: Shows generation time
-  - Analyze-diff: Shows analysis time
-  - Helps identify performance improvements and bottlenecks
+    - All operations now display execution time in seconds and milliseconds
+    - Pre-commit analysis: Shows time on success and failure
+    - Message generation: Shows generation time
+    - Analyze-diff: Shows analysis time
+    - Helps identify performance improvements and bottlenecks
 
 - 🔧 **Git Worktree Support**
-  - `claude-hooks` now recognizes worktrees created in PowerShell from WSL
-  - Automatically converts Windows paths (C:\) to WSL paths (/mnt/c/)
-  - No more "not a git repository" errors when working in cross-platform worktrees
+    - `claude-hooks` now recognizes worktrees created in PowerShell from WSL
+    - Automatically converts Windows paths (C:\) to WSL paths (/mnt/c/)
+    - No more "not a git repository" errors when working in cross-platform worktrees
 
 ### Changed
 
@@ -429,14 +556,14 @@ Existing installations will continue working. To upgrade:
 ### Fixed
 
 - 🔧 **Generación de prompt de resolución en modo SonarQube**
-  - Ahora se genera correctamente `claude_resolution_prompt.md` cuando el Quality Gate falla
-  - El archivo se genera cuando hay `blockingIssues`, independiente del tipo de fallo
-  - Corregido el flujo para que siempre muestre los issues críticos antes de generar el prompt
+    - Ahora se genera correctamente `claude_resolution_prompt.md` cuando el Quality Gate falla
+    - El archivo se genera cuando hay `blockingIssues`, independiente del tipo de fallo
+    - Corregido el flujo para que siempre muestre los issues críticos antes de generar el prompt
 
 - 🎯 **Unificación de lógica de análisis**
-  - Eliminada lógica duplicada entre modo "clásico" y SonarQube
-  - Ahora siempre se usa modo SonarQube (como se especificó en v1.4.1)
-  - Simplificación del flujo de decisión en el pre-commit hook
+    - Eliminada lógica duplicada entre modo "clásico" y SonarQube
+    - Ahora siempre se usa modo SonarQube (como se especificó en v1.4.1)
+    - Simplificación del flujo de decisión en el pre-commit hook
 
 ### Changed
 
@@ -448,9 +575,9 @@ Existing installations will continue working. To upgrade:
 ### Fixed
 
 - 🔧 Comando `analyze-diff` ahora siempre compara con ramas origin
-  - Si se especifica rama: compara con `origin/rama-especificada`
-  - Si no se especifica: compara con `origin/rama-actual`
-  - Fallback automático a `origin/develop` y luego `origin/main` si no existe la rama origin
+    - Si se especifica rama: compara con `origin/rama-especificada`
+    - Si no se especifica: compara con `origin/rama-actual`
+    - Fallback automático a `origin/develop` y luego `origin/main` si no existe la rama origin
 
 ### Changed
 
@@ -481,13 +608,13 @@ Existing installations will continue working. To upgrade:
 ### Added
 
 - 🔍 Nuevo comando `claude-hooks analyze-diff [base]` para análisis de diferencias entre ramas
-  - Genera título de PR conciso (máx. 72 caracteres)
-  - Crea descripción detallada del PR con markdown
-  - Sugiere nombre de rama siguiendo formato tipo/descripcion
-  - Identifica tipo de cambio (feature/fix/refactor/docs/test/chore)
-  - Detecta breaking changes
-  - Proporciona notas de testing recomendado
-  - Guarda resultados en `.claude-pr-analysis.json`
+    - Genera título de PR conciso (máx. 72 caracteres)
+    - Crea descripción detallada del PR con markdown
+    - Sugiere nombre de rama siguiendo formato tipo/descripcion
+    - Identifica tipo de cambio (feature/fix/refactor/docs/test/chore)
+    - Detecta breaking changes
+    - Proporciona notas de testing recomendado
+    - Guarda resultados en `.claude-pr-analysis.json`
 
 ### Changed
 
@@ -511,11 +638,11 @@ Existing installations will continue working. To upgrade:
 ### Added
 
 - 🚫 Comentario `// SKIP-ANALYSIS` para excluir código del análisis
-  - Una línea: excluye la siguiente línea
-  - Bloque: código entre dos comentarios `// SKIP_ANALYSIS_BLOCK` es excluido
+    - Una línea: excluye la siguiente línea
+    - Bloque: código entre dos comentarios `// SKIP_ANALYSIS_BLOCK` es excluido
 - 📝 Excepciones para Spring Framework en criterios de evaluación
-  - `@Autowired` no es considerado issue bloqueante (máximo severidad MAJOR)
-  - Inyección de dependencias con field injection es aceptable
+    - `@Autowired` no es considerado issue bloqueante (máximo severidad MAJOR)
+    - Inyección de dependencias con field injection es aceptable
 
 ### Changed