@vibecheckai/cli 3.2.0 → 3.2.2

package/mcp-server/truth-firewall-tools.js

@@ -1,25 +1,79 @@
 /**
- * Truth Firewall MCP Tools
+ * Truth Firewall MCP Tools (Enhanced)
+ *
+ * Goals:
+ * - Evidence-first outputs (file/line/snippet + stable hash)
+ * - Policy-aware enforcement (strict/balanced/permissive)
+ * - Project fingerprint invalidates stale claims
+ * - Safe filesystem access (no path traversal)
+ * - Patch verification with allowlist + timeouts
+ * - Faster evidence search (optional ripgrep)
+ */
+
+import fs from "fs/promises";
+import fssync from "fs";
+import path from "path";
+import crypto from "crypto";
+import { execSync, spawnSync } from "child_process";
+import { createRequire } from "module";
+
+// Route Truth v1 integration - AST-based route extraction (Fastify + Next.js)
+const require = createRequire(import.meta.url);
+const { RouteIndex, validateRouteExists: routeTruthValidate, canonicalizePath: routeTruthCanonicalize } = require("../bin/runners/lib/route-truth.js");
+
+// =============================================================================
+// TYPES (JSDoc for IDE support)
+// =============================================================================
+
+/**
+ * @typedef {"strict" | "balanced" | "permissive"} PolicyName
+ * @typedef {"true" | "false" | "unknown"} ClaimResultValue
+ * @typedef {"high" | "medium" | "med" | "low" | number} ConfidenceLabel
  * 
- * The "best-in-world" hallucination stopper toolkit.
- * Agents cannot work without these tools - they enforce truth.
+ * @typedef {Object} EvidenceItem
+ * @property {string} file
+ * @property {number} [line] - start line
+ * @property {string} [lines] - "12-18"
+ * @property {string} [snippet]
+ * @property {string} [hash]
+ * @property {number} [confidence]
  * 
- * Core Tools:
- *   get_truthpack()         - Get the truth pack for this repo
- *   compile_context(task)   - Get task-targeted context
- *   validate_claim(claim)   - Verify a claim has evidence (CRITICAL)
- *   search_evidence(query)  - Find evidence for a claim
- *   find_counterexamples()  - Falsify a claim
- *   propose_patch()         - Create proof-carrying patch
- *   verify_patch()          - Verify a patch meets requirements
- *   check_invariants()      - Check all invariants
+ * @typedef {Object} NormalizedEvidence
+ * @property {string} file
+ * @property {number} line
+ * @property {string} [lines]
+ * @property {string} snippet
+ * @property {string} hash
+ * @property {number} confidence
+ * 
+ * @typedef {Object} EnforcementDecisionAllowed
+ * @property {true} allowed
+ * @property {number} confidence
+ * @property {string} [reason]
+ * 
+ * @typedef {Object} EnforcementDecisionBlocked
+ * @property {false} allowed
+ * @property {number} [confidence]
+ * @property {string} reason
+ * @property {string} [suggestion]
+ * @property {string[]} [blockedActions]
+ * 
+ * @typedef {EnforcementDecisionAllowed | EnforcementDecisionBlocked} EnforcementDecision
+ * 
+ * @typedef {Object} ProjectFingerprint
+ * @property {string} hash
+ * @property {string} commitHash
+ * @property {string[]} fileHashes
+ * @property {string} generatedAt
+ * 
+ * @typedef {Object} ToolResponseMeta
+ * @property {true} ok
+ * @property {string} version
+ * @property {ProjectFingerprint} projectFingerprint
+ * @property {string} attribution
+ * @property {string} generatedAt
  */
 
-import fs from 'fs/promises';
-import path from 'path';
-import crypto from 'crypto';
-import { execSync } from 'child_process';
-
 // =============================================================================
 // TOOL DEFINITIONS
 // =============================================================================
@@ -27,42 +81,36 @@ import { execSync } from 'child_process';
 export const TRUTH_FIREWALL_TOOLS = [
   {
     name: "vibecheck.get_truthpack",
-    description: `📦 Get the Truth Pack — the verified ground truth about this codebase.
+    description: `📦 Get the Truth Pack — verified ground truth about this codebase.
 
 Returns evidence-backed facts about routes, auth, billing, env vars, and schema.
-Every claim has file/line citations and confidence scores.
+Every claim should point to files/lines with confidence scores.
 
-⚠️ CRITICAL: Use this BEFORE making any assertions about the codebase.`,
+Use this BEFORE making assertions about the repo.`,
     inputSchema: {
       type: "object",
       properties: {
         scope: {
           type: "string",
           enum: ["all", "routes", "auth", "billing", "env", "schema", "graph"],
-          description: "What to include (default: all)",
           default: "all",
         },
-        refresh: {
-          type: "boolean",
-          description: "Force recompile even if cached (default: false)",
-          default: false,
-        },
+        refresh: { type: "boolean", default: false },
       },
     },
   },
-  
+
   {
     name: "vibecheck.validate_claim",
     description: `🔍 TRUTH FIREWALL — Validate a claim before acting on it.
 
-Returns: true | false | unknown
-- If 'unknown': you MUST NOT proceed with actions that depend on this claim
-- If 'false': the claim is disproven, do not proceed
-- If 'true': proceed with evidence citations
+Returns: true | false | unknown + enforcement decision
+Policy matters:
+- strict/balanced: unknown blocks dependent actions
+- permissive: unknown allowed (but flagged)
 
 Examples:
   { "claim": "route_exists", "subject": { "method": "POST", "path": "/api/login" } }
-  { "claim": "auth_enforced", "subject": { "path": "/dashboard" } }
   { "claim": "env_var_exists", "subject": { "name": "STRIPE_SECRET_KEY" } }`,
     inputSchema: {
       type: "object",
@@ -71,7 +119,7 @@ Examples:
           type: "string",
           enum: [
             "route_exists",
-            "route_guarded", 
+            "route_guarded",
             "env_var_exists",
             "env_var_used",
             "middleware_applied",
@@ -82,405 +130,358 @@ Examples:
             "model_exists",
             "component_exists",
           ],
-          description: "Type of claim to verify",
         },
         subject: {
           type: "object",
-          description: "What the claim is about",
           properties: {
-            method: { type: "string", description: "HTTP method (for routes)" },
-            path: { type: "string", description: "Route path or file path" },
-            name: { type: "string", description: "Name of function/component/env var" },
+            method: { type: "string" },
+            path: { type: "string" },
+            name: { type: "string" },
           },
         },
-        expected: {
+        expected: { type: "boolean", default: true },
+        policy: {
+          type: "string",
+          enum: ["strict", "balanced", "permissive"],
+          default: "strict",
+        },
+        refresh: {
           type: "boolean",
-          description: "Expected result (default: true)",
-          default: true,
+          default: false,
+          description: "Force refresh of underlying truthpack/contracts before verifying",
         },
       },
       required: ["claim", "subject"],
     },
   },
-  
+
   {
     name: "vibecheck.compile_context",
-    description: `🎯 Get task-targeted context — minimal sufficient context for your task.
+    description: `🎯 Get minimal sufficient context for a task (not a token bomb).
 
-Big context = noise. Small context = missing facts.
-This compiles exactly what you need for the task.
-
-Returns relevant nodes, edges, evidence, and applicable invariants.`,
+Returns relevant nodes, edges, evidence, and invariants.`,
     inputSchema: {
       type: "object",
       properties: {
-        task: {
-          type: "string",
-          description: "What you're trying to do (e.g., 'fix dead login button', 'add Stripe checkout')",
-        },
-        files: {
-          type: "array",
-          items: { type: "string" },
-          description: "Specific files to include",
-        },
-        policy: {
-          type: "string",
-          enum: ["strict", "balanced", "permissive"],
-          description: "How strict to be about context (default: balanced)",
-          default: "balanced",
-        },
+        task: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+        policy: { type: "string", enum: ["strict", "balanced", "permissive"], default: "balanced" },
+        maxItems: { type: "number", default: 50 },
       },
       required: ["task"],
     },
   },
-  
+
   {
     name: "vibecheck.search_evidence",
     description: `📎 Search for evidence in the codebase.
 
-Returns code snippets with file/line citations.
-Use this to find proof for claims.`,
+Supports text mode or regex mode. Returns file/line/snippet + hashes.`,
     inputSchema: {
       type: "object",
       properties: {
-        query: {
-          type: "string",
-          description: "What to search for (e.g., 'login handler', 'auth middleware', 'Stripe webhook')",
-        },
-        type: {
-          type: "string",
-          enum: ["route", "handler", "middleware", "component", "env_var", "model", "any"],
-          description: "Type of evidence to find (default: any)",
-          default: "any",
-        },
-        limit: {
-          type: "number",
-          description: "Max results (default: 10)",
-          default: 10,
-        },
+        query: { type: "string" },
+        mode: { type: "string", enum: ["text", "regex"], default: "text" },
+        type: { type: "string", enum: ["route", "handler", "middleware", "component", "env_var", "model", "any"], default: "any" },
+        limit: { type: "number", default: 10 },
+        caseSensitive: { type: "boolean", default: false },
+        includeTests: { type: "boolean", default: false },
       },
       required: ["query"],
     },
   },
-  
+
   {
     name: "vibecheck.find_counterexamples",
-    description: `🔴 Find counterexamples that would disprove a claim.
-
-This is the FALSIFICATION mechanism.
-If counterexamples exist, the claim becomes false or low confidence.
+    description: `🔴 FALSIFICATION — find counterexamples that disprove a claim.
 
-Use this for high-stakes claims about auth, billing, security.`,
+Use for auth, billing, security.`,
     inputSchema: {
       type: "object",
       properties: {
-        claim: {
-          type: "string",
-          enum: ["auth_enforced", "billing_gate_exists", "route_guarded", "no_bypass"],
-          description: "Claim to falsify",
-        },
+        claim: { type: "string", enum: ["auth_enforced", "billing_gate_exists", "route_guarded", "no_bypass"] },
         subject: {
           type: "object",
-          description: "What the claim is about",
-          properties: {
-            path: { type: "string" },
-            name: { type: "string" },
-          },
+          properties: { path: { type: "string" }, name: { type: "string" } },
         },
+        policy: { type: "string", enum: ["strict", "balanced", "permissive"], default: "strict" },
       },
       required: ["claim", "subject"],
     },
   },
-  
+
   {
     name: "vibecheck.propose_patch",
     description: `📝 Propose a proof-carrying patch.
 
-When proposing changes, you MUST attach:
-- Which findings it fixes
-- Which claims it depends on (must be verified)
-- Evidence references
-- Verification commands
+Patches must attach:
+- findings fixed
+- claim dependencies (validated)
+- verification commands
 
 Patches without proof are NOT eligible for auto-apply.`,
     inputSchema: {
       type: "object",
       properties: {
-        diff: {
-          type: "string",
-          description: "The diff content",
-        },
-        fixes: {
-          type: "array",
-          items: { type: "string" },
-          description: "Finding IDs this patch fixes",
-        },
-        claims: {
-          type: "array",
-          items: { type: "string" },
-          description: "Claim IDs this patch depends on (must all be verified)",
-        },
-        verification: {
-          type: "array",
-          items: { type: "string" },
-          description: "Commands to verify the patch (e.g., 'vibecheck ship', 'pnpm test')",
-        },
+        diff: { type: "string" },
+        fixes: { type: "array", items: { type: "string" } },
+        claims: { type: "array", items: { type: "string" } },
+        verification: { type: "array", items: { type: "string" } },
+        policy: { type: "string", enum: ["strict", "balanced", "permissive"], default: "strict" },
+        save: { type: "boolean", default: true },
       },
       required: ["diff", "fixes"],
     },
   },
-  
+
   {
-    name: "vibecheck.check_invariants",
-    description: `⚖️ Check all invariants (product religion rules).
+    name: "vibecheck.verify_patch",
+    description: `✅ Verify a patch meets requirements.
+
+Runs verification commands with allowlist + timeouts.
+Returns pass/fail and command output (truncated).`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        patchId: { type: "string", description: "Patch ID from propose_patch (optional)" },
+        diff: { type: "string", description: "If no patchId, provide diff text (not auto-applied)" },
+        commands: { type: "array", items: { type: "string" }, description: "Commands to run" },
+        policy: { type: "string", enum: ["strict", "balanced", "permissive"], default: "strict" },
+        timeoutMs: { type: "number", default: 120000 },
+      },
+      required: ["commands"],
+    },
+  },
 
-Returns:
-- Ship killers: BLOCK deployment
-- Warnings: Require acknowledgment
+  {
+    name: "vibecheck.check_invariants",
+    description: `⚖️ Check invariants (ship-killer rules).
 
-Invariants include:
-- No paid feature without server-side enforcement
+Examples:
+- No paid feature without server enforcement
 - No success UI without confirmed success
-- No route reference without matching route map entry
-- No silent catch in auth/billing flows`,
+- No silent catch in auth/billing`,
     inputSchema: {
       type: "object",
       properties: {
-        category: {
-          type: "string",
-          enum: ["all", "auth", "billing", "security", "ux", "api"],
-          description: "Category to check (default: all)",
-          default: "all",
-        },
+        category: { type: "string", enum: ["all", "auth", "billing", "security", "ux", "api"], default: "all" },
+        policy: { type: "string", enum: ["strict", "balanced", "permissive"], default: "strict" },
       },
     },
   },
-  
+
   {
     name: "vibecheck.add_assumption",
-    description: `⚠️ Log an assumption (with budget enforcement).
-
-Assumptions stack up and cause failures. Track them explicitly.
-
-Rules:
-- Max 2 assumptions per mission
-- Must provide verification steps
-- If budget exceeded, you MUST use proof tooling instead`,
+    description: `⚠️ Log an assumption (budget enforced).`,
     inputSchema: {
       type: "object",
       properties: {
-        description: {
-          type: "string",
-          description: "What you're assuming",
-        },
-        reason: {
-          type: "string",
-          description: "Why you need this assumption",
-        },
-        verificationSteps: {
-          type: "array",
-          items: { type: "string" },
-          description: "How to verify this assumption later",
-        },
+        description: { type: "string" },
+        reason: { type: "string" },
+        verificationSteps: { type: "array", items: { type: "string" } },
       },
       required: ["description", "verificationSteps"],
     },
   },
-  
+
   {
     name: "vibecheck.validate_plan",
-    description: `🛡️ HALLUCINATION STOPPER — Validate an AI plan against contracts.
-
-Before executing a plan, you MUST validate it against contracts.
-Rejects plans that:
-- Reference routes not in routes.json
-- Use env vars not in env.json  
-- Make auth assumptions that contradict auth.json
-- Reference external services not in external.json
-
-⚠️ CRITICAL: If validation fails, you MUST NOT proceed with the plan.
-
-Example:
-  { "plan": "Create POST /api/checkout endpoint using STRIPE_SECRET_KEY" }
+    description: `🛡️ Validate an AI plan against contracts (routes/env/auth/external).
 
-Returns: { valid: boolean, violations: [], warnings: [], suggestions: [] }`,
+If validation fails: do NOT proceed.`,
     inputSchema: {
       type: "object",
       properties: {
-        plan: {
-          type: "string",
-          description: "The plan text or JSON to validate",
-        },
-        strict: {
-          type: "boolean",
-          description: "If true, warnings also cause rejection (default: false)",
-          default: false,
-        },
+        plan: { type: "string" },
+        strict: { type: "boolean", default: false },
       },
       required: ["plan"],
     },
   },
-  
+
   {
     name: "vibecheck.check_drift",
-    description: `📊 Check for contract drift — detect when code has changed but contracts are stale.
-
-Returns drift findings for:
-- Routes added/removed but not in contract
-- Env vars used but not declared
-- Auth patterns changed
-- External services added
-
-Per spec: routes/env/auth drift → BLOCK (AI will lie about these)`,
+    description: `📊 Detect contract drift (routes/env/auth/external).`,
     inputSchema: {
       type: "object",
       properties: {
-        category: {
-          type: "string",
-          enum: ["all", "routes", "env", "auth", "external"],
-          description: "Category to check (default: all)",
-          default: "all",
-        },
+        category: { type: "string", enum: ["all", "routes", "env", "auth", "external"], default: "all" },
       },
     },
   },
-  
+
   {
     name: "vibecheck.get_contracts",
-    description: `📜 Get the current contracts (routes/env/auth/external).
-
-Contracts are the "you may not lie" rules for this repo.
-AI output must satisfy these contracts.
-
-Returns the contract files from .vibecheck/contracts/`,
+    description: `📜 Get contracts from .vibecheck/contracts/`,
     inputSchema: {
       type: "object",
       properties: {
-        type: {
-          type: "string",
-          enum: ["all", "routes", "env", "auth", "external"],
-          description: "Which contract to get (default: all)",
-          default: "all",
-        },
+        type: { type: "string", enum: ["all", "routes", "env", "auth", "external"], default: "all" },
       },
     },
   },
 ];
 
 // =============================================================================
-// TOOL HANDLERS
+// TOOL HANDLER
 // =============================================================================
 
 export async function handleTruthFirewallTool(toolName, args, projectPath = process.cwd()) {
   switch (toolName) {
     case "vibecheck.get_truthpack":
-      return await getTruthPack(projectPath, args);
-      
+      return wrapMcpResponse(await getTruthPack(projectPath, args), projectPath);
+
     case "vibecheck.validate_claim":
-      return await validateClaim(projectPath, args);
-      
+      return wrapMcpResponse(await validateClaim(projectPath, args), projectPath);
+
     case "vibecheck.compile_context":
-      return await compileContext(projectPath, args);
-      
+      return wrapMcpResponse(await compileContext(projectPath, args), projectPath);
+
     case "vibecheck.search_evidence":
-      return await searchEvidence(projectPath, args);
-      
+      return wrapMcpResponse(await searchEvidence(projectPath, args), projectPath);
+
     case "vibecheck.find_counterexamples":
-      return await findCounterexamples(projectPath, args);
-      
+      return wrapMcpResponse(await findCounterexamples(projectPath, args), projectPath);
+
     case "vibecheck.propose_patch":
-      return await proposePatch(projectPath, args);
-      
+      return wrapMcpResponse(await proposePatch(projectPath, args), projectPath);
+
+    case "vibecheck.verify_patch":
+      return wrapMcpResponse(await verifyPatch(projectPath, args), projectPath);
+
     case "vibecheck.check_invariants":
-      return await checkInvariants(projectPath, args);
-      
+      return wrapMcpResponse(await checkInvariants(projectPath, args), projectPath);
+
     case "vibecheck.add_assumption":
-      return await addAssumption(projectPath, args);
-      
+      return wrapMcpResponse(await addAssumption(projectPath, args), projectPath);
+
     case "vibecheck.validate_plan":
-      return await getPlanValidationResult(projectPath, args);
-      
+      return wrapMcpResponse(await getPlanValidationResult(projectPath, args), projectPath);
+
     case "vibecheck.check_drift":
-      return await checkDriftTool(projectPath, args);
-      
+      return wrapMcpResponse(await checkDriftTool(projectPath, args), projectPath);
+
     case "vibecheck.get_contracts":
-      return await getContractsTool(projectPath, args);
-      
+      return wrapMcpResponse(await getContractsTool(projectPath, args), projectPath);
+
     default:
-      return { error: `Unknown tool: ${toolName}` };
+      return wrapMcpResponse({ error: `Unknown tool: ${toolName}` }, projectPath);
   }
 }
 
 // =============================================================================
-// IMPLEMENTATION
+// STATE (Per-project aware)
 // =============================================================================
 
-// In-memory state
+/**
+ * @typedef {Object} CachedClaim
+ * @property {string} projectHash
+ * @property {number} timestamp
+ * @property {*} result
+ */
+
 const state = {
-  truthPack: null,
-  assumptions: [],
+  truthPackByProject: new Map(),
+  assumptionsByProject: new Map(),
   verifiedClaims: new Map(),
-  maxAssumptions: 2,
   lastValidationByProject: new Map(),
+  routeIndexByProject: new Map(), // Route Truth v1 index cache
+  maxAssumptions: 2,
 };
 
-const MAX_EVIDENCE_SNIPPET = 200;
+const MAX_EVIDENCE_SNIPPET = 240;
+const MAX_CMD_OUTPUT = 12_000;
+
+// =============================================================================
+// POLICY CONFIG
+// =============================================================================
 
-/**
- * Policy configuration - aligned with proof-context.js TRUTH_CONTRACT
- */
 const POLICY_CONFIG = {
   strict: {
     minConfidence: 0.8,
     allowUnknown: false,
     requireValidation: true,
     blockOnDrift: true,
-    validationTTL: 5 * 60 * 1000, // 5 minutes
+    validationTTL: 5 * 60 * 1000,
   },
   balanced: {
     minConfidence: 0.6,
     allowUnknown: false,
     requireValidation: true,
     blockOnDrift: false,
-    validationTTL: 10 * 60 * 1000, // 10 minutes
+    validationTTL: 10 * 60 * 1000,
   },
   permissive: {
     minConfidence: 0.4,
     allowUnknown: true,
     requireValidation: false,
     blockOnDrift: false,
-    validationTTL: 30 * 60 * 1000, // 30 minutes
+    validationTTL: 30 * 60 * 1000,
   },
 };
 
-/**
- * Get policy configuration
- */
-export function getPolicyConfig(policy = 'strict') {
+export function getPolicyConfig(policy = "strict") {
   return POLICY_CONFIG[policy] || POLICY_CONFIG.strict;
 }
 
 function confidenceToScore(confidence) {
   if (typeof confidence === "number") return confidence;
   switch (confidence) {
-    case "high":
-      return 0.9;
+    case "high": return 0.9;
     case "medium":
-      return 0.7;
-    case "low":
-      return 0.5;
-    default:
-      return 0.6;
+    case "med": return 0.7;
+    case "low": return 0.5;
+    default: return 0.6;
+  }
+}
+
+// =============================================================================
+// SAFETY: PROJECT-ROOT SANDBOX
+// =============================================================================
+
+function safeProjectJoin(projectPath, rel) {
+  const root = path.resolve(projectPath);
+  const abs = path.resolve(root, rel);
+  if (!abs.startsWith(root + path.sep) && abs !== root) {
+    throw new Error(`Refusing to access path outside project root: ${rel}`);
   }
+  return abs;
+}
+
+async function safeReadFile(projectPath, rel) {
+  const abs = safeProjectJoin(projectPath, rel);
+  return await fs.readFile(abs, "utf8");
+}
+
+// =============================================================================
+// EVIDENCE NORMALIZATION
+// =============================================================================
+
+function sha16(s) {
+  return crypto.createHash("sha256").update(s).digest("hex").slice(0, 16);
+}
+
+function parseLineRange(lines) {
+  if (typeof lines === "number") return { start: Math.max(1, lines), end: Math.max(1, lines) };
+  if (!lines) return { start: 1, end: 1 };
+  const s = String(lines).trim();
+  const m = s.match(/^(\d+)(?:\s*-\s*(\d+))?$/);
+  if (!m) return { start: 1, end: 1 };
+  const a = Number(m[1]);
+  const b = m[2] ? Number(m[2]) : a;
+  return { start: Math.max(1, a), end: Math.max(1, b) };
 }
 
-async function readSnippet(projectPath, file, line) {
+async function readSnippet(projectPath, file, lines) {
   if (!file) return "";
   try {
-    const content = await fs.readFile(path.join(projectPath, file), "utf8");
-    const lines = content.split("\n");
-    const idx = Math.max(0, Math.min(lines.length - 1, line - 1));
-    return (lines[idx] || "").slice(0, MAX_EVIDENCE_SNIPPET);
+    const content = await safeReadFile(projectPath, file);
+    const arr = content.split(/\r?\n/);
+    const { start, end } = parseLineRange(lines);
+    const s = Math.max(1, Math.min(arr.length, start));
+    const e = Math.max(s, Math.min(arr.length, end));
+    const snippet = arr.slice(s - 1, e).join("\n");
+    return snippet.slice(0, MAX_EVIDENCE_SNIPPET);
   } catch {
     return "";
   }
@@ -488,91 +489,180 @@ async function readSnippet(projectPath, file, line) {
 
 async function normalizeEvidence(projectPath, evidence, fallback, confidence) {
   const raw = Array.isArray(evidence) ? evidence : evidence ? [evidence] : [];
-  const normalized = [];
+  const out = [];
 
   for (const item of raw) {
     const file = item?.file || fallback?.file || "";
-    const line = Number(item?.line || item?.lines || fallback?.line || 1);
-    const snippet =
-      item?.snippet ||
-      item?.evidence ||
-      (await readSnippet(projectPath, file, line));
+    const rangeStr = item?.lines ?? item?.line ?? fallback?.line ?? 1;
+    const { start, end } = parseLineRange(rangeStr);
+    const snippet = (item?.snippet || (await readSnippet(projectPath, file, `${start}-${end}`)) || "").slice(0, MAX_EVIDENCE_SNIPPET);
+    const hash = item?.hash || sha16(`${file}:${start}:${snippet}`);
 
-    normalized.push({
+    out.push({
       file,
-      line,
+      line: start,
+      lines: end !== start ? `${start}-${end}` : `${start}`,
       snippet,
+      hash,
       confidence: item?.confidence ?? confidenceToScore(confidence),
     });
   }
 
-  if (normalized.length === 0 && fallback?.file) {
-    normalized.push({
-      file: fallback.file,
-      line: fallback.line || 1,
-      snippet: await readSnippet(projectPath, fallback.file, fallback.line || 1),
+  if (out.length === 0 && fallback?.file) {
+    const file = fallback.file;
+    const line = fallback.line || 1;
+    const snippet = await readSnippet(projectPath, file, line);
+    out.push({
+      file,
+      line,
+      lines: `${line}`,
+      snippet,
+      hash: sha16(`${file}:${line}:${snippet}`),
       confidence: confidenceToScore(confidence),
     });
   }
 
-  return normalized;
+  return out;
 }
 
-/**
- * Check if there's a recent claim validation for the project.
- * The TTL depends on the policy mode.
- */
-export function hasRecentClaimValidation(projectPath, policy = 'strict') {
-  const last = state.lastValidationByProject.get(projectPath);
-  if (typeof last !== "number") return false;
-  
-  const config = getPolicyConfig(policy);
-  const maxAgeMs = config.validationTTL;
-  return Date.now() - last <= maxAgeMs;
-}
+// =============================================================================
+// POLICY ENFORCEMENT (FIXED)
+// =============================================================================
 
 /**
- * Validate a claim result against policy thresholds.
- * Returns an enforcement decision.
+ * Correct confidence derivation (your original had precedence issues).
  */
-export function enforceClaimResult(result, policy = 'strict') {
+export function enforceClaimResult(result, policy = "strict") {
   const config = getPolicyConfig(policy);
-  const confidence = confidenceToScore(result.confidence || result.result === 'true' ? 0.9 : 0.3);
-  
-  // Unknown results
-  if (result.result === 'unknown') {
-    if (!config.allowUnknown) {
-      return {
-        allowed: false,
-        reason: `Unknown claims are not allowed in ${policy} mode`,
-        suggestion: 'Use search_evidence to find proof or get_truthpack to refresh context',
-      };
-    }
+
+  const derived =
+    result?.confidence !== undefined
+      ? confidenceToScore(result.confidence)
+      : (result?.result === "true" ? 0.9 : result?.result === "false" ? 0.9 : 0.3);
+
+  if (result.result === "unknown" && !config.allowUnknown) {
+    return {
+      allowed: false,
+      confidence: derived,
+      reason: `Unknown claims are not allowed in ${policy} mode`,
+      suggestion: "Use search_evidence / get_truthpack / refresh=true to gather proof.",
+      blockedActions: ["fix", "autopilot_apply", "propose_patch"],
+    };
+  }
+
+  if (derived < config.minConfidence) {
+    return {
+      allowed: false,
+      confidence: derived,
+      reason: `Confidence ${(derived * 100).toFixed(0)}% below ${policy} threshold ${(config.minConfidence * 100).toFixed(0)}%`,
+      suggestion: "Find more evidence or lower strictness (permissive policy).",
+    };
   }
-  
-  // Low confidence
-  if (confidence < config.minConfidence) {
+
+  if (result.result === "false") {
     return {
       allowed: false,
-      reason: `Confidence ${(confidence * 100).toFixed(0)}% below ${policy} threshold ${(config.minConfidence * 100).toFixed(0)}%`,
-      suggestion: 'Find additional evidence or use permissive policy',
+      confidence: derived,
+      reason: "Claim is disproven. Do not proceed with dependent actions.",
     };
   }
-  
-  return { allowed: true };
+
+  return { allowed: true, confidence: derived };
+}
+
+/**
+ * Claim validation freshness per policy TTL.
+ */
+export function hasRecentClaimValidation(projectPath, policy = "strict") {
+  const last = state.lastValidationByProject.get(projectPath);
+  if (typeof last !== "number") return false;
+  const ttl = getPolicyConfig(policy).validationTTL;
+  return Date.now() - last <= ttl;
+}
+
+// =============================================================================
+// FINGERPRINT + WRAPPER
+// =============================================================================
+
+function getCommitHash(projectPath) {
+  try {
+    return execSync("git rev-parse HEAD", { cwd: projectPath, encoding: "utf8" }).trim();
+  } catch {
+    return "unknown";
+  }
+}
+
+export function getProjectFingerprint(projectPath) {
+  const commitHash = getCommitHash(projectPath);
+  const keyFiles = [
+    "package.json",
+    "pnpm-lock.yaml",
+    "package-lock.json",
+    "yarn.lock",
+    "prisma/schema.prisma",
+    "next.config.js",
+    "next.config.ts",
+    ".vibecheck/contracts/routes.json",
+    ".vibecheck/contracts/env.json",
+    ".vibecheck/contracts/auth.json",
+    ".vibecheck/contracts/external.json",
+  ];
+
+  const fileHashes = [];
+  for (const rel of keyFiles) {
+    try {
+      const abs = safeProjectJoin(projectPath, rel);
+      if (!fssync.existsSync(abs)) continue;
+      const content = fssync.readFileSync(abs, "utf8");
+      fileHashes.push(`${rel}:${sha16(content)}`);
+    } catch { /* ignore */ }
+  }
+
+  const material = [commitHash, ...fileHashes].join("|");
+  return {
+    hash: sha16(material),
+    commitHash,
+    fileHashes,
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+const CONTEXT_ATTRIBUTION = "🧠 Context enhanced by vibecheck";
+
+export function getContextAttribution() {
+  return CONTEXT_ATTRIBUTION;
+}
+
+export function wrapMcpResponse(data, projectPath) {
+  return {
+    ok: true,
+    version: "2.1.0",
+    projectFingerprint: getProjectFingerprint(projectPath),
+    attribution: CONTEXT_ATTRIBUTION,
+    generatedAt: new Date().toISOString(),
+    data,
+  };
 }
 
+// =============================================================================
+// IMPLEMENTATION: TRUTHPACK
+// =============================================================================
+
 async function getTruthPack(projectPath, args) {
-  const scope = args.scope || 'all';
-  const refresh = args.refresh || false;
-  
-  if (state.truthPack && !refresh) {
-    return filterTruthPack(state.truthPack, scope);
+  const scope = args?.scope || "all";
+  const refresh = Boolean(args?.refresh);
+
+  if (refresh) {
+    // Also clear route index on refresh
+    state.routeIndexByProject.delete(projectPath);
+  }
+
+  if (!refresh && state.truthPackByProject.has(projectPath)) {
+    return filterTruthPack(state.truthPackByProject.get(projectPath), scope);
   }
-  
-  // Build truth pack
+
   const truthPack = {
-    version: '1.0.0',
+    version: "2.0.0", // v2 with Route Truth v1 integration
     generatedAt: new Date().toISOString(),
     projectPath,
     commitHash: getCommitHash(projectPath),
@@ -580,378 +670,603 @@ async function getTruthPack(projectPath, args) {
     confidence: 0,
     _attribution: CONTEXT_ATTRIBUTION,
   };
-  
-  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 extractEnv(projectPath);
-  }
-  if (scope === 'all' || scope === 'schema') {
-    truthPack.sections.schema = await extractSchema(projectPath);
-  }
-  if (scope === 'all' || scope === 'graph') {
-    truthPack.sections.graph = await extractGraph(projectPath);
-  }
-  
-  // Calculate confidence
+
+  if (scope === "all" || scope === "routes") truthPack.sections.routes = await extractRoutes(projectPath, refresh);
+  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 extractEnv(projectPath);
+  if (scope === "all" || scope === "schema") truthPack.sections.schema = await extractSchema(projectPath);
+  if (scope === "all" || scope === "graph") truthPack.sections.graph = await extractGraph(projectPath);
+
   const sections = Object.values(truthPack.sections);
-  truthPack.confidence = sections.reduce((sum, s) => sum + (s.confidence || 0), 0) / sections.length;
-  
-  state.truthPack = truthPack;
+  truthPack.confidence = sections.length
+    ? sections.reduce((sum, s) => sum + (s?.confidence || 0), 0) / sections.length
+    : 0.4;
+
+  state.truthPackByProject.set(projectPath, truthPack);
   return truthPack;
 }
 
+function filterTruthPack(pack, scope) {
+  if (scope === "all") return pack;
+  return { ...pack, sections: { [scope]: pack.sections?.[scope] } };
+}
+
+// =============================================================================
+// IMPLEMENTATION: validate_claim (policy-aware + fingerprint cache)
+// =============================================================================
+
 async function validateClaim(projectPath, args) {
-  const { claim, subject, expected = true } = args;
-  const claimId = `claim_${crypto.createHash('sha256').update(JSON.stringify({ claim, subject })).digest('hex').slice(0, 12)}`;
-  
-  // Check cache
-  if (state.verifiedClaims.has(claimId)) {
-    const cached = state.verifiedClaims.get(claimId);
-    if (Date.now() - cached.timestamp < 5 * 60 * 1000) {
-      return { ...cached.result, cached: true };
+  const { claim, subject, expected = true, policy = "strict", refresh = false } = args || {};
+  const pol = policy || "strict";
+
+  if (refresh) {
+    // force refresh truthpack + route index for this project
+    state.truthPackByProject.delete(projectPath);
+    state.routeIndexByProject.delete(projectPath);
+  }
+
+  const fingerprint = getProjectFingerprint(projectPath);
+  const claimKey = { claim, subject, expected };
+  const claimId = `claim_${sha16(JSON.stringify(claimKey))}`;
+
+  // policy TTL cache + fingerprint invalidation
+  const cached = state.verifiedClaims.get(claimId);
+  if (cached && cached.projectHash === fingerprint.hash) {
+    const ttl = getPolicyConfig(pol).validationTTL;
+    if (Date.now() - cached.timestamp <= ttl) {
+      return { claimId, ...cached.result, cached: true };
     }
   }
-  
-  let result = { result: 'unknown', confidence: 'low', evidence: [], nextSteps: [] };
-  
+
+  let result = { result: "unknown", confidence: "low", evidence: [], nextSteps: [] };
+
   try {
     switch (claim) {
-      case 'route_exists':
-        result = await verifyRouteExists(projectPath, subject);
+      case "route_exists":
+        result = await verifyRouteExists(projectPath, subject, refresh);
         break;
-      case 'file_exists':
+
+      case "file_exists":
         result = await verifyFileExists(projectPath, subject);
         break;
-      case 'env_var_exists':
-      case 'env_var_used':
+
+      case "env_var_exists":
+      case "env_var_used":
         result = await verifyEnvVar(projectPath, subject, claim);
         break;
-      case 'auth_enforced':
-      case 'route_guarded':
+
+      case "auth_enforced":
+      case "route_guarded":
         result = await verifyRouteGuarded(projectPath, subject);
         break;
-      case 'function_exists':
-      case 'component_exists':
-      case 'model_exists':
+
+      case "function_exists":
+      case "component_exists":
+      case "model_exists":
         result = await verifyEntityExists(projectPath, subject, claim);
         break;
+
       default:
-        result.nextSteps = [`Claim type "${claim}" not yet implemented. Use search_evidence instead.`];
+        result = {
+          result: "unknown",
+          confidence: "low",
+          evidence: [],
+          nextSteps: [`Claim type "${claim}" not implemented. Use search_evidence.`],
+        };
+        break;
     }
   } catch (error) {
-    result.nextSteps = [`Verification error: ${error.message}`];
-  }
-  
-  // ENFORCED: Unknown claims must return explicit "unknown" error 
-  // that blocks dependent actions in strict/balanced modes
-  if (result.result === 'unknown') {
-    result.nextSteps.push(
-      'call vibecheck.search_evidence to find related code',
-      'call vibecheck.get_truthpack to get full context',
-    );
-    result.warning = '⚠️ UNKNOWN claims BLOCK dependent actions. Verify before proceeding.';
-    result.enforcement = {
-      allowed: false,
-      reason: 'Claim result is unknown - cannot proceed without evidence',
-      blockedActions: ['fix', 'autopilot_apply', 'propose_patch'],
-    };
-  } else if (result.result === 'true') {
-    result.enforcement = {
-      allowed: true,
-      confidence: confidenceToScore(result.confidence),
-    };
-  } else {
-    // result is 'false'
-    result.enforcement = {
-      allowed: false,
-      reason: 'Claim is disproven - do not proceed with dependent actions',
+    result = {
+      result: "unknown",
+      confidence: "low",
+      evidence: [],
+      nextSteps: [`Verification error: ${error?.message || String(error)}`],
     };
   }
-  
-  // Cache result
-  state.verifiedClaims.set(claimId, { result, timestamp: Date.now(), projectPath });
-  state.lastValidationByProject.set(projectPath, Date.now());
-  
-  return {
+
+  // normalize evidence consistently
+  const normalized = await normalizeEvidence(
+    projectPath,
+    result.evidence,
+    { file: subject?.path || subject?.name, line: 1 },
+    result.confidence
+  );
+
+  // enforcement (policy-driven)
+  const enforcement = enforceClaimResult({ result: result.result, confidence: result.confidence }, pol);
+
+  // guidance
+  const nextSteps = Array.isArray(result.nextSteps) ? result.nextSteps : [];
+  if (result.result === "unknown") {
+    nextSteps.push("call vibecheck.search_evidence for proof", "call vibecheck.get_truthpack refresh=true");
+  }
+  if (result.result === "false" && expected === true) {
+    nextSteps.push("Claim expected true but evaluated false: check path/method/name canonicalization.");
+  }
+
+  const finalResult = {
     claimId,
-    ...result,
-    evidence: await normalizeEvidence(projectPath, result.evidence, {
-      file: subject?.path || subject?.name,
-      line: 1,
-    }, result.confidence),
+    claim,
+    subject,
+    expected,
+    result: result.result,
+    confidence: result.confidence,
+    evidence: normalized,
+    enforcement,
+    nextSteps,
     timestamp: new Date().toISOString(),
     _attribution: CONTEXT_ATTRIBUTION,
   };
+
+  state.verifiedClaims.set(claimId, { projectHash: fingerprint.hash, timestamp: Date.now(), result: finalResult });
+  state.lastValidationByProject.set(projectPath, Date.now());
+
+  return finalResult;
 }
 
+// =============================================================================
+// IMPLEMENTATION: compile_context
+// =============================================================================
+
 async function compileContext(projectPath, args) {
-  const { task, files = [], policy = 'balanced' } = args;
-  
-  // Analyze task to determine relevant domains
+  const { task, files = [], policy = "balanced", maxItems = 50 } = args || {};
+  const pol = policy || "balanced";
+
   const domains = detectDomains(task);
   const keywords = extractKeywords(task);
-  
-  // Get relevant parts of truth pack
-  const truthPack = await getTruthPack(projectPath, { scope: 'all' });
-  
-  // Filter to relevant content
-  const relevantRoutes = truthPack.sections.routes?.routes?.filter(r => 
-    keywords.some(k => r.path.includes(k) || r.file.includes(k))
-  ) || [];
-  
-  const relevantAuth = domains.includes('auth') ? truthPack.sections.auth : null;
-  const relevantBilling = domains.includes('billing') ? truthPack.sections.billing : null;
-  
-  // Get applicable invariants
+  const truthPack = await getTruthPack(projectPath, { scope: "all", refresh: false });
+
+  const routesAll = truthPack.sections?.routes?.routes || [];
+  const relevantRoutes = routesAll.filter((r) => {
+    const hay = `${r.path || ""} ${r.file || ""}`.toLowerCase();
+    return keywords.some((k) => hay.includes(k));
+  });
+
+  const context = {
+    routes: relevantRoutes.slice(0, Math.max(0, maxItems)),
+    auth: domains.includes("auth") ? truthPack.sections?.auth : null,
+    billing: domains.includes("billing") ? truthPack.sections?.billing : null,
+    env: domains.includes("env") ? truthPack.sections?.env : null,
+    focusFiles: Array.isArray(files) ? files : [],
+  };
+
   const invariants = getInvariantsForDomains(domains);
-  
-  // Estimate token count
-  const tokenCount = estimateTokens({ relevantRoutes, relevantAuth, relevantBilling });
-  
+  const tokenCount = estimateTokens(context);
+
   return {
     task,
-    policy,
+    policy: pol,
     domains,
-    context: {
-      routes: relevantRoutes.slice(0, policy === 'strict' ? 10 : 50),
-      auth: relevantAuth,
-      billing: relevantBilling,
-    },
+    context,
     invariants,
     tokenCount,
-    warnings: generateContextWarnings(domains, policy, relevantRoutes.length),
+    warnings: generateContextWarnings(domains, pol, relevantRoutes.length),
     _attribution: CONTEXT_ATTRIBUTION,
   };
 }
 
+// =============================================================================
+// IMPLEMENTATION: search_evidence (rg accel + safe scan)
+// =============================================================================
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function isTestFilePath(rel) {
+  return /(^|\/)(__tests__|test|tests|spec)\//i.test(rel) || /\.(test|spec)\.(ts|tsx|js|jsx)$/i.test(rel);
+}
+
 async function searchEvidence(projectPath, args) {
-  const { query, type = 'any', limit = 10 } = args;
+  const {
+    query,
+    mode = "text",
+    type = "any",
+    limit = 10,
+    caseSensitive = false,
+    includeTests = false,
+  } = args || {};
+
+  const q = String(query || "").trim();
+  if (!q) return { query: q, count: 0, results: [], _attribution: CONTEXT_ATTRIBUTION };
+
+  // Try ripgrep for speed (optional)
+  const rgResults = tryRipgrep(projectPath, q, { mode, caseSensitive, limit, includeTests });
+  if (rgResults) {
+    return { query: q, count: rgResults.length, results: rgResults, engine: "ripgrep", _attribution: CONTEXT_ATTRIBUTION };
+  }
+
+  const files = await findSourceFiles(projectPath, { includeTests });
+  const flags = caseSensitive ? "g" : "gi";
+  const re = new RegExp(mode === "regex" ? q : escapeRegex(q), flags);
+
   const results = [];
-  
-  const files = await findSourceFiles(projectPath);
-  const pattern = new RegExp(query, 'gi');
-  
-  for (const file of files.slice(0, 100)) {
+  for (const fileAbs of files) {
+    const relPath = path.relative(projectPath, fileAbs).replace(/\\/g, "/");
+    if (!includeTests && isTestFilePath(relPath)) continue;
+
     try {
-      const content = await fs.readFile(file, 'utf8');
-      const lines = content.split('\n');
-      const relPath = path.relative(projectPath, file);
-      
+      const content = await fs.readFile(fileAbs, "utf8");
+      const lines = content.split(/\r?\n/);
+
       for (let i = 0; i < lines.length; i++) {
-        if (pattern.test(lines[i])) {
-          const snippet = lines.slice(Math.max(0, i - 2), Math.min(lines.length, i + 3)).join('\n');
+        if (re.test(lines[i])) {
+          const snippet = lines.slice(Math.max(0, i - 2), Math.min(lines.length, i + 3)).join("\n").slice(0, 320);
           results.push({
             file: relPath,
             line: i + 1,
-            snippet: snippet.slice(0, 300),
-            hash: crypto.createHash('sha256').update(lines[i]).digest('hex').slice(0, 16),
+            lines: `${i + 1}`,
+            snippet,
+            hash: sha16(`${relPath}:${i + 1}:${lines[i]}`),
             confidence: 0.6,
           });
-          
           if (results.length >= limit) break;
         }
-        pattern.lastIndex = 0;
+        re.lastIndex = 0;
       }
-      
+
       if (results.length >= limit) break;
-    } catch {}
+    } catch { /* ignore */ }
   }
-  
-  return {
-    query,
-    count: results.length,
-    results,
-    _attribution: CONTEXT_ATTRIBUTION,
-  };
+
+  return { query: q, count: results.length, results, engine: "scan", _attribution: CONTEXT_ATTRIBUTION };
 }
 
+function tryRipgrep(projectPath, query, opts) {
+  try {
+    const rgArgs = ["-n", "--hidden", "--no-heading", "--color", "never"];
+    rgArgs.push("--glob", "!**/node_modules/**");
+    rgArgs.push("--glob", "!**/.next/**");
+    rgArgs.push("--glob", "!**/dist/**");
+    rgArgs.push("--glob", "!**/build/**");
+    rgArgs.push("--glob", "!**/coverage/**");
+    if (!opts.includeTests) {
+      rgArgs.push("--glob", "!**/__tests__/**");
+      rgArgs.push("--glob", "!**/tests/**");
+      rgArgs.push("--glob", "!**/*.test.*");
+      rgArgs.push("--glob", "!**/*.spec.*");
+    }
+    if (!opts.caseSensitive) rgArgs.push("-i");
+    if (opts.mode === "text") rgArgs.push("-F"); // fixed string
+    rgArgs.push("--max-count", String(Math.max(1, opts.limit)));
+    rgArgs.push(query);
+    rgArgs.push(".");
+
+    const out = spawnSync("rg", rgArgs, { cwd: projectPath, encoding: "utf8" });
+    if (out.error || out.status !== 0) return null;
+
+    const lines = String(out.stdout || "").split(/\r?\n/).filter(Boolean);
+    const results = lines.slice(0, opts.limit).map((l) => {
+      // format: file:line:match
+      const m = l.match(/^(.+?):(\d+):(.*)$/);
+      if (!m) return null;
+      const file = m[1].replace(/\\/g, "/");
+      const lineNum = Number(m[2]);
+      const text = m[3] || "";
+      return {
+        file,
+        line: lineNum,
+        lines: `${lineNum}`,
+        snippet: text.slice(0, 320),
+        hash: sha16(`${file}:${lineNum}:${text}`),
+        confidence: 0.65,
+      };
+    }).filter(Boolean);
+
+    return results;
+  } catch {
+    return null;
+  }
+}
+
+// =============================================================================
+// IMPLEMENTATION: find_counterexamples
+// =============================================================================
+
 async function findCounterexamples(projectPath, args) {
-  const { claim, subject } = args;
+  const { claim, subject, policy = "strict" } = args || {};
+  const pol = policy || "strict";
+
   const counterexamples = [];
-  
-  switch (claim) {
-    case 'auth_enforced':
-      // Check for client-only guards
-      const authResult = await verifyRouteGuarded(projectPath, subject);
-      if (authResult.result === 'true' && authResult.evidence) {
-        // Check if guard is client-only
-        for (const ev of authResult.evidence) {
-          const content = await fs.readFile(path.join(projectPath, ev.file), 'utf8');
-          if (content.includes('client') && !content.includes('middleware')) {
-            counterexamples.push({
-              type: 'bypass_possible',
-              description: 'Auth appears to be client-side only - can be bypassed',
-              evidence: ev,
-              severity: 'ship_killer',
-            });
-          }
-        }
-      }
-      break;
-      
-    case 'billing_gate_exists':
-      // Check for client-only tier checks
-      const evidence = await searchEvidence(projectPath, { query: subject.name || 'tier', limit: 5 });
-      for (const ev of evidence.results) {
-        if (ev.snippet.includes('localStorage') || ev.snippet.includes('client')) {
-          counterexamples.push({
-            type: 'bypass_possible',
-            description: 'Billing check appears client-side only',
-            evidence: ev,
-            severity: 'ship_killer',
-          });
-        }
+
+  if (claim === "auth_enforced" || claim === "route_guarded") {
+    // Look for client-only guards (classic bypass)
+    const guardEvidence = await searchEvidence(projectPath, { query: "useEffect|client|localStorage|sessionStorage", mode: "regex", limit: 20 });
+    const middlewareEvidence = await searchEvidence(projectPath, { query: "middleware", mode: "text", limit: 10 });
+
+    if (guardEvidence.count > 0 && middlewareEvidence.count === 0) {
+      counterexamples.push({
+        type: "bypass_possible",
+        severity: "ship_killer",
+        description: "Auth appears client-only (no middleware/server guard evidence found).",
+        evidence: guardEvidence.results.slice(0, 3),
+      });
+    }
+  }
+
+  if (claim === "billing_gate_exists") {
+    const billingEvidence = await searchEvidence(projectPath, { query: "isPro|tier|plan|subscription|stripe", mode: "regex", limit: 20 });
+    for (const ev of billingEvidence.results) {
+      if (/localStorage|sessionStorage|client/i.test(ev.snippet)) {
+        counterexamples.push({
+          type: "bypass_possible",
+          severity: "ship_killer",
+          description: "Billing gate likely client-side (bypassable).",
+          evidence: ev,
+        });
       }
-      break;
+    }
   }
-  
+
   return {
     claim,
     subject,
+    policy: pol,
     counterexamples,
     claimDemoted: counterexamples.length > 0,
+    _attribution: CONTEXT_ATTRIBUTION,
   };
 }
 
+// =============================================================================
+// IMPLEMENTATION: propose_patch + verify_patch
+// =============================================================================
+
+function ensureDir(dirAbs) {
+  if (!fssync.existsSync(dirAbs)) fssync.mkdirSync(dirAbs, { recursive: true });
+}
+
 async function proposePatch(projectPath, args) {
-  const { diff, fixes, claims = [], verification = [] } = args;
-  
-  // Validate all dependent claims
+  const { diff, fixes, claims = [], verification = [], policy = "strict", save = true } = args || {};
+  const pol = policy || "strict";
+
   const claimValidation = [];
   for (const claimId of claims) {
     const cached = state.verifiedClaims.get(claimId);
     if (!cached) {
-      claimValidation.push({ claimId, valid: false, error: 'Claim not verified' });
-    } else if (cached.result.result === 'unknown') {
-      claimValidation.push({ claimId, valid: false, error: 'Claim is unknown - cannot proceed' });
-    } else if (cached.result.result === 'false') {
-      claimValidation.push({ claimId, valid: false, error: 'Claim is false - invalid dependency' });
-    } else {
-      claimValidation.push({ claimId, valid: true });
+      claimValidation.push({ claimId, valid: false, error: "Claim not verified" });
+      continue;
     }
+    const res = cached.result;
+    if (res?.result === "unknown") claimValidation.push({ claimId, valid: false, error: "Claim is unknown" });
+    else if (res?.result === "false") claimValidation.push({ claimId, valid: false, error: "Claim is false" });
+    else claimValidation.push({ claimId, valid: true });
   }
-  
-  const allClaimsValid = claimValidation.every(c => c.valid);
-  
+
+  const allClaimsValid = claimValidation.every((c) => c.valid);
+  const patchId = `patch_${crypto.randomUUID().slice(0, 12)}`;
+
   const patch = {
-    patchId: `patch_${crypto.randomUUID().slice(0, 12)}`,
-    diff: diff.slice(0, 5000), // Truncate for storage
-    fixes,
-    dependsOnClaims: claims,
-    verification: verification.length > 0 ? verification : ['vibecheck ship', 'pnpm test'],
+    patchId,
+    diff: String(diff || "").slice(0, 50_000),
+    fixes: Array.isArray(fixes) ? fixes : [],
+    dependsOnClaims: Array.isArray(claims) ? claims : [],
+    verification: (Array.isArray(verification) && verification.length > 0) ? verification : ["vibecheck ship", "pnpm test"],
     createdAt: new Date().toISOString(),
-    eligible: allClaimsValid && fixes.length > 0,
+    eligible: allClaimsValid && (Array.isArray(fixes) && fixes.length > 0),
     claimValidation,
+    policy: pol,
   };
-  
+
   if (!patch.eligible) {
-    patch.blockers = claimValidation.filter(c => !c.valid);
-    patch.message = '⚠️ Patch NOT eligible for auto-apply. Fix blockers first.';
+    patch.blockers = claimValidation.filter((c) => !c.valid);
+    patch.message = "⚠️ Patch NOT eligible for auto-apply. Fix blockers first.";
+  }
+
+  if (save) {
+    try {
+      const dir = safeProjectJoin(projectPath, ".vibecheck/patches");
+      ensureDir(dir);
+      const out = path.join(dir, `${patchId}.json`);
+      await fs.writeFile(out, JSON.stringify(patch, null, 2), "utf8");
+      patch.savedTo = path.relative(projectPath, out).replace(/\\/g, "/");
+    } catch (e) {
+      patch.saveError = e?.message || String(e);
+    }
   }
-  
+
   return patch;
 }
 
+function commandAllowlisted(cmd) {
+  // Keep this tight. Expand only if you mean it.
+  const allow = [
+    /^vibecheck(\s|$)/,
+    /^pnpm(\s|$)/,
+    /^npm(\s|$)/,
+    /^yarn(\s|$)/,
+    /^node(\s|$)/,
+    /^bun(\s|$)/,
+    /^vitest(\s|$)/,
+    /^jest(\s|$)/,
+    /^tsc(\s|$)/,
+    /^eslint(\s|$)/,
+    /^playwright(\s|$)/,
+  ];
+  return allow.some((re) => re.test(cmd.trim()));
+}
+
+async function verifyPatch(projectPath, args) {
+  const { patchId, diff, commands, policy = "strict", timeoutMs = 120000 } = args || {};
+  const pol = policy || "strict";
+
+  let patch = null;
+  if (patchId) {
+    try {
+      const abs = safeProjectJoin(projectPath, `.vibecheck/patches/${patchId}.json`);
+      const content = await fs.readFile(abs, "utf8");
+      patch = JSON.parse(content);
+    } catch (error) {
+      // Invalid JSON or file not found - treat as no patch
+      patch = null;
+    }
+  }
+
+  // NOTE: This does NOT auto-apply diff. It only runs verification commands.
+  // Auto-apply should be a separate tool with explicit guardrails.
+  const cmds = Array.isArray(commands) ? commands : [];
+  const results = [];
+
+  for (const cmd of cmds) {
+    if (!commandAllowlisted(cmd)) {
+      results.push({ cmd, ok: false, blocked: true, reason: "Command not allowlisted" });
+      continue;
+    }
+    const started = Date.now();
+    const out = spawnSync(cmd, {
+      cwd: projectPath,
+      shell: true,
+      encoding: "utf8",
+      timeout: Math.max(1000, Number(timeoutMs) || 120000),
+      maxBuffer: 1024 * 1024 * 5,
+    });
+
+    const stdout = String(out.stdout || "").slice(0, MAX_CMD_OUTPUT);
+    const stderr = String(out.stderr || "").slice(0, MAX_CMD_OUTPUT);
+
+    results.push({
+      cmd,
+      ok: out.status === 0 && !out.error,
+      status: out.status,
+      durationMs: Date.now() - started,
+      stdout,
+      stderr,
+      error: out.error ? String(out.error.message || out.error) : null,
+    });
+  }
+
+  const pass = results.every((r) => r.ok);
+
+  return {
+    patchId: patch?.patchId || patchId || null,
+    hasPatchRecord: !!patch,
+    policy: pol,
+    pass,
+    results,
+    note: "verify_patch runs commands only. Applying diffs should be explicit + guarded.",
+    _attribution: CONTEXT_ATTRIBUTION,
+  };
+}
+
+// =============================================================================
+// IMPLEMENTATION: invariants
+// =============================================================================
+
 async function checkInvariants(projectPath, args) {
-  const category = args.category || 'all';
+  const { category = "all", policy = "strict" } = args || {};
+  const pol = policy || "strict";
+
   const shipKillers = [];
   const warnings = [];
-  
-  // Check for silent catches in auth/billing
-  const silentCatches = await searchEvidence(projectPath, { 
-    query: 'catch.*\\{\\s*\\}|catch.*\\{\\s*//|catch.*console\\.log', 
-    limit: 20 
+
+  // 1) Silent catches in auth/billing/middleware are ship killers
+  const silentCatches = await searchEvidence(projectPath, {
+    query: String.raw`catch\s*\(\s*\w*\s*\)\s*\{\s*(?:\}|\/\/|console\.log|return\s*;|return\s*null\s*;)`,
+    mode: "regex",
+    limit: 50,
   });
-  
+
   for (const ev of silentCatches.results) {
-    if (ev.file.includes('auth') || ev.file.includes('billing') || ev.file.includes('middleware')) {
+    if (/auth|billing|middleware|payment/i.test(ev.file)) {
       shipKillers.push({
-        invariant: 'security_no_silent_catch',
-        rule: 'No silent catch in auth/billing flows',
+        invariant: "security_no_silent_catch",
+        rule: "No silent catch in auth/billing/middleware",
         evidence: ev,
       });
     }
   }
-  
-  // Check for hardcoded secrets
+
+  // 2) Hardcoded secrets (ship killer)
   const secrets = await searchEvidence(projectPath, {
-    query: 'sk_live_|sk_test_|apiKey.*=.*["\'][a-zA-Z0-9]{20,}',
-    limit: 10,
+    query: String.raw`(sk_live_|AKIA[0-9A-Z]{16}|AIza[0-9A-Za-z\-_]{35}|xox[baprs]-[0-9A-Za-z\-]{10,})`,
+    mode: "regex",
+    limit: 20,
   });
-  
+
   for (const ev of secrets.results) {
-    if (!ev.file.includes('.test.') && !ev.file.includes('.example')) {
+    if (!/\.example|\.test\.|\.spec\./i.test(ev.file)) {
       shipKillers.push({
-        invariant: 'security_no_exposed_secrets',
-        rule: 'No hardcoded secrets or API keys',
+        invariant: "security_no_exposed_secrets",
+        rule: "No hardcoded secrets or API keys",
         evidence: ev,
       });
     }
   }
-  
+
+  // 3) “Success UI without confirmed success” (warning by default)
+  const fakeSuccess = await searchEvidence(projectPath, {
+    query: String.raw`toast\.(success|info)|setSuccess\s*\(|"success"|success:\s*true`,
+    mode: "regex",
+    limit: 30,
+  });
+
+  for (const ev of fakeSuccess.results) {
+    // This is heuristic: you’ll tighten it by correlating with network calls later.
+    warnings.push({
+      invariant: "ux_no_fake_success",
+      rule: "Success UI should be tied to confirmed success (network/response)",
+      evidence: ev,
+    });
+  }
+
+  const passed = shipKillers.length === 0;
   return {
-    passed: shipKillers.length === 0,
+    policy: pol,
+    category,
+    passed,
     shipKillers,
     warnings,
-    summary: shipKillers.length === 0 
-      ? '✅ All invariants pass'
-      : `❌ ${shipKillers.length} ship killers found - deployment blocked`,
+    summary: passed ? "✅ Invariants pass" : `❌ ${shipKillers.length} ship killers found`,
+    _attribution: CONTEXT_ATTRIBUTION,
   };
 }
 
+// =============================================================================
+// IMPLEMENTATION: assumptions
+// =============================================================================
+
 async function addAssumption(projectPath, args) {
-  const { description, reason, verificationSteps } = args;
-  
-  if (state.assumptions.length >= state.maxAssumptions) {
+  const { description, reason, verificationSteps } = args || {};
+
+  const list = state.assumptionsByProject.get(projectPath) || [];
+  if (list.length >= state.maxAssumptions) {
     return {
-      error: `Assumption budget exceeded (${state.assumptions.length}/${state.maxAssumptions})`,
-      message: '⚠️ You MUST verify existing assumptions or use proof tooling instead of assuming.',
-      currentAssumptions: state.assumptions,
+      error: `Assumption budget exceeded (${list.length}/${state.maxAssumptions})`,
+      message: "⚠️ Verify or delete assumptions. Don’t stack guesses.",
+      currentAssumptions: list,
+      _attribution: CONTEXT_ATTRIBUTION,
     };
   }
-  
+
   const assumption = {
-    id: `assumption_${Date.now()}`,
-    description,
-    reason,
-    verificationSteps,
+    id: `assumption_${Date.now()}_${crypto.randomUUID().slice(0, 6)}`,
+    description: String(description || ""),
+    reason: reason ? String(reason) : "",
+    verificationSteps: Array.isArray(verificationSteps) ? verificationSteps : [],
     madeAt: new Date().toISOString(),
     verified: false,
   };
-  
-  state.assumptions.push(assumption);
-  
+
+  list.push(assumption);
+  state.assumptionsByProject.set(projectPath, list);
+
   return {
     assumption,
-    budget: {
-      used: state.assumptions.length,
-      max: state.maxAssumptions,
-      remaining: state.maxAssumptions - state.assumptions.length,
-    },
-    warning: state.assumptions.length >= state.maxAssumptions - 1
-      ? '⚠️ Approaching assumption limit. Consider verifying claims instead.'
-      : null,
+    budget: { used: list.length, max: state.maxAssumptions, remaining: state.maxAssumptions - list.length },
+    warning: list.length >= state.maxAssumptions ? "⚠️ Assumption limit reached." : null,
+    _attribution: CONTEXT_ATTRIBUTION,
   };
 }
 
 // =============================================================================
-// PLAN VALIDATION & DRIFT DETECTION (Spec 10.3)
+// PLAN VALIDATION & DRIFT
 // =============================================================================
 
 async function getPlanValidationResult(projectPath, args) {
-  const { plan, strict = false } = args;
-  
-  // Load contracts
+  const { plan, strict = false } = args || {};
+
   const contracts = await loadContractsFromDisk(projectPath);
-  
   if (!contracts || Object.keys(contracts).length === 0) {
     return {
       valid: true,
@@ -959,87 +1274,72 @@ async function getPlanValidationResult(projectPath, args) {
       violations: [],
       warnings: [],
       suggestions: ['Generate contracts with: vibecheck ctx sync'],
+      _attribution: CONTEXT_ATTRIBUTION,
     };
   }
-  
-  // Parse plan to extract actions
+
   const actions = parsePlanActions(plan);
+
   const violations = [];
   const warnings = [];
   const suggestions = [];
-  
-  // Validate route references
+
+  // routes
   if (contracts.routes && actions.routes.length > 0) {
-    const contractRoutes = new Set(contracts.routes.routes?.map(r => r.path) || []);
-    
-    for (const route of actions.routes) {
-      if (!contractRoutes.has(route.path)) {
-        // Check parameterized match
-        const match = contracts.routes.routes?.find(r => matchesParameterizedPath(r.path, route.path));
-        if (!match) {
-          violations.push({
-            type: 'invented_route',
-            severity: 'BLOCK',
-            route: route.path,
-            method: route.method,
-            message: `Plan references route ${route.method} ${route.path} which does not exist in contract`,
-            suggestion: `Available routes: ${contracts.routes.routes?.slice(0, 5).map(r => r.path).join(', ')}...`,
-          });
-        }
-      }
-    }
-  }
-  
-  // Validate env var references
-  if (contracts.env && actions.envVars.length > 0) {
-    const contractVars = new Set(contracts.env.vars?.map(v => v.name) || []);
-    
-    for (const varName of actions.envVars) {
-      if (!contractVars.has(varName)) {
-        warnings.push({
-          type: 'undeclared_env',
-          severity: 'WARN',
-          name: varName,
-          message: `Plan uses env var ${varName} which is not in contract`,
-          suggestion: 'Add to .vibecheck/contracts/env.json or .env.example',
+    const contractRoutes = (contracts.routes.routes || []).map((r) => ({
+      method: String(r.method || "*").toUpperCase(),
+      path: canonicalizePath(String(r.path || "")),
+    }));
+
+    for (const r of actions.routes) {
+      const wanted = { method: String(r.method || "GET").toUpperCase(), path: canonicalizePath(r.path) };
+      const exists = contractRoutes.some((cr) => (cr.method === "*" || cr.method === wanted.method) && matchesParameterizedPath(cr.path, wanted.path));
+      if (!exists) {
+        violations.push({
+          type: "invented_route",
+          severity: "BLOCK",
+          route: wanted.path,
+          method: wanted.method,
+          message: `Plan references route ${wanted.method} ${wanted.path} not in routes contract`,
         });
       }
     }
   }
-  
-  // Validate auth assumptions
-  if (contracts.auth && actions.authAssumptions.length > 0) {
-    for (const assumption of actions.authAssumptions) {
-      if (assumption.type === 'no_auth') {
+
+  // env vars
+  if (contracts.env && actions.envVars.length > 0) {
+    const contractVars = new Set((contracts.env.vars || []).map((v) => v.name));
+    for (const v of actions.envVars) {
+      if (!contractVars.has(v)) {
         warnings.push({
-          type: 'auth_assumption',
-          severity: 'WARN',
-          message: 'Plan assumes some routes are public - verify against auth contract',
-          suggestion: `Protected patterns: ${contracts.auth.protectedPatterns?.slice(0, 3).join(', ')}...`,
+          type: "undeclared_env",
+          severity: "WARN",
+          name: v,
+          message: `Plan uses env var ${v} not declared in env contract`,
+          suggestion: "Add to .vibecheck/contracts/env.json and .env.example",
         });
       }
     }
   }
-  
-  // Validate external service usage
+
+  // external services
   if (contracts.external && actions.externalCalls.length > 0) {
-    const contractServices = new Set(contracts.external.services?.map(s => s.name) || []);
-    
+    const contractServices = new Set((contracts.external.services || []).map((s) => s.name));
     for (const call of actions.externalCalls) {
       if (!contractServices.has(call.service)) {
         warnings.push({
-          type: 'undeclared_service',
-          severity: 'WARN',
+          type: "undeclared_service",
+          severity: "WARN",
           service: call.service,
-          message: `Plan uses ${call.service} which is not declared in external contract`,
-          suggestion: 'Add to .vibecheck/contracts/external.json',
+          message: `Plan uses ${call.service} not declared in external contract`,
+          suggestion: "Add to .vibecheck/contracts/external.json",
         });
       }
     }
   }
-  
+
   const valid = violations.length === 0 && (!strict || warnings.length === 0);
-  
+
   return {
     valid,
     violations,
@@ -1047,78 +1347,48 @@ async function getPlanValidationResult(projectPath, args) {
     suggestions,
     parsedActions: actions,
     contractsLoaded: Object.keys(contracts),
-    message: valid 
-      ? '✅ Plan validated against contracts'
-      : `❌ Plan validation failed: ${violations.length} violations, ${warnings.length} warnings`,
+    message: valid ? "✅ Plan validated" : `❌ Plan invalid: ${violations.length} violations, ${warnings.length} warnings`,
+    _attribution: CONTEXT_ATTRIBUTION,
   };
 }
 
 async function checkDriftTool(projectPath, args) {
-  const category = args.category || 'all';
-  
-  // Load contracts
+  const category = args?.category || "all";
+
   const contracts = await loadContractsFromDisk(projectPath);
-  
   if (!contracts || Object.keys(contracts).length === 0) {
-    return {
-      hasDrift: false,
-      message: 'No contracts found. Run "vibecheck ctx sync" to generate contracts.',
-      findings: [],
-    };
+    return { hasDrift: false, message: 'No contracts found. Run "vibecheck ctx sync".', findings: [], _attribution: CONTEXT_ATTRIBUTION };
   }
-  
-  // Build current truthpack
+
   const truthpack = await buildCurrentTruthpack(projectPath);
-  
-  // Detect drift
   const findings = [];
-  
-  if (category === 'all' || category === 'routes') {
-    const routeDrift = detectRouteDrift(contracts.routes, truthpack);
-    findings.push(...routeDrift);
-  }
-  
-  if (category === 'all' || category === 'env') {
-    const envDrift = detectEnvDrift(contracts.env, truthpack);
-    findings.push(...envDrift);
-  }
-  
-  if (category === 'all' || category === 'auth') {
-    const authDrift = detectAuthDrift(contracts.auth, truthpack);
-    findings.push(...authDrift);
-  }
-  
-  const blocks = findings.filter(f => f.severity === 'BLOCK');
-  const warns = findings.filter(f => f.severity === 'WARN');
-  
+
+  if (category === "all" || category === "routes") findings.push(...detectRouteDrift(contracts.routes, truthpack));
+  if (category === "all" || category === "env") findings.push(...detectEnvDrift(contracts.env, truthpack));
+  if (category === "all" || category === "auth") findings.push(...detectAuthDrift(contracts.auth, truthpack));
+
+  const blocks = findings.filter((f) => f.severity === "BLOCK");
+  const warns = findings.filter((f) => f.severity === "WARN");
+
   return {
     hasDrift: findings.length > 0,
-    verdict: blocks.length > 0 ? 'BLOCK' : warns.length > 0 ? 'WARN' : 'PASS',
-    summary: {
-      blocks: blocks.length,
-      warns: warns.length,
-      total: findings.length,
-    },
+    verdict: blocks.length > 0 ? "BLOCK" : warns.length > 0 ? "WARN" : "PASS",
+    summary: { blocks: blocks.length, warns: warns.length, total: findings.length },
     findings,
-    message: findings.length === 0
-      ? '✅ No drift detected - contracts match codebase'
-      : `⚠️ Drift detected: ${blocks.length} blocks, ${warns.length} warnings. Run 'vibecheck ctx sync' to update.`,
+    message: findings.length === 0 ? "✅ No drift detected" : `⚠️ Drift detected: ${blocks.length} blocks, ${warns.length} warnings`,
+    _attribution: CONTEXT_ATTRIBUTION,
   };
 }
 
 async function getContractsTool(projectPath, args) {
-  const type = args.type || 'all';
+  const type = args?.type || "all";
   const contracts = await loadContractsFromDisk(projectPath);
-  
+
   if (!contracts || Object.keys(contracts).length === 0) {
-    return {
-      found: false,
-      message: 'No contracts found. Run "vibecheck ctx sync" to generate contracts.',
-      contracts: {},
-    };
+    return { found: false, message: 'No contracts found. Run "vibecheck ctx sync".', contracts: {}, _attribution: CONTEXT_ATTRIBUTION };
   }
-  
-  if (type === 'all') {
+
+  if (type === "all") {
     return {
       found: true,
       contracts,
@@ -1128,371 +1398,461 @@ async function getContractsTool(projectPath, args) {
         authPatterns: contracts.auth?.protectedPatterns?.length || 0,
         services: contracts.external?.services?.length || 0,
       },
+      _attribution: CONTEXT_ATTRIBUTION,
     };
   }
-  
-  return {
-    found: !!contracts[type],
-    contracts: { [type]: contracts[type] },
-  };
+
+  return { found: !!contracts[type], contracts: { [type]: contracts[type] }, _attribution: CONTEXT_ATTRIBUTION };
 }
 
-// Helper: Load contracts from disk
 async function loadContractsFromDisk(projectPath) {
-  const contractDir = path.join(projectPath, '.vibecheck', 'contracts');
+  const contractDir = safeProjectJoin(projectPath, ".vibecheck/contracts");
   const contracts = {};
-  
+
   const files = {
-    routes: 'routes.json',
-    env: 'env.json',
-    auth: 'auth.json',
-    external: 'external.json',
+    routes: "routes.json",
+    env: "env.json",
+    auth: "auth.json",
+    external: "external.json",
   };
-  
+
   for (const [key, file] of Object.entries(files)) {
-    const filePath = path.join(contractDir, file);
     try {
-      const content = await fs.readFile(filePath, 'utf8');
+      const abs = path.join(contractDir, file);
+      const content = await fs.readFile(abs, "utf8");
       contracts[key] = JSON.parse(content);
-    } catch {}
+    } catch (error) {
+      // Invalid JSON or file not found - skip this contract
+      // ignore
+    }
   }
-  
+
   return contracts;
 }
 
-// Helper: Parse plan to extract actions
+// =============================================================================
+// PARSING HELPERS
+// =============================================================================
+
+function canonicalizePath(p) {
+  let s = String(p || "").trim();
+  if (!s.startsWith("/")) s = "/" + s;
+  s = s.replace(/\/+/g, "/");
+  if (s.length > 1) s = s.replace(/\/$/, "");
+  return s;
+}
+
+function dedupe(arr, keyFn) {
+  const seen = new Set();
+  const out = [];
+  for (const item of arr) {
+    const k = keyFn(item);
+    if (seen.has(k)) continue;
+    seen.add(k);
+    out.push(item);
+  }
+  return out;
+}
+
 function parsePlanActions(plan) {
   const actions = {
     routes: [],
     envVars: [],
-    files: [],
     authAssumptions: [],
     externalCalls: [],
   };
-  
-  const planText = typeof plan === 'string' ? plan : JSON.stringify(plan);
-  
-  // Extract route references
+
+  const planText = typeof plan === "string" ? plan : JSON.stringify(plan);
+
+  // routes
   const routePatterns = [
-    /(?:fetch|axios|api\.?)\s*\(\s*['"`]([/][^'"`]+)['"`]/gi,
-    /(?:GET|POST|PUT|PATCH|DELETE)\s+([/][^\s]+)/gi,
+    /(?:GET|POST|PUT|PATCH|DELETE)\s+([/][^\s"'`]+)/gi,
     /\/api\/[a-z0-9/_-]+/gi,
   ];
-  
+
   for (const pattern of routePatterns) {
     let match;
     while ((match = pattern.exec(planText)) !== null) {
-      const p = match[1] || match[0];
-      if (p.startsWith('/')) {
-        actions.routes.push({
-          path: p.replace(/['"`]/g, ''),
-          method: inferMethodFromText(match[0]),
-        });
+      const p = (match[1] || match[0]).replace(/['"`]/g, "");
+      if (p.startsWith("/")) {
+        actions.routes.push({ path: canonicalizePath(p), method: inferMethodFromText(match[0]) });
       }
     }
   }
-  
-  // Extract env var references
+
+  actions.routes = dedupe(actions.routes, (r) => `${r.method}:${r.path}`);
+
+  // env vars
   const envPatterns = [
-    /process\.env\.([A-Z_][A-Z0-9_]*)/gi,
-    /import\.meta\.env\.([A-Z_][A-Z0-9_]*)/gi,
+    /process\.env\.([A-Z_][A-Z0-9_]*)/g,
+    /import\.meta\.env\.([A-Z_][A-Z0-9_]*)/g,
   ];
-  
   for (const pattern of envPatterns) {
     let match;
-    while ((match = pattern.exec(planText)) !== null) {
-      if (match[1] && /^[A-Z]/.test(match[1])) {
-        actions.envVars.push(match[1]);
-      }
-    }
-  }
-  
-  // Extract auth assumptions
-  if (/(?:authenticated|logged in|auth required|protected)/i.test(planText)) {
-    actions.authAssumptions.push({ type: 'requires_auth' });
+    while ((match = pattern.exec(planText)) !== null) actions.envVars.push(match[1]);
   }
-  if (/(?:public|no auth|unauthenticated)/i.test(planText)) {
-    actions.authAssumptions.push({ type: 'no_auth' });
-  }
-  
-  // Extract external service references
-  const servicePatterns = [
-    { pattern: /stripe\./gi, service: 'stripe' },
-    { pattern: /github\./gi, service: 'github' },
-    { pattern: /sendgrid\./gi, service: 'sendgrid' },
-    { pattern: /twilio\./gi, service: 'twilio' },
-    { pattern: /supabase\./gi, service: 'supabase' },
+  actions.envVars = dedupe(actions.envVars, (v) => v);
+
+  // auth assumptions
+  if (/(authenticated|logged in|auth required|protected)/i.test(planText)) actions.authAssumptions.push({ type: "requires_auth" });
+  if (/(public|no auth|unauthenticated)/i.test(planText)) actions.authAssumptions.push({ type: "no_auth" });
+
+  // external services
+  const services = [
+    { re: /stripe\./i, service: "stripe" },
+    { re: /github\./i, service: "github" },
+    { re: /sendgrid\./i, service: "sendgrid" },
+    { re: /twilio\./i, service: "twilio" },
+    { re: /supabase\./i, service: "supabase" },
   ];
-  
-  for (const { pattern, service } of servicePatterns) {
-    if (pattern.test(planText)) {
-      actions.externalCalls.push({ service });
-    }
+  for (const s of services) {
+    if (s.re.test(planText)) actions.externalCalls.push({ service: s.service });
   }
-  
+  actions.externalCalls = dedupe(actions.externalCalls, (c) => c.service);
+
   return actions;
 }
 
 function inferMethodFromText(text) {
-  const upper = text.toUpperCase();
-  if (upper.includes('POST')) return 'POST';
-  if (upper.includes('PUT')) return 'PUT';
-  if (upper.includes('PATCH')) return 'PATCH';
-  if (upper.includes('DELETE')) return 'DELETE';
-  return 'GET';
+  const upper = String(text || "").toUpperCase();
+  if (upper.includes("POST")) return "POST";
+  if (upper.includes("PUT")) return "PUT";
+  if (upper.includes("PATCH")) return "PATCH";
+  if (upper.includes("DELETE")) return "DELETE";
+  return "GET";
 }
 
 function matchesParameterizedPath(pattern, actual) {
-  const patternParts = pattern.split('/').filter(Boolean);
-  const actualParts = actual.split('/').filter(Boolean);
-  if (patternParts.length !== actualParts.length) return false;
-  for (let i = 0; i < patternParts.length; i++) {
-    const p = patternParts[i];
-    if (p.startsWith(':') || p.startsWith('*') || p.startsWith('[')) continue;
-    if (p !== actualParts[i]) return false;
+  const pParts = canonicalizePath(pattern).split("/").filter(Boolean);
+  const aParts = canonicalizePath(actual).split("/").filter(Boolean);
+  if (pParts.length !== aParts.length) return false;
+
+  for (let i = 0; i < pParts.length; i++) {
+    const p = pParts[i];
+    if (p.startsWith(":") || p.startsWith("*") || p.startsWith("[")) continue;
+    if (p !== aParts[i]) return false;
   }
   return true;
 }
 
-// Helper: Build current truthpack (lightweight version)
-async function buildCurrentTruthpack(projectPath) {
-  const routes = await extractRoutes(projectPath);
+// =============================================================================
+// DRIFT DETECTORS (improved: added removals)
+// =============================================================================
+
+async function buildCurrentTruthpack(projectPath, refresh = false) {
+  const routes = await extractRoutes(projectPath, refresh);
   const env = await extractEnv(projectPath);
   const auth = await extractAuth(projectPath);
-  
+
   return {
     routes: {
-      server: routes.routes,
-      clientRefs: [],
-    },
-    env: {
-      vars: env.used,
-      declared: env.declared.map(d => d.name),
-    },
-    auth: {
-      nextMatcherPatterns: [], // Would need middleware parsing
+      server: routes.routes || [],
+      gaps: routes.gaps || [],
+      engine: routes.engine,
     },
+    env: { vars: env.used || [], declared: (env.declared || []).map((d) => d.name) },
+    auth: { nextMatcherPatterns: auth?.nextMatcherPatterns || [] },
   };
 }
 
-// Helper: Detect route drift
 function detectRouteDrift(routeContract, truthpack) {
   const findings = [];
   if (!routeContract?.routes) return findings;
-  
-  const contractRoutes = new Map(routeContract.routes.map(r => [`${r.method}_${r.path}`, r]));
-  const serverRoutes = truthpack?.routes?.server || [];
-  
-  for (const route of serverRoutes) {
-    const key = `${route.method}_${route.path}`;
-    if (!contractRoutes.has(key)) {
+
+  // Use Route Truth v1 canonicalization for consistency
+  const canonicalize = routeTruthCanonicalize || canonicalizePath;
+
+  const contractSet = new Set(routeContract.routes.map((r) => `${String(r.method || "*").toUpperCase()}_${canonicalize(r.path)}`));
+  const server = truthpack?.routes?.server || [];
+  const serverSet = new Set(server.map((r) => `${String(r.method || "*").toUpperCase()}_${canonicalize(r.path)}`));
+  const gaps = truthpack?.routes?.gaps || [];
+
+  // new routes (in code, not in contract)
+  for (const key of serverSet) {
+    if (!contractSet.has(key)) {
+      const [method, routePath] = key.split("_");
+      const routeInfo = server.find((r) => canonicalize(r.path) === routePath && String(r.method || "*").toUpperCase() === method);
+
+      findings.push({
+        type: "new_route_not_in_contract",
+        severity: "BLOCK",
+        title: `New route not in contract: ${method} ${routePath}`,
+        message: "Route exists in code but not synced to routes contract.",
+        file: routeInfo?.file,
+        framework: routeInfo?.framework,
+      });
+    }
+  }
+
+  // removed routes (in contract, not in code)
+  for (const key of contractSet) {
+    if (!serverSet.has(key)) {
+      const hasGaps = gaps.length > 0;
       findings.push({
-        type: 'new_route_not_in_contract',
-        severity: 'BLOCK',
-        title: `New route ${route.method} ${route.path} not in contract`,
-        message: 'Route added to code but not synced to contracts.',
+        type: "contract_route_missing_in_code",
+        severity: hasGaps ? "WARN" : "WARN", // Demote if gaps exist
+        title: `Contract route missing in code: ${key.replace("_", " ")}`,
+        message: hasGaps
+          ? "Contract lists a route not detected in code. Note: some plugins couldn't be resolved."
+          : "Contract lists a route not detected in code (stale contract?).",
+        mayBeExtractorGap: hasGaps,
       });
     }
   }
-  
+
+  // Report gaps as info
+  if (gaps.length > 0) {
+    findings.push({
+      type: "extractor_gaps",
+      severity: "INFO",
+      title: `Route extractor has ${gaps.length} unresolved module(s)`,
+      message: "Some Fastify plugins or imports couldn't be resolved - routes may be incomplete.",
+      gaps: gaps.slice(0, 5), // Limit to first 5
+    });
+  }
+
   return findings;
 }
 
-// Helper: Detect env drift
 function detectEnvDrift(envContract, truthpack) {
   const findings = [];
   if (!envContract?.vars) return findings;
-  
-  const contractVars = new Set(envContract.vars.map(v => v.name));
-  const usedVars = truthpack?.env?.vars || [];
-  
-  for (const v of usedVars) {
-    if (!contractVars.has(v.name)) {
+
+  const contractVars = new Set(envContract.vars.map((v) => v.name));
+  const usedVars = new Set((truthpack?.env?.vars || []).map((v) => v.name));
+
+  for (const name of usedVars) {
+    if (!contractVars.has(name)) {
       findings.push({
-        type: 'new_env_not_in_contract',
-        severity: 'WARN',
-        title: `Env var ${v.name} used but not in contract`,
-        message: 'Env var used in code but not declared in contracts.',
+        type: "new_env_not_in_contract",
+        severity: "WARN",
+        title: `Env var used but not in contract: ${name}`,
+        message: "Env var used in code but not declared in contracts.",
       });
     }
   }
-  
+
+  for (const name of contractVars) {
+    if (!usedVars.has(name)) {
+      findings.push({
+        type: "contract_env_unused",
+        severity: "WARN",
+        title: `Env var in contract appears unused: ${name}`,
+        message: "Contract env var not detected in usage (stale contract or extractor gap).",
+      });
+    }
+  }
+
   return findings;
 }
 
-// Helper: Detect auth drift
 function detectAuthDrift(authContract, truthpack) {
   const findings = [];
   if (!authContract?.protectedPatterns) return findings;
-  
-  const contractPatterns = new Set(authContract.protectedPatterns);
-  const currentPatterns = new Set(truthpack?.auth?.nextMatcherPatterns || []);
-  
-  for (const pattern of currentPatterns) {
-    if (!contractPatterns.has(pattern)) {
+
+  const contract = new Set(authContract.protectedPatterns);
+  const current = new Set(truthpack?.auth?.nextMatcherPatterns || []);
+
+  for (const pattern of current) {
+    if (!contract.has(pattern)) {
       findings.push({
-        type: 'new_auth_pattern',
-        severity: 'BLOCK',
-        title: `New auth pattern "${pattern}" not in contract`,
-        message: 'Auth pattern added but not in contracts.',
+        type: "new_auth_pattern",
+        severity: "BLOCK",
+        title: `New auth pattern not in contract: ${pattern}`,
+        message: "Auth matcher/pattern changed but contracts not updated.",
       });
     }
   }
-  
+
   return findings;
 }
 
 // =============================================================================
-// HELPERS
+// DOMAIN HELPERS
 // =============================================================================
 
-function getCommitHash(projectPath) {
-  try {
-    return execSync('git rev-parse HEAD', { cwd: projectPath, encoding: 'utf8' }).trim();
-  } catch {
-    return 'unknown';
-  }
+function detectDomains(task) {
+  const domains = [];
+  const t = String(task || "");
+  if (/auth|login|logout|session|password/i.test(t)) domains.push("auth");
+  if (/billing|payment|stripe|subscription/i.test(t)) domains.push("billing");
+  if (/env|secret|config/i.test(t)) domains.push("env");
+  if (/route|api|endpoint/i.test(t)) domains.push("api");
+  if (/component|button|ui|form/i.test(t)) domains.push("ui");
+  return domains.length ? domains : ["general"];
 }
 
-/**
- * Generate a project fingerprint for stale assumption detection (Spec 10.2)
- * Includes: commit hash, key file hashes, timestamp
- */
-export function getProjectFingerprint(projectPath) {
-  const commitHash = getCommitHash(projectPath);
-  const keyFiles = [
-    'package.json',
-    'prisma/schema.prisma',
-    'next.config.js',
-    'next.config.ts',
-    '.vibecheck/contracts/routes.json',
-  ];
-  
-  const fileHashes = [];
-  for (const file of keyFiles) {
+function extractKeywords(task) {
+  return String(task || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9\s/_-]/g, " ")
+    .split(/\s+/)
+    .filter((w) => w.length > 2)
+    .slice(0, 40);
+}
+
+function getInvariantsForDomains(domains) {
+  const invariants = [];
+  if (domains.includes("auth")) invariants.push("No protected route without server middleware");
+  if (domains.includes("billing")) invariants.push("No paid feature without server-side enforcement");
+  invariants.push("No success UI without confirmed success");
+  invariants.push("No invented routes/env vars/functions in plans");
+  return invariants;
+}
+
+function estimateTokens(context) {
+  let tokens = 0;
+  if (context?.routes) tokens += context.routes.length * 50;
+  if (context?.auth) tokens += 220;
+  if (context?.billing) tokens += 220;
+  if (context?.env) tokens += 180;
+  return tokens;
+}
+
+function generateContextWarnings(domains, policy, routeCount) {
+  const warnings = [];
+  if (domains.includes("auth") || domains.includes("billing")) warnings.push("High-stakes domain: verify claims before edits.");
+  if (routeCount > 50 && policy === "strict") warnings.push("Large route surface: narrow task or specify files.");
+  return warnings;
+}
+
+// =============================================================================
+// SOURCE FILE DISCOVERY (safe + bounded)
+// =============================================================================
+
+async function findSourceFiles(projectPath, opts) {
+  const files = [];
+  const ignoreDirs = new Set(["node_modules", "dist", "build", ".git", ".next", "coverage", "out"]);
+
+  async function walk(dirAbs) {
+    let entries = [];
     try {
-      const content = require('fs').readFileSync(path.join(projectPath, file), 'utf8');
-      const hash = crypto.createHash('sha256').update(content).digest('hex').slice(0, 8);
-      fileHashes.push(`${file}:${hash}`);
-    } catch {}
+      entries = await fs.readdir(dirAbs, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const full = path.join(dirAbs, entry.name);
+      if (entry.isDirectory()) {
+        if (ignoreDirs.has(entry.name) || entry.name.startsWith(".")) continue;
+        await walk(full);
+      } else if (entry.isFile()) {
+        if (!/\.(ts|tsx|js|jsx)$/.test(entry.name)) continue;
+        const rel = path.relative(projectPath, full).replace(/\\/g, "/");
+        if (!opts?.includeTests && isTestFilePath(rel)) continue;
+        files.push(full);
+        if (files.length > 2500) return; // hard cap
+      }
+    }
   }
-  
-  const fingerprintData = [
-    commitHash,
-    ...fileHashes,
-  ].join('|');
-  
-  return {
-    hash: crypto.createHash('sha256').update(fingerprintData).digest('hex').slice(0, 16),
-    commitHash,
-    fileHashes,
-    generatedAt: new Date().toISOString(),
-  };
+
+  await walk(path.resolve(projectPath));
+  return files;
 }
 
-/**
- * Context attribution message shown when AI uses vibecheck data
- */
-const CONTEXT_ATTRIBUTION = "🧠 Context enhanced by vibecheck";
+// =============================================================================
+// ROUTE TRUTH V1 INTEGRATION (AST-based, follows Fastify register prefixes + Next.js app/pages)
+// =============================================================================
 
 /**
- * Wrap MCP response with standard metadata including fingerprint (Spec 10.2)
+ * Get or build the Route Truth v1 index for a project.
+ * This is the SINGLE SOURCE OF TRUTH for route reality.
  */
-export function wrapMcpResponse(data, projectPath) {
-  return {
-    ok: true,
-    version: '2.0.0',
-    projectFingerprint: getProjectFingerprint(projectPath),
-    data,
-    _attribution: CONTEXT_ATTRIBUTION,
-  };
+async function getRouteIndex(projectPath, refresh = false) {
+  if (!refresh && state.routeIndexByProject.has(projectPath)) {
+    return state.routeIndexByProject.get(projectPath);
+  }
+
+  const index = new RouteIndex();
+  await index.build(projectPath);
+  state.routeIndexByProject.set(projectPath, index);
+  return index;
 }
 
 /**
- * Get the context attribution message
+ * Extract routes using Route Truth v1 (AST-based).
+ * - Fastify: follows register() prefixes, resolves relative plugin imports
+ * - Next.js: App Router (route.ts exports) + Pages Router (/pages/api/**)
+ * - Proper path canonicalization (dynamic segments, splats)
  */
-export function getContextAttribution() {
-  return CONTEXT_ATTRIBUTION;
-}
+async function extractRoutes(projectPath, refresh = false) {
+  const index = await getRouteIndex(projectPath, refresh);
+  const routeMap = index.getRouteMap();
+
+  // Transform to truthpack format
+  const routes = (routeMap.server || []).map((r) => ({
+    method: r.method,
+    path: r.path,
+    file: r.handler,
+    line: r.evidence?.[0]?.lines?.split("-")[0] || 1,
+    framework: r.framework,
+    routerType: r.routerType,
+    confidence: r.confidence === "high" ? 0.95 : r.confidence === "med" ? 0.8 : 0.6,
+    evidence: r.evidence,
+  }));
+
+  const gaps = routeMap.gaps || [];
+  const hasGaps = gaps.length > 0;
 
-async function extractRoutes(projectPath) {
-  const routes = [];
-  const files = await findSourceFiles(projectPath);
-  const routePatterns = [
-    /\.(get|post|put|patch|delete)\s*\(\s*['"`]([^'"`]+)['"`]/gi,
-    /router\.(get|post|put|patch|delete)\s*\(\s*['"`]([^'"`]+)['"`]/gi,
-  ];
-  
-  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,
-          });
-        }
-      }
-    } catch {}
-  }
-  
-  return { count: routes.length, routes, confidence: routes.length > 0 ? 0.8 : 0.2 };
+  return {
+    count: routes.length,
+    routes,
+    gaps,
+    confidence: hasGaps ? 0.7 : (routes.length > 0 ? 0.95 : 0.3),
+    engine: "route-truth-v1",
+    _note: hasGaps
+      ? `⚠️ ${gaps.length} unresolved plugins/modules - some routes may be missing`
+      : "AST-based extraction (Fastify register prefixes + Next.js app/pages)",
+  };
 }
 
 async function extractAuth(projectPath) {
-  const evidence = await searchEvidence(projectPath, { 
-    query: 'auth|authenticate|authorize|middleware|guard|jwt|session', 
-    limit: 30 
-  });
-  return { count: evidence.count, indicators: evidence.results, confidence: evidence.count > 5 ? 0.8 : 0.4 };
+  // TODO: parse Next middleware matcher for real; this is evidence-based heuristics
+  const evidence = await searchEvidence(projectPath, { query: "middleware|auth|authenticate|authorize|jwt|session", mode: "regex", limit: 30 });
+  return {
+    count: evidence.count,
+    indicators: evidence.results,
+    nextMatcherPatterns: [],
+    confidence: evidence.count > 5 ? 0.8 : 0.4,
+  };
 }
 
 async function extractBilling(projectPath) {
-  const evidence = await searchEvidence(projectPath, { 
-    query: 'stripe|billing|payment|subscription|checkout|tier|isPro', 
-    limit: 20 
-  });
-  return { count: evidence.count, indicators: evidence.results, confidence: evidence.count > 3 ? 0.7 : 0.3 };
+  const evidence = await searchEvidence(projectPath, { query: "stripe|billing|payment|subscription|checkout|tier|isPro", mode: "regex", limit: 25 });
+  return { count: evidence.count, indicators: evidence.results, confidence: evidence.count > 3 ? 0.75 : 0.3 };
 }
 
 async function extractEnv(projectPath) {
   const declared = [];
   const used = [];
-  
-  // Check .env.example
+
+  // .env.example declarations
   try {
-    const content = await fs.readFile(path.join(projectPath, '.env.example'), 'utf8');
-    const lines = content.split('\n');
+    const content = await safeReadFile(projectPath, ".env.example");
+    const lines = content.split(/\r?\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], line: i + 1 });
+      const m = lines[i].match(/^([A-Z][A-Z0-9_]*)=/);
+      if (m) declared.push({ name: m[1], line: i + 1 });
     }
-  } catch {}
-  
-  // Check process.env usage
-  const evidence = await searchEvidence(projectPath, { query: 'process\\.env\\.([A-Z][A-Z0-9_]*)', limit: 50 });
-  for (const ev of evidence.results) {
-    const match = ev.snippet.match(/process\.env\.([A-Z][A-Z0-9_]*)/);
-    if (match) used.push({ name: match[1], file: ev.file, line: ev.line });
+  } catch { /* ignore */ }
+
+  // usage
+  const usage = await searchEvidence(projectPath, { query: "process\\.env\\.([A-Z][A-Z0-9_]*)", mode: "regex", limit: 200, includeTests: false });
+  for (const ev of usage.results) {
+    const m = ev.snippet.match(/process\.env\.([A-Z][A-Z0-9_]*)/);
+    if (m) used.push({ name: m[1], file: ev.file, line: ev.line });
   }
-  
-  const declaredNames = new Set(declared.map(d => d.name));
-  const usedNames = new Set(used.map(u => u.name));
-  
+
+  const declaredNames = new Set(declared.map((d) => d.name));
+  const usedNames = new Set(used.map((u) => u.name));
+
   return {
     declared,
     used,
     mismatches: {
-      undeclared: Array.from(usedNames).filter(n => !declaredNames.has(n)),
-      unused: Array.from(declaredNames).filter(n => !usedNames.has(n)),
+      undeclared: Array.from(usedNames).filter((n) => !declaredNames.has(n)),
+      unused: Array.from(declaredNames).filter((n) => !usedNames.has(n)),
     },
     confidence: 0.8,
   };
@@ -1500,178 +1860,184 @@ async function extractEnv(projectPath) {
 
 async function extractSchema(projectPath) {
   const schemas = [];
-  
-  // Check Prisma
   try {
-    const content = await fs.readFile(path.join(projectPath, 'prisma', 'schema.prisma'), 'utf8');
+    const content = await safeReadFile(projectPath, "prisma/schema.prisma");
     const models = content.matchAll(/model\s+(\w+)\s*\{/g);
-    for (const match of models) {
-      schemas.push({ type: 'prisma_model', name: match[1] });
-    }
-  } catch {}
-  
+    for (const m of models) schemas.push({ type: "prisma_model", name: m[1] });
+  } catch { /* ignore */ }
   return { count: schemas.length, schemas, confidence: schemas.length > 0 ? 0.9 : 0.3 };
 }
 
-async function extractGraph(projectPath) {
-  return { nodes: [], edges: [], message: 'Graph extraction requires full build. Use get_truthpack with refresh=true.' };
+async function extractGraph(_projectPath) {
+  return { nodes: [], edges: [], message: "Graph extraction not implemented in this module." };
 }
 
-async function verifyRouteExists(projectPath, subject) {
-  const routes = await extractRoutes(projectPath);
-  const match = routes.routes.find(r => 
-    r.path === subject.path || 
-    (subject.method && r.method === subject.method.toUpperCase() && r.path === subject.path)
-  );
-  
-  if (match) {
+// =============================================================================
+// CLAIM VERIFIERS (tightened)
+// =============================================================================
+
+/**
+ * Verify route_exists claim using Route Truth v1 index.
+ * This uses proper AST-based route detection with:
+ * - Fastify register() prefix resolution
+ * - Next.js App/Pages router support
+ * - Parameterized path matching (:id, *slug)
+ * - Closest route suggestions on miss
+ */
+async function verifyRouteExists(projectPath, subject, refresh = false) {
+  const index = await getRouteIndex(projectPath, refresh);
+
+  const claim = {
+    method: subject?.method || "*",
+    path: subject?.path,
+  };
+
+  // Use Route Truth v1 validation (handles parameterized matching, gaps, etc.)
+  const result = await routeTruthValidate(claim, projectPath, index);
+
+  if (result.result === "true") {
+    const matched = result.matchedRoute;
     return {
-      result: 'true',
-      confidence: 'high',
-      evidence: [{ file: match.file, lines: `${match.line}`, hash: '' }],
+      result: "true",
+      confidence: result.confidence === "high" ? "high" : result.confidence === "med" ? "medium" : "low",
+      evidence: (matched?.evidence || []).map((e) => ({
+        file: e.file,
+        lines: e.lines,
+        snippet: "",
+        hash: e.snippetHash || sha16(`${e.file}:${e.lines}`),
+      })),
+      matchedRoute: {
+        method: matched?.method,
+        path: matched?.path,
+        file: matched?.handler,
+        framework: matched?.framework,
+      },
     };
   }
-  
-  return { result: 'false', confidence: 'high', evidence: [], nextSteps: ['Route not found in codebase'] };
+
+  if (result.result === "unknown") {
+    // Has gaps (unresolved plugins) - can't be certain
+    return {
+      result: "unknown",
+      confidence: "low",
+      evidence: [],
+      gaps: result.gaps,
+      closestRoutes: (result.closestRoutes || []).map((r) => ({
+        method: r.method,
+        path: r.path,
+        file: r.handler,
+      })),
+      nextSteps: result.nextSteps || [
+        "Some plugins/modules could not be resolved",
+        "Route may exist but extractor couldn't follow import chain",
+      ],
+    };
+  }
+
+  // result === "false" - route definitely doesn't exist
+  const closest = (result.closestRoutes || []).map((r) => ({
+    method: r.method,
+    path: r.path,
+    file: r.handler,
+  }));
+
+  return {
+    result: "false",
+    confidence: "high",
+    evidence: [],
+    closestRoutes: closest,
+    nextSteps: result.nextSteps || (closest.length
+      ? [`Route not found. Did you mean: ${closest.map((r) => `${r.method} ${r.path}`).join(", ")}?`]
+      : ["Route not found. No similar routes detected."]),
+  };
 }
 
 async function verifyFileExists(projectPath, subject) {
-  const filePath = path.join(projectPath, subject.path || subject.name);
+  const rel = String(subject?.path || subject?.name || "");
+  if (!rel) return { result: "unknown", confidence: "low", evidence: [], nextSteps: ["Missing subject.path"] };
   try {
-    await fs.access(filePath);
-    return { result: 'true', confidence: 'high', evidence: [{ file: subject.path || subject.name, lines: '1', hash: '' }] };
+    const abs = safeProjectJoin(projectPath, rel);
+    await fs.access(abs);
+    return { result: "true", confidence: "high", evidence: [{ file: rel, lines: "1", hash: sha16(rel) }] };
   } catch {
-    return { result: 'false', confidence: 'high', evidence: [] };
+    return { result: "false", confidence: "high", evidence: [] };
   }
 }
 
 async function verifyEnvVar(projectPath, subject, claim) {
   const env = await extractEnv(projectPath);
-  const name = subject.name;
-  
-  const isDeclared = env.declared.some(d => d.name === name);
-  const isUsed = env.used.some(u => u.name === name);
-  
-  if (claim === 'env_var_exists') {
-    return {
-      result: isDeclared ? 'true' : 'unknown',
-      confidence: isDeclared ? 'high' : 'low',
-      evidence: isDeclared ? [{ file: '.env.example', lines: '1', hash: '' }] : [],
-    };
-  } else {
-    return {
-      result: isUsed ? 'true' : 'false',
-      confidence: 'high',
-      evidence: env.used.filter(u => u.name === name).map(u => ({ file: u.file, lines: `${u.line}`, hash: '' })),
-    };
+  const name = String(subject?.name || "");
+  if (!name) return { result: "unknown", confidence: "low", evidence: [], nextSteps: ["Missing subject.name"] };
+
+  const declared = env.declared?.find((d) => d.name === name);
+  const used = (env.used || []).filter((u) => u.name === name);
+
+  if (claim === "env_var_exists") {
+    if (declared) {
+      return { result: "true", confidence: "high", evidence: [{ file: ".env.example", lines: `${declared.line}`, hash: sha16(`${name}:${declared.line}`) }] };
+    }
+    // "exists" might be in real env, but contract says no -> unknown
+    return { result: "unknown", confidence: "low", evidence: [], nextSteps: ["Not declared in .env.example / contract"] };
   }
-}
 
-async function verifyRouteGuarded(projectPath, subject) {
-  const routePath = subject.path;
-  const evidence = await searchEvidence(projectPath, { query: `${routePath}.*auth|middleware.*${routePath}`, limit: 5 });
-  
-  if (evidence.count > 0) {
+  // env_var_used
+  if (used.length > 0) {
     return {
-      result: 'true',
-      confidence: 'medium',
-      evidence: evidence.results.map(e => ({ file: e.file, lines: `${e.line}`, hash: e.hash })),
+      result: "true",
+      confidence: "high",
+      evidence: used.map((u) => ({ file: u.file, lines: `${u.line}`, hash: sha16(`${u.file}:${u.line}:${name}`) })),
     };
   }
-  
-  return { result: 'unknown', confidence: 'low', evidence: [], nextSteps: ['Could not find auth guards for this route'] };
+
+  return { result: "false", confidence: "high", evidence: [] };
 }
 
-async function verifyEntityExists(projectPath, subject, claim) {
-  const name = subject.name;
-  const evidence = await searchEvidence(projectPath, { query: name, limit: 5 });
-  
+async function verifyRouteGuarded(projectPath, subject) {
+  const routePath = canonicalizePath(String(subject?.path || ""));
+  if (!routePath) return { result: "unknown", confidence: "low", evidence: [], nextSteps: ["Missing subject.path"] };
+
+  // heuristic: route mentioned near middleware/auth patterns
+  const evidence = await searchEvidence(projectPath, {
+    query: String.raw`(middleware|auth|authorize|session).*(\Q${routePath}\E)|\Q${routePath}\E.*(middleware|auth|authorize|session)`.replace(/\Q|\E/g, ""),
+    mode: "regex",
+    limit: 10,
+  });
+
   if (evidence.count > 0) {
     return {
-      result: 'true',
-      confidence: 'medium',
-      evidence: evidence.results.map(e => ({ file: e.file, lines: `${e.line}`, hash: e.hash })),
+      result: "true",
+      confidence: "med",
+      evidence: evidence.results.map((e) => ({ file: e.file, lines: `${e.line}`, hash: e.hash, snippet: e.snippet })),
     };
   }
-  
-  return { result: 'unknown', confidence: 'low', evidence: [] };
-}
-
-function filterTruthPack(pack, scope) {
-  if (scope === 'all') return pack;
-  return {
-    ...pack,
-    sections: { [scope]: pack.sections[scope] },
-  };
-}
 
-function detectDomains(task) {
-  const domains = [];
-  if (/auth|login|logout|session|password/i.test(task)) domains.push('auth');
-  if (/billing|payment|stripe|subscription/i.test(task)) domains.push('billing');
-  if (/route|api|endpoint/i.test(task)) domains.push('api');
-  if (/component|button|ui|form/i.test(task)) domains.push('ui');
-  return domains.length > 0 ? domains : ['general'];
+  return { result: "unknown", confidence: "low", evidence: [], nextSteps: ["No guard evidence found (may still exist; extractor is heuristic)"] };
 }
 
-function extractKeywords(task) {
-  return task.toLowerCase().replace(/[^a-z0-9\s]/g, ' ').split(/\s+/).filter(w => w.length > 2);
-}
+async function verifyEntityExists(projectPath, subject, _claim) {
+  const name = String(subject?.name || "");
+  if (!name) return { result: "unknown", confidence: "low", evidence: [], nextSteps: ["Missing subject.name"] };
 
-function getInvariantsForDomains(domains) {
-  const invariants = [];
-  if (domains.includes('auth')) {
-    invariants.push('No protected route without server middleware');
-  }
-  if (domains.includes('billing')) {
-    invariants.push('No paid feature without server-side enforcement');
+  const evidence = await searchEvidence(projectPath, { query: name, mode: "text", limit: 8 });
+  if (evidence.count > 0) {
+    return {
+      result: "true",
+      confidence: "med",
+      evidence: evidence.results.map((e) => ({ file: e.file, lines: `${e.line}`, hash: e.hash, snippet: e.snippet })),
+    };
   }
-  invariants.push('No success UI without confirmed success');
-  return invariants;
-}
 
-function estimateTokens(context) {
-  let tokens = 0;
-  if (context.relevantRoutes) tokens += context.relevantRoutes.length * 50;
-  if (context.relevantAuth) tokens += 200;
-  if (context.relevantBilling) tokens += 200;
-  return tokens;
+  return { result: "unknown", confidence: "low", evidence: [] };
 }
 
-function generateContextWarnings(domains, policy, routeCount) {
-  const warnings = [];
-  if (domains.includes('auth') || domains.includes('billing')) {
-    warnings.push('High-stakes domain - verify all claims before changes');
-  }
-  if (routeCount > 20 && policy === 'strict') {
-    warnings.push('Large context - consider narrowing scope');
-  }
-  return warnings;
-}
+// =============================================================================
+// EXPORTS
+// =============================================================================
 
-async function findSourceFiles(projectPath) {
-  const files = [];
-  const ignoreDirs = ['node_modules', 'dist', 'build', '.git', '.next', 'coverage'];
-  
-  async function walk(dir) {
-    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 (!ignoreDirs.includes(entry.name) && !entry.name.startsWith('.')) {
-            await walk(fullPath);
-          }
-        } else if (entry.isFile() && /\.(ts|tsx|js|jsx)$/.test(entry.name)) {
-          files.push(fullPath);
-        }
-      }
-    } catch {}
-  }
-  
-  await walk(projectPath);
-  return files;
-}
+export {
+  getRouteIndex,      // Route Truth v1 index - single source of truth for routes
+  extractRoutes,      // Route extraction via Route Truth v1
+};
 
 export default {
   TRUTH_FIREWALL_TOOLS,
@@ -1682,5 +2048,6 @@ export default {
   getProjectFingerprint,
   wrapMcpResponse,
   getContextAttribution,
+  getRouteIndex,      // Also on default export
   CONTEXT_ATTRIBUTION,
 };