claude-git-hooks 2.32.0 → 2.33.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.33.0] - 2026-03-20
+
+### ✨ Added
+- Always-on metrics system for code quality observability (#41) - collects structured JSONL events locally with 90-day retention for trend analysis
+- Team-based reviewer selection via GitHub Teams API (#115, #36) - automatically resolves team members and excludes PR author when selecting reviewers
+- New metrics module (`lib/utils/metrics.js`) with fire-and-forget event recording that never blocks callers
+- Metrics instrumentation for pre-commit analysis, commit message generation, PR creation, judge verdicts, and orchestration batches
+- Documented proven implementation patterns in CLAUDE.md covering testability, git operations, and architecture best practices
+
+### 🔧 Changed
+- Telemetry system now always enabled - removed opt-out toggle for consistent observability
+- Existing telemetry events dual-write to unified metrics system for consolidated analysis
+- PR statistics module now records to both legacy JSONL and new metrics system
+- Judge module switched from telemetry to metrics recording with richer event data including false positives and unresolved issues
+
+### 🗑️ Removed
+- Removed `system.telemetry` configuration option - metrics are now always collected locally
+- Removed telemetry disabled warnings from `batch-info` and `telemetry-cmd` commands
+
+
 ## [2.32.0] - 2026-03-19
 
 ### ✨ Added

package/CLAUDE.md

@@ -1240,6 +1240,28 @@ No enforced threshold. Focus on critical paths:
 - `git-operations.js` - Git command abstraction
 - `config.js` - Configuration merging
 
+## Proven Implementation Patterns
+
+Recurring patterns validated across 15+ automation sessions. Apply these in new code to avoid known pitfalls.
+
+### Testability
+
+- **`process.exit()` outside try/catch**: Mocking `process.exit` to throw requires the throw to propagate. Any surrounding `catch (e)` silently swallows it. Pattern: capture fallible values inside try/catch, check them and exit *outside* the catch block.
+- **`jest.resetAllMocks()` over `clearAllMocks()`**: `clearAllMocks()` clears call history but does NOT drain `mockResolvedValueOnce` queues. Tests that leave unconsumed values silently corrupt subsequent tests. Use `resetAllMocks()` in `beforeEach` and re-apply all defaults explicitly.
+- **`_privateHelper` export for unit testing**: Private-by-convention functions (`_` prefix) can be exported for direct unit testing without invoking the full command flow. Used in `close-release.js`, `revert-feature.js`, `shadow.js`.
+
+### Git Operations
+
+- **`execSync` with `input` for multi-line commit messages**: `git commit -F -` with `execSync({ input: fullMessage })` avoids temp files, heredocs, and `\n` escaping. Used when `createCommit()` (which only supports `-m`) is insufficient.
+- **`git diff-tree --no-commit-id -r --name-only <hash>`**: Canonical command to list files changed in a single commit. Preferable to parsing `git show --stat` (fragile) or `getChangedFilesBetweenRefs('<hash>^', '<hash>')` (breaks on first commit).
+- **`git merge --no-verify --no-ff` via `execSync`**: `mergeBranch()` in `git-operations.js` does not support `--no-verify`. For hook-free merges (shadow sync, back-merge), use `execSync` directly with the full flags.
+
+### Architecture
+
+- **`PROTECTED_COMMANDS` fast-path**: Static Set check before any API call — non-protected commands short-circuit with zero network overhead. Pattern for any guard that only applies to a subset of commands.
+- **Graceful degradation for features, fail-closed for security**: Labels, shadow sync, CHANGELOG — warn and continue on failure. Authorization, permissions — block on any error. Two fetch patterns for the same config repo.
+- **Inline Set intersection over Union-Find for single-target checks**: `coupling-detector.js` Union-Find is for N-PR transitive grouping. For checking one commit against others (revert-feature), a simple `Set` intersection per item is sufficient.
+
 ## Restrictions
 
 ### What Claude should NOT do in this repository

package/lib/commands/create-pr.js

@@ -23,6 +23,7 @@ import { getBranchPushStatus, pushBranch } from '../utils/git-operations.js';
 import logger from '../utils/logger.js';
 import { resolveLabels } from '../utils/label-resolver.js';
 import { error, checkGitRepo } from './helpers.js';
+import { recordMetric } from '../utils/metrics.js';
 
 /**
  * Detect expected merge strategy from branch naming conventions
@@ -697,6 +698,18 @@ export async function runCreatePr(args) {
                 prUrl: result.html_url
             });
 
+            // Record PR creation metric
+            recordMetric('pr.created', {
+                repo: repoInfo.fullName,
+                base: baseBranch,
+                head: currentBranch,
+                strategy: mergeStrategy,
+                labels,
+                reviewerCount: reviewers.length,
+                fileCount: filesArray.length,
+                prNumber: result.number
+            }).catch(() => {});
+
             console.log('');
             showSuccess('Pull request created successfully!');
             console.log('');

package/lib/commands/diff-batch-info.js

@@ -39,15 +39,6 @@ export async function runDiffBatchInfo() {
     try {
         const stats = await getStatistics(7);
 
-        if (!stats.enabled) {
-            console.log('  Telemetry is disabled — no speed data available.');
-            console.log(
-                '  To enable, ensure "system.telemetry" is not set to false in .claude/config.json'
-            );
-            console.log();
-            return;
-        }
-
         if (stats.totalEvents === 0) {
             console.log('━━━ SPEED TELEMETRY (last 7 days) ━━━');
             console.log('  No telemetry data yet.');

package/lib/commands/telemetry-cmd.js

@@ -3,13 +3,11 @@
  * Purpose: Telemetry management commands (show, clear)
  */
 
-import { getConfig } from '../config.js';
 import {
     displayStatistics as showTelemetryStats,
     clearTelemetry as clearTelemetryData
 } from '../utils/telemetry.js';
 import { promptConfirmation } from '../utils/interactive-ui.js';
-import logger from '../utils/logger.js';
 import { success, info } from './helpers.js';
 
 /**
@@ -25,19 +23,6 @@ export async function runShowTelemetry() {
  * Why: Allow users to reset telemetry
  */
 export async function runClearTelemetry() {
-    const config = await getConfig();
-
-    if (!config.system?.telemetry && config.system?.telemetry !== undefined) {
-        logger.warning('⚠️  Telemetry is currently disabled.');
-        logger.info('To re-enable (default), remove or set to true in .claude/config.json:');
-        logger.info('{');
-        logger.info('  "system": {');
-        logger.info('    "telemetry": true');
-        logger.info('  }');
-        logger.info('}');
-        return;
-    }
-
     const confirmed = await promptConfirmation(
         'Are you sure you want to clear all telemetry data?'
     );

package/lib/config.js

@@ -62,7 +62,6 @@ 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

@@ -32,6 +32,7 @@ import { loadPreset } from '../utils/preset-loader.js';
 import { getVersion } from '../utils/package-info.js';
 import logger from '../utils/logger.js';
 import { getConfig } from '../config.js';
+import { recordMetric } from '../utils/metrics.js';
 
 /**
  * Configuration loaded from lib/config.js
@@ -218,6 +219,23 @@ const main = async () => {
                 console.log();
             }
 
+            // Record blocked analysis metric
+            recordMetric('analysis.completed', {
+                files: validFiles.map(f => f.path),
+                fileCount: validFiles.length,
+                issues: result.issues,
+                details: (result.details || []).map(d => ({
+                    severity: d.severity, category: d.category,
+                    description: d.description, file: d.file
+                })),
+                blocked: true,
+                duration: Date.now() - startTime,
+                preset: presetName,
+                orchestrated: filesData.length >= 3
+            }).catch((err) => {
+                logger.debug('pre-commit - main', 'Metrics recording failed (blocked)', err);
+            });
+
             // Generate resolution prompt if needed
             if (shouldGeneratePrompt(result)) {
                 const resolutionPath = await generateResolutionPrompt(result, {
@@ -235,6 +253,23 @@ const main = async () => {
             process.exit(1);
         }
 
+        // Record successful analysis metric
+        recordMetric('analysis.completed', {
+            files: validFiles.map(f => f.path),
+            fileCount: validFiles.length,
+            issues: result.issues,
+            details: (result.details || []).map(d => ({
+                severity: d.severity, category: d.category,
+                description: d.description, file: d.file
+            })),
+            blocked: false,
+            duration: Date.now() - startTime,
+            preset: presetName,
+            orchestrated: filesData.length >= 3
+        }).catch((err) => {
+            logger.debug('pre-commit - main', 'Metrics recording failed (success)', err);
+        });
+
         // Success
         const duration = ((Date.now() - startTime) / 1000).toFixed(2);
         console.log(`\n⏱️  Analysis time: ${duration}s`);
@@ -242,6 +277,14 @@ const main = async () => {
 
         process.exit(0);
     } catch (error) {
+        // Record analysis failure metric
+        recordMetric('analysis.failed', {
+            errorMessage: error.message,
+            duration: Date.now() - startTime
+        }).catch((err) => {
+            logger.debug('pre-commit - main', 'Metrics recording failed (error)', err);
+        });
+
         const duration = ((Date.now() - startTime) / 1000).toFixed(2);
         console.log(`\n⏱️  Analysis time: ${duration}s`);
 

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

@@ -25,6 +25,7 @@ import { getVersion } from '../utils/package-info.js';
 import logger from '../utils/logger.js';
 import { getConfig } from '../config.js';
 import { getOrPromptTaskId, formatWithTaskId } from '../utils/task-id.js';
+import { recordMetric } from '../utils/metrics.js';
 
 /**
  * Builds commit message generation prompt
@@ -265,6 +266,14 @@ const main = async () => {
         // Write to commit message file
         await fs.writeFile(commitMsgFile, `${message}\n`, 'utf8');
 
+        // Record commit generation metric
+        recordMetric('commit.generated', {
+            fileCount: filesData.length,
+            files: filesData.map(f => f.path),
+            duration: Date.now() - startTime,
+            success: true
+        }).catch(() => {});
+
         const duration = ((Date.now() - startTime) / 1000).toFixed(2);
         console.error(`⏱️  Message generation completed in ${duration}s`);
 
@@ -272,6 +281,12 @@ const main = async () => {
 
         process.exit(0);
     } catch (error) {
+        // Record commit failure metric
+        recordMetric('commit.failed', {
+            errorMessage: error.message,
+            duration: Date.now() - startTime
+        }).catch(() => {});
+
         const duration = ((Date.now() - startTime) / 1000).toFixed(2);
         console.error(`⏱️  Message generation failed after ${duration}s`);
 

package/lib/utils/analysis-engine.js

@@ -34,6 +34,7 @@ import { analyzeCode } from './claude-client.js';
 import { orchestrateBatches } from './diff-analysis-orchestrator.js';
 import { buildAnalysisPrompt } from './prompt-builder.js';
 import logger from './logger.js';
+import { recordMetric } from './metrics.js';
 
 /**
  * Standard file data schema used throughout the analysis pipeline
@@ -448,6 +449,15 @@ export const runAnalysis = async (filesData, config, options = {}) => {
 
         result = consolidateResults(results);
 
+        // Record orchestration metric
+        recordMetric('orchestration.completed', {
+            fileCount: filesData.length,
+            batchCount: batches.length,
+            batchBreakdown: batches.map(b => ({ files: b.files.length, model: b.model })),
+            orchestrationTime,
+            hook
+        }).catch(() => {});
+
         if (saveDebug) {
             const { saveDebugResponse } = await import('./claude-client.js');
             await saveDebugResponse(

package/lib/utils/judge.js

@@ -25,7 +25,7 @@ import { loadPrompt } from './prompt-builder.js';
 import { formatBlockingIssues, getAffectedFiles, formatFileContents } from './resolution-prompt.js';
 import { getRepoRoot, getRepoName, getCurrentBranch } from './git-operations.js';
 import logger from './logger.js';
-import { recordEvent } from './telemetry.js';
+import { recordMetric } from './metrics.js';
 
 const JUDGE_DEFAULT_MODEL = 'sonnet';
 const JUDGE_TIMEOUT = 120000;
@@ -239,14 +239,21 @@ const judgeAndFix = async (analysisResult, filesData, config) => {
         );
     }
 
-    // Record telemetry
-    await recordEvent('judge', {
+    // Record metrics
+    recordMetric('judge.completed', {
         model,
         issueCount: allIssues.length,
         fixedCount,
         falsePositiveCount,
-        unresolvedCount
-    });
+        unresolvedCount,
+        falsePositives: fixes.filter(f => f.assessment === 'FALSE_POSITIVE')
+            .map(f => ({ explanation: f.explanation || '' })),
+        unresolved: remainingIssues.map(i => ({
+            severity: i.severity, description: i.description || i.message || '', file: i.file
+        })),
+        fixed: fixes.filter((f, idx) => f.assessment === 'TRUE_ISSUE' && resolvedIndices.has(idx))
+            .map(f => ({ file: f.file, explanation: f.explanation || '' }))
+    }).catch(() => {});
 
     return { fixedCount, falsePositiveCount, remainingIssues, verdicts };
 };

package/lib/utils/metrics.js

@@ -0,0 +1,185 @@
+/**
+ * File: metrics.js
+ * Purpose: Centralized metrics collection for code quality observability
+ *
+ * Design principles:
+ * - ALWAYS ON: No opt-in/opt-out toggle
+ * - LOCAL ONLY: Data never leaves user's machine
+ * - FIRE-AND-FORGET: All errors swallowed, never blocks callers
+ * - STRUCTURED LOGS: JSONL format with typed events
+ * - AUTO-ROTATION: 90-day retention for quality trend analysis
+ *
+ * Event schema:
+ * {
+ *   id: "1703612345678-001-a3f",
+ *   timestamp: "2026-03-20T10:30:00.000Z",
+ *   type: "analysis.completed",
+ *   repoId: "owner/repo",
+ *   data: { ... }
+ * }
+ *
+ * Dependencies:
+ * - fs/promises: File operations
+ * - logger: Debug logging
+ * - git-operations: getRepoRoot
+ * - github-client: parseGitHubRepo (lazy, cached)
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import logger from './logger.js';
+import { getRepoRoot } from './git-operations.js';
+
+/**
+ * Counter for generating unique IDs within the same millisecond
+ */
+let eventCounter = 0;
+
+/**
+ * Cached repoId: undefined = not resolved, null = failed, string = resolved
+ */
+let cachedRepoId;
+
+/**
+ * Generate unique event ID
+ * 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);
+
+    if (eventCounter > 999) {
+        eventCounter = 0;
+    }
+
+    return `${timestamp}-${counter}-${random}`;
+};
+
+/**
+ * Get metrics directory path
+ * @returns {string} Metrics directory path under repo root
+ */
+const getMetricsDir = () => {
+    try {
+        return path.join(getRepoRoot(), '.claude', 'metrics');
+    } catch {
+        return path.join(process.cwd(), '.claude', 'metrics');
+    }
+};
+
+/**
+ * Get current metrics log file path (date-stamped)
+ * @returns {string} Current log file path
+ */
+const getCurrentLogFile = () => {
+    const date = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
+    return path.join(getMetricsDir(), `events-${date}.jsonl`);
+};
+
+/**
+ * Resolve repository identifier from git remote URL
+ * Uses dynamic import() to avoid circular deps. Cached per-process.
+ *
+ * @returns {Promise<string|null>} Repository full name (owner/repo) or null
+ */
+export const getRepoId = async () => {
+    if (cachedRepoId !== undefined) {
+        return cachedRepoId;
+    }
+
+    try {
+        const { parseGitHubRepo } = await import('./github-client.js');
+        const repo = parseGitHubRepo();
+        cachedRepoId = repo.fullName;
+    } catch {
+        cachedRepoId = null;
+    }
+
+    return cachedRepoId;
+};
+
+/**
+ * Record a metric event
+ * Fire-and-forget: never throws, never blocks
+ *
+ * @param {string} eventType - Event type (e.g., 'analysis.completed', 'judge.completed')
+ * @param {Object} data - Event-specific data
+ * @returns {Promise<void>}
+ */
+export const recordMetric = async (eventType, data = {}) => {
+    try {
+        const dir = getMetricsDir();
+        await fs.mkdir(dir, { recursive: true });
+
+        const repoId = await getRepoId();
+
+        const event = {
+            id: generateEventId(),
+            timestamp: new Date().toISOString(),
+            type: eventType,
+            repoId,
+            data
+        };
+
+        const logFile = getCurrentLogFile();
+        await fs.appendFile(logFile, `${JSON.stringify(event)}\n`, 'utf8');
+
+        logger.debug('metrics - recordMetric', `Event logged: ${eventType}`);
+    } catch (error) {
+        // Fire-and-forget: never throw
+        logger.debug('metrics - recordMetric', 'Failed to record metric', error);
+    }
+};
+
+/**
+ * Rotate old metrics files
+ * Deletes files older than maxDays (default: 90)
+ *
+ * @param {number} maxDays - Keep files newer than this many days
+ * @returns {Promise<void>}
+ */
+export const rotateMetrics = async (maxDays = 90) => {
+    try {
+        const dir = getMetricsDir();
+        const files = await fs.readdir(dir);
+
+        const logFiles = files.filter((f) => f.endsWith('.jsonl'));
+
+        const cutoffDate = new Date();
+        cutoffDate.setDate(cutoffDate.getDate() - maxDays);
+        const cutoffStr = cutoffDate.toISOString().split('T')[0];
+
+        for (const file of logFiles) {
+            const match = file.match(/events-(\d{4}-\d{2}-\d{2})\.jsonl/);
+            if (match && match[1] < cutoffStr) {
+                await fs.unlink(path.join(dir, file));
+                logger.debug('metrics - rotateMetrics', `Deleted old metrics file: ${file}`);
+            }
+        }
+    } catch (error) {
+        logger.debug('metrics - rotateMetrics', 'Failed to rotate metrics', error);
+    }
+};
+
+/**
+ * Clear all metrics data
+ * @returns {Promise<void>}
+ */
+export const clearMetrics = async () => {
+    try {
+        const dir = getMetricsDir();
+        const files = await fs.readdir(dir);
+        const logFiles = files.filter((f) => f.endsWith('.jsonl'));
+
+        for (const file of logFiles) {
+            await fs.unlink(path.join(dir, file));
+        }
+
+        logger.debug('metrics - clearMetrics', `Cleared ${logFiles.length} metrics files`);
+    } catch (error) {
+        logger.debug('metrics - clearMetrics', 'Failed to clear metrics', error);
+    }
+};

package/lib/utils/pr-statistics.js

@@ -15,6 +15,7 @@ import fs from 'fs';
 import path from 'path';
 import { execSync } from 'child_process';
 import logger from './logger.js';
+import { recordMetric } from './metrics.js';
 
 /**
  * Get repository root directory
@@ -72,6 +73,20 @@ export const recordPRAnalysis = (data) => {
 
         fs.appendFileSync(statsFile, `${JSON.stringify(record)}\n`, 'utf8');
 
+        // Dual-write to unified metrics
+        recordMetric('pr.analyzed', {
+            url: data.url,
+            number: data.number,
+            repo: data.repo,
+            preset: data.preset,
+            verdict: data.verdict,
+            totalIssues: data.totalIssues,
+            commentsPosted: data.commentsPosted,
+            commentsSkipped: data.commentsSkipped
+        }).catch((err) => {
+            logger.debug('pr-statistics - recordPRAnalysis', 'Metrics write failed', err);
+        });
+
         logger.debug('pr-statistics - recordPRAnalysis', 'Statistics recorded', {
             statsFile,
             totalIssues: data.totalIssues

package/lib/utils/telemetry.js

@@ -24,7 +24,7 @@ import fs from 'fs/promises';
 import fsSync from 'fs';
 import path from 'path';
 import logger from './logger.js';
-import config from '../config.js';
+import { recordMetric, rotateMetrics as rotateMetricsData, clearMetrics as clearMetricsData } from './metrics.js';
 
 /**
  * Telemetry event structure
@@ -82,15 +82,6 @@ const getCurrentLogFile = () => {
     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
-    config.system?.telemetry !== false;
 /**
  * Ensure telemetry directory exists
  * Why: Create on first use
@@ -134,11 +125,6 @@ const appendEvent = async (event) => {
  * @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();
@@ -156,6 +142,11 @@ export const recordEvent = async (eventType, eventData = {}, metadata = {}) => {
 
         // Append to log
         await appendEvent(event);
+
+        // Dual-write to unified metrics
+        recordMetric(eventType, { ...eventData, _meta: metadata }).catch((err) => {
+            logger.debug('telemetry - recordEvent', 'Metrics write failed', err);
+        });
     } catch (error) {
         // Don't fail on telemetry errors
         logger.debug('telemetry - recordEvent', 'Failed to record event', error);
@@ -289,14 +280,6 @@ const readTelemetryEvents = async (maxDays = 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);
 
@@ -415,10 +398,6 @@ export const getStatistics = async (maxDays = 7) => {
  * @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);
@@ -450,6 +429,9 @@ export const rotateTelemetry = async (maxDays = 30) => {
     } catch (error) {
         logger.debug('telemetry - rotateTelemetry', 'Failed to rotate telemetry', error);
     }
+
+    // Also rotate unified metrics (90-day retention)
+    await rotateMetricsData().catch(() => {});
 };
 
 /**
@@ -479,6 +461,9 @@ export const clearTelemetry = async () => {
     } catch (error) {
         logger.error('telemetry - clearTelemetry', 'Failed to clear telemetry', error);
     }
+
+    // Also clear unified metrics
+    await clearMetricsData().catch(() => {});
 };
 
 /**
@@ -492,18 +477,6 @@ export const displayStatistics = async () => {
     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`);

package/package.json

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