<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/architecture/status-model/">
  <id>https://docs.spec-kitty.ai/architecture/status-model/</id>
  <title>Status Model: Operator Documentation</title>
  <updated>2026-11-01T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/architecture/status-model/"/>
  <summary>Operator reference for the Spec Kitty status model: the append-only event-log lane state machine, the canonical --mission selector, and mission_id ULID identity.</summary>
  <content type="html">&lt;span id=&quot;status-model-operator-documentation&quot;&gt;&lt;/span&gt;
&lt;p&gt;&lt;strong&gt;Mission of record&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;034-feature-status-state-model-remediation&lt;/code&gt; (legacy slug)&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Terminology note&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Domain model: &lt;code dir=&quot;auto&quot;&gt;Mission Type -&gt; Mission -&gt; Mission Run&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;--mission&lt;/code&gt; is the only tracked-mission selector. The old &lt;code dir=&quot;auto&quot;&gt;--feature&lt;/code&gt; alias has been
removed from every user-facing command (#1060, the selector hard-removal); passing
&lt;code dir=&quot;auto&quot;&gt;--feature&lt;/code&gt; exits with code 2.&lt;/li&gt;
&lt;li&gt;A mission’s canonical machine identity is &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; (a ULID, since mission
&lt;code dir=&quot;auto&quot;&gt;083-mission-id-canonical-identity-migration&lt;/code&gt;). The &lt;code dir=&quot;auto&quot;&gt;--mission&lt;/code&gt; flag accepts &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;mid8&lt;/code&gt; (first 8 chars of the ULID), or &lt;code dir=&quot;auto&quot;&gt;mission_slug&lt;/code&gt;. The numeric prefix in slug examples below (e.g. &lt;code dir=&quot;auto&quot;&gt;034-feature-name&lt;/code&gt;) is display-only metadata — the event log’s aggregate key is &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt;, not the prefix. See the &lt;a href=&quot;/migrations/mission-id-canonical-identity/&quot;&gt;mission identity migration runbook&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;overview&quot;&gt;Overview&lt;/h2&gt;
&lt;p&gt;The status model uses a single canonical append-only event log per mission as the sole authority for work package status. Every lane transition is an immutable &lt;code dir=&quot;auto&quot;&gt;StatusEvent&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;. A deterministic reducer produces &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; snapshots.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Which reducer runs?&lt;/strong&gt; One: the wall-clock &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.diary.reduce_parsed&lt;/code&gt;, reached through &lt;code dir=&quot;auto&quot;&gt;status.reducer.reduce&lt;/code&gt; and through &lt;code dir=&quot;auto&quot;&gt;materialize_snapshot&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;materialize&lt;/code&gt;. It is deterministic but not Lamport-ordered; see &lt;a href=&quot;#known-limitations&quot;&gt;Known limitations&lt;/a&gt;. Every other event log core writes and reads is mapped in &lt;a href=&quot;/architecture/event-ledger-writers-and-readers/&quot;&gt;Event ledger writers and readers&lt;/a&gt;.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;This event log is the open-core producer’s read model (2026-10-12 direction).&lt;/strong&gt; The
&lt;strong&gt;Mission Status Read API&lt;/strong&gt; — the open-core &lt;strong&gt;producer&lt;/strong&gt; surface (ADR
&lt;a href=&quot;/adr/4.x/2026-10-01-2-mission-status-read-api-and-dashboard-extraction/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-10-01-2&lt;/code&gt;&lt;/a&gt;,
Accepted) — is conformance-gated against &lt;code dir=&quot;auto&quot;&gt;status.reducer.materialize_snapshot&lt;/code&gt;, the same
wall-clock reducer every CLI reader uses, so its answer is meant to match &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt;.
Its Java port does not yet carry the #4941 approved-departure lift (#6268). Its Java service and the
&lt;code dir=&quot;auto&quot;&gt;mission-status&lt;/code&gt; contract live in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;service/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;contracts/&lt;/code&gt;, ADR
&lt;a href=&quot;/adr/4.x/2026-10-29-1-the-events-domain-and-its-java-services-live-in-spec-kitty-events/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-10-29-1&lt;/code&gt;&lt;/a&gt;);
core pins a release (&lt;code dir=&quot;auto&quot;&gt;pins/read-service.source.yaml&lt;/code&gt;) and checks this Python reducer against its
bundled contract and conformance fixtures. Consumers (Team Kitty /
“Multiplayer Mode”) read that API across its contract, never this log directly.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;&lt;strong&gt;Key principles&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; is the &lt;strong&gt;sole source of truth&lt;/strong&gt; for WP lane state&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; is a &lt;strong&gt;derived&lt;/strong&gt; materialized snapshot (regenerable)&lt;/li&gt;
&lt;li&gt;WP frontmatter is for &lt;strong&gt;static definition only&lt;/strong&gt; (title, dependencies, subtasks) — the &lt;code dir=&quot;auto&quot;&gt;lane&lt;/code&gt; field is no longer written or read by active runtime code&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; is the &lt;strong&gt;canonical bootstrap point&lt;/strong&gt; — it creates initial WP definitions; status transitions are tracked exclusively in the event log&lt;/li&gt;
&lt;li&gt;Frontmatter &lt;code dir=&quot;auto&quot;&gt;lane&lt;/code&gt; is a &lt;strong&gt;historical/migration-only&lt;/strong&gt; concept retained in migration code paths for backward compatibility&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Read-only commands stay read-only&lt;/strong&gt;: status commands (including &lt;code dir=&quot;auto&quot;&gt;materialize()&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent status materialize&lt;/code&gt;) no longer dirty the git working tree. &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; is only written when there is a new event to materialize. The &lt;code dir=&quot;auto&quot;&gt;materialized_at&lt;/code&gt; field in &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; reflects the timestamp of the last event in the log, not the wall clock at the time the command was run.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Forward-looking (Proposed):&lt;/strong&gt; the “frontmatter is static-only” principle above
is only half-delivered today — &lt;code dir=&quot;auto&quot;&gt;lane&lt;/code&gt; was evicted, but &lt;code dir=&quot;auto&quot;&gt;shell_pid&lt;/code&gt;,
subtask-checkbox state, review-cycle fields, &lt;code dir=&quot;auto&quot;&gt;agent&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;assignee&lt;/code&gt;, and the
activity-log narrative are still written into &lt;code dir=&quot;auto&quot;&gt;tasks/WP##.md&lt;/code&gt; at runtime. The
WP runtime-state eviction mission generalises the &lt;code dir=&quot;auto&quot;&gt;lane&lt;/code&gt; retirement to &lt;strong&gt;all&lt;/strong&gt;
of these, introducing a &lt;strong&gt;non-transition annotation event class&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;shell_refresh&lt;/code&gt;
/ &lt;code dir=&quot;auto&quot;&gt;subtask_marked&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;activity_note&lt;/code&gt;) alongside the transition ledger so the
9-lane FSM stays unchanged. After it lands, &lt;code dir=&quot;auto&quot;&gt;WP##.md&lt;/code&gt; holds only static intent
and hashes stably across every runtime mutation. See
&lt;a href=&quot;/adr/3.x/2026-07-16-1-wp-runtime-state-authority-event-log-eviction/&quot;&gt;ADR 2026-07-16-1&lt;/a&gt;
and the &lt;a href=&quot;/architecture/wp-runtime-state-eviction/&quot;&gt;eviction design&lt;/a&gt;.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2 id=&quot;known-limitations&quot;&gt;Known limitations&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;One reducer, ordered by wall clock.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;status.reducer.reduce&lt;/code&gt; calls
&lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.diary.reduce_parsed&lt;/code&gt; directly (&lt;code dir=&quot;auto&quot;&gt;status/reducer.py:205&lt;/code&gt;), and
&lt;code dir=&quot;auto&quot;&gt;materialize_snapshot&lt;/code&gt; calls &lt;code dir=&quot;auto&quot;&gt;reduce_shared_state&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;:401&lt;/code&gt;), which is
&lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.status.reduce&lt;/code&gt;, a re-export of &lt;code dir=&quot;auto&quot;&gt;diary.reduce&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;parse_diary&lt;/code&gt;, then
&lt;code dir=&quot;auto&quot;&gt;reduce_parsed&lt;/code&gt;). Lane transitions are ordered by the writer’s &lt;code dir=&quot;auto&quot;&gt;at&lt;/code&gt;, then &lt;code dir=&quot;auto&quot;&gt;event_id&lt;/code&gt;;
CLI lane rows carry no Lamport clock, and the Lamport reducer
&lt;code dir=&quot;auto&quot;&gt;reduce_status_events&lt;/code&gt; is not on the CLI path. So the CLI does not implement the
Lamport-primary order of ADR
&lt;a href=&quot;/adr/2.x/2026-02-09-3-event-log-merge-semantics/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-02-09-3&lt;/code&gt;&lt;/a&gt;. The consolidation
reconciliation gate reads through the same reducer. Two ordering cases are fixed in
the library: a stale approval overriding a committed rejection (#4990, 10.4.0) and a
rejection minted after a clock-ahead approval (#4941, 10.5.1: a non-seed departure from
&lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; sorts after the approval it followed). A non-approval transition minted on a
clock behind the event it follows still sorts before that event.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;cli-commands&quot;&gt;CLI Commands&lt;/h2&gt;
&lt;p&gt;All status commands live under &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent status&lt;/code&gt;.&lt;/p&gt;
&lt;h3 id=&quot;spec-kitty-agent-status-emit&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent status emit&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;Record a lane transition event for a work package.&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&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:#919F9F;--1:#5F636F&quot;&gt;# Move WP01 to claimed (assigns to an actor)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;emit&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;WP01&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--to&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;claimed&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--actor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;claude&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Move WP01 to in_progress (begin implementation)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;emit&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;WP01&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--to&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;in_progress&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--actor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;claude&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# &quot;doing&quot; is accepted as an alias for &quot;in_progress&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;emit&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;WP01&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--to&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;doing&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--actor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;claude&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Move to for_review (submit for review)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;emit&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;WP01&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--to&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;for_review&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--actor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;claude&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Move to done with reviewer evidence (required unless forced)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;emit&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;WP01&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--to&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;done&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--actor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;claude&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--evidence-json&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&apos;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;{&quot;review&quot;: {&quot;reviewer&quot;: &quot;alice&quot;, &quot;verdict&quot;: &quot;approved&quot;, &quot;reference&quot;: &quot;PR#42&quot;}}&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Return from review to in_progress (changes requested -- requires review_ref)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;emit&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;WP01&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--to&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;in_progress&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--actor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;reviewer&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--review-ref&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;PR#42-comment-7&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Force a transition that bypasses guard conditions (requires actor + reason)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;emit&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;WP01&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--to&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;in_progress&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--actor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;admin&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--force&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--reason&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;Reopening after incorrectly marked done&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Block a work package&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;emit&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;WP01&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--to&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;blocked&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--actor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;claude&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--reason&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;Waiting on upstream dependency&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Machine-readable JSON output&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;emit&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;WP01&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--to&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;claimed&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--actor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;claude&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--json&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Options&lt;/strong&gt;:&lt;/p&gt;




























































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Option&lt;/th&gt;&lt;th&gt;Required&lt;/th&gt;&lt;th&gt;Description&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;WP_ID&lt;/code&gt; (argument)&lt;/td&gt;&lt;td&gt;Yes&lt;/td&gt;&lt;td&gt;work package ID (e.g., &lt;code dir=&quot;auto&quot;&gt;WP01&lt;/code&gt;)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--to&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Yes&lt;/td&gt;&lt;td&gt;Target lane (canonical or alias)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--actor&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Yes&lt;/td&gt;&lt;td&gt;Who is making this transition: a tool name (&lt;code dir=&quot;auto&quot;&gt;claude&lt;/code&gt;) or the compact &lt;code dir=&quot;auto&quot;&gt;tool:model:profile&lt;/code&gt; form. The event stores the structured actor (see &lt;a href=&quot;#the-actor&quot;&gt;The actor&lt;/a&gt;); the command output echoes the value as given&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--mission&lt;/code&gt;&lt;/td&gt;&lt;td&gt;No&lt;/td&gt;&lt;td&gt;Mission slug&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt;&lt;/td&gt;&lt;td&gt;No&lt;/td&gt;&lt;td&gt;Bypass guard conditions&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--reason&lt;/code&gt;&lt;/td&gt;&lt;td&gt;When &lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Reason for forced transition&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--evidence-json&lt;/code&gt;&lt;/td&gt;&lt;td&gt;When &lt;code dir=&quot;auto&quot;&gt;--to done&lt;/code&gt;&lt;/td&gt;&lt;td&gt;JSON string with DoneEvidence&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--review-ref&lt;/code&gt;&lt;/td&gt;&lt;td&gt;When &lt;code dir=&quot;auto&quot;&gt;for_review -&gt; in_progress&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Review feedback reference&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--execution-mode&lt;/code&gt;&lt;/td&gt;&lt;td&gt;No&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;worktree&lt;/code&gt; (default) or &lt;code dir=&quot;auto&quot;&gt;direct_repo&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt;&lt;/td&gt;&lt;td&gt;No&lt;/td&gt;&lt;td&gt;Machine-readable JSON output&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;On a coordination-routed Mission the write can be refused with
&lt;code dir=&quot;auto&quot;&gt;COORD_STATUS_SURFACE_DIVERGED&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;COORD_STATUS_SURFACE_UNREADABLE&lt;/code&gt;; see
&lt;a href=&quot;#coordination-status-write-guard&quot;&gt;Coordination status-write guard&lt;/a&gt;.&lt;/p&gt;
&lt;h3 id=&quot;spec-kitty-agent-status-materialize&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent status materialize&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;Rebuild &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; from the canonical event log.&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&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:#919F9F;--1:#5F636F&quot;&gt;# Rebuild snapshot (auto-detects mission)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;materialize&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Specify mission explicitly&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;materialize&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--mission&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;034-feature-name&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# JSON output (full snapshot)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;materialize&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--mission&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;034-feature-name&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--json&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;When to use&lt;/strong&gt;: After manual edits to &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;, after resolving merge conflicts in the event log, or after running &lt;code dir=&quot;auto&quot;&gt;status validate&lt;/code&gt; reports materialization drift.&lt;/p&gt;
&lt;h3 id=&quot;spec-kitty-agent-status-validate&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent status validate&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;Check event log integrity, transition legality, done-evidence completeness, and drift detection.&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&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:#919F9F;--1:#5F636F&quot;&gt;# Validate event log for a mission&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;validate&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--mission&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;034-feature-name&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# JSON output for CI integration&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;validate&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--mission&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;034-feature-name&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--json&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Checks performed&lt;/strong&gt;:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Schema validation&lt;/strong&gt;: All required fields present, ULID format, canonical lane values, ISO 8601 timestamps&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Transition legality&lt;/strong&gt;: Every &lt;code dir=&quot;auto&quot;&gt;(from_lane, to_lane)&lt;/code&gt; pair is in the allowed transitions set (force transitions are always legal)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Done-evidence completeness&lt;/strong&gt;: Every done transition has evidence or force flag&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Materialization drift&lt;/strong&gt;: Compares &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; on disk with reducer output from event log&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Derived-view drift&lt;/strong&gt;: Compares materialized &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; against canonical event log (error if diverged)&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;spec-kitty-agent-status-reconcile&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent status reconcile&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;Scan target repositories for WP-linked branches and commits, detect planning-vs-implementation drift, and optionally emit reconciliation events.&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&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:#919F9F;--1:#5F636F&quot;&gt;# Preview reconciliation suggestions (dry-run is the default)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;reconcile&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--mission&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;034-feature-name&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--dry-run&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Scan a specific target repository&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;reconcile&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--mission&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;034-feature-name&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--target-repo&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;/path/to/implementation-repo&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--dry-run&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Apply reconciliation events (2.x only; disabled on 0.1x)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;reconcile&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--mission&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;034-feature-name&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--apply&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;How it works&lt;/strong&gt;:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Scans target repos for branches matching &lt;code dir=&quot;auto&quot;&gt;*&amp;#x3C;feature-slug&gt;*WP##*&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Scans commit messages containing &lt;code dir=&quot;auto&quot;&gt;WP##&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Checks which lane or mission branches are merged into the target branch&lt;/li&gt;
&lt;li&gt;Compares implementation evidence against canonical snapshot state&lt;/li&gt;
&lt;li&gt;Generates legal transition events to align planning with reality&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Limitations on 0.1x&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;--apply&lt;/code&gt; is disabled. Reconciliation is dry-run only.&lt;/p&gt;
&lt;h3 id=&quot;spec-kitty-agent-status-doctor&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent status doctor&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;Run health checks detecting stale claims, orphan workspaces, and unresolved drift.&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&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:#919F9F;--1:#5F636F&quot;&gt;# Run all health checks for a mission&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;doctor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--mission&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;034-feature-name&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Health checks&lt;/strong&gt;:&lt;/p&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Check&lt;/th&gt;&lt;th&gt;Severity&lt;/th&gt;&lt;th&gt;Description&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Event-log read failure&lt;/td&gt;&lt;td&gt;Error&lt;/td&gt;&lt;td&gt;Corrupt or unreadable &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;, regardless of snapshot presence&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Stale claims&lt;/td&gt;&lt;td&gt;Warning&lt;/td&gt;&lt;td&gt;WPs in &lt;code dir=&quot;auto&quot;&gt;claimed&lt;/code&gt; for &gt;7 days or &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt; for &gt;14 days&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Orphan workspaces&lt;/td&gt;&lt;td&gt;Warning&lt;/td&gt;&lt;td&gt;Worktrees existing for features where all WPs are terminal (done/canceled)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Materialization drift&lt;/td&gt;&lt;td&gt;Warning&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; does not match reducer output&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Derived-view drift&lt;/td&gt;&lt;td&gt;Error&lt;/td&gt;&lt;td&gt;Materialized snapshot differs from canonical event log&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Doctor reads the canonical event log before trusting &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt;. If the log is corrupt or unreadable it reports &lt;code dir=&quot;auto&quot;&gt;event_log_error&lt;/code&gt; (ERROR, exit 1, JSON &lt;code dir=&quot;auto&quot;&gt;healthy: false&lt;/code&gt;) naming the resolved path, the reason, and the 1-based line for malformed records. Log-dependent checks (stale claims, drift, reviewer self-approval, WP reconciliation) are skipped; independent checks still run. Doctor never modifies either file: preserve both, restore trusted history or fix file access, then rerun. Backfill and materialization do not substitute for a readable log.&lt;/p&gt;
&lt;h3 id=&quot;spec-kitty-agent-status-migrate&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent status migrate&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;Bootstrap canonical event logs from existing frontmatter lane state.&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&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:#919F9F;--1:#5F636F&quot;&gt;# Preview migration for a single feature&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;migrate&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--mission&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;034-feature-name&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--dry-run&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Execute migration for a single feature&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;migrate&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--mission&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;034-feature-name&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Migrate all features&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;migrate&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--all&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Preview all migrations&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;migrate&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--all&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--dry-run&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Migration behavior&lt;/strong&gt; (for pre-3.0 missions):&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Reads current frontmatter &lt;code dir=&quot;auto&quot;&gt;lane&lt;/code&gt; values from all WP files in the feature&lt;/li&gt;
&lt;li&gt;Resolves aliases (&lt;code dir=&quot;auto&quot;&gt;doing&lt;/code&gt; -&gt; &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt;) before creating events&lt;/li&gt;
&lt;li&gt;Generates one bootstrap event per WP: &lt;code dir=&quot;auto&quot;&gt;from_lane=planned, to_lane=&amp;#x3C;current_lane&gt;&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;WPs already at &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt; produce no events (no transition occurred)&lt;/li&gt;
&lt;li&gt;Idempotent: features with existing non-empty &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; are skipped&lt;/li&gt;
&lt;li&gt;Verification: reads back persisted events and confirms count matches&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;For new missions (3.0+)&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; bootstraps WP definitions. All subsequent status transitions are validated once in the status-owned &lt;code dir=&quot;auto&quot;&gt;transition_pipeline&lt;/code&gt; and appended to the event log by one of its two shells — the flat/primary &lt;code dir=&quot;auto&quot;&gt;emit_status_transition()&lt;/code&gt; or the transactional shell in &lt;code dir=&quot;auto&quot;&gt;coordination/status_transition.py&lt;/code&gt;. No frontmatter lane is written.&lt;/p&gt;
&lt;h3 id=&quot;legacy-compatibility&quot;&gt;Legacy Compatibility&lt;/h3&gt;
&lt;p&gt;The existing &lt;code dir=&quot;auto&quot;&gt;move-task&lt;/code&gt; command still works and internally delegates to the status emit pipeline:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&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:#919F9F;--1:#5F636F&quot;&gt;# This still works -- delegates to status emit internally&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;tasks&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;move-task&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;WP01&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--to&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;doing&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# &quot;doing&quot; is accepted as alias, persists as &quot;in_progress&quot; in the event log&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h2 id=&quot;subtask-completion-ownership-agent-tasks-mark-status&quot;&gt;Subtask completion ownership (&lt;code dir=&quot;auto&quot;&gt;agent tasks mark-status&lt;/code&gt;)&lt;/h2&gt;
&lt;p&gt;Subtask completion is an annotation on a work package, so the command has to decide
which work package an id belongs to before it writes anything. That decision has two
sources, and only two:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;the authored &lt;code dir=&quot;auto&quot;&gt;subtasks:&lt;/code&gt; list in the work package’s &lt;code dir=&quot;auto&quot;&gt;tasks/&amp;#x3C;WP&gt;.md&lt;/code&gt; frontmatter
(static design intent), and&lt;/li&gt;
&lt;li&gt;a &lt;strong&gt;structured&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt; row that names the id — a &lt;code dir=&quot;auto&quot;&gt;- [ ]&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;- [x]&lt;/code&gt; checkbox row,
a pipe-table row (owner from its WP column, else the enclosing heading), or an
inline &lt;code dir=&quot;auto&quot;&gt;Subtasks: T001, T002&lt;/code&gt; list under a work-package heading. A prose mention
never claims an id. Ids compare case-insensitively in both sources.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The owners of an id are the union of those two sources. An id more than one work
package claims is &lt;em&gt;shared&lt;/em&gt;, and &lt;code dir=&quot;auto&quot;&gt;mark-status&lt;/code&gt; refuses it rather than picking one:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&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:#919F9F;--1:#5F636F&quot;&gt;# refused: names WP01 and WP02, writes nothing&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;tasks&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;mark-status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;T001&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;done&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# scoped: records completion on WP02 only&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;tasks&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;mark-status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;T001&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;done&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--wp&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;WP02&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;A &lt;code dir=&quot;auto&quot;&gt;WP&amp;#x3C;digits&gt;&lt;/code&gt; id is a lane, not a subtask: &lt;code dir=&quot;auto&quot;&gt;mark-status WP01&lt;/code&gt; is refused with the
&lt;code dir=&quot;auto&quot;&gt;move-task&lt;/code&gt; remedy, even when the id also appears in a &lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt; index table. If a
work package genuinely authors a subtask with a work-package-shaped id, &lt;code dir=&quot;auto&quot;&gt;--wp &amp;#x3C;owner&gt;&lt;/code&gt;
is required, because the bare id reads two ways.&lt;/p&gt;
&lt;p&gt;The completion annotation’s &lt;code dir=&quot;auto&quot;&gt;wp_id&lt;/code&gt; is the owner resolved this way; the writer never
re-derives it from document order or a filename, so an event cannot land on a work
package the caller did not select.&lt;/p&gt;
&lt;h2 id=&quot;9-lane-state-machine&quot;&gt;9-Lane State Machine&lt;/h2&gt;
&lt;h3 id=&quot;canonical-lanes&quot;&gt;Canonical Lanes&lt;/h3&gt;























































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Lane&lt;/th&gt;&lt;th&gt;Description&lt;/th&gt;&lt;th&gt;Terminal&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt;&lt;/td&gt;&lt;td&gt;WP defined, not yet claimed&lt;/td&gt;&lt;td&gt;No&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;claimed&lt;/code&gt;&lt;/td&gt;&lt;td&gt;WP assigned to an actor, not yet started&lt;/td&gt;&lt;td&gt;No&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Active implementation underway&lt;/td&gt;&lt;td&gt;No&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Implementation complete, awaiting review&lt;/td&gt;&lt;td&gt;No&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Reviewer actively examining implementation&lt;/td&gt;&lt;td&gt;No&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Review passed, awaiting merge&lt;/td&gt;&lt;td&gt;No&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Merged/integrated into the mission target branch&lt;/td&gt;&lt;td&gt;Yes (unless forced)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Blocked by external dependency or issue&lt;/td&gt;&lt;td&gt;No&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;canceled&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Permanently abandoned&lt;/td&gt;&lt;td&gt;Yes&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;strong&gt;Alias&lt;/strong&gt;: &lt;code dir=&quot;auto&quot;&gt;doing&lt;/code&gt; -&gt; &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt; (resolved at input boundaries, never persisted in events)&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Display&lt;/strong&gt;: The kanban board shows 6 columns (Planned, Doing, For Review, In Review, Approved, Done). &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt; WPs appear in Planned; &lt;code dir=&quot;auto&quot;&gt;claimed&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt; appear in Doing, with &lt;code dir=&quot;auto&quot;&gt;claimed&lt;/code&gt; still preserved as a distinct canonical lane for ownership/stale-claim diagnostics. &lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;canceled&lt;/code&gt; WPs are shown separately below the board.&lt;/p&gt;
&lt;h3 id=&quot;allowed-transitions-27-pairs&quot;&gt;Allowed Transitions (27 pairs)&lt;/h3&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;plaintext&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;# Normal flow (implementation progression)&lt;/span&gt;&lt;/div&gt;&lt;/div&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;planned     -&gt; claimed         (requires actor)&lt;/span&gt;&lt;/div&gt;&lt;/div&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;claimed     -&gt; in_progress     (workspace context)&lt;/span&gt;&lt;/div&gt;&lt;/div&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;in_progress -&gt; for_review      (subtasks check)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&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;# Review progression&lt;/span&gt;&lt;/div&gt;&lt;/div&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;for_review  -&gt; in_review       (reviewer claims; actor required with conflict detection)&lt;/span&gt;&lt;/div&gt;&lt;/div&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;in_review   -&gt; approved        (ReviewResult required)&lt;/span&gt;&lt;/div&gt;&lt;/div&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;in_review   -&gt; done            (ReviewResult required)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&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;# Direct approval paths (legacy, kept for backward compat)&lt;/span&gt;&lt;/div&gt;&lt;/div&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;in_progress -&gt; approved        (direct approval path)&lt;/span&gt;&lt;/div&gt;&lt;/div&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;approved    -&gt; done            (merge verified)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&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;# Feedback loops&lt;/span&gt;&lt;/div&gt;&lt;/div&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;in_review   -&gt; in_progress     (changes requested, ReviewResult required)&lt;/span&gt;&lt;/div&gt;&lt;/div&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;in_review   -&gt; planned         (rejection with feedback, ReviewResult required)&lt;/span&gt;&lt;/div&gt;&lt;/div&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;approved    -&gt; in_progress     (rework after approval, requires review_ref)&lt;/span&gt;&lt;/div&gt;&lt;/div&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;approved    -&gt; planned         (rejection after approval, requires review_ref)&lt;/span&gt;&lt;/div&gt;&lt;/div&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;in_progress -&gt; planned         (abandon/reassign, requires reason)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&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;# Blocking&lt;/span&gt;&lt;/div&gt;&lt;/div&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;planned     -&gt; blocked&lt;/span&gt;&lt;/div&gt;&lt;/div&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;claimed     -&gt; blocked&lt;/span&gt;&lt;/div&gt;&lt;/div&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;in_progress -&gt; blocked&lt;/span&gt;&lt;/div&gt;&lt;/div&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;for_review  -&gt; blocked&lt;/span&gt;&lt;/div&gt;&lt;/div&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;in_review   -&gt; blocked         (ReviewResult required)&lt;/span&gt;&lt;/div&gt;&lt;/div&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;approved    -&gt; blocked&lt;/span&gt;&lt;/div&gt;&lt;/div&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;blocked     -&gt; in_progress&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&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;# Cancellation&lt;/span&gt;&lt;/div&gt;&lt;/div&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;planned     -&gt; canceled&lt;/span&gt;&lt;/div&gt;&lt;/div&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;claimed     -&gt; canceled&lt;/span&gt;&lt;/div&gt;&lt;/div&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;in_progress -&gt; canceled&lt;/span&gt;&lt;/div&gt;&lt;/div&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;for_review  -&gt; canceled&lt;/span&gt;&lt;/div&gt;&lt;/div&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;in_review   -&gt; canceled        (ReviewResult required)&lt;/span&gt;&lt;/div&gt;&lt;/div&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;approved    -&gt; canceled&lt;/span&gt;&lt;/div&gt;&lt;/div&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;blocked     -&gt; canceled&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Force override&lt;/strong&gt;: Any transition can be forced with &lt;code dir=&quot;auto&quot;&gt;--force --actor &amp;#x3C;name&gt; --reason &amp;#x3C;text&gt;&lt;/code&gt;. Forced transitions from terminal states (done, canceled) are allowed. All force events carry a full audit trail. One refusal is not force-overridable: a rewind into &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt; from &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; must carry a &lt;code dir=&quot;auto&quot;&gt;review_ref&lt;/code&gt; whether or not it is forced — see &lt;a href=&quot;#forced-rewinds-out-of-review&quot;&gt;Forced rewinds out of review&lt;/a&gt;.&lt;/p&gt;
&lt;h3 id=&quot;guard-conditions&quot;&gt;Guard Conditions&lt;/h3&gt;
















































































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Transition&lt;/th&gt;&lt;th&gt;Guard&lt;/th&gt;&lt;th&gt;Error if Violated&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;planned -&gt; claimed&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Actor identity required&lt;/td&gt;&lt;td&gt;“Transition planned -&gt; claimed requires actor identity”&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;claimed -&gt; in_progress&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Workspace context (placeholder, always passes)&lt;/td&gt;&lt;td&gt;“No workspace context”&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;in_progress -&gt; for_review&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Subtask completion check (placeholder)&lt;/td&gt;&lt;td&gt;“Unchecked subtasks”&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;in_progress -&gt; approved&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Reviewer approval evidence required&lt;/td&gt;&lt;td&gt;“Missing review approval evidence”&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;for_review -&gt; in_review&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Actor identity required (conflict detection)&lt;/td&gt;&lt;td&gt;“Transition for_review -&gt; in_review requires actor identity”&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;in_review -&gt; *&lt;/code&gt; (all outbound)&lt;/td&gt;&lt;td&gt;ReviewResult required in TransitionContext&lt;/td&gt;&lt;td&gt;“in_review outbound transitions require ReviewResult”&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;approved -&gt; done&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Merge/integration evidence required&lt;/td&gt;&lt;td&gt;“Missing merge evidence”&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;approved -&gt; in_progress&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Review feedback reference required&lt;/td&gt;&lt;td&gt;“Missing review feedback reference”&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;approved -&gt; planned&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Review feedback reference required&lt;/td&gt;&lt;td&gt;“Missing review feedback reference”&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;in_progress -&gt; planned&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Reason required&lt;/td&gt;&lt;td&gt;“Transition in_progress -&gt; planned requires reason”&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;in_review -&gt; in_progress&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;review_ref&lt;/code&gt; required (rail: the status emit path derives it from &lt;code dir=&quot;auto&quot;&gt;review_result.reference&lt;/code&gt; when no &lt;code dir=&quot;auto&quot;&gt;--review-ref&lt;/code&gt; was given)&lt;/td&gt;&lt;td&gt;a forced rewind without one: “Transition in_review -&gt; in_progress requires review_ref: …”; an unforced one is refused by the &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; review_result guard&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;for_review -&gt; in_progress&lt;/code&gt; (forced)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;review_ref&lt;/code&gt; required — force does &lt;strong&gt;not&lt;/strong&gt; override it&lt;/td&gt;&lt;td&gt;“Transition for_review -&gt; in_progress requires review_ref: …”&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;approved -&gt; in_progress&lt;/code&gt; (forced)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;review_ref&lt;/code&gt; required — force does &lt;strong&gt;not&lt;/strong&gt; override it&lt;/td&gt;&lt;td&gt;“Transition approved -&gt; in_progress requires review_ref: …”&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Any forced transition&lt;/td&gt;&lt;td&gt;Actor AND reason required&lt;/td&gt;&lt;td&gt;“Force transitions require actor and reason”&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;forced-rewinds-out-of-review&quot;&gt;Forced rewinds out of review&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; has no backward edge in the lane graph, so &lt;code dir=&quot;auto&quot;&gt;for_review -&gt; in_progress&lt;/code&gt; is
reachable &lt;strong&gt;only&lt;/strong&gt; by force. That makes the force gate the only gate on the edge, and a
force carrying nothing but &lt;code dir=&quot;auto&quot;&gt;--reason&lt;/code&gt; used to append a
&lt;code dir=&quot;auto&quot;&gt;for_review -&gt; in_progress&lt;/code&gt; event with &lt;code dir=&quot;auto&quot;&gt;review_ref: null&lt;/code&gt; — an event &lt;code dir=&quot;auto&quot;&gt;status validate&lt;/code&gt;
refuses (&lt;code dir=&quot;auto&quot;&gt;for_review-&gt;in_progress without review_ref&lt;/code&gt;). Because the log is append-only, the
row was permanent: a command that reported success left the Mission’s canonical ledger in a
state its own auditor calls invalid.&lt;/p&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;approved -&gt; in_progress&lt;/code&gt; reopen had the same defect on its forced arm (#6955): without a
&lt;code dir=&quot;auto&quot;&gt;--review-feedback-file&lt;/code&gt; the row recorded &lt;code dir=&quot;auto&quot;&gt;force: true&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;review_ref: null&lt;/code&gt;, which the
shared wire contract the sync consumer enforces rejects, so the reopen never propagated even
though the local ledger accepted it.&lt;/p&gt;
&lt;p&gt;The requirement is therefore &lt;strong&gt;force-insurmountable&lt;/strong&gt;. &lt;code dir=&quot;auto&quot;&gt;--force --reason&lt;/code&gt; still overrides a
missing edge or a guard, but it cannot override this: a rewind out of review must cite the
review feedback it is rewinding.&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Writer&lt;/th&gt;&lt;th&gt;Supplies the pointer how&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent status emit --to in_progress&lt;/code&gt;&lt;/td&gt;&lt;td&gt;the caller’s &lt;code dir=&quot;auto&quot;&gt;--review-ref &amp;#x3C;ref&gt;&lt;/code&gt;, or — since #7080 — the &lt;code dir=&quot;auto&quot;&gt;reference&lt;/code&gt; of the structured &lt;code dir=&quot;auto&quot;&gt;--review-result-json&lt;/code&gt; outcome; a request with neither is refused&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty orchestrator-api transition --to in_progress&lt;/code&gt;&lt;/td&gt;&lt;td&gt;the same two: &lt;code dir=&quot;auto&quot;&gt;--review-ref &amp;#x3C;ref&gt;&lt;/code&gt; or the structured review result’s &lt;code dir=&quot;auto&quot;&gt;reference&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent tasks move-task --to in_progress&lt;/code&gt;&lt;/td&gt;&lt;td&gt;the supplied review-feedback file, &lt;code dir=&quot;auto&quot;&gt;force-override&lt;/code&gt; (the command’s own sentinel for an operator rewind, set for both the explicit &lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt; form and the auto-promoted backward move, and since #6955 for the forced &lt;code dir=&quot;auto&quot;&gt;approved -&gt; in_progress&lt;/code&gt; reopen), or the structured review result’s &lt;code dir=&quot;auto&quot;&gt;reference&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent action implement&lt;/code&gt; (implementer of record or &lt;code dir=&quot;auto&quot;&gt;--force --note&lt;/code&gt; withdrawal)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;force-override&lt;/code&gt;, the same sentinel&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;A supplied &lt;code dir=&quot;auto&quot;&gt;--review-feedback-file&lt;/code&gt; on the &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; reopen always wins over the sentinel:
the row records the file path, and the move is force-free unless the caller explicitly
passed &lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt; (the reopen is still not a rejected verdict and mints no rejection review
cycle). &lt;code dir=&quot;auto&quot;&gt;force-override&lt;/code&gt; is a marker, not a path: no reader resolves it to an artifact, and
the implementer projection reads it as an operator rewind, never as a reviewer verdict.&lt;/p&gt;
&lt;p&gt;The generic doors (&lt;code dir=&quot;auto&quot;&gt;agent status emit&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;orchestrator-api&lt;/code&gt;, the batch and coordination
shells) get the derivation from &lt;code dir=&quot;auto&quot;&gt;status/transition_pipeline.py::prepare_transition&lt;/code&gt;, the
validation/event-build function they all go through; &lt;code dir=&quot;auto&quot;&gt;move-task&lt;/code&gt; keeps its own copy in
&lt;code dir=&quot;auto&quot;&gt;build_transition_plan&lt;/code&gt;, because its force decision needs the pointer before the request
exists. The derivation applies to every exit that carries a structured review result, not
only this edge, and it fills an &lt;strong&gt;absent&lt;/strong&gt; pointer only: a caller’s &lt;code dir=&quot;auto&quot;&gt;--review-ref&lt;/code&gt; is
recorded unchanged, a pointer that disagrees with &lt;code dir=&quot;auto&quot;&gt;review_result.reference&lt;/code&gt; is refused by
the consistency guard on an unforced move (a forced move skips that guard, as before), and
a blank or non-string structured reference is not a pointer.&lt;/p&gt;
&lt;p&gt;The edge set (&lt;code dir=&quot;auto&quot;&gt;REVIEW_REF_REQUIRED_EDGES&lt;/code&gt;) holds the edges whose persisted events the
shared &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events&lt;/code&gt; contract gates on &lt;code dir=&quot;auto&quot;&gt;review_ref&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;for_review -&gt; in_progress&lt;/code&gt;
(#6514), &lt;code dir=&quot;auto&quot;&gt;approved -&gt; in_progress&lt;/code&gt; (#6955) and &lt;code dir=&quot;auto&quot;&gt;in_review -&gt; in_progress&lt;/code&gt; (#7080). A
&lt;code dir=&quot;auto&quot;&gt;migration:&lt;/code&gt; actor is exempt from the write-path refusal (it reconstructs state; same
precedent as the #5446 note rule), though the auditor still reports such a row. A forced
&lt;code dir=&quot;auto&quot;&gt;approved -&gt; planned&lt;/code&gt; rewind is likewise outside this family: the sentinel fill follows the
edge set and the evidence-gated reopen arm covers only &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt;, so that row still
records &lt;code dir=&quot;auto&quot;&gt;force: true&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;review_ref: null&lt;/code&gt; — a forced rewind out of review does not by
itself imply a pointer.&lt;/p&gt;
&lt;p&gt;A refused command exits non-zero, names &lt;code dir=&quot;auto&quot;&gt;review_ref&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;--review-ref&lt;/code&gt;, and writes nothing:
&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; are byte-identical afterwards, and
&lt;code dir=&quot;auto&quot;&gt;status validate&lt;/code&gt; still passes. The rule is evaluated during validation, before the
lock-protected append, the snapshot materialization and the frontmatter mirror.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Rows written before this refusal.&lt;/strong&gt; An event already in the log is untouched: the tool
never rewrites historical event bytes, because event-sourced consumers replay them. That
covers every pointerless &lt;code dir=&quot;auto&quot;&gt;for_review -&gt; in_progress&lt;/code&gt; row written before #6514 and every
pointerless &lt;code dir=&quot;auto&quot;&gt;approved -&gt; in_progress&lt;/code&gt; row written before #6955 and every pointerless
&lt;code dir=&quot;auto&quot;&gt;in_review -&gt; in_progress&lt;/code&gt; row written before #7080.
&lt;code dir=&quot;auto&quot;&gt;spec-kitty agent status validate --mission &amp;#x3C;slug&gt; --json&lt;/code&gt; names each offending
&lt;code dir=&quot;auto&quot;&gt;event_id&lt;/code&gt;, and that finding stays until the row is corrected. There is no automatic
repair, and this release ships none. The only supported correction is append-only: a
maintainer authors a migration that appends a correction preserving the original record
(never an in-place rewrite) and records why, so the compensation is auditable alongside
the row it corrects. The compensating row does not clear the finding: schema validation
reads each immutable row on its own, so the original row keeps being reported. Do not
hand-edit &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;; the materialized &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; is derived and would
diverge.&lt;/p&gt;
&lt;h2 id=&quot;migration-phases&quot;&gt;Migration Phases&lt;/h2&gt;
&lt;p&gt;The status model used a phased rollout. As of 3.0, &lt;strong&gt;Phase 2 is the active and only supported model&lt;/strong&gt;. Phases 0 and 1 are historical and no longer apply to new missions.&lt;/p&gt;





























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Phase&lt;/th&gt;&lt;th&gt;Name&lt;/th&gt;&lt;th&gt;Behavior&lt;/th&gt;&lt;th&gt;Status&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;0&lt;/td&gt;&lt;td&gt;Hardening&lt;/td&gt;&lt;td&gt;Transition matrix enforced, no event log. Frontmatter was sole authority.&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Historical&lt;/strong&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;1&lt;/td&gt;&lt;td&gt;Dual-write&lt;/td&gt;&lt;td&gt;Events AND frontmatter updated on every transition. Reads came from frontmatter.&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Historical&lt;/strong&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;2&lt;/td&gt;&lt;td&gt;Read-cutover&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; is sole authority. &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; is derived snapshot.&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Active&lt;/strong&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;strong&gt;Default&lt;/strong&gt;: Phase 2 (event-log authority). Frontmatter lane is no longer written or read by active runtime commands.&lt;/p&gt;
&lt;h3 id=&quot;configuration&quot;&gt;Configuration&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Global default&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt;):&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;yaml&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:#7FDBCA;--1:#111111&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;phase&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;1&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# 0=hardening, 1=dual-write, 2=read-cutover&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Per-feature override&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;feature&gt;/meta.json&lt;/code&gt;):&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;json&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;{&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;status_phase&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;2&lt;/span&gt;&lt;/div&gt;&lt;/div&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;}&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Precedence&lt;/strong&gt;: meta.json &gt; config.yaml &gt; built-in default (1)&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;On 0.1x branches&lt;/strong&gt;: Phase is capped at 2 (maximum). Reconcile &lt;code dir=&quot;auto&quot;&gt;--apply&lt;/code&gt; is disabled.&lt;/p&gt;
&lt;h3 id=&quot;migration-workflow&quot;&gt;Migration Workflow&lt;/h3&gt;
&lt;p&gt;To migrate existing features to the canonical event log:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Preview&lt;/strong&gt;: Run &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent status migrate --all --dry-run&lt;/code&gt; to see what would happen&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Execute&lt;/strong&gt;: Run &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent status migrate --all&lt;/code&gt; to bootstrap event logs from frontmatter&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Verify&lt;/strong&gt;: Run &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent status validate --mission &amp;#x3C;slug&gt;&lt;/code&gt; for each mission to confirm integrity&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Optionally advance to Phase 2&lt;/strong&gt;: Set &lt;code dir=&quot;auto&quot;&gt;status.phase: 2&lt;/code&gt; in config.yaml or per-feature in meta.json&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;canonical-event-log-format&quot;&gt;Canonical Event Log Format&lt;/h2&gt;
&lt;p&gt;Events are stored in &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&amp;#x3C;feature&gt;/status.events.jsonl&lt;/code&gt; as one JSON object per line:&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;json&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;{&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;actor&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:{&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;model&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;span style=&quot;--0:#FF6A83;--1:#A24848&quot;&gt;null&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;profile&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;span style=&quot;--0:#FF6A83;--1:#A24848&quot;&gt;null&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;role&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;implementer&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;tool&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;claude&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;},&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;at&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;2026-02-08T12:00:00+00:00&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;event_id&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;01HXYZ...&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;evidence&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;span style=&quot;--0:#FF6A83;--1:#A24848&quot;&gt;null&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;execution_mode&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;worktree&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;mission_slug&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;034-feature-name&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;force&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;span style=&quot;--0:#FF6A83;--1:#A24848&quot;&gt;false&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;from_lane&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;planned&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;reason&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;span style=&quot;--0:#FF6A83;--1:#A24848&quot;&gt;null&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;review_ref&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;span style=&quot;--0:#FF6A83;--1:#A24848&quot;&gt;null&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;to_lane&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;claimed&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;,&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;wp_id&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;WP01&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;}&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Keys are always sorted (&lt;code dir=&quot;auto&quot;&gt;sort_keys=True&lt;/code&gt;) for deterministic, merge-friendly output.&lt;/p&gt;
&lt;h3 id=&quot;the-actor&quot;&gt;The actor&lt;/h3&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;actor&lt;/code&gt; field records who wrote an event. Transitions and annotations
written by agent, operator and system commands store a structured actor with
exactly four keys (#6400, extended to the system writers by #6722):&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Key&lt;/th&gt;&lt;th&gt;Value&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;tool&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The agent handle, for example &lt;code dir=&quot;auto&quot;&gt;claude&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;codex&lt;/code&gt;. Only the bare tool: a compact &lt;code dir=&quot;auto&quot;&gt;--agent&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;--actor&lt;/code&gt; value such as &lt;code dir=&quot;auto&quot;&gt;claude:opus:python-pedro&lt;/code&gt; contributes &lt;code dir=&quot;auto&quot;&gt;claude&lt;/code&gt; here. &lt;code dir=&quot;auto&quot;&gt;user&lt;/code&gt; when an operator names no agent (&lt;code dir=&quot;auto&quot;&gt;mark-status&lt;/code&gt; without &lt;code dir=&quot;auto&quot;&gt;--agent&lt;/code&gt;); for a system write, the identity that writer records (see &lt;a href=&quot;#system-writes&quot;&gt;System writes&lt;/a&gt;).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;role&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;implementer&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;reviewer&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;system&lt;/code&gt;, set by the action (see below), never by the profile.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;profile&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The agent profile, or &lt;code dir=&quot;auto&quot;&gt;null&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;model&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The model, or &lt;code dir=&quot;auto&quot;&gt;null&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;These commands write it: &lt;code dir=&quot;auto&quot;&gt;agent tasks move-task&lt;/code&gt; (every hop and its paired
note), &lt;code dir=&quot;auto&quot;&gt;agent tasks mark-status&lt;/code&gt; (which takes an optional &lt;code dir=&quot;auto&quot;&gt;--agent&lt;/code&gt;),
&lt;code dir=&quot;auto&quot;&gt;agent tasks add-history&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;agent action implement&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;agent action review&lt;/code&gt;
(their transitions and annotations), the review verdict note,
&lt;code dir=&quot;auto&quot;&gt;agent status emit&lt;/code&gt; and the &lt;code dir=&quot;auto&quot;&gt;orchestrator-api&lt;/code&gt; lifecycle commands
(&lt;code dir=&quot;auto&quot;&gt;start-implementation&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;start-review&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;transition&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;append-history&lt;/code&gt;).
The &lt;code dir=&quot;auto&quot;&gt;orchestrator-api&lt;/code&gt; JSON envelopes do not change; only the stored event does.
The system writers listed under &lt;a href=&quot;#system-writes&quot;&gt;System writes&lt;/a&gt; write the same
four keys, with &lt;code dir=&quot;auto&quot;&gt;role: &quot;system&quot;&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Profile.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;profile&lt;/code&gt; (and &lt;code dir=&quot;auto&quot;&gt;model&lt;/code&gt;) come from, in this order: the dispatch
invocation (&lt;code dir=&quot;auto&quot;&gt;--invocation-id&lt;/code&gt;), then &lt;code dir=&quot;auto&quot;&gt;--profile&lt;/code&gt;, then the profile (and model)
segment of a compact &lt;code dir=&quot;auto&quot;&gt;--agent&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;--actor&lt;/code&gt; value. When none of these gives one,
the value is &lt;code dir=&quot;auto&quot;&gt;null&lt;/code&gt;. Nothing is guessed, and the planned &lt;code dir=&quot;auto&quot;&gt;agent_profile&lt;/code&gt; in the
WP frontmatter is not copied in.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Role.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;reviewer&lt;/code&gt; for a hop into &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt;, for any
hop that leaves &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt; (a rejection, a block or a cancel during review)
and for a review verdict note. &lt;code dir=&quot;auto&quot;&gt;implementer&lt;/code&gt; for every other hop, for
implementer notes and for subtask marks. &lt;code dir=&quot;auto&quot;&gt;system&lt;/code&gt; for a write the program makes
with no agent dispatch behind it, on its own or on the operator’s behalf (an
attestation records the operator identity in &lt;code dir=&quot;auto&quot;&gt;tool&lt;/code&gt;; see &lt;a href=&quot;#system-writes&quot;&gt;System writes&lt;/a&gt;);
an agent role is never derived from a lane hop for a system write, and a system
write never gains &lt;code dir=&quot;auto&quot;&gt;implementer&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;reviewer&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Display and identity.&lt;/strong&gt; The board, the snapshot &lt;code dir=&quot;auto&quot;&gt;actor&lt;/code&gt; slot and the claim
check still use the bare tool (&lt;code dir=&quot;auto&quot;&gt;actor_identity_str&lt;/code&gt;), so a structured actor and
a bare-string actor naming the same tool are the same agent.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;What readers accept.&lt;/strong&gt; A bare string (every event written before #6400, and
every system row written before #6722), the 4-key dict above, and a 5-key dict
that adds &lt;code dir=&quot;auto&quot;&gt;profile_source&lt;/code&gt;. Any other dict is refused when the log is read. The
4-key dict is what every writer emits today, agent, operator and system alike.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;System writes.&lt;/strong&gt; A write the program makes on its own initiative or on the
operator’s behalf records the same four keys with &lt;code dir=&quot;auto&quot;&gt;role: &quot;system&quot;&lt;/code&gt;:&lt;/p&gt;

































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Writer&lt;/th&gt;&lt;th&gt;&lt;code dir=&quot;auto&quot;&gt;tool&lt;/code&gt;&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;the &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; bootstrap seed&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;a lane recovery catch-up&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;recovery&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;the consolidation approval replay and done mark, and the done-write refusal probe (a dry request that is never persisted)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;the &lt;code dir=&quot;auto&quot;&gt;--skip-review-artifact-check&lt;/code&gt; override annotation&lt;/td&gt;&lt;td&gt;the resolved operator identity&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;--attest-approved-reviewed&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;--attest-canceled-superseded&lt;/code&gt;&lt;/td&gt;&lt;td&gt;the resolved operator identity&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;migrate backfill-wp-status&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;backfill-runtime-state&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;verdict-provenance&lt;/code&gt; seeds&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;migration:&amp;#x3C;id&gt;&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;profile&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;model&lt;/code&gt; are always &lt;code dir=&quot;auto&quot;&gt;null&lt;/code&gt; for a system write: there is no dispatch
binding, and nothing is filled in from a plan or a default. &lt;code dir=&quot;auto&quot;&gt;tool&lt;/code&gt; carries the
identity the writer already recorded, whole — a &lt;code dir=&quot;auto&quot;&gt;migration:&amp;#x3C;id&gt;&lt;/code&gt; seed identity is
never split into a tool and a model, which is what keeps it a seed.&lt;/p&gt;
&lt;p&gt;Seed classification is unchanged and shape-blind: &lt;code dir=&quot;auto&quot;&gt;is_migration_actor&lt;/code&gt; (and so
the reducer’s seed arm, the timestamp-continuity exemption and the consolidation
work-window rule) projects a structured actor to its &lt;code dir=&quot;auto&quot;&gt;tool&lt;/code&gt;, so the string rows
written before this change and the structured rows written after it are the same
seed. An attestation is still identified by &lt;code dir=&quot;auto&quot;&gt;policy_metadata.attestation&lt;/code&gt;, never
by its &lt;code dir=&quot;auto&quot;&gt;role&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Who may write a seed.&lt;/strong&gt; A &lt;code dir=&quot;auto&quot;&gt;migration:&lt;/code&gt; actor means exactly one thing: an
in-process migration reconstructed that event. It is never a live decision, so a
caller can no longer produce one (#6754). &lt;code dir=&quot;auto&quot;&gt;agent status emit --actor&lt;/code&gt;, the four
&lt;code dir=&quot;auto&quot;&gt;orchestrator-api&lt;/code&gt; lifecycle verbs (&lt;code dir=&quot;auto&quot;&gt;start-implementation&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;start-review&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;transition&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;append-history&lt;/code&gt;, refused as &lt;code dir=&quot;auto&quot;&gt;USAGE_ERROR&lt;/code&gt;) and the hidden
&lt;code dir=&quot;auto&quot;&gt;implement --actor&lt;/code&gt; refuse a caller-supplied identity that starts with
&lt;code dir=&quot;auto&quot;&gt;migration:&lt;/code&gt;, exit non-zero and write nothing; the value is never rewritten into
a live-looking actor. An explicit &lt;code dir=&quot;auto&quot;&gt;--agent migration:x&lt;/code&gt; is &lt;strong&gt;not&lt;/strong&gt; refused: it is
read as the compact &lt;code dir=&quot;auto&quot;&gt;tool:model:profile&lt;/code&gt; form, so its tool is &lt;code dir=&quot;auto&quot;&gt;migration&lt;/code&gt; and it
is not a seed. A &lt;code dir=&quot;auto&quot;&gt;migration:&lt;/code&gt; identity already recorded keeps its seed status
when a later command re-records it with no caller option.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Planned (follow-up #6721).&lt;/strong&gt; A later release adds &lt;code dir=&quot;auto&quot;&gt;profile_source&lt;/code&gt; (where the
profile came from) to the written actor and fills &lt;code dir=&quot;auto&quot;&gt;profile&lt;/code&gt; from the WP
frontmatter when nothing else gives one. Readers already accept that 5-key
shape; a profile taken from the frontmatter will not count as the agent’s
identity in the reviewer-versus-implementer check.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2 id=&quot;commit-attribution-stamp-policy_metadatalane_head&quot;&gt;Commit attribution stamp (&lt;code dir=&quot;auto&quot;&gt;policy_metadata.lane_head&lt;/code&gt;)&lt;/h2&gt;
&lt;p&gt;Every persisted lifecycle transition of a WP mapped to a non-planning
execution lane whose branch exists is stamped, best-effort, with
&lt;code dir=&quot;auto&quot;&gt;policy_metadata[&quot;lane_head&quot;]&lt;/code&gt; — that lane branch’s &lt;code dir=&quot;auto&quot;&gt;git rev-parse&lt;/code&gt; HEAD sha
at the moment the transition is written. Both status shells inject the same
probe (&lt;code dir=&quot;auto&quot;&gt;specify_cli.status.lane_head.read_lane_head&lt;/code&gt;): the flat/primary
shell (&lt;code dir=&quot;auto&quot;&gt;status.emit.emit_status_transition&lt;/code&gt;) and the coordination
transactional shell (&lt;code dir=&quot;auto&quot;&gt;coordination.status_transition. emit_status_transition_transactional&lt;/code&gt;). The stamp is a local, free-form
sidecar on &lt;code dir=&quot;auto&quot;&gt;StatusEvent.policy_metadata&lt;/code&gt; — it does not change the
&lt;code dir=&quot;auto&quot;&gt;spec_kitty_events&lt;/code&gt; schema.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Best-effort, never blocking.&lt;/strong&gt; The probe never raises and never refuses a
transition: no &lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;, an unassigned WP, a planning lane, or a missing
lane branch all resolve to “no stamp” (&lt;code dir=&quot;auto&quot;&gt;policy_metadata&lt;/code&gt; stays absent or
unset for that key), and the transition still persists. A mission created
before this stamp existed, or a transition made outside the governed
workflow, therefore carries no stamp on some or all of its events — this is
expected, not corruption.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Read only by the consolidation reconciliation gate, and only for mixed
lanes.&lt;/strong&gt; A &lt;em&gt;mixed lane&lt;/em&gt; is an execution lane with at least one approved WP
and at least one WP canceled with operator provenance. For every such lane,
the gate resolves each WP’s implementation/review windows from its own
&lt;code dir=&quot;auto&quot;&gt;lane_head&lt;/code&gt; stamps (the SHA an &lt;em&gt;opening&lt;/em&gt; transition — &lt;code dir=&quot;auto&quot;&gt;claimed&lt;/code&gt;/
&lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt; — and a &lt;em&gt;closing&lt;/em&gt; transition — &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt;/cancel —
carried), bounding exactly which lane commits belong to which WP’s work
sessions. Events synthesized by a migration (actor &lt;code dir=&quot;auto&quot;&gt;migration:...&lt;/code&gt;, e.g. the
birth-cutover backfill seeds) never open, close or extend a window. Lanes that
are not mixed never read this stamp — the ordinary consolidation path is
unchanged for them.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Verdict rules (summary).&lt;/strong&gt; For a mixed lane, the gate compares each canceled
WP’s own unsuperseded content against the target, and checks that every lane
commit belongs to some WP’s window:&lt;/p&gt;


















































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Verdict&lt;/th&gt;&lt;th&gt;When&lt;/th&gt;&lt;th&gt;Effect and recovery&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;PASS&lt;/td&gt;&lt;td&gt;No mixed lane, or every canceled WP’s content was superseded by a later, non-canceled commit on the same lane (a rework, a revert, or content the target already carried), and every lane content commit lies in some WP’s window&lt;/td&gt;&lt;td&gt;Consolidation proceeds&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;FAIL&lt;/td&gt;&lt;td&gt;A canceled WP’s content (an addition, a modification, or a deletion) is still present on the target, unsuperseded&lt;/td&gt;&lt;td&gt;Target restored (compare-and-swap); names the lane, WP and every offending path. Recovery: revert the change on the lane through a surviving WP’s governed work, re-run. &lt;strong&gt;Not overridable.&lt;/strong&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;FAIL (&lt;code dir=&quot;auto&quot;&gt;CANCELED_REACHABLE_VIA_DEPENDENCY&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;A fully-canceled dependency lane’s content reached an approved lane through the dependency step, is still live there and is on the target (#5569, #5613). Commits that every carrying lane fully superseded are not counted&lt;/td&gt;&lt;td&gt;Target restored; names the canceled WPs, both lanes and the path, alongside the strategy check’s own message. Recovery: undo the change on the carrying lane through a surviving WP’s governed work, re-run. &lt;strong&gt;Not overridable.&lt;/strong&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;FAIL (&lt;code dir=&quot;auto&quot;&gt;APPROVED_CONTENT_MISSING&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;An approved code lane’s own net change to a path is not on the target, the target left that path alone since the lane was cut, and no later approved lane built atop it superseded the path (#5571, #5613). Applies to every lane, mixed or not, under both strategies. A path the target also changed is not judged&lt;/td&gt;&lt;td&gt;Target restored; names the approved WP, its lane and the path. Recovery: restore the change on the mission branch (for example revert a commit that recorded the staged deletions of a lagging worktree), re-run. &lt;strong&gt;Not overridable.&lt;/strong&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;REFUSE (attribution evidence)&lt;/td&gt;&lt;td&gt;The canceled WP’s commits cannot be bounded: no stamp, a window that never closed, a stamp that is not an ancestor of the lane tip, or a commit contested between two WPs’ windows&lt;/td&gt;&lt;td&gt;Target restored. The evidence cannot appear later (the log is append-only), so the message names the override: verify by hand that the canceled content is absent or superseded, then re-run with &lt;code dir=&quot;auto&quot;&gt;--attest-canceled-superseded &amp;#x3C;WP&gt; --attest-reason &quot;&amp;#x3C;what you checked&gt;&quot;&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;REFUSE (closed world)&lt;/td&gt;&lt;td&gt;Every window resolved, yet a non-merge, non-bookkeeping lane commit lies in no WP’s window and after the lane’s own base (a straggler after the cancel, a commit by a WP that never entered implementation). Commits reachable from the lane head at its first claim, a dependency-lane tip, or the target’s pre-consolidation tip are not outside&lt;/td&gt;&lt;td&gt;Target restored; names the lane, up to three short commit shas and a path. Recovery: verify by hand that those commits carry no canceled work, then attest as above; re-attesting after a later straggler records a fresh attestation whose stamp covers it&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;REFUSE (merged with an independent change)&lt;/td&gt;&lt;td&gt;The target is neither the canceled state, its pre-state, nor the window base’s state&lt;/td&gt;&lt;td&gt;Target restored. Recovery: supersede through a surviving WP and re-run, or attest after verifying by hand&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;REFUSE (infrastructure)&lt;/td&gt;&lt;td&gt;The status event log or the lane’s git history cannot be read&lt;/td&gt;&lt;td&gt;Target restored. Repair the log or history and re-run. &lt;strong&gt;Not overridable.&lt;/strong&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;“Target restored” in this table is the minimum: every FAIL/REFUSE (and every
squash-projection refusal) also runs the single rollback authority
(&lt;code dir=&quot;auto&quot;&gt;consolidation/rollback.py&lt;/code&gt;), which restores every branch the run moved —
target, mission branch, coordination branch — to its pre-consolidation commit
with compare-and-swap and prints a per-branch report; a branch another actor
moved is named, never overwritten. A claim whose integrity already fails
(explicit refusal, unresolved surface, empty claim) is refused before any
mutation instead (ADR &lt;code dir=&quot;auto&quot;&gt;2026-09-19-1&lt;/code&gt;, Amendment 2026-09-29; #5338, #5318).&lt;/p&gt;
&lt;p&gt;REFUSE takes precedence over FAIL: an attribution failure is always reported
as missing evidence, never silently downgraded to (or masked by) a content
verdict.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Operator-attested override (FR-012).&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty consolidate --attest-canceled-superseded &amp;#x3C;WP&gt; --attest-reason &quot;&amp;#x3C;text&gt;&quot;&lt;/code&gt; (the WP id is
repeatable; the reason is required) records, through the canonical status
write seam, a forced &lt;code dir=&quot;auto&quot;&gt;canceled -&gt; canceled&lt;/code&gt; transition of that canceled WP
carrying the actor, the reason, the timestamp, &lt;code dir=&quot;auto&quot;&gt;reason_source: operator&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;policy_metadata.attestation: canceled_superseded&lt;/code&gt;. No event-schema change is
involved and the event log stays the only authority. For an attested WP the
gate lifts the attribution-evidence and “merged with an independent change”
REFUSEs. For the closed world the attestation is bounded in time: its own
&lt;code dir=&quot;auto&quot;&gt;lane_head&lt;/code&gt; stamp exempts the lane commits made up to it, and a straggler
committed afterwards still REFUSEs until the operator checks it and attests
again. Attesting again is not enough when the straggler was committed after
an approved WP’s approval: that WP must also be approved again, or the lane
refuses with &lt;code dir=&quot;auto&quot;&gt;LANE_MOVED_AFTER_APPROVAL&lt;/code&gt; (ADR
&lt;a href=&quot;/adr/4.x/2026-10-04-5-approval-stamp-bounds-the-approved-claim/&quot;&gt;2026-10-04-5&lt;/a&gt;). Every explicit &lt;code dir=&quot;auto&quot;&gt;--attest-canceled-superseded&lt;/code&gt; records a fresh
attestation (a new operator act with its own reason and stamp); the latest one
per WP is the one the gate reads. A FAIL and an
infrastructure REFUSE still stand. A later governed transition of the WP voids
the attestation. The attestation applies only to a WP canceled with operator
provenance; any other WP id is refused before anything is recorded. &lt;code dir=&quot;auto&quot;&gt;--dry-run&lt;/code&gt;
records nothing and says so. The attestation’s &lt;code dir=&quot;auto&quot;&gt;policy_metadata&lt;/code&gt; key also counts
as event-log runtime evidence for the birth cutover
(&lt;code dir=&quot;auto&quot;&gt;status/cutover_eligibility.py&lt;/code&gt;), like any key other than &lt;code dir=&quot;auto&quot;&gt;lane_head&lt;/code&gt;. See ADR
&lt;a href=&quot;/adr/3.x/2026-09-29-1-closed-world-refuse-on-mixed-lanes/&quot;&gt;2026-09-29-1&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Known, accepted residuals.&lt;/strong&gt; Attribution works per commit window and per
path, not per hunk or per author, and the closed world trusts its anchors, so
four shapes remain documented limitations. Two of them over-block (the gate FAILs when it ideally would not,
or names the wrong WP), which is the safe direction:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;content that a separate approved lane independently authored under the
identical path and bytes can still FAIL;&lt;/li&gt;
&lt;li&gt;an out-of-workflow commit by a sibling WP that never entered
implementation, landing inside a canceled WP’s open window, is attributed
to the canceled WP — the gate still FAILs, but the finding names the wrong
WP.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Two of them can let canceled or unowned content reach the target under a PASS:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;a survivor’s rework that only partially overwrites a canceled WP’s change
marks the whole path superseded, so the kept hunks ship;&lt;/li&gt;
&lt;li&gt;an out-of-workflow commit made on the lane before the first governed claim
is exempt via the first-claim anchor;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;A fully-canceled dependency lane whose content fast-forwards into a dependent
lane is no longer a residual: its commits are subtracted from the dependency-tip
exemption (#5569), and a fully-canceled dependency lane whose branch is deleted
or unreadable REFUSEs at claim time, unless the status event log proves the lane
never started (every WP canceled from &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt; and none ever moved
into any other lane than &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;canceled&lt;/code&gt;, so no branch was
created) and no lane-tip ref is recorded for it (#5937). A
canceled lane nobody depends on is still tolerated when its branch is gone.
Since #5613 a canceled commit that every carrying lane fully superseded stays in
the claim, live content FAILs with &lt;code dir=&quot;auto&quot;&gt;CANCELED_REACHABLE_VIA_DEPENDENCY&lt;/code&gt;, and a
canceled dependency WP without a &lt;code dir=&quot;auto&quot;&gt;lane_head&lt;/code&gt; stamp REFUSEs at claim time; the
attestation lifts that refusal only, per attested WP, and never the FAIL.
Supersession is per path here too: an approved WP that touches a canceled WP’s
file supersedes the whole path.&lt;/p&gt;
&lt;p&gt;Each is pinned by a strict expected-failure test that asserts the ideal
outcome, and is tracked as follow-up work under the parent epic. Two former
residuals are closed by the closed-world check and are pinned as REFUSE: an
out-of-workflow commit on the lane after a cancel, and a commit by a WP that
never entered implementation.&lt;/p&gt;
&lt;h2 id=&quot;mission-write-lock-and-rollback&quot;&gt;Mission write lock and rollback&lt;/h2&gt;
&lt;p&gt;Several agents can write one Mission checkout at once (#5819). Two rules keep their writes apart.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;One lock per Mission, one key.&lt;/strong&gt; Every writer of a Mission’s status files and shared planning files takes &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;git common dir&gt;/spec-kitty-locks/&amp;#x3C;Mission directory name&gt;.status.lock&lt;/code&gt;. The key is computed by the pure, git-free &lt;code dir=&quot;auto&quot;&gt;mission_lock_key(feature_dir)&lt;/code&gt;: when the Mission is coordination-routed (a &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; is recorded) and a mid8 is recorded, the key is the coordination directory name, otherwise it is the Mission directory name — never the bare slug. Every lock door and the status transaction resolve the same key through this one function, so a legacy &lt;code dir=&quot;auto&quot;&gt;060-test&lt;/code&gt; primary directory and its &lt;code dir=&quot;auto&quot;&gt;060-test-&amp;#x3C;mid8&gt;&lt;/code&gt; coordination surface lock the same file. The key is computed once before the lock is entered and passed down; a thread already holding the lock reuses the held key, so a writer that changes &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;mid8&lt;/code&gt; inside the hold never takes a second, different lock. The decisions lock (&lt;code dir=&quot;auto&quot;&gt;decisions/index.json.lock&lt;/code&gt;) is taken before the Mission status lock, never the reverse: a resolve, defer or cancel holds it across its artifact write and its terminal event append, which takes the Mission status lock inside (#5681, the terminal half of #4848). The primitive is &lt;code dir=&quot;auto&quot;&gt;status/mission_write.py&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;mission_write_lock(feature_dir)&lt;/code&gt; (re-entrant per thread; bounded wait by default, while the &lt;code dir=&quot;auto&quot;&gt;agent action implement&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;review&lt;/code&gt; claim windows and &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt;’s claim hold wait without a limit), &lt;code dir=&quot;auto&quot;&gt;locked_rewrite_text(path, transform, feature_dir=...)&lt;/code&gt; (read, transform and atomic write under the lock), &lt;code dir=&quot;auto&quot;&gt;capture_rollback_point&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;rollback_events_log&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;rollback_status_artifacts&lt;/code&gt;. Non-status writers resolve the directory with &lt;code dir=&quot;auto&quot;&gt;mission_write_lock_dir&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;missions/_read_path_resolver.py&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Locked helpers for &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; and frontmatter.&lt;/strong&gt; A read-modify-write of a Mission file runs inside one lock hold through a registered helper, so a concurrent locked write is never erased. &lt;code dir=&quot;auto&quot;&gt;locked_update_meta(feature_dir, mutate, ...)&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;mission_metadata&lt;/code&gt;) takes the lock, re-reads &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;, applies the mutation and writes atomically; every &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; setter uses it. &lt;code dir=&quot;auto&quot;&gt;locked_update_frontmatter(wp_path, mutate, *, feature_dir, ...)&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;frontmatter&lt;/code&gt;) does the same for a work package’s frontmatter, so &lt;code dir=&quot;auto&quot;&gt;map-requirements&lt;/code&gt; and the &lt;code dir=&quot;auto&quot;&gt;finalize-tasks&lt;/code&gt; flush keep each other’s refs and history notes. The issue-matrix scaffold runs its existence check and its write under the lock, and the acceptance-matrix re-read helper, the acceptance verdict guard and the issue-verdict helper lock through the same door so writers in two worktrees of one Mission exclude each other.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Rollback is verified.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;capture_rollback_point&lt;/code&gt; records the log size and &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; bytes and refuses unless the caller holds the lock. A rollback cuts only the rows its own operation appended and that are not committed at &lt;code dir=&quot;auto&quot;&gt;HEAD&lt;/code&gt;. It refuses on any doubt: the log vanished or shrank, the tail is not whole JSON rows, the tail is not the rows the caller appended, the tail is already committed, or &lt;code dir=&quot;auto&quot;&gt;HEAD&lt;/code&gt; cannot be read (including a committed log that holds a non-JSON line). A refusal leaves the files unchanged and reports &lt;code dir=&quot;auto&quot;&gt;STATUS_ROLLBACK_REFUSED&lt;/code&gt; with the reason and a &lt;code dir=&quot;auto&quot;&gt;git diff HEAD -- &amp;#x3C;log&gt;&lt;/code&gt; command naming the log it checked (on a coordination Mission, the coordination worktree’s log); &lt;code dir=&quot;auto&quot;&gt;agent action&lt;/code&gt; prints it, and the coordination fallback appends it to the commit error it re-raises. The exception is a tail already committed at &lt;code dir=&quot;auto&quot;&gt;HEAD&lt;/code&gt; (always so on a coordination Mission): &lt;code dir=&quot;auto&quot;&gt;agent action implement&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;review&lt;/code&gt; then print &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;WP&gt; claim was committed; the follow-up &amp;#x3C;operation&gt; commit failed: &amp;#x3C;error&gt;&lt;/code&gt;, record the claim as committed and exit 1, with no refusal code. Nothing is cut and there is nothing to revert. The rollback never extends the file. Only this module truncates or unlinks &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Checkout claim lock.&lt;/strong&gt; On &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt; the write checkout has one occupant. &lt;code dir=&quot;auto&quot;&gt;write_checkout_claim_lock(write_checkout)&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;status/locking.py&lt;/code&gt;, beside &lt;code dir=&quot;auto&quot;&gt;feature_status_lock&lt;/code&gt;) is a sibling of the Mission lock in the same lock hierarchy: it serializes the occupancy scan and the claim emit, keyed on the resolved checkout root. The order is fixed, checkout lock then Mission lock. Taking the checkout lock while the thread holds any other status lock raises &lt;code dir=&quot;auto&quot;&gt;RuntimeError&lt;/code&gt; naming the held lock keys. That is an internal error (a caller broke the order), so the orchestrator API lets it propagate. A checkout lock that stays held past its bound is the retryable case: &lt;code dir=&quot;auto&quot;&gt;agent action implement&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt; and the orchestrator API &lt;code dir=&quot;auto&quot;&gt;start-implementation&lt;/code&gt; report it as &lt;code dir=&quot;auto&quot;&gt;STATUS_LOCK_HELD&lt;/code&gt; (the API as an envelope, the CLI as a printed code with exit 1). &lt;code dir=&quot;auto&quot;&gt;agent action implement&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;agent action review&lt;/code&gt; also warn, without refusing, when &lt;code dir=&quot;auto&quot;&gt;shared_workspace_writers&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;lanes/checkout_occupancy.py&lt;/code&gt;) finds another actor’s work package active in the same checkout.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Gate.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_mission_write_discipline.py&lt;/code&gt; keeps the writer class closed by construction, with an empty allowlist. Its four rules fail the build on: (1) a truncate, unlink or whole-file rewrite (&lt;code dir=&quot;auto&quot;&gt;open(..., &quot;w&quot;)&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;write_text&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;write_bytes&lt;/code&gt;) of a status log or run log outside the primitive; (2) a callable passed into a lock region that is stored, returned or captured so it could run after the lock is released; (3) a Mission lock keyed by anything other than a known Mission-directory-name expression (a slug-keyed or subscript key is refused); and &lt;strong&gt;Rule 4&lt;/strong&gt; — a write to &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;, a &lt;code dir=&quot;auto&quot;&gt;tasks/WP*.md&lt;/code&gt; frontmatter file or &lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt; that sits outside a lock region and does not go through a registered locked helper. A lock region is a lexical &lt;code dir=&quot;auto&quot;&gt;with&lt;/code&gt; of a lock context manager (and its &lt;code dir=&quot;auto&quot;&gt;ExitStack&lt;/code&gt; / assigned-name forms); the status-core regions (&lt;code dir=&quot;auto&quot;&gt;BookkeepingTransaction&lt;/code&gt; and the emit lock) are recognised structurally, and migrations get no exemption — they write through the helpers.&lt;/p&gt;
&lt;h2 id=&quot;file-layout-per-feature&quot;&gt;File Layout (per feature)&lt;/h2&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;plaintext&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;kitty-specs/&amp;#x3C;feature&gt;/&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;status.events.jsonl    # CANONICAL: append-only event log&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;status.json            # DERIVED: materialized snapshot (regenerable)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;meta.json              # Mission metadata (includes optional status_phase)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;tasks/&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;WP01-name.md         # DERIVED: frontmatter lane is compatibility view&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;WP02-name.md&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;tasks.md               # DERIVED: status sections from snapshot&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Authority hierarchy&lt;/strong&gt;:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; — canonical truth (append-only, immutable events)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; — derived snapshot (regenerable via &lt;code dir=&quot;auto&quot;&gt;status materialize&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;WP frontmatter — static definition only (title, dependencies, subtasks); &lt;code dir=&quot;auto&quot;&gt;lane&lt;/code&gt; field is historical/migration-only&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tasks.md&lt;/code&gt; status sections — human view (regenerable)&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;troubleshooting&quot;&gt;Troubleshooting&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;“Illegal transition” error&lt;/strong&gt;: The transition is not in the allowed transitions matrix. Use &lt;code dir=&quot;auto&quot;&gt;--force --actor &amp;#x3C;name&gt; --reason &amp;#x3C;text&gt;&lt;/code&gt; to override, or check that the from_lane matches what you expect (run &lt;code dir=&quot;auto&quot;&gt;status materialize --json&lt;/code&gt; to see current state).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Materialization drift detected&lt;/strong&gt;: Run &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent status materialize&lt;/code&gt; to regenerate &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; from the event log.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Frontmatter lane drift&lt;/strong&gt; (legacy missions only): Frontmatter lane is no longer part of the active status model. For pre-3.0 missions that still have frontmatter lane values, run &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent status migrate --mission &amp;#x3C;slug&gt;&lt;/code&gt; to bootstrap the event log, then status is managed exclusively via events.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;“No event log found”&lt;/strong&gt;: Run &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent status migrate --mission &amp;#x3C;slug&gt;&lt;/code&gt; to bootstrap from existing frontmatter state.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Stale claims reported by doctor&lt;/strong&gt;: Either continue work on the WP or release the claim by moving it back to &lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt; (requires reason).&lt;/p&gt;
&lt;h3 id=&quot;coordination-status-write-guard&quot;&gt;Coordination status-write guard&lt;/h3&gt;
&lt;p&gt;On a Mission with a coordination topology, a status write (&lt;code dir=&quot;auto&quot;&gt;agent status emit&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;agent tasks move-task&lt;/code&gt;, and any other command that records a lane
transition) is committed from the coordination worktree. Before a write that
goes through the status transaction (&lt;code dir=&quot;auto&quot;&gt;BookkeepingTransaction.acquire&lt;/code&gt;) opens,
the status log in that worktree is compared with the log its branch HEAD has
committed (#5572, #5613). The write is refused, and nothing is written, in two
cases:&lt;/p&gt;




















&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Code&lt;/th&gt;&lt;th&gt;Condition&lt;/th&gt;&lt;th&gt;Recovery&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;COORD_STATUS_SURFACE_DIVERGED&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The worktree’s &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; no longer holds events that HEAD has committed, for example after a rolled-back consolidation restored the file to its earlier bytes and the rollback could not bring the checkout back to the coordination tip (since #5638 it does so whenever only status residue differs). Writing on top of it would commit a log without those events&lt;/td&gt;&lt;td&gt;The message names up to three of the missing event ids and offers two remedies. &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor coordination --fix --mission &amp;#x3C;slug&gt;&lt;/code&gt; reverts the stranded &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt;, so the Mission is no longer recorded as done; &lt;code dir=&quot;auto&quot;&gt;spec-kitty consolidate --resume --mission &amp;#x3C;slug&gt;&lt;/code&gt; does the same heal and then completes the consolidation. Always pass &lt;code dir=&quot;auto&quot;&gt;--mission&lt;/code&gt;: without it &lt;code dir=&quot;auto&quot;&gt;doctor coordination --fix&lt;/code&gt; acts on every Mission and flattens those with a stale &lt;code dir=&quot;auto&quot;&gt;coordination_branch&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;git -C &amp;#x3C;coordination worktree&gt; checkout HEAD -- &amp;#x3C;mission dir&gt;/status.events.jsonl &amp;#x3C;mission dir&gt;/status.json&lt;/code&gt; keeps the committed events and discards only the stale working-tree bytes; once a later status write lands on top of them, &lt;code dir=&quot;auto&quot;&gt;consolidate --resume&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;doctor coordination --fix&lt;/code&gt; decline the automatic heal (the log holds a commit the marker did not record) and ask for a manual reconcile. Choose one, then retry the write&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;COORD_STATUS_SURFACE_UNREADABLE&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The check cannot be answered: HEAD or its committed log cannot be read, the committed log has a malformed line or repeats an event id, or the working-tree log cannot be read&lt;/td&gt;&lt;td&gt;Repair the committed log or the checkout, then retry. The message names the reason&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Extra, uncommitted lines in the worktree log are not a divergence: an
interrupted append is repaired by the write’s own rollback. A Mission without a
coordination topology is not checked. The caller-visible shape of the refusal is
in the &lt;a href=&quot;/api/agent-subcommands/#coordination-status-writes-refusal-on-a-diverged-status-log&quot;&gt;agent subcommand reference&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;The guard does not cover every writer. The fallback coordination arm
(&lt;code dir=&quot;auto&quot;&gt;_emit_on_coord_then_commit&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;coordination/status_transition.py&lt;/code&gt;) and the
writers that append raw decision and retrospective rows (&lt;code dir=&quot;auto&quot;&gt;append_raw_rows_atomic&lt;/code&gt;)
do not pass through the status transaction, so they do not run this check
(#5644).&lt;/p&gt;
&lt;h3 id=&quot;pre-30-layout-rejection&quot;&gt;Pre-3.0 layout rejection&lt;/h3&gt;
&lt;p&gt;Active &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; commands (task, status, acceptance) require a post-3.0
project layout — flat &lt;code dir=&quot;auto&quot;&gt;tasks/WP*.md&lt;/code&gt; files and &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; as the
status source of truth. Commands that encounter a pre-3.0 lane-directory layout
(&lt;code dir=&quot;auto&quot;&gt;tasks/planned/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tasks/doing/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tasks/for_review/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tasks/done/&lt;/code&gt;
containing &lt;code dir=&quot;auto&quot;&gt;.md&lt;/code&gt; files) will refuse to proceed:&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;plaintext&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;Pre-3.0 layout detected (tasks/planned/ directories or frontmatter lane state).&lt;/span&gt;&lt;/div&gt;&lt;/div&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;Run `spec-kitty upgrade` to migrate before continuing.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;Migration path&lt;/strong&gt;: Run &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; (or
&lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade --migration 0.9.0_frontmatter_only_lanes&lt;/code&gt;) to move WP
files from lane subdirectories to flat &lt;code dir=&quot;auto&quot;&gt;tasks/&lt;/code&gt;. After upgrade, all active
commands will work normally.&lt;/p&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;lane&lt;/code&gt; frontmatter field is historical/migration-only and is not written
or read by any active command. Status is tracked exclusively through
&lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt;.&lt;/p&gt;</content>
</entry>
