One folder, one bounded contextLLM view

Merging without a queue

It works by making clashes impossible, not by testing every combination. A small bot of our own catches the few that remain. No Enterprise.

The rethink: 4 laws

  1. The path is the name. The folder names the context. The kernel puts that name in front of every URL, metric, alert, flag, MCP tool, table and event.
  2. A claim is a git conflict. Whatever two pull requests could both claim is a path or one line in a sorted list. context.yaml holds a random id. GitHub refuses to merge a text conflict, on any plan.
  3. No file every pull request edits. The kernel finds contexts; shared lists are generated and not committed.
  4. What others use only grows. A published contract is never edited. Retire first, delete later.

The breaks you saw, and the others (MEASURED, local git)

Break20 Nov layoutWith the 4 laws
same metric, two contextsbreaks mainimpossible
same metric, same contextgit conflictgit conflict
same context namemerges silently into one foldergit conflict
same route, two contextsbreaks mainimpossible
same route, same contextgit conflictgit conflict
same alert id, two contextsbreaks mainimpossible
same alert id, same contextbreaks maingit conflict
same free URL (an old or vanity address)no rule existed (REASONED, not run)git conflict (one claim file per address)
used dependency deletedbreaks mainred in its own pull request
published contract editedsilentred in its own pull request
stale generated file, upgrade forgot filesred in its own pull requestred in its own pull request
retired dependency or contract deleted while an old pull request starts using itbreaks mainremains
two pull requests each add half of a call loopbreaks mainremains
context deleted while another adds a file to itbreaks mainremains
generator upgraded while another adds a context (committed generated files only)breaks mainremains
  • Every pair, not just the examples: 62 possible changes, 1,891 pairs. 1,804 merged clean, 62 were git conflicts, 25 broke main. All 25 are the four "remains" rows: deletions, upgrades and new call edges. No unknown kind appeared. MEASURED
  • Conflicts almost never cross contexts: 1 of the 1,498 pairs from different contexts conflicted (a deletion against a generator upgrade). MEASURED
  • Correction to the earlier proof: a context.yaml alone is not enough. Two identical ones merge silently, which is what a template produces. The random id is what makes it a conflict. MEASURED (case 2c)

The four that remain: our own merge bot (built and tested)

  1. You label a pull request merge.
  2. The bot joins it with the newest main.
  3. It runs the fast whole-repo check (names, needs, uses, generated files; add the compile step per language).
  4. It pushes exactly what it tested. If main moved meanwhile, it starts again.
  5. Red: it removes the label and says why.
TestResultTag
the four remaining breaksall bounced; main greenMEASURED, local
50 waiting pull requests50 merged in 12.4 secondsMEASURED, local
a person pushes while the bot testsretried; main greenMEASURED, local
same on GitHub, private repo2 to 4 seconds each; pull requests show "merged"; commits verifiedMEASURED, GitHub
pull request with a git conflictGitHub refused it (HTTP 405)MEASURED, GitHub
a person skips the bot, no rulesmain broke; a signed revert made it green in 1.5 secondsMEASURED, GitHub
GitHub Team rule "only the bot updates main"the button and an unlisted pusher were refused; the listed one mergedMEASURED, GitHub
  • The bug the test found: asking GitHub for "pull requests with label merge" lags behind a fresh label. The bot now reads the plain list. MEASURED, fixed
  • Nobody rebases. The bot does the join. The pull request's own CI does not run again.
  • Why it stays fast: it runs only the check that needs the whole repo. The full tests run on the pull request and again on main.
  • Backstop: CI on main. Red blocks the release (already decided) and opens a revert pull request. The revert pull request is REASONED, NOT BUILT.

What GitHub Free private repos cannot enforce

ThingFree privateWhat we do instead
block a text conflictworksthis is why the laws turn clashes into conflicts
required CI before mergenothe bot; CI on main
"only the bot merges"noa habit; CI on main catches a skip
stop a direct push to mainnoCI on main, revert
required review, code ownersnothe pull request author asks
signed commits requirednodev shell signs; CI can only report
merge queueno (Enterprise only)the bot
  • Rules on a private Free repo: GitHub answered 403 "Upgrade to GitHub Pro". MEASURED on a private repo. Reviews, protected branches and code owners are paid on private repos: FROM DOCS (https://docs.github.com/en/get-started/learning-about-github/githubs-plans).
  • GitHub Free now includes 12 US dollars a month of Actions use for private repos, not a number of minutes. FROM DOCS (same page).
  • Not tested: the bot running as a GitHub Action (private repos in our test org cannot run Actions; the workflow is written and linted), and a GitHub App as the listed actor (tested with the repo admin role). Before use, the bot must also check that the pull request's own CI is green.

A clash the laws cannot stop, and the bot

Animation, 5 steps. Starts with: box pa "A: deletes a retired dependency"; box pb "B: starts using it"; box bot "merge bot"; cylinder mn "main". Connected: pa -> bot, pb -> bot, bot -> mn. Families, one colour each: pr "pull requests" (pa, pb); tool "our bot" (bot); main (mn). 1. Both pull requests are green on their own. Git sees no conflict. 2. The bot tests main plus A. Green, so it pushes A. pa -> bot: A 3. It pushes exactly what it tested. bot -> mn: tested 4. The bot tests the new main plus B. Red, so B goes back with the reason. pb -> bot: B 5. Main never saw the break.

  • pull requests
  • our bot
  • main
A: deletes a retired dependencyA: deletes aretired dependencyB: starts using itB: starts using itmerge botmerge botmainmain
1Both pull requests are green on their own. Git sees no conflict.
1 / 5
All steps (5)
the four breaks, given to the bot (real output, shortened)
$bun bot-proof.ts
3b retired dependency deleted, old PR starts using it
a merged, attempt 1 (163 ms)
b bounced: [deps] users uses cache.spare, not declared (132 ms)
main: green
8a two PRs each add half of a cycle
a merged, attempt 1 (170 ms)
b bounced: [cycle] billing -> users -> billing (151 ms)
main: green
$