@compr/opscontext-mcp 2.8.2 → 2.8.4

package/CHANGELOG.md

@@ -4,6 +4,43 @@ All notable changes to OpsContext for AI Agents (previously ContextEngine — MC
 
 > Entries for 2.2.0 through 2.4.0 were not backfilled here; see `docs/sessions/SESSION_19` through `SESSION_21` for those releases.
 
+## [2.8.4] 2026-09-17: a gate on complexity, a watch on doubled hooks
+
+### Added
+
+- **`install-claude-hook --simplicity`: a PostToolUse gate against complexity an edit just
+  introduced** (`defaults/simplicity-gate.py`, LOCK `[SIMPLICITY-GATE-SILENT-WHEN-BLIND]`).
+  After Claude edits or writes a Python file, ruff's complexity rules (C901, PLR0911, PLR0912,
+  PLR0915) run on the file and on its git HEAD version; only functions the edit made new
+  offenders or worse come back to Claude (exit 2) with the ask to simplify them without
+  changing behavior. Complexity that was already there, files outside git and a missing ruff
+  are silent. Registered once under `Edit|Write|MultiEdit` through the same count-verified
+  installer; a plain re-run keeps it, `uninstall-claude-hook --simplicity` removes only it.
+  Needs ruff (`brew install ruff`); the installer says where it found it, or that it did not.
+- **Fleet health flags a doubled Claude Code hook within a minute, not nine days**
+  (`src/fleet-health.ts`). Two measured checks: the OpsContext registrations per event in
+  `~/.claude/settings.json`, counted the way the installer counts them (a registration above 1,
+  or a partial install, is a warning), and the day's `vscode.*` audit records that repeat the
+  previous one in event and payload within 2 s (a warning above 5 percent, once the day has 10
+  hook events). Both show in `contextengine servers` (exit 1), `end-session` and the VS Code
+  status bar. The 2026-09-06 doubling ran at 99.5 to 100 percent for nine days unseen.
+
+## [2.8.3] 2026-09-16: one hook per event, verified
+
+### Fixed
+
+- **`install-claude-hook` no longer registers the emit hooks twice** (`src/install-claude-hook.ts`,
+  LOCKs `[HOOKS-COMPARED-BY-EXPANDED-PATH]`, `[INSTALL-VERIFIES-BY-COUNT]`). Its "already
+  installed?" check compared command text literally, so hooks written as
+  `$HOME/.claude/hooks/opscontext-emit.sh` looked absent and a second set was added: on the
+  author's machine every Claude Code prompt and tool call reached the audit log twice from
+  2026-09-06 to 2026-09-15, doubling the inputs of the `stuck` and `silent_failure` heuristics.
+  The installer now compares script paths with `$HOME`, `${HOME}` and `~` expanded, removes
+  extra copies of its own commands (other hooks untouched), and after writing re-reads
+  `settings.json` and exits 1 unless each event runs its script exactly once. Running
+  `install-claude-hook` again repairs an affected machine; the audit log is left as it is (it is
+  hash-chained).
+
 ## [2.8.2] 2026-09-08: every source says what it is
 
 ### Added

package/defaults/simplicity-gate.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""OpsContext simplicity gate: a Claude Code PostToolUse hook (Edit, Write, MultiEdit).
+
+Reads the hook JSON on stdin, runs ruff's complexity rules (C901, PLR0911, PLR0912, PLR0915)
+on the edited Python file and on the same file at git HEAD, and exits 2 (stderr goes back to
+Claude) only for functions that are new offenders or got worse. Installed by
+`opscontext install-claude-hook --simplicity`; removed by `uninstall-claude-hook --simplicity`.
+
+[LOCKED] [SIMPLICITY-GATE-SILENT-WHEN-BLIND] 2026-09-17
+[NEVER] exit 2 for complexity that was already there at HEAD, or when ruff, git, the file or
+        the input cannot be read. A gate that nags about code the edit did not touch, or that
+        fails when a tool is missing, gets disabled and then protects nothing.
+WHY: the 2026-09-15 bake-off on KONIVE: three simplification tools cut branches, none cut
+     lines, and a guidelines-only pass deleted a function a newer commit used. Only a diff
+     against HEAD, per (rule, function), tells "this edit made it worse" from "it was like that".
+FIX: compare per (rule, function) against HEAD; every blind path returns 0 with no output.
+     ruff is looked up in SIMPLICITY_RUFF, then PATH, then the usual install dirs, because
+     Claude Code runs hooks without the user's shell PATH.
+"""
+import ast
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+
+RULES = "C901,PLR0911,PLR0912,PLR0915"
+
+
+def find_ruff():
+    """ruff to run: SIMPLICITY_RUFF, then PATH, then where brew, pipx and cargo put it."""
+    env = os.environ.get("SIMPLICITY_RUFF")
+    if env:
+        return env
+    on_path = shutil.which("ruff")
+    if on_path:
+        return on_path
+    home = os.path.expanduser("~")
+    for candidate in (
+        "/opt/homebrew/bin/ruff",
+        "/usr/local/bin/ruff",
+        os.path.join(home, ".local", "bin", "ruff"),
+        os.path.join(home, ".cargo", "bin", "ruff"),
+    ):
+        if os.access(candidate, os.X_OK):
+            return candidate
+    return "ruff"  # run() then fails with OSError and the gate stays silent
+
+
+RUFF = find_ruff()
+
+
+def run(cmd, **kwargs):
+    try:
+        return subprocess.run(cmd, capture_output=True, text=True, **kwargs)
+    except OSError:
+        return None
+
+
+def def_names(source):
+    """Map a def line number to its function name."""
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return {}
+    return {n.lineno: n.name for n in ast.walk(tree) if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))}
+
+
+def violations(path, source):
+    """{(rule, function): (value, message)}; None when ruff cannot run."""
+    if not source:
+        return {}
+    done = run([RUFF, "check", "--no-cache", "--select", RULES, "--output-format", "json",
+                "--stdin-filename", path, "-"], input=source)
+    if done is None:
+        return None
+    try:
+        items = json.loads(done.stdout or "[]")
+    except ValueError:
+        return None
+    names = def_names(source)
+    found = {}
+    for v in items:
+        if v.get("code") not in RULES.split(","):
+            continue  # ruff always reports syntax errors; a half-written file is not "complex"
+        row = (v.get("location") or {}).get("row")
+        numbers = re.findall(r"\((\d+) > \d+\)", v.get("message", ""))
+        found[(v.get("code"), names.get(row, f"line {row}"))] = (int(numbers[0]) if numbers else 0, v.get("message", ""))
+    return found
+
+
+def head_source(path):
+    """File content at HEAD; "" when the file is new; None when not inside a git repo."""
+    top = run(["git", "-C", os.path.dirname(path) or ".", "rev-parse", "--show-toplevel"])
+    if top is None or top.returncode != 0:
+        return None
+    root = top.stdout.strip()
+    rel = os.path.relpath(os.path.realpath(path), os.path.realpath(root))
+    shown = run(["git", "-C", root, "show", f"HEAD:{rel}"])
+    return shown.stdout if shown is not None and shown.returncode == 0 else ""
+
+
+def main():
+    try:
+        event = json.load(sys.stdin)
+    except ValueError:
+        return 0
+    path = (event.get("tool_input") or {}).get("file_path", "")
+    if not path.endswith(".py") or not os.path.isfile(path):
+        return 0
+    baseline = head_source(path)
+    if baseline is None:
+        return 0
+    with open(path, encoding="utf-8", errors="replace") as fh:
+        now = violations(path, fh.read())
+    before = violations(path, baseline)
+    if now is None or before is None:
+        return 0
+    worse = [key for key, (value, _) in now.items() if key not in before or value > before[key][0]]
+    if not worse:
+        return 0
+    lines = "\n".join(f"- {name}: {now[(code, name)][1]}" for code, name in worse)
+    print(
+        f"Simplicity gate: your edit of {os.path.basename(path)} made these functions more complex than the limit:\n"
+        f"{lines}\n"
+        "Simplify them now without changing behavior (early returns, a lookup table instead of branches, "
+        "split one job per function). Keep every LOCK comment. Do not touch functions you did not edit.",
+        file=sys.stderr,
+    )
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/dist/fleet-health.d.ts

@@ -23,7 +23,16 @@ export interface FleetHealth {
         /** Above this many writes per hour a warning is raised. */
         threshold: number;
     };
+    /** Claude Code hook registrations per event, read from ~/.claude/settings.json the way the
+     *  installer counts them (paths expanded). null: no readable settings.json. A correct install
+     *  has 1 for every event; the 2026-09-06 doubling would have shown 2 here within a minute. */
+    claudeHooks: Record<string, number> | null;
     today: {
+        /** Claude Code hook events (vscode.*) since local midnight. */
+        hookEvents: number;
+        /** Of those, records identical in event and payload to the previous hook event within
+         *  DOUBLED_WINDOW_MS: what a hook registered twice produces. */
+        doubledHookEvents: number;
         /** Pre-commit blocks (hook.block) since local midnight. */
         blocks: number;
         /** Store refusals (unreadable, shrink refused, growth refused) since local midnight. */
@@ -42,6 +51,11 @@ export interface FleetHealth {
     warnings: string[];
 }
 export declare const REINDEX_PER_HOUR_WARN = 30;
+/** Doubled hook events above this share of the day's hook events raise a warning, once the day
+ *  has at least DOUBLED_MIN_EVENTS of them (a single repeated call is not a doubled hook). */
+export declare const DOUBLED_HOOK_EVENTS_WARN_PCT = 5;
+export declare const DOUBLED_MIN_EVENTS = 10;
+export declare const DOUBLED_WINDOW_MS = 2000;
 export declare function fleetHealthPath(): string;
 /** The highest version with a verify-release marker; version order, not file time (ties). */
 export declare function lastVerifiedRelease(dir?: string): string | null;
@@ -50,6 +64,7 @@ export declare function computeFleetHealth(opts?: {
     version?: string;
     auditPath?: string;
     report?: ServerReport;
+    settingsPath?: string;
 }): FleetHealth;
 /** Temp file + rename: a reader never sees half a file. */
 export declare function writeFleetHealth(h: FleetHealth): string;

package/dist/fleet-health.js

@@ -13,7 +13,13 @@ import { closeSync, existsSync, fstatSync, mkdirSync, openSync, readSync, readdi
 import { join } from "path";
 import { homedir } from "os";
 import { listServers } from "./server-registry.js";
+import { claudeHookRegistrations } from "./install-claude-hook.js";
 export const REINDEX_PER_HOUR_WARN = 30;
+/** Doubled hook events above this share of the day's hook events raise a warning, once the day
+ *  has at least DOUBLED_MIN_EVENTS of them (a single repeated call is not a doubled hook). */
+export const DOUBLED_HOOK_EVENTS_WARN_PCT = 5;
+export const DOUBLED_MIN_EVENTS = 10;
+export const DOUBLED_WINDOW_MS = 2000;
 const TAIL_BYTES = 8 * 1024 * 1024;
 function ceHome() {
     return process.env.CONTEXTENGINE_HOME || join(homedir(), ".contextengine");
@@ -100,12 +106,20 @@ export function computeFleetHealth(opts = {}) {
     const midnight = localMidnight(now).getTime();
     const hourAgo = now.getTime() - 3_600_000;
     const perCorpus = {};
-    let lastHourWrites = 0, blocks = 0, refusals = 0, learningsSaved = 0;
+    let lastHourWrites = 0, blocks = 0, refusals = 0, learningsSaved = 0, hookEvents = 0, doubledHookEvents = 0;
     const lastBlocks = [];
+    let prevHook = null;
     for (const r of records) {
         const t = Date.parse(r.ts);
         if (Number.isNaN(t))
             continue;
+        if (r.event.startsWith("vscode.") && t >= midnight) {
+            hookEvents++;
+            const payload = JSON.stringify(r.payload ?? {});
+            if (prevHook && prevHook.event === r.event && prevHook.payload === payload && t - prevHook.t <= DOUBLED_WINDOW_MS)
+                doubledHookEvents++;
+            prevHook = { t, event: r.event, payload };
+        }
         if (r.event === "index.write" && t >= hourAgo) {
             lastHourWrites++;
             const c = String(r.payload?.corpus ?? "?");
@@ -127,9 +141,22 @@ export function computeFleetHealth(opts = {}) {
     const stale = report.servers.filter((s) => s.staleBuild).map((s) => ({ pid: s.pid, version: s.version, build: s.build, cwd: s.cwd }));
     const diskBuild = report.servers.find((s) => s.currentBuild)?.currentBuild ?? null;
     const indexers = report.servers.filter((s) => s.role !== "reader").length;
+    const claudeHooks = claudeHookRegistrations(opts.settingsPath);
     const warnings = [];
     if (stale.length > 0)
         warnings.push(`${stale.length} server(s) on an old build (pid ${stale.map((s) => s.pid).join(", ")}): reload their windows`);
+    if (claudeHooks) {
+        const doubled = Object.entries(claudeHooks).filter(([, n]) => n > 1);
+        if (doubled.length > 0)
+            warnings.push(`Claude Code runs an OpsContext hook more than once (${doubled.map(([ev, n]) => `${ev}=${n}`).join(", ")}): every event reaches the audit log that many times, run install-claude-hook`);
+        const core = ["UserPromptSubmit", "PostToolUse", "SessionStart", "Stop"];
+        const present = core.filter((ev) => (claudeHooks[ev] ?? 0) >= 1);
+        if (present.length > 0 && present.length < core.length)
+            warnings.push(`OpsContext hooks installed for ${present.join(", ")} but not ${core.filter((ev) => !present.includes(ev)).join(", ")}: run install-claude-hook`);
+    }
+    if (hookEvents >= DOUBLED_MIN_EVENTS && doubledHookEvents * 100 > hookEvents * DOUBLED_HOOK_EVENTS_WARN_PCT) {
+        warnings.push(`${doubledHookEvents} of ${hookEvents} Claude Code hook events today arrived twice within ${DOUBLED_WINDOW_MS / 1000} s: a hook is registered twice somewhere, run install-claude-hook`);
+    }
     if (lastHourWrites > REINDEX_PER_HOUR_WARN)
         warnings.push(`${lastHourWrites} shared-index writes in the last hour (ceiling ${REINDEX_PER_HOUR_WARN}): something saves in a loop`);
     if (refusals > 0)
@@ -143,7 +170,8 @@ export function computeFleetHealth(opts = {}) {
         writerPid: process.pid,
         servers: { total: report.servers.length, indexers, readers: report.servers.length - indexers, stale, diskBuild },
         reindex: { lastHourWrites, perCorpus, threshold: REINDEX_PER_HOUR_WARN },
-        today: { blocks, refusals, learningsSaved, lastBlocks: lastBlocks.slice(-3) },
+        claudeHooks,
+        today: { hookEvents, doubledHookEvents, blocks, refusals, learningsSaved, lastBlocks: lastBlocks.slice(-3) },
         lastVerifiedRelease: lastVerifiedRelease(),
         warnings,
     };
@@ -163,6 +191,7 @@ export function formatFleetHealth(h) {
     lines.push(`  servers ${h.servers.total}: ${h.servers.indexers} indexing, ${h.servers.readers} reading, ${h.servers.stale.length} on an old build`);
     lines.push(`  shared-index writes last hour: ${h.reindex.lastHourWrites} (ceiling ${h.reindex.threshold})`);
     lines.push(`  today: ${h.today.blocks} block(s) prevented, ${h.today.refusals} store refusal(s), ${h.today.learningsSaved} learning(s) saved`);
+    lines.push(`  claude code: ${h.today.hookEvents} hook event(s) today, ${h.today.doubledHookEvents} doubled; registrations ${h.claudeHooks ? Object.entries(h.claudeHooks).map(([ev, n]) => `${ev}=${n}`).join(" ") : "no settings.json"}`);
     for (const b of h.today.lastBlocks)
         lines.push(`    ${b.ts.slice(11, 19)}Z ${b.kind}: ${b.detail}`);
     for (const w of h.warnings)

package/dist/install-claude-hook.d.ts

@@ -1,3 +1,31 @@
+export interface HookCommand {
+    type: string;
+    command: string;
+    timeout?: number;
+}
+export interface HookEntry {
+    matcher?: string;
+    hooks: HookCommand[];
+}
+export interface Settings {
+    hooks?: Record<string, HookEntry[]>;
+    [k: string]: unknown;
+}
+/** The script path of a hook command, with $HOME, ${HOME} or a leading ~ expanded. */
+export declare function hookScriptPath(command: string, home?: string): string;
+/** Removes repeated registrations of our scripts under the same matcher. Keeps the first copy
+ *  and every hook that is not ours; drops an entry only when that leaves it empty. */
+export declare function dropDuplicateHooks(entries: HookEntry[], ourScripts: string[], home?: string): {
+    entries: HookEntry[];
+    removed: number;
+};
+/** How many times each event runs `script`. A correct install has exactly 1 everywhere. */
+export declare function countOurHooks(settings: Settings, events: readonly string[], script: string, home?: string): Record<string, number>;
+/** How many times Claude Code runs each OpsContext hook, read from settings.json: the three
+ *  emit events, the Stop gate, and the optional simplicity gate as "PostToolUse(simplicity)".
+ *  null when there is no readable settings.json. Shared by the install verification
+ *  ([INSTALL-VERIFIES-BY-COUNT]) and fleet health, so both count the same way. */
+export declare function claudeHookRegistrations(settingsPath?: string, home?: string): Record<string, number> | null;
 export declare function cliInstallClaudeHook(args: string[]): Promise<void>;
 export declare function cliUninstallClaudeHook(args: string[]): Promise<void>;
 //# sourceMappingURL=install-claude-hook.d.ts.map

package/dist/install-claude-hook.js

@@ -31,6 +31,12 @@ const HOOK_SCRIPT = join(HOOKS_DIR, "opscontext-emit.sh");
 /** The Stop gate: a wrapper that runs `session-gate` with the node and CLI that installed it.
  *  [LOCK] [SESSION-SAVE-IS-A-GATE] (src/session-gate.ts) */
 const GATE_SCRIPT = join(HOOKS_DIR, "opscontext-session-gate.sh");
+/** The simplicity gate: a PostToolUse hook on Edit/Write that reports complexity the edit just
+ *  introduced in a Python file, compared with git HEAD. Optional: `--simplicity`.
+ *  [LOCK] [SIMPLICITY-GATE-SILENT-WHEN-BLIND] (defaults/simplicity-gate.py) */
+const SIMPLICITY_SCRIPT = join(HOOKS_DIR, "opscontext-simplicity-gate.py");
+const SIMPLICITY_MATCHER = "Edit|Write|MultiEdit";
+const OUR_SCRIPTS = [HOOK_SCRIPT, GATE_SCRIPT, SIMPLICITY_SCRIPT];
 const EVENT_KINDS = ["UserPromptSubmit", "PostToolUse", "SessionStart"];
 function readSettings() {
     if (!existsSync(SETTINGS_FILE))
@@ -50,27 +56,113 @@ function backupSettings() {
     copyFileSync(SETTINGS_FILE, backup);
     return backup;
 }
-function hookAlreadyWired(entries, hookScript) {
-    if (!entries)
-        return false;
-    return entries.some((e) => e.hooks?.some((h) => h.command?.startsWith(hookScript)));
+// [LOCKED] [HOOKS-COMPARED-BY-EXPANDED-PATH] - 2026-09-15
+// [NEVER] compare a hook command with startsWith or any other literal text match again.
+// WHY: settings.json held the emit hooks as "$HOME/.claude/hooks/opscontext-emit.sh <Kind>",
+//      hand-wired on 2026-06-23 before this installer existed. On 2026-09-06 the 2.7.0 rollout
+//      ran install-claude-hook; its startsWith(absolute path) check did not see them, printed
+//      "4 hook entries added, 0 already present" and wrote a second set. From 2026-09-06
+//      08:20:21Z every Claude Code event reached the audit log twice (0 doubled events in the 8
+//      days before, 99.5 to 100 percent every day after), doubling the stuck and silent_failure
+//      inputs that [OPSCONTEXT-CC-HOOK] protects.
+// FIX: compare the script path after expanding $HOME, ${HOME} and a leading ~; installing also
+//      removes extra copies of our own commands under the same matcher, and nothing else.
+/** The script path of a hook command, with $HOME, ${HOME} or a leading ~ expanded. */
+export function hookScriptPath(command, home = homedir()) {
+    const m = /^\s*(?:"([^"]*)"|'([^']*)'|(\S+))/.exec(command ?? "");
+    const path = m ? (m[1] ?? m[2] ?? m[3]) : "";
+    return path.replace(/^(?:\$HOME|\$\{HOME\}|~)(?=\/)/, home);
 }
-/** Path to the reference hook script bundled with this package. */
-function bundledHookSource() {
-    // dist/install-claude-hook.js → ../defaults/claude-code-hook.sh in dev tree,
-    // or .../node_modules/@compr/opscontext-mcp/defaults/claude-code-hook.sh
+/** The command with its script path expanded, so two spellings of one call compare equal. */
+function normalizedCommand(command, home) {
+    const args = (command ?? "").trim().replace(/^(?:"[^"]*"|'[^']*'|\S+)/, "").trim();
+    return `${hookScriptPath(command, home)} ${args}`.trim();
+}
+function hookAlreadyWired(entries, hookScript, home = homedir()) {
+    return (entries ?? []).some((e) => e.hooks?.some((h) => hookScriptPath(h.command, home) === hookScript));
+}
+/** Removes repeated registrations of our scripts under the same matcher. Keeps the first copy
+ *  and every hook that is not ours; drops an entry only when that leaves it empty. */
+export function dropDuplicateHooks(entries, ourScripts, home = homedir()) {
+    const seen = new Set();
+    let removed = 0;
+    const kept = [];
+    for (const entry of entries) {
+        const before = entry.hooks ?? [];
+        const hooks = before.filter((h) => {
+            if (!ourScripts.includes(hookScriptPath(h.command, home)))
+                return true;
+            const key = `${entry.matcher ?? ""}\u0000${normalizedCommand(h.command, home)}`;
+            if (seen.has(key)) {
+                removed++;
+                return false;
+            }
+            seen.add(key);
+            return true;
+        });
+        if (hooks.length > 0 || before.length === 0)
+            kept.push({ ...entry, hooks });
+    }
+    return { entries: kept, removed };
+}
+/** How many times each event runs `script`. A correct install has exactly 1 everywhere. */
+export function countOurHooks(settings, events, script, home = homedir()) {
+    const count = (ev) => (settings.hooks?.[ev] ?? []).flatMap((e) => e.hooks ?? []).filter((h) => hookScriptPath(h.command, home) === script).length;
+    return Object.fromEntries(events.map((ev) => [ev, count(ev)]));
+}
+/** How many times Claude Code runs each OpsContext hook, read from settings.json: the three
+ *  emit events, the Stop gate, and the optional simplicity gate as "PostToolUse(simplicity)".
+ *  null when there is no readable settings.json. Shared by the install verification
+ *  ([INSTALL-VERIFIES-BY-COUNT]) and fleet health, so both count the same way. */
+export function claudeHookRegistrations(settingsPath = SETTINGS_FILE, home = homedir()) {
+    let settings;
+    try {
+        if (!existsSync(settingsPath))
+            return null;
+        settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+    const hooksDir = join(home, ".claude", "hooks");
+    const emit = join(hooksDir, "opscontext-emit.sh");
+    return {
+        ...countOurHooks(settings, EVENT_KINDS, emit, home),
+        ...countOurHooks(settings, ["Stop"], join(hooksDir, "opscontext-session-gate.sh"), home),
+        "PostToolUse(simplicity)": countOurHooks(settings, ["PostToolUse"], join(hooksDir, "opscontext-simplicity-gate.py"), home).PostToolUse,
+    };
+}
+/** Path to a file bundled under defaults/ with this package. */
+function bundledFile(name) {
+    // dist/install-claude-hook.js → ../defaults/<name> in dev tree,
+    // or .../node_modules/@compr/opscontext-mcp/defaults/<name>
     // when globally / locally installed via npm. Both follow the same relative
     // shape because npm copies defaults/ via the `files` whitelist.
-    const candidates = [
-        join(__dirname_esm, "..", "defaults", "claude-code-hook.sh"),
-        join(__dirname_esm, "defaults", "claude-code-hook.sh"),
-    ];
+    const candidates = [join(__dirname_esm, "..", "defaults", name), join(__dirname_esm, "defaults", name)];
     for (const c of candidates) {
         if (existsSync(c))
             return c;
     }
     return null;
 }
+/** Where the simplicity gate will find ruff: PATH, then the usual install dirs (the same
+ *  order as the script itself). null when it is nowhere, so the install can say so. */
+function findRuff() {
+    try {
+        const onPath = execSync("command -v ruff 2>/dev/null", { encoding: "utf-8" }).trim();
+        if (onPath)
+            return onPath;
+    }
+    catch {
+        /* not on PATH */
+    }
+    const home = homedir();
+    for (const c of ["/opt/homebrew/bin/ruff", "/usr/local/bin/ruff", join(home, ".local", "bin", "ruff"), join(home, ".cargo", "bin", "ruff")]) {
+        if (existsSync(c))
+            return c;
+    }
+    return null;
+}
 /** dist/cli.js of a global install, when there is one (same preference as install-autostart). */
 function globalCliPath() {
     try {
@@ -85,7 +177,7 @@ function globalCliPath() {
 export async function cliInstallClaudeHook(args) {
     const help = args.includes("-h") || args.includes("--help");
     if (help) {
-        console.log(`Usage: opscontext install-claude-hook
+        console.log(`Usage: opscontext install-claude-hook [--simplicity]
 
 Wires OpsContext into Claude Code's hook system so every terminal Claude
 Code session sends prompts + tool calls to the OpsContext audit log.
@@ -96,12 +188,19 @@ Events emitted (all go through the local HTTP endpoint, never the network):
   • SessionStart     → vscode.session_start
   • Stop             → the session gate: a turn cannot end while the repo's CE session
                        is older than the last commit (contextengine session-gate --help)
+  • PostToolUse on Edit|Write|MultiEdit, with --simplicity → the simplicity gate: after an
+                       edit to a Python file, ruff's complexity rules run on the file and on
+                       its git HEAD version; functions the edit made new offenders or worse
+                       are reported back to Claude (exit 2). Pre-existing complexity, files
+                       outside git and a missing ruff are silent. Needs ruff (brew install ruff).
 
 The installer:
   1. Copies the bundled hook script to ~/.claude/hooks/opscontext-emit.sh
-     and writes ~/.claude/hooks/opscontext-session-gate.sh (node + this CLI, absolute paths)
-  2. Splices four entries into ~/.claude/settings.json under "hooks"
-  3. Preserves every existing hook entry (idempotent, safe to re-run)
+     and writes ~/.claude/hooks/opscontext-session-gate.sh (node + this CLI, absolute paths);
+     with --simplicity also ~/.claude/hooks/opscontext-simplicity-gate.py
+  2. Splices four entries (five with --simplicity) into ~/.claude/settings.json under "hooks"
+  3. Preserves every existing hook entry (idempotent, safe to re-run; a re-run without
+     --simplicity keeps an installed simplicity gate and refreshes its script)
 
 A timestamped backup is written next to settings.json before any change.
 
@@ -111,9 +210,10 @@ Run: opscontext install-autostart
 `);
         return;
     }
+    const simplicityAsked = args.includes("--simplicity");
     // Step 1: Install / verify the hook script
     mkdirSync(HOOKS_DIR, { recursive: true });
-    const src = bundledHookSource();
+    const src = bundledFile("claude-code-hook.sh");
     if (!src) {
         console.error(`❌ Could not find bundled hook script defaults/claude-code-hook.sh.`);
         console.error(`   This means the install is incomplete. Reinstall opscontext:`);
@@ -129,7 +229,17 @@ Run: opscontext install-autostart
     if (backup)
         console.log(`✅ Backed up settings.json → ${backup}`);
     settings.hooks ??= {};
-    const hookCmdPrefix = `${HOOK_SCRIPT}`; // command string starts with this
+    const hookCmdPrefix = `${HOOK_SCRIPT}`; // compared by expanded path, [HOOKS-COMPARED-BY-EXPANDED-PATH]
+    // [LOCK] [HOOKS-COMPARED-BY-EXPANDED-PATH]: remove extra copies before deciding what to add.
+    let deduped = 0;
+    for (const kind of [...EVENT_KINDS, "Stop"]) {
+        const entries = settings.hooks[kind];
+        if (!entries)
+            continue;
+        const r = dropDuplicateHooks(entries, OUR_SCRIPTS);
+        settings.hooks[kind] = r.entries;
+        deduped += r.removed;
+    }
     let added = 0;
     let skipped = 0;
     for (const kind of EVENT_KINDS) {
@@ -168,8 +278,57 @@ Run: opscontext install-autostart
         added++;
     }
     console.log(`✅ Installed session gate: ${GATE_SCRIPT}`);
+    // Step 4: the simplicity gate, when asked for or already there (a plain re-run keeps it and
+    // refreshes its script, so an upgrade reaches it too).
+    const simplicityWired = hookAlreadyWired(settings.hooks.PostToolUse, SIMPLICITY_SCRIPT);
+    const wantSimplicity = simplicityAsked || simplicityWired;
+    if (wantSimplicity) {
+        const gateSrc = bundledFile("simplicity-gate.py");
+        if (!gateSrc) {
+            console.error(`❌ Could not find bundled defaults/simplicity-gate.py. Reinstall opscontext.`);
+            process.exit(1);
+        }
+        copyFileSync(gateSrc, SIMPLICITY_SCRIPT);
+        chmodSync(SIMPLICITY_SCRIPT, 0o755);
+        if (simplicityWired) {
+            skipped++;
+        }
+        else {
+            settings.hooks.PostToolUse.push({
+                matcher: SIMPLICITY_MATCHER,
+                hooks: [{ type: "command", command: SIMPLICITY_SCRIPT, timeout: 30 }],
+            });
+            added++;
+        }
+        console.log(`✅ Installed simplicity gate: ${SIMPLICITY_SCRIPT} (PostToolUse ${SIMPLICITY_MATCHER})`);
+        const ruff = findRuff();
+        if (ruff)
+            console.log(`   ruff: ${ruff}`);
+        else
+            console.log(`⚠️  ruff not found (PATH, /opt/homebrew/bin, /usr/local/bin, ~/.local/bin, ~/.cargo/bin): the gate stays silent until it is installed (brew install ruff, or pipx install ruff).`);
+    }
     writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2) + "\n");
-    console.log(`✅ ${added} hook entries added, ${skipped} already present.`);
+    const removedNote = deduped ? `, ${deduped} duplicate registrations removed` : "";
+    console.log(`✅ ${added} hook entries added, ${skipped} already present${removedNote}.`);
+    // [LOCKED] [INSTALL-VERIFIES-BY-COUNT] - 2026-09-15
+    // [NEVER] treat the added/present counters above as proof of a correct install.
+    // WHY: on 2026-09-06 this command printed "0 already present" over three existing hooks, and
+    //      the session that ran it recorded "they were not there"; the doubled audit events then
+    //      went unseen for nine days.
+    // FIX: re-read settings.json from disk and require exactly one registration per event.
+    const counts = claudeHookRegistrations() ?? {};
+    // Every event exactly once; the optional gate exactly once when wanted, never otherwise (a
+    // dedup pass alone never adds it).
+    const expected = Object.fromEntries(Object.keys(counts).map((ev) => [ev, 1]));
+    expected["PostToolUse(simplicity)"] = wantSimplicity ? 1 : 0;
+    const wrong = Object.entries(counts).filter(([ev, n]) => n !== expected[ev]);
+    if (wrong.length > 0) {
+        const detail = wrong.map(([ev, n]) => `${ev}=${n}`).join(", ");
+        console.error(`❌ settings.json must hold exactly one OpsContext hook per event, found ${detail}. Backup: ${backup || "none"}`);
+        process.exit(1);
+    }
+    const once = Object.keys(expected).filter((ev) => expected[ev] === 1);
+    console.log(`✅ Verified in settings.json: exactly one registration for ${once.join(", ")}.`);
     console.log(``);
     console.log(`Test live:`);
     console.log(`  1. Open a NEW VS Code terminal (settings.json is read at session start).`);
@@ -181,13 +340,17 @@ Run: opscontext install-autostart
 }
 export async function cliUninstallClaudeHook(args) {
     if (args.includes("-h") || args.includes("--help")) {
-        console.log(`Usage: opscontext uninstall-claude-hook
+        console.log(`Usage: opscontext uninstall-claude-hook [--simplicity]
 
-Removes OpsContext hook entries from ~/.claude/settings.json. The hook
-script file (~/.claude/hooks/opscontext-emit.sh) is left in place — delete
-manually if you want it gone. The audit log is NOT touched.`);
+Removes OpsContext hook entries from ~/.claude/settings.json. With --simplicity
+only the simplicity gate entry is removed; the emit hooks and the Stop gate stay.
+The hook script files under ~/.claude/hooks/ are left in place — delete
+manually if you want them gone. The audit log is NOT touched.`);
         return;
     }
+    const ourNames = args.includes("--simplicity")
+        ? ["opscontext-simplicity-gate.py"]
+        : ["opscontext-emit.sh", "opscontext-session-gate.sh", "opscontext-simplicity-gate.py"];
     const settings = readSettings();
     if (!settings.hooks) {
         console.log(`   (no hooks block in settings.json — nothing to remove)`);
@@ -201,7 +364,7 @@ manually if you want it gone. The audit log is NOT touched.`);
         const entries = settings.hooks[kind];
         if (!entries)
             continue;
-        const filtered = entries.filter((e) => !e.hooks?.some((h) => h.command?.includes("opscontext-emit.sh") || h.command?.includes("opscontext-session-gate.sh")));
+        const filtered = entries.filter((e) => !e.hooks?.some((h) => ourNames.some((n) => h.command?.includes(n))));
         removed += entries.length - filtered.length;
         if (filtered.length === 0) {
             delete settings.hooks[kind];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compr/opscontext-mcp",
-  "version": "2.8.2",
+  "version": "2.8.4",
   "description": "OpsContext for AI Agents — read-only fleet visibility (PM2/nginx/Docker/git/cron) + tamper-evident audit log + policy-as-code hooks. The ops + compliance layer Claude Code can't grow natively.",
   "type": "module",
   "main": "dist/index.js",
@@ -66,6 +66,7 @@
     "!dist/test*",
     "!dist/**/*.map",
     "defaults/",
+    "!defaults/__pycache__",
     "skills/",
     "examples/",
     "LICENSE",