cursordoctrine 0.3.2 → 0.4.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` (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

@@ -86,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 |

package/bin/cli.mjs

@@ -40,7 +40,7 @@ const pendingDir = join(cursorDst, '.hooks-pending');
 const hooksJsonDst = join(cursorDst, 'hooks.json');
 
 const injectName = platform === 'windows' ? 'inject-doctrine.ps1' : 'inject-doctrine.sh';
-const doctrineFiles = [injectName, 'doctrine.md', 'USER-RULES.md', 'declared-editing.md'];
+const doctrineFiles = [injectName, 'doctrine.md', 'USER-RULES.md', 'declared-editing.md', 'pre-compile.md'];
 
 function payloadHookFiles() {
   return readdirSync(join(payload, 'hooks'));
@@ -263,6 +263,22 @@ function verify() {
     return true;
   });
 
+  check('anchor-set nudge fires on first edit, then goes quiet', () => {
+    // First edit of the implementation -> the pre-compile nudge stashes its
+    // advisory in the pending feedback bus and arms the one-shot flag.
+    const first = runHook(hook('anchor-set-nudge'), { conversation_id: 'npxv3', file_path: join(HOME, 'x.py') });
+    if (!first.includes('additional_context') || !first.includes('PRE-COMPILE NUDGE')) {
+      // anchor-set-nudge appends to feedback-<cid>.txt (the shared bus) rather
+      // than emitting JSON directly; drain it the same way post-tool-use does.
+      const drained = runHook(hook('post-tool-use'), { conversation_id: 'npxv3' });
+      if (!drained.includes('PRE-COMPILE NUDGE')) return { ok: false, detail: 'nudge did not reach the feedback bus on first edit' };
+    }
+    // Second edit -> flag is armed, nudge must stay silent.
+    const second = runHook(hook('anchor-set-nudge'), { conversation_id: 'npxv3', file_path: join(HOME, 'y.py') });
+    if (second.includes('PRE-COMPILE NUDGE')) return { ok: false, detail: 'nudge re-fired on second edit (flag not gating)' };
+    return true;
+  });
+
   check('doctrine injection emits additional_context', () =>
     runHook(join(cursorDst, injectName), {}).includes('additional_context'));
 
@@ -374,6 +390,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/anchor-set-nudge.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# anchor-set-nudge.sh - afterFileEdit "pre-compile" nudge (Cursor, Linux).
+#
+# Proactive counterpart to the reactive audits. On the FIRST file edit of an
+# implementation (per conversation), remind the agent to compile its Anchor Set
+# (pre-compile.md) and write .scope.json BEFORE piling on more code. The
+# reactive stack (self-review, anti-slop, final-review) only fires AFTER code
+# exists; this nudge catches intent dilution at token ~50, not at the ~5000 of
+# the stop-hook axis 0. A clean final review of the wrong feature is still the
+# wrong feature - the Anchor Set exists so the right feature is on the rails
+# from the first edit.
+#
+# One-shot PER IMPLEMENTATION, not per session: gated by an
+# anchor-declared-<cid>.flag in the pending dir. That flag is cleared by
+# final-review.sh / subagent-stop-review.sh at the SAME per-implementation
+# boundary where they clear session-edits-<cid>.txt and reviewed-<cid>.flag
+# (the stop after a review pass). So a long conversation with N implementations
+# gets N nudges, not one - every new body of work re-earns the reminder.
+#
+# Advisory only: never blocks, never reads the diff, ALWAYS exits 0. Appends to
+# the shared feedback-<cid>.txt bus; post-tool-use.sh delivers it next turn.
+# Disable: HOOKS_ENFORCE=0  or  ANCHOR_NUDGE_ENFORCE=0
+
+set +e
+. "$(dirname "$0")/hook-common.sh"
+
+[ "${HOOKS_ENFORCE:-}" = "0" ] && exit 0
+[ "${ANCHOR_NUDGE_ENFORCE:-}" = "0" ] && exit 0
+
+input="$(read_hook_stdin)"
+[ -n "$input" ] || exit 0
+
+file_path=""
+for k in file_path path filePath; do
+    file_path="$(json_get "$input" "$k")"
+    [ -n "$file_path" ] && break
+done
+[ -n "$file_path" ] || exit 0
+is_cursor_config_path "$file_path" && exit 0
+
+cid="$(safe_conversation_id "$input")"
+pending_dir="$(hooks_pending_dir)"
+flag="$pending_dir/anchor-declared-$cid.flag"
+
+# Already nudged this implementation -> stay quiet. The flag is cleared at the
+# per-implementation boundary in final-review.sh / subagent-stop-review.sh.
+[ -f "$flag" ] && exit 0
+
+msg="PRE-COMPILE NUDGE - first edit of this implementation: $file_path
+
+Before you keep going, did you compile your Anchor Set (pre-compile.md)?
+  1. OBJECTIVE   - one operational sentence. What is strictly necessary.
+  2. CONSTRAINTS - local negations (what you will NOT do).
+  3. SCOPE       - files to touch, files untouchable.
+  4. SUCCESS     - the one deterministic check that decides done.
+
+If you have not already, write it to .scope.json now (intent / files /
+acceptance / allow_growth). The scope-gate audits every edit against files[],
+and final-review axis 0 traces every diff hunk back to intent. An Anchor Set
+that lives only in your head is not an Anchor Set - the gate cannot audit it.
+
+Skip this for trivial one-liners (typo, literal). Otherwise: compile, then code."
+
+# Append to the shared pending file (same bus as the other advisories).
+pending="$pending_dir/feedback-$cid.txt"
+mkdir -p "$pending_dir" 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
+
+# Arm the one-shot brake BEFORE returning, so a crash after the append can't
+# re-nudge on the next edit. Mirrors the arming order in final-review.sh.
+touch "$flag" 2>/dev/null
+
+exit 0

package/linux/hooks/final-review.md

@@ -64,6 +64,17 @@ 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

package/linux/hooks/final-review.sh

@@ -36,13 +36,16 @@ cid="$(safe_conversation_id "$input")"
 pending_dir="$(hooks_pending_dir)"
 marker="$pending_dir/session-edits-$cid.txt"
 flag="$pending_dir/reviewed-$cid.flag"
+anchor_flag="$pending_dir/anchor-declared-$cid.flag"
 
 # Sweep state from sessions that died before their stop hook ran.
 find "$pending_dir" -maxdepth 1 -type f -mtime +7 -delete 2>/dev/null
 
 # One-shot brake: the previous stop for this conversation emitted the review.
+# Also clear anchor-declared-<cid>.flag so the pre-compile nudge re-fires for
+# the NEXT implementation (one nudge per body of work, not per session).
 if [ -f "$flag" ]; then
-    rm -f "$flag" "$marker" 2>/dev/null
+    rm -f "$flag" "$marker" "$anchor_flag" 2>/dev/null
     emit_none
 fi
 
@@ -91,6 +94,14 @@ Fix now, re-run the scan + tests, then stop. If an axis is clean, say so in one
 fi
 body="$(expand_agent_paths "$body")"
 
+# Regla R1 (re-entry): if this review pass is a re-audit after a failed gate or
+# axis, suppress History Propagation - the model must NOT build on its own prior
+# wrong diff. Reset its prior to the Anchor Set, not to its previous attempt.
+reentry_line="
+
+RE-ENTRY RULE (Regla R1): if a gate or axis failed, forget the approach that produced it. Re-read your ORIGINAL REQUEST above and your Anchor Set (.scope.json, if you wrote one). Fix ONLY what is failing. Do not refactor in this pass - that is History Propagation, the exact failure mode the Anchor Set exists to prevent.
+"
+
 file_list=""
 while IFS= read -r p; do
     [ -n "$p" ] || continue
@@ -127,7 +138,7 @@ msg="FINAL REVIEW (end of implementation) - intent, correctness, reliability, co
 ${surface_block}${intent_block}Files you changed this session:
 $file_list
 
-$body"
+${body}${reentry_line}"
 
 # Arm the one-shot brake BEFORE emitting, so a crash after emit can't re-fire.
 touch "$flag" 2>/dev/null

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

@@ -0,0 +1,155 @@
+#!/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", "")
+acceptance = p.get("acceptance", "")
+print(f"__AG__{allow_growth}")
+print(f"__INTENT__{intent}")
+print(f"__ACCEPT__{acceptance}")
+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__//')"
+acceptance="$(printf '%s\n' "$parsed" | grep '__ACCEPT__' | sed 's/__ACCEPT__//')"
+
+# 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 ------------------------------------------------------
+# acceptance line: only quote it when the agent declared one. A blank acceptance
+# means the Anchor Set was incomplete - surface that gap, since the whole point
+# of the pre-compile phase is to name the deterministic success check.
+if [ -n "$acceptance" ]; then
+    acceptance_line="$acceptance"
+else
+    acceptance_line="(not declared - your Anchor Set is missing the EXITO/acceptance field)"
+fi
+
+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.
+
+  Your success contract (acceptance): $acceptance_line
+  Does growing into $rel still serve that?"
+else
+    summary="[SCOPE VIOLATION] $rel is NOT in your declared scope"
+    body="  Your contract (.scope.json):
+    intent: $intent
+    files: $declared_files
+    acceptance: $acceptance_line
+
+  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/subagent-stop-review.sh

@@ -44,10 +44,13 @@ cid="$(safe_conversation_id "$input")"
 pending_dir="$(hooks_pending_dir)"
 marker="$pending_dir/session-edits-$cid.txt"
 flag="$pending_dir/reviewed-$cid.flag"
+anchor_flag="$pending_dir/anchor-declared-$cid.flag"
 
 # One-shot brake: the previous subagentStop for this id emitted the review.
+# Also clear anchor-declared-<cid>.flag so the pre-compile nudge re-fires for
+# the next subagent implementation (one nudge per body of work).
 if [ -f "$flag" ]; then
-    rm -f "$flag" "$marker" 2>/dev/null
+    rm -f "$flag" "$marker" "$anchor_flag" 2>/dev/null
     emit_none
 fi
 
@@ -80,6 +83,14 @@ If an axis is clean, say so in one line. Then stop.'
 fi
 body="$(expand_agent_paths "$body")"
 
+# Regla R1 (re-entry): same suppression as final-review.sh. A subagent that
+# failed an axis must not build on its own prior wrong diff - reset its prior
+# to the Anchor Set, not to its previous attempt.
+reentry_line="
+
+RE-ENTRY RULE (Regla R1): if an axis failed, forget the approach that produced it. Re-read your original task and your Anchor Set (.scope.json, if you wrote one). Fix ONLY what is failing. Do not refactor in this pass.
+"
+
 file_list=""
 while IFS= read -r p; do
     [ -n "$p" ] || continue
@@ -94,7 +105,7 @@ msg="SUBAGENT FINAL REVIEW - you just finished delegated implementation work. Be
 Files you changed this run:
 $file_list
 
-$body"
+${body}${reentry_line}"
 
 # Arm the one-shot brake BEFORE emitting, so a crash after emit can't re-fire.
 touch "$flag" 2>/dev/null

package/linux/hooks.json

@@ -27,11 +27,23 @@
         "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,
         "matcher": "^(Write|StrReplace|EditNotebook)$",
         "_comment": "15s: AI-slop advisory, companion to minimal-edit-audit. git diff flags new deps / premature abstractions (Factory/Repository/Mediator/CQRS/DDD) / redundant comments, and injects the anti-slop.md self-review checklist on substantial edits (>= ANTI_SLOP_CHECKLIST_LINES, default 40). Appends to the conversation's pending file; never blocks. Disable: HOOKS_ENFORCE=0 or ANTI_SLOP_ENFORCE=0."
+      },
+      {
+        "command": "bash ~/.agents/hooks/anchor-set-nudge.sh",
+        "timeout": 5,
+        "matcher": "^(Write|StrReplace|EditNotebook)$",
+        "_comment": "5s: PROACTIVE pre-compile nudge. On the FIRST edit of each implementation (per conversation), remind the agent to compile its Anchor Set (pre-compile.md) into .scope.json BEFORE piling on more code. The reactive audits (self-review / anti-slop / final-review axis 0) only fire after code exists; this catches intent dilution at token ~50 instead of ~5000. One-shot per implementation: gated by anchor-declared-<cid>.flag, which final-review.sh / subagent-stop-review.sh clear at the same per-implementation boundary as reviewed-<cid>.flag. Advisory only; never blocks. Disable: HOOKS_ENFORCE=0 or ANCHOR_NUDGE_ENFORCE=0."
       }
     ],
     "postToolUse": [

package/linux/inject-doctrine.sh

@@ -16,7 +16,7 @@ set +e
 cat >/dev/null
 
 context=""
-for p in "$HOME/.cursor/doctrine.md" "$HOME/.cursor/USER-RULES.md" "$HOME/.cursor/declared-editing.md"; do
+for p in "$HOME/.cursor/doctrine.md" "$HOME/.cursor/USER-RULES.md" "$HOME/.cursor/declared-editing.md" "$HOME/.cursor/pre-compile.md"; do
     if [ -f "$p" ]; then
         part="$(cat "$p")"
         if [ -n "$context" ]; then context="$context

package/linux/pre-compile.md

@@ -0,0 +1,72 @@
+# Pre-compile — Thin Intent Compilation
+
+ACTIVE EVERY IMPLEMENTATION TURN. Before writing or modifying a single line of
+code, emit your Anchor Set. Compiling intent first is what stops the dilution
+that no later axis can fully undo — a clean final review of the wrong feature
+is still the wrong feature.
+
+This is the proactive phase. The anti-slop checklist, the self-review trigger
+and the final review are reactive — they audit after the fact. You compile the
+intent BEFORE the first token of code so they have the right thing to audit.
+
+## The Anchor Set
+
+Answer these four, terse, in your first response. One phrase each, not prose:
+
+1. OBJECTIVE — one operational sentence. What is *strictly* necessary. Not
+   "improve X" — "make X return Y when Z".
+2. CONSTRAINTS (local negations) — what you will NOT do. "NO schema migration.
+   NO new dependency. NO refactor of the surrounding function." Negations bind
+   harder than the objective: a constraint that the task contradicts is a bug
+   in your reading of the task, and you ask before you override it.
+3. SCOPE —
+   - FILES TO TOUCH: exact list, derived from the objective, nothing speculative.
+   - FILES UNTOUCHABLE: anything the system marked off-limits (.cursor state,
+     lockfiles you weren't asked to touch, files outside the request's blast
+     radius).
+4. DETERMINISTIC SUCCESS — the one command, test, or observable check that
+   will decide whether this is done. "Tests pass" is not deterministic; the
+   specific failing test going green is. If you cannot name one, you do not
+   yet understand the task — ask.
+
+## Materialize it: .scope.json
+
+Write the Anchor Set to `.scope.json` in the repo root before editing source.
+This is the machine-checkable form — the scope-gate hook audits every edit
+against `files[]`, and the final-review axis 0 traces every diff hunk back to
+`intent`. An Anchor Set that lives only in your head is not an Anchor Set.
+
+```json
+{
+  "intent": "<OBJECTIVE>",
+  "files": ["<FILES TO TOUCH, repo-relative, glob-friendly>"],
+  "acceptance": "<DETERMINISTIC SUCCESS>",
+  "allow_growth": false
+}
+```
+
+`allow_growth: false` is the default — the gate fires on any edit outside
+`files[]`. Set it true only if you expect the work to discover new files
+(a refactor, a migration) and you will justify each one as it appears.
+
+No need to write `.scope.json` for trivial one-liners (a typo, a literal).
+The declared-editing ladder's rung 1 ("does this need to exist?") governs when
+the Anchor Set itself is overkill. When in doubt, write it.
+
+## Regla R3 — Authority
+
+If, during execution, you read logs or code that contradict these anchors,
+**the anchors win.** Prior history in this session is auditor material, not
+authority. An earlier wrong assumption of yours does not override the Anchor
+Set you declared at the start.
+
+## Regla R1 — On re-entry (when the loop hands you back a failure)
+
+If the harness returns a gate failure or a failed axis: forget the approach
+that produced it. Re-read your OBJECTIVE and your Anchor Set, not your prior
+diff. Fix ONLY what is failing. Do not refactor in the same pass — that is
+History Propagation, the failure mode the Anchor Set exists to prevent.
+
+---
+
+End of pre-compile. Now emit the Anchor Set, then do the work.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cursordoctrine",
-  "version": "0.3.2",
-  "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.",
+  "version": "0.4.0",
+  "description": "Thin self-review hooks for Cursor — the model is the auditor. Pre-compile Anchor Set phase (proactive intent compilation), 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.