cursordoctrine 0.1.1 → 0.2.1

package/README.md

@@ -10,7 +10,7 @@ A small set of Cursor hooks that make the agent review its own work without bolt
 2. **Hand the model its own edits back.** After each agent edit, a self-review prompt (plus minimal-edit and anti-slop advisories when they trip) is stashed and delivered on the next turn. The model reads its own diff, fixes real bugs, and stays quiet otherwise.
 3. **Gate blast radius.** One permission gate denies a short, explicit list of dangerous commands (`rm -rf /`, `curl | sh`, force-push, `npm publish`, ...). Everything else is allowed.
 
-When an implementation finishes, a stop hook fires exactly one final review pass over everything that changed — then stops. Delegated work gets the same treatment: a subagent that edited files reviews its own implementation before its result returns to the parent, and its edits are folded into the parent's final review. Every bound is enforced twice: in the script and in `hooks.json`.
+When an implementation finishes, a stop hook fires exactly one final review pass over everything that changed — then stops. The review runs across five axes, the first of which is **intent trace**: the hook extracts your last user message from the transcript and prepends it to the review so the model must trace every diff hunk back to a concrete request. Anything untraceable is a hallucinated requirement and gets reverted — this is the only detector that catches "clean code, wrong feature," which no later axis and no linter can see. Delegated work gets the same treatment: a subagent that edited files reviews its own implementation before its result returns to the parent, and its edits are folded into the parent's final review. Every bound is enforced twice: in the script and in `hooks.json`.
 
 This setup is for Cursor only. It installs into `~/.cursor` and `~/.agents/hooks` and touches nothing in your projects.
 
@@ -41,7 +41,7 @@ The two folders are functionally identical. Windows runs everything through `pws
 | Session | `sessionStart` | `inject-doctrine` reads the doctrine + user rules 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` and `anti-slop-audit` append advisories when thresholds trip; `final-review` fires one end-of-implementation pass. |
+| Edit | `afterFileEdit` + `stop` | `self-review-trigger` stashes the review prompt per edit; `minimal-edit-audit` and `anti-slop-audit` append advisories when thresholds trip (new deps / premature abstraction / redundant comments / Tier 3 operational slop: retry-without-backoff, await-in-loop, telemetry spam); `final-review` fires one end-of-implementation pass. |
 | Subagent | `subagentStop` | `subagent-stop-review` fires one in-subagent final review when a delegated run edited files, before the result returns to the parent. Marker-gated and flag-braked like `final-review`. |
 
 ## Install
@@ -59,7 +59,7 @@ No Node? Open `INSTALL.md`, paste its contents into a Cursor agent chat on the t
 
 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 final review runs the scanner from there; if it's missing (an install from before it shipped), the review falls back to the `~/.agents/hooks/anti-slop.md` checklist instead of failing.
+The anti-slop skill (`skills/anti-slop/` — SKILL.md and the duplication scanner) installs to `~/.cursor/skills/anti-slop/`. The hook checklist (`~/.agents/hooks/anti-slop.md`, 13 items) is the canonical slop detector for both per-edit advisories and final-review axis 4. The final review runs the scanner from the skill path first when available.
 
 ## Tuning and kill switches
 

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

@@ -12,6 +12,8 @@
 #       *Strategy / *Singleton / *Facade / *Builder / *Visitor / *Decorator
 #       class, or CQRS / Event-Sourcing / DDD vocabulary
 #     * redundant comments that merely restate the next line of code
+#     * operational slop (Tier 3): retry-without-backoff, await-in-loop,
+#       telemetry spam (>= 6 log/print statements added in one edit)
 #
 # Fires when a static signal trips OR the edit added a substantial block of
 # new source (>= ANTI_SLOP_CHECKLIST_LINES, default 40). Otherwise silent.
@@ -102,6 +104,31 @@ redundant="$(printf '%s\n' "$added" |
         fi
     done | sort -u | head -n 4)"
 
+# --- signal 4: operational slop (Tier 3) ------------------------------------
+# Retry-without-backoff: a retry construct with no sleep/backoff/setTimeout in
+# the added lines. Seed-grade (high precision); the model judges.
+ops_flags=""
+if printf '%s\n' "$added" | grep -qE '\b(retry|retryCount|retries|maxRetries|attempt)[A-Za-z0-9_]*\b'; then
+    if ! printf '%s\n' "$added" | grep -qE '\b(sleep|setTimeout|backoff|back_off|exponential|jitter|delay)[A-Za-z0-9_]*\b'; then
+        ops_flags="${ops_flags}- RETRY WITHOUT BACKOFF: a retry construct was added but no sleep/backoff/setTimeout is visible in this edit's added lines. Unbounded retries = retry storms + token/cost burn; add bounded backoff or confirm the runtime already throttles.
+"
+    fi
+fi
+# Awaited IO call co-occurring with a loop construct on the same edit. N+1 in
+# agent/edge code, not just SQL. The model judges streaming vs serial-await.
+if printf '%s\n' "$added" | grep -qE '\b(for|while|forEach|map|filter|reduce|flatMap|for[[:space:]]+await|async[[:space:]]+for)\b'; then
+    if printf '%s\n' "$added" | grep -qE '\bawait[[:space:]]+(fetch|ctx\.db|ctx\.run|client\.|axios|prisma\.|supabase\.|db\.|repo\.)'; then
+        ops_flags="${ops_flags}- AWAIT IN LOOP: a loop construct and an awaited IO call both appear in this edit. Sequential awaits in a loop = N+1 / serial latency; confirm whether Promise.all / a batch call / a single query is the right primitive. (If this is genuinely a streaming pattern, ignore.)
+"
+    fi
+fi
+# Telemetry spam seed: 6+ log/print statements added in one file.
+log_count="$(printf '%s\n' "$added" | grep -cE '\b(console\.(log|debug|info|warn|error)|print\(|fmt\.Print|std::cout|NSLog|System\.out\.println|println!|dbg!|console\.dir)\b')"
+if [ "$log_count" -ge 6 ]; then
+    ops_flags="${ops_flags}- TELEMETRY SPAM: ${log_count} log/print statements added in this one edit. Debug-level telemetry that nobody reads is slop; consolidate or remove (kept only if this is a real logging entrypoint).
+"
+fi
+
 # --- decide whether to fire -------------------------------------------------
 added_code="$(printf '%s\n' "$added" | grep -cE '[^[:space:]]')"
 checklist_lines="${ANTI_SLOP_CHECKLIST_LINES:-40}"
@@ -118,6 +145,7 @@ flags=""
 "
 [ -n "$redundant" ] && flags="${flags}- REDUNDANT COMMENTS: $(printf '%s' "$redundant" | paste -sd '|' -) - delete comments that restate the code; keep only WHY.
 "
+flags="${flags}${ops_flags}"
 
 if [ -z "$flags" ] && [ "$substantial" = "0" ]; then exit 0; fi
 
@@ -126,17 +154,14 @@ checklist_file="$HOME/.agents/hooks/anti-slop.md"
 checklist=""
 [ -f "$checklist_file" ] && checklist="$(cat "$checklist_file")"
 if [ -z "$checklist" ]; then
-    checklist='ANTI-SLOP SELF-REVIEW - audit the edit you just made and FIX (do not explain) any slop:
-  1. Edge cases beyond the happy path (null / empty / zero / boundary / error).
-  2. Duplicated logic that already exists in this repo - call it, do not re-implement.
-  3. Conventions - match the file'"'"'s existing style / naming / structure / error-handling.
-  4. Unnecessary dependencies - remove libs the stdlib or an existing dep covers.
-  5. Premature abstraction - no Factory/Repository/Mediator/CQRS/DDD without 2-3 real call sites today.
-  6. Accidental complexity - flatten indirection a junior cannot read in 30s.
-  7. Tests assert real behaviour and edge cases, not just "it runs".
-  8. Cargo cult - delete any construct whose reason you cannot state.
-  9. Architecture - respect the project'"'"'s layering and boundaries.
- 10. Redundant comments restating code - delete; keep only WHY.'
+    checklist='ANTI-SLOP — read ~/.agents/hooks/anti-slop.md (13 items). Fallback if missing:
+  1–10: edge cases, duplication, conventions, deps, premature abstraction,
+  accidental complexity, tests (no tautologies), cargo cult, architecture,
+  redundant comments / prompt residue.
+  11: semantic contracts (behavior change without name/signature change).
+  12: operational slop (retry w/o backoff, await-in-loop, telemetry spam).
+  13: change surface (too many files for a simple request).
+Fix guilty items now. Never revert what the user asked for.'
 fi
 
 flag_block=""

package/linux/hooks/anti-slop.md

@@ -1,56 +1,54 @@
-ANTI-SLOP SELF-REVIEW — you just edited a file. Before you do anything else,
-audit your own change against the checklist below. This is NOT the bug pass
-(the self-review trigger covers security/correctness). This is about *slop*:
-code that runs but should not ship.
-
-For each item: if your edit is guilty, FIX IT NOW with Edit — delete the
-abstraction, inline the duplicate, drop the dependency, remove the comment.
-Do not explain, do not report, just fix. If the edit is clean, say nothing.
-
-  1. EDGE CASES — Does it only handle the happy path? Check the null / empty /
-     zero / boundary / error inputs the task implies. An unhandled obvious
-     edge case is a bug waiting in production.
-
-  2. DUPLICATION — Did you write logic that already exists in this repo? Look
-     before you add. If it exists, call it; do not re-implement it.
-
-  3. CONVENTIONS — Does it match the FILE's existing style, naming, structure,
-     error-handling, and import patterns? Match the neighbours, not your
-     defaults.
-
-  4. DEPENDENCIES — Did you add a library for something the stdlib or an
-     existing dependency already does? Remove it. A new dependency must earn
-     its place.
-
-  5. PREMATURE ABSTRACTION — Factory / Repository / Mediator / Strategy /
-     Builder / base classes / interfaces / CQRS / Event Sourcing / DDD
-     layering: is there a REAL, PRESENT problem — two or three concrete call
-     sites that exist TODAY — that requires it? "For future flexibility" is
-     not a reason. Delete it and write the direct code. Abstraction debt is
-     layers without problems.
-
-  6. ACCIDENTAL COMPLEXITY — Could a junior read this in 30 seconds? Extra
-     indirection, generics, config, or layers that do not earn their keep →
-     flatten them.
-
-  7. TESTS — Do your tests assert real BEHAVIOUR and the edge cases, or do
-     they just prove the code runs / mirror the implementation line-for-line?
-     A test that cannot fail is slop. Make it verify outcomes.
-
-  8. CARGO CULT — Can you state WHY each non-obvious construct is there? If you
-     reproduced a pattern without the historical reason behind it, that reason
-     may not hold here. Remove what you cannot justify. Replicating a shape you
-     have seen is not the same as needing it.
-
-  9. ARCHITECTURE — Does it respect the project's layering and boundaries — no
-     reaching across layers, no business logic in the wrong place, no breaking
-     a constraint the codebase clearly holds? Honour the constraints.
-
- 10. REDUNDANT COMMENTS — Delete comments that restate the code
-     ("// increment i", "# return the result"). Keep only comments that
-     explain WHY, never WHAT.
-
-Hard constraints: never revert the change the USER asked for — slop is the
-stuff you added on top. Do not "improve" beyond removing slop. At most a few
-targeted edits, then stop. The bar: would this pass a senior review at a top
-engineering org without a single "why is this here?" comment.
+ANTI-SLOP SELF-REVIEW — you just edited a file (or you are auditing the
+session diff at final review). Code that runs but should not ship.
+
+Intent trace (Tier 0 — hallucinated requirements, scope drift) runs FIRST at
+stop via final-review axis 0, not here. This checklist covers code-shape and
+cost slop. Apply every item; if guilty, FIX with Edit — delete, inline, drop.
+Do not explain. If clean, say nothing.
+
+  1. EDGE CASES — Happy path only? Check null / empty / zero / boundary / error
+     inputs the task implies.
+
+  2. DUPLICATION — Logic that already exists in this repo? Call it; do not
+     re-implement. Same function in many files (isRecord-class) → one source.
+
+  3. CONVENTIONS — Match the FILE's style, naming, structure, error-handling,
+     imports. Not your defaults.
+
+  4. DEPENDENCIES — New library for something stdlib or an existing dep covers?
+     Remove it. A dependency must earn its place.
+
+  5. PREMATURE ABSTRACTION — Factory / Repository / Mediator / Strategy / Builder /
+     CQRS / Event Sourcing / DDD: is there a REAL problem with 2–3 call sites
+     TODAY? "Future flexibility" is not a reason. Delete and write direct code.
+
+  6. ACCIDENTAL COMPLEXITY — Could a junior read this in 30 seconds? Flatten
+     indirection, generics, config, layers that do not earn their keep.
+
+  7. TESTS (epistemic slop) — Assert real OUTCOMES and edge cases, not "it runs",
+     not a mirror of the implementation, not expect(true).toBe(true). A test
+     that cannot fail is slop.
+
+  8. CARGO CULT — Can you state WHY each non-obvious construct is there? Remove
+     what you cannot justify. A shape you have seen ≠ a shape you need.
+
+  9. ARCHITECTURE — Respect layering and boundaries. No reaching across layers,
+     no business logic in the wrong place, no breaking project constraints.
+
+ 10. REDUNDANT COMMENTS — Delete comments that restate the code ("// increment
+     i"). Keep only WHY, never WHAT. No prompt residue ("in a real app...").
+
+ 11. SEMANTIC CONTRACTS (Tier 1) — Did any existing function's BEHAVIOR change
+     without its name, signature, or docstring changing? Names are contracts.
+     deleteUser() that now soft-deletes is silent contract break.
+
+ 12. OPERATIONAL SLOP (Tier 3) — Retry loops without backoff/sleep/jitter?
+     await fetch / ctx.db / prisma inside a for/while/map? Six or more
+     console.log / print added in one edit? Token burn with no user value →
+     remove or bound.
+
+ 13. CHANGE SURFACE (Tier 5) — Did a simple request touch many files? Every
+     file in the diff must trace to the task. Trim unrelated hunks.
+
+Hard constraints: never revert what the USER asked for — slop is what got added
+on top. At most a few targeted edits, then stop.

package/linux/hooks/final-review.md

@@ -1,11 +1,20 @@
 FINAL REVIEW — you just finished an implementation. Before you treat it as done,
-audit EVERYTHING you changed this session across the four axes below and FIX what
+audit EVERYTHING you changed this session across the five axes below and FIX what
 fails. Do NOT revert the behaviour the user asked for. If an axis is already
 clean, say so in one line — do not manufacture work.
 
 Start by re-reading the diff. Scope the review to your session's changes and the
 code they touch.
 
+## 0. Intent trace (HIGHEST PRIORITY — run first)
+The hook extracted your last user message as "ORIGINAL REQUEST" above. For every
+hunk in the diff, answer: which part of the request forced this change? Anything
+that cannot trace to the request is a HALLUCINATED REQUIREMENT — a feature,
+flag, refactor, abstraction, dependency, or "nice to have" that nobody asked for.
+Revert each one. "Clean code, wrong feature" is the worst failure mode and no
+later axis can catch it. This axis outranks all others. (If no ORIGINAL REQUEST
+is present — sandboxed verify run, no transcript — skip this axis.)
+
 ## 1. Correctness
 - The logic does what the task requires — no off-by-one, inverted condition,
   wrong operator, wrong return value, wrong import path.
@@ -36,17 +45,23 @@ code they touch.
 - Add the missing tests; delete tautological ones.
 
 ## 4. Anti-slop
-- If `~/.cursor/skills/anti-slop/scripts/scan_slop.py` exists (INSTALL.md step 2
-  copies it there), run the whole-codebase duplication scan:
+Axis 0 already caught intent drift. This axis catches code-shape and cost slop
+across the whole session diff.
+
+Step A — mechanical scan (if available):
+  If `~/.cursor/skills/anti-slop/scripts/scan_slop.py` exists, run:
     python ~/.cursor/skills/anti-slop/scripts/scan_slop.py --all
-  If it does NOT exist, do not treat that as a failure and do not hunt for the
-  file: apply the checklist in `~/.agents/hooks/anti-slop.md` to the session
-  diff and look for duplicate function bodies in the files you touched.
-- Either way, consolidate clones: same function in many files / identical bodies
-  (the isRecord-class) → ONE shared definition, re-point imports, delete the
-  copies.
-- Premature abstraction (Factory / Repository / Mediator / CQRS / DDD with fewer
-  than 2–3 real call sites), unnecessary dependencies, redundant restate-the-code
-  comments, dead helpers, accidental complexity → remove.
-
-Fix with edits now; re-run the scan and the tests; then stop.
+  If it does NOT exist, skip Step A (not a failure; do not hunt for the file).
+
+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.
+
+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.
+
+Fix with edits now; re-run the scan (if Step A ran) and the tests; then stop.

package/linux/hooks/final-review.sh

@@ -1,8 +1,8 @@
 #!/usr/bin/env bash
 # final-review.sh - stop hook (Cursor, Linux).
 #
-# ONE comprehensive end-of-implementation review across four axes:
-# correctness, reliability, coverage, and anti-slop. When the agent finishes
+# ONE comprehensive end-of-implementation review across five axes:
+# intent, correctness, reliability, coverage, and anti-slop. 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.
@@ -76,11 +76,11 @@ if [ -z "$body" ]; then
      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 - 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 (a missing scanner
-     is not a failure). Consolidate clones/duplicates to one source of truth;
-     drop premature abstraction, unneeded deps, redundant comments, dead helpers.
+  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.
 Fix now, re-run the scan + tests, then stop. If an axis is clean, say so in one line.'
 fi
 body="$(expand_agent_paths "$body")"
@@ -94,9 +94,31 @@ done <<EOF
 $edited
 EOF
 file_list="$(printf '%s' "$file_list" | head -n 30)"
-msg="FINAL REVIEW (end of implementation) - correctness, reliability, coverage, anti-slop.
 
-Files you changed this session:
+# Tier 0: extract the last user <user_query> from the transcript so the model
+# can trace every diff hunk back to a concrete request. Anything untraceable is
+# a hallucinated requirement. Empty when there is no transcript or no
+# user_query (sandboxed verify runs, fresh installs) - the axis is then a no-op.
+user_query="$(extract_last_user_query "$input")"
+intent_block=""
+[ -n "$user_query" ] && intent_block="ORIGINAL REQUEST (your last user message, for intent trace):
+---
+$user_query
+---
+
+"
+
+# Tier 5: cross-file change-surface metric. The per-file afterFileEdit audits
+# miss the 50-file rename case; this seeds the whole-session footprint so the
+# model can judge whether the change surface is proportional to the request.
+unique_files="$(printf '%s\n' "$edited" | grep -c -v '^$')"
+surface_block="Session footprint: ${unique_files} file(s) touched. If a simple request produced >5 files or >200 lines, justify each file's inclusion or trim.
+
+"
+
+msg="FINAL REVIEW (end of implementation) - intent, correctness, reliability, coverage, anti-slop.
+
+${surface_block}${intent_block}Files you changed this session:
 $file_list
 
 $body"

package/linux/hooks/hook-common.sh

@@ -105,6 +105,76 @@ resolve_agent_path() {
     esac
 }
 
+# extract_last_user_query <json> -> text of the last <user_query> in this
+# conversation's transcript, or '' if there is none. Capped at 2000 chars.
+#
+# This is the Tier 0 intent-trace primitive: the final-review hook prepends the
+# extracted request to its followup so the model must trace every diff hunk back
+# to it. Anything untraceable is a hallucinated requirement.
+#
+# Walks the JSONL backward via tac (preferred) or a portable awk fallback; finds
+# the first (last) user record whose content carries a <user_query> tag.
+extract_last_user_query() {
+    local json="$1"
+    local tp
+    tp="$(json_get "$json" transcript_path)"
+    [ -n "$tp" ] && [ -f "$tp" ] || return 0
+
+    local reversed
+    if command -v tac >/dev/null 2>&1; then
+        reversed="$(tac "$tp" 2>/dev/null)"
+    else
+        # Portable fallback: awk NR table reversed.
+        reversed="$(awk '{a[NR]=$0} END {for(i=NR;i>=1;i--) print a[i]}' "$tp" 2>/dev/null)"
+    fi
+    [ -n "$reversed" ] || return 0
+
+    # Pull the text out via python3 if available (handles JSON content arrays);
+    # fall back to a pure-grep that handles string-typed content.
+    if have_py; then
+        printf '%s' "$reversed" | python3 -c '
+import json, re, sys
+try:
+    for line in sys.stdin:
+        line = line.strip()
+        if not line or "\"role\"" not in line:
+            continue
+        try:
+            rec = json.loads(line)
+        except Exception:
+            continue
+        if not isinstance(rec, dict) or rec.get("role") != "user":
+            continue
+        msg = rec.get("message") or {}
+        content = msg.get("content")
+        text = ""
+        if isinstance(content, str):
+            text = content
+        elif isinstance(content, list):
+            for p in content:
+                if isinstance(p, dict) and p.get("type") == "text" and p.get("text"):
+                    text += p["text"]
+        m = re.search(r"<user_query>\s*(.+?)\s*</user_query>", text, re.S)
+        if m:
+            q = m.group(1).strip()
+            if len(q) > 2000:
+                q = q[:2000] + "..."
+            print(q)
+            break
+except Exception:
+    pass
+' 2>/dev/null
+        return 0
+    fi
+
+    # No python3: best-effort grep for the common case where the user message
+    # is the only place <user_query> appears in a line. Imperfect but bounded.
+    printf '%s' "$reversed" |
+        grep -m1 -oE '<user_query>[^<]*</user_query>' 2>/dev/null |
+        sed -E 's@</?user_query>@@g' |
+        head -c 2000
+}
+
 # merge_subagent_edit_markers <json> <parent_cid> -> 0 if anything was folded
 #
 # Subagent edits fire afterFileEdit under the SUBAGENT's conversation_id, so

package/linux/hooks/self-review.md

@@ -19,6 +19,13 @@ file. Your job, on this turn, is to:
      - **Logic bugs that the user would actually care about**: a function
        that returns the wrong thing, an off-by-one, a missing `return`, a
        wrong import path.
+     - **Semantic contracts**: did any existing function's BEHAVIOR change
+       without its name, signature, or docstring changing? Names are
+       contracts. `deleteUser()` that now soft-deletes, a getter that now
+       writes, a function that used to throw on bad input and now silently
+       returns null — these are silent contract breaks that callers will
+       rely on and break against. If behavior changed, the name, signature,
+       or docstring must reflect it.
   4. If you find a real bug, **fix it with `Edit`**, then say nothing.
      Do not report it. Do not explain it. The user will see the fix
      in the next message; the bug is gone.

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 four-axis review never fires for
+# that marker is never drained and the five-axis review never fires for
 # delegated implementations. This hook closes the loop: when a subagent
 # finishes and ITS conversation has a session-edits marker, return ONE
 # followup_message so the subagent audits its own implementation before the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cursordoctrine",
-  "version": "0.1.1",
-  "description": "Thin self-review hooks for Cursor — the model is the auditor. One command installs the doctrine, the hook pack, and the anti-slop skill.",
+  "version": "0.2.1",
+  "description": "Thin self-review hooks for Cursor — the model is the auditor. Intent-trace final review (Tier 0), unified 13-item anti-slop checklist, operational slop detection.",
   "bin": {
     "cursordoctrine": "bin/cli.mjs"
   },

package/skills/anti-slop/SKILL.md

@@ -223,10 +223,15 @@ management*, not token volume — one source of truth per concept.
 
 ## Automatic final review
 
-The `stop` hook (`anti-slop-final-review.ps1`) fires after the agent finishes
-an implementation that edited files: it returns a `followup_message` Cursor
-auto-submits, so the model re-audits everything it changed this session and
-removes slop it introduced — one bounded pass.
+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
+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.
 
 ## Hard constraints
 
@@ -259,9 +264,11 @@ Diff: {before} → {after} lines.   Tests: {pass | n/a}
 | Install path | `~/.cursor/skills/anti-slop/` |
 | Invoke | `/anti-slop`, or "remove the AI slop" |
 | Scanner | `python scripts/scan_slop.py --all` |
-| Final review | automatic via `stop` hook |
+| Final review | automatic via `stop` hook (`final-review.ps1` / `final-review.sh`) |
+| Hook checklist | `~/.agents/hooks/anti-slop.md` (13 items; per-edit + final-review axis 4) |
 
 The scanner is stdlib-only and needs Python 3.9+. Pairs with the **anti-slop
-hook** (advisory, per edit), the **stop hook** (auto final review), and
-**minimal-editing** (smallest-diff). This skill is the active "delete it now"
-layer those only nudge toward.
+audit hook** (`anti-slop-audit.ps1` / `.sh`, advisory per edit), the **stop
+hook** (`final-review.ps1` / `.sh`, five-axis session review incl. intent
+trace), and **minimal-editing** (smallest-diff). This skill is the active
+"delete it now" layer those only nudge toward.

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

@@ -13,6 +13,8 @@
 #       *Strategy / *Singleton / *Facade / *Builder / *Visitor / *Decorator
 #       class, or CQRS / Event-Sourcing / DDD vocabulary
 #     * redundant comments that merely restate the next line of code
+#     * operational slop (Tier 3): retry-without-backoff, await-in-loop,
+#       telemetry spam (>= 6 log/print statements added in one edit)
 #
 #   Deferred to the model (semantic - no regex can judge these without drowning
 #   the user in false positives): edge cases, duplicated logic, ignored
@@ -128,6 +130,50 @@ foreach ($a in $added) {
     if ($redundant.Count -ge 4) { break }
 }
 
+# --- signal 4: operational slop (Tier 3) ----------------------------------
+# Retry-without-backoff: a retry loop or recursive retry without an obvious
+# sleep/backoff/setTimeout nearby. The whole-file body is scanned so the
+# backoff can sit above or below the retry; this is deliberately seed-grade
+# (high precision), not a verdict.
+$opsFlags = New-Object System.Collections.Generic.List[string]
+$bodyHas = {
+    param($pat)
+    foreach ($a in $added) { if ($a -match $pat) { return $true } }
+    return $false
+}
+$retryWord    = '\b(retry|retryCount|retries|maxRetries|attempt)\w*\b'
+$backoffWord  = '\b(sleep|setTimeout|backoff|back_off|exponential|jitter|delay)\w*\b'
+if (& $bodyHas $retryWord) {
+    $noBackoff = $true
+    foreach ($a in $added) { if ($a -match $backoffWord) { $noBackoff = $false; break } }
+    if ($noBackoff) {
+        $opsFlags.Add("- RETRY WITHOUT BACKOFF: a retry construct was added but no sleep/backoff/setTimeout is visible in this edit's added lines. Unbounded retries = retry storms + token/cost burn; add bounded backoff or confirm the runtime already throttles.")
+    }
+}
+
+# `await` (or `await ctx.db`) inside a loop construct on its own line — N+1 in
+# agent/edge code, not just SQL. We seed on the added-line co-occurrence of a
+# loop keyword and an awaited call; the model judges whether it is genuinely a
+# sequential-await loop (real slop) or a legit streaming pattern.
+$loopWord = '\b(for|while|forEach|map|filter|reduce|flatMap|for\s+await|async\s+for)\b'
+$awaitCall = '\bawait\s+(fetch|ctx\.db|ctx\.run|client\.|axios|prisma\.|supabase\.|db\.|repo\.)'
+if (& $bodyHas $loopWord) {
+    $awaitInLoop = $false
+    foreach ($a in $added) { if ($a -match $awaitCall) { $awaitInLoop = $true; break } }
+    if ($awaitInLoop) {
+        $opsFlags.Add("- AWAIT IN LOOP: a loop construct and an awaited IO call both appear in this edit. Sequential awaits in a loop = N+1 / serial latency; confirm whether Promise.all / a batch call / a single query is the right primitive. (If this is genuinely a streaming pattern, ignore.)")
+    }
+}
+
+# Telemetry spam seed: 6+ console.log / print / fmt.Print / std::cout::<< added
+# in one file. Models paste debug prints liberally; six is well past intent.
+$logRe = '\b(console\.(log|debug|info|warn|error)|print\(|fmt\.Print|std::cout|NSLog|System\.out\.println|println!|dbg!|console\.dir)\b'
+$logCount = 0
+foreach ($a in $added) { if ($a -match $logRe) { $logCount++ } }
+if ($logCount -ge 6) {
+    $opsFlags.Add("- TELEMETRY SPAM: $logCount log/print statements added in this one edit. Debug-level telemetry that nobody reads is slop; consolidate or remove (kept only if this is a real logging entrypoint).")
+}
+
 # --- decide whether to fire ----------------------------------------------
 $srcRe = '\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|kts|cs|cpp|cc|cxx|c|h|hpp|rb|php|swift|scala|m|mm|sh|ps1|lua|dart|ex|exs|vue|svelte)$'
 $addedCode = 0
@@ -139,6 +185,7 @@ $flags = New-Object System.Collections.Generic.List[string]
 if ($depAdded)              { $flags.Add("- DEPENDENCY: " + $base + " gained a dependency - is it necessary, or do the stdlib / existing deps already cover it?") }
 if ($patterns.Count -gt 0)  { $flags.Add("- PREMATURE ABSTRACTION: " + ($patterns -join ', ') + " - is there a real, present problem (2-3+ call sites that exist today) that needs it? If it is speculative, delete it and write the direct code.") }
 if ($redundant.Count -gt 0) { $flags.Add("- REDUNDANT COMMENTS: " + ($redundant -join ' | ') + " - delete comments that restate the code; keep only WHY.") }
+$flags.AddRange($opsFlags)
 
 if ($flags.Count -eq 0 -and -not $substantial) { exit 0 }
 
@@ -148,17 +195,14 @@ $checklist = ''
 if (Test-Path -LiteralPath $checklistFile) { $checklist = Get-Content -Raw -LiteralPath $checklistFile }
 if (-not $checklist) {
     $checklist = @'
-ANTI-SLOP SELF-REVIEW - audit the edit you just made and FIX (do not explain) any slop:
-  1. Edge cases beyond the happy path (null / empty / zero / boundary / error).
-  2. Duplicated logic that already exists in this repo - call it, do not re-implement.
-  3. Conventions - match the file's existing style / naming / structure / error-handling.
-  4. Unnecessary dependencies - remove libs the stdlib or an existing dep covers.
-  5. Premature abstraction - no Factory/Repository/Mediator/CQRS/DDD without 2-3 real call sites today.
-  6. Accidental complexity - flatten indirection a junior cannot read in 30s.
-  7. Tests assert real behaviour and edge cases, not just "it runs".
-  8. Cargo cult - delete any construct whose reason you cannot state.
-  9. Architecture - respect the project's layering and boundaries.
- 10. Redundant comments restating code - delete; keep only WHY.
+ANTI-SLOP — read ~/.agents/hooks/anti-slop.md (13 items). Fallback if missing:
+  1–10: edge cases, duplication, conventions, deps, premature abstraction,
+  accidental complexity, tests (no tautologies), cargo cult, architecture,
+  redundant comments / prompt residue.
+  11: semantic contracts (behavior change without name/signature change).
+  12: operational slop (retry w/o backoff, await-in-loop, telemetry spam).
+  13: change surface (too many files for a simple request).
+Fix guilty items now. Never revert what the user asked for.
 '@
 }
 

package/windows/hooks/anti-slop.md

@@ -1,56 +1,54 @@
-ANTI-SLOP SELF-REVIEW — you just edited a file. Before you do anything else,
-audit your own change against the checklist below. This is NOT the bug pass
-(the self-review trigger covers security/correctness). This is about *slop*:
-code that runs but should not ship.
-
-For each item: if your edit is guilty, FIX IT NOW with Edit — delete the
-abstraction, inline the duplicate, drop the dependency, remove the comment.
-Do not explain, do not report, just fix. If the edit is clean, say nothing.
-
-  1. EDGE CASES — Does it only handle the happy path? Check the null / empty /
-     zero / boundary / error inputs the task implies. An unhandled obvious
-     edge case is a bug waiting in production.
-
-  2. DUPLICATION — Did you write logic that already exists in this repo? Look
-     before you add. If it exists, call it; do not re-implement it.
-
-  3. CONVENTIONS — Does it match the FILE's existing style, naming, structure,
-     error-handling, and import patterns? Match the neighbours, not your
-     defaults.
-
-  4. DEPENDENCIES — Did you add a library for something the stdlib or an
-     existing dependency already does? Remove it. A new dependency must earn
-     its place.
-
-  5. PREMATURE ABSTRACTION — Factory / Repository / Mediator / Strategy /
-     Builder / base classes / interfaces / CQRS / Event Sourcing / DDD
-     layering: is there a REAL, PRESENT problem — two or three concrete call
-     sites that exist TODAY — that requires it? "For future flexibility" is
-     not a reason. Delete it and write the direct code. Abstraction debt is
-     layers without problems.
-
-  6. ACCIDENTAL COMPLEXITY — Could a junior read this in 30 seconds? Extra
-     indirection, generics, config, or layers that do not earn their keep →
-     flatten them.
-
-  7. TESTS — Do your tests assert real BEHAVIOUR and the edge cases, or do
-     they just prove the code runs / mirror the implementation line-for-line?
-     A test that cannot fail is slop. Make it verify outcomes.
-
-  8. CARGO CULT — Can you state WHY each non-obvious construct is there? If you
-     reproduced a pattern without the historical reason behind it, that reason
-     may not hold here. Remove what you cannot justify. Replicating a shape you
-     have seen is not the same as needing it.
-
-  9. ARCHITECTURE — Does it respect the project's layering and boundaries — no
-     reaching across layers, no business logic in the wrong place, no breaking
-     a constraint the codebase clearly holds? Honour the constraints.
-
- 10. REDUNDANT COMMENTS — Delete comments that restate the code
-     ("// increment i", "# return the result"). Keep only comments that
-     explain WHY, never WHAT.
-
-Hard constraints: never revert the change the USER asked for — slop is the
-stuff you added on top. Do not "improve" beyond removing slop. At most a few
-targeted edits, then stop. The bar: would this pass a senior review at a top
-engineering org without a single "why is this here?" comment.
+ANTI-SLOP SELF-REVIEW — you just edited a file (or you are auditing the
+session diff at final review). Code that runs but should not ship.
+
+Intent trace (Tier 0 — hallucinated requirements, scope drift) runs FIRST at
+stop via final-review axis 0, not here. This checklist covers code-shape and
+cost slop. Apply every item; if guilty, FIX with Edit — delete, inline, drop.
+Do not explain. If clean, say nothing.
+
+  1. EDGE CASES — Happy path only? Check null / empty / zero / boundary / error
+     inputs the task implies.
+
+  2. DUPLICATION — Logic that already exists in this repo? Call it; do not
+     re-implement. Same function in many files (isRecord-class) → one source.
+
+  3. CONVENTIONS — Match the FILE's style, naming, structure, error-handling,
+     imports. Not your defaults.
+
+  4. DEPENDENCIES — New library for something stdlib or an existing dep covers?
+     Remove it. A dependency must earn its place.
+
+  5. PREMATURE ABSTRACTION — Factory / Repository / Mediator / Strategy / Builder /
+     CQRS / Event Sourcing / DDD: is there a REAL problem with 2–3 call sites
+     TODAY? "Future flexibility" is not a reason. Delete and write direct code.
+
+  6. ACCIDENTAL COMPLEXITY — Could a junior read this in 30 seconds? Flatten
+     indirection, generics, config, layers that do not earn their keep.
+
+  7. TESTS (epistemic slop) — Assert real OUTCOMES and edge cases, not "it runs",
+     not a mirror of the implementation, not expect(true).toBe(true). A test
+     that cannot fail is slop.
+
+  8. CARGO CULT — Can you state WHY each non-obvious construct is there? Remove
+     what you cannot justify. A shape you have seen ≠ a shape you need.
+
+  9. ARCHITECTURE — Respect layering and boundaries. No reaching across layers,
+     no business logic in the wrong place, no breaking project constraints.
+
+ 10. REDUNDANT COMMENTS — Delete comments that restate the code ("// increment
+     i"). Keep only WHY, never WHAT. No prompt residue ("in a real app...").
+
+ 11. SEMANTIC CONTRACTS (Tier 1) — Did any existing function's BEHAVIOR change
+     without its name, signature, or docstring changing? Names are contracts.
+     deleteUser() that now soft-deletes is silent contract break.
+
+ 12. OPERATIONAL SLOP (Tier 3) — Retry loops without backoff/sleep/jitter?
+     await fetch / ctx.db / prisma inside a for/while/map? Six or more
+     console.log / print added in one edit? Token burn with no user value →
+     remove or bound.
+
+ 13. CHANGE SURFACE (Tier 5) — Did a simple request touch many files? Every
+     file in the diff must trace to the task. Trim unrelated hunks.
+
+Hard constraints: never revert what the USER asked for — slop is what got added
+on top. At most a few targeted edits, then stop.

package/windows/hooks/final-review.md

@@ -1,11 +1,20 @@
 FINAL REVIEW — you just finished an implementation. Before you treat it as done,
-audit EVERYTHING you changed this session across the four axes below and FIX what
+audit EVERYTHING you changed this session across the five axes below and FIX what
 fails. Do NOT revert the behaviour the user asked for. If an axis is already
 clean, say so in one line — do not manufacture work.
 
 Start by re-reading the diff. Scope the review to your session's changes and the
 code they touch.
 
+## 0. Intent trace (HIGHEST PRIORITY — run first)
+The hook extracted your last user message as "ORIGINAL REQUEST" above. For every
+hunk in the diff, answer: which part of the request forced this change? Anything
+that cannot trace to the request is a HALLUCINATED REQUIREMENT — a feature,
+flag, refactor, abstraction, dependency, or "nice to have" that nobody asked for.
+Revert each one. "Clean code, wrong feature" is the worst failure mode and no
+later axis can catch it. This axis outranks all others. (If no ORIGINAL REQUEST
+is present — sandboxed verify run, no transcript — skip this axis.)
+
 ## 1. Correctness
 - The logic does what the task requires — no off-by-one, inverted condition,
   wrong operator, wrong return value, wrong import path.
@@ -36,17 +45,23 @@ code they touch.
 - Add the missing tests; delete tautological ones.
 
 ## 4. Anti-slop
-- If `~/.cursor/skills/anti-slop/scripts/scan_slop.py` exists (INSTALL.md step 2
-  copies it there), run the whole-codebase duplication scan:
+Axis 0 already caught intent drift. This axis catches code-shape and cost slop
+across the whole session diff.
+
+Step A — mechanical scan (if available):
+  If `~/.cursor/skills/anti-slop/scripts/scan_slop.py` exists, run:
     python ~/.cursor/skills/anti-slop/scripts/scan_slop.py --all
-  If it does NOT exist, do not treat that as a failure and do not hunt for the
-  file: apply the checklist in `~/.agents/hooks/anti-slop.md` to the session
-  diff and look for duplicate function bodies in the files you touched.
-- Either way, consolidate clones: same function in many files / identical bodies
-  (the isRecord-class) → ONE shared definition, re-point imports, delete the
-  copies.
-- Premature abstraction (Factory / Repository / Mediator / CQRS / DDD with fewer
-  than 2–3 real call sites), unnecessary dependencies, redundant restate-the-code
-  comments, dead helpers, accidental complexity → remove.
-
-Fix with edits now; re-run the scan and the tests; then stop.
+  If it does NOT exist, skip Step A (not a failure; do not hunt for the file).
+
+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.
+
+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.
+
+Fix with edits now; re-run the scan (if Step A ran) and the tests; then stop.

package/windows/hooks/final-review.ps1

@@ -1,7 +1,7 @@
 # final-review.ps1 - stop hook (Cursor).
 #
-# ONE comprehensive end-of-implementation review across four axes:
-# correctness, reliability, coverage, and anti-slop. When the agent finishes an
+# ONE comprehensive end-of-implementation review across five axes:
+# intent, correctness, reliability, coverage, and anti-slop. 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
@@ -86,11 +86,11 @@ FINAL REVIEW - audit everything you changed this session and FIX what fails
      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 - 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 (a missing scanner
-     is not a failure). Consolidate clones/duplicates to one source of truth;
-     drop premature abstraction, unneeded deps, redundant comments, dead helpers.
+  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.
 Fix now, re-run the scan + tests, then stop. If an axis is clean, say so in one line.
 '@
 }
@@ -98,7 +98,24 @@ $body = Expand-AgentPaths $body
 
 $resolved = @($edited | ForEach-Object { Resolve-AgentPath $_ })
 $fileList = ($resolved | Select-Object -First 30) -join "`n  "
-$msg = "FINAL REVIEW (end of implementation) - correctness, reliability, coverage, anti-slop.`n`nFiles you changed this session:`n  $fileList`n`n$body"
+
+# Tier 0: extract the last user <user_query> from the transcript so the model
+# can trace every diff hunk back to a concrete request. Anything untraceable is
+# a hallucinated requirement. Empty when there is no transcript or no user_query
+# (sandboxed verify runs, fresh installs) — the axis is then a no-op.
+$userQuery = Get-LastUserQuery $obj
+$intentBlock = ''
+if ($userQuery) {
+    $intentBlock = "ORIGINAL REQUEST (your last user message, for intent trace):`n---`n$userQuery`n---`n`n"
+}
+
+# Tier 5: cross-file change-surface metric. The per-file afterFileEdit audits
+# miss the 50-file rename case; this seeds the whole-session footprint so the
+# model can judge whether the change surface is proportional to the request.
+$uniqueFiles = @($edited | Select-Object -Unique).Count
+$surfaceBlock = "Session footprint: $uniqueFiles file(s) touched. If a simple request produced >5 files or >200 lines, justify each file's inclusion or trim.`n`n"
+
+$msg = "FINAL REVIEW (end of implementation) - intent, correctness, reliability, coverage, anti-slop.`n`n${surfaceBlock}${intentBlock}Files you changed this session:`n  $fileList`n`n$body"
 
 # Arm the one-shot brake BEFORE emitting, so a crash after emit can't re-fire.
 New-Item -ItemType File -Path $flag -Force -ErrorAction SilentlyContinue | Out-Null

package/windows/hooks/hook-common.ps1

@@ -73,6 +73,47 @@ function Resolve-AgentPath([string]$p) {
     return ConvertTo-FwdPath $p
 }
 
+# Extract the last user <user_query> from a Cursor transcript JSONL. The
+# transcript is an array of {role, message} records; we walk backward from the
+# end, find the last user turn whose content has a <user_query> tag, and return
+# its text. Returns '' if there is no transcript or no user_query. Capped at
+# 2000 chars so the follow-up prompt stays bounded.
+#
+# This is the Tier 0 intent-trace primitive: the final-review hook prepends the
+# extracted request to its followup so the model must trace every diff hunk back
+# to it. Anything untraceable is a hallucinated requirement.
+function Get-LastUserQuery($obj) {
+    $tp = ''
+    if ($obj -and $obj.PSObject.Properties['transcript_path']) { $tp = [string]$obj.transcript_path }
+    if (-not $tp -or -not (Test-Path -LiteralPath $tp)) { return '' }
+    $lines = @(Get-Content -LiteralPath $tp -ErrorAction SilentlyContinue)
+    for ($i = $lines.Count - 1; $i -ge 0; $i--) {
+        $line = $lines[$i]
+        if (-not $line -or $line -notmatch '"role"\s*:\s*"user"') { continue }
+        try {
+            $rec = $line | ConvertFrom-Json -ErrorAction SilentlyContinue
+        } catch { continue }
+        if (-not $rec -or -not $rec.message) { continue }
+        $content = $rec.message.content
+        if (-not $content) { continue }
+        # content is an array of {type:text,text:...} or a plain string
+        $text = ''
+        if ($content -is [string]) {
+            $text = $content
+        } else {
+            foreach ($part in $content) {
+                if ($part.type -eq 'text' -and $part.text) { $text += $part.text }
+            }
+        }
+        if ($text -match '(?s)<user_query>\s*(.+?)\s*</user_query>') {
+            $q = $Matches[1].Trim()
+            if ($q.Length -gt 2000) { $q = $q.Substring(0, 2000) + '...' }
+            return $q
+        }
+    }
+    return ''
+}
+
 # Subagent edits fire afterFileEdit under the SUBAGENT's conversation_id, so
 # their session-edits markers are invisible to the parent's stop-hook review.
 # Subagent transcripts live at <transcripts>/<parent-cid>/subagents/<sub-cid>.jsonl,

package/windows/hooks/self-review.md

@@ -19,6 +19,13 @@ file. Your job, on this turn, is to:
      - **Logic bugs that the user would actually care about**: a function
        that returns the wrong thing, an off-by-one, a missing `return`, a
        wrong import path.
+     - **Semantic contracts**: did any existing function's BEHAVIOR change
+       without its name, signature, or docstring changing? Names are
+       contracts. `deleteUser()` that now soft-deletes, a getter that now
+       writes, a function that used to throw on bad input and now silently
+       returns null — these are silent contract breaks that callers will
+       rely on and break against. If behavior changed, the name, signature,
+       or docstring must reflect it.
   4. If you find a real bug, **fix it with `Edit`**, then say nothing.
      Do not report it. Do not explain it. The user will see the fix
      in the next message; the bug is gone.

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 four-axis review never fires for
+# that marker is never drained and the five-axis review never fires for
 # delegated implementations. This hook closes the loop: when a subagent
 # finishes and ITS conversation has a session-edits marker, return ONE
 # followup_message so the subagent audits its own implementation before the