Refresh Stale PR

Refresh a stale pull request

The PRs this is for are the maintainer's own: a branch on jggonz/os8088, usually one focused change, cut from a main that has since moved by tens of commits. Nobody else is going to push to it. The question is never "is this code good in the abstract" - it was good enough to open - but "is it still right on the main that exists today, and does anyone still need it".

It exists because PR #200 (the imager keeping SYSTEM.CFG) was 28 commits stale, merged with no conflict at all, passed every test it shipped - and was still wrong on today's main: #203 had taken FAT16 volumes to 2GB and the in-OS installer writes partition type 06h past 32MB, which the PR's reader refused. Git, the PR's tests and the fast tier all reported nothing. Finding it took reading what main gained around the PR, not in its files. Read LESSONS.md before step 3.

The user is the maintainer. Decisions that are theirs - close a PR, change its scope, merge it - go through AskUserQuestion or wait for their word; everything else you decide and record in the PR body.

1. Which PR, and is this the right skill

The number(s) may arrive as the argument (/refresh-stale-pr 200, or 200 201 for several, done one at a time). With none, list the candidates - the open PRs whose base has moved - and ask:

gh pr list --state open --json number,title,headRefName,headRepositoryOwner,updatedAt,isDraft

Then the facts:

gh pr view <N> --json number,title,state,isDraft,headRefName,headRepositoryOwner,\
baseRefName,mergeable,mergeStateStatus,additions,deletions,changedFiles,body,commits
gh pr view <N> --json comments,reviews --jq '.comments[].body, .reviews[].body'
git fetch -q origin main <headRef>
BASE=$(git merge-base origin/main origin/<headRef>)
git rev-list --count $BASE..origin/main                     # how stale
gh pr diff <N> --name-only

• headRepositoryOwner is not jggonz ⇒ stop and use review-fork-pr: pushing to origin would not update a fork's PR (that skill's LESSONS §1).
• state is not OPEN ⇒ say so and stop.
• Draft ⇒ ask whether it is meant to be finished now; a draft is often parked on purpose.

Tell the user the shape in two lines: what it does, how far behind, which files, conflicting or not.

2. Preflight - a worktree of its own

git rev-parse --is-shallow-repository     # true => git fetch --unshallow first (docs/UPSTREAM.md rule 0)
git worktree list | grep <headRef>        # the branch is often ALREADY checked out elsewhere

The PR's branch is usually still checked out in the worktree it was written in (../os8088-<feature>), so git worktree add <path> <headRef> refuses. Do not touch that worktree - it may hold the user's uncommitted work. Make a local branch off the remote head instead, and push it to the PR's branch by name at the end:

git worktree add -b pr<N>-refresh /tmp/pr<N> origin/<headRef>

/tmp/pr<N>, not the scratchpad: QMP and the zharness use AF_UNIX sockets with a ~104-byte path limit, and a scratchpad path is too long for them. The user's main checkout stays untouched for the whole run - other sessions write to it.

3. Merge main in

cd /tmp/pr<N> && git merge --no-edit origin/main

A conflict is resolved by docs/UPSTREAM.md's defaults (ours for what the PR deliberately changed, theirs for what it merely lacks). Then the checks a clean merge reports nothing about:

grep -oE '^#+ [0-9.]+' SPEC.md | sort | uniq -d    # a § number both sides took
python3 tools/checkdocs.py
python3 tools/os88index.py --check                 # docs/INDEX.md is generated

A § number main took while the PR sat open is the common collision: the PR's section renumbers (it is the newcomer now), with every reference to it.

Run the PR's own tests on the merged tree before editing anything - that separates "main's drift broke it" from "my fix broke it".

4. Is it still valid, and still needed?

This is the step the skill exists for. Two questions, answered with evidence:

Still needed? - has main already done this, or removed the thing it changes?

git log --oneline $BASE..origin/main -- <every file the PR touches>
git log --oneline $BASE..origin/main --grep '<the feature's key words>'

Grep main for the PR's new function names, flags and SPEC wording. If main superseded it, the answer is to recommend closing, with the commit that superseded it - ask before closing, never close unasked.

Still valid? - the PR's files merging cleanly says nothing about the code they call or the formats they read. For every module, tool, constant and on-disk format the PR depends on (not just the ones it edits):

git diff $BASE origin/main --stat -- <dependencies>
git diff $BASE origin/main -- <dependency> | less       # read it

Then read the commit titles of everything main gained and ask, of each one in the PR's subject area, does the PR's assumption still hold? Usual suspects: a format version bump (PKG_FMT, DRV_VER, SC_VER), a file that moved (SYSTEM/, APPDATA/), a limit that grew (volume size, cluster size, entry count), a new geometry, an API slot relayout, a knob made default. Check the kernel's own acceptance rules (what it mounts, what it reads, what version it refuses) against what the PR accepts - a host tool stricter than the kernel refuses real users' disks.

Say the verdict to the user plainly - valid and needed / needs fixes / superseded - with the commit or file that decides it, before fixing.