cursordoctrine 0.6.1 → 0.6.3

package/bin/cli.mjs

@@ -334,22 +334,18 @@ 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.
+    // --- Case 0: no .scope.json + NO transcript -> do NOT write hollow scaffold
+    // 0.6.1: never persist intent=<TODO> when the request is unreadable. Emit the
+    // pre-compile demand so the agent authors a real contract from the chat.
     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)' };
+    if (existsSync(scopePath)) {
+      cleanup(); return { ok: false, detail: 'hollow scaffold written without transcript (0.6.1 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}` };
+    if (!d0.includes('INTENT ANCHOR (pre-compile)')) {
+      cleanup(); return { ok: false, detail: 'no-transcript turn did not emit pre-compile demand' };
     }
-    // Clear the latch + scope so Case A starts fresh (with a real query this time).
+    // Clear the latch so Case A starts fresh (with a real query this time).
     runHook(hook('final-review'), { conversation_id: anchorCid, status: 'completed' });
     cleanup();
 

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/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.1",
+  "version": "0.6.3",
   "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/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"
 }