Why upper stack PRs sit on a parking branch

A three-layer Mergestorm stack does not restack every pull request every time the bottom one moves. That looks wrong if you are used to Graphite-style “always rebase the whole chain.” It is the product.

The live seam moves. Everything above it sits still until it has to move.

Two layers, one freeze

Take a stack with three open PRs:

1. PR1 is the live bottom. Its base is trunk (main, or the review-unit branch). When its parent moves, this PR restacks and Vortex reviews the new head.
2. PR2 is the seam child — position 2. When PR1 moves or lands, this is the layer we restack. It is the only descendant in that cascade.
3. PR3 and above sit on a parking freeze named mg-park-{unit}-g{generation}. That branch is an immutable snapshot of PR2’s tip at park time. Their GitHub base points at the freeze on purpose.

mg stack submit opens layer 3+ onto that freeze so GitHub never has to flip the base after opened. Adopt does the same for an existing chain: ensureLazyUpperPark freezes the seam child’s tip and retargets PR3+ onto mg-park-*.

If those upper PRs are already on the same freeze, park is a no-op. We do not mint g2. We do not retarget. We do not wake Vortex.

Why park at all

Restacking a whole stack is honest and expensive.

Each restack force-pushes a new head. Each new head is a Vortex pass — Core, plus whatever specialist lanes that PR already hired. On a five-layer stack, one one-line fix on the bottom PR becomes four follow-up reviews you did not ask for. The upper diffs did not change. The reviews still run.

Parking cuts that. The bottom and the seam stay live. PR3+ keep the same head and the same GitHub base until a promote, a merge, or a seam change that actually needs a new freeze. Same commits. Same review. Less compute.

That is the point: faster stack reviews, less churn, and the same correctness when an upper layer becomes the seam.

What restack does — and what it does not

When a stacked parent lands, or when the live bottom is rewritten, restack rebases the seam child only.

The cascade is a two-layer chain: trunk (or the new parent) plus the direct child. Parked grandchildren keep their heads. After a successful restack we retarget the seam PR’s GitHub base to the new parent. We do not walk PR3+ and rebase them onto the new seam tip.

If you open PR3 on GitHub and the base is still mg-park-12-g1 after PR1 picked up a commit, that is the model. It is not a missed rebase.

The freeze is the fork point. When that parked layer later becomes the seam, restack uses the freeze tip as the old base — not the just-moved parent’s head — so the child’s own commits replay once.

Generations

Each freeze has a generation: mg-park-12-g1, then g2 if we mint another.

g1 is created when the stack first grows past two layers — submit or adopt. The freeze SHA is the seam child’s tip at that moment. Freezes are never force-pushed.

A later generation is minted when the freeze has to change: the seam child’s tip moved, and remaining upper layers need a new snapshot. Promote and submit are the usual reasons. The bottom PR moving, by itself, is not.

Already-parked tips stay on their freeze until they become the seam. No g2, no base flip, no extra review.

If GitHub still points at g1, look at whether a newer generation exists. Sitting on the current freeze while the live seam moves is working as designed. Sitting on g1 after g2 was minted, with no retarget, is a different contract — the upper PR should follow the new freeze when we actually create one.

When an upper PR does move

PR3 stays parked until one of these is true:

• It becomes the seam. PR1 landed. PR2 is now the live bottom. PR3 is the new seam child, so the next restack belongs to it.
• A new generation is required. Promote or submit needs a freeze at a new seam tip. Then we mint g2 and the remaining upper PRs should base on that freeze.
• It was never parked. Mixed or live bases get parked onto a freeze once. After that, same no-op.

Until then, leave it. Do not rebase PR3 “to catch up.” Do not treat mg-park-*-g1 as stale because PR1 moved.

How to read GitHub

GitHub shows one base ref per PR. On a parked layer that ref is mg-park-{unit}-gN, not the parent’s feature branch. The diff is the upper layer against the frozen seam tip.

That is enough to review PR3 on its own commits. You do not need PR1’s latest restack in that diff. When PR3 becomes the seam, it will pick up the live parent and Vortex will review that head.

Two-layer stacks never park. There is no grandchild to freeze. Legacy stacks without a review unit still do a full descendant cascade. The parked model is the review-unit path — the one mg stack submit registers.

Try it

mg login
mg stack create feat/one
# edit + commit
mg stack create feat/two
# edit + commit
mg stack create feat/three
# edit + commit
mg stack submit

PR1 bases on trunk. PR2 bases on PR1. PR3 bases on mg-park-*-g1. Push another commit to PR1. PR2 restacks. PR3 does not.

More on the CLI in Stacked PRs from your terminal and on /cli.