speclock 1.2.0 → 1.2.1

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speclock",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "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",

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"),
   }
 );