speclock 1.5.1 → 1.7.0

package/README.md

@@ -174,10 +174,10 @@ Result: [HIGH] Conflict detected (confidence: 85%)
 | Mode | Platforms | How It Works |
 |------|-----------|--------------|
 | **MCP Remote** | Lovable, bolt.diy, Base44 | Connect via URL — no install needed |
-| **MCP Local** | Claude Code, Cursor, Windsurf, Cline | `npx speclock serve` — 19 tools via MCP |
+| **MCP Local** | Claude Code, Cursor, Windsurf, Cline | `npx speclock serve` — 22 tools via MCP |
 | **npm File-Based** | Bolt.new, Aider, Rocket.new | `npx speclock setup` — AI reads SPECLOCK.md + uses CLI |
 
-## 19 MCP Tools
+## 22 MCP Tools
 
 ### Memory Management
 | Tool | Purpose |
@@ -218,26 +218,76 @@ Result: [HIGH] Conflict detected (confidence: 85%)
 | `speclock_detect_drift` | Scan changes for constraint violations |
 | `speclock_health` | Health score + multi-agent timeline |
 
+### Templates, Reports & Enforcement (v1.7.0)
+| Tool | Purpose |
+|------|---------|
+| `speclock_apply_template` | Apply pre-built constraint templates (nextjs, react, express, etc.) |
+| `speclock_report` | Violation report — blocked change stats |
+| `speclock_audit` | Audit staged files against active locks |
+
+## 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
 # Setup
-speclock setup --goal "Build my app"   # One-shot: init + rules + context
+speclock setup --goal "Build my app" --template nextjs  # One-shot setup + template
 
 # 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
+
+# Templates (v1.7.0)
+speclock template list                 # List available templates
+speclock template apply <name>         # Apply: nextjs, react, express, supabase, stripe, security-hardened
+
+# Violation Report (v1.7.0)
+speclock report                        # Show violation stats + most tested locks
+
+# Git Pre-commit Hook (v1.7.0)
+speclock hook install                  # Install pre-commit hook
+speclock hook remove                   # Remove pre-commit hook
+speclock audit                         # Audit staged files against locks
+
 # 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
@@ -252,7 +302,7 @@ speclock watch                         # Start file watcher
 └──────────────┬──────────────────┬────────────────────┘
                │                  │
      MCP Protocol          File-Based (npm)
-    (19 tool calls)      (reads SPECLOCK.md +
+    (22 tool calls)      (reads SPECLOCK.md +
                         .speclock/context/latest.md,
                          runs CLI commands)
                │                  │
@@ -287,4 +337,4 @@ MIT License - see [LICENSE](LICENSE) file.
 
 ---
 
-*SpecLock v1.5.0 — Because remembering isn't enough. AI needs to respect boundaries.*
+*SpecLock v1.7.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.7.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,9 +14,16 @@ import {
   guardFile,
   unguardFile,
   injectPackageJsonMarker,
+  syncLocksToPackageJson,
+  autoGuardRelatedFiles,
+  listTemplates,
+  applyTemplate,
+  generateReport,
+  auditStagedFiles,
 } from "../core/engine.js";
 import { generateContext } from "../core/context.js";
 import { readBrain } from "../core/storage.js";
+import { installHook, removeHook } from "../core/hooks.js";
 
 // --- Argument parsing ---
 
@@ -72,23 +79,29 @@ function refreshContext(root) {
 
 function printHelp() {
   console.log(`
-SpecLock v1.5.0 — AI Constraint Engine
+SpecLock v1.7.0 — AI Constraint Engine
 Developed by Sandeep Roy (github.com/sgroy10)
 
 Usage: speclock <command> [options]
 
 Commands:
-  setup [--goal <text>]           Full setup: init + SPECLOCK.md + context
+  setup [--goal <text>] [--template <name>]  Full setup: init + SPECLOCK.md + context
   init                            Initialize SpecLock in current directory
   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)
+  guard <file> [--lock "text"]    Inject lock warning into a file
+  unguard <file>                  Remove lock warning from a file
   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
   check <text>                    Check if action conflicts with locks
+  template list                   List available constraint templates
+  template apply <name>           Apply a template (nextjs, react, etc.)
+  report                          Show violation report + stats
+  hook install                    Install git pre-commit hook
+  hook remove                     Remove git pre-commit hook
+  audit                           Audit staged files against locks
   context                         Generate and print context pack
   facts deploy [--provider X]     Set deployment facts
   watch                           Start file watcher (auto-track changes)
@@ -100,17 +113,20 @@ 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)
+  --template <name>               Template to apply during setup
   --lock <text>                   Lock text (for guard command)
   --project <path>                Project root (for serve)
 
+Templates: nextjs, react, express, supabase, stripe, security-hardened
+
 Examples:
-  npx speclock setup --goal "Build PawPalace pet shop"
+  npx speclock setup --goal "Build PawPalace pet shop" --template nextjs
   npx speclock lock "Never modify auth files"
-  npx speclock guard src/Auth.tsx --lock "Never modify auth files"
+  npx speclock template apply supabase
   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"
-  npx speclock context
+  npx speclock report
+  npx speclock hook install
+  npx speclock audit
   npx speclock status
 `);
 }
@@ -188,11 +204,21 @@ async function main() {
       console.log("Injected SpecLock marker into package.json.");
     }
 
-    // 5. Generate context
+    // 5. Apply template if specified
+    if (flags.template) {
+      const result = applyTemplate(root, flags.template);
+      if (result.applied) {
+        console.log(`Applied template "${result.displayName}": ${result.locksAdded} lock(s), ${result.decisionsAdded} decision(s).`);
+      } else {
+        console.error(`Template error: ${result.error}`);
+      }
+    }
+
+    // 6. Generate context
     generateContext(root);
     console.log("Generated .speclock/context/latest.md");
 
-    // 6. Print summary
+    // 7. Print summary
     console.log(`
 SpecLock is ready!
 
@@ -200,16 +226,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 +276,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 +295,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;
@@ -335,8 +379,8 @@ Next steps:
       console.log(`\nCONFLICT DETECTED`);
       console.log("=".repeat(50));
       for (const lock of result.conflictingLocks) {
-        console.log(`  [${lock.confidence}] "${lock.text}"`);
-        console.log(`  Confidence: ${lock.score}%`);
+        console.log(`  [${lock.level}] "${lock.text}"`);
+        console.log(`  Confidence: ${lock.confidence}%`);
         if (lock.reasons && lock.reasons.length > 0) {
           for (const reason of lock.reasons) {
             console.log(`  - ${reason}`);
@@ -440,6 +484,119 @@ Next steps:
     return;
   }
 
+  // --- TEMPLATE ---
+  if (cmd === "template") {
+    const sub = args[0];
+    if (sub === "list" || !sub) {
+      const templates = listTemplates();
+      console.log("\nAvailable Templates:");
+      console.log("=".repeat(50));
+      for (const t of templates) {
+        console.log(`  ${t.name.padEnd(20)} ${t.displayName} — ${t.description}`);
+        console.log(`  ${"".padEnd(20)} ${t.lockCount} lock(s), ${t.decisionCount} decision(s)`);
+        console.log("");
+      }
+      console.log("Apply: npx speclock template apply <name>");
+      return;
+    }
+    if (sub === "apply") {
+      const name = args[1];
+      if (!name) {
+        console.error("Error: Template name is required.");
+        console.error("Usage: speclock template apply <name>");
+        console.error("Run 'speclock template list' to see available templates.");
+        process.exit(1);
+      }
+      const result = applyTemplate(root, name);
+      if (result.applied) {
+        refreshContext(root);
+        console.log(`Template "${result.displayName}" applied successfully!`);
+        console.log(`  Locks added: ${result.locksAdded}`);
+        console.log(`  Decisions added: ${result.decisionsAdded}`);
+      } else {
+        console.error(result.error);
+        process.exit(1);
+      }
+      return;
+    }
+    console.error(`Unknown template command: ${sub}`);
+    console.error("Usage: speclock template list | speclock template apply <name>");
+    process.exit(1);
+  }
+
+  // --- REPORT ---
+  if (cmd === "report") {
+    const report = generateReport(root);
+    console.log("\nSpecLock Violation Report");
+    console.log("=".repeat(50));
+    console.log(`Total violations blocked: ${report.totalViolations}`);
+    if (report.timeRange) {
+      console.log(`Period: ${report.timeRange.from.substring(0, 10)} to ${report.timeRange.to.substring(0, 10)}`);
+    }
+    if (report.mostTestedLocks.length > 0) {
+      console.log("\nMost tested locks:");
+      for (const lock of report.mostTestedLocks) {
+        console.log(`  ${lock.count}x — "${lock.text}"`);
+      }
+    }
+    if (report.recentViolations.length > 0) {
+      console.log("\nRecent violations:");
+      for (const v of report.recentViolations) {
+        console.log(`  [${v.at.substring(0, 19)}] ${v.topLevel} (${v.topConfidence}%) — "${v.action.substring(0, 60)}"`);
+      }
+    }
+    console.log(`\n${report.summary}`);
+    return;
+  }
+
+  // --- HOOK ---
+  if (cmd === "hook") {
+    const sub = args[0];
+    if (sub === "install") {
+      const result = installHook(root);
+      if (result.success) {
+        console.log(result.message);
+      } else {
+        console.error(result.error);
+        process.exit(1);
+      }
+      return;
+    }
+    if (sub === "remove") {
+      const result = removeHook(root);
+      if (result.success) {
+        console.log(result.message);
+      } else {
+        console.error(result.error);
+        process.exit(1);
+      }
+      return;
+    }
+    console.error("Usage: speclock hook install | speclock hook remove");
+    process.exit(1);
+  }
+
+  // --- AUDIT ---
+  if (cmd === "audit") {
+    const result = auditStagedFiles(root);
+    if (result.passed) {
+      console.log(result.message);
+      process.exit(0);
+    } else {
+      console.log("\nSPECLOCK AUDIT FAILED");
+      console.log("=".repeat(50));
+      for (const v of result.violations) {
+        console.log(`  [${v.severity}] ${v.file}`);
+        console.log(`    Lock: ${v.lockText}`);
+        console.log(`    Reason: ${v.reason}`);
+        console.log("");
+      }
+      console.log(result.message);
+      console.log("Commit blocked. Unlock files or unstage them to proceed.");
+      process.exit(1);
+    }
+  }
+
   // --- STATUS ---
   if (cmd === "status") {
     showStatus(root);

package/src/core/engine.js

@@ -13,8 +13,10 @@ import {
   addRecentChange,
   addRevert,
   readEvents,
+  addViolation,
 } from "./storage.js";
-import { hasGit, getHead, getDefaultBranch, captureDiff } from "./git.js";
+import { hasGit, getHead, getDefaultBranch, captureDiff, getStagedFiles } from "./git.js";
+import { getTemplateNames, getTemplate } from "./templates.js";
 
 // --- Internal helpers ---
 
@@ -385,11 +387,23 @@ export function checkConflict(root, proposedAction) {
     )
     .join("\n");
 
-  return {
+  const result = {
     hasConflict: true,
     conflictingLocks: conflicting,
     analysis: `Potential conflict with ${conflicting.length} lock(s):\n${details}\nReview before proceeding.`,
   };
+
+  // Record violation for reporting
+  addViolation(brain, {
+    at: nowIso(),
+    action: proposedAction,
+    locks: conflicting.map((c) => ({ id: c.id, text: c.text, confidence: c.confidence, level: c.level })),
+    topLevel: conflicting[0].level,
+    topConfidence: conflicting[0].confidence,
+  });
+  writeBrain(root, brain);
+
+  return result;
 }
 
 // --- Auto-lock suggestions ---
@@ -777,6 +791,11 @@ npx speclock unguard <file>                      # Remove file protection
 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 template list                       # List constraint templates
+npx speclock template apply <name>               # Apply a template (nextjs, react, etc.)
+npx speclock report                              # Show violation stats
+npx speclock hook install                        # Install git pre-commit hook
+npx speclock audit                               # Audit staged files vs locks
 npx speclock context                             # Refresh context file
 \`\`\`
 
@@ -849,9 +868,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 +879,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)) {
@@ -906,3 +1061,188 @@ export function unguardFile(root, relativeFilePath) {
 
   return { success: true };
 }
+
+// --- Constraint Templates ---
+
+export function listTemplates() {
+  const names = getTemplateNames();
+  return names.map((name) => {
+    const t = getTemplate(name);
+    return {
+      name: t.name,
+      displayName: t.displayName,
+      description: t.description,
+      lockCount: t.locks.length,
+      decisionCount: t.decisions.length,
+    };
+  });
+}
+
+export function applyTemplate(root, templateName) {
+  const template = getTemplate(templateName);
+  if (!template) {
+    return { applied: false, error: `Template not found: "${templateName}". Available: ${getTemplateNames().join(", ")}` };
+  }
+
+  ensureInit(root);
+
+  let locksAdded = 0;
+  let decisionsAdded = 0;
+
+  for (const lockText of template.locks) {
+    addLock(root, lockText, [template.name], "agent");
+    autoGuardRelatedFiles(root, lockText);
+    locksAdded++;
+  }
+
+  for (const decText of template.decisions) {
+    addDecision(root, decText, [template.name], "agent");
+    decisionsAdded++;
+  }
+
+  syncLocksToPackageJson(root);
+
+  return {
+    applied: true,
+    templateName: template.name,
+    displayName: template.displayName,
+    locksAdded,
+    decisionsAdded,
+  };
+}
+
+// --- Violation Report ---
+
+export function generateReport(root) {
+  const brain = ensureInit(root);
+  const violations = brain.state.violations || [];
+
+  if (violations.length === 0) {
+    return {
+      totalViolations: 0,
+      violationsByLock: {},
+      mostTestedLocks: [],
+      recentViolations: [],
+      summary: "No violations recorded yet. SpecLock is watching.",
+    };
+  }
+
+  // Count violations per lock
+  const byLock = {};
+  for (const v of violations) {
+    for (const lock of v.locks) {
+      if (!byLock[lock.text]) {
+        byLock[lock.text] = { count: 0, lockId: lock.id, text: lock.text };
+      }
+      byLock[lock.text].count++;
+    }
+  }
+
+  // Sort by count descending
+  const mostTested = Object.values(byLock).sort((a, b) => b.count - a.count);
+
+  // Recent 10
+  const recent = violations.slice(0, 10).map((v) => ({
+    at: v.at,
+    action: v.action,
+    topLevel: v.topLevel,
+    topConfidence: v.topConfidence,
+    lockCount: v.locks.length,
+  }));
+
+  // Time range
+  const oldest = violations[violations.length - 1];
+  const newest = violations[0];
+
+  return {
+    totalViolations: violations.length,
+    timeRange: { from: oldest.at, to: newest.at },
+    violationsByLock: byLock,
+    mostTestedLocks: mostTested.slice(0, 5),
+    recentViolations: recent,
+    summary: `SpecLock blocked ${violations.length} violation(s). Most tested lock: "${mostTested[0].text}" (${mostTested[0].count} blocks).`,
+  };
+}
+
+// --- Pre-commit Audit ---
+
+export function auditStagedFiles(root) {
+  const brain = ensureInit(root);
+  const activeLocks = brain.specLock.items.filter((l) => l.active !== false);
+
+  if (activeLocks.length === 0) {
+    return { passed: true, violations: [], checkedFiles: 0, activeLocks: 0, message: "No active locks. Audit passed." };
+  }
+
+  const stagedFiles = getStagedFiles(root);
+  if (stagedFiles.length === 0) {
+    return { passed: true, violations: [], checkedFiles: 0, activeLocks: activeLocks.length, message: "No staged files. Audit passed." };
+  }
+
+  const violations = [];
+
+  for (const file of stagedFiles) {
+    // Check 1: Does the file have a SPECLOCK-GUARD header?
+    const fullPath = path.join(root, file);
+    if (fs.existsSync(fullPath)) {
+      try {
+        const content = fs.readFileSync(fullPath, "utf-8");
+        if (content.includes(GUARD_TAG)) {
+          violations.push({
+            file,
+            reason: "File has SPECLOCK-GUARD header — it is locked and must not be modified",
+            lockText: "(file-level guard)",
+            severity: "HIGH",
+          });
+          continue;
+        }
+      } catch (_) {}
+    }
+
+    // Check 2: Does the file path match any lock keywords?
+    const fileLower = file.toLowerCase();
+    for (const lock of activeLocks) {
+      const lockLower = lock.text.toLowerCase();
+      const lockHasNegation = hasNegation(lockLower);
+      if (!lockHasNegation) continue;
+
+      // Check if any FILE_KEYWORD_PATTERNS keywords from the lock match this file
+      for (const group of FILE_KEYWORD_PATTERNS) {
+        const lockMatchesKeyword = group.keywords.some((kw) => lockLower.includes(kw));
+        if (!lockMatchesKeyword) continue;
+
+        const fileMatchesPattern = group.patterns.some((pattern) => patternMatchesFile(pattern, fileLower) || patternMatchesFile(pattern, fileLower.split("/").pop()));
+        if (fileMatchesPattern) {
+          violations.push({
+            file,
+            reason: `File matches lock keyword pattern`,
+            lockText: lock.text,
+            severity: "MEDIUM",
+          });
+          break;
+        }
+      }
+    }
+  }
+
+  // Deduplicate by file
+  const seen = new Set();
+  const unique = violations.filter((v) => {
+    if (seen.has(v.file)) return false;
+    seen.add(v.file);
+    return true;
+  });
+
+  const passed = unique.length === 0;
+  const message = passed
+    ? `Audit passed. ${stagedFiles.length} file(s) checked against ${activeLocks.length} lock(s).`
+    : `AUDIT FAILED: ${unique.length} violation(s) in ${stagedFiles.length} staged file(s).`;
+
+  return {
+    passed,
+    violations: unique,
+    checkedFiles: stagedFiles.length,
+    activeLocks: activeLocks.length,
+    message,
+  };
+}

package/src/core/git.js

@@ -108,3 +108,9 @@ export function getDiffSummary(root) {
   if (!res.ok) return "";
   return res.stdout;
 }
+
+export function getStagedFiles(root) {
+  const res = safeGit(root, ["diff", "--cached", "--name-only"]);
+  if (!res.ok || !res.stdout) return [];
+  return res.stdout.split("\n").filter(Boolean);
+}

package/src/core/hooks.js

@@ -0,0 +1,87 @@
+// SpecLock Git Hook Management
+
+import fs from "fs";
+import path from "path";
+
+const HOOK_MARKER = "# SPECLOCK-HOOK";
+
+const HOOK_SCRIPT = `#!/bin/sh
+${HOOK_MARKER} — Do not remove this line
+# SpecLock pre-commit hook: checks staged files against active locks
+# Install: npx speclock hook install
+# Remove:  npx speclock hook remove
+
+npx speclock audit
+exit $?
+`;
+
+export function installHook(root) {
+  const hooksDir = path.join(root, ".git", "hooks");
+  if (!fs.existsSync(path.join(root, ".git"))) {
+    return { success: false, error: "Not a git repository. Run 'git init' first." };
+  }
+
+  // Ensure hooks directory exists
+  fs.mkdirSync(hooksDir, { recursive: true });
+
+  const hookPath = path.join(hooksDir, "pre-commit");
+
+  // Check if existing hook exists (not ours)
+  if (fs.existsSync(hookPath)) {
+    const existing = fs.readFileSync(hookPath, "utf-8");
+    if (existing.includes(HOOK_MARKER)) {
+      return { success: false, error: "SpecLock pre-commit hook is already installed." };
+    }
+    // Append to existing hook
+    const appended = existing.trimEnd() + "\n\n" + HOOK_SCRIPT;
+    fs.writeFileSync(hookPath, appended, { mode: 0o755 });
+    return { success: true, message: "SpecLock hook appended to existing pre-commit hook." };
+  }
+
+  fs.writeFileSync(hookPath, HOOK_SCRIPT, { mode: 0o755 });
+  return { success: true, message: "SpecLock pre-commit hook installed." };
+}
+
+export function removeHook(root) {
+  const hookPath = path.join(root, ".git", "hooks", "pre-commit");
+  if (!fs.existsSync(hookPath)) {
+    return { success: false, error: "No pre-commit hook found." };
+  }
+
+  const content = fs.readFileSync(hookPath, "utf-8");
+  if (!content.includes(HOOK_MARKER)) {
+    return { success: false, error: "Pre-commit hook exists but was not installed by SpecLock." };
+  }
+
+  // Check if lines other than our speclock block exist
+  const lines = content.split("\n");
+  const nonSpeclockLines = lines.filter((line) => {
+    const trimmed = line.trim();
+    const lower = trimmed.toLowerCase();
+    if (!trimmed || trimmed === "#!/bin/sh") return false;
+    if (lower.includes("speclock")) return false;
+    if (lower.includes("npx speclock")) return false;
+    if (trimmed === "exit $?") return false;
+    return true;
+  });
+
+  if (nonSpeclockLines.length === 0) {
+    // Entire hook was ours — remove file
+    fs.unlinkSync(hookPath);
+    return { success: true, message: "SpecLock pre-commit hook removed." };
+  }
+
+  // Other hook content exists — remove our block, keep the rest
+  const cleaned = content
+    .replace(/\n*# SPECLOCK-HOOK[^\n]*\n.*?exit \$\?\n?/s, "\n")
+    .trim();
+  fs.writeFileSync(hookPath, cleaned + "\n", { mode: 0o755 });
+  return { success: true, message: "SpecLock hook removed. Other hook content preserved." };
+}
+
+export function isHookInstalled(root) {
+  const hookPath = path.join(root, ".git", "hooks", "pre-commit");
+  if (!fs.existsSync(hookPath)) return false;
+  const content = fs.readFileSync(hookPath, "utf-8");
+  return content.includes(HOOK_MARKER);
+}

package/src/core/storage.js

@@ -73,6 +73,7 @@ export function makeBrain(root, hasGitRepo, defaultBranch) {
       },
       recentChanges: [],
       reverts: [],
+      violations: [],
     },
     events: { lastEventId: "", count: 0 },
   };
@@ -104,6 +105,11 @@ export function migrateBrainV1toV2(brain) {
     brain.facts.deploy.url = "";
   }
 
+  // Add violations array if missing
+  if (brain.state && !brain.state.violations) {
+    brain.state.violations = [];
+  }
+
   // Remove old importance field
   delete brain.importance;
 
@@ -120,6 +126,10 @@ export function readBrain(root) {
     brain = migrateBrainV1toV2(brain);
     writeBrain(root, brain);
   }
+  // Ensure violations array exists (added in v1.7.0)
+  if (brain.state && !brain.state.violations) {
+    brain.state.violations = [];
+  }
   return brain;
 }
 
@@ -184,3 +194,11 @@ export function addRecentChange(brain, item) {
 export function addRevert(brain, item) {
   brain.state.reverts.unshift(item);
 }
+
+export function addViolation(brain, item) {
+  if (!brain.state.violations) brain.state.violations = [];
+  brain.state.violations.unshift(item);
+  if (brain.state.violations.length > 100) {
+    brain.state.violations = brain.state.violations.slice(0, 100);
+  }
+}

package/src/core/templates.js

@@ -0,0 +1,114 @@
+// SpecLock Constraint Templates — Pre-built lock packs for common frameworks
+
+export const TEMPLATES = {
+  nextjs: {
+    name: "nextjs",
+    displayName: "Next.js",
+    description: "Constraints for Next.js applications — protects routing, API routes, and middleware",
+    locks: [
+      "Never modify the authentication system without explicit permission",
+      "Never change the Next.js routing structure (app/ or pages/ directory layout)",
+      "API routes must not expose internal server logic to the client",
+      "Middleware must not be modified without review",
+      "Environment variables must not be hardcoded in source files",
+    ],
+    decisions: [
+      "Framework: Next.js (App Router or Pages Router as configured)",
+      "Server components are the default; client components require 'use client' directive",
+    ],
+  },
+
+  react: {
+    name: "react",
+    displayName: "React",
+    description: "Constraints for React applications — protects state management, component architecture",
+    locks: [
+      "Never modify the authentication system without explicit permission",
+      "Global state management pattern must not change without review",
+      "Component prop interfaces must maintain backward compatibility",
+      "Shared utility functions must not have breaking changes",
+      "Environment variables must not be hardcoded in source files",
+    ],
+    decisions: [
+      "Framework: React with functional components and hooks",
+      "Styling approach must remain consistent across the project",
+    ],
+  },
+
+  express: {
+    name: "express",
+    displayName: "Express.js API",
+    description: "Constraints for Express.js backends — protects middleware, routes, and database layer",
+    locks: [
+      "Never modify authentication or authorization middleware without explicit permission",
+      "Database connection configuration must not change without review",
+      "No breaking changes to public API endpoints",
+      "Rate limiting and security middleware must not be disabled",
+      "Environment variables and secrets must not be hardcoded",
+    ],
+    decisions: [
+      "Backend: Express.js with REST API pattern",
+      "Error handling follows centralized middleware pattern",
+    ],
+  },
+
+  supabase: {
+    name: "supabase",
+    displayName: "Supabase",
+    description: "Constraints for Supabase projects — protects auth, RLS policies, and database schema",
+    locks: [
+      "Database must always be Supabase — never switch to another provider",
+      "Row Level Security (RLS) policies must not be disabled or weakened",
+      "Supabase auth configuration must not change without explicit permission",
+      "Database schema migrations must not drop tables or columns without review",
+      "Supabase client initialization must not be modified",
+    ],
+    decisions: [
+      "Database and auth provider: Supabase",
+      "All database access must go through Supabase client (no direct SQL in application code)",
+    ],
+  },
+
+  stripe: {
+    name: "stripe",
+    displayName: "Stripe Payments",
+    description: "Constraints for Stripe integration — protects payment logic, webhooks, and pricing",
+    locks: [
+      "Payment processing logic must not be modified without explicit permission",
+      "Stripe webhook handlers must not change without review",
+      "Pricing and subscription tier definitions must not change without permission",
+      "Stripe API keys must never be hardcoded or exposed to the client",
+      "Payment error handling must not be weakened or removed",
+    ],
+    decisions: [
+      "Payment provider: Stripe",
+      "All payment operations must be server-side only",
+    ],
+  },
+
+  "security-hardened": {
+    name: "security-hardened",
+    displayName: "Security Hardened",
+    description: "Strict security constraints — protects auth, secrets, CORS, input validation",
+    locks: [
+      "Never modify authentication or authorization without explicit permission",
+      "No secrets, API keys, or credentials in source code",
+      "CORS configuration must not be loosened without review",
+      "Input validation must not be weakened or bypassed",
+      "Security headers and CSP must not be removed or weakened",
+      "Dependencies must not be downgraded without security review",
+    ],
+    decisions: [
+      "Security-first development: all inputs validated, all outputs encoded",
+      "Authentication changes require explicit user approval",
+    ],
+  },
+};
+
+export function getTemplateNames() {
+  return Object.keys(TEMPLATES);
+}
+
+export function getTemplate(name) {
+  return TEMPLATES[name] || null;
+}

package/src/mcp/http-server.js

@@ -1,6 +1,6 @@
 /**
  * SpecLock MCP HTTP Server — for Railway / remote deployment
- * Wraps the same 19 tools as the stdio server using Streamable HTTP transport.
+ * Wraps the same 22 tools as the stdio server using Streamable HTTP transport.
  * Developed by Sandeep Roy (https://github.com/sgroy10)
  */
 
@@ -23,6 +23,10 @@ import {
   endSession,
   suggestLocks,
   detectDrift,
+  listTemplates,
+  applyTemplate,
+  generateReport,
+  auditStagedFiles,
 } from "../core/engine.js";
 import { generateContext, generateContextPack } from "../core/context.js";
 import {
@@ -41,7 +45,7 @@ import {
 } from "../core/git.js";
 
 const PROJECT_ROOT = process.env.SPECLOCK_PROJECT_ROOT || process.cwd();
-const VERSION = "1.2.0";
+const VERSION = "1.7.0";
 const AUTHOR = "Sandeep Roy";
 
 function createSpecLockServer() {
@@ -253,6 +257,41 @@ function createSpecLockServer() {
     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}*` }] };
   });
 
+  // Tool 20: speclock_apply_template
+  server.tool("speclock_apply_template", "Apply a pre-built constraint template (nextjs, react, express, supabase, stripe, security-hardened).", { name: z.string().optional().describe("Template name. Omit to list.") }, async ({ name }) => {
+    ensureInit(PROJECT_ROOT);
+    if (!name) {
+      const templates = listTemplates();
+      const text = templates.map(t => `- **${t.name}** (${t.displayName}): ${t.description} — ${t.lockCount} locks, ${t.decisionCount} decisions`).join("\n");
+      return { content: [{ type: "text", text: `## Available Templates\n\n${text}\n\nCall again with a name to apply.` }] };
+    }
+    const result = applyTemplate(PROJECT_ROOT, name);
+    if (!result.applied) return { content: [{ type: "text", text: result.error }], isError: true };
+    return { content: [{ type: "text", text: `Template "${result.displayName}" applied: ${result.locksAdded} lock(s) + ${result.decisionsAdded} decision(s).` }] };
+  });
+
+  // Tool 21: speclock_report
+  server.tool("speclock_report", "Violation report — how many times SpecLock blocked changes.", {}, async () => {
+    ensureInit(PROJECT_ROOT);
+    const report = generateReport(PROJECT_ROOT);
+    const parts = [`## Violation Report`, `Total blocked: **${report.totalViolations}**`];
+    if (report.mostTestedLocks.length > 0) {
+      parts.push("", "### Most Tested Locks");
+      for (const l of report.mostTestedLocks) parts.push(`- ${l.count}x — "${l.text}"`);
+    }
+    parts.push("", report.summary);
+    return { content: [{ type: "text", text: parts.join("\n") }] };
+  });
+
+  // Tool 22: speclock_audit
+  server.tool("speclock_audit", "Audit staged files against active locks.", {}, async () => {
+    ensureInit(PROJECT_ROOT);
+    const result = auditStagedFiles(PROJECT_ROOT);
+    if (result.passed) return { content: [{ type: "text", text: result.message }] };
+    const text = result.violations.map(v => `- [${v.severity}] **${v.file}** — ${v.reason}\n  Lock: "${v.lockText}"`).join("\n");
+    return { content: [{ type: "text", text: `## Audit Failed\n\n${text}\n\n${result.message}` }] };
+  });
+
   return server;
 }
 
@@ -292,7 +331,7 @@ app.get("/", (req, res) => {
     version: VERSION,
     author: AUTHOR,
     description: "AI Continuity Engine — Kill AI amnesia",
-    tools: 19,
+    tools: 22,
     mcp_endpoint: "/mcp",
     npm: "https://www.npmjs.com/package/speclock",
     github: "https://github.com/sgroy10/speclock",

package/src/mcp/server.js

@@ -16,6 +16,12 @@ import {
   endSession,
   suggestLocks,
   detectDrift,
+  syncLocksToPackageJson,
+  autoGuardRelatedFiles,
+  listTemplates,
+  applyTemplate,
+  generateReport,
+  auditStagedFiles,
 } from "../core/engine.js";
 import { generateContext, generateContextPack } from "../core/context.js";
 import {
@@ -50,7 +56,7 @@ const PROJECT_ROOT =
   args.project || process.env.SPECLOCK_PROJECT_ROOT || process.cwd();
 
 // --- MCP Server ---
-const VERSION = "1.2.0";
+const VERSION = "1.7.0";
 const AUTHOR = "Sandeep Roy";
 
 const server = new McpServer(
@@ -171,9 +177,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 +210,8 @@ server.tool(
         isError: true,
       };
     }
+    // Sync updated locks to package.json
+    syncLocksToPackageJson(PROJECT_ROOT);
     return {
       content: [
         {
@@ -752,6 +770,118 @@ server.tool(
   }
 );
 
+// ========================================
+// TEMPLATE, REPORT & AUDIT TOOLS (v1.7.0)
+// ========================================
+
+// Tool 20: speclock_apply_template
+server.tool(
+  "speclock_apply_template",
+  "Apply a pre-built constraint template (e.g., nextjs, react, express, supabase, stripe, security-hardened). Templates add recommended locks and decisions for common frameworks.",
+  {
+    name: z
+      .string()
+      .optional()
+      .describe("Template name to apply. Omit to list available templates."),
+  },
+  async ({ name }) => {
+    if (!name) {
+      const templates = listTemplates();
+      const formatted = templates
+        .map((t) => `- **${t.name}** (${t.displayName}): ${t.description} — ${t.lockCount} locks, ${t.decisionCount} decisions`)
+        .join("\n");
+      return {
+        content: [
+          {
+            type: "text",
+            text: `## Available Templates\n\n${formatted}\n\nCall again with a name to apply.`,
+          },
+        ],
+      };
+    }
+    const result = applyTemplate(PROJECT_ROOT, name);
+    if (!result.applied) {
+      return {
+        content: [{ type: "text", text: result.error }],
+        isError: true,
+      };
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Template "${result.displayName}" applied: ${result.locksAdded} lock(s) + ${result.decisionsAdded} decision(s) added.`,
+        },
+      ],
+    };
+  }
+);
+
+// Tool 21: speclock_report
+server.tool(
+  "speclock_report",
+  "Get a violation report showing how many times SpecLock blocked constraint violations, which locks were tested most, and recent violations.",
+  {},
+  async () => {
+    const report = generateReport(PROJECT_ROOT);
+
+    const parts = [`## SpecLock Violation Report`, ``, `Total violations blocked: **${report.totalViolations}**`];
+
+    if (report.timeRange) {
+      parts.push(`Period: ${report.timeRange.from.substring(0, 10)} to ${report.timeRange.to.substring(0, 10)}`);
+    }
+
+    if (report.mostTestedLocks.length > 0) {
+      parts.push("", "### Most Tested Locks");
+      for (const lock of report.mostTestedLocks) {
+        parts.push(`- ${lock.count}x — "${lock.text}"`);
+      }
+    }
+
+    if (report.recentViolations.length > 0) {
+      parts.push("", "### Recent Violations");
+      for (const v of report.recentViolations) {
+        parts.push(`- [${v.at.substring(0, 19)}] ${v.topLevel} (${v.topConfidence}%) — "${v.action}"`);
+      }
+    }
+
+    parts.push("", `---`, report.summary);
+
+    return {
+      content: [{ type: "text", text: parts.join("\n") }],
+    };
+  }
+);
+
+// Tool 22: speclock_audit
+server.tool(
+  "speclock_audit",
+  "Audit git staged files against active SpecLock constraints. Returns pass/fail with details on which files violate locks. Used by the pre-commit hook.",
+  {},
+  async () => {
+    const result = auditStagedFiles(PROJECT_ROOT);
+
+    if (result.passed) {
+      return {
+        content: [{ type: "text", text: result.message }],
+      };
+    }
+
+    const formatted = result.violations
+      .map((v) => `- [${v.severity}] **${v.file}** — ${v.reason}\n  Lock: "${v.lockText}"`)
+      .join("\n");
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `## Audit Failed\n\n${formatted}\n\n${result.message}`,
+        },
+      ],
+    };
+  }
+);
+
 // --- Smithery sandbox export ---
 export default function createSandboxServer() {
   return server;