cursordoctrine 0.5.5 → 0.6.0

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/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

@@ -111,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).
@@ -137,21 +139,33 @@ 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 -----------------------------------
+# --- 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 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.
+# 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_create=0
 should_regen=0
@@ -159,28 +173,34 @@ should_regen=0
 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.
+    # 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, and record _intent_hash so staleness is self-contained.
+    # 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 +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.5",
+  "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.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

@@ -109,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 {
@@ -119,40 +121,56 @@ 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 -----------------------------------
+# --- 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 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.
+# 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
 $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>' }
+        $intentVal  = if ($hasQuery) { $currentQuery } else { '<TODO: state the operational objective - what is strictly necessary>' }
+        $traceQuery = if ($hasQuery) { $currentQuery } else { '' }
         $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 +181,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.

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