|
| 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