speclock 2.1.1 → 2.5.0

package/README.md

@@ -58,6 +58,7 @@ No other tool does this. Not Claude's native memory. Not Mem0. Not CLAUDE.md fil
 | 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)** |
 
@@ -192,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` — 24 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 |
 
-## 24 MCP Tools
+## 28 MCP Tools
 
 ### Memory Management
 | Tool | Purpose |
@@ -249,6 +250,14 @@ Result:  NO CONFLICT (confidence: 7%)
 | `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**:
@@ -317,6 +326,12 @@ 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
@@ -372,6 +387,19 @@ SOC 2 reports include: constraint change history, access logs, decision audit tr
 ```
 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
@@ -382,7 +410,7 @@ Audits changed files against locks, posts PR comments, fails workflow on violati
 └──────────────┬──────────────────┬────────────────────┘
                │                  │
      MCP Protocol          File-Based (npm)
-    (24 tool calls)      (reads SPECLOCK.md +
+    (28 tool calls)      (reads SPECLOCK.md +
                         .speclock/context/latest.md,
                          runs CLI commands)
                │                  │
@@ -419,4 +447,4 @@ MIT License - see [LICENSE](LICENSE) file.
 
 ---
 
-*SpecLock v2.1.0 — Semantic conflict detection + enterprise audit & compliance. 100% detection, 0% false positives. HMAC audit chain, SOC 2/HIPAA exports. 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.1",
-  "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.1 — 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.1";
+const VERSION = "2.5.0";
 
 // PHI-related keywords for HIPAA filtering
 const PHI_KEYWORDS = [

package/src/core/conflict.js

@@ -0,0 +1,363 @@
+/**
+ * SpecLock Conflict Detection Module
+ * Conflict checking, drift detection, lock suggestions, audit.
+ * Extracted from engine.js for modularity.
+ *
+ * Developed by Sandeep Roy (https://github.com/sgroy10)
+ */
+
+import fs from "fs";
+import path from "path";
+import {
+  nowIso,
+  readBrain,
+  writeBrain,
+  readEvents,
+  addViolation,
+} from "./storage.js";
+import { getStagedFiles } from "./git.js";
+import { analyzeConflict } from "./semantics.js";
+import { ensureInit } from "./memory.js";
+
+// --- Legacy helpers (kept for pre-commit audit backward compat) ---
+
+const NEGATION_WORDS = ["no", "not", "never", "without", "dont", "don't", "cannot", "can't", "shouldn't", "mustn't", "avoid", "prevent", "prohibit", "forbid", "disallow"];
+
+function hasNegation(text) {
+  const lower = text.toLowerCase();
+  return NEGATION_WORDS.some((neg) => lower.includes(neg));
+}
+
+const FILE_KEYWORD_PATTERNS = [
+  { keywords: ["auth", "authentication", "login", "signup", "signin", "sign-in", "sign-up"], patterns: ["**/Auth*", "**/auth*", "**/Login*", "**/login*", "**/SignUp*", "**/signup*", "**/SignIn*", "**/signin*", "**/*Auth*", "**/*auth*"] },
+  { keywords: ["database", "db", "supabase", "firebase", "mongo", "postgres", "sql", "prisma"], patterns: ["**/supabase*", "**/firebase*", "**/database*", "**/db.*", "**/db/**", "**/prisma/**", "**/*Client*", "**/*client*"] },
+  { keywords: ["payment", "pay", "stripe", "billing", "checkout", "subscription"], patterns: ["**/payment*", "**/Payment*", "**/pay*", "**/Pay*", "**/stripe*", "**/Stripe*", "**/billing*", "**/Billing*", "**/checkout*", "**/Checkout*"] },
+  { keywords: ["api", "endpoint", "route", "routes"], patterns: ["**/api/**", "**/routes/**", "**/endpoints/**"] },
+  { keywords: ["config", "configuration", "settings", "env"], patterns: ["**/config*", "**/Config*", "**/settings*", "**/Settings*"] },
+];
+
+function patternMatchesFile(pattern, filePath) {
+  const clean = pattern.replace(/\\/g, "/");
+  const fileLower = filePath.toLowerCase();
+  const patternLower = clean.toLowerCase();
+  const namePattern = patternLower.replace(/^\*\*\//, "");
+  if (!namePattern.includes("/")) {
+    const fileName = fileLower.split("/").pop();
+    const regex = new RegExp("^" + namePattern.replace(/\*/g, ".*") + "$");
+    if (regex.test(fileName)) return true;
+    const corePattern = namePattern.replace(/\*/g, "");
+    if (corePattern.length > 2 && fileName.includes(corePattern)) return true;
+  }
+  const regex = new RegExp("^" + patternLower.replace(/\*\*\//g, "(.*/)?").replace(/\*/g, "[^/]*") + "$");
+  return regex.test(fileLower);
+}
+
+const GUARD_TAG = "SPECLOCK-GUARD";
+
+// --- Core functions ---
+
+export function checkConflict(root, proposedAction) {
+  const brain = ensureInit(root);
+  const activeLocks = brain.specLock.items.filter((l) => l.active !== false);
+  if (activeLocks.length === 0) {
+    return {
+      hasConflict: false,
+      conflictingLocks: [],
+      analysis: "No active locks. No constraints to check against.",
+    };
+  }
+
+  const conflicting = [];
+  for (const lock of activeLocks) {
+    const result = analyzeConflict(proposedAction, lock.text);
+    if (result.isConflict) {
+      conflicting.push({
+        id: lock.id,
+        text: lock.text,
+        matchedKeywords: [],
+        confidence: result.confidence,
+        level: result.level,
+        reasons: result.reasons,
+      });
+    }
+  }
+
+  if (conflicting.length === 0) {
+    return {
+      hasConflict: false,
+      conflictingLocks: [],
+      analysis: `Checked against ${activeLocks.length} active lock(s). No conflicts detected (semantic analysis v2). Proceed with caution.`,
+    };
+  }
+
+  conflicting.sort((a, b) => b.confidence - a.confidence);
+
+  const details = conflicting
+    .map(
+      (c) =>
+        `- [${c.level}] "${c.text}" (confidence: ${c.confidence}%)\n  Reasons: ${c.reasons.join("; ")}`
+    )
+    .join("\n");
+
+  const result = {
+    hasConflict: true,
+    conflictingLocks: conflicting,
+    analysis: `Potential conflict with ${conflicting.length} lock(s):\n${details}\nReview before proceeding.`,
+  };
+
+  addViolation(brain, {
+    at: nowIso(),
+    action: proposedAction,
+    locks: conflicting.map((c) => ({ id: c.id, text: c.text, confidence: c.confidence, level: c.level })),
+    topLevel: conflicting[0].level,
+    topConfidence: conflicting[0].confidence,
+  });
+  writeBrain(root, brain);
+
+  return result;
+}
+
+export async function checkConflictAsync(root, proposedAction) {
+  try {
+    const { llmCheckConflict } = await import("./llm-checker.js");
+    const llmResult = await llmCheckConflict(root, proposedAction);
+    if (llmResult) return llmResult;
+  } catch (_) {
+    // LLM checker not available — fall through
+  }
+  return checkConflict(root, proposedAction);
+}
+
+export function suggestLocks(root) {
+  const brain = ensureInit(root);
+  const suggestions = [];
+
+  for (const dec of brain.decisions) {
+    const lower = dec.text.toLowerCase();
+    if (/\b(always|must|only|exclusively|never|required)\b/.test(lower)) {
+      suggestions.push({
+        text: dec.text,
+        source: "decision",
+        sourceId: dec.id,
+        reason: `Decision contains strong commitment language — consider promoting to a lock`,
+      });
+    }
+  }
+
+  for (const note of brain.notes) {
+    const lower = note.text.toLowerCase();
+    if (/\b(never|must not|do not|don't|avoid|prohibit|forbidden)\b/.test(lower)) {
+      suggestions.push({
+        text: note.text,
+        source: "note",
+        sourceId: note.id,
+        reason: `Note contains prohibitive language — consider promoting to a lock`,
+      });
+    }
+  }
+
+  const existingLockTexts = brain.specLock.items
+    .filter((l) => l.active)
+    .map((l) => l.text.toLowerCase());
+
+  const commonPatterns = [
+    { keyword: "api", suggestion: "No breaking changes to public API" },
+    { keyword: "database", suggestion: "No destructive database migrations without backup" },
+    { keyword: "deploy", suggestion: "All deployments must pass CI checks" },
+    { keyword: "security", suggestion: "No secrets or credentials in source code" },
+    { keyword: "test", suggestion: "No merging without passing tests" },
+  ];
+
+  const allText = [
+    brain.goal.text,
+    ...brain.decisions.map((d) => d.text),
+    ...brain.notes.map((n) => n.text),
+  ].join(" ").toLowerCase();
+
+  for (const pattern of commonPatterns) {
+    if (allText.includes(pattern.keyword)) {
+      const alreadyLocked = existingLockTexts.some((t) =>
+        t.includes(pattern.keyword)
+      );
+      if (!alreadyLocked) {
+        suggestions.push({
+          text: pattern.suggestion,
+          source: "pattern",
+          sourceId: null,
+          reason: `Project mentions "${pattern.keyword}" but has no lock protecting it`,
+        });
+      }
+    }
+  }
+
+  return { suggestions, totalLocks: brain.specLock.items.filter((l) => l.active).length };
+}
+
+export function detectDrift(root) {
+  const brain = ensureInit(root);
+  const activeLocks = brain.specLock.items.filter((l) => l.active !== false);
+  if (activeLocks.length === 0) {
+    return { drifts: [], status: "no_locks", message: "No active locks to check against." };
+  }
+
+  const drifts = [];
+
+  for (const change of brain.state.recentChanges) {
+    for (const lock of activeLocks) {
+      const result = analyzeConflict(change.summary, lock.text);
+      if (result.isConflict) {
+        drifts.push({
+          lockId: lock.id,
+          lockText: lock.text,
+          changeEventId: change.eventId,
+          changeSummary: change.summary,
+          changeAt: change.at,
+          matchedTerms: result.reasons,
+          severity: result.level === "HIGH" ? "high" : "medium",
+        });
+      }
+    }
+  }
+
+  for (const revert of brain.state.reverts) {
+    drifts.push({
+      lockId: null,
+      lockText: "(git revert detected)",
+      changeEventId: revert.eventId,
+      changeSummary: `Git ${revert.kind} to ${revert.target.substring(0, 12)}`,
+      changeAt: revert.at,
+      matchedTerms: ["revert"],
+      severity: "high",
+    });
+  }
+
+  const status = drifts.length === 0 ? "clean" : "drift_detected";
+  const message = drifts.length === 0
+    ? `All clear. ${activeLocks.length} lock(s) checked against ${brain.state.recentChanges.length} recent change(s). No drift detected.`
+    : `WARNING: ${drifts.length} potential drift(s) detected. Review immediately.`;
+
+  return { drifts, status, message };
+}
+
+export function generateReport(root) {
+  const brain = ensureInit(root);
+  const violations = brain.state.violations || [];
+
+  if (violations.length === 0) {
+    return {
+      totalViolations: 0,
+      violationsByLock: {},
+      mostTestedLocks: [],
+      recentViolations: [],
+      summary: "No violations recorded yet. SpecLock is watching.",
+    };
+  }
+
+  const byLock = {};
+  for (const v of violations) {
+    for (const lock of v.locks) {
+      if (!byLock[lock.text]) {
+        byLock[lock.text] = { count: 0, lockId: lock.id, text: lock.text };
+      }
+      byLock[lock.text].count++;
+    }
+  }
+
+  const mostTested = Object.values(byLock).sort((a, b) => b.count - a.count);
+  const recent = violations.slice(0, 10).map((v) => ({
+    at: v.at,
+    action: v.action,
+    topLevel: v.topLevel,
+    topConfidence: v.topConfidence,
+    lockCount: v.locks.length,
+  }));
+
+  const oldest = violations[violations.length - 1];
+  const newest = violations[0];
+
+  return {
+    totalViolations: violations.length,
+    timeRange: { from: oldest.at, to: newest.at },
+    violationsByLock: byLock,
+    mostTestedLocks: mostTested.slice(0, 5),
+    recentViolations: recent,
+    summary: `SpecLock blocked ${violations.length} violation(s). Most tested lock: "${mostTested[0].text}" (${mostTested[0].count} blocks).`,
+  };
+}
+
+export function auditStagedFiles(root) {
+  const brain = ensureInit(root);
+  const activeLocks = brain.specLock.items.filter((l) => l.active !== false);
+
+  if (activeLocks.length === 0) {
+    return { passed: true, violations: [], checkedFiles: 0, activeLocks: 0, message: "No active locks. Audit passed." };
+  }
+
+  const stagedFiles = getStagedFiles(root);
+  if (stagedFiles.length === 0) {
+    return { passed: true, violations: [], checkedFiles: 0, activeLocks: activeLocks.length, message: "No staged files. Audit passed." };
+  }
+
+  const violations = [];
+
+  for (const file of stagedFiles) {
+    const fullPath = path.join(root, file);
+    if (fs.existsSync(fullPath)) {
+      try {
+        const content = fs.readFileSync(fullPath, "utf-8");
+        if (content.includes(GUARD_TAG)) {
+          violations.push({
+            file,
+            reason: "File has SPECLOCK-GUARD header — it is locked and must not be modified",
+            lockText: "(file-level guard)",
+            severity: "HIGH",
+          });
+          continue;
+        }
+      } catch (_) {}
+    }
+
+    const fileLower = file.toLowerCase();
+    for (const lock of activeLocks) {
+      const lockLower = lock.text.toLowerCase();
+      const lockHasNegation = hasNegation(lockLower);
+      if (!lockHasNegation) continue;
+
+      for (const group of FILE_KEYWORD_PATTERNS) {
+        const lockMatchesKeyword = group.keywords.some((kw) => lockLower.includes(kw));
+        if (!lockMatchesKeyword) continue;
+
+        const fileMatchesPattern = group.patterns.some((pattern) => patternMatchesFile(pattern, fileLower) || patternMatchesFile(pattern, fileLower.split("/").pop()));
+        if (fileMatchesPattern) {
+          violations.push({
+            file,
+            reason: `File matches lock keyword pattern`,
+            lockText: lock.text,
+            severity: "MEDIUM",
+          });
+          break;
+        }
+      }
+    }
+  }
+
+  const seen = new Set();
+  const unique = violations.filter((v) => {
+    if (seen.has(v.file)) return false;
+    seen.add(v.file);
+    return true;
+  });
+
+  const passed = unique.length === 0;
+  const message = passed
+    ? `Audit passed. ${stagedFiles.length} file(s) checked against ${activeLocks.length} lock(s).`
+    : `AUDIT FAILED: ${unique.length} violation(s) in ${stagedFiles.length} staged file(s).`;
+
+  return {
+    passed,
+    violations: unique,
+    checkedFiles: stagedFiles.length,
+    activeLocks: activeLocks.length,
+    message,
+  };
+}