Queue the gates that would have caught this session's repeat mistakes - #522
Merged
Conversation
Four items, each written from a failure that actually happened rather than from a hypothetical. The first applies to the gate itself a rule this repository already states, that a check finding nothing is indistinguishable from a check with nothing to find. Four separate routes to the same false clean were each fixed with their own guard, which is the wrong shape, because the fifth will need a fifth guard and will be found the same way. The second closes a gap the format check cannot see, since a fabricated SHA is forty hex characters like any other. The third targets the most frequent review finding of the session, a pull request description contradicting its own branch. The fourth reopens a decision rather than reversing it, because the reason doc gates stay out of the pre-commit hook was sound when the only mode was a whole-tree sweep and the diff-scoped mode has moved the trade. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the repository’s running backlog to capture four concrete, recently observed failure modes as future gate/check candidates, without introducing any behavioral changes.
Changes:
- Adds four new backlog entries describing proposed gates/checks (prose-lint scope floor, SHA pin resolvability, PR description drift, and reconsidering doc gates in pre-commit).
- Extends the link reference section with new references used by the added entries.
ptr727
added a commit
that referenced
this pull request
Aug 3, 2026
…ckup-event tooling to main (#528) Promotes four commits to `main`. Two of them change **carried** files, so downstream repos read the stale text until this lands, which is what makes the promotion the delivery step rather than bookkeeping. ## What this delivers to the fleet **Carried rule text**, picked up by every repo on its next re-vendor: | PR | File and section | Change | | --- | --- | --- | | #526 | `AGENTS.md`, Context and Delegation Discipline (**verbatim**) | A wait separates three outcomes and says which one it reached: run the command in the foreground before backgrounding it, never let `\|\| echo '[]'`, `\|\| true` or `2>/dev/null` stand in for a failure, emit on failure, and bound the wait. The session rule also stops ending a session on a third review round, which read as license to leave a loop open while it was still producing defects | | #526 | `GOVERNANCE.md`, Verification Discipline (**verbatim**) | A launched process is not a result, and a cause nobody observed is not a diagnosis | | #526 | `GOVERNANCE.md`, PR Review Etiquette (**verbatim**) | Every finding ends in one of five actions rather than at a round count: fixed, disproven with proof the reviewer can read, deferred against a filed issue, declined with the maintainer's explicit answer, or fixed as a class where the code keeps earning it | | #520 | `CODESTYLE.md` and the prose gate | The comment rules the gate now reaches, carried to the fleet through a public composite action | | #526, #527 | `.github/copilot-instructions.md` | A quota or rate-limit answer is terminal rather than pending; a request pending with no pickup is a third state with a recovery recipe; three corrections below | **Runbook corrections**, each one a path an agent followed to a wrong answer this week: - `gh pr view --json reviewRequests` **omits a Bot reviewer entirely**, reporting an empty set while Copilot sits in it. This is how a live stall was misdiagnosed to the maintainer as no request having been made. - Removal was called impossible for want of a named mutation. `requestReviews` **replaces** the reviewer set when `union` is false, which is the clear half of the recovery, and it resolved a real thirteen-and-a-half-hour stall in 35 seconds. - The reviewer login has a **third** spelling. A timeline `review_requested` carries login `Copilot` with type `Bot`, against GraphQL's `copilot-pull-request-reviewer` and the `[bot]` suffix REST user objects add. A filter keyed to either documented form selects nothing there. **Hub-only tooling** (`scripts/`, not carried): `pr_review.py` gains exit `40` for a reviewer answer that carries no commit and exit `50` for a request nothing picked up, with the window and interval guards those needed. `prose_lint.py` and the gate queue changes from #520 and #522 ride along. ## Why the rules moved Three stalls in one day, each reported as waiting on the reviewer, none of them that. A CI watcher whose command did not exist on the installed `gh` and whose fallback turned every error into "nothing yet". A stall explained afterwards with a throttle that appears nowhere in the record. And a review request that was pending while nothing acted on it. The common shape is a wait that cannot tell "not yet" from "never", and a report of patience standing in for a reading nobody took. ## Verification `scripts/test_pr_review.py` 59 pass, `scripts/test_prose_lint.py` 153 pass, `scripts/test_repo_gate.py` 23 pass, `spec/audit.py --selftest` pass, `spec/validate.py` clean, `repo_gate.py` clean, both `prose_lint.py` invocations clean, `editorconfig-checker` clean. Both source pull requests were driven to a clean Copilot round: #526 over seven rounds and ten findings, #527 over four rounds and five findings, every one of the fifteen real and answered. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Four backlog entries, each written from a failure that happened rather than one imagined. Documentation only, no behavior change.
Why these four
A session that shipped four merged pull requests also produced a set of repeated mistakes, and the useful split is between the ones a gate already caught and the ones nothing was watching for. Comment wrapping was caught every time, by a gate, and still reached commits because the gate ran after them. Suppressed review findings went unanswered because the tool that surfaces them was scoped to the head. A fabricated SHA reached a file and was caught by hand. Three pull request descriptions contradicted their own branches and were caught by a reviewer.
The entries
A floor assertion in
prose_lint.py. This one applies to the gate a ruleGOVERNANCE.mdalready states: "a gate that finds nothing is indistinguishable from a gate with nothing to find, so assert a floor on what a healthy run covers." Four separate routes to the same false clean appeared in one session, an unresolvable diff base, a multi-linepathsinput, a cross-repository diff, and a path under no repository. Each was fixed with its own guard, which is the wrong shape: the fifth route will need a fifth guard and will be found the way the first four were, by a reviewer. The entry records the honest limit too, since a change touching only files the gate does not read legitimately scopes to zero.Resolvability in the
sha-pincheck. The check validates the shape of a pin, and forty hex characters is a shape any fabricated string satisfies. It would also catch a pin whose commit is reachable only from a branch that has since been squashed and deleted, which breaks a downstream gate long after the change that caused it. The entry notes whygh-write-guardcannot cover this: it watches Bash, and an editor tool writing the same string into a file never reaches it.A pull request description drift check. The most frequent review finding of the session, six findings across three descriptions. Scoped deliberately to SHAs and
uses:refs quoted in the body rather than to prose claims, because judging prose needs a similarity heuristic andspec/section-model.mdalready rejects that approach for the same reason it would fail here.Reopening the pre-commit doc-gate decision.
scripts/README.mdrecords that doc linters stay out of the hook so it stays fast, which was sound when the only mode was a whole-tree sweep. The diff-scoped mode reads one commit's lines in about a second, so the trade has moved. Framed as a decision to revisit rather than one to reverse, and it names the risk of the change too, since a hook running the gate from the wrong directory is its own false clean.Verification
Prose gate, markdownlint and editorconfig-checker all clean on the changed lines. One British spelling (
neighbouring) was caught by the gate and corrected.