cursordoctrine 0.4.6 → 0.5.2

package/INSTALL.md

@@ -76,13 +76,14 @@ 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)
+# intent-anchor: writes .scope.json from the current prompt and re-injects it.
+# Needs a repo root in cwd (it will NOT write to $HOME - that's the guard).
+echo '{"conversation_id":"t3","cwd":"/tmp","file_path":"/tmp/x.py"}' | bash ~/.agents/hooks/intent-anchor.sh
+cat /tmp/.scope.json                                                         # expect a JSON scaffold with intent placeholder
+echo '{"conversation_id":"t3"}'       | bash ~/.agents/hooks/post-tool-use.sh # expect additional_context with the scaffold
+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)
+rm -f /tmp/.scope.json                                                        # cleanup the test scaffold
 ```
 
 If the scanner check fails, the final review still works — it falls back to the
@@ -96,11 +97,13 @@ 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
+# intent-anchor: writes .scope.json from the current prompt and re-injects it.
+# Needs a repo root in cwd (it will NOT write to $HOME - that's the guard).
+echo '{"conversation_id":"t3","cwd":"C:\tmp","file_path":"C:\tmp\x.py"}' | pwsh.exe -NoProfile -File $HOME\.agents\hooks\intent-anchor.ps1
+Get-Content C:\tmp\.scope.json                                            # expect a JSON scaffold with intent placeholder
+echo '{"conversation_id":"t3"}'  | pwsh.exe -NoProfile -File $HOME\.agents\hooks\post-tool-use.ps1  # additional_context with the scaffold
 python $HOME\.cursor\skills\anti-slop\scripts\scan_slop.py --help
+Remove-Item C:\tmp\.scope.json -Force                                     # cleanup the test scaffold
 ```
 
 Also validate the config: `~/.cursor/hooks.json` must parse as JSON.
@@ -109,7 +112,7 @@ Also validate the config: `~/.cursor/hooks.json` must parse as JSON.
 
 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; 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.
+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 `intent-anchor` should have written `.scope.json` to the repo root (intent from your prompt, `<TODO>` placeholders for files/acceptance). The scaffold regenerates when your prompt changes and is re-injected every 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.)
@@ -120,4 +123,4 @@ Also validate the config: `~/.cursor/hooks.json` must parse as JSON.
 
 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`, `ANCHOR_NUDGE_ENFORCE=0` (pre-compile nudge off), `INTENT_ANCHOR_ENFORCE=0` (thin-intent re-injection 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`.
+Kill switches if something misbehaves: `HOOKS_ENFORCE=0` (everything advisory off), `PERM_GATE_ENFORCE=0`, `INTENT_ANCHOR_ENFORCE=0` (thin-intent `.scope.json` scaffold/re-injection off), `SEMANTIC_DENSITY_ENFORCE=0`, `SCOPE_GATE_ENFORCE=0`, `ANTI_SLOP_ENFORCE=0`, `FINAL_REVIEW_ENFORCE=0`, `SUBAGENT_REVIEW_ENFORCE=0`.

package/README.md

@@ -21,12 +21,12 @@
 
 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. **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.
+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*. `intent-anchor` materializes that as `.scope.json` on the first tool of each turn (auto-created, regenerated when the prompt changes) and re-injects it into context every turn, so the contract stays in focus against Salience Dilution.
 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.
+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, and anti-slop 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. 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.
+When an implementation finishes, the stop hook runs one final review over everything that changed, then stops. Seven 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. The last is **mechanics & stack integrity** (N+1, idempotency, transactions, boundary validation, zombie listeners, god components, determinism) — patterns the regex scanner can't catch because they need semantic judgement. 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`.
 
@@ -90,13 +90,13 @@ 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.
+On the **first tool of each agent turn**, `intent-anchor` materializes the Anchor Set: it writes `.scope.json` to the repo root (regenerating it when the prompt changed) and re-injects it into context. One scaffold per prompt, re-injection per turn. The latch is armed on first fire and cleared **unconditionally** by the stop hook on every turn boundary, so the next turn re-fires and 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.
 
 ### Keeping the contract alive: `intent-anchor` (anti-Salience-Dilution)
 
-Writing `.scope.json` once is not enough. As a conversation fills with code, logs and errors, the token of the original request shrinks to a rounding error against the recent history — *Salience Dilution* — and the agent stops checking the contract it wrote at prompt 1. It forgets symmetry, colors, the acceptance bar. This is the failure mode the nudge alone can't fix (a reminder that the contract exists ≠ the contract being in context).
+Writing `.scope.json` once is not enough. As a conversation fills with code, logs and errors, the token of the original request shrinks to a rounding error against the recent history — *Salience Dilution* — and the agent stops checking the contract it wrote at prompt 1. It forgets symmetry, colors, the acceptance bar. Re-injecting the contract every turn is what defeats this: the requirements are re-stated in front of the model before each edit, not just written once and hoped-for.
 
 `intent-anchor` (`postToolUse`, registered first so it runs before `post-tool-use` drains the bus) does two things on the **first tool boundary of every turn** (per-turn latch, cleared unconditionally at each stop):
 
@@ -114,7 +114,7 @@ Crucially, `intent-anchor` carries the **semantic** contract (`intent`/`acceptan
 | Session | `sessionStart` | `inject-doctrine` reads doctrine + user rules + declared-editing + **pre-compile** and emits them as `additional_context`. |
 | Every turn | `postToolUse` | **`intent-anchor`** (registered first) re-injects `.scope.json` into `additional_context` at the first tool boundary of each turn — the anti-Salience-Dilution move that keeps `intent` + `acceptance` in the model's attentional focus before edits pile up. If the prompt changed since last turn, it demands the contract be updated. Then `post-tool-use` folds subagent markers and drains the feedback file. |
 | Shell | `beforeShellExecution` | `permission-gate` checks the command against a deny list. Allow by default, deny by list, fail open. |
-| 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. |
+| Edit | `afterFileEdit` + `stop` | **Proactive:** `intent-anchor` (`postToolUse`) scaffolds `.scope.json` per prompt and re-injects it each turn. **Reactive:** `self-review-trigger` stashes the review prompt per edit; `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 seven-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
@@ -149,9 +149,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) |
-| `INTENT_ANCHOR_ENFORCE=0` | on | disables the thin-intent re-injection (per-turn `.scope.json` echo into `additional_context`) |
-| `MINIMAL_EDITING_ENFORCE=0` | on | disables the over-edit advisory (deprecated in 0.3.0) |
+| `INTENT_ANCHOR_ENFORCE=0` | on | disables the thin-intent `.scope.json` scaffold + re-injection |
 | `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 |
 | `ANTI_SLOP_ENFORCE=0` | on | disables the slop advisory |
@@ -164,7 +162,7 @@ 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. 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.
+- **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 `intent-anchor` per-turn latch is separate and simpler: it's cleared **unconditionally** on every stop, so the scaffold/re-inject re-fires on the first tool 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.
 

package/bin/cli.mjs

@@ -284,43 +284,6 @@ function verify() {
     return true;
   });
 
-  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)' };
-    }
-    return true;
-  });
-
   check('intent-anchor scaffolds .scope.json per-prompt, never to $HOME', () => {
     // The user-requested behavior: every NEW prompt -> a fresh .scope.json
     // in the repo root, intent locked from the query. Same prompt -> re-inject
@@ -513,9 +476,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)
-  INTENT_ANCHOR_ENFORCE=0      thin-intent re-injection off (per-turn .scope.json echo)
-  MINIMAL_EDITING_ENFORCE=0    over-edit advisory off (deprecated in 0.3.0)
+  INTENT_ANCHOR_ENFORCE=0      thin-intent scaffold/re-injection off
   SEMANTIC_DENSITY_ENFORCE=0   semantic-opacity advisory off
   SCOPE_GATE_ENFORCE=0         declared-scope advisory off
   ANTI_SLOP_ENFORCE=0          slop advisory off

package/linux/hooks/anti-slop-audit.sh

@@ -1,10 +1,8 @@
 #!/usr/bin/env bash
 # anti-slop-audit.sh - afterFileEdit "AI slop" advisory (Cursor, Linux).
 #
-# Companion to minimal-edit-audit.sh. That hook guards ONE slop axis -
-# over-editing. This hook guards the rest of the taxonomy: the parts static
-# analysis can cheaply and precisely flag, plus a self-review checklist for
-# the parts it cannot.
+# Guards the parts of the slop taxonomy static analysis can cheaply and
+# precisely flag, plus a self-review checklist for the parts it cannot.
 #
 #   Statically flagged (high-precision, deliberately low false-positive):
 #     * new dependency added to a manifest
@@ -174,6 +172,9 @@ msg="Anti-slop audit - $rel
 ${flag_block}${checklist}
 
 (Advisory; the bug pass is the self-review trigger. Disable: ANTI_SLOP_ENFORCE=0)"
+# Expand ~ so the model gets literal absolute paths (followups should be
+# copy-pasteable; bash expands ~ but the agent may not be in a bash context).
+msg="$(expand_agent_paths "$msg")"
 
 # --- append to the shared pending file --------------------------------------
 cid="$(safe_conversation_id "$input")"

package/linux/hooks/final-review.md

@@ -56,26 +56,18 @@ Step A — mechanical scan (if available):
 Step B — canonical checklist (always):
   Read `~/.agents/hooks/anti-slop.md` and apply ALL 13 items to every hunk you
   changed this session. That file is the single source of truth for slop
-  detection — items 1–10 are structural/code, 11 is semantic contracts, 12 is
-  operational slop (retries, await-in-loop, telemetry spam), 13 is change
-  surface. Fix every hit; consolidate clones to one source of truth.
+  detection — it is NOT repeated here. Fix every hit; consolidate clones to one
+  source of truth.
 
 Step C — session footprint (also in the header above):
   If "Session footprint" shows >5 files or the request was simple, justify each
   file or trim. Unjustified files are slop.
 
-Step D — declared scope (closing gate for Compuerta 1):
-  If `.scope.json` exists in the repo root, run the session's full diff against
-  the declared contract. In your shell:
-    for f in $(git diff --name-only HEAD); do
-      python ~/.cursor/skills/anti-slop/scripts/scope_match.py --path "$f" --patterns-file .scope.json
-    done
-  Any file reporting `"in_scope": false` is a scope violation you must justify
-  (add to .scope.json with a one-line reason) or revert. If `.scope.json` does
-  not exist, this step is skipped — the declared-editing ladder and the
-  per-edit scope-gate-audit hook are the opt-in discipline.
-
 Fix with edits now; re-run the scan (if Step A ran) and the tests; then stop.
+(The per-edit `scope-gate-audit` hook already checks `.scope.json` files[] on
+every edit — Step D of older versions ran that loop again here. Removed: it
+duplicated the live hook and burned tokens. If `.scope.json` exists, trust the
+per-edit gate; the intent trace in axis 0 is the whole-session backstop.)
 
 ## 5. Wiring completeness
 For every user-visible behavior you added or changed (button, form submit, API
@@ -97,3 +89,38 @@ 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.
+
+## 6. Mechanics & Stack Integrity
+Stateless, cheap mechanical checks. These are patterns the regex scanner CANNOT
+catch (they need semantic/transversal judgement), so do them by reading the
+diff. If a pattern below is present, FIX it — do not explain, delete and write
+the correct pattern.
+
+Backend / DB:
+  - N+1 query: a query/fetch inside a loop over a list -> batch it or join.
+  - Non-idempotent mutation: a POST/PUT that double-applies on retry -> make it
+    idempotent (idempotency-key) or wrap in a transaction.
+  - Transactional integrity: multi-write ops (DB/API/files) without rollback or
+    a compensating action on partial failure -> wrap in a transaction or Saga.
+  - Missing boundary validation: external input (API/params/DB/URL) trusted
+    without a schema (Zod/Pydantic/Joi) -> validate at the boundary; never
+    hand-validate deeper in the logic.
+
+Frontend (React / Next / Astro / Tailwind):
+  - Zombie listener: a useEffect that adds a listener/subscription/timer
+    without a cleanup `return` -> add it.
+  - God component: a single file doing fetch + state + business logic + JSX
+    (>150 lines) -> split hooks / logic / render.
+  - Tailwind soup & magic tokens: a className with >~6 utilities repeated across
+    elements, or hardcoded hex / z-[9999] -> extract to a component or cva,
+    use design tokens.
+  - Index-as-key in non-static lists -> use a unique id.
+
+Determinism / purity:
+  - Date.now(), Math.random(), process.env read inline in business logic ->
+    inject them (param or a context module) so the function is pure & testable.
+  - In-place mutation of shared state (arr.push, obj.prop =) when a caller holds
+    a reference -> return new structures ([...arr, x], .map/.filter).
+
+You do NOT need to run a tool for these — read the diff and apply the named fix.
+If none apply, say so in one line.

package/linux/hooks/final-review.sh

@@ -1,8 +1,9 @@
 #!/usr/bin/env bash
 # final-review.sh - stop hook (Cursor, Linux).
 #
-# ONE comprehensive end-of-implementation review across six axes:
-# intent, correctness, reliability, coverage, anti-slop, and wiring completeness. When the agent finishes
+# ONE comprehensive end-of-implementation review across seven axes:
+# intent, correctness, reliability, coverage, anti-slop, wiring completeness,
+# and mechanics & stack integrity. 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.
@@ -36,21 +37,18 @@ 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"
 intent_latch="$pending_dir/intent-injected-$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 per-turn latches so the next turn re-fires. Every
-# stop is a turn boundary; clearing here (not only inside the reviewed-flag
-# block below) guarantees these re-fire on the first edit/tool of the NEXT
-# turn and can never get stranded silenced mid-session:
-#   - anchor-declared-<cid>.flag  (anchor-set-nudge, first-edit reminder)
-#   - intent-injected-<cid>.flag  (intent-anchor, first-tool re-injection)
+# Unconditionally clear the intent-anchor per-turn latch so the next turn
+# re-fires. Every stop is a turn boundary; clearing here (not only inside the
+# reviewed-flag block below) guarantees it re-fires on the first tool of the
+# NEXT turn and can never get stranded silenced mid-session.
 # last-query-<cid>.hash is NOT cleared here - it persists turn-to-turn so
 # intent-anchor can detect prompt changes; the 7-day sweep above reaps it.
-rm -f "$anchor_flag" "$intent_latch" 2>/dev/null
+rm -f "$intent_latch" 2>/dev/null
 
 # One-shot brake: the previous stop for this conversation emitted the review.
 if [ -f "$flag" ]; then
@@ -83,16 +81,17 @@ body=""
 if [ -z "$body" ]; then
     body='FINAL REVIEW - audit everything you changed this session and FIX what fails
 (do NOT revert the behaviour the user asked for):
+  0. Intent trace - tie every diff hunk back to the ORIGINAL REQUEST above.
+     Anything untraceable is a hallucinated requirement: revert it. Runs FIRST.
   1. Correctness - logic, edge cases (null/empty/zero/boundary), language traps, security.
   2. Reliability - error paths handled (no empty catch), timeouts/retries, resources
      released on every path, no races, input validated at the boundary.
   3. Coverage - behaviour-bearing changes have real tests; RUN the suite if present;
      no tautological tests.
-  4. Anti-slop - read ~/.agents/hooks/anti-slop.md and apply all 13 items to
-     the session diff. If ~/.cursor/skills/anti-slop/scripts/scan_slop.py exists,
-     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.
+  4. Anti-slop - if the anti-slop scanner exists, run `python <scanner> --all` first;
+     then read ~/.agents/hooks/anti-slop.md (the single source of truth) and apply all
+     13 items to the session diff. Consolidate clones; drop premature abstraction,
+     unneeded deps, operational slop, unjustified files. Do NOT re-list the items here.
   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:
@@ -101,6 +100,9 @@ if [ -z "$body" ]; then
      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
+# Expand ~ in the body AND the fallback, so the model gets literal absolute
+# paths it can paste at the shell (bash expands ~, but followups should emit
+# literals agents can copy-paste without re-interpreting).
 body="$(expand_agent_paths "$body")"
 
 # Regla R1 (re-entry): if this review pass is a re-audit after a failed gate or

package/linux/hooks/semantic-density-audit.sh

@@ -1,11 +1,10 @@
 #!/usr/bin/env bash
 # semantic-density-audit.sh - afterFileEdit "semantic opacity" advisory (Cursor, Linux).
 #
-# Guards the naming layer the other audit hooks do not see. minimal-edit-audit
-# watches diff SIZE; anti-slop-audit watches generated-code PATTERNS; this hook
-# watches whether the identifiers the agent JUST introduced actually communicate
-# intent. DataManager, process(), utils.ts, CoreEngine - names that exist but
-# say nothing.
+# Guards the naming layer the other audit hooks do not see. anti-slop-audit
+# watches generated-code PATTERNS; this hook watches whether the identifiers
+# the agent JUST introduced actually communicate intent. DataManager,
+# process(), utils.ts, CoreEngine - names that exist but say nothing.
 #
 # Mechanism: extract ADDED lines from `git diff HEAD -- <rel>` (with the
 # untracked-file fallback anti-slop-audit uses), pipe them to density_scan.py

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 six-axis review never fires for
+# that marker is never drained and the seven-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,13 +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"
 intent_latch="$pending_dir/intent-injected-$cid.flag"
 
-# Unconditionally clear the per-turn latches so the next subagent run re-fires.
-# Clearing here (not only inside the reviewed-flag block below) can never strand
-# them silenced. last-query-<cid>.hash is kept (cross-turn prompt-change detect).
-rm -f "$anchor_flag" "$intent_latch" 2>/dev/null
+# Unconditionally clear the intent-anchor per-turn latch so the next subagent
+# run re-fires. Clearing here (not only inside the reviewed-flag block below)
+# can never strand it silenced. last-query-<cid>.hash is kept (cross-turn
+# prompt-change detect).
+rm -f "$intent_latch" 2>/dev/null
 
 # One-shot brake: the previous subagentStop for this id emitted the review.
 if [ -f "$flag" ]; then
@@ -76,13 +76,15 @@ 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):
+behaviour the task asked for). Seven axes, in order:
+  0. Intent trace - tie every diff hunk back to your original task. Untraceable = hallucinated.
   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.
+  4. Anti-slop - if the scanner exists, run it --all first; otherwise read
+     ~/.agents/hooks/anti-slop.md (the single source of truth) and apply all 13 items.
+  5. Wiring completeness - trace every added behavior to a REAL EFFECT (persist/mutate/call/render).
+     A dead end (handleSubmit that doesn'"'"'t persist, an endpoint no caller invokes) is slop.
 If an axis is clean, say so in one line. Then stop.'
 fi
 body="$(expand_agent_paths "$body")"

package/linux/hooks.json

@@ -15,12 +15,6 @@
         "matcher": "^(Write|StrReplace|EditNotebook)$",
         "_comment": "5s: record the edit in ~/.cursor/.hooks-pending/session-edits-<conversation_id>.txt and stash the self-review prompt in feedback-<conversation_id>.txt. The harness normalizes agent file edits (incl. StrReplace) to tool type 'Write' in this event - verified via payload capture - so ^Write$ matches them all; the alternation is defensive against future harness versions reporting raw tool names. Anchored so TabWrite (every user tab-completion) stays excluded. The model is the auditor. NOTE: fires inside subagent contexts too, keyed by the SUBAGENT's conversation_id - see subagentStop + the marker fold in post-tool-use.sh/final-review.sh."
       },
-      {
-        "command": "bash ~/.agents/hooks/minimal-edit-audit.sh",
-        "timeout": 15,
-        "matcher": "^(Write|StrReplace|EditNotebook)$",
-        "_comment": "15s (DEPRECATED in 0.3.0, superseded by semantic-density-audit + declared-editing; retained for compat, removal slated for 0.4.0): minimal-editing advisory on the edited file (git --numstat line-count). Size-based gate; the intent-declared gate supersedes it. Appends findings to the conversation's pending file; never blocks. Disable: HOOKS_ENFORCE=0 or MINIMAL_EDITING_ENFORCE=0."
-      },
       {
         "command": "bash ~/.agents/hooks/semantic-density-audit.sh",
         "timeout": 15,
@@ -37,13 +31,7 @@
         "command": "bash ~/.agents/hooks/anti-slop-audit.sh",
         "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 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."
+        "_comment": "15s: AI-slop advisory. 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."
       }
     ],
     "postToolUse": [
@@ -78,7 +66,7 @@
     "stop": [
       {
         "command": "bash ~/.agents/hooks/final-review.sh",
-        "timeout": 5,
+        "timeout": 10,
         "loop_limit": 5,
         "_comment": "5s: ONE comprehensive end-of-implementation review across correctness + reliability + coverage + anti-slop. If the agent edited files this loop (session-edits-<conversation_id> marker), returns {followup_message} so Cursor auto-submits ONE review pass. Bounded by the script's per-conversation reviewed-flag (one review per implementation); loop_limit is the harness-side runaway cap. Disable: HOOKS_ENFORCE=0 or FINAL_REVIEW_ENFORCE=0."
       }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cursordoctrine",
-  "version": "0.4.6",
-  "description": "Thin self-review hooks for Cursor — the model is the auditor. Proactive intent compilation (pre-compile Anchor Set + auto-scaffolded .scope.json that regenerates per prompt and re-injects every turn against Salience Dilution), intent-trace final review (Tier 0), unified 13-item anti-slop checklist, operational slop detection.",
+  "version": "0.5.2",
+  "description": "Thin self-review hooks for Cursor — the model is the auditor. Pruned + deduplicated: intent-anchor (auto-scaffolded .scope.json per prompt + per-turn re-injection against Salience Dilution), intent-trace final review, unified anti-slop checklist as single source of truth.",
   "bin": {
     "cursordoctrine": "bin/cli.mjs"
   },

package/skills/anti-slop/SKILL.md

@@ -20,7 +20,7 @@ description: >-
   duplicate utilities.
 metadata:
   layer: active-cleanup
-  pairs-with: declared-editing (supersedes minimal-editing), semantic-density-audit
+  pairs-with: declared-editing, semantic-density-audit
 ---
 
 # Anti-Slop
@@ -228,7 +228,7 @@ 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 six axes: intent,
+and auto-submits a `followup_message` so the model audits seven 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,
@@ -275,8 +275,7 @@ low-density identifiers per edit — shares `low_density.py` with this scanner's
 `semantic_density` bucket), the **scope-gate-audit hook**
 (`scope-gate-audit.ps1` / `.sh`, Compuerta 1 — opt-in declared-scope gate
 that flags edits outside `.scope.json`; shares `scope_match.py` with the
-final-review Step D closing gate), the **stop hook** (`final-review.ps1` / `.sh`,
-six-axis session review incl. intent trace and wiring completeness), and
-**declared-editing** (YAGNI ultra ladder injected at session start;
-supersedes the deprecated `minimal-editing` size gate). This skill is the
-active "delete it now" layer those only nudge toward.
+**stop hook** (`final-review.ps1` / `.sh`,
+seven-axis session review incl. intent trace, wiring completeness, and mechanics & stack integrity), and
+**declared-editing** (YAGNI ultra ladder injected at session start).
+This skill is the active "delete it now" layer those only nudge toward.

package/windows/doctrine.md

@@ -13,27 +13,25 @@ new rule, you do not add it here — you do the work.
 
 ## 1. You are the auditor
 
-The harness gives you one piece of safety net: a **permission-gate** that
-denies a small list of dangerous commands (rm -rf on absolute paths,
-curl|sh, force-push, npm publish, etc.). It does **not** audit your code.
-It does **not** run linters. It does **not** score your diffs. **You**
-are the auditor. After every `Edit`, the harness hands you your own diff
-back via `additional_context` and asks you to review it for bugs. You
-must review, fix what is broken, and stay silent otherwise. The exact
-self-review prompt is in `self-review.md` next to the hook scripts
-(installed under `~/.agents/hooks/` — if you cannot find it, run
-`find ~/.agents ~/.cursor ~/.config -name self-review.md 2>/dev/null`
-on first session).
+The harness ships a set of **advisory hooks** — small scripts that flag
+patterns after you edit (semantic density, declared-scope drift, AI slop) and
+hand them back to you as `additional_context`. They never block, never revert,
+never decide anything. They surface signals; **you** decide. A permission-gate
+denies a short list of dangerous shell commands (`rm -rf` on absolute paths,
+`curl|sh`, force-push, `npm publish`, ...). That is the only hard block. After
+every `Edit`, a self-review prompt is handed back to you so you re-read your
+own diff and fix bugs.
 
 This means:
 
-  - You do not need a regex engine. You do not need an AST pass. You do
-    not need 8 audit layers. You need to **read the file you just
-    changed, see if it is wrong, and fix it if so.**
-  - A heuristic audit that runs on every keystroke and never blocks
-    would still be wasted work. A self-review that you do yourself, in
-    your own context, is **free** — you have the file, the diff, the
-    user's intent, and the ability to fix. Use that.
+  - You do not need a deterministic gate to catch bugs. The hooks seed signals
+    (regex hits, scope violations, low-density names); you do the actual audit
+    — **read the file you just changed, see if it is wrong, fix it if so.**
+    A self-review you do yourself, in your own context, is **free** — you have
+    the file, the diff, the user's intent, and the ability to fix.
+  - The hooks are advisory, not authoritative. If a hook flags something and you
+    disagree, say so in one line and proceed. You outrank the hooks. They exist
+    to remind you, not to overrule you.
   - "Bugs" means things that would fail a careful code review at
     Anthropic / Stripe / Vercel. Style, naming, formatting, missing
     type hints, "you could write this more idiomatically" — these are
@@ -140,20 +138,18 @@ When you call Bash:
 
 ## 7. What you do not do
 
-  - You do not run 8 audit engines on every file. The harness does not
-    have them. You are the auditor.
+  - You do not treat the advisory hooks as a gate to satisfy. They surface
+    signals; the hooks do not block, and you are the auditor. Optimize for
+    "the change is correct, small, and the user can review it in 30 seconds,"
+    not for "no hook fired."
   - You do not write to `.stuck-files/`, `.audit-baselines/`, or any
     other hook state directory. Those are not your concern.
-  - You do not maintain a "strict quality gate" config. There isn't
-    one. The rules above *are* the gate.
   - You do not set kill-switch env vars (`HOOKS_ENFORCE=0`,
-    `MYTHOS_ENFORCE=0`, etc.). They don't exist anymore.
+    `INTENT_ANCHOR_ENFORCE=0`, etc.) to silence the hooks. They exist; work
+    with them, or tell the user if one is wrong.
   - You do not re-read the doctrine on every turn. You read it once,
     at session start, and internalize it. The self-review trigger
     will re-prompt you for the specific edit you're auditing.
-  - You do not optimize for "the gate passed." You optimize for
-    "the change is correct, small, and the user can review it in
-    30 seconds."
 
 ---
 

package/windows/hooks/anti-slop-audit.ps1

@@ -1,8 +1,6 @@
 # anti-slop-audit.ps1 - afterFileEdit "AI slop" advisory (Cursor).
 #
-# Companion to minimal-edit-audit.ps1. That hook guards ONE slop axis -
-# over-editing (diff size / token-Levenshtein / added complexity). This hook
-# guards the rest of the taxonomy: the parts static analysis can cheaply and
+# Guards the parts of the slop taxonomy static analysis can cheaply and
 # precisely flag, plus a self-review checklist for the parts it cannot.
 #
 #   Statically flagged (high-precision, deliberately low false-positive):
@@ -209,9 +207,11 @@ Fix guilty items now. Never revert what the user asked for.
 $flagBlock = if ($flags.Count -gt 0) { "Static signals on this edit:`n" + ($flags -join "`n") + "`n`n" } else { '' }
 
 # Concatenate (do NOT interpolate $checklist - its content must stay literal).
+# Expand ~ on the final message so the model gets literal absolute paths
+# (Windows pwsh does NOT expand ~; the agent may paste paths into a shell).
 $header = "Anti-slop audit - $rel`n`n"
 $footer = "`n`n(Advisory; the bug pass is the self-review trigger. Disable: ANTI_SLOP_ENFORCE=0)"
-$msg = $header + $flagBlock + $checklist + $footer
+$msg = Expand-AgentPaths ($header + $flagBlock + $checklist + $footer)
 
 # --- append to the shared pending file ------------------------------------
 $cid = Get-SafeConversationId $obj