From ca2088e3d8a6ccd1183d5dbf73878a6dc55b73ea Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 5 Sep 2026 12:25:53 +0000 Subject: [PATCH 1/2] 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. From f0e9c4c8782ce741523355440063f6c50392bc96 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 7 Sep 2026 08:29:57 +0000 Subject: [PATCH 2/2] docs(agents): re-typeset the merge-tree corollary rules-only and raise the AGENTS.md ceiling 1058 -> 1068 (ruled) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The rules-only rewrite of `AGENTS.md` landed while this branch was open, so the bullet this branch adds is re-typeset into that voice: the incident clause "and it has already cost a seat a round trip" comes out, and the rest is re-wrapped to the surrounding block's own prose width (widest added line 90 bytes, against 90 bytes widest in the §11 block around it; the gate's hard cap is 120). Every rule sentence stays, because each is ruled substance: a local `merge-tree` of a `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; the sound probe is a throwaway bare clone that shares the object store with no driver registered, with both of its commands; and the `-c merge.os-regen.driver=` override is refused, with the reason it is refused — it does not disable the driver, it leaves git failing to run it and reporting a conflict for every routed path, including ones that text-merge cleanly. The bullet measures +10 lines against `origin/main`, taking `AGENTS.md` to 1068, so the `CEILINGS` entry moves 1058 -> 1068 at the landed count, headroom 0. That raise is the header's own escape hatch and it is ruled: maintainer, decision batch #63, 2026-09-07, verbatim and untranslated 「同意」 (PR #15885 comment 5564103435), and 「15885 你接手跟进合并」 (2026-09-07, quoted in the correction comment on the same PR, which re-measures the number the batch stated as 1171 against a `main` that had since moved). Re-wrap funding and a cross-file move were both refused per that header: the bullet is already at the block's prose width, and `AGENTS.md` is not a `CROSS_FILE_MOVES` destination, so no `ruledRaises` record applies. The widest-table-row leg (pin 768) and every other ceiling are untouched. Claude-Session: https://claude.ai/code/session_01TezFG8ZMrNH6n5VTNpPpdH Co-authored-by: Claude --- AGENTS.md | 18 +++++++++--------- scripts/pm/check-skill-line-ratchet.mjs | 13 ++++++++++++- 2 files changed, 21 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index cd515e0144..e010b4a6c3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -583,15 +583,15 @@ 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 + - **Corollary — a local `merge-tree` is NOT GitHub's mergeability**: 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 diff --git a/scripts/pm/check-skill-line-ratchet.mjs b/scripts/pm/check-skill-line-ratchet.mjs index b2da64db61..90e7aa0257 100644 --- a/scripts/pm/check-skill-line-ratchet.mjs +++ b/scripts/pm/check-skill-line-ratchet.mjs @@ -868,7 +868,18 @@ export const CEILINGS = new Map([ // 1162 → 1058: the rules-only rewrite — every incident narrative, ruling date and // quotation out, every rule kept as one sentence; re-pinned at the landed count, // headroom 0 (lowering is always legitimate). - ['AGENTS.md', 1058], + // + // 1058 → 1068: the merge-tree corollary (PR #15885, card #15871), +10 lines — a + // local `merge-tree` of a `merge=os-regen` path is NOT GitHub's mergeability, the + // driver-less bare-clone probe that answers GitHub's question, and the ⛔ refusal + // of `-c merge.os-regen.driver=`. Maintainer ruling, verbatim and untranslated: + // 「同意」 (decision batch #63, 2026-09-07, PR #15885 comment 5564103435) and + // 「15885 你接手跟进合并」 (2026-09-07, quoted in the director's correction comment + // on PR #15885). Re-wrap and cross-file moves are refused per the header: the + // bullet is already typeset at the surrounding block's 90-byte prose width, and + // AGENTS.md is not a CROSS_FILE_MOVES destination, so no `ruledRaises` record + // applies. Landed count, headroom 0, same convention. + ['AGENTS.md', 1068], // #9965: root CLAUDE.md is the other repo-root instruction file — same read // path (every seat session), same governance (Prime Directive #14). It is // structurally growth-prone in the way the ratchet is built for: it exists to