done-blocked

# DONE / BLOCKED Reporting Contract Terminal status is exactly two states, and BLOCKED requires specific evidence — not vague obstruction reports. ## The contract Every agent's final handoff line is one of: ``` DONE: <one-sentence summary of what shipped> artifact: <path to report/PR/commit> next: <who picks this up — pipeline stage, gate, or "pipeline continues"> ``` ``` BLOCKED: <one-sentence summary of the obstacle> tried: <what was attempted — file paths, commands, error signatures> failed_because: <concrete reason — not "unclear", not "complex"> need: <specific unblock — file access, missing config, CTO decision, another agent> ``` ## Hard rules 1. **No third state.** "Mostly done", "done with caveats", "almost there" → choose. If caveats exist, the caveat itself decides: - Caveat is cosmetic / P2+ → **DONE** (file a Beads bug, move on) - Caveat blocks the next pipeline stage → **BLOCKED** (do not pretend) 2. **BLOCKED requires three fields.** `tried` + `failed_because` + `need`. Missing any field → the verdict is rejected and the agent must re-report. No exceptions for "obvious" cases. 3. **Silence is not DONE.** If the agent stops producing output without a terminal line, the parent / next stage treats it as BLOCKED with `failed_because: silent — no terminal verdict written`. 4. **`failed_because` must be concrete.** These are rejected: - "environment issue" → say *which* command failed with *what* error - "tests failing" → say *which* t...