speclock 5.1.0 → 5.2.1

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-40_tools-green.svg?style=flat-square" alt="MCP 40 tools" /></a>
+  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-42_tools-green.svg?style=flat-square" alt="MCP 42 tools" /></a>
 </p>
 
 <p align="center">
@@ -32,7 +32,7 @@ AI:     ⚠️  BLOCKED — violates lock "Never touch the auth system"
         Should I find another approach?
 ```
 
-**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.**
+**1073 tests. 99.4% pass rate. 0 false positives across 15 suites. Gemini Flash hybrid, Spec Compiler, Code Graph, Typed Constraints, Python SDK, ROS2 integration.**
 
 ---
 
@@ -305,25 +305,118 @@ pip install speclock-sdk
 ```
 
 ```python
-from speclock import ConstraintChecker
-checker = ConstraintChecker(constraints)
-result = checker.check({"metric": "speed_mps", "value": 3.5})
+from speclock import SpecLock
+
+sl = SpecLock(project_root=".")
+
+# Check text constraints (semantic conflict detection)
+result = sl.check_text("Switch database to MongoDB")
+# → { has_conflict: True, conflicting_locks: [...] }
+
+# Check typed constraints (numerical/range/state/temporal)
+result = sl.check_typed(metric="speed_mps", value=3.5)
 # → violation: speed exceeds 2.0 m/s limit
+
+# Combined check (text + typed in one call)
+result = sl.check(action="Increase speed", speed_mps=3.5)
+```
+
+Uses the same `.speclock/brain.json` as the Node.js MCP server — constraints stay in sync across all environments.
+
+**ROS2 Guardian Node:** Real-time constraint enforcement for robots and autonomous systems.
+
+```yaml
+# config/constraints.yaml
+constraints:
+  - type: range
+    metric: joint_position_rad
+    min: -3.14
+    max: 3.14
+  - type: numerical
+    metric: velocity_mps
+    operator: "<="
+    value: 2.0
+  - type: state
+    metric: system_mode
+    forbidden:
+      - from: emergency_stop
+        to: autonomous
+```
+
+- Subscribes to `/joint_states`, `/cmd_vel`, `/speclock/state_transition`
+- Publishes violations to `/speclock/violations`
+- Triggers emergency stop via `/speclock/emergency_stop`
+- Checks constraints on every incoming ROS2 message at configurable rate
+
+---
+
+## Patch Gateway (v5.1)
+
+One API call gates every change. Takes a description + file list, returns ALLOW/WARN/BLOCK:
+
+```
+speclock_review_patch({
+  description: "Add social login to auth page",
+  files: ["src/auth/login.js"]
+})
+
+→ { verdict: "BLOCK", riskScore: 85,
+    reasons: [{ type: "semantic_conflict", lock: "Never modify auth" }],
+    blastRadius: { impactPercent: 28.3 },
+    summary: "BLOCKED. 1 constraint conflict. 12 files affected." }
+```
+
+Combines semantic conflict detection + lock-to-file mapping + blast radius + typed constraint awareness into a single risk score (0-100).
+
+---
+
+## AI Patch Firewall (v5.2)
+
+Reviews actual diffs, not just descriptions. Catches things intent review misses:
+
+```
+POST /api/v2/gateway/review-diff
+{
+  "description": "Remove password column",
+  "diff": "diff --git a/migrations/001.sql ..."
+}
+
+→ { verdict: "BLOCK",
+    reviewMode: "unified",
+    intentVerdict: "ALLOW",     ← description alone looks safe
+    diffVerdict: "BLOCK",       ← diff reveals destructive schema change
+    signals: {
+      schemaChange: { score: 12, isDestructive: true },
+      interfaceBreak: { score: 10 },
+      protectedSymbolEdit: { score: 8 },
+      dependencyDrift: { score: 5 },
+      publicApiImpact: { score: 0 }
+    },
+    recommendation: { action: "require_approval" } }
 ```
 
-**ROS2 Guardian Node:** Real-time constraint enforcement for robots. Subscribes to sensor topics, checks constraints at configurable rate, publishes violations, triggers emergency stop.
+**Signal detection:** Interface breaks (removed/changed exports), protected symbol edits in locked zones, dependency drift (critical package add/remove), schema/migration destructive changes, public API route changes.
+
+**Hard escalation rules:** Auto-BLOCK on destructive schema changes, removed API routes, protected symbol edits, or multiple critical findings — regardless of score.
+
+**Unified review:** Merges intent (35%) + diff (65%), takes the stronger verdict. Falls back to intent-only when no diff is available.
 
 ---
 
-## REST API v2 (v5.0)
+## REST API v2
 
-Real-time constraint checking for autonomous systems:
+Real-time constraint checking, patch review, and autonomous systems:
 
 ```bash
-# Single check
-POST /api/v2/check-typed    { metric, value, entity }
+# Patch Gateway (v5.1)
+POST /api/v2/gateway/review        { description, files, useLLM }
+
+# AI Patch Firewall (v5.2)
+POST /api/v2/gateway/review-diff   { description, files, diff, options }
+POST /api/v2/gateway/parse-diff    { diff }
 
-# Batch check (up to 100)
+# Typed constraint checking
+POST /api/v2/check-typed    { metric, value, entity }
 POST /api/v2/check-batch    { checks: [...] }
 
 # SSE streaming (real-time violations)
@@ -335,11 +428,12 @@ POST /api/v2/compiler/compile  { text, autoApply }
 # Code Graph
 GET  /api/v2/graph/blast-radius?file=src/core/memory.js
 GET  /api/v2/graph/lock-map
+POST /api/v2/graph/build
 ```
 
 ---
 
-## 40 MCP Tools
+## 42 MCP Tools
 
 <details>
 <summary><b>Memory</b> — goal, locks, decisions, notes, deploy facts</summary>
@@ -436,6 +530,17 @@ GET  /api/v2/graph/lock-map
 
 </details>
 
+<details>
+<summary><b>Patch Gateway & AI Patch Firewall</b> — change review, diff analysis (v5.1/v5.2)</summary>
+
+| Tool | What it does |
+|------|-------------|
+| `speclock_review_patch` | ALLOW/WARN/BLOCK verdict for proposed changes |
+| `speclock_review_patch_diff` | Diff-native review with signal scoring + unified verdict |
+| `speclock_parse_diff` | Parse unified diff into structured changes (debug/inspect) |
+
+</details>
+
 ---
 
 ## CLI
@@ -508,7 +613,7 @@ The AI opens the file and sees:
 │     AI Tool (Claude Code, Cursor, Bolt.new...)    │
 └────────────┬──────────────────┬──────────────────┘
              │                  │
-   MCP Protocol (40 tools)    npm File-Based
+   MCP Protocol (42 tools)    npm File-Based
              │              (SPECLOCK.md + CLI)
              │                  │
 ┌────────────▼──────────────────▼──────────────────┐
@@ -571,7 +676,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%** | **14 suites, 15 domains** |
+| **Total** | **940** | **99.4%** | **15 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 +716,4 @@ Built by **[Sandeep Roy](https://github.com/sgroy10)**
 
 ---
 
-<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>
+<p align="center"><i>v5.2.0 — 1073 tests, 99.4% pass rate, 42 MCP tools, Patch Gateway, AI Patch Firewall, 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.1.0",
+  "version": "5.2.1",
 
-  "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.",
+  "description": "AI Constraint Engine — AI Patch Firewall. Diff-native review (interface breaks, protected symbols, dependency drift, schema changes, API impact), Patch Gateway (ALLOW/WARN/BLOCK verdicts), Spec Compiler (NL→constraints), Code Graph (blast radius, lock-to-file mapping), Typed constraints, REST API v2, Python SDK, ROS2 integration. 42 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.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)
+SpecLock v5.2.1 — 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.1.0";
+const VERSION = "5.2.1";
 
 // PHI-related keywords for HIPAA filtering
 const PHI_KEYWORDS = [