cursordoctrine 0.3.2 → 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

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

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

@@ -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/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.2",
+  "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

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