cursordoctrine 0.1.0

package/INSTALL.md

@@ -0,0 +1,113 @@
+# Agent prompt: install the cursordoctrine hooks
+
+> Fast path: if Node 18+ is on the machine, `npx cursordoctrine@latest install`
+> does step 2 (including the hooks.json merge), and `npx cursordoctrine verify`
+> does step 3. Then restart Cursor and continue from step 4. The prompt below
+> is the manual path for machines without Node.
+
+> Paste everything below this line into a Cursor agent chat on the target machine.
+
+---
+
+Install the cursordoctrine hook package for Cursor on this machine, then verify it works. This package is for Cursor only — do not wire it into any other tool, project, or editor config.
+
+If `node --version` shows Node 18 or newer, prefer the npm installer: run `npx cursordoctrine@latest install`, then `npx cursordoctrine verify`, then skip to step 4. Otherwise continue with the manual steps.
+
+## 1. Ask the user which system they are on
+
+Before touching anything, ask the user one question and wait for the answer:
+
+> "Are you installing on **Windows** or **Linux** (including SSH remotes)?"
+
+Do not guess from the shell you happen to be running in — a Windows machine driving an SSH remote needs the Linux package on the remote. Use the answer to pick the folder:
+
+- **Windows** → use the `windows/` folder of this repo (PowerShell hooks, run with `pwsh.exe`).
+- **Linux** → use the `linux/` folder (bash hooks).
+
+Check the prerequisites first:
+
+- Windows: PowerShell 7 (`pwsh`) on PATH, plus `git`. Python 3.9+ if you want the anti-slop scanner (the hooks work without it).
+- Linux: `bash`, `git`, and either `jq` or `python3` (the hooks prefer `jq` and fall back to `python3`; install `jq` if neither is present). Python 3.9+ for the anti-slop scanner.
+
+## 2. Copy the files
+
+Windows (from the repo root, in pwsh):
+
+```powershell
+New-Item -ItemType Directory -Force "$HOME\.agents\hooks", "$HOME\.cursor" | Out-Null
+Copy-Item windows\hooks\* "$HOME\.agents\hooks\" -Force
+Copy-Item windows\inject-doctrine.ps1, windows\doctrine.md, windows\USER-RULES.md "$HOME\.cursor\" -Force
+# hooks.json ships with ~/ placeholders; pwsh -File does NOT expand ~, so
+# substitute the real profile path (forward slashes) at install time:
+$h = $HOME -replace '\\', '/'
+(Get-Content windows\hooks.json -Raw).Replace('~/', "$h/") | Set-Content "$HOME\.cursor\hooks.json" -NoNewline
+# anti-slop skill (SKILL.md + the scanner the final-review hook runs):
+New-Item -ItemType Directory -Force "$HOME\.cursor\skills" | Out-Null
+Copy-Item skills\anti-slop "$HOME\.cursor\skills\" -Recurse -Force
+```
+
+Linux (from the repo root, in bash):
+
+```bash
+mkdir -p ~/.agents/hooks ~/.cursor
+cp linux/hooks/* ~/.agents/hooks/
+cp linux/inject-doctrine.sh linux/doctrine.md linux/USER-RULES.md ~/.cursor/
+cp linux/hooks.json ~/.cursor/hooks.json
+chmod +x ~/.agents/hooks/*.sh ~/.cursor/inject-doctrine.sh
+# anti-slop skill (SKILL.md + the scanner the final-review hook runs):
+mkdir -p ~/.cursor/skills
+cp -r skills/anti-slop ~/.cursor/skills/
+```
+
+If `~/.cursor/hooks.json` already exists, merge the hook entries instead of overwriting — preserve anything the user already has.
+
+## 3. Verify before restarting Cursor
+
+Run each hook by hand with a fake payload and confirm the output. Every hook must exit 0; none of them may hang.
+
+Linux:
+
+```bash
+echo '{"command":"git push --force"}' | bash ~/.agents/hooks/permission-gate.sh   # expect "permission":"deny"
+echo '{"command":"git status"}'       | bash ~/.agents/hooks/permission-gate.sh   # expect {"permission":"allow"}
+echo '{"conversation_id":"t1","file_path":"/tmp/x.py"}' | bash ~/.agents/hooks/self-review-trigger.sh
+echo '{"conversation_id":"t1"}'       | bash ~/.agents/hooks/post-tool-use.sh     # expect {"additional_context": ...}
+echo '{"conversation_id":"t1","status":"completed"}' | bash ~/.agents/hooks/final-review.sh  # expect {"followup_message": ...} once, then {}
+echo '{"conversation_id":"t2","file_path":"/tmp/x.py"}' | bash ~/.agents/hooks/self-review-trigger.sh
+echo '{"conversation_id":"t2","status":"completed"}' | bash ~/.agents/hooks/subagent-stop-review.sh  # expect {"followup_message": "SUBAGENT FINAL REVIEW ..."} once, then {}
+echo '{"conversation_id":"t2"}'       | bash ~/.agents/hooks/post-tool-use.sh     # drain t2's leftover feedback file
+echo '{}' | bash ~/.cursor/inject-doctrine.sh                                     # expect {"additional_context": ...}
+python3 ~/.cursor/skills/anti-slop/scripts/scan_slop.py --help                    # expect usage text (final review's scanner)
+```
+
+If the scanner check fails, the final review still works — it falls back to the
+`~/.agents/hooks/anti-slop.md` checklist — but re-run the copy step above. The
+skill itself (`~/.cursor/skills/anti-slop/SKILL.md`) needs Python 3.9+ for the
+scanner and nothing else.
+
+Windows (same payloads, swap `bash ~/...sh` for `pwsh.exe -NoProfile -File $HOME\.agents\hooks\<name>.ps1`, `inject-doctrine.ps1` lives in `$HOME\.cursor`, and use `python` instead of `python3` for the scanner check):
+
+```powershell
+echo '{"command":"git push --force"}' | pwsh.exe -NoProfile -File $HOME\.agents\hooks\permission-gate.ps1
+echo '{"conversation_id":"t2","file_path":"C:\tmp\x.py"}' | pwsh.exe -NoProfile -File $HOME\.agents\hooks\self-review-trigger.ps1
+echo '{"conversation_id":"t2","status":"completed"}' | pwsh.exe -NoProfile -File $HOME\.agents\hooks\subagent-stop-review.ps1  # SUBAGENT FINAL REVIEW once, then {}
+python $HOME\.cursor\skills\anti-slop\scripts\scan_slop.py --help
+```
+
+Also validate the config: `~/.cursor/hooks.json` must parse as JSON.
+
+## 4. Verify inside Cursor
+
+1. Restart Cursor (hooks.json is read at startup).
+2. Open any project and start a new agent chat. The doctrine should be in context — ask the agent "what does your doctrine say about diffs?" and it should answer from §2.
+3. Have the agent make a small edit to a tracked file. On the next turn it should receive a `SELF-REVIEW TRIGGER` message.
+4. Ask the agent to run `git push --force` (in a throwaway repo). The permission gate must block it.
+5. Finish a small implementation and stop. A single `FINAL REVIEW` follow-up should fire — exactly once.
+6. Delegate a small edit to a subagent (e.g. ask the agent to "use a generalPurpose subagent to add a comment to <file>"). The subagent should receive one `SUBAGENT FINAL REVIEW` follow-up before returning, and the parent should see `SUBAGENT WORK DETECTED` at its next tool boundary. (`subagentStop` is only read at startup — if nothing fires, restart Cursor again.)
+7. Type `/anti-slop` in a chat (or say "remove the AI slop") — the anti-slop skill should load and run the scanner as its first step.
+
+## 5. Report
+
+Tell the user what was installed, which checks passed, and anything that failed with the exact error. Do not silently work around a failing check.
+
+Kill switches if something misbehaves: `HOOKS_ENFORCE=0` (everything advisory off), `PERM_GATE_ENFORCE=0`, `MINIMAL_EDITING_ENFORCE=0`, `ANTI_SLOP_ENFORCE=0`, `FINAL_REVIEW_ENFORCE=0`, `SUBAGENT_REVIEW_ENFORCE=0`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mario Pulice (kleosr)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# cursordoctrine
+
+Thin self-review hooks for Cursor. Five hook events, one message bus. The model is the auditor Cursor only carries context and gates blast radius.
+
+## What this is
+
+A small set of Cursor hooks that make the agent review its own work without bolting a static-analysis pipeline onto every keystroke. There is no regex army and no scoring engine. The hooks do three jobs:
+
+1. **Inject the doctrine** at session start, so every chat begins with the same short governing text (`doctrine.md` + `USER-RULES.md`).
+2. **Hand the model its own edits back.** After each agent edit, a self-review prompt (plus minimal-edit and anti-slop advisories when they trip) is stashed and delivered on the next turn. The model reads its own diff, fixes real bugs, and stays quiet otherwise.
+3. **Gate blast radius.** One permission gate denies a short, explicit list of dangerous commands (`rm -rf /`, `curl | sh`, force-push, `npm publish`, ...). Everything else is allowed.
+
+When an implementation finishes, a stop hook fires exactly one final review pass over everything that changed — then stops. Delegated work gets the same treatment: a subagent that edited files reviews its own implementation before its result returns to the parent, and its edits are folded into the parent's final review. Every bound is enforced twice: in the script and in `hooks.json`.
+
+This setup is for Cursor only. It installs into `~/.cursor` and `~/.agents/hooks` and touches nothing in your projects.
+
+## Layout
+
+```
+windows/          PowerShell hooks (pwsh) — install on Windows machines
+  hooks.json      hook wiring for ~/.cursor/hooks.json
+  inject-doctrine.ps1, doctrine.md, USER-RULES.md
+  hooks/          the eight scripts + the three prompt files
+linux/            bash hooks — install on Linux machines and SSH remotes
+  hooks.json, inject-doctrine.sh, doctrine.md, USER-RULES.md
+  hooks/          same hooks, ported to bash (jq preferred, python3 fallback)
+skills/           Cursor agent skills shipped with the package
+  anti-slop/      SKILL.md + the duplication scanner (final review runs it)
+bin/              the npm CLI (npx cursordoctrine install / verify / uninstall)
+INSTALL.md        a ready-to-paste prompt that tells a Cursor agent to
+                  install the right folder and verify every hook
+assets/           the architecture diagram above
+```
+
+The two folders are functionally identical. Windows runs everything through `pwsh.exe`; Linux runs bash, which is what you want on a remote you reach over SSH (see your `~/.ssh/config` host — the hooks live on the remote's `$HOME`, not on your laptop).
+
+## The five flows
+
+| Flow | Event | What happens |
+|---|---|---|
+| Session | `sessionStart` | `inject-doctrine` reads the doctrine + user rules and emits them as `additional_context`. |
+| Every turn | `postToolUse` | Folds completed subagents' edit markers into this conversation's marker, then drains the conversation's pending feedback file into `additional_context`. One-shot, keyed by conversation id. |
+| Shell | `beforeShellExecution` | `permission-gate` checks the command against a deny list. Allow by default, deny by list, fail open. |
+| Edit | `afterFileEdit` + `stop` | `self-review-trigger` stashes the review prompt per edit; `minimal-edit-audit` and `anti-slop-audit` append advisories when thresholds trip; `final-review` fires one end-of-implementation pass. |
+| Subagent | `subagentStop` | `subagent-stop-review` fires one in-subagent final review when a delegated run edited files, before the result returns to the parent. Marker-gated and flag-braked like `final-review`. |
+
+## Install
+
+The fast path is npm (Node 18+):
+
+```bash
+npx cursordoctrine@latest install   # copies the hook pack into ~/.agents/hooks + ~/.cursor, merges hooks.json
+npx cursordoctrine verify           # smoke-tests every hook with fake payloads, no restart needed
+```
+
+Then restart Cursor — `hooks.json` is read at startup. `install` is idempotent: re-run it to update, and entries you added to `~/.cursor/hooks.json` yourself are preserved. `npx cursordoctrine uninstall` removes the pack the same way.
+
+No Node? Open `INSTALL.md`, paste its contents into a Cursor agent chat on the target machine, and let the agent copy the files and run the verification checklist. Or do it by hand — the copy commands are in the same file.
+
+Prerequisites: `git` everywhere; `pwsh` on Windows; `bash` plus `jq` or `python3` on Linux.
+
+The anti-slop skill (`skills/anti-slop/` — SKILL.md and the duplication scanner) installs to `~/.cursor/skills/anti-slop/`. The final review runs the scanner from there; if it's missing (an install from before it shipped), the review falls back to the `~/.agents/hooks/anti-slop.md` checklist instead of failing.
+
+## Tuning and kill switches
+
+All hooks fail open and always exit 0. Nothing here can block your session.
+
+| Variable | Default | Effect |
+|---|---|---|
+| `HOOKS_ENFORCE=0` | on | turns off all advisory hooks at once |
+| `PERM_GATE_ENFORCE=0` | on | disables the permission gate |
+| `MINIMAL_EDITING_ENFORCE=0` | on | disables the over-edit advisory |
+| `ANTI_SLOP_ENFORCE=0` | on | disables the slop advisory |
+| `FINAL_REVIEW_ENFORCE=0` | on | disables the final review pass |
+| `SUBAGENT_REVIEW_ENFORCE=0` | on | disables the in-subagent review pass |
+| `MINIMAL_EDIT_WARN_LINES` / `MINIMAL_EDIT_FAIL_LINES` | 100 / 400 | over-edit thresholds |
+| `ANTI_SLOP_CHECKLIST_LINES` | 40 | added-lines threshold for the checklist |
+
+## Design notes
+
+- **State lives under `$HOME`**, in `~/.cursor/.hooks-pending/`, keyed by conversation id. No repo litter, and concurrent sessions can't drain each other's prompts. Stale state older than 7 days is swept on every stop.
+- **`afterFileEdit` output isn't consumed by Cursor**, so the edit hooks write to a pending file and `post-tool-use` re-emits it at the next tool boundary. That's the whole message bus.
+- **One review per implementation.** The stop hook arms a per-conversation flag before emitting its follow-up, so a crash can't re-fire it and a long chat still gets a review after each implementation.
+- **Subagents are first-class.** `afterFileEdit` fires inside subagents keyed by the *subagent's* conversation id, the harness normalizes agent edits (incl. `StrReplace`) to tool type `Write`, and `postToolUse` never fires for the `Task` tool — all verified by payload capture. So the matchers cover `Write|StrReplace|EditNotebook` defensively, `subagentStop` reviews the subagent in its own context, and the parent folds orphaned subagent markers (found via the `subagents/` transcript directory) into its own at every tool boundary and at stop.
+
+Self-contained. No build. Open `hooks.json` and read it — it's the whole system in one file.

package/bin/cli.mjs

@@ -0,0 +1,413 @@
+#!/usr/bin/env node
+// cursordoctrine — one-command installer for the cursordoctrine hook pack.
+//
+// The payload ships inside this npm package (windows/, linux/, skills/).
+// `install` copies it into $HOME exactly the way INSTALL.md step 2 does,
+// merging ~/.cursor/hooks.json instead of overwriting it. `verify` smoke-tests
+// every hook with fake payloads (INSTALL.md step 3). `uninstall` removes our
+// files and strips our hooks.json entries while preserving foreign ones.
+//
+// Zero runtime dependencies. Node >= 18.
+
+import {
+  chmodSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const pkg = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8'));
+
+// CURSORDOCTRINE_HOME lets tests install into a sandbox home.
+const HOME = process.env.CURSORDOCTRINE_HOME || homedir();
+const platform = process.platform === 'win32' ? 'windows' : 'linux';
+const payload = join(pkgRoot, platform);
+
+const hooksDst = join(HOME, '.agents', 'hooks');
+const cursorDst = join(HOME, '.cursor');
+const skillSrc = join(pkgRoot, 'skills', 'anti-slop');
+const skillDst = join(cursorDst, 'skills', 'anti-slop');
+const pendingDir = join(cursorDst, '.hooks-pending');
+const hooksJsonDst = join(cursorDst, 'hooks.json');
+
+const injectName = platform === 'windows' ? 'inject-doctrine.ps1' : 'inject-doctrine.sh';
+const doctrineFiles = [injectName, 'doctrine.md', 'USER-RULES.md'];
+
+function payloadHookFiles() {
+  return readdirSync(join(payload, 'hooks'));
+}
+
+// An entry in hooks.json is "ours" when its command references one of the
+// script filenames we ship (hook scripts or the inject-doctrine script).
+function ourKeys() {
+  return [...payloadHookFiles().filter((f) => !f.endsWith('.md')), injectName];
+}
+
+function isOurs(command, keys) {
+  return typeof command === 'string' && keys.some((k) => command.includes(k));
+}
+
+function keyOf(command, keys) {
+  if (typeof command !== 'string') return undefined;
+  return keys.find((k) => command.includes(k));
+}
+
+function mergeHooks(existing, incoming, keys) {
+  const out = structuredClone(existing);
+  if (out.version === undefined) out.version = incoming.version;
+  if (!out.hooks || typeof out.hooks !== 'object' || Array.isArray(out.hooks)) out.hooks = {};
+  for (const [event, entries] of Object.entries(incoming.hooks || {})) {
+    if (!Array.isArray(out.hooks[event])) out.hooks[event] = [];
+    const cur = out.hooks[event];
+    for (const entry of entries) {
+      const k = keyOf(entry.command, keys);
+      const i = cur.findIndex((x) => x && keyOf(x.command, keys) === k && k !== undefined);
+      if (i >= 0) cur[i] = entry;
+      else cur.push(entry);
+    }
+  }
+  let preserved = 0;
+  for (const entries of Object.values(out.hooks)) {
+    if (Array.isArray(entries)) preserved += entries.filter((x) => !isOurs(x?.command, keys)).length;
+  }
+  return { merged: out, preserved };
+}
+
+function install() {
+  console.log(`cursordoctrine ${pkg.version} — installing the ${platform} hook pack into ${HOME}`);
+  if (process.platform === 'darwin') {
+    console.log('  note: macOS detected — installing the Linux (bash) hook pack.');
+  }
+  if (platform === 'windows' && HOME.includes(' ')) {
+    console.log('  warning: home path contains spaces; hooks.json commands may need manual quoting.');
+  }
+
+  mkdirSync(hooksDst, { recursive: true });
+  mkdirSync(cursorDst, { recursive: true });
+
+  const hookFiles = payloadHookFiles();
+  for (const f of hookFiles) cpSync(join(payload, 'hooks', f), join(hooksDst, f));
+
+  for (const f of doctrineFiles) cpSync(join(payload, f), join(cursorDst, f));
+
+  if (platform === 'linux') {
+    for (const f of hookFiles) {
+      if (f.endsWith('.sh')) chmodSync(join(hooksDst, f), 0o755);
+    }
+    chmodSync(join(cursorDst, injectName), 0o755);
+  }
+
+  // hooks.json: pwsh -File does not expand ~, so substitute the real profile
+  // path (forward slashes) on Windows — same as INSTALL.md. Bash expands ~.
+  let text = readFileSync(join(payload, 'hooks.json'), 'utf8');
+  if (platform === 'windows') {
+    text = text.replaceAll('~/', HOME.replaceAll('\\', '/') + '/');
+  }
+  const incoming = JSON.parse(text);
+  const keys = ourKeys();
+
+  let hooksJsonNote = 'written';
+  let result = incoming;
+  if (existsSync(hooksJsonDst)) {
+    let existing = null;
+    try {
+      existing = JSON.parse(readFileSync(hooksJsonDst, 'utf8'));
+    } catch {
+      const bak = `${hooksJsonDst}.bak-${Date.now()}`;
+      cpSync(hooksJsonDst, bak);
+      hooksJsonNote = `existing file was invalid JSON — backed up to ${bak}, wrote fresh`;
+    }
+    if (existing) {
+      const { merged, preserved } = mergeHooks(existing, incoming, keys);
+      result = merged;
+      hooksJsonNote = preserved > 0 ? `merged (${preserved} foreign entr${preserved === 1 ? 'y' : 'ies'} preserved)` : 'merged';
+    }
+  }
+  writeFileSync(hooksJsonDst, JSON.stringify(result, null, 2) + '\n');
+
+  rmSync(skillDst, { recursive: true, force: true });
+  cpSync(skillSrc, skillDst, {
+    recursive: true,
+    filter: (src) => !src.includes('__pycache__'),
+  });
+
+  console.log('');
+  console.log(`  ~/.agents/hooks        ${hookFiles.length} files`);
+  console.log(`  ~/.cursor              ${doctrineFiles.join(', ')}`);
+  console.log(`  ~/.cursor/hooks.json   ${hooksJsonNote}`);
+  console.log('  ~/.cursor/skills       anti-slop (SKILL.md + scanner)');
+  console.log('');
+
+  const missing = prereqProblems();
+  for (const m of missing) console.log(`  warning: ${m}`);
+  if (missing.length) console.log('');
+
+  console.log('Done. Restart Cursor — hooks.json is read at startup.');
+  console.log('Next: npx cursordoctrine verify');
+}
+
+function prereqProblems() {
+  const problems = [];
+  if (platform === 'windows') {
+    if (!canRun('pwsh.exe', ['-NoProfile', '-Command', 'exit 0'])) {
+      problems.push('PowerShell 7 (pwsh) not found on PATH — the hooks will not run until it is installed.');
+    }
+  } else {
+    if (!canRun('bash', ['-c', 'exit 0'])) {
+      problems.push('bash not found — the hooks will not run until it is installed.');
+    }
+    if (!canRun('jq', ['--version']) && !canRun('python3', ['-c', ''])) {
+      problems.push('neither jq nor python3 found — install one (the hooks prefer jq).');
+    }
+  }
+  if (!pythonCmd()) {
+    problems.push('Python 3.9+ not found — the anti-slop scanner is unavailable (the final review falls back to the checklist).');
+  }
+  return problems;
+}
+
+function canRun(cmd, args) {
+  const r = spawnSync(cmd, args, { timeout: 15000, windowsHide: true, stdio: 'ignore' });
+  return !r.error && r.status === 0;
+}
+
+function pythonCmd() {
+  for (const c of platform === 'windows' ? ['python', 'python3', 'py'] : ['python3', 'python']) {
+    if (canRun(c, ['-c', ''])) return c;
+  }
+  return undefined;
+}
+
+function runHook(file, payloadObj) {
+  const cmd = platform === 'windows' ? ['pwsh.exe', '-NoProfile', '-File', file] : ['bash', file];
+  const r = spawnSync(cmd[0], cmd.slice(1), {
+    input: JSON.stringify(payloadObj),
+    encoding: 'utf8',
+    timeout: 20000,
+    windowsHide: true,
+    // Hooks resolve state under $HOME; pin it (and USERPROFILE, which pwsh
+    // derives $HOME from) so sandboxed verify runs stay self-contained.
+    env: { ...process.env, HOME, USERPROFILE: HOME },
+  });
+  if (r.error) return `spawn error: ${r.error.message}`;
+  return `${r.stdout || ''}${r.stderr || ''}`.trim();
+}
+
+function verify() {
+  console.log(`cursordoctrine ${pkg.version} — verifying the ${platform} hook pack in ${HOME}`);
+  console.log('');
+
+  if (!existsSync(hooksDst) || !existsSync(hooksJsonDst)) {
+    console.error('Not installed (missing ~/.agents/hooks or ~/.cursor/hooks.json).');
+    console.error('Run: npx cursordoctrine install');
+    process.exit(1);
+  }
+
+  const ext = platform === 'windows' ? 'ps1' : 'sh';
+  const hook = (name) => join(hooksDst, `${name}.${ext}`);
+  const results = [];
+  const check = (name, fn) => {
+    let ok = false;
+    let detail = '';
+    try {
+      const r = fn();
+      ok = r === true || (typeof r === 'object' && r.ok);
+      detail = typeof r === 'object' && r.detail ? r.detail : '';
+    } catch (e) {
+      detail = e.message;
+    }
+    results.push({ name, ok, detail });
+    console.log(`  ${ok ? ' ok ' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`);
+  };
+
+  check('hooks.json parses as JSON', () => {
+    JSON.parse(readFileSync(hooksJsonDst, 'utf8'));
+    return true;
+  });
+
+  check('permission gate denies `git push --force`', () =>
+    /"permission"\s*:\s*"deny"/.test(runHook(hook('permission-gate'), { command: 'git push --force' })));
+
+  check('permission gate allows `git status`', () =>
+    /"permission"\s*:\s*"allow"/.test(runHook(hook('permission-gate'), { command: 'git status' })));
+
+  check('self-review trigger stashes + post-tool-use drains', () => {
+    runHook(hook('self-review-trigger'), { conversation_id: 'npxv1', file_path: join(HOME, 'x.py') });
+    return runHook(hook('post-tool-use'), { conversation_id: 'npxv1' }).includes('additional_context');
+  });
+
+  check('final review fires once, then goes quiet', () => {
+    runHook(hook('self-review-trigger'), { conversation_id: 'npxv1', file_path: join(HOME, 'x.py') });
+    const first = runHook(hook('final-review'), { conversation_id: 'npxv1', status: 'completed' });
+    const second = runHook(hook('final-review'), { conversation_id: 'npxv1', status: 'completed' });
+    if (!first.includes('followup_message')) return { ok: false, detail: 'no followup_message on first stop' };
+    if (second.includes('followup_message')) return { ok: false, detail: 'review re-fired on second stop' };
+    return true;
+  });
+
+  check('subagent review fires once, then goes quiet', () => {
+    runHook(hook('self-review-trigger'), { conversation_id: 'npxv2', file_path: join(HOME, 'x.py') });
+    const first = runHook(hook('subagent-stop-review'), { conversation_id: 'npxv2', status: 'completed' });
+    const second = runHook(hook('subagent-stop-review'), { conversation_id: 'npxv2', status: 'completed' });
+    if (!first.includes('SUBAGENT FINAL REVIEW')) return { ok: false, detail: 'no SUBAGENT FINAL REVIEW on first stop' };
+    if (second.includes('followup_message')) return { ok: false, detail: 'review re-fired on second stop' };
+    return true;
+  });
+
+  check('doctrine injection emits additional_context', () =>
+    runHook(join(cursorDst, injectName), {}).includes('additional_context'));
+
+  const py = pythonCmd();
+  const scanner = join(skillDst, 'scripts', 'scan_slop.py');
+  let scannerOk = false;
+  if (py && existsSync(scanner)) {
+    const r = spawnSync(py, [scanner, '--help'], { encoding: 'utf8', timeout: 20000, windowsHide: true });
+    scannerOk = !r.error && /usage/i.test(`${r.stdout || ''}${r.stderr || ''}`);
+  }
+  console.log(`  ${scannerOk ? ' ok ' : 'warn'}  anti-slop scanner --help${scannerOk ? '' : ' — unavailable (final review falls back to the checklist)'}`);
+
+  // Clean up verification state so the next real session starts fresh.
+  if (existsSync(pendingDir)) {
+    for (const f of readdirSync(pendingDir)) {
+      if (f.includes('npxv')) rmSync(join(pendingDir, f), { force: true });
+    }
+  }
+
+  const failed = results.filter((r) => !r.ok);
+  console.log('');
+  if (failed.length) {
+    console.error(`${failed.length} check(s) failed. Re-run: npx cursordoctrine install`);
+    process.exit(1);
+  }
+  console.log('All checks passed. Restart Cursor if you have not since installing.');
+}
+
+function uninstall() {
+  console.log(`cursordoctrine ${pkg.version} — removing the ${platform} hook pack from ${HOME}`);
+
+  const removed = [];
+  for (const f of payloadHookFiles()) {
+    const p = join(hooksDst, f);
+    if (existsSync(p)) {
+      rmSync(p, { force: true });
+      removed.push(`~/.agents/hooks/${f}`);
+    }
+  }
+  for (const f of doctrineFiles) {
+    const p = join(cursorDst, f);
+    if (existsSync(p)) {
+      rmSync(p, { force: true });
+      removed.push(`~/.cursor/${f}`);
+    }
+  }
+  if (existsSync(skillDst)) {
+    rmSync(skillDst, { recursive: true, force: true });
+    removed.push('~/.cursor/skills/anti-slop/');
+  }
+  if (existsSync(pendingDir)) {
+    rmSync(pendingDir, { recursive: true, force: true });
+    removed.push('~/.cursor/.hooks-pending/');
+  }
+
+  if (existsSync(hooksJsonDst)) {
+    try {
+      const existing = JSON.parse(readFileSync(hooksJsonDst, 'utf8'));
+      const keys = ourKeys();
+      let foreign = 0;
+      for (const [event, entries] of Object.entries(existing.hooks || {})) {
+        if (!Array.isArray(entries)) continue;
+        existing.hooks[event] = entries.filter((x) => !isOurs(x?.command, keys));
+        foreign += existing.hooks[event].length;
+        if (existing.hooks[event].length === 0) delete existing.hooks[event];
+      }
+      if (foreign === 0) {
+        rmSync(hooksJsonDst, { force: true });
+        removed.push('~/.cursor/hooks.json');
+      } else {
+        writeFileSync(hooksJsonDst, JSON.stringify(existing, null, 2) + '\n');
+        removed.push(`~/.cursor/hooks.json (ours stripped, ${foreign} foreign entr${foreign === 1 ? 'y' : 'ies'} kept)`);
+      }
+    } catch {
+      console.log('  warning: ~/.cursor/hooks.json is not valid JSON — left untouched.');
+    }
+  }
+
+  console.log('');
+  for (const r of removed) console.log(`  removed  ${r}`);
+  if (removed.length === 0) console.log('  nothing to remove.');
+  console.log('');
+  console.log('Done. Restart Cursor to unload the hooks.');
+}
+
+function help() {
+  console.log(`cursordoctrine ${pkg.version} — thin self-review hooks for Cursor; the model is the auditor
+
+Usage
+  npx cursordoctrine <command>
+
+Commands
+  install      Install the hook pack, doctrine, and anti-slop skill into $HOME.
+               Merges ~/.cursor/hooks.json — entries you added yourself are preserved.
+  verify       Smoke-test every installed hook with fake payloads (no Cursor restart needed).
+  uninstall    Remove installed files and strip our hooks.json entries.
+  help         Show this help.
+
+After install
+  Restart Cursor — hooks.json is read at startup.
+
+Examples
+  npx cursordoctrine@latest install
+  npx cursordoctrine verify
+  npx cursordoctrine uninstall
+
+Kill switches (environment variables, all hooks fail open)
+  HOOKS_ENFORCE=0            everything advisory off
+  PERM_GATE_ENFORCE=0        permission gate off
+  MINIMAL_EDITING_ENFORCE=0  over-edit advisory off
+  ANTI_SLOP_ENFORCE=0        slop advisory off
+  FINAL_REVIEW_ENFORCE=0     final review off
+  SUBAGENT_REVIEW_ENFORCE=0  in-subagent review off
+
+Docs  https://github.com/kleosr/cursordoctrine`);
+}
+
+const cmd = process.argv[2];
+switch (cmd) {
+  case 'install':
+  case 'i':
+    install();
+    break;
+  case 'verify':
+  case 'check':
+    verify();
+    break;
+  case 'uninstall':
+  case 'remove':
+  case 'rm':
+    uninstall();
+    break;
+  case 'version':
+  case '--version':
+  case '-v':
+    console.log(pkg.version);
+    break;
+  case undefined:
+  case 'help':
+  case '--help':
+  case '-h':
+    help();
+    break;
+  default:
+    console.error(`Unknown command: ${cmd}\n`);
+    help();
+    process.exit(2);
+}

package/linux/USER-RULES.md

@@ -0,0 +1,12 @@
+Doctrine (governing text) lives at ~/.cursor/doctrine.md and is loaded
+at sessionStart. Read it once, internalize it; do not re-read it
+mid-task. Its §1 (auditor), §2 (smallest correct diff), §3 (verify
+then stop), §5 (ask don't guess), §8 (consistency anchor) are the only
+meta-instructions that matter during a session.
+
+When responding: be terse. No preamble, no postamble, no "I will now…".
+One sharp clarifying question if the task is ambiguous, then proceed.
+Reference code with `file_path:line_number` style.
+
+Do not re-load skills, do not re-read the doctrine, do not run
+gratuitous commands. If the answer is "I don't know", say so.