cursordoctrine 0.5.5 → 0.6.1

package/bin/cli.mjs

@@ -408,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/USER-RULES.md

@@ -1,12 +1,45 @@
-Doctrine (governing text) lives at ~/.cursor/doctrine.md and is loaded
-at sessionStart. Read it once, internalize it; do not re-read it
-mid-task. Its §1 (auditor), §2 (smallest correct diff), §3 (verify
-then stop), §5 (ask don't guess), §8 (consistency anchor) are the only
-meta-instructions that matter during a session.
-
-When responding: be terse. No preamble, no postamble, no "I will now…".
-One sharp clarifying question if the task is ambiguous, then proceed.
-Reference code with `file_path:line_number` style.
-
-Do not re-load skills, do not re-read the doctrine, do not run
-gratuitous commands. If the answer is "I don't know", say so.
+The user is a senior engineer who reviews every diff before shipping.
+
+## Scope
+Change only what the task requires. Preserve existing style and behavior unless
+the task itself is a behavior change. Refactors, renames, cleanup only when
+asked. Leave generated files alone unless explicitly required.
+
+## Intent contract (.scope.json)
+The harness auto-creates `.scope.json` in the repo root on your first tool of
+each turn, and re-injects it into your context every turn. Treat it as your
+operating contract, not optional:
+- On a fresh scaffold, FILL the `intent` and `acceptance` TODOs from the user's
+  request before editing source. `files[]` is auto-tracked - do not maintain it.
+- When the user's request changes, the scaffold regenerates with a new intent -
+  refill it for the new ask.
+- If a hook surfaces the contract, defer to it: it outranks momentum. Edit
+  inside the declared scope; if you must grow it, justify it, don't sneak past.
+
+## Loop
+1. Read what you need to understand the task.
+2. Make the minimal correct edit.
+3. Review the diff. Fix real issues: broken logic, type errors, unsafe
+   behavior, data-loss risk, unrequested API/contract changes, regressions.
+   Style and naming taste are not bugs.
+4. Verify proportionally to risk - relevant tests/typechecks for behavior, type,
+   API, DB, build, or config changes; nothing for trivial text edits.
+5. Report what changed and what was verified. Stop.
+
+## Shell
+Run the smallest command that answers the question. Never print secrets,
+tokens, private keys, or sensitive env vars. Never `curl | sh`, force-push, or
+publish without explicit instruction.
+
+## Uncertainty
+If ambiguity affects correctness or safety, ask one sharp question. If
+low-risk, state the assumption and proceed. If a tool returns nothing, say what
+you didn't find - don't fabricate. After two failed attempts at the same
+problem, stop and report observations.
+
+## Commits
+Conventional commits: `type(scope): description`. One logical change per
+commit, small and reviewable. Body only when the why isn't obvious from the
+diff. Verify before pushing when applicable. Never push without explicit
+instruction.
+

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

@@ -15,16 +15,19 @@
 #      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.sh fills it
-#      mechanically as the agent edits - the agent never maintains files[] by
-#      hand), acceptance as a TODO the agent sets. This is the user-requested
-#      behavior: every new prompt -> a fresh .scope.json the agent works from.
-#      Fixed vs the broken 0.4.4 build: never writes to $HOME (bails if no real
-#      root resolves -> no ghost files), regenerates on prompt CHANGE not just
-#      on absence.
+#   2. AUTO-CREATE / REGENERATE .scope.json (only when the request is READABLE):
+#      when the current <user_query> differs from the contract on disk (no
+#      contract yet, _intent_hash mismatch, OR a hollow <TODO> placeholder), the
+#      hook WRITES a scaffold to the REPO ROOT: intent locked from the prompt,
+#      files as an EMPTY array (scope-gate-audit.sh fills it mechanically as the
+#      agent edits - the agent never maintains files[] by hand), acceptance as a
+#      TODO the agent sets. We NEVER persist a hollow `intent: <TODO>` file: that
+#      caused "el .scope.json se escribe solo sin nada" - when transcript_path is
+#      absent on postToolUse the hook can't read the request, so a placeholder
+#      with an empty _intent_hash got written, looked owned, and never gained the
+#      real intent. Unreadable request -> write nothing, emit the pre-compile
+#      demand so the AGENT authors the contract. Never writes to $HOME (bails if
+#      no real root resolves -> no ghost files).
 #   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.
@@ -111,7 +114,10 @@ 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
+scope_hollow=0   # 1 when the on-disk contract has no real intent (empty or a <TODO> placeholder) -> unusable
+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).
@@ -137,50 +143,72 @@ 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.
+    # Hollow = no real intent on disk: empty, or still the hook's <TODO> placeholder.
+    # A hollow contract is worse than none (it looks owned, so neither hook nor agent
+    # fills it). Treat it as unusable: regenerate when the request is readable, else
+    # hand the agent the pre-compile demand to author a real one.
+    case "$scope_intent" in
+        ""|"<TODO"*) scope_hollow=1 ;;
+    esac
+    if [ "$scope_exists" = "1" ] && [ "$has_query" = "1" ]; then
+        if [ "$scope_hollow" = "1" ]; then
+            scope_stale=1
+        elif [ -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 -----------------------------------
-# CREATION does NOT require the query: if there's a root and no scope yet,
-# scaffold it NOW with intent=<TODO> (the agent fills it from the chat it's
-# already responding to). This was the 0.5.3 bug - creation was gated on
-# $hasQuery, so when Cursor didn't surface transcript_path in the first
-# postToolUse fire, the scope never got created.
-# REGENERATION does require the query: we can only detect a prompt change if
-# we can hash the current request. Without a query we leave an existing scope
-# alone (re-inject it) rather than blank it.
+# --- auto-create / regenerate / heal .scope.json ----------------------------
+# CREATION and REGENERATION both REQUIRE the query. We only ever write a
+# contract whose intent we actually know - never a hollow <TODO> scaffold.
+# Persisting a placeholder (the 0.5.3 "unconditional creation") caused "el
+# .scope.json se escribe solo sin nada": no transcript_path on postToolUse ->
+# the hook can't read the request -> intent=<TODO> with empty _intent_hash, a
+# file that looks owned and never gains the real intent. Unreadable request ->
+# write nothing, emit the pre-compile demand so the AGENT authors the contract.
+# A fresh write resets files[] -> ".scope fresco por prompt, sin arrastre."
+# (Hollow on-disk contracts are folded into $scope_stale above, so a readable
+# request also overwrites them here.)
 regenerated=0
 should_create=0
 should_regen=0
-[ "$scope_exists" != "1" ] && should_create=1
+[ "$scope_exists" != "1" ] && [ "$has_query" = "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_create" = "1" ] || [ "$should_regen" = "1" ]; then
-    # intent from the query when available, else a TODO for the agent to fill.
-    if [ "$has_query" = "1" ]; then
-        intent_val="$current_query"
-    else
-        intent_val="<TODO: state the operational objective - what is strictly necessary>"
-    fi
-    # jq preferred; python3 fallback. Write intent, empty files[], TODO
-    # acceptance, and record _intent_hash so staleness is self-contained.
+    # Both paths require $has_query, so intent is always locked from the request.
+    intent_val="$current_query"
+    trace_query="$current_query"
+    # 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 "$intent_val" --arg hash "$current_hash" \
-            '{intent:$intent, files:[], acceptance:"<TODO: the one deterministic check that decides done>", allow_growth:false, _intent_hash:$hash, _generated_by:"intent-anchor hook"}' \
+        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="$intent_val" 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",
 }
@@ -199,6 +227,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)"
@@ -224,17 +281,25 @@ is locked from what you just asked. files[] is AUTO-TRACKED - the scope hook
 records every file you edit, so do not maintain it by hand. Set acceptance to
 the one deterministic check that decides done, THEN proceed. This contract will
 be re-injected every turn until your request changes again."
-elif [ "$scope_exists" != "1" ]; then
-    msg="INTENT ANCHOR (pre-compile) - no .scope.json found in $root, and the current
-request was unavailable to scaffold from.
+elif [ "$scope_exists" != "1" ] || [ "$scope_hollow" = "1" ]; then
+    if [ "$scope_hollow" = "1" ]; then
+        state="the .scope.json in $root is only a <TODO> placeholder (the hook could not read your request to fill it)"
+    else
+        state="no .scope.json found in $root, and the current request was unavailable to scaffold from"
+    fi
+    msg="INTENT ANCHOR (pre-compile) - $state.
 
 Current request:
   $query_line
 
-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"
+YOU write the real contract to $scope_path now, from THIS conversation, BEFORE
+editing source. Do not leave the <TODO> placeholder:
+  intent:     one operational sentence - the ACTUAL request (not \"<TODO>\")
+  acceptance: the one deterministic check that decides done
+  files:      [] (leave empty - the scope hook records every file you edit)
+
+This is the one case where you own the file: once intent is real, the hook
+takes over (re-injection + per-prompt regeneration)."
 else
     # Contract exists and matches the current prompt -> re-inject it.
     if [ "$has_query" = "1" ]; then

package/linux/pre-compile.md

@@ -29,29 +29,52 @@ 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.
+
+**Exception — a hollow contract is YOURS to write.** The hook can only lock
+`intent` when the harness surfaces your request to it; in some Cursor builds it
+cannot, and the `intent-anchor` hook will then ask YOU to author the contract (or
+you may open `.scope.json` and find `intent` still a `<TODO>` placeholder). In
+that one case, write the whole file yourself from this conversation — a real
+`intent` (the actual request, not `<TODO>`), `acceptance`, and `files: []` — and
+do it BEFORE editing source. Never leave a `<TODO>` intent on disk: a placeholder
+contract looks owned, so nothing ever fills it, and scope-gate/final-review then
+audit your diff against nothing. Once `intent` is real, hand the file back to the
+hook (re-injection + per-prompt regeneration take over).
 
 ## Regla R3 — Authority
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursordoctrine",
-  "version": "0.5.5",
+  "version": "0.6.1",
   "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/USER-RULES.md

@@ -1,12 +1,45 @@
-Doctrine (governing text) lives at ~/.cursor/doctrine.md and is loaded
-at sessionStart. Read it once, internalize it; do not re-read it
-mid-task. Its §1 (auditor), §2 (smallest correct diff), §3 (verify
-then stop), §5 (ask don't guess), §8 (consistency anchor) are the only
-meta-instructions that matter during a session.
-
-When responding: be terse. No preamble, no postamble, no "I will now…".
-One sharp clarifying question if the task is ambiguous, then proceed.
-Reference code with `file_path:line_number` style.
-
-Do not re-load skills, do not re-read the doctrine, do not run
-gratuitous commands. If the answer is "I don't know", say so.
+The user is a senior engineer who reviews every diff before shipping.
+
+## Scope
+Change only what the task requires. Preserve existing style and behavior unless
+the task itself is a behavior change. Refactors, renames, cleanup only when
+asked. Leave generated files alone unless explicitly required.
+
+## Intent contract (.scope.json)
+The harness auto-creates `.scope.json` in the repo root on your first tool of
+each turn, and re-injects it into your context every turn. Treat it as your
+operating contract, not optional:
+- On a fresh scaffold, FILL the `intent` and `acceptance` TODOs from the user's
+  request before editing source. `files[]` is auto-tracked - do not maintain it.
+- When the user's request changes, the scaffold regenerates with a new intent -
+  refill it for the new ask.
+- If a hook surfaces the contract, defer to it: it outranks momentum. Edit
+  inside the declared scope; if you must grow it, justify it, don't sneak past.
+
+## Loop
+1. Read what you need to understand the task.
+2. Make the minimal correct edit.
+3. Review the diff. Fix real issues: broken logic, type errors, unsafe
+   behavior, data-loss risk, unrequested API/contract changes, regressions.
+   Style and naming taste are not bugs.
+4. Verify proportionally to risk - relevant tests/typechecks for behavior, type,
+   API, DB, build, or config changes; nothing for trivial text edits.
+5. Report what changed and what was verified. Stop.
+
+## Shell
+Run the smallest command that answers the question. Never print secrets,
+tokens, private keys, or sensitive env vars. Never `curl | sh`, force-push, or
+publish without explicit instruction.
+
+## Uncertainty
+If ambiguity affects correctness or safety, ask one sharp question. If
+low-risk, state the assumption and proceed. If a tool returns nothing, say what
+you didn't find - don't fabricate. After two failed attempts at the same
+problem, stop and report observations.
+
+## Commits
+Conventional commits: `type(scope): description`. One logical change per
+commit, small and reviewable. Body only when the why isn't obvious from the
+diff. Verify before pushing when applicable. Never push without explicit
+instruction.
+

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,18 +14,22 @@
 #      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 .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
+#   2. AUTO-CREATE .scope.json (only when the request is READABLE): if no valid
+#      contract exists and we can read <user_query>, WRITE one now with intent
+#      locked from the query. We NEVER persist a hollow `intent: <TODO>` file:
+#      that 0.5.3 "unconditional creation" caused "el .scope.json se escribe
+#      solo sin nada" - when Cursor doesn't surface transcript_path on
+#      postToolUse the hook can't read the request, so it wrote a placeholder
+#      with an empty _intent_hash. The file then looks owned (pre-compile.md
+#      tells the agent to leave it alone) and never gets the real intent. When
+#      the request is unreadable we write nothing and emit the pre-compile
+#      demand so the AGENT authors a real contract from the chat it already has.
+#   3. REGENERATE on prompt CHANGE or HOLLOW contract: when the current
+#      <user_query> hash differs from the contract's _intent_hash, OR the
+#      on-disk contract has no real intent (empty / <TODO> placeholder),
+#      overwrite it with the new intent + empty files + TODO acceptance.
+#      Requires $hasQuery (you can only lock intent if you can read the
+#      request). 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
@@ -109,7 +113,10 @@ $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
+$scopeHollow = $false   # true when the on-disk contract has no real intent (empty or a <TODO> placeholder) -> unusable
 $scopePath = Join-Path $root '.scope.json'
 if (Test-Path -LiteralPath $scopePath) {
     try {
@@ -119,40 +126,68 @@ 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))
+        # Hollow = no real intent on disk: empty, or still the hook's <TODO> placeholder.
+        # A hollow contract is worse than none (it looks owned, so neither hook nor agent
+        # fills it; scope-gate appends files to it and final-review audits against <TODO>).
+        # Treat it as unusable: regenerate when we can read the request, else hand the agent
+        # the pre-compile demand to write a real one.
+        $scopeHollow = ([string]::IsNullOrWhiteSpace($scopeIntent) -or $scopeIntent -match '^\s*<TODO')
+        # 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 ($scopeHollow) {
+                # Hollow + we can read the request -> overwrite with the real intent now.
+                $scopeStale = $true
+            } elseif ($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 -----------------------------------
-# CREATION does NOT require the query: if there's a root and no scope yet,
-# scaffold it NOW with intent=<TODO> (the agent fills it from the chat it's
-# already responding to). This was the 0.5.3 bug - creation was gated on
-# $hasQuery, so when Cursor didn't surface transcript_path in the first
-# postToolUse fire, the scope never got created. The agent never had a
-# contract to work from.
-# REGENERATION does require the query: we can only detect a prompt change if
-# we can hash the current request. Without a query we leave an existing scope
-# alone (re-inject it) rather than blank it.
+# --- auto-create / regenerate / heal .scope.json ----------------------------
+# CREATION and REGENERATION both REQUIRE the query. We only ever write a
+# contract whose intent we actually know - never a hollow <TODO> scaffold.
+# Persisting a placeholder file (the 0.5.3 "unconditional creation") was the
+# bug behind "el .scope.json se escribe solo sin nada": when Cursor doesn't
+# surface transcript_path on postToolUse, the hook can't read the request, so
+# it wrote intent=<TODO> with an empty _intent_hash. That file looks owned, so
+# pre-compile.md tells the agent to leave it alone, and it never gets the real
+# intent. When the request is unreadable we now write NOTHING and instead hand
+# the agent the pre-compile demand to author a real contract from the chat it
+# is already responding to. A fresh write resets files[] -> ".scope fresco por
+# prompt, sin arrastre entre features." (Hollow on-disk contracts are folded
+# into $scopeStale above, so a readable request also overwrites them here.)
 $regenerated = $false
-$shouldCreate = -not $scopeExists
+$shouldCreate = (-not $scopeExists) -and $hasQuery
 $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>' }
+        $intentVal  = $currentQuery
+        $traceQuery = $currentQuery
         $scaffold = [ordered]@{
             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     = $intentVal
         $scopeAcceptance = '<TODO: the one deterministic check that decides done>'
@@ -163,6 +198,26 @@ if ($shouldCreate -or $shouldRegen) {
     } 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.
@@ -182,18 +237,22 @@ records every file you edit, so do not maintain it by hand. Set acceptance to
 the one deterministic check that decides done, THEN proceed. This contract will
 be re-injected every turn until your request changes again.
 "@
-} elseif (-not $scopeExists) {
+} elseif (-not $scopeExists -or $scopeHollow) {
+    $state = if ($scopeHollow) { "the .scope.json in $root is only a <TODO> placeholder (the hook could not read your request to fill it)" } else { "no .scope.json found in $root, and the current request was unavailable to scaffold from" }
     $msg = @"
-INTENT ANCHOR (pre-compile) - no .scope.json found in $root, and the current
-request was unavailable to scaffold from.
+INTENT ANCHOR (pre-compile) - $state.
 
 Current request:
   $queryLine
 
-Write .scope.json in the repo root yourself:
-  intent:     one operational sentence (what is strictly necessary)
-  files:      the exact files you will touch
+YOU write the real contract to $scopePath now, from THIS conversation, BEFORE
+editing source. Do not leave the <TODO> placeholder:
+  intent:     one operational sentence - the ACTUAL request (not "<TODO>")
   acceptance: the one deterministic check that decides done
+  files:      [] (leave empty - the scope hook records every file you edit)
+
+This is the one case where you own the file: once intent is real, the hook
+takes over (re-injection + per-prompt regeneration).
 "@
 } else {
     # Contract exists and matches the current prompt -> re-inject it.

package/windows/pre-compile.md

@@ -29,29 +29,52 @@ 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.
+
+**Exception — a hollow contract is YOURS to write.** The hook can only lock
+`intent` when the harness surfaces your request to it; in some Cursor builds it
+cannot, and the `intent-anchor` hook will then ask YOU to author the contract (or
+you may open `.scope.json` and find `intent` still a `<TODO>` placeholder). In
+that one case, write the whole file yourself from this conversation — a real
+`intent` (the actual request, not `<TODO>`), `acceptance`, and `files: []` — and
+do it BEFORE editing source. Never leave a `<TODO>` intent on disk: a placeholder
+contract looks owned, so nothing ever fills it, and scope-gate/final-review then
+audit your diff against nothing. Once `intent` is real, hand the file back to the
+hook (re-injection + per-prompt regeneration take over).
 
 ## Regla R3 — Authority