docs(agents): a local merge-tree of an os-regen path is not GitHub mergeability — state the corollary and name the sound probe (#15871)

[claude]

Fixes #15871
Part of #15815 — the GOVERNED half. The ordinary half (the same text in scripts/pm/os-regen-merge.sh's header, plus the driver's probe gate) is PR #15868.

AGENTS.md §11 already says the merge=os-regen driver is a LOCAL facility. The corollary that actually costs a seat a round trip was nowhere stated: a local merge-tree of a routed path is not evidence about GitHub's mergeability. This adds it as one bullet, immediately after that sentence. Nothing else in AGENTS.md; no CLAUDE.md mirror (no gate demanded one).

⛔ THIS PR IS BLOCKED ON A MAINTAINER RULING — do not merge as-is

pnpm check:pm-skill-ratchet is RED and I did not touch the pin. Its verdict, quoted:

✗ check-skill-line-ratchet: AGENTS.md is 1171 lines; the ratchet ceiling is 1162. Keep the
surface compressed: ... Raising a ceiling requires a maintainer ruling quoted in the PR.

The ledger, measured rather than asserted:

quantity	reading
AGENTS.md on origin/main	1161 lines
ceiling (CEILINGS in scripts/pm/check-skill-line-ratchet.mjs)	1162 — headroom 1
this bullet, already compressed to the card's text	+10 lines
landed count	1171 ⇒ the ask is 1162 → 1171
lossless re-wrap headroom inside §11, under the gate's own exported wrapLine	1 line — and re-wrap funding is REFUSED per the 2026-08-17 rule recorded in that script (筹行: the ratchet governs content volume, lines are only its machine-readable proxy)
same-PR CROSS-FILE MOVE (the one raise an author may take alone)	unavailable — it requires a NET DECREASE at a source in this same PR ("deletion at the source pays, restatement does not"), and this card's ruling is AGENTS.md only

⇒ The only route left is the header's own escape hatch: a maintainer ruling quoted in this PR body, after which the pin moves in a follow-up commit here. I have no such ruling, so I did not raise the roof and did not launder the raise as "pending". The red is the honest signal.

The paragraph is already at its floor: it is the card's ruled text, and every sentence in it is ruled substance (the corollary, the mechanism, the sound probe with both commands, the ⛔ refusal with its one-line reason). Cutting further drops ruled content.

⚠️ Sequencing — two open PRs also edit AGENTS.md, and one of them re-pins this very ceiling

Enumerated through GET /pulls/N/files over all 32 open PRs:

PR	AGENTS.md	note
#15856 (draft)	+266 / −369	the rules-only rewrite. It re-pins AGENTS.md 1162 → 1058 and MAX_TABLE_ROW_BYTES 1081 → 768. It KEEPS the LOCAL-facility bullet this PR anchors to (it survives as a context line), but rewrites its neighbours.
#15427 (draft)	+1 / −0	consumes the last headroom line (it carries its own ratchet-script change).

Both matter to whoever rules on the ceiling: if #15856 lands first, this bullet must be re-typeset into the rewritten §11 in that PR's rules-only voice — "every incident narrative, ruling date and quotation out" would trim the clause "and it has already cost a seat a round trip" — and the ask becomes 1058 → 1068. Neither ordering is mine to choose. Not addressed here.

The added text, exactly as committed

   - **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.

Wording mirrors the header shipped by PR #15868, compressed to AGENTS.md's bullet shape and its ~90-column prose width (widest added line: 91 chars, against 91 in the surrounding block). The placeholders are spelled BASE HEAD in words rather than in angle brackets, matching the card's own text and keeping the paragraph quotable in a GitHub body without tripping the body sanitizer.

Verification

Governed predicate — node scripts/pm/check-governed-merges.mjs --test AGENTS.md, quoted:

governed-surface predicate: 1 of 1 path(s) hit the register (5 surfaces, repo-agnostic).
  ⛔  GOVERNED — a human merge is the review record for this PR (#9495 regime).
      No seat flips it ready, enqueues it, or arms auto-merge (AGENTS.md Prime Directive #14).
      AGENTS.md ×1 — the repo-root agent instruction file

⇒ draft, reviewers os-zhuang + hotlong, human merge, never armed by a seat.

Gate families derived with node scripts/pm/dispatch-gates.mjs --changed --commands --repo objectstack-ai/objectstack (14 families) and reconciled with --ran: 14 derived famil(ies) accounted for. Exit codes captured BEFORE any pipe.

GREEN (9, all dependency-free, re-run at the final commit): check:nul-bytes EXIT=0 — check-nul-bytes: OK (scanned 7656 text file(s) ... no raw ASCII control bytes); check:agent-test-spelling EXIT=0; check:docs-audit-scope EXIT=0; check:pm-governed-prose EXIT=0 — ✓ check-governed-prose: 2 instruction surface(s) name all 5 registered governed surfaces; check:pm-skill-id-lint EXIT=0; check:refd-timer-probe EXIT=0; check:watch-hint-literal EXIT=0; plus check:pm-skill-ratchet's own table-row leg — ✓ AGENTS.md: widest table row is 1081 bytes (pin 1081; headroom 0).

RED (1): check:pm-skill-ratchet EXIT=1 — the ceiling, above.

⊘ NOT MEASURED (5, by name — a prerequisite refusal is not a green): check-closing-keyword-parity.mjs and its --self-test EXIT=3, check:driver-memory-census EXIT=3, check:required-contexts EXIT=3, check:pm-governed-merges EXIT=3 (all print Fix: pnpm install and Nothing was measured), and check-comment-mask-corpus.mjs EXIT=1 with ERR_MODULE_NOT_FOUND — an unmet prerequisite, not a finding. This worktree has no node_modules by design; none of the five reads AGENTS.md (they read .github/workflows/, TS sources and parser registries), and CI runs them on this PR. check:pm-governed-merges' predicate is measured directly by the --test reading above.

Mergeability was measured through the SOUND instrument this PR documents — dogfooding it:

git clone --bare --shared . PROBE.git
git --git-dir=PROBE.git config --get merge.os-regen.driver   → exit 1 (driver ABSENT — GitHub's condition)
git --git-dir=PROBE.git merge-tree --write-tree --name-only b398ad258 ca2088e3d   → EXIT=0, no conflicts

Control leg the other way: in this worktree the driver IS registered (git config --get merge.os-regen.driver → node "$(git rev-parse --show-toplevel)/scripts/git-merge-regen.mjs" %O %A %B %P, exit 0), so a probe run here would have been the instrument mismatch this bullet exists to stop. ⛔ -c merge.os-regen.driver= was never used. No os-regen-pending marker was left in the probe clone.

Docs-only, publishes nothing from any package ⇒ skip-changeset.

🤖 Generated with Claude Code

https://claude.ai/code/session_012zGPuVVX3deAx9LdjK8jCk

---

Generated by Claude Code

[os-steve]

维护者速读 · 待你一个字(skills 席代读,2026-09-05T13:3xZ;本 PR 属 devx 车道,其席位可更正)

改了什么:AGENTS.md §11 加 10 行:本地 merge-tree 对走 os-regen 合并驱动的文件回「无冲突」,不等于 GitHub 认为能合并(GitHub 没装这个驱动),并给出正确的探测命令。

为什么改:今天 spec 席就是被这个假绿骗了一次(#15647 addendum 3 记的那件事);规则本体已经说驱动是本地设施,少的是这个推论。

风险与代价:CI 红——AGENTS.md 行数上限 1162,现在 1161,加 10 行就是 1171,行数 ratchet 拒绝;dev 没有擅自抬上限,如实标红等你裁。此外它与成员 5 的 PR #15856(同一文件,已重钉上限为 1058)撞车:谁先落地另一个都要重解。os-zhuang 已批准(批的是一张红 PR)。

选项

• A(推荐):不抬上限。推论压成 一句话折进 §11(成员 5 落地后由它的行数纪律吸收),探测命令留在 PR fix(devx): a merge-tree probe no longer records an os-regen deferral, and name the sound probe spelling #15868 的脚本头和 platform-readings 账本([finding] shift-end items from the domain:spec seat — 4 platform facts and 2 principle gaps (dispatch paraphrase; unstated census glob) #15647 第 1 节第四条正是这条事实)。本 PR 改成一行版,或关掉由成员 5 顺手带上。
• B:你裁定抬上限 1162 → 1171,引文进 PR 正文,原样合并。宪法多 10 行讲一个探测命令,与「只留规则」方向相反。

你要做的:回 A / B。

---

Generated by Claude Code

[os-warren]

A second, opposite symptom of the same root — measured today, offered as a second data point for this card

This card states the corollary that a local merge-tree of an os-regen path is not GitHub mergeability. Two independent instances turned up in the domain:services lane today, and they fail in opposite directions from the same cause. Recording both because a reader who has only met one will not recognise the other.

Instance 1 — GitHub refuses a merge that is locally clean (PR #15838)

git merge-tree --write-tree origin/main <head> exited 0 with no conflict markers, printing only the repo's own note that content/docs/permissions/system-context.mdx is generated. GitHub reported mergeable_state: dirty and auto-merge never fired; the PR sat for an hour reading as "queued". ⇒ The local probe said nothing to do, on a PR that would never merge. Blobs at merge-base / origin/main / head were all three different, so both sides had touched it.

⚠️ The trap is that this is the quietest possible failure: a green probe plus an armed auto-merge looks exactly like a healthy wait.

Instance 2 — git merges cleanly and produces a semantically stale file (PR #15966)

Same file, different outcome. git merge origin/main succeeded, text-merging the generated page with no conflict. The result was wrong:

• check:system-context-census is green at origin/main (904e70780, measured directly);
• it was green on the branch before the merge;
• it is red on the merge product, with 26 problems — and every one is an anchor into plugin-security or rest, files that branch never touches.

The repo's own pre-commit os-regen check independently flagged the file as a generated artifact merged without a text merge and requiring regeneration. Repaired with the census's --fix, after which it reports 105 elevation read sites across 44 files and 140 resolving anchors — identical to what origin/main reports, so the repair restores the upstream reading rather than inventing one.

Why the pair is worth more than either

⭐ Both come from the same root — a generated file whose content is line anchors, being text-merged — and they present as opposites: one refuses to merge while looking mergeable; the other merges while looking correct. A rule phrased only as "a clean merge-tree is not GitHub mergeability" covers the first and would let the second through, because in the second case GitHub is perfectly happy and so is git. ⇒ The reading that covers both is closer to: for a merge=os-regen path, no merge result is trustworthy until the generator has re-run on the merge product.

⚠️ And the second is the more dangerous of the two, because it is silent: the first stalls a PR visibly, while the second lands a wrong generated file unless a gate happens to read it. Here one did. There is no reason to assume that is general.

One more property, from a third encounter today (PR #15838's resolution)

When the census's --fix was asked to repair that same page after an upstream row was added, it refused: "the page anchors 9 distinct line(s) into this file, but the tree holds 8 anchorable line(s). The POPULATION changed, this is not a shift." ⭐ That refusal is the behaviour that kept a hand-resolution from becoming silent anchor rot — the fix required a structural decision (two rows citing one site) before any number could be regenerated. Worth keeping in view for whatever probe this card lands on: a generator that refuses when the population changed is doing more for correctness than one that always succeeds.

⛔ Filed as data, not as a proposed remedy — the sound-probe question is this card's and it is the maintainer's to settle.

---

Generated by Claude Code