@manukyalo/scopelock 2.1.0 → 2.3.0

package/bin/scopelock.js

@@ -13,9 +13,11 @@
  *   scopelock status                        Print manifest summary
  */
 
+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,13 +56,47 @@ switch (command) {
   }
 
   case 'check':
-    git.check();
+    git.check(args);
     break;
 
   case 'status':
     manifest.status();
     break;
 
+  case 'blast-radius': {
+    const target = args[0];
+    if (!target) {
+      console.error('Usage: scopelock blast-radius <file>');
+      process.exit(1);
+    }
+    blast.printBlastRadius(target);
+    break;
+  }
+
+  case 'superlock': {
+    const target = args[0];
+    const reason = args.slice(1).join(' ') || 'production path — superlock applied';
+    if (!target) {
+      console.error('Usage: scopelock superlock <file> <reason>');
+      process.exit(1);
+    }
+    manifest.superlock(target, reason);
+    break;
+  }
+
+  case 'sudo-unlock': {
+    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 sudo-unlock <file> --human-approved=<ticket> <reason>');
+      process.exit(1);
+    }
+    manifest.sudoUnlock(target, ticket, reason);
+    break;
+  }
+
   case 'allow-secret': {
     const target = args[0];
     const reason = args.slice(1).join(' ');
@@ -72,18 +108,81 @@ switch (command) {
     break;
   }
 
+  case 'snapshot': {
+    try {
+      const ts = new Date().toISOString().replace(/[:.]/g, '-');
+      const manifestObj = manifest.getManifest();
+
+      // Exclude .scopelock.json from stash — the manifest must survive the snapshot.
+      // On Windows, stash@{0} needs to be quoted.
+      const out = execSync(
+        `git stash push --include-untracked -m "scopelock-snapshot-${ts}" -- . ":(exclude).scopelock.json"`,
+        { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+
+      if (out.includes('No local changes to save')) {
+        manifestObj.lastSnapshot = 'clean';
+      } else {
+        // Re-apply so the working tree is fully restored; stash stays as our savepoint.
+        execSync(`git stash apply "stash@{0}"`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+        manifestObj.lastSnapshot = 'dirty';
+      }
+
+      manifest.saveManifest(manifestObj);
+      console.log(`✅ Snapshot created. Run 'scopelock revert' to obliterate agent changes and restore this state.`);
+    } catch (e) {
+      console.error('Failed to create snapshot.', e.stderr || e.message);
+      process.exit(1);
+    }
+    break;
+  }
+
+  case 'revert': {
+    try {
+      const manifestObj = manifest.getManifest();
+      if (!manifestObj.lastSnapshot) {
+        console.error('❌ No snapshot found. Run `scopelock snapshot` first.');
+        process.exit(1);
+      }
+      console.log(`Obliterating agent mess...`);
+      execSync(`git reset --hard HEAD`, { stdio: ['pipe', 'pipe', 'pipe'] });
+      execSync(`git clean -fd`, { stdio: ['pipe', 'pipe', 'pipe'] });
+
+      if (manifestObj.lastSnapshot === 'dirty') {
+        const stashes = execSync('git stash list', { encoding: 'utf8' });
+        const match = stashes.match(/stash@\{(\d+)\}: .*?scopelock-snapshot/);
+        if (match) {
+          execSync(`git stash pop "stash@{${match[1]}}"`, { stdio: ['pipe', 'pipe', 'pipe'] });
+        }
+      }
+
+      manifestObj.lastSnapshot = null;
+      manifest.saveManifest(manifestObj);
+      console.log(`✅ Rollback complete. The repository has been restored.`);
+    } catch (e) {
+      console.error('Failed to revert.', e.stderr || e.message);
+      process.exit(1);
+    }
+    break;
+  }
+
   default:
     console.log(`
 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 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 superlock <file> <reason>               Permanent production-path lock (no override)
+  scopelock sudo-unlock <file> --human-approved=<ticket> <reason>  Release a superlock
+  scopelock blast-radius <file>                     Show all files that import this file
+  scopelock allow-secret <file> <reason>            Bypass Secret Sentinel for a specific file
+  scopelock snapshot                                Auto-snapshot repo state before an agent session
+  scopelock revert                                  Rollback to the last snapshot
+  scopelock context [task]                          Generate AI context block for a task
+  scopelock check [--require-tests]                 Check git diff for violations and secret leaks
+  scopelock status                                  Show manifest summary
 
 
 Examples:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manukyalo/scopelock",
-  "version": "2.1.0",
+  "version": "2.3.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 blast-radius <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 blast-radius 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 check` 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 check 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 check` 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 sudo-unlock' 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 `superlock` makes this a physical constraint, not a policy.
+
+A superlocked 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 Superlock on Every Project
+
+```bash
+# Authentication
+scopelock superlock src/auth/token.ts "core auth — requires senior review"
+scopelock superlock src/middleware/auth.ts "core auth — requires senior review"
+
+# Billing & Payments
+scopelock superlock src/billing/stripe.ts "billing — requires finance team approval"
+scopelock superlock src/billing/webhooks.ts "billing — requires finance team approval"
+
+# Database Migrations
+scopelock superlock migrations/ "schema changes — requires DBA review"
+
+# Security-critical config
+scopelock superlock .env.production "production secrets — never touch"
+```
+
+## Agent Protocol
+
+### When you encounter a superlocked file:
+```
+❌ 'src/auth/token.ts' is SUPERLOCKED and cannot be unlocked with 'scopelock unlock'.
+   This path is a protected production route.
+   Use: scopelock sudo-unlock 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 sudo-unlock src/auth/token.ts --human-approved=JIRA-123 "fixing JWT expiry bug approved in PR-456"
+   ```
+4. Only after you see the `SUDO-UNLOCKED` confirmation may you proceed.
+5. Re-superlock the file immediately after your change is committed:
+   ```bash
+   scopelock superlock src/auth/token.ts "re-locked after JWT fix — JIRA-123"
+   ```
+
+## The Audit Trail
+
+Every `sudo-unlock` 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. `superlocked` 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 snapshot` 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 revert` 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 snapshot
+```
+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 revert
+```
+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/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 check 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 check
+```
+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 allow-secret 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

@@ -0,0 +1,21 @@
+---
+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."
+---
+
+## 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.
+
+## 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.
+5. **Ship**: Only after the test gate is passed are you allowed to commit or mark the task as complete.
+
+## Why this exists
+
+Agents often write code and immediately declare a task "done" without proving it works. This physical gate prevents the agent from bypassing the verification phase. No tests, no merge.

package/src/blast.js

@@ -0,0 +1,160 @@
+'use strict';
+
+/**
+ * src/blast.js
+ *
+ * Cross-File Blast Radius Map.
+ *
+ * Given a file path, scan the entire repo for any file that imports or
+ * requires it. Returns an array of dependent file paths.
+ *
+ * Handles the following import patterns (JS/TS/Python/Go):
+ *   import ... from './path/to/file'
+ *   require('./path/to/file')
+ *   from './path/to/file' import ...   (Python)
+ *   import "./path/to/file"
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// Directories that are never part of the blast radius analysis.
+const IGNORED_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build', 'out', 'coverage',
+  '.turbo', '.cache', '__pycache__', '.venv', 'venv', 'target',
+]);
+
+/**
+ * Recursively walk a directory and collect all files.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function walkDir(dir) {
+  const results = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.') && entry.name !== '.') continue;
+    if (IGNORED_DIRS.has(entry.name)) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkDir(full));
+    } else {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/**
+ * Generate all possible import path variants for a given target file.
+ * For example, given src/auth/token.ts, this yields:
+ *   ./token, ../auth/token, ../../src/auth/token, etc.
+ * We match against these from each candidate file's directory.
+ *
+ * @param {string} targetRelative  e.g. "src/auth/token.ts"
+ * @returns {string[]}  stem variants (without extension, for partial matching)
+ */
+function getTargetStems(targetRelative) {
+  const normalized = targetRelative.replace(/\\/g, '/');
+  const noExt = normalized.replace(/\.[^.]+$/, '');
+  return [normalized, noExt];
+}
+
+/**
+ * Check if a file's content contains an import/require of the target.
+ *
+ * @param {string} fileContent
+ * @param {string[]} targetStems
+ * @param {string} fileDir       Absolute directory of the importing file
+ * @param {string} repoRoot      Absolute repo root
+ * @param {string} targetAbsolute Absolute path of the target file
+ * @returns {boolean}
+ */
+function fileImportsTarget(fileContent, targetAbsolute, fileDir) {
+  // Extract all quoted string literals that look like import paths
+  const importPathRe = /(?:from|import|require)\s*\(?['"]([^'"]+)['"]\)?/g;
+  let match;
+  while ((match = importPathRe.exec(fileContent)) !== null) {
+    const importPath = match[1];
+    // Only resolve relative paths; skip node_module specifiers
+    if (!importPath.startsWith('.')) continue;
+    try {
+      const resolved = path.resolve(fileDir, importPath);
+      // Match with or without extension
+      const targetNoExt = targetAbsolute.replace(/\.[^.]+$/, '');
+      if (
+        resolved === targetAbsolute ||
+        resolved === targetNoExt ||
+        resolved + path.extname(targetAbsolute) === targetAbsolute
+      ) {
+        return true;
+      }
+    } catch {
+      // If resolution fails, skip
+    }
+  }
+  return false;
+}
+
+/**
+ * Compute the full blast radius for a given file.
+ *
+ * @param {string} targetFile  Relative or absolute path to the file.
+ * @returns {{ target: string, dependents: string[], total: number }}
+ */
+function blastRadius(targetFile) {
+  const repoRoot    = process.cwd();
+  const targetAbs   = path.resolve(repoRoot, targetFile);
+  const targetRel   = path.relative(repoRoot, targetAbs).replace(/\\/g, '/');
+  const allFiles    = walkDir(repoRoot);
+  const dependents  = [];
+
+  for (const f of allFiles) {
+    // Skip the target itself
+    if (path.resolve(f) === targetAbs) continue;
+
+    let content;
+    try {
+      content = fs.readFileSync(f, 'utf8');
+    } catch {
+      continue;
+    }
+
+    if (fileImportsTarget(content, targetAbs, path.dirname(f))) {
+      dependents.push(path.relative(repoRoot, f).replace(/\\/g, '/'));
+    }
+  }
+
+  return { target: targetRel, dependents, total: dependents.length };
+}
+
+/**
+ * Print a human-readable blast radius report to stdout.
+ *
+ * @param {string} targetFile
+ */
+function printBlastRadius(targetFile) {
+  const { target, dependents, total } = blastRadius(targetFile);
+
+  console.log(`\n💥  Blast Radius: ${target}\n`);
+
+  if (total === 0) {
+    console.log('   No other files import this file. Safe to modify.\n');
+    return;
+  }
+
+  console.log(`   ${total} file(s) directly import this file:\n`);
+  for (const dep of dependents) {
+    console.log(`   → ${dep}`);
+  }
+  console.log('');
+  console.log(`   ⚠️  Modifying '${target}' may impact all ${total} of the above file(s).`);
+  console.log(`   Run 'scopelock lock ${target}' to protect it before your session.\n`);
+}
+
+module.exports = { blastRadius, printBlastRadius };

package/src/git.js

@@ -21,7 +21,8 @@ const { getChangedLines } = require('./diff');
 const { extractFunctions } = require('./parser');
 const { detectSecret }  = require('./secrets');
 
-function check() {
+function check(args = []) {
+  const requireTests = args.includes('--require-tests');
   const manifest = getManifest();
   let diffOutput;
 
@@ -47,6 +48,24 @@ function check() {
   }
 
   const violations = [];
+  
+  // ── Tier -1: Test Coverage Gate ───────────────────────────────────────────
+  if (requireTests) {
+    const hasSourceChanges = changedFiles.some(f => 
+      !f.includes('.test.') && !f.includes('.spec.') && !f.includes('/test/') && !f.includes('/__tests__/') &&
+      (f.endsWith('.js') || f.endsWith('.ts') || f.endsWith('.py') || f.endsWith('.go') || f.endsWith('.rs'))
+    );
+    const hasTestChanges = changedFiles.some(f => 
+      f.includes('.test.') || f.includes('.spec.') || f.includes('/test/') || f.includes('/__tests__/')
+    );
+    if (hasSourceChanges && !hasTestChanges) {
+      violations.push({
+        type: 'test-gate',
+        file: 'N/A',
+        message: 'TEST GATE VIOLATION: Source logic was modified, but no tests were added or updated. You must write tests to pass `--require-tests`.'
+      });
+    }
+  }
 
   for (const file of changedFiles) {
     const normalizedFile = file.replace(/\\/g, '/');
@@ -74,11 +93,12 @@ function check() {
     }
 
     // ── Tier 1: File-level lock ─────────────────────────────────────────────
-    if (entry && entry.status === 'locked') {
+    if (entry && (entry.status === 'locked' || entry.status === 'superlocked')) {
+      const label = entry.status === 'superlocked' ? 'SUPERLOCKED' : 'LOCKED';
       violations.push({
         type: 'file',
         file: normalizedFile,
-        message: `File '${normalizedFile}' is LOCKED.`,
+        message: `File '${normalizedFile}' is ${label}.`,
       });
       continue; // No need to check functions if the whole file is locked
     }

package/src/manifest.js

@@ -177,6 +177,63 @@ function lock(target, reason = 'manually locked') {
   }
 }
 
+/**
+ * Superlock a file — permanent, override-resistant production path lock.
+ * Cannot be removed by 'unlock'. Requires 'sudo-unlock' with a human-approved ticket.
+ *
+ * @param {string} file   File path
+ * @param {string} reason Mandatory reason string
+ */
+function superlock(file, reason) {
+  const relativePath = file.replace(/\\/g, '/');
+  const manifest = getManifest();
+  ensureFileEntry(manifest, relativePath);
+  const entry = manifest.files[relativePath];
+
+  entry.status = 'superlocked';
+  entry.history.push({
+    timestamp: new Date().toISOString(),
+    action:    'superlocked',
+    reason,
+  });
+  saveManifest(manifest);
+  console.log(`🔐 SUPERLOCKED ${relativePath}. Only 'scopelock sudo-unlock' with a human-approved ticket can release this.`);
+}
+
+/**
+ * Remove a superlock from a file. Requires an explicit human-approved ticket string.
+ * This is the only command that can override a 'superlocked' file.
+ *
+ * @param {string} file     File path
+ * @param {string} ticket   Human-approved ticket (e.g. "JIRA-123" or "PR-456")
+ * @param {string} reason   Mandatory reason string
+ */
+function sudoUnlock(file, ticket, reason) {
+  if (!ticket || !reason) {
+    console.error('Usage: scopelock sudo-unlock <file> --human-approved=<ticket> <reason>');
+    process.exit(1);
+  }
+  const relativePath = file.replace(/\\/g, '/');
+  const manifest = getManifest();
+  ensureFileEntry(manifest, relativePath);
+  const entry = manifest.files[relativePath];
+
+  if (entry.status !== 'superlocked') {
+    console.error(`'${relativePath}' is not superlocked. Use 'scopelock unlock' instead.`);
+    process.exit(1);
+  }
+
+  entry.status = 'active';
+  entry.history.push({
+    timestamp:     new Date().toISOString(),
+    action:        'sudo-unlocked',
+    humanApproved: ticket,
+    reason,
+  });
+  saveManifest(manifest);
+  console.log(`🔓 SUDO-UNLOCKED ${relativePath}. Ticket: ${ticket}. Reason: ${reason}`);
+}
+
 /**
  * Unlock a file or a specific function.
  *
@@ -206,6 +263,15 @@ function unlock(target, reason) {
     saveManifest(manifest);
     console.log(`🔓 Unlocked function '${funcName}' in ${relativePath}. Reason: ${reason}`);
   } else {
+    // Guard against bypassing a superlock with a normal unlock
+    if (entry.status === 'superlocked') {
+      console.error(
+        `❌ '${relativePath}' is SUPERLOCKED and cannot be unlocked with 'scopelock unlock'.\n` +
+        `   This path is a protected production route.\n` +
+        `   Use: scopelock sudo-unlock ${relativePath} --human-approved=<ticket> <reason>`
+      );
+      process.exit(1);
+    }
     entry.status = 'active';
     entry.history.push(historyEntry);
     saveManifest(manifest);
@@ -220,9 +286,10 @@ function status() {
   const manifest = getManifest();
   const files    = Object.entries(manifest.files);
 
-  const locked   = files.filter(([, v]) => v.status === 'locked');
-  const active   = files.filter(([, v]) => v.status === 'active');
-  const unscoped = files.filter(([, v]) => v.status === 'unscoped');
+  const superlocked = files.filter(([, v]) => v.status === 'superlocked');
+  const locked      = files.filter(([, v]) => v.status === 'locked');
+  const active      = files.filter(([, v]) => v.status === 'active');
+  const unscoped    = files.filter(([, v]) => v.status === 'unscoped');
 
   // Count locked functions across all files
   let lockedFnCount = 0;
@@ -294,4 +361,4 @@ function allowSecret(file, reason) {
   console.log(`⚠️  Secret Sentinel bypassed for ${relativePath}. Reason: ${reason}`);
 }
 
-module.exports = { init, lock, unlock, allowSecret, status, getManifest, saveManifest };
+module.exports = { init, lock, unlock, superlock, sudoUnlock, allowSecret, status, getManifest, saveManifest };

package/test/run.js

@@ -156,6 +156,59 @@ console.log('\n--- Test 14: scopelock context output ---');
 const ctx = run(`${CLI} context "update the WIP function"`);
 assert(ctx.includes('SCOPE CONTEXT'), 'context output contains header');
 
+console.log('\n--- Test 15: Test Coverage Gate (Missing Tests) ---');
+fs.writeFileSync('feature.js', 'console.log("new logic");\n');
+run('git add feature.js');
+const testGateOut = run(`${CLI} check --require-tests`, true);
+assert(testGateOut.includes('TEST GATE VIOLATION'), 'check catches missing tests when flag is used');
+
+console.log('\n--- Test 16: Test Coverage Gate (Tests Provided) ---');
+fs.writeFileSync('feature.test.js', 'console.log("test for logic");\n');
+run('git add feature.test.js');
+const testGatePass = run(`${CLI} check --require-tests`);
+assert(testGatePass.includes('passed'), 'check passes when test files accompany source files');
+
+console.log('\n--- Test 17: Rollback Snapshot Creation ---');
+run(`${CLI} snapshot`);
+const m4 = JSON.parse(fs.readFileSync('.scopelock.json', 'utf8'));
+assert(m4.lastSnapshot === 'clean' || m4.lastSnapshot === 'dirty', 'snapshot state is tracked in manifest');
+
+console.log('\n--- Test 18: Rollback Revert ---');
+fs.writeFileSync('rogue.js', 'I am a rogue agent destroying things');
+run(`${CLI} revert`);
+assert(!fs.existsSync('rogue.js'), 'revert destroys untracked rogue files');
+const m5 = JSON.parse(fs.readFileSync('.scopelock.json', 'utf8'));
+assert(m5.lastSnapshot === null, 'revert clears the snapshot marker');
+
+console.log('\n--- Test 19: Production Path Lock (superlock) ---');
+run(`${CLI} superlock app.js "core auth logic — requires PR approval to modify"`);
+const m6 = JSON.parse(fs.readFileSync('.scopelock.json', 'utf8'));
+assert(m6.files['app.js'].status === 'superlocked', 'superlock sets status to superlocked');
+
+console.log('\n--- Test 20: superlock blocks regular unlock ---');
+const superUnlockOut = run(`${CLI} unlock app.js "trying to bypass"`, true);
+assert(superUnlockOut.includes('SUPERLOCKED'), 'regular unlock is blocked on superlocked file');
+
+console.log('\n--- Test 21: superlock blocks scopelock check ---');
+fs.appendFileSync('app.js', '\n// rogue addition\n');
+const superCheckOut = run(`${CLI} check`, true);
+assert(superCheckOut.includes('SUPERLOCKED'), 'check reports SUPERLOCKED violation');
+run('git restore app.js');
+
+console.log('\n--- Test 22: sudo-unlock releases a superlock with ticket ---');
+run(`${CLI} sudo-unlock app.js --human-approved=JIRA-999 "approved by senior eng for critical hotfix"`);
+const m7 = JSON.parse(fs.readFileSync('.scopelock.json', 'utf8'));
+assert(m7.files['app.js'].status === 'active', 'sudo-unlock transitions superlocked to active');
+const sudoHistory = m7.files['app.js'].history.find(h => h.action === 'sudo-unlocked');
+assert(sudoHistory && sudoHistory.humanApproved === 'JIRA-999', 'sudo-unlock logs the human-approved ticket');
+
+console.log('\n--- Test 23: Blast Radius Map ---');
+// Make app.js import readme.txt by creating an importer
+fs.writeFileSync('importer.js', `import { something } from './app';\n`);
+const blastOut = run(`${CLI} blast-radius app.js`);
+assert(blastOut.includes('Blast Radius'), 'blast-radius outputs the report header');
+assert(blastOut.includes('importer.js'), 'blast-radius correctly identifies importer.js as a dependent');
+
 // ─── Done ─────────────────────────────────────────────────────────────────────
 
-console.log('\n✅  All 14 tests passed.\n');
+console.log('\n✅  All 23 tests passed.\n');