cursordoctrine 0.3.3 → 0.4.1

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 the implementation) a `PRE-COMPILE NUDGE` reminder to write its Anchor Set to `.scope.json`.
 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 implementation 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 implementation**, `anchor-set-nudge` drops a reminder into the feedback bus: *did you write your Anchor Set to `.scope.json`?* One nudge per body of work — the flag is cleared at the same per-implementation boundary where the final-review one-shot brake fires, so a long chat with N implementations gets N nudges.
+
+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 implementation 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` flag and the review flag clear together at that boundary — one nudge + one review per body of work.
+- **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

@@ -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', 'declared-editing.md'];
+const doctrineFiles = [injectName, 'doctrine.md', 'USER-RULES.md', 'declared-editing.md', 'pre-compile.md'];
 
 function payloadHookFiles() {
   return readdirSync(join(payload, 'hooks'));
@@ -263,6 +263,22 @@ 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' };
+    }
+    // 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;
+  });
+
   check('doctrine injection emits additional_context', () =>
     runHook(join(cursorDst, injectName), {}).includes('additional_context'));
 
@@ -372,6 +388,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

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# 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.
+#
+# 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.
+#
+# 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.
+# Disable: HOOKS_ENFORCE=0  or  ANCHOR_NUDGE_ENFORCE=0
+
+set +e
+. "$(dirname "$0")/hook-common.sh"
+
+[ "${HOOKS_ENFORCE:-}" = "0" ] && exit 0
+[ "${ANCHOR_NUDGE_ENFORCE:-}" = "0" ] && exit 0
+
+input="$(read_hook_stdin)"
+[ -n "$input" ] || exit 0
+
+file_path=""
+for k in file_path path filePath; do
+    file_path="$(json_get "$input" "$k")"
+    [ -n "$file_path" ] && break
+done
+[ -n "$file_path" ] || exit 0
+is_cursor_config_path "$file_path" && exit 0
+
+cid="$(safe_conversation_id "$input")"
+pending_dir="$(hooks_pending_dir)"
+flag="$pending_dir/anchor-declared-$cid.flag"
+
+# Already nudged this implementation -> stay quiet. The flag is cleared at the
+# per-implementation boundary in final-review.sh / subagent-stop-review.sh.
+[ -f "$flag" ] && exit 0
+
+msg="PRE-COMPILE NUDGE - first edit of this implementation: $file_path
+
+Before you keep going, did you compile your Anchor Set (pre-compile.md)?
+  1. OBJECTIVE   - one operational sentence. What is strictly necessary.
+  2. CONSTRAINTS - local negations (what you will NOT do).
+  3. SCOPE       - files to touch, files untouchable.
+  4. SUCCESS     - the one deterministic check that decides done.
+
+If you have not already, write it to .scope.json now (intent / files /
+acceptance / allow_growth). The scope-gate audits every edit against files[],
+and final-review axis 0 traces every diff hunk back to intent. An Anchor Set
+that lives only in your head is not an Anchor Set - the gate cannot audit it.
+
+Skip this for trivial one-liners (typo, literal). Otherwise: compile, then code."
+
+# Append to the shared pending file (same bus as the other advisories).
+pending="$pending_dir/feedback-$cid.txt"
+mkdir -p "$pending_dir" 2>/dev/null
+if [ -s "$pending" ]; then
+    printf '\n\n---\n\n%s' "$msg" >> "$pending" 2>/dev/null
+else
+    printf '%s' "$msg" >> "$pending" 2>/dev/null
+fi
+
+# Arm the one-shot brake BEFORE returning, so a crash after the append can't
+# re-nudge on the next edit. Mirrors the arming order in final-review.sh.
+touch "$flag" 2>/dev/null
+
+exit 0

package/linux/hooks/final-review.sh

@@ -36,13 +36,16 @@ cid="$(safe_conversation_id "$input")"
 pending_dir="$(hooks_pending_dir)"
 marker="$pending_dir/session-edits-$cid.txt"
 flag="$pending_dir/reviewed-$cid.flag"
+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
 
 # 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" 2>/dev/null
+    rm -f "$flag" "$marker" "$anchor_flag" 2>/dev/null
     emit_none
 fi
 
@@ -91,6 +94,14 @@ Fix now, re-run the scan + tests, then stop. If an axis is clean, say so in one
 fi
 body="$(expand_agent_paths "$body")"
 
+# Regla R1 (re-entry): if this review pass is a re-audit after a failed gate or
+# axis, suppress History Propagation - the model must NOT build on its own prior
+# wrong diff. Reset its prior to the Anchor Set, not to its previous attempt.
+reentry_line="
+
+RE-ENTRY RULE (Regla R1): if a gate or axis failed, forget the approach that produced it. Re-read your ORIGINAL REQUEST above and your Anchor Set (.scope.json, if you wrote one). Fix ONLY what is failing. Do not refactor in this pass - that is History Propagation, the exact failure mode the Anchor Set exists to prevent.
+"
+
 file_list=""
 while IFS= read -r p; do
     [ -n "$p" ] || continue
@@ -127,7 +138,7 @@ msg="FINAL REVIEW (end of implementation) - intent, correctness, reliability, co
 ${surface_block}${intent_block}Files you changed this session:
 $file_list
 
-$body"
+${body}${reentry_line}"
 
 # Arm the one-shot brake BEFORE emitting, so a crash after emit can't re-fire.
 touch "$flag" 2>/dev/null

package/linux/hooks/scope-gate-audit.sh

@@ -78,8 +78,10 @@ if p.get("in_scope"):
     sys.exit(3)   # in scope -> clean
 allow_growth = "1" if p.get("allow_growth") else "0"
 intent = p.get("intent", "")
+acceptance = p.get("acceptance", "")
 print(f"__AG__{allow_growth}")
 print(f"__INTENT__{intent}")
+print(f"__ACCEPT__{acceptance}")
 sys.exit(0)
 PYEOF
 }
@@ -90,6 +92,7 @@ rc=$?
 
 allow_growth="$(printf '%s\n' "$parsed" | grep '__AG__' | sed 's/__AG__//')"
 intent="$(printf '%s\n' "$parsed" | grep '__INTENT__' | sed 's/__INTENT__//')"
+acceptance="$(printf '%s\n' "$parsed" | grep '__ACCEPT__' | sed 's/__ACCEPT__//')"
 
 # Read declared files for the message (best-effort)
 declared_files="$(printf '%s' "$scope_file" | "$py" -c "
@@ -102,16 +105,29 @@ except Exception:
 " "$scope_file" 2>/dev/null)"
 
 # --- compose advisory ------------------------------------------------------
+# acceptance line: only quote it when the agent declared one. A blank acceptance
+# means the Anchor Set was incomplete - surface that gap, since the whole point
+# of the pre-compile phase is to name the deterministic success check.
+if [ -n "$acceptance" ]; then
+    acceptance_line="$acceptance"
+else
+    acceptance_line="(not declared - your Anchor Set is missing the EXITO/acceptance field)"
+fi
+
 if [ "$allow_growth" = "1" ]; then
     summary="Scope note - $rel is new vs your declared scope (growth allowed)"
     body="  You touched a file outside your initial declared set. Since allow_growth is
   true, this is not a violation, but justify it: add $rel to .scope.json or
-  explain why the scope grew."
+  explain why the scope grew.
+
+  Your success contract (acceptance): $acceptance_line
+  Does growing into $rel still serve that?"
 else
     summary="[SCOPE VIOLATION] $rel is NOT in your declared scope"
     body="  Your contract (.scope.json):
     intent: $intent
     files: $declared_files
+    acceptance: $acceptance_line
 
   You declared these files and touched one outside the set. Either:
     1. Add $rel to .scope.json with a one-line justification, OR

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
@@ -44,10 +44,13 @@ cid="$(safe_conversation_id "$input")"
 pending_dir="$(hooks_pending_dir)"
 marker="$pending_dir/session-edits-$cid.txt"
 flag="$pending_dir/reviewed-$cid.flag"
+anchor_flag="$pending_dir/anchor-declared-$cid.flag"
 
 # 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" 2>/dev/null
+    rm -f "$flag" "$marker" "$anchor_flag" 2>/dev/null
     emit_none
 fi
 
@@ -80,6 +83,14 @@ If an axis is clean, say so in one line. Then stop.'
 fi
 body="$(expand_agent_paths "$body")"
 
+# Regla R1 (re-entry): same suppression as final-review.sh. A subagent that
+# failed an axis must not build on its own prior wrong diff - reset its prior
+# to the Anchor Set, not to its previous attempt.
+reentry_line="
+
+RE-ENTRY RULE (Regla R1): if an axis failed, forget the approach that produced it. Re-read your original task and your Anchor Set (.scope.json, if you wrote one). Fix ONLY what is failing. Do not refactor in this pass.
+"
+
 file_list=""
 while IFS= read -r p; do
     [ -n "$p" ] || continue
@@ -94,7 +105,7 @@ msg="SUBAGENT FINAL REVIEW - you just finished delegated implementation work. Be
 Files you changed this run:
 $file_list
 
-$body"
+${body}${reentry_line}"
 
 # Arm the one-shot brake BEFORE emitting, so a crash after emit can't re-fire.
 touch "$flag" 2>/dev/null

package/linux/hooks.json

@@ -38,6 +38,12 @@
         "timeout": 15,
         "matcher": "^(Write|StrReplace|EditNotebook)$",
         "_comment": "15s: AI-slop advisory, companion to minimal-edit-audit. git diff flags new deps / premature abstractions (Factory/Repository/Mediator/CQRS/DDD) / redundant comments, and injects the anti-slop.md self-review checklist on substantial edits (>= ANTI_SLOP_CHECKLIST_LINES, default 40). Appends to the conversation's pending file; never blocks. Disable: HOOKS_ENFORCE=0 or ANTI_SLOP_ENFORCE=0."
+      },
+      {
+        "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."
       }
     ],
     "postToolUse": [

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" "$HOME/.cursor/declared-editing.md"; do
+for p in "$HOME/.cursor/doctrine.md" "$HOME/.cursor/USER-RULES.md" "$HOME/.cursor/declared-editing.md" "$HOME/.cursor/pre-compile.md"; do
     if [ -f "$p" ]; then
         part="$(cat "$p")"
         if [ -n "$context" ]; then context="$context

package/linux/pre-compile.md

@@ -0,0 +1,72 @@
+# Pre-compile — Thin Intent Compilation
+
+ACTIVE EVERY IMPLEMENTATION TURN. Before writing or modifying a single line of
+code, emit your Anchor Set. Compiling intent first is what stops the dilution
+that no later axis can fully undo — a clean final review of the wrong feature
+is still the wrong feature.
+
+This is the proactive phase. The anti-slop checklist, the self-review trigger
+and the final review are reactive — they audit after the fact. You compile the
+intent BEFORE the first token of code so they have the right thing to audit.
+
+## The Anchor Set
+
+Answer these four, terse, in your first response. One phrase each, not prose:
+
+1. OBJECTIVE — one operational sentence. What is *strictly* necessary. Not
+   "improve X" — "make X return Y when Z".
+2. CONSTRAINTS (local negations) — what you will NOT do. "NO schema migration.
+   NO new dependency. NO refactor of the surrounding function." Negations bind
+   harder than the objective: a constraint that the task contradicts is a bug
+   in your reading of the task, and you ask before you override it.
+3. SCOPE —
+   - FILES TO TOUCH: exact list, derived from the objective, nothing speculative.
+   - FILES UNTOUCHABLE: anything the system marked off-limits (.cursor state,
+     lockfiles you weren't asked to touch, files outside the request's blast
+     radius).
+4. DETERMINISTIC SUCCESS — the one command, test, or observable check that
+   will decide whether this is done. "Tests pass" is not deterministic; the
+   specific failing test going green is. If you cannot name one, you do not
+   yet understand the task — ask.
+
+## Materialize it: .scope.json
+
+Write the Anchor Set to `.scope.json` in the repo root before editing source.
+This is the machine-checkable form — the scope-gate hook audits every edit
+against `files[]`, and the final-review axis 0 traces every diff hunk back to
+`intent`. An Anchor Set that lives only in your head is not an Anchor Set.
+
+```json
+{
+  "intent": "<OBJECTIVE>",
+  "files": ["<FILES TO TOUCH, repo-relative, glob-friendly>"],
+  "acceptance": "<DETERMINISTIC SUCCESS>",
+  "allow_growth": false
+}
+```
+
+`allow_growth: false` is the default — the gate fires on any edit outside
+`files[]`. Set it true only if you expect the work to discover new files
+(a refactor, a migration) and you will justify each one as it appears.
+
+No need to write `.scope.json` for trivial one-liners (a typo, a literal).
+The declared-editing ladder's rung 1 ("does this need to exist?") governs when
+the Anchor Set itself is overkill. When in doubt, write it.
+
+## Regla R3 — Authority
+
+If, during execution, you read logs or code that contradict these anchors,
+**the anchors win.** Prior history in this session is auditor material, not
+authority. An earlier wrong assumption of yours does not override the Anchor
+Set you declared at the start.
+
+## Regla R1 — On re-entry (when the loop hands you back a failure)
+
+If the harness returns a gate failure or a failed axis: forget the approach
+that produced it. Re-read your OBJECTIVE and your Anchor Set, not your prior
+diff. Fix ONLY what is failing. Do not refactor in the same pass — that is
+History Propagation, the failure mode the Anchor Set exists to prevent.
+
+---
+
+End of pre-compile. Now emit the Anchor Set, then do the work.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cursordoctrine",
-  "version": "0.3.3",
-  "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.",
+  "version": "0.4.1",
+  "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.",
   "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.