claude-git-hooks 2.0.0 → 2.3.0

package/CHANGELOG.md

@@ -5,6 +5,218 @@ 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.3.0] - 2025-11-11
+
+### ✨ 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
+
+- **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`)
+
+### 🐛 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
+- **Template Name Mismatch**: Fixed config.js template paths
+  - `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
+
+- ❌ Deleted `readPassword()` function (24 lines) - unused since v2.0.0 sudo removal
+- ❌ Deleted `setMode()` function (5 lines) - empty implementation, never used
+- ❌ Deleted `readMultipleFiles()` function (62 lines) - exported but never imported
+- ❌ Removed `"main": "lib/index.js"` from package.json - CLI-only package
+- ❌ Deleted obsolete root template `CLAUDE_PRE_COMMIT_SONAR.md`
+
+### 🔄 Changed
+
+- **Commit Message Timeout**: Increased from 120s to 180s for complex analysis
+- **Config Loading**: All hooks now use async `getConfig()` for proper preset merging
+
+### 📚 Documentation
+
+- 📖 Updated CHANGELOG with v2.3.0 release notes
+- 📝 Marked Phase 3 preset system as IMPLEMENTED in spec
+
+### 🎯 Preset Examples
+
+```bash
+# List available presets
+claude-hooks presets
+
+# Set backend preset (filters to .java, .xml, .yml files)
+claude-hooks --set-preset backend
+
+# Check active preset
+claude-hooks preset current
+
+# All presets installed during: claude-hooks install
+```
+
+### 📦 Available Presets
+
+1. **backend** - Spring Boot + SQL Server (Java, XML, YAML)
+2. **frontend** - React + Material-UI (JS, JSX, TS, TSX, CSS)
+3. **fullstack** - Backend + Frontend + DB with consistency checks
+4. **database** - SQL Server migrations and procedures
+5. **ai** - Node.js + Claude CLI integration
+6. **default** - General-purpose scripting
+
+### 📋 Migration from v2.2.0
+
+No breaking changes. Presets are opt-in:
+
+```bash
+# Continue using defaults (no preset)
+git commit -m "message"
+
+# Or activate a preset
+claude-hooks --set-preset backend
+git commit -m "message"  # Now filters to .java, .xml, .yml only
+```
+
+## [2.2.0] - 2025-11-04
+
+### ✨ 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
+
+- **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
+
+- **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`
+
+### 🔄 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
+
+- **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
+
+- **Template Loading**
+  - 📂 Enhanced `loadTemplate()` with fallback: `.claude/` → `templates/`
+  - 🔀 Enables per-project customization of prompts
+
+### 🗑️ Removed
+
+- ❌ Deleted `buildCommitMessagePrompt()` - unused legacy code
+- ❌ Removed all `process.env` references except OS check
+
+### 📚 Documentation
+
+- 📖 Added `next-steps/V2.2.0_CONFIG_CENTRALIZATION.md`
+- 📖 Added `next-steps/V2.2.0_PHASE2_PROMPTS.md`
+- 📝 Updated configuration examples and customization guides
+
+### 🎯 Benefits
+
+- **Maintainability:** Prompts editable by non-developers
+- **Flexibility:** Easy A/B testing of prompt styles
+- **Customization:** Per-project overrides via `.claude/config.json`
+- **Simplicity:** Clear separation of concerns (JS = logic, .md = content)
+
+### 📋 Migration Guide
+
+No breaking changes. All defaults match previous behavior.
+
+**Optional: Customize configuration**
+```bash
+# Create project config
+mkdir -p .claude
+cat > .claude/config.json << 'EOF'
+{
+  "analysis": {
+    "maxFileSize": 200000,
+    "maxFiles": 15
+  },
+  "subagents": {
+    "enabled": true,
+    "model": "sonnet"
+  },
+  "system": {
+    "debug": true
+  }
+}
+EOF
+```
+
+**Optional: Customize prompts**
+```bash
+# Override commit message prompt
+cp templates/COMMIT_MESSAGE.md .claude/
+# Edit .claude/COMMIT_MESSAGE.md as needed
+```
+
+## [2.1.0] - 2025-11-04
+
+### Changed
+
+- 🔄 Renombrado marcador de exclusión de línea única: `// SKIP-ANALYSIS` → `// SKIP_ANALYSIS_LINE` para consistencia de nomenclatura
+- 🐛 Corregido bug crítico en orden de detección de patrones que impedía funcionamiento de `SKIP_ANALYSIS_BLOCK`
+
+### Known Issues
+
+- ⚠️ **SKIP_ANALYSIS marcado como EXPERIMENTAL/BROKEN**: Los marcadores de exclusión no funcionan correctamente porque el análisis se realiza sobre git diff en lugar del archivo completo. Marcadores agregados en commits anteriores no son detectados en cambios subsecuentes.
+
+### Migration Guide
+
+Si utilizabas `// SKIP-ANALYSIS` en tu código, reemplázalo por `// SKIP_ANALYSIS_LINE`:
+
+```java
+// Antes (deprecated):
+// SKIP-ANALYSIS
+private String legacyCode;
+
+// Ahora:
+// SKIP_ANALYSIS_LINE
+private String legacyCode;
+```
+
+El marcador de bloque `// SKIP_ANALYSIS_BLOCK` permanece sin cambios.
+
+## [2.0.1] - 2025-11-04
+
+### Fixed
+
+- 🔧 Compatibilidad completa en Windows: corregidos line endings CRLF, validación WSL, y comparación de versiones sin dependencia bash
+- 🔧 Operaciones de rutas utilizan módulo `path` nativo para mejor portabilidad multiplataforma
+
 ## [2.0.0] - 2025-10-30
 
 ### 🚀 BREAKING CHANGE: Migration from Bash to Node.js Hooks

package/README.md

@@ -5,6 +5,7 @@
 ## ✨ Novedad v2.0.0 - Ahora Cross-Platform
 
 **¡Nueva arquitectura!** Migración completa a Node.js con ES6 modules para soporte más universal:
+
 - ✅ **Windows** - Git en Bash y Powershell
 - ✅ **WSL** - Subsistema de Linux
 - ✅ **Linux** - Funcionamiento nativo
@@ -16,8 +17,9 @@
 - 🔍 **Análisis de código pre-commit**: Detecta issues críticos antes de que lleguen al repo
 - 💬 **Mensajes de commit automáticos**: Escribe "auto" y Claude genera el mensaje
 - 📋 **Generación de PRs**: Título, descripción y tests sugeridos con un solo comando
-- 🚫 **Skip inteligente**: Excluye código con comentarios SKIP-ANALYSIS
-- 🕵️‍♂️ **Paralelización**: Análisis asincrónico de archivos con sub agentes
+- 🎯 **Presets por tech-stack**: 6 configuraciones optimizadas (backend, frontend, fullstack, database, ai, default) - v2.3.0+
+- ⚠️ **Skip inteligente** (EXPERIMENTAL/BROKEN): Exclusión de código con comentarios SKIP_ANALYSIS - no funciona correctamente con git diff
+- 🚀 **Parallel Analysis**: Multiple Claude CLI processes analyzing file batches simultaneously (v2.2.0+)
 - 🔄 **Auto-actualización**: Se mantiene actualizado automáticamente
 - 🌍 **Cross-platform**: Windows, WSL, macOS, Linux sin configuración especial
 
@@ -37,6 +39,15 @@ claude-hooks analyze-diff develop
 
 # Reinstalar durante desarrollo (después de npm link)
 claude-hooks install --force --skip-auth
+
+# Listar presets
+claude-hooks presets
+
+# Seleccionar preset
+claude-hooks --set-preset <name>
+
+# Mostrar preset actual
+claude-hooks preset current
 ```
 
 ### 📦 Instalación y Gestión
@@ -85,10 +96,13 @@ git commit --no-verify -m "hotfix: corrección urgente"
 git commit --amend
 ```
 
-### 🚫 Exclusión de Código del Análisis
+### ⚠️ Exclusión de Código del Análisis (EXPERIMENTAL/BROKEN)
 
 ```java
-// SKIP-ANALYSIS
+// NOTA: Este feature NO funciona correctamente
+// Los marcadores no son detectados si fueron agregados en commits anteriores
+
+// SKIP_ANALYSIS_LINE
 private String legacyCode = "no analizar siguiente línea";
 
 // SKIP_ANALYSIS_BLOCK
@@ -99,25 +113,124 @@ public void methodToIgnore() {
 // SKIP_ANALYSIS_BLOCK
 ```
 
-### 🔧 Configuración Avanzada
+### 🔧 Configuración Avanzada (v2.2.0+)
 
 ```bash
-# Archivos de configuración
+# Configuración vía .claude/config.json
 .claude/
-├── CLAUDE_PRE_COMMIT_SONAR.md      # Personalizar criterios
-├── CLAUDE_ANALYSIS_PROMPT_SONAR.md # Modificar prompt
-└── settings.local.json              # Configuración local
-
-# Variables de entorno
-export CLAUDE_ANALYSIS_MODE=sonarqube  # Modo de análisis
-export CLAUDE_DEBUG=true               # Debug detallado
-
-# Subagent configuration (parallel analysis for multiple files)
-export CLAUDE_USE_SUBAGENTS=true           # Enable subagent parallel analysis
-export CLAUDE_SUBAGENT_MODEL=haiku         # Model: haiku (fast), sonnet (balanced), opus (thorough)
-export CLAUDE_SUBAGENT_BATCH_SIZE=3        # Parallel subagents per batch (default: 3)
+├── config.json                      # Configuración principal (v2.2.0+)
+├── CLAUDE_PRE_COMMIT_SONAR.md      # Personalizar criterios (override)
+└── CLAUDE_ANALYSIS_PROMPT_SONAR.md # Modificar prompt (override)
+
+# Ejemplo de config.json (todas las opciones son opcionales)
+cat > .claude/config.json << 'EOF'
+{
+  "preset": "backend",
+  "analysis": {
+    "maxFileSize": 150000,
+    "maxFiles": 12,
+    "timeout": 150000
+  },
+  "commitMessage": {
+    "autoKeyword": "auto",
+    "timeout": 180000
+  },
+  "subagents": {
+    "enabled": true,
+    "model": "haiku",
+    "batchSize": 3
+  },
+  "system": {
+    "debug": true
+  }
+}
+EOF
 ```
 
+#### 🎯 Presets Disponibles
+
+| Preset        | Extensiones de Archivo                                                     | Caso de Uso      | Tech Stack                   |
+| ------------- | -------------------------------------------------------------------------- | ---------------- | ---------------------------- |
+| **backend**   | `.java`, `.xml`, `.yml`, `.yaml`                                           | APIs Spring Boot | Spring Boot, JPA, SQL Server |
+| **frontend**  | `.js`, `.jsx`, `.ts`, `.tsx`, `.css`, `.scss`, `.html`                     | Apps React       | React, Redux, Material-UI    |
+| **fullstack** | Todos backend + frontend                                                   | Apps full-stack  | Spring Boot + React          |
+| **database**  | `.sql`                                                                     | Scripts de BD    | SQL Server, T-SQL            |
+| **ai**        | `.js`, `.json`, `.md`, `.sh`                                               | Herramientas CLI | Node.js, Claude API          |
+| **default**   | `.js`, `.sh`, `.py`, `.rb`, `.pl`, `.sql`, `.yaml`, `.json`, `.xml`, `.md` | Propósito general| Lenguajes mixtos             |
+
+---
+
+#### 🔍 Qué Verifica Cada Preset
+
+**Backend (Spring Boot + SQL Server)**
+
+- ✅ Diseño de API REST y métodos HTTP
+- ✅ Entidades JPA y repositorios
+- ✅ Seguridad (OWASP Top 10)
+- ✅ Prevención de inyección SQL
+- ✅ Gestión de transacciones
+- ✅ Mapeos DTO
+- ✅ Mejores prácticas Spring Security
+
+**Frontend (React + Material-UI)**
+
+- ✅ Mejores prácticas de hooks React
+- ✅ Diseño de componentes y reusabilidad
+- ✅ Patrones de gestión de estado
+- ✅ Prevención XSS
+- ✅ Optimización de rendimiento
+- ✅ Accesibilidad (a11y)
+- ✅ Error boundaries
+
+**Fullstack (Spring Boot + React)**
+
+- ✅ **Consistencia de contrato API** (prioridad)
+- ✅ Flujo de datos (BD → API → UI)
+- ✅ Autenticación entre capas
+- ✅ Consistencia en manejo de errores
+- ✅ Todas las verificaciones backend
+- ✅ Todas las verificaciones frontend
+
+**Database (SQL Server)**
+
+- ✅ Riesgos de inyección SQL
+- ✅ UPDATE/DELETE sin WHERE
+- ✅ Índices faltantes
+- ✅ Rendimiento de consultas
+- ✅ Manejo de transacciones
+- ✅ Restricciones de integridad de datos
+
+**AI (Node.js + Claude)**
+
+- ✅ Mejores prácticas Claude API
+- ✅ Calidad de ingeniería de prompts
+- ✅ Experiencia de usuario CLI
+- ✅ Seguridad de operaciones Git
+- ✅ Compatibilidad multiplataforma
+- ✅ Protección de API key
+
+**Default (Propósito general)**
+
+- ✅ Fundamentos de calidad de código
+- ✅ Fundamentos de seguridad
+- ✅ Manejo de errores
+- ✅ Mejores prácticas por lenguaje
+- ✅ Mantenibilidad
+
+---
+
+##### ⚙️ Prioridad de Configuración
+
+```
+defaults (lib/config.js)
+  ↓
+preset config (templates/presets/backend/config.json)
+  ↓
+user config (.claude/config.json)  ← MÁXIMA PRIORIDAD
+```
+
+**Nota v2.2.0+:** Variables de entorno ya NO son soportadas. Usar `.claude/config.json` en su lugar.
+
 ### 🎯 Casos de Uso Específicos
 
 ```bash
@@ -145,60 +258,74 @@ git commit -m "fix: resolver issues"
 1. **Mensaje automático**: Usa `"auto"` como mensaje para que Claude lo genere
 2. **Skip auth**: Usa `--skip-auth` en CI/CD o desarrollo local
 3. **Force install**: Usa `--force` para reinstalar sin confirmación
-4. **Debug**: Activa `CLAUDE_DEBUG=true` para ver detalles completos
+4. **Debug**: Activa en `.claude/config.json`: `{"system": {"debug": true}}`
 5. **Archivos grandes**: Se omiten automáticamente archivos > 100KB
-6. **Límite de archivos**: Máximo 10 archivos por commit
+6. **Límite de archivos**: Máximo 10 archivos por commit (configurable)
 
-### 🚀 Parallel Analysis with Subagents (NEW in v1.5.5)
+### 🚀 Parallel Analysis (v2.2.0+)
 
-**When analyzing 3+ files**, enable subagents for faster parallel processing:
+**When analyzing 3+ files**, parallel execution runs multiple Claude CLI processes simultaneously for faster analysis:
 
 ```bash
-# Enable subagent parallel analysis
-export CLAUDE_USE_SUBAGENTS=true
-
-# Optional: Choose model (default: haiku for speed)
-export CLAUDE_SUBAGENT_MODEL=haiku    # Fast & cheap
-export CLAUDE_SUBAGENT_MODEL=sonnet   # Balanced quality/speed
-export CLAUDE_SUBAGENT_MODEL=opus     # Maximum quality
+# Configure in .claude/config.json
+{
+  "subagents": {
+    "enabled": true,
+    "model": "haiku",
+    "batchSize": 2
+  }
+}
+```
 
-# Optional: Adjust batch size (default: 3 files at a time)
-export CLAUDE_SUBAGENT_BATCH_SIZE=3
+**Model options:**
 
-# Now commits will use parallel analysis automatically
-git commit -m "feat: implement multiple features"
-```
+- `haiku` - Fast & cheap (default, recommended)
+- `sonnet` - Balanced quality/speed
+- `opus` - Maximum quality (slower)
 
 **How batching works:**
-- `BATCH_SIZE=1` with 4 files → 4 sequential batches (1 subagent each)
-- `BATCH_SIZE=3` with 4 files → 2 batches (3 parallel, then 1)
-- `BATCH_SIZE=4` with 4 files → 1 batch (all 4 in parallel)
-- Batch size is validated automatically (minimum: 1)
 
-**How it works:**
-- Each file is analyzed by a dedicated Claude subagent
-- Files are processed in batches for optimal performance
-- Results are consolidated automatically into single response
-- Shows execution time for all operations
-- Uses one-line prompt injection - no complex architecture changes
+- Files are split into batches of size `batchSize`
+- Each batch runs in a separate Claude CLI process
+- All batches execute in parallel (true OS-level parallelism)
+- Results are consolidated automatically
+
+**Examples with 4 files:**
+
+- `batchSize: 1` → 4 parallel Claude processes (1 file each) - **fastest**
+- `batchSize: 2` → 2 parallel Claude processes (2 files each) - **balanced**
+- `batchSize: 4` → 1 process (all files) - no parallelization
+
+**Speed improvement:**
+
+- Sequential: 60s per file × 4 = 240s total
+- Parallel (batch=1): max(60s) = 60s total ✅ **4x faster**
 
-**Best for:** Large commits (3+ files), refactoring tasks, feature branches
+**Console output:**
+
+```
+🚀 PARALLEL EXECUTION: 4 Claude processes
+  ⚡ Launching batch 1/4...
+  ⚡ Launching batch 2/4...
+  ⚡ Launching batch 3/4...
+  ⚡ Launching batch 4/4...
+  ⏳ Waiting for all batches to complete...
+
+✅ PARALLEL EXECUTION COMPLETE: 4 results in 62.5s
+```
+
+**Best for:** Large commits (3+ files), refactoring, multi-file features
 
 ### 🎨 Personalización y Customización
 
 **Archivos clave para modificar:**
+
+- `.claude/config.json` - Configuración principal (v2.2.0+)
 - `.claude/CLAUDE_PRE_COMMIT_SONAR.md` - Criterios (backend/frontend/data/db)
 - `.claude/CLAUDE_ANALYSIS_PROMPT_SONAR.md` - Template del prompt
-- `lib/hooks/pre-commit.js` - CONFIG object (extensiones, límites, umbrales)
-
-**Subagents (v1.5.5+)** - Para commits multi-archivo (3+), reduce análisis 60-70%:
-```bash
-export CLAUDE_USE_SUBAGENTS=true      # Activar paralelo
-export CLAUDE_SUBAGENT_MODEL=haiku    # haiku/sonnet/opus
-export CLAUDE_SUBAGENT_BATCH_SIZE=3   # Archivos simultáneos
-```
 
 **Ejemplo:**
+
 ```bash
 vim .claude/CLAUDE_PRE_COMMIT_SONAR.md  # Agregar reglas API REST/Spring Boot
 ```
@@ -265,9 +392,9 @@ El comando `claude-hooks install` crea los siguientes archivos y directorios:
 2. **`.git/hooks/prepare-commit-msg`** - Hook de generación de mensajes
 3. **`.git/hooks/check-version.sh`** - Script de verificación de versión
 4. **`.claude/`** - Directorio para archivos de configuración
-   - `CLAUDE_PRE_COMMIT_SONAR.md` - Pautas de evaluación SonarQube
-   - `CLAUDE_ANALYSIS_PROMPT_SONAR.md` - Template de prompt para análisis SonarQube
-   - `CLAUDE_RESOLUTION_PROMPT.md` - Template para prompt de resolución AI
+    - `CLAUDE_PRE_COMMIT_SONAR.md` - Pautas de evaluación SonarQube
+    - `CLAUDE_ANALYSIS_PROMPT_SONAR.md` - Template de prompt para análisis SonarQube
+    - `CLAUDE_RESOLUTION_PROMPT.md` - Template para prompt de resolución AI
 
 ### Actualización automática de .gitignore
 
@@ -295,21 +422,21 @@ Si no existe un `.gitignore`, se creará uno nuevo. Si ya existe, las entradas s
 
 1. **Intercepta cada intento de commit**
 2. **Extrae y filtra archivos modificados**:
-   - Solo analiza: Java, XML, properties, yml, yaml
-   - Omite archivos mayores a 100KB
-   - Límite de 10 archivos por commit
+    - Solo analiza: Java, XML, properties, yml, yaml
+    - Omite archivos mayores a 100KB
+    - Límite de 10 archivos por commit
 3. **Construye prompt inteligente**:
-   - Usa template de prompt desde `.claude/CLAUDE_ANALYSIS_PROMPT*.md`
-   - Lee las pautas desde `.claude/CLAUDE_PRE_COMMIT*.md`
-   - Incluye el diff completo para archivos nuevos
-   - Muestra solo cambios para archivos existentes
+    - Usa template de prompt desde `.claude/CLAUDE_ANALYSIS_PROMPT*.md`
+    - Lee las pautas desde `.claude/CLAUDE_PRE_COMMIT*.md`
+    - Incluye el diff completo para archivos nuevos
+    - Muestra solo cambios para archivos existentes
 4. **Envía a Claude CLI para revisión**
 5. **Procesa respuesta JSON estructurada**:
-   - blockingIssues siempre como objetos con localización precisa
-   - verifica `QUALITY_GATE`, muestra métricas y issues por severidad
+    - blockingIssues siempre como objetos con localización precisa
+    - verifica `QUALITY_GATE`, muestra métricas y issues por severidad
 6. **Decisión final**:
-   - Si hay problemas críticos → genera prompt AI de resolución y bloquea commit
-   - Si todo está bien → commit procede
+    - Si hay problemas críticos → genera prompt AI de resolución y bloquea commit
+    - Si todo está bien → commit procede
 7. **Generación de Prompt de Resolución AI** (opcional): Cuando se detectan problemas críticos:
 
 - Se genera automáticamente un archivo `claude_resolution_prompt.md`
@@ -320,48 +447,46 @@ Si no existe un `.gitignore`, se creará uno nuevo. Si ya existe, las entradas s
 ### Hook prepare-commit-msg (Generación automática de mensajes)
 
 1. **Se activa cuando el mensaje es**:
-   - `"auto"`
+    - `"auto"`
 2. **Analiza los cambios del staging area**:
-   - Lista archivos modificados con estadísticas
-   - Incluye diffs completos para archivos < 100KB
+    - Lista archivos modificados con estadísticas
+    - Incluye diffs completos para archivos < 100KB
 3. **Genera mensaje en formato Conventional Commits**:
-   - Determina tipo: feat, fix, docs, style, refactor, test, chore
-   - Crea título conciso y descriptivo
-   - Añade body con detalles si es necesario
+    - Determina tipo: feat, fix, docs, style, refactor, test, chore
+    - Crea título conciso y descriptivo
+    - Añade body con detalles si es necesario
 4. **Manejo de errores**:
-   - Si falla la generación → cancela el commit completamente
-   - No usa mensajes genéricos de fallback
+    - Si falla la generación → cancela el commit completamente
+    - No usa mensajes genéricos de fallback
 
 ### Características adicionales
 
 - **Generación de información para Pull Requests**: `claude-hooks analyze-diff [branch]` para comparar rama local con rama origin, propone nombre para rama actual, título y detalles para pull request, da tips para verificar trabajo. Si se especifica branch, compara con origin/branch. Si no, compara con origin de la rama actual. Este comando genera automáticamente:
-  - 📝 Título de PR conciso (máx. 72 caracteres)
-  - 📄 Descripción detallada con markdown
-  - 🌿 Nombre de rama sugerido (formato: tipo/descripcion)
-  - 📋 Tipo de cambio (feature/fix/refactor/docs/test/chore)
-  - ⚠️ Indicador de breaking changes
-  - 🧪 Notas de testing recomendado
-  - 📝 Archivo `.claude-pr-analysis.json`
+    - 📝 Título de PR conciso (máx. 72 caracteres)
+    - 📄 Descripción detallada con markdown
+    - 🌿 Nombre de rama sugerido (formato: tipo/descripcion)
+    - 📋 Tipo de cambio (feature/fix/refactor/docs/test/chore)
+    - ⚠️ Indicador de breaking changes
+    - 🧪 Notas de testing recomendado
+    - 📝 Archivo `.claude-pr-analysis.json`
 - **Auto-actualización**: Verificación automática de versiones antes de cada commit con prompt interactivo para actualizar
 - **Comando update**: `claude-hooks update` para actualizar manualmente a la última versión
 - **Modo debug**: `DEBUG=1 git commit` guarda respuestas en `debug-claude-response.json`
 - **Análisis de PR**: Nuevo comando `analyze-diff` para generar información de Pull Requests
 - **Validación de dependencias**: Verifica que Claude CLI esté autenticado antes de ejecutar
-- **Exclusión de código del análisis con SKIP-ANALYSIS**: Puedes excluir código específico del análisis usando comentarios `// SKIP-ANALYSIS`:
+- **⚠️ Exclusión de código del análisis (EXPERIMENTAL/BROKEN)**: Los marcadores `// SKIP_ANALYSIS_LINE` y `// SKIP_ANALYSIS_BLOCK` no funcionan correctamente. El hook analiza git diff en lugar del archivo completo, por lo que marcadores agregados en commits anteriores no son detectados en cambios subsecuentes.
 
 ```java
-// Excluir una sola línea
-// SKIP-ANALYSIS
-@Autowired private LegacyService legacyService;  // Esta línea no será analizada
+// NOTA: Este feature actualmente NO funciona de forma confiable
+// SKIP_ANALYSIS_LINE
+@Autowired private LegacyService legacyService;
 
-// Excluir un bloque de código
-// SKIP-ANALYSIS_BLOCK
+// SKIP_ANALYSIS_BLOCK
 @Deprecated
 public void methodWithKnownIssues() {
-    // Código legacy que no queremos que sea analizado
-    System.out.println("Debug temporal");
+    System.out.println("Legacy code");
 }
-// SKIP-ANALYSIS_BLOCK
+// SKIP_ANALYSIS_BLOCK
 ```
 
 ### Desactivar/Activar hooks
@@ -437,7 +562,7 @@ claude-git-hooks/
 │   └── utils/
 │       ├── logger.js                         # Sistema de logging centralizado
 │       ├── git-operations.js                 # Operaciones git abstractas
-│       ├── file-operations.js                # I/O con filtro SKIP-ANALYSIS
+│       ├── file-operations.js                # I/O con filtro SKIP_ANALYSIS_LINE
 │       ├── claude-client.js                  # Cliente Claude CLI
 │       ├── prompt-builder.js                 # Constructor de prompts
 │       └── resolution-prompt.js              # Generador de resolution prompts