ai-robot-core/spec/contracting.md

contracting.md（ai 必须遵守：契约成熟度与门禁规则）

本文件仅包含编码智能体必须遵守的契约约束与门禁规则（面向执行与校验）。

约定：若本文件与 agents.md 冲突，以 agents.md 为准；若本文件与 spec/<module>/requirements.md 或 OpenAPI 契约冲突，必须先修正文档再编码，禁止猜测。

---

1. 文件与字段硬约束

• 本模块的 OpenAPI 契约拆分为：

  • openapi.provider.yaml：本模块对外提供的 API（provider）
  • openapi.deps.yaml：本模块依赖的外部 API 契约（consumer 需求侧）

• 两份 OpenAPI 都必须在 info 下声明成熟度（全局标记，不按 operation 级）：

  • info.x-contract-level: L0 | L1 | L2 | L3

• provider 端接口（建议强制）：

  • operationId 必须存在且在同文件内唯一
  • 应通过 x-requirements: [AC-...] 或 requirements 的 traceability 表建立 AC 追踪

---

2. 契约成熟度（L0-L3）最低要求

• L0（占位/可 mock）：允许 schema 粗粒度；仅用于并行启动与 mock。
• L1（可调用/可生成 sdk）：关键请求/响应字段 required/optional 明确；基本状态码集合明确。
• L2（可验收/可契约测试）：关键字段校验规则与错误语义稳定；可进行 provider-driven schema 校验。
• L3（可演进/可兼容治理）：具备兼容策略与示例；可治理 breaking change。

---

3. 细化路径（粗 → 细）执行规则

• 新增/调整 AC 会驱动契约细化；任何字段/错误语义/校验规则的新增，必须能追溯到某条 AC-*。
• 当实现准备进入可合并状态（尤其是自动合并）时，必须先把 openapi.provider.yaml 提升到 L2。

---

4. 门禁规则（软/硬）

4.1 feature 分支（软门禁）

允许：

• 使用 openapi.deps.yaml (L0/L1+) 生成 mock/sdks，推进调用方开发。

禁止：

• 未满足 openapi.provider.yaml >= L2 的情况下，将 provider 实现以“自动合并”方式进入 main。

4.2 main 分支（硬门禁）

满足以下条件前，禁止合并（或禁止自动合并）：

• openapi.provider.yaml >= L2
• 契约测试通过（响应符合 openapi schema）
• openapi diff 检查通过（无未声明 breaking change）
• 需求追踪检查通过（AC 引用未断裂）

---

5. 最小检查清单（编码智能体自检）

• openapi 文件可解析
• info.x-contract-level存在且为 L0-L3
• provider: operationId 唯一
• provider: 能追踪到 AC（x-requirements 或 traceability）