speclock 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sandeep Roy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,289 @@
+# SpecLock
+
+**AI Continuity Engine** — The MCP server that kills AI amnesia.
+
+> Developed by **Sandeep Roy** ([github.com/sgroy10](https://github.com/sgroy10))
+
+[![npm version](https://img.shields.io/npm/v/speclock.svg)](https://www.npmjs.com/package/speclock)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+
+---
+
+## The Problem
+
+Every AI coding tool forgets. Every. Single. Session.
+
+- Claude Code forgets the decisions you made yesterday
+- Cursor forgets the constraints you set last week
+- Codex rebuilds what another agent already built
+- Your AI agent violates rules it agreed to 3 sessions ago
+
+**AI amnesia is the #1 productivity killer in AI-assisted development.**
+
+## The Solution
+
+SpecLock maintains a `.speclock/` directory inside your repo that gives every AI agent perfect memory — across sessions, across tools, across time.
+
+```
+.speclock/
+├── brain.json         # Structured project memory
+├── events.log         # Append-only event ledger (JSONL)
+├── patches/           # Git diffs captured per event
+└── context/
+    └── 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.
+
+**No context is ever lost again.**
+
+## Why SpecLock Wins
+
+| Feature | CLAUDE.md / .cursorrules | Chat History | Memory Plugins | **SpecLock** |
+|---------|--------------------------|--------------|----------------|--------------|
+| Structured memory | Static files | Noise-heavy | Generic | **Structured brain.json** |
+| Constraint enforcement | None | None | None | **Active lock checking** |
+| Conflict detection | None | None | None | **Semantic + synonym matching** |
+| Drift detection | None | None | None | **Auto-scan against locks** |
+| Git-aware | No | No | No | **Checkpoints, diffs, reverts** |
+| Multi-agent | No | No | Partial | **Full session timeline** |
+| Auto-suggestions | No | No | No | **AI-powered lock suggestions** |
+| Cross-tool | Tool-specific | Tool-specific | Tool-specific | **Universal MCP** |
+
+**Other tools remember. SpecLock enforces.**
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install -g speclock
+```
+
+Or use directly with npx:
+
+```bash
+npx speclock init
+```
+
+### 2. Initialize in Your Project
+
+```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`:
+
+```json
+{
+  "mcpServers": {
+    "speclock": {
+      "command": "npx",
+      "args": ["-y", "speclock", "serve", "--project", "."]
+    }
+  }
+}
+```
+
+**Cursor** — Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "speclock": {
+      "command": "npx",
+      "args": ["-y", "speclock", "serve", "--project", "."]
+    }
+  }
+}
+```
+
+**Windsurf / Cline / Any MCP tool** — Same pattern:
+
+```json
+{
+  "mcpServers": {
+    "speclock": {
+      "command": "npx",
+      "args": ["-y", "speclock", "serve", "--project", "."]
+    }
+  }
+}
+```
+
+### 4. Use It
+
+The AI tool now has access to **19 SpecLock tools**. The key workflow:
+
+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
+
+## MCP Tools (19)
+
+### Memory Management
+| Tool | Purpose |
+|------|---------|
+| `speclock_init` | Initialize SpecLock in project |
+| `speclock_get_context` | **THE KEY TOOL** — full context pack |
+| `speclock_set_goal` | Set/update project goal |
+| `speclock_add_lock` | Add non-negotiable constraint |
+| `speclock_remove_lock` | Deactivate a lock by ID |
+| `speclock_add_decision` | Record an architectural decision |
+| `speclock_add_note` | Add a pinned note |
+| `speclock_set_deploy_facts` | Record deploy configuration |
+
+### Change Tracking
+| Tool | Purpose |
+|------|---------|
+| `speclock_log_change` | Manually log a significant change |
+| `speclock_get_changes` | Get recent tracked changes |
+| `speclock_get_events` | Get event log (filterable by type/time) |
+
+### Continuity Protection
+| Tool | Purpose |
+|------|---------|
+| `speclock_check_conflict` | Check action against locks (semantic matching) |
+| `speclock_session_briefing` | Start session + full briefing |
+| `speclock_session_summary` | End session + record summary |
+
+### Git Integration
+| Tool | Purpose |
+|------|---------|
+| `speclock_checkpoint` | Create named git tag for rollback |
+| `speclock_repo_status` | Branch, commit, changed files, diff |
+
+### Intelligence (NEW in v1.1)
+| Tool | Purpose |
+|------|---------|
+| `speclock_suggest_locks` | AI-powered lock suggestions from patterns |
+| `speclock_detect_drift` | Scan changes for constraint violations |
+| `speclock_health` | Health score + multi-agent timeline |
+
+## Killer Features
+
+### Semantic Conflict Detection
+
+Not just keyword matching — SpecLock understands synonyms, negation, and destructive intent:
+
+```
+Lock: "No breaking changes to public API"
+
+Action: "remove the external endpoints"
+Result: [HIGH] Conflict detected (confidence: 85%)
+  - synonym match: remove/delete, external/public, endpoints/api
+  - lock prohibits this action (negation detected)
+  - destructive action against locked constraint
+```
+
+### Auto-Lock Suggestions
+
+SpecLock analyzes your decisions and notes for commitment language and suggests constraints:
+
+```
+Decision: "Always use REST for public endpoints"
+→ Suggestion: Promote to lock (contains "always" — strong commitment language)
+
+Project mentions "security" but has no security lock
+→ Suggestion: "No secrets or credentials in source code"
+```
+
+### Drift Detection
+
+Proactively scans recent changes against your locks:
+
+```
+Lock: "No database schema changes without migration"
+Change: "Modified users table schema directly"
+→ [HIGH] Drift detected — review immediately
+```
+
+### Multi-Agent Timeline
+
+Track which AI tools touched your project and what they did:
+
+```
+Health Check — Score: 85/100 (Grade: A)
+
+Multi-Agent Timeline:
+- claude-code: 12 sessions, last active 2026-02-24
+- cursor: 5 sessions, last active 2026-02-23
+- codex: 2 sessions, last active 2026-02-20
+```
+
+## CLI Commands
+
+```
+speclock init                          Initialize SpecLock
+speclock goal <text>                   Set project goal
+speclock lock <text> [--tags a,b]      Add a SpecLock constraint
+speclock lock remove <id>              Remove a lock
+speclock decide <text>                 Record a decision
+speclock note <text>                   Add a note
+speclock facts deploy --provider X     Set deploy facts
+speclock context                       Generate and print context pack
+speclock watch                         Start file watcher
+speclock serve [--project <path>]      Start MCP server
+speclock status                        Show brain summary
+```
+
+## Why MCP?
+
+MCP (Model Context Protocol) is the universal integration standard for AI tools. One SpecLock MCP server works with:
+
+- Claude Code
+- Cursor
+- Windsurf
+- Cline
+- Codex
+- Any MCP-compatible tool
+
+SpecLock is infrastructure, not a competitor. It makes **every** AI coding tool better.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│            AI Tool (Claude Code, Cursor, etc.)          │
+└────────────────────┬────────────────────────────────────┘
+                     │ MCP Protocol (stdio)
+┌────────────────────▼────────────────────────────────────┐
+│           SpecLock MCP Server (19 tools)                │
+│   Memory | Tracking | Protection | Git | Intelligence   │
+└────────────────────┬────────────────────────────────────┘
+                     │
+              .speclock/
+              ├── brain.json      (structured memory)
+              ├── events.log      (immutable audit trail)
+              ├── patches/        (git diffs per event)
+              └── context/        (generated context packs)
+```
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR on [GitHub](https://github.com/sgroy10/speclock).
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file.
+
+## Author
+
+**Developed by Sandeep Roy**
+
+- GitHub: [github.com/sgroy10](https://github.com/sgroy10)
+- Repository: [github.com/sgroy10/speclock](https://github.com/sgroy10/speclock)
+- npm: [npmjs.com/package/speclock](https://www.npmjs.com/package/speclock)
+
+---
+
+*SpecLock — Because no AI session should ever forget.*

package/bin/speclock.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../src/cli/index.js";

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "speclock",
+  "version": "1.1.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",
+  "bin": {
+    "speclock": "./bin/speclock.js"
+  },
+  "scripts": {
+    "start": "node src/mcp/server.js",
+    "serve": "node src/mcp/server.js",
+    "test": "node --experimental-vm-modules node_modules/.bin/jest"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "ai",
+    "ai-memory",
+    "ai-continuity",
+    "context",
+    "memory",
+    "claude",
+    "claude-code",
+    "cursor",
+    "codex",
+    "windsurf",
+    "cline",
+    "speclock",
+    "ai-amnesia",
+    "model-context-protocol",
+    "drift-detection",
+    "constraint-enforcement"
+  ],
+  "author": "Sandeep Roy (https://github.com/sgroy10)",
+  "license": "MIT",
+  "homepage": "https://github.com/sgroy10/speclock#readme",
+  "bugs": {
+    "url": "https://github.com/sgroy10/speclock/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sgroy10/speclock.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "chokidar": "^3.6.0",
+    "zod": "^3.25.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/cli/index.js

@@ -0,0 +1,285 @@
+import path from "path";
+import {
+  ensureInit,
+  setGoal,
+  addLock,
+  removeLock,
+  addDecision,
+  addNote,
+  updateDeployFacts,
+  watchRepo,
+} from "../core/engine.js";
+import { generateContext } from "../core/context.js";
+import { readBrain } from "../core/storage.js";
+
+// --- Argument parsing ---
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const cmd = args.shift() || "";
+  return { cmd, args };
+}
+
+function parseFlags(args) {
+  const out = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = args[i + 1];
+      if (!next || next.startsWith("--")) {
+        out[key] = true;
+      } else {
+        out[key] = next;
+        i++;
+      }
+    } else {
+      out._.push(a);
+    }
+  }
+  return out;
+}
+
+function parseTags(raw) {
+  if (!raw) return [];
+  return raw
+    .split(",")
+    .map((t) => t.trim())
+    .filter(Boolean);
+}
+
+function rootDir() {
+  return process.cwd();
+}
+
+// --- Help text ---
+
+function printHelp() {
+  console.log(`
+SpecLock v1.1.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
+
+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)
+
+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
+`);
+}
+
+// --- Status display ---
+
+function showStatus(root) {
+  const brain = readBrain(root);
+  if (!brain) {
+    console.log("SpecLock not initialized. Run: speclock init");
+    return;
+  }
+
+  const activeLocks = brain.specLock.items.filter((l) => l.active !== false);
+
+  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(`Decisions: ${brain.decisions.length}`);
+  console.log(`Notes: ${brain.notes.length}`);
+  console.log(`Events: ${brain.events.count}`);
+  console.log(`Deploy: ${brain.facts.deploy.provider}`);
+
+  if (brain.sessions.current) {
+    console.log(`Session: active (${brain.sessions.current.toolUsed})`);
+  } else {
+    console.log(`Session: none active`);
+  }
+
+  if (brain.sessions.history.length > 0) {
+    const last = brain.sessions.history[0];
+    console.log(
+      `Last session: ${last.toolUsed} — ${last.summary || "(no summary)"}`
+    );
+  }
+
+  console.log(`Recent changes: ${brain.state.recentChanges.length}`);
+  console.log(`Reverts: ${brain.state.reverts.length}`);
+  console.log("");
+}
+
+// --- Main ---
+
+async function main() {
+  const { cmd, args } = parseArgs(process.argv);
+  const root = rootDir();
+
+  if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (cmd === "init") {
+    ensureInit(root);
+    console.log("SpecLock initialized.");
+    return;
+  }
+
+  if (cmd === "goal") {
+    const text = args.join(" ").trim();
+    if (!text) {
+      console.error("Error: Goal text is required.");
+      console.error("Usage: speclock goal <text>");
+      process.exit(1);
+    }
+    setGoal(root, text);
+    console.log(`Goal set: "${text}"`);
+    return;
+  }
+
+  if (cmd === "lock") {
+    // Check for "lock remove <id>"
+    if (args[0] === "remove") {
+      const lockId = args[1];
+      if (!lockId) {
+        console.error("Error: Lock ID is required.");
+        console.error("Usage: speclock lock remove <lockId>");
+        process.exit(1);
+      }
+      const result = removeLock(root, lockId);
+      if (result.removed) {
+        console.log(`Lock removed: "${result.lockText}"`);
+      } else {
+        console.error(result.error);
+        process.exit(1);
+      }
+      return;
+    }
+
+    const flags = parseFlags(args);
+    const text = flags._.join(" ").trim();
+    if (!text) {
+      console.error("Error: Lock text is required.");
+      console.error("Usage: speclock lock <text> [--tags a,b] [--source user]");
+      process.exit(1);
+    }
+    const { lockId } = addLock(root, text, parseTags(flags.tags), flags.source || "user");
+    console.log(`SpecLock added (${lockId}): "${text}"`);
+    return;
+  }
+
+  if (cmd === "decide") {
+    const flags = parseFlags(args);
+    const text = flags._.join(" ").trim();
+    if (!text) {
+      console.error("Error: Decision text is required.");
+      console.error("Usage: speclock decide <text> [--tags a,b]");
+      process.exit(1);
+    }
+    const { decId } = addDecision(root, text, parseTags(flags.tags), flags.source || "user");
+    console.log(`Decision recorded (${decId}): "${text}"`);
+    return;
+  }
+
+  if (cmd === "note") {
+    const flags = parseFlags(args);
+    const text = flags._.join(" ").trim();
+    if (!text) {
+      console.error("Error: Note text is required.");
+      console.error("Usage: speclock note <text> [--pinned]");
+      process.exit(1);
+    }
+    const pinned = flags.pinned !== false;
+    const { noteId } = addNote(root, text, pinned);
+    console.log(`Note added (${noteId}): "${text}"`);
+    return;
+  }
+
+  if (cmd === "facts") {
+    const sub = args.shift();
+    if (sub !== "deploy") {
+      console.error("Error: Only 'facts deploy' is supported.");
+      console.error(
+        "Usage: speclock facts deploy --provider X --branch Y"
+      );
+      process.exit(1);
+    }
+    const flags = parseFlags(args);
+    const payload = {
+      provider: flags.provider,
+      branch: flags.branch,
+      notes: flags.notes,
+      url: flags.url,
+    };
+    if (flags.autoDeploy !== undefined) {
+      payload.autoDeploy =
+        String(flags.autoDeploy).toLowerCase() === "true";
+    }
+    updateDeployFacts(root, payload);
+    console.log("Deploy facts updated.");
+    return;
+  }
+
+  if (cmd === "context") {
+    const md = generateContext(root);
+    console.log(md);
+    return;
+  }
+
+  if (cmd === "watch") {
+    await watchRepo(root);
+    return;
+  }
+
+  if (cmd === "serve") {
+    // Start MCP server — pass through --project if provided
+    const flags = parseFlags(args);
+    const projectArg = flags.project || root;
+    process.env.SPECLOCK_PROJECT_ROOT = projectArg;
+    await import("../mcp/server.js");
+    return;
+  }
+
+  if (cmd === "status") {
+    showStatus(root);
+    return;
+  }
+
+  console.error(`Unknown command: ${cmd}`);
+  console.error("Run 'speclock --help' for usage.");
+  process.exit(1);
+}
+
+main().catch((err) => {
+  console.error("SpecLock error:", err.message);
+  process.exit(1);
+});