speclock 1.5.0 → 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.0",
+  "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

@@ -702,85 +702,91 @@ export async function watchRepo(root) {
 export function createSpecLockMd(root) {
   const mdContent = `# SpecLock — AI Constraint Engine Active
 
-## STOP — Read this before doing ANYTHING.
+## CRITICAL: LOCKED FILES CANNOT BE MODIFIED
 
-This project has SpecLock installed. It tracks project memory, goals, constraints (locks), and decisions.
+If a lock says "never modify auth files" then you CANNOT modify those files.
+Not now. Not later. Not if the user asks a question. Not for any reason.
 
-**Step 1:** Read \`.speclock/context/latest.md\` — this contains the full project memory.
-**Step 2:** Follow ALL rules below on every message.
+**The ONLY way to modify a locked file:** The user must explicitly say "unlock" or "remove the lock."
+Asking a question is NOT permission. Talking about a feature is NOT permission.
+ONLY the words "unlock", "remove the lock", or "I changed my mind about the lock" count.
 
-**If a file contains "SPECLOCK-GUARD" at the top → DO NOT EDIT IT. Period.**
+**If a file contains "SPECLOCK-GUARD" at the top → DO NOT EDIT IT. No exceptions.**
 
-## Returning to This Project? (New Chat Session)
+## On EVERY message — do this FIRST:
+
+1. Read \`.speclock/context/latest.md\` for project memory
+2. Run \`npx speclock check "what you plan to do"\` BEFORE any code changes
+3. If conflict found → STOP. Tell user. Do NOT proceed. Do NOT ask "should I proceed?"
+4. Wait for user to explicitly say "unlock" or "remove the lock" before touching locked files
 
-If you are starting a new chat on this project:
-1. SpecLock is ALREADY installed — do NOT reinstall it
-2. The \`.speclock/\` directory contains all project memory
-3. Run \`npx speclock status\` to see the current state
-4. Read \`.speclock/context/latest.md\` for full context (goals, locks, decisions, history)
-5. Respect ALL existing locks and constraints before making any changes
+## Returning to This Project? (New Chat Session)
 
-**DO NOT say "SpecLock is not installed" — if you can read this file, it IS installed.**
+SpecLock is ALREADY installed. Do NOT reinstall it. Do NOT say "it's not installed."
+1. Run \`npx speclock status\` to see current locks and decisions
+2. Read \`.speclock/context/latest.md\` for full project context
+3. Respect ALL existing locks — they carry over between sessions
 
-## Your Job (Do This Automatically — The User Will NOT Ask)
+## What Counts as Permission to Bypass a Lock?
 
-### On EVERY message:
-Read \`.speclock/context/latest.md\` first. Always. No exceptions.
+| User says | Is this permission? | What you do |
+|-----------|-------------------|-------------|
+| "add google auth" | NO — lock still active | Say "Auth files are locked. Want me to unlock them first?" |
+| "is speclock initialized?" | NO — just a question | Answer the question. Do NOT change any code. |
+| "yeah go ahead" (after you warned about lock) | NO — too vague | Say "To modify locked files, please confirm: unlock the auth files" |
+| "ok unlock the auth files" | YES — explicit unlock | Run \`npx speclock lock remove <lockId>\`, then make changes |
+| "remove the lock on auth" | YES — explicit unlock | Run \`npx speclock lock remove <lockId>\`, then make changes |
+| "I changed my mind, you can edit auth" | YES — explicit unlock | Run \`npx speclock lock remove <lockId>\`, then make changes |
 
-### Before changing ANY code:
-Run \`npx speclock check "what you plan to do"\` BEFORE writing code.
-If conflict → STOP. Tell the user. Do NOT proceed.
+**When in doubt: DO NOT modify locked files. Ask for clarification instead.**
 
-### Detect constraints from natural language:
-Users will NOT say "lock this." They speak naturally. YOU must detect it.
+## Detect Constraints from Natural Language
 
-Examples of what users say → what you do:
+Users will NOT say "lock this." They speak naturally. YOU must detect intent and lock automatically.
 
 | User says | You do |
 |-----------|--------|
-| "don't touch the auth" | \`npx speclock lock "Never modify auth files"\` + \`npx speclock guard src/components/Auth.tsx --lock "Never modify auth files"\` |
+| "don't touch the auth" | \`npx speclock lock "Never modify auth files"\` + \`npx speclock guard\` the auth files |
 | "database is firebase, don't change it" | \`npx speclock lock "Database must always be Firebase"\` |
-| "leave the payment system alone" | \`npx speclock lock "Never modify payment system"\` + guard the payment files |
+| "leave the payment system alone" | \`npx speclock lock "Never modify payment system"\` + guard payment files |
 | "always use Supabase" | \`npx speclock lock "Always use Supabase"\` |
-| "the API is done, don't mess with it" | \`npx speclock lock "Never modify API endpoints"\` + guard the API files |
+| "the API is done, don't mess with it" | \`npx speclock lock "Never modify API endpoints"\` + guard API files |
 
 When you lock something, ALSO guard the specific files:
 \`npx speclock guard <filepath> --lock "the constraint"\`
-This injects a warning directly into the file so it cannot be missed.
 
-### When user wants to change something locked:
-User might say "actually, let me change auth" or "ok modify the database."
-1. Warn: "This is currently locked: [constraint]. Want me to unlock?"
-2. If they confirm → \`npx speclock lock remove <lockId>\` + \`npx speclock unguard <file>\`
+## Unlocking (When User Gives Explicit Permission)
+
+1. User says "unlock auth" or "remove the auth lock" or "I changed my mind about auth"
+2. Run \`npx speclock lock remove <lockId>\` + \`npx speclock unguard <file>\`
 3. Make the changes
-4. Ask if they want to re-lock: "Want me to lock this again?"
+4. Ask: "Want me to re-lock this?"
 
-### After building something:
-\`npx speclock log-change "what you built" --files file1.tsx,file2.ts\`
+## After Building Something
 
-### When a tech decision is made:
-\`npx speclock decide "the decision"\`
+\`npx speclock log-change "what you built" --files file1.tsx,file2.ts\`
 
 ## Commands
 
 \`\`\`bash
-npx speclock status                              # CHECK IF ALREADY SET UP
+npx speclock status                              # Check current state
 npx speclock check "what you plan to do"         # ALWAYS RUN BEFORE CHANGES
 npx speclock lock "constraint"                   # Lock a constraint
 npx speclock guard <file> --lock "constraint"    # Protect a specific file
 npx speclock unguard <file>                      # Remove file protection
-npx speclock lock remove <lockId>                # Unlock a constraint
+npx speclock lock remove <lockId>                # Unlock (only after explicit permission)
 npx speclock log-change "what changed"           # Log changes
 npx speclock decide "decision"                   # Record a decision
 npx speclock context                             # Refresh context file
 \`\`\`
 
-## Key Rule
+## Key Rules
 
-**The user will NEVER tell you to run these commands. You run them automatically.**
-**The user will NEVER say "lock this." You detect the intent and lock it yourself.**
-**The user will NEVER say "check constraints." You check before EVERY code change.**
-**If this file exists, SpecLock is installed. Do NOT reinstall. Just read the context and follow the rules.**
+1. **A question is NOT permission to bypass a lock.**
+2. **Run speclock check before EVERY code change, EVERY time, EVERY message.**
+3. **If you already warned about a conflict, the lock is STILL active until explicitly removed.**
+4. **The user will NEVER tell you to run these commands. You run them automatically.**
+5. **If this file exists, SpecLock is installed. Do NOT reinstall.**
 `;
   const filePath = path.join(root, "SPECLOCK.md");
   fs.writeFileSync(filePath, mdContent);
@@ -828,9 +834,11 @@ export function guardFile(root, relativeFilePath, lockText) {
   const warningLines = [
     `${style.start}${"=".repeat(60)}${style.end || ""}`,
     `${style.start}${GUARD_TAG} — DO NOT MODIFY THIS FILE${style.end || ""}`,
-    `${style.start}LOCKED BY SPECLOCK: ${lockText}${style.end || ""}`,
-    `${style.start}Run "npx speclock check" before ANY changes to this file.${style.end || ""}`,
-    `${style.start}If you modify this file, you are VIOLATING a project constraint.${style.end || ""}`,
+    `${style.start}LOCKED: ${lockText}${style.end || ""}`,
+    `${style.start}THIS FILE IS LOCKED. DO NOT EDIT, CHANGE, OR REWRITE ANY PART OF IT.${style.end || ""}`,
+    `${style.start}The user must say "unlock" before this file can be changed.${style.end || ""}`,
+    `${style.start}A question is NOT permission. Asking about features is NOT permission.${style.end || ""}`,
+    `${style.start}ONLY "unlock" or "remove the lock" is permission to edit this file.${style.end || ""}`,
     `${style.start}${"=".repeat(60)}${style.end || ""}`,
     "",
   ];
@@ -841,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." };
@@ -852,21 +860,157 @@ 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) {

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: [
         {