run-state

name	run-state
description	Durable per-plan run ledger (STATE.md) so a killed multi-phase run resumes with zero re-implementation. Use for any multi-phase run (/ck:cook, /ck:flow, /ck:fix, /ck:refactor), when resuming an interrupted run, after a spend/session kill, or after context compaction. Covers the append-only event contract, the resume protocol (re-derive truth from git + gates, never trust the plan's status claims), and parallel-session safety.
metadata	{"version":"1.0.0"}

Run-State — the Durable Ledger

Why

Progress that lives in TodoWrite + prose plans dies with the session: ≥11 runs across two users were killed mid-phase by spend limits / session loss / 529s, each costing full manual state reconstruction (one needed 4× continue; TodoWrite itself failed repeatedly). The ledger is the record that survives.

Ledger is authoritative over recollection. After compaction or resume, what you "remember" doing is inadmissible; what STATE.md + git say happened is the record. TodoWrite is a UI mirror, never the record.

Where

plans/<plan>/STATE.md — beside the plan it tracks, committed with the phase it records, so a resume after a machine loss can pull it from the remote.

An ignored ledger is a broken ledger. On start, run git check-ignore plans/<plan>/STATE.md. If it matches, the ledger can neither be committed nor survive git clean -fdx — warn once and name the fix (the repo's .gitignore needs the re-include stanza below; a downstream project that ignores plans/ inherits the same defect, invisible until the run that needed the ledger is already dead):

plans/**/*
!plans/**/
!plans/**/plan.md
!plans/**/phase-*.md
!plans/**/STATE.md

(The directory re-include line must come first — a file cannot be re-included once its parent directory is excluded.)

Contract

First line names the plan; everything after is append-only, one line per event:

# run-state — plan: <plan path>

phase <N>: started (base <sha7>)
phase <N>: gate <name> → PASS|FAIL (evidence: <cmd> → <result>)
phase <N>: complete (commits <a7>..<b7>, tests <X/Y>, review clean|<K> parked)
phase <N>: parked — <finding> — ruling: <why>
phase <N>: BLOCKED — <reason>

Full event vocabulary + field semantics: references/state-schema.md.

Write points: append at every gate transition — requirements gate, verify-plan, scope-lock, each implement phase, test, review, debug loop rulings, finish — not only inside Implement. Also record environment facts a resume needs (pre-edit baseline, model substitutions, dead-agent redispatches).

Resume protocol (the core value)

On starting a run whose plan directory already has a STATE.md:

1. Read the ledger. Last event tells you the claimed position.
2. Re-derive true state — never trust status claims (the source data has plans whose own status lines were wrong):
   • git log --oneline <base>..HEAD — what was actually committed;
   • git status --porcelain — what is half-done in the tree;
   • re-run the declared exit gates of every phase the ledger marks complete (plans carry machine-checkable gates — a command + expected result).
3. Emit a derived-state table before touching code: phase · ledger claim · gate re-run result · verdict (CONFIRMED / STALE / CONTRADICTED). A CONTRADICTED phase is re-opened, not re-trusted.
4. Resume at the first phase that is not CONFIRMED complete. Zero re-implementation of confirmed work.
5. Append phase <N>: resumed (derived from ledger + gates, <K> phases confirmed).

Parallel-session safety

• One ledger per plan, not per repo — concurrent sessions on different plans never touch the same file.
• Writes are append-only single lines (>>), so two sessions on the same plan interleave without clobbering.
• A ledger whose first line names a different plan is another run's record: leave it, start your own.

Rules

• A killed run resumes from STATE.md + gate re-runs alone — if resume would need anything else, that thing belongs in the ledger.
• Evidence in gate lines is verbatim (<cmd> → <result>), per the code-review skill's Iron Law — "gate passed" without the command is a claim, not a record.
• Commit the ledger with the phase it records (same commit or immediately after).
• Related: planning skill (executable exit gates are what make step 2 possible), code-review (verification gates), tdd (the baseline: line a resume needs to tell inherited breakage from regressions).