diff --git a/.changeset/agents-md-names-the-merge-queue.md b/.changeset/agents-md-names-the-merge-queue.md new file mode 100644 index 000000000..a02e53021 --- /dev/null +++ b/.changeset/agents-md-names-the-merge-queue.md @@ -0,0 +1,35 @@ +--- +--- + +Agent-facing governance doc only — this PR releases nothing to HotCRM users, so the +frontmatter above is deliberately empty (the sanctioned "releases nothing" declaration +that `.github/workflows/changeset-check.yml` documents, on par with the `skip-changeset` +label). No object, dataset, widget, layout, filter, translation or exported symbol +changed: the whole diff is `AGENTS.md` prose. + +`AGENTS.md` §How a green PR lands told every seat that a green, non-governed PR lands by +arming auto-merge, and deliberately never named a merge queue — PR #1798's body records +that omission as intentional, on the premise that this repo has no queue. The premise is +false. The section now names the queue as the mechanism arming hands off to. + +Re-measured on this branch before the prose was written, on both channels: + +- **Configuration.** `GET /repos/objectstack-ai/hotcrm/rulesets` returns one ruleset, + `main` (id 12187346), `enforcement: active`, whose rules are `deletion`, + `non_fast_forward`, **`merge_queue`** and `pull_request`. +- **Behaviour.** `added_to_merge_queue` / `removed_from_merge_queue` by + `github-merge-queue[bot]` on every recently merged PR — #1810, #1811, #1813, #1816. + +The gesture a seat performs is unchanged and nothing is rolled back: arming auto-merge +**enqueues**, and every PR that landed this round landed correctly. This is a description +defect, not a broken procedure. + +The section deliberately does **not** record `min_entries_to_merge_wait_minutes: 5` as a +wait a seat should expect, because measurement says it is not one. Nine merged PRs +(#1795, #1798, #1799, #1801, #1809, #1810, #1811, #1813, #1816) each took **17–20 seconds** +from `added_to_merge_queue` to `merged`. That parameter caps how long the queue *gathers* +a group before merging a smaller one, and never engages while `min_entries_to_merge` is +`1`. PR #1795's much-cited "5m40s from creation to merge" decomposes as **5m18s sitting +as a draft** while its checks ran, 5s from ready to enqueue, and **17s in the queue** — +so it is not evidence of the queue's wait either. The section warns against re-deriving +the five-minute figure instead of repeating it. diff --git a/AGENTS.md b/AGENTS.md index 19a2b2a05..3218e0ef6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -587,12 +587,23 @@ governed path governs the whole diff however small that part of it is. A governe `skip-changeset` label) or that never ran because a path filter excluded it (`link-check` on a diff carrying no `.md`) is not a failure. +**Arming does not itself merge — it enqueues.** This repo's `main` ruleset carries a +**merge queue**, and the queue is what performs the (squash) merge. Because a seat arms +only once every check has finished, the enqueue fires at once and the queue merges within +seconds — a green PR that pauses briefly after arming is landing, not stuck. ⛔ Do not +re-derive a five-minute wait from the ruleset's `min_entries_to_merge_wait_minutes`: that +parameter caps how long the queue *gathers* a group, and never engages while +`min_entries_to_merge` is `1`. + Written down because an unwritten landing rule is re-derived by every seat, and re-derivation is where seats diverge — invisibly, until the divergence produces a merge nobody authorised. > Ruling: #1742, decision batch #81 (2026-09-08), which chose this over "every PR waits -> for the maintainer". Governed surfaces graded on #1233. +> for the maintainer". Governed surfaces graded on #1233. *The queue is named here on +> #1815 — PR #1798 omitted it after two probes that cannot see a queue at rest; the +> repo's **rulesets** are the channel that answers, and the ruling's own "the merge +> queue remains the only route in" was right.* ### Verifying UI in the browser