speclock 5.5.3 → 5.5.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +264 -336
- package/package.json +217 -1
- package/src/cli/index.js +858 -39
- package/src/core/auth.js +8 -0
- package/src/core/compliance.js +1 -1
- package/src/core/enforcer.js +7 -1
- package/src/core/guardian.js +78 -5
- package/src/core/hooks.js +5 -2
- package/src/core/lock-author.js +8 -0
- package/src/core/mcp-install.js +484 -0
- package/src/core/telemetry.js +685 -114
- package/src/dashboard/index.html +2 -2
- package/src/mcp/http-server.js +2 -2
- package/src/mcp/server.js +1 -1
- package/src/templates/rule-packs/fastapi.md +22 -0
- package/src/templates/rule-packs/nextjs.md +22 -0
- package/src/templates/rule-packs/node.md +22 -0
- package/src/templates/rule-packs/python.md +22 -0
- package/src/templates/rule-packs/rails.md +22 -0
- package/src/templates/rule-packs/react.md +22 -0
package/README.md
CHANGED
|
@@ -25,7 +25,41 @@
|
|
|
25
25
|
|
|
26
26
|
---
|
|
27
27
|
|
|
28
|
-
|
|
28
|
+
## Quick Start
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
npx speclock protect # Install in your project (creates CLAUDE.md if missing)
|
|
32
|
+
speclock mcp install claude-code # Wire up MCP for Claude Code (or cursor, windsurf, cline, codex)
|
|
33
|
+
speclock doctor # Verify everything is set up correctly
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
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`.
|
|
37
|
+
|
|
38
|
+
## What's New in v5.5.4
|
|
39
|
+
|
|
40
|
+
- **Default WARN mode** — no more false-positive blocks. Loud warnings instead. Opt in to strict with `--strict` or `SPECLOCK_STRICT=1`.
|
|
41
|
+
- **`speclock mcp install <client>`** — autoinstaller for Claude Code, Cursor, Windsurf, Cline, Codex. No more hand-editing JSON.
|
|
42
|
+
- **Greenfield support** — `speclock protect` in fresh projects auto-creates CLAUDE.md with safe defaults.
|
|
43
|
+
- **`speclock doctor`** — health check verifying installation, git hook, rule files, and MCP integration. Prints exact fix commands for any issues.
|
|
44
|
+
|
|
45
|
+
## What is SpecLock?
|
|
46
|
+
|
|
47
|
+
**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.
|
|
48
|
+
|
|
49
|
+
## Commands Reference
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
speclock protect # Install pre-commit hook + extract locks from rule files
|
|
53
|
+
speclock protect --strict # Hard enforcement mode (blocks violations)
|
|
54
|
+
speclock doctor # Health check — verifies install, hooks, rules, MCP
|
|
55
|
+
speclock mcp install <client> # Wire up MCP server (claude-code, cursor, windsurf, cline, codex)
|
|
56
|
+
speclock check "action description" # Test if an action would conflict with locks
|
|
57
|
+
speclock add-lock "rule" # Add a new lock
|
|
58
|
+
speclock list-locks # Show all locks
|
|
59
|
+
speclock enforce hard|advisory # Change enforcement mode
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Full command reference: `npx speclock help`
|
|
29
63
|
|
|
30
64
|
---
|
|
31
65
|
|
|
@@ -43,25 +77,6 @@ AI: ⚠️ BLOCKED — violates lock "Never touch the auth system"
|
|
|
43
77
|
```
|
|
44
78
|
|
|
45
79
|
**100/100 on Claude's independent test suite. 991 tests across 19 suites. 0 false positives. 15.7ms per check.**
|
|
46
|
-
**Zero-config Guardian Mode, Universal Rules Sync, AI Patch Firewall, Drift Score, Spec Compiler, Code Graph.**
|
|
47
|
-
|
|
48
|
-
---
|
|
49
|
-
|
|
50
|
-
## Install
|
|
51
|
-
|
|
52
|
-
```bash
|
|
53
|
-
npx speclock setup --goal "Build my app"
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
That's it. One command. Works everywhere — Bolt.new, Claude Code, Cursor, Lovable, Windsurf, Cline, Aider.
|
|
57
|
-
|
|
58
|
-
### Already have `.cursorrules`, `CLAUDE.md`, or `AGENTS.md`?
|
|
59
|
-
|
|
60
|
-
```bash
|
|
61
|
-
npx speclock protect
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
Zero flags. Reads your existing rule files, extracts enforceable constraints, installs a pre-commit hook, and syncs rules to every AI tool. **Your rules are now enforced, not just suggested.**
|
|
65
80
|
|
|
66
81
|
## The Problem
|
|
67
82
|
|
|
@@ -143,153 +158,6 @@ Same config — add to `.cursor/mcp.json` or equivalent.
|
|
|
143
158
|
|
|
144
159
|
---
|
|
145
160
|
|
|
146
|
-
## Universal Rules Sync (v5.3)
|
|
147
|
-
|
|
148
|
-
One command syncs your SpecLock constraints to every AI coding tool:
|
|
149
|
-
|
|
150
|
-
```bash
|
|
151
|
-
speclock sync --all
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
```
|
|
155
|
-
SpecLock Sync Complete
|
|
156
|
-
✓ Cursor → .cursor/rules/speclock.mdc
|
|
157
|
-
✓ Claude Code → CLAUDE.md
|
|
158
|
-
✓ AGENTS.md → AGENTS.md (Linux Foundation standard)
|
|
159
|
-
✓ Windsurf → .windsurf/rules/speclock.md
|
|
160
|
-
✓ GitHub Copilot → .github/copilot-instructions.md
|
|
161
|
-
✓ Gemini → GEMINI.md
|
|
162
|
-
✓ Aider → .aider.conf.yml
|
|
163
|
-
|
|
164
|
-
7 file(s) synced. Your AI tools will now see SpecLock constraints.
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
Stop maintaining 3 separate rules files. Define constraints once in SpecLock, sync everywhere.
|
|
168
|
-
|
|
169
|
-
```bash
|
|
170
|
-
speclock sync --format cursor # Sync to Cursor only
|
|
171
|
-
speclock sync --preview claude # Preview without writing
|
|
172
|
-
speclock sync --list # Show all supported formats
|
|
173
|
-
```
|
|
174
|
-
|
|
175
|
-
---
|
|
176
|
-
|
|
177
|
-
## Incident Replay (v5.3)
|
|
178
|
-
|
|
179
|
-
Flight recorder for your AI coding sessions. See exactly what happened:
|
|
180
|
-
|
|
181
|
-
```bash
|
|
182
|
-
speclock replay
|
|
183
|
-
|
|
184
|
-
Session: ses_a1b2c3 (claude-code, 47 min)
|
|
185
|
-
────────────────────────────────────────────
|
|
186
|
-
14:02 [ALLOW] Create user profile component
|
|
187
|
-
14:08 [ALLOW] Add form validation
|
|
188
|
-
14:15 [WARN] Simplify authentication flow
|
|
189
|
-
→ matched lock: "Never modify auth"
|
|
190
|
-
14:23 [BLOCK] Clean up old user records
|
|
191
|
-
→ euphemism detected: "clean up" = deletion
|
|
192
|
-
14:31 [ALLOW] Update landing page hero section
|
|
193
|
-
|
|
194
|
-
Score: 5 events | 3 allowed | 1 warned | 1 BLOCKED
|
|
195
|
-
```
|
|
196
|
-
|
|
197
|
-
```bash
|
|
198
|
-
speclock replay --list # List available sessions
|
|
199
|
-
speclock replay --session <id> # Replay specific session
|
|
200
|
-
```
|
|
201
|
-
|
|
202
|
-
---
|
|
203
|
-
|
|
204
|
-
## Safety Templates (v5.3)
|
|
205
|
-
|
|
206
|
-
Pre-built constraint packs for common scenarios:
|
|
207
|
-
|
|
208
|
-
```bash
|
|
209
|
-
speclock template apply safe-defaults # 5 locks — "Vibe Coding Seatbelt"
|
|
210
|
-
speclock template apply solo-founder # 3 locks — auth, payments, data
|
|
211
|
-
speclock template apply hipaa # 8 locks — HIPAA healthcare
|
|
212
|
-
speclock template apply api-stability # 6 locks — API contract protection
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
**Safe Defaults** prevents the 5 most common AI disasters:
|
|
216
|
-
1. Database deletion
|
|
217
|
-
2. Auth removal
|
|
218
|
-
3. Secret exposure
|
|
219
|
-
4. Error handling removal
|
|
220
|
-
5. Logging disablement
|
|
221
|
-
|
|
222
|
-
One command. Instant protection. `npx speclock setup --template safe-defaults`
|
|
223
|
-
|
|
224
|
-
---
|
|
225
|
-
|
|
226
|
-
## Drift Score (v5.4)
|
|
227
|
-
|
|
228
|
-
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*.
|
|
229
|
-
|
|
230
|
-
```bash
|
|
231
|
-
$ speclock drift
|
|
232
|
-
|
|
233
|
-
Drift Score: 23/100 (B) — minor drift
|
|
234
|
-
Trend: improving | Period: 30 days | Active locks: 8
|
|
235
|
-
|
|
236
|
-
Signal Breakdown:
|
|
237
|
-
Violations: 6/30 (4 violations in 12 checks)
|
|
238
|
-
Overrides: 5/20 (1 override)
|
|
239
|
-
Reverts: 3/15 (1 revert detected)
|
|
240
|
-
Lock churn: 0/15 (0 removed, 3 added)
|
|
241
|
-
Goal stability: 0/10 (1 goal change)
|
|
242
|
-
Session gaps: 9/10 (3/5 unsummarized)
|
|
243
|
-
|
|
244
|
-
README badge: 
|
|
245
|
-
```
|
|
246
|
-
|
|
247
|
-
Put the badge in your README. Show the world your AI respects your architecture.
|
|
248
|
-
|
|
249
|
-
---
|
|
250
|
-
|
|
251
|
-
## Lock Coverage Audit (v5.4)
|
|
252
|
-
|
|
253
|
-
SpecLock scans your codebase and tells you what's **unprotected**:
|
|
254
|
-
|
|
255
|
-
```bash
|
|
256
|
-
$ speclock coverage
|
|
257
|
-
|
|
258
|
-
Lock Coverage: 60% (B) — partially protected
|
|
259
|
-
|
|
260
|
-
[COVERED] CRITICAL authentication 2 file(s)
|
|
261
|
-
[EXPOSED] CRITICAL payments 1 file(s)
|
|
262
|
-
[COVERED] CRITICAL secrets 0 file(s)
|
|
263
|
-
[COVERED] HIGH api-routes 2 file(s)
|
|
264
|
-
|
|
265
|
-
Suggested Locks (ready to apply):
|
|
266
|
-
1. [CRITICAL] payments (1 file at risk)
|
|
267
|
-
speclock lock "Never modify payment processing or billing without permission"
|
|
268
|
-
```
|
|
269
|
-
|
|
270
|
-
Like a security scanner, but for AI constraint gaps. Solo founders building fast don't know what they haven't protected — SpecLock tells them.
|
|
271
|
-
|
|
272
|
-
---
|
|
273
|
-
|
|
274
|
-
## Lock Strengthener (v5.4)
|
|
275
|
-
|
|
276
|
-
Your locks might be too vague. SpecLock grades each one and suggests improvements:
|
|
277
|
-
|
|
278
|
-
```bash
|
|
279
|
-
$ speclock strengthen
|
|
280
|
-
|
|
281
|
-
Lock Strength: 72/100 (B) — 3 strong, 1 weak
|
|
282
|
-
|
|
283
|
-
[WEAK ] 45/100 (D) "don't touch auth"
|
|
284
|
-
Issue: Too vague — short locks miss edge cases
|
|
285
|
-
Issue: No specific scope
|
|
286
|
-
Suggested: "Never modify, refactor, or delete auth..."
|
|
287
|
-
|
|
288
|
-
[STRONG] 90/100 (A) "Never expose API keys in client-side code, logs, or error messages"
|
|
289
|
-
```
|
|
290
|
-
|
|
291
|
-
---
|
|
292
|
-
|
|
293
161
|
## Semantic Engine
|
|
294
162
|
|
|
295
163
|
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).
|
|
@@ -403,172 +271,6 @@ Import and export policies between projects. Share constraint templates across y
|
|
|
403
271
|
|
|
404
272
|
---
|
|
405
273
|
|
|
406
|
-
## Spec Compiler (v5.0)
|
|
407
|
-
|
|
408
|
-
Paste a PRD, README, or architecture doc — SpecLock extracts all constraints automatically:
|
|
409
|
-
|
|
410
|
-
```
|
|
411
|
-
Input: "We're building a fintech app. Use React and FastAPI.
|
|
412
|
-
Never touch the auth module. Response time must stay
|
|
413
|
-
under 200ms. Payments go through Stripe."
|
|
414
|
-
|
|
415
|
-
Output: 2 text locks:
|
|
416
|
-
- "Never touch the auth module"
|
|
417
|
-
- "Payments go through Stripe — don't change provider"
|
|
418
|
-
1 typed lock:
|
|
419
|
-
- response_time_ms <= 200 (numerical)
|
|
420
|
-
2 decisions:
|
|
421
|
-
- "Use React for frontend"
|
|
422
|
-
- "Use FastAPI for backend"
|
|
423
|
-
```
|
|
424
|
-
|
|
425
|
-
Uses Gemini Flash by default ($0.01 per 1000 compilations). No API key needed for core SpecLock — only the compiler uses LLM. Falls back gracefully if no key is set.
|
|
426
|
-
|
|
427
|
-
---
|
|
428
|
-
|
|
429
|
-
## Code Graph (v5.0)
|
|
430
|
-
|
|
431
|
-
Live dependency graph of your codebase. Parses JS/TS/Python imports.
|
|
432
|
-
|
|
433
|
-
```
|
|
434
|
-
$ speclock blast-radius src/core/memory.js
|
|
435
|
-
|
|
436
|
-
Direct Dependents: 8 files
|
|
437
|
-
Transitive Impact: 14 files (33% of codebase)
|
|
438
|
-
Max Depth: 4 hops
|
|
439
|
-
```
|
|
440
|
-
|
|
441
|
-
**Lock-to-file mapping:** Lock "Never modify auth" → automatically maps to `src/api/auth.js`, `src/middleware/auth.js`, `src/utils/jwt.js`. No configuration needed.
|
|
442
|
-
|
|
443
|
-
**Module detection:** Groups files into logical modules, tracks inter-module dependencies, identifies critical paths.
|
|
444
|
-
|
|
445
|
-
---
|
|
446
|
-
|
|
447
|
-
## Typed Constraints (v5.0)
|
|
448
|
-
|
|
449
|
-
Real-time value and state checking for autonomous systems, IoT, robotics:
|
|
450
|
-
|
|
451
|
-
```javascript
|
|
452
|
-
// Numerical: speed must be <= 2.0 m/s
|
|
453
|
-
{ constraintType: "numerical", metric: "speed_mps", operator: "<=", value: 2.0 }
|
|
454
|
-
|
|
455
|
-
// Range: temperature must stay between 20-25°C
|
|
456
|
-
{ constraintType: "range", metric: "temperature_c", min: 20, max: 25 }
|
|
457
|
-
|
|
458
|
-
// State: never go from armed → disarmed without approval
|
|
459
|
-
{ constraintType: "state", metric: "system_mode", forbidden: [{ from: "armed", to: "disarmed" }] }
|
|
460
|
-
|
|
461
|
-
// Temporal: heartbeat must occur every 30 seconds
|
|
462
|
-
{ constraintType: "temporal", metric: "heartbeat_s", operator: "<=", value: 30 }
|
|
463
|
-
```
|
|
464
|
-
|
|
465
|
-
---
|
|
466
|
-
|
|
467
|
-
## Python SDK & ROS2 (v5.0)
|
|
468
|
-
|
|
469
|
-
```bash
|
|
470
|
-
pip install speclock-sdk
|
|
471
|
-
```
|
|
472
|
-
|
|
473
|
-
```python
|
|
474
|
-
from speclock import SpecLock
|
|
475
|
-
|
|
476
|
-
sl = SpecLock(project_root=".")
|
|
477
|
-
|
|
478
|
-
# Check text constraints (semantic conflict detection)
|
|
479
|
-
result = sl.check_text("Switch database to MongoDB")
|
|
480
|
-
# → { has_conflict: True, conflicting_locks: [...] }
|
|
481
|
-
|
|
482
|
-
# Check typed constraints (numerical/range/state/temporal)
|
|
483
|
-
result = sl.check_typed(metric="speed_mps", value=3.5)
|
|
484
|
-
# → violation: speed exceeds 2.0 m/s limit
|
|
485
|
-
|
|
486
|
-
# Combined check (text + typed in one call)
|
|
487
|
-
result = sl.check(action="Increase speed", speed_mps=3.5)
|
|
488
|
-
```
|
|
489
|
-
|
|
490
|
-
Uses the same `.speclock/brain.json` as the Node.js MCP server — constraints stay in sync across all environments.
|
|
491
|
-
|
|
492
|
-
**ROS2 Guardian Node:** Real-time constraint enforcement for robots and autonomous systems.
|
|
493
|
-
|
|
494
|
-
```yaml
|
|
495
|
-
# config/constraints.yaml
|
|
496
|
-
constraints:
|
|
497
|
-
- type: range
|
|
498
|
-
metric: joint_position_rad
|
|
499
|
-
min: -3.14
|
|
500
|
-
max: 3.14
|
|
501
|
-
- type: numerical
|
|
502
|
-
metric: velocity_mps
|
|
503
|
-
operator: "<="
|
|
504
|
-
value: 2.0
|
|
505
|
-
- type: state
|
|
506
|
-
metric: system_mode
|
|
507
|
-
forbidden:
|
|
508
|
-
- from: emergency_stop
|
|
509
|
-
to: autonomous
|
|
510
|
-
```
|
|
511
|
-
|
|
512
|
-
- Subscribes to `/joint_states`, `/cmd_vel`, `/speclock/state_transition`
|
|
513
|
-
- Publishes violations to `/speclock/violations`
|
|
514
|
-
- Triggers emergency stop via `/speclock/emergency_stop`
|
|
515
|
-
- Checks constraints on every incoming ROS2 message at configurable rate
|
|
516
|
-
|
|
517
|
-
---
|
|
518
|
-
|
|
519
|
-
## Patch Gateway (v5.1)
|
|
520
|
-
|
|
521
|
-
One API call gates every change. Takes a description + file list, returns ALLOW/WARN/BLOCK:
|
|
522
|
-
|
|
523
|
-
```
|
|
524
|
-
speclock_review_patch({
|
|
525
|
-
description: "Add social login to auth page",
|
|
526
|
-
files: ["src/auth/login.js"]
|
|
527
|
-
})
|
|
528
|
-
|
|
529
|
-
→ { verdict: "BLOCK", riskScore: 85,
|
|
530
|
-
reasons: [{ type: "semantic_conflict", lock: "Never modify auth" }],
|
|
531
|
-
blastRadius: { impactPercent: 28.3 },
|
|
532
|
-
summary: "BLOCKED. 1 constraint conflict. 12 files affected." }
|
|
533
|
-
```
|
|
534
|
-
|
|
535
|
-
Combines semantic conflict detection + lock-to-file mapping + blast radius + typed constraint awareness into a single risk score (0-100).
|
|
536
|
-
|
|
537
|
-
---
|
|
538
|
-
|
|
539
|
-
## AI Patch Firewall (v5.2)
|
|
540
|
-
|
|
541
|
-
Reviews actual diffs, not just descriptions. Catches things intent review misses:
|
|
542
|
-
|
|
543
|
-
```
|
|
544
|
-
POST /api/v2/gateway/review-diff
|
|
545
|
-
{
|
|
546
|
-
"description": "Remove password column",
|
|
547
|
-
"diff": "diff --git a/migrations/001.sql ..."
|
|
548
|
-
}
|
|
549
|
-
|
|
550
|
-
→ { verdict: "BLOCK",
|
|
551
|
-
reviewMode: "unified",
|
|
552
|
-
intentVerdict: "ALLOW", ← description alone looks safe
|
|
553
|
-
diffVerdict: "BLOCK", ← diff reveals destructive schema change
|
|
554
|
-
signals: {
|
|
555
|
-
schemaChange: { score: 12, isDestructive: true },
|
|
556
|
-
interfaceBreak: { score: 10 },
|
|
557
|
-
protectedSymbolEdit: { score: 8 },
|
|
558
|
-
dependencyDrift: { score: 5 },
|
|
559
|
-
publicApiImpact: { score: 0 }
|
|
560
|
-
},
|
|
561
|
-
recommendation: { action: "require_approval" } }
|
|
562
|
-
```
|
|
563
|
-
|
|
564
|
-
**Signal detection:** Interface breaks (removed/changed exports), protected symbol edits in locked zones, dependency drift (critical package add/remove), schema/migration destructive changes, public API route changes.
|
|
565
|
-
|
|
566
|
-
**Hard escalation rules:** Auto-BLOCK on destructive schema changes, removed API routes, protected symbol edits, or multiple critical findings — regardless of score.
|
|
567
|
-
|
|
568
|
-
**Unified review:** Merges intent (35%) + diff (65%), takes the stronger verdict. Falls back to intent-only when no diff is available.
|
|
569
|
-
|
|
570
|
-
---
|
|
571
|
-
|
|
572
274
|
## REST API v2
|
|
573
275
|
|
|
574
276
|
Real-time constraint checking, patch review, and autonomous systems:
|
|
@@ -884,9 +586,9 @@ The AI opens the file and sees:
|
|
|
884
586
|
| REST API v2 | 9 | 100% | Typed constraint endpoints, SSE |
|
|
885
587
|
| PII/Export Detection | 8 | 100% | SSN, email export, data access violations |
|
|
886
588
|
| Guardian (Protect) | 47 | 100% | Zero-config rule file extraction |
|
|
887
|
-
| **Total** | **
|
|
589
|
+
| **Total** | **991** | **100%** | **19 suites, 15+ domains** |
|
|
888
590
|
|
|
889
|
-
**External validation:** Claude's independent 7-suite adversarial test battery — **100/100 (100%)** on v5.5.
|
|
591
|
+
**External validation:** Claude's independent 7-suite adversarial test battery — **100/100 (100%)** on v5.5.4. Zero false positives. Zero missed violations. 15.7ms per check.
|
|
890
592
|
|
|
891
593
|
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.
|
|
892
594
|
|
|
@@ -912,6 +614,232 @@ Tested across: fintech, e-commerce, IoT, healthcare, SaaS, gaming, biotech, aero
|
|
|
912
614
|
|
|
913
615
|
---
|
|
914
616
|
|
|
617
|
+
## Changelog
|
|
618
|
+
|
|
619
|
+
Prior-version feature tours. The Quick Start and What's New sections above cover v5.5.4 — this section preserves details on features shipped in v5.0–v5.4.
|
|
620
|
+
|
|
621
|
+
### v5.4 — Drift Score, Lock Coverage, Lock Strengthener
|
|
622
|
+
|
|
623
|
+
**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*.
|
|
624
|
+
|
|
625
|
+
```bash
|
|
626
|
+
$ speclock drift
|
|
627
|
+
|
|
628
|
+
Drift Score: 23/100 (B) — minor drift
|
|
629
|
+
Trend: improving | Period: 30 days | Active locks: 8
|
|
630
|
+
|
|
631
|
+
Signal Breakdown:
|
|
632
|
+
Violations: 6/30 (4 violations in 12 checks)
|
|
633
|
+
Overrides: 5/20 (1 override)
|
|
634
|
+
Reverts: 3/15 (1 revert detected)
|
|
635
|
+
Lock churn: 0/15 (0 removed, 3 added)
|
|
636
|
+
Goal stability: 0/10 (1 goal change)
|
|
637
|
+
Session gaps: 9/10 (3/5 unsummarized)
|
|
638
|
+
|
|
639
|
+
README badge: 
|
|
640
|
+
```
|
|
641
|
+
|
|
642
|
+
**Lock Coverage Audit.** SpecLock scans your codebase and tells you what's **unprotected**:
|
|
643
|
+
|
|
644
|
+
```bash
|
|
645
|
+
$ speclock coverage
|
|
646
|
+
|
|
647
|
+
Lock Coverage: 60% (B) — partially protected
|
|
648
|
+
|
|
649
|
+
[COVERED] CRITICAL authentication 2 file(s)
|
|
650
|
+
[EXPOSED] CRITICAL payments 1 file(s)
|
|
651
|
+
[COVERED] CRITICAL secrets 0 file(s)
|
|
652
|
+
[COVERED] HIGH api-routes 2 file(s)
|
|
653
|
+
|
|
654
|
+
Suggested Locks (ready to apply):
|
|
655
|
+
1. [CRITICAL] payments (1 file at risk)
|
|
656
|
+
speclock lock "Never modify payment processing or billing without permission"
|
|
657
|
+
```
|
|
658
|
+
|
|
659
|
+
Like a security scanner, but for AI constraint gaps.
|
|
660
|
+
|
|
661
|
+
**Lock Strengthener.** Your locks might be too vague. SpecLock grades each one and suggests improvements:
|
|
662
|
+
|
|
663
|
+
```bash
|
|
664
|
+
$ speclock strengthen
|
|
665
|
+
|
|
666
|
+
Lock Strength: 72/100 (B) — 3 strong, 1 weak
|
|
667
|
+
|
|
668
|
+
[WEAK ] 45/100 (D) "don't touch auth"
|
|
669
|
+
Issue: Too vague — short locks miss edge cases
|
|
670
|
+
Issue: No specific scope
|
|
671
|
+
Suggested: "Never modify, refactor, or delete auth..."
|
|
672
|
+
|
|
673
|
+
[STRONG] 90/100 (A) "Never expose API keys in client-side code, logs, or error messages"
|
|
674
|
+
```
|
|
675
|
+
|
|
676
|
+
### v5.3 — Universal Rules Sync, Incident Replay, Safety Templates
|
|
677
|
+
|
|
678
|
+
**Universal Rules Sync.** One command syncs your SpecLock constraints to every AI coding tool:
|
|
679
|
+
|
|
680
|
+
```bash
|
|
681
|
+
speclock sync --all
|
|
682
|
+
```
|
|
683
|
+
|
|
684
|
+
```
|
|
685
|
+
SpecLock Sync Complete
|
|
686
|
+
✓ Cursor → .cursor/rules/speclock.mdc
|
|
687
|
+
✓ Claude Code → CLAUDE.md
|
|
688
|
+
✓ AGENTS.md → AGENTS.md (Linux Foundation standard)
|
|
689
|
+
✓ Windsurf → .windsurf/rules/speclock.md
|
|
690
|
+
✓ GitHub Copilot → .github/copilot-instructions.md
|
|
691
|
+
✓ Gemini → GEMINI.md
|
|
692
|
+
✓ Aider → .aider.conf.yml
|
|
693
|
+
|
|
694
|
+
7 file(s) synced.
|
|
695
|
+
```
|
|
696
|
+
|
|
697
|
+
Define constraints once in SpecLock, sync everywhere. `--format cursor` for single format, `--preview` to dry-run, `--list` to see supported formats.
|
|
698
|
+
|
|
699
|
+
**Incident Replay.** Flight recorder for your AI coding sessions:
|
|
700
|
+
|
|
701
|
+
```bash
|
|
702
|
+
speclock replay
|
|
703
|
+
|
|
704
|
+
Session: ses_a1b2c3 (claude-code, 47 min)
|
|
705
|
+
────────────────────────────────────────────
|
|
706
|
+
14:02 [ALLOW] Create user profile component
|
|
707
|
+
14:08 [ALLOW] Add form validation
|
|
708
|
+
14:15 [WARN] Simplify authentication flow
|
|
709
|
+
→ matched lock: "Never modify auth"
|
|
710
|
+
14:23 [BLOCK] Clean up old user records
|
|
711
|
+
→ euphemism detected: "clean up" = deletion
|
|
712
|
+
14:31 [ALLOW] Update landing page hero section
|
|
713
|
+
|
|
714
|
+
Score: 5 events | 3 allowed | 1 warned | 1 BLOCKED
|
|
715
|
+
```
|
|
716
|
+
|
|
717
|
+
`speclock replay --list` lists sessions; `--session <id>` replays a specific one.
|
|
718
|
+
|
|
719
|
+
**Safety Templates.** Pre-built constraint packs:
|
|
720
|
+
|
|
721
|
+
```bash
|
|
722
|
+
speclock template apply safe-defaults # 5 locks — "Vibe Coding Seatbelt"
|
|
723
|
+
speclock template apply solo-founder # 3 locks — auth, payments, data
|
|
724
|
+
speclock template apply hipaa # 8 locks — HIPAA healthcare
|
|
725
|
+
speclock template apply api-stability # 6 locks — API contract protection
|
|
726
|
+
```
|
|
727
|
+
|
|
728
|
+
Safe Defaults prevents the 5 most common AI disasters: database deletion, auth removal, secret exposure, error-handling removal, logging disablement.
|
|
729
|
+
|
|
730
|
+
### v5.2 — AI Patch Firewall
|
|
731
|
+
|
|
732
|
+
Reviews actual diffs, not just descriptions. Catches things intent review misses:
|
|
733
|
+
|
|
734
|
+
```
|
|
735
|
+
POST /api/v2/gateway/review-diff
|
|
736
|
+
{
|
|
737
|
+
"description": "Remove password column",
|
|
738
|
+
"diff": "diff --git a/migrations/001.sql ..."
|
|
739
|
+
}
|
|
740
|
+
|
|
741
|
+
→ { verdict: "BLOCK",
|
|
742
|
+
reviewMode: "unified",
|
|
743
|
+
intentVerdict: "ALLOW", ← description alone looks safe
|
|
744
|
+
diffVerdict: "BLOCK", ← diff reveals destructive schema change
|
|
745
|
+
signals: {
|
|
746
|
+
schemaChange: { score: 12, isDestructive: true },
|
|
747
|
+
interfaceBreak: { score: 10 },
|
|
748
|
+
protectedSymbolEdit: { score: 8 },
|
|
749
|
+
dependencyDrift: { score: 5 },
|
|
750
|
+
publicApiImpact: { score: 0 }
|
|
751
|
+
},
|
|
752
|
+
recommendation: { action: "require_approval" } }
|
|
753
|
+
```
|
|
754
|
+
|
|
755
|
+
**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.
|
|
756
|
+
|
|
757
|
+
### v5.1 — Patch Gateway
|
|
758
|
+
|
|
759
|
+
One API call gates every change. Takes a description + file list, returns ALLOW/WARN/BLOCK:
|
|
760
|
+
|
|
761
|
+
```
|
|
762
|
+
speclock_review_patch({
|
|
763
|
+
description: "Add social login to auth page",
|
|
764
|
+
files: ["src/auth/login.js"]
|
|
765
|
+
})
|
|
766
|
+
|
|
767
|
+
→ { verdict: "BLOCK", riskScore: 85,
|
|
768
|
+
reasons: [{ type: "semantic_conflict", lock: "Never modify auth" }],
|
|
769
|
+
blastRadius: { impactPercent: 28.3 },
|
|
770
|
+
summary: "BLOCKED. 1 constraint conflict. 12 files affected." }
|
|
771
|
+
```
|
|
772
|
+
|
|
773
|
+
Combines semantic conflict detection + lock-to-file mapping + blast radius + typed constraint awareness into a single risk score (0-100).
|
|
774
|
+
|
|
775
|
+
### v5.0 — Spec Compiler, Code Graph, Typed Constraints, Python SDK & ROS2
|
|
776
|
+
|
|
777
|
+
**Spec Compiler.** Paste a PRD, README, or architecture doc — SpecLock extracts all constraints automatically:
|
|
778
|
+
|
|
779
|
+
```
|
|
780
|
+
Input: "We're building a fintech app. Use React and FastAPI.
|
|
781
|
+
Never touch the auth module. Response time must stay
|
|
782
|
+
under 200ms. Payments go through Stripe."
|
|
783
|
+
|
|
784
|
+
Output: 2 text locks:
|
|
785
|
+
- "Never touch the auth module"
|
|
786
|
+
- "Payments go through Stripe — don't change provider"
|
|
787
|
+
1 typed lock:
|
|
788
|
+
- response_time_ms <= 200 (numerical)
|
|
789
|
+
2 decisions:
|
|
790
|
+
- "Use React for frontend"
|
|
791
|
+
- "Use FastAPI for backend"
|
|
792
|
+
```
|
|
793
|
+
|
|
794
|
+
Uses Gemini Flash by default ($0.01 per 1000 compilations).
|
|
795
|
+
|
|
796
|
+
**Code Graph.** Live dependency graph of your codebase. Parses JS/TS/Python imports.
|
|
797
|
+
|
|
798
|
+
```
|
|
799
|
+
$ speclock blast-radius src/core/memory.js
|
|
800
|
+
|
|
801
|
+
Direct Dependents: 8 files
|
|
802
|
+
Transitive Impact: 14 files (33% of codebase)
|
|
803
|
+
Max Depth: 4 hops
|
|
804
|
+
```
|
|
805
|
+
|
|
806
|
+
Lock-to-file mapping auto-maps locks to source files; module detection groups files into logical modules.
|
|
807
|
+
|
|
808
|
+
**Typed Constraints.** Real-time value and state checking for autonomous systems, IoT, robotics:
|
|
809
|
+
|
|
810
|
+
```javascript
|
|
811
|
+
// Numerical: speed must be <= 2.0 m/s
|
|
812
|
+
{ constraintType: "numerical", metric: "speed_mps", operator: "<=", value: 2.0 }
|
|
813
|
+
|
|
814
|
+
// Range: temperature must stay between 20-25°C
|
|
815
|
+
{ constraintType: "range", metric: "temperature_c", min: 20, max: 25 }
|
|
816
|
+
|
|
817
|
+
// State: never go from armed → disarmed without approval
|
|
818
|
+
{ constraintType: "state", metric: "system_mode", forbidden: [{ from: "armed", to: "disarmed" }] }
|
|
819
|
+
|
|
820
|
+
// Temporal: heartbeat must occur every 30 seconds
|
|
821
|
+
{ constraintType: "temporal", metric: "heartbeat_s", operator: "<=", value: 30 }
|
|
822
|
+
```
|
|
823
|
+
|
|
824
|
+
**Python SDK & ROS2.**
|
|
825
|
+
|
|
826
|
+
```bash
|
|
827
|
+
pip install speclock-sdk
|
|
828
|
+
```
|
|
829
|
+
|
|
830
|
+
```python
|
|
831
|
+
from speclock import SpecLock
|
|
832
|
+
|
|
833
|
+
sl = SpecLock(project_root=".")
|
|
834
|
+
result = sl.check_text("Switch database to MongoDB")
|
|
835
|
+
result = sl.check_typed(metric="speed_mps", value=3.5)
|
|
836
|
+
result = sl.check(action="Increase speed", speed_mps=3.5)
|
|
837
|
+
```
|
|
838
|
+
|
|
839
|
+
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`.
|
|
840
|
+
|
|
841
|
+
---
|
|
842
|
+
|
|
915
843
|
## Contributing
|
|
916
844
|
|
|
917
845
|
Issues and PRs welcome on [GitHub](https://github.com/sgroy10/speclock).
|
|
@@ -931,4 +859,4 @@ Sandeep Roy is the sole developer of SpecLock — the AI Constraint Engine that
|
|
|
931
859
|
|
|
932
860
|
---
|
|
933
861
|
|
|
934
|
-
<p align="center"><i>SpecLock v5.5.
|
|
862
|
+
<p align="center"><i>SpecLock v5.5.4 — Your AI has rules. SpecLock makes them unbreakable. 991 tests, 100% pass rate, 51 MCP tools, Default WARN mode, MCP Autoinstaller, Greenfield support, Doctor health check. Developed by Sandeep Roy.</i></p>
|