# Stacked PRs: the problem, GitHub’s design, and how to build them from scratch

As of **August 22, 2026**, GitHub’s native Stacked Pull Requests feature is in public preview. GitHub announced the preview on July 30, 2026. ([The GitHub Blog][1])

The most important idea is this:

> **A stacked PR system is not merely a chain of pull requests with unusual base branches. It is an orchestration layer over ordinary Git branches and PRs.**

The branch chain gives you small, reviewable diffs. The first-class stack abstraction gives you everything else: ordering, policy inheritance, cascading rebases, stack-aware CI, merge-queue behavior, conflict handling, and the ability to merge a contiguous portion of the stack as one operation.

---

## 1. The basic model

Suppose a developer wants to ship a feature in three logical pieces:

1. Add the database schema.

2. Add the API.

3. Add the user interface.

Without stacking, the developer has two bad options:

* Put everything in one large PR.

* Wait for each PR to merge before beginning the next.

With stacked PRs, the Git history looks like this:

```text

A                         main

 \

  B                       feature/schema

   \

    C                     feature/api

     \

      D                   feature/ui

```

The corresponding pull requests are:

```text

PR 101: feature/schema → main

PR 102: feature/api    → feature/schema

PR 103: feature/ui     → feature/api

```

GitHub calls PR 101 the **bottom** of the stack because it is closest to the trunk branch. PR 103 is the **top** because it is furthest away. Each PR presents only the changes introduced by its own layer, even though the top branch contains the cumulative result of every layer below it. ([GitHub Docs][2])

Formally, let a stack be:

```text

S = [P₁, P₂, …, Pₙ]

```

where:

```text

base(P₁) = trunk

base(Pᵢ) = head(Pᵢ₋₁), for i > 1

```

For a healthy, fully restacked stack, the current commit graph should also satisfy:

```text

isAncestor(trunkTip, H₁)

isAncestor(H₁, H₂)

…

isAncestor(Hₙ₋₁, Hₙ)

```

where `Hᵢ` is the current head commit of the branch belonging to `Pᵢ`.

There are two different notions of “base”:

```text

directBase(Pᵢ) =

    trunk,               when i = 1

    head branch of Pᵢ₋₁, when i > 1

effectiveBase(Pᵢ) = trunk

```

That distinction is fundamental:

* The **direct base** determines what the reviewer sees in the PR diff.

* The **effective base** determines which branch protections, workflows, CODEOWNERS rules, and merge policies apply.

GitHub explicitly applies the stack’s trunk-branch policies to every PR in the stack, rather than allowing an intermediate feature branch to weaken or redefine policy for upper layers. ([GitHub Docs][3])

---

# 2. What problem stacked PRs solve

## 2.1 They decouple authoring throughput from merge latency

In a conventional PR workflow, a developer often finishes one change and then waits:

```text

write → open PR → wait for review → merge → begin next change

```

The waiting may take hours or days. Yet the developer already knows what the next dependent change should be.

A stack changes the workflow to:

```text

write layer 1 → open PR 1

write layer 2 → open PR 2

write layer 3 → open PR 3

```

Review and implementation proceed concurrently.

The developer does not need to merge schema work before writing API work. They can build the API on the schema branch while preserving a separate review boundary.

GitHub specifically presents this as a way to continue building dependent work without waiting for earlier PRs to merge. ([GitHub Docs][2])

## 2.2 They make reviews smaller without destroying dependency structure

A large feature might contain:

* schema changes,

* migrations,

* server types,

* business logic,

* API endpoints,

* client state,

* UI,

* tests,

* instrumentation.

A single 3,000-line PR is difficult to review. Splitting it into unrelated PRs is also difficult because later pieces cannot compile or function without earlier ones.

Stacking preserves the real dependency:

```text

UI depends on API

API depends on schema

```

while giving reviewers focused units:

```text

PR 1: Review the schema design.

PR 2: Review the API implementation.

PR 3: Review the UI.

```

This is qualitatively different from merely breaking work into commits. Each layer gets its own:

* discussion,

* reviewers,

* approval state,

* CI result,

* merge policy,

* audit trail,

* issue linkage,

* release metadata.

## 2.3 They make sequencing explicit

The stack is an explicit declaration that:

```text

P₁ must land before P₂

P₂ must land before P₃

```

Without a first-class s[118;1:3utack, this information is usually buried in:

* branch ancestry,

* PR descriptions,

* “Depends on #123” comments,

* naming conventions,

* or the author’s memory.

A first-class stack turns dependency order into enforceable data.

## 2.4 They automate cascading branch maintenance

Suppose review of the bottom PR requests a change:

```text

A---B---C---D

    ↑

  modify B

```

After modifying or rebasing `B`, the old `C` and `D` are based on the wrong history. They must be replayed:

```text

A---B'

     \

      C'

       \

        D'

```

Doing this manually is error-prone. A stack system can perform a **waterfall rebase** from the bottom upward, stopping at the first conflict and retaining enough state to continue or abort.

GitHub supports cascading rebases, and its open-source `gh-stack` CLI persists local stack and interrupted-rebase state under `.git/gh-stack`. ([GitHub Docs][2])

## 2.5 They prevent policy bypass through intermediate branches

A naïve chained-PR implementation often evaluates this PR:

```text

feature/api → feature/schema

```

as though `feature/schema` were its true destination.

That can create serious inconsistencies:

* Workflows configured for `main` might not run.

* `main`’s required checks might not apply.

* CODEOWNERS from a lower feature branch might replace the protected version.

* A lower layer could alter policy and thereby change the requirements for upper layers.

GitHub avoids this by evaluating every layer against the stack’s ultimate base branch. A workflow whose pull-request filter targets `main` can therefore run for every PR in a stack rooted at `main`, even when a PR’s direct base is another feature branch. ([GitHub Docs][3])

## 2.6 They make merging a coordinated operation

If three dependent PRs are ready, naïvely merging them requires:

1. Merge PR 1.

2. Retarget or rebase PR 2.

3. Wait for checks.

4. Merge PR 2.

5. Retarget or rebase PR 3.

6. Wait again.

7. Merge PR 3.

A stack-aware system can validate the entire contiguous prefix and merge it through a single user operation.

GitHub permits merging from the bottom through a selected PR. Selecting the top PR merges all PRs below it as well. It does not allow skipping a lower PR and merging a middle layer independently. ([GitHub Docs][4])

## 2.7 They are particularly well suited to coding agents

A coding agent naturally produces sequential units:

```text

Task 1: Add data model

Task 2: Add service

Task 3: Add endpoint

Task 4: Add frontend

Task 5: Add tests

```

Without stacks, the agent either creates a giant PR or must wait for humans between tasks. With stacks, it can maintain small review boundaries while continuing autonomously.

GitHub explicitly associates stacked PRs with higher-volume development and AI-assisted coding workflows. ([GitHub Docs][2])

---

# 3. What stacked PRs do not solve

Stacked PRs are a **linear dependency model**, not a universal dependency graph.

They do not naturally represent this:

```text

        PR B

       /    \

PR A          PR D

       \    /

        PR C

```

That is a DAG, not a stack.

They also do not solve:

* Cross-repository atomic changes.

* Independent changes that happen to be authored together.

* Semantic merge conflicts.

* Poor review discipline.

* Excessive CI cost.

* Long-lived branch divergence.

* Release-train coordination across many unrelated stacks.

* The need for feature flags when partially landed work must remain inactive.

GitHub’s current implementation is restricted to PRs in the same repository, which keeps the public model linear and avoids cross-repository branch, permission, and object-storage complications. ([GitHub Docs][2])

A useful rule is:

> Stack changes that must land in a specific linear order. Do not stack changes merely because one developer authored them consecutively.

---

# 4. Manual chained PRs versus a first-class stack

Developers have manually created stacked PRs for years by pointing each PR at the branch below it. That supplies only part of the system.

| Capability                          |  Manual branch chain | First-class stack |

| ----------------------------------- | -------------------: | ----------------: |

| Small per-layer diff                |                  Yes |               Yes |

| Explicit stack identity             |                   No |               Yes |

| Durable ordering                    |             Informal |          Enforced |

| Trunk policy applied to every layer |           Usually no |               Yes |

| Stack-aware CI metadata             |                   No |               Yes |

| Cascading rebase                    | Manual/tool-specific |        Integrated |

| Merge contiguous prefix             |     Multiple actions |     One operation |

| Merge-queue ordering                |              Unaware |       Stack-aware |

| Conflict recovery state             |               Ad hoc | Durable operation |

| Stack lifecycle/webhooks            |                   No |               Yes |

| Concurrency control                 |                   No |               Yes |

A branch chain answers:

> “What commit is this branch based on?”

A stack object answers:

> “Which PRs constitute one ordered unit of dependent work, what trunk do they ultimately target, what policy applies to them, and what operations may be performed across the group?”

That is why a serious implementation needs a server-side stack object.

---

# 5. How GitHub implemented stacked PRs

GitHub’s exact internal service architecture is not publicly documented. However, its public APIs, documentation, UI behavior, and open-source CLI reveal the external data model and much of the operational design.

## 5.1 Ordinary Git branches remain the storage model

GitHub did not introduce a new Git object type.

A stack still consists of:

* ordinary commits,

* ordinary branch refs,

* ordinary pull requests,

* ordinary base/head branch relationships.

The additional stack is collaboration metadata that links and orders those PRs. This is evident from GitHub’s stack API and from `gh-stack`, which creates or updates regular branches and PRs before creating or extending the server-side stack. ([GitHub Docs][5])

That is a good compatibility decision. Existing Git clients, fetches, branch protections, commit pages, and PR machinery continue to work.

## 5.2 GitHub has a first-class server-side stack object

GitHub’s REST representation includes concepts such as:

* stack ID,

* repository-scoped stack number,

* ultimate base ref,

* ordered pull requests,

* open/completed state,

* timestamps.

The creation API receives PR numbers ordered from bottom to top and validates that each PR’s base branch matches the preceding PR’s head branch. GitHub also exposes an operation that appends a PR to the top of an existing stack and returns a conflict response if a concurrent modification prevents the update. ([GitHub Docs][5])

Its GraphQL model exposes a `PullRequestStack` and ordered `PullRequestStackEntry` objects. Each entry has a one-based position and links to a PR. ([GitHub Docs][6])

A likely normalized representation is therefore approximately:

```text

pull_request_stacks

  id

  repository_id

  number

  base_ref

  state

pull_request_stack_entries

  id

  stack_id

  pull_request_id

  position

```

That table design is an inference, not a claim about GitHub’s private schema. But it closely matches the public object model.

## 5.3 The stack is durable rather than inferred on every request

GitHub could theoretically inspect PR bases and reconstruct branch chains dynamically. It instead provides APIs for explicitly creating, extending, and dissolving stacks.

That matters because branch topology alone is ambiguous.

For example:

* A developer may temporarily base one feature branch on another without intending a stack.

* A PR could be retargeted accidentally.

* Closed and merged PRs complicate inference.

* A branch could appear in several possible chains.

* Operations need a stable ID and optimistic-concurrency boundary.

* Webhooks and audit logs need an identifiable object.

The Git graph should be treated as a structural invariant of the stack, not as its sole identity.

## 5.4 The local CLI tracks more than branch names

GitHub’s `gh-stack` code maintains local metadata and records, for each stacked branch, both its current head and a base commit boundary. The project’s source describes that base as the parent branch’s head SHA at the last synchronization or rebase, used to identify the commits unique to the layer. ([GitHub][7])

This is one of the most important implementation details in the entire system.

Consider:

```text

A---B---C

main = A

PR 1 head = B

PR 2 head = C

```

Now PR 1 is squash-merged, producing commit `S`:

```text

A---S              main

A---B---C          old feature history

```

To restack PR 2, the system must replay only the work after `B`:

```bash

git rebase --onto S B C

```

It must **not** replay everything after `A`, because that would reapply PR 1’s changes on top of the squashed version.

The old boundary SHA `B` tells the system where PR 2’s unique layer begins.

Branch names are insufficient because `feature/schema` may have moved, been deleted, or been replaced by a squash commit. A robust stack implementation must retain commit boundaries as immutable OIDs.

## 5.5 GitHub uses waterfall rebasing

A cascade rebase proceeds from the trunk upward:

```text

rebase layer 1 onto current trunk

rebase layer 2 onto new layer 1

rebase layer 3 onto new layer 2

…

```

If a conflict occurs, the operation pauses at the affected layer. GitHub’s CLI supports continuing or aborting an interrupted stack rebase and persists the necessary local state. ([GitHub][8])

The direction matters. Rebasing the top first would use parent commits that are about to be replaced.

## 5.6 Pushes use optimistic ref safety

GitHub’s CLI pushes active branches with per-ref `--force-with-lease`, protecting against overwriting a remote branch that changed unexpectedly.

The CLI documentation notes that its multi-branch push is not completely atomic: one branch update can succeed while another fails. It therefore needs reconciliation and retry behavior. ([GitHub][8])

A GitHub clone that owns its Git backend can provide stronger server-side semantics through a batch compare-and-swap ref API.

## 5.7 GitHub virtualizes the policy base

GitHub distinguishes the immediate PR base from the stack’s trunk base.

For all stacked layers, GitHub evaluates:

* branch protection,

* required checks,

* workflow applicability,

* required reviews,

* CODEOWNERS,

against the stack’s ultimate target branch. In particular, changing a CODEOWNERS file in a lower PR does not alter ownership requirements for upper PRs; the policy definition is taken from the stack base. ([GitHub Docs][3])

This is both a security requirement and a usability requirement.

## 5.8 GitHub includes stack context in CI events

GitHub’s pull-request event payload exposes stack metadata including:

* stack number,

* stack size,

* the PR’s position,

* the effective base ref and SHA.

That lets CI systems make stack-aware decisions. ([GitHub Docs][3])

For example:

```yaml

if: github.event.pull_request.stack.position ==

    github.event.pull_request.stack.size

```

could run a particularly expensive end-to-end suite only for the top layer, while cheaper required checks still run for every layer.

The downside is CI multiplication. A ten-layer stack may trigger ten sets of workflows, and changing the bottom can invalidate all ten.

## 5.9 GitHub supports contiguous-prefix merges

Suppose the stack is:

```text

PR 1

PR 2

PR 3

PR 4

```

Permitted operations include:

```text

merge PR 1

merge PRs 1–2

merge PRs 1–3

merge PRs 1–4

```

But not:

```text

merge only PR 2

merge PRs 2–3 while PR 1 remains open

```

All selected layers and all layers below the selected one must satisfy their requirements. ([GitHub Docs][4])

This follows directly from the dependency model: a layer cannot land without its prerequisites.

## 5.10 Stack merging is asynchronous

GitHub exposes an asynchronous merge endpoint for stacked PRs. The request can include:

* expected head SHA,

* merge method,

* direct merge versus merge queue,

* and the selected PR.

The server returns an operation UUID and an HTTP `202 Accepted`; the client polls for the result. GitHub also returns conflicts for an already-running incompatible operation. ([GitHub Docs][9])

This is the correct architectural model. A stack merge may need to:

* validate several PRs,

* query checks and reviews,

* create multiple commits,

* interact with the merge queue,

* update several branches,

* close several PRs,

* generate events,

* and restack remaining upper branches.

That should not be implemented as a fragile synchronous HTTP request.

## 5.11 GitHub supports the normal merge methods

GitHub documents stack behavior for:

* **Merge commit:** one merge commit for the selected group, preserving the commits in the selected branch history.

* **Squash:** one squashed commit per PR.

* **Rebase:** commits from each PR are replayed in stack order.

For merge-queue operation, stack ordering is preserved, and ejecting a lower member necessarily affects the members above it. ([GitHub Docs][10])

## 5.12 “Atomic” has an important caveat

GitHub describes stack merging as one coordinated operation, but its troubleshooting documentation acknowledges that an unexpected failure may occur after some lower PRs have already landed. In that case, the landed PRs remain merged and the failed and upper PRs remain open. ([GitHub Docs][11])

Therefore, “atomic” should be understood as:

* one user-visible operation,

* one preflight,

* one ordered orchestration,

not necessarily a mathematically strict all-or-nothing transaction spanning Git refs, SQL rows, CI, queues, and webhooks.

A new implementation can make Git-ref movement more atomic than this, but it still needs durable recovery across storage systems.

## 5.13 Current limitations

GitHub’s documented preview currently has several meaningful constraints:

* All PRs must be in the same repository.

* GitHub Desktop does not provide stack management.

* Auto-merge is not supported for stacked PRs.

* Merge queue is supported.

* REST and webhooks support stack operations; GraphQL exposes a read model.

* The feature remains subject to change during public preview. ([GitHub Docs][2])

---

# 6. Architecture for implementing stacked PRs in a GitHub clone

A clean implementation should separate the system into seven responsibilities:

```text

┌───────────────────────────────────────────────────────────────┐

│ Web UI / CLI / API                                            │

├──────────────────────────────┬────────────────────────────────┤

│ Pull Request Service         │ Stack Service                  │

│ reviews, comments, diffs     │ membership, ordering, state    │

├──────────────────────────────┼────────────────────────────────┤

│ Policy + CI Planner          │ Operation Orchestrator         │

│ effective base, checks       │ rebase, merge, recovery        │

├──────────────────────────────┴────────────────────────────────┤

│ Merge Queue                                                   │

├───────────────────────────────────────────────────────────────┤

│ Git Data Plane                                                │

│ objects, refs, diffs, merge/replay, CAS ref transactions      │

├───────────────────────────────────────────────────────────────┤

│ Metadata DB + Outbox + Workers                                │

└───────────────────────────────────────────────────────────────┘

```

In a forge where Git object storage is already separated from collaboration metadata, the stack should live in the **collaboration database and orchestration layer**.

The Git data plane should not know what a “pull request stack” is. It should expose generic primitives:

```text

ResolveRef

ReadCommitGraph

IsAncestor

ComputeDiff

MergeTrees

ReplayCommits

CreateCommit

BatchUpdateRefsCAS

PinObjects

```

The stack service composes those primitives.

That separation keeps Git storage reusable for:

* ordinary PRs,

* merge queues,

* coding-agent workspaces,

* patch previews,

* release branches,

* mirrors,

* and ephemeral environments.

---

# 7. Recommended data model

## 7.1 Stack records

```sql

CREATE TABLE pull_request_stacks (

    id                  UUID PRIMARY KEY,

    repository_id       UUID NOT NULL,

    number              BIGINT NOT NULL,

    trunk_ref_name      TEXT NOT NULL,

    state               TEXT NOT NULL,

    version             BIGINT NOT NULL DEFAULT 1,

    created_by          UUID NOT NULL,

    created_at          TIMESTAMPTZ NOT NULL,

    updated_at          TIMESTAMPTZ NOT NULL,

    UNIQUE (repository_id, number)

);

```

Suggested states:

```text

OPEN

COMPLETED

DISSOLVED

```

Avoid encoding transient operational states directly on the stack. Put those in an operation table.

## 7.2 Ordered entries

```sql

CREATE TABLE pull_request_stack_entries (

    id                  UUID PRIMARY KEY,

    stack_id            UUID NOT NULL,

    pull_request_id     UUID NOT NULL,

    position            INTEGER NOT NULL,

    boundary_oid        BYTEA NOT NULL,

    observed_head_oid   BYTEA NOT NULL,

    removed_at          TIMESTAMPTZ,

    UNIQUE (stack_id, position)

);

```

`boundary_oid` is the critical field.

For each layer:

```text

bottom entry boundary = trunk SHA at its last valid restack

upper entry boundary  = previous layer’s head SHA at its last valid restack

```

Use an opaque Git OID type or a representation capable of storing both SHA-1 and SHA-256 object IDs. Do not hard-code a 40-character SHA-1 schema.

Add a partial uniqueness constraint so a PR cannot be an active member of two stacks simultaneously.

## 7.3 Durable operations

```sql

CREATE TABLE stack_operations (

    id                      UUID PRIMARY KEY,

    stack_id                UUID NOT NULL,

    kind                    TEXT NOT NULL,

    state                   TEXT NOT NULL,

    target_position         INTEGER,

    expected_stack_version  BIGINT NOT NULL,

    idempotency_key         TEXT NOT NULL,

    request                 JSONB NOT NULL,

    snapshot                JSONB,

    planned_result          JSONB,

    error                   JSONB,

    created_at              TIMESTAMPTZ NOT NULL,

    started_at              TIMESTAMPTZ,

    completed_at            TIMESTAMPTZ,

    UNIQUE (stack_id, idempotency_key)

);

```

Operation kinds:

```text

CREATE

APPEND

RESTRUCTURE

REBASE

MERGE

QUEUE

UNSTACK

DISSOLVE

REPAIR

```

Operation states:

```text

PENDING

RUNNING

WAITING_FOR_CONFLICT_RESOLUTION

WAITING_FOR_CHECKS

SUCCEEDED

PARTIALLY_SUCCEEDED

FAILED

CANCELLED

```

For detailed recovery, add:

```sql

stack_operation_steps (

    operation_id,

    sequence,

    entry_id,

    action,

    state,

    old_oid,

    new_oid,

    error

);

```

## 7.4 Object retention

Every `boundary_oid` must remain reachable.

A commit that is no longer referenced by a public branch can eventually be garbage-collected. If that commit is the only record of a layer boundary, future restacking becomes unreliable.

Use either:

* hidden internal refs, such as `refs/internal/stacks/<stack-id>/<entry-id>`,

* object leases,

* or an explicit Git-object retention table understood by the garbage collector.

Do not advertise those internal refs to normal clients.

---

# 8. Structural invariants

Separate **structural validity** from **current mergeability**.

## 8.1 Hard structural invariants

A stack should require:

```text

All PRs belong to the same repository.

All entries are unique.

Positions are contiguous: 1…n.

The first PR targets the stack trunk.

Every later PR targets the preceding PR’s head branch.

No PR belongs to two active stacks.

No branch appears twice.

No cycle exists.

```

While a PR is stacked, generic “change base branch” operations should either:

* be routed through the stack service,

* or be rejected with an explanation.

Otherwise an ordinary PR update can silently corrupt the stack.

## 8.2 Dynamic validity

A stack can remain a recognized stack while temporarily needing a rebase.

For example:

```text

A---X                   main

 \

  B---C                 stack branches

```

The stack metadata remains valid, but `main`’s new commit `X` is not an ancestor of the bottom branch.

Represent that as:

```text

stack state: OPEN

health: NEEDS_REBASE

```

Other useful health states:

```text

HEALTHY

NEEDS_REBASE

CONFLICTED

MISSING_REF

HEAD_CHANGED

POLICY_BLOCKED

OPERATION_IN_PROGRESS

```

Do not dissolve the stack merely because its Git topology is temporarily stale.

## 8.3 Mergeability invariants

Before merging a selected prefix, require:

```text

current trunk tip is an ancestor of layer 1 head

layer 1 head is an ancestor of layer 2 head

…

selected layers form the lowest contiguous open prefix

all expected head SHAs still match

all required checks are current

all required approvals are current

no conflicting operation is active

```

For a simpler first version, prohibit merge commits inside individual layers when using the rebase merge method. Supporting arbitrary merge topologies complicates commit selection and replay semantics considerably.

---

# 9. Creating a stack

A creation operation should look like this:

```text

POST /repos/:owner/:repo/stacks

{

  "trunk_ref": "main",

  "pull_requests": [101, 102, 103],

  "expected_heads": {

    "101": "…",

    "102": "…",

    "103": "…"

  },

  "idempotency_key": "…"

}

```

Server algorithm:

```text

1. Begin metadata transaction.

2. Lock the repository’s relevant PR and stack rows.

3. Check repository and PR permissions.

4. Require every PR to be open and in the same repository.

5. Require no active membership in another stack.

6. Resolve all base and head refs from the Git service.

7. Validate the direct-base chain.

8. Snapshot current head OIDs.

9. Assign boundary OIDs.

10. Create stack and ordered entries.

11. Pin all boundary objects.

12. Increment stack version.

13. Write outbox events.

14. Commit metadata transaction.

15. Schedule policy and CI recalculation.

```

A useful UI may detect a potential manual chain and offer:

> “These three PRs form a branch chain. Convert them into a stack?”

But conversion should be explicit. Automatically treating every chain as a stack would produce surprising policy and merge behavior.

---

# 10. Computing the PR diff

GitHub PRs conventionally display a three-dot comparison: changes from the merge base of the base and head branches to the head. ([GitHub Docs][12])

Conceptually:

```bash

git diff base...head

```

or:

```text

M = mergeBase(baseHead, prHead)

diff(M, prHead)

```

For a healthy stacked layer:

```text

mergeBase(parentHead, childHead) = parentHead

```

so the PR displays only the child layer.

For the example:

```text

A---B---C---D

```

the reviews are:

```text

PR 1 diff: A → B

PR 2 diff: B → C

PR 3 diff: C → D

```

The system should offer two views:

### Layer diff

```text

direct base → this PR head

```

This is the primary review view.

### Cumulative preview

```text

trunk → this PR head

```

This answers:

> “What will the repository look like if everything through this point lands?”

If a lower branch is rewritten and an upper branch has not yet been restacked, the merge base may move backward and the layer diff may suddenly include lower-layer changes. The UI should not present that enormous diff without explanation. It should show:

```text

This layer is based on an outdated parent commit.

Rebase the stack to restore the intended review boundary.

```

---

# 11. Policy and CI architecture

## 11.1 Store both direct and effective bases

For each PR evaluation:

```text

direct_base_ref    = immediate parent branch

effective_base_ref = stack trunk branch

```

Use `direct_base_ref` for:

* diff presentation,

* branch ancestry,

* layer boundary,

* base branch display.

Use `effective_base_ref` for:

* branch protection,

* rulesets,

* required workflows,

* allowed merge methods,

* required approvals,