fix(sdlc-gate): 能力閘門依 CLI 分流，判不出能力就擋下
What：
- current_model_report() 的偵測鏈依 CLI 分流，一支只讀自己的紀錄。claude 讀 transcript 與 hook stdin，codex 讀 hook stdin 與自己的 session 記錄，copilot、antigravity、kiro 本機沒有可讀的模型紀錄，判不出是哪一支 CLI 時不採用任何自動來源。JSC_MODEL 人工覆寫五支都保留，而且一律排在最後。
- session_id() 的退路鏈補上 CLAUDE_CODE_SESSION_ID，cli_name() 補上 CLAUDECODE 與 CLAUDE_CODE_SESSION_ID。
- 階段鎖狀態檔改成 sessions/{CLI 代號}-{sid}.stage。舊路徑仍讀得到，unlock 不帶參數時新舊兩份一起清，也收一個狀態檔路徑當參數。
- check 改成 fail-closed：判不出 CLI、判不出模型、模型不在能力標籤表上，三種一律以 exit 2 擋下該輪提示。每一則擋下的訊息都印出兩條逃生門。
- write-guard.sh 的 stage 模式改讀 lib.sh 的路徑函式，擋人訊息把實際讀到的狀態檔路徑寫進解除指令。
- codex_session_file() 取「全樹最新一支」的做法改掉。
- wire-cli.sh 的冒煙夾具跟著補：模型來源四條各自指定 CLI 代號，另加三種擋下情形、check 的 fail-closed、階段鎖的 CLI 區隔與舊格式相容，這一組的判定條數由四條增為十二條。
- README 的 hooks 表、狀態檔分界表與環境變數表跟著改。
Why：
- 使用者回報兩件事：在 claude 底下被 codex 的模型判定，而且這道閘門應該只鎖能力標籤、不鎖模型。查下來根因是同一個——閘門完全不分辨自己跑在哪一支 CLI 上。
- 偵測鏈不分流，claude 拿不到 transcript 就一路掉進 codex 的 session 記錄，拿別支的模型判這一支。順帶每一輪都對一個上千個檔、兩百多 MB 的目錄樹跑一次 find，宿主 CLI 跟著卡。
- session_id() 讀的變數名在目前的 claude 上並不存在，sid 一路退回 default。cli_name() 犯同一類錯：只認 plugin 接線才有的變數，技能以 Bash 工具呼叫腳本時取不到，一律判成 unknown。
- 前三項合起來的後果是：技能呼叫 lock 算出的檔名，跟 hook 算出的檔名永遠不同。階段鎖上了也對不上，所以這道閘門在 claude 上一直沒有真正生效。
- 狀態檔不分 CLI，各支就共用同一支 default.stage，一支上的鎖擋到另一支。那不只擋提示，write-guard.sh 的 stage 模式連 Write、Edit、MultiEdit 一起擋。
How：
- 政策改成 fail-closed：不知道能力就擋下，知道才比對標籤。原本判不出模型只提醒不擋，那等於「換一支讀不到紀錄的 CLI 就能繞過去」，閘門形同虛設。代價是把人鎖在送不出提示的狀態，所以每一則擋下的訊息都要帶兩條逃生門，照抄就脫困。
- 逃生門的路徑照抄進指令裡。擋人的是 hook，解鎖的是人在殼層手動執行，兩邊算出來的檔名未必相同，不點名就解不到真正擋人的那一支。
- unlock 的參數只收 sessions 目錄底下的 .stage 檔，逃生門不該順便變成任意刪檔的工具。判準刻意不綁這支行程算出的 JSC_HOME：擋人的一側跟解鎖的一側未必相同，綁上去就會把照抄訊息的人擋掉，那正是這個逃生門要避免的事。
- 狀態檔用檔名前綴不用子目錄。外部工具以單層的 sessions/*.stage 盤點階段鎖，改成子目錄會讓每一支鎖從那些盤點裡整批消失。
- 舊路徑只讀不搬也不刪，unlock 一併清掉。只清新的那一份，舊格式的鎖就永遠解不開，被它擋住的人沒有逃生門。
- 變數名只補實測看得到的那幾個，而且只補 claude 這一支。其他 CLI 的變數名與環境特徵沒有實測過，猜一個填進來只會多一個錯誤來源，那幾支本來就由接線設定明確帶 JSC_CLI。
- codex_session_file() 原本寫成 xargs ls -t 再 head -n 1，那是錯的：xargs 依參數長度分批，ls -t 只在自己那一批裡排序，取到的是第一批裡最新的，不是全域最新。改成讓 find 一併印出修改時間再全域排序；沒有 -printf 就退回路徑排序，那些檔名以 ISO 時間開頭，字典序等同時間序。
- 冒煙的擋人案例連訊息一起驗，不只比結束碼。訊息漏掉逃生門一樣是綠燈，而那才是這道 fail-closed 真正的風險。
- 四支腳本併成一筆。write-guard.sh 讀 lib.sh 的路徑函式，wire-cli.sh 是驗這些行為的冒煙夾具，拆開會留下跑不過的中間版本：路徑函式與呼叫端分兩筆，中間那一筆狀態檔的讀寫兩側就對不上。
- 一次性代價：升級後每台機器第一次 SessionStart 會清一次重啟閘門。sid 換了名字，看起來像新的工作階段。只發生這一次。
- 三份 manifest 這一筆不動，版本號另外提升。
Who：
SDLC 階段能力閘門。修的是它一直沒有生效的那條路徑，順帶把 codex session 記錄的取檔方式一起修掉。
This commit is contained in:
@@ -33,7 +33,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
|
||||
| `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 快取目錄，也不指向開發存取庫。
|
||||
@@ -157,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` | 無 | 正確 | 這些是全機共用設定，不是檢查紀錄。 |
|
||||
@@ -169,7 +170,7 @@ Claude 由 `hooks/hooks.json` 自動接線九支 hook；其他 CLI 用 `hooks-in
|
||||
| `tools/jsc-wrap.sh` | 沒有完整 hook 系統的 CLI 的包裝啟動器：匯出 `JSC_CLI`、`JSC_SESSION_ID`，前後接 `session-timer.sh`，結束時自動跑 `scan-logs.sh` 回填，再依序跑一次 `comment-scope.sh sweep` 與 `lang-guard.sh sweep` 掃整個 git 工作區的註解範圍與繁中編碼（copilot 與 antigravity 沒有任何逐輪事件，整個工作階段只有這裡掃得到）。兩次收尾掃描一律不影響結束碼：包裝器原樣回傳 CLI 自己的結束碼，`sweep` 命中只把警告印到 stderr。`JSC_CLI` 存 CLI 代號，實際執行的是對應的執行檔（antigravity 是 agy、kiro 是 kiro-cli） |
|
||||
| `tools/scan-logs.sh` | 離線回填：解析 copilot、antigravity、codex 的原生日誌，把技能用量與階段界線補進 `$JSC_HOME`，重掃不重複 |
|
||||
| `tools/report-error.sh` | 失敗回報流程：把一筆 hook 或工具異常寫成 wiki 的 `ERROR_{HASH}`，並在 `ERROR_CONTENTS` 附上一列索引。目錄頁一律先讀回舊頁再附加新列、整頁寫回，不整頁覆蓋：只有 `wiki-get` 回 4（頁面真的不存在）才用範本建新頁，回 7（金鑰失效）或 8（其他 API 失敗）代表舊內容未知，放棄目錄頁寫入並以 exit 4 回報，免得拿範本蓋掉所有既有列。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/wire-cli.sh` | 單一 CLI 的 hook 生命週期，共四個用法。`{cli}` 是接線：先建立或更新 `$JSC_HOME/current/jsc-hooks` 指向目前這版 plugin，接著把對應的設定編輯、包裝別名安裝、hook 檔建立成穩定路徑，皆以 `<!-- jsc-hooks -->`（或 `# jsc-hooks`）標記整段重寫，重跑等同先移除再重裝；寫完每個檔案會重讀驗證位置正確才回報成功（codex 的 `notify` 必須是根層鍵、`.codex-plugin/plugin.json` 的 matcher 必須是 `Bash`、copilot 必須是小寫 `skill` 且沒有第二種大小寫的事件名、antigravity 的 matcher 必須帶錨點 `^view_file$` 且有 `PreInvocation`、kiro 的 agent JSON 必須成對且 `hooks`、`resources`、`tools` 在最上層並含兩層 `skill://` glob），也會確認寫入路徑能解到既有腳本。matcher 本身要單獨驗：鍵在、matcher 卻錯的形態最難查，回報會說接好了，實際一次都不會被叫用。檔案系統不能建立 symlink 時，會明確回報並退回目前根目錄，不會靜默寫出壞路徑。`status=wired\|degraded\|skipped\|failed` 回報接線結果。`purge {cli}` 是移除：把該 CLI 的**所有** hook 清掉，含非 jsc 的第三方項目，動到的檔案先原樣備份到 `$JSC_HOME/backup/hooks/{cli}/{yyyyMMdd_HHmmss}/`，備份失敗就不移除；移除標記段落時會先去掉標記行前後空白，所以縮排或尾端補空白的 jsc 區塊一樣會移除；移除後重讀驗證，驗不過自動還原備份，以 `status=purged\|skipped\|failed` 回報。`smoke {cli}` 是執行期冒煙測試：九支 hook 的每個接線模式各跑一次，非零退出即為錯誤，另外把五支 CLI 的真實負載各餵進 `skill-name.sh` 一次驗技能名解析、四種阻擋形態各驗一次 `deny.sh`，再把那些負載直接餵進 `restart-gate.sh` 驗「解析→判定→輸出形態」整條串得起來（含 fail-open、豁免放行與 kiro 的注入路徑）——前兩組分開看都會顯示正常，中間接不上照樣是全程放行，那正是先前三支 CLI 失效的樣子；另外用一份暫時的 `$JSC_HOME` 狀態檔把模型來源與階段鎖、工作包歸屬、部署後重啟閘門與寫入提交閘門的每條判定路徑各跑一次並比對結束碼（模型來源的每個案例各自指定 CLI 代號，不跟著這一輪接線的 CLI 走——偵測鏈已依 CLI 分流；「不知道能力就擋下」的三種情形連訊息裡的逃生門一起驗，只比結束碼的話訊息漏掉逃生門也是綠燈），再用一份暫時的 `HOME`（假的 `installed_plugins.json` 與各 plugin 的 manifest）把 `version-guard.sh` 相依版本檢查的每條路徑跑一次——相依落後的擋人與訊息內容、相等與超前的放行、豁免技能在相依落後時照樣放行、四種 fail-open、逃生門，另加一條回歸：多行縮排的 manifest，`jsc.requires` 的最後一個鍵也要解得到。驗的是判定結果本身，不只是腳本跑得完（例外有四個：`sdlc-gate.sh check` 的 exit 2 是階段鎖的設計行為，`comment-scope.sh`、`lang-guard.sh` 掃描模式與 `write-guard.sh` 三種模式的 exit 2 是命中違規的設計行為——`sweep` 在髒工作區本來就會回 2，`write-guard.sh` 在機器剛好鎖在 `plan` 階段時也會回 2，都不算 hook 壞掉），以 `status=ok\|failed` 回報。**結果行數由腳本自己數、自己斷言**：`status=` 之後緊接一行 `lines<TAB>{數量}`，那是其後 `[jsc]` 結果行的實際條數，與腳本內逐類宣告的預期條數比對，不符就回非零。判定路徑增減時只改腳本裡的預期值，散文一律引用這一行，不另外抄一份數字。`status {cli}` 是唯讀盤點：只讀設定檔判斷段落與 matcher 對不對，不寫檔也不執行 hook，claude、codex、copilot、antigravity 回 `wired`，kiro 回 `degraded` 並在 `reason` 講明那是 CLI 限制；每個接線點印一行 `item<TAB>{項目}<TAB>{路徑}<TAB>{present\|missing\|unverified}`，也會把帶版號快取路徑、開發存取庫路徑與不存在的腳本列為缺項。狀態有三格不是兩格：`unverified` 是「這一項驗不了」，只有 `missing` 才算缺項——`kiro-cli agent validate` 在沒登入時印的是環境問題，不是這個檔案的問題，報 `present` 會讓沒驗到的東西看起來像通過，報 `missing` 會把沒登入算成接線缺漏；`status claude` 讀 Claude Code 實際載入的 `installed_plugins.json`，不再檢查目前腳本旁邊那份 `hooks.json`。體檢類技能（`/jsc-cli:doctor`）只能用這個子命令，另外三個都會動到環境；那道限制另有程式層把關，`JSC_READONLY=1` 之下只准 `status` 與 `smoke`，`purge` 與接線一律以 exit 6 拒絕並回報 `status=readonly`，環境不會被動到 |
|
||||
| `tools/scan-hook-errors.sh` | 掃 CLI 原生紀錄找 hook 的執行期錯誤（接線寫對、跑起來出錯）。只有 claude 有 hook 結果紀錄，掃 `~/.claude/projects/**/*.jsonl` 的 `hook_non_blocking_error` 與非空 `hookErrors`；codex、copilot、antigravity、kiro 沒有等價紀錄，一律回報 `unavailable` 並指向 `wire-cli.sh smoke {cli}`。每筆錯誤附加一行 JSON 到 `$JSC_HOME/errors/hooks.jsonl`，`jsc` 欄位標明是不是 jsc 自己的 hook（第三方 hook 的錯誤只回報，不由 jsc 修正）；去重與 `scan-logs.sh` 同法，重掃只讀新增段落，以 `status=clean\|errors\|unavailable` 回報 |
|
||||
|
||||
## 失敗回報範本
|
||||
@@ -225,7 +226,7 @@ Claude 由 `hooks/hooks.json` 自動接線九支 hook；其他 CLI 用 `hooks-in
|
||||
| `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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user