docs(agents): require commit-then-revert for reverse verification

[huangyiirene]

Fixes #7800

The hazard

CLAUDE.md's "Never git stash" block offered four replacements. The first one

git checkout origin/main -- <path>     # then: git checkout <your-branch> -- <path>

silently destroys uncommitted work in exactly the situation it reads as designed for. git checkout <branch> -- <path> copies the file as committed; it knows nothing about working-tree edits. During reverse verification the fix is typically not committed yet — that is the whole point of the exercise — so the "restore" half restores the branch's older version and the edit is gone. Exit 0, no warning, no conflict, no "would be overwritten" refusal.

Already realized, not theoretical: #7739's dev agent (PR #7791) lost an in-flight edit to this recipe today and recovered it only by retyping from context. An agent that hit this after a context compaction would not have recovered.

Adopting objectui's correction, not inventing a second one

objectui merged the equivalent correction this afternoon — verified against the actual commit rather than the issue text:

c880799bc398cfbdda24adb749dfd780776a39bd
docs(agents): require commit-then-revert for reverse verification (#4301) (#4339)
2026-08-11 17:40:19 +0000
 AGENTS.md | 1 +

Its fix has two halves, and this PR mirrors both:

1. objectui's CLAUDE.md lists only the three safe forms — the git checkout origin/main -- <path> line is not present in its copy at all.
2. c880799 added a positive commit-then-revert rule to objectui's AGENTS.md, verbatim:

• 要做反向验证(删掉修复 → 看预期的钉子变红 → 还原)就先把修复 commit 掉。 提交之后,还原是 git checkout <你的分支> -- <path>,对着一个真实存在的 commit 取回;直接对未提交的改动做同一个删除(git checkout origin/main -- <path>)则没有任何还原点 —— 工作区就是唯一副本,而 git stash 一律禁用(共享 stash 栈,见 CLAUDE.md),改动当场就没了。同一天两次踩实:The schemaless nodes' designer forms live only in objectui's hand-written table, and nothing reconciles them — script offers three broken options and cannot author the one that works #4278(PR docs(automation): 补上声明式 connectors: 的手写授权指南 (#4289) #4293)、sys_migration 由 service-storage 注册——账本是平台基础设施，不该由一个可选服务持有 #4243(PR docs(adr): ADR-0104 的 meta 广告位条款按实际落地修订（#3438 后续） #4299),两次都靠会话 transcript 逐行重打才找回来 —— transcript 不全就是净损失。sys_migration 由 service-storage 注册——账本是平台基础设施，不该由一个可选服务持有 #4243 那次是先 commit、再重跑一遍反向验证,最终那组红绿数字才可信。

This also settles a factual conflict in the issue thread: the body states objectui "lists only the three safe forms" (true, and so this is a delete for CLAUDE.md), while triage points at c880799 as a commit-then-revert replacement (also true — it lives in AGENTS.md). Both are right about different files. This PR reconciles them.

What lands here

• CLAUDE.md — drop the hazardous line (−1). The block exists to give agents a reflex that is safe without thinking about it; a recipe whose safety depends on remembering an unstated precondition does not serve that purpose, and the remaining three forms each capture the uncommitted state first and cover the same use case. This leaves the block identical in shape to objectui's copy. Matches the PM ruling on the issue (delete, not annotate).
• AGENTS.md (source of truth) — grep hit: its own stash block at line 194 carried the same recipe. Removed there too, and the commit-then-revert requirement objectui added is stated in the adjacent prose, in this file's English style, citing both repos' incidents (objectui The schemaless nodes' designer forms live only in objectui's hand-written table, and nothing reconciles them — script offers three broken options and cannot author the one that works #4278/sys_migration 由 service-storage 注册——账本是平台基础设施，不该由一个可选服务持有 #4243, this repo's external-datasource-federated-read: external-write refusal (ExternalWriteForbiddenError) leaks to the client as a bare 500 INTERNAL_ERROR #7739).

The AGENTS.md paragraph also picks up the issue's second, smaller point: a matching git diff --stat insertion count is not byte-identity, so a retyped recovery is proved with git diff against a saved patch or git hash-object — the weak reach is what a silent failure mode invites.

Scope notes

• Docs-only. No changeset — skip-changeset handling is the PM's.
• pnpm check:doc-authoring → ✓ doc authoring guard: 375 files clean.
• Not touched, deliberately: objectui (already fixed), .claude/skills/**, content/docs/releases/**.
• Out-of-scope copies found, for the PM to route: the same recipe also appears in .claude/agents/os-dev.md:488, .claude/hooks/guard-shared-stash.sh:32,170 (comment + help text), and .claude/skills/pm-dispatch/SKILL.md:2120. All outside this card's stated file surface; the skills path is explicitly the manual-review channel. Worth a follow-up card.

---

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)
objectstack	Ignored		Aug 11, 2026 8:09pm