speclock 1.4.1 → 1.5.1

package/README.md

@@ -76,7 +76,7 @@ Or run it yourself:
 npx speclock setup --goal "Build my app"
 ```
 
-**That's it.** The AI reads `SPECLOCK.md`, follows the rules, and uses CLI commands. Tested on Bolt.new — the AI ran 17 commands automatically on first install, setting up goals, locks, and decisions without any configuration.
+**That's it.** SpecLock creates `SPECLOCK.md`, injects a marker into `package.json`, and generates `.speclock/context/latest.md`. The AI reads these automatically and follows the rules. When the AI returns in a new session, it sees the SpecLock marker in `package.json` and knows to check the rules before making changes.
 
 ### Lovable (MCP Remote — No Install)
 
@@ -287,4 +287,4 @@ MIT License - see [LICENSE](LICENSE) file.
 
 ---
 
-*SpecLock v1.3.1 — Because remembering isn't enough. AI needs to respect boundaries.*
+*SpecLock v1.5.0 — Because remembering isn't enough. AI needs to respect boundaries.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speclock",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "description": "AI constraint engine — MCP server + CLI with active enforcement. Memory + guardrails for AI coding tools. Works with Bolt.new, Claude Code, Cursor, Lovable.",
   "type": "module",
   "main": "src/mcp/server.js",

package/src/cli/index.js

@@ -13,6 +13,7 @@ import {
   createSpecLockMd,
   guardFile,
   unguardFile,
+  injectPackageJsonMarker,
 } from "../core/engine.js";
 import { generateContext } from "../core/context.js";
 import { readBrain } from "../core/storage.js";
@@ -71,7 +72,7 @@ function refreshContext(root) {
 
 function printHelp() {
   console.log(`
-SpecLock v1.4.0 — AI Constraint Engine
+SpecLock v1.5.0 — AI Constraint Engine
 Developed by Sandeep Roy (github.com/sgroy10)
 
 Usage: speclock <command> [options]
@@ -181,18 +182,25 @@ async function main() {
     const mdPath = createSpecLockMd(root);
     console.log(`Created SPECLOCK.md (AI instructions file).`);
 
-    // 4. Generate context
+    // 4. Inject marker into package.json (so AI tools auto-discover SpecLock)
+    const pkgResult = injectPackageJsonMarker(root);
+    if (pkgResult.success) {
+      console.log("Injected SpecLock marker into package.json.");
+    }
+
+    // 5. Generate context
     generateContext(root);
     console.log("Generated .speclock/context/latest.md");
 
-    // 5. Print summary
+    // 6. Print summary
     console.log(`
 SpecLock is ready!
 
-Files created:
+Files created/updated:
   .speclock/brain.json          — Project memory
   .speclock/context/latest.md   — Context for AI (read this)
   SPECLOCK.md                   — AI rules (read this)
+  package.json                  — SpecLock marker added (AI auto-discovery)
 
 Next steps:
   The AI should read SPECLOCK.md for rules and
@@ -210,8 +218,9 @@ Next steps:
   if (cmd === "init") {
     ensureInit(root);
     createSpecLockMd(root);
+    injectPackageJsonMarker(root);
     generateContext(root);
-    console.log("SpecLock initialized. Created SPECLOCK.md and context file.");
+    console.log("SpecLock initialized. Created SPECLOCK.md, updated package.json, and generated context file.");
     return;
   }
 

package/src/core/engine.js

@@ -702,68 +702,91 @@ export async function watchRepo(root) {
 export function createSpecLockMd(root) {
   const mdContent = `# SpecLock — AI Constraint Engine Active
 
-## STOP — Read this before doing ANYTHING.
+## CRITICAL: LOCKED FILES CANNOT BE MODIFIED
 
-**If a file contains "SPECLOCK-GUARD" at the top → DO NOT EDIT IT. Period.**
+If a lock says "never modify auth files" then you CANNOT modify those files.
+Not now. Not later. Not if the user asks a question. Not for any reason.
 
-## Your Job (Do This Automatically — The User Will NOT Ask)
+**The ONLY way to modify a locked file:** The user must explicitly say "unlock" or "remove the lock."
+Asking a question is NOT permission. Talking about a feature is NOT permission.
+ONLY the words "unlock", "remove the lock", or "I changed my mind about the lock" count.
 
-### On EVERY message:
-Read \`.speclock/context/latest.md\` first. Always. No exceptions.
+**If a file contains "SPECLOCK-GUARD" at the top → DO NOT EDIT IT. No exceptions.**
 
-### Before changing ANY code:
-Run \`npx speclock check "what you plan to do"\` BEFORE writing code.
-If conflict → STOP. Tell the user. Do NOT proceed.
+## On EVERY message — do this FIRST:
 
-### Detect constraints from natural language:
-Users will NOT say "lock this." They speak naturally. YOU must detect it.
+1. Read \`.speclock/context/latest.md\` for project memory
+2. Run \`npx speclock check "what you plan to do"\` BEFORE any code changes
+3. If conflict found → STOP. Tell user. Do NOT proceed. Do NOT ask "should I proceed?"
+4. Wait for user to explicitly say "unlock" or "remove the lock" before touching locked files
 
-Examples of what users say → what you do:
+## Returning to This Project? (New Chat Session)
+
+SpecLock is ALREADY installed. Do NOT reinstall it. Do NOT say "it's not installed."
+1. Run \`npx speclock status\` to see current locks and decisions
+2. Read \`.speclock/context/latest.md\` for full project context
+3. Respect ALL existing locks — they carry over between sessions
+
+## What Counts as Permission to Bypass a Lock?
+
+| User says | Is this permission? | What you do |
+|-----------|-------------------|-------------|
+| "add google auth" | NO — lock still active | Say "Auth files are locked. Want me to unlock them first?" |
+| "is speclock initialized?" | NO — just a question | Answer the question. Do NOT change any code. |
+| "yeah go ahead" (after you warned about lock) | NO — too vague | Say "To modify locked files, please confirm: unlock the auth files" |
+| "ok unlock the auth files" | YES — explicit unlock | Run \`npx speclock lock remove <lockId>\`, then make changes |
+| "remove the lock on auth" | YES — explicit unlock | Run \`npx speclock lock remove <lockId>\`, then make changes |
+| "I changed my mind, you can edit auth" | YES — explicit unlock | Run \`npx speclock lock remove <lockId>\`, then make changes |
+
+**When in doubt: DO NOT modify locked files. Ask for clarification instead.**
+
+## Detect Constraints from Natural Language
+
+Users will NOT say "lock this." They speak naturally. YOU must detect intent and lock automatically.
 
 | User says | You do |
 |-----------|--------|
-| "don't touch the auth" | \`npx speclock lock "Never modify auth files"\` + \`npx speclock guard src/components/Auth.tsx --lock "Never modify auth files"\` |
+| "don't touch the auth" | \`npx speclock lock "Never modify auth files"\` + \`npx speclock guard\` the auth files |
 | "database is firebase, don't change it" | \`npx speclock lock "Database must always be Firebase"\` |
-| "leave the payment system alone" | \`npx speclock lock "Never modify payment system"\` + guard the payment files |
+| "leave the payment system alone" | \`npx speclock lock "Never modify payment system"\` + guard payment files |
 | "always use Supabase" | \`npx speclock lock "Always use Supabase"\` |
-| "the API is done, don't mess with it" | \`npx speclock lock "Never modify API endpoints"\` + guard the API files |
+| "the API is done, don't mess with it" | \`npx speclock lock "Never modify API endpoints"\` + guard API files |
 
 When you lock something, ALSO guard the specific files:
 \`npx speclock guard <filepath> --lock "the constraint"\`
-This injects a warning directly into the file so it cannot be missed.
 
-### When user wants to change something locked:
-User might say "actually, let me change auth" or "ok modify the database."
-1. Warn: "This is currently locked: [constraint]. Want me to unlock?"
-2. If they confirm → \`npx speclock lock remove <lockId>\` + \`npx speclock unguard <file>\`
+## Unlocking (When User Gives Explicit Permission)
+
+1. User says "unlock auth" or "remove the auth lock" or "I changed my mind about auth"
+2. Run \`npx speclock lock remove <lockId>\` + \`npx speclock unguard <file>\`
 3. Make the changes
-4. Ask if they want to re-lock: "Want me to lock this again?"
+4. Ask: "Want me to re-lock this?"
 
-### After building something:
-\`npx speclock log-change "what you built" --files file1.tsx,file2.ts\`
+## After Building Something
 
-### When a tech decision is made:
-\`npx speclock decide "the decision"\`
+\`npx speclock log-change "what you built" --files file1.tsx,file2.ts\`
 
 ## Commands
 
 \`\`\`bash
+npx speclock status                              # Check current state
 npx speclock check "what you plan to do"         # ALWAYS RUN BEFORE CHANGES
 npx speclock lock "constraint"                   # Lock a constraint
 npx speclock guard <file> --lock "constraint"    # Protect a specific file
 npx speclock unguard <file>                      # Remove file protection
-npx speclock lock remove <lockId>                # Unlock a constraint
+npx speclock lock remove <lockId>                # Unlock (only after explicit permission)
 npx speclock log-change "what changed"           # Log changes
 npx speclock decide "decision"                   # Record a decision
 npx speclock context                             # Refresh context file
-npx speclock status                              # See project summary
 \`\`\`
 
-## Key Rule
+## Key Rules
 
-**The user will NEVER tell you to run these commands. You run them automatically.**
-**The user will NEVER say "lock this." You detect the intent and lock it yourself.**
-**The user will NEVER say "check constraints." You check before EVERY code change.**
+1. **A question is NOT permission to bypass a lock.**
+2. **Run speclock check before EVERY code change, EVERY time, EVERY message.**
+3. **If you already warned about a conflict, the lock is STILL active until explicitly removed.**
+4. **The user will NEVER tell you to run these commands. You run them automatically.**
+5. **If this file exists, SpecLock is installed. Do NOT reinstall.**
 `;
   const filePath = path.join(root, "SPECLOCK.md");
   fs.writeFileSync(filePath, mdContent);
@@ -811,9 +834,11 @@ export function guardFile(root, relativeFilePath, lockText) {
   const warningLines = [
     `${style.start}${"=".repeat(60)}${style.end || ""}`,
     `${style.start}${GUARD_TAG} — DO NOT MODIFY THIS FILE${style.end || ""}`,
-    `${style.start}LOCKED BY SPECLOCK: ${lockText}${style.end || ""}`,
-    `${style.start}Run "npx speclock check" before ANY changes to this file.${style.end || ""}`,
-    `${style.start}If you modify this file, you are VIOLATING a project constraint.${style.end || ""}`,
+    `${style.start}LOCKED: ${lockText}${style.end || ""}`,
+    `${style.start}THIS FILE IS LOCKED. DO NOT EDIT, CHANGE, OR REWRITE ANY PART OF IT.${style.end || ""}`,
+    `${style.start}The user must say "unlock" before this file can be changed.${style.end || ""}`,
+    `${style.start}A question is NOT permission. Asking about features is NOT permission.${style.end || ""}`,
+    `${style.start}ONLY "unlock" or "remove the lock" is permission to edit this file.${style.end || ""}`,
     `${style.start}${"=".repeat(60)}${style.end || ""}`,
     "",
   ];
@@ -824,6 +849,34 @@ export function guardFile(root, relativeFilePath, lockText) {
   return { success: true };
 }
 
+// --- Package.json marker injection (makes Bolt.new auto-discover SpecLock) ---
+
+export function injectPackageJsonMarker(root) {
+  const pkgPath = path.join(root, "package.json");
+  if (!fs.existsSync(pkgPath)) {
+    return { success: false, error: "No package.json found in project root." };
+  }
+
+  try {
+    const raw = fs.readFileSync(pkgPath, "utf-8");
+    const pkg = JSON.parse(raw);
+
+    // Add speclock marker
+    pkg.speclock = {
+      active: true,
+      rules: "IMPORTANT: Read SPECLOCK.md before making ANY changes to this project. Read .speclock/context/latest.md for project memory, goals, locks, and decisions. Run 'npx speclock check' before modifying locked files.",
+    };
+
+    // Write back with same formatting
+    const indent = raw.match(/^(\s+)/m)?.[1] || "  ";
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + "\n");
+
+    return { success: true };
+  } catch (err) {
+    return { success: false, error: `Failed to modify package.json: ${err.message}` };
+  }
+}
+
 export function unguardFile(root, relativeFilePath) {
   const fullPath = path.join(root, relativeFilePath);
   if (!fs.existsSync(fullPath)) {