cursordoctrine 0.5.4 → 0.6.0

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 });
@@ -389,6 +408,56 @@ function verify() {
     if (!scope._generated_by || !scope._intent_hash) {
       cleanup(); return { ok: false, detail: 'scaffold missing _generated_by / _intent_hash fields' };
     }
+
+    // --- Case C: MODEL-written scope (no _intent_hash) + a NEW prompt --------
+    // Reproduces the shipped bug (chiquipuesto/WAVE): the model wrote .scope.json
+    // per the legacy 4-field schema, so the hook could never detect staleness and
+    // scope-gate kept appending files across features. A new prompt (fresh cid =>
+    // promptChanged) must now REGENERATE and RESET files[].
+    const mkT = (p, q) => writeFileSync(p,
+      JSON.stringify({ role: 'user', message: { content: `<user_query>${q}</user_query>` } }) + '\n', 'utf8');
+    const cidC = 'npxv5';
+    const transcriptC = join(HOME, '.cursor', '.hooks-pending', 'verify-transcript-npxv5.jsonl');
+    const failC = (detail) => { try { rmSync(transcriptC, { force: true }); } catch {} cleanup(); return { ok: false, detail }; };
+    try { rmSync(scopePath, { force: true }); } catch {}
+    writeFileSync(scopePath, JSON.stringify({ intent: q1, files: ['a.ts', 'b.ts'], acceptance: 'keep', allow_growth: false }, null, 2), 'utf8');
+    mkT(transcriptC, q2);
+    runHook(hook('intent-anchor'), { conversation_id: cidC, cwd: repoDir, transcript_path: transcriptC });
+    drainedOf(cidC);
+    let sc;
+    try { sc = JSON.parse(readFileSync(scopePath, 'utf8')); } catch { return failC('model-written scope corrupted after new prompt'); }
+    if (sc.intent !== q2) return failC(`carryover not regenerated (want "${q2}"): ${sc.intent}`);
+    if (!Array.isArray(sc.files) || sc.files.length !== 0) return failC(`files[] not reset on regen: ${JSON.stringify(sc.files)}`);
+    if (!sc._intent_hash) return failC('regen did not install _intent_hash');
+    if (!sc.trace || sc.trace.query !== q2) return failC('regen did not record trace.query');
+    runHook(hook('final-review'), { conversation_id: cidC, status: 'completed' });
+    rmSync(transcriptC, { force: true });
+
+    // --- Case D: MODEL-written scope (no _intent_hash) + the SAME prompt ------
+    // The model wrote the contract for THIS request this session. The hook must
+    // HEAL in place (backfill _intent_hash + trace) WITHOUT resetting files[] or
+    // acceptance, so the NEXT prompt change is detectable by hash.
+    const cidD = 'npxv6';
+    const transcriptD = join(HOME, '.cursor', '.hooks-pending', 'verify-transcript-npxv6.jsonl');
+    const failD = (detail) => { try { rmSync(transcriptD, { force: true }); } catch {} cleanup(); return { ok: false, detail }; };
+    try { rmSync(scopePath, { force: true }); } catch {}
+    mkT(transcriptD, q1);
+    // prime last-query-<cidD>.hash with q1 (a hook-written scaffold), clear the
+    // latch, then overwrite with a model-style scope for the SAME prompt.
+    runHook(hook('intent-anchor'), { conversation_id: cidD, cwd: repoDir, transcript_path: transcriptD });
+    runHook(hook('final-review'), { conversation_id: cidD, status: 'completed' });
+    writeFileSync(scopePath, JSON.stringify({ intent: q1, files: ['a.ts', 'b.ts'], acceptance: 'keep me', allow_growth: false }, null, 2), 'utf8');
+    runHook(hook('intent-anchor'), { conversation_id: cidD, cwd: repoDir, transcript_path: transcriptD });
+    drainedOf(cidD);
+    let sd;
+    try { sd = JSON.parse(readFileSync(scopePath, 'utf8')); } catch { return failD('healed scope corrupted'); }
+    if (!sd._intent_hash) return failD('heal did not backfill _intent_hash');
+    if (!sd.trace) return failD('heal did not add trace');
+    if (!Array.isArray(sd.files) || sd.files.join(',') !== 'a.ts,b.ts') return failD(`heal reset files[] (should preserve): ${JSON.stringify(sd.files)}`);
+    if (sd.acceptance !== 'keep me') return failD(`heal clobbered acceptance: ${sd.acceptance}`);
+    runHook(hook('final-review'), { conversation_id: cidD, status: 'completed' });
+    rmSync(transcriptD, { force: true });
+
     cleanup();
     return true;
   });

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/final-review.sh

@@ -110,7 +110,7 @@ body="$(expand_agent_paths "$body")"
 # wrong diff. Reset its prior to the Anchor Set, not to its previous attempt.
 reentry_line="
 
-RE-ENTRY RULE (Regla R1): if a gate or axis failed, forget the approach that produced it. Re-read your ORIGINAL REQUEST above and your Anchor Set (.scope.json, if you wrote one). Fix ONLY what is failing. Do not refactor in this pass - that is History Propagation, the exact failure mode the Anchor Set exists to prevent.
+RE-ENTRY RULE (Regla R1): if a gate or axis failed, forget the approach that produced it. Re-read your ORIGINAL REQUEST above and your Anchor Set (.scope.json, maintained by the intent-anchor hook). Fix ONLY what is failing. Do not refactor in this pass - that is History Propagation, the exact failure mode the Anchor Set exists to prevent.
 "
 
 file_list=""

package/linux/hooks/intent-anchor.sh

@@ -58,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
 
@@ -101,7 +111,9 @@ scope_exists=0
 scope_intent=""
 scope_acceptance=""
 scope_files=""
-scope_stale=0   # 1 if on-disk contract predates the current query
+scope_stale=0    # 1 when the on-disk contract belongs to a DIFFERENT prompt -> regenerate (resets files[])
+needs_heal=0     # 1 when a model-written contract matches THIS prompt but lacks _intent_hash -> backfill in place
+on_disk_hash=""
 scope_path="$root/.scope.json"
 if [ -f "$scope_path" ]; then
     # Prefer jq; fall back to python3 (mirrors hook-common.sh degrade policy).
@@ -127,42 +139,68 @@ except Exception:
 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
+    # Staleness, hash-agnostic so it survives MODEL-written contracts:
+    #   - hook-written (has _intent_hash): stale when that hash != current query hash.
+    #   - model-written (no _intent_hash - the legacy pre-compile.md schema): fall back to
+    #     $prompt_changed (current query hash != the per-conversation last-query hash). Prompt
+    #     changed (or a new session) => regenerate and RESET files[] (the "arrastre entre
+    #     features" fix). Same prompt this session => heal in place (backfill bookkeeping, keep
+    #     files[]/acceptance) so the NEXT prompt is detected by hash.
+    if [ "$scope_exists" = "1" ] && [ "$has_query" = "1" ]; then
+        if [ -n "$on_disk_hash" ]; then
+            [ "$on_disk_hash" != "$current_hash" ] && scope_stale=1
+        elif [ "$prompt_changed" = "1" ]; then
+            scope_stale=1
+        else
+            needs_heal=1
+        fi
     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 / heal .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 requires the query: a prompt change is only detectable when we
+# can read the request. A fresh scaffold resets files[] -> ".scope fresco por
+# prompt, sin arrastre entre features."
 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
+now_ts="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null)"
 
-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.
+    # trace.query records the verbatim originating request (provenance); empty
+    # when there is no transcript to read it from.
+    if [ "$has_query" = "1" ]; then
+        intent_val="$current_query"
+        trace_query="$current_query"
+    else
+        intent_val="<TODO: state the operational objective - what is strictly necessary>"
+        trace_query=""
+    fi
+    # jq preferred; python3 fallback. Write intent, empty files[], TODO acceptance,
+    # trace provenance, and _intent_hash so staleness is self-contained.
     if have_jq; then
-        jq -n --arg intent "$current_query" --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"}' \
+        jq -n --arg intent "$intent_val" --arg hash "$current_hash" --arg tq "$trace_query" --arg ts "$now_ts" \
+            '{intent:$intent, files:[], acceptance:"<TODO: the one deterministic check that decides done>", allow_growth:false, trace:{query:$tq, ts:$ts}, _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" I_TQ="$trace_query" I_TS="$now_ts" python3 -c '
 import json, os
 obj = {
     "intent": os.environ["I_INTENT"],
     "files": [],
     "acceptance": "<TODO: the one deterministic check that decides done>",
     "allow_growth": False,
+    "trace": {"query": os.environ["I_TQ"], "ts": os.environ["I_TS"]},
     "_intent_hash": os.environ["I_HASH"],
     "_generated_by": "intent-anchor hook",
 }
@@ -173,7 +211,7 @@ 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="(auto-tracked - the scope hook records every file you edit)"
         scope_exists=1
@@ -181,6 +219,35 @@ with open(os.environ["I_FILE"], "w", encoding="utf-8") as f:
     fi
 fi
 
+# HEAL a model-written contract that matches the current prompt but lacks the
+# hook's bookkeeping: backfill _intent_hash + trace + _generated_by IN PLACE,
+# preserving the model's files[] and acceptance. Without this a contract written
+# per the legacy pre-compile.md schema (no _intent_hash) can never go stale, so
+# the next prompt never regenerates - the carryover bug. Healing installs the
+# hash so the next prompt change is detected by hash like any hook contract.
+if [ "$needs_heal" = "1" ] && [ "$regenerated" != "1" ]; then
+    if have_jq; then
+        healed="$(jq --arg hash "$current_hash" --arg tq "$current_query" --arg ts "$now_ts" \
+            '._intent_hash = $hash | .trace //= {query:$tq, ts:$ts} | ._generated_by //= "intent-anchor hook (healed)"' \
+            "$scope_path" 2>/dev/null)"
+        [ -n "$healed" ] && printf '%s\n' "$healed" > "$scope_path"
+    elif have_py; then
+        I_FILE="$scope_path" I_HASH="$current_hash" I_TQ="$current_query" I_TS="$now_ts" python3 -c '
+import json, os, sys
+path = os.environ["I_FILE"]
+try:
+    d = json.load(open(path, encoding="utf-8"))
+except Exception:
+    sys.exit(0)
+d["_intent_hash"] = os.environ["I_HASH"]
+d.setdefault("trace", {"query": os.environ["I_TQ"], "ts": os.environ["I_TS"]})
+d.setdefault("_generated_by", "intent-anchor hook (healed)")
+with open(path, "w", encoding="utf-8") as f:
+    json.dump(d, f, ensure_ascii=False, indent=2)
+' 2>/dev/null
+    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)"

package/linux/pre-compile.md

@@ -29,29 +29,41 @@ Answer these four, terse, in your first response. One phrase each, not prose:
    specific failing test going green is. If you cannot name one, you do not
    yet understand the task — ask.
 
-## Materialize it: .scope.json
-
-Write the Anchor Set to `.scope.json` in the repo root before editing source.
-This is the machine-checkable form — the scope-gate hook audits every edit
-against `files[]`, and the final-review axis 0 traces every diff hunk back to
-`intent`. An Anchor Set that lives only in your head is not an Anchor Set.
+## Materialize it: .scope.json (the hook owns this file)
+
+The `intent-anchor` hook creates and maintains `.scope.json` in the repo root for
+you, automatically, on the first tool of every turn:
+  - `intent` is locked from your current request and REFRESHED when the request
+    changes — a new prompt regenerates the contract and resets `files[]`, so it
+    never carries over between features;
+  - `files[]` is auto-recorded — the scope hook appends every file you edit, so
+    you never maintain it by hand;
+  - `trace`, `_intent_hash`, `_generated_by` are hook bookkeeping (provenance and
+    change detection). Leave them alone.
+
+Your one job on the contract: set **`acceptance`** — the single deterministic check
+that decides done — which the hook cannot derive. Edit ONLY that field (a targeted
+string replace). Do **NOT** rewrite the whole file: overwriting it drops the hook's
+`_intent_hash`/`trace`, which disables per-prompt regeneration and brings back the
+cross-feature carryover. The scope-gate hook audits every edit against `files[]`,
+and final-review axis 0 traces every diff hunk back to `intent`.
 
 ```json
 {
-  "intent": "<OBJECTIVE>",
-  "files": ["<FILES TO TOUCH, repo-relative, glob-friendly>"],
-  "acceptance": "<DETERMINISTIC SUCCESS>",
-  "allow_growth": false
+  "intent":       "<locked from your request by the hook>",
+  "files":        ["<auto-recorded by the hook as you edit>"],
+  "acceptance":   "<YOU set this: the deterministic check that decides done>",
+  "allow_growth": false,
+  "trace":        { "query": "<originating request>", "ts": "<when>" },
+  "_intent_hash": "<hook bookkeeping>",
+  "_generated_by":"intent-anchor hook"
 }
 ```
 
-`allow_growth: false` is the default — the gate fires on any edit outside
-`files[]`. Set it true only if you expect the work to discover new files
-(a refactor, a migration) and you will justify each one as it appears.
-
-No need to write `.scope.json` for trivial one-liners (a typo, a literal).
-The declared-editing ladder's rung 1 ("does this need to exist?") governs when
-the Anchor Set itself is overkill. When in doubt, write it.
+`allow_growth: false` is the default. If the contract has not appeared yet (the
+hook scaffolds on a tool boundary), just proceed — you do not need to hand-write
+it. The declared-editing ladder's rung 1 ("does this need to exist?") still governs
+trivial one-liners.
 
 ## Regla R3 — Authority
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursordoctrine",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "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/skills/anti-slop/scripts/scope_match.py

@@ -8,12 +8,16 @@ declared-scope check (Step C), so the two never disagree on what counts as
 "in scope". It also surfaces the contract's `intent` and `acceptance` fields
 so the calling hook can quote them back to the agent.
 
-.scope.json schema (intent + files[] + acceptance + allow_growth):
+.scope.json schema (the intent-anchor hook owns this file; this matcher reads
+only intent/files/acceptance/allow_growth and ignores the hook bookkeeping):
   {
     "intent":       "one operational sentence of objective",
     "files":        [ "repo-relative globs", ... ],
     "acceptance":   "the deterministic check that decides success",
-    "allow_growth": false
+    "allow_growth": false,
+    "trace":        { "query": "originating request", "ts": "ISO-8601" },
+    "_intent_hash": "hook bookkeeping: sha256 of the request, drives per-prompt regen",
+    "_generated_by":"intent-anchor hook"
   }
 
 Pattern support:

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/final-review.ps1

@@ -119,7 +119,7 @@ $body = Expand-AgentPaths $body
 # Regla R1 (re-entry): if this review pass is a re-audit after a failed gate or
 # axis, suppress History Propagation - the model must NOT build on its own prior
 # wrong diff. Reset its prior to the Anchor Set, not to its previous attempt.
-$reentryLine = "`n`nRE-ENTRY RULE (Regla R1): if a gate or axis failed, forget the approach that produced it. Re-read your ORIGINAL REQUEST above and your Anchor Set (.scope.json, if you wrote one). Fix ONLY what is failing. Do not refactor in this pass - that is History Propagation, the exact failure mode the Anchor Set exists to prevent.`n"
+$reentryLine = "`n`nRE-ENTRY RULE (Regla R1): if a gate or axis failed, forget the approach that produced it. Re-read your ORIGINAL REQUEST above and your Anchor Set (.scope.json, maintained by the intent-anchor hook). Fix ONLY what is failing. Do not refactor in this pass - that is History Propagation, the exact failure mode the Anchor Set exists to prevent.`n"
 
 $resolved = @($edited | ForEach-Object { Resolve-AgentPath $_ })
 $fileList = ($resolved | Select-Object -First 30) -join "`n  "

package/windows/hooks/intent-anchor.ps1

@@ -14,17 +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 as an EMPTY array (scope-gate-audit.ps1 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
+#   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).
+#   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.
 #
@@ -56,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 }
 
@@ -96,7 +109,9 @@ $scopeExists = $false
 $scopeIntent = ''
 $scopeAcceptance = ''
 $scopeFiles = ''
-$scopeStale = $false   # true if the on-disk contract predates the current query
+$scopeStale = $false    # true when the on-disk contract belongs to a DIFFERENT prompt -> regenerate (resets files[])
+$needsHeal = $false     # true when a model-written contract matches THIS prompt but lacks _intent_hash -> backfill in place
+$scopeHasHash = $false
 $scopePath = Join-Path $root '.scope.json'
 if (Test-Path -LiteralPath $scopePath) {
     try {
@@ -106,39 +121,58 @@ if (Test-Path -LiteralPath $scopePath) {
         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
-        # 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)
+        $scopeHasHash = ($sj.PSObject.Properties['_intent_hash'] -and -not [string]::IsNullOrWhiteSpace([string]$sj._intent_hash))
+        # Staleness, hash-agnostic so it survives MODEL-written contracts:
+        #   - hook-written (has _intent_hash): stale when that hash != current query hash.
+        #   - model-written (no _intent_hash - the legacy pre-compile.md schema): we cannot
+        #     hash-compare, so fall back to $promptChanged (current query hash != the per-
+        #     conversation last-query hash). Prompt changed (or a new session) => stale ->
+        #     regenerate and RESET files[]; this is the "arrastre entre features" fix (a model-
+        #     written scope could never go stale, so it never refreshed and scope-gate kept
+        #     appending files across unrelated features). Same prompt this session => the model
+        #     wrote it for THIS request; heal in place (backfill the bookkeeping, keep its
+        #     files[]/acceptance) so the NEXT prompt is detected by hash like any hook contract.
+        if ($hasQuery) {
+            if ($scopeHasHash) {
+                $scopeStale = ([string]$sj._intent_hash -ne $currentHash)
+            } elseif ($promptChanged) {
+                $scopeStale = $true
+            } else {
+                $needsHeal = $true
+            }
         }
     } 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 starts EMPTY (scope-gate-audit
-# auto-records edits into it); acceptance is a TODO the agent sets. 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 / heal .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 requires the query: a prompt change is only detectable when we
+# can read the request. A fresh scaffold resets files[] -> ".scope fresco por
+# prompt, sin arrastre entre features."
 $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>' }
+        $traceQuery = if ($hasQuery) { $currentQuery } else { '' }
         $scaffold = [ordered]@{
-            intent        = $currentQuery
+            intent        = $intentVal
             files         = @()
             acceptance    = '<TODO: the one deterministic check that decides done>'
             allow_growth  = $false
+            trace         = [ordered]@{ query = $traceQuery; ts = (Get-Date).ToString('o') }
             _intent_hash  = $currentHash
             _generated_by = 'intent-anchor hook'
         }
-        $json = $scaffold | ConvertTo-Json -Depth 5
+        $json = $scaffold | ConvertTo-Json -Depth 8
         [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      = '(auto-tracked - the scope hook records every file you edit)'
         $scopeExists     = $true
@@ -147,6 +181,26 @@ if ($shouldWrite) {
     } catch { }   # write failed (perms / locked) -> fall through to demand msg
 }
 
+# HEAL a model-written contract that matches the current prompt but lacks the
+# hook's bookkeeping: backfill _intent_hash + trace + _generated_by IN PLACE,
+# preserving the model's files[] and acceptance. Without this, a contract written
+# per pre-compile.md (no _intent_hash) can never go stale, so the next prompt
+# never regenerates - the carryover bug. Healing installs the hash so the next
+# prompt change is detected by hash like any hook-written contract.
+if ($needsHeal -and -not $regenerated) {
+    try {
+        $ordered = [ordered]@{}
+        foreach ($p in $sj.PSObject.Properties) { $ordered[$p.Name] = $p.Value }
+        if (-not $ordered.Contains('trace')) {
+            $ordered['trace'] = [ordered]@{ query = $currentQuery; ts = (Get-Date).ToString('o') }
+        }
+        $ordered['_intent_hash'] = $currentHash
+        if (-not $ordered.Contains('_generated_by')) { $ordered['_generated_by'] = 'intent-anchor hook (healed)' }
+        $json = $ordered | ConvertTo-Json -Depth 8
+        [System.IO.File]::WriteAllText($scopePath, $json, [System.Text.UTF8Encoding]::new($false))
+    } catch { }
+}
+
 # --- 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.

package/windows/pre-compile.md

@@ -29,29 +29,41 @@ Answer these four, terse, in your first response. One phrase each, not prose:
    specific failing test going green is. If you cannot name one, you do not
    yet understand the task — ask.
 
-## Materialize it: .scope.json
-
-Write the Anchor Set to `.scope.json` in the repo root before editing source.
-This is the machine-checkable form — the scope-gate hook audits every edit
-against `files[]`, and the final-review axis 0 traces every diff hunk back to
-`intent`. An Anchor Set that lives only in your head is not an Anchor Set.
+## Materialize it: .scope.json (the hook owns this file)
+
+The `intent-anchor` hook creates and maintains `.scope.json` in the repo root for
+you, automatically, on the first tool of every turn:
+  - `intent` is locked from your current request and REFRESHED when the request
+    changes — a new prompt regenerates the contract and resets `files[]`, so it
+    never carries over between features;
+  - `files[]` is auto-recorded — the scope hook appends every file you edit, so
+    you never maintain it by hand;
+  - `trace`, `_intent_hash`, `_generated_by` are hook bookkeeping (provenance and
+    change detection). Leave them alone.
+
+Your one job on the contract: set **`acceptance`** — the single deterministic check
+that decides done — which the hook cannot derive. Edit ONLY that field (a targeted
+string replace). Do **NOT** rewrite the whole file: overwriting it drops the hook's
+`_intent_hash`/`trace`, which disables per-prompt regeneration and brings back the
+cross-feature carryover. The scope-gate hook audits every edit against `files[]`,
+and final-review axis 0 traces every diff hunk back to `intent`.
 
 ```json
 {
-  "intent": "<OBJECTIVE>",
-  "files": ["<FILES TO TOUCH, repo-relative, glob-friendly>"],
-  "acceptance": "<DETERMINISTIC SUCCESS>",
-  "allow_growth": false
+  "intent":       "<locked from your request by the hook>",
+  "files":        ["<auto-recorded by the hook as you edit>"],
+  "acceptance":   "<YOU set this: the deterministic check that decides done>",
+  "allow_growth": false,
+  "trace":        { "query": "<originating request>", "ts": "<when>" },
+  "_intent_hash": "<hook bookkeeping>",
+  "_generated_by":"intent-anchor hook"
 }
 ```
 
-`allow_growth: false` is the default — the gate fires on any edit outside
-`files[]`. Set it true only if you expect the work to discover new files
-(a refactor, a migration) and you will justify each one as it appears.
-
-No need to write `.scope.json` for trivial one-liners (a typo, a literal).
-The declared-editing ladder's rung 1 ("does this need to exist?") governs when
-the Anchor Set itself is overkill. When in doubt, write it.
+`allow_growth: false` is the default. If the contract has not appeared yet (the
+hook scaffolds on a tool boundary), just proceed — you do not need to hand-write
+it. The declared-editing ladder's rung 1 ("does this need to exist?") still governs
+trivial one-liners.
 
 ## Regla R3 — Authority