claude-git-hooks 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -5,6 +5,125 @@ 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.4.0] - 2025-11-17
+
+### ⚠️ BREAKING CHANGES
+
+- **Debug Mode** - Environment variable `DEBUG` no longer supported
+  - **What changed**: Removed `DEBUG` environment variable support from `lib/utils/logger.js`
+  - **Why**: Aligns with project philosophy "no environment variables" and provides better user experience
+  - **Migration**: Use `claude-hooks --debug true` instead of `DEBUG=1 git commit`
+  - **Alternative**: Set `"system": { "debug": true }` in `.claude/config.json`
+
+### 🔄 Changed
+
+- **File Size Limit Increased** - Default `maxFileSize` increased from 100KB to 1MB
+  - **What changed**: `analysis.maxFileSize` now defaults to 1000000 (1MB) instead of 100000 (100KB)
+  - **Why**: Previous 100KB limit was too restrictive, rejected many legitimate source files
+  - **Files updated**:
+    - `lib/config.js:29` - Default configuration
+    - All preset configs in `templates/presets/*/config.json`
+    - `templates/config.example.json`
+  - **Impact**: More files will be analyzed without manual config adjustment
+  - **User action**: If you want stricter limits, set `"maxFileSize": 100000` in `.claude/config.json`
+
+### ✨ Added
+
+- **Debug CLI Command** - New `--debug` flag for managing debug mode
+  - **Usage**: `claude-hooks --debug <true|false|status>`
+  - **Purpose**: Enables detailed logging for troubleshooting
+  - **Implementation**: Generic `updateConfig()` function in `bin/claude-hooks:1262`
+  - **Benefits**: Consistent with `--set-preset` pattern, no need to remember env var syntax
+
+- **Generic Config Updater** - Reusable `updateConfig()` function
+  - **Purpose**: Centralized config update logic for all CLI commands
+  - **Location**: `bin/claude-hooks:1262`
+  - **Features**: Dot notation path support, custom validators, custom success messages
+  - **Extensibility**: Easy to add new config commands (`--set-max-files`, `--set-timeout`, etc.)
+
+### 🔄 Changed
+
+- **setPreset() Refactored** - Now uses generic `updateConfig()` function
+  - **Effect**: Less code duplication, consistent error handling
+  - **Location**: `bin/claude-hooks:1349`
+
+- **Debug Mode Activation** - Hooks now enable debug from config
+  - **Files**: `lib/hooks/pre-commit.js:185`, `lib/hooks/prepare-commit-msg.js:124`
+  - **Effect**: Debug logs appear when `config.system.debug` is true
+
+### 📚 Documentation
+
+- **Help Text Updated** - Added `--debug` command documentation
+  - **Location**: `bin/claude-hooks:1170`
+  - **Includes**: Command description, examples, debug mode section
+
+- **README.md Updated** - Debug command documented in multiple sections
+  - **Cheatsheet**: Added debug commands to "Comandos Frecuentes" (line 52-56)
+  - **Tips**: Updated tip #4 with CLI command (line 269)
+  - **Features**: Updated debug mode description (line 492)
+
+## [2.3.1] - 2025-11-13
+
+### 🔄 Changed
+
+- **Configuration Priority** - Updated merge order: `defaults < user config < preset config`
+  - **Rationale**: User sets general preferences in `.claude/config.json`, preset provides tech-stack-specific overrides (highest priority)
+  - **Effect**: Presets now correctly override user settings (e.g., preset's `model: sonnet` wins over user's `model: haiku`)
+  - **Files updated**: `lib/config.js:116` (merge logic), README.md:222 (documentation)
+
+### ✨ Added
+
+- **Installation Diagnostics Utility** - New `lib/utils/installation-diagnostics.js`
+  - **Purpose**: Reusable error diagnostics with actionable remediation steps
+  - **Exports**: `formatError()`, `getInstallationDiagnostics()`, `isInstallationHealthy()`
+  - **Use case**: Detects installation in wrong directory (common cause of "presets not found" errors)
+  - **Extensible**: Documented future enhancements (file permissions, Claude CLI check, etc.)
+
+- **Enhanced Error Messages** - Better guidance when installation fails
+  - **Presets not found** (`lib/utils/preset-loader.js:194`): Shows current vs repo root directory
+  - **Hook scripts missing** (`templates/pre-commit:76`, `templates/prepare-commit-msg:76`): Early `.claude/` check with remediation steps
+  - **npm package issues**: Suggests verifying `npm list -g claude-git-hooks`
+
+- **Bash Wrapper Early Validation** - Hooks now check `.claude/` exists before attempting execution
+  - **Why**: Fails fast with helpful message if installation incomplete or performed from wrong directory
+  - **Effect**: Users immediately know to `cd` to repo root and reinstall
+
+- **Claude Error Diagnostics** - New `lib/utils/claude-diagnostics.js`
+  - **Purpose**: Detects and formats Claude CLI errors with actionable solutions
+  - **Error types**: Rate limit, authentication, network, invalid response, generic
+  - **Exports**: `detectClaudeError()`, `formatClaudeError()`, `ClaudeErrorType`, `isRecoverableError()`
+  - **Integration**: `lib/utils/claude-client.js:147` automatically detects and formats errors
+  - **Effect**: Users see clear guidance (e.g., "Rate limit resets in 2 hours, switch to haiku model")
+
+### 📚 Documentation
+
+- **CUSTOMIZATION_GUIDE.md** - Comprehensive preset creation guide in `/templates`
+  - Visual flowchart showing prompt assembly (8-step diagram)
+  - Step-by-step preset creation tutorial
+  - Placeholder system reference with examples
+  - Preset kickstart prompt for Claude-assisted generation
+  - **Burst limit warning**: Explains why git hooks hit rate limits when manual CLI doesn't
+  - Referenced in README.md:333 for discoverability
+
+- **Utility Modules Reference** - New section in README.md:596
+  - Table of all `lib/utils/` modules with purpose and key exports
+  - Usage examples for other Claude instances
+  - Promotes code reuse across projects
+
+- **README-NPM.md** - Complete rewrite for npm package page
+  - **Length**: 266 lines (up from 145 lines, but more focused)
+  - **Updated**: v2.3.0 presets, v2.2.0 config centralization, v2.0.0 cross-platform
+  - **Added**: Configuration priority explanation, troubleshooting, "What's New" section
+  - **Removed**: Outdated v1.x references, environment variable examples
+
+### 🎯 User Experience
+
+- **Clearer error context**: Errors now show current directory vs repository root
+- **Actionable solutions**: Every error includes specific commands to fix the issue
+- **Installation verification**: Early checks prevent confusing downstream errors
+- **Better documentation**: Users can find utility functions and customization guides easily
+- **Claude error clarity**: Rate limits, auth failures, and network errors now show specific remediation steps
+
 ## [2.3.0] - 2025-11-11
 
 ### ✨ Added

package/README.md

@@ -48,6 +48,12 @@ claude-hooks --set-preset <name>
 
 # Mostrar preset actual
 claude-hooks preset current
+
+# Activar modo debug
+claude-hooks --debug true
+
+# Ver estado de debug
+claude-hooks --debug status
 ```
 
 ### 📦 Instalación y Gestión
@@ -127,7 +133,7 @@ cat > .claude/config.json << 'EOF'
 {
   "preset": "backend",
   "analysis": {
-    "maxFileSize": 150000,
+    "maxFileSize": 1000000,
     "maxFiles": 12,
     "timeout": 150000
   },
@@ -224,11 +230,13 @@ EOF
 ```
 defaults (lib/config.js)
   ↓
-preset config (templates/presets/backend/config.json)
+user config (.claude/config.json)  ← General preferences
   ↓
-user config (.claude/config.json)  ← MÁXIMA PRIORIDAD
+preset config (.claude/presets/{name}/config.json)  ← MÁXIMA PRIORIDAD (tech-stack specific)
 ```
 
+**Rationale**: User sets general preferences, preset provides tech-stack-specific overrides.
+
 **Nota v2.2.0+:** Variables de entorno ya NO son soportadas. Usar `.claude/config.json` en su lugar.
 
 ### 🎯 Casos de Uso Específicos
@@ -258,9 +266,9 @@ git commit -m "fix: resolver issues"
 1. **Mensaje automático**: Usa `"auto"` como mensaje para que Claude lo genere
 2. **Skip auth**: Usa `--skip-auth` en CI/CD o desarrollo local
 3. **Force install**: Usa `--force` para reinstalar sin confirmación
-4. **Debug**: Activa en `.claude/config.json`: `{"system": {"debug": true}}`
-5. **Archivos grandes**: Se omiten automáticamente archivos > 100KB
-6. **Límite de archivos**: Máximo 10 archivos por commit (configurable)
+4. **Debug**: Activa con `claude-hooks --debug true` o en `.claude/config.json`: `{"system": {"debug": true}}`
+5. **Archivos grandes**: Se omiten automáticamente archivos > 1MB
+6. **Límite de archivos**: Máximo 30 archivos por commit (configurable)
 
 ### 🚀 Parallel Analysis (v2.2.0+)
 
@@ -324,6 +332,16 @@ git commit -m "fix: resolver issues"
 - `.claude/CLAUDE_PRE_COMMIT_SONAR.md` - Criterios (backend/frontend/data/db)
 - `.claude/CLAUDE_ANALYSIS_PROMPT_SONAR.md` - Template del prompt
 
+**Crear o modificar presets personalizados:**
+
+```bash
+# Ver guía completa de customización
+cat templates/CUSTOMIZATION_GUIDE.md
+
+# O en GitHub
+# https://github.com/pablorovito/claude-git-hooks/blob/main/templates/CUSTOMIZATION_GUIDE.md
+```
+
 **Ejemplo:**
 
 ```bash
@@ -423,8 +441,8 @@ Si no existe un `.gitignore`, se creará uno nuevo. Si ya existe, las entradas s
 1. **Intercepta cada intento de commit**
 2. **Extrae y filtra archivos modificados**:
     - Solo analiza: Java, XML, properties, yml, yaml
-    - Omite archivos mayores a 100KB
-    - Límite de 10 archivos por commit
+    - Omite archivos mayores a 1MB
+    - Límite de 30 archivos por commit
 3. **Construye prompt inteligente**:
     - Usa template de prompt desde `.claude/CLAUDE_ANALYSIS_PROMPT*.md`
     - Lee las pautas desde `.claude/CLAUDE_PRE_COMMIT*.md`
@@ -450,7 +468,7 @@ Si no existe un `.gitignore`, se creará uno nuevo. Si ya existe, las entradas s
     - `"auto"`
 2. **Analiza los cambios del staging area**:
     - Lista archivos modificados con estadísticas
-    - Incluye diffs completos para archivos < 100KB
+    - Incluye diffs completos para archivos < 1MB
 3. **Genera mensaje en formato Conventional Commits**:
     - Determina tipo: feat, fix, docs, style, refactor, test, chore
     - Crea título conciso y descriptivo
@@ -471,7 +489,7 @@ Si no existe un `.gitignore`, se creará uno nuevo. Si ya existe, las entradas s
     - 📝 Archivo `.claude-pr-analysis.json`
 - **Auto-actualización**: Verificación automática de versiones antes de cada commit con prompt interactivo para actualizar
 - **Comando update**: `claude-hooks update` para actualizar manualmente a la última versión
-- **Modo debug**: `DEBUG=1 git commit` guarda respuestas en `debug-claude-response.json`
+- **Modo debug**: `claude-hooks --debug true` activa logging detallado para troubleshooting
 - **Análisis de PR**: Nuevo comando `analyze-diff` para generar información de Pull Requests
 - **Validación de dependencias**: Verifica que Claude CLI esté autenticado antes de ejecutar
 - **⚠️ Exclusión de código del análisis (EXPERIMENTAL/BROKEN)**: Los marcadores `// SKIP_ANALYSIS_LINE` y `// SKIP_ANALYSIS_BLOCK` no funcionan correctamente. El hook analiza git diff en lugar del archivo completo, por lo que marcadores agregados en commits anteriores no son detectados en cambios subsecuentes.
@@ -518,13 +536,13 @@ claude-hooks status
 
 En `lib/hooks/pre-commit.js`:
 
-- **`MAX_FILE_SIZE`**: Tamaño máximo de archivo a analizar (default: 100KB)
-- **`MAX_FILES`**: Número máximo de archivos por commit (default: 10)
+- **`MAX_FILE_SIZE`**: Tamaño máximo de archivo a analizar (default: 1MB)
+- **`MAX_FILES`**: Número máximo de archivos por commit (default: 30)
 - **`ALLOWED_EXTENSIONS`**: Extensiones permitidas (default: .java, .xml, .properties, .yml, .yaml)
 
 En `lib/hooks/prepare-commit-msg.js`:
 
-- **`MAX_FILE_SIZE`**: Tamaño máximo para incluir diff completo (default: 100KB)
+- **`MAX_FILE_SIZE`**: Tamaño máximo para incluir diff completo (default: 1MB)
 
 ### Pautas de Evaluación
 
@@ -556,16 +574,20 @@ claude-git-hooks/
 ├── bin/
 │   └── claude-hooks                          # CLI principal (ES6 modules)
 ├── lib/                                      # 🆕 Código Node.js modular
+│   ├── config.js                             # Configuración centralizada con merge
 │   ├── hooks/
 │   │   ├── pre-commit.js                     # Hook de análisis (Node.js)
 │   │   └── prepare-commit-msg.js             # Hook de mensajes (Node.js)
 │   └── utils/
 │       ├── logger.js                         # Sistema de logging centralizado
 │       ├── git-operations.js                 # Operaciones git abstractas
-│       ├── file-operations.js                # I/O con filtro SKIP_ANALYSIS_LINE
+│       ├── file-utils.js                     # Utilidades de sistema de archivos
 │       ├── claude-client.js                  # Cliente Claude CLI
 │       ├── prompt-builder.js                 # Constructor de prompts
-│       └── resolution-prompt.js              # Generador de resolution prompts
+│       ├── resolution-prompt.js              # Generador de resolution prompts
+│       ├── preset-loader.js                  # Cargador de presets
+│       ├── installation-diagnostics.js       # Diagnósticos de instalación
+│       └── claude-diagnostics.js             # Diagnósticos de errores Claude CLI
 ├── templates/
 │   ├── pre-commit                            # Bash wrapper (llama a lib/hooks/pre-commit.js)
 │   ├── prepare-commit-msg                    # Bash wrapper (llama a lib/hooks/prepare-commit-msg.js)
@@ -588,6 +610,68 @@ claude-git-hooks/
 └── .gitignore                                # Archivos ignorados por git
 ```
 
+### 🔌 Utility Modules Reference
+
+**Purpose**: Reusable modules for extending claude-hooks or building similar tools
+
+#### Core Utilities
+
+| Module | Purpose | Key Exports | Usage Context |
+|--------|---------|-------------|---------------|
+| **`config.js`** | Centralized configuration management | `getConfig()`, `defaults` | Priority merging: defaults < user < preset |
+| **`logger.js`** | Structured logging with debug support | `info()`, `warning()`, `error()`, `debug()` | Console output with context tracking |
+| **`git-operations.js`** | Git command abstractions | `getRepoRoot()`, `getStagedFiles()`, `getDiff()` | Safe git operations with error handling |
+| **`file-utils.js`** | File system operations | `ensureDir()`, `writeFile()` | Repo-root-relative path handling |
+| **`claude-client.js`** | Claude CLI integration | `analyzeCode()`, `analyzeCodeParallel()` | Prompt execution with timeout/retry |
+| **`prompt-builder.js`** | Template-based prompts | `buildAnalysisPrompt()`, `loadTemplate()` | Dynamic prompt construction from .md files |
+| **`preset-loader.js`** | Preset system | `loadPreset()`, `listPresets()`, `loadTemplate()` | Metadata, config, template loading |
+| **`resolution-prompt.js`** | Issue resolution prompts | `generateResolutionPrompt()` | AI-friendly error remediation prompts |
+| **`installation-diagnostics.js`** | Installation error diagnostics | `formatError()`, `getInstallationDiagnostics()` | Installation error formatting with remediation |
+| **`claude-diagnostics.js`** | Claude CLI error diagnostics | `detectClaudeError()`, `formatClaudeError()` | Rate limit, auth, network error detection |
+
+#### Using Utilities in Other Claude Instances
+
+**Example: Check installation health**
+```javascript
+import { formatError } from './lib/utils/installation-diagnostics.js';
+
+try {
+  // ... operation that may fail
+} catch (error) {
+  console.error(formatError('Operation failed', ['Additional context line']));
+  process.exit(1);
+}
+```
+
+**Example: Load configuration**
+```javascript
+import { getConfig } from './lib/config.js';
+
+const config = await getConfig();
+const maxFiles = config.analysis.maxFiles;
+```
+
+**Example: Execute git operations**
+```javascript
+import { getRepoRoot, getStagedFiles } from './lib/utils/git-operations.js';
+
+const repoRoot = getRepoRoot();
+const files = getStagedFiles({ extensions: ['.js', '.ts'] });
+```
+
+**Example: Build custom prompts**
+```javascript
+import { buildAnalysisPrompt } from './lib/utils/prompt-builder.js';
+
+const prompt = await buildAnalysisPrompt({
+  templateName: 'CUSTOM_PROMPT.md',
+  files: filesData,
+  metadata: { REPO_NAME: 'my-repo' }
+});
+```
+
+**Note**: All utilities follow single-responsibility principle and include JSDoc documentation inline.
+
 ### Configuración del Entorno de Desarrollo
 
 ```bash

package/bin/claude-hooks

@@ -468,6 +468,7 @@ async function install(args) {
   console.log('  📝 Edit .claude/config.json to customize settings');
   console.log('  🎯 Use presets: backend, frontend, fullstack, database, ai, default');
   console.log('  🚀 Enable parallel analysis: set subagents.enabled = true');
+  console.log('  🐛 Enable debug mode: claude-hooks --debug true');
   console.log('\n📖 Example config.json:');
   console.log('  {');
   console.log('    "preset": "backend",');
@@ -1167,6 +1168,7 @@ Commands:
   presets              List all available presets
   --set-preset <name>  Set the active preset
   preset current       Show the current active preset
+  --debug <value>      Set debug mode (true, false, or status)
   --version, -v        Show the current version
   help                 Show this help
 
@@ -1185,6 +1187,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 --debug true         # Enable debug mode
+  claude-hooks --debug status       # Check debug status
 
 Commit use cases:
   git commit -m "message"           # Manual message + blocking analysis
@@ -1236,6 +1240,12 @@ Parallel Analysis (v2.2.0+):
   - batchSize: 4+ → Fewer API calls but slower
   - Speed improvement: up to 4x faster with batchSize: 1
 
+Debug Mode:
+  Enable detailed logging for troubleshooting:
+  - CLI: claude-hooks --debug true
+  - Config: "system": { "debug": true } in .claude/config.json
+  - Check status: claude-hooks --debug status
+
 Customization:
   Override prompts by copying to .claude/:
     cp templates/COMMIT_MESSAGE.md .claude/
@@ -1247,6 +1257,68 @@ More information: https://github.com/pablorovito/claude-git-hooks
 `);
 }
 
+// Configuration Management Functions
+
+/**
+ * Updates a configuration value in .claude/config.json
+ * Why: Centralized config update logic for all CLI commands
+ *
+ * @param {string} propertyPath - Dot notation path (e.g., 'preset', 'system.debug')
+ * @param {any} value - Value to set
+ * @param {Object} options - Optional settings
+ * @param {Function} options.validator - Custom validation function, receives value, throws on invalid
+ * @param {Function} options.successMessage - Function that receives value and returns success message
+ */
+async function updateConfig(propertyPath, value, options = {}) {
+  const { validator, successMessage } = options;
+
+  try {
+    // Validate value if validator provided
+    if (validator) {
+      await validator(value);
+    }
+
+    // Get repo root
+    const repoRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
+    const configDir = path.join(repoRoot, '.claude');
+    const configPath = path.join(configDir, 'config.json');
+
+    // Ensure .claude directory exists
+    if (!fs.existsSync(configDir)) {
+      fs.mkdirSync(configDir, { recursive: true });
+    }
+
+    // Load existing config or create new
+    let config = {};
+    if (fs.existsSync(configPath)) {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    }
+
+    // Set value at propertyPath (support dot notation like 'system.debug')
+    const pathParts = propertyPath.split('.');
+    let current = config;
+    for (let i = 0; i < pathParts.length - 1; i++) {
+      const part = pathParts[i];
+      if (!current[part] || typeof current[part] !== 'object') {
+        current[part] = {};
+      }
+      current = current[part];
+    }
+    current[pathParts[pathParts.length - 1]] = value;
+
+    // Save config
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+
+    // Show success message
+    const message = successMessage ? successMessage(value) : 'Configuration updated';
+    success(message);
+    info(`Configuration saved to ${configPath}`);
+  } catch (err) {
+    error(`Failed to update configuration: ${err.message}`);
+    process.exit(1);
+  }
+}
+
 // Preset Management Functions
 
 /**
@@ -1282,6 +1354,7 @@ async function showPresets() {
 
 /**
  * Sets the active preset
+ * Why: Configures tech-stack specific analysis settings
  */
 async function setPreset(presetName) {
   if (!presetName) {
@@ -1289,45 +1362,24 @@ async function setPreset(presetName) {
     return;
   }
 
-  try {
-    // Verify preset exists
-    const presets = await listPresets();
-    const preset = presets.find(p => p.name === presetName);
-
-    if (!preset) {
-      error(`Preset "${presetName}" not found`);
-      info('Available presets:');
-      presets.forEach(p => console.log(`  - ${p.name}`));
-      process.exit(1);
-    }
-
-    // Update .claude/config.json
-    const repoRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
-    const configDir = path.join(repoRoot, '.claude');
-    const configPath = path.join(configDir, 'config.json');
-
-    // Ensure .claude directory exists
-    if (!fs.existsSync(configDir)) {
-      fs.mkdirSync(configDir, { recursive: true });
-    }
-
-    // Load existing config or create new
-    let config = {};
-    if (fs.existsSync(configPath)) {
-      config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  await updateConfig('preset', presetName, {
+    validator: async (name) => {
+      const presets = await listPresets();
+      const preset = presets.find(p => p.name === name);
+      if (!preset) {
+        error(`Preset "${name}" not found`);
+        info('Available presets:');
+        presets.forEach(p => console.log(`  - ${p.name}`));
+        throw new Error(`Invalid preset: ${name}`);
+      }
+      return preset;
+    },
+    successMessage: async (name) => {
+      const presets = await listPresets();
+      const preset = presets.find(p => p.name === name);
+      return `Preset '${preset.displayName}' activated`;
     }
-
-    // Set preset
-    config.preset = presetName;
-
-    // Save config
-    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
-
-    success(`Preset '${preset.displayName}' activated`);
-    info(`Configuration saved to ${configPath}`);
-  } catch (err) {
-    error(`Failed to set preset: ${err.message}`);
-  }
+  });
 }
 
 /**
@@ -1354,6 +1406,45 @@ async function currentPreset() {
   }
 }
 
+/**
+ * Sets debug mode
+ * Why: Enables detailed logging for troubleshooting
+ */
+async function setDebug(value) {
+  if (!value) {
+    error('Please specify a value: claude-hooks --debug <true|false|status>');
+    return;
+  }
+
+  const normalizedValue = value.toLowerCase();
+
+  // Handle status check
+  if (normalizedValue === 'status') {
+    try {
+      const config = await getConfig();
+      const isEnabled = config.system.debug || false;
+      console.log('');
+      info(`Debug mode: ${isEnabled ? colors.green + 'enabled' + colors.reset : colors.red + 'disabled' + colors.reset}`);
+      console.log('');
+    } catch (err) {
+      error(`Failed to check debug status: ${err.message}`);
+    }
+    return;
+  }
+
+  // Validate and convert to boolean
+  if (normalizedValue !== 'true' && normalizedValue !== 'false') {
+    error('Invalid value. Use: true, false, or status');
+    return;
+  }
+
+  const debugValue = normalizedValue === 'true';
+
+  await updateConfig('system.debug', debugValue, {
+    successMessage: (val) => `Debug mode ${val ? 'enabled' : 'disabled'}`
+  });
+}
+
 // Main
 async function main() {
   const args = process.argv.slice(2);
@@ -1395,6 +1486,9 @@ async function main() {
         error(`Unknown preset subcommand: ${args[1]}`);
       }
       break;
+    case '--debug':
+      await setDebug(args[1]);
+      break;
     case '--version':
     case '-v':
     case 'version':

package/lib/config.js

@@ -2,13 +2,14 @@
  * File: config.js
  * Purpose: Centralized configuration management
  *
- * Priority: .claude/config.json > defaults
+ * Priority: preset config > .claude/config.json > defaults
  *
  * Key features:
  * - Single source of truth for all configurable values
  * - No environment variables (except OS for platform detection)
  * - Preset-aware (allowedExtensions come from preset templates)
- * - Override via .claude/config.json per project
+ * - User config (.claude/config.json) provides general preferences per project
+ * - Preset config provides tech-stack-specific overrides (highest priority)
  */
 
 import fs from 'fs';
@@ -25,9 +26,9 @@ const __dirname = path.dirname(__filename);
 const defaults = {
     // Analysis configuration
     analysis: {
-        maxFileSize: 100000,              // 100KB - max file size to analyze
-        maxFiles: 10,                      // Max number of files per commit
-        timeout: 120000,                   // 2 minutes - Claude analysis timeout
+        maxFileSize: 1000000,              // 1MB - max file size to analyze
+        maxFiles: 20,                      // Max number of files per commit
+        timeout: 300000,                   // 3 minutes - Claude analysis timeout
         contextLines: 3,                   // Git diff context lines
         ignoreExtensions: [],              // Extensions to exclude (e.g., ['.min.js', '.lock'])
         // NOTE: allowedExtensions comes from preset/template, not here
@@ -36,14 +37,14 @@ const defaults = {
     // Commit message generation
     commitMessage: {
         autoKeyword: 'auto',               // Keyword to trigger auto-generation
-        timeout: 180000,                   
+        timeout: 300000,
     },
 
     // Subagent configuration (parallel analysis)
     subagents: {
-        enabled: true,                     // Enable parallel file analysis
+        enabled: false,                    // Enable parallel file analysis
         model: 'haiku',                    // haiku (fast), sonnet (balanced), opus (thorough)
-        batchSize: 3,                      // Parallel subagents per batch
+        batchSize: 1,                      // Parallel subagents per batch
     },
 
     // Template paths
@@ -79,9 +80,9 @@ const defaults = {
 
 /**
  * Loads user configuration from .claude/config.json
- * Merges with defaults and preset config (preset -> user config takes priority)
+ * Merges with defaults and preset config (preset takes highest priority)
  *
- * Priority: defaults < preset config < user config
+ * Priority: defaults < user config < preset config
  *
  * @param {string} baseDir - Base directory to search for config (default: cwd)
  * @returns {Promise<Object>} Merged configuration
@@ -112,8 +113,8 @@ const loadUserConfig = async (baseDir = process.cwd()) => {
         }
     }
 
-    // Merge: defaults < preset < user
-    return deepMerge(deepMerge(defaults, presetConfig), userConfig);
+    // Merge: defaults < user < preset
+    return deepMerge(deepMerge(defaults, userConfig), presetConfig);
 };
 
 /**