@homericintelligence/athena-opencode 0.5.0 → 0.5.2

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

@@ -1,9 +1,11 @@
 #!/usr/bin/env python3
-"""Collect GitHub PR metadata and immutable review evidence."""
+"""Collect GitHub pull-request metadata and immutable review evidence."""
 
 from __future__ import annotations
 
+import importlib.util
 import json
+import re
 import subprocess
 import sys
 import threading
@@ -12,10 +14,7 @@ from collections.abc import Sequence
 from dataclasses import dataclass, field
 from hashlib import sha256
 from pathlib import Path
-from typing import IO, Any
-
-if __package__ in {None, ""}:
-    sys.path.insert(0, str(Path(__file__).resolve().parents[3]))
+from typing import IO, TYPE_CHECKING, Any
 
 from materialize_snapshot import (
     MaterializedSnapshot,
@@ -32,21 +31,40 @@ from pr_identity import (
     validate_pr_identifier,
 )
 
-from skills._cli import (
-    argument_parser,
-    git_read_arguments,
-    git_read_environment,
-    require_complete_git_history,
-    require_unambiguous_git_merge_base,
-    run_command,
-)
+if TYPE_CHECKING or __package__ not in {None, ""}:
+    from skills._cli import (
+        argument_parser,
+        git_read_arguments,
+        git_read_environment,
+        require_complete_git_history,
+        require_unambiguous_git_merge_base,
+        run_command,
+    )
+else:
+    _cli_path = Path(__file__).resolve().parents[2] / "_cli.py"
+    _cli_spec = importlib.util.spec_from_file_location(
+        "athena_installed_cli", _cli_path
+    )
+    if _cli_spec is None or _cli_spec.loader is None:
+        raise RuntimeError(
+            f"The installed Athena CLI helper is unavailable: '{_cli_path}'."
+        )
+    _cli = importlib.util.module_from_spec(_cli_spec)
+    _cli_spec.loader.exec_module(_cli)
+    argument_parser = _cli.argument_parser
+    git_read_arguments = _cli.git_read_arguments
+    git_read_environment = _cli.git_read_environment
+    require_complete_git_history = _cli.require_complete_git_history
+    require_unambiguous_git_merge_base = _cli.require_unambiguous_git_merge_base
+    run_command = _cli.run_command
 
 # Keep this query below GitHub's GraphQL complexity budget. Strict callers bind
-# changed paths to local immutable Git objects; legacy callers retain the REST
-# file-list fallback for backwards compatibility only.
+# changed paths to local immutable Git objects. Earlier callers use the REST
+# file-list fallback only for backward compatibility.
 FIELDS = (
     "number,title,body,state,isDraft,author,baseRefName,headRefName,"
-    "baseRefOid,headRefOid,reviews,statusCheckRollup,closingIssuesReferences,url"
+    "baseRefOid,headRefOid,reviewDecision,reviews,statusCheckRollup,"
+    "closingIssuesReferences,url"
 )
 ISSUE_FIELDS = "id,number,url,title,body,state"
 READ_CHUNK_SIZE = 64 * 1024
@@ -68,7 +86,6 @@ MAX_CHANGED_PATH_MANIFEST_BYTES = 2 * 1024 * 1024
 MAX_CHANGED_PATHS = 10_000
 MAX_CHANGED_PATH_STDERR_BYTES = 16 * 1024
 CHANGED_PATH_REQUEST_TIMEOUT_SECONDS = 30.0
-MAX_CHECK_RUN_PAGE_BYTES = 256 * 1024
 MAX_CHECK_RUN_BYTES = 2 * 1024 * 1024
 MAX_CHECK_RUN_PAGES = 100
 MAX_CHECK_RUNS = 10_000
@@ -90,7 +107,7 @@ class CheckEvidenceCoverageGap(RuntimeError):
 
 @dataclass
 class LinkedRequirementBudget:
-    """One cumulative provider budget shared by both strict evidence reads."""
+    """This budget controls both strict evidence reads from the provider."""
 
     pages: int = 0
     comments: int = 0
@@ -105,7 +122,7 @@ class LinkedRequirementBudget:
         """Reserve one bounded provider request before issuing it."""
         if self.requests >= MAX_LINKED_REQUIREMENT_REQUESTS:
             raise LinkedRequirementsCoverageGap(
-                "linked issue requirements exceed the safe aggregate request limit"
+                "The linked issue requirements exceed the safe aggregate request limit."
             )
         self.requests += 1
 
@@ -113,7 +130,7 @@ class LinkedRequirementBudget:
         """Reserve one aggregate comment page and its provider request."""
         if self.pages >= MAX_LINKED_REQUIREMENT_PAGES:
             raise LinkedRequirementsCoverageGap(
-                "linked issue requirements exceed the safe aggregate page limit"
+                "The linked issue requirements exceed the safe aggregate page limit."
             )
         self.reserve_request()
 
@@ -121,7 +138,7 @@ class LinkedRequirementBudget:
         """Account for one provider response without crossing the byte budget."""
         if count > self.remaining_bytes():
             raise LinkedRequirementsCoverageGap(
-                "linked issue requirements exceed the safe aggregate byte limit"
+                "The linked issue requirements exceed the safe aggregate byte limit."
             )
         self.bytes_read += count
 
@@ -129,7 +146,7 @@ class LinkedRequirementBudget:
         """Account for one successful provider page and its item count."""
         if self.comments + count > MAX_LINKED_REQUIREMENT_COMMENTS:
             raise LinkedRequirementsCoverageGap(
-                "linked issue requirements exceed the safe aggregate comment limit"
+                "The linked issue requirements exceed the safe aggregate comment limit."
             )
         self.pages += 1
         self.comments += count
@@ -137,7 +154,7 @@ class LinkedRequirementBudget:
 
 @dataclass
 class ProviderStream:
-    """One bounded asynchronous stdout or stderr capture."""
+    """This record contains one bounded asynchronous output stream."""
 
     maximum_bytes: int
     output: bytearray = field(default_factory=bytearray)
@@ -148,7 +165,7 @@ class ProviderStream:
 
 @dataclass
 class ChangedPathStream:
-    """Incrementally validate a bounded NUL-delimited Git path manifest."""
+    """Incrementally validate a bounded null-byte-delimited Git path manifest."""
 
     maximum_bytes: int
     maximum_paths: int
@@ -164,7 +181,7 @@ class ChangedPathStream:
 
 @dataclass(frozen=True)
 class ImmutableIdentity:
-    """The review artifact and exact revisions that evidence is bound to."""
+    """This record binds evidence to a review artifact and its exact revisions."""
 
     repository: str
     number: int
@@ -187,7 +204,7 @@ class ImmutableIdentity:
 
 @dataclass(frozen=True)
 class ExpectedReviewTarget:
-    """The immutable GitHub artifact target resolved before strict collection."""
+    """This record identifies the immutable GitHub target for strict collection."""
 
     host: str
     repository: str
@@ -201,7 +218,7 @@ class ExpectedReviewTarget:
 
 @dataclass(frozen=True)
 class ChangedPathManifest:
-    """A canonical, immutable changed-path manifest derived from Git objects."""
+    """This record describes a canonical changed-path manifest from Git objects."""
 
     paths: tuple[str, ...]
     sha256: str
@@ -217,7 +234,7 @@ class ChangedPathManifest:
 
 @dataclass(frozen=True)
 class ReviewScope:
-    """Canonical mutable review-context fields bound to an evidence collection."""
+    """This record binds mutable review-context fields to an evidence collection."""
 
     fields: dict[str, Any]
     sha256: str
@@ -229,7 +246,7 @@ class ReviewScope:
 
 @dataclass(frozen=True)
 class LinkedRequirements:
-    """Canonical content binding for every linked issue used as requirements."""
+    """This record binds the canonical content of each linked issue used as requirements."""
 
     items: tuple[LinkedRequirement, ...]
     sha256: str
@@ -245,7 +262,7 @@ class LinkedRequirements:
 
 @dataclass(frozen=True)
 class LinkedRequirement:
-    """One linked issue's stable identity and content-only requirements digest."""
+    """This record contains one linked issue identity and its requirements digest."""
 
     id: str
     repository: str
@@ -265,9 +282,9 @@ class LinkedRequirement:
 
 
 def metadata_error(metadata: object, *, require_immutable_identity: bool) -> str | None:
-    """Return a diagnostic when GitHub returns partial PR metadata."""
+    """Return a diagnostic when GitHub returns partial pull-request metadata."""
     if not isinstance(metadata, dict):
-        return "PR metadata must be a JSON object"
+        return "The pull-request metadata must be a JSON object."
     required_types = {
         "number": int,
         "title": str,
@@ -287,11 +304,13 @@ def metadata_error(metadata: object, *, require_immutable_identity: bool) -> str
     if not isinstance(author, dict) or not isinstance(author.get("login"), str):
         invalid.append("author.login")
     if invalid:
-        return "GitHub returned incomplete or invalid PR metadata fields: " + ", ".join(
-            sorted(set(invalid))
+        return (
+            "GitHub returned pull-request metadata fields that are incomplete or not valid: "
+            + ", ".join(f"'{field}'" for field in sorted(set(invalid)))
+            + "."
         )
     if metadata["state"] != "OPEN":
-        return f"pull request {metadata['number']} is not open"
+        return f"Pull request {metadata['number']} is not open."
     identity_fields = ("baseRefOid", "headRefOid")
     identity_values = [metadata.get(field) for field in identity_fields]
     has_identity = any(value is not None for value in identity_values)
@@ -303,8 +322,10 @@ def metadata_error(metadata: object, *, require_immutable_identity: bool) -> str
         ]
         if invalid_identity:
             return (
-                "GitHub returned incomplete or invalid immutable PR identity fields: "
-                + ", ".join(invalid_identity)
+                "GitHub returned immutable pull-request identity fields that are "
+                "incomplete or not valid: "
+                + ", ".join(f"'{field}'" for field in invalid_identity)
+                + "."
             )
     if require_immutable_identity:
         body = metadata.get("body")
@@ -320,8 +341,9 @@ def metadata_error(metadata: object, *, require_immutable_identity: bool) -> str
             scope_invalid.append("closingIssuesReferences")
         if scope_invalid:
             return (
-                "GitHub returned incomplete or invalid review-scope fields: "
-                + ", ".join(scope_invalid)
+                "GitHub returned review-scope fields that are incomplete or not valid: "
+                + ", ".join(f"'{field}'" for field in scope_invalid)
+                + "."
             )
     return None
 
@@ -335,11 +357,11 @@ def immutable_identity(
     if base_oid is None and head_oid is None and not require_immutable_identity:
         return None
     if not isinstance(base_oid, str) or not isinstance(head_oid, str):
-        raise TypeError("GitHub returned incomplete immutable pull-request identity")
+        raise TypeError("GitHub returned incomplete immutable pull-request identity.")
     number = metadata.get("number")
     url = metadata.get("url")
     if not isinstance(number, int) or not isinstance(url, str):
-        raise TypeError("GitHub returned incomplete pull-request identity")
+        raise TypeError("GitHub returned incomplete pull-request identity.")
     return ImmutableIdentity(
         repository=repository,
         number=number,
@@ -354,15 +376,19 @@ def expected_identity(
 ) -> tuple[str, str] | None:
     """Validate the optional immutable identity supplied by resolve_pr.py."""
     if (base_oid is None) != (head_oid is None):
-        parser.error(
-            "--expected-base-oid and --expected-head-oid must be supplied together"
-        )
+        parser.error("Specify --expected-base-oid and --expected-head-oid together.")
     if base_oid is None or head_oid is None:
         return None
     if COMMIT_OID.fullmatch(base_oid) is None:
-        parser.error("--expected-base-oid must be a lowercase 40-hex Git commit OID")
+        parser.error(
+            "--expected-base-oid must be a Git commit object identifier that contains "
+            "40 lowercase hexadecimal characters."
+        )
     if COMMIT_OID.fullmatch(head_oid) is None:
-        parser.error("--expected-head-oid must be a lowercase 40-hex Git commit OID")
+        parser.error(
+            "--expected-head-oid must be a Git commit object identifier that contains "
+            "40 lowercase hexadecimal characters."
+        )
     return base_oid, head_oid
 
 
@@ -374,7 +400,7 @@ def expected_target(
     number: int | None,
     url: str | None,
 ) -> ExpectedReviewTarget | None:
-    """Require the resolved GitHub target whenever immutable OIDs are supplied."""
+    """Require the resolved GitHub target when immutable object identifiers are supplied."""
     if identity is None:
         if (
             host is not None
@@ -383,21 +409,22 @@ def expected_target(
             or url is not None
         ):
             parser.error(
-                "--expected-host, --expected-repository, --expected-pr-number, and "
-                "--expected-pr-url require immutable expected OIDs"
+                "If you specify an expected target, also specify --expected-base-oid "
+                "and --expected-head-oid."
             )
         return None
     if host is None or repository is None or number is None or url is None:
         parser.error(
+            "With --expected-base-oid and --expected-head-oid, specify "
             "--expected-host, --expected-repository, --expected-pr-number, and "
-            "--expected-pr-url are required with immutable expected OIDs"
+            "--expected-pr-url."
         )
     assert host is not None
     assert repository is not None
     assert number is not None
     assert url is not None
     if host != "github.com":
-        parser.error("--expected-host must be github.com")
+        parser.error("'--expected-host' must be 'github.com'.")
     try:
         canonical_repository = require_github_repository(
             repository, "--expected-repository"
@@ -405,7 +432,7 @@ def expected_target(
     except RuntimeError as error:
         parser.error(str(error))
     if number < 1:
-        parser.error("--expected-pr-number must be a positive pull-request number")
+        parser.error("--expected-pr-number must be a positive pull-request number.")
     try:
         canonical_url = require_canonical_pull_request_url(
             url, canonical_repository, number, "--expected-pr-url"
@@ -423,14 +450,15 @@ def expected_target(
 def ensure_expected_identity(
     identity: ImmutableIdentity | None, expected: tuple[str, str] | None
 ) -> None:
-    """Fail closed when collected revisions differ from the resolved PR."""
+    """Fail closed when collected revisions differ from the resolved pull request."""
     if expected is None:
         return
     if identity is None:
-        raise RuntimeError("GitHub returned no immutable pull-request identity")
+        raise RuntimeError("GitHub did not return an immutable pull-request identity.")
     if (identity.base_oid, identity.head_oid) != expected:
         raise RuntimeError(
-            "immutable pull-request identity does not match the expected base/head OIDs"
+            "The immutable pull-request identity does not match the expected base "
+            "object identifier and head object identifier."
         )
 
 
@@ -441,20 +469,22 @@ def ensure_expected_target(
     if target is None:
         return
     if identity is None:
-        raise RuntimeError("GitHub returned no immutable pull-request identity")
+        raise RuntimeError("GitHub did not return an immutable pull-request identity.")
     if (
         identity.repository.casefold() != target.repository.casefold()
         or identity.number != target.number
         or identity.url != target.url
     ):
-        raise RuntimeError("pull-request identity does not match the expected target")
+        raise RuntimeError(
+            "The pull-request identity does not match the expected target."
+        )
 
 
 def review_scope(metadata: dict[str, Any]) -> ReviewScope:
-    """Bind mutable issue/scope fields so they cannot drift during review."""
+    """Bind mutable issue fields and scope fields so they cannot change during review."""
     closing_issues = metadata.get("closingIssuesReferences")
     if not isinstance(closing_issues, list):
-        raise TypeError("GitHub returned incomplete review-scope fields")
+        raise TypeError("GitHub returned incomplete review-scope fields.")
     try:
         canonical_issues = sorted(
             json.dumps(
@@ -485,7 +515,9 @@ def review_scope(metadata: dict[str, Any]) -> ReviewScope:
             sort_keys=True,
         )
     except (KeyError, TypeError, ValueError, json.JSONDecodeError) as error:
-        raise RuntimeError("GitHub returned invalid review-scope fields") from error
+        raise RuntimeError(
+            "GitHub returned review-scope fields that are not valid."
+        ) from error
     return ReviewScope(
         fields=fields,
         sha256=sha256(canonical_scope.encode("utf-8")).hexdigest(),
@@ -495,7 +527,7 @@ def review_scope(metadata: dict[str, Any]) -> ReviewScope:
 def linked_issue_reference(issue: object) -> tuple[str, str, int, str]:
     """Return one validated canonical linked-issue identity."""
     if not isinstance(issue, dict):
-        raise TypeError("GitHub returned an invalid linked issue reference")
+        raise TypeError("GitHub returned a linked issue reference that is not valid.")
     issue_id = issue.get("id")
     repository_data = issue.get("repository")
     number = issue.get("number")
@@ -507,7 +539,7 @@ def linked_issue_reference(issue: object) -> tuple[str, str, int, str]:
         or isinstance(number, bool)
         or not isinstance(number, int)
     ):
-        raise RuntimeError("GitHub returned an incomplete linked issue reference")
+        raise RuntimeError("GitHub returned an incomplete linked issue reference.")
     owner_data = repository_data.get("owner")
     name = repository_data.get("name")
     owner = owner_data.get("login") if isinstance(owner_data, dict) else None
@@ -519,18 +551,18 @@ def linked_issue_reference(issue: object) -> tuple[str, str, int, str]:
         or number < 1
         or not isinstance(url, str)
     ):
-        raise RuntimeError("GitHub returned an incomplete linked issue reference")
+        raise RuntimeError("GitHub returned an incomplete linked issue reference.")
     try:
         repository = require_github_repository(
             f"{owner}/{name}", "GitHub linked issue repository"
         )
     except RuntimeError as error:
         raise RuntimeError(
-            "GitHub returned an invalid linked issue repository"
+            "GitHub returned a linked issue repository that is not valid."
         ) from error
     canonical_url = f"https://github.com/{repository}/issues/{number}"
     if url != canonical_url:
-        raise RuntimeError("GitHub returned an invalid linked issue URL")
+        raise RuntimeError("GitHub returned a linked issue URL that is not valid.")
     return issue_id, repository, number, canonical_url
 
 
@@ -545,7 +577,7 @@ def canonical_json(value: object, label: str) -> str:
             sort_keys=True,
         )
     except (TypeError, ValueError) as error:
-        raise RuntimeError(f"GitHub returned invalid {label}") from error
+        raise RuntimeError(f"The data for {label} is not valid.") from error
 
 
 def drain_provider_stream(stream: IO[bytes], capture: ProviderStream) -> None:
@@ -571,7 +603,7 @@ def drain_provider_stream(stream: IO[bytes], capture: ProviderStream) -> None:
         try:
             stream.close()
         except OSError:
-            # Another cleanup path may already have closed this best-effort pipe.
+            # A different cleanup path can close this pipe first. Ignore the error.
             pass
         capture.completed.set()
 
@@ -579,15 +611,15 @@ def drain_provider_stream(stream: IO[bytes], capture: ProviderStream) -> None:
 def validate_changed_path(entry: bytes) -> None:
     """Reject an empty or unsafe Git-relative path entry."""
     if not entry:
-        raise RuntimeError("Git returned an empty changed path")
+        raise RuntimeError("Git returned an empty changed path.")
     if entry.startswith(b"/") or any(
         component in {b".", b".."} for component in entry.split(b"/")
     ):
-        raise RuntimeError("Git returned an unsafe changed path")
+        raise RuntimeError("Git returned an unsafe changed path.")
 
 
 def drain_changed_path_stream(stream: IO[bytes], capture: ChangedPathStream) -> None:
-    """Incrementally collect one bounded, NUL-delimited Git path manifest."""
+    """Incrementally collect one bounded, null-byte-delimited Git path manifest."""
     try:
         while True:
             read_size = min(
@@ -595,7 +627,7 @@ def drain_changed_path_stream(stream: IO[bytes], capture: ChangedPathStream) ->
             )
             if read_size <= 0:
                 capture.limit_error = (
-                    "changed-path manifest exceeds the safe byte limit"
+                    "The changed-path manifest exceeds the safe byte limit."
                 )
                 capture.overflowed.set()
                 return
@@ -603,12 +635,13 @@ def drain_changed_path_stream(stream: IO[bytes], capture: ChangedPathStream) ->
             if not chunk:
                 if capture.trailing:
                     raise RuntimeError(
-                        "Git returned a malformed NUL-delimited changed-path manifest"
+                        "Git returned a null-byte-delimited changed-path manifest that "
+                        "is not valid."
                     )
                 return
             if capture.bytes_read + len(chunk) > capture.maximum_bytes:
                 capture.limit_error = (
-                    "changed-path manifest exceeds the safe byte limit"
+                    "The changed-path manifest exceeds the safe byte limit."
                 )
                 capture.overflowed.set()
                 return
@@ -618,10 +651,10 @@ def drain_changed_path_stream(stream: IO[bytes], capture: ChangedPathStream) ->
             for entry in entries:
                 validate_changed_path(entry)
                 if entry in capture.seen_paths:
-                    raise RuntimeError("Git returned duplicate changed paths")
+                    raise RuntimeError("Git returned duplicate changed paths.")
                 if len(capture.paths) >= capture.maximum_paths:
                     capture.limit_error = (
-                        "changed-path manifest exceeds the safe path limit"
+                        "The changed-path manifest exceeds the safe path limit."
                     )
                     capture.overflowed.set()
                     return
@@ -633,7 +666,7 @@ def drain_changed_path_stream(stream: IO[bytes], capture: ChangedPathStream) ->
         try:
             stream.close()
         except (OSError, ValueError):
-            # A sibling cleanup path can close the pipe before this reader exits.
+            # A different cleanup path can close this pipe first. Ignore the error.
             pass
         capture.completed.set()
 
@@ -650,7 +683,7 @@ def reap_provider(
         try:
             stream.close()
         except (OSError, ValueError):
-            # Reaping is best effort after either reader may have closed the pipe.
+            # A reader can close this pipe first. Ignore the error.
             pass
     process.wait()
     for reader in readers:
@@ -704,14 +737,18 @@ def bounded_gh_output(
     limit_error: str,
     timeout_seconds: float | None = None,
     stderr_maximum_bytes: int | None = None,
-    stderr_limit_error: str = "linked issue response exceeds the safe stderr limit",
-    deadline_error: str = "linked issue provider exceeded the safe provider deadline",
-    output_error: str = "cannot read linked issue provider output",
-    unavailable_output_error: str = "GitHub did not provide linked issue provider output",
-    operating_system_error: str = "cannot collect linked issue comments",
+    stderr_limit_error: str = (
+        "The linked issue response exceeds the safe standard-error limit."
+    ),
+    deadline_error: str = "The linked issue provider exceeded the safe deadline.",
+    output_error: str = "The tool cannot read linked issue provider output.",
+    unavailable_output_error: str = (
+        "The GitHub CLI process did not provide linked issue output."
+    ),
+    operating_system_error: str = "The tool cannot collect linked issue comments",
     coverage_gap: type[RuntimeError] = LinkedRequirementsCoverageGap,
 ) -> bytes:
-    """Run one deadline-bound GitHub request with bounded stdout and stderr."""
+    """Run one deadline-bound GitHub request with bounded output streams."""
     command = ["gh", *arguments]
     effective_timeout = (
         LINKED_ISSUE_COMMENT_REQUEST_TIMEOUT_SECONDS
@@ -732,7 +769,8 @@ def bounded_gh_output(
             )
         except FileNotFoundError as error:
             raise RuntimeError(
-                f"required command unavailable: {error.filename or command[0]}"
+                "The required command is not available: "
+                f"'{error.filename or command[0]}'."
             ) from error
         stdout = process.stdout
         stderr = process.stderr
@@ -777,10 +815,16 @@ def bounded_gh_output(
             message = (
                 bytes(stderr_capture.output).decode("utf-8", errors="replace").strip()
             )
-            raise RuntimeError(message or f"gh {' '.join(arguments)} failed")
+            raise RuntimeError(
+                message
+                or f"The GitHub CLI command failed. Command: gh {' '.join(arguments)}"
+            )
         return bytes(stdout_capture.output)
     except OSError as error:
-        raise RuntimeError(f"{operating_system_error}: {error}") from error
+        raise RuntimeError(
+            f"{operating_system_error}. "
+            f"The operation returned this diagnostic.\n{error}"
+        ) from error
 
 
 def paginated_issue_comments(
@@ -795,11 +839,11 @@ def paginated_issue_comments(
         aggregate_remaining_bytes = collection_budget.remaining_bytes()
         if remaining_bytes <= 0:
             raise LinkedRequirementsCoverageGap(
-                "linked issue comments exceed the safe byte limit"
+                "The linked issue comments exceed the safe byte limit."
             )
         if aggregate_remaining_bytes <= 0:
             raise LinkedRequirementsCoverageGap(
-                "linked issue requirements exceed the safe aggregate byte limit"
+                "The linked issue requirements exceed the safe aggregate byte limit."
             )
         collection_budget.reserve_comment_page()
         response = bounded_gh_output(
@@ -819,7 +863,7 @@ def paginated_issue_comments(
                 remaining_bytes,
                 aggregate_remaining_bytes,
             ),
-            limit_error="linked issue comments exceed the safe byte limit",
+            limit_error="The linked issue comments exceed the safe byte limit.",
         )
         bytes_read += len(response)
         collection_budget.record_bytes(len(response))
@@ -827,27 +871,33 @@ def paginated_issue_comments(
             page_comments = json.loads(response)
         except json.JSONDecodeError as error:
             raise RuntimeError(
-                "GitHub returned invalid linked issue comment pages"
+                "GitHub returned linked issue comment pages that are not valid."
             ) from error
         if not isinstance(page_comments, list):
-            raise TypeError("GitHub returned invalid linked issue comment pages")
+            raise TypeError(
+                "GitHub returned linked issue comment pages that are not valid."
+            )
         if not all(isinstance(comment, dict) for comment in page_comments):
-            raise RuntimeError("GitHub returned an invalid linked issue comment")
+            raise RuntimeError(
+                "GitHub returned a linked issue comment that is not valid."
+            )
         if page > MAX_LINKED_ISSUE_COMMENT_PAGES:
             if page_comments:
                 raise LinkedRequirementsCoverageGap(
-                    "linked issue comments exceed the safe page limit"
+                    "The linked issue comments exceed the safe page limit."
                 )
             return comments
         if len(comments) + len(page_comments) > MAX_LINKED_ISSUE_COMMENTS:
             raise LinkedRequirementsCoverageGap(
-                "linked issue comments exceed the safe comment limit"
+                "The linked issue comments exceed the safe comment limit."
             )
         collection_budget.record_comment_page(len(page_comments))
         comments.extend(page_comments)
         if len(page_comments) < LINKED_ISSUE_COMMENT_PAGE_SIZE:
             return comments
-    raise AssertionError("bounded linked issue comment pagination did not terminate")
+    raise AssertionError(
+        "The bounded linked issue comment pagination did not terminate."
+    )
 
 
 def structured_error(error: str, details: str) -> None:
@@ -862,7 +912,7 @@ def linked_issue_metadata(
     aggregate_remaining_bytes = budget.remaining_bytes()
     if aggregate_remaining_bytes <= 0:
         raise LinkedRequirementsCoverageGap(
-            "linked issue requirements exceed the safe aggregate byte limit"
+            "The linked issue requirements exceed the safe aggregate byte limit."
         )
     budget.reserve_request()
     response = bounded_gh_output(
@@ -878,43 +928,69 @@ def linked_issue_metadata(
         maximum_bytes=min(
             MAX_LINKED_REQUIREMENT_METADATA_BYTES, aggregate_remaining_bytes
         ),
-        limit_error="linked issue metadata exceeds the safe metadata byte limit",
+        limit_error="The linked issue metadata exceeds the safe metadata byte limit.",
     )
     budget.record_bytes(len(response))
     try:
         issue_data = json.loads(response)
     except json.JSONDecodeError as error:
-        raise RuntimeError("GitHub returned an invalid linked issue") from error
+        raise RuntimeError(
+            "GitHub returned a linked issue that is not valid."
+        ) from error
     if not isinstance(issue_data, dict):
-        raise TypeError("GitHub returned an invalid linked issue")
+        raise TypeError("GitHub returned a linked issue that is not valid.")
     return issue_data
 
 
 def linked_requirements(
-    metadata: dict[str, Any], budget: LinkedRequirementBudget | None = None
+    metadata: dict[str, Any],
+    budget: LinkedRequirementBudget | None = None,
+    requirement_issues: Sequence[str] = (),
 ) -> LinkedRequirements:
     """Bind every linked issue's requirement content and complete comment history."""
     references = metadata.get("closingIssuesReferences")
     if not isinstance(references, list):
-        raise TypeError("GitHub returned incomplete linked issue references")
+        raise TypeError("GitHub returned incomplete linked issue references.")
     identities = sorted(linked_issue_reference(issue) for issue in references)
     if len(identities) != len(set(identities)):
-        raise RuntimeError("GitHub returned duplicate linked issue references")
+        raise RuntimeError("GitHub returned duplicate linked issue references.")
+    selected: dict[str, tuple[str | None, str, int, str]] = {
+        identity[3]: identity for identity in identities
+    }
+    if len(selected) != len(identities):
+        raise RuntimeError(
+            "GitHub returned different identities for the same linked issue URL."
+        )
+    for url in requirement_issues:
+        match = re.fullmatch(
+            r"https://github\.com/([^/]+)/([^/]+)/issues/([1-9][0-9]{0,19})", url
+        )
+        if match is None:
+            raise RuntimeError("Use a canonical GitHub issue URL for each requirement.")
+        repository = require_github_repository(
+            f"{match[1]}/{match[2]}", "requirement issue repository"
+        )
+        selected.setdefault(url, (None, repository, int(match[3]), url))
     collection_budget = budget if budget is not None else LinkedRequirementBudget()
     items: list[LinkedRequirement] = []
-    for expected_id, repository, number, expected_url in identities:
+    for expected_id, repository, number, expected_url in sorted(
+        selected.values(), key=lambda identity: identity[3]
+    ):
         issue_data = linked_issue_metadata(repository, number, collection_budget)
         issue_id = issue_data.get("id")
         body = issue_data.get("body")
         if (
-            issue_id != expected_id
+            not isinstance(issue_id, str)
+            or not issue_id
+            or (expected_id is not None and issue_id != expected_id)
+            or isinstance(issue_data.get("number"), bool)
             or issue_data.get("number") != number
             or issue_data.get("url") != expected_url
             or not isinstance(issue_data.get("title"), str)
             or (body is not None and not isinstance(body, str))
             or not isinstance(issue_data.get("state"), str)
         ):
-            raise RuntimeError("GitHub returned incomplete linked issue requirements")
+            raise RuntimeError("GitHub returned incomplete linked issue requirements.")
         comments = sorted(
             canonical_json(comment, "linked issue comment")
             for comment in paginated_issue_comments(
@@ -929,7 +1005,7 @@ def linked_requirements(
         }
         items.append(
             LinkedRequirement(
-                id=expected_id,
+                id=issue_id,
                 repository=repository,
                 number=number,
                 url=expected_url,
@@ -938,6 +1014,7 @@ def linked_requirements(
                 ).hexdigest(),
             )
         )
+    items.sort(key=lambda item: (item.id, item.repository, item.number, item.url))
     document = canonical_json(
         [item.as_json() for item in items], "linked issue requirements"
     )
@@ -962,14 +1039,17 @@ def bounded_git_path_manifest(
             )
         except FileNotFoundError as error:
             raise RuntimeError(
-                f"required command unavailable: {error.filename or command[0]}"
+                "The required command is not available: "
+                f"'{error.filename or command[0]}'."
             ) from error
         stdout = process.stdout
         stderr = process.stderr
         if stdout is None or stderr is None:
             process.kill()
             process.wait()
-            raise RuntimeError("Git did not provide changed-path output")
+            raise RuntimeError(
+                "The Git process did not provide the required output streams."
+            )
         stdout_capture = ChangedPathStream(
             MAX_CHANGED_PATH_MANIFEST_BYTES, MAX_CHANGED_PATHS
         )
@@ -993,11 +1073,15 @@ def bounded_git_path_manifest(
                 process,
                 stdout_capture,
                 stderr_capture,
-                "changed-path manifest exceeds the safe byte limit",
+                "The changed-path manifest exceeds the safe byte limit.",
                 timeout_seconds=CHANGED_PATH_REQUEST_TIMEOUT_SECONDS,
-                stderr_limit_error="changed-path response exceeds the safe stderr limit",
-                deadline_error="changed-path provider exceeded the safe provider deadline",
-                output_error="cannot read immutable changed-path output",
+                stderr_limit_error=(
+                    "The changed-path response exceeds the safe standard-error limit."
+                ),
+                deadline_error=(
+                    "The changed-path provider exceeded the safe deadline."
+                ),
+                output_error="The tool cannot read immutable changed-path output.",
                 coverage_gap=ChangedPathCoverageGap,
             )
         except BaseException:
@@ -1009,16 +1093,19 @@ def bounded_git_path_manifest(
             message = (
                 bytes(stderr_capture.output).decode("utf-8", errors="replace").strip()
             )
-            raise RuntimeError(message or f"git {' '.join(arguments)} failed")
+            raise RuntimeError(
+                message or f"The Git command failed. Command: git {' '.join(arguments)}"
+            )
         return stdout_capture.paths
     except OSError as error:
         raise RuntimeError(
-            f"cannot collect immutable changed paths: {error}"
+            "The tool cannot collect immutable changed paths. "
+            f"The operation returned this diagnostic.\n{error}"
         ) from error
 
 
 def git_bytes(*arguments: str, cwd: Path | None = None) -> bytes:
-    """Run a read-only Git query and return its byte-exact stdout."""
+    """Run a read-only Git query and return its byte-exact standard output."""
     result: Any = run_command(
         ["git", *git_read_arguments(), *arguments],
         capture_output=True,
@@ -1032,17 +1119,19 @@ def git_bytes(*arguments: str, cwd: Path | None = None) -> bytes:
             message = stderr.decode("utf-8", errors="replace").strip()
         else:
             message = str(stderr).strip()
-        raise RuntimeError(message or f"git {' '.join(arguments)} failed")
+        raise RuntimeError(
+            message or f"The Git command failed. Command: git {' '.join(arguments)}"
+        )
     stdout = result.stdout
     if not isinstance(stdout, bytes):
-        raise TypeError("git returned non-byte output for immutable path evidence")
+        raise TypeError("Git returned non-byte output for immutable path evidence.")
     return stdout
 
 
 def immutable_range_paths(
     base_oid: str, head_oid: str, *, cwd: Path | None = None
 ) -> list[bytes]:
-    """Return validated NUL-safe paths from one immutable Git diff range."""
+    """Return validated null-byte-safe paths from one immutable Git diff range."""
     return bounded_git_path_manifest(
         (
             "-c",
@@ -1081,7 +1170,9 @@ def immutable_changed_paths(
     try:
         paths = tuple(entry.decode("utf-8") for entry in canonical_entries)
     except UnicodeDecodeError as error:
-        raise RuntimeError("Git returned a non-UTF-8 changed path") from error
+        raise RuntimeError(
+            "Git returned a changed path that is not valid 'UTF-8'."
+        ) from error
     canonical_bytes = b"".join(entry + b"\0" for entry in canonical_entries)
     return ChangedPathManifest(paths=paths, sha256=sha256(canonical_bytes).hexdigest())
 
@@ -1101,13 +1192,15 @@ def strict_changed_paths(
     expected: tuple[str, str],
     target: ExpectedReviewTarget,
 ) -> tuple[ChangedPathManifest, MaterializedSnapshot | None]:
-    """Derive strict paths locally or from a verified host-owned snapshot."""
+    """Derive strict paths locally or from a verified host-owned materialized snapshot."""
     base_oid, head_oid = expected
     if local_immutable_objects_available(base_oid, head_oid):
         return immutable_changed_paths(base_oid, head_oid), None
     base_ref = metadata.get("baseRefName")
     if not isinstance(base_ref, str):
-        raise TypeError("GitHub returned an invalid pull-request base ref")
+        raise TypeError(
+            "GitHub returned a pull-request base reference that is not valid."
+        )
     snapshot = materialize_snapshot(
         repository=target.repository,
         number=target.number,
@@ -1129,7 +1222,10 @@ def gh(*arguments: str, accepted_codes: tuple[int, ...] = (0,)) -> str:
         ["gh", *arguments], capture_output=True, text=True, check=False
     )
     if result.returncode not in accepted_codes:
-        raise RuntimeError(result.stderr.strip() or f"gh {' '.join(arguments)} failed")
+        raise RuntimeError(
+            result.stderr.strip()
+            or f"The GitHub CLI command failed. Command: gh {' '.join(arguments)}"
+        )
     return result.stdout
 
 
@@ -1142,12 +1238,12 @@ def head_bound_check_runs(repository: str, head_oid: str) -> list[dict[str, Any]
     for page_number in range(1, MAX_CHECK_RUN_PAGES + 2):
         if page_number > MAX_CHECK_RUN_PAGES:
             raise CheckEvidenceCoverageGap(
-                "GitHub check runs exceed the safe page limit"
+                "GitHub check runs exceed the safe page limit."
             )
         remaining_bytes = MAX_CHECK_RUN_BYTES - bytes_read
         if remaining_bytes <= 0:
             raise CheckEvidenceCoverageGap(
-                "GitHub check runs exceed the safe aggregate byte limit"
+                "GitHub check runs exceed the safe aggregate byte limit."
             )
         try:
             response = bounded_gh_output(
@@ -1164,32 +1260,40 @@ def head_bound_check_runs(repository: str, head_oid: str) -> list[dict[str, Any]
                         f"per_page=100&page={page_number}"
                     ),
                 ),
-                maximum_bytes=min(MAX_CHECK_RUN_PAGE_BYTES, remaining_bytes),
-                limit_error="GitHub check-run response exceeds the safe byte limit",
+                maximum_bytes=remaining_bytes,
+                limit_error="The GitHub check-run response exceeds the safe byte limit.",
                 timeout_seconds=CHECK_RUN_REQUEST_TIMEOUT_SECONDS,
                 stderr_maximum_bytes=MAX_CHECK_RUN_STDERR_BYTES,
-                stderr_limit_error="GitHub check-run response exceeds the safe stderr limit",
-                deadline_error="GitHub check-run provider exceeded the safe provider deadline",
-                output_error="cannot read GitHub check-run provider output",
-                unavailable_output_error="GitHub did not provide check-run provider output",
-                operating_system_error="cannot collect GitHub check runs",
+                stderr_limit_error=(
+                    "The GitHub check-run response exceeds the safe standard-error limit."
+                ),
+                deadline_error=(
+                    "The GitHub check-run provider exceeded the safe deadline."
+                ),
+                output_error="The tool cannot read GitHub check-run provider output.",
+                unavailable_output_error=(
+                    "The GitHub CLI process did not provide check-run output."
+                ),
+                operating_system_error="The tool cannot collect GitHub check runs",
                 coverage_gap=CheckEvidenceCoverageGap,
             )
         except RuntimeError as error:
             if isinstance(error, CheckEvidenceCoverageGap):
                 raise
             raise CheckEvidenceCoverageGap(
-                "GitHub did not return readable head-bound check evidence"
+                "GitHub did not return readable check evidence for the head object identifier."
             ) from error
         bytes_read += len(response)
         try:
             page = json.loads(response)
         except json.JSONDecodeError as error:
             raise CheckEvidenceCoverageGap(
-                "GitHub did not return readable head-bound check evidence"
+                "GitHub did not return readable check evidence for the head object identifier."
             ) from error
         if not isinstance(page, dict):
-            raise CheckEvidenceCoverageGap("GitHub returned a malformed check-run page")
+            raise CheckEvidenceCoverageGap(
+                "GitHub returned a check-run page that is not valid."
+            )
         page_total = page.get("total_count")
         page_runs = page.get("check_runs")
         if (
@@ -1199,21 +1303,23 @@ def head_bound_check_runs(repository: str, head_oid: str) -> list[dict[str, Any]
             or not isinstance(page_runs, list)
         ):
             raise CheckEvidenceCoverageGap(
-                "GitHub returned incomplete check-run evidence"
+                "GitHub returned incomplete check-run evidence."
             )
         if total_count is None:
             total_count = page_total
             if total_count > MAX_CHECK_RUNS:
                 raise CheckEvidenceCoverageGap(
-                    "GitHub check runs exceed the safe run limit"
+                    "GitHub check runs exceed the safe run limit."
                 )
         elif page_total != total_count:
             raise CheckEvidenceCoverageGap(
-                "GitHub returned inconsistent check-run totals"
+                "GitHub returned inconsistent check-run totals."
             )
         for run in page_runs:
             if not isinstance(run, dict):
-                raise CheckEvidenceCoverageGap("GitHub returned a malformed check run")
+                raise CheckEvidenceCoverageGap(
+                    "GitHub returned a check run that is not valid."
+                )
             run_id = run.get("id")
             run_head_oid = run.get("head_sha")
             if (
@@ -1229,69 +1335,98 @@ def head_bound_check_runs(repository: str, head_oid: str) -> list[dict[str, Any]
                 or COMMIT_OID.fullmatch(run_head_oid) is None
             ):
                 raise CheckEvidenceCoverageGap(
-                    "GitHub returned incomplete check-run evidence"
+                    "GitHub returned incomplete check-run evidence."
                 )
             if run_head_oid != head_oid:
                 raise CheckEvidenceCoverageGap(
-                    "GitHub returned a check run bound to a different head OID"
+                    "GitHub returned a check run that is bound to a different head "
+                    "object identifier."
                 )
             run_ids.add(run_id)
             runs.append(run)
         if len(runs) == total_count:
             return runs
         if not page_runs:
-            raise CheckEvidenceCoverageGap("GitHub returned partial check-run evidence")
-    raise AssertionError("bounded check-run pagination did not terminate")
+            raise CheckEvidenceCoverageGap(
+                "GitHub returned partial check-run evidence."
+            )
+    raise AssertionError("The bounded check-run pagination did not terminate.")
 
 
 def pr_metadata(
     pull_request: str, target: ExpectedReviewTarget | None
 ) -> dict[str, Any]:
-    """Read one PR through the retained target when strict evidence is required."""
+    """Read one pull request through the retained target when strict evidence is required."""
     command = ["pr", "view", pull_request]
     if target is not None:
         command.extend(("--repo", target.repository_argument()))
     command.extend(("--json", FIELDS))
     metadata = json.loads(gh(*command))
     if not isinstance(metadata, dict):
-        raise TypeError("GitHub returned an invalid pull-request object")
+        raise TypeError("GitHub returned a pull-request object that is not valid.")
     return metadata
 
 
+def merge_readiness(metadata: dict[str, Any]) -> dict[str, str]:
+    """Return forge approval state as evidence separate from the review verdict."""
+    decision = metadata.get("reviewDecision")
+    if not isinstance(decision, str) or not decision:
+        decision = "UNAVAILABLE"
+    approval_gate = {
+        "APPROVED": "satisfied",
+        "CHANGES_REQUESTED": "blocked",
+        "REVIEW_REQUIRED": "blocked",
+    }.get(decision, "unknown")
+    return {
+        "auto_merge_approval_gate": approval_gate,
+        "authority": (
+            "Repository-policy evidence excluded from the review verdict and scope digests."
+        ),
+        "review_decision": decision,
+    }
+
+
 def main(argv: Sequence[str] | None = None) -> int:
     parser = argument_parser(description=__doc__)
     parser.add_argument(
         "--expected-base-oid",
         metavar="BASE_OID",
-        help="immutable base revision returned by resolve_pr.py",
+        help="Use the immutable base revision from 'resolve_pr.py'.",
     )
     parser.add_argument(
         "--expected-head-oid",
         metavar="HEAD_OID",
-        help="immutable head revision returned by resolve_pr.py",
+        help="Use the immutable head revision from 'resolve_pr.py'.",
     )
     parser.add_argument(
         "--expected-host",
         metavar="HOST",
-        help="canonical GitHub host returned by resolve_pr.py",
+        help="Use the canonical GitHub host from 'resolve_pr.py'.",
     )
     parser.add_argument(
         "--expected-repository",
         metavar="OWNER/REPOSITORY",
-        help="canonical GitHub repository returned by resolve_pr.py",
+        help="Use the canonical GitHub repository from 'resolve_pr.py'.",
     )
     parser.add_argument(
         "--expected-pr-number",
         metavar="NUMBER",
         type=int,
-        help="canonical pull-request number returned by resolve_pr.py",
+        help="Use the canonical pull-request number from 'resolve_pr.py'.",
     )
     parser.add_argument(
         "--expected-pr-url",
         metavar="URL",
-        help="canonical pull-request URL returned by resolve_pr.py",
+        help="Use the canonical pull-request URL from 'resolve_pr.py'.",
     )
     parser.add_argument("pull_request", metavar="PR_NUMBER_OR_URL")
+    parser.add_argument(
+        "--requirement-issue",
+        action="append",
+        default=[],
+        metavar="ISSUE_URL",
+        help="Bind another GitHub issue. Use this option for each non-closing requirement.",
+    )
     arguments = parser.parse_args(argv)
     pull_request = arguments.pull_request
     expected = expected_identity(
@@ -1306,17 +1441,20 @@ def main(argv: Sequence[str] | None = None) -> int:
         arguments.expected_pr_url,
     )
     require_immutable_identity = expected is not None
+    if arguments.requirement_issue and not require_immutable_identity:
+        parser.error("All strict identity arguments are necessary for this option.")
     try:
         validate_pr_identifier(pull_request)
         requested = pull_request_number(pull_request)
         if target is not None:
             if requested != target.number:
                 raise RuntimeError(
-                    "requested pull request does not match the expected target number"
+                    "The requested pull request does not match the expected target "
+                    "number."
                 )
             if pull_request.startswith("https://") and pull_request != target.url:
                 raise RuntimeError(
-                    "requested pull request does not match the expected target URL"
+                    "The requested pull request does not match the expected target URL."
                 )
         metadata = pr_metadata(pull_request, target)
         metadata_problem = metadata_error(
@@ -1337,15 +1475,18 @@ def main(argv: Sequence[str] | None = None) -> int:
             or not isinstance(number, int)
             or not isinstance(url, str)
         ):
-            raise TypeError("GitHub returned incomplete repository or PR identity")
+            raise TypeError(
+                "GitHub returned an incomplete repository or pull-request identity."
+            )
         pull_repository = repository_from_pr_url(url, number)
         if pull_repository.casefold() != repository.casefold():
             raise RuntimeError(
-                f"pull request {url} does not belong to current repository {repository}"
+                f"Pull request '{url}' is not in the current repository '{repository}'."
             )
         if number != requested:
             raise RuntimeError(
-                "GitHub returned a pull request different from the requested identifier"
+                "GitHub returned a pull request that is different from the requested "
+                "identifier."
             )
         identity = immutable_identity(
             metadata,
@@ -1359,7 +1500,9 @@ def main(argv: Sequence[str] | None = None) -> int:
             LinkedRequirementBudget() if expected is not None else None
         )
         reviewed_linked_requirements = (
-            linked_requirements(metadata, linked_requirement_budget)
+            linked_requirements(
+                metadata, linked_requirement_budget, arguments.requirement_issue
+            )
             if expected is not None
             else None
         )
@@ -1410,7 +1553,7 @@ def main(argv: Sequence[str] | None = None) -> int:
                 )
             )
             if not isinstance(checks, list):
-                raise RuntimeError("GitHub returned invalid check evidence")
+                raise RuntimeError("GitHub returned check evidence that is not valid.")
         final_metadata = pr_metadata(pull_request, target)
         final_problem = metadata_error(
             final_metadata, require_immutable_identity=require_immutable_identity
@@ -1425,21 +1568,23 @@ def main(argv: Sequence[str] | None = None) -> int:
         )
         if final_identity != identity:
             raise RuntimeError(
-                "immutable pull-request identity changed while collecting evidence"
+                "The immutable pull-request identity changed during evidence collection."
             )
         ensure_expected_identity(final_identity, expected)
         ensure_expected_target(final_identity, target)
         final_scope = review_scope(final_metadata) if expected is not None else None
         if final_scope != reviewed_scope:
-            raise RuntimeError("review scope changed while collecting evidence")
+            raise RuntimeError("The review scope changed during evidence collection.")
         final_linked_requirements = (
-            linked_requirements(final_metadata, linked_requirement_budget)
+            linked_requirements(
+                final_metadata, linked_requirement_budget, arguments.requirement_issue
+            )
             if expected is not None
             else None
         )
         if final_linked_requirements != reviewed_linked_requirements:
             raise RuntimeError(
-                "linked issue requirements changed while collecting evidence"
+                "The linked issue requirements changed during evidence collection."
             )
     except ChangedPathCoverageGap as error:
         structured_error("changed path coverage gap", str(error))
@@ -1454,7 +1599,12 @@ def main(argv: Sequence[str] | None = None) -> int:
         "changed_files": changed_files,
         "changed_paths": changed_files,
         "checks": checks,
-        "pull_request": final_metadata,
+        "pull_request": {
+            key: value
+            for key, value in final_metadata.items()
+            if key != "reviewDecision"
+        },
+        "merge_readiness": merge_readiness(final_metadata),
     }
     if identity is not None:
         evidence["reviewed_identity"] = identity.as_json()