@manukyalo/scopelock 2.2.0 → 3.0.0

package/README.md

@@ -1,4 +1,4 @@
-# scopelock
+# scopelock v3.0
 
 **Anti-hallucination scope locking for AI coding agents.**
 
@@ -12,86 +12,101 @@ npm install -g @manukyalo/scopelock
 
 ## Features
 
-- **File-level locks**: Run `scopelock lock src/auth.ts` to make the file read-only for agents.
-- **Function-level locks**: Don't want to lock the whole file? Lock specific AST functions so agents can only edit adjacent code.
-- **Dependency Lockdown**: Zero-trust dependency management. Automatically locks `package.json` and other dependency manifests on init to prevent silent dependency drift.
+- **File & Function Locks**: Run `scopelock lock src/auth.ts` or `scopelock lock src/auth.ts:validateToken` to make code read-only for agents.
+- **Production Path Locks (Seal)**: Use `scopelock seal` for critical paths like billing. Agents cannot override this; it requires explicit human sign-off via `scopelock unseal --human-approved=<ticket>`.
+- **Blast Radius Map**: Prevent scope creep *before* it happens. Run `scopelock impact <file>` to see every file that imports a target file before you touch it.
+- **Dependency Lockdown**: Zero-trust dependency management. Automatically locks `package.json` on init to prevent silent dependency drift.
 - **Secret Sentinel**: A hard-blocking pre-commit scanner that physically prevents agents from committing AWS keys, Stripe tokens, or `.env` leaks.
-- **Zero dependencies**: Written in pure Node.js. Install it anywhere without bloating your `node_modules`.
+- **Test Coverage Gate**: Run `scopelock guard --tests` to block any source code changes that aren't accompanied by tests.
+- **Rollback Snapshots**: Run `scopelock save` before an agent starts working, and `scopelock restore` to obliterate any rogue changes instantly.
 
 ---
 
 ## Commands
 
 ```bash
-  scopelock init                           Scan repo and generate .scopelock.json
-  scopelock lock <file>[:<func>] [reason]  Lock a file or a specific function
-  scopelock unlock <file>[:<func>] <reason> Unlock (reason is mandatory)
-  scopelock allow-secret <file> <reason>   Bypass Secret Sentinel for a specific file
-  scopelock context [task]                 Generate AI context block for a task
-  scopelock check                          Check git diff for scope violations and secret leaks
-  scopelock status                         Show manifest summary
+  scopelock init                                    Scan repo and generate .scopelock.json
+  scopelock lock <file>[:<func>] [reason]           Lock a file or a specific function
+  scopelock unlock <file>[:<func>] <reason>          Unlock (reason is mandatory)
+  scopelock seal <file> <reason>                    Permanent production-path lock (no override)
+  scopelock unseal <file> --human-approved=<ticket> <reason>  Release a seal
+  scopelock impact <file>                           Show all files that import this file
+  scopelock trust <file> <reason>                   Bypass Secret Sentinel for a specific file
+  scopelock save                                    Auto-snapshot repo state before an agent session
+  scopelock restore                                 Rollback to the last snapshot
+  scopelock context [task]                          Generate AI context block for a task
+  scopelock guard [--tests]                         Check git diff for violations and secret leaks
+  scopelock status                                  Show manifest summary
 ```
 
-### `scopelock init`
-Scan the repo and generate `.scopelock.json`. Automatically ignores `node_modules`, `.git`, `.next`, `dist`, `build`, `out`, `coverage`, and other build artifacts.
-
-### `scopelock lock <file>[:<function>] [reason]`
-Lock a whole file or a specific named function.
+### `scopelock lock` & `unlock`
+Lock a whole file or a specific named function. Unlock requires a reason that gets logged to history.
 
 ```bash
-# Lock a whole file
 scopelock lock src/lib/supabase.ts "production client — stable"
-
-# Lock a specific function (validates it exists before locking)
 scopelock lock src/auth/token.ts:validateToken "tested — do not touch"
+scopelock unlock src/auth/token.ts:validateToken "fixing JWT expiry edge case"
 ```
 
-### `scopelock unlock <file>[:<function>] <reason>`
-Unlock a file or function. Reason is mandatory and logged.
+### `scopelock seal` & `unseal`
+For files that should *never* be touched without human oversight (e.g., `/billing`, `/migrations`). Seals cannot be removed by `unlock`.
 
 ```bash
-scopelock unlock src/auth/token.ts:validateToken "fixing JWT expiry edge case"
+scopelock seal src/billing/stripe.ts "core billing logic"
+scopelock unseal src/billing/stripe.ts --human-approved=PR-123 "updating webhook"
 ```
 
-### `scopelock allow-secret <file> <reason>`
-Bypass the Secret Sentinel hard-block for a specific file (e.g., when intentionally committing a mock test key).
+### `scopelock impact`
+Before making a change, see the blast radius. Outputs a list of all files in the repository that import the target file.
 
 ```bash
-scopelock allow-secret test/run.js "this is a mock stripe key for testing"
+scopelock impact src/utils/auth.ts
 ```
 
-### `scopelock check`
-Two-tier scope violation check against `git diff HEAD`. Exits non-zero on violations or secret leaks. Wire this up as a `pre-commit` hook.
+### `scopelock guard`
+Two-tier scope violation check against `git diff HEAD`. Exits non-zero on violations or secret leaks. Wire this up as a `pre-commit` hook. Add `--tests` to strictly enforce test coverage for any changed logic.
 
 ```bash
-scopelock check
+scopelock guard
+scopelock guard --tests
 ```
 
-### `scopelock context [task]`
-Output a token-efficient AI context block with all locks clearly flagged.
+### `scopelock save` & `restore`
+Never fear an agent hallucination destroying your workspace again. `save` stores a snapshot in git stash that survives hard resets. `restore` obliterates the working directory and cleanly reverts to the snapshot.
 
 ```bash
-scopelock context "Update the login page"
+scopelock save
+scopelock restore
 ```
+
+### `scopelock trust`
+Bypass the Secret Sentinel hard-block for a specific file (e.g., when intentionally committing a mock test key).
+
+```bash
+scopelock trust test/run.js "this is a mock stripe key for testing"
 ```
-[SCOPE CONTEXT]
-Task: Update the login page
 
-Status:
-  🔒 locked   — 1 file(s)
-  ✏️ active   — 0 file(s)
-  ⬜ unscoped — 14 file(s)
+### `scopelock context`
+Output a token-efficient AI context block with all locks clearly flagged for the agent's system prompt.
 
-Locked files:
-  src/lib/supabase.ts
+```bash
+scopelock context "Update the login page"
 ```
 
-## Agent Skill
+## Agent Skills (Godmode)
+
+`scopelock` ships with 7 native AI Agent Skills located in the `skills/` folder. 
+If you use an agent framework (like Antigravity or Cline) that supports Markdown skills, point it to these folders to automatically teach the agent how to use `scopelock` safely.
 
-`scopelock` includes a native Agent Skill. 
-If you use an agent framework (like Antigravity or Cline) that supports Markdown skills, point it to `skills/scope-enforcement/SKILL.md` to automatically teach the agent how to use `scopelock` safely.
+The skills map directly to features:
+- `scope-enforcement`
+- `dependency-lockdown`
+- `secret-sentinel`
+- `test-coverage-gate`
+- `rollback-snapshot`
+- `blast-radius`
+- `production-path-lock`
 
 ## Data Model
 All state is stored in `.scopelock.json` at the root of your repo.
-
 The manifest is project state, not a personal config. Commit it so your whole team — and all their AI agents — share the same scope boundaries.

package/bin/scopelock.js

@@ -17,6 +17,7 @@ const { execSync } = require('child_process');
 const manifest = require('../src/manifest');
 const context  = require('../src/context');
 const git      = require('../src/git');
+const blast    = require('../src/blast');
 
 const [,, command, ...args] = process.argv;
 
@@ -54,26 +55,60 @@ switch (command) {
     break;
   }
 
-  case 'check':
-    git.check(args);
+  case 'guard':
+    git.guard(args);
     break;
 
   case 'status':
     manifest.status();
     break;
 
-  case 'allow-secret': {
+  case 'impact': {
+    const target = args[0];
+    if (!target) {
+      console.error('Usage: scopelock impact <file>');
+      process.exit(1);
+    }
+    blast.printBlastRadius(target);
+    break;
+  }
+
+  case 'seal': {
+    const target = args[0];
+    const reason = args.slice(1).join(' ') || 'production path — seal applied';
+    if (!target) {
+      console.error('Usage: scopelock seal <file> <reason>');
+      process.exit(1);
+    }
+    manifest.seal(target, reason);
+    break;
+  }
+
+  case 'unseal': {
+    const target = args[0];
+    const ticketArg = args.find(a => a.startsWith('--human-approved='));
+    const ticket = ticketArg ? ticketArg.replace('--human-approved=', '') : null;
+    const reason = args.filter(a => !a.startsWith('--')).slice(1).join(' ');
+    if (!target || !ticket || !reason) {
+      console.error('Usage: scopelock unseal <file> --human-approved=<ticket> <reason>');
+      process.exit(1);
+    }
+    manifest.unseal(target, ticket, reason);
+    break;
+  }
+
+  case 'trust': {
     const target = args[0];
     const reason = args.slice(1).join(' ');
     if (!target || !reason) {
-      console.error('Usage: scopelock allow-secret <file> <reason>');
+      console.error('Usage: scopelock trust <file> <reason>');
       process.exit(1);
     }
-    manifest.allowSecret(target, reason);
+    manifest.trust(target, reason);
     break;
   }
 
-  case 'snapshot': {
+  case 'save': {
     try {
       const ts = new Date().toISOString().replace(/[:.]/g, '-');
       const manifestObj = manifest.getManifest();
@@ -94,7 +129,7 @@ switch (command) {
       }
 
       manifest.saveManifest(manifestObj);
-      console.log(`✅ Snapshot created. Run 'scopelock revert' to obliterate agent changes and restore this state.`);
+      console.log(`✅ Snapshot created. Run 'scopelock restore' to obliterate agent changes and restore this state.`);
     } catch (e) {
       console.error('Failed to create snapshot.', e.stderr || e.message);
       process.exit(1);
@@ -102,11 +137,11 @@ switch (command) {
     break;
   }
 
-  case 'revert': {
+  case 'restore': {
     try {
       const manifestObj = manifest.getManifest();
       if (!manifestObj.lastSnapshot) {
-        console.error('❌ No snapshot found. Run `scopelock snapshot` first.');
+        console.error('❌ No snapshot found. Run `scopelock save` first.');
         process.exit(1);
       }
       console.log(`Obliterating agent mess...`);
@@ -136,15 +171,18 @@ switch (command) {
 scopelock — Anti-hallucination scope locking for AI coding agents.
 
 Usage:
-  scopelock init                           Scan repo and generate .scopelock.json
-  scopelock lock <file>[:<func>] [reason]  Lock a file or a specific function
-  scopelock unlock <file>[:<func>] <reason> Unlock (reason is mandatory)
-  scopelock allow-secret <file> <reason>   Bypass Secret Sentinel for a specific file
-  scopelock context [task]                 Generate AI context block for a task
-  scopelock snapshot                       Auto-snapshot repo state before an agent session
-  scopelock revert                         Rollback to the last snapshot
-  scopelock check [--require-tests]        Check git diff for violations and test coverage
-  scopelock status                         Show manifest summary
+  scopelock init                                    Scan repo and generate .scopelock.json
+  scopelock lock <file>[:<func>] [reason]           Lock a file or a specific function
+  scopelock unlock <file>[:<func>] <reason>          Unlock (reason is mandatory)
+  scopelock seal <file> <reason>                    Permanent production-path lock (no override)
+  scopelock unseal <file> --human-approved=<ticket> <reason>  Release a seal
+  scopelock impact <file>                           Show all files that import this file
+  scopelock trust <file> <reason>                   Bypass Secret Sentinel for a specific file
+  scopelock save                                    Auto-snapshot repo state before an agent session
+  scopelock restore                                 Rollback to the last snapshot
+  scopelock context [task]                          Generate AI context block for a task
+  scopelock guard [--tests]                         Check git diff for violations and secret leaks
+  scopelock status                                  Show manifest summary
 
 
 Examples:
@@ -152,7 +190,7 @@ Examples:
   scopelock lock src/auth.ts:validateToken "stable — do not touch"
   scopelock unlock src/auth.ts:validateToken "need to fix JWT expiry bug"
   scopelock context "Fix the broken checkout flow"
-  scopelock check
+  scopelock guard
     `);
     process.exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manukyalo/scopelock",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "description": "Anti-hallucination scope locking for AI coding agents.",
   "main": "bin/scopelock.js",
   "bin": {

package/skills/blast-radius/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: blast-radius-map
+description: "Godmode Skill: Before modifying any file, run 'scopelock impact <file>' to see every other file that imports it. Prevents scope creep by making the full impact of a change visible BEFORE the agent writes a single line."
+---
+
+## Overview
+
+An AI agent can't know what it doesn't know. If it modifies `src/utils/auth.ts` without understanding that 14 other files import it, it has no idea if the function signature change it's making will cascade into 14 broken components.
+
+This skill instructs the agent to **check before it touches**, not after.
+
+## Agent Protocol
+
+### MANDATORY: Before editing any file
+
+1. Run the blast radius check first:
+   ```bash
+   scopelock impact src/utils/auth.ts
+   ```
+
+2. Read the output:
+   ```
+   💥  Blast Radius: src/utils/auth.ts
+
+      7 file(s) directly import this file:
+
+      → src/pages/login.tsx
+      → src/pages/register.tsx
+      → src/api/session.ts
+      → src/middleware.ts
+      → src/hooks/useUser.ts
+      → test/auth.test.ts
+      → test/session.test.ts
+
+      ⚠️  Modifying 'src/utils/auth.ts' may impact all 7 of the above file(s).
+   ```
+
+3. **Assess the risk** based on what you see:
+   - **0 dependents** → safe to modify freely.
+   - **1–5 dependents** → proceed carefully, check each dependent after your change.
+   - **6+ dependents** → this is a high-blast-radius file. Consider locking it and building a new abstraction instead of modifying it directly.
+
+4. If you decide to proceed, lock all other files first:
+   ```bash
+   scopelock lock src/pages/login.tsx "blast radius protection"
+   scopelock lock src/middleware.ts "blast radius protection"
+   # ... etc
+   ```
+
+5. Make your change to the target file only.
+
+6. Run `scopelock guard` to verify no locked files were touched.
+
+## Why this exists
+
+The most expensive bugs come from changes that seemed small but weren't. This skill makes the full impact of every change explicit before the agent commits to it.

package/skills/dependency-lockdown/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: dependency-lockdown
+description: "Godmode Skill: Prevents AI agents from silently adding or upgrading npm/pip/cargo packages. Dependency manifest files (package.json, requirements.txt, etc.) are automatically locked by scopelock on init. Any diff touching these files will fail scopelock guard until explicitly unlocked with a reason."
+---
+
+## Overview
+
+Dependency drift is one of the most common and expensive agent mistakes. An agent trying to fix one bug will silently add 12 packages, bloat the bundle, and introduce unknown vulnerabilities. This skill makes that impossible.
+
+## How it Works
+
+On `scopelock init`, the following files are **automatically locked** without any manual action required:
+- `package.json`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
+- `requirements.txt`, `Pipfile`, `Pipfile.lock`, `poetry.lock`
+- `Cargo.toml`, `Cargo.lock`, `go.mod`, `go.sum`
+
+## Agent Protocol
+
+### When you need to add a dependency:
+1. You MUST explicitly unlock the manifest first with a clear reason:
+   ```bash
+   scopelock unlock package.json "adding zod for runtime validation of API responses"
+   ```
+2. Make your change (add the dependency to the manifest).
+3. Run `scopelock guard` to confirm the change is authorized.
+4. Re-lock the manifest immediately after:
+   ```bash
+   scopelock lock package.json "dependencies updated and reviewed"
+   ```
+
+### When you do NOT need a new dependency:
+- If you find yourself reaching for a new package, stop and ask: can this be solved with a built-in or existing dependency?
+- The lock exists to force that question before the decision is made.
+
+## Why this exists
+
+Agents never "just need one package." Every dependency is a long-term maintenance cost, a security surface, and a potential supply chain attack vector. This skill enforces that every dependency addition is a deliberate, logged, human-approved decision.

package/skills/production-path-lock/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: production-path-lock
+description: "Godmode Skill: A permanent, override-resistant lock for critical production paths like /auth, /billing, /migrations. Regular 'scopelock unlock' cannot bypass it. Requires a second human's explicit sign-off via 'scopelock unseal' with a ticket."
+---
+
+## Overview
+
+Some files must never be touched by an AI agent without explicit human sign-off. Your `/auth` logic, billing handlers, and database migration files are not negotiable. A `seal` makes this a physical constraint, not a policy.
+
+A sealed file cannot be overridden by `scopelock unlock`. The agent must stop, escalate to a human, and provide a traceable ticket before any modification is allowed.
+
+## Recommended Files to Seal on Every Project
+
+```bash
+# Authentication
+scopelock seal src/auth/token.ts "core auth — requires senior review"
+scopelock seal src/middleware/auth.ts "core auth — requires senior review"
+
+# Billing & Payments
+scopelock seal src/billing/stripe.ts "billing — requires finance team approval"
+scopelock seal src/billing/webhooks.ts "billing — requires finance team approval"
+
+# Database Migrations
+scopelock seal migrations/ "schema changes — requires DBA review"
+
+# Security-critical config
+scopelock seal .env.production "production secrets — never touch"
+```
+
+## Agent Protocol
+
+### When you encounter a sealed file:
+```
+❌ 'src/auth/token.ts' is SEALED and cannot be unlocked with 'scopelock unlock'.
+   This path is a protected production route.
+   Use: scopelock unseal src/auth/token.ts --human-approved=<ticket> <reason>
+```
+
+1. **STOP.** Do not attempt to work around the lock.
+2. **Escalate.** Tell the human you cannot proceed without their explicit approval.
+3. **The human must run:**
+   ```bash
+   scopelock unseal src/auth/token.ts --human-approved=JIRA-123 "fixing JWT expiry bug approved in PR-456"
+   ```
+4. Only after you see the `UNSEALED` confirmation may you proceed.
+5. Re-seal the file immediately after your change is committed:
+   ```bash
+   scopelock seal src/auth/token.ts "re-locked after JWT fix — JIRA-123"
+   ```
+
+## The Audit Trail
+
+Every `unseal` is permanently logged in `.scopelock.json` with:
+- The timestamp
+- The human-approved ticket number
+- The full reason string
+
+This creates a traceable, auditable record of every time a production path was modified — essential for SOC2, GDPR, and any compliance review.
+
+## Why this exists
+
+`locked` is a request. `sealed` is a wall. Some files need a wall.

package/skills/rollback-snapshot/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: rollback-snapshot
+description: "Godmode Skill: Creates a one-command safety net before every agent session. If the agent goes rogue, a single command obliterates all changes and perfectly restores the repository to its pre-session state."
+---
+
+## Overview
+
+Before you let an agent loose on a codebase, you need a guaranteed escape hatch. `scopelock save` creates that escape hatch using git's native stash mechanism. It is instant, requires no external tools, and can restore the repo to its exact pre-session state in under one second.
+
+## How Storage Works
+
+- The snapshot is stored in **git's local stash** (`.git/refs/stash`) — it never leaves your machine and is never pushed to GitHub.
+- The `.scopelock.json` manifest stores a pointer (`lastSnapshot: "dirty" | "clean"`) so `scopelock restore` knows what to restore.
+- If you clone the repo on a new machine, the snapshot is gone — this is correct. Snapshots are session-scoped, not repository-scoped.
+
+## Agent Protocol
+
+### At the start of EVERY agent session:
+```bash
+scopelock save
+```
+This is the first command you run, before writing a single line of code.
+
+### If the session goes well:
+Simply commit your work normally. The stash will remain in git until git's garbage collection cleans it up automatically (default: 90 days).
+
+### If the agent goes rogue:
+```bash
+scopelock restore
+```
+This command:
+1. Runs `git reset --hard HEAD` — obliterates all tracked file changes.
+2. Runs `git clean -fd` — deletes all untracked files the agent created.
+3. Pops the stash — restores your working tree to the exact state at snapshot time.
+
+## When to Use
+
+- Before any multi-file refactor.
+- Before any session where the agent is given broad instructions like "fix all the TypeScript errors."
+- Before any experiment where you are not 100% sure of the outcome.
+
+## Why this exists
+
+`Ctrl+Z` doesn't work across a 45-minute agent session. This skill gives you a time machine.

package/skills/scope-enforcement/SKILL.md

@@ -10,7 +10,7 @@ AI coding agents default to the shortest path to a passing result — which freq
 This skill uses `scopelock` — a zero-dependency Node.js CLI — to enforce two tiers of scope protection:
 
 - **File-level:** An entire file is locked. No agent may touch it.
-- **Function-level:** A specific function within a file is locked. The file may be edited, but that function's body is off-limits. `scopelock check` detects if any changed line falls inside the locked function's boundaries.
+- **Function-level:** A specific function within a file is locked. The file may be edited, but that function's body is off-limits. `scopelock guard` detects if any changed line falls inside the locked function's boundaries.
 
 The skill operates at three checkpoints: **Session Start**, **Pre-Commit**, and **Post-Task Review**.
 
@@ -64,7 +64,7 @@ scopelock lock src/auth/token.ts:validateToken "tested, do not touch"
 
 **Step 4: Run the scope check.**
 ```bash
-scopelock check
+scopelock guard
 ```
 
 Two-tier enforcement:
@@ -87,7 +87,7 @@ git restore <file>
 *Genuinely required change:*
 ```bash
 scopelock unlock src/auth/token.ts:validateToken "fixing JWT expiry edge case"
-scopelock check   # must pass before committing
+scopelock guard   # must pass before committing
 ```
 
 ---
@@ -108,7 +108,7 @@ scopelock lock src/auth/token.ts:validateToken "fixed and re-locked"
 
 ```bash
 echo '#!/bin/sh
-scopelock check' > .git/hooks/pre-commit
+scopelock guard' > .git/hooks/pre-commit
 chmod +x .git/hooks/pre-commit
 ```
 
@@ -123,14 +123,14 @@ chmod +x .git/hooks/pre-commit
 | "The agent said it needed to modify that function." | Then re-evaluate scope, not the lock. If you can't write a specific reason, the modification isn't justified. |
 | "Function-level locking is overkill." | File-level locking doesn't stop an agent from rewriting a critical function inside a file marked `active`. |
 | "The parser didn't detect my function." | Use file-level locking instead. Flag the miss — it's a parser bug, not a reason to skip protection. |
-| "Running `scopelock check` slows my commit flow." | Under 300ms. The alternative is debugging a hallucinated refactor for hours. |
+| "Running `scopelock guard` slows my commit flow." | Under 300ms. The alternative is debugging a hallucinated refactor for hours. |
 | ".scopelock.json shouldn't be committed." | Commit it. It's shared project state — your whole team and their agents benefit. |
 
 ---
 
 ## Red Flags
 
-- `scopelock check` reports violations in more than 2 files — significant scope drift.
+- `scopelock guard` reports violations in more than 2 files — significant scope drift.
 - An unlock entry has a vague reason string (e.g., "fix", "update") — bypassed without thinking.
 - The agent proposes unlocking multiple files at once with one generic reason — batch rationalization.
 - A locked function is reported as `function-missing` after a diff — it was deleted or renamed.
@@ -144,7 +144,7 @@ A session is compliant when ALL of the following are true:
 
 - [ ] `.scopelock.json` exists and `scopelock status` shows the expected locks.
 - [ ] `scopelock context "<task>"` output was injected into the agent before any code was written.
-- [ ] `scopelock check` exits `0` before every commit in this session.
+- [ ] `scopelock guard` exits `0` before every commit in this session.
 - [ ] Every `unlock` entry has a specific, task-justified reason string.
 - [ ] No diff contains modifications to locked files or lines inside locked function bodies that were not explicitly unlocked.
 - [ ] All modified files and functions have been reviewed for re-locking post-task.

package/skills/secret-sentinel/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: secret-sentinel
+description: "Godmode Skill: Physically blocks AI agents from committing API keys, tokens, or .env leaks. scopelock guard scans every added line in the git diff for high-entropy secrets before the commit is allowed. This is a hard block — not a warning."
+---
+
+## Overview
+
+Leaked secrets are the number one cause of production security incidents caused by AI agents. An agent will hardcode an API key to "test something quickly" and forget to remove it. This skill prevents that from ever reaching the repo.
+
+## What Gets Blocked
+
+The Secret Sentinel scans every newly added line for:
+- **AWS Access Keys** (`AKIA...`)
+- **Stripe Secret Keys** (`sk_live_...`, `sk_test_...`)
+- **GitHub Tokens** (`ghp_...`, `ghs_...`)
+- **Slack Tokens** (`xoxb-...`, `xoxs-...`)
+- **Generic hardcoded secrets** (any `api_key = "..."`, `password = "..."`, `token = "..."` with a value 16+ chars long)
+
+## Agent Protocol
+
+### Before every commit:
+```bash
+scopelock guard
+```
+If a secret is detected, you will see:
+```
+❌ VIOLATION: SECRET LEAK [Stripe Secret Key] detected in 'src/api.ts' on line 42.
+```
+
+### How to resolve:
+1. **Remove the secret from the file** — use an environment variable instead:
+   ```ts
+   // WRONG — will be blocked
+   const key = "sk_live_1234abcdefgh";
+   
+   // CORRECT — reads from environment
+   const key = process.env.STRIPE_SECRET_KEY;
+   ```
+2. Add the secret to `.env` (which should be in `.gitignore`).
+3. Add the variable name to `.env.example` so other developers know it exists.
+
+### Intentional exception (mock/test keys only):
+If you are intentionally committing a **mock** key for testing purposes, a human must explicitly authorize it:
+```bash
+scopelock trust test/fixtures/mock.ts "contains a mock stripe key for unit tests — not a real key"
+```
+This bypass is logged permanently in `.scopelock.json` for audit purposes.
+
+## Why this exists
+
+You cannot undo a leaked secret that was pushed to a public GitHub repo. This skill makes leaking a secret a physical impossibility, not a code review catch.

package/skills/test-coverage-gate/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: test-coverage-gate
-description: "Godmode Skill: Forces the AI agent to write or update test files whenever it modifies application logic. Run 'scopelock check --require-tests' before committing to enforce this rule."
+description: "Godmode Skill: Forces the AI agent to write or update test files whenever it modifies application logic. Run 'scopelock guard --tests' before committing to enforce this rule."
 ---
 
 ## Overview
 
 This skill teaches the agent how to navigate the `scopelock` Test Coverage Gate. 
-When `--require-tests` is active, the CLI will hard-block any commit that modifies a source file (`.js`, `.ts`, `.py`, etc.) if a corresponding test file (`.test.ts`, `.spec.js`, `test/`) is not also modified in the same diff.
+When `--tests` is active, the CLI will hard-block any commit that modifies a source file (`.js`, `.ts`, `.py`, etc.) if a corresponding test file (`.test.ts`, `.spec.js`, `test/`) is not also modified in the same diff.
 
 ## Agent Protocol
 
 1. **Before writing code**: If you are about to modify application logic, understand that your changes will be rejected unless you also provide test coverage.
 2. **Write the code**: Implement the requested feature or fix.
 3. **Write the test**: You *must* update the corresponding test file or create a new one. The file path must contain `.test.`, `.spec.`, or be inside a `test/` or `__tests__/` directory.
-4. **Validation**: Run `scopelock check --require-tests` to mathematically verify your diff will pass the coverage gate.
+4. **Validation**: Run `scopelock guard --tests` to mathematically verify your diff will pass the coverage gate.
 5. **Ship**: Only after the test gate is passed are you allowed to commit or mark the task as complete.
 
 ## Why this exists