cursordoctrine 0.4.0 → 0.4.2

package/INSTALL.md

@@ -26,7 +26,7 @@ Do not guess from the shell you happen to be running in — a Windows machine dr
 
 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).
+- Windows: **PowerShell 7 (`pwsh`) on PATH**, plus `git`. Python 3.9+ if you want the anti-slop scanner (the hooks work without it). Confirm with `pwsh -Version` — Windows PowerShell 5.1 (`powershell.exe`) is NOT supported; install PowerShell 7 via `winget install --id Microsoft.PowerShell --source winget` if missing.
 - 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
@@ -36,7 +36,7 @@ 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
+Copy-Item windows\inject-doctrine.ps1, windows\doctrine.md, windows\USER-RULES.md, windows\declared-editing.md, windows\pre-compile.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 '\\', '/'
@@ -51,7 +51,7 @@ 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/inject-doctrine.sh linux/doctrine.md linux/USER-RULES.md linux/declared-editing.md linux/pre-compile.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):
@@ -76,6 +76,11 @@ echo '{"conversation_id":"t1","status":"completed"}' | bash ~/.agents/hooks/fina
 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
+# anchor-set nudge: fires PRE-COMPILE NUDGE on the first edit, silent on the second
+echo '{"conversation_id":"t3","file_path":"/tmp/x.py"}' | bash ~/.agents/hooks/anchor-set-nudge.sh
+echo '{"conversation_id":"t3"}'       | bash ~/.agents/hooks/post-tool-use.sh     # expect additional_context containing "PRE-COMPILE NUDGE"
+echo '{"conversation_id":"t3","file_path":"/tmp/y.py"}' | bash ~/.agents/hooks/anchor-set-nudge.sh  # second edit -> flag armed -> silent
+echo '{"conversation_id":"t3"}'       | bash ~/.agents/hooks/post-tool-use.sh     # expect {} (nothing new stashed)
 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)
 ```
@@ -91,6 +96,10 @@ Windows (same payloads, swap `bash ~/...sh` for `pwsh.exe -NoProfile -File $HOME
 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 {}
+# anchor-set nudge: fires PRE-COMPILE NUDGE on the first edit, silent on the second
+echo '{"conversation_id":"t3","file_path":"C:\tmp\x.py"}' | pwsh.exe -NoProfile -File $HOME\.agents\hooks\anchor-set-nudge.ps1
+echo '{"conversation_id":"t3"}'  | pwsh.exe -NoProfile -File $HOME\.agents\hooks\post-tool-use.ps1   # additional_context with "PRE-COMPILE NUDGE"
+echo '{"conversation_id":"t3","file_path":"C:\tmp\y.py"}' | pwsh.exe -NoProfile -File $HOME\.agents\hooks\anchor-set-nudge.ps1  # second edit -> silent
 python $HOME\.cursor\skills\anti-slop\scripts\scan_slop.py --help
 ```
 
@@ -99,15 +108,16 @@ 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.
+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; ask "what is the Anchor Set?" and it should answer from `pre-compile.md` (Objective / Constraints / Scope / Deterministic success).
+3. Have the agent make a small edit to a tracked file. On the next turn it should receive a `SELF-REVIEW TRIGGER` message, and (if it's the first edit of that turn) a `PRE-COMPILE NUDGE` reminder to write its Anchor Set to `.scope.json`. The nudge re-fires on the first edit of each new turn.
 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.
+8. (Optional, opt-in scope gate) Have the agent write a `.scope.json` in the repo root (`intent` + `files[]` + `acceptance`), then edit a file outside `files[]`. The next turn should carry a `[SCOPE VIOLATION]` advisory quoting the declared `intent` and `acceptance`. Delete the file to disable the gate.
 
 ## 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` (deprecated in 0.3.0), `SEMANTIC_DENSITY_ENFORCE=0`, `SCOPE_GATE_ENFORCE=0`, `ANTI_SLOP_ENFORCE=0`, `FINAL_REVIEW_ENFORCE=0`, `SUBAGENT_REVIEW_ENFORCE=0`.
+Kill switches if something misbehaves: `HOOKS_ENFORCE=0` (everything advisory off), `PERM_GATE_ENFORCE=0`, `ANCHOR_NUDGE_ENFORCE=0` (pre-compile nudge off), `MINIMAL_EDITING_ENFORCE=0` (deprecated in 0.3.0), `SEMANTIC_DENSITY_ENFORCE=0`, `SCOPE_GATE_ENFORCE=0`, `ANTI_SLOP_ENFORCE=0`, `FINAL_REVIEW_ENFORCE=0`, `SUBAGENT_REVIEW_ENFORCE=0`.

package/README.md

@@ -9,8 +9,8 @@
 
 <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>
+  <p><strong>Self-review hooks for Cursor — proactive and reactive.</strong></p>
+  <p>Five hook events, one message bus.<br />The model compiles its intent, audits its own work, and stays on the rails. Cursor carries context and gates blast radius.</p>
 </div>
 
 <br />
@@ -19,18 +19,35 @@
 
 ## What this is
 
-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:
+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. Four jobs:
 
-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.
+1. **Compile intent before coding** (proactive) — at session start the agent gets the doctrine plus the **Anchor Set** discipline (`pre-compile.md`): before writing code it must emit *Objective / Constraints / Scope / Deterministic success*, and write that contract to `.scope.json`. On the first edit of each agent turn a `anchor-set-nudge` advisory fires to catch intent dilution at token ~50 instead of waiting for the stop-hook review at token ~5000.
+2. **Inject the doctrine** at session start — every chat starts with the same short governing text (`doctrine.md`, `USER-RULES.md`, `declared-editing.md` the YAGNI ultra ladder, and `pre-compile.md` the thin intent-compilation phase).
+3. **Hand the model its own edits back** (reactive) — after each agent edit, a self-review prompt goes into a pending file (plus semantic-density, scope-gate, anti-slop, and the pre-compile nudge advisories when they trip). Next turn the model reads its diff, fixes real bugs, stays quiet otherwise.
+4. **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, 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.
+When an implementation finishes, the stop hook runs one final review over everything that changed, then stops. Six 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.
 
 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`.
 
 Cursor only. Installs into `~/.cursor` and `~/.agents/hooks`. Doesn't touch your projects.
 
+## Prerequisites
+
+> **PowerShell 7 (`pwsh`) is required on Windows.** The hooks run via `pwsh.exe -NoProfile -File ...`. Windows PowerShell 5.1 (`powershell.exe`) is not supported — install PowerShell 7 separately.
+
+| Platform | Required | Optional (recommended) |
+|---|---|---|
+| **Windows** | `git`, **PowerShell 7 (`pwsh`) on PATH** | Python 3.9+ (powers the anti-slop scanner; hooks work without it) |
+| **Linux / SSH remotes** | `bash`, `git`, and `jq` **or** `python3` | Python 3.9+ (anti-slop scanner) |
+
+Install PowerShell 7:
+
+- **Windows**: `winget install --id Microsoft.PowerShell --source winget` (or grab the MSI from the [PowerShell GitHub releases](https://github.com/PowerShell/PowerShell/releases)). Confirm with `pwsh -Version`.
+- **Linux**: follow the [official package instructions](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-linux) — only needed if you run the `windows/` pack on a Linux box (unusual); normal Linux installs use the `linux/` bash pack.
+
+`npx cursordoctrine install` warns at the end if `pwsh` (Windows) or `bash`+`jq`/`python3` (Linux) or Python are missing, so you'll know up front.
+
 ## Install
 
 Node 18+:
@@ -44,38 +61,72 @@ Restart Cursor after install — `hooks.json` is read at startup. `install` is i
 
 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 proactive phase: the Anchor Set
+
+The reactive stack (self-review, anti-slop, final-review) only fires *after* code exists. If the agent drifted from the request on its first token, a clean final review of the wrong feature is still the wrong feature. The pre-compile phase puts the right feature on the rails first.
+
+`pre-compile.md` (injected at session start alongside the doctrine) asks the agent to emit, terse, before any code:
+
+1. **OBJECTIVE** — one operational sentence. Not "improve X" but "make X return Y when Z".
+2. **CONSTRAINTS** — local negations: what it will NOT do (no schema migration, no new dep, no refactor of the surrounding function).
+3. **SCOPE** — files to touch (exact, derived from the objective) and files untouchable.
+4. **DETERMINISTIC SUCCESS** — the one command, test, or observable check that decides done.
+
+It then writes that contract to `.scope.json` in the repo root:
+
+```json
+{
+  "intent": "make /api/login return 401 instead of 500 on a bad password",
+  "files": ["src/api/login.ts", "tests/login.test.ts"],
+  "acceptance": "tests/login.test.ts passes; curl /api/login with wrong password returns 401",
+  "allow_growth": false
+}
+```
+
+Two machine-checkable consequences:
+
+- **`scope-gate-audit`** (afterFileEdit, opt-in via `.scope.json` existing) audits every edit against `files[]` and quotes `intent` + `acceptance` back on a violation. Editing outside the declared set is the textbook scope-creep signal.
+- **final-review axis 0** (intent trace) traces every diff hunk back to `intent`. Anything untraceable is a hallucinated requirement.
+
+On the **first edit of each agent turn**, `anchor-set-nudge` drops a reminder into the feedback bus: *did you write your Anchor Set to `.scope.json`?* One nudge per turn — the latch is armed on that first edit and cleared **unconditionally** by the stop hook on every turn boundary, so the next turn re-earns its nudge. A long chat with N turns gets up to N nudges, and the latch can never get stranded silenced mid-session.
+
+The Anchor Set is skipped for trivial one-liners (typo, literal) — the `declared-editing.md` ladder's rung 1 governs when it's overkill.
+
 ## The five flows
 
 | Flow | Event | What happens |
 |---|---|---|
-| Session | `sessionStart` | `inject-doctrine` reads doctrine + user rules + declared-editing and emits them as `additional_context`. |
+| Session | `sessionStart` | `inject-doctrine` reads doctrine + user rules + declared-editing + **pre-compile** 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. |
+| Edit | `afterFileEdit` + `stop` | **Proactive:** `anchor-set-nudge` fires once per turn (on its first edit) to push the Anchor Set. **Reactive:** `self-review-trigger` stashes the review prompt per edit; `minimal-edit-audit` (deprecated), `semantic-density-audit`, `scope-gate-audit` (opt-in, audits `.scope.json`), and `anti-slop-audit` append advisories when they trip; `final-review` fires one end-of-implementation six-axis 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`. |
 
 ## Layout
 
 ```
-windows/          PowerShell hooks (pwsh) — install on Windows machines
+windows/          PowerShell 7 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
+  inject-doctrine.ps1, doctrine.md, USER-RULES.md,
+  declared-editing.md, pre-compile.md
+  hooks/          the ten hook scripts + hook-common.ps1 (shared) + 3 prompt files
+                  (anti-slop.md, self-review.md, final-review.md)
 linux/            bash hooks — install on Linux machines and SSH remotes
-  hooks.json, inject-doctrine.sh, doctrine.md, USER-RULES.md, declared-editing.md
+  hooks.json, inject-doctrine.sh, doctrine.md, USER-RULES.md,
+  declared-editing.md, pre-compile.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)
+                  scripts/scope_match.py — the .scope.json matcher shared by
+                  scope-gate-audit and final-review (returns intent + acceptance)
 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
 ```
 
-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).
+Both folders do the same thing. Windows runs everything through `pwsh.exe` (PowerShell 7 — Windows PowerShell 5.1 is not supported). 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
 
@@ -85,6 +136,7 @@ All hooks fail open and always exit 0. Nothing here can block your session.
 |---|---|---|
 | `HOOKS_ENFORCE=0` | on | turns off all advisory hooks at once |
 | `PERM_GATE_ENFORCE=0` | on | disables the permission gate |
+| `ANCHOR_NUDGE_ENFORCE=0` | on | disables the pre-compile nudge (first-edit Anchor Set reminder) |
 | `MINIMAL_EDITING_ENFORCE=0` | on | disables the over-edit advisory (deprecated in 0.3.0) |
 | `SCOPE_GATE_ENFORCE=0` | on | disables the declared-scope advisory (opt-in: only fires when `.scope.json` exists) |
 | `SEMANTIC_DENSITY_ENFORCE=0` | on | disables the semantic-opacity advisory |
@@ -98,7 +150,8 @@ All hooks fail open and always exit 0. Nothing here can block your session.
 
 - **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.
+- **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. The `anchor-set-nudge` latch is separate and simpler: it's cleared **unconditionally** on every stop, so the nudge re-fires on the first edit of each new turn and can never get stranded silenced mid-session.
+- **The `.scope.json` contract is opt-in.** No `.scope.json` in the repo root → `scope-gate-audit` stays silent and the system falls back to the `declared-editing` ladder plus the final-review footprint check. Writing the file is how the agent opts into a machine-checked scope.
 - **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.

package/bin/cli.mjs

@@ -263,19 +263,40 @@ function verify() {
     return true;
   });
 
-  check('anchor-set nudge fires on first edit, then goes quiet', () => {
-    // First edit of the implementation -> the pre-compile nudge stashes its
-    // advisory in the pending feedback bus and arms the one-shot flag.
-    const first = runHook(hook('anchor-set-nudge'), { conversation_id: 'npxv3', file_path: join(HOME, 'x.py') });
-    if (!first.includes('additional_context') || !first.includes('PRE-COMPILE NUDGE')) {
-      // anchor-set-nudge appends to feedback-<cid>.txt (the shared bus) rather
-      // than emitting JSON directly; drain it the same way post-tool-use does.
-      const drained = runHook(hook('post-tool-use'), { conversation_id: 'npxv3' });
-      if (!drained.includes('PRE-COMPILE NUDGE')) return { ok: false, detail: 'nudge did not reach the feedback bus on first edit' };
+  check('anchor-set nudge fires once per turn, stop re-arms it', () => {
+    // anchor-set-nudge appends to feedback-<cid>.txt (the shared bus) rather
+    // than emitting JSON directly; drain it the same way post-tool-use does.
+    const drainedOf = (cidv) => runHook(hook('post-tool-use'), { conversation_id: cidv });
+
+    // --- Turn 1 -------------------------------------------------------------
+    // First edit -> nudge stashes into the feedback bus and arms the latch.
+    runHook(hook('anchor-set-nudge'), { conversation_id: 'npxv3', file_path: join(HOME, 'x.py') });
+    if (!drainedOf('npxv3').includes('PRE-COMPILE NUDGE')) {
+      return { ok: false, detail: 'nudge did not reach the feedback bus on first edit' };
+    }
+    // Second edit same turn -> latch armed, nudge must stay silent.
+    runHook(hook('anchor-set-nudge'), { conversation_id: 'npxv3', file_path: join(HOME, 'y.py') });
+    if (drainedOf('npxv3').includes('PRE-COMPILE NUDGE')) {
+      return { ok: false, detail: 'nudge re-fired on second edit (latch not gating)' };
+    }
+    // End of turn: final-review clears the latch unconditionally. Drive a
+    // review-less stop (no session-edits marker) so it hits the clear path and
+    // exits {}, same as a turn that produced no reviewable edits.
+    const stopOut = runHook(hook('final-review'), { conversation_id: 'npxv3', status: 'completed' });
+    if (stopOut !== '{}' && stopOut.replace(/\s/g, '') !== '{}') {
+      // A review fired (fine - the earlier edit left a session-edits marker via
+      // self-review-trigger if one ran). What matters is the latch got cleared;
+      // we verify that with the next-turn re-fire below.
+    }
+    // --- Turn 2 -------------------------------------------------------------
+    // First edit of the NEXT turn -> latch was cleared at the stop boundary, so
+    // the nudge MUST re-fire. This is the regression that 0.4.0 shipped broken:
+    // the latch only cleared on the fragile second-stop path, so it stranded
+    // and the nudge went permanently silent mid-session.
+    runHook(hook('anchor-set-nudge'), { conversation_id: 'npxv3', file_path: join(HOME, 'z.py') });
+    if (!drainedOf('npxv3').includes('PRE-COMPILE NUDGE')) {
+      return { ok: false, detail: 'nudge did NOT re-fire on the next turn (latch stranded at the stop boundary)' };
     }
-    // Second edit -> flag is armed, nudge must stay silent.
-    const second = runHook(hook('anchor-set-nudge'), { conversation_id: 'npxv3', file_path: join(HOME, 'y.py') });
-    if (second.includes('PRE-COMPILE NUDGE')) return { ok: false, detail: 'nudge re-fired on second edit (flag not gating)' };
     return true;
   });
 
@@ -388,6 +409,7 @@ Examples
 Kill switches (environment variables, all hooks fail open)
   HOOKS_ENFORCE=0              everything advisory off
   PERM_GATE_ENFORCE=0          permission gate off
+  ANCHOR_NUDGE_ENFORCE=0       pre-compile nudge off (first-edit Anchor Set reminder)
   MINIMAL_EDITING_ENFORCE=0    over-edit advisory off (deprecated in 0.3.0)
   SEMANTIC_DENSITY_ENFORCE=0   semantic-opacity advisory off
   SCOPE_GATE_ENFORCE=0         declared-scope advisory off

package/linux/hooks/anchor-set-nudge.sh

@@ -2,20 +2,20 @@
 # anchor-set-nudge.sh - afterFileEdit "pre-compile" nudge (Cursor, Linux).
 #
 # Proactive counterpart to the reactive audits. On the FIRST file edit of an
-# implementation (per conversation), remind the agent to compile its Anchor Set
-# (pre-compile.md) and write .scope.json BEFORE piling on more code. The
-# reactive stack (self-review, anti-slop, final-review) only fires AFTER code
-# exists; this nudge catches intent dilution at token ~50, not at the ~5000 of
-# the stop-hook axis 0. A clean final review of the wrong feature is still the
-# wrong feature - the Anchor Set exists so the right feature is on the rails
-# from the first edit.
+# agent turn, remind the agent to compile its Anchor Set (pre-compile.md) and
+# write .scope.json BEFORE piling on more code. The reactive stack (self-review,
+# anti-slop, final-review) only fires AFTER code exists; this nudge catches
+# intent dilution at token ~50, not at the ~5000 of the stop-hook axis 0. A
+# clean final review of the wrong feature is still the wrong feature - the
+# Anchor Set exists so the right feature is on the rails from the first edit.
 #
-# One-shot PER IMPLEMENTATION, not per session: gated by an
-# anchor-declared-<cid>.flag in the pending dir. That flag is cleared by
-# final-review.sh / subagent-stop-review.sh at the SAME per-implementation
-# boundary where they clear session-edits-<cid>.txt and reviewed-<cid>.flag
-# (the stop after a review pass). So a long conversation with N implementations
-# gets N nudges, not one - every new body of work re-earns the reminder.
+# Fires ONCE PER TURN (per conversation): gated by an anchor-declared-<cid>.flag
+# in the pending dir, armed here on first edit and cleared UNCONDITIONALLY by
+# final-review.sh / subagent-stop-review.sh on every stop. So a long
+# conversation with N turns gets up to N nudges - every new turn re-earns the
+# reminder on its first edit. The clear is unconditional (not gated on the
+# reviewed-flag path) so the latch can never get stranded silenced mid-session,
+# which would silently stop reminding the agent to write .scope.json.
 #
 # Advisory only: never blocks, never reads the diff, ALWAYS exits 0. Appends to
 # the shared feedback-<cid>.txt bus; post-tool-use.sh delivers it next turn.

package/linux/hooks/final-review.sh

@@ -41,11 +41,16 @@ anchor_flag="$pending_dir/anchor-declared-$cid.flag"
 # Sweep state from sessions that died before their stop hook ran.
 find "$pending_dir" -maxdepth 1 -type f -mtime +7 -delete 2>/dev/null
 
+# Unconditionally clear the pre-compile nudge's per-turn latch. Every stop is a
+# turn boundary; clearing here (not only inside the reviewed-flag block below)
+# guarantees the nudge re-fires on the first edit of the NEXT turn and can never
+# get stranded silenced. Clearing it only on the SECOND stop left the nudge
+# permanently off for any conversation that never cleanly hit that boundary.
+rm -f "$anchor_flag" 2>/dev/null
+
 # One-shot brake: the previous stop for this conversation emitted the review.
-# Also clear anchor-declared-<cid>.flag so the pre-compile nudge re-fires for
-# the NEXT implementation (one nudge per body of work, not per session).
 if [ -f "$flag" ]; then
-    rm -f "$flag" "$marker" "$anchor_flag" 2>/dev/null
+    rm -f "$flag" "$marker" 2>/dev/null
     emit_none
 fi
 

package/linux/hooks/subagent-stop-review.sh

@@ -4,7 +4,7 @@
 # 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
+# that marker is never drained and the six-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
@@ -46,11 +46,14 @@ marker="$pending_dir/session-edits-$cid.txt"
 flag="$pending_dir/reviewed-$cid.flag"
 anchor_flag="$pending_dir/anchor-declared-$cid.flag"
 
+# Unconditionally clear the pre-compile nudge's per-turn latch so it re-fires
+# on the first edit of the next subagent run. Clearing here (not only inside
+# the reviewed-flag block below) can never strand the nudge silenced.
+rm -f "$anchor_flag" 2>/dev/null
+
 # One-shot brake: the previous subagentStop for this id emitted the review.
-# Also clear anchor-declared-<cid>.flag so the pre-compile nudge re-fires for
-# the next subagent implementation (one nudge per body of work).
 if [ -f "$flag" ]; then
-    rm -f "$flag" "$marker" "$anchor_flag" 2>/dev/null
+    rm -f "$flag" "$marker" 2>/dev/null
     emit_none
 fi
 

package/linux/hooks.json

@@ -43,7 +43,7 @@
         "command": "bash ~/.agents/hooks/anchor-set-nudge.sh",
         "timeout": 5,
         "matcher": "^(Write|StrReplace|EditNotebook)$",
-        "_comment": "5s: PROACTIVE pre-compile nudge. On the FIRST edit of each implementation (per conversation), remind the agent to compile its Anchor Set (pre-compile.md) into .scope.json BEFORE piling on more code. The reactive audits (self-review / anti-slop / final-review axis 0) only fire after code exists; this catches intent dilution at token ~50 instead of ~5000. One-shot per implementation: gated by anchor-declared-<cid>.flag, which final-review.sh / subagent-stop-review.sh clear at the same per-implementation boundary as reviewed-<cid>.flag. Advisory only; never blocks. Disable: HOOKS_ENFORCE=0 or ANCHOR_NUDGE_ENFORCE=0."
+        "_comment": "5s: PROACTIVE pre-compile nudge. On the FIRST edit of each agent turn (per conversation), remind the agent to compile its Anchor Set (pre-compile.md) into .scope.json BEFORE piling on more code. The reactive audits (self-review / anti-slop / final-review axis 0) only fire after code exists; this catches intent dilution at token ~50 instead of ~5000. One-shot per turn: gated by anchor-declared-<cid>.flag, armed here on first edit and cleared UNCONDITIONALLY by final-review.sh / subagent-stop-review.sh on every stop - so it re-fires on the first edit of the next turn and can never get stranded silenced. Advisory only; never blocks. Disable: HOOKS_ENFORCE=0 or ANCHOR_NUDGE_ENFORCE=0."
       }
     ],
     "postToolUse": [

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cursordoctrine",
-  "version": "0.4.0",
-  "description": "Thin self-review hooks for Cursor — the model is the auditor. Pre-compile Anchor Set phase (proactive intent compilation), intent-trace final review (Tier 0), unified 13-item anti-slop checklist, operational slop detection.",
+  "version": "0.4.2",
+  "description": "Thin self-review hooks for Cursor — the model is the auditor. Pre-compile Anchor Set phase (proactive intent compilation, fires once per turn), intent-trace final review (Tier 0), unified 13-item anti-slop checklist, operational slop detection.",
   "bin": {
     "cursordoctrine": "bin/cli.mjs"
   },

package/skills/anti-slop/SKILL.md

@@ -228,8 +228,8 @@ The `stop` hook (`~/.agents/hooks/final-review.ps1` on Windows,
 `~/.agents/hooks/final-review.sh` on Linux) fires after the agent finishes an
 implementation that edited files. It extracts the last `<user_query>` from the
 session transcript (Tier 0 intent trace), reports session footprint (Tier 5),
-and auto-submits a `followup_message` so the model audits five axes: intent,
-correctness, reliability, coverage, anti-slop. Axis 4 delegates to this skill's
+and auto-submits a `followup_message` so the model audits six axes: intent,
+correctness, reliability, coverage, anti-slop, wiring completeness. Axis 4 delegates to this skill's
 scanner (`scan_slop.py --all`) and the canonical checklist at
 `~/.agents/hooks/anti-slop.md` (13 items, including semantic contracts,
 operational slop, and change surface). One bounded pass per implementation.

package/windows/hooks/anchor-set-nudge.ps1

@@ -1,20 +1,20 @@
 # anchor-set-nudge.ps1 - afterFileEdit "pre-compile" nudge (Cursor).
 #
 # Proactive counterpart to the reactive audits. On the FIRST file edit of an
-# implementation (per conversation), remind the agent to compile its Anchor Set
-# (pre-compile.md) and write .scope.json BEFORE piling on more code. The
-# reactive stack (self-review, anti-slop, final-review) only fires AFTER code
-# exists; this nudge catches intent dilution at token ~50, not at the ~5000 of
-# the stop-hook axis 0. A clean final review of the wrong feature is still the
-# wrong feature - the Anchor Set exists so the right feature is on the rails
-# from the first edit.
+# agent turn, remind the agent to compile its Anchor Set (pre-compile.md) and
+# write .scope.json BEFORE piling on more code. The reactive stack (self-review,
+# anti-slop, final-review) only fires AFTER code exists; this nudge catches
+# intent dilution at token ~50, not at the ~5000 of the stop-hook axis 0. A
+# clean final review of the wrong feature is still the wrong feature - the
+# Anchor Set exists so the right feature is on the rails from the first edit.
 #
-# One-shot PER IMPLEMENTATION, not per session: gated by an
-# anchor-declared-<cid>.flag in the pending dir. That flag is cleared by
-# final-review.ps1 / subagent-stop-review.ps1 at the SAME per-implementation
-# boundary where they clear session-edits-<cid>.txt and reviewed-<cid>.flag
-# (the stop after a review pass). So a long conversation with N implementations
-# gets N nudges, not one - every new body of work re-earns the reminder.
+# Fires ONCE PER TURN (per conversation): gated by an anchor-declared-<cid>.flag
+# in the pending dir, armed here on first edit and cleared UNCONDITIONALLY by
+# final-review.ps1 / subagent-stop-review.ps1 on every stop. So a long
+# conversation with N turns gets up to N nudges - every new turn re-earns the
+# reminder on its first edit. The clear is unconditional (not gated on the
+# reviewed-flag path) so the latch can never get stranded silenced mid-session,
+# which would silently stop reminding the agent to write .scope.json.
 #
 # Advisory only: never blocks, never reads the diff, ALWAYS exits 0. Appends to
 # the shared feedback-<cid>.txt bus; post-tool-use.ps1 delivers it next turn.

package/windows/hooks/final-review.ps1

@@ -48,12 +48,19 @@ Get-ChildItem $pendingDir -File -ErrorAction SilentlyContinue |
     Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-7) } |
     Remove-Item -Force -ErrorAction SilentlyContinue
 
+# Unconditionally clear the pre-compile nudge's per-turn latch. Every stop is a
+# turn boundary; clearing here (not only inside the reviewed-flag block below)
+# guarantees the nudge re-fires on the first edit of the NEXT turn and can never
+# get stranded silenced. The original design cleared anchor-declared-<cid>.flag
+# only on the SECOND stop (the reviewed-flag path), so any conversation that
+# never cleanly hit that boundary left the nudge permanently off - the agent
+# then stopped being reminded to write .scope.json.
+Remove-Item $anchorFlag -Force -ErrorAction SilentlyContinue
+
 # One-shot brake: the previous stop for this conversation emitted the review.
 # Clear the flag (and whatever the review pass itself edited) and end the loop.
-# Also clear anchor-declared-<cid>.flag so the pre-compile nudge re-fires for
-# the NEXT implementation (one nudge per body of work, not per session).
 if (Test-Path $flag) {
-    Remove-Item $flag, $marker, $anchorFlag -Force -ErrorAction SilentlyContinue
+    Remove-Item $flag, $marker -Force -ErrorAction SilentlyContinue
     Emit-None
 }
 

package/windows/hooks/subagent-stop-review.ps1

@@ -3,7 +3,7 @@
 # Counterpart of final-review.ps1 for delegated work. afterFileEdit DOES fire
 # inside subagents (verified: a poteto subagent run left ~58 entries 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
+# that marker is never drained and the six-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
@@ -45,11 +45,14 @@ $marker = Join-Path $pendingDir "session-edits-$cid.txt"
 $flag   = Join-Path $pendingDir "reviewed-$cid.flag"
 $anchorFlag = Join-Path $pendingDir "anchor-declared-$cid.flag"
 
+# Unconditionally clear the pre-compile nudge's per-turn latch so it re-fires
+# on the first edit of the next subagent run. Clearing here (not only inside
+# the reviewed-flag block below) can never strand the nudge silenced.
+Remove-Item $anchorFlag -Force -ErrorAction SilentlyContinue
+
 # One-shot brake: the previous subagentStop for this id emitted the review.
-# Also clear anchor-declared-<cid>.flag so the pre-compile nudge re-fires for
-# the next subagent implementation (one nudge per body of work).
 if (Test-Path $flag) {
-    Remove-Item $flag, $marker, $anchorFlag -Force -ErrorAction SilentlyContinue
+    Remove-Item $flag, $marker -Force -ErrorAction SilentlyContinue
     Emit-None
 }
 

package/windows/hooks.json

@@ -43,7 +43,7 @@
         "command": "pwsh.exe -NoProfile -File ~/.agents/hooks/anchor-set-nudge.ps1",
         "timeout": 5,
         "matcher": "^(Write|StrReplace|EditNotebook)$",
-        "_comment": "5s: PROACTIVE pre-compile nudge. On the FIRST edit of each implementation (per conversation), remind the agent to compile its Anchor Set (pre-compile.md) into .scope.json BEFORE piling on more code. The reactive audits (self-review / anti-slop / final-review axis 0) only fire after code exists; this catches intent dilution at token ~50 instead of ~5000. One-shot per implementation: gated by anchor-declared-<cid>.flag, which final-review.ps1 / subagent-stop-review.ps1 clear at the same per-implementation boundary as reviewed-<cid>.flag. Advisory only; never blocks. Disable: HOOKS_ENFORCE=0 or ANCHOR_NUDGE_ENFORCE=0."
+        "_comment": "5s: PROACTIVE pre-compile nudge. On the FIRST edit of each agent turn (per conversation), remind the agent to compile its Anchor Set (pre-compile.md) into .scope.json BEFORE piling on more code. The reactive audits (self-review / anti-slop / final-review axis 0) only fire after code exists; this catches intent dilution at token ~50 instead of ~5000. One-shot per turn: gated by anchor-declared-<cid>.flag, armed here on first edit and cleared UNCONDITIONALLY by final-review.ps1 / subagent-stop-review.ps1 on every stop - so it re-fires on the first edit of the next turn and can never get stranded silenced. Advisory only; never blocks. Disable: HOOKS_ENFORCE=0 or ANCHOR_NUDGE_ENFORCE=0."
       }
     ],
     "postToolUse": [