Verify Workflow Spec Compliance

Spec Compliance — 功能完整性审查

入口/出口

• 入口: 已完成的功能代码、即将合并的 PR、对应的 spec 文档
• 出口: spec 合规性审查报告（通过/不通过 + 遗漏清单）
• 指向: 通过 → verify-quality-code-quality；不通过 → 退回 build 补齐功能
• 前置加载: CANON.md
• 输出路径: docs/features/YYYYMMDD-<name>/04-review.md（合规性部分） → verify-quality-code-quality（通过时）或 build-workflow-execute（不通过时退回补齐）
• 辅助参考: references/spec-compliance-examples.md（需求提取示例、验证标记示例、完整虚构报告、边界判断说明）

何时不使用

• 没有对应 spec 文档的代码变更（无法验证功能完整性）
• 代码还在开发中，未声称完成（不应进入审查阶段）

Iron Law

核心锚点

Traceability Matrix

每个 spec 需求必须建立 spec 行号 → 代码实现 → 测试 的可追溯链。

执行规则：

• 需求分四类提取：功能需求（"系统应该"）、边界条件（"当…时"）、错误场景（"失败时"）、验收标准（"验证…确保…"）
• 每条需求标记 [spec:LXX] + 实现文件路径 + 测试文件路径
• 完整示例见 references/spec-compliance-examples.md §1-2

Coverage-Gated Review

100% 覆盖是通过的唯一标准。任何缺口 = 不通过。

执行规则：

• 功能需求缺失 → Critical，必须修复
• 边界条件缺失 → Critical，必须修复
• 错误场景缺失 → Important，强烈建议修复
• 验收标准缺少测试 → Critical，必须修复
• 不通过时退回 build，提供遗漏清单和修复建议，不进入 code quality

Scope Creep Detection

任何代码中实现但 spec 未提及的用户可见功能 = scope creep。

执行规则：

• 检查范围：新增 API 端点、UI 组件、数据库表/字段、配置选项
• 合理扩展（内部工具函数、辅助类型）→ 标记通过
• Scope Creep（用户可见功能）→ 要求 human partner 判断：必要则修改 spec 收入，不必要则移除

Spec-Code Boundary

spec 明确要求的 = Spec Compliance（本技能）；spec 未提及但应该有的 = Code Quality（verify-quality-code-quality）。

执行规则：

• "函数没处理 null" → spec 要求处理 null = Spec Compliance；spec 未提及 = Code Quality
• 灰色地带（实现方式与 spec 不一致但效果相同、spec 描述模糊）→ 标记差异，由 human partner 判断

流程

Step 1：定位 spec 文档

标准路径：docs/features/YYYYMMDD-<name>/01-spec.md；Bug 修复：docs/bugs/<name>/01-root-cause.md + 02-fix-plan.md。找不到 spec 时询问用户或要求先创建 spec。

Checkpoint：spec 文档已定位。

Step 2：提取需求清单（Traceability Matrix）

逐行读取 spec，按四类提取所有需求，每条标记 [spec:LXX]。

Checkpoint：所有功能需求、边界条件、错误场景、验收标准已提取，无遗漏。

Step 3：逐项验证实现

对每个需求在代码中查找对应实现。功能需求搜函数/组件/API；边界条件查 if/guard；错误场景查 try/catch；验收标准查测试。

Checkpoint：每条需求已标记 实现路径 + 测试路径。

Step 4：Scope Creep 检查

检查代码中 spec 未提及的用户可见功能。

Checkpoint：每个 scope creep 项已标记 + 判断理由。

Step 5：生成报告 + 判定

汇总覆盖率，按 Coverage-Gated Review 判定通过/不通过。

Checkpoint：报告已生成，判定结果明确，不通过时有遗漏清单和修复建议。

常见说辞

红旗 — STOP

验证失败处理

好坏示例

Good — 结构化合规清单 + spec→代码映射

逐条提取 spec 需求，每条标注 spec 行号、代码实现位置、测试位置。覆盖率 100% 才通过；遗漏项有修复建议和影响说明。

Bad — "代码能跑就行"

跳过逐条对照，声称"功能基本实现"但实际有遗漏。无 spec→代码映射，无覆盖率计算，遗漏的边界条件和验收标准在生产以 bug 形式爆发。

完整虚构报告示例见 references/spec-compliance-examples.md §4。

输出模板

### Spec Compliance — <feature-name>

**Spec**: [01-spec.md 路径] | **时间**: [YYYY-MM-DD] | **结果**: PASS / FAIL

**覆盖率**: 功能 [X/Y] | 边界 [X/Y] | 错误 [X/Y] | 验收 [X/Y] | **总 [X/Y]**

**遗漏（Critical）**:
| # | spec 行号 | 需求 | 状态 | 影响 | 建议 |
|---|----------|------|------|------|------|
| 1 | [L12] | [需求] | [缺失] | [影响] | [建议] |

**Scope Creep**: [列表 / 无] | **测试缺口**: [列表 / 无]
**下一步**: [通过 → code quality / 不通过 → 回 build 补齐]

验证清单

• spec 文档已定位
• 所有需求（功能/边界/错误/验收）已提取并标记行号
• 每条需求已验证代码实现和测试
• Scope Creep 已检查并判断
• 覆盖率已计算（目标 100%）
• 合规性报告已生成
• 通过/不通过已判定；不通过时遗漏清单和修复建议已提供