# 已知誤解 / 踩過的坑

> 這是 ISEP 自己的坑，不是 InkStoneCo 的（不轉抄，複製即 fork，fork 即漂移）。
> 撞到新坑就 append 一條；session 開場只推最近幾條標題（見 `hooks/session-start-recall.sh` push 5/5），全文在這裡。

⚠️ MISTAKE: 「環境設定」曾經拆成兩份，各自會漂
   症狀: 本機在跑 `InkStoneCo/.claude/`（真身），雲端跑的是 `generate-shell-payload.py`
         另外產生塞進 GitHub 私 repo 的一份（薄殼）。`inkstone/InkStoneCo#57` 實測：薄殼比真身
         少 7 支閘，其中兩支是前一天才立的；`#14` 更早查到雲端 33 支 guard 一支都沒生效。
   正確做法: 只留一份——ISEP 這個 repo 本身就是唯一真相源，本機與雲端裝同一個 plugin。
             改動一律只改這裡，然後兩邊各自 `/plugin update`。不要再改
             `InkStoneCo/.claude/hooks/`（退場中，早晚會刪）。
   原因: 「一份東西兩個副本」在沒有機制強制同步的情況下必然漂移——差異不是誰疏忽，
         是結構本身允許漂移發生。
   日期: 2026-08-20（ISEP `c263866` 建立時就是為了解這個病）

⚠️ MISTAKE: hook 路徑寫死會在雲端斷
   症狀: 舊版 hook 若用 `$CLAUDE_PROJECT_DIR/.claude/hooks/...` 或寫死的絕對路徑指向 hook
         腳本自己，雲端執行時的 cwd 不是本機那個真身目錄，路徑就對不到、hook 直接失效
         （正是上一條「雲端 33 支 guard 一支都沒生效」的根因）。
   正確做法: hook 指自己（找到自己在哪、要 source 的其他 hook 檔）一律用官方
             `${CLAUDE_PLUGIN_ROOT}`。腳本內部要指**專案裡的檔案**（如 `system-dev/wiki/`、
             `system-dev/docs/`）才用 `$CLAUDE_PROJECT_DIR`——那些檔案本來就该住在被操作的
             那個 repo 裡，跟 hook 自己的路徑是两回事，别混。
   原因: 兩種路徑指的是完全不同的東西（「plugin 安裝到哪」vs「正在操作哪個專案」），
         混用就是這條坑的直接原因。
   日期: 2026-08-20（README「路徑規約」段記錄，ISEP 0.1.0 把 51 條 hook 路徑全部改過一輪）

## ⚠️ MISTAKE: 「裝好了」不等於「它在跑」

2026-08-20 實查：ISEP repo 建好、README 寫著 0.1.0、41 支閘都在裡面——
但 `claude plugin list` 裡**根本沒有 ISEP**。本機仍然在跑 `InkStoneCo/.claude/`，
Gitea 上**一個 release tag 都沒有**。

⇒ 「東西做出來了」與「有人在用它」是兩件事，而只有後者算交付。
⇒ 判準：**去執行環境查它有沒有被載入**（`claude plugin list` / `claude plugin details`），
   不要從 repo 裡有什麼檔案去推論。