cursordoctrine 0.3.1 → 0.3.2

package/README.md

@@ -1,65 +1,81 @@
-# cursordoctrine
+<div align="center">
+  <img src="https://img.shields.io/badge/node-%3E%3D18-339933?style=flat-square&logo=node.js&logoColor=white" />
+  <img src="https://img.shields.io/npm/v/cursordoctrine?style=flat-square&color=blue" />
+  <img src="https://img.shields.io/badge/license-MIT-brightgreen?style=flat-square" />
+  <img src="https://img.shields.io/badge/built%20for-Cursor-6c47ff?style=flat-square" />
+</div>
 
-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.
+<br />
+
+<div align="center">
+  <h1>cursordoctrine</h1>
+  <p><strong>Thin self-review hooks for Cursor.</strong></p>
+  <p>Five hook events, one message bus.<br />The model audits its own work. Cursor carries context and gates blast radius.</p>
+</div>
+
+<br />
+
+---
 
 ## 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:
+Cursor hooks that make the agent review its own edits without bolting a static-analysis pipeline onto every keystroke. No regex army, no scoring engine. Three jobs:
 
-1. **Inject the doctrine** at session start, so every chat begins with the same short governing text (`doctrine.md` + `USER-RULES.md` + `declared-editing.md` — the YAGNI ultra ladder that prevents over-building before a single line is written).
-2. **Hand the model its own edits back.** After each agent edit, a self-review prompt (plus minimal-edit, semantic-density, 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.
+1. **Inject the doctrine** at session start — every chat starts with the same short governing text (`doctrine.md`, `USER-RULES.md`, and `declared-editing.md`, the YAGNI ultra ladder that stops over-building before a line gets written).
+2. **Hand the model its own edits back** — after each agent edit, a self-review prompt goes into a pending file (plus minimal-edit, semantic-density, and anti-slop advisories when they trip). Next turn the model reads its diff, fixes real bugs, 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 passes.
 
-When an implementation finishes, a stop hook fires exactly one final review pass over everything that changed — then stops. The review runs across five axes, the first of which is **intent trace**: the hook extracts your last user message from the transcript and prepends it to the review so the model must trace every diff hunk back to a concrete request. Anything untraceable is a hallucinated requirement and gets reverted — this is the only detector that catches "clean code, wrong feature," which no later axis and no linter can see. 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`.
+When an implementation finishes, the stop hook runs one final review over everything that changed, then stops. Five axes. The first is **intent trace**: the hook pulls your last user message from the transcript and prepends it to the review so the model has to tie every diff hunk to a concrete request. Anything it can't trace is a hallucinated requirement and gets reverted. That's the only check that catches "clean code, wrong feature" — linters and later axes miss it.
 
-This setup is for Cursor only. It installs into `~/.cursor` and `~/.agents/hooks` and touches nothing in your projects.
+Subagents get the same treatment. If a delegated run edited files, it reviews its own work before the result goes back to the parent. Those edits fold into the parent's final review. Every bound is enforced twice: in the script and in `hooks.json`.
 
-## Layout
+Cursor only. Installs into `~/.cursor` and `~/.agents/hooks`. Doesn't touch your projects.
 
+## Install
+
+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
 ```
-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).
+Restart Cursor after install — `hooks.json` is read at startup. `install` is idempotent; re-run to update. Entries you added to `~/.cursor/hooks.json` yourself are kept. `npx cursordoctrine uninstall` removes the pack the same way.
+
+No Node? Open `INSTALL.md`, paste it into a Cursor agent chat on the target machine, and let the agent copy files and run the checklist. Copy commands are in the same file if you prefer doing it by hand.
+
+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 hook checklist (`~/.agents/hooks/anti-slop.md`, 13 items) is the canonical slop detector for per-edit advisories and final-review axis 4. Final review runs the scanner from the skill path first when it's there.
 
 ## The five flows
 
 | Flow | Event | What happens |
 |---|---|---|
-| Session | `sessionStart` | `inject-doctrine` reads the doctrine + user rules and emits them as `additional_context`. |
+| Session | `sessionStart` | `inject-doctrine` reads doctrine + user rules + declared-editing 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` (deprecated in 0.3.0), `semantic-density-audit`, and `anti-slop-audit` append advisories when thresholds trip (new deps / premature abstraction / redundant comments / **semantic opacity**: low-density identifiers like `DataManager`, `process()`, `utils.ts` / Tier 3 operational slop: retry-without-backoff, await-in-loop, telemetry spam); `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+):
+## Layout
 
-```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
+```
+windows/          PowerShell hooks (pwsh) — install on Windows machines
+  hooks.json      hook wiring for ~/.cursor/hooks.json
+  inject-doctrine.ps1, doctrine.md, USER-RULES.md, declared-editing.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, declared-editing.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        ready-to-paste prompt that tells a Cursor agent to
+                  install the right folder and verify every hook
 ```
 
-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 hook checklist (`~/.agents/hooks/anti-slop.md`, 13 items) is the canonical slop detector for both per-edit advisories and final-review axis 4. The final review runs the scanner from the skill path first when available.
+Both folders do the same thing. Windows runs everything through `pwsh.exe`. Linux runs bash, which is what you want on a remote over SSH (check your `~/.ssh/config` host — hooks live on the remote's `$HOME`, not your laptop).
 
 ## Tuning and kill switches
 
@@ -79,9 +95,15 @@ All hooks fail open and always exit 0. Nothing here can block your session.
 
 ## 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.
+- **State lives under `$HOME`**, in `~/.cursor/.hooks-pending/`, keyed by conversation id. No repo litter. Concurrent sessions can't drain each other's prompts. Stale state older than 7 days gets swept on every stop.
+- **`afterFileEdit` output isn't consumed by Cursor**, so 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.
+- **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 — verified by payload capture. Matchers cover `Write|StrReplace|EditNotebook` defensively. `subagentStop` reviews the subagent in its own context. The parent folds orphaned subagent markers (from the `subagents/` transcript directory) into its own at every tool boundary and at stop.
+
+Self-contained. No build. Open `hooks.json` and read it — that's the whole system in one file.
+
+Built with [Cursor](https://cursor.com).
+
+## License
 
-Self-contained. No build. Open `hooks.json` and read it — it's the whole system in one file.
+MIT. See [LICENSE](LICENSE).

package/linux/hooks/final-review.md

@@ -1,5 +1,5 @@
 FINAL REVIEW — you just finished an implementation. Before you treat it as done,
-audit EVERYTHING you changed this session across the five axes below and FIX what
+audit EVERYTHING you changed this session across the six axes below and FIX what
 fails. Do NOT revert the behaviour the user asked for. If an axis is already
 clean, say so in one line — do not manufacture work.
 
@@ -65,3 +65,24 @@ Step C — session footprint (also in the header above):
   file or trim. Unjustified files are slop.
 
 Fix with edits now; re-run the scan (if Step A ran) and the tests; then stop.
+
+## 5. Wiring completeness
+For every user-visible behavior you added or changed (button, form submit, API
+call, route, state transition, scheduled job), trace its execution path end to
+end and confirm it reaches a REAL EFFECT (persist, mutate, call, render, notify).
+A dead end is slop even if the code is clean. Hunt for the vibe-coding failure
+mode where a layer EXISTS but is not WIRED:
+
+  - `handleSubmit()` that does not persist / does not call the API.
+  - An endpoint that no route or caller invokes.
+  - A DB write / table that nothing reads or writes.
+  - A component that renders but is never mounted / routed to.
+  - A hook / store / context that is declared but never consumed.
+  - A `TODO` / empty body / stubbed `console.log` standing in for the effect.
+
+The bar is: a senior can follow the path click -> handler -> call -> store ->
+render (or the equivalent slice) without hitting a gap. If a step is missing or
+faked, either wire it now or remove the dead half so the diff does not ship
+scaffolding that looks complete but does nothing. Stubs you intend to wire later
+must be marked with a `TODO(wire):` comment naming what is missing; unmarked
+dead ends are failures.

package/linux/hooks/final-review.sh

@@ -1,8 +1,8 @@
 #!/usr/bin/env bash
 # final-review.sh - stop hook (Cursor, Linux).
 #
-# ONE comprehensive end-of-implementation review across five axes:
-# intent, correctness, reliability, coverage, and anti-slop. When the agent finishes
+# ONE comprehensive end-of-implementation review across six axes:
+# intent, correctness, reliability, coverage, anti-slop, and wiring completeness. When the agent finishes
 # an implementation that touched files, Cursor auto-submits this hook's
 # `followup_message` as the next user turn, so the model re-audits everything
 # it changed this session and FIXES what fails.
@@ -81,6 +81,12 @@ if [ -z "$body" ]; then
      run `python ~/.cursor/skills/anti-slop/scripts/scan_slop.py --all` first.
      Consolidate clones; drop premature abstraction, unneeded deps, operational
      slop (retries, await-in-loop, log spam), unjustified files.
+  5. Wiring completeness - for every user-visible behavior you added/changed
+     (button, submit, API call, route, state transition), trace its execution
+     path to a REAL EFFECT (persist, mutate, call, render). A dead end is slop:
+     handleSubmit that does not persist, an endpoint no caller invokes, a store
+     never consumed, a stub/TODO/console.log standing in for the effect. Wire it
+     now or remove the dead half; mark later-stubs with TODO(wire):.
 Fix now, re-run the scan + tests, then stop. If an axis is clean, say so in one line.'
 fi
 body="$(expand_agent_paths "$body")"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursordoctrine",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Thin self-review hooks for Cursor — the model is the auditor. Intent-trace final review (Tier 0), unified 13-item anti-slop checklist, operational slop detection.",
   "bin": {
     "cursordoctrine": "bin/cli.mjs"

package/windows/hooks/final-review.md

@@ -1,5 +1,5 @@
 FINAL REVIEW — you just finished an implementation. Before you treat it as done,
-audit EVERYTHING you changed this session across the five axes below and FIX what
+audit EVERYTHING you changed this session across the six axes below and FIX what
 fails. Do NOT revert the behaviour the user asked for. If an axis is already
 clean, say so in one line — do not manufacture work.
 
@@ -65,3 +65,24 @@ Step C — session footprint (also in the header above):
   file or trim. Unjustified files are slop.
 
 Fix with edits now; re-run the scan (if Step A ran) and the tests; then stop.
+
+## 5. Wiring completeness
+For every user-visible behavior you added or changed (button, form submit, API
+call, route, state transition, scheduled job), trace its execution path end to
+end and confirm it reaches a REAL EFFECT (persist, mutate, call, render, notify).
+A dead end is slop even if the code is clean. Hunt for the vibe-coding failure
+mode where a layer EXISTS but is not WIRED:
+
+  - `handleSubmit()` that does not persist / does not call the API.
+  - An endpoint that no route or caller invokes.
+  - A DB write / table that nothing reads or writes.
+  - A component that renders but is never mounted / routed to.
+  - A hook / store / context that is declared but never consumed.
+  - A `TODO` / empty body / stubbed `console.log` standing in for the effect.
+
+The bar is: a senior can follow the path click -> handler -> call -> store ->
+render (or the equivalent slice) without hitting a gap. If a step is missing or
+faked, either wire it now or remove the dead half so the diff does not ship
+scaffolding that looks complete but does nothing. Stubs you intend to wire later
+must be marked with a `TODO(wire):` comment naming what is missing; unmarked
+dead ends are failures.

package/windows/hooks/final-review.ps1

@@ -1,7 +1,7 @@
 # final-review.ps1 - stop hook (Cursor).
 #
-# ONE comprehensive end-of-implementation review across five axes:
-# intent, correctness, reliability, coverage, and anti-slop. When the agent finishes an
+# ONE comprehensive end-of-implementation review across six axes:
+# intent, correctness, reliability, coverage, anti-slop, and wiring completeness. When the agent finishes an
 # implementation that touched files, Cursor auto-submits this hook's
 # `followup_message` as the next user turn, so the model re-audits everything it
 # changed this session and FIXES what fails - the model-as-auditor pattern over
@@ -91,6 +91,12 @@ FINAL REVIEW - audit everything you changed this session and FIX what fails
      run `python ~/.cursor/skills/anti-slop/scripts/scan_slop.py --all` first.
      Consolidate clones; drop premature abstraction, unneeded deps, operational
      slop (retries, await-in-loop, log spam), unjustified files.
+  5. Wiring completeness - for every user-visible behavior you added/changed
+     (button, submit, API call, route, state transition), trace its execution
+     path to a REAL EFFECT (persist, mutate, call, render). A dead end is slop:
+     handleSubmit that does not persist, an endpoint no caller invokes, a store
+     never consumed, a stub/TODO/console.log standing in for the effect. Wire it
+     now or remove the dead half; mark later-stubs with TODO(wire):.
 Fix now, re-run the scan + tests, then stop. If an axis is clean, say so in one line.
 '@
 }