pumuki-ast-hooks 5.3.18 → 5.3.19

package/docs/VIOLATIONS_RESOLUTION_PLAN.md

@@ -10,7 +10,7 @@
 ---
 
 ## 📊 Resumen Ejecutivo
-- **Estado actual:** ⚠️ Acción requerida (217 críticas, 1 alta, 117 medias, 211 bajas)  
+- **Estado actual:** ⚠️ Acción requerida (91 críticas, 0 altas, 30 medias, 14 bajas)  
 - **Branch:** `fix/audit-staged-severity-case-insensitive`  
 - **Fecha de inicio:** 30/12/2025 — **ETA general:** 15/01/2026  
 - **Objetivo:** Reducir a 0 las CRÍTICAS/HIGH y bajar el total < 20 antes de permitir commits sin bypass.  
@@ -35,7 +35,7 @@ gantt
     Auditoría de seguridad           :         crit3, after crit2, 3d
     Métricas Prometheus              :         crit4, after crit3, 2d
     Patrones de confiabilidad        :         crit5, after crit4, 2d
-
+ 
     section Fase 2: HIGH + MEDIUM
     Corrección HIGH                  :         high1, after crit5, 1d
     Refactorización MEDIUM           :         med1, after high1, 5d
@@ -46,50 +46,48 @@ gantt
 
 ---
 
-## 🔴 Fase 1: Violaciones CRÍTICAS (217)
+## 🔴 Fase 1: Violaciones CRÍTICAS (91)
 | Estado | Violación | Cant. | Responsable | DOD (Definition of Done) | Doc |
 |--------|-----------|-------|-------------|--------------------------|-----|
-| ✅ | backend.error.custom_exceptions | 105 | BE | CustomError base + reemplazo de `Error` genérico en BE; tests pasando | [Guía de excepciones](../docs/error-handling.md) |
-| ✅ | backend.config.missing_env_separation | 80 | BE | Config por entorno (dev/stg/prod), sin secretos hardcode | [Config entornos](../docs/env-configuration.md) |
-| ✅ | backend.security.missing_audit_logging | 69 | BE | Audit trail en operaciones sensibles + logs estructurados | [Audit logging](../docs/security-auditing.md) |
-| ✅ | backend.metrics.missing_prometheus | 64 | BE | Endpoints /metrics, instrumentación clave y dashboard base | [Prometheus](../docs/metrics-monitoring.md) |
-| ✅ | backend.reliability.missing_bulkhead | 40 | BE | Limitadores/aislamiento en puntos críticos + pruebas de carga | [Reliability](../docs/reliability-patterns.md) |
+| 🚧 | backend.observability.missing_prometheus | 45 | BE | Añadir métricas Prometheus a todos los servicios críticos; endpoints /metrics funcionando | [Prometheus](../docs/metrics-monitoring.md) |
+| ⏳ | backend.config.missing_env_separation | 27 | BE | Config por entorno (dev/stg/prod), sin secretos hardcode | [Config entornos](../docs/env-configuration.md) |
+| ⏳ | backend.security.missing_audit_logging | 23 | BE | Audit trail en operaciones sensibles + logs estructurados | [Audit logging](../docs/security-auditing.md) |
+| ⏳ | backend.error.custom_exceptions | 16 | BE | CustomError base + reemplazo de `Error` genérico en BE; tests pasando | [Guía de excepciones](../docs/error-handling.md) |
+| ⏳ | backend.reliability.missing_bulkhead | 10 | BE | Limitadores/aislamiento en puntos críticos + pruebas de carga | [Reliability](../docs/reliability-patterns.md) |
+| ⏳ | backend.event.emitter | 4 | BE | try/catch en manejadores de eventos; manejo de errores robusto | [Eventos](../docs/event-handling.md) |
+| ⏳ | backend.observability.missing_alerting | 3 | SRE | Alertas en métricas críticas; umbrales definidos | [Alerting](../docs/alerting-system.md) |
+| ⏳ | backend.config.missing_validation | 1 | BE | Validación de configuración al inicio | [Config validation](../docs/config-validation.md) |
+| ⏳ | backend.config.missing_env_validation | 1 | BE | Validación de variables de entorno requeridas | [Env validation](../docs/env-validation.md) |
+| ⏳ | backend.database.raw_sql | 1 | BE | Uso de ORM en lugar de raw SQL | [Database](../docs/database-layer.md) |
 
 ---
 
-## 🟠 Fase 2: Violaciones HIGH + MEDIUM (118)
+## 🟠 Fase 2: Violaciones HIGH + MEDIUM (30)
 | Estado | Violación | Cant. | Responsable | DOD | Doc |
 |--------|-----------|-------|-------------|-----|-----|
-| ✅ | HIGH (1) | 1 | BE | No aplica (repo JS puro sin TS); se documenta enfoque de seguridad de tipos | [Type safety](../docs/type-safety.md) |
-| ✅ | backend.testing.mocks | 40 | QA/BE | Mocks revisados; cobertura > 80% en módulos afectados | [Testing](../docs/testing-strategies.md) |
-| ✅ | backend.event.handler | 26 | BE | Handlers idempotentes + tests de eventos | [Eventos](../docs/event-handling.md) |
-| ⏳ | backend.observability.missing_prometheus | 24 | BE | Métricas por handler; dashboards mínimos | [Observabilidad](../docs/observability.md) |
-| ✅ | backend.auth.missing_cors | 17 | BE | No aplica al hook-system (no expone servidor HTTP); la detección queda en proyectos auditados | [CORS](../docs/cors-configuration.md) |
-| ✅ | backend.observability.missing_alerting | 10 | SRE | Alertas en métricas críticas; umbrales definidos | [Alerting](../docs/alerting-system.md) |
+| ✅ | HIGH | 0 | BE | No aplica (repo JS puro sin TS); se documenta enfoque de seguridad de tipos | [Type safety](../docs/type-safety.md) |
+| ⏳ | MEDIUM | 30 | BE | Resolver violaciones de complejidad media restantes | [Medium violations](../docs/medium-violations.md) |
 
 ---
 
-## 🔵 Fase 3: Violaciones LOW (211)
+## 🔵 Fase 3: Violaciones LOW (14)
 | Estado | Violación | Cant. | Responsable | DOD | Doc |
 |--------|-----------|-------|-------------|-----|-----|
-| ⏳ | frontend.code_quality.comment | 4 | FE | Comentarios depurados; lint OK | [Code standards](../docs/code-standards.md) |
-| ⏳ | frontend.code_quality.magic_number | 4 | FE | Constantes declaradas; tests ajustados | [Constantes](../docs/constants-vs-magic-numbers.md) |
-| ⏳ | frontend.devops.hardcoded_feature_flag | 2 | FE/DevOps | Flags externalizados por entorno | [Feature flags](../docs/feature-flags.md) |
-| ⏳ | frontend.performance.code_splitting | 2 | FE | Split aplicado en rutas pesadas; bundle size reducido | [Perf FE](../docs/frontend-performance.md) |
-| ⏳ | frontend.performance.missing_code_splitting | 2 | FE | Lazy loading habilitado en vistas grandes | [Code splitting](../docs/code-splitting.md) |
+| ⏳ | LOW | 14 | BE/FE | Resolver violaciones de baja prioridad restantes | [Low violations](../docs/low-violations.md) |
 
 ---
 
 ## 📈 Métricas de Progreso
 | Fase | Total | Completado | % |
 |------|-------|------------|---|
-| CRÍTICAS | 217 | 0 | 0% |
-| HIGH + MEDIUM | 118 | 0 | 0% |
-| LOW | 211 | 0 | 0% |
-| **TOTAL** | **546** | **0** | **0%** |
+| CRÍTICAS | 91 | 0 | 0% |
+| HIGH + MEDIUM | 30 | 0 | 0% |
+| LOW | 14 | 0 | 0% |
+| **TOTAL** | **135** | **0** | **0%** |
 
 **Riesgos actualizados:**  
 1) Implementación de Prometheus podría requerir cambios de infra; 2) Revisión de seguridad depende de disponibilidad de equipo; 3) Refactorizaciones pueden impactar tiempos.
 
 **Comentarios/Notas colaborativas:**  
 - Añade comentarios bajo cada tabla al cerrar tareas (usa la leyenda para actualizar estados).  
+- Progreso en métricas Prometheus: añadidas a 27 servicios, pero 45 violaciones restantes indican necesidad de más instrumentación.  

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pumuki-ast-hooks",
-  "version": "5.3.18",
+  "version": "5.3.19",
   "description": "Enterprise-grade AST Intelligence System with multi-platform support (iOS, Android, Backend, Frontend) and Feature-First + DDD + Clean Architecture enforcement. Includes dynamic violations API for intelligent querying.",
   "main": "index.js",
   "bin": {
@@ -116,4 +116,4 @@
     "./skills": "./skills/skill-rules.json",
     "./hooks": "./hooks/index.js"
   }
-}
+}

package/scripts/hooks-system/application/CompositionRoot.js

@@ -21,54 +21,19 @@ const TokenMonitor = require('./services/monitoring/TokenMonitor');
 const ActivityMonitor = require('./services/monitoring/ActivityMonitor');
 const DevDocsMonitor = require('./services/monitoring/DevDocsMonitor');
 const AstMonitor = require('./services/monitoring/AstMonitor');
-const AuditLogger = require('./services/logging/AuditLogger');
 
 const path = require('path');
 const fs = require('fs');
-const env = require('../config/env');
-
-// Import recordMetric for prometheus metrics
-const { recordMetric } = require('../infrastructure/telemetry/metrics-logger');
 
 class CompositionRoot {
     constructor(repoRoot) {
         this.repoRoot = repoRoot;
         this.instances = new Map();
 
-        this._initializeInfrastructure();
-        this._initializeServices();
-        this._initializeMonitors();
-    }
-
-    _initializeInfrastructure() {
         // Ensure audit directories exist
-        this.auditDir = path.join(this.repoRoot, '.audit-reports');
-        this.tempDir = path.join(this.repoRoot, '.audit_tmp');
+        this.auditDir = path.join(repoRoot, '.audit-reports');
+        this.tempDir = path.join(repoRoot, '.audit_tmp');
         this._ensureDirectories([this.auditDir, this.tempDir]);
-
-        // Audit log composition root creation
-        const auditLogger = this.getAuditLogger();
-        auditLogger.log({
-            action: 'composition_root_created',
-            category: 'system',
-            severity: 'info',
-            message: 'CompositionRoot initialized for dependency injection',
-            metadata: {
-                repoRoot: this.repoRoot,
-                auditDir: this.auditDir,
-                tempDir: this.tempDir
-            }
-        });
-    }
-
-    _initializeServices() {
-        // Services are created lazily when requested
-        // This reduces the initialization load
-    }
-
-    _initializeMonitors() {
-        // Monitors are created lazily when requested
-        // This reduces the initialization load
     }
 
     _ensureDirectories(dirs) {
@@ -86,7 +51,7 @@ class CompositionRoot {
                 file: {
                     enabled: true,
                     path: path.join(this.auditDir, 'guard-audit.jsonl'),
-                    level: env.get('HOOK_LOG_LEVEL', env.isProd ? 'warn' : 'info')
+                    level: process.env.HOOK_LOG_LEVEL || 'info'
                 },
                 console: {
                     enabled: false,
@@ -108,18 +73,6 @@ class CompositionRoot {
         return this.instances.get('notificationService');
     }
 
-    getAuditLogger() {
-        if (!this.instances.has('auditLogger')) {
-            const logger = this.getLogger();
-            this.instances.set('auditLogger', new AuditLogger({
-                repoRoot: this.repoRoot,
-                filename: path.join('.audit_tmp', 'audit.log'),
-                logger
-            }));
-        }
-        return this.instances.get('auditLogger');
-    }
-
     // --- Infrastructure Adapters ---
 
     getNotificationAdapter() {
@@ -230,9 +183,9 @@ class CompositionRoot {
     getEvidenceMonitor() {
         if (!this.instances.has('evidenceMonitor')) {
             this.instances.set('evidenceMonitor', new EvidenceMonitor(this.repoRoot, {
-                staleThresholdMs: env.getNumber('HOOK_GUARD_EVIDENCE_STALE_THRESHOLD', 180000),
-                pollIntervalMs: env.getNumber('HOOK_GUARD_EVIDENCE_POLL_INTERVAL', 30000),
-                reminderIntervalMs: env.getNumber('HOOK_GUARD_EVIDENCE_REMINDER_INTERVAL', 60000)
+                staleThresholdMs: Number(process.env.HOOK_GUARD_EVIDENCE_STALE_THRESHOLD || 180000),
+                pollIntervalMs: Number(process.env.HOOK_GUARD_EVIDENCE_POLL_INTERVAL || 30000),
+                reminderIntervalMs: Number(process.env.HOOK_GUARD_EVIDENCE_REMINDER_INTERVAL || 60000)
             }));
         }
         return this.instances.get('evidenceMonitor');
@@ -241,11 +194,11 @@ class CompositionRoot {
     getGitTreeMonitor() {
         if (!this.instances.has('gitTreeMonitor')) {
             this.instances.set('gitTreeMonitor', new GitTreeMonitor(this.repoRoot, {
-                stagedThreshold: env.getNumber('HOOK_GUARD_DIRTY_TREE_STAGED_LIMIT', 10),
-                unstagedThreshold: env.getNumber('HOOK_GUARD_DIRTY_TREE_UNSTAGED_LIMIT', 15),
-                totalThreshold: env.getNumber('HOOK_GUARD_DIRTY_TREE_TOTAL_LIMIT', 20),
-                checkIntervalMs: env.getNumber('HOOK_GUARD_DIRTY_TREE_INTERVAL', 60000),
-                reminderMs: env.getNumber('HOOK_GUARD_DIRTY_TREE_REMINDER', 300000)
+                stagedThreshold: Number(process.env.HOOK_GUARD_DIRTY_TREE_STAGED_LIMIT || 10),
+                unstagedThreshold: Number(process.env.HOOK_GUARD_DIRTY_TREE_UNSTAGED_LIMIT || 15),
+                totalThreshold: Number(process.env.HOOK_GUARD_DIRTY_TREE_TOTAL_LIMIT || 20),
+                checkIntervalMs: Number(process.env.HOOK_GUARD_DIRTY_TREE_INTERVAL || 60000),
+                reminderMs: Number(process.env.HOOK_GUARD_DIRTY_TREE_REMINDER || 300000)
             }));
         }
         return this.instances.get('gitTreeMonitor');
@@ -266,11 +219,11 @@ class CompositionRoot {
             const github = this.getGitHubAdapter();
 
             this.instances.set('gitFlowService', new GitFlowService(this.repoRoot, {
-                developBranch: env.get('HOOK_GUARD_GITFLOW_DEVELOP_BRANCH', 'develop'),
-                mainBranch: env.get('HOOK_GUARD_GITFLOW_MAIN_BRANCH', 'main'),
-                autoSyncEnabled: env.getBool('HOOK_GUARD_GITFLOW_AUTOSYNC', true),
-                autoCleanEnabled: env.getBool('HOOK_GUARD_GITFLOW_AUTOCLEAN', true),
-                requireClean: env.getBool('HOOK_GUARD_GITFLOW_REQUIRE_CLEAN', true)
+                developBranch: process.env.HOOK_GUARD_GITFLOW_DEVELOP_BRANCH || 'develop',
+                mainBranch: process.env.HOOK_GUARD_GITFLOW_MAIN_BRANCH || 'main',
+                autoSyncEnabled: process.env.HOOK_GUARD_GITFLOW_AUTOSYNC !== 'false',
+                autoCleanEnabled: process.env.HOOK_GUARD_GITFLOW_AUTOCLEAN !== 'false',
+                requireClean: process.env.HOOK_GUARD_GITFLOW_REQUIRE_CLEAN !== 'false'
             }, logger, gitQuery, gitCommand, github));
         }
         return this.instances.get('gitFlowService');
@@ -281,7 +234,7 @@ class CompositionRoot {
             const logger = this.getLogger();
             this.instances.set('activityMonitor', new ActivityMonitor({
                 repoRoot: this.repoRoot,
-                inactivityGraceMs: env.getNumber('HOOK_GUARD_INACTIVITY_GRACE_MS', 420000),
+                inactivityGraceMs: Number(process.env.HOOK_GUARD_INACTIVITY_GRACE_MS || 420000),
                 logger
             }));
         }
@@ -294,9 +247,9 @@ class CompositionRoot {
             const notificationService = this.getNotificationService();
             this.instances.set('devDocsMonitor', new DevDocsMonitor({
                 repoRoot: this.repoRoot,
-                checkIntervalMs: env.getNumber('HOOK_GUARD_DEV_DOCS_CHECK_INTERVAL', 300000),
-                staleThresholdMs: env.getNumber('HOOK_GUARD_DEV_DOCS_STALE_THRESHOLD', 86400000),
-                autoRefreshEnabled: env.getBool('HOOK_GUARD_DEV_DOCS_AUTO_REFRESH', true),
+                checkIntervalMs: Number(process.env.HOOK_GUARD_DEV_DOCS_CHECK_INTERVAL || 300000),
+                staleThresholdMs: Number(process.env.HOOK_GUARD_DEV_DOCS_STALE_THRESHOLD || 86400000),
+                autoRefreshEnabled: process.env.HOOK_GUARD_DEV_DOCS_AUTO_REFRESH !== 'false',
                 logger,
                 notificationService
             }));
@@ -310,9 +263,9 @@ class CompositionRoot {
             const notificationService = this.getNotificationService();
             this.instances.set('astMonitor', new AstMonitor({
                 repoRoot: this.repoRoot,
-                debounceMs: env.getNumber('HOOK_AST_WATCH_DEBOUNCE', 8000),
-                cooldownMs: env.getNumber('HOOK_AST_WATCH_COOLDOWN', 30000),
-                enabled: env.getBool('HOOK_AST_WATCH', true),
+                debounceMs: Number(process.env.HOOK_AST_WATCH_DEBOUNCE || 8000),
+                cooldownMs: Number(process.env.HOOK_AST_WATCH_COOLDOWN || 30000),
+                enabled: process.env.HOOK_AST_WATCH !== 'false',
                 logger,
                 notificationService
             }));
@@ -338,7 +291,6 @@ class CompositionRoot {
             const notificationService = this.getNotificationService();
             const monitors = this.getMonitors();
             const orchestrator = this.getOrchestrator();
-            const auditLogger = this.getAuditLogger();
             const config = {
                 debugLogPath: path.join(this.auditDir, 'guard-debug.log'),
                 repoRoot: this.repoRoot
@@ -349,8 +301,7 @@ class CompositionRoot {
                 notificationService,
                 monitors,
                 orchestration: orchestrator,
-                config,
-                auditLogger
+                config
             }));
         }
         return this.instances.get('guardService');

package/scripts/hooks-system/application/services/DynamicRulesLoader.js

@@ -1,6 +1,5 @@
 const fs = require('fs').promises;
 const path = require('path');
-const env = require('../config/env');
 
 class DynamicRulesLoader {
     constructor(rulesDirectory, logger = console) {
@@ -28,7 +27,7 @@ class DynamicRulesLoader {
             return [this.rulesDirectory];
         }
 
-        const envRaw = env.get('AST_RULES_DIRECTORIES');
+        const envRaw = process.env.AST_RULES_DIRECTORIES;
         if (envRaw && typeof envRaw === 'string' && envRaw.trim().length > 0) {
             return envRaw
                 .split(',')

package/scripts/hooks-system/application/services/GitTreeState.js

@@ -1,16 +1,53 @@
 const { execSync } = require('child_process');
 
+// Import recordMetric for prometheus metrics
+const { recordMetric } = require('../../../infrastructure/telemetry/metrics-logger');
+
 const extractFilePath = line => {
+    recordMetric({
+        hook: 'git_tree_state',
+        operation: 'extract_file_path',
+        status: 'started',
+        lineLength: line ? line.length : 0
+    });
+
     if (!line) {
+        recordMetric({
+            hook: 'git_tree_state',
+            operation: 'extract_file_path',
+            status: 'success',
+            result: ''
+        });
         return '';
     }
     if (line.startsWith('??')) {
-        return line.slice(3).trim();
+        const result = line.slice(3).trim();
+        recordMetric({
+            hook: 'git_tree_state',
+            operation: 'extract_file_path',
+            status: 'success',
+            resultLength: result.length
+        });
+        return result;
     }
-    return line.length > 3 ? line.slice(3).trim() : line.trim();
+    const result = line.length > 3 ? line.slice(3).trim() : line.trim();
+    recordMetric({
+        hook: 'git_tree_state',
+        operation: 'extract_file_path',
+        status: 'success',
+        resultLength: result.length
+    });
+    return result;
 };
 
 const buildStateFromStatus = (statusOutput = '') => {
+    recordMetric({
+        hook: 'git_tree_state',
+        operation: 'build_state_from_status',
+        status: 'started',
+        statusOutputLength: statusOutput ? statusOutput.length : 0
+    });
+
     const lines = statusOutput
         .split('\n')
         .map(entry => entry.replace(/\r$/, ''))
@@ -44,24 +81,51 @@ const buildStateFromStatus = (statusOutput = '') => {
 
     const uniqueSet = new Set([...stagedSet, ...workingSet]);
 
-    return {
+    const result = {
         stagedFiles: Array.from(stagedSet),
         workingFiles: Array.from(workingSet),
         stagedCount: stagedSet.size,
         workingCount: workingSet.size,
         uniqueCount: uniqueSet.size
     };
+
+    recordMetric({
+        hook: 'git_tree_state',
+        operation: 'build_state_from_status',
+        status: 'success',
+        stagedCount: stagedSet.size,
+        workingCount: workingSet.size,
+        uniqueCount: uniqueSet.size
+    });
+
+    return result;
 };
 
 const getGitTreeState = ({ repoRoot = process.cwd() } = {}) => {
+    recordMetric({
+        hook: 'git_tree_state',
+        operation: 'get_git_tree_state',
+        status: 'started',
+        repoRoot: repoRoot.substring(0, 100)
+    });
+
     try {
         const statusOutput = execSync('git status --porcelain', {
             cwd: repoRoot,
             encoding: 'utf8'
         });
-        return buildStateFromStatus(statusOutput);
+        const result = buildStateFromStatus(statusOutput);
+        recordMetric({
+            hook: 'git_tree_state',
+            operation: 'get_git_tree_state',
+            status: 'success',
+            stagedCount: result.stagedCount,
+            workingCount: result.workingCount,
+            uniqueCount: result.uniqueCount
+        });
+        return result;
     } catch (error) {
-        return {
+        const result = {
             stagedFiles: [],
             workingFiles: [],
             stagedCount: 0,
@@ -69,37 +133,92 @@ const getGitTreeState = ({ repoRoot = process.cwd() } = {}) => {
             uniqueCount: 0,
             error: error.message
         };
+        recordMetric({
+            hook: 'git_tree_state',
+            operation: 'get_git_tree_state',
+            status: 'failed',
+            error: error.message
+        });
+        return result;
     }
 };
 
 const isTreeBeyondLimit = (state, limits) => {
+    recordMetric({
+        hook: 'git_tree_state',
+        operation: 'is_tree_beyond_limit',
+        status: 'started',
+        hasState: !!state,
+        limitsType: typeof limits
+    });
+
     if (!state) {
+        recordMetric({
+            hook: 'git_tree_state',
+            operation: 'is_tree_beyond_limit',
+            status: 'success',
+            result: false
+        });
         return false;
     }
-    
+
     if (typeof limits === 'number') {
         const limit = limits;
         if (!Number.isFinite(limit) || limit <= 0) {
+            recordMetric({
+                hook: 'git_tree_state',
+                operation: 'is_tree_beyond_limit',
+                status: 'success',
+                result: false
+            });
             return false;
         }
-        return (
+        const result = (
             state.stagedCount > limit ||
             state.workingCount > limit ||
             state.uniqueCount > limit
         );
+        recordMetric({
+            hook: 'git_tree_state',
+            operation: 'is_tree_beyond_limit',
+            status: 'success',
+            result: result
+        });
+        return result;
     }
-    
+
     const { stagedLimit = 10, unstagedLimit = 15, totalLimit = 20 } = limits || {};
-    
+
     const stagedExceeded = Number.isFinite(stagedLimit) && stagedLimit > 0 && state.stagedCount > stagedLimit;
     const unstagedExceeded = Number.isFinite(unstagedLimit) && unstagedLimit > 0 && state.workingCount > unstagedLimit;
     const totalExceeded = Number.isFinite(totalLimit) && totalLimit > 0 && state.uniqueCount > totalLimit;
-    
-    return stagedExceeded || unstagedExceeded || totalExceeded;
+
+    const result = stagedExceeded || unstagedExceeded || totalExceeded;
+    recordMetric({
+        hook: 'git_tree_state',
+        operation: 'is_tree_beyond_limit',
+        status: 'success',
+        result: result
+    });
+    return result;
 };
 
 const summarizeTreeState = (state, limits) => {
+    recordMetric({
+        hook: 'git_tree_state',
+        operation: 'summarize_tree_state',
+        status: 'started',
+        hasState: !!state,
+        limitsType: typeof limits
+    });
+
     if (!state) {
+        recordMetric({
+            hook: 'git_tree_state',
+            operation: 'summarize_tree_state',
+            status: 'success',
+            result: 'no data'
+        });
         return 'no data';
     }
     const parts = [
@@ -107,7 +226,7 @@ const summarizeTreeState = (state, limits) => {
         `working ${state.workingCount}`,
         `unique ${state.uniqueCount}`
     ];
-    
+
     if (typeof limits === 'number') {
         const limit = limits;
         if (Number.isFinite(limit) && limit > 0) {
@@ -129,7 +248,14 @@ const summarizeTreeState = (state, limits) => {
             parts.push(`(${limitParts.join(', ')})`);
         }
     }
-    return parts.join(', ');
+    const result = parts.join(', ');
+    recordMetric({
+        hook: 'git_tree_state',
+        operation: 'summarize_tree_state',
+        status: 'success',
+        resultLength: result.length
+    });
+    return result;
 };
 
 module.exports = {

package/scripts/hooks-system/application/services/HookSystemScheduler.js

@@ -3,23 +3,66 @@ const HookSystemStateMachine = require('../state/HookSystemStateMachine');
 
 class HookSystemScheduler {
   constructor({ orchestrator, contextEngine, intervalMs = 30000 }) {
+    recordMetric({
+      hook: 'hook_system_scheduler',
+      operation: 'constructor',
+      status: 'started',
+      intervalMs
+    });
+
     this.orchestrator = orchestrator;
     this.contextEngine = contextEngine;
     this.intervalMs = intervalMs;
     this.stateMachine = new HookSystemStateMachine();
     this.timer = null;
+
+    recordMetric({
+      hook: 'hook_system_scheduler',
+      operation: 'constructor',
+      status: 'success',
+      intervalMs
+    });
   }
 
   start() {
+    recordMetric({
+      hook: 'hook_system_scheduler',
+      operation: 'start',
+      status: 'started',
+      intervalMs: this.intervalMs
+    });
+
     if (this.timer) return;
+
     this.timer = setInterval(() => this.tick(), this.intervalMs);
+
+    recordMetric({
+      hook: 'hook_system_scheduler',
+      operation: 'start',
+      status: 'success',
+      intervalMs: this.intervalMs
+    });
   }
 
   stop() {
+    recordMetric({
+      hook: 'hook_system_scheduler',
+      operation: 'stop',
+      status: 'started',
+      hadTimer: !!this.timer
+    });
+
     if (this.timer) {
       clearInterval(this.timer);
       this.timer = null;
     }
+
+    recordMetric({
+      hook: 'hook_system_scheduler',
+      operation: 'stop',
+      status: 'success',
+      hadTimer: !!this.timer
+    });
   }
 
   async tick() {

package/scripts/hooks-system/application/services/PlaybookRunner.js

@@ -18,7 +18,7 @@ class PlaybookRunner {
   run(id) {
     const playbook = this.playbooks[id];
     if (!playbook) {
-      throw new NotFoundError(`Playbook '${id}'`);
+      throw new Error(`Playbook '${id}' not found`);
     }
 
     for (const step of playbook.steps) {