anian0/plan-execution-v2

计划执行 v2

直接实施已确认的任务计划，并用真实证据验证。主 agent 对执行端到端负责。subagent 可以用于审查或调查，但不能替代真实实现和验证。

先读取

执行前读取这些引用：

• ../project-development-v2-common/references/no-simulation-policy.md
• ../project-development-v2-common/references/delivery-contract.md
• references/execution-checklist.md

核心规则

• 必须从包含 index.md 和 T-* 任务文件的 v2 计划目录开始。
• 执行前必须检查计划是否有审查记录；没有审查记录时，先做最小计划审查，发现阻塞级缺口则停止并说明。
• 执行前只读 index.md，向用户确认计划理解、任务数量、验证数量、测试资产规划、特别关注点和执行顺序；用户确认后才能修改代码。
• 执行过程中不提交 git，除非用户明确要求提交。
• 使用 index.md 管理任务顺序和状态。
• 读取当前 T-* 文件；有歧义时再读取来源需求和技术方案。
• 默认由主会话直接编辑代码，除非用户明确要求委派。
• subagent 只用于聚焦代码审查、调查或独立验证。
• 只有实现完成且验证证据已记录，任务才能标记完成。
• 不得把 mock、stub、fallback、伪造输出、未检查 UI 或未运行测试当作完成。
• done 是强状态，只能在实现、真实依赖接入、反模拟扫描、任务验证和证据记录全部通过后使用。
• build、typecheck、lint 只能作为基础验证；除非任务本身只要求构建，否则不能单独证明 API、数据、MCP、调度、诊断、UI 或跨服务链路完成。
• 任务要求数据库、外部服务、MCP、队列、文件系统、共享契约、诊断日志或 UI 状态时，必须证明真实接入；只创建接口、类型、空壳或内存实现不得标记 done。
• 任务验收包含失败、超时、无效引用、隔离、诊断、禁用、撤回、压缩或来源追溯时，必须验证对应负向路径；只验证 happy path 不得标记 done。
• 新增测试、fixtures、review 清单和 smoke 脚本必须落到计划指定的 workplace/<version>/test/ 子目录；源码旁新增测试必须有计划中的明确例外。
• 任务标记 done 前必须完成独立审核。可由主 agent 重新审查、调用 project-development-review-v2，或委派 subagent；不得只相信实现报告。
• 如果验证无法运行，标记为 not_verified 并写清阻塞原因。
• 如果计划包含最终闭环/放行门槛，未执行或未通过前不得宣布整体完成。

流程

1. 按 delivery-contract.md 解析真实版本目录；在 workplace/<version>/plan/ 找到计划目录，或使用用户给定路径。
2. 读取 index.md。
3. 检查 审查记录、覆盖审计、测试资产规划、最终闭环/放行门槛和风险阻塞。
4. 向用户确认计划理解：计划路径、任务数量、验证数量、测试资产根目录、特别关注点、执行顺序和已发现风险。
5. 如果用户确认开始，继续；如果用户调整范围，先更新计划。
6. 如果发现任务缺少文件、契约、验证、测试资产或闭环，先做最小计划修正；如果影响范围、数据模型、兼容性、安全或预期 UX，停止询问用户。
7. 选择第一个状态为 todo 或 in_progress 的任务。
8. 将任务状态更新为 in_progress。
9. 读取任务文件和必要上下文。
10. 检查任务文件中的占位路径；不得把 <version>、1.X 或其他占位路径传入执行。
11. 按正常代码编辑流程实现任务。
12. 运行任务定义的验证命令或步骤；同一验证失败最多连续修复三轮。
13. 执行 done 前硬门禁：
    • 反模拟扫描。
    • 真实依赖接入检查。
    • 正向和必要负向路径验证。
    • 测试资产目录合规检查。
    • 独立任务审核。
    • 证据日志完整性检查。
14. 在任务范围内修复失败。
15. 填写任务文件中的 证据日志。
16. 更新 index.md 状态：
    • 验证通过才写 done。
    • 已实现但无法验证写 not_verified。
    • 无法继续实现写 blocked。
    • 存在模拟实现、内存替代持久化、空校验或缺少负向验证时，保持 in_progress 或写 not_verified，不得写 done。
17. 用户没有要求停止时，继续下一个任务。
18. 所有普通任务结束后，执行最终闭环/放行任务。
19. 运行 index.md 中的全局验证。
20. 执行最终审核，检查需求/验收覆盖、任务状态、测试资产完整性、跨任务接口一致性、特别关注点和最终闭环证据。
21. 最终审核通过后总结剩余风险。

证据要求

每个任务记录：

• 修改文件。
• 执行过的命令。
• 关键输出或结果。
• 用户可见任务的 UI/浏览器证据。
• 跳过的验证及阻塞原因。
• 与计划的偏差。
• done 前硬门禁结果：
  • 反模拟扫描命中项和处理结论。
  • 真实依赖接入证据。
  • 正向/负向验证证据。
  • 测试资产目录合规证据。
  • 独立审核结论。

不要粘贴大段日志，只保留能证明验证真实发生的关键信息。

处理计划问题

如果计划错误或不完整：

• 不要静默发明新范围。
• 做能继续执行的最小计划修正。
• 在 index.md 或任务文件中记录修正。
• 只要不改变产品范围或主要设计决策，可以继续。
• 如果修正影响范围、数据模型、兼容性、安全或预期 UX，必须询问用户。
• 如果任务文件或命令中出现 <version>、1.X 等未替换占位符，先替换为当前计划真实版本路径；无法确定版本时停止询问用户。

测试资产目录

执行时遵循计划中的测试资产规划。默认根目录：

workplace/<version>/test/
├── backend/unit/
├── backend/integration/
├── frontend/unit/
├── frontend/component/
├── contract/
├── smoke/
├── review/
├── fixtures/
└── README.md

规则：

• 本计划新增测试、fixtures、review 清单、smoke 脚本必须放到该目录下。
• 如果目录不存在，第一个需要新增测试资产的任务负责创建骨架和 README.md。
• README.md 必须记录运行命令矩阵、依赖前置条件和覆盖的 V-*。
• 源码旁新增测试只有在计划写明项目规范要求时才允许，并必须在证据日志标明例外。
• 独立审核必须检查新增测试文件位置是否合规。

验证标准

使用任务可行范围内最强的验证：

• 有单元、集成或契约测试时运行它们。
• 变更触及共享行为时，运行 build、typecheck 或 lint。
• UI 任务可行时检查真实渲染页面。
• API 任务可行时调用真实本地 handler/server 或运行集成测试。
• 数据迁移可行时，在真实本地/测试数据库验证 schema 或数据影响。
• 任务要求持久化时，必须证明数据经过真实 repository、数据库或文件存储，并能重新查询；内存 Map、模块级 dict、数组只能作为缓存，不能作为计划要求的持久化。
• 任务要求外部 MCP 或 tool 调用时，必须证明真实 client/adapter 的 discover/list/call 路径；固定返回、回显参数或“模拟 handler”不能通过。
• 任务要求引用校验时，必须证明有效引用通过、无效引用失败；空实现、恒真/恒假返回不能通过。
• 任务要求 diagnostics、日志或事件时，必须证明成功和失败都能写入并查询。
• 任务要求共享契约时，必须证明下游服务、前端或生成代码实际消费该契约。

如果验证依赖不可用服务或凭据，说明缺少什么，并标记 not_verified。

done 前硬门禁

每个任务标记 done 前必须逐项检查，并把结果写入证据日志。

1. 反模拟扫描

检查本任务修改范围内是否出现或保留：

• mock、stub、fake、dummy、placeholder、fallback、hardcoded。
• 模拟、占位、临时、固定返回、回显。
• TODO、return []、return true、return false、空校验函数。
• 模块级 Map、dict、数组等替代计划要求的持久化。

命中不一定自动失败，但必须解释为什么不是完成捷径。解释不成立时不得 done。

2. 真实依赖接入证明

按任务要求证明真实依赖已经接上：

• 数据库：schema/repository/迁移/读写查询证据。
• MCP/tool：真实 connect/list/call 或 adapter 调用证据。
• 调度任务：真实 handler registry、任务配置校验和执行证据。
• sandbox/daemon：真实进程或 handler 调用、失败和超时返回语义证据。
• 共享契约：实际 import、生成代码、OpenAPI/schema 消费证据。
• 前端：真实页面请求真实 API 并渲染状态的证据。

只有类型定义、空 service、内存存储或固定响应，不能算真实接入。

3. 验证覆盖

验证必须覆盖任务承诺的行为：

• 至少覆盖一个正向路径。
• 如果计划或验收提到失败、超时、诊断、无效引用、隔离或禁用，必须覆盖对应负向路径。
• 如果任务写入数据、日志、事件或 diagnostics，必须再通过查询证明可回查。
• 如果没有测试文件或 smoke 脚本，要说明为什么不可行，并标记 not_verified，不能仅靠 build/typecheck 写 done。

4. 测试资产合规

检查：

• 每个新增测试、fixture、review 清单或 smoke 脚本都位于计划指定的 workplace/<version>/test/ 子目录。
• 测试类型和目录匹配：unit、integration、contract、component、smoke、review、fixtures。
• README.md 包含本任务新增命令或步骤。
• 源码旁新增测试有计划例外和理由。
• 每个相关 V-* 能追踪到测试资产或明确的验证步骤。

不合规时不得 done。

5. 独立任务审核

任务完成前必须独立审核：

• 对照当前任务的 R-*、A-*、C-*、V-* 检查功能覆盖。
• 重新检查关键实现路径，不只相信执行报告。
• 复核反模拟扫描、真实依赖接入、测试资产目录和负向验证。
• 检查特别关注点是否落实。
• 审核未通过时保持 in_progress 或 not_verified。

6. 状态回滚

如果后续审查发现 done 不成立：

• 立即把任务状态改回 in_progress、not_verified 或 blocked。
• 在任务证据日志追加审查发现编号、原因和下一步。
• 同步更新 index.md 的总览状态。
• 阻塞级 REV-* 未解决前，不得继续把相关下游任务标记为整体完成。

验证失败处理

• 同一个验证连续失败时，最多修复三轮。
• 每轮必须记录失败命令、关键错误、修复摘要和再次验证结果。
• 三轮仍未通过时，停止该任务，标记 blocked 或 not_verified，向用户报告已尝试修复、推测根因和可选下一步。

最终审核

整体完成前必须执行最终审核。审核内容：

• 每个 R-* / A-* 是否有完成任务和通过验证。
• 每个 C-* / V-* 是否有执行证据。
• 所有 done 任务是否有 done 前硬门禁记录。
• 测试资产目录是否完整，README.md 是否包含命令矩阵。
• 跨任务接口、字段、数据格式和状态是否一致。
• 特别关注点是否落实。
• 最终闭环/放行任务是否真实通过。

发现阻塞问题时，按“状态回滚”处理，不得宣布整体完成。

完成标准

单任务完成必须同时满足：

• 代码已修改。
• 必要验证已通过；验证无法运行时不得写 done，只能写 not_verified。
• done 前硬门禁全部通过。
• 独立任务审核通过。
• 通过证据已记录。
• 没有用捷径替代计划需求。
• 没有隐藏无关重构或范围扩张。

最终完成必须满足：

• 所有任务为 done，或明确说明未完成状态。
• 全局验证已运行，或因阻塞标记 not_verified。
• 最终闭环/放行门槛已通过，或明确标记 not_verified 并说明不能整体放行。
• 最终审核通过。
• 最终总结把完成情况映射回 R-*、C-*、T-* 和 V-*。