cursordoctrine 0.2.2 → 0.3.0

package/INSTALL.md

@@ -110,4 +110,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`, `MINIMAL_EDITING_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`, `MINIMAL_EDITING_ENFORCE=0` (deprecated in 0.3.0), `SEMANTIC_DENSITY_ENFORCE=0`, `ANTI_SLOP_ENFORCE=0`, `FINAL_REVIEW_ENFORCE=0`, `SUBAGENT_REVIEW_ENFORCE=0`.

package/README.md

@@ -7,7 +7,7 @@ Thin self-review hooks for Cursor. Five hook events, one message bus. The model
 A small set of Cursor hooks that make the agent review its own work without bolting a static-analysis pipeline onto every keystroke. There is no regex army and no scoring engine. The hooks do three jobs:
 
 1. **Inject the doctrine** at session start, so every chat begins with the same short governing text (`doctrine.md` + `USER-RULES.md`).
-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.
+2. **Hand the model its own edits back.** After each agent edit, a self-review prompt (plus minimal-edit, semantic-density, 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. 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`.
@@ -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 (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. |
+| Edit | `afterFileEdit` + `stop` | `self-review-trigger` stashes the review prompt per edit; `minimal-edit-audit` (deprecated in 0.3.0), `semantic-density-audit`, and `anti-slop-audit` append advisories when thresholds trip (new deps / premature abstraction / redundant comments / **semantic opacity**: low-density identifiers like `DataManager`, `process()`, `utils.ts` / Tier 3 operational slop: retry-without-backoff, await-in-loop, telemetry spam); `final-review` fires one end-of-implementation pass. |
 | 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
@@ -69,7 +69,8 @@ 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 |
-| `MINIMAL_EDITING_ENFORCE=0` | on | disables the over-edit advisory |
+| `MINIMAL_EDITING_ENFORCE=0` | on | disables the over-edit advisory (deprecated in 0.3.0) |
+| `SEMANTIC_DENSITY_ENFORCE=0` | on | disables the semantic-opacity advisory |
 | `ANTI_SLOP_ENFORCE=0` | on | disables the slop advisory |
 | `FINAL_REVIEW_ENFORCE=0` | on | disables the final review pass |
 | `SUBAGENT_REVIEW_ENFORCE=0` | on | disables the in-subagent review pass |

package/bin/cli.mjs

@@ -370,12 +370,13 @@ Examples
   npx cursordoctrine uninstall
 
 Kill switches (environment variables, all hooks fail open)
-  HOOKS_ENFORCE=0            everything advisory off
-  PERM_GATE_ENFORCE=0        permission gate off
-  MINIMAL_EDITING_ENFORCE=0  over-edit advisory off
-  ANTI_SLOP_ENFORCE=0        slop advisory off
-  FINAL_REVIEW_ENFORCE=0     final review off
-  SUBAGENT_REVIEW_ENFORCE=0  in-subagent review off
+  HOOKS_ENFORCE=0              everything advisory off
+  PERM_GATE_ENFORCE=0          permission gate off
+  MINIMAL_EDITING_ENFORCE=0    over-edit advisory off (deprecated in 0.3.0)
+  SEMANTIC_DENSITY_ENFORCE=0   semantic-opacity advisory off
+  ANTI_SLOP_ENFORCE=0          slop advisory off
+  FINAL_REVIEW_ENFORCE=0       final review off
+  SUBAGENT_REVIEW_ENFORCE=0    in-subagent review off
 
 Docs  https://github.com/kleosr/cursordoctrine`);
 }

package/linux/hooks/minimal-edit-audit.sh

@@ -1,6 +1,14 @@
 #!/usr/bin/env bash
 # minimal-edit-audit.sh - afterFileEdit minimal-editing advisory (Cursor, Linux).
 #
+# DEPRECATED in 0.3.0 (superseded by semantic-density-audit.sh + the
+# declared-editing discipline; removal slated for 0.4.0). The line-count
+# heuristic here is the size-based gate the cursordoctrine audit identified
+# as the antipattern: it penalizes legitimate large declared changes and
+# misses small quiet drifts. Retained for compatibility with existing installs;
+# new installs register semantic-density-audit.sh alongside it. To opt out of
+# the deprecated hook without uninstalling: MINIMAL_EDITING_ENFORCE=0.
+#
 # Audits the just-edited file for over-editing:
 #   * line-count    - git diff --numstat thresholds (any language).
 #   * token metrics - audit-metrics.py (token-Levenshtein + cognitive

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

@@ -0,0 +1,151 @@
+#!/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.
+#
+# Mechanism: extract ADDED lines from `git diff HEAD -- <rel>` (with the
+# untracked-file fallback anti-slop-audit uses), pipe them to density_scan.py
+# (a thin wrapper over the shared low_density module), read back one JSON
+# object of findings, append a short advisory to the shared pending-feedback
+# file. One denylist, shared with scan_slop.py's semantic_density bucket -
+# zero drift between the per-edit advisory and the audit-of-record.
+#
+# FAIL findings (DataManager / Utils / placeholder names) always fire. WARN
+# findings (defensible DDD with a domain noun - PostgresUserRepository) only
+# fire when at least one FAIL is also present, so the hook stays quiet on
+# legitimate code and loud on the real slop.
+#
+# Advisory only: never blocks, never persists state, ALWAYS exits 0.
+# Disable: HOOKS_ENFORCE=0  or  SEMANTIC_DENSITY_ENFORCE=0
+
+set +e
+. "$(dirname "$0")/hook-common.sh"
+
+[ "${HOOKS_ENFORCE:-}" = "0" ] && exit 0
+[ "${SEMANTIC_DENSITY_ENFORCE:-}" = "0" ] && exit 0
+
+input="$(read_hook_stdin)"
+[ -n "$input" ] || exit 0
+
+# audit root: project from JSON (cwd, then workspace_roots), else CURSOR_PROJECT_DIR / HOME
+root=""
+while IFS= read -r cand; do
+    [ -n "$cand" ] && [ -d "$cand" ] && { root="${cand%/}"; break; }
+done <<EOF
+$(json_get "$input" cwd)
+$(json_get_array "$input" workspace_roots)
+EOF
+[ -n "$root" ] || root="${CURSOR_PROJECT_DIR:-$HOME}"
+root="${root%/}"
+
+# edited file -> repo-relative path
+fp=""
+for k in file_path path filename absolute_path abs_path; do
+    fp="$(json_get "$input" "$k")"
+    [ -n "$fp" ] && break
+done
+[ -n "$fp" ] || exit 0
+rel="$fp"
+case "$rel" in "$root"/*) rel="${rel#"$root"/}" ;; esac
+if is_cursor_config_path "$fp" || is_cursor_config_path "$rel"; then exit 0; fi
+
+# git repo?
+git -C "$root" rev-parse --git-dir >/dev/null 2>&1 || exit 0
+
+# --- collect ADDED lines for this file (working tree vs HEAD) --------------
+added="$(git -C "$root" diff HEAD -- "$rel" 2>/dev/null |
+    grep -E '^\+' | grep -vE '^\+\+\+' | cut -c2- | head -n 1500)"
+if [ -z "$added" ]; then
+    # untracked / brand-new file: whole file is "added"
+    if ! git -C "$root" ls-files --error-unmatch -- "$rel" >/dev/null 2>&1; then
+        [ -f "$root/$rel" ] && added="$(head -n 1500 "$root/$rel")"
+    fi
+fi
+[ -n "$added" ] || exit 0
+
+# --- resolve Python + run density_scan.py ---------------------------------
+# Linux ships python3; fall back to python for older distros.
+py=""
+for c in python3 python; do
+    if command -v "$c" >/dev/null 2>&1; then py="$c"; break; fi
+done
+[ -n "$py" ] || exit 0   # no Python -> fail open, scanner unavailable
+
+scanner="$HOME/.cursor/skills/anti-slop/scripts/density_scan.py"
+[ -f "$scanner" ] || exit 0   # skill not installed -> silent
+
+# Pipe added lines to the scanner, read JSON back.
+mout="$(printf '%s\n' "$added" | "$py" "$scanner" --rel "$rel" 2>/dev/null)"
+[ -n "$mout" ] || exit 0
+
+# --- parse JSON findings with python (the hook already requires python) ----
+# jq would be ideal but the installer notes python3 as the fallback; reuse it.
+parse_json() {
+    "$py" - "$@" <<'PYEOF' 2>/dev/null
+import json, sys
+try:
+    p = json.loads(sys.stdin.read())
+except Exception:
+    sys.exit(1)
+fails = [f for f in p.get("findings", []) if f.get("severity") == "fail"]
+warns = [f for f in p.get("findings", []) if f.get("severity") == "warn"]
+if not fails and not warns:
+    sys.exit(2)
+# WARNs only fire alongside a FAIL (defensible DDD stays quiet on clean code).
+flagged = fails + (warns if fails else [])
+lines = []
+for f in (flagged)[:12]:
+    tag = f.get("severity", "").upper()
+    ln = f.get("line", 0)
+    where = f"line {ln}" if ln and ln > 0 else "file name"
+    reason = "; ".join(f.get("reasons", []))
+    if len(reason) > 110:
+        reason = reason[:107] + "..."
+    lines.append(f"  [{tag}] {f.get('kind','?')} '{f.get('name','?')}' ({where}): {reason}")
+print("\n".join(lines))
+print(f"__COUNTS__{len(fails)}__{len(warns)}")
+PYEOF
+}
+
+parsed="$(printf '%s' "$mout" | parse_json)"
+rc=$?
+[ "$rc" -eq 0 ] || exit 0   # parse failed or no findings -> silent
+
+# Split the parsed output: findings lines + the __COUNTS__N__N sentinel.
+counts_line="$(printf '%s\n' "$parsed" | grep '__COUNTS__' | tail -1)"
+findings_block="$(printf '%s\n' "$parsed" | grep -v '__COUNTS__')"
+fail_n="$(printf '%s' "$counts_line" | sed -E 's/.*__COUNTS__([0-9]+)__.*/\1/')"
+warn_n="$(printf '%s' "$counts_line" | sed -E 's/.*__[0-9]+__([0-9]+)/\1/')"
+
+# --- compose advisory ------------------------------------------------------
+summary="Semantic-density audit - $rel - ${fail_n} FAIL, ${warn_n} WARN"
+
+advice='  High-density names are predictable from the name alone (InvoiceEmailSender,
+  PostgresUserRepository, GenerateMonthlyReport). Low-density names name a
+  category, not a thing (Manager, Utils, process, handleThing). Rename so the
+  identifier states its concrete responsibility. WARNs with a domain noun are
+  defensible DDD and can be left if intentional.'
+
+msg="${summary}
+
+${findings_block}
+
+${advice}
+
+(Advisory; disable: SEMANTIC_DENSITY_ENFORCE=0)"
+
+# --- append to the shared pending file --------------------------------------
+cid="$(safe_conversation_id "$input")"
+pending="$(hooks_pending_dir)/feedback-${cid}.txt"
+mkdir -p "$(dirname "$pending")" 2>/dev/null
+if [ -s "$pending" ]; then
+    printf '\n\n---\n\n%s' "$msg" >> "$pending" 2>/dev/null
+else
+    printf '%s' "$msg" >> "$pending" 2>/dev/null
+fi
+
+exit 0

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

@@ -1,103 +1,103 @@
-#!/usr/bin/env bash
-# subagent-stop-review.sh - subagentStop for Cursor (Linux).
-#
-# Counterpart of final-review.sh for delegated work. afterFileEdit DOES fire
-# inside subagents (verified: a subagent run left its edits in
-# session-edits-<subagent-cid>.txt), but subagents get no `stop` event, so
-# that marker is never drained and the five-axis review never fires for
-# 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
-# result goes back to the parent.
-#
-# Same bounding pattern as final-review.sh:
-#   - marker-gated: no edits in the subagent run -> no review, no noise,
-#   - reviewed-<cid>.flag one-shot brake: the stop AFTER the review pass
-#     clears flag + marker and ends the loop (one review per implementation;
-#     resumed subagents with a second implementation get a second review),
-#   - loop_limit in hooks.json caps runaway follow-ups harness-side,
-#   - only on status == 'completed' when a status field is present.
-#
-# If subagentStop's stdin carries a conversation_id that doesn't match the
-# id afterFileEdit used, the marker lookup misses and this emits {} - the
-# marker fold in post-tool-use.sh / final-review.sh still routes the
-# subagent's edits into the parent's stop review as the backstop.
-#
-# Always emits valid JSON ({} = no follow-up). Review body reuses
-# final-review.md (embedded fallback if missing).
-# Disable: HOOKS_ENFORCE=0 or SUBAGENT_REVIEW_ENFORCE=0.
-
-set +e
-. "$(dirname "$0")/hook-common.sh"
-
-emit_none() { printf '{}'; exit 0; }
-
-[ "${HOOKS_ENFORCE:-}" = "0" ] && emit_none
-[ "${SUBAGENT_REVIEW_ENFORCE:-}" = "0" ] && emit_none
-
-input="$(read_hook_stdin)"
-[ -n "$input" ] || emit_none
-
-status="$(json_get "$input" status)"
-cid="$(safe_conversation_id "$input")"
-
-pending_dir="$(hooks_pending_dir)"
-marker="$pending_dir/session-edits-$cid.txt"
-flag="$pending_dir/reviewed-$cid.flag"
-
-# One-shot brake: the previous subagentStop for this id emitted the review.
-if [ -f "$flag" ]; then
-    rm -f "$flag" "$marker" 2>/dev/null
-    emit_none
-fi
-
-# Review only a clean completion; otherwise clear the marker and stop.
-if [ -n "$status" ] && [ "$status" != "completed" ]; then
-    rm -f "$marker" 2>/dev/null
-    emit_none
-fi
-
-# No edits this run -> nothing to review.
-[ -f "$marker" ] || emit_none
-edited="$(grep -vE '^[[:space:]]*$' "$marker" 2>/dev/null | sort -u)"
-rm -f "$marker" 2>/dev/null
-[ -n "$edited" ] || emit_none
-
-# Compose the follow-up review prompt (md preferred, embedded fallback).
-prompt_file="$HOME/.agents/hooks/final-review.md"
-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):
-  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.
-If an axis is clean, say so in one line. Then stop.'
-fi
-body="$(expand_agent_paths "$body")"
-
-file_list=""
-while IFS= read -r p; do
-    [ -n "$p" ] || continue
-    rp="$(resolve_agent_path "$p")"
-    file_list="${file_list}  ${rp}"$'\n'
-done <<EOF
-$edited
-EOF
-file_list="$(printf '%s' "$file_list" | head -n 30)"
-msg="SUBAGENT FINAL REVIEW - you just finished delegated implementation work. Before your result returns to the parent agent, audit it.
-
-Files you changed this run:
-$file_list
-
-$body"
-
-# Arm the one-shot brake BEFORE emitting, so a crash after emit can't re-fire.
-touch "$flag" 2>/dev/null
-
-emit_json followup_message "$msg"
-exit 0
+#!/usr/bin/env bash
+# subagent-stop-review.sh - subagentStop for Cursor (Linux).
+#
+# Counterpart of final-review.sh for delegated work. afterFileEdit DOES fire
+# inside subagents (verified: a subagent run left its edits in
+# session-edits-<subagent-cid>.txt), but subagents get no `stop` event, so
+# that marker is never drained and the five-axis review never fires for
+# 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
+# result goes back to the parent.
+#
+# Same bounding pattern as final-review.sh:
+#   - marker-gated: no edits in the subagent run -> no review, no noise,
+#   - reviewed-<cid>.flag one-shot brake: the stop AFTER the review pass
+#     clears flag + marker and ends the loop (one review per implementation;
+#     resumed subagents with a second implementation get a second review),
+#   - loop_limit in hooks.json caps runaway follow-ups harness-side,
+#   - only on status == 'completed' when a status field is present.
+#
+# If subagentStop's stdin carries a conversation_id that doesn't match the
+# id afterFileEdit used, the marker lookup misses and this emits {} - the
+# marker fold in post-tool-use.sh / final-review.sh still routes the
+# subagent's edits into the parent's stop review as the backstop.
+#
+# Always emits valid JSON ({} = no follow-up). Review body reuses
+# final-review.md (embedded fallback if missing).
+# Disable: HOOKS_ENFORCE=0 or SUBAGENT_REVIEW_ENFORCE=0.
+
+set +e
+. "$(dirname "$0")/hook-common.sh"
+
+emit_none() { printf '{}'; exit 0; }
+
+[ "${HOOKS_ENFORCE:-}" = "0" ] && emit_none
+[ "${SUBAGENT_REVIEW_ENFORCE:-}" = "0" ] && emit_none
+
+input="$(read_hook_stdin)"
+[ -n "$input" ] || emit_none
+
+status="$(json_get "$input" status)"
+cid="$(safe_conversation_id "$input")"
+
+pending_dir="$(hooks_pending_dir)"
+marker="$pending_dir/session-edits-$cid.txt"
+flag="$pending_dir/reviewed-$cid.flag"
+
+# One-shot brake: the previous subagentStop for this id emitted the review.
+if [ -f "$flag" ]; then
+    rm -f "$flag" "$marker" 2>/dev/null
+    emit_none
+fi
+
+# Review only a clean completion; otherwise clear the marker and stop.
+if [ -n "$status" ] && [ "$status" != "completed" ]; then
+    rm -f "$marker" 2>/dev/null
+    emit_none
+fi
+
+# No edits this run -> nothing to review.
+[ -f "$marker" ] || emit_none
+edited="$(grep -vE '^[[:space:]]*$' "$marker" 2>/dev/null | sort -u)"
+rm -f "$marker" 2>/dev/null
+[ -n "$edited" ] || emit_none
+
+# Compose the follow-up review prompt (md preferred, embedded fallback).
+prompt_file="$HOME/.agents/hooks/final-review.md"
+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):
+  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.
+If an axis is clean, say so in one line. Then stop.'
+fi
+body="$(expand_agent_paths "$body")"
+
+file_list=""
+while IFS= read -r p; do
+    [ -n "$p" ] || continue
+    rp="$(resolve_agent_path "$p")"
+    file_list="${file_list}  ${rp}"$'\n'
+done <<EOF
+$edited
+EOF
+file_list="$(printf '%s' "$file_list" | head -n 30)"
+msg="SUBAGENT FINAL REVIEW - you just finished delegated implementation work. Before your result returns to the parent agent, audit it.
+
+Files you changed this run:
+$file_list
+
+$body"
+
+# Arm the one-shot brake BEFORE emitting, so a crash after emit can't re-fire.
+touch "$flag" 2>/dev/null
+
+emit_json followup_message "$msg"
+exit 0

package/linux/hooks.json

@@ -19,7 +19,13 @@
         "command": "bash ~/.agents/hooks/minimal-edit-audit.sh",
         "timeout": 15,
         "matcher": "^(Write|StrReplace|EditNotebook)$",
-        "_comment": "15s: minimal-editing advisory on the edited file (git --numstat line-count + audit-metrics.py token metrics on .py, from ~/.cursor/skills/minimal-editing/ if installed). Appends findings to the conversation's pending file; never blocks. Disable: HOOKS_ENFORCE=0 or MINIMAL_EDITING_ENFORCE=0."
+        "_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,
+        "matcher": "^(Write|StrReplace|EditNotebook)$",
+        "_comment": "15s: semantic-opacity advisory on the edited file. Extracts added lines from git diff, pipes to density_scan.py (shared low_density module), flags identifiers that communicate no intent (DataManager, process(), utils.ts, CoreEngine). FAIL = bare low-density token or generic-suffix class without domain noun; WARN = defensible DDD with domain noun (PostgresUserRepository) - only fires alongside a FAIL so clean code stays quiet. One denylist shared with scan_slop.py's semantic_density bucket. Appends to pending; never blocks. Disable: HOOKS_ENFORCE=0 or SEMANTIC_DENSITY_ENFORCE=0."
       },
       {
         "command": "bash ~/.agents/hooks/anti-slop-audit.sh",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursordoctrine",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "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"
@@ -14,7 +14,10 @@
     "windows/",
     "linux/",
     "skills/",
-    "INSTALL.md"
+    "INSTALL.md",
+    "!**/__pycache__",
+    "!**/*.pyc",
+    "!**/*.pyo"
   ],
   "repository": {
     "type": "git",

package/skills/anti-slop/SKILL.md

@@ -20,7 +20,7 @@ description: >-
   duplicate utilities.
 metadata:
   layer: active-cleanup
-  pairs-with: minimal-editing, anti-slop-hook
+  pairs-with: declared-editing (supersedes minimal-editing), semantic-density-audit
 ---
 
 # Anti-Slop
@@ -160,6 +160,7 @@ Walk every row. Rows tagged *(scanner)* are seeded mechanically by
 | **Duplicated logic** | new code mirrors something already in the repo | Delete the copy; call the existing function. Grep before you keep it. |
 | **Clone proliferation / DRY / Knowledge duplication** | `--all` reports the same function name in ≥2 files, or identical bodies under different names (`isRecord` / `isObject` / `isPlainObject`) | Keep ONE canonical definition; re-point imports; delete the copies. One source of truth per concept. |
 | **Utility explosion / Helper Hell / Fingerprints** | a swarm of tiny `is*` / `assert*` / `safe*` one-liners; fingerprints (`isRecord`, `safeParse`, `sleep`, `retry`, `assertNever`) | Inline single-use micro-helpers; consolidate genuinely shared ones into one module. |
+| **Semantic opacity / low-density names** *(scanner)* | identifiers that exist but communicate no intent: `DataManager`, `CoreEngine`, `process()`, `handleThing`, `utils.ts`, `x1`, `tempFix`, `finalFinal`. FAIL = bare low-density token or generic-suffix class with no domain noun; WARN = defensible DDD with a domain noun (`PostgresUserRepository`). Shared denylist lives in `low_density.py` and fires identically in `scan_slop.py --all` and the per-edit `semantic-density-audit` hook. | Rename to state the concrete responsibility: `DataManager` → `InvoiceRepository` or `PersistUserSessions`; `process` → `GenerateMonthlyReport`; `utils.ts` → `invoice_totals.ts`. Leave WARNs that are intentional DDD. |
 | **Ignored conventions** | style / naming / structure / error-handling differs from the file's neighbours | Rewrite to match the surrounding code. |
 | **Accidental complexity** | indirection / generics / config a junior can't read in 30s | Flatten to the simplest form that works. |
 | **Superficial tests / Test theater** | the test asserts "it runs", mirrors the implementation, or cannot fail; literal tautologies (`expect(true).toBe(true)`, `assert True`) *(scanner)*; snapshot-everything, mocks of mocks, assertion poverty | Rewrite to assert real outcomes and the edge cases; delete tautological tests. |
@@ -268,7 +269,10 @@ Diff: {before} → {after} lines.   Tests: {pass | n/a}
 | 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
-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.
+audit hook** (`anti-slop-audit.ps1` / `.sh`, advisory per edit), the
+**semantic-density-audit hook** (`semantic-density-audit.ps1` / `.sh`, flags
+low-density identifiers per edit — shares `low_density.py` with this scanner's
+`semantic_density` bucket), the **stop hook** (`final-review.ps1` / `.sh`,
+five-axis session review incl. intent trace), and **declared-editing**
+(supersedes the deprecated `minimal-editing` size gate). This skill is the
+active "delete it now" layer those only nudge toward.

package/skills/anti-slop/scripts/density_scan.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""density_scan.py - per-edit semantic-density hook wrapper.
+
+The afterFileEdit hook (semantic-density-audit.{ps1,sh}) extracts the ADDED
+lines for the just-edited file from `git diff HEAD` and pipes them here on
+stdin. This wrapper scores them with the shared low_density module and emits
+one JSON object the hook can read. One job, one contract:
+
+    stdin:  added lines (one per line, leading '+' already stripped)
+    argv:   --rel <repo-relative path of the edited file>
+    stdout: {"rel": ..., "findings": [...], "count": N}
+            where each finding = {name, line, kind, severity, reasons}
+    exit:   0 always (advisory; the hook never blocks)
+
+Why a separate wrapper instead of `scan_slop.py --added-json -`? scan_slop's
+per-file signal loop is the right granularity for a whole-codebase audit, but
+the hook needs ONE call that ingests pre-extracted added lines and returns
+density findings only - no dep/abstraction/residue detection (that is
+anti-slop-audit's job, already running in the same afterFileEdit slot). This
+keeps the two hooks non-overlapping and the density path fast (<50ms typical).
+
+Stdlib only; Python 3.9+. REPORTS only - never edits.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import Any
+
+# Resolve sibling low_density.py + scan_slop.py the same way low_density does.
+_SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+if _SCRIPT_DIR not in sys.path:
+    sys.path.insert(0, _SCRIPT_DIR)
+
+import low_density  # noqa: E402  (path set up above)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(
+        description="Per-edit semantic-density scorer (hook wrapper).")
+    ap.add_argument("--rel", required=True,
+                    help="repo-relative path of the edited file (used for "
+                         "language detection and filename scoring)")
+    ap.add_argument("--max-lines", type=int, default=2000,
+                    help="cap on stdin lines read (runtime bound, matches the "
+                         "hook's own 1500-line git cap with headroom)")
+    args = ap.parse_args()
+
+    rel = args.rel.replace("\\", "/").lstrip("/")
+
+    # Read added lines from stdin. The hook already stripped leading '+' and
+    # '+++' headers and applied its own cap; we apply a defensive second cap.
+    added: list[str] = []
+    try:
+        for i, line in enumerate(sys.stdin):
+            if i >= args.max_lines:
+                break
+            added.append(line.rstrip("\n"))
+    except (KeyboardInterrupt, IOError):
+        pass
+
+    findings: list[dict[str, Any]] = low_density.score_identifiers(added, rel)
+
+    payload = {
+        "rel": rel,
+        "findings": findings,
+        "count": len(findings),
+        "fail_count": sum(1 for f in findings if f.get("severity") == "fail"),
+        "warn_count": sum(1 for f in findings if f.get("severity") == "warn"),
+    }
+    print(json.dumps(payload))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())