@vibecheckai/cli 3.4.0 → 3.5.1

package/bin/runners/lib/detectors-v2.js

@@ -1,622 +1,860 @@
 /**
- * Truth Context – MCP Tools for Evidence‑Backed AI
- *
- * Core context-engine tools that surface **truth-backed** context for AI agents.
- * Every response is grounded in concrete evidence with file/line citations
- * and explicit confidence scores.
- *
- * This is the "Truth Firewall", exposed to agents as an "Evidence Pack" / "Truth Pack". [web:3]
- *
- * Tools:
- *   - vibecheck.ctx           – Build a repo-level Truth Pack (routes, auth, billing, env, schema)
- *   - vibecheck.verify_claim  – Check whether a claim is backed by real evidence
- *   - vibecheck.evidence      – Pull code-level evidence for a specific file/function
+ * Canonical Detectors v2
+ * 
+ * Implementation of all spec-defined detectors that produce v2-compliant findings.
+ * Each detector has a unique ID and produces evidence-backed findings.
+ * 
+ * Detector Categories:
+ * - Routes (D_ROUTE_*)
+ * - Auth Coverage (D_AUTH_*)
+ * - Env (D_ENV_*)
+ * - Fake Success / Truth (D_FAKE_SUCCESS_*, D_SILENT_CATCH)
+ * - Dead UI (D_DEAD_*, D_UI_*)
+ * - Billing/Stripe (D_STRIPE_*)
+ * - Entitlements (D_LOCAL_BYPASS_*)
+ * - Drift (D_CONTRACTS_*)
  */
 
-import fs from "fs/promises";
-import path from "path";
-import { execSync } from "child_process";
-
-// ============================================================================
-// TRUTH CONTEXT TOOLS
-// ============================================================================
-
-export const TRUTH_CONTEXT_TOOLS = [
-  {
-    name: "vibecheck.ctx",
-    description: `📋 Build a repo Truth Pack: routes, auth, billing, env vars, schema.
-
-Generates an evidence-backed context bundle with file/line citations.
-Use this before the agent makes any architectural or behavioral claims
-about the codebase.
-
-Returns:
-- routes: All detected routes with handlers and middleware
-- auth: Auth guards, protected routes, auth flow indicators
-- billing: Payment gates, subscription checks, paid feature indicators
-- env: Environment variables (declared vs used, mismatches)
-- schema: Database schema and TypeScript contracts
-- confidence: Aggregate confidence score (0–1) for the extracted view`,
-    inputSchema: {
-      type: "object",
-      properties: {
-        scope: {
-          type: "string",
-          enum: ["all", "routes", "auth", "billing", "env", "schema"],
-          description: "Which slice of context to extract (default: all)",
-          default: "all",
-        },
-        path: {
-          type: "string",
-          description: "Project root path (default: current working directory)",
-        },
-      },
-    },
-  },
-  {
-    name: "vibecheck.verify_claim",
-    description: `🔍 Truth Firewall check – verify that a claim is backed by code.
-
-Run this before asserting that something exists, is configured, or is enforced.
-Returns concrete evidence (file/line) when the claim is supported,
-or a structured rejection with an explanation when it is not.
-
-Examples:
-- "Route /api/users exists"        → VERIFIED with handler at src/routes/users.ts:45
-- "Auth is required for /admin"    → VERIFIED via middleware at src/middleware/auth.ts:12
-- "Stripe is configured"           → REJECTED: No evidence of Stripe integration found`,
-    inputSchema: {
-      type: "object",
-      properties: {
-        claim_type: {
-          type: "string",
-          enum: [
-            "route",
-            "endpoint",
-            "env_var",
-            "middleware",
-            "auth_guard",
-            "billing_gate",
-            "file",
-            "function",
-          ],
-          description: "Category of claim to verify",
-        },
-        claim: {
-          type: "string",
-          description:
-            "The claim subject (e.g. '/api/users', 'AUTH_SECRET', 'authMiddleware')",
-        },
-        path: {
-          type: "string",
-          description: "Project root path (default: current working directory)",
-        },
-      },
-      required: ["claim_type", "claim"],
-    },
-  },
-  {
-    name: "vibecheck.evidence",
-    description: `📎 Retrieve code evidence for a file or symbol.
-
-Returns an annotated code snippet with line numbers for precise citation.
-Use this when the agent needs to quote or reason about specific code blocks
-in its response.`,
-    inputSchema: {
-      type: "object",
-      properties: {
-        file: {
-          type: "string",
-          description: "File path relative to the project root",
-        },
-        function_name: {
-          type: "string",
-          description: "Optional function/class name to locate within the file",
-        },
-        line: {
-          type: "number",
-          description: "Optional 1-based line number to center the snippet on",
-        },
-        context_lines: {
-          type: "number",
-          description:
-            "Number of lines of context before/after the target (default: 10)",
-          default: 10,
-        },
-        path: {
-          type: "string",
-          description: "Project root path (default: current working directory)",
-        },
-      },
-      required: ["file"],
-    },
-  },
-];
-
-// ============================================================================
-// TOOL DISPATCH
-// ============================================================================
-
-export async function handleTruthContextTool(toolName, args) {
-  const projectPath = args.path || process.cwd();
-
-  switch (toolName) {
-    case "vibecheck.ctx":
-      return await getTruthPack(projectPath, args.scope || "all");
-    case "vibecheck.verify_claim":
-      return await verifyClaim(projectPath, args.claim_type, args.claim);
-    case "vibecheck.evidence":
-      return await getEvidence(projectPath, args.file, args);
-    default:
-      return { error: `Unknown tool: ${toolName}` };
-  }
-}
+"use strict";
 
-// ============================================================================
-// CONTEXT EXTRACTION
-// ============================================================================
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { createFindingV2, createEvidence, generateFingerprint } = require("./schema-validator");
 
-async function getTruthPack(projectPath, scope) {
-  const truthPack = {
-    version: "1.0.0",
-    generatedAt: new Date().toISOString(),
-    projectPath,
-    scope,
-    confidence: 0,
-    sections: {},
-  };
+// =============================================================================
+// B1) Routes Detectors
+// =============================================================================
 
-  try {
-    if (scope === "all" || scope === "routes") {
-      truthPack.sections.routes = await extractRoutes(projectPath);
-    }
-    if (scope === "all" || scope === "auth") {
-      truthPack.sections.auth = await extractAuth(projectPath);
-    }
-    if (scope === "all" || scope === "billing") {
-      truthPack.sections.billing = await extractBilling(projectPath);
-    }
-    if (scope === "all" || scope === "env") {
-      truthPack.sections.env = await extractEnvVars(projectPath);
+/**
+ * D_ROUTE_MISSING (BLOCK)
+ * Trigger: clientCalls contains /api/x but truthpack routes has no matching endpoint
+ */
+function detectRouteMissing(truthpack) {
+  const findings = [];
+  const serverRoutes = truthpack.routes || [];
+  const clientCalls = truthpack.clientCalls || [];
+
+  for (const call of clientCalls) {
+    const resolved = call.resolvedPath || call.urlTemplate;
+    const method = call.method || "UNKNOWN";
+
+    const match = serverRoutes.find(r => 
+      routeMatches(r.path, resolved) && 
+      (r.methods.includes(method) || r.methods.includes("*"))
+    );
+
+    if (!match) {
+      findings.push(createFindingV2({
+        detectorId: "ROUTE_MISSING",
+        severity: "BLOCK",
+        category: "Routes",
+        scope: "client",
+        title: `Client calls ${method} ${resolved} but no server route exists`,
+        why: "AI frequently invents endpoints. This will cause 404 errors or silent failures in production.",
+        confidence: call.confidence || "medium",
+        evidence: call.evidence || [
+          createEvidence({
+            kind: "file",
+            reason: "Client call site",
+            file: call.evidence?.[0]?.file || "unknown",
+            lines: call.evidence?.[0]?.lines || "1-1",
+          })
+        ],
+        fixHints: [
+          "Create the missing server route handler",
+          "Or update the client to call an existing route",
+          "Check truthpack.routes for available endpoints"
+        ],
+      }));
     }
-    if (scope === "all" || scope === "schema") {
-      truthPack.sections.schema = await extractSchema(projectPath);
+  }
+
+  return findings;
+}
+
+/**
+ * D_ROUTE_METHOD_MISMATCH (BLOCK/WARN)
+ * Trigger: client uses POST but server exposes GET (or vice versa)
+ */
+function detectRouteMethodMismatch(truthpack) {
+  const findings = [];
+  const serverRoutes = truthpack.routes || [];
+  const clientCalls = truthpack.clientCalls || [];
+
+  for (const call of clientCalls) {
+    const resolved = call.resolvedPath || call.urlTemplate;
+    const clientMethod = call.method || "UNKNOWN";
+
+    const pathMatch = serverRoutes.find(r => routeMatches(r.path, resolved));
+    
+    if (pathMatch && !pathMatch.methods.includes(clientMethod) && !pathMatch.methods.includes("*")) {
+      const isCritical = /checkout|login|save|pay|submit|register/i.test(resolved);
+      
+      findings.push(createFindingV2({
+        detectorId: "ROUTE_METHOD_MISMATCH",
+        severity: isCritical ? "BLOCK" : "WARN",
+        category: "Routes",
+        scope: "client",
+        title: `Method mismatch: client uses ${clientMethod} but server only handles ${pathMatch.methods.join("/")} for ${resolved}`,
+        why: "Method mismatch will cause 405 errors. Critical paths (checkout/login) must match exactly.",
+        confidence: "high",
+        evidence: [
+          createEvidence({
+            kind: "file",
+            reason: "Client call site",
+            file: call.evidence?.[0]?.file || "unknown",
+            lines: call.evidence?.[0]?.lines || "1-1",
+          }),
+          createEvidence({
+            kind: "file",
+            reason: "Server route handler",
+            file: pathMatch.handler?.file || "unknown",
+            lines: "1-1",
+          })
+        ],
+        fixHints: [
+          `Update client to use ${pathMatch.methods[0]} method`,
+          `Or add ${clientMethod} handler to server route`
+        ],
+      }));
     }
+  }
 
-    const sections = Object.values(truthPack.sections);
-    if (sections.length > 0) {
-      truthPack.confidence =
-        sections.reduce((sum, section) => sum + (section.confidence || 0), 0) /
-        sections.length;
+  return findings;
+}
+
+/**
+ * D_ROUTE_PREFIX_DRIFT (WARN→BLOCK)
+ * Trigger: Fastify registered under /api/v1 but client hits /api/
+ */
+function detectRoutePrefixDrift(truthpack) {
+  const findings = [];
+  const fastifyPrefixes = truthpack.stack?.fastify?.prefixes || [];
+  const clientCalls = truthpack.clientCalls || [];
+
+  if (fastifyPrefixes.length === 0) return findings;
+
+  const prefixSet = new Set(fastifyPrefixes);
+  let mismatchCount = 0;
+
+  for (const call of clientCalls) {
+    const resolved = call.resolvedPath || call.urlTemplate;
+    
+    // Check if client path uses a known prefix
+    const usesKnownPrefix = fastifyPrefixes.some(prefix => resolved.startsWith(prefix));
+    
+    if (!usesKnownPrefix && resolved.startsWith("/api/")) {
+      mismatchCount++;
     }
+  }
 
-    return truthPack;
-  } catch (error) {
-    return {
-      error: error.message,
-      projectPath,
-      suggestion: "Run `vibecheck init` to set up the project",
-    };
+  if (mismatchCount > 0) {
+    findings.push(createFindingV2({
+      detectorId: "ROUTE_PREFIX_DRIFT",
+      severity: mismatchCount > 5 ? "BLOCK" : "WARN",
+      category: "Routes",
+      scope: "client",
+      title: `${mismatchCount} client calls don't match Fastify prefixes: ${fastifyPrefixes.join(", ")}`,
+      why: "Prefix drift causes silent failures. Clients must use the correct API prefix.",
+      confidence: "medium",
+      evidence: [
+        createEvidence({
+          kind: "file",
+          reason: "Fastify entry file with prefix registration",
+          file: truthpack.stack?.fastify?.entryFile || "unknown",
+          lines: "1-1",
+        })
+      ],
+      fixHints: [
+        `Update client calls to use correct prefix (${fastifyPrefixes[0] || "/api"})`,
+        "Or update Fastify prefix registration to match client expectations"
+      ],
+    }));
   }
-}
 
-async function extractRoutes(projectPath) {
-  const routes = [];
-  const routePatterns = [
-    /app\.(get|post|put|patch|delete|use)\s*\(\s*['"`]([^'"`]+)['"`]/gi,
-    /router\.(get|post|put|patch|delete|use)\s*\(\s*['"`]([^'"`]+)['"`]/gi,
-    /@(Get|Post|Put|Patch|Delete)\s*\(\s*['"`]([^'"`]+)['"`]/gi,
-  ];
+  return findings;
+}
 
-  const files = await findSourceFiles(projectPath, [".ts", ".js", ".tsx", ".jsx"]);
+// =============================================================================
+// B2) Auth Coverage Detectors
+// =============================================================================
 
-  for (const file of files.slice(0, 50)) {
-    try {
-      const content = await fs.readFile(file, "utf8");
-      const relPath = path.relative(projectPath, file);
-
-      for (const pattern of routePatterns) {
-        let match;
-        pattern.lastIndex = 0;
-        while ((match = pattern.exec(content)) !== null) {
-          const line = content.substring(0, match.index).split("\n").length;
-          routes.push({
-            method: match[1].toUpperCase(),
-            path: match[2],
-            file: relPath,
-            line,
-            evidence: {
-              snippet: content.split("\n")[line - 1]?.trim(),
-              verifiedAt: new Date().toISOString(),
-            },
-          });
-        }
+/**
+ * D_AUTH_PROTECTED_ROUTE_ACCESSIBLE_ANON (BLOCK) - runtime
+ * Trigger: --verify-auth ANON pass can access protected route
+ */
+function detectAuthProtectedAccessibleAnon(realityReport, authContract) {
+  const findings = [];
+  if (!realityReport?.run?.pass === "anon") return findings;
+
+  const protectedPatterns = authContract?.protectedRoutes || [];
+  const anonPages = realityReport.pages || [];
+  const anonNetwork = realityReport.network || [];
+
+  for (const pattern of protectedPatterns) {
+    // Check if anon pass successfully accessed a protected route
+    const accessed = anonNetwork.filter(req => 
+      matchPattern(pattern.pattern, req.url) && 
+      req.status >= 200 && req.status < 300
+    );
+
+    for (const req of accessed) {
+      if (pattern.expect?.anon === "deny" || pattern.expect?.anon === "redirect") {
+        findings.push(createFindingV2({
+          detectorId: "AUTH_PROTECTED_ROUTE_ACCESSIBLE_ANON",
+          severity: "BLOCK",
+          category: "AuthCoverage",
+          scope: "runtime",
+          title: `Protected route ${req.url} accessible to anonymous users`,
+          why: "Auth contract expects denial/redirect but got 2xx. This is a security bypass.",
+          confidence: "high",
+          evidence: [
+            createEvidence({
+              kind: "request",
+              reason: "Successful anonymous request to protected route",
+              url: req.url,
+              httpStatus: req.status,
+              requestId: req.id,
+            })
+          ],
+          fixHints: [
+            "Add server-side auth middleware to this route",
+            "Ensure Next.js middleware matcher covers this path",
+            "Verify auth contract pattern is correct"
+          ],
+          repro: {
+            steps: [
+              `Navigate to ${req.url} without authentication`,
+              "Observe that the page loads successfully (should be denied)"
+            ],
+            url: req.url,
+          },
+        }));
       }
-    } catch {
-      // Skip unreadable files
     }
   }
 
-  return {
-    count: routes.length,
-    routes: routes.slice(0, 100),
-    confidence: routes.length > 0 ? 0.8 : 0.2,
-  };
+  return findings;
 }
 
-async function extractAuth(projectPath) {
-  const authIndicators = [];
-  const authPatterns = [
-    /auth(enticate|orize|Middleware|Guard|Check)/gi,
-    /isAuthenticated|requireAuth|verifyToken|jwt\.verify/gi,
-    /passport\.(authenticate|use)/gi,
-    /session\.|cookie\./gi,
-  ];
-
-  const files = await findSourceFiles(projectPath, [".ts", ".js"]);
-
-  for (const file of files.slice(0, 50)) {
-    try {
-      const content = await fs.readFile(file, "utf8");
-      const relPath = path.relative(projectPath, file);
-
-      for (const pattern of authPatterns) {
-        let match;
-        pattern.lastIndex = 0;
-        while ((match = pattern.exec(content)) !== null) {
-          const line = content.substring(0, match.index).split("\n").length;
-          authIndicators.push({
-            type: "auth_indicator",
-            match: match[0],
-            file: relPath,
-            line,
-          });
-        }
-      }
-    } catch {
-      // Skip
+/**
+ * D_AUTH_PROTECTED_ROUTE_BLOCKED_WHEN_AUTHED (BLOCK) - runtime
+ * Trigger: AUTH pass still denied/redirected repeatedly
+ */
+function detectAuthProtectedBlockedWhenAuthed(realityReport, authContract) {
+  const findings = [];
+  if (!realityReport?.run?.pass === "authed") return findings;
+
+  const protectedPatterns = authContract?.protectedRoutes || [];
+  const authedNetwork = realityReport.network || [];
+
+  for (const pattern of protectedPatterns) {
+    const blocked = authedNetwork.filter(req =>
+      matchPattern(pattern.pattern, req.url) &&
+      (req.status === 401 || req.status === 403 || req.status >= 300 && req.status < 400)
+    );
+
+    if (blocked.length > 2 && pattern.expect?.authed === "allow") {
+      findings.push(createFindingV2({
+        detectorId: "AUTH_PROTECTED_ROUTE_BLOCKED_WHEN_AUTHED",
+        severity: "BLOCK",
+        category: "AuthCoverage",
+        scope: "runtime",
+        title: `Protected route ${pattern.pattern} blocks authenticated users`,
+        why: "Auth contract expects allow but authenticated user is denied/redirected repeatedly.",
+        confidence: "high",
+        evidence: blocked.slice(0, 3).map(req => createEvidence({
+          kind: "request",
+          reason: "Request denied despite authentication",
+          url: req.url,
+          httpStatus: req.status,
+          requestId: req.id,
+        })),
+        fixHints: [
+          "Check if session/token is being passed correctly",
+          "Verify middleware is not over-blocking",
+          "Check for redirect loops"
+        ],
+      }));
     }
   }
 
-  return {
-    count: authIndicators.length,
-    indicators: authIndicators.slice(0, 50),
-    confidence:
-      authIndicators.length > 5
-        ? 0.8
-        : authIndicators.length > 0
-        ? 0.5
-        : 0.1,
-  };
+  return findings;
 }
 
-async function extractBilling(projectPath) {
-  const billingIndicators = [];
-  const billingPatterns = [
-    /stripe|paddle|lemonsqueezy|gumroad/gi,
-    /subscription|payment|checkout|invoice/gi,
-    /isPro|isPremium|isEnterprise|hasPaid/gi,
-    /price|tier|plan/gi,
-  ];
-
-  const files = await findSourceFiles(projectPath, [".ts", ".js"]);
+/**
+ * D_AUTH_CONTRACT_DRIFT (WARN/BLOCK)
+ * Trigger: contracts/auth.json patterns don't match middleware matcher
+ */
+function detectAuthContractDrift(truthpack, authContract) {
+  const findings = [];
+  const middlewareMatchers = new Set(truthpack.auth?.middlewareMatchers || []);
+  const contractPatterns = new Set(authContract?.protectedRoutes?.map(r => r.pattern) || []);
+
+  // Patterns in contract but not in middleware
+  for (const pattern of contractPatterns) {
+    if (!middlewareMatchers.has(pattern)) {
+      findings.push(createFindingV2({
+        detectorId: "AUTH_CONTRACT_DRIFT",
+        severity: "BLOCK",
+        category: "Drift",
+        scope: "contracts",
+        title: `Auth pattern "${pattern}" in contract but not in middleware`,
+        why: "Contract expects protection but middleware doesn't enforce it. Security boundary may be exposed.",
+        confidence: "high",
+        evidence: [
+          createEvidence({
+            kind: "file",
+            reason: "Auth contract file",
+            file: ".vibecheck/contracts/auth.json",
+            lines: "1-1",
+          })
+        ],
+        fixHints: [
+          "Add pattern to middleware matcher",
+          "Or run 'vibecheck ctx sync' to update contract"
+        ],
+      }));
+    }
+  }
 
-  for (const file of files.slice(0, 30)) {
-    try {
-      const content = await fs.readFile(file, "utf8");
-      const relPath = path.relative(projectPath, file);
-
-      for (const pattern of billingPatterns) {
-        let match;
-        pattern.lastIndex = 0;
-        while ((match = pattern.exec(content)) !== null) {
-          const line = content.substring(0, match.index).split("\n").length;
-          billingIndicators.push({
-            type: "billing_indicator",
-            match: match[0],
-            file: relPath,
-            line,
-          });
-        }
-      }
-    } catch {
-      // Skip
+  // Patterns in middleware but not in contract (WARN - might be intentional)
+  for (const pattern of middlewareMatchers) {
+    if (!contractPatterns.has(pattern)) {
+      findings.push(createFindingV2({
+        detectorId: "AUTH_CONTRACT_DRIFT",
+        severity: "WARN",
+        category: "Drift",
+        scope: "contracts",
+        title: `Middleware pattern "${pattern}" not declared in auth contract`,
+        why: "Middleware protects a pattern not in contract. AI agents won't know about this protection.",
+        confidence: "medium",
+        evidence: [
+          createEvidence({
+            kind: "file",
+            reason: "Middleware file",
+            file: truthpack.stack?.next?.middlewareFile || "middleware.ts",
+            lines: "1-1",
+          })
+        ],
+        fixHints: [
+          "Run 'vibecheck ctx sync' to update contract"
+        ],
+      }));
     }
   }
 
-  return {
-    count: billingIndicators.length,
-    indicators: billingIndicators.slice(0, 30),
-    confidence:
-      billingIndicators.length > 3
-        ? 0.7
-        : billingIndicators.length > 0
-        ? 0.4
-        : 0.1,
-  };
+  return findings;
 }
 
-async function extractEnvVars(projectPath) {
-  const declared = [];
-  const used = [];
+// =============================================================================
+// B3) Env Detectors
+// =============================================================================
 
-  const envFiles = [".env.example", ".env.local.example", ".env.sample"];
-  for (const envFile of envFiles) {
-    try {
-      const content = await fs.readFile(path.join(projectPath, envFile), "utf8");
-      const lines = content.split("\n");
-      for (let i = 0; i < lines.length; i++) {
-        const match = lines[i].match(/^([A-Z][A-Z0-9_]*)=/);
-        if (match) {
-          declared.push({
-            name: match[1],
-            file: envFile,
-            line: i + 1,
-          });
-        }
+/**
+ * D_ENV_USED_BUT_UNDECLARED (WARN→BLOCK if required)
+ * Trigger: truthpack envUsage includes FOO but contracts/env.json does not
+ * Enhanced with better required/optional detection
+ */
+function detectEnvUsedButUndeclared(truthpack, envContract) {
+  const findings = [];
+  const envUsage = truthpack.envUsage || [];
+  const declaredVars = new Set(envContract?.vars?.map(v => v.name) || []);
+
+  for (const usage of envUsage) {
+    if (!declaredVars.has(usage.name)) {
+      // Check if usage pattern suggests optional
+      const usageCode = usage.locations?.[0]?.snippet || "";
+      const hasOptionalPattern = hasOptionalUsagePattern(usageCode);
+      
+      // Determine if required based on name patterns and usage
+      const isRequired = !hasOptionalPattern && 
+        (usage.inferredRequiredness === "required" || isLikelyRequired(usage.name));
+      
+      // Skip reporting for common optional env vars that are typically not documented
+      const commonOptionalVars = [
+        /^DEBUG$/i,
+        /^LOG_LEVEL$/i,
+        /^NODE_ENV$/i,
+        /^CI$/i,
+        /^VERCEL/i,
+        /^GITHUB_/i,
+        /^NEXT_PUBLIC_VERCEL/i,
+      ];
+      
+      if (commonOptionalVars.some(p => p.test(usage.name))) {
+        continue;
       }
-    } catch {
-      // File does not exist
+      
+      findings.push(createFindingV2({
+        detectorId: "ENV_USED_BUT_UNDECLARED",
+        severity: isRequired ? "BLOCK" : "WARN",
+        category: "Env",
+        scope: "server",
+        title: `Env var ${usage.name} used but not declared in contract`,
+        why: isRequired
+          ? "Required env var missing from contract. Deployment will fail if not set."
+          : "Env var used but not documented. AI won't know about this dependency.",
+        confidence: isRequired ? "high" : "medium",
+        evidence: usage.locations?.slice(0, 3).map(loc => createEvidence({
+          kind: "file",
+          reason: `Usage of ${usage.name}`,
+          file: loc.file,
+          lines: loc.lines,
+          snippet: loc.snippetHash,
+        })) || [],
+        fixHints: [
+          "Add to .env.example with appropriate default/placeholder",
+          "Run 'vibecheck ctx sync' to update env contract",
+          isRequired ? "Ensure this var is set in all environments" : null
+        ].filter(Boolean),
+      }));
     }
   }
 
-  const files = await findSourceFiles(projectPath, [".ts", ".js"]);
-  for (const file of files.slice(0, 30)) {
-    try {
-      const content = await fs.readFile(file, "utf8");
-      const relPath = path.relative(projectPath, file);
-      const pattern = /process\.env\.([A-Z][A-Z0-9_]*)/g;
-      let match;
-      while ((match = pattern.exec(content)) !== null) {
-        const line = content.substring(0, match.index).split("\n").length;
-        used.push({
-          name: match[1],
-          file: relPath,
-          line,
-        });
-      }
-    } catch {
-      // Skip
-    }
-  }
+  return findings;
+}
+
+// =============================================================================
+// B4) Fake Success / Truth Detectors
+// =============================================================================
 
-  const declaredNames = new Set(declared.map((d) => d.name));
-  const usedNames = new Set(used.map((u) => u.name));
-  const undeclared = [...usedNames].filter((name) => !declaredNames.has(name));
-  const unused = [...declaredNames].filter((name) => !usedNames.has(name));
-
-  return {
-    declared: declared.slice(0, 50),
-    used: used.slice(0, 50),
-    mismatches: {
-      undeclared,
-      unused,
-    },
-    confidence: undeclared.length === 0 ? 0.9 : 0.5,
-  };
+/**
+ * D_FAKE_SUCCESS_TOAST_BEFORE_AWAIT (BLOCK/WARN)
+ * Trigger: toast.success before awaited network call
+ */
+function detectFakeSuccessToastBeforeAwait(projectPath) {
+  const findings = [];
+  // This requires AST analysis - see existing findFakeSuccess in analyzers.js
+  // Placeholder for integration
+  return findings;
 }
 
-async function extractSchema(projectPath) {
-  const schemas = [];
+/**
+ * D_FAKE_SUCCESS_RESPONSE_OK_IGNORED (BLOCK)
+ * Trigger: fetch result not checked before success UI
+ */
+function detectFakeSuccessResponseIgnored(projectPath) {
+  const findings = [];
+  // This requires AST analysis
+  return findings;
+}
 
-  try {
-    const prismaPath = path.join(projectPath, "prisma", "schema.prisma");
-    const content = await fs.readFile(prismaPath, "utf8");
-    const modelMatches = content.matchAll(/model\s+(\w+)\s*\{/g);
-    for (const match of modelMatches) {
-      schemas.push({
-        type: "prisma_model",
-        name: match[1],
-        file: "prisma/schema.prisma",
-      });
+/**
+ * D_SILENT_CATCH (WARN→BLOCK)
+ * Trigger: catch (e) {} OR catch { return null } + UI success continues
+ */
+function detectSilentCatch(projectPath) {
+  const findings = [];
+  // This requires AST analysis
+  return findings;
+}
+
+// =============================================================================
+// B5) Dead UI Detectors (runtime-first)
+// =============================================================================
+
+/**
+ * D_DEAD_CLICK_NO_EFFECT (BLOCK/WARN)
+ * Trigger: action click yields no navigation, no DOM change, no network, no console
+ */
+function detectDeadClickNoEffect(realityReport) {
+  const findings = [];
+  const actions = realityReport?.actions || [];
+
+  for (const action of actions) {
+    if (action.type !== "click") continue;
+
+    const noNavigation = action.pageUrl === action.afterPageUrl;
+    const noDomChange = action.beforeDomHash === action.afterDomHash;
+    const noNetwork = !action.networkRequestIds || action.networkRequestIds.length === 0;
+
+    if (noNavigation && noDomChange && noNetwork) {
+      const isCritical = /save|submit|pay|login|continue|checkout/i.test(action.label || "");
+      
+      findings.push(createFindingV2({
+        detectorId: "DEAD_CLICK_NO_EFFECT",
+        severity: isCritical ? "BLOCK" : "WARN",
+        category: "DeadUI",
+        scope: "runtime",
+        title: `Click on "${action.label || action.selector}" has no effect`,
+        why: "Button/link does nothing - no navigation, no DOM change, no network call. User will think app is broken.",
+        confidence: "high",
+        evidence: [
+          createEvidence({
+            kind: "screenshot",
+            reason: "Screenshot before click",
+            artifactPath: action.screenshotBefore,
+          }),
+          createEvidence({
+            kind: "screenshot",
+            reason: "Screenshot after click (unchanged)",
+            artifactPath: action.screenshotAfter,
+          })
+        ].filter(e => e.artifactPath),
+        fixHints: [
+          "Wire click handler to actual functionality",
+          "If disabled, add aria-disabled and disabled styling",
+          "If feature not ready, remove or hide the element"
+        ],
+        repro: {
+          steps: [
+            `Navigate to ${action.pageUrl}`,
+            `Click on element: ${action.selector || action.label}`,
+            "Observe: nothing happens"
+          ],
+          url: action.pageUrl,
+        },
+      }));
     }
-  } catch {
-    // No Prisma schema
   }
 
-  const files = await findSourceFiles(projectPath, [".ts", ".tsx"]);
-  for (const file of files.slice(0, 20)) {
-    try {
-      const content = await fs.readFile(file, "utf8");
-      const relPath = path.relative(projectPath, file);
-
-      const typeMatches = content.matchAll(/(?:interface|type)\s+(\w+)/g);
-      for (const match of typeMatches) {
-        const line = content.substring(0, match.index).split("\n").length;
-        schemas.push({
-          type: "typescript_type",
-          name: match[1],
-          file: relPath,
-          line,
-        });
+  return findings;
+}
+
+/**
+ * D_UI_ACTION_CAUSES_4XX_5XX (BLOCK)
+ * Trigger: click leads to request with 4xx/5xx
+ */
+function detectUIActionCauses4xx5xx(realityReport) {
+  const findings = [];
+  const actions = realityReport?.actions || [];
+  const network = realityReport?.network || [];
+
+  for (const action of actions) {
+    if (!action.networkRequestIds) continue;
+
+    for (const reqId of action.networkRequestIds) {
+      const req = network.find(r => r.id === reqId);
+      if (req && (req.status >= 400 || req.failed)) {
+        findings.push(createFindingV2({
+          detectorId: "UI_ACTION_CAUSES_4XX_5XX",
+          severity: "BLOCK",
+          category: "DeadUI",
+          scope: "runtime",
+          title: `Click on "${action.label || action.selector}" causes ${req.status} error`,
+          why: `UI action triggers failed API call (${req.status}). User will see broken functionality.`,
+          confidence: "high",
+          evidence: [
+            createEvidence({
+              kind: "request",
+              reason: `Failed request triggered by UI action`,
+              url: req.url,
+              httpStatus: req.status,
+              requestId: req.id,
+            })
+          ],
+          fixHints: [
+            "Fix the API endpoint to return success",
+            "Add proper error handling in UI",
+            "If endpoint doesn't exist, create it"
+          ],
+          repro: {
+            steps: [
+              `Navigate to ${action.pageUrl}`,
+              `Click on element: ${action.selector || action.label}`,
+              `Observe: API returns ${req.status}`
+            ],
+            url: action.pageUrl,
+          },
+        }));
       }
-    } catch {
-      // Skip
     }
   }
 
-  return {
-    count: schemas.length,
-    schemas: schemas.slice(0, 50),
-    confidence:
-      schemas.length > 5 ? 0.7 : schemas.length > 0 ? 0.4 : 0.2,
-  };
+  return findings;
 }
 
-// ============================================================================
-// CLAIM VERIFICATION
-// ============================================================================
+// =============================================================================
+// B6) Billing/Stripe Detectors
+// =============================================================================
 
-async function verifyClaim(projectPath, claimType, claim) {
-  const result = {
-    claim: { type: claimType, value: claim },
-    verified: false,
-    evidence: null,
-    confidence: 0,
-    rejection: null,
-  };
+/**
+ * D_STRIPE_WEBHOOK_NO_SIGNATURE_VERIFY (BLOCK)
+ * Trigger: webhook route handler lacks signature verification
+ */
+function detectStripeWebhookNoSigVerify(truthpack) {
+  const findings = [];
+  const webhookRoutes = truthpack.externals?.stripe?.webhookRoutes || [];
+
+  // This requires checking if routes have proper verification
+  // Placeholder - actual implementation would scan the handler files
+  
+  return findings;
+}
 
-  try {
-    switch (claimType) {
-      case "file": {
-        const filePath = path.join(projectPath, claim);
-        try {
-          await fs.access(filePath);
-          const stats = await fs.stat(filePath);
-          result.verified = true;
-          result.confidence = 1.0;
-          result.evidence = {
-            file: claim,
-            exists: true,
-            size: stats.size,
-            verifiedAt: new Date().toISOString(),
-          };
-        } catch {
-          result.rejection = `File does not exist: ${claim}`;
-        }
-        break;
-      }
+// =============================================================================
+// B7) Entitlements Detectors
+// =============================================================================
 
-      case "route":
-      case "endpoint": {
-        const routes = await extractRoutes(projectPath);
-        const matchingRoute = routes.routes.find(
-          (route) => route.path === claim || route.path.includes(claim),
-        );
-        if (matchingRoute) {
-          result.verified = true;
-          result.confidence = 0.9;
-          result.evidence = matchingRoute;
-        } else {
-          result.rejection = `No route matching "${claim}" found in codebase`;
-        }
-        break;
-      }
+/**
+ * D_LOCAL_BYPASS_PAID_FEATURE (BLOCK)
+ * Trigger: code checks env var like OWNER_MODE=true to unlock features
+ */
+function detectLocalBypassPaidFeature(projectPath) {
+  const findings = [];
+  // This requires scanning for patterns like OWNER_MODE, SKIP_AUTH, etc.
+  return findings;
+}
 
-      case "env_var": {
-        const envData = await extractEnvVars(projectPath);
-        const isDeclared = envData.declared.some((env) => env.name === claim);
-        const isUsed = envData.used.some((env) => env.name === claim);
-        if (isDeclared || isUsed) {
-          result.verified = true;
-          result.confidence = isDeclared && isUsed ? 1.0 : 0.7;
-          result.evidence = {
-            declared: isDeclared,
-            used: isUsed,
-            locations: [
-              ...envData.declared.filter((env) => env.name === claim),
-              ...envData.used.filter((env) => env.name === claim),
-            ],
-          };
-        } else {
-          result.rejection = `Environment variable "${claim}" not found`;
-        }
-        break;
-      }
+// =============================================================================
+// B8) Drift Detectors
+// =============================================================================
 
-      default:
-        result.rejection = `Claim type "${claimType}" verification is not implemented yet`;
+/**
+ * D_CONTRACTS_OUT_OF_DATE (WARN/BLOCK)
+ * Trigger: truthpack fingerprint changed but contracts still reflect old fingerprint
+ */
+function detectContractsOutOfDate(truthpack, contracts) {
+  const findings = [];
+  const truthpackFingerprint = truthpack.fingerprint;
+
+  for (const [type, contract] of Object.entries(contracts)) {
+    if (contract.projectFingerprint && contract.projectFingerprint !== truthpackFingerprint) {
+      findings.push(createFindingV2({
+        detectorId: "CONTRACTS_OUT_OF_DATE",
+        severity: type === "routes" || type === "auth" ? "BLOCK" : "WARN",
+        category: "Drift",
+        scope: "contracts",
+        title: `${type} contract out of date (fingerprint mismatch)`,
+        why: `Contract was generated from old codebase. AI agents will use stale information.`,
+        confidence: "high",
+        evidence: [
+          createEvidence({
+            kind: "hash",
+            reason: "Contract fingerprint",
+            file: `.vibecheck/contracts/${type}.json`,
+            lines: "1-1",
+          })
+        ],
+        fixHints: [
+          "Run 'vibecheck ctx sync' to regenerate contracts"
+        ],
+      }));
     }
-  } catch (error) {
-    result.rejection = `Verification error: ${error.message}`;
   }
 
-  return result;
+  return findings;
 }
 
-// ============================================================================
-// EVIDENCE EXTRACTION
-// ============================================================================
+// =============================================================================
+// Helpers
+// =============================================================================
 
-async function getEvidence(projectPath, file, options) {
-  const filePath = path.join(projectPath, file);
-
-  try {
-    const content = await fs.readFile(filePath, "utf8");
-    const lines = content.split("\n");
-
-    let targetLine = options.line || 1;
-    const contextLines = options.context_lines || 10;
-
-    if (options.function_name) {
-      const pattern = new RegExp(
-        `(function|const|let|var|class)\\s+${options.function_name}`,
-        "i",
-      );
-      for (let i = 0; i < lines.length; i++) {
-        if (pattern.test(lines[i])) {
-          targetLine = i + 1;
-          break;
-        }
-      }
+/**
+ * Enhanced route matching with support for:
+ * - Dynamic segments (:id, [id], [slug], [...slug])
+ * - Optional catch-all routes [[...slug]]
+ * - Query string stripping
+ * - Trailing slash normalization
+ */
+function routeMatches(pattern, actual) {
+  // Normalize: strip query strings and trailing slashes
+  const normalizedPattern = pattern.split("?")[0].replace(/\/+$/, "") || "/";
+  const normalizedActual = actual.split("?")[0].replace(/\/+$/, "") || "/";
+  
+  const patternParts = normalizedPattern.split("/").filter(Boolean);
+  const actualParts = normalizedActual.split("/").filter(Boolean);
+
+  // Handle catch-all routes: [...slug] or [[...slug]]
+  const hasCatchAll = patternParts.some(p => 
+    p.startsWith("[...") || p.startsWith("[[...")
+  );
+  
+  if (hasCatchAll) {
+    const catchAllIndex = patternParts.findIndex(p => 
+      p.startsWith("[...") || p.startsWith("[[...")
+    );
+    
+    // For catch-all, pattern up to catch-all must match
+    for (let i = 0; i < catchAllIndex; i++) {
+      const p = patternParts[i];
+      if (isDynamicSegment(p)) continue;
+      if (p !== actualParts[i]) return false;
+    }
+    
+    // Catch-all matches any remaining segments (including none for [[...]])
+    const isOptional = patternParts[catchAllIndex].startsWith("[[...");
+    if (!isOptional && actualParts.length <= catchAllIndex) {
+      return false;
     }
+    
+    return true;
+  }
+
+  // Standard matching: lengths must match
+  if (patternParts.length !== actualParts.length) return false;
 
-    const startLine = Math.max(1, targetLine - contextLines);
-    const endLine = Math.min(lines.length, targetLine + contextLines);
-
-    const snippet = lines
-      .slice(startLine - 1, endLine)
-      .map(
-        (line, index) =>
-          `${String(startLine + index).padStart(4, " ")} | ${line}`,
-      )
-      .join("\n");
-
-    return {
-      file,
-      targetLine,
-      startLine,
-      endLine,
-      totalLines: lines.length,
-      snippet,
-      verifiedAt: new Date().toISOString(),
-    };
-  } catch (error) {
-    return {
-      error: `Cannot read file: ${error.message}`,
-      file,
-    };
+  for (let i = 0; i < patternParts.length; i++) {
+    const p = patternParts[i];
+    if (isDynamicSegment(p)) continue;
+    if (p !== actualParts[i]) return false;
   }
+  return true;
 }
 
-// ============================================================================
-// UTILITIES
-// ============================================================================
-
-async function findSourceFiles(projectPath, extensions) {
-  const files = [];
+/**
+ * Check if a route segment is dynamic
+ */
+function isDynamicSegment(segment) {
+  return segment.startsWith(":") ||    // Express-style :id
+         segment.startsWith("[") ||     // Next.js-style [id]
+         segment === "*" ||             // Wildcard
+         segment.startsWith("$");       // Remix-style $id
+}
 
-  async function walk(dir) {
+/**
+ * Enhanced glob pattern matching with proper escaping
+ */
+function matchPattern(pattern, url) {
+  try {
+    // Normalize URL: extract pathname
+    let pathname;
     try {
-      const entries = await fs.readdir(dir, { withFileTypes: true });
-      for (const entry of entries) {
-        const fullPath = path.join(dir, entry.name);
-        if (entry.isDirectory()) {
-          if (
-            !entry.name.startsWith(".") &&
-            entry.name !== "node_modules" &&
-            entry.name !== "dist" &&
-            entry.name !== "build"
-          ) {
-            await walk(fullPath);
-          }
-        } else if (entry.isFile()) {
-          const ext = path.extname(entry.name).toLowerCase();
-          if (extensions.includes(ext)) {
-            files.push(fullPath);
-          }
-        }
-      }
+      pathname = new URL(url, "http://localhost").pathname;
     } catch {
-      // Skip inaccessible directories
+      pathname = url.split("?")[0];
     }
+    
+    // Escape special regex chars except * and ?
+    const escaped = pattern
+      .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+      .replace(/\*\*/g, "{{GLOBSTAR}}")
+      .replace(/\*/g, "[^/]*")
+      .replace(/\?/g, ".")
+      .replace(/{{GLOBSTAR}}/g, ".*");
+    
+    const regex = new RegExp("^" + escaped + "$");
+    return regex.test(url) || regex.test(pathname);
+  } catch {
+    // Fallback to simple comparison
+    return pattern === url;
   }
+}
 
-  await walk(projectPath);
-  return files;
+/**
+ * Enhanced env var requirement detection
+ * Returns { required: boolean, confidence: 'high' | 'medium' | 'low', reason: string }
+ */
+function isLikelyRequired(name) {
+  // High-confidence required patterns
+  const highConfidenceRequired = [
+    /^DATABASE_URL$/i,
+    /^NEXTAUTH_SECRET$/i,
+    /^NEXTAUTH_URL$/i,
+    /^JWT_SECRET$/i,
+    /^AUTH_SECRET$/i,
+    /^SESSION_SECRET$/i,
+    /^ENCRYPTION_KEY$/i,
+    /^STRIPE_SECRET_KEY$/i,
+    /^STRIPE_WEBHOOK_SECRET$/i,
+    /^OPENAI_API_KEY$/i,
+    /^ANTHROPIC_API_KEY$/i,
+  ];
+  
+  // Medium-confidence required patterns
+  const mediumConfidenceRequired = [
+    /SECRET$/i,
+    /TOKEN$/i,
+    /API_KEY$/i,
+    /PRIVATE_KEY$/i,
+    /PASSWORD$/i,
+    /CREDENTIALS$/i,
+  ];
+  
+  // Patterns that indicate optional env vars
+  const optionalPatterns = [
+    /^DEBUG/i,
+    /^LOG_/i,
+    /^ENABLE_/i,
+    /^DISABLE_/i,
+    /^FEATURE_/i,
+    /^FLAG_/i,
+    /^ANALYTICS/i,
+    /^TELEMETRY/i,
+    /^SENTRY/i,
+    /^PORT$/i,
+    /^HOST$/i,
+    /^NODE_ENV$/i,
+  ];
+  
+  // Check optional first (overrides required)
+  if (optionalPatterns.some(p => p.test(name))) {
+    return false;
+  }
+  
+  // Check high-confidence required
+  if (highConfidenceRequired.some(p => p.test(name))) {
+    return true;
+  }
+  
+  // Check medium-confidence required
+  if (mediumConfidenceRequired.some(p => p.test(name))) {
+    return true;
+  }
+  
+  return false;
+}
+
+/**
+ * Check if an env var usage suggests it's optional
+ */
+function hasOptionalUsagePattern(code) {
+  const optionalPatterns = [
+    /\|\|\s*['"]?undefined['"]?/,      // || undefined
+    /\?\?\s*['"]?undefined['"]?/,      // ?? undefined
+    /\|\|\s*null/,                      // || null
+    /\?\?\s*null/,                      // ?? null
+    /\|\|\s*false/,                     // || false
+    /\?\?\s*false/,                     // ?? false
+    /if\s*\(\s*process\.env\./,         // Conditional usage
+    /process\.env\.\w+\s*\?\s*\./,      // Optional chaining
+  ];
+  
+  return optionalPatterns.some(p => p.test(code));
 }
 
-export default {
-  TRUTH_CONTEXT_TOOLS,
-  handleTruthContextTool,
+// =============================================================================
+// Exports
+// =============================================================================
+
+module.exports = {
+  // Routes
+  detectRouteMissing,
+  detectRouteMethodMismatch,
+  detectRoutePrefixDrift,
+  
+  // Auth
+  detectAuthProtectedAccessibleAnon,
+  detectAuthProtectedBlockedWhenAuthed,
+  detectAuthContractDrift,
+  
+  // Env
+  detectEnvUsedButUndeclared,
+  
+  // Fake Success
+  detectFakeSuccessToastBeforeAwait,
+  detectFakeSuccessResponseIgnored,
+  detectSilentCatch,
+  
+  // Dead UI
+  detectDeadClickNoEffect,
+  detectUIActionCauses4xx5xx,
+  
+  // Billing
+  detectStripeWebhookNoSigVerify,
+  
+  // Entitlements
+  detectLocalBypassPaidFeature,
+  
+  // Drift
+  detectContractsOutOfDate,
+  
+  // Helpers
+  routeMatches,
+  matchPattern,
+  isLikelyRequired,
+  isDynamicSegment,
+  hasOptionalUsagePattern,
 };