ci: rule 3 does not reach a run that carries no per-commit answer

[JulienMartel]

What

docs/ci.md, one insertion into rule 3 (41 added, 20 of them rewrites of nothing — pure addition against main). Docs only.

Rule 3 bolds an absolute — "Only a PR run is ever in a shared group" — and the family has three standing counterexamples that the doc never mentioned. This writes the exemption.

Follow-up to #587, which narrowed rule 3's endorsement of hausfold.co so the paragraph could not be read as blessing them, but deliberately left the exemption itself unwritten.

Why

An unstated exemption is what the next PR "fixes". Three workflows key every run into one constant group with no github.sha in it, all in hausfold.co — deploy.yml, dns.yml, preview-sweep.yml — each on purpose and each commented (two of them) in its own file.

The property is written so the count is not load-bearing: what a gate loses when an intermediate run is dropped is that commit's answer, which nothing else will produce. These three converge something outside the repo instead — the deployed site, the DNS zone, this repo's own preview Workers — and a converge has no answer to lose, because the surviving run redoes the whole job from current state. For them the constant group is the point of the line, not a cost of it.

Three things the text is careful about, each of which a review caught in the first draft:

• The pull_request guard comes with a standing example, not a hypothetical. preview.yml converges something external and has a PR run, and keys on the PR number anyway — rule 3's ternary with only the PR arm left.
• The three do not share one cancel-in-progress reason. deploy cancels (a newer build supersedes outright); dns does not (a converge stopped between two tables leaves the zone half-way, its own words); the preview sweep does not for a completely different reason — its deletes are independent and an already-gone Worker counts as success, so nothing is half-written; there is simply nothing to supersede, and a dry_run dispatch would otherwise take out a live sweep. The first draft gave the sweep dns's reason, which its own job body contradicts.
• The cost is stated, not papered over. dns's scheduled check shares group: dns with publish, and a pending run is cancelled outright when a newer one joins whatever cancel-in-progress says — so a Monday check queued behind a running converge can be dropped, and that week's drift answer waits seven days. One writer on the zone is worth more than one week's report. That is a trade made once, for a converge, not a reason to key a gate this way.

Verify

Census over every public repo in the org at its origin/main, walking .github/workflows/* rather than trusting a list (ops is private and outside it; it runs a scheduled scoreboard and nothing on a push):

workflows in the family	27
carrying a concurrency: block	21
with a constant top-level group:	3, all in hausfold.co
deploy.yml	group: deploy, cancel-in-progress: true
dns.yml	group: dns, cancel-in-progress: false
preview-sweep.yml	group: preview-sweep, cancel-in-progress: false
any of the three with a pull_request: trigger	none — push+dispatch, push+schedule+dispatch, schedule+dispatch

Near misses, both correctly keyed and correctly excluded: scruff's release.yml (release-${{ github.ref }}) and hausfold.co's preview.yml (preview-${{ github.event.pull_request.number }}).

The fourth constant group a reader's grep will find is pounce's job-level bump-pin in release.yml. Release workflows are off this list by the doc's own line, and the text now says so in half a clause so the grep closes instead of reading stale.

Reasons checked against the workflows themselves, not assumed: deploy.yml and dns.yml each carry a comment stating theirs. preview-sweep.yml carries none — its reason here is read out of the job body (independent per-Worker DELETEs, a continue on per-Worker failure, Cloudflare 10007 treated as success, a dry_run dispatch input).

Pre-PR assurance pass run on the diff + AGENTS.md. Nothing at 5; the one 4/5 (the sweep's invented reason) and all three 3/5s (the "is not a gate" opener colliding with this file's own gate table, the dns scheduled-check arm, the fourth constant group) are fixed in this commit. No test in this repo asserts on docs/ci.md.

Watch out

• docs/ci.md is hot — CI: one run per commit, nothing from apt, and the rules written down #578, ci: haus is five ubuntu jobs, the shell half four of them #580 through ci: a fifth rule — group parallel jobs by need, not by step count #585, and ci: hausfold.co fixed what rule 3's paragraph still calls out #587 all landed in it today. Rebase onto main, never merge main in.

• bench overlap, verbatim:

  ≋  earshot — 6 other lane(s) on workshop; 0 in your way, 1 nearby
    · add-homebrew-formula docs/ci.md elsewhere in the file
  
  ⚠  merge-tree already conflicts (committed work only):
    ✗ add-homebrew-formula .agents/skills/docs-sync/SKILL.md
  ↳  rebase onto main once the other branch lands — never merge main into yours
  

  The ⚠ is on a file this branch does not touch. add-homebrew-formula does touch docs/ci.md, but only at the gate table near the top, nowhere near this insertion.

• preview-sweep.yml has no comment on its concurrency block, so after this lands docs/ci.md is the only place its cancel-in-progress: false is explained — the one fact here with no home in the repo that owns it. That is now ci: say why the sweep never cancels itself hausfold.co#348, which puts the reason in the file that owns it — land it first, or this doc is briefly the only copy.

• The doc's opener deliberately avoids the word "gate" for these three, because docs/ci.md's own gate table lists Deploy, DNS and the preview sweep among hausfold.co's gates. "Produces no per-commit answer" is the operative test; "not a gate" would have made the file contradict itself.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UMUHVTxRfgADnACNXzc6Ef