speclock 4.0.0 → 4.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speclock",
-  "version": "4.0.0",
+  "version": "4.1.1",
   "description": "AI constraint engine with Policy-as-Code DSL, OAuth/OIDC SSO, admin dashboard, telemetry, API key auth, RBAC, AES-256-GCM encryption, hard enforcement, semantic pre-commit, HMAC audit chain, SOC 2/HIPAA compliance. 100% detection, 0% false positives. 31 MCP tools + CLI. Enterprise platform.",
   "type": "module",
   "main": "src/mcp/server.js",

package/src/core/conflict.js

@@ -68,6 +68,7 @@ export function checkConflict(root, proposedAction) {
   }
 
   const conflicting = [];
+  let maxNonConflictScore = 0;
   for (const lock of activeLocks) {
     const result = analyzeConflict(proposedAction, lock.text);
     if (result.isConflict) {
@@ -79,6 +80,8 @@ export function checkConflict(root, proposedAction) {
         level: result.level,
         reasons: result.reasons,
       });
+    } else if (result.confidence > maxNonConflictScore) {
+      maxNonConflictScore = result.confidence;
     }
   }
 
@@ -86,6 +89,7 @@ export function checkConflict(root, proposedAction) {
     return {
       hasConflict: false,
       conflictingLocks: [],
+      _maxNonConflictScore: maxNonConflictScore,
       analysis: `Checked against ${activeLocks.length} active lock(s). No conflicts detected (semantic analysis v2). Proceed with caution.`,
     };
   }
@@ -102,6 +106,7 @@ export function checkConflict(root, proposedAction) {
   const result = {
     hasConflict: true,
     conflictingLocks: conflicting,
+    _maxNonConflictScore: maxNonConflictScore,
     analysis: `Potential conflict with ${conflicting.length} lock(s):\n${details}\nReview before proceeding.`,
   };
 
@@ -118,51 +123,62 @@ export function checkConflict(root, proposedAction) {
 }
 
 /**
- * Async conflict check with LLM fallback for ambiguous cases.
- * Strategy: Run heuristic first (fast, free). If any match falls in the
- * "medium confidence" zone (30–70%), optionally verify with LLM.
- * HIGH confidence (>70%) and NO conflict (<30%) are trusted as-is.
+ * Async conflict check with LLM fallback for grey-zone cases.
+ * Strategy: Run heuristic first (fast, free, offline).
+ *   - Score > 70% on ALL conflicts → trust heuristic (skip LLM)
+ *   - Score == 0 everywhere (no signal at all) → trust heuristic (skip LLM)
+ *   - Score 1–70% on ANY lock → GREY ZONE → call LLM for universal domain coverage
+ * This catches vocabulary gaps where the heuristic has partial/no signal
+ * but an LLM (which knows every domain) would detect the conflict.
  */
 export async function checkConflictAsync(root, proposedAction) {
   // 1. Always run the fast heuristic first
   const heuristicResult = checkConflict(root, proposedAction);
 
-  // 2. If no conflict at all, trust the heuristic
-  if (!heuristicResult.hasConflict) return heuristicResult;
-
-  // 3. Check if any conflicts are in the ambiguous zone (30–70%)
-  const ambiguous = heuristicResult.conflictingLocks.filter(
-    (c) => c.confidence >= 30 && c.confidence <= 70
-  );
-
-  // If all conflicts are HIGH confidence (>70%), trust the heuristic
-  if (ambiguous.length === 0) return heuristicResult;
+  // 2. Determine the max score across ALL locks (conflict + non-conflict)
+  const maxConflictScore = heuristicResult.conflictingLocks.length > 0
+    ? Math.max(...heuristicResult.conflictingLocks.map((c) => c.confidence))
+    : 0;
+  const maxNonConflictScore = heuristicResult._maxNonConflictScore || 0;
+  const maxScore = Math.max(maxConflictScore, maxNonConflictScore);
+
+  // 3. Fast path: all conflicts are HIGH (>70%) → heuristic is certain, skip LLM
+  if (
+    heuristicResult.hasConflict &&
+    heuristicResult.conflictingLocks.every((c) => c.confidence > 70)
+  ) {
+    return heuristicResult;
+  }
 
-  // 4. Try LLM verification for the ambiguous cases
+  // 4. Call LLM for everything else — including score 0.
+  // Score 0 means "heuristic vocabulary doesn't cover this domain",
+  // which is EXACTLY when an LLM (which knows every domain) adds value.
   try {
     const { llmCheckConflict } = await import("./llm-checker.js");
     const llmResult = await llmCheckConflict(root, proposedAction);
     if (llmResult) {
-      // Merge: keep HIGH heuristic results, replace ambiguous with LLM
+      // Keep HIGH heuristic conflicts (>70%) — they're already certain
       const highConfidence = heuristicResult.conflictingLocks.filter(
         (c) => c.confidence > 70
       );
       const llmConflicts = llmResult.conflictingLocks || [];
       const merged = [...highConfidence, ...llmConflicts];
 
-      // Deduplicate by lock text
-      const seen = new Set();
-      const unique = merged.filter((c) => {
-        if (seen.has(c.text)) return false;
-        seen.add(c.text);
-        return true;
-      });
+      // Deduplicate by lock text, keeping the higher-confidence entry
+      const byText = new Map();
+      for (const c of merged) {
+        const existing = byText.get(c.text);
+        if (!existing || c.confidence > existing.confidence) {
+          byText.set(c.text, c);
+        }
+      }
+      const unique = [...byText.values()];
 
       if (unique.length === 0) {
         return {
           hasConflict: false,
           conflictingLocks: [],
-          analysis: `Heuristic flagged ${ambiguous.length} ambiguous case(s), LLM verified as safe. No conflicts.`,
+          analysis: `Heuristic had partial signal, LLM verified as safe. No conflicts.`,
         };
       }
 

package/src/core/llm-checker.js

@@ -1,8 +1,10 @@
 // ===================================================================
 // SpecLock LLM-Powered Conflict Checker (Optional)
-// Uses OpenAI or Anthropic APIs for enterprise-grade detection.
+// Uses Gemini, OpenAI, or Anthropic APIs for universal detection.
 // Zero mandatory dependencies — uses built-in fetch().
 // Falls back gracefully if no API key is configured.
+//
+// Developed by Sandeep Roy (https://github.com/sgroy10)
 // ===================================================================
 
 import { readBrain } from "./storage.js";
@@ -38,9 +40,22 @@ function cacheSet(key, value) {
 // --- Configuration ---
 
 function getConfig(root) {
-  // Priority: env var > brain.json config
-  const apiKey = process.env.SPECLOCK_LLM_KEY || process.env.OPENAI_API_KEY || process.env.ANTHROPIC_API_KEY;
-  const provider = process.env.SPECLOCK_LLM_PROVIDER || "openai"; // "openai" or "anthropic"
+  // Priority: explicit SPECLOCK key > provider-specific keys > brain.json
+  const apiKey =
+    process.env.SPECLOCK_LLM_KEY ||
+    process.env.GEMINI_API_KEY ||
+    process.env.GOOGLE_API_KEY ||
+    process.env.OPENAI_API_KEY ||
+    process.env.ANTHROPIC_API_KEY;
+
+  // Auto-detect provider from which env var is set
+  const provider =
+    process.env.SPECLOCK_LLM_PROVIDER ||
+    (process.env.SPECLOCK_LLM_KEY ? "gemini" : null) ||
+    (process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY ? "gemini" : null) ||
+    (process.env.OPENAI_API_KEY ? "openai" : null) ||
+    (process.env.ANTHROPIC_API_KEY ? "anthropic" : null) ||
+    "gemini"; // default to gemini (cheapest, free tier)
 
   if (apiKey) {
     return { apiKey, provider };
@@ -52,7 +67,7 @@ function getConfig(root) {
     if (brain?.facts?.llm) {
       return {
         apiKey: brain.facts.llm.apiKey,
-        provider: brain.facts.llm.provider || "openai",
+        provider: brain.facts.llm.provider || "gemini",
       };
     }
   } catch (_) {}
@@ -156,6 +171,43 @@ async function callAnthropic(apiKey, userPrompt) {
   }
 }
 
+async function callGemini(apiKey, userPrompt) {
+  const resp = await fetch(
+    `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=${apiKey}`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        contents: [
+          {
+            parts: [
+              { text: SYSTEM_PROMPT + "\n\n" + userPrompt },
+            ],
+          },
+        ],
+        generationConfig: {
+          temperature: 0.1,
+          maxOutputTokens: 1000,
+        },
+      }),
+    }
+  );
+
+  if (!resp.ok) return null;
+  const data = await resp.json();
+  const content = data.candidates?.[0]?.content?.parts?.[0]?.text;
+  if (!content) return null;
+
+  try {
+    return JSON.parse(content);
+  } catch (_) {
+    // Try to extract JSON from markdown code block
+    const match = content.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (match) return JSON.parse(match[1]);
+    return null;
+  }
+}
+
 // --- Main export ---
 
 /**
@@ -199,7 +251,9 @@ export async function llmCheckConflict(root, proposedAction, activeLocks) {
   // Call LLM
   let llmResult = null;
   try {
-    if (config.provider === "anthropic") {
+    if (config.provider === "gemini") {
+      llmResult = await callGemini(config.apiKey, userPrompt);
+    } else if (config.provider === "anthropic") {
       llmResult = await callAnthropic(config.apiKey, userPrompt);
     } else {
       llmResult = await callOpenAI(config.apiKey, userPrompt);

package/src/mcp/server.js

@@ -470,10 +470,10 @@ server.tool(
 // CONTINUITY PROTECTION TOOLS
 // ========================================
 
-// Tool 12: speclock_check_conflict (v2.5: uses enforcer — hard mode returns isError)
+// Tool 12: speclock_check_conflict (v4.1: hybrid heuristic + Gemini LLM)
 server.tool(
   "speclock_check_conflict",
-  "Check if a proposed action conflicts with any active SpecLock. Use before making significant changes. In hard enforcement mode, conflicts above the threshold will BLOCK the action (isError: true).",
+  "Check if a proposed action conflicts with any active SpecLock. Uses fast heuristic + Gemini LLM for universal domain coverage. In hard enforcement mode, conflicts above the threshold will BLOCK the action (isError: true).",
   {
     proposedAction: z
       .string()
@@ -481,18 +481,18 @@ server.tool(
       .describe("Description of the action you plan to take"),
   },
   async ({ proposedAction }) => {
-    // Try LLM-enhanced check first, fall back to heuristic enforcer
-    let result;
-    try {
-      const { llmCheckConflict } = await import("../core/llm-checker.js");
-      const llmResult = await llmCheckConflict(PROJECT_ROOT, proposedAction);
-      if (llmResult) {
-        result = llmResult;
+    // Hybrid check: heuristic first, LLM for grey-zone (1-70%)
+    let result = await checkConflictAsync(PROJECT_ROOT, proposedAction);
+
+    // If async hybrid returned no conflict, also check enforcer for hard mode
+    if (!result.hasConflict) {
+      const enforced = enforceConflictCheck(PROJECT_ROOT, proposedAction);
+      if (enforced.blocked) {
+        return {
+          content: [{ type: "text", text: enforced.analysis }],
+          isError: true,
+        };
       }
-    } catch (_) {}
-
-    if (!result) {
-      result = enforceConflictCheck(PROJECT_ROOT, proposedAction);
     }
 
     // In hard mode with blocking conflict, return isError: true