Repository navigation
Releases
v0.5.0: feat: loop_status.py says where the loop is and the one next command
Why
Resuming a loop after a day, a compacted context or an interrupted session meant reading state.json, three provenance files, preferences.json and git by hand, then applying the resume ladder in resume-and-recovery.md as prose. That ladder was marked as needing to become deterministic. This script makes it code.
PR 3 of 3, stacked on #126 (phase recording), which is stacked on #125 (the state.json lock). This is the release: release:minor.
What
loop_status.py, stdlib only, local reads only, never callsgh. Prints a[loop] statusblock: reviewer, phase and age, session cycle, cap used over limit, the recorded request, a kept wait outcome, local HEAD against the upstream, profile state, warnings, thenNext:with exactly one command.--format jsonreturns the same decision as an object;--pr <url|number>overrides the PR;--cwdpicks the checkout.decide_nextis the resume ladder. Precedence: no persisted reviewer → select one; an open unconfirmed reservation →request_rereview.py(it settles first); then the phase. A cap raised in preferences.json lifts "capped" before any fetch (case 1); local commits ahead of@{u}mean push (case 2); a pushed head with no request, or arequested_headolder than HEAD, means request (case 3); a kept timed-out or refused wait means re-run it or record (quota: ask the user first).- The PR is picked from the checkout's active run, else its newest run block, else its last recorded run.
- Warnings: git facts skipped when the checkout is another repo, no upstream, incomplete provenance, count is a bound, loop-active marker missing while a run is active or stale, a stale summary the push gate will block on, a cap raised since the last fetch.
- Docs: SKILL.md's reference-table row and the "re-invocation at the cap" sentence now say to run it first (15762 of 15800 bytes, 146 of 150 lines, no budget change).
resume-and-recovery.mdcarries the usage block, the phase table, and the ladder with a "how it is detected" column. The resumed-session section says to run it before the--fullfetch.
Hooks are unchanged.
Tests
tests/test_loop_status.py: the full decide_next table (20 rows), precedence, PR selection, origin URL forms, git facts from a real checkout with a local upstream, read-only preferences access (the file is never created), and the CLI: text block shape and last two lines, JSON with no ANSI, --pr forms, no state, last_run, an open reservation, each warning, a cap raised in preferences, a kept refusal, and running the script by path with python -I.
Suite: 1723 passed. ruff check plugins/ tests/ clean with the CI version. Doc budgets pass.
🤖 Generated with Claude Code
Summary by Sourcery
Make review-loop recovery deterministic by adding a local status command that identifies the current phase and provides the single appropriate next action.
New Features:
- Add a local-only
loop_status.pycommand that reports review-loop state and recommends exactly one next command, with text and JSON output. - Implement deterministic resume decisions across reviewer selection, reservations, loop phases, cap changes, local Git state, and wait outcomes.
Bug Fixes:
- Make resumed and compacted sessions recoverable without manually reconstructing state from multiple local files or prose instructions.
- Ensure cap increases in preferences are recognized before fetching and distinguish pushed, unpushed, and stale review-request states.
Enhancements:
- Persist fetch results needed for local status decisions, including actionable-thread counts and clean-state blockers.
- Improve PR discovery, Git remote handling, provenance and loop-marker warnings, and checkout-specific command generation.
Documentation:
- Update the skill and resume documentation to direct users through
loop_status.pyand document its deterministic resume ladder.
Tests:
- Add comprehensive coverage for decision precedence, PR selection, Git facts, preferences access, warnings, output formats, CLI behavior, and standalone execution.
Chores:
- Record the new loop-status capability in the changelog.
v0.4.9: fix: serialize every state.json write under one lock and write it atomically
Why
state.json is rewritten whole by many writers that never locked each other, so a writer holding an older snapshot erased whatever was written meanwhile (PR #116 review). The cycle stamps and the request provenance moved to append-only logs for that reason. Everything that stays in the file was still exposed: the run block, the wait block, fixed markers, judge verdicts, the reviewer selection, the render baseline, the sticky comment id.
This is PR 1 of 3. PR 2 records the loop phase in the run block from two scripts, which is exactly the clobber case, so the lock lands first. PR 3 adds loop_status.py on top.
What
loop_state.pygains a file-widestate.lock, the lock primitive the re-review script used per PR (now shared asfile_lock), andmutate_sticky_state(fn): read, apply, write under the lock.- All 18 write sites in
fetch_gemini_threads.pygo through it. None holds the lock across a GitHub or git call: the sticky receipt collects its field updates and applies them at the end, and the churn tracker runs itsgit diffbefore taking the lock. save_sticky_statewrites a sibling file and renames it into place, so a reader never sees a torn file thatload_sticky_statewould read as an empty state and the next writer would save over every PR.- A busy lock (5 s) or an unavailable one warns once on stderr and writes anyway. That is the old behavior, so the lock can never wedge the loop.
request_rereview.pykeeps its per-PR lock and statuses; only the primitive moved.
No behavior change visible to the agent. No doc or budget change. Release: patch (the default, no label).
Tests
- A holder subprocess takes the lock, signals, sleeps, then writes its key while this process writes another. Without the lock the holder's save erases the second key; with it both survive.
- Busy lock past the wait, no lock module, and an unwritable lock directory each warn and still write.
- The save leaves no temporary file.
- The two existing
record_cycletests now patchloop_state, where the write path lives.
Suite: 1667 passed. ruff check plugins/ tests/ clean with the CI version.
🤖 Generated with Claude Code
Summary by Sourcery
Prevent concurrent state.json updates from losing persisted loop data by coordinating writers with a shared lock and atomic file replacement.
Bug Fixes:
- Serialize all state.json mutations through a shared file-wide lock to prevent concurrent writers from clobbering persisted loop state.
- Write state.json atomically so readers never observe partially written state, while preserving fail-open behavior when locking is unavailable.
Enhancements:
- Share the file-locking primitive between state persistence and per-PR re-review requests without holding locks across external GitHub or git operations.
- Harden state reads and mutation handling for malformed or unreadable state data.
Documentation:
- Document the serialized and atomic state.json persistence behavior in the changelog.
Tests:
- Add coverage for concurrent state writers, atomic replacement, lock timeouts and unavailable locks, temporary-file cleanup, and malformed state handling.
v0.4.8: feat: head checks as feedback, churn stop, Codex clean receipt
Summary
Two gaps from a survey of the review-loop tools shipping in 2026, plus one bug found by running the loop on this PR. The write-safety invariants are unchanged: the loop never resolves an unresolved thread, never submits a review, never merges.
- CI on the head is feedback. The GraphQL query asks
statusCheckRollupfor check names, conclusions,isRequired(pullRequestNumber:)and details URLs (verified by schema introspection and a live query against #122).ci_status()reduces that to a[loop] CI:block listing failing and still-running checks, with agh run view <id> --repo … --log-failedcommand per failing Actions check. The loop reports a red check and never fixes it; with nothing else left the run ends as the new outcomeci_failed. An incomplete rollup (non-success state with no failing check fetched, or a full page of 50 contexts) is named, not read as green. Every non-ready wait exit carries the head's checks, since a reviewer that runs only after CI never arrives on a red head. - Churn detection. Each fetch records the head it saw; the next diffs
prev..head(-U0) in any checkout of the PR's repo that has both commits and tags new RIGHT-side findings anchored inside those hunks as fix-induced (· on lines this loop changedin the receipt,fix_inducedin the run record,loopStatus.fixInducedin JSON). When every new finding on cycle 2+ is fix-induced the script prints[loop] churn:and the loop stops with the new outcomechurn, unless the user says to ignore churn. LEFT anchors are never compared; git-quoted paths are decoded. - Codex's clean receipt ends the wait. Codex answers a re-review that found nothing with a top-level comment (
<!-- codex-review-receipt:v1 -->), not a review. The second cycle of this PR timed out on exactly that. The vendor table now says Codex posts summaries and the receipt is read as its answer; the third cycle's wait ended on it within three minutes.
Dropped from an earlier revision as speculative: resume from state embedded in the receipt, and listing threads a person opened. Neither answered a reported problem, and both added weight to the fetch script (#101). The design note records why.
Docs: references/ci-checks.md, references/churn.md, stop conditions 6 and 7 in SKILL.md, notes in receipts-and-metrics.md, variations.md and reviewer-selection.md, README row, CHANGELOG, docs/superpowers/specs/2026-11-06-ci-checks-and-churn-design.md. SKILL.md budget 15300→15800 bytes in tests/budgets.json for the two stop conditions and two pointer rows.
Test plan
-
pytest: 1657 passed (33 new intests/test_ci_churn.py);ruffclean - Extended query validated read-only against #122 (6 green checks)
- Review loop run on this PR with Codex: 7 findings over two passes, all fixed; third pass clean; the Codex receipt fix confirmed live
- Run on a PR with a red check
🤖 Generated with Claude Code
Summary by Sourcery
Improve the review loop's feedback and stopping behavior by reporting head CI, detecting fix-induced churn, and recognizing Codex clean receipts.
New Features:
- Surface failing and pending head CI checks, including required status and GitHub Actions log commands, and stop with a dedicated
ci_failedoutcome when CI is the only remaining issue. - Detect reviewer findings caused by the loop's own changes and stop with a
churnoutcome when all new findings are fix-induced. - Treat Codex clean receipt comments as completed re-reviews and avoid redundant requests for heads they cover.
Bug Fixes:
- Prevent incomplete check rollups and unverified head arrival times from being interpreted as green or reviewed.
- Ensure CI status is preserved across non-ready wait exits and timeout results.
Enhancements:
- Add fix-induced findings, CI summaries, and the new terminal outcomes to receipts, JSON status, and run metrics.
- Document the new CI, churn, stopping, reviewer, and receipt behavior.
Documentation:
- Add guidance for head checks, churn handling, new stop conditions, Codex receipts, and related loop behavior.
Tests:
- Add comprehensive offline coverage for CI parsing and formatting, changed-line detection, churn classification, wait behavior, and Codex receipt handling.
v0.4.7: fix: no reviewer means no ping; read graded Claude summaries; wait on push-reviewing CI jobs; gate the repo the push runs in
Summary
Four bugs in the loop when the reviewer is a CI job that posts Claude's review as a PR comment (as github-actions[bot]) on every push.
request_rereview.main
+ no reviewer persisted or named → reviewer_not_configured (was: post `@codex review`)
head_already_reviewed (PR reviews)
+ summary_review_state (PR comments: the CI job never submits a review)
+ summary posted after head arrived → already_reviewed_head
+ ≥2 summaries nobody asked for → review_pending, reason: reviews_on_push
+ (logged once per head; counts toward the cap)
cap check (pings + push waits)
post trigger parse_summary_comment
### Grade: sections
+ "`path:line` — **Warning:** …" paragraphs / numbered items (either order)
blob-link numbered list
+ verdict count ("0 Critical, 1 Warning, 2 Suggestions") > findings read → incomplete, agent reads it fetch, nothing persisted
- "# Codex Threads … Author filter: chatgpt-codex-connector"
+ [loop] No reviewer is configured … Reviewers seen on this PR: Claude Code (as github-actions)
+ (select with --reviewer github-actions --reviewer-vendor claude --reviewer-source confirmed)
+ reviewerSelection.candidates loop_summary_gate
- repo = gh repo view (session cwd)
+ repo = gh repo view in git -C <dir> | last `cd <dir>` before the push | session cwdNew references/claude-reviewer.md holds the Claude detail; SKILL.md gains one pointer row and stays within budget (net −4 bytes).
Evidence
- Before: with no reviewer persisted,
request_rereview.py --repo … --pr N --dry-run→"phrase": "@codex review"on a PR that only Claude reviews.
After:"status": "reviewer_not_configured", nothing posted. - Before:
parse_summary_commentread 0 findings from every summary such a CI job posted; an approving summary read as clean while its verdict counted a Suggestion.
After: 15 of 17 real summaries parse to exactly their verdict count. The other two are the reviewer over-counting itself (an extra low item) and a grade written mid-sentence, which is marked incomplete for the agent to read. - Before:
head_already_reviewed(…, login="github-actions")→Noneon a head the push review had covered, so every cycle pinged@claude reviewand started a second Claude run.
After:summary_review_state→covers_head: True, reviews_on_push: True→already_reviewed_head. - Before: gate payload
cd <looped clone> && git pushfrom another repo's cwd → exit 0, cycles pushed without--cycle-summary.
After: exit 2 with the PR's--cycle-summarycommand (TestPushTarget). pytest: 1591 passed (33 new). Ten old request tests relied on the Codex fallback and now name Codex explicitly; one Claude acceptance test pinged a head its own summary already covered and now expectsalready_reviewed_head.
Merge Danger
Door: two-way
The only new persisted data is request-log records with via: "push"; older versions count request-log records only for Copilot, so they ignore these.
Blast Radius: moderate
- A caller that runs
request_rereview.pywith no persisted reviewer and no--reviewer-loginnow getsreviewer_not_configuredinstead of a Codex ping. - Claude CI repos that review every push see
review_pendingwaits instead of pings; a wait counts toward the cap like a ping. - The push gate can now block
cd <looped clone> && git pushandgit -Cpushes it used to let through.
🤖 Generated with Claude Code
Summary by Sourcery
Prevent unintended reviewer pings and duplicate Claude runs while improving summary parsing, push-review coordination, and push repository safety.
New Features:
- Add support for discovering and selecting Claude Code reviewers represented by CI-generated PR summaries.
- Recognize additional graded Claude summary formats and validate parsed findings against verdict totals.
Bug Fixes:
- Prevent re-review requests from pinging an unconfigured default reviewer.
- Avoid duplicate Claude reviews by recognizing summaries that already cover the current head and waiting for repositories that review every push.
- Ensure push-summary gating evaluates the repository and all pushes targeted by the actual shell command.
Enhancements:
- Count push-review waits as re-review cycles and document Claude-specific review behavior and statuses.
Documentation:
- Document Claude reviewer selection, summary formats, clean-gate behavior, and push-review re-review handling.
Tests:
- Expand coverage for Claude summary parsing, push-review deduplication and waits, reviewer configuration, and push target resolution.
Chores:
- Update anonymized validation examples and fixtures.
v0.4.6: feat: Claude Code as a first-class reviewer
Summary
Claude Code joins Codex, Gemini and Copilot as a built-in reviewer. One vendor covers the three ways Claude reviews a PR through the Claude GitHub App, and the loop now reads all three the way it reads Copilot's overview.
reviewer surface posts as review arrives as re-review
───────────────────────────────── ─────────────────── ─────────────────────────────── ───────────────
hosted Code Review claude[bot] review per head commit @claude review
+ 🔴/🟡/🟣 inline threads
+ <!-- bhrv:… --> body
claude-code-action /code-review claude[bot] body-less reviews per inline @claude (action
--comment comment, or one "No issues trigger phrase)
found" PR comment
CI job running the skill with github-actions[bot] one PR comment ending in @claude (the
GITHUB_TOKEN (a private repository) <!-- review:complete --> interactive job)
What the fetch does per cycle for a Claude reviewer:
fetch
filter_threads(author)
review_body_findings(author) # Codex badges in a review body
+ summary_comment_findings(author) # findings a summary comment reports with no thread
annotate_reviewer_severity(threads)
+ parse_reviewer_overview → parse_claude_overview # bhrv marker, open-items block, empty body
reviewer_overview_for(author)
- review_request vendors only (Copilot)
+ head_reviews vendors (Copilot, Claude); newer of head review and summary comment
clean_blocked_by(threads, overview, head_review_vendor)
+ known ids include synthetic summary findings
wait
review_activity_fingerprint
+ + author's finished summary comments (never the "Claude Code is working…" tracking comment)
request_rereview (comment path)
+ head_already_reviewed → already_reviewed_head # a push-triggered review beat the pingThe login problem the example PR exposes — Claude's review posted by github-actions[bot] — is solved by binding a login to a vendor:
--list-reviewers
- Claude Code (as github-actions) `github-actions` trigger=@claude
(select with --reviewer github-actions --reviewer-vendor claude)
record: {login: "github-actions", vendor: "claude", review_trigger: "@claude", …}
bind_from_record() restores it in both scripts; author filters keep "github-actions";
binding another vendor's own login (chatgpt-codex-connector → claude) is refused.
Design, verified facts and the live evidence table: docs/superpowers/specs/2026-10-21-claude-reviewer-design.md.
Evidence
- Before:
--list-reviewerson a private repository's PR found nothing (the review is a PR comment, not a thread or review), and selectingclaudeon a hosted-review PR producedunknownseverities, a guessed mention, no clean gate, and a wait that a "No issues found" comment could never end.
After: read-only runs against live PRs, scratch state dir, no GitHub writes:
$ fetch_gemini_threads.py --pr …/OWNER/REPO/pull/N --list-reviewers
- Claude Code (as github-actions) `github-actions` trigger=@claude (select with --reviewer github-actions --reviewer-vendor claude)
$ fetch_gemini_threads.py --pr …/REPO/pull/N --reviewer github-actions --reviewer-vendor claude --dry-run --format json
selection: login=github-actions display_name="Claude Code (as github-actions)" review_trigger=@claude vendor=claude
overview: source=comment approving=True open_findings=0 covers_head=True cleanBlockedBy: None
$ fetch_gemini_threads.py --pr …/anthropics/claude-agent-sdk-python/pull/1422 --reviewer claude --dry-run --format json
overview: assessment="No new blocking issues." commit=e41ad10 covers_head=True open_findings=2
finding_ids=[4331815546, 4331815536] cleanBlockedBy: None
- Tests: 1,472 → 1,544, all passing (
pytest -q). New:tests/test_claude_review.py(vendor, binding, markers, both parsers, summary findings, wait, overview choice, discovery, request-side dedupe) andtests/test_acceptance_claude_cycle.pyovertests/fixtures/claude_cycle.json(hosted cycle fetch → ping → head-anchored re-fetch; clean / stale / unseen open item / dispositioned; the action's clean note after body-less reviews; tracking comment alone times out; CI-summary cycle undergithub-actionswith the binding restored; filtered summary finding does not block clean). Copilot, Codex and Gemini suites pass unmodified apart from thehead_review_vendorkeyword rename intest_copilot_overview.py. Doc budgets hold without a raise (SKILL.md 15,277 / 15,300 bytes after dropping one sentence already stated inscript-usage.md).
Merge Danger
Door: two-way
Revert restores the previous scripts; the only persisted-state change is an optional vendor key on a reviewer record, which older code ignores.
Blast Radius: additive
Codex and Gemini paths are untouched except for two additive reads: the main GraphQL query gains commits(last:1){committedDate} and the discovery query gains comments(last:100){author body}. Copilot keeps its behavior under the renamed head_reviews flag. Known limits, stated in the docs: a repo running both the hosted service and the action on the default @claude phrase starts both on one ping (Anthropic's advice is to change the action's trigger_phrase); a summary comment the parser cannot read is overview_unparseable and left to the agent; the action's own /code-review inline comments carry no grade and stay unknown.
🤖 Generated with Claude Code
Summary by Sourcery
Make Claude Code a first-class reviewer with support for its hosted, action-based, and CI-driven review workflows.
New Features:
- Add Claude Code as a built-in reviewer across hosted Code Review, claude-code-action, and CI summary-comment workflows.
- Support reviewer discovery, severity parsing, head-commit coverage, summary findings, clean verdicts, and re-review handling for Claude.
- Allow non-standard reviewer logins such as github-actions to be bound to a known vendor with --reviewer-vendor.
Bug Fixes:
- Prevent Claude tracking comments from being treated as completed review activity.
- Avoid redundant Claude re-review requests when the current head has already been reviewed.
- Prevent clean results from being reported when Claude has not reviewed the current head or when unaccounted findings remain.
Enhancements:
- Generalize head-anchored review and overview handling so it supports Claude alongside Copilot while preserving existing vendor behavior.
- Represent findings reported only in Claude summary comments as actionable synthetic findings with normalized severity.
Documentation:
- Document Claude Code setup, supported review surfaces, reviewer binding, severity formats, and known limitations.
Tests:
- Add unit and acceptance coverage for Claude vendor behavior, parsing, discovery, login binding, waiting, clean gating, and re-review deduplication.
Chores:
- Add Claude Code metadata to the plugin marketplace and plugin manifests.
v0.4.5: fix: count unlogged review requests as an upper bound; uniform posted status
What
Three gaps found running v0.4.4 on a Copilot-enabled org from a second machine (a private repository):
uncountable_countwas notcapped. With no local provenance but review requests under the member's login on the timeline,count_agent_review_requestsreturned None and the loop refused to post. Every first run on a second machine (or after a cleared state dir) hit this. Both sides now count those requests as an upper bound toward the cap. The fetch already reported that bound ("1/3"); it now also lets it reachlimitReached, so the two scripts agree. Acappedpayload carriescount_is_upper_boundand says the count includes manual clicks, so the member knows raising the cap is the honest answer.- No "stop or raise the cap?" prompt. SKILL.md Stopping Condition 1 now asks once: stop, or raise to N (
--max-rereview-requests N).cappedmoves out of step 8's "stop and relay exactly" list. Byte budget held (15295/15300) by trimming wording in the same section. - Posted results had no
status.post_rereview,request_review(posted and dry-run) and the confirmed-after-uncertain payload now carrystatus: "posted"/"dry_run", so a wrapper branching onstatusno longer treats success as nothing-happened and skips the wait.
Tests
test_requests_with_no_local_record_count_as_an_upper_bound,test_unknown_provenance_with_candidate_events_counts_the_bound(inverted from the PR #116 refusal rule, with the reason in the docstrings)test_a_cap_hit_without_local_provenance_says_the_count_is_a_boundtest_a_posted_request_carries_a_status_like_every_other_result- fetch:
test_an_actor_fallback_count_reaches_the_cap_like_the_request_side
1455 passed, ruff clean, run_profile.py passed.
🤖 Generated with Claude Code
https://claude.ai/code/session_01WAVwBABjFrMBSwMRMDALr9
Summary by Sourcery
Align review-request counting and reporting across machines by treating unlogged history as an explicit upper bound, preserving it in provenance, and standardizing result statuses.
New Features:
- Treat review requests found without local provenance as an upper-bound count toward the re-review cap, with explicit payload messaging and baseline adoption for future consistency.
- Add a stopping-condition prompt to either stop at the cap or raise the configured re-review limit.
- Include uniform
statusvalues for posted and dry-run review-request results.
Bug Fixes:
- Prevent second-machine or cleared-state runs from refusing to proceed solely because prior review-request provenance is unavailable.
- Ensure wrappers recognize successful review-request posts and continue to the wait phase.
- Keep fetch-side cap reporting aligned with request-side upper-bound counting.
Enhancements:
- Adopt existing login-attributed review requests into provenance before posting and fail safely when that history cannot be recorded.
- Share a single timeline snapshot between provenance adoption and cap counting.
- Mark cap results based on adopted or unlogged history as upper bounds, including manual clicks.
Documentation:
- Update privacy, design, and workflow guidance to document provenance adoption, upper-bound counts, and cap handling.
Tests:
- Add coverage for upper-bound counting, baseline adoption and recovery, shared timeline snapshots, cap payloads, and posted-result statuses.
v0.4.4: feat: GitHub Copilot as a first-class reviewer
Summary
GitHub Copilot code review becomes a built-in reviewer, alongside Codex and Gemini. Copilot reviews only on request and has no comment trigger, so this adds a second vendor kind: trigger_kind: review_request, re-asked through the GitHub reviewer-request API instead of an @mention.
- Vendor record (
review_vendors.py):COPILOTwithrequest_login: copilot-pull-request-reviewer[bot];Copilot,@copilot, and the[bot]login all resolve and canonicalize before filtering. - Request path (
request_rereview.py): reads PR state first (GraphQL head + pendingreviewRequests; paginated REST reviews and request events) and only then posts. States: completed-current-head, pending, stale-pending (20 min, withdrawn before re-posting), absent, unknown. Never re-requests while pending; an uncertain POST is reconciled via the timeline and otherwise reported as unknown, not as unposted. Failures classified as permission / validation / rate-limited / transient / not-found / uncertain / not_enabled.--expect-headguards the post-push window on both paths. - Registration check (from the first live run): GitHub answers 201 and adds nobody when Copilot code review is not available for the repo. After a 201 the script reads
reviewRequestsback (3 tries, 1 s apart; a vendor review landing on the head counts too) and reportsreview_request_rejected/not_enabledwith nothing stamped when the reviewer never appears. - Cap (
reviewer_resolver.counted_review_requests): one rule shared by fetch and request sides. Only the loop's own review requests made after Copilot's first completed review count. The initial request, a human's click, refused posts, deduped posts and dropped posts are free. Missing local provenance fails closed;reReviewCountComplete: falseflags a lower bound. - Wait (
fetch_gemini_threads.py): Copilot waits are anchored onreview.commit.oid == headRefOid, so a same-second review is caught and a review of a previous head (or by another bot) never ends the wait. Gemini's fingerprint path is byte-identical. - Severity: parsed from Copilot's per-review overview (
alt="High severity"next to a#discussion_r<id>link), attached asreviewerSeveritywith provenance (review_url,commit). Unparseable overview leaves threadsunknownand kept. - Clean gate:
loopStatus.cleanBlockedBy∈ {no_review_for_head,overview_unparseable,overview_reports_open_findings}. A stale approval never makes the PR clean; findings whose threads were resolved without a push do not block (thread state is live, the overview a snapshot); a count exceeding the parsed links blocks. - Discovery: candidates also come from (paginated) review authors and pending review requests.
- Docs: README prerequisites and reviewer table, three-convention severity caveat,
references/reviewer-selection.mdstatuses andcleanBlockedByguidance, SKILL.md steps 4/6/8 (budget raised 15000→15300 bytes with justification intests/budgets.json).
Design spec (with §6.1 and §9 live amendments), plan, and the raw GraphQL evidence from public Copilot PRs are under docs/superpowers/.
Branch history note
This branch was rewritten on 2026-10-10 to drop the unrelated glg-questionnaire plugin commit it had been carrying. The glg work, including the glg halves of the eight mixed Codex-cycle fix commits, now lives on feat/glg-questionnaire; CHANGELOG bullets were partitioned per commit by plugin. Codex review threads on glg files from before the rewrite no longer apply here.
Test plan
-
/opt/homebrew/bin/pytest -q→ 1290 passed on this branch (1220 onfeat/glg-questionnaire) - Regression tests for: pending review, current-head dedupe, stale review (cancel then re-post), same-second response, incomplete pagination, unparseable overview, initial-request cap exemption, human request not counted, 422 →
validationwith nothing stamped, 201-with-nobody-added →not_enabledwith nothing stamped - Fresh whole-branch review (pre-rewrite): 0 Critical; 4 Important fixed with RED→GREEN tests. Nine further Codex review cycles on this PR fixed by a second session.
- Live run 1 (2026-10-10,
OrenAshkenazy/copilot-review-lab#1, account without a Copilot code review plan): discovery and--dry-runcorrect (ABSENT,would_post); real POST → 201 withrequested_reviewers: [], no pending request, no timeline event; the script wrongly saidposted: true→ fixed (registration check), re-run with the fix →review_request_rejected/not_enabled, nothing stamped. Head-anchored wait ignored Sourcery's and Codex's reviews of the same head and ran to its timeout as designed. - Live run 2 (pending Copilot entitlement): real request registered →
review_pendingon immediate re-run → head-anchored wait returns on Copilot's review →reviewerOverview.covers_head: true, overview severities on threads,reReviewRequests == 1→already_reviewed_headon re-request. Needs a Copilot plan that includes code review on this account, or a repo in an org that enables it.
Notes for the reviewer
- Deferred minors from the final review (not fixed): overview parser hardening against legend icons and
]in titles;pending_sinceset while ABSENT; no runner-level end-to-end test of the request flow.
🤖 Generated with Claude Code
v0.4.3: OpenAI submission
Summary by Sourcery
Harden re-review cap enforcement and improve GitHub CLI error reporting across the review loop.
Bug Fixes:
- Prevent re-review requests when the existing request count cannot be established, ensuring the cap cannot be bypassed unintentionally.
- Report missing working directories separately from missing GitHub CLI installations.
Enhancements:
- Clarify re-review cap failure statuses and loop guidance across the plugin documentation.
- Update test utilities and coverage for known cap checks, uncountable counts, bypass behavior, and GitHub CLI error handling.
Documentation:
- Document that uncountable re-review writes are refused unless the cap check is explicitly bypassed.
Tests:
- Add coverage for refusing requests with unknown counts and for distinguishing invalid working-directory errors from missing GitHub CLI errors.
v0.4.2: openai submission
- fix(skill): explicit precedence, clean gh-missing stop, one name for the cap
- chore(manifests): OpenAI directory limits and one story across all listings
Summary by Sourcery
Clarify the review-loop contract and consistently present its bounded counter as re-review requests across supported listings and user-facing reporting.
Bug Fixes:
- Handle missing GitHub CLI installations with a clear actionable error and stop cleanly instead of exposing a traceback or falling back to raw API calls.
Enhancements:
- Clarify skill instruction precedence, required preconditions, reviewer selection, and cap behavior.
- Rename user-facing cycle metrics to consistently identify re-review requests and their cap across receipts, summaries, statistics, documentation, and manifests.
Documentation:
- Update review-loop documentation and examples to use the re-review request terminology and explain runtime limitations.
Tests:
- Add regression coverage for instruction-precedence and precondition contracts, consistent cap labeling, and missing-
gherror handling.
v0.4.1: fix: pre-launch hardening — anchor containment, state-dir file shadowing
Three findings from an adversarial pass over the v0.2.34..v0.4.0 delta.
-
Shape clustering read anchored files without the containment rule the
sweep enforces. _anchored_tokens did root / path on a thread-supplied
path, so a symlinked or ../ anchor leaked tokens from files the diff
never touched into the merge decision — while the README extends the
"never reads outside the changed files" claim to cluster_findings.py,
and this same release shipped _contained_path for exactly this vector
in sweep_siblings.py. It now routes through the same helper: a path
that escapes yields no tokens, and the cluster falls back to prose. -
A stray file at ~/.config/gh-review-loop shadowed a legacy directory
full of user data. state_dir() used exists(), which is true for files,
so resolution picked a path that cannot hold state and the next write
crashed with an uncaught FileExistsError (exist_ok does not cover
non-directories) while preferences.json and runs.jsonl sat untouched
in the legacy dir. is_dir() falls back to the legacy data instead. -
The relocated "Why this exists" README section was pasted without a
blank line after the preceding paragraph.
Tests: symlink and ../ anchors produce no shape merge; a file at the new
state path resolves to the legacy directory. 1102 pass, replay byte-stable.
Summary by Sourcery
Harden pre-launch review processing against untrusted anchor paths and invalid state-directory shadowing.
Bug Fixes:
- Prevent shape clustering from reading anchored files outside the changed repository through symlink or parent-directory escapes.
- Resolve state storage to the legacy directory when the new state path is occupied by a file, preserving existing user data and avoiding write failures.
Documentation:
- Restore the missing spacing before the README's “Why this exists” section.
Tests:
- Add coverage for symlinked and parent-directory anchor escapes and file-shadowed state-directory resolution.