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 tests and the actual assertion message
   • "unclear requirements" → say which decision is needed and the two options
   • "not enough context" → say which file / doc / config you tried to read

5. need names a specific unblock. These are rejected:

   • "more information" → ask one specific question
   • "help from another agent" → name the agent (architect / security-officer / …)
   • "CTO approval" → state the exact choice (approve gate X, pick option A vs B, waive check)

Where the verdict goes

Every agent writes the verdict to two places:

1. Last line of agent output (visible to the orchestrator that spawned it).
2. .great_cto/verdicts/<agent>-<YYYY-MM-DD-HHMMSS>.log — append-only audit trail.

mkdir -p .great_cto/verdicts
VERDICT_FILE=".great_cto/verdicts/<agent>-$(date -u +%Y-%m-%d-%H%M%S).log"
printf '%s\n' "$VERDICT_LINE" > "$VERDICT_FILE"

Examples

Good — DONE:

DONE: CSO audit passed — 0 P0, 2 P1 findings filed as Beads tasks.
  artifact: docs/security/CSO-2026-04-19.md
  next: gate:ship ready for CTO approval

Good — BLOCKED:

BLOCKED: senior-dev cannot claim task BD-42 — circular dependency with BD-38.
  tried: bd ready → BD-42 did not appear; bd dep tree BD-42 → shows BD-38 blocks BD-42, BD-42 blocks BD-38
  failed_because: both tasks depend on each other transitively (BD-42 → BD-38 → BD-39 → BD-42)
  need: architect to split BD-39 into two tasks so the cycle breaks

Rejected — vague BLOCKED:

BLOCKED: couldn't finish QA — environment problems.
  tried: ran tests
  failed_because: stuff broken
  need: help

Why rejected: tried lacks command/path; failed_because is tautological; need is not actionable.

Measuring the contract

.great_cto/verdicts/*.log is machine-readable. Weekly digest can compute:

• DONE:BLOCKED ratio per agent — too many BLOCKED from one agent = that role is under-resourced or prompt is unclear
• failed_because clustering — if the same reason appears 3+ times, that's a recurring obstruction worth a meta-fix (tooling, doc, skill)
• Silence rate (agents with no terminal verdict written) — should trend to zero

Anti-patterns

• Writing both DONE and BLOCKED in the same report ("DONE but blocked on X"). Pick one. If you're blocked, the work isn't done.
• Using DONE as a politeness signal when the gate still fails. The verdict is for the machine, not the CTO's feelings.
• Writing the verdict only to stdout without persisting to .great_cto/verdicts/. The audit trail is what makes the contract measurable.