From dbf9aac25ebb7a834833d18a5e070e13413d253b Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 27 Aug 2026 16:34:17 +0800 Subject: [PATCH 1/6] =?UTF-8?q?feat(restart-gate):=20=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=E9=83=A8=E7=BD=B2=E5=BE=8C=E5=BC=B7=E5=88=B6=E9=87=8D=E5=95=9F?= =?UTF-8?q?=E9=96=98=E9=96=80=EF=BC=8C=E4=B8=A6=E6=8E=A5=E4=B8=8A=E6=96=B0?= =?UTF-8?q?=E5=B7=A5=E4=BD=9C=E9=9A=8E=E6=AE=B5=E8=87=AA=E5=8B=95=E6=B8=85?= =?UTF-8?q?=E9=99=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：新增第八支 hook `hooks/restart-gate.sh`。hook 模式在 `$JSC_HOME/restart-required` 存在時以 exit 2 擋下 jsc 技能呼叫，另有三個子命令：`require {模式} [{domain}...]` 寫入狀態檔掛上閘門、`clear` 清除狀態檔、`report` 印出狀態檔內容。`hooks/hooks.json` 把它接到 PreToolUse(Skill)，排在 `version-guard.sh` 前面。`hooks/session-timer.sh` 的 `start` 與 `restart` 在判定為新工作階段時轉呼叫 `clear`。 Why：部署換掉的是磁碟上的技能檔，正在跑的 CLI 行程載入的還是舊版——SKILL.md、hook 腳本與 tools 都在啟動當下讀進記憶體。這段落差期間跑技能，改動看起來沒生效，人會以為部署失敗又重跑一次。所以部署收尾要求重新啟動，這道閘門負責讓「還沒重啟就繼續用技能」擋在門外。 How：判定看的是「檔案在不在」，欄位只用在擋人訊息上——欄位缺了只讓訊息少幾個字，不影響判定。狀態檔用純文字 `key=value`（`at`、`mode`、`domains`、`cli`），格式與工作包狀態檔同一套，`jsc-hooks` 與 `jsc-cli` 兩邊各自實作也對得上。放行原則比照 `version-guard.sh`：只擋確定違規，狀態檔讀不到、技能名取不到、工具名不是 `Skill`、技能不是 `jsc-*:*` 一律 exit 0，沒有證據時擋下等於停掉每一次技能呼叫。九支豁免（`jsc-cli:deploy`、`jsc-hooks:hooks-install`、`jsc-gitea:wiki`、`jsc-log:worklog`、`jsc-log:learn`、`jsc-meta:*`、`jsc-ask:ask`、`jsc-git:pr`、`jsc-git:commit`）的理由是同一件事：部署後還要寫得完技能組異動報告與工作日誌，整批擋下去「先重啟」與「先寫完報告」會互相打死。後三支自己不是收尾規則的主體，是為了讓前六支走得完才補進來的——清單認的是技能名，不是呼叫鏈。清除交給 `session-timer.sh`，不由本檔自己判：新舊工作階段的判準（`sessions/{sid}.start` 在不在）只有那支腳本知道，兩邊各寫一份就會漂移；續接同一階段走不到那一段，閘門就一路留到真的重新啟動。`require`、`clear`、`report` 都不讀標準輸入，只有 hook 模式讀，工具端呼叫一律再補 `/dev/null | head -n1 +} + +case "${1:-}" in + require) + _mode="${2:-update}" + _domains="" + if [ "$#" -gt 2 ]; then shift 2; _domains="$*"; fi + mkdir -p "$JSC_HOME" 2>/dev/null || true + printf 'at=%s\nmode=%s\ndomains=%s\ncli=%s\n' \ + "$(now_iso)" "$_mode" "$_domains" "$(cli_name)" > "$STATE" 2>/dev/null || { + # 寫不進去要講出來：沒寫成就沒有閘門，部署卻以為掛上了。 + printf '[jsc][重啟閘門][ERR]：寫不進 %s，這次部署沒有掛上重啟閘門。\n' "$STATE" >&2 + exit 2 + } + exit 0 ;; + clear) + rm -f "$STATE" 2>/dev/null || true + exit 0 ;; + report) + if [ -f "$STATE" ] && [ -r "$STATE" ]; then cat "$STATE" 2>/dev/null || true; fi + exit 0 ;; + "") ;; # 落到下面的 hook 模式 + *) exit 0 ;; # 不認得的子命令一律安靜放行，不中斷宿主 CLI +esac + +read_stdin + +[ "${JSC_RESTART_GATE:-}" = "off" ] && exit 0 + +# 輸入相容：stdin JSON（Claude 格式）與環境變數（其他四支 CLI 接線時設定）都要收， +# 取法比照 version-guard.sh。工具名取不到就當成沒篩，繼續判技能名。 +tool="${JSC_TOOL_NAME:-${TOOL_NAME:-$(json_str tool_name)}}" +[ -z "$tool" ] || [ "$tool" = "Skill" ] || exit 0 + +skill="${JSC_SKILL:-${SKILL:-$(json_str skill)}}" +[ -n "$skill" ] || exit 0 + +# 只管本技能組（jsc-{domain}:{name}）。別人的技能不受這道閘門影響。 +case "$skill" in + jsc-*:*) ;; + *) exit 0 ;; +esac + +# 豁免清單（理由見檔頭） +case "$skill" in + jsc-cli:deploy|jsc-hooks:hooks-install|jsc-gitea:wiki|jsc-log:worklog|jsc-log:learn|jsc-meta:*|jsc-ask:ask|jsc-git:pr|jsc-git:commit) + exit 0 ;; +esac + +# 狀態檔讀不到就放行：沒有「剛部署過」的證據，就沒有擋人的理由。 +[ -f "$STATE" ] && [ -r "$STATE" ] || exit 0 + +at=$(state_field at) +mode=$(state_field mode) +domains=$(state_field domains) + +# 重啟方式依實際 CLI 給。印別的 CLI 的執行檔名等於沒給指示。 +bin=$(cli_bin "$(cli_name)") +[ "$bin" = unknown ] && bin="目前的 CLI" + +# 訊息裡的部署資訊逐段接起來，缺欄位就少一段，不會留下空括號或多餘的逗號。 +info="" +[ -n "$at" ] && info="$at" +[ -n "$mode" ] && info="${info}${info:+，}模式 $mode" +[ -n "$domains" ] && info="${info}${info:+，}domain：$domains" + +printf '[jsc][重啟閘門][ERR]：技能組已更新%s，%s 還在跑舊版，新版要重新啟動才會載入。本次技能呼叫已擋下。\n' \ + "${info:+（$info）}" "$bin" >&2 +printf '重新啟動：結束 %s 再重新開啟一次，狀態檔 %s 會在新工作階段開始時自動清除。\n' \ + "$bin" "$STATE" >&2 +printf '仍可使用：/jsc-cli:deploy、/jsc-hooks:hooks-install、/jsc-gitea:wiki、/jsc-log:worklog、/jsc-log:learn、/jsc-meta:*、/jsc-ask:ask、/jsc-git:pr、/jsc-git:commit（部署後的異動報告與工作日誌要寫得完）　｜　確定要略過閘門：JSC_RESTART_GATE=off\n' >&2 +exit 2 diff --git a/hooks/session-timer.sh b/hooks/session-timer.sh index 13867c7..5c7895f 100755 --- a/hooks/session-timer.sh +++ b/hooks/session-timer.sh @@ -11,16 +11,32 @@ # SessionStart 會再觸發一次，覆寫起始時間會讓花費時間歸零。 # restart 給接不到 session id 的 CLI（kiro）。那些 CLI 的紀錄共用 default， # 不覆寫就會把上一個工作階段的起始時間算進來，花費時間虛胖。 +# +# 這兩個子命令另外兼一件事：判定為「新的工作階段」時清除部署後的重啟閘門 +# （restart-gate.sh clear）。新工作階段代表 CLI 行程是新起的，新版技能組一定已經載入。 +# 判準只有這裡知道——start 分支的「起始檔不存在」就是這個 session id 第一次開始， +# 所以清除掛在這裡，不在 restart-gate.sh 裡自己再判一次。 HERE=$(dirname "$0"); . "$HERE/lib.sh" read_stdin sid=$(session_id) + +# 放下部署後的重啟閘門。狀態檔的路徑與格式只留在 restart-gate.sh，這裡不碰檔案。 +# 一律 /dev/null || true +} + case "${1:-mark}" in start) f="$JSC_HOME/sessions/$sid.start" - [ -f "$f" ] || now_epoch > "$f" ;; + if [ ! -f "$f" ]; then + now_epoch > "$f" + clear_restart_gate # 起始檔不存在＝這個工作階段第一次開始，也就是行程新起的那一次 + fi ;; restart) now_epoch > "$JSC_HOME/sessions/$sid.start" - rm -f "$JSC_HOME/sessions/$sid.end" ;; + rm -f "$JSC_HOME/sessions/$sid.end" + clear_restart_gate ;; # 接不到 session id 的 CLI 每次工作階段開始都算新的，一律清 mark) now_epoch > "$JSC_HOME/sessions/$sid.end" ;; report) -- 2.53.0 From e370729720ceb2e86682b3a1322e9924ebf78678 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 27 Aug 2026 16:34:17 +0800 Subject: [PATCH 2/6] =?UTF-8?q?feat(wire-cli):=20=E6=8E=A5=E7=B7=9A?= =?UTF-8?q?=E8=85=B3=E6=9C=AC=E7=B4=8D=E5=85=A5=E9=83=A8=E7=BD=B2=E5=BE=8C?= =?UTF-8?q?=E9=87=8D=E5=95=9F=E9=96=98=E9=96=80=EF=BC=8C=E4=B8=83=E6=94=AF?= =?UTF-8?q?=E6=94=B9=E5=85=AB=E6=94=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：`tools/wire-cli.sh` 四處增修。`smoke` 加跑 `restart-gate.sh`，另外自備一份暫時的 `$JSC_HOME`，把八條判定路徑（狀態檔不存在、狀態檔存在且技能為 `jsc-sdlc:implement`、四支豁免技能各一條、逃生門、取不到技能名）各跑一次並比對結束碼，再驗一次清除機制真的清得掉；claude 的接線驗證與 `status` 盤點各加一個 `restart-gate` 檢查點；codex、copilot、antigravity、kiro 四支的 degraded 說法補上「部署後重啟閘門也接不上」；檔頭與各處「七支」一律改為「八支」。 Why：新的 hook 接進 `hooks.json` 只代表宣告在檔案裡。接線驗證不點名就漏得掉——`comment-scope.sh` 與 `lang-guard.sh` 當初就是為同一個原因各列一項。冒煙測試也一樣：不自備狀態檔，只走得到「狀態檔不存在」與「取不到技能名」兩條捷徑，擋人與豁免那幾條一次都跑不到，判定寫了卻沒驗等於沒寫。四個 CLI 的降級說法不補，回報就會暗示每個 CLI 都擋得下來。 How：驗的是判定結果本身，不只是腳本跑得完——每一條路徑都給定預期結束碼，對不上就計入失敗並印出前 200 字的輸出。狀態檔放在暫時目錄，冒煙測試不該把使用者真正的 `$JSC_HOME/restart-required` 拆掉。清除機制那一段刻意走 `session-timer.sh start` 這條真實路徑，不直接呼叫 `clear`：要驗的是「新工作階段會不會清」，不是「`clear` 這個子命令能不能刪檔」。每次呼叫都接 `> "$smoke_out" fi + + # 部署後重啟閘門（restart-gate.sh）：上面那支只走得到「狀態檔不存在」與「取不到技能名」， + # 擋人那一條完全沒跑到。這裡同樣自備一份暫時的 $JSC_HOME，把五條判定路徑各跑一次並比對 + # 結束碼，最後再驗清除機制真的把狀態檔清掉。用暫時目錄是為了不動到使用者真正的 + # $JSC_HOME/restart-required——冒煙測試不該把別人的閘門拆掉。 + # 一律 &1); _rc=$? + if [ "$_rc" -eq "$3" ]; then + printf '[jsc] restart-gate.sh（%s）：exit %s，與預期相同。\n' "$1" "$_rc" >> "$smoke_out" + else + smoke_fails=$((smoke_fails + 1)) + printf '[jsc] restart-gate.sh（%s）：exit %s，預期 %s，重啟閘門判定壞了：%s\n' \ + "$1" "$_rc" "$3" "$(printf '%s' "$_out" | tr '\n' ' ' | cut -c1-200)" >> "$smoke_out" + fi + } + if rs_home=$(mktemp -d 2>/dev/null); then + smoke_rs_case "狀態檔不存在" jsc-sdlc:implement 0 + JSC_HOME="$rs_home" sh "$HOOKS/restart-gate.sh" require update hooks cli /dev/null + smoke_rs_case "狀態檔存在，技能 jsc-sdlc:implement" jsc-sdlc:implement 2 + smoke_rs_case "狀態檔存在，豁免技能 jsc-cli:deploy" jsc-cli:deploy 0 + smoke_rs_case "狀態檔存在，豁免技能 jsc-gitea:wiki" jsc-gitea:wiki 0 + smoke_rs_case "狀態檔存在，豁免技能 jsc-log:worklog" jsc-log:worklog 0 + smoke_rs_case "狀態檔存在，豁免技能 jsc-meta:skill-check" jsc-meta:skill-check 0 + smoke_rs_case "逃生門 JSC_RESTART_GATE=off" jsc-sdlc:implement 0 off + smoke_rs_case "取不到技能名" "" 0 + # 清除機制：session-timer.sh 判定為新工作階段時會呼叫 restart-gate.sh clear。 + # 這裡走的就是那條路徑（暫時 $JSC_HOME 底下沒有起始檔，等同行程新起的第一次）。 + if [ -f "$rs_home/restart-required" ]; then + JSC_HOME="$rs_home" JSC_SESSION_ID=smoke-restart \ + sh "$HOOKS/session-timer.sh" start /dev/null + if [ -f "$rs_home/restart-required" ]; then + smoke_fails=$((smoke_fails + 1)) + printf '[jsc] restart-gate.sh（清除機制）：新工作階段開始後狀態檔還在，閘門會一直擋。\n' >> "$smoke_out" + else + printf '[jsc] restart-gate.sh（清除機制）：新工作階段開始後狀態檔已清除，與預期相同。\n' >> "$smoke_out" + fi + else + smoke_fails=$((smoke_fails + 1)) + printf '[jsc] restart-gate.sh（清除機制）：require 沒有寫出狀態檔，清除機制沒驗到。\n' >> "$smoke_out" + fi + rm -rf "$rs_home" + else + smoke_fails=$((smoke_fails + 1)) + printf '[jsc] restart-gate.sh：建不出暫存目錄，部署後重啟閘門判定沒驗到。\n' >> "$smoke_out" + fi # comment-scope.sh 有三個接在不同事件的模式，三個都要驗：prompt 一律 exit 0， # 無參數模式在取不到檔名時安靜 exit 0（上面已清空 JSC_CHANGED_FILE，stdin 也只有 {}）， # sweep 掃目前工作目錄所在的 git 工作區——乾淨或非 git 目錄回 0，有違規註解回 2， @@ -715,7 +768,7 @@ if [ "$action" = smoke ]; then 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 有執行期錯誤" @@ -772,14 +825,18 @@ if [ "$action" = status ]; then 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 - # 七支 hook 全靠這一個檔宣告，只看檔案在不在會漏掉「檔在、某支沒接進去」。 - # 後來才加進來的 comment-scope.sh 與 lang-guard.sh 是最可能漏的兩支，所以各列一項。 + # 八支 hook 全靠這一個檔宣告，只看檔案在不在會漏掉「檔在、某支沒接進去」。 + # 後來才加進來的 comment-scope.sh、lang-guard.sh 與 restart-gate.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 ;; + else st_item lang-guard "$HOOKS/hooks.json" missing; fi + if [ -f "$HOOKS/hooks.json" ] && grep -qF 'restart-gate.sh' "$HOOKS/hooks.json" 2>/dev/null + then st_item restart-gate "$HOOKS/hooks.json" present + else st_item restart-gate "$HOOKS/hooks.json" missing; fi ;; codex) config="${CODEX_HOME:-$HOME/.codex}/config.toml" @@ -808,21 +865,21 @@ if [ "$action" = status ]; then st_block ste100 "${CODEX_HOME:-$HOME/.codex}/AGENTS.md" "" 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 可接版本前置檢查，註解範圍與繁中編碼改為每輪結束掃整個工作區，不是逐檔即時" ;; + 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_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 可接版本前置檢查，註解範圍與繁中編碼只在工作階段結束時掃一次整個工作區" ;; + 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_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 可接版本前置檢查，註解範圍與繁中編碼只在工作階段結束時掃一次整個工作區" ;; + st_degrade="STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查與部署後重啟閘門，註解範圍與繁中編碼只在工作階段結束時掃一次整個工作區" ;; kiro) # kiro 的 hook 檔綁在工作區，這裡看的一律是目前工作目錄底下那一份 @@ -849,7 +906,7 @@ if [ "$action" = status ]; then 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 可接版本前置檢查，註解範圍與繁中編碼改為每輪提示送出時掃整個工作區，不是逐檔即時" ;; + st_degrade="SDLC 模型鎖降級為技能步驟檢查，無 pre-tool hook 可接版本前置檢查與部署後重啟閘門，註解範圍與繁中編碼改為每輪提示送出時掃整個工作區，不是逐檔即時" ;; esac if [ "$st_missing" -gt 0 ]; then @@ -860,7 +917,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 @@ -873,8 +930,11 @@ case "$cli" in || 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，繁中與編碼檢查不會生效" + grep -qF 'restart-gate.sh' "$HOOKS/hooks.json" 2>/dev/null \ + || fail "$HOOKS/hooks.json 沒有接上 restart-gate.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 有 pre-tool hook，版本前置檢查與部署後重啟閘門只在這裡擋得下技能呼叫；其他四個 CLI 兩道閘門都接不上。" echo "[jsc] claude：只有 claude 有 post-tool hook，comment-scope.sh 與 lang-guard.sh 的逐檔即時掃描只在這裡接得上；其他四個 CLI 改用 sweep 掃整個工作區，時機晚一輪或晚到工作階段結束。" exit 0 ;; @@ -912,13 +972,14 @@ case "$cli" in has_block "$agents" "" || fail "$agents 寫入後讀不到 jsc-hooks 標記段落" has_comment_scope "$agents" || fail "$agents 寫入後讀不到註解範圍規則" has_lang_guard "$agents" || fail "$agents 寫入後讀不到繁中與編碼規則" - printf 'status=degraded reason=%s\n' "STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-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，最後跑 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：部署後重啟閘門也接不上（同樣是沒有 pre-tool hook），一次技能呼叫都擋不下來；狀態檔照樣寫、下次工作階段開始照樣清，重啟要自己動手。" echo "[jsc] codex：註解範圍與繁中編碼除了規則提示，每輪結束會由 notify 各掃一次整個 git 工作區（codex 沒有 post-tool hook，接不到逐檔即時掃描），回饋比 claude 晚一輪。" exit 1 ;; @@ -933,12 +994,13 @@ case "$cli" in has_block "$instr" "" || fail "$instr 寫入後讀不到 jsc-hooks 標記段落" has_comment_scope "$instr" || fail "$instr 寫入後讀不到註解範圍規則" has_lang_guard "$instr" || fail "$instr 寫入後讀不到繁中與編碼規則" - printf 'status=degraded reason=%s\n' "STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-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：部署後重啟閘門也接不上（同樣是沒有 pre-tool hook），一次技能呼叫都擋不下來；狀態檔照樣寫、下次工作階段開始照樣清，重啟要自己動手。" echo "[jsc] copilot：註解範圍與繁中編碼除了規則提示，工作階段結束時由 jsc-wrap.sh 收尾各掃一次整個 git 工作區（copilot 連逐輪事件都沒有），回饋要等到離開 CLI 才看得到。" exit 1 ;; @@ -953,12 +1015,13 @@ case "$cli" in has_block "$rules" "" || fail "$rules 寫入後讀不到 jsc-hooks 標記段落" has_comment_scope "$rules" || fail "$rules 寫入後讀不到註解範圍規則" has_lang_guard "$rules" || fail "$rules 寫入後讀不到繁中與編碼規則" - printf 'status=degraded reason=%s\n' "STE100 降級為 prompt 檔，SDLC 模型鎖降級為技能步驟檢查，無 pre-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：部署後重啟閘門也接不上（同樣是沒有 pre-tool hook），一次技能呼叫都擋不下來；狀態檔照樣寫、下次工作階段開始照樣清，重啟要自己動手。" echo "[jsc] antigravity：註解範圍與繁中編碼除了規則提示，工作階段結束時由 jsc-wrap.sh 收尾各掃一次整個 git 工作區（antigravity 連逐輪事件都沒有），回饋要等到離開 CLI 才看得到。" exit 1 ;; @@ -1011,10 +1074,11 @@ EOF || 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 可接版本前置檢查，註解範圍與繁中編碼改為每輪提示送出時掃整個工作區，不是逐檔即時" + 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：部署後重啟閘門也接不上（同樣是沒有 pre-tool hook），一次技能呼叫都擋不下來；狀態檔照樣寫、下次工作階段開始照樣清，重啟要自己動手。" echo "[jsc] kiro：註解範圍與繁中編碼除了規則提示，每輪提示送出時會各掃一次整個 git 工作區（kiro 沒有 post-tool hook），掃到的是上一輪寫的檔。" exit 1 ;; esac -- 2.53.0 From 7f8615a9ed8e72a4a9db6fd69d68da5b4af54651 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 27 Aug 2026 16:34:17 +0800 Subject: [PATCH 3/6] =?UTF-8?q?feat(hooks-install):=20=E6=8A=80=E8=83=BD?= =?UTF-8?q?=E5=90=8C=E6=AD=A5=E5=88=B0=E5=85=AB=E6=94=AF=20hook=20?= =?UTF-8?q?=E8=88=87=E9=87=8D=E5=95=9F=E9=96=98=E9=96=80=E7=9A=84=E9=99=8D?= =?UTF-8?q?=E7=B4=9A=E8=AA=AA=E6=B3=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：`skills/hooks-install/SKILL.md` 四處增修。`description` 與目標段落的 hook 清單加入 `restart-gate.sh`，七支改八支；降級說明補上「四個 CLI 連部署後重啟閘門也接不上」與後果一句；第 4 步的冒煙說明補上重啟閘門的每條判定路徑；備註新增 `restart-gate.sh` 一條，並在 `session-timer.sh` 那一條補上「`start` 與 `restart` 會清除閘門」。 Why：技能是接線這件事的對外說法。hook 加了一支、技能還寫七支，回報就會少一項，而且降級說法不補會暗示每個 CLI 都擋得下來——這正是準則明文禁止的。`session-timer.sh` 那條也要補：清除閘門掛在那兩個事件上，接線少了它們，閘門會一路擋到使用者自己下逃生門。 How：降級那一段把後果講明白，不只說「接不上」：在那四個 CLI 上一次技能呼叫都擋不下來，狀態檔照樣寫、下一個工作階段開始照樣清，重啟本身只靠 `jsc-cli:deploy` 的收尾訊息。備註那一條寫出豁免清單與逃生門，並講明豁免的理由是異動報告與工作日誌要寫得完，讓接線的人知道哪些技能在閘門升起時仍然叫得動。 Who：`/jsc-hooks:hooks-install` 的接線流程與對使用者的回報。 --- skills/hooks-install/SKILL.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/skills/hooks-install/SKILL.md b/skills/hooks-install/SKILL.md index 41d6b68..83fae58 100644 --- a/skills/hooks-install/SKILL.md +++ b/skills/hooks-install/SKILL.md @@ -1,15 +1,15 @@ --- name: hooks-install -description: Wire jsc hooks (STE100 guard, session timer, skill usage logger, SDLC model gate, plugin version guard, comment scope scanner, language guard) into every installed AI CLI, purging all pre-existing hooks first — third-party ones included, backed up before removal. Drive it per CLI through tools/wire-cli.sh purge, tools/wire-cli.sh, tools/wire-cli.sh smoke and tools/scan-hook-errors.sh. Hand any hook error, wiring or runtime, to jsc-hooks:repair, which must finish with a PR against develop; aborting the rest of the install to start that repair is allowed. Use after installing or updating the jsc plugin set; not for writing new hooks. +description: Wire jsc hooks (STE100 guard, session timer, skill usage logger, SDLC model gate, plugin version guard, post-deploy restart gate, comment scope scanner, language guard) into every installed AI CLI, purging all pre-existing hooks first — third-party ones included, backed up before removal. Drive it per CLI through tools/wire-cli.sh purge, tools/wire-cli.sh, tools/wire-cli.sh smoke and tools/scan-hook-errors.sh. Hand any hook error, wiring or runtime, to jsc-hooks:repair, which must finish with a PR against develop; aborting the rest of the install to start that repair is allowed. Use after installing or updating the jsc plugin set; not for writing new hooks. --- # hooks-install — wire jsc hooks into every installed CLI -Goal: make the seven hooks (`ste100-guard.sh`, `session-timer.sh`, `skill-usage.sh`, `sdlc-gate.sh`, `version-guard.sh`, `comment-scope.sh`, `lang-guard.sh`) effective in every CLI, with nothing else wired alongside them. +Goal: make the eight hooks (`ste100-guard.sh`, `session-timer.sh`, `skill-usage.sh`, `sdlc-gate.sh`, `version-guard.sh`, `restart-gate.sh`, `comment-scope.sh`, `lang-guard.sh`) effective in every CLI, with nothing else wired alongside them. 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. +Only claude has PreToolUse, PostToolUse and UserPromptSubmit, so only claude reports `wired`. On codex, copilot, antigravity and kiro neither the version guard nor the post-deploy restart gate can 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. On those four the restart gate blocks no skill call whatsoever: the state file is still written and still cleared at the next session start, so the restart itself rests on the `jsc-cli:deploy` closing message. `comment-scope.sh` and `lang-guard.sh` both reach all five, wired at the same set of places, but on a different event and at a different moment each. Report the timing per CLI; never state it as one uniform behaviour: @@ -33,7 +33,7 @@ The detailed flow **MUST run as a sub agent**; the main agent only reports the s 1. Run `jsc-cli/tools/detect-clis.sh`. Done when you hold the list of installed CLIs; when the list is empty, report that and stop. 2. For each installed CLI, run `tools/wire-cli.sh purge {cli}`. The script backs up every file it touches, removes all hooks, re-reads each file to confirm the removal, and restores the backup by itself when a check fails. Done when every CLI has printed exactly one `status=purged|skipped|failed reason=...` line and you have noted the backup directory path from its `[jsc]` output. 3. For each installed CLI, run `tools/wire-cli.sh {cli}`. The script owns both the wiring and its verification: it writes the config, alias or hook file inside a `` (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 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. +4. For each installed CLI, run `tools/wire-cli.sh smoke {cli}`. This runs all eight hooks once each, every wired mode included, plus each decision path of the work-package check and of the restart gate, 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`. @@ -41,7 +41,8 @@ The detailed flow **MUST run as a sub agent**; the main agent only reports the s ## Notes - Every hook script accepts both stdin JSON and environment variables (`JSC_CLI`, `JSC_SESSION_ID`, `JSC_SKILL`, `JSC_TOOL_NAME`, `JSC_MODEL`); `jsc-wrap.sh` sets the first two itself. -- `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. +- `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. `start` and `restart` also clear the restart gate whenever they decide this SessionStart is a new session, so the wiring of those two events is what lowers the gate after a restart — a CLI wired without them keeps the gate up until the user sets `JSC_RESTART_GATE=off`. +- `restart-gate.sh` blocks jsc skill calls while `$JSC_HOME/restart-required` exists, so a freshly deployed skill set is not used by a process still running the old one. `jsc-cli:deploy` writes that file through `restart-gate.sh require {install|update} [{domain}...]` at the end of an install or update. Exempt skills stay callable — `jsc-cli:deploy`, `jsc-hooks:hooks-install`, `jsc-gitea:wiki`, `jsc-log:worklog`, `jsc-log:learn`, `jsc-meta:*` — because the change report and the worklog still have to be finished after a deploy. Escape hatch: `JSC_RESTART_GATE=off`. - `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` 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. -- 2.53.0 From c1f2a5d728c53abb507b54b2aec36c7998c8aa4b Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 27 Aug 2026 16:34:17 +0800 Subject: [PATCH 4/6] =?UTF-8?q?docs(hooks):=20README=20=E8=88=87=20AGENTS?= =?UTF-8?q?=20=E8=A3=9C=E4=B8=8A=E9=83=A8=E7=BD=B2=E5=BE=8C=E9=87=8D?= =?UTF-8?q?=E5=95=9F=E9=96=98=E9=96=80=E8=88=87=E7=8B=80=E6=85=8B=E6=AA=94?= =?UTF-8?q?=E6=A0=BC=E5=BC=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：`README.md` 五處增修：hook 表新增 `hooks/restart-gate.sh` 一列，`session-timer.sh` 那一列補上會清除閘門、`wire-cli.sh` 那一列補上冒煙新增的判定路徑；覆蓋範圍那段的「七支」改「八支」並補上四個 CLI 接不上重啟閘門的後果；新增「部署後重啟狀態檔」一節，用表列出四個欄位與範例，寫明誰寫誰讀；環境變數表新增 `JSC_RESTART_GATE` 一列；`hooks-install` 段落同步。`AGENTS.md` 的 domain 一句話說明補上「部署後強制重啟閘門」。 Why：狀態檔的格式是 `jsc-hooks` 與 `jsc-cli` 兩邊的介面。介面只寫在腳本註解裡，另一邊改的時候看不到，格式一走鐘閘門就掛不上——這次就真的發生過：`jsc-cli` 寫四欄 TSV、這邊讀 `key=value`，狀態檔存在卻解不出欄位。覆蓋範圍也要據實寫，八支 hook 只有 claude 全接得上。 How：格式壓到最簡的純文字 `key=value`，一行一欄位，順序不拘，不認得的鍵一律忽略，與工作包狀態檔同一套寫法，兩邊各自實作也對得上。表只寫欄位與範例，判定規則寫在表底下：判定看檔案在不在、欄位只用在擋人訊息上、寫的一律是 `jsc-cli:deploy`、清的一律是 `session-timer.sh`，而且判準留在 `session-timer.sh`、狀態檔留在 `restart-gate.sh`，兩邊都不抄對方那一半。 Who：讀 `jsc-hooks` 說明的人，以及 `jsc-cli` 那一側寫 `deploy.sh` 的人。 --- AGENTS.md | 2 +- README.md | 27 ++++++++++++++++++++++----- 2 files changed, 23 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5da8f18..b08dd14 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 使用。 ## 規則 diff --git a/README.md b/README.md index fd7ba06..49b38a8 100644 --- a/README.md +++ b/README.md @@ -23,16 +23,17 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安 | 腳本 | 事件 | 作用 | | --- | --- | --- | | `hooks/ste100-guard.sh` | UserPromptSubmit | 注入 STE100 繁體中文輸出規則（hook > prompt 強制層） | -| `hooks/session-timer.sh` | SessionStart / Stop / SessionEnd | 記錄工作階段起訖。子指令：`start` 記起始時間（已有紀錄就不動，給 claude 這種每階段有自己 session id 的 CLI）、`restart` 一律覆寫起始時間（給接不到 session id 的 kiro，不覆寫會把上一階段算進來）、`mark` 更新最後活動時間、`report` 供 `jsc-log:worklog` 取花費時間 | +| `hooks/session-timer.sh` | SessionStart / Stop / SessionEnd | 記錄工作階段起訖。子指令：`start` 記起始時間（已有紀錄就不動，給 claude 這種每階段有自己 session id 的 CLI）、`restart` 一律覆寫起始時間（給接不到 session id 的 kiro，不覆寫會把上一階段算進來）、`mark` 更新最後活動時間、`report` 供 `jsc-log:worklog` 取花費時間。`start` 與 `restart` 判定為新工作階段時，另外呼叫 `restart-gate.sh clear` 放下部署後的重啟閘門——新工作階段代表 CLI 行程是新起的，新版一定已經載入 | | `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/restart-gate.sh` | PreToolUse(Skill) | 部署後強制重啟閘門：`$JSC_HOME/restart-required` 存在時以 exit 2 擋下 jsc 技能呼叫，並印出要重新啟動哪一支 CLI。狀態檔由 `jsc-cli:deploy` 在 install 或 update 收尾時經 `restart-gate.sh require {install｜update} [{domain}...]` 寫入，在下一個工作階段開始時由 `session-timer.sh` 呼叫 `restart-gate.sh clear` 清除。判定看檔案在不在：狀態檔讀不到、技能名取不到都放行（理由與 `version-guard.sh` 一致，只擋確定違規）。豁免 `jsc-cli:deploy`、`jsc-hooks:hooks-install`、`jsc-gitea:wiki`、`jsc-log:worklog`、`jsc-log:learn`、`jsc-meta:*`、`jsc-ask:ask`、`jsc-git:pr`、`jsc-git:commit`——部署後還要寫得完技能組異動報告與工作日誌，整批擋下去兩條規則會互相打死。清單認技能名不認呼叫鏈，後三支是為了讓前六支走得完才補進來的：`deploy` 要問模式、報告寫完要開 PR。另有唯讀子指令 `report` 印出狀態檔內容。逃生門 `JSC_RESTART_GATE=off` | | `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-claim {owner}/{repo} {工作包代號} [{PR 編號}] [{分析頁頁名}]` 記下這個存取庫目前領取哪一包、`wp-unclaim {owner}/{repo}` 交回、`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`，不是這裡。另外會比對歸屬：未結清的 PR 不屬於目前領取的工作包時，`prompt` 多注入一行「那幾支交給領取它的工作階段」，`skill` 在擋下 `plan`、`analyze`、`maintain` 時一併點名，`implement` 仍放行但收到同一則提醒。逃生門 `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、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` 別名在啟動當下開始；沒走別名啟動時，時間從第一輪回應算起。 +> 覆蓋範圍要據實看待：只有 claude 同時有 PreToolUse、PostToolUse 與 UserPromptSubmit，八支 hook 全接得上，回報 `wired`。codex、copilot、antigravity、kiro 都沒有 pre-tool hook，接不上 `version-guard.sh` 的版本前置檢查，也接不上 `restart-gate.sh` 的部署後重啟閘門，SDLC 模型鎖也只剩技能步驟檢查，這四個 CLI 一律回報 `degraded`，靠 `/jsc-cli:deploy` 定期更新。重啟閘門在這四個 CLI 上一次技能呼叫都擋不下來：狀態檔照樣寫、下一個工作階段開始照樣清，只是中間沒有判定點，重啟得靠 `/jsc-cli:deploy` 收尾的提示自己動手。codex 另外沒有工作階段開始事件，計時改由 `tools/jsc-wrap.sh` 的 `codex` 別名在啟動當下開始；沒走別名啟動時，時間從第一輪回應算起。 > `comment-scope.sh` 與 `lang-guard.sh` 五個 CLI 都掃得到，接的是同一批位置，但時機不同，不能當成五支一樣： @@ -58,6 +59,21 @@ Claude 由 `hooks/hooks.json` 自動接線七支 hook；其他 CLI 用 `hooks-in 歸屬查不到就放行（exit 0，只注入提醒）：沒有分析頁、`wp` 沒寫、領取檔不存在，三種都算這一類。理由與 `version-guard.sh` 一致——只擋確定違規，否則會把技能組維護自己鎖死。舊版鎖檔是單行 TSV（`{repo}{index}{上鎖時間}`，沒有工作包欄位），照樣讀得動，讀出來是查無歸屬。 +### 部署後重啟狀態檔 + +`$JSC_HOME/restart-required`（`JSC_HOME` 未設定時為 `~/.jsc`）一支檔案，格式與工作包狀態檔同一套：純文字 `key=value`，一行一欄位，順序不拘，不認得的鍵一律忽略。`jsc-hooks` 與 `jsc-cli` 兩邊各自實作也對得上。 + +| 欄位 | 內容 | 範例 | +| --- | --- | --- | +| `at` | 部署收尾時間，UTC | `at=2026-08-27T02:00:00Z` | +| `mode` | 這次部署的模式，`install` 或 `update` | `mode=update` | +| `domains` | 這次更新到的 domain，空白分隔 | `domains=hooks cli meta` | +| `cli` | 執行部署的 CLI 代號 | `cli=claude` | + +寫檔的一律是 `jsc-cli:deploy`，經 `restart-gate.sh require {install｜update} [{domain}...]` 落地，寫不進去會 exit 2 並講明「這次部署沒有掛上重啟閘門」——沒寫成就沒有閘門，不能讓部署以為掛上了。清除的一律是 `session-timer.sh`：`start` 判定起始檔不存在（這個 session id 第一次開始）、或 `restart`（接不到 session id 的 CLI，每次工作階段開始都算新的）時，呼叫 `restart-gate.sh clear`。判準留在 `session-timer.sh`、狀態檔留在 `restart-gate.sh`，兩邊都不抄對方那一半。 + +欄位只用在擋人訊息上。判定看的是「檔案在不在」——檔案存在就是還沒重啟過的證據，欄位缺了只讓訊息少幾個字。狀態檔讀不到、技能名取不到一律放行，理由與 `version-guard.sh` 相同。 + > `version-guard.sh report` 是非 hook 的子指令：印出每個已安裝 jsc plugin 的 > 「{domain} {本機} {遠端} {落後｜最新｜超前｜查詢失敗}」，最後一行 `behind {落後個數}`。 > 本機沒有 Claude 的 plugin 註冊檔時改印 `noregistry {路徑}` 再接 `behind 0`， @@ -72,7 +88,7 @@ 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` 回填，再依序跑一次 `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 的每個接線模式各跑一次，非零退出即為錯誤，另外用一份暫時的 `$JSC_HOME` 狀態檔把工作包歸屬的四條判定路徑（查無歸屬、自己的工作包、別的工作包、逃生門）各跑一次並比對結束碼，驗的是判定結果本身，不只是腳本跑得完（例外有三個：`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/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 的每個接線模式各跑一次，非零退出即為錯誤，另外用一份暫時的 `$JSC_HOME` 狀態檔把工作包歸屬的四條判定路徑（查無歸屬、自己的工作包、別的工作包、逃生門）與重啟閘門的五條判定路徑（狀態檔不存在、狀態檔存在、豁免技能、逃生門、取不到技能名）各跑一次並比對結束碼，再驗一次重啟閘門的清除機制真的清得掉，驗的是判定結果本身，不只是腳本跑得完（例外有三個：`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` 回報 | ## 失敗回報範本 @@ -93,7 +109,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，版本前置檢查接不上；也沒有 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 錯誤只回報，不轉修正。 +把八支 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` @@ -112,6 +128,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_RESTART_GATE` | 設 `off` 完全略過部署後重啟閘門（`restart-gate.sh` 一律放行） | 啟用閘門 | | `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` 使用 | 安靜降級，不掃描 | -- 2.53.0 From 4f92c48e10221dcf34f3b09601135ae319a879be Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 27 Aug 2026 16:34:17 +0800 Subject: [PATCH 5/6] =?UTF-8?q?chore(manifest):=20=E4=B8=89=E4=BB=BD=20man?= =?UTF-8?q?ifest=20=E7=89=88=E6=9C=AC=E5=8D=87=E5=88=B0=200.2.4=EF=BC=8C?= =?UTF-8?q?=E6=8F=8F=E8=BF=B0=E8=A3=9C=E9=BD=8A=E5=85=AB=E6=94=AF=20hook?= 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` 的 `version` 由 0.2.3 改為 0.2.4，`description` 的 hook 清單從五支補齊到八支，補上註解範圍守門、繁中編碼守門與部署後強制重啟。 Why：本次新增第八支 hook `restart-gate.sh` 並接進 `hooks.json`，`session-timer.sh` 多了清除閘門這件事，接線與冒煙也跟著改，屬於行為變更，版本要跟著往上走，各 CLI 才知道要更新。`description` 原本只列到「版本前置檢查」，而註解範圍與繁中編碼兩支早就在跑了，`README.md` 與 `AGENTS.md` 也都寫了八支——manifest 是各 CLI 安裝時唯一看得到的說明，落後就會讓人以為這個外掛只有五支 hook。 How：三份只改 `version` 與 `description` 兩個欄位，其餘內容不動，三份保持同一版號與同一段描述。 Who：`jsc-hooks` 外掛的套件描述檔。 --- .claude-plugin/plugin.json | 4 ++-- .codex-plugin/plugin.json | 4 ++-- plugin.json | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index c7339a4..2087948 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "jsc-hooks", - "version": "0.2.3", - "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查", + "version": "0.2.4", + "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟", "skills": "./skills", "author": { "name": "JSC" diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index bf89b9d..44a74aa 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-hooks", - "version": "0.2.3", - "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查", + "version": "0.2.4", + "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟", "skills": "./skills" } diff --git a/plugin.json b/plugin.json index 3e2fbc3..f8c27c9 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-hooks", - "version": "0.2.3", - "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查", + "version": "0.2.4", + "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟", "skills": "./skills/" } -- 2.53.0 From 7d67538a2a24ce8dd559061d495e3bc2d0b12e6c Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 27 Aug 2026 16:49:02 +0800 Subject: [PATCH 6/6] =?UTF-8?q?docs(hooks-install):=20=E8=B1=81=E5=85=8D?= =?UTF-8?q?=E6=B8=85=E5=96=AE=E8=A3=9C=E9=BD=8A=E7=82=BA=E4=B9=9D=E6=94=AF?= =?UTF-8?q?=EF=BC=8C=E8=88=87=E5=AF=A6=E4=BD=9C=E5=92=8C=E6=BA=96=E5=89=87?= =?UTF-8?q?=E5=B0=8D=E9=BD=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：`skills/hooks-install/SKILL.md` 的 Notes 段落，重啟閘門的豁免技能清單從六支補到九支，補上 `jsc-ask:ask`、`jsc-git:pr`、`jsc-git:commit`，並寫明「閘門認技能名不認呼叫鏈」以及清單的唯一來源在 `hooks/restart-gate.sh`。 Why：這三支是使用者在同一輪追問後才裁定加入的，實作 `hooks/restart-gate.sh` 與準則 `guidelines.md`「部署後重啟閘門」都已經是九支，只有這份技能文件還停在六支。技能文件是接線時唯一會被讀到的說明，少列三支會讓人以為 `deploy` 問模式、收尾開 PR 都會被擋，反而去下逃生門。 How：只改那一行，補上三支與兩句說明，並指向清單的唯一來源，避免下次又各自維護一份。三份 manifest 版本同步升到 0.2.5。 Who：`jsc-hooks:hooks-install` 技能文件，以及部署後重啟閘門這條規則的說明一致性。 --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- plugin.json | 2 +- skills/hooks-install/SKILL.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 2087948..cc19137 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-hooks", - "version": "0.2.4", + "version": "0.2.5", "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 44a74aa..d3b9b46 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-hooks", - "version": "0.2.4", + "version": "0.2.5", "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟", "skills": "./skills" } diff --git a/plugin.json b/plugin.json index f8c27c9..1b2054b 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-hooks", - "version": "0.2.4", + "version": "0.2.5", "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟", "skills": "./skills/" } diff --git a/skills/hooks-install/SKILL.md b/skills/hooks-install/SKILL.md index 83fae58..6d66c7a 100644 --- a/skills/hooks-install/SKILL.md +++ b/skills/hooks-install/SKILL.md @@ -42,7 +42,7 @@ The detailed flow **MUST run as a sub agent**; the main agent only reports the s - Every hook script accepts both stdin JSON and environment variables (`JSC_CLI`, `JSC_SESSION_ID`, `JSC_SKILL`, `JSC_TOOL_NAME`, `JSC_MODEL`); `jsc-wrap.sh` sets the first two itself. - `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. `start` and `restart` also clear the restart gate whenever they decide this SessionStart is a new session, so the wiring of those two events is what lowers the gate after a restart — a CLI wired without them keeps the gate up until the user sets `JSC_RESTART_GATE=off`. -- `restart-gate.sh` blocks jsc skill calls while `$JSC_HOME/restart-required` exists, so a freshly deployed skill set is not used by a process still running the old one. `jsc-cli:deploy` writes that file through `restart-gate.sh require {install|update} [{domain}...]` at the end of an install or update. Exempt skills stay callable — `jsc-cli:deploy`, `jsc-hooks:hooks-install`, `jsc-gitea:wiki`, `jsc-log:worklog`, `jsc-log:learn`, `jsc-meta:*` — because the change report and the worklog still have to be finished after a deploy. Escape hatch: `JSC_RESTART_GATE=off`. +- `restart-gate.sh` blocks jsc skill calls while `$JSC_HOME/restart-required` exists, so a freshly deployed skill set is not used by a process still running the old one. `jsc-cli:deploy` writes that file through `restart-gate.sh require {install|update} [{domain}...]` at the end of an install or update. Exempt skills stay callable — `jsc-cli:deploy`, `jsc-hooks:hooks-install`, `jsc-gitea:wiki`, `jsc-log:worklog`, `jsc-log:learn`, `jsc-meta:*`, `jsc-ask:ask`, `jsc-git:pr`, `jsc-git:commit` — because the change report and the worklog still have to be finished after a deploy, and the first six reach that finish line only through the last three: the deploy asks for its mode, the report closes with a PR. The gate matches skill names, not call chains, so a nested call to anything off the list is blocked all the same. `hooks/restart-gate.sh` owns the list; guidelines.md「部署後重啟閘門」carries the same nine with a reason per entry. Escape hatch: `JSC_RESTART_GATE=off`. - `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` 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. -- 2.53.0