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
--strictorSPECLOCK_STRICT=1. speclock mcp install <client>— autoinstaller for Claude Code, Cursor, Windsurf, Cline, Codex. No more hand-editing JSON.- Greenfield support —
speclock protectin 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 <client> # 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)
- Go to Settings → Connectors → New MCP server
- Enter URL:
https://speclock-mcp-production.up.railway.app/mcp - Paste project instructions 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).
<table> <tr><td><b>Category</b></td><td><b>Detection</b></td><td><b>Example</b></td></tr> <tr><td>Direct violations</td><td>100%</td><td>"Delete the auth module" vs lock "Never modify auth"</td></tr> <tr><td>Euphemistic attacks</td><td>100%</td><td>"Clean up old patient data" = deletion</td></tr> <tr><td>Temporal evasion</td><td>100%</td><td>"Temporarily disable MFA" = disable MFA</td></tr> <tr><td>Dilution attacks</td><td>100%</td><td>Violation buried in multi-part request</td></tr> <tr><td>Compound sentences</td><td>100%</td><td>"Update UI and also drop users table"</td></tr> <tr><td>Synonym substitution</td><td>100%</td><td>"Sunset the API" = remove the API</td></tr> <tr><td>Payment brand names (11 gateways)</td><td>100%</td><td>"Add Razorpay" / "Implement PayU" vs "Must use Stripe"</td></tr> <tr><td>Salary/payroll cross-vocab</td><td>100%</td><td>"Optimize salary" vs "Payroll records locked"</td></tr> <tr><td>Safety system bypass</td><td>100%</td><td>"Disable safety interlock" = bypass safety</td></tr> <tr><td>Unknown domains (via Gemini)</td><td>100%</td><td>Gaming, biotech, aerospace, music, legal</td></tr> <tr><td>Safe actions (true negatives)</td><td>0% FP</td><td>"Change the font" correctly passes auth locks</td></tr> </table>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 <lockId> "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
<details> <summary><b>Memory</b> — goal, locks, decisions, notes, deploy facts</summary>| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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) |
| 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 <id>
speclock check "Add social login" # Test before doing
# Enforcement
speclock enforce hard # Block violations
speclock override <lockId> "JIRA-1234" # Override with reason
# Audit & Compliance
speclock audit-verify # Verify HMAC chain
speclock export --format soc2 # Compliance report
speclock audit-semantic # Semantic pre-commit
# Git
speclock hook install # Pre-commit hook
speclock audit # Audit staged files
# Templates
speclock template apply safe-defaults # Vibe coding seatbelt (5 locks)
speclock template apply solo-founder # Indie builder essentials (3 locks)
speclock template apply hipaa # HIPAA healthcare (8 locks)
speclock template apply api-stability # API contract protection (6 locks)
speclock template apply nextjs # Next.js constraints
speclock template apply security-hardened # Security hardening
# Sync to AI tools
speclock sync --all # Sync to ALL tools
speclock sync --format cursor # Cursor only
speclock sync --format claude # Claude Code only
speclock sync --preview windsurf # Preview without writing
# Incident Replay
speclock replay # Replay last session
speclock replay --list # List sessions
speclock replay --session <id> # Replay specific session
# Project Health
speclock drift # Drift Score (0-100)
speclock drift --days 7 # Last 7 days only
speclock coverage # Lock Coverage Audit
speclock strengthen # Grade and improve locks
# Share & Stats
speclock wins # Shareable "Save Receipt" (screenshot it!)
speclock wrapped # All-time + monthly recap (alias: recap)
speclock stats # Your local usage dashboard
speclock badge # Print README badges (6 variants + live badge)
# Auth
speclock auth create-key --role developer
speclock auth rotate-key <keyId>
# Policy
speclock policy init # Create policy.yml
speclock policy evaluate --files "src/auth/*" # Test against rules
Full command reference: npx speclock help
Auto-Guard
When you lock something, SpecLock finds related files and injects a warning the AI sees when it opens them:
speclock lock "Never modify auth files"
→ Auto-guarded 2 files:
🔒 src/components/Auth.tsx
🔒 src/contexts/AuthContext.tsx
The AI opens the file and sees:
// ============================================================
// SPECLOCK-GUARD — DO NOT MODIFY THIS FILE
// LOCKED: Never modify auth files
// ONLY "unlock" or "remove the lock" is permission to edit.
// ============================================================
Architecture
┌──────────────────────────────────────────────────┐
│ AI Tool (Claude Code, Cursor, Bolt.new...) │
└────────────┬──────────────────┬──────────────────┘
│ │
MCP Protocol (51 tools) npm File-Based
│ (SPECLOCK.md + CLI)
│ │
┌────────────▼──────────────────▼──────────────────┐
│ SpecLock Core Engine │
│ │
│ Semantic Engine ─── 65+ synonym groups │
│ HMAC Audit ──────── SHA-256 hash chain │
│ Enforcer ────────── advisory / hard block │
│ Auth + RBAC ─────── 4 roles, API keys │
│ AES-256-GCM ─────── encrypted at rest │
│ Policy DSL ──────── YAML rules │
│ Compliance ──────── SOC 2, HIPAA, CSV │
│ SSO ─────────────── Okta, Azure AD, Auth0 │
└──────────────────────┬───────────────────────────┘
│
.speclock/
├── brain.json (project memory)
├── events.log (HMAC audit trail)
├── policy.yml (policy rules)
├── auth.json (API keys — gitignored)
└── context/
└── latest.md (AI-readable context)
3 npm dependencies. Zero runtime dependencies for the semantic engine. Pure JavaScript.
Configuration
| Variable | Default | Description |
|---|---|---|
SPECLOCK_API_KEY | — | API key for authenticated access |
SPECLOCK_ENCRYPTION_KEY | — | Enables AES-256-GCM encryption at rest |
SPECLOCK_NO_PROXY | false | Set true for heuristic-only mode (~250ms). Skips the Gemini proxy (~2s) |
SPECLOCK_LLM_KEY | — | Your own LLM API key (Gemini/OpenAI/Anthropic) |
GEMINI_API_KEY | — | Google Gemini API key for hybrid conflict detection |
SPECLOCK_TELEMETRY | false | Opt-in anonymous usage analytics |
Tip: The heuristic engine alone scores 95%+ accuracy at ~250ms. The Gemini proxy adds cross-domain coverage but takes ~2s. For fastest response, set
SPECLOCK_NO_PROXY=true.
Test Results
Pre-publish gate runs all 24 suites before every npm publish. If any test fails, publish is blocked.
| Suite | Tests | Pass Rate | What it covers |
|---|---|---|---|
| Real-World Testers | 111 | 100% | 5 developers, 30+ locks, diverse domains |
| Adversarial Conflict | 46 | 100% | Euphemisms, temporal evasion, compound sentences |
| Phase 4 (Multi-domain) | 91 | 100% | Fintech, e-commerce, IoT, healthcare, SaaS |
| Sam (Enterprise HIPAA) | 124 | 100% | HIPAA locks, PHI, encryption, RBAC |
| Auth & Crypto | 114 | 100% | API keys, RBAC, AES-256 encryption |
| John (Indie Dev Journey) | 86 | 100% | 8-session Bolt.new build with 5 locks |
| Diff-Native Review | 76 | 100% | Interface breaks, schema changes, API impact |
| Patch Gateway | 57 | 100% | ALLOW/WARN/BLOCK verdicts, blast radius |
| Compliance Export | 50 | 100% | SOC 2, HIPAA, CSV formats |
| Enforcement | 40 | 100% | Hard/advisory mode, overrides |
| Audit Chain | 35 | 100% | HMAC-SHA256 chain integrity |
| Code Graph | 33 | 100% | Import parsing, blast radius, lock mapping |
| Spec Compiler | 24 | 100% | NL→constraints parsing, auto-apply |
| Typed Constraints | 13 | 100% | Numerical, range, state, temporal validation |
| Claude Regression | 9 | 100% | Vue detection, safe-intent, patch gateway |
| Question Framing | 9 | 100% | "What if we..." and "How hard would it be..." |
| REST API v2 | 9 | 100% | Typed constraint endpoints, SSE |
| PII/Export Detection | 8 | 100% | SSN, email export, data access violations |
| Guardian (Protect) | 47 | 100% | Zero-config rule file extraction |
| Total | 1043 | 100% | 24 suites, 15+ domains |
External validation: Claude's independent 7-suite adversarial test battery — 100/100 (100%) on v5.7.0. Zero false positives. Zero missed violations. 15.7ms per check.
Tested across: fintech, e-commerce, IoT, healthcare, SaaS, gaming, biotech, aerospace, payments, payroll, robotics, autonomous systems, telecom, insurance, government. All 11 Indian payment gateways detected. Zero false positives on UI/cosmetic actions.
Real-World Tested
John — Indie developer on Bolt.new
8 sessions building an ecommerce app. 5 locks (auth, Firebase, Supabase, shipping, Stripe). Every direct violation caught. Every euphemistic attack caught ("clean up auth", "modernize database", "streamline serverless"). Zero false positives on safe actions (product page, cart, dark mode). 86/86 tests passed.
Sam — Senior engineer building a HIPAA hospital ERP
10 sessions with 8 HIPAA locks. Every violation caught — expose PHI, remove encryption, disable audit, downgrade MFA, bypass FHIR. Euphemistic HIPAA attacks caught ("simplify data flow", "modernize auth"). Full auth + RBAC + encryption + compliance export workflow verified. 124/124 tests passed.
Pricing
| Tier | Price | What you get |
|---|---|---|
| Free | $0 | 10 locks, conflict detection, MCP, CLI |
| Pro | $19/mo | Unlimited locks, HMAC audit, compliance exports |
| Enterprise | $99/mo | + RBAC, encryption, SSO, policy-as-code |
Changelog
Prior-version feature tours. The Quick Start and What's New sections above cover v5.7.0 — this section preserves details on features shipped in v5.0–v5.5.
v5.4 — Drift Score, Lock Coverage, Lock Strengthener
Drift Score. How much has your AI-built project drifted from your original intent? Only SpecLock can answer this — because only SpecLock knows what was intended vs what was done.
$ speclock drift
Drift Score: 23/100 (B) — minor drift
Trend: improving | Period: 30 days | Active locks: 8
Signal Breakdown:
Violations: 6/30 (4 violations in 12 checks)
Overrides: 5/20 (1 override)
Reverts: 3/15 (1 revert detected)
Lock churn: 0/15 (0 removed, 3 added)
Goal stability: 0/10 (1 goal change)
Session gaps: 9/10 (3/5 unsummarized)
README badge: 
Lock Coverage Audit. SpecLock scans your codebase and tells you what's unprotected:
$ speclock coverage
Lock Coverage: 60% (B) — partially protected
[COVERED] CRITICAL authentication 2 file(s)
[EXPOSED] CRITICAL payments 1 file(s)
[COVERED] CRITICAL secrets 0 file(s)
[COVERED] HIGH api-routes 2 file(s)
Suggested Locks (ready to apply):
1. [CRITICAL] payments (1 file at risk)
speclock lock "Never modify payment processing or billing without permission"
Like a security scanner, but for AI constraint gaps.
Lock Strengthener. Your locks might be too vague. SpecLock grades each one and suggests improvements:
$ speclock strengthen
Lock Strength: 72/100 (B) — 3 strong, 1 weak
[WEAK ] 45/100 (D) "don't touch auth"
Issue: Too vague — short locks miss edge cases
Issue: No specific scope
Suggested: "Never modify, refactor, or delete auth..."
[STRONG] 90/100 (A) "Never expose API keys in client-side code, logs, or error messages"
v5.3 — Universal Rules Sync, Incident Replay, Safety Templates
Universal Rules Sync. One command syncs your SpecLock constraints to every AI coding tool:
speclock sync --all
SpecLock Sync Complete
✓ Cursor → .cursor/rules/speclock.mdc
✓ Claude Code → CLAUDE.md
✓ AGENTS.md → AGENTS.md (Linux Foundation standard)
✓ Windsurf → .windsurf/rules/speclock.md
✓ GitHub Copilot → .github/copilot-instructions.md
✓ Gemini → GEMINI.md
✓ Aider → .aider.conf.yml
7 file(s) synced.
Define constraints once in SpecLock, sync everywhere. --format cursor for single format, --preview to dry-run, --list to see supported formats.
Incident Replay. Flight recorder for your AI coding sessions:
speclock replay
Session: ses_a1b2c3 (claude-code, 47 min)
────────────────────────────────────────────
14:02 [ALLOW] Create user profile component
14:08 [ALLOW] Add form validation
14:15 [WARN] Simplify authentication flow
→ matched lock: "Never modify auth"
14:23 [BLOCK] Clean up old user records
→ euphemism detected: "clean up" = deletion
14:31 [ALLOW] Update landing page hero section
Score: 5 events | 3 allowed | 1 warned | 1 BLOCKED
speclock replay --list lists sessions; --session <id> replays a specific one.
Safety Templates. Pre-built constraint packs:
speclock template apply safe-defaults # 5 locks — "Vibe Coding Seatbelt"
speclock template apply solo-founder # 3 locks — auth, payments, data
speclock template apply hipaa # 8 locks — HIPAA healthcare
speclock template apply api-stability # 6 locks — API contract protection
Safe Defaults prevents the 5 most common AI disasters: database deletion, auth removal, secret exposure, error-handling removal, logging disablement.
v5.2 — AI Patch Firewall
Reviews actual diffs, not just descriptions. Catches things intent review misses:
POST /api/v2/gateway/review-diff
{
"description": "Remove password column",
"diff": "diff --git a/migrations/001.sql ..."
}
→ { verdict: "BLOCK",
reviewMode: "unified",
intentVerdict: "ALLOW", ← description alone looks safe
diffVerdict: "BLOCK", ← diff reveals destructive schema change
signals: {
schemaChange: { score: 12, isDestructive: true },
interfaceBreak: { score: 10 },
protectedSymbolEdit: { score: 8 },
dependencyDrift: { score: 5 },
publicApiImpact: { score: 0 }
},
recommendation: { action: "require_approval" } }
Signal detection: interface breaks, protected symbol edits in locked zones, dependency drift, schema/migration destructive changes, public API route changes. Hard escalation: auto-BLOCK on destructive schema changes, removed API routes, protected symbol edits. Unified review: merges intent (35%) + diff (65%), takes the stronger verdict.
v5.1 — Patch Gateway
One API call gates every change. Takes a description + file list, returns ALLOW/WARN/BLOCK:
speclock_review_patch({
description: "Add social login to auth page",
files: ["src/auth/login.js"]
})
→ { verdict: "BLOCK", riskScore: 85,
reasons: [{ type: "semantic_conflict", lock: "Never modify auth" }],
blastRadius: { impactPercent: 28.3 },
summary: "BLOCKED. 1 constraint conflict. 12 files affected." }
Combines semantic conflict detection + lock-to-file mapping + blast radius + typed constraint awareness into a single risk score (0-100).
v5.0 — Spec Compiler, Code Graph, Typed Constraints, Python SDK & ROS2
Spec Compiler. Paste a PRD, README, or architecture doc — SpecLock extracts all constraints automatically:
Input: "We're building a fintech app. Use React and FastAPI.
Never touch the auth module. Response time must stay
under 200ms. Payments go through Stripe."
Output: 2 text locks:
- "Never touch the auth module"
- "Payments go through Stripe — don't change provider"
1 typed lock:
- response_time_ms <= 200 (numerical)
2 decisions:
- "Use React for frontend"
- "Use FastAPI for backend"
Uses Gemini Flash by default ($0.01 per 1000 compilations).
Code Graph. Live dependency graph of your codebase. Parses JS/TS/Python imports.
$ speclock blast-radius src/core/memory.js
Direct Dependents: 8 files
Transitive Impact: 14 files (33% of codebase)
Max Depth: 4 hops
Lock-to-file mapping auto-maps locks to source files; module detection groups files into logical modules.
Typed Constraints. Real-time value and state checking for autonomous systems, IoT, robotics:
// Numerical: speed must be <= 2.0 m/s
{ constraintType: "numerical", metric: "speed_mps", operator: "<=", value: 2.0 }
// Range: temperature must stay between 20-25°C
{ constraintType: "range", metric: "temperature_c", min: 20, max: 25 }
// State: never go from armed → disarmed without approval
{ constraintType: "state", metric: "system_mode", forbidden: [{ from: "armed", to: "disarmed" }] }
// Temporal: heartbeat must occur every 30 seconds
{ constraintType: "temporal", metric: "heartbeat_s", operator: "<=", value: 30 }
Python SDK & ROS2.
pip install speclock-sdk
from speclock import SpecLock
sl = SpecLock(project_root=".")
result = sl.check_text("Switch database to MongoDB")
result = sl.check_typed(metric="speed_mps", value=3.5)
result = sl.check(action="Increase speed", speed_mps=3.5)
Uses the same .speclock/brain.json as the Node.js MCP server. ROS2 Guardian Node subscribes to /joint_states, /cmd_vel, /speclock/state_transition; publishes violations to /speclock/violations; triggers emergency stop via /speclock/emergency_stop.
Show your support
If SpecLock saves your project from a 3am incident, add this badge to your README:
[](https://github.com/sgroy10/speclock)
Or run speclock badge in your terminal to see all variants. Full gallery: sgroy10.github.io/speclock/badge.html · Full docs: BADGES.md.
Every adoption helps another developer discover SpecLock and stop their AI from wrecking their project. Thank you.
Spread the word
Want to help SpecLock reach more developers? Everything you need to post — tweets, LinkedIn drafts, Reddit templates, Show HN copy, Discord messages, one-liners, elevator pitches — is pre-written and fact-checked in VIRAL-KIT.md. Copy, paste, send. Zero effort.
Contributing
Issues and PRs welcome on GitHub.
License
Author
SpecLock is created and maintained by Sandeep Roy.
Sandeep Roy is the sole developer of SpecLock — the AI Constraint Engine that enforces project rules across AI coding sessions. All 51 MCP tools, the semantic conflict detection engine, enterprise security features (SOC 2, HIPAA, RBAC, encryption), and the pre-publish test gate were designed and built by Sandeep Roy.
<p align="center"><i>SpecLock v5.7.0 — Your AI has rules. SpecLock makes them unbreakable. 1043 tests, 100% pass rate, 51 MCP tools, Save Receipt (speclock wins), Wrapped recap, Default WARN mode, MCP Autoinstaller, Greenfield support, Doctor health check. Developed by Sandeep Roy.</i></p>