docs(hooks): 每支腳本檔頭補上結束碼宣告，文件對齊九支 hook 的現況

共用函式庫與各支腳本的檔頭各補一段結束碼宣告，逐個子命令寫明哪些情況放行、
哪些情況擋下。說明文件改寫成九支 hook 的現況，補上寫入與提交閘門、唯讀模式、
建議子命令與新的環境變數。異常目錄範本補上「一律附加、不整頁覆蓋」的寫入語意。

呼叫端要靠結束碼決定下一步，但多數腳本只寫用法、沒寫結束碼，
讀的人得自己翻程式碼推，推錯就把安靜降級當成失敗處理。
共用函式庫載不到時，殼層會就地結束並回非零，接在工具呼叫前的閘門遇到這一下
等於無聲擋人，腳本自己的放行路徑一條都跑不到，這件事非寫進每一支檔頭不可。
文件停在八支 hook 的舊敘述，看的人會誤判覆蓋範圍，以為每支 CLI 都擋得住。
目錄頁的寫入語意只寫在腳本裡，換一支工具來寫就會整頁覆蓋。

一支腳本一段檔頭，逐子命令列出結束碼，並各自註明共用函式庫載入失敗會回哪一個碼。
文件的行數一律引用腳本自己印出來的那一行，不另抄一份數字，
判定路徑增減時就不會漂移。覆蓋範圍逐支 CLI 分開寫，接不上的就寫接不上。

hooks/lib.sh

@@ -4,6 +4,13 @@
 # 缺資料時安靜降級，hook 預設 exit 0，不可中斷宿主 CLI。
 # 唯一例外：sdlc-gate.sh check 在「SDLC 階段鎖存在且模型不符」時會 exit 2 擋下該輪提示；
 # 其餘情況（無鎖、資料不足無法判定）仍照舊 exit 0。
+#
+# 結束碼：不適用。本檔是被 source 的共用函式庫，不是可執行入口，內部一次 exit 都沒有。
+#   載入成功回 0（最後一行是函式定義）；拿 `sh lib.sh` 直接跑也只是定義完函式回 0，不做事。
+#   呼叫端真正要防的是「載入失敗」：POSIX sh 找不到這個檔時，`.` 會讓整支腳本就地結束並回 2。
+#   接在 PreToolUse 的 hook 遇到這一下，等於無聲擋掉每一次工具呼叫，而且腳本自己的放行路徑
+#   一條都跑不到。要安靜降級的呼叫端請寫 `. "$HERE/lib.sh" 2>/dev/null || true`
+#   （comment-scope.sh 就是這樣接）；其餘直接載入的腳本，各自檔頭都標了這一條。
 
 JSC_HOME="${JSC_HOME:-$HOME/.jsc}"
 mkdir -p "$JSC_HOME/sessions" "$JSC_HOME/usage" 2>/dev/null || true

hooks/session-timer.sh

@@ -6,6 +6,12 @@
 #   session-timer.sh mark             # Stop/SessionEnd：更新最後活動時間
 #   session-timer.sh report [sid]     # 印出 {sid} {seconds}；無紀錄印 0
 #
+# 結束碼：0=一律成功，四個子命令都走到最後那一行 exit 0，不認得的子命令也一樣（case 沒有
+#   相符分支就直接落到那一行）。這支接在 SessionStart 與 Stop／SessionEnd 上，本來就不擋人：
+#   狀態檔寫不進去只是少一筆計時，report 讀不到起始時間就印 0，都照樣 exit 0。
+#   唯一的非零來源是 lib.sh 載入失敗：本檔以 `. "$HERE/lib.sh"` 載入，沒有接 `|| true`，
+#   檔案不在時 sh 會就地結束並回 2。這兩個事件不擋工具呼叫，回 2 只會在宿主留下一筆 hook 錯誤。
+#
 # start 與 restart 的差別在「同一個 session id 會不會重複開始」：
 #   start   給 Claude 這種每個工作階段都有自己 session id 的 CLI。續接同一階段時
 #           SessionStart 會再觸發一次，覆寫起始時間會讓花費時間歸零。

hooks/skill-usage.sh

@@ -5,6 +5,12 @@
 # 產出:
 #   $JSC_HOME/usage/skills.jsonl  {ts,cli,session,skill}
 #   $JSC_HOME/usage/chains.jsonl  {ts,cli,session,from,to}（同 session 內前一技能 → 本技能）
+#
+# 結束碼：0=一律成功，只有這一種正常碼。取不到技能名（JSC_SKILL 與 stdin JSON 都沒有）就
+#   安靜降級，不寫任何紀錄直接 exit 0；寫得成紀錄也是 exit 0。這支接在 PostToolUse，
+#   技能已經跑完了，結束碼擋不掉任何事，所以連寫檔失敗都不回報。
+#   唯一的非零來源同 session-timer.sh：本檔以 `. "$HERE/lib.sh"` 載入，沒有接 `|| true`，
+#   lib.sh 讀不到時 sh 會就地結束並回 2。
 HERE=$(dirname "$0"); . "$HERE/lib.sh"
 read_stdin
 skill="${JSC_SKILL:-$(json_str skill)}"

hooks/ste100-guard.sh

@@ -3,6 +3,10 @@
 # Claude: UserPromptSubmit 的 stdout 會成為額外 context。
 # 其他 CLI: 由 hooks-install 以各自的規則檔（AGENTS.md 等）落地，本腳本仍可被 wrapper 呼叫。
 # 完整規則的唯一來源：jsc-meta 的 references/ste100.md。
+#
+# 結束碼：0=一律放行，而且只有這一種。本檔只把規則文字印到 stdout，不讀輸入、不碰檔案、
+#   不載入 lib.sh，所以沒有任何擋人路徑，也沒有會冒出非零碼的降級路徑。
+#   UserPromptSubmit 的 stdout 會成為額外 context，這支的產出走的是 stdout，不是結束碼。
 echo "[jsc] 輸出規則：STE100 繁體中文，擬人台灣感。適用範圍是所有非程式碼輸出——程式碼註解、commit 訊息、PR 描述、wiki 頁、對使用者的回報、README 與各種文件都算。短句、一句一指令、主動語態、術語一致；台灣用語（預設、支援、相容、資訊）；全形標點；去 AI 味（不用「總的來說」「首先／其次／最後」開場收尾套路、不諂媚）；直接講重點。一律 UTF-8 無亂碼、無簡體字，檔案不加 BOM。完整規則見 jsc-meta 的 references/ste100.md。"
 echo "[jsc] 送出前自我檢查，命中任一項就先改再送出：1）簡體字（例：应、为、这、说、后、发）；2）句尾用半形標點（. , ! ?），應為全形（。，！？）；3）套路句（「總的來說」「綜上所述」「首先…其次…最後」）；4）中文並列用半形「/」，應改頓號「、」；5）諂媚開場（「好問題」「當然可以」）。"
 exit 0