cursordoctrine 0.3.1 → 0.3.3

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` (deprecated in 0.3.0), `SEMANTIC_DENSITY_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`, `SCOPE_GATE_ENFORCE=0`, `ANTI_SLOP_ENFORCE=0`, `FINAL_REVIEW_ENFORCE=0`, `SUBAGENT_REVIEW_ENFORCE=0`.

package/README.md

@@ -1,65 +1,81 @@
-# cursordoctrine
+<div align="center">
+  <img src="https://img.shields.io/badge/node-%3E%3D18-339933?style=flat-square&logo=node.js&logoColor=white" />
+  <img src="https://img.shields.io/npm/v/cursordoctrine?style=flat-square&color=blue" />
+  <img src="https://img.shields.io/badge/license-MIT-brightgreen?style=flat-square" />
+  <img src="https://img.shields.io/badge/built%20for-Cursor-6c47ff?style=flat-square" />
+</div>
 
-Thin self-review hooks for Cursor. Five hook events, one message bus. The model is the auditor Cursor only carries context and gates blast radius.
+<br />
+
+<div align="center">
+  <h1>cursordoctrine</h1>
+  <p><strong>Thin self-review hooks for Cursor.</strong></p>
+  <p>Five hook events, one message bus.<br />The model audits its own work. Cursor carries context and gates blast radius.</p>
+</div>
+
+<br />
+
+---
 
 ## What this is
 
-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:
+Cursor hooks that make the agent review its own edits without bolting a static-analysis pipeline onto every keystroke. No regex army, no scoring engine. Three jobs:
 
-1. **Inject the doctrine** at session start, so every chat begins with the same short governing text (`doctrine.md` + `USER-RULES.md` + `declared-editing.md` — the YAGNI ultra ladder that prevents over-building before a single line is written).
-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.
+1. **Inject the doctrine** at session start — every chat starts with the same short governing text (`doctrine.md`, `USER-RULES.md`, and `declared-editing.md`, the YAGNI ultra ladder that stops over-building before a line gets written).
+2. **Hand the model its own edits back** — after each agent edit, a self-review prompt goes into a pending file (plus minimal-edit, semantic-density, and anti-slop advisories when they trip). Next turn the model reads its diff, fixes real bugs, stays quiet otherwise.
+3. **Gate blast radius** — one permission gate denies a short explicit list of dangerous commands (`rm -rf /`, `curl | sh`, force-push, `npm publish`, ...). Everything else passes.
 
-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`.
+When an implementation finishes, the stop hook runs one final review over everything that changed, then stops. Five axes. The first is **intent trace**: the hook pulls your last user message from the transcript and prepends it to the review so the model has to tie every diff hunk to a concrete request. Anything it can't trace is a hallucinated requirement and gets reverted. That's the only check that catches "clean code, wrong feature" — linters and later axes miss it.
 
-This setup is for Cursor only. It installs into `~/.cursor` and `~/.agents/hooks` and touches nothing in your projects.
+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`.
 
-## Layout
+Cursor only. Installs into `~/.cursor` and `~/.agents/hooks`. Doesn't touch your projects.
 
+## Install
+
+Node 18+:
+
+```bash
+npx cursordoctrine@latest install   # copies the hook pack into ~/.agents/hooks + ~/.cursor, merges hooks.json
+npx cursordoctrine verify           # smoke-tests every hook with fake payloads, no restart needed
 ```
-windows/          PowerShell hooks (pwsh) — install on Windows machines
-  hooks.json      hook wiring for ~/.cursor/hooks.json
-  inject-doctrine.ps1, doctrine.md, USER-RULES.md
-  hooks/          the eight scripts + the three prompt files
-linux/            bash hooks — install on Linux machines and SSH remotes
-  hooks.json, inject-doctrine.sh, doctrine.md, USER-RULES.md
-  hooks/          same hooks, ported to bash (jq preferred, python3 fallback)
-skills/           Cursor agent skills shipped with the package
-  anti-slop/      SKILL.md + the duplication scanner (final review runs it)
-bin/              the npm CLI (npx cursordoctrine install / verify / uninstall)
-INSTALL.md        a ready-to-paste prompt that tells a Cursor agent to
-                  install the right folder and verify every hook
-assets/           the architecture diagram above
-```
 
-The two folders are functionally identical. Windows runs everything through `pwsh.exe`; Linux runs bash, which is what you want on a remote you reach over SSH (see your `~/.ssh/config` host — the hooks live on the remote's `$HOME`, not on your laptop).
+Restart Cursor after install — `hooks.json` is read at startup. `install` is idempotent; re-run to update. Entries you added to `~/.cursor/hooks.json` yourself are kept. `npx cursordoctrine uninstall` removes the pack the same way.
+
+No Node? Open `INSTALL.md`, paste it into a Cursor agent chat on the target machine, and let the agent copy files and run the checklist. Copy commands are in the same file if you prefer doing it by hand.
+
+Prerequisites: `git` everywhere; `pwsh` on Windows; `bash` plus `jq` or `python3` on Linux.
+
+The anti-slop skill (`skills/anti-slop/` — SKILL.md and the duplication scanner) installs to `~/.cursor/skills/anti-slop/`. The hook checklist (`~/.agents/hooks/anti-slop.md`, 13 items) is the canonical slop detector for per-edit advisories and final-review axis 4. Final review runs the scanner from the skill path first when it's there.
 
 ## The five flows
 
 | Flow | Event | What happens |
 |---|---|---|
-| Session | `sessionStart` | `inject-doctrine` reads the doctrine + user rules and emits them as `additional_context`. |
+| Session | `sessionStart` | `inject-doctrine` reads doctrine + user rules + declared-editing and emits them as `additional_context`. |
 | Every turn | `postToolUse` | Folds completed subagents' edit markers into this conversation's marker, then drains the conversation's pending feedback file into `additional_context`. One-shot, keyed by conversation id. |
 | Shell | `beforeShellExecution` | `permission-gate` checks the command against a deny list. Allow by default, deny by list, fail open. |
 | Edit | `afterFileEdit` + `stop` | `self-review-trigger` stashes the review prompt per edit; `minimal-edit-audit` (deprecated in 0.3.0), `semantic-density-audit`, and `anti-slop-audit` append advisories when thresholds trip (new deps / premature abstraction / redundant comments / **semantic opacity**: low-density identifiers like `DataManager`, `process()`, `utils.ts` / Tier 3 operational slop: retry-without-backoff, await-in-loop, telemetry spam); `final-review` fires one end-of-implementation pass. |
 | 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
-
-The fast path is npm (Node 18+):
+## Layout
 
-```bash
-npx cursordoctrine@latest install   # copies the hook pack into ~/.agents/hooks + ~/.cursor, merges hooks.json
-npx cursordoctrine verify           # smoke-tests every hook with fake payloads, no restart needed
+```
+windows/          PowerShell hooks (pwsh) — install on Windows machines
+  hooks.json      hook wiring for ~/.cursor/hooks.json
+  inject-doctrine.ps1, doctrine.md, USER-RULES.md, declared-editing.md
+  hooks/          the eight scripts + the three prompt files
+linux/            bash hooks — install on Linux machines and SSH remotes
+  hooks.json, inject-doctrine.sh, doctrine.md, USER-RULES.md, declared-editing.md
+  hooks/          same hooks, ported to bash (jq preferred, python3 fallback)
+skills/           Cursor agent skills shipped with the package
+  anti-slop/      SKILL.md + the duplication scanner (final review runs it)
+bin/              the npm CLI (npx cursordoctrine install / verify / uninstall)
+INSTALL.md        ready-to-paste prompt that tells a Cursor agent to
+                  install the right folder and verify every hook
 ```
 
-Then restart Cursor — `hooks.json` is read at startup. `install` is idempotent: re-run it to update, and entries you added to `~/.cursor/hooks.json` yourself are preserved. `npx cursordoctrine uninstall` removes the pack the same way.
-
-No Node? Open `INSTALL.md`, paste its contents into a Cursor agent chat on the target machine, and let the agent copy the files and run the verification checklist. Or do it by hand — the copy commands are in the same file.
-
-Prerequisites: `git` everywhere; `pwsh` on Windows; `bash` plus `jq` or `python3` on Linux.
-
-The anti-slop skill (`skills/anti-slop/` — SKILL.md and the duplication scanner) installs to `~/.cursor/skills/anti-slop/`. The hook checklist (`~/.agents/hooks/anti-slop.md`, 13 items) is the canonical slop detector for both per-edit advisories and final-review axis 4. The final review runs the scanner from the skill path first when available.
+Both folders do the same thing. Windows runs everything through `pwsh.exe`. Linux runs bash, which is what you want on a remote over SSH (check your `~/.ssh/config` host — hooks live on the remote's `$HOME`, not your laptop).
 
 ## Tuning and kill switches
 
@@ -70,6 +86,7 @@ All hooks fail open and always exit 0. Nothing here can block your session.
 | `HOOKS_ENFORCE=0` | on | turns off all advisory hooks at once |
 | `PERM_GATE_ENFORCE=0` | on | disables the permission gate |
 | `MINIMAL_EDITING_ENFORCE=0` | on | disables the over-edit advisory (deprecated in 0.3.0) |
+| `SCOPE_GATE_ENFORCE=0` | on | disables the declared-scope advisory (opt-in: only fires when `.scope.json` exists) |
 | `SEMANTIC_DENSITY_ENFORCE=0` | on | disables the semantic-opacity advisory |
 | `ANTI_SLOP_ENFORCE=0` | on | disables the slop advisory |
 | `FINAL_REVIEW_ENFORCE=0` | on | disables the final review pass |
@@ -79,9 +96,15 @@ All hooks fail open and always exit 0. Nothing here can block your session.
 
 ## Design notes
 
-- **State lives under `$HOME`**, in `~/.cursor/.hooks-pending/`, keyed by conversation id. No repo litter, and concurrent sessions can't drain each other's prompts. Stale state older than 7 days is swept on every stop.
-- **`afterFileEdit` output isn't consumed by Cursor**, so the edit hooks write to a pending file and `post-tool-use` re-emits it at the next tool boundary. That's the whole message bus.
+- **State lives under `$HOME`**, in `~/.cursor/.hooks-pending/`, keyed by conversation id. No repo litter. Concurrent sessions can't drain each other's prompts. Stale state older than 7 days gets swept on every stop.
+- **`afterFileEdit` output isn't consumed by Cursor**, so edit hooks write to a pending file and `post-tool-use` re-emits it at the next tool boundary. That's the whole message bus.
 - **One review per implementation.** The stop hook arms a per-conversation flag before emitting its follow-up, so a crash can't re-fire it and a long chat still gets a review after each implementation.
-- **Subagents are first-class.** `afterFileEdit` fires inside subagents keyed by the *subagent's* conversation id, the harness normalizes agent edits (incl. `StrReplace`) to tool type `Write`, and `postToolUse` never fires for the `Task` tool — all verified by payload capture. So the matchers cover `Write|StrReplace|EditNotebook` defensively, `subagentStop` reviews the subagent in its own context, and the parent folds orphaned subagent markers (found via the `subagents/` transcript directory) into its own at every tool boundary and at stop.
+- **Subagents are first-class.** `afterFileEdit` fires inside subagents keyed by the subagent's conversation id. The harness normalizes agent edits (incl. `StrReplace`) to tool type `Write`, and `postToolUse` never fires for the `Task` tool — verified by payload capture. Matchers cover `Write|StrReplace|EditNotebook` defensively. `subagentStop` reviews the subagent in its own context. The parent folds orphaned subagent markers (from the `subagents/` transcript directory) into its own at every tool boundary and at stop.
+
+Self-contained. No build. Open `hooks.json` and read it — that's the whole system in one file.
+
+Built with [Cursor](https://cursor.com).
+
+## License
 
-Self-contained. No build. Open `hooks.json` and read it — it's the whole system in one file.
+MIT. See [LICENSE](LICENSE).

package/bin/cli.mjs

@@ -374,6 +374,7 @@ Kill switches (environment variables, all hooks fail open)
   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
+  SCOPE_GATE_ENFORCE=0         declared-scope advisory off
   ANTI_SLOP_ENFORCE=0          slop advisory off
   FINAL_REVIEW_ENFORCE=0       final review off
   SUBAGENT_REVIEW_ENFORCE=0    in-subagent review off

package/linux/hooks/final-review.md

@@ -1,5 +1,5 @@
 FINAL REVIEW — you just finished an implementation. Before you treat it as done,
-audit EVERYTHING you changed this session across the five axes below and FIX what
+audit EVERYTHING you changed this session across the six 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.
 
@@ -64,4 +64,36 @@ 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.
+
+## 5. Wiring completeness
+For every user-visible behavior you added or changed (button, form submit, API
+call, route, state transition, scheduled job), trace its execution path end to
+end and confirm it reaches a REAL EFFECT (persist, mutate, call, render, notify).
+A dead end is slop even if the code is clean. Hunt for the vibe-coding failure
+mode where a layer EXISTS but is not WIRED:
+
+  - `handleSubmit()` that does not persist / does not call the API.
+  - An endpoint that no route or caller invokes.
+  - A DB write / table that nothing reads or writes.
+  - A component that renders but is never mounted / routed to.
+  - A hook / store / context that is declared but never consumed.
+  - A `TODO` / empty body / stubbed `console.log` standing in for the effect.
+
+The bar is: a senior can follow the path click -> handler -> call -> store ->
+render (or the equivalent slice) without hitting a gap. If a step is missing or
+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.

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 five axes:
-# intent, correctness, reliability, coverage, and anti-slop. When the agent finishes
+# ONE comprehensive end-of-implementation review across six axes:
+# intent, correctness, reliability, coverage, anti-slop, and wiring completeness. 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.
@@ -81,6 +81,12 @@ if [ -z "$body" ]; then
      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.
+  5. Wiring completeness - for every user-visible behavior you added/changed
+     (button, submit, API call, route, state transition), trace its execution
+     path to a REAL EFFECT (persist, mutate, call, render). A dead end is slop:
+     handleSubmit that does not persist, an endpoint no caller invokes, a store
+     never consumed, a stub/TODO/console.log standing in for the effect. Wire it
+     now or remove the dead half; mark later-stubs with TODO(wire):.
 Fix now, re-run the scan + tests, then stop. If an axis is clean, say so in one line.'
 fi
 body="$(expand_agent_paths "$body")"

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

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# scope-gate-audit.sh - afterFileEdit "declared scope" advisory (Cursor, Linux).
+#
+# Compuerta 1 of the anti-slop system: the declared-scope gate. When the agent
+# writes a .scope.json contract (intent + files[] + acceptance), this hook
+# checks every edited file against it. Editing OUTSIDE the declared set is the
+# textbook scope-creep / gold-plating signal. Advisory only (no preToolUse for
+# file edits on Cursor); the violation is flagged on the next turn.
+#
+# Opt-in: if .scope.json does not exist in the repo root, this hook is silent.
+# No contract = no gate (fallback to declared-editing ladder + final-review).
+#
+# Mechanism: resolve edited file -> repo-relative, run scope_match.py against
+# .scope.json's files[], append advisory to feedback-<cid>.txt on violation.
+#
+# Advisory only: never blocks, never persists state, ALWAYS exits 0.
+# Disable: HOOKS_ENFORCE=0  or  SCOPE_GATE_ENFORCE=0
+
+set +e
+. "$(dirname "$0")/hook-common.sh"
+
+[ "${HOOKS_ENFORCE:-}" = "0" ] && exit 0
+[ "${SCOPE_GATE_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
+
+# --- opt-in gate: no .scope.json = no gate ---------------------------------
+scope_file="$root/.scope.json"
+[ -f "$scope_file" ] || exit 0
+
+# --- resolve Python + run scope_match.py ---------------------------------
+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
+
+matcher="$HOME/.cursor/skills/anti-slop/scripts/scope_match.py"
+[ -f "$matcher" ] || exit 0   # skill not installed -> silent
+
+mout="$("$py" "$matcher" --path "$rel" --patterns-file "$scope_file" 2>/dev/null)"
+[ -n "$mout" ] || exit 0
+
+# --- parse the JSON result (reuse the Python we already resolved) ----------
+parse_result() {
+    "$py" - "$@" <<'PYEOF' 2>/dev/null
+import json, sys
+try:
+    p = json.loads(sys.stdin.read())
+except Exception:
+    sys.exit(1)
+if p.get("skipped"):
+    sys.exit(2)   # no valid contract -> fail-open
+if p.get("in_scope"):
+    sys.exit(3)   # in scope -> clean
+allow_growth = "1" if p.get("allow_growth") else "0"
+intent = p.get("intent", "")
+print(f"__AG__{allow_growth}")
+print(f"__INTENT__{intent}")
+sys.exit(0)
+PYEOF
+}
+
+parsed="$(printf '%s' "$mout" | parse_result)"
+rc=$?
+[ "$rc" -eq 0 ] || exit 0   # 2=skipped, 3=in-scope, 1=parse-fail -> all silent
+
+allow_growth="$(printf '%s\n' "$parsed" | grep '__AG__' | sed 's/__AG__//')"
+intent="$(printf '%s\n' "$parsed" | grep '__INTENT__' | sed 's/__INTENT__//')"
+
+# Read declared files for the message (best-effort)
+declared_files="$(printf '%s' "$scope_file" | "$py" -c "
+import json, sys
+try:
+    d = json.load(open(sys.argv[1]))
+    print(', '.join(d.get('files', [])))
+except Exception:
+    pass
+" "$scope_file" 2>/dev/null)"
+
+# --- compose advisory ------------------------------------------------------
+if [ "$allow_growth" = "1" ]; then
+    summary="Scope note - $rel is new vs your declared scope (growth allowed)"
+    body="  You touched a file outside your initial declared set. Since allow_growth is
+  true, this is not a violation, but justify it: add $rel to .scope.json or
+  explain why the scope grew."
+else
+    summary="[SCOPE VIOLATION] $rel is NOT in your declared scope"
+    body="  Your contract (.scope.json):
+    intent: $intent
+    files: $declared_files
+
+  You declared these files and touched one outside the set. Either:
+    1. Add $rel to .scope.json with a one-line justification, OR
+    2. Revert the change - it is out of scope for the declared intent.
+
+  Declared-editing: declare BEFORE you expand. Don't sneak edits past the gate."
+fi
+
+msg="${summary}
+
+${body}
+
+(Advisory; disable: SCOPE_GATE_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.json

@@ -27,6 +27,12 @@
         "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/scope-gate-audit.sh",
+        "timeout": 10,
+        "matcher": "^(Write|StrReplace|EditNotebook)$",
+        "_comment": "10s (Compuerta 1): declared-scope advisory. OPT-IN: only active when .scope.json exists in the repo root. The agent declares intent + files[] + acceptance; this hook checks every edit against the declared set via scope_match.py (exact, * glob, ** recursive, bare-dir). Out-of-scope edit = [SCOPE VIOLATION] advisory to pending. No .scope.json = silent (fallback to declared-editing ladder + final-review footprint check). Never blocks (Cursor has no preToolUse for file edits). Disable: HOOKS_ENFORCE=0 or SCOPE_GATE_ENFORCE=0."
+      },
       {
         "command": "bash ~/.agents/hooks/anti-slop-audit.sh",
         "timeout": 15,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursordoctrine",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Thin self-review hooks for Cursor — the model is the auditor. Intent-trace final review (Tier 0), unified 13-item anti-slop checklist, operational slop detection.",
   "bin": {
     "cursordoctrine": "bin/cli.mjs"

package/skills/anti-slop/SKILL.md

@@ -272,7 +272,11 @@ 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
 **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
+`semantic_density` bucket), the **scope-gate-audit hook**
+(`scope-gate-audit.ps1` / `.sh`, Compuerta 1 — opt-in declared-scope gate
+that flags edits outside `.scope.json`; shares `scope_match.py` with the
+final-review Step D closing gate), the **stop hook** (`final-review.ps1` / `.sh`,
+six-axis session review incl. intent trace and wiring completeness), and
+**declared-editing** (YAGNI ultra ladder injected at session start;
+supersedes the deprecated `minimal-editing` size gate). This skill is the
 active "delete it now" layer those only nudge toward.

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

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""scope_match.py - declared-scope glob matcher (shared helper).
+
+One job: given a repo-relative path and a list of declared-scope patterns
+(from .scope.json `files`), return whether the path is in scope. Shared
+between the per-edit scope-gate-audit hook (afterFileEdit) and final-review's
+declared-scope check (Step C), so the two never disagree on what counts as
+"in scope".
+
+Pattern support:
+  - exact path:   src/components/LoginButton.tsx
+  - glob *:       src/styles/*.css           (single segment, no /)
+  - glob **:      src/**/test_*.py           (recursive across dirs)
+  - bare dir:     src/components             (matches everything under it)
+
+Stdlib only; Python 3.9+. REPORTS only - never edits.
+
+CLI:
+  scope_match.py --path src/auth/session.ts --patterns-file .scope.json
+  -> prints JSON {"in_scope": false, "matched_by": null} and exits 0
+  -> if .scope.json is missing or unparseable, prints {"in_scope": true,
+     "skipped": "no .scope.json"} (fail-open: no contract = no gate)
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+
+# Sentinel chars for anchoring; built once, used in the regex below.
+_ANCHOR_START = "^"
+_ANCHOR_END = "$"
+
+
+def _pattern_to_regex(pattern: str) -> re.Pattern:
+    """Convert a glob pattern to a compiled regex matching the WHOLE path.
+
+    Standard glob semantics (NOT fnmatch's):
+      **  matches any chars INCLUDING / (recursive)
+      *   matches any chars EXCEPT / (single segment)
+      ?   matches a single char EXCEPT /
+      A bare directory pattern (basename has no dot, e.g. 'src/components')
+      matches the dir AND everything beneath it.
+    """
+    bare = pattern.rstrip("/")
+    base = os.path.basename(bare)
+    is_dir = ("." not in base)
+
+    out: list[str] = []
+    i = 0
+    while i < len(pattern):
+        c = pattern[i]
+        if c == "*" and i + 1 < len(pattern) and pattern[i + 1] == "*":
+            out.append(".*")           # ** crosses /
+            i += 2
+        elif c == "*":
+            out.append("[^/]*")        # * stays within a segment
+            i += 1
+        elif c == "?":
+            out.append("[^/]")
+            i += 1
+        else:
+            out.append(re.escape(c))
+            i += 1
+    body = "".join(out)
+
+    if is_dir:
+        body = body + "(/.*)?"
+
+    return re.compile(_ANCHOR_START + body + _ANCHOR_END)
+
+
+def in_scope(path: str, patterns: list) -> tuple:
+    """Return (matched_bool, matched_by_pattern_or_None)."""
+    norm = path.replace("\\", "/").lstrip("/")
+    for p in patterns:
+        p = p.strip().replace("\\", "/")
+        if not p:
+            continue
+        if _pattern_to_regex(p).match(norm):
+            return True, p
+    return False, None
+
+
+def load_scope(scope_path: str):
+    """Load and validate .scope.json. Returns the dict, or None if missing/
+    unparseable (fail-open: no contract = no gate fires)."""
+    if not os.path.isfile(scope_path):
+        return None
+    try:
+        with open(scope_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        if not isinstance(data, dict):
+            return None
+        if not isinstance(data.get("files", []), list):
+            return None
+        return data
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(
+        description="Declared-scope glob matcher (shared helper).")
+    ap.add_argument("--path", required=True,
+                    help="repo-relative path to check")
+    ap.add_argument("--patterns-file",
+                    help="path to .scope.json (default: .scope.json in cwd)")
+    ap.add_argument("--patterns",
+                    help="comma-separated patterns (overrides --patterns-file)")
+    args = ap.parse_args()
+
+    if args.patterns:
+        patterns = [p.strip() for p in args.patterns.split(",") if p.strip()]
+        matched, by = in_scope(args.path, patterns)
+        result = {"in_scope": matched, "matched_by": by}
+    else:
+        scope_path = args.patterns_file or os.path.join(os.getcwd(), ".scope.json")
+        scope = load_scope(scope_path)
+        if scope is None:
+            print(json.dumps({"in_scope": True, "skipped": "no valid .scope.json"}))
+            return 0
+        patterns = [str(f) for f in scope.get("files", [])]
+        matched, by = in_scope(args.path, patterns)
+        result = {
+            "in_scope": matched,
+            "matched_by": by,
+            "allow_growth": bool(scope.get("allow_growth", False)),
+            "intent": scope.get("intent", ""),
+        }
+
+    print(json.dumps(result))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/windows/hooks/final-review.md

@@ -1,5 +1,5 @@
 FINAL REVIEW — you just finished an implementation. Before you treat it as done,
-audit EVERYTHING you changed this session across the five axes below and FIX what
+audit EVERYTHING you changed this session across the six 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.
 
@@ -64,4 +64,36 @@ 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.
+
+## 5. Wiring completeness
+For every user-visible behavior you added or changed (button, form submit, API
+call, route, state transition, scheduled job), trace its execution path end to
+end and confirm it reaches a REAL EFFECT (persist, mutate, call, render, notify).
+A dead end is slop even if the code is clean. Hunt for the vibe-coding failure
+mode where a layer EXISTS but is not WIRED:
+
+  - `handleSubmit()` that does not persist / does not call the API.
+  - An endpoint that no route or caller invokes.
+  - A DB write / table that nothing reads or writes.
+  - A component that renders but is never mounted / routed to.
+  - A hook / store / context that is declared but never consumed.
+  - A `TODO` / empty body / stubbed `console.log` standing in for the effect.
+
+The bar is: a senior can follow the path click -> handler -> call -> store ->
+render (or the equivalent slice) without hitting a gap. If a step is missing or
+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.

package/windows/hooks/final-review.ps1

@@ -1,7 +1,7 @@
 # final-review.ps1 - stop hook (Cursor).
 #
-# ONE comprehensive end-of-implementation review across five axes:
-# intent, correctness, reliability, coverage, and anti-slop. When the agent finishes an
+# ONE comprehensive end-of-implementation review across six axes:
+# intent, correctness, reliability, coverage, anti-slop, and wiring completeness. 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
@@ -91,6 +91,12 @@ FINAL REVIEW - audit everything you changed this session and FIX what fails
      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.
+  5. Wiring completeness - for every user-visible behavior you added/changed
+     (button, submit, API call, route, state transition), trace its execution
+     path to a REAL EFFECT (persist, mutate, call, render). A dead end is slop:
+     handleSubmit that does not persist, an endpoint no caller invokes, a store
+     never consumed, a stub/TODO/console.log standing in for the effect. Wire it
+     now or remove the dead half; mark later-stubs with TODO(wire):.
 Fix now, re-run the scan + tests, then stop. If an axis is clean, say so in one line.
 '@
 }

package/windows/hooks/scope-gate-audit.ps1

@@ -0,0 +1,125 @@
+# scope-gate-audit.ps1 - afterFileEdit "declared scope" advisory (Cursor).
+#
+# Compuerta 1 of the anti-slop system: the declared-scope gate. When the agent
+# writes a .scope.json contract (intent + files[] + acceptance), this hook
+# checks every edited file against it. Editing OUTSIDE the declared set is the
+# textbook scope-creep / gold-plating signal - the agent is doing work it did
+# not declare. Advisory only on Cursor (no preToolUse for file edits), but the
+# violation is flagged on the next turn and the model must justify or revert.
+#
+# Opt-in: if .scope.json does not exist in the repo root, this hook is silent.
+# Declared-editing discipline is something the agent opts into by writing the
+# contract. No contract = no gate (fallback to declared-editing ladder + the
+# footprint check in final-review).
+#
+# Mechanism: resolve edited file -> repo-relative, run scope_match.py against
+# .scope.json's files[], append advisory to feedback-<cid>.txt on violation.
+# Identical pattern to semantic-density-audit and anti-slop-audit.
+#
+# Advisory only: never blocks, never persists state, ALWAYS exits 0.
+# Disable: HOOKS_ENFORCE=0  or  SCOPE_GATE_ENFORCE=0
+
+$ErrorActionPreference = 'SilentlyContinue'
+. "$PSScriptRoot\hook-common.ps1"
+
+if ($env:HOOKS_ENFORCE -eq '0' -or $env:SCOPE_GATE_ENFORCE -eq '0') { exit 0 }
+
+$obj = Read-HookStdinJson
+if (-not $obj) { exit 0 }
+
+# audit root: project from JSON (cwd, then workspace_roots), else CURSOR_PROJECT_DIR / HOME
+$root = ''
+$cands = @()
+if ($obj.PSObject.Properties['cwd'] -and $obj.cwd) { $cands += [string]$obj.cwd }
+if ($obj.PSObject.Properties['workspace_roots']) { foreach ($w in $obj.workspace_roots) { $cands += [string]$w } }
+foreach ($c in $cands) { $f = ConvertTo-FwdPath $c; if ($f -and (Test-Path -LiteralPath $f)) { $root = $f.TrimEnd('/'); break } }
+if (-not $root) { $root = (& { if ($env:CURSOR_PROJECT_DIR) { $env:CURSOR_PROJECT_DIR } else { $HOME } }).Replace('\', '/').TrimEnd('/') }
+
+# edited file -> repo-relative forward-slash path
+$fp = ''
+foreach ($k in 'file_path', 'path', 'filename', 'absolute_path', 'abs_path') {
+    if ($obj.PSObject.Properties[$k] -and $obj.$k) { $fp = [string]$obj.$k; break }
+}
+if (-not $fp) { exit 0 }
+$rel = ConvertTo-FwdPath $fp
+if ($rel.StartsWith($root + '/', [System.StringComparison] 'OrdinalIgnoreCase')) { $rel = $rel.Substring($root.Length + 1) }
+if (Test-IsCursorConfigPath $fp) { exit 0 }
+if (Test-IsCursorConfigPath $rel) { exit 0 }
+
+# --- opt-in gate: no .scope.json = no gate ---------------------------------
+$scopeFile = "$root/.scope.json"
+if (-not (Test-Path -LiteralPath $scopeFile)) { exit 0 }
+
+# --- resolve Python + run scope_match.py -----------------------------------
+$py = Get-Command python, python3, py -ErrorAction SilentlyContinue | Select-Object -First 1
+if (-not $py) { exit 0 }   # no Python -> fail open
+
+$matcher = Join-Path $HOME '.cursor\skills\anti-slop\scripts\scope_match.py'
+if (-not (Test-Path $matcher)) { exit 0 }   # skill not installed -> silent
+
+$mout = & $py.Source $matcher --path $rel --patterns-file $scopeFile 2>$null
+if (-not $mout) { exit 0 }
+
+$payload = $null
+try { $payload = ($mout -join "`n") | ConvertFrom-Json } catch { }
+if (-not $payload) { exit 0 }
+
+# fail-open: if scope_match reported skipped (no valid contract), stay silent
+$hasSkipped = $false
+try { if ($payload.PSObject.Properties['skipped']) { $hasSkipped = $true } } catch { }
+if ($hasSkipped) { exit 0 }
+
+$inScope = $false
+try { $inScope = [bool]$payload.in_scope } catch { }
+if ($inScope) { exit 0 }
+
+# --- violation: compose advisory -------------------------------------------
+$allowGrowth = $false
+if ($payload.PSObject.Properties['allow_growth'] -and $payload.allow_growth) { $allowGrowth = $true }
+$intent = ''
+if ($payload.PSObject.Properties['intent']) { $intent = [string]$payload.intent }
+
+# Read the declared files list for the message (best-effort; skip on failure)
+$declaredFiles = ''
+try {
+    $scopeJson = Get-Content -LiteralPath $scopeFile -Raw | ConvertFrom-Json
+    if ($scopeJson.files) { $declaredFiles = ($scopeJson.files -join ', ') }
+} catch { }
+
+if ($allowGrowth) {
+    # Growth is allowed: informational, not a violation
+    $summary = "Scope note - $rel is new vs your declared scope (growth allowed)"
+    $body = @"
+  You touched a file outside your initial declared set. Since allow_growth is
+  true, this is not a violation, but justify it: add $rel to .scope.json or
+  explain why the scope grew.
+"@
+} else {
+    # Hard violation: edited outside the declared contract
+    $summary = "[SCOPE VIOLATION] $rel is NOT in your declared scope"
+    $body = @"
+  Your contract (.scope.json):
+    intent: $intent
+    files: $declaredFiles
+
+  You declared these files and touched one outside the set. Either:
+    1. Add $rel to .scope.json with a one-line justification, OR
+    2. Revert the change - it is out of scope for the declared intent.
+
+  Declared-editing: declare BEFORE you expand. Don't sneak edits past the gate.
+"@
+}
+
+$msg = "$summary`n`n$body`n`n(Advisory; disable: SCOPE_GATE_ENFORCE=0)"
+
+# --- append to the shared pending file --------------------------------------
+$cid = Get-SafeConversationId $obj
+$pending = Join-Path (Get-HooksPendingDir) "feedback-$cid.txt"
+try {
+    New-Item -ItemType Directory -Path (Split-Path $pending) -Force | Out-Null
+    $prefix = ''
+    if ((Test-Path $pending) -and ((Get-Item $pending).Length -gt 0)) { $prefix = "`n`n---`n`n" }
+    Add-Content -Path $pending -Value ($prefix + $msg) -NoNewline
+} catch { }
+
+exit 0

package/windows/hooks.json

@@ -27,6 +27,12 @@
         "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": "pwsh.exe -NoProfile -File ~/.agents/hooks/scope-gate-audit.ps1",
+        "timeout": 10,
+        "matcher": "^(Write|StrReplace|EditNotebook)$",
+        "_comment": "10s (Compuerta 1): declared-scope advisory. OPT-IN: only active when .scope.json exists in the repo root. The agent declares intent + files[] + acceptance; this hook checks every edit against the declared set via scope_match.py (exact, * glob, ** recursive, bare-dir). Out-of-scope edit = [SCOPE VIOLATION] advisory to pending. No .scope.json = silent (fallback to declared-editing ladder + final-review footprint check). Never blocks (Cursor has no preToolUse for file edits). Disable: HOOKS_ENFORCE=0 or SCOPE_GATE_ENFORCE=0."
+      },
       {
         "command": "pwsh.exe -NoProfile -File ~/.agents/hooks/anti-slop-audit.ps1",
         "timeout": 15,