docs(agents): record the merge_group leg's SECOND refusal predicate (the contract-review carrier)

[claude]

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 docs(agents): cite by content, not by line address (#8875 clause 1) #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 finding(docs): AGENTS.md describes the queue guard's merge_group refusal as the approval predicate alone — objectui#9018 added a second, independent one and that paragraph is governed surface #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.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr

---

Generated by Claude Code

[claude]

PM review — ⛔ VERIFIED AND PARKED. This seat will NOT land it.

domain:devx @ objectui seat (#5748). ⚠️ This PR is on GOVERNED SURFACE and stays a DRAFT. It needs a human APPROVED review from GOVERNED_APPROVERS (os-zhuang / hotlong) and a human merge. ⛔ I have not flipped it ready, ⛔ not armed auto-merge, ⛔ not enqueued it, and ⛔ will not.

node scripts/check-governed-queue-guard.mjs --test AGENTS.md
  ⛔ GOVERNED — 1 of 1 path(s) are on a governed surface
     AGENTS.md x1 — the repo-root agent instruction file
     One governed path governs the WHOLE pull request — proportion is not a question.
  exit 3

⚠️ The green Governed Surface Queue Guard on this PR is NOT a clearance. That is the pull_request leg, which is deliberately exit 0 as an early warning — and this very paragraph in AGENTS.md says so: 「pull_request 腿是早期告警、故意 exit 0(受管 PR 停在 draft 正是健康终态,所以绿不等于不受管)」. ⭐ A reader who took that green as permission to enqueue would reproduce objectui#6596.

What I verified myself

The diff is as minimal as it can physically be. 1 file, 1 line, purely additive: the target paragraph is one physical line, base 1434 chars → 1835 (+401, −0).

It does not touch objectui#9301's region. That PR's single AGENTS.md hunk is @@ -107,6 +107,13 @@; this one is @@ -519,7 +519,7 @@. ⭐ ~400 lines apart — ⚠️ and I record here that my own earlier claim that these two collided 「on the same governed paragraph」 was never measured and was false, and it parked this p2 for hours. A blocker is a measurement, not a recollection.

⭐ The wording was PROPAGATED, not invented — which is the whole point. The card refused to propose wording (「a maintainer's call, not a seat's, and the file is governed precisely so that it is」), and the dev honoured that by taking the account already accepted in content/docs/guide/ci-cd-pipeline.md — not governed, and updated by PR objectui#9212 for exactly this reason:

:1710 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 … It enumerates every pull request the merge group is landing — per commit … because merge_group.head_ref names only the last pull request in the group … 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).

The inserted Chinese carries exactly those facts and no others. ⇒ the maintainer is being asked to accept a phrasing this tree already accepted elsewhere, not to adjudicate a new one. Five alternatives are offered in the PR body, ⛔ none in the file.

The substance, re-derived on origin/main — ⛔ not on the shared checkout, which is ~3 weeks stale:

git grep -n 'EXIT_REFUSED_CARRIER' origin/main -- scripts/check-governed-queue-guard.mjs
  :258  EXIT_REFUSED_CARRIER = 6            carried
  :259  EXIT_REFUSED_CARRIER_UNREADABLE = 7 unreadable, or the group names no pull request

⭐ And the leg reads a LABEL, ⛔ not a surface — CONTRACT_REVIEW_LABEL = 'needs:contract-review', read per queued pull request. ⇒ the paragraph's existing caveat (「覆盖面以脚本自己的 GOVERNED_SURFACES 为准」) cannot reach it: that delegates the surface list, and this leg consults no surface list at all.

⭐ Register was measured, not eyeballed: the target line runs 27 half-width ,, 13 (), 9 :, 5 ; against 2 full-width — and both full-width marks sit inside a verbatim untranslated maintainer quote. A first draft using full-width punctuation was discarded and redone.

⚠️ The same defect exists in a SECOND place — reported, ⛔ not filed, and it belongs to whoever rules on this

The guard's own --test renderer — the advisory a seat reads — describes the merge-queue refusal with the approval predicate alone:

The merge-queue run of "Governed Surface Queue Guard" refuses this diff unless an APPROVED review by an authorized approver … is on the pull request

⇒ the same false-by-omission shape, in the same permissive direction, one file over. ⚠️ It is arguably defensible — a path test cannot know about labels on a queue it has not seen — ⭐ which is exactly why it is a maintainer's call and not a seat's. ⛔ The dev did not touch it; ⛔ neither did I. Flagged here because the person reading this PR is the right audience for it.

Status

CI on the head: Governed Surface Queue Guard success (the advisory leg, see above), four Test shards still running, nothing failed. Gates run by the dev: check:control-bytes, docs:check-links, check:shell-escape-residue, check:governed-queue-guard self-test (185 cases, and its own output names this second predicate), check:required-check-set self-test — all exit 0 PRE and POST. No changeset owed.

⇒ Over to a maintainer. ⛔ Nothing further from this seat.

---

Generated by Claude Code