From ca2088e3d8a6ccd1183d5dbf73878a6dc55b73ea Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 5 Sep 2026 12:25:53 +0000 Subject: [PATCH] docs(agents): state the corollary that a local `merge-tree` of an os-regen path is not GitHub mergeability, and name the sound probe (#15871) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AGENTS.md §11 already says the `merge=os-regen` driver is a LOCAL facility. What it never stated is the corollary that costs a seat a round trip: a local `git merge-tree` of a routed path runs the same merge-ort machinery as `git merge`, so it HONOURS the driver, while GitHub runs none — the two answer different questions about the same snapshot. The added bullet names the sound instrument (a throwaway bare clone sharing the object store, where the driver is genuinely absent, which is GitHub's actual condition) and refuses the falsified `-c merge.os-regen.driver=` spelling, whose empty string does not disable the driver but leaves git failing to run it and reporting a conflict for every routed path — including ones that text-merge cleanly. Measurements are on PR #15868, which carries the same text in `scripts/pm/os-regen-merge.sh`'s header. Part of #15815 Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_012zGPuVVX3deAx9LdjK8jCk --- AGENTS.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 64fe9b5dbc..15b746d69e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -650,6 +650,16 @@ Even inside your own worktree, operate defensively: (`authorable-surface/`, `json-schema.manifest/`, `api-surface/`) to keep parallel spec PRs textually disjoint; every gate reads the whole directory as one set, so ratchet semantics are unchanged (`packages/spec/scripts/lib/sharded-artifacts.ts`). + - **Corollary — a local `merge-tree` is NOT GitHub's mergeability**, and it has already + cost a seat a round trip: a local `git merge-tree` of any `merge=os-regen` path runs + the same merge-ort machinery as `git merge` and therefore honours the custom driver, + while GitHub runs none, so the two answer different questions about the same snapshot. + Probe from a throwaway bare clone that shares the object store and has no driver + registered (`git clone --bare --shared . PROBE.git`, then + `git --git-dir=PROBE.git merge-tree --write-tree --name-only BASE HEAD`), ⛔ never with + `-c merge.os-regen.driver=`, which does not disable the driver but leaves git failing + to run it and reporting a conflict for every routed path, including ones that + text-merge cleanly. - **Registration is per clone** (`pnpm install` → `prepare` → `scripts/setup-git-hooks.mjs`); an unregistered clone falls back to git's default text merge — older behaviour, not breakage.