--- disable-model-invocation: true name: spec-update description: 当同一个活跃 Spec（位于 `spec/versions//specs//`）在当前工作分支内需要小迭代、补充需求、修正方案或优化实现，且原 Spec 目录已有 writer/plan.html + executor/summary.html 时使用。默认复用 writer/plan.html 记录的 git_branch，不新建分支。不要用于新功能从零设计、已合并/已关闭分支上的后续需求，或需要独立 PR/MR 的较大变更。 --- # Spec Update ## 核心原则 1. **同 Spec 原则**：update 报告必须放在原 Spec 目录的 `updater/` 下，禁止创建新的 Spec 根目录 2. **不归档原则**：更新完成后不归档，保留在原目录以便后续更新 3. **编号递增**：`updater/update-001.html` → `updater/update-002.html` → `updater/update-003.html`（三位数，不跳号） 4. **严格遵循方案**：只实现 `updater/update-xxx.html` 定义的修改，不添加方案之外的内容 5. **回归测试必须通过**：新增测试 + 修改测试 + 原有功能回归测试全部通过 6. **规范维护审查**：更新也可能产生长期规则，完成后同样检查是否需要维护 AGENTS.md / .agents/rules/ 7. **同分支原则**：update 默认复用原 Spec 的 `git_branch`，禁止为同一活跃 Spec 的小更新默认创建新分支 8. **报告用 HTML**：update 报告遵循 html-report 契约（HTML + 共享样式表 + `data-rev` 修订标记）；经验/知识记忆保持 Markdown（账本两种格式皆可） 9. **续接同一批角色**：update 是同一个 Spec 的延续，不是新任务。必须续接原来那批角色，不重新 spawn —— 见下文「角色续接」 ## 角色续接（必须执行） 用户的期望是「还是那个 writer / tester 在跟我对话」，而不是每次 update 都换一批零历史的新实例。做法固定三步： 1. **查账本**：读 `lead/team-context.md`（或 `.html`）的「角色运行句柄」，取本 Spec 上次用的 `agent_id` 与状态。 2. **核对实况**：用运行时的 agent 列表核对该 handle 当前的真实状态。 3. **按状态决定动作**： | 账本/实况状态 | 动作 | |---------------|------| | `running` / `idle` / `parked` | **发消息**给同一个 agent。`parked` 收到消息会自动复活且上下文完整，不需要任何额外操作 | | `aborted` | 只能重新 spawn 同一项目级角色，并让它先读账本与既有产物重建上下文 | **禁止用重新 spawn 代替续接。** 运行时按 name 分配 agent id，同名再 spawn 会得到 `spec-writer-2` 这样的全新零历史实例——影子角色。续接成功后更新账本的「续接方式」与「累计参与 Spec 数」。 跨进程（omp 重启后）handle 可能已失效，此时账本与落盘产物是唯一恢复路径——这也是账本必须实时更新而非攒批的原因。 ## 确认方式随模式（必须执行） `gated` 模式下，以下三个节点必须使用当前运行环境的确认方式向用户确认。`autopilot` 模式下由各节点标注的机械证据替代，缺证据不得放行： **节点 1 — 更新方案确认**（创建 `updater/update-xxx.html` 后）： ```text 确认目标：updater/update-xxx.html 已创建完成，更新方案是否可以开始执行？ 确认选项： - 确认，开始执行 - 需要修改（请说明修改要求） ``` **节点 2 — 审查报告确认**（生成 `reviewer/update-xxx-review.html` 后）： ```text 确认目标：reviewer/update-xxx-review.html 已创建完成，审查结果是否通过？ 确认选项： - 审查通过 - 需要修复（请说明问题） ``` **节点 3 — 分支收尾确认**（测试和审查通过后）： ```text 确认目标：本次 update 已通过测试和审查。是否提交并推送当前 Spec 分支？如果该 Spec 已准备整体交付，是否创建/更新 PR？ 确认选项： - 确认，提交并推送 - 暂不提交 ``` 响应处理：选择确认选项 → 继续；选择修改/修复或"Other" → 根据用户反馈调整后重新确认。 ## 报告模板 - **updater/update-xxx.html 模板**：见 [references/update-template.html](references/update-template.html)（含元信息字段说明） - **updater/update-xxx-summary.html 模板**：见 [references/summary-template.html](references/summary-template.html)（含元信息字段说明） 两个模板的骨架、组件与修订标记规范由 html-report skill 定义；样式表相对路径按 `updater/` 回到项目根的 6 层写作（`../../../../../../html-report/assets/rk-report.css`），项目层级不同需相应调整。 **功能等价要求（不允许退化）**： - 原 frontmatter 字段必须双轨保留：`` 里逐字段写 ``，文档关联写 ``；`.rk-meta` 镜像同样字段（含基准分支与 PR） - 原双链必须保留双向：末尾「关联产物」拆成「本报告引用」（`