claude-git-hooks 2.32.0 → 2.33.1

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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.1] - 2026-03-26
+
+### 🔧 Changed
+- Improved WSL Claude CLI detection to resolve Claude's path via login shell when installed via nvm or user-scoped npm prefix
+- Added support for detecting Claude CLI in non-default WSL distros when the default distro is docker-desktop or similar
+- Switched to execFileSync for WSL distro listing to avoid cmd.exe quote mangling issues
+- Updated README-NPM with release workflow commands documentation and WSL troubleshooting guide
+
+### 🐛 Fixed
+- Fixed Claude CLI not being detected on Windows when running from Git Bash with Claude installed inside WSL via nvm (#120)
+- Fixed WSL distro detection failing due to UTF-16LE encoding from wsl.exe output
+
+
+## [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/helpers.js

@@ -18,6 +18,7 @@ import os from 'os';
 import https from 'https';
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
+import { getRunningWSLDistros } from '../utils/claude-client.js';
 
 // Why: ES6 modules don't have __dirname, need to recreate it
 const __filename = fileURLToPath(import.meta.url);
@@ -130,9 +131,46 @@ export function isWindows() {
     return os.platform() === 'win32' || process.env.OS === 'Windows_NT';
 }
 
+/**
+ * Resolve Claude's absolute path inside WSL via login shell
+ * Why: If Claude is installed via nvm or user-scoped npm prefix in WSL,
+ * it's only in PATH when .bashrc/.profile is sourced (login/interactive shell).
+ * A bare `wsl claude` runs a non-interactive shell that skips profile loading.
+ *
+ * @param {string|null} distro - WSL distro name (null = default distro)
+ * @returns {string|null} Absolute Linux path to claude binary, or null
+ */
+export function resolveClaudePathInWSL(distro = null) {
+    const distroFlag = distro ? `-d "${distro}" ` : '';
+    try {
+        const resolvedPath = execSync(`wsl ${distroFlag}bash -lc "which claude"`, {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'ignore'],
+            timeout: 10000
+        }).trim();
+
+        if (resolvedPath && resolvedPath.startsWith('/')) {
+            // Verify the resolved path actually works
+            execSync(`wsl ${distroFlag}${resolvedPath} --version`, {
+                stdio: 'ignore',
+                timeout: 10000
+            });
+            return resolvedPath;
+        }
+        return null;
+    } catch (e) {
+        return null;
+    }
+}
+
 /**
  * Get Claude command based on platform
  * Why: On Windows, try native Claude first, then WSL as fallback
+ * Strategy:
+ *   1. Native Windows `claude` (installed via npm/scoop/choco on Windows)
+ *   2. Direct `wsl claude` (Claude in WSL default PATH)
+ *   3. WSL login-shell resolution (Claude installed via nvm or custom PATH in WSL)
+ *   4. Non-default distro scan (default may be docker-desktop, not Ubuntu)
  * @returns {string}
  */
 export function getClaudeCommand() {
@@ -142,8 +180,37 @@ export function getClaudeCommand() {
             execSync('claude --version', { stdio: 'ignore', timeout: 3000 });
             return 'claude';
         } catch (e) {
-            // Fallback to WSL
-            return 'wsl claude';
+            // Try direct WSL (Claude in default non-interactive PATH)
+            try {
+                execSync('wsl claude --version', { stdio: 'ignore', timeout: 10000 });
+                return 'wsl claude';
+            } catch (e2) {
+                // Try WSL with login shell (Claude installed via nvm or custom PATH)
+                const resolvedPath = resolveClaudePathInWSL();
+                if (resolvedPath) {
+                    return `wsl ${resolvedPath}`;
+                }
+
+                // Strategy 4: Non-default WSL distro (e.g., default is docker-desktop)
+                const distros = getRunningWSLDistros('wsl');
+                for (const distro of distros) {
+                    try {
+                        execSync(`wsl -d "${distro}" claude --version`, {
+                            stdio: 'ignore',
+                            timeout: 10000
+                        });
+                        return `wsl -d "${distro}" claude`;
+                    } catch (distroError) {
+                        const resolved = resolveClaudePathInWSL(distro);
+                        if (resolved) {
+                            return `wsl -d "${distro}" ${resolved}`;
+                        }
+                    }
+                }
+
+                // All attempts failed — return best-effort fallback
+                return 'wsl claude';
+            }
         }
     }
     return 'claude';

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/claude-client.js

@@ -15,7 +15,7 @@
  * - claude-diagnostics: Error detection and formatting
  */
 
-import { spawn, execSync } from 'child_process';
+import { spawn, execSync, execFileSync } from 'child_process';
 import fs from 'fs/promises';
 import path from 'path';
 import os from 'os';
@@ -70,6 +70,37 @@ const isWSLAvailable = () => {
     }
 };
 
+/**
+ * Get running WSL distros, excluding Docker-internal ones
+ * Why: The default WSL distro may be docker-desktop (which doesn't have Claude).
+ * We need to find the actual Linux distro (e.g., Ubuntu) where Claude is installed.
+ *
+ * @param {string} wslPath - Absolute path to wsl.exe
+ * @returns {string[]} List of running non-Docker distro names
+ */
+export const getRunningWSLDistros = (wslPath) => {
+    try {
+        // Use execFileSync to bypass cmd.exe shell quoting — args passed directly to wsl.exe
+        const raw = execFileSync(wslPath, ['-l', '--running', '-q'], {
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'ignore']
+        });
+        // Why UTF-16LE: wsl.exe is a native Windows executable that outputs Unicode in Windows' default
+        // encoding (UTF-16LE), not UTF-8. The null bytes (\0) are BOM artifacts and padding characters
+        // from the UTF-16LE encoding that must be stripped to get clean distro names.
+        const output = raw.toString('utf16le');
+        return output
+            .split(/\r?\n/)
+            .map((s) => s.replace(/\0/g, '').trim())
+            .filter((s) => s && !s.toLowerCase().includes('docker'));
+    } catch (e) {
+        logger.debug('claude-client - getRunningWSLDistros', 'Failed to list WSL distros', {
+            error: e.message
+        });
+        return [];
+    }
+};
+
 /**
  * Get Claude command configuration for current platform
  * Why: On Windows, try native Claude first, then WSL as fallback
@@ -112,11 +143,12 @@ const getClaudeCommand = () => {
         // Node 24: Resolve wsl.exe absolute path to avoid shell: true
         const wslPath = which('wsl');
         if (wslPath) {
+            const wslCheckTimeout = config.system.wslCheckTimeout || 15000;
+
+            // Strategy 1: Direct `wsl claude` (Claude in default non-interactive PATH)
+            // Use execFileSync to bypass cmd.exe — args passed directly to wsl.exe without quote mangling
             try {
-                // Verify Claude exists in WSL
-                // Increased timeout from 5s to 15s to handle system load better
-                const wslCheckTimeout = config.system.wslCheckTimeout || 15000;
-                execSync(`"${wslPath}" claude --version`, {
+                execFileSync(wslPath, ['claude', '--version'], {
                     stdio: 'ignore',
                     timeout: wslCheckTimeout
                 });
@@ -125,11 +157,9 @@ const getClaudeCommand = () => {
                 });
                 return { command: wslPath, args: ['claude'] };
             } catch (wslError) {
-                // Differentiate error types for accurate user feedback
                 const errorMsg = wslError.message || '';
-                const wslCheckTimeout = config.system.wslCheckTimeout || 15000;
 
-                // Timeout: Transient system load issue
+                // Timeout: Transient system load issue — don't try fallback
                 if (errorMsg.includes('ETIMEDOUT')) {
                     throw new ClaudeClientError(
                         'Timeout connecting to WSL - system under heavy load',
@@ -146,30 +176,132 @@ const getClaudeCommand = () => {
                     );
                 }
 
-                // 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"'
-                        }
+                // Not a timeout — try login-shell fallback below
+                logger.debug(
+                    'claude-client - getClaudeCommand',
+                    'Direct wsl claude failed, trying login-shell resolution',
+                    { error: errorMsg }
+                );
+            }
+
+            // Strategy 2: WSL login-shell resolution (Claude installed via nvm or custom PATH)
+            // Why: `wsl claude` runs a non-interactive shell that doesn't source .bashrc/.profile,
+            // so Claude installed via nvm or user-scoped npm prefix won't be in PATH.
+            // `bash -lc "which claude"` sources the login profile to resolve the full path.
+            // Why execFileSync: cmd.exe strips inner quotes from `bash -lc "which claude"`,
+            // causing bash to receive `which` and `claude` as separate args. execFileSync bypasses
+            // cmd.exe and passes arguments directly, preserving multi-word argument boundaries.
+            try {
+                const resolvedPath = execFileSync(
+                    wslPath,
+                    ['bash', '-lc', 'which claude'],
+                    {
+                        encoding: 'utf8',
+                        stdio: ['pipe', 'pipe', 'ignore'],
+                        timeout: wslCheckTimeout
+                    }
+                ).trim();
+
+                if (resolvedPath && resolvedPath.startsWith('/')) {
+                    // Verify: run the resolved path via login shell (node may also require login shell)
+                    execFileSync(wslPath, ['bash', '-lc', `${resolvedPath} --version`], {
+                        stdio: 'ignore',
+                        timeout: wslCheckTimeout
                     });
+                    logger.debug(
+                        'claude-client - getClaudeCommand',
+                        'Using WSL Claude CLI via login-shell resolution',
+                        { wslPath, claudePath: resolvedPath }
+                    );
+                    // Return loginShell so executeClaude wraps the call in bash -lc
+                    return { command: wslPath, args: [], loginShell: { path: resolvedPath } };
                 }
+            } catch (loginShellError) {
+                logger.debug(
+                    'claude-client - getClaudeCommand',
+                    'WSL login-shell resolution failed',
+                    { error: loginShellError.message }
+                );
+            }
 
-                // Generic error: Other WSL issues
-                throw new ClaudeClientError('Failed to verify Claude CLI in WSL', {
-                    context: {
-                        platform: 'Windows',
-                        wslPath,
-                        error: errorMsg,
-                        suggestion:
-                            'Check WSL is functioning: wsl --version, or skip analysis: git commit --no-verify'
+            // Strategy 3: Non-default WSL distro (e.g., default is docker-desktop)
+            // Why: If the default WSL distro is docker-desktop or another minimal distro,
+            // Claude may be installed in a different distro like Ubuntu.
+            const distros = getRunningWSLDistros(wslPath);
+            logger.debug(
+                'claude-client - getClaudeCommand',
+                'Trying non-default WSL distros',
+                { distros }
+            );
+
+            for (const distro of distros) {
+                // Try direct call in this distro
+                try {
+                    execFileSync(wslPath, ['-d', distro, 'claude', '--version'], {
+                        stdio: 'ignore',
+                        timeout: wslCheckTimeout
+                    });
+                    logger.debug(
+                        'claude-client - getClaudeCommand',
+                        'Using WSL Claude CLI in distro',
+                        { wslPath, distro }
+                    );
+                    return { command: wslPath, args: ['-d', distro, 'claude'] };
+                } catch (distroError) {
+                    // Try login-shell resolution in this distro
+                    try {
+                        const resolved = execFileSync(
+                            wslPath,
+                            ['-d', distro, 'bash', '-lc', 'which claude'],
+                            {
+                                encoding: 'utf8',
+                                stdio: ['pipe', 'pipe', 'ignore'],
+                                timeout: wslCheckTimeout
+                            }
+                        ).trim();
+
+                        if (resolved && resolved.startsWith('/')) {
+                            execFileSync(
+                                wslPath,
+                                ['-d', distro, 'bash', '-lc', `${resolved} --version`],
+                                {
+                                    stdio: 'ignore',
+                                    timeout: wslCheckTimeout
+                                }
+                            );
+                            logger.debug(
+                                'claude-client - getClaudeCommand',
+                                'Using WSL Claude CLI via login-shell in distro',
+                                { wslPath, distro, claudePath: resolved }
+                            );
+                            // Return loginShell so executeClaude wraps the call in bash -lc
+                            return {
+                                command: wslPath,
+                                args: ['-d', distro],
+                                loginShell: { path: resolved }
+                            };
+                        }
+                    } catch (distroLoginError) {
+                        logger.debug(
+                            'claude-client - getClaudeCommand',
+                            `Distro ${distro} does not have Claude`,
+                            { error: distroLoginError.message }
+                        );
                     }
-                });
+                }
             }
+
+            // All strategies failed
+            throw new ClaudeClientError('Claude CLI not found in WSL', {
+                context: {
+                    platform: 'Windows',
+                    wslPath,
+                    error: 'Claude not found via direct call or login-shell resolution',
+                    triedDistros: distros,
+                    suggestion:
+                        'Install Claude in WSL: wsl -e bash -c "npm install -g @anthropic-ai/claude-cli"'
+                }
+            });
         }
 
         throw new ClaudeClientError('Claude CLI not found in Windows or WSL', {
@@ -212,18 +344,26 @@ const getClaudeCommand = () => {
 const executeClaude = (prompt, { timeout = 120000, allowedTools = [], model = null } = {}) =>
     new Promise((resolve, reject) => {
         // Get platform-specific command
-        const { command, args } = getClaudeCommand();
+        const { command, args, loginShell } = getClaudeCommand();
 
-        // Add allowed tools if specified (for MCP tools)
+        // Build final args — handling differs for login-shell (WSL via bash -lc) vs direct invocation
         const finalArgs = [...args];
-        if (allowedTools.length > 0) {
-            // Format: --allowedTools "mcp__github__create_pull_request,mcp__github__get_file_contents"
-            finalArgs.push('--allowedTools', allowedTools.join(','));
-        }
-
-        // Add model override if specified
-        if (model) {
-            finalArgs.push('--model', model);
+        if (loginShell) {
+            // Why: When claude is found via WSL login-shell (e.g. nvm-installed node), it must be
+            // executed inside bash --login so that .profile/.bashrc set up the correct PATH.
+            // All CLI flags are embedded in the bash -c command string (no spaces in flag values).
+            const claudeParts = [loginShell.path];
+            if (allowedTools.length > 0) claudeParts.push(`--allowedTools ${allowedTools.join(',')}`);
+            if (model) claudeParts.push(`--model ${model}`);
+            finalArgs.push('bash', '-lc', claudeParts.join(' '));
+        } else {
+            if (allowedTools.length > 0) {
+                // Format: --allowedTools "mcp__github__create_pull_request,mcp__github__get_file_contents"
+                finalArgs.push('--allowedTools', allowedTools.join(','));
+            }
+            if (model) {
+                finalArgs.push('--model', model);
+            }
         }
 
         // CRITICAL FIX: Windows .cmd/.bat file handling

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.1",
     "description": "Git hooks with Claude CLI for code analysis and automatic commit messages",
     "type": "module",
     "bin": {