cursordoctrine 0.5.3 → 0.5.5

package/bin/cli.mjs

@@ -334,6 +334,25 @@ function verify() {
         JSON.stringify({ role: 'user', message: { content: `<user_query>${q}</user_query>` } }) + '\n',
         'utf8');
 
+    // --- Case 0: no .scope.json + NO transcript -> WRITE scaffold anyway -------
+    // This is the 0.5.3 regression: creation was gated on $hasQuery, so when
+    // Cursor didn't surface transcript_path in the first postToolUse fire, the
+    // scope never appeared. Now creation is unconditional on a real root.
+    runHook(hook('intent-anchor'), { conversation_id: anchorCid, cwd: repoDir });
+    let d0 = drainedOf(anchorCid);
+    if (!existsSync(scopePath)) {
+      cleanup(); return { ok: false, detail: 'scaffold NOT created without transcript (0.5.3 regression)' };
+    }
+    let scope0;
+    try { scope0 = JSON.parse(readFileSync(scopePath, 'utf8')); }
+    catch { cleanup(); return { ok: false, detail: '.scope.json (no-transcript) is not valid JSON' }; }
+    if (!scope0.intent || !scope0.intent.includes('TODO')) {
+      cleanup(); return { ok: false, detail: `no-transcript scaffold should have intent <TODO>, got: ${scope0.intent}` };
+    }
+    // Clear the latch + scope so Case A starts fresh (with a real query this time).
+    runHook(hook('final-review'), { conversation_id: anchorCid, status: 'completed' });
+    cleanup();
+
     // --- Case A: no .scope.json + prompt q1 -> WRITE scaffold with q1 as intent -
     writeTranscript(q1);
     runHook(hook('intent-anchor'), { conversation_id: anchorCid, cwd: repoDir, transcript_path: transcriptPath });

package/linux/hooks/final-review.md

@@ -122,5 +122,18 @@ Determinism / purity:
   - In-place mutation of shared state (arr.push, obj.prop =) when a caller holds
     a reference -> return new structures ([...arr, x], .map/.filter).
 
+Logic & structure:
+  - Arrow code: >2 levels of nested if/for -> flatten with guard clauses
+    (early returns). Code reads top-to-bottom, no deep indent.
+  - Switch/if-else bloat: a switch or 5+ if/else branches -> Map/dispatch
+    (Record<State, fn>) or the Command pattern.
+  - Mixed abstraction (SLAP): a function mixing DB calls + string validation +
+    date formatting -> one level of abstraction per function; extract helpers.
+  - Primitive obsession: a primitive with business rules (email, userId, chainId)
+    passed as a bare string/number across functions -> a named type/value object.
+  - Imperative transforms: a `for` loop building an array when the language has
+    .map/.filter/.reduce -> use the declarative form; reserve `for` for cases
+    map/reduce cannot express.
+
 You do NOT need to run a tool for these — read the diff and apply the named fix.
 If none apply, say so in one line.

package/linux/hooks/intent-anchor.sh

@@ -18,11 +18,13 @@
 #   2. AUTO-CREATE / REGENERATE .scope.json: when the current <user_query>
 #      differs from the contract on disk (no contract yet, OR _intent_hash
 #      mismatch), the hook WRITES a scaffold to the REPO ROOT: intent locked
-#      from the prompt, files/acceptance as TODO placeholders the agent
-#      refines. This is the user-requested behavior: every new prompt ->
-#      a fresh .scope.json the agent works from. Fixed vs the broken 0.4.4
-#      build: never writes to $HOME (bails if no real root resolves -> no
-#      ghost files), and regenerates on prompt CHANGE not just on absence.
+#      from the prompt, files as an EMPTY array (scope-gate-audit.sh fills it
+#      mechanically as the agent edits - the agent never maintains files[] by
+#      hand), acceptance as a TODO the agent sets. This is the user-requested
+#      behavior: every new prompt -> a fresh .scope.json the agent works from.
+#      Fixed vs the broken 0.4.4 build: never writes to $HOME (bails if no real
+#      root resolves -> no ghost files), regenerates on prompt CHANGE not just
+#      on absence.
 #   3. RE-INJECT on same-prompt turns: when the query is unchanged (contract
 #      already current), the hook re-injects the existing contract into the
 #      feedback bus so it stays in the model's attentional focus each turn.
@@ -56,6 +58,16 @@ pending_dir="$(hooks_pending_dir)"
 latch="$pending_dir/intent-injected-$cid.flag"
 hash_file="$pending_dir/last-query-$cid.hash"
 
+# Stale-latch defense: if a previous session died mid-turn without hitting
+# stop (Cursor crash, force-quit), the latch can persist and silence this hook
+# for the whole next session -> scope never gets created. If the latch is older
+# than 2 hours, treat it as orphaned and clear it. Normal clears happen at
+# every stop (final-review.sh); this is the backstop for abnormal terminations.
+if [ -f "$latch" ]; then
+    age_hours=$(( ($(date +%s) - $(stat -c %Y "$latch" 2>/dev/null || stat -f %m "$latch" 2>/dev/null || echo 0)) / 3600 ))
+    [ "$age_hours" -ge 2 ] && rm -f "$latch" 2>/dev/null
+fi
+
 # Already injected this turn -> quiet. Latch cleared at every stop.
 [ -f "$latch" ] && exit 0
 
@@ -131,34 +143,42 @@ EOF
     fi
 fi
 
-# --- auto-create / regenerate .scope.json (the 0.4.4 behavior, fixed) --------
-# The user wants: every NEW prompt -> a fresh .scope.json the agent works from.
-# So we WRITE the scaffold when (a) there is no valid contract, OR (b) the
-# contract on disk is stale (its _intent_hash != current query hash). Fixed vs
-# 0.4.4: never writes to $HOME (bail above if no real root) -> no ghost files;
-# regenerates on prompt CHANGE not just absence -> "each prompt, new file".
+# --- auto-create / regenerate .scope.json -----------------------------------
+# CREATION does NOT require the query: if there's a root and no scope yet,
+# scaffold it NOW with intent=<TODO> (the agent fills it from the chat it's
+# already responding to). This was the 0.5.3 bug - creation was gated on
+# $hasQuery, so when Cursor didn't surface transcript_path in the first
+# postToolUse fire, the scope never got created.
+# REGENERATION does require the query: we can only detect a prompt change if
+# we can hash the current request. Without a query we leave an existing scope
+# alone (re-inject it) rather than blank it.
 regenerated=0
-should_write=0
-if [ "$has_query" = "1" ]; then
-    if [ "$scope_exists" != "1" ] || [ "$scope_stale" = "1" ]; then
-        should_write=1
-    fi
+should_create=0
+should_regen=0
+[ "$scope_exists" != "1" ] && should_create=1
+if [ "$has_query" = "1" ] && [ "$scope_exists" = "1" ] && [ "$scope_stale" = "1" ]; then
+    should_regen=1
 fi
 
-if [ "$should_write" = "1" ]; then
-    # jq preferred; python3 fallback. Write intent from the query, TODO
-    # placeholders for files/acceptance, and record _intent_hash so staleness
-    # is self-contained in the file (survives cross-session hash sweeps).
+if [ "$should_create" = "1" ] || [ "$should_regen" = "1" ]; then
+    # intent from the query when available, else a TODO for the agent to fill.
+    if [ "$has_query" = "1" ]; then
+        intent_val="$current_query"
+    else
+        intent_val="<TODO: state the operational objective - what is strictly necessary>"
+    fi
+    # jq preferred; python3 fallback. Write intent, empty files[], TODO
+    # acceptance, and record _intent_hash so staleness is self-contained.
     if have_jq; then
-        jq -n --arg intent "$current_query" --arg hash "$current_hash" \
-            '{intent:$intent, files:["<TODO: list files you will touch>"], acceptance:"<TODO: the one deterministic check that decides done>", allow_growth:false, _intent_hash:$hash, _generated_by:"intent-anchor hook"}' \
+        jq -n --arg intent "$intent_val" --arg hash "$current_hash" \
+            '{intent:$intent, files:[], acceptance:"<TODO: the one deterministic check that decides done>", allow_growth:false, _intent_hash:$hash, _generated_by:"intent-anchor hook"}' \
             > "$scope_path" 2>/dev/null && regenerated=1
     elif have_py; then
-        if I_FILE="$scope_path" I_INTENT="$current_query" I_HASH="$current_hash" python3 -c '
+        if I_FILE="$scope_path" I_INTENT="$intent_val" I_HASH="$current_hash" python3 -c '
 import json, os
 obj = {
     "intent": os.environ["I_INTENT"],
-    "files": ["<TODO: list files you will touch>"],
+    "files": [],
     "acceptance": "<TODO: the one deterministic check that decides done>",
     "allow_growth": False,
     "_intent_hash": os.environ["I_HASH"],
@@ -171,14 +191,18 @@ with open(os.environ["I_FILE"], "w", encoding="utf-8") as f:
         fi
     fi
     if [ "$regenerated" = "1" ]; then
-        scope_intent="$current_query"
+        scope_intent="$intent_val"
         scope_acceptance="<TODO: the one deterministic check that decides done>"
-        scope_files="<TODO: list files you will touch>"
+        scope_files="(auto-tracked - the scope hook records every file you edit)"
         scope_exists=1
         scope_stale=0
     fi
 fi
 
+# files[] is auto-tracked and starts empty; show something readable until the
+# scope hook has recorded the first edit.
+[ -n "$scope_files" ] || scope_files="(none yet - auto-tracked as you edit)"
+
 # --- compose the anchor message ---------------------------------------------
 # Three states: regenerated this turn (new prompt), no contract (and no query
 # to scaffold from), or re-injecting an existing current contract.
@@ -196,9 +220,10 @@ if [ "$regenerated" = "1" ]; then
   acceptance: $scope_acceptance
 
 The hook wrote a fresh scaffold to $scope_path from your current request. intent
-is locked from what you just asked. Fill the TODO placeholders with the real
-files you will touch and the deterministic acceptance check, THEN proceed. This
-contract will be re-injected every turn until your request changes again."
+is locked from what you just asked. files[] is AUTO-TRACKED - the scope hook
+records every file you edit, so do not maintain it by hand. Set acceptance to
+the one deterministic check that decides done, THEN proceed. This contract will
+be re-injected every turn until your request changes again."
 elif [ "$scope_exists" != "1" ]; then
     msg="INTENT ANCHOR (pre-compile) - no .scope.json found in $root, and the current
 request was unavailable to scaffold from.

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

@@ -1,19 +1,20 @@
 #!/usr/bin/env bash
-# scope-gate-audit.sh - afterFileEdit "declared scope" advisory (Cursor, Linux).
+# scope-gate-audit.sh - afterFileEdit "scope auto-record" (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.
+# Compuerta 1, mechanical edition: keep .scope.json's files[] in sync with what
+# the agent ACTUALLY edits, with ZERO reliance on the model remembering to fill
+# it. intent-anchor.sh writes the scaffold (intent locked from the prompt,
+# files: [], acceptance: TODO); THIS hook appends every edited file to files[]
+# as the edit happens. Net effect: the contract's files[] is always an accurate
+# ledger of the session footprint, which final-review audits against intent.
 #
-# 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).
+# This REPLACES the old declared-scope VIOLATION advisory. When every edit is
+# auto-recorded, an edit can never be "out of declared scope" - there is nothing
+# to violate. The gate became a recorder. acceptance stays the model's to fill.
 #
-# 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.
+# Opt-in: silent if .scope.json does not exist in the repo root. Rewrites ONLY
+# files[]; every other field is preserved. jq preferred, python3 fallback; if
+# neither is present we fail open (no JSON tool = no record). ALWAYS exits 0.
 # Disable: HOOKS_ENFORCE=0  or  SCOPE_GATE_ENFORCE=0
 
 set +e
@@ -45,111 +46,45 @@ done
 [ -n "$fp" ] || exit 0
 rel="$fp"
 case "$rel" in "$root"/*) rel="${rel#"$root"/}" ;; esac
+rel="${rel#/}"
 if is_cursor_config_path "$fp" || is_cursor_config_path "$rel"; then exit 0; fi
+# Never record the contract file into itself.
+[ "$rel" = ".scope.json" ] && exit 0
 
-# --- opt-in gate: no .scope.json = no gate ---------------------------------
+# --- opt-in gate: no .scope.json = nothing to maintain ---------------------
 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
+# --- auto-record $rel into files[] (jq preferred, python3 fallback) --------
+# Clean the existing list (drop the scaffold placeholder + blanks), then add
+# this edit if absent. Write only when the resulting files[] actually changed,
+# so repeat edits of the same file do not churn the contract.
+jq_prog='((.files // []) | map(select(type=="string" and . != "" and (startswith("<TODO")|not)))) as $c'
+
+if have_jq; then
+    old_files="$(jq -c '.files // []' "$scope_file" 2>/dev/null)"
+    new_files="$(jq -c --arg rel "$rel" "$jq_prog | (if (\$c | index(\$rel)) then \$c else \$c + [\$rel] end)" "$scope_file" 2>/dev/null)"
+    [ -n "$new_files" ] || exit 0
+    [ "$new_files" = "$old_files" ] && exit 0
+    updated="$(jq --arg rel "$rel" "$jq_prog | .files = (if (\$c | index(\$rel)) then \$c else \$c + [\$rel] end)" "$scope_file" 2>/dev/null)"
+    [ -n "$updated" ] && printf '%s\n' "$updated" > "$scope_file"
+elif have_py; then
+    I_FILE="$scope_file" I_REL="$rel" python3 -c '
+import json, os, sys
+path = os.environ["I_FILE"]; rel = os.environ["I_REL"]
 try:
-    p = json.loads(sys.stdin.read())
+    d = json.load(open(path, encoding="utf-8"))
 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
+    sys.exit(0)
+files = d.get("files", []) or []
+clean = [f for f in files if isinstance(f, str) and f and not f.startswith("<TODO")]
+new = clean if rel in clean else clean + [rel]
+if new == files:
+    sys.exit(0)
+d["files"] = new
+with open(path, "w", encoding="utf-8") as f:
+    json.dump(d, f, ensure_ascii=False, indent=2)
+' 2>/dev/null
 fi
 
 exit 0

package/linux/hooks.json

@@ -25,7 +25,7 @@
         "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."
+        "_comment": "10s (Compuerta 1, mechanical): scope auto-record. OPT-IN: only active when .scope.json exists in the repo root. intent-anchor scaffolds files:[]; this hook APPENDS every edited file to files[] (drops the scaffold placeholder, dedups, preserves all other fields) via jq with a python3 fallback, so files[] is always an accurate ledger of the session footprint that final-review audits against intent. No model effort required - the agent never maintains files[] by hand. Replaces the old [SCOPE VIOLATION] advisory (with auto-record an edit can never be out-of-declared-scope). No JSON tool / no .scope.json = silent. Never blocks, always exits 0. Disable: HOOKS_ENFORCE=0 or SCOPE_GATE_ENFORCE=0."
       },
       {
         "command": "bash ~/.agents/hooks/anti-slop-audit.sh",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursordoctrine",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "Thin self-review hooks for Cursor — the model is the auditor. Pruned + deduplicated: intent-anchor (auto-scaffolded .scope.json per prompt + per-turn re-injection against Salience Dilution), intent-trace final review, unified anti-slop checklist as single source of truth.",
   "bin": {
     "cursordoctrine": "bin/cli.mjs"

package/windows/hooks/final-review.md

@@ -122,5 +122,18 @@ Determinism / purity:
   - In-place mutation of shared state (arr.push, obj.prop =) when a caller holds
     a reference -> return new structures ([...arr, x], .map/.filter).
 
+Logic & structure:
+  - Arrow code: >2 levels of nested if/for -> flatten with guard clauses
+    (early returns). Code reads top-to-bottom, no deep indent.
+  - Switch/if-else bloat: a switch or 5+ if/else branches -> Map/dispatch
+    (Record<State, fn>) or the Command pattern.
+  - Mixed abstraction (SLAP): a function mixing DB calls + string validation +
+    date formatting -> one level of abstraction per function; extract helpers.
+  - Primitive obsession: a primitive with business rules (email, userId, chainId)
+    passed as a bare string/number across functions -> a named type/value object.
+  - Imperative transforms: a `for` loop building an array when the language has
+    .map/.filter/.reduce -> use the declarative form; reserve `for` for cases
+    map/reduce cannot express.
+
 You do NOT need to run a tool for these — read the diff and apply the named fix.
 If none apply, say so in one line.

package/windows/hooks/intent-anchor.ps1

@@ -14,15 +14,20 @@
 #      at the START of each turn's work, before edits pile up and dilute the
 #      original intent. Works UNCONDITIONALLY - no transcript needed.
 #
-#   2. AUTO-CREATE / REGENERATE .scope.json: when the current <user_query>
-#      differs from the contract on disk (no contract yet, OR _intent_hash
-#      mismatch), the hook WRITES a scaffold to the REPO ROOT: intent locked
-#      from the prompt, files/acceptance as TODO placeholders the agent
-#      refines. This is the user-requested behavior: every new prompt ->
-#      a fresh .scope.json the agent works from. Fixed vs the broken 0.4.4
+#   2. AUTO-CREATE .scope.json (UNCONDITIONAL on a real root): if no valid
+#      contract exists in the repo root, WRITE one now - intent locked from the
+#      query when available, otherwise `intent: <TODO>` for the agent to fill.
+#      Creation does NOT require transcript_path; only regeneration does. This
+#      was the 0.5.3 bug: creation was gated on $hasQuery, so when Cursor didn't
+#      surface the transcript on the first postToolUse fire, the scope never
+#      appeared and the agent had no contract to work from.
+#   3. REGENERATE on prompt CHANGE: when the current <user_query> hash differs
+#      from the contract's _intent_hash, overwrite the scaffold with the new
+#      intent + empty files + TODO acceptance. Requires $hasQuery (you can only
+#      detect a change if you can read the request). Fixed vs the broken 0.4.4
 #      build: never writes to $HOME (bails if no real root resolves -> no
-#      ghost files), and regenerates on prompt CHANGE not just on absence.
-#   3. RE-INJECT on same-prompt turns: when the query is unchanged (contract
+#      ghost files).
+#   4. RE-INJECT on same-prompt turns: when the query is unchanged (contract
 #      already current), the hook re-injects the existing contract into the
 #      feedback bus so it stays in the model's attentional focus each turn.
 #
@@ -54,6 +59,16 @@ $pendingDir = Get-HooksPendingDir
 $latch    = Join-Path $pendingDir "intent-injected-$cid.flag"
 $hashFile = Join-Path $pendingDir "last-query-$cid.hash"
 
+# Stale-latch defense: if a previous session died mid-turn without hitting
+# stop (Cursor crash, force-quit), the latch can persist and silence this hook
+# for the whole next session -> scope never gets created. If the latch is older
+# than 2 hours, treat it as orphaned and clear it. Normal clears happen at
+# every stop (final-review.ps1); this is the backstop for abnormal terminations.
+if (Test-Path $latch) {
+    $age = (Get-Date) - (Get-Item $latch).LastWriteTime
+    if ($age.TotalHours -ge 2) { Remove-Item $latch -Force -ErrorAction SilentlyContinue }
+}
+
 # Already injected this turn -> quiet. Latch cleared at every stop.
 if (Test-Path $latch) { exit 0 }
 
@@ -101,7 +116,8 @@ if (Test-Path -LiteralPath $scopePath) {
         $sj = Get-Content -LiteralPath $scopePath -Raw | ConvertFrom-Json
         if ($sj.intent)     { $scopeIntent = [string]$sj.intent }
         if ($sj.acceptance) { $scopeAcceptance = [string]$sj.acceptance }
-        if ($sj.files)      { $scopeFiles = ($sj.files -join ', ') }
+        if ($sj.files)      { $scopeFiles = (@($sj.files) -join ', ') }
+        if ([string]::IsNullOrWhiteSpace($scopeFiles)) { $scopeFiles = '(none yet - auto-tracked as you edit)' }
         $scopeExists = $true
         # The contract is "stale" if its recorded intent hash != current query
         # hash. We persist the query hash inside .scope.json under _intent_hash
@@ -112,22 +128,25 @@ if (Test-Path -LiteralPath $scopePath) {
     } catch { $scopeExists = $false }   # malformed JSON -> treat as missing
 }
 
-# --- auto-create / regenerate .scope.json (the 0.4.4 behavior, fixed) --------
-# The user wants: every NEW prompt -> a fresh .scope.json the agent works from.
-# So we WRITE the scaffold when (a) there is no valid contract, OR (b) the
-# contract on disk is stale (its _intent_hash != current query hash). Intent is
-# locked from the current <user_query>; files/acceptance are TODO placeholders
-# the agent refines. Fixed vs 0.4.4:
-#   - NEVER writes to $HOME (bail above if no real root) -> no ghost files.
-#   - Regenerates on prompt CHANGE, not just on absence -> "each prompt, new file".
-#   - Records _intent_hash so staleness is self-contained in the file.
+# --- auto-create / regenerate .scope.json -----------------------------------
+# CREATION does NOT require the query: if there's a root and no scope yet,
+# scaffold it NOW with intent=<TODO> (the agent fills it from the chat it's
+# already responding to). This was the 0.5.3 bug - creation was gated on
+# $hasQuery, so when Cursor didn't surface transcript_path in the first
+# postToolUse fire, the scope never got created. The agent never had a
+# contract to work from.
+# REGENERATION does require the query: we can only detect a prompt change if
+# we can hash the current request. Without a query we leave an existing scope
+# alone (re-inject it) rather than blank it.
 $regenerated = $false
-$shouldWrite = $hasQuery -and (-not $scopeExists -or $scopeStale)
-if ($shouldWrite) {
+$shouldCreate = -not $scopeExists
+$shouldRegen  = $hasQuery -and $scopeExists -and $scopeStale
+if ($shouldCreate -or $shouldRegen) {
     try {
+        $intentVal = if ($hasQuery) { $currentQuery } else { '<TODO: state the operational objective - what is strictly necessary>' }
         $scaffold = [ordered]@{
-            intent        = $currentQuery
-            files         = @('<TODO: list files you will touch>')
+            intent        = $intentVal
+            files         = @()
             acceptance    = '<TODO: the one deterministic check that decides done>'
             allow_growth  = $false
             _intent_hash  = $currentHash
@@ -135,9 +154,9 @@ if ($shouldWrite) {
         }
         $json = $scaffold | ConvertTo-Json -Depth 5
         [System.IO.File]::WriteAllText($scopePath, $json, [System.Text.UTF8Encoding]::new($false))
-        $scopeIntent     = $currentQuery
+        $scopeIntent     = $intentVal
         $scopeAcceptance = '<TODO: the one deterministic check that decides done>'
-        $scopeFiles      = '<TODO: list files you will touch>'
+        $scopeFiles      = '(auto-tracked - the scope hook records every file you edit)'
         $scopeExists     = $true
         $scopeStale      = $false
         $regenerated     = $true
@@ -158,9 +177,10 @@ INTENT ANCHOR (scope regenerated) - .scope.json written for this prompt.
   acceptance: $scopeAcceptance
 
 The hook wrote a fresh scaffold to $scopePath from your current request. intent
-is locked from what you just asked. Fill the TODO placeholders with the real
-files you will touch and the deterministic acceptance check, THEN proceed. This
-contract will be re-injected every turn until your request changes again.
+is locked from what you just asked. files[] is AUTO-TRACKED - the scope hook
+records every file you edit, so do not maintain it by hand. Set acceptance to
+the one deterministic check that decides done, THEN proceed. This contract will
+be re-injected every turn until your request changes again.
 "@
 } elseif (-not $scopeExists) {
     $msg = @"

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

@@ -1,22 +1,22 @@
-# scope-gate-audit.ps1 - afterFileEdit "declared scope" advisory (Cursor).
+# scope-gate-audit.ps1 - afterFileEdit "scope auto-record" (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.
+# Compuerta 1, mechanical edition: keep .scope.json's files[] in sync with what
+# the agent ACTUALLY edits, with ZERO reliance on the model remembering to fill
+# it. intent-anchor.ps1 writes the scaffold (intent locked from the prompt,
+# files: [], acceptance: TODO); THIS hook appends every edited file to files[]
+# as the edit happens. Net effect: the contract's files[] is always an accurate
+# ledger of the session footprint, which final-review audits against intent
+# (the "you touched 8 files for a 1-line request - justify" axis).
 #
-# 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).
+# This REPLACES the old declared-scope VIOLATION advisory. When every edit is
+# auto-recorded, an edit can never be "out of declared scope" - there is nothing
+# to violate. The gate became a recorder. acceptance stays the model's to fill:
+# a deterministic success check cannot be derived mechanically.
 #
-# 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.
+# Opt-in: silent if .scope.json does not exist in the repo root (no scaffold yet
+# = nothing to maintain). Rewrites ONLY files[]; every other field (intent,
+# acceptance, allow_growth, _intent_hash, _generated_by, ...) is preserved.
+# Never blocks, never needs Python, ALWAYS exits 0.
 # Disable: HOOKS_ENFORCE=0  or  SCOPE_GATE_ENFORCE=0
 
 $ErrorActionPreference = 'SilentlyContinue'
@@ -43,94 +43,55 @@ foreach ($k in 'file_path', 'path', 'filename', 'absolute_path', 'abs_path') {
 if (-not $fp) { exit 0 }
 $rel = ConvertTo-FwdPath $fp
 if ($rel.StartsWith($root + '/', [System.StringComparison] 'OrdinalIgnoreCase')) { $rel = $rel.Substring($root.Length + 1) }
+$rel = $rel.TrimStart('/')
 if (Test-IsCursorConfigPath $fp) { exit 0 }
 if (Test-IsCursorConfigPath $rel) { exit 0 }
+# Never record the contract file into itself.
+if ($rel -ieq '.scope.json') { exit 0 }
 
-# --- opt-in gate: no .scope.json = no gate ---------------------------------
+# --- opt-in gate: no .scope.json = nothing to maintain ---------------------
 $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 }
-$acceptance = ''
-if ($payload.PSObject.Properties['acceptance']) { $acceptance = [string]$payload.acceptance }
-
-# 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 { }
-
-# acceptance line: only quote it when the agent bothered to declare 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.
-$acceptanceLine = if ($acceptance) { $acceptance } else { '(not declared — your Anchor Set is missing the ÉXITO/acceptance field)' }
-
-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.
-
-  Your success contract (acceptance): $acceptanceLine
-  Does growing into $rel still serve that?
-"@
-} 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
-    acceptance: $acceptanceLine
-
-  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.
+# --- load the contract; bail quietly on malformed JSON ---------------------
+$sj = $null
+try { $sj = Get-Content -LiteralPath $scopeFile -Raw | ConvertFrom-Json } catch { exit 0 }
+if (-not $sj) { exit 0 }
+
+# --- compute the new files[] -----------------------------------------------
+# Start from existing files, drop the scaffold placeholder and blanks, then add
+# this edit if it is not already recorded (case-insensitive, slash-normalized).
+$existing = @()
+if ($sj.PSObject.Properties['files'] -and $sj.files) { $existing = @($sj.files) }
+
+$kept = @()
+foreach ($e in $existing) {
+    if (-not $e) { continue }
+    $s = [string]$e
+    if ($s -match '^\s*<TODO') { continue }       # drop the scaffold placeholder
+    if ([string]::IsNullOrWhiteSpace($s)) { continue }
+    $kept += $s
+}
 
-  Declared-editing: declare BEFORE you expand. Don't sneak edits past the gate.
-"@
+$already = $false
+foreach ($f in $kept) {
+    if (([string]$f).Replace('\', '/').TrimStart('/') -ieq $rel) { $already = $true; break }
 }
+if (-not $already) { $kept += $rel }
 
-$msg = "$summary`n`n$body`n`n(Advisory; disable: SCOPE_GATE_ENFORCE=0)"
+# Only rewrite when files[] actually changed (avoid churning the file on every
+# repeat edit of the same path).
+$before = ($existing | ForEach-Object { [string]$_ }) -join '|'
+$after  = ($kept     | ForEach-Object { [string]$_ }) -join '|'
+if ($before -eq $after) { exit 0 }
 
-# --- append to the shared pending file --------------------------------------
-$cid = Get-SafeConversationId $obj
-$pending = Join-Path (Get-HooksPendingDir) "feedback-$cid.txt"
+# --- write back, preserving every other field and its order ----------------
 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
+    $ordered = [ordered]@{}
+    foreach ($p in $sj.PSObject.Properties) { $ordered[$p.Name] = $p.Value }
+    $ordered['files'] = @($kept)                  # force array form under pwsh 7
+    $json = $ordered | ConvertTo-Json -Depth 8
+    [System.IO.File]::WriteAllText($scopeFile, $json, [System.Text.UTF8Encoding]::new($false))
 } catch { }
 
 exit 0

package/windows/hooks.json

@@ -25,7 +25,7 @@
         "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."
+        "_comment": "10s (Compuerta 1, mechanical): scope auto-record. OPT-IN: only active when .scope.json exists in the repo root. intent-anchor scaffolds files:[]; this hook APPENDS every edited file to files[] (drops the scaffold placeholder, dedups, preserves all other fields), so files[] is always an accurate ledger of the session footprint that final-review audits against intent. No model effort required - the agent never maintains files[] by hand. Replaces the old [SCOPE VIOLATION] advisory (with auto-record an edit can never be out-of-declared-scope). No JSON tool / no .scope.json = silent. Never blocks, always exits 0. Disable: HOOKS_ENFORCE=0 or SCOPE_GATE_ENFORCE=0."
       },
       {
         "command": "pwsh.exe -NoProfile -File ~/.agents/hooks/anti-slop-audit.ps1",