cursordoctrine 0.4.2 → 0.4.4

package/INSTALL.md

@@ -120,4 +120,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`, `ANCHOR_NUDGE_ENFORCE=0` (pre-compile nudge off), `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`.
+Kill switches if something misbehaves: `HOOKS_ENFORCE=0` (everything advisory off), `PERM_GATE_ENFORCE=0`, `ANCHOR_NUDGE_ENFORCE=0` (pre-compile nudge off), `INTENT_ANCHOR_ENFORCE=0` (thin-intent re-injection off), `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

@@ -94,12 +94,24 @@ On the **first edit of each agent turn**, `anchor-set-nudge` drops a reminder in
 
 The Anchor Set is skipped for trivial one-liners (typo, literal) — the `declared-editing.md` ladder's rung 1 governs when it's overkill.
 
+### Keeping the contract alive: `intent-anchor` (anti-Salience-Dilution)
+
+Writing `.scope.json` once is not enough. As a conversation fills with code, logs and errors, the token of the original request shrinks to a rounding error against the recent history — *Salience Dilution* — and the agent stops checking the contract it wrote at prompt 1. It forgets symmetry, colors, the acceptance bar. This is the failure mode the nudge alone can't fix (a reminder that the contract exists ≠ the contract being in context).
+
+`intent-anchor` (`postToolUse`, registered first so it runs before `post-tool-use` drains the bus) does three things on the **first tool boundary of every turn** (per-turn latch, cleared unconditionally at each stop):
+
+1. **Materialize the contract (0.4.4+).** If `.scope.json` is missing or invalid and the current `<user_query>` is available, the hook **writes a scaffold to disk** — `intent` from your prompt, `files`/`acceptance` as obvious `<TODO: …>` placeholders. Contract creation is no longer probabilistic.
+2. **Re-inject the contract.** Reads `.scope.json` and stashes `intent` + `files` + `acceptance` into the feedback bus, which `post-tool-use` delivers as `additional_context`.
+3. **Re-compile on prompt change.** Hashes the current `<user_query>` and compares to the previous turn's hash. If the request moved and a non-scaffold contract already exists, it demands the agent **update** `.scope.json`.
+
+Crucially, `intent-anchor` carries the **semantic** contract (`intent`/`acceptance`) into context every turn — something the path-only `scope-gate-audit` can never do. That is what makes "the agent forgot about grid symmetry while editing the right file" catchable: the symmetry requirement is re-stated in front of the model before each edit, not just checked against a file list after.
+
 ## The five flows
 
 | Flow | Event | What happens |
 |---|---|---|
 | Session | `sessionStart` | `inject-doctrine` reads doctrine + user rules + declared-editing + **pre-compile** 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. |
+| Every turn | `postToolUse` | **`intent-anchor`** (registered first) re-injects `.scope.json` into `additional_context` at the first tool boundary of each turn — the anti-Salience-Dilution move that keeps `intent` + `acceptance` in the model's attentional focus before edits pile up. If the prompt changed since last turn, it demands the contract be updated. Then `post-tool-use` folds subagent markers and drains the feedback file. |
 | Shell | `beforeShellExecution` | `permission-gate` checks the command against a deny list. Allow by default, deny by list, fail open. |
 | Edit | `afterFileEdit` + `stop` | **Proactive:** `anchor-set-nudge` fires once per turn (on its first edit) to push the Anchor Set. **Reactive:** `self-review-trigger` stashes the review prompt per edit; `minimal-edit-audit` (deprecated), `semantic-density-audit`, `scope-gate-audit` (opt-in, audits `.scope.json`), and `anti-slop-audit` append advisories when they trip; `final-review` fires one end-of-implementation six-axis 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`. |
@@ -137,6 +149,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 |
 | `ANCHOR_NUDGE_ENFORCE=0` | on | disables the pre-compile nudge (first-edit Anchor Set reminder) |
+| `INTENT_ANCHOR_ENFORCE=0` | on | disables the thin-intent re-injection (per-turn `.scope.json` echo into `additional_context`) |
 | `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 |

package/bin/cli.mjs

@@ -74,6 +74,26 @@ function mergeHooks(existing, incoming, keys) {
       if (i >= 0) cur[i] = entry;
       else cur.push(entry);
     }
+    // Re-order our entries to match the shipped hooks.json (merge used to leave
+    // stale order — e.g. post-tool-use before intent-anchor — breaking same-tool
+    // delivery of the anchor message).
+    const foreign = cur.filter((x) => x && !isOurs(x.command, keys));
+    const reordered = [];
+    const used = new Set();
+    for (const entry of entries) {
+      const k = keyOf(entry.command, keys);
+      if (!k || !isOurs(entry.command, keys)) continue;
+      const found = cur.find((x) => x && keyOf(x.command, keys) === k);
+      if (found) {
+        reordered.push(found);
+        used.add(k);
+      }
+    }
+    for (const x of cur) {
+      const k = keyOf(x?.command, keys);
+      if (isOurs(x?.command, keys) && k && !used.has(k)) reordered.push(x);
+    }
+    out.hooks[event] = [...reordered, ...foreign];
   }
   let preserved = 0;
   for (const entries of Object.values(out.hooks)) {
@@ -300,6 +320,70 @@ function verify() {
     return true;
   });
 
+  check('intent-anchor scaffolds .scope.json and re-injects every turn', () => {
+    const drainedOf = (cidv) => runHook(hook('post-tool-use'), { conversation_id: cidv });
+    const anchorCid = 'npxv4';
+    const scopePath = join(HOME, '.scope.json');
+    const transcriptPath = join(HOME, '.cursor', '.hooks-pending', 'verify-transcript-npxv4.jsonl');
+    const testQuery = 'fix grid symmetry and color tokens';
+
+    const cleanup = () => {
+      try { rmSync(scopePath, { force: true }); } catch {}
+      try { rmSync(transcriptPath, { force: true }); } catch {}
+    };
+    cleanup();
+
+    // Fake transcript so Get-LastUserQuery / scaffold can read the request.
+    const transcriptLine = JSON.stringify({
+      role: 'user',
+      message: { content: `<user_query>${testQuery}</user_query>` },
+    });
+    writeFileSync(transcriptPath, transcriptLine + '\n', 'utf8');
+
+    const anchorPayload = { conversation_id: anchorCid, cwd: HOME, transcript_path: transcriptPath };
+
+    // --- Case A: no .scope.json -> hook writes scaffold on disk ----------
+    runHook(hook('intent-anchor'), anchorPayload);
+    let d = drainedOf(anchorCid);
+    if (!existsSync(scopePath)) {
+      cleanup(); return { ok: false, detail: '.scope.json was not written to disk' };
+    }
+    let scope;
+    try { scope = JSON.parse(readFileSync(scopePath, 'utf8')); } catch {
+      cleanup(); return { ok: false, detail: '.scope.json scaffold is not valid JSON' };
+    }
+    if (scope.intent !== testQuery) {
+      cleanup(); return { ok: false, detail: `scaffold intent mismatch: ${scope.intent}` };
+    }
+    if (!d.includes('scaffold written') || !d.includes(testQuery)) {
+      cleanup(); return { ok: false, detail: 'scaffold branch did not inject written contract' };
+    }
+
+    // --- Stop clears the latch -------------------------------------------
+    runHook(hook('final-review'), { conversation_id: anchorCid, status: 'completed' });
+
+    // --- Case B: scope exists -> re-inject contract every turn -----------
+    writeFileSync(scopePath, JSON.stringify({
+      intent: 'fix grid symmetry and color tokens',
+      files: ['src/grid.tsx'],
+      acceptance: 'grid renders symmetric; tokens match palette',
+    }));
+    runHook(hook('intent-anchor'), { conversation_id: anchorCid, cwd: HOME, transcript_path: transcriptPath });
+    d = drainedOf(anchorCid);
+    if (!d.includes('fix grid symmetry and color tokens') || !d.includes('INTENT ANCHOR')) {
+      cleanup(); return { ok: false, detail: 'contract not re-injected on turn 2' };
+    }
+
+    runHook(hook('final-review'), { conversation_id: anchorCid, status: 'completed' });
+    runHook(hook('intent-anchor'), { conversation_id: anchorCid, cwd: HOME, transcript_path: transcriptPath });
+    d = drainedOf(anchorCid);
+    if (!d.includes('fix grid symmetry and color tokens')) {
+      cleanup(); return { ok: false, detail: 'contract not re-injected on turn 3 (latch stranded at stop)' };
+    }
+    cleanup();
+    return true;
+  });
+
   check('doctrine injection emits additional_context', () =>
     runHook(join(cursorDst, injectName), {}).includes('additional_context'));
 
@@ -410,6 +494,7 @@ Kill switches (environment variables, all hooks fail open)
   HOOKS_ENFORCE=0              everything advisory off
   PERM_GATE_ENFORCE=0          permission gate off
   ANCHOR_NUDGE_ENFORCE=0       pre-compile nudge off (first-edit Anchor Set reminder)
+  INTENT_ANCHOR_ENFORCE=0      thin-intent re-injection off (per-turn .scope.json echo)
   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

package/linux/hooks/final-review.sh

@@ -37,16 +37,20 @@ 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"
+intent_latch="$pending_dir/intent-injected-$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
 
-# Unconditionally clear the pre-compile nudge's per-turn latch. Every stop is a
-# turn boundary; clearing here (not only inside the reviewed-flag block below)
-# guarantees the nudge re-fires on the first edit of the NEXT turn and can never
-# get stranded silenced. Clearing it only on the SECOND stop left the nudge
-# permanently off for any conversation that never cleanly hit that boundary.
-rm -f "$anchor_flag" 2>/dev/null
+# Unconditionally clear the per-turn latches so the next turn re-fires. Every
+# stop is a turn boundary; clearing here (not only inside the reviewed-flag
+# block below) guarantees these re-fire on the first edit/tool of the NEXT
+# turn and can never get stranded silenced mid-session:
+#   - anchor-declared-<cid>.flag  (anchor-set-nudge, first-edit reminder)
+#   - intent-injected-<cid>.flag  (intent-anchor, first-tool re-injection)
+# last-query-<cid>.hash is NOT cleared here - it persists turn-to-turn so
+# intent-anchor can detect prompt changes; the 7-day sweep above reaps it.
+rm -f "$anchor_flag" "$intent_latch" 2>/dev/null
 
 # One-shot brake: the previous stop for this conversation emitted the review.
 if [ -f "$flag" ]; then

package/linux/hooks/intent-anchor.sh

@@ -0,0 +1,225 @@
+#!/usr/bin/env bash
+# intent-anchor.sh - postToolUse "thin intent compilation" anchor (Cursor, Linux).
+#
+# Counteracts Salience Dilution: the failure mode where the agent's original
+# intent erodes as the conversation fills with code, logs and errors, until the
+# token of the original request is a rounding error against the recent history
+# and the agent drifts ("forgets" symmetry, colors, the .scope.json it wrote at
+# prompt 1). Two jobs, both on the FIRST tool boundary of each turn (per-turn
+# latch intent-injected-<cid>.flag, armed here, cleared at every stop):
+#
+#   1. RE-INJECT .scope.json (the core anti-dilution move): read the contract
+#      (intent + files + acceptance) and stash it in the feedback bus so
+#      post-tool-use.sh delivers it as additional_context at the next tool
+#      boundary. This puts the contract back in the model's attentional focus
+#      at the START of each turn's work, before edits pile up and dilute the
+#      original intent. Works UNCONDITIONALLY - no transcript needed.
+#
+#   2. RE-COMPILE ON PROMPT CHANGE: hash the current <user_query> (via
+#      extract_last_user_query, which reads the transcript) and compare to
+#      last-query-<cid>.hash. If they differ and a valid .scope.json exists,
+#      demand the agent UPDATE it. If no valid .scope.json exists and the query
+#      is available, WRITE a deterministic scaffold to disk (intent = query,
+#      files/acceptance = TODO placeholders) so re-injection always has real
+#      content from the first tool boundary — contract creation is not left to
+#      the LLM alone.
+#
+# Why postToolUse, not afterFileEdit: afterFileEdit only fires AFTER an edit
+# exists, and Cursor has no preToolUse for file edits. postToolUse fires after
+# EVERY tool (Read/Glob/Bash/Write/...), so its first fire of a turn is the
+# earliest moment the agent has begun working - typically right after the first
+# Read/Glob, before any edit. Best available injection point for "before files".
+#
+# Once per turn: latch armed on first fire, cleared UNCONDITIONALLY at every
+# stop (final-review.sh). Cannot strand silenced mid-session. Registered first
+# in the postToolUse array so it appends to the feedback bus before
+# post-tool-use.sh drains it (same-tool delivery; if reordered, delivery slips
+# one tool - still correct).
+#
+# Advisory only: never blocks, never reads the diff, ALWAYS exits 0. Appends to
+# the shared feedback-<cid>.txt bus. Disable: HOOKS_ENFORCE=0 or INTENT_ANCHOR_ENFORCE=0.
+
+set +e
+. "$(dirname "$0")/hook-common.sh"
+
+[ "${HOOKS_ENFORCE:-}" = "0" ] && exit 0
+[ "${INTENT_ANCHOR_ENFORCE:-}" = "0" ] && exit 0
+
+input="$(read_hook_stdin)"
+[ -n "$input" ] || exit 0
+
+cid="$(safe_conversation_id "$input")"
+pending_dir="$(hooks_pending_dir)"
+latch="$pending_dir/intent-injected-$cid.flag"
+hash_file="$pending_dir/last-query-$cid.hash"
+
+# Already injected this turn -> quiet. Latch cleared at every stop.
+[ -f "$latch" ] && exit 0
+
+# --- current request (best-effort; absent in sandboxed runs) -----------------
+current_query="$(extract_last_user_query "$input")"
+has_query=0
+[ -n "$current_query" ] && has_query=1
+
+current_hash=""
+prompt_changed=0
+if [ "$has_query" = "1" ]; then
+    if command -v sha256sum >/dev/null 2>&1; then
+        current_hash="$(printf '%s' "$current_query" | sha256sum | awk '{print $1}')"
+    elif command -v shasum >/dev/null 2>&1; then
+        current_hash="$(printf '%s' "$current_query" | shasum -a 256 | awk '{print $1}')"
+    fi
+    prev_hash=""
+    [ -f "$hash_file" ] && prev_hash="$(cat "$hash_file" 2>/dev/null)"
+    [ "$current_hash" != "$prev_hash" ] && prompt_changed=1
+fi
+
+# --- repo root (same resolution as scope-gate-audit.sh) ----------------------
+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%/}"
+
+# --- read the existing contract (if any) -------------------------------------
+scope_exists=0
+scope_intent=""
+scope_acceptance=""
+scope_files=""
+scope_path="$root/.scope.json"
+if [ -f "$scope_path" ]; then
+    # Prefer jq; fall back to python3 (mirrors hook-common.sh degrade policy).
+    if have_jq; then
+        scope_intent="$(jq -r '.intent // empty' "$scope_path" 2>/dev/null)"
+        scope_acceptance="$(jq -r '.acceptance // empty' "$scope_path" 2>/dev/null)"
+        scope_files="$(jq -r '(.files // []) | join(", ")' "$scope_path" 2>/dev/null)"
+        scope_exists=1
+    elif have_py; then
+        read -r scope_intent scope_acceptance scope_files <<EOF
+$(python3 -c '
+import json, sys
+try:
+    d = json.load(open(sys.argv[1]))
+    print(d.get("intent","") or "")
+    print(d.get("acceptance","") or "")
+    print(", ".join(d.get("files",[]) or []))
+except Exception:
+    sys.exit(1)
+' "$scope_path" 2>/dev/null)
+EOF
+        [ $? -eq 0 ] && scope_exists=1 || scope_exists=0
+    fi
+fi
+
+# --- deterministic scaffold (0.4.4) -------------------------------------------
+# When the query is available and there is no valid contract, write .scope.json
+# on disk — intent from <user_query>, TODO placeholders for files/acceptance.
+scaffold_written=0
+should_scaffold=0
+[ "$has_query" = "1" ] && [ "$scope_exists" != "1" ] && should_scaffold=1
+
+if [ "$should_scaffold" = "1" ]; then
+    if have_py; then
+        if python3 -c '
+import json, sys
+path, intent = sys.argv[1], sys.argv[2]
+obj = {
+    "intent": intent,
+    "files": ["<TODO: list files>"],
+    "acceptance": "<TODO: deterministic success check>",
+    "allow_growth": False,
+}
+with open(path, "w", encoding="utf-8") as f:
+    json.dump(obj, f, ensure_ascii=False)
+' "$scope_path" "$current_query" 2>/dev/null; then
+            scaffold_written=1
+            scope_exists=1
+            scope_intent="$current_query"
+            scope_acceptance="<TODO: deterministic success check>"
+            scope_files="<TODO: list files>"
+        fi
+    fi
+fi
+
+# --- compose the anchor message ---------------------------------------------
+if [ "$has_query" = "1" ]; then
+    query_line="$current_query"
+else
+    query_line="(current request unavailable - no transcript in this event)"
+fi
+
+if [ "$scaffold_written" = "1" ]; then
+    msg="INTENT ANCHOR (scaffold written to .scope.json) - contract materialized from your request.
+
+  intent:     $scope_intent
+  files:      $scope_files
+  acceptance: $scope_acceptance
+
+The hook wrote this scaffold to $scope_path — intent is locked from your current
+request. Replace the TODO placeholders with real files[] and acceptance before
+editing source. The contract is on disk and will be re-injected every turn."
+elif [ "$scope_exists" != "1" ]; then
+    msg="INTENT ANCHOR (pre-compile) - no .scope.json found in $root.
+
+Current request:
+  $query_line
+
+You have NOT compiled your Anchor Set. Before editing files, write .scope.json
+in the repo root:
+  intent:     one operational sentence (what is strictly necessary)
+  files:      the exact files you will touch
+  acceptance: the one deterministic check that decides done
+
+Compile it now, then proceed. The scope tracks the request - it is how you stay
+on the rails when the conversation gets long."
+elif [ "$prompt_changed" = "1" ]; then
+    msg="INTENT ANCHOR (pre-compile) - your request changed; .scope.json may be stale.
+
+Current request:
+  $query_line
+
+Your existing contract (.scope.json):
+  intent:     $scope_intent
+  files:      $scope_files
+  acceptance: $scope_acceptance
+
+If the current request differs from the intent above, UPDATE .scope.json now
+to match what was just asked. When the request moves, the scope moves with it -
+do not edit against a contract written for a different request."
+else
+    # Same prompt continuing (or query unavailable) -> re-inject the contract.
+    if [ "$has_query" = "1" ]; then
+        drift_note="Every edit this turn must advance intent and stay inside files. acceptance is the bar for done."
+    else
+        drift_note="(request unavailable to diff against - re-injecting the contract as-is.)"
+    fi
+    msg="INTENT ANCHOR (re-injected this turn from .scope.json) - your contract. Do not drift from it.
+
+  intent:     $scope_intent
+  files:      $scope_files
+  acceptance: $scope_acceptance
+
+$drift_note If a constraint above conflicts with what you are about to do, stop
+and reconcile - the contract outranks momentum."
+fi
+
+# --- stash to the feedback bus (drained by post-tool-use.sh) -----------------
+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 latch; record the query hash for next-turn change detection -----
+touch "$latch" 2>/dev/null
+if [ -n "$current_hash" ]; then
+    printf '%s' "$current_hash" > "$hash_file" 2>/dev/null
+fi
+
+exit 0

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

@@ -45,11 +45,12 @@ 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"
+intent_latch="$pending_dir/intent-injected-$cid.flag"
 
-# Unconditionally clear the pre-compile nudge's per-turn latch so it re-fires
-# on the first edit of the next subagent run. Clearing here (not only inside
-# the reviewed-flag block below) can never strand the nudge silenced.
-rm -f "$anchor_flag" 2>/dev/null
+# Unconditionally clear the per-turn latches so the next subagent run re-fires.
+# Clearing here (not only inside the reviewed-flag block below) can never strand
+# them silenced. last-query-<cid>.hash is kept (cross-turn prompt-change detect).
+rm -f "$anchor_flag" "$intent_latch" 2>/dev/null
 
 # One-shot brake: the previous subagentStop for this id emitted the review.
 if [ -f "$flag" ]; then

package/linux/hooks.json

@@ -47,6 +47,11 @@
       }
     ],
     "postToolUse": [
+      {
+        "command": "bash ~/.agents/hooks/intent-anchor.sh",
+        "timeout": 5,
+        "_comment": "5s: THIN INTENT COMPILATION (anti Salience Dilution). Registered FIRST so it appends to the feedback bus before post-tool-use.sh drains it (same-tool delivery). On the FIRST tool boundary of each turn (per-turn latch intent-injected-<cid>.flag, cleared unconditionally at every stop), (1) re-injects the existing .scope.json (intent/files/acceptance) into additional_context so the contract is back in the model's attentional focus before edits pile up - UNCONDITIONAL, no transcript needed; (2) if the current <user_query> hash differs from last-query-<cid>.hash, demands the agent UPDATE .scope.json to match the new request (scope tracks the request). No .scope.json -> demand one be written. Needs transcript_path for change-detection; degrades to silent there but re-injection still runs. Advisory only; never blocks. Disable: HOOKS_ENFORCE=0 or INTENT_ANCHOR_ENFORCE=0."
+      },
       {
         "command": "bash ~/.agents/hooks/post-tool-use.sh",
         "timeout": 5,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cursordoctrine",
-  "version": "0.4.2",
-  "description": "Thin self-review hooks for Cursor — the model is the auditor. Pre-compile Anchor Set phase (proactive intent compilation, fires once per turn), intent-trace final review (Tier 0), unified 13-item anti-slop checklist, operational slop detection.",
+  "version": "0.4.4",
+  "description": "Thin self-review hooks for Cursor — the model is the auditor. Proactive intent compilation (pre-compile Anchor Set + per-turn .scope.json re-injection against Salience Dilution), intent-trace final review (Tier 0), unified 13-item anti-slop checklist, operational slop detection.",
   "bin": {
     "cursordoctrine": "bin/cli.mjs"
   },

package/windows/hooks/final-review.ps1

@@ -40,7 +40,8 @@ $cid = Get-SafeConversationId $obj
 $pendingDir = Get-HooksPendingDir
 $marker = Join-Path $pendingDir "session-edits-$cid.txt"
 $flag   = Join-Path $pendingDir "reviewed-$cid.flag"
-$anchorFlag = Join-Path $pendingDir "anchor-declared-$cid.flag"
+$anchorFlag  = Join-Path $pendingDir "anchor-declared-$cid.flag"
+$intentLatch = Join-Path $pendingDir "intent-injected-$cid.flag"
 
 # Sweep state from sessions that died before their stop hook ran. Cheap (one
 # directory listing on an event that fires once per agent loop).
@@ -48,14 +49,16 @@ Get-ChildItem $pendingDir -File -ErrorAction SilentlyContinue |
     Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-7) } |
     Remove-Item -Force -ErrorAction SilentlyContinue
 
-# Unconditionally clear the pre-compile nudge's per-turn latch. Every stop is a
-# turn boundary; clearing here (not only inside the reviewed-flag block below)
-# guarantees the nudge re-fires on the first edit of the NEXT turn and can never
-# get stranded silenced. The original design cleared anchor-declared-<cid>.flag
-# only on the SECOND stop (the reviewed-flag path), so any conversation that
-# never cleanly hit that boundary left the nudge permanently off - the agent
-# then stopped being reminded to write .scope.json.
-Remove-Item $anchorFlag -Force -ErrorAction SilentlyContinue
+# Unconditionally clear the per-turn latches so the next turn re-fires. Every
+# stop is a turn boundary; clearing here (not only inside the reviewed-flag
+# block below) guarantees these re-fire on the first edit/tool of the NEXT
+# turn and can never get stranded silenced mid-session:
+#   - anchor-declared-<cid>.flag  (anchor-set-nudge, first-edit reminder)
+#   - intent-injected-<cid>.flag  (intent-anchor, first-tool re-injection)
+# last-query-<cid>.hash is NOT cleared here - it must persist turn-to-turn so
+# intent-anchor can detect prompt changes; the 7-day sweep above reaps it when
+# a conversation truly dies.
+Remove-Item $anchorFlag, $intentLatch -Force -ErrorAction SilentlyContinue
 
 # One-shot brake: the previous stop for this conversation emitted the review.
 # Clear the flag (and whatever the review pass itself edited) and end the loop.

package/windows/hooks/intent-anchor.ps1

@@ -0,0 +1,208 @@
+# intent-anchor.ps1 - postToolUse "thin intent compilation" anchor (Cursor).
+#
+# Counteracts Salience Dilution: the failure mode where the agent's original
+# intent erodes as the conversation fills with code, logs and errors, until the
+# token of the original request is a rounding error against the recent history
+# and the agent drifts ("forgets" symmetry, colors, the .scope.json it wrote at
+# prompt 1). Two jobs, both on the FIRST tool boundary of each turn (per-turn
+# latch intent-injected-<cid>.flag, armed here, cleared at every stop):
+#
+#   1. RE-INJECT .scope.json (the core anti-dilution move): read the contract
+#      (intent + files + acceptance) and stash it in the feedback bus so
+#      post-tool-use.ps1 delivers it as additional_context at the next tool
+#      boundary. This puts the contract back in the model's attentional focus
+#      at the START of each turn's work, before edits pile up and dilute the
+#      original intent. Works UNCONDITIONALLY - no transcript needed.
+#
+#   2. RE-COMPILE ON PROMPT CHANGE: hash the current <user_query> (via
+#      Get-LastUserQuery, which reads the transcript) and compare to
+#      last-query-<cid>.hash. If they differ and a valid .scope.json exists,
+#      demand the agent UPDATE it. If no valid .scope.json exists and the query
+#      is available, WRITE a deterministic scaffold to disk (intent = query,
+#      files/acceptance = TODO placeholders) so re-injection always has real
+#      content from the first tool boundary — contract creation is not left to
+#      the LLM alone.
+#
+# Why postToolUse, not afterFileEdit: afterFileEdit only fires AFTER an edit
+# exists, and Cursor has no preToolUse for file edits. postToolUse fires after
+# EVERY tool (Read/Glob/Bash/Write/...), so its first fire of a turn is the
+# earliest moment the agent has begun working - typically right after the first
+# Read/Glob, before any edit. Best available injection point for "before files".
+#
+# Once per turn: latch armed on first fire, cleared UNCONDITIONALLY at every
+# stop (final-review.ps1). Cannot strand silenced mid-session (that was the
+# 0.4.0 bug). Registered first in the postToolUse array so it appends to the
+# feedback bus before post-tool-use.ps1 drains it (same-tool delivery; if an
+# updated install orders it after, delivery slips one tool - still correct).
+#
+# Advisory only: never blocks, never reads the diff, ALWAYS exits 0. Appends to
+# the shared feedback-<cid>.txt bus. Disable: HOOKS_ENFORCE=0 or INTENT_ANCHOR_ENFORCE=0.
+
+$ErrorActionPreference = 'SilentlyContinue'
+. "$PSScriptRoot\hook-common.ps1"
+
+if ($env:HOOKS_ENFORCE -eq '0' -or $env:INTENT_ANCHOR_ENFORCE -eq '0') { exit 0 }
+
+$obj = Read-HookStdinJson
+if (-not $obj) { exit 0 }
+
+$cid = Get-SafeConversationId $obj
+$pendingDir = Get-HooksPendingDir
+$latch    = Join-Path $pendingDir "intent-injected-$cid.flag"
+$hashFile = Join-Path $pendingDir "last-query-$cid.hash"
+
+# Already injected this turn -> quiet. Latch cleared at every stop.
+if (Test-Path $latch) { exit 0 }
+
+# --- current request (best-effort; absent in sandboxed runs) -----------------
+$currentQuery = Get-LastUserQuery $obj
+$hasQuery = -not [string]::IsNullOrWhiteSpace($currentQuery)
+
+$currentHash = ''
+$promptChanged = $false
+if ($hasQuery) {
+    $bytes  = [System.Text.Encoding]::UTF8.GetBytes($currentQuery)
+    $hasher = [System.Security.Cryptography.SHA256]::Create()
+    $currentHash = -join ($hasher.ComputeHash($bytes) | ForEach-Object { $_.ToString('x2') })
+    $prevHash = ''
+    if (Test-Path $hashFile) { $prevHash = (Get-Content $hashFile -Raw -ErrorAction SilentlyContinue).Trim() }
+    $promptChanged = ($currentHash -ne $prevHash)
+}
+
+# --- repo root (same resolution as scope-gate-audit.ps1) ---------------------
+$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('/') }
+
+# --- read the existing contract (if any) -------------------------------------
+$scopeExists = $false
+$scopeIntent = ''
+$scopeAcceptance = ''
+$scopeFiles = ''
+$scopePath = Join-Path $root '.scope.json'
+if (Test-Path -LiteralPath $scopePath) {
+    try {
+        $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 ', ') }
+        $scopeExists = $true
+    } catch { $scopeExists = $false }   # malformed JSON -> treat as missing
+}
+
+# --- deterministic scaffold (0.4.4) -----------------------------------------
+# When the query is available and there is no valid contract, the hook writes
+# .scope.json itself — intent from <user_query>, obvious TODO placeholders
+# for files/acceptance. Fires on prompt change (incl. first turn: empty prev
+# hash) or whenever the contract is still missing on a turn boundary.
+$scaffoldWritten = $false
+$shouldScaffold = $hasQuery -and (-not $scopeExists)
+if ($shouldScaffold) {
+    try {
+        $scaffold = [ordered]@{
+            intent       = $currentQuery
+            files        = @('<TODO: list files>')
+            acceptance   = '<TODO: deterministic success check>'
+            allow_growth = $false
+        }
+        $json = $scaffold | ConvertTo-Json -Depth 4 -Compress
+        $dir = Split-Path -Parent $scopePath
+        if ($dir -and -not (Test-Path -LiteralPath $dir)) {
+            New-Item -ItemType Directory -Path $dir -Force | Out-Null
+        }
+        [System.IO.File]::WriteAllText($scopePath, $json, [System.Text.UTF8Encoding]::new($false))
+        $scopeIntent = $currentQuery
+        $scopeAcceptance = '<TODO: deterministic success check>'
+        $scopeFiles = '<TODO: list files>'
+        $scopeExists = $true
+        $scaffoldWritten = $true
+    } catch { }
+}
+
+# --- compose the anchor message ---------------------------------------------
+# Re-injection (req 2) is unconditional whenever a contract exists.
+# Recompile-demand (req 1) fires when the prompt moved but a real contract exists.
+$queryLine = if ($hasQuery) { $currentQuery } else { '(current request unavailable - no transcript in this event)' }
+
+if ($scaffoldWritten) {
+    $msg = @"
+INTENT ANCHOR (scaffold written to .scope.json) - contract materialized from your request.
+
+  intent:     $scopeIntent
+  files:      $scopeFiles
+  acceptance: $scopeAcceptance
+
+The hook wrote this scaffold to $scopePath — intent is locked from your current
+request. Replace the TODO placeholders with real files[] and acceptance before
+editing source. The contract is on disk and will be re-injected every turn.
+"@
+} elseif (-not $scopeExists) {
+    $msg = @"
+INTENT ANCHOR (pre-compile) - no .scope.json found in $root.
+
+Current request:
+  $queryLine
+
+You have NOT compiled your Anchor Set. Before editing files, write .scope.json
+in the repo root:
+  intent:     one operational sentence (what is strictly necessary)
+  files:      the exact files you will touch
+  acceptance: the one deterministic check that decides done
+
+Compile it now, then proceed. The scope tracks the request - it is how you stay
+on the rails when the conversation gets long.
+"@
+} elseif ($promptChanged) {
+    $msg = @"
+INTENT ANCHOR (pre-compile) - your request changed; .scope.json may be stale.
+
+Current request:
+  $queryLine
+
+Your existing contract (.scope.json):
+  intent:     $scopeIntent
+  files:      $scopeFiles
+  acceptance: $scopeAcceptance
+
+If the current request differs from the intent above, UPDATE .scope.json now
+to match what was just asked. When the request moves, the scope moves with it -
+do not edit against a contract written for a different request.
+"@
+} else {
+    # Same prompt continuing (or query unavailable) -> re-inject the contract.
+    $driftNote = if ($hasQuery) {
+        "Every edit this turn must advance intent and stay inside files. acceptance is the bar for done."
+    } else {
+        "(request unavailable to diff against - re-injecting the contract as-is.)"
+    }
+    $msg = @"
+INTENT ANCHOR (re-injected this turn from .scope.json) - your contract. Do not drift from it.
+
+  intent:     $scopeIntent
+  files:      $scopeFiles
+  acceptance: $scopeAcceptance
+
+$driftNote If a constraint above conflicts with what you are about to do, stop
+and reconcile - the contract outranks momentum.
+"@
+}
+
+# --- stash to the feedback bus (drained by post-tool-use.ps1) ----------------
+$pending = Join-Path $pendingDir "feedback-$cid.txt"
+try {
+    New-Item -ItemType Directory -Path $pendingDir -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 { }
+
+# --- arm the latch; record the query hash for next-turn change detection -----
+New-Item -ItemType File -Path $latch -Force -ErrorAction SilentlyContinue | Out-Null
+if ($currentHash) {
+    try { Set-Content -Path $hashFile -Value $currentHash -NoNewline -ErrorAction SilentlyContinue } catch { }
+}
+
+exit 0

package/windows/hooks/subagent-stop-review.ps1

@@ -43,12 +43,13 @@ $cid = Get-SafeConversationId $obj
 $pendingDir = Get-HooksPendingDir
 $marker = Join-Path $pendingDir "session-edits-$cid.txt"
 $flag   = Join-Path $pendingDir "reviewed-$cid.flag"
-$anchorFlag = Join-Path $pendingDir "anchor-declared-$cid.flag"
+$anchorFlag  = Join-Path $pendingDir "anchor-declared-$cid.flag"
+$intentLatch = Join-Path $pendingDir "intent-injected-$cid.flag"
 
-# Unconditionally clear the pre-compile nudge's per-turn latch so it re-fires
-# on the first edit of the next subagent run. Clearing here (not only inside
-# the reviewed-flag block below) can never strand the nudge silenced.
-Remove-Item $anchorFlag -Force -ErrorAction SilentlyContinue
+# Unconditionally clear the per-turn latches so the next subagent run re-fires.
+# Clearing here (not only inside the reviewed-flag block below) can never strand
+# them silenced. last-query-<cid>.hash is kept (cross-turn prompt-change detect).
+Remove-Item $anchorFlag, $intentLatch -Force -ErrorAction SilentlyContinue
 
 # One-shot brake: the previous subagentStop for this id emitted the review.
 if (Test-Path $flag) {

package/windows/hooks.json

@@ -47,6 +47,11 @@
       }
     ],
     "postToolUse": [
+      {
+        "command": "pwsh.exe -NoProfile -File ~/.agents/hooks/intent-anchor.ps1",
+        "timeout": 5,
+        "_comment": "5s: THIN INTENT COMPILATION (anti Salience Dilution). Registered FIRST so it appends to the feedback bus before post-tool-use.ps1 drains it (same-tool delivery). On the FIRST tool boundary of each turn (per-turn latch intent-injected-<cid>.flag, cleared unconditionally at every stop), (1) re-injects the existing .scope.json (intent/files/acceptance) into additional_context so the contract is back in the model's attentional focus before edits pile up - UNCONDITIONAL, no transcript needed; (2) if the current <user_query> hash differs from last-query-<cid>.hash, demands the agent UPDATE .scope.json to match the new request (scope tracks the request). No .scope.json -> demand one be written. Needs transcript_path for change-detection; degrades to silent there but re-injection still runs. Advisory only; never blocks. Disable: HOOKS_ENFORCE=0 or INTENT_ANCHOR_ENFORCE=0."
+      },
       {
         "command": "pwsh.exe -NoProfile -File ~/.agents/hooks/post-tool-use.ps1",
         "timeout": 5,