claude-dev-env 8.6.1 → 8.7.0

package/rules/correction-lens.md

@@ -0,0 +1,134 @@
+# Correction Lens
+
+**Standing rule. This file is never archived and never removed.** The permanence
+clause at the end of this document states what that binds.
+
+**When this applies:** Every correction the user gives. A "no, do it this way", a
+"stop writing that word", a repeated review comment, a fix the user makes by hand
+after an agent hands work back. Each one is evidence that a control is missing,
+and the correction is handled by building that control.
+
+## Rule
+
+A correction runs through five layers, in this order, and the lesson lands at the
+highest layer that can hold it. The change opens in the same run as the
+correction.
+
+| Priority | Layer | What holds the lesson | The lesson lands as |
+|---|---|---|---|
+| 1 | Codebase | The mistake is impossible by how the code is written | A type, a signature, a data structure, an API shape, a deleted branch |
+| 2 | Static analysis | A program reads the tree and decides | A lint rule, an enforcer check, a paired test, a CI gate |
+| 3 | Review tooling | A reviewer or a review bot reads the criterion | A `CODE_RULES.md` row, a `.cursor/BUGBOT.md` pointer, a Graphite or BugBot rule |
+| 4 | Skill | An agent follows a procedure | A skill under the agents home |
+| 5 | Style guide | Word choice and prose shape | A row in a `rules/*.md` file or a style document |
+
+Layer 1 is the goal every time. A lesson encoded there needs no reader, no run,
+and no agent to remember it. The wrong call has nowhere to live.
+
+## Choosing the layer
+
+Three sentences close every correction:
+
+1. The layer chosen.
+2. Why each higher layer cannot hold this lesson.
+3. The change opened at the chosen layer, by pull request.
+
+A layer holds a lesson when its own test passes:
+
+- **Layer 1 holds it** when a type, a signature, or a data structure can make the
+  wrong call fail to compile, fail to construct, or fail to exist.
+- **Layer 2 holds it** when a program reading the tree can separate right from
+  wrong with no judgment call.
+- **Layer 3 holds it** when a reader needs the criterion in front of them and a
+  program cannot decide it.
+- **Layer 4 holds it** when the lesson is a procedure with steps an agent runs.
+- **Layer 5 holds it** when the lesson is word choice or the shape of prose.
+
+Effort rules out no layer. A layer is ruled out when it lacks the capability to
+hold the lesson, and the sentence that rules it out says which capability is
+missing. "A lint for this would take a day" leaves layer 2 in play.
+
+Two layers often hold one correction. Take both: the shape at layer 1 and the
+check at layer 2 cost one run together and each covers what the other misses.
+
+## A repeated correction moves up a layer
+
+The same correction arriving a second time is the measurement. The layer chosen
+the first time was too low. Move the lesson one layer up and say so in the same
+run.
+
+A review comment that repeats across pull requests reads the same way. Each
+repetition names the layer below the reviewer as the one that needs the control.
+Count the repetitions.
+
+## Where the control lands
+
+A control lands in this package, so every session that loads this environment
+carries it, on any machine, under any model. A control written into one
+project's instructions reaches that project alone, and a control written into a
+chat reply reaches that conversation alone.
+
+Memory holds the decision. The control holds the behavior. A correction that
+produced a memory file and nothing else has been recorded and never encoded, so
+the rule still binds. Open the control.
+
+## Trust grows as the controls catch the common mistakes
+
+Add agents after the controls catch what agents get wrong, and start from a
+workflow small enough to watch. Each repeated correction becomes a stronger
+control, and the number of agents rises behind it.
+[`docs/high-trust-agent-delivery.md`](../docs/high-trust-agent-delivery.md)
+carries the model this comes from, including the layered-controls picture and
+the inner and outer delivery loops.
+
+## Permanence
+
+This file stays in `rules/`. A prune pass, an archive sweep, a consolidation, or
+a rewrite that would move it into `rules-archived/` stops at this line. The
+"Never archived" section of
+[`packages/claude-dev-env/rules-archived/ARCHIVE-MANIFEST.md`](../rules-archived/ARCHIVE-MANIFEST.md)
+names it, and
+[`archiving-agent-config.md`](archiving-agent-config.md) names the same
+exemption from the archiving procedure's side.
+
+An edit that sharpens this rule is welcome. The file stays.
+
+## Excerpt for repository-instruction sessions
+
+Codex reads its repository `AGENTS.md`; this excerpt supplies the standalone
+contract.
+
+```
+Correction handling for this run, from rules/correction-lens.md.
+
+Every correction the user gives becomes a control. Run it through five layers
+and land it at the highest one that can hold it:
+
+1. Codebase. The mistake is impossible by how the code is written: a type, a
+   signature, a data structure, an API shape.
+2. Static analysis. A program reads the tree and decides: a lint rule, an
+   enforcer check, a paired test, a CI gate.
+3. Review tooling. A reviewer or a review bot reads the criterion: a code-rules
+   row, a BUGBOT pointer, a Graphite rule.
+4. Skill. An agent follows a procedure.
+5. Style guide. Word choice and prose shape.
+
+Close the correction with three sentences: the layer chosen, why each higher
+layer cannot hold the lesson, and the change opened at that layer in this run.
+Effort rules out no layer; a missing capability does, and you name which one.
+
+The same correction arriving twice means the layer was too low. Move it up one
+layer and say so.
+
+Land the control in the shared environment package, so every session carries
+it. A memory file records the decision and encodes nothing.
+```
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`flag-non-breaking-findings.md`](flag-non-breaking-findings.md) | A gate blocks on a breaking finding and records a smell |
+| [`code-standards.md`](code-standards.md) | The layer map of contract, pointer, enforcer, lint, session rules |
+| [`archiving-agent-config.md`](archiving-agent-config.md) | How a rule leaves service, and which files are exempt |
+| [`falsify-before-green.md`](falsify-before-green.md) | A new layer-2 check counts once it has run red on a named break |

package/rules/flag-non-breaking-findings.md

@@ -97,6 +97,17 @@ loading, so the gate fails. A non-canonical filename and a Git mode other than
 `SEVERITY_BY_RULE_ID` in that module is the whole declaration. Add a check,
 add its row.
 
+`scripts/repository_policy.py` splits the committed-tree checks the same way.
+`SEVERITY_BY_CHECK_ID` in `repository_checks/config/constants.py` carries one
+row per check id, and a check id with no row reads as breaking. The
+`package-inventory` check is the one smell there. A production file whose
+package inventory omits its row still imports and still runs, so the check
+prints its finding with an `advisory:` prefix, records it in the ledger, and
+leaves the tree passing. Every other committed-tree check blocks: a `CLAUDE.md`
+naming a file that does not exist, an env-var row naming a file that never
+reads the variable, a test outside the testpaths allowlist, and a tracked
+secret.
+
 ## Sibling rules
 
 | Rule | Role |

package/rules/no-contrast-framing.md

@@ -0,0 +1,68 @@
+# No Contrast Framing
+
+**When this applies:** Every sentence a person reads. A chat reply, a commit
+message, a pull request title or body, a review comment, an issue, a rule file,
+a document, a plan, a memory file.
+
+## Rule
+
+State what is true. Leave the rejected reading out.
+
+A contrast defines its subject against something the writer already decided
+against, so the reader carries two readings where one would do, and the second
+one is the writer's own discarded draft. The sentence says more and shows less.
+
+Six forms carry the whole ban. Each row names the form the check reports.
+
+| Form | Shape | Write this |
+|---|---|---|
+| `trailing-comma-not` | `a diff regression, not shared infrastructure` | `a diff regression` |
+| `corrective-it-is-not` | `it is not a flake, it is a bug` | `a bug`, then the evidence that shows it |
+| `substitution-rather-than` | `park it rather than fix it` | `park it` |
+| `additive-not-just` | `not just for today` | the point the sentence was building toward |
+| `comparative-ranking` | `being precise matters more than trying to cover them` | `be precise about these three` |
+| `substitution-as-opposed-to` | `a warning as opposed to a failure` | `a warning` |
+
+A comparison of quantities stays. "The function runs more than 30 lines" counts
+lines. The ban covers the comparison that ranks one course of action over
+another the writer is turning down.
+
+Three shapes stay quiet by design. A backticked span or a fenced block carries
+an example, so the check blanks it first. A line opening with `>` quotes
+someone else, whose words are theirs to write. A `, not` clause reports only
+when no bare `not` already sits earlier in the line, so a list of clauses
+reports its first `, not` and stays quiet on the rest, as in
+`a diff regression, not shared code, not a workaround`. A list whose own
+opening word is a bare `not`, as in "not in chat, not in a commit message, not
+in a body", keeps even its first `, not` quiet. A release automation body
+passes the post linter untouched, since the bot builds it from commit
+subjects and reads it back as machine input.
+
+When the sentence thins after the contrast comes out, the missing piece is
+evidence. Name it: the failing check, the log line, the measured number, the
+file and the line.
+
+## Where it is enforced
+
+| Surface | What runs |
+|---|---|
+| Authored Markdown in the repository | The staged policy lint's `contrast-framing` rule, on every changed file, graded against the file's prior text |
+| A pull request or issue title and body, and a comment | `scripts/durable_post_lint.py`, which every post passes through before it reaches GitHub |
+| A chat reply | The writer, reading the sentence back before sending |
+
+The pattern list lives in
+`scripts/dev_env_scripts_constants/contrast_framing_constants.py`, and both
+lints read that one list. A synchronization test requires a row in the table
+above for every form the list carries.
+
+A chat reply reaches no check, so the same list is what the writer reads the
+sentence against: a comma followed by `not`, a `rather than`, a `not just`, a
+ranking of one thing over another.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`asd-ste100-language.md`](asd-ste100-language.md) | Plain word choice, sentence style, and tone |
+| [`correction-lens.md`](correction-lens.md) | Every correction becomes a control at the highest layer that can hold it |
+| [`research-mode.md`](research-mode.md) | A claim carries its source |

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

@@ -0,0 +1,44 @@
+# Review Closure Is a Check
+
+**When this applies:** Any pull request an agent drives, from the first review comment on it to the merge.
+
+## 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.
+
+One command prints the same verdict:
+
+```
+python packages/claude-dev-env/scripts/review_closure.py <owner>/<name> <number>
+```
+
+It prints `CLOSED` and exits 0 when every finding on the head is answered. It prints `OPEN`, one line per waiting finding, and exits 1. It exits 2 when the state could not be read.
+
+## What closes a finding
+
+| The thread | Closed by |
+|---|---|
+| A review comment on code | A push that replaced the code it points at |
+| A review comment on code | A reply from the account driving the pull request |
+| A review comment on code | Resolution, where the comment carries no red circle |
+| 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 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.
+
+The driving account is the one that opened the pull request. Where the agent comments under a second login, `--driver-login <login>` names it, repeatably.
+
+## 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.
+
+`Echo-Visuals-Inc/python-automation` runs the same command from its own workflow, against the revision of this package that its workflow pins.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`agent-merges-its-own-green-pull-request.md`](agent-merges-its-own-green-pull-request.md) | The agent that drives a pull request merges it once its gate passes |
+| [`git-workflow.md`](git-workflow.md) | Draft first, and confirm each required context fired after the push |
+| [`correction-lens.md`](correction-lens.md) | A correction becomes a control at the highest layer that can hold it |

package/scripts/Invoke-PesterSuites.ps1

@@ -0,0 +1,42 @@
+#!/usr/bin/env pwsh
+<#
+.SYNOPSIS
+    Run every Pester suite under a tests directory and exit on its verdict.
+
+.DESCRIPTION
+    check.ps1 calls this script as a child process so Invoke-Tool reads a
+    process exit code the way it does for ruff, mypy and pytest. Pester is a
+    cmdlet and leaves $LASTEXITCODE alone, so running it in-process would
+    report every suite as passing.
+
+    A missing Pester module exits non-zero. A gate that cannot run its check
+    has not passed it, and a skip here would leave the suites reporting
+    nothing while the tree reads as covered.
+
+.PARAMETER TestsRoot
+    Directory holding the *.Tests.ps1 suites.
+
+.OUTPUTS
+    Pester's own detailed output. Exit code 0 when every suite passes.
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$TestsRoot
+)
+
+$ErrorActionPreference = 'Stop'
+
+if (-not (Get-Module -ListAvailable -Name Pester)) {
+    Write-Error "Pester is not installed, so the suites under $TestsRoot cannot run."
+    exit 1
+}
+
+Import-Module Pester -MinimumVersion 5.0
+
+$suiteConfiguration = New-PesterConfiguration
+$suiteConfiguration.Run.Path = $TestsRoot
+$suiteConfiguration.Run.Exit = $true
+$suiteConfiguration.Output.Verbosity = 'Detailed'
+
+Invoke-Pester -Configuration $suiteConfiguration

package/scripts/agent_merge_check.py

@@ -0,0 +1,381 @@
+#!/usr/bin/env python3
+"""Report whether the agent driving a pull request may merge it now.
+
+An agent that drives a pull request in this repository merges it once the
+repository's own gate passes and no review thread is open. This command reads
+that state from GitHub and prints one verdict line, so the decision rests on
+the pull request's live state rather than on the agent's reading of it.
+
+Usage::
+
+    python3 agent_merge_check.py jl-cmd/claude-dev-env 1442
+    -> MERGE jl-cmd/claude-dev-env#1442 ab845eb :: green, no open review
+       thread, ready for the agent to merge
+
+Exit status is 0 for MERGE, 1 for HOLD, and 2 when the state could not be
+read.
+"""
+
+from __future__ import annotations
+
+import argparse
+import functools
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Callable, Mapping, Sequence
+
+from dev_env_scripts_constants.agent_merge_check_constants import (
+    ACCEPT_HEADER,
+    ALL_HOLD_REASONS_BY_STATE,
+    ALL_OUTDATED_KEYS,
+    ALL_RESOLVED_KEYS,
+    ALL_THREAD_NODE_KEYS,
+    ALL_TOKEN_ENVIRONMENT_VARIABLES,
+    AUTHORIZATION_HEADER,
+    BEARER_PREFIX,
+    COMMAND_DESCRIPTION,
+    CONTENT_TYPE_HEADER,
+    DRAFT_HOLD_REASON,
+    DRAFT_KEY,
+    ERROR_EXIT_CODE,
+    GITHUB_ACCEPT_TYPE,
+    GITHUB_API_ROOT,
+    GITHUB_GRAPHQL_ENDPOINT,
+    HEAD_KEY,
+    HOLD_EXIT_CODE,
+    HOLD_VERDICT_LABEL,
+    JSON_CONTENT_TYPE,
+    MERGE_EXIT_CODE,
+    MERGE_VERDICT_LABEL,
+    MERGEABLE_STATE_CLEAN,
+    MERGEABLE_STATE_KEY,
+    MERGEABLE_STATE_UNKNOWN,
+    NAME_VARIABLE,
+    NO_SIGN_IN_MESSAGE,
+    NUMBER_ARGUMENT_HELP,
+    NUMBER_KEY,
+    NUMBER_VARIABLE,
+    OWNER_VARIABLE,
+    PAGE_SIZE_VARIABLE,
+    PULL_REQUEST_ENDPOINT_TEMPLATE,
+    QUERY_KEY,
+    READY_DETAIL,
+    REQUEST_TIMEOUT_SECONDS,
+    REVIEW_THREAD_PAGE_SIZE,
+    REVIEW_THREADS_ENDPOINT_TEMPLATE,
+    SETTLE_ATTEMPT_COUNT,
+    SETTLE_WAIT_SECONDS,
+    SHA_KEY,
+    SHORT_SHA_LENGTH,
+    SLUG_ARGUMENT_HELP,
+    SLUG_SEPARATOR,
+    UNKNOWN_STATE_HOLD_TEMPLATE,
+    UNRESOLVED_THREAD_QUERY,
+    UNRESOLVED_THREADS_HOLD_TEMPLATE,
+    UTF8_ENCODING,
+    VARIABLES_KEY,
+    VERDICT_LINE_TEMPLATE,
+)
+
+
+class MergeCheckError(Exception):
+    """Raised when the pull request state could not be read."""
+
+
+def hold_reason(
+    all_pull_request_fields: Mapping[str, object],
+    unresolved_thread_count: int,
+) -> str | None:
+    """Return why this pull request stays open, or None when it may merge.
+
+    Args:
+        all_pull_request_fields: The pull request as the GitHub API reports
+            it, carrying its draft flag and its merge state.
+        unresolved_thread_count: How many review threads are open on it.
+
+    Returns:
+        The reason text for a draft, for a merge state other than clean, and
+        for an open review thread. 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_CLEAN:
+        return ALL_HOLD_REASONS_BY_STATE.get(
+            merge_state,
+            UNKNOWN_STATE_HOLD_TEMPLATE.format(state=merge_state),
+        )
+    if unresolved_thread_count > 0:
+        return UNRESOLVED_THREADS_HOLD_TEMPLATE.format(count=unresolved_thread_count)
+    return None
+
+
+def verdict_line(
+    slug: str,
+    all_pull_request_fields: Mapping[str, object],
+    reason: str | None,
+) -> str:
+    """Build the one line this command prints for a pull request.
+
+    Args:
+        slug: The repository as ``owner/name``.
+        all_pull_request_fields: The pull request the verdict describes.
+        reason: The hold reason, or None for a pull request that may merge.
+
+    Returns:
+        A line naming the verdict, the pull request, its head commit, and
+        either the hold reason or the ready detail.
+    """
+    all_head_fields = all_pull_request_fields.get(HEAD_KEY, {})
+    head_sha = ""
+    if isinstance(all_head_fields, Mapping):
+        head_sha = str(all_head_fields.get(SHA_KEY, ""))[:SHORT_SHA_LENGTH]
+    return VERDICT_LINE_TEMPLATE.format(
+        label=HOLD_VERDICT_LABEL if reason else MERGE_VERDICT_LABEL,
+        slug=slug,
+        number=all_pull_request_fields.get(NUMBER_KEY),
+        sha=head_sha,
+        detail=reason or READY_DETAIL,
+    )
+
+
+def count_unresolved_threads(all_thread_records: Sequence[object]) -> int:
+    """Count the review threads that still wait on an answer.
+
+    Args:
+        all_thread_records: The review threads GitHub reports for the pull
+            request.
+
+    Returns:
+        How many of them are unresolved and still point at live code. An
+        outdated thread names code the pull request has since replaced, so it
+        holds nothing back.
+    """
+    return sum(
+        1
+        for each_thread in all_thread_records
+        if isinstance(each_thread, Mapping)
+        and not _any_flag(each_thread, ALL_RESOLVED_KEYS)
+        and not _any_flag(each_thread, ALL_OUTDATED_KEYS)
+    )
+
+
+def _any_flag(all_thread_fields: Mapping[str, object], all_keys: Sequence[str]) -> bool:
+    return any(all_thread_fields.get(each_key) for each_key in all_keys)
+
+
+def _github_token() -> str:
+    for each_variable in ALL_TOKEN_ENVIRONMENT_VARIABLES:
+        token = os.environ.get(each_variable)
+        if token:
+            return token
+    raise MergeCheckError(NO_SIGN_IN_MESSAGE)
+
+
+def _request_json(
+    url: str,
+    token: str,
+    all_payload_fields: Mapping[str, object] | None,
+) -> object:
+    request = urllib.request.Request(url)
+    request.add_header(ACCEPT_HEADER, GITHUB_ACCEPT_TYPE)
+    request.add_header(AUTHORIZATION_HEADER, BEARER_PREFIX + token)
+    body = None
+    if all_payload_fields is not None:
+        request.add_header(CONTENT_TYPE_HEADER, JSON_CONTENT_TYPE)
+        body = json.dumps(all_payload_fields).encode(UTF8_ENCODING)
+    try:
+        with urllib.request.urlopen(
+            request,
+            data=body,
+            timeout=REQUEST_TIMEOUT_SECONDS,
+        ) as answer:
+            return json.loads(answer.read().decode(UTF8_ENCODING))
+    except (urllib.error.URLError, ValueError) as failure:
+        raise MergeCheckError(str(failure)) from failure
+
+
+def read_pull_request(slug: str, number: int, token: str) -> Mapping[str, object]:
+    """Read one pull request from the GitHub REST API.
+
+    Args:
+        slug: The repository as ``owner/name``.
+        number: The pull request number.
+        token: The GitHub token the request authenticates with.
+
+    Returns:
+        The pull request fields, carrying its draft flag, its merge state,
+        and its head commit.
+
+    Raises:
+        MergeCheckError: The API call failed, or answered with something
+            other than a pull request object.
+    """
+    document = _request_json(
+        PULL_REQUEST_ENDPOINT_TEMPLATE.format(
+            api_root=GITHUB_API_ROOT,
+            slug=slug,
+            number=number,
+        ),
+        token,
+        None,
+    )
+    if not isinstance(document, Mapping):
+        raise MergeCheckError(str(document))
+    return document
+
+
+def read_unresolved_thread_count(slug: str, number: int, token: str) -> int:
+    """Read how many review threads on a pull request stay open.
+
+    Two routes carry the same fact. A Claude Code session reaches GitHub
+    through a proxy that refuses GraphQL and serves the review threads over a
+    REST route of its own, so this reads that route first and falls back to
+    the GraphQL query every other caller has.
+
+    Args:
+        slug: The repository as ``owner/name``.
+        number: The pull request number.
+        token: The GitHub token the request authenticates with.
+
+    Returns:
+        The count of unresolved, current review threads.
+
+    Raises:
+        MergeCheckError: Both routes failed, or both answered with a shape
+            that carries no review threads.
+    """
+    all_thread_records = _thread_records_over_rest(slug, number, token)
+    if all_thread_records is None:
+        return _read_unresolved_thread_count_over_graphql(slug, number, token)
+    return count_unresolved_threads(all_thread_records)
+
+
+def _thread_records_over_rest(
+    slug: str,
+    number: int,
+    token: str,
+) -> list[object] | None:
+    try:
+        document = _request_json(
+            REVIEW_THREADS_ENDPOINT_TEMPLATE.format(
+                api_root=GITHUB_API_ROOT,
+                slug=slug,
+                number=number,
+            ),
+            token,
+            None,
+        )
+    except MergeCheckError:
+        return None
+    return document if isinstance(document, list) else None
+
+
+def _thread_query_payload(owner: str, name: str, number: int) -> dict[str, object]:
+    return {
+        QUERY_KEY: UNRESOLVED_THREAD_QUERY,
+        VARIABLES_KEY: {
+            OWNER_VARIABLE: owner,
+            NAME_VARIABLE: name,
+            NUMBER_VARIABLE: number,
+            PAGE_SIZE_VARIABLE: REVIEW_THREAD_PAGE_SIZE,
+        },
+    }
+
+
+def _read_unresolved_thread_count_over_graphql(
+    slug: str,
+    number: int,
+    token: str,
+) -> int:
+    owner, _, name = slug.partition(SLUG_SEPARATOR)
+    document = _request_json(
+        GITHUB_GRAPHQL_ENDPOINT,
+        token,
+        _thread_query_payload(owner, name, number),
+    )
+    all_thread_records = functools.reduce(
+        functools.partial(_field_at, document),
+        ALL_THREAD_NODE_KEYS,
+        document,
+    )
+    if not isinstance(all_thread_records, Sequence):
+        raise MergeCheckError(str(document))
+    return count_unresolved_threads(all_thread_records)
+
+
+def _field_at(document: object, all_fields: object, key: str) -> object:
+    if not isinstance(all_fields, Mapping):
+        raise MergeCheckError(str(document))
+    return all_fields.get(key)
+
+
+def read_settled_pull_request(
+    slug: str,
+    number: int,
+    token: str,
+    sleep: Callable[[float], None],
+) -> Mapping[str, object]:
+    """Read a pull request whose merge state GitHub has worked out.
+
+    GitHub reports ``unknown`` while it computes mergeability after a push,
+    so this reads again until the state settles.
+
+    Args:
+        slug: The repository as ``owner/name``.
+        number: The pull request number.
+        token: The GitHub token the request authenticates with.
+        sleep: How the caller waits between reads.
+
+    Returns:
+        The fields the last read reported.
+
+    Raises:
+        MergeCheckError: A read failed.
+    """
+    for each_attempt in range(SETTLE_ATTEMPT_COUNT):
+        all_pull_request_fields = read_pull_request(slug, number, token)
+        if all_pull_request_fields.get(MERGEABLE_STATE_KEY) != MERGEABLE_STATE_UNKNOWN:
+            return all_pull_request_fields
+        if each_attempt + 1 < SETTLE_ATTEMPT_COUNT:
+            sleep(SETTLE_WAIT_SECONDS)
+    return all_pull_request_fields
+
+
+def main(all_arguments: Sequence[str]) -> int:
+    """Print the merge verdict for one pull request.
+
+    Args:
+        all_arguments: The command line, without the program name.
+
+    Returns:
+        Zero when the pull request may merge, one when it holds, and two
+        when its state could not be read.
+    """
+    parser = argparse.ArgumentParser(description=COMMAND_DESCRIPTION)
+    parser.add_argument("slug", help=SLUG_ARGUMENT_HELP)
+    parser.add_argument("number", type=int, help=NUMBER_ARGUMENT_HELP)
+    parsed = parser.parse_args(all_arguments)
+    try:
+        token = _github_token()
+        all_pull_request_fields = read_settled_pull_request(
+            parsed.slug, parsed.number, token, time.sleep
+        )
+        unresolved_thread_count = read_unresolved_thread_count(
+            parsed.slug, parsed.number, token
+        )
+    except MergeCheckError as failure:
+        print(failure, file=sys.stderr)
+        return ERROR_EXIT_CODE
+    reason = hold_reason(all_pull_request_fields, unresolved_thread_count)
+    print(verdict_line(parsed.slug, all_pull_request_fields, reason))
+    return HOLD_EXIT_CODE if reason else MERGE_EXIT_CODE
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))