From 096a85e6389a93e78291cdd932b6709047a59a27 Mon Sep 17 00:00:00 2001
From: Jeffery <jiantw83@yahoo.com>
Date: Wed, 2 Sep 2026 14:27:18 +0800
Subject: [PATCH 1/9] =?UTF-8?q?feat(link):=20=E9=80=A3=E7=B5=90=E4=B8=80?=
 =?UTF-8?q?=E5=BE=8B=E5=AF=AB=E6=88=90=20[=E6=96=87=E5=AD=97](=E7=B5=95?=
 =?UTF-8?q?=E5=B0=8D=E7=B6=B2=E5=9D=80)=EF=BC=8C=E5=AF=AB=E5=85=A5?=
 =?UTF-8?q?=E5=89=8D=E5=85=88=E9=A9=97=E8=AD=89=E9=80=A3=E5=BE=97=E5=88=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

取消 [[頁名]] 與 [[顯示文字|頁名]] 兩種同 wiki 寫法，不再分「同存取庫」與
「跨存取庫」兩條規則。那種寫法只在自己那個 wiki 內解析，寫錯不報錯，畫面上
看起來像普通文字或死連結，巡不到也修不了。

連結寫進頁面前先過 jsc-gitea 的 link-check.sh，結束碼 0 才寫。驗證一律走 API，
不看網頁狀態碼：私有存取庫的網頁網址對未登入請求一律回 404，拿狀態碼判會把
好連結判成壞的。認證失敗回 7，與死連結的 1 分開，免得金鑰一過期就把還在的頁
整批判死。
---
 README.md                     |  4 +--
 references/behaviors.md       |  8 +++---
 skills/hooks-install/SKILL.md |  2 +-
 templates/error-contents.md   |  6 ++--
 tools/report-error.sh         | 52 +++++++++++++++++++++++++++--------
 5 files changed, 52 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 39597f9..e1975d3 100644
--- a/README.md
+++ b/README.md
@@ -169,7 +169,7 @@ Claude 由 `hooks/hooks.json` 自動接線九支 hook；其他 CLI 用 `hooks-in
 | --- | --- |
 | `tools/jsc-wrap.sh` | 沒有完整 hook 系統的 CLI 的包裝啟動器：匯出 `JSC_CLI`、`JSC_SESSION_ID`，前後接 `session-timer.sh`，結束時自動跑 `scan-logs.sh` 回填，再依序跑一次 `comment-scope.sh sweep` 與 `lang-guard.sh sweep` 掃整個 git 工作區的註解範圍與繁中編碼（copilot 與 antigravity 沒有任何逐輪事件，整個工作階段只有這裡掃得到）。兩次收尾掃描一律不影響結束碼：包裝器原樣回傳 CLI 自己的結束碼，`sweep` 命中只把警告印到 stderr。`JSC_CLI` 存 CLI 代號，實際執行的是對應的執行檔（antigravity 是 agy、kiro 是 kiro-cli） |
 | `tools/scan-logs.sh` | 離線回填：解析 copilot、antigravity、codex 的原生日誌，把技能用量與階段界線補進 `$JSC_HOME`，重掃不重複 |
-| `tools/report-error.sh` | 失敗回報流程：把一筆 hook 或工具異常寫成 wiki 的 `ERROR_{HASH}`，並在 `ERROR_CONTENTS` 附上一列索引。目錄頁一律先讀回舊頁再附加新列、整頁寫回，不整頁覆蓋：只有 `wiki-get` 回 4（頁面真的不存在）才用範本建新頁，回 7（金鑰失效）或 8（其他 API 失敗）代表舊內容未知，放棄目錄頁寫入並以 exit 4 回報，免得拿範本蓋掉所有既有列。目錄頁指向異常頁的連結用 `gitea.sh wiki-url` 的絕對網址，跨存取庫的 `[[頁名]]` 解不開。網址在異常頁寫成功之後才取：頁名的 hash 帶時間戳，每次回報都是全新的頁，寫進去之前查一定是 404，先查就只拿得到空字串。取不到網址時只印頁名，原因走 stderr，結束碼照舊回 0。wiki 位置分兩次解析：異常頁走 `jsc-gitea` 的 `gitea.sh wiki-repo ERROR`，目錄頁走 `gitea.sh wiki-repo CONTENTS`，兩者是兩個不同的存取庫。異常頁的存取庫解不出來就整支安靜降級；只有目錄頁的存取庫解不出來，就只寫異常頁、跳過目錄頁更新，仍回 exit 0。由操作者手動執行，或由 `hooks-install` 在 `wire-cli.sh` 回報 `status=failed` 時執行；**不接在失敗的 hook 上自動觸發**（hook 一律安靜 exit 0，自我回報會疊出迴圈） |
+| `tools/report-error.sh` | 失敗回報流程：把一筆 hook 或工具異常寫成 wiki 的 `ERROR_{HASH}`，並在 `ERROR_CONTENTS` 附上一列索引。目錄頁一律先讀回舊頁再附加新列、整頁寫回，不整頁覆蓋：只有 `wiki-get` 回 4（頁面真的不存在）才用範本建新頁，回 7（金鑰失效）或 8（其他 API 失敗）代表舊內容未知，放棄目錄頁寫入並以 exit 4 回報，免得拿範本蓋掉所有既有列。目錄頁那一列指向異常頁，連結一律寫成 `[{文字}]({連結})`，網址取 `jsc-gitea` 的 `gitea.sh wiki-url` 印出的那一個，不自己組路徑。寫進那一格之前，先把那個網址交給 `jsc-gitea` 的 `tools/link-check.sh` 驗一次，結束碼 0 才寫連結；`link-check.sh` 的路徑由已經解出來的 `gitea.sh` 推得，兩支同一個 tools 目錄。驗不過（含找不到 `link-check.sh`、`GITEA_HOST` 未設定回 3、金鑰失效回 7）就只在那一格留純文字頁名，那一列照寫、異常頁照寫、結束碼照舊，原因走 stderr——回報失敗不該再變成一次失敗。網址在異常頁寫成功之後才取：頁名的 hash 帶時間戳，每次回報都是全新的頁，寫進去之前查一定是 404，先查就只拿得到空字串。取不到網址時只印頁名，原因走 stderr，結束碼照舊回 0。wiki 位置分兩次解析：異常頁走 `jsc-gitea` 的 `gitea.sh wiki-repo ERROR`，目錄頁走 `gitea.sh wiki-repo CONTENTS`，兩者是兩個不同的存取庫。異常頁的存取庫解不出來就整支安靜降級；只有目錄頁的存取庫解不出來，就只寫異常頁、跳過目錄頁更新，仍回 exit 0。由操作者手動執行，或由 `hooks-install` 在 `wire-cli.sh` 回報 `status=failed` 時執行；**不接在失敗的 hook 上自動觸發**（hook 一律安靜 exit 0，自我回報會疊出迴圈） |
 | `tools/wire-cli.sh` | 單一 CLI 的 hook 生命週期，共四個用法。`{cli}` 是接線：先建立或更新 `$JSC_HOME/current/jsc-hooks` 指向目前這版 plugin，接著把對應的設定編輯、包裝別名安裝、hook 檔建立成穩定路徑，皆以 `<!-- jsc-hooks -->`（或 `# jsc-hooks`）標記整段重寫，重跑等同先移除再重裝；寫完每個檔案會重讀驗證位置正確才回報成功（codex 的 `notify` 必須是根層鍵、`.codex-plugin/plugin.json` 的 matcher 必須是 `Bash`、copilot 必須是小寫 `skill` 且沒有第二種大小寫的事件名、antigravity 的 matcher 必須帶錨點 `^view_file$` 且有 `PreInvocation`、kiro 的 agent JSON 必須成對且 `hooks`、`resources`、`tools` 在最上層並含兩層 `skill://` glob），也會確認寫入路徑能解到既有腳本。matcher 本身要單獨驗：鍵在、matcher 卻錯的形態最難查，回報會說接好了，實際一次都不會被叫用。檔案系統不能建立 symlink 時，會明確回報並退回目前根目錄，不會靜默寫出壞路徑。`status=wired\|degraded\|skipped\|failed` 回報接線結果。`purge {cli}` 是移除：把該 CLI 的**所有** hook 清掉，含非 jsc 的第三方項目，動到的檔案先原樣備份到 `$JSC_HOME/backup/hooks/{cli}/{yyyyMMdd_HHmmss}/`，備份失敗就不移除；移除標記段落時會先去掉標記行前後空白，所以縮排或尾端補空白的 jsc 區塊一樣會移除；移除後重讀驗證，驗不過自動還原備份，以 `status=purged\|skipped\|failed` 回報。`smoke {cli}` 是執行期冒煙測試：九支 hook 的每個接線模式各跑一次，非零退出即為錯誤，另外把五支 CLI 的真實負載各餵進 `skill-name.sh` 一次驗技能名解析、四種阻擋形態各驗一次 `deny.sh`，再把那些負載直接餵進 `restart-gate.sh` 驗「解析→判定→輸出形態」整條串得起來（含 fail-open、豁免放行與 kiro 的注入路徑）——前兩組分開看都會顯示正常，中間接不上照樣是全程放行，那正是先前三支 CLI 失效的樣子；另外用一份暫時的 `$JSC_HOME` 狀態檔把模型來源與階段鎖、工作包歸屬、部署後重啟閘門與寫入提交閘門的每條判定路徑各跑一次並比對結束碼（模型來源的每個案例各自指定 CLI 代號，不跟著這一輪接線的 CLI 走——偵測鏈已依 CLI 分流；「不知道能力就擋下」的三種情形連訊息裡的逃生門一起驗，只比結束碼的話訊息漏掉逃生門也是綠燈），再用一份暫時的 `HOME`（假的 `installed_plugins.json` 與各 plugin 的 manifest）把 `version-guard.sh` 相依版本檢查的每條路徑跑一次——相依落後的擋人與訊息內容、相等與超前的放行、豁免技能在相依落後時照樣放行、四種 fail-open、逃生門，另加一條回歸：多行縮排的 manifest，`jsc.requires` 的最後一個鍵也要解得到。驗的是判定結果本身，不只是腳本跑得完（例外有四個：`sdlc-gate.sh check` 的 exit 2 是階段鎖的設計行為，`comment-scope.sh`、`lang-guard.sh` 掃描模式與 `write-guard.sh` 三種模式的 exit 2 是命中違規的設計行為——`sweep` 在髒工作區本來就會回 2，`write-guard.sh` 在機器剛好鎖在 `plan` 階段時也會回 2，都不算 hook 壞掉），以 `status=ok\|failed` 回報。**結果行數由腳本自己數、自己斷言**：`status=` 之後緊接一行 `lines<TAB>{數量}`，那是其後 `[jsc]` 結果行的實際條數，與腳本內逐類宣告的預期條數比對，不符就回非零。判定路徑增減時只改腳本裡的預期值，散文一律引用這一行，不另外抄一份數字。`status {cli}` 是唯讀盤點：只讀設定檔判斷段落與 matcher 對不對，不寫檔也不執行 hook，claude、codex、copilot、antigravity 回 `wired`，kiro 回 `degraded` 並在 `reason` 講明那是 CLI 限制；每個接線點印一行 `item<TAB>{項目}<TAB>{路徑}<TAB>{present\|missing\|unverified}`，也會把帶版號快取路徑、開發存取庫路徑與不存在的腳本列為缺項。狀態有三格不是兩格：`unverified` 是「這一項驗不了」，只有 `missing` 才算缺項——`kiro-cli agent validate` 在沒登入時印的是環境問題，不是這個檔案的問題，報 `present` 會讓沒驗到的東西看起來像通過，報 `missing` 會把沒登入算成接線缺漏；`status claude` 讀 Claude Code 實際載入的 `installed_plugins.json`，不再檢查目前腳本旁邊那份 `hooks.json`。體檢類技能（`/jsc-cli:doctor`）只能用這個子命令，另外三個都會動到環境；那道限制另有程式層把關，`JSC_READONLY=1` 之下只准 `status` 與 `smoke`，`purge` 與接線一律以 exit 6 拒絕並回報 `status=readonly`，環境不會被動到 |
 | `tools/scan-hook-errors.sh` | 掃 CLI 原生紀錄找 hook 的執行期錯誤（接線寫對、跑起來出錯）。只有 claude 有 hook 結果紀錄，掃 `~/.claude/projects/**/*.jsonl` 的 `hook_non_blocking_error` 與非空 `hookErrors`；codex、copilot、antigravity、kiro 沒有等價紀錄，一律回報 `unavailable` 並指向 `wire-cli.sh smoke {cli}`。每筆錯誤附加一行 JSON 到 `$JSC_HOME/errors/hooks.jsonl`，`jsc` 欄位標明是不是 jsc 自己的 hook（第三方 hook 的錯誤只回報，不由 jsc 修正）；去重與 `scan-logs.sh` 同法，重掃只讀新增段落，以 `status=clean\|errors\|unavailable` 回報 |
 
@@ -181,7 +181,7 @@ Claude 由 `hooks/hooks.json` 自動接線九支 hook；其他 CLI 用 `hooks-in
 | 範本 | 用途 |
 | --- | --- |
 | `templates/error-page.md` | 單筆 hook 異常頁 `ERROR_{HASH}`，記錄當次失敗的觸發條件、錯誤摘要與處理結果。 |
-| `templates/error-contents.md` | 異常目錄 `ERROR_CONTENTS`，彙整所有異常頁，方便先看最新問題再往下追。落在目錄專用存取庫，一律 upsert 附加，連結用絕對網址。 |
+| `templates/error-contents.md` | 異常目錄 `ERROR_CONTENTS`，彙整所有異常頁，方便先看最新問題再往下追。落在目錄專用存取庫，一律 upsert 附加，連結一律寫成 `[{文字}]({連結})` 且先過 `link-check.sh` 驗過才寫。 |
 
 ## Skills 目錄
 
diff --git a/references/behaviors.md b/references/behaviors.md
index 51e1e58..2b64c64 100644
--- a/references/behaviors.md
+++ b/references/behaviors.md
@@ -7,10 +7,10 @@
 | 項目 | 內容 |
 | --- | --- |
 | 觸發時機 | 裝好或更新完 jsc 技能組之後，要把九支 hook 接線到每一支已安裝的 CLI 時用；`jsc-cli:deploy` 收尾會把偵測到的 CLI 清單交給它。不用於撰寫新的 hook，也不用於單獨修一支壞掉的 hook，那是 `jsc-hooks:repair` 的事 |
-| 關鍵步驟 | 取得 CLI 清單（呼叫端交來的優先，沒有才自己跑 `detect-clis.sh`）、第一支 CLI 單獨跑完整條管線（它負責更新共用的 `$JSC_HOME/current/jsc-hooks` 連結）、其餘 CLI 一支一個 sub agent 並行、每支 CLI 依序走 purge、接線、status、smoke、scan 五道關卡、讀每道關卡自己印的第一行判定、任一關卡出錯就寫 `ERROR_{HASH}` 並轉給 `jsc-hooks:repair`（異常頁與索引目錄頁分屬兩個存取庫，各自解析；只解不出目錄頁的存取庫時異常頁照寫、索引跳過，回報要講明那一頁沒被索引）、逐 CLI 回報五道關卡的結果 |
-| 外部呼叫 | `tools/wire-cli.sh purge`、`tools/wire-cli.sh {cli}`、`tools/wire-cli.sh status`、`tools/wire-cli.sh smoke`、`tools/scan-hook-errors.sh`、`tools/report-error.sh`、`jsc-cli/tools/detect-clis.sh`、`jsc-hooks:repair` 技能、`jsc-gitea:wiki`（寫 `ERROR_{HASH}` 時經 `report-error.sh`）；接線腳本內部另呼叫 `hooks/skill-name.sh` 與 `hooks/deny.sh` 做冒煙斷言 |
-| 完成條件 | 每一支偵測到的 CLI 都有五道關卡各一行判定，沒有任何一道回結束碼 2，smoke 的 `lines` 條數與它自己的斷言相符，claude、codex、copilot、antigravity 回 `wired` 而 kiro 回 `degraded`（CLI 擋不下技能叫用），四支非 claude 的執行期錯誤掃描一律據實回 `unavailable`，各 CLI 的形狀與觸發驗證等級分開寫進回報（codex、antigravity、kiro 形狀實證，copilot 形狀未證；kiro 觸發部分實證，其餘未驗證），而且每一筆錯誤都帶一個 `ERROR_{HASH}` 結果與一條對 `develop` 的修正 PR 連結 |
-| 可驗證跡象 | 各 CLI 的設定檔多出 jsc 段落：codex 的 `config.toml` 標記段落、`hooks/codex-hooks.json`（從 `hooks/hooks.json` 推導，matcher `Skill` 換成 `Bash`）與 `.codex-plugin/plugin.json` 指過去的 `hooks` 路徑字串、copilot 的 `~/.copilot/settings.json` 頂層 `hooks` 鍵（matcher `skill`，合併不覆寫，`enabledPlugins` 與第三方條目原樣保留）與 `$COPILOT_HOME` 底下的指引檔、antigravity 的 `~/.gemini/config/hooks.json` 的 `jsc` 段落（`PreToolUse` 為 Grouped、matcher `^view_file$`，`PreInvocation` 維持 Flat）、kiro 的 `~/.kiro/agents/jsc.json`（`hooks` 為 `agentSpawn`、`userPromptSubmit`、`stop` 三個合法事件加 `timeout_ms`、兩層 `skill://` glob 的 `resources`、明列的 `tools`，並通過 `kiro-cli agent validate`）與 `~/.kiro/settings/cli.json` 的 `chat.defaultAgent=jsc`；四支非 claude 的接線命令都以 `JSC_CLI={代號}` 前綴自帶 CLI 代號，缺了它兩道閘門解不出技能名、一律安靜放行，所以 `status` 把它列成單獨一項；另有 `$JSC_HOME/current/jsc-hooks` 符號連結建立或更新、`$JSC_HOME/backup/hooks/{cli}/{時間戳}/` 留下 purge 前的備份、出錯時 wiki 多一頁 `ERROR_{HASH}`（落在 `JSC_WIKI_REPO_ERROR` 解出的存取庫）並在索引目錄頁補一列（落在 `JSC_WIKI_REPO_CONTENTS` 解出的另一個存取庫，那一列指向異常頁的連結是絕對網址）、修正路徑留下一條對 `develop` 的 PR |
+| 關鍵步驟 | 取得 CLI 清單（呼叫端交來的優先，沒有才自己跑 `detect-clis.sh`）、第一支 CLI 單獨跑完整條管線（它負責更新共用的 `$JSC_HOME/current/jsc-hooks` 連結）、其餘 CLI 一支一個 sub agent 並行、每支 CLI 依序走 purge、接線、status、smoke、scan 五道關卡、讀每道關卡自己印的第一行判定、任一關卡出錯就寫 `ERROR_{HASH}` 並轉給 `jsc-hooks:repair`（異常頁與索引目錄頁分屬兩個存取庫，各自解析；只解不出目錄頁的存取庫時異常頁照寫、索引跳過，回報要講明那一頁沒被索引）、目錄頁那一列指向異常頁的連結一律寫成 `[{文字}]({連結})`，網址取 `gitea.sh wiki-url`，寫進去之前先過 `jsc-gitea/tools/link-check.sh`，結束碼 0 才寫連結、驗不過那一格只留純文字頁名而那一列與異常頁照寫（`report-error.sh` 內部做完，結束碼不變）、逐 CLI 回報五道關卡的結果 |
+| 外部呼叫 | `tools/wire-cli.sh purge`、`tools/wire-cli.sh {cli}`、`tools/wire-cli.sh status`、`tools/wire-cli.sh smoke`、`tools/scan-hook-errors.sh`、`tools/report-error.sh`、`jsc-cli/tools/detect-clis.sh`、`jsc-hooks:repair` 技能、`jsc-gitea:wiki`（寫 `ERROR_{HASH}` 時經 `report-error.sh`）、`jsc-gitea/tools/gitea.sh wiki-url` 與 `jsc-gitea/tools/link-check.sh`（同樣經 `report-error.sh`，取目錄頁那一列的網址並驗它連得到）；接線腳本內部另呼叫 `hooks/skill-name.sh` 與 `hooks/deny.sh` 做冒煙斷言 |
+| 完成條件 | 每一支偵測到的 CLI 都有五道關卡各一行判定，沒有任何一道回結束碼 2，smoke 的 `lines` 條數與它自己的斷言相符，claude、codex、copilot、antigravity 回 `wired` 而 kiro 回 `degraded`（CLI 擋不下技能叫用），四支非 claude 的執行期錯誤掃描一律據實回 `unavailable`，各 CLI 的形狀與觸發驗證等級分開寫進回報（codex、antigravity、kiro 形狀實證，copilot 形狀未證；kiro 觸發部分實證，其餘未驗證），每一筆錯誤都帶一個 `ERROR_{HASH}` 結果與一條對 `develop` 的修正 PR 連結，而且目錄頁那一列的連結驗不過時，回報要講明那一列只有純文字頁名、沒有連結 |
+| 可驗證跡象 | 各 CLI 的設定檔多出 jsc 段落：codex 的 `config.toml` 標記段落、`hooks/codex-hooks.json`（從 `hooks/hooks.json` 推導，matcher `Skill` 換成 `Bash`）與 `.codex-plugin/plugin.json` 指過去的 `hooks` 路徑字串、copilot 的 `~/.copilot/settings.json` 頂層 `hooks` 鍵（matcher `skill`，合併不覆寫，`enabledPlugins` 與第三方條目原樣保留）與 `$COPILOT_HOME` 底下的指引檔、antigravity 的 `~/.gemini/config/hooks.json` 的 `jsc` 段落（`PreToolUse` 為 Grouped、matcher `^view_file$`，`PreInvocation` 維持 Flat）、kiro 的 `~/.kiro/agents/jsc.json`（`hooks` 為 `agentSpawn`、`userPromptSubmit`、`stop` 三個合法事件加 `timeout_ms`、兩層 `skill://` glob 的 `resources`、明列的 `tools`，並通過 `kiro-cli agent validate`）與 `~/.kiro/settings/cli.json` 的 `chat.defaultAgent=jsc`；四支非 claude 的接線命令都以 `JSC_CLI={代號}` 前綴自帶 CLI 代號，缺了它兩道閘門解不出技能名、一律安靜放行，所以 `status` 把它列成單獨一項；另有 `$JSC_HOME/current/jsc-hooks` 符號連結建立或更新、`$JSC_HOME/backup/hooks/{cli}/{時間戳}/` 留下 purge 前的備份、出錯時 wiki 多一頁 `ERROR_{HASH}`（落在 `JSC_WIKI_REPO_ERROR` 解出的存取庫）並在索引目錄頁補一列（落在 `JSC_WIKI_REPO_CONTENTS` 解出的另一個存取庫，那一列的第 2 格寫成 `[{頁名}]({絕對網址})`，網址取自 `gitea.sh wiki-url` 且已經過 `link-check.sh` 驗到結束碼 0；驗不過那一格只有純文字頁名，`report-error.sh` 在 stderr 留一行 `[jsc]` 講明是哪一種原因）、修正路徑留下一條對 `develop` 的 PR |
 
 ## repair
 
diff --git a/skills/hooks-install/SKILL.md b/skills/hooks-install/SKILL.md
index a5b9ebf..a7c93ea 100644
--- a/skills/hooks-install/SKILL.md
+++ b/skills/hooks-install/SKILL.md
@@ -75,7 +75,7 @@ The detailed flow **MUST run as a sub agent**; the main agent only reports the s
    5. `tools/scan-hook-errors.sh --cli {cli}` — only claude keeps hook results in its native records and can answer `clean` or `errors`; codex, copilot, antigravity and kiro answer `unavailable`, and their runtime evidence comes from the smoke stage alone. Exit 0 covers both `clean` and `unavailable`, exit 1 is `errors` and every entry with `jsc=true` goes to step 3, exit 2 is a bad CLI name.
 
    Done when every detected CLI has exactly one verdict line per stage, no stage exited 2, the smoke stage's `lines` count matches its own assertion, the four non-claude CLIs are reported as `unavailable` rather than clean on the scan stage, and antigravity and kiro carry the note that their hook firing is unverified.
-3. For each error — a failed purge, a failed wiring, an `unwired` status, a failed smoke, or a scanned error with `jsc=true` — run `tools/report-error.sh --hook {script name} --exit {code} --summary "{reason}" --cli {cli}` with the script's `[jsc]` output on stdin, then hand the failure to `jsc-hooks:repair`, which **MUST run as a sub agent** and must finish by opening a PR against `develop`. Aborting the remaining installs here is allowed as long as the repair starts. The error page and the error directory page live in two different wiki repos, resolved separately: the page through `wiki-repo ERROR`, the directory through `wiki-repo CONTENTS`. Exit 0 with an `ERROR_{HASH}` page name and URL on stdout means the page was written; the same exit 0 with a `[jsc]` line on stderr still means the page landed, and that line says what is missing — either the directory repo would not resolve, so nothing indexes the page, or the page URL could not be read back, so the page name comes out on its own — carry that note into step 4. Exit 0 with no output at all means the run ended on one of the quiet-degradation reasons listed in the script's own header — no `gitea.sh` on the path, the error page's wiki repo unresolved, the hash not computed, or a temp file not created — so no page was written at all and that reason goes into step 4 instead; exit 2 means the call itself was malformed — `--hook` or `--summary` is missing — so fix the arguments and rerun the same call; exit 4 means the wiki record did not land, so report the failure text and still start the repair — a page that could not be written is no reason to leave a broken hook wired. Exit 4 covers two cases, and the report has to say which: a failed write, or the script refusing to write the error directory page because it could not read the old one back. That directory is appended to, never overwritten: every row on it is somebody else's error report, so the script reads the page, adds this run's row, and writes the whole page. Only a genuine 404 (`wiki-get` exit 4) means the page is not there yet and lets it build one from the template. An invalid key (exit 7) or any other API failure (exit 8) leaves the old rows unknown, so it skips the directory write and names the code instead — writing a fresh template over a directory it never read would erase every earlier report, with no merge and no backup behind it. A scanned error with `jsc=false` belongs to a third-party hook: report it and leave it alone. Skip this step when every CLI passed all five stages. Done when every error carries one `ERROR_{HASH}` result — a page name with its URL, a page name plus the reason the URL is missing, or the recorded reason no page was written — and one repair PR URL against `develop`.
+3. For each error — a failed purge, a failed wiring, an `unwired` status, a failed smoke, or a scanned error with `jsc=true` — run `tools/report-error.sh --hook {script name} --exit {code} --summary "{reason}" --cli {cli}` with the script's `[jsc]` output on stdin, then hand the failure to `jsc-hooks:repair`, which **MUST run as a sub agent** and must finish by opening a PR against `develop`. Aborting the remaining installs here is allowed as long as the repair starts. The error page and the error directory page live in two different wiki repos, resolved separately: the page through `wiki-repo ERROR`, the directory through `wiki-repo CONTENTS`. Exit 0 with an `ERROR_{HASH}` page name and URL on stdout means the page was written; the same exit 0 with a `[jsc]` line on stderr still means the page landed, and that line says what is missing — the directory repo would not resolve, so nothing indexes the page; the page URL could not be read back, so the page name comes out on its own; or the URL failed the reachability check, so the directory row carries the page name as plain text with no link — carry that note into step 4. Every link on that row is written as `[{text}]({url})` with the URL from `gitea.sh wiki-url`, and the script checks it with `jsc-gitea/tools/link-check.sh` before writing: exit 0 writes the link, anything else keeps the row and drops the link, and none of it changes the exit code — this is the failure-reporting path, so a failed report must never become a second failure. Exit 0 with no output at all means the run ended on one of the quiet-degradation reasons listed in the script's own header — no `gitea.sh` on the path, the error page's wiki repo unresolved, the hash not computed, or a temp file not created — so no page was written at all and that reason goes into step 4 instead; exit 2 means the call itself was malformed — `--hook` or `--summary` is missing — so fix the arguments and rerun the same call; exit 4 means the wiki record did not land, so report the failure text and still start the repair — a page that could not be written is no reason to leave a broken hook wired. Exit 4 covers two cases, and the report has to say which: a failed write, or the script refusing to write the error directory page because it could not read the old one back. That directory is appended to, never overwritten: every row on it is somebody else's error report, so the script reads the page, adds this run's row, and writes the whole page. Only a genuine 404 (`wiki-get` exit 4) means the page is not there yet and lets it build one from the template. An invalid key (exit 7) or any other API failure (exit 8) leaves the old rows unknown, so it skips the directory write and names the code instead — writing a fresh template over a directory it never read would erase every earlier report, with no merge and no backup behind it. A scanned error with `jsc=false` belongs to a third-party hook: report it and leave it alone. Skip this step when every CLI passed all five stages. Done when every error carries one `ERROR_{HASH}` result — a page name with its URL, a page name plus the reason the URL is missing, or the recorded reason no page was written — and one repair PR URL against `develop`.
 4. Report five results per CLI — purge, wiring, status, smoke, scan — each with the reason its script printed, plus the smoke `lines` count, any `ERROR_{HASH}` page name and every repair PR URL. Done when every detected CLI appears with one verdict per stage and every repair has a PR against `develop`.
 
 ## Notes
diff --git a/templates/error-contents.md b/templates/error-contents.md
index ca2f666..4d9cbce 100644
--- a/templates/error-contents.md
+++ b/templates/error-contents.md
@@ -6,10 +6,12 @@
 >
 > 寫入語意：一列代表一次 hook 異常回報。寫入前先讀回整頁，同一筆異常已經有列就更新那一列，沒有才在文末附加一列，最後整頁寫回。一律 upsert 附加，禁止整頁覆蓋，也不得改動別人的列。
 >
-> 連結寫法：指向異常頁的連結一律用 `gitea.sh wiki-url` 產出的絕對網址。跨存取庫的 `[[頁名]]` 解不開，只會留下死連結。
+> 連結寫法：一律寫成 `[{文字}]({絕對網址})`，網址取 `jsc-gitea/tools/gitea.sh wiki-url` 印出的那一個，不自己組路徑。wiki 自己那種雙中括號寫法只在同一個 wiki 裡解得開，寫錯不會報錯，畫面上看起來像正常文字或死連結。
+>
+> 寫入前驗證：這一列要放進去的連結，先交給 `jsc-gitea/tools/link-check.sh`，結束碼 0 才把連結寫進那一格。驗不過就只留純文字頁名，那一列照寫，異常紀錄不因為一條連結整份丟掉。驗證走 API，不看網頁狀態碼——私有存取庫的網頁網址對未登入請求一律回 404，拿狀態碼判會把還在的頁判成死連結。結束碼 7 是金鑰失效，不算死連結，也不改寫任何既有列。
 
 ## 異常清單
 
 | 時間 | 頁名 | 存取庫名稱 | 觸發 hook | 退出碼 | 摘要 |
 | --- | --- | --- | --- | --- | --- |
-| {yyyy-MM-dd HH:mm:ss} | [{error title}]({error url}) | {owner}/{repo} | {hook_name} | {exit_code} | {error_summary} |
+| {yyyy-MM-dd HH:mm:ss} | [{頁名}]({wiki-url 印出的絕對網址}) | {owner}/{repo} | {hook_name} | {exit_code} | {error_summary} |
diff --git a/tools/report-error.sh b/tools/report-error.sh
index cebecb9..341596e 100755
--- a/tools/report-error.sh
+++ b/tools/report-error.sh
@@ -24,6 +24,13 @@
 #   一份寫得成的異常紀錄，不該因為目錄頁沒地方放就整份丟掉。
 #   寫入 wiki 失敗才以 exit 4 回報，訊息走 stderr。
 #
+# 連結:
+#   目錄頁那一列指向異常頁，一律寫成 [{文字}]({連結})，網址取 jsc-gitea 的
+#   gitea.sh wiki-url，不自己組路徑。
+#   寫入前先把那個網址交給 jsc-gitea 的 link-check.sh，結束碼 0 才把連結寫進那一列。
+#   驗不過就只留純文字頁名：那一列照寫、異常頁照寫、結束碼照舊。這一段一律不改結束碼，
+#   本腳本是失敗回報路徑，回報失敗不該再變成一次失敗。
+#
 # 結束碼: 0=已寫入異常頁並印出頁名（取得網址就一併印出），或以上列四種安靜降級原因之一
 #           結束、沒有寫出任何頁也沒有任何輸出——回報失敗不該再變成一次失敗
 #         2=用法錯誤（缺 --hook 或 --summary）
@@ -139,8 +146,9 @@ if ! sh "$gsh" wiki-put "$wrepo" "$page" "$tmp_page" >/dev/null 2>&1; then
   exit 4
 fi
 
-# 目錄頁與異常頁分屬兩個存取庫，wiki 的 [[頁名]] 只在同一個存取庫內解得開，跨庫一律解成
-# 死連結。所以目錄頁指向異常頁的連結一律用絕對網址。
+# 目錄頁那一列指向異常頁，連結一律寫成 [{文字}]({連結})，網址取 gitea.sh wiki-url。
+# wiki 自己那種雙中括號寫法只在同一個 wiki 裡解得開，寫錯不會報錯，畫面上看起來像正常
+# 文字或死連結，巡不到也修不了。
 # 網址取不到不算失敗：異常頁已經寫成功了，只是這一列少一條連結。這裡把原因記下來走 stderr，
 # 結束碼照舊——安靜降級仍是 exit 0，回報失敗不該再變成一次失敗。
 url=$(sh "$gsh" wiki-url "$wrepo" "$page" 2>/dev/null)
@@ -161,17 +169,39 @@ emit() { # 異常頁已經寫成功，頁名一定要印；網址取不到就只
   if [ -n "$url" ]; then printf '%s %s\n' "$page" "$url"; else printf '%s\n' "$page"; fi
 }
 
-row=$(printf '| %s | [%s](%s) | %s | %s | %s | %s |' \
-  "$ts" "$hook 異常 $ts" "$url" "$repo" "$hook" "$code" "$summary")
+# 連結先驗證連得到，才寫進目錄頁那一列。沒驗過的連結寫進去，異常頁一樣會在目錄頁長出
+# 死連結，而目錄頁是別人查問題的入口。驗不過就只留純文字頁名，那一列照寫。
+link_cell="$page"
+if [ -n "$url" ]; then
+  # link-check.sh 與 gitea.sh 同一個 tools 目錄，路徑直接由已經解出來的那一支推得，
+  # 不另寫一套搜尋，兩邊才不會一支解到開發版面、一支解到安裝版面。
+  lcs="$(dirname "$gsh")/link-check.sh"
+  if [ ! -f "$lcs" ]; then
+    echo "[jsc] 找不到 $lcs，這一列的連結沒驗過，只留頁名；$page 已建立。" >&2
+  else
+    sh "$lcs" "$url" >/dev/null 2>&1
+    lc_code=$?
+    case "$lc_code" in
+      0) link_cell=$(printf '[%s](%s)' "$page" "$url") ;;
+      # 7 是金鑰失效，不是死連結。金鑰過期時私有存取庫的回應與「頁不存在」分不出來，
+      # 把它當成死連結就會連還在的頁一起判死。
+      7) echo "[jsc] 連結驗證遇上金鑰失效（link-check.sh 回 7），不判成死連結，這一列只留頁名；$page 已建立。" >&2 ;;
+      3) echo "[jsc] GITEA_HOST 未設定（link-check.sh 回 3），連結沒驗過，這一列只留頁名；$page 已建立。" >&2 ;;
+      *) echo "[jsc] 連結驗不過（link-check.sh 結束碼 $lc_code），這一列只留頁名；$page 已建立。" >&2 ;;
+    esac
+  fi
+fi
+
+row=$(printf '| %s | %s | %s | %s | %s | %s |' \
+  "$ts" "$link_cell" "$repo" "$hook" "$code" "$summary")
 
 build_contents() { # 用範本建一份全新的目錄頁；只有確定舊頁不存在時才可以呼叫
-  fill '{yyyy-MM-dd HH:mm:ss}' "$ts" < "$ROOT/templates/error-contents.md" \
-    | fill '{error url}' "$url" \
-    | fill '{error title}' "$hook 異常 $ts" \
-    | fill '{owner}/{repo}' "$repo" \
-    | fill '{hook_name}' "$hook" \
-    | fill '{exit_code}' "$code" \
-    | fill '{error_summary}' "$summary" > "$tmp_list"
+  # 範本的示範列整列換成本次這一列，不逐格填。連結那一格已經驗過也組好了，拆成頁名與
+  # 網址兩個佔位再填，會在驗不過的時候留下一個空網址的死連結。
+  ROW="$row" awk '
+    index($0, "| {yyyy-MM-dd HH:mm:ss} |") == 1 { print ENVIRON["ROW"]; next }
+    { print }
+  ' "$ROOT/templates/error-contents.md" > "$tmp_list"
 }
 
 if [ -z "$crepo" ]; then
-- 
2.53.0


From 913689483777b0a41347f3d978965d209e9151db Mon Sep 17 00:00:00 2001
From: Jeffery <jiantw83@yahoo.com>
Date: Wed, 2 Sep 2026 14:27:18 +0800
Subject: [PATCH 2/9] =?UTF-8?q?chore(plugin=20=E7=89=88=E6=9C=AC):=20?=
 =?UTF-8?q?=E4=B8=89=E4=BB=BD=20manifest=20=E5=8D=87=E7=89=88=E8=87=B3=200?=
 =?UTF-8?q?.3.9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .claude-plugin/plugin.json | 2 +-
 .codex-plugin/plugin.json  | 2 +-
 plugin.json                | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 70d2045..2490afb 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "jsc-hooks",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟、寫入與提交閘門",
   "skills": "./skills",
   "author": {
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index a241d04..76aec92 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "hooks": "./hooks/codex-hooks.json",
   "name": "jsc-hooks",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟、寫入與提交閘門",
   "skills": "./skills",
   "jsc": {
diff --git a/plugin.json b/plugin.json
index 03d9fa6..2b486eb 100644
--- a/plugin.json
+++ b/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "jsc-hooks",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟、寫入與提交閘門",
   "skills": "./skills/",
   "jsc": {
-- 
2.53.0


From 1d8635976791d9e0c0f16aaafed248f230cb2548 Mon Sep 17 00:00:00 2001
From: Jeffery <jiantw83@yahoo.com>
Date: Wed, 2 Sep 2026 14:57:04 +0800
Subject: [PATCH 3/9] =?UTF-8?q?fix(=E6=8E=A5=E7=B7=9A=E7=9B=A4=E9=BB=9E):?=
 =?UTF-8?q?=20status=20=E5=88=97=E8=88=89=E6=AF=8F=E4=B8=80=E5=80=8B?=
 =?UTF-8?q?=E6=8E=A5=E7=B7=9A=E9=BB=9E=EF=BC=8C=E4=B8=8D=E5=86=8D=E5=8F=AA?=
 =?UTF-8?q?=E6=8C=91=E5=9B=9B=E6=94=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

README 早就寫明「每個接線點印一行 item」，程式卻只列 comment-scope、
lang-guard、restart-gate 與 write-guard 三種模式，共六項。sdlc-gate 的三個
接線點、session-timer 的兩個、skill-usage 與 version-guard 都沒列出來。

漏列的後果不是少幾行字。reason 那行寫的是「全部九支 hook」，拿這份輸出
驗收接線的人會把沒列到的當成沒接——模型能力鎖就是這樣被誤判成沒接線的。
體檢技能也讀這支的輸出，同樣看不到那四支。

一支腳本接在多個接線點時，每個點各自列一項。只驗腳本名的話，「腳本在、
某個接線點沒接」會被算成完整接線，那正是最難查的一種。
---
 tools/wire-cli.sh | 40 ++++++++++++++++++++++++----------------
 1 file changed, 24 insertions(+), 16 deletions(-)

diff --git a/tools/wire-cli.sh b/tools/wire-cli.sh
index a3a54b9..f9c818d 100755
--- a/tools/wire-cli.sh
+++ b/tools/wire-cli.sh
@@ -2302,22 +2302,30 @@ if [ "$action" = status ]; then
       if [ -n "$claude_root" ] && [ -f "$claude_hooks" ]; then st_item hooks.json "$claude_hooks" present
       else st_item hooks.json "${claude_hooks:-$HOME/.claude/plugins/installed_plugins.json}" missing; fi
       # 九支 hook 全靠這一個檔宣告，只看檔案在不在會漏掉「檔在、某支沒接進去」。
-      # 後來才加進來的 comment-scope.sh、lang-guard.sh、restart-gate.sh 與 write-guard.sh
-      # 是最可能漏的四支，所以各列一項。
-      if [ -f "$claude_hooks" ] && grep -qF 'comment-scope.sh' "$claude_hooks" 2>/dev/null
-      then st_item comment-scope "$claude_hooks" present
-      else st_item comment-scope "$claude_hooks" missing; fi
-      if [ -f "$claude_hooks" ] && grep -qF 'lang-guard.sh' "$claude_hooks" 2>/dev/null
-      then st_item lang-guard "$claude_hooks" present
-      else st_item lang-guard "$claude_hooks" missing; fi
-      if [ -f "$claude_hooks" ] && grep -qF 'restart-gate.sh' "$claude_hooks" 2>/dev/null
-      then st_item restart-gate "$claude_hooks" present
-      else st_item restart-gate "$claude_hooks" missing; fi
-      # write-guard.sh 接在兩個 matcher 上，三種模式各自是一件事，只驗腳本名會漏掉少接的那一個
-      for _m in stage review commit; do
-        if [ -f "$claude_hooks" ] && grep -qF "write-guard.sh\\\" $_m" "$claude_hooks" 2>/dev/null
-        then st_item "write-guard-$_m" "$claude_hooks" present
-        else st_item "write-guard-$_m" "$claude_hooks" missing; fi
+      # 每一支都列一項，一支都不省。reason 那行講的是「全部九支」，列舉卻只挑幾支的話，
+      # 拿這份輸出驗收接線的人會把沒列到的當成沒接——模型能力鎖就是這樣被誤判成沒接線的。
+      for _h in comment-scope lang-guard restart-gate skill-usage version-guard; do
+        if [ -f "$claude_hooks" ] && grep -qF "$_h.sh" "$claude_hooks" 2>/dev/null
+        then st_item "$_h" "$claude_hooks" present
+        else st_item "$_h" "$claude_hooks" missing; fi
+      done
+      # 一支腳本接在多個接線點時，每個點各自是一件事，只驗腳本名會漏掉少接的那一個。
+      # 三支這種腳本的接線點對照（左邊是項目名，右邊是 hooks.json 裡的子命令）：
+      #   write-guard   stage、review、commit
+      #   sdlc-gate     check（階段模型鎖）、wp-check prompt、wp-check skill（工作包歸屬）
+      #   session-timer start、mark
+      for _p in "write-guard-stage write-guard.sh\\\" stage" \
+                "write-guard-review write-guard.sh\\\" review" \
+                "write-guard-commit write-guard.sh\\\" commit" \
+                "sdlc-gate-check sdlc-gate.sh\\\" check" \
+                "sdlc-gate-wp-prompt sdlc-gate.sh\\\" wp-check prompt" \
+                "sdlc-gate-wp-skill sdlc-gate.sh\\\" wp-check skill" \
+                "session-timer-start session-timer.sh\\\" start" \
+                "session-timer-mark session-timer.sh\\\" mark"; do
+        _name=${_p%% *}; _pat=${_p#* }
+        if [ -f "$claude_hooks" ] && grep -qF "$_pat" "$claude_hooks" 2>/dev/null
+        then st_item "$_name" "$claude_hooks" present
+        else st_item "$_name" "$claude_hooks" missing; fi
       done ;;
 
     codex)
-- 
2.53.0


From c0ce4c5c3c30ca72ace335827725279b97b618e7 Mon Sep 17 00:00:00 2001
From: Jeffery <jiantw83@yahoo.com>
Date: Wed, 2 Sep 2026 14:57:04 +0800
Subject: [PATCH 4/9] =?UTF-8?q?chore(plugin=20=E7=89=88=E6=9C=AC):=20?=
 =?UTF-8?q?=E4=B8=89=E4=BB=BD=20manifest=20=E5=8D=87=E7=89=88=E8=87=B3=200?=
 =?UTF-8?q?.4.0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .claude-plugin/plugin.json | 2 +-
 .codex-plugin/plugin.json  | 2 +-
 plugin.json                | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 2490afb..a906dd9 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "jsc-hooks",
-  "version": "0.3.9",
+  "version": "0.4.0",
   "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟、寫入與提交閘門",
   "skills": "./skills",
   "author": {
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 76aec92..3d87763 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "hooks": "./hooks/codex-hooks.json",
   "name": "jsc-hooks",
-  "version": "0.3.9",
+  "version": "0.4.0",
   "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟、寫入與提交閘門",
   "skills": "./skills",
   "jsc": {
diff --git a/plugin.json b/plugin.json
index 2b486eb..f2ba5b3 100644
--- a/plugin.json
+++ b/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "jsc-hooks",
-  "version": "0.3.9",
+  "version": "0.4.0",
   "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟、寫入與提交閘門",
   "skills": "./skills/",
   "jsc": {
-- 
2.53.0


From a3ef20548905c352a006e68e494dbef533e75b60 Mon Sep 17 00:00:00 2001
From: Jeffery <jiantw83@yahoo.com>
Date: Wed, 2 Sep 2026 15:40:17 +0800
Subject: [PATCH 5/9] =?UTF-8?q?feat(=E7=8B=80=E6=85=8B=E5=9B=9E=E5=A0=B1):?=
 =?UTF-8?q?=20=E6=8A=80=E8=83=BD=E8=88=87=20hook=20=E7=9A=84=E5=9F=B7?=
 =?UTF-8?q?=E8=A1=8C=E7=B5=90=E6=9E=9C=E5=AF=AB=E9=80=B2=E6=9C=AC=E6=A9=9F?=
 =?UTF-8?q?=E4=BA=8B=E4=BB=B6=E6=B5=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

現行紀錄只記「被叫用」，欄位是 ts、cli、session、skill，沒有成敗也沒有
結束碼。跑完整輪的技能與開場就中止的技能，在紀錄裡長得一模一樣。hook
成功時更是完全不留紀錄，只有錯誤路徑會寫 wiki，而那條路徑刻意不自動觸發。

事件流走本機檔案，不直接寫 wiki。hook 每次提示都跑，網路寫入會拖垮宿主
CLI；失敗的 hook 自我回報還會疊出迴圈，既有的錯誤回報因此不接在失敗的
hook 上，這裡沿用同一條線。助理巡檢時排空、彙整、寫頁。

hook 端用 EXIT trap 接，一支只加一行。這幾支的 exit 點很多，階段閘門一支
就有五十幾個；逐點改要動到每一條判定路徑，而那些路徑正是閘門的判準，為了
加一行紀錄去動閘門，風險遠大於收益。trap 涵蓋每一條離開路徑，含中途失敗。

狀態預設由結束碼推，推不出來的由 hook 自己覆寫。相依版本檢查與兩道閘門有
這種情形：antigravity 走 deny JSON、kiro 只印警告，兩者擋下時結束碼都是 0，
單看結束碼會把擋下記成放行。

技能的 start 由既有的技能用量 hook 順手發，不必改任何技能文件。end 只能由
技能自己在收尾步驟寫——hook 觸發時技能的實際工作還在後面的模型輪次，看不到
成敗。有 start 沒有配對的 end，就是那一輪中止了。
---
 README.md               |   1 +
 hooks/assistant-gate.sh |   4 ++
 hooks/comment-scope.sh  |   1 +
 hooks/heartbeat.sh      |   1 +
 hooks/lang-guard.sh     |   1 +
 hooks/lib.sh            |  56 +++++++++++++++++
 hooks/restart-gate.sh   |   4 ++
 hooks/sdlc-gate.sh      |   1 +
 hooks/session-timer.sh  |   1 +
 hooks/skill-usage.sh    |   7 +++
 hooks/version-guard.sh  |   4 ++
 hooks/write-guard.sh    |   1 +
 references/behaviors.md |   2 +-
 tools/report-status.sh  | 130 ++++++++++++++++++++++++++++++++++++++++
 14 files changed, 213 insertions(+), 1 deletion(-)
 create mode 100755 tools/report-status.sh

diff --git a/README.md b/README.md
index e1975d3..4bf4bd4 100644
--- a/README.md
+++ b/README.md
@@ -171,6 +171,7 @@ Claude 由 `hooks/hooks.json` 自動接線九支 hook；其他 CLI 用 `hooks-in
 | `tools/scan-logs.sh` | 離線回填：解析 copilot、antigravity、codex 的原生日誌，把技能用量與階段界線補進 `$JSC_HOME`，重掃不重複 |
 | `tools/report-error.sh` | 失敗回報流程：把一筆 hook 或工具異常寫成 wiki 的 `ERROR_{HASH}`，並在 `ERROR_CONTENTS` 附上一列索引。目錄頁一律先讀回舊頁再附加新列、整頁寫回，不整頁覆蓋：只有 `wiki-get` 回 4（頁面真的不存在）才用範本建新頁，回 7（金鑰失效）或 8（其他 API 失敗）代表舊內容未知，放棄目錄頁寫入並以 exit 4 回報，免得拿範本蓋掉所有既有列。目錄頁那一列指向異常頁，連結一律寫成 `[{文字}]({連結})`，網址取 `jsc-gitea` 的 `gitea.sh wiki-url` 印出的那一個，不自己組路徑。寫進那一格之前，先把那個網址交給 `jsc-gitea` 的 `tools/link-check.sh` 驗一次，結束碼 0 才寫連結；`link-check.sh` 的路徑由已經解出來的 `gitea.sh` 推得，兩支同一個 tools 目錄。驗不過（含找不到 `link-check.sh`、`GITEA_HOST` 未設定回 3、金鑰失效回 7）就只在那一格留純文字頁名，那一列照寫、異常頁照寫、結束碼照舊，原因走 stderr——回報失敗不該再變成一次失敗。網址在異常頁寫成功之後才取：頁名的 hash 帶時間戳，每次回報都是全新的頁，寫進去之前查一定是 404，先查就只拿得到空字串。取不到網址時只印頁名，原因走 stderr，結束碼照舊回 0。wiki 位置分兩次解析：異常頁走 `jsc-gitea` 的 `gitea.sh wiki-repo ERROR`，目錄頁走 `gitea.sh wiki-repo CONTENTS`，兩者是兩個不同的存取庫。異常頁的存取庫解不出來就整支安靜降級；只有目錄頁的存取庫解不出來，就只寫異常頁、跳過目錄頁更新，仍回 exit 0。由操作者手動執行，或由 `hooks-install` 在 `wire-cli.sh` 回報 `status=failed` 時執行；**不接在失敗的 hook 上自動觸發**（hook 一律安靜 exit 0，自我回報會疊出迴圈） |
 | `tools/wire-cli.sh` | 單一 CLI 的 hook 生命週期，共四個用法。`{cli}` 是接線：先建立或更新 `$JSC_HOME/current/jsc-hooks` 指向目前這版 plugin，接著把對應的設定編輯、包裝別名安裝、hook 檔建立成穩定路徑，皆以 `<!-- jsc-hooks -->`（或 `# jsc-hooks`）標記整段重寫，重跑等同先移除再重裝；寫完每個檔案會重讀驗證位置正確才回報成功（codex 的 `notify` 必須是根層鍵、`.codex-plugin/plugin.json` 的 matcher 必須是 `Bash`、copilot 必須是小寫 `skill` 且沒有第二種大小寫的事件名、antigravity 的 matcher 必須帶錨點 `^view_file$` 且有 `PreInvocation`、kiro 的 agent JSON 必須成對且 `hooks`、`resources`、`tools` 在最上層並含兩層 `skill://` glob），也會確認寫入路徑能解到既有腳本。matcher 本身要單獨驗：鍵在、matcher 卻錯的形態最難查，回報會說接好了，實際一次都不會被叫用。檔案系統不能建立 symlink 時，會明確回報並退回目前根目錄，不會靜默寫出壞路徑。`status=wired\|degraded\|skipped\|failed` 回報接線結果。`purge {cli}` 是移除：把該 CLI 的**所有** hook 清掉，含非 jsc 的第三方項目，動到的檔案先原樣備份到 `$JSC_HOME/backup/hooks/{cli}/{yyyyMMdd_HHmmss}/`，備份失敗就不移除；移除標記段落時會先去掉標記行前後空白，所以縮排或尾端補空白的 jsc 區塊一樣會移除；移除後重讀驗證，驗不過自動還原備份，以 `status=purged\|skipped\|failed` 回報。`smoke {cli}` 是執行期冒煙測試：九支 hook 的每個接線模式各跑一次，非零退出即為錯誤，另外把五支 CLI 的真實負載各餵進 `skill-name.sh` 一次驗技能名解析、四種阻擋形態各驗一次 `deny.sh`，再把那些負載直接餵進 `restart-gate.sh` 驗「解析→判定→輸出形態」整條串得起來（含 fail-open、豁免放行與 kiro 的注入路徑）——前兩組分開看都會顯示正常，中間接不上照樣是全程放行，那正是先前三支 CLI 失效的樣子；另外用一份暫時的 `$JSC_HOME` 狀態檔把模型來源與階段鎖、工作包歸屬、部署後重啟閘門與寫入提交閘門的每條判定路徑各跑一次並比對結束碼（模型來源的每個案例各自指定 CLI 代號，不跟著這一輪接線的 CLI 走——偵測鏈已依 CLI 分流；「不知道能力就擋下」的三種情形連訊息裡的逃生門一起驗，只比結束碼的話訊息漏掉逃生門也是綠燈），再用一份暫時的 `HOME`（假的 `installed_plugins.json` 與各 plugin 的 manifest）把 `version-guard.sh` 相依版本檢查的每條路徑跑一次——相依落後的擋人與訊息內容、相等與超前的放行、豁免技能在相依落後時照樣放行、四種 fail-open、逃生門，另加一條回歸：多行縮排的 manifest，`jsc.requires` 的最後一個鍵也要解得到。驗的是判定結果本身，不只是腳本跑得完（例外有四個：`sdlc-gate.sh check` 的 exit 2 是階段鎖的設計行為，`comment-scope.sh`、`lang-guard.sh` 掃描模式與 `write-guard.sh` 三種模式的 exit 2 是命中違規的設計行為——`sweep` 在髒工作區本來就會回 2，`write-guard.sh` 在機器剛好鎖在 `plan` 階段時也會回 2，都不算 hook 壞掉），以 `status=ok\|failed` 回報。**結果行數由腳本自己數、自己斷言**：`status=` 之後緊接一行 `lines<TAB>{數量}`，那是其後 `[jsc]` 結果行的實際條數，與腳本內逐類宣告的預期條數比對，不符就回非零。判定路徑增減時只改腳本裡的預期值，散文一律引用這一行，不另外抄一份數字。`status {cli}` 是唯讀盤點：只讀設定檔判斷段落與 matcher 對不對，不寫檔也不執行 hook，claude、codex、copilot、antigravity 回 `wired`，kiro 回 `degraded` 並在 `reason` 講明那是 CLI 限制；每個接線點印一行 `item<TAB>{項目}<TAB>{路徑}<TAB>{present\|missing\|unverified}`，也會把帶版號快取路徑、開發存取庫路徑與不存在的腳本列為缺項。狀態有三格不是兩格：`unverified` 是「這一項驗不了」，只有 `missing` 才算缺項——`kiro-cli agent validate` 在沒登入時印的是環境問題，不是這個檔案的問題，報 `present` 會讓沒驗到的東西看起來像通過，報 `missing` 會把沒登入算成接線缺漏；`status claude` 讀 Claude Code 實際載入的 `installed_plugins.json`，不再檢查目前腳本旁邊那份 `hooks.json`。體檢類技能（`/jsc-cli:doctor`）只能用這個子命令，另外三個都會動到環境；那道限制另有程式層把關，`JSC_READONLY=1` 之下只准 `status` 與 `smoke`，`purge` 與接線一律以 exit 6 拒絕並回報 `status=readonly`，環境不會被動到 |
+| `tools/report-status.sh` | 技能與 hook 的執行狀態事件流，寫進 `$JSC_HOME/usage/events.jsonl`，一次一行。`skill-start`、`skill-end`、`hook-end` 三個記錄子命令；`drain` 印出上次排空之後的新事件（位移存在 `usage/scan-state/events.offset`，檔案比位移小就當作輪替過、從頭讀，不比對 inode——五支 CLI 與容器裡的行程看到的 inode 不保證一致）；`rotate` 超過 5 MiB 就改名成 `.1` 並把位移歸零，只留一份舊的。`status` 是 `ok`、`blocked`、`failed`、`degraded`、`aborted` 五選一。**三個記錄子命令一律回 0，寫檔失敗也是 0**：回報機制自己壞掉，不可以讓被回報的東西跟著壞——hook 的結束碼是閘門的判準，被記錄動到就等於閘門行為被記錄改寫。參數檢查是例外，那是呼叫端的程式錯誤，寫進去只會汙染事件流，所以以 2 擋在記錄之前。本檔不讀 stdin：技能由 Bash 呼叫它，stdin 可能是還沒關閉的管線，讀下去會卡住宿主，所有資訊一律走參數。輪替不放在每次寫入，那等於每次提示多一次系統呼叫；改由巡檢排空之後呼叫。為什麼不直接寫 wiki：hook 每次提示都跑，網路寫入會拖垮宿主 CLI，而且失敗的 hook 自我回報會疊出迴圈，`report-error.sh` 因此刻意不接在失敗的 hook 上，這裡沿用同一條線 |
 | `tools/scan-hook-errors.sh` | 掃 CLI 原生紀錄找 hook 的執行期錯誤（接線寫對、跑起來出錯）。只有 claude 有 hook 結果紀錄，掃 `~/.claude/projects/**/*.jsonl` 的 `hook_non_blocking_error` 與非空 `hookErrors`；codex、copilot、antigravity、kiro 沒有等價紀錄，一律回報 `unavailable` 並指向 `wire-cli.sh smoke {cli}`。每筆錯誤附加一行 JSON 到 `$JSC_HOME/errors/hooks.jsonl`，`jsc` 欄位標明是不是 jsc 自己的 hook（第三方 hook 的錯誤只回報，不由 jsc 修正）；去重與 `scan-logs.sh` 同法，重掃只讀新增段落，以 `status=clean\|errors\|unavailable` 回報 |
 
 ## 失敗回報範本
diff --git a/hooks/assistant-gate.sh b/hooks/assistant-gate.sh
index eddb6b1..d6cec18 100755
--- a/hooks/assistant-gate.sh
+++ b/hooks/assistant-gate.sh
@@ -120,6 +120,7 @@ if [ "${JSC_ASSISTANT_GATE:-}" = "off" ]; then
 fi
 
 HERE=$(dirname "$0"); . "$HERE/lib.sh"
+hook_trace "assistant-gate ${1:-}"
 
 read_stdin
 
@@ -200,5 +201,8 @@ esac
   printf '%s\n' "$second"
   printf '仍可使用：/jsc-assist:*、/jsc-hooks:repair、/jsc-hooks:hooks-install、/jsc-cli:doctor、/jsc-cli:setup、/jsc-cli:deploy、/jsc-cli:models、/jsc-gitea:wiki、/jsc-ask:ask、/jsc-git:commit、/jsc-git:pr（啟動助理與修環境這兩條路徑要永遠走得通，包括它們轉呼叫的下一層）\n'
   printf '確定要略過閘門：JSC_ASSISTANT_GATE=off\n'
+# 這條路徑是「已經擋下」，但輸出形態依 CLI 而定：antigravity 走 stdout 的 deny JSON、
+# kiro 只印警告，兩者的結束碼都是 0。不覆寫狀態的話，事件流會把擋下記成放行。
+JSC_EVENT_STATUS=blocked
 } | sh "$HERE/deny.sh" "$(cli_name)"
 exit $?
diff --git a/hooks/comment-scope.sh b/hooks/comment-scope.sh
index e67f49d..6963885 100755
--- a/hooks/comment-scope.sh
+++ b/hooks/comment-scope.sh
@@ -25,6 +25,7 @@
 set -u
 
 . "$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)/lib.sh" 2>/dev/null || true
+command -v hook_trace >/dev/null 2>&1 && hook_trace "comment-scope ${1:-}"
 
 [ "${JSC_COMMENT_SCOPE:-on}" = "off" ] && exit 0
 
diff --git a/hooks/heartbeat.sh b/hooks/heartbeat.sh
index beac7a2..8dea014 100755
--- a/hooks/heartbeat.sh
+++ b/hooks/heartbeat.sh
@@ -75,6 +75,7 @@
 #   2。這一點的後果與 restart-gate.sh 不同：那支接在 PreToolUse 上，回 2 等於無聲擋下每一次
 #   技能呼叫；這支沒接任何 hook，回 2 只會讓呼叫端收到「心跳判不出來」，擋不到任何人。
 HERE=$(dirname "$0"); . "$HERE/lib.sh"
+hook_trace "heartbeat ${1:-}"
 
 # 這支永遠不讀標準輸入，但 session_id() 會去看 STDIN_JSON。先設成空字串，讓它直接走環境
 # 變數那條路，不會因為變數沒定義而拿到不確定的值。
diff --git a/hooks/lang-guard.sh b/hooks/lang-guard.sh
index e40e0e8..67c45c9 100755
--- a/hooks/lang-guard.sh
+++ b/hooks/lang-guard.sh
@@ -32,6 +32,7 @@
 set -u
 
 . "$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)/lib.sh" 2>/dev/null || true
+command -v hook_trace >/dev/null 2>&1 && hook_trace "lang-guard ${1:-}"
 
 [ "${JSC_LANG_GUARD:-on}" = "off" ] && exit 0
 
diff --git a/hooks/lib.sh b/hooks/lib.sh
index a18b50d..9eebf2f 100755
--- a/hooks/lib.sh
+++ b/hooks/lib.sh
@@ -263,3 +263,59 @@ cli_bin() { # $1=CLI 代號
 
 now_epoch() { date +%s; }
 now_iso() { date -u +%Y-%m-%dT%H:%M:%SZ; }
+
+# --- 執行狀態事件流 ---
+#
+# 每支 hook 與每支技能的執行結果都寫進 $JSC_HOME/usage/events.jsonl，助理巡檢時排空。
+# 為什麼不直接寫 wiki：hook 每次提示都跑，網路寫入會拖垮宿主 CLI；而且失敗的 hook
+# 自我回報會疊出迴圈，report-error.sh 因此刻意不接在失敗的 hook 上，這裡沿用同一條線。
+#
+# 兩條硬規則，違反哪一條這套機制都會反過來害到被它記錄的東西：
+#   一、一行一次 printf，且長度壓在 4096 位元組內。五支 CLI 併發時，單次 O_APPEND
+#       寫入才不會互相插隊；拆成多次 printf 就會交錯成無法解析的行。detail 因此要截斷。
+#   二、寫入失敗一律吞掉，不得改變呼叫端的結束碼。回報機制自己壞掉，不可以讓被回報的
+#       東西跟著壞——hook 的結束碼是閘門的判準，被記錄動到就等於閘門行為被記錄改寫。
+
+# JSON 字串值跳脫：只處理反斜線、雙引號與會拆行的字元。這三類不處理就會寫出解析不了的行。
+json_escape() {
+  printf '%s' "$1" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' | tr -d '\n\r\t'
+}
+
+# emit_event <kind> <name> <phase> <status> <exit> [ms] [detail]
+emit_event() {
+  _ek="$1"; _en="$2"; _ep="$3"; _es="$4"; _ex="$5"; _em="${6:-}"; _ed="${7:-}"
+  # detail 截到 200 字元：長內容是硬規則一的主要威脅，來源不可信就先砍再寫。
+  [ -n "$_ed" ] && _ed=$(printf '%s' "$_ed" | cut -c1-200)
+  _ems=""
+  [ -n "$_em" ] && _ems=$(printf ',"ms":%s' "$_em")
+  _eds=""
+  [ -n "$_ed" ] && _eds=$(printf ',"detail":"%s"' "$(json_escape "$_ed")")
+  printf '{"ts":"%s","cli":"%s","session":"%s","kind":"%s","name":"%s","phase":"%s","status":"%s","exit":%s%s%s}\n' \
+    "$(now_iso)" "$(cli_name)" "$(session_id)" "$_ek" "$(json_escape "$_en")" \
+    "$_ep" "$_es" "$_ex" "$_ems" "$_eds" \
+    >> "$JSC_HOME/usage/events.jsonl" 2>/dev/null || true
+}
+
+# 結束碼推 status。各 hook 的 2 一律是「擋下」的設計行為，不是壞掉。
+hook_status_of() {
+  case "$1" in
+    0) printf ok ;;
+    2) printf blocked ;;
+    *) printf failed ;;
+  esac
+}
+
+# hook_trace <名稱> — 裝一個 EXIT trap，腳本不論從哪一個 exit 離開都記一筆。
+#
+# 為什麼用 trap 而不是逐點改：這幾支 hook 的 exit 點很多，sdlc-gate.sh 一支就有五十幾個。
+# 逐點換成「記錄再離開」要改動每一條判定路徑，而那些路徑正是閘門的判準；為了加一行紀錄
+# 去動閘門，風險遠大於收益。trap 只加一行，且涵蓋每一條離開路徑，含 set -e 的中途失敗。
+#
+# 狀態預設由結束碼推。推不出來的由 hook 自己在離開前設 JSC_EVENT_STATUS 覆寫——
+# version-guard.sh 就有這種情形：antigravity 走 stdout 的 deny JSON、kiro 只印警告，
+# 兩者擋下時結束碼都是 0，單看結束碼會把「已經擋下」記成「放行」。
+hook_trace() {
+  JSC_EVENT_NAME="$1"
+  JSC_EVENT_STATUS=""
+  trap '_rc=$?; emit_event hook "$JSC_EVENT_NAME" end "${JSC_EVENT_STATUS:-$(hook_status_of "$_rc")}" "$_rc"' EXIT
+}
diff --git a/hooks/restart-gate.sh b/hooks/restart-gate.sh
index 4264ed5..21f1277 100755
--- a/hooks/restart-gate.sh
+++ b/hooks/restart-gate.sh
@@ -120,6 +120,7 @@
 #
 # 逃生門：JSC_RESTART_GATE=off 完全略過這道閘門。
 HERE=$(dirname "$0"); . "$HERE/lib.sh"
+hook_trace "restart-gate ${1:-}"
 
 STATE_DIR="$JSC_HOME/restart-required.d"
 # 舊格式的單一狀態檔。只為過渡而讀，可移除的時機見檔頭「舊檔相容」。
@@ -249,5 +250,8 @@ info=""
   printf '重新啟動：結束 %s 再重新開啟一次，狀態檔 %s 會在新工作階段開始時自動清除。\n' \
     "$bin" "$state"
   printf '仍可使用：/jsc-cli:deploy、/jsc-hooks:hooks-install、/jsc-hooks:repair、/jsc-gitea:wiki、/jsc-log:worklog、/jsc-log:learn、/jsc-meta:*、/jsc-ask:ask、/jsc-git:pr、/jsc-git:commit（部署後的異動報告與工作日誌要寫得完，hook 壞掉也要修得回來）　｜　確定要略過閘門：JSC_RESTART_GATE=off\n'
+# 這條路徑是「已經擋下」，但輸出形態依 CLI 而定：antigravity 走 stdout 的 deny JSON、
+# kiro 只印警告，兩者的結束碼都是 0。不覆寫狀態的話，事件流會把擋下記成放行。
+JSC_EVENT_STATUS=blocked
 } | sh "$HERE/deny.sh" "$(cli_name)"
 exit $?
diff --git a/hooks/sdlc-gate.sh b/hooks/sdlc-gate.sh
index d8db948..8a14c50 100755
--- a/hooks/sdlc-gate.sh
+++ b/hooks/sdlc-gate.sh
@@ -123,6 +123,7 @@
 # 刻意的例外——鎖存在且不合規時 exit 2 擋下。只用提示注入的話模型可以無視，閘門形同虛設。
 # 無鎖、或資料不足無法判定時，仍照舊 exit 0 安靜降級。
 HERE=$(dirname "$0"); . "$HERE/lib.sh"
+hook_trace "sdlc-gate ${1:-}"
 # 只有需要 stdin JSON 的子命令才讀它：模型判定要 transcript_path，session 判定要 session_id。
 # wp-lock、wp-unlock、wp-claim、wp-unclaim、wp-report 兩者都不需要，而 read_stdin 在標準輸入
 # 是管線又沒人關閉時會一直等——工具腳本（jsc-sdlc 的 wp-gate.sh）轉呼叫這些子命令時就這樣整支
diff --git a/hooks/session-timer.sh b/hooks/session-timer.sh
index 3dcf048..273ffb4 100755
--- a/hooks/session-timer.sh
+++ b/hooks/session-timer.sh
@@ -25,6 +25,7 @@
 # 清除的範圍是「跑到這一支腳本的那個 CLI 自己那一份狀態檔」，由 restart-gate.sh clear 認定，
 # 這裡不必也不能過問：這個工作階段開始的只有一支 CLI，別支沒重啟，閘門要留著。
 HERE=$(dirname "$0"); . "$HERE/lib.sh"
+hook_trace "session-timer ${1:-}"
 read_stdin
 sid=$(session_id)
 
diff --git a/hooks/skill-usage.sh b/hooks/skill-usage.sh
index 91cc26d..5344873 100755
--- a/hooks/skill-usage.sh
+++ b/hooks/skill-usage.sh
@@ -12,6 +12,7 @@
 #   唯一的非零來源同 session-timer.sh：本檔以 `. "$HERE/lib.sh"` 載入，沒有接 `|| true`，
 #   lib.sh 讀不到時 sh 會就地結束並回 2。
 HERE=$(dirname "$0"); . "$HERE/lib.sh"
+hook_trace "skill-usage ${1:-}"
 read_stdin
 skill="${JSC_SKILL:-$(json_str skill)}"
 [ -n "$skill" ] || exit 0
@@ -25,4 +26,10 @@ if [ -n "$last" ]; then
     "$ts" "$cli" "$sid" "$last" "$skill" >> "$JSC_HOME/usage/chains.jsonl"
 fi
 printf '%s' "$skill" > "$last_f"
+
+# 技能的 start 事件在這裡發，不必改任何 SKILL.md：這支接在技能指示載入之後，那一刻
+# 就是「技能開始跑」。end 只能由技能自己在收尾步驟寫——本 hook 觸發時，技能的實際工作
+# 還在後面的模型輪次，看不到成敗。有 start 沒有配對的 end，就是那一輪中止了。
+emit_event skill "$skill" start ok 0
+
 exit 0
diff --git a/hooks/version-guard.sh b/hooks/version-guard.sh
index 54896d4..23a68bd 100755
--- a/hooks/version-guard.sh
+++ b/hooks/version-guard.sh
@@ -101,6 +101,7 @@
 #                             再呼叫一次 report，這裡刻意不混印，免得 cut 取值被表格內容打亂。
 #                             recommend 只讀不擋，永遠 exit 0：判定結果只看那一行的第二欄。
 HERE=$(dirname "$0"); . "$HERE/lib.sh"
+hook_trace "version-guard ${1:-}"
 
 REG="$HOME/.claude/plugins/installed_plugins.json"
 MK="$HOME/.claude/plugins/known_marketplaces.json"
@@ -354,6 +355,9 @@ deny() { # $1=訊息
   { printf '[jsc][版本檢查][ERR]：%s\n' "$1"
     printf '更新指令：%s\n' "$(update_cmd "$domain")"
     printf '更新整組：/jsc-cli:deploy　｜　確定要略過檢查：JSC_VERSION_GUARD=off\n'
+# 這條路徑是「已經擋下」，但輸出形態依 CLI 而定：antigravity 走 stdout 的 deny JSON、
+# kiro 只印警告，兩者的結束碼都是 0。不覆寫狀態的話，事件流會把擋下記成放行。
+JSC_EVENT_STATUS=blocked
   } | sh "$HERE/deny.sh" "$(cli_name)"
   exit $?
 }
diff --git a/hooks/write-guard.sh b/hooks/write-guard.sh
index 8615090..b6345a0 100755
--- a/hooks/write-guard.sh
+++ b/hooks/write-guard.sh
@@ -75,6 +75,7 @@ HERE=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
 # 的 exit 2——而 PreToolUse 的 exit 2 正是「擋下」，等於每一次寫檔與提交都被無聲擋死。
 [ -r "$HERE/lib.sh" ] || exit 0
 . "$HERE/lib.sh"
+hook_trace "write-guard ${1:-}"
 # lib.sh 沒載到時這個變數就沒人設，下面兩個模式都要用它組狀態檔路徑，補一份同樣的預設值。
 JSC_HOME="${JSC_HOME:-$HOME/.jsc}"
 
diff --git a/references/behaviors.md b/references/behaviors.md
index 2b64c64..47a3abc 100644
--- a/references/behaviors.md
+++ b/references/behaviors.md
@@ -10,7 +10,7 @@
 | 關鍵步驟 | 取得 CLI 清單（呼叫端交來的優先，沒有才自己跑 `detect-clis.sh`）、第一支 CLI 單獨跑完整條管線（它負責更新共用的 `$JSC_HOME/current/jsc-hooks` 連結）、其餘 CLI 一支一個 sub agent 並行、每支 CLI 依序走 purge、接線、status、smoke、scan 五道關卡、讀每道關卡自己印的第一行判定、任一關卡出錯就寫 `ERROR_{HASH}` 並轉給 `jsc-hooks:repair`（異常頁與索引目錄頁分屬兩個存取庫，各自解析；只解不出目錄頁的存取庫時異常頁照寫、索引跳過，回報要講明那一頁沒被索引）、目錄頁那一列指向異常頁的連結一律寫成 `[{文字}]({連結})`，網址取 `gitea.sh wiki-url`，寫進去之前先過 `jsc-gitea/tools/link-check.sh`，結束碼 0 才寫連結、驗不過那一格只留純文字頁名而那一列與異常頁照寫（`report-error.sh` 內部做完，結束碼不變）、逐 CLI 回報五道關卡的結果 |
 | 外部呼叫 | `tools/wire-cli.sh purge`、`tools/wire-cli.sh {cli}`、`tools/wire-cli.sh status`、`tools/wire-cli.sh smoke`、`tools/scan-hook-errors.sh`、`tools/report-error.sh`、`jsc-cli/tools/detect-clis.sh`、`jsc-hooks:repair` 技能、`jsc-gitea:wiki`（寫 `ERROR_{HASH}` 時經 `report-error.sh`）、`jsc-gitea/tools/gitea.sh wiki-url` 與 `jsc-gitea/tools/link-check.sh`（同樣經 `report-error.sh`，取目錄頁那一列的網址並驗它連得到）；接線腳本內部另呼叫 `hooks/skill-name.sh` 與 `hooks/deny.sh` 做冒煙斷言 |
 | 完成條件 | 每一支偵測到的 CLI 都有五道關卡各一行判定，沒有任何一道回結束碼 2，smoke 的 `lines` 條數與它自己的斷言相符，claude、codex、copilot、antigravity 回 `wired` 而 kiro 回 `degraded`（CLI 擋不下技能叫用），四支非 claude 的執行期錯誤掃描一律據實回 `unavailable`，各 CLI 的形狀與觸發驗證等級分開寫進回報（codex、antigravity、kiro 形狀實證，copilot 形狀未證；kiro 觸發部分實證，其餘未驗證），每一筆錯誤都帶一個 `ERROR_{HASH}` 結果與一條對 `develop` 的修正 PR 連結，而且目錄頁那一列的連結驗不過時，回報要講明那一列只有純文字頁名、沒有連結 |
-| 可驗證跡象 | 各 CLI 的設定檔多出 jsc 段落：codex 的 `config.toml` 標記段落、`hooks/codex-hooks.json`（從 `hooks/hooks.json` 推導，matcher `Skill` 換成 `Bash`）與 `.codex-plugin/plugin.json` 指過去的 `hooks` 路徑字串、copilot 的 `~/.copilot/settings.json` 頂層 `hooks` 鍵（matcher `skill`，合併不覆寫，`enabledPlugins` 與第三方條目原樣保留）與 `$COPILOT_HOME` 底下的指引檔、antigravity 的 `~/.gemini/config/hooks.json` 的 `jsc` 段落（`PreToolUse` 為 Grouped、matcher `^view_file$`，`PreInvocation` 維持 Flat）、kiro 的 `~/.kiro/agents/jsc.json`（`hooks` 為 `agentSpawn`、`userPromptSubmit`、`stop` 三個合法事件加 `timeout_ms`、兩層 `skill://` glob 的 `resources`、明列的 `tools`，並通過 `kiro-cli agent validate`）與 `~/.kiro/settings/cli.json` 的 `chat.defaultAgent=jsc`；四支非 claude 的接線命令都以 `JSC_CLI={代號}` 前綴自帶 CLI 代號，缺了它兩道閘門解不出技能名、一律安靜放行，所以 `status` 把它列成單獨一項；另有 `$JSC_HOME/current/jsc-hooks` 符號連結建立或更新、`$JSC_HOME/backup/hooks/{cli}/{時間戳}/` 留下 purge 前的備份、出錯時 wiki 多一頁 `ERROR_{HASH}`（落在 `JSC_WIKI_REPO_ERROR` 解出的存取庫）並在索引目錄頁補一列（落在 `JSC_WIKI_REPO_CONTENTS` 解出的另一個存取庫，那一列的第 2 格寫成 `[{頁名}]({絕對網址})`，網址取自 `gitea.sh wiki-url` 且已經過 `link-check.sh` 驗到結束碼 0；驗不過那一格只有純文字頁名，`report-error.sh` 在 stderr 留一行 `[jsc]` 講明是哪一種原因）、修正路徑留下一條對 `develop` 的 PR |
+| 可驗證跡象 | 各 CLI 的設定檔多出 jsc 段落：codex 的 `config.toml` 標記段落、`hooks/codex-hooks.json`（從 `hooks/hooks.json` 推導，matcher `Skill` 換成 `Bash`）與 `.codex-plugin/plugin.json` 指過去的 `hooks` 路徑字串、copilot 的 `~/.copilot/settings.json` 頂層 `hooks` 鍵（matcher `skill`，合併不覆寫，`enabledPlugins` 與第三方條目原樣保留）與 `$COPILOT_HOME` 底下的指引檔、antigravity 的 `~/.gemini/config/hooks.json` 的 `jsc` 段落（`PreToolUse` 為 Grouped、matcher `^view_file$`，`PreInvocation` 維持 Flat）、kiro 的 `~/.kiro/agents/jsc.json`（`hooks` 為 `agentSpawn`、`userPromptSubmit`、`stop` 三個合法事件加 `timeout_ms`、兩層 `skill://` glob 的 `resources`、明列的 `tools`，並通過 `kiro-cli agent validate`）與 `~/.kiro/settings/cli.json` 的 `chat.defaultAgent=jsc`；四支非 claude 的接線命令都以 `JSC_CLI={代號}` 前綴自帶 CLI 代號，缺了它兩道閘門解不出技能名、一律安靜放行，所以 `status` 把它列成單獨一項；另有 `$JSC_HOME/current/jsc-hooks` 符號連結建立或更新、`$JSC_HOME/backup/hooks/{cli}/{時間戳}/` 留下 purge 前的備份、出錯時 wiki 多一頁 `ERROR_{HASH}`（落在 `JSC_WIKI_REPO_ERROR` 解出的存取庫）並在索引目錄頁補一列（落在 `JSC_WIKI_REPO_CONTENTS` 解出的另一個存取庫，那一列的第 2 格寫成 `[{頁名}]({絕對網址})`，網址取自 `gitea.sh wiki-url` 且已經過 `link-check.sh` 驗到結束碼 0；驗不過那一格只有純文字頁名，`report-error.sh` 在 stderr 留一行 `[jsc]` 講明是哪一種原因）、修正路徑留下一條對 `develop` 的 PR 。接線完成後 `$JSC_HOME/usage/events.jsonl` 會逐行長出 `{kind:hook}` 事件，每支 hook 每次執行一筆，欄位含 `status` 與實際結束碼；跑過技能之後另有 `{kind:skill,phase:start}`。事件寫不進去不影響任何 hook 的結束碼 |
 
 ## repair
 
diff --git a/tools/report-status.sh b/tools/report-status.sh
new file mode 100755
index 0000000..9c412e4
--- /dev/null
+++ b/tools/report-status.sh
@@ -0,0 +1,130 @@
+#!/usr/bin/env sh
+# report-status.sh — 技能與 hook 的執行狀態事件流。
+#
+# 為什麼要有這支：現行 usage/skills.jsonl 只記「被叫用」，欄位是 {ts,cli,session,skill}，
+# 沒有成敗、沒有結束碼。跑完整輪的技能與開場就中止的技能，在紀錄裡長得一模一樣。
+# hook 成功時更是完全不留紀錄，只有錯誤路徑會寫 wiki，而那條路徑刻意不自動觸發。
+#
+# 為什麼不直接寫 wiki：hook 每次提示都跑，網路寫入會拖垮宿主 CLI；失敗的 hook 自我回報
+# 還會疊出迴圈。所以一律先寫本機事件流，助理巡檢時排空、彙整、寫 MONITOR 頁。
+#
+# 用法:
+#   report-status.sh skill-start <名稱>
+#   report-status.sh skill-end   <名稱> <status> [結束碼] [detail]
+#   report-status.sh hook-end    <名稱> <status> <結束碼> [detail]
+#   report-status.sh drain                       # 印出上次排空之後的新事件
+#   report-status.sh rotate                      # 超過上限就輪替，只留一份舊的
+#
+# <名稱>: 技能寫 {domain}:{skill}，hook 寫 {腳本檔名} 加子命令，例如 sdlc-gate check。
+# <status>: ok、blocked、failed、degraded、aborted 五選一。
+#   ok       完成條件全部達成
+#   blocked  被閘門或前置條件擋下，沒有做事
+#   failed   做到一半失敗
+#   degraded 做完了但有部分沒達成
+#   aborted  使用者中止，或前提不成立而主動停止
+#
+# 規則:
+#   - 三個記錄子命令一律回 0，寫檔失敗也是 0。回報機制自己壞掉，不可以讓被回報的東西
+#     跟著壞——hook 的結束碼是閘門的判準，被記錄動到就等於閘門行為被記錄改寫。
+#     參數檢查是例外：那是呼叫端的程式錯誤，寫進去只會汙染事件流，所以先擋下來。
+#   - 本檔不讀 stdin。技能由 Bash 呼叫它，stdin 可能是還沒關閉的管線，讀下去會卡住宿主。
+#     所有資訊一律走參數。
+#   - 輪替不放在每次寫入。每次提示都寫事件，順手 stat 一次檔案就是每次提示多一次系統呼叫；
+#     改由巡檢排空之後呼叫 rotate，成本落在本來就週期性執行的地方。
+#
+# 結束碼: 0=成功（記錄子命令一律 0） 2=用法錯誤 3=drain 沒有新事件
+set -eu
+
+HERE=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+# lib.sh 在同一個存取庫，不是跨 plugin 依賴。hook 必須自足，事件寫入的函式因此留在 lib.sh，
+# 這支只是把它包成命令列介面給技能用。
+STDIN_JSON=""
+. "$HERE/../hooks/lib.sh"
+
+EVENTS="$JSC_HOME/usage/events.jsonl"
+OFFSET="$JSC_HOME/usage/scan-state/events.offset"
+MAX_BYTES=5242880
+
+usage() {
+  cat >&2 <<'EOF'
+用法:
+  report-status.sh skill-start <名稱>
+  report-status.sh skill-end   <名稱> <status> [結束碼] [detail]
+  report-status.sh hook-end    <名稱> <status> <結束碼> [detail]
+  report-status.sh drain
+  report-status.sh rotate
+
+status: ok、blocked、failed、degraded、aborted
+結束碼: 0=成功 2=用法錯誤 3=drain 沒有新事件
+EOF
+  exit 2
+}
+
+valid_status() {
+  case "$1" in
+    ok|blocked|failed|degraded|aborted) ;;
+    *) echo "[jsc][狀態回報][ERR]：status 須為 ok、blocked、failed、degraded、aborted 五選一，收到「$1」。" >&2; exit 2 ;;
+  esac
+}
+
+valid_exit() {
+  case "$1" in
+    ''|*[!0-9]*) echo "[jsc][狀態回報][ERR]：結束碼須為非負整數，收到「$1」。" >&2; exit 2 ;;
+  esac
+}
+
+cmd="${1:-}"; [ -n "$cmd" ] || usage
+shift || true
+
+case "$cmd" in
+  skill-start)
+    name="${1:-}"; [ -n "$name" ] || usage
+    # start 沒有成敗可言，狀態欄固定 ok、結束碼固定 0。判讀靠的是「有沒有配對的 end」：
+    # 有 start 沒 end 就是中止，那正是現行紀錄分不出來的那一種。
+    emit_event skill "$name" start ok 0
+    ;;
+  skill-end)
+    name="${1:-}"; status="${2:-}"
+    [ -n "$name" ] && [ -n "$status" ] || usage
+    valid_status "$status"
+    code="${3:-0}"; valid_exit "$code"
+    emit_event skill "$name" end "$status" "$code" "" "${4:-}"
+    ;;
+  hook-end)
+    name="${1:-}"; status="${2:-}"; code="${3:-}"
+    [ -n "$name" ] && [ -n "$status" ] && [ -n "$code" ] || usage
+    valid_status "$status"; valid_exit "$code"
+    emit_event hook "$name" end "$status" "$code" "" "${4:-}"
+    ;;
+  drain)
+    [ -f "$EVENTS" ] || exit 3
+    size=$(wc -c < "$EVENTS" 2>/dev/null || echo 0)
+    old=0
+    [ -f "$OFFSET" ] && old=$(cat "$OFFSET" 2>/dev/null || echo 0)
+    case "$old" in ''|*[!0-9]*) old=0 ;; esac
+    # 檔案比已存位移還小就是輪替過，從頭讀。不比對 inode：五支 CLI 與容器裡的行程
+    # 看到的 inode 不保證一致，用大小判斷才在每個環境都成立。
+    [ "$size" -lt "$old" ] && old=0
+    [ "$size" -eq "$old" ] && exit 3
+    mkdir -p "$(dirname "$OFFSET")" 2>/dev/null || true
+    # tail -c +N 從第 N 個位元組起（1 起算），所以位移要加一。
+    # 不用 dd bs=1 skip=：那是一個位元組一次系統呼叫，位移到了幾 MB 就是幾百萬次，
+    # 每輪巡檢都排空一次的話會慢到不能用。
+    tail -c "+$((old + 1))" "$EVENTS" 2>/dev/null || true
+    printf '%s' "$size" > "$OFFSET" 2>/dev/null || true
+    ;;
+  rotate)
+    [ -f "$EVENTS" ] || exit 0
+    size=$(wc -c < "$EVENTS" 2>/dev/null || echo 0)
+    if [ "$size" -gt "$MAX_BYTES" ]; then
+      mv "$EVENTS" "$EVENTS.1" 2>/dev/null || true
+      : > "$EVENTS" 2>/dev/null || true
+      # 位移歸零：新檔從頭算起，不歸零的話下一次 drain 會跳過開頭那一段。
+      printf '0' > "$OFFSET" 2>/dev/null || true
+      printf '已輪替：%s -> %s.1（原大小 %s 位元組）\n' "$EVENTS" "$EVENTS" "$size"
+    fi
+    ;;
+  *) usage ;;
+esac
+
+exit 0
-- 
2.53.0


From 106922d530279ad48c634c26a740029bb219b06c Mon Sep 17 00:00:00 2001
From: Jeffery <jiantw83@yahoo.com>
Date: Wed, 2 Sep 2026 15:40:17 +0800
Subject: [PATCH 6/9] =?UTF-8?q?chore(plugin=20=E7=89=88=E6=9C=AC):=20?=
 =?UTF-8?q?=E4=B8=89=E4=BB=BD=20manifest=20=E5=8D=87=E7=89=88=E8=87=B3=200?=
 =?UTF-8?q?.4.1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .claude-plugin/plugin.json | 2 +-
 .codex-plugin/plugin.json  | 2 +-
 plugin.json                | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index a906dd9..aba5b7c 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "jsc-hooks",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟、寫入與提交閘門",
   "skills": "./skills",
   "author": {
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 3d87763..78461b8 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "hooks": "./hooks/codex-hooks.json",
   "name": "jsc-hooks",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟、寫入與提交閘門",
   "skills": "./skills",
   "jsc": {
diff --git a/plugin.json b/plugin.json
index f2ba5b3..e964f42 100644
--- a/plugin.json
+++ b/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "jsc-hooks",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟、寫入與提交閘門",
   "skills": "./skills/",
   "jsc": {
-- 
2.53.0


From 358c30c7b848d4c3af8f3cc859d30f1235c29abb Mon Sep 17 00:00:00 2001
From: Jeffery <jiantw83@yahoo.com>
Date: Thu, 3 Sep 2026 10:31:29 +0800
Subject: [PATCH 7/9] =?UTF-8?q?fix(hooks-install):=20=E8=85=B3=E6=9C=AC?=
 =?UTF-8?q?=E5=91=BC=E5=8F=AB=E4=B8=80=E5=BE=8B=E5=AF=AB=E6=88=90=E5=9F=B7?=
 =?UTF-8?q?=E8=A1=8C=E6=9C=9F=E8=A7=A3=E5=87=BA=E7=9A=84=E5=AD=97=E9=9D=A2?=
 =?UTF-8?q?=E7=B5=95=E5=B0=8D=E8=B7=AF=E5=BE=91?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

無人看管的輪次會在第一支腳本就被擋下，整輪還沒開始就結束。2026-09-02 到 09-03 以非互動模式比照排程環境實測七種寫法，結論很乾淨：權限層比對的是還沒展開的字面字串，帶變數或帶波浪號的路徑一律解不出來，一律要人核准；路徑中段的萬用字元也不匹配，所以帶版本號的快取路徑放不進允許清單。連 readlink、ls 這種只讀指令都要有自己的規則。放寬允許清單救不了這件事，只有把路徑寫成字面絕對值才跑得動。

技能因此多兩節。路徑守則寫明每一次腳本呼叫都要是字面絕對路徑，並說清楚為什麼不能為了可攜性換回變數寫法——變數寫法買不到可攜性，只買到一輪還沒跑到第一階段就死掉。前置步驟把可攜性挪到執行期：兩個根目錄各以 readlink 解一次，只在這裡解，之後不重解，也不為此新增腳本。主代理人解完把兩條字面路徑交給每一個 sub agent，sub agent 自己不解。技能內九處腳本呼叫都改成由這兩個根目錄開頭。

兩條 readlink 各自在同一步用 [ -d ] 查過印出來的目錄真的存在。JSC_HOME 沒設時第一條會印出 /current、結束碼 0，非空又是絕對路徑，只查前三項擋不下來。

解兩個根目錄不是重複。連結農場根目錄給跨 domain 呼叫用；jsc-hooks 的實體根目錄只給接線腳本用，而這一條的理由與權限無關：那支腳本從自身位置推出自己的根目錄，又會改寫自己正踩著的那條連結。走連結跑下去，連結會被指向自己，全機器的 hook 一起失效——這件事實際發生過。

存放庫自帶的 hook 設定檔刻意保留變數寫法，技能文件也把這個例外寫明。那是檔案內容，由 hook 自己的 shell 在執行當下展開，不經過權限層，也不是誰在提示裡打出來的路徑；改成實體路徑等於把某一台機器的路徑寫死進要發佈的檔案。

行為清單的 hooks-install 四列跟著校準。

受影響的是每一個跑 hooks-install 的人，最直接的是排程觸發、沒有人在旁邊核准的那些輪次。
---
 references/behaviors.md       |  8 +++----
 skills/hooks-install/SKILL.md | 39 +++++++++++++++++++++++++++--------
 2 files changed, 34 insertions(+), 13 deletions(-)

diff --git a/references/behaviors.md b/references/behaviors.md
index 47a3abc..2a4a8f2 100644
--- a/references/behaviors.md
+++ b/references/behaviors.md
@@ -7,10 +7,10 @@
 | 項目 | 內容 |
 | --- | --- |
 | 觸發時機 | 裝好或更新完 jsc 技能組之後，要把九支 hook 接線到每一支已安裝的 CLI 時用；`jsc-cli:deploy` 收尾會把偵測到的 CLI 清單交給它。不用於撰寫新的 hook，也不用於單獨修一支壞掉的 hook，那是 `jsc-hooks:repair` 的事 |
-| 關鍵步驟 | 取得 CLI 清單（呼叫端交來的優先，沒有才自己跑 `detect-clis.sh`）、第一支 CLI 單獨跑完整條管線（它負責更新共用的 `$JSC_HOME/current/jsc-hooks` 連結）、其餘 CLI 一支一個 sub agent 並行、每支 CLI 依序走 purge、接線、status、smoke、scan 五道關卡、讀每道關卡自己印的第一行判定、任一關卡出錯就寫 `ERROR_{HASH}` 並轉給 `jsc-hooks:repair`（異常頁與索引目錄頁分屬兩個存取庫，各自解析；只解不出目錄頁的存取庫時異常頁照寫、索引跳過，回報要講明那一頁沒被索引）、目錄頁那一列指向異常頁的連結一律寫成 `[{文字}]({連結})`，網址取 `gitea.sh wiki-url`，寫進去之前先過 `jsc-gitea/tools/link-check.sh`，結束碼 0 才寫連結、驗不過那一格只留純文字頁名而那一列與異常頁照寫（`report-error.sh` 內部做完，結束碼不變）、逐 CLI 回報五道關卡的結果 |
-| 外部呼叫 | `tools/wire-cli.sh purge`、`tools/wire-cli.sh {cli}`、`tools/wire-cli.sh status`、`tools/wire-cli.sh smoke`、`tools/scan-hook-errors.sh`、`tools/report-error.sh`、`jsc-cli/tools/detect-clis.sh`、`jsc-hooks:repair` 技能、`jsc-gitea:wiki`（寫 `ERROR_{HASH}` 時經 `report-error.sh`）、`jsc-gitea/tools/gitea.sh wiki-url` 與 `jsc-gitea/tools/link-check.sh`（同樣經 `report-error.sh`，取目錄頁那一列的網址並驗它連得到）；接線腳本內部另呼叫 `hooks/skill-name.sh` 與 `hooks/deny.sh` 做冒煙斷言 |
-| 完成條件 | 每一支偵測到的 CLI 都有五道關卡各一行判定，沒有任何一道回結束碼 2，smoke 的 `lines` 條數與它自己的斷言相符，claude、codex、copilot、antigravity 回 `wired` 而 kiro 回 `degraded`（CLI 擋不下技能叫用），四支非 claude 的執行期錯誤掃描一律據實回 `unavailable`，各 CLI 的形狀與觸發驗證等級分開寫進回報（codex、antigravity、kiro 形狀實證，copilot 形狀未證；kiro 觸發部分實證，其餘未驗證），每一筆錯誤都帶一個 `ERROR_{HASH}` 結果與一條對 `develop` 的修正 PR 連結，而且目錄頁那一列的連結驗不過時，回報要講明那一列只有純文字頁名、沒有連結 |
-| 可驗證跡象 | 各 CLI 的設定檔多出 jsc 段落：codex 的 `config.toml` 標記段落、`hooks/codex-hooks.json`（從 `hooks/hooks.json` 推導，matcher `Skill` 換成 `Bash`）與 `.codex-plugin/plugin.json` 指過去的 `hooks` 路徑字串、copilot 的 `~/.copilot/settings.json` 頂層 `hooks` 鍵（matcher `skill`，合併不覆寫，`enabledPlugins` 與第三方條目原樣保留）與 `$COPILOT_HOME` 底下的指引檔、antigravity 的 `~/.gemini/config/hooks.json` 的 `jsc` 段落（`PreToolUse` 為 Grouped、matcher `^view_file$`，`PreInvocation` 維持 Flat）、kiro 的 `~/.kiro/agents/jsc.json`（`hooks` 為 `agentSpawn`、`userPromptSubmit`、`stop` 三個合法事件加 `timeout_ms`、兩層 `skill://` glob 的 `resources`、明列的 `tools`，並通過 `kiro-cli agent validate`）與 `~/.kiro/settings/cli.json` 的 `chat.defaultAgent=jsc`；四支非 claude 的接線命令都以 `JSC_CLI={代號}` 前綴自帶 CLI 代號，缺了它兩道閘門解不出技能名、一律安靜放行，所以 `status` 把它列成單獨一項；另有 `$JSC_HOME/current/jsc-hooks` 符號連結建立或更新、`$JSC_HOME/backup/hooks/{cli}/{時間戳}/` 留下 purge 前的備份、出錯時 wiki 多一頁 `ERROR_{HASH}`（落在 `JSC_WIKI_REPO_ERROR` 解出的存取庫）並在索引目錄頁補一列（落在 `JSC_WIKI_REPO_CONTENTS` 解出的另一個存取庫，那一列的第 2 格寫成 `[{頁名}]({絕對網址})`，網址取自 `gitea.sh wiki-url` 且已經過 `link-check.sh` 驗到結束碼 0；驗不過那一格只有純文字頁名，`report-error.sh` 在 stderr 留一行 `[jsc]` 講明是哪一種原因）、修正路徑留下一條對 `develop` 的 PR 。接線完成後 `$JSC_HOME/usage/events.jsonl` 會逐行長出 `{kind:hook}` 事件，每支 hook 每次執行一筆，欄位含 `status` 與實際結束碼；跑過技能之後另有 `{kind:skill,phase:start}`。事件寫不進去不影響任何 hook 的結束碼 |
+| 關鍵步驟 | 先跑前置步驟解出兩個字面絕對路徑：`readlink -f "$JSC_HOME/current"` 解出連結農場根目錄（跨 domain 呼叫用它），`readlink -f "$JSC_HOME/current/jsc-hooks"` 解出 jsc-hooks 的實體根目錄（只有 `wire-cli.sh` 從這裡跑，因為它會改寫自己正踩著的那條連結，走連結跑會讓 `ln -sfn` 把連結指向自己、全機器 hook 一起失效）、兩個路徑各解一次不重解、各自在同一步用 `[ -d ]` 查過印出來的目錄真的存在（`JSC_HOME` 沒設時第一條會印出 `/current`、結束碼 0，非空又是絕對路徑，只查前三項擋不下來），任何一條解不出來、不是絕對路徑、或目錄不存在就停手回報是哪一條沒解出來並叫人跑 `jsc-cli:deploy`，不接任何線也不猜路徑、不退回帶版本號的快取路徑、之後每一次腳本呼叫都用解出來的字面絕對路徑開頭、取得 CLI 清單（呼叫端交來的優先，沒有才自己跑 `detect-clis.sh`）、第一支 CLI 單獨跑完整條管線（它負責更新共用的 `{連結農場根}/jsc-hooks` 連結）、其餘 CLI 一支一個 sub agent 並行、每支 CLI 依序走 purge、接線、status、smoke、scan 五道關卡、讀每道關卡自己印的第一行判定、任一關卡出錯就寫 `ERROR_{HASH}` 並轉給 `jsc-hooks:repair`（異常頁與索引目錄頁分屬兩個存取庫，各自解析；只解不出目錄頁的存取庫時異常頁照寫、索引跳過，回報要講明那一頁沒被索引）、目錄頁那一列指向異常頁的連結一律寫成 `[{文字}]({連結})`，網址取 `gitea.sh wiki-url`，寫進去之前先過 `jsc-gitea/tools/link-check.sh`，結束碼 0 才寫連結、驗不過那一格只留純文字頁名而那一列與異常頁照寫（`report-error.sh` 內部做完，結束碼不變）、逐 CLI 回報五道關卡的結果 |
+| 外部呼叫 | `readlink -f`（前置步驟解兩個根目錄，各一次）、`tools/wire-cli.sh purge`、`tools/wire-cli.sh {cli}`、`tools/wire-cli.sh status`、`tools/wire-cli.sh smoke`、`tools/scan-hook-errors.sh`、`tools/report-error.sh`、`jsc-cli/tools/detect-clis.sh`、`jsc-hooks:repair` 技能、`jsc-gitea:wiki`（寫 `ERROR_{HASH}` 時經 `report-error.sh`）、`jsc-gitea/tools/gitea.sh wiki-url` 與 `jsc-gitea/tools/link-check.sh`（同樣經 `report-error.sh`，取目錄頁那一列的網址並驗它連得到）；接線腳本內部另呼叫 `hooks/skill-name.sh` 與 `hooks/deny.sh` 做冒煙斷言 |
+| 完成條件 | 前置步驟解出的兩個根目錄都是一條存在的絕對路徑（各自用 `[ -d ]` 查過），而且整個流程沒有任何一次腳本呼叫帶著未展開的變數或波浪號，每一支偵測到的 CLI 都有五道關卡各一行判定，沒有任何一道回結束碼 2，smoke 的 `lines` 條數與它自己的斷言相符，claude、codex、copilot、antigravity 回 `wired` 而 kiro 回 `degraded`（CLI 擋不下技能叫用），四支非 claude 的執行期錯誤掃描一律據實回 `unavailable`，各 CLI 的形狀與觸發驗證等級分開寫進回報（codex、antigravity、kiro 形狀實證，copilot 形狀未證；kiro 觸發部分實證，其餘未驗證），每一筆錯誤都帶一個 `ERROR_{HASH}` 結果與一條對 `develop` 的修正 PR 連結，而且目錄頁那一列的連結驗不過時，回報要講明那一列只有純文字頁名、沒有連結 |
+| 可驗證跡象 | 各 CLI 的設定檔多出 jsc 段落：codex 的 `config.toml` 標記段落、`hooks/codex-hooks.json`（從 `hooks/hooks.json` 推導，matcher `Skill` 換成 `Bash`）與 `.codex-plugin/plugin.json` 指過去的 `hooks` 路徑字串、copilot 的 `~/.copilot/settings.json` 頂層 `hooks` 鍵（matcher `skill`，合併不覆寫，`enabledPlugins` 與第三方條目原樣保留）與 `$COPILOT_HOME` 底下的指引檔、antigravity 的 `~/.gemini/config/hooks.json` 的 `jsc` 段落（`PreToolUse` 為 Grouped、matcher `^view_file$`，`PreInvocation` 維持 Flat）、kiro 的 `~/.kiro/agents/jsc.json`（`hooks` 為 `agentSpawn`、`userPromptSubmit`、`stop` 三個合法事件加 `timeout_ms`、兩層 `skill://` glob 的 `resources`、明列的 `tools`，並通過 `kiro-cli agent validate`）與 `~/.kiro/settings/cli.json` 的 `chat.defaultAgent=jsc`；四支非 claude 的接線命令都以 `JSC_CLI={代號}` 前綴自帶 CLI 代號，缺了它兩道閘門解不出技能名、一律安靜放行，所以 `status` 把它列成單獨一項；另有 `{連結農場根}/jsc-hooks` 符號連結建立或更新，而且它指向 jsc-hooks 的實體根目錄、不是指向自己（`readlink -f` 解得出一個存在的目錄，裡面有 `hooks/session-timer.sh` 與 `tools/jsc-wrap.sh`）、各 CLI 設定裡存下來的接線命令也都是展開後的字面絕對路徑，只有存放庫自帶的 `hooks/hooks.json` 保留 `${JSC_HOME:-$HOME/.jsc}/current/jsc-hooks` 這段變數寫法，由 hook 自己的 shell 在執行當下展開、`$JSC_HOME/backup/hooks/{cli}/{時間戳}/` 留下 purge 前的備份、出錯時 wiki 多一頁 `ERROR_{HASH}`（落在 `JSC_WIKI_REPO_ERROR` 解出的存取庫）並在索引目錄頁補一列（落在 `JSC_WIKI_REPO_CONTENTS` 解出的另一個存取庫，那一列的第 2 格寫成 `[{頁名}]({絕對網址})`，網址取自 `gitea.sh wiki-url` 且已經過 `link-check.sh` 驗到結束碼 0；驗不過那一格只有純文字頁名，`report-error.sh` 在 stderr 留一行 `[jsc]` 講明是哪一種原因）、修正路徑留下一條對 `develop` 的 PR 。接線完成後 `$JSC_HOME/usage/events.jsonl` 會逐行長出 `{kind:hook}` 事件，每支 hook 每次執行一筆，欄位含 `status` 與實際結束碼；跑過技能之後另有 `{kind:skill,phase:start}`。事件寫不進去不影響任何 hook 的結束碼 |
 
 ## repair
 
diff --git a/skills/hooks-install/SKILL.md b/skills/hooks-install/SKILL.md
index a7c93ea..c62502c 100644
--- a/skills/hooks-install/SKILL.md
+++ b/skills/hooks-install/SKILL.md
@@ -7,9 +7,30 @@ description: Wire jsc hooks (STE100 guard, session timer, skill usage logger, SD
 
 Goal: make the nine hooks (`ste100-guard.sh`, `session-timer.sh`, `skill-usage.sh`, `sdlc-gate.sh`, `version-guard.sh`, `restart-gate.sh`, `comment-scope.sh`, `lang-guard.sh`, `write-guard.sh`) effective in every CLI, with nothing else wired alongside them.
 
+## Path rule
+
+**Every script call in this skill is written as a literal absolute path.** A path that still carries `$JSC_HOME`, any other unexpanded variable, or a `~` cannot be resolved statically by the permission layer, so it is treated as unknown and always asks for approval. An unattended round has nobody to approve, so it stops at the first script and the whole install never starts.
+
+Measured on this machine: `$JSC_HOME/current/jsc-assist/tools/patrol.sh` and `~/.jsc/current/...` were both blocked and the command never ran; the same script at `/root/.jsc/current/...` ran. Adding an allow rule that itself starts with `$JSC_HOME` changed nothing on a retest, because the rule is matched against the expanded command — widening the permission list is not the fix.
+
+Do not trade this back for portability. A variable-form path in this file buys no portability; it buys a round that dies before its first stage. Portability lives in the prerequisite below, which resolves the roots once, on the machine, at run time.
+
+## Prerequisite — resolve the roots once
+
+Run these two before any other call in this skill, and only here:
+
+1. `readlink -f "$JSC_HOME/current"` prints the link farm as a literal absolute path. Call it `{JSC_ROOT}`. Every cross-domain call is written `{JSC_ROOT}/jsc-{domain}/...` with that path substituted in.
+2. `readlink -f "$JSC_HOME/current/jsc-hooks"` prints the physical root behind the `jsc-hooks` link. Call it `{HOOKS_ROOT}`. `tools/wire-cli.sh` is called from there and from nowhere else. That script rewrites the very `{JSC_ROOT}/jsc-hooks` link it would be running through and derives its own root from `$0`, so running it through the link makes `ln -sfn` point that link at itself. The loop takes every CLI's hooks down at once, and it has happened.
+
+**Both results are checked before anything else runs: `[ -d "{JSC_ROOT}" ]` and `[ -d "{HOOKS_ROOT}" ]`, each in the same approved step as its own `readlink`.** A `readlink` that printed something is not a `readlink` that found something. With `JSC_HOME` unset the first call prints `/current` and exits 0 — non-empty, absolute, and wrong — and every literal path built from it then names a place that is not there; the second call has the same hole one level down. An empty result, a non-zero exit, a path that is not absolute, or a directory that does not exist stops the skill here: report which of the two roots did not resolve and what the command printed, say `jsc-cli:deploy` has to run to restore `current` and its `jsc-hooks` link, and wire nothing. Never guess a root, never fall back to a versioned plugin cache path, and never create either root here — a run that pushes on wires every CLI to scripts that are not there, and `purge` has already removed the hooks that worked.
+
+Resolve both once, here. Do not re-resolve per call, and do not add a tool that prints these paths — two `readlink` runs and their two checks are the whole step. The main agent resolves them and hands both literal paths to every sub agent it starts, so a sub agent never resolves anything itself. Done when you hold two literal absolute paths, both naming directories that exist, and every later call starts with one of them.
+
+## Wiring
+
 Install on a clean slate. Every CLI is purged of all hooks first, third-party ones included, so a later failure has exactly one owner. `tools/wire-cli.sh purge` backs up every file it touches before it removes anything, so the removal stays reversible.
 
-The wiring commands stored in user config use `$JSC_HOME/current/jsc-hooks`, not the versioned plugin cache path and not the development checkout. `tools/wire-cli.sh {cli}` creates or refreshes that symlink before it writes `notify`, shell aliases or Kiro hook JSON, then verifies the linked scripts exist. If the filesystem cannot create the symlink, the script must say so and explicitly fall back to the current root; it must never write a silent broken path. The bundled `hooks/hooks.json` follows the same rule: use `${CLAUDE_PLUGIN_ROOT}` only where the host provides it, and fall back to `$JSC_HOME/current/jsc-hooks` for any other CLI reading the same manifest, so an unset Claude-only variable never expands into `/hooks/...`.
+The wiring commands stored in user config use `{JSC_ROOT}/jsc-hooks`, not the versioned plugin cache path and not the development checkout. `wire-cli.sh` expands that root itself, so what lands in each CLI's config is already a literal absolute path. `{HOOKS_ROOT}/tools/wire-cli.sh {cli}` creates or refreshes that symlink before it writes `notify`, shell aliases or Kiro hook JSON, then verifies the linked scripts exist. If the filesystem cannot create the symlink, the script must say so and explicitly fall back to the current root; it must never write a silent broken path. The bundled `hooks/hooks.json` follows the same rule with one deliberate exception: use `${CLAUDE_PLUGIN_ROOT}` only where the host provides it, and fall back to the manifest's own text, `${JSC_HOME:-$HOME/.jsc}/current/jsc-hooks`, for any other CLI reading the same manifest, so an unset Claude-only variable never expands into `/hooks/...`. That one stays in variable form on purpose: it is file content shipped with the repo, expanded by the hook's own shell on whatever machine reads it, and it never passes through the permission layer. It is not a path anyone types at a prompt, so the path rule above does not reach it.
 
 Four of the five CLIs have a pre-tool hook that can block. The version guard and the restart gate reach codex, copilot and antigravity too — each at its own wiring point, with its own matcher and its own blocking shape. Never say a CLI "has no pre-tool hook"; that claim is wrong and it is what left three CLIs unguarded.
 
@@ -66,16 +87,16 @@ The detailed flow **MUST run as a sub agent**; the main agent only reports the s
 
 ## Steps
 
-1. Take the CLI list from the caller when it hands one over — `jsc-cli:deploy` passes the list it already detected, and probing the same five executables a second time buys nothing. Run `jsc-cli/tools/detect-clis.sh` yourself only when no list came in; that fallback is what keeps this skill usable when it is called on its own. The script always exits 0 and prints one `name<TAB>path<TAB>version` line per installed CLI. Done when you hold that list and have said which of the two ways produced it; when it is empty, report that no CLI was detected and stop.
-2. Run the five-stage pipeline **purge → wire → status → smoke → scan** once per detected CLI. Run the first CLI's pipeline on its own, because `tools/wire-cli.sh {cli}` is what refreshes the shared `$JSC_HOME/current/jsc-hooks` link and two CLIs must not rewrite it at the same time; once that first pipeline has finished, run every remaining CLI's pipeline in parallel, one sub agent per CLI — the five stages of one CLI stay in this order, but different CLIs touch different config files and share nothing else. Every stage prints its verdict on its first line, so read that line and never infer the outcome from the prose below it.
-   1. `tools/wire-cli.sh purge {cli}` — backs up every file it touches, removes all hooks, re-reads each file to confirm the removal, and restores the backup by itself when a check fails. Marker matching trims leading and trailing whitespace, so an indented or padded marker block is still removed as the same jsc-owned block. Exit 0 is `purged`, exit 3 is `skipped` (that CLI's executable is not on this machine, so skip its remaining stages too), exit 4 is `failed` and goes to step 3. Exit 2 is a bad CLI name, not a purge outcome — fix the name and rerun the stage.
-   2. `tools/wire-cli.sh {cli}` — owns both the wiring and its verification: it refreshes the link, writes the config, alias or hook file inside a `<!-- jsc-hooks -->` (or `# jsc-hooks`) marker block, re-reads every file it wrote, confirms the block is present and correctly placed, and confirms the stored runtime paths resolve to existing scripts before it prints a success status. Exit 0 is `wired` and is the expected result on claude, codex, copilot and antigravity; exit 1 is `degraded` and is expected on kiro alone; exit 3 is `skipped`, exit 4 is `failed` and goes to step 3. Exit 2 is a bad CLI name — fix the name and rerun. The matcher is verified on its own, not just the presence of a key: a key that is there with the wrong matcher reports as wired and fires never.
-   3. `tools/wire-cli.sh status {cli}` — the read-only inventory of what the previous stage wrote. It writes nothing and runs no hook, so it is safe to run right after wiring. Exit 0 is `wired` (claude, codex, copilot, antigravity), exit 1 is `degraded` (kiro), exit 3 is `skipped`, exit 5 is `unwired`, which names every missing item and means the wiring stage has to run again before you continue. Exit 2 is a bad CLI name. For codex this stage is the only one that reads the installed `jsc-hooks` manifest in the Codex plugin cache and reports a stale `UserPromptSubmit` command there, the one that expands `${CLAUDE_PLUGIN_ROOT}` into `/hooks/...`; carry that item into the report.
-   4. `tools/wire-cli.sh smoke {cli}` — runs every wired mode of all nine hooks once, plus each decision path of the work-package check, of the restart gate and of the write and commit guard. It catches what the wiring check cannot see: a hook that is wired correctly and still fails when it executes. It also runs each CLI's real payload through `skill-name.sh`, each blocking shape through `deny.sh`, and those same payloads straight through `restart-gate.sh` end to end, so a break anywhere along parse, decide and emit is caught — the two ends look healthy on their own while the middle silently passes everything through, which is exactly how three CLIs went unguarded. It prints its own result-line count as `lines<TAB>{count}` and asserts that count against what it expected to run, so read the number from that line and never restate a number of your own. Exit 0 is `ok`, exit 4 is `failed` — either a hook errored or the line count did not match, and both go to step 3. Exit 2 is a bad CLI name.
-   5. `tools/scan-hook-errors.sh --cli {cli}` — only claude keeps hook results in its native records and can answer `clean` or `errors`; codex, copilot, antigravity and kiro answer `unavailable`, and their runtime evidence comes from the smoke stage alone. Exit 0 covers both `clean` and `unavailable`, exit 1 is `errors` and every entry with `jsc=true` goes to step 3, exit 2 is a bad CLI name.
+1. Take the CLI list from the caller when it hands one over — `jsc-cli:deploy` passes the list it already detected, and probing the same five executables a second time buys nothing. Run `{JSC_ROOT}/jsc-cli/tools/detect-clis.sh` yourself only when no list came in; that fallback is what keeps this skill usable when it is called on its own. The script always exits 0 and prints one `name<TAB>path<TAB>version` line per installed CLI. Done when you hold that list and have said which of the two ways produced it; when it is empty, report that no CLI was detected and stop.
+2. Run the five-stage pipeline **purge → wire → status → smoke → scan** once per detected CLI. Run the first CLI's pipeline on its own, because `{HOOKS_ROOT}/tools/wire-cli.sh {cli}` is what refreshes the shared `{JSC_ROOT}/jsc-hooks` link and two CLIs must not rewrite it at the same time; once that first pipeline has finished, run every remaining CLI's pipeline in parallel, one sub agent per CLI — the five stages of one CLI stay in this order, but different CLIs touch different config files and share nothing else. Every stage prints its verdict on its first line, so read that line and never infer the outcome from the prose below it.
+   1. `{HOOKS_ROOT}/tools/wire-cli.sh purge {cli}` — backs up every file it touches, removes all hooks, re-reads each file to confirm the removal, and restores the backup by itself when a check fails. Marker matching trims leading and trailing whitespace, so an indented or padded marker block is still removed as the same jsc-owned block. Exit 0 is `purged`, exit 3 is `skipped` (that CLI's executable is not on this machine, so skip its remaining stages too), exit 4 is `failed` and goes to step 3. Exit 2 is a bad CLI name, not a purge outcome — fix the name and rerun the stage.
+   2. `{HOOKS_ROOT}/tools/wire-cli.sh {cli}` — owns both the wiring and its verification: it refreshes the link, writes the config, alias or hook file inside a `<!-- jsc-hooks -->` (or `# jsc-hooks`) marker block, re-reads every file it wrote, confirms the block is present and correctly placed, and confirms the stored runtime paths resolve to existing scripts before it prints a success status. Exit 0 is `wired` and is the expected result on claude, codex, copilot and antigravity; exit 1 is `degraded` and is expected on kiro alone; exit 3 is `skipped`, exit 4 is `failed` and goes to step 3. Exit 2 is a bad CLI name — fix the name and rerun. The matcher is verified on its own, not just the presence of a key: a key that is there with the wrong matcher reports as wired and fires never.
+   3. `{HOOKS_ROOT}/tools/wire-cli.sh status {cli}` — the read-only inventory of what the previous stage wrote. It writes nothing and runs no hook, so it is safe to run right after wiring. Exit 0 is `wired` (claude, codex, copilot, antigravity), exit 1 is `degraded` (kiro), exit 3 is `skipped`, exit 5 is `unwired`, which names every missing item and means the wiring stage has to run again before you continue. Exit 2 is a bad CLI name. For codex this stage is the only one that reads the installed `jsc-hooks` manifest in the Codex plugin cache and reports a stale `UserPromptSubmit` command there, the one that expands `${CLAUDE_PLUGIN_ROOT}` into `/hooks/...`; carry that item into the report.
+   4. `{HOOKS_ROOT}/tools/wire-cli.sh smoke {cli}` — runs every wired mode of all nine hooks once, plus each decision path of the work-package check, of the restart gate and of the write and commit guard. It catches what the wiring check cannot see: a hook that is wired correctly and still fails when it executes. It also runs each CLI's real payload through `skill-name.sh`, each blocking shape through `deny.sh`, and those same payloads straight through `restart-gate.sh` end to end, so a break anywhere along parse, decide and emit is caught — the two ends look healthy on their own while the middle silently passes everything through, which is exactly how three CLIs went unguarded. It prints its own result-line count as `lines<TAB>{count}` and asserts that count against what it expected to run, so read the number from that line and never restate a number of your own. Exit 0 is `ok`, exit 4 is `failed` — either a hook errored or the line count did not match, and both go to step 3. Exit 2 is a bad CLI name.
+   5. `{JSC_ROOT}/jsc-hooks/tools/scan-hook-errors.sh --cli {cli}` — only claude keeps hook results in its native records and can answer `clean` or `errors`; codex, copilot, antigravity and kiro answer `unavailable`, and their runtime evidence comes from the smoke stage alone. Exit 0 covers both `clean` and `unavailable`, exit 1 is `errors` and every entry with `jsc=true` goes to step 3, exit 2 is a bad CLI name.
 
    Done when every detected CLI has exactly one verdict line per stage, no stage exited 2, the smoke stage's `lines` count matches its own assertion, the four non-claude CLIs are reported as `unavailable` rather than clean on the scan stage, and antigravity and kiro carry the note that their hook firing is unverified.
-3. For each error — a failed purge, a failed wiring, an `unwired` status, a failed smoke, or a scanned error with `jsc=true` — run `tools/report-error.sh --hook {script name} --exit {code} --summary "{reason}" --cli {cli}` with the script's `[jsc]` output on stdin, then hand the failure to `jsc-hooks:repair`, which **MUST run as a sub agent** and must finish by opening a PR against `develop`. Aborting the remaining installs here is allowed as long as the repair starts. The error page and the error directory page live in two different wiki repos, resolved separately: the page through `wiki-repo ERROR`, the directory through `wiki-repo CONTENTS`. Exit 0 with an `ERROR_{HASH}` page name and URL on stdout means the page was written; the same exit 0 with a `[jsc]` line on stderr still means the page landed, and that line says what is missing — the directory repo would not resolve, so nothing indexes the page; the page URL could not be read back, so the page name comes out on its own; or the URL failed the reachability check, so the directory row carries the page name as plain text with no link — carry that note into step 4. Every link on that row is written as `[{text}]({url})` with the URL from `gitea.sh wiki-url`, and the script checks it with `jsc-gitea/tools/link-check.sh` before writing: exit 0 writes the link, anything else keeps the row and drops the link, and none of it changes the exit code — this is the failure-reporting path, so a failed report must never become a second failure. Exit 0 with no output at all means the run ended on one of the quiet-degradation reasons listed in the script's own header — no `gitea.sh` on the path, the error page's wiki repo unresolved, the hash not computed, or a temp file not created — so no page was written at all and that reason goes into step 4 instead; exit 2 means the call itself was malformed — `--hook` or `--summary` is missing — so fix the arguments and rerun the same call; exit 4 means the wiki record did not land, so report the failure text and still start the repair — a page that could not be written is no reason to leave a broken hook wired. Exit 4 covers two cases, and the report has to say which: a failed write, or the script refusing to write the error directory page because it could not read the old one back. That directory is appended to, never overwritten: every row on it is somebody else's error report, so the script reads the page, adds this run's row, and writes the whole page. Only a genuine 404 (`wiki-get` exit 4) means the page is not there yet and lets it build one from the template. An invalid key (exit 7) or any other API failure (exit 8) leaves the old rows unknown, so it skips the directory write and names the code instead — writing a fresh template over a directory it never read would erase every earlier report, with no merge and no backup behind it. A scanned error with `jsc=false` belongs to a third-party hook: report it and leave it alone. Skip this step when every CLI passed all five stages. Done when every error carries one `ERROR_{HASH}` result — a page name with its URL, a page name plus the reason the URL is missing, or the recorded reason no page was written — and one repair PR URL against `develop`.
+3. For each error — a failed purge, a failed wiring, an `unwired` status, a failed smoke, or a scanned error with `jsc=true` — run `{JSC_ROOT}/jsc-hooks/tools/report-error.sh --hook {script name} --exit {code} --summary "{reason}" --cli {cli}` with the script's `[jsc]` output on stdin, then hand the failure to `jsc-hooks:repair`, which **MUST run as a sub agent** and must finish by opening a PR against `develop`. Aborting the remaining installs here is allowed as long as the repair starts. The error page and the error directory page live in two different wiki repos, resolved separately: the page through `wiki-repo ERROR`, the directory through `wiki-repo CONTENTS`. Exit 0 with an `ERROR_{HASH}` page name and URL on stdout means the page was written; the same exit 0 with a `[jsc]` line on stderr still means the page landed, and that line says what is missing — the directory repo would not resolve, so nothing indexes the page; the page URL could not be read back, so the page name comes out on its own; or the URL failed the reachability check, so the directory row carries the page name as plain text with no link — carry that note into step 4. Every link on that row is written as `[{text}]({url})` with the URL from `gitea.sh wiki-url`, and the script checks it with `jsc-gitea/tools/link-check.sh` before writing: exit 0 writes the link, anything else keeps the row and drops the link, and none of it changes the exit code — this is the failure-reporting path, so a failed report must never become a second failure. Exit 0 with no output at all means the run ended on one of the quiet-degradation reasons listed in the script's own header — no `gitea.sh` on the path, the error page's wiki repo unresolved, the hash not computed, or a temp file not created — so no page was written at all and that reason goes into step 4 instead; exit 2 means the call itself was malformed — `--hook` or `--summary` is missing — so fix the arguments and rerun the same call; exit 4 means the wiki record did not land, so report the failure text and still start the repair — a page that could not be written is no reason to leave a broken hook wired. Exit 4 covers two cases, and the report has to say which: a failed write, or the script refusing to write the error directory page because it could not read the old one back. That directory is appended to, never overwritten: every row on it is somebody else's error report, so the script reads the page, adds this run's row, and writes the whole page. Only a genuine 404 (`wiki-get` exit 4) means the page is not there yet and lets it build one from the template. An invalid key (exit 7) or any other API failure (exit 8) leaves the old rows unknown, so it skips the directory write and names the code instead — writing a fresh template over a directory it never read would erase every earlier report, with no merge and no backup behind it. A scanned error with `jsc=false` belongs to a third-party hook: report it and leave it alone. Skip this step when every CLI passed all five stages. Done when every error carries one `ERROR_{HASH}` result — a page name with its URL, a page name plus the reason the URL is missing, or the recorded reason no page was written — and one repair PR URL against `develop`.
 4. Report five results per CLI — purge, wiring, status, smoke, scan — each with the reason its script printed, plus the smoke `lines` count, any `ERROR_{HASH}` page name and every repair PR URL. Done when every detected CLI appears with one verdict per stage and every repair has a PR against `develop`.
 
 ## Notes
-- 
2.53.0


From 221dca70e69176544d1f095cd3089ee2f3e865a7 Mon Sep 17 00:00:00 2001
From: Jeffery <jiantw83@yahoo.com>
Date: Thu, 3 Sep 2026 10:32:11 +0800
Subject: [PATCH 8/9] =?UTF-8?q?fix(behaviors):=20repair=20=E7=9A=84?=
 =?UTF-8?q?=E5=8F=AF=E9=A9=97=E8=AD=89=E8=B7=A1=E8=B1=A1=E8=A3=9C=E4=B8=8A?=
 =?UTF-8?q?=E6=94=B6=E5=B0=BE=E4=BA=8B=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

行為清單檢查拿 HEAD 的內容跑就過不了，它點名 repair 那一列的可驗證跡象沒寫到收尾的 skill-end 事件。這是既有欠帳，跟這一批的路徑處理沒有關係，所以單獨一筆，之後要回退哪一邊都不會牽連另一邊。

補上的內容照準則寫：收尾在本機事件流留下這一輪的 skill-end，status 從 ok、blocked、failed、degraded、aborted 五個裡取一個，中途停下的那幾輪也照寫——只有 start 沒有配對的 end，會被讀成中斷。

受影響的是驗收 repair 有沒有跑完的人，還有把行為清單檢查掛在流程裡的每一個存放庫。
---
 references/behaviors.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/references/behaviors.md b/references/behaviors.md
index 2a4a8f2..bd95640 100644
--- a/references/behaviors.md
+++ b/references/behaviors.md
@@ -20,4 +20,4 @@
 | 關鍵步驟 | 從 `ERROR_{HASH}` 讀失敗情境（沒有頁就讀失敗的 `status=` 那一行，讀不到就停下來問）、跑 `detect-clis.sh`、每一支偵測到的 CLI 各開一個唯讀 sub agent 診斷並交回根因、要改的檔案與驗證指令、挑最小的修正改進 hooks 存取庫（技能名解析改 `hooks/skill-name.sh`、阻擋形態改 `hooks/deny.sh`，兩支是唯一真實來源，不在閘門裡各補一份）、跑 `wire-cli.sh smoke {cli}` 驗到 exit 0、跑 `sync-skill-manifest.sh .` 同步版本、以 `jsc-git:pr` 對 `develop` 開 PR |
 | 外部呼叫 | `jsc-gitea:wiki`、`jsc-cli/tools/detect-clis.sh`、`tools/wire-cli.sh smoke`、`jsc-meta/tools/sync-skill-manifest.sh`、`jsc-git:pr`；診斷階段另以 sub agent 叫用各支已安裝的 AI CLI |
 | 完成條件 | 修正已經落在磁碟上、`wire-cli.sh smoke` 對受影響的 CLI 回 exit 0、`sync-skill-manifest.sh` 回 exit 0 而且三份 manifest 版本一致，最後拿到一條對 `develop` 的 PR 連結；開不出 PR 時要講明修正已套用但尚未合併、帶上分支名與失敗原因 |
-| 可驗證跡象 | hooks 存取庫多一個修正提交與一條推上去的分支、`develop` 上多一條 PR、三份 manifest 與 README 技能清單版本一致、`wire-cli.sh smoke` 由失敗轉為 exit 0 |
+| 可驗證跡象 | hooks 存取庫多一個修正提交與一條推上去的分支、`develop` 上多一條 PR、三份 manifest 與 README 技能清單版本一致、`wire-cli.sh smoke` 由失敗轉為 exit 0。收尾在 `$JSC_HOME/usage/events.jsonl` 留下這一輪的 `skill-end` 事件，`status` 取 `ok`、`blocked`、`failed`、`degraded` 或 `aborted`，中途停下的那幾輪也照寫——只有 start 沒有配對 end 會被讀成中斷 |
-- 
2.53.0


From 70526244c7438d14789b5ae5e45326d4076a1b04 Mon Sep 17 00:00:00 2001
From: Jeffery <jiantw83@yahoo.com>
Date: Thu, 3 Sep 2026 10:32:11 +0800
Subject: [PATCH 9/9] =?UTF-8?q?chore(plugin):=20=E4=B8=89=E4=BB=BD=20manif?=
 =?UTF-8?q?est=20=E5=8D=87=E7=89=88=E8=87=B3=200.4.2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

hooks-install 的路徑處理與行為清單都變了，版號要帶得出這批變更，版本前置檢查才會要求機器端更新。

三份 manifest 由 sync-skill-manifest.sh 同步，只動版本欄位，內容一致。

受影響的是靠版號判斷要不要更新的每一台機器。
---
 .claude-plugin/plugin.json | 2 +-
 .codex-plugin/plugin.json  | 2 +-
 plugin.json                | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index aba5b7c..4536ccf 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "jsc-hooks",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟、寫入與提交閘門",
   "skills": "./skills",
   "author": {
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 78461b8..a99e8d2 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "hooks": "./hooks/codex-hooks.json",
   "name": "jsc-hooks",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟、寫入與提交閘門",
   "skills": "./skills",
   "jsc": {
diff --git a/plugin.json b/plugin.json
index e964f42..6d1ce6a 100644
--- a/plugin.json
+++ b/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "jsc-hooks",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟、寫入與提交閘門",
   "skills": "./skills/",
   "jsc": {
-- 
2.53.0