Read a pull request and its changes from executable documents

[taras]

Story

As an executable-document author with a pull request URL, I want to read that pull request's details and exact changes, so an XMD workflow can review the right revision without invoking gh or parsing provider-specific responses.

Example outcome

A workflow starts with one known canonical pull request URL and reads:

• its number, title, body, author, state, and timestamps;
• its base and head references and exact commit SHAs;
• its ordered commits and changed files; and
• its complete base-to-head diff.

Those values compose with the existing evidence reads:

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

The exact component names and whether details and changes are separate public forms remain product-interface decisions. The lasting outcome is a provider-neutral snapshot that an executable document can read from a known URL.

Current gap

The existing pull-request read components return reviews, comments, and checks. They do not return the pull request's general metadata, commits, changed files, or diff.

<PullRequest> creates or updates a pull request after an authorized <Git.Push>; it is not a general read. Review workflows therefore fall back to gh pr view and gh pr diff, then expose provider-specific output to later steps.

Package and Plugin boundary

#822 is a prerequisite. It places the provider-neutral pull-request components, APIs and durable records together with GitHub authentication and adapters in one bundled @executablemd/git Plugin, active by default for run/workflow execution. There is no separate git-host or GitHub package or Plugin.

A GitHub-backed read therefore needs no Plugin selector beyond the bare run/workflow profile. The operation chooses the bundled GitHub adapter from its canonical URL and trusted host ceiling. Loading the Plugin alone reads no GitHub configuration or credential and starts no transport; missing or unusable provider configuration refuses only the invoked GitHub read, before transport.

Read contract

Provide read-only values for two independently useful operations:

1. Read one pull request's identity and general metadata from its canonical URL.
2. Read its exact change evidence: base and head SHAs, ordered commits, changed files, and complete diff.

Details and change evidence may remain separate components because a potentially large diff has a different failure and reuse boundary from metadata. Neither operation returns a partly successful aggregate.

Every result is normalized and closed over documented fields. Provider tokens, API endpoints, pagination cursors, raw responses, and transport diagnostics do not enter document bindings, rendered output, or journals.

Change evidence identifies the exact base and head it describes. If the pull request advances during a multi-request read, the operation retries against one snapshot or refuses. It never combines metadata, commits, files, or diff content from different heads.

Host boundary

The canonical pull request URL names the subject. The trusted host decides which pull requests may be read before it reads a credential or contacts a provider, following the existing XMD_WORKFLOW_GITHUB_PULL_REQUESTS boundary.

GitHub is the first adapter, but its response shapes do not become the XMD contract. An ordinary xmd run performs a fresh read. A workflow run retains and replays the normalized result through the existing pull-request read execution boundary.

These reads grant no Git push, pull-request update, comment publication, check publication, merge, or issue mutation permission.

Product-interface decisions before implementation

Settle with the Product Owner:

• the exact component names and whether details and changes are separate public forms;
• whether a change read accepts an expected head SHA or returns and internally verifies one snapshot; and
• how a complete diff that exceeds a provider or host limit refuses and tells the author what to do next.

Acceptance

• An executable document reads normalized metadata for one configured canonical pull request URL without a shell command.
• The read components, contracts, GitHub authentication and transport adapter belong to the one bundled default Git Plugin, behind distinct provider-neutral and provider-specific module boundaries.
• Loading the bundled Plugin alone performs no GitHub configuration read, credential lookup or transport; an invoked GitHub-backed read with missing or unusable configuration refuses before transport.
• It reads ordered commits, changed files, and a complete diff tied to exact base and head SHAs.
• The same document composes those results with <PullRequest.Reviews>, <PullRequest.Comments>, and <PullRequest.Checks>.
• An unauthorized pull request refuses before credential lookup or network access.
• Missing authentication, incomplete pagination, rate limiting, malformed provider data, an unavailable oversized diff, and a head that changes during collection cannot become an empty, truncated, or mixed successful answer.
• Provider credentials, endpoints, cursors, and raw responses never cross the normalized read boundary.
• Completed workflow replay performs no provider request; an ordinary run reads current data.
• Existing comment, review, check, and pull-request upsert behavior remains unchanged.
• .reviews/AnalyzeReviewFeedback.md can replace its gh pr view and gh pr diff collection with the delivered components.
• The code-review workflow can inspect the exact pull-request subject without depending on recent-pull-request listing.

Evidence

Focused tests cover exact snapshot identity, endpoint pagination, moving-head refusal or retry, a complete large diff, every incomplete or unavailable case, credential ordering, normalized results, ordinary execution, and durable replay.

An integration document reads a controlled pull request using the new components plus the existing comments, reviews, and checks components. A negative control advances the head between provider calls and proves that no mixed snapshot is returned. Plugin-profile coverage proves that the complete Git Plugin is present once by default, while zero-effect coverage proves that merely loading it reaches no GitHub configuration, credential or transport boundary.

Related work

• Make Git and GitHub available in XMD runs and workflows #822 establishes one bundled default Git Plugin containing the GitHub adapter and must be delivered before this story.
• Read complete pull-request review evidence from a workflow #576 delivered the existing URL-addressed reviews, comments, and checks reads.
• Search GitHub issues and pull requests in the current repository #815 owns bounded, deterministic listing of recent pull requests. Listing may supply a URL to this story but is not required when the URL is already known.
• Quest: Run Codex code review from the README as an Actions check #813 and Run Codex code review from the root README as an Actions check #534 consume this capability for the repository's Codex review check.
• Add an executable pull-request description workflow #680 consumes general pull-request evidence for description generation and staleness checks.
• 🏭 Add reconciled GitHub projection effects #700 owns reconciled GitHub projection mutations, not this read-only surface.

Out of scope

• Discovering or listing pull requests in a repository.
• Creating, updating, closing, merging, or marking a pull request ready.
• Posting comments or publishing check results.
• Replacing the existing reviews, comments, or checks components.
• Exposing raw GitHub REST or GraphQL response shapes.