4runr-cursor-setup 0.1.18 → 0.1.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -36,14 +36,14 @@ npx -y 4runr-cursor-setup@latest doctor --strict
|
|
|
36
36
|
# Repair / normalize any repo (safe)
|
|
37
37
|
npx -y 4runr-cursor-setup@latest doctor --fix --purge-orphans --strict
|
|
38
38
|
|
|
39
|
-
# Install core commands
|
|
40
|
-
npx -y 4runr-cursor-setup@latest add core
|
|
39
|
+
# Install core commands (updates if already installed)
|
|
40
|
+
npx -y 4runr-cursor-setup@latest add core --force
|
|
41
41
|
|
|
42
42
|
# CI / health check (fails if issues)
|
|
43
43
|
npx -y 4runr-cursor-setup@latest doctor --strict
|
|
44
44
|
|
|
45
|
-
#
|
|
46
|
-
npx -y 4runr-cursor-setup@latest doctor --
|
|
45
|
+
# Read-only audit plan (for reviews)
|
|
46
|
+
npx -y 4runr-cursor-setup@latest doctor --plan
|
|
47
47
|
```
|
|
48
48
|
|
|
49
49
|
## Contract / Invariants
|
|
@@ -100,6 +100,56 @@ npx -y 4runr-cursor-setup@latest add core --dry-run
|
|
|
100
100
|
- `governance`: Governance commands (decision, scope-change)
|
|
101
101
|
- `debugging`: Debugging commands (repro, verify)
|
|
102
102
|
|
|
103
|
+
## What `/close` Means
|
|
104
|
+
|
|
105
|
+
The `/close` command (from the `core` group) produces a session handoff summary. **It is a reflection of verified repo state, not a progress generator.**
|
|
106
|
+
|
|
107
|
+
### Key Rules
|
|
108
|
+
|
|
109
|
+
- **Evidence-gated:** Every claimed change must be proven with repo evidence (git status, git diff, file paths, quoted snippets)
|
|
110
|
+
- **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."
|
|
111
|
+
- **No hallucination:** The command cannot invent work, summarize changes without evidence, or list files that don't exist
|
|
112
|
+
- **Clean repo → clean close:** A clean repository results in a read-only close output
|
|
113
|
+
|
|
114
|
+
### Verification Gate
|
|
115
|
+
|
|
116
|
+
Every `/close` output starts with a mandatory **REPO CONTEXT PROOF** section:
|
|
117
|
+
- `pwd` (current directory)
|
|
118
|
+
- `git rev-parse --show-toplevel` (repo root verification)
|
|
119
|
+
- `git status --porcelain` (working tree status)
|
|
120
|
+
|
|
121
|
+
**If git is unavailable (not a git repo or wrong directory):**
|
|
122
|
+
- `/close` switches to **NON-GIT MODE**
|
|
123
|
+
- Output states: "NOT A GIT REPO / WRONG DIRECTORY"
|
|
124
|
+
- **No claims about file modifications, diffs, or line numbers**
|
|
125
|
+
- Provides a corrective hint (cd to repo root, or initialize git)
|
|
126
|
+
|
|
127
|
+
**If git is available:**
|
|
128
|
+
- Proceeds with **VERIFICATION** block:
|
|
129
|
+
- `git status` output
|
|
130
|
+
- `git diff --name-only` output
|
|
131
|
+
- Explicit list of modified files (or "NONE")
|
|
132
|
+
- Only lists changes with evidence (git diff, file paths, quoted snippets)
|
|
133
|
+
- If evidence is unavailable, states "NOT AVAILABLE" rather than guessing
|
|
134
|
+
|
|
135
|
+
### What It Does
|
|
136
|
+
|
|
137
|
+
- **With changes:** Lists verified changes with evidence (file paths, diffs, quotes)
|
|
138
|
+
- **Without changes:** States explicitly that the session was read-only
|
|
139
|
+
- **Always:** Provides next steps and project memory updates (docs/status.md, docs/todo.md, docs/decisions.md)
|
|
140
|
+
|
|
141
|
+
**Important:** `/close` reflects only what actually happened in the repo. It does not generate progress or invent improvements.
|
|
142
|
+
|
|
143
|
+
### Upgrading Existing Repos
|
|
144
|
+
|
|
145
|
+
To update the `/close` template (and other core commands) in an existing repo:
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
npx -y 4runr-cursor-setup@latest add core --force
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
This updates the templates to the latest version while preserving your project structure.
|
|
152
|
+
|
|
103
153
|
## Common Scenarios
|
|
104
154
|
|
|
105
155
|
### "0 files written" When Adding a Group
|
|
@@ -4,28 +4,159 @@
|
|
|
4
4
|
|
|
5
5
|
We are ending this session. Produce a clean handoff.
|
|
6
6
|
|
|
7
|
-
##
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
7
|
+
## 🔒 CRITICAL: Evidence-Gated Close (Non-Negotiable)
|
|
8
|
+
|
|
9
|
+
**You MUST prove every claimed change with repo evidence. If you cannot prove it, you must not claim it occurred.**
|
|
10
|
+
|
|
11
|
+
### Anti-Hallucination Rules
|
|
12
|
+
|
|
13
|
+
- **Do NOT infer or summarize changes unless you can point to the exact file and evidence.**
|
|
14
|
+
- **Do NOT describe "improvements", "fixes", or "updates" without proof.**
|
|
15
|
+
- **Do NOT list files unless they actually exist or were modified.**
|
|
16
|
+
- **Do NOT claim line numbers, diffs, or file changes without evidence.**
|
|
17
|
+
- **If unsure, state uncertainty explicitly.**
|
|
18
|
+
|
|
19
|
+
## Mandatory Repo Context Proof (FIRST STEP)
|
|
20
|
+
|
|
21
|
+
**You MUST run these commands FIRST and report the results:**
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
REPO CONTEXT PROOF
|
|
25
|
+
- pwd: [run `pwd` and report the current directory]
|
|
26
|
+
- git rev-parse --show-toplevel: [run `git rev-parse --show-toplevel` and report the repo root or ERROR]
|
|
27
|
+
- git status --porcelain: [run `git status --porcelain` and report output or ERROR]
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
**If `git rev-parse --show-toplevel` fails (returns error or non-zero exit code):**
|
|
31
|
+
- **STOP. Switch to NON-GIT MODE immediately.**
|
|
32
|
+
- Do NOT attempt to run any other git commands.
|
|
33
|
+
- Do NOT produce a "What changed" section.
|
|
34
|
+
- Do NOT claim any file modifications, diffs, or line numbers.
|
|
35
|
+
|
|
36
|
+
## Mode C: NON-GIT MODE (Git Unavailable)
|
|
37
|
+
|
|
38
|
+
**Use this if `git rev-parse --show-toplevel` fails:**
|
|
39
|
+
|
|
40
|
+
1. **REPO CONTEXT PROOF** (mandatory, at top)
|
|
41
|
+
- pwd: [actual current directory]
|
|
42
|
+
- git rev-parse --show-toplevel: **ERROR - NOT A GIT REPO / WRONG DIRECTORY**
|
|
43
|
+
- git status --porcelain: **NOT RUN (git unavailable)**
|
|
44
|
+
|
|
45
|
+
2. **Session summary**
|
|
46
|
+
- **MUST state explicitly:**
|
|
47
|
+
```
|
|
48
|
+
NOT A GIT REPO / WRONG DIRECTORY
|
|
49
|
+
|
|
50
|
+
Cannot verify changes. No claims about file modifications, diffs, or line numbers.
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
3. **Corrective step**
|
|
54
|
+
- **Provide ONE corrective hint:**
|
|
55
|
+
- "cd to repo root / open correct folder"
|
|
56
|
+
- OR: "initialize git (git init) if intended"
|
|
57
|
+
|
|
58
|
+
4. **Next steps** (if any, minimal)
|
|
59
|
+
- 1–3 steps, atomic
|
|
60
|
+
|
|
61
|
+
**Output must be short and boring. No invented "evidence". No "What changed" section. No file lists without proof.**
|
|
62
|
+
|
|
63
|
+
## Mandatory Verification Block (Git Mode Only)
|
|
64
|
+
|
|
65
|
+
**Use this ONLY if `git rev-parse --show-toplevel` succeeds:**
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
VERIFICATION
|
|
69
|
+
- git status: [run `git status` and report: clean / modified files / not run]
|
|
70
|
+
- git diff --name-only: [run `git diff --name-only` and list files or "none"]
|
|
71
|
+
- Files modified: [explicit list of file paths or "NONE"]
|
|
72
|
+
```
|
|
11
73
|
|
|
12
|
-
|
|
13
|
-
### 1) What changed
|
|
14
|
-
- Bullet list
|
|
74
|
+
**If you cannot populate this truthfully, you must say "NOT AVAILABLE" for that field.**
|
|
15
75
|
|
|
16
|
-
|
|
17
|
-
- Exact file paths
|
|
76
|
+
## Output Format (Git Mode Only)
|
|
18
77
|
|
|
19
|
-
###
|
|
20
|
-
- Decision
|
|
21
|
-
- Why
|
|
22
|
-
- Trade-offs
|
|
78
|
+
### Mode A: Evidence Mode (Changes Exist)
|
|
23
79
|
|
|
24
|
-
|
|
25
|
-
- 3–7 steps, atomic
|
|
80
|
+
**Use this ONLY if you have evidence of changes:**
|
|
26
81
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
-
|
|
30
|
-
-
|
|
31
|
-
|
|
82
|
+
1. **REPO CONTEXT PROOF** (mandatory, at top)
|
|
83
|
+
- pwd: [actual current directory]
|
|
84
|
+
- git rev-parse --show-toplevel: [actual repo root]
|
|
85
|
+
- git status --porcelain: [actual output]
|
|
86
|
+
|
|
87
|
+
2. **VERIFICATION** (mandatory)
|
|
88
|
+
- git status: [actual output or "not run"]
|
|
89
|
+
- git diff --name-only: [list or "none"]
|
|
90
|
+
- Files modified: [explicit list or "NONE"]
|
|
91
|
+
|
|
92
|
+
3. **What changed** (evidence-required, strict gating)
|
|
93
|
+
- **For each claimed change, you MUST include ONE of:**
|
|
94
|
+
- `git diff --name-only` showing the file
|
|
95
|
+
- A `git diff` snippet (exact quoted output)
|
|
96
|
+
- A direct file excerpt with explicit file path + exact quoted lines
|
|
97
|
+
- **If you cannot provide evidence, write "Not verified" and omit from "What changed".**
|
|
98
|
+
- **No evidence → do not claim changes.**
|
|
99
|
+
|
|
100
|
+
4. **Files involved**
|
|
101
|
+
- Exact file paths (only files that exist or were modified, with evidence)
|
|
102
|
+
|
|
103
|
+
5. **Decisions** (if any)
|
|
104
|
+
- Decision
|
|
105
|
+
- Why
|
|
106
|
+
- Trade-offs
|
|
107
|
+
|
|
108
|
+
6. **Next steps**
|
|
109
|
+
- 3–7 steps, atomic
|
|
110
|
+
|
|
111
|
+
7. **Project memory updates**
|
|
112
|
+
- Provide copy-paste text for:
|
|
113
|
+
- docs/status.md
|
|
114
|
+
- docs/todo.md
|
|
115
|
+
- docs/decisions.md (only if needed)
|
|
116
|
+
|
|
117
|
+
### Mode B: Read-Only Mode (No Changes)
|
|
118
|
+
|
|
119
|
+
**Use this if no evidence of changes exists:**
|
|
120
|
+
|
|
121
|
+
1. **REPO CONTEXT PROOF** (mandatory, at top)
|
|
122
|
+
- pwd: [actual current directory]
|
|
123
|
+
- git rev-parse --show-toplevel: [actual repo root]
|
|
124
|
+
- git status --porcelain: [actual output]
|
|
125
|
+
|
|
126
|
+
2. **VERIFICATION** (mandatory)
|
|
127
|
+
- git status: [actual output]
|
|
128
|
+
- git diff --name-only: [actual output]
|
|
129
|
+
- Files modified: NONE
|
|
130
|
+
|
|
131
|
+
3. **Session summary**
|
|
132
|
+
- **MUST state explicitly:**
|
|
133
|
+
```
|
|
134
|
+
No files were created, modified, or deleted.
|
|
135
|
+
This session was read-only inspection only.
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
4. **What was inspected** (optional, only if relevant)
|
|
139
|
+
- Files read
|
|
140
|
+
- Commands run
|
|
141
|
+
- Information gathered
|
|
142
|
+
|
|
143
|
+
5. **Next steps** (if any)
|
|
144
|
+
- 3–7 steps, atomic
|
|
145
|
+
|
|
146
|
+
6. **Project memory updates** (if any changes to understanding)
|
|
147
|
+
- Provide copy-paste text for:
|
|
148
|
+
- docs/status.md
|
|
149
|
+
- docs/todo.md
|
|
150
|
+
- docs/decisions.md (only if needed)
|
|
151
|
+
|
|
152
|
+
## Hard Rules
|
|
153
|
+
|
|
154
|
+
- No emojis
|
|
155
|
+
- No assumptions
|
|
156
|
+
- No "this should work"
|
|
157
|
+
- No vague summaries without evidence
|
|
158
|
+
- No claiming changes without proof
|
|
159
|
+
- No line numbers, diffs, or file changes without evidence
|
|
160
|
+
- Clean repo → clean close (read-only mode)
|
|
161
|
+
- If git is unavailable, ignore change-reporting sections entirely
|
|
162
|
+
- /close is read-only: suggest commands, do not run changes
|
package/package.json
CHANGED
|
@@ -4,28 +4,159 @@
|
|
|
4
4
|
|
|
5
5
|
We are ending this session. Produce a clean handoff.
|
|
6
6
|
|
|
7
|
-
##
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
7
|
+
## 🔒 CRITICAL: Evidence-Gated Close (Non-Negotiable)
|
|
8
|
+
|
|
9
|
+
**You MUST prove every claimed change with repo evidence. If you cannot prove it, you must not claim it occurred.**
|
|
10
|
+
|
|
11
|
+
### Anti-Hallucination Rules
|
|
12
|
+
|
|
13
|
+
- **Do NOT infer or summarize changes unless you can point to the exact file and evidence.**
|
|
14
|
+
- **Do NOT describe "improvements", "fixes", or "updates" without proof.**
|
|
15
|
+
- **Do NOT list files unless they actually exist or were modified.**
|
|
16
|
+
- **Do NOT claim line numbers, diffs, or file changes without evidence.**
|
|
17
|
+
- **If unsure, state uncertainty explicitly.**
|
|
18
|
+
|
|
19
|
+
## Mandatory Repo Context Proof (FIRST STEP)
|
|
20
|
+
|
|
21
|
+
**You MUST run these commands FIRST and report the results:**
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
REPO CONTEXT PROOF
|
|
25
|
+
- pwd: [run `pwd` and report the current directory]
|
|
26
|
+
- git rev-parse --show-toplevel: [run `git rev-parse --show-toplevel` and report the repo root or ERROR]
|
|
27
|
+
- git status --porcelain: [run `git status --porcelain` and report output or ERROR]
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
**If `git rev-parse --show-toplevel` fails (returns error or non-zero exit code):**
|
|
31
|
+
- **STOP. Switch to NON-GIT MODE immediately.**
|
|
32
|
+
- Do NOT attempt to run any other git commands.
|
|
33
|
+
- Do NOT produce a "What changed" section.
|
|
34
|
+
- Do NOT claim any file modifications, diffs, or line numbers.
|
|
35
|
+
|
|
36
|
+
## Mode C: NON-GIT MODE (Git Unavailable)
|
|
37
|
+
|
|
38
|
+
**Use this if `git rev-parse --show-toplevel` fails:**
|
|
39
|
+
|
|
40
|
+
1. **REPO CONTEXT PROOF** (mandatory, at top)
|
|
41
|
+
- pwd: [actual current directory]
|
|
42
|
+
- git rev-parse --show-toplevel: **ERROR - NOT A GIT REPO / WRONG DIRECTORY**
|
|
43
|
+
- git status --porcelain: **NOT RUN (git unavailable)**
|
|
44
|
+
|
|
45
|
+
2. **Session summary**
|
|
46
|
+
- **MUST state explicitly:**
|
|
47
|
+
```
|
|
48
|
+
NOT A GIT REPO / WRONG DIRECTORY
|
|
49
|
+
|
|
50
|
+
Cannot verify changes. No claims about file modifications, diffs, or line numbers.
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
3. **Corrective step**
|
|
54
|
+
- **Provide ONE corrective hint:**
|
|
55
|
+
- "cd to repo root / open correct folder"
|
|
56
|
+
- OR: "initialize git (git init) if intended"
|
|
57
|
+
|
|
58
|
+
4. **Next steps** (if any, minimal)
|
|
59
|
+
- 1–3 steps, atomic
|
|
60
|
+
|
|
61
|
+
**Output must be short and boring. No invented "evidence". No "What changed" section. No file lists without proof.**
|
|
62
|
+
|
|
63
|
+
## Mandatory Verification Block (Git Mode Only)
|
|
64
|
+
|
|
65
|
+
**Use this ONLY if `git rev-parse --show-toplevel` succeeds:**
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
VERIFICATION
|
|
69
|
+
- git status: [run `git status` and report: clean / modified files / not run]
|
|
70
|
+
- git diff --name-only: [run `git diff --name-only` and list files or "none"]
|
|
71
|
+
- Files modified: [explicit list of file paths or "NONE"]
|
|
72
|
+
```
|
|
11
73
|
|
|
12
|
-
|
|
13
|
-
### 1) What changed
|
|
14
|
-
- Bullet list
|
|
74
|
+
**If you cannot populate this truthfully, you must say "NOT AVAILABLE" for that field.**
|
|
15
75
|
|
|
16
|
-
|
|
17
|
-
- Exact file paths
|
|
76
|
+
## Output Format (Git Mode Only)
|
|
18
77
|
|
|
19
|
-
###
|
|
20
|
-
- Decision
|
|
21
|
-
- Why
|
|
22
|
-
- Trade-offs
|
|
78
|
+
### Mode A: Evidence Mode (Changes Exist)
|
|
23
79
|
|
|
24
|
-
|
|
25
|
-
- 3–7 steps, atomic
|
|
80
|
+
**Use this ONLY if you have evidence of changes:**
|
|
26
81
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
-
|
|
30
|
-
-
|
|
31
|
-
|
|
82
|
+
1. **REPO CONTEXT PROOF** (mandatory, at top)
|
|
83
|
+
- pwd: [actual current directory]
|
|
84
|
+
- git rev-parse --show-toplevel: [actual repo root]
|
|
85
|
+
- git status --porcelain: [actual output]
|
|
86
|
+
|
|
87
|
+
2. **VERIFICATION** (mandatory)
|
|
88
|
+
- git status: [actual output or "not run"]
|
|
89
|
+
- git diff --name-only: [list or "none"]
|
|
90
|
+
- Files modified: [explicit list or "NONE"]
|
|
91
|
+
|
|
92
|
+
3. **What changed** (evidence-required, strict gating)
|
|
93
|
+
- **For each claimed change, you MUST include ONE of:**
|
|
94
|
+
- `git diff --name-only` showing the file
|
|
95
|
+
- A `git diff` snippet (exact quoted output)
|
|
96
|
+
- A direct file excerpt with explicit file path + exact quoted lines
|
|
97
|
+
- **If you cannot provide evidence, write "Not verified" and omit from "What changed".**
|
|
98
|
+
- **No evidence → do not claim changes.**
|
|
99
|
+
|
|
100
|
+
4. **Files involved**
|
|
101
|
+
- Exact file paths (only files that exist or were modified, with evidence)
|
|
102
|
+
|
|
103
|
+
5. **Decisions** (if any)
|
|
104
|
+
- Decision
|
|
105
|
+
- Why
|
|
106
|
+
- Trade-offs
|
|
107
|
+
|
|
108
|
+
6. **Next steps**
|
|
109
|
+
- 3–7 steps, atomic
|
|
110
|
+
|
|
111
|
+
7. **Project memory updates**
|
|
112
|
+
- Provide copy-paste text for:
|
|
113
|
+
- docs/status.md
|
|
114
|
+
- docs/todo.md
|
|
115
|
+
- docs/decisions.md (only if needed)
|
|
116
|
+
|
|
117
|
+
### Mode B: Read-Only Mode (No Changes)
|
|
118
|
+
|
|
119
|
+
**Use this if no evidence of changes exists:**
|
|
120
|
+
|
|
121
|
+
1. **REPO CONTEXT PROOF** (mandatory, at top)
|
|
122
|
+
- pwd: [actual current directory]
|
|
123
|
+
- git rev-parse --show-toplevel: [actual repo root]
|
|
124
|
+
- git status --porcelain: [actual output]
|
|
125
|
+
|
|
126
|
+
2. **VERIFICATION** (mandatory)
|
|
127
|
+
- git status: [actual output]
|
|
128
|
+
- git diff --name-only: [actual output]
|
|
129
|
+
- Files modified: NONE
|
|
130
|
+
|
|
131
|
+
3. **Session summary**
|
|
132
|
+
- **MUST state explicitly:**
|
|
133
|
+
```
|
|
134
|
+
No files were created, modified, or deleted.
|
|
135
|
+
This session was read-only inspection only.
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
4. **What was inspected** (optional, only if relevant)
|
|
139
|
+
- Files read
|
|
140
|
+
- Commands run
|
|
141
|
+
- Information gathered
|
|
142
|
+
|
|
143
|
+
5. **Next steps** (if any)
|
|
144
|
+
- 3–7 steps, atomic
|
|
145
|
+
|
|
146
|
+
6. **Project memory updates** (if any changes to understanding)
|
|
147
|
+
- Provide copy-paste text for:
|
|
148
|
+
- docs/status.md
|
|
149
|
+
- docs/todo.md
|
|
150
|
+
- docs/decisions.md (only if needed)
|
|
151
|
+
|
|
152
|
+
## Hard Rules
|
|
153
|
+
|
|
154
|
+
- No emojis
|
|
155
|
+
- No assumptions
|
|
156
|
+
- No "this should work"
|
|
157
|
+
- No vague summaries without evidence
|
|
158
|
+
- No claiming changes without proof
|
|
159
|
+
- No line numbers, diffs, or file changes without evidence
|
|
160
|
+
- Clean repo → clean close (read-only mode)
|
|
161
|
+
- If git is unavailable, ignore change-reporting sections entirely
|
|
162
|
+
- /close is read-only: suggest commands, do not run changes
|