claude-git-hooks 2.6.3 → 2.8.0

package/CHANGELOG.md

@@ -5,6 +5,179 @@ 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.8.0] - 2025-12-24
+
+### 🎨 Changed
+
+- **Simplified configuration format** - New v2.8.0 config structure reduces redundancy and improves maintainability
+    - **What changed**: Config now uses `version` field and `overrides` structure, 21 parameters moved to hardcoded defaults
+    - **New format**: `{ "version": "2.8.0", "preset": "backend", "overrides": {...} }`
+    - **Old format**: `{ "preset": "backend", "analysis": {...}, "subagents": {...}, ... }` (20+ top-level keys)
+    - **User-configurable** (5 params): `preset`, `github.pr.*`, `subagents.batchSize`
+    - **Hardcoded** (21 params): `analysis.*` (maxFileSize, maxFiles, timeout), `commitMessage.*`, `templates.*`, etc.
+    - **Advanced** (3 params): `analysis.ignoreExtensions`, `commitMessage.taskIdPattern`, `subagents.model`
+    - **Files changed**:
+        - `lib/config.js:1-280` - Split into HARDCODED and defaults, added legacy format detection
+        - `templates/config.example.json` - New simplified format with examples
+        - `templates/config.advanced.example.json` - Advanced parameters with documentation
+        - `bin/claude-hooks:483-570` - Auto-migration during install
+    - **Impact**: Cleaner config files, sensible defaults work for 99% of users
+
+- **Automatic config migration** - Legacy configs auto-migrate during installation with backup
+    - **What changed**: `claude-hooks install` detects legacy format and migrates automatically
+    - **Migration process**: Backup to `.claude/config_old/`, extract allowed params, create v2.8.0 config
+    - **Preserved settings**: `github.pr.*`, `subagents.batchSize`, and advanced params (with warnings)
+    - **Files changed**:
+        - `bin/claude-hooks:510-530,1942-2115` - Auto-migration in install, new `migrate-config` command
+    - **Impact**: Seamless upgrade path, settings preserved, zero manual work
+
+- **Organized prompt templates** - All .md files moved to `.claude/prompts/` subdirectory
+    - **What changed**: Installation creates `.claude/prompts/` and places markdown templates there
+    - **Old location**: `.claude/CLAUDE_ANALYSIS_PROMPT.md`, `.claude/CLAUDE_PRE_COMMIT.md`, etc.
+    - **New location**: `.claude/prompts/CLAUDE_ANALYSIS_PROMPT.md`, `.claude/prompts/CLAUDE_PRE_COMMIT.md`, etc.
+    - **Auto-cleanup**: Old .md files in `.claude/` root are automatically removed during installation
+    - **Files changed**:
+        - `bin/claude-hooks:401-457` - Creates prompts directory, moves .md files, cleans up old files
+        - `lib/config.js:57` - Updated `templates.baseDir` to `.claude/prompts`
+    - **Impact**: Cleaner `.claude/` directory structure, prompts separated from config files
+
+- **Parallel analysis enabled by default** - Subagents now hardcoded to enabled (was opt-in)
+    - **What changed**: `subagents.enabled` moved from user config to hardcoded `true`
+    - **Why**: Faster analysis is universally beneficial, no reason to disable
+    - **Files changed**: `lib/config.js:52-54` - Hardcoded `enabled: true`, `model: 'haiku'`, `batchSize: 3`
+    - **Impact**: All users get faster analysis out-of-box (4x speedup on 3+ files)
+
+### ✨ Added
+
+- **Config example files** - Split documentation into simple and advanced examples
+    - `templates/config.example.json` - Minimal config (99% of users) with inline examples
+    - `templates/config.advanced.example.json` - Advanced parameters with full documentation
+    - Installation copies both to `.claude/config_example/` for reference
+    - **Impact**: Clear guidance for common use cases, power users can tinker safely
+
+- **Manual config migration command** - New `claude-hooks migrate-config` for manual upgrades
+    - Checks config version, creates backup in `.claude/config_old/`
+    - Extracts allowed parameters, warns about advanced params
+    - Shows diff preview before writing
+    - **Impact**: Users can migrate at their pace, review changes before applying
+
+### 🔧 Fixed
+
+- **Preset name now correctly displayed in hooks** - Fixed config loader not including preset name in final config
+    - **What was broken**: Hooks always showed "Default (General-purpose)" preset regardless of actual preset configured
+    - **Root cause**: Config loader extracted `presetName` but never added it to the final merged config object
+    - **Fix**: Add `preset` field to final config object after merge operations
+    - **Files changed**: `lib/config.js:181-184`
+    - **Impact**: Hooks now correctly display configured preset (e.g., "AI", "Backend", "Frontend")
+
+- **Example configs no longer clutter .claude/** - Example files only exist in `.claude/config_example/`
+    - **What was broken**: Installation copied `*example.json` to both `.claude/` and `.claude/config_example/`
+    - **Fix**: Filter `*example.json` during template copy, only place in `config_example/`
+    - **Files changed**: `bin/claude-hooks:410-415,498-507`
+    - **Impact**: Cleaner `.claude/` directory without redundant example files
+
+### ⚠️ Breaking Changes
+
+- **Config format change** - Legacy config format (pre-v2.8.0) requires migration
+    - **Migration**: Automatic during `install`, or manual via `claude-hooks migrate-config`
+    - **Compatibility**: Legacy format still works with deprecation warning until v3.0.0
+    - **Action required**: None (auto-migrates), but consider running `migrate-config` to see diff
+
+- **Template location change** - .md files moved from `.claude/` to `.claude/prompts/`
+    - **Migration**: Automatic during `install --force`
+    - **Custom templates**: If you customized templates, move them to `.claude/prompts/` manually
+    - **Impact**: Low - most users don't customize, system checks both locations
+
+- **Hardcoded parameters** - 21 parameters no longer user-configurable in .claude/config.json
+    - **Removed from user config**: `analysis.*` (except ignoreExtensions), `commitMessage.*` (except taskIdPattern), `templates.*`, `output.*`, `system.*`, `git.*`, `subagents.enabled`, `subagents.model` (except in advanced config)
+    - **Rationale**: Sensible defaults work for everyone, reduces configuration complexity
+    - **Override**: Advanced params available in `config.advanced.example.json` (use with caution)
+
+## [2.7.2] - 2025-12-23
+
+### ✨ Added
+
+- **Retry logic for PR commands** - Added automatic retry for `create-pr` and `analyze-diff` commands (#49)
+    - **What changed**: Both commands now use `executeClaudeWithRetry()` with exponential backoff (2s, 4s, 8s delays)
+    - **Impact**: PR creation and diff analysis now automatically recover from transient Claude API errors
+    - **Files changed**:
+        - `lib/utils/claude-client.js:676-745,846` - Created reusable `withRetry()` wrapper and `executeClaudeWithRetry()` export
+        - `bin/claude-hooks:11,972,1234` - Updated create-pr and analyze-diff to use retry logic
+
+### 🐛 Fixed
+
+- **Windows WSL timeout** - Increased WSL availability check from 3s to 15s to handle system load (#49)
+    - `lib/config.js:78` - Made configurable via `config.system.wslCheckTimeout`
+    - `lib/utils/claude-client.js:107` - Uses config value for WSL check
+- **Duplicate task ID logging** - Removed redundant log in prepare-commit-msg (#49)
+    - `lib/hooks/prepare-commit-msg.js:191-193` - Removed duplicate logger.info call
+
+### 🎯 Improved
+
+- **Error diagnostics** - Added timing information to all error contexts (#49)
+    - `lib/utils/claude-client.js:248-340` - Added `elapsedTime`, `timeoutValue`, `retryAttempt` to errors
+    - `lib/utils/claude-diagnostics.js:118-143,187-344` - Created `formatTimingInfo()` helper, updated all error formatters
+
+## [2.7.1] - 2025-12-22
+
+### 🐛 Fixed
+
+- **Improved reliability with automatic retry logic** - Fixed intermittent "Execution error" failures from Claude API
+    - **What was broken**: Claude CLI occasionally returned "Execution error" (15 chars) with exit code 0, causing commits to fail ~50% of the time
+    - **Root cause**: Claude API rate limiting or temporary backend issues returned error text instead of valid JSON, but was treated as success due to exit code 0
+    - **Fix**: Added detection for "Execution error" responses and automatic retry logic with 2-second delay
+    - **Files changed**:
+        - `lib/utils/claude-diagnostics.js:22-29,47-57,122-170,307-310` - Added EXECUTION_ERROR type detection and formatting
+        - `lib/utils/claude-client.js:24,246-270,620-679` - Check for error even with exit code 0, added retry logic
+    - **Impact**: Significantly improved reliability - transient API errors now automatically retry once, reducing failure rate
+    - **User experience**: Clear error messages explain the issue, automatic retry happens transparently with "⏳ Retrying..." message
+
+### 🎯 User Experience
+
+- **Before**: Commits failed ~50% of the time with cryptic "No valid JSON found" error, requiring manual retries
+- **After**: System automatically detects and retries recoverable errors, with helpful messages explaining what's happening
+- **Error messages**: Now include specific guidance for "Execution error" (likely rate limiting, try haiku model, commit fewer files)
+
+## [2.7.0] - 2025-12-19
+
+### 🎨 Changed
+
+- **Simplified code analysis output format** - Replaced fake SonarQube metrics with issue count summary (#47)
+    - **What changed**: Removed BLOCKER/CRITICAL/MAJOR/MINOR severity labels and A-E reliability/security/maintainability ratings
+    - **Why**: Metrics were Claude's opinion presented as facts, causing confusion and false sense of precision
+    - **New format**: Simple summary "X issue(s) found across Y file(s)" or "✅ No issues found!"
+    - **Files changed**:
+        - `lib/hooks/pre-commit.js:67-100` - Replaced metrics display with issue count summary
+        - `templates/CLAUDE_PRE_COMMIT_SONAR.md` → `templates/CLAUDE_PRE_COMMIT.md` (renamed)
+        - `templates/CLAUDE_ANALYSIS_PROMPT_SONAR.md` → `templates/CLAUDE_ANALYSIS_PROMPT.md` (renamed)
+        - `lib/config.js:58-59` - Updated template paths to remove SONAR suffix
+        - `bin/claude-hooks:387-407` - Installer now removes old SONAR template files
+    - **Impact**: Cleaner output focused on actual issues, not fake quality scores
+
+- **Added false-positive prevention guidance** - Pre-commit hook now avoids reporting improvements as issues (#47)
+    - **What was broken**: Hook reported routine improvements (better formatting, added docs) as CODE_SMELL issues
+    - **Root cause**: Prompts lacked explicit guidance to distinguish problems from improvements
+    - **Fix**: Added clear instructions to only report actual bugs, security issues, or quality degradations
+    - **New guidance in templates**:
+        - "Only report actual problems, bugs, security issues, or code quality concerns"
+        - "Do NOT report improvements, positive changes, or routine maintenance as issues"
+        - "It is perfectly acceptable to find ZERO issues - this is a positive outcome"
+        - "When in doubt, err on the side of NOT reporting it"
+    - **Files changed**:
+        - `templates/CLAUDE_PRE_COMMIT.md` - Added false-positive prevention section at top
+        - `templates/CLAUDE_ANALYSIS_PROMPT.md` - Updated instructions before JSON schema
+    - **Compatibility**: Existing configurations continue to work, but users get fewer false positives
+
+### 🔧 Fixed
+
+- **Pre-commit hook no longer reports improvements as issues** - Documentation additions and formatting improvements now correctly pass analysis (#47)
+
+### ⚠️ Breaking Changes (Minor)
+
+- **Template file renames**: `CLAUDE_PRE_COMMIT_SONAR.md` → `CLAUDE_PRE_COMMIT.md`, `CLAUDE_ANALYSIS_PROMPT_SONAR.md` → `CLAUDE_ANALYSIS_PROMPT.md`
+    - **Migration**: Installer automatically removes old files and installs new ones on `claude-hooks install --force`
+    - **Impact**: Low - most users don't customize these files. Custom templates need manual rename.
+
 ## [2.6.3]
 
 ### 🐛 Fixed

package/README.md

@@ -1,6 +1,10 @@
 # Pre-commit Hook con Claude CLI
 
-🚀 **Transforma tu flujo de desarrollo con IA**: análisis de código instantáneo, mensajes de commit automáticos y generación de PRs perfectas. Claude revisa tu código antes de cada commit, detecta issues críticos al estilo SonarQube, y genera toda la documentación que necesitas. ¿Lo mejor? Se ejecuta localmente sin contaminar tu CI/CD.
+🚀 **Transforma tu flujo de desarrollo con IA**: análisis de código instantáneo, mensajes de commit automáticos y generación de PRs perfectas. Claude revisa tu código antes de cada commit, detecta issues críticos con análisis estructurado, y genera toda la documentación que necesitas. ¿Lo mejor? Se ejecuta localmente sin contaminar tu CI/CD.
+
+## ✨ Novedad v2.7.1 - Improved Reliability
+
+**Nuevo v2.7.1**: Sistema de reintentos automáticos para errores transitorios de Claude API. Cuando Claude devuelve "Execution error" (típicamente por rate limiting), el sistema ahora reintenta automáticamente después de 2 segundos.
 
 ## ✨ Novedad v2.0.0 - Ahora Cross-Platform
 
@@ -22,6 +26,7 @@
 - 🚀 **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
+- ♻️ **Reintentos automáticos**: Recuperación automática de errores transitorios de API (v2.7.1+)
 
 ## 📋 CHEATSHEET
 
@@ -159,16 +164,20 @@ export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_tu_token_aqui"
 ### 4. Configurar reviewers y labels (opcional)
 
 ```bash
-# Ver templates/config.github.example.json para formato completo
+# Ver .claude/config_example/ para más ejemplos
 cat > .claude/config.json << 'EOF'
 {
-  "github": {
-    "pr": {
-      "defaultBase": "develop",
-      "reviewers": ["tu-usuario-github", "teammate"],
-      "labelRules": {
-        "backend": ["backend", "java"],
-        "frontend": ["frontend", "react"]
+  "version": "2.8.0",
+  "preset": "backend",
+  "overrides": {
+    "github": {
+      "pr": {
+        "defaultBase": "develop",
+        "reviewers": ["tu-usuario-github", "teammate"],
+        "labelRules": {
+          "backend": ["backend", "java"],
+          "frontend": ["frontend", "react"]
+        }
       }
     }
   }
@@ -201,40 +210,41 @@ Ver `templates/config.github.example.json` para configuración avanzada (reviewe
 
 Toda idea es bienvenida, aunque parezca espantosa. Si hay bugs, incluirlos también. Dónde? en https://github.com/mscope-S-L/git-hooks/issues/new.
 
-### 🔧 Configuración Avanzada (v2.2.0+)
+### 🔧 Configuración Avanzada (v2.8.0+)
 
 ```bash
-# Configuración vía .claude/config.json
+# Configuración vía .claude/config.json (v2.8.0+)
 .claude/
-├── 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)
+├── config.json                      # Configuración principal (formato simplificado)
+├── config_example/                  # Ejemplos de configuración
+│   ├── config.example.json          # Configuración básica
+│   └── config.advanced.example.json # Parámetros avanzados
+└── prompts/                         # Templates de prompts (v2.8.0+)
+    ├── CLAUDE_PRE_COMMIT.md         # Criterios de análisis
+    └── CLAUDE_ANALYSIS_PROMPT.md    # Template del prompt
+
+# Ejemplo de config.json v2.8.0 (formato simplificado)
 cat > .claude/config.json << 'EOF'
 {
+  "version": "2.8.0",
   "preset": "backend",
-  "analysis": {
-    "maxFileSize": 1000000,
-    "maxFiles": 12,
-    "timeout": 150000
-  },
-  "commitMessage": {
-    "autoKeyword": "auto",
-    "timeout": 180000,
-    "taskIdPattern": "([A-Z]{1,3}[-\\s]\\d{3,5})"
-  },
-  "subagents": {
-    "enabled": true,
-    "model": "haiku",
-    "batchSize": 3
-  },
-  "system": {
-    "debug": true
+  "overrides": {
+    "github": {
+      "pr": {
+        "defaultBase": "main",
+        "reviewers": ["tech-lead"]
+      }
+    },
+    "subagents": {
+      "batchSize": 2
+    }
   }
 }
 EOF
 
+# Para configuración avanzada, consultar:
+# .claude/config_example/config.advanced.example.json
+
 # Personalizar patrón de task-id
 # Default: 1-3 letras + separador + 3-5 dígitos
 # Ejemplos válidos: ABC-12345, IX-123, DE 4567
@@ -352,31 +362,40 @@ git commit -m "fix: resolver issues"
 ### ⚡ Tips y Trucos
 
 1. **Mensaje automático**: Usa `"auto"` como mensaje para que Claude lo genere con task-id automático
-2. **Task-ID pattern**: Default 1-3 letras + separador + 3-5 dígitos (ABC-12345, IX-123). Configurable en `.claude/config.json` → `commitMessage.taskIdPattern`
+2. **Task-ID pattern**: Default 1-3 letras + separador + 3-5 dígitos (ABC-12345, IX-123). Configurable en `.claude/config_example/config.advanced.example.json`
 3. **Skip auth**: Usa `--skip-auth` en CI/CD o desarrollo local
 4. **Force install**: Usa `--force` para reinstalar sin confirmación
-5. **Debug**: Activa con `claude-hooks --debug true` o en `.claude/config.json`: `{"system": {"debug": true}}`
-6. **Archivos grandes**: Se omiten automáticamente archivos > 1MB
-7. **Límite de archivos**: Máximo 30 archivos por commit (configurable)
+5. **Debug**: Activa con `claude-hooks --debug true`
+6. **Archivos grandes**: Se omiten automáticamente archivos > 1MB (hardcoded desde v2.8.0)
+7. **Límite de archivos**: Máximo 20 archivos por commit (hardcoded desde v2.8.0)
+
+### 🚀 Parallel Analysis (Enabled by default desde v2.8.0)
+
+**When analyzing 3+ files**, parallel execution runs multiple Claude CLI processes simultaneously for faster analysis.
 
-### 🚀 Parallel Analysis (v2.2.0+)
+**Configuración automática (hardcoded):**
+- ✅ **Enabled**: `true` (siempre activo)
+- ⚡ **Model**: `haiku` (rápido y económico)
+- 📦 **BatchSize**: `3` files per batch (puede overridearse)
 
-**When analyzing 3+ files**, parallel execution runs multiple Claude CLI processes simultaneously for faster analysis:
+**Customizar batch size (opcional):**
 
 ```bash
-# Configure in .claude/config.json
+# En .claude/config.json v2.8.0
 {
-  "subagents": {
-    "enabled": true,
-    "model": "haiku",
-    "batchSize": 2
+  "version": "2.8.0",
+  "preset": "backend",
+  "overrides": {
+    "subagents": {
+      "batchSize": 2
+    }
   }
 }
 ```
 
-**Model options:**
+**Model options (solo en config avanzado):**
 
-- `haiku` - Fast & cheap (default, recommended)
+- `haiku` - Fast & cheap (default)
 - `sonnet` - Balanced quality/speed
 - `opus` - Maximum quality (slower)
 
@@ -417,9 +436,9 @@ git commit -m "fix: resolver issues"
 
 **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
+- `.claude/config.json` - Configuración principal (v2.8.0+)
+- `.claude/prompts/CLAUDE_PRE_COMMIT.md` - Criterios (backend/frontend/data/db)
+- `.claude/prompts/CLAUDE_ANALYSIS_PROMPT.md` - Template del prompt
 
 **Crear o modificar presets personalizados:**
 
@@ -434,7 +453,7 @@ cat templates/CUSTOMIZATION_GUIDE.md
 **Ejemplo:**
 
 ```bash
-vim .claude/CLAUDE_PRE_COMMIT_SONAR.md  # Agregar reglas API REST/Spring Boot
+vim .claude/prompts/CLAUDE_PRE_COMMIT.md  # Agregar reglas API REST/Spring Boot
 ```
 
 ## 🔧 Configuración Previa Importante
@@ -501,8 +520,8 @@ 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_PRE_COMMIT.md` - Criterios de evaluación de calidad
+    - `CLAUDE_ANALYSIS_PROMPT.md` - Template de prompt para análisis
     - `CLAUDE_RESOLUTION_PROMPT.md` - Template para prompt de resolución AI
 
 ### Actualización automática de .gitignore
@@ -532,8 +551,8 @@ Si no existe un `.gitignore`, se creará uno nuevo. Si ya existe, las entradas s
     - Omite archivos mayores a 1MB
     - Límite de 30 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`
+    - Usa template de prompt desde `.claude/prompts/CLAUDE_ANALYSIS_PROMPT*.md`
+    - Lee las pautas desde `.claude/prompts/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**
@@ -621,11 +640,11 @@ En `lib/hooks/prepare-commit-msg.js`:
 
 ### Pautas de Evaluación
 
-- **`CLAUDE_PRE_COMMIT_SONAR.md`** - Criterios para modo SonarQube
+- **`CLAUDE_PRE_COMMIT.md`** - Criterios de evaluación de calidad
 
 ### Templates de Prompts
 
-- **`CLAUDE_ANALYSIS_PROMPT_SONAR.md`** - Estructura del prompt SonarQube
+- **`CLAUDE_ANALYSIS_PROMPT.md`** - Estructura del prompt de análisis
 - **`CLAUDE_RESOLUTION_PROMPT.md`** - Template para generar prompts de resolución
 
 Todos estos archivos son personalizables y específicos de tu proyecto. Puedes:
@@ -672,8 +691,8 @@ claude-git-hooks/
 │   ├── pre-commit                            # Bash wrapper (llama a lib/hooks/pre-commit.js)
 │   ├── prepare-commit-msg                    # Bash wrapper (llama a lib/hooks/prepare-commit-msg.js)
 │   ├── check-version.sh                      # Script de verificación de versión
-│   ├── CLAUDE_PRE_COMMIT_SONAR.md            # Pautas SonarQube
-│   ├── CLAUDE_ANALYSIS_PROMPT_SONAR.md       # Template de prompt para análisis
+│   ├── CLAUDE_PRE_COMMIT.md            # Criterios de evaluación
+│   ├── CLAUDE_ANALYSIS_PROMPT.md       # Template de prompt para análisis
 │   ├── CLAUDE_RESOLUTION_PROMPT.md           # Template para resolución de issues
 │   ├── ANALYZE_DIFF.md                       # Template para análisis de diff (PR metadata)
 │   ├── CREATE_GITHUB_PR.md                   # Template para creación de PR