name: openspec-verify-change description: 验证实现是否匹配变更制品。当用户想要在归档之前验证实现是否完整、正确和一致时使用。 license: MIT compatibility: 需要 openspec CLI。 metadata: author: openspec version: “1.0” generatedBy: “1.0.0”

验证实现是否匹配变更制品（规格、任务、设计）。

输入：可选指定变更名称。如果省略，检查是否可以从对话上下文推断。如果模糊或模糊不清，必须提示可用变更。

步骤

如果没有提供变更名称，提示选择

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

显示具有实现任务的变更（存在任务制品）。

如果可用，包括每个变更使用的模式。

标记具有不完整任务的变更为“（进行中）”。

重要：不要猜测或自动选择变更。始终让用户选择。
检查状态以理解模式
```
openspec status --change "<name>" --json
```
解析 JSON 以理解：
- schemaName：正在使用的工作流（例如，“spec-driven”、“tdd”）
- 哪些制品存在于此变更
获取变更目录并加载制品
```
openspec instructions apply --change "<name>" --json
```
这返回变更目录和上下文文件。从 contextFiles 中读取所有可用制品。
初始化验证报告结构

创建一个具有三个维度的报告结构：
- 完整性：跟踪任务和规格覆盖
- 正确性：跟踪需求实现和场景覆盖
- 一致性：跟踪设计遵循和模式一致性
每个维度可以有 CRITICAL、WARNING 或 SUGGESTION 问题。
验证完整性

任务完成：
- 如果 contextFiles 中存在 tasks.md，读取它
- 解析复选框：- [ ]（不完整） vs - [x]（完成）
- 计算完成与总任务数
- 如果存在不完整任务：
  - 为每个不完整任务添加 CRITICAL 问题
  - 建议：“完成任务：<描述>”或“如果已实现，标记为完成”
规格覆盖：
- 如果 openspec/changes/<name>/specs/ 中存在 delta specs：
  - 提取所有需求（标记为“### Requirement:”）
  - 对于每个需求：
    - 在代码库中搜索与需求相关的关键词
    - 评估实现是否可能存在
  - 如果需求似乎未实现：
    - 添加 CRITICAL 问题：“需求未找到：<需求名称>”
    - 建议：“实现需求 X：<描述>”
验证正确性

需求实现映射：
- 对于 delta specs 中的每个需求：
  - 在代码库中搜索实现证据
  - 如果找到，记录文件路径和行范围
  - 评估实现是否匹配需求意图
  - 如果检测到差异：
    - 添加 WARNING：“实现可能偏离规格：<细节>”
    - 建议：“审查 <文件>:<行> 与需求 X”
场景覆盖：
- 对于 delta specs 中的每个场景（标记为“#### Scenario:”）：
  - 检查条件是否在代码中处理
  - 检查是否存在覆盖场景的测试
  - 如果场景似乎未覆盖：
    - 添加 WARNING：“场景未覆盖：<场景名称>”
    - 建议：“为场景添加测试或实现：<描述>”
验证一致性

设计遵循：
- 如果 contextFiles 中存在 design.md：
  - 提取关键决策（查找像“Decision:”、“Approach:”、“Architecture:”这样的部分）
  - 验证实现是否遵循这些决策
  - 如果检测到矛盾：
    - 添加 WARNING：“设计决策未遵循：<决策>”
    - 建议：“更新实现或修订 design.md 以匹配现实”
- 如果没有 design.md：跳过设计遵循检查，备注“没有 design.md 可验证”
代码模式一致性：
- 审查新代码以保持与项目模式的一致性
- 检查文件命名、目录结构、编码风格
- 如果发现显著偏差：
  - 添加 SUGGESTION：“代码模式偏差：<细节>”
  - 建议：“考虑遵循项目模式：<示例>”
生成验证报告

摘要计分卡：
```
## 验证报告：<变更名称>

### 摘要
| 维度     | 状态          |
|----------|---------------|
| 完整性 | X/Y 任务，N 需求|
| 正确性 | M/N 需求覆盖  |
| 一致性 | 遵循/问题     |
```
按优先级分类的问题：
1. CRITICAL（归档前必须修复）：
  - 不完整任务
  - 缺失需求实现
  - 每个都有具体的、可操作的建议
2. WARNING（应该修复）：
  - 规格/设计差异
  - 缺失场景覆盖
  - 每个都有具体建议
3. SUGGESTION（最好修复）：
  - 模式不一致性
  - 小改进
  - 每个都有具体建议
最终评估：
- 如果有 CRITICAL 问题：“找到 X 个关键问题。在归档前修复。”
- 如果只有 warnings：“没有关键问题。有 Y 个警告需要考虑。准备好归档（带有注释的改进）。”
- 如果全部清晰：“所有检查通过。准备好归档。”

验证启发式方法

完整性：专注于客观清单项（复选框、需求列表）
正确性：使用关键词搜索、文件路径分析、合理推断 - 不需要完美确定性
一致性：寻找明显的矛盾，不要挑剔风格
假阳性：当不确定时，优先使用 SUGGESTION 而不是 WARNING，WARNING 而不是 CRITICAL
可操作性：每个问题必须有具体的建议，带有文件/行引用（如果适用）

优雅降级

如果只有 tasks.md 存在：只验证任务完成，跳过规格/设计检查
如果任务 + 规格存在：验证完整性和正确性，跳过设计
如果全部制品存在：验证所有三个维度
始终注明哪些检查被跳过以及原因

输出格式

使用清晰的 markdown，包括：

摘要计分卡的表格
分组列表用于问题（CRITICAL/WARNING/SUGGESTION）
代码引用格式：file.ts:123
具体的、可操作的建议
没有模糊的建议，如“考虑审查”