docs: restore stashes by stable identity

Co-Authored-By: Codex <noreply@openai.com>
This commit is contained in:
pikastech
2026-07-18 10:34:31 +02:00
parent 9cc000c0d2
commit d87165ddd6
4 changed files with 35 additions and 4 deletions
+2 -2
View File
@@ -9,11 +9,11 @@
## P0: 主 worktree 同步提交第一原则
- P0: 固定主/目标 worktree 与 remote 不一致时,必须按顺序处理:
-`git stash push -u` 保存全部脏改,包括 untracked;
-带当前操作唯一 marker 的 `git stash push -u -m <marker>` 保存全部脏改,包括 untracked,并按 marker 记录稳定 stash commit SHA
-`git fetch` 刷新 remote
- 仅落后时用 `git pull --ff-only` 快进;
- 分叉时必须把 remote 分支语义合并到固定 worktree,逐项解决冲突并保留双方有效语义;
-`git stash apply` 恢复并继续按语义解决冲突或重复内容;
-`git stash apply <stash-commit-sha>` 精确恢复并继续按语义解决冲突或重复内容,禁止依赖可变的 `stash@{N}` 或无参数 apply
- 先提交并推送语义合并及主工作区恢复出的并行改动,再继续后续任务;
- 禁止绕过未对齐的固定 worktree,改用干净 anchor 或新任务 worktree 继续;
- 禁止用 reset、drop 或覆盖式 checkout 丢弃并行改动。
@@ -0,0 +1,22 @@
# R5 任务报告
## 问题
固定 worktree 同步流程原先使用 `git stash push -u` 后再执行无参数 `git stash apply`。并发任务在两步之间新增 stash 时,`stash@{0}` 会改变。本次 Workbench closeout 已真实观察到无参数 apply 恢复了另一任务的 Web Probe 修改,随后只能按 stash message 从列表重新定位正确对象。
## 修复
- 建立 [UniDesk #2516](https://github.com/pikasTech/unidesk/issues/2516)。
- `docs/reference/devops-hygiene.md` 规定 stash push 必须携带当前操作唯一 marker。
- 按 marker 从 `git stash list --format='%H %gs'` 解析稳定 stash commit SHA。
- 同步后只允许 `git stash apply <stash-commit-sha>` 精确恢复。
- 禁止依赖可变 `stash@{N}` 或执行无参数 apply。
- apply 后必须核对原文件集合和新增并行修改仍存在。
- `AGENTS.md` 的顶级损害预防摘要同步相同规则。
## 验证
- `AGENTS.md` 保持在 10 KiB 硬上限内。
- `git diff --check` 通过。
- 规则面向任意并发仓库和任意任务 marker,不绑定本次 stash 序号、分支或文件。
- 本次主 worktree 中两组并行修改均已恢复并保持未提交,证明按稳定对象恢复不会要求 reset、drop 或覆盖式 checkout。
@@ -30,3 +30,7 @@
## R4 [completed]
解决 [agent_skills #15](https://github.com/pikasTech/agent_skills/issues/15):为 Playwright wrapper 增加不泄露凭据的 fill-file 表单填充,并证明 Secret 不进入 argv、输出或 JSONL 日志,完成任务后将详细报告写入[任务报告](./details/mdtodo-tooling-reliability/R4_Task_Report.md)。
## R5 [completed]
解决 [UniDesk #2516](https://github.com/pikasTech/unidesk/issues/2516):固定主 worktree 同步时记录稳定 stash 对象 ID,并按该 ID 精确恢复,禁止并发仓库使用无参数 git stash apply;更新唯一长期出处与顶级损害预防摘要,完成任务后将详细报告写入[任务报告](./details/mdtodo-tooling-reliability/R5_Task_Report.md)。
+7 -2
View File
@@ -98,15 +98,20 @@ When diagnosing a missing worktree file, first classify ownership. A tracked fil
- 固定主/目标 worktree 的同步前置:
- 只要 HEAD 与 remote/base 不一致,就必须先同步再继续分析或创建任务 worktree;
- 先 `git stash push -u` 保存全部脏改,包括 untracked
- 先记录 `git status --porcelain=v1` 的待恢复文件集合
- 使用带当前操作唯一 marker 的 `git stash push -u -m <marker>` 保存全部脏改,包括 untracked;
- 立即按该 marker 从 `git stash list --format='%H %gs'` 解析并保存唯一 stash commit SHA
- marker 必须绑定当前任务或同步操作,禁止复用固定文案后再按列表位置猜测;
- 再用 `git fetch` 刷新 remote
- 仅落后时执行 `git pull --ff-only <remote> <branch>`
- 分叉时把 remote 分支 merge 到固定 worktree
- 逐项解决冲突并保留双方仍有效的语义;
- 执行 `git stash apply` 后继续处理冲突或重复内容;
- 执行 `git stash apply <stash-commit-sha>` 后继续处理冲突或重复内容;
- apply 后核对原待恢复文件集合与新增并行修改均仍存在;
- 把语义合并及恢复出的并行改动提交、推送到 remote/base。
- stash 与损害预防:
- stash 只用于保护并行修改;
- 并发仓库中禁止执行无参数 `git stash apply`,也禁止把 `stash@{0}` 或其他 `stash@{N}` 当作稳定身份;
- 禁止把 stash 用作清理、丢弃或隐式接管并行任务;
- 禁止使用 reset、drop 或覆盖式 checkout
- 禁止改用干净 anchor 或新任务 worktree 绕过固定 worktree 的语义合并。