Merge branch 'master' of https://git.d-popov.com/popov/neuron-tai

docs/agents/issue-tracker.md

@@ -1,19 +1,47 @@
 # Issue tracker: Local Markdown
 
-Issues and PRDs for this project live as markdown files under `docs/`.
+## Lifecycle
 
-## Conventions
+Active feature work lives in `.scratch/<feature-slug>/`. When a feature is complete, `/close-feature` graduates it into `docs/`. This keeps in-progress work isolated from the permanent record.
 
-- The PRD is `docs/PRD.md` (narrative) and `docs/prd.json` (machine-readable story list used by ralph)
+```
-- Implementation issues (user stories) are `docs/issues/<NN>-<slug>.md`, numbered from `01`
+/grilling → /to-prd → /to-issues → .scratch/<slug>/
-- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
+                                         ↓ all Status: done
-- ADRs (architecture decisions) are `docs/adr/<NNNN>-<slug>.md`, numbered from `0001`
+                                    /close-feature
-- Comments and conversation history append to the bottom of the file under a `## Comments` heading
+                                         ↓
+                                      docs/
+```
+
+## During a feature (in .scratch/)
+
+- `.scratch/<slug>/PRD.md` — narrative PRD
+- `.scratch/<slug>/prd.json` — machine-readable story list (used by ralph)
+- `.scratch/<slug>/issues/<NN>-<slug>.md` — user stories, numbered from `01`
+- Triage state is a `Status:` line near the top of each issue (see `triage-labels.md`)
+- Comments and conversation history append under a `## Comments` heading
+
+## After close (in docs/)
+
+- `docs/PRD.md` — narrative PRD (appended under a feature heading)
+- `docs/prd.json` — merged story list
+- `docs/issues/<NN>-<slug>.md` — renumbered from next available slot
+- `docs/adr/<NNNN>-<slug>.md` — any ADRs from the feature, renumbered
+
+## Closing a feature
+
+Run `/close-feature <slug>` when all issues have `Status: done`. The skill will:
+1. Verify all issues are done (stops if any are incomplete)
+2. Show what will move and ask for confirmation
+3. `git mv` everything into `docs/` with correct numbering
+4. Merge prd.json user stories into `docs/prd.json`
+5. Delete `.scratch/<slug>/` and commit
+
+The agent should also **proactively offer** to run `/close-feature` when it notices all issues in a `.scratch/<slug>/` are done.
 
 ## When a skill says "publish to the issue tracker"
 
-Create a new file under `docs/issues/` following the numbering convention.
+Create a new file under `.scratch/<feature-slug>/issues/` following the numbering convention. Create the directory if it doesn't exist.
 
 ## When a skill says "fetch the relevant ticket"
 
-Read the file at the referenced path. The user will normally pass the path or the issue number directly.
+Read the file at the referenced path. The user will normally pass the path or issue number directly. Check both `docs/issues/` (closed features) and `.scratch/*/issues/` (active features).