docs(hooks): 同步文件與參考資料

What：更新 README、AGENTS.md、templates 與 references，讓文件敘述與實際行為一致。

Why：稽核發現多處文件與程式行為分歧，違反「每個意義只有單一真實來源」。

How：以實際程式行為為準改寫敘述，重複的規則收成單一來源並以一行指引指過去。

Who：jsc-meta:skill-check 例行稽核（2026-08-25）。

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

README.md

@@ -23,29 +23,35 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
 | 腳本 | 事件 | 作用 |
 | --- | --- | --- |
 | `hooks/ste100-guard.sh` | UserPromptSubmit | 注入 STE100 繁體中文輸出規則（hook > prompt 強制層） |
-| `hooks/session-timer.sh` | SessionStart / Stop / SessionEnd | 記錄工作階段起訖；`report` 子指令供 `jsc-log:worklog` 取花費時間 |
-| `hooks/version-guard.sh` | PreToolUse(Skill) | 技能使用前的版本前置檢查：本機**實際載入**版本落後遠端發佈版本就以 exit 2 擋下該次呼叫並提示更新指令。只擋落後（超前放行，開發技能組時本機本來就會超前）；遠端查不到一律擋（fail-closed），逃生門 `JSC_VERSION_GUARD=off`。豁免 `jsc-cli:deploy`、`jsc-hooks:hooks-install`、`jsc-cli:models`、`jsc-meta:*` |
+| `hooks/session-timer.sh` | SessionStart / Stop / SessionEnd | 記錄工作階段起訖。子指令：`start` 記起始時間（已有紀錄就不動，給 claude 這種每階段有自己 session id 的 CLI）、`restart` 一律覆寫起始時間（給接不到 session id 的 kiro，不覆寫會把上一階段算進來）、`mark` 更新最後活動時間、`report` 供 `jsc-log:worklog` 取花費時間 |
+| `hooks/version-guard.sh` | PreToolUse(Skill) | 技能使用前的版本前置檢查：本機**實際載入**版本落後遠端發佈版本就以 exit 2 擋下該次呼叫並提示更新指令（更新指令依當前 CLI 給）。只擋落後這一種情況：超前放行（開發技能組時本機本來就會超前），讀不到本機版本、推導不出站台、查不到遠端版本也一律放行。逃生門 `JSC_VERSION_GUARD=off`。豁免 `jsc-cli:deploy`、`jsc-hooks:hooks-install`、`jsc-cli:models`、`jsc-meta:*` |
 | `hooks/skill-usage.sh` | PostToolUse(Skill) | 記錄技能使用與呼叫鏈到 `$JSC_HOME/usage/*.jsonl`，供 `jsc-log:stats` 統計 |
 | `hooks/sdlc-gate.sh` | UserPromptSubmit | SDLC 階段能力標籤閘門與模型鎖：`lock {stage}` 由 jsc-sdlc 階段技能呼叫，從 transcript 讀出實際模型 id 比對該階段必要標籤（`$JSC_HOME/model-tags.tsv`），不符就拒絕上鎖；`check` 在模型不符時以 exit 2 擋下該輪提示（其他 hook 一律 exit 0，此處是刻意例外）；`unlock` 為逃生門 |
 
-Claude 由 `hooks/hooks.json` 自動接線；其他 CLI 用 `hooks-install` 技能接線、改裝包裝啟動器，或降級為規則檔。
+Claude 由 `hooks/hooks.json` 自動接線五支 hook；其他 CLI 用 `hooks-install` 技能接線、改裝包裝啟動器，或降級為規則檔。
+
+> 覆蓋範圍要據實看待：只有 claude 同時有 PreToolUse 與 UserPromptSubmit，五支 hook 全接得上，回報 `wired`。codex、copilot、antigravity、kiro 都沒有 pre-tool hook，接不上 `version-guard.sh` 的版本前置檢查，SDLC 模型鎖也只剩技能步驟檢查，這四個 CLI 一律回報 `degraded`，靠 `/jsc-cli:deploy` 定期更新。codex 另外沒有工作階段開始事件，計時改由 `tools/jsc-wrap.sh` 的 `codex` 別名在啟動當下開始；沒走別名啟動時，時間從第一輪回應算起。
 
 > `version-guard.sh report` 是非 hook 的子指令：印出每個已安裝 jsc plugin 的
 > 「{domain} {本機} {遠端} {落後｜最新｜超前｜查詢失敗}」，最後一行 `behind {落後個數}`。
+> 本機沒有 Claude 的 plugin 註冊檔時改印 `noregistry {路徑}` 再接 `behind 0`，
+> 代表這台機器無法做版本檢查，跟「全部最新」是兩件事。查遠端版本走與 hook 同一份快取
+> 與同一個 `JSC_VERSION_TTL`，一次部署不會為每個 domain 各打一輪網路。
 > `jsc-cli:deploy` 用它決定要不要把「更新」設成推薦選項。
 
 ## 工具
 
 | 腳本 | 用途 |
 | --- | --- |
-| `tools/jsc-wrap.sh` | 無 hook 系統 CLI 的包裝啟動器：匯出 `JSC_CLI`、`JSC_SESSION_ID`，前後接 `session-timer.sh`，結束時自動跑 `scan-logs.sh` 回填 |
+| `tools/jsc-wrap.sh` | 沒有完整 hook 系統的 CLI 的包裝啟動器：匯出 `JSC_CLI`、`JSC_SESSION_ID`，前後接 `session-timer.sh`，結束時自動跑 `scan-logs.sh` 回填。`JSC_CLI` 存 CLI 代號，實際執行的是對應的執行檔（antigravity 是 agy、kiro 是 kiro-cli） |
 | `tools/scan-logs.sh` | 離線回填：解析 copilot、antigravity、codex 的原生日誌，把技能用量與階段界線補進 `$JSC_HOME`，重掃不重複 |
-| `tools/wire-cli.sh` | 單一 CLI 的接線流程：`{cli}` 對應的設定編輯、包裝別名安裝、hook 檔建立，皆以 `<!-- jsc-hooks -->`（或 `# jsc-hooks`）標記整段取代，重跑不重複；以 `status=wired\|degraded\|skipped` 回報結果 |
+| `tools/report-error.sh` | 失敗回報流程：把一筆 hook 或工具異常寫成 wiki 的 `ERROR_{HASH}`，並在 `ERROR_CONTENTS` 附上一列索引。wiki 位置由 `jsc-gitea` 的 `gitea.sh wiki-repo ERROR` 解析，解析不出來就安靜降級。由操作者手動執行，或由 `hooks-install` 在 `wire-cli.sh` 回報 `status=failed` 時執行；**不接在失敗的 hook 上自動觸發**（hook 一律安靜 exit 0，自我回報會疊出迴圈） |
+| `tools/wire-cli.sh` | 單一 CLI 的接線流程：`{cli}` 對應的設定編輯、包裝別名安裝、hook 檔建立，皆以 `<!-- jsc-hooks -->`（或 `# jsc-hooks`）標記整段取代，重跑不重複。寫完每個檔案會重讀驗證位置正確才回報成功（codex 的 `notify` 必須是根層鍵、kiro 的 JSON 必須成對且 `on`、`run` 在最上層）；以 `status=wired\|degraded\|skipped\|failed` 回報結果 |
 
 ## 失敗回報範本
 
-這兩個模板給外層的 hook 失敗回報流程使用，不改動現有 hook 行為。
-失敗時若要寫入 wiki，套用這兩個檔案即可。
+這兩個模板是失敗回報頁的文案來源，由 `tools/report-error.sh` 填欄位後寫進 wiki。
+用法：`tools/report-error.sh --hook {名稱} --exit {碼} --summary {摘要}`，錯誤輸出摘要走標準輸入。
 
 | 範本 | 用途 |
 | --- | --- |
@@ -60,7 +66,7 @@ Claude 由 `hooks/hooks.json` 自動接線；其他 CLI 用 `hooks-install` 技
 
 ### `hooks-install`
 
-把四支 hook 接線到所有已安裝的 CLI：偵測 CLI 後，逐一呼叫 `tools/wire-cli.sh {cli}` 完成接線（claude 由 `hooks.json` 自動接線，無需寫入）。copilot、antigravity 由該腳本裝上 `tools/jsc-wrap.sh` 包裝別名補上計時與用量回填（結束時自動跑 `tools/scan-logs.sh`），語言規則仍追加到各自的規則檔（以 `<!-- jsc-hooks -->` 標記整段取代，不重複追加）。codex、kiro 的 SDLC 模型鎖降級為技能步驟檢查，鎖檔仍由 SDLC 技能直接呼叫 `sdlc-gate.sh lock` 寫入。腳本以 `status=wired|degraded|skipped` 回報結果，供技能對照 verify 表。
+把五支 hook 接線到所有已安裝的 CLI：偵測 CLI 後，逐一呼叫 `tools/wire-cli.sh {cli}` 完成接線（claude 由 `hooks.json` 自動接線，無需寫入）。codex、copilot、antigravity 由該腳本裝上 `tools/jsc-wrap.sh` 包裝別名補上計時與用量回填（結束時自動跑 `tools/scan-logs.sh`），語言規則仍追加到各自的規則檔（以 `<!-- jsc-hooks -->` 標記整段取代，不重複追加）。codex、copilot、antigravity、kiro 的 SDLC 模型鎖降級為技能步驟檢查，鎖檔仍由 SDLC 技能直接呼叫 `sdlc-gate.sh lock` 寫入；這四個 CLI 沒有 pre-tool hook，版本前置檢查接不上，腳本會在 `reason` 裡講明，只有 claude 回報 `wired`。腳本第一行以 `status=wired|degraded|skipped|failed reason=...` 回報結果；`failed` 由技能改呼叫 `tools/report-error.sh` 寫一頁 `ERROR_{HASH}`。
 
 <!-- JSC-SKILLS:END -->
 
@@ -69,9 +75,11 @@ Claude 由 `hooks/hooks.json` 自動接線；其他 CLI 用 `hooks-install` 技
 | 變數 | 用途 | 未設定時 |
 | --- | --- | --- |
 | `JSC_HOME` | Hook 資料目錄 | 預設 `~/.jsc` |
+| `JSC_WIKI_REPO_ERROR` | `ERROR_CONTENTS`、`ERROR_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` |
+| `JSC_WIKI_REPO` | 未逐類設定時的共用 wiki `{owner}/{repo}` | `tools/report-error.sh` 安靜降級，不寫 wiki |
 | `JSC_VERSION_GUARD` | 設 `off` 完全略過版本前置檢查（離線工作用） | 啟用檢查 |
 | `JSC_VERSION_TTL` | 遠端版本查詢的快取秒數 | 預設 600 |
-| `JSC_CLI` / `JSC_SESSION_ID` / `JSC_SKILL` | 非 Claude CLI 接線時由 `tools/jsc-wrap.sh` 或接線設定提供 | 安靜降級 |
+| `JSC_CLI` / `JSC_SESSION_ID` / `JSC_SKILL` / `JSC_TOOL_NAME` | 非 Claude CLI 接線時由 `tools/jsc-wrap.sh` 或接線設定提供，代替 stdin JSON 的 `session_id`、`skill`、`tool_name`（`version-guard.sh` 也收沒有前綴的 `SKILL`、`TOOL_NAME`） | 安靜降級 |
 | `JSC_MODEL` | 非 Claude CLI 的目前模型，供 `sdlc-gate.sh` 比對；優先序在 transcript 實際值與 stdin `model` 之後 | 改讀 `~/.claude/settings.json`，再不行就安靜降級 |
 
 ## 相關 domain