--- status: draft created: 2026-08-12 owner: nova28 --- # Task step transition ledger ## Why Kandev records *when a card was worked on* but not *which workflow step it was in at the time*. Cost, token, and duration events can be joined to a task and a session, but attributing them to a step requires reconstructing step boundaries from the message timeline. On the reference store that reconstruction leaves **47.0%** of spend cleanly inside one step, **30.5%** merely "dominant of two steps in the window", and **22.5%** unattributable — so "what does Review cost" cannot be answered without a caveat larger than the answer. The one table that looks like it should answer this, `session_step_history`, is keyed by **session** while Kandev tracks step state on the **task** (`base_migrations.go` removed `task_sessions.workflow_step_id` for exactly that reason). A card can change step with no active session, or with several, so attributing a task-level transition to one session manufactures ownership that does not exist. ## What this feature is, and is not **It is a forward-looking record of step boundaries.** From its activation point onward, every durable change to a task's workflow step is recorded with its timestamp, its cause, and its actor, so downstream analysis can bound a step interval from data rather than infer it from chat. **It cannot repair the past.** No historical transition is reconstructed or backfilled. Rows before the activation point do not exist and MUST NOT be synthesised. **It does not make per-step cost exact.** Cost events bill windows that cross step boundaries; better boundaries improve attribution but do not decide how one window's cost divides between two steps. The "dominant of two steps" bucket shrinks; it does not disappear. **It is not `workflow_step_decisions`.** That table has a live writer on the Office approval path; its zero rows mean an unused feature, not a missing one. The two mechanisms MUST NOT be merged. **It is not a replacement for `session_step_history`.** This spec neither wires, removes, nor changes that table or the `GET /api/v1/sessions/:id/workflow/history` endpoint that reads it. See *Relationship to `session_step_history`*. ## What The feature ships as two independently valuable slices. **Slice 1 SHALL ship and be measured before Slice 2 is built** (see *Gate between slices*). ### Slice 1 — turn-start step stamp - A turn created for a session records the workflow step its task was in at the moment the turn started. - The stamp is present on every turn created after activation whose task has a workflow step, and **absent** — never empty, never `0` — when the task has none. - The stamp is immutable once written. A step change during the turn does not rewrite it. - No column is added to `task_session_turns`. ### Slice 2 — task-level transition ledger - Every committed change to a task's workflow step produces exactly one ledger row, written in the same database transaction as the change. - A row that is not committed with its transition does not exist: a rolled-back or WIP-rejected move leaves no row. - A move that does not change the step (position-only reorder, re-issued move to the current step) produces **no** row. - Each row names the task, the step it left and the step it entered, when, why (trigger), what kind of actor caused it, and that actor's **identifier** — never a display name. - The initiating session is recorded when one exists and is genuinely the initiator; it is `NULL` otherwise. A transition with no session, or with several candidate sessions and no single initiator, MUST record `NULL` rather than pick one. - Each row carries the collection-contract version it was written under. ### Cross-cutting - Legacy rows and unstamped turns get `NULL` / absent — **never `0`, never `""`**. - Both slices publish a machine-readable activation point, because the downstream extract is a point-in-time snapshot with no schema versioning: a column whose meaning changes mid-series is silently discontinuous. - Both writers are observable at runtime, and the set of code paths that may mutate a task's workflow step is pinned by a test (see *Writer health*). ## Data model ### `task_step_transitions` (new) ``` task_step_transitions id int64 PK, monotonic per install (SQLite AUTOINCREMENT / Postgres BIGSERIAL) task_id string FK -> tasks.id ON DELETE CASCADE session_id string FK -> task_sessions.id ON DELETE SET NULL, nullable — the initiating session, when one exists from_workflow_id string nullable — NULL only on the genesis row from_workflow_step_id string nullable — NULL on genesis, and when the task held no step (detached from a workflow) to_workflow_id string nullable — NULL when the task is detached to_workflow_step_id string nullable — NULL when the task is detached trigger enum see Trigger below, NOT NULL actor_kind enum see Actor kind below, NOT NULL actor_id string nullable — an opaque identifier, never a name contract_version int NOT NULL, starts at 1 occurred_at timestamp NOT NULL, UTC ``` Indexes: `(task_id, occurred_at, id)` for interval reconstruction; `(occurred_at)` for extract windowing. `from_*` and `to_*` are never both NULL — a row with neither side would record nothing. `from_workflow_step_id` equals `to_workflow_step_id` on no row; that combination is the no-op case, which writes nothing. **Empty string normalizes to NULL.** `tasks.workflow_step_id` uses `''` for "no step" and `tasks.workflow_id` likewise. The ledger stores `NULL`, never `''`, for the same condition, in both the `from_*` and `to_*` pairs. A consumer that sees `''` in this table is looking at a bug. **There is deliberately no foreign key to `workflow_steps` or `workflows`.** Steps and workflows are deleted; the historical fact that a card was in a now-deleted step must survive that deletion. Consumers MUST tolerate a step ID with no matching row. **Trigger** — why the step changed. Unrecognised or unattributable causes use `unknown`; the enum is closed and new causes are added to it deliberately. | Value | Meaning | |---|---| | `task_created` | The genesis row: the task was created into a step. | | `manual_move` | A user moved the card (HTTP/WS move, drag, board action). | | `task_update` | A task update changed `workflow_step_id` without going through the move path. | | `mcp_move` | An agent moved the card via `move_task_kandev`, applied immediately. | | `mcp_deferred_move` | An agent's `move_task_kandev` applied at turn end. | | `engine_transition` | The workflow engine applied a step action (`on_enter`, `on_exit`, `on_turn_start`, `on_turn_complete`). | | `wip_pull` | A WIP/queue reconciler pulled or promoted the card into a vacated step. | | `bulk_move` | A bulk move of a selection or of a whole step. | | `unarchive_restore` | A restore/rollback returned the card to a recorded step. | | `workflow_attached` | The task was attached to a workflow. | | `workflow_detached` | The task was removed from a workflow (`to_*` NULL). | | `unknown` | The path did not declare a trigger. | Each production path that mutates a task's workflow step maps to exactly one trigger. The mapping is fixed so that no implementer has to choose: | Path | Trigger | |---|---| | Task creation admission placement | `task_created` | | `Service.MoveTask` / `MoveTaskWithOptions` from an HTTP/WS board action | `manual_move` | | `Service.MoveTask` reached from `move_task_kandev`, applied immediately | `mcp_move` | | A `move_task_kandev` pending move applied at turn end | `mcp_deferred_move` | | `Service.UpdateTask` where the request carries a new `workflow_step_id` | `task_update` | | `executeStepTransition` and the engine's `ApplyTransition` | `engine_transition` | | An explicit user cancellation completing a turn (`turnCompletionCauseUserCancellation`), reached through the same `on_turn_complete` code path as `engine_transition` | `user_cancellation` | | Feeder pull and queued-task promotion on step vacate | `wip_pull` | | `BulkMoveTasks` / `BulkMoveSelectedTasks` | `bulk_move` | | `RestoreTaskMessageRollbackIfSessionState` | `unarchive_restore` | | `AddTaskToWorkflow` | `workflow_attached` | | `RemoveTaskFromWorkflow` | `workflow_detached` | | Anything not in this table | `unknown` | A move that reaches `MoveTask` through more than one of these is attributed to the outermost caller: `mcp_move` beats `manual_move`, because the agent, not a board click, is what caused it. **Actor kind** — what kind of thing caused it. | Value | Meaning | |---|---| | `human` | An authenticated identity, or the synthetic single-user identity when auth is disabled. `actor_id` is the user ID. | | `agent` | An agent session acting through MCP, or a session whose turn the engine reacted to. `actor_id` is the session ID. | | `system` | The workflow engine reacting to a non-session trigger, a queue reconciler, or a scheduler, with no initiating identity. `actor_id` is `NULL`. | | `integration` | An external watcher or automation (GitHub, GitLab, Jira, Linear, Sentry, Azure DevOps, webhook automation). `actor_id` is the watch/automation ID. | | `unknown` | Not determinable. `actor_id` is `NULL`. | `actor_id` MUST be an identifier. Display names, titles, emails, and prompts MUST NOT be written to this table. For actor kind `agent`, `actor_id` and `session_id` hold the same session ID. The duplication is intentional: `actor_id` then has one uniform meaning ("the identifier of whoever caused this") across every actor kind, and consumers do not branch on kind to find the actor. An `engine_transition` is `agent` when the trigger came from a session's turn (`on_turn_start`, `on_turn_complete`, `on_exit`/`on_enter` reached through one) and `system` when it came from a non-session trigger such as a children-completed rollup or a scheduled evaluation. A `user_cancellation` is never `agent`, even though it reaches the engine through the same `on_turn_complete` code path an `engine_transition` does: the turn didn't run to completion on its own, a caller forced it closed. Actor kind for `user_cancellation` follows the same identity-on-context rule as `manual_move` — `human` with the cancelling request's user ID when an authenticated identity is present, `system` with no identifier when it is not (for example, an automated caller that cancels on a session's behalf with no request-scoped identity). This is a deliberate carve-out from the `engine_transition` rule above, not a relaxation of it: the trigger value itself (`user_cancellation` vs. `engine_transition`) is what distinguishes a forced completion from a natural one, so a consumer never has to inspect `actor_kind` to tell them apart. ### `telemetry_activations` (new) A one-row-per-contract registry that makes each telemetry contract's activation point readable from the snapshot itself. ``` telemetry_activations contract_key string PK part 1 — e.g. "turn.workflow_step_id_at_start", "task_step_transitions" contract_version int PK part 2 activated_at timestamp NOT NULL, UTC — first boot on which this version of the contract became active on this install ``` The primary key is `(contract_key, contract_version)`, not `contract_key` alone, so a future version bump **appends** a row rather than overwriting the first activation. That is the whole point: a series that changed meaning mid-stream must show two activation points, not one. Written once per `(key, version)`, on the boot that first makes it active; never rewritten. It lives in the same schema as the data it describes so that a database reset clears both together — an activation marker that outlives its data would be worse than none. This spec registers exactly two keys: `turn.workflow_step_id_at_start` (Slice 1) and `task_step_transitions` (Slice 2), each at version `1`. ### `task_session_turns.metadata` (existing column, new key) `metadata` is a JSON object; today its only key is `runtime_config_snapshot` (1,722 of 1,722 turns in the reference store). Slice 1 adds a sibling key: ```json { "runtime_config_snapshot": { "model": "opus[1m]", "mode": "auto" }, "workflow_step_id_at_start": "e6f925e0-de99-4a29-88d7-1843d033e141" } ``` - The key is present only when the task held a workflow step when the turn started. It is otherwise **absent** — not `""`, not `null`, not `0`. - Adding the key MUST NOT depend on `runtime_config_snapshot` being present. A turn whose runtime snapshot is empty still carries the stamp. - The value is a workflow step ID. It is not resolved to a step name; step names are mutable and the ID is the join key. ## API surface **None.** This feature adds no HTTP route, no WebSocket event, no MCP tool, and no frontend surface. Its only consumers read the database. Existing surfaces are unchanged, including `GET /api/v1/sessions/:id/workflow/history`. The Go-side contract is the invariant in *What*, Slice 2: the repository transaction that commits a change to `tasks.workflow_step_id` also commits the ledger row. Callers supply trigger and actor; a caller that supplies neither gets `unknown` / `unknown`, which is a recorded fact and not an error. ## Determinism, ordering, and concurrency **Ordering.** Ledger rows for one task are ordered by `occurred_at` ASC, tiebroken by `id` ASC. `id` is the authoritative sequence — two transitions can share a timestamp, and `occurred_at` alone is not a total order. There is no third tiebreak because `id` is unique. **Clock.** `occurred_at` is the host wall clock at transaction time, in UTC. It can move backwards across an NTP correction. When `occurred_at` and `id` disagree about the order of two rows **for the same task**, `id` is correct; `occurred_at` is a measurement, `id` is the record. Consumers computing durations from a backwards-stepping pair get a non-positive interval and MUST treat it as unknown rather than clamping it to zero. **`id` is not a global watermark.** Postgres `BIGSERIAL` allocates from a sequence before commit, so ids can commit out of order across concurrent transactions. An incremental extract MUST window on `occurred_at` with an overlap wide enough to cover its longest transaction, never on `MAX(id)` seen last time. Within a single task the chain invariant below makes gaps detectable; across tasks it does not. **Chain invariant.** For any single task, reading its rows in that order, each row's `from_workflow_step_id` equals the previous row's `to_workflow_step_id`, and the last row's `to_workflow_step_id` equals the task's current `tasks.workflow_step_id`. This holds under concurrent moves; it therefore requires that the read of the old step and the write of the new one be serialized against other writers of the same task row, not read outside the write transaction. **Concurrency.** Two callers moving the same task to different steps produce two rows with an intact chain, in the order the transactions committed. This spec does not change which move wins — last committed writer still wins, as today. Neither move is rejected merely because the other raced it. **No-op writes.** A committed update whose `workflow_step_id` is unchanged writes no row, whatever else it changed. This is the whole of the feature's idempotency: a client retrying a move that already applied produces a second committed update, a no-op step change, and therefore no second row. **Engine retries.** Engine transitions are already deduplicated by the engine's `OperationID` applied-operations store, so a retried trigger does not re-apply the transition and writes no second row. No additional idempotency key is added, and there is no unique constraint on the ledger — a card legitimately moving A→B→A→B produces four rows. **Genesis rows.** Task creation writes one row with `from_*` NULL and trigger `task_created`, including when WIP capacity places the task in a feeder step rather than the requested target. Without it, the first interval of every task created after activation would have no start boundary in the ledger. A task created with **no workflow at all** writes no genesis row — there is no step to record, and a row with both sides NULL is forbidden. Its first row is the `workflow_attached` row written when it later joins a workflow. **Which tasks are recorded.** All of them, including ephemeral (quick-chat) and config tasks, and including tasks whose origin excludes them from WIP counts. Filtering by task kind is the consumer's job; excluding a class of task here would put invisible holes in the chain invariant, and the invariant is what makes the ledger self-checking. **Archiving is not a transition.** Archive, unarchive-in-place, cascade archive, and delete do not change `tasks.workflow_step_id` and therefore write no row. Only `unarchive_restore`, which does set a step, writes one. **Ledger vs. `tasks.updated_at`.** `occurred_at` is the transaction's timestamp, so a row's `occurred_at` and its task's `updated_at` agree at write time. The task's `updated_at` moves on later unrelated writes; the ledger row never does. ## Permissions The ledger is written by the same transactions that already perform authorized step mutations; it grants no new capability and performs no authorization of its own. If a caller was not permitted to move the task, no move and therefore no row occurs. There is no read surface, so there is no read authorization. Anyone with database access already has it. ## Failure modes | Condition | Behaviour | |---|---| | Ledger insert fails inside the transaction | The whole transaction rolls back: the step change does not commit either. Telemetry never silently diverges from the state it describes. | | Migration fails at boot | Kandev's migration runner swallows migration errors (`db.MigrateLogger.Apply` logs and continues). A failed `CREATE TABLE` is therefore invisible at boot. The writer MUST detect the missing table at first write and fail the transaction rather than skip the row — a step change that cannot be recorded is preferable to a ledger that is quietly partial. The boot health line (below) reports the table's absence. | | Trigger or actor cannot be determined | Written as `unknown`, which is a recorded fact. It is never guessed. | | Task has several live sessions and no single initiator | `session_id` is `NULL`. | | Task has no workflow step (detached) | `to_*` NULL with trigger `workflow_detached`; the stamp key is absent from new turns. | | Task is deleted | Rows cascade away with the task. Kandev prefers archive over delete, and archived tasks retain their rows; a deleted task's step history is gone by design and is not recoverable. | | Session is deleted | `session_id` becomes `NULL`; the row survives, because the transition was a task-level fact. | | Slice 1: the task row cannot be read when a turn starts | The turn is still created; the stamp key is absent. Turn creation MUST NOT fail because telemetry could not be resolved. | ## Persistence guarantees - Ledger rows and turn stamps survive restart, upgrade, and backup/restore. They are ordinary rows in the primary database. - Nothing about this feature is held in memory across a restart. There is no queue, no buffer, and no deferred flush; a row exists exactly when its transaction committed. - `telemetry_activations` rows survive restart and upgrade, and are cleared by a database reset together with the data they describe. - No retention policy, no TTL, no pruning. The ledger is bounded by the number of step changes (72 tasks and 1,722 turns on the reference store); it needs none. - Postgres parity is required per [ADR 0027](../../../decisions/0027-replayable-schema-migrations.md). ## Migration and activation Kandev has no migration framework: schema is Go string DDL applied idempotently at boot, and the runner swallows errors. Therefore: - New columns are added nullable and backfilled by a separate idempotent statement, following the `task_session_messages.updated_at` pattern (`ALTER TABLE … ADD COLUMN` then `UPDATE … WHERE … IS NULL`). Anything referencing a new column — index, backfill, partial predicate — runs after the `ADD COLUMN`, never in the `CREATE TABLE` init block. - Nothing is backfilled with a substituted value. Pre-activation state is absent, and absent is the correct reading. - The migration is replay-safe: running it twice on the same database is a no-op, and dialect-specific replay classification uses `internal/db` (`IsDuplicateColumnError` / `IsAlreadyExistsError`), never local string matching. - Coverage mirrors `task_external_id_migration_test.go`: seed a pre-migration row, run migrations, assert the pre-existing row reads NULL and the new objects exist, then call the migration runner **twice more** and assert idempotence — on SQLite and, env-gated, on Postgres. - On the boot that first activates each contract, a `telemetry_activations` row is written with that boot's UTC time and contract version `1`. It is written once and never rewritten. ## Writer health A telemetry writer that silently stops is worse than one that was never built, because its output still looks like data. Three controls, all required: 1. **A pinning test over the mutation set.** The production statements that may change `tasks.workflow_step_id` are enumerated in a test. A new statement that is not registered fails the build. This is the control that matters: the realistic failure is not the writer breaking, it is a new code path bypassing it. The set as of this spec is `UpdateTask`, `UpdateTaskIfWorkflowStepHasCapacity`, `PromoteQueuedTaskIfWorkflowStepHasCapacity`, `RestoreTaskMessageRollbackIfSessionState`, `AddTaskToWorkflow`, `RemoveTaskFromWorkflow`, and task creation's admission placement. 2. **Runtime counters**, following the `routing.metric.*` precedent: an expvar counter of rows written keyed by trigger, and of turns created keyed by whether the stamp was present. Mirrored as structured logs under a `telemetry.metric.*` namespace so a log-aggregation rule can match the event name without scanning free text. 3. **A boot health line** reporting, for each registered contract key: whether its objects exist, its activation timestamp, the current row count, and the most recent `occurred_at`. An install whose ledger stopped growing is visible in one line. ## Relationship to `session_step_history` `session_step_history` exists, has a `CreateStepTransition` writer with **zero production callers** on `main` (verified at `db4fc039a`), and is read by `GET /api/v1/sessions/:id/workflow/history`, which therefore returns `{"history":[]}` on every install. Wiring that writer is separate work and lands first; it and this ledger touch the same code region and cannot proceed in parallel. This spec does not delete, deprecate, migrate, or dual-write that table. The two answer different questions — "what did this session do" versus "what happened to this card" — and a card can change step with no session or with several, which is why the second question needs its own grain. ## Downstream consumer contract Normative for the analysis extract, not for this repository — recorded here because the producer's obligations only make sense against it. Every published per-step figure MUST carry an `attribution_basis` per row and coverage counts by basis. Basis is resolved in this precedence: | Basis | Source | Precedence | |---|---|---| | `task_history` | A `task_step_transitions` interval containing the event | 1 (strongest) | | `turn_start` | `task_session_turns.metadata.workflow_step_id_at_start` | 2 | | `message_reconstruction` | `task_session_messages.metadata.workflow_step_id` on workflow-automation messages (the mechanism in use today) | 3 | | `unknown` | No source resolves the event | 4 | **A partly-populated ledger MUST NOT silently replace message-timeline reconstruction.** Both remain live; the ledger raises precedence for events it covers and changes nothing for events it does not. A figure published without its coverage-by-basis breakdown is a figure whose meaning changed when the ledger activated, and that is exactly the discontinuity this contract exists to prevent. Kandev's obligations that make this possible: publish the activation point (`telemetry_activations`), version each row (`contract_version`), and leave pre-activation state absent rather than defaulted. ## Honest limits - Attribution improves **forward only**. History is not repaired. - A cost event whose window crosses a step boundary is still not divided between the two steps. The 30.5% "dominant of two steps" bucket shrinks as boundaries sharpen; it does not go to zero, and this feature does not attempt it. - Turn-level stamping records the step at turn **start**. A turn that spans a step change is attributed to where it began, which is a choice, not a measurement. - Step names are not captured. A renamed step is the same step; a deleted step leaves rows pointing at an ID with no row to join, and the consumer must tolerate that. ## Gate between slices Slice 1 ships alone and is measured before Slice 2 is built. The measurement that opens the gate: on a store with at least two weeks of post-activation turns, report the share of post-activation turns carrying the stamp, and the resulting change in the 47.0 / 30.5 / 22.5 attribution split when `turn_start` is admitted as a basis. If Slice 1 alone moves the unattributable bucket enough, Slice 2's scope is a decision made against that number rather than against this spec's assumption. If the measurement is inconclusive — too few post-activation turns, or a change inside noise — the default is that **Slice 2 proceeds as specified**. The gate exists to let evidence shrink Slice 2, not to let missing evidence stall it. The two slices can disagree: a turn's stamp reads the task's step at turn start and can be superseded by a move that commits moments later, which the ledger records and the stamp does not. That is expected, not an inconsistency, and is why `task_history` outranks `turn_start` in the basis precedence. Neither writer corrects the other. ## Scenarios ### Slice 1 — turn-start step stamp - **GIVEN** a session whose task sits in workflow step `S`, **WHEN** a turn starts, **THEN** the turn's metadata contains `workflow_step_id_at_start` = `S`. - **GIVEN** a session whose task has no workflow step, **WHEN** a turn starts, **THEN** the turn's metadata contains no `workflow_step_id_at_start` key — not an empty string, not `null`, not `0`. - **GIVEN** a session with no runtime config to snapshot, **WHEN** a turn starts while its task sits in step `S`, **THEN** the metadata contains `workflow_step_id_at_start` = `S` and no `runtime_config_snapshot`. - **GIVEN** a turn stamped with step `S`, **WHEN** the task moves to step `T` before the turn completes, **THEN** the turn's stamp is still `S`. - **GIVEN** a turn created before activation, **WHEN** it is read after activation, **THEN** it carries no stamp and is not backfilled. - **GIVEN** the task row cannot be read, **WHEN** a turn starts, **THEN** the turn is created without a stamp and turn creation does not fail. - **GIVEN** a synthetic completed turn created for a lifecycle message, **WHEN** it is written while its task sits in step `S`, **THEN** it carries the same stamp as a normal turn. ### Slice 2 — ledger writes - **GIVEN** a task in step `A`, **WHEN** a user moves it to step `B`, **THEN** exactly one ledger row exists with `from_workflow_step_id` = `A`, `to_workflow_step_id` = `B`, trigger `manual_move`, actor kind `human`, and `actor_id` equal to the acting user's ID. - **GIVEN** a task in step `A` with no session at all, **WHEN** a bulk move sends it to step `B`, **THEN** one row is written with `session_id` NULL and trigger `bulk_move`. - **GIVEN** a task in step `A` with two live sessions, **WHEN** a WIP pull promotes it into step `B`, **THEN** one row is written with `session_id` NULL, trigger `wip_pull`, and actor kind `system`. - **GIVEN** an agent session on a task in step `A`, **WHEN** the agent calls `move_task_kandev` and it applies immediately, **THEN** one row is written with trigger `mcp_move`, actor kind `agent`, and `actor_id` equal to that session's ID. - **GIVEN** an agent's deferred `move_task_kandev`, **WHEN** it applies at turn end, **THEN** one row is written with trigger `mcp_deferred_move`. - **GIVEN** a workflow step whose `on_turn_complete` transitions to step `B`, **WHEN** the turn completes, **THEN** one row is written with trigger `engine_transition`. - **GIVEN** a task in step `A`, **WHEN** a move to step `A` is issued, **THEN** no row is written. - **GIVEN** a task in step `A`, **WHEN** only its position within `A` changes, **THEN** no row is written. - **GIVEN** a WIP-limited target step at capacity, **WHEN** a move into it is rejected, **THEN** no row is written and the task's step is unchanged. - **GIVEN** the transaction that changes the step is rolled back for any reason, **WHEN** it completes, **THEN** no row exists for it. - **GIVEN** a task created into step `A`, **WHEN** creation commits, **THEN** one row exists with `from_workflow_id` and `from_workflow_step_id` NULL and trigger `task_created`. - **GIVEN** a task created targeting a full step `B` with feeder step `A`, **WHEN** creation commits and places it in `A`, **THEN** the genesis row's `to_workflow_step_id` is `A`, the step it was actually placed in. - **GIVEN** a task attached to a workflow, **WHEN** it is later removed from that workflow, **THEN** a row is written with `to_workflow_id` and `to_workflow_step_id` NULL and trigger `workflow_detached`. - **GIVEN** a task whose step changed via a task update rather than the move path, **WHEN** the update commits, **THEN** one row is written with trigger `task_update`. - **GIVEN** a caller that declares no trigger or actor, **WHEN** its step change commits, **THEN** the row records trigger `unknown`, actor kind `unknown`, and `actor_id` NULL. - **GIVEN** a task created with no workflow, **WHEN** creation commits, **THEN** no row is written; **WHEN** it is later attached to a workflow, **THEN** its first row has trigger `workflow_attached` and `from_*` NULL. - **GIVEN** an ephemeral (quick-chat) task in step `A`, **WHEN** it moves to step `B`, **THEN** a row is written exactly as for any other task. - **GIVEN** a task in step `A`, **WHEN** it is archived, unarchived in place, cascade-archived, or deleted without its step changing, **THEN** no row is written for that action. - **GIVEN** an engine action that switches a task to a step in a **different** workflow, **WHEN** the transition commits, **THEN** one row is written whose `from_workflow_id` and `to_workflow_id` differ, with trigger `engine_transition`. - **GIVEN** a task whose step is stored as the empty string, **WHEN** it moves into step `B`, **THEN** the row's `from_workflow_step_id` is NULL, not `""`. - **GIVEN** a row referencing a workflow step that is later deleted, **WHEN** the step is deleted, **THEN** the row survives unchanged with its step ID intact. ### Ordering, chain, and concurrency - **GIVEN** a task moved `A`→`B`→`A`→`B`, **WHEN** its rows are read ordered by `(occurred_at, id)`, **THEN** four rows appear and each row's `from_workflow_step_id` equals the previous row's `to_workflow_step_id`. - **GIVEN** two rows for one task sharing an identical `occurred_at`, **WHEN** they are ordered by `(occurred_at, id)`, **THEN** the order is total and matches the order the transitions committed. - **GIVEN** two callers concurrently moving the same task, one to `B` and one to `C`, **WHEN** both transactions commit, **THEN** exactly two rows exist, their chain is intact, and the later row's `to_workflow_step_id` equals the task's final `workflow_step_id`. - **GIVEN** an engine trigger that is retried with the same `OperationID`, **WHEN** the retry is handled, **THEN** no second row is written. - **GIVEN** any task, **WHEN** its last row is read, **THEN** its `to_workflow_step_id` equals `tasks.workflow_step_id`. - **GIVEN** two rows for one task whose `occurred_at` values run backwards because the host clock was corrected, **WHEN** they are ordered by `id`, **THEN** the chain invariant still holds and the ledger is not repaired or reordered by timestamp. - **GIVEN** a turn stamped with step `S` and a ledger row moving the task to `T` a moment after that turn started, **WHEN** both are read, **THEN** they disagree, and neither is treated as an error. ### Actor and privacy - **GIVEN** authentication is disabled, **WHEN** the single synthetic user moves a card, **THEN** actor kind is `human` and `actor_id` is that identity's user ID. - **GIVEN** a Jira or Linear watcher that moves a card, **WHEN** the move commits, **THEN** actor kind is `integration` and `actor_id` is the watch ID. - **GIVEN** any row, **WHEN** it is inspected, **THEN** `actor_id` holds an identifier and no display name, email, title, or prompt text appears anywhere in the row. ### Migration and activation - **GIVEN** a database created before this feature, **WHEN** the backend boots, **THEN** the ledger table and `telemetry_activations` exist, pre-existing tasks have no ledger rows, and pre-existing turns carry no stamp. - **GIVEN** a database already migrated, **WHEN** the migration runner is run twice more, **THEN** it succeeds both times and changes nothing. - **GIVEN** a Postgres deployment, **WHEN** the same fresh-then-replay sequence runs, **THEN** it behaves identically to SQLite. - **GIVEN** a first boot on which a contract activates, **WHEN** boot completes, **THEN** `telemetry_activations` holds one row for that key with `contract_version` = 1 and that boot's UTC time. - **GIVEN** a subsequent boot, **WHEN** it completes, **THEN** the existing activation row is unchanged. - **GIVEN** an install where the ledger table is absent because its migration silently failed, **WHEN** a step change is attempted, **THEN** the transaction fails rather than committing a step change with no row, and the boot health line reports the table as absent. ### Writer health - **GIVEN** a new production statement that mutates `tasks.workflow_step_id`, **WHEN** the test suite runs, **THEN** the pinning test fails until that statement is registered. - **GIVEN** a ledger row is written, **WHEN** metrics are read, **THEN** the expvar counter for that trigger has incremented and a `telemetry.metric.*` log line names the event. - **GIVEN** any boot, **WHEN** startup completes, **THEN** one health line per registered contract key reports object existence, activation time, row count, and most recent `occurred_at`. ## Out of scope - **Backfilling history.** No pre-activation transition is reconstructed, from the message timeline or otherwise. - **Dividing a cost event across a mid-turn step change.** Explicitly not attempted; the "dominant of two steps" bucket remains. - **`workflow_step_decisions`.** A different mechanism with a live writer. Not merged, not extended, not read here. - **Wiring, changing, or removing `session_step_history`** and its endpoint. Separate work, lands first. - **Any read API.** No HTTP route, no WS event, no MCP tool, no UI. Consumers read the database. - **The downstream extract and dashboard.** The consumer contract above is recorded for the analysis side; implementing it is not part of this feature. - **Step-name capture or step-rename history.** IDs only. - **Retention, pruning, or archival of ledger rows.** - **A `parent_session_id` / subagent grain.** Separate card. - **Per-turn cost columns.** Separate card.