chore(plugin 版本): 三份 manifest 升版至 0.4.2

hook 在原理上看不到技能的成敗：它接在技能工具呼叫上，而實際工作發生在
之後的模型輪次。start 由技能用量 hook 順手發，end 只能由技能自己寫。
有 start 沒有配對的 end，就是那一輪中止了。

.agents/plugins/marketplace.json

@@ -13,6 +13,14 @@
       },
       "description": "決策樹問詢與問詢紀錄（QUESTION_* wiki 頁）"
     },
+    {
+      "name": "jsc-assist",
+      "source": {
+        "source": "url",
+        "url": "https://gitea.jsc.idv.tw/plugins/assist.git"
+      },
+      "description": "助理：事件收攏、健康巡檢與待辦簿（MONITOR_* wiki 頁）"
+    },
     {
       "name": "jsc-cli",
       "source": {

.claude-plugin/marketplace.json

@@ -13,6 +13,14 @@
       },
       "description": "決策樹問詢與問詢紀錄（QUESTION_* wiki 頁）"
     },
+    {
+      "name": "jsc-assist",
+      "source": {
+        "source": "url",
+        "url": "https://gitea.jsc.idv.tw/plugins/assist.git"
+      },
+      "description": "助理：事件收攏、健康巡檢與待辦簿（MONITOR_* wiki 頁）"
+    },
     {
       "name": "jsc-cli",
       "source": {

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-hooks",
-  "version": "0.3.4",
+  "version": "0.4.2",
   "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟、寫入與提交閘門",
   "skills": "./skills",
   "author": {

.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "hooks": "./hooks/codex-hooks.json",
   "name": "jsc-hooks",
-  "version": "0.3.4",
+  "version": "0.4.2",
   "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟、寫入與提交閘門",
   "skills": "./skills",
   "jsc": {

README.md

@@ -28,10 +28,12 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
 | `hooks/deny.sh` | 不直接接線，由 `version-guard.sh` 與 `restart-gate.sh` 呼叫 | 產出各 CLI 認得的阻擋輸出，訊息從參數或標準輸入進。claude、codex、copilot 訊息寫 stderr 並回 exit 2；antigravity 印 stdout 的 `{"decision":"deny","reason":"..."}` 並固定回 0——那支 CLI 的結束碼語意兩邊文件都沒寫，靠結束碼會變成「判定擋下、CLI 照樣放行」的無聲失效，所以 stdout 只准有那一行；kiro 擋不下技能叫用，改印警告後回 0；認不得的代號走 stderr 加 2 這個保守預設 |
 | `hooks/version-guard.sh` | PreToolUse：claude matcher `Skill`、codex matcher `Bash`、copilot matcher `skill`、antigravity matcher `^view_file$` 加 `PreInvocation`；kiro `userPromptSubmit`（只注入警告） | 技能使用前的版本前置檢查，擋兩種情況，兩種都擋下該次呼叫並提示更新指令（更新指令依當前 CLI 給；技能名解析交給 `hooks/skill-name.sh`、阻擋輸出形態交給 `hooks/deny.sh`，兩支的規則見上面兩列，這裡不重寫第二套）：一是本機**實際載入**版本落後遠端發佈版本，二是技能所屬 plugin 的 manifest 在 `jsc.requires` 宣告的相依 plugin 版本落後——相依那一項讀 `installPath` 底下那份 `plugin.json`，逐項比對相依 plugin 的本機實際載入版本，訊息講明哪一個 plugin、需要哪一版、目前哪一版、怎麼補。相依檢查排在遠端比對之前，全部讀本機檔案，離線也判得動；判定邏輯自己實作，不呼叫 `jsc-cli/tools/check-requires.sh`，免得 hook 散落到別的 domain，也免得跟已宣告相依 `jsc-hooks` 的 `jsc-cli` 做出循環相依。部署那端照樣更新、只回報，阻擋落在這支 hook。兩種都只擋確定落後：超前放行（開發技能組時本機本來就會超前），讀不到本機版本、推導不出站台、查不到遠端版本、解不出安裝路徑、讀不到 manifest、manifest 沒有 `jsc.requires`、讀不到相依 plugin 的本機載入版本也一律放行。遠端版本快取在 `$JSC_HOME/version-cache/{CLI 代號}/{domain}`，一支 CLI 一份；舊路徑 `$JSC_HOME/version-cache/{domain}` 會在第一次讀取時複製到新路徑。逃生門 `JSC_VERSION_GUARD=off`。豁免 `jsc-cli:deploy`、`jsc-hooks:hooks-install`、`jsc-hooks:repair`、`jsc-cli:models`、`jsc-meta:*`、`jsc-ask:ask`、`jsc-gitea:wiki`——共 7 項，兩種擋人情況共用同一份，相依落後不另立短清單；清單的唯一來源是 `hooks/version-guard.sh` 的檔頭，那裡一項一個理由 |
 | `hooks/restart-gate.sh` | PreToolUse：claude matcher `Skill`、codex matcher `Bash`、copilot matcher `skill`、antigravity matcher `^view_file$` 加 `PreInvocation`；kiro `userPromptSubmit`（只注入警告） | 部署後強制重啟閘門：`$JSC_HOME/restart-required.d/{CLI 代號}` 一支 CLI 一份，當前 CLI 那份存在時擋下 jsc 技能呼叫，並印出要重新啟動哪一支 CLI（技能名解析交給 `hooks/skill-name.sh`、阻擋輸出形態交給 `hooks/deny.sh`，兩支的規則見上面兩列）；別支 CLI 那幾份不影響這一支。狀態檔由 `jsc-cli:deploy` 在 install 或 update 收尾時經 `restart-gate.sh require {install｜update} [{domain}...]` 寫入當前 CLI 那一份，在下一個工作階段開始時由 `session-timer.sh` 呼叫 `restart-gate.sh clear` 只清除那一份。判定看檔案在不在：狀態檔讀不到、CLI 代號取不到、技能名取不到都放行（理由與 `version-guard.sh` 一致，只擋確定違規）。舊格式的單一檔案 `$JSC_HOME/restart-required` 存在時一律擋，`clear` 會一併刪掉它（過渡相容，詳見下面「部署後重啟狀態檔」）。豁免 `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 壞掉也要修得回來，整批擋下去這些規則會互相打死。清單認技能名不認呼叫鏈，後三支是為了讓前七支走得完才補進來的：`deploy` 要問模式、報告寫完要開 PR。另有唯讀子指令 `report`，一支 CLI 一行印出每一份狀態檔的內容，看得出還有哪幾支沒重啟。逃生門 `JSC_RESTART_GATE=off` |
+| `hooks/heartbeat.sh` | 不接線，由 `jsc-assist` 的助理主體、系統排程與 `status` 技能呼叫 | 助理心跳檔 `$JSC_HOME/assistant/heartbeat` 的讀寫工具，純文字 key=value，欄位 `ts`、`pid`、`cli`、`session`。四個子命令：`write` 寫入四個欄位（目錄不存在就建，先寫暫存檔再改名，讀的那一端永遠讀到完整的一份）、`check` 判定新不新鮮（什麼都不印，結果只在結束碼）、`report` 印一行現況供 `status` 技能與擋人訊息取用、`clear` 刪除心跳檔（由助理的 `stop` 呼叫，檔案不存在也算成功）。新鮮的判準只有一條：心跳檔存在、而且 `ts` 距現在小於門檻秒數，門檻預設 300（心跳週期 60 秒的五倍，一次卡頓不會誤判），可用 `JSC_ASSISTANT_HEARTBEAT_TTL` 覆寫。**絕不看 pid 存活**：五支 CLI 與容器裡的行程互相看不到彼此的 pid，問了會把活著的判成停了，pid 又會被回收，反過來把停掉的判成還在跑，兩種誤判都不報錯；pid 只當擋人訊息的線索。`check` 的結束碼分四種讓呼叫端各自處置：0 新鮮、1 過期（跑過但停了）、3 心跳檔不存在（從沒啟動過）、4 檔案在但 `ts` 讀不出來（檔案壞了）；`write` 與 `clear` 的檔案系統失敗回 5，用法錯誤回 6。四個子命令都不讀標準輸入——這支不是 hook，是被工具端呼叫的腳本，讀了會在管線沒人關閉時整支卡死。逐碼意義與 `report` 的欄位順序見腳本檔頭 |
+| `hooks/assistant-gate.sh` | **這一版尚未接線。** 接線位置比照 `restart-gate.sh`（PreToolUse，claude matcher `Skill`、codex matcher `Bash`、copilot matcher `skill`、antigravity matcher `^view_file$` 加 `PreInvocation`；kiro `userPromptSubmit` 只注入警告） | 助理運行閘門：助理沒在跑就擋下 jsc 技能呼叫。判定整段交給 `heartbeat.sh check`，本檔不自己讀心跳檔；訊息細節取自 `heartbeat.sh report`（技能名解析交給 `hooks/skill-name.sh`、阻擋輸出形態交給 `hooks/deny.sh`）。心跳新鮮放行；心跳不存在、過期、`ts` 讀不出來三種都擋，三種的訊息各寫一份——沒啟動過的要去啟動、跑過停了的要去查為什麼停、檔案壞了的要先 `stop` 再 `start` 重建，併成一句就會叫錯人做錯事。`heartbeat.sh` 回 2（腳本沒跑起來）、5（檔案系統失敗）、6（用法錯誤）一律放行：那三碼是判定機制自己壞了，不是「助理沒在跑」的證據，而且 5 正是磁碟滿或權限壞的訊號，擋下去會把全機器整組技能鎖死、連豁免那幾支也修不動。**這是整組技能唯一一道 fail-closed 閘門**（其餘 hook 一律資料不足就放行），所以逃生門與豁免清單是它能上線的前提，不是選配。豁免 `jsc-assist:*`（啟動助理本身就是一次技能呼叫，少了它整組鎖死）、`jsc-hooks:repair`、`jsc-hooks:hooks-install`、`jsc-cli:doctor`、`jsc-cli:setup`、`jsc-cli:deploy`、`jsc-gitea:wiki`、`jsc-ask:ask`、`jsc-git:commit`、`jsc-git:pr`、`jsc-cli:models`。清單認技能名不認呼叫鏈，後五支是為了讓前六支走得完才補進來的，其中 `jsc-gitea:wiki` 最容易漏：巡檢一輪要先把結果寫進 `MONITOR_{HASH}` 才寫心跳，擋了它就變成「沒心跳 → 擋 wiki → 巡檢不完 → 還是沒心跳」自己咬住自己。逃生門 `JSC_ASSISTANT_GATE=off`，判斷擺在載入 `lib.sh` 之前——`lib.sh` 讀不到時 sh 回 2 等於無聲擋下每一次呼叫，逃生門也會跟著跑不到 |
 | `hooks/skill-usage.sh` | PostToolUse(Skill) | 記錄技能使用與呼叫鏈到 `$JSC_HOME/usage/*.jsonl`，供 `jsc-log:stats` 統計 |
 | `hooks/comment-scope.sh` | UserPromptSubmit、PostToolUse(Write、Edit、MultiEdit)、codex `notify`、kiro `userPromptSubmit`、`tools/jsc-wrap.sh` 收尾 | 程式碼註解不得夾帶文件相關資訊與審查流程痕跡，共三種模式。`prompt`：在每次提示注入規則摘要（禁止項與白名單各一行），五個 CLI 都接得到。無參數：寫檔後的逐檔掃描，從 stdin JSON 取 `file_path`（或環境變數 `JSC_CHANGED_FILE`），只有 claude 的 PostToolUse 接得上。`sweep [dir]`：掃整個 git 工作區這次改過的所有檔案，給沒有 post-tool hook 的四個 CLI 用，找不到 git 就安靜 exit 0。掃描時機每個 CLI 不同——claude 逐檔即時（PostToolUse）、codex 每輪結束（`notify`）、kiro 每輪提示送出時（`userPromptSubmit`，掃的是上一輪寫的檔）、copilot 與 antigravity 只有工作階段結束時由 `tools/jsc-wrap.sh` 收尾掃一次。兩種掃描模式都只看 `git diff HEAD` 的新增行、不翻舊帳，命中就把警告與最多三行證據送到 stderr 並以 exit 2 交回模型就地修正（不擋寫入，檔案已經寫好了）。markdown、純文字、資料檔與二進位檔一律跳過。只實作可用樣式判定的項目，專案代號、客戶名稱這類判不出來的交給 `/jsc-review:code-review`。規則正文的唯一來源在 `jsc-review` 的 `references/comment-scope.md`，本存取庫不留副本。逃生門 `JSC_COMMENT_SCOPE=off` |
 | `hooks/lang-guard.sh` | UserPromptSubmit、PostToolUse(Write、Edit、MultiEdit)、codex `notify`、kiro `userPromptSubmit`、`tools/jsc-wrap.sh` 收尾 | 所有非程式碼輸出一律繁體中文、UTF-8、無亂碼、無簡體字，共三種模式。`prompt`：在每次提示注入規則摘要（適用範圍與自我檢查各一行），五個 CLI 都接得到。無參數：寫檔後的逐檔掃描，從 stdin JSON 取 `file_path`（或環境變數 `JSC_CHANGED_FILE`），只有 claude 的 PostToolUse 接得上。`sweep [dir]`：掃整個 git 工作區這次改過的所有檔案，給沒有 post-tool hook 的四個 CLI 用，找不到 git 就安靜 exit 0。接線位置與掃描時機跟 `comment-scope.sh` 完全一樣，見下面那張表。偵測三項：簡體字（字表在 `hooks/simplified.txt`，讀不到就安靜跳過這一項）、亂碼（U+FFFD 替代字元與雙重編碼殘骸）、非 UTF-8 編碼（用 `iconv` 判定，沒有 `iconv` 就跳過）。三項都掃整個檔案、不只掃註解行，`.md` 與純文字檔照掃——那些正是「非程式碼輸出」的主場，這兩點跟 `comment-scope.sh` 刻意不同。掃描深度仍只看 `git diff HEAD` 的新增行、不翻舊帳，命中就把警告與最多三行證據送到 stderr 並以 exit 2 交回模型就地修正（不擋寫入）。二進位檔（只認 NUL 位元組）與 `*.lock`、`*.min.js`、`*.map` 這類產生檔跳過；`hooks/simplified.txt`、`hooks/ste100-guard.sh`、`hooks/lang-guard.sh` 也跳過，那三份檔案裡的簡體字與亂碼樣本是被討論的對象，不是被使用。規則正文的唯一來源在 `jsc-meta` 的 `references/ste100.md`。逃生門 `JSC_LANG_GUARD=off` |
-| `hooks/sdlc-gate.sh` | UserPromptSubmit、PreToolUse(Skill) | SDLC 階段能力標籤閘門與模型鎖：`lock {stage}` 由 jsc-sdlc 階段技能呼叫，從可驗證來源讀出模型 id，比對該階段必要標籤（`$JSC_HOME/model-tags.tsv`），不符就拒絕上鎖；來源優先序為 transcript、hook stdin JSON、Codex 本機 session 記錄，最後才接受 `JSC_MODEL` 人工覆寫，且回報會標明人工覆寫；`check` 在模型不符時以 exit 2 擋下該輪提示（其他 hook 一律 exit 0，此處是刻意例外）；`report` 印出階段、必要標籤、模型 id、模型來源與判定結果；`unlock` 為逃生門。另含工作包 PR 閘門：`wp-lock {owner}/{repo} {index} [{工作包代號}]` 記下一筆未結清的工作包 PR、`wp-unlock {owner}/{repo} {index}` 結清那一筆（檔案不存在也算成功）、`wp-claim {owner}/{repo} {工作包代號} [{PR 編號}] [{分析頁頁名}]` 記下這個存取庫目前領取哪一包、`wp-unclaim {owner}/{repo}` 交回、`wp-report` 印出所有未結清、`wp-check {prompt｜skill}` 為 hook 模式。狀態檔一個工作包一支，在 `$JSC_HOME/wp/{owner}-{repo}-{index}.pr`，**刻意不綁 session**——PR 沒合併時換一個工作階段照樣要擋；一個工作包一支鎖檔是為了讓好幾個互不相依的工作包能同時記在案，不會互相覆蓋掉對方的鎖。`wp-check prompt` 只注入提醒、絕不擋提示（擋了連「去修那支 PR」的對話都送不出去）；`wp-check skill` 在有未結清 PR 時以 exit 2 擋下 `analyze` 與 `maintain`，但一律放行 `implement`（結清 PR 正是 implement 的步驟，擋它會鎖死流程），也放行 `plan`，只注入提醒（plan 是純邏輯階段、不碰程式碼，而這道閘門只知道「有 PR 未合併」、判不出跟新計畫有沒有關聯；放棄的是在製品上限，`analyze` 與 `maintain` 兩道仍在，上限晚一個階段才生效）——這一層是整個存取庫共用的粗粒度提醒，「某個候選工作包能不能挑」的細粒度判斷在 `jsc-sdlc/tools/wp-gate.sh check-deps`，不是這裡。另外會比對歸屬：未結清的 PR 不屬於目前領取的工作包時，`prompt` 多注入一行「那幾支交給領取它的工作階段」，`skill` 在擋下 `analyze`、`maintain` 時一併點名，`plan` 與 `implement` 仍放行但收到同一則提醒。逃生門 `JSC_WP_GATE=off`。這道閘門只讀檔案、不打網路，PR 的真實合併狀態由 `jsc-sdlc/tools/wp-gate.sh` 查證 |
+| `hooks/sdlc-gate.sh` | UserPromptSubmit、PreToolUse(Skill) | SDLC 階段能力標籤閘門與模型鎖：`lock {stage}` 由 jsc-sdlc 階段技能呼叫，從可驗證來源讀出模型 id，比對該階段必要標籤（`$JSC_HOME/model-tags.tsv`），不符就拒絕上鎖。**來源依 CLI 分流**，一支 CLI 只讀自己的紀錄：claude 讀 transcript 與 hook stdin JSON，codex 讀 hook stdin JSON 與自己的 session 記錄，copilot、antigravity、kiro 本機沒有可讀的模型紀錄，判不出 CLI 時不採用任何自動來源；所有 CLI 最後都接受 `JSC_MODEL` 人工覆寫，且回報會標明人工覆寫。政策是 **fail-closed**：不知道能力就擋下，三種情形一律擋——判不出 CLI、判不出模型、模型不在能力標籤表上；每一則擋下的訊息都會印出兩條逃生門（設 `JSC_MODEL`，或執行 `sdlc-gate.sh unlock {狀態檔}`）。`check` 在上述任一情形以 exit 2 擋下該輪提示（其他 hook 一律 exit 0，此處是刻意例外）；`report` 印出階段、必要標籤、模型 id、模型來源與判定結果；`unlock` 為逃生門，不帶參數清這個工作階段的新舊兩份，帶參數只清指定的那一支。階段鎖狀態檔是 `$JSC_HOME/sessions/{CLI 代號}-{sid}.stage`，舊路徑 `$JSC_HOME/sessions/{sid}.stage` 仍讀得到。另含工作包 PR 閘門：`wp-lock {owner}/{repo} {index} [{工作包代號}]` 記下一筆未結清的工作包 PR、`wp-unlock {owner}/{repo} {index}` 結清那一筆（檔案不存在也算成功）、`wp-claim {owner}/{repo} {工作包代號} [{PR 編號}] [{分析頁頁名}]` 記下這個存取庫目前領取哪一包、`wp-unclaim {owner}/{repo}` 交回、`wp-report` 印出所有未結清、`wp-check {prompt｜skill}` 為 hook 模式。狀態檔一個工作包一支，在 `$JSC_HOME/wp/{owner}-{repo}-{index}.pr`，**刻意不綁 session**——PR 沒合併時換一個工作階段照樣要擋；一個工作包一支鎖檔是為了讓好幾個互不相依的工作包能同時記在案，不會互相覆蓋掉對方的鎖。`wp-check prompt` 只注入提醒、絕不擋提示（擋了連「去修那支 PR」的對話都送不出去）；`wp-check skill` 在有未結清 PR 時以 exit 2 擋下 `analyze` 與 `maintain`，但一律放行 `implement`（結清 PR 正是 implement 的步驟，擋它會鎖死流程），也放行 `plan`，只注入提醒（plan 是純邏輯階段、不碰程式碼，而這道閘門只知道「有 PR 未合併」、判不出跟新計畫有沒有關聯；放棄的是在製品上限，`analyze` 與 `maintain` 兩道仍在，上限晚一個階段才生效）——這一層是整個存取庫共用的粗粒度提醒，「某個候選工作包能不能挑」的細粒度判斷在 `jsc-sdlc/tools/wp-gate.sh check-deps`，不是這裡。另外會比對歸屬：未結清的 PR 不屬於目前領取的工作包時，`prompt` 多注入一行「那幾支交給領取它的工作階段」，`skill` 在擋下 `analyze`、`maintain` 時一併點名，`plan` 與 `implement` 仍放行但收到同一則提醒。逃生門 `JSC_WP_GATE=off`。這道閘門只讀檔案、不打網路，PR 的真實合併狀態由 `jsc-sdlc/tools/wp-gate.sh` 查證 |
 | `hooks/write-guard.sh` | PreToolUse(Write、Edit、MultiEdit)、PreToolUse(Bash) | 寫入與提交閘門，共三種擋人模式，目前只接在 claude 上；codex、copilot、antigravity 三支已經有可用的 pre-tool hook（見上面「各 CLI 的 pre-tool 接線位置」），只是這三種模式還沒接過去，kiro 則是本來就擋不下來。另有一個不接 hook 的 `release` 解除模式。`stage`：`sdlc-gate.sh` 的階段鎖鎖在 `plan` 或 `analyze` 時，以 exit 2 擋下 `Write`、`Edit`、`MultiEdit`——那兩個階段的產出是計畫頁與分析頁，不是檔案。階段鎖狀態檔沿用 `sdlc-gate.sh` 那一份，這裡只讀不寫。`review`：目前技能是 `jsc-review:code-review` 或 `jsc-review:api-doc` 時擋下寫入，那兩支只回報發現、不改程式碼。技能名先讀環境變數，取不到才讀 `skill-usage.sh` 記下的那一份；沒有「技能結束」事件可讀，所以紀錄超過 `JSC_WRITE_GUARD_TTL` 秒就當那支技能早已跑完。`jsc-review:comment-cleanup` **刻意不擋**：它本來就要改檔，只是限定僅註解行，而精確判定要解析工具參數裡整份新內容再逐語言判斷哪幾行是註解，判錯會擋掉合法的清理，代價比漏擋大，所以那條界線留給技能內文與後續審查。`commit`：擋下「同一道指令把全部變更一次加進索引再提交」，也擋下含簡體字、亂碼或非 UTF-8 編碼的提交訊息（判定整段轉呼叫 `lang-guard.sh`，字表仍是 `hooks/simplified.txt`，這裡不留第二份樣式）。跨兩次工具呼叫的 `git add -A` 不擋：那要記跨呼叫狀態，而被擋下的人沒有辦法讓那個狀態自己消失，閘門會把解除自己的路徑一起鎖掉。`release`：刪掉 `review` 模式認人用的那份紀錄，一律 exit 0，由 `jsc-review:code-review` 與 `jsc-review:api-doc` 在收尾時各呼叫一次。有這個模式是因為那份紀錄記的是「最近一次載入的技能」不是「還在跑的技能」——稽核收尾後呼叫端本來就要動手改，那時紀錄仍寫著稽核技能，TTL 內每一次寫入都被擋，解除路徑只剩逃生門或空等；閘門不得把解除自己的路徑一起鎖掉。逃生門 `JSC_WRITE_GUARD=off`（`release` 不受它影響，清紀錄擋不到任何人） |
 
 Claude 由 `hooks/hooks.json` 自動接線九支 hook；其他 CLI 用 `hooks-install` 技能接線、改裝包裝啟動器，或降級為規則檔。寫進使用者設定的長期命令一律指向 `$JSC_HOME/current/jsc-hooks`，不指向帶版號的 plugin 快取目錄，也不指向開發存取庫。
@@ -155,7 +157,8 @@ Claude 由 `hooks/hooks.json` 自動接線九支 hook；其他 CLI 用 `hooks-in
 | `$JSC_HOME/errors/scan-state/{CLI 代號}-*.offset` | 有 | 正確 | 原生日誌位置與格式依 CLI 不同，掃描位移不能共用。 |
 | `$JSC_HOME/usage/scan-state/{CLI 代號}-*.offset` | 有 | 正確 | 離線回填逐 CLI 掃不同日誌，位移檔以 CLI 前綴隔離。 |
 | `$JSC_HOME/usage/skills.jsonl`、`$JSC_HOME/usage/chains.jsonl` | 每筆有 `cli` 欄位 | 正確 | 統計要能跨 CLI 彙整，也要能用欄位篩選。 |
-| `$JSC_HOME/sessions/` | 以 session id 分 | 正確 | 工作階段 id 由 CLI 或包裝器提供，實質上分離；同 id 才代表同一工作階段。 |
+| `$JSC_HOME/sessions/{CLI 代號}-{sid}.stage` | 有 | 正確 | session id 判不出時會退回 `default`，不分 CLI 就會共用同一支 `default.stage`，一支上的階段鎖會擋到另一支——那不只擋提示，`write-guard.sh` 的 `stage` 模式還會連寫檔一起擋。用檔名前綴不用子目錄，是因為外部工具以單層的 `sessions/*.stage` 盤點階段鎖。舊路徑 `$JSC_HOME/sessions/{sid}.stage` 只作往後相容的讀取，`unlock` 會一併清掉。 |
+| `$JSC_HOME/sessions/` 的其餘檔案（`.start`、`.end`、`.lastskill`） | 以 session id 分 | 正確 | 工作階段 id 由 CLI 或包裝器提供，實質上分離；同 id 才代表同一工作階段。 |
 | `$JSC_HOME/restart-required.d/{CLI 代號}` | 有 | 正確 | 重啟只清當前 CLI，那一支沒有重啟就不能被另一支解除。 |
 | `$JSC_HOME/wp/` | 無 | 正確 | 工作包 PR 狀態屬於存取庫與 PR，不屬於 CLI；換 CLI 也要看到同一支未結清 PR。 |
 | `$JSC_HOME/model-tags.tsv`、`$JSC_HOME/models.conf`、`$JSC_HOME/html-styles.conf` | 無 | 正確 | 這些是全機共用設定，不是檢查紀錄。 |
@@ -166,8 +169,9 @@ 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 回報，免得拿範本蓋掉所有既有列。wiki 位置由 `jsc-gitea` 的 `gitea.sh wiki-repo ERROR` 解析，解析不出來就安靜降級。由操作者手動執行，或由 `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` 狀態檔把工作包歸屬、部署後重啟閘門與寫入提交閘門的每條判定路徑各跑一次並比對結束碼，再用一份暫時的 `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-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` 回報 |
 
 ## 失敗回報範本
@@ -178,7 +182,7 @@ Claude 由 `hooks/hooks.json` 自動接線九支 hook；其他 CLI 用 `hooks-in
 | 範本 | 用途 |
 | --- | --- |
 | `templates/error-page.md` | 單筆 hook 異常頁 `ERROR_{HASH}`，記錄當次失敗的觸發條件、錯誤摘要與處理結果。 |
-| `templates/error-contents.md` | 異常目錄 `ERROR_CONTENTS`，彙整所有異常頁，方便先看最新問題再往下追。 |
+| `templates/error-contents.md` | 異常目錄 `ERROR_CONTENTS`，彙整所有異常頁，方便先看最新問題再往下追。落在目錄專用存取庫，一律 upsert 附加，連結一律寫成 `[{文字}]({連結})` 且先過 `link-check.sh` 驗過才寫。 |
 
 ## Skills 目錄
 
@@ -201,7 +205,8 @@ Claude 由 `hooks/hooks.json` 自動接線九支 hook；其他 CLI 用 `hooks-in
 | 變數 | 用途 | 未設定時 |
 | --- | --- | --- |
 | `JSC_HOME` | Hook 資料目錄 | 預設 `~/.jsc` |
-| `JSC_WIKI_REPO_ERROR` | `ERROR_CONTENTS`、`ERROR_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` |
+| `JSC_WIKI_REPO_ERROR` | 異常內容頁 `ERROR_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO`；還是解不出來就整支 `tools/report-error.sh` 安靜降級，不寫 wiki |
+| `JSC_WIKI_REPO_CONTENTS` | 目錄頁 `ERROR_CONTENTS` 所在的 `{owner}/{repo}`。目錄頁與內容頁分屬兩個不同的存取庫，各解各的 | 退回 `JSC_WIKI_REPO`；還是解不出來就只寫內容頁、跳過目錄頁更新，`tools/report-error.sh` 仍回 exit 0 |
 | `JSC_WIKI_REPO` | 未逐類設定時的共用 wiki `{owner}/{repo}` | `tools/report-error.sh` 安靜降級，不寫 wiki |
 | `COPILOT_HOME` | copilot 的設定根目錄，`hooks/jsc-hooks.json` 與指引檔都寫在它底下 | 預設 `~/.copilot` |
 | `KIRO_HOME` | kiro 的設定根目錄，`agents/jsc.json`、`settings/cli.json` 與 `resources` 的 `skill://` glob 都由它推導 | 預設 `~/.kiro` |
@@ -217,11 +222,13 @@ Claude 由 `hooks/hooks.json` 自動接線九支 hook；其他 CLI 用 `hooks-in
 | `JSC_LANG_GUARD` | 設 `off` 完全略過繁中與編碼檢查（`lang-guard.sh` 三種模式都直接結束） | 啟用檢查 |
 | `JSC_WRITE_GUARD` | 設 `off` 完全略過寫入與提交閘門（`write-guard.sh` 三種模式都直接結束） | 啟用閘門 |
 | `JSC_WRITE_GUARD_TTL` | `write-guard.sh review` 判定「稽核技能還在跑」的時效秒數 | 預設 900 |
+| `JSC_ASSISTANT_HEARTBEAT_TTL` | `hooks/heartbeat.sh check` 判定心跳新鮮的門檻秒數。值不是正整數就退回預設值 | 預設 300（心跳週期 60 秒的五倍） |
+| `JSC_ASSISTANT_GATE` | 設 `off` 完全略過助理運行閘門（`assistant-gate.sh` 一律放行）。判斷擺在載入 `lib.sh` 之前，那支函式庫讀不到時逃生門照樣有效 | 啟用閘門 |
 | `JSC_READONLY` | 設 `1` 時 `tools/wire-cli.sh` 只准 `status` 與 `smoke`，`purge` 與接線一律拒絕並回 exit 6 | 四個用法都可執行 |
 | `JSC_CHANGED_FILE` | 非 Claude CLI 要掃描的檔案路徑，代替 stdin JSON 的 `file_path`，供 `comment-scope.sh` 與 `lang-guard.sh` 使用 | 安靜降級，不掃描 |
 | `JSC_TOOL_COMMAND` | 非 Claude CLI 要判定的 Bash 指令字串，代替 stdin JSON 的 `command`，供 `write-guard.sh commit` 使用 | 安靜降級，不判定 |
 | `JSC_CLI` / `JSC_SESSION_ID` / `JSC_SKILL` / `JSC_TOOL_NAME` | 非 Claude CLI 接線時由 `tools/jsc-wrap.sh` 或接線設定提供，代替 stdin JSON 的 `session_id`、技能名與 `tool_name`（`hooks/skill-name.sh` 也收沒有前綴的 `SKILL`，而且環境變數蓋過負載解析；`write-guard.sh` 也收 `TOOL_NAME`）。`version-guard.sh` 與 `restart-gate.sh` 已經不篩工具名——五支 CLI 的工具名各不相同（`Skill`、`Bash`、`skill`、`view_file`），拿 Claude 那一個當通用條件會把另外四支整批擋在判定之外 | 安靜降級：`JSC_CLI` 取不到就當查不到 CLI，技能名取不到就由負載解析，兩邊都空就放行 |
-| `JSC_MODEL` | `sdlc-gate.sh` 找不到 transcript、hook stdin JSON 與 Codex 本機 session 記錄時的人工覆寫模型 id；回報會標明 `人工覆寫:JSC_MODEL` | 找不到可驗證模型來源時拒絕 `lock`，並列出已檢查來源與修復建議 |
+| `JSC_MODEL` | `sdlc-gate.sh` 在當前 CLI 自己的模型來源都失敗時的人工覆寫模型 id，五支 CLI 都適用；回報會標明 `人工覆寫:JSC_MODEL` | 找不到可驗證模型來源時 `lock` 拒絕、`check` 擋下該輪提示，並列出已檢查來源與兩條逃生門 |
 
 ## 相關 domain
 

hooks/assistant-gate.sh

@@ -0,0 +1,208 @@
+#!/usr/bin/env sh
+# assistant-gate.sh — 助理運行閘門（PreToolUse，matcher: Skill）。
+#
+# 助理在背景跑，前景會話看不到它。技能組有一批規則要靠它落地：巡檢、監控頁、待辦簿。助理停著
+# 的時候那些規則沒有人執行，可是技能照樣叫得起來，看起來一切正常。這道閘門負責讓「助理沒在跑
+# 就繼續用技能」擋在門外。
+#
+# --- 這一版尚未接線 ---
+#
+# 本檔沒有寫進 hooks/hooks.json、hooks/codex-hooks.json 與 tools/wire-cli.sh，五支 CLI 一支都不
+# 會叫到它。要驗證請直接跑 `sh hooks/assistant-gate.sh`，餵環境變數與標準輸入。
+#
+# 接線的前提有兩條，兩條都成立才可以接：
+#   1. 助理已經在跑——`jsc-assist:assistant` 的 start 跑過，排程項目確實裝上了。
+#   2. 心跳穩定——`heartbeat.sh check` 連續多輪都回 0。排程寫進 crontab 不等於 cron 在跑，
+#      WSL 預設不啟動 cron，那種機器上心跳一拍都不會有。
+# 這兩條沒確認就接線，下一次技能呼叫就會被擋，而且擋的是整台機器的五支 CLI。
+#
+# 結束碼（hook 模式，本檔只有這一個模式）：
+#   0  放行，或已經以不靠結束碼的形態擋下。所以「exit 0」在這支腳本有兩種意思。
+#      放行的情況：逃生門 JSC_ASSISTANT_GATE=off、負載裡解不出技能名、解出來的不是 jsc 技能、
+#      命中下方豁免清單、`heartbeat.sh check` 回 0（心跳新鮮）、`heartbeat.sh check` 回 2、5、6
+#      （判不出來，理由見下方「心跳結束碼怎麼處置」）。
+#      已擋下但不靠結束碼的情況：antigravity 的 stdout deny JSON、kiro 的注入警告。
+#   2  擋下該次技能呼叫（claude、codex、copilot，以及認不得的 CLI 代號）。
+#      擋下時的輸出形態由 deny.sh 依當前 CLI 決定，本檔只負責判定與訊息內容：
+#      claude、codex、copilot 走 stderr 加 exit 2；antigravity 走 stdout 的 deny JSON，結束碼
+#      固定 0（那支 CLI 的結束碼語意沒有文件，不可靠）；kiro 擋不下來，改印警告後 exit 0。
+#   本檔沒有其他結束碼，也沒有子命令。帶進來的參數一律忽略。
+#
+# 輸入：技能名一律由 skill-name.sh 從當前 CLI 的負載解析，環境變數 JSC_SKILL、SKILL 優先，
+#   規則與 version-guard.sh、restart-gate.sh 共用同一份。不另外篩工具名：工具名每支 CLI 都不
+#   一樣（Skill、Bash、skill、view_file），拿 Claude 的那一個當通用條件會把另外四支整批擋在判定
+#   之外。
+#
+# --- 這是整組技能唯一一道 fail-closed 閘門 ---
+#
+# 其餘 hook 的原則都是「資料不足就放行」：version-guard.sh 查不到版本放行，restart-gate.sh 讀不
+# 到狀態檔放行。這一道相反——心跳不存在就是助理沒在跑，照要求要擋。心跳檔不存在本身就是證據，
+# 不是「資料不足」。
+#
+# 代價講白：$JSC_HOME 寫不進去的時候（磁碟滿、權限壞、掛載掉了）助理寫不出心跳，這道閘門就把
+# 全機器五支 CLI 的整組技能一起停掉。所以逃生門與豁免清單不是選配，是這道閘門能上線的前提：
+#   逃生門讓人在閘門判錯時當場繞過去，不必先修好環境才動得了技能。
+#   豁免清單讓「啟動助理」與「修環境」這兩條路徑永遠走得通，閘門才不會把解除自己的路徑鎖掉。
+# 這兩樣任何一樣被拿掉或改窄，這道閘門就不可以接線。
+#
+# --- 心跳結束碼怎麼處置 ---
+#
+# 判定一律交給 `heartbeat.sh check`，本檔不自己讀心跳檔——判定寫兩份就會漂移，狀態跟訊息對不上。
+# 那支腳本的六個結束碼逐碼處置如下：
+#   0  新鮮。放行。
+#   1  過期：心跳檔在、ts 也讀得到，但距現在已達門檻。助理跑過、現在停了。擋，訊息講「跑過但
+#      停了」，並講出超過門檻幾秒。
+#   2  腳本沒跑起來（`. lib.sh` 載入失敗時 sh 自己回這一碼）。放行——這是判定機制自己壞了，
+#      不是「助理沒在跑」的證據。
+#   3  心跳檔不存在。助理從沒啟動過。擋，訊息講「從沒啟動過」，要人去啟動。與 1 的處置不同：
+#      使用者要做的事不一樣，併成同一句話會叫錯人去做錯事。
+#   4  心跳檔在、ts 卻讀不出來（缺鍵、空值或不是數字）。**擋。** heartbeat.sh 檔頭寫明呼叫端
+#      一律當成不新鮮處置，絕不可以退回當成新鮮。訊息與 1、3 都不同：那是檔案壞了，不是助理
+#      停了，修法是先 stop 再 start 把心跳檔重建起來。
+#   5  檔案系統操作失敗。**放行。** 理由見下一段。
+#   6  用法錯誤（不認得的子命令，或一個都沒給）。放行——本檔固定送 check，收到 6 就代表
+#      heartbeat.sh 換了介面、或這支閘門叫錯了。那是這一邊的缺陷，不是助理的狀態。
+#
+# 5 為什麼選放行，不選擋：
+#   一、`check` 這條路徑根本不產生 5。5 只由 `write` 與 `clear` 產出。從 check 收到 5，意思是
+#       判定機制本身壞了，跟 2 與 6 同一類，不是「助理沒在跑」。
+#   二、fail-closed 管的是「助理狀態」這一件事實：確定沒有新鮮心跳才擋。5 的意思是連事實都問
+#       不出來，那不在這道閘門的職權裡。
+#   三、最要緊的實務理由：5 正是磁碟滿或權限壞的訊號，而那一刻助理自己也寫不出心跳。擋下去的
+#       結果是全機器整組技能鎖死，出路只剩豁免清單那幾支——可是那幾支同樣要寫 $JSC_HOME
+#       （接線狀態、用量、工作階段），環境壞著它們也修不動。磁碟壞掉要人去清磁碟，不是把技能
+#       組鎖起來。
+#   四、和 4 的差別在有沒有出路：4 是「檔案在、內容壞」，那是確定沒有可信心跳的證據，而且修法
+#       就在豁免清單裡（stop 再 start），擋得起；5 是「檔案系統問不出來」，擋了沒有出路。
+#   代價據實寫：磁碟壞掉時這道閘門會安靜放行，助理沒在跑也擋不到。那是刻意的取捨——這道閘門
+#   不是磁碟監控，環境壞掉由 /jsc-cli:doctor 抓。
+#
+# 豁免（這些技能永遠放行，改動前想清楚後果）：
+#   jsc-assist:*            啟動助理本身就是一次技能呼叫。少了這一條，助理永遠啟動不了，整組
+#                           技能鎖死。這是雞生蛋，清單裡最要緊的一條
+#   jsc-hooks:repair        修 hook 的唯一路徑。修 hook 的技能被 hook 擋下，就沒有任何方法把
+#                           hook 修回來，閘門等於把解除自己的路徑一起鎖掉
+#   jsc-hooks:hooks-install 重新接線的唯一路徑。這道閘門接錯了要靠它拆掉
+#   jsc-cli:doctor          環境健檢。心跳寫不出來多半是環境問題，查不了就修不了
+#   jsc-cli:setup           修設定的唯一路徑，doctor 找到的東西要靠它落地
+#   jsc-cli:deploy          部署技能組。助理主體本身也是技能，裝不上就啟動不了
+#   jsc-gitea:wiki          助理巡檢一輪要先把結果寫進 MONITOR_{HASH}，寫不成那一輪就不寫心跳
+#                           （no record, no heartbeat）。擋了它，巡檢永遠跑不完、心跳永遠不出現，
+#                           助理再也啟動不了。jsc-hooks:repair 的第一步也是讀 ERROR_{HASH}，讀
+#                           不到就中止
+#   jsc-ask:ask             上面幾支都要問使用者：assistant 要問做哪一個操作，setup 與 deploy
+#                           要問模式。擋了它，start 連要不要跑都問不出來
+#   jsc-git:commit          jsc-hooks:repair 收尾要提交，擋了修好的東西進不了版本控制
+#   jsc-git:pr              同上，repair 規定收尾要對 develop 開 PR，擋了修復做一半
+#   jsc-cli:models          jsc-cli:setup 遇到 model-tags.tsv 不見時要靠它補回來，擋了那一項修不完
+#
+# 清單認的是技能名，不是呼叫鏈：豁免技能轉呼叫的下一層若不在清單上，那一層照樣會被擋。後五支
+# （wiki、ask、commit、pr、models）就是為了這件事補進來的——它們自己不是啟動助理的主體，但前
+# 六支少了它們就走不完。jsc-gitea:wiki 是這裡面最容易漏的一支：只豁免 jsc-assist:* 看起來就夠
+# 了，可是巡檢那一輪會轉呼叫 wiki 去寫監控頁，寫不成就不寫心跳，於是「沒心跳 → 擋 wiki →
+# 巡檢不完 → 還是沒心跳」自己咬住自己，永遠解不開。
+#
+# 清單刻意不收 jsc-log:worklog 與 jsc-log:learn：那兩支是部署收尾的規則，跟「把助理啟動起來」
+# 這條路徑無關。fail-closed 閘門的豁免清單只收解鎖路徑，收寬了這道閘門就等於沒有。
+#
+# 逃生門：JSC_ASSISTANT_GATE=off 完全略過這道閘門。
+#
+# 註：逃生門的判斷擺在載入 lib.sh 之前，這一點與 restart-gate.sh 不同。lib.sh 讀不到時 sh 會就地
+#   結束並回 2，接在 PreToolUse 上就是無聲擋下每一次技能呼叫；這道閘門是 fail-closed 的，那個
+#   結果方向上不算錯，但逃生門也跟著跑不到，人就沒有辦法自己繞過去。所以先看逃生門，再載入。
+#   hooks/skill-name.sh、hooks/deny.sh 與 hooks/heartbeat.sh 都以子行程呼叫，讀不到只會讓判定
+#   降級成放行，不會反過來擋人。
+
+# 逃生門先看。結束前把標準輸入讀乾淨：不讀就結束，宿主 CLI 會寫進斷掉的管線。
+if [ "${JSC_ASSISTANT_GATE:-}" = "off" ]; then
+  [ -t 0 ] || cat >/dev/null 2>&1
+  exit 0
+fi
+
+HERE=$(dirname "$0"); . "$HERE/lib.sh"
+hook_trace "assistant-gate ${1:-}"
+
+read_stdin
+
+# 技能名解析：交給 skill-name.sh。輸出固定是「{domain}<TAB>{技能名}」；用 awk 判 NF==2 才取值，
+# 少一欄就當成解析不出來，免得沒有定位字元時 cut -f2 把整行當成技能名，拼出一個不存在的技能名
+# 去比對豁免清單。
+sn=$(printf '%s' "$STDIN_JSON" | sh "$HERE/skill-name.sh" "$(cli_name)" 2>/dev/null)
+sn_domain=$(printf '%s\n' "$sn" | awk -F'\t' 'NF == 2 { print $1; exit }')
+sn_name=$(printf '%s\n' "$sn" | awk -F'\t' 'NF == 2 { print $2; exit }')
+[ -n "$sn_domain" ] && [ -n "$sn_name" ] || exit 0
+skill="jsc-$sn_domain:$sn_name"
+
+# 豁免清單（理由見檔頭）
+case "$skill" in
+  jsc-assist:*|jsc-hooks:repair|jsc-hooks:hooks-install|jsc-cli:doctor|jsc-cli:setup|jsc-cli:deploy|jsc-gitea:wiki|jsc-ask:ask|jsc-git:commit|jsc-git:pr|jsc-cli:models)
+    exit 0 ;;
+esac
+
+# 心跳判定。補 </dev/null：heartbeat.sh 不讀標準輸入，但這裡的標準輸入已經被 read_stdin 收乾，
+# 留著空管線給子行程沒有意義，明確關掉才不會有人往回接一條會等的路。
+sh "$HERE/heartbeat.sh" check </dev/null 2>/dev/null
+hb=$?
+case "$hb" in
+  0) exit 0 ;;         # 新鮮
+  1|3|4) ;;            # 過期、不存在、時間戳壞掉：落到下面組訊息並擋下
+  *) exit 0 ;;         # 2、5、6：判不出來就放行，逐碼理由見檔頭
+esac
+
+# 訊息細節一律取自 `heartbeat.sh report`，本檔不自己解析心跳檔：判定與訊息共用同一份探測結果，
+# 兩邊各讀一次會出現「擋的理由」與「印的數字」對不上。
+REPORT=$(sh "$HERE/heartbeat.sh" report </dev/null 2>/dev/null)
+
+# report 是一行、欄位以空白分隔。除了 file 以外每一欄都不含空白，換行切開再取最穩。
+rep_field() { # $1=鍵名（file 除外）
+  printf '%s' "$REPORT" | tr ' ' '\n' | sed -n "s/^$1=//p" | head -n1
+}
+# file 擺在最後，路徑可能含空白，所以取「file= 之後的全部」。
+rep_file() {
+  printf '%s' "$REPORT" | sed -n 's/.*[[:space:]]file=//p'
+}
+
+hb_age=$(rep_field age)
+hb_ttl=$(rep_field ttl)
+hb_pid=$(rep_field pid)
+hb_file=$(rep_file)
+[ -n "$hb_file" ] || hb_file="$JSC_HOME/assistant/heartbeat"
+
+# 超過門檻幾秒。兩個值都是純數字才算，算不出來就不印那一段——寧可少講一個數字，也不要印出
+# 算壞的值。
+hb_over=""
+case "$hb_age$hb_ttl" in
+  ''|*[!0-9]*) ;;
+  *) hb_over=$(( hb_age - hb_ttl )) ;;
+esac
+
+# 三種狀態的第一句話各寫一份。使用者要做的事不一樣：沒啟動過的要去啟動，跑過停了的要去查為
+# 什麼停，檔案壞了的要去重建。併成同一句就會叫錯人做錯事。
+case "$hb" in
+  3) first=$(printf '[jsc][助理閘門][ERR]：助理沒有在跑。心跳檔 %s 不存在，助理從沒啟動過。技能 /%s 這一次呼叫已擋下。' \
+       "$hb_file" "$skill") ;;
+  1) first=$(printf '[jsc][助理閘門][ERR]：助理跑過，現在停了。上次心跳是 %s 秒前，門檻 %s 秒，已經超過門檻 %s 秒（寫入者 pid=%s，心跳檔 %s）。技能 /%s 這一次呼叫已擋下。' \
+       "${hb_age:-不明}" "${hb_ttl:-不明}" "${hb_over:-不明}" "${hb_pid:-不明}" "$hb_file" "$skill") ;;
+  *) first=$(printf '[jsc][助理閘門][ERR]：助理狀態判不出來。心跳檔 %s 在，但 ts 欄位缺了、是空的、或不是數字——檔案壞了，不是助理停了。一律當成沒有心跳處置。技能 /%s 這一次呼叫已擋下。' \
+       "$hb_file" "$skill") ;;
+esac
+
+# 第二句：怎麼把助理弄回來。三種狀態的做法也不同。
+case "$hb" in
+  3) second='啟動助理：/jsc-assist:assistant，操作選 start。它會先跑一輪巡檢，把結果寫上監控頁，再把排程項目裝起來；心跳是那一輪跑完才寫的。' ;;
+  1) second='重新啟動助理：/jsc-assist:assistant，操作選 start；先用 status 看排程項目還在不在。排程寫進 crontab 不等於 cron 在跑，WSL 預設不啟動 cron，那種機器要先 sudo service cron start，而且每次重開機都要再跑一次。' ;;
+  *) second='重建心跳：/jsc-assist:assistant，操作先選 stop 再選 start。stop 會把壞掉的心跳檔刪掉，start 跑完一輪巡檢才寫出新的一份。' ;;
+esac
+
+# 擋人輸出交給 deny.sh：形態依 CLI 而定，本檔只組訊息。四段訊息整段走同一條管線送過去，
+# antigravity 那一支才有辦法把它們壓成同一個 reason 字串；分次呼叫會做出好幾份 deny JSON，
+# 那支 CLI 只認第一份，後面三段使用者永遠看不到。
+{ printf '%s\n' "$first"
+  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 $?

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
 
@@ -81,7 +82,13 @@ scan_file() { # $1=檔案路徑；命中就把報告印到 stdout 並回傳 1，
     hit '(^|[^[:alnum:]_/])#[0-9]+'                                             '議題編號（#123）'
     hit '(^|[^[:alnum:]_])![0-9]+'                                              'PR、MR 編號（!45）'
     hit '[A-Z]{2,6}-[0-9]{1,6}'                                                 '工作包、故事、驗收、測試案例、變更單、議題編號（前綴加流水號）'
-    hit '(QUESTION|PLAN|ANALYZE|DELIVER|MAINTAIN|REPO|LOG|LEARN|ERROR|CHECK|REPORT)_([A-Z0-9]{8}|CONTENTS)' 'jsc wiki 頁面編號'
+    # 頁名樣式：十五種頁型，尾段是 CONTENTS（目錄頁）、40 碼大寫十六進位（內容頁），
+    # 或尚未遷移的舊頁編號。舊頁那兩條要留著，不然舊頁編號會漏偵測。
+    # 舊頁為什麼有 H 開頭這一條：舊的短碼演算法只要首碼落在 0-9ABC 就改寫成 H 加原前 7 碼，
+    # 十六個十六進位首碼有十三個會命中，所以既有舊頁名大多是 H 開頭，只收 [0-9A-F]{8} 會漏掉。
+    # 這條式子在別處另有兩份各自獨立的定義，稽核時才比對一致。刻意不共用函式：hook 要能
+    # 自足執行，執行期相依別的 plugin 路徑，那條路徑一缺，整支 hook 就掃不動了。
+    hit '(QUESTION|PLAN|ANALYZE|DELIVER|MAINTAIN|REPO|LOG|LEARN|ERROR|CHECK|REPORT|SKILLSET|TOOLING|MONITOR|CONTENTS)_(CONTENTS|[0-9A-F]{8}|H[0-9A-F]{7}|[0-9A-F]{40})' 'jsc wiki 頁面編號'
     hit '(todo|TODO|待辦)[[:space:]]*#?[0-9]+'                                  'TDD 待辦編號'
     hit '([Ss]print|里程碑|[Mm]ilestone)[[:space:]]*[0-9]+'                     'Sprint、里程碑編號'
     hit '(^|[^[:alnum:].])v[0-9]+\.[0-9]+|版本[[:space:]]*v?[0-9]+\.[0-9]+'     '版本號'

hooks/heartbeat.sh

@@ -0,0 +1,177 @@
+#!/usr/bin/env sh
+# heartbeat.sh — 助理心跳檔的讀寫工具。
+#
+# 助理在背景跑，前景會話看不到它。心跳檔就是它還在跑的唯一證據：助理主體與系統排程每 60 秒
+# 寫一次，`jsc-assist:assistant` 與擋人訊息讀這一份，判斷助理在不在。
+#
+# 這支不是 hook，不接在任何事件上，只被工具端呼叫，所以它擋不到任何人。它只做判定，擋不擋
+# 由呼叫端自己決定——助理不參與閘門判定，只負責維持心跳。
+#
+# 用法（四個子命令都不讀標準輸入，理由見下方「不讀標準輸入」）：
+#   heartbeat.sh write    寫入心跳檔，四個欄位一次寫齊，目錄不存在就建。由助理主體與系統
+#                         排程呼叫。
+#   heartbeat.sh check    判定心跳新不新鮮。什麼都不印，結果只在結束碼；要細節請跑 report。
+#   heartbeat.sh report   印一行心跳現況，格式見下方「report 輸出格式」。
+#   heartbeat.sh clear    刪除心跳檔。由助理的 stop 呼叫。檔案不存在也算成功。
+#
+# 結束碼:
+#   0  check 判定新鮮（state=fresh）；write 寫成功；clear 清完，檔案已經不在；report 印完
+#   1  check：心跳檔在、ts 也讀得到，但距現在已達門檻（state=stale）。助理跑過，現在停了。
+#      訊息要叫人去查助理為什麼停
+#   2  保留給「腳本沒跑起來」：`. lib.sh` 載入失敗時 sh 自己回這一碼（見最下方註）。判定路徑
+#      刻意不用 2，兩者才分得開
+#   3  check：心跳檔不存在（state=absent）。助理從沒啟動過。處置與 1 不同，訊息要叫人去啟動
+#   4  check：心跳檔在、ts 卻讀不出來（state=invalid，缺鍵、空值或不是數字）。檔案壞了，不是
+#      助理停了。呼叫端一律當成不新鮮處置，絕不可以退回當成新鮮
+#   5  檔案系統操作失敗：write 寫不進去（磁碟滿、權限壞、目錄建不起來），或 clear 刪不掉、
+#      檔案還在。這是嚴重狀況——助理沒有心跳就會被自己那道閘門擋掉，所以一定要吵出來，
+#      不能安靜當成成功
+#   6  用法錯誤：不認得的子命令，或一個子命令都沒給。刻意不與上面任何一種正常狀態共用碼，
+#      共用了呼叫端就分不出「助理沒在跑」與「這支腳本被叫錯」
+#
+# --- 只看 ts，絕不看 pid 存活 ---
+#
+# 新鮮的判準只有一條：心跳檔存在，而且 ts 距現在小於門檻秒數。pid 一律不拿來判定。
+# 一台機器上五支 CLI 各自是獨立行程，助理也可能跑在容器裡，彼此看不到對方的 pid：拿
+# `kill -0` 去問，看不到的行程一律回失敗，活著的助理會被判成停了；pid 還會被回收，別人的
+# 行程剛好接到同一個號碼，就反過來把停掉的助理判成還在跑。兩種誤判都不會報錯，查起來也沒有
+# 線索。pid 只寫進檔案當擋人訊息的線索，讓人自己去查那個行程。
+#
+# --- 門檻為什麼是 300 ---
+#
+# 心跳週期是 60 秒，門檻取五倍。一次網路或磁碟卡頓讓某一拍沒寫成，後面還有四拍補得回來，
+# 不會誤判成助理停了。門檻用環境變數 JSC_ASSISTANT_HEARTBEAT_TTL 覆寫，單位是秒；值不是
+# 正整數就退回 300——環境變數打錯字不該讓判定整個歪掉。
+#
+# --- 不讀標準輸入 ---
+#
+# 這支是被工具端呼叫的腳本，四個子命令一律不讀 stdin。理由與 restart-gate.sh 的子命令相同：
+# read_stdin 在標準輸入是管線又沒人關閉時會一直等，工具端呼叫就整支卡死。
+#
+# --- 狀態檔格式 ---
+#
+# $JSC_HOME/assistant/heartbeat（JSC_HOME 未設定時為 ~/.jsc），純文字 key=value，一行一欄位，
+# 順序不拘，不認得的鍵一律忽略：
+#   ts={epoch 秒數}    寫入當下的時間。判定只看這一欄
+#   pid={行程 id}      寫入者的行程 id。只當擋人訊息的線索
+#   cli={CLI 代號}     寫入者是哪一支 CLI，取自 cli_name()
+#   session={id}       寫入者的工作階段 id，取自 session_id()
+# 寫入走「先寫暫存檔、再改名」：改名是原子的，讀的那一端永遠讀到完整的一份。直接覆寫的話，
+# 剛好讀到寫一半的檔案會少掉 ts，判定就從 fresh 掉成 invalid，助理明明活著卻被說成壞了。
+#
+# --- report 輸出格式 ---
+#
+# 固定一行，鍵的順序固定，欄位以空白分隔。鍵一個都不會少，缺值就只留鍵名，呼叫端不必判斷
+# 有沒有這一欄。路徑擺最後，路徑含空白時才不會把後面的欄位吃掉：
+#   state={fresh|stale|invalid|absent} ts={epoch} age={秒} ttl={秒} pid={} cli={} session={} file={路徑}
+# state 的四種值與 check 的結束碼一一對應：fresh=0、stale=1、absent=3、invalid=4。
+# 例（心跳新鮮）：
+#   state=fresh ts=1756684800 age=42 ttl=300 pid=31415 cli=claude session=a1b2c3 file=/root/.jsc/assistant/heartbeat
+# 例（心跳檔不存在）：
+#   state=absent ts= age= ttl=300 pid= cli= session= file=/root/.jsc/assistant/heartbeat
+# ts 不是數字時 ts 與 age 兩欄都印空的：那個值是垃圾，原樣印出來會夾帶空白把欄位切歪。
+#
+# 註：本檔以 `. "$HERE/lib.sh"` 載入共用函式，沒有接 `|| true`。載入失敗時 sh 會就地結束並回
+#   2。這一點的後果與 restart-gate.sh 不同：那支接在 PreToolUse 上，回 2 等於無聲擋下每一次
+#   技能呼叫；這支沒接任何 hook，回 2 只會讓呼叫端收到「心跳判不出來」，擋不到任何人。
+HERE=$(dirname "$0"); . "$HERE/lib.sh"
+hook_trace "heartbeat ${1:-}"
+
+# 這支永遠不讀標準輸入，但 session_id() 會去看 STDIN_JSON。先設成空字串，讓它直接走環境
+# 變數那條路，不會因為變數沒定義而拿到不確定的值。
+STDIN_JSON=""
+
+STATE_DIR="$JSC_HOME/assistant"
+STATE="$STATE_DIR/heartbeat"
+
+DEFAULT_TTL=300
+
+# 門檻秒數。環境變數不是正整數就退回預設值，理由見檔頭「門檻為什麼是 300」。
+ttl() {
+  _t="${JSC_ASSISTANT_HEARTBEAT_TTL:-}"
+  case "$_t" in
+    ''|*[!0-9]*) printf '%s' "$DEFAULT_TTL"; return 0 ;;
+  esac
+  if [ "$_t" -gt 0 ] 2>/dev/null; then printf '%s' "$_t"; else printf '%s' "$DEFAULT_TTL"; fi
+}
+
+# 從心跳檔取一個欄位；檔案讀不到或欄位不存在就不輸出。
+field() { # $1=鍵名
+  [ -f "$STATE" ] && [ -r "$STATE" ] || return 0
+  sed -n "s/^$1=//p" "$STATE" 2>/dev/null | head -n1
+}
+
+# 判定心跳狀態，印出「{state}<TAB>{ts}<TAB>{age}」，後兩欄在 absent 與 invalid 時留空。
+# check 與 report 共用這一份：兩邊各判一次就會漂移，狀態與訊息對不上。
+probe() {
+  if [ ! -f "$STATE" ] || [ ! -r "$STATE" ]; then
+    printf 'absent\t\t\n'; return 0
+  fi
+  _ts=$(field ts)
+  case "$_ts" in
+    ''|*[!0-9]*) printf 'invalid\t\t\n'; return 0 ;;
+  esac
+  # 去掉開頭的 0：POSIX 算術把 08 當八進位，會直接報錯，錯完 age 是空的，判定就整條歪掉。
+  while :; do
+    case "$_ts" in 0?*) _ts=${_ts#0} ;; *) break ;; esac
+  done
+  _age=$(( $(now_epoch) - _ts ))
+  # age 是負的代表 ts 在未來，那是時鐘偏移，不是助理停了，照樣算新鮮。
+  if [ "$_age" -lt "$(ttl)" ]; then _st=fresh; else _st=stale; fi
+  printf '%s\t%s\t%s\n' "$_st" "$_ts" "$_age"
+}
+
+usage() {
+  printf 'usage: heartbeat.sh {write|check|report|clear}\n' >&2
+  exit 6
+}
+
+case "${1:-}" in
+  write)
+    # 心跳檔的位置被目錄或別的東西佔住時要當場失敗。`mv` 遇到目標是目錄會把暫存檔搬進去，
+    # 搬得成功、心跳檔卻永遠不存在，寫的那一端拿到 0，讀的那一端說助理沒啟動過。
+    if [ -e "$STATE" ] && [ ! -f "$STATE" ]; then
+      printf '[jsc][助理心跳][ERR]：%s 不是一般檔案，心跳寫不進去。\n' "$STATE" >&2
+      exit 5
+    fi
+    mkdir -p "$STATE_DIR" 2>/dev/null || true
+    _tmp="$STATE.tmp.$$"
+    # stderr 先轉走再開檔：順序反過來的話，開檔失敗的訊息是 sh 自己印的，那時 stderr 還沒
+    # 轉走，會漏到呼叫端的畫面上，蓋掉下面那句講得清楚的錯誤訊息。
+    if ! printf 'ts=%s\npid=%s\ncli=%s\nsession=%s\n' \
+        "$(now_epoch)" "$$" "$(cli_name)" "$(session_id)" 2>/dev/null > "$_tmp"; then
+      rm -f "$_tmp" 2>/dev/null
+      printf '[jsc][助理心跳][ERR]：寫不進 %s，助理這一拍沒有心跳。\n' "$STATE" >&2
+      exit 5
+    fi
+    if ! mv -f "$_tmp" "$STATE" 2>/dev/null; then
+      rm -f "$_tmp" 2>/dev/null
+      printf '[jsc][助理心跳][ERR]：換不上 %s，助理這一拍沒有心跳。\n' "$STATE" >&2
+      exit 5
+    fi
+    exit 0 ;;
+  check)
+    case "$(probe | cut -f1)" in
+      fresh) exit 0 ;;
+      stale) exit 1 ;;
+      absent) exit 3 ;;
+      *) exit 4 ;;
+    esac ;;
+  report)
+    _p=$(probe)
+    printf 'state=%s ts=%s age=%s ttl=%s pid=%s cli=%s session=%s file=%s\n' \
+      "$(printf '%s' "$_p" | cut -f1)" \
+      "$(printf '%s' "$_p" | cut -f2)" \
+      "$(printf '%s' "$_p" | cut -f3)" \
+      "$(ttl)" "$(field pid)" "$(field cli)" "$(field session)" "$STATE"
+    exit 0 ;;
+  clear)
+    rm -f "$STATE" 2>/dev/null
+    # 刪不掉就要講出來：檔案還在，別人讀到的心跳會說助理還在跑。
+    if [ -e "$STATE" ]; then
+      printf '[jsc][助理心跳][ERR]：刪不掉 %s，心跳檔還在。\n' "$STATE" >&2
+      exit 5
+    fi
+    exit 0 ;;
+  *) usage ;;
+esac

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
 

hooks/lib.sh

@@ -2,8 +2,9 @@
 # lib.sh — jsc hooks 共用函式。所有 hook 腳本 source 此檔。
 # 輸入相容：Claude 式 stdin JSON、或環境變數（codex/copilot/antigravity/kiro 接線時設定）。
 # 缺資料時安靜降級，hook 預設 exit 0，不可中斷宿主 CLI。
-# 唯一例外：sdlc-gate.sh check 在「SDLC 階段鎖存在且模型不符」時會 exit 2 擋下該輪提示；
-# 其餘情況（無鎖、資料不足無法判定）仍照舊 exit 0。
+# 唯一例外：sdlc-gate.sh check 在「SDLC 階段鎖存在，而且不知道目前模型的能力」時會 exit 2
+# 擋下該輪提示。不知道能力有三種：判不出是哪一支 CLI、判不出模型、模型不在能力標籤表上。
+# 這是刻意的 fail-closed——放行等於閘門不存在。沒有階段鎖時仍照舊 exit 0。
 #
 # 結束碼：不適用。本檔是被 source 的共用函式庫，不是可執行入口，內部一次 exit 都沒有。
 #   載入成功回 0（最後一行是函式定義）；拿 `sh lib.sh` 直接跑也只是定義完函式回 0，不做事。
@@ -31,12 +32,58 @@ json_str() { # $1=欄位名
 }
 
 # 目前 session id：stdin JSON > 環境變數 > 固定值
+#
+# 環境變數這一段的順序：
+#   JSC_SESSION_ID           jsc 自己的指定值（tools/jsc-wrap.sh 會設），人工指定優先於偵測。
+#   CLAUDE_CODE_SESSION_ID   claude 實際匯出的名字，實測確認過。
+#   CLAUDE_SESSION_ID        只留作往後相容，排在實測名之後。這個名字在目前的 claude 上並不
+#                            存在，兩個都設到的話，該信的是實測看得到的那一個；只設到這一個
+#                            的版本仍然退得下來，所以留著不會有損失。
+# 為什麼這一條要修：退路鏈原本只找 CLAUDE_SESSION_ID，那個名字取不到值，於是沒有 stdin 的
+# 執行路徑（技能以 Bash 呼叫 sdlc-gate.sh lock）一律退回 default，而 hook 有 stdin、拿得到
+# 真正的 id。同一個工作階段的兩條路徑因此算出兩支不同的狀態檔，階段鎖上了也永遠對不上。
+# 這裡只補退路鏈的變數名，不動取值順序以外的行為：其他 CLI 的變數名沒有實測過，猜一個填進來
+# 只會多一個錯誤來源。
 session_id() {
   sid=$(json_str session_id)
-  [ -n "$sid" ] || sid="${JSC_SESSION_ID:-${CLAUDE_SESSION_ID:-default}}"
+  [ -n "$sid" ] || sid="${JSC_SESSION_ID:-${CLAUDE_CODE_SESSION_ID:-${CLAUDE_SESSION_ID:-default}}}"
   printf '%s' "$sid"
 }
 
+# 階段鎖狀態檔名要用的 CLI 代號。這個值直接拼進檔名，所以不像代號的字元一律換掉；
+# 帶斜線或空白的值會把檔案寫到別的地方去，理由與 restart-gate.sh 的做法相同。
+stage_state_cli() {
+  cli_name | sed 's/[^A-Za-z0-9._-]/_/g'
+}
+
+# 階段鎖狀態檔的舊路徑：$JSC_HOME/sessions/{sid}.stage。只作往後相容的讀取來源，
+# 以及 unlock 的清除對象，新的寫入一律不走這裡。
+stage_state_legacy_file() {
+  printf '%s/sessions/%s.stage' "$JSC_HOME" "$(session_id)"
+}
+
+# 階段鎖狀態檔（寫入用）：$JSC_HOME/sessions/{cli}-{sid}.stage。
+# 為什麼要帶 CLI 代號：session_id() 判不出工作階段時會退回 default，各 CLI 於是共用同一支
+# default.stage，一支上的階段鎖就會擋到另一支。那不只擋提示——write-guard.sh 的 stage 模式
+# 在 plan 或 analyze 持鎖時連 Write、Edit、MultiEdit 一起擋掉。
+# 為什麼用檔名前綴而不是子目錄：外部工具以單層的 sessions/*.stage 盤點階段鎖，改成子目錄
+# 會讓每一支鎖從那些盤點裡整批消失；前綴照樣列得到，只是多一段代號。
+stage_state_file() {
+  printf '%s/sessions/%s-%s.stage' "$JSC_HOME" "$(stage_state_cli)" "$(session_id)"
+}
+
+# 階段鎖狀態檔（讀取用）：新路徑優先，沒有才回舊路徑。舊檔記的是實際工作，只讀不搬也不刪。
+# 兩邊都沒有時回新路徑，讓呼叫端一律用「檔案在不在」判斷有沒有鎖。
+stage_state_read_file() {
+  _sf=$(stage_state_file)
+  if [ -f "$_sf" ]; then
+    printf '%s' "$_sf"
+  else
+    _so=$(stage_state_legacy_file)
+    if [ -f "$_so" ]; then printf '%s' "$_so"; else printf '%s' "$_sf"; fi
+  fi
+}
+
 MODEL_SOURCE_CHECKS=""
 
 model_checked() {
@@ -75,9 +122,17 @@ codex_session_file() { # $1=CODEX_HOME $2=session id
     find "$ch/sessions" -type f -name "*$sid*.jsonl" 2>/dev/null | sort | tail -n 1
     return 0
   fi
-  files=$(find "$ch/sessions" -type f -name '*.jsonl' 2>/dev/null)
-  [ -n "$files" ] || return 1
-  printf '%s\n' "$files" | xargs ls -t 2>/dev/null | head -n 1
+  # 全樹最新的一支。原本寫成 `xargs ls -t | head -n 1`，那是錯的：xargs 會依參數長度分批，
+  # ls -t 只在自己那一批裡排序，取到的是「第一批裡最新的」而不是全域最新。改成讓 find 一併
+  # 印出修改時間，所有檔案在同一輪比較，批次邊界就影響不到結果。
+  newest=$(find "$ch/sessions" -type f -name '*.jsonl' -printf '%T@\t%p\n' 2>/dev/null \
+    | sort -rn | head -n 1 | cut -f2-)
+  # find 沒有 -printf（非 GNU）時退回路徑排序。codex 的 session 依「年/月/日」分目錄，
+  # 檔名又以 ISO 時間開頭，字典序等同時間序，仍然是全域比較，不會被分批切斷。
+  [ -n "$newest" ] || newest=$(find "$ch/sessions" -type f -name '*.jsonl' 2>/dev/null \
+    | sort | tail -n 1)
+  [ -n "$newest" ] || return 1
+  printf '%s\n' "$newest"
 }
 
 codex_model() {
@@ -98,9 +153,21 @@ codex_model() {
   return 1
 }
 
+# 目前模型的判定。輸出單行「{模型 id}<TAB>{來源}<TAB>{已檢查來源}」，判不出時前兩欄留空。
+#
+# 偵測鏈依 CLI 分流：一支 CLI 只讀自己的紀錄。兩個理由。
+#   一是正確性：跨過去讀別支的紀錄，拿到的是別支的模型，用它判定這一支等於沒有判準。
+#   二是速度：別支的 session 目錄可能有上千個檔案，每一輪 hook 都掃一次會把宿主 CLI 拖住。
+# 判不出是哪一支 CLI 時不猜任何來源——不知道是誰，就不知道該讀誰的紀錄。
+# JSC_MODEL 這個人工覆寫對所有 CLI 都保留，而且一律排在最後：可驗證的紀錄優先於人工宣告。
 current_model_report() {
   MODEL_SOURCE_CHECKS=""
+  _mcli=$(cli_name)
+  model_checked "JSC_CLI:$_mcli"
 
+  case "$_mcli" in
+    claude)
+      # transcript 是 claude 自己寫下的執行紀錄，也是唯一逐輪更新的來源。
       tp=$(json_str transcript_path)
       [ -n "$tp" ] || tp="${JSC_TRANSCRIPT_PATH:-}"
       model_checked "transcript_path:${tp:-未提供}"
@@ -109,17 +176,34 @@ current_model_report() {
         [ -n "$m" ] && { printf '%s\t%s\t%s\n' "$(model_clean "$m")" "transcript:$tp" "$MODEL_SOURCE_CHECKS"; return 0; }
       fi
 
+      model_checked "hook-stdin:model/model_id/model_slug/modelName/current_model/currentModel"
+      m=$(json_model_value "$STDIN_JSON")
+      [ -n "$m" ] && { printf '%s\t%s\t%s\n' "$(model_clean "$m")" "hook-stdin" "$MODEL_SOURCE_CHECKS"; return 0; }
+      ;;
+    codex)
+      # hook 負載是這一輪由 codex 自己餵進來的，不是別支 CLI 的紀錄，所以照收；
+      # 而且它反映當下這一輪，比落在檔案裡的紀錄新，排在 session 記錄前面。
       model_checked "hook-stdin:model/model_id/model_slug/modelName/current_model/currentModel"
       m=$(json_model_value "$STDIN_JSON")
       [ -n "$m" ] && { printf '%s\t%s\t%s\n' "$(model_clean "$m")" "hook-stdin" "$MODEL_SOURCE_CHECKS"; return 0; }
 
-  model_checked "codex:${CODEX_HOME:-$HOME/.codex}、~/.codex/sessions、history.jsonl、session_index.jsonl"
+      model_checked "codex:${CODEX_HOME:-$HOME/.codex}/sessions、history.jsonl、session_index.jsonl"
       cm=$(codex_model 2>/dev/null || true)
       if [ -n "$cm" ]; then
         m=$(printf '%s' "$cm" | cut -f1)
         src=$(printf '%s' "$cm" | cut -f2)
         [ -n "$m" ] && { printf '%s\t%s\t%s\n' "$(model_clean "$m")" "$src" "$MODEL_SOURCE_CHECKS"; return 0; }
       fi
+      ;;
+    copilot|antigravity|kiro)
+      # 這三支由 tools/jsc-wrap.sh 包起來跑，只餵得到環境變數：沒有 transcript、沒有 hook
+      # 負載，本機也沒有可讀的模型紀錄。這裡如實記成「沒有來源」，不去翻別支 CLI 的檔案。
+      model_checked "$_mcli：本機沒有可讀的模型紀錄，只認 JSC_MODEL"
+      ;;
+    *)
+      model_checked "未知 CLI：判不出是哪一支，不採用任何自動來源"
+      ;;
+  esac
 
   model_checked "JSC_MODEL"
   if [ -n "${JSC_MODEL:-}" ]; then
@@ -130,10 +214,18 @@ current_model_report() {
   printf '\t\t%s\n' "$MODEL_SOURCE_CHECKS"
 }
 
-# 目前 CLI 名稱：環境變數 > 依 stdin 特徵猜測 > unknown
+# 目前 CLI 名稱：環境變數 > 依環境特徵判斷 > unknown
+#
+# claude 的判準有三個，任一個成立就算。理由與 session_id() 那條退路鏈同源：CLAUDE_PLUGIN_ROOT
+# 只有 plugin 接線的 hook 執行環境才有，技能以 Bash 工具呼叫腳本時並不存在，於是同一個工作
+# 階段的兩條路徑一條認得出 claude、一條回 unknown，狀態檔名跟著分岔。CLAUDECODE 與
+# CLAUDE_CODE_SESSION_ID 兩者在工具呼叫的環境裡都看得到（實測確認），補上去兩條路徑才算得出
+# 同一個代號。只補 claude 這一支：其他 CLI 的環境特徵沒有實測過，猜一個填進來只會多一個
+# 錯誤來源，那幾支本來就由接線設定明確帶 JSC_CLI。
 cli_name() {
   if [ -n "${JSC_CLI:-}" ]; then printf '%s' "$JSC_CLI"
-  elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ]; then printf 'claude'
+  elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] || [ -n "${CLAUDECODE:-}" ] \
+    || [ -n "${CLAUDE_CODE_SESSION_ID:-}" ]; then printf 'claude'
   else printf 'unknown'; fi
 }
 
@@ -171,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
+}

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 $?

hooks/sdlc-gate.sh

@@ -3,18 +3,37 @@
 #
 # 判準是階段的「能力標籤」，不是模型名稱：
 #   - 標籤資料讀 $JSC_HOME/model-tags.tsv，由 jsc-cli/tools/model-tags.sh sync 產生。
-#   - 目前模型 id 取自可驗證紀錄。優先讀 transcript，其次讀 hook stdin JSON 與 Codex 本機
-#     session 記錄。只有這些來源都失敗時，才接受 JSC_MODEL 這個人工覆寫。
+#   - 目前模型 id 取自可驗證紀錄，而且只讀屬於當前 CLI 的那一份（判定鏈見 lib.sh 的
+#     current_model_report）。claude 讀 transcript 與 hook stdin，codex 讀 hook stdin 與
+#     自己的 session 記錄，其餘 CLI 本機沒有可讀的紀錄。只有這些來源都失敗時，才接受
+#     JSC_MODEL 這個人工覆寫。
 #   - 不採用對話內容裡模型自稱的 id。自我回報無法驗證，等同沒有閘門。
 #   - 鎖存的是「階段的必要標籤」，不是「上鎖那一刻的模型」。鎖當時的模型只留作記錄，
 #     否則用不合格的模型起跑就會把自己鎖成合格，閘門永遠通過。
 #
-# 狀態檔：$JSC_HOME/sessions/{sid}.stage，單行「{stage}<TAB>{必要標籤}<TAB>{上鎖時的模型}<TAB>{模型來源}」。
+# 政策是 fail-closed：不知道能力就擋下，知道才比對能力標籤。不知道能力有三種，一律擋下——
+# 判不出是哪一支 CLI、判不出目前模型、模型判得出來但不在能力標籤表上。放行任何一種，用不
+# 合格的模型跑階段就查不出來，閘門形同虛設。代價是被擋住的人可能不知道怎麼脫困，所以每一則
+# 擋下的訊息都要帶逃生門：設 JSC_MODEL 人工指明模型，或執行本檔的 unlock 解除該階段的鎖。
+#
+# 狀態檔：$JSC_HOME/sessions/{cli}-{sid}.stage，單行
+# 「{stage}<TAB>{必要標籤}<TAB>{上鎖時的模型}<TAB>{模型來源}」。
+# 檔名帶 CLI 代號的理由見 lib.sh 的 stage_state_file：session id 判不出時會退回 default，
+# 不分 CLI 就會共用同一支 default.stage，一支上的鎖擋到另一支。舊路徑
+# $JSC_HOME/sessions/{sid}.stage 仍讀得到（往後相容），unlock 也會一併清掉，
+# 但新的寫入一律走新路徑。
 #
 # 用法：
 #   sdlc-gate.sh lock {stage}  階段閘門：比對實際模型與該階段必要標籤，通過才上鎖。
 #                              exit 0 = 通過並已上鎖；exit 1 = 未通過，呼叫端必須停止流程。
-#   sdlc-gate.sh unlock        移除狀態檔（被擋住又確定要放行時的逃生門）。
+#   sdlc-gate.sh unlock [{狀態檔}]
+#                              移除狀態檔（被擋住又確定要放行時的逃生門）。不帶參數時清掉這個
+#                              工作階段的新舊兩份；帶參數時清掉指定的那一份。
+#                              為什麼要收參數：hook 拿得到 stdin 的 session id 與 JSC_CLI，
+#                              手動執行拿不到，兩邊算出來的檔名可能不同，逃生門就按不到真正
+#                              擋人的那一支。所以擋人訊息會把實際讀到的路徑一起印出來，
+#                              照抄就解得開。參數只收 sessions 目錄底下的 .stage 檔，
+#                              避免這個逃生門變成任意刪檔的工具。
 #   sdlc-gate.sh check         hook 模式（UserPromptSubmit）：模型不符即擋下該輪提示。
 #   sdlc-gate.sh report        印出 {sid} {stage} {必要標籤} {模型 id} {模型來源} {判定}；無鎖不印。
 #
@@ -39,9 +58,10 @@
 # 結束碼（一個子命令一列）：
 #   lock              0=通過並已上鎖 1=未通過，呼叫端必須停止流程（階段名不合法、讀不到該
 #                     階段的必要標籤、判定不出目前模型、模型不在標籤表上、缺標籤、寫不進狀態檔）
-#   unlock            0=永遠成功，狀態檔不存在也算
-#   check             0=放行 2=擋下該輪提示。安靜放行：沒有階段鎖、舊格式狀態檔讀不出必要標籤、
-#                     必要標籤是 any、判定不出目前模型（只提醒不擋）
+#   unlock            0=永遠成功，狀態檔不存在也算；不帶參數時新舊兩種路徑都會清掉
+#                     2=參數不是 sessions 目錄底下的 .stage 檔
+#   check             0=放行 2=擋下該輪提示。安靜放行只剩三種：沒有階段鎖、舊格式狀態檔讀不出
+#                     必要標籤、必要標籤是 any。判定不出目前模型改為擋下，見上面的 fail-closed
 #   report            0=永遠成功，無鎖就不印
 #   wp-lock           0=已記下 2=存取庫不是 {owner}/{repo}、PR 編號不是數字、寫不進狀態檔
 #   wp-unlock         0=已結清，狀態檔不存在也算 2=存取庫或 PR 編號格式錯誤
@@ -103,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）轉呼叫這些子命令時就這樣整支
@@ -112,7 +133,9 @@ case "${1:-}" in
   *) read_stdin ;;
 esac
 sid=$(session_id)
-state="$JSC_HOME/sessions/$sid.stage"
+# 讀寫兩條路徑分開：寫入一律走帶 CLI 代號的新路徑，讀取則允許退回舊路徑（往後相容）。
+state=$(stage_state_read_file)
+state_new=$(stage_state_file)
 TAGS_TSV="$JSC_HOME/model-tags.tsv"
 STAGES="plan analyze implement maintain"
 
@@ -182,8 +205,33 @@ model_verdict() { # $1=stage $2=req $3=model
   [ -z "$miss" ] && printf 'pass' || printf 'fail:%s' "$miss"
 }
 
-model_fail_message() { # $1=stage $2=checked
-  echo "[jsc][SDLC 閘門][ERR]：判定不出目前實際使用的模型，無法驗證是否符合階段「$1」。已檢查來源：${2:-無}。請確認 hook stdin 帶有 transcript_path 或 model 欄位、Codex session 記錄可讀，或明確設定 JSC_MODEL 作為人工覆寫後重跑。本次不進行任何工作。" >&2
+# 逃生門說明。被擋住的人多半不熟這套東西，訊息要讓他照著做就脫困，所以兩條路都寫成
+# 可以照抄的指令，而且把「可以填什麼」一併列出來。
+gate_escape_hint() { # $1=必要標籤 $2=擋人的那一支狀態檔（可省略）
+  _ok=$(eligible_models "$1")
+  echo "逃生門二選一："
+  echo "  1. 人工指明模型：設環境變數 JSC_MODEL={模型 id} 之後重來一次。標籤表上合格的模型 id：${_ok:-（表上沒有合格模型，請先補表）}。"
+  # 路徑照抄進指令裡：手動執行時算出來的檔名跟 hook 算出來的可能不同，不點名就解不到那一支。
+  if [ -n "${2:-}" ]; then
+    echo "  2. 解除這個階段的鎖：執行 sh $0 unlock $2。解除之後這道閘門就不再擋。"
+  else
+    echo "  2. 解除這個階段的鎖：執行 sh $0 unlock。解除之後這道閘門就不再擋。"
+  fi
+}
+
+# 判不出 CLI 時追加一句。這是「不知道能力」的第一種，成因與修法都跟另外兩種不同：
+# 不知道是哪一支 CLI，就不知道該讀誰的模型紀錄，接線設定要把代號帶上。
+gate_cli_hint() {
+  [ "$(cli_name)" = unknown ] || return 0
+  echo "另外：目前判不出是哪一支 CLI（環境變數 JSC_CLI 沒有設），所以連該讀哪一份模型紀錄都不知道。接線設定應以 JSC_CLI={CLI 代號} 帶上。"
+}
+
+model_fail_message() { # $1=stage $2=checked $3=必要標籤
+  {
+    echo "[jsc][SDLC 閘門][ERR]：判定不出目前實際使用的模型，無法驗證是否符合階段「$1」（需要 ${3:-未知}）。已檢查來源：${2:-無}。本次不進行任何工作。"
+    gate_cli_hint
+    gate_escape_hint "${3:-any}"
+  } >&2
 }
 
 # --- 工作包 PR 閘門（狀態檔：$JSC_HOME/wp/{owner}-{repo}-{index}.pr，一個工作包一支） ---
@@ -291,14 +339,17 @@ case "${1:-check}" in
     src=$(printf '%s' "$info" | cut -f2)
     checked=$(printf '%s' "$info" | cut -f3-)
     if [ -z "$cur" ]; then
-      model_fail_message "$stage" "$checked"
+      model_fail_message "$stage" "$checked" "$req"
       exit 1
     fi
 
     if [ "$req" != "any" ]; then
       have=$(model_tags "$cur")
       if [ -z "$have" ]; then
-        echo "[jsc][SDLC 閘門][ERR]：模型「$cur」不在能力標籤表上，無法判定是否夠格跑階段「$stage」（需要 $req）。請把該模型補進 jsc-cli/references/model-tags.md 後執行 model-tags.sh sync，本次不進行任何工作。" >&2
+        {
+          echo "[jsc][SDLC 閘門][ERR]：模型「$cur」（來源 ${src:-未知}）不在能力標籤表上，無法判定是否夠格跑階段「$stage」（需要 $req）。請把該模型補進 jsc-cli/references/model-tags.md 後執行 model-tags.sh sync，本次不進行任何工作。"
+          gate_escape_hint "$req"
+        } >&2
         exit 1
       fi
       miss=$(missing_tags "$req" "$have")
@@ -309,13 +360,29 @@ case "${1:-check}" in
       fi
     fi
 
-    printf '%s\t%s\t%s\t%s\n' "$stage" "$req" "$cur" "$src" > "$state" 2>/dev/null || {
-      echo "[jsc][SDLC 閘門][ERR]：寫不進狀態檔 $state，階段鎖未生效。" >&2; exit 1; }
+    printf '%s\t%s\t%s\t%s\n' "$stage" "$req" "$cur" "$src" > "$state_new" 2>/dev/null || {
+      echo "[jsc][SDLC 閘門][ERR]：寫不進狀態檔 $state_new，階段鎖未生效。" >&2; exit 1; }
     echo "[jsc][SDLC 閘門][OK]：階段「$stage」通過（需要 $req，目前模型 $cur，來源 $src），已上鎖。"
     exit 0 ;;
 
   unlock)
-    rm -f "$state" 2>/dev/null || true
+    target="${2:-}"
+    if [ -n "$target" ]; then
+      # 只認「上一層目錄叫 sessions、副檔名是 .stage」的路徑：逃生門不該順便變成任意刪檔的
+      # 工具。判準刻意不寫成「必須在這支行程算出來的 $JSC_HOME 底下」——擋人的是 hook，
+      # 解鎖的是人在殼層手動執行，兩邊的 JSC_HOME 未必相同，綁上去就會把照抄訊息的人擋掉，
+      # 那正是這個逃生門要避免的事。
+      case "$target" in
+        */sessions/*.stage) ;;
+        *)
+          echo "[jsc][SDLC 閘門][ERR]：unlock 的參數只收 sessions 目錄底下的 .stage 檔，收到「$target」。不帶參數則清掉這個工作階段自己那一份。" >&2
+          exit 2 ;;
+      esac
+      rm -f "$target" 2>/dev/null || true
+      exit 0
+    fi
+    # 新舊兩種路徑都要清。只清新的話，舊格式的鎖永遠解不開，被它擋住的人就沒有逃生門。
+    rm -f "$state_new" "$(stage_state_legacy_file)" 2>/dev/null || true
     exit 0 ;;
 
   check)
@@ -330,15 +397,24 @@ case "${1:-check}" in
     cur=$(printf '%s' "$info" | cut -f1)
     src=$(printf '%s' "$info" | cut -f2)
     checked=$(printf '%s' "$info" | cut -f3-)
-    # 判定不出模型時只提醒，不擋——否則使用者會被鎖在無法送出提示的狀態。
+    # 判定不出模型就擋下。這是刻意改成 fail-closed：放行等於「換一支讀不到紀錄的 CLI
+    # 就能繞過閘門」，閘門形同虛設。原本只提醒不擋，怕的是把人鎖在送不出提示的狀態——
+    # 那個風險是真的，所以訊息一定要把兩條逃生門寫清楚，照著做就能脫困。
     if [ -z "$cur" ]; then
-      echo "[jsc] SDLC 階段「${stage}」需要標籤「${req}」，但判定不出目前模型。已檢查來源：${checked:-無}。請確認 transcript、Codex session 記錄，或設定 JSC_MODEL 人工覆寫。"
-      exit 0
+      {
+        echo "[jsc][SDLC 閘門][ERR]：SDLC 階段「${stage}」需要能力標籤「${req}」，但判定不出目前用的是哪個模型，也就無法確認夠不夠格。已檢查來源：${checked:-無}。本輪提示已擋下。"
+        gate_cli_hint
+        gate_escape_hint "$req" "$state"
+      } >&2
+      exit 2
     fi
 
     have=$(model_tags "$cur")
     if [ -z "$have" ]; then
-      echo "[jsc][SDLC 閘門][ERR]：模型「${cur}」（來源 ${src:-未知}）不在能力標籤表上，無法確認是否夠格跑階段「${stage}」（需要 ${req}）。請補進 jsc-cli/references/model-tags.md 並執行 model-tags.sh sync；確定要放行請執行 jsc-hooks/hooks/sdlc-gate.sh unlock。本輪提示已擋下。" >&2
+      {
+        echo "[jsc][SDLC 閘門][ERR]：模型「${cur}」（來源 ${src:-未知}）不在能力標籤表上，無法確認是否夠格跑階段「${stage}」（需要 ${req}）。請補進 jsc-cli/references/model-tags.md 並執行 model-tags.sh sync。本輪提示已擋下。"
+        gate_escape_hint "$req" "$state"
+      } >&2
       exit 2
     fi
 
@@ -346,7 +422,10 @@ case "${1:-check}" in
     [ -z "$miss" ] && exit 0
 
     ok=$(eligible_models "$req")
-    echo "[jsc][SDLC 閘門][ERR]：SDLC 階段「${stage}」需要標籤「${req}」，目前模型「${cur}」（來源 ${src:-未知}）缺少「${miss}」。請切換到下列任一模型後重送：${ok:-（表上無合格模型，請補表）}。要結束本階段的鎖請執行 jsc-hooks/hooks/sdlc-gate.sh unlock。本輪提示已擋下。" >&2
+    {
+      echo "[jsc][SDLC 閘門][ERR]：SDLC 階段「${stage}」需要標籤「${req}」，目前模型「${cur}」（來源 ${src:-未知}）缺少「${miss}」。請切換到下列任一模型後重送：${ok:-（表上無合格模型，請補表）}。本輪提示已擋下。"
+      echo "要結束本階段的鎖請執行：sh $0 unlock $state"
+    } >&2
     exit 2 ;;
 
   report)

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)
 

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

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 $?
 }

hooks/write-guard.sh

@@ -24,10 +24,12 @@
 #
 # --- stage 模式 ---
 #
-# 階段鎖狀態檔沿用 sdlc-gate.sh 那一份（$JSC_HOME/sessions/{sid}.stage，單行
+# 階段鎖狀態檔沿用 sdlc-gate.sh 那一份（$JSC_HOME/sessions/{cli}-{sid}.stage，單行
 # 「{階段}<TAB>{必要標籤}<TAB>{上鎖時的模型}」），這裡只讀不寫：判準與格式留在 sdlc-gate.sh，
-# 兩邊各存一份就會漂移。plan 與 analyze 是純邏輯階段，產出是 wiki 頁不是程式碼，所以那兩個
-# 階段鎖著時 Write、Edit、MultiEdit 一律擋下；implement 與 maintain 本來就要寫檔，放行。
+# 兩邊各存一份就會漂移。路徑一律取自 lib.sh 的 stage_state_read_file，連「新路徑優先、舊路徑
+# 往後相容」這條規則也不在這裡抄第二份。plan 與 analyze 是純邏輯階段，產出是 wiki 頁不是
+# 程式碼，所以那兩個階段鎖著時 Write、Edit、MultiEdit 一律擋下；implement 與 maintain
+# 本來就要寫檔，放行。
 #
 # --- review 模式 ---
 #
@@ -73,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}"
 
@@ -124,16 +127,18 @@ write_tool_or_exit() {
 # ── stage：plan 與 analyze 階段鎖存在時擋下寫檔
 if [ "$mode" = stage ]; then
   write_tool_or_exit
-  state="$JSC_HOME/sessions/$(session_id).stage"
+  state=$(stage_state_read_file)
   [ -f "$state" ] && [ -r "$state" ] || exit 0
   stage=$(cut -f1 "$state" 2>/dev/null | head -n1)
   case "$stage" in
     plan|analyze) ;;
     *) exit 0 ;;   # implement 與 maintain 本來就要寫檔；讀不出階段也放行
   esac
+  # 解除指令帶上實際讀到的狀態檔路徑：擋人的是 hook，解鎖的是人在殼層手動執行，兩邊算出來
+  # 的檔名未必相同，不點名就會解到別的地方去。
   deny "目前鎖在 SDLC「$stage」階段，這個階段只產出計畫或分析頁，不寫檔案。本次寫入已擋下。" \
 "改法：把結論寫進該階段的 wiki 頁；真的要動程式碼請先進入 implement 階段。
-解除階段鎖：jsc-hooks/hooks/sdlc-gate.sh unlock"
+解除階段鎖：sh $HERE/sdlc-gate.sh unlock $state"
 fi
 
 # ── review：稽核類技能執行中擋下寫檔

plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-hooks",
-  "version": "0.3.4",
+  "version": "0.4.2",
   "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟、寫入與提交閘門",
   "skills": "./skills/",
   "jsc": {

references/behaviors.md

@@ -7,17 +7,17 @@
 | 項目 | 內容 |
 | --- | --- |
 | 觸發時機 | 裝好或更新完 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}` 並在 `ERROR_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/report-status.sh skill-end jsc-hooks:hooks-install {status} {結束碼} {detail}` 記下整輪怎麼結束。腳本在同一個存取庫，用 `tools/` 相對路徑；這一筆只由主代理寫一次，寫在並行的各 CLI sub agent 裡會變成五筆互相矛盾的結局。腳本不在就安靜跳過，回報失敗不得變成接線失敗 |
+| 外部呼叫 | `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 連結，而且目錄頁那一列的連結驗不過時，回報要講明那一列只有純文字頁名、沒有連結。以上收完之後還要走完最後一步：呼叫 `report-status.sh skill-end`，狀態五選一——每一支偵測到的 CLI 五道關卡全過而且一律回 `wired` 是 `ok`，實務上等於那台機器沒有 kiro；跑完整輪但有一部分沒到 `wired` 是 `degraded`，涵蓋 kiro 只能降級接線，以及某支 CLI 接線失敗、已經轉交 `jsc-hooks:repair` 而且拿到一條對 `develop` 的 PR，還有被跳過的 CLI；關卡失敗而沒人接手是 `failed`，也就是修正技能起不來或回不出 PR，壞掉的 hook 還掛在那裡；`JSC_READONLY=1` 讓 `wire-cli.sh` 回 exit 6、一支 CLI 都沒動是 `blocked`；偵測不到任何 CLI 而主動停止是 `aborted`。腳本不在磁碟上就跳過，這一步照樣算走完 |
+| 可驗證跡象 | 各 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}`。這支技能自己收尾時，同一個 `$JSC_HOME/usage/events.jsonl` 尾端會多一筆 `{kind:skill,phase:end}`，`name` 是 `jsc-hooks:hooks-install`，整輪只有一筆，`status` 與那次結局相符，`exit` 是決定結局的那道關卡的結束碼；`report-status.sh` 不在那台機器上就沒有這一筆，接線結果一字不變。事件寫不進去不影響任何 hook 的結束碼，也不影響本技能的結局 |
 
 ## repair
 
 | 項目 | 內容 |
 | --- | --- |
 | 觸發時機 | `hooks-install` 或 `report-error.sh` 回報某一支 hook 失敗時用，或是重新接線之後那支 hook 還是一直失敗時用。不用於例行接線，也不用於與 hook 無關的修改 |
-| 關鍵步驟 | 從 `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 |
+| 關鍵步驟 | 從 `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、收尾呼叫 `tools/report-status.sh skill-end jsc-hooks:repair {status} {結束碼} {detail}` 記下這次修正怎麼結束（腳本在同一個存取庫，用 `tools/` 相對路徑，比照 `tools/wire-cli.sh`；檔案不在就安靜跳過，回報失敗不得變成修正失敗） |
 | 外部呼叫 | `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 |
+| 完成條件 | 修正已經落在磁碟上、`wire-cli.sh smoke` 對受影響的 CLI 回 exit 0、`sync-skill-manifest.sh` 回 exit 0 而且三份 manifest 版本一致，最後拿到一條對 `develop` 的 PR 連結；開不出 PR 時要講明修正已套用但尚未合併、帶上分支名與失敗原因。每一條路線都要走完最後一步：呼叫 `report-status.sh skill-end`，狀態五選一——修正落地、smoke 回 exit 0、三份 manifest 版本一致而且拿到 PR 連結是 `ok`；smoke 過了但東西沒送出去是 `degraded`，也就是開不出 PR 只剩分支，或 manifest 沒對齊；修不好是 `failed`，也就是診斷繞回去以後 smoke 還是回 exit 4，或同步版本踩到環境錯誤，壞掉的接線還是壞的；沒有可修的項目是 `aborted`，也就是讀不到任何失敗情境。本技能豁免版本閘門與部署後重啟閘門，沒有別的閘門擋得住它，所以不會用 `blocked`。腳本不在磁碟上就跳過，這一步照樣算走完 |
+| 可驗證跡象 | hooks 存取庫多一個修正提交與一條推上去的分支、`develop` 上多一條 PR、三份 manifest 與 README 技能清單版本一致、`wire-cli.sh smoke` 由失敗轉為 exit 0；不論走哪一條路線，`$JSC_HOME/usage/events.jsonl` 尾端都會多一筆 `{kind:skill,phase:end}` 事件，`name` 是 `jsc-hooks:repair`，`status` 與那次結局相符，`exit` 是決定結局的那支工具的結束碼；`report-status.sh` 不在那台機器上就沒有這一筆，修正結果一字不變 |

skills/hooks-install/SKILL.md

@@ -75,8 +75,12 @@ 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. Exit 0 with an `ERROR_{HASH}` page name and URL on stdout means the page was written; exit 0 with empty output means `JSC_WIKI_REPO_ERROR` and `JSC_WIKI_REPO` are both unset, so carry that reason 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 and URL, 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`.
+5. Record how the whole install ended. Run `tools/report-status.sh skill-end jsc-hooks:hooks-install {status} {exit} "{detail}"` — the script is in this same repo, so it takes the plain `tools/` path that every other stage above uses. **The main agent makes this one call, after every per-CLI report is in.** The per-CLI pipelines run as parallel sub agents and one skill run is one event, so a call inside those sub agents would write one line per CLI and turn the install's outcome into five contradictory ones. The gate that records a skill's start fires when the skill is loaded and can never see how it ended; without this line a finished install and an install abandoned halfway look identical afterwards, which is the whole reason the closing step exists.
+   - `{status}` is one of five. `ok`: every detected CLI passed all five stages and every one of them reported `wired` — in practice that means kiro was not on the machine. `degraded`: the pipeline ran to the end and part of it did not reach `wired`. That covers kiro, which is `degraded` by design because the CLI cannot block a skill call, and it covers a CLI whose stage failed and was handed to `jsc-hooks:repair` with a PR against `develop` — the failure has an owner and a fix in flight, so the install is incomplete, not broken. A `skipped` CLI belongs here too. `failed`: a stage failed and the failure was left with nobody holding it — `jsc-hooks:repair` could not be started, or it came back with no PR — so a broken hook stays wired and nothing is going to fix it. `blocked`: `wire-cli.sh` refused with exit 6 under `JSC_READONLY=1`, so no CLI was purged or wired at all. `aborted`: step 1 detected no CLI, so there was nothing to wire and the run stopped on a precondition rather than on an error.
+   - Take `{exit}` from the stage that decided the ending — the `wire-cli.sh`, `smoke` or `scan-hook-errors.sh` code — and otherwise use 0 for `ok` and 1 for every other status. `{detail}` is optional, one line, at most 200 characters: the CLI count per verdict, or the CLI and stage that failed. Never fold the five per-CLI reports into it; those go to the user in step 4.
+   - Reporting never changes the install. `report-status.sh` swallows its own write failures and always exits 0, and an absent file is skipped in silence — the same rule the nine hooks follow, and for the same reason: a reporter that can fail the thing it reports on is worse than no reporter. Done when the one call was made, or the script was absent and this step was skipped without a word.
 
 ## Notes
 

skills/repair/SKILL.md

@@ -16,3 +16,7 @@ This skill is exempt from the version guard and the post-deploy restart gate, be
 3. Pick the smallest repair that makes the wiring pass, then apply it in the `hooks` repo. When the fix touches wiring behaviour, update `hooks/tools/wire-cli.sh`, `hooks/skills/hooks-install/SKILL.md` and `hooks/README.md` in the same change. Run `tools/wire-cli.sh smoke {cli}` for the affected CLI: exit 0 means the repair holds, exit 4 means it does not — go back to step 2 with the new output, exit 2 means a bad CLI name, so fix the name and rerun. Done when the fix is on disk and smoke exits 0.
 4. Run `jsc-meta/tools/sync-skill-manifest.sh .` from the repo root. Exit 0 means the README skill list and all three manifests carry the same new version. Exit 1 means a missing path, a missing `JSC-SKILLS` marker or an unreadable manifest — fix the named file and rerun. Exit 2 means a usage error, so pass exactly one path. Any other exit code is an environment fault, never a successful sync: stop and report it. Done when the script exits 0 and the three manifests show the same version.
 5. Commit, push and open a PR with `jsc-git:pr` against `develop`. When `jsc-git:pr` returns no PR URL, report the repair as applied but unmerged, name the branch that holds it, and hand back the failure reason — never claim a PR exists. Done when a PR URL comes back, or the branch name and the failure reason are both reported.
+6. Record how the repair ended. Run `tools/report-status.sh skill-end jsc-hooks:repair {status} {exit} "{detail}"` — the script is in this same repo, so it takes the plain `tools/` path, like `tools/wire-cli.sh` in step 3. This step runs on every route out of steps 1 to 5, the ones that stopped early included. What records a skill's start fires when the skill is loaded and cannot see how it ended, so a repair that never writes this line is indistinguishable afterwards from one that was abandoned with a hook still broken.
+   - `{status}` is one of five. `ok`: the fix is on disk, `wire-cli.sh smoke` exits 0 for every affected CLI, `sync-skill-manifest.sh` exits 0 with all three manifests on the same version, and a PR URL against `develop` came back. `degraded`: the repair holds — smoke exits 0 — but the change did not get all the way out, because `jsc-git:pr` returned no PR URL and the fix is sitting on a branch, or `sync-skill-manifest.sh` left the manifests unaligned. `failed`: the hook could not be repaired. Smoke still exits 4 after the diagnosis loop of step 2 came back around, or step 4 hit an environment fault, so the broken wiring is still broken. `aborted`: there was nothing to repair — step 1 found no failure context, no `ERROR_{HASH}` page and no failed `status=` line, so the run stopped on a precondition rather than on a fault. `blocked` does not arise: this skill is exempt from the version guard and the post-deploy restart gate, which are the only two gates that could hold it, and that exemption exists precisely because it is the way back from a broken hook.
+   - Take `{exit}` from whatever decided the ending — the `wire-cli.sh smoke` or `sync-skill-manifest.sh` code — and otherwise use 0 for `ok` and 1 for every other status. `{detail}` is optional, one line, at most 200 characters: the hook and CLI that were repaired, or the branch that holds an unmerged fix. Diagnosis output and diffs never go on this line.
+   - Reporting never changes the repair. `report-status.sh` swallows its own write failures and always exits 0, and an absent file is skipped in silence, so a missing reporter can never be the reason a repaired hook reads as unrepaired. Done when the call was made, or the script was absent and this step was skipped without a word.

templates/error-contents.md

@@ -2,10 +2,16 @@
 
 > 由 `jsc-hooks` 的失敗回報流程維護。新異常附加在文末，查問題時先看最新一筆。
 >
-> 寫入語意：一列代表一次 hook 異常回報。寫入前先讀回整頁，同一筆異常已經有列就更新那一列，沒有才在文末附加一列，最後整頁寫回。禁止整頁覆蓋，也不得改動別人的列。
+> 存放位置：本頁落在 `JSC_WIKI_REPO_CONTENTS` 解出的目錄專用存取庫，與異常頁的存取庫是兩個不同的存取庫。
+>
+> 寫入語意：一列代表一次 hook 異常回報。寫入前先讀回整頁，同一筆異常已經有列就更新那一列，沒有才在文末附加一列，最後整頁寫回。一律 upsert 附加，禁止整頁覆蓋，也不得改動別人的列。
+>
+> 連結寫法：一律寫成 `[{文字}]({絕對網址})`，網址取 `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_{HASH}]] | {owner}/{repo} | {hook_name} | {exit_code} | {error_summary} |
+| {yyyy-MM-dd HH:mm:ss} | [{頁名}]({wiki-url 印出的絕對網址}) | {owner}/{repo} | {hook_name} | {exit_code} | {error_summary} |

tools/report-error.sh

@@ -12,13 +12,27 @@
 #   相關輸出（stdout／stderr 摘要）由標準輸入讀入，可省略。
 #
 # 輸出:
-#   成功印出「{頁名} {網址}」一行。
-#   wiki 位置解析不出來（JSC_WIKI_REPO_ERROR 與 JSC_WIKI_REPO 都沒設，或找不到
-#   gitea.sh）時安靜降級：不輸出、exit 0。回報失敗不該再變成一次失敗。
+#   成功印出「{頁名} {網址}」一行。網址在異常頁寫成功之後才取，頁名的 hash 帶時間戳，
+#   每次都是全新的頁，寫之前查一定是 404。取不到網址時只印頁名，原因走 stderr，仍然 exit 0。
+#   下列四種情形安靜降級：不寫任何頁、不輸出任何內容、exit 0。回報失敗不該再變成一次失敗。
+#     1. 找不到 gitea.sh
+#     2. 解析不出異常頁的 wiki 存取庫（JSC_WIKI_REPO_ERROR 與 JSC_WIKI_REPO 都沒設）
+#     3. 算不出 HASH（hash-id 失敗或回空字串）
+#     4. 建不出暫存檔（mktemp 失敗）
+#   異常頁與目錄頁分屬兩個存取庫，各解各的：解不出異常頁的存取庫就整支降級；解得出
+#   異常頁、只解不出目錄頁的存取庫，就只寫異常頁、跳過目錄頁更新，印出頁名，仍然 exit 0。
+#   一份寫得成的異常紀錄，不該因為目錄頁沒地方放就整份丟掉。
 #   寫入 wiki 失敗才以 exit 4 回報，訊息走 stderr。
 #
-# 結束碼: 0=已寫入 wiki 並印出「{頁名} {網址}」，或安靜降級（找不到 gitea.sh、解析不出
-#           wiki 存取庫、算不出 HASH、建不出暫存檔）——回報失敗不該再變成一次失敗
+# 連結:
+#   目錄頁那一列指向異常頁，一律寫成 [{文字}]({連結})，網址取 jsc-gitea 的
+#   gitea.sh wiki-url，不自己組路徑。
+#   寫入前先把那個網址交給 jsc-gitea 的 link-check.sh，結束碼 0 才把連結寫進那一列。
+#   驗不過就只留純文字頁名：那一列照寫、異常頁照寫、結束碼照舊。這一段一律不改結束碼，
+#   本腳本是失敗回報路徑，回報失敗不該再變成一次失敗。
+#
+# 結束碼: 0=已寫入異常頁並印出頁名（取得網址就一併印出），或以上列四種安靜降級原因之一
+#           結束、沒有寫出任何頁也沒有任何輸出——回報失敗不該再變成一次失敗
 #         2=用法錯誤（缺 --hook 或 --summary）
 #         4=寫入 wiki 失敗（異常頁與索引目錄頁，任一支寫不進去就算），或目錄頁的舊內容
 #           讀不回來（wiki-get 回 7 金鑰失效、8 其他 API 失敗）而放棄寫入；訊息走 stderr。
@@ -27,8 +41,10 @@
 #   就地結束並回 2，跟用法錯誤同碼；分不出是哪一種時，先確認 hooks/lib.sh 在不在。
 #
 # 頁名:
-#   ERROR_{HASH}，HASH 取「{owner}/{repo} {hook} {時間}」的 SHA-1 前 8 碼（共用 hash 規則）。
+#   ERROR_{HASH}，HASH 取「{owner}/{repo} {hook} {時間}」的 SHA-1 完整 40 碼大寫十六進位
+#   （共用 hash 規則）。三段以空白相連當 hash 輸入。
 #   時間放進 hash：同一種失敗再發生時要另開新頁，不覆寫舊紀錄。
+#   索引目錄頁的頁名固定，不帶 HASH。
 #
 # 誰來呼叫:
 #   由操作者手動執行，或由技能步驟執行（`jsc-hooks:hooks-install` 在 wire-cli.sh 回報
@@ -63,12 +79,19 @@ if [ -z "$hook" ] || [ -z "$summary" ]; then
 fi
 
 gsh=$(jsc_gitea_sh) || exit 0
+# 異常頁與索引目錄頁落在兩個不同的存取庫，各解各的：異常頁走自己的型別，目錄頁走目錄專用
+# 型別。異常頁的存取庫解不出來就整支降級，連異常都沒地方寫，做下去也沒意義。
 wrepo=$(sh "$gsh" wiki-repo ERROR 2>/dev/null) || exit 0
 [ -n "$wrepo" ] || exit 0
+# 目錄頁的存取庫解不出來不算失敗：異常頁照寫，只跳過目錄頁更新，仍然 exit 0。
+# 一份寫得成的異常紀錄，不該因為索引沒地方放就整份丟掉。
+crepo=$(sh "$gsh" wiki-repo CONTENTS 2>/dev/null || true)
 
 # 存取庫名稱未指定就取工作目錄的 origin（只用來標記異常屬於哪個存取庫）
 if [ -z "$repo" ]; then
   origin=$(git config --get remote.origin.url 2>/dev/null || true)
+  # 尾綴的 .git 在這裡剝掉：hash 工具刻意不做輸入正規化，同一份輸入要算出同一個 HASH，
+  # 正規化就是呼叫端的責任。帶不帶 .git 會算出兩個不同的頁，同一個存取庫就分裂成兩份紀錄。
   repo=$(printf '%s' "$origin" \
     | sed -n 's#.*[/:]\([^/]*\)/\([^/]*\)$#\1/\2#p' | sed 's/\.git$//')
 fi
@@ -116,19 +139,77 @@ fill '{HASH}' "$hash" < "$ROOT/templates/error-page.md" \
   | fill '{stdout / stderr 摘要}' "$detail" \
   | fill '{yyyyMMdd}_{HHmmss}' "$ticket_ts" > "$tmp_page"
 
-row=$(printf '| %s | [[%s|%s]] | %s | %s | %s | %s |' \
-  "$ts" "$hook 異常 $ts" "$page" "$repo" "$hook" "$code" "$summary")
+# 異常頁先寫，網址後取。頁名的 hash 帶時間戳，每次回報都是一個全新的頁，寫進去之前查網址
+# 一定是 404，拿到的必然是空字串；目錄頁那一列會變成沒有連結的死字，stdout 也少一半。
+if ! sh "$gsh" wiki-put "$wrepo" "$page" "$tmp_page" >/dev/null 2>&1; then
+  echo "[jsc] 寫入 $page 失敗（$wrepo）。" >&2
+  exit 4
+fi
+
+# 目錄頁那一列指向異常頁，連結一律寫成 [{文字}]({連結})，網址取 gitea.sh wiki-url。
+# wiki 自己那種雙中括號寫法只在同一個 wiki 裡解得開，寫錯不會報錯，畫面上看起來像正常
+# 文字或死連結，巡不到也修不了。
+# 網址取不到不算失敗：異常頁已經寫成功了，只是這一列少一條連結。這裡把原因記下來走 stderr，
+# 結束碼照舊——安靜降級仍是 exit 0，回報失敗不該再變成一次失敗。
+url=$(sh "$gsh" wiki-url "$wrepo" "$page" 2>/dev/null)
+url_code=$?
+url_note=''
+if [ "$url_code" -ne 0 ]; then
+  url=''
+  case "$url_code" in
+    4) url_note='頁面查不到（wiki-url 回 4），寫入後尚未生效' ;;
+    5) url_note='回應裡沒有 html_url（wiki-url 回 5）' ;;
+    7) url_note='金鑰失效或權限不足（wiki-url 回 7）' ;;
+    *) url_note="wiki-url 結束碼 $url_code" ;;
+  esac
+  echo "[jsc] 取不到 $page 的網址：$url_note。目錄頁那一列與輸出只留頁名。" >&2
+fi
+
+emit() { # 異常頁已經寫成功，頁名一定要印；網址取不到就只印頁名，不印一個空欄位
+  if [ -n "$url" ]; then printf '%s %s\n' "$page" "$url"; else printf '%s\n' "$page"; fi
+}
+
+# 連結先驗證連得到，才寫進目錄頁那一列。沒驗過的連結寫進去，異常頁一樣會在目錄頁長出
+# 死連結，而目錄頁是別人查問題的入口。驗不過就只留純文字頁名，那一列照寫。
+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 '{HASH}' "$hash" \
-    | 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
+  echo "[jsc] 目錄頁的 wiki 存取庫解不出來，只寫異常頁，跳過目錄；$page 已建立（$wrepo）。" >&2
+  emit
+  exit 0
+fi
+
 # 異常目錄頁一律附加，不整頁覆蓋。頁上每一列都是別人回報的異常，本腳本沒有從別處讀過
 # 那些列，所以先把舊頁讀回來、把新列附在文末（最新一筆在最後），再整頁寫回。
 # 這個語意完全靠「讀得回舊內容」撐著，因此依 wiki-get 的結束碼分流：
@@ -138,27 +219,19 @@ build_contents() { # 用範本建一份全新的目錄頁；只有確定舊頁
 #   8 → 其他 API 失敗，舊內容一樣未知，處置同 7
 # 為什麼 7 與 8 不能當成「頁面不存在」：拿範本蓋掉一份讀不回來的目錄頁，等於刪光所有既有
 # 列，而 wiki-put 不做合併、也不留備份，蓋掉就救不回來。
-sh "$gsh" wiki-get "$wrepo" ERROR_CONTENTS > "$tmp_list" 2>/dev/null
+sh "$gsh" wiki-get "$crepo" ERROR_CONTENTS > "$tmp_list" 2>/dev/null
 get_code=$?
-contents_skip=''
 case "$get_code" in
   0) if [ -s "$tmp_list" ]; then printf '%s\n' "$row" >> "$tmp_list"; else build_contents; fi ;;
   4) build_contents ;;
-  *) contents_skip=$get_code ;;
+  *)
+    echo "[jsc] 讀取目錄頁失敗（$crepo，wiki-get 結束碼 $get_code），舊內容未知，不寫目錄頁；$page 已建立。" >&2
+    exit 4 ;;
 esac
 
-if ! sh "$gsh" wiki-put "$wrepo" "$page" "$tmp_page" >/dev/null 2>&1; then
-  echo "[jsc] 寫入 $page 失敗（$wrepo）。" >&2
-  exit 4
-fi
-if [ -n "$contents_skip" ]; then
-  echo "[jsc] 讀取 ERROR_CONTENTS 失敗（$wrepo，wiki-get 結束碼 $contents_skip），舊內容未知，不寫目錄頁；$page 已建立。" >&2
-  exit 4
-fi
-if ! sh "$gsh" wiki-put "$wrepo" ERROR_CONTENTS "$tmp_list" >/dev/null 2>&1; then
-  echo "[jsc] 寫入 ERROR_CONTENTS 失敗（$wrepo），$page 已建立。" >&2
+if ! sh "$gsh" wiki-put "$crepo" ERROR_CONTENTS "$tmp_list" >/dev/null 2>&1; then
+  echo "[jsc] 寫入目錄頁失敗（$crepo），$page 已建立。" >&2
   exit 4
 fi
 
-url=$(sh "$gsh" wiki-url "$wrepo" "$page" 2>/dev/null || true)
-printf '%s %s\n' "$page" "$url"
+emit

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

tools/wire-cli.sh

@@ -1354,7 +1354,8 @@ if [ "$action" = smoke ]; then
   # 那一類會讓總數永遠對不上，斷言也就形同虛設。
   #   hook 模式    九支 hook 的每個接線模式各一條。sdlc-gate.sh、comment-scope.sh、
   #                lang-guard.sh 與 write-guard.sh 各有多個模式，所以比 hook 支數多
-  #   模型來源     sdlc-gate.sh lock 取模型代號的四條來源判定路徑
+  #   模型與階段鎖 sdlc-gate.sh 取模型代號的四條來源判定路徑，加上「不知道能力就擋下」的
+  #                三種情形、check 的 fail-closed，以及階段鎖狀態檔的 CLI 區隔與舊格式相容
   #   工作包       sdlc-gate.sh wp-check skill 的歸屬判定路徑
   #   重啟閘門     restart-gate.sh 的判定、清除路徑與狀態檔範圍檢查
   #   寫入閘門     write-guard.sh 三種擋人模式與 release 解除模式的判定路徑
@@ -1364,7 +1365,7 @@ if [ "$action" = smoke ]; then
   #   跨 CLI 貫通  restart-gate.sh 吃五支 CLI 的真實負載，驗判定與輸出形態串得起來
   #   接線形狀     每支 CLI 要寫出去的內容真的產出來一次，驗結構本身（正反案例各一組）
   SMOKE_EXPECT_HOOK=17
-  SMOKE_EXPECT_MODEL=4
+  SMOKE_EXPECT_MODEL=12
   SMOKE_EXPECT_WP=6
   SMOKE_EXPECT_RS=16
   SMOKE_EXPECT_WG=21
@@ -1424,8 +1425,11 @@ if [ "$action" = smoke ]; then
   smoke_one sdlc-gate.sh "wp-check prompt"
   smoke_one sdlc-gate.sh "wp-check skill"
 
-  smoke_model_case() { # $1=情境 $2=來源模式 $3=預期來源片段
-    _name="$1"; _mode="$2"; _want="$3"
+  # 第四個參數是這個案例要用的 CLI 代號，不跟著這一輪接線的 $cli 走：模型偵測鏈已經依 CLI
+  # 分流，transcript 只有 claude 讀得到、codex session 記錄只有 codex 讀得到。拿 $cli 去跑
+  # 每一個案例，換一支 CLI 冒煙就會有一半的案例本來就不該命中，測的東西跟著變。
+  smoke_model_case() { # $1=情境 $2=來源模式 $3=預期來源片段 $4=案例用的 CLI 代號
+    _name="$1"; _mode="$2"; _want="$3"; _mcli="$4"
     # 先計數再開工：底下建不出暫存目錄那條路徑也會印一條結果行，計數放在後面就會漏掉它。
     smoke_n_model=$((smoke_n_model + 1))
     _home=$(mktemp -d 2>/dev/null) || {
@@ -1446,11 +1450,11 @@ if [ "$action" = smoke ]; then
       override) _json='{"session_id":"smoke-model-override"}'; _env="JSC_MODEL=gpt-5.x" ;;
     esac
     if [ "$_mode" = override ]; then
-      _out=$(printf '%s' "$_json" | JSC_HOME="$_home" CODEX_HOME="$_home/codex" JSC_CLI="$cli" JSC_MODEL="gpt-5.x" sh "$HOOKS/sdlc-gate.sh" lock plan 2>&1); _rc=$?
+      _out=$(printf '%s' "$_json" | JSC_HOME="$_home" CODEX_HOME="$_home/codex" JSC_CLI="$_mcli" JSC_MODEL="gpt-5.x" sh "$HOOKS/sdlc-gate.sh" lock plan 2>&1); _rc=$?
     else
-      _out=$(printf '%s' "$_json" | JSC_HOME="$_home" CODEX_HOME="$_home/codex" JSC_CLI="$cli" sh "$HOOKS/sdlc-gate.sh" lock plan 2>&1); _rc=$?
+      _out=$(printf '%s' "$_json" | JSC_HOME="$_home" CODEX_HOME="$_home/codex" JSC_CLI="$_mcli" sh "$HOOKS/sdlc-gate.sh" lock plan 2>&1); _rc=$?
     fi
-    _rep=$(JSC_HOME="$_home" CODEX_HOME="$_home/codex" JSC_CLI="$cli" \
+    _rep=$(JSC_HOME="$_home" CODEX_HOME="$_home/codex" JSC_CLI="$_mcli" \
       sh "$HOOKS/sdlc-gate.sh" report </dev/null 2>/dev/null)
     if [ "$_rc" -eq 0 ] && printf '%s\n%s' "$_out" "$_rep" | grep -qF "$_want"; then
       printf '[jsc] sdlc-gate.sh model（%s）：exit 0，來源含 %s，與預期相同。\n' "$_name" "$_want" >> "$smoke_out"
@@ -1461,10 +1465,117 @@ if [ "$action" = smoke ]; then
     fi
     rm -rf "$_home"
   }
-  smoke_model_case "transcript 實查" transcript "transcript:"
-  smoke_model_case "Codex session 記錄" codex "codex-session:"
-  smoke_model_case "stdin model 欄位" stdin "hook-stdin"
-  smoke_model_case "JSC_MODEL 人工覆寫" override "人工覆寫:JSC_MODEL"
+  smoke_model_case "transcript 實查" transcript "transcript:" claude
+  smoke_model_case "Codex session 記錄" codex "codex-session:" codex
+  smoke_model_case "stdin model 欄位" stdin "hook-stdin" claude
+  # 人工覆寫對每一支 CLI 都保留，所以這一條照這一輪接線的 CLI 跑。
+  smoke_model_case "JSC_MODEL 人工覆寫" override "人工覆寫:JSC_MODEL" "$cli"
+
+  # 「不知道能力就擋下」的三種情形。判定結果與訊息一起驗：只比結束碼的話，訊息漏掉逃生門
+  # 一樣是綠燈，而被擋住的人就真的出不來了——那才是這道 fail-closed 真正的風險。
+  smoke_model_deny_case() { # $1=情境 $2=案例用的 CLI 代號 $3=JSC_MODEL 值 $4=預期訊息片段
+    smoke_n_model=$((smoke_n_model + 1))
+    _home=$(mktemp -d 2>/dev/null) || {
+      smoke_fails=$((smoke_fails + 1))
+      printf '[jsc] sdlc-gate.sh model（%s）：建不出暫存目錄，擋人判定沒驗到。\n' "$1" >> "$smoke_out"
+      return
+    }
+    mkdir -p "$_home/sessions" "$_home/codex/sessions/2026/08/28" 2>/dev/null
+    printf 'stage\tplan\treasoning-max\nmodel\tgpt-5.x\treasoning-max,reasoning-high,coding\n' > "$_home/model-tags.tsv"
+    # codex 的 session 記錄照樣擺著：claude 情境要驗的正是「明明有這一份，也不去讀」。
+    printf '{"type":"turn_context","payload":{"model":"gpt-5.x"}}\n' \
+      > "$_home/codex/sessions/2026/08/28/rollout-2026-08-28T00-00-00-smoke-deny.jsonl"
+    # claude 的三個環境特徵一併清空：JSC_CLI 是空字串時 cli_name() 會退去看它們，只要有一個
+    # 留著繼承來的值，「判不出 CLI」那一條就會被測成 claude。三個要一起清，漏一個等於沒清。
+    _out=$(printf '{"session_id":"smoke-model-deny"}' \
+      | env JSC_HOME="$_home" CODEX_HOME="$_home/codex" JSC_CLI="$2" \
+        CLAUDE_PLUGIN_ROOT="" CLAUDECODE="" CLAUDE_CODE_SESSION_ID="" \
+        JSC_MODEL="$3" sh "$HOOKS/sdlc-gate.sh" lock plan 2>&1); _rc=$?
+    if [ "$_rc" -eq 1 ] && printf '%s' "$_out" | grep -qF "$4" \
+       && printf '%s' "$_out" | grep -qF 'JSC_MODEL={模型 id}'; then
+      printf '[jsc] sdlc-gate.sh model（%s）：exit 1，擋下且訊息帶得出逃生門，與預期相同。\n' "$1" >> "$smoke_out"
+    else
+      smoke_fails=$((smoke_fails + 1))
+      printf '[jsc] sdlc-gate.sh model（%s）：exit %s，預期 exit 1 且訊息含「%s」與逃生門，能力閘門壞了：%s\n' \
+        "$1" "$_rc" "$4" "$(printf '%s' "$_out" | tr '\n' ' ' | cut -c1-200)" >> "$smoke_out"
+    fi
+    rm -rf "$_home"
+  }
+  smoke_model_deny_case "claude 情境不去讀 codex 紀錄" claude "" "判定不出目前實際使用的模型"
+  smoke_model_deny_case "判不出是哪一支 CLI" "" "" "判不出是哪一支 CLI"
+  smoke_model_deny_case "模型不在能力標籤表上" claude "mystery-model-not-listed" "不在能力標籤表上"
+
+  # check 的 fail-closed：階段鎖在、判不出模型，要 exit 2 擋下該輪提示並帶出逃生門。
+  # 這一條原本是「只提醒不擋」，改成擋下之後逃生門就是唯一的出路，所以訊息一起驗。
+  smoke_n_model=$((smoke_n_model + 1))
+  if ck_home=$(mktemp -d 2>/dev/null) && mkdir -p "$ck_home/sessions" 2>/dev/null; then
+    printf 'stage\tplan\treasoning-max\nmodel\tgpt-5.x\treasoning-max,coding\n' > "$ck_home/model-tags.tsv"
+    printf 'plan\treasoning-max\tgpt-5.x\tsmoke\n' > "$ck_home/sessions/claude-smoke-check.stage"
+    ck_out=$(printf '{"session_id":"smoke-check"}' \
+      | env JSC_HOME="$ck_home" JSC_CLI=claude CLAUDE_PLUGIN_ROOT="" JSC_MODEL="" \
+        JSC_SESSION_ID=smoke-check sh "$HOOKS/sdlc-gate.sh" check 2>&1); ck_rc=$?
+    if [ "$ck_rc" -eq 2 ] && printf '%s' "$ck_out" | grep -qF 'JSC_MODEL={模型 id}' \
+       && printf '%s' "$ck_out" | grep -qF 'unlock'; then
+      printf '[jsc] sdlc-gate.sh check（判不出模型時擋下）：exit 2，兩條逃生門都印出來，與預期相同。\n' >> "$smoke_out"
+    else
+      smoke_fails=$((smoke_fails + 1))
+      printf '[jsc] sdlc-gate.sh check（判不出模型時擋下）：exit %s，預期 exit 2 且訊息含 JSC_MODEL 與 unlock 兩條逃生門，輸出：%s\n' \
+        "$ck_rc" "$(printf '%s' "$ck_out" | tr '\n' ' ' | cut -c1-200)" >> "$smoke_out"
+    fi
+    rm -rf "$ck_home"
+  else
+    smoke_fails=$((smoke_fails + 1))
+    printf '[jsc] sdlc-gate.sh check（判不出模型時擋下）：建不出暫存目錄，沒驗到。\n' >> "$smoke_out"
+  fi
+
+  # 階段鎖狀態檔的 CLI 區隔：兩支 CLI 各上一次鎖，兩份狀態檔要分得開，解鎖也只解自己那一份。
+  # session id 判不出時會退回 default，不分 CLI 就會共用同一支檔案，一支上的鎖擋到另一支。
+  smoke_st_case() { # $1=情境 $2=條件成立就通過（已求值的結果字串 ok 或其他）
+    smoke_n_model=$((smoke_n_model + 1))
+    if [ "$2" = ok ]; then
+      printf '[jsc] sdlc-gate.sh 階段鎖（%s）：與預期相同。\n' "$1" >> "$smoke_out"
+    else
+      smoke_fails=$((smoke_fails + 1))
+      printf '[jsc] sdlc-gate.sh 階段鎖（%s）：不如預期，狀態檔的 CLI 區隔壞了。\n' "$1" >> "$smoke_out"
+    fi
+  }
+  if st_home=$(mktemp -d 2>/dev/null) && mkdir -p "$st_home/sessions" 2>/dev/null; then
+    printf 'stage\tplan\treasoning-max\nstage\timplement\tcoding\nmodel\tgpt-5.x\treasoning-max,coding\n' \
+      > "$st_home/model-tags.tsv"
+    # 兩支各上一次鎖，而且刻意上不同的階段：檔名分開之外，內容也要各記各的。
+    # 不寫成迴圈是為了不動到腳本的位置參數——這一段跑在函式外，set -- 會蓋掉整支腳本的 $@。
+    env JSC_HOME="$st_home" JSC_CLI=claude CLAUDE_PLUGIN_ROOT="" JSC_MODEL=gpt-5.x \
+      JSC_SESSION_ID=smoke-stage sh "$HOOKS/sdlc-gate.sh" lock plan </dev/null >/dev/null 2>&1
+    env JSC_HOME="$st_home" JSC_CLI=codex CLAUDE_PLUGIN_ROOT="" JSC_MODEL=gpt-5.x \
+      JSC_SESSION_ID=smoke-stage sh "$HOOKS/sdlc-gate.sh" lock implement </dev/null >/dev/null 2>&1
+    st_a="$st_home/sessions/claude-smoke-stage.stage"
+    st_b="$st_home/sessions/codex-smoke-stage.stage"
+    st_r=bad; { [ -f "$st_a" ] && [ -f "$st_b" ]; } && st_r=ok
+    smoke_st_case "兩支 CLI 各寫出自己那一份" "$st_r"
+    st_r=bad
+    [ "$(cut -f1 "$st_a" 2>/dev/null)" = plan ] \
+      && [ "$(cut -f1 "$st_b" 2>/dev/null)" = implement ] && st_r=ok
+    smoke_st_case "兩份互不覆蓋，各自記自己的階段" "$st_r"
+    env JSC_HOME="$st_home" JSC_CLI=claude CLAUDE_PLUGIN_ROOT="" \
+      JSC_SESSION_ID=smoke-stage sh "$HOOKS/sdlc-gate.sh" unlock </dev/null >/dev/null 2>&1
+    st_r=bad; { [ ! -f "$st_a" ] && [ -f "$st_b" ]; } && st_r=ok
+    smoke_st_case "解鎖只解自己那一份" "$st_r"
+    # 舊格式 sessions/{sid}.stage 的往後相容：新路徑沒有時要讀得到它，unlock 也要清得掉。
+    rm -f "$st_b"
+    printf 'plan\treasoning-max\tgpt-5.x\tsmoke\n' > "$st_home/sessions/smoke-legacy.stage"
+    st_out=$(env JSC_HOME="$st_home" JSC_CLI=claude CLAUDE_PLUGIN_ROOT="" JSC_MODEL=gpt-5.x \
+      JSC_SESSION_ID=smoke-legacy sh "$HOOKS/sdlc-gate.sh" report </dev/null 2>/dev/null)
+    st_r=bad; printf '%s' "$st_out" | grep -qF 'smoke-legacy plan reasoning-max' && st_r=ok
+    smoke_st_case "舊格式狀態檔仍讀得到" "$st_r"
+    rm -rf "$st_home"
+  else
+    smoke_fails=$((smoke_fails + 4))
+    printf '[jsc] sdlc-gate.sh 階段鎖：建不出暫存目錄，狀態檔的 CLI 區隔沒驗到。\n' >> "$smoke_out"
+    printf '[jsc] sdlc-gate.sh 階段鎖：同上，兩份互不覆蓋沒驗到。\n' >> "$smoke_out"
+    printf '[jsc] sdlc-gate.sh 階段鎖：同上，解鎖範圍沒驗到。\n' >> "$smoke_out"
+    printf '[jsc] sdlc-gate.sh 階段鎖：同上，舊格式相容沒驗到。\n' >> "$smoke_out"
+    smoke_n_model=$((smoke_n_model + 4))
+  fi
 
   # 工作包歸屬判定（wp-check 的第二段）：上面兩支清空技能名，只走得到「沒有未結清 PR」與
   # 「取不到技能名」兩條捷徑，歸屬比對整段都沒跑到。這裡自備一份暫時的 $JSC_HOME 狀態檔，
@@ -1506,16 +1617,57 @@ if [ "$action" = smoke ]; then
   # 舊格式的單一狀態檔照樣擋得下來。用暫時目錄是為了不動到使用者真正的
   # $JSC_HOME/restart-required.d/——冒煙測試不該把別人的閘門拆掉。
   # 一律 </dev/null：hook 模式會讀標準輸入，管線沒人關閉時整支卡死。
-  smoke_rs_case() { # $1=情境 $2=技能名 $3=預期結束碼 $4=JSC_RESTART_GATE 值（可省略）
+  #
+  # 「擋下」的形態依 CLI 而定，事實來源是 hooks/deny.sh 的 case：claude、codex、copilot 與認不得
+  # 的代號走 stderr 加結束碼 2；antigravity 改印一行 stdout 的 deny JSON，kiro 只能注入警告，
+  # 這兩支的結束碼都固定 0。所以預期擋下不能寫死 2。
+  # 也不能一律放寬成 0：那兩支上放行也是 0，放寬之後「該擋沒擋」與「正確擋下」完全同形，
+  # 這道斷言等於作廢。解法是結束碼與擋人標記一起比，而且預期放行的案例要反過來確認標記沒出現，
+  # 兩個方向都守得住。既有的 smoke_dn_case 與 smoke_cx_case 已經是這個做法，這裡沿用同一套。
+  smoke_deny_rc() { # 這支 CLI 擋下時的結束碼
+    case "$cli" in antigravity|kiro) printf 0 ;; *) printf 2 ;; esac
+  }
+  smoke_deny_mark() { # 結束碼分不出擋下與放行時，輸出必定出現的擋人標記；空字串代表結束碼已經夠用
+    case "$cli" in
+      antigravity) printf '"decision":"deny"' ;;
+      kiro)        printf 'kiro 擋不下技能叫用' ;;
+      *)           printf '' ;;
+    esac
+  }
+  smoke_deny_ok() { # $1=預期（數字，或字面值 deny）$2=實際結束碼 $3=實際輸出；回 0 代表通過
+    _d_want=$1; _d_rc=$2; _d_out=$3
+    _d_mark=$(smoke_deny_mark)
+    if [ "$_d_want" = deny ]; then
+      [ "$_d_rc" -eq "$(smoke_deny_rc)" ] || return 1
+      [ -n "$_d_mark" ] || return 0
+      printf '%s' "$_d_out" | grep -qF "$_d_mark"
+      return $?
+    fi
+    [ "$_d_rc" -eq "$_d_want" ] || return 1
+    [ -n "$_d_mark" ] || return 0
+    ! printf '%s' "$_d_out" | grep -qF "$_d_mark"
+  }
+  smoke_deny_desc() { # $1=預期；把預期講成失敗訊息看得懂的形態
+    _d_mark=$(smoke_deny_mark)
+    if [ "$1" = deny ]; then
+      if [ -n "$_d_mark" ]; then printf 'exit %s 且輸出含「%s」' "$(smoke_deny_rc)" "$_d_mark"
+      else printf 'exit %s' "$(smoke_deny_rc)"; fi
+    else
+      if [ -n "$_d_mark" ]; then printf 'exit %s 且輸出不含「%s」' "$1" "$_d_mark"
+      else printf 'exit %s' "$1"; fi
+    fi
+  }
+  smoke_rs_case() { # $1=情境 $2=技能名 $3=預期（結束碼，或 deny）$4=JSC_RESTART_GATE 值（可省略）
     _out=$(JSC_HOME="$rs_home" JSC_CLI="$cli" JSC_SKILL="$2" SKILL="$2" \
       JSC_RESTART_GATE="${4:-}" sh "$HOOKS/restart-gate.sh" </dev/null 2>&1); _rc=$?
     smoke_n_rs=$((smoke_n_rs + 1))
-    if [ "$_rc" -eq "$3" ]; then
+    if smoke_deny_ok "$3" "$_rc" "$_out"; then
       printf '[jsc] restart-gate.sh（%s）：exit %s，與預期相同。\n' "$1" "$_rc" >> "$smoke_out"
     else
       smoke_fails=$((smoke_fails + 1))
       printf '[jsc] restart-gate.sh（%s）：exit %s，預期 %s，重啟閘門判定壞了：%s\n' \
-        "$1" "$_rc" "$3" "$(printf '%s' "$_out" | tr '\n' ' ' | cut -c1-200)" >> "$smoke_out"
+        "$1" "$_rc" "$(smoke_deny_desc "$3")" \
+        "$(printf '%s' "$_out" | tr '\n' ' ' | cut -c1-200)" >> "$smoke_out"
     fi
   }
   # 狀態檔在不在也要比：一支 CLI 一份的重點就在「該留的留、該刪的刪」，只看結束碼看不出來。
@@ -1540,7 +1692,7 @@ if [ "$action" = smoke ]; then
     JSC_HOME="$rs_home" JSC_CLI="$cli" \
       sh "$HOOKS/restart-gate.sh" require update hooks cli </dev/null 2>/dev/null
     smoke_rs_file "require 寫出當前 CLI 那一份" "$rs_dir/$cli" exist
-    smoke_rs_case "當前 CLI 那份存在，技能 jsc-sdlc:implement" jsc-sdlc:implement 2
+    smoke_rs_case "當前 CLI 那份存在，技能 jsc-sdlc:implement" jsc-sdlc:implement deny
     smoke_rs_case "當前 CLI 那份存在，豁免技能 jsc-cli:deploy" jsc-cli:deploy 0
     smoke_rs_case "當前 CLI 那份存在，豁免技能 jsc-gitea:wiki" jsc-gitea:wiki 0
     smoke_rs_case "當前 CLI 那份存在，豁免技能 jsc-log:worklog" jsc-log:worklog 0
@@ -1557,7 +1709,7 @@ if [ "$action" = smoke ]; then
     # 舊格式的單一狀態檔（過渡相容）：沒有 per-CLI 資訊，所以一律擋，clear 一併刪掉。
     printf 'at=%s\nmode=update\ndomains=hooks\ncli=%s\n' "$(now_iso)" "$rs_other" \
       > "$rs_home/restart-required" 2>/dev/null
-    smoke_rs_case "舊格式單一狀態檔存在" jsc-sdlc:implement 2
+    smoke_rs_case "舊格式單一狀態檔存在" jsc-sdlc:implement deny
     JSC_HOME="$rs_home" JSC_CLI="$cli" JSC_SESSION_ID=smoke-restart-legacy \
       sh "$HOOKS/session-timer.sh" restart </dev/null 2>/dev/null
     smoke_rs_file "清除一併刪掉舊格式狀態檔" "$rs_home/restart-required" absent
@@ -1609,6 +1761,8 @@ if [ "$action" = smoke ]; then
     wg_state="$wg_home/sessions/smoke-write.stage"
     wg_last="$wg_home/sessions/smoke-write.lastskill"
     # stage：階段鎖狀態檔的格式沿用 sdlc-gate.sh 那一份，這裡照樣寫三欄。
+    # 檔名刻意用舊格式的 sessions/{sid}.stage，順帶把 write-guard 這一側的往後相容也蓋到：
+    # 新路徑不存在時要退回舊路徑讀得出來，否則既有的鎖會在換路徑那一刻整批失效。
     smoke_wg_case "沒有階段鎖" stage 0
     printf 'plan\treasoning-max\tsmoke\n' > "$wg_state"
     smoke_wg_case "階段鎖 plan" stage 2
@@ -1658,7 +1812,7 @@ if [ "$action" = smoke ]; then
   # GITEA_HOST 一律清空：放行的案例會繼續往下走到遠端比對，站台推導得出來就會真的連網，
   # 冒煙不該依賴網路，也不該讓遠端落後把預期放行的案例判成擋下。
   # 一律 </dev/null：hook 模式會讀標準輸入，管線沒人關閉時整支卡死。
-  smoke_vg_case() { # $1=情境 $2=技能名 $3=預期結束碼 $4=額外環境設定（KEY=值，可省略）
+  smoke_vg_case() { # $1=情境 $2=技能名 $3=預期（結束碼，或 deny）$4=額外環境設定（KEY=值，可省略）
     # 第四個參數省略時仍要餵一個合法的 KEY=值 給 env，否則它會把空字串當成要執行的指令。
     # 這個名字沒有任何 hook 讀它，只是佔位。
     _extra="${4:-JSC_VERSION_GUARD_UNUSED=1}"
@@ -1668,12 +1822,13 @@ if [ "$action" = smoke ]; then
       JSC_TOOL_NAME=Skill JSC_SKILL="$2" SKILL="$2" "$_extra" \
       sh "$HOOKS/version-guard.sh" </dev/null 2>&1); _rc=$?
     smoke_n_vg=$((smoke_n_vg + 1))
-    if [ "$_rc" -eq "$3" ]; then
+    if smoke_deny_ok "$3" "$_rc" "$vg_out"; then
       printf '[jsc] version-guard.sh（%s）：exit %s，與預期相同。\n' "$1" "$_rc" >> "$smoke_out"
     else
       smoke_fails=$((smoke_fails + 1))
       printf '[jsc] version-guard.sh（%s）：exit %s，預期 %s，相依版本判定壞了：%s\n' \
-        "$1" "$_rc" "$3" "$(printf '%s' "$vg_out" | tr '\n' ' ' | cut -c1-200)" >> "$smoke_out"
+        "$1" "$_rc" "$(smoke_deny_desc "$3")" \
+        "$(printf '%s' "$vg_out" | tr '\n' ' ' | cut -c1-200)" >> "$smoke_out"
     fi
   }
   # 訊息內容也要比：擋下來卻沒指名是哪一個相依落後，使用者看不出要更新哪一個 plugin，
@@ -1710,7 +1865,7 @@ if [ "$action" = smoke ]; then
     # 一、相依確定落後：擋下，而且訊息要指名是哪一項、需要哪一版、目前哪一版。
     printf '{"name": "jsc-sdlc", "version": "0.1.0", "jsc": {"requires": {"jsc-cli": ">=9.9.9"}}}\n' \
       > "$vg_manifest"
-    smoke_vg_case "相依落後" jsc-sdlc:implement 2
+    smoke_vg_case "相依落後" jsc-sdlc:implement deny
     smoke_vg_msg "相依落後時訊息指名那一項" "jsc-cli 需要 >=9.9.9，目前 0.1.0"
 
     # 二、相依相等或超前都放行：只擋落後，本機超前是開發技能組時的常態，擋了維護者自己動不了。
@@ -1724,7 +1879,7 @@ if [ "$action" = smoke ]; then
     # 三、豁免技能：這一條最要緊，它證明閘門不會把更新與修復的唯一路徑鎖死。同一個 jsc-cli
     # plugin 底下，非豁免的技能在相依落後時被擋、豁免的那一支照樣放行，差別只在豁免清單。
     smoke_vg_case "豁免技能 jsc-cli:deploy，相依落後照樣放行" jsc-cli:deploy 0
-    smoke_vg_case "同 plugin 的非豁免技能 jsc-cli:doctor" jsc-cli:doctor 2
+    smoke_vg_case "同 plugin 的非豁免技能 jsc-cli:doctor" jsc-cli:doctor deny
 
     # 四、fail-open 四條：沒有證據不等於落後。五支 CLI 只有 claude 讀得到本機載入版本，
     # 這四條任何一條改成擋人，另外四支就會被整批鎖死。
@@ -1746,7 +1901,7 @@ if [ "$action" = smoke ]; then
     # 前面那一項則是滿足的：漏掉最後一筆就會變成放行，當場被這一條抓出來。
     printf '{\n  "name": "jsc-sdlc",\n  "version": "0.1.0",\n  "jsc": {\n    "requires": {\n      "jsc-hooks": ">=0.0.1",\n      "jsc-cli": ">=9.9.9"\n    }\n  }\n}\n' \
       > "$vg_manifest"
-    smoke_vg_case "多行縮排 manifest，落後的相依擺在最後一個鍵" jsc-sdlc:implement 2
+    smoke_vg_case "多行縮排 manifest，落後的相依擺在最後一個鍵" jsc-sdlc:implement deny
     smoke_vg_msg "最後一個鍵的落後項也列進訊息" "jsc-cli 需要 >=9.9.9，目前 0.1.0"
     rm -rf "$vg_home"
   else
@@ -2019,7 +2174,7 @@ if [ "$action" = smoke ]; then
   [ "$smoke_n_hook" = "$SMOKE_EXPECT_HOOK" ] \
     || smoke_mismatch="${smoke_mismatch}hook 模式 $smoke_n_hook 條（預期 $SMOKE_EXPECT_HOOK）；"
   [ "$smoke_n_model" = "$SMOKE_EXPECT_MODEL" ] \
-    || smoke_mismatch="${smoke_mismatch}模型來源 $smoke_n_model 條（預期 $SMOKE_EXPECT_MODEL）；"
+    || smoke_mismatch="${smoke_mismatch}模型與階段鎖 $smoke_n_model 條（預期 $SMOKE_EXPECT_MODEL）；"
   [ "$smoke_n_wp" = "$SMOKE_EXPECT_WP" ] \
     || smoke_mismatch="${smoke_mismatch}工作包 $smoke_n_wp 條（預期 $SMOKE_EXPECT_WP）；"
   [ "$smoke_n_rs" = "$SMOKE_EXPECT_RS" ] \
@@ -2039,7 +2194,7 @@ if [ "$action" = smoke ]; then
   [ "$smoke_lines" = "$smoke_total" ] \
     || smoke_mismatch="${smoke_mismatch}結果行數 $smoke_lines 行（預期 $smoke_total）；"
 
-  smoke_breakdown="hook 模式 $SMOKE_EXPECT_HOOK 條、模型來源 $SMOKE_EXPECT_MODEL 條、工作包 $SMOKE_EXPECT_WP 條、重啟閘門 $SMOKE_EXPECT_RS 條、寫入閘門 $SMOKE_EXPECT_WG 條、相依版本 $SMOKE_EXPECT_VG 條、技能名解析 $SMOKE_EXPECT_SN 條、阻擋形態 $SMOKE_EXPECT_DN 條、跨 CLI 貫通 $SMOKE_EXPECT_CX 條、接線形狀 $SMOKE_EXPECT_SH 條"
+  smoke_breakdown="hook 模式 $SMOKE_EXPECT_HOOK 條、模型與階段鎖 $SMOKE_EXPECT_MODEL 條、工作包 $SMOKE_EXPECT_WP 條、重啟閘門 $SMOKE_EXPECT_RS 條、寫入閘門 $SMOKE_EXPECT_WG 條、相依版本 $SMOKE_EXPECT_VG 條、技能名解析 $SMOKE_EXPECT_SN 條、阻擋形態 $SMOKE_EXPECT_DN 條、跨 CLI 貫通 $SMOKE_EXPECT_CX 條、接線形狀 $SMOKE_EXPECT_SH 條"
   if [ -n "$smoke_mismatch" ]; then
     printf 'status=failed reason=%s\n' "冒煙結果行數與預期不符：${smoke_mismatch}判定路徑有增減時要一併改腳本裡的預期條數"
     printf 'lines\t%s\n' "$smoke_lines"
@@ -2050,7 +2205,7 @@ if [ "$action" = smoke ]; then
   fi
 
   if [ "$smoke_fails" -eq 0 ]; then
-    printf 'status=ok reason=%s\n' "九支 hook 的每個接線模式都跑得完，模型來源、工作包歸屬、部署後重啟閘門、寫入提交閘門、相依版本檢查、五支 CLI 的技能名解析、四種阻擋形態、跨 CLI 貫通與各 CLI 的接線形狀的每條路徑也各走過一次（$smoke_breakdown），沒有執行期錯誤"
+    printf 'status=ok reason=%s\n' "九支 hook 的每個接線模式都跑得完，模型與階段鎖、工作包歸屬、部署後重啟閘門、寫入提交閘門、相依版本檢查、五支 CLI 的技能名解析、四種阻擋形態、跨 CLI 貫通與各 CLI 的接線形狀的每條路徑也各走過一次（$smoke_breakdown），沒有執行期錯誤"
     printf 'lines\t%s\n' "$smoke_lines"
     cat "$smoke_out"; rm -f "$smoke_out"; exit 0
   fi
@@ -2147,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)