docs(tasktree): require timely lifecycle updates

This commit is contained in:
pikastech
2026-07-21 10:30:19 +02:00
parent 65c0012fb8
commit 81b4266dae
+28
View File
@@ -39,6 +39,32 @@ description: >-
- 失败必须保留稳定错误码和非零退出;
- 不把自然语言日志或数据库行数当作任务状态真相。
## 强制生命周期同步
- TaskTree 状态是当前工作的权威真相,不是事后可选记录:
- 开始执行已有任务前先用 `task get` 确认状态;状态为 `pending` 时必须立即
执行 `task start`
- 新建后立即开始的任务必须在同一工作回合执行 `task start`,禁止长期留在
`pending`
- 验收完成后、向用户报告完成前,必须先写 ExecutionReport,再执行
`task complete`
- 禁止因为代码已提交、issue 已关闭、服务已上线或准备执行 `$post-task`
就跳过 TaskTree 状态更新;这些事实只能作为报告证据,不能替代状态 mutation;
- 当前仍受阻时及时更新为 `blocked` 并在报告中写明阻塞证据;阻塞解除并恢复
执行时重新 `task start`
- 父任务的验收目标与全部必要子任务均完成后,父任务也必须写报告并完成,
不能只完成叶子节点而让父节点永久停留在未开始或进行中。
- 每次任务收口必须执行状态复核:
-`task get` 确认当前任务为 `completed`,并能读到本次 ExecutionReport
-`group stats` 检查所属 TaskGroup,不得把“实际完成但仍为 pending、
in_progress 或 blocked”的任务留给后续代理修正;
- 只有用户明确暂停、验收未通过或存在真实阻塞时,任务才可以非 completed
状态结束当前回合,并必须向用户报告原因。
- 清理历史滞后状态时不得仅凭标题批量完成:
- 逐项核对提交、issue、部署、测试或既有报告证据;
- 证据充分时补写 ExecutionReport 后完成任务;
- 证据不足时保持原状态并补充说明,不伪造完成事实。
## 能力映射
| 任务管理能力 | TaskTree CLI |
@@ -137,6 +163,8 @@ tasktree workflow start
- 任务执行前用 `task get` 读取当前状态与报告;
- 批量查看使用 `task list --group <group-id>`
- 收口使用 `group stats --group <group-id>`
- 最终回复前必须按“强制生命周期同步”完成当前任务的报告、状态 mutation
和复核;
- 删除不存在的对象必须返回 `not_found`,不得伪装成功。
- 配置与传输错误:
- L0 缺少数据库地址返回 `missing_database_url`