implement

实现

你正在执行 agent-toolkit 流程中的 implement 阶段，即 Spine 第 4 阶段。你的工作是忠实执行 plan.md。不得对公共契约、安全策略、兼容性／迁移、明确的边界、不可逆或成本高昂的承诺，或有实质意义的架构／运维权衡作出任何新决定。遇到这些情况应退回。你可以选择惯用、符合习惯的本地／私有／可逆实现方案。

运行辅助脚本

此技能将辅助脚本打包在自己的 scripts/ 目录中（与此 SKILL.md 一同安装）。将 SKILL_DIR 设置为此技能的绝对路径——本文件末尾的 此技能的基础目录 中会显示该路径——然后从你的 项目根目录 运行脚本（脚本会操作项目的 .changes/ 和 CONTEXT.md 文件）：

SKILL_DIR="<absolute path to this skill's directory>"

以下所有 node "$SKILL_DIR/scripts/..." 命令都依赖此设置。切勿引用 packages/build/——该路径仅存在于工具包的开发仓库中，不存在于已安装的技能中。

你的立场

实现者应遵循已确认的结果和范围。不得临场发挥行为或契约。应先调查不确定之处；只有在证据表明仍有用户负责的重大决策未解决时，才退回。私有辅助函数、本地数据结构、控制流和等效的惯用实现机制都属于实现选择，并非规范缺陷。

代码质量仍由你负责，但不会按章节进行评审。每个章节都要达到绿色基线；所有章节均为绿色后，再进行一次有范围限制的评审和保持行为不变的整改（参见 references/implementation-review.md）。

前提条件

加载 manifest.yaml。验证：

• phase 为 implement（计划审批已通过）。
• approvals.implement 为 pending。
• plan.md 存在。

先阅读 change-brief.md，再阅读 references/engineering-fundamentals.md。如果设置了 manifest.language，请使用 idioms 技能加载对应语言的规范包，用于实现和评审。如果未安装匹配的规范包，请说明这一点，并遵循仓库约定和工具链。

工作循环：逐章节（实现 → 测试通过）

按照 plan.md 一次处理一个章节。每个章节：

步骤 1：先编写明确边界测试

找出本章节中所有标记为 [seam: <id>] [firmness: firm] 的测试任务。先编写这些测试。在编写任何实现代码之前，这些测试必须为 红色（失败）。这是不可协商的。

步骤 2：实现至绿色

编写计划中的实现任务。按清单顺序逐项执行。完成后，在 plan.md 中将相应任务标记为 [x]。目标：让明确边界测试通过。

步骤 3：编写软边界测试并达到绿色基线

编写本章节中任何标记为 [seam: <id>] [firmness: soft] 的测试任务。运行测试；本章节必须达到绿色基线后才能继续。此时不要重构——重构将在下文一次性进行。勾选本章节的验证任务，然后继续处理下一章节。

所有章节完成后

有界独立审查与保持行为的修复（L3）

此流程针对整个变更仅运行一次，且为实现审批的必需环节。完整详情见 references/implementation-review.md。

1. 一次全面的发现审查。 在单独的上下文中启动一个全新的只读审计员。向其提供完整差异、相关 CONTEXT/接缝，以及仅适用于有效范围的惯用法包。按照 references/adversarial-review.md，在适用范围内深入审查数据/状态、数据结构、接口/特征、错误、安全性、可观测性、简洁性、可维护性和惯用法。无需强制填写 N/A 套话。
2. 一次汇总批次。 对所有阻断级/主要问题去重。在计划的审查表中记录稳定的 RV-NNN ID，包含严重性 blocker|major、类别 correctness|security|simplicity|maintainability|idioms、证据、具体影响和具体替代方案。不要提交细枝末节的问题，也不要启动后续批次。使用以下内容进行确认：

node "$SKILL_DIR/scripts/review-log.mjs" record --id --phase implement --cycle implement-N --role auditor
--reviewer "" --verdict changes-requested
--finding '{"id":"RV-001","severity":"major","category":"maintainability","location":"file:line","impact":"","alternative":""}'

如果没有问题，在计划中记录 `approved`，并附上简短且基于证据的理由。
3. **一次修复。** 在保持行为的前提下解决整个批次。自动选择局部/私有/可逆且符合惯用法的修复。任何越过实质性边界的修复都应退回。仅更改实现和软接缝测试。硬接缝测试必须保持通过；若失败，意味着必须停止并退回，绝不能编辑测试。
4. **完整通过测试。** 修复后运行所有适用的测试套件。
5. **针对性验证。** 启动一个不同的全新只读验证员。它只检查原有 `RV-*` ID 和保持行为的证据，不重复发现审查、不扩大范围，也不提出新的低级/主要问题：

node "$SKILL_DIR/scripts/review-log.mjs" record --id --phase implement --cycle implement-N --role verifier
--reviewer "" --verdict approved --resolution RV-001=resolved

修复导致的阻断级回归是唯一允许新增 ID 的例外：使用 `--regression` 记录，在同一针对性范围内修正，并在一次针对性重新验证期间使用 `--regression-resolution` 关闭。若任何 ID 仍未解决，或关闭问题需要进行全面审查，则停止并退回，不得延长此流程。

### 实现审批

当所有部分均已通过、有界审查/修复已完成，且已记录获批的验证员审查时：

> “所有实现部分均已完成，测试通过，独立审查已获批准。您是否批准实现审批？”

node "$SKILL_DIR/scripts/manifest-approval.mjs" --id --approval implement --approve

若此变更不存在获批的验证员审查（且该审查由不同的审计员审查支持），则不予批准。

## 退回流程

遇到以下情况时：
- 计划未涵盖的歧义
- 产物无法解决实质性边界上的决策
- 重构阶段的硬接缝测试失败（行为发生变化）
- 计划与实际情况冲突，且需要解决

**立即停止。** 不要继续，也不要自行变通。

1. 向用户清楚说明缺口。
2. 分类：这是 `defect`（规范本应发现的问题）还是 `amendment`（合理的新信息）？
3. 记录退回事项：

node "$SKILL_DIR/scripts/kickback-log.mjs" --id --type defect|amendment --phase implement --impact specify|plan|implementation
--missed "<what the spec didn't cover>"

   实质性决策发生变化时选择 `specify`；仅检查清单过时时选择 `plan`；没有上游产物失效时选择 `implementation`。脚本会记录准确的 `restart_phase` 和 `invalidated_approvals`。
4. 告知用户从记录的阶段继续，并且只需重新批准已失效的审批。
5. 在退回事项解决前，不得继续此会话。
### 文档对齐（文档审批）

从 `manifest.yaml` 加载 `manifest.context_targets`。针对每个目标 CONTEXT.md：
1. 运行 `context-verify.mjs`，建立基线：

node "$SKILL_DIR/scripts/context-verify.mjs" --path

2. 对比 `architecture.md`、`decisions.md` 和 CONTEXT.md。有哪些变化？
3. 更新 CONTEXT.md 以反映这些变化：
   - 带有牢固度标签的新接缝
   - 更新后的接口/契约
   - 新术语表词条
   - 新的验收标准（如果添加了牢固接缝）
   - 更新 `Known-soft-spots`（添加引入的任何技术债务；移除已解决的）
   - 重新标注来源信息：`Provenance: validated-at: <current HEAD sha>`
4. 运行验证子 Agent：
> “将这些 CONTEXT.md 文件与实现进行对比。文档中的声明是否与代码相符？列出所有差异。”

5. 对齐后运行 `context-verify.mjs`，在适用时包括牢固接缝测试，并处理其发现的问题。
6. 提交对齐摘要。处理所有验证结果。

询问用户：
> “CONTEXT.md 文件已完成对齐和验证。您对这项变更满意吗？（批准文档审批后，变更将进入 `archive-ready`。）”

批准后：

node "$SKILL_DIR/scripts/manifest-approval.mjs" --id --approval docs --approve

### 可归档状态与已验证归档

node "$SKILL_DIR/scripts/change-archive.mjs" --id

只有在文档审批将变更移至 `archive-ready` 后，才能运行此步骤。只有在归档验证成功且 zip 位于 `.changes/archive/<id>.zip` 时，变更才算终结。

若要改为取消，请在 `manifest.yaml` 中记录具体的 `archive.reason`，并归档当前产物，而不是删除它们。

## 牢固接缝触发器（摘要）

**绝不要为了让重构通过而编辑牢固接缝测试。** 这就是触发器。它表示：
- 这不是纯重构（行为发生了变化）→ 使用 `--impact specify` 退回。
- 或者牢固接缝本身需要变更 → 这要求遵循完整的牢固变更流程（参见 `references/firm-change-protocol.md`）、使用 `Firm-Change:` 退回，并对受影响的审批进行范围限定的重新审批。

## 参考文件

- `references/implementation-review.md` — 有界的独立实现审查和审查记录
- `references/adversarial-review.md` — 有界审查周期、审查维度和 `RV-*` 问题约定
- `references/seam-and-test-taxonomy.md` — 牢固/软性测试规则、触发器
- `references/manifest-schema.md` — 退回类型
- `references/change-lifecycle.md` — 文档对齐 + 归档
- `references/firm-change-protocol.md` — 牢固接缝必须变更时使用
- `references/drift-control.md` — CONTEXT.md 更新规则
- `idioms` skill — 匹配实现和审查指南
- `references/engineering-fundamentals.md` — 跨语言数据、状态、抽象和有界资源指南