Skip to content
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Commit 4b9a0a8

Browse files
claude[bot]claude
andauthored
docs(agents): record the merge_group leg's SECOND refusal predicate (the contract-review carrier) (#9466)
Fixes #9213 ## ⛔ This PR is GOVERNED and opens as a DRAFT — the draft state is the FINISHED state `AGENTS.md` is governed surface. Verbatim verdict from this branch: ``` $ node scripts/check-governed-queue-guard.mjs --test AGENTS.md # exit 3 ⛔ GOVERNED — 1 of 1 path(s) are on a governed surface: AGENTS.md x1 — the repo-root agent instruction file - AGENTS.md One governed path governs the WHOLE pull request — proportion is not a question. ⛔ Do not flip it ready, enqueue it, or arm auto-merge. Park it as a DRAFT and leave the merge to the maintainer; a human merge IS the review record for a governed surface. The merge-queue run of "Governed Surface Queue Guard" refuses this diff unless an APPROVED review by an authorized approver (GOVERNED_APPROVERS: os-zhuang, hotlong) is on the pull request — on whichever commit it was left (maintainer ruling 2026-09-04). ``` ⚠️ **The draft state does not mean the work is unfinished.** The change is complete and the gates are green. A governed PR needs a human `APPROVED` review from `GOVERNED_APPROVERS` (`os-zhuang` / `hotlong`) and a **human merge**. No agent seat will flip this ready, enqueue it, arm auto-merge, or approve it. ## What is wrong `AGENTS.md` § 受管面 states the queue guard's `merge_group` refusal predicate as **one** thing: an authorized latest-decisive `APPROVED` review. Since #9018 / PR #9212 that leg carries **two independent predicates**: | leg | predicate | exits | |:--|:--|:--| | governed surface | an authorized latest-decisive `APPROVED` review record | 3 · 4 · 5 | | contract-review carrier | no queued pull request carries `needs:contract-review` | 6 · 7 | ⇒ **a merge group whose diff touches nothing governed at all can now be refused.** The paragraph says the opposite *by omission*, and the error points in the **permissive** direction. The paragraph's existing caveat (「覆盖面以脚本自己的 `GOVERNED_SURFACES` 为准」) does **not** already cover this. It delegates the **surface list**. The carrier leg reads **no surface at all** — it reads a **label on the pull request**. ## Measurements, re-derived on this branch's base (`f5b9c17973`), not inherited from the card **1. The exits exist and mean what the card said.** ``` $ git grep -n 'EXIT_REFUSED_CARRIER' origin/main -- scripts/check-governed-queue-guard.mjs origin/main:scripts/check-governed-queue-guard.mjs:258:export const EXIT_REFUSED_CARRIER = 6; origin/main:scripts/check-governed-queue-guard.mjs:259:export const EXIT_REFUSED_CARRIER_UNREADABLE = 7; ``` 6 = a queued pull request carries the label (`refusalKind: 'gated'`). 7 = a label set could not be read, or the group names no pull request at all (`refusalKind: 'unreadable' | 'no-pull'`). **2. The carrier leg reads a LABEL, not a surface.** Code path, all in `scripts/check-governed-queue-guard.mjs`: `runCarrierGuard({ event, rows, namedPull, fetchLabels })` → `carrierPullsInGroup(rows, namedPull)` enumerates the queued PRs **per commit** → for each, `await fetchLabels(pr)` → the whole predicate is `names.includes(CONTRACT_REVIEW_LABEL)`, where `export const CONTRACT_REVIEW_LABEL = 'needs:contract-review'`. **No path, no diff, no surface set is consulted anywhere on this leg.** The file says so itself: > the carrier is REMOTE state hung by a seat, not a property of the diff. So every merge group pays > one label read per queued pull request. ⚖️ THE ACCEPTED COST … a GitHub outage now refuses a merge > group whose diff touches nothing governed, which the governed leg alone never did. **3. `AGENTS.md` carried no mention of it.** ⚠️ Read as **TEXT with whitespace collapsed**, not with a line-oriented grep — the target is one enormous wrapping sentence on a single physical line (1434 chars), and a line grep cannot be trusted to answer a question about a sentence. ``` needs:contract-review 0 | GOVERNED_APPROVERS 3 (control, HIT) contract-review 0 | merge_group 2 (control, HIT) carrier 0 | latest-decisive 2 (control, HIT) 承载 / 合同评审 / EXIT_REFUSED_CARRIER 0 ``` Every zero is carried by three controls that HIT in the same run, in the same file, with the same reader. **4. `content/docs/guide/ci-cd-pipeline.md` (NOT governed) already carries the corrected account** — PR #9212 updated it. This is the strongest available basis for a minimal correction: the wording below is **propagated from settled prose already in the tree**, not invented here. > **The second leg: the contract-review carrier.** On a **merge-queue build only**, this check > carries a second and completely independent predicate, keyed on a *label* rather than on paths > (#9018, a re-implementation of the leg objectstack landed as its own `objectstack#17484`). It > enumerates **every** pull request the merge group is landing — per commit, exactly as the governed > leg does, because `merge_group.head_ref` names only the *last* pull request in the group and keying > on it would let an earlier pull request's open carrier ride into `main` behind a clean one — reads > each one's labels from the pull object … and refuses while `needs:contract-review` is on any of > them (**exit 6**) or when a label set cannot be read or the group names no pull request at all > (**exit 7**, split from 6 for the same reason 4 is split from 3). The `pull_request` leg is > untouched and reads no label. Its row in the same file's check table already says it too: > a governed-surface diff with no authorized approval record (on any commit) is refused there, and so > is any merge group whose queued pull requests still carry `needs:contract-review` ## ⭐ The wording is the maintainer's to amend — that is why the diff is this small #9213 declines to propose wording, verbatim: 「**Not proposing the wording.** What the paragraph should say is a maintainer's call, not a seat's, and the file is governed precisely so that it is.」 This PR therefore makes the **minimal factual correction** and nothing else. **`diff --numstat` → `1 1 AGENTS.md`.** One line changed, because the paragraph is one physical line. Text was **added**; nothing was removed. **What I deliberately did NOT touch:** - ⛔ did not restructure the paragraph into a two-predicate list, though that reads better - ⛔ did not re-translate, re-punctuate, shorten or otherwise "improve" any existing prose - ⛔ did not touch the 「覆盖面以脚本自己的 `GOVERNED_SURFACES` 为准」 caveat, even though it is the sentence a reader is most likely to over-read (see the alternatives below) - ⛔ did not touch any other paragraph, section or file — not the guard script, not the workflow, not `content/docs/guide/ci-cd-pipeline.md` - ⛔ did not rule on anything the card declined to rule on - ⛔ did not touch #9301's region (lines 107..112); this change is in the 受管面 paragraph near line 522. Verified non-overlapping. Register: the insertion is Chinese prose with inline code spans, half-width punctuation (`,` `;` `:` `(` `)` — measured on the target line: 27 `,`, 13 `()`, 9 `:`, 5 `;`; the only two full-width `,` in that line are inside the verbatim untranslated maintainer quote), and the paragraph's existing ⚠️ / ⇒ / `**bold**` markers. No English sentence was introduced. ## ⭐ Alternative phrasings I considered — offered here, NOT put in the file The maintainer should feel free to take any of these instead; amending one line is cheap by construction. 1. **(taken)** One appended sentence-block after the 已接受的代价 caveat and before 「⚠️ 但它**尚未**是 required context」, opening 「⚠️ 而这条拒绝腿上的判据**不止上面那一条**」. Chosen because it lands while 「`merge_group` 腿才是会拒绝的那条 —— 它要求 …」 is still in the reader's eye, and because the following 「但它尚未是 required context ⇒ 那条拒绝腿只报告、不阻止队列」 is true of **both** predicates, so it now correctly scopes over both. 2. **Restructure into 「它有两条相互独立的拒绝判据:① … ② …」.** Clearer, and what I would write from scratch. Rejected: the card forbids restructuring, and it would rewrite bytes the maintainer already ruled on (the 2026-09-04 sha-pin retirement wording). 3. **Insert immediately after 「它要求 [predicate 1] …(维护者 2026-09-04 裁 …)。」, before the 已接受的代价 caveat.** Tightest possible placement. Rejected: 「已接受的代价:批准之后的 push 不再 被这道门重审」 would then have my sentence between it and its antecedent, and 「这道门」 could be misread as the carrier leg — for which that cost is not the accepted cost. 4. **Append at the very end of the paragraph, after the `GOVERNED_SURFACES` caveat**, so it could say 「上面那句托付的是受管面清单,⛔ 不是判据清单」. Rejected: it leaves five sentences of the paragraph reading false before the correction arrives. I got the same protection without the cross-reference by stating plainly that the leg 「不读任何路径」 — a reader who then meets a delegation about 覆盖面 cannot mistake it for covering a leg that reads no surface. 5. **Also correct the `--test` renderer's own advisory text**, which describes the merge-queue refusal with the approval predicate alone (quoted at the top of this PR). Rejected: out of scope for #9213, and it is a different file. Reported to the PM rather than fixed here. ## Gates — PRE / POST, exit codes captured by redirect-then-capture, never across a pipe PRE = base bytes restored from `HEAD` by explicit ref; POST = this commit. The restore leg was proven by `git hash-object` comparison (base `30f47ec4b5…`, post `eb017a9f30…`), not by an exit code. | gate | PRE | POST | |:--|:--|:--| | `check:control-bytes` | 0 | 0 | | `check:new-line-citations` | 0 | 0 | | `docs:check-links` | 0 | 0 | | `check:shell-escape-residue` | 0 | 0 | | `check:governed-queue-guard` (self-test) | 0 | 0 | | `check:required-check-set` (self-test) | 0 | 0 | | `check-changeset-presence.mjs` | — | 0 | Both sides agree, so each instrument is shown to be non-empty and to have actually read the file: - `check-control-bytes: OK (scanned 7644 tracked text file(s); skipped 85 binary)` - `check-shell-escape-residue: OK (5/5 root(s) resolved -- AGENTS.md: 1 file(s), 15 fence(s); …)` - `Links are valid across 17 scan roots.` - `VERDICT new-cross-file-line-citations: 0 new citation(s), enforcement report-only -> exit 0` - `check-governed-queue-guard self-test: 185 cases pass (… plus the SECOND queue predicate objectui#9018 added on the merge_group leg — the contract-review carrier …)` — the guard's own self-test corroborates the premise on this base. Changeset: none owed. `check-changeset-presence.mjs` → `✅ No source or published contract of a released package changed in this range, so no changeset is owed.` ⚠️ The `skip-changeset` label was deliberately **not** applied: in this repository that label object exists but no workflow or script reads it, and a pin test holds that in place. I also self-scanned the file for control bytes outside the gate (`grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]'` → no match, with a positive control that HIT in the same run on a fixture containing `0x0c`). ## 维护者速读(草稿) **改了什么** —— `AGENTS.md` 受管面那段里,关于 `merge_group` 拒绝腿的描述补了一句:那条腿现在有**两条** 相互独立的判据,原文只写了一条(获授权的 APPROVED review),漏掉了 #9018 加的 contract-review carrier (读 PR 上的 `needs:contract-review` label,exit 6 / 7)。一行 diff,只加不删。 **为什么改** —— 漏写的方向是**放宽**:照原文读,一个 diff 完全没碰受管面的 merge group 不可能被这道 check 拒绝;实际上可以。每一次 dispatch 都读这段。 **风险与代价(含回滚)** —— 风险极低:纯文字,不动脚本、不动 workflow、不动任何判定逻辑,六道门禁 PRE/POST 全绿。回滚 = revert 这一个 commit,恢复一行。措辞是从 `content/docs/guide/ci-cd-pipeline.md` 里已经被接受的说法搬过来的,不是新造的。 **席位意见** —— **你要做的** —— ① 读上面「Alternative phrasings」五条,措辞归你定,改一行很便宜;② 这是受管面 PR, 需要你一条 `APPROVED` 并由你合并 —— 席位不会 ready、不会入队、不会自合、不会批准。 --- 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr --- _Generated by [Claude Code](https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr)_ Co-authored-by: Claude <noreply@anthropic.com>
1 parent f7fcc2c commit 4b9a0a8

1 file changed

Lines changed: 1 addition & 1 deletion

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -531,7 +531,7 @@ sha pin **退休**之后这条**更重、不是更轻**(维护者 2026-09-04 裁
531531
- **CI 全绿、已 review 都不构成例外。** 这类文件是后续每一次 dispatch 读的操作规程,绿灯说明不了它该不该成为规程。
532532
- **发现自己已经挂上了怎么办**:把 PR 转回 **draft** 是唯一能可靠退出合并队列的动作 —— 只调 `disable_pr_auto_merge` 会摘掉 auto-merge 但**不取消队列成员资格**,两个都要做。⚠️ 只回收**你自己**挂上的:本仓多 agent 共用同一 GitHub 身份,不是你设置的状态就属于别的 actor —— 去问、去报告,别替他回退。
533533
534-
**本仓的机械兜底只有一件,而且它现在只报告、不拦截 —— 别读成一道拦得住的门,也别再读成「什么都没有」。** 本仓仍然没有 CODEOWNERS(核实:仓内不存在该文件),受管面上也没有钩子;但 `.github/workflows/governed-surface-guard.yml`(check 名 `Governed Surface Queue Guard`,判定逻辑在 `scripts/check-governed-queue-guard.mjs`)**是活的**:`pull_request` 腿是早期告警、**故意 exit 0**(受管 PR 停在 draft 正是健康终态,所以**绿不等于不受管**),`merge_group` 腿才是会拒绝的那条 —— 它要求 `GOVERNED_APPROVERS`(`os-zhuang` / `hotlong`)里某个账号的一条 latest-decisive APPROVED review,**留在哪个 commit 上都算**;DISMISSED 与被顶掉的批准(同一 reviewer 后续给了 CHANGES_REQUESTED)不算,该集合之外账号的 APPROVED 不算,review 列表为空或读不到则 fail closed —— 判定读的是**有没有一条人工批准记录**,不问它是对哪些字节给的(维护者 2026-09-04 裁,逐字未译:「你的门禁有问题,只需要有人工批准记录就行,不需要卡最新的提交。」;sha pin 是**退休**不是放宽,守卫里已没有任何判定读 `commit_id`)。⚠️ 已接受的代价:批准之后的 push 不再被这道门重审,一个已批准的受管 PR 可以带着批准者没读过的字节落地 —— 维护者接受这一点,而这道拒绝先印的补救仍是转回 draft、交人类合并。⚠️ 但它**尚未**是 required context:ruleset 开关只有维护者能翻(#6596,`pm:awaiting-maintainer`),**在翻转之前,那条拒绝腿只报告、不阻止队列**。事后一侧:`../objectstack` 的 report-only 合并后审计(`scripts/pm/check-governed-merges.mjs`)自 objectstack#9619 起**已覆盖本仓**(四个受管仓一次扫完),它把受管面的合并列出来,但同样不阻止任何事。⇒ 违规不再完全静默,但**仍然没有任何东西会替你拦下它**,这条规则的效力主要还是在于你读到了它并照做。**⛔ 别再把本段当成兜底工具的完整清单** —— 覆盖面以脚本自己的 `GOVERNED_SURFACES` 为准(它随树变化,本段不会);⚠️ 该清单曾与上面的受管面清单**并不一致**(脚本的集合含已发布 `skills/**`),这一分歧**已裁**:维护者第 5 场决裁批 #7 采 **Option A**(#6866 评论 5469339478)—— 已发布 `skills/**` **受管**,守卫的读法才是裁定的那个;该裁决**已随本段上方的清单落地**(#6866):上面五项已含 `skills/**`,与脚本的 `GOVERNED_SURFACES` 一致,曾经那条「仓根 `skills/**` 不受管、自行入队」的豁免**已作废**,⛔ 别再照它行事。
534+
**本仓的机械兜底只有一件,而且它现在只报告、不拦截 —— 别读成一道拦得住的门,也别再读成「什么都没有」。** 本仓仍然没有 CODEOWNERS(核实:仓内不存在该文件),受管面上也没有钩子;但 `.github/workflows/governed-surface-guard.yml`(check 名 `Governed Surface Queue Guard`,判定逻辑在 `scripts/check-governed-queue-guard.mjs`)**是活的**:`pull_request` 腿是早期告警、**故意 exit 0**(受管 PR 停在 draft 正是健康终态,所以**绿不等于不受管**),`merge_group` 腿才是会拒绝的那条 —— 它要求 `GOVERNED_APPROVERS`(`os-zhuang` / `hotlong`)里某个账号的一条 latest-decisive APPROVED review,**留在哪个 commit 上都算**;DISMISSED 与被顶掉的批准(同一 reviewer 后续给了 CHANGES_REQUESTED)不算,该集合之外账号的 APPROVED 不算,review 列表为空或读不到则 fail closed —— 判定读的是**有没有一条人工批准记录**,不问它是对哪些字节给的(维护者 2026-09-04 裁,逐字未译:「你的门禁有问题,只需要有人工批准记录就行,不需要卡最新的提交。」;sha pin 是**退休**不是放宽,守卫里已没有任何判定读 `commit_id`)。⚠️ 已接受的代价:批准之后的 push 不再被这道门重审,一个已批准的受管 PR 可以带着批准者没读过的字节落地 —— 维护者接受这一点,而这道拒绝先印的补救仍是转回 draft、交人类合并。⚠️ 而这条拒绝腿上的判据**不止上面那一条** —— #9018(PR #9212)给 `merge_group` 腿加了**第二条、与受管面完全无关的**判据:它枚举该 merge group 要落地的**每一个** PR(逐 commit 分解,不是只读 `merge_group.head_ref`),读每个 PR 的 label,其中任何一个仍挂着 `needs:contract-review` 就拒绝(**exit 6**);label 读不到、或该 group 指不出任何 PR,同样拒绝(**exit 7**)。⚠️ 这条判据读的是**挂在 PR 上的 label**,不读任何路径、不问 diff 命中了什么 —— ⇒ **一个 diff 完全没碰受管面的 merge group,现在也可能被这道 check 拒绝**;`pull_request` 腿不受影响,不读 label。⚠️ 但它**尚未**是 required context:ruleset 开关只有维护者能翻(#6596,`pm:awaiting-maintainer`),**在翻转之前,那条拒绝腿只报告、不阻止队列**。事后一侧:`../objectstack` 的 report-only 合并后审计(`scripts/pm/check-governed-merges.mjs`)自 objectstack#9619 起**已覆盖本仓**(四个受管仓一次扫完),它把受管面的合并列出来,但同样不阻止任何事。⇒ 违规不再完全静默,但**仍然没有任何东西会替你拦下它**,这条规则的效力主要还是在于你读到了它并照做。**⛔ 别再把本段当成兜底工具的完整清单** —— 覆盖面以脚本自己的 `GOVERNED_SURFACES` 为准(它随树变化,本段不会);⚠️ 该清单曾与上面的受管面清单**并不一致**(脚本的集合含已发布 `skills/**`),这一分歧**已裁**:维护者第 5 场决裁批 #7 采 **Option A**(#6866 评论 5469339478)—— 已发布 `skills/**` **受管**,守卫的读法才是裁定的那个;该裁决**已随本段上方的清单落地**(#6866):上面五项已含 `skills/**`,与脚本的 `GOVERNED_SURFACES` 一致,曾经那条「仓根 `skills/**` 不受管、自行入队」的豁免**已作废**,⛔ 别再照它行事。
535535
536536
### 服务纪律(本仓库与 `../objectstack` 多 agent 并行开发)
537537

0 commit comments

Comments
 (0)