Retroactive review loop
This document is the normative reference for the retroactive routing
engine that closes the REVIEW stage of the lifecycle introduced in
ADR-0010 — specifically
Stage definitions → REVIEW. It operationalises the requirements of
specs/0005-retroactive-routing-engine.md
and the contract layered on top by AGENTS.md → Retroactive review
loop. Every section below traces back to one of spec 0005's
requirements R1..R14.
Finding classes and routing
Every REVIEW finding SHALL be tagged with exactly one class. Class drives the loop target.
| Finding class | Loop target | Re-spawn | Spec-PR impact |
|---|---|---|---|
tech |
DEV | developer + tester | none |
arch |
PLAN | architect → developer + tester | none |
spec |
SPECS | spec-author → architect → developer + tester | new delta-spec PR (per #170) |
Rules:
- The loop SHALL NOT change the logbook issue (Rule A still holds).
Termination. The lifecycle terminates at MERGE iff a REVIEW pass verdict is APPROVE AND the pass surfaces zero findings of any class AND CI is green on the head commit reviewed.
Max-iteration guardrail. The loop halts after 5 iterations (configurable in the spec frontmatter, default 5) without termination. On halt, the orchestrator posts a structured summary on the logbook issue and pages the user regardless of mode (including AUTO).
Definitions of each class, canonical and borderline examples, and the disambiguation rule (escalate upstream on tie) live in ADR-0010 → Finding classification taxonomy. The routing engine itself lands in issue #172.
Deferred-findings ledger
Non-blocking findings MAY be routed to a persistent findings ledger rather than into the retroactive routing loop (see Non-blocking conditional routing below).
Turnover-shaped findings — an inbound cause. A finding a seated pass raises on a surface unchanged since that seat last examined it, carrying no statement of which condition returned that surface to scope (docs/reviewer-seat.md → A finding on an unchanged surface), SHALL be treated as non-blocking and routed here; the iteration SHALL NOT be routed to an upstream stage on its account. In INTERMEDIATE, MINIMAL and AUTO the orchestrator applies this disposition directly, as Non-blocking conditional routing below already requires. In FULL it is the disposition the orchestrator presents in that same section's per-finding triage: the user's loop / ledger / dismiss choice, and Termination condition 4's treatment of a FULL-mode loop-routed finding, are unchanged — spec 0166 R20 forbids the seat contract from removing that gate.
Ledger shape and ownership. The project maintains exactly one findings ledger: a pinned GitHub issue titled 📋 Findings ledger — deferred non-blocking findings carrying the deferred-findings-ledger label. It serves as the single sink for all ledger-routed findings and SHALL never be closed. Each entry records the source PR number, source ticket number, finding class, a one-line summary, date routed, and the routing actor.
Journalling. The orchestrator SHALL journal every ledger-route disposition on the active logbook issue (one line per finding: finding ref, disposition ledger, actor).
Drain protocol. The project maintainer triggers a drain pass by posting a DRAIN comment on the ledger issue. Each open entry is evaluated as:
- Promote: Finding is material; open a new ticket to address it.
- Accept: Finding is noted but not actionable; close entry with rationale.
- Carry: Finding is still relevant but not urgent; leave open.
The maintainer is the sole decision-maker for each disposition.
Growth guardrail. To prevent unbounded growth:
- The orchestrator posts a warning on the logbook issue when open entries exceed 10.
- The orchestrator pages the user and blocks all further ledger-route operations when open entries exceed 20, until a DRAIN comment is posted and at least one entry is disposed.
Doc-only engine
The engine is a documented procedure the orchestrator (the
team-lead role) follows, not an executable script (spec 0005 R1).
Until friction on the first ten real REVIEW loops justifies otherwise,
no helper binary, no parser, no review-comment crawler ships with this
spec — the orchestrator reads the verdict, applies the rules below,
and acts. A scripted variant is a candidate follow-up tracked in
specs/0005-retroactive-routing-engine.md → Out of scope; pre-empting
it would encode guesses about a routing surface no live run has
exercised end-to-end.
The reading audience is the orchestrator. Reviewers (architect,
pr-reviewer, spec-author when acting as spec reviewer) need only
the Class tagging discipline section below; downstream skills
(developer, tester, spec-author in delta mode) need only the
Routing matrix row that names them.
REVIEW launch trigger
The REVIEW stage begins the moment the implementation PR exists on the remote. The orchestrator SHALL:
- Apply the
iter:1label to the implementation PR (per Iteration counter — GitHub label). - Immediately instantiate the
review/<ticket>seat with a references-only brief — no pause, no prompt, no user acknowledgement requested. The brief's contents, and the seat's obligations, are defined indocs/reviewer-seat.md; theiter:1-before-instantiation ordering above is unchanged.
The spawn sequence is mode-conditional:
| Mode | Action |
|---|---|
| INTERMEDIATE | Apply iter:1 label; spawn pr-reviewer immediately. |
| MINIMAL | Apply iter:1 label; spawn pr-reviewer immediately. |
| AUTO | Apply iter:1 label; spawn pr-reviewer immediately. |
| FULL | Post the non-blocking start-of-iteration notification on the logbook issue (per AGENTS.md → Interaction modes); apply iter:1 label; spawn pr-reviewer immediately. The notification does NOT block spawning. |
Process violation. Pausing after PR creation and waiting for user input before spawning the reviewer is a process violation in INTERMEDIATE, MINIMAL, and AUTO modes. The REVIEW loop in those modes is fully autonomous from the moment the PR exists — no user gate fires until the max-iteration guardrail (see Max-iteration guardrail) or the final merge-authorization request.
Routing matrix
The matrix below is the engine's authoritative reference. It is also restated in condensed form in ADR-0010 → Routing matrix for cross-section navigability; the duplication is intentional, and the two surfaces SHALL stay in lockstep when either is amended.
| Class | Loop target | Re-spawn sequence | Spec-PR impact |
|---|---|---|---|
tech |
DEV | developer (+ tester if the touched surface includes test code) |
none |
arch |
PLAN | architect (PLAN-author) → on revalidation, DEV team re-runs from start of the matching template (per AGENTS.md → Standard Team Templates) |
none |
spec |
SPECS | spec-author in delta-spec mode → spec-PR review → on merge, PLAN re-runs (fresh architect), then DEV team re-runs |
new delta-spec PR (per spec 0003 → Delta-spec cumulative rule) |
The re-spawn columns are minimums. Every re-spawn SHALL apply the
security rule from AGENTS.md → Standard Team Templates →
Security rule if the touched surface qualifies; the engine does not
override the rule, it inherits it.
Delta-spec baseline reset. When a spec-class iteration produces
and merges a new delta-spec PR, the return to the PLAN stage initiates a
fresh planning baseline against the amended specification: the PLAN-revision
counter resets to zero for that subsequent iteration (per
docs/plan-review-protocol.md → PLAN-loop cap).
Class tagging discipline
Every reviewer finding SHALL carry exactly one class: field whose
value is one of tech, arch, or spec (spec 0005 R2). The tag is
the only signal the engine reads — without it, routing is undefined.
Untagged-finding round-trip. A REVIEW verdict that contains at
least one finding without a class: field is malformed. The
orchestrator SHALL NOT consume it. Instead (spec 0005 R3):
- Post a comment on the relevant PR (implementation-PR for
tech/archcandidates, spec-PR forspeccandidates) explicitly requesting retagging, naming each unlabeled finding by its index. - Re-issue the verdict from the same seat (a fresh agent holding no
session state, per
docs/reviewer-seat.md→ Retagged verdicts) with the retag instruction. The retag opens no new dossier entry, and the corrected verdict replaces the malformed one in the dossier. - Do NOT increment the iteration counter for this pass. A malformed verdict does not count as an iteration consumed against the max-iteration guardrail (R9). The engine refuses to penalise the implementation team for the reviewer's protocol violation.
The orchestrator SHALL NOT default an untagged finding to tech — a
silent default would conceal a reviewer defect and would drift the
loop target away from the most upstream class present.
Routing precedence
A single REVIEW pass MAY surface findings of multiple classes. The engine SHALL pick the most upstream class present and route the entire iteration to the corresponding stage (spec 0005 R4):
precedence: spec > arch > tech
Findings of lower-precedence classes from the same pass SHALL NOT be
silently dropped — they SHALL be re-tagged onto the next iteration's
verdict by the same seat's next pass (spec 0005 R5; the seat is
defined in docs/reviewer-seat.md). The precedence
order above is unchanged. The engine does not parallelise multi-class
routing within a single iteration; parallelising would fan out the team
and require synchronizing N upstream re-spawns against a single PR,
which the spec-PR workflow
(spec 0003) and the plan-review protocol (spec 0004) explicitly
forbid by their one-artifact-per-stage discipline.
The disambiguation rule on a tie at SPECS time (arch vs spec,
tech vs arch) — escalate upstream — lives in ADR-0010 →
Finding classification taxonomy. The engine inherits it; it does
not redefine it.
Spec-class loop — delta mode only
A spec-class iteration SHALL invoke spec-author in delta-spec
mode (spec 0005 R6). The original spec on main is immutable per
ADR-0010 and spec 0003 — the delta-spec accumulates as a new file
/specs/<NNNN>-<slug>.delta-<NN>.md on a fresh branch
spec/<NNNN>-<slug>-delta-<NN> cut from main, reviewed as its own
spec-PR, and merged independently. The implementation-PR then
absorbs the delta on the next iteration per spec 0003 →
Delta-spec cumulative rule.
Re-authoring a fundamentally broken spec — status transition to
superseded — is out of the loop. It is a new-ticket path:
abandon the implementation-PR, open a fresh ticket whose SPECS stage
authors a replacement spec (frontmatter superseded-by: <new-id> on
the old, superseded on its status line). The loop owns deltas;
it does not own full re-authoring.
Spec-PR ordering guard
When an implementation branch (feat/<NNNN>-<slug> and siblings) is
opened against main while the corresponding spec-PR is still open,
the REVIEW pass on that implementation-PR SHALL emit a class: tech
finding citing docs/spec-pr-workflow.md →
Ordering rule (and
specs/0003-spec-pr-workflow.md →
Ordering rule), and the implementation-PR SHALL NOT be retried until
the spec-PR is merged on main.
Iteration counter — GitHub label
The iteration counter SHALL be persisted as a GitHub label iter:N
on the PR (spec 0005 R7). The label is the engine's source of truth
for "what iteration are we on" — no shadow counter in memory, no
parsing of comment timestamps, no spreadsheet.
Which PR carries the label. The label lives on the PR whose content the iteration is reshaping:
techandarchiterations → label on the implementation-PR (feat/<NNNN>-<slug>or sibling).speciterations → label on the spec-PR for the active delta (spec/<NNNN>-<slug>-delta-<NN>). Once the delta-spec merges and the implementation-PR resumes its loop, the implementation-PR'siter:Nlabel increments on the next pass; the spec-PR's label becomes a permanent record of how many spec-class passes the ticket required.
Increment mechanism. Atomic via the GitHub label API:
gh pr edit <pr-number> --add-label "iter:<N>" --remove-label "iter:<N-1>"
Run the command at the start of every new iteration, after a verdict has been validated as well-formed (untagged-finding round- trips do NOT increment, see Class tagging discipline above). The command is idempotent against repeated invocation on the same N and cross-session-safe by virtue of being a GitHub primitive — two sibling orchestrators racing the same PR converge on the same label state without coordinating through MemPalace.
Initial label. The iter:1 label SHALL be applied to the PR
before the first reviewer is spawned — between PR creation and
reviewer launch, not after the first verdict is consumed (see
REVIEW launch trigger for the exact step ordering). PRs that never
need a second pass therefore carry exactly one iter:N label on
merge — a useful searchable signal for ticket-difficulty
retrospectives.
Termination
The lifecycle terminates at MERGE iff all four conditions hold on the same REVIEW pass (spec 0005 R8, as amended by spec 0162):
- The verdict line is
### Verdict: APPROVE. - The pass surfaces zero blocking findings of any class.
- CI is green on the head commit reviewed. The engine SHALL
query
gh pr checks <pr-number>and confirm every required check ispass; pending or failing checks block termination regardless of the verdict text. - Every non-blocking finding in the pass has been disposed as ledger or dismiss (FULL: per user triage; others: auto-ledger). Non-blocking findings loop-routed by the user in FULL mode count as blocking for this purpose.
All four are necessary. An APPROVE with one blocking finding is one finding away
from termination. An APPROVE with zero blocking findings and red CI is a
reviewer who skipped the CI-status section of pr-reviewer →
Preflight; the engine SHALL flag this as a protocol violation and
re-instantiate the same seat. A seat's bounded reading
(docs/reviewer-seat.md → Bounded scope from the
second pass) never waives this: the continuous-integration state of the
current head is inside the bound on every pass, whatever else the pass is
excused from re-examining.
Max-iteration guardrail
The loop SHALL halt after 5 iterations without termination (spec
0005 R9). The default is configurable per ticket via the spec
frontmatter max-iterations field (docs/spec-format.md →
Frontmatter schema); the engine reads the value at SPECS time and
caches it for the duration of the lifecycle.
On halt, the orchestrator SHALL:
- Post a structured summary comment on the logbook issue. The summary lists, per iteration: the class routed, the role(s) re-spawned, the verdict outcome, and the carry-over findings (if any).
- Page the user regardless of mode — including AUTO. The guardrail is the one place where AUTO breaks its no-user-round-trip contract: five autonomous iterations without convergence is the engine's signal that the ticket has crossed from "automation-tractable" to "needs human judgment", and the user is the only role that can decide the next move (abandon, re-scope, lift the cap, etc.).
The guardrail SHALL NOT auto-increment past the cap. The orchestrator stops the loop; the user resumes it (or terminates it) explicitly.
Non-blocking conditional routing
Reviewer findings carry an implicit blocking / non-blocking classification: blocking findings prevent merge, non-blocking findings are observations the reviewer surfaces without gating the verdict. The engine routes non-blocking findings conditionally on the lifecycle's interaction mode (spec 0005 R10):
| Mode | Non-blocking finding handling |
|---|---|
| FULL | The orchestrator SHALL present every non-blocking finding to the user. The user SHALL choose per finding: loop (routed into the retroactive loop via the blocking matrix), ledger (routed to the findings ledger), or dismiss (journalled in the logbook and left unactioned). |
| INTERMEDIATE | The orchestrator SHALL route every non-blocking finding to the ledger by default. No user gate SHALL fire. |
| MINIMAL | Same as INTERMEDIATE — the orchestrator SHALL route to the ledger by default; no user gate SHALL fire. |
| AUTO | Same as MINIMAL — the orchestrator SHALL route to the ledger by default; no user gate SHALL fire. |
The asymmetry reflects the lifecycle's gating philosophy: only FULL keeps the user in the loop during REVIEW and gives the user the last word on scope; every other mode delegates scope to the engine and routes every signal through the matrix so that termination genuinely means "no work left", not "no work the engine bothered to do".
Worked example — PR #183 iteration 2
The closest live fixture is the second iteration of PR #183 (the
plan-format ticket, issue #169), where the cold review surfaced three
non-blocking findings under INTERMEDIATE mode. Under the model as
amended for #288, INTERMEDIATE fires no REVIEW gate, so the engine
routes all three findings into the loop using the same precedence
matrix as blocking findings — none are presented to the user for a
keep-or-defer decision. Had the same findings surfaced under FULL,
the orchestrator would instead present them for a bounded per-pass
triage and route only the ones the user accepts (per the table above).
The fixture predates this spec's iter:N label convention — the
label was not applied retroactively — so readers should treat the
example as a retrofit ("had the engine existed, here is how it would
route today") rather than a literal record of label state.
Cross-references
- Spec 0005 —
specs/0005-retroactive-routing-engine.md. - ADR-0010 —
docs/adr/0010-spec-plan-review-lifecycle.md, specifically Stage definitions → REVIEW and Finding classification taxonomy. - Plan format and review protocol —
docs/plan-format.mdandAGENTS.md→ Plan review protocol. - Spec format and delta-spec convention —
docs/spec-format.md. - Spec-PR workflow —
specs/0003-spec-pr-workflow.mdandAGENTS.md→ Spec-PR workflow. - Team Communication Rule 4 —
AGENTS.md→ Agent Team Protocol → Team Communication. - Reviewer seat contract —
docs/reviewer-seat.mdandspecs/0166-stable-reviewer-seat.md.