ns-sdd-execution-handoff-generator

执行交接生成器

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

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

Harness 发现

请参阅 ../ns-harness/references/harness-discovery.md 和 ../ns-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：task-NNN（取自 task-NNN-*.md，去掉 slug）
层级	从文件名或任务正文推断（backend、frontend、infra、unit-tests、e2e）

不要在交接表中填写 Feature、模型层级或自由格式备注——这些内容应放在任务文件中。

2. 构建执行规则块

在 {product_root}/docs/context/stack-confirmed.md 存在时，与 requirements.md 一并阅读。向 {execution_rules_block} 添加最多 10 条关键要点——例如遗留数据库约束、多租户、测试环境规则等。不要重复完整的需求文件。

3. 编写文件

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

• 所有任务的状态均设为 pending，时间戳设为 —，Time (s): 0，Tokens: 0
• 标题中的 Tokens (total): 设为 0
• {next_task_id} = 第一个短 ID（例如 task-001）
• 若存在 gitlab-sync-config.md，则从中获取 {base_branch} / {work_branch}；否则设为 —

4. 向编排器报告

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

状态更新（实施期间）

任务开始、完成、阻塞或获豁免时：

1. 在 任务状态 中定位任务行
2. 更新 Status、Started at（状态为 in_progress 时）、Finished at（状态为 completed 时）、Time (s)（Finished at − Started at）、Tokens、Updated at
3. 状态变为 completed 前必须填写 Tokens。 来源（按优先级排序）：
   1. 该任务的 coder-agent 和其他子 Agent 的任务结果／界面中显示的用量／tokens
   2. 如果平台显示该任务循环的父级 tokens，则使用父级 tokens
   3. 未显示任何信息：询问人工一次；如果对方拒绝，则使用 ~N 估算值，并在任务的 ## Execution notes 中添加一行 tokens: ~N (estimated) 禁止： 对执行过大模型工作的 completed 任务填写 0
4. 重新计算 Tokens (total) = Tokens 列之和（整数；~N 按 N 计）
5. 重新计算 Progress（Next task = 首个状态为 pending 或 in_progress 的任务）
6. 重新计算 时间跟踪（秒）：
   • Implementation — start = 最早填写的 Started at
   • Implementation — end = 最新填写的 Finished at（如有）
   • Implementation — total (s) = end − start
   • Total task time (s) = Time (s) 列之和
   • Total process time (s) = Planning — total (s) + Implementation — total (s) +（存在 Final delivery — end 时，Final delivery — end − Implementation — end）
   • Last recalculated = 当前时间戳
7. 更新 Version status（参见模板）
8. 可选追加 Session history（仅限日期 + 极简备注）
9. 重要备注（阻塞项、豁免）：追加到任务文件的 ## Execution notes 中——仅添加相关内容；交接中的 Notes 列始终不填写

版本收尾（审查、动态规范、移动至 _done/）：填写 Post-implementation review — end、Review — tokens（或添加 Session history 备注——不要填写在最后一个任务的 Tokens 列中）、Living specs — end（如适用）、Final delivery — end；重新计算 Total process time (s)。

允许的任务状态

pending | in_progress | completed | blocked | waived

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

生成后如有添加或移除任务，必须重新生成，并按任务短 ID 保留现有状态。

集成

阶段	技能／参考资料
任务生成后	此技能（生成交接）
经典实施	references/run-implementation.md + coder-agent（有条件时必须使用）/ ns-code-coder
分区实施	ns-execution-orchestrator（切片交接 + 主流程收尾）
版本结束审查	reviewer-agent（有条件时必须使用）/ ns-code-reviewer
动态规范	ns-sdd-living-spec-consolidator
GitLab 看板同步	ns-gitlab-board-sync（存在配置时）

参考资料

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