<?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-05-01-1-atomic-work-package-start-lifecycle/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-05-01-1-atomic-work-package-start-lifecycle/</id>
  <title>Atomic Work Package Start Lifecycle</title>
  <updated>2026-05-01T00: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-05-01-1-atomic-work-package-start-lifecycle/"/>
  <summary>Implementation start emits planned, claimed, and in_progress as one atomic event batch, so a crash mid-sequence can no longer strand a work package in claimed.</summary>
  <content type="html">&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-02-09-1-canonical-wp-status-model.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-02-09-3-event-log-merge-semantics.md&lt;/code&gt;&lt;/li&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;&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Implementation start is a semantic operation, not just a raw lane edge. Starting
work from &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt; requires two canonical events:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;planned -&gt; claimed&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;claimed -&gt; in_progress&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Before this ADR, callers emitted those transitions independently. That left
three architectural gaps:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;A crash or exception between the two writes could strand a WP in &lt;code dir=&quot;auto&quot;&gt;claimed&lt;/code&gt;
even though implementation had logically started.&lt;/li&gt;
&lt;li&gt;Retry behavior varied by surface: direct CLI, agent workflow, and
orchestrator API could disagree on whether same-agent retries were safe or
conflicting.&lt;/li&gt;
&lt;li&gt;Presentation treated &lt;code dir=&quot;auto&quot;&gt;claimed&lt;/code&gt; as passive backlog in some views even though
it is an active ownership state.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Spec Kitty supports 15 coding-agent hosts plus orchestration/API surfaces.
Lifecycle correctness therefore cannot live in a host-specific command wrapper
or in a one-off patch for one agent. All surfaces that begin implementation or
review must apply the same ownership, idempotency, and event-persistence
semantics.&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;Agent-surface parity&lt;/strong&gt; — Claude, Codex, OpenCode, Cursor, and all other
supported coding agents must observe the same lifecycle behavior.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Crash consistency&lt;/strong&gt; — a logical lifecycle start must not leave a half-started
event log.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Idempotent retry&lt;/strong&gt; — a same-actor retry after dispatch or process restart
should resume; a different actor should see a conflict.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Event-log authority&lt;/strong&gt; — preserve the append-only status log and the 9-lane
state machine rather than inventing a bypass.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Visible ownership&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;claimed&lt;/code&gt; is active work ownership and must be rendered
with Doing/progress, not hidden in Planned backlog.&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 raw transition calls at every caller and document retry rules.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; Special-case the failing agent workflow path only.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; Collapse implementation start into a single &lt;code dir=&quot;auto&quot;&gt;planned -&gt; in_progress&lt;/code&gt;
transition.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 4:&lt;/strong&gt; Move claim ownership to an external lock/control-plane service.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 5:&lt;/strong&gt; Add a shared lifecycle service backed by atomic event batches.&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 5: shared lifecycle service backed by atomic event
batches”, because it preserves the canonical event model while making lifecycle
starts all-or-none and host-independent.&lt;/p&gt;
&lt;h3 id=&quot;implementation-policy&quot;&gt;Implementation Policy&lt;/h3&gt;
&lt;p&gt;All implementation-start surfaces call a shared lifecycle operation instead of
hand-emitting start transitions:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;text&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;start_implementation_status(...)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;All review-start surfaces call:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;text&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;start_review_status(...)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;The lifecycle service owns these rules:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt; implementation start writes &lt;code dir=&quot;auto&quot;&gt;planned -&gt; claimed -&gt; in_progress&lt;/code&gt; as
one atomic event batch and materializes once.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;claimed&lt;/code&gt; by the same actor resumes to &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;claimed&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt; by a different actor raises a claim conflict.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt; by the same actor is a no-op.&lt;/li&gt;
&lt;li&gt;Review start mirrors the same pattern for &lt;code dir=&quot;auto&quot;&gt;for_review -&gt; in_review&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Raw status emit remains available for explicit low-level transitions, but
caller surfaces must not reimplement lifecycle-start policy.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Atomic batch persistence appends the full batch to a temporary JSONL file and
then replaces the canonical event log. Reducer ordering is preserved by assigning
deterministically increasing timestamps inside the batch.&lt;/p&gt;
&lt;h3 id=&quot;supersession-analysis&quot;&gt;Supersession Analysis&lt;/h3&gt;
&lt;p&gt;This ADR does &lt;strong&gt;not&lt;/strong&gt; supersede the existing status ADRs:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-02-09-1&lt;/code&gt; remains authoritative for the append-only JSONL event log and
derived &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; snapshot.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-02-09-3&lt;/code&gt; remains authoritative for merge-time concatenate, dedupe, sort,
and reduce semantics. This ADR acts earlier, at write time, by making a single
process’s logical start operation atomic before git merge semantics apply.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;2026-04-06-1&lt;/code&gt; remains authoritative for the 9-lane state model and lane-owned
behavior. This ADR clarifies which service owns multi-edge lifecycle commands
that are built from those lane transitions.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The new rule is additive: &lt;strong&gt;semantic lifecycle starts are service-owned; raw
transition validation remains state-machine-owned.&lt;/strong&gt;&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;Same-agent retries become safe across CLI, workflow, and orchestrator API.&lt;/li&gt;
&lt;li&gt;Different-agent overlap is detected consistently instead of depending on the
entry point.&lt;/li&gt;
&lt;li&gt;Crash windows no longer expose &lt;code dir=&quot;auto&quot;&gt;planned -&gt; claimed&lt;/code&gt; without the paired
&lt;code dir=&quot;auto&quot;&gt;claimed -&gt; in_progress&lt;/code&gt; event for new implementation starts.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;claimed&lt;/code&gt; work is visible as active Doing work, while still preserving the
separate canonical lane for stale-claim diagnostics and audit.&lt;/li&gt;
&lt;li&gt;The design remains offline-first and git-native.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Start lifecycle behavior now has a dedicated service layer that callers must
use correctly.&lt;/li&gt;
&lt;li&gt;Atomic batch writes rewrite the JSONL file through a temp file, which is more
code than simple append.&lt;/li&gt;
&lt;li&gt;Diff coverage and tests must cover both single-event emit and batch-event emit
paths.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The canonical event sequence remains two events; historical logs and reducers
do not need migration.&lt;/li&gt;
&lt;li&gt;The low-level status command can still emit individual legal transitions for
repair, migration, and operator workflows.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;claimed&lt;/code&gt; remains distinct from &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt;; the display change only affects
progress grouping.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;This decision is valid when:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;all implementation and review start entry points use the shared lifecycle
service;&lt;/li&gt;
&lt;li&gt;same-actor retries are idempotent and different-actor retries conflict;&lt;/li&gt;
&lt;li&gt;a planned implementation start persists both events or neither event;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;claimed&lt;/code&gt; appears with active Doing work in dashboards/boards while stale
claim diagnostics still see the canonical lane;&lt;/li&gt;
&lt;li&gt;CI covers batch persistence, lifecycle conflict/no-op paths, dashboard lane
grouping, and orchestrator API parity.&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-raw-transition-calls-at-every-caller&quot;&gt;Option 1: Keep raw transition calls at every caller&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Minimal code movement.&lt;/li&gt;
&lt;li&gt;Preserves every caller’s current structure.&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;Keeps lifecycle policy duplicated across host surfaces.&lt;/li&gt;
&lt;li&gt;Leaves retry and conflict semantics dependent on caller ordering.&lt;/li&gt;
&lt;li&gt;Does not close the crash window between start events.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2-special-case-the-failing-agent-workflow-path-only&quot;&gt;Option 2: Special-case the failing agent workflow path only&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Fastest targeted fix for Issue #944.&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 agent-surface parity.&lt;/li&gt;
&lt;li&gt;Leaves orchestrator API and direct CLI with divergent behavior.&lt;/li&gt;
&lt;li&gt;Creates a pattern for host-specific lifecycle exceptions.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-3-collapse-implementation-start-into-one-transition&quot;&gt;Option 3: Collapse implementation start into one transition&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Removes the multi-event crash window.&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;Destroys the audit distinction between claim and active implementation.&lt;/li&gt;
&lt;li&gt;Conflicts with the canonical 9-lane state machine.&lt;/li&gt;
&lt;li&gt;Breaks stale-claim diagnostics and existing event history semantics.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-4-external-lockcontrol-plane-service&quot;&gt;Option 4: External lock/control-plane service&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Could provide real-time distributed locking across machines.&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 offline-first status authority.&lt;/li&gt;
&lt;li&gt;Makes local CLI correctness depend on network/service availability.&lt;/li&gt;
&lt;li&gt;Duplicates ownership state outside the canonical event log.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-5-shared-lifecycle-service-backed-by-atomic-event-batches&quot;&gt;Option 5: Shared lifecycle service backed by atomic event batches&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Keeps event sourcing and the 9-lane model intact.&lt;/li&gt;
&lt;li&gt;Centralizes lifecycle-start policy for all supported agents and APIs.&lt;/li&gt;
&lt;li&gt;Provides crash consistency for composite start operations.&lt;/li&gt;
&lt;li&gt;Keeps ownership visible and auditable.&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;Adds a service abstraction between callers and raw status emit.&lt;/li&gt;
&lt;li&gt;Requires callers to distinguish semantic lifecycle operations from low-level
repair transitions.&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;Issue: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/944&quot;&gt;#944&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Implementation PR: &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/pull/946&quot;&gt;#946&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Canonical status model: &lt;code dir=&quot;auto&quot;&gt;2026-02-09-1-canonical-wp-status-model.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Event-log merge semantics: &lt;code dir=&quot;auto&quot;&gt;2026-02-09-3-event-log-merge-semantics.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Current lane model: &lt;code dir=&quot;auto&quot;&gt;2026-04-06-1-wp-state-pattern-for-lane-behavior.md&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
