claude-dev-env 8.32.2 → 8.33.1

package/rules/agent-merges-its-own-green-pull-request.md

@@ -4,7 +4,7 @@
 
 ## Rule
 
-The agent that drives a pull request merges it. A pull request that is green, carries no open review thread, and sits at a merge state of `clean` is merged in the same run that brought it there. Waiting for the owner to type "merge" parks finished work on the person the work was done for.
+The agent that drives a pull request merges it. A pull request that is green, carries no open review thread, and sits at a merge state of `clean` is merged in the same run that brought it there. A merge state of `unstable` counts as `clean` when every check's newest report on the head passes. GitHub also counts the older runs of a check that ran again, so a cancelled run followed by a passing re-run still reads `unstable`. Waiting for the owner to type "merge" parks finished work on the person the work was done for.
 
 Three things stay with the owner, and nothing else does:
 
@@ -24,7 +24,7 @@ One command prints the verdict:
 python packages/claude-dev-env/scripts/agent_merge_check.py <owner>/<name> <number>
 ```
 
-It prints `MERGE` and exits 0 when the pull request is ready. It prints `HOLD` with the reason and exits 1 for a draft, for a head behind or conflicting with the base, for a required check that is not passing, for a check still running or red, for a head the merge queue ejected for failed checks, and for an open review thread. It exits 2 when the state could not be read.
+It prints `MERGE` and exits 0 when the pull request is ready. It prints `HOLD` with the reason and exits 1 for a draft, for a head behind or conflicting with the base, for a required check that is not passing, for a check whose newest report on the head is still running, cancelled, or red, for a head the merge queue ejected for failed checks, and for an open review thread. It exits 2 when the state could not be read.
 
 Each hold reason names its own repair, and each repair belongs to the agent:
 
@@ -33,7 +33,7 @@ Each hold reason names its own repair, and each repair belongs to the agent:
 | Head behind the base | Merge the base branch in and push |
 | Head conflicts with the base | Merge the base branch in, resolve, push |
 | A required check is red | Read the failing check, fix it, push |
-| A check is red or still running | Fix it, or wait for it, then read the verdict again |
+| A check is red, cancelled, or still running | Fix a red one, re-run a cancelled one, or wait for a running one, then read the verdict again |
 | A review thread is open | Answer it, push the fix, resolve the thread |
 | Ejected from the merge queue for failed checks on this head | Read the merge_group run, fix the failure, push, then read the verdict again |
 | The pull request is a draft | Mark it ready once the checks pass |

package/scripts/agent_merge_check.py

@@ -70,6 +70,7 @@ from dev_env_scripts_constants.agent_merge_check_constants import (
     DRAFT_KEY,
     ERROR_EXIT_CODE,
     FAILED_CHECKS_REMOVAL_REASON,
+    FIRST_PAGE_NUMBER,
     FAILING_REQUIRED_CHECKS_HOLD_TEMPLATE,
     GITHUB_ACCEPT_TYPE,
     GITHUB_API_ROOT,
@@ -89,6 +90,7 @@ from dev_env_scripts_constants.agent_merge_check_constants import (
     MERGEABLE_STATE_CLEAN,
     MERGEABLE_STATE_KEY,
     MERGEABLE_STATE_UNKNOWN,
+    MERGEABLE_STATE_UNSTABLE,
     MISSING_CHECK_STATE,
     NAME_VARIABLE,
     NO_SIGN_IN_MESSAGE,
@@ -96,6 +98,7 @@ from dev_env_scripts_constants.agent_merge_check_constants import (
     NUMBER_KEY,
     NUMBER_VARIABLE,
     OWNER_VARIABLE,
+    PAGE_PARAMETER,
     PAGE_SIZE_VARIABLE,
     PENDING_CHECK_STATE,
     PENDING_STATUS_STATE,
@@ -126,6 +129,7 @@ from dev_env_scripts_constants.agent_merge_check_constants import (
     UNKNOWN_STATE_HOLD_TEMPLATE,
     UNRESOLVED_THREAD_QUERY,
     UNRESOLVED_THREADS_HOLD_TEMPLATE,
+    UNSTABLE_CHECKS_HOLD_TEMPLATE,
     UTF8_ENCODING,
     VARIABLES_KEY,
     VERDICT_LINE_TEMPLATE,
@@ -192,6 +196,7 @@ def hold_reason(
     unresolved_thread_count: int,
     blocked_evidence: BlockedEvidence | None = None,
     is_ejected_from_merge_queue: bool = False,
+    all_unstable_checks: tuple[str, ...] | None = None,
 ) -> str | None:
     """Return why this pull request stays open, or None when it may merge.
 
@@ -203,19 +208,31 @@ def hold_reason(
             None when nothing was read.
         is_ejected_from_merge_queue: Whether the merge queue ejected the
             current head for failed checks.
+        all_unstable_checks: Each check whose newest report on the head is
+            not passing, read behind an ``unstable`` merge state, or None
+            when nothing was read.
 
     Returns:
         The reason text for a draft, for a merge state other than clean, for
-        a head the merge queue ejected, and for an open review thread. None
-        when the pull request is ready for the agent that drives it to merge
-        it.
+        a head the merge queue ejected, and for an open review thread. An
+        ``unstable`` head whose newest reports all pass reads as clean,
+        because GitHub also counts the older runs those reports replaced.
+        None when the pull request is ready for the agent that drives it to
+        merge it.
     """
     if all_pull_request_fields.get(DRAFT_KEY):
         return DRAFT_HOLD_REASON
     merge_state = all_pull_request_fields.get(MERGEABLE_STATE_KEY)
     if merge_state == MERGEABLE_STATE_BLOCKED and blocked_evidence is not None:
         return blocked_hold_reason(blocked_evidence)
-    if merge_state != MERGEABLE_STATE_CLEAN:
+    if merge_state == MERGEABLE_STATE_UNSTABLE and all_unstable_checks:
+        return UNSTABLE_CHECKS_HOLD_TEMPLATE.format(
+            checks=REQUIRED_CHECK_SEPARATOR.join(all_unstable_checks)
+        )
+    is_superseded_unstable = (
+        merge_state == MERGEABLE_STATE_UNSTABLE and all_unstable_checks == ()
+    )
+    if merge_state != MERGEABLE_STATE_CLEAN and not is_superseded_unstable:
         return ALL_HOLD_REASONS_BY_STATE.get(
             merge_state,
             UNKNOWN_STATE_HOLD_TEMPLATE.format(state=merge_state),
@@ -346,6 +363,70 @@ def _newest_matching_run(
     return max(all_matching_runs, key=_check_run_id)
 
 
+def unmet_newest_checks(
+    all_check_runs: Sequence[object],
+    all_statuses: Sequence[object],
+) -> tuple[str, ...]:
+    """Name each check whose newest report on the head is not passing.
+
+    ::
+
+        Review closure   run 409 cancelled, run 412 cancelled, run 874 success
+                                                               newest ^
+        ok:   ()                                  every newest run passes
+        flag: ("Review closure (cancelled)",)     the newest run is cancelled
+
+    Runs of one name from one app collapse to the run with the highest id,
+    so the latest re-run or workflow run decides the check. Statuses arrive
+    newest first, so the first status of each context decides it.
+
+    Args:
+        all_check_runs: Every check run reported on the head commit.
+        all_statuses: The commit statuses on the head, newest first.
+
+    Returns:
+        Each non-passing check as its name and state, such as
+        ``Ruff (failure)``, check runs first and then commit statuses.
+    """
+    return (*_unmet_run_states(all_check_runs), *_unmet_status_states(all_statuses))
+
+
+def _unmet_run_states(all_check_runs: Sequence[object]) -> list[str]:
+    return [
+        REQUIRED_CHECK_STATE_TEMPLATE.format(
+            context=each_run.get(CHECK_RUN_NAME_KEY), state=state
+        )
+        for each_run in _newest_run_per_check(all_check_runs)
+        if (state := _check_run_state(each_run)) is not None
+    ]
+
+
+def _unmet_status_states(all_statuses: Sequence[object]) -> list[str]:
+    all_newest_statuses: dict[object, Mapping[str, object]] = {}
+    for each_status in all_statuses:
+        if isinstance(each_status, Mapping):
+            all_newest_statuses.setdefault(each_status.get(CONTEXT_KEY), each_status)
+    return [
+        REQUIRED_CHECK_STATE_TEMPLATE.format(context=context, state=state)
+        for context, each_status in all_newest_statuses.items()
+        if (state := _status_state(each_status)) is not None
+    ]
+
+
+def _newest_run_per_check(
+    all_check_runs: Sequence[object],
+) -> list[Mapping[str, object]]:
+    all_newest_runs: dict[tuple[object, object], Mapping[str, object]] = {}
+    for each_run in all_check_runs:
+        if not isinstance(each_run, Mapping):
+            continue
+        run_key = (each_run.get(CHECK_RUN_NAME_KEY), _check_run_app_id(each_run))
+        newest_run = all_newest_runs.get(run_key)
+        if newest_run is None or _check_run_id(each_run) > _check_run_id(newest_run):
+            all_newest_runs[run_key] = each_run
+    return list(all_newest_runs.values())
+
+
 def _check_run_id(all_run_fields: Mapping[str, object]) -> int:
     run_id = all_run_fields.get(CHECK_RUN_ID_KEY)
     return run_id if isinstance(run_id, int) else 0
@@ -563,22 +644,73 @@ def _read_branch_rules(slug: str, base_ref: str, token: str) -> list[object]:
     )
 
 
+def read_unstable_checks(
+    slug: str, head_sha: str, token: str
+) -> tuple[str, ...] | None:
+    """Read which checks hold an ``unstable`` head back by their newest report.
+
+    Args:
+        slug: The repository as ``owner/name``.
+        head_sha: The pull request's head commit.
+        token: The GitHub token the requests authenticate with.
+
+    Returns:
+        Each check whose newest run or latest status on the head is not
+        passing, read across every page of check runs and of statuses. None
+        when the head reports no check run and no status, so nothing
+        explains why GitHub calls it unstable.
+
+    Raises:
+        MergeCheckError: A read failed, or answered with another shape.
+    """
+    all_check_runs = _read_every_page(
+        CHECK_RUNS_ENDPOINT_TEMPLATE, slug, head_sha, token, CHECK_RUNS_KEY
+    )
+    all_statuses = _read_statuses(slug, head_sha, token)
+    if not all_check_runs and not all_statuses:
+        return None
+    return unmet_newest_checks(all_check_runs, all_statuses)
+
+
+def _read_every_page(
+    endpoint_template: str,
+    slug: str,
+    head_sha: str,
+    token: str,
+    key: str,
+) -> list[object]:
+    all_records: list[object] = []
+    page_number = FIRST_PAGE_NUMBER
+    while True:
+        query = urllib.parse.urlencode(
+            {PER_PAGE_PARAMETER: CHECK_PAGE_SIZE, PAGE_PARAMETER: page_number}
+        )
+        all_page_records = _request_list_field(
+            endpoint_template.format(
+                api_root=GITHUB_API_ROOT, slug=slug, sha=head_sha, query=query
+            ),
+            token,
+            key,
+        )
+        all_records.extend(all_page_records)
+        if len(all_page_records) < CHECK_PAGE_SIZE:
+            return all_records
+        page_number += 1
+
+
+def _read_statuses(slug: str, head_sha: str, token: str) -> list[object]:
+    return _read_every_page(
+        COMBINED_STATUS_ENDPOINT_TEMPLATE, slug, head_sha, token, STATUSES_KEY
+    )
+
+
 def _read_unmet_checks(
     slug: str,
     head_sha: str,
     all_rules: Sequence[object],
     token: str,
 ) -> tuple[str, ...]:
-    all_statuses = _request_list_field(
-        COMBINED_STATUS_ENDPOINT_TEMPLATE.format(
-            api_root=GITHUB_API_ROOT,
-            slug=slug,
-            sha=head_sha,
-            query=urllib.parse.urlencode({PER_PAGE_PARAMETER: CHECK_PAGE_SIZE}),
-        ),
-        token,
-        STATUSES_KEY,
-    )
+    all_statuses = _read_statuses(slug, head_sha, token)
     all_unmet_checks: list[str] = []
     for each_required in required_contexts(all_rules):
         all_check_runs = _read_check_runs(slug, head_sha, each_required.context, token)
@@ -866,11 +998,22 @@ def main(all_arguments: Sequence[str]) -> int:
             )
         except MergeCheckError as failure:
             print(failure, file=sys.stderr)
+    all_unstable_checks = None
+    if all_pull_request_fields.get(MERGEABLE_STATE_KEY) == MERGEABLE_STATE_UNSTABLE:
+        try:
+            all_unstable_checks = read_unstable_checks(
+                parsed.slug,
+                str(_nested_field(all_pull_request_fields, HEAD_KEY, SHA_KEY)),
+                token,
+            )
+        except MergeCheckError as failure:
+            print(failure, file=sys.stderr)
     reason = hold_reason(
         all_pull_request_fields,
         unresolved_thread_count,
         blocked_evidence,
         is_ejected_from_merge_queue,
+        all_unstable_checks,
     )
     print(verdict_line(parsed.slug, all_pull_request_fields, reason))
     return HOLD_EXIT_CODE if reason else MERGE_EXIT_CODE

package/scripts/dev_env_scripts_constants/agent_merge_check_constants.py

@@ -38,6 +38,8 @@ COMBINED_STATUS_ENDPOINT_TEMPLATE = (
 COMPARE_ENDPOINT_TEMPLATE = "{api_root}/repos/{slug}/compare/{base}...{head}"
 CHECK_NAME_PARAMETER = "check_name"
 PER_PAGE_PARAMETER = "per_page"
+PAGE_PARAMETER = "page"
+FIRST_PAGE_NUMBER = 1
 CHECK_PAGE_SIZE = 100
 
 RULE_TYPE_KEY = "type"
@@ -101,6 +103,10 @@ FAILING_REQUIRED_CHECKS_HOLD_TEMPLATE = (
     "A required check is not passing on this head: {checks}. Read the "
     "failing check, fix it, and push."
 )
+UNSTABLE_CHECKS_HOLD_TEMPLATE = (
+    "A check on this head is not passing: {checks}. Wait for a pending "
+    "check, re-run a cancelled one, and fix a failing one."
+)
 REQUIRED_CHECK_STATE_TEMPLATE = "{context} ({state})"
 REQUIRED_CHECK_SEPARATOR = ", "
 MISSING_CHECK_STATE = "missing"

package/scripts/policy_lint/adapter_configuration.py

@@ -130,6 +130,7 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
         hooks/blocking/step_note_gate.py                 -> exempt
         hooks/blocking/reply_length_gate.py              -> exempt
         hooks/blocking/edit_marker_gate.py               -> exempt
+        hooks/blocking/verify_before_acting.py           -> exempt
         hooks/blocking/some_new_blocker.py               -> flagged
 
     The Bash PreToolUse dispatcher sits under ``blocking/`` for layout reasons
@@ -145,6 +146,9 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
     The edit marker gate keeps strikethrough and edit notes out of an edited
     chat message. It decides the shape of prose and no code or safety policy.
 
+    The verify-before-acting hook runs after a mutating call has finished. It
+    asks the model to check a hedged claim, and the call it reads stays in place.
+
     Args:
         registered_string: One command, path, script, or entrypoint string.
     """

package/scripts/policy_lint/config/constants.py

@@ -66,6 +66,7 @@ ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
     "blocking/step_note_gate.py",
     "blocking/reply_length_gate.py",
     "blocking/edit_marker_gate.py",
+    "blocking/verify_before_acting.py",
 )
 ALL_TEST_DIRECTORY_NAMES = frozenset({"tests"})
 ALL_TEST_FILE_PREFIXES = ("test_",)

package/scripts/test_agent_merge_check.py

@@ -782,3 +782,269 @@ def test_read_merge_queue_ejection_compares_failed_checks_removals_to_the_head(
         )
         is expected_ejection
     )
+
+
+PULL_REQUEST_5330_HEAD_SHA = "bd616254075d6d2bbe58acadca3d6a30bf8ee814"
+PULL_REQUEST_5330 = {
+    "number": 5330,
+    "draft": False,
+    "mergeable_state": "unstable",
+    "base": {"ref": "main"},
+    "head": {"sha": PULL_REQUEST_5330_HEAD_SHA},
+}
+COPILOT_REVIEWER_APP_ID = 946600
+PULL_REQUEST_5330_CHECK_RUNS = [
+    _check_run("Review closure", "success", run_id=110871328668),
+    _check_run("Review closure", "cancelled", run_id=110871409317),
+    _check_run("Review closure", "cancelled", run_id=110871412010),
+    _check_run("Review closure", "cancelled", run_id=110871418946),
+    _check_run("Review closure", "cancelled", run_id=110871420919),
+    _check_run("Review closure", "success", run_id=110874389252),
+    _check_run("Ruff", "cancelled", run_id=110871770000),
+    _check_run("Ruff", "success", run_id=110887099099),
+    _check_run("Tip Local green", "success", run_id=110873242269),
+    _check_run("Merge queue build verdict", "skipped", run_id=110887297809),
+    _check_run(
+        "copilot-pull-request-reviewer",
+        "success",
+        run_id=110871360430,
+        app_id=COPILOT_REVIEWER_APP_ID,
+    ),
+]
+NEWEST_REVIEW_CLOSURE_CANCELLED = [
+    *PULL_REQUEST_5330_CHECK_RUNS,
+    _check_run("Review closure", "cancelled", run_id=110890000000),
+]
+
+
+def test_superseded_cancelled_runs_leave_no_unmet_newest_check() -> None:
+    assert agent_merge_check.unmet_newest_checks(PULL_REQUEST_5330_CHECK_RUNS, []) == ()
+
+
+@pytest.mark.parametrize(
+    ("all_check_runs", "all_statuses", "expected_checks"),
+    [
+        (NEWEST_REVIEW_CLOSURE_CANCELLED, [], ("Review closure (cancelled)",)),
+        (
+            [_check_run("Ruff", None, run_id=2, status="in_progress")],
+            [],
+            ("Ruff (pending)",),
+        ),
+        (
+            [
+                _check_run("Ruff", "success", run_id=2),
+                _check_run("Ruff", "failure", run_id=5, app_id=1),
+            ],
+            [],
+            ("Ruff (failure)",),
+        ),
+        (
+            PULL_REQUEST_5330_CHECK_RUNS,
+            [
+                {"context": "local-checks", "state": "success"},
+                {"context": "Semgrep", "state": "failure"},
+            ],
+            ("Semgrep (failure)",),
+        ),
+        (
+            PULL_REQUEST_5330_CHECK_RUNS,
+            [
+                {"context": "Semgrep", "state": "success"},
+                {"context": "Semgrep", "state": "failure"},
+            ],
+            (),
+        ),
+        (
+            PULL_REQUEST_5330_CHECK_RUNS,
+            [
+                {"context": "Semgrep", "state": "pending"},
+                {"context": "Semgrep", "state": "success"},
+            ],
+            ("Semgrep (pending)",),
+        ),
+    ],
+)
+def test_unmet_newest_checks_names_each_check_whose_newest_report_is_not_passing(
+    all_check_runs: list[object],
+    all_statuses: list[object],
+    expected_checks: tuple[str, ...],
+) -> None:
+    assert (
+        agent_merge_check.unmet_newest_checks(all_check_runs, all_statuses)
+        == expected_checks
+    )
+
+
+def test_an_unstable_head_whose_newest_runs_pass_may_merge() -> None:
+    assert (
+        agent_merge_check.hold_reason(
+            _pull_request(mergeable_state="unstable"), 0, all_unstable_checks=()
+        )
+        is None
+    )
+
+
+def test_an_unstable_head_whose_newest_runs_pass_still_holds_on_an_open_thread() -> (
+    None
+):
+    reason = agent_merge_check.hold_reason(
+        _pull_request(mergeable_state="unstable"), 1, all_unstable_checks=()
+    )
+    assert reason is not None
+    assert "1 review thread" in reason
+
+
+def test_an_unstable_head_names_the_check_whose_newest_run_failed() -> None:
+    reason = agent_merge_check.hold_reason(
+        _pull_request(mergeable_state="unstable"),
+        0,
+        all_unstable_checks=("Review closure (cancelled)",),
+    )
+    assert reason is not None
+    assert "Review closure (cancelled)" in reason
+
+
+def _unstable_answers(
+    all_check_runs: list[dict[str, object]],
+    all_threads: list[object] | None = None,
+    all_statuses: list[object] | None = None,
+) -> object:
+    def _answer(url: str, token: str, all_payload_fields: object) -> object:
+        parsed = urllib.parse.urlparse(url)
+        if parsed.path.endswith("/pulls/5330"):
+            return PULL_REQUEST_5330
+        if parsed.path.endswith("/ccr/review_threads"):
+            return all_threads or []
+        if parsed.path.endswith("/graphql"):
+            return _merge_queue_document([])
+        if parsed.path.endswith("/check-runs"):
+            return {"check_runs": _requested_page(parsed.query, all_check_runs)}
+        if parsed.path.endswith("/status"):
+            return {"statuses": _requested_page(parsed.query, all_statuses or [])}
+        raise AssertionError(url)
+
+    return _answer
+
+
+def _requested_page(query: str, all_records: list[object]) -> list[object]:
+    all_parameters = urllib.parse.parse_qs(query)
+    page_size = int(all_parameters["per_page"][0])
+    page_number = int(all_parameters["page"][0])
+    first_index = (page_number - 1) * page_size
+    return all_records[first_index : first_index + page_size]
+
+
+def _run_unstable_main(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    answer: object,
+) -> tuple[int, str]:
+    monkeypatch.setenv("GH_TOKEN", "token")
+    monkeypatch.setattr(agent_merge_check, "_request_json", answer)
+    exit_code = agent_merge_check.main(["jl-cmd/claude-dev-env", "5330"])
+    return exit_code, capsys.readouterr().out
+
+
+def test_the_pull_request_5330_shape_reads_merge(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    exit_code, line = _run_unstable_main(
+        monkeypatch, capsys, _unstable_answers(PULL_REQUEST_5330_CHECK_RUNS)
+    )
+    assert exit_code == 0
+    assert line.startswith(MERGE_VERDICT_LABEL)
+    assert "bd61625" in line
+
+
+def test_a_newest_run_cancellation_on_an_unstable_head_holds(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    exit_code, line = _run_unstable_main(
+        monkeypatch, capsys, _unstable_answers(NEWEST_REVIEW_CLOSURE_CANCELLED)
+    )
+    assert exit_code == 1
+    assert line.startswith(HOLD_VERDICT_LABEL)
+    assert "Review closure (cancelled)" in line
+
+
+def test_an_unreadable_check_listing_keeps_the_generic_unstable_reason(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    routed_answer = _unstable_answers(PULL_REQUEST_5330_CHECK_RUNS)
+
+    def _answer(url: str, token: str, all_payload_fields: object) -> object:
+        if "/check-runs" in url:
+            raise agent_merge_check.MergeCheckError("HTTP Error 403: Forbidden")
+        return routed_answer(url, token, all_payload_fields)
+
+    exit_code, line = _run_unstable_main(monkeypatch, capsys, _answer)
+    assert exit_code == 1
+    assert UNSTABLE_HOLD_REASON in line
+
+
+def test_read_unstable_checks_reads_every_page_of_check_runs(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    all_passing_runs = [
+        _check_run(f"Shard {each_index}", "success", run_id=each_index)
+        for each_index in range(1, 151)
+    ]
+    all_runs_with_late_failure = [
+        *all_passing_runs,
+        _check_run("Shard 150", "failure", run_id=151),
+    ]
+    monkeypatch.setattr(
+        agent_merge_check,
+        "_request_json",
+        _unstable_answers(all_runs_with_late_failure),
+    )
+    assert agent_merge_check.read_unstable_checks(
+        "jl-cmd/claude-dev-env", PULL_REQUEST_5330_HEAD_SHA, "token"
+    ) == ("Shard 150 (failure)",)
+
+
+def test_read_unstable_checks_reads_every_page_of_commit_statuses(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    all_statuses_with_late_failure = [
+        *(
+            {"context": f"Gate {each_index}", "state": "success"}
+            for each_index in range(1, 121)
+        ),
+        {"context": "Gate 121", "state": "failure"},
+    ]
+    monkeypatch.setattr(
+        agent_merge_check,
+        "_request_json",
+        _unstable_answers(
+            PULL_REQUEST_5330_CHECK_RUNS,
+            all_statuses=all_statuses_with_late_failure,
+        ),
+    )
+    assert agent_merge_check.read_unstable_checks(
+        "jl-cmd/claude-dev-env", PULL_REQUEST_5330_HEAD_SHA, "token"
+    ) == ("Gate 121 (failure)",)
+
+
+def test_an_unstable_head_with_no_reported_check_keeps_the_generic_hold(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    exit_code, line = _run_unstable_main(monkeypatch, capsys, _unstable_answers([]))
+    assert exit_code == 1
+    assert UNSTABLE_HOLD_REASON in line
+
+
+def test_read_unstable_checks_reports_nothing_read_for_an_empty_head(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(agent_merge_check, "_request_json", _unstable_answers([]))
+    assert (
+        agent_merge_check.read_unstable_checks(
+            "jl-cmd/claude-dev-env", PULL_REQUEST_5330_HEAD_SHA, "token"
+        )
+        is None
+    )

package/scripts/tests/test_adapter_configuration.py

@@ -74,6 +74,14 @@ def test_new_edit_marker_gate_registration_is_clean(tmp_path: Path) -> None:
     assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
 
 
+def test_new_verify_before_acting_registration_is_clean(tmp_path: Path) -> None:
+    current_document = _hook_document(
+        ["hooks/blocking/verify_before_acting.py"],
+        '{"hooks": {}}',
+    )
+    assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
+
+
 def test_new_blocker_in_staged_change_is_rejected(tmp_path: Path) -> None:
     current_document = _hook_document(
         ["hooks/blocking/new.py"],