pumuki-ast-hooks 5.3.1

package/scripts/hooks-system/application/services/__tests__/RealtimeGuardService.critical.spec.js

@@ -0,0 +1,401 @@
+const path = require('path');
+const fs = require('fs');
+const { getGitTreeState, isTreeBeyondLimit } = require('../GitTreeState');
+
+jest.mock('../GitTreeState');
+jest.mock('../IntelligentGitTreeMonitor');
+jest.mock('../ContextDetectionEngine');
+jest.mock('../PlatformDetectionService');
+jest.mock('../AutonomousOrchestrator');
+jest.mock('../../use-cases/AutoExecuteAIStartUseCase');
+
+const RealtimeGuardService = require('../RealtimeGuardService');
+
+const EVIDENCE_PATH = path.join(process.cwd(), '.AI_EVIDENCE.json');
+
+function makeSUT(options = {}) {
+  const defaultOptions = {
+    notifier: jest.fn(),
+    notifications: true,
+    ...options,
+  };
+  const service = new RealtimeGuardService(defaultOptions);
+  jest.spyOn(fs, 'existsSync').mockReturnValue(true);
+  jest.spyOn(fs, 'mkdirSync').mockImplementation(() => {});
+  jest.spyOn(fs, 'readFileSync').mockReturnValue('{}');
+  jest.spyOn(fs, 'writeFileSync').mockImplementation(() => {});
+  jest.spyOn(fs, 'appendFileSync').mockImplementation(() => {});
+  jest.spyOn(fs, 'watch').mockReturnValue({ close: jest.fn() });
+  return service;
+}
+
+function createMockEvidence(timestamp) {
+  return {
+    timestamp: new Date(timestamp).toISOString(),
+    ai_gate: { status: 'ALLOWED' },
+  };
+}
+
+describe('RealtimeGuardService - Critical Methods', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.useFakeTimers();
+    process.env.HOOK_GUARD_AUTO_REFRESH = 'false';
+    process.env.HOOK_GUARD_EVIDENCE_STALE_THRESHOLD = '60000';
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  describe('readEvidenceTimestamp', () => {
+    it('should return timestamp when evidence file exists', () => {
+      const now = Date.now();
+      const evidence = createMockEvidence(now);
+      const service = makeSUT();
+      fs.existsSync.mockReturnValueOnce(true).mockReturnValueOnce(true);
+      fs.readFileSync.mockReturnValueOnce(JSON.stringify(evidence));
+      const timestamp = service.readEvidenceTimestamp();
+      expect(timestamp).toBe(now);
+    });
+
+    it('should return null when evidence file does not exist', () => {
+      const service = makeSUT();
+      fs.existsSync.mockReturnValue(false);
+      const timestamp = service.readEvidenceTimestamp();
+      expect(timestamp).toBeNull();
+    });
+
+    it('should return null when evidence file is invalid JSON', () => {
+      const service = makeSUT();
+      fs.existsSync.mockReturnValue(true);
+      fs.readFileSync.mockReturnValue('invalid json');
+      const timestamp = service.readEvidenceTimestamp();
+      expect(timestamp).toBeNull();
+    });
+
+    it('should return null when timestamp is invalid', () => {
+      const service = makeSUT();
+      fs.existsSync.mockReturnValue(true);
+      fs.readFileSync.mockReturnValue(JSON.stringify({ timestamp: 'invalid' }));
+      const timestamp = service.readEvidenceTimestamp();
+      expect(timestamp).toBeNull();
+    });
+  });
+
+  describe('evaluateEvidenceAge', () => {
+    it('should not trigger alert when evidence is fresh', () => {
+      const now = Date.now();
+      const freshTimestamp = now - 30000;
+      const evidence = createMockEvidence(freshTimestamp);
+      jest.spyOn(fs, 'existsSync').mockReturnValue(true);
+      jest.spyOn(fs, 'readFileSync').mockReturnValue(JSON.stringify(evidence));
+      const service = makeSUT();
+      jest.spyOn(service, 'readEvidenceTimestamp').mockReturnValue(freshTimestamp);
+      const notifySpy = jest.spyOn(service, 'notify');
+      service.evaluateEvidenceAge('test');
+      expect(notifySpy).not.toHaveBeenCalled();
+    });
+
+    it('should trigger stale alert when evidence is old', () => {
+      const now = Date.now();
+      const staleTimestamp = now - 120000;
+      const service = makeSUT();
+      service.lastUserActivityAt = now - 500000;
+      jest.spyOn(service, 'readEvidenceTimestamp').mockReturnValue(staleTimestamp);
+      const triggerSpy = jest.spyOn(service, 'triggerStaleAlert');
+      service.evaluateEvidenceAge('test');
+      expect(triggerSpy).toHaveBeenCalledWith('test', expect.any(Number));
+    });
+
+    it('should suppress stale alert when user activity is recent', () => {
+      const now = Date.now();
+      const staleTimestamp = now - 120000;
+      const service = makeSUT();
+      service.lastUserActivityAt = now - 10000;
+      jest.spyOn(service, 'readEvidenceTimestamp').mockReturnValue(staleTimestamp);
+      const triggerSpy = jest.spyOn(service, 'triggerStaleAlert');
+      service.evaluateEvidenceAge('test');
+      expect(triggerSpy).not.toHaveBeenCalled();
+    });
+
+    it('should notify fresh when evidence becomes fresh after being stale', () => {
+      const now = Date.now();
+      const freshTimestamp = now - 30000;
+      const service = makeSUT();
+      service.lastStaleNotification = now - 10000;
+      jest.spyOn(service, 'readEvidenceTimestamp').mockReturnValue(freshTimestamp);
+      const notifySpy = jest.spyOn(service, 'notify');
+      service.evaluateEvidenceAge('test', true);
+      expect(notifySpy).toHaveBeenCalledWith('Evidence updated; back within SLA.', 'info');
+    });
+  });
+
+  describe('triggerStaleAlert', () => {
+    it('should notify when evidence is stale', () => {
+      const service = makeSUT();
+      service.lastStaleNotification = 0;
+      const notifySpy = jest.spyOn(service, 'notify');
+      const attemptSpy = jest.spyOn(service, 'attemptAutoRefresh').mockResolvedValue();
+      service.triggerStaleAlert('test', 120000);
+      expect(notifySpy).toHaveBeenCalled();
+      expect(attemptSpy).toHaveBeenCalledWith('stale');
+    });
+
+    it('should respect reminder interval', () => {
+      const now = Date.now();
+      const service = makeSUT();
+      service.lastStaleNotification = now - 30000;
+      service.reminderIntervalMs = 60000;
+      const notifySpy = jest.spyOn(service, 'notify');
+      service.triggerStaleAlert('test', 120000);
+      expect(notifySpy).not.toHaveBeenCalled();
+    });
+
+    it('should format age message correctly', () => {
+      const service = makeSUT();
+      service.lastStaleNotification = 0;
+      service.staleThresholdMs = 60000;
+      const notifySpy = jest.spyOn(service, 'notify');
+      jest.spyOn(service, 'attemptAutoRefresh').mockResolvedValue();
+      service.triggerStaleAlert('test', 120000);
+      expect(notifySpy).toHaveBeenCalledWith(
+        expect.stringContaining('Evidence has been'),
+        'warn',
+        { forceDialog: true }
+      );
+    });
+  });
+
+  describe('evaluateGitTree', () => {
+    it('should handle clean git tree', async () => {
+      const cleanState = {
+        stagedCount: 0,
+        workingCount: 0,
+        uniqueCount: 0,
+      };
+      getGitTreeState.mockReturnValue(cleanState);
+      const service = makeSUT();
+      const resolveSpy = jest.spyOn(service, 'resolveDirtyTree');
+      await service.evaluateGitTree();
+      expect(resolveSpy).toHaveBeenCalledWith(cleanState, {
+        stagedLimit: service.gitTreeStagedThreshold,
+        unstagedLimit: service.gitTreeUnstagedThreshold,
+        totalLimit: service.gitTreeTotalThreshold
+      });
+    });
+
+    it('should handle dirty git tree beyond limit', async () => {
+      const dirtyState = {
+        stagedCount: 50,
+        workingCount: 60,
+        uniqueCount: 110,
+      };
+      getGitTreeState.mockReturnValue(dirtyState);
+      isTreeBeyondLimit.mockReturnValue(true);
+      const service = makeSUT();
+      const handleSpy = jest.spyOn(service, 'handleDirtyTree');
+      await service.evaluateGitTree();
+      expect(handleSpy).toHaveBeenCalledWith(dirtyState, {
+        stagedLimit: service.gitTreeStagedThreshold,
+        unstagedLimit: service.gitTreeUnstagedThreshold,
+        totalLimit: service.gitTreeTotalThreshold
+      });
+    });
+
+    it.skip('should use intelligent monitor for large trees', async () => {
+      const largeState = {
+        stagedCount: 10,
+        workingCount: 15,
+        uniqueCount: 25,
+      };
+      getGitTreeState.mockReturnValue(largeState);
+      isTreeBeyondLimit.mockReturnValue(false);
+      const service = makeSUT();
+      const mockNotify = jest.fn().mockResolvedValue();
+      const IntelligentGitTreeMonitor = require('../IntelligentGitTreeMonitor');
+      IntelligentGitTreeMonitor.mockImplementation(() => ({
+        notify: mockNotify,
+      }));
+      await service.evaluateGitTree();
+      expect(mockNotify).toHaveBeenCalled();
+    });
+
+    it.skip('should handle errors gracefully', async () => {
+      const service = makeSUT();
+      getGitTreeState.mockImplementation(() => {
+        throw new Error('Git error');
+      });
+      const appendSpy = jest.spyOn(service, 'appendDebugLog');
+      await service.evaluateGitTree();
+      expect(appendSpy).toHaveBeenCalledWith(expect.stringContaining('DIRTY_TREE_ERROR'));
+    });
+  });
+
+  describe('handleDirtyTree', () => {
+    it('should notify when tree is dirty', () => {
+      const dirtyState = {
+        stagedCount: 50,
+        workingCount: 60,
+        uniqueCount: 110,
+      };
+      const service = makeSUT();
+      service.lastDirtyTreeNotification = 0;
+      const notifySpy = jest.spyOn(service, 'notify');
+      service.handleDirtyTree(dirtyState, 100);
+      expect(notifySpy).toHaveBeenCalled();
+      expect(service.dirtyTreeActive).toBe(true);
+    });
+
+    it('should suppress notification within reminder interval', () => {
+      const now = Date.now();
+      const dirtyState = {
+        stagedCount: 50,
+        workingCount: 60,
+        uniqueCount: 110,
+      };
+      const service = makeSUT();
+      service.lastDirtyTreeNotification = now - 60000;
+      service.gitTreeReminderMs = 300000;
+      const notifySpy = jest.spyOn(service, 'notify');
+      service.handleDirtyTree(dirtyState, 100);
+      expect(notifySpy).not.toHaveBeenCalled();
+    });
+
+    it('should persist dirty tree state', () => {
+      const dirtyState = {
+        stagedCount: 50,
+        workingCount: 60,
+        uniqueCount: 110,
+      };
+      const service = makeSUT();
+      service.lastDirtyTreeNotification = 0;
+      const persistSpy = jest.spyOn(service, 'persistDirtyTreeState');
+      service.handleDirtyTree(dirtyState, 100);
+      expect(persistSpy).toHaveBeenCalled();
+    });
+  });
+
+  describe('attemptAutoRefresh', () => {
+    it('should skip when auto refresh is disabled', async () => {
+      process.env.HOOK_GUARD_AUTO_REFRESH = 'false';
+      const service = makeSUT();
+      const readSpy = jest.spyOn(service, 'readEvidenceTimestamp');
+      await service.attemptAutoRefresh('test');
+      expect(readSpy).not.toHaveBeenCalled();
+    });
+
+    it('should skip when update script does not exist', async () => {
+      process.env.HOOK_GUARD_AUTO_REFRESH = 'true';
+      const service = makeSUT();
+      fs.existsSync.mockImplementation((filePath) => {
+        if (filePath && filePath.includes('update-evidence.sh')) return false;
+        return true;
+      });
+      const readSpy = jest.spyOn(service, 'readEvidenceTimestamp');
+      await service.attemptAutoRefresh('test');
+      expect(readSpy).not.toHaveBeenCalled();
+    });
+
+    it('should skip when evidence is fresh', async () => {
+      process.env.HOOK_GUARD_AUTO_REFRESH = 'true';
+      const now = Date.now();
+      const freshTimestamp = now - 30000;
+      jest.spyOn(fs, 'existsSync').mockReturnValue(true);
+      const service = makeSUT();
+      jest.spyOn(service, 'readEvidenceTimestamp').mockReturnValue(freshTimestamp);
+      const refreshSpy = jest.spyOn(service, 'runDirectEvidenceRefresh');
+      await service.attemptAutoRefresh('test');
+      expect(refreshSpy).not.toHaveBeenCalled();
+    });
+
+    it('should skip when within cooldown period', async () => {
+      process.env.HOOK_GUARD_AUTO_REFRESH = 'true';
+      const now = Date.now();
+      const staleTimestamp = now - 120000;
+      jest.spyOn(fs, 'existsSync').mockReturnValue(true);
+      const service = makeSUT();
+      service.lastAutoRefresh = now - 10000;
+      service.autoRefreshCooldownMs = 180000;
+      jest.spyOn(service, 'readEvidenceTimestamp').mockReturnValue(staleTimestamp);
+      const refreshSpy = jest.spyOn(service, 'runDirectEvidenceRefresh');
+      await service.attemptAutoRefresh('test');
+      expect(refreshSpy).not.toHaveBeenCalled();
+    });
+
+    it('should skip when refresh is already in flight', async () => {
+      process.env.HOOK_GUARD_AUTO_REFRESH = 'true';
+      const now = Date.now();
+      const staleTimestamp = now - 120000;
+      jest.spyOn(fs, 'existsSync').mockReturnValue(true);
+      const service = makeSUT();
+      service.autoRefreshInFlight = true;
+      jest.spyOn(service, 'readEvidenceTimestamp').mockReturnValue(staleTimestamp);
+      const refreshSpy = jest.spyOn(service, 'runDirectEvidenceRefresh');
+      await service.attemptAutoRefresh('test');
+      expect(refreshSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('startGitTreeMonitoring', () => {
+    it('should start monitoring when threshold is valid', () => {
+      const service = makeSUT();
+      service.gitTreeStagedThreshold = 10;
+      service.gitTreeUnstagedThreshold = 15;
+      service.gitTreeTotalThreshold = 20;
+      service.gitTreeCheckIntervalMs = 60000;
+      const evaluateSpy = jest.spyOn(service, 'evaluateGitTree').mockResolvedValue();
+      service.startGitTreeMonitoring();
+      expect(evaluateSpy).toHaveBeenCalled();
+      expect(service.gitTreeTimer).toBeDefined();
+    });
+
+    it('should not start when threshold is invalid', () => {
+      const service = makeSUT();
+      service.gitTreeStagedThreshold = 0;
+      service.gitTreeUnstagedThreshold = 0;
+      service.gitTreeTotalThreshold = 0;
+      service.startGitTreeMonitoring();
+      expect(service.gitTreeTimer).toBeNull();
+    });
+
+    it('should not start when interval is zero', () => {
+      const service = makeSUT();
+      service.gitTreeStagedThreshold = 10;
+      service.gitTreeUnstagedThreshold = 15;
+      service.gitTreeTotalThreshold = 20;
+      service.gitTreeCheckIntervalMs = 0;
+      service.startGitTreeMonitoring();
+      expect(service.gitTreeTimer).toBeNull();
+    });
+  });
+
+  describe('startEvidencePolling', () => {
+    it('should start polling when interval is positive', () => {
+      const service = makeSUT();
+      service.pollIntervalMs = 30000;
+      const evaluateSpy = jest.spyOn(service, 'evaluateEvidenceAge');
+      service.startEvidencePolling();
+      expect(service.pollTimer).toBeDefined();
+      jest.advanceTimersByTime(30000);
+      expect(evaluateSpy).toHaveBeenCalledWith('polling');
+    });
+
+    it('should not start when interval is zero', () => {
+      const service = makeSUT();
+      service.pollIntervalMs = 0;
+      service.startEvidencePolling();
+      expect(service.pollTimer).toBeNull();
+    });
+
+    it('should clear existing timer before starting new one', () => {
+      const service = makeSUT();
+      service.pollIntervalMs = 30000;
+      service.pollTimer = setInterval(() => {}, 1000);
+      const clearSpy = jest.spyOn(global, 'clearInterval');
+      service.startEvidencePolling();
+      expect(clearSpy).toHaveBeenCalled();
+    });
+  });
+});
+

package/scripts/hooks-system/application/services/commit/CommitMessageGenerator.js

@@ -0,0 +1,34 @@
+class CommitMessageGenerator {
+    constructor(logger = console) {
+        this.logger = logger;
+    }
+
+    /**
+     * Generate commit message for a feature group
+     */
+    generate(group) {
+        const type = group.hasTests ? 'feat' : 'chore';
+        const scope = group.feature || group.module;
+        const platform = group.platform !== 'shared' ? `(${group.platform})` : '';
+
+        let message = `${type}${platform}(${scope}): `;
+
+        if (group.feature && group.feature !== 'unknown') {
+            message += `update ${group.feature} ${group.module}`;
+        } else {
+            message += `update ${group.module} files`;
+        }
+
+        if (group.hasTests) {
+            message += ' (includes tests)';
+        }
+
+        if (this.logger && this.logger.debug) {
+            this.logger.debug('COMMIT_MESSAGE_GENERATED', { group: group.module, message });
+        }
+
+        return message;
+    }
+}
+
+module.exports = CommitMessageGenerator;

package/scripts/hooks-system/application/services/commit/FeatureDetector.js

@@ -0,0 +1,101 @@
+class FeatureDetector {
+    constructor(logger = console) {
+        this.logger = logger;
+    }
+
+    /**
+     * Detect feature name from file path
+     * Returns null for non-feature files (config, scripts, docs)
+     */
+    detectFeature(filePath) {
+        const feature = this._detectFeatureStrategy(filePath);
+        if (feature && this.logger && this.logger.debug) {
+            // High volume log, maybe comment out or keep as debug
+            // this.logger.debug('FEATURE_DETECTED', { filePath, feature });
+        }
+        return feature;
+    }
+
+    _detectFeatureStrategy(filePath) {
+        if (filePath.startsWith(' D ') || filePath.includes('(deleted)')) {
+            return null;
+        }
+
+        if (filePath.match(/\.(json|yaml|yml|toml|lock)$/) &&
+            (filePath.includes('package.json') || filePath.includes('tsconfig') || filePath.includes('build'))) {
+            return null;
+        }
+
+        if (filePath.match(/\/bin\/|\/dist\/|\/build\/|\.(class|jar|o|so|dylib)$/)) {
+            return null;
+        }
+
+        const backendMatch = filePath.match(/apps\/backend\/src\/([^\/]+)/);
+        if (backendMatch) return backendMatch[1];
+
+        const frontendMatch = filePath.match(/apps\/(?:admin-dashboard|web-app)\/src\/([^\/]+)/);
+        if (frontendMatch) return frontendMatch[1];
+
+        const iosMatch = filePath.match(/apps\/ios\/([^\/]+)/);
+        if (iosMatch) return iosMatch[1];
+
+        const androidMatch = filePath.match(/apps\/android\/feature\/([^\/]+)/);
+        if (androidMatch) return androidMatch[1];
+
+        if (filePath.includes('hooks-system')) {
+            return 'hooks-system';
+        }
+
+        if (filePath.includes('.ast-intelligence/')) {
+            return 'ast-intelligence-config';
+        }
+
+        if (filePath.includes('docs/')) {
+            return 'docs';
+        }
+
+        if (filePath.match(/^(\.github|\.vscode|\.cursor|\.ast-intelligence)/)) {
+            return null;
+        }
+
+        return null;
+    }
+
+    /**
+     * Detect module/concern from file path
+     */
+    detectModule(filePath) {
+        if (filePath.includes('/domain/')) return 'domain';
+        if (filePath.includes('/application/')) return 'application';
+        if (filePath.includes('/infrastructure/')) return 'infrastructure';
+        if (filePath.includes('/presentation/')) return 'presentation';
+        if (filePath.includes('/data/')) return 'data';
+        if (filePath.includes('/ui/')) return 'ui';
+        if (filePath.includes('/hooks/')) return 'hooks';
+        if (filePath.includes('/components/')) return 'components';
+        return 'root';
+    }
+
+    /**
+     * Detect platform from file path
+     */
+    detectPlatform(filePath) {
+        if (filePath.includes('apps/backend')) return 'backend';
+        if (filePath.includes('apps/admin-dashboard') || filePath.includes('apps/web-app')) return 'frontend';
+        if (filePath.includes('apps/ios')) return 'ios';
+        if (filePath.includes('apps/android')) return 'android';
+        return 'shared';
+    }
+
+    /**
+     * Check if file is a test file
+     */
+    isTestFile(filePath) {
+        return /\.(test|spec)\.(ts|tsx|js|jsx|swift|kt)$/.test(filePath) ||
+            filePath.includes('/__tests__/') ||
+            filePath.includes('/test/') ||
+            filePath.includes('/tests/');
+    }
+}
+
+module.exports = FeatureDetector;

package/scripts/hooks-system/application/services/evidence/EvidenceContextManager.js

@@ -0,0 +1,163 @@
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { DomainError } = require('../../../domain/errors');
+
+const DEFAULT_PLATFORMS = ['1', '2', '3', '4'];
+
+function resolveUpdateEvidenceScript(repoRoot) {
+    const candidates = [
+        path.join(repoRoot, 'scripts/hooks-system/bin/update-evidence.sh'),
+        path.join(repoRoot, 'node_modules/@pumuki/ast-intelligence-hooks/bin/update-evidence.sh'),
+        path.join(repoRoot, 'bin/update-evidence.sh')
+    ];
+
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+
+    return null;
+}
+
+class EvidenceContextManager {
+    constructor({
+        repoRoot = process.cwd(),
+        updateScript = resolveUpdateEvidenceScript(repoRoot) || path.join(process.cwd(), 'scripts', 'hooks-system', 'bin', 'update-evidence.sh'),
+        thresholdSeconds = 180,
+        autoPlatforms = DEFAULT_PLATFORMS,
+        notificationCenter = null,
+        logger = console,
+        intervalMs = 0,
+        timers = { setInterval, clearInterval },
+        runCommand = EvidenceContextManager.runUpdateScript
+    } = {}) {
+        this.repoRoot = repoRoot;
+        this.updateScript = updateScript;
+        this.thresholdSeconds = thresholdSeconds;
+        this.autoPlatforms = Array.isArray(autoPlatforms) && autoPlatforms.length ? autoPlatforms : DEFAULT_PLATFORMS;
+        this.notificationCenter = notificationCenter;
+        this.logger = logger || console;
+        this.intervalMs = intervalMs;
+        this.timers = timers;
+        this.runCommand = runCommand;
+        this.timerRef = null;
+        this.refreshInProgress = false;
+    }
+
+    static runUpdateScript(scriptPath, platforms) {
+        const args = ['--auto', '--platforms', platforms.join(',')];
+        const result = spawnSync(scriptPath, args, { cwd: process.cwd(), stdio: 'pipe' });
+        if (result.error) {
+            throw result.error;
+        }
+        if (result.status !== 0) {
+            throw new DomainError(result.stderr?.toString() || `update script exited with ${result.status}`, 'SCRIPT_ERROR');
+        }
+        return {
+            stdout: result.stdout?.toString() || ''
+        };
+    }
+
+    start(reason = 'startup') {
+        this.ensureFresh(reason).catch(error => {
+            this.log('error', 'EVIDENCE_STARTUP_REFRESH_FAILED', { error: error.message });
+        });
+        if (this.intervalMs > 0) {
+            this.timerRef = this.timers.setInterval(() => {
+                this.ensureFresh('interval').catch(error => {
+                    this.log('error', 'EVIDENCE_INTERVAL_REFRESH_FAILED', { error: error.message });
+                });
+            }, this.intervalMs);
+            if (this.timerRef && typeof this.timerRef.unref === 'function') {
+                this.timerRef.unref();
+            }
+        }
+    }
+
+    stop() {
+        if (this.timerRef) {
+            this.timers.clearInterval(this.timerRef);
+            this.timerRef = null;
+        }
+    }
+
+    async ensureFresh(reason = 'manual') {
+        const info = this.readEvidence();
+        if (!info.valid || this.isStale(info.timestamp)) {
+            await this.refresh({ reason });
+            return { refreshed: true, reason };
+        }
+        return { refreshed: false, reason };
+    }
+
+    isStale(timestamp) {
+        if (!timestamp) {
+            return true;
+        }
+        const evidenceEpoch = Date.parse(timestamp);
+        if (!Number.isFinite(evidenceEpoch)) {
+            return true;
+        }
+        const diffSeconds = Math.floor((Date.now() - evidenceEpoch) / 1000);
+        return diffSeconds > this.thresholdSeconds;
+    }
+
+    readEvidence() {
+        try {
+            const target = path.join(this.repoRoot, '.AI_EVIDENCE.json');
+            if (!fs.existsSync(target)) {
+                return { valid: false };
+            }
+            const content = JSON.parse(fs.readFileSync(target, 'utf8'));
+            return {
+                valid: true,
+                timestamp: content.timestamp,
+                payload: content
+            };
+        } catch (error) {
+            this.log('warn', 'EVIDENCE_READ_FAILED', { error: error.message });
+            return { valid: false };
+        }
+    }
+
+    async refresh({ reason = 'auto', platforms = this.autoPlatforms } = {}) {
+        if (this.refreshInProgress) {
+            return { status: 'skipped', reason: 'in_progress' };
+        }
+        this.refreshInProgress = true;
+        try {
+            this.log('info', 'EVIDENCE_REFRESH_STARTED', { reason, platforms });
+            const result = await this.runCommand(this.updateScript, platforms);
+            this.log('info', 'EVIDENCE_REFRESH_COMPLETED', { reason, output: result.stdout });
+            this.notify(`AI evidence refreshed (${reason})`, 'info', { reason, platforms });
+            return { status: 'refreshed' };
+        } catch (error) {
+            this.log('error', 'EVIDENCE_REFRESH_FAILED', { reason, error: error.message });
+            this.notify(`AI evidence refresh failed: ${error.message}`, 'error', { reason });
+            throw error;
+        } finally {
+            this.refreshInProgress = false;
+        }
+    }
+
+    log(level, event, data = {}) {
+        if (this.logger && typeof this.logger[level] === 'function') {
+            this.logger[level](event, data);
+        }
+    }
+
+    notify(message, level, metadata = {}) {
+        if (this.notificationCenter && typeof this.notificationCenter.enqueue === 'function') {
+            this.notificationCenter.enqueue({
+                message,
+                level,
+                type: `evidence_${level}`,
+                metadata
+            });
+        }
+    }
+}
+
+module.exports = { EvidenceContextManager };