diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index e21b3b4..09c2b65 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-hooks", - "version": "0.1.8", + "version": "0.2.2", "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index ed01596..56a1664 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-hooks", - "version": "0.1.8", + "version": "0.2.2", "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查", "skills": "./skills" } diff --git a/.gitignore b/.gitignore index 710e336..1db0849 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,6 @@ Thumbs.db # 暫存 *.tmp *.log + +# 本機接線檔（jsc-hooks:hooks-install 產生，內含本機絕對路徑） +.kiro/ diff --git a/AGENTS.md b/AGENTS.md index e627860..5da8f18 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # jsc-hooks — 給 AI 助理的指引 -本 repo 是 jsc 技能組的 `hooks` domain（跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查），可同時被 Claude Code / Codex / Copilot / Antigravity / Kiro 使用。 +本 repo 是 jsc 技能組的 `hooks` domain（跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍檢查、繁中與編碼檢查），可同時被 Claude Code / Codex / Copilot / Antigravity / Kiro 使用。 ## 規則 @@ -8,7 +8,9 @@ 2. 技能位於 `skills/{name}/SKILL.md`；處理任務前先比對需求與各技能的 `description`，相符就載入並依其步驟執行。 3. 技能準則的唯一來源：`plugins/meta` 存取庫的 `references/guidelines.md`。 4. 所有 hook 只放在 `jsc-hooks`；gitea 操作一律經由 `jsc-gitea` 的 `tools/gitea.sh`；問使用者一律依 `jsc-ask:ask` 的決策樹規則。 -5. 主 agent 不需要處理細節的流程，一律建立 sub agent 處理。 +5. 註解範圍規則正文的唯一來源：`jsc-review` 的 `references/comment-scope.md`。本存取庫只放 `hooks/comment-scope.sh` 的判定實作，不留規則清單副本，接線腳本要用規則文字時一律取腳本的實際輸出。`comment-scope.sh` 有 `prompt`、無參數逐檔掃描、`sweep` 掃整個 git 工作區三種模式；掃描時機每個 CLI 都不同（claude 逐檔即時、codex 每輪結束、kiro 每輪提示送出時、copilot 與 antigravity 只有工作階段結束時），談覆蓋範圍時一律據實分開講，不得寫成五支一樣。 +6. 所有非程式碼輸出一律繁體中文、UTF-8、無亂碼、無簡體字：程式碼註解、commit 訊息、PR 描述、wiki 頁、對使用者的回報、README 與各種文件都算。規則正文的唯一來源同樣是 `plugins/meta` 的 `references/ste100.md`，本存取庫只放 `hooks/lang-guard.sh` 的判定實作與 `hooks/simplified.txt` 的機檢字表。那份字表是本存取庫的單一真實來源，刻意排除繁體也在用的字（后、台、干、只、里、面、制、志），增刪前先確認不會製造誤報。`lang-guard.sh` 的三種模式與掃描時機跟 `comment-scope.sh` 一致，但它掃整個檔案而不只掃註解行，`.md` 與純文字檔也照掃。 +7. 主 agent 不需要處理細節的流程，一律建立 sub agent 處理。 ## 呼叫慣例 diff --git a/README.md b/README.md index 471900a..481c135 100644 --- a/README.md +++ b/README.md @@ -26,11 +26,24 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安 | `hooks/session-timer.sh` | SessionStart / Stop / SessionEnd | 記錄工作階段起訖。子指令：`start` 記起始時間（已有紀錄就不動，給 claude 這種每階段有自己 session id 的 CLI）、`restart` 一律覆寫起始時間（給接不到 session id 的 kiro，不覆寫會把上一階段算進來）、`mark` 更新最後活動時間、`report` 供 `jsc-log:worklog` 取花費時間 | | `hooks/version-guard.sh` | PreToolUse(Skill) | 技能使用前的版本前置檢查：本機**實際載入**版本落後遠端發佈版本就以 exit 2 擋下該次呼叫並提示更新指令（更新指令依當前 CLI 給）。只擋落後這一種情況：超前放行（開發技能組時本機本來就會超前），讀不到本機版本、推導不出站台、查不到遠端版本也一律放行。逃生門 `JSC_VERSION_GUARD=off`。豁免 `jsc-cli:deploy`、`jsc-hooks:hooks-install`、`jsc-cli:models`、`jsc-meta:*` | | `hooks/skill-usage.sh` | PostToolUse(Skill) | 記錄技能使用與呼叫鏈到 `$JSC_HOME/usage/*.jsonl`，供 `jsc-log:stats` 統計 | +| `hooks/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 階段技能呼叫，從 transcript 讀出實際模型 id 比對該階段必要標籤（`$JSC_HOME/model-tags.tsv`），不符就拒絕上鎖；`check` 在模型不符時以 exit 2 擋下該輪提示（其他 hook 一律 exit 0，此處是刻意例外）；`unlock` 為逃生門。另含工作包 PR 閘門：`wp-lock {owner}/{repo} {index}` 記下一筆未結清的工作包 PR、`wp-unlock {owner}/{repo} {index}` 結清那一筆（檔案不存在也算成功）、`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 擋下 `plan`、`analyze`、`maintain`，但一律放行 `implement`（結清 PR 正是 implement 的步驟，擋它會鎖死流程）——這一層是整個存取庫共用的粗粒度提醒，「某個候選工作包能不能挑」的細粒度判斷在 `jsc-sdlc/tools/wp-gate.sh check-deps`，不是這裡。逃生門 `JSC_WP_GATE=off`。這道閘門只讀檔案、不打網路，PR 的真實合併狀態由 `jsc-sdlc/tools/wp-gate.sh` 查證 | -Claude 由 `hooks/hooks.json` 自動接線五支 hook；其他 CLI 用 `hooks-install` 技能接線、改裝包裝啟動器，或降級為規則檔。 +Claude 由 `hooks/hooks.json` 自動接線七支 hook；其他 CLI 用 `hooks-install` 技能接線、改裝包裝啟動器，或降級為規則檔。 -> 覆蓋範圍要據實看待：只有 claude 同時有 PreToolUse 與 UserPromptSubmit，五支 hook 全接得上，回報 `wired`。codex、copilot、antigravity、kiro 都沒有 pre-tool hook，接不上 `version-guard.sh` 的版本前置檢查，SDLC 模型鎖也只剩技能步驟檢查，這四個 CLI 一律回報 `degraded`，靠 `/jsc-cli:deploy` 定期更新。codex 另外沒有工作階段開始事件，計時改由 `tools/jsc-wrap.sh` 的 `codex` 別名在啟動當下開始；沒走別名啟動時，時間從第一輪回應算起。 +> 覆蓋範圍要據實看待：只有 claude 同時有 PreToolUse、PostToolUse 與 UserPromptSubmit，七支 hook 全接得上，回報 `wired`。codex、copilot、antigravity、kiro 都沒有 pre-tool hook，接不上 `version-guard.sh` 的版本前置檢查，SDLC 模型鎖也只剩技能步驟檢查，這四個 CLI 一律回報 `degraded`，靠 `/jsc-cli:deploy` 定期更新。codex 另外沒有工作階段開始事件，計時改由 `tools/jsc-wrap.sh` 的 `codex` 別名在啟動當下開始；沒走別名啟動時，時間從第一輪回應算起。 + +> `comment-scope.sh` 與 `lang-guard.sh` 五個 CLI 都掃得到，接的是同一批位置，但時機不同，不能當成五支一樣： + +| CLI | 掃描時機 | 接在哪裡 | +| --- | --- | --- | +| claude | 逐檔即時，寫完哪個檔就掃哪個 | PostToolUse | +| codex | 每輪結束，掃整個 git 工作區 | `config.toml` 的根層 `notify` | +| kiro | 每輪提示送出時，掃整個 git 工作區（掃到的是上一輪寫的檔） | `.kiro/hooks/jsc-hooks.json` 的 `userPromptSubmit` | +| copilot、antigravity | 工作階段結束時掃一次 | `tools/jsc-wrap.sh` 收尾 | + +> 上表對 `comment-scope.sh` 與 `lang-guard.sh` 同時成立，兩支接在同一批位置。`sweep` 看的是 `git diff HEAD`，涵蓋範圍與 claude 一樣，差的是回饋速度：claude 當下就叫，其他四個要等到該輪或該階段結束。不在 git 工作區內時 `sweep` 安靜 exit 0，等於沒掃。規則提示（`prompt` 模式）在五個 CLI 都照樣寫進規則檔，三段（STE100、註解範圍、繁中編碼）共用同一個標記段落——晚一輪的警告，價值仍低於一開始就不要寫。判不出來的項目（專案代號、客戶名稱）一律交給 `/jsc-review:code-review` 第 2 組。 > `version-guard.sh report` 是非 hook 的子指令：印出每個已安裝 jsc plugin 的 > 「{domain} {本機} {遠端} {落後｜最新｜超前｜查詢失敗}」，最後一行 `behind {落後個數}`。 @@ -43,10 +56,10 @@ 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` 回填。`JSC_CLI` 存 CLI 代號，實際執行的是對應的執行檔（antigravity 是 agy、kiro 是 kiro-cli） | +| `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 位置由 `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}` 是接線：對應的設定編輯、包裝別名安裝、hook 檔建立，皆以 ``（或 `# jsc-hooks`）標記整段重寫，重跑等同先移除再重裝；寫完每個檔案會重讀驗證位置正確才回報成功（codex 的 `notify` 必須是根層鍵、kiro 的 JSON 必須成對且 `on`、`run` 在最上層），以 `status=wired\|degraded\|skipped\|failed` 回報。`purge {cli}` 是移除：把該 CLI 的**所有** hook 清掉，含非 jsc 的第三方項目，動到的檔案先原樣備份到 `$JSC_HOME/backup/hooks/{cli}/{yyyyMMdd_HHmmss}/`，備份失敗就不移除，移除後重讀驗證，驗不過自動還原備份，以 `status=purged\|skipped\|failed` 回報。`smoke {cli}` 是執行期冒煙測試：五支 hook 各跑一次，非零退出即為錯誤（唯一例外是 `sdlc-gate.sh check` 的 exit 2，那是階段鎖的設計行為），以 `status=ok\|failed` 回報。`status {cli}` 是唯讀盤點：只讀設定檔判斷標記段落在不在，不寫檔也不執行 hook，每個接線點印一行 `item{項目}{路徑}{present\|missing}`，以 `status=wired\|degraded\|unwired\|skipped` 回報（結束碼 0、1、5、3）。體檢類技能（`/jsc-cli:doctor`）只能用這個子命令，另外三個都會動到環境 | +| `tools/wire-cli.sh` | 單一 CLI 的 hook 生命週期，共三個用法。`{cli}` 是接線：對應的設定編輯、包裝別名安裝、hook 檔建立，皆以 ``（或 `# jsc-hooks`）標記整段重寫，重跑等同先移除再重裝；寫完每個檔案會重讀驗證位置正確才回報成功（codex 的 `notify` 必須是根層鍵、kiro 的 JSON 必須成對且 `on`、`run` 在最上層），以 `status=wired\|degraded\|skipped\|failed` 回報。`purge {cli}` 是移除：把該 CLI 的**所有** hook 清掉，含非 jsc 的第三方項目，動到的檔案先原樣備份到 `$JSC_HOME/backup/hooks/{cli}/{yyyyMMdd_HHmmss}/`，備份失敗就不移除，移除後重讀驗證，驗不過自動還原備份，以 `status=purged\|skipped\|failed` 回報。`smoke {cli}` 是執行期冒煙測試：七支 hook 的每個接線模式各跑一次，非零退出即為錯誤（例外有三個：`sdlc-gate.sh check` 的 exit 2 是階段鎖的設計行為，`comment-scope.sh` 與 `lang-guard.sh` 掃描模式的 exit 2 是掃到違規的設計行為——`sweep` 在髒工作區本來就會回 2，不算 hook 壞掉），以 `status=ok\|failed` 回報。`status {cli}` 是唯讀盤點：只讀設定檔判斷標記段落在不在，不寫檔也不執行 hook，每個接線點印一行 `item{項目}{路徑}{present\|missing}`，以 `status=wired\|degraded\|unwired\|skipped` 回報（結束碼 0、1、5、3）。體檢類技能（`/jsc-cli:doctor`）只能用這個子命令，另外三個都會動到環境 | | `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` 回報 | ## 失敗回報範本 @@ -67,7 +80,7 @@ Claude 由 `hooks/hooks.json` 自動接線五支 hook；其他 CLI 用 `hooks-in ### `hooks-install` -把五支 hook 接線到所有已安裝的 CLI，每個 CLI 走四道關卡：先 `tools/wire-cli.sh purge {cli}` 備份後移除所有 hook（含非 jsc 的第三方項目，乾淨起跑才分得清後續失敗是誰的），再 `tools/wire-cli.sh {cli}` 接線（claude 由 `hooks.json` 自動接線，無需寫入），接著 `tools/wire-cli.sh smoke {cli}` 驗執行期，最後 `tools/scan-hook-errors.sh --cli {cli}` 掃原生紀錄。codex、copilot、antigravity 由接線腳本裝上 `tools/jsc-wrap.sh` 包裝別名補上計時與用量回填（結束時自動跑 `tools/scan-logs.sh`），語言規則仍重寫到各自的規則檔（以 `` 標記整段取代，等同先移除再重裝，不重複追加）。codex、copilot、antigravity、kiro 的 SDLC 模型鎖降級為技能步驟檢查，鎖檔仍由 SDLC 技能直接呼叫 `sdlc-gate.sh lock` 寫入；這四個 CLI 沒有 pre-tool hook，版本前置檢查接不上，腳本會在 `reason` 裡講明，只有 claude 回報 `wired`，也只有 claude 掃得到執行期錯誤紀錄。任一關卡出錯（purge、接線、冒煙失敗，或掃到 `jsc=true` 的執行期錯誤）就先寫 `ERROR_{HASH}`，再交給 `repair` 技能接手並以 `develop` PR 收尾；此時允許中止剩下的安裝，但修正一定要開始。掃到 `jsc=false` 的第三方 hook 錯誤只回報，不轉修正。 +把七支 hook 接線到所有已安裝的 CLI，每個 CLI 走四道關卡：先 `tools/wire-cli.sh purge {cli}` 備份後移除所有 hook（含非 jsc 的第三方項目，乾淨起跑才分得清後續失敗是誰的），再 `tools/wire-cli.sh {cli}` 接線（claude 由 `hooks.json` 自動接線，無需寫入），接著 `tools/wire-cli.sh smoke {cli}` 驗執行期，最後 `tools/scan-hook-errors.sh --cli {cli}` 掃原生紀錄。codex、copilot、antigravity 由接線腳本裝上 `tools/jsc-wrap.sh` 包裝別名補上計時與用量回填（結束時自動跑 `tools/scan-logs.sh`），語言規則仍重寫到各自的規則檔（以 `` 標記整段取代，等同先移除再重裝，不重複追加）。codex、copilot、antigravity、kiro 的 SDLC 模型鎖降級為技能步驟檢查，鎖檔仍由 SDLC 技能直接呼叫 `sdlc-gate.sh lock` 寫入；這四個 CLI 沒有 pre-tool hook，版本前置檢查接不上；也沒有 post-tool hook，`comment-scope.sh` 接不到逐檔即時掃描，改用 `sweep` 掃整個 git 工作區——codex 每輪結束、kiro 每輪提示送出時、copilot 與 antigravity 只有工作階段結束時掃一次，腳本會在 `reason` 裡講明各自的時機，只有 claude 回報 `wired`，也只有 claude 掃得到執行期錯誤紀錄。任一關卡出錯（purge、接線、冒煙失敗，或掃到 `jsc=true` 的執行期錯誤）就先寫 `ERROR_{HASH}`，再交給 `repair` 技能接手並以 `develop` PR 收尾；此時允許中止剩下的安裝，但修正一定要開始。掃到 `jsc=false` 的第三方 hook 錯誤只回報，不轉修正。 ### `repair` @@ -86,6 +99,9 @@ Claude 由 `hooks/hooks.json` 自動接線五支 hook；其他 CLI 用 `hooks-in | `JSC_VERSION_GUARD` | 設 `off` 完全略過版本前置檢查（離線工作用） | 啟用檢查 | | `JSC_VERSION_TTL` | 遠端版本查詢的快取秒數 | 預設 600 | | `JSC_WP_GATE` | 設 `off` 完全略過工作包 PR 閘門（`wp-check` 一律放行） | 啟用閘門 | +| `JSC_COMMENT_SCOPE` | 設 `off` 完全略過註解範圍檢查（`comment-scope.sh` 三種模式都直接結束） | 啟用檢查 | +| `JSC_LANG_GUARD` | 設 `off` 完全略過繁中與編碼檢查（`lang-guard.sh` 三種模式都直接結束） | 啟用檢查 | +| `JSC_CHANGED_FILE` | 非 Claude CLI 要掃描的檔案路徑，代替 stdin JSON 的 `file_path`，供 `comment-scope.sh` 與 `lang-guard.sh` 使用 | 安靜降級，不掃描 | | `JSC_CLI` / `JSC_SESSION_ID` / `JSC_SKILL` / `JSC_TOOL_NAME` | 非 Claude CLI 接線時由 `tools/jsc-wrap.sh` 或接線設定提供，代替 stdin JSON 的 `session_id`、`skill`、`tool_name`（`version-guard.sh` 也收沒有前綴的 `SKILL`、`TOOL_NAME`） | 安靜降級 | | `JSC_MODEL` | 非 Claude CLI 的目前模型，供 `sdlc-gate.sh` 比對；優先序在 transcript 實際值與 stdin `model` 之後 | 改讀 `~/.claude/settings.json`，再不行就安靜降級 | diff --git a/hooks/comment-scope.sh b/hooks/comment-scope.sh new file mode 100755 index 0000000..d00d749 --- /dev/null +++ b/hooks/comment-scope.sh @@ -0,0 +1,148 @@ +#!/usr/bin/env sh +# comment-scope.sh — 程式碼註解不得夾帶文件相關資訊（hook > prompt 的強制層）。 +# 規則正文的唯一來源：jsc-review 的 references/comment-scope.md。本腳本只實作可用樣式判定的項目； +# 專案代號、客戶名稱這類無法用樣式判定的，交給 jsc-review:code-review 第 2 組人工審查。 +# +# 用法: +# comment-scope.sh prompt 注入規則摘要（UserPromptSubmit 或規則檔取文字用） +# comment-scope.sh 掃描剛寫入的單一檔案（PostToolUse） +# comment-scope.sh sweep [dir] 掃描整個工作區這次改過的所有檔案（沒有 post-tool hook 的 CLI 用） +# +# 為什麼要有 sweep：只有 claude 接得到 PostToolUse，逐檔精準掃得到。codex 只有每輪結束的 +# notify、kiro 只有 userPromptSubmit、copilot 與 antigravity 只有包裝別名，這四個都拿不到 +# 「剛剛寫了哪個檔」，只能改成掃整個工作區的 git diff。時機晚一點，涵蓋範圍一樣。 +# +# 輸入相容： +# Claude: PostToolUse 的 stdin JSON，取 tool_input.file_path。 +# 其他 CLI: 環境變數 JSC_CHANGED_FILE。 +# 兩者都取不到就安靜降級（exit 0）。 +# +# 掃描範圍：檔案在 git 工作區內就只掃 `git diff HEAD` 的新增行，不翻舊帳； +# 不在 git 內或檔案尚未追蹤才整檔掃描。sweep 一律只看 git diff。 +# +# 結束碼：0=沒命中或資料不足；2=命中，訊息走 stderr 交回模型自行修正（不擋寫入，檔案已經寫好了）。 +# 逃生門：JSC_COMMENT_SCOPE=off。 +set -u + +. "$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)/lib.sh" 2>/dev/null || true + +[ "${JSC_COMMENT_SCOPE:-on}" = "off" ] && exit 0 + +if [ "${1:-}" = "prompt" ]; then + echo "[jsc] 程式碼註解只寫「為什麼這樣寫」，不寫「這件事記在哪份文件」。禁止寫入：議題與 PR 編號、變更單編號、wiki 頁編號與網址、工作包編號、TDD 待辦編號、使用者故事與驗收條件與測試案例編號、規格章節與稽核項編號、commit hash 與分支名、版本號與 Sprint 與里程碑、人名與認領者與 @ 提及、工時估算、專案代號與客戶名稱、產生來源署名、外部文件連結。" + echo "[jsc] 註解可以寫：日期與時間戳、需求變更歷程、RFC 與 ISO 標準編號、CVE 編號、第三方套件 issue 連結、授權標頭與 SPDX 標記、@deprecated 與 @since 等語言原生標記。命中禁止項就把編號指向的內容搬進註解，再刪掉編號。規則正文見 jsc-review 的 references/comment-scope.md。" + exit 0 +fi + +hit() { # $1=樣式 $2=說明；命中就把說明與最多三行證據印到 stdout + m=$(printf '%s\n' "$cleaned" | grep -nE "$1" | head -n 3) + [ -n "$m" ] || return 0 + printf ' %s\n' "$2" + printf '%s\n' "$m" | sed 's/^/ /' +} + +scan_file() { # $1=檔案路徑；命中就把報告印到 stdout 並回傳 1，沒命中回傳 0 + f=$1 + [ -f "$f" ] || return 0 + + # 非程式碼檔不受本規則限制：markdown、純文字、資料檔沒有「程式碼註解」。 + case "$f" in + *.md|*.markdown|*.txt|*.rst|*.json|*.csv|*.tsv|*.svg|*.lock|*.log|*COMMIT_EDITMSG) return 0 ;; + esac + # 二進位檔跳過。只認 NUL 位元組——拿「非可列印字元」當判準會把所有含中文的檔案誤判成二進位。 + raw=$(head -c 1024 "$f" 2>/dev/null | wc -c) + txt=$(head -c 1024 "$f" 2>/dev/null | LC_ALL=C tr -d '\000' | wc -c) + [ "$raw" = "$txt" ] || return 0 + + d=$(dirname -- "$f") + if git -C "$d" rev-parse --is-inside-work-tree >/dev/null 2>&1 && + git -C "$d" ls-files --error-unmatch -- "$f" >/dev/null 2>&1; then + lines=$(git -C "$d" diff HEAD -- "$f" 2>/dev/null | sed -n 's/^+[^+]/&/p' | cut -c2-) + [ -n "$lines" ] || return 0 + else + lines=$(cat "$f" 2>/dev/null) + fi + + # 只留註解行：行首註解符號，或行中出現 // 與 # 的行尾註解。 + comments=$(printf '%s\n' "$lines" | grep -E '^[[:space:]]*(//|#|--|\*|/\*|` (or `# jsc-hooks`) marker block, re-reads every file it wrote, and confirms the block is present and correctly placed before it prints a success status. Trust its first line, `status=wired|degraded|skipped|failed reason=...`. Exit 2 means a bad CLI name, not a wiring outcome — fix the name and rerun. Done when every installed CLI has printed exactly one `status=` line and none exited 2. -4. For each installed CLI, run `tools/wire-cli.sh smoke {cli}`. This runs all five hooks once each and catches what the wiring check cannot see: a hook that is wired correctly and still fails when it executes. Done when every CLI has printed one `status=ok|failed reason=...` line plus one result line per hook. +4. For each installed CLI, run `tools/wire-cli.sh smoke {cli}`. This runs all seven hooks once each, every wired mode included, and catches what the wiring check cannot see: a hook that is wired correctly and still fails when it executes. Done when every CLI has printed one `status=ok|failed reason=...` line plus one result line per hook. 5. For each installed CLI, run `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 step 4 alone. Done when every CLI has printed one `status=clean|errors|unavailable reason=...` line and the four `unavailable` CLIs are reported as exactly that, not as clean. 6. For each error — `purge` failed, wiring failed, smoke failed, 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. A scanned error with `jsc=false` belongs to a third-party hook: report it and leave it alone. Done when each error has either an `ERROR_{HASH}` page name on stdout, or an empty exit 0 meaning `JSC_WIKI_REPO_ERROR` and `JSC_WIKI_REPO` are both unset — in that second case carry the reason into step 7 instead. Skip this step when every CLI passed all four checks. 7. Report four results per CLI — purge, wiring, smoke, scan — each with the reason its script printed, plus any `ERROR_{HASH}` page name and repair PR URL. Done when every detected CLI has exactly one status per check and every repair has a PR against `develop`. @@ -33,6 +44,9 @@ The detailed flow **MUST run as a sub agent**; the main agent only reports the s - `session-timer.sh` takes `start` (keep an existing start time), `restart` (always overwrite it, for a CLI with no session id — kiro), `mark` and `report`. `wire-cli.sh` picks the right one per CLI; do not hand-edit the generated hook files. - `purge` reaches the user-level config only. Hooks that another plugin ships in its own `hooks.json` stay active, and uninstalling that plugin is the only way to clear them — say so when reporting, and treat their errors as third-party. - Backups land in `$JSC_HOME/backup/hooks/{cli}/{yyyyMMdd_HHmmss}/`, one directory per purge run, under the original file names. Hand that path to the user whenever a purge removed something. -- `smoke` treats `sdlc-gate.sh check` exit 2 as healthy: that exit is the stage lock blocking a turn on purpose, not a runtime error. +- `smoke` treats `sdlc-gate.sh check` exit 2 as healthy: that exit is the stage lock blocking a turn on purpose, not a runtime error. `comment-scope.sh` and `lang-guard.sh` exit 2 count as healthy for the same reason — the scan found something and warned about it. Their no-argument mode has no file name during smoke and exits 0 in silence; `sweep` depends on the worktree it runs in, so it answers 2 whenever that worktree happens to carry an offending comment, a simplified character or a mojibake sequence. None of these is a broken hook. +- `comment-scope.sh` takes three modes: `prompt` (inject the rule summary at UserPromptSubmit), no argument at all (scan the file just written at PostToolUse, reading `file_path` from stdin JSON or `JSC_CHANGED_FILE`), and `sweep [dir]` (scan every file the git worktree changed, for the four CLIs with no post-tool hook). All scanning modes read only the lines a diff added, skip markdown and binary files, and turn off entirely with `JSC_COMMENT_SCOPE=off`. The rule text itself lives in one place only, `jsc-review`'s `references/comment-scope.md`; never restate the list anywhere in this repo. +- `lang-guard.sh` takes the same three modes as `comment-scope.sh` and is wired at the same places, but it scans differently on purpose: it reads the whole file rather than comment lines only, and it does scan `.md` and plain-text files, because those are exactly the non-code output the rule targets. It flags three things — simplified characters (word list in `hooks/simplified.txt`, the single source of truth for this repo; a missing list skips that check in silence), mojibake (U+FFFD and double-encoding remnants), and non-UTF-8 encoding (decided by `iconv`; no `iconv` skips that check). It skips binaries, generated files, and the three files whose subject is those very characters (`simplified.txt`, `ste100-guard.sh`, `lang-guard.sh`). Turn it off with `JSC_LANG_GUARD=off`. The rule text lives only in `jsc-meta`'s `references/ste100.md`. +- `jsc-wrap.sh` runs both sweeps after the CLI exits and always returns the CLI's own exit code. A `sweep` hit warns on stderr and changes nothing else — never let a language or comment warning turn a successful CLI run into a failed one. - `tools/report-error.sh` is operator- or skill-invoked only. Never wire it to fire from a failing hook: hooks stay silent and exit 0, and a failing hook that reports itself can loop. - Data lands in `$JSC_HOME` (default `~/.jsc`), consumed by `jsc-log:worklog` and `jsc-log:stats`. diff --git a/tools/jsc-wrap.sh b/tools/jsc-wrap.sh index cc3adf6..e379865 100755 --- a/tools/jsc-wrap.sh +++ b/tools/jsc-wrap.sh @@ -2,7 +2,9 @@ # jsc-wrap.sh — 無 hook 系統 CLI 的包裝啟動器（例：copilot、antigravity）。 # 用法: jsc-wrap.sh {cli} [args...] # 行為: 匯出 JSC_CLI 與 JSC_SESSION_ID → session-timer start → 執行 CLI → -# 結束後 session-timer mark 並以 scan-logs.sh 回填用量，最後回傳 CLI 的結束碼。 +# 結束後 session-timer mark、以 scan-logs.sh 回填用量、以 comment-scope.sh sweep +# 掃一次整個工作區的註解範圍，再以 lang-guard.sh sweep 掃一次繁中與編碼， +# 最後回傳 CLI 的結束碼。 # 注意: JSC_CLI 存的是 CLI 代號（antigravity、kiro），實際執行的是 cli_bin 對應的 # 執行檔（agy、kiro-cli）。直接拿代號當指令跑會 127，因為沒有這兩個執行檔。 HERE=$(cd "$(dirname "$0")" && pwd) @@ -25,4 +27,13 @@ rc=$? # 收尾：補記結束時間，並從原生日誌回填技能用量 sh "$HOOKS/session-timer.sh" mark /dev/null | sed '/^exit /d'; } +# 註解範圍規則段落的唯一來源：comment-scope.sh prompt 的實際輸出。 +# 規則正文不在這裡抄一份：抄了就會跟腳本各自漂移，兩邊講的規則對不起來。 +comment_scope_text() { sh "$HOOKS/comment-scope.sh" prompt 2>/dev/null | sed '/^exit /d'; } + +# 繁中與編碼規則段落的唯一來源：lang-guard.sh prompt 的實際輸出。理由同上，不在這裡抄一份。 +lang_guard_text() { sh "$HOOKS/lang-guard.sh" prompt 2>/dev/null | sed '/^exit /d'; } + +# 寫進規則檔的完整段落：語言規則加註解範圍規則加繁中編碼規則，共用同一組 jsc-hooks 標記。 +# 三段合在一個標記段落裡，purge 與重跑接線都是整段處理，不必各自再記一組標記。 +rules_text() { ste100_text; comment_scope_text; lang_guard_text; } + +# 驗證：規則檔真的收到註解範圍那一段了嗎。比對字串取自腳本的第一行實際輸出， +# 不是另外抄一句關鍵字——抄的關鍵字改腳本時不會跟著改，驗證就會永遠通過。 +# $1=檔案 +has_comment_scope() { + _first=$(comment_scope_text | head -n1) + [ -n "$_first" ] || return 1 + grep -qF "$_first" "$1" 2>/dev/null +} + +# 驗證：規則檔真的收到繁中與編碼那一段了嗎。同樣取腳本的第一行實際輸出來比對，理由同上。 +# $1=檔案 +has_lang_guard() { + _first=$(lang_guard_text | head -n1) + [ -n "$_first" ] || return 1 + grep -qF "$_first" "$1" 2>/dev/null +} + # 以標記整段取代（冪等）；標記不存在就在檔尾新增；檔案不存在就建立。 # 適用 markdown 規則檔與 shell rc 檔：這兩種檔案沒有「區段」概念，附在檔尾就對了。 # $1=檔案 $2=開頭標記行 $3=結尾標記行 $4=標記之間要寫入的內容 @@ -588,7 +632,10 @@ if [ "$action" = smoke ]; then _h="$1"; _s="${2:-}" # 技能名一律清空：冒煙要驗的是「沒有技能情境時腳本跑得完」。留著繼承來的 JSC_SKILL， # sdlc-gate.sh wp-check skill 會拿它當真實呼叫判定，有未結清 PR 時就誤報成執行期錯誤。 - _out=$(printf '{}' | JSC_CLI="$cli" JSC_SKILL="" SKILL="" sh "$HOOKS/$_h" $_s 2>&1); _rc=$? + # JSC_CHANGED_FILE 同理清空：留著繼承來的檔名，comment-scope.sh 與 lang-guard.sh 會真的 + # 去掃那個檔，掃到違規就 exit 2，冒煙測試變成看環境臉色，測不出腳本本身跑不跑得完。 + _out=$(printf '{}' | JSC_CLI="$cli" JSC_SKILL="" SKILL="" JSC_CHANGED_FILE="" \ + sh "$HOOKS/$_h" $_s 2>&1); _rc=$? if [ "$_rc" -eq 0 ]; then printf '[jsc] %s%s：exit 0，正常。\n' "$_h" "${_s:+ $_s}" >> "$smoke_out" elif [ "$_h" = sdlc-gate.sh ] && [ "$_s" = check ] && [ "$_rc" -eq 2 ]; then @@ -596,6 +643,15 @@ if [ "$action" = smoke ]; then # （見 hooks/lib.sh 開頭）——鎖存在且模型不符時就該擋下該輪提示。那是 hook 正常 # 工作，不是執行期錯誤；把它算成錯誤會讓每個正在上鎖的工作階段都誤報一次失敗。 printf '[jsc] %s check：exit 2，SDLC 階段鎖擋下該輪提示，屬設計行為，不算錯誤。\n' "$_h" >> "$smoke_out" + elif [ "$_h" = comment-scope.sh ] && [ "$_rc" -eq 2 ]; then + # 同一類放行：comment-scope.sh 掃描模式的 exit 2 是「掃到違規註解」的設計行為。 + # 無參數模式冒煙時取不到檔名，正常會走 exit 0；sweep 則看工作區乾不乾淨——工作區剛好 + # 有違規註解就回 2。那是 hook 正常工作，不是 hook 壞掉，不能因此判定接線失敗。 + printf '[jsc] %s%s：exit 2，掃到違規註解並發出警告，屬設計行為，不算錯誤。\n' "$_h" "${_s:+ $_s}" >> "$smoke_out" + elif [ "$_h" = lang-guard.sh ] && [ "$_rc" -eq 2 ]; then + # 沿用同一條例外：lang-guard.sh 掃描模式的 exit 2 是「掃到簡體字、亂碼或編碼問題」的 + # 設計行為。sweep 一樣看工作區乾不乾淨，髒工作區本來就會回 2，不是 hook 壞掉。 + printf '[jsc] %s%s：exit 2，掃到簡體字或亂碼並發出警告，屬設計行為，不算錯誤。\n' "$_h" "${_s:+ $_s}" >> "$smoke_out" else smoke_fails=$((smoke_fails + 1)) printf '[jsc] %s%s：exit %s，執行期出錯：%s\n' "$_h" "${_s:+ $_s}" "$_rc" \ @@ -612,9 +668,21 @@ if [ "$action" = smoke ]; then # wp-check skill 在取不到技能名時放行（上面已清空技能名），所以兩者都不需要白名單例外。 smoke_one sdlc-gate.sh "wp-check prompt" smoke_one sdlc-gate.sh "wp-check skill" + # comment-scope.sh 有三個接在不同事件的模式，三個都要驗：prompt 一律 exit 0， + # 無參數模式在取不到檔名時安靜 exit 0（上面已清空 JSC_CHANGED_FILE，stdin 也只有 {}）， + # sweep 掃目前工作目錄所在的 git 工作區——乾淨或非 git 目錄回 0，有違規註解回 2， + # 後者由上面的白名單放行（見 smoke_one）。 + smoke_one comment-scope.sh prompt + smoke_one comment-scope.sh + smoke_one comment-scope.sh sweep + # lang-guard.sh 同樣有三個接在不同事件的模式，三個都要驗，判定理由與 comment-scope.sh 相同： + # prompt 一律 exit 0，無參數模式取不到檔名時安靜 exit 0，sweep 在髒工作區回 2 由白名單放行。 + smoke_one lang-guard.sh prompt + smoke_one lang-guard.sh + smoke_one lang-guard.sh sweep if [ "$smoke_fails" -eq 0 ]; then - printf 'status=ok reason=%s\n' "五支 hook 的每個接線模式都跑得完，沒有執行期錯誤" + printf 'status=ok reason=%s\n' "七支 hook 的每個接線模式都跑得完，沒有執行期錯誤" cat "$smoke_out"; rm -f "$smoke_out"; exit 0 fi printf 'status=failed reason=%s\n' "$smoke_fails 支 hook 有執行期錯誤" @@ -644,6 +712,20 @@ if [ "$action" = status ]; then else st_item "$1" "$2" missing; fi } + # 註解範圍規則寫進規則檔了嗎。與 STE100 共用同一個標記段落，所以要單獨比對內容： + # 標記在、內容卻是舊版只有 STE100 的那一份時，這一項才看得出來缺了。$1=項目名 $2=檔案 + st_comment_scope() { + if [ -f "$2" ] && has_comment_scope "$2"; then st_item "$1" "$2" present + else st_item "$1" "$2" missing; fi + } + + # 繁中與編碼規則寫進規則檔了嗎。同樣與 STE100 共用標記段落，所以要單獨比對內容： + # 標記在、內容卻是舊版沒有這一段時，這一項才看得出來缺了。$1=項目名 $2=檔案 + st_lang_guard() { + if [ -f "$2" ] && has_lang_guard "$2"; then st_item "$1" "$2" present + else st_item "$1" "$2" missing; fi + } + # 別名段落只要任何一個既有 rc 檔帶有標記就算接上。$1=項目名 $2=標記名 st_rc_alias() { for _rc in "$HOME/.bashrc" "$HOME/.zshrc" "$HOME/.config/fish/config.fish"; do @@ -656,7 +738,15 @@ if [ "$action" = status ]; then case "$cli" in claude) if [ -f "$HOOKS/hooks.json" ]; then st_item hooks.json "$HOOKS/hooks.json" present - else st_item hooks.json "$HOOKS/hooks.json" missing; fi ;; + else st_item hooks.json "$HOOKS/hooks.json" missing; fi + # 七支 hook 全靠這一個檔宣告，只看檔案在不在會漏掉「檔在、某支沒接進去」。 + # 後來才加進來的 comment-scope.sh 與 lang-guard.sh 是最可能漏的兩支，所以各列一項。 + if [ -f "$HOOKS/hooks.json" ] && grep -qF 'comment-scope.sh' "$HOOKS/hooks.json" 2>/dev/null + then st_item comment-scope "$HOOKS/hooks.json" present + else st_item comment-scope "$HOOKS/hooks.json" missing; fi + if [ -f "$HOOKS/hooks.json" ] && grep -qF 'lang-guard.sh' "$HOOKS/hooks.json" 2>/dev/null + then st_item lang-guard "$HOOKS/hooks.json" present + else st_item lang-guard "$HOOKS/hooks.json" missing; fi ;; codex) config="${CODEX_HOME:-$HOME/.codex}/config.toml" @@ -667,19 +757,39 @@ if [ "$action" = status ]; then else st_item notify-root "$config" missing fi + # notify 接上了，不代表 sweep 也串進那一行：舊版接線只有計時，掃描是後來才加的 + if [ -f "$config" ] && grep -qF 'comment-scope.sh' "$config" 2>/dev/null && + grep -qF 'sweep' "$config" 2>/dev/null; then + st_item notify-sweep "$config" present + else + st_item notify-sweep "$config" missing + fi + # 兩支 sweep 各算一項：只驗其中一支會讓「舊版只接了註解範圍」看起來像接線完整 + if [ -f "$config" ] && grep -qF 'lang-guard.sh' "$config" 2>/dev/null && + grep -qF 'sweep' "$config" 2>/dev/null; then + st_item notify-lang-sweep "$config" present + else + st_item notify-lang-sweep "$config" missing + fi st_rc_alias alias jsc-hooks:codex st_block ste100 "${CODEX_HOME:-$HOME/.codex}/AGENTS.md" "" - st_degrade="STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查" ;; + st_comment_scope comment-scope "${CODEX_HOME:-$HOME/.codex}/AGENTS.md" + st_lang_guard lang-guard "${CODEX_HOME:-$HOME/.codex}/AGENTS.md" + st_degrade="STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查，註解範圍與繁中編碼改為每輪結束掃整個工作區，不是逐檔即時" ;; copilot) st_rc_alias alias jsc-hooks:copilot st_block ste100 "${JSC_COPILOT_INSTRUCTIONS:-$HOME/.config/copilot/copilot-instructions.md}" "" - st_degrade="STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查" ;; + st_comment_scope comment-scope "${JSC_COPILOT_INSTRUCTIONS:-$HOME/.config/copilot/copilot-instructions.md}" + st_lang_guard lang-guard "${JSC_COPILOT_INSTRUCTIONS:-$HOME/.config/copilot/copilot-instructions.md}" + st_degrade="STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查，註解範圍與繁中編碼只在工作階段結束時掃一次整個工作區" ;; antigravity) st_rc_alias alias jsc-hooks:antigravity st_block ste100 "${JSC_ANTIGRAVITY_RULES:-$HOME/.antigravity/AGENTS.md}" "" - st_degrade="STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查" ;; + st_comment_scope comment-scope "${JSC_ANTIGRAVITY_RULES:-$HOME/.antigravity/AGENTS.md}" + st_lang_guard lang-guard "${JSC_ANTIGRAVITY_RULES:-$HOME/.antigravity/AGENTS.md}" + st_degrade="STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查，註解範圍與繁中編碼只在工作階段結束時掃一次整個工作區" ;; kiro) # kiro 的 hook 檔綁在工作區，這裡看的一律是目前工作目錄底下那一份 @@ -687,7 +797,26 @@ if [ "$action" = status ]; then if [ -f "$_f" ] && json_top_key "$_f" run; then st_item "$(basename "$_f" .json)" "$_f" present else st_item "$(basename "$_f" .json)" "$_f" missing; fi done - st_degrade="SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查" ;; + # userPromptSubmit 那一筆的 run 串了好幾支腳本，只驗 JSON 讀得懂會漏掉少接的那一支。 + # comment-scope.sh 的 prompt 與 sweep 是兩件事，各算一項，才看得出舊版接線少了哪一個。 + if [ -f ./.kiro/hooks/jsc-hooks.json ] && + grep -qF 'comment-scope.sh\" prompt' ./.kiro/hooks/jsc-hooks.json 2>/dev/null + then st_item comment-scope ./.kiro/hooks/jsc-hooks.json present + else st_item comment-scope ./.kiro/hooks/jsc-hooks.json missing; fi + if [ -f ./.kiro/hooks/jsc-hooks.json ] && + grep -qF 'comment-scope.sh\" sweep' ./.kiro/hooks/jsc-hooks.json 2>/dev/null + then st_item comment-scope-sweep ./.kiro/hooks/jsc-hooks.json present + else st_item comment-scope-sweep ./.kiro/hooks/jsc-hooks.json missing; fi + # lang-guard.sh 的兩個模式同理各算一項 + if [ -f ./.kiro/hooks/jsc-hooks.json ] && + grep -qF 'lang-guard.sh\" prompt' ./.kiro/hooks/jsc-hooks.json 2>/dev/null + then st_item lang-guard ./.kiro/hooks/jsc-hooks.json present + else st_item lang-guard ./.kiro/hooks/jsc-hooks.json missing; fi + if [ -f ./.kiro/hooks/jsc-hooks.json ] && + grep -qF 'lang-guard.sh\" sweep' ./.kiro/hooks/jsc-hooks.json 2>/dev/null + then st_item lang-guard-sweep ./.kiro/hooks/jsc-hooks.json present + else st_item lang-guard-sweep ./.kiro/hooks/jsc-hooks.json missing; fi + st_degrade="SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查，註解範圍與繁中編碼改為每輪提示送出時掃整個工作區，不是逐檔即時" ;; esac if [ "$st_missing" -gt 0 ]; then @@ -698,7 +827,7 @@ if [ "$action" = status ]; then printf 'status=degraded reason=%s\n' "$st_degrade" cat "$st_items"; rm -f "$st_items"; exit 1 fi - printf 'status=wired reason=%s\n' "hooks.json 自動接線全部五支 hook" + printf 'status=wired reason=%s\n' "hooks.json 自動接線全部七支 hook" cat "$st_items"; rm -f "$st_items"; exit 0 fi @@ -707,8 +836,13 @@ case "$cli" in bin=$(cli_bin claude) command -v "$bin" >/dev/null 2>&1 || skip "未偵測到 claude 執行檔" [ -f "$HOOKS/hooks.json" ] || fail "找不到 $HOOKS/hooks.json，claude 接不到任何 hook" + grep -qF 'comment-scope.sh' "$HOOKS/hooks.json" 2>/dev/null \ + || fail "$HOOKS/hooks.json 沒有接上 comment-scope.sh，註解範圍檢查不會生效" + grep -qF 'lang-guard.sh' "$HOOKS/hooks.json" 2>/dev/null \ + || fail "$HOOKS/hooks.json 沒有接上 lang-guard.sh，繁中與編碼檢查不會生效" printf 'status=wired reason=%s\n' "hooks.json 自動接線" - echo "[jsc] claude：由 hooks/hooks.json 自動接線全部五支 hook，無需寫入設定。" + echo "[jsc] claude：由 hooks/hooks.json 自動接線全部七支 hook，無需寫入設定。" + echo "[jsc] claude：只有 claude 有 post-tool hook，comment-scope.sh 與 lang-guard.sh 的逐檔即時掃描只在這裡接得上；其他四個 CLI 改用 sweep 掃整個工作區，時機晚一輪或晚到工作階段結束。" exit 0 ;; codex) @@ -722,25 +856,37 @@ case "$cli" in # 一個 JSC_SESSION_ID，codex 內觸發的 notify 會沿用同一個 id。 # 2. notify 每輪先補 start 再 mark。start 已有紀錄就不動，所以沒走別名啟動時 # 仍拿得到起始時間（從第一輪算起）。少了這一段，worklog 只會拿到 0 秒。 + # notify 最後再掛 comment-scope.sh sweep：codex 沒有 post-tool hook，拿不到「剛剛寫了 + # 哪個檔」，只能改掃整個 git 工作區的 diff。每輪結束掃一次，時機比 claude 晚，那一輪 + # 寫過的檔一個都不會漏。 timer="sh '$HOOKS/session-timer.sh'" - notify_line="notify = [\"env\", \"JSC_CLI=codex\", \"sh\", \"-c\", \"$timer start /dev/null \ + || fail "$config 的 notify 沒有接到 comment-scope.sh sweep，codex 每輪結束不會掃註解範圍" + grep -qF "$lang sweep" "$config" 2>/dev/null \ + || fail "$config 的 notify 沒有接到 lang-guard.sh sweep，codex 每輪結束不會掃簡體字與亂碼" write_alias_rc "jsc-hooks:codex" "$alias_line" || fail "無法把 $bin 別名寫進 shell rc 檔" - replace_block "$agents" "" "" "$(ste100_text)" \ + replace_block "$agents" "" "" "$(rules_text)" \ || fail "無法寫入 $agents" has_block "$agents" "" || fail "$agents 寫入後讀不到 jsc-hooks 標記段落" - printf 'status=degraded reason=%s\n' "STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查" + has_comment_scope "$agents" || fail "$agents 寫入後讀不到註解範圍規則" + has_lang_guard "$agents" || fail "$agents 寫入後讀不到繁中與編碼規則" + printf 'status=degraded reason=%s\n' "STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查，註解範圍與繁中編碼改為每輪結束掃整個工作區，不是逐檔即時" echo "[jsc] codex：已在 shell rc 加上 $bin 別名，轉呼叫 tools/jsc-wrap.sh codex，啟動當下開始計時。" echo "[jsc] codex：別名要開新的 shell 或重新 source rc 檔才生效。" - echo "[jsc] codex：已設定 $config 的 notify（根層鍵，已驗證），每輪補 session-timer.sh start 再 mark。" - echo "[jsc] codex：已在 $agents 寫入 STE100 規則段落（prompt 降級）。" + echo "[jsc] codex：已設定 $config 的 notify（根層鍵，已驗證），每輪補 session-timer.sh start 再 mark，最後跑 comment-scope.sh sweep 與 lang-guard.sh sweep。" + echo "[jsc] codex：已在 $agents 寫入 STE100、註解範圍與繁中編碼規則段落（prompt 降級）。" echo "[jsc] codex：SDLC 模型鎖降級為技能步驟檢查，鎖檔仍由 sdlc-gate.sh lock 寫入。" echo "[jsc] codex：版本前置檢查接不上（codex 沒有 pre-tool hook），改由 /jsc-cli:deploy 定期更新。" + echo "[jsc] codex：註解範圍與繁中編碼除了規則提示，每輪結束會由 notify 各掃一次整個 git 工作區（codex 沒有 post-tool hook，接不到逐檔即時掃描），回饋比 claude 晚一輪。" exit 1 ;; copilot) @@ -749,15 +895,18 @@ case "$cli" in instr="${JSC_COPILOT_INSTRUCTIONS:-$HOME/.config/copilot/copilot-instructions.md}" alias_line="alias $bin='sh \"$HERE/jsc-wrap.sh\" copilot'" write_alias_rc "jsc-hooks:copilot" "$alias_line" || fail "無法把 $bin 別名寫進 shell rc 檔" - replace_block "$instr" "" "" "$(ste100_text)" \ + replace_block "$instr" "" "" "$(rules_text)" \ || fail "無法寫入 $instr" has_block "$instr" "" || fail "$instr 寫入後讀不到 jsc-hooks 標記段落" - printf 'status=degraded reason=%s\n' "STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查" + has_comment_scope "$instr" || fail "$instr 寫入後讀不到註解範圍規則" + has_lang_guard "$instr" || fail "$instr 寫入後讀不到繁中與編碼規則" + printf 'status=degraded reason=%s\n' "STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查，註解範圍與繁中編碼只在工作階段結束時掃一次整個工作區" echo "[jsc] copilot：已在 shell rc 加上 $bin 別名，轉呼叫 tools/jsc-wrap.sh copilot。" - echo "[jsc] copilot：已在 $instr 寫入 STE100 規則段落（prompt 降級）。" + echo "[jsc] copilot：已在 $instr 寫入 STE100、註解範圍與繁中編碼規則段落（prompt 降級）。" echo "[jsc] copilot：別名要開新的 shell 或重新 source rc 檔才生效。" echo "[jsc] copilot：SDLC 模型鎖降級為技能步驟檢查，鎖檔仍由 sdlc-gate.sh lock 寫入。" echo "[jsc] copilot：版本前置檢查接不上（copilot 沒有 pre-tool hook），改由 /jsc-cli:deploy 定期更新。" + echo "[jsc] copilot：註解範圍與繁中編碼除了規則提示，工作階段結束時由 jsc-wrap.sh 收尾各掃一次整個 git 工作區（copilot 連逐輪事件都沒有），回饋要等到離開 CLI 才看得到。" exit 1 ;; antigravity) @@ -766,15 +915,18 @@ case "$cli" in rules="${JSC_ANTIGRAVITY_RULES:-$HOME/.antigravity/AGENTS.md}" alias_line="alias $bin='sh \"$HERE/jsc-wrap.sh\" antigravity'" write_alias_rc "jsc-hooks:antigravity" "$alias_line" || fail "無法把 $bin 別名寫進 shell rc 檔" - replace_block "$rules" "" "" "$(ste100_text)" \ + replace_block "$rules" "" "" "$(rules_text)" \ || fail "無法寫入 $rules" has_block "$rules" "" || fail "$rules 寫入後讀不到 jsc-hooks 標記段落" - printf 'status=degraded reason=%s\n' "STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查" + has_comment_scope "$rules" || fail "$rules 寫入後讀不到註解範圍規則" + has_lang_guard "$rules" || fail "$rules 寫入後讀不到繁中與編碼規則" + printf 'status=degraded reason=%s\n' "STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查，註解範圍與繁中編碼只在工作階段結束時掃一次整個工作區" echo "[jsc] antigravity：已在 shell rc 加上 $bin 別名，轉呼叫 tools/jsc-wrap.sh antigravity。" - echo "[jsc] antigravity：已在 $rules 寫入 STE100 規則段落（prompt 降級）。" + echo "[jsc] antigravity：已在 $rules 寫入 STE100、註解範圍與繁中編碼規則段落（prompt 降級）。" echo "[jsc] antigravity：別名要開新的 shell 或重新 source rc 檔才生效。" echo "[jsc] antigravity：SDLC 模型鎖降級為技能步驟檢查，鎖檔仍由 sdlc-gate.sh lock 寫入。" echo "[jsc] antigravity：版本前置檢查接不上（antigravity 沒有 pre-tool hook），改由 /jsc-cli:deploy 定期更新。" + echo "[jsc] antigravity：註解範圍與繁中編碼除了規則提示，工作階段結束時由 jsc-wrap.sh 收尾各掃一次整個 git 工作區（antigravity 連逐輪事件都沒有），回饋要等到離開 CLI 才看得到。" exit 1 ;; kiro) @@ -795,13 +947,16 @@ case "$cli" in "run": "sh \\"$HOOKS/session-timer.sh\\" restart "$hookfile" 2>/dev/null </dev/null || fail "$startfile 沒有接在 sessionStart" grep -qF '"userPromptSubmit"' "$hookfile" 2>/dev/null || fail "$hookfile 沒有接在 userPromptSubmit" - printf 'status=degraded reason=%s\n' "SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查" + grep -qF 'comment-scope.sh' "$hookfile" 2>/dev/null || fail "$hookfile 的 run 沒有接到 comment-scope.sh" + # 兩個模式接的是兩件事，只驗腳本名會漏掉少接的那一個，所以各驗一次 + grep -qF 'comment-scope.sh\" prompt' "$hookfile" 2>/dev/null \ + || fail "$hookfile 的 run 沒有接到 comment-scope.sh prompt，每輪不會注入註解範圍規則" + grep -qF 'comment-scope.sh\" sweep' "$hookfile" 2>/dev/null \ + || fail "$hookfile 的 run 沒有接到 comment-scope.sh sweep，kiro 每輪不會掃註解範圍" + grep -qF 'lang-guard.sh' "$hookfile" 2>/dev/null || fail "$hookfile 的 run 沒有接到 lang-guard.sh" + grep -qF 'lang-guard.sh\" prompt' "$hookfile" 2>/dev/null \ + || fail "$hookfile 的 run 沒有接到 lang-guard.sh prompt，每輪不會注入繁中與編碼規則" + grep -qF 'lang-guard.sh\" sweep' "$hookfile" 2>/dev/null \ + || fail "$hookfile 的 run 沒有接到 lang-guard.sh sweep，kiro 每輪不會掃簡體字與亂碼" + printf 'status=degraded reason=%s\n' "SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查，註解範圍與繁中編碼改為每輪提示送出時掃整個工作區，不是逐檔即時" echo "[jsc] kiro：已建立 $startfile（sessionStart 開始計時）與 $hookfile（JSC_CLI=kiro），兩份都已驗證。" echo "[jsc] kiro：SDLC 模型鎖降級為技能步驟檢查，鎖檔仍由 sdlc-gate.sh lock 寫入。" echo "[jsc] kiro：版本前置檢查接不上（kiro 沒有 pre-tool hook），改由 /jsc-cli:deploy 定期更新。" + echo "[jsc] kiro：註解範圍與繁中編碼除了規則提示，每輪提示送出時會各掃一次整個 git 工作區（kiro 沒有 post-tool hook），掃到的是上一輪寫的檔。" exit 1 ;; esac