diff --git a/.github/cursor-review/README.md b/.github/cursor-review/README.md index 4ea8f0b9..4041eaaf 100644 --- a/.github/cursor-review/README.md +++ b/.github/cursor-review/README.md @@ -435,6 +435,7 @@ All optional except `workflows_ref` (required, no default) — pass them under | `approve_only_max_runs` | `10` | Re-checks per panel round, read off the re-check sentinel, which names the round it counts for; clamped to `card.RECHECK_HEADS_KEPT` (50), past which the count could not grow. | | `carry_forward_unchanged_diff` | `false` | Opt-in: `dismiss-stale-approval` re-approves the live head before dismissing when the PR's own changes (compare API, merge base → head, hunk line numbers ignored, headings and inter-hunk distances kept) equal the ones the approving round reviewed under a threshold no looser than today's — the stacked-PR rebase, re-merge or retarget. What the round reviewed comes only from the approver's own records: the merge base the approval recorded (`approval_merge_base`, when the compare API and the round's sentinel agree — the sentinel can veto a record, never supply one) or what a carried approval copied forward (`carry_baseline`), and the compare API must show it as an ancestor of the reviewed commit; an approval with neither never carries. Only under `pull_request_target`, only for the approver's latest verdict, failing closed (dismissing as before) on anything it cannot compare (`try_carry_forward`); `mark_card_stale` leaves the card alone while such an approval stands. See [the setup guide](../../docs/callers/cursor-review.md#auto-approve). | | `max_rounds` | `5` | Per-PR review-round cap; `0` → none. Counts the posting identity's consolidated reviews since `needs-human-review` was last removed, except a round whose own decision found the PR head had moved (a push superseded it), at most once per reviewed commit and at most `max_rounds` times; at or over the cap the panel is skipped, the PR is labelled `needs-human-review`, one comment lists the latest round's open findings above the threshold, and the `approve_gate` output is `capped`. Fails open on a read error. See [the setup guide](../../docs/callers/cursor-review.md#round-cap-and-the-approve_gate-output). | +| `handoff_after_cap` | `false` | After the last allowed delivered review, recount and hand off in the same run. Requires a positive cap and `fail_closed_round_cap`; concurrent and undelivered runs are not serialized. | | `preserve_round_count` | `false` | Keep counting prior delivered reviews after the human handoff label is removed. Does not count undelivered panels or serialize runs. | | `count_superseded_rounds` | `false` | Count delivered reviews even when a later decision found the head moved. Does not count undelivered panels or change resets. | | `fail_closed_round_cap` | `false` | Stop the panel if cap evaluation or handoff fails. Requires a positive `max_rounds`; does not change resets, superseded-round exemptions or concurrency. | diff --git a/.github/cursor-review/auto-approve.py b/.github/cursor-review/auto-approve.py index c30a69cb..98ded56d 100644 --- a/.github/cursor-review/auto-approve.py +++ b/.github/cursor-review/auto-approve.py @@ -281,6 +281,7 @@ VETO_LABELS = (SKIP_REVIEW_LABEL,) ROUND_CAP_MARKER = "" PRESERVED_CAP_MARKER = "" +AFTER_REVIEW_CAP_MARKER = "" # post-review.py opens two bodies with CONSOLIDATED_MARKER that report a round # which reviewed NOTHING — the "Review failed" error review and the # all-panel-cells-failed review (both `delivers=False`). Neither spent a panel's @@ -4077,13 +4078,15 @@ def superseded_by_push(panel: dict, reviews: list, login: str, marker: str) -> s return "" -def cap_comment_posted(comments: list, poster_login: str, since, preserve: bool = False) -> bool: +def cap_comment_posted(comments: list, poster_login: str, since, preserve: bool = False, + after_review: bool = False) -> bool: """True when this cap's comment is already on the PR (posted after `since`).""" return any( isinstance(c, dict) and ((c.get("user") or {}).get("login") or "").lower() == poster_login.lower() and (PRESERVED_CAP_MARKER if preserve else ROUND_CAP_MARKER) in (c.get("body") or "") and (preserve or PRESERVED_CAP_MARKER not in (c.get("body") or "")) + and ((AFTER_REVIEW_CAP_MARKER in (c.get("body") or "")) == after_review) and _after(c.get("created_at"), since) for c in comments ) @@ -4111,19 +4114,22 @@ def cap_findings(review_comments: list, open_ids, threshold: str) -> list: def render_cap_comment(rounds: int, max_rounds: int, findings: list, threshold: str, review_url: str, - preserve: bool = False) -> str: + preserve: bool = False, after_review: bool = False) -> str: render_code_ref = _load_post_review().render_code_ref scope = f"above `{threshold}`" if threshold else "still open" lines = [ ROUND_CAP_MARKER, "### 🛑 Cursor Review — round cap reached", - f"This PR has had {rounds} review round(s) (`max_rounds: {max_rounds}`), so no new " - f"panel ran and it is labelled `{HUMAN_REVIEW_LABEL}`. Auto-approve will not " + f"This PR has had {rounds} review round(s) (`max_rounds: {max_rounds}`); " + + ("the latest review was delivered" if after_review else "no new panel ran") + + f" and it is labelled `{HUMAN_REVIEW_LABEL}`. Auto-approve will not " "approve it while the label is on; " + ("removing the label does not reset the round count." if preserve else "removing the label resets the round count."), ] if preserve: lines.insert(1, PRESERVED_CAP_MARKER) + if after_review: + lines.insert(1, AFTER_REVIEW_CAP_MARKER) if findings: lines.append(f"\nFindings from the latest round {scope}:") for sev, path, line in findings[:30]: @@ -4222,8 +4228,19 @@ def parse_max_rounds(value) -> int: return int(number) +def uncertain_after_review_handoff(args, reason: str) -> int: + """Stop a later review while the delivered round's count is uncertain.""" + try: + ensure_label(args.repo, args.pr_number) + except RuntimeError as e: + print(f"::error::Could not apply the human handoff label: {e}") + print(f"::error::{reason}; the handoff needs human verification.") + return 1 + + def cmd_round_cap(args) -> int: - strict = getattr(args, "fail_closed_round_cap", False) + after_review = getattr(args, "after_review", False) + strict = getattr(args, "fail_closed_round_cap", False) or after_review set_output("capped", "false") set_output("labelled", "false") # The EFFECTIVE cap, for the workflow's `max_rounds` output: an invalid value @@ -4256,6 +4273,8 @@ def cmd_round_cap(args) -> int: set_output("labelled", "true") except (RuntimeError, ValueError) as e: print(f"::warning::Could not read this PR's labels: {e}") + if after_review: + return uncertain_after_review_handoff(args, "Could not read the PR labels after delivery") if strict: return 1 try: @@ -4267,6 +4286,8 @@ def cmd_round_cap(args) -> int: 0 if getattr(args, "count_superseded_rounds", False) else max_rounds) except (RuntimeError, ValueError) as e: # Legacy callers fail open; strict callers stop the panel. + if after_review: + return uncertain_after_review_handoff(args, "Could not count review rounds after delivery") if strict: print(f"::error::Could not count review rounds; stopping the panel: {e}") return 1 @@ -4278,6 +4299,8 @@ def cmd_round_cap(args) -> int: # than a guess. set_output("next_round", len(rounds) + 1) if len(rounds) < max_rounds: + if after_review: + return uncertain_after_review_handoff(args, "The delivered review is not yet reflected in the count") emit(f"Round cap: {len(rounds)}/{max_rounds} round(s) so far — running the panel.") return 0 @@ -4296,11 +4319,13 @@ def cmd_round_cap(args) -> int: return 0 set_output("capped", "true") set_output("labelled", "true") - emit(f"🛑 **Round cap reached** — {len(rounds)}/{max_rounds} round(s); skipped the panel and labelled `{HUMAN_REVIEW_LABEL}`.") + emit(f"🛑 **Round cap reached** — {len(rounds)}/{max_rounds} round(s); " + + ("review delivered" if after_review else "skipped the panel") + + f" and labelled `{HUMAN_REVIEW_LABEL}`.") failed = [] try: comments = _paginate(f"repos/{args.repo}/issues/{args.pr_number}/comments?per_page=100") - if cap_comment_posted(comments, args.poster_login, since, preserve): + if cap_comment_posted(comments, args.poster_login, since, preserve, after_review): emit("Round cap: the cap comment is already on this PR — not posting it again.") else: latest = rounds[-1] @@ -4308,7 +4333,7 @@ def cmd_round_cap(args) -> int: f"repos/{args.repo}/pulls/{args.pr_number}/reviews/{latest['id']}/comments?per_page=100" ) findings = cap_findings(review_comments, open_thread_ids(args.repo, int(args.pr_number)), threshold) - body = render_cap_comment(len(rounds), max_rounds, findings, threshold, latest.get("html_url") or "", preserve) + body = render_cap_comment(len(rounds), max_rounds, findings, threshold, latest.get("html_url") or "", preserve, after_review) gh(["api", "-X", "POST", f"repos/{args.repo}/issues/{args.pr_number}/comments", "--input", "-"], {"body": body}) except (RuntimeError, ValueError, KeyError) as e: failed.append(f"comment: {e}") @@ -4744,6 +4769,7 @@ def main() -> int: c.add_argument("--fail-closed-round-cap", action="store_true") c.add_argument("--count-superseded-rounds", action="store_true") c.add_argument("--preserve-round-count", action="store_true") + c.add_argument("--after-review", action="store_true") e = sub.add_parser("approve-external") e.add_argument("--repo", required=True) e.add_argument("--pr-number", required=True) diff --git a/.github/cursor-review/tests/test_auto_approve.py b/.github/cursor-review/tests/test_auto_approve.py index a930b51b..69626b77 100644 --- a/.github/cursor-review/tests/test_auto_approve.py +++ b/.github/cursor-review/tests/test_auto_approve.py @@ -1823,14 +1823,14 @@ def test_comment_neutralises_model_paths(self): class StrictRoundCapPrerequisiteTest(unittest.TestCase): - def run_prerequisite(self, limit, configured, token, slug): + def run_prerequisite(self, limit, configured, token, slug, handoff="false", fail_closed="false"): with open(WORKFLOW_PATH, encoding="utf-8") as f: workflow = f.read() step = workflow.split("- name: Validate strict cap prerequisites", 1)[1].split("\n - name:", 1)[0] script = step.split("run: |\n", 1)[1] script = "\n".join(line[10:] for line in script.splitlines()) env = {"PATH": os.environ["PATH"], "MAX_ROUNDS": limit, "BOT_CONFIGURED": configured, - "BOT_TOKEN": token, "BOT_SLUG": slug} + "BOT_TOKEN": token, "BOT_SLUG": slug, "HANDOFF_AFTER_CAP": handoff, "FAIL_CLOSED": fail_closed} return subprocess.run(["bash", "-e", "-c", script], env=env, capture_output=True).returncode def test_no_bot_allows_a_positive_limit(self): @@ -1842,6 +1842,10 @@ def test_configured_bot_needs_both_token_and_identity(self): self.assertNotEqual(self.run_prerequisite("3", "true", token, slug), 0) self.assertEqual(self.run_prerequisite("3", "true", "token", "bot"), 0) + def test_immediate_handoff_requires_fail_closed_counting(self): + self.assertNotEqual(self.run_prerequisite("3", "false", "", "", handoff="true"), 0) + self.assertEqual(self.run_prerequisite("3", "false", "", "", handoff="true", fail_closed="true"), 0) + def test_zero_and_negative_limits_are_rejected(self): for limit in ("0", "-1"): with self.subTest(limit=limit): @@ -1869,11 +1873,41 @@ def test_count_step_passes_the_opt_in_to_the_real_entrypoint(self): +class ImmediateHandoffStepTest(unittest.TestCase): + def test_step_runs_after_post_and_before_approval_with_policy_flags(self): + with open(WORKFLOW_PATH, encoding="utf-8") as f: + workflow = f.read() + post = workflow.split(" post-review:\n", 1)[1].split("\n dismiss-stale-approval:", 1)[0] + self.assertLess(post.index("- name: Post review"), post.index("- name: Hand off after the last delivered review")) + self.assertLess(post.index("- name: Hand off after the last delivered review"), post.index("- name: Auto-approve decision")) + step = post.split("- name: Hand off after the last delivered review", 1)[1].split("\n - name:", 1)[0] + self.assertIn("steps.post.outputs.delivered == 'true'", step) + self.assertIn("needs.round-cap.outputs.next_round == inputs.max_rounds", step) + script = "\n".join(line[10:] for line in step.split("run: |\n", 1)[1].splitlines()) + with tempfile.TemporaryDirectory() as d: + with open(os.path.join(d, "auto-approve.py"), "w", encoding="utf-8") as f: + f.write("import json, os, sys\nopen(os.environ['ARGS'], 'w').write(json.dumps(sys.argv[1:]))\n") + path = os.path.join(d, "args") + env = {"PATH": os.environ["PATH"], "CURSOR_REVIEW_ASSETS": d, "ARGS": path, + "APP_SLUG": "review", "BOT_TOKEN": "token", "BOT_APP_ID": "1", + "COUNT_SUPERSEDED_ROUNDS": "true", "PRESERVE_ROUND_COUNT": "true", + "REPO": "o/r", "PR_NUMBER": "1", "MAX_ROUNDS": "3", "THRESHOLD": ""} + subprocess.run(["bash", "-e", "-c", script], env=env, check=True, capture_output=True) + with open(path, encoding="utf-8") as f: + args = json.load(f) + for flag in ("--after-review", "--count-superseded-rounds", "--preserve-round-count"): + self.assertIn(flag, args) + self.assertEqual(args[args.index("--poster-login") + 1], "review[bot]") + env["BOT_TOKEN"] = "" + self.assertNotEqual(subprocess.run(["bash", "-e", "-c", script], env=env, + capture_output=True).returncode, 0) + + class RoundCapCommandTest(unittest.TestCase): """The cap path end to end, with gh stubbed by endpoint.""" def run_cap(self, reviews, max_rounds="5", timeline=(), comments=(), label_exists=True, fail=(), labels=(), - probe_error="HTTP 404", strict=False, count_superseded=False, preserve=False): + probe_error="HTTP 404", strict=False, count_superseded=False, preserve=False, after_review=False): writes = [] def fake_gh(args, payload=None): @@ -1911,7 +1945,7 @@ def fake_gh(args, payload=None): open(out, "w").close() args = argparse.Namespace(repo="o/r", pr_number="1", max_rounds=max_rounds, threshold="medium", poster_login=BOT, fail_closed_round_cap=strict, count_superseded_rounds=count_superseded, - preserve_round_count=preserve) + preserve_round_count=preserve, after_review=after_review) with mock.patch.dict(os.environ, {"GITHUB_OUTPUT": out}), \ mock.patch.object(AA, "gh", fake_gh), \ mock.patch.object(AA, "open_thread_ids", lambda *a: {"11", "12"}), \ @@ -2001,6 +2035,34 @@ def test_opt_in_counts_a_delivered_review_superseded_by_a_push(self): self.assertEqual((default["capped"], default["rounds"]), ("false", "2")) self.assertEqual((counted["capped"], counted["rounds"]), ("true", "3")) + def test_after_third_review_hands_off_and_describes_completed_round(self): + rc, out, writes = self.run_cap(self.FIVE[:3], max_rounds="3", strict=True, + preserve=True, after_review=True) + self.assertEqual((rc, out["capped"]), (0, "true")) + bodies = [payload["body"] for _, path, payload in writes if path.endswith("/comments")] + self.assertEqual(len(bodies), 1) + self.assertIn("the latest review was delivered", bodies[0]) + self.assertNotIn("no new panel ran", bodies[0]) + + def test_after_review_does_not_reuse_a_pre_review_handoff_notice(self): + prior = {"user": {"login": BOT}, "body": AA.ROUND_CAP_MARKER + "\n" + AA.PRESERVED_CAP_MARKER, + "created_at": "2026-01-06T00:00:00Z"} + _, _, writes = self.run_cap(self.FIVE[:3], max_rounds="3", preserve=True, after_review=True, + comments=[prior]) + bodies = [payload["body"] for _, path, payload in writes if path.endswith("/comments")] + self.assertEqual(len(bodies), 1) + self.assertIn("the latest review was delivered", bodies[0]) + + def test_after_review_fails_if_delivered_round_is_not_visible_yet(self): + rc, _, writes = self.run_cap(self.FIVE[:2], max_rounds="3", strict=True, after_review=True) + self.assertNotEqual(rc, 0) + self.assertIn(("POST", "repos/o/r/issues/1/labels"), [(m, p) for m, p, _ in writes]) + + def test_after_review_marks_handoff_if_history_cannot_be_read(self): + rc, _, writes = self.run_cap(self.FIVE[:3], max_rounds="3", after_review=True, fail=("/reviews",)) + self.assertNotEqual(rc, 0) + self.assertIn(("POST", "repos/o/r/issues/1/labels"), [(m, p) for m, p, _ in writes]) + def test_strict_cap_allows_two_and_hands_off_at_three(self): rc, out, _ = self.run_cap(self.FIVE[:2], max_rounds="3", strict=True) self.assertEqual((rc, out["capped"], out["rounds"]), (0, "false", "2")) diff --git a/.github/workflows/cursor-review.yml b/.github/workflows/cursor-review.yml index 1f3d90d5..23bf91a2 100644 --- a/.github/workflows/cursor-review.yml +++ b/.github/workflows/cursor-review.yml @@ -766,6 +766,15 @@ on: type: number required: false default: 5 + handoff_after_cap: + description: >- + After the last allowed delivered review, recount and hand the PR to a + human in the same run. Requires a positive max_rounds and + fail_closed_round_cap. This is not an + atomic cap on concurrent or undelivered runs. + type: boolean + required: false + default: false preserve_round_count: description: >- Keep counting prior delivered reviews when the human handoff label is @@ -1916,16 +1925,22 @@ jobs: private-key: ${{ secrets.BOT_APP_PRIVATE_KEY }} - name: Validate strict cap prerequisites - if: ${{ inputs.fail_closed_round_cap }} + if: ${{ inputs.fail_closed_round_cap || inputs.handoff_after_cap }} env: MAX_ROUNDS: ${{ inputs.max_rounds }} BOT_TOKEN: ${{ steps.bot_token.outputs.token }} BOT_SLUG: ${{ steps.bot_token.outputs.app-slug }} + HANDOFF_AFTER_CAP: ${{ inputs.handoff_after_cap }} + FAIL_CLOSED: ${{ inputs.fail_closed_round_cap }} run: | if ! python3 -c 'import sys; sys.exit(0 if float(sys.argv[1]) > 0 else 1)' "$MAX_ROUNDS"; then echo "::error::fail_closed_round_cap requires a positive max_rounds" exit 1 fi + if [ "$HANDOFF_AFTER_CAP" = true ] && [ "$FAIL_CLOSED" != true ]; then + echo "::error::handoff_after_cap requires fail_closed_round_cap" + exit 1 + fi if [ "$BOT_CONFIGURED" = true ] && { [ -z "$BOT_TOKEN" ] || [ -z "$BOT_SLUG" ]; }; then echo "::error::The configured posting bot token could not be minted; cannot count its reviews" exit 1 @@ -6458,6 +6473,35 @@ jobs: --error-message "Judge call failed (status=${JUDGE_STATUS}): ${JUDGE_ERROR}" fi + - name: Hand off after the last delivered review + if: >- + ${{ inputs.handoff_after_cap && steps.post.outputs.delivered == 'true' && + needs.round-cap.outputs.next_round != '' && + needs.round-cap.outputs.next_round == inputs.max_rounds }} + env: + GH_TOKEN: ${{ steps.bot_token.outputs.token || secrets.GITHUB_TOKEN }} + BOT_TOKEN: ${{ steps.bot_token.outputs.token }} + APP_SLUG: ${{ steps.bot_token.outputs.app-slug }} + BOT_APP_ID: ${{ inputs.bot_app_id }} + MAX_ROUNDS: ${{ inputs.max_rounds }} + THRESHOLD: ${{ inputs.approve_max_severity }} + COUNT_SUPERSEDED_ROUNDS: ${{ inputs.count_superseded_rounds }} + PRESERVE_ROUND_COUNT: ${{ inputs.preserve_round_count }} + PR_NUMBER: ${{ github.event.pull_request.number }} + REPO: ${{ github.repository }} + run: | + if [ -n "$BOT_APP_ID" ] && { [ -z "$BOT_TOKEN" ] || [ -z "$APP_SLUG" ]; }; then + echo "::error::The posting identity could not be confirmed; handoff was not attempted" + exit 1 + fi + if [ -n "$APP_SLUG" ]; then LOGIN="${APP_SLUG}[bot]"; else LOGIN="github-actions[bot]"; fi + FLAGS=(--after-review) + if [ "$COUNT_SUPERSEDED_ROUNDS" = true ]; then FLAGS+=(--count-superseded-rounds); fi + if [ "$PRESERVE_ROUND_COUNT" = true ]; then FLAGS+=(--preserve-round-count); fi + python3 "$CURSOR_REVIEW_ASSETS/auto-approve.py" round-cap \ + --repo "$REPO" --pr-number "$PR_NUMBER" --max-rounds "$MAX_ROUNDS" \ + --threshold "$THRESHOLD" --poster-login "$LOGIN" "${FLAGS[@]}" + - name: Auto-approve decision # Opt-in (inputs.approve_max_severity). Runs only after `Post review` # succeeded, so the decision is about a review that is on the PR. All of diff --git a/docs/callers/cursor-review.md b/docs/callers/cursor-review.md index 80d82c30..47ca98f9 100644 --- a/docs/callers/cursor-review.md +++ b/docs/callers/cursor-review.md @@ -148,6 +148,7 @@ pull-requests: write # posting the consolidated review (and, at the round cap, | `approve_only_max_runs` | `10` | Cap on `approve_only_on_push` re-checks per panel round, counted on the status card; a new panel round resets it. At the cap a push is left to a relabel (or `auto_rereview_after_dismissal`). Clamped to `50`, the heads the card's record keeps; unparsable re-checks nothing. | | `carry_forward_unchanged_diff` | `false` | Opt-in, for stacked PRs: when a push or a retarget would dismiss the approver's approval but the PR's **own** changes are identical to the ones a round reviewed (a rebase or re-merge onto a moved base, e.g. a lower PR of the stack changed or landed), re-approve the live head, then dismiss the old approval; the card keeps its approval and no round is scheduled. Identical is the compare API's diff from the merge base the approval recorded to the reviewed commit against the diff from the live base to the live head, file by file, context lines and hunk headings included, hunk line numbers ignored. Anything it cannot vouch for dismisses as before, and an approval that records no merge base (every one an earlier version posted, too) never carries. Only under `pull_request_target`, and only with `approve_max_severity` set and `bot_app_id` posting the rounds (with `defer_approval`, pass cursor-approve that App's `poster_login` too). See [Auto-approve](#auto-approve) for every condition and the [trust model](#trust-model) for what it trusts. | | `max_rounds` | `5` | Cap on review rounds per PR (`0` → no cap). At or over it, no panel runs: the PR is labelled `needs-human-review`, one comment lists the latest round's open findings above the threshold, and the `approve_gate` output is `capped`. A round whose own decision found the PR head had moved (a newer push superseded it) does not count, at most once per reviewed commit and at most `max_rounds` times. Removing the label resets the count unless `preserve_round_count` is enabled. See [round cap](#round-cap-and-the-approve_gate-output). | +| `handoff_after_cap` | `false` | After the last allowed delivered review, recount and hand off in the same run. Requires a positive cap and `fail_closed_round_cap`; concurrent and undelivered runs are not serialized. | | `preserve_round_count` | `false` | Keep counting prior delivered reviews after the human handoff label is removed. Does not count undelivered panels or serialize runs. | | `count_superseded_rounds` | `false` | Count delivered reviews even when a later decision found the head moved. Does not count undelivered panels or change resets. | | `fail_closed_round_cap` | `false` | Stop the panel if the cap cannot be evaluated or handoff fails. Requires a positive `max_rounds` and, when configured, the posting bot token and identity. This preserves the existing reset, superseded-round exemptions and concurrency behavior; it does not guarantee a lifetime limit on all reviewer executions. |