speclock 5.0.2 → 5.1.0

package/README.md

@@ -8,7 +8,7 @@
   <a href="https://www.npmjs.com/package/speclock"><img src="https://img.shields.io/npm/v/speclock.svg?style=flat-square&color=4F46E5" alt="npm version" /></a>
   <a href="https://www.npmjs.com/package/speclock"><img src="https://img.shields.io/npm/dm/speclock.svg?style=flat-square&color=22C55E" alt="npm downloads" /></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="MIT License" /></a>
-  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-39_tools-green.svg?style=flat-square" alt="MCP 39 tools" /></a>
+  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-40_tools-green.svg?style=flat-square" alt="MCP 40 tools" /></a>
 </p>
 
 <p align="center">
@@ -32,7 +32,7 @@ AI:     ⚠️  BLOCKED — violates lock "Never touch the auth system"
         Should I find another approach?
 ```
 
-**940 tests. 99.4% pass rate. 0 false positives across 13 suites. Gemini Flash hybrid, Spec Compiler, Code Graph, Typed Constraints, Python SDK, ROS2 integration.**
+**997 tests. 99.4% pass rate. 0 false positives across 14 suites. Gemini Flash hybrid, Spec Compiler, Code Graph, Typed Constraints, Python SDK, ROS2 integration.**
 
 ---
 
@@ -339,7 +339,7 @@ GET  /api/v2/graph/lock-map
 
 ---
 
-## 39 MCP Tools
+## 40 MCP Tools
 
 <details>
 <summary><b>Memory</b> — goal, locks, decisions, notes, deploy facts</summary>
@@ -508,7 +508,7 @@ The AI opens the file and sees:
 │     AI Tool (Claude Code, Cursor, Bolt.new...)    │
 └────────────┬──────────────────┬──────────────────┘
              │                  │
-   MCP Protocol (39 tools)    npm File-Based
+   MCP Protocol (40 tools)    npm File-Based
              │              (SPECLOCK.md + CLI)
              │                  │
 ┌────────────▼──────────────────▼──────────────────┐
@@ -571,7 +571,7 @@ The AI opens the file and sees:
 | Python SDK | 62 | 100% | pip install, constraint checking |
 | ROS2 Guardian | 26 | 100% | Robot safety constraint enforcement |
 | Real-World Testers | 105 | 95% | 5 developers, 30+ locks, diverse domains |
-| **Total** | **940** | **99.4%** | **13 suites, 15 domains** |
+| **Total** | **940** | **99.4%** | **14 suites, 15 domains** |
 
 Tested across: fintech, e-commerce, IoT, healthcare, SaaS, gaming, biotech, aerospace, payments, payroll, robotics, autonomous systems. All 11 Indian payment gateways detected. Zero false positives on UI/cosmetic actions.
 
@@ -611,4 +611,4 @@ Built by **[Sandeep Roy](https://github.com/sgroy10)**
 
 ---
 
-<p align="center"><i>v5.0.0 — 940 tests, 99.4% pass rate, 39 MCP tools, Spec Compiler, Code Graph, Typed Constraints, Python SDK, ROS2, REST API v2. Because remembering isn't enough.</i></p>
+<p align="center"><i>v5.0.0 — 997 tests, 99.4% pass rate, 40 MCP tools, Spec Compiler, Code Graph, Typed Constraints, Python SDK, ROS2, REST API v2. Because remembering isn't enough.</i></p>

package/package.json

@@ -2,9 +2,9 @@
 
   "name": "speclock",
 
-  "version": "5.0.2",
+  "version": "5.1.0",
 
-  "description": "AI Constraint Engine for autonomous systems governance. Spec Compiler (NL→constraints), Code Graph (blast radius, lock-to-file mapping), Typed constraints (numerical, range, state, temporal), REST API v2, Python SDK, ROS2 integration. 39 MCP tools, Gemini LLM hybrid, HMAC audit chain, RBAC, encryption, SOC 2/HIPAA compliance.",
+  "description": "AI Constraint Engine for autonomous systems governance. Patch Gateway (ALLOW/WARN/BLOCK change verdicts), Spec Compiler (NL→constraints), Code Graph (blast radius, lock-to-file mapping), Typed constraints (numerical, range, state, temporal), REST API v2, Python SDK, ROS2 integration. 40 MCP tools, Gemini LLM hybrid, HMAC audit chain, RBAC, encryption, SOC 2/HIPAA compliance.",
 
   "type": "module",
 

package/src/cli/index.js

@@ -117,7 +117,7 @@ function refreshContext(root) {
 
 function printHelp() {
   console.log(`
-SpecLock v5.0.0 — AI Constraint Engine (Spec Compiler + Code Graph + Typed Constraints + Python SDK + ROS2 + REST API v2 + Gemini LLM + Policy-as-Code + Auth + RBAC + Encryption)
+SpecLock v5.1.0 — AI Constraint Engine (Spec Compiler + Code Graph + Typed Constraints + Python SDK + ROS2 + REST API v2 + Gemini LLM + Policy-as-Code + Auth + RBAC + Encryption)
 Developed by Sandeep Roy (github.com/sgroy10)
 
 Usage: speclock <command> [options]

package/src/core/compliance.js

@@ -9,7 +9,7 @@
 import { readBrain, readEvents } from "./storage.js";
 import { verifyAuditChain } from "./audit.js";
 
-const VERSION = "5.0.0";
+const VERSION = "5.1.0";
 
 // PHI-related keywords for HIPAA filtering
 const PHI_KEYWORDS = [

package/src/core/engine.js

@@ -638,3 +638,9 @@ export {
   getModules,
   getCriticalPaths,
 } from "./code-graph.js";
+
+// --- Patch Gateway (v5.1) ---
+export {
+  reviewPatch,
+  reviewPatchAsync,
+} from "./patch-gateway.js";

package/src/core/patch-gateway.js

@@ -0,0 +1,346 @@
+// ===================================================================
+// SpecLock Patch Gateway — Change Decision Engine
+// Combines semantic conflict detection, lock-to-file mapping, blast
+// radius analysis, and typed constraints into a single ALLOW/WARN/BLOCK
+// verdict for any proposed change.
+//
+// Developed by Sandeep Roy (https://github.com/sgroy10)
+// ===================================================================
+
+import { readBrain } from "./storage.js";
+import { ensureInit } from "./memory.js";
+import { analyzeConflict } from "./semantics.js";
+import { checkAllTypedConstraints } from "./typed-constraints.js";
+import { getOrBuildGraph, getBlastRadius, mapLocksToFiles } from "./code-graph.js";
+
+// --- Thresholds ---
+
+const BLOCK_CONFIDENCE = 70;   // Semantic confidence >= 70 → BLOCK
+const WARN_CONFIDENCE = 40;    // Semantic confidence >= 40 → WARN
+const HIGH_BLAST_RADIUS = 20;  // > 20% impact → adds to risk
+const MED_BLAST_RADIUS = 10;   // > 10% impact → moderate risk
+
+// --- Main Gateway ---
+
+/**
+ * Review a proposed change against all active constraints.
+ *
+ * @param {string} root - Project root
+ * @param {object} opts
+ * @param {string} opts.description - What the change does (natural language)
+ * @param {string[]} [opts.files] - Files being changed (project-relative paths)
+ * @param {boolean} [opts.includeGraph=true] - Whether to run blast radius analysis
+ * @returns {object} Verdict with risk score, reasons, and summary
+ */
+export function reviewPatch(root, { description, files = [], includeGraph = true }) {
+  if (!description || typeof description !== "string" || !description.trim()) {
+    return {
+      verdict: "ERROR",
+      riskScore: 0,
+      error: "description is required (describe what the change does)",
+      reasons: [],
+      summary: "No change description provided.",
+    };
+  }
+
+  const brain = ensureInit(root);
+  const activeLocks = (brain.specLock?.items || []).filter(l => l.active !== false);
+  const textLocks = activeLocks.filter(l => !l.constraintType);
+  const typedLocks = activeLocks.filter(l => l.constraintType);
+
+  const reasons = [];
+  let maxConfidence = 0;
+
+  // --- Step 1: Semantic conflict check against all text locks ---
+  for (const lock of textLocks) {
+    const result = analyzeConflict(description, lock.text);
+    if (result.isConflict) {
+      const confidence = result.confidence || 0;
+      if (confidence > maxConfidence) maxConfidence = confidence;
+      reasons.push({
+        type: "semantic_conflict",
+        severity: confidence >= BLOCK_CONFIDENCE ? "block" : "warn",
+        lockId: lock.id,
+        lockText: lock.text,
+        confidence,
+        level: result.level || "MEDIUM",
+        details: result.reasons || [],
+      });
+    }
+  }
+
+  // --- Step 2: Lock-to-file mapping (do changed files touch locked zones?) ---
+  let lockFileMatches = [];
+  if (files.length > 0) {
+    try {
+      const lockMap = mapLocksToFiles(root);
+      const normalizedFiles = files.map(f => f.replace(/\\/g, "/"));
+
+      for (const mapping of lockMap) {
+        const overlapping = mapping.matchedFiles.filter(mf =>
+          normalizedFiles.some(cf => {
+            const cfNorm = cf.toLowerCase();
+            const mfNorm = mf.toLowerCase();
+            return cfNorm === mfNorm || cfNorm.endsWith("/" + mfNorm) || mfNorm.endsWith("/" + cfNorm);
+          })
+        );
+        if (overlapping.length > 0) {
+          lockFileMatches.push({
+            lockId: mapping.lockId,
+            lockText: mapping.lockText,
+            overlappingFiles: overlapping,
+          });
+          // Find the lock's existing semantic confidence, or default to 60
+          const existingSemantic = reasons.find(r => r.lockId === mapping.lockId);
+          if (!existingSemantic) {
+            // This lock wasn't caught by semantic analysis but the files overlap
+            reasons.push({
+              type: "lock_file_overlap",
+              severity: "warn",
+              lockId: mapping.lockId,
+              lockText: mapping.lockText,
+              confidence: 60,
+              level: "MEDIUM",
+              details: [`Changed files overlap with locked zone: ${overlapping.join(", ")}`],
+            });
+            if (60 > maxConfidence) maxConfidence = 60;
+          } else {
+            // Boost existing semantic match — file evidence confirms it
+            existingSemantic.confidence = Math.min(100, existingSemantic.confidence + 15);
+            existingSemantic.details.push(`File-level confirmation: ${overlapping.join(", ")}`);
+            if (existingSemantic.confidence > maxConfidence) maxConfidence = existingSemantic.confidence;
+            if (existingSemantic.confidence >= BLOCK_CONFIDENCE) existingSemantic.severity = "block";
+          }
+        }
+      }
+    } catch (_) {
+      // Lock mapping failed (no graph), continue without it
+    }
+  }
+
+  // --- Step 3: Blast radius for each changed file ---
+  let blastDetails = [];
+  let maxImpactPercent = 0;
+  if (includeGraph && files.length > 0) {
+    try {
+      for (const file of files) {
+        const br = getBlastRadius(root, file);
+        if (br.found) {
+          blastDetails.push({
+            file: br.file,
+            directDependents: br.directDependents?.length || 0,
+            transitiveDependents: br.blastRadius || 0,
+            impactPercent: br.impactPercent || 0,
+            depth: br.depth || 0,
+          });
+          if (br.impactPercent > maxImpactPercent) maxImpactPercent = br.impactPercent;
+        }
+      }
+
+      if (maxImpactPercent > HIGH_BLAST_RADIUS) {
+        reasons.push({
+          type: "high_blast_radius",
+          severity: "warn",
+          confidence: Math.min(90, 50 + maxImpactPercent),
+          level: "HIGH",
+          details: [`Change affects ${maxImpactPercent.toFixed(1)}% of the codebase`],
+        });
+      } else if (maxImpactPercent > MED_BLAST_RADIUS) {
+        reasons.push({
+          type: "moderate_blast_radius",
+          severity: "info",
+          confidence: 30 + maxImpactPercent,
+          level: "MEDIUM",
+          details: [`Change affects ${maxImpactPercent.toFixed(1)}% of the codebase`],
+        });
+      }
+    } catch (_) {
+      // Graph not available, skip blast radius
+    }
+  }
+
+  // --- Step 4: Typed constraint awareness ---
+  let typedWarnings = [];
+  if (typedLocks.length > 0) {
+    // Check if the description mentions any typed constraint metrics
+    const descLower = description.toLowerCase();
+    for (const lock of typedLocks) {
+      const metric = (lock.metric || lock.description || lock.text || "").toLowerCase();
+      if (metric && descLower.includes(metric.split(" ")[0])) {
+        typedWarnings.push({
+          lockId: lock.id,
+          constraintType: lock.constraintType,
+          metric: lock.metric || lock.description,
+          text: lock.text,
+        });
+        reasons.push({
+          type: "typed_constraint_relevant",
+          severity: "info",
+          lockId: lock.id,
+          lockText: lock.text,
+          confidence: 30,
+          level: "LOW",
+          details: [`Typed constraint (${lock.constraintType}) may be relevant: ${lock.text}`],
+        });
+      }
+    }
+  }
+
+  // --- Step 5: Calculate risk score & verdict ---
+  let riskScore = 0;
+
+  // Base risk from semantic conflicts
+  if (maxConfidence > 0) {
+    riskScore = maxConfidence;
+  }
+
+  // Boost from lock-file overlaps
+  if (lockFileMatches.length > 0) {
+    riskScore = Math.max(riskScore, 55);
+    riskScore = Math.min(100, riskScore + lockFileMatches.length * 5);
+  }
+
+  // Boost from blast radius
+  if (maxImpactPercent > HIGH_BLAST_RADIUS) {
+    riskScore = Math.min(100, riskScore + 15);
+  } else if (maxImpactPercent > MED_BLAST_RADIUS) {
+    riskScore = Math.min(100, riskScore + 8);
+  }
+
+  // Determine verdict
+  let verdict;
+  const hasBlockSeverity = reasons.some(r => r.severity === "block");
+  if (hasBlockSeverity || riskScore >= BLOCK_CONFIDENCE) {
+    verdict = "BLOCK";
+  } else if (riskScore >= WARN_CONFIDENCE || reasons.some(r => r.severity === "warn")) {
+    verdict = "WARN";
+  } else {
+    verdict = "ALLOW";
+  }
+
+  // --- Step 6: Build human-readable summary ---
+  const summary = buildSummary(verdict, riskScore, reasons, files, blastDetails, lockFileMatches);
+
+  return {
+    verdict,
+    riskScore,
+    description,
+    fileCount: files.length,
+    lockCount: activeLocks.length,
+    reasons,
+    blastRadius: blastDetails.length > 0 ? {
+      files: blastDetails,
+      maxImpactPercent,
+    } : undefined,
+    lockFileOverlaps: lockFileMatches.length > 0 ? lockFileMatches : undefined,
+    typedConstraints: typedWarnings.length > 0 ? typedWarnings : undefined,
+    summary,
+  };
+}
+
+/**
+ * Async version — adds LLM-powered conflict checking for grey-zone decisions.
+ */
+export async function reviewPatchAsync(root, opts) {
+  // Start with heuristic review
+  const result = reviewPatch(root, opts);
+
+  // If verdict is already BLOCK or ALLOW with high confidence, return immediately
+  if (result.verdict === "BLOCK" || (result.verdict === "ALLOW" && result.riskScore < 20)) {
+    result.source = "heuristic";
+    return result;
+  }
+
+  // For WARN / uncertain cases, try LLM enhancement
+  try {
+    const { llmCheckConflict } = await import("./llm-checker.js");
+    const brain = readBrain(root);
+    const activeLocks = (brain?.specLock?.items || []).filter(l => l.active !== false && !l.constraintType);
+
+    if (activeLocks.length > 0) {
+      const llmResult = await llmCheckConflict(root, opts.description, activeLocks);
+      if (llmResult && llmResult.hasConflict) {
+        for (const lc of (llmResult.conflictingLocks || [])) {
+          const confidence = lc.confidence || 50;
+          const existing = result.reasons.find(r => r.lockId === lc.id);
+          if (existing) {
+            // LLM confirms heuristic — boost confidence
+            existing.confidence = Math.max(existing.confidence, confidence);
+            existing.details.push("LLM confirmed conflict");
+            if (existing.confidence >= BLOCK_CONFIDENCE) existing.severity = "block";
+          } else {
+            // LLM found new conflict heuristic missed
+            result.reasons.push({
+              type: "llm_conflict",
+              severity: confidence >= BLOCK_CONFIDENCE ? "block" : "warn",
+              lockId: lc.id,
+              lockText: lc.text,
+              confidence,
+              level: lc.level || "MEDIUM",
+              details: lc.reasons || ["LLM-detected conflict"],
+            });
+          }
+          if (confidence > result.riskScore) result.riskScore = confidence;
+        }
+
+        // Re-evaluate verdict with LLM data
+        const hasBlock = result.reasons.some(r => r.severity === "block");
+        if (hasBlock || result.riskScore >= BLOCK_CONFIDENCE) {
+          result.verdict = "BLOCK";
+        } else if (result.riskScore >= WARN_CONFIDENCE) {
+          result.verdict = "WARN";
+        }
+
+        result.summary = buildSummary(
+          result.verdict, result.riskScore, result.reasons,
+          opts.files || [], result.blastRadius?.files || [],
+          result.lockFileOverlaps || []
+        );
+      }
+    }
+    result.source = "hybrid";
+  } catch (_) {
+    result.source = "heuristic-only";
+  }
+
+  return result;
+}
+
+// --- Summary builder ---
+
+function buildSummary(verdict, riskScore, reasons, files, blastDetails, lockFileMatches) {
+  const parts = [];
+
+  if (verdict === "BLOCK") {
+    parts.push(`BLOCKED (risk: ${riskScore}/100)`);
+  } else if (verdict === "WARN") {
+    parts.push(`WARNING (risk: ${riskScore}/100)`);
+  } else {
+    parts.push(`ALLOWED (risk: ${riskScore}/100)`);
+  }
+
+  const semanticConflicts = reasons.filter(r => r.type === "semantic_conflict" || r.type === "llm_conflict");
+  if (semanticConflicts.length > 0) {
+    parts.push(`${semanticConflicts.length} constraint conflict(s): ${semanticConflicts.map(r => `"${r.lockText}"`).join(", ")}`);
+  }
+
+  if (lockFileMatches.length > 0) {
+    const fileCount = lockFileMatches.reduce((acc, m) => acc + m.overlappingFiles.length, 0);
+    parts.push(`${fileCount} file(s) in locked zones`);
+  }
+
+  if (blastDetails.length > 0) {
+    const maxImpact = Math.max(...blastDetails.map(b => b.impactPercent));
+    const totalDeps = blastDetails.reduce((acc, b) => acc + b.transitiveDependents, 0);
+    if (maxImpact > 0) {
+      parts.push(`blast radius: ${totalDeps} dependent file(s), ${maxImpact.toFixed(1)}% impact`);
+    }
+  }
+
+  const typedReasons = reasons.filter(r => r.type === "typed_constraint_relevant");
+  if (typedReasons.length > 0) {
+    parts.push(`${typedReasons.length} typed constraint(s) may be affected`);
+  }
+
+  return parts.join(". ") + ".";
+}

package/src/dashboard/index.html

@@ -89,7 +89,7 @@
 <div class="header">
   <div>
     <h1><span>SpecLock</span> Dashboard</h1>
-    <div class="meta">v5.0.0 &mdash; AI Constraint Engine</div>
+    <div class="meta">v5.1.0 &mdash; AI Constraint Engine</div>
   </div>
   <div style="display:flex;align-items:center;gap:12px;">
     <span id="health-badge" class="status-badge healthy">Loading...</span>
@@ -182,7 +182,7 @@
 </div>
 
 <div style="text-align:center;padding:24px;color:var(--muted);font-size:12px;">
-  SpecLock v5.0.0 &mdash; Developed by Sandeep Roy &mdash; <a href="https://github.com/sgroy10/speclock" style="color:var(--accent)">GitHub</a>
+  SpecLock v5.1.0 &mdash; Developed by Sandeep Roy &mdash; <a href="https://github.com/sgroy10/speclock" style="color:var(--accent)">GitHub</a>
 </div>
 
 <script>

package/src/mcp/http-server.js

@@ -52,6 +52,8 @@ import {
   mapLocksToFiles,
   getModules,
   getCriticalPaths,
+  reviewPatch,
+  reviewPatchAsync,
 } from "../core/engine.js";
 import { generateContext, generateContextPack } from "../core/context.js";
 import {
@@ -107,7 +109,7 @@ import { fileURLToPath } from "url";
 import _path from "path";
 
 const PROJECT_ROOT = process.env.SPECLOCK_PROJECT_ROOT || process.cwd();
-const VERSION = "5.0.0";
+const VERSION = "5.1.0";
 const AUTHOR = "Sandeep Roy";
 const START_TIME = Date.now();
 
@@ -881,7 +883,7 @@ app.get("/health", (req, res) => {
     status: "healthy",
     version: VERSION,
     uptime: Math.floor((Date.now() - START_TIME) / 1000),
-    tools: 39,
+    tools: 40,
     auditChain: auditStatus,
     authEnabled: isAuthEnabled(PROJECT_ROOT),
     rateLimit: { limit: RATE_LIMIT, windowMs: RATE_WINDOW_MS },
@@ -895,8 +897,8 @@ app.get("/", (req, res) => {
     name: "speclock",
     version: VERSION,
     author: AUTHOR,
-    description: "AI Constraint Engine for autonomous systems governance. Spec Compiler (NL→constraints), Code Graph (blast radius, lock-to-file mapping), Typed constraints (numerical, range, state, temporal), REST API v2 with batch checking & SSE streaming. Python SDK + ROS2 integration. Policy-as-Code, RBAC, AES-256-GCM encryption, hard enforcement, HMAC audit chain, SOC 2/HIPAA compliance. 39 MCP tools. 940 tests, 99.4% accuracy.",
-    tools: 39,
+    description: "AI Constraint Engine for autonomous systems governance. Spec Compiler (NL→constraints), Code Graph (blast radius, lock-to-file mapping), Typed constraints (numerical, range, state, temporal), REST API v2 with batch checking & SSE streaming. Python SDK + ROS2 integration. Policy-as-Code, RBAC, AES-256-GCM encryption, hard enforcement, HMAC audit chain, SOC 2/HIPAA compliance. 40 MCP tools. 940 tests, 99.4% accuracy.",
+    tools: 40,
     mcp_endpoint: "/mcp",
     health_endpoint: "/health",
     npm: "https://www.npmjs.com/package/speclock",
@@ -910,7 +912,7 @@ app.get("/.well-known/mcp/server-card.json", (req, res) => {
   res.json({
     name: "SpecLock",
     version: VERSION,
-    description: "AI Constraint Engine for autonomous systems governance. Spec Compiler (NL→constraints via Gemini Flash), Code Graph (dependency parsing, blast radius, lock-to-file mapping), Typed constraints (numerical, range, state, temporal), REST API v2, Python SDK + ROS2 Guardian Node. Hybrid heuristic + Gemini LLM. Policy-as-Code, RBAC, AES-256-GCM encryption, hard enforcement, HMAC audit chain, SOC 2/HIPAA compliance. 39 MCP tools. 940 tests, 99.4% accuracy. Works with Claude Code, Cursor, Windsurf, Cline, Bolt.new, Lovable.",
+    description: "AI Constraint Engine for autonomous systems governance. Spec Compiler (NL→constraints via Gemini Flash), Code Graph (dependency parsing, blast radius, lock-to-file mapping), Typed constraints (numerical, range, state, temporal), REST API v2, Python SDK + ROS2 Guardian Node. Hybrid heuristic + Gemini LLM. Policy-as-Code, RBAC, AES-256-GCM encryption, hard enforcement, HMAC audit chain, SOC 2/HIPAA compliance. 40 MCP tools. 940 tests, 99.4% accuracy. Works with Claude Code, Cursor, Windsurf, Cline, Bolt.new, Lovable.",
     author: {
       name: "Sandeep Roy",
       url: "https://github.com/sgroy10",
@@ -919,7 +921,7 @@ app.get("/.well-known/mcp/server-card.json", (req, res) => {
     homepage: "https://sgroy10.github.io/speclock/",
     license: "MIT",
     capabilities: {
-      tools: 39,
+      tools: 40,
       categories: [
         "Memory Management",
         "Change Tracking",
@@ -1509,6 +1511,36 @@ app.get("/api/v2/graph/lock-map", (req, res) => {
   }
 });
 
+// ========================================
+// PATCH GATEWAY (v5.1)
+// ========================================
+
+app.post("/api/v2/gateway/review", async (req, res) => {
+  setCorsHeaders(res);
+
+  const clientIp = req.headers["x-forwarded-for"]?.split(",")[0]?.trim() || req.socket?.remoteAddress || "unknown";
+  if (!checkRateLimit(clientIp)) {
+    return res.status(429).json({ error: "Rate limit exceeded", api_version: "v2" });
+  }
+
+  const { description, files, useLLM } = req.body || {};
+  if (!description || typeof description !== "string") {
+    return res.status(400).json({ error: "Missing 'description' field (describe what the change does)", api_version: "v2" });
+  }
+
+  try {
+    ensureInit(PROJECT_ROOT);
+    const fileList = Array.isArray(files) ? files : [];
+    const result = useLLM
+      ? await reviewPatchAsync(PROJECT_ROOT, { description, files: fileList })
+      : reviewPatch(PROJECT_ROOT, { description, files: fileList });
+
+    return res.json({ ...result, api_version: "v2" });
+  } catch (err) {
+    return res.status(500).json({ error: err.message, api_version: "v2" });
+  }
+});
+
 // ========================================
 // SSO ENDPOINTS (v3.5)
 // ========================================

package/src/mcp/server.js

@@ -57,6 +57,8 @@ import {
   mapLocksToFiles,
   getModules,
   getCriticalPaths,
+  reviewPatch,
+  reviewPatchAsync,
 } from "../core/engine.js";
 import { generateContext, generateContextPack } from "../core/context.js";
 import {
@@ -114,7 +116,7 @@ const PROJECT_ROOT =
   args.project || process.env.SPECLOCK_PROJECT_ROOT || process.cwd();
 
 // --- MCP Server ---
-const VERSION = "5.0.0";
+const VERSION = "5.1.0";
 const AUTHOR = "Sandeep Roy";
 
 const server = new McpServer(
@@ -1716,6 +1718,70 @@ server.tool(
   }
 );
 
+// --- Patch Gateway (v5.1) ---
+
+server.tool(
+  "speclock_review_patch",
+  "Review a proposed code change and get an ALLOW/WARN/BLOCK verdict. Combines semantic conflict detection, lock-to-file mapping, blast radius analysis, and typed constraint awareness into a single risk assessment. The patch-time decision engine that gates every change.",
+  {
+    description: z.string().describe("What the change does (e.g. 'Add social login to auth page')"),
+    files: z.array(z.string()).optional().default([]).describe("Files being changed (project-relative paths, e.g. ['src/auth/login.js'])"),
+    useLLM: z.boolean().optional().default(false).describe("If true, uses LLM for enhanced conflict detection on ambiguous cases"),
+  },
+  async ({ description, files, useLLM }) => {
+    const perm = requirePermission("speclock_review_patch");
+    if (!perm.allowed) return { content: [{ type: "text", text: perm.error }], isError: true };
+
+    const result = useLLM
+      ? await reviewPatchAsync(PROJECT_ROOT, { description, files })
+      : reviewPatch(PROJECT_ROOT, { description, files });
+
+    if (result.verdict === "ERROR") {
+      return { content: [{ type: "text", text: result.error }], isError: true };
+    }
+
+    const lines = [
+      `Patch Gateway Verdict: ${result.verdict}`,
+      `Risk Score: ${result.riskScore}/100`,
+      `Source: ${result.source || "heuristic"}`,
+      `Active Locks: ${result.lockCount}`,
+      `Files Reviewed: ${result.fileCount}`,
+      ``,
+      result.summary,
+    ];
+
+    if (result.reasons.length > 0) {
+      lines.push(``, `Reasons:`);
+      for (const r of result.reasons) {
+        const icon = r.severity === "block" ? "BLOCK" : r.severity === "warn" ? "WARN" : "INFO";
+        lines.push(`  [${icon}] ${r.type}: "${r.lockText || r.details?.[0] || ""}" (confidence: ${r.confidence}%)`);
+        if (r.details && r.details.length > 0) {
+          r.details.forEach(d => lines.push(`    - ${d}`));
+        }
+      }
+    }
+
+    if (result.blastRadius) {
+      lines.push(``, `Blast Radius:`);
+      for (const b of result.blastRadius.files) {
+        lines.push(`  ${b.file}: ${b.transitiveDependents} dependents (${b.impactPercent.toFixed(1)}% impact)`);
+      }
+    }
+
+    if (result.lockFileOverlaps) {
+      lines.push(``, `Lock-File Overlaps:`);
+      for (const o of result.lockFileOverlaps) {
+        lines.push(`  Lock: "${o.lockText}" → Files: ${o.overlappingFiles.join(", ")}`);
+      }
+    }
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      isError: result.verdict === "BLOCK",
+    };
+  }
+);
+
 // --- Smithery sandbox export ---
 export default function createSandboxServer() {
   return server;