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 CHANGED
@@ -25,7 +25,41 @@
25
25
 
26
26
  ---
27
27
 
28
- > **New in v5.5:** `npx speclock protect` — zero-config Guardian Mode. Reads your existing `.cursorrules`, `CLAUDE.md`, `AGENTS.md`, extracts enforceable constraints, installs a pre-commit hook. One command. Your rules are now enforced, not just suggested. Also: ALWAYS/MUST pattern enforcement catches "switch from TypeScript to JavaScript" and "skip input validation."
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: ![Drift Score](https://img.shields.io/badge/drift_score-23%2F100-brightgreen.svg)
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** | **976** | **100%** | **19 suites, 15+ domains** |
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.2. Zero false positives. Zero missed violations. 15.7ms per check.
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: ![Drift Score](https://img.shields.io/badge/drift_score-23%2F100-brightgreen.svg)
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.2 — Your AI has rules. SpecLock makes them unbreakable. 991 tests, 100% pass rate, 51 MCP tools, Zero-config Guardian Mode, Universal Rules Sync, AI Patch Firewall, Drift Score. Developed by Sandeep Roy.</i></p>
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>