Stacked PRs

Stacked PRs

Build, publish, synchronize, validate, merge, and clean up stacked pull requests without corrupting branch topology.

The package identity is provider-neutral. Git is the source of truth for branch ancestry; provider PR metadata is the source of truth for review bases. GitHub through gh is the first documented provider adapter.

Reference Files

When To Use

Core Rules

• Run git rev-parse --show-toplevel before any workflow.
• Run git status --porcelain before rebases, pushes, PR creation, PR retargeting, merge, or cleanup.
• Stop on a dirty worktree unless the user explicitly scopes the operation to inspection only.
• Prefer existing PR baseRefName values over inferred ancestry.
• Resolve <base> from the root PR's baseRefName (gh pr view <root-pr> --json baseRefName --jq .baseRefName), not from origin/HEAD; a stack's trunk need not be the repository's default branch.
• Use explicit branch order or .stack-prs.yaml when parent inference is ambiguous.
• Never use plain git push --force; use git push --force-with-lease origin <branch>.
• Merge from root to leaf. Never merge a child before its parent.
• Do not delete unmerged stack branches without explicit user instruction.
• Stamp Stack-Id and Stack-Position trailers on every commit the skill creates or splits; copy the ID from .stack-prs.yaml or mint it once when absent.
• Verify trailers are present and consistent before merge.
• Probe every open stack PR for native-stack membership during Inspect (references/stack-model.md § Native Stack Detection) before merge planning; a detected native stack makes the manual merge path in §5 unavailable, not merely discouraged.
• Detect the provider's squash message policy (squash_merge_commit_message) before merging with --squash. Fold trailers into the squash body only when the policy is PR_BODY or BLANK; under COMMIT_MESSAGES (GitHub's default) trailers already survive automatically.

GitHub-native stack mode

GitHub-native stacks are public preview and same-repository-only. They enhance manual Armory stacks; they do not replace provenance trailers, .stack-prs.yaml, or the provider-neutral workflow.

Native-stack membership is a provider-side property of a pull request, not a mode this skill chooses. Detect it for every stack PR during Inspect, before any merge planning, whether or not github-native mode was requested.

Creating native state (opt-in)

Converting a manual stack to native with gh stack link is a mutation with public-preview risk. Use it only after this eligibility probe passes:

1. GitHub CLI plus gh stack --help succeeds; install github/gh-stack when absent.
2. Native stack support is enabled for the repository; native exit code 9 falls back to manual mode.
3. Every proposed head/base branch and pull request belongs to the same GitHub repository; reject forks and cross-repository stacks.
4. Existing PR bases, local branch order, and Stack-Id/Stack-Position provenance agree. Stop on disagreement.
5. The user explicitly requests native mode or accepts its public-preview risk.

Operating on an already-native stack (mandatory)

Once Inspect finds a PR already native, native mode is not a choice for any operation that mutates that PR: the provider refuses a plain synchronous merge mutation (gh pr merge, and the underlying mergePullRequest/PUT .../pulls/{n}/merge) for a stack member with "must be merged using the asynchronous merge REST API." There is no manual Armory merge path for an already-native stack; do not present one as an alternative. Conditions 1-4 above still apply as safety checks; condition 5's user consent does not — a stack the provider already registered as native carries no additional preview risk beyond what already exists.

When eligible or already native:

• Link existing branches or PRs bottom-to-top with gh stack link --base <base> <branch-or-pr>....
• Inspect both Armory provenance and the GitHub-native stack position.
• Sync with gh stack sync; re-read gh stack view after every non-interactive sync and use gh stack rebase plus gh stack push for non-linear history.
• Merge the entire stack only on an explicit user request; invoke gh stack merge --yes --merge-method <merge|squash|rebase> with no positional argument. For a partial prefix, require the exact highest PR number and run gh stack merge <pr-number> --yes --merge-method <merge|squash|rebase>. Outside a merge queue, GitHub merges every lower layer atomically.
• Before choosing --squash, check gh api repos/{owner}/{repo} --jq '.squash_merge_commit_message'. Trailers survive automatically under COMMIT_MESSAGES (GitHub's default). Under PR_BODY they survive only if every PR body already carries them. Under BLANK they are always lost and gh stack merge has no --subject/--body override to fold them back in — change the repository's policy first or merge with --merge-method merge/rebase instead.
• gh stack merge exposes no --subject/--body. With squash_merge_commit_title: COMMIT_OR_PR_TITLE (GitHub's default), a PR squashing a single commit takes that commit's headline as the base-branch subject, not the PR title, and this cannot be corrected after merge without rewriting pushed history. When the visible subject matters for a single-commit PR under --merge-method squash, align the commit headline with the PR title first (git commit --amend -m "<pr-title>", then force-with-lease push) before running gh stack merge.
• For a merge queue, method flags are ignored and stack members may land in separate queue groups; require explicit queue acceptance and verify each group.
• Re-fetch and verify the remaining stack topology, CI, and provenance after GitHub's cascading rebase/retarget.

Fall back to the manual workflow only when the stack is not yet native: the creation probe fails, the stack spans a fork, the preview surface is unavailable, or provider/trailer topology differs. Never silently switch modes mid-stack, and never attempt the manual merge path once Inspect has found the stack is already native.

Workflow

1. Inspect

Build a stack model without modifying anything:

git rev-parse --show-toplevel
git status --porcelain
git branch --show-current
git for-each-ref --format='%(refname:short)' refs/heads
git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'
gh pr list --state open --json number,title,headRefName,baseRefName,state,url

Produce a table with one row per stack branch. Run the native-stack probe (references/stack-model.md § Native Stack Detection) for every PR before recording this table:

Stop when no provider adapter is available, no local branches match the requested stack, or parent order cannot be inferred from PR bases, explicit order, or metadata.

2. Publish

Create missing PRs and retarget wrong bases:

git status --porcelain
git push -u origin <branch>
gh pr create \
  --base <parent-branch> \
  --head <branch> \
  --title "<title>" \
  --body-file <generated-body-file>
gh pr edit <number> --base <parent-branch>

Generated PR bodies must include the stack order and validation state:

## Stack

Stack-Id: `auth-refactor-a1b2c3`
Base: `main`
Position: 1/3

1. `feat/parser-core` -> this PR
2. `feat/parser-cache` -> #102
3. `feat/parser-cli` -> #103

Depends on: (none - root)
Upstack: #102

## Validation

- Pending: commands not run yet

For non-root PRs, Depends on: lists the parent PR number. Upstack: lists the immediate child PR number when known.

Stop when a branch has no commits beyond its parent, an existing PR is closed and unmerged, or the provider rejects base retargeting.

3. Sync

Rebase each stack branch onto its parent after <base> or any parent branch moves:

git status --porcelain
git fetch origin --prune
git switch <branch>
git rebase <parent-branch>
git push --force-with-lease origin <branch>

Start at the first branch above the base and continue toward the leaf. Stop on conflicts, remote lease failures, or a parent PR that closed without merge.

4. Validate

Validate the stack as reviewable slices. Run cheap checks on every branch when practical; run expensive full checks on the leaf when branch-by-branch validation is not reasonable. Record exactly what ran in each PR body.

Use the target repository's detected local gate and provider checks. Do not run armory package-evaluation commands when operating on another repository's stack.

For this armory package implementation only, use:

uv run python scripts/validate_evals.py
uv run python scripts/generate_manifest.py
uv run python scripts/evaluate_package.py --path skills/stacked-prs