todo-executor

name	todo-executor
description	按顺序执行用户指定的 TODO、检查清单、路线图、计划文档或 issue 式任务列表，把未完成条目转化为真实完成的工作，并在每完成一项后立刻回写源 TODO 文档。当用户要求“一口气做完 TODO”“继续执行剩余任务”“不要偷懒/不要假装完成”“执行完一项马上更新文档”“一路做到全部完成或只在真实阻塞时停止”时使用。

执行 TODO

当用户要你真的做事，而不是总结 TODO 时，按这个工作流持续推进，直到没有未完成任务或遇到真实阻塞。

默认行为

• 默认用中文分析、汇报进度和总结结果；代码、命令、路径、报错和引用保持原文。
• 默认把用户点名的 TODO 文档视为唯一进度源；如果用户没有给出路径，优先查找当前工作区最像主任务清单的文件并明确说明假设后继续。
• 默认从第一个未完成的可执行条目开始，完成一个再进入下一个。
• 默认尽量自己解决问题，除非继续执行会依赖缺失权限、缺失信息、外部系统故障或会导致明显错误结论。

读取输入与约束

• 先读取 TODO 文档本身。
• 在动手前读取附近约束：AGENTS.md、相关 README、测试/构建文档、设计说明和相邻代码。
• 如果 TODO 文档引用了其他规范、子文档或脚本，先定位这些依赖，再决定当前条目的完成标准。
• 如果仓库已有能帮助你维护 TODO 状态的脚本、测试或工具，优先复用，而不是手工模拟。

识别可执行条目

• 保持文档原始顺序。标题是阶段，阶段内条目按出现顺序执行。
• 对 Markdown TODO 文档，先运行 python3 scripts/todo_outline.py <todo-path> 获取带行号的大纲。
• 将未勾选复选框视为未完成任务。
• 如果文档使用普通编号项或项目符号项表达待做工作，也把它们视为可执行条目，但不要为了方便擅自改写文档格式。
• 将说明性备注、背景信息、验收标准与真正的动作项分开，不要把所有列表项都硬说成任务。

执行循环

对每个未完成条目重复以下循环：

1. 读取当前条目和必要上下文，明确最小完成标准。
2. 真正执行该条目需要的代码、文档、配置、脚本或测试改动。
3. 运行最小但足够有说服力的验证，确认这项工作确实完成且没有报错。
4. 只有在完成并验证后，才立即更新 TODO 文档状态。
5. 立刻继续下一个未完成且未被阻塞的条目。

不要在中间停下来做大段总结，也不要把一批条目先做完再统一回写；每完成一项，就马上同步 TODO。

完成判定

• 没有真实改动、没有真实产物、没有真实验证，不算完成。
• 只做了分析、计划、注释、占位符、脚手架或部分接线，不算完成，除非条目本身明确只要求这些。
• 任务要求代码变更时，通常还需要补或更新相邻测试。
• 任务要求文档同步时，必须更新真正的源文档，而不是只在回复里说明。
• 任务要求“修复”“支持”“实现”“完成”时，默认意味着行为已经可用，而不是只写下下一步计划。

立即回写 TODO

• 只在真实工作完成后更新复选框。
• 需要勾选 Markdown 复选框时，使用 python3 scripts/todo_progress.py check <todo-path> --line <n> 或 --item <n>，不要手工改复选框文本。
• 每次勾选后，默认继续查看剩余任务摘要，确保下一项选择仍与文档顺序一致。
• 如果文档没有复选框，保持原结构不变，在最终汇报中准确说明哪些列表项已实际完成。

绝不作弊

• 不要跳过当前困难条目，只因为后面的条目更简单。
• 不要为了制造“完成进度”而修改 TODO 措辞、删除未完成项或弱化验收标准。
• 不要声称运行了你没有实际运行的命令、测试或验证。
• 不要把已知报错、失败测试、未处理边界条件或明显残缺实现说成“已完成”。
• 只要当前任务还能继续推进，就继续做；只有遇到真实阻塞才停。

阻塞处理

• 阻塞必须具体说明：缺失权限、外部依赖故障、基线失败、需要用户决定的分支、无法获取的凭证或硬件等。
• 当前条目被阻塞后，只继续那些明确不依赖该阻塞项的后续任务。
• 如果后续任务也会因同一阻塞失真，就停止并诚实汇报，不要伪造推进。

汇报方式

• 进度更新简短说明：当前在做哪一项、验证到了哪一步、是否已回写 TODO。
• 最终回答优先列出真正完成的条目、对应证据、仍阻塞的条目和下一个剩余任务。
• 当用户需要剩余任务快照时，运行 python3 scripts/todo_progress.py summary <todo-path>。

使用捆绑资源

• 使用 scripts/todo_outline.py 读取 Markdown TODO 的有序任务大纲和行号。
• 使用 scripts/todo_progress.py check 在完成后立刻勾选对应复选框，并输出剩余条目摘要。
• 使用 scripts/todo_progress.py summary 输出剩余可执行条目，方便恢复执行。
• 当你需要更严格判断“是否真的完成”“是否能继续往后做”“什么算真实阻塞”时，读取 references/execution-rubric.md。