cursordoctrine 0.3.0 → 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`).
-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/bin/cli.mjs

@@ -40,7 +40,7 @@ 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'];
+const doctrineFiles = [injectName, 'doctrine.md', 'USER-RULES.md', 'declared-editing.md'];
 
 function payloadHookFiles() {
   return readdirSync(join(payload, 'hooks'));

package/linux/declared-editing.md

@@ -0,0 +1,30 @@
+# Declared-editing — YAGNI ultra
+
+ACTIVE EVERY RESPONSE. No drift back to over-building. Still active if unsure.
+
+Before writing any code, stop at the first rung that holds:
+
+1. Does this need to exist at all? (YAGNI) If no — say so, don't build it.
+2. Does the stdlib already do this? Use it.
+3. Does a native platform feature cover it? Use it.
+4. Does an already-installed dependency solve it? Use it.
+5. Can this be one line? Make it one line.
+6. Only then: write the minimum code that works.
+
+Ultra means:
+
+- Deletion before addition. If you can remove code to solve the problem, remove it.
+- Ship the one-liner and challenge the rest of the requirement in the same breath.
+- A hand-rolled abstraction is a bug farm with a hit rate. Say so.
+- Question complex requests: "Do you actually need X, or does Y cover it?"
+
+Mark intentional simplifications with a `declared:` comment naming the ceiling
+and the upgrade path: `// declared: O(n^2) scan, fine <10k rows; index at 50k`.
+
+Not lazy about: input validation at trust boundaries, error handling that
+prevents data loss, security, accessibility, anything explicitly requested.
+Non-trivial logic leaves ONE runnable check behind (an assert or one small
+test, no framework, no fixtures). Trivial one-liners need none.
+
+Output format when you skipped building something:
+  -> skipped: [X], add when [Y]

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/linux/hooks/subagent-stop-review.sh

@@ -1,103 +1,103 @@
-#!/usr/bin/env bash
-# subagent-stop-review.sh - subagentStop for Cursor (Linux).
-#
-# Counterpart of final-review.sh for delegated work. afterFileEdit DOES fire
-# inside subagents (verified: a subagent run left its edits in
-# session-edits-<subagent-cid>.txt), but subagents get no `stop` event, so
-# that marker is never drained and the five-axis review never fires for
-# delegated implementations. This hook closes the loop: when a subagent
-# finishes and ITS conversation has a session-edits marker, return ONE
-# followup_message so the subagent audits its own implementation before the
-# result goes back to the parent.
-#
-# Same bounding pattern as final-review.sh:
-#   - marker-gated: no edits in the subagent run -> no review, no noise,
-#   - reviewed-<cid>.flag one-shot brake: the stop AFTER the review pass
-#     clears flag + marker and ends the loop (one review per implementation;
-#     resumed subagents with a second implementation get a second review),
-#   - loop_limit in hooks.json caps runaway follow-ups harness-side,
-#   - only on status == 'completed' when a status field is present.
-#
-# If subagentStop's stdin carries a conversation_id that doesn't match the
-# id afterFileEdit used, the marker lookup misses and this emits {} - the
-# marker fold in post-tool-use.sh / final-review.sh still routes the
-# subagent's edits into the parent's stop review as the backstop.
-#
-# Always emits valid JSON ({} = no follow-up). Review body reuses
-# final-review.md (embedded fallback if missing).
-# Disable: HOOKS_ENFORCE=0 or SUBAGENT_REVIEW_ENFORCE=0.
-
-set +e
-. "$(dirname "$0")/hook-common.sh"
-
-emit_none() { printf '{}'; exit 0; }
-
-[ "${HOOKS_ENFORCE:-}" = "0" ] && emit_none
-[ "${SUBAGENT_REVIEW_ENFORCE:-}" = "0" ] && emit_none
-
-input="$(read_hook_stdin)"
-[ -n "$input" ] || emit_none
-
-status="$(json_get "$input" status)"
-cid="$(safe_conversation_id "$input")"
-
-pending_dir="$(hooks_pending_dir)"
-marker="$pending_dir/session-edits-$cid.txt"
-flag="$pending_dir/reviewed-$cid.flag"
-
-# One-shot brake: the previous subagentStop for this id emitted the review.
-if [ -f "$flag" ]; then
-    rm -f "$flag" "$marker" 2>/dev/null
-    emit_none
-fi
-
-# Review only a clean completion; otherwise clear the marker and stop.
-if [ -n "$status" ] && [ "$status" != "completed" ]; then
-    rm -f "$marker" 2>/dev/null
-    emit_none
-fi
-
-# No edits this run -> nothing to review.
-[ -f "$marker" ] || emit_none
-edited="$(grep -vE '^[[:space:]]*$' "$marker" 2>/dev/null | sort -u)"
-rm -f "$marker" 2>/dev/null
-[ -n "$edited" ] || emit_none
-
-# Compose the follow-up review prompt (md preferred, embedded fallback).
-prompt_file="$HOME/.agents/hooks/final-review.md"
-body=""
-[ -f "$prompt_file" ] && body="$(cat "$prompt_file")"
-if [ -z "$body" ]; then
-    body='Audit everything you changed in this run and FIX what fails (do NOT revert the
-behaviour the task asked for):
-  1. Correctness - logic, edge cases (null/empty/zero/boundary), language traps, security.
-  2. Reliability - error paths handled, no swallowed errors, resources released.
-  3. Coverage - behaviour-bearing changes have real tests; RUN the suite if present.
-  4. Anti-slop - if ~/.cursor/skills/anti-slop/scripts/scan_slop.py exists, run
-     `python ~/.cursor/skills/anti-slop/scripts/scan_slop.py --all`; otherwise
-     apply ~/.agents/hooks/anti-slop.md to the session diff.
-If an axis is clean, say so in one line. Then stop.'
-fi
-body="$(expand_agent_paths "$body")"
-
-file_list=""
-while IFS= read -r p; do
-    [ -n "$p" ] || continue
-    rp="$(resolve_agent_path "$p")"
-    file_list="${file_list}  ${rp}"$'\n'
-done <<EOF
-$edited
-EOF
-file_list="$(printf '%s' "$file_list" | head -n 30)"
-msg="SUBAGENT FINAL REVIEW - you just finished delegated implementation work. Before your result returns to the parent agent, audit it.
-
-Files you changed this run:
-$file_list
-
-$body"
-
-# Arm the one-shot brake BEFORE emitting, so a crash after emit can't re-fire.
-touch "$flag" 2>/dev/null
-
-emit_json followup_message "$msg"
-exit 0
+#!/usr/bin/env bash
+# subagent-stop-review.sh - subagentStop for Cursor (Linux).
+#
+# Counterpart of final-review.sh for delegated work. afterFileEdit DOES fire
+# inside subagents (verified: a subagent run left its edits in
+# session-edits-<subagent-cid>.txt), but subagents get no `stop` event, so
+# that marker is never drained and the five-axis review never fires for
+# delegated implementations. This hook closes the loop: when a subagent
+# finishes and ITS conversation has a session-edits marker, return ONE
+# followup_message so the subagent audits its own implementation before the
+# result goes back to the parent.
+#
+# Same bounding pattern as final-review.sh:
+#   - marker-gated: no edits in the subagent run -> no review, no noise,
+#   - reviewed-<cid>.flag one-shot brake: the stop AFTER the review pass
+#     clears flag + marker and ends the loop (one review per implementation;
+#     resumed subagents with a second implementation get a second review),
+#   - loop_limit in hooks.json caps runaway follow-ups harness-side,
+#   - only on status == 'completed' when a status field is present.
+#
+# If subagentStop's stdin carries a conversation_id that doesn't match the
+# id afterFileEdit used, the marker lookup misses and this emits {} - the
+# marker fold in post-tool-use.sh / final-review.sh still routes the
+# subagent's edits into the parent's stop review as the backstop.
+#
+# Always emits valid JSON ({} = no follow-up). Review body reuses
+# final-review.md (embedded fallback if missing).
+# Disable: HOOKS_ENFORCE=0 or SUBAGENT_REVIEW_ENFORCE=0.
+
+set +e
+. "$(dirname "$0")/hook-common.sh"
+
+emit_none() { printf '{}'; exit 0; }
+
+[ "${HOOKS_ENFORCE:-}" = "0" ] && emit_none
+[ "${SUBAGENT_REVIEW_ENFORCE:-}" = "0" ] && emit_none
+
+input="$(read_hook_stdin)"
+[ -n "$input" ] || emit_none
+
+status="$(json_get "$input" status)"
+cid="$(safe_conversation_id "$input")"
+
+pending_dir="$(hooks_pending_dir)"
+marker="$pending_dir/session-edits-$cid.txt"
+flag="$pending_dir/reviewed-$cid.flag"
+
+# One-shot brake: the previous subagentStop for this id emitted the review.
+if [ -f "$flag" ]; then
+    rm -f "$flag" "$marker" 2>/dev/null
+    emit_none
+fi
+
+# Review only a clean completion; otherwise clear the marker and stop.
+if [ -n "$status" ] && [ "$status" != "completed" ]; then
+    rm -f "$marker" 2>/dev/null
+    emit_none
+fi
+
+# No edits this run -> nothing to review.
+[ -f "$marker" ] || emit_none
+edited="$(grep -vE '^[[:space:]]*$' "$marker" 2>/dev/null | sort -u)"
+rm -f "$marker" 2>/dev/null
+[ -n "$edited" ] || emit_none
+
+# Compose the follow-up review prompt (md preferred, embedded fallback).
+prompt_file="$HOME/.agents/hooks/final-review.md"
+body=""
+[ -f "$prompt_file" ] && body="$(cat "$prompt_file")"
+if [ -z "$body" ]; then
+    body='Audit everything you changed in this run and FIX what fails (do NOT revert the
+behaviour the task asked for):
+  1. Correctness - logic, edge cases (null/empty/zero/boundary), language traps, security.
+  2. Reliability - error paths handled, no swallowed errors, resources released.
+  3. Coverage - behaviour-bearing changes have real tests; RUN the suite if present.
+  4. Anti-slop - if ~/.cursor/skills/anti-slop/scripts/scan_slop.py exists, run
+     `python ~/.cursor/skills/anti-slop/scripts/scan_slop.py --all`; otherwise
+     apply ~/.agents/hooks/anti-slop.md to the session diff.
+If an axis is clean, say so in one line. Then stop.'
+fi
+body="$(expand_agent_paths "$body")"
+
+file_list=""
+while IFS= read -r p; do
+    [ -n "$p" ] || continue
+    rp="$(resolve_agent_path "$p")"
+    file_list="${file_list}  ${rp}"$'\n'
+done <<EOF
+$edited
+EOF
+file_list="$(printf '%s' "$file_list" | head -n 30)"
+msg="SUBAGENT FINAL REVIEW - you just finished delegated implementation work. Before your result returns to the parent agent, audit it.
+
+Files you changed this run:
+$file_list
+
+$body"
+
+# Arm the one-shot brake BEFORE emitting, so a crash after emit can't re-fire.
+touch "$flag" 2>/dev/null
+
+emit_json followup_message "$msg"
+exit 0

package/linux/inject-doctrine.sh

@@ -16,7 +16,7 @@ set +e
 cat >/dev/null
 
 context=""
-for p in "$HOME/.cursor/doctrine.md" "$HOME/.cursor/USER-RULES.md"; do
+for p in "$HOME/.cursor/doctrine.md" "$HOME/.cursor/USER-RULES.md" "$HOME/.cursor/declared-editing.md"; do
     if [ -f "$p" ]; then
         part="$(cat "$p")"
         if [ -n "$context" ]; then context="$context

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursordoctrine",
-  "version": "0.3.0",
+  "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/declared-editing.md

@@ -0,0 +1,30 @@
+# Declared-editing — YAGNI ultra
+
+ACTIVE EVERY RESPONSE. No drift back to over-building. Still active if unsure.
+
+Before writing any code, stop at the first rung that holds:
+
+1. Does this need to exist at all? (YAGNI) If no — say so, don't build it.
+2. Does the stdlib already do this? Use it.
+3. Does a native platform feature cover it? Use it.
+4. Does an already-installed dependency solve it? Use it.
+5. Can this be one line? Make it one line.
+6. Only then: write the minimum code that works.
+
+Ultra means:
+
+- Deletion before addition. If you can remove code to solve the problem, remove it.
+- Ship the one-liner and challenge the rest of the requirement in the same breath.
+- A hand-rolled abstraction is a bug farm with a hit rate. Say so.
+- Question complex requests: "Do you actually need X, or does Y cover it?"
+
+Mark intentional simplifications with a `declared:` comment naming the ceiling
+and the upgrade path: `// declared: O(n^2) scan, fine <10k rows; index at 50k`.
+
+Not lazy about: input validation at trust boundaries, error handling that
+prevents data loss, security, accessibility, anything explicitly requested.
+Non-trivial logic leaves ONE runnable check behind (an assert or one small
+test, no framework, no fixtures). Trivial one-liners need none.
+
+Output format when you skipped building something:
+  -> skipped: [X], add when [Y]

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.
 '@
 }

package/windows/inject-doctrine.ps1

@@ -1,58 +1,59 @@
-# inject-doctrine.ps1 - Cursor sessionStart injection.
-#
-# Emits {"additional_context": "<doctrine + USER-RULES>"} as PURE-ASCII JSON.
-#
-# Why pure ASCII: the doctrine contains multi-byte UTF-8 characters (em dash,
-# section sign, <=, arrows). Written as UTF-8, their continuation bytes
-# (0x80-0x9F) get decoded by Cursor's JSON reader as C1 control characters ->
-# "Bad control character in string literal in JSON at position N". Escaping every
-# non-ASCII char to \uXXXX makes the output byte-identical under EVERY encoding,
-# so it cannot be mangled; JSON.parse turns § back into the real char. We
-# also write the bytes straight to stdout to bypass [Console]::OutputEncoding.
-#
-# Fail open: missing files or any error -> "{}" (valid, empty). Never block or
-# crash session start.
-
-$ErrorActionPreference = 'SilentlyContinue'
-
-# Drain stdin (Cursor sends session metadata) so the pipe never blocks.
-$null = [Console]::In.ReadToEnd()
-
-function Write-StdoutAscii([string]$s) {
-    # Write exact ASCII bytes to stdout, immune to whatever [Console]::OutputEncoding is.
-    $bytes = [System.Text.Encoding]::ASCII.GetBytes($s)
-    $stdout = [Console]::OpenStandardOutput()
-    $stdout.Write($bytes, 0, $bytes.Length)
-    $stdout.Flush()
-}
-
-try {
-    $paths = @(
-        (Join-Path $PSScriptRoot 'doctrine.md'),
-        (Join-Path $PSScriptRoot 'USER-RULES.md')
-    )
-
-    $parts = foreach ($p in $paths) {
-        if (Test-Path -LiteralPath $p) { Get-Content -Raw -LiteralPath $p }
-    }
-    $context = ($parts -join "`n`n").Trim()
-
-    if (-not $context) { Write-StdoutAscii '{}'; exit 0 }
-
-    $json = @{ additional_context = $context } | ConvertTo-Json -Compress
-
-    # Escape every non-ASCII (and any stray control) char to \uXXXX -> pure ASCII.
-    # ConvertTo-Json's structural chars and \n / \" escapes are ASCII and pass through.
-    $sb = [System.Text.StringBuilder]::new($json.Length + 64)
-    foreach ($ch in $json.ToCharArray()) {
-        $code = [int][char]$ch
-        if ($code -lt 32 -or $code -gt 126) { [void]$sb.AppendFormat('\u{0:x4}', $code) }
-        else { [void]$sb.Append($ch) }
-    }
-    Write-StdoutAscii $sb.ToString()
-}
-catch {
-    Write-StdoutAscii '{}'
-}
-
-exit 0
+# inject-doctrine.ps1 - Cursor sessionStart injection.
+#
+# Emits {"additional_context": "<doctrine + USER-RULES>"} as PURE-ASCII JSON.
+#
+# Why pure ASCII: the doctrine contains multi-byte UTF-8 characters (em dash,
+# section sign, <=, arrows). Written as UTF-8, their continuation bytes
+# (0x80-0x9F) get decoded by Cursor's JSON reader as C1 control characters ->
+# "Bad control character in string literal in JSON at position N". Escaping every
+# non-ASCII char to \uXXXX makes the output byte-identical under EVERY encoding,
+# so it cannot be mangled; JSON.parse turns § back into the real char. We
+# also write the bytes straight to stdout to bypass [Console]::OutputEncoding.
+#
+# Fail open: missing files or any error -> "{}" (valid, empty). Never block or
+# crash session start.
+
+$ErrorActionPreference = 'SilentlyContinue'
+
+# Drain stdin (Cursor sends session metadata) so the pipe never blocks.
+$null = [Console]::In.ReadToEnd()
+
+function Write-StdoutAscii([string]$s) {
+    # Write exact ASCII bytes to stdout, immune to whatever [Console]::OutputEncoding is.
+    $bytes = [System.Text.Encoding]::ASCII.GetBytes($s)
+    $stdout = [Console]::OpenStandardOutput()
+    $stdout.Write($bytes, 0, $bytes.Length)
+    $stdout.Flush()
+}
+
+try {
+    $paths = @(
+        (Join-Path $PSScriptRoot 'doctrine.md'),
+        (Join-Path $PSScriptRoot 'USER-RULES.md'),
+        (Join-Path $PSScriptRoot 'declared-editing.md')
+    )
+
+    $parts = foreach ($p in $paths) {
+        if (Test-Path -LiteralPath $p) { Get-Content -Raw -LiteralPath $p }
+    }
+    $context = ($parts -join "`n`n").Trim()
+
+    if (-not $context) { Write-StdoutAscii '{}'; exit 0 }
+
+    $json = @{ additional_context = $context } | ConvertTo-Json -Compress
+
+    # Escape every non-ASCII (and any stray control) char to \uXXXX -> pure ASCII.
+    # ConvertTo-Json's structural chars and \n / \" escapes are ASCII and pass through.
+    $sb = [System.Text.StringBuilder]::new($json.Length + 64)
+    foreach ($ch in $json.ToCharArray()) {
+        $code = [int][char]$ch
+        if ($code -lt 32 -or $code -gt 126) { [void]$sb.AppendFormat('\u{0:x4}', $code) }
+        else { [void]$sb.Append($ch) }
+    }
+    Write-StdoutAscii $sb.ToString()
+}
+catch {
+    Write-StdoutAscii '{}'
+}
+
+exit 0