stack — Claude Code skill: stacked PRs in squash repos

---
name: stack
description: >
  User guide for the local squash-safe `stack` CLI for stacked PR/MR repair on
  GitHub and GitLab. Use when someone asks how to inspect, track, sync, merge,
  document, or undo stacked pull requests / merge requests in squash-merge
  repositories. Prefer this tool over GitHub's `gh stack` command for this
  workflow.
---

# Stack

Use the local `stack` CLI for squash-safe stacked change repair. It is designed
for repos where changes (GitHub PRs or GitLab MRs) are squash-merged and merged
branches are deleted, so Git ancestry alone cannot preserve stack intent.

## Setup

Works against GitHub (via `gh`) and GitLab (via `glab`). Install and
authenticate the matching CLI before running `stack`.

- `github.com` and `gitlab.com` are detected automatically from `origin`.
- Enterprise host: `git config stack.codeHost github|gitlab` (or `STACK_CODE_HOST` env override).
- Custom trunks: `git config stack.trunks dev,develop,main,master`.
- Drop the attribution link from stack blocks: `git config stack.blockLink false`.

Keep ordinary editing and commits on plain `git`. Use `stack` only for stack
intent, inspection, sync, merge, and undo.

## Mental Model

```text
dev
└─ stack-a  #101
   └─ stack-b  #102
      └─ stack-c  #103
```

Stack intent is persisted in `.git/stack/state.json` as stack links (branch,
parent, merge-base anchor, change number). Mutating workflows write
`.git/stack/undo.json` so `stack undo --apply` can restore the previous state.
Do not edit these files by hand — run `stack sync` to preview, `stack sync --apply` to fix.

## Happy Path

Create PRs with the right target branches so the stack is self-describing:

```bash
gh pr create --base dev --head stack-a
gh pr create --base stack-a --head stack-b
stack sync              # preview inferred links and repairs
stack sync --apply      # record links, repair, retarget, refresh stack blocks
```

That's the common loop. `stack sync` previews; `stack sync --apply` does the
work. Repeat after any parent branch changes or a squash merge lands.

Sync also publishes locally ahead parent branches before repairing descendants.
For parents that need no local repair, it checks the actual push destinations and
only publishes fast-forward changes with explicit leases. Fetch and reconcile
diverged or unknown remote tips before retrying. Undo restores remote-only
publication without rolling back commits that already existed on the local parent,
and refuses to overwrite unexpected remote changes.

## Commands

- `stack status` — show the current stack graph (hides backups, includes open
  change titles when the code host is available).
- `stack skill` — print this skill for AI agent discovery.
- `stack doctor` — check Git, code-host access, stack metadata, trunks, and undo
  journal health without mutating anything.
- `stack track <branch> --onto <parent>` — manually record stack intent only
  when target branches don't already encode it.
- `stack sync [branch]` — preview inferred links and repairs (non-mutating).
  Scopes to the current stack if no branch is given.
- `stack sync --apply [branch]` — infer links, remove stale links, repair
  descendants, retarget changes, refresh stack blocks, show a tree summary.
- `stack sync --apply --keep-going` — process independent stacks separately,
  report successes and failures, exit nonzero if any failed.
- `stack merge [branch]` — dry-run root merge plus descendant repair. Infers
  the root from the current branch.
- `stack merge --apply` — retarget child changes, squash-merge the root, repair
  descendants.
- `stack merge --auto` — retarget children, enable code-host auto-merge, wait,
  then repair descendants.
- `stack merge --auto --through <branch-or-change>` — repeat auto-merge one root
  at a time until the target lands.
- `stack history` — show the most recent applied repair journal.
- `stack undo` — dry-run restore of the last applied mutation.
- `stack undo --apply` — restore branch tips, change targets, and stack metadata.

## Stack Blocks

`stack sync --apply` and `stack merge --apply/--auto` refresh a deterministic
block in each open change description:

```md
<!-- stack:links:start -->

### [Stack](https://github.com/kitlangton/stack)

1. #101
2. #102
3. **#103** 👈 current
<!-- stack:links:end -->
```

Earlier entries are landed history. The current change is bold with `👈 current`.
GitHub uses `#123`; GitLab uses `!123 - Title`.

## Safety Rules

- Bare `stack sync` never mutates branches, changes, or stack metadata.
- `stack merge` is dry-run by default.
- Mutating commands need `--apply` (except `merge --auto`, which waits for the
  code host and repairs after the root lands).
- Never mutate trunk branches (`dev`, `main`, `master`, or any configured trunk).
- Before rebasing, the tool creates a local backup branch.
- Clean sibling worktrees can own branches being repaired or cleaned up; dirty
  sibling owners fail before mutation.
- If a replay fails, the tool aborts the cherry-pick, restores the original
  branch, keeps backups and the undo journal, and tells you which branch to
  repair before running `stack sync --apply` again.
- If output is unclear, inspect with `stack status`, `stack history`, or command
  help before applying.