speclock 1.5.1 → 1.6.0

package/README.md

@@ -218,6 +218,35 @@ Result: [HIGH] Conflict detected (confidence: 85%)
 | `speclock_detect_drift` | Scan changes for constraint violations |
 | `speclock_health` | Health score + multi-agent timeline |
 
+## Auto-Guard: Locks That Actually Work
+
+When you add a lock, SpecLock **automatically finds and guards related files**:
+
+```
+speclock lock "Never modify auth files"
+→ Auto-guarded 2 related file(s):
+  🔒 src/components/Auth.tsx
+  🔒 src/contexts/AuthContext.tsx
+
+speclock lock "Database must always be Supabase"
+→ Auto-guarded 1 related file(s):
+  🔒 src/lib/supabase.ts
+```
+
+The guard injects a warning **directly inside the file**. When the AI opens the file to edit it, it sees:
+```
+// ============================================================
+// SPECLOCK-GUARD — DO NOT MODIFY THIS FILE
+// LOCKED: Never modify auth files
+// THIS FILE IS LOCKED. DO NOT EDIT, CHANGE, OR REWRITE ANY PART OF IT.
+// The user must say "unlock" before this file can be changed.
+// A question is NOT permission. Asking about features is NOT permission.
+// ONLY "unlock" or "remove the lock" is permission to edit this file.
+// ============================================================
+```
+
+Active locks are also embedded in `package.json` — so the AI sees your constraints every time it reads the project config.
+
 ## CLI Commands
 
 ```bash
@@ -226,18 +255,20 @@ speclock setup --goal "Build my app"   # One-shot: init + rules + context
 
 # Memory
 speclock goal <text>                   # Set project goal
-speclock lock <text> [--tags a,b]      # Add a constraint
+speclock lock <text> [--tags a,b]      # Add constraint + auto-guard files
 speclock lock remove <id>              # Remove a lock
 speclock decide <text>                 # Record a decision
 speclock note <text>                   # Add a note
 
+# Enforcement
+speclock check <text>                  # Check for lock conflicts
+speclock guard <file> --lock "text"    # Manually guard a specific file
+speclock unguard <file>                # Remove guard from file
+
 # Tracking
 speclock log-change <text> --files x   # Log a change
 speclock context                       # Regenerate context file
 
-# Enforcement
-speclock check <text>                  # Check for lock conflicts
-
 # Other
 speclock status                        # Show brain summary
 speclock serve [--project <path>]      # Start MCP server
@@ -287,4 +318,4 @@ MIT License - see [LICENSE](LICENSE) file.
 
 ---
 
-*SpecLock v1.5.0 — Because remembering isn't enough. AI needs to respect boundaries.*
+*SpecLock v1.6.0 — Because remembering isn't enough. AI needs to respect boundaries.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speclock",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "AI constraint engine — MCP server + CLI with active enforcement. Memory + guardrails for AI coding tools. Works with Bolt.new, Claude Code, Cursor, Lovable.",
   "type": "module",
   "main": "src/mcp/server.js",

package/src/cli/index.js

@@ -14,6 +14,8 @@ import {
   guardFile,
   unguardFile,
   injectPackageJsonMarker,
+  syncLocksToPackageJson,
+  autoGuardRelatedFiles,
 } from "../core/engine.js";
 import { generateContext } from "../core/context.js";
 import { readBrain } from "../core/storage.js";
@@ -72,7 +74,7 @@ function refreshContext(root) {
 
 function printHelp() {
   console.log(`
-SpecLock v1.5.0 — AI Constraint Engine
+SpecLock v1.6.0 — AI Constraint Engine
 Developed by Sandeep Roy (github.com/sgroy10)
 
 Usage: speclock <command> [options]
@@ -200,16 +202,16 @@ Files created/updated:
   .speclock/brain.json          — Project memory
   .speclock/context/latest.md   — Context for AI (read this)
   SPECLOCK.md                   — AI rules (read this)
-  package.json                  — SpecLock marker added (AI auto-discovery)
+  package.json                  — Active locks embedded (AI auto-discovery)
 
 Next steps:
-  The AI should read SPECLOCK.md for rules and
-  .speclock/context/latest.md for project context.
-
   To add constraints:  npx speclock lock "Never touch auth files"
   To check conflicts:  npx speclock check "Modifying auth page"
   To log changes:      npx speclock log-change "Built landing page"
   To see status:       npx speclock status
+
+Tip: When starting a new chat, tell the AI:
+  "Check speclock status and read the project constraints before doing anything"
 `);
     return;
   }
@@ -250,6 +252,8 @@ Next steps:
       }
       const result = removeLock(root, lockId);
       if (result.removed) {
+        // Sync updated locks to package.json
+        syncLocksToPackageJson(root);
         refreshContext(root);
         console.log(`Lock removed: "${result.lockText}"`);
       } else {
@@ -267,6 +271,22 @@ Next steps:
       process.exit(1);
     }
     const { lockId } = addLock(root, text, parseTags(flags.tags), flags.source || "user");
+
+    // Auto-guard related files (Solution 1)
+    const guardResult = autoGuardRelatedFiles(root, text);
+    if (guardResult.guarded.length > 0) {
+      console.log(`Auto-guarded ${guardResult.guarded.length} related file(s):`);
+      for (const f of guardResult.guarded) {
+        console.log(`  🔒 ${f}`);
+      }
+    }
+
+    // Sync locks to package.json (Solution 2)
+    const syncResult = syncLocksToPackageJson(root);
+    if (syncResult.success) {
+      console.log(`Synced ${syncResult.lockCount} lock(s) to package.json.`);
+    }
+
     refreshContext(root);
     console.log(`Locked (${lockId}): "${text}"`);
     return;

package/src/core/engine.js

@@ -849,9 +849,9 @@ export function guardFile(root, relativeFilePath, lockText) {
   return { success: true };
 }
 
-// --- Package.json marker injection (makes Bolt.new auto-discover SpecLock) ---
+// --- Package.json lock sync (Solution 2: embed active locks directly in package.json) ---
 
-export function injectPackageJsonMarker(root) {
+export function syncLocksToPackageJson(root) {
   const pkgPath = path.join(root, "package.json");
   if (!fs.existsSync(pkgPath)) {
     return { success: false, error: "No package.json found in project root." };
@@ -860,23 +860,159 @@ export function injectPackageJsonMarker(root) {
   try {
     const raw = fs.readFileSync(pkgPath, "utf-8");
     const pkg = JSON.parse(raw);
+    const brain = readBrain(root);
+    if (!brain) {
+      return { success: false, error: "SpecLock not initialized." };
+    }
+
+    const activeLocks = brain.specLock.items
+      .filter((l) => l.active !== false)
+      .map((l) => l.text);
 
-    // Add speclock marker
     pkg.speclock = {
       active: true,
-      rules: "IMPORTANT: Read SPECLOCK.md before making ANY changes to this project. Read .speclock/context/latest.md for project memory, goals, locks, and decisions. Run 'npx speclock check' before modifying locked files.",
+      message: "STOP — This project has SpecLock constraints. Read SPECLOCK.md and .speclock/context/latest.md BEFORE making ANY changes. Run 'npx speclock check' before ALL code changes. If a lock below is violated, STOP and ask user to unlock.",
+      locks: activeLocks,
+      context: ".speclock/context/latest.md",
+      rules: "SPECLOCK.md",
     };
 
-    // Write back with same formatting
     const indent = raw.match(/^(\s+)/m)?.[1] || "  ";
     fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + "\n");
 
-    return { success: true };
+    return { success: true, lockCount: activeLocks.length };
   } catch (err) {
-    return { success: false, error: `Failed to modify package.json: ${err.message}` };
+    return { success: false, error: `Failed to sync locks to package.json: ${err.message}` };
   }
 }
 
+// Backward-compatible alias
+export function injectPackageJsonMarker(root) {
+  return syncLocksToPackageJson(root);
+}
+
+// --- Auto-guard related files (Solution 1: scan project and guard files matching lock keywords) ---
+
+const FILE_KEYWORD_PATTERNS = [
+  { keywords: ["auth", "authentication", "login", "signup", "signin", "sign-in", "sign-up"], patterns: ["**/Auth*", "**/auth*", "**/Login*", "**/login*", "**/SignUp*", "**/signup*", "**/SignIn*", "**/signin*", "**/*Auth*", "**/*auth*"] },
+  { keywords: ["database", "db", "supabase", "firebase", "mongo", "postgres", "sql", "prisma"], patterns: ["**/supabase*", "**/firebase*", "**/database*", "**/db.*", "**/db/**", "**/prisma/**", "**/*Client*", "**/*client*"] },
+  { keywords: ["payment", "pay", "stripe", "billing", "checkout", "subscription"], patterns: ["**/payment*", "**/Payment*", "**/pay*", "**/Pay*", "**/stripe*", "**/Stripe*", "**/billing*", "**/Billing*", "**/checkout*", "**/Checkout*"] },
+  { keywords: ["api", "endpoint", "route", "routes"], patterns: ["**/api/**", "**/routes/**", "**/endpoints/**"] },
+  { keywords: ["config", "configuration", "settings", "env"], patterns: ["**/config*", "**/Config*", "**/settings*", "**/Settings*"] },
+];
+
+function findRelatedFiles(root, lockText) {
+  const lockLower = lockText.toLowerCase();
+  const matchedFiles = [];
+
+  // Find which keyword patterns match this lock text
+  const matchingPatterns = [];
+  for (const group of FILE_KEYWORD_PATTERNS) {
+    const hasMatch = group.keywords.some((kw) => lockLower.includes(kw));
+    if (hasMatch) {
+      matchingPatterns.push(...group.patterns);
+    }
+  }
+
+  if (matchingPatterns.length === 0) return matchedFiles;
+
+  // Scan the src/ directory (and common directories) for matching files
+  const searchDirs = ["src", "app", "components", "pages", "lib", "utils", "contexts", "hooks", "services"];
+
+  for (const dir of searchDirs) {
+    const dirPath = path.join(root, dir);
+    if (!fs.existsSync(dirPath)) continue;
+    scanDirForMatches(root, dirPath, matchingPatterns, matchedFiles);
+  }
+
+  // Also check root-level files
+  try {
+    const rootFiles = fs.readdirSync(root);
+    for (const file of rootFiles) {
+      const fullPath = path.join(root, file);
+      if (!fs.statSync(fullPath).isFile()) continue;
+      const ext = path.extname(file).slice(1).toLowerCase();
+      if (!GUARD_MARKERS[ext]) continue;
+
+      for (const pattern of matchingPatterns) {
+        const simpleMatch = patternMatchesFile(pattern, file);
+        if (simpleMatch) {
+          const rel = path.relative(root, fullPath).replace(/\\/g, "/");
+          if (!matchedFiles.includes(rel)) matchedFiles.push(rel);
+        }
+      }
+    }
+  } catch (_) {}
+
+  return matchedFiles;
+}
+
+function scanDirForMatches(root, dirPath, patterns, results) {
+  try {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dirPath, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name === ".speclock" || entry.name === ".git") continue;
+        scanDirForMatches(root, fullPath, patterns, results);
+      } else if (entry.isFile()) {
+        const ext = path.extname(entry.name).slice(1).toLowerCase();
+        if (!GUARD_MARKERS[ext]) continue;
+        const relPath = path.relative(root, fullPath).replace(/\\/g, "/");
+        for (const pattern of patterns) {
+          if (patternMatchesFile(pattern, relPath) || patternMatchesFile(pattern, entry.name)) {
+            if (!results.includes(relPath)) results.push(relPath);
+            break;
+          }
+        }
+      }
+    }
+  } catch (_) {}
+}
+
+function patternMatchesFile(pattern, filePath) {
+  // Simple glob matching: convert glob to regex
+  // Handle ** (any path), * (any chars in segment)
+  const clean = pattern.replace(/\\/g, "/");
+  const fileLower = filePath.toLowerCase();
+  const patternLower = clean.toLowerCase();
+
+  // Strip leading **/ for simple name matching
+  const namePattern = patternLower.replace(/^\*\*\//, "");
+
+  // Check if pattern is just a name pattern (no path separators)
+  if (!namePattern.includes("/")) {
+    const fileName = fileLower.split("/").pop();
+    // Convert glob * to regex .*
+    const regex = new RegExp("^" + namePattern.replace(/\*/g, ".*") + "$");
+    if (regex.test(fileName)) return true;
+    // Also check if the pattern appears anywhere in the filename
+    const corePattern = namePattern.replace(/\*/g, "");
+    if (corePattern.length > 2 && fileName.includes(corePattern)) return true;
+  }
+
+  // Full path match
+  const regex = new RegExp("^" + patternLower.replace(/\*\*\//g, "(.*/)?").replace(/\*/g, "[^/]*") + "$");
+  return regex.test(fileLower);
+}
+
+export function autoGuardRelatedFiles(root, lockText) {
+  const relatedFiles = findRelatedFiles(root, lockText);
+  const guarded = [];
+  const skipped = [];
+
+  for (const relFile of relatedFiles) {
+    const result = guardFile(root, relFile, lockText);
+    if (result.success) {
+      guarded.push(relFile);
+    } else {
+      skipped.push({ file: relFile, reason: result.error });
+    }
+  }
+
+  return { guarded, skipped, scannedPatterns: relatedFiles.length };
+}
+
 export function unguardFile(root, relativeFilePath) {
   const fullPath = path.join(root, relativeFilePath);
   if (!fs.existsSync(fullPath)) {

package/src/mcp/server.js

@@ -16,6 +16,8 @@ import {
   endSession,
   suggestLocks,
   detectDrift,
+  syncLocksToPackageJson,
+  autoGuardRelatedFiles,
 } from "../core/engine.js";
 import { generateContext, generateContextPack } from "../core/context.js";
 import {
@@ -171,9 +173,19 @@ server.tool(
   },
   async ({ text, tags, source }) => {
     const { lockId } = addLock(PROJECT_ROOT, text, tags, source);
+
+    // Auto-guard related files
+    const guardResult = autoGuardRelatedFiles(PROJECT_ROOT, text);
+    const guardMsg = guardResult.guarded.length > 0
+      ? `\nAuto-guarded ${guardResult.guarded.length} file(s): ${guardResult.guarded.join(", ")}`
+      : "";
+
+    // Sync active locks to package.json
+    syncLocksToPackageJson(PROJECT_ROOT);
+
     return {
       content: [
-        { type: "text", text: `Lock added (${lockId}): "${text}"` },
+        { type: "text", text: `Lock added (${lockId}): "${text}"${guardMsg}` },
       ],
     };
   }
@@ -194,6 +206,8 @@ server.tool(
         isError: true,
       };
     }
+    // Sync updated locks to package.json
+    syncLocksToPackageJson(PROJECT_ROOT);
     return {
       content: [
         {