feat/comment-scope-hook #26

2026-08-26T11:02:19Z

jiantw83 commented

2026-08-26 11:02:19 +00:00

摘要

需求描述：新增第六支 hook comment-scope.sh，強制「程式碼註解禁止夾帶文件相關資訊」。prompt 模式在每次提示注入規則摘要；無參數模式在寫檔後掃描剛寫入的檔案，命中就把警告送到 stderr 並以 exit 2 交回模型自行修正，不擋寫入。規則正文的唯一來源在 jsc-review 的 references/comment-scope.md，本存取庫不留副本。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
`hooks/comment-scope.sh`	新檔。兩種模式的判定實作：`prompt` 印規則摘要供 UserPromptSubmit 注入；無參數從 stdin JSON 的 `file_path`（或 `JSC_CHANGED_FILE`）取檔名，只掃 `git diff` 的新增行，命中就印警告並 exit 2。markdown 與二進位檔跳過，逃生門 `JSC_COMMENT_SCOPE=off`
`hooks/hooks.json`	claude 的接線：UserPromptSubmit 加一筆 `prompt` 模式，PostToolUse 新增 `Write\|Edit\|MultiEdit` 區塊接掃描模式
`tools/wire-cli.sh`	新增 `comment_scope_text()`、`rules_text()`、`has_comment_scope()`；codex、copilot、antigravity 的規則檔與 kiro 的 hook JSON 都接上 `prompt` 模式；`smoke` 與 `status` 補上這支 hook；全腳本五支改六支
`skills/hooks-install/SKILL.md`	`description` 與正文同步六支 hook，寫明兩種模式、冒煙測試的 exit 2 例外，以及四個 CLI 的降級實情
`README.md`	hook 表格新增一列，接線工具那列改寫 `smoke` 的例外說明，環境變數表補 `JSC_COMMENT_SCOPE` 與 `JSC_CHANGED_FILE`，另加一段講明覆蓋範圍差異
`AGENTS.md`	新增一條規則：註解範圍規則正文的唯一來源在 `jsc-review`，本存取庫只放判定實作、不留規則清單副本
`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`	三份 manifest 版本由 0.1.8 升到 0.1.9，讓版本前置檢查與 `jsc-cli:deploy` 看得出本機落後

設計重點

覆蓋範圍要據實看待：只有 claude 有 post-tool hook，接得到寫檔後的自動掃描。codex、copilot、antigravity、kiro 都沒有 post-tool hook，只接得到 UserPromptSubmit 的規則提示，寫進去的違規註解不會有人叫，要靠 /jsc-review:code-review 事後抓。
未做的部分也一併講明：這四個 CLI 的實際接線寫入沒有實機跑過，只做了語法檢查與程式碼審視。
掃描不擋寫入。檔案已經寫好了才掃，exit 2 的用意是把警告交回模型就地修正，不是回退寫入。
只掃 git diff 的新增行，不翻舊帳。既有檔案的舊註解不會被翻出來，避免每改一次就跳一次無關的警告。
只實作判得出來的樣式。專案代號、客戶名稱這類靠樣式判不出來的項目不硬做，交給 /jsc-review:code-review 第 2 組處理。
規則正文不複製。接線腳本要用規則文字時，一律取 comment-scope.sh prompt 的實際輸出，避免兩份規則各自漂移。
本存取庫另有一支 PR 尚未合併（version-guard 豁免修正與 .gitignore 忽略 .kiro/）。兩者檔案不重疊、沒有相依，合併順序不拘。

測試結果

sh -n hooks/comment-scope.sh 與 sh -n tools/wire-cli.sh 皆 exit 0。
hooks/hooks.json 通過 JSON 解析。
sh tools/wire-cli.sh smoke claude 回報 status=ok，六支 hook 的九個接線模式全部 exit 0。
sh tools/wire-cli.sh status claude 回報 status=wired，comment-scope 項目為 present。
違規樣本檔命中並 exit 2；白名單樣本檔（日期、RFC、CVE、SPDX、@deprecated、github issue 連結）exit 0。
對 36 支既有 jsc shell 腳本回歸測試，只有 2 支命中，且都是文件裡的示例字串。
未測：codex、copilot、antigravity、kiro 的實際接線寫入沒有實機執行，只做語法檢查與程式碼審視。

前置 Push Request

無

## 摘要 - 需求描述：新增第六支 hook `comment-scope.sh`，強制「程式碼註解禁止夾帶文件相關資訊」。`prompt` 模式在每次提示注入規則摘要；無參數模式在寫檔後掃描剛寫入的檔案，命中就把警告送到 stderr 並以 exit 2 交回模型自行修正，不擋寫入。規則正文的唯一來源在 `jsc-review` 的 `references/comment-scope.md`，本存取庫不留副本。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `hooks/comment-scope.sh` | 新檔。兩種模式的判定實作：`prompt` 印規則摘要供 UserPromptSubmit 注入；無參數從 stdin JSON 的 `file_path`（或 `JSC_CHANGED_FILE`）取檔名，只掃 `git diff` 的新增行，命中就印警告並 exit 2。markdown 與二進位檔跳過，逃生門 `JSC_COMMENT_SCOPE=off` | | `hooks/hooks.json` | claude 的接線：UserPromptSubmit 加一筆 `prompt` 模式，PostToolUse 新增 `Write\|Edit\|MultiEdit` 區塊接掃描模式 | | `tools/wire-cli.sh` | 新增 `comment_scope_text()`、`rules_text()`、`has_comment_scope()`；codex、copilot、antigravity 的規則檔與 kiro 的 hook JSON 都接上 `prompt` 模式；`smoke` 與 `status` 補上這支 hook；全腳本五支改六支 | | `skills/hooks-install/SKILL.md` | `description` 與正文同步六支 hook，寫明兩種模式、冒煙測試的 exit 2 例外，以及四個 CLI 的降級實情 | | `README.md` | hook 表格新增一列，接線工具那列改寫 `smoke` 的例外說明，環境變數表補 `JSC_COMMENT_SCOPE` 與 `JSC_CHANGED_FILE`，另加一段講明覆蓋範圍差異 | | `AGENTS.md` | 新增一條規則：註解範圍規則正文的唯一來源在 `jsc-review`，本存取庫只放判定實作、不留規則清單副本 | | `plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` | 三份 manifest 版本由 0.1.8 升到 0.1.9，讓版本前置檢查與 `jsc-cli:deploy` 看得出本機落後 | ## 設計重點 - 覆蓋範圍要據實看待：只有 claude 有 post-tool hook，接得到寫檔後的自動掃描。codex、copilot、antigravity、kiro 都沒有 post-tool hook，只接得到 UserPromptSubmit 的規則提示，寫進去的違規註解不會有人叫，要靠 `/jsc-review:code-review` 事後抓。 - 未做的部分也一併講明：這四個 CLI 的實際接線寫入沒有實機跑過，只做了語法檢查與程式碼審視。 - 掃描不擋寫入。檔案已經寫好了才掃，exit 2 的用意是把警告交回模型就地修正，不是回退寫入。 - 只掃 `git diff` 的新增行，不翻舊帳。既有檔案的舊註解不會被翻出來，避免每改一次就跳一次無關的警告。 - 只實作判得出來的樣式。專案代號、客戶名稱這類靠樣式判不出來的項目不硬做，交給 `/jsc-review:code-review` 第 2 組處理。 - 規則正文不複製。接線腳本要用規則文字時，一律取 `comment-scope.sh prompt` 的實際輸出，避免兩份規則各自漂移。 - 本存取庫另有一支 PR 尚未合併（version-guard 豁免修正與 `.gitignore` 忽略 `.kiro/`）。兩者檔案不重疊、沒有相依，合併順序不拘。 ## 測試結果 - `sh -n hooks/comment-scope.sh` 與 `sh -n tools/wire-cli.sh` 皆 exit 0。 - `hooks/hooks.json` 通過 JSON 解析。 - `sh tools/wire-cli.sh smoke claude` 回報 `status=ok`，六支 hook 的九個接線模式全部 exit 0。 - `sh tools/wire-cli.sh status claude` 回報 `status=wired`，`comment-scope` 項目為 present。 - 違規樣本檔命中並 exit 2；白名單樣本檔（日期、RFC、CVE、SPDX、`@deprecated`、github issue 連結）exit 0。 - 對 36 支既有 jsc shell 腳本回歸測試，只有 2 支命中，且都是文件裡的示例字串。 - 未測：codex、copilot、antigravity、kiro 的實際接線寫入沒有實機執行，只做語法檢查與程式碼審視。 ## 前置 Push Request - 無

jiantw83 added 4 commits 2026-08-26 11:02:20 +00:00

feat(comment-scope): 新增註解範圍檢查 hook 並接進 claude 的 hooks.json f81ceaf145

What：新增第六支 hook `hooks/comment-scope.sh`，並在 `hooks/hooks.json` 補上兩個接線點：UserPromptSubmit 走 `prompt` 模式、PostToolUse 的 `Write|Edit|MultiEdit` 走掃描模式。

Why：程式碼註解常被寫進工單編號、專案代號、負責人這類文件相關資訊，讓註解變成過期文件。過去只能靠 `/jsc-review:code-review` 事後抓，回饋太慢；把規則搬到寫檔當下，模型可以立刻修正。

How：`prompt` 模式印出規則摘要注入提示。無參數模式從 stdin JSON 取 `file_path`（或環境變數 `JSC_CHANGED_FILE`），只掃 `git diff HEAD` 的新增行，不翻舊帳；markdown、純文字、資料檔與二進位檔一律跳過。命中就把警告與最多三行證據送到 stderr 並以 exit 2 交回模型就地修正，不擋寫入。逃生門為 `JSC_COMMENT_SCOPE=off`。規則正文的唯一來源在 `jsc-review` 的 `references/comment-scope.md`，本存取庫不留副本。

Who：`jsc-hooks` 的 hook 層，服務 `jsc-hooks:hooks-install` 的接線流程與 `jsc-review:code-review` 的註解契約檢查。

feat(wire-cli): 接線腳本納入註解範圍 hook，五支改六支 e2232d26f1

What：`tools/wire-cli.sh` 新增 `comment_scope_text()`、`rules_text()` 與 `has_comment_scope()` 三個函式，把 `comment-scope.sh` 的 `prompt` 模式接進 codex、copilot、antigravity 的規則檔與 kiro 的 hook JSON，`smoke` 與 `status` 兩個子命令也補上這支 hook，全腳本由五支 hook 改口徑為六支。

Why：`hooks/hooks.json` 只服務 claude；其他四個 CLI 要靠這支腳本接線，不改就完全接不到新規則。`smoke` 與 `status` 不同步補上，接線成功與否也驗不出來。

How：`comment_scope_text()` 直接取 `comment-scope.sh prompt` 的實際輸出當規則文字，不在本存取庫留規則清單副本；`rules_text()` 把 STE100 與註解範圍併進同一個 `<!-- jsc-hooks -->` 標記段落，重跑等同先移除再重裝；`has_comment_scope()` 供 `status` 判斷標記段落在不在。`smoke` 把 `comment-scope.sh` 無參數模式的 exit 2 視為設計行為，與 `sdlc-gate.sh check` 同列例外。

Who：`jsc-hooks` 的接線工具層，供 `jsc-hooks:hooks-install` 與 `jsc-hooks:repair` 呼叫。

feat(hooks-install): 文件同步六支 hook 與降級說明 5d60e0f231

What：`skills/hooks-install/SKILL.md`、`README.md`、`AGENTS.md` 三份文件一併改口徑為六支 hook，補上 `comment-scope.sh` 的職責、兩種模式、環境變數 `JSC_COMMENT_SCOPE` 與 `JSC_CHANGED_FILE`，以及各 CLI 的覆蓋範圍差異。

Why：文件停在五支會誤導操作者，讓人以為每個 CLI 都受同等保護。實際上只有 claude 有 post-tool hook，其他四個 CLI 只接得到規則提示，這個落差必須據實寫明。

How：SKILL.md 的 `description` 與正文加上 comment scope scanner，並註明 exit 2 在冒煙測試裡算健康；README.md 的 hook 表格新增一列，接線工具那列改寫 `smoke` 的例外說明，環境變數表補兩列，另加一段講明四個 CLI 的降級實情；AGENTS.md 新增一條規則，寫明規則正文的唯一來源在 `jsc-review`，本存取庫不留副本。

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

feat(manifest): 三份 manifest 版本升到 0.1.9 7690b697c7

What：`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` 三份 manifest 的 `version` 由 0.1.8 升到 0.1.9。

Why：本次新增了第六支 hook，屬於功能增修。版本不升，`version-guard.sh` 的版本前置檢查與 `jsc-cli:deploy` 的更新判斷都看不出本機落後，使用者不會收到更新提示。

How：三份檔案同步改同一個版本號，維持三份 manifest 版本一致的既有慣例。

Who：`jsc-hooks` 的發佈中繼資料，供 `hooks/version-guard.sh` 與 `jsc-cli:deploy` 比對版本。

admin merged commit 8f98e42171 into develop

2026-08-27 00:56:46 +00:00

admin deleted branch feat/comment-scope-hook

2026-08-27 00:56:46 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: plugins/hooks#26