# jsc-hooks — 跨 CLI Hooks

jsc 技能組的 hooks domain：所有 hook **只放在這個 repo**（技能準則）。腳本為 POSIX shell，同時支援 stdin JSON（Claude 格式）與環境變數輸入，適用 claude / codex / copilot / antigravity / kiro。

## 安裝、更新、移除

Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安裝 token 為 `jsc-hooks@jsc`。每個指令一行：

| CLI | 安裝 | 更新 | 移除 |
| --- | --- | --- | --- |
| claude | `claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && claude plugin install jsc-hooks@jsc` | `claude plugin marketplace update jsc && claude plugin update jsc-hooks@jsc` | `claude plugin uninstall jsc-hooks@jsc` |
| codex | `codex plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && codex plugin add jsc-hooks@jsc` | `codex plugin marketplace upgrade jsc` | `codex plugin remove jsc-hooks@jsc` |
| copilot | `copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && copilot plugin install jsc-hooks@jsc` | `copilot plugin marketplace update jsc && copilot plugin update jsc-hooks@jsc` | `copilot plugin uninstall jsc-hooks@jsc` |
| antigravity | `git clone https://gitea.jsc.idv.tw/plugins/hooks.git ~/plugins/hooks && agy plugin install ~/plugins/hooks` | `git -C ~/plugins/hooks pull && agy plugin uninstall jsc-hooks && agy plugin install ~/plugins/hooks` | `agy plugin uninstall jsc-hooks` |
| kiro | `kiro-cli plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && kiro-cli plugin install jsc-hooks@jsc` | `kiro-cli plugin marketplace update jsc && kiro-cli plugin update jsc-hooks@jsc` | `kiro-cli plugin uninstall jsc-hooks@jsc` |

> antigravity 不支援 gitea URL 安裝，改用本地 clone 路徑。批次操作五個 CLI：使用 `/jsc-cli:deploy`。

> 舊入口 `plugins/jsc` 已移除，marketplace 正本移到 `plugins/meta`。marketplace 名稱仍是 `jsc`（取自 marketplace.json 的 `name` 欄位，與存取庫名無關），安裝 token 不變；已從舊入口安裝過的人先執行 `claude plugin marketplace remove jsc`，再依上表重新 add。

## Hooks

| 腳本 | 事件 | 作用 |
| --- | --- | --- |
| `hooks/ste100-guard.sh` | UserPromptSubmit | 注入 STE100 繁體中文輸出規則（hook > prompt 強制層） |
| `hooks/session-timer.sh` | SessionStart / Stop / SessionEnd | 記錄工作階段起訖；`report` 子指令供 `jsc-log:worklog` 取花費時間 |
| `hooks/version-guard.sh` | PreToolUse(Skill) | 技能使用前的版本前置檢查：本機**實際載入**版本落後遠端發佈版本就以 exit 2 擋下該次呼叫並提示更新指令。只擋落後（超前放行，開發技能組時本機本來就會超前）；遠端查不到一律擋（fail-closed），逃生門 `JSC_VERSION_GUARD=off`。豁免 `jsc-cli:deploy`、`jsc-hooks:hooks-install`、`jsc-cli:models`、`jsc-meta:*` |
| `hooks/skill-usage.sh` | PostToolUse(Skill) | 記錄技能使用與呼叫鏈到 `$JSC_HOME/usage/*.jsonl`，供 `jsc-log:stats` 統計 |
| `hooks/sdlc-gate.sh` | UserPromptSubmit | SDLC 階段能力標籤閘門與模型鎖：`lock {stage}` 由 jsc-sdlc 階段技能呼叫，從 transcript 讀出實際模型 id 比對該階段必要標籤（`$JSC_HOME/model-tags.tsv`），不符就拒絕上鎖；`check` 在模型不符時以 exit 2 擋下該輪提示（其他 hook 一律 exit 0，此處是刻意例外）；`unlock` 為逃生門 |

Claude 由 `hooks/hooks.json` 自動接線；其他 CLI 用 `hooks-install` 技能接線、改裝包裝啟動器，或降級為規則檔。

> `version-guard.sh report` 是非 hook 的子指令：印出每個已安裝 jsc plugin 的
> 「{domain} {本機} {遠端} {落後｜最新｜超前｜查詢失敗}」，最後一行 `behind {落後個數}`。
> `jsc-cli:deploy` 用它決定要不要把「更新」設成推薦選項。

## 工具

| 腳本 | 用途 |
| --- | --- |
| `tools/jsc-wrap.sh` | 無 hook 系統 CLI 的包裝啟動器：匯出 `JSC_CLI`、`JSC_SESSION_ID`，前後接 `session-timer.sh`，結束時自動跑 `scan-logs.sh` 回填 |
| `tools/scan-logs.sh` | 離線回填：解析 copilot、antigravity、codex 的原生日誌，把技能用量與階段界線補進 `$JSC_HOME`，重掃不重複 |
| `tools/wire-cli.sh` | 單一 CLI 的接線流程：`{cli}` 對應的設定編輯、包裝別名安裝、hook 檔建立，皆以 `<!-- jsc-hooks -->`（或 `# jsc-hooks`）標記整段取代，重跑不重複；以 `status=wired\|degraded\|skipped` 回報結果 |

## 失敗回報範本

這兩個模板給外層的 hook 失敗回報流程使用，不改動現有 hook 行為。
失敗時若要寫入 wiki，套用這兩個檔案即可。

| 範本 | 用途 |
| --- | --- |
| `templates/error-page.md` | 單筆 hook 異常頁 `ERROR_{HASH}`，記錄當次失敗的觸發條件、錯誤摘要與處理結果。 |
| `templates/error-contents.md` | 異常目錄 `ERROR_CONTENTS`，彙整所有異常頁，方便先看最新問題再往下追。 |

## Skills 目錄

呼叫方式：Claude / Antigravity `/jsc-hooks:{name}`；Codex `${name}`；Copilot / Kiro 描述需求自動觸發。

<!-- JSC-SKILLS:START -->

### `hooks-install`

把四支 hook 接線到所有已安裝的 CLI：偵測 CLI 後，逐一呼叫 `tools/wire-cli.sh {cli}` 完成接線（claude 由 `hooks.json` 自動接線，無需寫入）。copilot、antigravity 由該腳本裝上 `tools/jsc-wrap.sh` 包裝別名補上計時與用量回填（結束時自動跑 `tools/scan-logs.sh`），語言規則仍追加到各自的規則檔（以 `<!-- jsc-hooks -->` 標記整段取代，不重複追加）。codex、kiro 的 SDLC 模型鎖降級為技能步驟檢查，鎖檔仍由 SDLC 技能直接呼叫 `sdlc-gate.sh lock` 寫入。腳本以 `status=wired|degraded|skipped` 回報結果，供技能對照 verify 表。

<!-- JSC-SKILLS:END -->

## 環境變數

| 變數 | 用途 | 未設定時 |
| --- | --- | --- |
| `JSC_HOME` | Hook 資料目錄 | 預設 `~/.jsc` |
| `JSC_VERSION_GUARD` | 設 `off` 完全略過版本前置檢查（離線工作用） | 啟用檢查 |
| `JSC_VERSION_TTL` | 遠端版本查詢的快取秒數 | 預設 600 |
| `JSC_CLI` / `JSC_SESSION_ID` / `JSC_SKILL` | 非 Claude CLI 接線時由 `tools/jsc-wrap.sh` 或接線設定提供 | 安靜降級 |
| `JSC_MODEL` | 非 Claude CLI 的目前模型，供 `sdlc-gate.sh` 比對；優先序在 transcript 實際值與 stdin `model` 之後 | 改讀 `~/.claude/settings.json`，再不行就安靜降級 |

## 相關 domain

- [`jsc-cli`](https://gitea.jsc.idv.tw/plugins/cli)：CLI 偵測（`tools/detect-clis.sh`）
- [`jsc-log`](https://gitea.jsc.idv.tw/plugins/log)：讀取本 domain 產出的工時與用量資料