Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
randypanding merged 2 commits into from
Aug 20, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2170518
governance: 契约兼容性 policy 落盘 + GOVERNANCE CI-5（P2-4，ADR-0038）
randypanding Aug 20, 2026
09866f1
governance: 契约兼容性 policy 落盘 + GOVERNANCE CI-5（P2-4，ADR-0038）
randypanding Aug 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion governance/GOVERNANCE.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,11 @@ domains:
intent: "工作流安全静态审计（zizmor medium+ 拦截）"
strength: enforced
platform: {github: {mechanism: hygiene-job, part_of: CI-1}}
- id: CI-5
intent: "契约兼容性检测门：OpenAPI/JSON Schema breaking 变更须 ADR 引用；DB migration destructive DDL 须 ADR + downgrade 逆操作；policy 声明路径与实际文件对账（失明即红）"
strength: enforced

@qodo-code-review qodo-code-review Bot Aug 20, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Action required

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

platform: {github: {mechanism: reusable-workflows, repo: CI-Workflows, workflow: contract.yml, policy: "governance/policy/contracts.yaml"}}
verify: {method: "contract-selftest（CI-Workflows ci.yml，卡内 T1-T7 fixture 全套）+ 声明路径失明防护红测（T6）"}

supply_chain:
measures:
Expand Down Expand Up @@ -232,4 +237,4 @@ portability:
github-app: {gitlab: project-access-token+deploy-tokens, generic: fine-grained-pat}
environment: {gitlab: protected-environments}
reusable-workflows: {gitlab: includes, generic: shared-ci-scripts}
migration_rule: "换平台 = 重写 platform 段 + apply/drift 脚本；intent/verify/flows 原样保留"
migration_rule: "换平台 = 重写 platform 段 + apply/drift 脚本；intent/verify/flows 原样保留"
61 changes: 61 additions & 0 deletions governance/policy/contracts.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
version: 1
# ============================================================================
# 契约兼容性检测政策（P2-4，.github#89，ADR-0038）—— 机器可判定的 SoT。
# 消费方: CI-Workflows scripts/contract/contract_check.py（contract-check job）。
# 读法:
# defaults.breaking_requires_adr —— breaking 契约变更须 PR 引用真实存在的
# ADR-NNNN（agent-registry/decisions/，防幽灵 ADR）才放行，否则红。
# defaults.openapi_fail_on —— oasdiff --fail-on 档位（ERR=社区默认；
# WARN=从严：删可选响应属性也拦——customer_upgrade_failure 姿态）。
# repos.<name>.contracts[] —— kind ∈ openapi|jsonschema（proto 未实装，
# 声明即报错：组织无 proto，首个 proto 仓落地时修订 ADR-0038 实装 buf breaking）
# repos.<name>.migrations —— tool ∈ alembic|sql + dir。
# destructive DDL 模式清单与逆操作映射落盘引擎
# （CI-Workflows scripts/contract/contract_check.py，T7 fixture 回归锁定）。
# 失明防护（T6）: 声明路径在 HEAD 必须命中 ≥1 文件、迁移目录必须非空，
# 否则红——契约文件被移走后检测器不得静默失明。
# N/A 显式: 未声明契约面的仓，contract-check 真跑并显式输出 N/A（非 skipped）。
# 盘点基线（2026-08-20，#89 执行步骤 1）: 全组织无 OpenAPI/proto 文件；
# 契约面 = JSON Schema ×3 仓 + alembic ×1 仓。
# ============================================================================
defaults:
breaking_requires_adr: true
openapi_fail_on: WARN

repos:
template-service:
# 盘点：无契约文件、无迁移——N/A 显式路径的模板载体（新服务仓复制此接线后
# 声明自己的契约面即可纳入检测）
contracts: []
migrations: null

AI_Web_School:
contracts:
- {kind: jsonschema, path: "specs/contracts/**"}
migrations:
tool: alembic
dir: alembic/versions
# 与 contract.yml（contract-watch，P5 冻结契约变更检测）职责互补：
# P5 = 冻结文件任何变更须走契约变更申请；本门 = 全部契约的 breaking 判定 +
# 迁移 destructive DDL 判定（ADR-0038）

Shorts_Director:
contracts:
- {kind: jsonschema, path: "schema/contracts/**"}
- {kind: jsonschema, path: "schema/entities/**"}
- {kind: jsonschema, path: "schema/common/**"}
migrations: null

agent-registry:
# L1 声明层契约。接线延后：validate.yml 为单 job 架构（gate job 内联全部检查，
# 无 needs 聚合层），接入需先做 aggregator 拆分重构——独立小卡（.github#89 留言，
# ADR-0038 决策 9）。声明先行：contract-check 一旦在该仓运行即生效。
contracts:
- {kind: jsonschema, path: "registry/schemas/**"}
migrations: null

# 盘点备注（不声明、不接线）：
# agent-registry 之外的注册表消费方 agent-platform —— 仅 vendor/ 拷贝，
# 源头真身在 agent-registry（vendor 漂移属另一关注面，不在本卡范围）
# mutual —— spec/01-schemas.md 为散文 schema，不可机判；落地 JSON Schema 后再声明
# Script_Writer / agent-tools / Use-up-Plan / .github / CI-Workflows —— 无契约面