claude-dev-env 8.6.1 → 8.7.0

package/scripts/codex_compat_materializer.py

@@ -27,7 +27,8 @@ publish_plan_max_positional_arguments = 3
 publish_plan_failure_injector_position = 2
 frontmatter_unsupported_fields = ("tools", "model", "color", "disable-model-invocation")
 instruction_alias_filenames = frozenset({"AGENTS.md", "CLAUDE.md"})
-failure_blast_radius_rule_relative_path = "rules/failure-blast-radius.md"
+codex_instruction_rule_relative_paths = ("rules/failure-blast-radius.md", "rules/correction-lens.md")
+codex_instruction_source_separator = ", "
 codex_instruction_target_path = "AGENTS.md"
 codex_instruction_section_heading = "## Excerpt for repository-instruction sessions"
 codex_hook_manifest_source_path = "hooks/hooks.json"
@@ -502,41 +503,57 @@ def convert_agent(agent: ClaudeAgent) -> str:
     return content
 
 
-def render_codex_failure_blast_radius(rule_content: str) -> str:
-    """Extract the repository-instruction contract from the canonical rule.
+def render_codex_instruction_excerpt(rule_content: str, rule_relative_path: str) -> str:
+    """Extract one rule's repository-instruction contract.
+
+    A rule reaches a Codex session through the fenced block under its
+    "Excerpt for repository-instruction sessions" heading, and this returns
+    that block's own text.
 
     Args:
-        rule_content: Canonical failure blast-radius rule text.
+        rule_content: Canonical rule text.
+        rule_relative_path: Repository-relative path of that rule, named in errors.
 
     Returns:
         The fenced repository-instruction excerpt with a trailing newline.
 
     Raises:
-        MaterializerError: If the canonical rule lacks the required excerpt.
+        MaterializerError: If the rule lacks a complete excerpt.
     """
     heading_start = rule_content.find(codex_instruction_section_heading)
     if heading_start < 0:
-        raise MaterializerError("failure blast-radius rule requires a Codex excerpt")
+        raise MaterializerError(f"{rule_relative_path} requires a Codex excerpt")
     fence_start = rule_content.find("```", heading_start)
     if fence_start < 0:
-        raise MaterializerError("failure blast-radius rule requires a Codex excerpt")
+        raise MaterializerError(f"{rule_relative_path} requires a Codex excerpt")
     content_start = rule_content.find(line_separator, fence_start)
     fence_end = rule_content.find(line_separator + "```", content_start + 1)
     if content_start < 0 or fence_end < 0:
-        raise MaterializerError("failure blast-radius rule requires a complete Codex excerpt")
+        raise MaterializerError(f"{rule_relative_path} requires a complete Codex excerpt")
     return rule_content[content_start + len(line_separator) : fence_end].rstrip() + line_separator
 
 
 def _build_codex_instruction_projection(config: MaterializerConfig) -> PlannedFile | None:
-    """Build the managed AGENTS.md projection when the canonical rule is present."""
-    source_path = config.source_root / failure_blast_radius_rule_relative_path
-    if not source_path.exists() and not _is_reparse_point(source_path):
+    """Build the managed AGENTS.md projection from every projected rule present."""
+    all_present_rules: list[tuple[str, str]] = []
+    for each_relative_path in codex_instruction_rule_relative_paths:
+        candidate_path = config.source_root / each_relative_path
+        if not candidate_path.exists() and not _is_reparse_point(candidate_path):
+            continue
+        source_path = _validated_source_file(config, each_relative_path, each_relative_path)
+        rule_content = source_path.read_text(encoding="utf-8")
+        all_present_rules.append(
+            (each_relative_path, render_codex_instruction_excerpt(rule_content, each_relative_path))
+        )
+    if not all_present_rules:
         return None
-    source_path = _validated_source_file(config, failure_blast_radius_rule_relative_path, "failure blast-radius rule")
-    rule_content = source_path.read_text(encoding="utf-8")
-    projected_content = render_codex_failure_blast_radius(rule_content)
+    projected_content = line_separator.join(
+        each_excerpt for _, each_excerpt in all_present_rules
+    )
     return PlannedFile(
-        failure_blast_radius_rule_relative_path,
+        codex_instruction_source_separator.join(
+            each_path for each_path, _ in all_present_rules
+        ),
         codex_instruction_target_path,
         projected_content,
         hash_content(projected_content),
@@ -987,7 +1004,7 @@ def discover_agents(config: MaterializerConfig) -> list[ClaudeAgent]:
         if _is_reparse_point(each_path):
             raise MaterializerError(f"source reparse point is not allowed: {each_path}")
         relative_source = each_path.relative_to(config.source_root).as_posix()
-        if relative_source == failure_blast_radius_rule_relative_path:
+        if relative_source in codex_instruction_rule_relative_paths:
             _validate_containment(config.source_root, each_path)
             continue
         _validate_containment(config.source_root, each_path)

package/scripts/contrast_framing.py

@@ -0,0 +1,101 @@
+"""Find contrast framing in authored prose.
+
+A contrast defines its subject against a rejected alternative, so the reader
+carries two readings where one would do.
+
+::
+
+    all_hits = find_contrast_framing("A diff regression, not shared code.")
+    ok:   all_hits == [(1, 18, "trailing-comma-not")]
+    flag: find_contrast_framing("The function runs more than 30 lines.") == []
+
+Code spans, fenced blocks, paths, and link targets are blanked before the
+patterns run, so an example quoted in backticks stays quiet. A blockquote line
+is skipped, since it carries someone else's words. A comma-``not`` match
+reports only when no bare ``not`` already sits earlier in the line, so a
+second one in a list stays quiet, and a list that opens with ``not`` keeps
+even its first comma quiet. The pattern list lives in the constants module
+beside this one, and the durable post linter reads the same list.
+"""
+
+from __future__ import annotations
+
+import re
+
+from banned_prose_words import prose_lines
+from dev_env_scripts_constants.contrast_framing_constants import (
+    ALL_CONTRAST_FRAMING_FORMS,
+    CONTRAST_FRAMING_MESSAGE_TEMPLATE,
+    CONTRAST_FRAMING_QUOTED_LINE_LIMIT,
+    ContrastFramingForm,
+)
+
+_BARE_NOT = re.compile(r"\bnot\b", re.IGNORECASE)
+
+
+def _reports(form: ContrastFramingForm, prose_line: str, match_start: int) -> bool:
+    if not form.repeats_as_a_list:
+        return True
+    return _BARE_NOT.search(prose_line[:match_start]) is None
+
+
+def _line_hits(line_number: int, prose_line: str) -> list[tuple[int, int, str]]:
+    if prose_line.lstrip().startswith(">"):
+        return []
+    return [
+        (line_number, each_match.start() + 1, each_form.name)
+        for each_form in ALL_CONTRAST_FRAMING_FORMS
+        for each_match in each_form.pattern.finditer(prose_line)
+        if _reports(each_form, prose_line, each_match.start())
+    ]
+
+
+def find_contrast_framing(document_text: str) -> list[tuple[int, int, str]]:
+    """Return each contrast-framing occurrence in authored prose.
+
+    Args:
+        document_text: Full document source.
+
+    Returns:
+        Ordered ``(line number, column, form name)`` triples, both 1-based.
+    """
+    all_hits: list[tuple[int, int, str]] = []
+    for each_line_number, each_prose_line in enumerate(prose_lines(document_text), 1):
+        all_hits.extend(_line_hits(each_line_number, each_prose_line))
+    return sorted(all_hits)
+
+
+def form_named(form_name: str) -> ContrastFramingForm:
+    """Return the contrast form carrying one name.
+
+    Args:
+        form_name: Name reported by ``find_contrast_framing``.
+
+    Returns:
+        The matching form.
+
+    Raises:
+        KeyError: If no form carries that name.
+    """
+    for each_form in ALL_CONTRAST_FRAMING_FORMS:
+        if each_form.name == form_name:
+            return each_form
+    raise KeyError(form_name)
+
+
+def describe_contrast_framing(source_line: str, form_name: str) -> str:
+    """Return the reader-facing message for one occurrence.
+
+    Args:
+        source_line: The document line the occurrence sits on.
+        form_name: Name of the form that matched.
+
+    Returns:
+        The message naming the form, the line it sits on, and the fix.
+    """
+    matched_form = form_named(form_name)
+    return CONTRAST_FRAMING_MESSAGE_TEMPLATE.format(
+        name=form_name,
+        text=source_line.strip()[:CONTRAST_FRAMING_QUOTED_LINE_LIMIT],
+        guidance=matched_form.guidance,
+    )

package/scripts/dev_env_scripts_constants/agent_merge_check_constants.py

@@ -0,0 +1,121 @@
+"""Named constants for agent_merge_check, the agent merge check."""
+
+from __future__ import annotations
+
+GITHUB_API_ROOT = "https://api.github.com"
+GITHUB_GRAPHQL_ENDPOINT = "https://api.github.com/graphql"
+PULL_REQUEST_ENDPOINT_TEMPLATE = "{api_root}/repos/{slug}/pulls/{number}"
+REVIEW_THREADS_ENDPOINT_TEMPLATE = (
+    "{api_root}/repos/{slug}/pulls/{number}/ccr/review_threads"
+)
+ACCEPT_HEADER = "Accept"
+GITHUB_ACCEPT_TYPE = "application/vnd.github+json"
+AUTHORIZATION_HEADER = "Authorization"
+BEARER_PREFIX = "Bearer "
+CONTENT_TYPE_HEADER = "Content-Type"
+JSON_CONTENT_TYPE = "application/json"
+UTF8_ENCODING = "utf-8"
+REQUEST_TIMEOUT_SECONDS = 30
+
+ALL_TOKEN_ENVIRONMENT_VARIABLES = ("GH_TOKEN", "GITHUB_TOKEN")
+
+DRAFT_KEY = "draft"
+MERGEABLE_STATE_KEY = "mergeable_state"
+NUMBER_KEY = "number"
+TITLE_KEY = "title"
+HEAD_KEY = "head"
+SHA_KEY = "sha"
+
+MERGEABLE_STATE_CLEAN = "clean"
+MERGEABLE_STATE_BEHIND = "behind"
+MERGEABLE_STATE_DIRTY = "dirty"
+MERGEABLE_STATE_BLOCKED = "blocked"
+MERGEABLE_STATE_UNSTABLE = "unstable"
+MERGEABLE_STATE_UNKNOWN = "unknown"
+SETTLE_ATTEMPT_COUNT = 5
+SETTLE_WAIT_SECONDS = 3
+
+DRAFT_HOLD_REASON = (
+    "The pull request is a draft, so it carries no verdict to merge on. "
+    "Mark it ready once its checks pass."
+)
+BEHIND_HOLD_REASON = (
+    "The head is behind the base branch and the branch rule requires an "
+    "up-to-date head. Merge the base branch into this one and push."
+)
+DIRTY_HOLD_REASON = (
+    "The head conflicts with the base branch. Merge the base branch into "
+    "this one, resolve the conflict, and push."
+)
+BLOCKED_HOLD_REASON = (
+    "A required status check is not passing on this head. Read the failing "
+    "check, fix it, and push."
+)
+UNSTABLE_HOLD_REASON = (
+    "A check on this head is failing or still running. Wait for it, and fix "
+    "it when it comes back red."
+)
+ALL_HOLD_REASONS_BY_STATE = {
+    MERGEABLE_STATE_BEHIND: BEHIND_HOLD_REASON,
+    MERGEABLE_STATE_DIRTY: DIRTY_HOLD_REASON,
+    MERGEABLE_STATE_BLOCKED: BLOCKED_HOLD_REASON,
+    MERGEABLE_STATE_UNSTABLE: UNSTABLE_HOLD_REASON,
+}
+UNKNOWN_STATE_HOLD_TEMPLATE = (
+    "GitHub reports the merge state as {state}, which this check does not "
+    "treat as ready. Read the pull request page."
+)
+UNRESOLVED_THREADS_HOLD_TEMPLATE = (
+    "{count} review thread(s) are open. Answer each one and resolve it."
+)
+
+MERGE_VERDICT_LABEL = "MERGE"
+HOLD_VERDICT_LABEL = "HOLD"
+VERDICT_LINE_TEMPLATE = "{label} {slug}#{number} {sha} :: {detail}"
+SHORT_SHA_LENGTH = 7
+READY_DETAIL = "green, no open review thread, ready for the agent to merge"
+
+MERGE_EXIT_CODE = 0
+HOLD_EXIT_CODE = 1
+ERROR_EXIT_CODE = 2
+
+NO_SIGN_IN_MESSAGE = "No GitHub token in the environment. Set GH_TOKEN or GITHUB_TOKEN."
+SLUG_SEPARATOR = "/"
+SLUG_ARGUMENT_HELP = "Repository as owner/name, such as jl-cmd/claude-dev-env."
+NUMBER_ARGUMENT_HELP = "Pull request number."
+COMMAND_DESCRIPTION = (
+    "Report whether a pull request is ready for the agent that drives it to merge it."
+)
+
+REVIEW_THREAD_PAGE_SIZE = 100
+UNRESOLVED_THREAD_QUERY = """
+query($owner: String!, $name: String!, $number: Int!, $pageSize: Int!) {
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      reviewThreads(first: $pageSize) {
+        nodes { isResolved isOutdated }
+      }
+    }
+  }
+}
+"""
+QUERY_KEY = "query"
+VARIABLES_KEY = "variables"
+OWNER_VARIABLE = "owner"
+NAME_VARIABLE = "name"
+NUMBER_VARIABLE = "number"
+PAGE_SIZE_VARIABLE = "pageSize"
+DATA_KEY = "data"
+REPOSITORY_KEY = "repository"
+PULL_REQUEST_KEY = "pullRequest"
+REVIEW_THREADS_KEY = "reviewThreads"
+NODES_KEY = "nodes"
+ALL_THREAD_NODE_KEYS = (
+    DATA_KEY,
+    REPOSITORY_KEY,
+    PULL_REQUEST_KEY,
+    REVIEW_THREADS_KEY,
+    NODES_KEY,
+)
+ALL_RESOLVED_KEYS = ("isResolved", "is_resolved", "resolved")
+ALL_OUTDATED_KEYS = ("isOutdated", "is_outdated", "outdated")

package/scripts/dev_env_scripts_constants/contrast_framing_constants.py

@@ -0,0 +1,82 @@
+"""Constants for the contrast-framing detector.
+
+Each form names one shape a sentence takes when it defines its subject
+against a rejected reading::
+
+    "a diff regression, not shared code"   -> trailing-comma-not
+    "park it rather than fix it"           -> substitution-rather-than
+    "precision matters more than coverage" -> comparative-ranking
+    ok: "the function runs more than 30 lines"
+
+The rule file ``rules/no-contrast-framing.md`` carries one row for each name
+here, and a test holds the two in step.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ContrastFramingForm:
+    """One banned contrast form and the pattern that finds it."""
+
+    name: str
+    pattern: re.Pattern[str]
+    guidance: str
+    repeats_as_a_list: bool = False
+
+
+ALL_CONTRAST_FRAMING_FORMS: tuple[ContrastFramingForm, ...] = (
+    ContrastFramingForm(
+        "trailing-comma-not",
+        re.compile(r",\s+not\s+[\w\"'`(]", re.IGNORECASE),
+        "Drop the clause after the comma and state what is true.",
+        repeats_as_a_list=True,
+    ),
+    ContrastFramingForm(
+        "corrective-it-is-not",
+        re.compile(
+            r"\b(?:it|that|this)(?:'s|\s+is|\s+was)\s+not\b[^.!?]*?,\s*"
+            r"(?:it|that|this)(?:'s|\s+is|\s+was)\b",
+            re.IGNORECASE,
+        ),
+        "State what it is and leave the rejected reading out.",
+    ),
+    ContrastFramingForm(
+        "substitution-rather-than",
+        re.compile(r"\brather than\b", re.IGNORECASE),
+        "Name the thing you chose and stop.",
+    ),
+    ContrastFramingForm(
+        "additive-not-just",
+        re.compile(r"\bnot (?:just|only|merely|simply)\b", re.IGNORECASE),
+        "Say the point the sentence is building toward.",
+    ),
+    ContrastFramingForm(
+        "comparative-ranking",
+        re.compile(
+            r"\b(?:matters?|counts?|helps?|weighs?)\s+more\s+than\b"
+            r"|\b(?:more|less)\s+(?:important|useful|valuable)\s+than\b"
+            r"|\bmore\s+than\s+(?:trying|attempting|hoping)\b",
+            re.IGNORECASE,
+        ),
+        "State the thing you want. Leave the ranking out.",
+    ),
+    ContrastFramingForm(
+        "substitution-as-opposed-to",
+        re.compile(r"\bas opposed to\b", re.IGNORECASE),
+        "Name the thing you chose and stop.",
+    ),
+)
+
+CONTRAST_FRAMING_MESSAGE_TEMPLATE: str = (
+    'Contrast framing ({name}): "{text}". {guidance}'
+)
+
+CONTRAST_FRAMING_QUOTED_LINE_LIMIT: int = 120
+
+CONTRAST_FRAMING_FINDING_CODE: str = "contrast-framing"
+
+CONTRAST_FRAMING_RULE_DOCUMENT: str = "rules/no-contrast-framing.md"

package/scripts/dev_env_scripts_constants/merge_gate_check_constants.py

@@ -0,0 +1,23 @@
+"""Names and values ``merge_gate_checks.py`` reads a merge policy with.
+
+The fenced block marker and the ruleset field names describe a document and a
+GitHub payload that both live outside this package, so they sit here rather
+than inside the module that reads them.
+"""
+
+REQUIRED_CHECK_BLOCK_INFO_STRING: str = "required-status-checks"
+FENCE_MARKER: str = "```"
+RULESET_API_TEMPLATE: str = (
+    "https://api.github.com/repos/{repository}/rules/branches/{branch}"
+)
+RULESET_API_ACCEPT_HEADER: str = "application/vnd.github+json"
+RULESET_REQUEST_TIMEOUT_SECONDS: int = 30
+REQUIRED_STATUS_CHECKS_RULE_TYPE: str = "required_status_checks"
+RULE_TYPE_KEY: str = "type"
+RULE_PARAMETERS_KEY: str = "parameters"
+RULE_CONTEXT_KEY: str = "context"
+ALL_GITHUB_TOKEN_VARIABLES: tuple[str, ...] = ("GITHUB_TOKEN", "GH_TOKEN")
+MERGE_GATE_CLEAN_EXIT_CODE: int = 0
+MERGE_GATE_MISSING_CHECK_EXIT_CODE: int = 1
+JSON_INDENT_WIDTH: int = 2
+UTF8_ENCODING: str = "utf-8"

package/scripts/dev_env_scripts_constants/review_closure_constants.py

@@ -0,0 +1,241 @@
+"""Constants for the review_closure script.
+
+Per the project's configuration conventions, script-level scalar constants
+live in dev_env_scripts_constants alongside timing.py.
+"""
+
+GITHUB_API_ROOT: str = "https://api.github.com"
+"""Root of the GitHub REST API."""
+
+GITHUB_GRAPHQL_ENDPOINT: str = "https://api.github.com/graphql"
+"""Endpoint that answers the review-thread query."""
+
+PULL_REQUEST_ENDPOINT_TEMPLATE: str = "{api_root}/repos/{slug}/pulls/{number}"
+"""REST route carrying one pull request."""
+
+REVIEW_THREADS_ENDPOINT_TEMPLATE: str = (
+    "{api_root}/repos/{slug}/pulls/{number}/ccr/review_threads"
+)
+"""REST route a Claude Code session has for review threads."""
+
+CHECK_RUNS_ENDPOINT_TEMPLATE: str = (
+    "{api_root}/repos/{slug}/commits/{sha}/check-runs?per_page={page_size}"
+)
+"""REST route carrying the check runs reported on one commit."""
+
+REVIEW_THREAD_PAGE_SIZE: int = 100
+"""How many review threads and comments one query asks for."""
+
+CHECK_RUN_PAGE_SIZE: int = 100
+"""How many check runs one request asks for."""
+
+REVIEW_THREAD_QUERY: str = """
+query($owner: String!, $name: String!, $number: Int!, $pageSize: Int!) {
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      reviewThreads(first: $pageSize) {
+        nodes {
+          path
+          isResolved
+          isOutdated
+          comments(first: $pageSize) {
+            nodes {
+              body
+              author { login }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+"""
+"""GraphQL query for the review threads on one pull request."""
+
+ALL_THREAD_NODE_KEYS: tuple[str, ...] = (
+    "data",
+    "repository",
+    "pullRequest",
+    "reviewThreads",
+    "nodes",
+)
+"""Path from the GraphQL answer down to the review-thread list."""
+
+ALL_RESOLVED_KEYS: tuple[str, ...] = ("isResolved", "resolved", "is_resolved")
+"""Field names either route uses for a resolved review thread."""
+
+ALL_OUTDATED_KEYS: tuple[str, ...] = ("isOutdated", "outdated", "is_outdated")
+"""Field names either route uses for a thread whose code has been replaced."""
+
+ALL_COMMENT_LIST_KEYS: tuple[str, ...] = ("comments", "all_comments")
+"""Field names either route uses for a thread's comment list."""
+
+COMMENT_NODES_KEY: str = "nodes"
+"""GraphQL wraps a comment list in this field."""
+
+COMMENT_BODY_KEY: str = "body"
+"""Field carrying a comment's text."""
+
+ALL_COMMENT_AUTHOR_KEYS: tuple[str, ...] = ("author", "user")
+"""Field names either route uses for a comment's author."""
+
+AUTHOR_LOGIN_KEY: str = "login"
+"""Field carrying an author's GitHub login."""
+
+THREAD_PATH_KEY: str = "path"
+"""Field carrying the file a review thread points at."""
+
+UNNAMED_THREAD_SUBJECT: str = "a review thread"
+"""Subject text for a thread that names no file."""
+
+RED_CIRCLE_MARKER: str = "\U0001f534"
+"""The red circle a review marks a blocking finding with."""
+
+APPROVALS_CHECK_NAME: str = "Claude Approvals"
+"""Name of the check run whose rows carry blocking findings."""
+
+ALL_BLOCKING_CONCLUSIONS: tuple[str, ...] = ("failure", "action_required")
+"""Check-run conclusions that mean a blocking row is open on this head."""
+
+APPROVALS_OPEN_REASON: str = (
+    "the Claude Approvals check reports a blocking row on this commit"
+)
+"""Why a failing approvals check leaves the pull request open."""
+
+RED_CIRCLE_OPEN_REASON: str = (
+    "a blocking finding here carries no reply from the driving agent"
+)
+"""Why a red-circle thread stays open until the agent answers it."""
+
+UNANSWERED_OPEN_REASON: str = "unresolved, with no reply from the driving agent"
+"""Why an ordinary thread stays open."""
+
+CHECK_RUNS_KEY: str = "check_runs"
+"""Field carrying the check-run list in the REST answer."""
+
+CHECK_RUN_NAME_KEY: str = "name"
+"""Field carrying a check run's name."""
+
+CHECK_RUN_CONCLUSION_KEY: str = "conclusion"
+"""Field carrying a check run's conclusion."""
+
+HEAD_KEY: str = "head"
+"""Field carrying a pull request's head."""
+
+SHA_KEY: str = "sha"
+"""Field carrying a commit identifier."""
+
+NUMBER_KEY: str = "number"
+"""Field carrying a pull request number."""
+
+USER_KEY: str = "user"
+"""Field carrying the account that opened a pull request."""
+
+SHORT_SHA_LENGTH: int = 7
+"""How much of a commit identifier the verdict line prints."""
+
+SLUG_SEPARATOR: str = "/"
+"""Separator between owner and name in a repository slug."""
+
+QUERY_KEY: str = "query"
+"""GraphQL payload field carrying the query text."""
+
+VARIABLES_KEY: str = "variables"
+"""GraphQL payload field carrying the query variables."""
+
+OWNER_VARIABLE: str = "owner"
+"""GraphQL variable naming the repository owner."""
+
+NAME_VARIABLE: str = "name"
+"""GraphQL variable naming the repository."""
+
+NUMBER_VARIABLE: str = "number"
+"""GraphQL variable naming the pull request number."""
+
+PAGE_SIZE_VARIABLE: str = "pageSize"
+"""GraphQL variable naming the page size."""
+
+ALL_TOKEN_ENVIRONMENT_VARIABLES: tuple[str, ...] = (
+    "GITHUB_TOKEN",
+    "GH_TOKEN",
+)
+"""Environment variables that carry a GitHub token, in the order read."""
+
+NO_SIGN_IN_MESSAGE: str = (
+    "No GitHub token found. Set GITHUB_TOKEN or GH_TOKEN and run this again."
+)
+"""What to print when no token is available."""
+
+COMMAND_DESCRIPTION: str = (
+    "Report whether every review finding on a pull request head has been "
+    "answered by the agent driving it."
+)
+"""Help text for the command."""
+
+SLUG_ARGUMENT_HELP: str = "Repository as owner/name."
+"""Help text for the repository argument."""
+
+NUMBER_ARGUMENT_HELP: str = "Pull request number."
+"""Help text for the pull request argument."""
+
+DRIVER_LOGIN_ARGUMENT_HELP: str = (
+    "A login whose comments count as the driving agent's reply. Repeatable. "
+    "The account that opened the pull request always counts."
+)
+"""Help text for the driver login argument."""
+
+CLOSED_VERDICT_LABEL: str = "CLOSED"
+"""Verdict label for a pull request with every finding answered."""
+
+OPEN_VERDICT_LABEL: str = "OPEN"
+"""Verdict label for a pull request with a finding still waiting."""
+
+CLOSED_DETAIL: str = "every review finding on this commit is answered"
+"""Detail text on a closed verdict."""
+
+OPEN_DETAIL_TEMPLATE: str = "{count} review finding(s) wait on the driving agent"
+"""Detail text on an open verdict."""
+
+VERDICT_LINE_TEMPLATE: str = "{label} {slug}#{number} {sha} :: {detail}"
+"""Shape of the one verdict line this command prints."""
+
+FINDING_LINE_TEMPLATE: str = "  - {subject}: {reason}"
+"""Shape of each open-finding line printed under the verdict."""
+
+CLOSED_EXIT_CODE: int = 0
+"""Exit status when every finding is answered."""
+
+OPEN_EXIT_CODE: int = 1
+"""Exit status when a finding waits on the driving agent."""
+
+ERROR_EXIT_CODE: int = 2
+"""Exit status when the pull request state could not be read."""
+
+REQUEST_TIMEOUT_SECONDS: int = 30
+"""How long one GitHub request waits for an answer."""
+
+REQUEST_FAILED_TEMPLATE: str = "{url} answered {status}"
+"""What to report when GitHub answers with something other than success."""
+
+GET_METHOD: str = "GET"
+"""HTTP method for a read."""
+
+POST_METHOD: str = "POST"
+"""HTTP method the GraphQL query uses."""
+
+COMMENT_IDS_KEY: str = "comment_ids"
+"""Field the session route uses for a thread's comment identifiers."""
+
+COMMENT_IDENTIFIER_KEY: str = "id"
+"""Field carrying a review comment's identifier."""
+
+REVIEW_COMMENTS_ENDPOINT_TEMPLATE: str = (
+    "{api_root}/repos/{slug}/pulls/{number}/comments?per_page={page_size}&page={page}"
+)
+"""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."""
+
+MAX_REVIEW_COMMENT_PAGES: int = 20
+"""How many comment pages one run reads before it stops."""

package/scripts/dev_env_scripts_constants/test_code_review_constants.py

@@ -0,0 +1,12 @@
+"""Behavioral tests for the host-aware code-review invoker constants module."""
+
+from __future__ import annotations
+
+from dev_env_scripts_constants import code_review_constants as review_constants
+
+
+def test_default_effort_is_a_known_token() -> None:
+    assert (
+        review_constants.DEFAULT_CODE_REVIEW_EFFORT
+        in review_constants.ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER
+    )