Organize work artifacts into threads

Author: yanfengliu

AGENTS.md

@@ -36,7 +36,7 @@
 - `ARCHITECTURE.md`: current file structure and architectural boundaries.
 - `GAME_RULES.md`: implementation-aligned game mechanics and controls.
 - `PROGRESS.md`: single running project log.
-- `docs/reviews/`: multi-CLI review artifacts for substantive changes and full-codebase audits.
+- `docs/threads/`: active and completed work threads, including multi-CLI review artifacts and full-codebase audits.
 
 ## Validation Gates
 
@@ -66,14 +66,18 @@
 - Review is required for changes to files such as `AGENTS.md`, `CLAUDE.md`, `ARCHITECTURE.md`, `GAME_RULES.md`, `.github/workflows/*`, `.pre-commit-config.yaml`, `pyproject.toml`, `environment.yml`, and any new review-process docs.
 - Review is also required for game-mechanic changes in `src/`, public API changes in `src/env.py` or `src/mediator.py`, balance/config changes in `src/config.py`, and new architectural boundaries.
 - Trivial typo fixes, status summaries, dependency inspection, simple setup commands, and README wording polish can skip review if they do not change behavior or process.
-- Store review artifacts under `docs/reviews/<scope>/<YYYY-MM-DD>/<iteration>/`:
+- Store active thread artifacts under `docs/threads/current/<theme>/<YYYY-MM-DD>/<iteration>/`:
   - `raw/codex.md`
   - `raw/opus.md`
   - optional extra independent reviewers as `raw/codex-2.md`, `raw/opus-2.md`, etc.
   - optional `raw/*.stdout.log` and `raw/*.stderr.log`
   - `diff.md`
   - `REVIEW.md`
-- Use path-limited diffs from `main`, for example `git diff -- AGENTS.md ARCHITECTURE.md docs/reviews/README.md`.
+- Use short kebab-case theme names. Full-codebase review threads always use `full`.
+- When a thread is complete, move or merge it into `docs/threads/done/<theme>/`. If that theme already exists under `done/`, move only the new date or iteration directories into the existing theme; never replace the whole theme directory.
+- Before choosing a new iteration number for a recurring theme, inspect both `docs/threads/current/<theme>/<YYYY-MM-DD>/` and `docs/threads/done/<theme>/<YYYY-MM-DD>/`.
+- Preserve `raw/` reviewer outputs verbatim. Record path migrations or follow-up context in `REVIEW.md` rather than rewriting raw reviewer text.
+- Use path-limited diffs from `main`, for example `git diff -- AGENTS.md ARCHITECTURE.md docs/threads/README.md`.
 - Reviewer prompt baseline:
 
 ```text
@@ -85,23 +89,23 @@ You are a senior code reviewer. Flag bugs, process regressions, stale documentat
 
 ## Full-Codebase Review
 
-- Full-codebase review iterations live under `docs/reviews/full/<YYYY-MM-DD>/<iteration>/`.
-- Before starting a new iteration, inspect existing numeric iteration folders for the same date and use the next number. If earlier iterations exist, give reviewers the previous `REVIEW.md` summaries and ask them to verify that earlier findings were resolved.
+- Full-codebase review iterations start under `docs/threads/current/full/<YYYY-MM-DD>/<iteration>/` and move or merge into `docs/threads/done/full/<YYYY-MM-DD>/<iteration>/` when complete.
+- Before starting a new iteration, inspect existing numeric iteration folders for the same date under both `current/full/` and `done/full/`, then use the next number. If earlier iterations exist, give reviewers the previous `REVIEW.md` summaries and ask them to verify that earlier findings were resolved.
 - Run three independent reviewers. Use both Codex and Claude when available; if one service is unavailable or out of quota, run additional independent instances of the available service until there are three raw reports.
 - Codex full-codebase reviewer command. Keep the prompt in a file and pipe it through stdin; this avoids PowerShell splitting multi-line prompts into unexpected positional arguments. Use `--ignore-user-config` so local plugin sync or user config does not interfere with a read-only review run:
 
 ```powershell
-Get-Content -Raw docs/reviews/full/<YYYY-MM-DD>/<iteration>/prompt-codex-1.md | codex -m gpt-5.5 -c model_reasoning_effort='xhigh' -a never -s read-only exec --ignore-user-config --cd . --ephemeral -o docs/reviews/full/<YYYY-MM-DD>/<iteration>/raw/codex-1.md -
+Get-Content -Raw docs/threads/current/full/<YYYY-MM-DD>/<iteration>/prompt-codex-1.md | codex -m gpt-5.5 -c model_reasoning_effort='xhigh' -a never -s read-only exec --ignore-user-config --cd . --ephemeral -o docs/threads/current/full/<YYYY-MM-DD>/<iteration>/raw/codex-1.md -
 ```
 
 - Claude full-codebase reviewer command. Keep the prompt in a variable so PowerShell passes it as one argument:
 
 ```powershell
-$prompt = Get-Content -Raw docs/reviews/full/<YYYY-MM-DD>/<iteration>/prompt-claude.md
+$prompt = Get-Content -Raw docs/threads/current/full/<YYYY-MM-DD>/<iteration>/prompt-claude.md
 claude -p $prompt --model best --effort max --permission-mode bypassPermissions --no-session-persistence --tools "Read,Glob,Grep,Bash" --allowedTools "Read,Glob,Grep,Bash(git *),Bash(python -m unittest *),Bash(C:\Users\38909\miniconda3\envs\py313\python.exe -m unittest *)" --output-format text
 ```
 
-- Save raw reviewer output under `raw/`, then synthesize `REVIEW.md` with severity, evidence, disposition, and a fix plan. Only fix findings after checking them against the codebase. Re-review fixes in the next iteration if code changes are made.
+- Save raw reviewer output under `raw/`, then synthesize `REVIEW.md` with severity, evidence, disposition, and a fix plan. Only fix findings after checking them against the codebase. Re-review fixes in the next iteration if code changes are made. When the full review is complete, move or merge the thread into `docs/threads/done/full/`.
 
 ## Visual Changes
 

ARCHITECTURE.md

@@ -5,10 +5,14 @@ python_mini_metro/
 |- .vscode/
 |  \- settings.json
 |- docs/
-|  \- reviews/
+|  \- threads/
 |     |- README.md
-|     |- agents-repo-fit/
-|     \- full/
+|     |- current/
+|     |  \- README.md
+|     \- done/
+|        |- README.md
+|        |- agents-repo-fit/
+|        \- full/
 |- src/
 |  |- agent_play.py
 |  |- config.py

PROGRESS.md

@@ -81,5 +81,6 @@
 ## 2026-04-28
 
 - Added Python/py313 workflow guidance in `AGENTS.md` with a `CLAUDE.md` shim, reflected the removed `.cursor/rules`, and added an initial review artifact directory.
-- Moved review artifacts under `docs/reviews/` and documented robust full-codebase Codex/Claude review commands.
+- Moved review artifacts under the docs thread area and documented robust full-codebase Codex/Claude review commands.
 - Ran the first full-codebase review, fixed terminal-state API mutation, malformed action handling, loop routing closure, stale travel-plan cleanup, the graph node hash contract, and the stale Ruff pre-commit hook, then added focused regressions.
+- Renamed review artifacts into the broader `docs/threads/` lifecycle, with active work in `current/`, completed work in `done/`, and completed `full` and `agents-repo-fit` themes migrated under `done/`.

docs/reviews/README.md

@@ -0,0 +1,29 @@
+# Threads
+
+This directory stores work threads. A thread is the durable record for one coherent piece of work, named by theme.
+
+Threads start under `current/` while work is active and move to `done/` when the work is complete. If a completed theme already exists under `done/`, merge the new date or iteration directories into that theme instead of replacing the whole theme directory.
+
+Use short kebab-case theme names, such as `agents-repo-fit`, `thread-structure`, or `metro-dwell-fix`. Full-codebase review work always uses the theme name `full`.
+
+Preserve `raw/` reviewer outputs verbatim. If a folder migration changes where a thread lives, document that migration in `REVIEW.md` or another non-raw note instead of rewriting the original reviewer text.
+
+Use this layout for thread artifacts:
+
+```text
+docs/threads/current/<theme>/<YYYY-MM-DD>/<iteration>/
+|- raw/
+|  |- codex-1.md
+|  |- opus.md
+|  \- codex-2.md
+|- diff.md
+\- REVIEW.md
+```
+
+When the thread is complete, move or merge that date/iteration tree to:
+
+```text
+docs/threads/done/<theme>/<YYYY-MM-DD>/<iteration>/
+```
+
+Start iteration numbering at `1` and increment it only when a re-review or revised artifact set is needed after addressing findings. For recurring themes, inspect both `current/<theme>/` and `done/<theme>/` before choosing the next date or iteration number.

docs/threads/README.md

@@ -0,0 +1,5 @@
+# Current Threads
+
+Active work threads live here while they are in progress.
+
+Use `docs/threads/current/<theme>/<YYYY-MM-DD>/<iteration>/` for review artifacts, notes, diffs, and raw reviewer output that belong to the active thread. When the work is complete, move or merge the thread into `docs/threads/done/<theme>/`.

docs/threads/current/README.md

@@ -0,0 +1,5 @@
+# Done Threads
+
+Completed work threads live here.
+
+If a theme already exists, add the new date or iteration directories under the existing theme. Do not replace an existing theme directory just because a new thread shares the same name.

docs/threads/done/README.md

@@ -3,15 +3,15 @@
 ## Scope
 
 - Rewrote `AGENTS.md` from a copied workflow template into a Python/py313 workflow for this repo.
-- Added `docs/reviews/README.md` so the review artifact directory referenced by `AGENTS.md` exists in the repo.
-- Updated `ARCHITECTURE.md` after the user removed `.cursor/rules` and this change added `docs/reviews/`.
+- Added `docs/threads/README.md` so the review artifact directory referenced by `AGENTS.md` exists in the repo.
+- Updated `ARCHITECTURE.md` after the user removed `.cursor/rules` and this change added `docs/threads/done/`.
 - Updated `PROGRESS.md` with a short entry for the process-documentation change.
 
 ## Validation
 
 - `C:\Users\38909\miniconda3\envs\py313\python.exe -m unittest -v`: passed, 167 tests.
-- `C:\Users\38909\miniconda3\envs\py313\python.exe -m pre_commit run --files AGENTS.md ARCHITECTURE.md CLAUDE.md PROGRESS.md docs/reviews/README.md docs/reviews/agents-repo-fit/2026-04-28/1/diff.md docs/reviews/agents-repo-fit/2026-04-28/1/REVIEW.md docs/reviews/agents-repo-fit/2026-04-28/1/raw/codex.md docs/reviews/agents-repo-fit/2026-04-28/1/raw/opus.md`: passed after adding a final newline to `CLAUDE.md`.
-- `git diff --check -- AGENTS.md ARCHITECTURE.md PROGRESS.md docs/reviews/README.md docs/reviews/agents-repo-fit/2026-04-28/1`: passed, with expected CRLF warnings only.
+- `C:\Users\38909\miniconda3\envs\py313\python.exe -m pre_commit run --files AGENTS.md ARCHITECTURE.md CLAUDE.md PROGRESS.md docs/threads/README.md docs/threads/done/agents-repo-fit/2026-04-28/1/diff.md docs/threads/done/agents-repo-fit/2026-04-28/1/REVIEW.md docs/threads/done/agents-repo-fit/2026-04-28/1/raw/codex.md docs/threads/done/agents-repo-fit/2026-04-28/1/raw/opus.md`: passed after adding a final newline to `CLAUDE.md`.
+- `git diff --check -- AGENTS.md ARCHITECTURE.md PROGRESS.md docs/threads/README.md docs/threads/done/agents-repo-fit/2026-04-28/1`: passed, with expected CRLF warnings only.
 
 ## Codex Findings
 
@@ -21,7 +21,7 @@
 ## Claude Findings
 
 - P2: `PROGRESS.md` and the review artifact path use `2026-04-28`, while the reviewer inferred April 27, 2026 from local session context. Disposition: not accepted for the same reason as the Codex date finding.
-- P2: The `PROGRESS.md` bullet under-described the actual process change. Disposition: accepted. The bullet now names `AGENTS.md`, `CLAUDE.md`, the removed `.cursor/rules`, and `docs/reviews/`.
+- P2: The `PROGRESS.md` bullet under-described the actual process change. Disposition: accepted. The bullet now names `AGENTS.md`, `CLAUDE.md`, the removed `.cursor/rules`, and `docs/threads/done/`.
 - P3: The review packet should include the `.cursor/rules` deletion and `CLAUDE.md` addition. Disposition: accepted. `diff.md` was regenerated with those paths included.
 
 ## Result

…s/agents-repo-fit/2026-04-28/1/REVIEW.md …e/agents-repo-fit/2026-04-28/1/REVIEW.mddocs/reviews/agents-repo-fit/2026-04-28/1/REVIEW.md renamed to docs/threads/done/agents-repo-fit/2026-04-28/1/REVIEW.md docs/reviews/agents-repo-fit/2026-04-28/1/REVIEW.md renamed to docs/threads/done/agents-repo-fit/2026-04-28/1/REVIEW.md

@@ -104,7 +104,7 @@ index 0000000..bf60f17
 +- `ARCHITECTURE.md`: current file structure and architectural boundaries.
 +- `GAME_RULES.md`: implementation-aligned game mechanics and controls.
 +- `PROGRESS.md`: single running project log.
-+- `reviews/`: multi-CLI review artifacts for substantive changes.
++- `docs/threads/done/`: multi-CLI review artifacts for substantive changes.
 +
 +## Validation Gates
 +
@@ -134,13 +134,13 @@ index 0000000..bf60f17
 +- Review is required for changes to files such as `AGENTS.md`, `CLAUDE.md`, `ARCHITECTURE.md`, `GAME_RULES.md`, `.github/workflows/*`, `.pre-commit-config.yaml`, `pyproject.toml`, `environment.yml`, and any new review-process docs.
 +- Review is also required for game-mechanic changes in `src/`, public API changes in `src/env.py` or `src/mediator.py`, balance/config changes in `src/config.py`, and new architectural boundaries.
 +- Trivial typo fixes, status summaries, dependency inspection, simple setup commands, and README wording polish can skip review if they do not change behavior or process.
-+- Store review artifacts under `reviews/<scope>/<YYYY-MM-DD>/<iteration>/`:
++- Store review artifacts under `docs/threads/current/<theme>/<YYYY-MM-DD>/<iteration>/`:
 +  - `raw/codex.md`
 +  - `raw/opus.md`
 +  - optional `raw/*.stdout.log` and `raw/*.stderr.log`
 +  - `diff.md`
 +  - `REVIEW.md`
-+- Use path-limited diffs from `main`, for example `git diff -- AGENTS.md ARCHITECTURE.md reviews/README.md`.
++- Use path-limited diffs from `main`, for example `git diff -- AGENTS.md ARCHITECTURE.md docs/threads/README.md`.
 +- Reviewer prompt baseline:
 +
 +```text
@@ -186,7 +186,7 @@ index e678939..a6b66ef 100644
  |     \- test.yml
 +|- .vscode/
 +|  \- settings.json
-+|- reviews/
++|- docs/threads/done/
 +|  \- README.md
  |- src/
  |  |- agent_play.py
@@ -219,12 +219,12 @@ index d858993..b3879b3 100644
 +
 +## 2026-04-28
 +
-+- Added Python/py313 workflow guidance in `AGENTS.md` with a `CLAUDE.md` shim, reflected the removed `.cursor/rules`, and added a `reviews/` artifact directory.
-diff --git a/reviews/README.md b/reviews/README.md
++- Added Python/py313 workflow guidance in `AGENTS.md` with a `CLAUDE.md` shim, reflected the removed `.cursor/rules`, and added a `docs/threads/done/` artifact directory.
+diff --git a/docs/threads/README.md b/docs/threads/README.md
 new file mode 100644
 index 0000000..d5d2eef
 --- /dev/null
-+++ b/reviews/README.md
++++ b/docs/threads/README.md
 @@ -0,0 +1,16 @@
 +# Reviews
 +
@@ -233,7 +233,7 @@ index 0000000..d5d2eef
 +Use this layout:
 +
 +```text
-+reviews/<scope>/<YYYY-MM-DD>/<iteration>/
++docs/threads/current/<theme>/<YYYY-MM-DD>/<iteration>/
 +|- raw/
 +|  |- codex.md
 +|  \- opus.md