@vibecheckai/cli 3.2.0 → 3.2.2

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

@@ -1,860 +1,622 @@
 /**
- * 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_*)
+ * 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
  */
 
-"use strict";
+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}` };
+  }
+}
 
-const fs = require("fs");
-const path = require("path");
-const crypto = require("crypto");
-const { createFindingV2, createEvidence, generateFingerprint } = require("./schema-validator");
+// ============================================================================
+// CONTEXT EXTRACTION
+// ============================================================================
 
-// =============================================================================
-// B1) Routes Detectors
-// =============================================================================
+async function getTruthPack(projectPath, scope) {
+  const truthPack = {
+    version: "1.0.0",
+    generatedAt: new Date().toISOString(),
+    projectPath,
+    scope,
+    confidence: 0,
+    sections: {},
+  };
 
-/**
- * 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"
-        ],
-      }));
+  try {
+    if (scope === "all" || scope === "routes") {
+      truthPack.sections.routes = await extractRoutes(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`
-        ],
-      }));
+    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);
+    }
+    if (scope === "all" || scope === "schema") {
+      truthPack.sections.schema = await extractSchema(projectPath);
     }
-  }
-
-  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++;
+    const sections = Object.values(truthPack.sections);
+    if (sections.length > 0) {
+      truthPack.confidence =
+        sections.reduce((sum, section) => sum + (section.confidence || 0), 0) /
+        sections.length;
     }
-  }
 
-  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"
-      ],
-    }));
+    return truthPack;
+  } catch (error) {
+    return {
+      error: error.message,
+      projectPath,
+      suggestion: "Run `vibecheck init` to set up the project",
+    };
   }
-
-  return findings;
 }
 
-// =============================================================================
-// B2) Auth Coverage Detectors
-// =============================================================================
+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,
+  ];
 
-/**
- * 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,
-          },
-        }));
+  const files = await findSourceFiles(projectPath, [".ts", ".js", ".tsx", ".jsx"]);
+
+  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(),
+            },
+          });
+        }
       }
+    } catch {
+      // Skip unreadable files
     }
   }
 
-  return findings;
+  return {
+    count: routes.length,
+    routes: routes.slice(0, 100),
+    confidence: routes.length > 0 ? 0.8 : 0.2,
+  };
 }
 
-/**
- * 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 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,
+  ];
 
-/**
- * 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"
-        ],
-      }));
-    }
-  }
+  const files = await findSourceFiles(projectPath, [".ts", ".js"]);
 
-  // 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"
-        ],
-      }));
+  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
     }
   }
 
-  return findings;
+  return {
+    count: authIndicators.length,
+    indicators: authIndicators.slice(0, 50),
+    confidence:
+      authIndicators.length > 5
+        ? 0.8
+        : authIndicators.length > 0
+        ? 0.5
+        : 0.1,
+  };
 }
 
-// =============================================================================
-// B3) Env Detectors
-// =============================================================================
+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,
+  ];
 
-/**
- * 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;
+  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);
+
+      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,
+          });
+        }
       }
-      
-      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),
-      }));
+    } catch {
+      // Skip
     }
   }
 
-  return findings;
+  return {
+    count: billingIndicators.length,
+    indicators: billingIndicators.slice(0, 30),
+    confidence:
+      billingIndicators.length > 3
+        ? 0.7
+        : billingIndicators.length > 0
+        ? 0.4
+        : 0.1,
+  };
 }
 
-// =============================================================================
-// B4) Fake Success / Truth Detectors
-// =============================================================================
+async function extractEnvVars(projectPath) {
+  const declared = [];
+  const used = [];
 
-/**
- * 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;
-}
+  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,
+          });
+        }
+      }
+    } catch {
+      // File does not exist
+    }
+  }
 
-/**
- * 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;
-}
+  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
+    }
+  }
 
-/**
- * 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;
+  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,
+  };
 }
 
-// =============================================================================
-// B5) Dead UI Detectors (runtime-first)
-// =============================================================================
+async function extractSchema(projectPath) {
+  const schemas = [];
 
-/**
- * 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,
-        },
-      }));
+  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",
+      });
     }
+  } catch {
+    // No Prisma schema
   }
 
-  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,
-          },
-        }));
+  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,
+        });
       }
+    } catch {
+      // Skip
     }
   }
 
-  return findings;
+  return {
+    count: schemas.length,
+    schemas: schemas.slice(0, 50),
+    confidence:
+      schemas.length > 5 ? 0.7 : schemas.length > 0 ? 0.4 : 0.2,
+  };
 }
 
-// =============================================================================
-// B6) Billing/Stripe Detectors
-// =============================================================================
+// ============================================================================
+// CLAIM VERIFICATION
+// ============================================================================
 
-/**
- * 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;
-}
+async function verifyClaim(projectPath, claimType, claim) {
+  const result = {
+    claim: { type: claimType, value: claim },
+    verified: false,
+    evidence: null,
+    confidence: 0,
+    rejection: null,
+  };
 
-// =============================================================================
-// B7) Entitlements Detectors
-// =============================================================================
+  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;
+      }
 
-/**
- * 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 "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;
+      }
 
-// =============================================================================
-// B8) Drift Detectors
-// =============================================================================
+      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;
+      }
 
-/**
- * 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"
-        ],
-      }));
+      default:
+        result.rejection = `Claim type "${claimType}" verification is not implemented yet`;
     }
+  } catch (error) {
+    result.rejection = `Verification error: ${error.message}`;
   }
 
-  return findings;
+  return result;
 }
 
-// =============================================================================
-// Helpers
-// =============================================================================
+// ============================================================================
+// EVIDENCE EXTRACTION
+// ============================================================================
 
-/**
- * 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;
-  }
+async function getEvidence(projectPath, file, options) {
+  const filePath = path.join(projectPath, file);
 
-  // Standard matching: lengths must match
-  if (patternParts.length !== actualParts.length) return false;
+  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;
+        }
+      }
+    }
 
-  for (let i = 0; i < patternParts.length; i++) {
-    const p = patternParts[i];
-    if (isDynamicSegment(p)) continue;
-    if (p !== actualParts[i]) 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,
+    };
   }
-  return true;
 }
 
-/**
- * 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
-}
+// ============================================================================
+// UTILITIES
+// ============================================================================
 
-/**
- * Enhanced glob pattern matching with proper escaping
- */
-function matchPattern(pattern, url) {
-  try {
-    // Normalize URL: extract pathname
-    let pathname;
+async function findSourceFiles(projectPath, extensions) {
+  const files = [];
+
+  async function walk(dir) {
     try {
-      pathname = new URL(url, "http://localhost").pathname;
+      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);
+          }
+        }
+      }
     } catch {
-      pathname = url.split("?")[0];
+      // Skip inaccessible directories
     }
-    
-    // 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;
   }
-}
 
-/**
- * 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));
+  await walk(projectPath);
+  return files;
 }
 
-// =============================================================================
-// 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,
+export default {
+  TRUTH_CONTEXT_TOOLS,
+  handleTruthContextTool,
 };