pumuki-ast-hooks 5.3.19 → 5.3.21

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

@@ -21,9 +21,11 @@ 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');
 
 class CompositionRoot {
     constructor(repoRoot) {
@@ -51,7 +53,7 @@ class CompositionRoot {
                 file: {
                     enabled: true,
                     path: path.join(this.auditDir, 'guard-audit.jsonl'),
-                    level: process.env.HOOK_LOG_LEVEL || 'info'
+                    level: env.get('HOOK_LOG_LEVEL', env.isProd ? 'warn' : 'info')
                 },
                 console: {
                     enabled: false,
@@ -73,6 +75,18 @@ 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() {
@@ -183,9 +197,9 @@ class CompositionRoot {
     getEvidenceMonitor() {
         if (!this.instances.has('evidenceMonitor')) {
             this.instances.set('evidenceMonitor', new EvidenceMonitor(this.repoRoot, {
-                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)
+                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)
             }));
         }
         return this.instances.get('evidenceMonitor');
@@ -194,11 +208,11 @@ class CompositionRoot {
     getGitTreeMonitor() {
         if (!this.instances.has('gitTreeMonitor')) {
             this.instances.set('gitTreeMonitor', new GitTreeMonitor(this.repoRoot, {
-                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)
+                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)
             }));
         }
         return this.instances.get('gitTreeMonitor');
@@ -219,11 +233,11 @@ class CompositionRoot {
             const github = this.getGitHubAdapter();
 
             this.instances.set('gitFlowService', new GitFlowService(this.repoRoot, {
-                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'
+                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)
             }, logger, gitQuery, gitCommand, github));
         }
         return this.instances.get('gitFlowService');
@@ -234,7 +248,7 @@ class CompositionRoot {
             const logger = this.getLogger();
             this.instances.set('activityMonitor', new ActivityMonitor({
                 repoRoot: this.repoRoot,
-                inactivityGraceMs: Number(process.env.HOOK_GUARD_INACTIVITY_GRACE_MS || 420000),
+                inactivityGraceMs: env.getNumber('HOOK_GUARD_INACTIVITY_GRACE_MS', 420000),
                 logger
             }));
         }
@@ -247,9 +261,9 @@ class CompositionRoot {
             const notificationService = this.getNotificationService();
             this.instances.set('devDocsMonitor', new DevDocsMonitor({
                 repoRoot: this.repoRoot,
-                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',
+                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),
                 logger,
                 notificationService
             }));
@@ -263,9 +277,9 @@ class CompositionRoot {
             const notificationService = this.getNotificationService();
             this.instances.set('astMonitor', new AstMonitor({
                 repoRoot: this.repoRoot,
-                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',
+                debounceMs: env.getNumber('HOOK_AST_WATCH_DEBOUNCE', 8000),
+                cooldownMs: env.getNumber('HOOK_AST_WATCH_COOLDOWN', 30000),
+                enabled: env.getBool('HOOK_AST_WATCH', true),
                 logger,
                 notificationService
             }));
@@ -291,6 +305,7 @@ 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
@@ -301,7 +316,8 @@ class CompositionRoot {
                 notificationService,
                 monitors,
                 orchestration: orchestrator,
-                config
+                config,
+                auditLogger
             }));
         }
         return this.instances.get('guardService');

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

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

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

@@ -1,7 +1,8 @@
 const { execSync } = require('child_process');
+const path = require('path');
 
 // Import recordMetric for prometheus metrics
-const { recordMetric } = require('../../../infrastructure/telemetry/metrics-logger');
+const { recordMetric } = require(path.join(__dirname, '..', '..', 'infrastructure', 'telemetry', 'metrics-logger'));
 
 const extractFilePath = line => {
     recordMetric({

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 Error(`Playbook '${id}' not found`);
+      throw new NotFoundError(`Playbook '${id}'`);
     }
 
     for (const step of playbook.steps) {

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

@@ -1,6 +1,9 @@
 const fs = require('fs');
 const path = require('path');
 const { getGitTreeState, isTreeBeyondLimit } = require('./GitTreeState');
+const AuditLogger = require('./logging/AuditLogger');
+const { recordMetric } = require('../../infrastructure/telemetry/metrics-logger');
+const env = require('../../config/env');
 
 class RealtimeGuardService {
     /**
@@ -30,39 +33,42 @@ class RealtimeGuardService {
         this.monitors = monitors || {};
         this.orchestration = orchestration;
         this.config = config || {};
+        this.auditLogger = dependencies.auditLogger || new AuditLogger({ repoRoot: process.cwd(), logger: this.logger });
 
         if (!this.config.debugLogPath) {
             this.config.debugLogPath = path.join(process.cwd(), '.audit-reports', 'guard-debug.log');
         }
 
         this.evidencePath = this.config.evidencePath || path.join(process.cwd(), '.AI_EVIDENCE.json');
-        this.staleThresholdMs = Number(process.env.HOOK_GUARD_EVIDENCE_STALE_THRESHOLD || 60000);
-        this.reminderIntervalMs = Number(process.env.HOOK_GUARD_EVIDENCE_REMINDER_INTERVAL || 60000);
-        this.inactivityGraceMs = Number(process.env.HOOK_GUARD_INACTIVITY_GRACE_MS || 120000);
-        this.pollIntervalMs = Number(process.env.HOOK_GUARD_EVIDENCE_POLL_INTERVAL || 30000);
+        this.staleThresholdMs = env.getNumber('HOOK_GUARD_EVIDENCE_STALE_THRESHOLD', 60000);
+        this.reminderIntervalMs = env.getNumber('HOOK_GUARD_EVIDENCE_REMINDER_INTERVAL', 60000);
+        this.inactivityGraceMs = env.getNumber('HOOK_GUARD_INACTIVITY_GRACE_MS', 120000);
+        this.pollIntervalMs = env.getNumber('HOOK_GUARD_EVIDENCE_POLL_INTERVAL', 30000);
         this.pollTimer = null;
         this.lastStaleNotification = 0;
         this.lastUserActivityAt = 0;
 
-        this.gitTreeStagedThreshold = Number(process.env.HOOK_GUARD_DIRTY_TREE_STAGED_LIMIT || 10);
-        this.gitTreeUnstagedThreshold = Number(process.env.HOOK_GUARD_DIRTY_TREE_UNSTAGED_LIMIT || 15);
-        this.gitTreeTotalThreshold = Number(process.env.HOOK_GUARD_DIRTY_TREE_TOTAL_LIMIT || 20);
-        this.gitTreeCheckIntervalMs = Number(process.env.HOOK_GUARD_DIRTY_TREE_INTERVAL || 60000);
-        this.gitTreeReminderMs = Number(process.env.HOOK_GUARD_DIRTY_TREE_REMINDER || 300000);
+        this.gitTreeStagedThreshold = env.getNumber('HOOK_GUARD_DIRTY_TREE_STAGED_LIMIT', 10);
+        this.gitTreeUnstagedThreshold = env.getNumber('HOOK_GUARD_DIRTY_TREE_UNSTAGED_LIMIT', 15);
+        this.gitTreeTotalThreshold = env.getNumber('HOOK_GUARD_DIRTY_TREE_TOTAL_LIMIT', 20);
+        this.gitTreeCheckIntervalMs = env.getNumber('HOOK_GUARD_DIRTY_TREE_INTERVAL', 60000);
+        this.gitTreeReminderMs = env.getNumber('HOOK_GUARD_DIRTY_TREE_REMINDER', 300000);
         this.gitTreeTimer = null;
         this.lastDirtyTreeNotification = 0;
         this.dirtyTreeActive = false;
 
-        this.autoRefreshCooldownMs = Number(process.env.HOOK_GUARD_EVIDENCE_AUTO_REFRESH_COOLDOWN || 180000);
+        this.autoRefreshCooldownMs = env.getNumber('HOOK_GUARD_EVIDENCE_AUTO_REFRESH_COOLDOWN', 180000);
         this.lastAutoRefresh = 0;
         this.autoRefreshInFlight = false;
 
         this.watchers = [];
-        this.embedTokenMonitor = process.env.HOOK_GUARD_EMBEDDED_TOKEN_MONITOR === 'true';
+        this.embedTokenMonitor = env.getBool('HOOK_GUARD_EMBEDDED_TOKEN_MONITOR', false);
     }
 
     start() {
         this.logger.info('Starting RealtimeGuardService...');
+        this.auditLogger.record({ action: 'guard.realtime.start', resource: 'realtime_guard', status: 'success' });
+        recordMetric({ hook: 'realtime_guard', status: 'start' });
 
         // Start all monitors
         this._startEvidenceMonitoring();
@@ -82,6 +88,8 @@ class RealtimeGuardService {
 
     stop() {
         this.logger.info('Stopping RealtimeGuardService...');
+        this.auditLogger.record({ action: 'guard.realtime.stop', resource: 'realtime_guard', status: 'success' });
+        recordMetric({ hook: 'realtime_guard', status: 'stop' });
 
         this.watchers.forEach(w => w.close());
         this.watchers = [];
@@ -103,14 +111,27 @@ class RealtimeGuardService {
     }
 
     _startGitTreeMonitoring() {
-        if (process.env.HOOK_GUARD_DIRTY_TREE_DISABLED === 'true') return;
+        if (env.getBool('HOOK_GUARD_DIRTY_TREE_DISABLED', false)) return;
 
         this.monitors.gitTree.startMonitoring((state) => {
             if (state.isBeyondLimit) {
                 const message = `Git tree has too many files: ${state.total} total (${state.staged} staged, ${state.unstaged} unstaged)`;
                 this.notify(message, 'error', { forceDialog: true });
+                this.auditLogger.record({
+                    action: 'guard.git_tree.dirty',
+                    resource: 'git_tree',
+                    status: 'warning',
+                    meta: { total: state.total, staged: state.staged, unstaged: state.unstaged }
+                });
+                recordMetric({ hook: 'git_tree', status: 'dirty', total: state.total, staged: state.staged, unstaged: state.unstaged });
             } else {
                 this.notify('✅ Git tree is clean', 'success');
+                this.auditLogger.record({
+                    action: 'guard.git_tree.clean',
+                    resource: 'git_tree',
+                    status: 'success'
+                });
+                recordMetric({ hook: 'git_tree', status: 'clean' });
             }
         });
     }
@@ -124,22 +145,44 @@ class RealtimeGuardService {
         try {
             this.monitors.token.start();
             this.notify('🔋 Token monitor started', 'info');
+            this.auditLogger.record({
+                action: 'guard.token_monitor.start',
+                resource: 'token_monitor',
+                status: 'success'
+            });
+            recordMetric({ hook: 'token_monitor', status: 'start' });
         } catch (error) {
             this.notify(`Failed to start token monitor: ${error.message}`, 'error');
+            this.auditLogger.record({
+                action: 'guard.token_monitor.start',
+                resource: 'token_monitor',
+                status: 'fail',
+                meta: { message: error.message }
+            });
+            recordMetric({ hook: 'token_monitor', status: 'fail' });
         }
     }
 
     _startGitFlowSync() {
         if (!this.monitors.gitFlow.autoSyncEnabled) return;
 
+        this.auditLogger.record({
+            action: 'guard.gitflow.autosync.enabled',
+            resource: 'gitflow',
+            status: 'success',
+            meta: { intervalMs: env.getNumber('HOOK_GUARD_GITFLOW_AUTOSYNC_INTERVAL', 300000) }
+        });
+        recordMetric({ hook: 'gitflow_autosync', status: 'enabled' });
+
         const syncInterval = setInterval(() => {
             if (this.monitors.gitFlow.isClean()) {
                 const result = this.monitors.gitFlow.syncBranches();
                 if (result.success) {
                     this.notify('🔄 Branches synchronized', 'info');
+                    recordMetric({ hook: 'gitflow_autosync', status: 'sync_success' });
                 }
             }
-        }, Number(process.env.HOOK_GUARD_GITFLOW_AUTOSYNC_INTERVAL || 300000));
+        }, env.getNumber('HOOK_GUARD_GITFLOW_AUTOSYNC_INTERVAL', 300000));
 
         syncInterval.unref();
     }
@@ -247,11 +290,18 @@ class RealtimeGuardService {
         this.lastStaleNotification = now;
         const ageSec = Math.floor(ageMs / 1000);
         this.notify(`Evidence has been stale for ${ageSec}s (source: ${source}).`, 'warn', { forceDialog: true });
+        this.auditLogger.record({
+            action: 'guard.evidence.stale',
+            resource: 'evidence',
+            status: 'warning',
+            meta: { ageSec, source }
+        });
+        recordMetric({ hook: 'evidence', status: 'stale', ageSec, source });
         void this.attemptAutoRefresh('stale');
     }
 
     async attemptAutoRefresh(reason = 'manual') {
-        if (process.env.HOOK_GUARD_AUTO_REFRESH !== 'true') {
+        if (!env.getBool('HOOK_GUARD_AUTO_REFRESH', false)) {
             return;
         }
 
@@ -284,6 +334,13 @@ class RealtimeGuardService {
         try {
             await this.runDirectEvidenceRefresh(reason);
             this.lastAutoRefresh = now;
+            this.auditLogger.record({
+                action: 'guard.evidence.auto_refresh',
+                resource: 'evidence',
+                status: 'success',
+                meta: { reason }
+            });
+            recordMetric({ hook: 'evidence', status: 'auto_refresh_success', reason });
         } finally {
             this.autoRefreshInFlight = false;
         }

package/scripts/hooks-system/application/services/guard/GuardAutoManagerService.js

@@ -10,6 +10,9 @@ const GuardConfig = require('./GuardConfig');
 const GuardNotificationHandler = require('./GuardNotificationHandler');
 const GuardMonitorLoop = require('./GuardMonitorLoop');
 const GuardHealthReminder = require('./GuardHealthReminder');
+const AuditLogger = require('../logging/AuditLogger');
+const envHelper = require('../../../config/env');
+const { recordMetric } = require('../../../infrastructure/telemetry/metrics-logger');
 
 class GuardAutoManagerService {
     constructor({
@@ -19,9 +22,10 @@ class GuardAutoManagerService {
         fsModule = fs,
         childProcess = { spawnSync },
         timers = { setInterval, clearInterval },
-        env = process.env,
+        env = envHelper,
         processRef = process,
-        heartbeatMonitor = null
+        heartbeatMonitor = null,
+        auditLogger = null
     } = {}) {
         this.process = processRef;
 
@@ -30,6 +34,7 @@ class GuardAutoManagerService {
         this.eventLogger = new GuardEventLogger({ repoRoot, logger, fsModule });
         this.lockManager = new GuardLockManager({ repoRoot, logger, fsModule });
         this.processManager = new GuardProcessManager({ repoRoot, logger, fsModule, childProcess });
+        this.auditLogger = auditLogger || new AuditLogger({ repoRoot, logger });
 
         // Monitors & Handlers
         this.heartbeatMonitor = heartbeatMonitor || new GuardHeartbeatMonitor({
@@ -59,10 +64,14 @@ class GuardAutoManagerService {
     start() {
         if (!this.lockManager.acquireLock()) {
             this.eventLogger.log('Another guard auto manager instance detected. Exiting.');
+            this.auditLogger.record({ action: 'guard.lock.acquire', resource: 'guard_auto_manager', status: 'fail', meta: { reason: 'lock_exists' } });
+            recordMetric({ hook: 'guard_auto_manager', status: 'lock_fail' });
             return false;
         }
         this.lockManager.writePidFile();
         this.eventLogger.log('Guard auto manager started');
+        this.auditLogger.record({ action: 'guard.manager.start', resource: 'guard_auto_manager', status: 'success' });
+        recordMetric({ hook: 'guard_auto_manager', status: 'start' });
 
         this.ensureSupervisor('initial-start');
         this._startReminder();
@@ -94,6 +103,12 @@ class GuardAutoManagerService {
     handleMissingSupervisor() {
         this.lastHeartbeatState = { healthy: false, reason: 'missing-supervisor' };
         this.eventLogger.recordEvent('Guard supervisor no se encuentra en ejecución; reinicio automático.');
+        this.auditLogger.record({
+            action: 'guard.supervisor.missing',
+            resource: 'guard_supervisor',
+            status: 'fail',
+            meta: { reason: 'missing-supervisor' }
+        });
         this.ensureSupervisor('missing-supervisor');
     }
 
@@ -106,9 +121,21 @@ class GuardAutoManagerService {
                 this.eventLogger.log(`Heartbeat degraded (${heartbeat.reason}); attempting supervisor ensure.`);
                 this.lastHeartbeatRestart = now;
                 this.ensureSupervisor(`heartbeat-${heartbeat.reason}`);
+                this.auditLogger.record({
+                    action: 'guard.supervisor.ensure',
+                    resource: 'guard_supervisor',
+                    status: 'success',
+                    meta: { reason: heartbeat.reason }
+                });
             } else {
                 this.eventLogger.log(`Heartbeat degraded (${heartbeat.reason}); restart suppressed (cooldown).`);
                 this.eventLogger.recordEvent(`Heartbeat degradado (${heartbeat.reason}); reinicio omitido por cooldown.`);
+                this.auditLogger.record({
+                    action: 'guard.supervisor.ensure',
+                    resource: 'guard_supervisor',
+                    status: 'fail',
+                    meta: { reason: heartbeat.reason, suppressed: true }
+                });
             }
         } else {
             this.eventLogger.recordEvent(`Heartbeat en estado ${heartbeat.reason}; reinicio no requerido.`);
@@ -148,6 +175,8 @@ class GuardAutoManagerService {
         this.lockManager.removePidFile();
         this.lockManager.releaseLock();
         this.healthReminder.stop();
+        this.auditLogger.record({ action: 'guard.manager.stop', resource: 'guard_auto_manager', status: 'success' });
+        recordMetric({ hook: 'guard_auto_manager', status: 'stop' });
     }
 
     ensureSupervisor(reason) {

package/scripts/hooks-system/application/services/guard/GuardConfig.js

@@ -1,14 +1,22 @@
+const envHelper = require('../../../config/env');
+
 class GuardConfig {
-    constructor(env = process.env) {
-        this.healthyReminderIntervalMs = Number(env.GUARD_AUTOSTART_HEALTHY_INTERVAL || 0);
-        this.heartbeatNotifyCooldownMs = Number(env.GUARD_AUTOSTART_NOTIFY_COOLDOWN || 60000);
-        this.healthyReminderCooldownMs = Number(
-            env.GUARD_AUTOSTART_HEALTHY_COOLDOWN || (this.healthyReminderIntervalMs > 0 ? this.healthyReminderIntervalMs : 0)
+    constructor(env = envHelper) {
+        const getNumber = (name, def) =>
+            typeof env.getNumber === 'function' ? env.getNumber(name, def) : Number(env[name] || def);
+        const getBool = (name, def) =>
+            typeof env.getBool === 'function' ? env.getBool(name, def) : (env[name] !== 'false');
+
+        this.healthyReminderIntervalMs = getNumber('GUARD_AUTOSTART_HEALTHY_INTERVAL', 0);
+        this.heartbeatNotifyCooldownMs = getNumber('GUARD_AUTOSTART_NOTIFY_COOLDOWN', 60000);
+        this.healthyReminderCooldownMs = getNumber(
+            'GUARD_AUTOSTART_HEALTHY_COOLDOWN',
+            this.healthyReminderIntervalMs > 0 ? this.healthyReminderIntervalMs : 0
         );
-        this.heartbeatRestartCooldownMs = Number(env.GUARD_AUTOSTART_HEARTBEAT_COOLDOWN || 60000);
-        this.monitorIntervalMs = Number(env.GUARD_AUTOSTART_MONITOR_INTERVAL || 5000);
-        this.restartCooldownMs = Number(env.GUARD_AUTOSTART_RESTART_COOLDOWN || 2000);
-        this.stopSupervisorOnExit = env.GUARD_AUTOSTART_STOP_SUPERVISOR_ON_EXIT !== 'false';
+        this.heartbeatRestartCooldownMs = getNumber('GUARD_AUTOSTART_HEARTBEAT_COOLDOWN', 60000);
+        this.monitorIntervalMs = getNumber('GUARD_AUTOSTART_MONITOR_INTERVAL', 5000);
+        this.restartCooldownMs = getNumber('GUARD_AUTOSTART_RESTART_COOLDOWN', 2000);
+        this.stopSupervisorOnExit = getBool('GUARD_AUTOSTART_STOP_SUPERVISOR_ON_EXIT', true);
     }
 }
 

package/scripts/hooks-system/application/services/guard/GuardHeartbeatMonitor.js

@@ -1,29 +1,26 @@
 const fs = require('fs');
 const path = require('path');
+const env = require('../../../config/env');
 
 class GuardHeartbeatMonitor {
     constructor({
         repoRoot = process.cwd(),
         logger = console,
-        fsModule = fs,
-        env = process.env
+        fsModule = fs
     } = {}) {
         this.repoRoot = repoRoot;
         this.logger = logger;
         this.fs = fsModule;
-        this.env = env;
-
-        const heartbeatRelative = env.HOOK_GUARD_HEARTBEAT_PATH || path.join('.audit_tmp', 'guard-heartbeat.json');
+        const heartbeatRelative = env.get('HOOK_GUARD_HEARTBEAT_PATH', path.join('.audit_tmp', 'guard-heartbeat.json'));
         this.heartbeatPath = path.isAbsolute(heartbeatRelative)
             ? heartbeatRelative
             : path.join(this.repoRoot, heartbeatRelative);
 
-        this.heartbeatMaxAgeMs = Number(
-            env.GUARD_AUTOSTART_HEARTBEAT_MAX_AGE || env.HOOK_GUARD_HEARTBEAT_MAX_AGE || 60000
-        );
+        this.heartbeatMaxAgeMs = env.getNumber('GUARD_AUTOSTART_HEARTBEAT_MAX_AGE',
+            env.getNumber('HOOK_GUARD_HEARTBEAT_MAX_AGE', 60000));
 
         this.heartbeatRestartReasons = new Set(
-            (env.GUARD_AUTOSTART_HEARTBEAT_RESTART || 'missing,stale,invalid,degraded')
+            (env.get('GUARD_AUTOSTART_HEARTBEAT_RESTART', 'missing,stale,invalid,degraded'))
                 .split(',')
                 .map(entry => entry.trim().toLowerCase())
                 .filter(Boolean)

package/scripts/hooks-system/application/services/guard/GuardProcessManager.js

@@ -15,6 +15,7 @@ class GuardProcessManager {
 
         this.supervisorPidFile = path.join(this.repoRoot, '.guard-supervisor.pid');
         this.startScript = path.join(this.repoRoot, 'bin', 'start-guards.sh');
+        this.busy = false;
     }
 
     isSupervisorRunning() {
@@ -58,6 +59,15 @@ class GuardProcessManager {
     }
 
     startSupervisor() {
+        if (this.busy) {
+            return {
+                success: false,
+                error: new Error('bulkhead_busy'),
+                stdout: '',
+                stderr: 'bulkhead_busy'
+            };
+        }
+        this.busy = true;
         try {
             const result = this.childProcess.spawnSync(this.startScript, ['start'], {
                 cwd: this.repoRoot,
@@ -80,10 +90,21 @@ class GuardProcessManager {
                 stdout: '',
                 stderr: error.message
             };
+        } finally {
+            this.busy = false;
         }
     }
 
     stopSupervisor() {
+        if (this.busy) {
+            return {
+                success: false,
+                error: new Error('bulkhead_busy'),
+                stdout: '',
+                stderr: 'bulkhead_busy'
+            };
+        }
+        this.busy = true;
         try {
             const result = this.childProcess.spawnSync(this.startScript, ['stop'], {
                 cwd: this.repoRoot,
@@ -106,6 +127,8 @@ class GuardProcessManager {
                 stdout: '',
                 stderr: error.message
             };
+        } finally {
+            this.busy = false;
         }
     }
 }

package/scripts/hooks-system/application/services/installation/GitEnvironmentService.js

@@ -110,7 +110,7 @@ fi
 
 # Try node_modules/.bin first (works with npm install)
 if [ -f "node_modules/.bin/ast-hooks" ]; then
-  OUTPUT=$(node_modules/.bin/ast-hooks ast 2>&1)
+  OUTPUT=$(node_modules/.bin/ast-hooks ast --staged 2>&1)
   EXIT_CODE=$?
   echo "$OUTPUT"
   if [ $EXIT_CODE -ne 0 ]; then