@manukyalo/scopelock 2.0.0

package/README.md

@@ -0,0 +1,141 @@
+# scopelock
+
+**Anti-hallucination scope locking for AI coding agents.**
+
+```bash
+npm install -g @manukyalo/scopelock
+```
+
+`scopelock` solves a specific, well-documented problem: AI coding agents frequently exhibit scope creep — modifying files outside the intended change — and lack persistent project memory across sessions.
+
+---
+
+## Companion Skill
+
+`skills/scope-enforcement/SKILL.md` is a structured 3-checkpoint workflow for AI agents that enforces scopelock boundaries across every phase of a session. Load it into: **Antigravity**, **Claude Code**, **Gemini CLI**, **Cursor**, **Kiro**.
+
+---
+
+## The Problem
+
+You ask an AI agent to fix the login button. It also refactors your auth middleware, updates 3 unrelated components, and breaks a working API route. You had no pre-commit guardrail to stop it.
+
+`scopelock` enforces scope at two levels:
+
+| Protection | What it stops |
+|------------|--------------|
+| **File-level** | Agent modifies any file marked `locked` |
+| **Function-level** | Agent modifies lines inside a locked function body, even if the surrounding file is `active` |
+
+---
+
+## Commands
+
+### `scopelock init`
+Scan the repo and generate `.scopelock.json`. Automatically ignores `node_modules`, `.git`, `.next`, `dist`, `build`, `out`, `coverage`, and other build artifacts.
+
+```bash
+scopelock init
+```
+
+### `scopelock status`
+Print a human-readable summary of the manifest.
+
+```bash
+scopelock status
+
+# 📋  scopelock status
+#
+#   🔒  locked    — 3 file(s), 2 function(s)
+#   ✏️   active    — 1 file(s)
+#   ⬜  unscoped  — 98 file(s)
+#
+# Locked files:
+#   src/lib/supabase.ts
+#   src/middleware.ts
+#     └── middleware() [locked]
+```
+
+### `scopelock lock <file>[:<function>] [reason]`
+Lock a whole file or a specific named function.
+
+```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 <file>[:<function>] <reason>`
+Unlock a file or function. Reason is mandatory and logged.
+
+```bash
+scopelock unlock src/auth/token.ts:validateToken "fixing JWT expiry edge case"
+```
+
+### `scopelock check`
+Two-tier scope violation check against `git diff HEAD`. Exits non-zero on violations.
+
+```bash
+scopelock check
+```
+
+### `scopelock context [task]`
+Output a token-efficient AI context block with all locks clearly flagged.
+
+```bash
+scopelock context "Fix the broken checkout flow" | clip
+```
+
+---
+
+## Pre-commit Hook
+
+```bash
+echo '#!/bin/sh
+scopelock check' > .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+```
+
+Once wired, no agent or developer can commit a scope violation.
+
+---
+
+## File Statuses
+
+| Status | Meaning |
+|--------|---------|
+| `unscoped` | Not yet classified |
+| `locked` | Stable — do not modify without an explicit `scopelock unlock` |
+| `active` | In scope for the current task |
+
+---
+
+## Language Support for Function-level Locking
+
+| Language | Extensions |
+|----------|-----------|
+| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` |
+| TypeScript | `.ts`, `.tsx` |
+| Python | `.py` |
+
+All other file types fall back to file-level locking automatically.
+
+---
+
+## Commit `.scopelock.json`
+
+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.
+
+---
+
+## Zero Dependencies
+
+Built entirely on Node.js built-ins (`fs`, `path`, `child_process`). No runtime dependencies.
+
+---
+
+## License
+
+MIT

package/bin/scopelock.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * bin/scopelock.js — CLI entry point
+ *
+ * Commands:
+ *   scopelock init                          Scan repo, generate .scopelock.json
+ *   scopelock lock <file>[:<func>] [reason] Lock a file or function
+ *   scopelock unlock <file>[:<func>] <reason> Unlock with mandatory reason
+ *   scopelock context [task]                Generate AI context block
+ *   scopelock check                         Verify git diff — exits 1 on violation
+ *   scopelock status                        Print manifest summary
+ */
+
+const manifest = require('../src/manifest');
+const context  = require('../src/context');
+const git      = require('../src/git');
+
+const [,, command, ...args] = process.argv;
+
+switch (command) {
+
+  case 'init':
+    manifest.init();
+    break;
+
+  case 'lock': {
+    const target = args[0];
+    const reason = args.slice(1).join(' ') || 'manually locked';
+    if (!target) {
+      console.error('Usage: scopelock lock <file>[:<function>] [reason]');
+      process.exit(1);
+    }
+    manifest.lock(target, reason);
+    break;
+  }
+
+  case 'unlock': {
+    const target = args[0];
+    const reason = args.slice(1).join(' ');
+    if (!target || !reason) {
+      console.error('Usage: scopelock unlock <file>[:<function>] <reason>');
+      process.exit(1);
+    }
+    manifest.unlock(target, reason);
+    break;
+  }
+
+  case 'context': {
+    const task = args.join(' ');
+    context.generate(task);
+    break;
+  }
+
+  case 'check':
+    git.check();
+    break;
+
+  case 'status':
+    manifest.status();
+    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 context [task]                 Generate AI context block for a task
+  scopelock check                          Check git diff for scope violations
+  scopelock status                         Show manifest summary
+
+Examples:
+  scopelock lock src/auth.ts
+  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
+    `);
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@manukyalo/scopelock",
+  "version": "2.0.0",
+  "description": "Anti-hallucination scope locking for AI coding agents.",
+  "main": "bin/scopelock.js",
+  "bin": {
+    "scopelock": "bin/scopelock.js"
+  },
+  "scripts": {
+    "test": "node test/run.js"
+  },
+  "author": "Emmanuel",
+  "license": "MIT",
+  "skills": "./skills"
+}

package/skills/scope-enforcement/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: scope-enforcement
+description: "Prevents AI agent scope creep by enforcing scopelock boundaries before, during, and after every coding task. Supports file-level and function-level locking. Use before writing any code, before every commit, and before any review or ship phase. Requires scopelock CLI (npm install -g @manukyalo/scopelock)."
+---
+
+## Overview
+
+AI coding agents default to the shortest path to a passing result — which frequently means modifying files, functions, and logic far outside the declared task. `scope-enforcement` is the guardrail that stops this before it reaches a commit.
+
+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.
+
+The skill operates at three checkpoints: **Session Start**, **Pre-Commit**, and **Post-Task Review**.
+
+---
+
+## When to Use
+
+Activate this skill whenever:
+- Starting a new coding task in any AI-assisted session.
+- An agent is about to generate, modify, or delete any file.
+- Running a `/review` or `/ship` command.
+- You suspect an agent has drifted outside the declared task scope.
+- Onboarding a new agent to an existing codebase with stable, tested modules.
+
+---
+
+## Process
+
+### Checkpoint 1 — Session Start (Before writing any code)
+
+**Step 1: Verify scopelock is initialized.**
+```bash
+scopelock status
+```
+If no manifest exists:
+```bash
+scopelock init
+```
+
+**Step 2: Inject scope context into the agent.**
+```bash
+scopelock context "<task description>"
+```
+Paste the full output at the top of your agent's context window before writing a single line of code.
+
+**Step 3: Lock your stable code (if not already done).**
+
+Lock a whole file:
+```bash
+scopelock lock src/lib/supabase.ts "production client — stable"
+```
+
+Lock a specific function (JS, TS, Python):
+```bash
+scopelock lock src/auth/token.ts:validateToken "tested, do not touch"
+```
+
+---
+
+### Checkpoint 2 — Pre-Commit (Before every `git commit`)
+
+**Step 4: Run the scope check.**
+```bash
+scopelock check
+```
+
+Two-tier enforcement:
+
+| Tier | What it detects |
+|------|----------------|
+| File-level | Any file in the diff whose status is `locked` |
+| Function-level | Any changed line falling inside a locked function's body |
+
+- Exit `0` → commit is clean. Proceed.
+- Exit `1` → violation found. **Stop. Do not commit.**
+
+**Step 5: Handle violations.**
+
+*Unintentional (scope creep):*
+```bash
+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
+```
+
+---
+
+### Checkpoint 3 — Post-Task Review
+
+**Step 6: Audit the unlock history.**
+Open `.scopelock.json` and review every `history` entry. Every unlock must have a specific, task-justified reason. Vague entries like "needed it" indicate unreviewed scope creep.
+
+**Step 7: Re-lock completed code.**
+```bash
+scopelock lock src/auth/token.ts:validateToken "fixed and re-locked"
+```
+
+---
+
+## Pre-commit Hook (Wire once, enforce forever)
+
+```bash
+echo '#!/bin/sh
+scopelock check' > .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+```
+
+---
+
+## Common Rationalizations
+
+| Excuse | Rebuttal |
+|--------|----------|
+| "The locked function only had a minor change." | Size is irrelevant. Run `git restore` or use `scopelock unlock <file>:<func>` with a real reason. |
+| "I'll check scope after I finish the implementation." | Checking after the fact means the violation already happened. Start with `scopelock context`. |
+| "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. |
+| ".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.
+- 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.
+- `scopelock status` shows 0 locked files when you expected protection — manifest may be stale or deleted.
+
+---
+
+## Verification
+
+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.
+- [ ] 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.
+
+"Seems like it probably didn't touch anything important" is not verification. Run the check.

package/src/context.js

@@ -0,0 +1,76 @@
+'use strict';
+
+/**
+ * src/context.js
+ *
+ * Generates a condensed, token-efficient AI context block.
+ * The output is designed to be pasted into any AI agent's context window.
+ * V2: Surfaces function-level locks alongside file-level locks.
+ */
+
+const { getManifest } = require('./manifest');
+
+function generate(task) {
+  const manifest = getManifest();
+  const files    = Object.entries(manifest.files).sort(([a], [b]) => a.localeCompare(b));
+
+  const locked   = files.filter(([, v]) => v.status === 'locked');
+  const active   = files.filter(([, v]) => v.status === 'active');
+
+  // Files that are unscoped but contain locked functions
+  const fnLocked = files.filter(([, v]) => {
+    if (v.status === 'locked') return false; // already captured above
+    if (!v.functions) return false;
+    return Object.values(v.functions).some(f => f.status === 'locked');
+  });
+
+  console.log('='.repeat(60));
+  console.log('AI AGENT SCOPE CONTEXT — DO NOT IGNORE THESE CONSTRAINTS');
+  console.log('='.repeat(60));
+
+  if (task) {
+    console.log(`\nTask: ${task}`);
+  }
+
+  console.log('\n--- LOCKED (DO NOT MODIFY) ---');
+  if (locked.length === 0 && fnLocked.length === 0) {
+    console.log('  (none)');
+  }
+  for (const [filePath, data] of locked) {
+    console.log(`  [LOCKED FILE] ${filePath}`);
+    if (data.functions) {
+      for (const [fnName, fnData] of Object.entries(data.functions)) {
+        if (fnData.status === 'locked') {
+          console.log(`    └── [LOCKED FUNCTION] ${fnName}()`);
+        }
+      }
+    }
+  }
+  for (const [filePath, data] of fnLocked) {
+    console.log(`  [FILE — partial lock] ${filePath}`);
+    for (const [fnName, fnData] of Object.entries(data.functions)) {
+      if (fnData.status === 'locked') {
+        console.log(`    └── [LOCKED FUNCTION] ${fnName}() — DO NOT MODIFY`);
+      }
+    }
+  }
+
+  console.log('\n--- ACTIVE (In scope for this task) ---');
+  if (active.length === 0) {
+    console.log('  (none declared — use `scopelock lock` to classify files)');
+  }
+  for (const [filePath] of active) {
+    console.log(`  [ACTIVE] ${filePath}`);
+  }
+
+  console.log('\n' + '='.repeat(60));
+  console.log('INSTRUCTIONS FOR THIS SESSION:');
+  console.log('1. You MUST NOT modify any [LOCKED FILE] or [LOCKED FUNCTION].');
+  console.log('2. If a locked file or function genuinely needs to change,');
+  console.log('   run: scopelock unlock <file>[:<function>] "<reason>"');
+  console.log('3. Before committing, run: scopelock check');
+  console.log('4. Scope creep = silent regressions. Stay in bounds.');
+  console.log('='.repeat(60) + '\n');
+}
+
+module.exports = { generate };

package/src/diff.js

@@ -0,0 +1,68 @@
+'use strict';
+
+/**
+ * src/diff.js
+ *
+ * Parses `git diff HEAD -- <file>` output to extract the line numbers
+ * (1-indexed, in the NEW version of the file) that were added or changed.
+ *
+ * Returned as a Set<number> for O(1) membership tests.
+ */
+
+const { execSync } = require('child_process');
+
+// Matches hunk header: @@ -a,b +c,d @@
+// We only care about the new-file start (group 1) and optional length (group 2).
+const HUNK_HEADER_RE = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/;
+
+/**
+ * @param {string} filePath
+ * @returns {Set<number>}  1-indexed line numbers that changed in the new file.
+ */
+function getChangedLines(filePath) {
+  let diffOutput;
+  try {
+    // Use -- to prevent ambiguity between file names and git flags.
+    diffOutput = execSync(`git diff HEAD -- "${filePath}"`, {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'ignore'],  // suppress git's stderr in normal use
+    });
+  } catch {
+    return new Set();
+  }
+
+  if (!diffOutput.trim()) return new Set();
+
+  const changedLines = new Set();
+  const lines        = diffOutput.split('\n');
+  let   currentLine  = 0;
+
+  for (const line of lines) {
+    const hunkMatch = line.match(HUNK_HEADER_RE);
+    if (hunkMatch) {
+      currentLine = parseInt(hunkMatch[1], 10);
+      continue;
+    }
+
+    if (line.startsWith('+++') || line.startsWith('---')) {
+      // File header lines — ignore
+      continue;
+    }
+
+    if (line.startsWith('+')) {
+      // Added/changed line in the new file
+      changedLines.add(currentLine);
+      currentLine++;
+    } else if (line.startsWith('-')) {
+      // Deleted line — does NOT advance the new-file line counter
+    } else if (!line.startsWith('\\')) {
+      // Context line (unchanged) — advances both counters
+      currentLine++;
+    }
+    // `` lines are ignored
+  }
+
+  return changedLines;
+}
+
+module.exports = { getChangedLines };

package/src/git.js

@@ -0,0 +1,129 @@
+'use strict';
+
+/**
+ * src/git.js
+ *
+ * Scope violation checker — V2.
+ *
+ * Two tiers of enforcement:
+ *   1. File-level:     Any changed file whose manifest status is 'locked' → violation.
+ *   2. Function-level: Any changed file that has locked functions →
+ *                      parse the diff for changed line numbers, re-extract
+ *                      function boundaries from the current file, and flag
+ *                      any changed line that falls inside a locked function.
+ *
+ * Exits 1 if any violation found. Wireable as a pre-commit hook.
+ */
+
+const { execSync }      = require('child_process');
+const { getManifest }   = require('./manifest');
+const { getChangedLines } = require('./diff');
+const { extractFunctions } = require('./parser');
+
+function check() {
+  const manifest = getManifest();
+  let diffOutput;
+
+  try {
+    diffOutput = execSync('git diff HEAD --name-only', {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch (err) {
+    console.error('git error — are you inside a git repository with at least one commit?');
+    console.error(err.message);
+    process.exit(1);
+  }
+
+  const changedFiles = diffOutput
+    .split('\n')
+    .map(f => f.trim())
+    .filter(f => f.length > 0);
+
+  if (changedFiles.length === 0) {
+    console.log('✅ Scope check passed — no changes detected.');
+    return;
+  }
+
+  const violations = [];
+
+  for (const file of changedFiles) {
+    const normalizedFile = file.replace(/\\/g, '/');
+    const entry          = manifest.files[normalizedFile];
+
+    // ── Tier 1: File-level lock ─────────────────────────────────────────────
+    if (entry && entry.status === 'locked') {
+      violations.push({
+        type: 'file',
+        file: normalizedFile,
+        message: `File '${normalizedFile}' is LOCKED.`,
+      });
+      continue; // No need to check functions if the whole file is locked
+    }
+
+    // ── Tier 2: Function-level lock ─────────────────────────────────────────
+    if (!entry || !entry.functions) continue;
+
+    const lockedFunctions = Object.entries(entry.functions)
+      .filter(([, fnData]) => fnData.status === 'locked')
+      .map(([name]) => name);
+
+    if (lockedFunctions.length === 0) continue;
+
+    // Get the line numbers that changed in this specific file
+    const changedLines = getChangedLines(normalizedFile);
+    if (changedLines.size === 0) continue;
+
+    // Re-extract function boundaries from the current on-disk file
+    const currentFunctions = extractFunctions(normalizedFile);
+
+    for (const lockedFnName of lockedFunctions) {
+      const fn = currentFunctions.find(f => f.name === lockedFnName);
+      if (!fn) {
+        // Function was deleted or renamed — this itself is a violation
+        violations.push({
+          type:    'function-missing',
+          file:    normalizedFile,
+          fn:      lockedFnName,
+          message: `Locked function '${lockedFnName}' in '${normalizedFile}' was removed or renamed.`,
+        });
+        continue;
+      }
+
+      // Check if any changed line falls within the function's boundaries
+      for (const line of changedLines) {
+        if (line >= fn.startLine && line <= fn.endLine) {
+          violations.push({
+            type: 'function',
+            file: normalizedFile,
+            fn:   lockedFnName,
+            message:
+              `Locked function '${lockedFnName}' in '${normalizedFile}' was modified ` +
+              `(changed line ${line} is inside [${fn.startLine}–${fn.endLine}]).`,
+          });
+          break; // One violation per function is enough
+        }
+      }
+    }
+  }
+
+  // ── Report ────────────────────────────────────────────────────────────────
+  if (violations.length === 0) {
+    console.log('✅ Scope check passed — no locked files or functions were modified.');
+    return;
+  }
+
+  console.error(`\n❌ Scope violations detected:\n`);
+  for (const v of violations) {
+    console.error(`   VIOLATION: ${v.message}`);
+  }
+  console.error(
+    `\n${violations.length} violation(s) found.\n` +
+    `  • Revert unintentional changes with: git restore <file>\n` +
+    `  • Explicitly unlock with:            scopelock unlock <file>[:<function>] "<reason>"`
+  );
+
+  process.exit(1);
+}
+
+module.exports = { check };

package/src/manifest.js

@@ -0,0 +1,259 @@
+'use strict';
+
+/**
+ * src/manifest.js
+ *
+ * All reads and writes to .scopelock.json go through this module.
+ *
+ * Manifest schema (V2):
+ * {
+ *   "version": 2,
+ *   "files": {
+ *     "src/auth.ts": {
+ *       "status": "unscoped" | "locked" | "active",
+ *       "functions": {                          // populated by `scopelock lock`
+ *         "validateToken": {
+ *           "status": "locked" | "active",
+ *           "history": [{ timestamp, action, reason }]
+ *         }
+ *       },
+ *       "history": [{ timestamp, action, reason }]
+ *     }
+ *   }
+ * }
+ *
+ * V1 manifests (no "version" / no "functions" key) are read transparently.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const { extractFunctions, detectLanguage } = require('./parser');
+
+const MANIFEST_FILE = '.scopelock.json';
+const VERSION       = 2;
+
+// ─── Ignored directories ──────────────────────────────────────────────────────
+
+const IGNORED_DIRS = new Set([
+  'node_modules', '.git',     '.next',   '.nuxt',   '.turbo',
+  '.vercel',      '.expo',    'dist',    'build',   'out',
+  'coverage',     '__pycache__', '.pytest_cache', '.mypy_cache',
+  'target',       '.gradle',  '.idea',   '.vscode',
+]);
+
+// ─── File walker ──────────────────────────────────────────────────────────────
+
+function walkDir(dir, fileList = []) {
+  for (const entry of fs.readdirSync(dir)) {
+    if (IGNORED_DIRS.has(entry)) continue;
+    const fullPath = path.join(dir, entry);
+    if (fs.statSync(fullPath).isDirectory()) {
+      walkDir(fullPath, fileList);
+    } else {
+      fileList.push(fullPath);
+    }
+  }
+  return fileList;
+}
+
+// ─── Manifest I/O ─────────────────────────────────────────────────────────────
+
+function getManifest() {
+  if (!fs.existsSync(MANIFEST_FILE)) {
+    console.error(`No ${MANIFEST_FILE} found. Run 'scopelock init' first.`);
+    process.exit(1);
+  }
+  return JSON.parse(fs.readFileSync(MANIFEST_FILE, 'utf8'));
+}
+
+function saveManifest(data) {
+  fs.writeFileSync(MANIFEST_FILE, JSON.stringify(data, null, 2));
+}
+
+// Ensure a file entry exists in the manifest, creating it if needed.
+function ensureFileEntry(manifest, relativePath) {
+  if (!manifest.files[relativePath]) {
+    manifest.files[relativePath] = { status: 'unscoped', functions: {}, history: [] };
+  }
+  if (!manifest.files[relativePath].functions) {
+    manifest.files[relativePath].functions = {};
+  }
+}
+
+// ─── Commands ─────────────────────────────────────────────────────────────────
+
+function init() {
+  if (fs.existsSync(MANIFEST_FILE)) {
+    console.log(`.scopelock.json already exists. Use 'scopelock status' to view it.`);
+    return;
+  }
+
+  const files    = walkDir('.');
+  const manifest = { version: VERSION, files: {} };
+  let   count    = 0;
+
+  for (const f of files) {
+    const relativePath = path.relative('.', f).replace(/\\/g, '/');
+    if (relativePath === MANIFEST_FILE) continue;
+    manifest.files[relativePath] = { status: 'unscoped', functions: {}, history: [] };
+    count++;
+  }
+
+  saveManifest(manifest);
+  console.log(`✅ Initialized ${MANIFEST_FILE} — ${count} source files tracked.`);
+  console.log(`   Run 'scopelock lock <file>' to protect files or functions.`);
+}
+
+/**
+ * Lock a file or a specific function within a file.
+ *
+ * @param {string} target  "<file>" or "<file>:<functionName>"
+ * @param {string} [reason]  Optional reason (defaults to "manually locked")
+ */
+function lock(target, reason = 'manually locked') {
+  const [filePart, funcName] = target.split(':');
+  const relativePath = filePart.replace(/\\/g, '/');
+
+  const manifest = getManifest();
+  ensureFileEntry(manifest, relativePath);
+  const entry = manifest.files[relativePath];
+
+  const historyEntry = {
+    timestamp: new Date().toISOString(),
+    action:    'locked',
+    reason,
+  };
+
+  if (funcName) {
+    // Function-level lock — parse the file to validate the function exists
+    if (!fs.existsSync(filePart)) {
+      console.error(`File not found: ${filePart}`);
+      process.exit(1);
+    }
+
+    const lang = detectLanguage(filePart);
+    if (!lang) {
+      console.error(
+        `Function-level locking is only supported for JS, TS, and Python files.\n` +
+        `'${filePart}' is not a supported language. Lock the whole file instead.`
+      );
+      process.exit(1);
+    }
+
+    const fns = extractFunctions(filePart);
+    const found = fns.find(f => f.name === funcName);
+    if (!found) {
+      console.error(
+        `Function '${funcName}' not found in ${filePart}.\n` +
+        `Known functions: ${fns.map(f => f.name).join(', ') || '(none detected)'}`
+      );
+      process.exit(1);
+    }
+
+    entry.functions[funcName] = {
+      status:  'locked',
+      history: [historyEntry],
+    };
+    saveManifest(manifest);
+    console.log(`🔒 Locked function '${funcName}' in ${relativePath}.`);
+  } else {
+    // File-level lock
+    entry.status = 'locked';
+    entry.history.push(historyEntry);
+    saveManifest(manifest);
+    console.log(`🔒 Locked ${relativePath}.`);
+  }
+}
+
+/**
+ * Unlock a file or a specific function.
+ *
+ * @param {string} target  "<file>" or "<file>:<functionName>"
+ * @param {string} reason  Mandatory reason string for audit log.
+ */
+function unlock(target, reason) {
+  const [filePart, funcName] = target.split(':');
+  const relativePath = filePart.replace(/\\/g, '/');
+
+  const manifest = getManifest();
+  ensureFileEntry(manifest, relativePath);
+  const entry = manifest.files[relativePath];
+
+  const historyEntry = {
+    timestamp: new Date().toISOString(),
+    action:    'unlocked',
+    reason,
+  };
+
+  if (funcName) {
+    if (!entry.functions[funcName]) {
+      entry.functions[funcName] = { status: 'active', history: [] };
+    }
+    entry.functions[funcName].status = 'active';
+    entry.functions[funcName].history.push(historyEntry);
+    saveManifest(manifest);
+    console.log(`🔓 Unlocked function '${funcName}' in ${relativePath}. Reason: ${reason}`);
+  } else {
+    entry.status = 'active';
+    entry.history.push(historyEntry);
+    saveManifest(manifest);
+    console.log(`🔓 Unlocked ${relativePath}. Reason: ${reason}`);
+  }
+}
+
+/**
+ * Print a human-readable summary of the current manifest state.
+ */
+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');
+
+  // Count locked functions across all files
+  let lockedFnCount = 0;
+  for (const [, v] of files) {
+    if (!v.functions) continue;
+    lockedFnCount += Object.values(v.functions).filter(f => f.status === 'locked').length;
+  }
+
+  console.log(`\n📋  scopelock status\n`);
+  console.log(`  🔒  locked    — ${locked.length} file(s), ${lockedFnCount} function(s)`);
+  console.log(`  ✏️   active    — ${active.length} file(s)`);
+  console.log(`  ⬜  unscoped  — ${unscoped.length} file(s)\n`);
+
+  if (locked.length > 0) {
+    console.log(`Locked files:`);
+    for (const [filePath, data] of locked) {
+      console.log(`  ${filePath}`);
+      if (data.functions) {
+        for (const [fnName, fnData] of Object.entries(data.functions)) {
+          if (fnData.status === 'locked') {
+            console.log(`    └── ${fnName}() [locked]`);
+          }
+        }
+      }
+    }
+  }
+
+  if (active.length > 0) {
+    console.log(`\nActive (in-scope for current task):`);
+    for (const [filePath, data] of active) {
+      console.log(`  ${filePath}`);
+      if (data.functions) {
+        for (const [fnName, fnData] of Object.entries(data.functions)) {
+          if (fnData.status === 'locked') {
+            console.log(`    └── ${fnName}() [locked]`);
+          }
+        }
+      }
+    }
+  }
+
+  console.log('');
+}
+
+module.exports = { init, lock, unlock, status, getManifest, saveManifest };

package/src/parser.js

@@ -0,0 +1,141 @@
+'use strict';
+
+/**
+ * src/parser.js
+ *
+ * Language-aware function/class extractor.
+ * No external dependencies — uses line-by-line regex matching
+ * + brace-depth counting for JS/TS and indentation tracking for Python.
+ *
+ * Returns: Array<{ name: string, startLine: number, endLine: number }>
+ * All line numbers are 1-indexed.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// Extensions we know how to parse. Everything else gets file-level locking only.
+const EXTENSION_TO_LANG = {
+  '.js':  'javascript',
+  '.jsx': 'javascript',
+  '.ts':  'typescript',
+  '.tsx': 'typescript',
+  '.mjs': 'javascript',
+  '.cjs': 'javascript',
+  '.py':  'python',
+};
+
+// JS / TS patterns — each must capture the function/class name in group 1.
+// Order matters: more specific patterns first.
+const JS_PATTERNS = [
+  // export async function foo(  /  export function foo(  /  function foo(
+  /^[\t ]*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s+(\w+)\s*[(<]/,
+  // export class Foo  /  class Foo
+  /^[\t ]*(?:export\s+)?(?:default\s+)?class\s+(\w+)/,
+  // export const foo = async (  /  const foo = (  /  const foo = function(
+  /^[\t ]*(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?(?:\(|function\s*[({(])/,
+  // Class method shorthand: foo() {  /  async foo() {
+  /^[\t ]+(?:(?:static|async|get|set|public|private|protected|override|abstract)\s+)*(\w+)\s*\([^)]*\)\s*(?::\s*\S+\s*)?\{/,
+  // Object method shorthand or TypeScript interface method
+  /^[\t ]+(?:async\s+)?(\w+)\s*\([^)]*\)\s*(?::\s*[\w<>[\]|&, ]+\s*)?\{/,
+];
+
+const PY_PATTERNS = [
+  /^[\t ]*(?:async\s+)?def\s+(\w+)\s*\(/,
+  /^[\t ]*class\s+(\w+)/,
+];
+
+// ─── Language detection ───────────────────────────────────────────────────────
+
+function detectLanguage(filePath) {
+  return EXTENSION_TO_LANG[path.extname(filePath).toLowerCase()] || null;
+}
+
+// ─── End-of-function detection ────────────────────────────────────────────────
+
+/**
+ * Walk forward from startLine to find where this function/class ends.
+ * Returns a 0-indexed line number.
+ */
+function findFunctionEnd(lines, startLine, lang) {
+  if (lang === 'python') {
+    // Python: end when indentation returns to the level of the def/class line
+    // or we hit EOF.
+    const defLine     = lines[startLine];
+    const baseIndent  = (defLine.match(/^(\s*)/) || ['', ''])[1].length;
+
+    for (let i = startLine + 1; i < lines.length; i++) {
+      const line = lines[i];
+      if (!line.trim()) continue;                          // skip blank lines
+      const indent = (line.match(/^(\s*)/) || ['', ''])[1].length;
+      if (indent <= baseIndent) return i - 1;
+    }
+    return lines.length - 1;
+  }
+
+  // JS / TS: count braces from the declaration line forward.
+  // Caveat: this is naive — string literals and block comments with braces
+  // can confuse the counter, but it covers the vast majority of real code.
+  let depth     = 0;
+  let foundOpen = false;
+
+  for (let i = startLine; i < lines.length; i++) {
+    for (const ch of lines[i]) {
+      if (ch === '{') { depth++; foundOpen = true; }
+      else if (ch === '}') depth--;
+    }
+    if (foundOpen && depth === 0) return i;
+  }
+
+  return lines.length - 1;
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Extract all top-level and class-level function/method/class declarations
+ * from a source file.
+ *
+ * @param {string} filePath  Absolute or relative path to a source file.
+ * @returns {Array<{name: string, startLine: number, endLine: number}>}
+ */
+function extractFunctions(filePath) {
+  const lang = detectLanguage(filePath);
+  if (!lang) return [];
+
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return [];
+  }
+
+  const lines    = content.split('\n');
+  const patterns = lang === 'python' ? PY_PATTERNS : JS_PATTERNS;
+  const results  = [];
+
+  // Track the last end line to avoid duplicate matches inside the same block
+  let lastEnd = -1;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (i <= lastEnd) continue;      // already inside a block we catalogued
+
+    for (const pattern of patterns) {
+      const match = lines[i].match(pattern);
+      if (match && match[1]) {
+        const endLine = findFunctionEnd(lines, i, lang);
+        results.push({
+          name:      match[1],
+          startLine: i + 1,          // 1-indexed
+          endLine:   endLine + 1,    // 1-indexed
+        });
+        lastEnd = endLine;
+        break;                       // only one pattern fires per line
+      }
+    }
+  }
+
+  return results;
+}
+
+module.exports = { extractFunctions, detectLanguage };

package/test/run.js

@@ -0,0 +1,146 @@
+'use strict';
+
+/**
+ * test/run.js
+ *
+ * Integration tests for scopelock V2.
+ * Sets up a real git repo in test/tmp_repo/, exercises all commands,
+ * and asserts correct exit codes and output.
+ */
+
+const { execSync } = require('child_process');
+const fs   = require('fs');
+const path = require('path');
+
+// ─── Setup ────────────────────────────────────────────────────────────────────
+
+const testDir = path.join(__dirname, 'tmp_repo');
+if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true, force: true });
+fs.mkdirSync(testDir, { recursive: true });
+process.chdir(testDir);
+
+const CLI = 'node ../../bin/scopelock.js';
+
+function run(cmd, expectFail = false) {
+  try {
+    return execSync(cmd, { encoding: 'utf8', stdio: 'pipe' });
+  } catch (err) {
+    if (expectFail) return err.stderr + err.stdout;
+    console.error(`\nUnexpected failure running: ${cmd}`);
+    console.error(err.stdout);
+    console.error(err.stderr);
+    process.exit(1);
+  }
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    console.error(`\n  FAIL: ${message}`);
+    process.exit(1);
+  }
+  console.log(`  ✓  ${message}`);
+}
+
+// ─── Git repo bootstrap ───────────────────────────────────────────────────────
+
+run('git init');
+run('git config user.email "test@scopelock.dev"');
+run('git config user.name "scopelock test"');
+
+// Write a simple JS file with two named functions
+fs.writeFileSync('app.js', `
+function stableFunc() {
+  return 'I am stable and tested';
+}
+
+function workInProgress() {
+  return 'I am actively being edited';
+}
+`.trimStart());
+
+fs.writeFileSync('readme.txt', 'Initial readme content.\n');
+run('git add .');
+run('git commit -m "initial"');
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+console.log('\n--- Test 1: scopelock init ---');
+run(`${CLI} init`);
+assert(fs.existsSync('.scopelock.json'), '.scopelock.json was created');
+const manifest = JSON.parse(fs.readFileSync('.scopelock.json', 'utf8'));
+assert(manifest.version === 2, 'Manifest is V2 schema');
+assert(manifest.files['app.js'] !== undefined, 'app.js is tracked');
+assert(manifest.files['readme.txt'] !== undefined, 'readme.txt is tracked');
+
+console.log('\n--- Test 2: scopelock status ---');
+const statusOut = run(`${CLI} status`);
+assert(statusOut.includes('unscoped'), 'status shows unscoped files');
+
+console.log('\n--- Test 3: File-level lock ---');
+run(`${CLI} lock readme.txt "stable documentation"`);
+const m2 = JSON.parse(fs.readFileSync('.scopelock.json', 'utf8'));
+assert(m2.files['readme.txt'].status === 'locked', 'readme.txt is locked');
+
+console.log('\n--- Test 4: File-level violation detection ---');
+fs.appendFileSync('readme.txt', 'AI hallucinated this line.\n');
+const violation1 = run(`${CLI} check`, true);
+assert(violation1.includes('VIOLATION'), 'check detects locked file modification');
+
+console.log('\n--- Test 5: File-level unlock clears violation ---');
+run(`${CLI} unlock readme.txt "intentional update to docs"`);
+const check1 = run(`${CLI} check`);
+assert(check1.includes('passed'), 'check passes after unlock');
+run('git restore readme.txt'); // clean up
+
+console.log('\n--- Test 6: Function-level lock ---');
+run(`${CLI} lock app.js:stableFunc "tested, production-ready"`);
+const m3 = JSON.parse(fs.readFileSync('.scopelock.json', 'utf8'));
+assert(
+  m3.files['app.js'].functions['stableFunc'].status === 'locked',
+  'stableFunc is function-locked'
+);
+
+console.log('\n--- Test 7: Change OUTSIDE locked function — no violation ---');
+// Modify workInProgress (line 6-8), stableFunc is locked (lines 1-3)
+fs.writeFileSync('app.js', `
+function stableFunc() {
+  return 'I am stable and tested';
+}
+
+function workInProgress() {
+  return 'actively being edited -- new change';
+}
+`.trimStart());
+const check2 = run(`${CLI} check`);
+assert(check2.includes('passed'), 'change outside locked function does not trigger violation');
+
+console.log('\n--- Test 8: Change INSIDE locked function — violation ---');
+fs.writeFileSync('app.js', `
+function stableFunc() {
+  return 'I have been hallucinated';
+}
+
+function workInProgress() {
+  return 'actively being edited -- new change';
+}
+`.trimStart());
+const violation2 = run(`${CLI} check`, true);
+assert(violation2.includes('VIOLATION'), 'change inside locked function triggers violation');
+assert(violation2.includes('stableFunc'), 'violation names the locked function');
+
+console.log('\n--- Test 9: Function unlock clears function-level violation ---');
+run(`${CLI} unlock app.js:stableFunc "need to update return value for new API"`);
+const check3 = run(`${CLI} check`);
+assert(check3.includes('passed'), 'check passes after function unlock');
+
+console.log('\n--- Test 10: Lock unknown function fails gracefully ---');
+const badLock = run(`${CLI} lock app.js:doesNotExist "testing"`, true);
+assert(badLock.includes('not found'), 'locking unknown function fails with clear message');
+
+console.log('\n--- Test 11: scopelock context output ---');
+const ctx = run(`${CLI} context "update the WIP function"`);
+assert(ctx.includes('SCOPE CONTEXT'), 'context output contains header');
+
+// ─── Done ─────────────────────────────────────────────────────────────────────
+
+console.log('\n✅  All 11 tests passed.\n');