@vibecheckai/cli 3.0.4 → 3.0.7

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

@@ -0,0 +1,1500 @@
+/**
+ * Truth Firewall MCP Tools
+ * 
+ * The "best-in-world" hallucination stopper toolkit.
+ * Agents cannot work without these tools - they enforce truth.
+ * 
+ * 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
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import crypto from 'crypto';
+import { execSync } from 'child_process';
+
+// =============================================================================
+// TOOL DEFINITIONS
+// =============================================================================
+
+export const TRUTH_FIREWALL_TOOLS = [
+  {
+    name: "vibecheck.get_truthpack",
+    description: `📦 Get the Truth Pack — the 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.
+
+⚠️ CRITICAL: Use this BEFORE making any assertions about the codebase.`,
+    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,
+        },
+      },
+    },
+  },
+  
+  {
+    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
+
+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",
+      properties: {
+        claim: {
+          type: "string",
+          enum: [
+            "route_exists",
+            "route_guarded", 
+            "env_var_exists",
+            "env_var_used",
+            "middleware_applied",
+            "auth_enforced",
+            "billing_gate_exists",
+            "file_exists",
+            "function_exists",
+            "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" },
+          },
+        },
+        expected: {
+          type: "boolean",
+          description: "Expected result (default: true)",
+          default: true,
+        },
+      },
+      required: ["claim", "subject"],
+    },
+  },
+  
+  {
+    name: "vibecheck.compile_context",
+    description: `🎯 Get task-targeted context — minimal sufficient context for your task.
+
+Big context = noise. Small context = missing facts.
+This compiles exactly what you need for the task.
+
+Returns relevant nodes, edges, evidence, and applicable 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",
+        },
+      },
+      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.`,
+    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,
+        },
+      },
+      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.
+
+Use this for high-stakes claims about auth, billing, security.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        claim: {
+          type: "string",
+          enum: ["auth_enforced", "billing_gate_exists", "route_guarded", "no_bypass"],
+          description: "Claim to falsify",
+        },
+        subject: {
+          type: "object",
+          description: "What the claim is about",
+          properties: {
+            path: { type: "string" },
+            name: { type: "string" },
+          },
+        },
+      },
+      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 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')",
+        },
+      },
+      required: ["diff", "fixes"],
+    },
+  },
+  
+  {
+    name: "vibecheck.check_invariants",
+    description: `⚖️ Check all invariants (product religion rules).
+
+Returns:
+- Ship killers: BLOCK deployment
+- Warnings: Require acknowledgment
+
+Invariants include:
+- No paid feature without server-side enforcement
+- No success UI without confirmed success
+- No route reference without matching route map entry
+- No silent catch in auth/billing flows`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        category: {
+          type: "string",
+          enum: ["all", "auth", "billing", "security", "ux", "api"],
+          description: "Category to check (default: all)",
+          default: "all",
+        },
+      },
+    },
+  },
+  
+  {
+    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`,
+    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",
+        },
+      },
+      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" }
+
+Returns: { valid: boolean, violations: [], warnings: [], suggestions: [] }`,
+    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,
+        },
+      },
+      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)`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        category: {
+          type: "string",
+          enum: ["all", "routes", "env", "auth", "external"],
+          description: "Category to check (default: all)",
+          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/`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: {
+          type: "string",
+          enum: ["all", "routes", "env", "auth", "external"],
+          description: "Which contract to get (default: all)",
+          default: "all",
+        },
+      },
+    },
+  },
+];
+
+// =============================================================================
+// TOOL HANDLERS
+// =============================================================================
+
+export async function handleTruthFirewallTool(toolName, args, projectPath = process.cwd()) {
+  switch (toolName) {
+    case "vibecheck.get_truthpack":
+      return await getTruthPack(projectPath, args);
+      
+    case "vibecheck.validate_claim":
+      return await validateClaim(projectPath, args);
+      
+    case "vibecheck.compile_context":
+      return await compileContext(projectPath, args);
+      
+    case "vibecheck.search_evidence":
+      return await searchEvidence(projectPath, args);
+      
+    case "vibecheck.find_counterexamples":
+      return await findCounterexamples(projectPath, args);
+      
+    case "vibecheck.propose_patch":
+      return await proposePatch(projectPath, args);
+      
+    case "vibecheck.check_invariants":
+      return await checkInvariants(projectPath, args);
+      
+    case "vibecheck.add_assumption":
+      return await addAssumption(projectPath, args);
+      
+    case "vibecheck.validate_plan":
+      return await validatePlanTool(projectPath, args);
+      
+    case "vibecheck.check_drift":
+      return await checkDriftTool(projectPath, args);
+      
+    case "vibecheck.get_contracts":
+      return await getContractsTool(projectPath, args);
+      
+    default:
+      return { error: `Unknown tool: ${toolName}` };
+  }
+}
+
+// =============================================================================
+// IMPLEMENTATION
+// =============================================================================
+
+// In-memory state
+const state = {
+  truthPack: null,
+  assumptions: [],
+  verifiedClaims: new Map(),
+  maxAssumptions: 2,
+};
+
+async function getTruthPack(projectPath, args) {
+  const scope = args.scope || 'all';
+  const refresh = args.refresh || false;
+  
+  if (state.truthPack && !refresh) {
+    return filterTruthPack(state.truthPack, scope);
+  }
+  
+  // Build truth pack
+  const truthPack = {
+    version: '1.0.0',
+    generatedAt: new Date().toISOString(),
+    projectPath,
+    commitHash: getCommitHash(projectPath),
+    sections: {},
+    confidence: 0,
+  };
+  
+  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
+  const sections = Object.values(truthPack.sections);
+  truthPack.confidence = sections.reduce((sum, s) => sum + (s.confidence || 0), 0) / sections.length;
+  
+  state.truthPack = truthPack;
+  return truthPack;
+}
+
+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 };
+    }
+  }
+  
+  let result = { result: 'unknown', confidence: 'low', evidence: [], nextSteps: [] };
+  
+  try {
+    switch (claim) {
+      case 'route_exists':
+        result = await verifyRouteExists(projectPath, subject);
+        break;
+      case 'file_exists':
+        result = await verifyFileExists(projectPath, subject);
+        break;
+      case 'env_var_exists':
+      case 'env_var_used':
+        result = await verifyEnvVar(projectPath, subject, claim);
+        break;
+      case 'auth_enforced':
+      case 'route_guarded':
+        result = await verifyRouteGuarded(projectPath, subject);
+        break;
+      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.`];
+    }
+  } catch (error) {
+    result.nextSteps = [`Verification error: ${error.message}`];
+  }
+  
+  // If unknown, add helpful next steps
+  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.';
+  }
+  
+  // Cache result
+  state.verifiedClaims.set(claimId, { result, timestamp: Date.now() });
+  
+  return {
+    claimId,
+    ...result,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+async function compileContext(projectPath, args) {
+  const { task, files = [], policy = 'balanced' } = args;
+  
+  // Analyze task to determine relevant domains
+  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 invariants = getInvariantsForDomains(domains);
+  
+  // Estimate token count
+  const tokenCount = estimateTokens({ relevantRoutes, relevantAuth, relevantBilling });
+  
+  return {
+    task,
+    policy,
+    domains,
+    context: {
+      routes: relevantRoutes.slice(0, policy === 'strict' ? 10 : 50),
+      auth: relevantAuth,
+      billing: relevantBilling,
+    },
+    invariants,
+    tokenCount,
+    warnings: generateContextWarnings(domains, policy, relevantRoutes.length),
+  };
+}
+
+async function searchEvidence(projectPath, args) {
+  const { query, type = 'any', limit = 10 } = args;
+  const results = [];
+  
+  const files = await findSourceFiles(projectPath);
+  const pattern = new RegExp(query, 'gi');
+  
+  for (const file of files.slice(0, 100)) {
+    try {
+      const content = await fs.readFile(file, 'utf8');
+      const lines = content.split('\n');
+      const relPath = path.relative(projectPath, file);
+      
+      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');
+          results.push({
+            file: relPath,
+            line: i + 1,
+            snippet: snippet.slice(0, 300),
+            hash: crypto.createHash('sha256').update(lines[i]).digest('hex').slice(0, 16),
+          });
+          
+          if (results.length >= limit) break;
+        }
+        pattern.lastIndex = 0;
+      }
+      
+      if (results.length >= limit) break;
+    } catch {}
+  }
+  
+  return {
+    query,
+    count: results.length,
+    results,
+  };
+}
+
+async function findCounterexamples(projectPath, args) {
+  const { claim, subject } = args;
+  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',
+          });
+        }
+      }
+      break;
+  }
+  
+  return {
+    claim,
+    subject,
+    counterexamples,
+    claimDemoted: counterexamples.length > 0,
+  };
+}
+
+async function proposePatch(projectPath, args) {
+  const { diff, fixes, claims = [], verification = [] } = args;
+  
+  // Validate all dependent claims
+  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 });
+    }
+  }
+  
+  const allClaimsValid = claimValidation.every(c => c.valid);
+  
+  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'],
+    createdAt: new Date().toISOString(),
+    eligible: allClaimsValid && fixes.length > 0,
+    claimValidation,
+  };
+  
+  if (!patch.eligible) {
+    patch.blockers = claimValidation.filter(c => !c.valid);
+    patch.message = '⚠️ Patch NOT eligible for auto-apply. Fix blockers first.';
+  }
+  
+  return patch;
+}
+
+async function checkInvariants(projectPath, args) {
+  const category = args.category || 'all';
+  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 
+  });
+  
+  for (const ev of silentCatches.results) {
+    if (ev.file.includes('auth') || ev.file.includes('billing') || ev.file.includes('middleware')) {
+      shipKillers.push({
+        invariant: 'security_no_silent_catch',
+        rule: 'No silent catch in auth/billing flows',
+        evidence: ev,
+      });
+    }
+  }
+  
+  // Check for hardcoded secrets
+  const secrets = await searchEvidence(projectPath, {
+    query: 'sk_live_|sk_test_|apiKey.*=.*["\'][a-zA-Z0-9]{20,}',
+    limit: 10,
+  });
+  
+  for (const ev of secrets.results) {
+    if (!ev.file.includes('.test.') && !ev.file.includes('.example')) {
+      shipKillers.push({
+        invariant: 'security_no_exposed_secrets',
+        rule: 'No hardcoded secrets or API keys',
+        evidence: ev,
+      });
+    }
+  }
+  
+  return {
+    passed: shipKillers.length === 0,
+    shipKillers,
+    warnings,
+    summary: shipKillers.length === 0 
+      ? '✅ All invariants pass'
+      : `❌ ${shipKillers.length} ship killers found - deployment blocked`,
+  };
+}
+
+async function addAssumption(projectPath, args) {
+  const { description, reason, verificationSteps } = args;
+  
+  if (state.assumptions.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,
+    };
+  }
+  
+  const assumption = {
+    id: `assumption_${Date.now()}`,
+    description,
+    reason,
+    verificationSteps,
+    madeAt: new Date().toISOString(),
+    verified: false,
+  };
+  
+  state.assumptions.push(assumption);
+  
+  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,
+  };
+}
+
+// =============================================================================
+// PLAN VALIDATION & DRIFT DETECTION (Spec 10.3)
+// =============================================================================
+
+async function validatePlanTool(projectPath, args) {
+  const { plan, strict = false } = args;
+  
+  // Load contracts
+  const contracts = await loadContractsFromDisk(projectPath);
+  
+  if (!contracts || Object.keys(contracts).length === 0) {
+    return {
+      valid: true,
+      warning: 'No contracts found. Run "vibecheck ctx sync" to generate contracts.',
+      violations: [],
+      warnings: [],
+      suggestions: ['Generate contracts with: vibecheck ctx sync'],
+    };
+  }
+  
+  // Parse plan to extract actions
+  const actions = parsePlanActions(plan);
+  const violations = [];
+  const warnings = [];
+  const suggestions = [];
+  
+  // Validate route references
+  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',
+        });
+      }
+    }
+  }
+  
+  // Validate auth assumptions
+  if (contracts.auth && actions.authAssumptions.length > 0) {
+    for (const assumption of actions.authAssumptions) {
+      if (assumption.type === 'no_auth') {
+        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(', ')}...`,
+        });
+      }
+    }
+  }
+  
+  // Validate external service usage
+  if (contracts.external && actions.externalCalls.length > 0) {
+    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',
+          service: call.service,
+          message: `Plan uses ${call.service} which is not declared in external contract`,
+          suggestion: 'Add to .vibecheck/contracts/external.json',
+        });
+      }
+    }
+  }
+  
+  const valid = violations.length === 0 && (!strict || warnings.length === 0);
+  
+  return {
+    valid,
+    violations,
+    warnings,
+    suggestions,
+    parsedActions: actions,
+    contractsLoaded: Object.keys(contracts),
+    message: valid 
+      ? '✅ Plan validated against contracts'
+      : `❌ Plan validation failed: ${violations.length} violations, ${warnings.length} warnings`,
+  };
+}
+
+async function checkDriftTool(projectPath, args) {
+  const category = args.category || 'all';
+  
+  // Load contracts
+  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: [],
+    };
+  }
+  
+  // 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');
+  
+  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,
+    },
+    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.`,
+  };
+}
+
+async function getContractsTool(projectPath, args) {
+  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: {},
+    };
+  }
+  
+  if (type === 'all') {
+    return {
+      found: true,
+      contracts,
+      summary: {
+        routes: contracts.routes?.routes?.length || 0,
+        envVars: contracts.env?.vars?.length || 0,
+        authPatterns: contracts.auth?.protectedPatterns?.length || 0,
+        services: contracts.external?.services?.length || 0,
+      },
+    };
+  }
+  
+  return {
+    found: !!contracts[type],
+    contracts: { [type]: contracts[type] },
+  };
+}
+
+// Helper: Load contracts from disk
+async function loadContractsFromDisk(projectPath) {
+  const contractDir = path.join(projectPath, '.vibecheck', 'contracts');
+  const contracts = {};
+  
+  const files = {
+    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');
+      contracts[key] = JSON.parse(content);
+    } catch {}
+  }
+  
+  return contracts;
+}
+
+// Helper: Parse plan to extract actions
+function parsePlanActions(plan) {
+  const actions = {
+    routes: [],
+    envVars: [],
+    files: [],
+    authAssumptions: [],
+    externalCalls: [],
+  };
+  
+  const planText = typeof plan === 'string' ? plan : JSON.stringify(plan);
+  
+  // Extract route references
+  const routePatterns = [
+    /(?:fetch|axios|api\.?)\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]),
+        });
+      }
+    }
+  }
+  
+  // Extract env var references
+  const envPatterns = [
+    /process\.env\.([A-Z_][A-Z0-9_]*)/gi,
+    /import\.meta\.env\.([A-Z_][A-Z0-9_]*)/gi,
+  ];
+  
+  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' });
+  }
+  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' },
+  ];
+  
+  for (const { pattern, service } of servicePatterns) {
+    if (pattern.test(planText)) {
+      actions.externalCalls.push({ 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';
+}
+
+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;
+  }
+  return true;
+}
+
+// Helper: Build current truthpack (lightweight version)
+async function buildCurrentTruthpack(projectPath) {
+  const routes = await extractRoutes(projectPath);
+  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
+    },
+  };
+}
+
+// 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)) {
+      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.',
+      });
+    }
+  }
+  
+  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)) {
+      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.',
+      });
+    }
+  }
+  
+  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)) {
+      findings.push({
+        type: 'new_auth_pattern',
+        severity: 'BLOCK',
+        title: `New auth pattern "${pattern}" not in contract`,
+        message: 'Auth pattern added but not in contracts.',
+      });
+    }
+  }
+  
+  return findings;
+}
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+function getCommitHash(projectPath) {
+  try {
+    return execSync('git rev-parse HEAD', { cwd: projectPath, encoding: 'utf8' }).trim();
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * 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) {
+    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 {}
+  }
+  
+  const fingerprintData = [
+    commitHash,
+    ...fileHashes,
+  ].join('|');
+  
+  return {
+    hash: crypto.createHash('sha256').update(fingerprintData).digest('hex').slice(0, 16),
+    commitHash,
+    fileHashes,
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Wrap MCP response with standard metadata including fingerprint (Spec 10.2)
+ */
+export function wrapMcpResponse(data, projectPath) {
+  return {
+    ok: true,
+    version: '2.0.0',
+    projectFingerprint: getProjectFingerprint(projectPath),
+    data,
+  };
+}
+
+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 };
+}
+
+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 };
+}
+
+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 };
+}
+
+async function extractEnv(projectPath) {
+  const declared = [];
+  const used = [];
+  
+  // Check .env.example
+  try {
+    const content = await fs.readFile(path.join(projectPath, '.env.example'), 'utf8');
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const match = lines[i].match(/^([A-Z][A-Z0-9_]*)=/);
+      if (match) declared.push({ name: match[1], 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 });
+  }
+  
+  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)),
+    },
+    confidence: 0.8,
+  };
+}
+
+async function extractSchema(projectPath) {
+  const schemas = [];
+  
+  // Check Prisma
+  try {
+    const content = await fs.readFile(path.join(projectPath, 'prisma', 'schema.prisma'), 'utf8');
+    const models = content.matchAll(/model\s+(\w+)\s*\{/g);
+    for (const match of models) {
+      schemas.push({ type: 'prisma_model', name: match[1] });
+    }
+  } catch {}
+  
+  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 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) {
+    return {
+      result: 'true',
+      confidence: 'high',
+      evidence: [{ file: match.file, lines: `${match.line}`, hash: '' }],
+    };
+  }
+  
+  return { result: 'false', confidence: 'high', evidence: [], nextSteps: ['Route not found in codebase'] };
+}
+
+async function verifyFileExists(projectPath, subject) {
+  const filePath = path.join(projectPath, subject.path || subject.name);
+  try {
+    await fs.access(filePath);
+    return { result: 'true', confidence: 'high', evidence: [{ file: subject.path || subject.name, lines: '1', hash: '' }] };
+  } catch {
+    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: '' })),
+    };
+  }
+}
+
+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) {
+    return {
+      result: 'true',
+      confidence: 'medium',
+      evidence: evidence.results.map(e => ({ file: e.file, lines: `${e.line}`, hash: e.hash })),
+    };
+  }
+  
+  return { result: 'unknown', confidence: 'low', evidence: [], nextSteps: ['Could not find auth guards for this route'] };
+}
+
+async function verifyEntityExists(projectPath, subject, claim) {
+  const name = subject.name;
+  const evidence = await searchEvidence(projectPath, { query: name, limit: 5 });
+  
+  if (evidence.count > 0) {
+    return {
+      result: 'true',
+      confidence: 'medium',
+      evidence: evidence.results.map(e => ({ file: e.file, lines: `${e.line}`, hash: e.hash })),
+    };
+  }
+  
+  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'];
+}
+
+function extractKeywords(task) {
+  return task.toLowerCase().replace(/[^a-z0-9\s]/g, ' ').split(/\s+/).filter(w => w.length > 2);
+}
+
+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');
+  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;
+}
+
+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;
+}
+
+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 default {
+  TRUTH_FIREWALL_TOOLS,
+  handleTruthFirewallTool,
+};