done-blocked

DONE / BLOCKED 報告の契約

終端ステータスは厳密に 2 つです。BLOCKED には具体的な根拠が必要であり、曖昧な障害報告では認められません。

契約

すべてのエージェントの最終引き継ぎ行は、次のいずれかです。

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>

厳格なルール

1. 3 つ目の状態はありません。「ほぼ完了」「但し書き付きで完了」「もう少し」などの場合も、どちらかを選びます。但し書きがある場合は、その内容によって決まります。

   • 但し書きが見た目上の問題、または P2 以上 → DONE（Beads のバグを起票して、次に進みます）
   • 但し書きによって次のパイプライン段階に進めない → BLOCKED（完了したふりをしてはいけません）

2. BLOCKED には 3 つのフィールドが必要です。 tried + failed_because + need のいずれかが欠けている場合、判定は却下され、エージェントは再報告する必要があります。「明らか」なケースでも例外はありません。

3. 沈黙は DONE ではありません。 エージェントが終端行を書かずに出力を停止した場合、親エージェント／次の段階では、failed_because: silent — no terminal verdict written を伴う BLOCKED として扱います。

4. failed_because は具体的でなければなりません。 次の報告は却下されます。

   • 「環境の問題」→ どのコマンドが、どのエラーで失敗したのかを記載します
   • 「テストが失敗」→ どのテストが失敗し、実際のアサーションメッセージが何だったのかを記載します
   • 「要件が不明確」→ どの判断が必要で、選択肢が何と何なのかを記載します
   • 「コンテキストが不十分」→ 読もうとしたファイル／ドキュメント／設定を記載します

5. need には具体的なブロック解除策を記載します。 次の報告は却下されます。

   • 「詳しい情報」→ 具体的な質問を 1 つ尋ねます
   • 「別のエージェントの支援」→ エージェント名（architect / security-officer / …）を指定します
   • 「CTO の承認」→ 正確な選択内容（ゲート X を承認する、選択肢 A と B のどちらかを選ぶ、チェックを免除する）を記載します

判定の記載場所

すべてのエージェントは、判定を2 か所に記載します。

1. エージェント出力の最終行（エージェントを起動したオーケストレーターから見える場所）。
2. .great_cto/verdicts/<agent>-<YYYY-MM-DD-HHMMSS>.log — 追記専用の監査証跡。

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"

例

良い例 — 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

良い例 — 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

却下例 — 曖昧な BLOCKED：

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

却下理由：tried にコマンド／パスがありません。failed_because は同語反復です。need は実行可能な内容ではありません。

契約の測定

.great_cto/verdicts/*.log は機械可読です。週次ダイジェストでは、次の項目を算出できます。

• エージェントごとの DONE:BLOCKED 比率 — 1 つのエージェントで BLOCKED が多すぎる場合、その役割のリソースが不足しているか、プロンプトが不明確です
• failed_because のクラスタリング — 同じ理由が 3 回以上現れる場合、メタレベルの修正（ツール、ドキュメント、スキル）が必要な、繰り返し発生する障害です
• 沈黙率（終端判定が書かれていないエージェントの割合） — 0 に近づくようにします

アンチパターン

• 同じ報告に DONE と BLOCKED の両方を書く（「DONE ですが、X でブロックされています」）。どちらかを選びます。ブロックされているなら、作業は完了していません。
• ゲートがまだ失敗しているのに、礼儀として DONE を使う。判定は機械のためのものであり、CTO の心情に配慮するためのものではありません。
• .great_cto/verdicts/ に保存せず、標準出力だけに判定を書く。契約を測定可能にするのは監査証跡です。