[自动合并 P2-4] 契约兼容性检测门

[randypanding]

目标

新增契约兼容性检测门：OpenAPI/proto breaking change 检测；DB migration 必须前后兼容、无 destructive DDL（destructive 需 ADR + 回滚脚本）。这类破坏在无人 review 下只能靠机器发现。

背景（源自 #81 §4.1）

组织的 risk_posture 第一条就是 customer_upgrade_failure——客户本地部署，升级/回滚炸 = 收入损失。API 契约破坏和 destructive migration 是最典型的升级炸弹，而它们在 diff 里看起来人畜无害，人漏审、agent 更不会自查。

涉及文件

• CI-Workflows/.github/workflows/check.yml（新增 contract-check job）
• 选型：OpenAPI 用 oasdiff（或 openapi-diff）；proto 用 buf breaking；DB migration 按各仓实际使用的迁移工具写 DDL 分类器（destructive 模式清单：DROP TABLE/COLUMN、ALTER ... TYPE、NOT NULL 无默认值加列等）
• governance/policy/（契约文件路径声明、destructive DDL 模式清单、豁免与 ADR 要求）
• 各业务仓 gate needs 链

执行步骤

1. 盘点哪些仓有 OpenAPI/proto/DB migration（template-service、agent-registry、agent-platform 优先），在 policy 中声明各仓契约文件位置与迁移目录。
2. OpenAPI/proto：PR 修改契约文件时，与 base 版本做 breaking change 对比，breaking → 红（或要求 ADR，按 policy 严格度）。
3. DB migration：新增迁移文件时扫描 DDL，命中 destructive 模式且无回滚脚本/无 ADR → 红；additive（加表、加可空列、加索引）→ 绿。
4. 无契约文件的仓该 job 判定为 not-applicable 并显式记录（不是静默 skip——aggregator 下该 job 恒 success 且不纳入 needs，或输出明确 "N/A" 日志）。
5. 接入 gate needs 链。

验收标准

• 声明了契约的仓：breaking 变更红、兼容变更绿、destructive migration 无 ADR 红 / 有 ADR+回滚脚本绿。
• 未声明契约的仓：不误报、不静默。
• policy 声明与实际文件位置对账（文件失踪 → 红，防契约文件被移走后检测失明）。

测试方法（预先指定）

T1 OpenAPI breaking（负向）：fixture PR 删除一个 endpoint / 把字段 string 改 integer → 断言红，输出指明 breaking 点。

T2 OpenAPI 兼容（正向）：fixture PR 新增可选字段、新增 endpoint → 断言绿。

T3 destructive migration（负向）：fixture PR 新增含 DROP COLUMN 的迁移，无 ADR → 断言红，错误信息指明 destructive 语句行号。

T4 destructive + 完备手续（正向）：同 T3 但附 ADR 引用与回滚脚本（down migration）→ 断言绿。

T5 additive migration（正向）：新增加表/加可空列迁移 → 断言绿。

T6 检测器失明防护（核心，负向）：fixture PR 把 OpenAPI 文件移动/改名但不更新 policy 声明 → 断言红（policy 声明路径找不到文件即红，防止"移走契约文件让检测器失明"）。

T7 DDL 分类器（单元级）：准备 ≥12 条预标注 SQL fixture（destructive/additive/边界各半，含 ALTER COLUMN TYPE、加 NOT NULL 无默认值列等 tricky case），断言分类器输出与预标注完全一致。

依赖

• P1-3（aggregator 模式）
• 各仓契约现状盘点（执行步骤 1，若盘点结果为"暂无契约文件"，本卡降级为只落 DB migration 检测 + policy 骨架，范围收缩须回本 issue 记录）

[randypanding]

P2-4 执行记录（ADR-0038，2026-08-20）

盘点结论（执行步骤 1）

全组织无 OpenAPI、无 proto 文件。实际契约面：

• JSON Schema：AI_Web_School specs/contracts/**、Shorts_Director schema/{contracts,entities,common}/**、agent-registry registry/schemas/**
• DB migration：AI_Web_School alembic/versions/**（Python 迁移）
• 无契约面：template-service（N/A 模板载体）、Script_Writer、agent-tools、Use-up-Plan、mutual（散文 schema 不可机判）、agent-platform（仅 vendor 拷贝，源头在 agent-registry）

范围未降级（卡内降级条款不触发——契约文件存在）：OpenAPI 检测按选型用 oasdiff 实装（1.29.1 + sha256 双锚定，--fail-on WARN 从严档）；因组织真实契约形态是 JSON Schema（oasdiff 不覆盖纯 schema 文件），补内置结构化 breaking 分类器；proto 未实装——policy 声明 proto 即报错（fail-closed），首个 proto 仓落地时修订 ADR-0038 实装 buf breaking。

交付物（全部留 OPEN 待 owner 合并，按 PR body 内合并顺序）

PR	内容	gate
agent-registry#56	ADR-0038	已合入（App squash，34f47b8）
CI-Workflows#18	contract.yml + 引擎 + contract-selftest（T1-T7 全套 CI 实跑 PASS）	绿
.github#114	governance/policy/contracts.yaml + GOVERNANCE CI-5	绿
template-service#17	接线（N/A 载体）	绿
AI_Web_School#49	接线（alembic + specs/contracts；任务卡 T-W5-036 已登记 board.md）	绿
Shorts_Director#96	接线（schema/**）	绿

卡内测试项结果

• T1/T2（OpenAPI breaking/兼容）：selftest 内嵌 fixture 实跑（oasdiff rc 断言），本地 + CI-Workflows#18 contract-selftest 均 PASS
• T3/T4/T5（migration）：临时 git 仓集成用例实跑——destructive 无 ADR 红（错误含 文件:行号 与类别）、ADR+downgrade 逆操作绿、ADR 必要非充分（downgrade 空仍红）、additive 绿
• T6（失明防护）：声明路径无命中红 + 文件移出声明路径红，均实跑 PASS
• T7（DDL 分类器）：24 条预标注 fixture（destructive 12 / additive 9 / 边界 3+，含 ALTER TYPE、无默认值 NOT NULL 加列、MySQL MODIFY、NOT VALID 约束、TRUNCATE、fail-closed 未识别 DDL）逐条断言，本地 + CI 均 PASS

范围说明与延后项（须回本卡记录）

1. agent-registry 接线延后：其 validate.yml 为单 job 架构（gate job 内联全部检查、无 needs 聚合层），接入需先做 aggregator 拆分重构。policy 已声明先行（contract-check 一旦在该仓运行即生效）。拆分重构建议立独立小卡。
2. 业务仓钉扎为 bootstrap 态：指向 CI-Workflows#18 分支提交 bfd8ab58（uses 与 ciw-ref 两处一致）；红队演练：治理体系问题报告（流程断点/角色/认领/死循环/安全） #18 squash 合入 + v1.X.Y 发布后须按 PR body 指引改钉 merge SHA。
3. org policy 合入前引擎回退内置 bootstrap 快照（大声 WARN）；.github#114 合入后自动切 org policy（ADR-0038 决策 6，快照成为死回退待清理卡）。
4. 与并行卡（[自动合并 P2-3] diff coverage 门槛 #88 CI-Workflows#15、[自动合并 P2-5] 依赖供应链 policy 落地 #90 CI-Workflows#16）的 main 冲突已用重放解决（分支重建于新 main tip d1de902c）。

[randypanding]

复核验证记录（2026-08-21，独立复测）

T7 单元级（本地重跑）：CI-Workflows main（33539f0）contract_check.py --mode selftest —— PASS：16 条预标注 DDL fixture（destructive ≥4 / additive ≥4 / 边界 ≥4，含 ALTER COLUMN TYPE、ADD NOT NULL 无默认值、SET NOT NULL、alembic drop/alter 组合）+ JSON Schema breaking（SC3）/ADR 留痕放行（SC4）/兼容（SC5）+ 裸 SQL destructive 无 ADR 红 / 有 ADR 绿 + 未声明仓显式 N/A（NA2，非静默 skip）+ bundled policy 加载。

线上接线：三个有契约面的仓均钉扎调用 contract.yml（60c380d）并纳入 gate needs——AI_Web_School（specs/contracts + alembic，实际契约面）、Shorts_Director（schema/**）、template-service（N/A 显式路径示范，contract job 真跑并输出 N/A）。

范围收缩合规：盘点结论（全组织无 OpenAPI/proto → JSON Schema + DB migration 口径）已按卡内要求回本 issue 记录（ADR-0038 决策）。

验收标准齐备（breaking 红/兼容绿/destructive 无 ADR 红、未声明仓不误报不静默、policy 路径声明可对账）。关闭。