Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions quest/m0/helpers/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,13 +55,20 @@ commands from Sep-Oct. Session counts in each child come from that window.
into the PR state commands, which landed in
[kixelated/quest#185](https://github.com/kixelated/quest/pull/185).

- Decided 2026-10-26 (user), from moq-dev/moq's serial merge queue: a batched
merge gate, `quest land`, joins this epic. It ranks after the existing
children, and kixelated/quest adopts it first. moq-dev/moq, moq-dev/moq.pro,
and kixelated/rust2 plan their own adoption.

## Required

- [Landing rules](/quest/m0/helpers/landing.md) - land only heads that contain the current base, ask on a missing review, one design checkpoint
- [Wait and status accuracy](/quest/m0/helpers/wait-accuracy.md) - wake on edited bot comments, honest `checks:passed`, review rounds in `quest status`
- [Status holds](/quest/m0/helpers/status-holds.md) - `quest status` shows a PR's `quest:*` hold
- [Headless agents](/quest/m0/helpers/headless-agents.md) - `/quest-spawn api` launches, resumes, and stops billed agents through one command auto mode allows
- [Sibling PRs through a server-side merge](/quest/m0/helpers/queue-siblings.md) - children of one epic land back to back through a merge queue without conflicting on its link list
- [Batched merge gate: quest land](/quest/m0/helpers/land.md) - a repository's CI lands every queued PR as one tested squash chain, fast-forwarding the base to the longest passing prefix
- [kixelated/quest lands through quest land](/quest/m0/helpers/land-adopt.md) - this repository's `main` changes only through its own gate

## Related

Expand Down
27 changes: 27 additions & 0 deletions quest/m0/helpers/land-adopt.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# [S] kixelated/quest lands through quest land

## Goal

PRs to kixelated/quest's `main` land only through
[`quest land`](/quest/m0/helpers/land.md), on a hosted runner, running
`just check` and `just test` once per batch. GitHub's merge button cannot
land around it.

## Plan

Decided 2026-10-26 (user): the repository adopts its own gate first. Being
user-owned, it cannot use GitHub's merge queue
([landing](/quest/m0/helpers/landing.md)).

- The push credential is GitHub Actions in the `main` ruleset's bypass list,
guarded by a test that refuses `contents: write` anywhere but the land job,
as moq.pro's `queue.test.ts` does. The admin role keeps its emergency
bypass. Ruleset writes are the user's.
- The ruleset requires a check that PR heads never carry, so auto-merge only
waits for the gate.
- Update `CONTRIBUTING.md`'s landing section; the user asked for it through
this plan.

## Required

- [Batched merge gate: quest land](/quest/m0/helpers/land.md) - the engine
76 changes: 76 additions & 0 deletions quest/m0/helpers/land.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# [L] Batched merge gate: quest land

## Goal

`quest land`, run from a repository's own CI, lands every PR whose landing
was requested as one tested batch. It builds the queued PRs, in enqueue
order, into a chain of squash commits on the base branch, resolving quest
files with `quest resolve`. It runs the repository's check command once on
the chain's tip and fast-forwards the base to the longest passing prefix.
Each landed PR shows as merged. The base only ever holds a tree the gate
tested, and a PR that fails alone or conflicts outside quest files is ejected
with a reason `quest status` reports. It works on any GitHub repository,
including user-owned ones that cannot use GitHub's merge queue.

## Plan

Decided 2026-10-26 (user), planning moq-dev/moq's merge throughput
([moq-dev/moq#6854](https://github.com/moq-dev/moq/pull/6854)). Over 414
queue merges, the serial GitHub merge queue landed 5.5 PRs per hour.
Waiting behind other entries was 98% of the time, with a median of 18 PRs
ahead of each new entry. GitHub's merge queue cannot test several PRs in one
run ("merge limits do not combine `merge_group` builds"), and Mergify merges
through the API, so neither can guarantee the tested tree or run the merge
driver.

- **Host.** A CLI subcommand in `src/cli/`, run by a thin workflow in each
repository. It needs no kix. moq.pro's `gate.yml` and `queue.yml` are the
serial precedent. kix's merge jobs feed the same queue through their
`deliver` landing.
- **Trust split.** Three phases, so PR code never sees a push credential:
a trusted hosted job resolves the queue and the chain's inputs, an
untrusted job builds the chain and runs the repository's check command
with a read-only token, and a trusted hosted job lands. The push token is
the repository's choice: moq uses its moq-bot App with the key in a
main-only Environment; moq.pro, kixelated/quest, and kixelated/rust2 put
GitHub Actions in the bypass list, behind a source-policy test.
- **Landing.** Write each PR's squash commit onto the chain. Force-push each
PR's branch, with a lease on the head that was tested, to its commit. Then
fast-forward the base to the tip in one push. GitHub marks a PR merged
once its head is on the base, so history stays linear and each PR shows as
merged. Verify that GitHub behavior against a scratch repository first. If
it does not hold, stop and report rather than fall back to closing PRs.
A failed lease stops the landing. The prefix before it lands only if a
check passed on exactly that prefix, since a later PR can mask an earlier
one's failure; otherwise nothing lands. The gate's own head pushes must not
dequeue the PR they move.
- **Batches.** Every queued PR, with no size constant. On failure, test the
first half; a passing prefix lands at once and the rest continues. A PR
that fails alone is ejected with a comment linking the run. No retries.
Order is enqueue order, with no priority classes.
- **Queue membership.** This quest decides, with a recommendation to the
user, how a repository without GitHub's merge queue marks a PR queued and
pins the head that was approved. `quest merge --land <sha>` already holds
the PR with `quest:merge` and enables auto-merge bound to that head. In a
gated repository the base requires a check that PR heads never carry, so
that auto-merge only waits. A push by anyone but the gate dequeues the PR.
- **Ejection.** Remove `quest:merge`, comment with the reason, and make it
readable through `quest status`'s `landing-stopped`, alongside GitHub's
queue reasons (`merge_conflict`, `failed_checks`).
- **Forks.** A fork PR without maintainer edits cannot have its head moved,
so it is ejected with a comment asking for them.
- Update `--help`, the README, and the merge skill's landing prose. The user
asked for those skill edits through this plan.
- Test chain building, prefix bisection, ejection, a failed lease (including
A failing alone and A+B passing when B's lease fails, which lands nothing),
and a quest-file conflict resolved by the driver, against the shared fake
GitHub (`cloudflare/dev/github.ts`) and a local git repository.

Adopters, each through its own plan: [kixelated/quest](/quest/m0/helpers/land-adopt.md),
[moq-dev/moq](https://github.com/moq-dev/moq/blob/main/quest/m0/ci/land.md),
moq-dev/moq.pro, and kixelated/rust2.

## Related

- [Sibling PRs through a server-side merge](/quest/m0/helpers/queue-siblings.md) - the same conflicts for repositories that still merge on GitHub
- [Land only heads tested against the current base](/quest/m0/helpers/landing.md) - the single-PR landing rule this generalizes
9 changes: 9 additions & 0 deletions quest/m0/helpers/queue-siblings.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,14 @@ and a tolerant check must tell a finished quest from a mistyped link.
The fix belongs in quest, not in each repository's process. Rejected:
landing one sibling at a time, which serializes batches.

Narrowed 2026-10-26 (user): [`quest land`](/quest/m0/helpers/land.md) runs
the merge driver while it builds its chain, so a repository on that gate no
longer hits the link-list conflict. This quest keeps the dead-link
`quest check` failure on every gate, which caused 6 of moq's queue failures
from 2026-10-23 to 10-26, and the link-list conflict for repositories that
still merge through GitHub's merge queue. Its third option below is what
`quest land` does.

Open (this quest decides, with a recommendation to the user):

- Change the link-list format so deleting one entry never touches its
Expand All @@ -42,4 +50,5 @@ landing through a merge that does not run the driver.

## Related

- [Batched merge gate: quest land](/quest/m0/helpers/land.md) - resolves the link-list conflict for gated repositories
- [Land only heads tested against the current base](/quest/m0/helpers/landing.md) - the same landing path
Loading