docs: simplify TaskTree report completion flow

This commit is contained in:
pikastech
2026-07-21 14:09:06 +02:00
parent d7a3fb8cbb
commit 2197012a5a
+15 -9
View File
@@ -46,12 +46,15 @@ description: >-
执行 `task start`
- 新建后立即开始的任务必须在同一工作回合执行 `task start`,禁止长期留在
`pending`
- 验收完成后、向用户报告完成前,必须写 ExecutionReport,再执行
`task complete`
- 验收完成后、向用户报告完成前,必须写 ExecutionReport
- `report write` 成功后默认在同一事务内把任务切换为 `completed`,日常闭环
不再额外执行 `task complete`
- 相同报告幂等写入返回 `mutation=false`,但任务状态滞后时仍必须校正为
`completed`
- 禁止因为代码已提交、issue 已关闭、服务已上线或准备执行 `$post-task`
就跳过 TaskTree 状态更新;这些事实只能作为报告证据,不能替代状态 mutation;
- 当前仍受阻时及时更新为 `blocked` 并在报告中写明阻塞证据;阻塞解除并恢复
执行时重新 `task start`
- 当前仍受阻时及时更新为 `blocked` 并在任务说明中写明阻塞证据;阻塞解除并
恢复执行时重新 `task start`,验收完成后再写 ExecutionReport
- 父任务的验收目标与全部必要子任务均完成后,父任务也必须写报告并完成,
不能只完成叶子节点而让父节点永久停留在未开始或进行中。
- 每次任务收口必须执行状态复核:
@@ -62,7 +65,7 @@ description: >-
状态结束当前回合,并必须向用户报告原因。
- 清理历史滞后状态时不得仅凭标题批量完成:
- 逐项核对提交、issue、部署、测试或既有报告证据;
- 证据充分时补写 ExecutionReport完成任务;
- 证据充分时补写 ExecutionReport,由报告写入自动完成任务;
- 证据不足时保持原状态并补充说明,不伪造完成事实。
## 能力映射
@@ -97,15 +100,13 @@ bun scripts/cli.ts tasktree task start \
--task <task-id>
```
- 完成任务前先写 ExecutionReport
- 完成任务时写入 ExecutionReport,报告与完成状态在同一事务内提交
```bash
bun scripts/cli.ts tasktree report write \
--task <task-id> --title "执行报告" --stdin <<'EOF'
验证已完成,记录命令、结果和关键证据。
EOF
bun scripts/cli.ts tasktree task complete \
--task <task-id>
bun scripts/cli.ts tasktree group stats \
--group <group-id>
```
@@ -137,6 +138,9 @@ tasktree workflow start
- 同批任务必须在一个事务内全部成功或全部失败;
- 报告使用 `report write --stdin``--body-file`
- 相同任务、标题、正文和状态的重复报告返回 `mutation=false`
- `report write` 返回完成后的 `task``taskMutation`
- 报告内容幂等但任务尚未完成时,`mutation=false`
`taskMutation=true`
- 参数合同:
- 多余位置参数返回 `invalid_arguments`
- 未知选项或命令不支持的选项返回 `invalid_option`
@@ -150,7 +154,9 @@ tasktree workflow start
- Subsubtask 禁止继续创建下级。
- 状态流转:
- `task start` 把任务标记为 `in_progress`
- `task complete``task done` 要求至少一份 ExecutionReport
- `report write` 成功后自动把任务标记为 `completed`
- `task complete``task done` 保留为已有报告场景的显式完成入口,并要求
至少一份 ExecutionReport
- 禁止使用 `task update --status completed` 绕过报告门禁;
- `task update --status blocked` 用于标记阻塞;
- `task delete``task remove` 使用相同删除合同。