Read complete pull-request review evidence from a workflow

[taras]

Story

As a workflow author, I want authenticated, complete pull-request review evidence to be readable through host-owned components, so a network-denied reviewing Agent and the supervising user receive the existing objections and check results before they decide what happens next.

Motivation

The supervised composition in #301 must give both the reviewing Planner and the user every existing review body, pull-request comment, and check result. <PullRequest> deliberately returns only stable evidence about the upsert it reconciled; later reviews, comments, and checks are separate reads.

<Fetch> is not this boundary. It is credential-free, performs one GET or HEAD per invocation, and has no pagination contract. Raw authored credential headers are retained document data rather than host authentication, cannot reliably reach a private repository, and would bypass the adapter-private destination and credential ceiling.

Authoring contract

The workflow host registers three self-closing components beside <PullRequest>:

<PullRequest.Reviews number={pullRequest.number} as="reviews" />
<PullRequest.Comments number={pullRequest.number} as="comments" />
<PullRequest.Checks number={pullRequest.number} as="checks" />

• Each component has one required positive-integer prop, number, requires ordinary as, accepts no content, and returns one JSON array.
• The enclosing retained Repository and selected checkout identify the Git repository. There is no repository, URL, host, provider, endpoint, token, credential, page, cursor, or limit prop.
• Reviews, comments, and checks are separate reads and separate durable effects. One may replay or fail independently of the others; no partial three-list result exists.
• The values are closed, provider-neutral normalized records. Their implementation plan freezes the exact item schemas before coding. Original review and comment bodies and check conclusions/messages needed by the reader remain byte-for-byte unchanged; raw provider responses and live handles never cross the component boundary.
• PullRequest.Comments accounts for both pull-request conversation comments and inline review comments. It tags their normalized records so the two kinds cannot be confused.
• PullRequest.Checks accounts for every check/status result the GitHub pull-request UI associates with the exact head commit read for the numbered pull request. A moved head produces evidence for the newly observed head and retains that head SHA with the result; it is never silently combined with an earlier snapshot.
• Arrays retain the adapter's deterministic page/item order. An empty array means the authenticated provider completed the collection and found none.

The components render nothing. The caller iterates their arrays with <Each> into the Planner prompt and the user's checkpoint material; it does not stringify or summarize the original evidence.

Authority and authentication

The first adapter is GitHub for repositories on github.com.

• It reuses the host credential broker shipped by 🔐 Reach a private repository as whoever is running the host #532: GH_TOKEN, then GITHUB_TOKEN, then the machine's gh auth token, acquired lazily for the exact retained locator and disposed with that invocation.
• The adapter-private ceiling decides which retained repository the credential may reach. Public middleware, props, bindings, a same-name repository component, generated source, and another loaded package copy may narrow or refuse but cannot recover the credential or widen the destination.
• The pull-request number is checked against the request and retained Repository. A response naming another repository, pull request, or head is a provider protocol failure rather than data.
• A completed replay opens no authentication session and performs no network request.

Pagination and completeness

Reuse the GitHub adapter's existing pagination boundary: PAGE_SIZE = 100 and PAGE_LIMIT = 32.

• Follow GitHub's authenticated pagination until the collection is complete.
• A next relation is followed only on the adapter's authorized API origin.
• A malformed, off-origin, cyclic, unreadable, or still-present next relation at the page limit makes the read unavailable.
• Transport failure, rate limiting, authentication failure, an ambiguous 404, malformed JSON, an unreadable item, or an incomplete page walk is unavailable. None becomes an empty or truncated array.
• The component publishes its result only after the complete collection and every normalized item have been validated.

Retention, replay, and failure

Each invocation is one non-mutating durable read whose identity includes the retained Repository identity, pull-request number, and collection kind. A checks result additionally retains the pull-request head SHA it observed, so the evidence says which revision it describes.

The normalized request and complete result cross the existing secret gate before persistence. No credential, endpoint, raw response, provider identity, host path, or pagination transport state is retained.

Completed replay restores the exact array without authentication or another request. Interruption before the durable result commits may repeat the authenticated GETs; no incomplete list is retained. An unavailable or protocol-invalid read fails the stage with a fixed diagnostic and binds nothing. It never lets the reviewing workflow continue as though there were no existing objections.

Acceptance and focused evidence

• A private github.com repository is read through the 🔐 Reach a private repository as whoever is running the host #532 credential broker without exposing or retaining the credential.
• Each component validates its closed self-closing shape before contacting the provider and binds its closed normalized array only through as.
• Reviews preserve every review body; comments preserve every conversation and inline-review body with an explicit kind; checks preserve every result associated with the exact observed head.
• Multi-page fixtures beyond one page return every item exactly once in deterministic order.
• Empty completed collections bind []; unavailable, malformed, off-origin, cyclic, over-limit, rate-limited, unauthorized, and ambiguous-404 walks fail and bind nothing.
• A payload for another repository, pull request, or head is refused as a protocol failure rather than published.
• Reviews, comments, and checks are three distinct durable effects. Completing one does not manufacture either of the others.
• Completed replay performs zero HTTP and credential-broker calls and returns byte-identical normalized evidence.
• Interruption before commit retains no partial array; continuation performs the unfinished read and commits one complete result.
• The complete bodies and check evidence reach both the Compose the supervised adversarial implementation workflow #301 Planner prompt and checkpoint material unchanged; replay performs no second read.
• Ordinary xmd run remains unchanged. The components are installed only by a live or partial workflow host; a completed workflow replay installs no provider.
• Architecture, executable-MDX, workflow-Workspace, and component inventory prose describe the authenticated read, completeness rule, retention, replay, and failure boundary in present tense.

Focused provider evidence belongs with the existing GitHub adapter suite in packages/workflow/tests/pull-request-github.test.ts; component and durable replay evidence belongs in a new focused pull-request-read suite. The Planner freezes the exact normalized item schemas and named test cases before the Implementor handoff.

Dependencies

• 🔐 Reach a private repository as whoever is running the host #532 supplies the shared GitHub credential broker and per-invocation authentication lifetime.
• Add a deterministic PullRequest workflow effect #295 supplies retained Repository/PullRequest identity and the existing GitHub adapter and pagination machinery.
• Add workflow inspection, cancellation, suspension, and deletion #367 supplies retained workflow lifecycle and replay ownership.
• Compose the supervised adversarial implementation workflow #301 consumes this surface in the supervised adversarial composition and renders its results to the Planner and user.
• 🌐 Fetch retained HTTP observations from Markdown #456 remains the general credential-free <Fetch> boundary and is not widened by this issue.

Out of scope

• Pull-request creation, update, merge, close, review submission, commenting, rerunning checks, or any other mutation.
• Giving an Agent network access, credentials, native tools, a Workspace path, or a direct provider handle.
• Adding authentication, pagination, mutating methods, or provider selection to <Fetch>.
• A generic Git-host query language, raw REST/GraphQL component, caller-selected endpoint, or public credential reference.
• Non-GitHub adapters in the first delivery.
• Generated-XMD admission of these components.
• Workflow scheduling or unattended review polling.