speclock 1.4.0 → 1.5.0

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.0",
+  "version": "1.5.0",
   "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,54 +702,85 @@ export async function watchRepo(root) {
 export function createSpecLockMd(root) {
   const mdContent = `# SpecLock — AI Constraint Engine Active
 
-## MANDATORY: Read this BEFORE doing anything.
+## STOP — Read this before doing ANYTHING.
 
-This project uses **SpecLock** for AI constraint enforcement.
+This project has SpecLock installed. It tracks project memory, goals, constraints (locks), and decisions.
 
-**STOP. Before writing or modifying ANY code, you MUST:**
-1. Read \`.speclock/context/latest.md\` for project memory
-2. Run \`npx speclock check "what you plan to change"\`
-3. If conflict found → STOP and warn the user
+**Step 1:** Read \`.speclock/context/latest.md\` — this contains the full project memory.
+**Step 2:** Follow ALL rules below on every message.
 
-**If a file starts with "SPECLOCK-GUARD — DO NOT MODIFY" → DO NOT EDIT IT.**
+**If a file contains "SPECLOCK-GUARD" at the top → DO NOT EDIT IT. Period.**
 
-## Rules (MANDATORY — every message, no exceptions)
+## Returning to This Project? (New Chat Session)
 
-1. **FIRST ACTION OF EVERY MESSAGE**: Read \`.speclock/context/latest.md\`. This contains all project constraints (locks), decisions, and goals. Show: "Memory loaded — X locks, Y decisions." If the file doesn't exist, run \`npx speclock context\`.
+If you are starting a new chat on this project:
+1. SpecLock is ALREADY installed — do NOT reinstall it
+2. The \`.speclock/\` directory contains all project memory
+3. Run \`npx speclock status\` to see the current state
+4. Read \`.speclock/context/latest.md\` for full context (goals, locks, decisions, history)
+5. Respect ALL existing locks and constraints before making any changes
 
-2. **BEFORE MODIFYING ANY CODE — EVERY TIME**: Run \`npx speclock check "description of what you plan to change"\`. If a conflict is found (HIGH confidence), STOP IMMEDIATELY. Tell the user which constraint would be violated. Do NOT proceed unless the user explicitly overrides. THIS IS THE MOST IMPORTANT RULE.
+**DO NOT say "SpecLock is not installed" — if you can read this file, it IS installed.**
 
-3. **WHEN USER SAYS "lock this", "never touch", "don't change", "always", "critical"**: Run \`npx speclock lock "the exact constraint"\`. Then run \`npx speclock guard <file> --lock "constraint"\` on the specific files to inject a lock warning directly into the file. Confirm: "Locked: [constraint]"
+## Your Job (Do This Automatically — The User Will NOT Ask)
 
-4. **AFTER COMPLETING A FEATURE OR CHANGE**: Run \`npx speclock log-change "what was built" --files file1.tsx,file2.ts\`.
+### On EVERY message:
+Read \`.speclock/context/latest.md\` first. Always. No exceptions.
 
-5. **WHEN AN ARCHITECTURAL DECISION IS MADE**: Run \`npx speclock decide "the decision"\`
+### 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.
 
-6. **WHEN USER WANTS TO CHANGE SOMETHING LOCKED**: Warn first. If confirmed, run \`npx speclock lock remove <lockId>\` and \`npx speclock unguard <file>\` to remove the file guard.
+### Detect constraints from natural language:
+Users will NOT say "lock this." They speak naturally. YOU must detect it.
 
-## Quick Reference
+Examples of what users say → what you do:
+
+| 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"\` |
+| "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 |
+| "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 |
+
+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>\`
+3. Make the changes
+4. Ask if they want to re-lock: "Want me to lock this again?"
+
+### After building something:
+\`npx speclock log-change "what you built" --files file1.tsx,file2.ts\`
+
+### When a tech decision is made:
+\`npx speclock decide "the decision"\`
+
+## Commands
 
 \`\`\`bash
-npx speclock check "what you plan to do"         # CHECK BEFORE CHANGES
-npx speclock lock "constraint text"              # Add a constraint
-npx speclock guard src/Auth.tsx --lock "text"    # Inject lock into file
-npx speclock unguard src/Auth.tsx                # Remove file lock
-npx speclock lock remove <lockId>                # Remove a constraint
-npx speclock log-change "what changed"           # Log a change
-npx speclock decide "decision text"              # Record a decision
-npx speclock context                             # Regenerate context file
-npx speclock status                              # See brain summary
+npx speclock status                              # CHECK IF ALREADY SET UP
+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 log-change "what changed"           # Log changes
+npx speclock decide "decision"                   # Record a decision
+npx speclock context                             # Refresh context file
 \`\`\`
 
-## How It Works
-
-SpecLock maintains a \`.speclock/\` directory with structured project memory:
-- \`brain.json\` — goals, locks, decisions, session history
-- \`events.log\` — immutable audit trail
-- \`context/latest.md\` — human-readable context (read this!)
+## Key Rule
 
-**Guarded files** have a lock warning header injected directly into the source code.
-When you see "SPECLOCK-GUARD" at the top of a file, that file is LOCKED.
+**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.**
+**If this file exists, SpecLock is installed. Do NOT reinstall. Just read the context and follow the rules.**
 `;
   const filePath = path.join(root, "SPECLOCK.md");
   fs.writeFileSync(filePath, mdContent);
@@ -810,6 +841,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)) {