governance: 契约兼容性 policy 落盘（contracts.yaml）+ GOVERNANCE CI-5（P2-4，ADR-0038）

[randypanding]

摘要（P2-4，.github#89，ADR-0038）

契约兼容性检测门的 policy SoT 落盘 governance/policy/contracts.yaml + GOVERNANCE.yaml 新增 CI-5 度量。

contracts.yaml 内容

• defaults：breaking_requires_adr: true（breaking 契约变更须 PR 引用真实存在的 ADR）；openapi_fail_on: WARN（oasdiff 从严档：删可选响应属性也拦）。
• 仓声明（盘点基线 2026-08-20，[自动合并 P2-4] 契约兼容性检测门 #89 执行步骤 1——全组织无 OpenAPI/proto）：
  • AI_Web_School：jsonschema specs/contracts/** + alembic alembic/versions
  • Shorts_Director：jsonschema schema/{contracts,entities,common}/**
  • agent-registry：jsonschema registry/schemas/**（声明先行、接线延后——validate.yml 单 job 架构需先拆 aggregator，[自动合并 P2-4] 契约兼容性检测门 #89 留言记录）
  • template-service：无契约面（N/A 显式路径的模板载体）
• 盘点备注（不声明不接线）：agent-platform 仅 vendor 拷贝（源头在 agent-registry）；mutual 为散文 schema 不可机判。
• 失明防护语义（T6）：声明路径在 HEAD 必须命中 ≥1 文件、迁移目录必须非空，否则红。

GOVERNANCE.yaml

ci_gate 域新增 CI-5：intent/platform/verify 三段（reusable-workflows contract.yml + policy 文件 + contract-selftest 验证面）。

消费方

CI-Workflows scripts/contract/contract_check.py（contract-check job）：优先读本 policy（gh api 公开仓读）；本 policy 合入前引擎回退内置 bootstrap 快照（ADR-0038 决策 6，合入后快照成为死回退待清理）。

合并顺序

依赖 CI-Workflows#18（引擎）先行或同批合入——本 policy 合入后即取代 bundled 快照。

[coderabbitai]

Warning

Review limit reached

@randypanding, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 19 minutes

Limit details: You’ve used all 10 included reviews currently available.

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

Wait for the limit to reset, then comment @coderabbitai review or push new commits to the PR.

An organization admin can change what happens after included review limits in Billing.

How do review limits work?

CodeRabbit enforces per-developer PR review limits within each organization.

For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6f063a66-eb06-4fb8-84fd-5570f985bddf

📥 Commits

Reviewing files that changed from the base of the PR and between 8c91075 and 09866f1.

📒 Files selected for processing (2)

• governance/GOVERNANCE.yaml
• governance/policy/contracts.yaml

---

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-code-review]

PR Summary by Qodo

落盘契约兼容性策略并登记 CI-5 治理门

✨ Enhancement ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• 新增组织级契约策略，声明 JSON Schema 与数据库迁移检测面。
• 强制破坏性变更引用有效 ADR，并对声明路径实施失明防护。
• 在治理总表登记 CI-5 工作流及自测验证面。

Diagram

graph TD
  CI5["CI-5 Measure"] --> WF["Contract Workflow"] --> CHECK["Contract Checker"] --> SURF["Repo Contract Surfaces"]
  POLICY["contracts.yaml Policy"] --> CHECK
  TEST["T1-T7 Self-tests"] --> WF

Loading

High-Level Assessment

集中式、机器可读的策略 SoT 与现有治理模型和共享工作流架构最匹配。分仓配置会造成策略漂移，自动发现则难以区分权威契约与 vendor 或散文文件；当前显式清单配合失明防护更可控。

Files changed (2) +67 / -1

Enhancement (1) +61 / -0

contracts.yaml新增组织级契约兼容性策略源 +61/-0

新增组织级契约兼容性策略源

• 定义破坏性变更必须引用 ADR、OpenAPI WARN 失败阈值及声明路径失明防护。盘点并声明 AI_Web_School、Shorts_Director、agent-registry 和 template-service 的契约或迁移检测面。

governance/policy/contracts.yaml

Other (1) +6 / -1

GOVERNANCE.yaml登记强制执行的 CI-5 契约兼容性治理门 +6/-1

登记强制执行的 CI-5 契约兼容性治理门

• 在 ci_gate 域新增 CI-5，定义 OpenAPI、JSON Schema 和破坏性数据库迁移的 ADR 要求。关联 CI-Workflows 的 contract.yml、集中策略文件及 T1-T7 自测验证面。

governance/GOVERNANCE.yaml

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📜 Skill insights (0)

1. Unwired repository marked enforced 🐞 Bug ≡ Correctness

Description

CI-5 is marked enforced, yet the policy explicitly postpones contract-check wiring for
agent-registry, leaving changes under registry/schemas/** able to merge without this
compatibility gate. This contradicts the documented meaning of enforced and makes the
organization-level control materially incomplete.

Code

governance/GOVERNANCE.yaml[67]

+        strength: enforced

Relevance

●●● Strong

Recent governance precedents accept findings exposing mismatches between declared controls and
actual enforcement or documented semantics.

PR-#19
PR-#48

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The governance file defines enforced as platform-enforced, while the new policy says
agent-registry integration is deliberately deferred despite declaring its schema path. The
required-check standard also says gate is the sole required check, so an unaggregated or absent
contract job cannot block merges.

governance/GOVERNANCE.yaml[8-8]
governance/GOVERNANCE.yaml[65-69]
governance/policy/contracts.yaml[49-55]
standards/automation/required-check-chains.md[8-20]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
CI-5 is declared platform-enforced even though the policy explicitly states that `agent-registry` wiring is deferred. Ensure every declared contract surface participates in its repository's required `gate`, or do not advertise the measure as enforced yet.

## Issue Context
`agent-registry` owns the declared `registry/schemas/**` contract surface, so declaration alone does not prevent incompatible changes from merging. The repository uses a single required gate and needs contract checking included in or aggregated into that gate.

## Fix Focus Areas
- governance/GOVERNANCE.yaml[65-69]
- governance/policy/contracts.yaml[49-55]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

✅ Compliance rules (platform): 8 rules

Review mode: ⚖️ Balanced: This changes enforced governance policy and CI contract-gating behavior, including ADR validation, migration checks, and path-blindness safeguards; it has meaningful behavioral and compatibility risk, but the scoped diff is not dense enough to justify redundant extended review.

Tip of the day

💡 Did you know, you can copy the agent prompt from any finding and feed it to your IDE agent

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

1. Unwired repository marked enforced 🐞 Bug ≡ Correctness

CI-5 is marked enforced, yet the policy explicitly postpones contract-check wiring for
agent-registry, leaving changes under registry/schemas/** able to merge without this
compatibility gate. This contradicts the documented meaning of enforced and makes the
organization-level control materially incomplete.

Agent Prompt

## Issue description
CI-5 is declared platform-enforced even though the policy explicitly states that `agent-registry` wiring is deferred. Ensure every declared contract surface participates in its repository's required `gate`, or do not advertise the measure as enforced yet.

## Issue Context
`agent-registry` owns the declared `registry/schemas/**` contract surface, so declaration alone does not prevent incompatible changes from merging. The repository uses a single required gate and needs contract checking included in or aggregated into that gate.

## Fix Focus Areas
- governance/GOVERNANCE.yaml[65-69]
- governance/policy/contracts.yaml[49-55]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools