docs: Run /session-review in rounds before the orchestrator tells the user that a milestone is done

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>

Author: codeguru42

docs/dev/issues.md

@@ -31,4 +31,4 @@ The rules for the links are in [The blocked-by links](planning.md#the-blocked-by
 
 ## Milestones
 
-[The milestone of an issue](planning.md#the-milestone-of-an-issue) of planning.md gives the milestone of each issue. The planning session closes a milestone only when the operator says so. Then it runs `gh api -X PATCH repos/codeguru42/tasker/milestones/<number> -f state=closed`.
+[The milestone of an issue](planning.md#the-milestone-of-an-issue) of planning.md gives the milestone of each issue. The planning session closes a milestone only when the operator says so. Then it runs `gh api -X PATCH repos/codeguru42/tasker/milestones/<number> -f state=closed`. An orchestrator asks the operator to close a milestone only after each finding of its review rounds is handled, as [Pick the tickets](orchestration.md#pick-the-tickets) of orchestration.md says.

docs/dev/orchestration.md

@@ -25,7 +25,7 @@ The orchestrator does all the steps of this section.
 - The move rule: a moving ticket is a ticket that moves or splits a whole shared file, for example the split of `test/helpers.ts` into the folder `test/helpers/` on #140. The orchestrator starts a moving ticket only after each task in flight that changes that file has landed. This rule covers the tasks of every milestone, except a parked task (see [the defer rule](#the-defer-rule)). For the start of a moving ticket, this rule wins over the last sentence of the bullet before it. [The overlap rule](#the-overlap-rule) gives the steps that list the tasks in flight and their files. The reason: a moving ticket changes each line of the file. As a result, a ticket that lands later in that file causes a rebase conflict in each commit, or one more refine before `tasker approve`. [The stacking rule](#the-stacking-rule) gives one exception for a parent.
 - If a task in flight that changes the file of a moving ticket is far from landing, for example in `awaiting_plan_review`, the orchestrator asks the user. The user decides whether the orchestrator waits or starts the moving ticket now. The orchestrator follows [A decision of the user](working-with-the-user.md#a-decision-of-the-user). If the user answers "start now", the orchestrator sets a landing order between the moving ticket and that task in flight, as [Land the work](#land-the-work) says. For a moving ticket of the milestone "Docs" and a task in flight of a numbered milestone, [the Docs rule](#the-docs-rule) sets no landing order. For that moving ticket and that task in flight, the answer of the user wins over the sentence "Start the second ticket after the first one lands." of the shared-file bullet above. For a task in flight of another milestone, [the overlap rule](#the-overlap-rule) applies.
 - When a ticket starts, the orchestrator moves its card to In progress. `tasker start` does not move the card. The board moves the card to Done when `tasker finish` closes the issue.
-- When the Todo column of the milestone is empty, stop and tell the user. Do not write the issues of the next milestone. This bullet does not cover a long-running orchestrator (see [The handoff](#the-handoff)).
+- When the Todo column of the milestone is empty, the orchestrator waits until the last ticket of the milestone closes and no task of the milestone is in flight. Then the orchestrator runs `/session-review` before it stops and tells the user. Do not write the issues of the next milestone. A round is one run of `/session-review`. The orchestrator runs `/session-review` again after each round that found something. The rounds end when a round finds nothing new. A round can find a lesson that an earlier round missed, or a new fact from the answers of the user. A finding is handled when the orchestrator filed it as an issue or added it to an open issue. A finding is also handled when the orchestrator wrote it to memory, for a fact that the rules keep out of the tracked docs. A finding is also handled when the user decided to drop it. A finding that is not handled is open. When the orchestrator tells the user that the milestone is done, it lists each finding with its state, handled or open. The orchestrator asks the user to close the milestone only after each finding is handled. The milestone closes only when the user says so, as [Milestones](issues.md#milestones) of issues.md says. The stop of this bullet does not cover a long-running orchestrator (see [The handoff](#the-handoff)). The review rounds of this bullet, the list of the findings and the ask to close the milestone cover a long-running orchestrator, before it moves to the next milestone.
 
 ### The stacking rule
 
@@ -677,7 +677,7 @@ After the start, the old orchestrator does these steps:
 
 1. Start no new ticket.
 2. Wait until each task in flight lands. For each landing, do the usual steps: delete the jobs (see [Delete the job](#delete-the-job)), do [the re-read rule](#the-re-read-rule) and do [the notice rule](#the-notice-rule). The reason: a job lives only in the session of the orchestrator (see [Terms](#terms)). If a task is still in flight at the handoff, nobody resumes it after a quota stop.
-3. Write the handoff file `$HOME/Documents/tasker/handoff/<date>-<role>.md`, for example `2026-10-15-docs-orchestrator.md`. If a file with that name exists, add a number, for example `2026-10-15-docs-orchestrator-2.md`.
+3. Run the review rounds of the last bullet of [Pick the tickets](#pick-the-tickets), until a round finds nothing new. The user asked for this rule on 2026-10-17. Then write the handoff file `$HOME/Documents/tasker/handoff/<date>-<role>.md`, for example `2026-10-15-docs-orchestrator.md`. If a file with that name exists, add a number, for example `2026-10-15-docs-orchestrator-2.md`.
 4. Give the path of the file in the reply to the user.
 
 Only the user ends a handoff that started. The handoff ends when the user clears the old session and starts the new session with the prompt of the handoff file. Until then, the old orchestrator starts no new ticket, also after step 4. On 2026-10-17, the Docs orchestrator saw that its handoff started too early. It then started a new ticket without the word of the user.
@@ -688,6 +688,7 @@ The old orchestrator puts these items in the handoff file:
 - The state at the handoff: the tasks in flight of other milestones that share a file with an open issue of the milestone, the parked tasks and the other sessions.
 - What the old orchestrator did, and each decision of the user from its session.
 - A table of the open issues of the milestone, with the columns issue, topic, blockers and files.
+- Each finding of the review rounds, with its state, handled or open.
 
 The old orchestrator puts no rule in the handoff file. The rules stay in the docs, and the prompt points to them.