Skip to content

Commit fafba3c

Browse files
deruelleclaude
andauthored
compound: absent-by-design config is not drift (merge_queue / #6512 session) (#6521)
Captures tonight's misdiagnosis: I flagged the absent `merge_queue` rule in ruleset-ci-required.tf as fixable "config drift" and proposed re-adding it. It was absent BY DESIGN — reverted 2026-06-30 because CodeQL posts no status on `merge_group` (upstream github/codeql-action#1537, verified still OPEN), so a merge queue and a required CodeQL check are mutually exclusive. Re-adding it would have dropped a required security gate. A monthly watcher (codeql-1537-revisit-watch.yml) + tracking issue #5840 already manage the re-adoption window. Lesson: absence + upstream-issue ref + watcher is the signature of by-design, not drift. Grep the owning file for revert/blocker/upstream markers before proposing a fix. Sibling of hr-verify-repo-capability-claim-before-assert. No AGENTS.md rule added: domain-scoped, and the always-loaded payload is already at 22.8k (>22k critical). Also records the cleanup-merged empty-worktree footgun. Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
1 parent 9649baa commit fafba3c

1 file changed

Lines changed: 117 additions & 0 deletions

File tree

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
title: An absent config with an upstream blocker + watcher is not drift — verify intent before proposing a fix
3+
date: 2026-07-16
4+
category: integration-issues
5+
module: infra/github
6+
tags: [terraform, github-ruleset, merge-queue, codeql, config-diagnosis, false-drift, review-reasoning]
7+
related_issues: [6512, 5780, 5840, 6458]
8+
related_learnings:
9+
- knowledge-base/project/learnings/2026-07-15-false-comment-shipped-the-bug-then-plan-guard-adr-and-tests-each-restated-it.md
10+
---
11+
12+
# Learning: an absent config that is absent-*by-design* looks identical to drift
13+
14+
## Problem
15+
16+
While closing out the #6458 session I hit real, repeated pain: the strict
17+
"require branches up to date" policy sent the PR back to `BEHIND` three times as
18+
`main` advanced, forcing a manual `gh pr update-branch` each time. I noticed
19+
`infra/github/ruleset-ci-required.tf` *mentions* a GitHub merge queue — the exact
20+
mechanism that would absorb this churn — but the live ruleset has no `merge_queue`
21+
rule. I flagged it as **config drift** ("documented intent, never applied") and
22+
proposed fixing it by adding the rule.
23+
24+
That was wrong, and the fix would have been a security regression.
25+
26+
## Investigation
27+
28+
Reading the file properly instead of skimming its comments:
29+
30+
- The `merge_queue` block was **added by #5780 and deliberately REVERTED on
31+
2026-06-30**. Its absence is the intended state, not an omission.
32+
- Reason (stated verbatim in the file): a merge queue posts status checks on the
33+
`merge_group` ref, but **CodeQL reports no status on `merge_group` in ANY setup
34+
mode** (upstream `github/codeql-action#1537`). A merge queue and a *required*
35+
`CodeQL` check are therefore mutually exclusive on GitHub.
36+
- `CodeQL` is a required context in the same ruleset (`context = "CodeQL"`), and a
37+
comment says outright: *"DO NOT re-adopt the queue by converting CodeQL to
38+
advanced setup … decision is to keep CodeQL required."*
39+
- The re-adoption window is already automated: `codeql-1537-revisit-watch.yml`
40+
polls #1537 monthly and, when it closes, comments on standing tracking issue
41+
**#5840** (`merge-queue-revisit`) and flags it `needs-attention`.
42+
43+
Live check at the time: `gh issue view 1537 --repo github/codeql-action` → still
44+
**OPEN** (updated 2026-05-22). The blocker is current, not stale. Re-adding the
45+
rule would have dropped a required security gate to buy merge-queue convenience.
46+
47+
## Root cause
48+
49+
Two ordinary things combined to make a correct state read as a bug:
50+
51+
1. **A recurring symptom primed the wrong diagnosis.** The `BEHIND` starvation was
52+
genuinely painful and genuinely what a merge queue fixes, so "the queue is
53+
missing" felt *confirmed by the symptom* before the file was read. The pain was
54+
real; the causal story ("missing because nobody applied it") was invented.
55+
2. **Absent-by-design is visually identical to drift.** A file that discusses a
56+
mechanism it does not currently declare looks the same whether the mechanism was
57+
never added or was added and removed on purpose. The distinguishing evidence —
58+
REVERT date, upstream-issue ref, a watcher, a tracking issue — lives in prose
59+
comments that a skim glides over.
60+
61+
## Key insight
62+
63+
**Before flagging a missing/absent piece of infrastructure as fixable drift,
64+
prove the absence is accidental rather than deliberate.** The tell for
65+
*deliberate* absence is cheap to grep for in the same file:
66+
67+
```bash
68+
# In the file that "should" declare the missing thing, look for intent-to-omit:
69+
grep -niE 'revert|removed|do not (re-?adopt|re-?add|enable)|mutually exclusive|kill.?switch|upstream (issue|bug)|#[0-9]+' infra/github/ruleset-ci-required.tf
70+
```
71+
72+
If any of those hit near the mechanism, the absence is a decision — find the
73+
decision's blocker and its re-visit trigger (a watcher workflow, a tracking issue)
74+
before proposing to "fix" it. Re-adding a by-design omission can *undo the reason
75+
it was omitted*; here that reason was a required security check.
76+
77+
Corollary: a painful recurring symptom is evidence that *a* problem exists, never
78+
evidence for *your* explanation of it. Read the authoritative source before letting
79+
the symptom pick the cause.
80+
81+
## Prevention
82+
83+
- **Grep the owning file for revert/blocker/upstream markers** (above) as step 1 of
84+
any "this infra looks missing" claim. Absence + an upstream issue ref + a watcher
85+
is the signature of by-design, not drift.
86+
- **Check for a standing watcher/tracking issue.** Repos that revert something
87+
pending an upstream fix tend to leave a monthly watcher and a labelled tracking
88+
issue. If one exists, the omission is managed; there is nothing to fix.
89+
- **Name the security/consistency cost of re-adding** before proposing it. If
90+
re-adding the thing weakens a required gate, that is a regression regardless of
91+
the convenience gained.
92+
93+
This is the sibling of `hr-verify-repo-capability-claim-before-assert`: that rule
94+
guards against asserting a capability *exists*; this guards against asserting a
95+
capability is *missing-as-a-bug*. Both are "read the source before you assert."
96+
97+
## Session Errors
98+
99+
- **Misdiagnosed absent `merge_queue` as fixable drift** — Recovery: read the file's
100+
own revert comment + checked upstream #1537 live (still OPEN) + confirmed the
101+
watcher/#5840 apparatus, then withdrew the proposal. Prevention: the grep
102+
heuristic above, run before flagging absent infra as drift.
103+
- **`cleanup-merged` deleted a freshly-created empty worktree** — a branch created
104+
at `main`'s HEAD has no commits, so `git branch --merged main` classifies it as
105+
merged and the sweeper removes it. Recovery: recreated the worktree and gave the
106+
branch a commit immediately. Prevention: when creating a worktree purely to hold
107+
new work, make the first commit before running any `cleanup-merged`, or have the
108+
sweeper skip zero-commit-ahead branches younger than N minutes (candidate
109+
follow-up — different subsystem, not fixed here).
110+
- **`gh issue create` rejected without `--milestone`** — Recovery: re-ran with
111+
`--milestone "Post-MVP / Later"` (the documented default for operational issues).
112+
Prevention: already hook-enforced; no change needed.
113+
114+
## Tags
115+
116+
category: integration-issues
117+
module: infra/github

0 commit comments

Comments
 (0)