openspec-verify-change

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

存储库选择： 如果用户指定了存储库（存储库是此计算机上注册的独立 OpenSpec 仓库），或工作所在的位置属于某个存储库，请运行 openspec store list --json 以查找已注册的存储库 ID，然后在读取或写入规范和变更的命令（new change、status、instructions、list、show、validate、archive、doctor、context、schemas、view）中传入 --store <id>。选定后，在后续工作流中始终使用 --store <id>。下方这些命令未指定存储库的示例均为简写：运行前请追加该标志。例如，运行 openspec status --change "<name>" --json --store "<id>"，而非下方所示的未指定存储库形式。其他命令不接受此标志。命令打印的提示中已包含该标志；后续命令也请保留此标志。如果未指定存储库，命令会作用于最近的本地 openspec/ 根目录。

输入：可以指定变更名称。如果省略，请检查能否从对话上下文中推断。如果含糊不清或存在歧义，你必须询问用户有哪些可用变更。

步骤

1. 选择变更

   如果已提供名称，请使用该名称。否则：

   • 如果用户在对话上下文中提到了变更，则据此推断
   • 如果只有一个进行中的变更，则自动选择
   • 如果存在歧义，请运行 openspec list --json 获取可用变更，并让用户选择一个

   提示用户时，显示包含实现任务的变更（存在 tasks 产物）。 如果可用，请一并显示每个变更使用的 schema。 将任务尚未完成的变更标记为“（进行中）”。

   始终宣布：“使用变更：”，并说明如何切换（例如，/openspec-verify-change <other>）。

2. 检查状态以了解 schema

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

   解析 JSON，了解：

   • schemaName：所使用的工作流（例如，“spec-driven”）
   • planningHome、changeRoot、artifactPaths 和 actionContext：路径和范围上下文
   • 此变更中存在哪些产物

3. 获取规划上下文并加载产物

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

   这会返回变更目录和 contextFiles（产物 ID -> 具体文件路径数组）。读取 contextFiles 中所有可用的产物。

4. 初始化验证报告结构

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

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

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

5. 验证完整性

   任务完成情况：

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

   规范覆盖情况：

   • 如果 contextFiles.specs 中存在增量规范：
     • 提取所有需求（以“### Requirement:”标记）
     • 对每项需求：
       • 在代码库中搜索与需求相关的关键词
       • 评估是否可能已实现
     • 如果需求看起来尚未实现：
       • 添加 CRITICAL 问题：“未找到需求：”
       • 建议：“实现需求 X：”

6. 验证正确性

   需求实现映射：

   • 对增量规范中的每项需求：
     • 搜索实现证据
     • 如果找到，记录文件路径和行号范围
     • 评估实现是否符合需求意图
     • 如果发现偏差：
       • 添加 WARNING：“实现可能偏离规范：
         ”
       • 建议：“根据需求 X 检查 :” 场景覆盖：
   • 对 delta 规范中的每个场景（标记为“#### Scenario:”）：
     • 检查代码是否处理了相关条件
     • 检查是否有测试覆盖该场景
     • 如果发现某个场景未覆盖：
       • 添加 WARNING：“Scenario not covered: ”
       • 建议：“Add test or implementation for scenario: ”

7. 验证一致性

   遵循设计：

   • 如果存在 contextFiles.design：
     • 提取关键决策（查找“Decision:”“Approach:”“Architecture:”等章节）
     • 验证实现是否遵循这些决策
     • 如果发现矛盾：
       • 添加 WARNING：“Design decision not followed: ”
       • 建议：“Update implementation or revise design.md to match reality”
   • 如果不存在 design.md：跳过设计遵循检查，并注明“No design.md to verify against”

   代码模式一致性：

   • 检查新增代码是否与项目模式一致
   • 检查文件命名、目录结构和编码风格
   • 如果发现明显偏差：
     • 添加 SUGGESTION：“Code pattern deviation:
       ”
     • 建议：“Consider following project pattern: ”

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：只验证任务完成情况，跳过规范／设计检查
• 如果存在任务和规范：验证完整性和正确性，跳过设计检查
• 如果存在完整的制品：验证所有三个维度
• 始终注明跳过了哪些检查及原因

输出格式

使用清晰的 Markdown，包含：

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