# 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）