docs(agents): 合并指引收口为一条实测的队列教条 —— 两处 --auto 禁令与队列 hedge 不再自相矛盾 (#6118)

[hotlong]

Fixes #6118

AGENTS.md 的合并指引三处互相矛盾:§7 标题写「Never gh pr merge --auto」,Post-Task Checklist 第 2 条重复同一禁令,而 §7 自己下面又写着「队列启用后 add to queue 才是正道」—— 挂 auto-merge 正是入队手段,今天全部落地也正是走这条路。本 PR 把三处收口成一条按本仓实测写成的合并教条。

⛔ 按单里的硬约束执行:不照抄 objectui#3522 的叙述,不外推它的 405 实测。下面每一条断言要么在本仓测到(附 PR / run 号),要么显式标注未测。

前提复核(先证后写)

前提成立,但行号又漂了一轮。分诊评论给的是 184 / 188 / 761;我的 base(01faeb1,= #6237)上是 193 / 197 / 770。按内容定位,不按行号。

分诊说	我的 base 上	原文
184	193	7. **Merge only after remote CI is fully green. Never `gh pr merge --auto`.**
188	197	Once the repo's merge queue is enabled, "add to queue" IS the sanctioned
761	770	never `gh pr merge --auto`)

全仓 grep -rn -- "merge --auto" 只有这两处禁令(均在 AGENTS.md),没有第三处需要同步。

改写的四处

1. §7 标题(193–196)—— 禁令翻转为正道

改前

7. Merge only after remote CI is fully green. Never gh pr merge --auto.
   Auto-merge can land a still-red PR onto shared main and break it for every parallel agent (see Validation rules: 6 of 9 spec rule types are declared but not enforced at runtime #1475). Merge serially; rebase other open branches before merging the next one.

改后

7. Land through the merge queue: arm auto-merge on a PR that is already green, accepted and non-draft, then let the queue merge it. Arming is how you enter the queue, and the queue is what makes arming safe — it rebuilds your PR as merged onto the current main, re-runs the subscribing workflows on that rebuilt generation, and lands it only if the required ones pass. That is the §10 re-verification, done by the platform, race-free.

2. §7 的 hedge(197–206)—— 「once enabled」的条件句换成本仓读数

改前(半更新的 hedge,与标题打架)

Once the repo's merge queue is enabled, "add to queue" IS the sanctioned path — it is the opposite of the auto-merge this rule bans: …

改后(拆成四段:实测所指 → 旧禁令为真的那一半 → required 集的边界 → 三条重挂情形 + 一条非修法 + 未测项 + fallback)

What "the queue validates" means here, measured (origin/main, 2026-08-07): three of this repo's 22 workflows carry an on: merge_group: trigger — ci.yml, lint.yml, spec-liveness-check.yml — and the Actions API reports 2742 merge_group runs, the most recent 30 all on gh-readonly-queue/main/pr-* refs, all three workflows, all green. A fourth workflow, merge-queue-triage.yml, is not a subscriber: it watches those runs through workflow_run …

This supersedes the older "never gh pr merge --auto" ban. Its premise — auto-merge lands a still-red PR on shared main (#1475) — is inverted by rebuild-then-land … Its true half survives, as a precondition rather than a prohibition: arm only what is already green and accepted …

The queue enforces only the required set; everything else is advisory and rides through. …

⚠️ 对分诊读数的一处修正:分诊评论写「4 of 22 订阅 merge_group,含 merge-queue-triage.yml」。实测该文件的 on: 是 workflow_run(workflows: [CI], types: [completed]),merge_group 只出现在它的 if: 过滤条件里 —— 它观察队列世代的 CI 结果并在红时发诊断评论,自己不在队列世代上跑。所以订阅者是 3 个,观察者 1 个,两者作用不同,散文里分开写了。旁证:仓内 .changeset/agents-releases-freeze-merge-queue.md 自述「the three required-check workflows gain merge_group: triggers」。

3. Post-Task Checklist 第 2 条(770)—— 第二处禁令

改前

…and merge it after remote CI is fully green (see Multi-agent discipline: never straight to main, never gh pr merge --auto).

改后

…and — once remote CI is fully green and the PR is accepted — arm auto-merge so the queue lands it (Multi-agent discipline §7: never straight to main; never arm a PR that isn't green yet).

4. §10 的同族过期 hedge(原 256 行)—— 顺手改正,同一处矛盾的第四张脸

改前:CI on the PR (and the merge queue, once enabled) validates the merge commit itself
改后:CI on the PR, and then the merge queue on its rebuilt generation (§7), validates the merge commit itself

「once enabled」和 §7 的 hedge 是同一句条件句的两个副本;留着它,读者仍会以为队列没开。

实测证据表(每条断言 → 证据号 / 「未测」)

断言	证据	判定
队列在本仓是活的,且在重建世代上重跑检查	Actions API:event=merge_group 共 2742 次运行;最近 30 次全部落在 gh-readonly-queue/main/pr-* 上(如 pr-6237-… / pr-6233-… / pr-6228-… / pr-6210-… / pr-6209-…),全 success	实测
22 个 workflow 中 3 个带 on: merge_group:	origin/main (01faeb1) 上 grep:ci.yml:16 / lint.yml:13 / spec-liveness-check.yml:30;release.yml:471 是注释,不是触发器	实测
merge-queue-triage.yml 是观察者不是订阅者	该文件 on: workflow_run(:36–39),merge_group 只在 :47 的 if: 里	实测
auto-merge → 入队 → rebuild-then-land 是今天的落地路径	#6059(01:04:15Z 重挂 → 01:25:00Z 合入)、#6097(01:46:50Z 合入)	实测
队列会因你这一世代的红把条目踢出,且 triage 会评论	#6059 01:03:02Z 被踢;merge-queue-triage 于 01:03:27Z 评论,点名 run 31136158512 与失败用例	实测
踢出会掉 auto-merge,必须重挂	#6059 —— 车道于 01:04:15Z 重挂后才落地	实测
前车失败导致的连带踢出按设计无评论	merge-queue-triage.yml 自述:Fires on conclusion == failure ONLY. 'cancelled' is the queue evicting an entry because something AHEAD of it failed … so it gets no comment	实测(workflow 源码)
required 集之外的检查是 advisory,红着也能过队	#6067 的队列世代 gh-readonly-queue/main/pr-6067-db0d53c2…,Lint & Type Check run 31136745851 = completed/failure(01:12:11Z),合并于 01:13Z(merge commit f226605)	实测
该红随 merge ref 毒化后续每个 PR 的 ESLint job	#6100(受影响面:#6048 / #6059 / #6091 / #6092 及此后每条);同形先例 #5584 → #5601 → 热修 #5615	实测
ESLint / TypeScript Type Check 现已进入分支保护 required 集与队列检查集	#5617:维护者 2026-08-07 执行;观测层反证 —— #5827 全检查结论后唯一非绿是 ESLint 而 mergeable_state=blocked,对照 #6093 零 review 合入(⇒ 本仓不要求 review ⇒ blocked 只能来自 required check)	实测(设置页本身 agent 无权限直读,以 #5617 存档读数为准)
在没绿的 PR 上挂 auto-merge 不会入队,只会藏起来	#4852 —— 10:15 挂上,因 CI 红从未入队,空转 100 分钟	实测(仓内记录)
rerun_failed_jobs 复用原 run 的提交与合并 ref,拿不到之后合入的修复	#4852 的红在止血 #4856 落地前重跑仍逐字节相同	实测(仓内记录)
转回 draft 同时掉 auto-merge 与队列成员资格,且不自动恢复	.claude/skills/pm-dispatch/SKILL.md Operational note 1(:146)与接力纪律(:1727)—— 仓内在册操作纪律	⚠️ 本轮未用 API 独立复测,散文里已如实标注
直接(非 auto)gh pr merge 在本仓是否 405	—	⛔ 未测

显式标注为未测/未复测的两项

1. 直接 gh pr merge 是否 405 —— 要确证只能在一个活 PR 上真做一次合并,按单里明令不做这个实验。散文原文:"Not measured here … objectui returns 405; that is not extrapolated to this repo (objectui#3243) — separate rulesets, and 红的 ESLint job 没有拦住合并:PR #5584 在 ESLint 已红 19 分钟的情况下过队合入 —— main 的 required-status-check 集需要维护者核查 #5617's cross-repo audit found the two configured differently."(红的 ESLint job 没有拦住合并:PR #5584 在 ESLint 已红 19 分钟的情况下过队合入 —— main 的 required-status-check 集需要维护者核查 #5617 的跨仓审计正好记录了两仓配置不同:objectui 零 merge_group 订阅,队列必需集为空。)
2. draft 翻转掉 auto-merge/队列成员资格 —— 是仓内在册操作纪律,不是本轮的 API 读数;容器里 api.github.com 的未认证 REST 被代理拦掉(HTTP 403),timeline 事件读不到,而复测它需要真去 arm/翻转一个活 PR。散文里就地标注 "not an API measurement",不冒充实测。

反向引用与编号完整性

⛔ 一个编号都没动(§1–§11 位置不变),全部为就地改写。逐条核过:

引用方	引的是	改后是否仍成立
.claude/skills/pm-dispatch/SKILL.md:1544	AGENTS.md §7「无队列时串行合并、只在远端 CI 全绿后合」	✅ 成立 —— fallback 段原样保留了这句话
.claude/skills/pm-dispatch/SKILL.md:1590	§3(禁 rebase / force-push)	✅ 未触及
.claude/skills/pm-dispatch/SKILL.md:1736	§10(clean merge ≠ working merge)	✅ 未触及(仅改了其中一个子项的一句从句)
AGENTS.md:83	Multi-agent discipline §8(不杀别人的 server)	✅ 未触及
.claude/agents/os-dev.md:114	§9(stale artefact)	✅ 未触及
.changeset/agents-releases-freeze-merge-queue.md:6	「AGENTS.md multi-agent §10」	✅ 未触及
AGENTS.md 内部	:198 → §10、:308 → §9、:323 → §7、:329 → §10、:359/:375 → §9	✅ 全部指向未移位的条目

AGENTS.md:114 的「§7 Built」指的是 north-star.mdx 的 §7,不是本文件的 §7 —— 未受影响。

门禁

$ pnpm check:doc-authoring
✓ doc authoring guard: 365 files clean — no bare metadata literals.          EXIT=0

$ pnpm check:role-word
check-role-word: OK (44 baselined file(s), no new occurrences).              EXIT=0
  (作用域为 content/docs + skills/,AGENTS.md 本就不在其中;diff 里也没有引入
   任何一处 `role`/`roles`,已 grep 确认)

$ pnpm check:nul-bytes
check-nul-bytes: OK (scanned 5949 tracked text file(s); no raw ASCII control bytes).  EXIT=0

$ grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' AGENTS.md   # 门禁之外的自扫
(无命中)

关于 pnpm test / pnpm typecheck:本 PR 只动 AGENTS.md 一个文件,不属于任何 package 的源码面,跑包级测试与类型检查对本改动没有判别力 —— 如实记录为「不适用」,不凑一份看起来像验证过的输出。真正有判别力的是上面三道文档门禁 + 反向引用核查。

本 PR 走哪条路

只改 AGENTS.md(仓库流程文档),不发布任何包 ⇒ 按 pr-automation.yml 的处方走路线 2:skip-changeset 标签,不带 changeset。路线 3(空 frontmatter changeset)已于 #5471 / PR #6059 关闭,本 PR 不做它的第一个反例。

不在本 PR 里

• ⛔ 未改任何 workflow / ruleset / required 集 —— 设置面属维护者(红的 ESLint job 没有拦住合并:PR #5584 在 ESLint 已红 19 分钟的情况下过队合入 —— main 的 required-status-check 集需要维护者核查 #5617)。
• ⛔ 未照抄 objectui#3522 的散文,未外推它的 405。
• ⛔ 未动 content/docs/releases/、未动 .claude/**(SKILL.md 只读引用,未编辑)。
• ⛔ 编号未重排、未做结构搬移。
• git show --stat = 1 file changed。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 7, 2026 12:11pm