The merge scripts read pull request snapshots, reviews and the local diff through one Go reader #862

Problem

Every merge-pr script starts from one saved gh pr view response and reads it with helpers in pull-request.sh (165 lines): the field reader, the base commit lookup, the review-decision refusal, the review pages with author types, and the local fetch of pinned base and head objects with the complete diff. This is under the shell freeze in #588. The check-rollup judge in the same file is a separate outcome handled by child 21.

Part of #324, within #588. Child 04 in #324's Children list. Replaces the snapshot, review-page, base-commit, review-decision and local-diff parts of packages/agents/source/skills/merge-pr/shared/scripts/pull-request.sh.

Acceptance criteria

1. AC1: Given a pull request number, when the snapshot is read, then the requested fields are saved from one GitHub response, and when unattended gating is on and reviews is requested, the review pages with author type are read pinned to that same head.
2. AC2: Given the head moves while review pages are read, when the snapshot is built, then it fails with an error, exits non-zero, and hands the caller no usable snapshot; the files left behind on this failure are the same as the frozen reader leaves (the initial snapshot may remain on disk), and no caller reads it after the failure.
3. AC3: Given a review decision of REVIEW_REQUIRED or CHANGES_REQUESTED, when the snapshot is checked, then the caller gets the WAITING_REVIEW message on stderr and exit status 75; given APPROVED, empty or NONE, then it passes; given any other value, then it fails naming the value.
4. AC4: Given a pinned base and head commit, when the local diff is built, then the objects are fetched without moving a branch, the index or FETCH_HEAD, fork heads included, a shallow clone is unshallowed, and the complete binary diff and the name-status list are written with the same content as the frozen reader writes for the same fixtures, including a diff large enough to exceed a single pipe buffer.
5. AC5: Given GitHub reports a rate limit, when any reader fails, then the caller sees the original error and the status the shared reader assigns it, with no retry.
6. AC6: Given the base branch name, when the base commit is read, then it is the commit the branch points at on GitHub for the repository gh merges in, and an absent ref fails with base ref not found.
7. AC7: Non-functional: the readers run against a fake gh and a scratch Git repository in tests, and run on macOS, Linux and Windows in CI.

Scope and non-goals

Scope: the snapshot, review-page, base-commit, review-decision and local-diff readers, with tests ported from merge-workflow.bats.

Non-goal: the check-rollup verdict (child 21). Non-goal: the unattended gates themselves (child 05). Non-goal: new command-line surface; these are readers consumed by children 05 to 12. Non-goal: changing the shell scripts before child 14.

Approach

Meet AC1 to AC7 with failing cases first: record the shell readers' output on fixtures, then match it. Mechanism is the implementer's choice.

Dependencies

Blocked by: #333.

Prerequisites: #321 (GitHub identity and quota helpers) and #333.

Size

S. One pull request.

Verify plan

• AC1, AC2: fake-gh tests, one that returns a moved head between pages, asserting the exit status, the error text and the set of files left behind against the frozen reader's on the same fixture.
• AC3: table over review decisions checking status and stderr.
• AC4: scratch repositories, including a shallow clone, a fork-style pull ref and the large-diff and shallow-history scenarios of merge-workflow.bats, asserting branch, index and FETCH_HEAD unchanged and comparing the written diff and name-status files byte for byte with the frozen reader's.
• AC5: a fake gh that prints each rate-limit shape.
• AC6: a fake gh that returns and omits the ref.
• AC7: the CI matrix run.
• Definition of done: D1 each AC is verified at the merged head, with the commands and results cited in the pull request's Verification. D2 an independent review approves the exact merged head, and every finding has a recorded disposition. D3 required checks pass with no gate loosened. D4 the leak scans the repository specifies are clean, and every post made for this work passes the per-post leak review before it is posted. D5 every commit is signed. D6 the documentation matches the change or the Verification says why there is no impact. D7 every commit has an Assisted-by trailer and the pull request has the provenance:agent-assisted label. D8 the pull request stays within the size limits. D9 follow-ups are filed as issues and listed under Related. D10 the merge closes the issue through a closing reference, the board shows Done, and the final Status: comment names the merge commit.

Risks

A reader that moves a branch or the index would disturb the operator's checkout; AC4 holds that. A snapshot taken across a moving head would bind the wrong review; AC2 holds that. Undo: revert; nothing calls these readers until children 05 and later.

Operator authority

None.