cursordoctrine 0.1.1 → 0.2.0

package/README.md

@@ -10,7 +10,7 @@ A small set of Cursor hooks that make the agent review its own work without bolt
 2. **Hand the model its own edits back.** After each agent edit, a self-review prompt (plus minimal-edit and anti-slop advisories when they trip) is stashed and delivered on the next turn. The model reads its own diff, fixes real bugs, and stays quiet otherwise.
 3. **Gate blast radius.** One permission gate denies a short, explicit list of dangerous commands (`rm -rf /`, `curl | sh`, force-push, `npm publish`, ...). Everything else is allowed.
 
-When an implementation finishes, a stop hook fires exactly one final review pass over everything that changed — then stops. Delegated work gets the same treatment: a subagent that edited files reviews its own implementation before its result returns to the parent, and its edits are folded into the parent's final review. Every bound is enforced twice: in the script and in `hooks.json`.
+When an implementation finishes, a stop hook fires exactly one final review pass over everything that changed — then stops. The review runs across five axes, the first of which is **intent trace**: the hook extracts your last user message from the transcript and prepends it to the review so the model must trace every diff hunk back to a concrete request. Anything untraceable is a hallucinated requirement and gets reverted — this is the only detector that catches "clean code, wrong feature," which no later axis and no linter can see. Delegated work gets the same treatment: a subagent that edited files reviews its own implementation before its result returns to the parent, and its edits are folded into the parent's final review. Every bound is enforced twice: in the script and in `hooks.json`.
 
 This setup is for Cursor only. It installs into `~/.cursor` and `~/.agents/hooks` and touches nothing in your projects.
 
@@ -41,7 +41,7 @@ The two folders are functionally identical. Windows runs everything through `pws
 | Session | `sessionStart` | `inject-doctrine` reads the doctrine + user rules and emits them as `additional_context`. |
 | Every turn | `postToolUse` | Folds completed subagents' edit markers into this conversation's marker, then drains the conversation's pending feedback file into `additional_context`. One-shot, keyed by conversation id. |
 | Shell | `beforeShellExecution` | `permission-gate` checks the command against a deny list. Allow by default, deny by list, fail open. |
-| Edit | `afterFileEdit` + `stop` | `self-review-trigger` stashes the review prompt per edit; `minimal-edit-audit` and `anti-slop-audit` append advisories when thresholds trip; `final-review` fires one end-of-implementation pass. |
+| Edit | `afterFileEdit` + `stop` | `self-review-trigger` stashes the review prompt per edit; `minimal-edit-audit` and `anti-slop-audit` append advisories when thresholds trip (new deps / premature abstraction / redundant comments / Tier 3 operational slop: retry-without-backoff, await-in-loop, telemetry spam); `final-review` fires one end-of-implementation pass. |
 | Subagent | `subagentStop` | `subagent-stop-review` fires one in-subagent final review when a delegated run edited files, before the result returns to the parent. Marker-gated and flag-braked like `final-review`. |
 
 ## Install

package/linux/hooks/anti-slop-audit.sh

@@ -12,6 +12,8 @@
 #       *Strategy / *Singleton / *Facade / *Builder / *Visitor / *Decorator
 #       class, or CQRS / Event-Sourcing / DDD vocabulary
 #     * redundant comments that merely restate the next line of code
+#     * operational slop (Tier 3): retry-without-backoff, await-in-loop,
+#       telemetry spam (>= 6 log/print statements added in one edit)
 #
 # Fires when a static signal trips OR the edit added a substantial block of
 # new source (>= ANTI_SLOP_CHECKLIST_LINES, default 40). Otherwise silent.
@@ -102,6 +104,31 @@ redundant="$(printf '%s\n' "$added" |
         fi
     done | sort -u | head -n 4)"
 
+# --- signal 4: operational slop (Tier 3) ------------------------------------
+# Retry-without-backoff: a retry construct with no sleep/backoff/setTimeout in
+# the added lines. Seed-grade (high precision); the model judges.
+ops_flags=""
+if printf '%s\n' "$added" | grep -qE '\b(retry|retryCount|retries|maxRetries|attempt)[A-Za-z0-9_]*\b'; then
+    if ! printf '%s\n' "$added" | grep -qE '\b(sleep|setTimeout|backoff|back_off|exponential|jitter|delay)[A-Za-z0-9_]*\b'; then
+        ops_flags="${ops_flags}- RETRY WITHOUT BACKOFF: a retry construct was added but no sleep/backoff/setTimeout is visible in this edit's added lines. Unbounded retries = retry storms + token/cost burn; add bounded backoff or confirm the runtime already throttles.
+"
+    fi
+fi
+# Awaited IO call co-occurring with a loop construct on the same edit. N+1 in
+# agent/edge code, not just SQL. The model judges streaming vs serial-await.
+if printf '%s\n' "$added" | grep -qE '\b(for|while|forEach|map|filter|reduce|flatMap|for[[:space:]]+await|async[[:space:]]+for)\b'; then
+    if printf '%s\n' "$added" | grep -qE '\bawait[[:space:]]+(fetch|ctx\.db|ctx\.run|client\.|axios|prisma\.|supabase\.|db\.|repo\.)'; then
+        ops_flags="${ops_flags}- AWAIT IN LOOP: a loop construct and an awaited IO call both appear in this edit. Sequential awaits in a loop = N+1 / serial latency; confirm whether Promise.all / a batch call / a single query is the right primitive. (If this is genuinely a streaming pattern, ignore.)
+"
+    fi
+fi
+# Telemetry spam seed: 6+ log/print statements added in one file.
+log_count="$(printf '%s\n' "$added" | grep -cE '\b(console\.(log|debug|info|warn|error)|print\(|fmt\.Print|std::cout|NSLog|System\.out\.println|println!|dbg!|console\.dir)\b')"
+if [ "$log_count" -ge 6 ]; then
+    ops_flags="${ops_flags}- TELEMETRY SPAM: ${log_count} log/print statements added in this one edit. Debug-level telemetry that nobody reads is slop; consolidate or remove (kept only if this is a real logging entrypoint).
+"
+fi
+
 # --- decide whether to fire -------------------------------------------------
 added_code="$(printf '%s\n' "$added" | grep -cE '[^[:space:]]')"
 checklist_lines="${ANTI_SLOP_CHECKLIST_LINES:-40}"
@@ -118,6 +145,7 @@ flags=""
 "
 [ -n "$redundant" ] && flags="${flags}- REDUNDANT COMMENTS: $(printf '%s' "$redundant" | paste -sd '|' -) - delete comments that restate the code; keep only WHY.
 "
+flags="${flags}${ops_flags}"
 
 if [ -z "$flags" ] && [ "$substantial" = "0" ]; then exit 0; fi
 

package/linux/hooks/final-review.md

@@ -1,11 +1,20 @@
 FINAL REVIEW — you just finished an implementation. Before you treat it as done,
-audit EVERYTHING you changed this session across the four axes below and FIX what
+audit EVERYTHING you changed this session across the five axes below and FIX what
 fails. Do NOT revert the behaviour the user asked for. If an axis is already
 clean, say so in one line — do not manufacture work.
 
 Start by re-reading the diff. Scope the review to your session's changes and the
 code they touch.
 
+## 0. Intent trace (HIGHEST PRIORITY — run first)
+The hook extracted your last user message as "ORIGINAL REQUEST" above. For every
+hunk in the diff, answer: which part of the request forced this change? Anything
+that cannot trace to the request is a HALLUCINATED REQUIREMENT — a feature,
+flag, refactor, abstraction, dependency, or "nice to have" that nobody asked for.
+Revert each one. "Clean code, wrong feature" is the worst failure mode and no
+later axis can catch it. This axis outranks all others. (If no ORIGINAL REQUEST
+is present — sandboxed verify run, no transcript — skip this axis.)
+
 ## 1. Correctness
 - The logic does what the task requires — no off-by-one, inverted condition,
   wrong operator, wrong return value, wrong import path.

package/linux/hooks/final-review.sh

@@ -94,9 +94,31 @@ done <<EOF
 $edited
 EOF
 file_list="$(printf '%s' "$file_list" | head -n 30)"
-msg="FINAL REVIEW (end of implementation) - correctness, reliability, coverage, anti-slop.
 
-Files you changed this session:
+# Tier 0: extract the last user <user_query> from the transcript so the model
+# can trace every diff hunk back to a concrete request. Anything untraceable is
+# a hallucinated requirement. Empty when there is no transcript or no
+# user_query (sandboxed verify runs, fresh installs) - the axis is then a no-op.
+user_query="$(extract_last_user_query "$input")"
+intent_block=""
+[ -n "$user_query" ] && intent_block="ORIGINAL REQUEST (your last user message, for intent trace):
+---
+$user_query
+---
+
+"
+
+# Tier 5: cross-file change-surface metric. The per-file afterFileEdit audits
+# miss the 50-file rename case; this seeds the whole-session footprint so the
+# model can judge whether the change surface is proportional to the request.
+unique_files="$(printf '%s\n' "$edited" | grep -c -v '^$')"
+surface_block="Session footprint: ${unique_files} file(s) touched. If a simple request produced >5 files or >200 lines, justify each file's inclusion or trim.
+
+"
+
+msg="FINAL REVIEW (end of implementation) - intent, correctness, reliability, coverage, anti-slop.
+
+${surface_block}${intent_block}Files you changed this session:
 $file_list
 
 $body"

package/linux/hooks/hook-common.sh

@@ -105,6 +105,76 @@ resolve_agent_path() {
     esac
 }
 
+# extract_last_user_query <json> -> text of the last <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
+# extracted request to its followup so the model must trace every diff hunk back
+# 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.
+extract_last_user_query() {
+    local json="$1"
+    local tp
+    tp="$(json_get "$json" transcript_path)"
+    [ -n "$tp" ] && [ -f "$tp" ] || return 0
+
+    local reversed
+    if command -v tac >/dev/null 2>&1; then
+        reversed="$(tac "$tp" 2>/dev/null)"
+    else
+        # Portable fallback: awk NR table reversed.
+        reversed="$(awk '{a[NR]=$0} END {for(i=NR;i>=1;i--) print a[i]}' "$tp" 2>/dev/null)"
+    fi
+    [ -n "$reversed" ] || return 0
+
+    # Pull the text out via python3 if available (handles JSON content arrays);
+    # fall back to a pure-grep that handles string-typed content.
+    if have_py; then
+        printf '%s' "$reversed" | python3 -c '
+import json, re, sys
+try:
+    for line in sys.stdin:
+        line = line.strip()
+        if not line or "\"role\"" not in line:
+            continue
+        try:
+            rec = json.loads(line)
+        except Exception:
+            continue
+        if not isinstance(rec, dict) or rec.get("role") != "user":
+            continue
+        msg = rec.get("message") or {}
+        content = msg.get("content")
+        text = ""
+        if isinstance(content, str):
+            text = content
+        elif isinstance(content, list):
+            for p in content:
+                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] + "..."
+            print(q)
+            break
+except Exception:
+    pass
+' 2>/dev/null
+        return 0
+    fi
+
+    # 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.
+    printf '%s' "$reversed" |
+        grep -m1 -oE '<user_query>[^<]*</user_query>' 2>/dev/null |
+        sed -E 's@</?user_query>@@g' |
+        head -c 2000
+}
+
 # merge_subagent_edit_markers <json> <parent_cid> -> 0 if anything was folded
 #
 # Subagent edits fire afterFileEdit under the SUBAGENT's conversation_id, so

package/linux/hooks/self-review.md

@@ -19,6 +19,13 @@ file. Your job, on this turn, is to:
      - **Logic bugs that the user would actually care about**: a function
        that returns the wrong thing, an off-by-one, a missing `return`, a
        wrong import path.
+     - **Semantic contracts**: did any existing function's BEHAVIOR change
+       without its name, signature, or docstring changing? Names are
+       contracts. `deleteUser()` that now soft-deletes, a getter that now
+       writes, a function that used to throw on bad input and now silently
+       returns null — these are silent contract breaks that callers will
+       rely on and break against. If behavior changed, the name, signature,
+       or docstring must reflect it.
   4. If you find a real bug, **fix it with `Edit`**, then say nothing.
      Do not report it. Do not explain it. The user will see the fix
      in the next message; the bug is gone.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cursordoctrine",
-  "version": "0.1.1",
-  "description": "Thin self-review hooks for Cursor — the model is the auditor. One command installs the doctrine, the hook pack, and the anti-slop skill.",
+  "version": "0.2.0",
+  "description": "Thin self-review hooks for Cursor — the model is the auditor. One command installs the doctrine, the hook pack, and the anti-slop skill. Adds an intent-trace final-review axis that catches clean-code-wrong-feature (the worst AI slop).",
   "bin": {
     "cursordoctrine": "bin/cli.mjs"
   },

package/windows/hooks/anti-slop-audit.ps1

@@ -13,6 +13,8 @@
 #       *Strategy / *Singleton / *Facade / *Builder / *Visitor / *Decorator
 #       class, or CQRS / Event-Sourcing / DDD vocabulary
 #     * redundant comments that merely restate the next line of code
+#     * operational slop (Tier 3): retry-without-backoff, await-in-loop,
+#       telemetry spam (>= 6 log/print statements added in one edit)
 #
 #   Deferred to the model (semantic - no regex can judge these without drowning
 #   the user in false positives): edge cases, duplicated logic, ignored
@@ -128,6 +130,50 @@ foreach ($a in $added) {
     if ($redundant.Count -ge 4) { break }
 }
 
+# --- signal 4: operational slop (Tier 3) ----------------------------------
+# Retry-without-backoff: a retry loop or recursive retry without an obvious
+# sleep/backoff/setTimeout nearby. The whole-file body is scanned so the
+# backoff can sit above or below the retry; this is deliberately seed-grade
+# (high precision), not a verdict.
+$opsFlags = New-Object System.Collections.Generic.List[string]
+$bodyHas = {
+    param($pat)
+    foreach ($a in $added) { if ($a -match $pat) { return $true } }
+    return $false
+}
+$retryWord    = '\b(retry|retryCount|retries|maxRetries|attempt)\w*\b'
+$backoffWord  = '\b(sleep|setTimeout|backoff|back_off|exponential|jitter|delay)\w*\b'
+if (& $bodyHas $retryWord) {
+    $noBackoff = $true
+    foreach ($a in $added) { if ($a -match $backoffWord) { $noBackoff = $false; break } }
+    if ($noBackoff) {
+        $opsFlags.Add("- RETRY WITHOUT BACKOFF: a retry construct was added but no sleep/backoff/setTimeout is visible in this edit's added lines. Unbounded retries = retry storms + token/cost burn; add bounded backoff or confirm the runtime already throttles.")
+    }
+}
+
+# `await` (or `await ctx.db`) inside a loop construct on its own line — N+1 in
+# agent/edge code, not just SQL. We seed on the added-line co-occurrence of a
+# loop keyword and an awaited call; the model judges whether it is genuinely a
+# sequential-await loop (real slop) or a legit streaming pattern.
+$loopWord = '\b(for|while|forEach|map|filter|reduce|flatMap|for\s+await|async\s+for)\b'
+$awaitCall = '\bawait\s+(fetch|ctx\.db|ctx\.run|client\.|axios|prisma\.|supabase\.|db\.|repo\.)'
+if (& $bodyHas $loopWord) {
+    $awaitInLoop = $false
+    foreach ($a in $added) { if ($a -match $awaitCall) { $awaitInLoop = $true; break } }
+    if ($awaitInLoop) {
+        $opsFlags.Add("- AWAIT IN LOOP: a loop construct and an awaited IO call both appear in this edit. Sequential awaits in a loop = N+1 / serial latency; confirm whether Promise.all / a batch call / a single query is the right primitive. (If this is genuinely a streaming pattern, ignore.)")
+    }
+}
+
+# Telemetry spam seed: 6+ console.log / print / fmt.Print / std::cout::<< added
+# in one file. Models paste debug prints liberally; six is well past intent.
+$logRe = '\b(console\.(log|debug|info|warn|error)|print\(|fmt\.Print|std::cout|NSLog|System\.out\.println|println!|dbg!|console\.dir)\b'
+$logCount = 0
+foreach ($a in $added) { if ($a -match $logRe) { $logCount++ } }
+if ($logCount -ge 6) {
+    $opsFlags.Add("- TELEMETRY SPAM: $logCount log/print statements added in this one edit. Debug-level telemetry that nobody reads is slop; consolidate or remove (kept only if this is a real logging entrypoint).")
+}
+
 # --- decide whether to fire ----------------------------------------------
 $srcRe = '\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|kts|cs|cpp|cc|cxx|c|h|hpp|rb|php|swift|scala|m|mm|sh|ps1|lua|dart|ex|exs|vue|svelte)$'
 $addedCode = 0
@@ -139,6 +185,7 @@ $flags = New-Object System.Collections.Generic.List[string]
 if ($depAdded)              { $flags.Add("- DEPENDENCY: " + $base + " gained a dependency - is it necessary, or do the stdlib / existing deps already cover it?") }
 if ($patterns.Count -gt 0)  { $flags.Add("- PREMATURE ABSTRACTION: " + ($patterns -join ', ') + " - is there a real, present problem (2-3+ call sites that exist today) that needs it? If it is speculative, delete it and write the direct code.") }
 if ($redundant.Count -gt 0) { $flags.Add("- REDUNDANT COMMENTS: " + ($redundant -join ' | ') + " - delete comments that restate the code; keep only WHY.") }
+$flags.AddRange($opsFlags)
 
 if ($flags.Count -eq 0 -and -not $substantial) { exit 0 }
 

package/windows/hooks/final-review.md

@@ -1,11 +1,20 @@
 FINAL REVIEW — you just finished an implementation. Before you treat it as done,
-audit EVERYTHING you changed this session across the four axes below and FIX what
+audit EVERYTHING you changed this session across the five axes below and FIX what
 fails. Do NOT revert the behaviour the user asked for. If an axis is already
 clean, say so in one line — do not manufacture work.
 
 Start by re-reading the diff. Scope the review to your session's changes and the
 code they touch.
 
+## 0. Intent trace (HIGHEST PRIORITY — run first)
+The hook extracted your last user message as "ORIGINAL REQUEST" above. For every
+hunk in the diff, answer: which part of the request forced this change? Anything
+that cannot trace to the request is a HALLUCINATED REQUIREMENT — a feature,
+flag, refactor, abstraction, dependency, or "nice to have" that nobody asked for.
+Revert each one. "Clean code, wrong feature" is the worst failure mode and no
+later axis can catch it. This axis outranks all others. (If no ORIGINAL REQUEST
+is present — sandboxed verify run, no transcript — skip this axis.)
+
 ## 1. Correctness
 - The logic does what the task requires — no off-by-one, inverted condition,
   wrong operator, wrong return value, wrong import path.

package/windows/hooks/final-review.ps1

@@ -98,7 +98,24 @@ $body = Expand-AgentPaths $body
 
 $resolved = @($edited | ForEach-Object { Resolve-AgentPath $_ })
 $fileList = ($resolved | Select-Object -First 30) -join "`n  "
-$msg = "FINAL REVIEW (end of implementation) - correctness, reliability, coverage, anti-slop.`n`nFiles you changed this session:`n  $fileList`n`n$body"
+
+# Tier 0: extract the last user <user_query> from the transcript so the model
+# can trace every diff hunk back to a concrete request. Anything untraceable is
+# a hallucinated requirement. Empty when there is no transcript or no user_query
+# (sandboxed verify runs, fresh installs) — the axis is then a no-op.
+$userQuery = Get-LastUserQuery $obj
+$intentBlock = ''
+if ($userQuery) {
+    $intentBlock = "ORIGINAL REQUEST (your last user message, for intent trace):`n---`n$userQuery`n---`n`n"
+}
+
+# Tier 5: cross-file change-surface metric. The per-file afterFileEdit audits
+# miss the 50-file rename case; this seeds the whole-session footprint so the
+# model can judge whether the change surface is proportional to the request.
+$uniqueFiles = @($edited | Select-Object -Unique).Count
+$surfaceBlock = "Session footprint: $uniqueFiles file(s) touched. If a simple request produced >5 files or >200 lines, justify each file's inclusion or trim.`n`n"
+
+$msg = "FINAL REVIEW (end of implementation) - intent, correctness, reliability, coverage, anti-slop.`n`n${surfaceBlock}${intentBlock}Files you changed this session:`n  $fileList`n`n$body"
 
 # Arm the one-shot brake BEFORE emitting, so a crash after emit can't re-fire.
 New-Item -ItemType File -Path $flag -Force -ErrorAction SilentlyContinue | Out-Null

package/windows/hooks/hook-common.ps1

@@ -73,6 +73,47 @@ function Resolve-AgentPath([string]$p) {
     return ConvertTo-FwdPath $p
 }
 
+# Extract the last user <user_query> from a Cursor transcript JSONL. The
+# 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.
+#
+# 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
+# to it. Anything untraceable is a hallucinated requirement.
+function Get-LastUserQuery($obj) {
+    $tp = ''
+    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)
+    for ($i = $lines.Count - 1; $i -ge 0; $i--) {
+        $line = $lines[$i]
+        if (-not $line -or $line -notmatch '"role"\s*:\s*"user"') { continue }
+        try {
+            $rec = $line | ConvertFrom-Json -ErrorAction SilentlyContinue
+        } catch { continue }
+        if (-not $rec -or -not $rec.message) { continue }
+        $content = $rec.message.content
+        if (-not $content) { continue }
+        # content is an array of {type:text,text:...} or a plain string
+        $text = ''
+        if ($content -is [string]) {
+            $text = $content
+        } else {
+            foreach ($part in $content) {
+                if ($part.type -eq 'text' -and $part.text) { $text += $part.text }
+            }
+        }
+        if ($text -match '(?s)<user_query>\s*(.+?)\s*</user_query>') {
+            $q = $Matches[1].Trim()
+            if ($q.Length -gt 2000) { $q = $q.Substring(0, 2000) + '...' }
+            return $q
+        }
+    }
+    return ''
+}
+
 # Subagent edits fire afterFileEdit under the SUBAGENT's conversation_id, so
 # their session-edits markers are invisible to the parent's stop-hook review.
 # Subagent transcripts live at <transcripts>/<parent-cid>/subagents/<sub-cid>.jsonl,

package/windows/hooks/self-review.md

@@ -19,6 +19,13 @@ file. Your job, on this turn, is to:
      - **Logic bugs that the user would actually care about**: a function
        that returns the wrong thing, an off-by-one, a missing `return`, a
        wrong import path.
+     - **Semantic contracts**: did any existing function's BEHAVIOR change
+       without its name, signature, or docstring changing? Names are
+       contracts. `deleteUser()` that now soft-deletes, a getter that now
+       writes, a function that used to throw on bad input and now silently
+       returns null — these are silent contract breaks that callers will
+       rely on and break against. If behavior changed, the name, signature,
+       or docstring must reflect it.
   4. If you find a real bug, **fix it with `Edit`**, then say nothing.
      Do not report it. Do not explain it. The user will see the fix
      in the next message; the bug is gone.