Clarify nested TODO completion rules

Describe level-2 milestones/themes, level-3 workstreams and the rule that
completed workstreams stay under their parent until the whole milestone is
done. Add a milestone-shaped recommended format and align the changelog/tag
steps with nested sections.

AGENTS.md

@@ -44,8 +44,13 @@ Do not assume that a task is unimplemented without checking the code and documen
 All planned implementation work must be represented in `TODO.md`.
 
 - Use headings to group related work into sections.
-- Use checkbox items for each concrete task.
+- Use level-2 headings (`##`) for milestones or stable themes. A milestone should state its goal
-- Group larger tasks in sub-sections of smaller tasks to keep the checklist organized.
+  and an explicit exit criterion; a theme groups small related work that does not need a
+  milestone.
+- Use level-3 headings (`###`) for workstreams inside a milestone (for example, `0.8.1
+  First-shift tutorial`). Keep the hierarchy to three levels: milestone → workstream → checkbox.
+- Use checkbox items for each concrete task, normally under a level-3 workstream. Direct
+  checkboxes under a level-2 section are acceptable for small, single-workstream sections.
 - Keep tasks small enough to complete and review independently.
 - Add new tasks when discoveries expand the scope.
 - When starting a task, claim it for the agent workflow by changing `[ ]` to `[-]`. Keep it `[-]`
@@ -62,25 +67,20 @@ Recommended format:
 ```md
 # TODO
 
-## Setup
+## Milestone 0.8.0 — First hour and content depth
 
-### Initial Setup
+### 0.8.1 First-shift tutorial
 
-- [x] Install required dependencies.
+- [x] Write the tutorial beat sheet.
-- [-] Configure environment variables.
+- [-] Implement the tutorial state machine. (claimed; implementation/verification in progress)
-- [ ] Verify initial project setup by running the basic test suite.
+- [ ] Add the tutorial smoke test.
 
-### Environment Setup
+### 0.8.2 Campaign shell
 
-- [x] Set up local development environment.
+- [ ] Define campaign data.
-- [-] Configure project-specific environment variables.
+- [ ] Persist campaign progress.
-- [ ] Verify environment setup by running environment checks or sample scripts.
 
-## Core Gameplay
+**Exit:** a first-time player completes a shift without external documentation.
-
-- [ ] Add player movement controls.
-- [-] Implement NPC approach behavior. (claimed; implementation/verification in progress)
-- [x] Define escalation levels.
 
 ## Documentation
 
@@ -89,16 +89,26 @@ Recommended format:
 
 ### 3. Move Completed Sections to `DONE.md`
 
-When every task in a `TODO.md` section is complete:
+`TODO.md` uses nested sections. Apply these completion rules:
 
-1. Verify the work and update the checkbox items to `[x]`.
+1. **Level-3 workstream:** verify the work, mark every checkbox `[x]`, and add a short completion
-2. Move the entire completed section, including its heading and checklist, to `DONE.md`.
+   note. Leave the completed workstream under its parent milestone; do not move an isolated
-3. Remove that section from `TODO.md`.
+   level-3 section to `DONE.md`.
-4. Add a short completion note or date when useful.
+2. **Level-2 milestone/theme:** it is complete only when its direct checkboxes and **all** of its
+   level-3 workstreams are complete. Verify the whole milestone, record its capabilities in
+   `docs/development-status.md` when it represents shipped functionality, and write the matching
+   `CHANGELOG.md` entry.
+3. Move the **entire level-2 section**, including all level-3 headings and checklists, to
+   `DONE.md`. Remove it from `TODO.md` and add a completion date/note.
+4. **Planning/overview sections** such as a gap analysis, roadmap overview, dependencies or
+   deferred ideas are not completion milestones. Do not move them merely because their checkboxes
+   are empty or complete; update or supersede them as the roadmap changes.
+5. Do not move partially completed milestones. Leave them in `TODO.md` until every nested task is
+   complete, or split the unfinished work into a new smaller level-2 milestone first.
 
-Do not move partially completed sections. Leave them in `TODO.md` until all of their tasks are complete, or split the section into smaller sections first.
+When a completed milestone represents shipped functionality, also record the new capability in
-
+`docs/development-status.md` so the implemented-features list stays accurate, and write a matching
-When a completed section represents shipped functionality, also record the new capability in `docs/development-status.md` so the implemented-features list stays accurate, and write a matching entry in `CHANGELOG.md` (see "Maintain `CHANGELOG.md`" below).
+entry in `CHANGELOG.md` (see "Maintain `CHANGELOG.md`" below).
 
 ### 4. Maintain `MEMORY.md`
 
@@ -169,7 +179,7 @@ The root-level `CHANGELOG.md` records the user-facing changes for every release.
 - Describe changes in user-facing terms, not as raw commit messages.
 - Add the entry when its work ships. If the version number is not yet known, record it under `Unreleased` and move it into a numbered version when the version is tagged.
 
-When a full level-2 section in `TODO.md` is implemented, completed, and moved to `DONE.md`:
+When a full executable level-2 milestone/theme in `TODO.md` is implemented, completed, and moved to `DONE.md`:
 
 1. Verify the work and mark every checkbox in the section `[x]`.
 2. Use the section heading and its completed items to describe the changes and write a `CHANGELOG.md` entry under the next appropriate version.
@@ -187,9 +197,9 @@ For each task:
 4. Run the relevant tests, checks, or manual verification.
 5. Update documentation if the change creates lasting context: add features to `docs/development-status.md`, adjust the README links or other `docs/` files as needed, and record decisions/gotchas in `MEMORY.md`.
 6. Mark the task complete.
-7. Move its section to `DONE.md` when the entire section is complete (after recording its `CHANGELOG.md` entry).
+7. Keep completed level-3 workstreams in place until the parent milestone is complete; then move the entire level-2 milestone to `DONE.md` after recording its `CHANGELOG.md` entry.
 8. Commit the changes to the version control system with a descriptive message.
-9. If a section from `TODO.md` has been fully completed, ensure its `CHANGELOG.md` entry is in place, then create a new version or tag in the version control system to mark the milestone.
+9. If a level-2 milestone from `TODO.md` has been fully completed, ensure its `CHANGELOG.md` entry is in place, then create a new version or tag in the version control system to mark the milestone.
 10. Push the committed changes to the shared repository if applicable.
 11. Note the new version or tag created in the version control system in any relevant documentation or handoff summary.