Repository navigation
feat(scripts): add pr_watch.py PR waiter with optional review-bot gate (12.1.0) - #110
Merged
Merged
Conversation
…e (12.1.0) `watch` polls PRs and prints one line per state change (state, decision, unresolved threads, non-passing checks, optional pr-hygiene block and gate line); `gate` is a push check for a bot that edits one status comment in place, optionally cross-checked against a JSON feed of its running reviews. Ported from a user-level pr-fleet-loop script pair; documented in git-and-github's "Wait for bots" rule. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… tests - Fetch failures go to stderr once per PR per distinct error; a malformed response is a failed reading in watch and exit 2 in gate. - Feed: HTTP protocol errors, malformed entries and naive timestamps are handled; --gate-feed-url/--gate-busy move to gate, the only consumer. - Regex options are validated by argparse. - The PR body comes from the same GraphQL query; an empty description is a PR without a Hygiene block. - Tests clear REPO/GATE_* and forbid network fetches. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… match Both tests fail on 2592b1d and pass once fixed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…p on persistent failure - Match the feed repo and gate-bot login case-insensitively, as GitHub does; a differently cased --repo or --gate-bot could read a running review as idle. - Split gh --jq comment rows on "\n" only: a raw U+0085 inside a body is valid JSON and splitlines() broke every gate read on that PR. - watch: re-report a fetch failure after each recovery, and --oneshot exits 2 after 5 passes in which every fetch failed instead of waiting forever. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Case-sensitive gate-marker matching can falsely report success for a busy gate, while missing pagination can hide unresolved review threads beyond the first 100.
2 open issues
What changed in this PR
Adds a reusable PR watcher and optional review-bot push gate to Claudius, replacing ad hoc polling scripts with a repository-independent helper.
Changes:
- Adds
pr_watch.pywith change monitoring, configurable bot detection, and gate exit codes. - Documents background waiting and pre-push gate usage.
- Adds fixture-based tests and bumps the plugin version to 12.1.0.
| File | Description |
|---|---|
scripts/pr_watch.py |
Implements PR monitoring and the optional review-bot gate. |
tests/test_pr_watch.py |
Tests parsing, polling, failures, and CLI behavior. |
tests/fixtures/pr-watch/graphql-1167.json |
Supplies PR state and review-thread data. |
tests/fixtures/pr-watch/feed.json |
Supplies active and queued review-feed examples. |
tests/fixtures/pr-watch/comments.jsonl |
Supplies bot status and unrelated comment examples. |
tests/fixtures/pr-watch/body-hygiene.md |
Supplies a PR hygiene block for parser tests. |
skills/git-and-github/SKILL.md |
Links pre-push guidance to the new helper. |
skills/git-and-github/references/gh-cli.md |
Documents commands, options, and exit-code caveats. |
.claude-plugin/plugin.json |
Bumps the plugin version to 12.1.0. |
Review effort: Balanced
…eview threads - watch: every --probe-interval (default 30 s) send conditional REST requests for the PR, its head's check runs and statuses, and the first comments page with a gate bot. A 304 costs no rate limit; any change triggers a full reading at once. Full readings still run every --interval (default 120 s). Both intervals also take PR_WATCH_INTERVAL / PR_WATCH_PROBE_INTERVAL. An endpoint that fails is skipped until the PR's next good full reading. - Follow reviewThreads pagination, so threads past the first 100 count. - The default gate marker <bot>-gate matches in any case, like the login; an explicit --gate-marker still matches exactly. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…be churn Both marked xfail(strict) until fixed: full readings drift past --interval when the probe interval does not divide it, and the pulls ETag changes on any push to the repository (embedded base.repo.pushed_at). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ever drift past --interval
- pulls/{n} embeds the repository's pushed_at, so a push to any branch changed
its ETag and turned every probe into a counted 200 plus a full reading on a
busy repository. Probe issues/{n} instead and take the head for the
check-run and status probes from the last full reading.
- Count probes per full reading with floor division, so full readings are at
most --interval apart for any probe interval.
- Reject --interval 0, which made the watcher read in a tight loop.
- gh-cli.md: --oneshot gives up after 5 failed full readings in a row.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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.


TL;DR: Adds a ready-made way to wait for pull requests to change and to check, before pushing, whether a review bot is still working on a pull request.
User story
As a developer driving several pull requests with an AI agent, I can have the agent wait in the background until something on a pull request changes (a new review comment, a failed check, a finished bot review) and check that a review bot is not in the middle of a review before it pushes, to avoid wasted reviews and constant manual polling.
Scenario
Base flow
Actual behavior
The plugin only offers one-off GitHub lookups. Waiting for changes and detecting a running bot review relied on scripts kept outside the plugin, tied to one bot and one repository.
Expected behavior
The plugin ships a waiter that works in any repository. It prints a line when a watched pull request changes and can be told which bot to treat as a reviewer. Before a push, it answers "reviewing" / "not reviewing" / "could not tell" through its exit code.
Detailed discussion
What was done
scripts/pr_watch.py(Python, stdlib only), two subcommands:watch <pr>...— takes a full reading every--interval(default 120 s, envPR_WATCH_INTERVAL) and prints one line per PR whose reading changed: state, review decision, draft flag, unresolved review threads (GraphQL with pagination, body in the same query), and non-passing checks (gh pr checks --json name,bucket, judged by output since gh exits non-zero for failing/pending checks). Options:--checksregex,--ignore-pending,--quiet-init,--oneshot. A failed fetch, or apr-hygieneblock that describes an older head, skips the PR for that pass. The failure is reported on stderr once per outage;--oneshotexits 2 after 5 passes in which every fetch failed.--probe-interval(default 30 s, envPR_WATCH_PROBE_INTERVAL, 0 disables) it sends conditional REST requests (If-None-Match) for the PR's issue record (notpulls/{n}, whose ETag changes on any push to the repository), the last-read head's check runs and commit statuses, and with a gate bot the first page of comments. A 304 costs no rate limit; any change triggers a full reading at once. The notifications API would be cheaper still, but fine-grained tokens cannot use it. An endpoint that fails (for example no permission) is skipped until the PR's next good full reading. Changes the probes cannot see, such as a resolved review thread, show at the next full reading.gate <pr>— for a bot that edits one status comment in place. The comment is selected by marker (default<login>-gate) and newestupdated_at. An optional JSON feed (live.active/live.queued,data_as_of) can be cross-checked. A busy comment always holds. A feed ACTIVE entry holds unless the comment was edited later. Exit codes: 3 = reviewing, 0 = not reviewing, 2 = fetch failure or bad usage. Unexpected errors also map to 2, never to an implicit "go".--gate-bot/GATE_BOTmeans no gate, and no hygiene block in the body means no hygiene segment.REPO/GATE_BOT/GATE_MARKER/GATE_FEED_URLsupply defaults.git-and-github§ Before Every Push ("Wait for bots") points to the script.references/gh-cli.md§ PR waiter documents usage: background run with--quiet-init --oneshot, relaunch after each event, and the exit-code caveats.Testing
tests/test_pr_watch.py: 60 tests on recorded, trimmed real responses intests/fixtures/pr-watch/(PR body with hygiene block, GraphQL PR node, gate comments, review-system feed). Covered: multi-line and CRLF gate comments, emoji-prefixed status lines, case-insensitive repo, bot names and default gate marker, review threads past the first page, conditional probes (baseline, 304, change, failing endpoint backoff) and their scheduling against full readings, a U+0085 inside a comment body, stale feed ACTIVE vs a newer gate edit, a stale hygiene head, failed/malformed fetches, failing checks with non-zero exit, "no checks reported", quiet-init/oneshot (including giving up on persistent failure), exit codes, regex validation, and isolation from exported env vars and the network.python3 -m pytest -q testspasses. Shell tests pass, excepttests/test_cargo_cached.sh. That one fails on this host becausecargo metadatatimes out, and it touches no file in this PR.Breaking changes
None.
Checklist
Prior work
Ported from a user-level script pair (
pr-watch.sh,bot-gate.sh), generalized to be repository- and bot-agnostic.Attribution
🤖 Co-authored by Claudius the Magnificent AI Agent
🤖 Generated with Claude Code