cursordoctrine 0.5.1 → 0.5.2

package/README.md

@@ -26,7 +26,7 @@ Cursor hooks that make the agent review its own edits without bolting a static-a
 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`.
 
@@ -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:** `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 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

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.

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
@@ -76,7 +76,7 @@ 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). Six axes, in order:
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursordoctrine",
-  "version": "0.5.1",
+  "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

@@ -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,
@@ -276,6 +276,6 @@ low-density identifiers per edit — shares `low_density.py` with this scanner's
 (`scope-gate-audit.ps1` / `.sh`, Compuerta 1 — opt-in declared-scope gate
 that flags edits outside `.scope.json`; shares `scope_match.py` with the
 **stop hook** (`final-review.ps1` / `.sh`,
-six-axis session review incl. intent trace and wiring completeness), and
+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/hooks/final-review.md

@@ -89,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/windows/hooks/final-review.ps1

@@ -1,7 +1,8 @@
 # final-review.ps1 - stop hook (Cursor).
 #
-# ONE comprehensive end-of-implementation review across six axes:
-# intent, correctness, reliability, coverage, anti-slop, and wiring completeness. When the agent finishes an
+# 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 - the model-as-auditor pattern over

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 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
@@ -76,7 +76,7 @@ if (Test-Path $promptFile) { $body = Get-Content -Raw $promptFile }
 if (-not $body) {
     $body = @'
 Audit everything you changed in this run and FIX what fails (do NOT revert the
-behaviour the task asked for). Six axes, in order:
+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.