AGENTS.md

Auto-synced from SpecLock. Run speclock sync --format agents to update.

Project Goal

QualityLens — Jewelry manufacturer QC manual management and AI checklist generation system for Sky Gold & Diamonds Ltd. Stack: Node.js/Express + React/Vite/Tailwind + Railway PostgreSQL + Gemini AI. Monorepo /server + /client. GitHub: sgroy10/qualitylens. Railway auto-deploy.

Constraints

The following rules are non-negotiable. Any AI agent working on this codebase MUST respect them:

• NEVER VIOLATE: Always call speclock_session_briefing at start of session and speclock_session_summary before ending.
• NEVER VIOLATE: The /api/refine endpoint response must NOT exceed 5MB total JSON size. If GLB is larger than 3MB after decimation, return file URLs via /api/files/{filename} instead of base64. The browser WILL fail on 20MB+ JSON responses — this was proven when 16MB GLB caused "Failed to fetch".
• NEVER VIOLATE: Each Hitem3D run costs ~$2 USD. NEVER deploy untested code that touches the pipeline. Test every API endpoint with curl BEFORE asking user to test. Verify response sizes, status codes, and content. The user's time and money are at stake — treat every deploy as production.
• NEVER VIOLATE: Hitem3D settings: model=hitem3dv2.0, resolution=1536pro, face=2000000, request_type=1 (geometry only), format=2 (GLB). Submit+poll architecture — POST /api/generate-3d/submit returns task_id, GET /api/generate-3d/poll/{task_id} polls status. 15 min max poll. These settings are PROVEN WORKING — do not change.
• NEVER VIOLATE: NEVER make multiple changes at once. When fixing a bug, fix ONLY that one thing. Do not refactor, do not "improve" unrelated code, do not touch working prompts. Test the fix before deploying. One commit per fix.
• NEVER VIOLATE: Blender refine.py must NOT use voxel_remesh() or subdivide() — these destroy prong tips and stone seat detail. Hitem3D 2M face output has enough detail. Blender only does: scale to mm → light cleanup (remove doubles, fix normals) → sharpen edges → weighted normals → decimate to 100K faces → export STL + GLB.
• NEVER VIOLATE: Wax views must show OPEN THROUGH-HOLES at every stone position — not closed cups. You must see background through each hole. This is production jewelry CAD standard. The sketch prompt must ask for drilled through-holes, gold render must preserve them, wax must clone them exactly.
• NEVER VIOLATE: JewelCraft Grounding Pattern is MANDATORY. Pipeline: Photo → Pencil Sketch (same angle, through-holes not cups) → Gold Render (from sketch, holes preserved) → Wax Views (from gold render, exact material clone). Each stage feeds PREVIOUS stage's output image. NEVER send original photo to Hitem3D. NEVER skip grounding. NEVER fallback to original image.
• NEVER VIOLATE: Memory system: per-project auto-saved memory (goal, decisions, constraints, context). Stored in PostgreSQL project_memory table. Loaded into system prompt at every conversation turn. User can view/edit in Memory panel. Inspired by Claude memory + OpenClaw bootstrap injection.
• NEVER VIOLATE: SpecLock constraint engine MUST be baked into the codebase — not an external MCP call. Port the core semantics.js logic into the v3 codebase. Auto-detect constraints from conversation, enforce on every generation.
• NEVER VIOLATE: Built-in database for user apps: Railway PostgreSQL with schema-per-project isolation. User never sees connection strings or SQL. AI auto-provisions tables. Free tier: 1 project, 100MB.
• NEVER VIOLATE: VibeLock v3 is a CLEAN BUILD — zero bolt.diy code. Fresh Next.js 15, fresh components, fresh architecture. No copying from the bolt.diy fork. The v3 branch starts empty.
• NEVER VIOLATE: Railway environment variables are already set: DATABASE_URL (Railway PostgreSQL internal), DEEPSEEK_API_KEY, BETTER_AUTH_SECRET, BETTER_AUTH_URL, NEXT_PUBLIC_APP_URL, PORT=5173, NODE_ENV=production, DEFAULT_NUM_CTX=32768. OpenRouter API key is set via OPEN_ROUTER_API_KEY. Add new env vars via Railway GraphQL API or CLI: railway variables set KEY=VALUE.
• NEVER VIOLATE: DEPLOY PIPELINE: Code lives in github.com/sgroy10/vibelock branch v3. Railway project is "captivating-tranquility" (ID: ced04e82-b903-458d-9351-ac5944054e92), service ID: 439001ce-1854-454f-8b05-842fa925963f, environment ID: c2cb15c3-9a96-4854-a65c-c3aa0c3ee253. GitHub repo trigger IS connected — git push to the configured branch auto-deploys. Domain: www.vibelock.in. Railway CLI is installed and authenticated as sgroy10@gmail.com. To redeploy from git: use GraphQL mutation serviceInstanceRedeploy. To check deploy status: query deployments via GraphQL. NEVER waste time polling curl — check deploy status via API.
• NEVER VIOLATE: vibelock.in is the LIVE production domain, pointing to Railway project "captivating-tranquility". It runs the main branch (Remix/bolt.diy fork codebase). When anyone asks about vibelock.in, this is the codebase — NOT the v2 Next.js branch.
• NEVER VIOLATE: Auto-deploy pipeline: push to git → Railway auto-deploys → URL works. No manual railway up commands. Clean CI/CD from day one.
• NEVER VIOLATE: UI must be Apple-level polished — every pixel matters. Hermes brand colors (orange-black), subtle animations, beautiful typography, perfect spacing. First impressions are critical. No ugly scaffolds, no default gray UIs. Think Lovable/Orchid level branding but with our own identity.
• NEVER VIOLATE: ZERO bolt.diy code — this is a clean-room build. No copy-pasting from the fork. Fresh architecture, fresh components, fresh code. We learned our lesson from 10 hours of debugging someone else's mess.
• NEVER VIOLATE: Non-technical users must NEVER need to configure a database manually. Storage must work out of the box with zero configuration.
• NEVER VIOLATE: Preview experience must match or exceed Lovable/Bolt — responsive preview frames (mobile/tablet/desktop), new-tab preview, fast refresh, and eventually shareable preview links. The sandbox must feel polished and professional.
• NEVER VIOLATE: Rola (robotics layer) must NOT be rushed into production before the core platform (app creation + SpecLock + multilingual + design quality) is rock solid. Stage 4 per vision timeline.
• NEVER VIOLATE: Never expose SpecLock complexity to normal users — its power should be FELT (safety, continuity, nothing breaks) more than explained. No jargon, no constraint IDs, no JSON. Just trust.
• NEVER VIOLATE: VibeLock is NOT a Bolt clone — we are constraint-first, multilingual, and robotics-capable. Every product decision must answer: "Does this move VibeLock closer to becoming the trusted platform for multilingual natural-language creation of apps, agents, devices, and robot behaviors?"
• NEVER VIOLATE: Multilingual is NOT just translation — the AI must understand cultural context, respond in the user's language naturally, generate UI labels in the user's language, and make non-English speakers feel first-class. Support Gujarati, Hindi, Spanish, English at minimum, with universal language detection for any language.
• NEVER VIOLATE: SpecLock MUST be automatic and invisible to non-technical users — constraints detected from natural conversation, locked silently, protection felt but not explained. Power users can see the constraint dashboard. No manual setup required.
• NEVER VIOLATE: Every generated app MUST look beautiful by default — modern typography, gradient accents, micro-interactions, proper spacing, responsive design. A todo app must have a stunning landing page. No ugly scaffolds. Design quality is a core differentiator.
• NEVER VIOLATE: ZERO bolt.diy branding anywhere — no "bolt" in user-facing UI, page titles, meta tags, social previews, or marketing. Internal code references (CSS variables, artifact tags) must be migrated to vibelock namespace.
• NEVER VIOLATE: Never commit code changes without bumping the version number. Every code change that touches src/ files requires a patch version bump before commit.
• NEVER VIOLATE: Never push code to git without completing the full release checklist: (1) bump version in ALL 7 files (package.json, http-server.js, server.js, compliance.js, cli/index.js, dashboard/index.html x2), (2) npm publish, (3) git commit, (4) git push, (5) git tag vX.Y.Z, (6) git push origin tag, (7) railway up, (8) curl health to verify version. All 8 steps are mandatory — skipping any step is a violation.
• NEVER VIOLATE: Never modify authentication files without security review
• NEVER VIOLATE: No breaking changes to public API

Decisions

• QualityLens uses Gemini API (key: set as GEMINI_API_KEY on Railway) instead of Anthropic. All AI features (chat, vision captioning, order parsing, checklist generation) use @google/generative-ai SDK with gemini-2.5-flash model. No Anthropic SDK.
• The ONLY remaining bug is /api/refine response too large for browser. The fix is ONLY: reduce decimation target OR return file URLs. Do NOT touch grounding code, prompts, frontend grounding logic, or Hitem3D code to fix this. Isolate the fix to refine endpoint response handling ONLY.
• Grounding pipeline prompts (sketch, gold, wax) are PROVEN WORKING as of commit fa36c95. Sketch asks for through-holes referencing Rhino/Matrix CAD. Gold preserves holes exactly. Wax is exact material clone. These prompts produced perfect results — do not modify without testing first.
• ARCHITECTURE PIVOT: Replace WebContainer (browser-based WASM) with Cloudflare Containers for code execution. WebContainer has unreliable file writing — files generated by AI streaming don't persist to the virtual filesystem. Cloudflare Containers provide real Linux filesystem at ~$20/mo for 1,000 users. Cloudflare account: sgroy10@gmail.com, Account ID: 3e8eb36d3c9062ca1df6523a9cd0011f. Wrangler CLI authenticated. Also rebuild workspace UI to match Lovable quality — clean typography, proper spacing, professional layout.
• File operation format: structured JSON operations (create/update/delete/shell), NOT XML tags. Parsed from AI streaming output. Inspired by OpenClaw's structured patch format.
• Tech stack v3: Next.js 15 (App Router, standalone output), React 19, Tailwind v4, Framer Motion, Zustand, @webcontainer/api, Vercel AI SDK + Gemini Flash via OpenRouter, Prisma + Railway PostgreSQL, better-auth, xterm.js, CodeMirror 6 (dev mode only), lucide-react icons.
• Branch strategy: main = current live bolt.diy fork (keep running). v3 = clean build. When v3 is ready, switch Railway repo trigger from main to v3 (or merge v3 to main).
• LLM: Gemini 2.5 Flash via OpenRouter. Cheapest good-quality coding LLM. Already configured. Budget: $50/month for API calls.
• VibeLock brand is LIGHT theme inspired by Hermes: warm cream/orange backgrounds (#FFF8F0, #FFF1E6), dark text (#1A1A1A, #2D2D2D), orange accents (#FF6B2C). NOT dark theme. Think Hermes.com — luxurious, warm, readable. Auth forms must be modern and beautiful, not basic HTML.
• Build sequentially: (1) Project scaffold + Railway auto-deploy pipeline, (2) Auth + database from day 1, (3) Home page with stunning UI, (4) Chat + AI streaming, (5) WebContainer sandbox + preview, (6) Terminal, (7) SpecLock integration, (8) Multilingual. No skipping steps.

Working with this project

• Before making changes, check if they conflict with the constraints above
• If a requested change violates a constraint, inform the user and suggest alternatives
• Run speclock check "<your planned action>" to verify before proceeding

---

Powered by SpecLock — AI Constraint Engine by Sandeep Roy

---

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 <client> — 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 <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)

1. Go to Settings → Connectors → New MCP server
2. Enter URL: https://speclock-mcp-production.up.railway.app/mcp
3. 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).

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

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: ![Drift Score](https://img.shields.io/badge/drift_score-23%2F100-brightgreen.svg)

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:

[![Protected by SpecLock](https://img.shields.io/badge/Protected_by-SpecLock-FF6B2C?style=flat&logo=lock)](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

MIT

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.

• GitHub: @sgroy10
• npm: speclock

---