<?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-06-07-3-wp-lane-fsm-genesis-and-finalize-clobber/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-06-07-3-wp-lane-fsm-genesis-and-finalize-clobber/</id>
  <title>ADR: WP Lane Finite State Machine, the `genesis` lane, and the finalize event-log clobber fix</title>
  <updated>2026-06-07T00: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-06-07-3-wp-lane-fsm-genesis-and-finalize-clobber/"/>
  <summary>Adds a non-display `genesis` lane so seeding a work package becomes a real persisted edge, and stops finalize-tasks overwriting the canonical event log with a stale copy.</summary>
  <content type="html">&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;A newly created coordination-topology mission could not start its implement loop:
&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent action implement WP01&lt;/code&gt; failed with &lt;em&gt;“WP WP01 has no canonical
status”&lt;/em&gt; even though &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; printed &lt;em&gt;“13 WPs seeded”&lt;/em&gt;. This reproduced
the &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/1589&quot;&gt;#1589&lt;/a&gt; “status
split-brain”: &lt;code dir=&quot;auto&quot;&gt;tasks status&lt;/code&gt; showed 13 planned, &lt;code dir=&quot;auto&quot;&gt;materialize&lt;/code&gt; showed &lt;code dir=&quot;auto&quot;&gt;0 events -&gt; 0 WPs&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;emit … --to planned&lt;/code&gt; was rejected as &lt;code dir=&quot;auto&quot;&gt;planned -&gt; planned&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;Live probing isolated &lt;strong&gt;two independent defects&lt;/strong&gt;, both rooted in
under-encapsulation of the WP lane state model:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Finalize clobbers the canonical event log.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;bootstrap_canonical_state&lt;/code&gt;
correctly seeds lane-state events through the transactional emitter into the
coordination worktree. But &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; then &lt;code dir=&quot;auto&quot;&gt;shutil.copy2&lt;/code&gt;’d the
&lt;em&gt;primary checkout’s&lt;/em&gt; stale &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; (lifecycle
events only, no lane state) &lt;strong&gt;over&lt;/strong&gt; the coord worktree’s canonical copies
before committing — wiping the just-seeded lane state. (Proven: a direct
&lt;code dir=&quot;auto&quot;&gt;emit&lt;/code&gt; persisted &lt;code dir=&quot;auto&quot;&gt;WP01=claimed&lt;/code&gt;; running &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; reset it to &lt;code dir=&quot;auto&quot;&gt;[]&lt;/code&gt;.)&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;genesis&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt; conflation makes the seed an implicit no-op.&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;_derive_from_lane&lt;/code&gt; returned &lt;code dir=&quot;auto&quot;&gt;Lane.PLANNED&lt;/code&gt; for a work package with no
lane-state events. So the bootstrap “seed” was a &lt;code dir=&quot;auto&quot;&gt;planned -&gt; planned&lt;/code&gt;
self-transition — semantically a no-op, and indistinguishable from a real
planned WP. The &lt;em&gt;write&lt;/em&gt; layer treated “uninitialized” as &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt; (lenient);
the &lt;em&gt;read&lt;/em&gt; layer (&lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;materialize&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;doctor&lt;/code&gt;) demanded an explicit
event (strict). Two readers, two truths.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The deeper smell: the lane model had &lt;strong&gt;two parallel sources of transition
truth&lt;/strong&gt; — the State-pattern classes in &lt;code dir=&quot;auto&quot;&gt;status/wp_state.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;allowed_targets()&lt;/code&gt;)
and a hand-maintained flat &lt;code dir=&quot;auto&quot;&gt;ALLOWED_TRANSITIONS&lt;/code&gt; frozenset in
&lt;code dir=&quot;auto&quot;&gt;status/transitions.py&lt;/code&gt;, kept in lockstep only by an equivalence test. Each
prior incident was patched class-by-class (“whack-a-class”). The operator
directed a proper fix now rather than another patch.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;h3 id=&quot;1-introduce-lanegenesis-as-an-explicit-non-display-pre-finalize-lane&quot;&gt;1. Introduce &lt;code dir=&quot;auto&quot;&gt;Lane.GENESIS&lt;/code&gt; as an explicit, non-display pre-finalize lane&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;genesis&lt;/code&gt; is the state of a WP that has been &lt;em&gt;created&lt;/em&gt; (&lt;code dir=&quot;auto&quot;&gt;WPCreated&lt;/code&gt;) but not yet
seeded into the lane lifecycle. &lt;code dir=&quot;auto&quot;&gt;_derive_from_lane&lt;/code&gt; now returns &lt;code dir=&quot;auto&quot;&gt;GENESIS&lt;/code&gt; (not
&lt;code dir=&quot;auto&quot;&gt;PLANNED&lt;/code&gt;) for a WP with no lane-state events. The bootstrap seed becomes an
&lt;strong&gt;explicit &lt;code dir=&quot;auto&quot;&gt;genesis -&gt; planned&lt;/code&gt; transition&lt;/strong&gt; — a real, persisted edge, not a
dropped self-transition. Read and write layers now agree: an unfinalized WP is
&lt;code dir=&quot;auto&quot;&gt;genesis&lt;/code&gt;; a finalized one is &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;genesis&lt;/code&gt; is &lt;strong&gt;non-display&lt;/strong&gt;: it is deliberately &lt;em&gt;not&lt;/em&gt; in &lt;code dir=&quot;auto&quot;&gt;CANONICAL_LANES&lt;/code&gt;, has
no kanban column, no board-summary key, and weight &lt;code dir=&quot;auto&quot;&gt;0.0&lt;/code&gt;. A &lt;code dir=&quot;auto&quot;&gt;genesis&lt;/code&gt; WP has no
lane events and so never materializes into a snapshot (once seeded it is
&lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt;); the lane exists only as the seed’s &lt;code dir=&quot;auto&quot;&gt;from_lane&lt;/code&gt; and as the
&lt;code dir=&quot;auto&quot;&gt;_derive_from_lane&lt;/code&gt; result for unseeded WPs. It is accepted by event validation
as a valid &lt;code dir=&quot;auto&quot;&gt;from_lane&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Consequent behavioural change (intended):&lt;/strong&gt; a WP can no longer be transitioned
straight to &lt;code dir=&quot;auto&quot;&gt;claimed&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt; from nothing — it must first be seeded
&lt;code dir=&quot;auto&quot;&gt;genesis -&gt; planned&lt;/code&gt; (which &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; does). This is strictly more correct
(you cannot claim an unfinalized WP) and is the explicit contract the operator
requested.&lt;/p&gt;
&lt;h3 id=&quot;2-the-wp-lane-state-machine-is-the-single-source-of-transition-truth&quot;&gt;2. The WP lane State machine is the single source of transition truth&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;status/wp_state.py&lt;/code&gt; (the State pattern, per
&lt;a href=&quot;https://refactoring.guru/design-patterns/state&quot;&gt;refactoring.guru/design-patterns/state&lt;/a&gt;)
is now the &lt;strong&gt;authority&lt;/strong&gt; for structural transitions. &lt;code dir=&quot;auto&quot;&gt;ALLOWED_TRANSITIONS&lt;/code&gt; in
&lt;code dir=&quot;auto&quot;&gt;status/transitions.py&lt;/code&gt; is &lt;strong&gt;derived&lt;/strong&gt; from the state objects’ &lt;code dir=&quot;auto&quot;&gt;allowed_targets()&lt;/code&gt;
rather than hand-maintained, eliminating the dual-source drift the equivalence
test previously papered over. Rich mission guards (actor, subtasks-complete,
review result, done evidence, force) remain layered on top by
&lt;code dir=&quot;auto&quot;&gt;validate_transition&lt;/code&gt; via &lt;code dir=&quot;auto&quot;&gt;_GUARDED_TRANSITIONS&lt;/code&gt; — guard evaluation is a separate
concern from edge existence.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;GenesisState&lt;/code&gt; is a first-class state (&lt;code dir=&quot;auto&quot;&gt;allowed_targets = {planned, canceled}&lt;/code&gt;).&lt;/p&gt;
&lt;h3 id=&quot;3-the-fsm-exposes-a-canonical-encapsulated-interface&quot;&gt;3. The FSM exposes a canonical, encapsulated interface&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;WPState&lt;/code&gt; gains the operator-specified Finite-State-Machine vocabulary:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;current_lane -&gt; Lane&lt;/code&gt; — the lane this state represents.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;may_transition_to(target: Lane) -&gt; bool&lt;/code&gt; — guard-free structural edge check.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;transition_to(target, ctx) -&gt; WPState&lt;/code&gt; — guarded transition (raises
&lt;code dir=&quot;auto&quot;&gt;InvalidTransitionError&lt;/code&gt; on a missing edge or rejected guard).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;(&lt;code dir=&quot;auto&quot;&gt;lane&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;can_transition_to&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;transition&lt;/code&gt; are retained as the underlying
mechanics so existing callers are unaffected — this is a behaviour-preserving
refactor for the nine pre-existing lanes.)&lt;/p&gt;
&lt;h3 id=&quot;4-finalize-must-not-overwrite-the-coordination-event-log&quot;&gt;4. Finalize must not overwrite the coordination event log&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; no longer copies &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; from the
primary checkout into the coordination worktree. The canonical event log is
owned by the transactional emitter on the coordination branch; finalize commits
only the other planning artifacts (&lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;acceptance-matrix.json&lt;/code&gt;, …). The copy logic is extracted into the testable
&lt;code dir=&quot;auto&quot;&gt;_stage_finalize_artifacts_in_coord_worktree&lt;/code&gt; helper, which skips
&lt;code dir=&quot;auto&quot;&gt;_COORD_OWNED_STATUS_FILES&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Positive:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;#1589&lt;/code&gt; is fixed at the root; the implement loop can start.
The lane model has one transition authority (no drift). The FSM is explicitly
testable. &lt;code dir=&quot;auto&quot;&gt;genesis&lt;/code&gt; makes “unfinalized” a first-class, observable state rather
than an implicit default that silently masquerades as &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Cost:&lt;/strong&gt; one extra &lt;code dir=&quot;auto&quot;&gt;Lane&lt;/code&gt; enum member (10 total; 9 active/display + genesis)
and &lt;code dir=&quot;auto&quot;&gt;~2&lt;/code&gt; derived transition edges. Tests that emitted transitions on an
unseeded WP now seed &lt;code dir=&quot;auto&quot;&gt;genesis -&gt; planned&lt;/code&gt; first (a &lt;code dir=&quot;auto&quot;&gt;_seed_planned&lt;/code&gt; helper); this
is a one-line setup addition that makes the previously-implicit step explicit.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Trade-off accepted (operator):&lt;/strong&gt; slightly more model surface in exchange for
conceptual clarity, testability, and the elimination of the whack-a-class
failure mode.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Non-goals:&lt;/strong&gt; display/kanban changes (genesis is non-display by design).&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Revision (DM-01KTH03G, post-initial-draft):&lt;/strong&gt; guard unification was
originally listed as a non-goal, but the accepted decision moved guards and
force handling &lt;strong&gt;into&lt;/strong&gt; the &lt;code dir=&quot;auto&quot;&gt;WPState&lt;/code&gt; objects (&lt;code dir=&quot;auto&quot;&gt;guard_for&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;check_transition&lt;/code&gt;);
&lt;code dir=&quot;auto&quot;&gt;validate_transition&lt;/code&gt; is now a thin delegator and &lt;code dir=&quot;auto&quot;&gt;_GUARDED_TRANSITIONS&lt;/code&gt; is gone.
See &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/status/wp_state.py&lt;/code&gt;.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;verification&quot;&gt;Verification&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;tests/status/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/status/&lt;/code&gt;, and all touched cross-cutting test
files (coordination, sync, dashboard, lanes, integration, upgrade) are green;
&lt;code dir=&quot;auto&quot;&gt;ruff&lt;/code&gt; clean and &lt;code dir=&quot;auto&quot;&gt;mypy&lt;/code&gt; neutral (no new errors) on all changed production files.
A dedicated regression test (&lt;code dir=&quot;auto&quot;&gt;test_finalize_coord_staging.py&lt;/code&gt;) pins that finalize
preserves the seeded coordination event log.&lt;/p&gt;</content>
</entry>
