claude-git-hooks 2.6.2 → 2.7.1

package/CHANGELOG.md

@@ -5,6 +5,88 @@ 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.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
+
+- **WSL timeout error misreporting** - Fixed misleading error message when WSL times out under system load (#49)
+    - **What was broken**: ETIMEDOUT errors during WSL Claude verification were misreported as "Claude CLI not found in WSL"
+    - **Root cause**: Catch block in WSL verification treated all errors identically, including transient ETIMEDOUT timeouts from system load
+    - **Fix**: Added error type differentiation to distinguish between ETIMEDOUT (transient timeout), ENOENT (missing CLI), and generic WSL errors
+    - **Files changed**:
+        - `lib/utils/claude-client.js:109-146` - Enhanced error detection with three distinct error paths
+    - **Impact**:
+        - ETIMEDOUT: Clear message "Timeout connecting to WSL - system under heavy load" with suggestion to retry or skip
+        - ENOENT: Preserved original "Claude CLI not found in WSL" with installation instructions
+        - Generic: New fallback "Failed to verify Claude CLI in WSL" with WSL diagnostic suggestions
+    - **Compatibility**: No breaking changes, improves error accuracy for Windows WSL users
+
+### 🎯 User Experience
+
+- **Before**: Users experiencing system load timeouts saw misleading "Claude CLI not found" error and tried reinstalling unnecessarily
+- **After**: Clear distinction between transient timeouts (retry/skip) and missing CLI (install) with actionable suggestions for each
+- **Debug**: All error cases now include context with platform, wslPath, error type, and specific remediation steps
+
 ## [2.6.2] - 2025-12-12
 
 ### 🐛 Fixed
@@ -118,11 +200,13 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 ### 🔧 Technical Details
 
 **DEP0190 Explanation**:
+
 - **What**: Node.js 24 deprecates `spawn(cmd, args, { shell: true })`
 - **Why**: Args are not escaped, just concatenated → shell injection risk
 - **Fix**: Use absolute executable paths, remove `shell: true`
 
 **Files Changed**:
+
 - `lib/utils/claude-client.js` - Command resolution and spawn call
 - `lib/utils/which-command.js` - NEW utility for path resolution
 - `package.json` - Platform documentation
@@ -131,6 +215,7 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 - `MIGRATION_NODE24.md` - NEW migration guide
 
 **Backward Compatibility**:
+
 - ✅ Works on Node 16.9.0+ (unchanged)
 - ✅ Works on Node 18 (unchanged)
 - ✅ Works on Node 20 (unchanged)
@@ -149,6 +234,7 @@ y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.h
 ### 📋 Migration Checklist
 
 For users on Node 24:
+
 - [x] Update to claude-git-hooks 2.6.0
 - [x] Verify no DEP0190 warnings: `claude-hooks install`
 - [x] Test pre-commit hook: `git commit`

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
 
@@ -207,8 +212,8 @@ Toda idea es bienvenida, aunque parezca espantosa. Si hay bugs, incluirlos tambi
 # Configuración vía .claude/config.json
 .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)
+├── CLAUDE_PRE_COMMIT.md      # Personalizar criterios (override)
+└── CLAUDE_ANALYSIS_PROMPT.md # Modificar prompt (override)
 
 # Ejemplo de config.json (todas las opciones son opcionales)
 cat > .claude/config.json << 'EOF'
@@ -418,8 +423,8 @@ 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/CLAUDE_PRE_COMMIT.md` - Criterios (backend/frontend/data/db)
+- `.claude/CLAUDE_ANALYSIS_PROMPT.md` - Template del prompt
 
 **Crear o modificar presets personalizados:**
 
@@ -434,7 +439,7 @@ cat templates/CUSTOMIZATION_GUIDE.md
 **Ejemplo:**
 
 ```bash
-vim .claude/CLAUDE_PRE_COMMIT_SONAR.md  # Agregar reglas API REST/Spring Boot
+vim .claude/CLAUDE_PRE_COMMIT.md  # Agregar reglas API REST/Spring Boot
 ```
 
 ## 🔧 Configuración Previa Importante
@@ -501,8 +506,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
@@ -621,11 +626,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 +677,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

package/bin/claude-hooks

@@ -384,6 +384,20 @@ async function install(args) {
     success('.claude directory created');
   }
 
+  // Remove old SONAR template files if they exist (migration from v2.6.x to v2.7.0+)
+  const oldSonarFiles = [
+    'CLAUDE_PRE_COMMIT_SONAR.md',
+    'CLAUDE_ANALYSIS_PROMPT_SONAR.md'
+  ];
+
+  oldSonarFiles.forEach(oldFile => {
+    const oldPath = path.join(claudeDir, oldFile);
+    if (fs.existsSync(oldPath)) {
+      fs.unlinkSync(oldPath);
+      info(`Removed old template: ${oldFile}`);
+    }
+  });
+
   // Copy ALL template files (.md and .json) to .claude directory
   const templateFiles = fs.readdirSync(templatesPath)
     .filter(file => {
@@ -1455,7 +1469,7 @@ function status() {
 
   // Check guidelines files
   console.log('\nGuidelines files:');
-  const guidelines = ['CLAUDE_PRE_COMMIT_SONAR.md'];
+  const guidelines = ['CLAUDE_PRE_COMMIT.md'];
   guidelines.forEach(guideline => {
     const claudePath = path.join('.claude', guideline);
     if (fs.existsSync(claudePath)) {
@@ -1683,7 +1697,7 @@ Customization:
   Override prompts by copying to .claude/:
     cp templates/COMMIT_MESSAGE.md .claude/
     cp templates/ANALYZE_DIFF.md .claude/
-    cp templates/CLAUDE_PRE_COMMIT_SONAR.md .claude/
+    cp templates/CLAUDE_PRE_COMMIT.md .claude/
     # Edit as needed - system uses .claude/ version if exists
 
 More information: https://github.com/pablorovito/claude-git-hooks

package/lib/config.js

@@ -55,8 +55,8 @@ const defaults = {
     // Template paths
     templates: {
         baseDir: '.claude',                                    // Base directory for all templates
-        analysis: 'CLAUDE_ANALYSIS_PROMPT_SONAR.md',          // Pre-commit analysis prompt
-        guidelines: 'CLAUDE_PRE_COMMIT_SONAR.md',             // Analysis guidelines
+        analysis: 'CLAUDE_ANALYSIS_PROMPT.md',                // Pre-commit analysis prompt
+        guidelines: 'CLAUDE_PRE_COMMIT.md',                   // Analysis guidelines
         commitMessage: 'COMMIT_MESSAGE.md',                   // Commit message prompt
         analyzeDiff: 'ANALYZE_DIFF.md',                       // PR analysis prompt
         resolution: 'CLAUDE_RESOLUTION_PROMPT.md',            // Issue resolution prompt

package/lib/hooks/pre-commit.js

@@ -9,7 +9,7 @@
  * 2. Build analysis prompt with file diffs
  * 3. Send to Claude CLI for analysis
  * 4. Parse JSON response
- * 5. Display SonarQube-style results
+ * 5. Display structured analysis results
  * 6. Generate resolution prompt if issues found
  * 7. Block commit if quality gate fails
  *
@@ -52,8 +52,8 @@ import { getConfig } from '../config.js';
  */
 
 /**
- * Displays SonarQube-style analysis results
- * Why: Provides structured, visual feedback about code quality
+ * Displays structured analysis results
+ * Why: Provides clear, visual feedback about code quality
  *
  * @param {Object} result - Analysis result from Claude
  */
@@ -73,19 +73,16 @@ const displayResults = (result) => {
     }
     console.log();
 
-    // Metrics
-    if (result.metrics && typeof result.metrics === 'object') {
-        console.log('📊 METRICS');
-        console.log(`├─ Reliability: ${result.metrics.reliability || '?'}`);
-        console.log(`├─ Security: ${result.metrics.security || '?'}`);
-        console.log(`├─ Maintainability: ${result.metrics.maintainability || '?'}`);
-        console.log(`├─ Coverage: ${result.metrics.coverage || '?'}%`);
-        console.log(`├─ Duplications: ${result.metrics.duplications || '?'}%`);
-        console.log(`└─ Complexity: ${result.metrics.complexity || '?'}`);
-        console.log();
+    // Issues Summary - Simple count
+    if (Array.isArray(result.details) && result.details.length > 0) {
+        const fileCount = new Set(result.details.map(i => i.file)).size;
+        console.log(`📊 ${result.details.length} issue(s) found across ${fileCount} file(s)`);
+    } else {
+        console.log('✅ No issues found!');
     }
+    console.log();
 
-    // Issues Summary
+    // Issues Breakdown (severity counts)
     if (result.issues && typeof result.issues === 'object') {
         console.log('📋 ISSUES SUMMARY');
 

package/lib/utils/claude-client.js

@@ -21,7 +21,7 @@ import path from 'path';
 import os from 'os';
 import logger from './logger.js';
 import config from '../config.js';
-import { detectClaudeError, formatClaudeError, ClaudeErrorType } from './claude-diagnostics.js';
+import { detectClaudeError, formatClaudeError, ClaudeErrorType, isRecoverableError } from './claude-diagnostics.js';
 import { which } from './which-command.js';
 
 /**
@@ -107,11 +107,40 @@ const getClaudeCommand = () => {
                 logger.debug('claude-client - getClaudeCommand', 'Using WSL Claude CLI', { wslPath });
                 return { command: wslPath, args: ['claude'] };
             } catch (wslError) {
-                throw new ClaudeClientError('Claude CLI not found in WSL', {
+                // Differentiate error types for accurate user feedback
+                const errorMsg = wslError.message || '';
+
+                // Timeout: Transient system load issue
+                if (errorMsg.includes('ETIMEDOUT')) {
+                    throw new ClaudeClientError('Timeout connecting to WSL - system under heavy load', {
+                        context: {
+                            platform: 'Windows',
+                            wslPath,
+                            error: 'ETIMEDOUT',
+                            suggestion: 'System is busy. Wait a moment and try again, or skip analysis: git commit --no-verify'
+                        }
+                    });
+                }
+
+                // Not found: Claude CLI missing in WSL
+                if (errorMsg.includes('ENOENT') || errorMsg.includes('command not found')) {
+                    throw new ClaudeClientError('Claude CLI not found in WSL', {
+                        context: {
+                            platform: 'Windows',
+                            wslPath,
+                            error: 'ENOENT',
+                            suggestion: 'Install Claude in WSL: wsl -e bash -c "npm install -g @anthropic-ai/claude-cli"'
+                        }
+                    });
+                }
+
+                // Generic error: Other WSL issues
+                throw new ClaudeClientError('Failed to verify Claude CLI in WSL', {
                     context: {
                         platform: 'Windows',
                         wslPath,
-                        wslError: wslError.message
+                        error: errorMsg,
+                        suggestion: 'Check WSL is functioning: wsl --version, or skip analysis: git commit --no-verify'
                     }
                 });
             }
@@ -214,6 +243,33 @@ const executeClaude = (prompt, { timeout = 120000, allowedTools = [] } = {}) =>
     claude.on('close', (code) => {
         const duration = Date.now() - startTime;
 
+        // Check for "Execution error" even when exit code is 0
+        // Why: Claude CLI sometimes returns "Execution error" with exit code 0
+        // This occurs during API rate limiting or temporary backend issues
+        // IMPORTANT: Only check for EXACT match to avoid false positives
+        if (stdout.trim() === 'Execution error') {
+            const errorInfo = detectClaudeError(stdout, stderr, code);
+
+            logger.error(
+                'claude-client - executeClaude',
+                `Claude CLI returned execution error (exit ${code})`,
+                new ClaudeClientError(`Claude CLI error: ${errorInfo.type}`, {
+                    output: { stdout, stderr },
+                    context: { exitCode: code, duration, errorType: errorInfo.type }
+                })
+            );
+
+            // Show formatted error to user
+            const formattedError = formatClaudeError(errorInfo);
+            console.error(`\n${  formattedError  }\n`);
+
+            reject(new ClaudeClientError(`Claude CLI error: ${errorInfo.type}`, {
+                output: { stdout, stderr },
+                context: { exitCode: code, duration, errorInfo }
+            }));
+            return;
+        }
+
         if (code === 0) {
             logger.debug(
                 'claude-client - executeClaude',
@@ -562,11 +618,16 @@ const saveDebugResponse = async (prompt, response, filename = config.output.debu
  * @returns {Promise<Object>} Parsed analysis result
  * @throws {ClaudeClientError} If analysis fails
  */
-const analyzeCode = async (prompt, { timeout = 120000, saveDebug = config.system.debug } = {}) => {
+const analyzeCode = async (prompt, { timeout = 120000, saveDebug = config.system.debug, retryCount = 0 } = {}) => {
+    const maxRetries = 3; // Retry up to 3 times for recoverable errors
+    const baseRetryDelay = 2000; // Base delay: 2 seconds
+    // Exponential backoff: 2s, 4s, 8s
+    const retryDelay = baseRetryDelay * Math.pow(2, retryCount);
+
     logger.debug(
         'claude-client - analyzeCode',
         'Starting code analysis',
-        { promptLength: prompt.length, timeout, saveDebug }
+        { promptLength: prompt.length, timeout, saveDebug, retryCount }
     );
 
     try {
@@ -594,6 +655,45 @@ const analyzeCode = async (prompt, { timeout = 120000, saveDebug = config.system
         return result;
 
     } catch (error) {
+        // Check if error is recoverable and we haven't exceeded retry limit
+        const hasContext = !!error.context;
+        const hasErrorInfo = !!error.context?.errorInfo;
+        const isRecoverable = hasErrorInfo ? isRecoverableError(error.context.errorInfo) : false;
+        const canRetry = retryCount < maxRetries;
+
+        logger.debug(
+            'claude-client - analyzeCode',
+            'Retry check',
+            {
+                retryCount,
+                maxRetries,
+                hasContext,
+                hasErrorInfo,
+                isRecoverable,
+                canRetry,
+                errorType: error.context?.errorInfo?.type,
+                errorName: error.name
+            }
+        );
+
+        const shouldRetry = canRetry && hasContext && hasErrorInfo && isRecoverable;
+
+        if (shouldRetry) {
+            logger.debug(
+                'claude-client - analyzeCode',
+                `Recoverable error detected, retrying in ${retryDelay}ms (attempt ${retryCount + 1}/${maxRetries})`,
+                { errorType: error.context.errorInfo.type }
+            );
+
+            console.log(`\n⏳ Retrying in ${retryDelay / 1000} seconds due to ${error.context.errorInfo.type}...\n`);
+
+            // Wait before retry
+            await new Promise(resolve => setTimeout(resolve, retryDelay));
+
+            // Retry with incremented count
+            return analyzeCode(prompt, { timeout, saveDebug, retryCount: retryCount + 1 });
+        }
+
         logger.error('claude-client - analyzeCode', 'Code analysis failed', error);
         throw error;
     }

package/lib/utils/claude-diagnostics.js

@@ -25,6 +25,7 @@ export const ClaudeErrorType = {
     TIMEOUT: 'TIMEOUT',
     NETWORK: 'NETWORK',
     INVALID_RESPONSE: 'INVALID_RESPONSE',
+    EXECUTION_ERROR: 'EXECUTION_ERROR',
     GENERIC: 'GENERIC'
 };
 
@@ -44,7 +45,20 @@ export const ClaudeErrorType = {
  * @returns {Object|null} Error information or null if no specific error detected
  */
 export const detectClaudeError = (stdout = '', stderr = '', exitCode = 1) => {
-    // 1. Rate limit detection
+    // 1. Execution error detection (Claude CLI internal error)
+    // This occurs when Claude API returns an error instead of valid response
+    // Often caused by rate limiting, API errors, or temporary backend issues
+    // IMPORTANT: Only match EXACT "Execution error" response, not partial matches
+    const trimmedStdout = stdout.trim();
+    if (trimmedStdout === 'Execution error') {
+        return {
+            type: ClaudeErrorType.EXECUTION_ERROR,
+            exitCode,
+            stdout: stdout.substring(0, 100)
+        };
+    }
+
+    // 2. Rate limit detection
     const rateLimitMatch = stdout.match(/Claude AI usage limit reached\|(\d+)/);
     if (rateLimitMatch) {
         const resetTimestamp = parseInt(rateLimitMatch[1], 10);
@@ -61,7 +75,7 @@ export const detectClaudeError = (stdout = '', stderr = '', exitCode = 1) => {
         };
     }
 
-    // 2. Authentication failure detection
+    // 3. Authentication failure detection
     if (stdout.includes('not authenticated') || stderr.includes('not authenticated') ||
         stdout.includes('authentication failed') || stderr.includes('authentication failed')) {
         return {
@@ -70,7 +84,7 @@ export const detectClaudeError = (stdout = '', stderr = '', exitCode = 1) => {
         };
     }
 
-    // 3. Network errors
+    // 4. Network errors
     if (stderr.includes('ENOTFOUND') || stderr.includes('ECONNREFUSED') ||
         stderr.includes('network error') || stderr.includes('connection refused')) {
         return {
@@ -79,7 +93,7 @@ export const detectClaudeError = (stdout = '', stderr = '', exitCode = 1) => {
         };
     }
 
-    // 4. Invalid response (JSON parsing errors)
+    // 5. Invalid response (JSON parsing errors)
     if (stdout.includes('SyntaxError') || stdout.includes('Unexpected token')) {
         return {
             type: ClaudeErrorType.INVALID_RESPONSE,
@@ -87,7 +101,7 @@ export const detectClaudeError = (stdout = '', stderr = '', exitCode = 1) => {
         };
     }
 
-    // 5. Generic error
+    // 6. Generic error
     return {
         type: ClaudeErrorType.GENERIC,
         exitCode,
@@ -107,6 +121,9 @@ export const formatClaudeError = (errorInfo) => {
     const lines = [];
 
     switch (errorInfo.type) {
+        case ClaudeErrorType.EXECUTION_ERROR:
+            return formatExecutionError(errorInfo);
+
         case ClaudeErrorType.RATE_LIMIT:
             return formatRateLimitError(errorInfo);
 
@@ -125,6 +142,35 @@ export const formatClaudeError = (errorInfo) => {
     }
 };
 
+/**
+ * Format execution error
+ */
+const formatExecutionError = ({ exitCode, stdout }) => {
+    const lines = [];
+
+    lines.push('❌ Claude CLI execution error');
+    lines.push('');
+    lines.push('Claude returned "Execution error" instead of valid response.');
+    lines.push('');
+    lines.push('Common causes:');
+    lines.push('  1. API rate limiting (burst limits)');
+    lines.push('  2. Temporary Claude API backend issues');
+    lines.push('  3. Request/response size limits exceeded');
+    lines.push('');
+    lines.push('Solutions:');
+    lines.push('  1. Wait 10-30 seconds and try again');
+    lines.push('  2. Reduce prompt size by committing fewer files at once');
+    lines.push('  3. Switch to haiku model (faster, higher rate limits):');
+    lines.push('     Edit .claude/config.json:');
+    lines.push('     { "subagents": { "model": "haiku" } }');
+    lines.push('  4. Skip analysis for now:');
+    lines.push('     git commit --no-verify -m "your message"');
+    lines.push('');
+    lines.push('The hook will automatically retry once after 2 seconds.');
+
+    return lines.join('\n');
+};
+
 /**
  * Format rate limit error
  */
@@ -261,6 +307,7 @@ const formatGenericError = ({ exitCode, stdout, stderr }) => {
  * @returns {boolean} True if error might resolve with retry
  */
 export const isRecoverableError = (errorInfo) => {
-    return errorInfo.type === ClaudeErrorType.RATE_LIMIT ||
+    return errorInfo.type === ClaudeErrorType.EXECUTION_ERROR ||
+           errorInfo.type === ClaudeErrorType.RATE_LIMIT ||
            errorInfo.type === ClaudeErrorType.NETWORK;
 };

package/lib/utils/prompt-builder.js

@@ -215,8 +215,8 @@ const formatFileSection = ({ path, diff, content, isNew }) => {
  * }
  */
 const buildAnalysisPrompt = async ({
-    templateName = 'CLAUDE_ANALYSIS_PROMPT_SONAR.md',
-    guidelinesName = 'CLAUDE_PRE_COMMIT_SONAR.md',
+    templateName = 'CLAUDE_ANALYSIS_PROMPT.md',
+    guidelinesName = 'CLAUDE_PRE_COMMIT.md',
     files = [],
     metadata = {},
     subagentConfig = null

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-git-hooks",
-    "version": "2.6.2",
+    "version": "2.7.1",
     "description": "Git hooks with Claude CLI for code analysis and automatic commit messages",
     "type": "module",
     "bin": {

package/templates/{CLAUDE_ANALYSIS_PROMPT_SONAR.md → CLAUDE_ANALYSIS_PROMPT.md}

@@ -1,4 +1,4 @@
-ROLE:SeniorCodeReviewer,SonarQube-experienced
+ROLE:SeniorCodeReviewer,CodeQualityExpert
 TASK:Analyze code->JSON only
 CRITICAL:NoTextOutsideJSON,ValidJSON
 
@@ -44,6 +44,7 @@ OUTPUT_SCHEMA:
 ```
 
 RULES:
+- **FALSE_POSITIVE_PREVENTION**: Only report actual problems. Do not report improvements, positive changes, or routine maintenance as issues. Zero issues is a valid and positive outcome.
 - blockingIssues=ALWAYS_ARRAY_OF_OBJECTS(never_strings)
 - blockingIssues=ALL(details.severity∈{BLOCKER,CRITICAL})
 - Each_blockingIssue_MUST_have:description,file,line,method,severity

package/templates/{CLAUDE_PRE_COMMIT_SONAR.md → CLAUDE_PRE_COMMIT.md}

@@ -1,4 +1,13 @@
-# SONARQUBE_EVAL_CRITERIA
+# CODE_QUALITY_EVALUATION_CRITERIA
+
+## FALSE_POSITIVE_PREVENTION
+
+**IMPORTANT**: 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 about whether something is an issue, err on the side of NOT reporting it
+- Focus on what could break, harm security, or degrade quality - not what could be "better"
 
 ## EXCEPTIONS_AND_ALLOWED_PATTERNS
 ### Spring Framework Patterns (NOT blocking issues)

package/templates/CUSTOMIZATION_GUIDE.md

@@ -149,7 +149,7 @@ A preset is a **self-contained package** that customizes claude-hooks for a spec
                          │
 ┌────────────────────────▼────────────────────────────────────┐
 │ 8. RESPONSE PROCESSED                                       │
-│    - JSON format (SonarQube-style)                          │
+│    - JSON format with structured results                    │
 │    - Quality gate: PASSED/FAILED                            │
 │    - Issues by severity: blocker, critical, major, minor    │
 │    - Commit proceeds or blocked                             │
@@ -382,7 +382,7 @@ Perform a comprehensive code quality analysis focusing on these areas:
 **Template**:
 
 ````markdown
-# SonarQube-Style Evaluation Criteria
+# Code Quality Evaluation Criteria
 
 ## Severity Levels
 
@@ -599,7 +599,7 @@ Please generate the following files:
 - This preset will be installed at: `templates/presets/{preset-name}/`
 - It should follow the same structure as existing presets in `templates/presets/backend/`
 - Users will select it with: `claude-hooks --set-preset {preset-name}`
-- The preset must output JSON in SonarQube format
+- The preset must output JSON with structured analysis results
 
 **Format**: Return each file's content as a separate code block with clear file headers.
 ```

package/templates/config.example.json

@@ -18,8 +18,8 @@
     },
     "templates": {
         "baseDir": ".claude",
-        "analysis": "CLAUDE_ANALYSIS_PROMPT_SONAR.md",
-        "guidelines": "CLAUDE_PRE_COMMIT_SONAR.md",
+        "analysis": "CLAUDE_ANALYSIS_PROMPT.md",
+        "guidelines": "CLAUDE_PRE_COMMIT.md",
         "commitMessage": "COMMIT_MESSAGE.md",
         "analyzeDiff": "ANALYZE_DIFF.md",
         "resolution": "CLAUDE_RESOLUTION_PROMPT.md",

package/templates/presets/ai/ANALYSIS_PROMPT.md

@@ -83,7 +83,7 @@ Perform a comprehensive code quality analysis focusing on these areas:
 
 ## Output Format
 
-Respond with a valid JSON following the SonarQube format:
+Respond with a valid JSON following the structured JSON format:
 
 ```json
 {

package/templates/presets/backend/ANALYSIS_PROMPT.md

@@ -45,7 +45,7 @@ Perform a comprehensive code quality analysis focusing on these areas:
 
 ## Output Format
 
-Respond with a valid JSON following the SonarQube format:
+Respond with a valid JSON following the structured JSON format:
 
 ```json
 {

package/templates/presets/database/ANALYSIS_PROMPT.md

@@ -64,7 +64,7 @@ Perform a comprehensive database code quality analysis focusing on these areas:
 
 ## Output Format
 
-Respond with a valid JSON following the SonarQube format:
+Respond with a valid JSON following the structured JSON format:
 
 ```json
 {

package/templates/presets/frontend/ANALYSIS_PROMPT.md

@@ -56,7 +56,7 @@ Perform a comprehensive code quality analysis focusing on these areas:
 
 ## Output Format
 
-Respond with a valid JSON following the SonarQube format:
+Respond with a valid JSON following the structured JSON format:
 
 ```json
 {

package/templates/presets/fullstack/ANALYSIS_PROMPT.md

@@ -57,7 +57,7 @@ Check these consistency issues first:
 
 ## Output Format
 
-Respond with a valid JSON following the SonarQube format:
+Respond with a valid JSON following the structured JSON format:
 
 ```json
 {

package/templates/shared/ANALYSIS_PROMPT.md

@@ -46,7 +46,7 @@ Evaluate the code changes across these dimensions:
 
 ## Output Format
 
-Respond with a valid JSON following the SonarQube format:
+Respond with a valid JSON following the structured JSON format:
 
 ```json
 {