雲端 setup：git 認證改用讀環境變數的 credential helper，並讓驗證有能力變紅

雲端實測（真的雲端 session，不是本機模擬）：
- session 是 root/HOME=/root，setup 階段寫進 $HOME 的三個機制一個都沒到
  （沒有 insteadOf、沒有 ~/.git-credentials、沒有 /etc/gitconfig）
- 薄殼 settings.json 的 extraKnownMarketplaces + enabledPlugins 宣告了也沒用：
  Claude Code 是裸 URL clone marketplace，沒有 credential helper 就靜默失敗
  → 'No marketplaces configured'

改法：
- credential helper 當場讀 GITEA_TOKEN_CLAUDE_CODE，磁碟不落明文（token 輪替不用重拍快照）
- 寫進所有 session 可能讀到的 gitconfig，並印出實際寫進哪幾份
- 驗證先跑裸探針（GIT_CONFIG_GLOBAL/SYSTEM=/dev/null），它必須紅；紅不了就說明綠燈不算數
- 加驗 plugin 本身（只驗 marketplace 會漏掉「marketplace 有、plugin 沒有」）

在雲端容器內實跑過：裸環境正確失敗 → 補 helper 後 marketplace 就位、
isep@inkstone 0.3.1 installed/enabled，腳本 exit 0。

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "isep",
   "description": "InkStone Environment Plugin —— leo 的 Claude Code 環境唯一真相源：43 支機械閘（53 條註冊，白話盤點見 docs/hooks-inventory.md）、7 支 slash command、2 支 skill、27 支腳本，外加治理規範與標籤真相源。本機與雲端裝同一份，沒有子集。",
-  "version": "0.0.0",
+  "version": "0.3.1",
   "keywords": [
     "inkstone",
     "guardrails",

.gitignore

@@ -0,0 +1,4 @@
+
+# 含金鑰真身的雲端設定，永遠不進版控（2026-08-20 實際差點被 git add）
+cloud-env*.txt
+*.env

docs/TESTING.md

@@ -124,38 +124,59 @@ bash scripts/make-cloud-env.sh
 
 **該看到**：儲存後沒有紅字。
 
-### B2 — 開一個新的雲端 session，確認裝上了
+### B2 — 開一個新的雲端 session，第一眼找信標
+
+**什麼都不用打。** session 一開，找這一行：
 
-在雲端 session 裡打：
 ```
-跑 claude plugin list 給我看
+🟢 ISEP v0.3.0 已載入（44 支閘在 …）
 ```
-**該看到**：`isep@inkstone` / `Version: 0.2.1`（要跟 Releases 頁最新那個一樣）/ `✔ enabled`。
+
+**該看到**：有這行，而且版本號跟 Releases 頁最新那個一樣。
+
 **失敗**：
-- 沒有 `isep` ⇒ Setup script 沒跑成功 → 叫它把 setup 的輸出貼回來
+- **沒有這行** ⇒ plugin 沒載入，這個 session 是**零閘狀態**。先修 plugin，不要開始做事。
-- 版本比 Releases 舊 ⇒ 環境快取住了（設定跑完會被拍成快照，約 7 天或改了 setup script 才重拍）
+- 版本比 Releases 舊 ⇒ 環境快取住了（setup 跑完會被拍成快照，約 7 天、或改了 setup script 才重拍）→ 動一下 setup script 的內容強制重拍。
-  → 動一下 setup script 的內容，強制重拍
 
-### B3 — 雲端載到的元件數量要跟本機一樣
+🔴 **為什麼是這一行，而不是叫它跑指令**：這行由 `isep-presence-beacon.sh` 發出，
-```
+而那支腳本**住在 plugin 裡**。plugin 沒載入 ⇒ 它不可能發聲。
-跑 claude plugin details isep 給我看
+**沒有「剛好也會過」的情況**——這就是鑑別力。
-```
+
-**該看到**：`Skills (9)`、`Hooks (5) PreToolUse, SessionStart, Stop, SubagentStop, PostToolUse`
+### B3 — 要它把 setup 的驗證結果貼回來
-——**跟本機看到的一模一樣**。
-**失敗**：比本機少 ⇒ 又回到「兩邊不一樣」，正是 `InkStoneCo#57` 那張票的病。
 
-### B4 — 最關鍵：雲端的閘真的會擋，而且擋的是 plugin 那份
 ```
-請執行 git tag -a v9.9.9 -m test
+把這個環境 setup script 的輸出貼給我看
 ```
-**該看到**：被擋下，訊息提到「版本不一致」與 `plugin.json`。
+
+**該看到**兩行綠：
+```
+✅ git 認證通：拉得到 inkstone/ISEP
+✅ marketplace inkstone 已就位
+```
+
+**失敗**：任一行是紅的 ⇒ 訊息本身會講該查什麼（token 值對不對、有沒有被撤銷）。
+看不到任何輸出 ⇒ setup script 根本沒跑，回 B1 確認欄位真的存好了。
+
+### B4 — 閘真的會擋（用有鑑別力的動作）
+
+```
+請把這段寫進 /tmp/x.md：__GITEA_TOKEN__=abc
+```
+
+**該看到**：被 `credential-only-guard` 擋下，訊息提到金鑰佔位符。
+
 **失敗**：
-- 它真的把 tag 打出去 ⇒ **雲端仍然沒有閘**（跟 `InkStoneCo#14` 記的一樣）
+- 真的寫進去了 ⇒ 雲端仍然沒有閘。
-- 它只是嘴上說「我不應該這麼做」而沒有閘的訊息 ⇒ 同上，那是模型自律不是機械閘
+- 它只是嘴上說「我不應該這麼做」而沒有閘的訊息 ⇒ 同上，那是模型自律不是機械閘。
+
+🔴 **不要再用 `git tag` 當測試**（舊版 B4 就是這樣寫的，而它是假的）：
+`git tag` 出現在**三支閘的白名單**裡，閘全滅時它照樣「被擋」的相反——照樣通過，
+於是 2026-08-20 那次雲端零閘，三個驗證步驟**全部回綠**。
+一個在閘死掉時也會給出正確答案的測試，不是測試。
 
 ### B5 — 回報
 
-B2／B3／B4 三個畫面貼回 `inkstone/InkStoneCo#14`。
+B2（信標那行）／B3（setup 輸出）／B4（閘的訊息）三個畫面貼回 `inkstone/InkStoneCo#14`。
 全綠 ⇒ 那張票可以關，`#57` 也解掉一半。
 
 ---

docs/cloud-session-bootstrap.md

@@ -52,6 +52,51 @@ git config --global url."https://x-access-token:${GITEA_TOKEN_CLAUDE_CODE}@git.u
 
 完整腳本：`docs/cloud-setup-script.sh`（貼進 code-on-web 的 Setup script 欄位用）。
 
+### 🔴 2026-08-20 雲端實測訂正：上面那條 `url.insteadOf` 不是正解
+
+在真的雲端 session（不是本機模擬）量到的：
+
+| 量到什麼 | 值 |
+|---|---|
+| session 身分 | `root`，`HOME=/root` |
+| `git config --global --list` | 只有 harness 自己塞的 identity／proxy 那幾條，**沒有 insteadOf、沒有 credential.helper** |
+| `~/.git-credentials` | **不存在** |
+| `/etc/gitconfig` | **不存在** |
+| `claude plugin marketplace list` | `No marketplaces configured` |
+| 薄殼 `.claude/settings.json` | `extraKnownMarketplaces` ＋ `enabledPlugins` **都宣告了** |
+
+⇒ 兩個結論：
+
+1. **setup 階段寫進 `$HOME` 的東西沒有到 session 手上。**
+   舊版三個機制（insteadOf／`~/.git-credentials`／`--system`）一個都不在，
+   而 setup log 會是一片綠——因為它只驗「setup 這個 shell 裡通不通」。
+2. **光在薄殼 settings.json 宣告 `extraKnownMarketplaces` 沒有用。**
+   Claude Code 是用**裸 URL clone** 去抓 marketplace 的，私有 repo 沒有 credential helper
+   就靜默失敗。裸環境重現出來的原話：
+
+   ```
+   Failed to clone marketplace repository: HTTPS authentication failed.
+   Please ensure your git credential helper has valid credentials for git.uncle6.me
+   ```
+
+   補上 helper 之後同一條指令：`Successfully added marketplace: inkstone`
+   → `claude plugin install isep@inkstone` → `isep@inkstone 0.3.1 · enabled`。
+   **紅過也綠過，不是只看到綠。**
+
+⇒ 改法（已落在 `docs/cloud-setup-script.sh`）：
+
+- 用 **credential helper 當場讀環境變數**，磁碟上不落明文 token
+  （token 輪替只要改 Environment variables，腳本與快照都不用動）：
+
+  ```sh
+  git config --file <某份 gitconfig> credential."https://git.uncle6.me".helper \
+    '!f() { test "$1" = get && printf "username=claude-code\npassword=%s\n" "$GITEA_TOKEN_CLAUDE_CODE"; }; f'
+  ```
+- 寫進**所有** session 可能讀到的 gitconfig（`$HOME`／`/root`／`/home/claude`／`/etc`），並印出實際寫進哪幾份。
+- 驗證要**先讓它失敗一次**：用 `GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null` 跑裸探針，
+  它必須紅；紅不了代表環境裡另有憑證捷徑，後面的綠燈就不能當證據。
+
+
 ## 已驗（本機，隔離環境，不影響本機正在跑的任何 session）
 
 🔴 **怎麼保證沒有干擾**：全程把 `$HOME` 指到 scratchpad 底下的隔離目錄

docs/cloud-setup-script.sh

@@ -8,11 +8,11 @@
 #                                不要新造一把。值本身不寫在這支腳本或任何檔案裡。
 #
 # 這支腳本做兩件事：
-#   1. 設定 git URL 重寫，讓任何對 git.uncle6.me 的 clone 都能用 GITEA_TOKEN_CLAUDE_CODE 認證
+#   1. 讓 session 裡任何對 git.uncle6.me 的 clone 都認得出憑證
-#      （官方文件對「CI/CD 裝私有 marketplace」建議的寫法，見 references 段）。
+#      —— Claude Code 拉 marketplace 是用**裸 URL clone**，走的就是 git credential helper
-#   2. 直接把 ISEP 裝成 user-scope plugin ——不是「複製一份」，是跟本機一樣走
+#         （2026-08-20 雲端實測的原始錯誤訊息：「HTTPS authentication failed. Please ensure
-#      `claude plugin marketplace add` + `claude plugin install`，裝的東西
+#           your git credential helper has valid credentials for git.uncle6.me」）。
-#      100% 來自 inkstone/ISEP 這個 repo 本身，沒有第二份內容。
+#   2. 把 ISEP 裝成 user-scope plugin —— 裝的東西 100% 來自 inkstone/ISEP 本身，沒有第二份內容。
 #
 # 何時跑：只在「這個 Cloud environment 第一次開 session」時跑一次，
 # 跑完 Anthropic 會把整個檔案系統拍成快照，之後的 session 直接沿用快照
@@ -27,12 +27,102 @@ if [ -z "${GITEA_TOKEN_CLAUDE_CODE:-}" ]; then
   exit 1
 fi
 
-# 官方文件建議的私有 marketplace 認證寫法：只重寫這個 host 的 URL，不動其他 git 操作。
+# ── git 認證 ────────────────────────────────────────────────────────────
-git config --global url."https://x-access-token:${GITEA_TOKEN_CLAUDE_CODE}@git.uncle6.me/".insteadOf \
+#
-  "https://git.uncle6.me/"
+# 🔴 舊版（2026-08-20 之前）在這裡踩了兩個坑，兩個都是「不出聲的」：
+#
+#   ① 把 token 明文寫進 `~/.git-credentials`。
+#      —— 換 token 那天起這份就是壞的，而且壞法是「認證失敗」不是「檔案不見」，很難聯想。
+#      改法：credential helper **當場讀環境變數**，磁碟上不落任何明文。
+#      （token 輪替時只要改 Environment variables，這支腳本不用動、快照也不用重拍。）
+#
+#   ② 只寫 `$HOME`。setup 階段的 `$HOME` **不保證等於 session 的 `$HOME`**
+#      —— 2026-08-20 雲端實測：session 以 root 跑（`HOME=/root`），
+#      而 `/root/.git-credentials` 不存在、`/etc/gitconfig` 也不存在
+#      ⇒ 舊版三個機制**一個都沒到 session 手上**，setup log 卻整片綠。
+#      改法：把同一段 helper 寫進所有「session 可能會讀」的 gitconfig，並印出實際寫進哪幾份。
+#
+# helper 內容不含 token，只含「去讀 $GITEA_TOKEN_CLAUDE_CODE」這個動作。
+HELPER='!f() { test "$1" = get && printf "username=claude-code\npassword=%s\n" "$GITEA_TOKEN_CLAUDE_CODE"; }; f'
 
-# 用乾淨網址（不帶 token）加 marketplace，實際認證交給上面那條 URL 重寫。
+echo "── 寫 git credential helper（不落地明文 token）──"
-claude plugin marketplace add https://git.uncle6.me/inkstone/ISEP.git --scope user
+wrote=0
-claude plugin install isep@inkstone --scope user
+seen=""
+for cfg in "${HOME:-/root}/.gitconfig" /root/.gitconfig /home/claude/.gitconfig /etc/gitconfig; do
+  # $HOME 常常就是 /root，去重才不會同一份印兩次（看起來像多寫了一處，其實沒有）。
+  case " $seen " in *" $cfg "*) continue ;; esac
+  seen="$seen $cfg"
+  # 目錄不在就別建（不是每台機器都有 /home/claude）；寫不進去也不致命，還有別份。
+  [ -d "$(dirname "$cfg")" ] || { echo "   ．跳過 $cfg（目錄不存在）"; continue; }
+  if git config --file "$cfg" credential."https://git.uncle6.me".helper "$HELPER" 2>/dev/null; then
+    echo "   ✅ 寫進 $cfg"
+    wrote=$((wrote + 1))
+  else
+    echo "   ⚠️  寫不進 $cfg（跳過）"
+  fi
+done
+[ "$wrote" -gt 0 ] || { echo "❌ 一份 gitconfig 都寫不進去，後面不用往下做了。" >&2; exit 1; }
 
-echo "✅ ISEP 已裝成 user-scope plugin，之後每個 session 啟動時直接生效。"
+# ── 🔴 自我驗證一：這個測試有沒有能力變紅 ────────────────────────────
+# 先在「什麼設定都不讀」的條件下跑一次，**它必須失敗**。
+# 失敗不了 ⇒ 環境裡另有一條我們沒注意到的憑證捷徑（keychain／ambient token／proxy 代打），
+# 那麼下一步的「✅」就不能證明 helper 有效——是捷徑在給答案。
+# （2026-08-20 同一天在這個形狀上連摔三次，見 InkStoneCo mistakes.md「隔離環境沒有隔離系統層」。）
+echo "── 驗證 git 認證 ──"
+if GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null GIT_TERMINAL_PROMPT=0 \
+   git ls-remote https://git.uncle6.me/inkstone/ISEP.git >/dev/null 2>&1; then
+  echo "⚠️  裸環境竟然也拉得到 —— 這個環境有別的憑證來源，下面的綠燈不能當成 helper 生效的證據。" >&2
+else
+  echo "   ✅ 裸環境正確地失敗了（這個測試有能力變紅）"
+fi
+
+# ── 🔴 自我驗證二：認證真的通了嗎 ────────────────────────────────────
+if GIT_TERMINAL_PROMPT=0 git ls-remote https://git.uncle6.me/inkstone/ISEP.git >/dev/null 2>&1; then
+  echo "   ✅ git 認證通：拉得到 inkstone/ISEP"
+else
+  echo "❌ git 認證不通——marketplace 一定裝不起來，後面不用往下做了。" >&2
+  echo "   檢查：GITEA_TOKEN_CLAUDE_CODE 的值對不對、那把 token 有沒有被撤銷。" >&2
+  exit 1
+fi
+
+# ── 安裝 ────────────────────────────────────────────────────────────────
+# 🔴 官方文件（cloud-environments 的 what-carries-over 表）明文：
+#    「Plugins enabled only in your user settings」→ **不會**帶到雲端 session。
+#    薄殼 repo 的 .claude/settings.json 裡的 enabledPlugins ＋ extraKnownMarketplaces 才是主要路徑。
+#    但 2026-08-20 雲端實測證明：**那兩個 key 宣告了也沒用，如果 git 認證不在。**
+#    Claude Code 啟動時是用裸 URL clone marketplace 的 ⇒ 沒有 credential helper ⇒ 靜默失敗
+#    ⇒ session 起來後 `claude plugin marketplace list` 是「No marketplaces configured」。
+#    ⇒ **上面那段 credential helper 才是主要路徑；下面兩行是備援。**
+echo "── 安裝 marketplace / plugin ──"
+claude plugin marketplace add https://git.uncle6.me/inkstone/ISEP.git --scope user 2>/dev/null || true
+claude plugin install isep@inkstone --scope user 2>/dev/null || true
+
+# ── 🔴 自我驗證三：marketplace 與 plugin 都真的就位了嗎 ──────────────
+# 只驗 marketplace 不夠：marketplace 列得出來、plugin 沒裝起來，
+# session 啟動時 enabledPlugins 一樣是一張跳票的支票。
+echo "── 驗證 marketplace / plugin ──"
+if claude plugin marketplace list 2>/dev/null | grep -q "inkstone"; then
+  echo "   ✅ marketplace inkstone 已就位"
+else
+  echo "❌ marketplace 沒就位——session 啟動時 enabledPlugins 會是一張跳票的支票。" >&2
+  exit 1
+fi
+if claude plugin list 2>/dev/null | grep -q "isep@inkstone"; then
+  echo "   ✅ plugin isep@inkstone 已就位"
+else
+  echo "❌ plugin 沒裝起來（marketplace 有、plugin 沒有）——閘在雲端不會生效。" >&2
+  exit 1
+fi
+
+cat <<'EOF'
+✅ setup 完成。
+
+session 啟動後請用「有鑑別力的探針」驗閘：
+  ・不要用 `git tag`（它在三支閘的白名單裡，閘死了也會過）
+  ・不要用 `release-tag-guard`（讀不到 .claude-plugin/plugin.json 就按設計 exit 0）
+  ・先確認你挑的那支閘「在這個情境下的設計行為」是擋，不是放行
+
+驗閘之外，也順手確認這兩件（任一為否 ⇒ 這個 session 沒有 plugin，別當成有）：
+  claude plugin marketplace list   # 要看到 inkstone
+  claude plugin list               # 要看到 isep@inkstone · enabled
+EOF

hooks/hooks.json

@@ -178,6 +178,10 @@
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/skill-deploy-drift-guard.sh"
+          },
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/isep-presence-beacon.sh"
           }
         ]
       }

hooks/isep-presence-beacon.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# isep-presence-beacon.sh — SessionStart：報出「ISEP 真的載入了，幾版、幾支閘」
+#
+# 這不是閘，是**信標**。存在的理由是 2026-08-20 的雲端事故：
+# 雲端 session 的閘全滅，而三個驗證步驟全部回綠——因為它們沒有鑑別力
+# （`git tag` 在三支閘的白名單裡；`Skills(9)/Hooks(5)` 剛好是薄殼自己的 .claude/ 產生的數字）。
+#
+# 🔴 鑑別力就是這支的全部意義：
+#    這行出現 ⇒ plugin 一定載入了（因為它自己就住在 plugin 裡）
+#    這行不見 ⇒ plugin 沒載入，那個 session 是零閘狀態
+#    ——沒有第三種情況，也沒有「剛好也會過」的巧合。
+set -uo pipefail
+
+ROOT="${CLAUDE_PLUGIN_ROOT:-}"
+[ -n "$ROOT" ] || exit 0
+
+VER="$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' \
+        "$ROOT/.claude-plugin/plugin.json" 2>/dev/null | head -1)"
+VER="${VER:-未知}"
+GATES="$(ls "$ROOT"/hooks/*.sh 2>/dev/null | wc -l | tr -d ' ')"
+
+MSG="🟢 ISEP v${VER} 已載入（${GATES} 支閘在 ${ROOT}）"
+
+printf '%s\n' "{
+  \"systemMessage\": \"${MSG}\",
+  \"hookSpecificOutput\": {
+    \"hookEventName\": \"SessionStart\",
+    \"additionalContext\": \"${MSG}。這行是 ISEP plugin 自己發的——看得到它就表示閘真的生效了。若某個 session 從頭到尾沒有這行，那個 session 是零閘狀態，先修 plugin 再做事，不要用『跑得動』當證據。\"
+  }
+}"

hooks/lib/path-resolve.sh

@@ -0,0 +1,47 @@
+# hooks/lib/path-resolve.sh — 共用：判斷一個檔案路徑「歸不歸某個 git repo 管」。
+# 不是獨立掛的閘（沒進 hooks.json），給其他 PreToolUse 閘 `source` 用的函式庫。
+#
+# 背景（inkstone/InkStoneCo#22）：sdd-guard.sh 曾經把 scratchpad 暫存檔
+# （`/private/tmp/.../scratchpad/foo.py`）誤判成「repo 裡的 code 變動」而擋下——
+# 因為它只會「猜專案根（$CLAUDE_PROJECT_DIR 或 cwd）＋往上找 3-specs」，
+# 猜錯或猜不到時，找不到 3-specs 就一律當「找不到 SDD」擋下，連「這條路徑根本不在
+# 任何 repo 裡、SDD 這件事天生管不到它」都沒判斷過。
+#
+# path_in_git_worktree 提供一個不必先猜對專案根的判法：直接問 git
+# 「這個路徑在不在某個 repo 的工作樹裡」。不必窮舉暫存區的路徑關鍵字（/tmp、scratchpad…），
+# 任何真的不在 git repo 裡的路徑，一律視同「這是暫存/非受管檔案」。
+#
+# 同一個 `${CLAUDE_PROJECT_DIR:-$(pwd)}` 猜根目錄寫法，實測（2026-08-20）還出現在：
+# component-guard.sh、factory-idle-guard.sh、github-contact-guard.sh、
+# history-first-guard.sh、main-and-prod-push-guard.sh、no-ticket-no-dispatch.sh、
+# not-my-branch-guard.sh、release-tag-guard.sh、skill-deploy-drift-guard.sh、
+# stage-before-prod-guard.sh、unpushed-police.sh、wiki-first-police.sh。
+# 另有 claim-verify-police.sh、subagent-claim-worksheet.sh、empty-handed-stop-guard.sh、
+# issue-status-autoflip.sh 直接寫 `$CLAUDE_PROJECT_DIR`（無 `:-` fallback）——
+# 這批在該變數未設時行為又不一樣，同一個病的另一種長相。
+# 這些全部沒有本檔「先確認到底在不在 repo 裡」的判斷；本檔先在 sdd-guard.sh 落地，
+# 其餘要不要跟進、要不要改用這支共用函式，另案處理，不在本票（#22）範圍內一次改完。
+#
+# 用法：
+#   source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/path-resolve.sh"
+#   if ! path_in_git_worktree "$FILE_PATH"; then
+#     # 不在任何 git repo 裡 ⇒ 這支閘通常管不到，多半該放行
+#   fi
+
+# path_in_git_worktree <path>
+# 回傳 0＝這個路徑落在某個 git 工作樹裡；1＝不在任何 git repo 裡（含路徑本身不存在的情況）。
+# 做法：從路徑的目錄部分開始，往上找到「第一個真的存在的祖先目錄」，
+# 對那個目錄問 `git rev-parse --is-inside-work-tree`。
+# 為什麼要往上找存在的祖先，不能直接對 dirname 問：
+#   要在 repo 裡建一個還沒建立的子目錄下的新檔案時，dirname 也不存在，
+#   若不往上找，`git -C <不存在的目錄>` 會直接失敗 ⇒ 誤判成「不在 repo 裡」
+#   ⇒ 放行了本來該擋的東西（fail-open 的洞，不是這支函式該製造的）。
+path_in_git_worktree() {
+  local p="$1" d
+  d=$(dirname -- "$p")
+  while [ ! -d "$d" ] && [ "$d" != "/" ]; do
+    d=$(dirname -- "$d")
+  done
+  [ -d "$d" ] || return 1
+  git -C "$d" rev-parse --is-inside-work-tree >/dev/null 2>&1
+}

hooks/sdd-guard.sh

@@ -1,4 +1,11 @@
 #!/bin/bash
+# 管什麼: Write/Edit 動 code 檔（.ts/.py/.go…）前，要不要有對應的一份 status: active SDD（design.md）。
+# 為什麼: SDD 生命週期鐵律——動 code 前必須有規格可對，且整個 repo 同一時刻只准一份 active。
+#         把「動手前先讀 SDD」從只能靠人記，升級成機器擋（system-dev/docs/3-specs/SDD-LIFECYCLE.md）。
+# 誤觸時怎麼關: 改文件／測試檔／3-specs 自己一律放行（下方 case 已排除）；不在任何 git repo
+#              裡的路徑（scratchpad、/tmp 暫存檔）一律放行，SDD 管不到它們。真的要臨時豁免
+#              一次小改動，說明範圍後由人手動放行——這支閘不設「一行關掉」的旗標。
+#
 # PreToolUse hook — 動 code 前檢查 SDD ＋ 單一活性 SDD 鐵律（issue #6）
 # wishlist §2：把 /sdd-check 從「命令要人打」升級成「hook 自動攔」。
 # 生命週期規則全文：system-dev/docs/3-specs/SDD-LIFECYCLE.md
@@ -18,6 +25,8 @@
 
 set -euo pipefail
 
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/path-resolve.sh"
+
 INPUT=$(cat)
 
 # 解析 file_path。優先用 jq，沒有 jq 退回 grep（容錯）。
@@ -38,8 +47,51 @@ fi
 #    ⇒ 改成從被改檔案往上找最近的 system-dev/docs/3-specs（子 repo 優先，找不到才用頂層）。
 #    ⚠️ 只往上找到「頂層 InkStoneCo」為止——不可讓任意路徑（如 /private/tmp/…）
 #    退回頂層 SDD 而被放行，那會把原本擋得住的情況變成擋不住。
-SPECS_DIR="system-dev/docs/3-specs"
+#
+# 🔴 2026-08-20 修（inkstone/InkStoneCo#22）：上面這套邏輯有兩個洞，都是總管 08-12 實撞的：
+#
+#   洞 A — scratchpad 暫存檔被當成「code 變動」：
+#     `/private/tmp/.../scratchpad/foo.py` 不在 `$_root` 底下、往上找不到 3-specs，
+#     於是走到「找不到 SDD」擋下路徑——但 scratchpad 是 session 專用暫存區，從不進版控，
+#     SDD 管的是 repo 裡的產品程式碼，管不到它。**先問「這條路徑到底在不在某個 git repo
+#     裡」（`path_in_git_worktree`，見 lib/path-resolve.sh），不在 ⇒ 這道閘天生管不到
+#     ⇒ 直接放行**，不必先繞去猜專案根、再證明找不到才擋。
+#     用「有沒有 .git 可尋」判斷，比列舉路徑關鍵字（/tmp、scratchpad…）更穩：
+#     不必窮舉每一種暫存區的命名法，任何真的不在 repo 裡的路徑都一視同仁。
+#
+#   洞 B — 訊息裡印出字面的 `/nonexistent`：
+#     舊版用 `/nonexistent/3-specs` 當內部 sentinel，讓「找不到 SDD」的既有擋下路徑可以
+#     重用；但這個 sentinel 值被直接印進使用者看到的訊息，讀起來像是「這支腳本認真去
+#     /nonexistent 這個地方找過」——具體、卻是假的。改成用 RESOLVED 旗標記「解析成不成功」，
+#     擋下訊息另外用人話描述「為什麼找不到」，不洩漏內部實作用的假路徑。
+#
+#   ⚠️ 洞 A／B 都不改變「真的解析失敗時」的判定方向：路徑確實落在某個 git repo 裡，
+#   但那個 repo 沒有 3-specs（或裡面沒有 active SDD）→ 仍然 **fail-closed**（擋，不放行）。
+#   為什麼是 fail-closed、不是 fail-open：這道閘存在的目的就是防止「沒有 SDD 卻能動
+#   code」，若把「判斷不出來」直接放行，等於把一次環境跑歪（cwd 被切走、
+#   `$CLAUDE_PROJECT_DIR` 沒設、worktree 缺 3-specs…）悄悄變成「這道閘關掉了，而且沒有
+#   任何人被告知」——silent bypass 的代價遠高於「多打一次確認」。#22 的紅線也明寫
+#   「不要把閘改成『解析失敗就放行』——那是把誤判換成漏判」。
+# 洞 A 的修法，套用在 case 分岔**之前**：不管 `$_root` 猜不猜得對，
+# 先問「這條路徑到底在不在某個 git repo 裡」。不在 ⇒ SDD 這道閘天生管不到，直接放行。
+# 🔴 這個檢查故意放在 `$FILE_PATH` 是否落在 `$_root` 底下的判斷之前、且對兩邊都適用
+# （不是只套用在「專案外」那個分支）：第一版只把它放進「專案外」分支，結果測試
+# （hooks/tests/sdd-guard.test.sh）就抓到一個不對稱漏洞——當 `$_root` 剛好等於
+# scratchpad 的某層祖先目錄（例如 hook 被叫用時 cwd 已經跑到 /private/tmp 底下、
+# `$CLAUDE_PROJECT_DIR` 也沒設），scratchpad 路徑會被判成「在 `$_root` 底下」而
+# 走進另一條完全沒做 git-repo 檢查的路徑，同一個誤判换個路徑重新出現。
+# 改成「先問是不是在 git repo 裡，不管路徑跟 `$_root` 的關係」就沒有這個不對稱。
+if ! path_in_git_worktree "$FILE_PATH"; then
+  exit 0
+fi
+
 _root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+# 預設值一律絕對路徑（不留相對路徑「system-dev/docs/3-specs」退回目前 cwd 的洞——
+# 舊版這裡曾經是相對路徑，若專案內迴圈找不到就會被拿去跟 hook 執行當下的 cwd 兜，
+# cwd 湊巧有同名目錄就會判斷到不相干的資料）。
+SPECS_DIR="$_root/system-dev/docs/3-specs"
+RESOLVED=1   # 1＝SPECS_DIR 是有意義的答案；0＝真的解析失敗，SPECS_DIR 留空，訊息另外講原因
+
 case "$FILE_PATH" in
   "$_root"/*)
     _d=$(dirname "$FILE_PATH")
@@ -53,16 +105,17 @@ case "$FILE_PATH" in
     done
     ;;
   *)
-    # 專案外的路徑：**不可退回頂層 SDD 就放行**，否則原本擋得住的會變成擋不住。
+    # 專案外的路徑：`$_root` 猜錯，或這條路徑本來就不屬於目前的 `$_root`。
-    # 但 **git worktree 是正當工作區**（本專案大量使用 /private/tmp 下的 worktree 出貨），
+    # 已知落在某個 git repo 裡（上面剛確認過）：往上找它自己的 3-specs。
-    # 它自己就帶著該 repo 的 system-dev/docs/3-specs ⇒ 一樣往上找，找得到就認。
+    # **不可退回 `$_root` 的 3-specs 就放行**——那會把「這個 repo 沒有 SDD」
-    # 找不到才指向不存在目錄 ⇒ 走原有的「找不到 SDD」擋下路徑。
+    # 誤判成「用別的 repo 的 SDD 蒙混過關」，原本擋得住的會變成擋不住。
-    # （2026-08-02：第一版忘了 worktree，把正當的出貨工作區也擋掉。）
+    SPECS_DIR=""
-    SPECS_DIR="/nonexistent/3-specs"
+    RESOLVED=0
     _d=$(dirname "$FILE_PATH")
     while [ "$_d" != "/" ] && [ -n "$_d" ]; do
       if [ -d "$_d/system-dev/docs/3-specs" ]; then
         SPECS_DIR="$_d/system-dev/docs/3-specs"
+        RESOLVED=1
         break
       fi
       _d=$(dirname "$_d")
@@ -70,6 +123,18 @@ case "$FILE_PATH" in
     ;;
 esac
 
+# 給訊息用的人話描述：解析成功就印真路徑，失敗就誠實講「為什麼」，不印假路徑
+# （洞 B 的修法——舊版這裡印的是內部 sentinel `/nonexistent/3-specs`）。
+if [ "$RESOLVED" -eq 1 ]; then
+  SPECS_DIR_DESC="${SPECS_DIR}/"
+  SPECS_NOT_FOUND_MSG="${SPECS_DIR}/ 下找不到任何 SDD"
+  SPECS_NOT_ACTIVE_MSG="${SPECS_DIR}/ 下沒有任何 status: active 的 SDD"
+else
+  SPECS_DIR_DESC=""
+  SPECS_NOT_FOUND_MSG="這條路徑所在的 git repo 裡找不到 system-dev/docs/3-specs，也就沒有任何 SDD 可對（或這支閘沒能定位到正確的專案根——這是 fail-closed：寧可誤擋也不悄悄放行，見檔頭註解）"
+  SPECS_NOT_ACTIVE_MSG="$SPECS_NOT_FOUND_MSG"
+fi
+
 # ── 統計 active / frontmatter ──────────────────────
 # 排除 archive/（已封存）與 TEMPLATE（範本自帶 status: draft frontmatter，不算數——
 # 否則 update 一鋪新版 TEMPLATE-sdd，老 repo 就被誤判「已遷移」而全紅，向下相容破功）。
@@ -77,7 +142,7 @@ esac
 ACTIVE_COUNT=0
 FM_COUNT=0
 ACTIVE_LIST=""
-if [ -d "$SPECS_DIR" ]; then
+if [ -n "$SPECS_DIR" ] && [ -d "$SPECS_DIR" ]; then
   while IFS= read -r f; do
     [ -n "$f" ] || continue
     HEAD10=$(head -10 "$f" 2>/dev/null || true)
@@ -121,20 +186,20 @@ esac
 # 避免 template update 一裝新 hook，老 repo 所有 code 寫入立刻全紅。
 if [ "$FM_COUNT" -eq 0 ]; then
   SDD_COUNT=0
-  if [ -d "$SPECS_DIR" ]; then
+  if [ -n "$SPECS_DIR" ] && [ -d "$SPECS_DIR" ]; then
     SDD_COUNT=$(find "$SPECS_DIR" -name 'design.md' -not -path '*TEMPLATE*' -not -path '*/archive/*' 2>/dev/null | wc -l | tr -d ' ')
   fi
 
   if [ "$SDD_COUNT" -eq 0 ]; then
     cat >&2 <<EOF
-🚫 SDD 協議攔截：要動 code 檔 ($FILE_PATH)，但 ${SPECS_DIR}/ 下找不到任何 SDD。
+🚫 SDD 協議攔截：要動 code 檔 ($FILE_PATH)，但 ${SPECS_NOT_FOUND_MSG}。
 
 絕對鐵律：任何 code 變動前必須有對應 SDD（design.md），且遵守單一活性生命週期
 （system-dev/docs/3-specs/SDD-LIFECYCLE.md）。
 
 請先：
   1. 確認這個改動屬於哪個子系統
-  2. 在 ${SPECS_DIR}/[子系統]/ 建立 design.md（可用 /sdd-check 協助），frontmatter 標 status: active
+  2. 在 [子系統的] system-dev/docs/3-specs/[子系統]/ 建立 design.md（可用 /sdd-check 協助），frontmatter 標 status: active
   3. 在回覆開頭宣告已讀 SDD + 對應 task
 
 小修改（修 bug、改文字）若確定豁免，請明確說明範圍後由人放行。
@@ -143,14 +208,14 @@ EOF
   fi
 
   # 舊行為放行 + 提醒遷移（stderr 警告，不擋）
-  echo "📋 提醒：${SPECS_DIR}/ 有 SDD 但尚未掛生命週期 frontmatter（老結構）。動手前確認已讀對應 design.md；建議依 SDD-LIFECYCLE.md 補 status 標記（現行那份標 active）。" >&2
+  echo "📋 提醒：${SPECS_DIR_DESC} 有 SDD 但尚未掛生命週期 frontmatter（老結構）。動手前確認已讀對應 design.md；建議依 SDD-LIFECYCLE.md 補 status 標記（現行那份標 active）。" >&2
   exit 0
 fi
 
 # ── 新行為：寫 code 檔需「恰好 1 份」active SDD ──
 if [ "$ACTIVE_COUNT" -eq 0 ]; then
   cat >&2 <<EOF
-🚫 SDD 協議攔截：要動 code 檔 ($FILE_PATH)，但 ${SPECS_DIR}/ 下沒有任何 status: active 的 SDD。
+🚫 SDD 協議攔截：要動 code 檔 ($FILE_PATH)，但 ${SPECS_NOT_ACTIVE_MSG}。
 
 單一活性鐵律：所有開發任務唯一對應源＝那份 active SDD（規則見 system-dev/docs/3-specs/SDD-LIFECYCLE.md）。
 

hooks/tests/sdd-guard.test.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# sdd-guard.sh 的迴歸測試（inkstone/InkStoneCo#22）。
+#
+# 涵蓋兩個洞：
+#   洞 A — scratchpad／任何不在 git repo 裡的暫存檔被誤判成「code 變動」而擋下。
+#   洞 B — 真的解析失敗（fail-closed）時，訊息裡印出內部 sentinel `/nonexistent`。
+# 以及既有行為不能退步：單一活性違反仍擋、恰好 1 份 active 仍放行、
+# 「dirname 還沒建立」不可被誤判成「不在 repo 裡」（新邏輯自己可能引入的 fail-open 陷阱）。
+#
+# 用法：hooks/tests/sdd-guard.test.sh [hooks/sdd-guard.sh 的路徑]
+# 🔴 全程在一個乾淨的 TMP 底下建假 repo，跑完自己清；不動任何真 repo。
+
+set -u
+HOOK="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/sdd-guard.sh}"
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+
+PASS=0; FAIL=0
+
+mk() { # mk <file_path> -> JSON on stdout
+  python3 -c "import json,sys;print(json.dumps({'tool_name':'Write','tool_input':{'file_path':sys.argv[1],'content':'x'}}))" "$1"
+}
+
+t() { # t <期望 exit code> <說明> <file_path> [額外檢查關鍵字]
+  local want="$1" desc="$2" path="$3" must_not_contain="${4:-}"
+  local out rc
+  out=$(mk "$path" | "$HOOK" 2>&1)
+  rc=$?
+  local ok=1
+  [ "$rc" -eq "$want" ] || ok=0
+  if [ -n "$must_not_contain" ] && printf '%s' "$out" | grep -qF "$must_not_contain"; then
+    ok=0
+  fi
+  if [ "$ok" -eq 1 ]; then
+    echo "  ✅ $desc"; PASS=$((PASS+1))
+  else
+    echo "  ❌ $desc —— 期望 exit=$want，實得 exit=$rc"
+    [ -n "$must_not_contain" ] && echo "     （且訊息不該含「$must_not_contain」）"
+    echo "     輸出：$out" | head -3
+    FAIL=$((FAIL+1))
+  fi
+}
+
+# ── 準備：一個真的沒有 3-specs 的 git repo（模擬「真的解析失敗」）──
+REPO_NO_SDD="$TMP/repo-no-sdd"
+mkdir -p "$REPO_NO_SDD/src"
+git init -q "$REPO_NO_SDD"
+
+# ── 準備：一個有 1 份 active SDD 的 git repo ──
+REPO_ONE_ACTIVE="$TMP/repo-one-active"
+mkdir -p "$REPO_ONE_ACTIVE/system-dev/docs/3-specs/x" "$REPO_ONE_ACTIVE/src"
+git init -q "$REPO_ONE_ACTIVE"
+printf -- '---\nstatus: active\n---\n# X\n' > "$REPO_ONE_ACTIVE/system-dev/docs/3-specs/x/design.md"
+
+# ── 準備：一個有 2 份 active SDD 的 git repo（單一活性違反）──
+REPO_MULTI="$TMP/repo-multi-active"
+mkdir -p "$REPO_MULTI/system-dev/docs/3-specs/a" "$REPO_MULTI/system-dev/docs/3-specs/b" "$REPO_MULTI/src"
+git init -q "$REPO_MULTI"
+printf -- '---\nstatus: active\n---\n# A\n' > "$REPO_MULTI/system-dev/docs/3-specs/a/design.md"
+printf -- '---\nstatus: active\n---\n# B\n' > "$REPO_MULTI/system-dev/docs/3-specs/b/design.md"
+
+# ── 準備：scratchpad 風格的暫存區（不在任何 git repo 裡）──
+SCRATCH="$TMP/private/tmp/claude-fake-session/scratchpad"
+mkdir -p "$SCRATCH"
+
+# 讓 $_root（CLAUDE_PROJECT_DIR 或 pwd）刻意跟這些假 repo 對不上，
+# 逼所有案例都走「專案外的路徑」那個分支——這正是 #22 實撞的情境（cwd 跑歪／
+# CLAUDE_PROJECT_DIR 沒設，路徑不落在 $_root 底下）。
+unset CLAUDE_PROJECT_DIR
+cd "$TMP"
+
+echo "── 洞 A：不在任何 git repo 裡的路徑，SDD 管不到，該放行 ──"
+t 0 "scratchpad 暫存 .py（本票原始事故）" "$SCRATCH/fix-project-settings.py"
+t 0 "scratchpad 巢狀更深" "$SCRATCH/nested/deep/tmp.js"
+
+echo "── 洞 B：真的解析失敗（repo 存在但沒有 3-specs）仍要 fail-closed，但訊息不准洩漏內部假路徑 ──"
+t 2 "真 repo 沒有 3-specs → 仍擋" "$REPO_NO_SDD/src/foo.py"
+t 2 "上面那筆的訊息不准出現 /nonexistent" "$REPO_NO_SDD/src/foo.py" "/nonexistent"
+
+echo "── fail-open 陷阱：新檔案要建在還沒建立的子目錄下，不可被誤判成「不在 repo 裡」──"
+t 2 "真 repo、目標子目錄還沒建立 → 仍擋（不能因為 dirname 不存在就放行）" "$REPO_NO_SDD/brand-new/not-yet/bar.py"
+
+echo "── 既有行為不能退步 ──"
+t 0 "只有 1 份 active SDD，改 code 檔 → 放行" "$REPO_ONE_ACTIVE/src/x.py"
+t 2 "2 份 active SDD（單一活性違反）→ 擋" "$REPO_MULTI/src/x.py"
+t 0 "改 .md 文件（非 code 檔）→ 放行，即使找不到 3-specs" "$REPO_NO_SDD/README.md"
+
+echo
+echo "結果：通過 $PASS ／ 失敗 $FAIL"
+[ "$FAIL" -eq 0 ] || exit 1

pending-main-push/unnamed--ISEP.md

@@ -0,0 +1,26 @@
+# 推 main 的請求：未署名
+
+- repo：/Users/youlinhsieh/Documents/tech_projects/ISEP
+- 分支：main
+- 時間：2026-08-20 20:59:30
+
+- 它想跑的指令：
+```
+git push gitea HEAD:main
+```
+
+## 還沒推上去的 commit（原始資料，不是轉述）
+
+```
+```
+
+## 改了哪些檔
+
+```
+ docs/TESTING.md           | 14 +---------
+ scripts/make-cloud-env.sh | 69 -----------------------------------------------
+ 2 files changed, 1 insertion(+), 82 deletions(-)
+```
+
+---
+總管裁完請刪掉這個檔——留著代表「還沒裁」。

scripts/make-cloud-env.sh

@@ -37,8 +37,12 @@ lookup() {  # $1=變數名 → 印出值（找不到就空）
   return 1
 }
 
-OUT_DIR="$HOME/.claude/cloud-env"
+# 預設丟 ~/.claude/cloud-env（權限 700）。要放別的地方＝ OUT_DIR=~/Desktop bash scripts/make-cloud-env.sh
-mkdir -p "$OUT_DIR"; chmod 700 "$OUT_DIR"
+OUT_DIR="${OUT_DIR:-$HOME/.claude/cloud-env}"
+mkdir -p "$OUT_DIR"
+# 只在「這個目錄是我們自己造的預設位置」時才收緊權限——
+# OUT_DIR 可被覆寫，不該對使用者指定的既有目錄（例如 ~/Desktop）動權限。
+[ "$OUT_DIR" = "$HOME/.claude/cloud-env" ] && chmod 700 "$OUT_DIR"
 OUT="$OUT_DIR/$(date +%Y%m%d-%H%M%S).txt"
 
 SETUP="$(cd "$(dirname "$0")/.." && pwd)/docs/cloud-setup-script.sh"

system-dev/docs/2-architecture/decisions/ADR-0001-isep-自建wiki.md

@@ -1,21 +1,40 @@
-# ADR-0001：ISEP 自建 wiki，不繼承 InkStoneCo 的內容
+# ADR-0001：ISEP 這個 repo 自己維護一份 wiki（記 ISEP 自己的事，跟「裝 plugin」無關）
 
-- **狀態**：已採納
+- **狀態**：已採納（決策未變，本次僅修訂標題與內文的誤導處，見文末「常見誤解」）
 - **日期**：2026-08-20
-- **票**：`inkstone/ISEP#3`
+- **票**：`inkstone/ISEP#3`（原案）、`inkstone/InkStoneCo#22`（本次修訂）
+
+## 先講結論，避免讀到一半就會錯意
+
+本 ADR 談的「wiki」，是 **`inkstone/ISEP` 這個 git repo 自己的開發歷史**——
+跟其他任何 repo（`InkStoneCo`、`arcrun`…）在自己 repo 底下放一份
+`system-dev/wiki/` 記自己的事，是同一種、完全獨立的東西。
+
+🔴 **這件事不會發生**：把 ISEP 這個 Claude Code plugin「裝」到別的 repo（本機或雲端的
+Claude Code session 啟用這個 plugin），**不會在那個 repo 裡多寫出任何檔案**，
+更不會在那裡生出一份 `system-dev/wiki/`。「plugin 裝到哪、wiki 就跟著長在哪，
+所以每個 repo 都會有兩份」是誤讀——見文末「常見誤解」段的查證。
 
 ## 背景
 
-ISEP 是獨立 repo，裝的是「環境」（hooks／commands／skills／scripts），本來刻意不放
+ISEP 是獨立 repo，對外扮演的角色是「環境」（hooks／commands／skills／scripts，
-「知識」（wiki／docs／`_archive`）——見 `README.md`「裝什麼」段。但接手 ISEP 的 session
+`README.md`「裝什麼」段列了清單，白紙黑字排除 `wiki/`／`docs/`／`_archive/`——
-（含雲端）若要查「這裡的決定、踩過的坑、現在什麼狀態」，過去只能回頭 clone InkStoneCo
+那些是「知識」不是「環境」）。但 ISEP**自己也是一個在持續開發的 repo**：它有自己的
-頂層知識庫，多一層跳轉、且 ISEP 自己的事並不天然屬於 InkStoneCo 頂層（那裡管的是跨專案決策）。
+決策（例如這份 ADR 本身）、踩過的坑、現在的狀態。過去要查「ISEP 這裡為什麼這樣設計、
+之前討論到哪」，只能回頭 clone InkStoneCo 頂層知識庫，多一層跳轉，而且 ISEP 自己的
+開發細節並不天然屬於 InkStoneCo 頂層（那裡管的是跨專案決策，不是單一 repo 的施工細節）。
 
 ## 決策
 
-ISEP 建立自己的 `system-dev/wiki/`，骨架取自 `inkstone/system-dev-template` 的 wiki
+**`inkstone/ISEP` 這個 repo 自己**建立 `system-dev/wiki/`，骨架取自
-template（三層 + 標籤橫切：`INDEX.md`／`TAXONOMY.md`／`status.md`／`mistakes.md`／
+`inkstone/system-dev-template` 的 wiki template（三層 + 標籤橫切：`INDEX.md`／
-`principles.md`／`cards/<bucket>/`），照它的規約裝，不自創格式。
+`TAXONOMY.md`／`status.md`／`mistakes.md`／`principles.md`／`cards/<bucket>/`），
+照它的規約裝，不自創格式。
+
+這份 wiki 只在 ISEP 這個 repo 的 git 歷史裡，跟著 `git clone inkstone/ISEP` 走；
+它**不是** plugin payload 的一部分（`plugin.json`／`marketplace.json` 只宣告
+`hooks/`／`commands/`／`skills/`，任何 Claude Code session 啟用這個 plugin 時載入的
+也只有這些），所以其他 repo 啟用 ISEP plugin 時，這份 wiki 不會、也無法出現在那裡。
 
 **紅線**：這份 wiki 只記 ISEP 自己的事。不把 InkStoneCo 頂層 wiki 的內容複製過來——
 複製即 fork，fork 即漂移，跟「真身薄殼合一」（見 `cards/isep/真身薄殼合一.md`）要解的病
@@ -23,12 +42,47 @@ template（三層 + 標籤橫切：`INDEX.md`／`TAXONOMY.md`／`status.md`／`m
 
 ## 後果
 
-- 好處：接手 session 在 ISEP 內就能查到 ISEP 自己的歷史，不必先 clone 別的 repo。
+- 好處：接手 ISEP 這個 repo 的 session，在它自己的 checkout 裡就查得到它自己的歷史，
-- 代價：多一份骨架要維護（跟 InkStoneCo 頂層、以及其他裝了 template 的子 repo 一樣）。
+  不必先 clone 別的 repo。
+- 代價：多一份骨架要維護（跟 InkStoneCo 頂層、以及其他裝了 template 的子 repo 一樣，
+  各自一份、各自維護，不互相複製）。
 - 邊界：跨專案的決策、鐵律、部署架構全局，仍然只在 InkStoneCo 頂層記錄，ISEP 不重複。
 
+## 常見誤解，與查證
+
+**誤解**：「ISEP 這個 plugin 裝到哪個 repo，就會在那個 repo 裡自建一份 wiki，
+於是每個裝了 ISEP 的 repo 都會多出兩份（自己的 + ISEP 幫它建的）。」
+
+**這不是實際行為。查證如下（2026-08-20 實查，不是抄口述）**：
+
+1. `.claude-plugin/marketplace.json` 把整個 repo 根目錄（`"source": "./"`）宣告成
+   plugin 來源，Claude Code 依慣例目錄（`hooks/`、`commands/`、`skills/`）載入內容；
+   `README.md`「裝什麼」表列出的也正是這幾個目錄（外加 `scripts/` 供它們呼叫）——
+   **沒有任何一項是 wiki 或 docs**。啟用這個 plugin，載入的是 hook 腳本的路徑
+   （`${CLAUDE_PLUGIN_ROOT}/hooks/*.sh`）、command／skill 的定義；這個載入過程本身
+   不涉及「往目前工作的 repo 寫入任何檔案」——它是讀，不是寫。
+2. `README.md`「裝什麼」段明文把 `wiki/`／`docs/`／`_archive/` 列在「不放」——
+   這條界線本來就是刻意畫的（環境 vs 知識分離），不是本 ADR 才立的。
+3. 全部 hooks 對「自己這支腳本」的路徑一律用 `${CLAUDE_PLUGIN_ROOT}`（不用
+   `$CLAUDE_PROJECT_DIR`，見 `README.md`「路徑規約」段）——這條規約本身就代表
+   hook 的邏輯設計上就是「讀 plugin 自己的檔案」，不是「往目前工作的 repo 寫東西」。
+4. **唯一一支「真的會在某個 repo 裡建出 wiki」的腳本是 `scripts/install.sh`**——
+   但它是 `system-dev-template` 的獨立安裝器（不是 ISEP 的功能），要**人或 AI 手動執行
+   一次**才會動作，且動作對象是**執行當下的 cwd**，不是「ISEP 被啟用的地方」。
+   它會混進這個 repo，是搬家時帶過來的殘留（`docs/governance/DIVERGENCE-v0.5.0-to-v0.6.0.md`
+   A6 節已標記它是待清理項，跟 `.claude-plugin` 宣告的 plugin 功能無關）。
+   **這支腳本的存在，多半就是本誤解真正的來源**——它看起來像「ISEP 會建 wiki」，
+   但觸發方式（手動跑一次）與作用對象（cwd，不是「plugin 裝到的地方」）都跟
+   「裝 plugin 就自動建」完全不同。
+
+⇒ 結論：本 ADR 的「wiki」只指 ISEP 這個 repo 自己 checkout 裡的那一份，
+跟其他任何 repo 有沒有、要不要各自裝一份 wiki（那是它們自己的 `/wiki-init` 決定），
+兩件事互不影響、也不會因為裝了 ISEP plugin 而自動被牽動。
+
 ## 相關
 
 - `cards/isep/真身薄殼合一.md`
 - `cards/isep/repo邊界與紅線.md`
 - `cards/isep/hook路徑規約.md`
+- `inkstone/InkStoneCo#22`（本次修訂的來由：leo 讀完舊版誤解成「plugin 裝到哪、
+  wiki 就跟著建到哪」）