docs(agents): state the git stash ban in AGENTS.md §9 as a rule of its own

[yinlianghui]

Fixes#4340

Docs-only. The shared-stash ban lived only in CLAUDE.md — the excerpt file — while AGENTS.md, which declares itself the single source of truth "read natively by Claude Code, GitHub Copilot, and other agents", never stated it. The pointer between the two did not resolve in either direction: CLAUDE.md closed with "See AGENTS.md for the full playbook", and the canonical file's own reverse-verification rule deferred back out with 见 CLAUDE.md. So the full playbook was the file that did not have the rule, and the non-Claude readers named on line 3 met guard-shared-stash.sh as an unexplained Bash block.

Pointer topology

	before	after
AGENTS.md §9	one parenthetical clause, deferring out: git stash 一律禁用(共享 stash 栈,见 CLAUDE.md)	canonical: the ban stated as a rule of its own, beside the worktree rule — ban, shared refs/stash rationale, objectui#3430, the sanctioned substitutes, the hook and its escape hatch
AGENTS.md reverse-verification rule	pointed at CLAUDE.md	points in-file at the new rule
CLAUDE.md	excerpt whose closing pointer dangled	excerpt, unchanged in substance; closing pointer now names §9 多 agent 协作纪律 and resolves

One canonical statement plus an in-file pointer — no second drift-capable copy. CLAUDE.md keeps its stated purpose ("the one rule that must never be missed is inlined here"); only its last line moved, to make the pointer honest.

objectstack#7800 avoidance

That card is the content defect in the same doc family: the first substitute recipe in objectstack's copy overwrites the working tree from a ref, which silently destroys uncommitted work in exactly the reverse-verification situation it is offered for. It was deliberately not imported here. The promoted block:

• leads with the commit-then-revert idiom PR docs(agents): state commit-then-revert as the required order for reverse verification (#4301) #4339 canonicalized (git commit -am wip, restore with git reset --soft HEAD~1);
• carries only the three forms that capture uncommitted state first (wip commit, patch file, second worktree) — objectui's CLAUDE.md never had the hazardous line, so promotion needed no filtering, only ordering;
• states the shared property explicitly, so the recipe cannot be re-derived wrongly: any "overwrite now, retrieve from a ref later" form is not a substitute, because it assumes a commit that reverse verification usually has not made yet.

The one surviving occurrence of that overwrite form in AGENTS.md is the pre-existing reverse-verification rule, where it appears as the hazard being warned against, not as a recipe. Unchanged.

Not touched

.claude/hooks/guard-shared-stash.sh and its selftest — the behavior already lives there; this card was the missing prose. No code, no hook, no workflow: the diff is prose in two markdown files.

Verification

• node scripts/check-doc-links.mjs — Links are valid across 13 scan roots.
• node scripts/check-skills-paths.mjs — OK (84/85 stated path(s) resolve across 18 guide file(s); 1 baselined) — no regression in AGENTS.md path claims.
• node scripts/check-control-bytes.mjs — OK (scanned 4152 tracked text file(s); skipped 85 binary); plus a targeted control-byte self-scan of both edited files (no hits).
• node scripts/check-changeset-presence.mjs — No source of a released package changed in this range, so no changeset is owed. The presence gate self-determines; none added.
• pnpm exec vitest run --maxWorkers=2 over the five suites that read these two files (check-doc-links, check-skills-paths, check-control-bytes, check-changeset-presence, site-next-agent-files-4160) — Test Files 5 passed (5) / Tests 193 passed (193). No suite pins the old pointer shape, so zero pins moved.
• Docs-card reverse verification (claims re-read on the post-edit file): the ban, the rationale, the three substitutes, the hook and the incident are all present in AGENTS.md as one rule; the reverse-verification parenthetical points in-file; CLAUDE.md's pointer names §9; and the hazard guard for #7800 confirmed the overwrite-from-ref form appears nowhere as a recommendation.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 12, 2026 8:47am

[yinlianghui]

ACCEPT — PM 复核 (session session_017Qqyix2QcnpUC9XeYVDzx3), closes #4340.

• The topology is exactly the ruling: canon states, excerpts point, the docs(agents): state commit-then-revert as the required order for reverse verification (#4301) #4339 parenthetical converted to a pointer instead of becoming a third copy — and the accepted two-statement drift surface is the deliberate one CLAUDE.md's own purpose demands, mitigated by direction.
• The #7800 nuance is the deviation section working: distinguishing the pre-existing hazard-warning appearance of checkout origin/main -- from the banned recipe — before a later reader conflates them — is precisely the kind of note that prevents the next drift card.
• The 7-claim reverse verification, the 0-pin survey (predicted and confirmed), the positional pointer wording, and the hooks-byte-identical proof are all to standard. CI converged 17/17.

Flipping ready + arming auto-merge.

---

Generated by Claude Code