cursordoctrine 0.5.4 → 0.5.5

package/bin/cli.mjs

@@ -334,6 +334,25 @@ function verify() {
         JSON.stringify({ role: 'user', message: { content: `<user_query>${q}</user_query>` } }) + '\n',
         'utf8');
 
+    // --- Case 0: no .scope.json + NO transcript -> WRITE scaffold anyway -------
+    // This is the 0.5.3 regression: creation was gated on $hasQuery, so when
+    // Cursor didn't surface transcript_path in the first postToolUse fire, the
+    // scope never appeared. Now creation is unconditional on a real root.
+    runHook(hook('intent-anchor'), { conversation_id: anchorCid, cwd: repoDir });
+    let d0 = drainedOf(anchorCid);
+    if (!existsSync(scopePath)) {
+      cleanup(); return { ok: false, detail: 'scaffold NOT created without transcript (0.5.3 regression)' };
+    }
+    let scope0;
+    try { scope0 = JSON.parse(readFileSync(scopePath, 'utf8')); }
+    catch { cleanup(); return { ok: false, detail: '.scope.json (no-transcript) is not valid JSON' }; }
+    if (!scope0.intent || !scope0.intent.includes('TODO')) {
+      cleanup(); return { ok: false, detail: `no-transcript scaffold should have intent <TODO>, got: ${scope0.intent}` };
+    }
+    // Clear the latch + scope so Case A starts fresh (with a real query this time).
+    runHook(hook('final-review'), { conversation_id: anchorCid, status: 'completed' });
+    cleanup();
+
     // --- Case A: no .scope.json + prompt q1 -> WRITE scaffold with q1 as intent -
     writeTranscript(q1);
     runHook(hook('intent-anchor'), { conversation_id: anchorCid, cwd: repoDir, transcript_path: transcriptPath });

package/linux/hooks/final-review.md

@@ -122,5 +122,18 @@ Determinism / purity:
   - In-place mutation of shared state (arr.push, obj.prop =) when a caller holds
     a reference -> return new structures ([...arr, x], .map/.filter).
 
+Logic & structure:
+  - Arrow code: >2 levels of nested if/for -> flatten with guard clauses
+    (early returns). Code reads top-to-bottom, no deep indent.
+  - Switch/if-else bloat: a switch or 5+ if/else branches -> Map/dispatch
+    (Record<State, fn>) or the Command pattern.
+  - Mixed abstraction (SLAP): a function mixing DB calls + string validation +
+    date formatting -> one level of abstraction per function; extract helpers.
+  - Primitive obsession: a primitive with business rules (email, userId, chainId)
+    passed as a bare string/number across functions -> a named type/value object.
+  - Imperative transforms: a `for` loop building an array when the language has
+    .map/.filter/.reduce -> use the declarative form; reserve `for` for cases
+    map/reduce cannot express.
+
 You do NOT need to run a tool for these — read the diff and apply the named fix.
 If none apply, say so in one line.

package/linux/hooks/intent-anchor.sh

@@ -58,6 +58,16 @@ pending_dir="$(hooks_pending_dir)"
 latch="$pending_dir/intent-injected-$cid.flag"
 hash_file="$pending_dir/last-query-$cid.hash"
 
+# Stale-latch defense: if a previous session died mid-turn without hitting
+# stop (Cursor crash, force-quit), the latch can persist and silence this hook
+# for the whole next session -> scope never gets created. If the latch is older
+# than 2 hours, treat it as orphaned and clear it. Normal clears happen at
+# every stop (final-review.sh); this is the backstop for abnormal terminations.
+if [ -f "$latch" ]; then
+    age_hours=$(( ($(date +%s) - $(stat -c %Y "$latch" 2>/dev/null || stat -f %m "$latch" 2>/dev/null || echo 0)) / 3600 ))
+    [ "$age_hours" -ge 2 ] && rm -f "$latch" 2>/dev/null
+fi
+
 # Already injected this turn -> quiet. Latch cleared at every stop.
 [ -f "$latch" ] && exit 0
 
@@ -133,30 +143,38 @@ EOF
     fi
 fi
 
-# --- auto-create / regenerate .scope.json (the 0.4.4 behavior, fixed) --------
-# The user wants: every NEW prompt -> a fresh .scope.json the agent works from.
-# So we WRITE the scaffold when (a) there is no valid contract, OR (b) the
-# contract on disk is stale (its _intent_hash != current query hash). Fixed vs
-# 0.4.4: never writes to $HOME (bail above if no real root) -> no ghost files;
-# regenerates on prompt CHANGE not just absence -> "each prompt, new file".
+# --- auto-create / regenerate .scope.json -----------------------------------
+# CREATION does NOT require the query: if there's a root and no scope yet,
+# scaffold it NOW with intent=<TODO> (the agent fills it from the chat it's
+# already responding to). This was the 0.5.3 bug - creation was gated on
+# $hasQuery, so when Cursor didn't surface transcript_path in the first
+# postToolUse fire, the scope never got created.
+# REGENERATION does require the query: we can only detect a prompt change if
+# we can hash the current request. Without a query we leave an existing scope
+# alone (re-inject it) rather than blank it.
 regenerated=0
-should_write=0
-if [ "$has_query" = "1" ]; then
-    if [ "$scope_exists" != "1" ] || [ "$scope_stale" = "1" ]; then
-        should_write=1
-    fi
+should_create=0
+should_regen=0
+[ "$scope_exists" != "1" ] && should_create=1
+if [ "$has_query" = "1" ] && [ "$scope_exists" = "1" ] && [ "$scope_stale" = "1" ]; then
+    should_regen=1
 fi
 
-if [ "$should_write" = "1" ]; then
-    # jq preferred; python3 fallback. Write intent from the query, TODO
-    # placeholders for files/acceptance, and record _intent_hash so staleness
-    # is self-contained in the file (survives cross-session hash sweeps).
+if [ "$should_create" = "1" ] || [ "$should_regen" = "1" ]; then
+    # intent from the query when available, else a TODO for the agent to fill.
+    if [ "$has_query" = "1" ]; then
+        intent_val="$current_query"
+    else
+        intent_val="<TODO: state the operational objective - what is strictly necessary>"
+    fi
+    # jq preferred; python3 fallback. Write intent, empty files[], TODO
+    # acceptance, and record _intent_hash so staleness is self-contained.
     if have_jq; then
-        jq -n --arg intent "$current_query" --arg hash "$current_hash" \
+        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"}' \
             > "$scope_path" 2>/dev/null && regenerated=1
     elif have_py; then
-        if I_FILE="$scope_path" I_INTENT="$current_query" I_HASH="$current_hash" python3 -c '
+        if I_FILE="$scope_path" I_INTENT="$intent_val" I_HASH="$current_hash" python3 -c '
 import json, os
 obj = {
     "intent": os.environ["I_INTENT"],
@@ -173,7 +191,7 @@ with open(os.environ["I_FILE"], "w", encoding="utf-8") as f:
         fi
     fi
     if [ "$regenerated" = "1" ]; then
-        scope_intent="$current_query"
+        scope_intent="$intent_val"
         scope_acceptance="<TODO: the one deterministic check that decides done>"
         scope_files="(auto-tracked - the scope hook records every file you edit)"
         scope_exists=1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursordoctrine",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "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/hooks/final-review.md

@@ -122,5 +122,18 @@ Determinism / purity:
   - In-place mutation of shared state (arr.push, obj.prop =) when a caller holds
     a reference -> return new structures ([...arr, x], .map/.filter).
 
+Logic & structure:
+  - Arrow code: >2 levels of nested if/for -> flatten with guard clauses
+    (early returns). Code reads top-to-bottom, no deep indent.
+  - Switch/if-else bloat: a switch or 5+ if/else branches -> Map/dispatch
+    (Record<State, fn>) or the Command pattern.
+  - Mixed abstraction (SLAP): a function mixing DB calls + string validation +
+    date formatting -> one level of abstraction per function; extract helpers.
+  - Primitive obsession: a primitive with business rules (email, userId, chainId)
+    passed as a bare string/number across functions -> a named type/value object.
+  - Imperative transforms: a `for` loop building an array when the language has
+    .map/.filter/.reduce -> use the declarative form; reserve `for` for cases
+    map/reduce cannot express.
+
 You do NOT need to run a tool for these — read the diff and apply the named fix.
 If none apply, say so in one line.

package/windows/hooks/intent-anchor.ps1

@@ -14,17 +14,20 @@
 #      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.ps1 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.
-#   3. RE-INJECT on same-prompt turns: when the query is unchanged (contract
+#   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
+#      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
 #      feedback bus so it stays in the model's attentional focus each turn.
 #
@@ -56,6 +59,16 @@ $pendingDir = Get-HooksPendingDir
 $latch    = Join-Path $pendingDir "intent-injected-$cid.flag"
 $hashFile = Join-Path $pendingDir "last-query-$cid.hash"
 
+# Stale-latch defense: if a previous session died mid-turn without hitting
+# stop (Cursor crash, force-quit), the latch can persist and silence this hook
+# for the whole next session -> scope never gets created. If the latch is older
+# than 2 hours, treat it as orphaned and clear it. Normal clears happen at
+# every stop (final-review.ps1); this is the backstop for abnormal terminations.
+if (Test-Path $latch) {
+    $age = (Get-Date) - (Get-Item $latch).LastWriteTime
+    if ($age.TotalHours -ge 2) { Remove-Item $latch -Force -ErrorAction SilentlyContinue }
+}
+
 # Already injected this turn -> quiet. Latch cleared at every stop.
 if (Test-Path $latch) { exit 0 }
 
@@ -115,21 +128,24 @@ if (Test-Path -LiteralPath $scopePath) {
     } catch { $scopeExists = $false }   # malformed JSON -> treat as missing
 }
 
-# --- auto-create / regenerate .scope.json (the 0.4.4 behavior, fixed) --------
-# The user wants: every NEW prompt -> a fresh .scope.json the agent works from.
-# So we WRITE the scaffold when (a) there is no valid contract, OR (b) the
-# contract on disk is stale (its _intent_hash != current query hash). Intent is
-# locked from the current <user_query>; files starts EMPTY (scope-gate-audit
-# auto-records edits into it); acceptance is a TODO the agent sets. Fixed vs 0.4.4:
-#   - NEVER writes to $HOME (bail above if no real root) -> no ghost files.
-#   - Regenerates on prompt CHANGE, not just on absence -> "each prompt, new file".
-#   - Records _intent_hash so staleness is self-contained in the file.
+# --- auto-create / regenerate .scope.json -----------------------------------
+# CREATION does NOT require the query: if there's a root and no scope yet,
+# scaffold it NOW with intent=<TODO> (the agent fills it from the chat it's
+# already responding to). This was the 0.5.3 bug - creation was gated on
+# $hasQuery, so when Cursor didn't surface transcript_path in the first
+# postToolUse fire, the scope never got created. The agent never had a
+# contract to work from.
+# REGENERATION does require the query: we can only detect a prompt change if
+# we can hash the current request. Without a query we leave an existing scope
+# alone (re-inject it) rather than blank it.
 $regenerated = $false
-$shouldWrite = $hasQuery -and (-not $scopeExists -or $scopeStale)
-if ($shouldWrite) {
+$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>' }
         $scaffold = [ordered]@{
-            intent        = $currentQuery
+            intent        = $intentVal
             files         = @()
             acceptance    = '<TODO: the one deterministic check that decides done>'
             allow_growth  = $false
@@ -138,7 +154,7 @@ if ($shouldWrite) {
         }
         $json = $scaffold | ConvertTo-Json -Depth 5
         [System.IO.File]::WriteAllText($scopePath, $json, [System.Text.UTF8Encoding]::new($false))
-        $scopeIntent     = $currentQuery
+        $scopeIntent     = $intentVal
         $scopeAcceptance = '<TODO: the one deterministic check that decides done>'
         $scopeFiles      = '(auto-tracked - the scope hook records every file you edit)'
         $scopeExists     = $true