execution-handoff-generator

执行交接生成器

衔接规划 → 实现。生成并维护 {product_root}/docs/versions/{version_san}/execution-handoff.md，作为任务顺序、进度和已用时间的唯一事实来源。

requirements.md 说明做什么；tasks/task-NNN-*.md 说明怎么做； execution-handoff.md 说明按什么顺序执行以及执行停在何处。

工具链发现

参见 ../nextstage-harness/references/harness-discovery.md 和 ../nextstage-harness/references/artifact-layout.md。

适用时机

触发条件	操作
规划结束（已编写所有 task-NNN-*.md）	生成初始交接文件
已有任务，但缺少交接文件	实现前先生成
任务开始、完成、受阻或被豁免	更新状态并重新计算时间
所有任务完成 — 审核 / 持续维护的规格 / 收尾	更新版本状态和最终时间戳

完整的实现者循环（读取交接文件 → 任务循环 → 收尾），请参见 references/run-implementation.md。

前置条件（生成）

• 已定义 {product_root} 和 {version_san}
• {product_root}/docs/versions/{version_san}/requirements.md 已存在
• 至少有一个 {product_root}/docs/versions/{version_san}/tasks/task-*.md
• 模板：references/execution-handoff.template.md
• 规划阶段的时间戳：
  • planning_started_at（ISO 本地时间 YYYY-MM-DDTHH:MM:SS）
  • planning_finished_at（ISO 本地时间 YYYY-MM-DDTHH:MM:SS）
  • planning_total_seconds（大于或等于 0 的整数）

对于子版本：将交接文件写入 subversions/{subversion_san}/execution-handoff.md（仅包含切片范围）。

初始生成

1. 收集任务元数据

按数字顺序处理每个 task-NNN-*.md：

字段	来源
ID	文件名中的 NNN
文件	文件名
标题	首个 # ... 行
功能	**Related feature:** 行
层级	根据文件名或任务正文推断（backend、frontend、infra、unit-tests、e2e）
模型层级	存在时的 **Suggested model tier:**

2. 构建执行规则块

读取 requirements.md，以及（如存在）{product_root}/docs/context/stack-confirmed.md。向 {execution_rules_block} 添加最多 10 条关键要点，例如旧版数据库约束、多租户、测试环境规则等。不要重复完整的需求文件。

3. 编写文件

使用 references/execution-handoff.template.md 保存至 {product_root}/docs/versions/{version_san}/execution-handoff.md：

• 所有任务初始状态均为 Status: pending，时间戳为 —，Time (s): 0
• {next_task_id} = 首个任务 ID（例如 001）
• {base_branch} / {work_branch} 从 gitlab-sync-config.md 获取（如存在）；否则为 —

4. 向编排器报告

返回：交接文件路径、已索引的任务总数、首个任务 ID，以及通过 references/run-implementation.md 开始实现的指示。

状态更新（实施期间）

当任务开始、完成、受阻或被豁免时：

1. 在 任务状态 中找到任务所在行
2. 更新 状态、开始时间（状态为 in_progress 时）、完成时间（状态为 completed 时）、耗时（秒）（完成时间 − 开始时间）、更新时间、备注
3. 重新计算 进度（下一项任务 = 第一个状态为 pending 或 in_progress 的任务）
4. 重新计算 时间跟踪（秒）：
   • 实施 — 开始时间 = 最早填写的 开始时间
   • 实施 — 结束时间 = 最新填写的 完成时间（如有）
   • 实施 — 总耗时（秒） = 结束时间 − 开始时间
   • 任务总耗时（秒） = 耗时（秒） 列的总和
   • 流程总耗时（秒） = 规划 — 总耗时（秒） + 实施 — 总耗时（秒） +（最终交付 — 结束时间 − 实施 — 结束时间，如有）
   • 上次重新计算时间 = 当前时间戳
5. 更新 版本状态（参见模板）
6. 可选择追加 会话历史

在版本收尾时（审查、维护中的规范、移入 _done/），还需填写： 实施后审查 — 结束时间、维护中的规范 — 结束时间（如适用）、 最终交付 — 结束时间，并重新计算 流程总耗时（秒）。

允许的任务状态

pending | in_progress | completed | blocked | waived

• waived： 必须在该行的 备注 中记录人工豁免。未经记录的风险接受，不得豁免 P0 测试任务（租户隔离、URL RBAC、身份验证速率限制）。
• 禁止： 没有 code-review-report.md 时，将版本标记为 completed
• 禁止： 未经人工批准，不得重新排序任务或重写基础提示词
• 禁止： 删除会话历史 — 只能追加

如果生成后添加或移除了任务，重新生成，并保留现有任务 ID 对应的状态。

集成

阶段	技能 / 参考资料
任务生成后	此技能（生成交接内容）
经典实施	references/run-implementation.md + code-coder
分区实施	execution-orchestrator（切片交接 + 主收尾）
版本结束审查	code-reviewer
维护中的规范	pm-living-spec-consolidator
GitLab 看板同步	gitlab-board-sync（存在配置时）

参考资料

文件	适用时机
references/execution-handoff.template.md	交接结构
references/run-implementation.md	经典版本执行循环