feat/comment-scope-sweep-all-clis #27

2026-08-27T01:21:23Z

jiantw83 commented

2026-08-27 01:21:23 +00:00

摘要

需求描述：讓「程式碼註解禁止夾帶文件相關資訊」在五支 CLI 都掃得到。前一支 PR 只接得上 claude 的 PostToolUse，codex、copilot、antigravity、kiro 拿不到「剛剛寫了哪個檔」，違規註解只能靠模型自律。本 PR 新增 sweep 模式，改掃整個 git 工作區這次改過的檔案，再依各 CLI 實際有的事件接上。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
`hooks/comment-scope.sh`	新增 `sweep [dir]` 模式：從任一子目錄找到 git 庫根，掃 `git diff HEAD` 改過的每個檔案。找不到 git 就安靜 exit 0。判定邏輯抽成 `scan_file` 函式，樣式與白名單一字未動
`tools/wire-cli.sh`	codex 的 `notify` 串上 sweep（每輪結束）；kiro 的 `userPromptSubmit` 串上 sweep（掃上一輪寫的）；兩者各加寫入後驗證；`smoke` 多跑一輪 sweep 並把 exit 2 例外放寬到所有掃描模式；`status` 新增 codex 的 `notify-sweep` 與 kiro 的 `comment-scope-sweep` 盤點項
`tools/jsc-wrap.sh`	CLI 結束後、回傳結束碼之前跑一次 sweep，補上 copilot 與 antigravity 唯一可用的時機
`skills/hooks-install/SKILL.md`	覆蓋範圍改成逐 CLI 表格，據實寫明各自的掃描時機
`README.md`、`AGENTS.md`	同步三種模式與五支 CLI 的掃描時機
三份 manifest	0.1.9 已發佈，本次新功能要能被 `version-guard.sh` 判定落後，升到 0.2.0

設計重點

掃描時機依各 CLI 實際有的事件配，不假裝五支一樣：claude 每次寫檔逐檔精準（PostToolUse）；codex 每輪結束掃工作區（config.toml 的 notify）；kiro 每輪提示送出時掃上一輪寫的（userPromptSubmit）；copilot 與 antigravity 只有工作階段結束時掃一次（jsc-wrap.sh 收尾）。時機不同、涵蓋不同，文件一律照實寫。
包裝器絕不吃掉 CLI 的結束碼：jsc-wrap.sh 先接住 CLI 的結束碼，sweep 以 || true 執行，最後回傳原本那個碼。sweep 命中只把警告印到 stderr。已實測驗證，不是讀程式碼推論。
冒煙測試不會因為工作區剛好有違規就判定 hook 壞掉：sweep 在髒工作區回 exit 2 是設計行為，比照 sdlc-gate.sh check 列入例外。
前置關係：本存取庫的 hook 與 jsc-review 的規則正文都已合併進各自的 develop。plugins/git 另有一支 PR 在 jsc-git:commit 加上提交前 sweep，補上五支 CLI 共用的最後一道網；那支只呼叫本腳本，腳本不在時安靜跳過，沒有合併順序相依。

測試結果

sh -n hooks/comment-scope.sh、sh -n tools/wire-cli.sh、sh -n tools/jsc-wrap.sh 皆 exit 0。
sh tools/wire-cli.sh smoke claude 回報 status=ok，六支 hook 的十個接線模式全部 exit 0（含 comment-scope.sh sweep）。
髒工作區跑 smoke copilot：status=ok，sweep 的 exit 2 被認定為設計行為，不算執行期錯誤。
暫存 git 庫實測：違規版 sweep exit 2 並列出命中行；還原成合規後 exit 0；從子目錄執行找得到庫根；非 git 目錄 exit 0。
結束碼保護實測：假 CLI exit 42 搭配必定命中的違規工作區，包裝器回傳 42 不是 2；假 CLI exit 0 時包裝器回傳 0。
誤判回歸：對 36 支既有 jsc shell 腳本重跑，命中數維持 2 支，與重構前相同，且兩支都是文件裡的示例字串。
生成設定實測（沙箱 HOME 與 CODEX_HOME，未動使用者本人設定）：codex 的 notify 含 sweep 且落在根層，status codex 三項皆 present；kiro 的 jsc-hooks.json 的 run 尾端含 sweep，status kiro 兩項皆 present。

前置 Push Request

無

## 摘要 - 需求描述：讓「程式碼註解禁止夾帶文件相關資訊」在五支 CLI 都掃得到。前一支 PR 只接得上 claude 的 PostToolUse，codex、copilot、antigravity、kiro 拿不到「剛剛寫了哪個檔」，違規註解只能靠模型自律。本 PR 新增 `sweep` 模式，改掃整個 git 工作區這次改過的檔案，再依各 CLI 實際有的事件接上。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `hooks/comment-scope.sh` | 新增 `sweep [dir]` 模式：從任一子目錄找到 git 庫根，掃 `git diff HEAD` 改過的每個檔案。找不到 git 就安靜 exit 0。判定邏輯抽成 `scan_file` 函式，樣式與白名單一字未動 | | `tools/wire-cli.sh` | codex 的 `notify` 串上 sweep（每輪結束）；kiro 的 `userPromptSubmit` 串上 sweep（掃上一輪寫的）；兩者各加寫入後驗證；`smoke` 多跑一輪 sweep 並把 exit 2 例外放寬到所有掃描模式；`status` 新增 codex 的 `notify-sweep` 與 kiro 的 `comment-scope-sweep` 盤點項 | | `tools/jsc-wrap.sh` | CLI 結束後、回傳結束碼之前跑一次 sweep，補上 copilot 與 antigravity 唯一可用的時機 | | `skills/hooks-install/SKILL.md` | 覆蓋範圍改成逐 CLI 表格，據實寫明各自的掃描時機 | | `README.md`、`AGENTS.md` | 同步三種模式與五支 CLI 的掃描時機 | | 三份 manifest | 0.1.9 已發佈，本次新功能要能被 `version-guard.sh` 判定落後，升到 0.2.0 | ## 設計重點 - **掃描時機依各 CLI 實際有的事件配，不假裝五支一樣**：claude 每次寫檔逐檔精準（PostToolUse）；codex 每輪結束掃工作區（config.toml 的 notify）；kiro 每輪提示送出時掃上一輪寫的（userPromptSubmit）；copilot 與 antigravity 只有工作階段結束時掃一次（jsc-wrap.sh 收尾）。時機不同、涵蓋不同，文件一律照實寫。 - **包裝器絕不吃掉 CLI 的結束碼**：`jsc-wrap.sh` 先接住 CLI 的結束碼，sweep 以 `|| true` 執行，最後回傳原本那個碼。sweep 命中只把警告印到 stderr。已實測驗證，不是讀程式碼推論。 - **冒煙測試不會因為工作區剛好有違規就判定 hook 壞掉**：sweep 在髒工作區回 exit 2 是設計行為，比照 `sdlc-gate.sh check` 列入例外。 - 前置關係：本存取庫的 hook 與 `jsc-review` 的規則正文都已合併進各自的 develop。`plugins/git` 另有一支 PR 在 `jsc-git:commit` 加上提交前 sweep，補上五支 CLI 共用的最後一道網；那支只呼叫本腳本，腳本不在時安靜跳過，沒有合併順序相依。 ## 測試結果 - `sh -n hooks/comment-scope.sh`、`sh -n tools/wire-cli.sh`、`sh -n tools/jsc-wrap.sh` 皆 exit 0。 - `sh tools/wire-cli.sh smoke claude` 回報 `status=ok`，六支 hook 的十個接線模式全部 exit 0（含 `comment-scope.sh sweep`）。 - 髒工作區跑 `smoke copilot`：`status=ok`，sweep 的 exit 2 被認定為設計行為，不算執行期錯誤。 - 暫存 git 庫實測：違規版 sweep exit 2 並列出命中行；還原成合規後 exit 0；從子目錄執行找得到庫根；非 git 目錄 exit 0。 - **結束碼保護實測**：假 CLI `exit 42` 搭配必定命中的違規工作區，包裝器回傳 42 不是 2；假 CLI `exit 0` 時包裝器回傳 0。 - 誤判回歸：對 36 支既有 jsc shell 腳本重跑，命中數維持 2 支，與重構前相同，且兩支都是文件裡的示例字串。 - 生成設定實測（沙箱 `HOME` 與 `CODEX_HOME`，未動使用者本人設定）：codex 的 `notify` 含 sweep 且落在根層，`status codex` 三項皆 present；kiro 的 `jsc-hooks.json` 的 `run` 尾端含 sweep，`status kiro` 兩項皆 present。 ## 前置 Push Request - 無

jiantw83 added 4 commits 2026-08-27 01:21:24 +00:00

feat(comment-scope): 新增 sweep 模式，掃整個 git 工作區 8ede74e9e2

What：`hooks/comment-scope.sh` 由兩種模式變三種，新增 `sweep [dir]`：掃整個 git 工作區這次改過的所有檔案，命中就把報告與最多三行證據送到 stderr 並 exit 2，找不到 git 就安靜 exit 0。`prompt` 與無參數單檔掃描兩個模式的判定邏輯一行不動。

Why：只有 claude 有 PostToolUse，拿得到「剛剛寫了哪個檔」。codex、copilot、antigravity、kiro 四個 CLI 都沒有 post-tool 事件，註解範圍檢查在那邊只剩規則提示，違規註解寫進去了不會有人叫。改掃整個工作區的 git diff，時機晚一點，涵蓋範圍一樣。

How：單檔判定抽成 `scan_file()`，兩種掃描模式共用同一份禁止樣式與白名單，不會各自漂移。`sweep` 以 `git rev-parse --show-toplevel` 找庫根，所以在子目錄跑也掃得到整個庫；逐檔報告累積在暫存檔再一次輸出，因為迴圈跑在管線的子行程裡，變數帶不回本 shell。

Who：`jsc-hooks` 的 hook 實作層，供 `tools/wire-cli.sh` 接線給 codex、copilot、antigravity、kiro 四個 CLI 使用。

feat(wire-cli): 把 comment-scope sweep 接到其餘四個 CLI 0bebdef46f

What：`tools/wire-cli.sh` 把 `comment-scope.sh sweep` 接進 codex 的 `config.toml` 根層 `notify` 與 kiro 的 `.kiro/hooks/jsc-hooks.json` 的 `userPromptSubmit`；`tools/jsc-wrap.sh` 在 CLI 結束後、回傳結束碼之前跑一次 sweep，涵蓋 copilot、antigravity 與同樣走包裝器的 codex。`smoke` 多跑一輪 sweep，`status` 多盤點 codex 的 `notify-sweep` 與 kiro 的 `comment-scope-sweep` 兩項。

Why：這四個 CLI 沒有 post-tool hook，接不到逐檔即時掃描，先前只寫得進規則提示，違規註解寫進去沒有人叫。接上 sweep 之後五個 CLI 都掃得到，差別只剩回饋速度。`smoke` 與 `status` 不同步補上，就驗不出來接線少了哪一支。

How：codex 的 notify 串成 `start; mark; sweep`，位置仍由 `replace_block_toml` 保證落在第一個表頭之前，寫入後除了既有的根層鍵檢查，再 grep 一次確認 sweep 真的串進那一行。kiro 的 `run` 尾端接上 sweep，`prompt` 與 `sweep` 各驗一個 grep，只驗腳本名會漏掉少接的那一個。`jsc-wrap.sh` 的 sweep 加 `|| true` 接住 exit 2，包裝器一律原樣回傳 CLI 自己的結束碼——包裝器改掉結束碼，呼叫端的 `cmd && next` 就會誤判。`smoke` 的 exit 2 白名單由「無參數模式」放寬到「所有掃描模式」，因為 sweep 在髒工作區本來就會回 2，那是 hook 正常工作，不是 hook 壞掉。四個 CLI 的 `reason` 與 `[jsc]` 說明改寫成各自真正的掃描時機。

Who：`jsc-hooks` 的接線工具層，供 `jsc-hooks:hooks-install` 與 `jsc-hooks:repair` 呼叫，最終服務 codex、copilot、antigravity、kiro 的使用者。

docs(hooks-install): 據實寫明各 CLI 的註解範圍掃描時機 b23c546079

What：`skills/hooks-install/SKILL.md`、`README.md`、`AGENTS.md` 三份文件一併改寫註解範圍的覆蓋範圍說明：`comment-scope.sh` 由兩種模式改為三種，並以表格列出五個 CLI 各自的掃描時機——claude 逐檔即時（PostToolUse）、codex 每輪結束（`notify`）、kiro 每輪提示送出時（`userPromptSubmit`，掃的是上一輪寫的檔）、copilot 與 antigravity 只有工作階段結束時由 `tools/jsc-wrap.sh` 收尾掃一次。README 的 `tools/jsc-wrap.sh` 那列補上收尾 sweep 與「不影響結束碼」的約定，`smoke` 例外說明改成掃描模式通用。

Why：舊文件寫的是「四個 CLI 只剩規則提示」，接上 sweep 之後那句話已經不實。但也不能倒過來寫成五支一樣：時機差一輪或差一整個工作階段，操作者要知道自己現在用的 CLI 什麼時候才會收到警告。文件不同步，操作者會對保護程度有錯誤預期。

How：SKILL.md 全份維持英文，正文改用一張 CLI 對掃描時機的表格，並註明 sweep 讀的是 `git diff HEAD`、涵蓋範圍與 claude 相同、不在 git 工作區內就安靜 exit 0，frontmatter 的 `description` 不動；README.md 維持 STE100 繁中，hook 一覽表那列補上三種模式與各 CLI 時機，原本的降級段落換成同一張表；AGENTS.md 的第 5 條補上三種模式與「不得寫成五支一樣」的要求。

Who：`jsc-hooks` 的文件層與 `hooks-install` 技能，供操作者與後續 sub agent 依循。

feat(manifest): 三份 manifest 版本升到 0.2.0 542f0aab2c

What：把 plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json 三份
manifest 的版本由 0.1.9 升到 0.2.0。

Why：0.1.9 已隨前一支 PR 發佈出去，本次新增的 sweep 模式與四支 CLI 的接線
沒有跟著升版，version-guard.sh 就看不出本機落後，使用者不會收到更新提示。

How：以 jsc-meta 的 sync-skill-manifest.sh 統一 bump，minor 進位、patch 歸零，
三份同步成同一個值。

Who：註解範圍檢查 hook 的跨 CLI 支援。

admin merged commit 2f74d6473c into develop

2026-08-27 01:28:49 +00:00

admin deleted branch feat/comment-scope-sweep-all-clis

2026-08-27 01:28:49 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: plugins/hooks#27