vibecheck-ai 2.0.1 → 5.0.0

package/bin/runners/lib/analyzers.js

@@ -0,0 +1,2500 @@
+// bin/runners/lib/analyzers.js
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const fg = require("fast-glob");
+const crypto = require("crypto");
+const { URL } = require("url");
+const parser = require("@babel/parser");
+const traverse = require("@babel/traverse").default;
+const t = require("@babel/types");
+
+const { routeMatches } = require("./claims");
+const { matcherCoversPath } = require("./auth-truth");
+
+/* ============================================================================
+ * STANDARD IGNORE PATTERNS
+ * Used by all analyzers to exclude non-production code
+ * ========================================================================== */
+const STANDARD_IGNORE_PATTERNS = [
+  // Core excludes
+  "**/node_modules/**",
+  "**/.next/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/*.d.ts",
+  "**/*.d.ts.map",
+  // Test files
+  "**/__tests__/**",
+  "**/tests/**",
+  "**/*.test.ts",
+  "**/*.test.tsx",
+  "**/*.test.js",
+  "**/*.spec.ts",
+  "**/*.spec.tsx",
+  "**/*.spec.js",
+  "**/fixtures/**",
+  // Internal tooling
+  "**/mcp-server/**",
+  "**/bin/**",
+  "**/packages/cli/**",
+  // Examples and templates
+  "**/examples/**",
+  "**/templates/**",
+  "**/docs/**",
+  // Cache and generated
+  "**/.guardrail/**",
+  "**/.cursor/**",
+  "**/.vibecheck/**",
+  "**/coverage/**",
+  "**/_archive/**",
+];
+
+/* ============================================================================
+ * WORLD-CLASS INFRA HELPERS
+ * - file caching (speed + consistent evidence)
+ * - stable IDs (diff-friendly)
+ * - safe regex usage (fixes /g + .test() state bugs)
+ * - memory management (clearFileCache for monorepos)
+ * ========================================================================== */
+
+const _FILE_TEXT = new Map();
+const _FILE_LINES = new Map();
+
+function readFileCached(fileAbs) {
+  if (_FILE_TEXT.has(fileAbs)) return _FILE_TEXT.get(fileAbs);
+  const txt = fs.readFileSync(fileAbs, "utf8");
+  _FILE_TEXT.set(fileAbs, txt);
+  return txt;
+}
+
+function readLinesCached(fileAbs) {
+  if (_FILE_LINES.has(fileAbs)) return _FILE_LINES.get(fileAbs);
+  const lines = readFileCached(fileAbs).split(/\r?\n/);
+  _FILE_LINES.set(fileAbs, lines);
+  return lines;
+}
+
+/**
+ * V3: Clear file cache to prevent memory leaks in large monorepos.
+ * Call this after a scan completes or between major steps.
+ */
+function clearFileCache() {
+  _FILE_TEXT.clear();
+  _FILE_LINES.clear();
+}
+
+/**
+ * V3: Shannon Entropy calculator for detecting high-randomness strings (likely secrets).
+ * Entropy > 4.5 typically indicates a random/secret string vs structured data.
+ * Git SHAs (hex only) have lower effective entropy due to limited charset.
+ */
+function getShannonEntropy(str) {
+  if (!str || str.length === 0) return 0;
+  const len = str.length;
+  const frequencies = {};
+  for (let i = 0; i < len; i++) {
+    const char = str[i];
+    frequencies[char] = (frequencies[char] || 0) + 1;
+  }
+  
+  let entropy = 0;
+  for (const char in frequencies) {
+    const p = frequencies[char] / len;
+    entropy -= p * Math.log2(p);
+  }
+  return entropy;
+}
+
+function sha256(text) {
+  return "sha256:" + crypto.createHash("sha256").update(String(text || "")).digest("hex");
+}
+
+function stableId(prefix, key) {
+  const h = crypto.createHash("sha256").update(String(key || "")).digest("hex").slice(0, 10);
+  return `${prefix}_${h}`;
+}
+
+// IMPORTANT: /g + .test() is stateful. This helper makes it deterministic.
+function rxTest(rx, s) {
+  if (!rx) return false;
+  rx.lastIndex = 0;
+  return rx.test(s);
+}
+
+// Try to use the engine's globalASTCache if available for better performance
+let _globalASTCache = null;
+try {
+  _globalASTCache = require("./engine/ast-cache").globalASTCache;
+} catch {
+  // Engine not available, will use direct parsing
+}
+
+function parseFile(code, fileAbsForErrors = "") {
+  // Use globalASTCache if available (engine v2 integration)
+  if (_globalASTCache) {
+    const result = _globalASTCache.parse(code, fileAbsForErrors);
+    if (result.ast) return result.ast;
+    // Fall through to direct parse if cache failed
+  }
+  
+  // Error recovery avoids hard-failing on mixed TS/JS/JSX edge cases.
+  return parser.parse(code, {
+    sourceType: "unambiguous",
+    errorRecovery: true,
+    allowReturnOutsideFunction: true,
+    plugins: [
+      "typescript",
+      "jsx",
+      "dynamicImport",
+      "topLevelAwait",
+      "classProperties",
+      "classPrivateProperties",
+      "classPrivateMethods",
+      "decorators-legacy",
+      "optionalChaining",
+      "nullishCoalescingOperator",
+    ],
+  });
+}
+
+function evidenceFromLoc(fileAbs, repoRoot, loc, reason) {
+  if (!loc) return null;
+  const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+  const lines = readLinesCached(fileAbs);
+  const start = Math.max(1, loc.start?.line || 1);
+  const end = Math.max(start, loc.end?.line || start);
+  const snippet = lines.slice(start - 1, end).join("\n");
+  return {
+    id: stableId("ev", `${fileRel}:${start}-${end}:${reason || ""}:${sha256(snippet)}`),
+    file: fileRel,
+    lines: `${start}-${end}`,
+    snippetHash: sha256(snippet),
+    reason,
+  };
+}
+
+/* ============================================================================
+ * ROUTE GAP ENGINE (world-class missing route logic)
+ * ========================================================================== */
+
+function safeUrlParse(maybeUrl) {
+  try {
+    // URL() needs protocol; allow //host/path too
+    if (typeof maybeUrl !== "string") return null;
+    if (/^https?:\/\//i.test(maybeUrl)) return new URL(maybeUrl);
+    if (/^\/\//.test(maybeUrl)) return new URL("https:" + maybeUrl);
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function normalizePath(raw) {
+  if (!raw) return "/";
+  let p = String(raw).trim();
+
+  // If full URL, strip to pathname.
+  const u = safeUrlParse(p);
+  if (u) p = u.pathname || "/";
+
+  // Strip query/hash if present
+  p = p.split("?")[0].split("#")[0];
+
+  // Decode safely
+  try {
+    p = decodeURIComponent(p);
+  } catch {
+    // keep original
+  }
+
+  // Ensure leading slash
+  if (!p.startsWith("/")) p = "/" + p;
+
+  // Collapse duplicate slashes
+  p = p.replace(/\/{2,}/g, "/");
+
+  // Remove trailing slash (except root)
+  if (p.length > 1 && p.endsWith("/")) p = p.slice(0, -1);
+
+  return p;
+}
+
+function pathLooksLikeAsset(p) {
+  const s = String(p || "");
+  // Common Next/static + file extensions that are not API routes
+  if (/^\/(_next|static|assets)\b/i.test(s)) return true;
+  if (/\.(png|jpg|jpeg|gif|webp|svg|ico|css|js|map|txt|xml|woff2?|ttf|eot)$/i.test(s)) return true;
+  return false;
+}
+
+function isInternalUtilityRoute(p) {
+  // Common internal/utility routes that should NOT be flagged as missing
+  // These are typically framework-specific, monitoring, or debugging endpoints
+  const internalPatterns = [
+    // Health/monitoring
+    /^\/(health|healthz|healthcheck|ready|readyz|live|livez|liveness|readiness|metrics|status|ping|version)/i,
+    // Internal/debug
+    /^\/(debug|internal|_internal|__internal|security|\.well-known)/i,
+    // WebSockets
+    /^\/(websocket|ws|socket\.io|sockjs)/i,
+    // Admin/dashboard
+    /^\/(admin|dashboard|_admin|__admin)/i,
+    // Next.js internals
+    /^\/_next\//i,
+    // Vite/dev tools
+    /^\/@vite|^\/@fs|^\/__vite/i,
+    // GraphQL
+    /^\/(graphql|graphiql|playground)/i,
+    // Swagger/API docs
+    /^\/(swagger|api-docs|openapi|docs|redoc)/i,
+    // Auth callbacks
+    /^\/(auth|oauth|callback|login|logout|signin|signout)\/?(callback|redirect)?$/i,
+    // Common framework routes
+    /^\/(favicon\.ico|robots\.txt|sitemap\.xml|manifest\.json)$/i,
+    // Vercel/serverless
+    /^\/api\/_/i,
+    // Hidden paths
+    /^\/[._]/i,
+  ];
+  return internalPatterns.some(rx => rxTest(rx, p));
+}
+
+function looksInventedRoute(p) {
+  // Stuff AI loves to hallucinate - but be VERY precise to avoid false positives
+  // Only flag patterns that are CLEARLY fake/placeholder
+  
+  // Require routes to start with these patterns (not just contain them)
+  // This avoids flagging legitimate routes like /users/foo-bar-123
+  const clearlyFakeStarts = [
+    /^\/(fake|dummy|placeholder|asdf|qwerty|lorem|ipsum)\b/i,
+    /^\/(foo|bar|baz|xxx|yyy)$/i, // Only if it's the ENTIRE route segment
+  ];
+  
+  for (const rx of clearlyFakeStarts) {
+    if (rxTest(rx, p)) return true;
+  }
+  
+  // Obvious "ai generated" patterns - must be at route start
+  if (rxTest(/^\/(generated|auto[-_]?gen|ai[-_]?gen)\b/i, p)) return true;
+  
+  // Obvious placeholder test data patterns (test123, abc123, demo123)
+  // Only if the ENTIRE segment is clearly placeholder
+  if (rxTest(/\/(test123|abc123|demo123|sample123|example123)$/i, p)) return true;
+  
+  // Very long hex strings in route (32+ chars) that aren't IDs
+  // Skip if it looks like a valid UUID pattern or session token
+  const segments = p.split('/').filter(Boolean);
+  for (const seg of segments) {
+    // Long hex that's NOT a UUID format and NOT a reasonable ID length
+    if (/^[a-f0-9]{40,}$/i.test(seg) && !/^[a-f0-9]{8}-/.test(seg)) {
+      return true;
+    }
+  }
+  
+  return false;
+}
+
+function canonicalizeDynamicSegments(p) {
+  // Convert common dynamic segments to a stable token so "/users/123" can match "/users/:id"
+  // NOTE: This function returns a string, not a boolean - name is for canonicalization, not validation
+  const segs = normalizePath(p).split("/").filter(Boolean);
+  const canon = segs.map((seg) => {
+    if (!seg) return seg;
+    // UUID
+    if (rxTest(/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i, seg)) return ":id";
+    // Numeric IDs
+    if (rxTest(/^\d{1,18}$/i, seg)) return ":id";
+    // Long hex
+    if (rxTest(/^(0x)?[0-9a-f]{16,}$/i, seg)) return ":id";
+    // Next-ish catchalls
+    if (seg === "[...slug]" || seg === "[[...slug]]") return ":slug";
+    return seg;
+  });
+  return "/" + canon.join("/");
+}
+
+function firstSegment(p) {
+  const seg = normalizePath(p).split("/").filter(Boolean)[0];
+  return seg || "";
+}
+
+function inferDominantPrefix(paths, minShare = 0.7) {
+  // Find a dominant first segment like "api" across a set of paths
+  const counts = new Map();
+  for (const p of paths) {
+    const seg = firstSegment(p);
+    if (!seg) continue;
+    counts.set(seg, (counts.get(seg) || 0) + 1);
+  }
+  let best = { seg: "", n: 0 };
+  for (const [seg, n] of counts.entries()) {
+    if (n > best.n) best = { seg, n };
+  }
+  if (!best.seg) return null;
+  const share = best.n / Math.max(1, paths.length);
+  return share >= minShare ? "/" + best.seg : null;
+}
+
+function buildServerRouteIndex(serverRoutes) {
+  // Index by method + first segment for fast shortlist
+  const byMethod = new Map(); // method -> seg -> routes[]
+  const all = [];
+
+  for (const r of serverRoutes) {
+    const method = String(r.method || "*").toUpperCase();
+    const pNorm = normalizePath(r.path);
+    const seg = firstSegment(pNorm);
+
+    const rec = { ...r, _method: method, _pathNorm: pNorm, _seg: seg, _canon: canonicalizeDynamicSegments(pNorm) };
+    all.push(rec);
+
+    if (!byMethod.has(method)) byMethod.set(method, new Map());
+    const segMap = byMethod.get(method);
+    if (!segMap.has(seg)) segMap.set(seg, []);
+    segMap.get(seg).push(rec);
+
+    // Also index wildcard bucket
+    if (!byMethod.has("*")) byMethod.set("*", new Map());
+    const w = byMethod.get("*");
+    if (!w.has(seg)) w.set(seg, []);
+    w.get(seg).push(rec);
+  }
+
+  return { byMethod, all };
+}
+
+function shortlistServerRoutes(index, method, pNorm) {
+  const m = String(method || "*").toUpperCase();
+  const seg = firstSegment(pNorm);
+
+  const pick = (meth) => {
+    const segMap = index.byMethod.get(meth);
+    if (!segMap) return [];
+    const bucket = segMap.get(seg) || [];
+    // If seg is empty or dynamic roots exist, include a fallback bucket
+    const rootBucket = segMap.get("") || [];
+    return bucket.concat(rootBucket);
+  };
+
+  // prioritize exact method, then wildcard
+  const a = pick(m);
+  const b = pick("*");
+  // de-dupe by path+method
+  const seen = new Set();
+  const out = [];
+  for (const r of a.concat(b)) {
+    const k = `${r._method}:${r._pathNorm}`;
+    if (seen.has(k)) continue;
+    seen.add(k);
+    out.push(r);
+  }
+  return out.length ? out : index.all;
+}
+
+function routeSimilarityScore(refPath, serverPathPattern) {
+  // Score 0..1 based on static segment overlap + prefix alignment
+  const a = canonicalizeDynamicSegments(refPath).split("/").filter(Boolean);
+  const b = canonicalizeDynamicSegments(serverPathPattern).split("/").filter(Boolean);
+
+  if (!a.length || !b.length) return 0;
+
+  const aStatic = a.filter((s) => !s.startsWith(":") && !s.startsWith("["));
+  const bStatic = b.filter((s) => !s.startsWith(":") && !s.startsWith("["));
+
+  const setA = new Set(aStatic);
+  const setB = new Set(bStatic);
+
+  let inter = 0;
+  for (const s of setA) if (setB.has(s)) inter++;
+
+  const union = new Set([...setA, ...setB]).size || 1;
+
+  const jaccard = inter / union;
+
+  // prefix bonus if first 1-2 segments align
+  const prefix1 = a[0] && b[0] && a[0] === b[0] ? 0.15 : 0;
+  const prefix2 = a[1] && b[1] && a[1] === b[1] ? 0.10 : 0;
+
+  // length penalty if wildly different
+  const lenPenalty = Math.min(0.25, Math.abs(a.length - b.length) * 0.05);
+
+  const score = Math.max(0, Math.min(1, jaccard + prefix1 + prefix2 - lenPenalty));
+  return score;
+}
+
+function compileAllowPatterns(patterns) {
+  const out = [];
+  for (const p of patterns || []) {
+    if (!p) continue;
+    if (p instanceof RegExp) {
+      out.push(p);
+      continue;
+    }
+    const s = String(p);
+    // Support "/.../i" style
+    const m = s.match(/^\/(.+)\/([gimsuy]*)$/);
+    if (m) {
+      try {
+        out.push(new RegExp(m[1], m[2]));
+        continue;
+      } catch {
+        // fall through
+      }
+    }
+    // Simple wildcard "*" and "?" -> regex
+    const esc = s
+      .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+      .replace(/\*/g, ".*")
+      .replace(/\?/g, ".");
+    try {
+      out.push(new RegExp("^" + esc + "$", "i"));
+    } catch {
+      // ignore bad patterns
+    }
+  }
+  return out;
+}
+
+function findMissingRoutes(truthpack) {
+  const findings = [];
+
+  const server = truthpack?.routes?.server || [];
+  const refs = truthpack?.routes?.clientRefs || [];
+  const gaps = truthpack?.routes?.gaps || [];
+
+  const hasGaps = gaps.length > 0;
+
+  // Allowlist/suppressions (lets users kill known false positives cleanly)
+  const allowMethods = new Set((truthpack?.routes?.allowlistMethods || []).map((m) => String(m).toUpperCase()));
+  const allowPatterns = compileAllowPatterns(truthpack?.routes?.allowlist || truthpack?.routes?.allowlistPatterns || []);
+  const ignorePatterns = compileAllowPatterns(truthpack?.routes?.ignore || truthpack?.routes?.ignorePatterns || []);
+
+  const isSuppressed = (method, pNorm) => {
+    const m = String(method || "*").toUpperCase();
+    if (allowMethods.size && !allowMethods.has(m) && !allowMethods.has("*")) {
+      // method not allowed by allowMethods -> don't suppress
+    }
+    for (const rx of ignorePatterns) if (rxTest(rx, `${m} ${pNorm}`) || rxTest(rx, pNorm)) return true;
+    for (const rx of allowPatterns) if (rxTest(rx, `${m} ${pNorm}`) || rxTest(rx, pNorm)) return true;
+    return false;
+  };
+
+  const serverCount = server.length;
+  const refCount = refs.length;
+
+  // Monorepo heuristic (keep, but make it less dumb)
+  const isLikelyMonorepo = refCount > Math.max(30, serverCount * 2.5);
+
+  const serverPaths = server.map((r) => normalizePath(r.path));
+  const refPaths = refs.map((r) => normalizePath(r.path));
+
+  // Dominant prefixes (commonly "/api")
+  const dominantServerPrefix = inferDominantPrefix(serverPaths, 0.7);
+  const dominantRefPrefix = inferDominantPrefix(refPaths, 0.7);
+
+  const serverPrefix = dominantServerPrefix || null;
+  const refPrefix = dominantRefPrefix || null;
+
+  const index = buildServerRouteIndex(server);
+
+  // Route-map quality gating:
+  // If we have unresolved gaps or tiny server map, DO NOT BLOCK unless obviously invented.
+  const routeMapQuality =
+    serverCount >= 10 && !hasGaps ? "strong" :
+    serverCount >= 5 ? "medium" :
+    "weak";
+
+  // More generous caps (but still bounded)
+  const MAX_WARNINGS = isLikelyMonorepo ? 35 : 60;
+  const MAX_BLOCKS = 15;
+
+  let warnCount = 0;
+  let blockCount = 0;
+
+  // Summaries to help you fix extraction instead of drowning in noise
+  const unmatchedByPrefix = new Map();
+  const externalRefs = [];
+
+  function addUnmatchedPrefix(pNorm) {
+    const seg = firstSegment(pNorm) || "/";
+    unmatchedByPrefix.set(seg, (unmatchedByPrefix.get(seg) || 0) + 1);
+  }
+
+  function tryMatch(method, pNorm) {
+    const shortlist = shortlistServerRoutes(index, method, pNorm);
+
+    // Try exact + canonicalized matching
+    const pCanon = canonicalizeDynamicSegments(pNorm);
+
+    for (const r of shortlist) {
+      if (routeMatches(r, method, pNorm) || routeMatches(r, "*", pNorm)) return { ok: true, matched: r };
+      // Try canonicalized path vs canonicalized server path
+      if (routeMatches({ ...r, path: r._canon }, method, pCanon) || routeMatches({ ...r, path: r._canon }, "*", pCanon)) {
+        return { ok: true, matched: r, usedCanon: true };
+      }
+    }
+    return { ok: false };
+  }
+
+  function closestSuggestions(method, pNorm) {
+    // Use a bounded scan: shortlist first, then broaden if needed
+    const shortlist = shortlistServerRoutes(index, method, pNorm);
+    const pool = shortlist.length ? shortlist : index.all;
+
+    const scored = pool
+      .map((r) => ({ r, score: routeSimilarityScore(pNorm, r._pathNorm) }))
+      .sort((a, b) => b.score - a.score)
+      .slice(0, 3);
+
+    // Raise threshold to 0.50 to only show genuinely similar routes
+    // This reduces "did you mean" noise for unrelated routes
+    return scored.filter((x) => x.score >= 0.50).map((x) => ({
+      method: x.r._method,
+      path: x.r._pathNorm,
+      score: Number(x.score.toFixed(2)),
+    }));
+  }
+
+  function detectMethodMismatch(pNorm, method) {
+    // If the path exists but only under other method(s), that's not "missing route"
+    const methods = ["GET", "POST", "PUT", "PATCH", "DELETE", "*"];
+    const hits = [];
+    for (const m of methods) {
+      if (String(m) === String(method).toUpperCase()) continue;
+      const res = tryMatch(m, pNorm);
+      if (res.ok) hits.push(m);
+    }
+    return hits.length ? hits : null;
+  }
+
+  for (const ref of refs) {
+    const rawPath = ref?.path;
+    const method = String(ref?.method || "*").toUpperCase();
+
+    // Normalize & classify
+    const u = safeUrlParse(rawPath);
+    const pNorm = normalizePath(rawPath);
+
+    // Skip asset-ish refs
+    if (pathLooksLikeAsset(pNorm)) continue;
+
+    // External refs: if full URL and host isn't localhost, treat as external service.
+    if (u && u.host && !/^(localhost|127\.0\.0\.1)(:\d+)?$/i.test(u.host)) {
+      externalRefs.push({ host: u.host, method, path: pNorm, evidence: ref.evidence || [] });
+      continue;
+    }
+
+    // Skip suppressed
+    if (isSuppressed(method, pNorm)) continue;
+
+    // Build candidate variants (this kills a lot of false positives)
+    const candidates = new Set();
+    candidates.add(pNorm);
+
+    // trailing slash variant
+    if (pNorm.length > 1) {
+      candidates.add(pNorm + "/");
+      candidates.add(pNorm.replace(/\/+$/g, ""));
+    }
+
+    // Toggle dominant server prefix (ex: /api) if mismatch likely
+    if (serverPrefix && serverPrefix !== "/" && !pNorm.startsWith(serverPrefix + "/") && pNorm !== serverPrefix) {
+      candidates.add(normalizePath(serverPrefix + pNorm));
+    }
+    if (serverPrefix && serverPrefix !== "/" && pNorm.startsWith(serverPrefix + "/")) {
+      candidates.add(normalizePath(pNorm.slice(serverPrefix.length)));
+    }
+
+    // Toggle dominant ref prefix similarly (sometimes refs have /api but server routes stored without it)
+    if (refPrefix && refPrefix !== "/" && !pNorm.startsWith(refPrefix + "/") && pNorm !== refPrefix) {
+      candidates.add(normalizePath(refPrefix + pNorm));
+    }
+    if (refPrefix && refPrefix !== "/" && pNorm.startsWith(refPrefix + "/")) {
+      candidates.add(normalizePath(pNorm.slice(refPrefix.length)));
+    }
+
+    // Canonicalized variant
+    candidates.add(canonicalizeDynamicSegments(pNorm));
+
+    // Try match all candidates
+    let matched = null;
+    let usedCanon = false;
+    for (const cand of candidates) {
+      const res = tryMatch(method, cand);
+      if (res.ok) {
+        matched = res.matched;
+        usedCanon = !!res.usedCanon;
+        break;
+      }
+    }
+    if (matched) continue;
+
+    addUnmatchedPrefix(pNorm);
+
+    // Method mismatch detection (not missing route)
+    const methodMismatch = detectMethodMismatch(pNorm, method);
+    if (methodMismatch) {
+      // Keep as WARN (not missing route) — reduces noise dramatically
+      if (warnCount >= MAX_WARNINGS) continue;
+      warnCount++;
+
+      findings.push({
+        id: stableId("F_ROUTE_METHOD_MISMATCH", `${method} ${pNorm}`),
+        severity: "WARN",
+        category: "MissingRoute",
+        title: `Method mismatch for route: ${method} ${pNorm}`,
+        why: `A server route exists for this path, but not for method ${method}. This is often a client bug or an incorrect assumption.`,
+        confidence: routeMapQuality === "strong" ? "high" : "med",
+        evidence: ref.evidence || [],
+        fixHints: [
+          `Check the client call method. Server supports: ${methodMismatch.join(", ")} for ${pNorm}`,
+          "If this is intentional, update the server to accept this method or adjust the client.",
+        ],
+      });
+      continue;
+    }
+
+    const invented = looksInventedRoute(pNorm);
+    const internal = isInternalUtilityRoute(pNorm);
+    
+    // Skip internal utility routes entirely - they're almost never real issues
+    if (internal) continue;
+
+    // Similarity suggestions
+    const suggestions = closestSuggestions(method, pNorm);
+
+    // Confidence + severity gating - CONSERVATIVE by default to reduce noise
+    let confidence = "low";
+    let severity = "WARN";
+
+    if (invented) {
+      // Only BLOCK truly invented routes - and require high confidence
+      severity = "BLOCK";
+      confidence = "high";
+    } else if (routeMapQuality === "strong" && !isLikelyMonorepo) {
+      // Even with strong route map, be conservative
+      const best = suggestions[0]?.score ?? 0;
+      if (best < 0.30) {
+        // No close matches - more likely to be a real issue, but still WARN
+        confidence = "med";
+        severity = "WARN";
+      } else if (best >= 0.70) {
+        // Very close match exists - probably a typo, keep as low-priority WARN
+        confidence = "low";
+        severity = "WARN";
+      } else {
+        // Moderate similarity - unclear
+        confidence = "low";
+        severity = "WARN";
+      }
+    } else {
+      // Weak route map or monorepo - don't trust findings, always WARN with low confidence
+      confidence = "low";
+      severity = "WARN";
+    }
+
+    // caps
+    if (severity === "BLOCK") {
+      if (blockCount >= MAX_BLOCKS) continue;
+      blockCount++;
+    } else {
+      if (warnCount >= MAX_WARNINGS) continue;
+      warnCount++;
+    }
+
+    const didYouMean = suggestions.length
+      ? `Closest server routes: ${suggestions.map((s) => `${s.method} ${s.path} (${s.score})`).join(" • ")}`
+      : "No close server route candidates were found (based on static segment similarity).";
+
+    findings.push({
+      id: stableId("F_MISSING_ROUTE", `${method} ${pNorm}`),
+      severity,
+      category: "MissingRoute",
+      title: `Client references route not found in detected server map: ${method} ${pNorm}`,
+      why:
+        severity === "BLOCK"
+          ? "This looks invented. Shipping this will break flows (404 / silent failure)."
+          : routeMapQuality === "weak" || hasGaps
+            ? "Route reference didn't match the detected server map. Route detection may be incomplete (dynamic registration, plugins, prefixes)."
+            : "Route reference didn't match the detected server map. This can be a real missing endpoint or an undetected server route.",
+      confidence,
+      evidence: ref.evidence || [],
+      fixHints: [
+        didYouMean,
+        usedCanon ? "Note: matching tried canonicalized ID segments (/:id normalization)." : "Matching tried normalization (origin/query/trailing slash/prefix toggles).",
+        hasGaps ? `Route map had ${gaps.length} unresolved sources; fix route extraction to reduce false positives.` : "If this is a real endpoint, add it server-side or correct the client call.",
+        isLikelyMonorepo ? "Monorepo/microservices likely: consider allowlisting external services or feeding service domains into truthpack." : "If this is an external service call, store it as external/allowlisted so it won't be flagged.",
+      ],
+    });
+  }
+
+  // Route map diagnostics (actionable, reduces "blame the analyzer" loops)
+  if (hasGaps) {
+    findings.push({
+      id: stableId("F_ROUTE_MAP_GAPS", String(gaps.length)),
+      severity: "WARN",
+      category: "RouteMapGaps",
+      title: `Route map incomplete (${gaps.length} unresolved route sources)`,
+      why: "Dynamic registration, unresolved plugin imports, or non-standard routing prevented complete detection. Missing route findings may be false positives.",
+      confidence: "med",
+      evidence: [],
+      fixHints: [
+        "Fix route extraction: resolve Fastify plugins and prefix registration (fastify.register(...,{ prefix })) and inline fastify.get/post routes.",
+        "If using Next App Router: ensure route handlers (app/**/route.ts) are included in server route extraction.",
+        "Add allowlistPatterns for external services to silence expected gaps.",
+      ],
+    });
+  }
+
+  // External refs summary (useful in microservices)
+  if (externalRefs.length) {
+    const topHosts = new Map();
+    for (const r of externalRefs) topHosts.set(r.host, (topHosts.get(r.host) || 0) + 1);
+    const hostSummary = [...topHosts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5)
+      .map(([h, n]) => `${h} (${n})`).join(", ");
+
+    findings.push({
+      id: stableId("F_EXTERNAL_ROUTE_REFS", hostSummary),
+      severity: "INFO",
+      category: "MissingRoute",
+      title: `External service routes detected in client refs (${externalRefs.length})`,
+      why: "These are full-URL calls to non-local hosts; they are not expected to match server route maps.",
+      confidence: "high",
+      evidence: [],
+      fixHints: [
+        `Top hosts: ${hostSummary}`,
+        "If you want to validate external APIs, add a separate analyzer that checks OpenAPI/spec contracts for those services.",
+        "Optionally add allowlistPatterns like '/^https?:\\/\\/(api\\.stripe\\.com|...)/' at truthpack.routes.allowlistPatterns.",
+      ],
+    });
+  }
+
+  // Biggest unmatched prefixes (points directly at extraction gaps)
+  if (unmatchedByPrefix.size) {
+    const top = [...unmatchedByPrefix.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5);
+    const summary = top.map(([k, v]) => `${k}:${v}`).join(" • ");
+    findings.push({
+      id: stableId("F_ROUTE_UNMATCHED_PREFIXES", summary),
+      severity: "INFO",
+      category: "MissingRoute",
+      title: "Unmatched client route prefixes (helps fix extraction/allowlists)",
+      why: "When one prefix dominates unmatched refs, it usually means server extraction missed a router/plugin prefix or the client is calling a different service.",
+      confidence: "med",
+      evidence: [],
+      fixHints: [
+        `Top unmatched prefixes: ${summary}`,
+        serverPrefix ? `Dominant server prefix inferred: ${serverPrefix}` : "No dominant server prefix detected.",
+        "If these should be local, improve route extraction for that prefix (Fastify register(prefix), Next middleware rewrites, basePath, etc.).",
+      ],
+    });
+  }
+
+  return findings;
+}
+
+/* ============================================================================
+ * ENV GAPS ANALYZER (tightened + fewer false positives)
+ * ========================================================================== */
+
+function findEnvGaps(truthpack) {
+  const findings = [];
+  const used = truthpack?.env?.vars || [];
+  const declared = new Set(truthpack?.env?.declared || []);
+  const declaredSources = truthpack?.env?.declaredSources || [];
+
+  // Well-known system/CI env vars that shouldn't be flagged
+  const systemEnvVars = new Set([
+    "HOME","USER","PATH","PWD","SHELL","TERM","LANG","TZ","TMPDIR","TEMP","TMP","COLORTERM","FORCE_COLOR","NO_COLOR",
+    "APPDATA","LOCALAPPDATA","USERPROFILE","COMPUTERNAME","USERNAME","HOMEDRIVE","HOMEPATH","SYSTEMROOT","WINDIR",
+    "PROGRAMFILES","PROGRAMDATA","COMMONPROGRAMFILES",
+    "NODE_ENV","NODE_OPTIONS","NODE_PATH","NODE_DEBUG","NODE_NO_WARNINGS",
+    "CI","CONTINUOUS_INTEGRATION","BUILD_NUMBER","BUILD_ID",
+    "GITHUB_ACTIONS","GITHUB_WORKFLOW","GITHUB_RUN_ID","GITHUB_RUN_NUMBER","GITHUB_SHA","GITHUB_REF","GITHUB_ACTOR",
+    "GITLAB_CI","CI_COMMIT_SHA","CI_PIPELINE_ID","CI_JOB_ID",
+    "CIRCLECI","CIRCLE_BUILD_NUM","CIRCLE_SHA1","CIRCLE_BRANCH",
+    "TRAVIS","TRAVIS_BUILD_NUMBER","TRAVIS_COMMIT",
+    "JENKINS_URL","BUILD_TAG","GIT_COMMIT",
+    "BUILDKITE","BUILDKITE_BUILD_NUMBER","BUILDKITE_COMMIT",
+    "CODEBUILD_BUILD_ID","CODEBUILD_RESOLVED_SOURCE_VERSION",
+    "VERCEL","VERCEL_ENV","VERCEL_URL","VERCEL_GIT_COMMIT_SHA",
+    "NETLIFY","CONTEXT","DEPLOY_PRIME_URL",
+    "RAILWAY_ENVIRONMENT","RAILWAY_GIT_COMMIT_SHA",
+    "HEROKU","DYNO","RENDER","FLY_APP_NAME",
+    "HTTP_PROXY","HTTPS_PROXY","NO_PROXY","http_proxy","https_proxy","no_proxy",
+    "HOSTNAME","HOST",
+    "DEBUG","VERBOSE","LOG_LEVEL",
+    "EDITOR","VISUAL","VSCODE_PID","TERM_SESSION_ID",
+    "PORT","npm_package_version","npm_package_name",
+  ]);
+
+  // Patterns for env vars that are commonly optional/internal
+  const optionalPatterns = [
+    /^(OPENAI|ANTHROPIC|COHERE|AZURE|AWS|GCP|GOOGLE)_/i,
+    /^(STRIPE|PAYPAL|PLAID)_/i,
+    /^(SENDGRID|RESEND|MAILGUN|SES)_/i,
+    /^(SENTRY|DATADOG|NEWRELIC|LOGROCKET)_/i,
+    /^(REDIS|POSTGRES|MYSQL|MONGO|DATABASE)_/i,
+    /^(NEXT_|NUXT_|VITE_|REACT_APP_)/i,
+    /^(VIBECHECK|GUARDRAIL)_/i,
+    /_(URL|KEY|SECRET|TOKEN|ID|PASSWORD|HOST|PORT)$/i,
+    /^(ENABLE_|DISABLE_|USE_|SKIP_|ALLOW_|NO_)/i,
+    /^(MAX_|MIN_|DEFAULT_|TIMEOUT_|LIMIT_|RATE_)/i,
+    /^(LOG_|DEBUG_|VERBOSE_|TRACE_)/i,
+    /^(TEST_|DEV_|STAGING_|PROD_)/i,
+    /^(ARTIFACTS_|CACHE_|TMP_|OUTPUT_)/i,
+    /^npm_/i,
+  ];
+
+  function isOptionalEnvVar(name) {
+    return optionalPatterns.some((p) => rxTest(p, name));
+  }
+
+  // Heuristic: treat vars referenced only in tooling/scripts as WARN (not BLOCK)
+  function evidenceIsToolingOnly(v) {
+    const refs = v.references || [];
+    if (!refs.length) return false;
+    return refs.every((r) => {
+      const f = String(r.file || "");
+      return /(^|\/)(scripts|tools|bin|cli|devops|infra|config)\//i.test(f);
+    });
+  }
+
+  for (const v of used) {
+    if (!v?.name) continue;
+    if (declared.has(v.name)) continue;
+    if (systemEnvVars.has(v.name)) continue;
+    if (isOptionalEnvVar(v.name)) continue;
+
+    const toolingOnly = evidenceIsToolingOnly(v);
+
+    // Only BLOCK if it's truly required, no fallback, and not tooling-only
+    const isReallyRequired = !!v.required && !v.hasFallback && !toolingOnly;
+    const sev = isReallyRequired ? "BLOCK" : "WARN";
+
+    findings.push({
+      id: `F_ENV_UNDECLARED_${v.name}`,
+      severity: sev,
+      category: "EnvContract",
+      title: `Env var used but not declared in env templates: ${v.name}`,
+      why: isReallyRequired
+        ? "Required env var is used with no fallback and not documented. This ships broken installs."
+        : toolingOnly
+          ? "Env var appears used in tooling/scripts. Document it if users need it; otherwise ignore."
+          : "Env var appears optional/guarded but should still be documented to prevent guesswork.",
+      confidence: isReallyRequired ? "high" : "low",
+      evidence: v.references || [],
+      fixHints: [
+        `Add to .env.example: ${v.name}=your_value_here`,
+        isReallyRequired
+          ? `Add fallback: const value = process.env.${v.name} ?? 'default';`
+          : `Guard usage: if (process.env.${v.name}) { /* use it */ }`,
+        "Docs: https://12factor.net/config",
+      ],
+    });
+  }
+
+  // Declared but never used
+  const usedSet = new Set(used.map((v) => v.name));
+  for (const name of declared) {
+    if (usedSet.has(name)) continue;
+    findings.push({
+      id: `F_ENV_UNUSED_${name}`,
+      severity: "WARN",
+      category: "EnvContract",
+      title: `Env var declared but never used: ${name}`,
+      why: "Dead config creates confusion and invites hallucinated wiring.",
+      confidence: "med",
+      evidence: [],
+      fixHints: [
+        "Remove it from templates if obsolete, or wire it intentionally.",
+        "If used only in infra/runtime, document that explicitly (where/why).",
+      ],
+    });
+  }
+
+  if (!declaredSources.length && used.length) {
+    findings.push({
+      id: "F_ENV_NO_TEMPLATE",
+      severity: "WARN",
+      category: "EnvContract",
+      title: "No .env.example/.env.template found",
+      why: "Without an env contract, humans and AI guess env vars and ship broken setups.",
+      confidence: "high",
+      evidence: [],
+      fixHints: ["Add a .env.example listing required/optional vars with comments."],
+    });
+  }
+
+  return findings;
+}
+
+/* ============================================================================
+ * FAKE SUCCESS ANALYZER (kept, but made safer & less noisy)
+ * ========================================================================== */
+
+function isToastSuccessCall(node) {
+  return !!(
+    t.isCallExpression(node) &&
+    t.isMemberExpression(node.callee) &&
+    t.isIdentifier(node.callee.object, { name: "toast" }) &&
+    t.isIdentifier(node.callee.property, { name: "success" })
+  );
+}
+
+function isRouterPushCall(node) {
+  return (
+    t.isCallExpression(node) &&
+    ((t.isMemberExpression(node.callee) && t.isIdentifier(node.callee.property, { name: "push" })) ||
+      (t.isIdentifier(node.callee) && node.callee.name === "navigate"))
+  );
+}
+
+function isFetchCall(node) {
+  return !!(t.isCallExpression(node) && t.isIdentifier(node.callee, { name: "fetch" }));
+}
+
+function isAxiosCall(node) {
+  return !!(
+    t.isCallExpression(node) &&
+    t.isMemberExpression(node.callee) &&
+    t.isIdentifier(node.callee.object, { name: "axios" }) &&
+    t.isIdentifier(node.callee.property) &&
+    ["get", "post", "put", "patch", "delete"].includes(node.callee.property.name)
+  );
+}
+
+function findFakeSuccess(repoRoot) {
+  const findings = [];
+  const files = fg.sync(["**/*.{ts,tsx,js,jsx}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: STANDARD_IGNORE_PATTERNS,
+  });
+
+  for (const fileAbs of files) {
+    const code = readFileCached(fileAbs);
+    
+    // V3: FAST PATH OPTIMIZATION
+    // AST parsing is 100x slower than regex. Skip files that don't contain
+    // relevant keywords (toast/push/navigate AND fetch/axios).
+    const hasSuccessUI = /\b(toast|\.push|navigate)\b/.test(code);
+    const hasNetworkCall = /\b(fetch|axios)\b/.test(code);
+    if (!hasSuccessUI || !hasNetworkCall) {
+      continue;
+    }
+
+    let ast;
+    try {
+      ast = parseFile(code, fileAbs);
+    } catch {
+      continue;
+    }
+
+    try {
+    traverse(ast, {
+      Function(pathFn) {
+        // Collect call sites with positions to reduce false positives.
+        const successCalls = [];
+        const networkCalls = [];
+        const okChecks = [];
+
+        pathFn.traverse({
+          CallExpression(p) {
+            const n = p.node;
+
+            if (isToastSuccessCall(n) || isRouterPushCall(n)) {
+              successCalls.push({ loc: n.loc, pos: n.start ?? 0 });
+            }
+
+            if (isFetchCall(n) || isAxiosCall(n)) {
+              const isAwaited = p.parentPath && p.parentPath.isAwaitExpression();
+              networkCalls.push({ pos: n.start ?? 0, awaited: !!isAwaited });
+            }
+          },
+          IfStatement(p) {
+            const test = p.node.test;
+            const txt = code.slice(test.start || 0, test.end || 0);
+            // Check for response status validation (res.ok, status)
+            if (/\b(res|response)\b/i.test(txt) && /\b(ok|status)\b/i.test(txt)) okChecks.push({ pos: p.node.start ?? 0 });
+            // Check for response body validation (data, error, success property checks)
+            if (/\b(data|result|response)\b/i.test(txt) && /\b(error|success|\.data|\.result)\b/i.test(txt)) okChecks.push({ pos: p.node.start ?? 0 });
+          },
+          // Also check for try-catch around the network call as a form of validation
+          TryStatement(tryPath) {
+            if (tryPath.node.handler) {
+              okChecks.push({ pos: tryPath.node.start ?? 0 });
+            }
+          },
+        });
+
+        if (!successCalls.length || !networkCalls.length) return;
+
+        // For each success call: if there exists an awaited network call before it, it's less severe.
+        for (const sc of successCalls) {
+          const netBefore = networkCalls.filter((n) => n.pos < sc.pos);
+          const awaitedBefore = netBefore.some((n) => n.awaited);
+          const okCheckBefore = okChecks.some((c) => c.pos < sc.pos);
+
+          // If no awaited call before success -> strong signal
+          const severity = awaitedBefore ? (okCheckBefore ? null : "WARN") : "BLOCK";
+          if (!severity) continue;
+
+          const ev = evidenceFromLoc(fileAbs, repoRoot, sc.loc, "Success UI call in networked flow");
+          findings.push({
+            id: stableId("F_FAKE_SUCCESS", `${path.relative(repoRoot, fileAbs)}:${sc.pos}:${severity}`),
+            severity,
+            category: "FakeSuccess",
+            title:
+              severity === "BLOCK"
+                ? "Success UI triggered without awaiting network call"
+                : "Success UI triggered without verifying network result (res.ok/status)",
+            why:
+              severity === "BLOCK"
+                ? "This ships lies. Users see success even when the request never completed."
+                : "You're not gating success on a real response; this often ships false success.",
+            confidence: "med",
+            evidence: ev ? [ev] : [],
+            fixHints: [
+              "const res = await fetch(...); if (!res.ok) throw new Error('Request failed');",
+              "const data = await res.json(); if (data.success) toast.success('Done!'); else toast.error(data.error);",
+              "Use try-catch: try { await api(); toast.success(); } catch (e) { toast.error(e.message); }",
+            ],
+          });
+        }
+      },
+    });
+    } catch {
+      // Babel traverse can fail on some edge-case files; skip them
+      continue;
+    }
+  }
+
+  return findings;
+}
+
+/* ============================================================================
+ * GHOST AUTH ANALYZER (kept)
+ * ========================================================================== */
+
+function looksSensitive(pathStr) {
+  const p = String(pathStr || "");
+  return (
+    p.startsWith("/api/admin") ||
+    p.startsWith("/api/billing") ||
+    p.startsWith("/api/stripe") ||
+    p.startsWith("/api/org") ||
+    p.startsWith("/api/team") ||
+    p.startsWith("/api/account") ||
+    p.startsWith("/api/settings") ||
+    p.startsWith("/api/users") ||
+    p.startsWith("/api/user")
+  );
+}
+
+function hasRouteLevelProtection(routeDef) {
+  const hooks = routeDef.hooks || [];
+  return !!(hooks.includes("preHandler") || hooks.includes("onRequest") || hooks.includes("preValidation"));
+}
+
+function handlerHasAuthSignal(repoRoot, handlerRel) {
+  const abs = path.join(repoRoot, handlerRel);
+  if (!fs.existsSync(abs)) return false;
+  const code = readFileCached(abs);
+
+  return (
+    /\bgetServerSession\b|\bauth\(\)\b|\bclerk\b|@clerk\/nextjs|\bcreateRouteHandlerClient\b|@supabase/i.test(code) ||
+    /\b(jwtVerify|authorization|bearer|verifyToken|verifyJWT)\b/i.test(code) ||
+    /\b(isAdmin|adminOnly|permissions|rbac)\b/i.test(code)
+  );
+}
+
+function isProtectedByNextMiddleware(truthpack, routePath) {
+  const patterns = truthpack?.auth?.nextMatcherPatterns || [];
+  return !!matcherCoversPath(patterns, routePath);
+}
+
+function findGhostAuth(truthpack, repoRoot) {
+  const findings = [];
+  const server = truthpack?.routes?.server || [];
+
+  // Track mutation routes without CSRF protection
+  const mutationMethods = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+
+  for (const r of server) {
+    const isMutation = mutationMethods.has(String(r.method).toUpperCase());
+    
+    if (!looksSensitive(r.path)) continue;
+
+    const middlewareProtected = isProtectedByNextMiddleware(truthpack, r.path);
+    const routeHooksProtected = hasRouteLevelProtection(r);
+    const handlerProtected = r.handler ? handlerHasAuthSignal(repoRoot, r.handler) : false;
+
+    const protectedSomehow = middlewareProtected || routeHooksProtected || handlerProtected;
+
+    if (!protectedSomehow) {
+      findings.push({
+        id: stableId("F_GHOST_AUTH", `${r.method} ${r.path}`),
+        severity: "BLOCK",
+        category: "GhostAuth",
+        title: `Sensitive endpoint appears unprotected: ${r.method} ${r.path}`,
+        why: "If the server doesn't enforce auth, it's public. UI gating is irrelevant.",
+        confidence: "med",
+        evidence: (r.evidence || []).slice(0, 2),
+        fixHints: [
+          `Next.js: const session = await getServerSession(); if (!session) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });`,
+          `Fastify: fastify.addHook('preHandler', async (req, reply) => { if (!req.user) reply.code(401).send({ error: 'Unauthorized' }); });`,
+          "Or add to middleware.ts matcher: export const config = { matcher: ['/api/admin/:path*'] };",
+          "Docs: https://nextjs.org/docs/app/building-your-application/authentication",
+        ],
+      });
+    }
+    
+    // Check for CSRF protection on mutations
+    if (isMutation && r.handler) {
+      const abs = path.join(repoRoot, r.handler);
+      if (fs.existsSync(abs)) {
+        const code = readFileCached(abs);
+        const hasCSRFCheck = /\b(csrf|csrfToken|_csrf|x-csrf-token|xsrf|anti-forgery)\b/i.test(code);
+        const isAPIRoute = r.path.startsWith("/api/");
+        
+        // Only warn for non-API routes (API routes typically use bearer tokens)
+        if (!hasCSRFCheck && !isAPIRoute) {
+          findings.push({
+            id: stableId("F_GHOST_AUTH_NO_CSRF", `${r.method} ${r.path}`),
+            severity: "WARN",
+            category: "GhostAuth",
+            title: `Mutation endpoint without CSRF protection: ${r.method} ${r.path}`,
+            why: "State-changing endpoints should verify CSRF tokens to prevent cross-site request forgery attacks.",
+            confidence: "low",
+            evidence: (r.evidence || []).slice(0, 2),
+            fixHints: [
+              "Add CSRF token validation for form submissions.",
+              "Or use SameSite cookies + Origin header validation.",
+              "API routes using bearer tokens are generally exempt.",
+            ],
+          });
+        }
+      }
+    }
+  }
+
+  const patterns = truthpack?.auth?.nextMatcherPatterns || [];
+  if (patterns.length) {
+    const coversApi = patterns.some((p) => String(p).includes("/api"));
+    if (!coversApi) {
+      findings.push({
+        id: "F_MIDDLEWARE_NOT_COVERING_API",
+        severity: "WARN",
+        category: "GhostAuth",
+        title: "Next middleware exists but does not appear to cover /api routes",
+        why: "People assume middleware protects APIs. Often it doesn't. Verify matcher patterns.",
+        confidence: "high",
+        evidence: (truthpack?.auth?.nextMiddleware?.[0]?.evidence || []).slice(0, 3),
+        fixHints: ["Add /api/:path* to middleware matcher if your design expects API auth protection."],
+      });
+    }
+  }
+
+  return findings;
+}
+
+/* ============================================================================
+ * STRIPE WEBHOOK VIOLATIONS (kept)
+ * ========================================================================== */
+
+function findStripeWebhookViolations(truthpack) {
+  const findings = [];
+  const billing = truthpack?.billing;
+
+  if (!billing?.hasStripe) return findings;
+
+  const candidates = billing.webhookCandidates || [];
+
+  if (!candidates.length) {
+    findings.push({
+      id: "F_STRIPE_NO_WEBHOOK_HANDLER",
+      severity: "WARN",
+      category: "Billing",
+      title: "Stripe appears used but no webhook handler candidate detected",
+      why: "Stripe billing usually needs webhooks; missing them causes subscription state desync.",
+      confidence: "med",
+      evidence: [],
+      fixHints: ["Add a Stripe webhook handler with signature verification and idempotency."],
+    });
+    return findings;
+  }
+
+  for (const w of candidates) {
+    const verified = w.signals.webhookConstructEvent && w.signals.rawBodySignal && w.signals.readsStripeSignatureHeader;
+    const idempotent = !!w.signals.idempotencySignal;
+
+    if (!verified) {
+      findings.push({
+        id: stableId("F_STRIPE_WEBHOOK_NOT_VERIFIED", w.file),
+        severity: "BLOCK",
+        category: "Billing",
+        title: `Stripe webhook handler not clearly signature-verified: ${w.file}`,
+        why: "Unverified webhooks = spoofable billing state.",
+        confidence: "high",
+        evidence: (w.evidence || []).slice(0, 4),
+        fixHints: [
+          "Use stripe.webhooks.constructEvent(rawBody, sigHeader, STRIPE_WEBHOOK_SECRET).",
+          "Ensure raw body is used (disable bodyParser in pages router; in app router read req.text()/arrayBuffer).",
+          "Reject if signature missing/invalid.",
+        ],
+      });
+    }
+
+    if (!idempotent) {
+      findings.push({
+        id: stableId("F_STRIPE_WEBHOOK_NOT_IDEMPOTENT", w.file),
+        severity: "BLOCK",
+        category: "Billing",
+        title: `Stripe webhook handler not clearly idempotent: ${w.file}`,
+        why: "Stripe retries webhooks; without dedupe you can double-grant access or double-write state.",
+        confidence: "med",
+        evidence: (w.evidence || []).slice(0, 4),
+        fixHints: [
+          "Persist event.id as processed (DB/Redis). If seen, return 200 immediately.",
+          "Wrap state mutation in a transaction keyed by event.id.",
+        ],
+      });
+    }
+  }
+
+  return findings;
+}
+
+/* ============================================================================
+ * PAID SURFACE NOT ENFORCED (kept)
+ * ========================================================================== */
+
+function findPaidSurfaceNotEnforced(truthpack) {
+  const findings = [];
+  const enforcement = truthpack?.enforcement;
+  const checks = enforcement?.checks || [];
+
+  for (const c of checks) {
+    if (c.enforced) continue;
+    findings.push({
+      id: stableId("F_PAID_SURFACE_NOT_ENFORCED", `${c.method} ${c.path}`),
+      severity: "BLOCK",
+      category: "Entitlements",
+      title: `Paid surface appears un-enforced server-side: ${c.method} ${c.path}`,
+      why: "If enforcement is only in the CLI/UI, users can call the endpoint directly.",
+      confidence: "med",
+      evidence: [],
+      fixHints: [
+        "Enforce in the server handler BEFORE doing work.",
+        "Return 402/403 with a structured error code.",
+        "Make the CLI treat that code as an upgrade prompt.",
+      ],
+    });
+  }
+  return findings;
+}
+
+/* ============================================================================
+ * OWNER MODE BYPASS (kept; uses deterministic regex testing)
+ * ========================================================================== */
+
+function findOwnerModeBypass(repoRoot) {
+  const findings = [];
+  const files = fg.sync(["**/*.{ts,tsx,js,jsx}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: STANDARD_IGNORE_PATTERNS,
+  });
+
+  const patterns = [
+    /OWNER_MODE/i,
+    /GUARDRAIL_OWNER_MODE/i,
+    /VIBECHECK_OWNER_MODE/i,
+    /process\.env\.[A-Z0-9_]*OWNER[A-Z0-9_]*/i,
+  ];
+
+  for (const fileAbs of files) {
+    const code = readFileCached(fileAbs);
+    const hit = patterns.some((rx) => rxTest(rx, code));
+    if (!hit) continue;
+
+    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+
+    findings.push({
+      id: stableId("F_OWNER_MODE_BYPASS", fileRel),
+      severity: "BLOCK",
+      category: "Security",
+      title: `Owner mode / env bypass signal detected: ${fileRel}`,
+      why: "This is a production backdoor unless cryptographically gated. It cannot ship.",
+      confidence: "high",
+      evidence: [],
+      fixHints: [
+        "Delete owner mode bypass. If you need dev override, require a signed admin token + non-prod environment.",
+        "Add a test that asserts no OWNER_MODE env var grants entitlements.",
+      ],
+    });
+  }
+
+  return findings;
+}
+
+/* ============================================================================
+ * MOCK DATA DETECTOR (fixed /g+.test() bug + better line discovery)
+ * ========================================================================== */
+
+function findMockData(repoRoot) {
+  const engines = require("./engines/vibecheck-engines");
+  const findings = [];
+  const files = fg.sync(["**/*.{ts,tsx,js,jsx}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: STANDARD_IGNORE_PATTERNS,
+  });
+
+  for (const fileAbs of files) {
+    try {
+      const code = readFileCached(fileAbs);
+      const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+
+      // Use unified engines
+      const engineFindings = engines.analyzeMockData(code, fileRel);
+      
+      // Convert engine findings to analyzer format
+      for (const finding of engineFindings) {
+        findings.push({
+          id: stableId("F_MOCK_DATA", `${fileRel}:${finding.type}:${finding.line}`),
+          severity: finding.severity,
+          category: finding.category,
+          title: finding.title,
+          message: finding.message,
+          file: finding.file,
+          line: finding.line,
+          why: "Mock/fake data in production causes embarrassing bugs and makes your app look unfinished.",
+          confidence: finding.confidence,
+          evidence: [{ file: fileRel, reason: finding.title, line: finding.line }],
+          fixHints: [
+            "Replace mock data with real API calls or database queries.",
+            "If intentional sample data, move to a clearly marked demo mode.",
+          ],
+        });
+      }
+    } catch (err) {
+      // Skip files that can't be analyzed
+      continue;
+    }
+  }
+
+  return findings;
+}
+
+/* ============================================================================
+ * TODO/FIXME DETECTOR (fixed /g+.test() bug)
+ * ========================================================================== */
+
+function findTodoFixme(repoRoot) {
+  // TODO/FIXME engine not in unified engines yet - keep using existing
+  const { analyzeTodoFixme } = require("./engines/todo-fixme-engine");
+  const engines = require("./engines/vibecheck-engines");
+  const findings = [];
+  const files = fg.sync(["**/*.{ts,tsx,js,jsx}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: STANDARD_IGNORE_PATTERNS,
+  });
+
+  for (const fileAbs of files) {
+    try {
+      const code = readFileCached(fileAbs);
+      const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+      
+      // Use AST-based engine (not in unified engines yet)
+      const engineFindings = analyzeTodoFixme(code, fileRel);
+      
+      // Convert engine findings to analyzer format
+      for (const finding of engineFindings) {
+        if (finding.type === "summary") {
+          findings.push({
+            id: "F_TODO_SUMMARY",
+            severity: finding.severity,
+            category: finding.category,
+            title: finding.title,
+            why: "Large numbers of TODO comments indicate significant unfinished work.",
+            confidence: finding.confidence,
+            evidence: [],
+            fixHints: [
+              "Review and address high-priority TODOs before shipping.",
+              `Run: vibecheck scan --json | jq '.findings[] | select(.category == "TODO")'`,
+            ],
+          });
+        } else {
+          findings.push({
+            id: stableId("F_TODO", `${fileRel}:${finding.line}:${finding.type}`),
+            severity: finding.severity,
+            category: finding.category,
+            title: finding.title,
+            message: finding.message,
+            file: finding.file,
+            line: finding.line,
+            why: finding.severity === "BLOCK"
+              ? "This comment indicates a known critical issue that must be addressed before shipping."
+              : "Unfinished work markers suggest the code isn't production-ready.",
+            confidence: finding.confidence,
+            evidence: [{ file: fileRel, lines: `${finding.line}`, reason: finding.title }],
+            fixHints: [
+              "Complete the TODO or remove it if already done.",
+              "If deferring, create a tracked issue and reference it in the comment.",
+            ],
+          });
+        }
+      }
+    } catch (err) {
+      // Skip files that can't be analyzed
+      continue;
+    }
+  }
+
+  return findings;
+}
+
+/* ============================================================================
+ * CONSOLE.LOG DETECTOR (kept)
+ * ========================================================================== */
+
+function findConsoleLogs(repoRoot) {
+  const engines = require("./engines/vibecheck-engines");
+  const findings = [];
+  const files = fg.sync(["**/*.{ts,tsx,js,jsx}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: STANDARD_IGNORE_PATTERNS,
+  });
+
+  for (const fileAbs of files) {
+    try {
+      const code = readFileCached(fileAbs);
+      const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+
+      // Use unified engines
+      const engineFindings = engines.analyzeConsoleLogs(code, fileRel);
+      
+      // Convert engine findings to analyzer format
+      for (const finding of engineFindings) {
+        findings.push({
+          id: stableId("F_CONSOLE_LOG", `${fileRel}:${finding.line}:${finding.type}`),
+          severity: finding.severity,
+          category: finding.category,
+          title: finding.title,
+          message: finding.message,
+          file: finding.file,
+          line: finding.line,
+          why: "Console statements leak debugging info and clutter logs/console.",
+          confidence: finding.confidence,
+          evidence: [{ file: fileRel, lines: `${finding.line}`, reason: finding.codeSnippet || finding.title }],
+          fixHints: ["Remove console.log or replace with a proper logger.", "Use a logger that can be silenced in production."],
+        });
+      }
+    } catch (err) {
+      // Skip files that can't be analyzed
+      continue;
+    }
+  }
+
+  return findings;
+}
+
+/* ============================================================================
+ * HARDCODED SECRETS DETECTOR (kept)
+ * ========================================================================== */
+
+function findHardcodedSecrets(repoRoot) {
+  const engines = require("./engines/vibecheck-engines");
+  const findings = [];
+  const files = fg.sync(["**/*.{ts,tsx,js,jsx,json}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: [...STANDARD_IGNORE_PATTERNS, "**/package*.json"],
+  });
+
+  for (const fileAbs of files) {
+    try {
+      const code = readFileCached(fileAbs);
+      const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+      
+      // Use unified engines
+      const engineFindings = engines.analyzeHardcodedSecrets(code, fileRel);
+      
+      // Convert engine findings to analyzer format
+      for (const finding of engineFindings) {
+        findings.push({
+          id: stableId("F_SECRET", `${fileRel}:${finding.type}:${finding.line}`),
+          severity: finding.severity,
+          category: finding.category,
+          title: finding.title,
+          message: finding.message,
+          file: finding.file,
+          line: finding.line,
+          why: finding.severity === "BLOCK"
+            ? "Hardcoded secrets get committed and leaked. This is critical."
+            : "This string looks mathematically random, which usually indicates a hardcoded secret key.",
+          confidence: finding.confidence,
+          evidence: [{ file: fileRel, reason: finding.title, line: finding.line }],
+          fixHints: finding.severity === "BLOCK"
+            ? [
+                "Move the secret to environment variables.",
+                "Rotate the compromised secret immediately.",
+                "Add the file to .gitignore if it shouldn't be committed.",
+              ]
+            : [
+                "Move the secret to environment variables.",
+                "If this is not a secret, consider using a more descriptive variable name.",
+              ],
+        });
+      }
+    } catch (err) {
+      // Skip files that can't be analyzed
+      continue;
+    }
+  }
+
+  return findings;
+}
+
+/* ============================================================================
+ * DEAD CODE / UNUSED EXPORTS DETECTOR (AST-based engine)
+ * ========================================================================== */
+
+function findDeadCode(repoRoot) {
+  const engines = require("./engines/vibecheck-engines");
+  const findings = [];
+  const files = fg.sync(["**/*.{ts,tsx,js,jsx}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: STANDARD_IGNORE_PATTERNS,
+  });
+
+  for (const fileAbs of files) {
+    try {
+      const code = readFileCached(fileAbs);
+      const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+      
+      // Use unified engines
+      const engineFindings = engines.analyzeDeadCode(code, fileRel);
+      
+      // Convert engine findings to analyzer format
+      for (const finding of engineFindings) {
+        findings.push({
+          id: stableId("F_DEAD_CODE", `${fileRel}:${finding.type}:${finding.line}`),
+          severity: finding.severity,
+          category: finding.category,
+          title: finding.title,
+          message: finding.message,
+          file: finding.file,
+          line: finding.line,
+          why: "Dead code adds confusion and maintenance burden and usually indicates incomplete refactoring.",
+          confidence: finding.confidence,
+          evidence: [{ file: fileRel, reason: finding.title, line: finding.line }],
+          fixHints: ["Remove the dead code entirely.", "If needed for reference, use git history instead of commenting."],
+        });
+      }
+    } catch (err) {
+      // Skip files that can't be analyzed
+      continue;
+    }
+  }
+
+  return findings;
+}
+
+/* ============================================================================
+ * DEPRECATED API USAGE DETECTOR (kept; deterministic)
+ * ========================================================================== */
+
+function findDeprecatedApis(repoRoot) {
+  const engines = require("./engines/vibecheck-engines");
+  const findings = [];
+  const files = fg.sync(["**/*.{ts,tsx,js,jsx}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: STANDARD_IGNORE_PATTERNS,
+  });
+
+  for (const fileAbs of files) {
+    try {
+      const code = readFileCached(fileAbs);
+      const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+      
+      // Use unified engines
+      const engineFindings = engines.analyzeDeprecatedApi(code, fileRel);
+      
+      // Convert engine findings to analyzer format
+      for (const finding of engineFindings) {
+        findings.push({
+          id: stableId("F_DEPRECATED", `${fileRel}:${finding.type}:${finding.line}`),
+          severity: finding.severity,
+          category: finding.category,
+          title: finding.title,
+          message: finding.message,
+          file: finding.file,
+          line: finding.line,
+          why: "Deprecated APIs may break in future versions and sometimes carry security issues.",
+          confidence: finding.confidence,
+          evidence: [{ file: fileRel, reason: finding.title, line: finding.line }],
+          fixHints: finding.replacement ? [`Use ${finding.replacement} instead.`, "Check migration guides for the specific deprecation."] : ["Update to the modern API equivalent.", "Check migration guides for the specific deprecation."],
+        });
+      }
+    } catch (err) {
+      // Skip files that can't be analyzed
+      continue;
+    }
+  }
+
+  return findings;
+}
+
+/* ============================================================================
+ * EMPTY CATCH BLOCKS DETECTOR (AST-based engine)
+ * ========================================================================== */
+
+function findEmptyCatch(repoRoot) {
+  const engines = require("./engines/vibecheck-engines");
+  const findings = [];
+  const files = fg.sync(["**/*.{ts,tsx,js,jsx}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: STANDARD_IGNORE_PATTERNS,
+  });
+
+  for (const fileAbs of files) {
+    try {
+      const code = readFileCached(fileAbs);
+      const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+      
+      // Use unified engines
+      const engineFindings = engines.analyzeEmptyCatch(code, fileRel);
+      
+      // Convert engine findings to analyzer format
+      for (const finding of engineFindings) {
+        findings.push({
+          id: stableId("F_EMPTY_CATCH", `${fileRel}:${finding.type}:${finding.line}`),
+          severity: finding.severity,
+          category: finding.category,
+          title: finding.title,
+          message: finding.message,
+          file: finding.file,
+          line: finding.line,
+          why: "Empty catch blocks swallow errors and make debugging impossible.",
+          confidence: finding.confidence,
+          evidence: [{ file: fileRel, reason: finding.title, line: finding.line }],
+          fixHints: ["Log the error or handle it appropriately.", "If intentionally ignoring, add a comment explaining why."],
+        });
+      }
+    } catch (err) {
+      // Skip files that can't be analyzed
+      continue;
+    }
+  }
+
+  return findings;
+}
+
+/* ============================================================================
+ * UNSAFE REGEX DETECTOR (fixed /g+.test() bug)
+ * ========================================================================== */
+
+function findUnsafeRegex(repoRoot) {
+  const engines = require("./engines/vibecheck-engines");
+  const findings = [];
+  const files = fg.sync(["**/*.{ts,tsx,js,jsx}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: STANDARD_IGNORE_PATTERNS,
+  });
+
+  for (const fileAbs of files) {
+    try {
+      const code = readFileCached(fileAbs);
+      const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+      
+      // Use unified engines
+      const engineFindings = engines.analyzeUnsafeRegex(code, fileRel);
+      
+      // Convert engine findings to analyzer format
+      for (const finding of engineFindings) {
+        findings.push({
+          id: stableId("F_UNSAFE_REGEX", `${fileRel}:${finding.type}:${finding.line}`),
+          severity: finding.severity,
+          category: finding.category,
+          title: finding.title,
+          message: finding.message,
+          file: finding.file,
+          line: finding.line,
+          why: "Unsafe regex patterns can cause denial of service via catastrophic backtracking.",
+          confidence: finding.confidence,
+          evidence: [{ file: fileRel, reason: finding.title, line: finding.line }],
+          fixHints: ["Validate input length before applying regex.", "Consider safer parsing or a regex linter.", "Avoid nested quantifiers."],
+        });
+      }
+    } catch (err) {
+      // Skip files that can't be analyzed
+      continue;
+    }
+  }
+
+  return findings;
+}
+
+/* ============================================================================
+ * NEW SECURITY & PERFORMANCE ANALYZERS
+ * ========================================================================== */
+
+function findSecurityVulnerabilities(repoRoot) {
+  // Note: Security vulnerabilities engine not in unified engines yet
+  // Keep using the existing engine for now
+  const { analyzeSecurityVulnerabilities } = require("./engines/security-vulnerabilities-engine");
+  const findings = [];
+  const files = fg.sync(["**/*.{ts,tsx,js,jsx}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: STANDARD_IGNORE_PATTERNS,
+  });
+
+  for (const fileAbs of files) {
+    try {
+      const code = readFileCached(fileAbs);
+      const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+      
+      const engineFindings = analyzeSecurityVulnerabilities(code, fileRel);
+      
+      for (const finding of engineFindings) {
+        findings.push({
+          id: stableId("F_SECURITY", `${fileRel}:${finding.type}:${finding.line}`),
+          severity: finding.severity,
+          category: finding.category,
+          title: finding.title,
+          message: finding.message,
+          file: finding.file,
+          line: finding.line,
+          why: "Security vulnerabilities can lead to data breaches, unauthorized access, or system compromise.",
+          confidence: finding.confidence,
+          evidence: [{ file: fileRel, reason: finding.title, line: finding.line }],
+          fixHints: [
+            "Review security best practices for the detected vulnerability type.",
+            "Use parameterized queries for SQL operations.",
+            "Sanitize and validate all user inputs.",
+            "Use Content Security Policy (CSP) headers for XSS protection.",
+          ],
+        });
+      }
+    } catch (err) {
+      continue;
+    }
+  }
+
+  return findings;
+}
+
+function findPerformanceIssues(repoRoot) {
+  const engines = require("./engines/vibecheck-engines");
+  const findings = [];
+  const files = fg.sync(["**/*.{ts,tsx,js,jsx}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: STANDARD_IGNORE_PATTERNS,
+  });
+
+  for (const fileAbs of files) {
+    try {
+      const code = readFileCached(fileAbs);
+      const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+      
+      // Use unified engines
+      const engineFindings = engines.analyzePerformanceIssues(code, fileRel);
+      
+      for (const finding of engineFindings) {
+        findings.push({
+          id: stableId("F_PERF", `${fileRel}:${finding.type}:${finding.line}`),
+          severity: finding.severity,
+          category: finding.category,
+          title: finding.title,
+          message: finding.message,
+          file: finding.file,
+          line: finding.line,
+          why: "Performance issues can degrade user experience and increase server costs.",
+          confidence: finding.confidence,
+          evidence: [{ file: fileRel, reason: finding.title, line: finding.line }],
+          fixHints: [
+            "Optimize algorithms and data structures.",
+            "Use pagination for large datasets.",
+            "Remove unnecessary re-renders.",
+            "Use async/await for I/O operations.",
+          ],
+        });
+      }
+    } catch (err) {
+      continue;
+    }
+  }
+
+  return findings;
+}
+
+function findCodeQualityIssues(repoRoot) {
+  const engines = require("./engines/vibecheck-engines");
+  const findings = [];
+  const files = fg.sync(["**/*.{ts,tsx,js,jsx}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: STANDARD_IGNORE_PATTERNS,
+  });
+
+  for (const fileAbs of files) {
+    try {
+      const code = readFileCached(fileAbs);
+      const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+      
+      // Use unified engines
+      const engineFindings = engines.analyzeCodeQuality(code, fileRel);
+      
+      for (const finding of engineFindings) {
+        findings.push({
+          id: stableId("F_QUALITY", `${fileRel}:${finding.type}:${finding.line}`),
+          severity: finding.severity,
+          category: finding.category,
+          title: finding.title,
+          message: finding.message,
+          file: finding.file,
+          line: finding.line,
+          why: "Code quality issues make code harder to maintain, test, and extend.",
+          confidence: finding.confidence,
+          evidence: [{ file: fileRel, reason: finding.title, line: finding.line }],
+          fixHints: [
+            "Break down complex functions into smaller, focused functions.",
+            "Extract magic numbers into named constants.",
+            "Reduce nesting depth with early returns.",
+            "Consider design patterns for common problems.",
+          ],
+        });
+      }
+    } catch (err) {
+      continue;
+    }
+  }
+
+  return findings;
+}
+
+function findCrossFileIssues(repoRoot) {
+  const { analyzeCrossFile } = require("./engines/cross-file-analysis-engine");
+  const fg = require("fast-glob");
+  
+  const files = fg.sync(["**/*.{ts,tsx,js,jsx}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: STANDARD_IGNORE_PATTERNS,
+  });
+
+  const engineFindings = analyzeCrossFile(files, repoRoot);
+  const findings = [];
+
+  for (const finding of engineFindings) {
+    findings.push({
+      id: stableId("F_CROSSFILE", `${finding.file}:${finding.type}`),
+      severity: finding.severity,
+      category: finding.category,
+      title: finding.title,
+      message: finding.message,
+      file: finding.file,
+      line: finding.line,
+      why: "Cross-file issues indicate architectural problems that can cause maintenance difficulties.",
+      confidence: finding.confidence,
+      evidence: [{ file: finding.file, reason: finding.title }],
+      fixHints: [
+        "Remove unused exports or mark them as internal.",
+        "Refactor to break circular dependencies.",
+        "Standardize import paths across the codebase.",
+      ],
+    });
+  }
+
+  return findings;
+}
+
+function findTypeSafetyIssues(repoRoot) {
+  const engines = require("./engines/vibecheck-engines");
+  const findings = [];
+  const files = fg.sync(["**/*.{ts,tsx,js,jsx}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: STANDARD_IGNORE_PATTERNS,
+  });
+
+  for (const fileAbs of files) {
+    try {
+      const code = readFileCached(fileAbs);
+      const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+      
+      // Use unified engines
+      const engineFindings = engines.analyzeTypeAware(code, fileRel);
+      
+      for (const finding of engineFindings) {
+        findings.push({
+          id: stableId("F_TYPE", `${fileRel}:${finding.type}:${finding.line}`),
+          severity: finding.severity,
+          category: finding.category,
+          title: finding.title,
+          message: finding.message,
+          file: finding.file,
+          line: finding.line,
+          why: "Type safety issues can lead to runtime errors and make code harder to maintain.",
+          confidence: finding.confidence,
+          evidence: [{ file: fileRel, reason: finding.title, line: finding.line }],
+          fixHints: [
+            "Use proper TypeScript types instead of 'any'.",
+            "Fix underlying type errors instead of suppressing them.",
+            "Add explicit return type annotations.",
+          ],
+        });
+      }
+    } catch (err) {
+      continue;
+    }
+  }
+
+  return findings;
+}
+
+function findAccessibilityIssues(repoRoot) {
+  const { analyzeAccessibility } = require("./engines/accessibility-engine");
+  const findings = [];
+  const files = fg.sync(["**/*.{tsx,jsx}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: STANDARD_IGNORE_PATTERNS,
+  });
+
+  for (const fileAbs of files) {
+    try {
+      const code = readFileCached(fileAbs);
+      const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+      
+      const engineFindings = analyzeAccessibility(code, fileRel);
+      
+      for (const finding of engineFindings) {
+        findings.push({
+          id: stableId("F_A11Y", `${fileRel}:${finding.type}:${finding.line}`),
+          severity: finding.severity,
+          category: finding.category,
+          title: finding.title,
+          message: finding.message,
+          file: finding.file,
+          line: finding.line,
+          why: "Accessibility issues prevent users with disabilities from using your application.",
+          confidence: finding.confidence,
+          evidence: [{ file: fileRel, reason: finding.title, line: finding.line }],
+          fixHints: [
+            "Add alt text to all images.",
+            "Ensure all interactive elements have accessible labels.",
+            "Add keyboard handlers for custom interactive elements.",
+            "Test with screen readers.",
+          ],
+        });
+      }
+    } catch (err) {
+      continue;
+    }
+  }
+
+  return findings;
+}
+
+function findAPIConsistencyIssues(repoRoot) {
+  const { analyzeAPIConsistency } = require("./engines/api-consistency-engine");
+  const findings = [];
+  const files = fg.sync(["**/*.{ts,tsx,js,jsx}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: STANDARD_IGNORE_PATTERNS,
+  });
+
+  for (const fileAbs of files) {
+    try {
+      const code = readFileCached(fileAbs);
+      const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+      
+      const engineFindings = analyzeAPIConsistency(code, fileRel);
+      
+      for (const finding of engineFindings) {
+        findings.push({
+          id: stableId("F_API", `${fileRel}:${finding.type}:${finding.line}`),
+          severity: finding.severity,
+          category: finding.category,
+          title: finding.title,
+          message: finding.message,
+          file: finding.file,
+          line: finding.line,
+          why: "API consistency issues make APIs harder to use and maintain.",
+          confidence: finding.confidence,
+          evidence: [{ file: fileRel, reason: finding.title, line: finding.line }],
+          fixHints: [
+            "Standardize response formats across all API routes.",
+            "Add consistent error handling.",
+            "Always return explicit HTTP status codes.",
+          ],
+        });
+      }
+    } catch (err) {
+      continue;
+    }
+  }
+
+  return findings;
+}
+
+/* ============================================================================
+ * OPTIMISTIC NO ROLLBACK DETECTOR
+ * Finds optimistic UI updates that don't rollback on failure
+ * ========================================================================== */
+
+function findOptimisticNoRollback(repoRoot) {
+  const findings = [];
+  const files = fg.sync(["**/*.{ts,tsx,js,jsx}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: STANDARD_IGNORE_PATTERNS,
+  });
+
+  for (const fileAbs of files) {
+    const code = readFileCached(fileAbs);
+    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+    
+    // Fast path: skip files without optimistic patterns
+    const hasOptimisticUpdate = /\b(setOptimistic|optimisticUpdate|setState.*\bfetch|useMutation.*onMutate)\b/i.test(code);
+    const hasStateUpdate = /\b(setState|set[A-Z]\w*|dispatch|update[A-Z])\b/.test(code);
+    const hasNetworkCall = /\b(fetch|axios|useMutation|mutate)\b/.test(code);
+    
+    if (!hasStateUpdate || !hasNetworkCall) continue;
+    
+    let ast;
+    try {
+      ast = parseFile(code, fileAbs);
+    } catch {
+      continue;
+    }
+
+    try {
+      traverse(ast, {
+        CallExpression(pathNode) {
+          const n = pathNode.node;
+          
+          // Look for setState/dispatch calls followed by fetch without catch/finally rollback
+          if (!t.isMemberExpression(n.callee)) return;
+          
+          const methodName = n.callee.property?.name || "";
+          const isStateUpdate = /^(setState|set[A-Z]|dispatch|update)/.test(methodName);
+          
+          if (!isStateUpdate) return;
+          
+          // Check if parent function has a try-catch with rollback
+          let parentFn = pathNode.findParent(p => p.isFunction());
+          if (!parentFn) return;
+          
+          let hasRollback = false;
+          let hasNetworkInSameBlock = false;
+          
+          parentFn.traverse({
+            CallExpression(inner) {
+              const callee = inner.node.callee;
+              if (isFetchCall(inner.node) || isAxiosCall(inner.node)) {
+                hasNetworkInSameBlock = true;
+              }
+            },
+            CatchClause(catchPath) {
+              // Check if catch has a state update (rollback)
+              catchPath.traverse({
+                CallExpression(rollbackCall) {
+                  if (t.isMemberExpression(rollbackCall.node.callee)) {
+                    const name = rollbackCall.node.callee.property?.name || "";
+                    if (/^(setState|set[A-Z]|dispatch|update)/.test(name)) {
+                      hasRollback = true;
+                    }
+                  }
+                }
+              });
+            }
+          });
+          
+          // If there's a state update, network call, but no rollback in catch
+          if (hasNetworkInSameBlock && !hasRollback) {
+            const loc = n.loc;
+            findings.push({
+              id: stableId("F_OPTIMISTIC_NO_ROLLBACK", `${fileRel}:${loc?.start?.line || 0}`),
+              severity: "WARN",
+              category: "OptimisticNoRollback",
+              title: "Optimistic update without rollback on failure",
+              why: "State is updated before network call completes, but there's no rollback if the request fails. Users see stale/incorrect data.",
+              confidence: "med",
+              evidence: [evidenceFromLoc(fileAbs, repoRoot, loc, "Optimistic state update")].filter(Boolean),
+              fixHints: [
+                "Add a catch block that reverts the state to previous value on failure.",
+                "Use react-query's onMutate/onError for automatic rollback.",
+                "Store previous state before update and restore it on error.",
+              ],
+            });
+          }
+        }
+      });
+    } catch {
+      continue;
+    }
+  }
+
+  return findings;
+}
+
+/* ============================================================================
+ * SILENT CATCH DETECTOR (Enhanced)
+ * Finds catch blocks that swallow errors without logging or re-throwing
+ * ========================================================================== */
+
+function findSilentCatch(repoRoot) {
+  const findings = [];
+  const files = fg.sync(["**/*.{ts,tsx,js,jsx}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: STANDARD_IGNORE_PATTERNS,
+  });
+
+  for (const fileAbs of files) {
+    const code = readFileCached(fileAbs);
+    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+    
+    // Fast path: skip files without try-catch
+    if (!/\bcatch\s*\(/.test(code)) continue;
+    
+    let ast;
+    try {
+      ast = parseFile(code, fileAbs);
+    } catch {
+      continue;
+    }
+
+    try {
+      traverse(ast, {
+        CatchClause(pathNode) {
+          const catchBody = pathNode.node.body;
+          const catchParam = pathNode.node.param?.name || "error";
+          
+          // Check if catch body is empty or only has comments
+          if (!catchBody.body || catchBody.body.length === 0) {
+            // Empty catch - already covered by findEmptyCatch
+            return;
+          }
+          
+          // Check if catch actually handles the error
+          let logsError = false;
+          let rethrowsError = false;
+          let showsUserError = false;
+          let hasConditionalReturn = false;
+          
+          pathNode.traverse({
+            CallExpression(inner) {
+              const callee = inner.node.callee;
+              const args = inner.node.arguments;
+              
+              // Check for console.error, console.log, logger.error, etc.
+              if (t.isMemberExpression(callee)) {
+                const obj = callee.object?.name || "";
+                const prop = callee.property?.name || "";
+                if ((obj === "console" || /logger|log/i.test(obj)) && /error|warn|log/.test(prop)) {
+                  // Check if it logs the error variable
+                  const argsStr = args.map(a => code.slice(a.start, a.end)).join(",");
+                  if (argsStr.includes(catchParam) || argsStr.includes("error") || argsStr.includes("err")) {
+                    logsError = true;
+                  }
+                }
+                // Check for toast.error, notification.error, etc.
+                if (/toast|notification|alert|message/i.test(obj) && /error|warn|fail/.test(prop)) {
+                  showsUserError = true;
+                }
+              }
+            },
+            ThrowStatement() {
+              rethrowsError = true;
+            },
+            ReturnStatement(ret) {
+              // Returning early might be intentional error handling
+              const ifParent = ret.findParent(p => p.isIfStatement());
+              if (ifParent) hasConditionalReturn = true;
+            }
+          });
+          
+          // Silent catch: doesn't log, doesn't rethrow, doesn't show user error
+          if (!logsError && !rethrowsError && !showsUserError && !hasConditionalReturn) {
+            const loc = pathNode.node.loc;
+            findings.push({
+              id: stableId("F_SILENT_CATCH", `${fileRel}:${loc?.start?.line || 0}`),
+              severity: "WARN",
+              category: "SilentCatch",
+              title: "Catch block swallows error silently",
+              why: "Errors are caught but not logged, reported, or shown to users. This makes debugging nearly impossible and hides failures.",
+              confidence: "med",
+              evidence: [evidenceFromLoc(fileAbs, repoRoot, loc, "Silent catch block")].filter(Boolean),
+              fixHints: [
+                `Add console.error(${catchParam}) or a logger call.`,
+                "Show user-friendly error message (toast, alert, etc.).",
+                "Re-throw the error if it should propagate.",
+                "If intentionally ignoring, add a comment explaining why.",
+              ],
+            });
+          }
+        }
+      });
+    } catch {
+      continue;
+    }
+  }
+
+  return findings;
+}
+
+/* ============================================================================
+ * METHOD MISMATCH DETECTOR
+ * Finds client-side GET requests to POST-only endpoints and vice versa
+ * ========================================================================== */
+
+function findMethodMismatch(truthpack) {
+  if (!truthpack?.routes) return [];
+  
+  const findings = [];
+  const serverRoutes = truthpack.routes.server || [];
+  const clientRefs = truthpack.routes.clientRefs || [];
+  
+  // Build a map of route -> allowed methods
+  const routeMethodMap = new Map();
+  for (const route of serverRoutes) {
+    const key = normalizeRoutePath(route.path);
+    if (!routeMethodMap.has(key)) {
+      routeMethodMap.set(key, new Set());
+    }
+    if (route.method) {
+      routeMethodMap.get(key).add(route.method.toUpperCase());
+    }
+  }
+  
+  // Check client refs for method mismatches
+  for (const ref of clientRefs) {
+    if (!ref.method || !ref.path) continue;
+    
+    const clientMethod = ref.method.toUpperCase();
+    const normalizedPath = normalizeRoutePath(ref.path);
+    
+    // Find matching server route
+    const allowedMethods = routeMethodMap.get(normalizedPath);
+    
+    if (allowedMethods && allowedMethods.size > 0 && !allowedMethods.has(clientMethod)) {
+      // Method mismatch found
+      const allowed = Array.from(allowedMethods).join(", ");
+      findings.push({
+        id: stableId("F_METHOD_MISMATCH", `${ref.file || "unknown"}:${ref.line || 0}:${ref.path}`),
+        severity: "BLOCK",
+        category: "MethodMismatch",
+        title: `${clientMethod} request to ${allowed}-only endpoint: ${ref.path}`,
+        why: `Client makes ${clientMethod} request but server only accepts ${allowed}. This will fail with 405 Method Not Allowed.`,
+        confidence: "high",
+        evidence: ref.file ? [{
+          file: ref.file,
+          line: ref.line,
+          reason: `Client ${clientMethod} to ${allowed}-only route`,
+        }] : [],
+        fixHints: [
+          `Change client request method from ${clientMethod} to ${allowed}.`,
+          `Add ${clientMethod} handler to the server route.`,
+          "Verify the API contract matches documentation.",
+        ],
+      });
+    }
+  }
+  
+  return findings;
+}
+
+// Helper to normalize route paths for comparison
+function normalizeRoutePath(routePath) {
+  if (!routePath) return "";
+  return routePath
+    .replace(/\[([^\]]+)\]/g, ":$1")  // [id] -> :id
+    .replace(/\/+/g, "/")              // multiple slashes -> single
+    .replace(/\/$/, "")                // remove trailing slash
+    .toLowerCase();
+}
+
+/* ============================================================================
+ * DEAD UI DETECTOR (Enhanced)
+ * Finds buttons, forms, and links that do nothing
+ * ========================================================================== */
+
+function findDeadUI(repoRoot) {
+  const findings = [];
+  const files = fg.sync(["**/*.{tsx,jsx}"], {
+    cwd: repoRoot,
+    absolute: true,
+    ignore: STANDARD_IGNORE_PATTERNS,
+  });
+
+  for (const fileAbs of files) {
+    const code = readFileCached(fileAbs);
+    const fileRel = path.relative(repoRoot, fileAbs).replace(/\\/g, "/");
+    
+    // Fast path: skip files without interactive elements
+    if (!/<(button|Button|form|Form|a|Link)\b/.test(code)) continue;
+    
+    let ast;
+    try {
+      ast = parseFile(code, fileAbs);
+    } catch {
+      continue;
+    }
+
+    try {
+      traverse(ast, {
+        JSXElement(pathNode) {
+          const opening = pathNode.node.openingElement;
+          const tagName = opening.name?.name || opening.name?.property?.name || "";
+          
+          // Check for buttons, forms, links
+          if (!/^(button|Button|form|Form|a|Link)$/i.test(tagName)) return;
+          
+          const attrs = opening.attributes || [];
+          let hasOnClick = false;
+          let hasOnSubmit = false;
+          let hasHref = false;
+          let hasAction = false;
+          let hasType = false;
+          let isDisabled = false;
+          
+          for (const attr of attrs) {
+            if (!t.isJSXAttribute(attr)) continue;
+            const name = attr.name?.name || "";
+            
+            if (name === "onClick" || name === "onPress") hasOnClick = true;
+            if (name === "onSubmit") hasOnSubmit = true;
+            if (name === "href" || name === "to") hasHref = true;
+            if (name === "action") hasAction = true;
+            if (name === "type") hasType = true;
+            if (name === "disabled") isDisabled = true;
+          }
+          
+          // Button without onClick (unless it's a submit button or disabled)
+          if (/button/i.test(tagName) && !hasOnClick && !isDisabled) {
+            const isSubmitType = attrs.some(a => 
+              t.isJSXAttribute(a) && 
+              a.name?.name === "type" && 
+              t.isStringLiteral(a.value) && 
+              a.value.value === "submit"
+            );
+            
+            if (!isSubmitType) {
+              const loc = opening.loc;
+              findings.push({
+                id: stableId("F_DEAD_UI", `${fileRel}:${loc?.start?.line || 0}:button`),
+                severity: "WARN",
+                category: "DeadUI",
+                title: "Button without onClick handler",
+                why: "This button does nothing when clicked. Users expect buttons to perform actions.",
+                confidence: "med",
+                evidence: [evidenceFromLoc(fileAbs, repoRoot, loc, "Dead button")].filter(Boolean),
+                fixHints: [
+                  "<Button onClick={() => handleAction()}>Click Me</Button>",
+                  "For submit: <Button type=\"submit\">Submit</Button>",
+                  "For disabled: <Button disabled>Coming Soon</Button>",
+                ],
+              });
+            }
+          }
+          
+          // Form without onSubmit or action
+          if (/form/i.test(tagName) && !hasOnSubmit && !hasAction) {
+            const loc = opening.loc;
+            findings.push({
+              id: stableId("F_DEAD_UI", `${fileRel}:${loc?.start?.line || 0}:form`),
+              severity: "WARN",
+              category: "DeadUI",
+              title: "Form without onSubmit or action",
+              why: "This form does nothing when submitted. Form data won't be processed.",
+              confidence: "med",
+              evidence: [evidenceFromLoc(fileAbs, repoRoot, loc, "Dead form")].filter(Boolean),
+              fixHints: [
+                "Add an onSubmit handler to process form data.",
+                "Or add an action attribute for server-side submission.",
+              ],
+            });
+          }
+          
+          // Link without href
+          if (/^(a|Link)$/i.test(tagName) && !hasHref) {
+            const loc = opening.loc;
+            findings.push({
+              id: stableId("F_DEAD_UI", `${fileRel}:${loc?.start?.line || 0}:link`),
+              severity: "WARN",
+              category: "DeadUI",
+              title: "Link without href or to prop",
+              why: "This link goes nowhere. Users expect links to navigate somewhere.",
+              confidence: "med",
+              evidence: [evidenceFromLoc(fileAbs, repoRoot, loc, "Dead link")].filter(Boolean),
+              fixHints: [
+                "Add href prop with the target URL.",
+                "If using Next.js Link, ensure href is provided.",
+                "If it's a button styled as link, use a button element instead.",
+              ],
+            });
+          }
+        }
+      });
+    } catch {
+      continue;
+    }
+  }
+
+  return findings;
+}
+
+module.exports = {
+  // V3: Cache management - call after scan completes to prevent memory leaks
+  clearFileCache,
+  
+  // V3: Entropy helper - exported for testing/reuse
+  getShannonEntropy,
+  
+  // Analyzers
+  findMissingRoutes,
+  findEnvGaps,
+  findFakeSuccess,
+  findGhostAuth,
+  findStripeWebhookViolations,
+  findPaidSurfaceNotEnforced,
+  findOwnerModeBypass,
+  findMockData,
+  findTodoFixme,
+  findConsoleLogs,
+  findHardcodedSecrets,
+  findDeadCode,
+  findDeprecatedApis,
+  findEmptyCatch,
+  findUnsafeRegex,
+  // Enhanced analyzers
+  findSecurityVulnerabilities,
+  findPerformanceIssues,
+  findCodeQualityIssues,
+  // Advanced analyzers
+  findCrossFileIssues,
+  findTypeSafetyIssues,
+  findAccessibilityIssues,
+  findAPIConsistencyIssues,
+  // NEW: AI Hallucination Detectors
+  findOptimisticNoRollback,
+  findSilentCatch,
+  findMethodMismatch,
+  findDeadUI,
+};