piv-implement

Execute：根据计划实施

要执行的计划

读取计划文件：$ARGUMENTS

开始前——在功能分支上工作

每个工单都应在自己的分支上实现，这样就能对应一个 PR。**理想情况下，你应该已经在该分支上——请在制定计划之前创建分支——这样，你提交的计划也会包含在该分支中，并随之进入 PR；如果计划提交在基准分支上，就不会包含在这个分支的 PR 中。**如果你仍在基准分支上，此步骤会立即创建分支。检测基准分支（不要硬编码 main）：git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' （回退值为 main）。

• 在基准分支上，工作区干净 → 创建一个分支：git checkout -b feature/<plan-slug>。
• 已经在功能分支或工作树中 → 使用当前分支或工作树。
• 在基准分支上，且有未提交的更改 → 停止：先提交或暂存更改。

（每个工单使用一个分支，也能让之后的并行工作树保持整洁。）

执行说明

1. 阅读并理解

• 仔细阅读整个计划
• 理解所有任务及其依赖关系
• 记下要运行的验证命令
• 查看测试策略

2. 按顺序执行任务

对于“逐步任务”中的每个任务：

a. 前往任务

• 确定所需修改的文件和操作
• 如果要修改文件，先阅读相关的现有文件

b. 实施任务

• 严格遵循详细规范
• 与现有代码模式保持一致
• 添加适当的类型提示和文档
• 适当添加结构化日志

c. 随做随验证

• 每次修改文件后检查语法
• 确保导入正确
• 确认类型定义正确
• **开始下一个任务前，运行当前任务自己的 VALIDATE 命令。**计划中的每个任务都包含一个该命令。 检查通过后，任务才算完成；如果失败，立即修复，不要把问题留到后续步骤。 第 4 步仍会运行完整测试套件；这项逐任务门槛可避免第 4 步的问题堆积。

3. 实施测试策略

完成实现任务后：

• 创建计划中指定的所有测试文件
• 实施提及的所有测试用例
• 遵循所述测试方法
• 确保测试覆盖边缘情况

4. 运行验证命令

按计划中的顺序执行所有验证命令：

# Run each command exactly as specified in plan

如果任何命令失败：

• 修复问题
• 重新运行命令
• 仅在命令通过后继续

5. 最终验证

完成前：

• ✅ 已完成计划中的所有任务
• ✅ 已创建所有测试，且测试均通过
• ✅ 所有验证命令均已通过
• ✅ 代码符合项目规范
• ✅ 已根据需要添加或更新文档

输出——撰写实施报告

将简短报告写入 .claude/reports/<plan-slug>-report.md（并打印摘要）。PR 正文和 piv-review-pr 门禁会读取这份报告，尤其是偏差（有记录的偏差属于有意决定，审核者不应将其标记出来）：

# Implementation Report — <feature>

**Plan**: <path>   **Branch**: <feature/...>   **Status**: COMPLETE | PARTIAL

## Summary
{What was built, 2-4 sentences.}

## Tasks completed
- [task] → `path/to/file` (CREATE/UPDATE)

## Tests added
{Test files + cases + results.}

## Validation results
{Type-check / lint / tests / build — pass/fail with counts.}

## Deviations from the plan
{What changed vs the plan and WHY — or "none". This is the reviewer's signal of intent.}

## Issues encountered
{Anything notable, or "none".}

准备进行下一步

• 确认所有更改均已完成，且验证均已通过。
• 下一步：先对工作执行 piv-commit，然后运行 piv-create-pr 创建 PR（报告内容会填入 PR 正文），再运行 piv-review-pr。

注意事项

• 遇到计划未涉及的问题时，请记录下来
• 如需偏离计划，请说明原因
• 如果测试失败，请修复实现，直到测试通过
• 不要跳过验证步骤