pumuki-ast-hooks 5.5.50 → 5.5.51

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pumuki-ast-hooks",
-  "version": "5.5.50",
+  "version": "5.5.51",
   "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": {

package/scripts/hooks-system/.audit_tmp/hook-metrics.jsonl

@@ -110,3 +110,51 @@
 {"timestamp":1767772971939,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
 {"timestamp":1767772971939,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
 {"timestamp":1767772971939,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767775802167,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767775802167,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767775802167,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767775802167,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767775833943,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767775833943,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767775833943,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767775833943,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767776135844,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767776135844,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767776135844,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767776135844,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767776384649,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767776384649,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767776384649,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767776384649,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767777653343,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767777653343,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767777653343,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767777653344,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767778142566,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767778142567,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767778142567,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767778142567,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767778800954,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767778800955,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767778800955,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767778800955,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767779528552,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767779528552,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767779528552,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767779528552,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767779903813,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767779903813,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767779903813,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767779903813,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767780497468,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767780497468,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767780497468,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767780497468,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767780655724,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767780655725,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767780655725,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767780655725,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767782291627,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767782291627,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767782291627,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767782291627,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}

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

@@ -130,33 +130,99 @@ class McpConfigurator {
             }
         };
 
-        const globalConfigPath = this.getGlobalWindsurfConfigPath();
-        const globalConfigDir = path.dirname(globalConfigPath);
-        if (!fs.existsSync(globalConfigDir)) {
-            fs.mkdirSync(globalConfigDir, { recursive: true });
-        }
+        this.configureProjectScoped(mcpConfig, serverId);
+        this.cleanupGlobalConfig(serverId);
+    }
+
+    configureProjectScoped(mcpConfig, serverId) {
+        const windsurfProjectDir = path.join(this.targetRoot, '.windsurf');
+        const windsurfProjectPath = path.join(windsurfProjectDir, 'mcp.json');
 
         try {
-            if (!fs.existsSync(globalConfigPath)) {
-                fs.writeFileSync(globalConfigPath, JSON.stringify(mcpConfig, null, 2));
-                this.logSuccess(`Configured global Windsurf MCP at ${globalConfigPath}`);
-                if (this.logger) this.logger.info('MCP_GLOBAL_CONFIGURED', { path: globalConfigPath });
-            } else {
-                const existing = JSON.parse(fs.readFileSync(globalConfigPath, 'utf8'));
+            if (!fs.existsSync(windsurfProjectDir)) {
+                fs.mkdirSync(windsurfProjectDir, { recursive: true });
+            }
+
+            let finalConfig = mcpConfig;
+            if (fs.existsSync(windsurfProjectPath)) {
+                const existing = JSON.parse(fs.readFileSync(windsurfProjectPath, 'utf8'));
                 if (!existing.mcpServers) existing.mcpServers = {};
+                Object.keys(existing.mcpServers).forEach(id => {
+                    if (id.startsWith('ast-intelligence-automation-') && id !== serverId) {
+                        delete existing.mcpServers[id];
+                    }
+                });
+                existing.mcpServers[serverId] = mcpConfig.mcpServers[serverId];
+                finalConfig = existing;
+            }
+
+            fs.writeFileSync(windsurfProjectPath, JSON.stringify(finalConfig, null, 2));
+            this.logSuccess(`Configured project-scoped Windsurf MCP at ${windsurfProjectPath}`);
+            if (this.logger) this.logger.info('MCP_PROJECT_CONFIGURED', { path: windsurfProjectPath, serverId });
+        } catch (error) {
+            this.logWarning(`Failed to configure project-scoped MCP: ${error.message}`);
+            if (this.logger) this.logger.warn('MCP_PROJECT_CONFIGURE_FAILED', { error: error.message });
+        }
 
-                // Prevent duplicate MCP servers for the same repoRoot by disabling legacy entries.
-                this.disableDuplicateServersForRepo(existing, serverId);
+        const cursorProjectDir = path.join(this.targetRoot, '.cursor');
+        const cursorProjectPath = path.join(cursorProjectDir, 'mcp.json');
 
+        try {
+            if (!fs.existsSync(cursorProjectDir)) {
+                fs.mkdirSync(cursorProjectDir, { recursive: true });
+            }
+
+            let finalConfig = mcpConfig;
+            if (fs.existsSync(cursorProjectPath)) {
+                const existing = JSON.parse(fs.readFileSync(cursorProjectPath, 'utf8'));
+                if (!existing.mcpServers) existing.mcpServers = {};
+                Object.keys(existing.mcpServers).forEach(id => {
+                    if (id.startsWith('ast-intelligence-automation-') && id !== serverId) {
+                        delete existing.mcpServers[id];
+                    }
+                });
                 existing.mcpServers[serverId] = mcpConfig.mcpServers[serverId];
+                finalConfig = existing;
+            }
+
+            fs.writeFileSync(cursorProjectPath, JSON.stringify(finalConfig, null, 2));
+            this.logSuccess(`Configured project-scoped Cursor MCP at ${cursorProjectPath}`);
+            if (this.logger) this.logger.info('MCP_CURSOR_CONFIGURED', { path: cursorProjectPath, serverId });
+        } catch (error) {
+            this.logWarning(`Failed to configure Cursor MCP: ${error.message}`);
+            if (this.logger) this.logger.warn('MCP_CURSOR_CONFIGURE_FAILED', { error: error.message });
+        }
+    }
+
+    cleanupGlobalConfig(currentServerId) {
+        const globalConfigPath = this.getGlobalWindsurfConfigPath();
 
+        try {
+            if (!fs.existsSync(globalConfigPath)) return;
+
+            const existing = JSON.parse(fs.readFileSync(globalConfigPath, 'utf8'));
+            if (!existing.mcpServers) return;
+
+            let modified = false;
+            Object.keys(existing.mcpServers).forEach(id => {
+                const server = existing.mcpServers[id];
+                if (!server || !server.env) return;
+
+                if (server.env.REPO_ROOT === this.targetRoot) {
+                    delete existing.mcpServers[id];
+                    modified = true;
+                    this.logInfo(`Removed ${id} from global config (now project-scoped)`);
+                }
+            });
+
+            if (modified) {
                 fs.writeFileSync(globalConfigPath, JSON.stringify(existing, null, 2));
-                this.logSuccess(`Updated global Windsurf MCP at ${globalConfigPath}`);
-                if (this.logger) this.logger.info('MCP_GLOBAL_UPDATED', { path: globalConfigPath });
+                if (this.logger) this.logger.info('MCP_GLOBAL_CLEANUP', { removedForRepo: this.targetRoot });
+            }
+        } catch (error) {
+            if (process.env.DEBUG) {
+                process.stderr.write(`[MCP] cleanupGlobalConfig failed: ${error.message}\n`);
             }
-        } catch (mergeError) {
-            this.logWarning(`${globalConfigPath} exists but couldn't be merged, skipping`);
-            if (this.logger) this.logger.warn('MCP_GLOBAL_MERGE_FAILED', { error: mergeError.message });
         }
     }
 

package/scripts/hooks-system/application/services/monitoring/EvidenceMonitor.js

@@ -1,7 +1,6 @@
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
-const { ConfigurationError, DomainError } = require('../../../domain/errors');
+const { EvidenceRefreshRunner } = require('./EvidenceRefreshRunner');
 const AuditLogger = require('../logging/AuditLogger');
 
 class EvidenceMonitor {
@@ -14,98 +13,9 @@ class EvidenceMonitor {
         this.lastStaleNotification = 0;
         this.pollTimer = null;
         this.evidencePath = path.join(repoRoot, '.AI_EVIDENCE.json');
-        this.tempDir = path.join(repoRoot, '.audit_tmp');
-        this.updateScript = this.resolveUpdateEvidenceScript();
-        this.refreshInFlight = false;
-        this.refreshTimeoutMs = options.refreshTimeoutMs || 120000;
-        this.refreshLockFile = path.join(this.tempDir, 'evidence-refresh.lock');
-    }
-
-    isPidRunning(pid) {
-        if (!pid || !Number.isFinite(pid) || pid <= 0) return false;
-        try {
-            process.kill(pid, 0);
-            return true;
-        } catch {
-            return false;
-        }
-    }
-
-    acquireRefreshLock() {
-        try {
-            fs.mkdirSync(this.tempDir, { recursive: true });
-        } catch (error) {
-            console.warn('[EvidenceMonitor] Failed to ensure temp dir:', error.message);
-        }
-
-        try {
-            const fd = fs.openSync(this.refreshLockFile, 'wx');
-            const payload = JSON.stringify({ pid: process.pid, timestamp: new Date().toISOString() });
-            fs.writeFileSync(fd, payload, { encoding: 'utf8' });
-            fs.closeSync(fd);
-            return { acquired: true };
-        } catch (error) {
-            if (error && error.code !== 'EEXIST') {
-                return { acquired: false, reason: 'error', error };
-            }
-
-            try {
-                const raw = String(fs.readFileSync(this.refreshLockFile, 'utf8') || '').trim();
-                const data = raw ? JSON.parse(raw) : null;
-                const lockPid = data && Number(data.pid);
-                if (lockPid && this.isPidRunning(lockPid)) {
-                    return { acquired: false, reason: 'locked', pid: lockPid };
-                }
-            } catch (error) {
-                console.warn('[EvidenceMonitor] Failed to read refresh lock file:', error.message);
-            }
-
-            try {
-                fs.unlinkSync(this.refreshLockFile);
-            } catch (error) {
-                console.warn('[EvidenceMonitor] Failed to remove stale refresh lock:', error.message);
-            }
-
-            try {
-                const fd = fs.openSync(this.refreshLockFile, 'wx');
-                const payload = JSON.stringify({ pid: process.pid, timestamp: new Date().toISOString() });
-                fs.writeFileSync(fd, payload, { encoding: 'utf8' });
-                fs.closeSync(fd);
-                return { acquired: true };
-            } catch (retryError) {
-                return { acquired: false, reason: 'locked', error: retryError };
-            }
-        }
-    }
-
-    releaseRefreshLock() {
-        try {
-            if (!fs.existsSync(this.refreshLockFile)) return;
-            const raw = String(fs.readFileSync(this.refreshLockFile, 'utf8') || '').trim();
-            const data = raw ? JSON.parse(raw) : null;
-            const lockPid = data && Number(data.pid);
-            if (lockPid === process.pid) {
-                fs.unlinkSync(this.refreshLockFile);
-            }
-        } catch (error) {
-            console.warn('[EvidenceMonitor] Failed to release refresh lock:', error.message);
-        }
-    }
-
-    resolveUpdateEvidenceScript() {
-        const candidates = [
-            path.join(this.repoRoot, 'node_modules/@pumuki/ast-intelligence-hooks/bin/update-evidence.sh'),
-            path.join(this.repoRoot, 'scripts/hooks-system/bin/update-evidence.sh'),
-            path.join(this.repoRoot, 'bin/update-evidence.sh')
-        ];
-
-        for (const candidate of candidates) {
-            if (fs.existsSync(candidate)) {
-                return candidate;
-            }
-        }
-
-        return null;
+        this.refreshRunner = new EvidenceRefreshRunner(repoRoot, {
+            refreshTimeoutMs: options.refreshTimeoutMs
+        });
     }
 
     isStale() {
@@ -123,58 +33,7 @@ class EvidenceMonitor {
     }
 
     async refresh() {
-        if (!this.updateScript) {
-            throw new ConfigurationError('Update evidence script not found', 'updateScript');
-        }
-
-        if (this.refreshInFlight) {
-            return '';
-        }
-
-        const lock = this.acquireRefreshLock();
-        if (!lock.acquired) {
-            return '';
-        }
-
-        this.refreshInFlight = true;
-
-        return new Promise((resolve, reject) => {
-            const child = require('child_process').spawn('bash', [this.updateScript, '--auto', '--refresh-only'], {
-                cwd: this.repoRoot,
-                stdio: ['pipe', 'pipe', 'pipe']
-            });
-
-            let output = '';
-            child.stdout.on('data', (data) => {
-                output += data.toString();
-            });
-
-            const timeoutId = setTimeout(() => {
-                try {
-                    child.kill('SIGKILL');
-                } catch (error) {
-                    console.warn('[EvidenceMonitor] Failed to kill timed-out refresh process:', error.message);
-                }
-            }, this.refreshTimeoutMs);
-
-            child.on('close', (code) => {
-                clearTimeout(timeoutId);
-                this.refreshInFlight = false;
-                this.releaseRefreshLock();
-                if (code === 0) {
-                    resolve(output);
-                } else {
-                    reject(new DomainError(`Evidence refresh failed with code ${code}`, 'EVIDENCE_REFRESH_FAILED'));
-                }
-            });
-
-            child.on('error', (err) => {
-                clearTimeout(timeoutId);
-                this.refreshInFlight = false;
-                this.releaseRefreshLock();
-                reject(err);
-            });
-        });
+        return this.refreshRunner.refresh();
     }
 
     startPolling(onStale, onRefreshed) {

package/scripts/hooks-system/application/services/monitoring/EvidenceRefreshRunner.js

@@ -0,0 +1,161 @@
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const { ConfigurationError, DomainError } = require('../../../domain/errors');
+
+class EvidenceRefreshRunner {
+    constructor(repoRoot, options = {}) {
+        this.repoRoot = repoRoot;
+        this.tempDir = path.join(repoRoot, '.audit_tmp');
+        this.refreshLockFile = path.join(this.tempDir, 'evidence-refresh.lock');
+        this.refreshTimeoutMs = options.refreshTimeoutMs || 120000;
+        this.refreshInFlight = false;
+        this.updateScript = this.resolveUpdateEvidenceScript();
+    }
+
+    resolveUpdateEvidenceScript() {
+        const candidates = [
+            path.join(this.repoRoot, 'node_modules/@pumuki/ast-intelligence-hooks/bin/update-evidence.sh'),
+            path.join(this.repoRoot, 'scripts/hooks-system/bin/update-evidence.sh'),
+            path.join(this.repoRoot, 'bin/update-evidence.sh')
+        ];
+
+        for (const candidate of candidates) {
+            if (fs.existsSync(candidate)) {
+                return candidate;
+            }
+        }
+
+        return null;
+    }
+
+    isPidRunning(pid) {
+        if (!pid || !Number.isFinite(pid) || pid <= 0) return false;
+        try {
+            process.kill(pid, 0);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    acquireRefreshLock() {
+        try {
+            fs.mkdirSync(this.tempDir, { recursive: true });
+        } catch (error) {
+            console.warn('[EvidenceRefreshRunner] Failed to ensure temp dir:', error.message);
+        }
+
+        try {
+            const fd = fs.openSync(this.refreshLockFile, 'wx');
+            const payload = JSON.stringify({ pid: process.pid, timestamp: new Date().toISOString() });
+            fs.writeFileSync(fd, payload, { encoding: 'utf8' });
+            fs.closeSync(fd);
+            return { acquired: true };
+        } catch (error) {
+            if (error && error.code !== 'EEXIST') {
+                return { acquired: false, reason: 'error', error };
+            }
+
+            try {
+                const raw = String(fs.readFileSync(this.refreshLockFile, 'utf8') || '').trim();
+                const data = raw ? JSON.parse(raw) : null;
+                const lockPid = data && Number(data.pid);
+                if (lockPid && this.isPidRunning(lockPid)) {
+                    return { acquired: false, reason: 'locked', pid: lockPid };
+                }
+            } catch (readError) {
+                console.warn('[EvidenceRefreshRunner] Failed to read refresh lock file:', readError.message);
+            }
+
+            try {
+                fs.unlinkSync(this.refreshLockFile);
+            } catch (removeError) {
+                console.warn('[EvidenceRefreshRunner] Failed to remove stale refresh lock:', removeError.message);
+            }
+
+            try {
+                const fd = fs.openSync(this.refreshLockFile, 'wx');
+                const payload = JSON.stringify({ pid: process.pid, timestamp: new Date().toISOString() });
+                fs.writeFileSync(fd, payload, { encoding: 'utf8' });
+                fs.closeSync(fd);
+                return { acquired: true };
+            } catch (retryError) {
+                return { acquired: false, reason: 'locked', error: retryError };
+            }
+        }
+    }
+
+    releaseRefreshLock() {
+        try {
+            if (!fs.existsSync(this.refreshLockFile)) return;
+            const raw = String(fs.readFileSync(this.refreshLockFile, 'utf8') || '').trim();
+            const data = raw ? JSON.parse(raw) : null;
+            const lockPid = data && Number(data.pid);
+            if (lockPid === process.pid) {
+                fs.unlinkSync(this.refreshLockFile);
+            }
+        } catch (error) {
+            console.warn('[EvidenceRefreshRunner] Failed to release refresh lock:', error.message);
+        }
+    }
+
+    async refresh() {
+        if (!this.updateScript) {
+            throw new ConfigurationError('Update evidence script not found', 'updateScript');
+        }
+
+        if (this.refreshInFlight) {
+            return '';
+        }
+
+        const lock = this.acquireRefreshLock();
+        if (!lock.acquired) {
+            return '';
+        }
+
+        this.refreshInFlight = true;
+
+        return new Promise((resolve, reject) => {
+            const child = spawn('bash', [this.updateScript, '--auto', '--refresh-only'], {
+                cwd: this.repoRoot,
+                stdio: ['pipe', 'pipe', 'pipe']
+            });
+
+            let output = '';
+            child.stdout.on('data', (data) => {
+                output += data.toString();
+            });
+
+            const timeoutId = setTimeout(() => {
+                try {
+                    child.kill('SIGKILL');
+                } catch (error) {
+                    console.warn('[EvidenceRefreshRunner] Failed to kill timed-out refresh process:', error.message);
+                }
+            }, this.refreshTimeoutMs);
+
+            const finalize = () => {
+                clearTimeout(timeoutId);
+                this.refreshInFlight = false;
+                this.releaseRefreshLock();
+            };
+
+            child.on('close', (code) => {
+                finalize();
+                if (code === 0) {
+                    resolve(output);
+                } else {
+                    reject(new DomainError(`Evidence refresh failed with code ${code}`, 'EVIDENCE_REFRESH_FAILED'));
+                }
+            });
+
+            child.on('error', (err) => {
+                finalize();
+                reject(err);
+            });
+        });
+    }
+}
+
+module.exports = { EvidenceRefreshRunner };

package/scripts/hooks-system/infrastructure/ast/ios/analyzers/StagedSwiftFilePreparer.js

@@ -0,0 +1,59 @@
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execSync } = require('child_process');
+
+class StagedSwiftFilePreparer {
+    constructor({ repoRoot, auditTmpDir }) {
+        this.repoRoot = repoRoot;
+        this.auditTmpDir = auditTmpDir || path.join(repoRoot, '.audit_tmp');
+    }
+
+    safeTempFilePath(displayPath) {
+        const hash = crypto.createHash('sha1').update(String(displayPath)).digest('hex').slice(0, 10);
+        const base = path.basename(displayPath, '.swift');
+        const filename = `${base}.${hash}.staged.swift`;
+        return path.join(this.auditTmpDir, filename);
+    }
+
+    readStagedFileContent(relPath) {
+        try {
+            return execSync(`git show :"${relPath}"`, {
+                encoding: 'utf8',
+                cwd: this.repoRoot,
+                stdio: ['ignore', 'pipe', 'pipe']
+            });
+        } catch (error) {
+            if (process.env.DEBUG) {
+                console.debug(`[StagedSwiftFilePreparer] Failed to read staged file ${relPath}: ${error.message}`);
+            }
+            return null;
+        }
+    }
+
+    prepare({ filePath, stagedRelPath, stagingOnly }) {
+        let parsePath = filePath;
+        let contentOverride = null;
+
+        if (stagingOnly && stagedRelPath) {
+            const stagedContent = this.readStagedFileContent(stagedRelPath);
+            if (typeof stagedContent === 'string') {
+                const tmpPath = this.safeTempFilePath(stagedRelPath);
+                try {
+                    fs.mkdirSync(path.dirname(tmpPath), { recursive: true });
+                    fs.writeFileSync(tmpPath, stagedContent, 'utf8');
+                    parsePath = tmpPath;
+                    contentOverride = stagedContent;
+                } catch (error) {
+                    if (process.env.DEBUG) {
+                        console.debug(`[StagedSwiftFilePreparer] Failed to write temp staged file ${tmpPath}: ${error.message}`);
+                    }
+                }
+            }
+        }
+
+        return { parsePath, contentOverride };
+    }
+}
+
+module.exports = { StagedSwiftFilePreparer };

package/scripts/hooks-system/infrastructure/ast/ios/analyzers/SwiftAstRunner.js

@@ -0,0 +1,51 @@
+const { execSync } = require('child_process');
+
+class SwiftAstRunner {
+    constructor({ toolchain }) {
+        this.toolchain = toolchain;
+    }
+
+    runSwiftSyntax(filePath, displayPath, findings) {
+        if (!this.toolchain.swiftSyntaxPath) return;
+
+        try {
+            const result = execSync(`"${this.toolchain.swiftSyntaxPath}" "${filePath}"`, {
+                encoding: 'utf8',
+                timeout: 30000,
+                stdio: ['pipe', 'pipe', 'pipe']
+            });
+            const violations = JSON.parse(result);
+            violations.forEach(v => {
+                findings.push({
+                    ruleId: v.ruleId,
+                    severity: String(v.severity || '').toUpperCase(),
+                    filePath: displayPath || filePath,
+                    line: v.line,
+                    column: v.column,
+                    message: v.message,
+                });
+            });
+        } catch (error) {
+            console.error('[SwiftAstRunner] Error parsing file with SwiftSyntax:', error.message);
+        }
+    }
+
+    parseSourceKitten(filePath) {
+        if (!this.toolchain.checkSourceKitten()) return null;
+
+        try {
+            const result = execSync(
+                `${this.toolchain.sourceKittenPath} structure --file "${filePath}"`,
+                { encoding: 'utf8', timeout: 30000, stdio: ['pipe', 'pipe', 'pipe'] }
+            );
+            return JSON.parse(result);
+        } catch (error) {
+            if (process.env.DEBUG) {
+                console.debug(`[SwiftAstRunner] SourceKitten parse failed for ${filePath}: ${error.message}`);
+            }
+            return null;
+        }
+    }
+}
+
+module.exports = { SwiftAstRunner };