speclock 1.6.0 → 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,6 +218,13 @@ 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**:
@@ -251,7 +258,7 @@ Active locks are also embedded in `package.json` — so the AI sees your constra
 
 ```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
@@ -265,6 +272,18 @@ 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
@@ -283,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)
                │                  │
@@ -318,4 +337,4 @@ MIT License - see [LICENSE](LICENSE) file.
 
 ---
 
-*SpecLock v1.6.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.6.0",
+  "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

@@ -16,9 +16,14 @@ import {
   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 ---
 
@@ -74,23 +79,29 @@ function refreshContext(root) {
 
 function printHelp() {
   console.log(`
-SpecLock v1.6.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)
@@ -102,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
 `);
 }
@@ -190,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!
 
@@ -355,8 +379,8 @@ Tip: When starting a new chat, tell the AI:
       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}`);
@@ -460,6 +484,119 @@ Tip: When starting a new chat, tell the AI:
     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
 \`\`\`
 
@@ -1042,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

@@ -18,6 +18,10 @@ import {
   detectDrift,
   syncLocksToPackageJson,
   autoGuardRelatedFiles,
+  listTemplates,
+  applyTemplate,
+  generateReport,
+  auditStagedFiles,
 } from "../core/engine.js";
 import { generateContext, generateContextPack } from "../core/context.js";
 import {
@@ -52,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(
@@ -766,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;