api-contract-consistency-validator

name	api-contract-consistency-validator
description	校验业务代码与 IDL 契约同步、字段冻结状态是否被破坏。作为 8 维度 code review 的"契约一致"维度，可被 design-checker / code-review-preparer 调用，也可独立运行。
allowed-tools	Read, Bash, Glob, Grep

Skill: api-contract-consistency-validator

原文 §8.3 把契约一致定位为 Skill（不是 Agent），因为它是一组确定性检查——无需主观判断，只需机械比对 diff 与契约状态。

输入

{
  "feature_ids": ["FT-001"],
  "commit_range": "abc..def",
  "business_diff_path?": "...",
  "idl_diff_path?": "..."
}

检查项

ID	检查	阻塞
K1	feature 标记 idl_change: true → IDL 仓必须存在对应 diff	YES
K2	feature 标记 idl_change: false → 业务 diff 中不允许引用新 IDL 字段	YES
K3	IDL 中带 frozen: true 注释/标记的字段，禁止类型/语义变更	YES
K4	业务代码引用的 IDL 字段必须存在（防止编译期不报但运行期 panic）	YES
K5	新增 IDL 字段必须有默认值或 optional 标记（向后兼容）	YES
K6	detail-design.md 的"IDL 变更"小节覆盖了本次 IDL diff（字段一致、版本号一致）	YES
K7	同名分支策略：业务仓改 IDL 字段 → IDL 仓必须有同名分支	YES（已在 4.3 门禁覆盖，这里再次确认）

工作流

1. 解析 tasks/features.json → 找出 idl_change=true 的 features
2. git -C {idl-repo} diff 取 IDL diff
3. git -C {business-repo} diff 取业务 diff
4. 解析两份 diff 的字段引用
5. 对照 detail-design.md 的"IDL 变更"小节
6. 输出结构化结论

输出

{
  "skill": "api-contract-consistency-validator",
  "verdict": "PASS|WARN|FAIL",
  "findings": [
    { "id": "K3", "file": "{idl-repo}/coupon.jce", "line": 24,
      "issue": "frozen 字段 user_ids 类型从 list<int> 改为 list<string>",
      "suggestion": "新增 user_ids_v2 字段，保持兼容" }
  ]
}

调用方

• code-review-preparer Agent 在阶段 4.4 把它作为第 6 维度调用
• detail-design-quality-reviewer 在阶段 3.3 调用其中 K5/K6 做设计期 IDL 预审
• CLI 直接调用：/agentic:check-contract

与 Agent 的边界

• Skill = 确定性检查，输出结构化数据
• Agent = 可能调用多个 Skill，做综合判断，写门禁文件