speclock 1.3.2 → 1.4.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "speclock",
-  "version": "1.3.2",
-  "description": "AI continuity engine — MCP server + CLI that kills AI amnesia. Maintains project memory, enforces constraints, and detects drift across AI coding sessions.",
+  "version": "1.4.1",
+  "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",
   "bin": {

package/src/cli/index.js

@@ -11,6 +11,8 @@ import {
   checkConflict,
   watchRepo,
   createSpecLockMd,
+  guardFile,
+  unguardFile,
 } from "../core/engine.js";
 import { generateContext } from "../core/context.js";
 import { readBrain } from "../core/storage.js";
@@ -69,7 +71,7 @@ function refreshContext(root) {
 
 function printHelp() {
   console.log(`
-SpecLock v1.3.0 — AI Continuity Engine
+SpecLock v1.4.0 — AI Constraint Engine
 Developed by Sandeep Roy (github.com/sgroy10)
 
 Usage: speclock <command> [options]
@@ -80,6 +82,8 @@ Commands:
   goal <text>                     Set or update the project goal
   lock <text> [--tags a,b]        Add a non-negotiable constraint
   lock remove <id>                Remove a lock by ID
+  guard <file> [--lock "text"]    Inject lock warning into a file (NEW)
+  unguard <file>                  Remove lock warning from a file (NEW)
   decide <text> [--tags a,b]      Record a decision
   note <text> [--pinned]          Add a pinned note
   log-change <text> [--files x,y] Log a significant change
@@ -95,11 +99,13 @@ Options:
   --source <user|agent>           Who created this (default: user)
   --files <a.ts,b.ts>             Comma-separated file paths
   --goal <text>                   Goal text (for setup command)
+  --lock <text>                   Lock text (for guard command)
   --project <path>                Project root (for serve)
 
 Examples:
   npx speclock setup --goal "Build PawPalace pet shop"
   npx speclock lock "Never modify auth files"
+  npx speclock guard src/Auth.tsx --lock "Never modify auth files"
   npx speclock check "Adding social login to auth page"
   npx speclock log-change "Built payment system" --files src/pay.tsx
   npx speclock decide "Use Supabase for auth"
@@ -336,6 +342,45 @@ Next steps:
     return;
   }
 
+  // --- GUARD (new: file-level lock) ---
+  if (cmd === "guard") {
+    const flags = parseFlags(args);
+    const filePath = flags._[0];
+    if (!filePath) {
+      console.error("Error: File path is required.");
+      console.error('Usage: speclock guard <file> --lock "constraint text"');
+      process.exit(1);
+    }
+    const lockText = flags.lock || "This file is locked by SpecLock. Do not modify.";
+    const result = guardFile(root, filePath, lockText);
+    if (result.success) {
+      console.log(`Guarded: ${filePath}`);
+      console.log(`Lock warning injected: "${lockText}"`);
+    } else {
+      console.error(result.error);
+      process.exit(1);
+    }
+    return;
+  }
+
+  // --- UNGUARD ---
+  if (cmd === "unguard") {
+    const filePath = args[0];
+    if (!filePath) {
+      console.error("Error: File path is required.");
+      console.error("Usage: speclock unguard <file>");
+      process.exit(1);
+    }
+    const result = unguardFile(root, filePath);
+    if (result.success) {
+      console.log(`Unguarded: ${filePath}`);
+    } else {
+      console.error(result.error);
+      process.exit(1);
+    }
+    return;
+  }
+
   // --- FACTS ---
   if (cmd === "facts") {
     const sub = args.shift();

package/src/core/engine.js

@@ -700,49 +700,156 @@ export async function watchRepo(root) {
 // --- SPECLOCK.md generator (for npm dependency / file-based mode) ---
 
 export function createSpecLockMd(root) {
-  const mdContent = `# SpecLock — Project Memory Active
+  const mdContent = `# SpecLock — AI Constraint Engine Active
 
-This project uses **SpecLock** for AI continuity across sessions.
-Read \`.speclock/context/latest.md\` for full project context before making changes.
+## STOP — Read this before doing ANYTHING.
 
-## Rules (follow on every message)
+**If a file contains "SPECLOCK-GUARD" at the top → DO NOT EDIT IT. Period.**
 
-1. **START OF EVERY MESSAGE**: Read \`.speclock/context/latest.md\` for project memory — goals, constraints (locks), decisions, and recent changes. If the file doesn't exist, run \`npx speclock context\` to generate it.
+## Your Job (Do This Automatically — The User Will NOT Ask)
 
-2. **BEFORE MODIFYING CODE**: Run \`npx speclock check "description of what you plan to change"\`. If a conflict is found (HIGH confidence), STOP and warn the user which constraint would be violated. Do NOT proceed unless the user explicitly says to override.
+### On EVERY message:
+Read \`.speclock/context/latest.md\` first. Always. No exceptions.
 
-3. **WHEN USER SAYS "lock this", "never touch", "don't change", "always", "critical"**: Run \`npx speclock lock "the exact constraint"\`. Confirm: "Locked: [constraint]"
+### 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.
 
-4. **AFTER COMPLETING A FEATURE OR SIGNIFICANT CHANGE**: Run \`npx speclock log-change "what was built/changed" --files file1.tsx,file2.ts\`. Then run \`npx speclock context\` to refresh the context file.
+### Detect constraints from natural language:
+Users will NOT say "lock this." They speak naturally. YOU must detect it.
 
-5. **WHEN AN ARCHITECTURAL DECISION IS MADE**: Run \`npx speclock decide "the decision"\`
+Examples of what users say → what you do:
 
-6. **WHEN USER WANTS TO CHANGE SOMETHING LOCKED**: Warn first: "This is locked: [constraint]. Want me to unlock and proceed?" If confirmed, run \`npx speclock lock remove <lockId>\`
+| 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"\` |
+| "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 |
+| "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 |
 
-## Quick Reference
+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>\`
+3. Make the changes
+4. Ask if they want to re-lock: "Want me to lock this again?"
+
+### After building something:
+\`npx speclock log-change "what you built" --files file1.tsx,file2.ts\`
+
+### When a tech decision is made:
+\`npx speclock decide "the decision"\`
+
+## Commands
 
 \`\`\`bash
-npx speclock status                              # See brain summary
-npx speclock context                             # Regenerate context file
-npx speclock lock "constraint text"              # Add a constraint
-npx speclock lock remove <lockId>                # Remove a constraint
-npx speclock decide "decision text"              # Record a decision
-npx speclock log-change "what changed"           # Log a change
-npx speclock check "what you plan to do"         # Check for conflicts
-npx speclock goal "project goal"                 # Set/update goal
-npx speclock note "important note"               # Add a note
+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 log-change "what changed"           # Log changes
+npx speclock decide "decision"                   # Record a decision
+npx speclock context                             # Refresh context file
+npx speclock status                              # See project summary
 \`\`\`
 
-## How It Works
+## Key Rule
 
-SpecLock maintains a \`.speclock/\` directory with structured project memory:
-- \`brain.json\` — goals, locks, decisions, session history
-- \`events.log\` — immutable audit trail
-- \`context/latest.md\` — human-readable context (read this!)
-
-Every command automatically refreshes the context file so it's always up to date.
+**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.**
 `;
   const filePath = path.join(root, "SPECLOCK.md");
   fs.writeFileSync(filePath, mdContent);
   return filePath;
 }
+
+// --- File-level lock guard ---
+
+const GUARD_MARKERS = {
+  js: { start: "// ", block: false },
+  ts: { start: "// ", block: false },
+  jsx: { start: "// ", block: false },
+  tsx: { start: "// ", block: false },
+  py: { start: "# ", block: false },
+  rb: { start: "# ", block: false },
+  sh: { start: "# ", block: false },
+  css: { start: "/* ", end: " */", block: true },
+  html: { start: "<!-- ", end: " -->", block: true },
+  vue: { start: "<!-- ", end: " -->", block: true },
+  svelte: { start: "<!-- ", end: " -->", block: true },
+  sql: { start: "-- ", block: false },
+};
+
+const GUARD_TAG = "SPECLOCK-GUARD";
+
+function getCommentStyle(filePath) {
+  const ext = path.extname(filePath).slice(1).toLowerCase();
+  return GUARD_MARKERS[ext] || { start: "// ", block: false };
+}
+
+export function guardFile(root, relativeFilePath, lockText) {
+  const fullPath = path.join(root, relativeFilePath);
+  if (!fs.existsSync(fullPath)) {
+    return { success: false, error: `File not found: ${relativeFilePath}` };
+  }
+
+  const content = fs.readFileSync(fullPath, "utf-8");
+  const style = getCommentStyle(fullPath);
+
+  // Check if already guarded
+  if (content.includes(GUARD_TAG)) {
+    return { success: false, error: `File already guarded: ${relativeFilePath}` };
+  }
+
+  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}${"=".repeat(60)}${style.end || ""}`,
+    "",
+  ];
+
+  const guarded = warningLines.join("\n") + content;
+  fs.writeFileSync(fullPath, guarded);
+
+  return { success: true };
+}
+
+export function unguardFile(root, relativeFilePath) {
+  const fullPath = path.join(root, relativeFilePath);
+  if (!fs.existsSync(fullPath)) {
+    return { success: false, error: `File not found: ${relativeFilePath}` };
+  }
+
+  const content = fs.readFileSync(fullPath, "utf-8");
+  if (!content.includes(GUARD_TAG)) {
+    return { success: false, error: `File is not guarded: ${relativeFilePath}` };
+  }
+
+  // Remove everything from first marker line to the blank line after last marker
+  const lines = content.split("\n");
+  let guardEnd = 0;
+  let inGuard = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes(GUARD_TAG)) inGuard = true;
+    if (inGuard && lines[i].includes("=".repeat(60)) && i > 0) {
+      guardEnd = i + 1; // Skip the blank line after
+      if (lines[guardEnd] === "") guardEnd++;
+      break;
+    }
+  }
+
+  const unguarded = lines.slice(guardEnd).join("\n");
+  fs.writeFileSync(fullPath, unguarded);
+
+  return { success: true };
+}