4runr-cursor-setup 0.1.17 → 0.1.19

package/README.md

@@ -1,6 +1,34 @@
 # 4runr-cursor-setup
 
-**Full Git usage guide:** [docs/USAGE_GIT.md](docs/USAGE_GIT.md)
+**Documentation:**
+- [Command Reference](docs/COMMANDS.md) — Complete command and flag documentation
+- [Git Usage Guide](docs/USAGE_GIT.md) — End-to-end Git repo usage guide
+
+## New Repo Quick Start
+
+**PowerShell:**
+```powershell
+# Step 1: Repair / normalize repo (safe)
+npx -y 4runr-cursor-setup@latest doctor --fix --purge-orphans --strict
+
+# Step 2: Install core commands
+npx -y 4runr-cursor-setup@latest add core
+
+# Step 3: Verify health
+npx -y 4runr-cursor-setup@latest doctor --strict
+```
+
+**Bash:**
+```bash
+# Step 1: Repair / normalize repo (safe)
+npx -y 4runr-cursor-setup@latest doctor --fix --purge-orphans --strict
+
+# Step 2: Install core commands
+npx -y 4runr-cursor-setup@latest add core
+
+# Step 3: Verify health
+npx -y 4runr-cursor-setup@latest doctor --strict
+```
 
 ## Golden Path
 
@@ -8,14 +36,14 @@
 # Repair / normalize any repo (safe)
 npx -y 4runr-cursor-setup@latest doctor --fix --purge-orphans --strict
 
-# Install core commands
-npx -y 4runr-cursor-setup@latest add core
+# Install core commands (updates if already installed)
+npx -y 4runr-cursor-setup@latest add core --force
 
 # CI / health check (fails if issues)
 npx -y 4runr-cursor-setup@latest doctor --strict
 
-# Machine-readable audit (for automation)
-npx -y 4runr-cursor-setup@latest doctor --json
+# Read-only audit plan (for reviews)
+npx -y 4runr-cursor-setup@latest doctor --plan
 ```
 
 ## Contract / Invariants
@@ -72,26 +100,138 @@ npx -y 4runr-cursor-setup@latest add core --dry-run
 - `governance`: Governance commands (decision, scope-change)
 - `debugging`: Debugging commands (repro, verify)
 
-## Troubleshooting
+## What `/close` Means
 
-### npx Cache Issues
+The `/close` command (from the `core` group) produces a session handoff summary. **It is a reflection of verified repo state, not a progress generator.**
 
-If `npx -y 4runr-cursor-setup@latest` fails with `ETARGET` but the version exists on npm:
+### Key Rules
 
-This is an npx cache desync. Clear the cache and retry:
+- **Evidence-gated:** Every claimed change must be proven with repo evidence (git status, git diff, file paths, quoted snippets)
+- **Read-only sessions:** If no files were changed, `/close` must explicitly state: "No files were created, modified, or deleted. This session was read-only inspection only."
+- **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
 
-**PowerShell:**
+### 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.
+
+### What It Does
+
+- **With changes:** Lists verified changes with evidence (file paths, diffs, quotes)
+- **Without changes:** States explicitly that the session was read-only
+- **Always:** Provides next steps and project memory updates (docs/status.md, docs/todo.md, docs/decisions.md)
+
+**Important:** `/close` reflects only what actually happened in the repo. It does not generate progress or invent improvements.
+
+### Upgrading Existing Repos
+
+To update the `/close` template (and other core commands) in an existing repo:
+
+```bash
+npx -y 4runr-cursor-setup@latest add core --force
+```
+
+This updates the templates to the latest version while preserving your project structure.
+
+## Common Scenarios
+
+### "0 files written" When Adding a Group
+
+**Reasons and exact next steps:**
+
+1. **Already installed and managed** (normal)
+   - Files exist, have marker, and are in manifest
+   - **Action:** Nothing to do. This is expected.
+
+2. **Orphan marker files**
+   - Files have marker but aren't in manifest
+   - **Fix:**
+     ```bash
+     npx -y 4runr-cursor-setup@latest doctor --purge-orphans
+     npx -y 4runr-cursor-setup@latest add planning
+     ```
+     (Replace `planning` with the actual group name)
+
+3. **Unmanaged collision**
+   - Files exist without marker (user-created)
+   - Tool will never overwrite these
+   - **Fix (manual):**
+     ```bash
+     # Rename or move the colliding file
+     mv .cursor/commands/4runr-start.md .cursor/commands/4runr-start.md.backup
+     # Then re-run add
+     npx -y 4runr-cursor-setup@latest add core
+     ```
+
+### Orphan Marker Files
+
+**What they are:**
+- Files in `.cursor/commands/` with the managed marker (`<!-- managed-by: 4runr-cursor-setup -->`) but not listed in the manifest
+
+**Why they exist:**
+- Manifest was deleted or reset
+- Files were manually created with marker
+- Manifest drift
+
+**Fix:**
+```bash
+npx -y 4runr-cursor-setup@latest doctor --purge-orphans
+```
+
+**What it does:**
+- Deletes only orphan marker files (safe)
+- Never deletes managed files or unmarked files
+
+### Unmanaged Collision
+
+**What it is:**
+- A file exists at a path where the tool wants to install a template, but the file doesn't have the managed marker
+
+**Why it happens:**
+- User created a file manually
+- File was created before tool installation
+
+**Resolution (manual):**
+1. Rename or move the colliding file:
+   ```bash
+   mv .cursor/commands/4runr-start.md .cursor/commands/4runr-start.md.backup
+   ```
+2. Re-run add:
+   ```bash
+   npx -y 4runr-cursor-setup@latest add core
+   ```
+
+**Important:** The tool will never overwrite unmanaged files, even with `--force`.
+
+### ETARGET / npx Cache Desync
+
+**Symptom:**
+- `npx -y 4runr-cursor-setup@latest` fails with `ETARGET` but the version exists on npm
+
+**Cause:**
+- npx cache is out of sync with npm registry
+
+**Fix (PowerShell):**
 ```powershell
 npm cache clean --force
 Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx" -ErrorAction SilentlyContinue
 ```
 
-**Bash:**
+**Fix (Bash):**
 ```bash
 npm cache clean --force
 rm -rf ~/.npm/_npx
 ```
 
+**Then retry your command.**
+
+## Troubleshooting
+
 ### PowerShell Error: The '<' operator is reserved for future use
 
 **Cause:** Copied placeholder like `GROUP` from documentation without replacing it.

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

@@ -4,28 +4,99 @@
 
 We are ending this session. Produce a clean handoff.
 
-## Hard rules
-- No emojis
-- No assumptions
-- No "this should work"
+## 🔒 CRITICAL: Evidence-Gated Close (Non-Negotiable)
+
+**You MUST prove every claimed change with repo evidence. If you cannot prove it, you must not claim it occurred.**
+
+### Anti-Hallucination Rules
+
+- **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.**
+- **If unsure, state uncertainty explicitly.**
+
+## Mandatory Verification Block
+
+**You MUST start your output with this verification block:**
+
+```
+VERIFICATION
+- git status: [run `git status` and report: clean / modified files / not run]
+- git diff --name-only: [run `git diff --name-only` and list files or "none"]
+- Files modified: [explicit list of file paths or "NONE"]
+```
+
+**If you cannot populate this truthfully, you must say "NOT AVAILABLE" for that field.**
+
+## Output Format
+
+### Mode A: Evidence Mode (Changes Exist)
+
+**Use this ONLY if you have evidence of changes:**
 
-## Output format
-### 1) What changed
-- Bullet list
+1. **VERIFICATION** (mandatory, at top)
+   - git status: [actual output or "not run"]
+   - git diff --name-only: [list or "none"]
+   - Files modified: [explicit list or "NONE"]
 
-### 2) Files involved
-- Exact file paths
+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) Decisions (if any)
-- Decision
-- Why
-- Trade-offs
+3. **Files involved**
+   - Exact file paths (only files that exist or were modified)
 
-### 4) Next steps
-- 3–7 steps, atomic
+4. **Decisions** (if any)
+   - Decision
+   - Why
+   - Trade-offs
 
-### 5) Project memory updates
-Provide copy-paste text for:
-- docs/status.md
-- docs/todo.md
-- docs/decisions.md (only if needed)
+5. **Next steps**
+   - 3–7 steps, atomic
+
+6. **Project memory updates**
+   - Provide copy-paste text for:
+     - docs/status.md
+     - docs/todo.md
+     - docs/decisions.md (only if needed)
+
+### Mode B: Read-Only Mode (No Changes)
+
+**Use this if no evidence of changes exists:**
+
+1. **VERIFICATION** (mandatory, at top)
+   - git status: [actual output]
+   - git diff --name-only: [actual output]
+   - Files modified: NONE
+
+2. **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)
+   - Files read
+   - Commands run
+   - Information gathered
+
+4. **Next steps** (if any)
+   - 3–7 steps, atomic
+
+5. **Project memory updates** (if any changes to understanding)
+   - Provide copy-paste text for:
+     - docs/status.md
+     - docs/todo.md
+     - docs/decisions.md (only if needed)
+
+## Hard Rules
+
+- No emojis
+- No assumptions
+- No "this should work"
+- No vague summaries without evidence
+- No claiming changes without proof
+- Clean repo → clean close (read-only mode)

package/package.json

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

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

@@ -4,28 +4,99 @@
 
 We are ending this session. Produce a clean handoff.
 
-## Hard rules
-- No emojis
-- No assumptions
-- No "this should work"
+## 🔒 CRITICAL: Evidence-Gated Close (Non-Negotiable)
+
+**You MUST prove every claimed change with repo evidence. If you cannot prove it, you must not claim it occurred.**
+
+### Anti-Hallucination Rules
+
+- **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.**
+- **If unsure, state uncertainty explicitly.**
+
+## Mandatory Verification Block
+
+**You MUST start your output with this verification block:**
+
+```
+VERIFICATION
+- git status: [run `git status` and report: clean / modified files / not run]
+- git diff --name-only: [run `git diff --name-only` and list files or "none"]
+- Files modified: [explicit list of file paths or "NONE"]
+```
+
+**If you cannot populate this truthfully, you must say "NOT AVAILABLE" for that field.**
+
+## Output Format
+
+### Mode A: Evidence Mode (Changes Exist)
+
+**Use this ONLY if you have evidence of changes:**
 
-## Output format
-### 1) What changed
-- Bullet list
+1. **VERIFICATION** (mandatory, at top)
+   - git status: [actual output or "not run"]
+   - git diff --name-only: [list or "none"]
+   - Files modified: [explicit list or "NONE"]
 
-### 2) Files involved
-- Exact file paths
+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) Decisions (if any)
-- Decision
-- Why
-- Trade-offs
+3. **Files involved**
+   - Exact file paths (only files that exist or were modified)
 
-### 4) Next steps
-- 3–7 steps, atomic
+4. **Decisions** (if any)
+   - Decision
+   - Why
+   - Trade-offs
 
-### 5) Project memory updates
-Provide copy-paste text for:
-- docs/status.md
-- docs/todo.md
-- docs/decisions.md (only if needed)
+5. **Next steps**
+   - 3–7 steps, atomic
+
+6. **Project memory updates**
+   - Provide copy-paste text for:
+     - docs/status.md
+     - docs/todo.md
+     - docs/decisions.md (only if needed)
+
+### Mode B: Read-Only Mode (No Changes)
+
+**Use this if no evidence of changes exists:**
+
+1. **VERIFICATION** (mandatory, at top)
+   - git status: [actual output]
+   - git diff --name-only: [actual output]
+   - Files modified: NONE
+
+2. **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)
+   - Files read
+   - Commands run
+   - Information gathered
+
+4. **Next steps** (if any)
+   - 3–7 steps, atomic
+
+5. **Project memory updates** (if any changes to understanding)
+   - Provide copy-paste text for:
+     - docs/status.md
+     - docs/todo.md
+     - docs/decisions.md (only if needed)
+
+## Hard Rules
+
+- No emojis
+- No assumptions
+- No "this should work"
+- No vague summaries without evidence
+- No claiming changes without proof
+- Clean repo → clean close (read-only mode)