v0.3.1

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.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 的輸出貼回來
-- 版本比 Releases 舊 ⇒ 環境快取住了（設定跑完會被拍成快照，約 7 天或改了 setup script 才重拍）
-  → 動一下 setup script 的內容，強制重拍
+- **沒有這行** ⇒ plugin 沒載入，這個 session 是**零閘狀態**。先修 plugin，不要開始做事。
+- 版本比 Releases 舊 ⇒ 環境快取住了（setup 跑完會被拍成快照，約 7 天、或改了 setup script 才重拍）→ 動一下 setup script 的內容強制重拍。
 
-### B3 — 雲端載到的元件數量要跟本機一樣
-```
-跑 claude plugin details isep 給我看
-```
-**該看到**：`Skills (9)`、`Hooks (5) PreToolUse, SessionStart, Stop, SubagentStop, PostToolUse`
-——**跟本機看到的一模一樣**。
-**失敗**：比本機少 ⇒ 又回到「兩邊不一樣」，正是 `InkStoneCo#57` 那張票的病。
+🔴 **為什麼是這一行，而不是叫它跑指令**：這行由 `isep-presence-beacon.sh` 發出，
+而那支腳本**住在 plugin 裡**。plugin 沒載入 ⇒ 它不可能發聲。
+**沒有「剛好也會過」的情況**——這就是鑑別力。
+
+### B3 — 要它把 setup 的驗證結果貼回來
 
-### 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-setup-script.sh

@@ -27,12 +27,46 @@ if [ -z "${GITEA_TOKEN_CLAUDE_CODE:-}" ]; then
   exit 1
 fi
 
-# 官方文件建議的私有 marketplace 認證寫法：只重寫這個 host 的 URL，不動其他 git 操作。
-git config --global url."https://x-access-token:${GITEA_TOKEN_CLAUDE_CODE}@git.uncle6.me/".insteadOf \
+# ── git 認證：三個機制都設，因為它們失效的方式不同 ────────────────
+#   ① URL 重寫（global）  ② 憑證存檔（global）  ③ 系統層（HOME 無關，best effort）
+# 2026-08-20 雲端實測：session 裡 git 是「匿名」的 ⇒ setup 設的東西沒生效到 session。
+# 原因未定（沒跑到／HOME 不同／快照沒帶），所以三條都設，並在下面自我驗證。
+git config --global url."https://claude-code:${GITEA_TOKEN_CLAUDE_CODE}@git.uncle6.me/".insteadOf \
   "https://git.uncle6.me/"
+git config --global credential.helper store
+printf 'https://claude-code:%s@git.uncle6.me\n' "$GITEA_TOKEN_CLAUDE_CODE" > "$HOME/.git-credentials"
+chmod 600 "$HOME/.git-credentials"
+git config --system url."https://claude-code:${GITEA_TOKEN_CLAUDE_CODE}@git.uncle6.me/".insteadOf \
+  "https://git.uncle6.me/" 2>/dev/null || echo "（system 層設不了，只靠 global——非致命）"
 
-# 用乾淨網址（不帶 token）加 marketplace，實際認證交給上面那條 URL 重寫。
-claude plugin marketplace add https://git.uncle6.me/inkstone/ISEP.git --scope user
-claude plugin install isep@inkstone --scope user
+# ── 🔴 自我驗證一：認證真的通了嗎 ──────────────────────────
+# 這一步是 2026-08-20 事故的直接產物：舊版設完就結束，token 沒生效也不出聲，
+# 於是雲端 session 開起來才發現 marketplace 拉不下來，而 setup log 一片綠。
+echo "── 驗證 git 認證 ──"
+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
 
-echo "✅ ISEP 已裝成 user-scope plugin，之後每個 session 啟動時直接生效。"
+# ── 安裝（user scope 只是備援）─────────────────────────────
+# 🔴 官方文件（cloud-environments 的 what-carries-over 表）明文：
+#    「Plugins enabled only in your user settings」→ **不會**帶到雲端 session。
+#    真正生效的是薄殼 repo 的 .claude/settings.json 裡的 enabledPlugins ＋ extraKnownMarketplaces。
+#    這兩行留著當本地備援，不是主要路徑——不要以為裝完就等於雲端有了。
+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 真的拉下來了嗎 ────────────────
+echo "── 驗證 marketplace ──"
+if claude plugin marketplace list 2>/dev/null | grep -q "inkstone"; then
+  echo "✅ marketplace inkstone 已就位"
+else
+  echo "❌ marketplace 沒就位——session 啟動時 enabledPlugins 會是一張跳票的支票。" >&2
+  exit 1
+fi
+
+echo "✅ setup 完成。session 啟動後請用「有鑑別力的探針」驗閘，"
+echo "   不要用 git tag（它在三支閘的白名單裡，閘死了也會過）。"

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/subagent-claim-worksheet.sh

@@ -118,24 +118,10 @@ if not ok_hits and not ng_hits:
     print("SKIP:no-claims"); raise SystemExit
 
 sid = (d.get("session_id") or "nosid")[:8]
-
-# 2026-08-20 修：檔名原本 hash (transcript_path + session_id + agent_id)
-#   => 每個新 agent 拿到新檔名，但抽出的宣稱是同一批（取 transcript 最後一個
-#      <result>，那個可能是舊的——檔頭 08-18 註解已記過同源問題）。
-#   實害：同兩條宣稱一天內產了 6 張不同 hash 的單，總管每回合重做一次已驗完的事。
-#   => InkStoneCo#48：「永遠在誤響的警報，等於訓練人忽略這個警報」。
-#   改成 hash 宣稱內容本身，且已驗歸檔的直接跳過。
-claims_sig = "\n".join(sorted(ok_hits + ng_hits))
-stamp = hashlib.sha1(claims_sig.encode()).hexdigest()[:8]
+aid = (d.get("agent_id") or d.get("subagent_id") or "")[:10]
+stamp = hashlib.sha1((tp + sid + aid).encode()).hexdigest()[:8]
 path = os.path.join(os.environ["DIR"], "claims-%s-%s.md" % (sid, stamp))
 
-_vdir = os.path.join(os.path.dirname(os.environ["DIR"]), "verified-claims")
-if os.path.isdir(_vdir):
-    for _f in os.listdir(_vdir):
-        if stamp in _f:
-            print("SKIP:already-verified:%s" % stamp)
-            raise SystemExit
-
 def block(title, items, howto, cap):
     if not items:
         return ""

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(-)
+```
+
+---
+總管裁完請刪掉這個檔——留著代表「還沒裁」。