done-blocked

DONE / BLOCKED 报告约定

终端状态只有两种，而且 BLOCKED 必须提供特定证据，不能含糊地报告受阻。

约定

每个 Agent 最终交接行只能是以下之一：

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. 不得有第三种状态。“基本完成”“完成但有保留意见”“快完成了”→ 请选择一种。如果存在保留意见，由保留意见本身决定：

   • 保留意见是外观问题 / P2+ → DONE（提交 Beads 缺陷报告，然后继续）
   • 保留意见会阻塞下一个流水线阶段 → BLOCKED（不要假装完成）

2. BLOCKED 必须包含三个字段。tried + failed_because + need。缺少任何字段 → 驳回该判定，Agent 必须重新报告。“情况显而易见”也不例外。

3. **沉默不等于 DONE。**如果 Agent 停止输出，却没有给出终端行，父级 / 下一阶段会将其视为 BLOCKED，并设置 failed_because: silent — no terminal verdict written。

4. **failed_because 必须具体。**以下表述会被驳回：

   • “环境问题” → 说明哪个命令失败，以及出现了什么错误
   • “测试失败” → 说明哪些测试失败，以及实际断言消息
   • “需求不明确” → 说明需要做出哪项决策，以及两个选项
   • “上下文不足” → 说明你尝试读取哪个文件 / 文档 / 配置

5. **need 必须指出具体的解阻事项。**以下表述会被驳回：

   • “更多信息” → 提出一个具体问题
   • “需要另一位 Agent 协助” → 指明该 Agent（architect / security-officer / …）
   • “CTO 批准” → 说明确切的选择（批准门禁 X、选择选项 A 或 B、豁免检查）

判定写入位置

每个 Agent 都必须将判定写入两个位置：

1. Agent 输出的最后一行（由启动该 Agent 的编排器查看）。
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 可供机器读取。每周摘要可以计算：

• 每个 Agent 的 DONE:BLOCKED 比率——某个 Agent 的 BLOCKED 过多，说明该角色资源不足或提示词不明确
• failed_because 聚类——如果同一原因出现 3 次或更多，说明这是反复出现的阻碍，值得通过元层面修复（工具、文档、技能）
• 沉默率（未写入终端判定的 Agent）——应逐渐降至零

反模式

• 在同一份报告中同时写 DONE 和 BLOCKED（“DONE，但被 X 阻塞”）。只能选一种。如果你受阻，工作就尚未完成。
• 当门禁仍未通过时，为了表示礼貌而使用 DONE。判定是给机器看的，不是为了照顾 CTO 的感受。
• 只将判定写入 stdout，却没有持久化到 .great_cto/verdicts/。审计记录能让这项约定变得可衡量。