@homericintelligence/athena-opencode 0.4.4 → 0.5.1

package/skills/pr-review/scripts/diff_context.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Compute the two required pull-request diff lenses."""
+"""Calculate the two Git ranges for a pull-request review."""
 
 from __future__ import annotations
 
@@ -32,7 +32,9 @@ def git(*arguments: str) -> str:
         check=False,
     )
     if result.returncode != 0:
-        raise RuntimeError(result.stderr.strip() or f"git {' '.join(arguments)} failed")
+        raise RuntimeError(
+            result.stderr.strip() or f"The git {' '.join(arguments)} command failed."
+        )
     return result.stdout.strip()
 
 
@@ -42,8 +44,8 @@ def main(argv: Sequence[str] | None = None) -> int:
     parser.add_argument("head_ref", metavar="HEAD_OID")
     arguments = parser.parse_args(argv)
     try:
-        base_ref = require_commit_oid(arguments.base_ref, "base OID")
-        head_ref = require_commit_oid(arguments.head_ref, "head OID")
+        base_ref = require_commit_oid(arguments.base_ref, "base object identifier")
+        head_ref = require_commit_oid(arguments.head_ref, "head object identifier")
         require_complete_git_history()
         git("rev-parse", "--verify", f"{base_ref}^{{commit}}")
         git("rev-parse", "--verify", f"{head_ref}^{{commit}}")

package/skills/pr-review/scripts/materialize_snapshot.py

@@ -27,11 +27,15 @@ from skills._cli import (
 
 SNAPSHOT_COMMAND_TIMEOUT_SECONDS = 30.0
 BOUNDED_MATERIALIZE_TIMEOUT_SECONDS = 600.0
+MATERIALIZE_ERROR = "The helper cannot materialize the immutable pull-request snapshot."
+QUOTA_ERROR = "The host cannot enforce the immutable pull-request snapshot size limit."
+REMOVE_ERROR = "The helper cannot remove the immutable pull-request snapshot."
+UNMANAGED_ROOT_ERROR = "The helper does not permit snapshot operations outside the managed temporary directory."
 
 
 @dataclass(frozen=True)
 class MaterializedSnapshot:
-    """A detached source tree bound to one reviewed GitHub pull request."""
+    """This record binds a detached source tree to one reviewed GitHub pull request."""
 
     root: Path
     source_path: Path
@@ -78,11 +82,9 @@ def _git(
             ["git", *git_read_arguments(), *arguments], **command_options
         )
     except subprocess.SubprocessError as error:
-        raise RuntimeError(
-            "cannot materialize the immutable pull-request snapshot"
-        ) from error
+        raise RuntimeError(MATERIALIZE_ERROR) from error
     if result.returncode not in accepted_codes:
-        raise RuntimeError("cannot materialize the immutable pull-request snapshot")
+        raise RuntimeError(MATERIALIZE_ERROR)
     return result.stdout.strip() if isinstance(result.stdout, str) else ""
 
 
@@ -97,32 +99,31 @@ def _hdiutil(*arguments: str) -> None:
             check=False,
         )
     except (OSError, RuntimeError, subprocess.SubprocessError) as error:
-        raise RuntimeError(
-            "host cannot enforce the immutable pull-request snapshot size limit"
-        ) from error
+        raise RuntimeError(QUOTA_ERROR) from error
     if result.returncode != 0:
-        raise RuntimeError(
-            "host cannot enforce the immutable pull-request snapshot size limit"
-        )
+        raise RuntimeError(QUOTA_ERROR)
 
 
 def _mount_tmpfs(source: Path, maximum_bytes: int) -> bool:
     """Mount a Linux tmpfs whose total capacity is the snapshot quota.
 
-    Returns True only when the mount is actually enforced; the caller must
-    verify ``source.is_mount()`` is not relied on elsewhere. On any failure
-    (no ``mount`` binary, no privilege, mount rejection) the caller uses the
-    bounded user/mount-namespace fallback or fails closed.
+    Return True only when the mount enforces the quota. Do not use
+    ``source.is_mount()`` elsewhere to infer this result. If the host cannot
+    find or run ``mount``, return False. If the host rejects the mount, return
+    False. The caller then uses the bounded user and mount namespace or fails
+    closed.
     """
     if sys.platform != "linux" or shutil.which("mount") is None:
         return False
     maximum_kibibytes = maximum_bytes // 1024
     if maximum_kibibytes < 1:
-        raise RuntimeError("immutable pull-request snapshot has no usable disk space")
+        raise RuntimeError(
+            "The immutable pull-request snapshot has no usable disk space."
+        )
     try:
         source.mkdir()
     except FileExistsError:
-        # Directory already exists from a prior materialization; reuse it.
+        # If a prior materialization created the directory, use it again.
         pass
     except OSError:
         return False
@@ -150,15 +151,17 @@ def _mount_tmpfs(source: Path, maximum_bytes: int) -> bool:
 def _create_quota_volume(root: Path, maximum_bytes: int) -> Path | None:
     """Return a bounded source directory, or None for the Linux bounded fallback.
 
-    darwin: attach a sparse HFS+ volume whose total capacity is the quota.
-    linux:  mount a tmpfs whose total capacity is the quota when the host is
-            privileged; otherwise return None so the caller materializes the
-            snapshot inside a bounded user/mount namespace.
-    other:  fail closed — the host cannot enforce the snapshot size limit.
+    On macOS, attach a sparse HFS+ volume whose total capacity is the quota.
+    On Linux, mount a tmpfs when the host has the required authority. Otherwise,
+    return None so the caller can materialize the snapshot inside a bounded user
+    and mount namespace. On other systems, fail closed because the host cannot
+    enforce the snapshot size limit.
     """
     maximum_kibibytes = maximum_bytes // 1024
     if maximum_kibibytes < 1:
-        raise RuntimeError("immutable pull-request snapshot has no usable disk space")
+        raise RuntimeError(
+            "The immutable pull-request snapshot has no usable disk space."
+        )
     if sys.platform == "darwin":
         image = root / "snapshot.sparseimage"
         source = root / "source"
@@ -173,7 +176,7 @@ def _create_quota_volume(root: Path, maximum_bytes: int) -> Path | None:
             "-fs",
             "Case-sensitive HFS+",
             "-volname",
-            "Athena PR Review",
+            "Athena pull-request review",
             "-nospotlight",
             str(image),
         )
@@ -186,9 +189,7 @@ def _create_quota_volume(root: Path, maximum_bytes: int) -> Path | None:
             str(image),
         )
         if not source.is_mount():
-            raise RuntimeError(
-                "host cannot enforce the immutable pull-request snapshot size limit"
-            )
+            raise RuntimeError(QUOTA_ERROR)
         return source
     if sys.platform.startswith("linux"):
         source = root / "source"
@@ -197,13 +198,11 @@ def _create_quota_volume(root: Path, maximum_bytes: int) -> Path | None:
         try:
             source.rmdir()
         except OSError:
-            # The mount may have partially created the directory; a failed
-            # rmdir is not fatal - the caller treats None as a fallback.
+            # The mount can create the directory before it fails.
+            # If rmdir fails, the caller uses None to select the other method.
             pass
         return None
-    raise RuntimeError(
-        "host cannot enforce the immutable pull-request snapshot size limit"
-    )
+    raise RuntimeError(QUOTA_ERROR)
 
 
 def _detach_volume(source: Path) -> None:
@@ -229,41 +228,38 @@ def _detach_volume(source: Path) -> None:
                     check=False,
                 )
             if result.returncode != 0:
-                raise RuntimeError("cannot remove the immutable pull-request snapshot")
+                raise RuntimeError(REMOVE_ERROR)
         except (OSError, RuntimeError, subprocess.SubprocessError) as error:
-            raise RuntimeError(
-                "cannot remove the immutable pull-request snapshot"
-            ) from error
+            raise RuntimeError(REMOVE_ERROR) from error
         return
-    raise RuntimeError("cannot remove the immutable pull-request snapshot")
+    raise RuntimeError(REMOVE_ERROR)
 
 
 def _detach_best_effort(source: Path) -> None:
-    """Detach a quota volume without masking a prior failure."""
+    """Detach the quota volume. Do not let a detach failure hide an earlier failure."""
     try:
         _detach_volume(source)
     except RuntimeError:
-        # Detach is best-effort; a prior failure must not be masked by a
-        # secondary cleanup error.
+        # Do not let this cleanup error hide an earlier failure.
         pass
 
 
 def _require_base_ref(base_ref: str) -> str:
     """Validate the GitHub base branch before it becomes a fetch refspec."""
     if not base_ref or base_ref.startswith("-") or ".." in base_ref:
-        raise RuntimeError("GitHub returned an invalid pull-request base ref")
+        raise RuntimeError("GitHub returned a pull-request base ref that is not valid.")
     _git("check-ref-format", "--branch", base_ref)
     return base_ref
 
 
 def _repository_size(path: Path, *, maximum_bytes: int | None = None) -> int:
-    """Return the size of a repository within 90 percent of free disk space."""
+    """Return the repository size and enforce the applicable size limit."""
     if maximum_bytes is None:
         try:
             maximum_bytes = (shutil.disk_usage(path).free * 9) // 10
         except OSError as error:
             raise RuntimeError(
-                "cannot inspect the immutable pull-request snapshot"
+                "The helper cannot inspect the immutable pull-request snapshot."
             ) from error
     total = 0
     for entry in path.rglob("*"):
@@ -271,13 +267,13 @@ def _repository_size(path: Path, *, maximum_bytes: int | None = None) -> int:
             details = entry.lstat()
         except OSError as error:
             raise RuntimeError(
-                "cannot inspect the immutable pull-request snapshot"
+                "The helper cannot inspect the immutable pull-request snapshot."
             ) from error
         if stat.S_ISREG(details.st_mode):
             total += details.st_size
             if total > maximum_bytes:
                 raise RuntimeError(
-                    "immutable pull-request snapshot exceeds the safe size limit"
+                    "The immutable pull-request snapshot exceeds the safe size limit."
                 )
     return total
 
@@ -296,7 +292,7 @@ def _verify_no_promisor_configuration(repository: Path) -> None:
         )
         if value:
             raise RuntimeError(
-                "immutable pull-request snapshot must not use partial clone configuration"
+                "The immutable pull-request snapshot must not use partial-clone configuration."
             )
     promisor = _git(
         "config",
@@ -309,12 +305,12 @@ def _verify_no_promisor_configuration(repository: Path) -> None:
     )
     if promisor:
         raise RuntimeError(
-            "immutable pull-request snapshot must not use promisor configuration"
+            "The immutable pull-request snapshot must not use promisor configuration."
         )
 
 
 def _require_commit(repository: Path, revision: str, label: str) -> str:
-    """Verify one fetched ref resolves exactly to its captured commit OID."""
+    """Verify that one fetched ref resolves to its captured commit object identifier."""
     resolved = _git(
         "rev-parse",
         "--verify",
@@ -326,7 +322,7 @@ def _require_commit(repository: Path, revision: str, label: str) -> str:
 
 
 def _make_read_only(root: Path) -> None:
-    """Remove write bits from the completed snapshot without following symlinks."""
+    """Remove write bits from the completed snapshot without following symbolic links."""
     entries = sorted(root.rglob("*"), key=lambda entry: len(entry.parts), reverse=True)
     for entry in entries:
         if entry.is_symlink():
@@ -339,7 +335,7 @@ def _make_read_only(root: Path) -> None:
                 entry.chmod(0o555 if mode & stat.S_IXUSR else 0o444)
         except OSError as error:
             raise RuntimeError(
-                "cannot make the immutable pull-request snapshot read-only"
+                "The helper cannot make the immutable pull-request snapshot read-only."
             ) from error
     root.chmod(0o555)
 
@@ -356,11 +352,11 @@ def _acquire_into(
     template: Path,
     maximum_bytes: int,
 ) -> tuple[str, str]:
-    """Fetch only the captured base branch and PR head into a source directory.
+    """Fetch only the captured base branch and pull-request head.
 
-    The source directory is provided by the caller (a quota volume or a
-    bounded tmpfs). Returns ``(merge_base, tree_oid)`` after verifying every
-    immutable binding against the captured OIDs.
+    The caller provides a source directory in a quota volume or bounded tmpfs.
+    Verify each immutable binding against the captured object identifiers.
+    Then, return ``(merge_base, tree_oid)``.
     """
     _git(
         "-c",
@@ -405,15 +401,26 @@ def _acquire_into(
         _git("rev-parse", "--is-shallow-repository", cwd=source, capture_output=True)
         != "false"
     ):
-        raise RuntimeError("immutable pull-request snapshot requires complete history")
-    if _require_commit(source, "refs/athena/base", "fetched base OID") != base_oid:
-        raise RuntimeError("fetched base ref does not match the captured base OID")
+        raise RuntimeError(
+            "The immutable pull-request snapshot requires complete history."
+        )
+    if (
+        _require_commit(source, "refs/athena/base", "fetched base object identifier")
+        != base_oid
+    ):
+        raise RuntimeError(
+            "The fetched base ref does not match the captured base object identifier."
+        )
     if (
-        _require_commit(source, f"refs/athena/pr/{number}/head", "fetched head OID")
+        _require_commit(
+            source,
+            f"refs/athena/pr/{number}/head",
+            "fetched head object identifier",
+        )
         != head_oid
     ):
         raise RuntimeError(
-            "fetched pull-request ref does not match the captured head OID"
+            "The fetched pull-request ref does not match the captured head object identifier."
         )
     merge_bases = _git(
         "merge-base",
@@ -425,15 +432,15 @@ def _acquire_into(
     ).splitlines()
     if len(merge_bases) != 1:
         raise RuntimeError(
-            "immutable pull-request snapshot requires one unambiguous merge base"
+            "The immutable pull-request snapshot requires one unambiguous merge base."
         )
     merge_base = require_commit_oid(merge_bases[0], "immutable merge base")
-    tree_oid = _require_commit(source, head_oid, "fetched head OID")
+    tree_oid = _require_commit(source, head_oid, "fetched head object identifier")
     tree_oid = _git(
         "rev-parse", f"{tree_oid}^{{tree}}", cwd=source, capture_output=True
     )
     if COMMIT_OID.fullmatch(tree_oid) is None:
-        raise RuntimeError("Git returned an invalid immutable head tree")
+        raise RuntimeError("Git returned an immutable head tree that is not valid.")
     _git(
         "-c",
         f"core.hooksPath={hooks}",
@@ -450,15 +457,16 @@ def _acquire_into(
 
 
 def _bounded_materialize_main(arguments: Sequence[str]) -> int:
-    """Materialize inside a bounded user/mount namespace (internal entry).
-
-    This runs as the child of ``unshare -rm`` on Linux. It mounts a tmpfs
-    whose total capacity is the snapshot quota, acquires the snapshot inside
-    that bound, copies the verified read-only tree to a host-visible path, and
-    prints the result as JSON. Exit 2 means the quota boundary itself could
-    not be established; exit 1 means materialization failed.
+    """Materialize inside a bounded user and mount namespace.
+
+    This helper runs as the child of ``unshare -rm`` on Linux. The helper mounts
+    a tmpfs whose total capacity is the snapshot quota. It materializes the
+    snapshot in the size-limited file system. Then, it copies the verified
+    read-only tree to a path that the host can read. Exit 2 means that the helper
+    could not establish the quota boundary. Exit 1 means that materialization
+    failed.
     """
-    parser = argument_parser(description="Bounded snapshot materialization.")
+    parser = argument_parser(description="Materialize a bounded pull-request snapshot.")
     parser.add_argument("--root", required=True, metavar="ROOT")
     parser.add_argument("--repository-url", required=True, metavar="URL")
     parser.add_argument("--pr-number", required=True, type=int, metavar="NUMBER")
@@ -470,22 +478,20 @@ def _bounded_materialize_main(arguments: Sequence[str]) -> int:
     root = Path(parsed.root).resolve()
     temporary_root = Path(tempfile.gettempdir()).resolve()
     if root.parent != temporary_root or not root.name.startswith("athena-pr-review-"):
-        print(
-            "refusing to materialize outside the managed temporary directory",
-            file=sys.stderr,
-        )
+        print(UNMANAGED_ROOT_ERROR, file=sys.stderr)
         return 1
     try:
-        canonical_base = require_commit_oid(parsed.base_oid, "captured base OID")
-        canonical_head = require_commit_oid(parsed.head_oid, "captured head OID")
+        canonical_base = require_commit_oid(
+            parsed.base_oid, "captured base object identifier"
+        )
+        canonical_head = require_commit_oid(
+            parsed.head_oid, "captured head object identifier"
+        )
         canonical_base_ref = _require_base_ref(parsed.base_ref)
         bounded = root / "bounded"
         bounded.mkdir()
         if not _mount_tmpfs(bounded, parsed.maximum_bytes):
-            print(
-                "host cannot enforce the immutable pull-request snapshot size limit",
-                file=sys.stderr,
-            )
+            print(QUOTA_ERROR, file=sys.stderr)
             return 2
         merge_base, tree_oid = _acquire_into(
             bounded,
@@ -528,20 +534,18 @@ def _bounded_materialize(
     base_oid: str,
     head_oid: str,
 ) -> MaterializedSnapshot:
-    """Materialize a snapshot inside a bounded Linux user/mount namespace.
-
-    Spawns this helper under ``unshare -rm`` (rootful within the new namespace
-    but unprivileged on the host), where the child mounts a tmpfs whose total
-    capacity is the snapshot quota. Every fetch/checkout write is bounded by
-    that filesystem; the verified tree is copied to a host-visible read-only
-    path before the namespace exits. Fails closed when ``unshare`` or a tmpfs
-    mount is unavailable.
+    """Materialize a snapshot inside a bounded Linux user and mount namespace.
+
+    Run this helper under ``unshare -rm``. The child has root authority only in
+    the new namespace. The child mounts a tmpfs whose total capacity is the
+    snapshot quota. The file system bounds each fetch and checkout write. Before
+    the namespace exits, the child copies the verified tree to a read-only path
+    that the host can read. If ``unshare`` or a tmpfs mount is not available,
+    the helper fails closed.
     """
     unshare = shutil.which("unshare")
     if unshare is None:
-        raise RuntimeError(
-            "host cannot enforce the immutable pull-request snapshot size limit"
-        )
+        raise RuntimeError(QUOTA_ERROR)
     command = [
         unshare,
         "-rm",
@@ -573,26 +577,20 @@ def _bounded_materialize(
             timeout=BOUNDED_MATERIALIZE_TIMEOUT_SECONDS,
         )
     except subprocess.TimeoutExpired as error:
-        raise RuntimeError(
-            "cannot materialize the immutable pull-request snapshot"
-        ) from error
+        raise RuntimeError(MATERIALIZE_ERROR) from error
     except (OSError, RuntimeError, subprocess.SubprocessError) as error:
-        raise RuntimeError(
-            "host cannot enforce the immutable pull-request snapshot size limit"
-        ) from error
+        raise RuntimeError(QUOTA_ERROR) from error
     if result.returncode == 2:
-        raise RuntimeError(
-            "host cannot enforce the immutable pull-request snapshot size limit"
-        )
+        raise RuntimeError(QUOTA_ERROR)
     if result.returncode != 0:
-        raise RuntimeError("cannot materialize the immutable pull-request snapshot")
+        raise RuntimeError(MATERIALIZE_ERROR)
     try:
         lines = [line for line in result.stdout.splitlines() if line.strip()]
         if not lines:
-            raise RuntimeError("cannot materialize the immutable pull-request snapshot")
+            raise RuntimeError(MATERIALIZE_ERROR)
         record = json.loads(lines[-1])
         if not isinstance(record, dict):
-            raise TypeError("cannot materialize the immutable pull-request snapshot")
+            raise TypeError(MATERIALIZE_ERROR)
         source_path = Path(str(record["source_path"]))
         merge_base = require_commit_oid(record["merge_base"], "immutable merge base")
         tree_oid = require_commit_oid(record["tree_oid"], "immutable head tree")
@@ -603,11 +601,9 @@ def _bounded_materialize(
         json.JSONDecodeError,
         RuntimeError,
     ) as error:
-        raise RuntimeError(
-            "cannot materialize the immutable pull-request snapshot"
-        ) from error
+        raise RuntimeError(MATERIALIZE_ERROR) from error
     if source_path != root / "source" or not source_path.is_dir():
-        raise RuntimeError("cannot materialize the immutable pull-request snapshot")
+        raise RuntimeError(MATERIALIZE_ERROR)
     return MaterializedSnapshot(
         root=root, source_path=source_path, merge_base=merge_base, tree_oid=tree_oid
     )
@@ -616,12 +612,12 @@ def _bounded_materialize(
 def materialize_snapshot(
     *, repository: str, number: int, base_ref: str, base_oid: str, head_oid: str
 ) -> MaterializedSnapshot:
-    """Fetch only a captured base branch and PR head into a fresh repository."""
+    """Materialize a captured base branch and pull-request head in a new repository."""
     canonical_repository = require_github_repository(repository, "GitHub repository")
     if isinstance(number, bool) or not isinstance(number, int) or number < 1:
-        raise RuntimeError("pull-request number must be positive")
-    canonical_base = require_commit_oid(base_oid, "captured base OID")
-    canonical_head = require_commit_oid(head_oid, "captured head OID")
+        raise RuntimeError("The pull-request number must be positive.")
+    canonical_base = require_commit_oid(base_oid, "captured base object identifier")
+    canonical_head = require_commit_oid(head_oid, "captured head object identifier")
     canonical_base_ref = _require_base_ref(base_ref)
     root = Path(tempfile.mkdtemp(prefix="athena-pr-review-"))
     template = root / "empty-template"
@@ -632,7 +628,7 @@ def materialize_snapshot(
         maximum_snapshot_bytes = (shutil.disk_usage(root).free * 9) // 10
         if maximum_snapshot_bytes < 1:
             raise RuntimeError(
-                "immutable pull-request snapshot has no usable disk space"
+                "The immutable pull-request snapshot has no usable disk space."
             )
         source = _create_quota_volume(root, maximum_snapshot_bytes)
         if source is None:
@@ -659,9 +655,7 @@ def materialize_snapshot(
         _make_read_only(root)
     except (OSError, subprocess.TimeoutExpired):
         remove_snapshot(root)
-        raise RuntimeError(
-            "cannot materialize the immutable pull-request snapshot"
-        ) from None
+        raise RuntimeError(MATERIALIZE_ERROR) from None
     except BaseException:
         remove_snapshot(root)
         raise
@@ -671,15 +665,13 @@ def materialize_snapshot(
 
 
 def remove_snapshot(root: Path) -> None:
-    """Remove a snapshot that this helper created after host inspection ends."""
+    """After host inspection ends, remove a snapshot that this helper materialized."""
     resolved = root.resolve()
     temporary_root = Path(tempfile.gettempdir()).resolve()
     if resolved.parent != temporary_root or not resolved.name.startswith(
         "athena-pr-review-"
     ):
-        raise RuntimeError(
-            "refusing to remove a snapshot outside the managed temporary directory"
-        )
+        raise RuntimeError(UNMANAGED_ROOT_ERROR)
     source = resolved / "source"
     if source.is_mount():
         _detach_volume(source)
@@ -690,7 +682,7 @@ def remove_snapshot(root: Path) -> None:
         if candidate.exists() and not candidate.is_symlink():
             candidate.chmod(0o700)
         if not callable(function):
-            raise TypeError("cannot remove the immutable pull-request snapshot")
+            raise TypeError(REMOVE_ERROR)
         function(path)
 
     shutil.rmtree(resolved, onexc=make_removable)

package/skills/pr-review/scripts/pr_identity.py

@@ -1,4 +1,4 @@
-"""Validate pull-request identifiers shared by PR review helpers."""
+"""Validate pull-request identifiers shared by pull-request review helpers."""
 
 from __future__ import annotations
 
@@ -12,45 +12,51 @@ GITHUB_HOST = "github.com"
 
 
 def validate_pr_identifier(value: str) -> None:
-    """Require a positive PR number or canonical GitHub pull-request URL."""
+    """Require a positive pull-request number or a canonical GitHub pull-request URL."""
     if (value.isascii() and value.isdigit() and int(value) > 0) or PR_URL.fullmatch(
         value
     ):
         return
-    raise RuntimeError(f"invalid pull-request identifier: {value!r}")
+    raise RuntimeError(f"The pull-request identifier is not valid: {value!r}.")
 
 
 def require_commit_oid(value: object, label: str) -> str:
-    """Return one canonical immutable commit OID or fail closed."""
+    """Return one canonical immutable commit object identifier or fail closed."""
     if not isinstance(value, str) or COMMIT_OID.fullmatch(value) is None:
-        raise RuntimeError(f"{label} must be a lowercase 40-hex Git commit OID")
+        raise RuntimeError(
+            f"The value for {label} must be a Git commit object identifier that "
+            "contains 40 lowercase hexadecimal characters."
+        )
     return value
 
 
 def require_github_repository(value: object, label: str) -> str:
-    """Return a canonical owner/repository target or reject unsafe input."""
+    """Return a canonical GitHub repository or reject unsafe input."""
     if not isinstance(value, str) or GITHUB_REPOSITORY.fullmatch(value) is None:
-        raise RuntimeError(f"{label} must be a canonical GitHub owner/repository")
+        raise RuntimeError(
+            "The value for "
+            f"{label} must use the canonical GitHub OWNER/REPOSITORY format."
+        )
     return value
 
 
 def require_github_host(value: object, label: str) -> str:
     """Return the supported canonical GitHub hostname or fail closed."""
     if value != GITHUB_HOST:
-        raise RuntimeError(f"{label} must be {GITHUB_HOST}")
+        raise RuntimeError(f"The value for {label} must be '{GITHUB_HOST}'.")
     return GITHUB_HOST
 
 
 def canonical_pull_request_url(repository: object, number: object) -> str:
-    """Return one exact public-GitHub pull-request URL from trusted identity."""
+    """Return one exact public GitHub pull-request URL from a trusted identity."""
     canonical_repository = require_github_repository(repository, "repository")
     if isinstance(number, bool) or not isinstance(number, int) or number < 1:
-        raise RuntimeError("pull-request number must be a positive integer")
+        raise RuntimeError("The pull-request number must be a positive integer.")
     return f"https://{GITHUB_HOST}/{canonical_repository}/pull/{number}"
 
 
 def pull_request_number(value: str) -> int:
-    """Return the positive number encoded by a validated PR identifier."""
+    """Return the positive number in a validated pull-request identifier."""
     validate_pr_identifier(value)
     if value.isdigit():
         return int(value)
@@ -64,17 +70,23 @@ def require_canonical_pull_request_url(
     """Require the exact canonical URL for a retained pull-request identity."""
     canonical_url = canonical_pull_request_url(repository, number)
     if value != canonical_url:
-        raise RuntimeError(f"{label} must be the canonical GitHub pull-request URL")
+        raise RuntimeError(
+            f"The value for {label} must be the canonical GitHub pull-request URL."
+        )
     return canonical_url
 
 
 def repository_from_pr_url(url: str, number: int) -> str:
-    """Return owner/repository after validating a canonical PR URL and number."""
+    """Return the repository from a canonical pull-request URL and number."""
     parsed_url = urlparse(url)
     path_parts = parsed_url.path.strip("/").split("/")
     if len(path_parts) != 4 or path_parts[2] != "pull" or path_parts[3] != str(number):
-        raise RuntimeError(f"GitHub returned invalid pull-request URL: {url}")
+        raise RuntimeError(
+            f"GitHub returned a pull-request URL that is not valid: '{url}'."
+        )
     repository = "/".join(path_parts[:2])
     if url != canonical_pull_request_url(repository, number):
-        raise RuntimeError(f"GitHub returned invalid pull-request URL: {url}")
+        raise RuntimeError(
+            f"GitHub returned a pull-request URL that is not valid: '{url}'."
+        )
     return repository