---
type: "Architecture"
title: "Status Model: Operator Documentation"
description: "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."
status: "stable"
generated:
  by: "process:dockitty-export"
  at: "2026-11-01T00:00:00Z"
---

# Status Model: Operator Documentation

**Mission of record**: `034-feature-status-state-model-remediation` (legacy slug)

**Terminology note**
- Domain model: `Mission Type -> Mission -> Mission Run`.
- `--mission` is the only tracked-mission selector. The old `--feature` alias has been
  removed from every user-facing command (#1060, the selector hard-removal); passing
  `--feature` exits with code 2.
- A mission's canonical machine identity is `mission_id` (a ULID, since mission
  `083-mission-id-canonical-identity-migration`). The `--mission` flag accepts `mission_id`, `mid8` (first 8 chars of the ULID), or `mission_slug`. The numeric prefix in slug examples below (e.g. `034-feature-name`) is display-only metadata — the event log's aggregate key is `mission_id`, not the prefix. See the [mission identity migration runbook](/migrations/mission-id-canonical-identity.md).

## Overview

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 `StatusEvent` in `status.events.jsonl`. A deterministic reducer produces `status.json` snapshots.

> **Which reducer runs?** One: the wall-clock `spec_kitty_events.diary.reduce_parsed`, reached through `status.reducer.reduce` and through `materialize_snapshot` / `materialize`. It is deterministic but not Lamport-ordered; see [Known limitations](#known-limitations). Every other event log core writes and reads is mapped in [Event ledger writers and readers](/architecture/event-ledger-writers-and-readers.md).

> **This event log is the open-core producer's read model (2026-10-12 direction).** The
> **Mission Status Read API** — the open-core **producer** surface (ADR
> [`2026-10-01-2`](/adr/4.x/2026-10-01-2-mission-status-read-api-and-dashboard-extraction.md),
> Accepted) — is conformance-gated against `status.reducer.materialize_snapshot`, the same
> wall-clock reducer every CLI reader uses, so its answer is meant to match `status.json`.
> Its Java port does not yet carry the #4941 approved-departure lift (#6268). Its Java service and the
> `mission-status` contract live in `spec-kitty-events` (`service/`, `contracts/`, ADR
> [`2026-10-29-1`](/adr/4.x/2026-10-29-1-the-events-domain-and-its-java-services-live-in-spec-kitty-events.md));
> core pins a release (`pins/read-service.source.yaml`) 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.

**Key principles**:
- `status.events.jsonl` is the **sole source of truth** for WP lane state
- `status.json` is a **derived** materialized snapshot (regenerable)
- WP frontmatter is for **static definition only** (title, dependencies, subtasks) -- the `lane` field is no longer written or read by active runtime code
- `finalize-tasks` is the **canonical bootstrap point** -- it creates initial WP definitions; status transitions are tracked exclusively in the event log
- Frontmatter `lane` is a **historical/migration-only** concept retained in migration code paths for backward compatibility

**Read-only commands stay read-only**: status commands (including `materialize()` and `spec-kitty agent status materialize`) no longer dirty the git working tree. `status.json` is only written when there is a new event to materialize. The `materialized_at` field in `status.json` reflects the timestamp of the last event in the log, not the wall clock at the time the command was run.

> **Forward-looking (Proposed):** the "frontmatter is static-only" principle above
> is only half-delivered today — `lane` was evicted, but `shell_pid`,
> subtask-checkbox state, review-cycle fields, `agent`/`assignee`, and the
> activity-log narrative are still written into `tasks/WP##.md` at runtime. The
> WP runtime-state eviction mission generalises the `lane` retirement to **all**
> of these, introducing a **non-transition annotation event class** (`shell_refresh`
> / `subtask_marked` / `activity_note`) alongside the transition ledger so the
> 9-lane FSM stays unchanged. After it lands, `WP##.md` holds only static intent
> and hashes stably across every runtime mutation. See
> [ADR 2026-07-16-1](/adr/3.x/2026-07-16-1-wp-runtime-state-authority-event-log-eviction.md)
> and the [eviction design](/architecture/wp-runtime-state-eviction.md).

## Known limitations

- **One reducer, ordered by wall clock.** `status.reducer.reduce` calls
  `spec_kitty_events.diary.reduce_parsed` directly (`status/reducer.py:205`), and
  `materialize_snapshot` calls `reduce_shared_state` (`:401`), which is
  `spec_kitty_events.status.reduce`, a re-export of `diary.reduce` (`parse_diary`, then
  `reduce_parsed`). Lane transitions are ordered by the writer's `at`, then `event_id`;
  CLI lane rows carry no Lamport clock, and the Lamport reducer
  `reduce_status_events` is not on the CLI path. So the CLI does not implement the
  Lamport-primary order of ADR
  [`2026-02-09-3`](/adr/2.x/2026-02-09-3-event-log-merge-semantics.md). 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
  `approved` sorts after the approval it followed). A non-approval transition minted on a
  clock behind the event it follows still sorts before that event.

## CLI Commands

All status commands live under `spec-kitty agent status`.

### `spec-kitty agent status emit`

Record a lane transition event for a work package.

```bash
# Move WP01 to claimed (assigns to an actor)
spec-kitty agent status emit WP01 --to claimed --actor claude

# Move WP01 to in_progress (begin implementation)
spec-kitty agent status emit WP01 --to in_progress --actor claude

# "doing" is accepted as an alias for "in_progress"
spec-kitty agent status emit WP01 --to doing --actor claude

# Move to for_review (submit for review)
spec-kitty agent status emit WP01 --to for_review --actor claude

# Move to done with reviewer evidence (required unless forced)
spec-kitty agent status emit WP01 --to done --actor claude \
  --evidence-json '{"review": {"reviewer": "alice", "verdict": "approved", "reference": "PR#42"}}'

# Return from review to in_progress (changes requested -- requires review_ref)
spec-kitty agent status emit WP01 --to in_progress --actor reviewer \
  --review-ref "PR#42-comment-7"

# Force a transition that bypasses guard conditions (requires actor + reason)
spec-kitty agent status emit WP01 --to in_progress --actor admin \
  --force --reason "Reopening after incorrectly marked done"

# Block a work package
spec-kitty agent status emit WP01 --to blocked --actor claude \
  --reason "Waiting on upstream dependency"

# Machine-readable JSON output
spec-kitty agent status emit WP01 --to claimed --actor claude --json
```

**Options**:

| Option | Required | Description |
|--------|----------|-------------|
| `WP_ID` (argument) | Yes | work package ID (e.g., `WP01`) |
| `--to` | Yes | Target lane (canonical or alias) |
| `--actor` | Yes | Who is making this transition: a tool name (`claude`) or the compact `tool:model:profile` form. The event stores the structured actor (see [The actor](#the-actor)); the command output echoes the value as given |
| `--mission` | No | Mission slug |
| `--force` | No | Bypass guard conditions |
| `--reason` | When `--force` | Reason for forced transition |
| `--evidence-json` | When `--to done` | JSON string with DoneEvidence |
| `--review-ref` | When `for_review -> in_progress` | Review feedback reference |
| `--execution-mode` | No | `worktree` (default) or `direct_repo` |
| `--json` | No | Machine-readable JSON output |

On a coordination-routed Mission the write can be refused with
`COORD_STATUS_SURFACE_DIVERGED` or `COORD_STATUS_SURFACE_UNREADABLE`; see
[Coordination status-write guard](#coordination-status-write-guard).

### `spec-kitty agent status materialize`

Rebuild `status.json` from the canonical event log.

```bash
# Rebuild snapshot (auto-detects mission)
spec-kitty agent status materialize

# Specify mission explicitly
spec-kitty agent status materialize --mission 034-feature-name

# JSON output (full snapshot)
spec-kitty agent status materialize --mission 034-feature-name --json
```

**When to use**: After manual edits to `status.events.jsonl`, after resolving merge conflicts in the event log, or after running `status validate` reports materialization drift.

### `spec-kitty agent status validate`

Check event log integrity, transition legality, done-evidence completeness, and drift detection.

```bash
# Validate event log for a mission
spec-kitty agent status validate --mission 034-feature-name

# JSON output for CI integration
spec-kitty agent status validate --mission 034-feature-name --json
```

**Checks performed**:
1. **Schema validation**: All required fields present, ULID format, canonical lane values, ISO 8601 timestamps
2. **Transition legality**: Every `(from_lane, to_lane)` pair is in the allowed transitions set (force transitions are always legal)
3. **Done-evidence completeness**: Every done transition has evidence or force flag
4. **Materialization drift**: Compares `status.json` on disk with reducer output from event log
5. **Derived-view drift**: Compares materialized `status.json` against canonical event log (error if diverged)

### `spec-kitty agent status reconcile`

Scan target repositories for WP-linked branches and commits, detect planning-vs-implementation drift, and optionally emit reconciliation events.

```bash
# Preview reconciliation suggestions (dry-run is the default)
spec-kitty agent status reconcile --mission 034-feature-name --dry-run

# Scan a specific target repository
spec-kitty agent status reconcile --mission 034-feature-name \
  --target-repo /path/to/implementation-repo --dry-run

# Apply reconciliation events (2.x only; disabled on 0.1x)
spec-kitty agent status reconcile --mission 034-feature-name --apply
```

**How it works**:
1. Scans target repos for branches matching `*<feature-slug>*WP##*`
2. Scans commit messages containing `WP##`
3. Checks which lane or mission branches are merged into the target branch
4. Compares implementation evidence against canonical snapshot state
5. Generates legal transition events to align planning with reality

**Limitations on 0.1x**: `--apply` is disabled. Reconciliation is dry-run only.

### `spec-kitty agent status doctor`

Run health checks detecting stale claims, orphan workspaces, and unresolved drift.

```bash
# Run all health checks for a mission
spec-kitty agent status doctor --mission 034-feature-name
```

**Health checks**:

| Check | Severity | Description |
|-------|----------|-------------|
| Event-log read failure | Error | Corrupt or unreadable `status.events.jsonl`, regardless of snapshot presence |
| Stale claims | Warning | WPs in `claimed` for >7 days or `in_progress` for >14 days |
| Orphan workspaces | Warning | Worktrees existing for features where all WPs are terminal (done/canceled) |
| Materialization drift | Warning | `status.json` does not match reducer output |
| Derived-view drift | Error | Materialized snapshot differs from canonical event log |

Doctor reads the canonical event log before trusting `status.json`. If the log is corrupt or unreadable it reports `event_log_error` (ERROR, exit 1, JSON `healthy: false`) 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.

### `spec-kitty agent status migrate`

Bootstrap canonical event logs from existing frontmatter lane state.

```bash
# Preview migration for a single feature
spec-kitty agent status migrate --mission 034-feature-name --dry-run

# Execute migration for a single feature
spec-kitty agent status migrate --mission 034-feature-name

# Migrate all features
spec-kitty agent status migrate --all

# Preview all migrations
spec-kitty agent status migrate --all --dry-run
```

**Migration behavior** (for pre-3.0 missions):
- Reads current frontmatter `lane` values from all WP files in the feature
- Resolves aliases (`doing` -> `in_progress`) before creating events
- Generates one bootstrap event per WP: `from_lane=planned, to_lane=<current_lane>`
- WPs already at `planned` produce no events (no transition occurred)
- Idempotent: features with existing non-empty `status.events.jsonl` are skipped
- Verification: reads back persisted events and confirms count matches

**For new missions (3.0+)**: `finalize-tasks` bootstraps WP definitions. All subsequent status transitions are validated once in the status-owned `transition_pipeline` and appended to the event log by one of its two shells — the flat/primary `emit_status_transition()` or the transactional shell in `coordination/status_transition.py`. No frontmatter lane is written.

### Legacy Compatibility

The existing `move-task` command still works and internally delegates to the status emit pipeline:

```bash
# This still works -- delegates to status emit internally
spec-kitty agent tasks move-task WP01 --to doing
# "doing" is accepted as alias, persists as "in_progress" in the event log
```

## Subtask completion ownership (`agent tasks mark-status`)

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:

1. the authored `subtasks:` list in the work package's `tasks/<WP>.md` frontmatter
   (static design intent), and
2. a **structured** `tasks.md` row that names the id — a `- [ ]`/`- [x]` checkbox row,
   a pipe-table row (owner from its WP column, else the enclosing heading), or an
   inline `Subtasks: T001, T002` list under a work-package heading. A prose mention
   never claims an id. Ids compare case-insensitively in both sources.

The owners of an id are the union of those two sources. An id more than one work
package claims is *shared*, and `mark-status` refuses it rather than picking one:

```bash
# refused: names WP01 and WP02, writes nothing
spec-kitty agent tasks mark-status T001 --status done
# scoped: records completion on WP02 only
spec-kitty agent tasks mark-status T001 --status done --wp WP02
```

A `WP<digits>` id is a lane, not a subtask: `mark-status WP01` is refused with the
`move-task` remedy, even when the id also appears in a `tasks.md` index table. If a
work package genuinely authors a subtask with a work-package-shaped id, `--wp <owner>`
is required, because the bare id reads two ways.

The completion annotation's `wp_id` 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.

## 9-Lane State Machine

### Canonical Lanes

| Lane | Description | Terminal |
|------|-------------|----------|
| `planned` | WP defined, not yet claimed | No |
| `claimed` | WP assigned to an actor, not yet started | No |
| `in_progress` | Active implementation underway | No |
| `for_review` | Implementation complete, awaiting review | No |
| `in_review` | Reviewer actively examining implementation | No |
| `approved` | Review passed, awaiting merge | No |
| `done` | Merged/integrated into the mission target branch | Yes (unless forced) |
| `blocked` | Blocked by external dependency or issue | No |
| `canceled` | Permanently abandoned | Yes |

**Alias**: `doing` -> `in_progress` (resolved at input boundaries, never persisted in events)

**Display**: The kanban board shows 6 columns (Planned, Doing, For Review, In Review, Approved, Done). `planned` WPs appear in Planned; `claimed` and `in_progress` appear in Doing, with `claimed` still preserved as a distinct canonical lane for ownership/stale-claim diagnostics. `blocked`/`canceled` WPs are shown separately below the board.

### Allowed Transitions (27 pairs)

```
# Normal flow (implementation progression)
planned     -> claimed         (requires actor)
claimed     -> in_progress     (workspace context)
in_progress -> for_review      (subtasks check)

# Review progression
for_review  -> in_review       (reviewer claims; actor required with conflict detection)
in_review   -> approved        (ReviewResult required)
in_review   -> done            (ReviewResult required)

# Direct approval paths (legacy, kept for backward compat)
in_progress -> approved        (direct approval path)
approved    -> done            (merge verified)

# Feedback loops
in_review   -> in_progress     (changes requested, ReviewResult required)
in_review   -> planned         (rejection with feedback, ReviewResult required)
approved    -> in_progress     (rework after approval, requires review_ref)
approved    -> planned         (rejection after approval, requires review_ref)
in_progress -> planned         (abandon/reassign, requires reason)

# Blocking
planned     -> blocked
claimed     -> blocked
in_progress -> blocked
for_review  -> blocked
in_review   -> blocked         (ReviewResult required)
approved    -> blocked
blocked     -> in_progress

# Cancellation
planned     -> canceled
claimed     -> canceled
in_progress -> canceled
for_review  -> canceled
in_review   -> canceled        (ReviewResult required)
approved    -> canceled
blocked     -> canceled
```

**Force override**: Any transition can be forced with `--force --actor <name> --reason <text>`. 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 `in_progress` from `for_review`, `in_review` or `approved` must carry a `review_ref` whether or not it is forced — see [Forced rewinds out of review](#forced-rewinds-out-of-review).

### Guard Conditions

| Transition | Guard | Error if Violated |
|------------|-------|-------------------|
| `planned -> claimed` | Actor identity required | "Transition planned -> claimed requires actor identity" |
| `claimed -> in_progress` | Workspace context (placeholder, always passes) | "No workspace context" |
| `in_progress -> for_review` | Subtask completion check (placeholder) | "Unchecked subtasks" |
| `in_progress -> approved` | Reviewer approval evidence required | "Missing review approval evidence" |
| `for_review -> in_review` | Actor identity required (conflict detection) | "Transition for_review -> in_review requires actor identity" |
| `in_review -> *` (all outbound) | ReviewResult required in TransitionContext | "in_review outbound transitions require ReviewResult" |
| `approved -> done` | Merge/integration evidence required | "Missing merge evidence" |
| `approved -> in_progress` | Review feedback reference required | "Missing review feedback reference" |
| `approved -> planned` | Review feedback reference required | "Missing review feedback reference" |
| `in_progress -> planned` | Reason required | "Transition in_progress -> planned requires reason" |
| `in_review -> in_progress` | `review_ref` required (rail: the status emit path derives it from `review_result.reference` when no `--review-ref` was given) | a forced rewind without one: "Transition in_review -> in_progress requires review_ref: ..."; an unforced one is refused by the `in_review` review_result guard |
| `for_review -> in_progress` (forced) | `review_ref` required — force does **not** override it | "Transition for_review -> in_progress requires review_ref: ..." |
| `approved -> in_progress` (forced) | `review_ref` required — force does **not** override it | "Transition approved -> in_progress requires review_ref: ..." |
| Any forced transition | Actor AND reason required | "Force transitions require actor and reason" |

### Forced rewinds out of review

`for_review` has no backward edge in the lane graph, so `for_review -> in_progress` is
reachable **only** by force. That makes the force gate the only gate on the edge, and a
force carrying nothing but `--reason` used to append a
`for_review -> in_progress` event with `review_ref: null` — an event `status validate`
refuses (`for_review->in_progress without review_ref`). 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.

The `approved -> in_progress` reopen had the same defect on its forced arm (#6955): without a
`--review-feedback-file` the row recorded `force: true` and `review_ref: null`, which the
shared wire contract the sync consumer enforces rejects, so the reopen never propagated even
though the local ledger accepted it.

The requirement is therefore **force-insurmountable**. `--force --reason` 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.

| Writer | Supplies the pointer how |
|---|---|
| `spec-kitty agent status emit --to in_progress` | the caller's `--review-ref <ref>`, or — since #7080 — the `reference` of the structured `--review-result-json` outcome; a request with neither is refused |
| `spec-kitty orchestrator-api transition --to in_progress` | the same two: `--review-ref <ref>` or the structured review result's `reference` |
| `spec-kitty agent tasks move-task --to in_progress` | the supplied review-feedback file, `force-override` (the command's own sentinel for an operator rewind, set for both the explicit `--force` form and the auto-promoted backward move, and since #6955 for the forced `approved -> in_progress` reopen), or the structured review result's `reference` |
| `spec-kitty agent action implement` (implementer of record or `--force --note` withdrawal) | `force-override`, the same sentinel |

A supplied `--review-feedback-file` on the `approved` reopen always wins over the sentinel:
the row records the file path, and the move is force-free unless the caller explicitly
passed `--force` (the reopen is still not a rejected verdict and mints no rejection review
cycle). `force-override` 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.

The generic doors (`agent status emit`, `orchestrator-api`, the batch and coordination
shells) get the derivation from `status/transition_pipeline.py::prepare_transition`, the
validation/event-build function they all go through; `move-task` keeps its own copy in
`build_transition_plan`, 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 **absent** pointer only: a caller's `--review-ref` is
recorded unchanged, a pointer that disagrees with `review_result.reference` 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.

The edge set (`REVIEW_REF_REQUIRED_EDGES`) holds the edges whose persisted events the
shared `spec_kitty_events` contract gates on `review_ref`: `for_review -> in_progress`
(#6514), `approved -> in_progress` (#6955) and `in_review -> in_progress` (#7080). A
`migration:` 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
`approved -> planned` rewind is likewise outside this family: the sentinel fill follows the
edge set and the evidence-gated reopen arm covers only `in_progress`, so that row still
records `force: true` with `review_ref: null` — a forced rewind out of review does not by
itself imply a pointer.

A refused command exits non-zero, names `review_ref` and `--review-ref`, and writes nothing:
`status.events.jsonl` and `status.json` are byte-identical afterwards, and
`status validate` still passes. The rule is evaluated during validation, before the
lock-protected append, the snapshot materialization and the frontmatter mirror.

**Rows written before this refusal.** 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 `for_review -> in_progress` row written before #6514 and every
pointerless `approved -> in_progress` row written before #6955 and every pointerless
`in_review -> in_progress` row written before #7080.
`spec-kitty agent status validate --mission <slug> --json` names each offending
`event_id`, 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 `status.events.jsonl`; the materialized `status.json` is derived and would
diverge.

## Migration Phases

The status model used a phased rollout. As of 3.0, **Phase 2 is the active and only supported model**. Phases 0 and 1 are historical and no longer apply to new missions.

| Phase | Name | Behavior | Status |
|-------|------|----------|--------|
| 0 | Hardening | Transition matrix enforced, no event log. Frontmatter was sole authority. | **Historical** |
| 1 | Dual-write | Events AND frontmatter updated on every transition. Reads came from frontmatter. | **Historical** |
| 2 | Read-cutover | `status.events.jsonl` is sole authority. `status.json` is derived snapshot. | **Active** |

**Default**: Phase 2 (event-log authority). Frontmatter lane is no longer written or read by active runtime commands.

### Configuration

**Global default** (`.kittify/config.yaml`):

```yaml
status:
  phase: 1  # 0=hardening, 1=dual-write, 2=read-cutover
```

**Per-feature override** (`kitty-specs/<feature>/meta.json`):

```json
{
  "status_phase": 2
}
```

**Precedence**: meta.json > config.yaml > built-in default (1)

**On 0.1x branches**: Phase is capped at 2 (maximum). Reconcile `--apply` is disabled.

### Migration Workflow

To migrate existing features to the canonical event log:

1. **Preview**: Run `spec-kitty agent status migrate --all --dry-run` to see what would happen
2. **Execute**: Run `spec-kitty agent status migrate --all` to bootstrap event logs from frontmatter
3. **Verify**: Run `spec-kitty agent status validate --mission <slug>` for each mission to confirm integrity
4. **Optionally advance to Phase 2**: Set `status.phase: 2` in config.yaml or per-feature in meta.json

## Canonical Event Log Format

Events are stored in `kitty-specs/<feature>/status.events.jsonl` as one JSON object per line:

```json
{"actor":{"model":null,"profile":null,"role":"implementer","tool":"claude"},"at":"2026-02-08T12:00:00+00:00","event_id":"01HXYZ...","evidence":null,"execution_mode":"worktree","mission_slug":"034-feature-name","force":false,"from_lane":"planned","reason":null,"review_ref":null,"to_lane":"claimed","wp_id":"WP01"}
```

Keys are always sorted (`sort_keys=True`) for deterministic, merge-friendly output.

### The actor

The `actor` 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):

| Key | Value |
|-----|-------|
| `tool` | The agent handle, for example `claude` or `codex`. Only the bare tool: a compact `--agent`/`--actor` value such as `claude:opus:python-pedro` contributes `claude` here. `user` when an operator names no agent (`mark-status` without `--agent`); for a system write, the identity that writer records (see [System writes](#system-writes)). |
| `role` | `implementer`, `reviewer` or `system`, set by the action (see below), never by the profile. |
| `profile` | The agent profile, or `null`. |
| `model` | The model, or `null`. |

These commands write it: `agent tasks move-task` (every hop and its paired
note), `agent tasks mark-status` (which takes an optional `--agent`),
`agent tasks add-history`, `agent action implement` and `agent action review`
(their transitions and annotations), the review verdict note,
`agent status emit` and the `orchestrator-api` lifecycle commands
(`start-implementation`, `start-review`, `transition`, `append-history`).
The `orchestrator-api` JSON envelopes do not change; only the stored event does.
The system writers listed under [System writes](#system-writes) write the same
four keys, with `role: "system"`.

**Profile.** `profile` (and `model`) come from, in this order: the dispatch
invocation (`--invocation-id`), then `--profile`, then the profile (and model)
segment of a compact `--agent`/`--actor` value. When none of these gives one,
the value is `null`. Nothing is guessed, and the planned `agent_profile` in the
WP frontmatter is not copied in.

**Role.** `reviewer` for a hop into `in_review`, `approved` or `done`, for any
hop that leaves `in_review` (a rejection, a block or a cancel during review)
and for a review verdict note. `implementer` for every other hop, for
implementer notes and for subtask marks. `system` 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 `tool`; see [System writes](#system-writes));
an agent role is never derived from a lane hop for a system write, and a system
write never gains `implementer` or `reviewer`.

**Display and identity.** The board, the snapshot `actor` slot and the claim
check still use the bare tool (`actor_identity_str`), so a structured actor and
a bare-string actor naming the same tool are the same agent.

**What readers accept.** 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 `profile_source`. 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.

**System writes.** A write the program makes on its own initiative or on the
operator's behalf records the same four keys with `role: "system"`:

| Writer | `tool` |
|--------|--------|
| the `finalize-tasks` bootstrap seed | `finalize-tasks` |
| a lane recovery catch-up | `recovery` |
| the consolidation approval replay and done mark, and the done-write refusal probe (a dry request that is never persisted) | `merge` |
| the `--skip-review-artifact-check` override annotation | the resolved operator identity |
| `--attest-approved-reviewed` and `--attest-canceled-superseded` | the resolved operator identity |
| `migrate backfill-wp-status`, `backfill-runtime-state` and `verdict-provenance` seeds | `migration:<id>` |

`profile` and `model` are always `null` for a system write: there is no dispatch
binding, and nothing is filled in from a plan or a default. `tool` carries the
identity the writer already recorded, whole — a `migration:<id>` seed identity is
never split into a tool and a model, which is what keeps it a seed.

Seed classification is unchanged and shape-blind: `is_migration_actor` (and so
the reducer's seed arm, the timestamp-continuity exemption and the consolidation
work-window rule) projects a structured actor to its `tool`, 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 `policy_metadata.attestation`, never
by its `role`.

**Who may write a seed.** A `migration:` 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). `agent status emit --actor`, the four
`orchestrator-api` lifecycle verbs (`start-implementation`, `start-review`,
`transition`, `append-history`, refused as `USAGE_ERROR`) and the hidden
`implement --actor` refuse a caller-supplied identity that starts with
`migration:`, exit non-zero and write nothing; the value is never rewritten into
a live-looking actor. An explicit `--agent migration:x` is **not** refused: it is
read as the compact `tool:model:profile` form, so its tool is `migration` and it
is not a seed. A `migration:` identity already recorded keeps its seed status
when a later command re-records it with no caller option.

> **Planned (follow-up #6721).** A later release adds `profile_source` (where the
> profile came from) to the written actor and fills `profile` 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.

## Commit attribution stamp (`policy_metadata.lane_head`)

Every persisted lifecycle transition of a WP mapped to a non-planning
execution lane whose branch exists is stamped, best-effort, with
`policy_metadata["lane_head"]` -- that lane branch's `git rev-parse` HEAD sha
at the moment the transition is written. Both status shells inject the same
probe (`specify_cli.status.lane_head.read_lane_head`): the flat/primary
shell (`status.emit.emit_status_transition`) and the coordination
transactional shell (`coordination.status_transition.
emit_status_transition_transactional`). The stamp is a local, free-form
sidecar on `StatusEvent.policy_metadata` -- it does not change the
`spec_kitty_events` schema.

**Best-effort, never blocking.** The probe never raises and never refuses a
transition: no `lanes.json`, an unassigned WP, a planning lane, or a missing
lane branch all resolve to "no stamp" (`policy_metadata` 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.

**Read only by the consolidation reconciliation gate, and only for mixed
lanes.** A *mixed lane* 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
`lane_head` stamps (the SHA an *opening* transition -- `claimed`/
`in_progress` -- and a *closing* transition -- `for_review`/cancel --
carried), bounding exactly which lane commits belong to which WP's work
sessions. Events synthesized by a migration (actor `migration:...`, 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.

**Verdict rules (summary).** 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:

| Verdict | When | Effect and recovery |
|---|---|---|
| PASS | 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 | Consolidation proceeds |
| FAIL | A canceled WP's content (an addition, a modification, or a deletion) is still present on the target, unsuperseded | 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. **Not overridable.** |
| FAIL (`CANCELED_REACHABLE_VIA_DEPENDENCY`) | 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 | 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. **Not overridable.** |
| FAIL (`APPROVED_CONTENT_MISSING`) | 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 | 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. **Not overridable.** |
| REFUSE (attribution evidence) | 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 | 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 `--attest-canceled-superseded <WP> --attest-reason "<what you checked>"` |
| REFUSE (closed world) | 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 | 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 |
| REFUSE (merged with an independent change) | The target is neither the canceled state, its pre-state, nor the window base's state | Target restored. Recovery: supersede through a surviving WP and re-run, or attest after verifying by hand |
| REFUSE (infrastructure) | The status event log or the lane's git history cannot be read | Target restored. Repair the log or history and re-run. **Not overridable.** |

"Target restored" in this table is the minimum: every FAIL/REFUSE (and every
squash-projection refusal) also runs the single rollback authority
(`consolidation/rollback.py`), 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 `2026-09-19-1`, Amendment 2026-09-29; #5338, #5318).

REFUSE takes precedence over FAIL: an attribution failure is always reported
as missing evidence, never silently downgraded to (or masked by) a content
verdict.

**Operator-attested override (FR-012).** `spec-kitty consolidate
--attest-canceled-superseded <WP> --attest-reason "<text>"` (the WP id is
repeatable; the reason is required) records, through the canonical status
write seam, a forced `canceled -> canceled` transition of that canceled WP
carrying the actor, the reason, the timestamp, `reason_source: operator` and
`policy_metadata.attestation: canceled_superseded`. 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
`lane_head` 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 `LANE_MOVED_AFTER_APPROVAL` (ADR
[2026-10-04-5](/adr/4.x/2026-10-04-5-approval-stamp-bounds-the-approved-claim.md)). Every explicit `--attest-canceled-superseded` 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. `--dry-run`
records nothing and says so. The attestation's `policy_metadata` key also counts
as event-log runtime evidence for the birth cutover
(`status/cutover_eligibility.py`), like any key other than `lane_head`. See ADR
[2026-09-29-1](/adr/3.x/2026-09-29-1-closed-world-refuse-on-mixed-lanes.md).

**Known, accepted residuals.** 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:

- content that a separate approved lane independently authored under the
  identical path and bytes can still FAIL;
- 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.

Two of them can let canceled or unowned content reach the target under a PASS:

- a survivor's rework that only partially overwrites a canceled WP's change
  marks the whole path superseded, so the kept hunks ship;
- an out-of-workflow commit made on the lane before the first governed claim
  is exempt via the first-claim anchor;

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 `planned`/`blocked` and none ever moved
into any other lane than `planned`, `blocked` or `canceled`, 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 `CANCELED_REACHABLE_VIA_DEPENDENCY`, and a
canceled dependency WP without a `lane_head` 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.

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.

## Mission write lock and rollback

Several agents can write one Mission checkout at once (#5819). Two rules keep their writes apart.

**One lock per Mission, one key.** Every writer of a Mission's status files and shared planning files takes `<git common dir>/spec-kitty-locks/<Mission directory name>.status.lock`. The key is computed by the pure, git-free `mission_lock_key(feature_dir)`: when the Mission is coordination-routed (a `coordination_branch` 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 `060-test` primary directory and its `060-test-<mid8>` 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 `coordination_branch` or `mid8` inside the hold never takes a second, different lock. The decisions lock (`decisions/index.json.lock`) 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 `status/mission_write.py`: `mission_write_lock(feature_dir)` (re-entrant per thread; bounded wait by default, while the `agent action implement` / `review` claim windows and `implement`'s claim hold wait without a limit), `locked_rewrite_text(path, transform, feature_dir=...)` (read, transform and atomic write under the lock), `capture_rollback_point`, `rollback_events_log` and `rollback_status_artifacts`. Non-status writers resolve the directory with `mission_write_lock_dir` (`missions/_read_path_resolver.py`).

**Locked helpers for `meta.json` and frontmatter.** 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. `locked_update_meta(feature_dir, mutate, ...)` (`mission_metadata`) takes the lock, re-reads `meta.json`, applies the mutation and writes atomically; every `meta.json` setter uses it. `locked_update_frontmatter(wp_path, mutate, *, feature_dir, ...)` (`frontmatter`) does the same for a work package's frontmatter, so `map-requirements` and the `finalize-tasks` 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.

**Rollback is verified.** `capture_rollback_point` records the log size and `status.json` 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 `HEAD`. 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 `HEAD` cannot be read (including a committed log that holds a non-JSON line). A refusal leaves the files unchanged and reports `STATUS_ROLLBACK_REFUSED` with the reason and a `git diff HEAD -- <log>` command naming the log it checked (on a coordination Mission, the coordination worktree's log); `agent action` prints it, and the coordination fallback appends it to the commit error it re-raises. The exception is a tail already committed at `HEAD` (always so on a coordination Mission): `agent action implement` / `review` then print `<WP> claim was committed; the follow-up <operation> commit failed: <error>`, 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 `status.events.jsonl`.

**Checkout claim lock.** On `single_branch` the write checkout has one occupant. `write_checkout_claim_lock(write_checkout)` (`status/locking.py`, beside `feature_status_lock`) 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 `RuntimeError` 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: `agent action implement`, `implement` and the orchestrator API `start-implementation` report it as `STATUS_LOCK_HELD` (the API as an envelope, the CLI as a printed code with exit 1). `agent action implement` and `agent action review` also warn, without refusing, when `shared_workspace_writers` (`lanes/checkout_occupancy.py`) finds another actor's work package active in the same checkout.

**Gate.** `tests/architectural/test_mission_write_discipline.py` 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 (`open(..., "w")`, `write_text`, `write_bytes`) 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 **Rule 4** — a write to `meta.json`, a `tasks/WP*.md` frontmatter file or `tasks.md` that sits outside a lock region and does not go through a registered locked helper. A lock region is a lexical `with` of a lock context manager (and its `ExitStack` / assigned-name forms); the status-core regions (`BookkeepingTransaction` and the emit lock) are recognised structurally, and migrations get no exemption — they write through the helpers.

## File Layout (per feature)

```
kitty-specs/<feature>/
  status.events.jsonl    # CANONICAL: append-only event log
  status.json            # DERIVED: materialized snapshot (regenerable)
  meta.json              # Mission metadata (includes optional status_phase)
  tasks/
    WP01-name.md         # DERIVED: frontmatter lane is compatibility view
    WP02-name.md
  tasks.md               # DERIVED: status sections from snapshot
```

**Authority hierarchy**:
1. `status.events.jsonl` -- canonical truth (append-only, immutable events)
2. `status.json` -- derived snapshot (regenerable via `status materialize`)
3. WP frontmatter -- static definition only (title, dependencies, subtasks); `lane` field is historical/migration-only
4. `tasks.md` status sections -- human view (regenerable)

## Troubleshooting

**"Illegal transition" error**: The transition is not in the allowed transitions matrix. Use `--force --actor <name> --reason <text>` to override, or check that the from_lane matches what you expect (run `status materialize --json` to see current state).

**Materialization drift detected**: Run `spec-kitty agent status materialize` to regenerate `status.json` from the event log.

**Frontmatter lane drift** (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 `spec-kitty agent status migrate --mission <slug>` to bootstrap the event log, then status is managed exclusively via events.

**"No event log found"**: Run `spec-kitty agent status migrate --mission <slug>` to bootstrap from existing frontmatter state.

**Stale claims reported by doctor**: Either continue work on the WP or release the claim by moving it back to `planned` (requires reason).

### Coordination status-write guard

On a Mission with a coordination topology, a status write (`agent status
emit`, `agent tasks move-task`, and any other command that records a lane
transition) is committed from the coordination worktree. Before a write that
goes through the status transaction (`BookkeepingTransaction.acquire`) 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:

| Code | Condition | Recovery |
|---|---|---|
| `COORD_STATUS_SURFACE_DIVERGED` | The worktree's `status.events.jsonl` 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 | The message names up to three of the missing event ids and offers two remedies. `spec-kitty doctor coordination --fix --mission <slug>` reverts the stranded `done`, so the Mission is no longer recorded as done; `spec-kitty consolidate --resume --mission <slug>` does the same heal and then completes the consolidation. Always pass `--mission`: without it `doctor coordination --fix` acts on every Mission and flattens those with a stale `coordination_branch`. `git -C <coordination worktree> checkout HEAD -- <mission dir>/status.events.jsonl <mission dir>/status.json` keeps the committed events and discards only the stale working-tree bytes; once a later status write lands on top of them, `consolidate --resume` and `doctor coordination --fix` 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 |
| `COORD_STATUS_SURFACE_UNREADABLE` | 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 | Repair the committed log or the checkout, then retry. The message names the reason |

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 [agent subcommand reference](/api/agent-subcommands.md#coordination-status-writes-refusal-on-a-diverged-status-log).

The guard does not cover every writer. The fallback coordination arm
(`_emit_on_coord_then_commit` in `coordination/status_transition.py`) and the
writers that append raw decision and retrospective rows (`append_raw_rows_atomic`)
do not pass through the status transaction, so they do not run this check
(#5644).

### Pre-3.0 layout rejection

Active `spec-kitty` commands (task, status, acceptance) require a post-3.0
project layout — flat `tasks/WP*.md` files and `status.events.jsonl` as the
status source of truth. Commands that encounter a pre-3.0 lane-directory layout
(`tasks/planned/`, `tasks/doing/`, `tasks/for_review/`, `tasks/done/`
containing `.md` files) will refuse to proceed:

```
Pre-3.0 layout detected (tasks/planned/ directories or frontmatter lane state).
Run `spec-kitty upgrade` to migrate before continuing.
```

**Migration path**: Run `spec-kitty upgrade` (or
`spec-kitty upgrade --migration 0.9.0_frontmatter_only_lanes`) to move WP
files from lane subdirectories to flat `tasks/`. After upgrade, all active
commands will work normally.

The `lane` frontmatter field is historical/migration-only and is not written
or read by any active command. Status is tracked exclusively through
`status.events.jsonl`.

## Related

- [Migration: Mission ID as Canonical Identity](/migrations/mission-id-canonical-identity.md)

## Audience

- [Stakeholder Persona: System Architect](/context/audience/internal/system-architect.md) - Written for the System Architect reader.
