<?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-06-1-wp-state-pattern-for-lane-behavior/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-04-06-1-wp-state-pattern-for-lane-behavior/</id>
  <title>WP State Pattern for Lane Behavior</title>
  <updated>2026-04-06T00: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-06-1-wp-state-pattern-for-lane-behavior/"/>
  <summary>Replaces the flat transition matrix and procedural guard dispatcher with nine frozen lane-state classes that own their own targets, guards, and display buckets.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;The spec-kitty work-package lifecycle previously used an 8-lane state machine implemented as a flat transition matrix (&lt;code dir=&quot;auto&quot;&gt;ALLOWED_TRANSITIONS&lt;/code&gt; frozenset) and a procedural guard dispatcher (&lt;code dir=&quot;auto&quot;&gt;_run_guard()&lt;/code&gt;). This ADR promotes &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; to a first-class 9th lane (see Decision below). Research (mission 065 Finding 3) identified:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;358 lane string literals&lt;/strong&gt; scattered across 46 files&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;3 duplicated &lt;code dir=&quot;auto&quot;&gt;LANES&lt;/code&gt; tuples&lt;/strong&gt; in separate modules&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Procedural guard dispatch&lt;/strong&gt; via a chain of &lt;code dir=&quot;auto&quot;&gt;elif&lt;/code&gt; branches — adding a new guard requires modifying the dispatcher, not the state that owns the behavior&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; treated as an alias&lt;/strong&gt; for &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt;, creating a concurrency blind spot: multiple agents cannot distinguish “awaiting review” from “review actively in progress”&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The question: how should lane-specific behavior (allowed targets, guard conditions, terminal/blocked classification, display metadata) be colocated with the lane identity?&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;Colocate behavior with identity&lt;/strong&gt;: each lane should own its allowed transitions, guards, and display metadata&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Preserve existing API&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;validate_transition()&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;ALLOWED_TRANSITIONS&lt;/code&gt; must remain accessible for non-migrated consumers (Strangler Fig)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Promote &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt;&lt;/strong&gt;: resolve the concurrency blind spot by making &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; a first-class 9th lane&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Type safety&lt;/strong&gt;: enable exhaustive match checking — adding a 10th lane should cause compile-time failures if behavior is missing&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Value-object semantics&lt;/strong&gt;: states are immutable, equal by attributes, and cheap to construct (&amp;#x3C; 1 ms)&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: ABC + frozen dataclass&lt;/strong&gt; (State Pattern)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2: Protocol-based structural typing&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3: Extend &lt;code dir=&quot;auto&quot;&gt;Lane(StrEnum)&lt;/code&gt; with methods&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 4: Dictionary-of-functions dispatch table&lt;/strong&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:&lt;/strong&gt; “ABC + frozen dataclass” (Option 1), because it colocates behavior with state identity while preserving shared default implementations (&lt;code dir=&quot;auto&quot;&gt;transition()&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;is_terminal&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;is_blocked&lt;/code&gt;) that concrete classes inherit. The ABC approach enables property-test equivalence proofs against the existing transition matrix, and frozen dataclass semantics guarantee immutability and value equality.&lt;/p&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;Each of the 9 lane states owns its &lt;code dir=&quot;auto&quot;&gt;allowed_targets()&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;can_transition_to()&lt;/code&gt;, guards, &lt;code dir=&quot;auto&quot;&gt;progress_bucket()&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;display_category()&lt;/code&gt; — no more procedural dispatch&lt;/li&gt;
&lt;li&gt;Property tests prove 100% equivalence with &lt;code dir=&quot;auto&quot;&gt;ALLOWED_TRANSITIONS&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;_run_guard()&lt;/code&gt; — no behavioral drift&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; promoted from alias to first-class lane with &lt;code dir=&quot;auto&quot;&gt;InReviewState&lt;/code&gt;, resolving the concurrency blind spot for parallel review workflows&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;TransitionContext&lt;/code&gt; frozen dataclass replaces the 8-argument kwargs bag in guard evaluation&lt;/li&gt;
&lt;li&gt;Old API preserved via Strangler Fig: &lt;code dir=&quot;auto&quot;&gt;validate_transition()&lt;/code&gt; continues to work for non-migrated consumers (WP06 handles migration)&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Adds 9 small classes + 1 ABC + 1 dataclass — moderate code surface increase&lt;/li&gt;
&lt;li&gt;Two parallel representations of transition logic exist during migration (Strangler Fig period) — resolved when WP06 migrates consumers&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;ReviewResult&lt;/code&gt; introduces a new type that existing event-log readers do not yet produce — forward-compatible but requires WP06 for full integration&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;doing&lt;/code&gt; alias continues to resolve at the &lt;code dir=&quot;auto&quot;&gt;wp_state_for()&lt;/code&gt; boundary — no &lt;code dir=&quot;auto&quot;&gt;DoingState&lt;/code&gt; class exists&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;adr-template.md&lt;/code&gt; in root &lt;code dir=&quot;auto&quot;&gt;architecture/&lt;/code&gt; is the template reference; this ADR follows the &lt;code dir=&quot;auto&quot;&gt;2.x/adr/&lt;/code&gt; naming convention&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Property tests (T025, T026) prove equivalence with existing &lt;code dir=&quot;auto&quot;&gt;ALLOWED_TRANSITIONS&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;_run_guard()&lt;/code&gt; for all 9 lanes&lt;/li&gt;
&lt;li&gt;Full test suite passes with zero regressions (8632 baseline tests)&lt;/li&gt;
&lt;li&gt;Type checks (&lt;code dir=&quot;auto&quot;&gt;mypy&lt;/code&gt;) pass with the new types&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;WPState&lt;/code&gt; instantiation benchmarks &amp;#x3C; 1 ms&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;option-1-abc--frozen-dataclass-state-pattern&quot;&gt;Option 1: ABC + frozen dataclass (State Pattern)&lt;/h3&gt;
&lt;p&gt;Concrete &lt;code dir=&quot;auto&quot;&gt;WPState&lt;/code&gt; subclasses (one per lane) inherit from a frozen ABC dataclass. Each class implements &lt;code dir=&quot;auto&quot;&gt;allowed_targets()&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;can_transition_to()&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;progress_bucket()&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;display_category()&lt;/code&gt;. A shared &lt;code dir=&quot;auto&quot;&gt;transition()&lt;/code&gt; method in the ABC delegates to &lt;code dir=&quot;auto&quot;&gt;can_transition_to()&lt;/code&gt; and the &lt;code dir=&quot;auto&quot;&gt;wp_state_for()&lt;/code&gt; factory.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Shared default behavior (&lt;code dir=&quot;auto&quot;&gt;transition()&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;is_terminal=False&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;is_blocked=False&lt;/code&gt;) without repetition&lt;/li&gt;
&lt;li&gt;Exhaustive pattern: adding a lane without a concrete class is a &lt;code dir=&quot;auto&quot;&gt;ValueError&lt;/code&gt; at the factory&lt;/li&gt;
&lt;li&gt;Frozen dataclass gives value-object semantics for free&lt;/li&gt;
&lt;li&gt;Guards live on the state that owns them — Open/Closed Principle&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;9 classes is moderate boilerplate (mitigated by each being &amp;#x3C; 30 lines)&lt;/li&gt;
&lt;li&gt;ABC cannot enforce that subclasses are also &lt;code dir=&quot;auto&quot;&gt;@dataclass(frozen=True)&lt;/code&gt; at the type level&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2-protocol-based-structural-typing&quot;&gt;Option 2: Protocol-based structural typing&lt;/h3&gt;
&lt;p&gt;Define a &lt;code dir=&quot;auto&quot;&gt;WPState&lt;/code&gt; Protocol; each lane implements it independently.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No inheritance hierarchy — fully structural&lt;/li&gt;
&lt;li&gt;Compatible with any class shape&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 shared default implementations — &lt;code dir=&quot;auto&quot;&gt;transition()&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;is_terminal&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;is_blocked&lt;/code&gt; must be repeated in every class&lt;/li&gt;
&lt;li&gt;Cannot provide a base &lt;code dir=&quot;auto&quot;&gt;transition()&lt;/code&gt; that delegates to &lt;code dir=&quot;auto&quot;&gt;can_transition_to()&lt;/code&gt; — each class must implement the full contract independently&lt;/li&gt;
&lt;li&gt;Duck typing makes exhaustiveness harder to verify statically&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-3-extend-lanestrenum-with-methods&quot;&gt;Option 3: Extend &lt;code dir=&quot;auto&quot;&gt;Lane(StrEnum)&lt;/code&gt; with methods&lt;/h3&gt;
&lt;p&gt;Add &lt;code dir=&quot;auto&quot;&gt;allowed_targets()&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;is_terminal&lt;/code&gt;, etc. directly as methods on the &lt;code dir=&quot;auto&quot;&gt;Lane&lt;/code&gt; enum.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No new classes — reuses the existing enum&lt;/li&gt;
&lt;li&gt;Single place for lane identity + behavior&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;Violates SRP: &lt;code dir=&quot;auto&quot;&gt;Lane&lt;/code&gt; is an identity type; adding transition logic, guard evaluation, and display metadata turns it into a God Object&lt;/li&gt;
&lt;li&gt;Enum methods cannot have per-member state or complex guard logic without becoming a giant switch statement — the same scatter problem in a different shape&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;TransitionContext&lt;/code&gt; would still be needed but would not benefit from polymorphic dispatch&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-4-dictionary-of-functions-dispatch-table&quot;&gt;Option 4: Dictionary-of-functions dispatch table&lt;/h3&gt;
&lt;p&gt;Replace &lt;code dir=&quot;auto&quot;&gt;_run_guard()&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;GUARDS: dict[tuple[str, str], Callable]&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Minimal structural change — same flat approach, slightly more organized&lt;/li&gt;
&lt;li&gt;Easy to add new guards&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;Does not colocate allowed targets, terminal/blocked classification, or display metadata with the lane&lt;/li&gt;
&lt;li&gt;Same scatter problem with different syntax — behavior is still separated from identity&lt;/li&gt;
&lt;li&gt;No type-safe exhaustiveness guarantee&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; promotion rationale&lt;/strong&gt;: The former &lt;code dir=&quot;auto&quot;&gt;LANE_ALIASES[&quot;in_review&quot;] = &quot;for_review&quot;&lt;/code&gt; mapping collapsed two distinct workflow states into one. In parallel execution, &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; should mean “queued for review” (no reviewer has claimed it) while &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; means “review actively in progress by a specific reviewer.” This is directly analogous to the &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; progression for implementation. The &lt;code dir=&quot;auto&quot;&gt;(for_review, in_review)&lt;/code&gt; transition carries an actor-required guard with conflict detection, preventing two reviewers from simultaneously claiming the same WP. This supersedes the approach in &lt;code dir=&quot;auto&quot;&gt;2026-04-03-2-review-approval-and-integration-completion-are-distinct.md&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Transition changes&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; outbound is narrowed to &lt;code dir=&quot;auto&quot;&gt;{in_review, blocked, canceled}&lt;/code&gt;. The former &lt;code dir=&quot;auto&quot;&gt;for_review → {approved, done, in_progress, planned}&lt;/code&gt; transitions move to &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; as the source. All outbound transitions from &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; require a &lt;code dir=&quot;auto&quot;&gt;ReviewResult&lt;/code&gt; in the &lt;code dir=&quot;auto&quot;&gt;TransitionContext&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Related mission artifacts&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;data-model.md&lt;/code&gt; (WPState/TransitionContext design), &lt;code dir=&quot;auto&quot;&gt;research.md&lt;/code&gt; Finding 3 (Lane Logic Scatter), &lt;code dir=&quot;auto&quot;&gt;plan.md&lt;/code&gt; WP05 section.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
