claude-dev-env 8.18.0 → 8.19.1

package/rules/review-closure-is-a-check.md

@@ -4,7 +4,7 @@
 
 ## Rule
 
-A review finding on the head is answered before the pull request merges. The agent driving it replies, pushes the fix, or both. The check named `Review closure` reads that state on every push and on every review event, and reports red while a finding waits.
+A review finding on the head is answered before the pull request merges. The agent driving it replies, pushes the fix, or both. The check named `Review closure` reads that state on every push, on every review event, and on every top-level comment, and reports red while a finding waits.
 
 One command prints the same verdict:
 
@@ -24,6 +24,7 @@ It prints `CLOSED` and exits 0 when every finding on the head is answered. It pr
 | A red-circle finding | A reply from the driving account, or a push that replaced the code |
 | A thread the driving account opened | Itself |
 | A blocking `Claude Approvals` row | A push, which moves the head the check reports on |
+| A top-level comment on the pull request | A later top-level comment from the driving account |
 
 A red circle marks a finding a review states as blocking, so resolution in silence leaves it open. The reply says what changed or why the finding stands, and the reviewer reads it beside the diff.
 
@@ -31,7 +32,9 @@ The driving account is the one that opened the pull request. Where the agent com
 
 ## Where the check runs
 
-`.github/workflows/review-closure.yml` runs it here on a push to a pull request, on a submitted or dismissed review, and on a review comment. Each run reports on the pull request's head commit, so a finding posted after the last push still turns the check red.
+`.github/workflows/review-closure.yml` runs it here on a push to a pull request, on a submitted or dismissed review, on a review comment, and on a top-level comment posted or edited on a pull request. Each run reports on the pull request's head commit, so a finding posted after the last push still turns the check red.
+
+A top-level comment arrives as an `issue_comment` event, and a run on that event belongs to the default branch commit. The comment job reads the pull request's head, runs the same command, and posts the verdict on that head through the Checks API as a `Review closure` check run. The token belongs to the GitHub Actions app, so that check run carries the same name and app as the pull request job's own, and the newest one on the head is the one branch rules read.
 
 A private repository that installs this package runs the same command from its own workflow, against the revision of this package that its workflow pins.
 

package/scripts/dev_env_scripts_constants/review_closure_constants.py

@@ -234,8 +234,33 @@ REVIEW_COMMENTS_ENDPOINT_TEMPLATE: str = (
 )
 """REST route carrying one page of a pull request's review comments."""
 
-REVIEW_COMMENT_PAGE_SIZE: int = 100
-"""How many review comments one page carries."""
+COMMENT_PAGE_SIZE: int = 100
+"""How many review or top-level comments one page carries."""
 
-MAX_REVIEW_COMMENT_PAGES: int = 20
-"""How many comment pages one run reads before it stops."""
+MAX_COMMENT_PAGES: int = 20
+"""How many comment pages one listing reads before it stops."""
+
+TOP_LEVEL_COMMENTS_ENDPOINT_TEMPLATE: str = (
+    "{api_root}/repos/{slug}/issues/{number}/comments?per_page={page_size}&page={page}"
+)
+"""REST route carrying one page of a pull request's top-level comments."""
+
+HTML_URL_KEY: str = "html_url"
+"""Field carrying the page address of a top-level comment."""
+
+CREATED_AT_KEY: str = "created_at"
+"""Field carrying when a top-level comment was posted."""
+
+UPDATED_AT_KEY: str = "updated_at"
+"""Field carrying when a top-level comment was last edited."""
+
+TOP_LEVEL_OPEN_REASON_TEMPLATE: str = (
+    "a top-level comment from {author} with no later top-level comment from "
+    "the driving agent"
+)
+"""Why a top-level comment stays open until the agent posts after it."""
+
+UNREADABLE_TOP_LEVEL_COMMENT_TEMPLATE: str = (
+    "a top-level comment carries an unreadable timestamp: {record}"
+)
+"""What to report when a top-level comment's timestamps do not parse."""

package/scripts/policy_lint/adapter_configuration.py

@@ -127,12 +127,16 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
     ::
 
         hooks/blocking/bash_pre_tool_use_dispatcher.py   -> exempt
+        hooks/blocking/step_note_gate.py                 -> exempt
         hooks/blocking/some_new_blocker.py               -> flagged
 
     The Bash PreToolUse dispatcher sits under ``blocking/`` for layout reasons
     while its roster hosts one allow-and-rewrite hook. Its path segment reads as
     a policy boundary that the chain never carries.
 
+    The step-note gate allows every call until the user runs ``/step-notes on``.
+    It asks for a readable status line and decides no code or safety policy.
+
     Args:
         registered_string: One command, path, script, or entrypoint string.
     """

package/scripts/policy_lint/config/constants.py

@@ -63,6 +63,7 @@ ALL_ACTION_BOUNDARY_SEGMENTS = frozenset(
 ALL_ACTION_BOUNDARY_PREFIXES = ("deny_", "block_", "ask_")
 ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
     "blocking/bash_pre_tool_use_dispatcher.py",
+    "blocking/step_note_gate.py",
 )
 ALL_TEST_DIRECTORY_NAMES = frozenset({"tests"})
 ALL_TEST_FILE_PREFIXES = ("test_",)

package/scripts/review_closure.py

@@ -7,8 +7,9 @@
     CLOSED jl-cmd/claude-dev-env#1442 ab845eb :: every review finding on this
     commit is answered
 
-A finding waits until the agent driving the pull request replies to it or
-pushes the fix. Exit status is 0 for CLOSED, 1 for OPEN, and 2 when the pull
+A finding is a review thread, a top-level comment on the pull request, or a
+blocking Claude Approvals row. It waits until the agent driving the pull
+request replies to it or pushes the fix. Exit status is 0 for CLOSED, 1 for OPEN, and 2 when the pull
 request state could not be read.
 """
 
@@ -35,6 +36,7 @@ from review_closure_github import (
     read_approvals_conclusion,
     read_pull_request,
     read_review_threads,
+    read_top_level_comments,
 )
 from review_closure_model import (
     OpenFinding,
@@ -93,6 +95,7 @@ def closure_report(
     all_pull_request_fields = read_pull_request(slug, number, token)
     all_findings = all_open_findings(
         read_review_threads(slug, number, token),
+        read_top_level_comments(slug, number, token),
         driver_logins(all_pull_request_fields, all_extra_logins),
         read_approvals_conclusion(slug, head_sha(all_pull_request_fields), token),
     )

package/scripts/review_closure_github.py

@@ -1,12 +1,13 @@
 """Read from GitHub what the review closure verdict rests on.
 
-Three reads answer one pull request: the pull request itself, its review
-threads, and the check runs on its head commit.
+Four reads answer one pull request: the pull request itself, its review
+threads, its top-level comments, and the check runs on its head commit.
 
 ::
 
     read_pull_request("jl-cmd/claude-dev-env", 1442, token)
     read_review_threads("jl-cmd/claude-dev-env", 1442, token)
+    read_top_level_comments("jl-cmd/claude-dev-env", 1442, token)
     read_approvals_conclusion("jl-cmd/claude-dev-env", "ab845eb", token)
 
 Two routes carry the review threads. A Claude Code session reaches GitHub
@@ -30,10 +31,11 @@ from dev_env_scripts_constants.review_closure_constants import (
     CHECK_RUN_PAGE_SIZE,
     CHECK_RUNS_ENDPOINT_TEMPLATE,
     CHECK_RUNS_KEY,
+    COMMENT_PAGE_SIZE,
     GET_METHOD,
     GITHUB_API_ROOT,
     GITHUB_GRAPHQL_ENDPOINT,
-    MAX_REVIEW_COMMENT_PAGES,
+    MAX_COMMENT_PAGES,
     NAME_VARIABLE,
     NO_SIGN_IN_MESSAGE,
     NUMBER_VARIABLE,
@@ -44,12 +46,13 @@ from dev_env_scripts_constants.review_closure_constants import (
     QUERY_KEY,
     REQUEST_FAILED_TEMPLATE,
     REQUEST_TIMEOUT_SECONDS,
-    REVIEW_COMMENT_PAGE_SIZE,
     REVIEW_COMMENTS_ENDPOINT_TEMPLATE,
     REVIEW_THREAD_PAGE_SIZE,
     REVIEW_THREAD_QUERY,
     REVIEW_THREADS_ENDPOINT_TEMPLATE,
     SLUG_SEPARATOR,
+    TOP_LEVEL_COMMENTS_ENDPOINT_TEMPLATE,
+    UNREADABLE_TOP_LEVEL_COMMENT_TEMPLATE,
     VARIABLES_KEY,
 )
 from pr_verification.config.constants import (
@@ -67,9 +70,11 @@ from pr_verification.config.constants import (
 from pr_verification.github_parsing import GitHubError
 from review_closure_model import (
     ReviewThread,
+    TopLevelComment,
     approvals_conclusion,
     comment_records_by_id,
     parse_thread,
+    parse_top_level_comment,
 )
 
 
@@ -191,23 +196,72 @@ def read_review_comments_by_id(
     Raises:
         GitHubError: A page answered with something other than a list.
     """
+    return comment_records_by_id(
+        _all_listed_records(REVIEW_COMMENTS_ENDPOINT_TEMPLATE, slug, number, token)
+    )
+
+
+def read_top_level_comments(
+    slug: str, number: int, token: str
+) -> tuple[TopLevelComment, ...]:
+    """Read every top-level comment on a pull request.
+
+    Args:
+        slug: The repository as ``owner/name``.
+        number: The pull request number.
+        token: The GitHub token the request authenticates with.
+
+    Returns:
+        Each comment posted on the pull request itself, outside any review
+        thread.
+
+    Raises:
+        GitHubError: A page answered with something other than a list, or a
+            comment carried a timestamp that does not parse.
+    """
+    all_records = _all_listed_records(
+        TOP_LEVEL_COMMENTS_ENDPOINT_TEMPLATE, slug, number, token
+    )
+    return tuple(
+        _parsed_top_level_comment(each_record)
+        for each_record in all_records
+        if isinstance(each_record, Mapping)
+    )
+
+
+def _parsed_top_level_comment(
+    all_comment_fields: Mapping[str, object],
+) -> TopLevelComment:
+    try:
+        return parse_top_level_comment(all_comment_fields)
+    except ValueError as failure:
+        raise GitHubError(
+            UNREADABLE_TOP_LEVEL_COMMENT_TEMPLATE.format(record=all_comment_fields)
+        ) from failure
+
+
+def _all_listed_records(
+    endpoint_template: str, slug: str, number: int, token: str
+) -> list[object]:
     all_records: list[object] = []
-    for each_page in range(1, MAX_REVIEW_COMMENT_PAGES + 1):
-        page = _review_comment_page(slug, number, token, each_page)
+    for each_page in range(1, MAX_COMMENT_PAGES + 1):
+        page = _listing_page(endpoint_template, slug, number, token, each_page)
         all_records.extend(page)
-        if len(page) < REVIEW_COMMENT_PAGE_SIZE:
+        if len(page) < COMMENT_PAGE_SIZE:
             break
-    return comment_records_by_id(all_records)
+    return all_records
 
 
-def _review_comment_page(slug: str, number: int, token: str, page: int) -> list[object]:
+def _listing_page(
+    endpoint_template: str, slug: str, number: int, token: str, page: int
+) -> list[object]:
     document = request_json(
         GET_METHOD,
-        REVIEW_COMMENTS_ENDPOINT_TEMPLATE.format(
+        endpoint_template.format(
             api_root=GITHUB_API_ROOT,
             slug=slug,
             number=number,
-            page_size=REVIEW_COMMENT_PAGE_SIZE,
+            page_size=COMMENT_PAGE_SIZE,
             page=page,
         ),
         token,

package/scripts/review_closure_model.py

@@ -2,7 +2,8 @@
 
 A review bot posts a finding, the agent driving the pull request answers it or
 pushes the fix, and the thread closes. Until then the finding waits. These
-functions read the threads and the approvals conclusion, and name what waits.
+functions read the review threads, the top-level comments on the pull request,
+and the approvals conclusion, and name what waits.
 
 ::
 
@@ -10,6 +11,9 @@ functions read the threads and the approvals conclusion, and name what waits.
     thread: a bot comment, then an agent reply  -> closed
     thread: a bot comment, code since replaced  -> closed
     thread: a red circle, resolved in silence   -> open
+    top-level: a bot comment, no agent comment  -> open
+    top-level: a bot comment, then an agent one -> closed
+    top-level: the bot edits after that reply   -> open
 
 A red circle marks a finding a review states as blocking, so resolution alone
 leaves it open. The reply says what changed, or why the finding stands.
@@ -19,6 +23,7 @@ from __future__ import annotations
 
 from collections.abc import Iterable, Mapping, Sequence
 from dataclasses import dataclass
+from datetime import datetime
 
 from dev_env_scripts_constants.review_closure_constants import (
     ALL_BLOCKING_CONCLUSIONS,
@@ -37,7 +42,9 @@ from dev_env_scripts_constants.review_closure_constants import (
     COMMENT_IDENTIFIER_KEY,
     COMMENT_IDS_KEY,
     COMMENT_NODES_KEY,
+    CREATED_AT_KEY,
     HEAD_KEY,
+    HTML_URL_KEY,
     NUMBER_KEY,
     OPEN_DETAIL_TEMPLATE,
     OPEN_VERDICT_LABEL,
@@ -46,8 +53,10 @@ from dev_env_scripts_constants.review_closure_constants import (
     SHA_KEY,
     SHORT_SHA_LENGTH,
     THREAD_PATH_KEY,
+    TOP_LEVEL_OPEN_REASON_TEMPLATE,
     UNANSWERED_OPEN_REASON,
     UNNAMED_THREAD_SUBJECT,
+    UPDATED_AT_KEY,
     USER_KEY,
     VERDICT_LINE_TEMPLATE,
 )
@@ -71,6 +80,17 @@ class ReviewThread:
     all_comments: tuple[ReviewComment, ...]
 
 
+@dataclass(frozen=True)
+class TopLevelComment:
+    """One comment on the pull request itself, outside any review thread."""
+
+    identifier: object
+    author_login: str
+    created_at: datetime
+    updated_at: datetime
+    url: str
+
+
 @dataclass(frozen=True)
 class OpenFinding:
     """One finding that still waits on the agent driving the pull request."""
@@ -150,8 +170,91 @@ def thread_finding(
     return OpenFinding(subject=thread.subject, reason=UNANSWERED_OPEN_REASON)
 
 
+def latest_driver_comment_time(
+    all_comments: Iterable[TopLevelComment],
+    all_driver_logins: frozenset[str],
+) -> datetime | None:
+    """Find when the driving agent last posted a top-level comment.
+
+    Args:
+        all_comments: The top-level comments on the pull request.
+        all_driver_logins: The logins that count as the driving agent.
+
+    Returns:
+        The creation time of the driving agent's latest top-level comment, or
+        None when it posted none.
+    """
+    return max(
+        (
+            each_comment.created_at
+            for each_comment in all_comments
+            if each_comment.author_login in all_driver_logins
+        ),
+        default=None,
+    )
+
+
+def top_level_finding(
+    comment: TopLevelComment,
+    all_driver_logins: frozenset[str],
+    latest_driver_time: datetime | None,
+) -> OpenFinding | None:
+    """Decide whether one top-level comment still waits on the driving agent.
+
+    Args:
+        comment: The top-level comment to judge.
+        all_driver_logins: The logins whose comments count as the answer.
+        latest_driver_time: When the driving agent last posted a top-level
+            comment, or None when it posted none.
+
+    Returns:
+        The finding this comment leaves open, or None when it is answered.
+    """
+    if comment.author_login in all_driver_logins:
+        return None
+    if latest_driver_time is not None and comment.updated_at <= latest_driver_time:
+        return None
+    return OpenFinding(
+        subject=comment.url,
+        reason=TOP_LEVEL_OPEN_REASON_TEMPLATE.format(author=comment.author_login),
+    )
+
+
+def top_level_findings(
+    all_comments: Iterable[TopLevelComment],
+    all_driver_logins: frozenset[str],
+) -> tuple[OpenFinding, ...]:
+    """Decide which top-level comments still wait on the driving agent.
+
+    The driving agent answers a top-level comment by posting a top-level
+    comment of its own. Its latest one answers every comment last touched
+    before it, and a comment edited after it waits again.
+
+    Args:
+        all_comments: The top-level comments on the pull request.
+        all_driver_logins: The logins whose comments count as the answer.
+
+    Returns:
+        One finding per comment from another account that was posted or
+        edited after the driving agent's latest top-level comment.
+    """
+    all_listed_comments = tuple(all_comments)
+    latest_driver_time = latest_driver_comment_time(
+        all_listed_comments, all_driver_logins
+    )
+    return tuple(
+        each_finding
+        for each_finding in (
+            top_level_finding(each_comment, all_driver_logins, latest_driver_time)
+            for each_comment in all_listed_comments
+        )
+        if each_finding is not None
+    )
+
+
 def all_open_findings(
     all_threads: Iterable[ReviewThread],
+    all_top_level_comments: Iterable[TopLevelComment],
     all_driver_logins: frozenset[str],
     approvals_conclusion_text: str | None,
 ) -> tuple[OpenFinding, ...]:
@@ -159,13 +262,15 @@ def all_open_findings(
 
     Args:
         all_threads: The review threads on the pull request.
+        all_top_level_comments: The comments on the pull request itself.
         all_driver_logins: The logins whose comments count as the answer.
         approvals_conclusion_text: What the Claude Approvals check run on the
             head concluded, or None where that check does not run.
 
     Returns:
-        One finding per open review thread, then the approvals finding when
-        that check reports a blocking row on this commit.
+        One finding per open review thread, then one per waiting top-level
+        comment, then the approvals finding when that check reports a
+        blocking row on this commit.
     """
     all_findings = [
         each_finding
@@ -175,6 +280,7 @@ def all_open_findings(
         )
         if each_finding is not None
     ]
+    all_findings.extend(top_level_findings(all_top_level_comments, all_driver_logins))
     if approvals_conclusion_text in ALL_BLOCKING_CONCLUSIONS:
         all_findings.append(
             OpenFinding(subject=APPROVALS_CHECK_NAME, reason=APPROVALS_OPEN_REASON)
@@ -301,6 +407,29 @@ def comment_records_by_id(
     }
 
 
+def parse_top_level_comment(
+    all_comment_fields: Mapping[str, object],
+) -> TopLevelComment:
+    """Read one top-level comment from the REST answer.
+
+    Args:
+        all_comment_fields: The comment as the issue comments route reports it.
+
+    Returns:
+        The comment in the shape the closure decision reads.
+
+    Raises:
+        ValueError: A timestamp is missing or does not parse.
+    """
+    return TopLevelComment(
+        identifier=all_comment_fields.get(COMMENT_IDENTIFIER_KEY),
+        author_login=_comment_author_login(all_comment_fields),
+        created_at=datetime.fromisoformat(str(all_comment_fields.get(CREATED_AT_KEY))),
+        updated_at=datetime.fromisoformat(str(all_comment_fields.get(UPDATED_AT_KEY))),
+        url=str(all_comment_fields.get(HTML_URL_KEY) or ""),
+    )
+
+
 def approvals_conclusion(all_check_runs: Iterable[object]) -> str | None:
     """Find what the Claude Approvals check reports on a commit.
 

package/scripts/tests/test_adapter_configuration.py

@@ -50,6 +50,14 @@ def test_new_bash_pre_tool_use_dispatcher_registration_is_clean(tmp_path: Path)
     assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
 
 
+def test_new_step_note_gate_registration_is_clean(tmp_path: Path) -> None:
+    current_document = _hook_document(
+        ["hooks/blocking/step_note_gate.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"],

package/scripts/tests/test_review_closure.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import sys
+from datetime import datetime
 from pathlib import Path
 
 import pytest
@@ -51,10 +52,14 @@ def stub_reads(
     monkeypatch: pytest.MonkeyPatch,
     all_threads: tuple[model.ReviewThread, ...],
     conclusion: str | None = "success",
+    all_top_level_comments: tuple[model.TopLevelComment, ...] = (),
 ) -> None:
     monkeypatch.setattr(command, "github_token", lambda: "a-token")
     monkeypatch.setattr(command, "read_pull_request", lambda *_: PULL_REQUEST)
     monkeypatch.setattr(command, "read_review_threads", lambda *_: all_threads)
+    monkeypatch.setattr(
+        command, "read_top_level_comments", lambda *_: all_top_level_comments
+    )
     monkeypatch.setattr(command, "read_approvals_conclusion", lambda *_: conclusion)
 
 
@@ -124,3 +129,23 @@ def should_exit_two_when_the_state_could_not_be_read(
 
     assert status == 2
     assert "refused" in capsys.readouterr().err
+
+
+def should_print_the_url_of_a_waiting_top_level_comment(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    summary_url = "https://github.com/jl-cmd/claude-dev-env/pull/7#issuecomment-1"
+    posted = datetime.fromisoformat("2026-09-26T12:00:00+00:00")
+    bot_summary = model.TopLevelComment(
+        identifier=1,
+        author_login="qodo-merge-pro[bot]",
+        created_at=posted,
+        updated_at=posted,
+        url=summary_url,
+    )
+    stub_reads(monkeypatch, (answered_thread(),), all_top_level_comments=(bot_summary,))
+
+    status = command.main([SLUG, "7"])
+
+    assert status == 1
+    assert summary_url in capsys.readouterr().out

package/scripts/tests/test_review_closure_github.py

@@ -238,3 +238,54 @@ def should_report_a_check_run_answer_of_the_wrong_shape(
 
     with pytest.raises(GitHubError):
         reader.read_approvals_conclusion("jl-cmd/claude-dev-env", "ab845eb", TOKEN)
+
+
+def top_level_record(identifier: int) -> dict[str, object]:
+    return {
+        "id": identifier,
+        "user": {"login": "qodo-merge-pro[bot]"},
+        "created_at": "2026-09-26T12:00:00Z",
+        "updated_at": "2026-09-26T12:00:00Z",
+        "html_url": (
+            f"https://github.com/jl-cmd/claude-dev-env/pull/7#issuecomment-{identifier}"
+        ),
+    }
+
+
+def should_read_the_second_page_of_top_level_comments(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    all_requested_urls = answer_with(
+        monkeypatch,
+        {
+            "issues/7/comments?per_page=100&page=1": (
+                200,
+                [top_level_record(each) for each in range(100)],
+            ),
+            "issues/7/comments?per_page=100&page=2": (200, [top_level_record(100)]),
+        },
+    )
+
+    all_comments = reader.read_top_level_comments("jl-cmd/claude-dev-env", 7, TOKEN)
+
+    assert len(all_comments) == 101
+    assert all_comments[-1].identifier == 100
+    assert len(all_requested_urls) == 2
+
+
+def should_report_a_top_level_comment_page_of_the_wrong_shape(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    answer_with(monkeypatch, {"issues/7/comments": (200, {"message": "not a list"})})
+
+    with pytest.raises(GitHubError):
+        reader.read_top_level_comments("jl-cmd/claude-dev-env", 7, TOKEN)
+
+
+def should_report_a_top_level_comment_without_timestamps(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    answer_with(monkeypatch, {"issues/7/comments": (200, [{"id": 1}])})
+
+    with pytest.raises(GitHubError):
+        reader.read_top_level_comments("jl-cmd/claude-dev-env", 7, TOKEN)