gh-stack ยท diff

git:20261012.5177130 to git:20261014.e6467ee

10 added, 11 removed. Audit A to A.

---
name: gh-stack
description: Load when deciding whether to use gh stack or working on dependent, stacked GitHub pull requests
license: MIT
---
## Choose the path
- - Fetch any named PR first. Inspect its base, head, and downstack PRs with the official GitHub MCP; a branch name or installed extension alone does not establish a stack.
- - One independent PR: use the normal GitHub MCP workflow, not `gh stack`. This dotfiles repository deploys without PRs.
- - Two or more dependent PRs (or a stack the user asked to manage): use stack-aware operations for branch order, remote stack linking, and atomic stack merge. Existing PR base chains need not be adopted into local `gh stack` tracking just to work on one layer.
- - Check `gh stack --help` for extension availability and `gh stack view --json` for a locally tracked stack. If unavailable or not tracked, do not assume stack metadata; inspect the PRs through the MCP. Each `gh *` invocation goes through Bash and requires its own OMP approval, including reads. Do not route it through Eval.
+ - Fetch a named PR first. Inspect its base, head, and downstack PRs with the official GitHub MCP; a branch name or installed extension alone does not establish a stack.
+ - Keep changes small and independently reviewable. Use `gh stack` when dependent PRs form a stack; one independent PR uses the normal GitHub workflow. The dotfiles repository deploys without PRs.
+ - Check `gh stack --help` for extension availability and `gh stack view --json` for a locally tracked stack. If unavailable or untracked, do not assume stack metadata; inspect PRs through the MCP. Run CLI operations through Bash, not Eval.
## Build or maintain
- - For new local tracking, only with a clean checkout whose branches are not checked out in other worktrees: `gh stack init --base <trunk> <bottom-branch> <next-branch> ...` adopts existing branches or creates missing ones in bottom-to-top order. `gh stack add <branch>` adds above the current layer. Verify branch ancestry and intended PR bases before remote writes.
- - Create or edit individual PRs with the official GitHub MCP; push an individual branch through the normal approval-gated git workflow. Set the bottom PR base to trunk and each higher PR base to the branch below. Preserve existing draft and reviewer state unless requested otherwise.
- - To register **existing** PRs as a GitHub stack without local tracking, use `gh stack link <bottom-PR-URL> <next-PR-URL> ...` only after verifying every member and base. Use PR URLs/numbers, not branch arguments: branch arguments can push and create PRs. Linking mutates remote stack membership; check resulting PR bases and stack membership afterward.
- - `gh stack submit` pushes every branch, creates PRs, updates existing PR bases, and creates/updates the remote stack. Its interactive editor defaults new PRs to ready; `--auto` skips the editor and defaults new PRs to draft; `--open` can change existing PRs to ready. Prefer individual MCP PR writes plus `link`, not `submit`, when exact titles, bodies, draft states, and targets must be approved in advance.
- - Do not use `gh stack sync` as a read or routine update: it fetches, cascade-rebases, force-with-lease atomically pushes branches, and syncs PR/stack state. `gh stack push` also uses force-with-lease and can partially update branches. After review, avoid rebasing away comment anchors; inspect the entire stack before either command.
- - For an atomic stack merge, inspect all downstack members first. `gh stack merge` includes every PR below the chosen one; non-interactive or `--yes` can merge the whole stack without a picker. A merge queue may only enqueue it. Do not claim merged until the PRs show merged through the MCP.
+ - Initialize local tracking only from a clean checkout whose branches are not checked out in other worktrees: `gh stack init --base <trunk> <bottom-branch> <next-branch> ...` adopts existing branches or creates missing ones in bottom-to-top order. `gh stack add <branch>` adds above the current layer. Verify branch ancestry and intended PR bases.
+ - Create or edit individual PRs with the official GitHub MCP. Set the bottom PR base to trunk and each higher PR base to the branch below. Preserve existing draft and reviewer state.
+ - To register existing PRs without local tracking, use `gh stack link <bottom-PR-URL> <next-PR-URL> ...` only after verifying each member and base. Use PR URLs/numbers, not branch arguments: branch arguments can push and create PRs. Check resulting PR bases and stack membership.
+ - `gh stack submit` pushes every branch, creates PRs, updates existing PR bases, and creates or updates the remote stack. Its interactive editor defaults new PRs to ready; `--auto` skips the editor and defaults new PRs to draft; `--open` can change existing PRs to ready. Inspect intended titles, bodies, draft states, and targets before submitting.
+ - Do not use `gh stack sync` as a read or routine update: it fetches, cascade-rebases, force-with-lease pushes branches atomically, and syncs PR/stack state. `gh stack push` also uses force-with-lease and can partially update branches. Inspect the entire stack before either command; after review, avoid rebasing away comment anchors.
+ - `gh stack merge` includes every PR below the selected one. Inspect all downstack members before merging; non-interactive or `--yes` can merge the whole stack without a picker. A merge queue may only enqueue it. Verify PRs show merged through the MCP before claiming completion.
- Before **each** push, PR change, link, sync, submit, or merge: show the exact repository, branch/PR set, bases, title/body/draft state if applicable, and command/API payload; request explicit approval for that exact remote write and wait. For an operation whose interactive UI conceals the final payload, use individual MCP writes instead. Re-read remote state after a partial or uncertain write before retrying.
+ OMP permissions configuration governs prompts. Do not add conversational approval requests or bypass configured gates. Re-read remote state after a partial or uncertain write before retrying it.