From 2fbcc149eca16f3b138470189f188e476d6cba5c Mon Sep 17 00:00:00 2001 From: lilyshen0722 Date: Tue, 29 Sep 2026 06:04:48 -0700 Subject: [PATCH 1/9] docs(checklist): rule 42 (a queued PR refuses every push) and rule 43 (a clearance binds a head the consumer can resolve) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two rules, both earned today, appended at EOF under their own headings. Rule 42 was drafted 2026-09-28 and held while #1994 claimed rule 41; that PR merged at 12:59:44Z as a20ea9b3, so this is the first cycle in which the numbers were free. 42 — a queued PR refuses every push (GH006), and that refusal is what keeps the pressed head equal to the gated head. Incident: #1984 was queued 95s after the % fold was asked for, so the fold became #1988 — a one-line catalog change billed as a PR with a rebase and two gates. The rule records that the queue merged the gated head faithfully and that the refusal is the mechanism holding rule 32's tree comparison true, not an obstacle. 43 — a clearance binds a head the consumer can resolve, and prose is not a head. Incident: TASK-186 carried "CODE PASS @ 1a811d84" in its board title for ~32h while #1988's PR held no code clearance at all; the pod line behind the claim named 58298156, a local commit the merge queue never let push, so the sha was resolvable in one clone and nowhere else. Verified through the numbering guard's own CI invocation (script extracted from origin/main, run from the repo root, --previous = the main this is based on): ✓ 43 rules, numbers 1..43 ascending with no gap, 21 citation(s) all resolve, and no rule changed its number or its name. Docs only: one file, +8 lines, no code and no tests. The guard is the test. --- docs/development/review-checklist.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/development/review-checklist.md b/docs/development/review-checklist.md index d2efd0f9c..d33900714 100644 --- a/docs/development/review-checklist.md +++ b/docs/development/review-checklist.md @@ -143,3 +143,11 @@ And then note where the fix landed. Someone hit the audience gap, felt it, and b **Never convert with `||` where a legal value is falsy.** `x || null` turns a deliberate `false` into `null` and a limit of `0` into `null`, and this model is full of both: `config` declares Booleans at `models/Integration.ts:270,286,301,304,397,398` and Numbers at `:272,276,299,372`. `x ?? null` is the shape when only `undefined`/`null` should become the clear value; `||` is safe only where every legal value is truthy — the `credentialRef`, `refreshTokenRef` and `providerSubject` String paths the instances below come from — and even there it is a fact to check about that path, not a habit to carry to the next one. Then keep one test per write path that drives the writer against a real in-memory Mongo and reads the row back, because the round-trip is the only instrument that can witness a no-op — and assert that the fields *beside* the cleared one are untouched, since a write that replaces the whole subdocument passes any assertion aimed at the single field. The failure itself is not a crash: it is a stale value nobody complains about, quiet for exactly as long as nothing compares it, and loud only where that comparison is a security decision. *(Earned: 2026-09-29, TASK-172 slice 3, three instances inside one slice — an unprefixed `$set` (rule 24's instance), a retired `refreshTokenRef` that survived a clear because `undefined` does not clear, and `providerSubject`: a token exchange that returned no ID token left the previous vendor account's subject on the row, so the next reconnect compared against a stale value, read "same account", and kept grants minted under whatever account held the row in between — the account-change rule that subject exists to enforce. The fix is a value in all three places, `|| null` there because all three are String paths whose legal values are all truthy — and precisely NOT the general prescription, since the same subdocument declares Booleans and Numbers where `||` would destroy a `false` or a `0`, which is the half Rhea's hold on the first version of this rule added. Her second hold removed a `required` distinction that does not exist — measured, either clear fails it, and an update validates neither verb unless `runValidators` is set — which is worth knowing about the rule itself: the first version coupled a real reader-visible distinction to a validator claim that was never run. The witness is a real-schema arm whose two assertions fail on the old code and pass on the new; that arm merges with the slice (TASK-172's stored-row callback suite, not on `main` when this rule was cut), which is why the rule is cut ahead of its code — a reviewer of the next connector write does not have to wait for it.)* + +## The merge queue + +42. **A queued PR refuses every push, and that refusal is what keeps the pressed head equal to the gated head.** Once a pull request is in the merge queue, GitHub rejects any push to its branch — `GH006: Protected branch update failed for refs/heads/ … branches that are queued for merging cannot be updated. To modify this branch, dequeue the associated pull request.` Read it as a mechanism rather than an obstacle: the queue merges the head it saw, so a delta arriving after queue entry cannot silently ride a stale clearance into main, and rule 32's tree comparison is then guaranteed rather than lucky. Land a late delta as a **follow-up PR** based on the merged main, citing the pre-rebase commit and showing per-file fidelity is empty (`git rebase --onto origin/main `, then `git patch-id --stable` per file); the costlier alternative is to dequeue, apply, re-gate and re-queue, which spends every stamp bound to the head. *(Earned: TASK-180's #1984 — ux-lead asked for the `%` fold at 04:48:45Z and the PR was queued at 04:50:20Z, 95 seconds later, so the fold could not land on that head at all and became #1988: one catalog line, a rebase and two gates. The queue had already merged the gated head faithfully — squash `f381b5aa` against `7f171637`, the three TASK-180 files byte-identical — so the pressed artifact was the reviewed artifact, which is the outcome the refusal buys. The operator-facing half is documented nowhere else: `GH006` / `queued for merging` / `merge queue` appear in exactly one tracked file, `.github/workflows/tests.yml:13`, and that comment is about the `merge_group` trigger, not about the push refusal.)* + +## What a clearance can bind + +43. **A clearance binds a head the CONSUMER can resolve, and prose is not a head.** A clearance naming a commit absent from the reader's clone — a local-only commit, a squashed-away branch head, a head from a different PR — is not a clearance, however carefully its content was verified, because nothing a press can read can confirm it. Carrying one across a PR boundary by arguing the artifact is byte-identical is the same error as arguing a test-only head move preserves a stamp: both reason from content, and rule 32 reasons from the head. If the head is not fetchable from the remote, the honest status is ungated — and `git cat-file -t` answering `commit` locally proves nothing about the remote, because the repository you can resolve it in is not the repository the press reads. *(Earned: TASK-186's #1988 — the row recorded "CODE PASS @ `1a811d84`" and put it in the board title for ~32h while `GET /pulls/1988/reviews` held exactly one review and no code clearance at all; the pod line behind the claim named `58298156`, a local commit the merge queue's `GH006` never let push. The sha is real in one clone and absent from every other, so the discriminating checks are `git merge-base --is-ancestor ` and whether the sha appears in `GET /pulls//reviews` — and reviews must be selected on `submitted_at` rather than on author, since every seat here posts under one GitHub identity.)* From fedced5564820c56e45e1c939bc5ebde18d5b186 Mon Sep 17 00:00:00 2001 From: lilyshen0722 Date: Tue, 29 Sep 2026 06:10:10 -0700 Subject: [PATCH 2/9] docs(checklist): fix both earned clauses against the ledger (rule 43's sha and spans, rule 42's file count) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sprint-review's CHANGES gate on b1515f59, all three findings confirmed by measurement rather than accepted on report. Two of the three were in the earned clauses, which is the worst place for them: the evidence IS the rule. Rule 43 named the wrong sha. The row recorded "CODE PASS @ 58298156" — the local-only commit, which is the whole point — at 06:54Z on 2026-09-28; the rule said 1a811d84, which is the head the row got RIGHT and which carried only the UX pass until a real code gate landed at 12:17:58Z. As written the example could not demonstrate its own rule: 1a811d84 is resolvable, so nothing about it is ungated. The spans were also wrong. Measured from the ledger: the row carried the claim 29.4h (06:54:19.520Z -> 12:17:58.983Z), the board title 8.7h (03:34:40.553Z -> 12:17:58.983Z, the 20.7h gap being the lag between the row and the title). The "~32h" matched neither. Added, because it is the mechanism the wrong sha came from: the title read "(UX PASS @ 1a811d84 + CODE PASS)" — it binds the sha to the UX pass and leaves the code pass bare, which is exactly how a reader collapses it into "CODE PASS @ 1a811d84". The wrong sha was not carelessness, it was the title's shape, and that shape is a second defect in the same title worth naming. Rule 42's "exactly one tracked file" was true of main and false at this head: b1515f59:.github/workflows/tests.yml plus b1515f59:docs/development/ review-checklist.md, because the rule quotes GH006 / "queued for merging" / "merge queue". Scoped to "before this entry existed", with the head-count stated so the next reader running git grep -l does not read two as a defect. Measured per string: GH006 and "queued for merging" appear only in this file at this head; "merge queue" is in both. Not changed: "95 seconds later". The two printed stamps (04:48:45Z, 04:50:20Z) differ by 95s as displayed; sprint-review's 94.3s is the same gap at sub-second precision, which the rule does not print. Guard, CI's own invocation, --previous = a20ea9b3: ✓ 43 rules, numbers 1..43 ascending with no gap, 21 citation(s) all resolve, and no rule changed its number or its name. --- docs/development/review-checklist.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/development/review-checklist.md b/docs/development/review-checklist.md index d33900714..4e9f92baa 100644 --- a/docs/development/review-checklist.md +++ b/docs/development/review-checklist.md @@ -146,8 +146,8 @@ And then note where the fix landed. Someone hit the audience gap, felt it, and b ## The merge queue -42. **A queued PR refuses every push, and that refusal is what keeps the pressed head equal to the gated head.** Once a pull request is in the merge queue, GitHub rejects any push to its branch — `GH006: Protected branch update failed for refs/heads/ … branches that are queued for merging cannot be updated. To modify this branch, dequeue the associated pull request.` Read it as a mechanism rather than an obstacle: the queue merges the head it saw, so a delta arriving after queue entry cannot silently ride a stale clearance into main, and rule 32's tree comparison is then guaranteed rather than lucky. Land a late delta as a **follow-up PR** based on the merged main, citing the pre-rebase commit and showing per-file fidelity is empty (`git rebase --onto origin/main `, then `git patch-id --stable` per file); the costlier alternative is to dequeue, apply, re-gate and re-queue, which spends every stamp bound to the head. *(Earned: TASK-180's #1984 — ux-lead asked for the `%` fold at 04:48:45Z and the PR was queued at 04:50:20Z, 95 seconds later, so the fold could not land on that head at all and became #1988: one catalog line, a rebase and two gates. The queue had already merged the gated head faithfully — squash `f381b5aa` against `7f171637`, the three TASK-180 files byte-identical — so the pressed artifact was the reviewed artifact, which is the outcome the refusal buys. The operator-facing half is documented nowhere else: `GH006` / `queued for merging` / `merge queue` appear in exactly one tracked file, `.github/workflows/tests.yml:13`, and that comment is about the `merge_group` trigger, not about the push refusal.)* +42. **A queued PR refuses every push, and that refusal is what keeps the pressed head equal to the gated head.** Once a pull request is in the merge queue, GitHub rejects any push to its branch — `GH006: Protected branch update failed for refs/heads/ … branches that are queued for merging cannot be updated. To modify this branch, dequeue the associated pull request.` Read it as a mechanism rather than an obstacle: the queue merges the head it saw, so a delta arriving after queue entry cannot silently ride a stale clearance into main, and rule 32's tree comparison is then guaranteed rather than lucky. Land a late delta as a **follow-up PR** based on the merged main, citing the pre-rebase commit and showing per-file fidelity is empty (`git rebase --onto origin/main `, then `git patch-id --stable` per file); the costlier alternative is to dequeue, apply, re-gate and re-queue, which spends every stamp bound to the head. *(Earned: TASK-180's #1984 — ux-lead asked for the `%` fold at 04:48:45Z and the PR was queued at 04:50:20Z, 95 seconds later, so the fold could not land on that head at all and became #1988: one catalog line, a rebase and two gates. The queue had already merged the gated head faithfully — squash `f381b5aa` against `7f171637`, the three TASK-180 files byte-identical — so the pressed artifact was the reviewed artifact, which is the outcome the refusal buys. Before this entry existed the operator-facing half was documented nowhere else: `GH006` / `queued for merging` / `merge queue` appeared in exactly one tracked file, `.github/workflows/tests.yml:13`, and that comment is about the `merge_group` trigger rather than the push refusal. Read that count as a fact about main *before* this rule landed — the rule quotes those strings, so it is itself the second file and `git grep -l` at this head returns two.)* ## What a clearance can bind -43. **A clearance binds a head the CONSUMER can resolve, and prose is not a head.** A clearance naming a commit absent from the reader's clone — a local-only commit, a squashed-away branch head, a head from a different PR — is not a clearance, however carefully its content was verified, because nothing a press can read can confirm it. Carrying one across a PR boundary by arguing the artifact is byte-identical is the same error as arguing a test-only head move preserves a stamp: both reason from content, and rule 32 reasons from the head. If the head is not fetchable from the remote, the honest status is ungated — and `git cat-file -t` answering `commit` locally proves nothing about the remote, because the repository you can resolve it in is not the repository the press reads. *(Earned: TASK-186's #1988 — the row recorded "CODE PASS @ `1a811d84`" and put it in the board title for ~32h while `GET /pulls/1988/reviews` held exactly one review and no code clearance at all; the pod line behind the claim named `58298156`, a local commit the merge queue's `GH006` never let push. The sha is real in one clone and absent from every other, so the discriminating checks are `git merge-base --is-ancestor ` and whether the sha appears in `GET /pulls//reviews` — and reviews must be selected on `submitted_at` rather than on author, since every seat here posts under one GitHub identity.)* +43. **A clearance binds a head the CONSUMER can resolve, and prose is not a head.** A clearance naming a commit absent from the reader's clone — a local-only commit, a squashed-away branch head, a head from a different PR — is not a clearance, however carefully its content was verified, because nothing a press can read can confirm it. Carrying one across a PR boundary by arguing the artifact is byte-identical is the same error as arguing a test-only head move preserves a stamp: both reason from content, and rule 32 reasons from the head. If the head is not fetchable from the remote, the honest status is ungated — and `git cat-file -t` answering `commit` locally proves nothing about the remote, because the repository you can resolve it in is not the repository the press reads. *(Earned: TASK-186's #1988. The row recorded "CODE PASS @ `58298156`" from 06:54Z on 2026-09-28 and carried it for **29.4h**; the board title carried "… (UX PASS @ `1a811d84` + CODE PASS)" for **8.7h** from 03:34Z the next morning. Throughout, `GET /pulls/1988/reviews` held exactly one review — ux-lead's — and no code clearance at all. `58298156` was a local commit `GH006` never let push: resolvable in one clone, absent from every other, so nothing a press reads could confirm it. The title's *shape* did as much damage as its content — binding the sha to the UX pass and leaving the code pass bare is what let a later reader collapse it into "CODE PASS @ `1a811d84`", and that head was real and resolvable and so looked verifiable. The discriminating checks are `git merge-base --is-ancestor ` and whether the sha appears in `GET /pulls//reviews` — and reviews must be selected on `submitted_at` rather than on author, since every seat here posts under one GitHub identity.)* From 82c0bd24892646abe0eba81d950d895cf43decaa Mon Sep 17 00:00:00 2001 From: lilyshen0722 Date: Tue, 29 Sep 2026 06:12:21 -0700 Subject: [PATCH 3/9] docs(checklist): lead rule 43 with the existence question, demote the rule-32 link to a neighbour note MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From the gate's answer on whether 43 is a rider on 32. It is a separate rule, and the reason is rule 41's own test applied to 32: every guard 32 sends you to check passes on #1988 — the head is fetchable, it never moved, and there is no merge to compare a clearance against — and the defect survives all of them. 32 asks an identity question, which presupposes a gate; 43 asks an existence question and sits upstream of that family. So the body now leads with the question 32 cannot ask and the 32 link is a neighbour note at the end, the way 41 handles 24. That ordering is the whole fix: the rule said the right thing in the order that made it read as a restatement of 32. Nothing operative changed. Kept, and named as the half 32 cannot reach: a sha resolving in the author's clone and nowhere else reads as sound to its author and as absent to every other seat. Neither side can see that asymmetry alone — which is why the incident needed both seats to close, and why the rule names the asymmetry rather than just the symptom. Removed from the earned clause: the discriminating checks, now stated in the body, so they appear once. Guard, CI's own invocation, --previous = a20ea9b3: ✓ 43 rules, numbers 1..43 ascending with no gap, 21 citation(s) all resolve, and no rule changed its number or its name. --- docs/development/review-checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/review-checklist.md b/docs/development/review-checklist.md index 4e9f92baa..e7e93da6a 100644 --- a/docs/development/review-checklist.md +++ b/docs/development/review-checklist.md @@ -150,4 +150,4 @@ And then note where the fix landed. Someone hit the audience gap, felt it, and b ## What a clearance can bind -43. **A clearance binds a head the CONSUMER can resolve, and prose is not a head.** A clearance naming a commit absent from the reader's clone — a local-only commit, a squashed-away branch head, a head from a different PR — is not a clearance, however carefully its content was verified, because nothing a press can read can confirm it. Carrying one across a PR boundary by arguing the artifact is byte-identical is the same error as arguing a test-only head move preserves a stamp: both reason from content, and rule 32 reasons from the head. If the head is not fetchable from the remote, the honest status is ungated — and `git cat-file -t` answering `commit` locally proves nothing about the remote, because the repository you can resolve it in is not the repository the press reads. *(Earned: TASK-186's #1988. The row recorded "CODE PASS @ `58298156`" from 06:54Z on 2026-09-28 and carried it for **29.4h**; the board title carried "… (UX PASS @ `1a811d84` + CODE PASS)" for **8.7h** from 03:34Z the next morning. Throughout, `GET /pulls/1988/reviews` held exactly one review — ux-lead's — and no code clearance at all. `58298156` was a local commit `GH006` never let push: resolvable in one clone, absent from every other, so nothing a press reads could confirm it. The title's *shape* did as much damage as its content — binding the sha to the UX pass and leaving the code pass bare is what let a later reader collapse it into "CODE PASS @ `1a811d84`", and that head was real and resolvable and so looked verifiable. The discriminating checks are `git merge-base --is-ancestor ` and whether the sha appears in `GET /pulls//reviews` — and reviews must be selected on `submitted_at` rather than on author, since every seat here posts under one GitHub identity.)* +43. **A clearance binds a head the CONSUMER can resolve, and prose is not a head.** The question is not whether the gated head equals the merged head but whether a clearance exists at all, at an object the press can fetch. A clearance naming a commit absent from the reader's clone — a local-only commit, a squashed-away branch head, a head from a different PR — is not a clearance, however carefully its content was verified, because nothing a press can read can confirm it; and `git cat-file -t` answering `commit` locally proves nothing about the remote, because the repository you can resolve it in is not the repository the press reads. If the head is not fetchable from the remote the honest status is ungated, and the checks that discriminate are `git merge-base --is-ancestor ` and whether the sha appears in `GET /pulls//reviews` — selected on `submitted_at`, never on author, since every seat here posts under one GitHub identity. Its own entry rather than a rider on rule 32, and the argument is 41's test applied to 32: every guard 32 sends you to check passes here — the head is fetchable, it never moved, and there is no merge to compare a clearance against — and the defect survives all of them. 32 asks an identity question, which presupposes a gate; this asks an existence question and sits upstream of that whole family. The one thing 32 cannot reach and this can: a sha resolving in the author's clone and nowhere else reads as sound to its author and as absent to every other seat, so neither side can see the asymmetry alone. *(Earned: TASK-186's #1988. The row recorded "CODE PASS @ `58298156`" from 06:54Z on 2026-09-28 and carried it for **29.4h**; the board title carried "… (UX PASS @ `1a811d84` + CODE PASS)" for **8.7h** from 03:34Z the next morning. Throughout, `GET /pulls/1988/reviews` held exactly one review — ux-lead's — and no code clearance at all. `58298156` was a local commit `GH006` never let push: resolvable in one clone, absent from every other, so nothing a press reads could confirm it. The title's *shape* did as much damage as its content — binding the sha to the UX pass and leaving the code pass bare is what let a later reader collapse it into "CODE PASS @ `1a811d84`", and that head was real and resolvable and so looked verifiable.)* From d1d56e4cc94ae54ad7103d9bbd3f672720e9a635 Mon Sep 17 00:00:00 2001 From: lilyshen0722 Date: Tue, 29 Sep 2026 06:14:23 -0700 Subject: [PATCH 4/9] docs(checklist): rule 42's file count is per string, not per union; rebase onto 87c73258 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The gate's non-blocking finding, folded because the entry is being touched anyway: "exactly one tracked file" is true of the union and false per string. Measured over the whole tree on main (no pathspec), `git grep -l -F` returns: GH006 -> 0 files · queued for merging -> 0 files · merge queue -> 1 file The one hit is .github/workflows/tests.yml:13, and lines 13-16 are about the merge_group trigger. So a reader grepping GH006 alone gets nothing and can read the rule as stale — which is the failure the sentence was written to prevent. Also rebased onto 87c73258 (main moved; #1995, disjoint — it does not touch this file). Text is otherwise unchanged from 9a8ec6e0. Guard, CI's own invocation, --previous = 87c73258: ✓ 43 rules, numbers 1..43 ascending with no gap, 21 citation(s) all resolve, and no rule changed its number or its name. --- docs/development/review-checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/review-checklist.md b/docs/development/review-checklist.md index e7e93da6a..a622b75ac 100644 --- a/docs/development/review-checklist.md +++ b/docs/development/review-checklist.md @@ -146,7 +146,7 @@ And then note where the fix landed. Someone hit the audience gap, felt it, and b ## The merge queue -42. **A queued PR refuses every push, and that refusal is what keeps the pressed head equal to the gated head.** Once a pull request is in the merge queue, GitHub rejects any push to its branch — `GH006: Protected branch update failed for refs/heads/ … branches that are queued for merging cannot be updated. To modify this branch, dequeue the associated pull request.` Read it as a mechanism rather than an obstacle: the queue merges the head it saw, so a delta arriving after queue entry cannot silently ride a stale clearance into main, and rule 32's tree comparison is then guaranteed rather than lucky. Land a late delta as a **follow-up PR** based on the merged main, citing the pre-rebase commit and showing per-file fidelity is empty (`git rebase --onto origin/main `, then `git patch-id --stable` per file); the costlier alternative is to dequeue, apply, re-gate and re-queue, which spends every stamp bound to the head. *(Earned: TASK-180's #1984 — ux-lead asked for the `%` fold at 04:48:45Z and the PR was queued at 04:50:20Z, 95 seconds later, so the fold could not land on that head at all and became #1988: one catalog line, a rebase and two gates. The queue had already merged the gated head faithfully — squash `f381b5aa` against `7f171637`, the three TASK-180 files byte-identical — so the pressed artifact was the reviewed artifact, which is the outcome the refusal buys. Before this entry existed the operator-facing half was documented nowhere else: `GH006` / `queued for merging` / `merge queue` appeared in exactly one tracked file, `.github/workflows/tests.yml:13`, and that comment is about the `merge_group` trigger rather than the push refusal. Read that count as a fact about main *before* this rule landed — the rule quotes those strings, so it is itself the second file and `git grep -l` at this head returns two.)* +42. **A queued PR refuses every push, and that refusal is what keeps the pressed head equal to the gated head.** Once a pull request is in the merge queue, GitHub rejects any push to its branch — `GH006: Protected branch update failed for refs/heads/ … branches that are queued for merging cannot be updated. To modify this branch, dequeue the associated pull request.` Read it as a mechanism rather than an obstacle: the queue merges the head it saw, so a delta arriving after queue entry cannot silently ride a stale clearance into main, and rule 32's tree comparison is then guaranteed rather than lucky. Land a late delta as a **follow-up PR** based on the merged main, citing the pre-rebase commit and showing per-file fidelity is empty (`git rebase --onto origin/main `, then `git patch-id --stable` per file); the costlier alternative is to dequeue, apply, re-gate and re-queue, which spends every stamp bound to the head. *(Earned: TASK-180's #1984 — ux-lead asked for the `%` fold at 04:48:45Z and the PR was queued at 04:50:20Z, 95 seconds later, so the fold could not land on that head at all and became #1988: one catalog line, a rebase and two gates. The queue had already merged the gated head faithfully — squash `f381b5aa` against `7f171637`, the three TASK-180 files byte-identical — so the pressed artifact was the reviewed artifact, which is the outcome the refusal buys. Before this entry existed the operator-facing half was documented nowhere else, and the count is **per string, not per union**: `merge queue` appeared in exactly one tracked file, `.github/workflows/tests.yml:13`, whose surrounding lines are about the `merge_group` trigger rather than the push refusal, while `GH006` and `queued for merging` appeared in **no** tracked file at all — `git grep -l -F` for the three strings over the whole tree on main returns 0, 0 and 1. Read those as the state of main *before* this rule landed, because the rule quotes all three: at this head it is the second file for every one of them, and a grep for `GH006` alone returning nothing is that pre-landing state and not a rule that has gone stale.)* ## What a clearance can bind From f625ff82cb6353380933c5483da88f022179203f Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Tue, 29 Sep 2026 06:17:45 -0700 Subject: [PATCH 5/9] =?UTF-8?q?docs(checklist):=20cut=20rule=2043=20down?= =?UTF-8?q?=20to=20existence=20=E2=80=94=20the=20sha=20was=20on=20the=20re?= =?UTF-8?q?mote=20all=20along?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ux-lead's second seat on the conclusion, and the finding is against my own rule's premise. Verified independently in a fresh clone before taking it: gh api repos/.../commits/58298156 -> resolves, parent 7f171637 git fetch origin 58298156deea4e... -> retrieves it git fetch origin 58298156 -> couldn't find remote ref advertised refs pointing at it -> 0 of 2,579 merge-base --is-ancestor 58298156 1a811d84 -> NOT an ancestor (a sibling) /pulls/1988/reviews -> 4 reviews, all commit_id=1a811d84 So "a local commit GH006 never let push" was false: the remote had it the whole time and a full-sha fetch gets it. What was missing was not resolvability but a gate — no review was ever taken at that head. Rule 43 now asks the existence question and nothing else; "absent from the reader's clone" is dropped as the test (an absence read in one clone is as clone-local as a presence read, and refs/pull//head keeps a squashed-away head fetchable), the instrument is commit_id, and --is-ancestor is named as a check that passes a spent stamp. Rule 42, both non-blocking asks folded: the follow-up PR is ungated until gated at its own head and the pre-rebase commit is provenance cited by full sha; the refusal keeps the merged head equal to the queued head, not to the gated one. Guard, CI's invocation, --previous = 87c73258: ✓ 43 rules, numbers 1..43 ascending with no gap, 23 citation(s) all resolve, and no rule changed its number or its name. --- docs/development/review-checklist.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/development/review-checklist.md b/docs/development/review-checklist.md index a622b75ac..bcfda9d08 100644 --- a/docs/development/review-checklist.md +++ b/docs/development/review-checklist.md @@ -146,8 +146,8 @@ And then note where the fix landed. Someone hit the audience gap, felt it, and b ## The merge queue -42. **A queued PR refuses every push, and that refusal is what keeps the pressed head equal to the gated head.** Once a pull request is in the merge queue, GitHub rejects any push to its branch — `GH006: Protected branch update failed for refs/heads/ … branches that are queued for merging cannot be updated. To modify this branch, dequeue the associated pull request.` Read it as a mechanism rather than an obstacle: the queue merges the head it saw, so a delta arriving after queue entry cannot silently ride a stale clearance into main, and rule 32's tree comparison is then guaranteed rather than lucky. Land a late delta as a **follow-up PR** based on the merged main, citing the pre-rebase commit and showing per-file fidelity is empty (`git rebase --onto origin/main `, then `git patch-id --stable` per file); the costlier alternative is to dequeue, apply, re-gate and re-queue, which spends every stamp bound to the head. *(Earned: TASK-180's #1984 — ux-lead asked for the `%` fold at 04:48:45Z and the PR was queued at 04:50:20Z, 95 seconds later, so the fold could not land on that head at all and became #1988: one catalog line, a rebase and two gates. The queue had already merged the gated head faithfully — squash `f381b5aa` against `7f171637`, the three TASK-180 files byte-identical — so the pressed artifact was the reviewed artifact, which is the outcome the refusal buys. Before this entry existed the operator-facing half was documented nowhere else, and the count is **per string, not per union**: `merge queue` appeared in exactly one tracked file, `.github/workflows/tests.yml:13`, whose surrounding lines are about the `merge_group` trigger rather than the push refusal, while `GH006` and `queued for merging` appeared in **no** tracked file at all — `git grep -l -F` for the three strings over the whole tree on main returns 0, 0 and 1. Read those as the state of main *before* this rule landed, because the rule quotes all three: at this head it is the second file for every one of them, and a grep for `GH006` alone returning nothing is that pre-landing state and not a rule that has gone stale.)* +42. **A queued PR refuses every push, and that refusal is what keeps the merged head equal to the queued head.** Once a pull request is in the merge queue, GitHub rejects any push to its branch — `GH006: Protected branch update failed for refs/heads/ … branches that are queued for merging cannot be updated. To modify this branch, dequeue the associated pull request.` Read it as a mechanism rather than an obstacle: the queue merges the head it saw, so a delta arriving after queue entry cannot silently ride a stale clearance into main, and rule 32's tree comparison is then guaranteed rather than lucky. It is not a clearance in itself, though — that the *queued* head is the *gated* head is still the press's job to check, which is rule 43's question. Land a late delta as a **follow-up PR** based on the merged main, showing per-file fidelity is empty (`git rebase --onto origin/main `, then `git patch-id --stable` per file); the costlier alternative is to dequeue, apply, re-gate and re-queue, which spends every stamp bound to the head. The follow-up is **ungated** until it is gated at its own head: cite the pre-rebase commit as provenance, by **full** sha, since a short sha will not fetch and a provenance citation that gets read as a clearance is the defect rule 43 exists for. *(Earned: TASK-180's #1984 — ux-lead asked for the `%` fold at 04:48:45Z and the PR was queued at 04:50:20Z, 95 seconds later, so the fold could not land on that head at all and became #1988: one catalog line, a rebase and two gates. The queue had already merged the gated head faithfully — squash `f381b5aa` against `7f171637`, the three TASK-180 files byte-identical — so the pressed artifact was the reviewed artifact, which is the outcome the refusal buys. Before this entry existed the operator-facing half was documented nowhere else, and the count is **per string, not per union**: `merge queue` appeared in exactly one tracked file, `.github/workflows/tests.yml:13`, whose surrounding lines are about the `merge_group` trigger rather than the push refusal, while `GH006` and `queued for merging` appeared in **no** tracked file at all — `git grep -l -F` for the three strings over the whole tree on main returns 0, 0 and 1. Read those as the state of main *before* this rule landed, because the rule quotes all three: at this head it is the second file for every one of them, and a grep for `GH006` alone returning nothing is that pre-landing state and not a rule that has gone stale.)* ## What a clearance can bind -43. **A clearance binds a head the CONSUMER can resolve, and prose is not a head.** The question is not whether the gated head equals the merged head but whether a clearance exists at all, at an object the press can fetch. A clearance naming a commit absent from the reader's clone — a local-only commit, a squashed-away branch head, a head from a different PR — is not a clearance, however carefully its content was verified, because nothing a press can read can confirm it; and `git cat-file -t` answering `commit` locally proves nothing about the remote, because the repository you can resolve it in is not the repository the press reads. If the head is not fetchable from the remote the honest status is ungated, and the checks that discriminate are `git merge-base --is-ancestor ` and whether the sha appears in `GET /pulls//reviews` — selected on `submitted_at`, never on author, since every seat here posts under one GitHub identity. Its own entry rather than a rider on rule 32, and the argument is 41's test applied to 32: every guard 32 sends you to check passes here — the head is fetchable, it never moved, and there is no merge to compare a clearance against — and the defect survives all of them. 32 asks an identity question, which presupposes a gate; this asks an existence question and sits upstream of that whole family. The one thing 32 cannot reach and this can: a sha resolving in the author's clone and nowhere else reads as sound to its author and as absent to every other seat, so neither side can see the asymmetry alone. *(Earned: TASK-186's #1988. The row recorded "CODE PASS @ `58298156`" from 06:54Z on 2026-09-28 and carried it for **29.4h**; the board title carried "… (UX PASS @ `1a811d84` + CODE PASS)" for **8.7h** from 03:34Z the next morning. Throughout, `GET /pulls/1988/reviews` held exactly one review — ux-lead's — and no code clearance at all. `58298156` was a local commit `GH006` never let push: resolvable in one clone, absent from every other, so nothing a press reads could confirm it. The title's *shape* did as much damage as its content — binding the sha to the UX pass and leaving the code pass bare is what let a later reader collapse it into "CODE PASS @ `1a811d84`", and that head was real and resolvable and so looked verifiable.)* +43. **A clearance has to exist as a record against the head being pressed, and prose is not a record.** The question is existence, not identity: not whether the gated content is what merged (that is rule 32), but whether *any* clearance was ever taken at the head the press will read. Use GitHub's own record rather than anyone's prose — every review in `GET /pulls//reviews` carries `commit_id`, the head it was submitted against, so "a review exists whose `commit_id` is the pressed head" answers the question without reading a single body. `submitted_at` orders reviews but does not bind them to a head, and it cannot be used to select one either: every seat here posts under one GitHub identity, so `.[-1]` returns whichever seat reviewed last. Two checks that look right and are not. `git merge-base --is-ancestor ` passes a clearance a later head move has already spent — `b8048c72` is an ancestor of `177ba436` — which is 32's class of defect, not this one. And a sha missing from your clone says nothing about the remote: a commit can be there with no ref pointing at it, so the remote has it, no ordinary fetch brings it in, and `refs/pull//head` keeps a squashed-away head fetchable — an absence read in one clone is as clone-local as a presence read. `commit_id` cannot tell a carry from a re-derivation, so the body still has to be read for that; it answers only whether a clearance exists at all. Its own entry rather than a rider on 32, and the argument is 41's test applied to 32: every guard 32 sends you to check passes here — nothing had merged, no head had moved, the required set was green — and the defect survives all of them, because 32 presupposes a clearance and this asks whether one exists. *(Earned: TASK-186's #1988. The row recorded "CODE PASS @ `58298156`" from 06:54Z on 2026-09-28 and carried it for **29.4h**; the board title carried "… (UX PASS @ `1a811d84` + CODE PASS)" for **8.7h** from 03:34Z the next morning. No clearance was ever taken at that commit: it is a **sibling** on `7f171637` rather than an ancestor of `1a811d84`, and `GET /pulls/1988/reviews` held four reviews, every one of them `commit_id=1a811d84`, of which only the first existed before 12:17Z the next day. The commit itself was confirmable — `gh api commits/` resolved it and a full-sha fetch retrieved it — but no advertised ref pointed at it — 0 of the 2,579 the remote advertised at the time — and `git fetch origin ` fails, so no ordinary fetch brought it into any other clone. So the commit could be confirmed and the gate could not, because there was no gate; a rule written about unresolvable heads would have mis-stated this incident. The title's *shape* did as much damage as its content — binding the sha to the UX pass and leaving the code pass bare is what let a later reader collapse it into "CODE PASS @ `1a811d84`", a head that was real and resolvable and so looked verifiable.)* From 59a017f6906b572f32d5c955217060529d065e8b Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Tue, 29 Sep 2026 06:24:06 -0700 Subject: [PATCH 6/9] =?UTF-8?q?docs(checklist):=20rule=2043's=20existence?= =?UTF-8?q?=20check=20is=20necessary=20and=20not=20sufficient=20=E2=80=94?= =?UTF-8?q?=20a=20review=20at=20the=20head=20can=20be=20a=20refusal?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ux-lead's re-gate, and the gap is the one my own ask left open. Their CHANGES @ d1d56e4c was itself the counterexample: that head's ONLY review was a refusal, so "a review exists whose commit_id is the pressed head" cleared a head that had just been refused. Measured before folding: #1988 reviews=4 states=COMMENTED #1989 reviews=10 states=COMMENTED #2000 reviews=4 states=COMMENTED All 18 reviews COMMENTED; not one APPROVED or CHANGES_REQUESTED. So `state` carries no verdict in this workflow and the verdict is the body's first line and nothing else. That is why the check has to be per required gate, against the first line, rather than against the presence of a review object. Rule 43 now says: a clearance has to exist as a PASS recorded against the head being pressed; existence is necessary and not sufficient; a head whose reviews are all refusals or all corrections ("Correction to my gate above" declares no verdict) is ungated. Guard, CI's invocation, --previous = 87c73258: ✓ 43 rules, numbers 1..43 ascending with no gap, 23 citation(s) all resolve, and no rule changed its number or its name. --- docs/development/review-checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/review-checklist.md b/docs/development/review-checklist.md index bcfda9d08..5bb1b636e 100644 --- a/docs/development/review-checklist.md +++ b/docs/development/review-checklist.md @@ -150,4 +150,4 @@ And then note where the fix landed. Someone hit the audience gap, felt it, and b ## What a clearance can bind -43. **A clearance has to exist as a record against the head being pressed, and prose is not a record.** The question is existence, not identity: not whether the gated content is what merged (that is rule 32), but whether *any* clearance was ever taken at the head the press will read. Use GitHub's own record rather than anyone's prose — every review in `GET /pulls//reviews` carries `commit_id`, the head it was submitted against, so "a review exists whose `commit_id` is the pressed head" answers the question without reading a single body. `submitted_at` orders reviews but does not bind them to a head, and it cannot be used to select one either: every seat here posts under one GitHub identity, so `.[-1]` returns whichever seat reviewed last. Two checks that look right and are not. `git merge-base --is-ancestor ` passes a clearance a later head move has already spent — `b8048c72` is an ancestor of `177ba436` — which is 32's class of defect, not this one. And a sha missing from your clone says nothing about the remote: a commit can be there with no ref pointing at it, so the remote has it, no ordinary fetch brings it in, and `refs/pull//head` keeps a squashed-away head fetchable — an absence read in one clone is as clone-local as a presence read. `commit_id` cannot tell a carry from a re-derivation, so the body still has to be read for that; it answers only whether a clearance exists at all. Its own entry rather than a rider on 32, and the argument is 41's test applied to 32: every guard 32 sends you to check passes here — nothing had merged, no head had moved, the required set was green — and the defect survives all of them, because 32 presupposes a clearance and this asks whether one exists. *(Earned: TASK-186's #1988. The row recorded "CODE PASS @ `58298156`" from 06:54Z on 2026-09-28 and carried it for **29.4h**; the board title carried "… (UX PASS @ `1a811d84` + CODE PASS)" for **8.7h** from 03:34Z the next morning. No clearance was ever taken at that commit: it is a **sibling** on `7f171637` rather than an ancestor of `1a811d84`, and `GET /pulls/1988/reviews` held four reviews, every one of them `commit_id=1a811d84`, of which only the first existed before 12:17Z the next day. The commit itself was confirmable — `gh api commits/` resolved it and a full-sha fetch retrieved it — but no advertised ref pointed at it — 0 of the 2,579 the remote advertised at the time — and `git fetch origin ` fails, so no ordinary fetch brought it into any other clone. So the commit could be confirmed and the gate could not, because there was no gate; a rule written about unresolvable heads would have mis-stated this incident. The title's *shape* did as much damage as its content — binding the sha to the UX pass and leaving the code pass bare is what let a later reader collapse it into "CODE PASS @ `1a811d84`", a head that was real and resolvable and so looked verifiable.)* +43. **A clearance has to exist as a PASS recorded against the head being pressed, and prose is not a record.** The question is existence, not identity: not whether the gated content is what merged (that is rule 32), but whether *any* clearance was ever taken at the head the press will read. Use GitHub's own record rather than anyone's prose — every review in `GET /pulls//reviews` carries `commit_id`, the head it was submitted against, so selecting reviews whose `commit_id` is the pressed head is how you find which gates this head actually has, without trusting a body. **Existence is necessary and not sufficient, because a review at the head can be a refusal.** `state` carries no verdict here: measured across #1988 (4), #1989 (10) and #2000 (4), all 18 reviews are `COMMENTED` — not one `APPROVED` or `CHANGES_REQUESTED` — so the verdict is the body's first line and nothing else. The check is therefore **per required gate: a review at the pressed head whose first line declares that gate's PASS.** #2000 @ `d1d56e4c` is the counterexample a bare existence test clears: its only review is a `DOCS-GATE: CHANGES` at that head. A head whose reviews are all refusals, or all corrections — "Correction to my gate above" declares no verdict — is ungated, which is the honest answer rather than a pass by default. `submitted_at` orders reviews but does not bind them to a head, and it cannot be used to select one either: every seat here posts under one GitHub identity, so `.[-1]` returns whichever seat reviewed last. Two checks that look right and are not. `git merge-base --is-ancestor ` passes a clearance a later head move has already spent — `b8048c72` is an ancestor of `177ba436` — which is 32's class of defect, not this one. And a sha missing from your clone says nothing about the remote: a commit can be there with no ref pointing at it, so the remote has it, no ordinary fetch brings it in, and `refs/pull//head` keeps a squashed-away head fetchable — an absence read in one clone is as clone-local as a presence read. `commit_id` cannot tell a carry from a re-derivation, so the body still has to be read for that; it answers only whether a clearance exists at all. Its own entry rather than a rider on 32, and the argument is 41's test applied to 32: every guard 32 sends you to check passes here — nothing had merged, no head had moved, the required set was green — and the defect survives all of them, because 32 presupposes a clearance and this asks whether one exists. *(Earned: TASK-186's #1988. The row recorded "CODE PASS @ `58298156`" from 06:54Z on 2026-09-28 and carried it for **29.4h**; the board title carried "… (UX PASS @ `1a811d84` + CODE PASS)" for **8.7h** from 03:34Z the next morning. No clearance was ever taken at that commit: it is a **sibling** on `7f171637` rather than an ancestor of `1a811d84`, and `GET /pulls/1988/reviews` held four reviews, every one of them `commit_id=1a811d84`, of which only the first existed before 12:17Z the next day. The commit itself was confirmable — `gh api commits/` resolved it and a full-sha fetch retrieved it — but no advertised ref pointed at it — 0 of the 2,579 the remote advertised at the time — and `git fetch origin ` fails, so no ordinary fetch brought it into any other clone. So the commit could be confirmed and the gate could not, because there was no gate; a rule written about unresolvable heads would have mis-stated this incident. The title's *shape* did as much damage as its content — binding the sha to the UX pass and leaving the code pass bare is what let a later reader collapse it into "CODE PASS @ `1a811d84`", a head that was real and resolvable and so looked verifiable.)* From 7174fa3d60f90eb61d830fdf4b431a00bc65733d Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Tue, 29 Sep 2026 06:29:23 -0700 Subject: [PATCH 7/9] =?UTF-8?q?docs(checklist):=20rule=2043's=20review=20c?= =?UTF-8?q?ounts=20are=20dated,=20not=20live=20=E2=80=94=20a=20count=20in?= =?UTF-8?q?=20a=20doc=20decays?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/development/review-checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/review-checklist.md b/docs/development/review-checklist.md index 5bb1b636e..e0a07de34 100644 --- a/docs/development/review-checklist.md +++ b/docs/development/review-checklist.md @@ -150,4 +150,4 @@ And then note where the fix landed. Someone hit the audience gap, felt it, and b ## What a clearance can bind -43. **A clearance has to exist as a PASS recorded against the head being pressed, and prose is not a record.** The question is existence, not identity: not whether the gated content is what merged (that is rule 32), but whether *any* clearance was ever taken at the head the press will read. Use GitHub's own record rather than anyone's prose — every review in `GET /pulls//reviews` carries `commit_id`, the head it was submitted against, so selecting reviews whose `commit_id` is the pressed head is how you find which gates this head actually has, without trusting a body. **Existence is necessary and not sufficient, because a review at the head can be a refusal.** `state` carries no verdict here: measured across #1988 (4), #1989 (10) and #2000 (4), all 18 reviews are `COMMENTED` — not one `APPROVED` or `CHANGES_REQUESTED` — so the verdict is the body's first line and nothing else. The check is therefore **per required gate: a review at the pressed head whose first line declares that gate's PASS.** #2000 @ `d1d56e4c` is the counterexample a bare existence test clears: its only review is a `DOCS-GATE: CHANGES` at that head. A head whose reviews are all refusals, or all corrections — "Correction to my gate above" declares no verdict — is ungated, which is the honest answer rather than a pass by default. `submitted_at` orders reviews but does not bind them to a head, and it cannot be used to select one either: every seat here posts under one GitHub identity, so `.[-1]` returns whichever seat reviewed last. Two checks that look right and are not. `git merge-base --is-ancestor ` passes a clearance a later head move has already spent — `b8048c72` is an ancestor of `177ba436` — which is 32's class of defect, not this one. And a sha missing from your clone says nothing about the remote: a commit can be there with no ref pointing at it, so the remote has it, no ordinary fetch brings it in, and `refs/pull//head` keeps a squashed-away head fetchable — an absence read in one clone is as clone-local as a presence read. `commit_id` cannot tell a carry from a re-derivation, so the body still has to be read for that; it answers only whether a clearance exists at all. Its own entry rather than a rider on 32, and the argument is 41's test applied to 32: every guard 32 sends you to check passes here — nothing had merged, no head had moved, the required set was green — and the defect survives all of them, because 32 presupposes a clearance and this asks whether one exists. *(Earned: TASK-186's #1988. The row recorded "CODE PASS @ `58298156`" from 06:54Z on 2026-09-28 and carried it for **29.4h**; the board title carried "… (UX PASS @ `1a811d84` + CODE PASS)" for **8.7h** from 03:34Z the next morning. No clearance was ever taken at that commit: it is a **sibling** on `7f171637` rather than an ancestor of `1a811d84`, and `GET /pulls/1988/reviews` held four reviews, every one of them `commit_id=1a811d84`, of which only the first existed before 12:17Z the next day. The commit itself was confirmable — `gh api commits/` resolved it and a full-sha fetch retrieved it — but no advertised ref pointed at it — 0 of the 2,579 the remote advertised at the time — and `git fetch origin ` fails, so no ordinary fetch brought it into any other clone. So the commit could be confirmed and the gate could not, because there was no gate; a rule written about unresolvable heads would have mis-stated this incident. The title's *shape* did as much damage as its content — binding the sha to the UX pass and leaving the code pass bare is what let a later reader collapse it into "CODE PASS @ `1a811d84`", a head that was real and resolvable and so looked verifiable.)* +43. **A clearance has to exist as a PASS recorded against the head being pressed, and prose is not a record.** The question is existence, not identity: not whether the gated content is what merged (that is rule 32), but whether *any* clearance was ever taken at the head the press will read. Use GitHub's own record rather than anyone's prose — every review in `GET /pulls//reviews` carries `commit_id`, the head it was submitted against, so selecting reviews whose `commit_id` is the pressed head is how you find which gates this head actually has, without trusting a body. **Existence is necessary and not sufficient, because a review at the head can be a refusal.** `state` carries no verdict here: measured across #1988, #1989 and #2000, every review on all three is `COMMENTED` — **18 of 18 when this was written, and that number only grows as seats post more, so re-run the count rather than quoting it** — not one `APPROVED` or `CHANGES_REQUESTED` across any of them, so the verdict is the body's first line and nothing else. The check is therefore **per required gate: a review at the pressed head whose first line declares that gate's PASS.** #2000 @ `d1d56e4c` is the counterexample a bare existence test clears: its only review is a `DOCS-GATE: CHANGES` at that head. A head whose reviews are all refusals, or all corrections — "Correction to my gate above" declares no verdict — is ungated, which is the honest answer rather than a pass by default. `submitted_at` orders reviews but does not bind them to a head, and it cannot be used to select one either: every seat here posts under one GitHub identity, so `.[-1]` returns whichever seat reviewed last. Two checks that look right and are not. `git merge-base --is-ancestor ` passes a clearance a later head move has already spent — `b8048c72` is an ancestor of `177ba436` — which is 32's class of defect, not this one. And a sha missing from your clone says nothing about the remote: a commit can be there with no ref pointing at it, so the remote has it, no ordinary fetch brings it in, and `refs/pull//head` keeps a squashed-away head fetchable — an absence read in one clone is as clone-local as a presence read. `commit_id` cannot tell a carry from a re-derivation, so the body still has to be read for that; it answers only whether a clearance exists at all. Its own entry rather than a rider on 32, and the argument is 41's test applied to 32: every guard 32 sends you to check passes here — nothing had merged, no head had moved, the required set was green — and the defect survives all of them, because 32 presupposes a clearance and this asks whether one exists. *(Earned: TASK-186's #1988. The row recorded "CODE PASS @ `58298156`" from 06:54Z on 2026-09-28 and carried it for **29.4h**; the board title carried "… (UX PASS @ `1a811d84` + CODE PASS)" for **8.7h** from 03:34Z the next morning. No clearance was ever taken at that commit: it is a **sibling** on `7f171637` rather than an ancestor of `1a811d84`, and `GET /pulls/1988/reviews` held four reviews at that point — every one of them `commit_id=1a811d84` — of which only the first existed before 12:17Z the next day. The commit itself was confirmable — `gh api commits/` resolved it and a full-sha fetch retrieved it — but no advertised ref pointed at it — 0 of the 2,579 the remote advertised at the time — and `git fetch origin ` fails, so no ordinary fetch brought it into any other clone. So the commit could be confirmed and the gate could not, because there was no gate; a rule written about unresolvable heads would have mis-stated this incident. The title's *shape* did as much damage as its content — binding the sha to the UX pass and leaving the code pass bare is what let a later reader collapse it into "CODE PASS @ `1a811d84`", a head that was real and resolvable and so looked verifiable.)* From ed23ee35e868a7bf1cc874c047d9d237a53e6378 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Tue, 29 Sep 2026 06:33:48 -0700 Subject: [PATCH 8/9] docs(checklist): rule 43's per-gate check must name the head, not just carry its commit_id --- docs/development/review-checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/review-checklist.md b/docs/development/review-checklist.md index e0a07de34..eedbed4c2 100644 --- a/docs/development/review-checklist.md +++ b/docs/development/review-checklist.md @@ -150,4 +150,4 @@ And then note where the fix landed. Someone hit the audience gap, felt it, and b ## What a clearance can bind -43. **A clearance has to exist as a PASS recorded against the head being pressed, and prose is not a record.** The question is existence, not identity: not whether the gated content is what merged (that is rule 32), but whether *any* clearance was ever taken at the head the press will read. Use GitHub's own record rather than anyone's prose — every review in `GET /pulls//reviews` carries `commit_id`, the head it was submitted against, so selecting reviews whose `commit_id` is the pressed head is how you find which gates this head actually has, without trusting a body. **Existence is necessary and not sufficient, because a review at the head can be a refusal.** `state` carries no verdict here: measured across #1988, #1989 and #2000, every review on all three is `COMMENTED` — **18 of 18 when this was written, and that number only grows as seats post more, so re-run the count rather than quoting it** — not one `APPROVED` or `CHANGES_REQUESTED` across any of them, so the verdict is the body's first line and nothing else. The check is therefore **per required gate: a review at the pressed head whose first line declares that gate's PASS.** #2000 @ `d1d56e4c` is the counterexample a bare existence test clears: its only review is a `DOCS-GATE: CHANGES` at that head. A head whose reviews are all refusals, or all corrections — "Correction to my gate above" declares no verdict — is ungated, which is the honest answer rather than a pass by default. `submitted_at` orders reviews but does not bind them to a head, and it cannot be used to select one either: every seat here posts under one GitHub identity, so `.[-1]` returns whichever seat reviewed last. Two checks that look right and are not. `git merge-base --is-ancestor ` passes a clearance a later head move has already spent — `b8048c72` is an ancestor of `177ba436` — which is 32's class of defect, not this one. And a sha missing from your clone says nothing about the remote: a commit can be there with no ref pointing at it, so the remote has it, no ordinary fetch brings it in, and `refs/pull//head` keeps a squashed-away head fetchable — an absence read in one clone is as clone-local as a presence read. `commit_id` cannot tell a carry from a re-derivation, so the body still has to be read for that; it answers only whether a clearance exists at all. Its own entry rather than a rider on 32, and the argument is 41's test applied to 32: every guard 32 sends you to check passes here — nothing had merged, no head had moved, the required set was green — and the defect survives all of them, because 32 presupposes a clearance and this asks whether one exists. *(Earned: TASK-186's #1988. The row recorded "CODE PASS @ `58298156`" from 06:54Z on 2026-09-28 and carried it for **29.4h**; the board title carried "… (UX PASS @ `1a811d84` + CODE PASS)" for **8.7h** from 03:34Z the next morning. No clearance was ever taken at that commit: it is a **sibling** on `7f171637` rather than an ancestor of `1a811d84`, and `GET /pulls/1988/reviews` held four reviews at that point — every one of them `commit_id=1a811d84` — of which only the first existed before 12:17Z the next day. The commit itself was confirmable — `gh api commits/` resolved it and a full-sha fetch retrieved it — but no advertised ref pointed at it — 0 of the 2,579 the remote advertised at the time — and `git fetch origin ` fails, so no ordinary fetch brought it into any other clone. So the commit could be confirmed and the gate could not, because there was no gate; a rule written about unresolvable heads would have mis-stated this incident. The title's *shape* did as much damage as its content — binding the sha to the UX pass and leaving the code pass bare is what let a later reader collapse it into "CODE PASS @ `1a811d84`", a head that was real and resolvable and so looked verifiable.)* +43. **A clearance has to exist as a PASS recorded against the head being pressed, and prose is not a record.** The question is existence, not identity: not whether the gated content is what merged (that is rule 32), but whether *any* clearance was ever taken at the head the press will read. Use GitHub's own record rather than anyone's prose — every review in `GET /pulls//reviews` carries `commit_id`, the head it was submitted against, so selecting reviews whose `commit_id` is the pressed head is how you find which gates this head actually has, without trusting a body. **Existence is necessary and not sufficient, because a review at the head can be a refusal.** `state` carries no verdict here: measured across #1988, #1989 and #2000, every review on all three is `COMMENTED` — **18 of 18 when this was written, and that number only grows as seats post more, so re-run the count rather than quoting it** — not one `APPROVED` or `CHANGES_REQUESTED` across any of them, so the verdict is the body's first line and nothing else. The check is therefore **per required gate: a review whose `commit_id` is the pressed head and whose first line names that same head and declares that gate's PASS.** The head name is not decoration. `commit_id` records the head **at submission**, so a gate taken at X and posted after a push to Y lands at Y and reads fresh at a head nobody read — and a check that stops at `commit_id` will accept it. A first line naming an *older* head is a rule 32 carry question, not an existence pass: the two heads may share a tree, in which case the artifact really was gated (32's test) and no existence check can know it. 43 answers whether a record claims *this* head; 32 answers whether an older claim still carries to it. Two counterexamples, one per half. #2000 @ `d1d56e4c` is what a bare existence test clears: its only review is a `DOCS-GATE: CHANGES` at that head. #1981 is what a `commit_id`-only test clears: pressed at `3d6e1763`, where its code review carries that `commit_id` and reads `DELTA RE-GATE: PASS @ a4566e29`. A head whose reviews are all refusals, or all corrections — "Correction to my gate above" declares no verdict — is ungated, which is the honest answer rather than a pass by default. `submitted_at` orders reviews but does not bind them to a head, and it cannot be used to select one either: every seat here posts under one GitHub identity, so `.[-1]` returns whichever seat reviewed last. Two checks that look right and are not. `git merge-base --is-ancestor ` passes a clearance a later head move has already spent — `b8048c72` is an ancestor of `177ba436` — which is 32's class of defect, not this one. And a sha missing from your clone says nothing about the remote: a commit can be there with no ref pointing at it, so the remote has it, no ordinary fetch brings it in, and `refs/pull//head` keeps a squashed-away head fetchable — an absence read in one clone is as clone-local as a presence read. `commit_id` cannot tell a carry from a re-derivation, so the body still has to be read for that; it answers only whether a clearance exists at all. Its own entry rather than a rider on 32, and the argument is 41's test applied to 32: every guard 32 sends you to check passes here — nothing had merged, no head had moved, the required set was green — and the defect survives all of them, because 32 presupposes a clearance and this asks whether one exists. *(Earned: TASK-186's #1988. The row recorded "CODE PASS @ `58298156`" from 06:54Z on 2026-09-28 and carried it for **29.4h**; the board title carried "… (UX PASS @ `1a811d84` + CODE PASS)" for **8.7h** from 03:34Z the next morning. No clearance was ever taken at that commit: it is a **sibling** on `7f171637` rather than an ancestor of `1a811d84`, and `GET /pulls/1988/reviews` held four reviews at that point — every one of them `commit_id=1a811d84` — of which only the first existed before 12:17Z the next day. The commit itself was confirmable — `gh api commits/` resolved it and a full-sha fetch retrieved it — but no advertised ref pointed at it — 0 of the 2,579 the remote advertised at the time — and `git fetch origin ` fails, so no ordinary fetch brought it into any other clone. So the commit could be confirmed and the gate could not, because there was no gate; a rule written about unresolvable heads would have mis-stated this incident. The title's *shape* did as much damage as its content — binding the sha to the UX pass and leaving the code pass bare is what let a later reader collapse it into "CODE PASS @ `1a811d84`", a head that was real and resolvable and so looked verifiable. And the `commit_id` half has its own incident: #1981 was pressed at `3d6e1763`, and the code review bearing that `commit_id` reads `DELTA RE-GATE: PASS @ a4566e29` — the stack had been re-authored from `a4566e29` to `3d6e1763` between the gate and its posting, and the two commits share tree `0e3b2d01cf`, so the artifact was gated and the record could not say so.)* From 3f11d65967576d731e9859152ab89ed5a1151d78 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Tue, 29 Sep 2026 06:39:42 -0700 Subject: [PATCH 9/9] =?UTF-8?q?docs(checklist):=20fold=20rule=2043's=20re-?= =?UTF-8?q?gate=20=E2=80=94=20candidates=20not=20clearances,=20and=20the?= =?UTF-8?q?=20differing-tree=20witness?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/development/review-checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/review-checklist.md b/docs/development/review-checklist.md index eedbed4c2..1a63221af 100644 --- a/docs/development/review-checklist.md +++ b/docs/development/review-checklist.md @@ -150,4 +150,4 @@ And then note where the fix landed. Someone hit the audience gap, felt it, and b ## What a clearance can bind -43. **A clearance has to exist as a PASS recorded against the head being pressed, and prose is not a record.** The question is existence, not identity: not whether the gated content is what merged (that is rule 32), but whether *any* clearance was ever taken at the head the press will read. Use GitHub's own record rather than anyone's prose — every review in `GET /pulls//reviews` carries `commit_id`, the head it was submitted against, so selecting reviews whose `commit_id` is the pressed head is how you find which gates this head actually has, without trusting a body. **Existence is necessary and not sufficient, because a review at the head can be a refusal.** `state` carries no verdict here: measured across #1988, #1989 and #2000, every review on all three is `COMMENTED` — **18 of 18 when this was written, and that number only grows as seats post more, so re-run the count rather than quoting it** — not one `APPROVED` or `CHANGES_REQUESTED` across any of them, so the verdict is the body's first line and nothing else. The check is therefore **per required gate: a review whose `commit_id` is the pressed head and whose first line names that same head and declares that gate's PASS.** The head name is not decoration. `commit_id` records the head **at submission**, so a gate taken at X and posted after a push to Y lands at Y and reads fresh at a head nobody read — and a check that stops at `commit_id` will accept it. A first line naming an *older* head is a rule 32 carry question, not an existence pass: the two heads may share a tree, in which case the artifact really was gated (32's test) and no existence check can know it. 43 answers whether a record claims *this* head; 32 answers whether an older claim still carries to it. Two counterexamples, one per half. #2000 @ `d1d56e4c` is what a bare existence test clears: its only review is a `DOCS-GATE: CHANGES` at that head. #1981 is what a `commit_id`-only test clears: pressed at `3d6e1763`, where its code review carries that `commit_id` and reads `DELTA RE-GATE: PASS @ a4566e29`. A head whose reviews are all refusals, or all corrections — "Correction to my gate above" declares no verdict — is ungated, which is the honest answer rather than a pass by default. `submitted_at` orders reviews but does not bind them to a head, and it cannot be used to select one either: every seat here posts under one GitHub identity, so `.[-1]` returns whichever seat reviewed last. Two checks that look right and are not. `git merge-base --is-ancestor ` passes a clearance a later head move has already spent — `b8048c72` is an ancestor of `177ba436` — which is 32's class of defect, not this one. And a sha missing from your clone says nothing about the remote: a commit can be there with no ref pointing at it, so the remote has it, no ordinary fetch brings it in, and `refs/pull//head` keeps a squashed-away head fetchable — an absence read in one clone is as clone-local as a presence read. `commit_id` cannot tell a carry from a re-derivation, so the body still has to be read for that; it answers only whether a clearance exists at all. Its own entry rather than a rider on 32, and the argument is 41's test applied to 32: every guard 32 sends you to check passes here — nothing had merged, no head had moved, the required set was green — and the defect survives all of them, because 32 presupposes a clearance and this asks whether one exists. *(Earned: TASK-186's #1988. The row recorded "CODE PASS @ `58298156`" from 06:54Z on 2026-09-28 and carried it for **29.4h**; the board title carried "… (UX PASS @ `1a811d84` + CODE PASS)" for **8.7h** from 03:34Z the next morning. No clearance was ever taken at that commit: it is a **sibling** on `7f171637` rather than an ancestor of `1a811d84`, and `GET /pulls/1988/reviews` held four reviews at that point — every one of them `commit_id=1a811d84` — of which only the first existed before 12:17Z the next day. The commit itself was confirmable — `gh api commits/` resolved it and a full-sha fetch retrieved it — but no advertised ref pointed at it — 0 of the 2,579 the remote advertised at the time — and `git fetch origin ` fails, so no ordinary fetch brought it into any other clone. So the commit could be confirmed and the gate could not, because there was no gate; a rule written about unresolvable heads would have mis-stated this incident. The title's *shape* did as much damage as its content — binding the sha to the UX pass and leaving the code pass bare is what let a later reader collapse it into "CODE PASS @ `1a811d84`", a head that was real and resolvable and so looked verifiable. And the `commit_id` half has its own incident: #1981 was pressed at `3d6e1763`, and the code review bearing that `commit_id` reads `DELTA RE-GATE: PASS @ a4566e29` — the stack had been re-authored from `a4566e29` to `3d6e1763` between the gate and its posting, and the two commits share tree `0e3b2d01cf`, so the artifact was gated and the record could not say so.)* +43. **A clearance has to exist as a PASS recorded against the head being pressed, and prose is not a record.** The question is existence, not identity: not whether the gated content is what merged (that is rule 32), but whether *any* clearance was ever taken at the head the press will read. Use GitHub's own record rather than anyone's prose — every review in `GET /pulls//reviews` carries `commit_id`, the head it was submitted against, so selecting reviews whose `commit_id` is the pressed head finds the reviews submitted against it: candidates, not clearances. **Existence is necessary and not sufficient, because a review at the head can be a refusal.** `state` carries no verdict here: measured across #1988, #1989 and #2000, every review on all three is `COMMENTED` — **18 of 18 when this was written, and that number only grows as seats post more, so re-run the count rather than quoting it** — not one `APPROVED` or `CHANGES_REQUESTED` across any of them, so the verdict is the body's first line and nothing else. The check is therefore **per required gate: a review whose `commit_id` is the pressed head and whose first line names that same head and declares that gate's PASS.** The head name is not decoration. `commit_id` records the head **at submission**, so a gate taken at X and posted after a push to Y lands at Y and reads fresh at a head nobody read — and a check that stops at `commit_id` will accept it. A first line naming an *older* head is a rule 32 carry question, not an existence pass: the two heads may share a tree, in which case the artifact really was gated (32's test) and no existence check can know it; or they may **differ**, in which case the clearance names content nobody gated. 43 answers whether a record claims *this* head; 32 answers whether an older claim still carries to it. Two counterexamples, one per half. #2000 @ `d1d56e4c` is what a bare existence test clears: its only review is a `DOCS-GATE: CHANGES` at that head. #1981 is what a `commit_id`-only test clears: pressed at `3d6e1763`, where its code review carries that `commit_id` and reads `DELTA RE-GATE: PASS @ a4566e29`. A head whose reviews are all refusals, or all corrections — "Correction to my gate above" declares no verdict — is ungated, which is the honest answer rather than a pass by default. `submitted_at` orders reviews but does not bind them to a head, and it cannot be used to select one either: every seat here posts under one GitHub identity, so `.[-1]` returns whichever seat reviewed last. Two checks that look right and are not. `git merge-base --is-ancestor ` passes a clearance a later head move has already spent — `b8048c72` is an ancestor of `177ba436` — which is 32's class of defect, not this one. And a sha missing from your clone says nothing about the remote: a commit can be there with no ref pointing at it, so the remote has it, no ordinary fetch brings it in, and `refs/pull//head` keeps a squashed-away head fetchable — an absence read in one clone is as clone-local as a presence read. `commit_id` cannot tell a carry from a re-derivation, so the body still has to be read for that; it answers only whether a review was submitted against that head at all. Its own entry rather than a rider on 32, and the argument is 41's test applied to 32: every guard 32 sends you to check passes here — nothing had merged, no head had moved, the required set was green — and the defect survives all of them, because 32 presupposes a clearance and this asks whether one exists. *(Earned: TASK-186's #1988. The row recorded "CODE PASS @ `58298156`" from 06:54Z on 2026-09-28 and carried it for **29.4h**; the board title carried "… (UX PASS @ `1a811d84` + CODE PASS)" for **8.7h** from 03:34Z the next morning. No clearance was ever taken at that commit: it is a **child** of `7f171637` — a sibling of `1a811d84`, not an ancestor of it, and `GET /pulls/1988/reviews` held four reviews at that point — every one of them `commit_id=1a811d84` — of which only the first existed before 12:17Z on 2026-09-29. The commit itself was confirmable — `gh api commits/` resolved it and a full-sha fetch retrieved it — but no advertised ref pointed at it — `git ls-remote` listed 2,579 of them when this was measured and not one was this sha, a number that only grows, so re-run it rather than quoting it — and `git fetch origin ` fails, so no ordinary fetch brought it into any other clone. So the commit could be confirmed and the gate could not, because there was no gate; a rule written about unresolvable heads would have mis-stated this incident. The title's *shape* did as much damage as its content — binding the sha to the UX pass and leaving the code pass bare is what let a later reader collapse it into "CODE PASS @ `1a811d84`", a head that was real and resolvable and so looked verifiable. And the `commit_id` half has its own incident: #1981 was pressed at `3d6e1763`, and the code review bearing that `commit_id` reads `DELTA RE-GATE: PASS @ a4566e29` — the stack had been re-authored from `a4566e29` to `3d6e1763` between the gate and its posting, and the two commits share tree `0e3b2d01cf`, so the artifact was gated and the record could not say so. Same PR, and the hazard's harsher half: the code review submitted at 21:26:47Z carries `commit_id=245dbaf4` while its first line names `5e0e7193`, and those trees **differ** — three files, three lines, the "pod, not room" string among them — so it attached a clearance to content nobody had gated; superseded seven minutes later and never pressed, which is why the incident above is the one that reached a press, and why a check that stops at `commit_id` cannot be trusted at all.)*