docs(guidelines): 改寫 hook 準則裡五支 CLI 的接線事實

What：
- 改寫「Hook 規則」第 3 條，寫明五支 CLI 的 hook 負載形態各不相同，沒有哪一支是基準格式。
- 新增「技能名解析與阻擋輸出的共用腳本」節，列出 skill-name.sh 與 deny.sh 的用法、各 CLI 的技能名取值來源、抽成共用腳本的理由。
- 改寫「版本前置檢查」，補上五支 CLI 的接線位置表、逐支陷阱表、未實測部分的標明規則。
- 改寫「部署後重啟閘門」，指名 restart-gate.sh，並寫明接線位置與版本前置檢查完全相同。
- 審核檢查清單新增一項：該 domain 的 lint-frontmatter.sh 要退出 0，退出 3 不算通過。

Why：
- 這一節以前寫著「只有 claude 接得上，其餘四支沒有 pre-tool hook」。那是錯的。四支全都有能阻擋的 pre-tool 事件，是我們接錯位置。
- 四個無聲失效逐一坐實了這件事：codex 的 matcher 用 Skill，但 Codex 沒有 Skill 工具，技能是模型用 Bash 讀 SKILL.md；codex 的 hooks 鍵寫成內嵌物件，實際規格是路徑字串；antigravity 的 PreToolUse 寫成 Flat，實際要 matcher 加 hooks 包一層的 Grouped；三支新接的命令沒帶 JSC_CLI={代號}，閘門認不出自己跑在哪支 CLI 上，一次都擋不下來。
- 錯誤的結論被寫進準則之後就沒有人再去查。版本前置檢查與部署後重啟閘門因此在四支 CLI 上長期失效，而且失效是安靜的：hook 沒被觸發不會報錯，看起來就跟「沒有東西該擋」一樣。

How：
- 接線位置表每一列都經過執行檔抽出或本機實測，事件名、matcher、寫入檔案、阻擋方式逐欄寫死。
- verdict 據實分級：claude、codex、copilot、antigravity 寫 wired；kiro 的技能叫用走 ResolveSkill 內部請求、不走工具管線，攔不到，寫 degraded，不寫 failed。
- antigravity 與 kiro 的觸發沒有實跑驗證，另段標明，回報時不得混進已驗證的結論。
- 兩道閘門共用同一套接線，就共用同一份事實表。重啟閘門那節只指回接線位置表，不另寫一份能力描述，避免改一份、漏一份。

Who：
屬 CLI hook 接線修正（jsc-hooks 0.3.4）在 meta 這一側的規範文件。

references/guidelines.md

@@ -59,8 +59,28 @@ PR 開立、更新、留言修正的收尾回報格式只看 [`references/pr-rep
 1. 所有 hook 專屬存放於 `jsc-hooks`，**不可散落在其他 domain**。
 2. Hook 腳本實作優先順序：**shell > nodejs > python**。
 3. Hook 必須適用於 claude / codex / copilot / antigravity / kiro 五種 CLI：
-   - 腳本同時支援 stdin JSON（Claude 格式）與環境變數輸入，缺欄位時安靜降級（exit 0）。
-   - 各 CLI 的接線方式由 `jsc-hooks:hooks-install` 技能處理。
+   - 五支 CLI 的 hook 負載形態各不相同，沒有哪一支是基準格式。腳本吃 stdin JSON，也吃環境變數，缺欄位時安靜降級（exit 0）。
+   - 各 CLI 的接線位置、事件名與 matcher 由 `jsc-hooks:hooks-install` 技能處理，接線位置表見「版本前置檢查」。
+   - 負載解析與阻擋輸出不各寫一份，一律走下面兩支共用腳本。
+
+### 技能名解析與阻擋輸出的共用腳本
+
+| 腳本 | 用法 | 做什麼 |
+| --- | --- | --- |
+| `jsc-hooks/hooks/skill-name.sh` | `skill-name.sh {claude\|codex\|copilot\|antigravity\|kiro}` | 從 stdin 讀該 CLI 的 hook 負載，印出一行 `{domain}<TAB>{技能名}`。解析不出就印空字串並退出 0，由呼叫端安靜放行 |
+| `jsc-hooks/hooks/deny.sh` | `deny.sh {cli}`，訊息從參數或 stdin 進 | 依該 CLI 的阻擋形態輸出：claude、codex、copilot 走結束碼 2 加 stderr；antigravity 走 stdout `{"decision":"deny","reason":"..."}`，**不可靠結束碼**；kiro 擋不了，改印警告到 stdout 供注入並退出 0 |
+
+各 CLI 的技能名取值來源：
+
+| CLI | 取自 |
+| --- | --- |
+| claude | stdin JSON 的 `skill` 欄位，或環境變數 `JSC_SKILL` |
+| codex | `tool_input.command` 裡的 `SKILL.md` 路徑 |
+| copilot | `toolArgs` 裡的技能名。`toolArgs` 是字串化的 JSON，**要剝兩層** |
+| antigravity | `toolCall.args.AbsolutePath`。args 鍵名是 PascalCase |
+| kiro | `prompt` 開頭的 `/{技能名}` |
+
+**為什麼要抽出來。** 三種負載形態（工具名、指令字串、檔案路徑）指向同一件事：從負載取出 domain 與技能名。同一套規則寫進兩支 hook 就會漂移——改了 `version-guard.sh`、忘了 `restart-gate.sh`，其中一道閘門就在某支 CLI 上安靜失效，而且失效不會報錯，跟 2026-08-31 抓到的接線缺陷是同一種病。抽成一支之後只有一份真實來源，CLI 換了負載形態也只改一個地方。阻擋輸出同理：五支 CLI 四種形態，寫散了就會有人拿 claude 的結束碼去擋 antigravity，而 antigravity 的結束碼語意兩邊文件都沒寫，擋不擋得住純靠運氣。
 
 ## 技能設計
 
@@ -137,9 +157,36 @@ PR 開立、更新、留言修正的收尾回報格式只看 [`references/pr-rep
 
 ## 版本前置檢查
 
-技能組的每一支技能在被呼叫前都要過兩道版本檢查：本機載入版本沒有落後遠端發佈版本，以及這支技能所屬 plugin 宣告的 `jsc.requires` 每一項都吃得到。兩道判定都在程式層，由 `jsc-hooks` 的 `version-guard.sh`（PreToolUse，matcher `Skill`）執行，**不靠技能內文自我約束**——寫在內文的規則，模型可以無視。
+技能組的每一支技能在被呼叫前都要過兩道版本檢查：本機載入版本沒有落後遠端發佈版本，以及這支技能所屬 plugin 宣告的 `jsc.requires` 每一項都吃得到。兩道判定都在程式層，由 `jsc-hooks` 的 `version-guard.sh` 執行，**不靠技能內文自我約束**——寫在內文的規則，模型可以無視。
 
-兩道都只擋「確定落後」一種情況。查不到任何一項基礎資訊就安靜放行（exit 0），不要求先修好環境：五支 CLI 只有 claude 讀得到本機載入版本，fail-closed 會把另外四支整批鎖死。
+兩道都只擋「確定落後」一種情況。查不到任何一項基礎資訊就安靜放行（exit 0），不要求先修好環境：只有 claude 讀得到 `installed_plugins.json` 那份本機載入版本，fail-closed 會把另外四支整批鎖死。這是**版本讀得到讀不到**的限制，跟能不能阻擋是兩件事，不要混談。
+
+### 五支 CLI 的接線位置
+
+**五支裡有四支都有能阻擋的 pre-tool 事件，kiro 是唯一例外。** 以下每一列都經過執行檔抽出或本機實測。
+
+| CLI | 事件與 matcher | 接線寫到哪 | 阻擋方式 | verdict |
+| --- | --- | --- | --- | --- |
+| claude | `PreToolUse`，matcher `Skill` | `jsc-hooks/hooks/hooks.json` | 結束碼 2 加 stderr | wired |
+| codex | `PreToolUse`，matcher 對 `tool_name` 做正規表示式比對，用 `Bash` 與 `Write\|Edit\|MultiEdit` | `.codex-plugin/plugin.json` 的 `hooks` 鍵 | 結束碼 2 加 stderr，或 stdout 回 `permissionDecision: deny` | wired |
+| copilot | `PreToolUse`，matcher `skill`（小寫） | `$COPILOT_HOME/hooks/jsc-hooks.json` | stdout 回 `{"permissionDecision":"deny","permissionDecisionReason":"..."}`，或結束碼 2 | wired |
+| antigravity | `PreToolUse` 加 `PreInvocation`，matcher `^view_file$` | `~/.gemini/config/hooks.json` 的 jsc 標記段落 | stdout 回 `{"decision":"deny","reason":"..."}` | wired |
+| kiro | `userPromptSubmit`（hook 宣告在 agent 設定檔的 `hooks` 鍵） | `~/.kiro/agents/jsc.json`，並設 `chat.defaultAgent=jsc` | **擋不了**。只能把警告印到 stdout 供注入，退出 0 | degraded |
+
+每一支的陷阱，接線與改動時逐條核對：
+
+| CLI | 陷阱 |
+| --- | --- |
+| codex | Codex **沒有 `Skill` 工具**。技能是模型自己用 `Bash` 讀 `SKILL.md` 載進來的，matcher 寫 `Skill` 等於沒接。非受管 hook 要先審核，內容一改就重新標記待審 |
+| copilot | command hook 是 **fail-closed**：崩潰或任何非零結束碼都算拒絕，但**逾時 fail-open**。所以那支腳本的每一條非預期路徑都要明確 `exit 0`。事件名 PascalCase 與 camelCase 都吃，兩種同時存在會**跑兩次** |
+| antigravity | **沒有專用的技能工具**，系統提示要求模型用 `view_file` 讀 `SKILL.md`。matcher 的錨點一定要寫，`view_file` 不加錨點會誤中 `view_file_outline`。**結束碼語意兩邊文件都沒寫，絕對不可靠 exit code**。斜線指令與預載技能直接把 `SKILL.md` 全文注入訊息，不產生工具呼叫，那條路徑擋不住 |
+| kiro | 技能**不走工具管線**，是 `ResolveSkill` 這個 agent 內部請求、由前端發起，所以 `preToolUse` 攔不到技能叫用；`userPromptSubmit` 的非零結束碼也不會擋下那一輪。合法 trigger 只有 `agentSpawn`、`userPromptSubmit`、`preToolUse`、`postToolUse`、`stop`，`sessionStart` 與 `sessionEnd` 不是合法事件。hook 只認 agent 設定檔的 `hooks` 鍵，`.kiro/hooks/` 不被讀 |
+
+**未實測的部分要據實標明。** antigravity 與 kiro 的 hook 觸發都沒有實跑驗證——前者對話 quota 用盡、後者未登入。這兩支的接線位置與欄位結構是從執行檔抽出來的事實，但「hook 真的被觸發」還沒看到。回報時不得把這兩支混進「已驗證」的結論。
+
+**為什麼要留這段。** 這一節以前寫著「只有 claude 接得上，其餘四支沒有 pre-tool hook」，那是錯的。四支全都有能阻擋的 pre-tool 事件，是我們接錯位置：codex 用了它根本沒有的 `Skill` matcher，copilot 與 antigravity 完全沒接，kiro 連接線位置、事件名、欄位結構三者都錯。錯誤的結論被寫進準則之後，就沒有人再去查——版本前置檢查與部署後重啟閘門因此在四支 CLI 上長期失效，而失效是安靜的：hook 沒被觸發不會報錯，閘門沒擋下來看起來就跟「沒有東西該擋」一樣。**一道護欄回報「這裡沒有能力」時，要先確認那是查證過的事實，不是沒查。**
+
+kiro 是唯一真的擋不了的，verdict 據實寫 `degraded`，不寫 `wired` 也不寫 `failed`：那是 CLI 的限制，不是我們接錯。
 
 | 項目 | 規則 |
 | --- | --- |
@@ -171,7 +218,7 @@ PR 開立、更新、留言修正的收尾回報格式只看 [`references/pr-rep
 
 相依版本檢查移到這裡，是因為 `deploy.sh update` 原本會跳過不符的 domain，跳過就永遠更新不到，理由見「Manifest 相依版本」第 5 條。更新照跑、呼叫才擋，落後的 domain 才有路徑補上來。
 
-沒有 pre-tool hook 的 CLI 接不上這道檢查，`hooks-install` 要據實回報，不得暗示每個 CLI 都有保護。
+`hooks-install` 要據實回報每一支的 verdict：claude、codex、copilot、antigravity 是 `wired`，kiro 是 `degraded`。不得暗示每個 CLI 都擋得住，也不得反過來暗示只有 claude 有保護。
 
 ## 部署後重啟閘門
 
@@ -181,11 +228,14 @@ PR 開立、更新、留言修正的收尾回報格式只看 [`references/pr-rep
 | --- | --- |
 | 狀態檔 | `$JSC_HOME/restart-required.d/{cli}`，**一支 CLI 一份**，由 `jsc-cli:deploy` 收尾寫入 |
 | 清除時機 | 重啟 CLI 之後由 `jsc-hooks` 清除**自己那一份**，不必手動刪 |
-| 該 CLI 那份存在時 | 擋下這支 CLI 的 jsc 技能呼叫，印出要重啟哪一支與狀態檔路徑 |
+| 該 CLI 那份存在時 | 擋下這支 CLI 的 jsc 技能呼叫，印出要重啟哪一支與狀態檔路徑。kiro 擋不了，改注入警告 |
 | 該 CLI 那份不存在時 | 放行。別支 CLI 的狀態檔不影響這一支 |
-| 判定位置 | 程式層，由 `jsc-hooks` 執行，不靠技能內文自我約束 |
+| 判定位置 | 程式層，由 `jsc-hooks/hooks/restart-gate.sh` 執行，不靠技能內文自我約束 |
+| 接線位置 | 與版本前置檢查完全相同，逐支見「版本前置檢查」的接線位置表 |
 | 逃生門 | `JSC_RESTART_GATE=off` |
 
+**這道閘門在五支 CLI 上的能力，跟版本前置檢查一模一樣。** claude、codex、copilot、antigravity 都有能阻擋的 pre-tool 事件，接上去就真的擋得住，verdict 是 `wired`；kiro 的技能叫用不走工具管線，攔不到，只能在 `userPromptSubmit` 注入警告，verdict 是 `degraded`。這一節以前跟著「只有 claude 有 pre-tool hook」那個錯誤結論走，所以重啟閘門也在四支 CLI 上長期失效：部署完照樣跑舊版技能，沒有任何東西擋，也沒有任何東西報錯。**兩道閘門共用同一套接線，就共用同一份事實表**，不要在這一節另寫一份能力描述——寫兩份就會只改一份，另一份繼續錯著。
+
 **豁免清單**（狀態檔存在也放行）：
 
 | 技能 | 為什麼不能擋 |
@@ -270,6 +320,7 @@ PR 開立、更新、留言修正的收尾回報格式只看 [`references/pr-rep
 - [ ] SKILL.md 整份為英文（要原樣輸出的繁中字面除外）；README、AGENTS、templates、references 為 STE100 繁中；UTF-8 無亂碼
 - [ ] 所有非程式碼輸出（程式碼註解、commit 訊息、PR 描述、wiki 頁、回報、文件）為繁體中文、UTF-8、無亂碼、無簡體字，且 `tools/ste100-lint.sh` 對該 domain 全綠
 - [ ] 該 domain 的 `references/behaviors.md` 與 `skills/` 相符，`tools/check-behaviors.sh {domain-path}` 對該 domain 退出 0；退出 3 是「什麼都沒查」，不算通過
+- [ ] 該 domain 每支 `skills/*/SKILL.md` 的 frontmatter 解析得動，`tools/lint-frontmatter.sh {domain-path}` 對該 domain 退出 0；退出 3 是「什麼都沒掃」，不算通過。frontmatter 有語法錯誤時，Antigravity 會**靜默丟棄整支技能**，沒有任何錯誤訊息，只有這支腳本抓得到
 - [ ] 已同步更新該 domain 的 README「Skills 目錄」與三份 manifest 的 version
 - [ ] PR 的 base 符合「PR 分支階梯」，沒有越級