Flow Next Plan Review

Fix Loop (INTERNAL)

The fix loop never pauses for user confirmation; never use AskUserQuestion in it. Which findings it fixes, and which it lists as follow-ups, follows the Review section of working-rules.md.

MAJOR_RETHINK is not a fix-loop input. Surface the reviewer's rationale and stop with BLOCKED: DESIGN_CONFLICT. NEEDS_HUMAN is not one either: stop and hand the reviewer's question to the person, on every backend. Only NEEDS_WORK enters the loop.

Attended: one fix pass, then one re-review, whose verdict is terminal. When working-rules.md's review loop applies (an unattended run, or a request to review until SHIP), repeat the steps below until SHIP or an ESCALATE:. The flowctl cap below stays as the backstop; never keep an agent-side counter.

The cap is enforced deterministically by flowctl: every dispatch reserves a spec-scoped round before launch. SHIP / NEEDS_WORK / MAJOR_RETHINK / NEEDS_HUMAN consume it; a no-verdict transport failure is durably recorded and refunded. At ${MAX_REVIEW_ITERATIONS:-8} verdict rounds, flowctl refuses with ESCALATE: and exit 4. More than ${MAX_REVIEW_TRANSPORT_FAILURES:-2} consecutive no-verdict failures stop separately with TRANSPORT_UNHEALTHY + exit 5. Callers invoke plan-review once and act on its terminal result. The verdict counter resets only on SHIP or an explicit re-plan, never on an edit, fresh invocation, or transport failure.**

ANTI-PATTERN: a delivered verdict is never a transport failure - never re-dispatch or re-frame NEEDS_WORK as a backend/sandbox problem to claim a refund. And never widen the reviewer sandbox: reviewers are read-only by contract, so a sandbox-blocked reviewer means something asked it to mutate the workspace. Fix that instead (Windows resolves via auto).

When the verdict is NEEDS_WORK:

1. Parse all valid issues from reviewer feedback.

2. Fix the user-edited current spec, never a checkpoint copy: edit the spec file in place (spec_path from $FLOWCTL show <SPEC_ID> --json), then persist that file. The file on disk is the input, so an edit the user made between cycles survives; on a set-plan failure, surface its error and stop the cycle.

   $FLOWCTL spec set-plan <SPEC_ID> --file <spec path> --json

3. Sync affected task specs when requirements, acceptance, design decisions, interfaces, retry/error semantics, or state values changed.

4. Re-enter the SAME selected backend file's re-review step. Never load or mix another backend. Codex/Copilot/Cursor/Claude resume only through a same-mode receipt; host uses a fresh read-only subagent.

5. Attended, stop after that one re-review: SHIP completes; NEEDS_WORK surfaces the surviving findings to the caller, never a second fix pass. In the review loop, repeat from step 1 as above.

Done when: the review ends in one of exactly five states — a SHIP from the backend, a re-review NEEDS_WORK with its surviving findings surfaced, a MAJOR_RETHINK escalated as BLOCKED: DESIGN_CONFLICT, a RETRY: no verdict (backend or transport failure) from a backend/transport failure, or flowctl's ESCALATE: cap refusal with the surviving findings surfaced. A round that ends with a NEEDS_WORK neither fixed in the current spec nor re-entered into the same backend has broken this.

Maintainability pointer. When the verdict's maintainability: block names a finding (anything other than none identified): read references/maintainability-pointer.md and record it.

Recovery after context compaction:

$FLOWCTL checkpoint restore --spec <SPEC_ID> --json

Every re-review follows the selected backend file's receipt/status rules.