speclock 4.2.0 → 4.3.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "speclock",
-  "version": "4.2.0",
-  "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.",
+  "version": "4.3.1",
+  "description": "AI constraint engine with Gemini LLM universal detection, 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. Cross-platform: MCP + direct API. 31 MCP tools + CLI. Enterprise platform.",
   "type": "module",
   "main": "src/mcp/server.js",
   "bin": {

package/src/cli/index.js

@@ -116,7 +116,7 @@ function refreshContext(root) {
 
 function printHelp() {
   console.log(`
-SpecLock v3.5.0 — AI Constraint Engine (Policy-as-Code + SSO + Dashboard + Telemetry + Auth + RBAC + Encryption)
+SpecLock v4.3.1 — AI Constraint Engine (Gemini LLM + Policy-as-Code + SSO + Dashboard + Telemetry + 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 = "3.5.4";
+const VERSION = "4.3.1";
 
 // PHI-related keywords for HIPAA filtering
 const PHI_KEYWORDS = [

package/src/core/conflict.js

@@ -56,13 +56,95 @@ const GUARD_TAG = "SPECLOCK-GUARD";
 
 // --- Core functions ---
 
-export function checkConflict(root, proposedAction) {
+/**
+ * Detect if the first argument is a file-system path (brain mode)
+ * or natural text (direct mode for cross-platform usage).
+ */
+function isDirectoryPath(str) {
+  if (!str || typeof str !== "string") return false;
+  // Absolute paths: /foo, C:\foo, \\server
+  if (str.startsWith("/") || str.startsWith("\\") || /^[A-Z]:/i.test(str)) return true;
+  // Relative path with separator or current dir
+  if (str === "." || str === ".." || str.includes("/") || str.includes("\\")) return true;
+  return false;
+}
+
+/**
+ * Direct-mode conflict check: action text + lock text(s) directly.
+ * No brain.json needed. Works on any platform.
+ * @param {string} actionText - The proposed action
+ * @param {string|string[]} locks - Lock text or array of lock texts
+ * @returns {Object} Same shape as brain-mode checkConflict
+ */
+function checkConflictDirect(actionText, locks) {
+  const lockList = Array.isArray(locks) ? locks : [locks];
+  const conflicting = [];
+  let maxNonConflictScore = 0;
+
+  for (const lockText of lockList) {
+    const result = analyzeConflict(actionText, lockText);
+    if (result.isConflict) {
+      conflicting.push({
+        id: "direct",
+        text: lockText,
+        matchedKeywords: [],
+        confidence: result.confidence,
+        level: result.level,
+        reasons: result.reasons,
+      });
+    } else if (result.confidence > maxNonConflictScore) {
+      maxNonConflictScore = result.confidence;
+    }
+  }
+
+  if (conflicting.length === 0) {
+    return {
+      hasConflict: false,
+      conflictingLocks: [],
+      _maxNonConflictScore: maxNonConflictScore,
+      analysis: `Checked against ${lockList.length} lock(s). No conflicts detected.`,
+    };
+  }
+
+  conflicting.sort((a, b) => b.confidence - a.confidence);
+  const details = conflicting
+    .map(
+      (c) =>
+        `- [${c.level}] "${c.text}" (confidence: ${c.confidence}%)\n  Reasons: ${c.reasons.join("; ")}`
+    )
+    .join("\n");
+
+  return {
+    hasConflict: true,
+    conflictingLocks: conflicting,
+    _maxNonConflictScore: maxNonConflictScore,
+    analysis: `Potential conflict with ${conflicting.length} lock(s):\n${details}\nReview before proceeding.`,
+  };
+}
+
+/**
+ * Check conflicts. Supports TWO calling patterns:
+ *   1. Brain mode:  checkConflict(rootDir, proposedAction)
+ *   2. Direct mode:  checkConflict(actionText, lockText)
+ *                    checkConflict(actionText, [lock1, lock2, ...])
+ * Automatically detects which mode based on the first argument.
+ */
+export function checkConflict(rootOrAction, proposedActionOrLock) {
+  // Direct mode: first arg is not a directory path → treat as (action, lock)
+  if (!isDirectoryPath(rootOrAction)) {
+    return checkConflictDirect(rootOrAction, proposedActionOrLock);
+  }
+
+  // Brain mode: first arg is a directory path → read locks from brain.json
+  const root = rootOrAction;
+  const proposedAction = proposedActionOrLock;
   const brain = ensureInit(root);
-  const activeLocks = brain.specLock.items.filter((l) => l.active !== false);
+  const activeLocks = (brain.specLock?.items || []).filter((l) => l.active !== false);
   if (activeLocks.length === 0) {
     return {
       hasConflict: false,
       conflictingLocks: [],
+      _maxNonConflictScore: 0,
       analysis: "No active locks. No constraints to check against.",
     };
   }
@@ -124,25 +206,17 @@ export function checkConflict(root, proposedAction) {
 
 /**
  * Async conflict check with LLM fallback for grey-zone cases.
+ * Supports both brain mode and direct mode (same as checkConflict).
  * 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.
+ *   - Everything else → call LLM for universal domain coverage
  */
-export async function checkConflictAsync(root, proposedAction) {
-  // 1. Always run the fast heuristic first
-  const heuristicResult = checkConflict(root, proposedAction);
-
-  // 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
+export async function checkConflictAsync(rootOrAction, proposedActionOrLock) {
+  // 1. Always run the fast heuristic first (handles both brain + direct mode)
+  const heuristicResult = checkConflict(rootOrAction, proposedActionOrLock);
+  const isDirect = !isDirectoryPath(rootOrAction);
+
+  // 2. Fast path: all conflicts are HIGH (>70%) → heuristic is certain, skip LLM
   if (
     heuristicResult.hasConflict &&
     heuristicResult.conflictingLocks.every((c) => c.confidence > 70)
@@ -150,12 +224,27 @@ export async function checkConflictAsync(root, proposedAction) {
     return heuristicResult;
   }
 
-  // 4. Call LLM for everything else — including score 0.
+  // 3. 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);
+    // In direct mode, build activeLocks from the lock text(s) passed directly
+    let llmResult;
+    if (isDirect) {
+      const lockTexts = Array.isArray(proposedActionOrLock)
+        ? proposedActionOrLock
+        : [proposedActionOrLock];
+      const activeLocks = lockTexts.map((t, i) => ({
+        id: `direct-${i}`,
+        text: t,
+        active: true,
+      }));
+      llmResult = await llmCheckConflict(null, rootOrAction, activeLocks);
+    } else {
+      llmResult = await llmCheckConflict(rootOrAction, proposedActionOrLock);
+    }
+
     if (llmResult) {
       // Keep HIGH heuristic conflicts (>70%) — they're already certain
       const highConfidence = heuristicResult.conflictingLocks.filter(

package/src/core/engine.js

@@ -44,6 +44,9 @@ export {
   auditStagedFiles,
 } from "./conflict.js";
 
+// --- Semantic Analysis (direct API for cross-platform usage) ---
+export { analyzeConflict, scoreConflict } from "./semantics.js";
+
 // --- Sessions ---
 export {
   startSession,

package/src/core/semantics.js

@@ -379,8 +379,7 @@ export const CONCEPT_MAP = {
                         "anti-fraud"],
   "posting":           ["transaction", "ledger entry", "journal entry", "record"],
   "reconciliation":    ["balance", "ledger", "account", "transaction", "audit"],
-  "checkout":          ["payment", "cart", "purchase", "transaction", "billing",
-                        "payment processing", "order"],
+  "checkout":          ["cart", "purchase", "order"],
   "revenue":           ["payment", "billing", "income", "sales", "earnings",
                         "transaction"],
   "invoice":           ["billing", "payment", "charge", "transaction", "accounts receivable"],
@@ -425,9 +424,9 @@ export const CONCEPT_MAP = {
 
   // E-commerce
   "cart":              ["checkout", "purchase", "shopping cart"],
-  "payment processing":["payment", "checkout", "billing", "transaction",
+  "payment processing":["payment", "billing", "transaction",
                         "stripe", "payment gateway"],
-  "payment gateway":   ["payment processing", "stripe", "paypal", "checkout",
+  "payment gateway":   ["payment processing", "stripe", "paypal",
                         "billing", "transaction"],
   "product":           ["item", "sku", "catalog", "merchandise", "product listing"],
   "price":             ["pricing", "cost", "amount", "rate", "charge"],
@@ -1386,17 +1385,35 @@ function _compareSubjectsInline(actionText, lockText) {
   };
 }
 
+// --- Performance cache: avoid re-computing action-side analysis across multiple locks ---
+const _actionCache = new Map();
+const _ACTION_CACHE_MAX = 50;
+
+function _getCachedAction(text) {
+  const cached = _actionCache.get(text);
+  if (cached) return cached;
+  const tokens = tokenize(text);
+  const expanded = expandSemantics(tokens.all);
+  const intent = classifyIntent(text);
+  const temporal = detectTemporalModifier(text);
+  const entry = { tokens, expanded, intent, temporal };
+  if (_actionCache.size >= _ACTION_CACHE_MAX) {
+    _actionCache.delete(_actionCache.keys().next().value);
+  }
+  _actionCache.set(text, entry);
+  return entry;
+}
+
 export function scoreConflict({ actionText, lockText }) {
-  const actionTokens = tokenize(actionText);
-  const lockTokens = tokenize(lockText);
+  const actionCached = _getCachedAction(actionText);
+  const actionTokens = actionCached.tokens;
+  const actionExpanded = actionCached.expanded;
+  const actionIntent = actionCached.intent;
+  const hasTemporalMod = actionCached.temporal;
 
-  const actionExpanded = expandSemantics(actionTokens.all);
+  const lockTokens = tokenize(lockText);
   const lockExpanded = expandSemantics(lockTokens.all);
-
-  const actionIntent = classifyIntent(actionText);
   const lockIntent = classifyIntent(lockText);
-
-  const hasTemporalMod = detectTemporalModifier(actionText);
   const lockIsProhibitive = isProhibitiveLock(lockText);
 
   let score = 0;

package/src/core/telemetry.js

@@ -257,7 +257,7 @@ export async function flushToRemote(root) {
   // Build anonymized payload
   const payload = {
     instanceId: summary.instanceId,
-    version: "3.5.0",
+    version: "4.3.1",
     totalCalls: summary.totalCalls,
     avgResponseMs: summary.avgResponseMs,
     conflicts: summary.conflicts,

package/src/dashboard/index.html

@@ -89,7 +89,7 @@
 <div class="header">
   <div>
     <h1><span>SpecLock</span> Dashboard</h1>
-    <div class="meta">v3.5.0 &mdash; AI Constraint Engine</div>
+    <div class="meta">v4.3.1 &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 v3.5.0 &mdash; Developed by Sandeep Roy &mdash; <a href="https://github.com/sgroy10/speclock" style="color:var(--accent)">GitHub</a>
+  SpecLock v4.3.1 &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

@@ -91,7 +91,7 @@ import { fileURLToPath } from "url";
 import _path from "path";
 
 const PROJECT_ROOT = process.env.SPECLOCK_PROJECT_ROOT || process.cwd();
-const VERSION = "3.5.4";
+const VERSION = "4.3.1";
 const AUTHOR = "Sandeep Roy";
 const START_TIME = Date.now();
 
@@ -262,21 +262,63 @@ function createSpecLockServer() {
     return { content: [{ type: "text", text: events.length ? JSON.stringify(events, null, 2) : "No matching events." }] };
   });
 
-  // Tool 12: speclock_check_conflict (v2.5: uses enforcer)
-  server.tool("speclock_check_conflict", "Check if a proposed action conflicts with any active SpecLock. In hard mode, blocks above threshold.", { proposedAction: z.string().min(1).describe("Description of the action") }, async ({ proposedAction }) => {
+  // Tool 12: speclock_check_conflict (v4.3: hybrid heuristic + Gemini LLM)
+  server.tool("speclock_check_conflict", "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.", { proposedAction: z.string().min(1).describe("Description of the action") }, async ({ proposedAction }) => {
     ensureInit(PROJECT_ROOT);
-    const result = enforceConflictCheck(PROJECT_ROOT, proposedAction);
+    // Hybrid check: heuristic first, LLM for grey-zone
+    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 };
+      }
+    }
+
+    // In hard mode with blocking conflict, return isError: true
     if (result.blocked) {
       return { content: [{ type: "text", text: result.analysis }], isError: true };
     }
+
     return { content: [{ type: "text", text: result.analysis }] };
   });
 
-  // Tool 13: speclock_session_briefing
+  // Tool 13: speclock_session_briefing (v4.3: try-catch + rich output)
   server.tool("speclock_session_briefing", "Start a new session and get a full briefing.", { toolName: z.enum(["claude-code", "cursor", "codex", "windsurf", "cline", "unknown"]).default("unknown") }, async ({ toolName }) => {
-    ensureInit(PROJECT_ROOT);
-    const briefing = getSessionBriefing(PROJECT_ROOT, toolName);
-    return { content: [{ type: "text", text: briefing }] };
+    try {
+      ensureInit(PROJECT_ROOT);
+      const briefing = getSessionBriefing(PROJECT_ROOT, toolName);
+      const contextMd = generateContext(PROJECT_ROOT);
+
+      const parts = [];
+      parts.push(`# SpecLock Session Briefing`);
+      parts.push(`Session started (${toolName}). ID: ${briefing.session?.id || "new"}`);
+      parts.push("");
+
+      if (briefing.lastSession) {
+        parts.push("## Last Session");
+        parts.push(`- Tool: **${briefing.lastSession.toolUsed || "unknown"}**`);
+        parts.push(`- Ended: ${briefing.lastSession.endedAt || "unknown"}`);
+        if (briefing.lastSession.summary) parts.push(`- Summary: ${briefing.lastSession.summary}`);
+        parts.push(`- Events: ${briefing.lastSession.eventsInSession || 0}`);
+        parts.push(`- Changes since then: ${briefing.changesSinceLastSession || 0}`);
+        parts.push("");
+      }
+
+      if (briefing.warnings?.length > 0) {
+        parts.push("## Warnings");
+        for (const w of briefing.warnings) parts.push(`- ${w}`);
+        parts.push("");
+      }
+
+      parts.push("---");
+      parts.push(contextMd);
+
+      return { content: [{ type: "text", text: parts.join("\n") }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `# SpecLock Session Briefing\n\nError loading session: ${err.message}\n\nTry running speclock_init first.\n\n---\n*SpecLock v${VERSION}*` }] };
+    }
   });
 
   // Tool 14: speclock_session_summary
@@ -329,24 +371,70 @@ function createSpecLockServer() {
     return { content: [{ type: "text", text: `## Drift Detected\n\n${text}` }] };
   });
 
-  // Tool 19: speclock_health
+  // Tool 19: speclock_health (v4.3: null-safe)
   server.tool("speclock_health", "Health check with completeness score and multi-agent timeline.", {}, async () => {
-    ensureInit(PROJECT_ROOT);
-    const brain = readBrain(PROJECT_ROOT);
-    const events = readEvents(PROJECT_ROOT);
-    let score = 0;
-    const checks = [];
-    if (brain.project.goal) { score += 20; checks.push("- [x] Goal set"); } else checks.push("- [ ] Goal missing");
-    if (brain.state.locks.filter(l => l.active).length > 0) { score += 20; checks.push("- [x] Locks defined"); } else checks.push("- [ ] No active locks");
-    if (brain.state.decisions.length > 0) { score += 15; checks.push("- [x] Decisions recorded"); } else checks.push("- [ ] No decisions");
-    if (brain.state.sessions.length > 0) { score += 15; checks.push("- [x] Sessions tracked"); } else checks.push("- [ ] No sessions");
-    if (brain.deploy?.provider) { score += 10; checks.push("- [x] Deploy facts set"); } else checks.push("- [ ] Deploy facts missing");
-    if (brain.state.notes.length > 0) { score += 10; checks.push("- [x] Notes present"); } else checks.push("- [ ] No notes");
-    if (events.length > 10) { score += 10; checks.push("- [x] Rich event history"); } else checks.push("- [ ] Limited events");
-    const grade = score >= 90 ? "A" : score >= 70 ? "B" : score >= 50 ? "C" : score >= 30 ? "D" : "F";
-    const sessions = brain.state.sessions.slice(-5);
-    const agentTimeline = sessions.length ? "\n\n### Recent Sessions\n" + sessions.map(s => `- **${s.tool || "unknown"}** @ ${s.startedAt}${s.summary ? ": " + s.summary : ""}`).join("\n") : "";
-    return { content: [{ type: "text", text: `## SpecLock Health Check\n\nScore: **${score}/100** (Grade: ${grade})\nEvents: ${brain.events.count} | Reverts: ${brain.state.reverts.length}\n\n### Checks\n${checks.join("\n")}${agentTimeline}\n\n---\n*SpecLock v${VERSION} — Developed by ${AUTHOR}*` }] };
+    try {
+      const brain = ensureInit(PROJECT_ROOT);
+      const activeLocks = (brain.specLock?.items || []).filter((l) => l.active !== false);
+
+      let score = 0;
+      const checks = [];
+
+      if (brain.goal?.text) { score += 20; checks.push("[PASS] Goal is set"); }
+      else checks.push("[MISS] No project goal set");
+
+      if (activeLocks.length > 0) { score += 25; checks.push(`[PASS] ${activeLocks.length} active lock(s)`); }
+      else checks.push("[MISS] No SpecLock constraints defined");
+
+      if ((brain.decisions || []).length > 0) { score += 15; checks.push(`[PASS] ${brain.decisions.length} decision(s) recorded`); }
+      else checks.push("[MISS] No decisions recorded");
+
+      if ((brain.notes || []).length > 0) { score += 10; checks.push(`[PASS] ${brain.notes.length} note(s)`); }
+      else checks.push("[MISS] No notes added");
+
+      const sessionHistory = brain.sessions?.history || [];
+      if (sessionHistory.length > 0) { score += 15; checks.push(`[PASS] ${sessionHistory.length} session(s) in history`); }
+      else checks.push("[MISS] No session history yet");
+
+      const recentChanges = brain.state?.recentChanges || [];
+      if (recentChanges.length > 0) { score += 10; checks.push(`[PASS] ${recentChanges.length} change(s) tracked`); }
+      else checks.push("[MISS] No changes tracked");
+
+      if (brain.facts?.deploy?.provider && brain.facts.deploy.provider !== "unknown") { score += 5; checks.push("[PASS] Deploy facts configured"); }
+      else checks.push("[MISS] Deploy facts not configured");
+
+      // Multi-agent timeline
+      const agentMap = {};
+      for (const session of sessionHistory) {
+        const tool = session.toolUsed || "unknown";
+        if (!agentMap[tool]) agentMap[tool] = { count: 0, lastUsed: "", summaries: [] };
+        agentMap[tool].count++;
+        if (!agentMap[tool].lastUsed || (session.endedAt && session.endedAt > agentMap[tool].lastUsed)) {
+          agentMap[tool].lastUsed = session.endedAt || session.startedAt || "";
+        }
+        if (session.summary && agentMap[tool].summaries.length < 3) {
+          agentMap[tool].summaries.push(session.summary.substring(0, 80));
+        }
+      }
+
+      let agentTimeline = "";
+      if (Object.keys(agentMap).length > 0) {
+        agentTimeline = "\n\n## Multi-Agent Timeline\n" +
+          Object.entries(agentMap)
+            .map(([tool, info]) =>
+              `- **${tool}**: ${info.count} session(s), last active ${info.lastUsed ? info.lastUsed.substring(0, 16) : "unknown"}\n  Recent: ${info.summaries.length > 0 ? info.summaries.map(s => `"${s}"`).join(", ") : "(no summaries)"}`
+            )
+            .join("\n");
+      }
+
+      const grade = score >= 80 ? "A" : score >= 60 ? "B" : score >= 40 ? "C" : score >= 20 ? "D" : "F";
+      const evtCount = brain.events?.count || 0;
+      const revertCount = (brain.state?.reverts || []).length;
+
+      return { content: [{ type: "text", text: `## SpecLock Health Check\n\nScore: **${score}/100** (Grade: ${grade})\nEvents: ${evtCount} | Reverts: ${revertCount}\n\n### Checks\n${checks.join("\n")}${agentTimeline}\n\n---\n*SpecLock v${VERSION} — Developed by ${AUTHOR}*` }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `## SpecLock Health Check\n\nError: ${err.message}\n\nTry running speclock_init first to initialize the project.\n\n---\n*SpecLock v${VERSION}*` }] };
+    }
   });
 
   // Tool 20: speclock_apply_template
@@ -612,7 +700,7 @@ app.get("/.well-known/mcp/server-card.json", (req, res) => {
   res.json({
     name: "SpecLock",
     version: VERSION,
-    description: "AI Constraint Engine — memory + enforcement for AI coding tools. 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. Works with Claude Code, Cursor, Windsurf, Cline, Bolt.new, Lovable.",
+    description: "AI Constraint Engine — memory + enforcement for AI coding tools. Hybrid heuristic + Gemini LLM for universal domain coverage. 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. 31 MCP tools + CLI. Works with Claude Code, Cursor, Windsurf, Cline, Bolt.new, Lovable.",
     author: {
       name: "Sandeep Roy",
       url: "https://github.com/sgroy10",

package/src/mcp/server.js

@@ -100,7 +100,7 @@ const PROJECT_ROOT =
   args.project || process.env.SPECLOCK_PROJECT_ROOT || process.cwd();
 
 // --- MCP Server ---
-const VERSION = "3.5.4";
+const VERSION = "4.3.1";
 const AUTHOR = "Sandeep Roy";
 
 const server = new McpServer(
@@ -521,48 +521,54 @@ server.tool(
       .describe("Which AI tool is being used"),
   },
   async ({ toolName }) => {
-    const briefing = getSessionBriefing(PROJECT_ROOT, toolName);
-    const contextMd = generateContext(PROJECT_ROOT);
-
-    const parts = [];
-
-    // Session info
-    parts.push(`# SpecLock Session Briefing`);
-    parts.push(`Session started (${toolName}). ID: ${briefing.session.id}`);
-    parts.push("");
-
-    // Last session summary
-    if (briefing.lastSession) {
-      parts.push("## Last Session");
-      parts.push(`- Tool: **${briefing.lastSession.toolUsed}**`);
-      parts.push(`- Ended: ${briefing.lastSession.endedAt || "unknown"}`);
-      if (briefing.lastSession.summary)
-        parts.push(`- Summary: ${briefing.lastSession.summary}`);
-      parts.push(
-        `- Events: ${briefing.lastSession.eventsInSession || 0}`
-      );
-      parts.push(
-        `- Changes since then: ${briefing.changesSinceLastSession}`
-      );
+    try {
+      const briefing = getSessionBriefing(PROJECT_ROOT, toolName);
+      const contextMd = generateContext(PROJECT_ROOT);
+
+      const parts = [];
+
+      // Session info
+      parts.push(`# SpecLock Session Briefing`);
+      parts.push(`Session started (${toolName}). ID: ${briefing.session?.id || "new"}`);
       parts.push("");
-    }
 
-    // Warnings
-    if (briefing.warnings.length > 0) {
-      parts.push("## ⚠ Warnings");
-      for (const w of briefing.warnings) {
-        parts.push(`- ${w}`);
+      // Last session summary
+      if (briefing.lastSession) {
+        parts.push("## Last Session");
+        parts.push(`- Tool: **${briefing.lastSession.toolUsed || "unknown"}**`);
+        parts.push(`- Ended: ${briefing.lastSession.endedAt || "unknown"}`);
+        if (briefing.lastSession.summary)
+          parts.push(`- Summary: ${briefing.lastSession.summary}`);
+        parts.push(
+          `- Events: ${briefing.lastSession.eventsInSession || 0}`
+        );
+        parts.push(
+          `- Changes since then: ${briefing.changesSinceLastSession || 0}`
+        );
+        parts.push("");
       }
-      parts.push("");
-    }
 
-    // Full context
-    parts.push("---");
-    parts.push(contextMd);
+      // Warnings
+      if (briefing.warnings?.length > 0) {
+        parts.push("## Warnings");
+        for (const w of briefing.warnings) {
+          parts.push(`- ${w}`);
+        }
+        parts.push("");
+      }
 
-    return {
-      content: [{ type: "text", text: parts.join("\n") }],
-    };
+      // Full context
+      parts.push("---");
+      parts.push(contextMd);
+
+      return {
+        content: [{ type: "text", text: parts.join("\n") }],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: `# SpecLock Session Briefing\n\nError loading session: ${err.message}\n\nTry running speclock_init first.\n\n---\n*SpecLock v${VERSION}*` }],
+      };
+    }
   }
 );
 
@@ -780,68 +786,78 @@ server.tool(
   "Get a health check of the SpecLock setup including completeness score, missing recommended items, and multi-agent session timeline.",
   {},
   async () => {
-    const brain = ensureInit(PROJECT_ROOT);
-    const activeLocks = brain.specLock.items.filter((l) => l.active !== false);
+    try {
+      const brain = ensureInit(PROJECT_ROOT);
+      const activeLocks = (brain.specLock?.items || []).filter((l) => l.active !== false);
 
-    // Calculate health score
-    let score = 0;
-    const checks = [];
+      // Calculate health score
+      let score = 0;
+      const checks = [];
 
-    if (brain.goal.text) { score += 20; checks.push("[PASS] Goal is set"); }
-    else checks.push("[MISS] No project goal set");
+      if (brain.goal?.text) { score += 20; checks.push("[PASS] Goal is set"); }
+      else checks.push("[MISS] No project goal set");
 
-    if (activeLocks.length > 0) { score += 25; checks.push(`[PASS] ${activeLocks.length} active lock(s)`); }
-    else checks.push("[MISS] No SpecLock constraints defined");
+      if (activeLocks.length > 0) { score += 25; checks.push(`[PASS] ${activeLocks.length} active lock(s)`); }
+      else checks.push("[MISS] No SpecLock constraints defined");
 
-    if (brain.decisions.length > 0) { score += 15; checks.push(`[PASS] ${brain.decisions.length} decision(s) recorded`); }
-    else checks.push("[MISS] No decisions recorded");
+      if ((brain.decisions || []).length > 0) { score += 15; checks.push(`[PASS] ${brain.decisions.length} decision(s) recorded`); }
+      else checks.push("[MISS] No decisions recorded");
 
-    if (brain.notes.length > 0) { score += 10; checks.push(`[PASS] ${brain.notes.length} note(s)`); }
-    else checks.push("[MISS] No notes added");
+      if ((brain.notes || []).length > 0) { score += 10; checks.push(`[PASS] ${brain.notes.length} note(s)`); }
+      else checks.push("[MISS] No notes added");
 
-    if (brain.sessions.history.length > 0) { score += 15; checks.push(`[PASS] ${brain.sessions.history.length} session(s) in history`); }
-    else checks.push("[MISS] No session history yet");
+      const sessionHistory = brain.sessions?.history || [];
+      if (sessionHistory.length > 0) { score += 15; checks.push(`[PASS] ${sessionHistory.length} session(s) in history`); }
+      else checks.push("[MISS] No session history yet");
 
-    if (brain.state.recentChanges.length > 0) { score += 10; checks.push(`[PASS] ${brain.state.recentChanges.length} change(s) tracked`); }
-    else checks.push("[MISS] No changes tracked");
+      const recentChanges = brain.state?.recentChanges || [];
+      if (recentChanges.length > 0) { score += 10; checks.push(`[PASS] ${recentChanges.length} change(s) tracked`); }
+      else checks.push("[MISS] No changes tracked");
 
-    if (brain.facts.deploy.provider !== "unknown") { score += 5; checks.push("[PASS] Deploy facts configured"); }
-    else checks.push("[MISS] Deploy facts not configured");
+      if (brain.facts?.deploy?.provider && brain.facts.deploy.provider !== "unknown") { score += 5; checks.push("[PASS] Deploy facts configured"); }
+      else checks.push("[MISS] Deploy facts not configured");
 
-    // Multi-agent timeline
-    const agentMap = {};
-    for (const session of brain.sessions.history) {
-      const tool = session.toolUsed || "unknown";
-      if (!agentMap[tool]) agentMap[tool] = { count: 0, lastUsed: "", summaries: [] };
-      agentMap[tool].count++;
-      if (!agentMap[tool].lastUsed || session.endedAt > agentMap[tool].lastUsed) {
-        agentMap[tool].lastUsed = session.endedAt || session.startedAt;
-      }
-      if (session.summary && agentMap[tool].summaries.length < 3) {
-        agentMap[tool].summaries.push(session.summary.substring(0, 80));
+      // Multi-agent timeline
+      const agentMap = {};
+      for (const session of sessionHistory) {
+        const tool = session.toolUsed || "unknown";
+        if (!agentMap[tool]) agentMap[tool] = { count: 0, lastUsed: "", summaries: [] };
+        agentMap[tool].count++;
+        if (!agentMap[tool].lastUsed || (session.endedAt && session.endedAt > agentMap[tool].lastUsed)) {
+          agentMap[tool].lastUsed = session.endedAt || session.startedAt || "";
+        }
+        if (session.summary && agentMap[tool].summaries.length < 3) {
+          agentMap[tool].summaries.push(session.summary.substring(0, 80));
+        }
       }
-    }
 
-    let agentTimeline = "";
-    if (Object.keys(agentMap).length > 0) {
-      agentTimeline = "\n\n## Multi-Agent Timeline\n" +
-        Object.entries(agentMap)
-          .map(([tool, info]) =>
-            `- **${tool}**: ${info.count} session(s), last active ${info.lastUsed ? info.lastUsed.substring(0, 16) : "unknown"}\n  Recent: ${info.summaries.length > 0 ? info.summaries.map(s => `"${s}"`).join(", ") : "(no summaries)"}`
-          )
-          .join("\n");
-    }
+      let agentTimeline = "";
+      if (Object.keys(agentMap).length > 0) {
+        agentTimeline = "\n\n## Multi-Agent Timeline\n" +
+          Object.entries(agentMap)
+            .map(([tool, info]) =>
+              `- **${tool}**: ${info.count} session(s), last active ${info.lastUsed ? info.lastUsed.substring(0, 16) : "unknown"}\n  Recent: ${info.summaries.length > 0 ? info.summaries.map(s => `"${s}"`).join(", ") : "(no summaries)"}`
+            )
+            .join("\n");
+      }
 
-    const grade = score >= 80 ? "A" : score >= 60 ? "B" : score >= 40 ? "C" : score >= 20 ? "D" : "F";
+      const grade = score >= 80 ? "A" : score >= 60 ? "B" : score >= 40 ? "C" : score >= 20 ? "D" : "F";
+      const evtCount = brain.events?.count || 0;
+      const revertCount = (brain.state?.reverts || []).length;
 
-    return {
-      content: [
-        {
-          type: "text",
-          text: `## SpecLock Health Check\n\nScore: **${score}/100** (Grade: ${grade})\nEvents: ${brain.events.count} | Reverts: ${brain.state.reverts.length}\n\n### Checks\n${checks.join("\n")}${agentTimeline}\n\n---\n*SpecLock v${VERSION} — Developed by ${AUTHOR}*`,
-        },
-      ],
-    };
+      return {
+        content: [
+          {
+            type: "text",
+            text: `## SpecLock Health Check\n\nScore: **${score}/100** (Grade: ${grade})\nEvents: ${evtCount} | Reverts: ${revertCount}\n\n### Checks\n${checks.join("\n")}${agentTimeline}\n\n---\n*SpecLock v${VERSION} — Developed by ${AUTHOR}*`,
+          },
+        ],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: `## SpecLock Health Check\n\nError: ${err.message}\n\nTry running speclock_init first to initialize the project.\n\n---\n*SpecLock v${VERSION}*` }],
+      };
+    }
   }
 );