speclock 1.2.0 → 1.3.0

package/README.md

@@ -35,9 +35,11 @@ SpecLock maintains a `.speclock/` directory inside your repo that gives every AI
     └── latest.md      # Always-fresh context pack for any AI agent
 ```
 
-Any AI tool calls `speclock_session_briefing` → gets **full project context** → works with complete memory → calls `speclock_session_summary` → next session continues seamlessly.
+**SpecLock = MCP Server + Project Instructions.**
 
-**No context is ever lost again.**
+The MCP server gives the AI tools for memory and constraint checking. The project instructions force the AI to use them on every action — automatically. Together, they create an active guardrail that prevents AI coding tools from breaking your work.
+
+**No context is ever lost. No constraints ever violated.**
 
 ## Why SpecLock Wins
 
@@ -56,31 +58,15 @@ Any AI tool calls `speclock_session_briefing` → gets **full project context**
 
 ## Quick Start
 
-### 1. Install
-
-```bash
-npm install -g speclock
-```
-
-Or use directly with npx:
+### 1. Connect SpecLock to Your AI Tool
 
-```bash
-npx speclock init
-```
+**Lovable** (no install needed):
 
-### 2. Initialize in Your Project
+1. Go to **Settings → Connectors → Personal connectors → New MCP server**
+2. Enter URL: `https://speclock-mcp-production.up.railway.app/mcp` — No auth
+3. Enable it in your project's prompt box
 
-```bash
-cd your-project
-speclock init
-speclock goal "Ship v1 of the product"
-speclock lock "No breaking changes to public API"
-speclock decide "Use PostgreSQL for persistence"
-```
-
-### 3. Connect to Your AI Tool
-
-**Claude Code** — Add to `.claude/settings.json`:
+**Claude Code** — Add to `.claude/settings.json` or `.mcp.json`:
 
 ```json
 {
@@ -106,27 +92,81 @@ speclock decide "Use PostgreSQL for persistence"
 }
 ```
 
-**Windsurf / Cline / Any MCP tool** — Same pattern:
+**Windsurf / Cline / Any MCP tool** — Same pattern as above.
+
+### 2. Add Project Instructions (Required)
+
+> **This is the critical step.** Without project instructions, the AI has the tools but won't use them automatically. With them, SpecLock becomes an active guardrail.
+
+Copy-paste the rules below into your platform's project instruction settings:
+
+| Platform | Where to paste |
+|----------|----------------|
+| **Lovable** | Project Settings → Knowledge |
+| **Cursor** | `.cursorrules` file in project root |
+| **Claude Code** | `CLAUDE.md` file in project root |
+| **Windsurf** | `.windsurfrules` file in project root |
+
+**The rules to paste:**
 
-```json
-{
-  "mcpServers": {
-    "speclock": {
-      "command": "npx",
-      "args": ["-y", "speclock", "serve", "--project", "."]
-    }
-  }
-}
 ```
+## SpecLock Rules (MANDATORY — follow on every message)
 
-### 4. Use It
+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."
 
-The AI tool now has access to **19 SpecLock tools**. The key workflow:
+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 it.
 
-1. **Start session**: AI calls `speclock_session_briefing` — gets full context + what changed
-2. **During work**: AI uses `add_decision`, `log_change`, `check_conflict`, `detect_drift`
-3. **End session**: AI calls `speclock_session_summary` — records what was accomplished
-4. **Next session (any tool)**: Step 1 repeats — full continuity preserved
+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.
+```
+
+See [SPECLOCK-INSTRUCTIONS.md](SPECLOCK-INSTRUCTIONS.md) for platform-specific versions and detailed examples.
+
+### 3. Start Building
+
+That's it. Now when you chat with your AI tool:
+
+1. **Every session starts**: AI auto-loads your project memory — goals, constraints, decisions, history
+2. **During work**: AI auto-captures decisions, logs changes, checks constraints before modifying code
+3. **Constraint protection**: If the AI tries to break something you locked, it stops and warns you
+4. **Every session ends**: AI records what was accomplished
+5. **Next session**: Full continuity — the AI remembers everything from all previous sessions
+
+## How It Works In Practice
+
+### You lock something important:
+```
+You:  "Don't ever touch the auth files"
+AI:   🔒 Locked: "Never modify auth files"
+```
+
+### AI checks before every change:
+```
+You:  "Add social login to the login page"
+AI:   ⚠️ This conflicts with your lock: "Never modify auth files"
+      Should I proceed anyway, or find another approach?
+```
+
+### New session, full memory:
+```
+You:  "Let's keep working on the dashboard"
+AI:   🔒 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.
+```
+
+### You change your mind:
+```
+You:  "Actually, unlock the auth files, I need to change them"
+AI:   You locked: "Never modify auth files". Want me to unlock this?
+You:  "Yes"
+AI:   🔓 Unlocked. Proceeding with auth file changes.
+```
 
 ## MCP Tools (19)
 

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.0",
+  "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;
+}

package/src/mcp/http-server.js

@@ -41,7 +41,7 @@ import {
 } from "../core/git.js";
 
 const PROJECT_ROOT = process.env.SPECLOCK_PROJECT_ROOT || process.cwd();
-const VERSION = "1.1.0";
+const VERSION = "1.2.0";
 const AUTHOR = "Sandeep Roy";
 
 function createSpecLockServer() {
@@ -49,38 +49,37 @@ function createSpecLockServer() {
     { name: "speclock", version: VERSION },
     {
       instructions: [
-        `You have SpecLock connected — an AI Continuity Engine by ${AUTHOR}. Follow these rules AUTOMATICALLY without the user ever having to ask:`,
+        `CRITICAL: You have SpecLock connected — an AI Continuity Engine that remembers project context across sessions. You MUST follow these rules:`,
         ``,
-        `## ON EVERY NEW CONVERSATION / SESSION START:`,
-        `1. IMMEDIATELY call speclock_session_briefing BEFORE responding to the user's first message.`,
-        `2. If it returns "not initialized", call speclock_init first, then proceed normally.`,
-        `3. Use the briefing context to understand the project's goal, constraints, decisions, and history.`,
-        `4. Never ask the user to "initialize SpecLock" or "start a session" — just do it silently.`,
+        `## STEP 1 — FIRST THING IN EVERY CONVERSATION (MANDATORY):`,
+        `Before doing ANYTHING else, call speclock_session_briefing. This loads the project's goal, constraints, decisions, and history from previous sessions.`,
+        `- If it returns "not initialized", call speclock_init first, then tell the user: "I've set up project memory for this workspace. I'll remember your decisions and constraints across sessions."`,
+        `- If it returns context, start your response with a brief one-line status like: "🔒 Project memory loaded — [X] constraints, [Y] decisions tracked from previous sessions." Then proceed to answer the user's actual question.`,
+        `- If there is no meaningful context yet (new project), say: "🔒 Project memory active. I'll automatically remember your key decisions and constraints across sessions." Then proceed normally.`,
         ``,
-        `## AUTOMATIC CONTEXT CAPTURE (do this silently as you work):`,
-        `- When the user describes what they're building → call speclock_set_goal with a concise summary.`,
-        `- When the user says something is non-negotiable (e.g., "always use Supabase", "never remove auth", "must support mobile") → call speclock_add_lock to save it as an immutable constraint.`,
-        `- When the user makes a technology/architecture choice (e.g., "let's use React Query", "we'll go with Stripe") → call speclock_add_decision.`,
-        `- When you complete a significant piece of work → call speclock_log_change.`,
-        `- Look for keywords like "always", "never", "must", "don't ever", "make sure to keep" — these signal constraints that should be locked.`,
+        `## STEP 2 — LISTEN AND CAPTURE (do this continuously as you work):`,
+        `- When the user describes what they're building → call speclock_set_goal.`,
+        `- When the user says something is non-negotiable or uses words like "always", "never", "must", "don't ever change", "make sure to keep", "this is critical" → call speclock_add_lock. Then briefly confirm: "🔒 Locked: [constraint]"`,
+        `- When the user makes a technology or design choice → call speclock_add_decision.`,
+        `- When you complete significant work → call speclock_log_change.`,
         ``,
-        `## BEFORE MAKING SIGNIFICANT CHANGES:`,
-        `- Call speclock_check_conflict with a description of what you're about to do.`,
-        `- If a conflict is detected (confidence HIGH), WARN the user and explain which constraint would be violated.`,
-        `- Do NOT proceed with the change unless the user explicitly says to override or remove the lock.`,
+        `## STEP 3 — PROTECT (before making significant changes):`,
+        `- Before removing features, changing architecture, switching technologies, or modifying core logic → call speclock_check_conflict.`,
+        `- If a conflict is found (confidence HIGH), STOP and warn: "⚠️ This would conflict with a constraint you set: [constraint]. Should I proceed anyway or keep the current approach?"`,
+        `- Do NOT proceed unless the user explicitly confirms.`,
         ``,
-        `## WHEN THE USER ASKS TO REMOVE SOMETHING THEY PREVIOUSLY LOCKED:`,
-        `- Remind them: "You previously locked this constraint: [constraint text]. Want me to remove the lock and proceed?"`,
-        `- If they confirm, call speclock_remove_lock, then proceed.`,
+        `## STEP 4 — REMEMBER (when the user wants to change their mind):`,
+        `- If they want to remove or change something they previously locked, remind them: "You previously locked: [constraint]. Want me to unlock this and proceed?"`,
+        `- If confirmed, call speclock_remove_lock, then proceed.`,
         ``,
-        `## AT THE END OF A CONVERSATION (when the user says goodbye, or the conversation naturally ends):`,
-        `- Call speclock_session_summary with a brief description of what was accomplished.`,
+        `## STEP 5 — CLOSE (when conversation ends):`,
+        `- Call speclock_session_summary with a brief description of what was done.`,
         ``,
-        `## IMPORTANT:`,
-        `- NEVER mention "SpecLock" to the user unless they ask about it. Just use it silently in the background.`,
-        `- The user should feel like the AI simply "remembers everything" — SpecLock is invisible infrastructure.`,
-        `- If the user asks "how do you remember this?" you can explain SpecLock is connected as a memory layer.`,
-        `- When showing the user what you know from previous sessions, present it naturally, not as a data dump.`,
+        `## KEY BEHAVIOR:`,
+        `- The 🔒 emoji is your SpecLock indicator. Users learn to recognize it means their project memory is active.`,
+        `- Keep SpecLock confirmations SHORT — one line max. Don't dump data.`,
+        `- Present remembered context NATURALLY. Instead of "SpecLock says your goal is X", just say "Based on our previous work, the goal is X."`,
+        `- If the user asks "how do you remember this?" — explain that SpecLock is connected as a project memory layer that persists across sessions.`,
       ].join("\n"),
     }
   );

package/src/mcp/server.js

@@ -50,45 +50,44 @@ const PROJECT_ROOT =
   args.project || process.env.SPECLOCK_PROJECT_ROOT || process.cwd();
 
 // --- MCP Server ---
-const VERSION = "1.1.0";
+const VERSION = "1.2.0";
 const AUTHOR = "Sandeep Roy";
 
 const server = new McpServer(
   { name: "speclock", version: VERSION },
   {
     instructions: [
-      `You have SpecLock connected — an AI Continuity Engine by ${AUTHOR}. Follow these rules AUTOMATICALLY without the user ever having to ask:`,
+      `CRITICAL: You have SpecLock connected — an AI Continuity Engine that remembers project context across sessions. You MUST follow these rules:`,
       ``,
-      `## ON EVERY NEW CONVERSATION / SESSION START:`,
-      `1. IMMEDIATELY call speclock_session_briefing BEFORE responding to the user's first message.`,
-      `2. If it returns "not initialized", call speclock_init first, then proceed normally.`,
-      `3. Use the briefing context to understand the project's goal, constraints, decisions, and history.`,
-      `4. Never ask the user to "initialize SpecLock" or "start a session" — just do it silently.`,
+      `## STEP 1 — FIRST THING IN EVERY CONVERSATION (MANDATORY):`,
+      `Before doing ANYTHING else, call speclock_session_briefing. This loads the project's goal, constraints, decisions, and history from previous sessions.`,
+      `- If it returns "not initialized", call speclock_init first, then tell the user: "I've set up project memory for this workspace. I'll remember your decisions and constraints across sessions."`,
+      `- If it returns context, start your response with a brief one-line status like: "🔒 Project memory loaded — [X] constraints, [Y] decisions tracked from previous sessions." Then proceed to answer the user's actual question.`,
+      `- If there is no meaningful context yet (new project), say: "🔒 Project memory active. I'll automatically remember your key decisions and constraints across sessions." Then proceed normally.`,
       ``,
-      `## AUTOMATIC CONTEXT CAPTURE (do this silently as you work):`,
-      `- When the user describes what they're building → call speclock_set_goal with a concise summary.`,
-      `- When the user says something is non-negotiable (e.g., "always use Supabase", "never remove auth", "must support mobile") → call speclock_add_lock to save it as an immutable constraint.`,
-      `- When the user makes a technology/architecture choice (e.g., "let's use React Query", "we'll go with Stripe") → call speclock_add_decision.`,
-      `- When you complete a significant piece of work → call speclock_log_change.`,
-      `- Look for keywords like "always", "never", "must", "don't ever", "make sure to keep" — these signal constraints that should be locked.`,
+      `## STEP 2 — LISTEN AND CAPTURE (do this continuously as you work):`,
+      `- When the user describes what they're building → call speclock_set_goal.`,
+      `- When the user says something is non-negotiable or uses words like "always", "never", "must", "don't ever change", "make sure to keep", "this is critical" → call speclock_add_lock. Then briefly confirm: "🔒 Locked: [constraint]"`,
+      `- When the user makes a technology or design choice → call speclock_add_decision.`,
+      `- When you complete significant work → call speclock_log_change.`,
       ``,
-      `## BEFORE MAKING SIGNIFICANT CHANGES:`,
-      `- Call speclock_check_conflict with a description of what you're about to do.`,
-      `- If a conflict is detected (confidence HIGH), WARN the user and explain which constraint would be violated.`,
-      `- Do NOT proceed with the change unless the user explicitly says to override or remove the lock.`,
+      `## STEP 3 — PROTECT (before making significant changes):`,
+      `- Before removing features, changing architecture, switching technologies, or modifying core logic → call speclock_check_conflict.`,
+      `- If a conflict is found (confidence HIGH), STOP and warn: "⚠️ This would conflict with a constraint you set: [constraint]. Should I proceed anyway or keep the current approach?"`,
+      `- Do NOT proceed unless the user explicitly confirms.`,
       ``,
-      `## WHEN THE USER ASKS TO REMOVE SOMETHING THEY PREVIOUSLY LOCKED:`,
-      `- Remind them: "You previously locked this constraint: [constraint text]. Want me to remove the lock and proceed?"`,
-      `- If they confirm, call speclock_remove_lock, then proceed.`,
+      `## STEP 4 — REMEMBER (when the user wants to change their mind):`,
+      `- If they want to remove or change something they previously locked, remind them: "You previously locked: [constraint]. Want me to unlock this and proceed?"`,
+      `- If confirmed, call speclock_remove_lock, then proceed.`,
       ``,
-      `## AT THE END OF A CONVERSATION (when the user says goodbye, or the conversation naturally ends):`,
-      `- Call speclock_session_summary with a brief description of what was accomplished.`,
+      `## STEP 5 — CLOSE (when conversation ends):`,
+      `- Call speclock_session_summary with a brief description of what was done.`,
       ``,
-      `## IMPORTANT:`,
-      `- NEVER mention "SpecLock" to the user unless they ask about it. Just use it silently in the background.`,
-      `- The user should feel like the AI simply "remembers everything" — SpecLock is invisible infrastructure.`,
-      `- If the user asks "how do you remember this?" you can explain SpecLock is connected as a memory layer.`,
-      `- When showing the user what you know from previous sessions, present it naturally, not as a data dump.`,
+      `## KEY BEHAVIOR:`,
+      `- The 🔒 emoji is your SpecLock indicator. Users learn to recognize it means their project memory is active.`,
+      `- Keep SpecLock confirmations SHORT — one line max. Don't dump data.`,
+      `- Present remembered context NATURALLY. Instead of "SpecLock says your goal is X", just say "Based on our previous work, the goal is X."`,
+      `- If the user asks "how do you remember this?" — explain that SpecLock is connected as a project memory layer that persists across sessions.`,
     ].join("\n"),
   }
 );