From 43d5f125156955341eb320ed38620487e64fe447 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 8 Sep 2026 14:31:47 +0000 Subject: [PATCH] docs(agents): state how a green PR lands, and the governed-surface exception MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AGENTS.md said nothing about what a seat does with a finished, green PR. The repository permits auto-merge, so the capability existed while the authorisation did not — and an unwritten rule is re-derived by every seat, which is where seats diverge, invisibly, until the divergence produces a merge nobody authorised. Maintainer ruling on #1742, decision batch #81: 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. "Every check green" is written as finished-and-none-failed because two checks here are routinely neither green nor red: Check Changeset concludes `skipped` under the skip-changeset label, and link-check never runs on a diff carrying no .md. No required-checks list is invented, because none was ruled. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01PpRjGNnwyo2J1rrmekxB1W --- .../agents-md-states-how-a-green-pr-lands.md | 31 +++++++++++++++++++ AGENTS.md | 19 ++++++++++++ 2 files changed, 50 insertions(+) create mode 100644 .changeset/agents-md-states-how-a-green-pr-lands.md diff --git a/.changeset/agents-md-states-how-a-green-pr-lands.md b/.changeset/agents-md-states-how-a-green-pr-lands.md new file mode 100644 index 000000000..25771dd24 --- /dev/null +++ b/.changeset/agents-md-states-how-a-green-pr-lands.md @@ -0,0 +1,31 @@ +--- +--- + +`AGENTS.md` 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 at lines 33-34 and 66-67, on par with +the `skip-changeset` label). No `src/` metadata changed: no object, field, view, label, +flow or hook. + +§✅ Verifying changes gains **How a green PR lands**, the posture this repo practised but +never wrote down: 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, chosen over +"every PR waits for the maintainer". + +Measured before writing, because the card turns on a zero: the filer's six terms +(`auto-merge`, `automerge`, `merge queue`, `merge-queue`, `squash`, `ready-for-review`) +across `AGENTS.md`, `CONTRIBUTING.md`, `docs/**` and `.github/**` return one hit, not +zero — `CONTRIBUTING.md:210` "Branch will be squash-merged", under §Getting Merged, which +states merge *mechanics* for a human contributor and never says who may perform the +merge. So the authorisation gap the card describes is real; the "zero hits" figure it +cites is off by one on a line that does not close it. + +"Every check green" is stated as *finished and none failed* rather than literally green, +because two checks in this repo are routinely neither green nor red: `Check Changeset` +concludes `skipped` under the `skip-changeset` label +(`.github/workflows/changeset-check.yml:14`), and `link-check` never runs at all on a +diff carrying no `.md` (`link-check.yml` `pull_request.paths`). Both were read off real +PRs — #1058 shows the skip and the absence, #1795 shows `link-check` present when the +diff does carry Markdown. No required-checks list is invented, because none was ruled. diff --git a/AGENTS.md b/AGENTS.md index cb981e201..a96e323ed 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -575,6 +575,25 @@ The lone exception is the **`skip-changeset`** label, for PRs that ship nothing users (CI-only chores, repo housekeeping). Do not reach for it to get a red check green — write the changeset instead. +### How a green PR lands + +**A seat may take a PR out of draft and arm auto-merge once every check on it has +finished and none has failed — unless its diff touches a governed path.** The governed +paths are `AGENTS.md`, `CLAUDE.md`, `.claude/**` and `.github/instructions/**`, and one +governed path governs the whole diff however small that part of it is. A governed PR +**stays a draft** and is the maintainer's own merge: ⛔ a seat never flips it ready and +⛔ never arms auto-merge on it. Arming auto-merge is a seat's only landing route — +⛔ never merge by hand. A check that concluded `skipped` (`Check Changeset` under the +`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. + +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. + ### Verifying UI in the browser The Console renders dashboards, charts, and views from metadata. When verifying a