From 8ede74e9e2253fd7a98934650b8dba71bf8f2ff6 Mon Sep 17 00:00:00 2001
From: Jeffery <jiantw83@yahoo.com>
Date: Thu, 27 Aug 2026 09:15:56 +0800
Subject: [PATCH 1/4] =?UTF-8?q?feat(comment-scope):=20=E6=96=B0=E5=A2=9E?=
 =?UTF-8?q?=20sweep=20=E6=A8=A1=E5=BC=8F=EF=BC=8C=E6=8E=83=E6=95=B4?=
 =?UTF-8?q?=E5=80=8B=20git=20=E5=B7=A5=E4=BD=9C=E5=8D=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 使用。
---
 hooks/comment-scope.sh | 166 ++++++++++++++++++++++++++---------------
 1 file changed, 106 insertions(+), 60 deletions(-)

diff --git a/hooks/comment-scope.sh b/hooks/comment-scope.sh
index 061b16c..d00d749 100755
--- a/hooks/comment-scope.sh
+++ b/hooks/comment-scope.sh
@@ -4,8 +4,13 @@
 # 專案代號、客戶名稱這類無法用樣式判定的，交給 jsc-review:code-review 第 2 組人工審查。
 #
 # 用法:
-#   comment-scope.sh prompt   # UserPromptSubmit：注入規則摘要
-#   comment-scope.sh          # PostToolUse：掃描剛寫入的檔案，命中就發警告
+#   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。
@@ -13,7 +18,7 @@
 #   兩者都取不到就安靜降級（exit 0）。
 #
 # 掃描範圍：檔案在 git 工作區內就只掃 `git diff HEAD` 的新增行，不翻舊帳；
-#   不在 git 內或檔案尚未追蹤才整檔掃描。
+#   不在 git 內或檔案尚未追蹤才整檔掃描。sweep 一律只看 git diff。
 #
 # 結束碼：0=沒命中或資料不足；2=命中，訊息走 stderr 交回模型自行修正（不擋寫入，檔案已經寫好了）。
 # 逃生門：JSC_COMMENT_SCOPE=off。
@@ -29,43 +34,6 @@ if [ "${1:-}" = "prompt" ]; then
   exit 0
 fi
 
-read_stdin 2>/dev/null || STDIN_JSON=""
-file=$(json_str file_path 2>/dev/null || true)
-[ -n "$file" ] || file="${JSC_CHANGED_FILE:-}"
-[ -n "$file" ] && [ -f "$file" ] || exit 0
-
-# 非程式碼檔不受本規則限制：markdown、純文字、資料檔沒有「程式碼註解」。
-case "$file" in
-  *.md|*.markdown|*.txt|*.rst|*.json|*.csv|*.tsv|*.svg|*.lock|*.log|*COMMIT_EDITMSG) exit 0 ;;
-esac
-# 二進位檔跳過。只認 NUL 位元組——拿「非可列印字元」當判準會把所有含中文的檔案誤判成二進位。
-raw=$(head -c 1024 "$file" 2>/dev/null | wc -c)
-txt=$(head -c 1024 "$file" 2>/dev/null | LC_ALL=C tr -d '\000' | wc -c)
-[ "$raw" = "$txt" ] || exit 0
-
-dir=$(dirname -- "$file")
-if git -C "$dir" rev-parse --is-inside-work-tree >/dev/null 2>&1 &&
-   git -C "$dir" ls-files --error-unmatch -- "$file" >/dev/null 2>&1; then
-  lines=$(git -C "$dir" diff HEAD -- "$file" 2>/dev/null | sed -n 's/^+[^+]/&/p' | cut -c2-)
-  [ -n "$lines" ] || exit 0
-else
-  lines=$(cat "$file" 2>/dev/null)
-fi
-
-# 只留註解行：行首註解符號，或行中出現 // 與 # 的行尾註解。
-comments=$(printf '%s\n' "$lines" | grep -E '^[[:space:]]*(//|#|--|\*|/\*|<!--|;|%)|[[:space:]](//|#)[[:space:]]' || true)
-[ -n "$comments" ] || exit 0
-
-# 白名單先剪掉，再比對禁止樣式。剪掉而不是整行放行——同一行可能一半合規、一半違規。
-cleaned=$(printf '%s\n' "$comments" | sed -E \
-  -e 's#SPDX-License-Identifier:[^[:space:]]*##g' \
-  -e 's#CVE-[0-9]{4}-[0-9]+##g' \
-  -e 's#(RFC|ISO|IEEE|ANSI|ECMA|UTF|SHA|MD|AES|RSA|HMAC|PBKDF|TLS|SSL|HTTP|BIG|EUC|JIS|GB|RS|IPV|X)-?[0-9]+(-[0-9]+)?##g' \
-  -e 's#@(deprecated|since|param|returns?|throws|type|typedef|example|see|link|inheritdoc|override|nullable|internal)##g' \
-  -e 's#https?://(github|gitlab|bitbucket)\.com/[^[:space:]]*##g' \
-  -e 's#https?://[^[:space:]]*[{<][^[:space:]]*##g' \
-  -e 's#[0-9]{4}[-/][0-9]{1,2}[-/][0-9]{1,2}##g')
-
 hit() { # $1=樣式 $2=說明；命中就把說明與最多三行證據印到 stdout
   m=$(printf '%s\n' "$cleaned" | grep -nE "$1" | head -n 3)
   [ -n "$m" ] || return 0
@@ -73,30 +41,108 @@ hit() { # $1=樣式 $2=說明；命中就把說明與最多三行證據印到 st
   printf '%s\n' "$m" | sed 's/^/    /'
 }
 
-out=$(
-  hit '(^|[^[:alnum:]_/])#[0-9]+'                                             '議題編號（#123）'
-  hit '(^|[^[:alnum:]_])![0-9]+'                                              'PR、MR 編號（!45）'
-  hit '[A-Z]{2,6}-[0-9]{1,6}'                                                 '工作包、故事、驗收、測試案例、變更單、議題編號（前綴加流水號）'
-  hit '(QUESTION|PLAN|ANALYZE|DELIVER|MAINTAIN|REPO|LOG|LEARN|ERROR|CHECK|REPORT)_([A-Z0-9]{8}|CONTENTS)' 'jsc wiki 頁面編號'
-  hit '(todo|TODO|待辦)[[:space:]]*#?[0-9]+'                                  'TDD 待辦編號'
-  hit '([Ss]print|里程碑|[Mm]ilestone)[[:space:]]*[0-9]+'                     'Sprint、里程碑編號'
-  hit '(^|[^[:alnum:].])v[0-9]+\.[0-9]+|版本[[:space:]]*v?[0-9]+\.[0-9]+'     '版本號'
-  hit '(commit|提交|hash|SHA)[[:space:]:]*[0-9a-f]{7,40}'                     'commit hash'
-  hit '(branch|分支)[[:space:]:]*[a-z]+/[a-z0-9-]+'                           '分支名稱'
-  hit '(^|[[:space:]])@[a-zA-Z][a-zA-Z0-9_.-]{2,}'                            '人名、認領者、@ 提及（含 @author）'
-  hit 'https?://[^[:space:]]*(wiki|confluence|atlassian|notion\.so|docs\.google|sharepoint)' 'wiki 或外部文件連結'
-  hit 'https?://[^[:space:]]*/(issues|pulls)/[0-9]+'                          '內部議題、PR 連結'
-  hit '([Gg]enerated (with|by)|Co-Authored-By|本檔(案)?由|AI (產生|生成|撰寫))'  '產生來源署名'
-  hit '預估[[:space:]]*[0-9]+[[:space:]]*(小時|分鐘|人日|人天|天)|[0-9]+[[:space:]]*(人日|人天|工時)' '工時估算'
-  hit '(規格書|需求書|準則|規範|清單|guidelines)[^。]{0,8}第[[:space:]]*[0-9]+|(規格書|需求書|SRS)[^。]{0,6}[0-9]+(\.[0-9]+)+' '規格文件章節、稽核檢查項編號'
-)
+scan_file() { # $1=檔案路徑；命中就把報告印到 stdout 並回傳 1，沒命中回傳 0
+  f=$1
+  [ -f "$f" ] || return 0
 
-[ -n "$out" ] || exit 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
 
-{
-  printf '[jsc] 程式碼註解夾帶了文件相關資訊，請就地修正：%s\n' "$file"
+  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:]]*(//|#|--|\*|/\*|<!--|;|%)|[[:space:]](//|#)[[:space:]]' || true)
+  [ -n "$comments" ] || return 0
+
+  # 白名單先剪掉，再比對禁止樣式。剪掉而不是整行放行——同一行可能一半合規、一半違規。
+  cleaned=$(printf '%s\n' "$comments" | sed -E \
+    -e 's#SPDX-License-Identifier:[^[:space:]]*##g' \
+    -e 's#CVE-[0-9]{4}-[0-9]+##g' \
+    -e 's#(RFC|ISO|IEEE|ANSI|ECMA|UTF|SHA|MD|AES|RSA|HMAC|PBKDF|TLS|SSL|HTTP|BIG|EUC|JIS|GB|RS|IPV|X)-?[0-9]+(-[0-9]+)?##g' \
+    -e 's#@(deprecated|since|param|returns?|throws|type|typedef|example|see|link|inheritdoc|override|nullable|internal)##g' \
+    -e 's#https?://(github|gitlab|bitbucket)\.com/[^[:space:]]*##g' \
+    -e 's#https?://[^[:space:]]*[{<][^[:space:]]*##g' \
+    -e 's#[0-9]{4}[-/][0-9]{1,2}[-/][0-9]{1,2}##g')
+
+  out=$(
+    hit '(^|[^[:alnum:]_/])#[0-9]+'                                             '議題編號（#123）'
+    hit '(^|[^[:alnum:]_])![0-9]+'                                              'PR、MR 編號（!45）'
+    hit '[A-Z]{2,6}-[0-9]{1,6}'                                                 '工作包、故事、驗收、測試案例、變更單、議題編號（前綴加流水號）'
+    hit '(QUESTION|PLAN|ANALYZE|DELIVER|MAINTAIN|REPO|LOG|LEARN|ERROR|CHECK|REPORT)_([A-Z0-9]{8}|CONTENTS)' 'jsc wiki 頁面編號'
+    hit '(todo|TODO|待辦)[[:space:]]*#?[0-9]+'                                  'TDD 待辦編號'
+    hit '([Ss]print|里程碑|[Mm]ilestone)[[:space:]]*[0-9]+'                     'Sprint、里程碑編號'
+    hit '(^|[^[:alnum:].])v[0-9]+\.[0-9]+|版本[[:space:]]*v?[0-9]+\.[0-9]+'     '版本號'
+    hit '(commit|提交|hash|SHA)[[:space:]:]*[0-9a-f]{7,40}'                     'commit hash'
+    hit '(branch|分支)[[:space:]:]*[a-z]+/[a-z0-9-]+'                           '分支名稱'
+    hit '(^|[[:space:]])@[a-zA-Z][a-zA-Z0-9_.-]{2,}'                            '人名、認領者、@ 提及（含 @author）'
+    hit 'https?://[^[:space:]]*(wiki|confluence|atlassian|notion\.so|docs\.google|sharepoint)' 'wiki 或外部文件連結'
+    hit 'https?://[^[:space:]]*/(issues|pulls)/[0-9]+'                          '內部議題、PR 連結'
+    hit '([Gg]enerated (with|by)|Co-Authored-By|本檔(案)?由|AI (產生|生成|撰寫))'  '產生來源署名'
+    hit '預估[[:space:]]*[0-9]+[[:space:]]*(小時|分鐘|人日|人天|天)|[0-9]+[[:space:]]*(人日|人天|工時)' '工時估算'
+    hit '(規格書|需求書|準則|規範|清單|guidelines)[^。]{0,8}第[[:space:]]*[0-9]+|(規格書|需求書|SRS)[^。]{0,6}[0-9]+(\.[0-9]+)+' '規格文件章節、稽核檢查項編號'
+  )
+
+  [ -n "$out" ] || return 0
+  printf '%s\n' "$f"
   printf '%s\n' "$out"
+  return 1
+}
+
+advice() {
   printf '  修法：把編號指向的內容搬進註解，然後刪掉編號。搬不動就代表那件事不該用註解表達。\n'
   printf '  規則正文與白名單見 jsc-review 的 references/comment-scope.md。誤判時用 JSC_COMMENT_SCOPE=off 關閉。\n'
+}
+
+if [ "${1:-}" = "sweep" ]; then
+  target=${2:-.}
+  [ -d "$target" ] || exit 0
+  root=$(git -C "$target" rev-parse --show-toplevel 2>/dev/null) || exit 0
+  [ -n "$root" ] || exit 0
+  changed=$(git -C "$root" diff --name-only HEAD 2>/dev/null)
+  [ -n "$changed" ] || exit 0
+
+  # 報告累積在暫存檔：迴圈跑在管線的子行程裡，變數帶不回來。
+  tmp=${TMPDIR:-/tmp}/jsc-comment-scope.$$
+  : > "$tmp" 2>/dev/null || exit 0
+  printf '%s\n' "$changed" | while IFS= read -r rel; do
+    [ -n "$rel" ] || continue
+    scan_file "$root/$rel" >> "$tmp" 2>/dev/null
+  done
+  if [ -s "$tmp" ]; then
+    {
+      printf '[jsc] 工作區有註解夾帶文件相關資訊，請就地修正：\n'
+      sed 's/^/  /' "$tmp"
+      advice
+    } >&2
+    rm -f "$tmp"
+    exit 2
+  fi
+  rm -f "$tmp"
+  exit 0
+fi
+
+read_stdin 2>/dev/null || STDIN_JSON=""
+file=$(json_str file_path 2>/dev/null || true)
+[ -n "$file" ] || file="${JSC_CHANGED_FILE:-}"
+[ -n "$file" ] || exit 0
+
+report=$(scan_file "$file") && exit 0
+{
+  printf '[jsc] 程式碼註解夾帶了文件相關資訊，請就地修正：\n'
+  printf '%s\n' "$report"
+  advice
 } >&2
 exit 2
-- 
2.53.0


From 0bebdef46f211ca6123c47d77ec88d73b28303f8 Mon Sep 17 00:00:00 2001
From: Jeffery <jiantw83@yahoo.com>
Date: Thu, 27 Aug 2026 09:16:15 +0800
Subject: [PATCH 2/4] =?UTF-8?q?feat(wire-cli):=20=E6=8A=8A=20comment-scope?=
 =?UTF-8?q?=20sweep=20=E6=8E=A5=E5=88=B0=E5=85=B6=E9=A4=98=E5=9B=9B?=
 =?UTF-8?q?=E5=80=8B=20CLI?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 的使用者。
---
 tools/jsc-wrap.sh |   9 +++-
 tools/wire-cli.sh | 116 ++++++++++++++++++++++++++++++----------------
 2 files changed, 85 insertions(+), 40 deletions(-)

diff --git a/tools/jsc-wrap.sh b/tools/jsc-wrap.sh
index cc3adf6..74290a9 100755
--- a/tools/jsc-wrap.sh
+++ b/tools/jsc-wrap.sh
@@ -2,7 +2,8 @@
 # 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
+#       掃一次整個工作區的註解範圍，最後回傳 CLI 的結束碼。
 # 注意: JSC_CLI 存的是 CLI 代號（antigravity、kiro），實際執行的是 cli_bin 對應的
 #       執行檔（agy、kiro-cli）。直接拿代號當指令跑會 127，因為沒有這兩個執行檔。
 HERE=$(cd "$(dirname "$0")" && pwd)
@@ -25,4 +26,10 @@ rc=$?
 # 收尾：補記結束時間，並從原生日誌回填技能用量
 sh "$HOOKS/session-timer.sh" mark </dev/null
 sh "$HERE/scan-logs.sh" --cli "$cli" --session "$JSC_SESSION_ID" </dev/null || true
+# 註解範圍收尾掃描：copilot 與 antigravity 連逐輪事件都沒有，整個工作階段只有這裡掃得到。
+# 掃的是啟動當下的工作目錄，也就是使用者跑 CLI 的那個 git 工作區。
+# `|| true` 不可省：sweep 掃到違規會 exit 2，接住它才不會蓋掉底下要回傳的 CLI 結束碼。
+# 警告只走 sweep 自己的 stderr，包裝器一律原樣回傳 $rc——包裝器改掉結束碼，呼叫端的
+# `cmd && next` 就會誤判，註解檢查不該有這種副作用。
+sh "$HOOKS/comment-scope.sh" sweep </dev/null || true
 exit "$rc"
diff --git a/tools/wire-cli.sh b/tools/wire-cli.sh
index b136293..2bb64a8 100755
--- a/tools/wire-cli.sh
+++ b/tools/wire-cli.sh
@@ -15,29 +15,37 @@
 #
 # 接線行為（依 CLI 而定，皆為冪等：重跑只取代既有的 jsc-hooks 標記段落，不會重複疊加）：
 #   claude       — 什麼都不用寫，hooks.json 已自動接線六支 hook
-#   codex        — 在 shell rc 檔加上 codex 別名，轉呼叫 tools/jsc-wrap.sh codex（開始計時）；
-#                  在 config.toml 設 notify（每輪補 session-timer.sh start 再 mark，JSC_CLI=codex）；
-#                  在 AGENTS.md 附加 STE100 與註解範圍規則段落（prompt 降級）
-#   copilot      — 在 shell rc 檔加上 copilot 別名，轉呼叫 tools/jsc-wrap.sh copilot；
-#                  在 copilot-instructions.md 附加 STE100 與註解範圍規則段落
-#   antigravity  — 在 shell rc 檔加上 agy 別名，轉呼叫 tools/jsc-wrap.sh antigravity；
-#                  在全域規則檔附加 STE100 與註解範圍規則段落
+#   codex        — 在 shell rc 檔加上 codex 別名，轉呼叫 tools/jsc-wrap.sh codex（開始計時，
+#                  結束時收尾掃一次註解範圍）；在 config.toml 設 notify（每輪補
+#                  session-timer.sh start 再 mark，最後 comment-scope.sh sweep 掃整個工作區，
+#                  JSC_CLI=codex）；在 AGENTS.md 附加 STE100 與註解範圍規則段落（prompt 降級）
+#   copilot      — 在 shell rc 檔加上 copilot 別名，轉呼叫 tools/jsc-wrap.sh copilot（結束時
+#                  收尾掃一次註解範圍）；在 copilot-instructions.md 附加 STE100 與註解範圍規則段落
+#   antigravity  — 在 shell rc 檔加上 agy 別名，轉呼叫 tools/jsc-wrap.sh antigravity（同樣收尾
+#                  掃一次）；在全域規則檔附加 STE100 與註解範圍規則段落
 #   kiro         — 在工作區 .kiro/hooks/ 下建立 jsc-hooks.json（每輪 mark 加 STE100
-#                  與註解範圍規則）與 jsc-hooks-session-start.json（sessionStart 開始計時），
-#                  皆帶 JSC_CLI=kiro
+#                  與註解範圍規則，再 comment-scope.sh sweep 掃整個工作區）與
+#                  jsc-hooks-session-start.json（sessionStart 開始計時），皆帶 JSC_CLI=kiro
 #
 # 覆蓋範圍要據實回報，不得暗示每個 CLI 都有保護：
 #   claude                          六支 hook 全接，回報 wired
-#   codex、copilot、antigravity、kiro 只有別名或規則檔，接不上 PreToolUse、PostToolUse 與
-#                                   UserPromptSubmit，版本前置檢查與 SDLC 模型鎖
-#                                   都沒接上，一律回報 degraded 並在 reason 講明。
-#                                   註解範圍檢查在這四個 CLI 只剩規則提示：沒有 post-tool
-#                                   hook，寫檔後的自動掃描接不上，違規註解只能靠模型自律
+#   codex、copilot、antigravity、kiro 只有別名、notify 或規則檔，接不上 PreToolUse、PostToolUse
+#                                   與 UserPromptSubmit，版本前置檢查與 SDLC 模型鎖都沒接上，
+#                                   一律回報 degraded 並在 reason 講明
+#
+# 註解範圍掃描每個 CLI 的時機都不同，回報時不得寫成五支一樣：
+#   claude                掛在 PostToolUse，寫完哪個檔就掃哪個，逐檔即時
+#   codex                 掛在每輪結束的 notify，掃整個 git 工作區這輪改過的檔（sweep）
+#   kiro                  掛在 userPromptSubmit，掃整個 git 工作區，掃到的是上一輪寫的檔
+#   copilot、antigravity  沒有任何逐輪事件，只有工作階段結束時由 jsc-wrap.sh 收尾掃一次
+# 時機晚一點、涵蓋範圍一樣：sweep 看的是 git diff，那一輪寫過的檔一個都不會漏。真正的差別
+# 在回饋速度——claude 當下就叫，其他四個要等到該輪或該階段結束。
 #   所有 jsc 標記段落都採整段重寫，重跑等同先移除舊內容再重裝
 #
 # 寫入後自我驗證，通過才回報成功：每個寫過的檔案重新讀一次，確認標記段落存在且落在
 # 正確位置（codex 的 notify 必須是根層鍵，不能被歸進前一張表；kiro 的 JSON 必須成對
-# 且 on、run 在最上層）。腳本說寫好了卻寫錯位置，是最難查的失敗，所以驗證放在腳本裡。
+# 且 on、run 在最上層），內容也要涵蓋這次該接上的每一支腳本（含 comment-scope.sh sweep）。
+# 腳本說寫好了卻寫錯位置或少接一支，是最難查的失敗，所以驗證放在腳本裡。
 #
 # 輸出: 第一行固定為 `status=... reason=...`（可供程式判讀），其後為人類可讀的繁中說明。
 # 結束碼（接線）: 0=wired（已完整接線） 1=degraded（降級為 prompt／技能步驟檢查）
@@ -619,10 +627,11 @@ if [ "$action" = smoke ]; then
       # （見 hooks/lib.sh 開頭）——鎖存在且模型不符時就該擋下該輪提示。那是 hook 正常
       # 工作，不是執行期錯誤；把它算成錯誤會讓每個正在上鎖的工作階段都誤報一次失敗。
       printf '[jsc] %s check：exit 2，SDLC 階段鎖擋下該輪提示，屬設計行為，不算錯誤。\n' "$_h" >> "$smoke_out"
-    elif [ "$_h" = comment-scope.sh ] && [ -z "$_s" ] && [ "$_rc" -eq 2 ]; then
-      # 同一類放行：comment-scope.sh 無參數模式的 exit 2 是「掃到違規註解」的設計行為。
-      # 冒煙時取不到檔名，正常會走 exit 0；真的走到 exit 2 也代表腳本判定跑完了，不是出錯。
-      printf '[jsc] %s：exit 2，掃到違規註解並發出警告，屬設計行為，不算錯誤。\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"
     else
       smoke_fails=$((smoke_fails + 1))
       printf '[jsc] %s%s：exit %s，執行期出錯：%s\n' "$_h" "${_s:+ $_s}" "$_rc" \
@@ -639,10 +648,13 @@ 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 也只有 {}）。
+  # 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
 
   if [ "$smoke_fails" -eq 0 ]; then
     printf 'status=ok reason=%s\n' "六支 hook 的每個接線模式都跑得完，沒有執行期錯誤"
@@ -710,22 +722,29 @@ 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
       st_rc_alias alias jsc-hooks:codex
       st_block ste100 "${CODEX_HOME:-$HOME/.codex}/AGENTS.md" "<!-- jsc-hooks -->"
       st_comment_scope comment-scope "${CODEX_HOME:-$HOME/.codex}/AGENTS.md"
-      st_degrade="STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查，註解範圍只剩規則提示、無 post-tool hook 可接寫檔後掃描" ;;
+      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}" "<!-- jsc-hooks -->"
       st_comment_scope comment-scope "${JSC_COPILOT_INSTRUCTIONS:-$HOME/.config/copilot/copilot-instructions.md}"
-      st_degrade="STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查，註解範圍只剩規則提示、無 post-tool hook 可接寫檔後掃描" ;;
+      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}" "<!-- jsc-hooks -->"
       st_comment_scope comment-scope "${JSC_ANTIGRAVITY_RULES:-$HOME/.antigravity/AGENTS.md}"
-      st_degrade="STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查，註解範圍只剩規則提示、無 post-tool hook 可接寫檔後掃描" ;;
+      st_degrade="STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查，註解範圍只在工作階段結束時掃一次整個工作區" ;;
 
     kiro)
       # kiro 的 hook 檔綁在工作區，這裡看的一律是目前工作目錄底下那一份
@@ -733,12 +752,17 @@ 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
-      # userPromptSubmit 那一筆的 run 串了兩支腳本，只驗 JSON 讀得懂會漏掉少接的那一支
+      # userPromptSubmit 那一筆的 run 串了好幾支腳本，只驗 JSON 讀得懂會漏掉少接的那一支。
+      # comment-scope.sh 的 prompt 與 sweep 是兩件事，各算一項，才看得出舊版接線少了哪一個。
       if [ -f ./.kiro/hooks/jsc-hooks.json ] &&
-         grep -qF 'comment-scope.sh' ./.kiro/hooks/jsc-hooks.json 2>/dev/null
+         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
-      st_degrade="SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查，註解範圍只剩規則提示、無 post-tool hook 可接寫檔後掃描" ;;
+      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
+      st_degrade="SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查，註解範圍改為每輪提示送出時掃整個工作區，不是逐檔即時" ;;
   esac
 
   if [ "$st_missing" -gt 0 ]; then
@@ -762,7 +786,7 @@ case "$cli" in
       || fail "$HOOKS/hooks.json 沒有接上 comment-scope.sh，註解範圍檢查不會生效"
     printf 'status=wired reason=%s\n' "hooks.json 自動接線"
     echo "[jsc] claude：由 hooks/hooks.json 自動接線全部六支 hook，無需寫入設定。"
-    echo "[jsc] claude：只有 claude 有 post-tool hook，comment-scope.sh 的寫檔後自動掃描只在這裡接得上。"
+    echo "[jsc] claude：只有 claude 有 post-tool hook，comment-scope.sh 的逐檔即時掃描只在這裡接得上；其他四個 CLI 改用 sweep 掃整個工作區，時機晚一輪或晚到工作階段結束。"
     exit 0 ;;
 
   codex)
@@ -776,27 +800,33 @@ 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; $timer mark </dev/null\"]"
+    scope="sh '$HOOKS/comment-scope.sh'"
+    notify_line="notify = [\"env\", \"JSC_CLI=codex\", \"sh\", \"-c\", \"$timer start </dev/null; $timer mark </dev/null; $scope sweep </dev/null\"]"
     alias_line="alias $bin='sh \"$HERE/jsc-wrap.sh\" codex'"
     replace_block_toml "$config" "# jsc-hooks" "# /jsc-hooks" "$notify_line" \
       || fail "無法寫入 $config"
     has_block "$config" "# jsc-hooks" || fail "$config 寫入後讀不到 jsc-hooks 標記段落"
     toml_root_key "$config" notify \
       || fail "$config 的 notify 沒有落在根層（被歸進某張表，codex 讀不到，hook 會靜靜失效）"
+    grep -qF "$scope sweep" "$config" 2>/dev/null \
+      || fail "$config 的 notify 沒有接到 comment-scope.sh sweep，codex 每輪結束不會掃註解範圍"
     write_alias_rc "jsc-hooks:codex" "$alias_line" || fail "無法把 $bin 別名寫進 shell rc 檔"
     replace_block "$agents" "<!-- jsc-hooks -->" "<!-- /jsc-hooks -->" "$(rules_text)" \
       || fail "無法寫入 $agents"
     has_block "$agents" "<!-- jsc-hooks -->" || fail "$agents 寫入後讀不到 jsc-hooks 標記段落"
     has_comment_scope "$agents" || fail "$agents 寫入後讀不到註解範圍規則"
-    printf 'status=degraded reason=%s\n' "STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查，註解範圍只剩規則提示、無 post-tool hook 可接寫檔後掃描"
+    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：已設定 $config 的 notify（根層鍵，已驗證），每輪補 session-timer.sh start 再 mark，最後跑 comment-scope.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：註解範圍檢查只接得到規則提示（codex 沒有 post-tool hook），寫檔後的自動掃描接不上，違規註解要靠 /jsc-review:code-review 補。"
+    echo "[jsc] codex：註解範圍除了規則提示，每輪結束會由 notify 掃一次整個 git 工作區（codex 沒有 post-tool hook，接不到逐檔即時掃描），回饋比 claude 晚一輪。"
     exit 1 ;;
 
   copilot)
@@ -809,13 +839,13 @@ case "$cli" in
       || fail "無法寫入 $instr"
     has_block "$instr" "<!-- jsc-hooks -->" || fail "$instr 寫入後讀不到 jsc-hooks 標記段落"
     has_comment_scope "$instr" || fail "$instr 寫入後讀不到註解範圍規則"
-    printf 'status=degraded reason=%s\n' "STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查，註解範圍只剩規則提示、無 post-tool hook 可接寫檔後掃描"
+    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：別名要開新的 shell 或重新 source rc 檔才生效。"
     echo "[jsc] copilot：SDLC 模型鎖降級為技能步驟檢查，鎖檔仍由 sdlc-gate.sh lock 寫入。"
     echo "[jsc] copilot：版本前置檢查接不上（copilot 沒有 pre-tool hook），改由 /jsc-cli:deploy 定期更新。"
-    echo "[jsc] copilot：註解範圍檢查只接得到規則提示（copilot 沒有 post-tool hook），寫檔後的自動掃描接不上，違規註解要靠 /jsc-review:code-review 補。"
+    echo "[jsc] copilot：註解範圍除了規則提示，工作階段結束時由 jsc-wrap.sh 收尾掃一次整個 git 工作區（copilot 連逐輪事件都沒有），回饋要等到離開 CLI 才看得到。"
     exit 1 ;;
 
   antigravity)
@@ -828,13 +858,13 @@ case "$cli" in
       || fail "無法寫入 $rules"
     has_block "$rules" "<!-- jsc-hooks -->" || fail "$rules 寫入後讀不到 jsc-hooks 標記段落"
     has_comment_scope "$rules" || fail "$rules 寫入後讀不到註解範圍規則"
-    printf 'status=degraded reason=%s\n' "STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查，註解範圍只剩規則提示、無 post-tool hook 可接寫檔後掃描"
+    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：別名要開新的 shell 或重新 source rc 檔才生效。"
     echo "[jsc] antigravity：SDLC 模型鎖降級為技能步驟檢查，鎖檔仍由 sdlc-gate.sh lock 寫入。"
     echo "[jsc] antigravity：版本前置檢查接不上（antigravity 沒有 pre-tool hook），改由 /jsc-cli:deploy 定期更新。"
-    echo "[jsc] antigravity：註解範圍檢查只接得到規則提示（antigravity 沒有 post-tool hook），寫檔後的自動掃描接不上，違規註解要靠 /jsc-review:code-review 補。"
+    echo "[jsc] antigravity：註解範圍除了規則提示，工作階段結束時由 jsc-wrap.sh 收尾掃一次整個 git 工作區（antigravity 連逐輪事件都沒有），回饋要等到離開 CLI 才看得到。"
     exit 1 ;;
 
   kiro)
@@ -855,13 +885,16 @@ case "$cli" in
   "run": "sh \\"$HOOKS/session-timer.sh\\" restart </dev/null"
 }
 EOF
+    # userPromptSubmit 那一輪的 run 最後再掛 comment-scope.sh sweep：kiro 沒有 post-tool hook，
+    # 拿不到「剛剛寫了哪個檔」，只能改掃整個 git 工作區的 diff。掃到的是上一輪寫的檔——
+    # 提示送出時，上一輪的寫入早就落地了，時機合理。
     cat > "$hookfile" 2>/dev/null <<EOF || fail "無法寫入 $hookfile"
 {
   "name": "jsc-hooks",
   "description": "jsc session timer + STE100 guard + comment scope bridge (auto-generated by jsc-hooks:hooks-install, do not edit by hand)",
   "on": ["sessionEnd", "userPromptSubmit"],
   "env": { "JSC_CLI": "kiro" },
-  "run": "sh \\"$HOOKS/session-timer.sh\\" mark </dev/null; sh \\"$HOOKS/ste100-guard.sh\\" </dev/null; sh \\"$HOOKS/comment-scope.sh\\" prompt </dev/null"
+  "run": "sh \\"$HOOKS/session-timer.sh\\" mark </dev/null; sh \\"$HOOKS/ste100-guard.sh\\" </dev/null; sh \\"$HOOKS/comment-scope.sh\\" prompt </dev/null; sh \\"$HOOKS/comment-scope.sh\\" sweep </dev/null"
 }
 EOF
     for f in "$startfile" "$hookfile"; do
@@ -873,10 +906,15 @@ EOF
     grep -qF '"sessionStart"' "$startfile" 2>/dev/null || fail "$startfile 沒有接在 sessionStart"
     grep -qF '"userPromptSubmit"' "$hookfile" 2>/dev/null || fail "$hookfile 沒有接在 userPromptSubmit"
     grep -qF 'comment-scope.sh' "$hookfile" 2>/dev/null || fail "$hookfile 的 run 沒有接到 comment-scope.sh"
-    printf 'status=degraded reason=%s\n' "SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查，註解範圍只剩規則提示、無 post-tool hook 可接寫檔後掃描"
+    # 兩個模式接的是兩件事，只驗腳本名會漏掉少接的那一個，所以各驗一次
+    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 每輪不會掃註解範圍"
+    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：註解範圍檢查只接得到規則提示（kiro 沒有 post-tool hook），寫檔後的自動掃描接不上，違規註解要靠 /jsc-review:code-review 補。"
+    echo "[jsc] kiro：註解範圍除了規則提示，每輪提示送出時會掃一次整個 git 工作區（kiro 沒有 post-tool hook），掃到的是上一輪寫的檔。"
     exit 1 ;;
 esac
-- 
2.53.0


From b23c54607987d1d733ac6c0f552c39fa1a078019 Mon Sep 17 00:00:00 2001
From: Jeffery <jiantw83@yahoo.com>
Date: Thu, 27 Aug 2026 09:16:32 +0800
Subject: [PATCH 3/4] =?UTF-8?q?docs(hooks-install):=20=E6=93=9A=E5=AF=A6?=
 =?UTF-8?q?=E5=AF=AB=E6=98=8E=E5=90=84=20CLI=20=E7=9A=84=E8=A8=BB=E8=A7=A3?=
 =?UTF-8?q?=E7=AF=84=E5=9C=8D=E6=8E=83=E6=8F=8F=E6=99=82=E6=A9=9F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 依循。
---
 AGENTS.md                     |  2 +-
 README.md                     | 21 +++++++++++++++------
 skills/hooks-install/SKILL.md | 17 ++++++++++++++---
 3 files changed, 30 insertions(+), 10 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 0e8bbc8..f0beeb2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,7 +8,7 @@
 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. 註解範圍規則正文的唯一來源：`jsc-review` 的 `references/comment-scope.md`。本存取庫只放 `hooks/comment-scope.sh` 的判定實作，不留規則清單副本，接線腳本要用規則文字時一律取腳本的實際輸出。
+5. 註解範圍規則正文的唯一來源：`jsc-review` 的 `references/comment-scope.md`。本存取庫只放 `hooks/comment-scope.sh` 的判定實作，不留規則清單副本，接線腳本要用規則文字時一律取腳本的實際輸出。`comment-scope.sh` 有 `prompt`、無參數逐檔掃描、`sweep` 掃整個 git 工作區三種模式；掃描時機每個 CLI 都不同（claude 逐檔即時、codex 每輪結束、kiro 每輪提示送出時、copilot 與 antigravity 只有工作階段結束時），談覆蓋範圍時一律據實分開講，不得寫成五支一樣。
 6. 主 agent 不需要處理細節的流程，一律建立 sub agent 處理。
 
 ## 呼叫慣例
diff --git a/README.md b/README.md
index 72b9941..15dbf12 100644
--- a/README.md
+++ b/README.md
@@ -26,14 +26,23 @@ 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) | 程式碼註解不得夾帶文件相關資訊：`prompt` 在每次提示注入規則摘要（禁止項與白名單各一行）；無參數為寫檔後掃描，從 stdin JSON 取 `file_path`（或環境變數 `JSC_CHANGED_FILE`），只掃 `git diff HEAD` 的新增行、不翻舊帳，命中就把警告與最多三行證據送到 stderr 並以 exit 2 交回模型就地修正（不擋寫入，檔案已經寫好了）。markdown、純文字、資料檔與二進位檔一律跳過。只實作可用樣式判定的項目，專案代號、客戶名稱這類判不出來的交給 `/jsc-review:code-review`。規則正文的唯一來源在 `jsc-review` 的 `references/comment-scope.md`，本存取庫不留副本。逃生門 `JSC_COMMENT_SCOPE=off` |
+| `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/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 同時有 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` 同樣分兩級：這四個 CLI 也沒有 post-tool hook，只接得到 `prompt` 模式的規則提示（寫進各自的規則檔，與 STE100 同一個標記段落），寫檔後的自動掃描接不上。也就是說在 codex、copilot、antigravity、kiro 上，違規註解只有規則提示擋一層，寫進去了不會有人叫，要靠 `/jsc-review:code-review` 第 2 組事後抓。只有 claude 兩級都有。
+> `comment-scope.sh` 五個 CLI 都掃得到，但時機不同，不能當成五支一樣：
+
+| CLI | 掃描時機 | 接在哪裡 |
+| --- | --- | --- |
+| claude | 逐檔即時，寫完哪個檔就掃哪個 | PostToolUse |
+| codex | 每輪結束，掃整個 git 工作區 | `config.toml` 的根層 `notify` |
+| kiro | 每輪提示送出時，掃整個 git 工作區（掃到的是上一輪寫的檔） | `.kiro/hooks/jsc-hooks.json` 的 `userPromptSubmit` |
+| copilot、antigravity | 工作階段結束時掃一次 | `tools/jsc-wrap.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 {落後個數}`。
@@ -46,10 +55,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` 掃整個 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 -->`（或 `# 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` 無參數模式的 exit 2 是掃到違規註解的設計行為），以 `status=ok\|failed` 回報。`status {cli}` 是唯讀盤點：只讀設定檔判斷標記段落在不在，不寫檔也不執行 hook，每個接線點印一行 `item<TAB>{項目}<TAB>{路徑}<TAB>{present\|missing}`，以 `status=wired\|degraded\|unwired\|skipped` 回報（結束碼 0、1、5、3）。體檢類技能（`/jsc-cli:doctor`）只能用這個子命令，另外三個都會動到環境 |
+| `tools/wire-cli.sh` | 單一 CLI 的 hook 生命週期，共三個用法。`{cli}` 是接線：對應的設定編輯、包裝別名安裝、hook 檔建立，皆以 `<!-- jsc-hooks -->`（或 `# 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` 掃描模式的 exit 2 是掃到違規註解的設計行為——`sweep` 在髒工作區本來就會回 2，不算 hook 壞掉），以 `status=ok\|failed` 回報。`status {cli}` 是唯讀盤點：只讀設定檔判斷標記段落在不在，不寫檔也不執行 hook，每個接線點印一行 `item<TAB>{項目}<TAB>{路徑}<TAB>{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` 回報 |
 
 ## 失敗回報範本
@@ -70,7 +79,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`），語言規則仍重寫到各自的規則檔（以 `<!-- jsc-hooks -->` 標記整段取代，等同先移除再重裝，不重複追加）。codex、copilot、antigravity、kiro 的 SDLC 模型鎖降級為技能步驟檢查，鎖檔仍由 SDLC 技能直接呼叫 `sdlc-gate.sh lock` 寫入；這四個 CLI 沒有 pre-tool hook，版本前置檢查接不上，也沒有 post-tool hook，`comment-scope.sh` 只接得到規則提示、接不上寫檔後的自動掃描，腳本會在 `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`），語言規則仍重寫到各自的規則檔（以 `<!-- jsc-hooks -->` 標記整段取代，等同先移除再重裝，不重複追加）。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`
 
@@ -89,7 +98,7 @@ 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_COMMENT_SCOPE` | 設 `off` 完全略過註解範圍檢查（`comment-scope.sh` 三種模式都直接結束） | 啟用檢查 |
 | `JSC_CHANGED_FILE` | 非 Claude CLI 要掃描的檔案路徑，代替 stdin JSON 的 `file_path`，供 `comment-scope.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/skills/hooks-install/SKILL.md b/skills/hooks-install/SKILL.md
index d5b910f..b3ceabc 100644
--- a/skills/hooks-install/SKILL.md
+++ b/skills/hooks-install/SKILL.md
@@ -10,7 +10,17 @@ Goal: make the six hooks (`ste100-guard.sh`, `session-timer.sh`, `skill-usage.sh
 Install on a clean slate. Every CLI is purged of all hooks first, third-party ones included, so a later failure has exactly one owner. `tools/wire-cli.sh purge` backs up every file it touches before it removes anything, so the removal stays reversible.
 
 Only claude has PreToolUse, PostToolUse and UserPromptSubmit, so only claude reports `wired`. On codex, copilot, antigravity and kiro the version guard cannot be wired at all and the SDLC gate degrades to the skill-step check, so all four report `degraded` — report that gap as the script words it instead of implying every CLI is covered.
-`comment-scope.sh` degrades the same way on those four: they have no post-tool hook, so only its `prompt` mode reaches them, written into the same rule file as the STE100 block. The file is never scanned after a write there, and a comment that already carries an issue number is caught only by `jsc-review:code-review`. Say that plainly — a rule reminder is not the same protection as the scan claude gets.
+
+`comment-scope.sh` now reaches all five, but on a different event and at a different moment each. Report the timing per CLI; never state it as one uniform behaviour:
+
+| CLI | Scanning moment | Wired through |
+| --- | --- | --- |
+| claude | Per file, the instant it is written | PostToolUse |
+| codex | End of every turn, over the whole git worktree | `notify` in `config.toml` |
+| kiro | On every prompt submit, over the whole git worktree — it sees what the previous turn wrote | `userPromptSubmit` in `.kiro/hooks/jsc-hooks.json` |
+| copilot, antigravity | Once, when the session ends | `tools/jsc-wrap.sh` teardown |
+
+The `sweep` mode reads `git diff HEAD`, so its coverage matches what claude sees; only the feedback delay differs. Outside a git worktree `sweep` exits 0 in silence and nothing is scanned at all — say so when the user works outside git. The `prompt` rule reminder still goes into every rule file alongside the STE100 block, because a warning that arrives a turn late is worth less than not writing the comment in the first place.
 The lock file still works on those four because the SDLC skills call `sdlc-gate.sh lock {stage}` directly — that call is where the capability-tag comparison happens, so the gate keeps its force even where the prompt hook cannot be wired.
 The gate needs `$JSC_HOME/model-tags.tsv`; when it is missing, report that `jsc-cli:models` (or `jsc-cli/tools/model-tags.sh sync`) must run once, because `sdlc-gate.sh lock` refuses to lock without it.
 
@@ -34,7 +44,8 @@ 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. `comment-scope.sh` exit 2 counts as healthy for the same reason — it means the scan found a comment and warned about it. With no file name to scan the hook exits 0 in silence, which is what smoke normally sees.
-- `comment-scope.sh` takes `prompt` (inject the rule summary at UserPromptSubmit) and no argument at all (scan the file just written at PostToolUse, reading `file_path` from stdin JSON or `JSC_CHANGED_FILE`). It scans only the lines a diff added, skips markdown and binary files, and turns 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.
+- `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` exit 2 counts as healthy for the same reason — it means the scan found a comment and warned about it. The 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. Neither 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.
+- `jsc-wrap.sh` runs `sweep` 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 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`.
-- 
2.53.0


From 542f0aab2c20fe3040228ba45cf9491baef44226 Mon Sep 17 00:00:00 2001
From: Jeffery <jiantw83@yahoo.com>
Date: Thu, 27 Aug 2026 09:20:44 +0800
Subject: [PATCH 4/4] =?UTF-8?q?feat(manifest):=20=E4=B8=89=E4=BB=BD=20mani?=
 =?UTF-8?q?fest=20=E7=89=88=E6=9C=AC=E5=8D=87=E5=88=B0=200.2.0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 支援。
---
 .claude-plugin/plugin.json | 2 +-
 .codex-plugin/plugin.json  | 2 +-
 plugin.json                | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index dcf3007..c7e0c3a 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "jsc-hooks",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查",
   "skills": "./skills",
   "author": {
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 13f0784..440650e 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "jsc-hooks",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查",
   "skills": "./skills"
 }
diff --git a/plugin.json b/plugin.json
index f6c6bfe..b014c28 100644
--- a/plugin.json
+++ b/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "jsc-hooks",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查",
   "skills": "./skills/"
 }
-- 
2.53.0