4runr-cursor-setup 0.1.19 → 0.1.21

package/README.md

@@ -34,9 +34,11 @@ npx -y 4runr-cursor-setup@latest doctor --strict
 
 ```bash
 # Repair / normalize any repo (safe)
+# Installs: manifest + docs + .cursor/rules/project.md
 npx -y 4runr-cursor-setup@latest doctor --fix --purge-orphans --strict
 
 # Install core commands (updates if already installed)
+# Installs: .cursor/commands/* (4runr-start.md, 4runr-close.md)
 npx -y 4runr-cursor-setup@latest add core --force
 
 # CI / health check (fails if issues)
@@ -46,6 +48,8 @@ npx -y 4runr-cursor-setup@latest doctor --strict
 npx -y 4runr-cursor-setup@latest doctor --plan
 ```
 
+**Note:** If Cursor UI doesn't show Project Rules after running `doctor --fix`, reload the window (Ctrl+Shift+P → Developer: Reload Window).
+
 ## Contract / Invariants
 
 - Tool never overwrites un-managed files (even with `--force`)
@@ -111,14 +115,26 @@ The `/close` command (from the `core` group) produces a session handoff summary.
 - **No hallucination:** The command cannot invent work, summarize changes without evidence, or list files that don't exist
 - **Clean repo → clean close:** A clean repository results in a read-only close output
 
-### Verification Block
-
-Every `/close` output starts with a mandatory verification block:
-- `git status` output
-- `git diff --name-only` output
-- Explicit list of modified files (or "NONE")
-
-If evidence is unavailable, the output must state "NOT AVAILABLE" rather than guessing.
+### Verification Gate
+
+Every `/close` output starts with a mandatory **REPO CONTEXT PROOF** section:
+- `pwd` (current directory)
+- `git rev-parse --show-toplevel` (repo root verification)
+- `git status --porcelain` (working tree status)
+
+**If git is unavailable (not a git repo or wrong directory):**
+- `/close` switches to **NON-GIT MODE**
+- Output states: "NOT A GIT REPO / WRONG DIRECTORY"
+- **No claims about file modifications, diffs, or line numbers**
+- Provides a corrective hint (cd to repo root, or initialize git)
+
+**If git is available:**
+- Proceeds with **VERIFICATION** block:
+  - `git status` output
+  - `git diff --name-only` output
+  - Explicit list of modified files (or "NONE")
+- Only lists changes with evidence (git diff, file paths, quoted snippets)
+- If evidence is unavailable, states "NOT AVAILABLE" rather than guessing
 
 ### What It Does
 

package/dist/commands/commands.js

@@ -248,8 +248,26 @@ export function addGroup(opts) {
     else {
         console.log('Installed group "' + group + '" into .cursor/commands (' + copied + " file(s) written).");
     }
-    if (group === "core")
+    // Check for rules file and provide hints (for core group, after successful write or when already installed)
+    if (group === "core" && (copied > 0 || (copied === 0 && !hasAnyFileToWrite))) {
+        const rulesPath = path.join(cwd, ".cursor/rules/project.md");
+        const rulesExistedBefore = fs.existsSync(rulesPath);
+        // Call ensureMemory (creates empty file if missing)
         ensureMemory(cwd);
+        // Check if rules were missing before ensureMemory created them
+        if (!rulesExistedBefore) {
+            // Rules were missing, hint user to run doctor --fix for proper setup
+            console.log("Hint: Project rules not found (.cursor/rules/project.md). Run: doctor --fix --purge-orphans --strict");
+        }
+        else if (fs.existsSync(rulesPath)) {
+            // Rules exist, show reload tip
+            console.log("Cursor tip: if rules exist but don't appear, reload Cursor window (Ctrl+Shift+P → Developer: Reload Window).");
+        }
+    }
+    else if (group === "core") {
+        // Still call ensureMemory even if we don't show hints
+        ensureMemory(cwd);
+    }
 }
 export function removeGroup(opts) {
     const { cwd, group, dryRun = false } = opts;

package/dist/commands/doctor.js

@@ -79,9 +79,25 @@ function purgeOrphans(cwd, dryRun, silent) {
     return { count: deleted, files: deletedFiles };
 }
 export function doctor(cwd, toolVersion, opts) {
+    // Track files created/verified during --fix
+    const rulesPath = path.join(cwd, ".cursor/rules/project.md");
+    const rulesExistedBefore = opts.fix && !opts.dryRun ? fs.existsSync(rulesPath) : false;
+    let rulesCreated = false;
+    let rulesVerified = false;
     // Run fixes first if requested
     if (opts.fix) {
         ensureMemory(cwd, { dryRun: !!opts.dryRun });
+        // Check if rules were created or verified
+        if (!opts.dryRun) {
+            if (fs.existsSync(rulesPath)) {
+                if (!rulesExistedBefore) {
+                    rulesCreated = true;
+                }
+                else {
+                    rulesVerified = true;
+                }
+            }
+        }
         // Always ensure manifest exists when --fix is used
         if (!loadManifest(cwd)) {
             const nm = createEmptyManifest(toolVersion);
@@ -190,6 +206,20 @@ export function doctor(cwd, toolVersion, opts) {
     if (opts.plan) {
         planItems = generatePlan(issues, m || null);
     }
+    // Prepare fixed files info for output
+    const fixedInfo = { created: [], verified: [] };
+    const notes = [];
+    if (opts.fix && !opts.dryRun) {
+        if (rulesCreated) {
+            fixedInfo.created.push(".cursor/rules/project.md");
+        }
+        else if (rulesVerified) {
+            fixedInfo.verified.push(".cursor/rules/project.md");
+        }
+        if (fs.existsSync(rulesPath)) {
+            notes.push("Reload Cursor window to apply Project Rules.");
+        }
+    }
     if (opts.json) {
         const jsonOutput = { ok: !hasErrors, issues };
         if (purgedInfo) {
@@ -198,6 +228,12 @@ export function doctor(cwd, toolVersion, opts) {
         if (opts.plan) {
             jsonOutput.plan = planItems;
         }
+        if (opts.fix && (fixedInfo.created.length > 0 || fixedInfo.verified.length > 0)) {
+            jsonOutput.fixed = fixedInfo;
+        }
+        if (notes.length > 0) {
+            jsonOutput.notes = notes;
+        }
         console.log(JSON.stringify(jsonOutput, null, 2));
     }
     else {
@@ -220,6 +256,18 @@ export function doctor(cwd, toolVersion, opts) {
         }
         else {
             // Normal output mode
+            // Print rules status if --fix was used
+            if (opts.fix && !opts.dryRun) {
+                if (rulesCreated) {
+                    console.log("CREATED rules: .cursor/rules/project.md");
+                }
+                else if (rulesVerified) {
+                    console.log("OK rules: .cursor/rules/project.md");
+                }
+                if (fs.existsSync(rulesPath)) {
+                    console.log("Note: if Cursor doesn't show Project Rules yet, reload the window (Ctrl+Shift+P → Developer: Reload Window).");
+                }
+            }
             if (issues.length === 0)
                 console.log("✅ doctor: OK");
             else {

package/dist/templates/commands/core/4runr-close.md

@@ -13,11 +13,56 @@ We are ending this session. Produce a clean handoff.
 - **Do NOT infer or summarize changes unless you can point to the exact file and evidence.**
 - **Do NOT describe "improvements", "fixes", or "updates" without proof.**
 - **Do NOT list files unless they actually exist or were modified.**
+- **Do NOT claim line numbers, diffs, or file changes without evidence.**
 - **If unsure, state uncertainty explicitly.**
 
-## Mandatory Verification Block
+## Mandatory Repo Context Proof (FIRST STEP)
 
-**You MUST start your output with this verification block:**
+**You MUST run these commands FIRST and report the results:**
+
+```
+REPO CONTEXT PROOF
+- pwd: [run `pwd` and report the current directory]
+- git rev-parse --show-toplevel: [run `git rev-parse --show-toplevel` and report the repo root or ERROR]
+- git status --porcelain: [run `git status --porcelain` and report output or ERROR]
+```
+
+**If `git rev-parse --show-toplevel` fails (returns error or non-zero exit code):**
+- **STOP. Switch to NON-GIT MODE immediately.**
+- Do NOT attempt to run any other git commands.
+- Do NOT produce a "What changed" section.
+- Do NOT claim any file modifications, diffs, or line numbers.
+
+## Mode C: NON-GIT MODE (Git Unavailable)
+
+**Use this if `git rev-parse --show-toplevel` fails:**
+
+1. **REPO CONTEXT PROOF** (mandatory, at top)
+   - pwd: [actual current directory]
+   - git rev-parse --show-toplevel: **ERROR - NOT A GIT REPO / WRONG DIRECTORY**
+   - git status --porcelain: **NOT RUN (git unavailable)**
+
+2. **Session summary**
+   - **MUST state explicitly:**
+     ```
+     NOT A GIT REPO / WRONG DIRECTORY
+     
+     Cannot verify changes. No claims about file modifications, diffs, or line numbers.
+     ```
+
+3. **Corrective step**
+   - **Provide ONE corrective hint:**
+     - "cd to repo root / open correct folder"
+     - OR: "initialize git (git init) if intended"
+
+4. **Next steps** (if any, minimal)
+   - 1–3 steps, atomic
+
+**Output must be short and boring. No invented "evidence". No "What changed" section. No file lists without proof.**
+
+## Mandatory Verification Block (Git Mode Only)
+
+**Use this ONLY if `git rev-parse --show-toplevel` succeeds:**
 
 ```
 VERIFICATION
@@ -28,35 +73,42 @@ VERIFICATION
 
 **If you cannot populate this truthfully, you must say "NOT AVAILABLE" for that field.**
 
-## Output Format
+## Output Format (Git Mode Only)
 
 ### Mode A: Evidence Mode (Changes Exist)
 
 **Use this ONLY if you have evidence of changes:**
 
-1. **VERIFICATION** (mandatory, at top)
+1. **REPO CONTEXT PROOF** (mandatory, at top)
+   - pwd: [actual current directory]
+   - git rev-parse --show-toplevel: [actual repo root]
+   - git status --porcelain: [actual output]
+
+2. **VERIFICATION** (mandatory)
    - git status: [actual output or "not run"]
    - git diff --name-only: [list or "none"]
    - Files modified: [explicit list or "NONE"]
 
-2. **What changed** (evidence-required)
-   - For each claimed change, include:
-     - File path
-     - What changed (specific, not vague)
-     - Evidence: diff snippet, command output, or exact file content quote
+3. **What changed** (evidence-required, strict gating)
+   - **For each claimed change, you MUST include ONE of:**
+     - `git diff --name-only` showing the file
+     - A `git diff` snippet (exact quoted output)
+     - A direct file excerpt with explicit file path + exact quoted lines
+   - **If you cannot provide evidence, write "Not verified" and omit from "What changed".**
+   - **No evidence → do not claim changes.**
 
-3. **Files involved**
-   - Exact file paths (only files that exist or were modified)
+4. **Files involved**
+   - Exact file paths (only files that exist or were modified, with evidence)
 
-4. **Decisions** (if any)
+5. **Decisions** (if any)
    - Decision
    - Why
    - Trade-offs
 
-5. **Next steps**
+6. **Next steps**
    - 3–7 steps, atomic
 
-6. **Project memory updates**
+7. **Project memory updates**
    - Provide copy-paste text for:
      - docs/status.md
      - docs/todo.md
@@ -66,27 +118,32 @@ VERIFICATION
 
 **Use this if no evidence of changes exists:**
 
-1. **VERIFICATION** (mandatory, at top)
+1. **REPO CONTEXT PROOF** (mandatory, at top)
+   - pwd: [actual current directory]
+   - git rev-parse --show-toplevel: [actual repo root]
+   - git status --porcelain: [actual output]
+
+2. **VERIFICATION** (mandatory)
    - git status: [actual output]
    - git diff --name-only: [actual output]
    - Files modified: NONE
 
-2. **Session summary**
+3. **Session summary**
    - **MUST state explicitly:**
      ```
      No files were created, modified, or deleted.
      This session was read-only inspection only.
      ```
 
-3. **What was inspected** (optional, only if relevant)
+4. **What was inspected** (optional, only if relevant)
    - Files read
    - Commands run
    - Information gathered
 
-4. **Next steps** (if any)
+5. **Next steps** (if any)
    - 3–7 steps, atomic
 
-5. **Project memory updates** (if any changes to understanding)
+6. **Project memory updates** (if any changes to understanding)
    - Provide copy-paste text for:
      - docs/status.md
      - docs/todo.md
@@ -99,4 +156,7 @@ VERIFICATION
 - No "this should work"
 - No vague summaries without evidence
 - No claiming changes without proof
+- No line numbers, diffs, or file changes without evidence
 - Clean repo → clean close (read-only mode)
+- If git is unavailable, ignore change-reporting sections entirely
+- /close is read-only: suggest commands, do not run changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "4runr-cursor-setup",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "",
   "main": "index.js",
   "scripts": {

package/scripts/smoke.ps1

@@ -69,6 +69,16 @@ try {
     Pop-Location
     Write-Host ""
 
+    # Verify .cursor/rules/project.md exists after doctor fix
+    $rulesPath = Join-Path $tempDir ".cursor\rules\project.md"
+    if (-not (Test-Path $rulesPath)) {
+        Write-Host "FAILED: .cursor/rules/project.md not found after doctor --fix" -ForegroundColor Red
+        $exitCode = 1
+    } else {
+        Write-Host "PASSED: .cursor/rules/project.md exists" -ForegroundColor Green
+    }
+    Write-Host ""
+
     if ($exitCode -ne 0) {
         exit $exitCode
     }

package/src/templates/commands/core/4runr-close.md

@@ -13,11 +13,56 @@ We are ending this session. Produce a clean handoff.
 - **Do NOT infer or summarize changes unless you can point to the exact file and evidence.**
 - **Do NOT describe "improvements", "fixes", or "updates" without proof.**
 - **Do NOT list files unless they actually exist or were modified.**
+- **Do NOT claim line numbers, diffs, or file changes without evidence.**
 - **If unsure, state uncertainty explicitly.**
 
-## Mandatory Verification Block
+## Mandatory Repo Context Proof (FIRST STEP)
 
-**You MUST start your output with this verification block:**
+**You MUST run these commands FIRST and report the results:**
+
+```
+REPO CONTEXT PROOF
+- pwd: [run `pwd` and report the current directory]
+- git rev-parse --show-toplevel: [run `git rev-parse --show-toplevel` and report the repo root or ERROR]
+- git status --porcelain: [run `git status --porcelain` and report output or ERROR]
+```
+
+**If `git rev-parse --show-toplevel` fails (returns error or non-zero exit code):**
+- **STOP. Switch to NON-GIT MODE immediately.**
+- Do NOT attempt to run any other git commands.
+- Do NOT produce a "What changed" section.
+- Do NOT claim any file modifications, diffs, or line numbers.
+
+## Mode C: NON-GIT MODE (Git Unavailable)
+
+**Use this if `git rev-parse --show-toplevel` fails:**
+
+1. **REPO CONTEXT PROOF** (mandatory, at top)
+   - pwd: [actual current directory]
+   - git rev-parse --show-toplevel: **ERROR - NOT A GIT REPO / WRONG DIRECTORY**
+   - git status --porcelain: **NOT RUN (git unavailable)**
+
+2. **Session summary**
+   - **MUST state explicitly:**
+     ```
+     NOT A GIT REPO / WRONG DIRECTORY
+     
+     Cannot verify changes. No claims about file modifications, diffs, or line numbers.
+     ```
+
+3. **Corrective step**
+   - **Provide ONE corrective hint:**
+     - "cd to repo root / open correct folder"
+     - OR: "initialize git (git init) if intended"
+
+4. **Next steps** (if any, minimal)
+   - 1–3 steps, atomic
+
+**Output must be short and boring. No invented "evidence". No "What changed" section. No file lists without proof.**
+
+## Mandatory Verification Block (Git Mode Only)
+
+**Use this ONLY if `git rev-parse --show-toplevel` succeeds:**
 
 ```
 VERIFICATION
@@ -28,35 +73,42 @@ VERIFICATION
 
 **If you cannot populate this truthfully, you must say "NOT AVAILABLE" for that field.**
 
-## Output Format
+## Output Format (Git Mode Only)
 
 ### Mode A: Evidence Mode (Changes Exist)
 
 **Use this ONLY if you have evidence of changes:**
 
-1. **VERIFICATION** (mandatory, at top)
+1. **REPO CONTEXT PROOF** (mandatory, at top)
+   - pwd: [actual current directory]
+   - git rev-parse --show-toplevel: [actual repo root]
+   - git status --porcelain: [actual output]
+
+2. **VERIFICATION** (mandatory)
    - git status: [actual output or "not run"]
    - git diff --name-only: [list or "none"]
    - Files modified: [explicit list or "NONE"]
 
-2. **What changed** (evidence-required)
-   - For each claimed change, include:
-     - File path
-     - What changed (specific, not vague)
-     - Evidence: diff snippet, command output, or exact file content quote
+3. **What changed** (evidence-required, strict gating)
+   - **For each claimed change, you MUST include ONE of:**
+     - `git diff --name-only` showing the file
+     - A `git diff` snippet (exact quoted output)
+     - A direct file excerpt with explicit file path + exact quoted lines
+   - **If you cannot provide evidence, write "Not verified" and omit from "What changed".**
+   - **No evidence → do not claim changes.**
 
-3. **Files involved**
-   - Exact file paths (only files that exist or were modified)
+4. **Files involved**
+   - Exact file paths (only files that exist or were modified, with evidence)
 
-4. **Decisions** (if any)
+5. **Decisions** (if any)
    - Decision
    - Why
    - Trade-offs
 
-5. **Next steps**
+6. **Next steps**
    - 3–7 steps, atomic
 
-6. **Project memory updates**
+7. **Project memory updates**
    - Provide copy-paste text for:
      - docs/status.md
      - docs/todo.md
@@ -66,27 +118,32 @@ VERIFICATION
 
 **Use this if no evidence of changes exists:**
 
-1. **VERIFICATION** (mandatory, at top)
+1. **REPO CONTEXT PROOF** (mandatory, at top)
+   - pwd: [actual current directory]
+   - git rev-parse --show-toplevel: [actual repo root]
+   - git status --porcelain: [actual output]
+
+2. **VERIFICATION** (mandatory)
    - git status: [actual output]
    - git diff --name-only: [actual output]
    - Files modified: NONE
 
-2. **Session summary**
+3. **Session summary**
    - **MUST state explicitly:**
      ```
      No files were created, modified, or deleted.
      This session was read-only inspection only.
      ```
 
-3. **What was inspected** (optional, only if relevant)
+4. **What was inspected** (optional, only if relevant)
    - Files read
    - Commands run
    - Information gathered
 
-4. **Next steps** (if any)
+5. **Next steps** (if any)
    - 3–7 steps, atomic
 
-5. **Project memory updates** (if any changes to understanding)
+6. **Project memory updates** (if any changes to understanding)
    - Provide copy-paste text for:
      - docs/status.md
      - docs/todo.md
@@ -99,4 +156,7 @@ VERIFICATION
 - No "this should work"
 - No vague summaries without evidence
 - No claiming changes without proof
+- No line numbers, diffs, or file changes without evidence
 - Clean repo → clean close (read-only mode)
+- If git is unavailable, ignore change-reporting sections entirely
+- /close is read-only: suggest commands, do not run changes