}

      ]

    },

    %{

      title: "Pull requests",

      items: [

        %{

          slug: "pull-requests",

          title: "Pull requests",

          icon: "pull-request-open",

          route: "/:owner/:repo/pulls"

        },

        %{

          slug: "stacked-pull-requests",

          title: "Stacked pull requests",

          icon: "stack",

          route: "/:owner/:repo/pulls/:number"

        },

        %{

          slug: "stack-actions",

          title: "Rebase and restructure a stack",

          icon: "reload",

          route: "/:owner/:repo/pulls/:number"

        },

        %{

          slug: "merging-stacks",

          title: "Merging stacks",

          icon: "check-circle",

          route: "/api/v3/repos/:owner/:repo/stacks"

        }

      ]

    },

    %{

      title: "Projects",

      items: [

          icon: "square-code",

          route: "/api/v3/repos/:owner/:repo/issues"

        },

        %{

          slug: "stacks-api",

          title: "Stacks API",

          icon: "square-code",

          route: "/api/v3/repos/:owner/:repo/stacks"

        },

        %{slug: "status-api", title: "Status API", icon: "info", route: "/api/status"}

      ]

    }

issue carries a number that is unique within its repository and never reused,

so a reference to an issue stays valid after it is closed.

[Pull requests](/docs/pull-requests) share the same number sequence: a pull

request is an issue paired with a branch comparison, so issue and pull

request numbers never collide within a repository.

## Comments

Comments are ordered and attributed. Editing one is limited to its author,

# Merging stacks

A stack merges bottom-first. You can land the whole stack or any contiguous

prefix of it — layers 1 and 2 while layer 3 is still in review — but never a layer

whose foundations have not landed.

Merging requires write access, and merge policy is evaluated against the

trunk for every layer. A layer's direct base being an intermediate branch

never relaxes what the trunk requires.

## Merge a prefix in one operation

`POST /api/v3/repos/:owner/:repo/stacks/:stack_number/merge` lands a

contiguous prefix as one operation:

```sh

curl -X POST \

  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \

  -H "Content-Type: application/json" \

  -H "Idempotency-Key: $(uuidgen)" \

  -d '{"pull_requests": [117, 118], "merge_method": "merge"}' \

  https://openagents.com/api/v3/repos/acme/api/stacks/1/merge

```

- `pull_requests` must be a contiguous prefix from the bottom of the stack.

  A gap or a middle-only selection is refused.

- `merge_method` is `merge`, `squash`, or `rebase`.

- `expected_stack_version` and expected head OIDs are optional guards; when

  supplied, a stack that moved since you read it fails the merge instead of

  landing something you did not review.

The request returns `202 Accepted` with a durable operation. Poll `GET

.../stacks/:stack_number/operations/:operation_id` until it succeeds or

fails. The trunk moves once for the whole prefix. Merged pull requests close as

merged, their entries leave the stack, and the layers above become the new

bottom.

## Merge one layer asynchronously

`PUT /api/v3/repos/:owner/:repo/pulls/:pull_number/merge-async` submits a

merge against one stacked pull request — it lands the contiguous prefix from

the bottom of the stack through that layer — and returns `202 Accepted`

immediately with an `operation_id` and a poll URL:

```sh

curl -X PUT \

  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \

  -H "Content-Type: application/json" \

  -H "Idempotency-Key: $(uuidgen)" \

  -d '{"merge_method": "squash"}' \

  https://openagents.com/api/v3/repos/acme/api/pulls/117/merge-async

```

Poll `GET .../pulls/:pull_number/merge-async/:operation_id` for the outcome.

`merge_status` is `pending` while the operation runs, then `merged` or

`failed`. `merge_method` defaults to `merge`. Repeating the request with the

same `Idempotency-Key` and body replays the same operation instead of

starting a second one; a different active operation on the stack returns

`409 Conflict` with that operation's id.

The submission is validated when it executes, not when it is accepted:

branch heads, stack membership, and merge policy are all checked at execution

time. An unstacked pull request cannot merge through this surface.

## Automatic restack after a partial merge

Landing a prefix rewrites the foundation under the remaining layers, so a

partial merge restacks them automatically: the remaining branches are rebased

onto the new trunk tip in the same coordinated fashion as

[Rebase the stack](/docs/stack-actions), and the stack's version advances.

The layers left behind stay reviewable without a manual cleanup step, and a

restack that would conflict fails the merge during planning — it never lands

the prefix and strands the rest.

## What atomic means here

Within one merge operation, the trunk either gains the whole requested prefix

or none of it — a conflict or policy failure partway lands nothing. It does

not mean the trunk pauses for you: another merge can land between your read

and your merge, which is what the `expected_stack_version` guard is for.

## Next steps

- [Stacked pull requests](/docs/stacked-pull-requests)

- [Stacks API](/docs/stacks-api)

# Pull requests

A pull request proposes merging one branch into another. Browse a

repository's pull requests at `/:owner/:repo/pulls`, and open one to review

its changes at `/:owner/:repo/pulls/:number`.

## What a pull request holds

A pull request pairs an issue with a branch comparison. The issue carries the

title, description, comments, state, and a number that is unique within the

repository and shared with plain issues. The comparison names a head branch,

a base branch, and the exact commits each pointed at when the comparison was

last observed, so the review diff is reproducible rather than whatever the

branches happen to say later.

A new pull request starts as a draft. Publish it by clearing the draft flag

when it is ready for review.

## The review diff

The pull request page shows the changes the head branch adds over the base

branch, as a unified diff with per-file collapse. When the pull request

belongs to a [stack](/docs/stacked-pull-requests), the page adds a stack map

and a layer-aware diff so each layer reviews only its own changes.

## Create one through the API

Pull requests are created through the REST API. `POST

/api/v3/repos/:owner/:repo/pulls` takes:

- `title` — required.

- `head` — required; the branch the work lives on.

- `head_repository` — required; the `owner/name` of the repository holding

  `head`. You need write access to it.

- `base` — optional; defaults to the repository's default branch.

- `body` — optional description.

- `draft` — optional; defaults to `true`.

```sh

curl -X POST \

  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \

  -H "Content-Type: application/json" \

  -d '{"title": "Add rate limiting", "head": "rate-limit",

       "head_repository": "acme/api", "base": "main"}' \

  https://openagents.com/api/v3/repos/acme/api/pulls

```

`PATCH /api/v3/repos/:owner/:repo/pulls/:pull_number` updates `title`,

`body`, `state`, `draft`, and `base`. While a pull request is an active stack

member its base belongs to the stack, so a direct base edit is refused —

restructure the stack instead.

Pull requests can be switched off per repository. When they are off, creation

returns `409 Conflict`.

## Merging

Merging is currently a stack operation: a pull request merges through the

stack it belongs to, and a stack can be as small as one pull request. See

[Merging stacks](/docs/merging-stacks). A standalone merge button for

unstacked pull requests is not implemented yet.

## Next steps

- [Stacked pull requests](/docs/stacked-pull-requests)

- [Rebase and restructure a stack](/docs/stack-actions)

- [Stacks API](/docs/stacks-api)

List responses use named envelopes. For example, the issue list returns an

object with an `issues` array.

## Pull requests and stacks

```text

GET    /api/v3/repos/:owner/:repo/pulls

POST   /api/v3/repos/:owner/:repo/pulls

GET    /api/v3/repos/:owner/:repo/pulls/:pull_number

PATCH  /api/v3/repos/:owner/:repo/pulls/:pull_number

GET    /api/v3/repos/:owner/:repo/stacks

POST   /api/v3/repos/:owner/:repo/stacks

GET    /api/v3/repos/:owner/:repo/stacks/:stack_number

POST   /api/v3/repos/:owner/:repo/stacks/:stack_number/append

POST   /api/v3/repos/:owner/:repo/stacks/:stack_number/rebase

POST   /api/v3/repos/:owner/:repo/stacks/:stack_number/merge

POST   /api/v3/repos/:owner/:repo/stacks/:stack_number/unstack

POST   /api/v3/repos/:owner/:repo/stacks/:stack_number/dissolve

PUT    /api/v3/repos/:owner/:repo/pulls/:pull_number/merge-async

```

See [Pull requests](/docs/pull-requests) for the pull request endpoints and

the [Stacks API](/docs/stacks-api) for stacks, durable operations,

idempotency, and optimistic concurrency.

## Issue prerequisites

An issue can wait on other issues in the same repository.

## Know what is not implemented

Pull requests, reviews, webhooks, releases, SSH Git transport, and Git LFS

object storage are outside the current subset.

Pull request reviews, webhooks, releases, SSH Git transport, and Git LFS

object storage are outside the current subset. Pull requests and stacked pull

requests are implemented — see [Pull requests](/docs/pull-requests) and the

[Stacks API](/docs/stacks-api).

# Rebase and restructure a stack

A stack stays useful only while its branches stay coherent. These actions

keep them that way, and every one of them runs on the server as a durable

operation rather than as a sequence of client-side pushes that can be

interrupted halfway.

All of them require write access to the repository.

## Rebase the stack

When the trunk moves, or a lower layer is rewritten, the layers above it go

stale. Click **Rebase the stack** on any stacked pull request page — it also

appears in the stale-boundary notice — or call `POST

/api/v3/repos/:owner/:repo/stacks/:stack_number/rebase`.

The rebase works bottom-to-top on the server:

1. It verifies every branch still points where the stack last observed it. A

   branch that moved since fails the operation instead of being silently

   overwritten.

2. It replays each layer's own commits onto the new base, keeping author

   identity. Server rebases are unsigned.

3. It moves every branch in one atomic batch. Either the whole stack moves or

   none of it does — a concurrent push to any stack branch makes the batch

   fail and preserves that push.

The pull request page shows the operation's progress — queued, running,

finished, or failed — with a **Check progress** button. Only one operation

can run per stack at a time; a second request while one is active returns the

active operation instead of starting another.

### Conflicts

A rebase that hits a conflict pauses rather than failing. The operation

reports which layer conflicted, and the API offers two ways out:

- `POST .../stacks/:stack_number/operations/:operation_id/continue` — resolve

  the conflict yourself, push the resolution commit, and pass its OID as

  `resolution_oid`. The operation verifies it and finishes the remaining

  layers.

- `POST .../stacks/:stack_number/operations/:operation_id/abort` — give up.

  No branch moves; the stack is exactly as it was.

Both re-verify branch heads before acting, so a resolution computed against

branches that have since moved is refused rather than applied.

## Remove the top layer

**Remove from stack** appears on the stack's top layer only. It detaches that

pull request from the stack — the pull request itself stays open and stops

being a layer. The equivalent API is `POST

/api/v3/repos/:owner/:repo/stacks/:stack_number/unstack` with

`{"pull_request": <number>}`.

Only the top layer can leave, because removing a middle layer would orphan

the branches above it. To take a middle layer out, remove layers from the top

down to it, or dissolve the stack.

## Grow the stack

`POST /api/v3/repos/:owner/:repo/stacks/:stack_number/append` adds one open

pull request on top. Its base branch must be the current top layer's head

branch.

## Dissolve the stack

`POST /api/v3/repos/:owner/:repo/stacks/:stack_number/dissolve` closes the

stack as an object while leaving every pull request open and every branch

where it is. Use it when the layers should continue as independent pull

requests.

A stack with an operation in flight refuses to unstack or dissolve until the

operation finishes.

These are the restructure operations available today. Reordering layers in

place is not supported — recreate the stack in the order you want instead.

## Next steps

- [Merging stacks](/docs/merging-stacks)

- [Stacks API](/docs/stacks-api)

# Stacked pull requests

A stack is an ordered series of dependent pull requests that merge

bottom-first into one trunk branch. Each layer's branch is based on the layer

below it, so a large change ships as several small reviews without losing the

dependency structure between them.

## Why stack

One big pull request is hard to review, and splitting it into independent

pull requests loses the ordering. A stack keeps both properties:

- Each layer is a small, focused review that shows only its own changes.

- The order is explicit. Layer 3 cannot land before layer 2, and the forge

  enforces that rather than trusting reviewers to remember it.

- Branch maintenance cascades. When the trunk or a lower layer moves, one

  server-side rebase moves every branch above it at once.

## The shape of a stack

A stack is a first-class object, not a naming convention. It holds:

- A **trunk** — the branch the whole stack eventually merges into, usually

  the default branch.

- **Ordered layers** — positions count up from 1 nearest the trunk. Each

  layer is one open pull request whose base branch is the head branch of the

  layer below (the bottom layer's base is the trunk).

- A **number** — unique within the repository, like an issue number.

- A **version** — increments on every structural change, so concurrent

  writers can detect that the stack moved underneath them.

- A **health** — `healthy`, or stale when a lower branch was rewritten and

  the layers above it need a rebase before their diffs are trustworthy.

Every layer keeps two bases. The *direct base* is the branch directly below,

and it defines what the layer's own review shows. The *effective base* is the

trunk, and it is what merge policy evaluates against — an intermediate branch

is never a policy target, so stacking cannot be used to slip changes past the

rules that protect the trunk.

## The stack map

Every pull request in a stack shows a stack map: the ordered rail of layers

with the newest on top, a state glyph per layer, the current layer

highlighted, and a trunk row that links to the trunk's file tree. Click any

other layer to jump to its pull request.

Below the map, a readiness line summarizes the whole stack — how many layers

are ready to merge bottom-first, how many are still drafts, or that the stack

needs a rebase first.

Members with write access also see the stack actions here. See

[Rebase and restructure a stack](/docs/stack-actions).

## Layer and cumulative review

A stacked pull request's diff has two views:

- **This layer** — the changes this layer adds over the layer below it. This

  is the default review view, computed from the boundary the stack recorded,

  so it shows only this layer's work even while other layers move.

- **Cumulative** — everything the stack contains through this layer,

  measured from the current trunk tip. Because the comparison starts at the

  *current* trunk, this view also picks up drift when the trunk has moved

  since the stack was created; it answers "what would the trunk gain", not

  "what did this author write".

When a lower layer is rewritten, the layer view above it becomes untrustworthy.

The page says so explicitly and offers the rebase action instead of showing a

diff that silently mixes in another layer's changes.

## Create a stack

Open the pull requests so their branches form a chain — each head is the next

base — then create the stack through the API:

```sh

curl -X POST \

  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \

  -H "Content-Type: application/json" \

  -H "Idempotency-Key: $(uuidgen)" \

  -d '{"trunk_ref": "main", "pull_requests": [117, 118, 119]}' \

  https://openagents.com/api/v3/repos/acme/api/stacks

```

The order in `pull_requests` runs bottom-first. Creation validates the whole

structure — every pull request open, in this repository, unduplicated, and

chained base-to-head — and refuses anything else. A stack holds at most 100

layers. See [Stacks API](/docs/stacks-api) for the full surface.

## Next steps

- [Rebase and restructure a stack](/docs/stack-actions)

- [Merging stacks](/docs/merging-stacks)

- [Stacks API](/docs/stacks-api)

# Stacks API

The stack surface lives under `/api/v3` beside the rest of the

[REST API](/docs/rest-api). Reads are public on a public repository; writes

require an `oa_pat_` bearer token with `forge:write` scope and an

`Idempotency-Key` header.

## Routes

```text

GET  /api/v3/repos/:owner/:repo/pulls

GET  /api/v3/repos/:owner/:repo/pulls/:pull_number

POST /api/v3/repos/:owner/:repo/pulls

PATCH /api/v3/repos/:owner/:repo/pulls/:pull_number

GET  /api/v3/repos/:owner/:repo/stacks

GET  /api/v3/repos/:owner/:repo/stacks/:stack_number

POST /api/v3/repos/:owner/:repo/stacks

POST /api/v3/repos/:owner/:repo/stacks/:stack_number/append

POST /api/v3/repos/:owner/:repo/stacks/:stack_number/rebase

POST /api/v3/repos/:owner/:repo/stacks/:stack_number/merge

POST /api/v3/repos/:owner/:repo/stacks/:stack_number/unstack

POST /api/v3/repos/:owner/:repo/stacks/:stack_number/dissolve

GET  /api/v3/repos/:owner/:repo/stacks/:stack_number/operations/:operation_id

POST /api/v3/repos/:owner/:repo/stacks/:stack_number/operations/:operation_id/continue

POST /api/v3/repos/:owner/:repo/stacks/:stack_number/operations/:operation_id/abort

PUT  /api/v3/repos/:owner/:repo/pulls/:pull_number/merge-async

GET  /api/v3/repos/:owner/:repo/pulls/:pull_number/merge-async/:operation_id

```

## The stack payload

A stack read returns the stack's `number`, `trunk_ref`, `state`, `health`,

`version`, and its active `entries` in position order. Each entry carries its

`position` and the pull request's `number`, `head` (`ref` and `sha`), and

`base` (`ref` and `sha`), so one read gives you the complete chain and the

exact commits the stack has observed.

```sh

curl https://openagents.com/api/v3/repos/acme/api/stacks/1

```

## Idempotency

Every write takes an `Idempotency-Key`. Repeating a request with the same key

and the same body returns the original result instead of acting twice; the

same key with a different body is refused with `409 Conflict`. Use a fresh

UUID per intended action and retry with the same one on network failure.

## Optimistic concurrency

A stack's `version` increments on every structural change. Writes accept an

optional `expected_stack_version`, and the mutating operations verify branch

heads against what the stack last observed before moving anything. When

either check fails you get a conflict rather than a mutation built on a stack

you have not seen — read again, re-decide, and resubmit.

## Operations

Rebase and merge run as durable operations. The submitting request returns

`202 Accepted` with the operation, and `GET

.../operations/:operation_id` reports its `state`: `pending`, `running`,

`waiting_for_conflict_resolution`, `succeeded`, `partially_succeeded`,

`failed`, or `cancelled`. One operation runs per stack at a time; submitting

while one is active returns `409 Conflict` carrying the active

`operation_id`. A paused rebase resumes through

[`continue` or `abort`](/docs/stack-actions).

## Worked example

Create three chained pull requests, stack them, and merge the bottom two:

```sh

repo=https://openagents.com/api/v3/repos/acme/api

auth="Authorization: Bearer $OPENAGENTS_TOKEN"

# One pull request per layer: base of each is the head of the one below.

curl -X POST -H "$auth" -H "Content-Type: application/json" \

  -d '{"title": "Layer 1", "head": "layer-1",

       "head_repository": "acme/api", "base": "main"}' $repo/pulls

curl -X POST -H "$auth" -H "Content-Type: application/json" \

  -d '{"title": "Layer 2", "head": "layer-2",

       "head_repository": "acme/api", "base": "layer-1"}' $repo/pulls

curl -X POST -H "$auth" -H "Content-Type: application/json" \

  -d '{"title": "Layer 3", "head": "layer-3",

       "head_repository": "acme/api", "base": "layer-2"}' $repo/pulls

# Stack them bottom-first.

curl -X POST -H "$auth" -H "Content-Type: application/json" \

  -H "Idempotency-Key: $(uuidgen)" \

  -d '{"trunk_ref": "main", "pull_requests": [1, 2, 3]}' $repo/stacks

# Land layers 1 and 2; layer 3 restacks automatically.

curl -X POST -H "$auth" -H "Content-Type: application/json" \

  -H "Idempotency-Key: $(uuidgen)" \

  -d '{"pull_requests": [1, 2], "merge_method": "merge"}' $repo/stacks/1/merge

```

## Next steps

- [Stacked pull requests](/docs/stacked-pull-requests)

- [Merging stacks](/docs/merging-stacks)

- [REST API](/docs/rest-api)