cursordoctrine 0.4.3 → 0.4.6

package/README.md

@@ -100,8 +100,10 @@ Writing `.scope.json` once is not enough. As a conversation fills with code, log
 
 `intent-anchor` (`postToolUse`, registered first so it runs before `post-tool-use` drains the bus) does two things on the **first tool boundary of every turn** (per-turn latch, cleared unconditionally at each stop):
 
-1. **Re-inject the contract.** Reads `.scope.json` and stashes `intent` + `files` + `acceptance` into the feedback bus, which `post-tool-use` delivers as `additional_context`. The contract is back in the model's attentional focus at the start of each turn's work — **before** edits pile up and dilute it. This runs unconditionally (no transcript needed); it's the core anti-dilution move.
-2. **Re-compile on prompt change.** Hashes the current `<user_query>` and compares to the previous turn's hash (`last-query-<cid>.hash`, which persists across turns). If the request moved, it demands the agent **update** `.scope.json` to match — the scope tracks the request. If no `.scope.json` exists, it demands one be written. (Needs `transcript_path` in the payload; if absent this part degrades to silent but the re-injection still runs.)
+1. **Materialize the contract per prompt.** When the current `<user_query>` differs from the contract on disk (no contract yet, or its recorded `_intent_hash` doesn't match), the hook **writes a fresh `.scope.json` to the repo root**: `intent` locked from the prompt, `files`/`acceptance` as `<TODO>` placeholders the agent fills in. Every new prompt → a fresh contract the agent works from. Same prompt → no rewrite.
+2. **Re-inject the contract every turn.** Reads `.scope.json` and stashes `intent` + `files` + `acceptance` into the feedback bus, which `post-tool-use` delivers as `additional_context`. The contract is back in the model's attentional focus at the start of each turn, before edits pile up and dilute it.
+
+> **The hook writes `.scope.json` deliberately.** This is the intended behavior: the contract must exist *before* the agent edits, and it must track the request. The agent fills the `<TODO>` placeholders (`files`, `acceptance`) on the first turn; the hook regenerates the scaffold when the prompt changes. Two real bugs in the earlier 0.4.4 build are fixed here: (a) **never writes to `$HOME`** — if the repo `cwd` can't be resolved the hook stays silent rather than drop a ghost file (bail instead of fallback); (b) **regenerates on prompt CHANGE, not on every turn** — staleness is tracked via `_intent_hash` stored in the file itself, so a same-prompt turn re-injects without rewriting.
 
 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.
 

package/bin/cli.mjs

@@ -17,6 +17,7 @@ import {
   readFileSync,
   readdirSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
@@ -74,6 +75,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,45 +321,84 @@ function verify() {
     return true;
   });
 
-  check('intent-anchor re-injects .scope.json every turn; latch re-arms at stop', () => {
-    // intent-anchor appends to feedback-<cid>.txt (the shared bus); drain via
-    // post-tool-use the same way the harness delivers additional_context.
+  check('intent-anchor scaffolds .scope.json per-prompt, never to $HOME', () => {
+    // The user-requested behavior: every NEW prompt -> a fresh .scope.json
+    // in the repo root, intent locked from the query. Same prompt -> re-inject
+    // without rewriting. Never writes to $HOME (the 0.4.4 ghost-file bug).
+    // We drive it with a synthetic transcript so Get-LastUserQuery can read
+    // the <user_query>; the hook resolves cwd -> HOME (the repo root here).
     const drainedOf = (cidv) => runHook(hook('post-tool-use'), { conversation_id: cidv });
     const anchorCid = 'npxv4';
-    const scopePath = join(HOME, '.scope.json');
-
-    const cleanup = () => { try { rmSync(scopePath, { force: true }); } catch {} };
+    const repoDir = HOME;   // verify() runs under a pinned HOME; treat it as the repo
+    const scopePath = join(repoDir, '.scope.json');
+    const transcriptPath = join(HOME, '.cursor', '.hooks-pending', 'verify-transcript-npxv4.jsonl');
+    const q1 = 'fix grid symmetry and color tokens';
+    const q2 = 'now add dark mode support';
+
+    const cleanup = () => {
+      try { rmSync(scopePath, { force: true }); } catch {}
+      try { rmSync(transcriptPath, { force: true }); } catch {}
+    };
     cleanup();
-
-    // --- Case A: no .scope.json -> demand one be written --------------
-    runHook(hook('intent-anchor'), { conversation_id: anchorCid, cwd: HOME });
+    const writeTranscript = (q) =>
+      writeFileSync(transcriptPath,
+        JSON.stringify({ role: 'user', message: { content: `<user_query>${q}</user_query>` } }) + '\n',
+        'utf8');
+
+    // --- 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 });
     let d = drainedOf(anchorCid);
-    if (!d.includes('INTENT ANCHOR') || !d.includes('NOT compiled your Anchor Set')) {
-      cleanup(); return { ok: false, detail: 'no-scope branch did not demand compilation' };
+    if (!existsSync(scopePath)) {
+      cleanup(); return { ok: false, detail: 'scaffold was NOT written on first prompt' };
+    }
+    let scope;
+    try { scope = JSON.parse(readFileSync(scopePath, 'utf8')); }
+    catch { cleanup(); return { ok: false, detail: '.scope.json is not valid JSON' }; }
+    if (scope.intent !== q1) {
+      cleanup(); return { ok: false, detail: `intent mismatch (want "${q1}"): ${scope.intent}` };
+    }
+    if (!d.includes('scope regenerated')) {
+      cleanup(); return { ok: false, detail: 'regenerated branch did not fire' };
     }
 
-    // --- Stop clears the latch (the regression path from 0.4.1) -------
+    // --- Stop clears the latch -> next turn can act again --------------------
     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',
-    }));
-    // Turn 2 (no transcript in sandbox -> query unavailable -> re-inject branch).
-    runHook(hook('intent-anchor'), { conversation_id: anchorCid, cwd: HOME });
+    // --- Case B: same prompt q1 again -> re-INJECT, do NOT rewrite ----------
+    const sizeBefore = statSync(scopePath).size;
+    runHook(hook('intent-anchor'), { conversation_id: anchorCid, cwd: repoDir, 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' };
+    if (!d.includes('re-injected this turn')) {
+      cleanup(); return { ok: false, detail: 'same-prompt turn did not re-inject' };
+    }
+    // _intent_hash matches -> file must not have been regenerated. Intent still q1.
+    try { scope = JSON.parse(readFileSync(scopePath, 'utf8')); }
+    catch { cleanup(); return { ok: false, detail: '.scope.json corrupted on same-prompt turn' }; }
+    if (scope.intent !== q1) {
+      cleanup(); return { ok: false, detail: `same-prompt turn rewrote intent (should stay "${q1}"): ${scope.intent}` };
     }
 
-    // --- Stop clears the latch again; turn 3 must re-inject too -------
+    // --- Stop; new prompt q2 -> REGENERATE with q2 as intent ----------------
     runHook(hook('final-review'), { conversation_id: anchorCid, status: 'completed' });
-    runHook(hook('intent-anchor'), { conversation_id: anchorCid, cwd: HOME });
+    writeTranscript(q2);
+    runHook(hook('intent-anchor'), { conversation_id: anchorCid, cwd: repoDir, 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)' };
+    try { scope = JSON.parse(readFileSync(scopePath, 'utf8')); }
+    catch { cleanup(); return { ok: false, detail: '.scope.json corrupted on prompt-change turn' }; }
+    if (scope.intent !== q2) {
+      cleanup(); return { ok: false, detail: `prompt-change did not regenerate intent (want "${q2}"): ${scope.intent}` };
+    }
+    if (!d.includes('scope regenerated')) {
+      cleanup(); return { ok: false, detail: 'prompt-change turn did not report regeneration' };
+    }
+
+    // --- The anti-ghost-file guard: no .scope.json should ever exist at $HOME
+    //     level OUTSIDE the resolved repo. Here repo == HOME so this is moot,
+    //     but assert the file has the _generated_by marker (proof the hook wrote
+    //     it, and that it carries _intent_hash for self-contained staleness).
+    if (!scope._generated_by || !scope._intent_hash) {
+      cleanup(); return { ok: false, detail: 'scaffold missing _generated_by / _intent_hash fields' };
     }
     cleanup();
     return true;

package/linux/hooks/intent-anchor.sh

@@ -15,14 +15,17 @@
 #      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, demand the agent UPDATE
-#      .scope.json to match the new request. If no .scope.json exists, demand
-#      one be written. The scope tracks the request - when the request moves,
-#      the scope moves with it. This part needs transcript_path in the payload;
-#      if it is absent the hook degrades to silent on change-detection but the
-#      re-injection above still runs.
+#   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.
+#   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.
 #
 # Why postToolUse, not afterFileEdit: afterFileEdit only fires AFTER an edit
 # exists, and Cursor has no preToolUse for file edits. postToolUse fires after
@@ -74,7 +77,10 @@ if [ "$has_query" = "1" ]; then
     [ "$current_hash" != "$prev_hash" ] && prompt_changed=1
 fi
 
-# --- repo root (same resolution as scope-gate-audit.sh) ----------------------
+# --- repo root (same resolution as scope-gate-audit.sh, but NO $HOME fallback) -
+# We do NOT fall back to $HOME: writing .scope.json into $HOME was the 0.4.4
+# "ghost file" bug. If we cannot resolve a real project root, the hook stays
+# silent (no scaffold, no demand) rather than litter the user's home dir.
 root=""
 while IFS= read -r cand; do
     [ -n "$cand" ] && [ -d "$cand" ] && { root="${cand%/}"; break; }
@@ -82,14 +88,18 @@ done <<EOF
 $(json_get "$input" cwd)
 $(json_get_array "$input" workspace_roots)
 EOF
-[ -n "$root" ] || root="${CURSOR_PROJECT_DIR:-$HOME}"
-root="${root%/}"
+if [ -z "$root" ] && [ -n "$CURSOR_PROJECT_DIR" ] && [ -d "$CURSOR_PROJECT_DIR" ]; then
+    root="${CURSOR_PROJECT_DIR%/}"
+fi
+# No $HOME fallback. If we still have no root, bail (cannot know where to write).
+[ -n "$root" ] || exit 0
 
 # --- read the existing contract (if any) -------------------------------------
 scope_exists=0
 scope_intent=""
 scope_acceptance=""
 scope_files=""
+scope_stale=0   # 1 if on-disk contract predates the current query
 scope_path="$root/.scope.json"
 if [ -f "$scope_path" ]; then
     # Prefer jq; fall back to python3 (mirrors hook-common.sh degrade policy).
@@ -97,9 +107,10 @@ if [ -f "$scope_path" ]; 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)"
+        on_disk_hash="$(jq -r '._intent_hash // empty' "$scope_path" 2>/dev/null)"
         scope_exists=1
     elif have_py; then
-        read -r scope_intent scope_acceptance scope_files <<EOF
+        read -r scope_intent scope_acceptance scope_files on_disk_hash <<EOF
 $(python3 -c '
 import json, sys
 try:
@@ -107,51 +118,100 @@ try:
     print(d.get("intent","") or "")
     print(d.get("acceptance","") or "")
     print(", ".join(d.get("files",[]) or []))
+    print(d.get("_intent_hash","") or "")
 except Exception:
     sys.exit(1)
 ' "$scope_path" 2>/dev/null)
 EOF
         [ $? -eq 0 ] && scope_exists=1 || scope_exists=0
     fi
+    # Stale if we have a query AND the on-disk _intent_hash differs from it.
+    if [ "$scope_exists" = "1" ] && [ "$has_query" = "1" ] && [ -n "$on_disk_hash" ]; then
+        [ "$on_disk_hash" != "$current_hash" ] && scope_stale=1
+    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".
+regenerated=0
+should_write=0
+if [ "$has_query" = "1" ]; then
+    if [ "$scope_exists" != "1" ] || [ "$scope_stale" = "1" ]; then
+        should_write=1
+    fi
+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 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"}' \
+            > "$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 '
+import json, os
+obj = {
+    "intent": os.environ["I_INTENT"],
+    "files": ["<TODO: list files you will touch>"],
+    "acceptance": "<TODO: the one deterministic check that decides done>",
+    "allow_growth": False,
+    "_intent_hash": os.environ["I_HASH"],
+    "_generated_by": "intent-anchor hook",
+}
+with open(os.environ["I_FILE"], "w", encoding="utf-8") as f:
+    json.dump(obj, f, ensure_ascii=False, indent=2)
+' 2>/dev/null; then
+            regenerated=1
+        fi
+    fi
+    if [ "$regenerated" = "1" ]; then
+        scope_intent="$current_query"
+        scope_acceptance="<TODO: the one deterministic check that decides done>"
+        scope_files="<TODO: list files you will touch>"
+        scope_exists=1
+        scope_stale=0
+    fi
 fi
 
 # --- 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.
 if [ "$has_query" = "1" ]; then
     query_line="$current_query"
 else
     query_line="(current request unavailable - no transcript in this event)"
 fi
 
-if [ "$scope_exists" != "1" ]; then
-    msg="INTENT ANCHOR (pre-compile) - no .scope.json found in $root.
+if [ "$regenerated" = "1" ]; then
+    msg="INTENT ANCHOR (scope regenerated) - .scope.json written for this prompt.
 
-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
+  intent:     $scope_intent
+  files:      $scope_files
+  acceptance: $scope_acceptance
 
-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.
+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."
+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.
 
 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."
+Write .scope.json in the repo root yourself:
+  intent:     one operational sentence (what is strictly necessary)
+  files:      the exact files you will touch
+  acceptance: the one deterministic check that decides done"
 else
-    # Same prompt continuing (or query unavailable) -> re-inject the contract.
+    # Contract exists and matches the current prompt -> re-inject it.
     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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cursordoctrine",
-  "version": "0.4.3",
-  "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.",
+  "version": "0.4.6",
+  "description": "Thin self-review hooks for Cursor — the model is the auditor. Proactive intent compilation (pre-compile Anchor Set + auto-scaffolded .scope.json that regenerates per prompt and re-injects every turn 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/intent-anchor.ps1

@@ -14,14 +14,17 @@
 #      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, demand the agent UPDATE
-#      .scope.json to match the new request. If no .scope.json exists, demand
-#      one be written. The scope tracks the request - when the request moves,
-#      the scope moves with it. This part needs transcript_path in the payload;
-#      if it is absent the hook degrades to silent on change-detection but the
-#      re-injection above still runs.
+#   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.
+#   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.
 #
 # Why postToolUse, not afterFileEdit: afterFileEdit only fires AFTER an edit
 # exists, and Cursor has no preToolUse for file edits. postToolUse fires after
@@ -70,18 +73,28 @@ if ($hasQuery) {
 }
 
 # --- repo root (same resolution as scope-gate-audit.ps1) ---------------------
+# Resolve cwd -> workspace_roots -> CURSOR_PROJECT_DIR. We do NOT fall back to
+# $HOME: writing .scope.json into $HOME was the 0.4.4 "ghost file" bug. If we
+# cannot resolve a real project root, the hook stays silent (no scaffold, no
+# demand) rather than litter the user's home directory.
 $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('/') }
+if (-not $root -and $env:CURSOR_PROJECT_DIR) {
+    $cpd = $env:CURSOR_PROJECT_DIR.Replace('\', '/').TrimEnd('/')
+    if (Test-Path -LiteralPath $cpd) { $root = $cpd }
+}
+# No $HOME fallback. If we still have no root, bail (cannot know where to write).
+if (-not $root) { exit 0 }
 
 # --- read the existing contract (if any) -------------------------------------
 $scopeExists = $false
 $scopeIntent = ''
 $scopeAcceptance = ''
 $scopeFiles = ''
+$scopeStale = $false   # true if the on-disk contract predates the current query
 $scopePath = Join-Path $root '.scope.json'
 if (Test-Path -LiteralPath $scopePath) {
     try {
@@ -90,48 +103,80 @@ if (Test-Path -LiteralPath $scopePath) {
         if ($sj.acceptance) { $scopeAcceptance = [string]$sj.acceptance }
         if ($sj.files)      { $scopeFiles = ($sj.files -join ', ') }
         $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
+        # so staleness survives even if last-query-<cid>.hash was swept.
+        if ($hasQuery -and $sj.PSObject.Properties['_intent_hash']) {
+            $scopeStale = ([string]$sj._intent_hash -ne $currentHash)
+        }
     } 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.
+$regenerated = $false
+$shouldWrite = $hasQuery -and (-not $scopeExists -or $scopeStale)
+if ($shouldWrite) {
+    try {
+        $scaffold = [ordered]@{
+            intent        = $currentQuery
+            files         = @('<TODO: list files you will touch>')
+            acceptance    = '<TODO: the one deterministic check that decides done>'
+            allow_growth  = $false
+            _intent_hash  = $currentHash
+            _generated_by = 'intent-anchor hook'
+        }
+        $json = $scaffold | ConvertTo-Json -Depth 5
+        [System.IO.File]::WriteAllText($scopePath, $json, [System.Text.UTF8Encoding]::new($false))
+        $scopeIntent     = $currentQuery
+        $scopeAcceptance = '<TODO: the one deterministic check that decides done>'
+        $scopeFiles      = '<TODO: list files you will touch>'
+        $scopeExists     = $true
+        $scopeStale      = $false
+        $regenerated     = $true
+    } catch { }   # write failed (perms / locked) -> fall through to demand msg
+}
+
 # --- compose the anchor message ---------------------------------------------
-# Re-injection (req 2) is unconditional whenever a contract exists.
-# Recompile-demand (req 1) fires when there is no contract, or the prompt moved.
+# Three states: regenerated this turn (new prompt), no contract (and no query
+# to scaffold from), or re-injecting an existing current contract.
 $queryLine = if ($hasQuery) { $currentQuery } else { '(current request unavailable - no transcript in this event)' }
 
-if (-not $scopeExists) {
+if ($regenerated) {
     $msg = @"
-INTENT ANCHOR (pre-compile) - no .scope.json found in $root.
-
-Current request:
-  $queryLine
+INTENT ANCHOR (scope regenerated) - .scope.json written for this prompt.
 
-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
+  intent:     $scopeIntent
+  files:      $scopeFiles
+  acceptance: $scopeAcceptance
 
-Compile it now, then proceed. The scope tracks the request - it is how you stay
-on the rails when the conversation gets long.
+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.
 "@
-} elseif ($promptChanged) {
+} elseif (-not $scopeExists) {
     $msg = @"
-INTENT ANCHOR (pre-compile) - your request changed; .scope.json may be stale.
+INTENT ANCHOR (pre-compile) - no .scope.json found in $root, and the current
+request was unavailable to scaffold from.
 
 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.
+Write .scope.json in the repo root yourself:
+  intent:     one operational sentence (what is strictly necessary)
+  files:      the exact files you will touch
+  acceptance: the one deterministic check that decides done
 "@
 } else {
-    # Same prompt continuing (or query unavailable) -> re-inject the contract.
+    # Contract exists and matches the current prompt -> re-inject it.
     $driftNote = if ($hasQuery) {
         "Every edit this turn must advance intent and stay inside files. acceptance is the bar for done."
     } else {