Speclock

Your AI keeps breaking things you told it not to touch.SpecLock makes it stop.

Browse all badge variants at sgroy10.github.io/speclock/badge.html · or run speclock badge in your terminal.

Website · npm · Saves Wall · Smithery · GitHub

Developed by Sandeep Roy · Free & Open Source (MIT License)

---

Quick Start

npx speclock protect              # Install in your project (creates CLAUDE.md if missing)
speclock mcp install claude-code  # Wire up MCP for Claude Code (or cursor, windsurf, cline, codex)
speclock doctor                   # Verify everything is set up correctly

That's it. Your AI now has rules it can't ignore. Default mode is WARN (loud warnings, no blocks). Opt in to hard enforcement with speclock protect --strict.

What's New in v5.7.0

• The Saves Wall — publish a save to a public, indexable page with speclock wins --publish (opt-in). Each gets a shareable URL with a rich social card, and a live "🔒 blocked by speclock · N" badge counts every published block. Browse them at /saves.

What's New in v5.6.1

• speclock wins — a shareable "Save Receipt" of everything SpecLock blocked your AI from doing. Screenshot-ready and screenshot-worthy.
• speclock wrapped — a Spotify-Wrapped-style recap of your saves, all-time and monthly (alias: speclock recap).
• Dynamic "🔒 N violations blocked" README badge — a new live badge variant that shows the real number of violations SpecLock has blocked for you. Add it with speclock badge.
• Default WARN mode — no more false-positive blocks. Loud warnings instead. Opt in to strict with --strict or SPECLOCK_STRICT=1.
• speclock mcp install — autoinstaller for Claude Code, Cursor, Windsurf, Cline, Codex. No more hand-editing JSON.
• Greenfield support — speclock protect in fresh projects auto-creates CLAUDE.md with safe defaults.
• speclock doctor — health check verifying installation, git hook, rule files, and MCP integration. Prints exact fix commands for any issues.

What is SpecLock?

SpecLock is an AI constraint engine that enforces your project rules across every AI coding session. Your AI keeps breaking things you told it not to touch — SpecLock makes it stop.

Commands Reference

speclock protect                      # Install pre-commit hook + extract locks from rule files
speclock protect --strict             # Hard enforcement mode (blocks violations)
speclock doctor                       # Health check — verifies install, hooks, rules, MCP
speclock mcp install          # Wire up MCP server (claude-code, cursor, windsurf, cline, codex)
speclock check "action description"   # Test if an action would conflict with locks
speclock add-lock "rule"              # Add a new lock
speclock list-locks                   # Show all locks
speclock enforce hard|advisory        # Change enforcement mode
speclock wins                         # Shareable "Save Receipt" of what SpecLock blocked (screenshot it!)
speclock wins --publish               # Publish your latest save to the public Saves Wall (opt-in)
speclock wrapped                      # Spotify-Wrapped-style recap of your saves (alias: recap)

Full command reference: npx speclock help

---

You:    "Never touch the auth system"
AI:     🔒 Locked.

         ... 5 sessions later ...

You:    "Add social login to the login page"
AI:     ⚠️  BLOCKED — violates lock "Never touch the auth system"
        Matched: auth → authentication (synonym), login → auth (concept)
        Confidence: 100%
        Should I find another approach?

100/100 on Claude's independent test suite. 1043 tests across 24 suites. 0 false positives. 15.7ms per check.

The Problem

AI coding tools have memory now. Claude Code has CLAUDE.md. Cursor has .cursorrules. Mem0 exists.

But memory without enforcement is useless.

Your AI remembers you use PostgreSQL — then switches to MongoDB because it "seemed better." Your AI remembers your auth setup — then rewrites it while "fixing" a bug. You said "never touch the payment logic" 3 sessions ago — the AI doesn't care.

Remembering is not respecting. No existing tool stops the AI from breaking what you locked.

How It Works

You set constraints. SpecLock enforces them — across sessions, across tools, across teams.

speclock lock "Never modify auth files"           → auto-guards src/auth/*.ts
speclock lock "Database must stay PostgreSQL"      → catches "migrate to MongoDB"
speclock lock "Never delete patient records"       → catches "clean up old data"
speclock lock "Don't touch the payment flow"       → catches "streamline checkout"

The semantic engine doesn't do keyword matching. It understands:

• "clean up old data" = deletion (euphemism detection)
• "streamline checkout" = modify payment flow (synonym + concept mapping)
• "temporarily disable logging" = disable logging (temporal evasion detection)
• "Update UI and also drop the users table" = hidden violation (compound splitter)

And it knows what's safe:

• "Enable audit logging" when the lock says "Never disable audit logging" → no conflict (intent alignment)

Quick Start by Platform

Bolt.new / Aider / Any npm Platform

npx speclock setup --goal "Build my app" --template nextjs

Creates SPECLOCK.md, injects rules into package.json, generates .speclock/context/latest.md. The AI reads these automatically.

Claude Code

Add to .mcp.json:

{
  "mcpServers": {
    "speclock": {
      "command": "npx",
      "args": ["-y", "speclock", "serve", "--project", "."]
    }
  }
}

Cursor / Windsurf / Cline

Same config — add to .cursor/mcp.json or equivalent.

Lovable (No Install)

1. Go to Settings → Connectors → New MCP server
2. Enter URL: https://speclock-mcp-production.up.railway.app/mcp
3. Paste [project instructions](SPECLOCK-INSTRUCTIONS.md) into Knowledge

---

Why SpecLock Over Alternatives?

| | Claude Memory | Mem0 | .cursorrules | SpecLock | |---|:---:|:---:|:---:|:---:| | Remembers context | Yes | Yes | Manual | Yes | | Blocks the AI from breaking things | No | No | No | Yes | | Semantic conflict detection | No | No | No | 100/100 score, 0% FP | | Tamper-proof audit trail | No | No | No | HMAC-SHA256 chain | | Hard enforcement (AI cannot proceed) | No | No | No | Yes | | SOC 2 / HIPAA compliance exports | No | No | No | Yes | | Encrypted storage (AES-256-GCM) | No | No | No | Yes | | RBAC + API key auth | No | No | No | 4 roles | | Policy-as-Code DSL | No | No | No | YAML rules | | Works on Bolt.new, Lovable, etc. | No | No | No | Yes |

Other tools remember. SpecLock enforces.

---

Semantic Engine

Not keyword matching — real semantic analysis with Gemini Flash hybrid for universal domain coverage. Scored 100/100 on Claude's independent adversarial test battery (7 suites, including false positives, question framing, patch gateway, and diff analysis).

CategoryDetectionExample Direct violations100%"Delete the auth module" vs lock "Never modify auth" Euphemistic attacks100%"Clean up old patient data" = deletion Temporal evasion100%"Temporarily disable MFA" = disable MFA Dilution attacks100%Violation buried in multi-part request Compound sentences100%"Update UI and also drop users table" Synonym substitution100%"Sunset the API" = remove the API Payment brand names (11 gateways)100%"Add Razorpay" / "Implement PayU" vs "Must use Stripe" Salary/payroll cross-vocab100%"Optimize salary" vs "Payroll records locked" Safety system bypass100%"Disable safety interlock" = bypass safety Unknown domains (via Gemini)100%Gaming, biotech, aerospace, music, legal Safe actions (true negatives)0% FP"Change the font" correctly passes auth locks

Under the hood: 65+ synonym groups · 80+ euphemism mappings · domain concept maps (fintech, e-commerce, IoT, healthcare, SaaS, payments, gaming, telecom, government) · intent classifier · compound sentence splitter · temporal evasion detector · verb tense normalization · UI cosmetic detection · safe-intent patterns · passive voice parsing — all in pure JavaScript. Gemini Flash hybrid for grey-zone cases ($0.01/1000 checks).

---

Hard Enforcement

Two modes:

Advisory (default):  AI gets a warning, decides what to do
Hard mode:           AI is BLOCKED — MCP returns isError, AI cannot proceed

speclock enforce hard   # Enable hard mode — violations above threshold are blocked

• Configurable threshold — default 70%. Only HIGH confidence conflicts block.
• Override with reason — speclock override "JIRA-1234: approved by CTO" (logged to audit trail)
• Auto-escalation — lock overridden 3+ times → auto-flags for review

---

Enterprise Security

API Key Auth + RBAC

speclock auth create-key --role developer --name "CI Bot"
# → sk_speclock_a1b2c3... (shown once, stored as SHA-256 hash)

| Role | Read | Write Locks | Override | Admin | |------|:---:|:---:|:---:|:---:| | viewer | Yes | — | — | — | | developer | Yes | — | With reason | — | | architect | Yes | Yes | Yes | — | | admin | Yes | Yes | Yes | Yes |

AES-256-GCM Encryption

export SPECLOCK_ENCRYPTION_KEY="your-secret"
speclock encrypt   # Encrypts brain.json + events.log at rest

PBKDF2 key derivation (100K iterations). Authenticated encryption. HIPAA 2026 compliant.

HMAC Audit Chain

Every event gets an HMAC-SHA256 hash chained to the previous event. Modify anything — the chain breaks.

$ speclock audit-verify

✓ Audit chain VALID — 247 events, 0 broken links, no tampering detected.

Compliance Exports

speclock export --format soc2    # SOC 2 Type II report (JSON)
speclock export --format hipaa   # HIPAA PHI protection report
speclock export --format csv     # All events for auditor spreadsheets

---

Policy-as-Code

Declarative YAML rules for organization-wide enforcement:

# .speclock/policy.yml
rules:
  - name: "HIPAA PHI Protection"
    match:
      files: ["**/patient/**", "**/medical/**"]
      actions: [delete, modify, export]
    enforce: block
    severity: critical

  - name: "No direct DB mutations"
    match:
      files: ["**/models/**"]
      actions: [delete]
    enforce: warn
    severity: high

Import and export policies between projects. Share constraint templates across your organization.

---

REST API v2

Real-time constraint checking, patch review, and autonomous systems:

# Patch Gateway (v5.1)
POST /api/v2/gateway/review        { description, files, useLLM }

# AI Patch Firewall (v5.2)
POST /api/v2/gateway/review-diff   { description, files, diff, options }
POST /api/v2/gateway/parse-diff    { diff }

# Typed constraint checking
POST /api/v2/check-typed    { metric, value, entity }
POST /api/v2/check-batch    { checks: [...] }

# SSE streaming (real-time violations)
GET  /api/v2/stream

# Spec Compiler
POST /api/v2/compiler/compile  { text, autoApply }

# Code Graph
GET  /api/v2/graph/blast-radius?file=src/core/memory.js
GET  /api/v2/graph/lock-map
POST /api/v2/graph/build

---

51 MCP Tools

Memory — goal, locks, decisions, notes, deploy facts

| Tool | What it does | |------|-------------| | speclock_init | Initialize SpecLock in project | | speclock_get_context | Full context pack (the key tool) | | speclock_set_goal | Set project goal | | speclock_add_lock | Add constraint + auto-guard files | | speclock_remove_lock | Soft-delete a lock | | speclock_add_decision | Record architectural decision | | speclock_add_note | Add pinned note | | speclock_set_deploy_facts | Record deploy config |

Enforcement — conflict detection, hard blocking, overrides

| Tool | What it does | |------|-------------| | speclock_check_conflict | Semantic conflict check against all locks | | speclock_set_enforcement | Switch advisory/hard mode | | speclock_override_lock | Override with reason (audit logged) | | speclock_override_history | View override audit trail | | speclock_semantic_audit | Analyze git diff against locks | | speclock_detect_drift | Scan for constraint violations | | speclock_audit | Audit staged files pre-commit |

Tracking & Sessions — changes, events, session continuity

| Tool | What it does | |------|-------------| | speclock_session_briefing | Start session + full briefing | | speclock_session_summary | End session + record summary | | speclock_log_change | Log a change with files | | speclock_get_changes | Recent tracked changes | | speclock_get_events | Full event log (filterable) | | speclock_checkpoint | Git tag for rollback | | speclock_repo_status | Branch, commit, diff summary |

Intelligence — suggestions, health, templates, reports

| Tool | What it does | |------|-------------| | speclock_suggest_locks | AI-powered lock suggestions | | speclock_health | Health score + multi-agent timeline | | speclock_apply_template | Apply constraint template | | speclock_report | Violation stats + most tested locks |

Enterprise — audit, compliance, policy, telemetry

| Tool | What it does | |------|-------------| | speclock_verify_audit | Verify HMAC chain integrity | | speclock_export_compliance | SOC 2 / HIPAA / CSV reports | | speclock_policy_evaluate | Evaluate policy rules | | speclock_policy_manage | CRUD for policy rules | | speclock_telemetry | Opt-in usage analytics |

Typed Constraints — numerical, range, state, temporal (v5.0)

| Tool | What it does | |------|-------------| | speclock_add_typed_lock | Add typed constraint (numerical/range/state/temporal) | | speclock_check_typed | Check proposed values against typed constraints | | speclock_list_typed_locks | List all typed constraints | | speclock_update_threshold | Update typed lock thresholds |

Spec Compiler & Code Graph — NL→constraints, dependency analysis (v5.0)

| Tool | What it does | |------|-------------| | speclock_compile_spec | Compile natural language into structured constraints | | speclock_build_graph | Build/refresh code dependency graph | | speclock_blast_radius | Calculate blast radius of file changes | | speclock_map_locks | Map locks to actual code files |

Patch Gateway & AI Patch Firewall — change review, diff analysis (v5.1/v5.2)

| Tool | What it does | |------|-------------| | speclock_review_patch | ALLOW/WARN/BLOCK verdict for proposed changes | | speclock_review_patch_diff | Diff-native review with signal scoring + unified verdict | | speclock_parse_diff | Parse unified diff into structured changes (debug/inspect) |

Universal Rules Sync & Incident Replay — cross-tool sync, session replay (v5.3)

| Tool | What it does | |------|-------------| | speclock_sync_rules | Sync constraints to Cursor, Claude, Copilot, Windsurf, Gemini, Aider, AGENTS.md | | speclock_list_sync_formats | List all available sync formats | | speclock_replay | Replay a session's activity — what AI tried and what was caught | | speclock_list_sessions | List available sessions for replay | | speclock_drift_score | 0-100 project integrity metric — how much AI deviated from intent | | speclock_coverage | Lock Coverage Audit — find unprotected code areas | | speclock_strengthen | Grade locks and suggest stronger versions |

---

CLI

# Setup
speclock setup --goal "Build my app" --template nextjs

# Constraints
speclock lock "Never modify auth files" --tags auth,security
speclock lock remove 
speclock check "Add social login"              # Test before doing

# Enforcement
speclock enforce hard                          # Block violations
speclock override  "JIRA-1234"         # Override with reason

# Audit & Compliance
speclock audit-verify                          # Verify HMAC chain
speclock

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sgroy10](https://github.com/sgroy10)
- **Source:** [sgroy10/speclock](https://github.com/sgroy10/speclock)
- **License:** MIT
- **Homepage:** https://sgroy10.github.io/speclock/

Install and usage instructions live in the source repository linked above.