<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/4.x/2026-10-07-3-review-lane-exit-requires-verdict-or-forced-note/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-07-3-review-lane-exit-requires-verdict-or-forced-note/</id>
  <title>ADR: a work package leaves review or approval only through a verdict or a noted force</title>
  <updated>2026-10-07T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/4.x/2026-10-07-3-review-lane-exit-requires-verdict-or-forced-note/"/>
  <summary>The transition pipeline refuses a forced exit from in_review or approved that carries no verdict and no note, on every surface; migration actors are exempt.</summary>
  <content type="html">&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-10-07&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (repository owner).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; #5446 (&lt;code dir=&quot;auto&quot;&gt;agent action implement&lt;/code&gt; pulled a work package out of review with exit 0 and a made-up reason); the forced-approval restamp narrowing is #5721. Related: #5340, #5668, ADR &lt;a href=&quot;/adr/4.x/2026-10-04-5-approval-stamp-bounds-the-approved-claim/&quot;&gt;2026-10-04-5&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Reader:&lt;/strong&gt; a maintainer changing the status transition pipeline, a transition surface (&lt;code dir=&quot;auto&quot;&gt;move-task&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;agent status emit&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;orchestrator-api transition&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;agent action implement&lt;/code&gt;) or the review-state readers.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;A work package in &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; holds a reviewer’s claim or verdict. Before this change, &lt;code dir=&quot;auto&quot;&gt;agent action implement &amp;#x3C;WP&gt; --agent &amp;#x3C;other&gt;&lt;/code&gt; force-moved such a package to &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt; for any agent, with the reason “Re-implementing after review feedback”. Nothing in that event was a review outcome. The first fix guarded only the &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt; path, so &lt;code dir=&quot;auto&quot;&gt;move-task --force&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;agent status emit --force&lt;/code&gt; and the &lt;code dir=&quot;auto&quot;&gt;orchestrator-api&lt;/code&gt; transition verbs could still take a package out of review with no verdict and no explanation. &lt;code dir=&quot;auto&quot;&gt;move-task&lt;/code&gt; also minted a &lt;code dir=&quot;auto&quot;&gt;changes_requested&lt;/code&gt; review result for any &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; exit that was not an approval, so a forced &lt;code dir=&quot;auto&quot;&gt;--to blocked&lt;/code&gt; carried a verdict nobody gave.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;One rule, in the one pipeline.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;status/transition_pipeline.prepare_transition&lt;/code&gt; refuses a transition when all of these hold: it is forced, its from-lane is &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt;, it carries no &lt;code dir=&quot;auto&quot;&gt;review_result&lt;/code&gt;, and its reason is blank. The refusal is a &lt;code dir=&quot;auto&quot;&gt;TransitionError&lt;/code&gt; that names &lt;code dir=&quot;auto&quot;&gt;FORCE_NOTE_REQUIRED&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;FORCE_NOTE_HINT&lt;/code&gt;. The FSM already requires a non-blank reason for any force (&lt;code dir=&quot;auto&quot;&gt;WPState._check_force&lt;/code&gt;), so on &lt;code dir=&quot;auto&quot;&gt;agent status emit&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;orchestrator-api&lt;/code&gt; a bare force was already refused with a generic message; the leak was &lt;code dir=&quot;auto&quot;&gt;move-task&lt;/code&gt;, which filled the reason (&lt;code dir=&quot;auto&quot;&gt;Force move to &amp;#x3C;lane&gt;&lt;/code&gt;) and, for an &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; exit, a &lt;code dir=&quot;auto&quot;&gt;changes_requested&lt;/code&gt; verdict itself. The pipeline rule gives the exit its own named refusal and no longer lets a synthesized reason stand for a note. The pipeline stays git-free, so every surface that emits a transition gets the rule and renders the refusal in its own shape (exit 1 for &lt;code dir=&quot;auto&quot;&gt;move-task&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;agent status emit&lt;/code&gt;, a &lt;code dir=&quot;auto&quot;&gt;TRANSITION_REJECTED&lt;/code&gt; envelope for &lt;code dir=&quot;auto&quot;&gt;orchestrator-api&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A verdict is the only other way out.&lt;/strong&gt; A transition that records a &lt;code dir=&quot;auto&quot;&gt;review_result&lt;/code&gt; is the verdict and needs no note. &lt;code dir=&quot;auto&quot;&gt;move-task&lt;/code&gt; mints a rejection result only for the rework edges (&lt;code dir=&quot;auto&quot;&gt;-&gt; planned&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;-&gt; in_progress&lt;/code&gt;), never for another exit, and it passes a bare &lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt; out of those lanes to the pipeline with no reason, so the pipeline sees what the operator actually supplied.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Migration actors are exempt.&lt;/strong&gt; An actor starting with &lt;code dir=&quot;auto&quot;&gt;migration:&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;MIGRATION_ACTOR_PREFIX&lt;/code&gt;, now defined in &lt;code dir=&quot;auto&quot;&gt;status&lt;/code&gt; and imported by the consolidation attribution code) reconstructs state; it is not an operator act.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Implementer-of-record withdrawal stays on the &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt; path.&lt;/strong&gt; Only the work package’s implementer of record may withdraw an unclaimed &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; submission, and that check needs the event log, the caller’s actor and the claim holder, so it remains in &lt;code dir=&quot;auto&quot;&gt;status/work_package_lifecycle.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;_review_lane_exit_reason&lt;/code&gt;). &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; is not a verdict-gated lane, so the pipeline rule does not apply to it. An unforced &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt; on &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; is still refused there as a claim conflict naming the reviewer, or with the rework route.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A cleared review-result slot is “no verdict on record”.&lt;/strong&gt; The reducer writes &lt;code dir=&quot;auto&quot;&gt;review_result: null&lt;/code&gt; when a package leaves &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; with no verdict. &lt;code dir=&quot;auto&quot;&gt;ReviewResultLookup.cleared_without_verdict&lt;/code&gt; is true only for that raw &lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt;; the readers treat it like an absent slot, so the next review approves normally. A malformed value (not an object, or an object that does not parse) keeps failing closed with a message that names a route that works.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A forced approval is a review only when a review backs it (#5721).&lt;/strong&gt; A forced move into &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; restamps the consolidation bound only as an approved-reviewed attestation, an arbiter override, or a hop out of &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; that carries an approved &lt;code dir=&quot;auto&quot;&gt;review_result&lt;/code&gt; after an unforced move into &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt;. Two routes into that set stay open, both recorded operator acts: moving the package unforced into &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; and then forcing it to &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; with a synthesized approved result, and a reject followed by a forced arbiter-override approval.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Pipeline rule (chosen).&lt;/strong&gt; One place, one refusal, every surface.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Per-surface checks.&lt;/strong&gt; Rejected: that is how &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt; was fixed first and the other three surfaces stayed open.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Refuse every forced exit from review.&lt;/strong&gt; Rejected: an operator with a real reason (an unavailable reviewer, a damaged claim) needs the override; the note makes it auditable.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Move the implementer-of-record check into the pipeline as well.&lt;/strong&gt; Rejected: it needs implement-path context, and the pipeline reads no log.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;move-task &amp;#x3C;WP&gt; --to &amp;#x3C;lane&gt; --force&lt;/code&gt; out of &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; needs &lt;code dir=&quot;auto&quot;&gt;--note&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;agent status emit&lt;/code&gt; needs &lt;code dir=&quot;auto&quot;&gt;--reason&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;orchestrator-api transition&lt;/code&gt; needs &lt;code dir=&quot;auto&quot;&gt;--note&lt;/code&gt;. Without it nothing is written.&lt;/li&gt;
&lt;li&gt;A forced &lt;code dir=&quot;auto&quot;&gt;approved -&gt; done&lt;/code&gt; is also a forced exit from &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; and needs a note.&lt;/li&gt;
&lt;li&gt;An unforced &lt;code dir=&quot;auto&quot;&gt;move-task&lt;/code&gt; out of &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; to a lane other than &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt; or an approval no longer gets a minted &lt;code dir=&quot;auto&quot;&gt;changes_requested&lt;/code&gt; result; the FSM refuses it for want of a review result, and the route is &lt;code dir=&quot;auto&quot;&gt;--force --note&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The rule judges the request, not the log: a reason of any non-blank text satisfies it. The note is evidence for the audit trail, not a check that the reason is true.&lt;/li&gt;
&lt;li&gt;Reversible only by a new decision; the cross-surface test in &lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/cli/commands/agent/test_approval_after_forced_review_exit.py&lt;/code&gt; fails when any surface bypasses the pipeline rule.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
