claude-git-hooks 2.8.0 → 2.9.1

package/CHANGELOG.md

@@ -5,6 +5,56 @@ 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.9.1] - 2025-12-30
+
+### 🐛 Fixed
+
+- **Template path mismatch after v2.8.0 migration** - Fixed critical bug where templates were not found after config migration (#51)
+    - **What was broken**: After v2.8.0 moved templates from `.claude/` to `.claude/prompts/`, the code still looked in the old location
+    - **Root cause**: `prompt-builder.js` and `resolution-prompt.js` had hardcoded `.claude/` paths instead of `.claude/prompts/`
+    - **Symptom**: `ENOENT: no such file or directory` errors for `CLAUDE_ANALYSIS_PROMPT.md` and `CLAUDE_RESOLUTION_PROMPT.md`
+    - **Fix**: Updated default paths in template loading functions to `.claude/prompts/`
+    - **Files changed**:
+        - `lib/utils/prompt-builder.js:45,133,223,234-235,244` - Updated `loadTemplate`, `loadPrompt`, `buildAnalysisPrompt` defaults
+        - `lib/utils/resolution-prompt.js:183` - Updated `generateResolutionPrompt` template path
+    - **Impact**: Pre-commit analysis and resolution prompt generation now work correctly after v2.8.0+ installation
+
+### 🎯 User Experience
+
+- **Before**: Users upgrading from v2.6.x to v2.8.0+ experienced "Template not found" errors even after successful installation
+- **After**: Templates are found in correct `.claude/prompts/` directory as intended by v2.8.0 changes
+
+## [2.9.0] - 2025-12-26
+
+### ✨ Added
+
+- **Local telemetry system with per-retry tracking** - Enabled by default for debugging JSON parsing failures (#50)
+    - **What it does**: Tracks JSON parsing failures and successes with full context, recording EVERY retry attempt individually
+    - **Key features**:
+        - **Granular tracking**: Records each retry attempt separately (not just final result)
+        - **Unique IDs**: Each event has unique ID (timestamp-counter-random) for deduplication
+        - **Success flag**: Boolean indicating whether attempt succeeded (true) or failed (false)
+        - **Retry metadata**: `retryAttempt` (0-3) and `totalRetries` (max configured)
+        - **Error types**: Tracks EXECUTION_ERROR, JSON_PARSE_ERROR, etc.
+        - **Hook coverage**: pre-commit, prepare-commit-msg, analyze-diff, create-pr
+    - **Privacy-first**: Local-only (`.claude/telemetry/`), no data leaves user's machine, no external transmission
+    - **Storage**: JSON lines format with automatic rotation (keeps last 30 days)
+    - **CLI commands**:
+        - `claude-hooks telemetry show` - Display statistics (failure rate, failures by batch size/model/hook, retry patterns)
+        - `claude-hooks telemetry clear` - Reset telemetry data
+    - **Enabled by default**: To disable, add `"system": { "telemetry": false }` to `.claude/config.json`
+    - **Files added**:
+        - `lib/utils/telemetry.js` - Telemetry collection with ID generation, retry tracking, and statistics
+    - **Files changed**:
+        - `lib/utils/claude-client.js:678-780,788-798` - Modified withRetry() to record telemetry on each attempt
+        - `lib/utils/claude-client.js:609-618,845-856` - Removed duplicate telemetry recordings
+        - `lib/hooks/pre-commit.js` - Pass telemetry context for analysis
+        - `lib/hooks/prepare-commit-msg.js` - Pass telemetry context for commit messages
+        - `lib/config.js` - Add telemetry config option (default: true)
+        - `bin/claude-hooks:1076-1091,1354-1366` - Add telemetry context to analyze-diff and create-pr
+        - `bin/claude-hooks` - Add telemetry CLI commands
+    - **Impact**: Enables diagnosis of retry patterns, identifies which retry attempts succeed, tracks transient vs persistent errors, helps optimize batch sizes and models
+
 ## [2.8.0] - 2025-12-24
 
 ### 🎨 Changed

package/README.md

@@ -65,6 +65,12 @@ claude-hooks --debug true
 
 # Ver estado de debug
 claude-hooks --debug status
+
+# Ver estadísticas de telemetría (v2.9.0+, habilitada por defecto)
+claude-hooks telemetry show
+
+# Limpiar datos de telemetría (v2.9.0+)
+claude-hooks telemetry clear
 ```
 
 ### 📦 Instalación y Gestión

package/bin/claude-hooks

@@ -16,6 +16,7 @@ import { getOrPromptTaskId, formatWithTaskId } from '../lib/utils/task-id.js';
 import { createPullRequest, getReviewersForFiles, parseGitHubRepo, setupGitHubMcp, getGitHubMcpStatus } from '../lib/utils/github-client.js';
 import { showPRPreview, promptConfirmation, promptMenu, showSuccess, showError, showInfo, showWarning, showSpinner, promptEditField } from '../lib/utils/interactive-ui.js';
 import { setupGitHubMCP } from '../lib/utils/mcp-setup.js';
+import { displayStatistics as showTelemetryStats, clearTelemetry as clearTelemetryData } from '../lib/utils/telemetry.js';
 import logger from '../lib/utils/logger.js';
 
 // Why: ES6 modules don't have __dirname, need to recreate it
@@ -1072,9 +1073,22 @@ async function analyzeDiff(args) {
   info('Sending to Claude for analysis...');
   const startTime = Date.now();
 
+  // Prepare telemetry context
+  const filesChanged = diffFiles.split('\n').length;
+  const telemetryContext = {
+    fileCount: filesChanged,
+    batchSize: filesChanged,
+    totalBatches: 1,
+    model: subagentModel || 'sonnet',
+    hook: 'analyze-diff'
+  };
+
   try {
-    // Use cross-platform executeClaudeWithRetry from claude-client.js
-    const response = await executeClaudeWithRetry(prompt, { timeout: 180000 }); // 3 minutes for diff analysis
+    // Use cross-platform executeClaudeWithRetry from claude-client.js with telemetry
+    const response = await executeClaudeWithRetry(prompt, {
+      timeout: 180000, // 3 minutes for diff analysis
+      telemetryContext
+    });
 
     // Extract JSON from response using claude-client utility
     const result = extractJSON(response);
@@ -1336,7 +1350,20 @@ async function createPr(args) {
 
     showInfo('Generating PR metadata with Claude...');
     logger.debug('create-pr', 'Calling Claude with prompt', { promptLength: prompt.length });
-    const response = await executeClaudeWithRetry(prompt, { timeout: 180000 });
+
+    // Prepare telemetry context for create-pr
+    const telemetryContext = {
+      fileCount: filesArray.length,
+      batchSize: filesArray.length,
+      totalBatches: 1,
+      model: 'sonnet', // create-pr always uses main model
+      hook: 'create-pr'
+    };
+
+    const response = await executeClaudeWithRetry(prompt, {
+      timeout: 180000,
+      telemetryContext
+    });
     logger.debug('create-pr', 'Claude response received', { responseLength: response.length });
 
     const analysisResult = extractJSON(response);
@@ -1703,6 +1730,7 @@ Commands:
   presets              List all available presets
   --set-preset <name>  Set the active preset
   preset current       Show the current active preset
+  telemetry [action]   Telemetry management (show or clear)
   --debug <value>      Set debug mode (true, false, or status)
   --version, -v        Show the current version
   help                 Show this help
@@ -1725,6 +1753,8 @@ Examples:
   claude-hooks presets              # List available presets
   claude-hooks --set-preset backend # Set backend preset
   claude-hooks preset current       # Show current preset
+  claude-hooks telemetry show       # Show telemetry statistics
+  claude-hooks telemetry clear      # Clear telemetry data
   claude-hooks --debug true         # Enable debug mode
   claude-hooks --debug status       # Check debug status
 
@@ -2171,6 +2201,41 @@ async function setDebug(value) {
 }
 
 // Main
+/**
+ * Show telemetry statistics
+ * Why: Help users understand JSON parsing patterns and batch performance
+ */
+async function showTelemetry() {
+  await showTelemetryStats();
+}
+
+/**
+ * Clear telemetry data
+ * Why: Allow users to reset telemetry
+ */
+async function clearTelemetry() {
+  const config = await getConfig();
+
+  if (!config.system?.telemetry && config.system?.telemetry !== undefined) {
+    console.log('\n⚠️  Telemetry is currently disabled.\n');
+    console.log('To re-enable (default), remove or set to true in .claude/config.json:');
+    console.log('{');
+    console.log('  "system": {');
+    console.log('    "telemetry": true');
+    console.log('  }');
+    console.log('}\n');
+    return;
+  }
+
+  const confirmed = await promptConfirmation('Are you sure you want to clear all telemetry data?');
+  if (confirmed) {
+    await clearTelemetryData();
+    success('Telemetry data cleared successfully');
+  } else {
+    info('Telemetry data was not cleared');
+  }
+}
+
 async function main() {
   const args = process.argv.slice(2);
   const command = args[0];
@@ -2223,6 +2288,16 @@ async function main() {
     case 'migrate-config':
       await migrateConfig();
       break;
+    case 'telemetry':
+      // Handle subcommands: telemetry show, telemetry clear
+      if (args[1] === 'show' || args[1] === undefined) {
+        await showTelemetry();
+      } else if (args[1] === 'clear') {
+        await clearTelemetry();
+      } else {
+        error(`Unknown telemetry subcommand: ${args[1]}`);
+      }
+      break;
     case '--debug':
       await setDebug(args[1]);
       break;

package/lib/config.js

@@ -72,6 +72,7 @@ const HARDCODED = {
     },
     system: {
         debug: false,                      // Controlled by --debug flag
+        telemetry: true,                   // Opt-out telemetry for debugging (local only, set to false to disable)
         wslCheckTimeout: 15000,            // System behavior
     },
     git: {

package/lib/hooks/pre-commit.js

@@ -364,10 +364,19 @@ const main = async () => {
                 })
             );
 
+            // Build telemetry context
+            const telemetryContext = {
+                fileCount: filesData.length,
+                batchSize: batchSize,
+                model: subagentModel,
+                hook: 'pre-commit'
+            };
+
             // Execute in parallel
             const results = await analyzeCodeParallel(prompts, {
                 timeout: config.analysis.timeout,
-                saveDebug: false  // Don't save debug for individual batches
+                saveDebug: false,  // Don't save debug for individual batches
+                telemetryContext
             });
 
             // Simple consolidation: merge all results
@@ -403,9 +412,19 @@ const main = async () => {
                 { promptLength: prompt.length }
             );
 
+            // Build telemetry context for single execution
+            const telemetryContext = {
+                fileCount: filesData.length,
+                batchSize: filesData.length,  // Single batch = all files
+                totalBatches: 1,
+                model: config.subagents?.model || 'haiku',
+                hook: 'pre-commit'
+            };
+
             result = await analyzeCode(prompt, {
                 timeout: config.analysis.timeout,
-                saveDebug: config.system.debug
+                saveDebug: config.system.debug,
+                telemetryContext
             });
         }
 

package/lib/hooks/prepare-commit-msg.js

@@ -265,9 +265,21 @@ const main = async () => {
         // Generate message with Claude
         logger.info('Sending to Claude...');
 
+        // Build telemetry context
+        const telemetryContext = {
+            fileCount: filesData.length,
+            batchSize: config.subagents?.batchSize || 3,
+            totalBatches: subagentsEnabled && filesData.length >= 3
+                ? Math.ceil(filesData.length / (config.subagents?.batchSize || 3))
+                : 1,
+            model: subagentModel,
+            hook: 'prepare-commit-msg'
+        };
+
         const response = await analyzeCode(prompt, {
             timeout: config.commitMessage.timeout,
-            saveDebug: config.system.debug
+            saveDebug: config.system.debug,
+            telemetryContext
         });
 
         logger.debug(

package/lib/utils/claude-client.js

@@ -23,6 +23,7 @@ import logger from './logger.js';
 import config from '../config.js';
 import { detectClaudeError, formatClaudeError, ClaudeErrorType, isRecoverableError } from './claude-diagnostics.js';
 import { which } from './which-command.js';
+import { recordJsonParseFailure, recordBatchSuccess, rotateTelemetry } from './telemetry.js';
 
 /**
  * Custom error for Claude client failures
@@ -526,10 +527,11 @@ const executeClaudeInteractive = (prompt, { timeout = 300000 } = {}) => new Prom
  * Why: Claude may include markdown formatting or explanatory text around JSON
  *
  * @param {string} response - Raw response from Claude
+ * @param {Object} telemetryContext - Context for telemetry recording (optional)
  * @returns {Object} Parsed JSON object
  * @throws {ClaudeClientError} If no valid JSON found
  */
-const extractJSON = (response) => {
+const extractJSON = (response, telemetryContext = {}) => {
     logger.debug(
         'claude-client - extractJSON',
         'Extracting JSON from response',
@@ -594,16 +596,24 @@ const extractJSON = (response) => {
     }
 
     // No valid JSON found
+    const responsePreview = response.substring(0, 500);
+
     logger.error(
         'claude-client - extractJSON',
         'No valid JSON found in response',
         new ClaudeClientError('No valid JSON in response', {
-            output: response.substring(0, 500) // First 500 chars for debugging
+            output: responsePreview
         })
     );
 
+    // Telemetry is now recorded by withRetry wrapper
     throw new ClaudeClientError('No valid JSON found in Claude response', {
-        output: response.substring(0, 500)
+        context: {
+            response: response,
+            errorInfo: {
+                type: 'JSON_PARSE_ERROR'
+            }
+        }
     });
 };
 
@@ -661,8 +671,8 @@ const saveDebugResponse = async (prompt, response, filename = config.output.debu
 };
 
 /**
- * Wraps an async function with retry logic for recoverable errors
- * Why: Reusable retry logic for Claude CLI operations
+ * Wraps an async function with retry logic for recoverable errors and telemetry tracking
+ * Why: Reusable retry logic for Claude CLI operations with per-attempt telemetry
  *
  * @param {Function} fn - Async function to execute with retry
  * @param {Object} options - Retry options
@@ -670,15 +680,50 @@ const saveDebugResponse = async (prompt, response, filename = config.output.debu
  * @param {number} options.baseRetryDelay - Base delay in ms (default: 2000)
  * @param {number} options.retryCount - Current retry attempt (internal, default: 0)
  * @param {string} options.operationName - Name for logging (default: 'operation')
+ * @param {Object} options.telemetryContext - Context for telemetry recording (optional)
  * @returns {Promise<any>} Result from fn
  * @throws {Error} If fn fails after all retries
  */
-const withRetry = async (fn, { maxRetries = 3, baseRetryDelay = 2000, retryCount = 0, operationName = 'operation' } = {}) => {
+const withRetry = async (fn, { maxRetries = 3, baseRetryDelay = 2000, retryCount = 0, operationName = 'operation', telemetryContext = null } = {}) => {
     const retryDelay = baseRetryDelay * Math.pow(2, retryCount);
+    const startTime = Date.now();
 
     try {
-        return await fn();
+        const result = await fn();
+
+        // Record success telemetry if context provided
+        if (telemetryContext) {
+            const duration = Date.now() - startTime;
+            await recordBatchSuccess({
+                ...telemetryContext,
+                duration,
+                retryAttempt: retryCount,
+                totalRetries: maxRetries
+            }).catch(err => {
+                logger.debug('claude-client - withRetry', 'Failed to record success telemetry', err);
+            });
+        }
+
+        return result;
     } catch (error) {
+        // Record failure telemetry if context provided (before retry decision)
+        if (telemetryContext) {
+            const errorType = error.context?.errorInfo?.type || error.name || 'UNKNOWN_ERROR';
+            const errorMessage = error.message || 'Unknown error';
+
+            await recordJsonParseFailure({
+                ...telemetryContext,
+                errorType,
+                errorMessage,
+                retryAttempt: retryCount,
+                totalRetries: maxRetries,
+                responseLength: error.context?.response?.length || 0,
+                responsePreview: error.context?.response?.substring(0, 100) || ''
+            }).catch(err => {
+                logger.debug('claude-client - withRetry', 'Failed to record failure telemetry', err);
+            });
+        }
+
         // Check if error is recoverable and we haven't exceeded retry limit
         const hasContext = !!error.context;
         const hasErrorInfo = !!error.context?.errorInfo;
@@ -714,8 +759,8 @@ const withRetry = async (fn, { maxRetries = 3, baseRetryDelay = 2000, retryCount
             // Wait before retry
             await new Promise(resolve => setTimeout(resolve, retryDelay));
 
-            // Retry with incremented count
-            return withRetry(fn, { maxRetries, baseRetryDelay, retryCount: retryCount + 1, operationName });
+            // Retry with incremented count and same telemetry context
+            return withRetry(fn, { maxRetries, baseRetryDelay, retryCount: retryCount + 1, operationName, telemetryContext });
         }
 
         // Add retry attempt to error context if not already present
@@ -730,17 +775,25 @@ const withRetry = async (fn, { maxRetries = 3, baseRetryDelay = 2000, retryCount
 };
 
 /**
- * Executes Claude CLI with retry logic
- * Why: Provides retry capability for executeClaude calls
+ * Executes Claude CLI with retry logic and telemetry tracking
+ * Why: Provides retry capability for executeClaude calls with per-attempt telemetry
  *
  * @param {string} prompt - Prompt text
- * @param {Object} options - Execution options (timeout, allowedTools)
+ * @param {Object} options - Execution options
+ * @param {number} options.timeout - Timeout in milliseconds
+ * @param {Array<string>} options.allowedTools - Allowed tools for Claude
+ * @param {Object} options.telemetryContext - Context for telemetry (fileCount, hook, etc.)
  * @returns {Promise<string>} Claude's response
  */
 const executeClaudeWithRetry = async (prompt, options = {}) => {
+    const { telemetryContext = {}, ...executeOptions } = options;
+
     return withRetry(
-        () => executeClaude(prompt, options),
-        { operationName: 'executeClaude' }
+        () => executeClaude(prompt, executeOptions),
+        {
+            operationName: 'executeClaude',
+            telemetryContext: telemetryContext
+        }
     );
 };
 
@@ -752,17 +805,25 @@ const executeClaudeWithRetry = async (prompt, options = {}) => {
  * @param {Object} options - Analysis options
  * @param {number} options.timeout - Timeout in milliseconds
  * @param {boolean} options.saveDebug - Save response to debug file (default: from config)
+ * @param {Object} options.telemetryContext - Context for telemetry (fileCount, batchSize, etc.)
  * @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, telemetryContext = {} } = {}) => {
+    const startTime = Date.now();
+
     logger.debug(
         'claude-client - analyzeCode',
         'Starting code analysis',
         { promptLength: prompt.length, timeout, saveDebug }
     );
 
-    // Use withRetry to wrap the entire analysis flow
+    // Rotate telemetry files periodically
+    rotateTelemetry().catch(err => {
+        logger.debug('claude-client - analyzeCode', 'Failed to rotate telemetry', err);
+    });
+
+    // Use withRetry to wrap the entire analysis flow (with telemetry tracking)
     return withRetry(
         async () => {
             // Execute Claude CLI
@@ -774,7 +835,9 @@ const analyzeCode = async (prompt, { timeout = 120000, saveDebug = config.system
             }
 
             // Extract and parse JSON
-            const result = extractJSON(response);
+            const result = extractJSON(response, telemetryContext);
+
+            const duration = Date.now() - startTime;
 
             logger.debug(
                 'claude-client - analyzeCode',
@@ -782,13 +845,21 @@ const analyzeCode = async (prompt, { timeout = 120000, saveDebug = config.system
                 {
                     hasApproved: 'approved' in result,
                     hasQualityGate: 'QUALITY_GATE' in result,
-                    blockingIssuesCount: result.blockingIssues?.length ?? 0
+                    blockingIssuesCount: result.blockingIssues?.length ?? 0,
+                    duration
                 }
             );
 
+            // Telemetry is now recorded by withRetry wrapper
             return result;
         },
-        { operationName: 'analyzeCode' }
+        {
+            operationName: 'analyzeCode',
+            telemetryContext: {
+                responseLength: 0, // Will be updated in withRetry
+                ...telemetryContext
+            }
+        }
     );
 };
 
@@ -810,6 +881,7 @@ const chunkArray = (array, size) => {
  * Runs multiple analyzeCode calls in parallel
  * @param {Array<string>} prompts - Array of prompts to analyze
  * @param {Object} options - Same options as analyzeCode
+ * @param {Object} options.telemetryContext - Base telemetry context (will be augmented per batch)
  * @returns {Promise<Array<Object>>} Array of results
  */
 const analyzeCodeParallel = async (prompts, options = {}) => {
@@ -824,7 +896,18 @@ const analyzeCodeParallel = async (prompts, options = {}) => {
     const promises = prompts.map((prompt, index) => {
         console.log(`  ⚡ Launching batch ${index + 1}/${prompts.length}...`);
         logger.debug('claude-client - analyzeCodeParallel', `Starting batch ${index + 1}`);
-        return analyzeCode(prompt, options);
+
+        // Augment telemetry context with batch info
+        const batchTelemetryContext = {
+            ...(options.telemetryContext || {}),
+            batchIndex: index,
+            totalBatches: prompts.length
+        };
+
+        return analyzeCode(prompt, {
+            ...options,
+            telemetryContext: batchTelemetryContext
+        });
     });
 
     console.log('  ⏳ Waiting for all batches to complete...\n');

package/lib/utils/prompt-builder.js

@@ -38,11 +38,11 @@ class PromptBuilderError extends Error {
  * Why absolute path: Ensures templates are found regardless of cwd (cross-platform)
  *
  * @param {string} templateName - Name of template file
- * @param {string} baseDir - Base directory (default: try .claude, fallback to templates)
+ * @param {string} baseDir - Base directory (default: .claude/prompts, fallback to templates)
  * @returns {Promise<string>} Template content
  * @throws {PromptBuilderError} If template not found
  */
-const loadTemplate = async (templateName, baseDir = '.claude') => {
+const loadTemplate = async (templateName, baseDir = '.claude/prompts') => {
     // Why: Use repo root for absolute path (works on Windows/PowerShell/Git Bash)
     const repoRoot = getRepoRoot();
     let templatePath = path.join(repoRoot, baseDir, templateName);
@@ -118,7 +118,7 @@ const replaceTemplate = (template, variables) => {
  *
  * @param {string} templateName - Name of template file
  * @param {Object} variables - Variables to replace in template
- * @param {string} baseDir - Base directory (default: .claude)
+ * @param {string} baseDir - Base directory (default: .claude/prompts)
  * @returns {Promise<string>} Prompt with replaced variables
  * @throws {PromptBuilderError} If template not found
  *
@@ -130,7 +130,7 @@ const replaceTemplate = (template, variables) => {
  *   DELETIONS: 5
  * });
  */
-const loadPrompt = async (templateName, variables = {}, baseDir = '.claude') => {
+const loadPrompt = async (templateName, variables = {}, baseDir = '.claude/prompts') => {
     logger.debug(
         'prompt-builder - loadPrompt',
         'Loading prompt with variables',
@@ -219,19 +219,20 @@ const buildAnalysisPrompt = async ({
     guidelinesName = 'CLAUDE_PRE_COMMIT.md',
     files = [],
     metadata = {},
-    subagentConfig = null
+    subagentConfig = null,
+    baseDir = '.claude/prompts'
 } = {}) => {
     logger.debug(
         'prompt-builder - buildAnalysisPrompt',
         'Building analysis prompt',
-        { templateName, guidelinesName, fileCount: files.length, subagentsEnabled: subagentConfig?.enabled }
+        { templateName, guidelinesName, fileCount: files.length, subagentsEnabled: subagentConfig?.enabled, baseDir }
     );
 
     try {
         // Load template and guidelines
         const [template, guidelines] = await Promise.all([
-            loadTemplate(templateName),
-            loadTemplate(guidelinesName)
+            loadTemplate(templateName, baseDir),
+            loadTemplate(guidelinesName, baseDir)
         ]);
 
         // Start with template
@@ -240,7 +241,7 @@ const buildAnalysisPrompt = async ({
         // Add subagent instruction if enabled and 3+ files
         if (subagentConfig?.enabled && files.length >= 3) {
             try {
-                const subagentInstruction = await loadTemplate('SUBAGENT_INSTRUCTION.md');
+                const subagentInstruction = await loadTemplate('SUBAGENT_INSTRUCTION.md', baseDir);
                 const subagentVariables = {
                     BATCH_SIZE: subagentConfig.batchSize || 3,
                     MODEL: subagentConfig.model || 'haiku'

package/lib/utils/resolution-prompt.js

@@ -171,7 +171,7 @@ ${content}
  * @param {Array<Object>} analysisResult.blockingIssues - Array of blocking issues
  * @param {Object} options - Generation options
  * @param {string} options.outputPath - Output file path (default: 'claude_resolution_prompt.md')
- * @param {string} options.templatePath - Template path (default: '.claude/CLAUDE_RESOLUTION_PROMPT.md')
+ * @param {string} options.templatePath - Template path (default: '.claude/prompts/CLAUDE_RESOLUTION_PROMPT.md')
  * @param {number} options.fileCount - Number of files analyzed
  * @returns {Promise<string>} Path to generated resolution prompt
  * @throws {ResolutionPromptError} If generation fails
@@ -180,7 +180,7 @@ const generateResolutionPrompt = async (
     analysisResult,
     {
         outputPath = null,
-        templatePath = '.claude/CLAUDE_RESOLUTION_PROMPT.md',
+        templatePath = '.claude/prompts/CLAUDE_RESOLUTION_PROMPT.md',
         fileCount = 0
     } = {}
 ) => {

package/lib/utils/telemetry.js

@@ -0,0 +1,507 @@
+/**
+ * File: telemetry.js
+ * Purpose: Local telemetry collection for debugging and optimization
+ *
+ * Design principles:
+ * - OPT-IN ONLY: Requires explicit config.system.telemetry = true
+ * - LOCAL ONLY: Data never leaves user's machine
+ * - PRIVACY-FIRST: No PII, no code content, just metrics
+ * - STRUCTURED LOGS: JSON lines format for easy analysis
+ * - AUTO-ROTATION: Limits file size to prevent unbounded growth
+ *
+ * Key responsibilities:
+ * - Track JSON parsing failures with context
+ * - Record batch analysis metrics
+ * - Provide local statistics via CLI
+ * - Auto-rotate log files
+ *
+ * Dependencies:
+ * - fs/promises: File operations
+ * - logger: Debug logging
+ */
+
+import fs from 'fs/promises';
+import fsSync from 'fs';
+import path from 'path';
+import logger from './logger.js';
+import config from '../config.js';
+
+/**
+ * Telemetry event structure
+ * @typedef {Object} TelemetryEvent
+ * @property {string} id - Unique event ID (timestamp-counter-random)
+ * @property {string} timestamp - ISO timestamp
+ * @property {string} type - Event type
+ * @property {boolean} success - Whether the operation succeeded
+ * @property {number} retryAttempt - Current retry attempt (0-based)
+ * @property {number} totalRetries - Total retry attempts configured
+ * @property {Object} data - Event data
+ */
+
+/**
+ * Counter for generating unique IDs within the same millisecond
+ */
+let eventCounter = 0;
+
+/**
+ * Generate unique event ID
+ * Why: Ensure each telemetry event has a unique identifier
+ * Format: timestamp-counter-random (e.g., 1703612345678-001-a3f)
+ *
+ * @returns {string} Unique event ID
+ */
+const generateEventId = () => {
+    const timestamp = Date.now();
+    const counter = String(eventCounter++).padStart(3, '0');
+    const random = Math.random().toString(36).substring(2, 5);
+
+    // Reset counter if it exceeds 999
+    if (eventCounter > 999) {
+        eventCounter = 0;
+    }
+
+    return `${timestamp}-${counter}-${random}`;
+};
+
+/**
+ * Get telemetry directory path
+ * Why: Store in .claude/telemetry (gitignored) per-repo
+ *
+ * @returns {string} Telemetry directory path
+ */
+const getTelemetryDir = () => {
+    return path.join(process.cwd(), '.claude', 'telemetry');
+};
+
+/**
+ * Get current telemetry log file path
+ * Why: Use date-based naming for natural rotation
+ *
+ * @returns {string} Current log file path
+ */
+const getCurrentLogFile = () => {
+    const date = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
+    return path.join(getTelemetryDir(), `telemetry-${date}.jsonl`);
+};
+
+/**
+ * Check if telemetry is enabled
+ * Why: Enabled by default, users must explicitly disable
+ *
+ * @returns {boolean} True if telemetry is enabled (default: true)
+ */
+const isTelemetryEnabled = () => {
+    // Enabled by default - only disabled if explicitly set to false
+    return config.system?.telemetry !== false;
+};
+
+/**
+ * Ensure telemetry directory exists
+ * Why: Create on first use
+ */
+const ensureTelemetryDir = async () => {
+    try {
+        const dir = getTelemetryDir();
+        await fs.mkdir(dir, { recursive: true });
+    } catch (error) {
+        logger.debug('telemetry - ensureTelemetryDir', 'Failed to create directory', error);
+    }
+};
+
+/**
+ * Append event to telemetry log
+ * Why: JSON lines format for efficient append and parsing
+ *
+ * @param {TelemetryEvent} event - Event to log
+ */
+const appendEvent = async (event) => {
+    try {
+        const logFile = getCurrentLogFile();
+        const line = JSON.stringify(event) + '\n';
+
+        // Append to file (create if doesn't exist)
+        await fs.appendFile(logFile, line, 'utf8');
+
+        logger.debug('telemetry - appendEvent', `Event logged: ${event.type}`);
+    } catch (error) {
+        // Don't fail on telemetry errors
+        logger.debug('telemetry - appendEvent', 'Failed to append event', error);
+    }
+};
+
+/**
+ * Record a telemetry event
+ * Why: Centralized event recording with opt-in check
+ *
+ * @param {string} eventType - Type of event
+ * @param {Object} eventData - Event-specific data (no PII, no code content)
+ * @param {Object} metadata - Event metadata (success, retryAttempt, totalRetries)
+ */
+export const recordEvent = async (eventType, eventData = {}, metadata = {}) => {
+    // Check opt-in
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+
+    try {
+        // Ensure directory exists
+        await ensureTelemetryDir();
+
+        // Create event with all metadata
+        const event = {
+            id: generateEventId(),
+            timestamp: new Date().toISOString(),
+            type: eventType,
+            success: metadata.success ?? false,
+            retryAttempt: metadata.retryAttempt ?? 0,
+            totalRetries: metadata.totalRetries ?? 0,
+            data: eventData
+        };
+
+        // Append to log
+        await appendEvent(event);
+    } catch (error) {
+        // Don't fail on telemetry errors
+        logger.debug('telemetry - recordEvent', 'Failed to record event', error);
+    }
+};
+
+/**
+ * Record JSON parsing failure or API execution error
+ * Why: Track failures with batch context and retry information for debugging
+ *
+ * @param {Object} options - Failure context
+ * @param {number} options.retryAttempt - Current retry attempt (0-based)
+ * @param {number} options.totalRetries - Total retry attempts configured
+ */
+export const recordJsonParseFailure = async (options) => {
+    await recordEvent(
+        'json_parse_failure',
+        {
+            fileCount: options.fileCount || 0,
+            batchSize: options.batchSize || 0,
+            batchIndex: options.batchIndex ?? -1,
+            totalBatches: options.totalBatches || 0,
+            model: options.model || 'unknown',
+            responseLength: options.responseLength || 0,
+            // Only include first 100 chars to avoid storing large responses
+            responsePreview: (options.responsePreview || '').substring(0, 100),
+            errorMessage: options.errorMessage || '',
+            errorType: options.errorType || 'unknown',
+            parallelMode: (options.totalBatches || 0) > 1,
+            hook: options.hook || 'unknown' // pre-commit, prepare-commit-msg, analyze-diff, create-pr
+        },
+        {
+            success: false,
+            retryAttempt: options.retryAttempt ?? 0,
+            totalRetries: options.totalRetries ?? 0
+        }
+    );
+};
+
+/**
+ * Record successful batch analysis
+ * Why: Track successes with retry information to compare against failures
+ *
+ * @param {Object} options - Success context
+ * @param {number} options.retryAttempt - Current retry attempt (0-based)
+ * @param {number} options.totalRetries - Total retry attempts configured
+ */
+export const recordBatchSuccess = async (options) => {
+    await recordEvent(
+        'batch_success',
+        {
+            fileCount: options.fileCount || 0,
+            batchSize: options.batchSize || 0,
+            batchIndex: options.batchIndex ?? -1,
+            totalBatches: options.totalBatches || 0,
+            model: options.model || 'unknown',
+            duration: options.duration || 0,
+            responseLength: options.responseLength || 0,
+            parallelMode: (options.totalBatches || 0) > 1,
+            hook: options.hook || 'unknown'
+        },
+        {
+            success: true,
+            retryAttempt: options.retryAttempt ?? 0,
+            totalRetries: options.totalRetries ?? 0
+        }
+    );
+};
+
+/**
+ * Read all telemetry events from log files
+ * Why: Aggregate data for statistics
+ *
+ * @param {number} maxDays - Maximum days to read (default: 7)
+ * @returns {Promise<Array<TelemetryEvent>>} Array of events
+ */
+const readTelemetryEvents = async (maxDays = 7) => {
+    try {
+        const dir = getTelemetryDir();
+        const files = await fs.readdir(dir);
+
+        // Filter to .jsonl files only
+        const logFiles = files.filter(f => f.endsWith('.jsonl'));
+
+        // Sort by date (newest first)
+        logFiles.sort().reverse();
+
+        // Limit to maxDays
+        const limitedFiles = logFiles.slice(0, maxDays);
+
+        // Read all events
+        const events = [];
+        for (const file of limitedFiles) {
+            const filePath = path.join(dir, file);
+            const content = await fs.readFile(filePath, 'utf8');
+
+            // Parse JSON lines
+            const lines = content.trim().split('\n');
+            for (const line of lines) {
+                if (line.trim()) {
+                    try {
+                        events.push(JSON.parse(line));
+                    } catch (parseError) {
+                        // Skip invalid lines
+                        logger.debug('telemetry - readTelemetryEvents', 'Invalid JSON line', parseError);
+                    }
+                }
+            }
+        }
+
+        return events;
+    } catch (error) {
+        logger.debug('telemetry - readTelemetryEvents', 'Failed to read events', error);
+        return [];
+    }
+};
+
+/**
+ * Get telemetry statistics
+ * Why: Provide insights for debugging and optimization
+ *
+ * @param {number} maxDays - Maximum days to analyze (default: 7)
+ * @returns {Promise<Object>} Statistics object
+ */
+export const getStatistics = async (maxDays = 7) => {
+    if (!isTelemetryEnabled()) {
+        return {
+            enabled: false,
+            message: 'Telemetry is disabled. To enable (default), remove or set "system.telemetry: true" in .claude/config.json'
+        };
+    }
+
+    try {
+        const events = await readTelemetryEvents(maxDays);
+
+        const stats = {
+            enabled: true,
+            period: `Last ${maxDays} days`,
+            totalEvents: events.length,
+            jsonParseFailures: 0,
+            batchSuccesses: 0,
+            failuresByBatchSize: {},
+            failuresByModel: {},
+            failuresByHook: {},
+            successesByHook: {},
+            avgFilesPerFailure: 0,
+            avgFilesPerSuccess: 0,
+            failureRate: 0
+        };
+
+        let totalFilesInFailures = 0;
+        let totalFilesInSuccesses = 0;
+
+        events.forEach(event => {
+            if (event.type === 'json_parse_failure') {
+                stats.jsonParseFailures++;
+                totalFilesInFailures += event.data.fileCount || 0;
+
+                // Group by batch size
+                const batchSize = event.data.batchSize || 0;
+                stats.failuresByBatchSize[batchSize] = (stats.failuresByBatchSize[batchSize] || 0) + 1;
+
+                // Group by model
+                const model = event.data.model || 'unknown';
+                stats.failuresByModel[model] = (stats.failuresByModel[model] || 0) + 1;
+
+                // Group by hook
+                const hook = event.data.hook || 'unknown';
+                stats.failuresByHook[hook] = (stats.failuresByHook[hook] || 0) + 1;
+
+            } else if (event.type === 'batch_success') {
+                stats.batchSuccesses++;
+                totalFilesInSuccesses += event.data.fileCount || 0;
+
+                // Group by hook
+                const hook = event.data.hook || 'unknown';
+                stats.successesByHook[hook] = (stats.successesByHook[hook] || 0) + 1;
+            }
+        });
+
+        // Calculate averages
+        if (stats.jsonParseFailures > 0) {
+            stats.avgFilesPerFailure = parseFloat((totalFilesInFailures / stats.jsonParseFailures).toFixed(2));
+        }
+        if (stats.batchSuccesses > 0) {
+            stats.avgFilesPerSuccess = parseFloat((totalFilesInSuccesses / stats.batchSuccesses).toFixed(2));
+        }
+
+        // Calculate failure rate
+        const totalAnalyses = stats.jsonParseFailures + stats.batchSuccesses;
+        if (totalAnalyses > 0) {
+            stats.failureRate = parseFloat((stats.jsonParseFailures / totalAnalyses * 100).toFixed(2));
+        }
+
+        return stats;
+    } catch (error) {
+        logger.debug('telemetry - getStatistics', 'Failed to calculate statistics', error);
+        return {
+            enabled: true,
+            error: 'Failed to calculate statistics',
+            details: error.message
+        };
+    }
+};
+
+/**
+ * Rotate old telemetry files
+ * Why: Prevent unbounded growth
+ *
+ * @param {number} maxDays - Keep files newer than this many days (default: 30)
+ */
+export const rotateTelemetry = async (maxDays = 30) => {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+
+    try {
+        const dir = getTelemetryDir();
+        const files = await fs.readdir(dir);
+
+        // Filter to .jsonl files
+        const logFiles = files.filter(f => f.endsWith('.jsonl'));
+
+        // Calculate cutoff date
+        const cutoffDate = new Date();
+        cutoffDate.setDate(cutoffDate.getDate() - maxDays);
+        const cutoffStr = cutoffDate.toISOString().split('T')[0]; // YYYY-MM-DD
+
+        // Delete old files
+        for (const file of logFiles) {
+            // Extract date from filename (telemetry-YYYY-MM-DD.jsonl)
+            const match = file.match(/telemetry-(\d{4}-\d{2}-\d{2})\.jsonl/);
+            if (match) {
+                const fileDate = match[1];
+                if (fileDate < cutoffStr) {
+                    const filePath = path.join(dir, file);
+                    await fs.unlink(filePath);
+                    logger.debug('telemetry - rotateTelemetry', `Deleted old telemetry file: ${file}`);
+                }
+            }
+        }
+    } catch (error) {
+        logger.debug('telemetry - rotateTelemetry', 'Failed to rotate telemetry', error);
+    }
+};
+
+/**
+ * Clear all telemetry data
+ * Why: Allow users to reset
+ */
+export const clearTelemetry = async () => {
+    try {
+        const dir = getTelemetryDir();
+
+        // Check if directory exists
+        if (!fsSync.existsSync(dir)) {
+            logger.info('No telemetry data found');
+            return;
+        }
+
+        // Delete all .jsonl files
+        const files = await fs.readdir(dir);
+        const logFiles = files.filter(f => f.endsWith('.jsonl'));
+
+        for (const file of logFiles) {
+            const filePath = path.join(dir, file);
+            await fs.unlink(filePath);
+        }
+
+        logger.info(`Cleared ${logFiles.length} telemetry files`);
+    } catch (error) {
+        logger.error('telemetry - clearTelemetry', 'Failed to clear telemetry', error);
+    }
+};
+
+/**
+ * Display telemetry statistics to console
+ * Why: User-friendly stats display for CLI
+ */
+export const displayStatistics = async () => {
+    const stats = await getStatistics();
+
+    console.log('\n╔════════════════════════════════════════════════════════════════════╗');
+    console.log('║                     TELEMETRY STATISTICS                           ║');
+    console.log('╚════════════════════════════════════════════════════════════════════╝\n');
+
+    if (!stats.enabled) {
+        console.log(stats.message);
+        console.log('\nTelemetry is disabled in your configuration.');
+        console.log('To re-enable (default), remove or set to true in .claude/config.json:');
+        console.log('{');
+        console.log('  "system": {');
+        console.log('    "telemetry": true');
+        console.log('  }');
+        console.log('}\n');
+        return;
+    }
+
+    if (stats.error) {
+        console.log(`Error: ${stats.error}`);
+        console.log(`Details: ${stats.details}\n`);
+        return;
+    }
+
+    console.log(`Period: ${stats.period}`);
+    console.log(`Total events: ${stats.totalEvents}\n`);
+
+    console.log('━━━ ANALYSIS RESULTS ━━━');
+    console.log(`✅ Successful analyses: ${stats.batchSuccesses}`);
+    console.log(`❌ JSON parse failures: ${stats.jsonParseFailures}`);
+    console.log(`📊 Failure rate: ${stats.failureRate}%\n`);
+
+    if (stats.jsonParseFailures > 0) {
+        console.log('━━━ FAILURES BY BATCH SIZE ━━━');
+        Object.entries(stats.failuresByBatchSize)
+            .sort((a, b) => b[1] - a[1])
+            .forEach(([size, count]) => {
+                console.log(`  Batch size ${size}: ${count} failures`);
+            });
+        console.log();
+
+        console.log('━━━ FAILURES BY MODEL ━━━');
+        Object.entries(stats.failuresByModel)
+            .sort((a, b) => b[1] - a[1])
+            .forEach(([model, count]) => {
+                console.log(`  ${model}: ${count} failures`);
+            });
+        console.log();
+
+        console.log('━━━ FAILURES BY HOOK ━━━');
+        Object.entries(stats.failuresByHook)
+            .sort((a, b) => b[1] - a[1])
+            .forEach(([hook, count]) => {
+                console.log(`  ${hook}: ${count} failures`);
+            });
+        console.log();
+
+        console.log('━━━ AVERAGES ━━━');
+        console.log(`  Avg files per failure: ${stats.avgFilesPerFailure}`);
+        console.log(`  Avg files per success: ${stats.avgFilesPerSuccess}\n`);
+    }
+
+    console.log('📂 Telemetry location: .claude/telemetry/');
+    console.log('💡 Tip: Share telemetry logs when reporting issues for faster debugging\n');
+};

package/package.json

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