<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/2.x/2026-02-09-2-wp-lifecycle-state-machine/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-02-09-2-wp-lifecycle-state-machine/</id>
  <title>WP Lifecycle State Machine</title>
  <updated>2026-02-09T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/2.x/2026-02-09-2-wp-lifecycle-state-machine/"/>
  <summary>Introduced a guarded lane transition matrix with claimed, blocked, and canceled states so concurrent agents could not jump straight from planned to done.</summary>
  <content type="html">&lt;blockquote&gt;
&lt;p&gt;Superseded by &lt;code dir=&quot;auto&quot;&gt;2026-04-03-2-review-approval-and-integration-completion-are-distinct.md&lt;/code&gt;,
which is itself partially superseded by &lt;code dir=&quot;auto&quot;&gt;2026-04-06-1-wp-state-pattern-for-lane-behavior.md&lt;/code&gt;.
&lt;code dir=&quot;auto&quot;&gt;2026-04-06-1&lt;/code&gt; is the current authority for the full 9-lane state machine.&lt;/p&gt;
&lt;p&gt;This ADR encoded a 7-lane model with &lt;code dir=&quot;auto&quot;&gt;for_review -&gt; done&lt;/code&gt; as reviewer approval.
The current lifecycle separates reviewer approval (&lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt;) from integrated
completion (&lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt;), promotes &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; to a first-class 9th lane, and
encapsulates all lane behavior in the &lt;code dir=&quot;auto&quot;&gt;WPState&lt;/code&gt; ABC.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;The current WP lifecycle uses an implicit 4-lane model (&lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;doing&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt;) with no formal transition validation or guard conditions. Any lane can be written directly, enabling invalid jumps (e.g., &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; without review). There is no blocked or canceled state, no ownership tracking beyond “doing”, and no forced-transition audit trail.&lt;/p&gt;
&lt;p&gt;The state machine operates on events from the canonical append-only event log defined in ADR 2026-02-09-1. Each state transition corresponds to an event appended to the log.&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;Multi-agent conflict prevention&lt;/strong&gt; — Multiple agents claiming or working the same WP must be detected&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Review authority&lt;/strong&gt; — Reviewer rollback must be enforceable, not silently overridden&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Blocked work visibility&lt;/strong&gt; — Stalled work must be surfaced, not hidden in “doing”&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Evidence-based transitions&lt;/strong&gt; — Guard conditions must enforce proof at each transition&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Deterministic replay&lt;/strong&gt; — A fixed state machine enables automated merge validation&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 current 4-lane model with added validation&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; 7-lane state machine with strict transition matrix&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; Full kanban with unlimited custom columns&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 4:&lt;/strong&gt; Simple binary (open/closed) with tags&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:&lt;/strong&gt; “Option 2: 7-lane state machine with strict transition matrix”, because it adds explicit ownership tracking (&lt;code dir=&quot;auto&quot;&gt;claimed&lt;/code&gt;), blocked work visibility (&lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt;), clean lifecycle termination (&lt;code dir=&quot;auto&quot;&gt;canceled&lt;/code&gt;), and mandatory guard conditions — all required for safe concurrent multi-agent work.&lt;/p&gt;
&lt;h3 id=&quot;implementation&quot;&gt;Implementation&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Lanes:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;claimed&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&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;p&gt;&lt;strong&gt;Allowed transitions (9 total):&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;planned → claimed&lt;/code&gt; — Agent declares intent to work&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;claimed → in_progress&lt;/code&gt; — Work actively begins (workspace context established)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;in_progress → for_review&lt;/code&gt; — Implementation complete, submitted for review&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;for_review → done&lt;/code&gt; — Reviewer approves (terminal)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;for_review → in_progress&lt;/code&gt; — Changes requested by reviewer&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;in_progress → planned&lt;/code&gt; — Abandon/reassign (mandatory reason)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;any → blocked&lt;/code&gt; — External blocker identified&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;blocked → in_progress&lt;/code&gt; — Blocker resolved&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;any (except done) → canceled&lt;/code&gt; — WP abandoned or superseded (terminal)&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Guard conditions (6):&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;planned → claimed&lt;/code&gt;: Assignee must be set; no conflicting active claim&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;claimed → in_progress&lt;/code&gt;: Active workspace context must be established&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;in_progress → for_review&lt;/code&gt;: Required subtasks complete OR force flag with reason&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;for_review → done&lt;/code&gt;: Reviewer identity and approval evidence required (per ADR 2026-02-09-4)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;for_review → in_progress&lt;/code&gt;: Review feedback reference required&lt;/li&gt;
&lt;li&gt;Any forced transition: Actor identity and reason are mandatory&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Explicit ownership tracking — &lt;code dir=&quot;auto&quot;&gt;claimed&lt;/code&gt; prevents phantom progress and concurrent claim conflicts&lt;/li&gt;
&lt;li&gt;Blocked state surfaces stalled work — no more hidden “doing” with no progress&lt;/li&gt;
&lt;li&gt;Guard conditions enforce evidence at every transition&lt;/li&gt;
&lt;li&gt;Forced transitions are always auditable (actor + reason recorded)&lt;/li&gt;
&lt;li&gt;Terminal &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; prevents accidental regression&lt;/li&gt;
&lt;li&gt;Deterministic replay — fixed state machine enables merge validation (ADR 2026-02-09-3)&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;More states = more complexity (7 lanes, 9 transitions vs 4 lanes, ~4 transitions)&lt;/li&gt;
&lt;li&gt;Migration required for existing WPs (&lt;code dir=&quot;auto&quot;&gt;doing&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;Guard conditions add friction to rapid prototyping&lt;/li&gt;
&lt;li&gt;Learning curve for new contributors&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Force-with-reason escape valve allows legitimate overrides while maintaining audit trail&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;status doctor&lt;/code&gt; command provides automated detection of stale claims and orphan contexts&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;CI validation: every merge triggers a transition validity scan against the state machine&lt;/li&gt;
&lt;li&gt;Migration: &lt;code dir=&quot;auto&quot;&gt;doing&lt;/code&gt; maps to &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt;; other lanes map 1:1&lt;/li&gt;
&lt;li&gt;Operational playbooks (PRD Section 13) cover common scenarios&lt;/li&gt;
&lt;/ul&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;keep-current-4-lane-model-with-added-validation&quot;&gt;Keep current 4-lane model with added validation&lt;/h3&gt;
&lt;p&gt;Retain &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;doing&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; but add transition validation.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No migration required&lt;/li&gt;
&lt;li&gt;Simpler mental model — fewer states&lt;/li&gt;
&lt;li&gt;Backward-compatible with all existing tooling&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;Cannot distinguish &lt;code dir=&quot;auto&quot;&gt;claimed&lt;/code&gt; from active work — phantom ownership undetectable&lt;/li&gt;
&lt;li&gt;Cannot represent &lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt; — stalled work invisible&lt;/li&gt;
&lt;li&gt;Cannot represent &lt;code dir=&quot;auto&quot;&gt;canceled&lt;/code&gt; — abandoned WPs linger indefinitely&lt;/li&gt;
&lt;li&gt;Weaker guard conditions (no workspace context check, no claim uniqueness)&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;full-kanban-with-unlimited-custom-columns&quot;&gt;Full kanban with unlimited custom columns&lt;/h3&gt;
&lt;p&gt;Allow projects to define arbitrary lane names and transition rules.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Maximum flexibility — teams define their own workflow&lt;/li&gt;
&lt;li&gt;Supports domain-specific states (e.g., “testing”, “staging”, “deployed”)&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;No standard transition validation possible&lt;/li&gt;
&lt;li&gt;Complexity explosion — custom lanes require custom guards, merge semantics, CI rules&lt;/li&gt;
&lt;li&gt;Deterministic merge requires a known, fixed state machine&lt;/li&gt;
&lt;li&gt;Interoperability between projects breaks if lane names differ&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;simple-binary-openclosed-with-tags&quot;&gt;Simple binary (open/closed) with tags&lt;/h3&gt;
&lt;p&gt;Two states (&lt;code dir=&quot;auto&quot;&gt;open&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;closed&lt;/code&gt;) with free-form tags for substates.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Minimal state machine — only one transition to validate&lt;/li&gt;
&lt;li&gt;Tags provide flexibility without schema changes&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;No transition validation — tags are unstructured&lt;/li&gt;
&lt;li&gt;Tags don’t compose into deterministic state&lt;/li&gt;
&lt;li&gt;Merge semantics for tag sets are undefined&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;Related ADRs:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;ADR 2026-02-09-1 (Canonical WP Status Model) — state machine consumes events from this log&lt;/li&gt;
&lt;li&gt;ADR 2026-02-09-3 (Event-Log Merge Semantics) — replays events through this state machine&lt;/li&gt;
&lt;li&gt;ADR 2026-02-09-4 (Cross-Repo Evidence Completion) — evidence payloads satisfy guard conditions&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;References:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Harel Statecharts — &lt;a href=&quot;https://www.wisdom.weizmann.ac.il/~dharel/SCANNED.PAPERS/Statecharts.pdf&quot;&gt;https://www.wisdom.weizmann.ac.il/~dharel/SCANNED.PAPERS/Statecharts.pdf&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;XState Documentation — &lt;a href=&quot;https://xstate.js.org/docs/&quot;&gt;https://xstate.js.org/docs/&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;PRD: Feature Status State Model Remediation (Sections 7, 8, 13, 14)&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
