cursordoctrine 0.6.2 → 0.6.4

package/linux/doctrine.md

@@ -69,6 +69,10 @@ what the task requires**.
 
 The natural order is:
 
+  0. **Restate** the request in one normalized line (`Understood as: …`) before
+     you touch a tool — grammar fixed, ambiguity resolved, meaning preserved.
+     It is the user's catch-point for a misread, and it becomes the contract's
+     `intent`. Full spec in pre-compile.
   1. **Read** the relevant file(s) to understand context.
   2. **Edit** to make the change.
   3. **Read** the file again (the self-review trigger will remind you).

package/linux/hooks/hook-common.sh

@@ -105,7 +105,7 @@ resolve_agent_path() {
     esac
 }
 
-# extract_last_user_query <json> -> text of the last <user_query> in this
+# extract_last_user_query <json> -> text of the last *human* <user_query> in this
 # conversation's transcript, or '' if there is none. Capped at 2000 chars.
 #
 # This is the Tier 0 intent-trace primitive: the final-review hook prepends the
@@ -113,7 +113,14 @@ resolve_agent_path() {
 # to it. Anything untraceable is a hallucinated requirement.
 #
 # Walks the JSONL backward via tac (preferred) or a portable awk fallback; finds
-# the first (last) user record whose content carries a <user_query> tag.
+# the first (last) user record whose content carries a <user_query> tag - SKIPPING
+# hook-generated turns. final-review.sh / subagent-stop-review.sh emit a
+# {followup_message} that Cursor replays as a user turn (and self-review /
+# intent-anchor inject into additional_context); returning one of those would lock
+# the review boilerplate into .scope.json as the intent (the contamination loop).
+# Hook turns are detected by their fixed headers; if the transcript has been
+# trimmed to just the hook turn, recover the real request from the embedded
+# "ORIGINAL REQUEST ... --- <request> ---" block.
 extract_last_user_query() {
     local json="$1"
     local tp
@@ -134,6 +141,14 @@ extract_last_user_query() {
     if have_py; then
         printf '%s' "$reversed" | python3 -c '
 import json, re, sys
+HOOK_HDR = re.compile(r"^\s*(FINAL REVIEW \(end of implementation\)|SUBAGENT FINAL REVIEW|SELF-REVIEW|INTENT ANCHOR)", re.M)
+EMBEDDED = re.compile(r"ORIGINAL REQUEST[^\r\n]*\r?\n-{3,}\r?\n(.+?)\r?\n-{3,}", re.S)
+def redact(q):
+    q = re.sub(r"\bnpm_[A-Za-z0-9]{10,}\b", "[REDACTED_NPM_TOKEN]", q)
+    q = re.sub(r"\b(sk-[A-Za-z0-9]{10,}|ghp_[A-Za-z0-9]{20,}|gho_[A-Za-z0-9]{20,})\b", "[REDACTED_TOKEN]", q)
+    q = re.sub(r"(?i)(api[_-]?key|token|secret|password)\s*[:=]\s*\S+", r"\1=[REDACTED]", q)
+    return q
+embedded_fallback = ""
 try:
     for line in sys.stdin:
         line = line.strip()
@@ -155,15 +170,26 @@ try:
                 if isinstance(p, dict) and p.get("type") == "text" and p.get("text"):
                     text += p["text"]
         m = re.search(r"<user_query>\s*(.+?)\s*</user_query>", text, re.S)
-        if m:
-            q = m.group(1).strip()
-            if len(q) > 2000:
-                q = q[:2000] + "..."
-            q = re.sub(r"\bnpm_[A-Za-z0-9]{10,}\b", "[REDACTED_NPM_TOKEN]", q)
-            q = re.sub(r"\b(sk-[A-Za-z0-9]{10,}|ghp_[A-Za-z0-9]{20,}|gho_[A-Za-z0-9]{20,})\b", "[REDACTED_TOKEN]", q)
-            q = re.sub(r"(?i)(api[_-]?key|token|secret|password)\s*[:=]\s*\S+", r"\1=[REDACTED]", q)
-            print(q)
-            break
+        if not m:
+            continue
+        q = m.group(1).strip()
+        # Hook-generated turn -> not the human words. Remember the embedded
+        # ORIGINAL REQUEST (latest such turn) and keep walking back.
+        if HOOK_HDR.search(q):
+            if not embedded_fallback:
+                em = EMBEDDED.search(q)
+                if em:
+                    embedded_fallback = em.group(1).strip()
+            continue
+        if len(q) > 2000:
+            q = q[:2000] + "..."
+        print(redact(q))
+        break
+    else:
+        if embedded_fallback:
+            if len(embedded_fallback) > 2000:
+                embedded_fallback = embedded_fallback[:2000] + "..."
+            print(redact(embedded_fallback))
 except Exception:
     pass
 ' 2>/dev/null
@@ -172,9 +198,14 @@ except Exception:
 
     # No python3: best-effort grep for the common case where the user message
     # is the only place <user_query> appears in a line. Imperfect but bounded.
+    # Drop hook-generated turns (FINAL REVIEW / SUBAGENT / SELF-REVIEW / INTENT
+    # ANCHOR) so we never lock review boilerplate as the intent; take the first
+    # surviving human <user_query>.
     printf '%s' "$reversed" |
-        grep -m1 -oE '<user_query>[^<]*</user_query>' 2>/dev/null |
+        grep -oE '<user_query>[^<]*</user_query>' 2>/dev/null |
         sed -E 's@</?user_query>@@g' |
+        grep -vE '^[[:space:]]*(FINAL REVIEW \(end of implementation\)|SUBAGENT FINAL REVIEW|SELF-REVIEW|INTENT ANCHOR)' 2>/dev/null |
+        head -n1 |
         sed -E 's/\bnpm_[A-Za-z0-9]{10,}\b/[REDACTED_NPM_TOKEN]/g' |
         head -c 2000
 }

package/linux/hooks/intent-anchor.sh

@@ -150,12 +150,14 @@ 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.
+    # Hollow = no real intent on disk: empty, the hook's <TODO> placeholder, OR
+    # hook-generated review boilerplate that a stale extractor locked in (the
+    # contamination loop - "FINAL REVIEW (end of implementation)..."). 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 ;;
+        ""|"<TODO"*|"FINAL REVIEW (end of implementation)"*|"SUBAGENT FINAL REVIEW"*|"SELF-REVIEW"*|"INTENT ANCHOR"*) scope_hollow=1 ;;
     esac
     if [ "$scope_exists" = "1" ] && [ "$has_query" = "1" ]; then
         if [ "$scope_hollow" = "1" ]; then

package/linux/pre-compile.md

@@ -9,12 +9,34 @@ This is the proactive phase. The anti-slop checklist, the self-review trigger
 and the final review are reactive — they audit after the fact. You compile the
 intent BEFORE the first token of code so they have the right thing to audit.
 
+## Step 0 — Restate the request (the user writes fast; you normalize)
+
+Before the Anchor Set, in ONE line, play the request back as you understood it:
+
+> **Understood as:** _one clean sentence — grammar fixed, pronouns resolved,
+> implicit constraints made explicit, in the language of the request._
+
+Mandatory every implementation turn. This line is the user's catch-point: a
+misread surfaces HERE, before you write a line of code, instead of in review.
+The restatement is **meaning-preserving** — you normalize phrasing, you do NOT
+add scope, drop a constraint, or invent a requirement. If normalizing would
+force a guess that changes what "correct" means, you do not bury the guess in
+the restatement — you ask one sharp question (§5) and wait.
+
+The user's verbatim words stay the ground truth: `.scope.json`'s `trace.query`
+keeps them exactly as typed, and final-review traces every diff hunk back to
+THAT, not to your paraphrase. Your normalized sentence becomes `intent` (and the
+Anchor Set's OBJECTIVE below). The two must say the same thing in different
+words — if you cannot make `intent` and `trace.query` agree, you have misread
+the request, and that is the bug to fix first.
+
 ## The Anchor Set
 
 Answer these four, terse, in your first response. One phrase each, not prose:
 
-1. OBJECTIVE — one operational sentence. What is *strictly* necessary. Not
-   "improve X" — "make X return Y when Z".
+1. OBJECTIVE — your Step 0 restatement, tightened to the operational verb. One
+   sentence, what is *strictly* necessary. Not "improve X" — "make X return Y
+   when Z".
 2. CONSTRAINTS (local negations) — what you will NOT do. "NO schema migration.
    NO new dependency. NO refactor of the surrounding function." Negations bind
    harder than the objective: a constraint that the task contradicts is a bug
@@ -33,28 +55,36 @@ Answer these four, terse, in your first response. One phrase each, not prose:
 
 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
+  - `intent` is seeded from your verbatim 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`.
+  - `trace.query` is the VERBATIM request (the audit anchor), `_intent_hash` and
+    `_generated_by` are hook bookkeeping. Leave all three alone.
+
+Your two targeted edits on the contract (each a string replace on ONE field, never
+a whole-file rewrite):
+  - **`intent`** → replace the verbatim seed with your Step 0 restatement: the
+    normalized, meaning-preserving sentence. This is what final-review axis 0
+    traces each diff hunk against, so a clean `intent` makes the audit sharp.
+  - **`acceptance`** → set the single deterministic check that decides done, which
+    the hook cannot derive.
+
+Do **NOT** touch `trace.query`, `_intent_hash`, or `_generated_by`, and do **NOT**
+rewrite the whole file: `_intent_hash` is computed from the verbatim `trace.query`,
+not from `intent`, so refining `intent` is safe — but dropping the hash/trace
+disables per-prompt regeneration and brings back cross-feature carryover. Keeping
+`trace.query` verbatim is what lets the audit catch a paraphrase that quietly
+changed the meaning: `intent` and `trace.query` must agree.
 
 ```json
 {
-  "intent":       "<locked from your request by the hook>",
+  "intent":       "<YOU refine this: your normalized Step 0 restatement>",
   "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>" },
+  "trace":        { "query": "<VERBATIM request - the hook owns this, leave it>", "ts": "<when>" },
   "_intent_hash": "<hook bookkeeping>",
   "_generated_by":"intent-anchor hook"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursordoctrine",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "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/doctrine.md

@@ -67,6 +67,10 @@ what the task requires**.
 
 The natural order is:
 
+  0. **Restate** the request in one normalized line (`Understood as: …`) before
+     you touch a tool — grammar fixed, ambiguity resolved, meaning preserved.
+     It is the user's catch-point for a misread, and it becomes the contract's
+     `intent`. Full spec in pre-compile.
   1. **Read** the relevant file(s) to understand context.
   2. **Edit** to make the change.
   3. **Read** the file again (the self-review trigger will remind you).

package/windows/hooks/hook-common.ps1

@@ -83,11 +83,36 @@ function Redact-SecretsFromIntent([string]$text) {
     return $text
 }
 
-# Extract the last user <user_query> from a Cursor transcript JSONL.
+# A <user_query> turn can actually be a HOOK-GENERATED message replayed by Cursor
+# as a user turn: final-review.ps1 and subagent-stop-review.ps1 emit a
+# {followup_message} that Cursor auto-submits as the next user turn, and the
+# self-review / intent-anchor injections get drained into additional_context.
+# If Get-LastUserQuery returns one of those, intent-anchor locks the REVIEW
+# BOILERPLATE into .scope.json as the "intent" (the contamination loop that put
+# "FINAL REVIEW (end of implementation)..." in the contract). Detect them by the
+# fixed headers the hooks emit and skip past them to the real human turn.
+function Test-IsHookGeneratedQuery([string]$text) {
+    if (-not $text) { return $false }
+    return ($text -match '(?m)^\s*(FINAL REVIEW \(end of implementation\)|SUBAGENT FINAL REVIEW|SELF-REVIEW|INTENT ANCHOR)')
+}
+
+# The final-review / subagent-review followups embed the real human request as:
+#   ORIGINAL REQUEST (...):\n---\n<request>\n---
+# When the transcript has been trimmed to just the hook turn, recover the human
+# request from that block instead of returning the boilerplate.
+function Get-EmbeddedOriginalRequest([string]$text) {
+    if (-not $text) { return '' }
+    if ($text -match '(?s)ORIGINAL REQUEST[^\r\n]*\r?\n-{3,}\r?\n(.+?)\r?\n-{3,}') {
+        return $Matches[1].Trim()
+    }
+    return ''
+}
+
+# Extract the last *human* user <user_query> from a Cursor transcript JSONL.
 # transcript is an array of {role, message} records; we walk backward from the
-# end, find the last user turn whose content has a <user_query> tag, and return
-# its text. Returns '' if there is no transcript or no user_query. Capped at
-# 2000 chars so the follow-up prompt stays bounded.
+# end, skipping hook-generated turns (see above), and return the first real human
+# turn's text. Returns '' if there is no transcript or no human user_query. Capped
+# at 2000 chars so the follow-up prompt stays bounded.
 #
 # This is the Tier 0 intent-trace primitive: the final-review hook prepends the
 # extracted request to its followup so the model must trace every diff hunk back
@@ -97,6 +122,7 @@ function Get-LastUserQuery($obj) {
     if ($obj -and $obj.PSObject.Properties['transcript_path']) { $tp = [string]$obj.transcript_path }
     if (-not $tp -or -not (Test-Path -LiteralPath $tp)) { return '' }
     $lines = @(Get-Content -LiteralPath $tp -ErrorAction SilentlyContinue)
+    $embeddedFallback = ''
     for ($i = $lines.Count - 1; $i -ge 0; $i--) {
         $line = $lines[$i]
         if (-not $line -or $line -notmatch '"role"\s*:\s*"user"') { continue }
@@ -117,10 +143,22 @@ function Get-LastUserQuery($obj) {
         }
         if ($text -match '(?s)<user_query>\s*(.+?)\s*</user_query>') {
             $q = $Matches[1].Trim()
+            # Hook-generated turn -> not the human's words. Remember the embedded
+            # ORIGINAL REQUEST (from the most recent such turn) and keep walking.
+            if (Test-IsHookGeneratedQuery $q) {
+                if (-not $embeddedFallback) { $embeddedFallback = Get-EmbeddedOriginalRequest $q }
+                continue
+            }
             if ($q.Length -gt 2000) { $q = $q.Substring(0, 2000) + '...' }
             return (Redact-SecretsFromIntent $q)
         }
     }
+    # No real human turn survived in the transcript -> fall back to the request
+    # embedded in the latest hook followup, if we found one.
+    if ($embeddedFallback) {
+        if ($embeddedFallback.Length -gt 2000) { $embeddedFallback = $embeddedFallback.Substring(0, 2000) + '...' }
+        return (Redact-SecretsFromIntent $embeddedFallback)
+    }
     return ''
 }
 

package/windows/hooks/intent-anchor.ps1

@@ -127,12 +127,14 @@ 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.
+        # Hollow = no real intent on disk: empty, the hook's <TODO> placeholder, OR
+        # hook-generated review boilerplate that a stale extractor locked in as the
+        # intent (the contamination loop - "FINAL REVIEW (end of implementation)...").
         # 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>).
+        # fills it; scope-gate appends files to it and final-review audits against garbage).
         # 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')
+        $scopeHollow = ([string]::IsNullOrWhiteSpace($scopeIntent) -or $scopeIntent -match '^\s*<TODO' -or (Test-IsHookGeneratedQuery $scopeIntent))
         # 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

package/windows/pre-compile.md

@@ -9,12 +9,34 @@ This is the proactive phase. The anti-slop checklist, the self-review trigger
 and the final review are reactive — they audit after the fact. You compile the
 intent BEFORE the first token of code so they have the right thing to audit.
 
+## Step 0 — Restate the request (the user writes fast; you normalize)
+
+Before the Anchor Set, in ONE line, play the request back as you understood it:
+
+> **Understood as:** _one clean sentence — grammar fixed, pronouns resolved,
+> implicit constraints made explicit, in the language of the request._
+
+Mandatory every implementation turn. This line is the user's catch-point: a
+misread surfaces HERE, before you write a line of code, instead of in review.
+The restatement is **meaning-preserving** — you normalize phrasing, you do NOT
+add scope, drop a constraint, or invent a requirement. If normalizing would
+force a guess that changes what "correct" means, you do not bury the guess in
+the restatement — you ask one sharp question (§5) and wait.
+
+The user's verbatim words stay the ground truth: `.scope.json`'s `trace.query`
+keeps them exactly as typed, and final-review traces every diff hunk back to
+THAT, not to your paraphrase. Your normalized sentence becomes `intent` (and the
+Anchor Set's OBJECTIVE below). The two must say the same thing in different
+words — if you cannot make `intent` and `trace.query` agree, you have misread
+the request, and that is the bug to fix first.
+
 ## The Anchor Set
 
 Answer these four, terse, in your first response. One phrase each, not prose:
 
-1. OBJECTIVE — one operational sentence. What is *strictly* necessary. Not
-   "improve X" — "make X return Y when Z".
+1. OBJECTIVE — your Step 0 restatement, tightened to the operational verb. One
+   sentence, what is *strictly* necessary. Not "improve X" — "make X return Y
+   when Z".
 2. CONSTRAINTS (local negations) — what you will NOT do. "NO schema migration.
    NO new dependency. NO refactor of the surrounding function." Negations bind
    harder than the objective: a constraint that the task contradicts is a bug
@@ -33,28 +55,36 @@ Answer these four, terse, in your first response. One phrase each, not prose:
 
 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
+  - `intent` is seeded from your verbatim 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`.
+  - `trace.query` is the VERBATIM request (the audit anchor), `_intent_hash` and
+    `_generated_by` are hook bookkeeping. Leave all three alone.
+
+Your two targeted edits on the contract (each a string replace on ONE field, never
+a whole-file rewrite):
+  - **`intent`** → replace the verbatim seed with your Step 0 restatement: the
+    normalized, meaning-preserving sentence. This is what final-review axis 0
+    traces each diff hunk against, so a clean `intent` makes the audit sharp.
+  - **`acceptance`** → set the single deterministic check that decides done, which
+    the hook cannot derive.
+
+Do **NOT** touch `trace.query`, `_intent_hash`, or `_generated_by`, and do **NOT**
+rewrite the whole file: `_intent_hash` is computed from the verbatim `trace.query`,
+not from `intent`, so refining `intent` is safe — but dropping the hash/trace
+disables per-prompt regeneration and brings back cross-feature carryover. Keeping
+`trace.query` verbatim is what lets the audit catch a paraphrase that quietly
+changed the meaning: `intent` and `trace.query` must agree.
 
 ```json
 {
-  "intent":       "<locked from your request by the hook>",
+  "intent":       "<YOU refine this: your normalized Step 0 restatement>",
   "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>" },
+  "trace":        { "query": "<VERBATIM request - the hook owns this, leave it>", "ts": "<when>" },
   "_intent_hash": "<hook bookkeeping>",
   "_generated_by":"intent-anchor hook"
 }