openspec-verify-change

验证实现是否符合变更工件（规范、任务、设计）。

输入：可选指定变更名称。如果未指定，请检查能否从对话上下文中推断。若信息模糊或存在歧义，必须提示用户选择可用的变更。

步骤

1. 未提供变更名称时，提示用户选择

   运行 openspec list --json 获取可用变更。使用 AskUserQuestion tool 让用户选择。

   显示包含实现任务的变更（存在 tasks 工件）。 如果可用，注明每项变更使用的 schema。 对任务未完成的变更标记为“（进行中）”。

   重要：不要猜测或自动选择变更。始终让用户选择。

2. 检查状态以了解 schema

   openspec status --change "<name>" --json
   

   解析 JSON 以了解：

   • schemaName：所使用的工作流（例如，“spec-driven”、“tdd”）
   • 此变更包含哪些工件

3. 获取变更目录并加载工件

   openspec instructions apply --change "<name>" --json
   

   这会返回变更目录和上下文文件。读取 contextFiles 中所有可用的工件。

4. 初始化验证报告结构

   创建包含三个维度的报告结构：

   • 完整性：跟踪任务和规范覆盖情况
   • 正确性：跟踪需求实现和场景覆盖情况
   • 一致性：跟踪设计遵循情况和模式一致性

   每个维度的问题级别可以是 CRITICAL、WARNING 或 SUGGESTION。

5. 验证完整性

   任务完成情况：

   • 如果 contextFiles 中存在 tasks.md，则读取它
   • 解析复选框：- [ ]（未完成）与 - [x]（已完成）
   • 统计已完成任务数和总任务数
   • 如果存在未完成任务：
     • 为每项未完成任务添加 CRITICAL 问题
     • 建议：“完成任务：”或“如果已实现，则标记为完成”

   规范覆盖情况：

   • 如果 openspec/changes/<name>/specs/ 中存在增量规范：
     • 提取所有需求（以“### Requirement:”标记）
     • 对于每项需求：
       • 在代码库中搜索相关关键词
       • 评估实现是否可能已存在
     • 如果需求似乎尚未实现：
       • 添加 CRITICAL 问题：“未找到需求：”
       • 建议：“实现需求 X：”

6. 验证正确性

   需求实现映射：

   • 对于增量规范中的每项需求：
     • 在代码库中搜索实现证据
     • 如果找到，记录文件路径和行号范围
     • 评估实现是否符合需求意图
     • 如果发现偏差：
       • 添加 WARNING：“实现可能偏离规范：
         ”
       • 建议：“根据需求 X 检查 :”

   场景覆盖情况：

   • 对于增量规范中的每个场景（以“#### Scenario:”标记）：
     • 检查代码是否处理了相关条件
     • 检查是否存在覆盖该场景的测试
     • 如果场景似乎未覆盖：
       • 添加 WARNING：“未覆盖场景：”
       • 建议：“为以下场景添加测试或实现：”

7. 验证一致性

   设计遵循情况：

   • 如果 contextFiles 中存在 design.md：
     • 提取关键决策（查找“Decision:”“Approach:”“Architecture:”等章节）
     • 验证实现是否遵循这些决策
     • 如果发现矛盾：
       • 添加 WARNING：“未遵循设计决策：”
       • 建议：“更新实现，或修改 design.md 以符合实际情况”
   • 如果不存在 design.md：跳过设计遵循检查，并注明“没有 design.md 可供核验” 代码模式一致性：
   • 检查新增代码是否与项目模式保持一致
   • 检查文件命名、目录结构和编码风格
   • 如果发现明显偏差：
     • 添加 SUGGESTION："代码模式偏差：
       "
     • 建议："考虑遵循项目模式："

8. 生成验证报告

   摘要评分卡：

   ## Verification Report: <change-name>
   
   ### Summary
   | Dimension    | Status           |
   |--------------|------------------|
   | Completeness | X/Y tasks, N reqs|
   | Correctness  | M/N reqs covered |
   | Coherence    | Followed/Issues  |
   

   按优先级分类的问题：

   1. CRITICAL（归档前必须修复）：

      • 未完成的任务
      • 缺少需求实现
      • 每项都附带具体、可执行的建议

   2. WARNING（应当修复）：

      • 与规格/设计不一致
      • 缺少场景覆盖
      • 每项都附带具体建议

   3. SUGGESTION（修复效果更佳）：

      • 模式不一致
      • 小幅改进
      • 每项都附带具体建议

   最终评估：

   • 如果存在 CRITICAL 问题："发现 X 个严重问题。请在归档前修复。"
   • 如果只有警告："没有严重问题。还有 Y 个警告需要考虑。可以归档（但需注意所述改进）。"
   • 如果全部通过："所有检查均已通过。可以归档。"

验证启发式

• 完整性：重点检查客观的清单项（复选框、需求列表）
• 正确性：使用关键词搜索、文件路径分析和合理推断，不要要求绝对确定
• 一致性：查找明显的不一致，不要吹毛求疵地挑剔风格
• 误报：不确定时，优先使用 SUGGESTION 而非 WARNING，优先使用 WARNING 而非 CRITICAL
• 可执行性：每个问题都必须附带具体建议，并在适用时提供文件/行号引用

优雅降级

• 如果只有 tasks.md：仅验证任务完成情况，跳过规格/设计检查
• 如果有 tasks 和 specs：验证完整性和正确性，跳过设计检查
• 如果工件齐全：验证全部三个维度
• 始终说明跳过了哪些检查以及原因

输出格式

使用清晰的 Markdown，包含：

• 用于摘要评分卡的表格
• 按问题类别分组的列表（CRITICAL/WARNING/SUGGESTION）
• 格式为 file.ts:123 的代码引用
• 具体、可执行的建议
• 不要使用“考虑检查一下”这类含糊的建议