oil-ui-pro 0.15.4 → 0.22.2（上游 ui.oiloil.org 正式包）＋ 记 P0-98 跨盘 rename 坑

- oil-ui-pro 升到 0.22.2：references 13→28 份（新增 16、删 imagery.md）、assets 增 cards/（22 组）与 fonts/、SKILL.md 顶层五步结构未改名。
- 升级路径：官方 `npx github:oil-oil/oil-cli update` 稳定失败（error=replace、报「检查目录权限」）。
  真身为 EXDEV —— 解压在 os.tmpdir()（C 盘）、技能目录在 E 盘，Windows 上 rename 不能跨盘；
  CLI 的 catch 把非 CliError 原生异常一律兜底成 replaceFailed，真错误一个字不吐。
  做法＝借其 prepare() 只做下载+校验，再 cp 到同盘 stage、rename 交换；官方命令复验 up_to_date。
- 回归：product-planning 按名引用的 visual-review.md／tools.md／design-direction.md／style-explorer.md 全部健在；命名闸门 2061｜0｜27。
- session-mechanism/references/pitfalls.md 新增 P0-98（含通则：更新器把原生错误兜底成指错方向的人话）。

session-mechanism/references/pitfalls.md

@@ -3794,3 +3794,32 @@ var r = el.getBoundingClientRect();
   静默的 fail-safe 与"正常的等待"在日志里不可区分，等于把排查线索整条抹掉（同族：P0-52）。
   另一条：**判据的取值形态不要靠"我想到的几种写法拉倒"** —— 形态是别人写进来的，
   能想到三种就会漏第四种，而漏掉的那种是**静默**的。要么归一（解码＋规范），要么别用字符串匹配。
+
+---
+
+## P0-98 🔴 **跨盘 rename ⇒ 技能自动更新必然失败，而报错文字指错了方向**（★ 2026-10-14 本机实测）
+
+- **现场**：把 `oil-ui-pro` 从 `0.15.4` 升到 `0.22.2`（上游 `ui.oiloil.org`，官方命令
+  `npx github:oil-oil/oil-cli update oil-ui-pro --path <技能目录>`）。命令稳定失败、可重复：
+  ```json
+  {"ok":false,"command":"update","error":"replace","message":"替换失败，原目录已还原，请检查目录权限。"}
+  ```
+  ⇒ **报错说的"目录权限"是错的**，照它排查会白跑（本机就是 Administrator、目录 rename 实测正常）。
+- **真身**：`EXDEV: cross-device link not permitted` ——
+  CLI 把包解压到 `os.tmpdir()`（本机 = `C:\Users\…\AppData\Local\Temp\`，**C 盘**），
+  而技能目录在 **`E:\`**；Windows 上 `rename` **不能跨盘符**。
+  ⚠️ 该错误的归类还被 CLI 抹掉了：`install.js` 的 catch 里，
+  **非 `CliError` 的原生异常一律兜底成 `replaceFailed`（"检查目录权限"）** ⇒ 真正的 `EXDEV` 一个字都不吐。
+- **判据（怎么一眼认出）**：失败后暂存目录 `.oil-stage-*/` 里**只有 `new/`、没有 `old/`**
+  ⇒ 说明挂在「新内容 → 目标」那一步，而不是读包／校验／下载。
+  另：中途失败会**留下 `.oil-stage-*` 残留**（在同级 `skills/` 下），下次跑前要清。
+- **✅ 正解**：**别让 rename 跨盘** —— 用 CLI 自己的 `prepare()` 只做「下载＋校验」（拿到权威包），
+  然后**先 `cp` 到目标同盘的临时目录、再 `rename` 交换**（同盘 rename 才成立）。
+  实测：`cp` 到 `E:` 同盘 stage ⇒ rename 交换 ⇒ 落地 `0.22.2`（125 文件）⇒
+  再跑官方命令复验得 `{"status":"up_to_date"}`（官方认账）。
+- 🔴 **通则**：**Windows 上凡是"解压到临时目录再搬"的更新器，都要先问"临时目录和目标在不在同一个盘"**
+  —— 跨盘时 `rename` 必炸，且很多更新器把这类原生错误**兜底成一个指错方向的人话**。
+  同族：本机既有纪律「写临时文件 ＋ `os.replace` 原子替换」在**跨盘时同样不成立**（`os.replace` 同为 rename 语义）。
+- ⚠️ 升级后必做的回归：核对**下游按名引用的具体文件还在不在**
+  （本次 `product-planning` 引用的 `visual-review.md`／`tools.md`／`design-direction.md`／`style-explorer.md` 全部健在；
+  新版删了 `imagery.md`、新增 16 份 —— 删除项要逐条确认无下游引用）。