Repository navigation
docs(ci): state the required-check contract the way GitHub reports it - #12
Merged
Merged
Conversation
Four documents claimed the three required check names were produced by `matrix.check_name` and could not be broken from inside the reusable workflows. Only half of that was ever true: a job that calls a reusable workflow reports `<caller job name> / <name the called workflow gives its own job>`, so the matrix fixes the first half and `_build-test.yml`'s unnamed `build-test` job fixes the second. That is why deleting the legacy per-platform copies stalled every PR — the bare contexts they alone reported stayed required with nothing to satisfy them, which `gh pr checks` cannot show because it lists only runs that exist. Reword the contract in AGENTS.md, the ci.yml header, TECH_SPECS.md, the testing guide and the ci-monitor agent, each with the ruleset-vs-check-runs diff that catches a recurrence, and correct the direction of the failure: the guard does not lift, it inverts into a permanent pending. Point the two clang-format pin comments at ci.yml, where that job now lives.
The macOS matrix comment still called `macos-build` the required check name, contradicting the contract written forty lines above it in the same file: that string is only the first half of the context `macos-build / build-test`. Tighten three claims that overstated or under-specified what happened. The ruleset never lost its required entries, so the CHANGELOG heading now names the legacy files as the deleted reporters rather than the deleted checks, and the stall is scoped to the one PR that actually hit it instead of "every PR, forever". TECH_SPECS gains the reason the suffix equals a job key — the called job sets no `name:` — since adding one would move all three contexts just as silently as renaming it.
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
wangrh0909
approved these changes
Sep 20, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
PR #11 删掉四个 legacy 分平台工作流之后，ruleset 要求的三个必需 context 失去了唯一的上报者，合并被永久卡住；那次修复（把 ruleset 对齐到
ci.yml真正报出的名字）暴露出五处文档仍在断言一件从未成立的事——"三个必需检查名由matrix.check_name生成，所以改复用工作流内部不会动到必需检查"。本 PR 只做订正，不改任何可执行行为。实际机制（已用
gh api在本仓实测）：用uses:调可复用工作流的 job，报名是matrix.check_name只供前一半；后一半是build-test，因为_build-test.yml写的是jobs: build-test:且没有name:键。所以 ruleset 现在要求的三条 context 是：linux-build-and-test / build-testwindows-build-and-test / build-testmacos-build / build-test另一处方向性纠正：缺少上报者不是"悄悄解除合并保护"，而是相反——ruleset 继续要求一个没人能上报的 context，于是每个 PR 挂在那一项 pending。而
gh pr checks只列出存在的 check run，绝不列出缺位的必需检查，所以看起来全绿、实际mergeStateStatus: BLOCKED。What changed
AGENTS.md"CI"：CI 表格改成真实报名形态；重写必需检查段落，含机制、失败方向与两条gh api差集取证命令。.github/workflows/ci.yml：头部 Check-name contract 注释同上；另外 macOS 矩阵项内一行旧注释仍称macos-build为 required check name，与同文件上方新立的契约自相矛盾，一并订正。TECH_SPECS.md"[MUST] CI 工作流治理"：检查名契约行从一句话假声明改为可核验规则，并补上"后缀等于键名只是因为该 job 没写name:，补一个name:同样会改掉三条 context"。docs/testing/testing_guide.md"CI/CD Integration"：必需项按 context 全称表述。.claude/agents/ci-monitor.md：同上 + 取证命令（该文件不被.codex/镜像，无 twin-parity 负担）。CHANGELOG.md：### Fixed新增一条记录这次故障与修法；同时修正两条既有陈述——"required check 名叫macos-build"改为"job 名"（裸 context 时代它确实是报名，这一点也写明），以及删除 legacy 那条 bullet 里"三个必需名不变、由 matrix.check_name 生成"的说法。.pre-commit-config.yaml、scripts/clang_format.py：两处钉版注释仍指向已删除的ci-linux.yml，改指ci.yml的static-analysis。无代码/构建行为改动：
ci.yml只动注释，YAML 结构未变。Verification
python scripts/check_architecture.py/check_docs_drift.py（7 规则）/check_test_layout.py/check_migrations.py/check_version_sync.py全部 exit 0。python -c "import yaml; yaml.safe_load(open('.github/workflows/ci.yml'))"ok；py_compile scripts/clang_format.pyok；git diff --check干净。integration_id；b8d7d72（master）的check-runs九个报名；_build-test.yml/_sdk-smoke.yml的 job 声明。b8d7d72的CI与coverage两轮均已 success（7 job 全绿），覆盖率棘轮在无 SEED 的情况下比对通过。ci.yml内部自相矛盾一处。全部已在两个提交内修掉。Deliberately not done
name:键与 job id 谁优先"）——文档页面没有该条款，故只陈述本仓可复现的事实形态。_build-test.yml里 Windows 腿CREATE USER test WITH PASSWORD '...'的写法：那是 CI runner 上的一次性占位口令，与 Linux 腿的POSTGRES_PASSWORD=123456同一性质，属另一主题。.kiro/、.qoder/、.zcode/、docs/history/、docs/superpowers/plans/里对 legacy 工作流名的历史记述——它们是当时状态的存档，不是现行声明。