implement

实施

从 setup-project 待办列表中执行已批准的工作，不得更改范围或优先级。单独的 WORK-NNN 是一个验收单元。一个 EPIC-NNN 及其所有已批准的子项构成一个结果验收单元：在组合后的 Epic 经审查、验证、合并、核对、完成并归档之前，子项始终为暂定状态。

每个验收单元使用一个常规分支，并且不允许存在其他本地非主分支。Epic 子项绝不独立合并到主分支、发布 wiki 状态或变为 done。来自 $implement-with-subagents 的内部暂定子项或暂定独立工作包，会在该分支上执行一次串行增量，不经过审查、治理或验收关卡。

权限与批准

条目的结果、验收标准、排除项和已批准关系定义了实施范围。父 Epic 提供协调上下文，但绝不扩大子项范围。已接受的 wiki 和仓库说明定义了当前状态基线和工程约束。

此调用是一项有门槛的执行工作流：它授权对所选已批准范围进行临时认领、清单留证和常规执行状态转换——但不授权更改结果或验收措辞、优先级、父子关系、关联关系、取消状态、子项范围或已接受的 wiki 知识。将拟议的取消和范围外决策保留在待办列表中，并暂停以等待负责人批准。除非已获得明确批准，否则必须针对确切的持久化 wiki 更新取得明确批准。

在 $to-product 下，其自主契约涵盖 PRD 所需的所有可由用户授权的决策，包括记录／Epic 调整、取消、恢复、wiki 更新、验收和关闭。它绝不授权无关或超出 PRD 范围的实施；将相邻范围标记为 proposed。

权限包的新鲜度

在本次调用中已完整读取的权限来源——记录、索引、wiki 概念、ADR、指导页面或源文件——应视为已读取；重复读取属于浪费。从此处调用的技能应接受本次调用已解析的权限包路径和角色，而不是重新发现它们。新鲜度按调用计算：绝不跨调用沿用，也绝不假定子 Agent 已掌握这些内容。

出现以下任一情况时，已读取的权限来源即失效，必须重新读取：

• 自读取后，上下文被总结或压缩；
• 分支发生变化，或有合并落地；
• 非本次调用所做的提交触及了该路径；
• 任何事务修改了该记录；
• 认领已过期或已续期；
• 自读取后，node scripts/validate-project.mjs 验证失败；
• 固定点发生变化。

每次选择和终态转换前，都要检查自上次读取以来的 git log -- docs/backlog：仅当非本次调用所做的提交触及相关内容时，才重新读取全局优先级、认领、状态和索引。若无法确定新鲜度，则重新读取。

**验证结果的新鲜度：**完整测试套件通过，即表示已验证受测试的代码影响输入内容：源代码、测试、依赖清单／锁文件、运行时／构建配置、生成的运行时产物，以及相关环境配置。记录受测提交和受影响路径分类。仅当这些输入仍与该状态一致时，才可复用测试结果；待办、wiki 和非可执行文档可以不同。合并后，将合并后的代码影响输入与受测分支状态进行比较，而不是比较整个工作树的哈希值。只要其中任一项不同，或分类不确定，就重新运行测试。

预检

在创建或切换分支，或修改认领之前完成：

1. 确定仓库根目录。阅读所有适用的 AGENTS.md、CLAUDE.md、嵌套说明以及贡献或编码标准。
2. 要求使用 $setup-project 脚手架及其当前 Epic 验收单元生命周期：一个启动事务、临时子项、批量清单证据，以及原子化的最终验收／归档。如果缺少文件，或项目本地维护仍要求逐个子项提交验收／证据，则停止，并要求 $setup-project 升级并协调相关内容。
3. 运行 node scripts/validate-project.mjs；如果基线无效，则报告并停止，除非用户明确要求修复该状态。
4. 检查当前分支、主分支、本地分支、远程仓库、已暂存／未暂存更改以及近期历史。遵守 $create-conventional-branch 的不变量。保留无关更改；绝不暂存这些更改。
5. 确定选择项：明确指定的 ID 或路径优先；否则，只接受对话中唯一明确的选择。若未指定或存在歧义，则列出候选项并询问。
6. 完整阅读选定记录、父 Epic 及 Epic 范围内的所有子项、全局排序、活动索引、所有相关记录，以及计算入向阻塞项所需的全部记录。仅在归档步骤需要写入归档索引时才读取该索引。
7. 阅读待办事项维护说明、适用的类型模板、所有关联的 wiki 概念及最近的索引、wiki 维护说明、相关工程与架构指南、ADR 索引 docs/wiki/architecture/decisions/index.md、记录中起草的 ## Decisions、提案研究与本地证据，以及受影响的仓库代码和测试。只有当某条现行 ADR 的主题与事项变更或起草的决策相关时，才打开该 ADR。
8. 阅读 docs/wiki/engineering/technologies/ 和 docs/wiki/engineering/standards/ 下所有适用的指南——根据事项变更涉及的每项技术和跨领域标准，从各自目录索引确定相应页面，而非读取全部页面。指南的约束力遵循 docs/wiki/maintenance.md § Adopted guidance；列出的 Known gap 表示现有不合规，必须设法绕开，绝不能以此为由引入更多不合规。若涉及的主题没有对应页面或页面已过时，则这是需要报告的缺口：依据事项的研究和仓库证据实施，并在验收后的 $guidance 提议和最终报告中指出；绝不能因此阻塞，也不能在此处向 docs/wiki 写入指南。
9. 确定本次调用的主分支固定点；在审查和集成证据中保留该固定点。对于 Epic，它也是最终 Epic 审查不可变的 Epic 固定点；不能以各个子项的固定点取而代之。

在此检查受影响的代码、测试和指南。仅当存在至少两个具体的只读问题或无副作用检查时，才使用 $parallel-execution。所有变更操作都必须串行执行；内部临时工作者不得委派任务。

内部临时数据包只有在注明编排者的活动会话、验收单元、唯一分支、预期 HEAD、声明、固定点、权限数据包和模式（child 或 standalone）时才有效。工作者无权拥有或更改声明。

创建分支前拒绝：

• 状态明确为 proposed、done 或 cancelled 的条目；
• 状态不是 ready 的条目，除非它是此执行器／会话拥有的当前验收单元，或受有效的内部临时数据包覆盖；
• 缺少任何就绪定义字段、客观标准、获批执行方案、验证命令、优先级条目、已解决的父级／关系、已完成或无需开展的研究，或已解决的 decisions 的 ready 条目；
• ## Subtasks 过于粗略、无法拆分为可检查的执行增量的 ready 条目——任何缺少范围或验证方式的子任务均不符合要求，除非该部分内容恰好是 No subtasks.；
• 存在未解决的向内 blocks 关系的 ready 条目；
• 格式错误的记录、无效项目、已过期的认领，或认领／状态不匹配；
• 由其他执行器持有的任何有效认领——绝不覆盖；
• 状态不是 ready 且并非正在继续执行该 in-progress Epic 的 Epic，或没有已获批子项的 Epic；
• Epic 范围中包含由其他执行器认领的必需非终态子项。

内部临时例外仅更改认领所有权和分支匹配要求；所有就绪状态、阻塞项、范围、权限和验证检查仍然适用。

报告所有阻塞记录、冲突认领／过期信息、格式错误的字段或所有者决策。拒绝后不要使用单独的 blocked 状态，也不要创建分支。使用 $to-product 时，按其约定修复所有仅由工作流导致的拒绝，重新验证，然后继续。

Epic 模式

当调用解析为 EPIC-NNN 时，完成预检后、选择第一个子项前，阅读 references/epic-mode.md；该文档规定了子项选择顺序以及 Epic 的完成和清理流程。调用 WORK-NNN 时绝不阅读该文档。

Epic 串行顺序

处理每个子项前，针对当前分支重新验证可执行性、依赖关系、共享接口和冲突域。

在本地实现优先级最高且可执行的子项，或让 $implement-with-subagents 将其分配给一名新的工作者。完成该子项并验证其提交后，再开始另一个子项。此调用负责保留认领、权限、审查、协调、集成和验收。

分支与认领

预检后：

1. 对于内部临时数据包，验证指定分支和精确的 HEAD，不得更改治理信息。否则，仅当唯一的验收分支、会话和有效认领均匹配时才继续；或者对独立条目或 Epic 调用一次 $create-conventional-branch。
2. 对于常规的独立条目或 Epic 调用，将认领期限设为足以覆盖整个执行单元。认领独立条目并将其从 ready 移至 in-progress；或者将 Epic 及其必需的非终态子项移至 in-progress，并为每个子项认领同一会话／验收分支。Epic 没有认领字段。
3. 对于常规调用，在 ## Execution 中记录一次分支／会话信息；运行 node scripts/validate-project.mjs；仅暂存受影响的待办路径；验证差异；提交这笔单独的启动事务。内部临时数据包跳过第 2–3 步，直接进入执行阶段。

常规执行期间不要写入待办证据。续期、安全释放或阻塞项恢复均属于例外情况下经过验证的事务，而非常规门槛。绝不要在认领过期后继续，也不要更改其他执行器的认领。

执行

对于独立事项、内部临时任务包，或通过 Epic 模式 选定的每个本地负责的 Epic 子项：

1. 记录其变更开始时对应的代码提交。遵循已批准的方案和子任务；先实现并冒烟测试实际变更路径。对于 Bug，记录成本最低且可靠的修复前失败复现。
2. 提交连贯的代码增量。先稳定一个增量，再运行受影响范围最小的检查。每项适用的 lint 或类型检查只运行一次；仅在检查失败或后续变更导致检查结果失效时重新运行。只有在不存在共享的可变缓存、输出、端口、数据库、模拟器或仓库状态时，才能并行运行确定性检查。此处不要运行完整测试套件或范围广泛的平台矩阵。
3. 复用现有覆盖。仅当新的可观察契约缺少验证时，才添加一个持久测试：优先选择验收关键的 E2E，其次是集成/契约测试，最后才是用于验证其他方式难以覆盖边界情况的单元测试。切勿重复测试层级、追求覆盖率、强制采用功能 TDD，或添加过多 E2E 测试。
4. 尽可能将仅用于验证的可执行文件保存在工作区之外；否则在验收前将其移除。只有在常规测试位置和既有命令中用于保护可观察契约时，才保留此类文件。
5. 仅从实时注册表固定未解决的依赖或工具版本，并保留来源和日期证据。
6. 在调用台账、可选的自主运行记录或最终记录编辑中汇总验收标准、子任务、提交、专项检查和冒烟测试的证据。不要按子任务或子项修改或提交待办记录。
7. 切勿扩大范围。若相邻变更构成阻碍，必须先进行已批准的待办事务。

内部临时调用在完成上述步骤后即停止，并向编排器返回提交和简明证据；绝不触及 review、primary、wiki、rank、claims、状态或归档。

审查与最终验证

每个验收单元恰好运行一次全面的 $code-review：独立事项在结束时运行，组合 Epic 在收尾时运行。在活动 Epic 验收单元内，绝不单独审查临时子项。涉及安全/身份验证、破坏性迁移或可信的数据丢失风险，以及公共 API 兼容性的事项，应选择审查的 Standards/Spec 拆分模式；这些情况绝不额外增加审查次数。

修复所有范围内的问题，直接检查修复差异，并仅重新运行受影响的检查。绝不调用修复审查或增量审查。如果修复需要未经批准的范围变更，则停止。

审查问题修复稳定后，每个验收单元在一个有代表性的受支持目标上运行一次完整测试套件。只有当变更代码涉及平台特定行为、自适应布局、兼容性、打包、迁移或其他对矩阵敏感的契约时，才扩展设备/运行时范围；记录每个维度适用的原因。发布结果始终运行完整的受支持矩阵。之后不得再进行影响代码的变更；若无法避免的变更导致测试套件失效，则重新运行并报告例外。待办事项、wiki、运行记录及其他不可执行的文档不会导致测试套件失效。

对账

验收单元完成审查和验证后，将完整实现与关联的 wiki 概念、研究、指南和已起草的决策对照一次：

• 没有持久性变更 → 记录 wiki reconciliation: no update required，并说明原因。
• 有持久性变更 → 以仅提案模式调用 $wiki，并起草一项精确的已接受状态事务，涵盖独立条目或整个 Epic。纳入所有已批准的子项/Epic 决策以及任何 ADR 替代；发布前不得分配 ADR ID。
• 对组合后的实现应用 ADR 重要性测试。若新出现的重要决策不在已批准范围内，则必须先有已批准的待办事项草案，才能验收。
• 如果措辞声称了 wiki_refs 之外的知识、与现行 ADR 相矛盾，或记录从未包含该内容，则暂停并等待所有者批准。

在最终事务完成前，将提案以及所有标准/子任务/审查/套件证据保留在调用台账中。绝不在工作分支上编辑已接受的 wiki 状态，也绝不单独提交完成证据。

验收与完成

对于独立条目或完整 Epic：

1. 确认实时声明；受支持的标准和子任务；一次全面审查；一次全新、有代表性的完整套件运行及有理据的矩阵扩展；精确对账；验证器通过；以及没有非预期变更。
2. 通过一次合并提交将验收分支合并到主分支，绝不 squash 或快进。将影响代码的输入与已验证的分支状态进行比较。如果一致，则复用套件；如果不同或分类不确定，则仅重跑受影响的针对性检查或套件。
3. 在主分支上运行 node scripts/validate-project.mjs。不可执行的待办事项、wiki、转录或文档变更绝不会使可执行验证失效。
4. 在主分支上应用一项已批准的 wiki 事务。发布所有已起草的 ADR，更新索引/日志，运行验证，并且只提交 wiki 路径。仅提供一次缺失或过时的验收后指南。仅有 wiki 变更后不要重跑可执行套件。
5. 应用一项已验证的最终待办事项事务。对于独立条目：写入累积的证据、清除其声明、解决决策、设为 done、移除排名，并将其归档。对于 Epic：写入累积的 Epic/子项证据、清除所有声明、解决所有决策、将每个子项和 Epic 设为 done、移除所有排名、将整个 Epic 目录移至 archive/epics/，并以原子方式更新索引。若提供了自主运行转录，则一并纳入。
6. 仅暂存最终事务路径，验证差异，并提交一次。绝不要提前将任何 Epic 子项标记为 done。

如果合并、授权、对账或必要检查失败，则在设为 done 前停止。暂停时，遵循 $create-conventional-branch 的恢复流程，释放声明，将未完成记录恢复为 ready，并移除验收分支。

完成与报告

最终事务和验证完成后，遵循 $create-conventional-branch 的已接受清理流程，并留在主分支。报告范围；分支和声明；子项顺序；提交；审查；套件和矩阵的理由；验收合并；对账/ADR；治理事务；归档；指南缺口；以及阻碍因素。

以 Next step: 结尾——受阻时给出精确的恢复命令；否则使用 $implement 处理排名最高的下一个独立条目或 Epic，或使用 $discuss 指明下一个未完成的结果。