speclock 5.2.5 → 5.3.0

package/src/core/rules-sync.js

@@ -0,0 +1,548 @@
+/**
+ * SpecLock Rules Sync — Universal AI Rules File Generator
+ * Syncs SpecLock constraints to .cursorrules, CLAUDE.md, AGENTS.md,
+ * .windsurfrules, copilot-instructions.md, GEMINI.md, and more.
+ *
+ * One source of truth → every AI tool gets the same constraints.
+ *
+ * Developed by Sandeep Roy (https://github.com/sgroy10)
+ */
+
+import fs from "fs";
+import path from "path";
+import { readBrain } from "./storage.js";
+import { ensureInit } from "./memory.js";
+
+// --- Format definitions ---
+
+const FORMATS = {
+  cursor: {
+    name: "Cursor",
+    file: ".cursor/rules/speclock.mdc",
+    description: "Cursor AI rules (MDC format)",
+    generate: generateCursorRules,
+  },
+  claude: {
+    name: "Claude Code",
+    file: "CLAUDE.md",
+    description: "Claude Code project instructions",
+    generate: generateClaudeMd,
+  },
+  agents: {
+    name: "AGENTS.md",
+    file: "AGENTS.md",
+    description: "Cross-tool agent instructions (Linux Foundation standard)",
+    generate: generateAgentsMd,
+  },
+  windsurf: {
+    name: "Windsurf",
+    file: ".windsurf/rules/speclock.md",
+    description: "Windsurf AI rules",
+    generate: generateWindsurfRules,
+  },
+  copilot: {
+    name: "GitHub Copilot",
+    file: ".github/copilot-instructions.md",
+    description: "GitHub Copilot custom instructions",
+    generate: generateCopilotInstructions,
+  },
+  gemini: {
+    name: "Gemini",
+    file: "GEMINI.md",
+    description: "Google Gemini CLI instructions",
+    generate: generateGeminiMd,
+  },
+  codex: {
+    name: "Codex",
+    file: "AGENTS.md",
+    description: "OpenAI Codex agent instructions (uses AGENTS.md)",
+    generate: generateAgentsMd,
+  },
+  aider: {
+    name: "Aider",
+    file: ".aider.conf.yml",
+    description: "Aider conventions file",
+    generate: generateAiderConf,
+  },
+};
+
+// --- Helpers ---
+
+function getActiveLocks(brain) {
+  return (brain.specLock?.items || []).filter((l) => l.active !== false);
+}
+
+function getActiveDecisions(brain) {
+  return brain.decisions || [];
+}
+
+function getGoal(brain) {
+  return brain.goal?.text || "";
+}
+
+function timestamp() {
+  return new Date().toISOString().substring(0, 19).replace("T", " ");
+}
+
+function header(format) {
+  return `# SpecLock Constraints — Auto-synced for ${format}\n# Generated: ${timestamp()}\n# Source: .speclock/brain.json\n# Do not edit manually — run \`speclock sync\` to regenerate\n# https://github.com/sgroy10/speclock\n`;
+}
+
+// --- Format generators ---
+
+function generateCursorRules(brain) {
+  const locks = getActiveLocks(brain);
+  const decisions = getActiveDecisions(brain);
+  const goal = getGoal(brain);
+
+  const lines = [];
+
+  // MDC frontmatter
+  lines.push("---");
+  lines.push("description: SpecLock project constraints — enforced automatically");
+  lines.push("globs: **/*");
+  lines.push("alwaysApply: true");
+  lines.push("---");
+  lines.push("");
+  lines.push("# SpecLock Constraints");
+  lines.push("");
+  lines.push(`> Auto-synced from SpecLock. Run \`speclock sync --format cursor\` to update.`);
+  lines.push("");
+
+  if (goal) {
+    lines.push("## Project Goal");
+    lines.push(goal);
+    lines.push("");
+  }
+
+  if (locks.length > 0) {
+    lines.push("## Non-Negotiable Constraints");
+    lines.push("");
+    lines.push("**These constraints MUST be followed. Violating any of them is an error.**");
+    lines.push("");
+    for (const lock of locks) {
+      lines.push(`- **[LOCKED]** ${lock.text}`);
+    }
+    lines.push("");
+  }
+
+  if (decisions.length > 0) {
+    lines.push("## Architectural Decisions");
+    lines.push("");
+    for (const dec of decisions.slice(0, 10)) {
+      lines.push(`- ${dec.text}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("---");
+  lines.push("*Powered by [SpecLock](https://github.com/sgroy10/speclock) — AI Constraint Engine by Sandeep Roy*");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+function generateClaudeMd(brain) {
+  const locks = getActiveLocks(brain);
+  const decisions = getActiveDecisions(brain);
+  const goal = getGoal(brain);
+
+  const lines = [];
+  lines.push(header("Claude Code"));
+  lines.push("");
+  lines.push("# Project Constraints (SpecLock)");
+  lines.push("");
+
+  if (goal) {
+    lines.push("## Goal");
+    lines.push(goal);
+    lines.push("");
+  }
+
+  if (locks.length > 0) {
+    lines.push("## IMPORTANT: Non-Negotiable Rules");
+    lines.push("");
+    lines.push("The following constraints are enforced by SpecLock. Do NOT violate any of them.");
+    lines.push("If a task conflicts with these constraints, STOP and inform the user.");
+    lines.push("");
+    for (let i = 0; i < locks.length; i++) {
+      lines.push(`${i + 1}. **${lock_text(locks[i])}**`);
+    }
+    lines.push("");
+  }
+
+  if (decisions.length > 0) {
+    lines.push("## Architectural Decisions");
+    lines.push("");
+    for (const dec of decisions.slice(0, 10)) {
+      lines.push(`- ${dec.text}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("---");
+  lines.push("*Auto-synced by [SpecLock](https://github.com/sgroy10/speclock). Run `speclock sync` to update.*");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+function lock_text(lock) {
+  return lock.originalText || lock.text;
+}
+
+function generateAgentsMd(brain) {
+  const locks = getActiveLocks(brain);
+  const decisions = getActiveDecisions(brain);
+  const goal = getGoal(brain);
+
+  const lines = [];
+  lines.push("# AGENTS.md");
+  lines.push("");
+  lines.push(`> Auto-synced from SpecLock. Run \`speclock sync --format agents\` to update.`);
+  lines.push("");
+
+  if (goal) {
+    lines.push("## Project Goal");
+    lines.push("");
+    lines.push(goal);
+    lines.push("");
+  }
+
+  if (locks.length > 0) {
+    lines.push("## Constraints");
+    lines.push("");
+    lines.push("The following rules are non-negotiable. Any AI agent working on this codebase MUST respect them:");
+    lines.push("");
+    for (const lock of locks) {
+      lines.push(`- **NEVER VIOLATE:** ${lock_text(lock)}`);
+    }
+    lines.push("");
+  }
+
+  if (decisions.length > 0) {
+    lines.push("## Decisions");
+    lines.push("");
+    for (const dec of decisions.slice(0, 10)) {
+      lines.push(`- ${dec.text}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## Working with this project");
+  lines.push("");
+  lines.push("- Before making changes, check if they conflict with the constraints above");
+  lines.push("- If a requested change violates a constraint, inform the user and suggest alternatives");
+  lines.push("- Run `speclock check \"<your planned action>\"` to verify before proceeding");
+  lines.push("");
+  lines.push("---");
+  lines.push("*Powered by [SpecLock](https://github.com/sgroy10/speclock) — AI Constraint Engine by Sandeep Roy*");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+function generateWindsurfRules(brain) {
+  const locks = getActiveLocks(brain);
+  const decisions = getActiveDecisions(brain);
+  const goal = getGoal(brain);
+
+  const lines = [];
+  lines.push("# SpecLock Constraints for Windsurf");
+  lines.push("");
+  lines.push(`> Auto-synced. Run \`speclock sync --format windsurf\` to update.`);
+  lines.push("");
+
+  if (goal) {
+    lines.push(`## Project Goal: ${goal}`);
+    lines.push("");
+  }
+
+  if (locks.length > 0) {
+    lines.push("## Rules (Non-Negotiable)");
+    lines.push("");
+    for (const lock of locks) {
+      lines.push(`- MUST: ${lock_text(lock)}`);
+    }
+    lines.push("");
+  }
+
+  if (decisions.length > 0) {
+    lines.push("## Architectural Decisions");
+    lines.push("");
+    for (const dec of decisions.slice(0, 10)) {
+      lines.push(`- ${dec.text}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("---");
+  lines.push("*Powered by [SpecLock](https://github.com/sgroy10/speclock)*");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+function generateCopilotInstructions(brain) {
+  const locks = getActiveLocks(brain);
+  const decisions = getActiveDecisions(brain);
+  const goal = getGoal(brain);
+
+  const lines = [];
+  lines.push("# GitHub Copilot Instructions (SpecLock)");
+  lines.push("");
+  lines.push(`> Auto-synced. Run \`speclock sync --format copilot\` to update.`);
+  lines.push("");
+
+  if (goal) {
+    lines.push(`## Project: ${goal}`);
+    lines.push("");
+  }
+
+  if (locks.length > 0) {
+    lines.push("## Constraints");
+    lines.push("");
+    lines.push("When generating or modifying code, respect these constraints:");
+    lines.push("");
+    for (const lock of locks) {
+      lines.push(`- **DO NOT** violate: ${lock_text(lock)}`);
+    }
+    lines.push("");
+  }
+
+  if (decisions.length > 0) {
+    lines.push("## Project Decisions");
+    lines.push("");
+    for (const dec of decisions.slice(0, 10)) {
+      lines.push(`- ${dec.text}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("---");
+  lines.push("*Auto-synced by [SpecLock](https://github.com/sgroy10/speclock)*");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+function generateGeminiMd(brain) {
+  const locks = getActiveLocks(brain);
+  const decisions = getActiveDecisions(brain);
+  const goal = getGoal(brain);
+
+  const lines = [];
+  lines.push("# GEMINI.md — Project Constraints (SpecLock)");
+  lines.push("");
+  lines.push(`> Auto-synced. Run \`speclock sync --format gemini\` to update.`);
+  lines.push("");
+
+  if (goal) {
+    lines.push("## Goal");
+    lines.push(goal);
+    lines.push("");
+  }
+
+  if (locks.length > 0) {
+    lines.push("## Non-Negotiable Constraints");
+    lines.push("");
+    lines.push("These rules must NEVER be violated:");
+    lines.push("");
+    for (const lock of locks) {
+      lines.push(`- ${lock_text(lock)}`);
+    }
+    lines.push("");
+  }
+
+  if (decisions.length > 0) {
+    lines.push("## Decisions");
+    lines.push("");
+    for (const dec of decisions.slice(0, 10)) {
+      lines.push(`- ${dec.text}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("---");
+  lines.push("*Powered by [SpecLock](https://github.com/sgroy10/speclock) — AI Constraint Engine by Sandeep Roy*");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+function generateAiderConf(brain) {
+  const locks = getActiveLocks(brain);
+  const goal = getGoal(brain);
+
+  const lines = [];
+  lines.push("# Aider configuration — SpecLock constraints");
+  lines.push(`# Auto-synced. Run \`speclock sync --format aider\` to update.`);
+  lines.push("");
+
+  const conventionLines = [];
+  if (goal) {
+    conventionLines.push(`Project goal: ${goal}`);
+    conventionLines.push("");
+  }
+  if (locks.length > 0) {
+    conventionLines.push("NON-NEGOTIABLE CONSTRAINTS:");
+    for (const lock of locks) {
+      conventionLines.push(`- ${lock_text(lock)}`);
+    }
+  }
+
+  if (conventionLines.length > 0) {
+    lines.push("conventions: |");
+    for (const cl of conventionLines) {
+      lines.push(`  ${cl}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+// --- Main sync function ---
+
+/**
+ * Sync SpecLock constraints to one or all AI tool rule formats.
+ *
+ * @param {string} root - Project root directory
+ * @param {Object} options
+ * @param {string} [options.format] - Specific format to sync (cursor, claude, agents, windsurf, copilot, gemini, aider). If omitted, syncs all.
+ * @param {boolean} [options.dryRun] - If true, returns content without writing files
+ * @param {boolean} [options.append] - If true, appends to existing file instead of overwriting (for claude format)
+ * @returns {{ synced: Array<{format: string, file: string, size: number}>, errors: string[] }}
+ */
+export function syncRules(root, options = {}) {
+  const brain = ensureInit(root);
+  const activeLocks = getActiveLocks(brain);
+
+  if (activeLocks.length === 0) {
+    return {
+      synced: [],
+      errors: ["No active locks found. Add constraints first: speclock lock \"Your constraint\""],
+      lockCount: 0,
+    };
+  }
+
+  const formats = options.format
+    ? { [options.format]: FORMATS[options.format] }
+    : { ...FORMATS };
+
+  // Remove codex duplicate (uses same file as agents)
+  if (!options.format) {
+    delete formats.codex;
+  }
+
+  if (options.format && !FORMATS[options.format]) {
+    return {
+      synced: [],
+      errors: [`Unknown format: "${options.format}". Available: ${Object.keys(FORMATS).join(", ")}`],
+      lockCount: activeLocks.length,
+    };
+  }
+
+  const synced = [];
+  const errors = [];
+
+  for (const [key, fmt] of Object.entries(formats)) {
+    try {
+      const content = fmt.generate(brain);
+      const filePath = path.join(root, fmt.file);
+
+      if (options.dryRun) {
+        synced.push({
+          format: key,
+          name: fmt.name,
+          file: fmt.file,
+          size: content.length,
+          content,
+        });
+        continue;
+      }
+
+      // Handle append mode for CLAUDE.md
+      if (options.append && key === "claude" && fs.existsSync(filePath)) {
+        const existing = fs.readFileSync(filePath, "utf8");
+        // Remove old SpecLock section if present
+        const cleaned = removeSpecLockSection(existing);
+        const merged = cleaned.trimEnd() + "\n\n" + content;
+        fs.writeFileSync(filePath, merged);
+      } else {
+        // Ensure directory exists
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) {
+          fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(filePath, content);
+      }
+
+      synced.push({
+        format: key,
+        name: fmt.name,
+        file: fmt.file,
+        size: content.length,
+      });
+    } catch (err) {
+      errors.push(`${key}: ${err.message}`);
+    }
+  }
+
+  return {
+    synced,
+    errors,
+    lockCount: activeLocks.length,
+    decisionCount: getActiveDecisions(brain).length,
+  };
+}
+
+/**
+ * Remove existing SpecLock section from a file's content.
+ * Looks for the auto-sync header comment and removes everything until the next --- or EOF.
+ */
+function removeSpecLockSection(content) {
+  // Remove from "# SpecLock Constraints" or "# Project Constraints (SpecLock)" to end of SpecLock block
+  const markers = [
+    /# SpecLock Constraints.*$/m,
+    /# Project Constraints \(SpecLock\).*$/m,
+    /^# SpecLock Constraints — Auto-synced.*$/m,
+  ];
+
+  for (const marker of markers) {
+    const match = content.match(marker);
+    if (match) {
+      const startIdx = content.indexOf(match[0]);
+      // Find the end marker: "Auto-synced by [SpecLock]" line
+      const endMarker = "*Auto-synced by [SpecLock]";
+      const endIdx = content.indexOf(endMarker, startIdx);
+      if (endIdx !== -1) {
+        // Remove until end of that line + trailing newlines
+        const lineEnd = content.indexOf("\n", endIdx + endMarker.length);
+        const removeEnd = lineEnd !== -1 ? lineEnd + 1 : content.length;
+        content = content.substring(0, startIdx) + content.substring(removeEnd);
+      }
+    }
+  }
+
+  return content;
+}
+
+/**
+ * Get list of available sync formats.
+ */
+export function getSyncFormats() {
+  return Object.entries(FORMATS).map(([key, fmt]) => ({
+    key,
+    name: fmt.name,
+    file: fmt.file,
+    description: fmt.description,
+  }));
+}
+
+/**
+ * Preview what would be generated for a specific format without writing.
+ */
+export function previewSync(root, format) {
+  return syncRules(root, { format, dryRun: true });
+}

package/src/core/semantics.js

@@ -2297,6 +2297,39 @@ export function scoreConflict({ actionText, lockText }) {
       intentAligned = true;
       reasons.push("intent alignment: adding a database index is a performance optimization — does not modify locked schema");
     }
+
+    // Pattern 6: Technology maintenance/refactoring vs exposure/secrets locks
+    // "Refactor React component file structure" vs "never expose API keys in frontend code" → safe
+    // "Update React Router to v7" vs "never expose API keys in frontend code" → safe
+    // But: "Expose React state to window" → action mentions "expos" → NOT safe
+    // But: "Add API key to React config" → action mentions "api key" → NOT safe
+    // But: "Update endpoint to include email" vs "never expose email" → direct subject overlap → NOT safe
+    // Root cause: concept map links react→frontend, matching "frontend" in exposure lock.
+    // Fix: constructive tech verbs against exposure locks are safe when action doesn't touch secrets
+    // AND there's no direct subject overlap (overlap is only through concept map expansion).
+    if (!intentAligned && !_compoundDestructive) {
+      const _isMaintenanceAction = /\b(?:refactor|restructure|reorganize|update|upgrade|bump|install|configure|optimize|improve|enhance|test|debug|fix|review|clean|format|lint|style|document|migrate)\b/i.test(_actionLowerSafe);
+      const _lockMentionsExposure = /\b(?:expos(?:e|ed|es|ing)?|leak(?:s|ed|ing)?|secrets?|credentials?|api.?keys?|passwords?|tokens?|sensitive)\b/i.test(lockText);
+      const _actionMentionsExposure = /\b(?:expos(?:e|ed|es|ing)?|leak(?:s|ed|ing)?|secrets?|credentials?|api.?keys?|passwords?|tokens?|sensitive|plain.?text|unencrypt)\b/i.test(_actionLowerSafe);
+      // Guard: check for direct subject overlap between action and lock.
+      // If the action directly mentions the lock's protected subjects (not via concept map),
+      // Pattern 6 should not apply — the action touches the lock's domain.
+      const _p6Exclude = /^(?:expos(?:e[ds]?|ing)?|leak(?:s|ed|ing)?|secrets?|credentials?|passwords?|tokens?|sensitive|never|must|should|always|code|dont|does|through|from|with|into|that|this)$/;
+      const _lockSubjects = lockText.toLowerCase()
+        .split(/[\s,]+/)
+        .map(w => w.replace(/[^a-z0-9]/g, ''))
+        .filter(w => w.length > 3 && !_p6Exclude.test(w));
+      const _actionWords6 = new Set(
+        _actionLowerSafe.split(/[\s,]+/)
+          .map(w => w.replace(/[^a-z0-9]/g, ''))
+          .filter(w => w.length > 3)
+      );
+      const _directSubjectOverlap = _lockSubjects.some(w => _actionWords6.has(w));
+      if (_isMaintenanceAction && _lockMentionsExposure && !_actionMentionsExposure && !_directSubjectOverlap) {
+        intentAligned = true;
+        reasons.push("intent alignment: technology maintenance action does not involve secrets/exposure — safe against exposure lock");
+      }
+    }
   }
 
   // Check 3c: Working WITH locked technology (not replacing it)

package/src/core/templates.js

@@ -104,6 +104,75 @@ export const TEMPLATES = {
       "Authentication changes require explicit user approval",
     ],
   },
+
+  "safe-defaults": {
+    name: "safe-defaults",
+    displayName: "Safe Defaults (Vibe Coding Seatbelt)",
+    description: "Prevents the 5 most common AI disasters — database deletion, auth removal, secret exposure, error handling removal, logging disablement",
+    locks: [
+      "Never delete database tables, columns, or user records — migrations must only add or modify, never drop",
+      "Never remove or bypass authentication or authorization — login, signup, session management, and access control are sacred",
+      "Never expose API keys, secrets, passwords, or credentials in client-side code, logs, or error messages",
+      "Never remove error handling, try-catch blocks, or validation logic — these exist for a reason",
+      "Never disable logging, monitoring, or audit trails — observability keeps production alive",
+    ],
+    decisions: [
+      "Safety-first: AI must ask before destructive operations",
+      "All database changes must be additive, not destructive",
+    ],
+  },
+
+  hipaa: {
+    name: "hipaa",
+    displayName: "HIPAA Healthcare",
+    description: "8 constraints for HIPAA-compliant healthcare applications — protects PHI, encryption, audit trails",
+    locks: [
+      "Protected Health Information (PHI) must never be logged, exposed in error messages, or sent to third-party services",
+      "All PHI must be encrypted at rest (AES-256) and in transit (TLS 1.2+) — never store PHI in plaintext",
+      "Authentication must use MFA — never disable or downgrade multi-factor authentication",
+      "Audit logging must capture all access to patient records — never disable audit trails",
+      "Patient data must never be deleted without explicit compliance review — soft-delete only",
+      "FHIR API endpoints must not have breaking changes — healthcare integrations depend on stability",
+      "Session timeout must not exceed 15 minutes of inactivity — never increase or disable session expiry",
+      "Role-based access control must be enforced on all patient data endpoints — never bypass RBAC",
+    ],
+    decisions: [
+      "HIPAA compliance is mandatory — all features must pass compliance review",
+      "PHI storage uses encrypted-at-rest database with per-row access logging",
+    ],
+  },
+
+  "api-stability": {
+    name: "api-stability",
+    displayName: "API Stability",
+    description: "6 constraints for public API projects — protects endpoints, response shapes, versioning",
+    locks: [
+      "Never remove or rename existing API endpoints — deprecated endpoints must continue to work",
+      "Never change the shape of API response objects — adding fields is OK, removing or renaming breaks clients",
+      "Never change HTTP status codes for existing endpoints — clients depend on specific codes",
+      "API versioning must be maintained — never merge v2 changes into v1 endpoints",
+      "Rate limiting and authentication on API endpoints must not be removed or weakened",
+      "Database schema changes must not break existing API contracts — migrations must be backward-compatible",
+    ],
+    decisions: [
+      "API follows semantic versioning — breaking changes require a new API version",
+      "All API changes must be backward-compatible within the same version",
+    ],
+  },
+
+  "solo-founder": {
+    name: "solo-founder",
+    displayName: "Solo Founder",
+    description: "3 essential constraints for solo builders — protects the things that cost you the most time to fix",
+    locks: [
+      "Never delete or drop database tables, user data, or production records — my users' data is sacred",
+      "Never modify the payment or billing system without explicit permission — revenue is life",
+      "Never remove authentication, session management, or access control — security is non-negotiable",
+    ],
+    decisions: [
+      "Ship fast but never break auth, payments, or user data",
+    ],
+  },
 };
 
 export function getTemplateNames() {

package/src/dashboard/index.html

@@ -89,7 +89,7 @@
 <div class="header">
   <div>
     <h1><span>SpecLock</span> Dashboard</h1>
-    <div class="meta">v5.2.5 &mdash; AI Constraint Engine</div>
+    <div class="meta">v5.3.0 &mdash; AI Constraint Engine</div>
   </div>
   <div style="display:flex;align-items:center;gap:12px;">
     <span id="health-badge" class="status-badge healthy">Loading...</span>
@@ -182,7 +182,7 @@
 </div>
 
 <div style="text-align:center;padding:24px;color:var(--muted);font-size:12px;">
-  SpecLock v5.2.5 &mdash; Developed by Sandeep Roy &mdash; <a href="https://github.com/sgroy10/speclock" style="color:var(--accent)">GitHub</a>
+  SpecLock v5.3.0 &mdash; Developed by Sandeep Roy &mdash; <a href="https://github.com/sgroy10/speclock" style="color:var(--accent)">GitHub</a>
 </div>
 
 <script>