@vibecheckai/cli 3.2.5 → 3.3.0

package/bin/runners/lib/drift.js

@@ -1,425 +1,425 @@
-/**
- * Contract Drift Detection
- * 
- * Detects when code has drifted from contracts (routes/env/auth/external).
- * Per spec: "routes/env/auth drift → usually BLOCK (because AI will lie here)"
- */
-
-"use strict";
-
-const path = require("path");
-const fs = require("fs");
-const crypto = require("crypto");
-const { createDriftFinding, migrateFindingToV2 } = require("./findings-schema");
-
-/**
- * Generate a stable fingerprint for a finding (for dedupe across runs)
- */
-function fingerprint(type, ...parts) {
-  const data = [type, ...parts].join("|");
-  return crypto.createHash("sha256").update(data).digest("hex").slice(0, 12);
-}
-
-/**
- * Find drift between contracts and current truthpack
- * Returns findings array with BLOCK/WARN severity based on category
- */
-function findContractDrift(contracts, truthpack, opts = {}) {
-  const findings = [];
-
-  // Route drift - BLOCK severity (AI can invent fake endpoints)
-  if (contracts?.routes && truthpack?.routes) {
-    const routeFindings = detectRouteDrift(contracts.routes, truthpack);
-    findings.push(...routeFindings);
-  }
-
-  // Env drift - BLOCK for required, WARN for optional
-  if (contracts?.env && truthpack?.env) {
-    const envFindings = detectEnvDrift(contracts.env, truthpack);
-    findings.push(...envFindings);
-  }
-
-  // Auth drift - BLOCK severity (security critical)
-  if (contracts?.auth && truthpack?.auth) {
-    const authFindings = detectAuthDrift(contracts.auth, truthpack);
-    findings.push(...authFindings);
-  }
-
-  // External drift - WARN severity (service changes)
-  if (contracts?.external) {
-    const externalFindings = detectExternalDrift(contracts.external, truthpack);
-    findings.push(...externalFindings);
-  }
-
-  return findings;
-}
-
-/**
- * Detect route drift: new routes not in contract, removed routes still in contract
- */
-function detectRouteDrift(routeContract, truthpack) {
-  const findings = [];
-  const contractRoutes = new Map();
-  
-  for (const r of routeContract.routes || []) {
-    const key = `${r.method}_${r.path}`;
-    contractRoutes.set(key, r);
-  }
-
-  const serverRoutes = truthpack?.routes?.server || [];
-  const currentRoutes = new Set();
-
-  // Check for new routes not in contract
-  for (const route of serverRoutes) {
-    const key = `${route.method}_${route.path}`;
-    currentRoutes.add(key);
-
-    if (!contractRoutes.has(key)) {
-      // Check parameterized match
-      const match = findParameterizedMatch(routeContract.routes, route.method, route.path);
-      if (!match) {
-        findings.push({
-          id: fingerprint("DRIFT_NEW_ROUTE", route.method, route.path),
-          category: "ContractDrift",
-          type: "new_route_not_in_contract",
-          severity: "BLOCK",
-          scope: "server",
-          title: `New route ${route.method} ${route.path} not declared in contract`,
-          message: `Route was added to code but not synced to contracts. AI agents cannot safely reference this route.`,
-          why: "Contracts are the source of truth. Undeclared routes can cause AI hallucinations.",
-          evidence: route.evidence || [],
-          fixHints: [
-            "Run 'vibecheck ctx sync' to update contracts",
-            "Or remove the route if unintended"
-          ],
-          fingerprint: fingerprint("DRIFT_NEW_ROUTE", route.method, route.path)
-        });
-      }
-    }
-  }
-
-  // Check for removed routes still in contract
-  for (const [key, contractRoute] of contractRoutes) {
-    if (!currentRoutes.has(key)) {
-      // Check if any current route matches parameterized
-      const stillExists = serverRoutes.some(r => 
-        matchesParameterized(contractRoute.path, r.path) && 
-        (contractRoute.method === "*" || contractRoute.method === r.method)
-      );
-
-      if (!stillExists) {
-        findings.push({
-          id: fingerprint("DRIFT_REMOVED_ROUTE", contractRoute.method, contractRoute.path),
-          category: "ContractDrift",
-          type: "route_removed_from_code",
-          severity: "BLOCK",
-          scope: "contracts",
-          title: `Route ${contractRoute.method} ${contractRoute.path} in contract but removed from code`,
-          message: `Contract declares a route that no longer exists. AI agents will reference a ghost endpoint.`,
-          why: "Stale contracts cause AI to generate code calling non-existent endpoints.",
-          evidence: contractRoute.evidence || [],
-          fixHints: [
-            "Run 'vibecheck ctx sync' to update contracts",
-            "Or restore the route if removal was unintended"
-          ],
-          fingerprint: fingerprint("DRIFT_REMOVED_ROUTE", contractRoute.method, contractRoute.path)
-        });
-      }
-    }
-  }
-
-  // Check for client refs not in contract (same as existing analyzer but with drift framing)
-  const clientRefs = truthpack?.routes?.clientRefs || [];
-  for (const ref of clientRefs) {
-    const key = `${ref.method}_${ref.path}`;
-    if (!contractRoutes.has(key)) {
-      const match = findParameterizedMatch(routeContract.routes, ref.method, ref.path);
-      if (!match) {
-        findings.push({
-          id: fingerprint("DRIFT_CLIENT_UNDECLARED", ref.method, ref.path),
-          category: "ContractDrift",
-          type: "client_refs_undeclared_route",
-          severity: "BLOCK",
-          scope: "client",
-          title: `Client calls ${ref.method} ${ref.path} which is not in contract`,
-          message: `Frontend references a route not declared in contracts. This will cause runtime errors.`,
-          why: "Client code should only call routes that exist in the contract.",
-          evidence: ref.evidence || [],
-          fixHints: [
-            "Create the missing route handler",
-            "Or update the client to use a valid route",
-            "Then run 'vibecheck ctx sync'"
-          ],
-          fingerprint: fingerprint("DRIFT_CLIENT_UNDECLARED", ref.method, ref.path)
-        });
-      }
-    }
-  }
-
-  return findings;
-}
-
-/**
- * Detect env drift: new vars not in contract, required vars removed
- */
-function detectEnvDrift(envContract, truthpack) {
-  const findings = [];
-  const contractVars = new Map();
-
-  for (const v of envContract.vars || []) {
-    contractVars.set(v.name, v);
-  }
-
-  const usedVars = truthpack?.env?.vars || [];
-  const currentVarNames = new Set(usedVars.map(v => v.name));
-
-  // Check for new env vars used but not in contract
-  for (const usedVar of usedVars) {
-    if (!contractVars.has(usedVar.name)) {
-      const isLikelyRequired = isRequiredEnvVar(usedVar.name);
-      findings.push({
-        id: fingerprint("DRIFT_NEW_ENV", usedVar.name),
-        category: "ContractDrift",
-        type: "new_env_not_in_contract",
-        severity: isLikelyRequired ? "BLOCK" : "WARN",
-        scope: "server",
-        title: `Env var ${usedVar.name} used but not in contract`,
-        message: `Code uses ${usedVar.name} but it's not declared in env contract.`,
-        why: "Undeclared env vars can cause deployment failures and AI confusion.",
-        evidence: usedVar.references || [],
-        fixHints: [
-          "Run 'vibecheck ctx sync' to update contracts",
-          `Add ${usedVar.name} to .env.example`
-        ],
-        fingerprint: fingerprint("DRIFT_NEW_ENV", usedVar.name)
-      });
-    }
-  }
-
-  // Check for required contract vars no longer used
-  for (const [name, spec] of contractVars) {
-    if (spec.required && !currentVarNames.has(name)) {
-      findings.push({
-        id: fingerprint("DRIFT_REMOVED_ENV", name),
-        category: "ContractDrift",
-        type: "required_env_removed",
-        severity: "WARN",
-        scope: "contracts",
-        title: `Required env var ${name} in contract but not used in code`,
-        message: `Contract marks ${name} as required but code no longer uses it.`,
-        why: "Stale env contracts cause confusion about what's actually needed.",
-        evidence: [],
-        fixHints: [
-          "Run 'vibecheck ctx sync' to update contracts",
-          "Or check if the var was accidentally removed from code"
-        ],
-        fingerprint: fingerprint("DRIFT_REMOVED_ENV", name)
-      });
-    }
-  }
-
-  return findings;
-}
-
-/**
- * Detect auth drift: protected patterns changed
- */
-function detectAuthDrift(authContract, truthpack) {
-  const findings = [];
-  const contractPatterns = new Set(authContract.protectedPatterns || []);
-  const currentPatterns = new Set(truthpack?.auth?.nextMatcherPatterns || []);
-
-  // New protected patterns not in contract
-  for (const pattern of currentPatterns) {
-    if (!contractPatterns.has(pattern)) {
-      findings.push({
-        id: fingerprint("DRIFT_NEW_AUTH", pattern),
-        category: "ContractDrift",
-        type: "new_auth_pattern",
-        severity: "BLOCK",
-        scope: "server",
-        title: `New auth pattern "${pattern}" not in contract`,
-        message: `Middleware protects a new pattern that isn't in the auth contract.`,
-        why: "Auth contracts define security boundaries. Undeclared patterns may not be properly tested.",
-        evidence: [],
-        fixHints: [
-          "Run 'vibecheck ctx sync' to update contracts",
-          "Verify the new pattern is intentional"
-        ],
-        fingerprint: fingerprint("DRIFT_NEW_AUTH", pattern)
-      });
-    }
-  }
-
-  // Protected patterns in contract but removed from code
-  for (const pattern of contractPatterns) {
-    if (!currentPatterns.has(pattern)) {
-      findings.push({
-        id: fingerprint("DRIFT_REMOVED_AUTH", pattern),
-        category: "ContractDrift",
-        type: "auth_pattern_removed",
-        severity: "BLOCK",
-        scope: "contracts",
-        title: `Auth pattern "${pattern}" in contract but removed from middleware`,
-        message: `Contract expects protection for "${pattern}" but middleware no longer enforces it.`,
-        why: "Removing auth patterns can expose protected routes. This is a security regression.",
-        evidence: [],
-        fixHints: [
-          "Restore the auth pattern in middleware if removal was unintended",
-          "Or run 'vibecheck ctx sync' to accept the change"
-        ],
-        fingerprint: fingerprint("DRIFT_REMOVED_AUTH", pattern)
-      });
-    }
-  }
-
-  return findings;
-}
-
-/**
- * Detect external service drift
- */
-function detectExternalDrift(externalContract, truthpack) {
-  const findings = [];
-  const contractServices = new Map();
-
-  for (const svc of externalContract.services || []) {
-    contractServices.set(svc.name, svc);
-  }
-
-  // Check Stripe webhook changes
-  const billing = truthpack?.billing || {};
-  if (contractServices.has("stripe")) {
-    const contractStripe = contractServices.get("stripe");
-    const currentWebhooks = billing.webhookCandidates || [];
-
-    // New webhook not in contract
-    for (const wh of currentWebhooks) {
-      const inContract = contractStripe.webhooks?.some(cw => cw.path === wh.path);
-      if (!inContract) {
-        findings.push({
-          id: fingerprint("DRIFT_NEW_WEBHOOK", wh.path),
-          category: "ContractDrift",
-          type: "new_webhook_not_in_contract",
-          severity: "WARN",
-          scope: "server",
-          title: `New Stripe webhook at ${wh.path} not in contract`,
-          message: `A webhook handler was added but not declared in external contract.`,
-          why: "Webhook contracts ensure proper signature verification and idempotency.",
-          evidence: wh.evidence || [],
-          fixHints: [
-            "Run 'vibecheck ctx sync' to update contracts"
-          ],
-          fingerprint: fingerprint("DRIFT_NEW_WEBHOOK", wh.path)
-        });
-      }
-    }
-  }
-
-  return findings;
-}
-
-function findParameterizedMatch(routes, method, pathToMatch) {
-  for (const r of routes || []) {
-    if (r.method !== "*" && r.method !== method) continue;
-    if (matchesParameterized(r.path, pathToMatch)) return r;
-  }
-  return null;
-}
-
-function matchesParameterized(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;
-}
-
-function isRequiredEnvVar(name) {
-  const requiredPatterns = [
-    /^DATABASE_URL$/i,
-    /^NEXTAUTH_SECRET$/i,
-    /^NEXTAUTH_URL$/i,
-    /^JWT_SECRET$/i,
-    /^STRIPE_SECRET_KEY$/i,
-    /^STRIPE_WEBHOOK_SECRET$/i,
-    /^API_KEY$/i,
-    /SECRET/i,
-    /TOKEN$/i,
-  ];
-  return requiredPatterns.some(p => p.test(name));
-}
-
-/**
- * Load contracts from disk
- */
-function loadContracts(repoRoot) {
-  const contractDir = path.join(repoRoot, ".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);
-    if (fs.existsSync(filePath)) {
-      try {
-        contracts[key] = JSON.parse(fs.readFileSync(filePath, "utf8"));
-      } catch (e) {
-        // Silently skip invalid files
-      }
-    }
-  }
-
-  return contracts;
-}
-
-/**
- * Check if contracts exist
- */
-function hasContracts(repoRoot) {
-  const contractDir = path.join(repoRoot, ".vibecheck", "contracts");
-  if (!fs.existsSync(contractDir)) return false;
-  
-  const files = ["routes.json", "env.json", "auth.json", "external.json"];
-  return files.some(f => fs.existsSync(path.join(contractDir, f)));
-}
-
-/**
- * Get drift summary for quick checks
- */
-function getDriftSummary(findings) {
-  const blocks = findings.filter(f => f.severity === "BLOCK");
-  const warns = findings.filter(f => f.severity === "WARN");
-
-  return {
-    hasDrift: findings.length > 0,
-    blocks: blocks.length,
-    warns: warns.length,
-    verdict: blocks.length > 0 ? "BLOCK" : warns.length > 0 ? "WARN" : "PASS",
-    categories: {
-      routes: findings.filter(f => f.type.includes("route")).length,
-      env: findings.filter(f => f.type.includes("env")).length,
-      auth: findings.filter(f => f.type.includes("auth")).length,
-      external: findings.filter(f => f.type.includes("webhook")).length
-    }
-  };
-}
-
-module.exports = {
-  findContractDrift,
-  loadContracts,
-  hasContracts,
-  getDriftSummary,
-  fingerprint
-};
+/**
+ * Contract Drift Detection
+ * 
+ * Detects when code has drifted from contracts (routes/env/auth/external).
+ * Per spec: "routes/env/auth drift → usually BLOCK (because AI will lie here)"
+ */
+
+"use strict";
+
+const path = require("path");
+const fs = require("fs");
+const crypto = require("crypto");
+const { createDriftFinding, migrateFindingToV2 } = require("./findings-schema");
+
+/**
+ * Generate a stable fingerprint for a finding (for dedupe across runs)
+ */
+function fingerprint(type, ...parts) {
+  const data = [type, ...parts].join("|");
+  return crypto.createHash("sha256").update(data).digest("hex").slice(0, 12);
+}
+
+/**
+ * Find drift between contracts and current truthpack
+ * Returns findings array with BLOCK/WARN severity based on category
+ */
+function findContractDrift(contracts, truthpack, opts = {}) {
+  const findings = [];
+
+  // Route drift - BLOCK severity (AI can invent fake endpoints)
+  if (contracts?.routes && truthpack?.routes) {
+    const routeFindings = detectRouteDrift(contracts.routes, truthpack);
+    findings.push(...routeFindings);
+  }
+
+  // Env drift - BLOCK for required, WARN for optional
+  if (contracts?.env && truthpack?.env) {
+    const envFindings = detectEnvDrift(contracts.env, truthpack);
+    findings.push(...envFindings);
+  }
+
+  // Auth drift - BLOCK severity (security critical)
+  if (contracts?.auth && truthpack?.auth) {
+    const authFindings = detectAuthDrift(contracts.auth, truthpack);
+    findings.push(...authFindings);
+  }
+
+  // External drift - WARN severity (service changes)
+  if (contracts?.external) {
+    const externalFindings = detectExternalDrift(contracts.external, truthpack);
+    findings.push(...externalFindings);
+  }
+
+  return findings;
+}
+
+/**
+ * Detect route drift: new routes not in contract, removed routes still in contract
+ */
+function detectRouteDrift(routeContract, truthpack) {
+  const findings = [];
+  const contractRoutes = new Map();
+  
+  for (const r of routeContract.routes || []) {
+    const key = `${r.method}_${r.path}`;
+    contractRoutes.set(key, r);
+  }
+
+  const serverRoutes = truthpack?.routes?.server || [];
+  const currentRoutes = new Set();
+
+  // Check for new routes not in contract
+  for (const route of serverRoutes) {
+    const key = `${route.method}_${route.path}`;
+    currentRoutes.add(key);
+
+    if (!contractRoutes.has(key)) {
+      // Check parameterized match
+      const match = findParameterizedMatch(routeContract.routes, route.method, route.path);
+      if (!match) {
+        findings.push({
+          id: fingerprint("DRIFT_NEW_ROUTE", route.method, route.path),
+          category: "ContractDrift",
+          type: "new_route_not_in_contract",
+          severity: "BLOCK",
+          scope: "server",
+          title: `New route ${route.method} ${route.path} not declared in contract`,
+          message: `Route was added to code but not synced to contracts. AI agents cannot safely reference this route.`,
+          why: "Contracts are the source of truth. Undeclared routes can cause AI hallucinations.",
+          evidence: route.evidence || [],
+          fixHints: [
+            "Run 'vibecheck ctx sync' to update contracts",
+            "Or remove the route if unintended"
+          ],
+          fingerprint: fingerprint("DRIFT_NEW_ROUTE", route.method, route.path)
+        });
+      }
+    }
+  }
+
+  // Check for removed routes still in contract
+  for (const [key, contractRoute] of contractRoutes) {
+    if (!currentRoutes.has(key)) {
+      // Check if any current route matches parameterized
+      const stillExists = serverRoutes.some(r => 
+        matchesParameterized(contractRoute.path, r.path) && 
+        (contractRoute.method === "*" || contractRoute.method === r.method)
+      );
+
+      if (!stillExists) {
+        findings.push({
+          id: fingerprint("DRIFT_REMOVED_ROUTE", contractRoute.method, contractRoute.path),
+          category: "ContractDrift",
+          type: "route_removed_from_code",
+          severity: "BLOCK",
+          scope: "contracts",
+          title: `Route ${contractRoute.method} ${contractRoute.path} in contract but removed from code`,
+          message: `Contract declares a route that no longer exists. AI agents will reference a ghost endpoint.`,
+          why: "Stale contracts cause AI to generate code calling non-existent endpoints.",
+          evidence: contractRoute.evidence || [],
+          fixHints: [
+            "Run 'vibecheck ctx sync' to update contracts",
+            "Or restore the route if removal was unintended"
+          ],
+          fingerprint: fingerprint("DRIFT_REMOVED_ROUTE", contractRoute.method, contractRoute.path)
+        });
+      }
+    }
+  }
+
+  // Check for client refs not in contract (same as existing analyzer but with drift framing)
+  const clientRefs = truthpack?.routes?.clientRefs || [];
+  for (const ref of clientRefs) {
+    const key = `${ref.method}_${ref.path}`;
+    if (!contractRoutes.has(key)) {
+      const match = findParameterizedMatch(routeContract.routes, ref.method, ref.path);
+      if (!match) {
+        findings.push({
+          id: fingerprint("DRIFT_CLIENT_UNDECLARED", ref.method, ref.path),
+          category: "ContractDrift",
+          type: "client_refs_undeclared_route",
+          severity: "BLOCK",
+          scope: "client",
+          title: `Client calls ${ref.method} ${ref.path} which is not in contract`,
+          message: `Frontend references a route not declared in contracts. This will cause runtime errors.`,
+          why: "Client code should only call routes that exist in the contract.",
+          evidence: ref.evidence || [],
+          fixHints: [
+            "Create the missing route handler",
+            "Or update the client to use a valid route",
+            "Then run 'vibecheck ctx sync'"
+          ],
+          fingerprint: fingerprint("DRIFT_CLIENT_UNDECLARED", ref.method, ref.path)
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Detect env drift: new vars not in contract, required vars removed
+ */
+function detectEnvDrift(envContract, truthpack) {
+  const findings = [];
+  const contractVars = new Map();
+
+  for (const v of envContract.vars || []) {
+    contractVars.set(v.name, v);
+  }
+
+  const usedVars = truthpack?.env?.vars || [];
+  const currentVarNames = new Set(usedVars.map(v => v.name));
+
+  // Check for new env vars used but not in contract
+  for (const usedVar of usedVars) {
+    if (!contractVars.has(usedVar.name)) {
+      const isLikelyRequired = isRequiredEnvVar(usedVar.name);
+      findings.push({
+        id: fingerprint("DRIFT_NEW_ENV", usedVar.name),
+        category: "ContractDrift",
+        type: "new_env_not_in_contract",
+        severity: isLikelyRequired ? "BLOCK" : "WARN",
+        scope: "server",
+        title: `Env var ${usedVar.name} used but not in contract`,
+        message: `Code uses ${usedVar.name} but it's not declared in env contract.`,
+        why: "Undeclared env vars can cause deployment failures and AI confusion.",
+        evidence: usedVar.references || [],
+        fixHints: [
+          "Run 'vibecheck ctx sync' to update contracts",
+          `Add ${usedVar.name} to .env.example`
+        ],
+        fingerprint: fingerprint("DRIFT_NEW_ENV", usedVar.name)
+      });
+    }
+  }
+
+  // Check for required contract vars no longer used
+  for (const [name, spec] of contractVars) {
+    if (spec.required && !currentVarNames.has(name)) {
+      findings.push({
+        id: fingerprint("DRIFT_REMOVED_ENV", name),
+        category: "ContractDrift",
+        type: "required_env_removed",
+        severity: "WARN",
+        scope: "contracts",
+        title: `Required env var ${name} in contract but not used in code`,
+        message: `Contract marks ${name} as required but code no longer uses it.`,
+        why: "Stale env contracts cause confusion about what's actually needed.",
+        evidence: [],
+        fixHints: [
+          "Run 'vibecheck ctx sync' to update contracts",
+          "Or check if the var was accidentally removed from code"
+        ],
+        fingerprint: fingerprint("DRIFT_REMOVED_ENV", name)
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Detect auth drift: protected patterns changed
+ */
+function detectAuthDrift(authContract, truthpack) {
+  const findings = [];
+  const contractPatterns = new Set(authContract.protectedPatterns || []);
+  const currentPatterns = new Set(truthpack?.auth?.nextMatcherPatterns || []);
+
+  // New protected patterns not in contract
+  for (const pattern of currentPatterns) {
+    if (!contractPatterns.has(pattern)) {
+      findings.push({
+        id: fingerprint("DRIFT_NEW_AUTH", pattern),
+        category: "ContractDrift",
+        type: "new_auth_pattern",
+        severity: "BLOCK",
+        scope: "server",
+        title: `New auth pattern "${pattern}" not in contract`,
+        message: `Middleware protects a new pattern that isn't in the auth contract.`,
+        why: "Auth contracts define security boundaries. Undeclared patterns may not be properly tested.",
+        evidence: [],
+        fixHints: [
+          "Run 'vibecheck ctx sync' to update contracts",
+          "Verify the new pattern is intentional"
+        ],
+        fingerprint: fingerprint("DRIFT_NEW_AUTH", pattern)
+      });
+    }
+  }
+
+  // Protected patterns in contract but removed from code
+  for (const pattern of contractPatterns) {
+    if (!currentPatterns.has(pattern)) {
+      findings.push({
+        id: fingerprint("DRIFT_REMOVED_AUTH", pattern),
+        category: "ContractDrift",
+        type: "auth_pattern_removed",
+        severity: "BLOCK",
+        scope: "contracts",
+        title: `Auth pattern "${pattern}" in contract but removed from middleware`,
+        message: `Contract expects protection for "${pattern}" but middleware no longer enforces it.`,
+        why: "Removing auth patterns can expose protected routes. This is a security regression.",
+        evidence: [],
+        fixHints: [
+          "Restore the auth pattern in middleware if removal was unintended",
+          "Or run 'vibecheck ctx sync' to accept the change"
+        ],
+        fingerprint: fingerprint("DRIFT_REMOVED_AUTH", pattern)
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Detect external service drift
+ */
+function detectExternalDrift(externalContract, truthpack) {
+  const findings = [];
+  const contractServices = new Map();
+
+  for (const svc of externalContract.services || []) {
+    contractServices.set(svc.name, svc);
+  }
+
+  // Check Stripe webhook changes
+  const billing = truthpack?.billing || {};
+  if (contractServices.has("stripe")) {
+    const contractStripe = contractServices.get("stripe");
+    const currentWebhooks = billing.webhookCandidates || [];
+
+    // New webhook not in contract
+    for (const wh of currentWebhooks) {
+      const inContract = contractStripe.webhooks?.some(cw => cw.path === wh.path);
+      if (!inContract) {
+        findings.push({
+          id: fingerprint("DRIFT_NEW_WEBHOOK", wh.path),
+          category: "ContractDrift",
+          type: "new_webhook_not_in_contract",
+          severity: "WARN",
+          scope: "server",
+          title: `New Stripe webhook at ${wh.path} not in contract`,
+          message: `A webhook handler was added but not declared in external contract.`,
+          why: "Webhook contracts ensure proper signature verification and idempotency.",
+          evidence: wh.evidence || [],
+          fixHints: [
+            "Run 'vibecheck ctx sync' to update contracts"
+          ],
+          fingerprint: fingerprint("DRIFT_NEW_WEBHOOK", wh.path)
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+function findParameterizedMatch(routes, method, pathToMatch) {
+  for (const r of routes || []) {
+    if (r.method !== "*" && r.method !== method) continue;
+    if (matchesParameterized(r.path, pathToMatch)) return r;
+  }
+  return null;
+}
+
+function matchesParameterized(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;
+}
+
+function isRequiredEnvVar(name) {
+  const requiredPatterns = [
+    /^DATABASE_URL$/i,
+    /^NEXTAUTH_SECRET$/i,
+    /^NEXTAUTH_URL$/i,
+    /^JWT_SECRET$/i,
+    /^STRIPE_SECRET_KEY$/i,
+    /^STRIPE_WEBHOOK_SECRET$/i,
+    /^API_KEY$/i,
+    /SECRET/i,
+    /TOKEN$/i,
+  ];
+  return requiredPatterns.some(p => p.test(name));
+}
+
+/**
+ * Load contracts from disk
+ */
+function loadContracts(repoRoot) {
+  const contractDir = path.join(repoRoot, ".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);
+    if (fs.existsSync(filePath)) {
+      try {
+        contracts[key] = JSON.parse(fs.readFileSync(filePath, "utf8"));
+      } catch (e) {
+        // Silently skip invalid files
+      }
+    }
+  }
+
+  return contracts;
+}
+
+/**
+ * Check if contracts exist
+ */
+function hasContracts(repoRoot) {
+  const contractDir = path.join(repoRoot, ".vibecheck", "contracts");
+  if (!fs.existsSync(contractDir)) return false;
+  
+  const files = ["routes.json", "env.json", "auth.json", "external.json"];
+  return files.some(f => fs.existsSync(path.join(contractDir, f)));
+}
+
+/**
+ * Get drift summary for quick checks
+ */
+function getDriftSummary(findings) {
+  const blocks = findings.filter(f => f.severity === "BLOCK");
+  const warns = findings.filter(f => f.severity === "WARN");
+
+  return {
+    hasDrift: findings.length > 0,
+    blocks: blocks.length,
+    warns: warns.length,
+    verdict: blocks.length > 0 ? "BLOCK" : warns.length > 0 ? "WARN" : "PASS",
+    categories: {
+      routes: findings.filter(f => f.type.includes("route")).length,
+      env: findings.filter(f => f.type.includes("env")).length,
+      auth: findings.filter(f => f.type.includes("auth")).length,
+      external: findings.filter(f => f.type.includes("webhook")).length
+    }
+  };
+}
+
+module.exports = {
+  findContractDrift,
+  loadContracts,
+  hasContracts,
+  getDriftSummary,
+  fingerprint
+};