cursordoctrine 0.6.0 → 0.6.1

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/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.
@@ -113,6 +116,7 @@ scope_acceptance=""
 scope_files=""
 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
@@ -146,8 +150,17 @@ EOF
     #     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 [ -n "$on_disk_hash" ]; 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
@@ -158,34 +171,29 @@ EOF
 fi
 
 # --- 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."
+# 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.
-    # 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
+    # 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
@@ -273,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

@@ -65,6 +65,17 @@ hook scaffolds on a tool boundary), just proceed — you do not need to hand-wri
 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
 
 If, during execution, you read logs or code that contradict these anchors,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursordoctrine",
-  "version": "0.6.0",
+  "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/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/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
@@ -112,6 +116,7 @@ $scopeFiles = ''
 $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 {
@@ -122,6 +127,12 @@ if (Test-Path -LiteralPath $scopePath) {
         if ([string]::IsNullOrWhiteSpace($scopeFiles)) { $scopeFiles = '(none yet - auto-tracked as you edit)' }
         $scopeExists = $true
         $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
@@ -133,7 +144,10 @@ if (Test-Path -LiteralPath $scopePath) {
         #     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) {
+            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
@@ -145,22 +159,25 @@ if (Test-Path -LiteralPath $scopePath) {
 }
 
 # --- 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."
+# 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>' }
-        $traceQuery = if ($hasQuery) { $currentQuery } else { '' }
+        $intentVal  = $currentQuery
+        $traceQuery = $currentQuery
         $scaffold = [ordered]@{
             intent        = $intentVal
             files         = @()
@@ -220,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

@@ -65,6 +65,17 @@ hook scaffolds on a tool boundary), just proceed — you do not need to hand-wri
 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
 
 If, during execution, you read logs or code that contradict these anchors,