docs(agents): state how a green PR lands, and the governed-surface exception

[huangyiirene]

Fixes #1742

AGENTS.md §✅ Verifying changes gains one subsection, How a green PR lands, plus an empty-frontmatter changeset. No workflow, no script, no gate, no automation — the card is about writing the rule down, and a gate is a separate decision nobody has made.

What it says

A seat may take a PR out of draft and arm auto-merge once every check has finished with none failed, unless the diff touches a governed path — AGENTS.md, CLAUDE.md, .claude/**, .github/instructions/** — in which case the PR stays a draft and the maintainer merges it. Maintainer ruling on #1742, decision batch #81 (issuecomment-5578141346), option A, chosen over "every PR waits for the maintainer".

The governed set is transcribed exactly as ruled: not widened, not narrowed, no "and anything sensitive" clause.

⚠️ This PR edits AGENTS.md, so it is itself governed: it stays a draft, has no auto-merge, and is the maintainer's own merge. The rule documenting itself.

Three measurements that changed the text

1. The filer's "zero hits" is off by one — the gap is still real

Re-ran the search at f1fc2127, same six terms, same four scopes (AGENTS.md, CONTRIBUTING.md, docs/**, .github/**), case-insensitive:

term	matching lines
auto-merge	0
automerge	0
merge queue	0
merge-queue	0
squash	1
ready-for-review	0

The hit is CONTRIBUTING.md:210 — Branch will be squash-merged, inside §Getting Merged. It states merge mechanics and never says who may perform the merge, so it does not close #1742's gap; but "zero" was not right, and the section it lives in has a worse problem. Filed separately as #1797: that same list says "At least one approval required", and PR #1795 merged with get_reviews returning []. ⛔ Not fixed here — different file, different reader, and #1742 is AGENTS.md-only.

Counts are grep -c on matching lines, not grep -o occurrences.

2. "Every check green" was not writable as-is

Two checks in this repo are routinely neither green nor red, so a literal reading is undecidable:

• Check Changeset concludes skipped under the skip-changeset label — changeset-check.yml:14 is if: "!contains(github.event.pull_request.labels.*.name, 'skip-changeset')". Observed on PR chore(deps): bump better-sqlite3 from 12.11.1 to 13.0.3 #1058: "name":"Check Changeset","conclusion":"skipped".
• link-check never runs at all on a diff carrying no Markdown — link-check.yml's pull_request trigger is filtered to '**/*.md', '**/*.mdx'. Observed by contrast: present on PR ci(labels): declare the 22 live-but-undeclared labels in the manifest #1795, absent from PR chore(deps): bump better-sqlite3 from 12.11.1 to 13.0.3 #1058's eight check runs entirely.

The text therefore says finished and none failed, and names both cases. ⛔ No required-checks list is invented, because none was ruled. A third check, Vercel Preview Comments (details_url vercel.com/github, concludes success in 0s), is a non-CI check that exists on every PR — it is covered by the same wording without needing to be named.

3. ⚠️ The ruling's "merge queue" sentence does not hold in this repo — so it is not written down

The ruling closes with "The merge queue remains the only route in (a direct merge returns 405)." Measured, that is an objectstack fact, not a hotcrm one:

probe	hotcrm	objectstack
workflows subscribing to merge_group	0 (grep -rn merge_group .github/ exits 1)	10 files
live refs/heads/gh-readonly-queue/* on origin	0	4

hotcrm has no merge queue. PR #1795 is consistent with this: its base.sha is dbe0ce16, but #1794 landed before it merged, and it merged anyway at 14:17:38 without a queue rebuild.

⇒ the section says arm auto-merge, the mechanism this repo actually has (allow_auto_merge: true), and keeps the ruling's intent — ⛔ never merge by hand — without naming a queue that does not exist here. Writing "merge queue" into the reference repo's AGENTS.md would have sent every future seat looking for one. The 405 claim itself was not tested: testing it means attempting a merge, which is forbidden.

Placement

New ### inside the existing ## ✅ Verifying changes, after ### Every PR carries a changeset and before ### Verifying UI in the browser. That section is already the PR lifecycle in order — verify, then changeset — and landing is the next step; the browser subsection is a how-to appendix that reads fine after it. No new top-level section needed.

Verification

Full chain, exit code captured before any pipe (pnpm verify > /tmp/verify.log 2>&1; EXIT=$?):

pnpm verify   EXIT=0

Chain is validate && typecheck && lint && lint:i18n-gate && hygiene && hygiene:tokens && build && test. Gate-printed verdict lines: ✓ Validation passed (1544ms), ✓ i18n lint gate: 0 i18n/missing-* issues, ✓ source hygiene clean, ✓ source token ratchet clean, ✓ Build complete (2413ms), and Test Files 165 passed (165) / Tests 3453 passed | 1 skipped (3454).

line_budget: N/A on the gate's own printed scope line, not by assertion — check-source-token-ratchet.mjs prints authored surface: src/**/*.ts minus src/translations, src/data, and this diff is one .md plus one .changeset/*.md. Run anyway: EXIT=0, ✓ source token ratchet clean, and its residual list (not in a headline layer) is entirely src/ subdirectories — no AGENTS.md, no .changeset.

link-check is in scope for this PR, since the diff carries .md. No link was added: the added lines contain no URL and no Markdown link syntax (grep -oE for both over the + lines exits 1). Issue references are plain #nnnn text.

Control characters: grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' over both changed files exits 1 (clean), independently of the hygiene gate's own ✓ no raw control bytes in first-party files.

Fence: test/** (epic #1579) not touched — git status --porcelain lists exactly M AGENTS.md and the new changeset, nothing else.

Changeset: empty-frontmatter, the sanctioned "releases nothing" declaration documented in changeset-check.yml:33-34 and :66-67. Precedent for this exact shape is .changeset/agents-md-pure-metadata-principles.md (AGENTS.md-only, empty frontmatter, reason stated). Nothing here ships to HotCRM users: no object, field, view, label, flow or hook.

Files changed

• AGENTS.md — +19 / -0, insertion only; no existing line rewritten, reordered or deleted
• .changeset/agents-md-states-how-a-green-pr-lands.md — new

Noted, not filed

• CONTRIBUTING.md §Getting Merged is the natural place to link this from, and the §Publishing note in the same file is the local model for "state the rule, link the runbook". No link was added, deliberately: the section it would point into is the one CONTRIBUTING.md §Getting Merged states "At least one approval required" — measured: PRs land with zero reviews, and it is now the second answer to the question #1742 just wrote down #1797 says is wrong, and AGENTS.md should not cite it until that is settled.

维护者速读（草稿）

改了什么 — AGENTS.md 加了一小节「How a green PR lands」：CI 全部跑完且没有失败的 PR，如果没碰治理面（AGENTS.md、CLAUDE.md、.claude/**、.github/instructions/**），席位可以自己翻 ready 并挂自动合并；碰了治理面的，保持草稿、由你手工合并。就是你在决策批次 #81 回的那个 A。

为什么改 — 这条规矩本来就在执行，只是没写下来。没写下来的规矩每个 agent 都要自己重新推一遍，而推导正是它们分岔的地方——分岔在造成一次错误合并之前完全看不见。三个兄弟仓都写了，hotcrm 是唯一沉默的，而它是参考实现。

风险与代价（含回滚） — 风险很低：一段散文，不新增任何能力、机制或门禁，仓库设置本来就允许自动合并。回滚就是 revert 这一个 commit，没有数据迁移、没有配置变更、没有别的文件依赖它。

⚠️ 有一处我按实测改了措辞，请你过目：裁决原文说「合并队列是唯一入口」，但这个仓没有合并队列（0 个 workflow 订阅 merge_group，origin 上 0 个队列分支；objectstack 分别是 10 和 4）。所以正文写的是「挂自动合并」这个本仓真实存在的机制，保留了「席位不手工合并」的原意。如果你的本意确实是要给 hotcrm 上合并队列，那是另一张卡，这段话要改。

席位意见 — （留空，待你裁定）

你要做的 — ⚠️ 这张 PR 自己就是治理面（它改的就是 AGENTS.md），所以它保持草稿、不挂自动合并、等你手工合并——这正是它写下来的那条规矩作用在它自己身上。你只需要：确认上面那处措辞偏差可以接受，然后合并它。顺带一提，CONTRIBUTING.md 里「至少一个 approval」那条是假的（PR #1795 零 review 就合了），已单独立成 #1797，不在这张 PR 里动。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01PpRjGNnwyo2J1rrmekxB1W

---

Generated by Claude Code

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated
hotcrm	Ignored		Sep 8, 2026 2:34pm UTC