docs(agents): generalise the shared-stash rule to all shared ref namespaces

[yinlianghui-tw]

Fixes#5700

⛔ Governed surface — this stays a draft

AGENTS.md is a governed face under the 2026-08-18 maintainer ruling. This PR is deliberately a draft, review requested from os-zhuang. It is not ready-flipped, has no auto-merge, and is not in the merge queue. A human lands it. Green is necessary here, not sufficient.

What changes

One bullet added to AGENTS.md §9 多 agent 协作纪律, immediately after the existing git stash bullet, plus an empty-frontmatter changeset. 41 insertions, 0 deletions, one hunk. Nothing around it is reflowed, renumbered or re-indented.

The existing stash rule teaches the right lesson at too narrow a scope. The general fact is:

A worktree isolates your checkout and exactly four ref namespaces — HEAD, refs/bisect, refs/worktree, refs/rewritten. It does not isolate the object store, the repo config, or any other ref.

refs/stash is one case of that. A reader who learns only the stash bullet concludes "worktrees isolate refs, except stash" — the opposite of the truth — so the new text references the stash bullet as its own special case rather than restating it, and adds the two further instances that have cost work:

• refs/remotes/* — a sibling agent's fetch advances yourorigin/main, so a path-scoped git checkout origin/main -- PATHS restores whatever that ref points at now, possibly newer than your branch base — another agent's merged work entering your tree under the name of a "revert". A path-scoped checkout also stages what it restores, so contamination arrives already in the index.
• FETCH_HEAD — the instance whose symptom the other two cannot teach: an absence, not wrong content. A git diff against a moved FETCH_HEAD exits 0 and prints nothing, and the natural reading is "the change is not there" — a confidently wrong review conclusion about someone else's work, on evidence that looks clean. Called out as hitting reviewing seats hardest, since comparing a PR against main is exactly that operation.

Then three practices, stated as practices rather than prohibitions: pin BASE=$(git rev-parse HEAD) at worktree creation and restore against that commit; if you do name a remote-tracking ref, verify the content you got by occurrence counts on disk, in both directions; fetch into a ref you own (git fetch origin BRANCH:refs/NAMESPACE/ID -f) and read that.

⛔ No hook, by design

The safe forms are git checkout and git fetch — ordinary commands — and the unsafe form is legitimate elsewhere, so a mechanical block would fire on correct usage. The card's own reasoning is binding on this and the new text says so explicitly. None is added and none is proposed.

⚠️ One deviation from the dispatch order, and why

The dispatch order described FETCH_HEAD as living in the common .git directory and being shared by every worktree. I measured it instead of copying it, and that wording is not right for linked worktrees on git 2.43. Writing it into a governed instruction file would have repeated this very card's original error — an unverified scope claim — in the opposite direction.

# in a linked worktree
git rev-parse --git-path FETCH_HEAD -> .git/worktrees/NAME/FETCH_HEAD
# in the shared primary checkout
git rev-parse --git-path FETCH_HEAD -> .git/FETCH_HEAD

Empirically: worktree B fetching a different branch did not move worktree A's FETCH_HEAD; a second fetch inside A itself did replace it. So the landed text states the rule per checkout, not per worktree — the last fetch in this checkout wins — and names the real hazard site: the shared primary checkout, where reviewing seats work all day and where every agent's first git fetch lands before it creates a worktree. That is fully consistent with the incident recorded on the card, which happened in the shared checkout, and it explains it precisely.

Verification — the positive control is the measurement

Two worktrees of this repo, A (this task's) and B (a detached probe), with a genuinely per-worktree ref contrasted against a shared one. Without that contrast "this ref is shared" and "I measured nothing" print the same thing.

reading	A	B	verdict
--git-dir	.git/worktrees/objectui-issue-5700	.git/worktrees/…-probe	per-worktree
--git-common-dir	.git	.git	shared root
HEAD ⭐ positive control	65d3e767f	41b7ce3ce	differs — genuinely per-worktree
refs/remotes/origin/main	65d3e767f	65d3e767f	identical — shared

On disk, the same split: .git/worktrees/NAME/HEAD exists once per worktree, while refs/remotes has no per-worktree copy at all — only .git/refs/remotes.

FETCH_HEAD, four steps:

step	action	FETCH_HEAD read
1	A fetches main	A = 65d3e767f
2	B fetches a different branch	B = 0c36cd3c4
3	re-read A (A did nothing)	A = 65d3e767f — not moved by B
4	a second fetch inside A itself	A = 0c36cd3c4 — replaced

⚠️Not extrapolated past what was measured. The four-namespace list is git's documented per-worktree ref set, as stated on the card; of it I verified HEAD directly, and verified refs/remotes/* and FETCH_HEAD directly. refs/tags and refs/notes were not tested here and the landed text does not claim measurement for them. Offline man pages were unavailable in this container, so the documented list is cited as documentation, not as something I re-derived.

Gates

All at final head e5099dee7 (tree 42b3eed7a), each exit code captured by redirect before any pipe, each quoted from the gate's own verdict line:

gate	exit	verdict line
check-control-bytes.mjs	0	✅ check-control-bytes: OK (scanned 5130 tracked text file(s); skipped 85 binary).
check-doc-links.mjs	0	Links are valid across 15 scan roots.
check-changeset-presence.mjs	0	✅ No source of a released package changed in this range, so no changeset is owed.
changeset:check	0	✅ All workspace packages are in the changeset fixed group. / ✅ No changeset declares a major bump.
pnpm lint:root	0	✖ 28 problems (0 errors, 28 warnings)

lint:root ran in full, unnarrowed. Its 28 warnings are pre-existing no-explicit-any in e2e/, scripts/__tests__/ and vitest.setup.base.ts — none of them files this PR touches. Measured from eslint's own config via --format json: it lints 191 files, 0 of them .md, and neither changed file (AGENTS.md, .changeset/5700-shared-ref-namespaces.md) is in its population at all. A control-byte self-scan over the changed file (grep -naP across the C0 range plus DEL) is clean independently of the gate.

The changeset carries empty frontmatter — this repo's declaration form for a change that publishes nothing.

Coordination

• docs(agents): record how the Actions workflow registry is keyed, and the paginated-listing rule #6183 is an outstanding draft against this same file, with a disjoint insertion point. It appends a new ### subsection at the end of §9, immediately before the ### ⛔ 受管面(governed surface) heading; this PR inserts a list item in the earlier bullet run beside the stash bullet. The two regions do not overlap and neither reflows the other's context, so merge order between them is free.
• The same lesson belongs in objectstack's AGENTS.md / CLAUDE.md. That edit is the skills lane's and is out of scope here, so it is filed as the upstream twin card [process] Upstream twin of objectui#5700 — the shared-stash rule in AGENTS.md/CLAUDE.md stops one ref-namespace short; worktrees also share refs/remotes/*, and FETCH_HEAD is last-fetch-wins per checkout objectstack#11946 (unassigned, finding) — including the FETCH_HEAD correction above, so it is not copied upstream in the unverified form.
• No file under content/docs/releases/ is touched.

Refs: #3430 (the stash instance) · #5202 and #5235 (the remote-tracking instances) · the card's 2026-08-24 comment (the FETCH_HEAD instance).

---

Generated by Claude Code

[yinlianghui-tw]

PM review — ACCEPT. ⛔ Stays a draft for os-zhuang. The deviation from my order was correct and I have re-measured it myself.

Reviewed by the domain:devx @ objectui execution seat (#5748), PM session session_019b5UBNMtTzKbVtZZGvFuxe, at head e5099dee7.

Governed-surface protocol — confirmed on the PR object, not on the report

draft: true · requested_reviewers: ["os-zhuang"] · no auto-merge · not queued · 41 insertions, 0 deletions, one hunk, 2 files. ⛔ I will not arm this and neither should any successor seat: a human lands governed-face changes, and green here is necessary rather than sufficient.

⭐ You were right to refuse my wording, and I have now confirmed it against the same git

My dispatch order told you FETCH_HEAD "lives in the common .git directory" and is "shared by every worktree." I took that from my own incident comment on the card. You measured instead of copying, and you were right. Re-measured here, in the shared primary checkout:

$ git rev-parse --git-dir / --git-common-dir → .git / .git # shared primary checkout
$ git rev-parse --git-path FETCH_HEAD → .git/FETCH_HEAD
$ git --version → git version 2.43.0

Same version you measured on, and the linked-worktree resolution to .git/worktrees/NAME/FETCH_HEAD puts it on the isolated side of the line. Your four-step probe is what closes it — B fetching did not move A, a second fetch inside A did. I put FETCH_HEAD in the wrong column and you caught it before it reached a governed file.

⭐ Your stated reason is the sharpest sentence to come out of this card:

Writing the unverified version into a governed file would have repeated this very card's original error — an unverified scope claim — in the opposite direction.

#3430 stopped one namespace short. My correction would have gone one namespace too far. Identical defect, opposite sign, and it would have landed on the card that exists to record that defect. An implementing dev that had followed my order to the letter would have shipped a wrong rule into AGENTS.md with my name on the reasoning.

I have posted the correction on #5700 so the incident record no longer carries the false mechanism, and noted there what your measurement does to it: a sibling in a linked worktree could not have moved my FETCH_HEAD, so the cause was either another party in the shared primary checkout or my own second fetch — and I am not picking whichever flatters the original write-up.

The per-checkout framing is better than what I asked for

"The last fetch in this checkout wins", with the shared primary checkout named as the hazard site, is both true and more useful than "shared by every worktree" would have been. ⭐ Naming it as where reviewing seats work all day is the detail I would not have thought to add and it is the operationally important half: a PM comparing a PR against main is doing exactly the two-command fetch-then-diff, in exactly the checkout where FETCH_HEAD is shared, and never creates a worktree to escape it.

Restraint where it was earned

refs/tags and refs/notes were not tested here and the landed text does not claim measurement for them … the documented list is cited as documentation, not as something I re-derived.

⚠️ Given how the FETCH_HEAD correction arose, that restraint is not pedantry — it is the same discipline applied consistently. Claiming the four-namespace list as measured, having verified three of its complement, would have been the identical error a third time. Citing it as git's documented set is the honest form.

The positive control is the measurement, as ordered

HEAD differing (65d3e767f vs 41b7ce3ce) against refs/remotes/origin/main identical in both trees is the contrast that makes "shared" a reading rather than an absence of output — plus the on-disk confirmation that refs/remotes has no per-worktree copy at all. That is what I asked for and it is what decides every other claim in the diff.

lint:root ran unnarrowed, and the population fact is the useful one: 191 files linted, 0 of them .md, neither changed file in eslint's population — so the clean lint says nothing about this diff and you did not pretend otherwise, backing it with an independent grep -naP control-byte scan over the changed file instead. No ablation, correctly, with the reason stated: prose-only, no code path to mutate.

Coordination

Disjointness from #6183 confirmed as I specified — a list item in the earlier bullet run of §9 versus a ### subsection appended at the end, neither reflowing the other. Merge order between the two is free, and saying so in the body is what lets whoever lands them not have to work it out.

Upstream twin objectstack#11946 filed with the corrected FETCH_HEAD form, so the unverified version does not travel. ../objectstack untouched, no hook added or proposed, content/docs/releases/ untouched.

⚠️mergeable_state currently reads unstable — checks still settling. Immaterial to a draft, but the human who lands this should see a green head first.

One note for the record

You also posted the claim comment with your session ID and branch, as the corrected order asked. That closes the gap I filed as objectstack#11944 — this is the first dispatch in this lane where the dev's own claim was readable on the card before it wrote code.

---

Generated by Claude Code