speclock 1.2.1 → 1.3.0

package/SPECLOCK-INSTRUCTIONS.md

@@ -0,0 +1,146 @@
+# SpecLock Project Instructions — Copy-Paste Templates
+
+These are **project-level instructions** that you paste into your AI coding platform's settings. They force the AI to use SpecLock on every action — turning it from a passive notepad into an active guardrail.
+
+---
+
+## For Lovable
+
+Go to **Project Settings → Knowledge** and paste this:
+
+```
+## SpecLock Rules (MANDATORY — follow on every message)
+
+1. START OF EVERY CONVERSATION: Call speclock_session_briefing FIRST. Read all locks, decisions, and goals before doing anything else. Show a brief summary: "🔒 Memory loaded — X locks, Y decisions."
+
+2. BEFORE WRITING OR MODIFYING ANY CODE: Call speclock_check_conflict with a description of what you're about to change (e.g., "Adding payment page, creating new route and components" or "Modifying the auth login flow"). If a conflict is found with HIGH confidence, STOP and tell me which lock would be violated. Do NOT proceed unless I explicitly say to override it.
+
+3. WHEN I SAY "lock this", "never touch this", "don't ever change this", "this is critical", or similar: Immediately call speclock_add_lock with my exact constraint. Confirm with: "🔒 Locked: [constraint]"
+
+4. AFTER COMPLETING ANY FEATURE OR SIGNIFICANT CHANGE: Call speclock_log_change with a summary of what was built/changed and which files were affected. Also call speclock_add_decision if an architectural choice was made.
+
+5. WHEN I ASK TO REMOVE OR CHANGE SOMETHING THAT WAS LOCKED: Warn me first: "⚠️ You locked this: [constraint]. Want me to unlock it and proceed?" Only proceed if I confirm.
+
+6. END OF CONVERSATION: Call speclock_session_summary with what was accomplished.
+```
+
+---
+
+## For Cursor
+
+Create or add to `.cursorrules` in your project root:
+
+```
+## SpecLock Rules (MANDATORY — follow on every message)
+
+1. START OF EVERY CONVERSATION: Call speclock_session_briefing FIRST. Read all locks, decisions, and goals before doing anything else. Show a brief summary: "🔒 Memory loaded — X locks, Y decisions."
+
+2. BEFORE WRITING OR MODIFYING ANY CODE: Call speclock_check_conflict with a description of what you're about to change. If a conflict is found with HIGH confidence, STOP and tell me which lock would be violated. Do NOT proceed unless I explicitly say to override.
+
+3. WHEN I SAY "lock this", "never touch this", "don't change this": Call speclock_add_lock immediately. Confirm: "🔒 Locked: [constraint]"
+
+4. AFTER COMPLETING ANY FEATURE: Call speclock_log_change with a summary and files affected. Call speclock_add_decision if an architectural choice was made.
+
+5. WHEN I ASK TO CHANGE SOMETHING LOCKED: Warn me: "⚠️ This is locked: [constraint]. Unlock and proceed?" Only continue if I confirm.
+
+6. END OF SESSION: Call speclock_session_summary.
+```
+
+---
+
+## For Claude Code
+
+Add to `CLAUDE.md` in your project root:
+
+```
+## SpecLock Rules (MANDATORY — follow on every message)
+
+1. START OF EVERY CONVERSATION: Call speclock_session_briefing FIRST. Read all locks, decisions, and goals before doing anything else. Show: "🔒 Memory loaded — X locks, Y decisions."
+
+2. BEFORE WRITING OR MODIFYING ANY CODE: Call speclock_check_conflict with what you're about to change. If conflict found (HIGH), STOP and warn me. Do NOT proceed unless I override.
+
+3. WHEN I SAY "lock this", "never touch", "don't change": Call speclock_add_lock. Confirm: "🔒 Locked: [constraint]"
+
+4. AFTER COMPLETING FEATURES: Call speclock_log_change + speclock_add_decision for architectural choices.
+
+5. LOCKED ITEMS: Warn before changing. Only proceed if I confirm unlock.
+
+6. END OF SESSION: Call speclock_session_summary.
+```
+
+---
+
+## For Windsurf
+
+Add to `.windsurfrules` in your project root:
+
+```
+## SpecLock Rules (MANDATORY — follow on every message)
+
+1. START OF EVERY CONVERSATION: Call speclock_session_briefing FIRST. Show: "🔒 Memory loaded — X locks, Y decisions."
+
+2. BEFORE MODIFYING CODE: Call speclock_check_conflict. If HIGH conflict, STOP and warn me.
+
+3. WHEN I SAY "lock this" / "never touch" / "don't change": Call speclock_add_lock. Confirm: "🔒 Locked: [constraint]"
+
+4. AFTER FEATURES: Call speclock_log_change + speclock_add_decision.
+
+5. LOCKED ITEMS: Warn before changing. Only unlock if I confirm.
+
+6. END: Call speclock_session_summary.
+```
+
+---
+
+## How It Works In Practice
+
+### Example 1: User locks something
+```
+User: "Don't ever touch the auth files"
+AI:   🔒 Locked: "Never modify auth files"
+```
+
+### Example 2: AI checks before changing
+```
+User: "Add social login to the login page"
+AI:   *calls speclock_check_conflict("Modifying auth login page to add social login")*
+      ⚠️ This conflicts with your lock: "Never modify auth files"
+      Should I proceed anyway, or find another approach?
+```
+
+### Example 3: New session, full memory
+```
+User: "Let's keep working on the dashboard"
+AI:   *calls speclock_session_briefing*
+      🔒 Memory loaded — 5 locks, 3 decisions, 2 sessions tracked.
+      Last session you added the payment page and locked the auth files.
+      Ready to work on the dashboard.
+```
+
+### Example 4: User changes their mind
+```
+User: "Actually, unlock the auth files, I need to change them"
+AI:   You locked: "Never modify auth files". Want me to unlock this?
+User: "Yes"
+AI:   🔓 Unlocked. Proceeding with auth file changes.
+```
+
+---
+
+## The Complete Setup (2 minutes)
+
+### Lovable:
+1. Connect SpecLock: Settings → Connectors → Custom → URL: `https://speclock-mcp-production.up.railway.app/mcp` → No auth
+2. Paste the instruction above into: Project Settings → Knowledge
+3. Say "initialize speclock" in your first chat
+4. Done. Every session after: AI auto-checks memory and constraints.
+
+### Cursor:
+1. Add to `.cursor/mcp.json`: `{"mcpServers":{"speclock":{"command":"npx","args":["-y","speclock","serve","--project","."]}}}`
+2. Create `.cursorrules` with the instruction above
+3. Done.
+
+### Claude Code:
+1. Add to `~/.claude.json` or `.mcp.json`: `{"mcpServers":{"speclock":{"command":"npx","args":["-y","speclock","serve","--project","."]}}}`
+2. Add the instruction above to `CLAUDE.md`
+3. Done.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speclock",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "AI continuity engine — MCP server + CLI that kills AI amnesia. Maintains project memory, enforces constraints, and detects drift across AI coding sessions.",
   "type": "module",
   "main": "src/mcp/server.js",
@@ -54,6 +54,7 @@
     "bin/",
     "src/",
     "README.md",
+    "SPECLOCK-INSTRUCTIONS.md",
     "LICENSE"
   ],
   "devDependencies": {

package/src/cli/index.js

@@ -7,7 +7,10 @@ import {
   addDecision,
   addNote,
   updateDeployFacts,
+  logChange,
+  checkConflict,
   watchRepo,
+  createSpecLockMd,
 } from "../core/engine.js";
 import { generateContext } from "../core/context.js";
 import { readBrain } from "../core/storage.js";
@@ -52,50 +55,56 @@ function rootDir() {
   return process.cwd();
 }
 
+// --- Auto-regenerate context after write operations ---
+
+function refreshContext(root) {
+  try {
+    generateContext(root);
+  } catch (_) {
+    // Silently skip if context generation fails
+  }
+}
+
 // --- Help text ---
 
 function printHelp() {
   console.log(`
-SpecLock v1.1.0 — AI Continuity Engine
+SpecLock v1.3.0 — AI Continuity Engine
 Developed by Sandeep Roy (github.com/sgroy10)
 
 Usage: speclock <command> [options]
 
 Commands:
-  init                          Initialize SpecLock in current directory
-  goal <text>                   Set or update the project goal
-  lock <text> [--tags a,b]      Add a non-negotiable constraint (SpecLock)
-  lock remove <id>              Remove a lock by ID
-  decide <text> [--tags a,b]    Record a decision
-  note <text> [--pinned]        Add a pinned note
-  facts deploy [--provider X]   Set deployment facts
-  context                       Generate and print context pack
-  watch                         Start file watcher (auto-track changes)
-  serve [--project <path>]      Start MCP stdio server
-  status                        Show project brain summary
+  setup [--goal <text>]           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
+  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
+  context                         Generate and print context pack
+  facts deploy [--provider X]     Set deployment facts
+  watch                           Start file watcher (auto-track changes)
+  serve [--project <path>]        Start MCP stdio server
+  status                          Show project brain summary
 
 Options:
-  --tags <a,b,c>                Comma-separated tags
-  --source <user|agent>         Who created this (default: user)
-  --provider <name>             Deploy provider
-  --branch <name>               Deploy branch
-  --autoDeploy <true|false>     Auto-deploy setting
-  --url <url>                   Deployment URL
-  --notes <text>                Additional notes
-  --project <path>              Project root (for serve)
+  --tags <a,b,c>                  Comma-separated tags
+  --source <user|agent>           Who created this (default: user)
+  --files <a.ts,b.ts>             Comma-separated file paths
+  --goal <text>                   Goal text (for setup command)
+  --project <path>                Project root (for serve)
 
 Examples:
-  speclock init
-  speclock goal "Ship v1 of the continuity engine"
-  speclock lock "No external database in v1" --tags scope
-  speclock decide "Use MCP as primary integration" --tags architecture
-  speclock context
-  speclock serve --project /path/to/repo
-
-MCP Tools (19): init, get_context, set_goal, add_lock, remove_lock,
-  add_decision, add_note, set_deploy_facts, log_change, get_changes,
-  get_events, check_conflict, session_briefing, session_summary,
-  checkpoint, repo_status, suggest_locks, detect_drift, health
+  npx speclock setup --goal "Build PawPalace pet shop"
+  npx speclock 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"
+  npx speclock context
+  npx speclock status
 `);
 }
 
@@ -104,7 +113,7 @@ MCP Tools (19): init, get_context, set_goal, add_lock, remove_lock,
 function showStatus(root) {
   const brain = readBrain(root);
   if (!brain) {
-    console.log("SpecLock not initialized. Run: speclock init");
+    console.log("SpecLock not initialized. Run: npx speclock setup");
     return;
   }
 
@@ -113,11 +122,11 @@ function showStatus(root) {
   console.log(`\nSpecLock Status — ${brain.project.name}`);
   console.log("=".repeat(50));
   console.log(`Goal: ${brain.goal.text || "(not set)"}`);
-  console.log(`SpecLocks: ${activeLocks.length} active`);
+  console.log(`Locks: ${activeLocks.length} active`);
   console.log(`Decisions: ${brain.decisions.length}`);
   console.log(`Notes: ${brain.notes.length}`);
   console.log(`Events: ${brain.events.count}`);
-  console.log(`Deploy: ${brain.facts.deploy.provider}`);
+  console.log(`Deploy: ${brain.facts.deploy.provider || "(not set)"}`);
 
   if (brain.sessions.current) {
     console.log(`Session: active (${brain.sessions.current.toolUsed})`);
@@ -133,7 +142,6 @@ function showStatus(root) {
   }
 
   console.log(`Recent changes: ${brain.state.recentChanges.length}`);
-  console.log(`Reverts: ${brain.state.reverts.length}`);
   console.log("");
 }
 
@@ -148,12 +156,60 @@ async function main() {
     process.exit(0);
   }
 
+  // --- SETUP (new: one-shot full setup) ---
+  if (cmd === "setup") {
+    const flags = parseFlags(args);
+    const goalText = flags.goal || flags._.join(" ").trim();
+
+    // 1. Initialize
+    ensureInit(root);
+    console.log("Initialized .speclock/ directory.");
+
+    // 2. Set goal if provided
+    if (goalText) {
+      setGoal(root, goalText);
+      console.log(`Goal set: "${goalText}"`);
+    }
+
+    // 3. Create SPECLOCK.md in project root
+    const mdPath = createSpecLockMd(root);
+    console.log(`Created SPECLOCK.md (AI instructions file).`);
+
+    // 4. Generate context
+    generateContext(root);
+    console.log("Generated .speclock/context/latest.md");
+
+    // 5. Print summary
+    console.log(`
+SpecLock is ready!
+
+Files created:
+  .speclock/brain.json          — Project memory
+  .speclock/context/latest.md   — Context for AI (read this)
+  SPECLOCK.md                   — AI rules (read this)
+
+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
+`);
+    return;
+  }
+
+  // --- INIT ---
   if (cmd === "init") {
     ensureInit(root);
-    console.log("SpecLock initialized.");
+    createSpecLockMd(root);
+    generateContext(root);
+    console.log("SpecLock initialized. Created SPECLOCK.md and context file.");
     return;
   }
 
+  // --- GOAL ---
   if (cmd === "goal") {
     const text = args.join(" ").trim();
     if (!text) {
@@ -162,10 +218,12 @@ async function main() {
       process.exit(1);
     }
     setGoal(root, text);
+    refreshContext(root);
     console.log(`Goal set: "${text}"`);
     return;
   }
 
+  // --- LOCK ---
   if (cmd === "lock") {
     // Check for "lock remove <id>"
     if (args[0] === "remove") {
@@ -177,6 +235,7 @@ async function main() {
       }
       const result = removeLock(root, lockId);
       if (result.removed) {
+        refreshContext(root);
         console.log(`Lock removed: "${result.lockText}"`);
       } else {
         console.error(result.error);
@@ -193,10 +252,12 @@ async function main() {
       process.exit(1);
     }
     const { lockId } = addLock(root, text, parseTags(flags.tags), flags.source || "user");
-    console.log(`SpecLock added (${lockId}): "${text}"`);
+    refreshContext(root);
+    console.log(`Locked (${lockId}): "${text}"`);
     return;
   }
 
+  // --- DECIDE ---
   if (cmd === "decide") {
     const flags = parseFlags(args);
     const text = flags._.join(" ").trim();
@@ -206,10 +267,12 @@ async function main() {
       process.exit(1);
     }
     const { decId } = addDecision(root, text, parseTags(flags.tags), flags.source || "user");
+    refreshContext(root);
     console.log(`Decision recorded (${decId}): "${text}"`);
     return;
   }
 
+  // --- NOTE ---
   if (cmd === "note") {
     const flags = parseFlags(args);
     const text = flags._.join(" ").trim();
@@ -220,10 +283,60 @@ async function main() {
     }
     const pinned = flags.pinned !== false;
     const { noteId } = addNote(root, text, pinned);
+    refreshContext(root);
     console.log(`Note added (${noteId}): "${text}"`);
     return;
   }
 
+  // --- LOG-CHANGE (new) ---
+  if (cmd === "log-change") {
+    const flags = parseFlags(args);
+    const text = flags._.join(" ").trim();
+    if (!text) {
+      console.error("Error: Change summary is required.");
+      console.error('Usage: speclock log-change "what changed" --files a.ts,b.ts');
+      process.exit(1);
+    }
+    const files = flags.files ? flags.files.split(",").map((f) => f.trim()).filter(Boolean) : [];
+    logChange(root, text, files);
+    refreshContext(root);
+    console.log(`Change logged: "${text}"`);
+    if (files.length > 0) {
+      console.log(`Files: ${files.join(", ")}`);
+    }
+    return;
+  }
+
+  // --- CHECK (new: conflict check) ---
+  if (cmd === "check") {
+    const text = args.join(" ").trim();
+    if (!text) {
+      console.error("Error: Action description is required.");
+      console.error('Usage: speclock check "what you plan to do"');
+      process.exit(1);
+    }
+    const result = checkConflict(root, text);
+    if (result.hasConflict) {
+      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}%`);
+        if (lock.reasons && lock.reasons.length > 0) {
+          for (const reason of lock.reasons) {
+            console.log(`  - ${reason}`);
+          }
+        }
+        console.log("");
+      }
+      console.log(result.analysis);
+    } else {
+      console.log(`No conflicts found. Safe to proceed with: "${text}"`);
+    }
+    return;
+  }
+
+  // --- FACTS ---
   if (cmd === "facts") {
     const sub = args.shift();
     if (sub !== "deploy") {
@@ -245,21 +358,25 @@ async function main() {
         String(flags.autoDeploy).toLowerCase() === "true";
     }
     updateDeployFacts(root, payload);
+    refreshContext(root);
     console.log("Deploy facts updated.");
     return;
   }
 
+  // --- CONTEXT ---
   if (cmd === "context") {
     const md = generateContext(root);
     console.log(md);
     return;
   }
 
+  // --- WATCH ---
   if (cmd === "watch") {
     await watchRepo(root);
     return;
   }
 
+  // --- SERVE ---
   if (cmd === "serve") {
     // Start MCP server — pass through --project if provided
     const flags = parseFlags(args);
@@ -269,6 +386,7 @@ async function main() {
     return;
   }
 
+  // --- STATUS ---
   if (cmd === "status") {
     showStatus(root);
     return;

package/src/core/engine.js

@@ -696,3 +696,53 @@ export async function watchRepo(root) {
   console.log("SpecLock watching for changes...");
   return watcher;
 }
+
+// --- SPECLOCK.md generator (for npm dependency / file-based mode) ---
+
+export function createSpecLockMd(root) {
+  const mdContent = `# SpecLock — Project Memory Active
+
+This project uses **SpecLock** for AI continuity across sessions.
+Read \`.speclock/context/latest.md\` for full project context before making changes.
+
+## Rules (follow on every message)
+
+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.
+
+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.
+
+3. **WHEN USER SAYS "lock this", "never touch", "don't change", "always", "critical"**: Run \`npx speclock lock "the exact constraint"\`. Confirm: "Locked: [constraint]"
+
+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.
+
+5. **WHEN AN ARCHITECTURAL DECISION IS MADE**: Run \`npx speclock decide "the decision"\`
+
+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>\`
+
+## Quick Reference
+
+\`\`\`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
+\`\`\`
+
+## How It Works
+
+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.
+`;
+  const filePath = path.join(root, "SPECLOCK.md");
+  fs.writeFileSync(filePath, mdContent);
+  return filePath;
+}