pumuki-ast-hooks 5.3.20 → 5.3.22

package/scripts/hooks-system/infrastructure/ast/frontend/ast-frontend.js

@@ -57,8 +57,8 @@ function runFrontendIntelligence(project, findings, platform) {
       return 0.6745 * (x - med) / madValue;
     };
 
-    const pOutlier = Number(process.env.AST_GODCLASS_P_OUTLIER || 90);
-    const pExtreme = Number(process.env.AST_GODCLASS_P_EXTREME || 97);
+    const pOutlier = env.getNumber('AST_GODCLASS_P_OUTLIER', 90);
+    const pExtreme = env.getNumber('AST_GODCLASS_P_EXTREME', 97);
 
     const componentPattern = /^(export\s+)?(?:const|function)\s+([A-Z]\w+)\s*[=:].*(?:React\.FC|JSX\.Element|\(\)\s*=>|function)/gm;
     const metrics = [];
@@ -1129,10 +1129,10 @@ function runFrontendIntelligence(project, findings, platform) {
       }
       if (/page\.tsx$/.test(filePath)) {
         const candidate = filePath.replace(/\/app\//, '/e2e/').replace(/\.tsx$/, '.spec.ts');
-        try { 
-          if (!fs.existsSync(candidate)) { 
-            pushFinding("frontend.testing.missing_e2e", "info", sf, sf, "No E2E spec found for this page (heuristic)", findings); 
-          } 
+        try {
+          if (!fs.existsSync(candidate)) {
+            pushFinding("frontend.testing.missing_e2e", "info", sf, sf, "No E2E spec found for this page (heuristic)", findings);
+          }
         } catch (error) {
           if (process.env.DEBUG) {
             console.debug(`[frontend-ast] Failed to check E2E spec file: ${error.message}`);
@@ -1181,14 +1181,14 @@ function runFrontendIntelligence(project, findings, platform) {
           const extreme = totalComplexityZ >= godComponentBaseline.thresholds.extreme.totalComplexityZ || bodyLinesZ >= godComponentBaseline.thresholds.extreme.bodyLinesZ;
 
           if (extreme || (complexityOutlier && sizeOutlier)) {
-          pushFinding(
-            "frontend.solid.srp_god_component",
-            "critical",
-            sf,
-            sf,
-            `Component '${componentName}' has ${hookCount} hooks + ${functionCount} functions = ${totalComplexity} (z=${totalComplexityZ.toFixed(2)}), ${bodyLines} lines (z=${bodyLinesZ.toFixed(2)}) - split responsibilities (SRP)`,
-            findings
-          );
+            pushFinding(
+              "frontend.solid.srp_god_component",
+              "critical",
+              sf,
+              sf,
+              `Component '${componentName}' has ${hookCount} hooks + ${functionCount} functions = ${totalComplexity} (z=${totalComplexityZ.toFixed(2)}), ${bodyLines} lines (z=${bodyLinesZ.toFixed(2)}) - split responsibilities (SRP)`,
+              findings
+            );
           }
         }
       });
@@ -1823,269 +1823,269 @@ function runFrontendIntelligence(project, findings, platform) {
     }
 
     const useStateCallsInComponent = sf.getDescendantsOfKind(SyntaxKind.CallExpression)
-    .filter(call => call.getExpression().getText() === 'useState');
+      .filter(call => call.getExpression().getText() === 'useState');
+
+    sf.getDescendantsOfKind(SyntaxKind.FunctionDeclaration).forEach(fn => {
+      const name = fn.getName();
+      if (name && /^[A-Z]/.test(name)) {
+        const useStatesInFn = useStateCallsInComponent.filter(call =>
+          fn.getDescendants().includes(call)
+        );
+
+        if (useStatesInFn.length >= 4) {
+          pushFinding(
+            "frontend.hooks.useState_overuse",
+            "medium",
+            sf,
+            fn,
+            `Component ${name} has ${useStatesInFn.length}+ useState. Consider useReducer for complex state. Benefits: Single state object, predictable updates, easier testing.`,
+            findings
+          );
+        }
+      }
+    });
+
+    const contextCreations = sf.getDescendantsOfKind(SyntaxKind.CallExpression)
+      .filter(call => call.getExpression().getText() === 'createContext');
 
-  sf.getDescendantsOfKind(SyntaxKind.FunctionDeclaration).forEach(fn => {
-    const name = fn.getName();
-    if (name && /^[A-Z]/.test(name)) {
-      const useStatesInFn = useStateCallsInComponent.filter(call =>
-        fn.getDescendants().includes(call)
+    if (contextCreations.length >= 3 && !sf.getFilePath().includes('context')) {
+      pushFinding(
+        "frontend.state.context_overuse",
+        "medium",
+        sf,
+        sf,
+        `Multiple Context creations (${contextCreations.length}). Consider Zustand for global state. Context rerenders all consumers. Zustand: Selective subscriptions, better performance.`,
+        findings
       );
+    }
+
+    sf.getDescendantsOfKind(SyntaxKind.FunctionDeclaration).forEach(fn => {
+      const name = fn.getName();
+      const body = fn.getBody()?.getText() || '';
+      const hasHookCall = /use[A-Z]/.test(body);
 
-      if (useStatesInFn.length >= 4) {
+      if (name && hasHookCall && !/^use[A-Z]/.test(name)) {
         pushFinding(
-          "frontend.hooks.useState_overuse",
+          "frontend.hooks.naming_convention",
           "medium",
           sf,
           fn,
-          `Component ${name} has ${useStatesInFn.length}+ useState. Consider useReducer for complex state. Benefits: Single state object, predictable updates, easier testing.`,
+          `Function ${name} uses hooks but doesn't start with 'use'. Rename to use${name[0].toUpperCase()}${name.slice(1)}. React ESLint requires 'use' prefix for hook functions.`,
           findings
         );
       }
-    }
-  });
-
-  const contextCreations = sf.getDescendantsOfKind(SyntaxKind.CallExpression)
-    .filter(call => call.getExpression().getText() === 'createContext');
-
-  if (contextCreations.length >= 3 && !sf.getFilePath().includes('context')) {
-    pushFinding(
-      "frontend.state.context_overuse",
-      "medium",
-      sf,
-      sf,
-      `Multiple Context creations (${contextCreations.length}). Consider Zustand for global state. Context rerenders all consumers. Zustand: Selective subscriptions, better performance.`,
-      findings
-    );
-  }
+    });
 
-  sf.getDescendantsOfKind(SyntaxKind.FunctionDeclaration).forEach(fn => {
-    const name = fn.getName();
-    const body = fn.getBody()?.getText() || '';
-    const hasHookCall = /use[A-Z]/.test(body);
+    const fullText = sf.getFullText();
+    const hasLargeImports = fullText.includes('import * as') ||
+      fullText.match(/import\s+\{[^}]{200,}\}/);
 
-    if (name && hasHookCall && !/^use[A-Z]/.test(name)) {
+    if (hasLargeImports) {
       pushFinding(
-        "frontend.hooks.naming_convention",
+        "frontend.performance.large_imports",
         "medium",
         sf,
-        fn,
-        `Function ${name} uses hooks but doesn't start with 'use'. Rename to use${name[0].toUpperCase()}${name.slice(1)}. React ESLint requires 'use' prefix for hook functions.`,
+        sf,
+        'Large import detected. Use tree-shaking: import { Button } from \'@mui/material/Button\' (not from \'@mui/material\'). Reduces bundle size by importing only needed components.',
         findings
       );
     }
-  });
 
-  const fullText = sf.getFullText();
-  const hasLargeImports = fullText.includes('import * as') ||
-    fullText.match(/import\s+\{[^}]{200,}\}/);
-
-  if (hasLargeImports) {
-    pushFinding(
-      "frontend.performance.large_imports",
-      "medium",
-      sf,
-      sf,
-      'Large import detected. Use tree-shaking: import { Button } from \'@mui/material/Button\' (not from \'@mui/material\'). Reduces bundle size by importing only needed components.',
-      findings
-    );
-  }
+    if (content.includes('class') && content.includes('extends Component') &&
+      !content.includes('componentDidCatch') && !content.includes('getDerivedStateFromError')) {
 
-  if (content.includes('class') && content.includes('extends Component') &&
-    !content.includes('componentDidCatch') && !content.includes('getDerivedStateFromError')) {
+      const hasChildrenRender = content.includes('render()') && content.includes('children');
 
-    const hasChildrenRender = content.includes('render()') && content.includes('children');
+      if (hasChildrenRender) {
+        pushFinding(
+          "frontend.error_handling.missing_error_boundary",
+          "medium",
+          sf,
+          sf,
+          'Component renders children without error boundary. Add: componentDidCatch(error, errorInfo) { logError(error); }. Prevents whole app crash from single component error.',
+          findings
+        );
+      }
+    }
+
+    const hasRoutes = content.includes('Route') || content.includes('router');
+    const hasLazy = content.includes('React.lazy') || content.includes('dynamic(');
 
-    if (hasChildrenRender) {
+    if (hasRoutes && !hasLazy && sf.getFilePath().includes('app')) {
       pushFinding(
-        "frontend.error_handling.missing_error_boundary",
+        "frontend.performance.missing_lazy_loading",
         "medium",
         sf,
         sf,
-        'Component renders children without error boundary. Add: componentDidCatch(error, errorInfo) { logError(error); }. Prevents whole app crash from single component error.',
+        'Routes without lazy loading. Use: const Dashboard = lazy(() => import(\'./Dashboard\')). Wrap with <Suspense>. Reduces initial bundle, faster First Contentful Paint.',
         findings
       );
     }
-  }
 
-  const hasRoutes = content.includes('Route') || content.includes('router');
-  const hasLazy = content.includes('React.lazy') || content.includes('dynamic(');
-
-  if (hasRoutes && !hasLazy && sf.getFilePath().includes('app')) {
-    pushFinding(
-      "frontend.performance.missing_lazy_loading",
-      "medium",
-      sf,
-      sf,
-      'Routes without lazy loading. Use: const Dashboard = lazy(() => import(\'./Dashboard\')). Wrap with <Suspense>. Reduces initial bundle, faster First Contentful Paint.',
-      findings
-    );
-  }
 
+    if (sf.getFilePath().includes('layout.tsx') || sf.getFilePath().includes('page.tsx')) {
+      const hasMetadata = content.includes('metadata') || content.includes('generateMetadata');
+
+      if (!hasMetadata) {
+        pushFinding(
+          "frontend.seo.missing_metadata",
+          "low",
+          sf,
+          sf,
+          'Missing SEO metadata. Export: export const metadata = { title, description, openGraph }. Improves Google ranking, social media previews.',
+          findings
+        );
+      }
+    }
 
-  if (sf.getFilePath().includes('layout.tsx') || sf.getFilePath().includes('page.tsx')) {
-    const hasMetadata = content.includes('metadata') || content.includes('generateMetadata');
+    if (sf.getFilePath().includes('sitemap')) {
+      const hasDynamicRoutes = content.includes('fetch') || content.includes('database');
 
-    if (!hasMetadata) {
-      pushFinding(
-        "frontend.seo.missing_metadata",
-        "low",
-        sf,
-        sf,
-        'Missing SEO metadata. Export: export const metadata = { title, description, openGraph }. Improves Google ranking, social media previews.',
-        findings
-      );
+      if (!hasDynamicRoutes && content.length < 200) {
+        pushFinding(
+          "frontend.seo.static_sitemap",
+          "low",
+          sf,
+          sf,
+          'Static sitemap. Generate dynamically: fetch all routes from API/DB. Update automatically when content changes. Better SEO indexing.',
+          findings
+        );
+      }
     }
-  }
 
-  if (sf.getFilePath().includes('sitemap')) {
-    const hasDynamicRoutes = content.includes('fetch') || content.includes('database');
+    if (sf.getFilePath().includes('robots')) {
+      const hasDisallow = content.includes('Disallow');
 
-    if (!hasDynamicRoutes && content.length < 200) {
-      pushFinding(
-        "frontend.seo.static_sitemap",
-        "low",
-        sf,
-        sf,
-        'Static sitemap. Generate dynamically: fetch all routes from API/DB. Update automatically when content changes. Better SEO indexing.',
-        findings
-      );
+      if (!hasDisallow) {
+        pushFinding(
+          "frontend.seo.robots_config",
+          "low",
+          sf,
+          sf,
+          'Robots.txt incomplete. Add Disallow rules for: /api, /admin, /_next. Prevents search engines indexing private routes.',
+          findings
+        );
+      }
     }
-  }
 
-  if (sf.getFilePath().includes('robots')) {
-    const hasDisallow = content.includes('Disallow');
+    if (sf.getFilePath().includes('manifest')) {
+      const hasIcons = content.includes('icons');
+      const hasThemeColor = content.includes('theme_color');
+
+      if (!hasIcons || !hasThemeColor) {
+        pushFinding(
+          "frontend.pwa.manifest_incomplete",
+          "low",
+          sf,
+          sf,
+          'PWA manifest incomplete. Add: icons (192x192, 512x512), theme_color, background_color, display: standalone. Enables Add to Home Screen.',
+          findings
+        );
+      }
+    }
 
-    if (!hasDisallow) {
+    if (content.includes('serviceWorker') && !content.includes('unregister')) {
       pushFinding(
-        "frontend.seo.robots_config",
+        "frontend.pwa.missing_sw_unregister",
         "low",
         sf,
         sf,
-        'Robots.txt incomplete. Add Disallow rules for: /api, /admin, /_next. Prevents search engines indexing private routes.',
+        'Service Worker registration without unregister fallback. Add: if (!production) navigator.serviceWorker.unregister(). Prevents caching issues in development.',
         findings
       );
     }
-  }
 
-  if (sf.getFilePath().includes('manifest')) {
-    const hasIcons = content.includes('icons');
-    const hasThemeColor = content.includes('theme_color');
+    if (sf.getFilePath().includes('lighthouse') || sf.getFilePath().includes('performance')) {
+      const hasThresholds = content.includes('performance') && content.includes('accessibility');
+
+      if (!hasThresholds) {
+        pushFinding(
+          "frontend.performance.lighthouse_monitoring",
+          "low",
+          sf,
+          sf,
+          'Lighthouse config without thresholds. Set CI thresholds: performance: 90, accessibility: 95, best-practices: 90, seo: 90. Prevents performance regressions.',
+          findings
+        );
+      }
+    }
+
+    const hasWebVitals = content.includes('reportWebVitals') || content.includes('web-vitals');
+    const hasAnalytics = content.includes('analytics') || content.includes('gtag');
 
-    if (!hasIcons || !hasThemeColor) {
+    if (hasWebVitals && !hasAnalytics) {
       pushFinding(
-        "frontend.pwa.manifest_incomplete",
+        "frontend.monitoring.web_vitals_no_analytics",
         "low",
         sf,
         sf,
-        'PWA manifest incomplete. Add: icons (192x192, 512x512), theme_color, background_color, display: standalone. Enables Add to Home Screen.',
+        'Web Vitals captured but not sent to analytics. Send to Google Analytics: gtag(\'event\', metric.name, { value: metric.value }). Track LCP, FID, CLS in production.',
         findings
       );
     }
-  }
-
-  if (content.includes('serviceWorker') && !content.includes('unregister')) {
-    pushFinding(
-      "frontend.pwa.missing_sw_unregister",
-      "low",
-      sf,
-      sf,
-      'Service Worker registration without unregister fallback. Add: if (!production) navigator.serviceWorker.unregister(). Prevents caching issues in development.',
-      findings
-    );
-  }
-
-  if (sf.getFilePath().includes('lighthouse') || sf.getFilePath().includes('performance')) {
-    const hasThresholds = content.includes('performance') && content.includes('accessibility');
 
-    if (!hasThresholds) {
+    if (sf.getFilePath().includes('layout') && !content.includes('analytics') && !content.includes('gtag')) {
       pushFinding(
-        "frontend.performance.lighthouse_monitoring",
+        "frontend.monitoring.missing_analytics",
         "low",
         sf,
         sf,
-        'Lighthouse config without thresholds. Set CI thresholds: performance: 90, accessibility: 95, best-practices: 90, seo: 90. Prevents performance regressions.',
+        'Root layout without analytics. Add Google Analytics: <Script src="https://www.googletagmanager.com/gtag/js" />. Track user behavior, conversion rates.',
         findings
       );
     }
-  }
 
-  const hasWebVitals = content.includes('reportWebVitals') || content.includes('web-vitals');
-  const hasAnalytics = content.includes('analytics') || content.includes('gtag');
-
-  if (hasWebVitals && !hasAnalytics) {
-    pushFinding(
-      "frontend.monitoring.web_vitals_no_analytics",
-      "low",
-      sf,
-      sf,
-      'Web Vitals captured but not sent to analytics. Send to Google Analytics: gtag(\'event\', metric.name, { value: metric.value }). Track LCP, FID, CLS in production.',
-      findings
-    );
-  }
-
-  if (sf.getFilePath().includes('layout') && !content.includes('analytics') && !content.includes('gtag')) {
-    pushFinding(
-      "frontend.monitoring.missing_analytics",
-      "low",
-      sf,
-      sf,
-      'Root layout without analytics. Add Google Analytics: <Script src="https://www.googletagmanager.com/gtag/js" />. Track user behavior, conversion rates.',
-      findings
-    );
-  }
-
-  if (sf.getFilePath().includes('error.tsx') && !content.includes('Sentry') && !content.includes('captureException')) {
-    pushFinding(
-      "frontend.monitoring.missing_error_tracking",
-      "low",
-      sf,
-      sf,
-      'Error page without error tracking. Install: npm i @sentry/nextjs. Track production errors: Sentry.captureException(error). Get alerts when users hit errors.',
-      findings
-    );
-  }
-
-  if (content.includes('if (') && /feature|experiment|rollout|beta/i.test(content)) {
-    const hasFeatureFlagLib = content.includes('unleash') || content.includes('launchdarkly') || content.includes('flagsmith');
-
-    if (!hasFeatureFlagLib) {
+    if (sf.getFilePath().includes('error.tsx') && !content.includes('Sentry') && !content.includes('captureException')) {
       pushFinding(
-        "frontend.devops.hardcoded_feature_flag",
+        "frontend.monitoring.missing_error_tracking",
         "low",
         sf,
         sf,
-        'Hardcoded feature flag. Use feature flag service: Unleash, LaunchDarkly, Flagsmith. Benefits: Toggle features without deployment, gradual rollout, A/B testing.',
+        'Error page without error tracking. Install: npm i @sentry/nextjs. Track production errors: Sentry.captureException(error). Get alerts when users hit errors.',
         findings
       );
     }
-  }
 
-  if (content.includes('variant') && content.includes('Math.random')) {
-    pushFinding(
-      "frontend.devops.manual_ab_testing",
-      "low",
-      sf,
-      sf,
-      'Manual A/B testing with Math.random. Use: Google Optimize, Optimizely, VWO. Benefits: Statistical significance, reporting, targeting rules.',
-      findings
-    );
-  }
+    if (content.includes('if (') && /feature|experiment|rollout|beta/i.test(content)) {
+      const hasFeatureFlagLib = content.includes('unleash') || content.includes('launchdarkly') || content.includes('flagsmith');
 
-  if (content.includes('fetch') && !content.includes('cache') && !content.includes('revalidate')) {
-    const isFetchInServerComponent = content.includes('async function') && !content.includes('\'use client\'');
+      if (!hasFeatureFlagLib) {
+        pushFinding(
+          "frontend.devops.hardcoded_feature_flag",
+          "low",
+          sf,
+          sf,
+          'Hardcoded feature flag. Use feature flag service: Unleash, LaunchDarkly, Flagsmith. Benefits: Toggle features without deployment, gradual rollout, A/B testing.',
+          findings
+        );
+      }
+    }
 
-    if (isFetchInServerComponent) {
+    if (content.includes('variant') && content.includes('Math.random')) {
       pushFinding(
-        "frontend.performance.missing_cache_strategy",
+        "frontend.devops.manual_ab_testing",
         "low",
         sf,
         sf,
-        'Fetch without cache strategy. Add: { cache: \'force-cache\' } or { next: { revalidate: 3600 } }. Default behavior may change. Be explicit.',
+        'Manual A/B testing with Math.random. Use: Google Optimize, Optimizely, VWO. Benefits: Statistical significance, reporting, targeting rules.',
         findings
       );
     }
-  }
+
+    if (content.includes('fetch') && !content.includes('cache') && !content.includes('revalidate')) {
+      const isFetchInServerComponent = content.includes('async function') && !content.includes('\'use client\'');
+
+      if (isFetchInServerComponent) {
+        pushFinding(
+          "frontend.performance.missing_cache_strategy",
+          "low",
+          sf,
+          sf,
+          'Fetch without cache strategy. Add: { cache: \'force-cache\' } or { next: { revalidate: 3600 } }. Default behavior may change. Be explicit.',
+          findings
+        );
+      }
+    }
   });
 }
 

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

@@ -815,8 +815,9 @@ class iOSASTIntelligentAnalyzer {
       return 0.6745 * (x - med) / madValue;
     };
 
-    const pOutlier = Number(process.env.AST_GODCLASS_P_OUTLIER || 90);
-    const pExtreme = Number(process.env.AST_GODCLASS_P_EXTREME || 97);
+    const env = require('../../../../config/env');
+    const pOutlier = env.getNumber('AST_GODCLASS_P_OUTLIER', 90);
+    const pExtreme = env.getNumber('AST_GODCLASS_P_EXTREME', 97);
 
     const methods = this.godClassCandidates.map(c => c.methodsCount);
     const props = this.godClassCandidates.map(c => c.propertiesCount);

package/scripts/hooks-system/infrastructure/hooks/skill-activation-prompt.js

@@ -3,8 +3,9 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
+const env = require('../../../config/env');
 
-const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const projectDir = env.get('CLAUDE_PROJECT_DIR', process.cwd());
 const rulesPath = path.join(projectDir, '.cursor', 'ai-skills', 'skill-rules.json');
 const mdcRulesDir = path.join(projectDir, '.cursor', 'rules');
 const debugLogPath = path.join(projectDir, '.audit_tmp', 'skill-activation-debug.log');
@@ -54,7 +55,7 @@ function sendMacNotification(title, message) {
         return;
     }
 
-    const enabled = process.env.HOOK_GUARD_ENABLE_SKILL_ACTIVATION !== '0';
+    const enabled = env.getBool('HOOK_GUARD_ENABLE_SKILL_ACTIVATION', true);
     if (!enabled) {
         appendDebugLog('Notifications disabled via HOOK_GUARD_ENABLE_SKILL_ACTIVATION');
         return;

package/scripts/hooks-system/infrastructure/logging/UnifiedLoggerFactory.js

@@ -1,13 +1,14 @@
 const fs = require('fs');
 const path = require('path');
+const env = require('../../../config/env');
 
 const UnifiedLogger = require('../../application/services/logging/UnifiedLogger');
 
 function createUnifiedLogger({
     repoRoot = process.cwd(),
     component = 'HookSystem',
-    consoleLevel = process.env.HOOK_LOG_CONSOLE_LEVEL || 'info',
-    fileLevel = process.env.HOOK_LOG_FILE_LEVEL || 'debug',
+    consoleLevel = env.get('HOOK_LOG_CONSOLE_LEVEL', 'info'),
+    fileLevel = env.get('HOOK_LOG_FILE_LEVEL', 'debug'),
     fileName = null,
     defaultData = {}
 } = {}) {
@@ -17,8 +18,8 @@ function createUnifiedLogger({
     const logFileName = fileName || `${component.replace(/\s+/g, '-').toLowerCase()}.log`;
     const filePath = path.join(reportsDir, logFileName);
 
-    const maxSizeBytes = Number(process.env.HOOK_LOG_MAX_SIZE || 5 * 1024 * 1024);
-    const maxFiles = Number(process.env.HOOK_LOG_MAX_FILES || 5);
+    const maxSizeBytes = env.getNumber('HOOK_LOG_MAX_SIZE', 5 * 1024 * 1024);
+    const maxFiles = env.getNumber('HOOK_LOG_MAX_FILES', 5);
 
     return new UnifiedLogger({
         component,

package/scripts/hooks-system/infrastructure/mcp/ast-intelligence-automation.js

@@ -53,6 +53,94 @@ function resolveRepoRoot() {
 
 const REPO_ROOT = resolveRepoRoot();
 
+const MCP_LOCK_DIR = path.join(REPO_ROOT, '.audit_tmp', 'mcp-singleton.lock');
+const MCP_LOCK_PID = path.join(MCP_LOCK_DIR, 'pid');
+
+function isPidRunning(pid) {
+    if (!pid || !Number.isFinite(pid) || pid <= 0) return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function safeReadPid(filePath) {
+    try {
+        if (!fs.existsSync(filePath)) return null;
+        const raw = String(fs.readFileSync(filePath, 'utf8') || '').trim();
+        const pid = Number(raw);
+        if (!Number.isFinite(pid) || pid <= 0) return null;
+        return pid;
+    } catch {
+        return null;
+    }
+}
+
+function removeLockDir() {
+    try {
+        if (fs.existsSync(MCP_LOCK_PID)) {
+            fs.unlinkSync(MCP_LOCK_PID);
+        }
+    } catch {
+        // ignore
+    }
+    try {
+        if (fs.existsSync(MCP_LOCK_DIR)) {
+            fs.rmdirSync(MCP_LOCK_DIR);
+        }
+    } catch {
+        // ignore
+    }
+}
+
+function acquireSingletonLock() {
+    try {
+        fs.mkdirSync(path.join(REPO_ROOT, '.audit_tmp'), { recursive: true });
+    } catch {
+        // ignore
+    }
+
+    try {
+        fs.mkdirSync(MCP_LOCK_DIR);
+    } catch (error) {
+        const existingPid = safeReadPid(MCP_LOCK_PID);
+        if (existingPid && isPidRunning(existingPid)) {
+            process.stderr.write(`[MCP] Another instance is already running (pid ${existingPid}). Exiting.\n`);
+            process.exit(0);
+        }
+
+        removeLockDir();
+        fs.mkdirSync(MCP_LOCK_DIR);
+    }
+
+    try {
+        fs.writeFileSync(MCP_LOCK_PID, String(process.pid), { encoding: 'utf8' });
+    } catch {
+        // ignore
+    }
+
+    const cleanup = () => {
+        const pid = safeReadPid(MCP_LOCK_PID);
+        if (pid === process.pid) {
+            removeLockDir();
+        }
+    };
+
+    process.on('exit', cleanup);
+    process.on('SIGINT', () => {
+        cleanup();
+        process.exit(0);
+    });
+    process.on('SIGTERM', () => {
+        cleanup();
+        process.exit(0);
+    });
+}
+
+acquireSingletonLock();
+
 // Lazy-loaded CompositionRoot - only initialized when first needed
 let _compositionRoot = null;
 function getCompositionRoot() {