<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-04-03-2-review-approval-and-integration-completion-are-distinct/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-03-2-review-approval-and-integration-completion-are-distinct/</id>
  <title>Review Approval and Integration Completion Are Distinct</title>
  <updated>2026-04-03T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-04-03-2-review-approval-and-integration-completion-are-distinct/"/>
  <summary>Splits reviewer sign-off from completion by adding an approved lane, so done means integrated with acceptance evidence recorded, not merely reviewed.</summary>
  <content type="html">&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Partial supersession (2026-04-06):&lt;/strong&gt; The core decision of this ADR — adding an explicit &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; lane and separating reviewer approval from integration-complete — remains in force. However, the &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; lane promotion section is superseded by &lt;code dir=&quot;auto&quot;&gt;2026-04-06-1-wp-state-pattern-for-lane-behavior.md&lt;/code&gt;, which promotes &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; from an alias for &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; to a first-class 9th lane with its own concrete &lt;code dir=&quot;auto&quot;&gt;WPState&lt;/code&gt; class and conflict-detection guard. The transition model in the &lt;em&gt;Decision Outcome&lt;/em&gt; section below reflects the pre-&lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt;-promotion design; see &lt;code dir=&quot;auto&quot;&gt;2026-04-06-1&lt;/code&gt; for the current canonical transition set.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Spec Kitty’s current 2.x lifecycle model still encodes &lt;code dir=&quot;auto&quot;&gt;for_review -&gt; done&lt;/code&gt; as
“reviewer approves”. That makes &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; mean “review passed”. But the newer
command/runtime direction and the actual product requirement are stricter:
&lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; must mean “integrated and acceptance-complete”, not merely “a reviewer
liked the branch diff”.&lt;/p&gt;
&lt;p&gt;This semantic gap produced contradictory behavior:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;prompts and reviewers could treat approval as completion,&lt;/li&gt;
&lt;li&gt;merge/integration logic needed &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; to mean the work was actually integrated,&lt;/li&gt;
&lt;li&gt;feature acceptance could be declared complete while forbidden fallback paths
still existed in the integrated product.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Feature &lt;code dir=&quot;auto&quot;&gt;028-saas-active-projects-shell&lt;/code&gt; exposed the consequence: work package
review was treated as effectively terminal even though the integrated feature
still violated the user journey.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Semantic clarity&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; must have one meaning everywhere.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Review/integration separation&lt;/strong&gt; — reviewer approval and integrated feature
completion are different events.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Merge safety&lt;/strong&gt; — the state model must not imply that branch-level review is
equivalent to product-level completion.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Evidence alignment&lt;/strong&gt; — review evidence and integration evidence should not
be conflated into one transition.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Command parity&lt;/strong&gt; — prompts, &lt;code dir=&quot;auto&quot;&gt;next&lt;/code&gt;, review flows, and merge guards must use
the same lifecycle semantics.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option 1:&lt;/strong&gt; Keep &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; meaning “review approved” and encode integration elsewhere&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; Keep the 7-lane model but add extra completion metadata flags&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; Add an explicit &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; lane before &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option: Option 3&lt;/strong&gt;, because the lifecycle needs an explicit state for
“review approved but not yet integration-complete”.&lt;/p&gt;
&lt;h3 id=&quot;core-decision&quot;&gt;Core Decision&lt;/h3&gt;
&lt;p&gt;The canonical WP lanes become:&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;planned -&gt; claimed -&gt; in_progress -&gt; for_review -&gt; approved -&gt; done&lt;/code&gt;&lt;/p&gt;
&lt;p&gt;plus &lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;canceled&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;state-semantics&quot;&gt;State Semantics&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; means implementation is ready for reviewer inspection.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; means reviewer approval has been granted for the current
implementation.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; means the work is integrated into the mission integration branch and
the required acceptance evidence has been recorded.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;transition-model&quot;&gt;Transition Model&lt;/h3&gt;
&lt;p&gt;At minimum, the following transitions are canonical:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;in_progress -&gt; for_review&lt;/code&gt; — implementation complete, evidence ready&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;for_review -&gt; approved&lt;/code&gt; — reviewer approval&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;for_review -&gt; in_progress&lt;/code&gt; — changes requested&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;approved -&gt; done&lt;/code&gt; — integration-complete and accepted&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;approved -&gt; in_progress&lt;/code&gt; — integration or acceptance uncovered required rework&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;evidence-split&quot;&gt;Evidence Split&lt;/h3&gt;
&lt;p&gt;Evidence requirements are split by transition:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;in_progress -&gt; for_review&lt;/code&gt; requires implementation evidence
(artifacts/tests/verification needed for review).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;for_review -&gt; approved&lt;/code&gt; requires review evidence
(reviewer identity, verdict, and reference).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;approved -&gt; done&lt;/code&gt; requires integration and acceptance evidence
(mission-branch integration proof and acceptance proof).&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;No single event is allowed to claim both review approval and integration-complete
status unless the system can prove both happened in the same operation.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; now means one thing everywhere: integrated and accepted.&lt;/li&gt;
&lt;li&gt;Review approval becomes visible and auditable as its own state.&lt;/li&gt;
&lt;li&gt;Feature-level acceptance can fail after branch review without violating the
lifecycle model.&lt;/li&gt;
&lt;li&gt;Evidence becomes easier to reason about because review evidence and acceptance
evidence are attached to different transitions.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative&quot;&gt;Negative&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;State-machine complexity increases from seven lanes to eight.&lt;/li&gt;
&lt;li&gt;Existing docs, prompts, guards, and tests that assume &lt;code dir=&quot;auto&quot;&gt;for_review -&gt; done&lt;/code&gt;
must be migrated.&lt;/li&gt;
&lt;li&gt;Historical tooling that equates “approved” with “done” needs explicit repair.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The append-only event log remains the canonical state authority.&lt;/li&gt;
&lt;li&gt;Existing blocked/canceled semantics remain unchanged.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;This decision is validated when:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;no prompt or command instructs &lt;code dir=&quot;auto&quot;&gt;for_review -&gt; done&lt;/code&gt; as mere approval,&lt;/li&gt;
&lt;li&gt;reviewer approval is represented as &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt;,&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; transitions require integration/acceptance evidence,&lt;/li&gt;
&lt;li&gt;integrated feature acceptance failures can reopen work from &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt;
without breaking lifecycle semantics.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-1-keep-done-meaning-review-approved&quot;&gt;Option 1: Keep &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; meaning review-approved&lt;/h3&gt;
&lt;p&gt;Treat reviewer approval as completion and keep integration as a separate informal
concept.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No lane migration required.&lt;/li&gt;
&lt;li&gt;Existing tooling keeps working in the short term.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; continues to mean different things in different parts of the system.&lt;/li&gt;
&lt;li&gt;Review approval and integrated completion remain conflated.&lt;/li&gt;
&lt;li&gt;The Feature 028 acceptance failure class remains structurally possible.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2-keep-seven-lanes-add-metadata-flags&quot;&gt;Option 2: Keep seven lanes, add metadata flags&lt;/h3&gt;
&lt;p&gt;Use side metadata to distinguish “approved” from “integrated”.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Avoids introducing another visible lane.&lt;/li&gt;
&lt;li&gt;Smaller migration surface for UIs that render lane chips.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Hidden state is harder to reason about than explicit lanes.&lt;/li&gt;
&lt;li&gt;Merge and review semantics become harder to validate deterministically.&lt;/li&gt;
&lt;li&gt;Encourages drift between lane rendering and actual completion meaning.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-3-add-explicit-approved-lane&quot;&gt;Option 3: Add explicit &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; lane&lt;/h3&gt;
&lt;p&gt;Use a distinct lane for reviewer approval before final integrated completion.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Makes the lifecycle honest and explicit.&lt;/li&gt;
&lt;li&gt;Aligns prompts, guards, and acceptance behavior.&lt;/li&gt;
&lt;li&gt;Allows reviewer approval to be preserved even if integration acceptance fails.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Requires lane/state migration work.&lt;/li&gt;
&lt;li&gt;UIs and reports must learn one more visible state.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Supersedes:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-02-09-2-wp-lifecycle-state-machine.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-02-09-4-cross-repo-evidence-completion.md&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Partially superseded by:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-04-06-1-wp-state-pattern-for-lane-behavior.md&lt;/code&gt; — supersedes the &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt;-as-alias approach; &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; is now a first-class lane&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Interprets alongside:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-02-09-3-event-log-merge-semantics.md&lt;/code&gt; — rollback-aware merge semantics
remain in force, but reviewer-forward progress is now &lt;code dir=&quot;auto&quot;&gt;for_review -&gt; approved&lt;/code&gt;
rather than &lt;code dir=&quot;auto&quot;&gt;for_review -&gt; done&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;architecture/adrs/2026-03-09-1-prompts-do-not-discover-context-commands-do.md&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Related ADRs:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-04-03-1-execution-lanes-own-worktrees-and-mission-branches.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-04-03-3-feature-acceptance-runs-on-the-integrated-mission-branch.md&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
