speclock 2.1.0 → 2.5.0

package/README.md

@@ -50,11 +50,15 @@ No other tool does this. Not Claude's native memory. Not Mem0. Not CLAUDE.md fil
 | Remembers context | Yes | Yes | Manual | **Yes** |
 | **Stops the AI from breaking things** | No | No | No | **Yes — active enforcement** |
 | **Semantic conflict detection** | No | No | No | **Yes — semantic engine v2 (100% detection, 0% false positives)** |
+| **Tamper-proof audit trail** | No | No | No | **Yes — HMAC-SHA256 hash chain** |
+| **Compliance exports** | No | No | No | **Yes — SOC 2, HIPAA, CSV** |
 | Works on Bolt.new | No | No | No | **Yes — npm file-based mode** |
 | Works on Lovable | No | No | No | **Yes — MCP remote** |
 | Structured decisions/locks | No | Tags only | Flat text | **Goals, locks, decisions, changes** |
 | Git-aware (checkpoints, rollback) | No | No | No | **Yes** |
 | Drift detection | No | No | No | **Yes — scans changes against locks** |
+| CI/CD integration | No | No | No | **Yes — GitHub Actions** |
+| **Hard enforcement (block violations)** | No | No | No | **Yes — hard mode blocks above threshold** |
 | Multi-agent timeline | No | No | No | **Yes** |
 | Cross-platform | Claude only | MCP only | Tool-specific | **Universal (MCP + npm)** |
 
@@ -189,10 +193,10 @@ Result:  NO CONFLICT (confidence: 7%)
 | Mode | Platforms | How It Works |
 |------|-----------|--------------|
 | **MCP Remote** | Lovable, bolt.diy, Base44 | Connect via URL — no install needed |
-| **MCP Local** | Claude Code, Cursor, Windsurf, Cline | `npx speclock serve` — 22 tools via MCP |
+| **MCP Local** | Claude Code, Cursor, Windsurf, Cline | `npx speclock serve` — 28 tools via MCP |
 | **npm File-Based** | Bolt.new, Aider, Rocket.new | `npx speclock setup` — AI reads SPECLOCK.md + uses CLI |
 
-## 22 MCP Tools
+## 28 MCP Tools
 
 ### Memory Management
 | Tool | Purpose |
@@ -240,6 +244,20 @@ Result:  NO CONFLICT (confidence: 7%)
 | `speclock_report` | Violation report — blocked change stats |
 | `speclock_audit` | Audit staged files against active locks |
 
+### Enterprise (v2.1)
+| Tool | Purpose |
+|------|---------|
+| `speclock_verify_audit` | Verify HMAC audit chain integrity — tamper detection |
+| `speclock_export_compliance` | Generate SOC 2 / HIPAA / CSV compliance reports |
+
+### Hard Enforcement (v2.5)
+| Tool | Purpose |
+|------|---------|
+| `speclock_set_enforcement` | Set enforcement mode: advisory (warn) or hard (block) |
+| `speclock_override_lock` | Override a lock with justification — logged to audit trail |
+| `speclock_semantic_audit` | Semantic pre-commit: analyze code changes vs locks |
+| `speclock_override_history` | View lock override history for audit review |
+
 ## Auto-Guard: Locks That Actually Work
 
 When you add a lock, SpecLock **automatically finds and guards related files**:
@@ -303,12 +321,87 @@ speclock audit                         # Audit staged files against locks
 speclock log-change <text> --files x   # Log a change
 speclock context                       # Regenerate context file
 
+# Enterprise (v2.1)
+speclock audit-verify                  # Verify HMAC audit chain integrity
+speclock export --format <soc2|hipaa|csv>  # Compliance export
+speclock license                       # Show license tier and usage
+
+# Hard Enforcement (v2.5)
+speclock enforce <advisory|hard>       # Set enforcement mode
+speclock override <lockId> <reason>    # Override a lock with justification
+speclock overrides [--lock <id>]       # Show override history
+speclock audit-semantic                # Semantic pre-commit audit
+
 # Other
 speclock status                        # Show brain summary
 speclock serve [--project <path>]      # Start MCP server
 speclock watch                         # Start file watcher
 ```
 
+## Enterprise Features (v2.1)
+
+### HMAC Audit Chain
+Every event in `events.log` gets an HMAC-SHA256 hash chained to the previous event. Modify any event and the chain breaks — instant tamper detection.
+
+```bash
+$ npx speclock audit-verify
+
+Audit Chain Verification
+==================================================
+Status: VALID
+Total events: 47
+Hashed events: 47
+Legacy events (pre-v2.1): 0
+Audit chain verified. No tampering detected.
+```
+
+### Compliance Exports
+Generate audit-ready reports for regulated industries:
+
+```bash
+npx speclock export --format soc2    # SOC 2 Type II JSON report
+npx speclock export --format hipaa   # HIPAA PHI protection report
+npx speclock export --format csv     # All events as CSV spreadsheet
+```
+
+SOC 2 reports include: constraint change history, access logs, decision audit trail, audit chain integrity verification. HIPAA reports filter for PHI-related constraints and check encryption/access control status.
+
+### License Tiers
+| Tier | Price | Locks | Features |
+|------|-------|-------|----------|
+| **Free** | $0 | 10 | Conflict detection, MCP, CLI, context |
+| **Pro** | $19/mo | Unlimited | + LLM detection, HMAC audit, compliance exports |
+| **Enterprise** | $99/mo | Unlimited | + RBAC, encrypted storage, SSO |
+
+### HTTP Server Hardening
+- Rate limiting: 100 req/min per IP (configurable via `SPECLOCK_RATE_LIMIT`)
+- CORS: configurable origins via `SPECLOCK_CORS_ORIGINS`
+- Health endpoint: `GET /health` with uptime and audit chain status
+
+### GitHub Actions
+```yaml
+# In your workflow:
+- uses: sgroy10/speclock-check@v2
+  with:
+    fail-on-conflict: true
+```
+Audits changed files against locks, posts PR comments, fails workflow on violations.
+
+## Hard Enforcement (v2.5)
+
+### Advisory vs Hard Mode
+```
+Advisory mode (default): AI gets a warning, decides what to do
+Hard mode:               AI is BLOCKED — cannot proceed (MCP returns isError: true)
+```
+
+- **Block threshold**: Configurable (default 70%). Only HIGH confidence conflicts block.
+- **Override mechanism**: `speclock_override_lock` with a reason (logged to audit trail)
+- **Escalation**: Lock overridden 3+ times → auto-creates a review note
+- **Semantic pre-commit**: Parses actual git diff content, runs semantic analysis against locks
+
+---
+
 ## Architecture
 
 ```
@@ -317,18 +410,20 @@ speclock watch                         # Start file watcher
 └──────────────┬──────────────────┬────────────────────┘
                │                  │
      MCP Protocol          File-Based (npm)
-    (22 tool calls)      (reads SPECLOCK.md +
+    (28 tool calls)      (reads SPECLOCK.md +
                         .speclock/context/latest.md,
                          runs CLI commands)
                │                  │
 ┌──────────────▼──────────────────▼────────────────────┐
 │              SpecLock Core Engine                      │
-│   Memory | Tracking | Enforcement | Git | Intelligence│
+│  Memory | Tracking | Enforcement | Git | Intelligence │
+│  Audit  | Compliance | License                        │
 └──────────────────────┬───────────────────────────────┘
                        │
                 .speclock/
                 ├── brain.json         (structured memory)
-                ├── events.log         (immutable audit trail)
+                ├── events.log         (HMAC-signed audit trail)
+                ├── .audit-key         (HMAC secret — gitignored)
                 ├── patches/           (git diffs per event)
                 └── context/
                     └── latest.md      (human-readable context)
@@ -352,4 +447,4 @@ MIT License - see [LICENSE](LICENSE) file.
 
 ---
 
-*SpecLock v2.0.0 — Real semantic conflict detection. 100% detection, 0% false positives. Because remembering isn't enough — AI needs to respect boundaries.*
+*SpecLock v2.5.0 — Semantic conflict detection + enterprise audit & compliance. 100% detection, 0% false positives. HMAC audit chain, SOC 2/HIPAA exports. Hard enforcement mode. Because remembering isn't enough — AI needs to respect boundaries.*

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "speclock",
-  "version": "2.1.0",
-  "description": "AI constraint engine with semantic conflict detection, HMAC audit chain, SOC 2/HIPAA compliance exports. 100% detection, 0% false positives. 24 MCP tools + CLI. Enterprise-ready memory + enforcement.",
+  "version": "2.5.0",
+  "description": "AI constraint engine with hard enforcement, semantic pre-commit, HMAC audit chain, SOC 2/HIPAA compliance. 100% detection, 0% false positives. 28 MCP tools + CLI. Enterprise-ready.",
   "type": "module",
   "main": "src/mcp/server.js",
   "bin": {
@@ -64,6 +64,7 @@
     "LICENSE"
   ],
   "devDependencies": {
-    "esbuild": "^0.27.3"
+    "esbuild": "^0.27.3",
+    "jest": "^30.2.0"
   }
 }

package/src/cli/index.js

@@ -23,6 +23,12 @@ import {
   verifyAuditChain,
   exportCompliance,
   getLicenseInfo,
+  enforceConflictCheck,
+  setEnforcementMode,
+  overrideLock,
+  getOverrideHistory,
+  getEnforcementConfig,
+  semanticAudit,
 } from "../core/engine.js";
 import { generateContext } from "../core/context.js";
 import { readBrain } from "../core/storage.js";
@@ -82,7 +88,7 @@ function refreshContext(root) {
 
 function printHelp() {
   console.log(`
-SpecLock v2.1.0 — AI Constraint Engine (Enterprise)
+SpecLock v2.5.0 — AI Constraint Engine (Hard Enforcement + Semantic Pre-Commit)
 Developed by Sandeep Roy (github.com/sgroy10)
 
 Usage: speclock <command> [options]
@@ -105,7 +111,11 @@ Commands:
   hook install                    Install git pre-commit hook
   hook remove                     Remove git pre-commit hook
   audit                           Audit staged files against locks
+  audit-semantic                  Semantic audit: analyze code changes vs locks
   audit-verify                    Verify HMAC audit chain integrity
+  enforce <advisory|hard>         Set enforcement mode (advisory=warn, hard=block)
+  override <lockId> <reason>      Override a lock with justification
+  overrides [--lock <id>]         Show override history
   export --format <soc2|hipaa|csv>  Export compliance report
   license                         Show license tier and usage info
   context                         Generate and print context pack
@@ -385,10 +395,12 @@ Tip: When starting a new chat, tell the AI:
       console.error('Usage: speclock check "what you plan to do"');
       process.exit(1);
     }
-    const result = checkConflict(root, text);
+    const result = enforceConflictCheck(root, text);
     if (result.hasConflict) {
-      console.log(`\nCONFLICT DETECTED`);
+      console.log(`\n${result.blocked ? "BLOCKED" : "CONFLICT DETECTED"}`);
       console.log("=".repeat(50));
+      console.log(`Mode: ${result.mode} | Threshold: ${result.threshold}%`);
+      console.log("");
       for (const lock of result.conflictingLocks) {
         console.log(`  [${lock.level}] "${lock.text}"`);
         console.log(`  Confidence: ${lock.confidence}%`);
@@ -400,6 +412,9 @@ Tip: When starting a new chat, tell the AI:
         console.log("");
       }
       console.log(result.analysis);
+      if (result.blocked) {
+        process.exit(1);
+      }
     } else {
       console.log(`No conflicts found. Safe to proceed with: "${text}"`);
     }
@@ -674,6 +689,95 @@ Tip: When starting a new chat, tell the AI:
     return;
   }
 
+  // --- ENFORCE (v2.5) ---
+  if (cmd === "enforce") {
+    const mode = args[0];
+    if (!mode || (mode !== "advisory" && mode !== "hard")) {
+      console.error("Usage: speclock enforce <advisory|hard> [--threshold 70]");
+      process.exit(1);
+    }
+    const flags = parseFlags(args.slice(1));
+    const options = {};
+    if (flags.threshold) options.blockThreshold = parseInt(flags.threshold, 10);
+    if (flags.override !== undefined) options.allowOverride = flags.override !== "false";
+    const result = setEnforcementMode(root, mode, options);
+    if (!result.success) {
+      console.error(result.error);
+      process.exit(1);
+    }
+    console.log(`\nEnforcement mode: ${result.mode.toUpperCase()}`);
+    console.log(`Block threshold: ${result.config.blockThreshold}%`);
+    console.log(`Overrides: ${result.config.allowOverride ? "allowed" : "disabled"}`);
+    if (result.mode === "hard") {
+      console.log(`\nHard mode active — conflicts above ${result.config.blockThreshold}% confidence will BLOCK actions.`);
+    }
+    return;
+  }
+
+  // --- OVERRIDE (v2.5) ---
+  if (cmd === "override") {
+    const lockId = args[0];
+    const reason = args.slice(1).join(" ");
+    if (!lockId || !reason) {
+      console.error("Usage: speclock override <lockId> <reason>");
+      process.exit(1);
+    }
+    const result = overrideLock(root, lockId, "(CLI override)", reason);
+    if (!result.success) {
+      console.error(result.error);
+      process.exit(1);
+    }
+    console.log(`Lock overridden: "${result.lockText}"`);
+    console.log(`Override count: ${result.overrideCount}`);
+    if (result.escalated) {
+      console.log(`\n${result.escalationMessage}`);
+    }
+    return;
+  }
+
+  // --- OVERRIDES (v2.5) ---
+  if (cmd === "overrides") {
+    const flags = parseFlags(args);
+    const result = getOverrideHistory(root, flags.lock || null);
+    if (result.total === 0) {
+      console.log("No overrides recorded.");
+      return;
+    }
+    console.log(`\nOverride History (${result.total})`);
+    console.log("=".repeat(50));
+    for (const o of result.overrides) {
+      console.log(`[${o.at.substring(0, 19)}] Lock: "${o.lockText}"`);
+      console.log(`  Action: ${o.action}`);
+      console.log(`  Reason: ${o.reason}`);
+      console.log("");
+    }
+    return;
+  }
+
+  // --- AUDIT-SEMANTIC (v2.5) ---
+  if (cmd === "audit-semantic") {
+    const result = semanticAudit(root);
+    console.log(`\nSemantic Pre-Commit Audit`);
+    console.log("=".repeat(50));
+    console.log(`Mode: ${result.mode} | Threshold: ${result.threshold}%`);
+    console.log(`Files analyzed: ${result.filesChecked}`);
+    console.log(`Active locks: ${result.activeLocks}`);
+    console.log(`Violations: ${result.violations.length}`);
+    if (result.violations.length > 0) {
+      console.log("");
+      for (const v of result.violations) {
+        console.log(`  [${v.level}] ${v.file} (confidence: ${v.confidence}%)`);
+        console.log(`    Lock: "${v.lockText}"`);
+        console.log(`    Reason: ${v.reason}`);
+        if (v.addedLines !== undefined) {
+          console.log(`    Changes: +${v.addedLines} / -${v.removedLines} lines`);
+        }
+      }
+    }
+    console.log(`\n${result.message}`);
+    process.exit(result.blocked ? 1 : 0);
+  }
+
   // --- STATUS ---
   if (cmd === "status") {
     showStatus(root);

package/src/core/compliance.js

@@ -9,7 +9,7 @@
 import { readBrain, readEvents } from "./storage.js";
 import { verifyAuditChain } from "./audit.js";
 
-const VERSION = "2.1.0";
+const VERSION = "2.5.0";
 
 // PHI-related keywords for HIPAA filtering
 const PHI_KEYWORDS = [