cursordoctrine 0.4.3 → 0.4.4

package/README.md

@@ -98,10 +98,11 @@ The Anchor Set is skipped for trivial one-liners (typo, literal) — the `declar
 
 Writing `.scope.json` once is not enough. As a conversation fills with code, logs and errors, the token of the original request shrinks to a rounding error against the recent history — *Salience Dilution* — and the agent stops checking the contract it wrote at prompt 1. It forgets symmetry, colors, the acceptance bar. This is the failure mode the nudge alone can't fix (a reminder that the contract exists ≠ the contract being in context).
 
-`intent-anchor` (`postToolUse`, registered first so it runs before `post-tool-use` drains the bus) does two things on the **first tool boundary of every turn** (per-turn latch, cleared unconditionally at each stop):
+`intent-anchor` (`postToolUse`, registered first so it runs before `post-tool-use` drains the bus) does three things on the **first tool boundary of every turn** (per-turn latch, cleared unconditionally at each stop):
 
-1. **Re-inject the contract.** Reads `.scope.json` and stashes `intent` + `files` + `acceptance` into the feedback bus, which `post-tool-use` delivers as `additional_context`. The contract is back in the model's attentional focus at the start of each turn's work — **before** edits pile up and dilute it. This runs unconditionally (no transcript needed); it's the core anti-dilution move.
-2. **Re-compile on prompt change.** Hashes the current `<user_query>` and compares to the previous turn's hash (`last-query-<cid>.hash`, which persists across turns). If the request moved, it demands the agent **update** `.scope.json` to match — the scope tracks the request. If no `.scope.json` exists, it demands one be written. (Needs `transcript_path` in the payload; if absent this part degrades to silent but the re-injection still runs.)
+1. **Materialize the contract (0.4.4+).** If `.scope.json` is missing or invalid and the current `<user_query>` is available, the hook **writes a scaffold to disk** — `intent` from your prompt, `files`/`acceptance` as obvious `<TODO: …>` placeholders. Contract creation is no longer probabilistic.
+2. **Re-inject the contract.** Reads `.scope.json` and stashes `intent` + `files` + `acceptance` into the feedback bus, which `post-tool-use` delivers as `additional_context`.
+3. **Re-compile on prompt change.** Hashes the current `<user_query>` and compares to the previous turn's hash. If the request moved and a non-scaffold contract already exists, it demands the agent **update** `.scope.json`.
 
 Crucially, `intent-anchor` carries the **semantic** contract (`intent`/`acceptance`) into context every turn — something the path-only `scope-gate-audit` can never do. That is what makes "the agent forgot about grid symmetry while editing the right file" catchable: the symmetry requirement is re-stated in front of the model before each edit, not just checked against a file list after.
 

package/bin/cli.mjs

@@ -74,6 +74,26 @@ function mergeHooks(existing, incoming, keys) {
       if (i >= 0) cur[i] = entry;
       else cur.push(entry);
     }
+    // Re-order our entries to match the shipped hooks.json (merge used to leave
+    // stale order — e.g. post-tool-use before intent-anchor — breaking same-tool
+    // delivery of the anchor message).
+    const foreign = cur.filter((x) => x && !isOurs(x.command, keys));
+    const reordered = [];
+    const used = new Set();
+    for (const entry of entries) {
+      const k = keyOf(entry.command, keys);
+      if (!k || !isOurs(entry.command, keys)) continue;
+      const found = cur.find((x) => x && keyOf(x.command, keys) === k);
+      if (found) {
+        reordered.push(found);
+        used.add(k);
+      }
+    }
+    for (const x of cur) {
+      const k = keyOf(x?.command, keys);
+      if (isOurs(x?.command, keys) && k && !used.has(k)) reordered.push(x);
+    }
+    out.hooks[event] = [...reordered, ...foreign];
   }
   let preserved = 0;
   for (const entries of Object.values(out.hooks)) {
@@ -300,42 +320,62 @@ function verify() {
     return true;
   });
 
-  check('intent-anchor re-injects .scope.json every turn; latch re-arms at stop', () => {
-    // intent-anchor appends to feedback-<cid>.txt (the shared bus); drain via
-    // post-tool-use the same way the harness delivers additional_context.
+  check('intent-anchor scaffolds .scope.json and re-injects every turn', () => {
     const drainedOf = (cidv) => runHook(hook('post-tool-use'), { conversation_id: cidv });
     const anchorCid = 'npxv4';
     const scopePath = join(HOME, '.scope.json');
+    const transcriptPath = join(HOME, '.cursor', '.hooks-pending', 'verify-transcript-npxv4.jsonl');
+    const testQuery = 'fix grid symmetry and color tokens';
 
-    const cleanup = () => { try { rmSync(scopePath, { force: true }); } catch {} };
+    const cleanup = () => {
+      try { rmSync(scopePath, { force: true }); } catch {}
+      try { rmSync(transcriptPath, { force: true }); } catch {}
+    };
     cleanup();
 
-    // --- Case A: no .scope.json -> demand one be written --------------
-    runHook(hook('intent-anchor'), { conversation_id: anchorCid, cwd: HOME });
+    // Fake transcript so Get-LastUserQuery / scaffold can read the request.
+    const transcriptLine = JSON.stringify({
+      role: 'user',
+      message: { content: `<user_query>${testQuery}</user_query>` },
+    });
+    writeFileSync(transcriptPath, transcriptLine + '\n', 'utf8');
+
+    const anchorPayload = { conversation_id: anchorCid, cwd: HOME, transcript_path: transcriptPath };
+
+    // --- Case A: no .scope.json -> hook writes scaffold on disk ----------
+    runHook(hook('intent-anchor'), anchorPayload);
     let d = drainedOf(anchorCid);
-    if (!d.includes('INTENT ANCHOR') || !d.includes('NOT compiled your Anchor Set')) {
-      cleanup(); return { ok: false, detail: 'no-scope branch did not demand compilation' };
+    if (!existsSync(scopePath)) {
+      cleanup(); return { ok: false, detail: '.scope.json was not written to disk' };
+    }
+    let scope;
+    try { scope = JSON.parse(readFileSync(scopePath, 'utf8')); } catch {
+      cleanup(); return { ok: false, detail: '.scope.json scaffold is not valid JSON' };
+    }
+    if (scope.intent !== testQuery) {
+      cleanup(); return { ok: false, detail: `scaffold intent mismatch: ${scope.intent}` };
+    }
+    if (!d.includes('scaffold written') || !d.includes(testQuery)) {
+      cleanup(); return { ok: false, detail: 'scaffold branch did not inject written contract' };
     }
 
-    // --- Stop clears the latch (the regression path from 0.4.1) -------
+    // --- Stop clears the latch -------------------------------------------
     runHook(hook('final-review'), { conversation_id: anchorCid, status: 'completed' });
 
-    // --- Case B: scope exists -> re-inject contract every turn --------
+    // --- Case B: scope exists -> re-inject contract every turn -----------
     writeFileSync(scopePath, JSON.stringify({
       intent: 'fix grid symmetry and color tokens',
       files: ['src/grid.tsx'],
       acceptance: 'grid renders symmetric; tokens match palette',
     }));
-    // Turn 2 (no transcript in sandbox -> query unavailable -> re-inject branch).
-    runHook(hook('intent-anchor'), { conversation_id: anchorCid, cwd: HOME });
+    runHook(hook('intent-anchor'), { conversation_id: anchorCid, cwd: HOME, transcript_path: transcriptPath });
     d = drainedOf(anchorCid);
     if (!d.includes('fix grid symmetry and color tokens') || !d.includes('INTENT ANCHOR')) {
       cleanup(); return { ok: false, detail: 'contract not re-injected on turn 2' };
     }
 
-    // --- Stop clears the latch again; turn 3 must re-inject too -------
     runHook(hook('final-review'), { conversation_id: anchorCid, status: 'completed' });
-    runHook(hook('intent-anchor'), { conversation_id: anchorCid, cwd: HOME });
+    runHook(hook('intent-anchor'), { conversation_id: anchorCid, cwd: HOME, transcript_path: transcriptPath });
     d = drainedOf(anchorCid);
     if (!d.includes('fix grid symmetry and color tokens')) {
       cleanup(); return { ok: false, detail: 'contract not re-injected on turn 3 (latch stranded at stop)' };

package/linux/hooks/intent-anchor.sh

@@ -17,12 +17,12 @@
 #
 #   2. RE-COMPILE ON PROMPT CHANGE: hash the current <user_query> (via
 #      extract_last_user_query, which reads the transcript) and compare to
-#      last-query-<cid>.hash. If they differ, demand the agent UPDATE
-#      .scope.json to match the new request. If no .scope.json exists, demand
-#      one be written. The scope tracks the request - when the request moves,
-#      the scope moves with it. This part needs transcript_path in the payload;
-#      if it is absent the hook degrades to silent on change-detection but the
-#      re-injection above still runs.
+#      last-query-<cid>.hash. If they differ and a valid .scope.json exists,
+#      demand the agent UPDATE it. If no valid .scope.json exists and the query
+#      is available, WRITE a deterministic scaffold to disk (intent = query,
+#      files/acceptance = TODO placeholders) so re-injection always has real
+#      content from the first tool boundary — contract creation is not left to
+#      the LLM alone.
 #
 # Why postToolUse, not afterFileEdit: afterFileEdit only fires AFTER an edit
 # exists, and Cursor has no preToolUse for file edits. postToolUse fires after
@@ -115,6 +115,36 @@ EOF
     fi
 fi
 
+# --- deterministic scaffold (0.4.4) -------------------------------------------
+# When the query is available and there is no valid contract, write .scope.json
+# on disk — intent from <user_query>, TODO placeholders for files/acceptance.
+scaffold_written=0
+should_scaffold=0
+[ "$has_query" = "1" ] && [ "$scope_exists" != "1" ] && should_scaffold=1
+
+if [ "$should_scaffold" = "1" ]; then
+    if have_py; then
+        if python3 -c '
+import json, sys
+path, intent = sys.argv[1], sys.argv[2]
+obj = {
+    "intent": intent,
+    "files": ["<TODO: list files>"],
+    "acceptance": "<TODO: deterministic success check>",
+    "allow_growth": False,
+}
+with open(path, "w", encoding="utf-8") as f:
+    json.dump(obj, f, ensure_ascii=False)
+' "$scope_path" "$current_query" 2>/dev/null; then
+            scaffold_written=1
+            scope_exists=1
+            scope_intent="$current_query"
+            scope_acceptance="<TODO: deterministic success check>"
+            scope_files="<TODO: list files>"
+        fi
+    fi
+fi
+
 # --- compose the anchor message ---------------------------------------------
 if [ "$has_query" = "1" ]; then
     query_line="$current_query"
@@ -122,7 +152,17 @@ else
     query_line="(current request unavailable - no transcript in this event)"
 fi
 
-if [ "$scope_exists" != "1" ]; then
+if [ "$scaffold_written" = "1" ]; then
+    msg="INTENT ANCHOR (scaffold written to .scope.json) - contract materialized from your request.
+
+  intent:     $scope_intent
+  files:      $scope_files
+  acceptance: $scope_acceptance
+
+The hook wrote this scaffold to $scope_path — intent is locked from your current
+request. Replace the TODO placeholders with real files[] and acceptance before
+editing source. The contract is on disk and will be re-injected every turn."
+elif [ "$scope_exists" != "1" ]; then
     msg="INTENT ANCHOR (pre-compile) - no .scope.json found in $root.
 
 Current request:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursordoctrine",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "Thin self-review hooks for Cursor — the model is the auditor. Proactive intent compilation (pre-compile Anchor Set + per-turn .scope.json re-injection against Salience Dilution), intent-trace final review (Tier 0), unified 13-item anti-slop checklist, operational slop detection.",
   "bin": {
     "cursordoctrine": "bin/cli.mjs"

package/windows/hooks/intent-anchor.ps1

@@ -16,12 +16,12 @@
 #
 #   2. RE-COMPILE ON PROMPT CHANGE: hash the current <user_query> (via
 #      Get-LastUserQuery, which reads the transcript) and compare to
-#      last-query-<cid>.hash. If they differ, demand the agent UPDATE
-#      .scope.json to match the new request. If no .scope.json exists, demand
-#      one be written. The scope tracks the request - when the request moves,
-#      the scope moves with it. This part needs transcript_path in the payload;
-#      if it is absent the hook degrades to silent on change-detection but the
-#      re-injection above still runs.
+#      last-query-<cid>.hash. If they differ and a valid .scope.json exists,
+#      demand the agent UPDATE it. If no valid .scope.json exists and the query
+#      is available, WRITE a deterministic scaffold to disk (intent = query,
+#      files/acceptance = TODO placeholders) so re-injection always has real
+#      content from the first tool boundary — contract creation is not left to
+#      the LLM alone.
 #
 # Why postToolUse, not afterFileEdit: afterFileEdit only fires AFTER an edit
 # exists, and Cursor has no preToolUse for file edits. postToolUse fires after
@@ -93,12 +93,53 @@ if (Test-Path -LiteralPath $scopePath) {
     } catch { $scopeExists = $false }   # malformed JSON -> treat as missing
 }
 
+# --- deterministic scaffold (0.4.4) -----------------------------------------
+# When the query is available and there is no valid contract, the hook writes
+# .scope.json itself — intent from <user_query>, obvious TODO placeholders
+# for files/acceptance. Fires on prompt change (incl. first turn: empty prev
+# hash) or whenever the contract is still missing on a turn boundary.
+$scaffoldWritten = $false
+$shouldScaffold = $hasQuery -and (-not $scopeExists)
+if ($shouldScaffold) {
+    try {
+        $scaffold = [ordered]@{
+            intent       = $currentQuery
+            files        = @('<TODO: list files>')
+            acceptance   = '<TODO: deterministic success check>'
+            allow_growth = $false
+        }
+        $json = $scaffold | ConvertTo-Json -Depth 4 -Compress
+        $dir = Split-Path -Parent $scopePath
+        if ($dir -and -not (Test-Path -LiteralPath $dir)) {
+            New-Item -ItemType Directory -Path $dir -Force | Out-Null
+        }
+        [System.IO.File]::WriteAllText($scopePath, $json, [System.Text.UTF8Encoding]::new($false))
+        $scopeIntent = $currentQuery
+        $scopeAcceptance = '<TODO: deterministic success check>'
+        $scopeFiles = '<TODO: list files>'
+        $scopeExists = $true
+        $scaffoldWritten = $true
+    } catch { }
+}
+
 # --- compose the anchor message ---------------------------------------------
 # Re-injection (req 2) is unconditional whenever a contract exists.
-# Recompile-demand (req 1) fires when there is no contract, or the prompt moved.
+# Recompile-demand (req 1) fires when the prompt moved but a real contract exists.
 $queryLine = if ($hasQuery) { $currentQuery } else { '(current request unavailable - no transcript in this event)' }
 
-if (-not $scopeExists) {
+if ($scaffoldWritten) {
+    $msg = @"
+INTENT ANCHOR (scaffold written to .scope.json) - contract materialized from your request.
+
+  intent:     $scopeIntent
+  files:      $scopeFiles
+  acceptance: $scopeAcceptance
+
+The hook wrote this scaffold to $scopePath — intent is locked from your current
+request. Replace the TODO placeholders with real files[] and acceptance before
+editing source. The contract is on disk and will be re-injected every turn.
+"@
+} elseif (-not $scopeExists) {
     $msg = @"
 INTENT ANCHOR (pre-compile) - no .scope.json found in $root.