vouchington-tooling 0.43.0 → 0.44.0

package/skills/stacked-prs/references/drain.md

@@ -0,0 +1,168 @@
+# Drain and keep track
+
+Shepherding a layer to ready and merging are different acts. The first covers every pull request
+the worker owns in the stack at once. The second lands the ready prefix in one command, and it is
+never the agent's own decision.
+
+## Establish scope
+
+1. Resolve the stack from `pulls/<any-layer>.stack`, and record whether the field was present. A
+   stack object supplies its number; an explicit `null` means no registered stack. A missing
+   preview field: query `stacks?pull_request=<N>`, where one result is the stack and zero means
+   unstacked. Do not treat an empty `.stack.number` alone as proof
+   that a pull request is unstacked.
+2. Read topology from `repos/{owner}/{repo}/stacks/<n>`, ordered bottom to top. A
+   `closed && merged_at == null` layer below an open one means the stack is broken. Report it to
+   the human, and never merge across it.
+3. Partition by ownership, using that topology read plus each member's body from `pulls/<N>` (the
+   stack response has no bodies). Shepherd only owned pull requests. Never
+   poll, fix, rebase, or push the others, but list them in every report. Owned means this session
+   opened the pull request, or a human named it in this session.
+   - The opened-by-me half is a durable remote fact when the repository's pull request description
+     tool stamps each body with the authoring harness and session id. Compare the stamp with the
+     current session id.
+   - The named-by-a-human half is conversational and cannot be recovered remotely. That is
+     acceptable, because the human can restate it after a compaction.
+   - Degrade explicitly. A body without a matching stamp, or with a stamp naming no session id,
+     is not owned. Report it as "ownership unverifiable" and never poll it.
+   - A parent may assign its stack to one worker by listing the pull request numbers and the
+     session id stamped on them. The worker treats that list as assigned and still refuses any
+     layer outside it.
+
+## Shepherd the owned layers
+
+Run one stack shepherd poll for the assigned stack, and follow its printed instructions.
+
+- A shepherd's own "owned" mark can mean only that the author login equals the authenticated
+  viewer. Several sessions often share one account, so filter every printed row against the
+  ownership partition above before acting. Never start a per-pull-request session, fix, or push
+  for a row outside it, even when the shepherd marks it owned.
+- Apply code fixes, rebases, pushes, and review mutations to owned layers only. Report work
+  surfaced on an unowned layer to the human.
+- Fix on the owning layer. Commit there, rebase the layers above it (`gh stack rebase --upstack`),
+  `gh stack sync` when there are no local stack commits, `gh stack push` once, then rerun the
+  shepherd.
+  `rebase --upstack` and `push` act through the top of the stack. When an unowned layer sits above
+  an owned one, stop at that layer: do not rebase or push it, and hand the remaining rebase and
+  push to its owner.
+- Start the shepherd with the first pull request. While the poll is in a pure wait and the
+  worktree is clean, commit the next layer once the lower layer is in decent shape. On a
+  fix-code result, finish it on the owning layer before more upper edits. A ready-delay schedules
+  the rerun: continue owned work on a later layer, and do not invent unrelated work.
+- Never run a printed merge command unless the human's approval covers that layer and every open
+  layer below it, and the checks below pass. `gh stack merge <pr>` lands that pull request and
+  every layer below it.
+- Mutating git does not parallelize. Stop the poll before a rebase, sync, or push in the stack's
+  shared worktree, because other layers' branches can be rewritten underneath it. Discard a poll
+  result that was in flight across the mutation, and start the poll again after the push lands.
+  Run at most one git mutation at a time.
+
+### Upper-only fast-forward
+
+A queued lower layer, or any lower layer that must not be rewritten, does not stop an upper-only
+fast-forward, or upper review and CI work that does not write git.
+
+- Before that push, read the forge and capture the parent head, the parent base, the upper remote
+  head, and the stack order. Read all four again immediately before pushing.
+- Push only when all four still match, the local upper commit fast-forwards that remote head, and
+  it still contains the parent. If anything differs, or the lower layer merges or leaves the queue
+  meanwhile, stop and read the forge again. Never push from a stale capture.
+- Do not amend, force-push, `gh stack sync`, or `gh stack rebase` a queued parent: each rewrites
+  it. When the lower layer changes, re-read topology before branch work that depends on the new
+  parent.
+
+### Escalations persist to the pull request
+
+When a layer needs a human, because it is ready and waiting on a merge decision or genuinely
+blocked:
+
+- Apply the repository's needs-human label and post one comment per escalation event, not per
+  poll, with the layer's position and what it needs.
+- When a layer re-escalates, minimize the superseded comment (GraphQL `minimizeComment`,
+  `classifier: OUTDATED`). Clear the label once the layer no longer needs a human.
+- A relayed merge command is for visibility only. The shepherd picks its target from ready
+  results alone and does not know what the human approved.
+
+## Report
+
+When the owned set settles, present the stack bottom to top: each layer's number, owner, state,
+and whether it is ready or blocked and why. Never leave a ready bottom layer under a blocked upper
+layer without saying so.
+
+## Merge the ready prefix
+
+The ready prefix is the bottom-most open layer plus every consecutive layer above it that is also
+ready and inside the approval. Its top layer is the merge target. A shepherd that prints a merge
+of its highest ready layer may name a layer above the approved range. Target the highest approved
+layer of the prefix instead; that is still one command.
+
+Merge only on explicit human approval. The approval names what it covers: one layer, a range, or
+the whole stack. Approving the whole stack also covers the next ready prefix after an earlier
+merge. It does not cover a layer added after the approval. Ask before merging any layer outside
+it.
+
+Immediately before each approved merge, run these checks in order:
+
+1. `gh api repos/{owner}/{repo}/stacks/<target>` must return 404. `gh stack merge` resolves a bare
+   number as a stack number first, then a pull request number. A 200 response means `--yes` would
+   merge every layer of that stack. Stop and ask.
+2. Re-read topology. Confirm every layer from the bottom-most open layer up to the target is open,
+   ready, and inside the approval, with nothing broken below.
+3. For every layer in the prefix, capture `pulls/<N>.head.sha` before the final poll and after it.
+   They must match. A mismatch means a push landed inside the evaluation window: discard the
+   verdict and poll again.
+4. `gh stack merge <target> --yes` with the repository's merge strategy. It lands the target and
+   every open layer below it, which is the ready prefix.
+5. Do not `gh stack sync` here. Return to step 2 of [Establish scope](#establish-scope) and
+   re-read topology remotely: rebasing right after a merge can replay already-landed commits from
+   a stale local base ref. Keep shepherding the layers above. When the new bottom is ready, merge
+   the next ready prefix the same way. Before any local edit, rebase, or push on a remaining
+   layer, rerun the fetch and ahead/behind check in
+   [Import a stack](gh-stack.md#import-a-stack-before-acting-on-it): GitHub rebases the next
+   layer remotely, so local upper branches are stale until fast-forwarded. The drain is complete when no unmerged owned layer remains.
+
+The window between the last head read and the merge cannot be closed, because `gh stack merge`
+has no head-SHA pin. Branch protection and rulesets are evaluated when the merge runs, and stacks
+cannot bypass merge requirements. If the merge is rejected, re-read topology instead of retrying
+blindly. Under a merge queue, a successful `gh stack merge` only enqueues: the prefix queues
+together, and a failing layer is ejected along with the layers above it. The next topology
+re-read handles that.
+
+When you stop or are blocked (an unresolved escalation, an interrupt or pause, repeated fixes with
+no progress, or an external blocker), report each layer's number and state. If the bottom layers
+are ready, ask whether to merge that ready prefix before continuing.
+
+## Keep track: derive the ledger
+
+A hand-kept list of "pull requests I opened" drifts, and a compaction or new session erases it.
+The ownership stamp makes the ledger derivable, so state is re-read instead of recalled.
+
+Reconcile broadly, partition narrowly. A new session opens a rival stack because it never looks for
+the old one, so the reconcile query is deliberately unfiltered; only the partition is
+session-filtered:
+
+```bash
+# Reconcile, unfiltered: it finds stacks this session did not create.
+gh api --paginate repos/{owner}/{repo}/stacks --jq '.[] | select(.open)'   # 30 per page
+gh api --paginate "repos/{owner}/{repo}/pulls?state=open&per_page=100" \
+  --jq '.[] | {number, title, user: .user.login, body}'
+# Partition: apply the ownership check from Establish scope to that output.
+```
+
+- Reconcile before starting anything new. At the start of work, and before opening any pull
+  request or stack, surface every open stack or unfinished layer, whoever made it.
+- Close out; do not drift away. Close a layer that will not land. Ending or pausing a session with
+  owned open layers requires reporting them.
+- Continue the stack instead of starting a parallel one. Dependent work for an owned open stack is
+  a new layer (`gh stack add`, after the layer cap check). For an unowned open stack, report it and
+  ask instead of adding to it or starting a rival.
+- Derive state (which pull requests and stacks exist, their positions, their status) every time;
+  never cache it. Only intent, such as which stack is being built or what a planned layer is for,
+  belongs in the session's plan or journal, and it is a plan, not a record.
+
+Known gaps:
+
+- An ownership stamp is a body line any writer can edit. It is a signal, not an authorization
+  boundary, and that is sound only because every merge is human-gated.
+- Stack and pull request numbers share no guaranteed disjointness, which is why merge check 1
+  runs before every merge.

package/skills/stacked-prs/references/gh-stack.md

@@ -0,0 +1,143 @@
+# gh-stack mechanics
+
+Official docs (do not copy): [About](https://docs.github.com/en/pull-requests/get-started/about-stacked-prs),
+[CLI](https://docs.github.com/en/pull-requests/reference/stacked-prs-cli-commands),
+[Managing](https://docs.github.com/en/pull-requests/how-tos/create-pull-requests/managing-stacked-pull-requests),
+[Merging](https://docs.github.com/en/pull-requests/how-tos/merge-and-close-pull-requests/merging-stacked-pull-requests).
+
+## Setup
+
+- Install on first stacked use: `gh extension install github/gh-stack`. The feature is in public
+  preview.
+- If `gh stack` exits 9 (stacks are not enabled on the repository), do not bundle the source issues
+  into one pull request. Open one pull request on the default branch for the bottom issue, wait for
+  it to merge, then open the next. Say that stacks are unavailable.
+- Workflows that must run on stacked pull requests must not set `pull_request.branches` or
+  `branches-ignore`. GitHub evaluates `branches: [main]` against `stack.base.ref`, but
+  `gh stack submit` opens mid-stack pull requests before the stack object exists
+  ([github/gh-stack#425](https://github.com/github/gh-stack/issues/425)), so the filter skips them
+  permanently. After a workflow trigger change lands on the default branch, rebase existing stacks
+  (`gh stack rebase` or `gh stack sync`) so parent branches include it.
+
+## Agent commands
+
+Use only non-interactive forms, and run every `gh stack` command without a TTY. Run
+`git config rerere.enabled true` before the first `init`, which otherwise prompts. An explicit
+`checkout` prompts when local and remote compositions differ, and `submit --auto` prompts to
+create ordinary pull requests when stacks are disabled; without a TTY these fail instead, so treat
+a failure as the exit-9 recovery above rather than answering a prompt.
+
+- `gh stack init <branch>`, rooted on the default branch only.
+- `gh stack add <branch>`, after the layer cap check in [SKILL.md](../SKILL.md#work-bottom-up).
+- `gh stack checkout <stack-or-pr-number>` imports an existing remote stack. See
+  [Import a stack](#import-a-stack-before-acting-on-it).
+- `gh stack submit --auto` creates drafts. Immediately update each new pull request's title and
+  body with the repository's pull request description tool; auto titles and bodies are not
+  sufficient, and an unstamped body fails the ownership check in [drain.md](drain.md).
+- `gh stack link <branch-or-pr>...` (bottom to top) registers a stack without local tracking. It
+  pushes the branches and creates a draft pull request for any branch without one. Update each
+  pull request it created the same way as after `submit --auto`.
+- `gh stack view --json` is for acting only. Never use it, or `gh stack bottom`, to decide
+  topology, ownership, or bottom-ness.
+- `gh stack rebase`, `gh stack rebase --upstack`, `gh stack rebase --continue`,
+  `gh stack rebase --abort`.
+- `gh stack sync` fetches, fast-forwards the trunk, cascade-rebases every layer onto its updated
+  parent, and pushes all branches with `--force-with-lease --atomic`. It rewrites every layer's
+  head, so treat it like a rebase: stop the poll first, never run it over a queued layer, and
+  expect reviewed heads to change. Do not check out the default branch. Run it without a TTY (a
+  TTY prompts on local/remote divergence; without one it aborts) and without `--prune`.
+- `gh stack push`.
+- `gh stack up <n>`, `gh stack down <n>`, `gh stack top`, `gh stack bottom`, for movement only.
+- `gh stack merge <pr> --yes --squash`, or the repository's merge strategy. The pull request number
+  is required. `--yes` skips a prompt that a non-interactive runner cannot answer.
+- `gh stack unstack [<stack-number>]` (alias `delete`) recovers a mis-rooted stack. With no
+  argument it targets the active stack. It unstacks on GitHub and removes local tracking; add
+  `--local` to remove only local tracking. Pull requests and branches survive. GitHub leaves
+  queued or auto-merge pull requests stacked, and then keeps the stack.
+
+Never run the interactive forms: `gh stack submit` without `--auto`, `gh stack modify`, bare
+`gh stack checkout`, `gh stack switch`, or bare `gh stack merge` (a TUI that lands the whole
+stack). `gh stack checkout <branch>` resolves only stacks this worktree already tracks. Do not run
+`gh stack trunk` from a linked worktree whose default branch is checked out elsewhere.
+
+## Worktree and scope
+
+- One worktree per stack. Move with `up` and `down`. Do not add a worktree per layer:
+  `gh stack rebase --upstack` rewrites upper branches, and git refuses to update a branch checked
+  out in another worktree.
+- `git diff --name-only origin/<default>...HEAD` lists what lands if this layer and every layer
+  below merge.
+- `git diff --name-only <parent>...HEAD` is this layer's review scope.
+
+## Import a stack before acting on it
+
+`gh stack rebase`, `sync`, `push`, and movement act only on stacks the worktree's local record
+tracks. A stack created from another worktree, session, or machine is not tracked. Before rebasing
+or pushing a layer, including when a shepherd instruction says to, import the stack:
+
+1. `gh stack checkout <stack-number>`, with the number from `pulls/<N>.stack.number`. It records
+   the stack and checks out the top-most unmerged layer. When the worktree already tracks a
+   matching stack it only switches branches, so remote-tracking refs can be stale.
+2. Resolve the remote gh-stack uses once (`remote.pushDefault` when set, else the only remote,
+   else `origin`), and read `origin` below as that remote.
+3. gh-stack keeps existing local layer branches as they are, so a stale one makes the next rebase
+   start from stale commits. Run `git fetch origin`, then for each unmerged layer branch `<b>` run
+   `git rev-list --left-right --count "$b...origin/$b"` (left: local-only commits; right: commits
+   only on the pull request head). Branch names may contain shell metacharacters: pass each as a
+   quoted variable, never paste it into a command line, and skip names that start with `-`:
+   - `0 0`: up to date.
+   - `0 N`: fast-forward. Use `git merge --ff-only origin/<b>` on the checked-out layer and
+     `git branch -f <b> origin/<b>` on any other.
+   - A left count above `0` (ahead or diverged): inspect before rewriting or pushing, as the
+     consumer's git procedure describes. Do not open another pull request for the layer.
+
+## Submit and verify the remote stack
+
+- A pull request's base branch selects its comparison target. Chaining bases alone does not
+  register a native stack. `gh stack init` and `add` record a local plan. Neither local tracking
+  nor a successful pull request creation proves GitHub registered the stack.
+- Once an upper layer has committed, reviewable work and its local checks pass, submit the layers
+  as drafts with `gh stack submit --auto` while the lower pull request is still open and unqueued.
+- Verify remote registration before asking to merge or enqueue the lower pull request. An open
+  pull request already in a merge queue cannot join a new stack. If it was queued externally, stop
+  registering and report the blocker. Do not dequeue it without authorization or rewrite it. When
+  it leaves the queue, re-read it: retry registration if it is still open and unqueued, or recover
+  as below if it merged. If it closed without merging, report the broken dependency.
+- Do not wait for upper-layer CI or ready status to register the dependency. Do not create empty
+  placeholder layers, or start work held for approval, only to preserve a stack.
+- After each submission or link, read every intended pull request's `pulls/<N>.stack` and the
+  single-stack endpoint. Require the same stack number, the intended bottom-to-top order, and the
+  expected bases. Missing preview metadata leaves membership unknown: report that, and do not infer
+  success from local tracking.
+- If the lower pull request merges before registration, GitHub can reject linking it. Re-read the
+  forge, fetch, and rebase the remaining work onto the updated default branch without replaying
+  the merged layer. Keep any upper pull request already created. Register several remaining open
+  layers as a stack and verify their bases. For a single survivor, read its remote base, retarget
+  it to the default branch if needed, and verify that before shepherding it alone: a head rebase
+  does not change a base. Report sequential pull requests when no stack registered. Do not recreate
+  the merged bottom or chain bases by hand as a substitute.
+
+## Lower-layer review fix
+
+Check out the layer that owns the change and commit there. Then run `gh stack rebase --upstack`
+and `gh stack push` once. Do not duplicate the fix in an upper layer.
+
+## The forge is the only truth
+
+Every fact the procedure branches on (topology, layer state, ownership, head SHA) comes from the
+REST or GraphQL API, never from local gh-stack metadata. A local base ref can go stale after a
+remote relink or rebase and silently replay already-landed commits. `gh stack view --json` also
+errors from a worktree whose current branch is not in the stack, which is normal right after a
+merge retargets it.
+
+```bash
+gh api "repos/{owner}/{repo}/pulls/<N>" --jq '{stackPresent: has("stack"), stack: .stack}'
+gh api "repos/{owner}/{repo}/stacks/<n>"   # layers bottom to top, with head.sha and author
+gh api --paginate "repos/{owner}/{repo}/stacks" --jq '.[] | select(.open)'   # state is null
+                                                                    # and ?state=open is ignored
+```
+
+- Use the single-stack endpoint for one stack's layers. The list form returns each layer's
+  `base.ref` as `null`.
+- `.stack` is a preview field. Its absence is not proof a pull request is unstacked: report "stack
+  membership unknown" instead of assuming it is unstacked.