plugins/hooks
2
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
182 Commits 12 Branches 0 Tags
f1255038f632e7e264a5c7ee89a7b0b73870e341
Commit Graph
100 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
jiantw83andClaude Opus 5 f1255038f6 Merge develop 
三份 manifest 取 develop 的版號再往上升一版：分支停在一個比 develop 舊的版號，
取它等於把版號往回退。

行為清單兩支技能的節整節取 develop 那一版，再把分支新增的收尾說明逐段原文
接回去。develop 那一邊在這條分支開出去之後改寫了根目錄解析與外部呼叫兩欄，
分支那一邊只在關鍵步驟與可驗證跡象兩欄的尾端附加收尾事件的說明——兩件事互不
相干，取任一邊都會弄丟另一邊。

解這一段時弄壞過一次：第一版拿字元級差異把新增片段逐塊疊回去，中文被切碎重組，
「決定結局的那支工具的結束碼」變成「決定結局的那工具的結束碼」，關鍵步驟那一
整列還整列消失。行為清單檢核抓到表格只剩四列才發現。改成整節從 develop 重取、
只接分支相對它自己基底的那一段尾端附加，切點在共同前綴的盡頭，不切中文。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-07 09:08:36 +08:00
jiantw83andClaude Opus 5 d6f1e0e7ba feat(接線): status 加 --verdict，把狀態與成敗兩種語意分開 
status 的結束碼帶的是狀態：0 是接好、1 是接好但這支 CLI 做不到、5 是有東西
沒接。那是給人看的三分法，本身沒有錯。

問題出在被當成檢查用。助理的內建檢查項照結束碼判成敗，非零就是那一筆失敗、
失敗次數加一。於是有先天限制的那一支 CLI 每一輪都讓那一筆失敗一次，一天 96
次，而沒有人修得動——那支 CLI 擋不下技能叫用是它的架構限制，不是接線缺漏，
16 個接線項目全部就位。

那個計數存在的理由是指出「有一筆壞掉的項目每輪重試而沒人知道」。被一個修不動
的數字填滿，就等於用假的壞掉把真的壞掉蓋掉。

修在這一邊而不是修在讀的那一邊：狀態與成敗是兩種語意，混在同一個通道上才是
根因。這個旗標把成敗那一種單獨拉出來，status 保持原樣給人看。

--verdict 之下輸出一字不變——degraded 那一行照印，人看得到——只有結束碼換一套
語意：該接的都接了就回 0，先天限制不算；真的缺項目照樣回 5。

只有 status 收這個旗標，別的子命令帶了回 2：另外三個子命令的結束碼本來就是
成敗語意，多一個旗標只會讓人以為它們也有兩套。

實測：五支 CLI 兩種模式各跑一次，只有帶先天限制那一支從 1 變 0；輸出逐字
相同；暫時拿掉一個接線項目之後 --verdict 回 5，還原後回 0；旗標的三條錯誤
路徑都回 2。

三份 manifest 版號 0.4.4 升到 0.4.5。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-04 18:04:51 +08:00
jiantw83 1684e5636d chore(plugin): 三份 manifest 升版至 0.4.4 
共用函式庫的收尾修正要靠版號才傳得到機器端。

三份 manifest 由 sync-skill-manifest.sh 同步，只動版本欄位。
 2026-09-03 13:06:35 +08:00
jiantw83 858d3521bd fix(lib): 補上 stdin JSON 的載入期預設值，收尾不再吐未設定訊息 
有幾條路徑在收尾時會往標準錯誤吐一行「參數未設定」，掃描結果其實是對的，但那行訊息讓人以為掃描失敗。註解範圍掃描的流程規定「安靜地回 0 才算通過」，這一行正好讓「安靜」這個判準失效。

根因在共用函式庫：hook_trace 裝的 EXIT trap 會在腳本結束時經由 emit_event 呼叫 session_id，而它第一件事就是讀 stdin JSON 那個變數。腳本在讀取標準輸入之前就離開時，那個變數還沒人設過，開了 set -u 的腳本收尾就報錯。

訊息裡的檔名有誤導性：dash 回報行號用被 source 檔的行號、檔名卻用呼叫端的名字，所以看起來像是呼叫端的第 30 行出錯，實際上在函式庫裡。用一支探針腳本確認過行號的來源。

修法是在共用函式庫載入期給那個變數一個預設值，寫在任何讀取它的函式之前。修在共用處而不是各腳本各補一次：讀它的是共用函式，補在共用處才涵蓋每一條離開路徑，也涵蓋往後新增的腳本。用帶預設的展開而不是直接指派空字串，呼叫端已經帶值進來時原樣保留。

這個缺陷不只一處。凡是「有 set -u、裝了 hook_trace、又在讀取標準輸入之前離開」的路徑都會中，實測四條路徑修前都吐、修後都安靜。

驗證三項：掃描回 0 且標準錯誤零位元組；陽性對照仍正確回 2 並印出命中，證明掃描還有作用；事件記錄仍然正常，且事件裡的工作階段欄位取自標準輸入而不是預設值。事件驗證用隔離的環境做，沒有污染正式事件流。
 2026-09-03 13:06:35 +08:00
jiantw83 e5a9b05164 chore(plugin): 三份 manifest 升版至 0.4.3 
路徑解析的修正要靠版號才傳得到機器端，版本前置檢查才會要求更新。

三份 manifest 由 sync-skill-manifest.sh 同步，只動版本欄位。
 2026-09-03 12:19:27 +08:00
jiantw83 95c7bb1eee fix(lib): 跨外掛路徑解析改實體解析，修好版本閘門 
版本閘門對 11 個 domain 全部回「查詢失敗」，等於完全失效——它擋不下任何版本落後的技能呼叫，而且是無聲的：report 照印表格，只是每一列都寫查詢失敗。

根因是 jsc_gitea_sh 回傳的路徑帶著 ..，而那些 .. 要穿過 current/jsc-hooks 這條符號連結。兩種解析方式對它的答案不同：核心與 [ -f ] 用實體解析、跟著連結走，判定檔案存在；shell 的 cd 用邏輯解析、純文字消去 ..，落到一個不存在的目錄。所以 [ -f ] 檢查通過、路徑交了出去，gitea.sh 的 cd 卻失敗，回結束碼 2 與空輸出，呼叫端就判成查不到。

新增 jsc_abs_path，用 cd -P 加 pwd -P 把路徑正規化成不含 .. 的實體路徑。挑這個做法是因為兩者都是 shell 內建，不必在 PATH 上找執行檔——這些函式會在 cron 那種只剩幾段 PATH 的環境下跑，少一個外部相依就少一個解不出來的理由。jsc_gitea_sh 的四條候選改成尾端統一正規化，正規化失敗就退回原樣路徑，「找得到」的判準不變。

wire-cli.sh 的 HERE 與 ROOT 一併改成實體解析。那是同一個根因的另一種發作方式：ROOT 會被 ln -sfn 當成目標，而這支腳本常常就是經由那條連結被叫起來的，邏輯解析會讓 ROOT 等於連結自己，連結被改成指向自己，全機器 hook 一起失效。這件事實際發生過。原本靠兩道防線擋著：事後的 [ -f ] 檢查，以及文件要求呼叫端先解出實體根目錄。前者要等連結已經被寫壞才攔得到，後者靠人記得。改成實體解析之後這個失敗模式不可能成立。

行為契約第 10 列跟著改：從實體根目錄跑 wire-cli.sh 的規定保留，但性質從必要條件降成多一層保險，並寫明保險為什麼還值得買——舊版腳本還在別的機器上跑。

驗證用同形佈局做：暫存區搭一套一樣形狀的連結農場，先塞原版重現失敗、再塞改版確認修好。真實環境的連結與快取全程沒有動過。
 2026-09-03 12:19:27 +08:00
jiantw83 70526244c7 chore(plugin): 三份 manifest 升版至 0.4.2 
hooks-install 的路徑處理與行為清單都變了，版號要帶得出這批變更，版本前置檢查才會要求機器端更新。

三份 manifest 由 sync-skill-manifest.sh 同步，只動版本欄位，內容一致。

受影響的是靠版號判斷要不要更新的每一台機器。
 2026-09-03 10:32:22 +08:00
jiantw83 221dca70e6 fix(behaviors): repair 的可驗證跡象補上收尾事件 
行為清單檢查拿 HEAD 的內容跑就過不了，它點名 repair 那一列的可驗證跡象沒寫到收尾的 skill-end 事件。這是既有欠帳，跟這一批的路徑處理沒有關係，所以單獨一筆，之後要回退哪一邊都不會牽連另一邊。

補上的內容照準則寫：收尾在本機事件流留下這一輪的 skill-end，status 從 ok、blocked、failed、degraded、aborted 五個裡取一個，中途停下的那幾輪也照寫——只有 start 沒有配對的 end，會被讀成中斷。

受影響的是驗收 repair 有沒有跑完的人，還有把行為清單檢查掛在流程裡的每一個存放庫。
 2026-09-03 10:32:22 +08:00
jiantw83 358c30c7b8 fix(hooks-install): 腳本呼叫一律寫成執行期解出的字面絕對路徑 
無人看管的輪次會在第一支腳本就被擋下，整輪還沒開始就結束。2026-09-02 到 09-03 以非互動模式比照排程環境實測七種寫法，結論很乾淨：權限層比對的是還沒展開的字面字串，帶變數或帶波浪號的路徑一律解不出來，一律要人核准；路徑中段的萬用字元也不匹配，所以帶版本號的快取路徑放不進允許清單。連 readlink、ls 這種只讀指令都要有自己的規則。放寬允許清單救不了這件事，只有把路徑寫成字面絕對值才跑得動。

技能因此多兩節。路徑守則寫明每一次腳本呼叫都要是字面絕對路徑，並說清楚為什麼不能為了可攜性換回變數寫法——變數寫法買不到可攜性，只買到一輪還沒跑到第一階段就死掉。前置步驟把可攜性挪到執行期：兩個根目錄各以 readlink 解一次，只在這裡解，之後不重解，也不為此新增腳本。主代理人解完把兩條字面路徑交給每一個 sub agent，sub agent 自己不解。技能內九處腳本呼叫都改成由這兩個根目錄開頭。

兩條 readlink 各自在同一步用 [ -d ] 查過印出來的目錄真的存在。JSC_HOME 沒設時第一條會印出 /current、結束碼 0，非空又是絕對路徑，只查前三項擋不下來。

解兩個根目錄不是重複。連結農場根目錄給跨 domain 呼叫用；jsc-hooks 的實體根目錄只給接線腳本用，而這一條的理由與權限無關：那支腳本從自身位置推出自己的根目錄，又會改寫自己正踩著的那條連結。走連結跑下去，連結會被指向自己，全機器的 hook 一起失效——這件事實際發生過。

存放庫自帶的 hook 設定檔刻意保留變數寫法，技能文件也把這個例外寫明。那是檔案內容，由 hook 自己的 shell 在執行當下展開，不經過權限層，也不是誰在提示裡打出來的路徑；改成實體路徑等於把某一台機器的路徑寫死進要發佈的檔案。

行為清單的 hooks-install 四列跟著校準。

受影響的是每一個跑 hooks-install 的人，最直接的是排程觸發、沒有人在旁邊核准的那些輪次。
 2026-09-03 10:32:22 +08:00
jiantw83 44d1d00c0c chore(plugin 版本): 三份 manifest 升版至 0.4.2 2026-09-02 16:05:54 +08:00
jiantw83 4afb282c78 feat(狀態回報): 兩支技能的收尾寫一筆 skill-end 
hook 在原理上看不到技能的成敗：它接在技能工具呼叫上，而實際工作發生在
之後的模型輪次。start 由技能用量 hook 順手發，end 只能由技能自己寫。
有 start 沒有配對的 end，就是那一輪中止了。
 2026-09-02 16:05:54 +08:00
jiantw83 106922d530 chore(plugin 版本): 三份 manifest 升版至 0.4.1 2026-09-02 15:40:17 +08:00
jiantw83 a3ef205489 feat(狀態回報): 技能與 hook 的執行結果寫進本機事件流 
現行紀錄只記「被叫用」，欄位是 ts、cli、session、skill，沒有成敗也沒有
結束碼。跑完整輪的技能與開場就中止的技能，在紀錄裡長得一模一樣。hook
成功時更是完全不留紀錄，只有錯誤路徑會寫 wiki，而那條路徑刻意不自動觸發。

事件流走本機檔案，不直接寫 wiki。hook 每次提示都跑，網路寫入會拖垮宿主
CLI；失敗的 hook 自我回報還會疊出迴圈，既有的錯誤回報因此不接在失敗的
hook 上，這裡沿用同一條線。助理巡檢時排空、彙整、寫頁。

hook 端用 EXIT trap 接，一支只加一行。這幾支的 exit 點很多，階段閘門一支
就有五十幾個；逐點改要動到每一條判定路徑，而那些路徑正是閘門的判準，為了
加一行紀錄去動閘門，風險遠大於收益。trap 涵蓋每一條離開路徑，含中途失敗。

狀態預設由結束碼推，推不出來的由 hook 自己覆寫。相依版本檢查與兩道閘門有
這種情形：antigravity 走 deny JSON、kiro 只印警告，兩者擋下時結束碼都是 0，
單看結束碼會把擋下記成放行。

技能的 start 由既有的技能用量 hook 順手發，不必改任何技能文件。end 只能由
技能自己在收尾步驟寫——hook 觸發時技能的實際工作還在後面的模型輪次，看不到
成敗。有 start 沒有配對的 end，就是那一輪中止了。
 2026-09-02 15:40:17 +08:00
jiantw83 c0ce4c5c3c chore(plugin 版本): 三份 manifest 升版至 0.4.0 2026-09-02 14:57:04 +08:00
jiantw83 1d86359767 fix(接線盤點): status 列舉每一個接線點，不再只挑四支 
README 早就寫明「每個接線點印一行 item」，程式卻只列 comment-scope、
lang-guard、restart-gate 與 write-guard 三種模式，共六項。sdlc-gate 的三個
接線點、session-timer 的兩個、skill-usage 與 version-guard 都沒列出來。

漏列的後果不是少幾行字。reason 那行寫的是「全部九支 hook」，拿這份輸出
驗收接線的人會把沒列到的當成沒接——模型能力鎖就是這樣被誤判成沒接線的。
體檢技能也讀這支的輸出，同樣看不到那四支。

一支腳本接在多個接線點時，每個點各自列一項。只驗腳本名的話，「腳本在、
某個接線點沒接」會被算成完整接線，那正是最難查的一種。
 2026-09-02 14:57:04 +08:00
jiantw83 9136894837 chore(plugin 版本): 三份 manifest 升版至 0.3.9 2026-09-02 14:27:18 +08:00
jiantw83 096a85e638 feat(link): 連結一律寫成 [文字](絕對網址)，寫入前先驗證連得到 
取消 [[頁名]] 與 [[顯示文字|頁名]] 兩種同 wiki 寫法，不再分「同存取庫」與
「跨存取庫」兩條規則。那種寫法只在自己那個 wiki 內解析，寫錯不報錯，畫面上
看起來像普通文字或死連結，巡不到也修不了。

連結寫進頁面前先過 jsc-gitea 的 link-check.sh，結束碼 0 才寫。驗證一律走 API，
不看網頁狀態碼：私有存取庫的網頁網址對未登入請求一律回 404，拿狀態碼判會把
好連結判成壞的。認證失敗回 7，與死連結的 1 分開，免得金鑰一過期就把還在的頁
整批判死。
 2026-09-02 14:27:18 +08:00
jiantw83 f4871afd19 feat(wiki): 異常目錄頁改走專用存取庫，並修正目錄列連結恆空 
What：ERROR_CONTENTS 改由 wiki-repo CONTENTS 解析，ERROR_{HASH} 仍走
wiki-repo ERROR，兩者是兩個不同的存取庫。目錄列的連結改用 wiki-url 的絕對網址。
註解掃描的頁面編號樣式補上 40 碼與 H 加 7 碼兩種形狀。

Why：目錄列的網址原本在異常頁寫入之前就取，而頁名的雜湊帶時間戳、每次都是全新頁，
那時查一定是 404，又被吞掉，所以那一格一直都是空的。註解掃描原本只收 8 碼純十六進位，
舊演算法有十三個首碼會改寫成 H 開頭，等於對絕大多數舊頁編號漏偵測。

How：降級語意分兩層——異常頁的存取庫解不出來就整支安靜降級，只有目錄頁解不出來就
只寫異常頁、跳過索引，兩種都維持 exit 0。「只有 exit 4 才准建新頁、7 與 8 一律中止」
那段原樣保留，那是防止把金鑰失效讀成頁面不存在、拿範本蓋掉整頁既有列。

Who：jsc-hooks
 2026-09-02 11:30:49 +08:00
jiantw83 78dcb5e33b fix(sdlc-gate): 能力閘門依 CLI 分流，判不出能力就擋下 
What：
- current_model_report() 的偵測鏈依 CLI 分流，一支只讀自己的紀錄。claude 讀 transcript 與 hook stdin，codex 讀 hook stdin 與自己的 session 記錄，copilot、antigravity、kiro 本機沒有可讀的模型紀錄，判不出是哪一支 CLI 時不採用任何自動來源。JSC_MODEL 人工覆寫五支都保留，而且一律排在最後。
- session_id() 的退路鏈補上 CLAUDE_CODE_SESSION_ID，cli_name() 補上 CLAUDECODE 與 CLAUDE_CODE_SESSION_ID。
- 階段鎖狀態檔改成 sessions/{CLI 代號}-{sid}.stage。舊路徑仍讀得到，unlock 不帶參數時新舊兩份一起清，也收一個狀態檔路徑當參數。
- check 改成 fail-closed：判不出 CLI、判不出模型、模型不在能力標籤表上，三種一律以 exit 2 擋下該輪提示。每一則擋下的訊息都印出兩條逃生門。
- write-guard.sh 的 stage 模式改讀 lib.sh 的路徑函式，擋人訊息把實際讀到的狀態檔路徑寫進解除指令。
- codex_session_file() 取「全樹最新一支」的做法改掉。
- wire-cli.sh 的冒煙夾具跟著補：模型來源四條各自指定 CLI 代號，另加三種擋下情形、check 的 fail-closed、階段鎖的 CLI 區隔與舊格式相容，這一組的判定條數由四條增為十二條。
- README 的 hooks 表、狀態檔分界表與環境變數表跟著改。

Why：
- 使用者回報兩件事：在 claude 底下被 codex 的模型判定，而且這道閘門應該只鎖能力標籤、不鎖模型。查下來根因是同一個——閘門完全不分辨自己跑在哪一支 CLI 上。
- 偵測鏈不分流，claude 拿不到 transcript 就一路掉進 codex 的 session 記錄，拿別支的模型判這一支。順帶每一輪都對一個上千個檔、兩百多 MB 的目錄樹跑一次 find，宿主 CLI 跟著卡。
- session_id() 讀的變數名在目前的 claude 上並不存在，sid 一路退回 default。cli_name() 犯同一類錯：只認 plugin 接線才有的變數，技能以 Bash 工具呼叫腳本時取不到，一律判成 unknown。
- 前三項合起來的後果是：技能呼叫 lock 算出的檔名，跟 hook 算出的檔名永遠不同。階段鎖上了也對不上，所以這道閘門在 claude 上一直沒有真正生效。
- 狀態檔不分 CLI，各支就共用同一支 default.stage，一支上的鎖擋到另一支。那不只擋提示，write-guard.sh 的 stage 模式連 Write、Edit、MultiEdit 一起擋。

How：
- 政策改成 fail-closed：不知道能力就擋下，知道才比對標籤。原本判不出模型只提醒不擋，那等於「換一支讀不到紀錄的 CLI 就能繞過去」，閘門形同虛設。代價是把人鎖在送不出提示的狀態，所以每一則擋下的訊息都要帶兩條逃生門，照抄就脫困。
- 逃生門的路徑照抄進指令裡。擋人的是 hook，解鎖的是人在殼層手動執行，兩邊算出來的檔名未必相同，不點名就解不到真正擋人的那一支。
- unlock 的參數只收 sessions 目錄底下的 .stage 檔，逃生門不該順便變成任意刪檔的工具。判準刻意不綁這支行程算出的 JSC_HOME：擋人的一側跟解鎖的一側未必相同，綁上去就會把照抄訊息的人擋掉，那正是這個逃生門要避免的事。
- 狀態檔用檔名前綴不用子目錄。外部工具以單層的 sessions/*.stage 盤點階段鎖，改成子目錄會讓每一支鎖從那些盤點裡整批消失。
- 舊路徑只讀不搬也不刪，unlock 一併清掉。只清新的那一份，舊格式的鎖就永遠解不開，被它擋住的人沒有逃生門。
- 變數名只補實測看得到的那幾個，而且只補 claude 這一支。其他 CLI 的變數名與環境特徵沒有實測過，猜一個填進來只會多一個錯誤來源，那幾支本來就由接線設定明確帶 JSC_CLI。
- codex_session_file() 原本寫成 xargs ls -t 再 head -n 1，那是錯的：xargs 依參數長度分批，ls -t 只在自己那一批裡排序，取到的是第一批裡最新的，不是全域最新。改成讓 find 一併印出修改時間再全域排序；沒有 -printf 就退回路徑排序，那些檔名以 ISO 時間開頭，字典序等同時間序。
- 冒煙的擋人案例連訊息一起驗，不只比結束碼。訊息漏掉逃生門一樣是綠燈，而那才是這道 fail-closed 真正的風險。
- 四支腳本併成一筆。write-guard.sh 讀 lib.sh 的路徑函式，wire-cli.sh 是驗這些行為的冒煙夾具，拆開會留下跑不過的中間版本：路徑函式與呼叫端分兩筆，中間那一筆狀態檔的讀寫兩側就對不上。
- 一次性代價：升級後每台機器第一次 SessionStart 會清一次重啟閘門。sid 換了名字，看起來像新的工作階段。只發生這一次。
- 三份 manifest 這一筆不動，版本號另外提升。

Who：
SDLC 階段能力閘門。修的是它一直沒有生效的那條路徑，順帶把 codex session 記錄的取檔方式一起修掉。
 2026-09-02 10:48:08 +08:00
jiantw83 800a899239 feat(assistant-gate): 助理運行閘門，這一版尚未接線 
What：
- 新增 hooks/assistant-gate.sh：心跳新鮮就放行，心跳不存在、過期或時間戳壞掉就擋下該次技能呼叫。
- 豁免清單十一支、逃生門一個。README 的 hooks 表與環境變數表跟著補。
- 這一版刻意不接線，接線檔一個字都沒動。

Why：
- 助理沒在跑的時候，技能會以為背景有人收尾，實際上沒有。這道閘門把那個落差擋在門外。
- 不接線是因為這台機器的穩定路徑指向開發存放庫，寫進接線檔就立刻對五支 CLI 生效。而現在還沒有心跳，接線的那一秒整組技能會全部鎖死，連修的路徑都走不到。接線的前提是助理已經在跑、心跳穩定。

How：
- 這是整組 hook 裡唯一一道 fail-closed 的閘門。其餘的原則都是資料不足就放行，這一道相反。代價是狀態檔寫不進去時全組停擺，所以逃生門與豁免清單不是選配，是能上線的前提。
- 豁免清單只收解鎖路徑，不收收尾規則。這一點與重啟閘門的方向相反：重啟閘門解鎖靠閘門外的動作，收尾規則要寫得完；這一道解鎖靠跑一支技能，清單收寬了閘門就等於沒有。
- 清單認技能名不認呼叫鏈，所以豁免技能轉呼叫的下一層也要收進來。最要緊的是 wiki 那一支：巡檢要先把結果寫上監控頁才寫心跳，只豁免助理自己會做出「沒心跳就擋 wiki、擋了巡檢跑不完、跑不完就還是沒心跳」的自咬環。
- 心跳判定回「檔案系統問不出來」時放行，不擋。那是判不出事實，不在這道閘門的職權裡；而且那一刻正是磁碟或權限壞掉的訊號，擋下去連豁免那幾支也修不動——它們同樣要寫狀態檔。磁碟壞掉要人去清磁碟，不是把技能組鎖起來。時間戳壞掉則照擋，那是確定沒有可信心跳的證據，而且修法就在豁免清單裡。
- 逃生門的判斷擺在載入共用函式庫之前。函式庫讀不到時 sh 會就地結束並回擋人的那個碼，逃生門也會跟著跑不到，人就繞不過去。
- 擋人一律經 deny.sh 輸出。三支走標準錯誤加結束碼，另外兩支靠標準輸出的內容擋，結束碼固定是零；自己印訊息會在那兩支上無聲失效。
- 心跳不存在、過期、時間戳壞掉三種情況講三種話。使用者要做的事不一樣：一個是從沒啟動過，一個是跑過停了，一個是檔案壞了要重建。

Who：
助理落地的最後一塊。接線與準則那一節另外處理。
 2026-09-01 15:19:59 +08:00
jiantw83 b5107563dd chore(manifest): 心跳腳本的版本號補上，檔頭改指正確的技能名 
What：
- 三份 manifest 的版本一起提升。
- heartbeat.sh 檔頭引用的技能名由 status 改成 assistant。

Why：
- 上一筆加了 heartbeat.sh 卻沒有動版本號。版本不動，別的 domain 就沒有辦法用相依宣告要求「要有這支腳本的那一版」——宣告寫得出來，卻保證不了內容。助理宣告的下限本來會落在一個不含這支腳本的版本上。
- 檔頭寫的技能名是助理落地初期那一支獨立技能。助理主體把三個操作收攏成一支之後，那個名字就不存在了，照著找會找不到東西。

How：
- 版本由 sync-skill-manifest.sh 同步，三份一致。
- 這一支仍然不接線，只是被助理與閘門呼叫的工具。

Who：
助理主體實作時，從相依宣告那一側回頭抓到的兩個缺口。
 2026-09-01 14:18:49 +08:00
jiantw83 b0e352ae15 feat(heartbeat): 新增助理心跳的寫入、判定與回報 
What：
- 新增 hooks/heartbeat.sh，四個子命令：write 寫心跳、check 判定新鮮、report 印現況、clear 清除。
- README 的 hooks 表補一列，事件欄註明不接線；環境變數表補上心跳門檻那一個。

Why：
- 助理是背景行程，別人要知道它還在不在跑，唯一的依據就是它留下的心跳。閘門要判、status 技能要印、巡檢要記，三邊都需要同一份判定。
- 判定散在三個地方一定會漂移，狀態跟訊息就會對不上。所以判定只寫一份，check 與 report 共用同一個探測函式。

How：
- 新鮮的判準是「檔案存在，而且時間戳距現在小於門檻」。門檻預設 300 秒，是心跳週期的五倍，一次網路或磁碟卡頓不會誤判；環境變數可以覆寫，壞值退回預設而不報錯——變數打錯字不該讓判定整個歪掉。
- 絕不看 pid 存活。五支 CLI 與容器裡的行程互相看不到彼此的 pid，看了也證明不了什麼，pid 只當擋人訊息的線索。
- check 用結束碼分四種狀態：新鮮、過期、不存在、時間戳壞掉。前三種的處置各不相同，擋人訊息要說的話也不一樣；第四種既不是「跑過停了」也不是「沒啟動過」，併進任何一邊都會讓訊息說錯話，而且絕不能退回判成新鮮。
- 寫入走暫存檔再更名。直接覆寫的話，剛好讀到寫一半的檔案會少掉時間戳，助理活著卻被判成壞了。
- 這一支不接線，只是被助理與閘門呼叫的工具。接線是後續獨立的一步，先接會在心跳還沒跑起來時就擋死整組技能。

Who：
助理落地的第一塊：先有心跳，閘門才判得動，主體才有東西可寫。
 2026-09-01 14:08:14 +08:00
jiantw83 6f8afb8ac8 chore(marketplace): 把 jsc-assist 登錄進統一 marketplace 
What：
- 兩份 marketplace 檔各加一個 jsc-assist 條目，來源網址指向 assist 存放庫。

Why：
- 準則要求每個 domain 存放庫都帶同一份 marketplace 檔，任何一個存放庫都能當註冊入口。副本之間只要有一份沒跟上，稽核就會報出不一致。
- 正本少了這個條目，各 CLI 的安裝指令就找不到 jsc-assist，這個 domain 等於發佈不出去。

How：
- 條目由 meta 的 sync-marketplace.sh 產生，同時寫進正本與每個 domain 存放庫的副本，寫完逐檔比對位元組。這一支存放庫的兩份副本就是那一輪的產物。
- 條目依名稱排序，縮排與非 ASCII 描述的處理都交給同一支腳本，不手改 JSON。
- 這一批是從最新的預設分支重新產生的。前一輪的分支基底早於監控頁型別那批改動，直接合併會把那些改動回退掉，所以整批重做而不是解衝突。

Who：
助理 domain 落地的註冊步驟在這個存放庫的同步。
 2026-09-01 12:50:04 +08:00
jiantw83 113df37808 fix(comment-scope): 頁面編號偵測補齊三種缺漏的型別 
What：
- wiki 頁面編號的偵測樣式補上 SKILLSET、TOOLING 與 MONITOR 三種型別。
- 三份 manifest 的版本一起提升。

Why：
- 這支 hook 的職責是擋住把文件追蹤資訊寫進程式碼註解，wiki 頁面編號正是禁止項之一。
- 樣式只列到 REPORT，但實際的頁型清單早就有 SKILLSET 與 TOOLING，現在再加 MONITOR。清單漏掉的那幾種，頁面編號寫進註解就攔不到，等於這條規則對它們不存在。
- SKILLSET 與 TOOLING 的缺漏是既有落差，不是這次新增型別才產生的，一併補齊比較省事，也不會留下第二個要記得的地方。

How：
- 型別的排列順序照 gitea.sh 的 resolve_wiki_repo 走，兩邊一致才看得出有沒有漏。
- 規則正文的唯一來源仍是 jsc-review 的註解範圍文件，這裡只補偵測樣式，不重述規則清單。
- 實測過三種型別各自都攔得下來，命中的說明都是「jsc wiki 頁面編號」，不是旁邊那條前綴加流水號的樣式誤撿。

Who：
技能助理落地帶出來的頁型別需求，四個存放庫同一批改。
 2026-09-01 12:11:10 +08:00
jiantw83 fbf0aec9f7 fix(smoke): 擋人斷言改依各 CLI 的形態判定 
What：
- wire-cli.sh 的 smoke 區段新增四個共用小函式：smoke_deny_rc 給結束碼、smoke_deny_mark 給擋人標記、smoke_deny_ok 做判定、smoke_deny_desc 產生失敗訊息。
- smoke_rs_case 與 smoke_vg_case 的判定改走 smoke_deny_ok，五個呼叫點的預期值由結束碼 2 改成字面值 deny。
- 三份 manifest 的版本一起提升，由 sync-skill-manifest.sh 同步。

Why：
- 兩個函式把「擋下」寫死成結束碼 2，但擋下的形態是由 deny.sh 依 CLI 決定的。claude、codex、copilot 與認不得的代號走 stderr 加結束碼 2；antigravity 改印一行 stdout 的 deny JSON，kiro 只能注入警告，這兩支的結束碼都固定 0。
- 結果是這兩支的 smoke 各有五條判定失敗，回報成執行期錯誤。但擋人訊息其實都正確印出來了，配套的訊息斷言也全部通過，壞的只有結束碼那一項比對——是斷言認錯形態，不是 hook 失效。
- 不能改成一律放寬到 0。那兩支上放行也是 0，放寬之後「該擋沒擋」與「正確擋下」完全同形，這道斷言等於作廢。

How：
- 形態表在 smoke 這側鏡射一份，事實來源仍是 deny.sh 的 case。表只有一份，改一支不會忘了另一支。
- 判定同時比結束碼與擋人標記；預期放行的案例反過來要求標記不得出現，所以「該擋沒擋」與「不該擋卻擋了」兩個方向都守得住。
- 走 stderr 的三支標記為空字串，判定行為與原本完全相同，不產生回歸。
- 斷言條數不增不減，兩個預期條數常數都不必動。
- 反向測試確認斷言仍然有效：拿掉 deny.sh 裡 antigravity 的 deny JSON 輸出，做出該擋卻靜靜放行的情境，smoke 正確判失敗。結束碼相同，靠擋人標記才分得出來。

Who：
接線後的冒煙測試在 antigravity 與 kiro 上判定失敗，追出來的是斷言本身的缺陷。
 2026-09-01 11:48:13 +08:00
jiantw83 462264a253 Merge pull request '收攏四支 CLI 的 pre-tool hook 接線修正與共用腳本' (#58) from feat/cli-hook-rewire/main into develop 2026-09-01 00:58:41 +00:00
jiantw83 453b576050 Merge pull request '修正四支 CLI 的 pre-tool hook 接線，補上技能名解析與阻擋輸出共用腳本' (#57) from feat/cli-hook-rewire/four-cli-pre-tool into feat/cli-hook-rewire/main 2026-09-01 00:56:10 +00:00
jiantw83 3cd4b40ad0 chore(release): 版本號同步為 0.3.4 
What：plugin.json 與 .claude-plugin/plugin.json 的 version 由 0.3.3 改為 0.3.4。

Why：
- 這一批補上四支 CLI 的 pre-tool hook 接線，屬於新增能力，要發一個新版本。
- 三份 manifest 的版本號必須一致。版本前置檢查比對的就是這個號，對不上會讓 hook 判出錯誤的落後結論。

How：
- 由主流程的 sync-skill-manifest.sh 同步，三份一起改，不手動各寫一次。
- .codex-plugin/plugin.json 那一份的版本號隨接線提交一起進來，因為同一個檔案還加了 hooks 路徑鍵。

Who：jsc-hooks 0.3.4 發佈收尾。
 2026-08-31 19:05:48 +08:00
jiantw83 f586a6b69f docs(hooks): 同步四支 CLI 的接線位置與驗證等級 
What：README.md、references/behaviors.md 與 skills/hooks-install/SKILL.md 同步這一批的接線事實。

Why：
- 文件寫著「這些 CLI 沒有 pre-tool hook」。那句話是錯的，也正是三支 CLI 長期沒有守門的原因。照著它報告，會讓使用者以為只有 claude 有保護、其餘四支本來就接不上。
- kiro 的 degraded 原本被寫成接線缺東西，實際上是那支 CLI 擋不下技能叫用。兩件事的處理方式完全不同。

How：
- 一支 CLI 一列，列出接線位置、事件與 matcher、阻擋形態與判定，並寫明 claude、codex、copilot、antigravity 回 wired，kiro 回 degraded。
- 新增驗證等級表，把「形狀」與「觸發」分開記：形狀是那支 CLI 真的讀得懂設定，觸發是 hook 真的被叫用過。copilot 的形狀未證、antigravity 與 codex 的觸發未驗證，一律照實列出，不含糊帶過。
- README 補上 hooks/skill-name.sh 與 hooks/deny.sh 兩列，並補 COPILOT_HOME、KIRO_HOME、JSC_ANTIGRAVITY_HOOKS、JSC_COPILOT_INSTRUCTIONS、JSC_ANTIGRAVITY_RULES 幾個環境變數。
- kiro 的接線位置從 .kiro/hooks/jsc-hooks.json 全面改寫成 ~/.kiro/agents/jsc.json。
- 講明 write-guard.sh 三個模式與 SDLC 模型鎖在另外三支上是「還沒接」，不是「沒有 hook 可接」。
- behaviors.md 的完成條件與可驗證跡象跟著改，repair 那一列加上「技能名解析改 skill-name.sh、阻擋形態改 deny.sh，兩支是唯一真實來源」。

Who：codex、copilot、antigravity、kiro 四支 CLI 的 pre-tool hook 接線修正。
 2026-08-31 19:05:48 +08:00
jiantw83 eebe2a2873 feat(wire-cli): 接上四支 CLI 的 pre-tool hook 
What：
- tools/wire-cli.sh 重寫 codex、copilot、antigravity、kiro 四支的接線、purge、status 與 smoke。
- 新增 hooks/codex-hooks.json，由 hooks/hooks.json 推導產生。
- .codex-plugin/plugin.json 加上 hooks 路徑鍵，指向那份檔案。

Why：這四支其實都有能介入的 pre-tool 事件，原本卻接錯位置，抓到五個同一類的無聲失效——設定看起來正確、CLI 靜默不理、不報錯：
- codex 的 matcher 用 Skill，但 Codex 沒有 Skill 這個工具，技能是模型自己用 Bash 讀 SKILL.md 載入的。
- codex 的 hooks 鍵寫成內嵌物件，實際規格是路徑字串，內嵌物件解析不了。
- antigravity 的 PreToolUse 寫成 Flat，實際要 matcher 加 hooks 包一層的 Grouped。Flat 的那一段整個被丟掉，hook 名稱照樣登記，檔案讀起來還是對的。
- copilot 的設定寫到 $COPILOT_HOME/hooks/，那是 hook 要跑的腳本目錄、不是設定目錄，設定從來不會被讀。
- 三支新接的命令沒帶 JSC_CLI={代號}，閘門認不出自己跑在哪支 CLI 上，一次都擋不下來。

How：
- codex：PreToolUse matcher 換成 Bash。codex-hooks.json 由 hooks/hooks.json 整份複製，再把 matcher 的 Skill 改寫成 Bash，其餘事件原樣保留，Claude 那份維持唯一真實來源，第二份絕不手寫。
- copilot：pre-tool hook 併進 ~/.copilot/settings.json 的頂層 hooks 鍵，matcher 用小寫 skill，事件名只寫一種大小寫。那份檔案同時裝著 enabledPlugins 與 extraKnownMarketplaces，所以合併不覆寫：寫前備份、只動 jsc 自己那幾筆、寫後回讀核對最上層鍵與別人的條目，對不上就還原。指引檔改寫到 $COPILOT_HOME 底下。
- antigravity：寫 ~/.gemini/config/hooks.json 的 jsc 段落。PreToolUse 改成 Grouped、matcher 是錨定的 view_file，錨點不能省，省了會連 view_file_outline 一起命中；另接 Flat 的 PreInvocation，攔斜線指令那條不產生工具呼叫的路。
- kiro：hook 宣告搬到 ~/.kiro/agents/jsc.json 的 hooks 鍵，事件只用 agentSpawn、userPromptSubmit、stop，欄位是 command 與 timeout_ms，並把 settings/cli.json 的 chat.defaultAgent 設成 jsc。kiro-cli agent validate 四種情況一律回 0，所以判準看輸出、不看結束碼。
- 四支非 claude 的接線命令一律以 JSC_CLI={代號} 前綴自帶代號，接線時、status 與 smoke 各斷言一次。
- status 從只驗「鍵在不在」改成驗形狀與位置，並新增第三格 unverified，把「驗不了」跟「驗過了」分開，只有 missing 算缺項。
- smoke 新增 26 條接線形狀斷言，每條正向配一條反向，另把五支 CLI 的真實負載直接餵進 restart-gate.sh，驗解析、判定、輸出整條串得起來。前兩段分開看都會顯示正常，中間接不上照樣是全程放行，那正是先前失效的樣子。

Who：codex、copilot、antigravity、kiro 四支 CLI 的 pre-tool hook 接線修正。
 2026-08-31 19:05:48 +08:00
jiantw83 0e9308f60e feat(hooks): 技能名解析與阻擋輸出共用化 
What：
- 新增 hooks/skill-name.sh。五支 CLI 各一個子命令，從各自的負載解析出這一次要用哪一支 jsc 技能，印一行「{domain}<TAB>{技能名}」。解不出來就印空字串並回 0。
- 新增 hooks/deny.sh。依當前 CLI 產出四種阻擋形態，訊息從參數或標準輸入進。
- version-guard.sh 與 restart-gate.sh 改用這兩支，各自那份工具名判定與技能名取值一併移除。

Why：
- 兩道閘門原本都拿 Claude 的工具名 Skill 當通用條件。另外四支 CLI 的工具名分別是 Bash、skill、view_file，一律被擋在判定之外，兩道閘門在那四支上長期完全失效，而且一聲都不吭。
- 阻擋形態每支 CLI 都不一樣，判定卻是同一件事。各自留一份輸出邏輯，改了一支忘了另一支，就會做出「判定擋下、CLI 照樣放行」的無聲失效。

How：
- 技能名取值規則只留 skill-name.sh 這一份，環境變數 JSC_SKILL、SKILL 優先。claude 讀 skill 欄位、codex 認 tool_input.command 裡那條 SKILL.md 路徑、copilot 先剝一層字串化 JSON 再讀 toolArgs、antigravity 讀 toolCall.args.AbsolutePath 並另收提示字串、kiro 取提示開頭那個斜線指令。
- 閘門端用 awk 判 NF == 2 才取值。少一欄就當成解析不出來，免得沒有定位字元時 cut -f2 把整行當成技能名，拼出一個不存在的技能名去比對豁免清單。
- deny.sh 定形態：claude、codex、copilot 走 stderr 加 exit 2；antigravity 印 stdout 的單行 deny JSON 並固定回 0，因為那支 CLI 的結束碼語意兩邊文件都沒寫、絕不可靠；kiro 擋不下技能叫用，改印警告後回 0；認不得的代號走 stderr 加 2 這個保守預設。
- 訊息整段走同一條管線送進 deny.sh。分次呼叫會做出好幾份 deny JSON，antigravity 只認第一份，後面幾段使用者永遠看不到。
- 豁免清單與 fail-open 原則不變。這兩支刻意以子行程呼叫、不用 source 載入：讀不到只會讓技能名解不出來而安靜放行，不會反過來擋掉每一次呼叫。

Who：codex、copilot、antigravity、kiro 四支 CLI 的 pre-tool hook 接線修正。
 2026-08-31 19:05:48 +08:00
jiantw83 9ccf0d555c Merge pull request '收攏技能行為清單與版本前置檢查相依擋人改動' (#55) from feat/skill-behaviors-and-version-block/main into develop 2026-08-31 08:10:36 +00:00
jiantw83 30c395b4d0 Merge pull request '版本前置檢查新增相依落後擋人、新增技能行為清單' (#54) from feat/skill-behaviors-and-version-block/version-guard-requires-block into feat/skill-behaviors-and-version-block/main 2026-08-31 08:09:21 +00:00
jiantw83andClaude Opus 5 6870975e08 chore(plugin): 三份外掛設定檔版本推進到 0.3.3 
plugin.json、.claude-plugin/plugin.json 與 .codex-plugin/plugin.json
的版本一起從 0.3.2 推到 0.3.3。

這一輪改了版本前置檢查的行為，多擋一種情況。版本不推上去，版本前置檢查
就看不出機器上載入的是舊版，使用者會拿舊的閘門跑新的流程，相依落後
一樣不會被擋下來。

三份設定檔改成同一個版本，避免不同 CLI 讀到不一樣的宣告。

所屬功能：版本前置檢查的相依版本閘門。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-31 13:41:25 +08:00
jiantw83andClaude Opus 5 63c8073be1 docs(references): 新增技能行為清單，作為技能驗證的比對基準 
新增 references/behaviors.md，逐支列出本存取庫 hooks-install 與 repair
兩支技能的行為：觸發時機、關鍵步驟、外部呼叫、完成條件與可驗證跡象。

技能驗證原本沒有一份基準可比。驗的人只能回頭讀技能內文，讀到的是當下的
寫法，不是講好的行為；技能改壞了、少走一道關卡，比對不出來。

一支技能一張表，一項一列，內容寫成看得出對錯的敘述，可驗證跡象逐條指到
磁碟上真的留得下的東西。技能異動時，在同一個 PR 內一起更新這一頁。

所屬功能：技能驗證基準。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-31 13:41:25 +08:00
jiantw83andClaude Opus 5 3485213145 docs(readme): 說明文件同步版本閘門的兩種擋人情況與冒煙沙箱 
比較表的 version-guard.sh 那一列改寫成擋兩種情況，逐項寫明相依版本檢查
讀哪一份 manifest、比哪一個版本、訊息講到什麼程度，也把新增的四種
fail-open 併進原本的放行清單，並註明兩種擋人情況共用同一份 7 項豁免清單。
wire-cli.sh 那一列補一句新的冒煙沙箱與它涵蓋的判定路徑。

文件停在只擋一種情況的舊敘述，讀的人會以為相依落後照樣放行，被擋下來時
找不到規則的出處。冒煙那一列不提新沙箱，維護者也看不出相依版本這一段
已經有斷言守著。

兩種擋人情況、fail-open 清單與共用的豁免清單都寫進表格，清單的唯一真實
來源仍然指向 hooks/version-guard.sh 的檔頭。冒煙那一句只講沙箱與涵蓋範圍，
不抄斷言條數；條數以腳本自己印出來的 lines 那一行為準，散文不另記一份數字。

所屬功能：版本前置檢查的相依版本閘門。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-31 13:41:25 +08:00
jiantw83andClaude Opus 5 15f7dcc5fb test(smoke): 接線腳本冒煙補上相依版本檢查的十三條判定斷言 
接線腳本的 smoke 多一個沙箱，逐條跑相依版本檢查的判定路徑並比對結束碼：
相依落後的擋人與訊息內容、相依相等與超前的放行、豁免技能在相依落後時
照樣放行、同一個 plugin 底下非豁免技能照樣被擋、四種 fail-open、
逃生門蓋過相依落後，另加一條回歸——多行縮排的 manifest，jsc.requires
的最後一個鍵也要解得到。

原本的 hook 模式只驗那支腳本跑得完，相依版本這一段一條判定路徑都沒走到。
新的擋人情況判錯方向，不是把每一次技能呼叫鎖死，就是整道護欄形同虛設，
沒有斷言就看不出來。多行縮排是真實 manifest 的樣子，解析漏掉最後一個鍵
會讓落後的相依靜靜被放行，那一條非釘住不可。

沙箱自備一份暫時的 HOME，註冊檔路徑由 $HOME 決定，不覆寫就會讀到使用者
真正的安裝清單。假的 installed_plugins.json 與各 plugin 的 manifest 都放進
那份 HOME，註冊欄位故意寫成很新的版本、installPath 底下的 manifest 寫舊版，
把「只認 installPath 底下那份檔案」的規則一起釘住。GITEA_HOST 一律清空，
放行的案例才不會往下走到遠端比對真的連網。擋人的兩條另外比訊息字串，
比的是同一次執行留下的輸出。新增計數器 smoke_n_vg 與預期值
SMOKE_EXPECT_VG，一併納入總數、逐類比對訊息與結果摘要，判定路徑增減時
只改腳本裡的預期值。

所屬功能：版本前置檢查的相依版本閘門。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-31 13:41:25 +08:00
jiantw83andClaude Opus 5 5c2727bf56 feat(version-guard): 版本前置檢查新增相依版本落後的擋人情況 
版本前置檢查多一種擋人情況。技能所屬 plugin 的 manifest 在 jsc.requires
宣告的相依 plugin，只要有一項的本機實際載入版本落後宣告的最低版本，
就以 exit 2 擋下這一次技能呼叫。訊息逐項講明哪一個 plugin、需要哪一版、
目前哪一版、怎麼補。

相依宣告原本只有部署那一端會回報，沒有任何一道閘門擋。機器上因此會出現
版本互相搭不起來的 plugin 組合，技能跑到一半才失敗，使用者也看不出要更新
哪一個 plugin。

判定邏輯自己實作，不呼叫 jsc-cli 的 check-requires.sh。hook 一律專屬存放在
jsc-hooks，不可散落到別的 domain；jsc-cli 也已經宣告相依 jsc-hooks，
反向呼叫會做出循環相依。安裝路徑解析抽成 install_path()，與本機載入版本
共用同一條規則，各寫一份就會漂移。相依檢查排在豁免清單與逃生門之後、
遠端比對之前，全部讀本機檔案，離線的機器也判得動。豁免沿用同一份 7 項清單，
相依落後不另立短清單：這幾支同樣是更新與修復的唯一路徑，用哪一個理由擋
都是死鎖。四種情況一律安靜放行：解不出安裝路徑、讀不到 manifest、
manifest 沒有 jsc.requires、讀不到相依 plugin 的本機載入版本。五支 CLI
只有 claude 讀得到本機載入版本，fail-closed 會把另外四支整批鎖死。

所屬功能：版本前置檢查的相依版本閘門。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-31 13:41:25 +08:00
jiantw83andClaude Opus 5 3ae6dba13f fix(smoke): 模型來源判定補上計數器，冒煙預期條數對回實際路徑 
重定基底到 develop 後，冒煙測試併入了 sdlc-gate.sh 取模型代號的四條來源
判定，但那支輸出函式沒有自己的計數器，四個預期值也沒跟著加。結果是實際
印出六十四條結果行、四類計數器只算到六十條，收尾的自我斷言當場判定不符，
smoke 一律以 exit 4 收場。

補上第五個計數器 smoke_n_model 與對應的 SMOKE_EXPECT_MODEL，計數放在該
函式開頭，連建不出暫存目錄那條也算得到；總數、逐類比對訊息與結果摘要一併
納入模型來源這一類。五支 CLI 的 smoke 都回 status=ok，行數與各類條數三邊
一致。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-31 11:26:11 +08:00
jiantw83 99d87f7365 chore(plugin): 推進外掛版本與描述，相依清單補上兩個技能組 
三份外掛設定檔的版本一起往上推，描述加上寫入與提交閘門，
相依清單補上 git 與 meta 兩個技能組。

這一輪新增一支 hook，也改了兩道閘門的行為。版本不推上去，
版本前置檢查就看不出機器上載入的是舊版，使用者會拿舊的閘門跑新的流程。
描述是使用者在市集看到的那一行，少一項就會漏掉新閘門。
寫入閘門擋下整包提交時，改法指向 git 技能組的分組流程；
語言規則的正文則在 meta 技能組。這兩個相依本來就成立，只是先前沒有寫進清單。

三份設定檔改成同一個版本，描述與相依清單三份同步，
避免不同 CLI 讀到不一樣的宣告。
 2026-08-31 11:17:28 +08:00
jiantw83 04225a7a2d docs(hooks): 每支腳本檔頭補上結束碼宣告，文件對齊九支 hook 的現況 
共用函式庫與各支腳本的檔頭各補一段結束碼宣告，逐個子命令寫明哪些情況放行、
哪些情況擋下。說明文件改寫成九支 hook 的現況，補上寫入與提交閘門、唯讀模式、
建議子命令與新的環境變數。異常目錄範本補上「一律附加、不整頁覆蓋」的寫入語意。

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

一支腳本一段檔頭，逐子命令列出結束碼，並各自註明共用函式庫載入失敗會回哪一個碼。
文件的行數一律引用腳本自己印出來的那一行，不另抄一份數字，
判定路徑增減時就不會漂移。覆蓋範圍逐支 CLI 分開寫，接不上的就寫接不上。
 2026-08-31 11:17:28 +08:00
jiantw83 e2b08f04a3 fix(gates): 修好會蓋掉異常目錄、把修復路徑鎖死與誤擋計畫階段的缺陷 
異常回報依 wiki 讀取的結束碼分流，只有頁面確定不存在才套範本建新頁。
版本閘門與重啟閘門的豁免清單各補上 hook 修復技能。
階段閘門把計畫階段移出擋人名單，改成只注入提醒。
錯誤掃描的自家 hook 判定補齊九支腳本，並加一條路徑判定。
修復技能與接線技能的內文改成真的走得到的路徑與真的存在的關卡數。

原本 wiki 讀取失敗會一路落到套範本那一步，金鑰失效或 API 出狀況時，
就拿一份空白範本蓋掉整份異常目錄，而寫入不做合併也不留備份，蓋掉就救不回來。
兩道閘門把唯一的 hook 修復路徑一起擋住，hook 一壞就沒有任何方法修回來，
閘門等於鎖掉解除自己的路徑。工作包閘門擋下計畫階段是誤擋：
計畫是純邏輯階段、不碰程式碼，而閘門只知道有 PR 未合併，判不出跟新計畫有沒有關聯。
自家 hook 判定只認得早期那五支，後來加的四支出錯會被當成第三方的，只回報不修正。
修復技能裡三個指向流程的路徑指到不存在的位置，照著走一定撲空；
接線流程寫四道關卡，實際上有五道，兩段中文說明也混在英文內文裡。

異常目錄改成先讀回舊頁、把新列附在文末、再整頁寫回；讀不回來就放棄寫目錄頁並回報，
寧可少一列索引，也不覆蓋別人的紀錄。兩份豁免清單各補一項，理由逐項寫在腳本檔頭。
計畫階段改印提醒後放行，放棄的在製品上限與代價一併寫在檔頭。
自家 hook 判定逐支列出腳本名，再加一條安裝路徑判定，日後新增 hook 忘了補清單也還認得出來。
三個路徑改指到擁有它的技能組，關卡數改成五道並逐關寫明結束碼，兩段中文說明改回英文。
版本閘門在同一次改動另補唯讀的建議子命令，把版本比對表收斂成一行結論，
部署技能不必自己再解一次那張表。
 2026-08-31 11:15:24 +08:00
jiantw83 b5219f6549 feat(write-guard): 新增寫入與提交閘門，把三條只寫在內文的規則落到程式層 
新增第九支 hook，共四種模式。stage 在計畫與分析階段鎖著時擋下寫檔。
review 在稽核類技能執行中擋下寫檔。commit 擋下「一次加入全部變更再提交」的
單一指令，也擋下含簡體字、亂碼或非 UTF-8 編碼的提交訊息。
release 不接 hook，由稽核技能收尾時自己呼叫，清掉認人用的那份紀錄，
讓呼叫端接手修改時不會被剛跑完的稽核擋住。

這三條規則原本只寫在技能內文，靠模型自律。稽核技能會順手改程式碼，
計畫階段會寫出不該寫的檔案，整包提交會把型別與功能分組壓成一次。
規則要真的生效，就得由程式擋。release 模式是必要的：紀錄記的是最近一次
載入的技能，不是還在跑的技能，沒有它，稽核跑完之後呼叫端每一次寫入都被擋，
閘門會把解除自己的路徑一起鎖掉。

接線設定把 stage 與 review 接在寫檔工具，把 commit 接在指令工具。
閘門只讀階段閘門的狀態鎖與技能用量的紀錄，不自己寫狀態檔；
簡繁與編碼判定整段轉呼叫語言守門，不留第二份字表。
接線腳本的接線、唯讀盤點與冒煙各補上這一支，冒煙自備暫時的狀態目錄，
逐條比對每種模式的結束碼。接線腳本另補唯讀模式，體檢類技能全程帶著它跑，
清除與接線一律拒絕並回非零，子命令打錯一個字也改不到環境。
冒煙改成自己數結果行並自我斷言，散文只引用那一行，不再各抄一份數字。

限制據實寫在檔頭：只有 claude 有寫檔前置鉤子，其餘四支 CLI 一條都接不上，
那四支上這三條規則仍只剩技能內文。
 2026-08-31 11:15:24 +08:00
jiantw83 955a36adb9 fix(codex-hooks): 避免 Claude manifest 在 Codex 變成空路徑 2026-08-28 18:07:20 +08:00
jiantw83 83f6bdf21c fix(model-gate): 支援 Codex 可驗證模型來源 2026-08-28 16:45:58 +08:00
jiantw83 49101fefdb fix(wire-cli): purge 容忍標記行空白 2026-08-28 16:03:25 +08:00
jiantw83 8a1d9d116e feat(manifest): 宣告 hooks 相依版本 2026-08-28 11:59:16 +08:00
jiantw83 4dc879e202 chore(release): 發布 jsc-hooks 0.2.8 2026-08-28 11:22:13 +08:00
jiantw83 4e23e49159 fix(hooks-install): 使用穩定路徑寫入 hook 接線 2026-08-28 11:22:08 +08:00
jiantw83 1477ba7b29 feat(comment-scope): 偵測審查流程痕跡 2026-08-28 09:30:18 +08:00
jiantw83 f6335180fa fix(version-guard): 依 CLI 分離遠端版本快取 2026-08-28 09:30:12 +08:00
jiantw83 0556512ebf chore(hooks): 三份 manifest 版本升到 0.2.6 
What：`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` 的 `version` 從 0.2.5 升到 0.2.6，三份同步，description 不動。

Why：這一輪改掉重啟閘門的狀態檔路徑與範圍，是使用者裝上去就會拿到的行為變更。版本不升，`version-guard.sh` 的版本前置檢查與 `jsc-cli:deploy` 的落後判定都看不出本機還是舊版，機器上就不會被提示更新。

How：只改版號一個欄位。三份必須一致：`plugin.json` 給 marketplace、`.claude-plugin` 給 claude、`.codex-plugin` 給 codex，任一份落後都會讓那一路的版本比對抓錯。修的是既有行為的缺陷、沒有新增子命令也沒有改變呼叫介面，所以走修訂號。

Who：`jsc-hooks` 的三份 plugin manifest，配合這一輪重啟閘門的修正發佈。
 2026-08-27 18:49:58 +08:00
jiantw83 c0c944085c docs(restart-gate): 說明文件同步一支 CLI 一份的狀態檔 
What：`README.md` 改三處——Hooks 表的 `restart-gate.sh` 與 `session-timer.sh` 兩列、覆蓋範圍的引言、以及「部署後重啟狀態檔」整節。整節改寫後寫明狀態檔路徑是 `$JSC_HOME/restart-required.d/{CLI 代號}`、一支 CLI 一份的理由、`report` 的輸出格式，以及舊檔相容與它可移除的時機。`skills/hooks-install/SKILL.md` 第 45 項改為 `restart-required.d/{cli}`，補上「每支 CLI 只讀自己那一份」、「重啟只清自己那一份」、「`report` 一支 CLI 一行」與舊檔過渡說明。

Why：這兩份是接線與判讀閘門時唯一會被讀到的說明。路徑改了而文件沒改，看文件的人會去看一個不存在的檔案，也會沿用「重啟一支就全清」的舊認知去判斷閘門有沒有生效。一支 CLI 一份的理由（並行覆寫與全域解除兩個實測缺陷）要留在文件裡，下一個人才不會為了少一個目錄又改回單一檔案。

How：只改說明，不動任何判定邏輯。路徑與格式的唯一來源仍是 `hooks/restart-gate.sh`，文件只轉述，舊檔相容的取捨與可移除清單也指回檔頭那一節，兩邊不各自維護一份。覆蓋範圍的引言照舊據實寫：非 claude 的四支 CLI 沒有 pre-tool hook，這道閘門一次都擋不下來，改成一支一份也不會變。

Who：`jsc-hooks` 的存取庫說明與 `jsc-hooks:hooks-install` 技能文件，對齊部署後重啟閘門的實作。
 2026-08-27 18:49:58 +08:00
jiantw83 9586e63005 test(restart-gate): 冒煙測試加驗一支 CLI 一份的範圍 
What：`tools/wire-cli.sh` 的 `smoke` 重啟閘門段從 9 條情境擴為 16 條，新增 `smoke_rs_file()` 比對狀態檔在不在。新增的情境是：只有別支 CLI 有狀態檔時放行、`require` 寫出的是當前 CLI 那一份、新工作階段開始後只清掉自己那一份、清除不動別支那一份、清除後放行、舊格式單一狀態檔存在時擋下、`clear` 一併刪掉舊檔、舊檔清除後放行。原有的豁免技能、逃生門與取不到技能名三類情境照舊，情境名稱從「狀態檔存在」改寫為「當前 CLI 那份存在」。檔頭的判定路徑清單同步改寫。

Why：只比對結束碼看不出「一支 CLI 一份」有沒有真的成立——別支那一份要留著、自己那一份要刪掉，兩件事都反映在檔案在不在，不反映在結束碼。舊版的冒煙只驗得到「狀態檔不存在」與「狀態檔存在」兩條，正好漏掉這次修掉的兩個缺陷所在的範圍：並行部署的覆寫與清除的全域解除，兩者在單一檔案的年代都跑得出 exit 0 與 exit 2 的正確值。

How：情境沿用暫時的 `$JSC_HOME`，不動使用者真正的狀態目錄——冒煙測試不該把別人的閘門拆掉。別支 CLI 的代號取 `smoke-other` 這個不在五支之列的固定值，才不會跟這一輪的 `$cli` 撞在一起。`smoke_rs_file()` 只比 `exist` 與 `absent` 兩種預期，失敗訊息直接講明「一支 CLI 一份的範圍壞了」，看訊息就知道是範圍出錯，不是腳本跑不動。舊檔那兩條情境走 `session-timer.sh restart` 觸發清除，跟真實路徑一致。

Who：`jsc-hooks` 接線工具的冒煙測試，覆蓋部署後重啟閘門的判定與清除範圍。
 2026-08-27 18:49:58 +08:00
jiantw83 7517566156 fix(restart-gate): 重啟閘門狀態檔改為一支 CLI 一份 
What：`hooks/restart-gate.sh` 的狀態檔從全機器單一檔案 `$JSC_HOME/restart-required` 改為狀態目錄 `$JSC_HOME/restart-required.d/{CLI 代號}`，一支 CLI 一份，檔名就是 CLI 代號，四行 key=value 的格式不變。新增 `cli_code()` 取當前 CLI 代號（含不能當檔名的髒值防護）與 `state_line()` 統一 `report` 的輸出格式；`require` 只寫自己那一份、hook 判定只讀自己那一份、`clear` 只刪自己那一份、`report` 一支 CLI 一行印出還沒重啟的是哪幾支。舊格式的單一檔案存在時一律擋，訊息標明是舊格式紀錄，`clear` 會一併刪掉它。檔頭註解同步改寫，新增「report 輸出格式」與「舊檔相容（過渡用）」兩節。`hooks/session-timer.sh` 程式碼不動，兩處註解補上「清除範圍只有跑到這支腳本的那一支 CLI」。

Why：這道閘門 2026-08-27 才上線，部署現場實測抓到兩個缺陷。第一，`require` 用 `>` 覆寫單一檔案，並行部署互相覆蓋——kiro 寫入 9 秒後被 codex 蓋掉，`domains=` 與 `cli=` 不再代表 kiro。第二，`clear` 用 `rm -f` 刪整個檔案，任一支 CLI 重啟就解除全部五支的閘門，其餘四支沒重啟卻不再被擋。這台機器就裝了五支 CLI，閘門在多 CLI 環境等於半失效。閘門管的是「這一支 CLI 的行程還在跑舊版」，那是每支 CLI 各自的事實，狀態檔本來就不該共用。

How：寫入、判定、清除三件事都只碰自己那一份，別支那幾份一律不看，`clear` 的範圍也就收斂成呼叫端那一支。取不到 CLI 代號時比照既有的「查不到就放行」原則：hook 模式放行，`require` 回 exit 2 並講明這次沒有掛上閘門——寫到讀不到的檔名等於沒掛，不能讓部署以為掛上了。代號會直接拿去當檔名，所以含 `/`、以 `.` 開頭、或出現 `[A-Za-z0-9._-]` 以外字元的值一律當成取不到，狀態檔就寫不到目錄外面去。舊檔沒有 per-CLI 資訊，分不出是哪一支寫的，判定寧可擋多不擋少；`clear` 只在新工作階段被呼叫，呼叫到就代表確實有一支重新啟動過了，舊檔留著會讓五支一路被擋到有人手動刪，所以一併刪掉。這段相容邏輯與可移除的時機（所有機器都跑過一次寫狀態目錄的部署與重啟之後）寫在檔頭「舊檔相容」與 README。`session-timer.sh` 不必跟著改：狀態檔的路徑、範圍與格式只留在 `restart-gate.sh`，那裡只負責判斷新舊工作階段。

Who：`jsc-hooks` 的部署後強制重啟閘門（R15），以及它與 `session-timer.sh` 的清除分工。
 2026-08-27 18:49:58 +08:00
jiantw83 7d67538a2a docs(hooks-install): 豁免清單補齊為九支，與實作和準則對齊 
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` 技能文件，以及部署後重啟閘門這條規則的說明一致性。
 2026-08-27 16:49:02 +08:00
jiantw83 4f92c48e10 chore(manifest): 三份 manifest 版本升到 0.2.4，描述補齊八支 hook 
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` 外掛的套件描述檔。
 2026-08-27 16:34:17 +08:00
jiantw83 c1f2a5d728 docs(hooks): README 與 AGENTS 補上部署後重啟閘門與狀態檔格式 
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` 的人。
 2026-08-27 16:34:17 +08:00
jiantw83 7f8615a9ed feat(hooks-install): 技能同步到八支 hook 與重啟閘門的降級說法 
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` 的接線流程與對使用者的回報。
 2026-08-27 16:34:17 +08:00
jiantw83 e370729720 feat(wire-cli): 接線腳本納入部署後重啟閘門，七支改八支 
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` 這個子命令能不能刪檔」。每次呼叫都接 `</dev/null`：hook 模式會讀標準輸入，管線沒人關閉時整支會卡死。建不出暫存目錄也算失敗，不能靜悄悄跳過。四支非 claude 的 CLI 除了 degraded 一句，另外逐支印一行講明後果：一次技能呼叫都擋不下來，狀態檔照樣寫、下次工作階段開始照樣清，只是中間沒有判定點，重啟要靠 `/jsc-cli:deploy` 收尾的提示自己動手。

Who：`jsc-hooks:hooks-install` 的接線、冒煙與盤點三個子命令。
 2026-08-27 16:34:17 +08:00
jiantw83 dbf9aac25e feat(restart-gate): 新增部署後強制重啟閘門，並接上新工作階段自動清除 
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`，理由與 `sdlc-gate.sh` 相同。接線排在 `version-guard.sh` 前面：還沒重啟的舊版比落後一個版號更該先攔。不認得的子命令一律安靜 exit 0，不中斷宿主 CLI。擋人訊息依實際 CLI 給重啟方式，並附上豁免清單與逃生門 `JSC_RESTART_GATE=off`。

Who：部署後的第一次技能呼叫，以及 `jsc-cli:deploy` 收尾寫入狀態檔的那一端。
 2026-08-27 16:34:17 +08:00
jiantw83 e714c6ade2 Merge pull request 'feat(hooks): 工作包閘門加上歸屬比對與領取、交回子指令' (#31) from feat/sdlc-flow-rules/main into develop 2026-08-27 03:39:37 +00:00
jiantw83 be75cc4bed chore(manifest): 三份 manifest 版本升到 0.2.3 
What：`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` 的 `version` 由 0.2.2 改為 0.2.3。

Why：本次新增 `wp-claim`、`wp-unclaim` 兩個子命令並改了鎖檔格式，屬於行為變更，版本要跟著往上走，各 CLI 才知道要更新。

How：三份只改 `version` 一個欄位，其餘內容不動，三份保持同一版號。

Who：`jsc-hooks` 外掛的套件描述檔。
 2026-08-27 11:20:28 +08:00
jiantw83 29facd385c docs(hooks): README 補上工作包歸屬狀態檔格式 
What：README 新增「工作包歸屬狀態檔」一節，用表列出鎖檔與領取檔的檔名、欄位與範例，寫明誰寫誰讀、查無歸屬一律放行、舊版 TSV 鎖檔照樣讀得動；`sdlc-gate.sh` 與 `wire-cli.sh` 兩列的說明同步補上新子命令與冒煙測試的新內容。

Why：狀態檔的格式是 `jsc-hooks` 與 `jsc-sdlc` 兩邊的介面。介面只寫在腳本註解裡，另一邊改的時候看不到，格式一走鐘歸屬就全部誤判。

How：格式壓到最簡的純文字 `key=value`，一行一欄位，順序不拘，不認得的鍵一律忽略，兩邊各自實作也對得上。表只寫欄位與範例，判定規則寫在表底下的三段短說明。

Who：讀 `jsc-hooks` 說明的人，以及 `jsc-sdlc` 那一側寫 `wp-gate.sh` 的人。
 2026-08-27 11:20:28 +08:00
jiantw83 3b6dd1b901 test(wire-cli): 冒煙測試補驗工作包歸屬的四條判定路徑 
What：`tools/wire-cli.sh` 的 `smoke` 新增一段，用一份暫時的 `$JSC_HOME` 狀態檔把「狀態檔不存在」「PR 屬於領取中的工作包」「PR 屬於別的工作包」「逃生門 `JSC_WP_GATE=off`」四種情境各跑一次，逐一比對結束碼；收尾那句 `status=ok` 的說明也跟著補上這一段。

Why：原本兩支 `wp-check` 冒煙都把技能名清空，只走得到「沒有未結清 PR」與「取不到技能名」兩條捷徑，歸屬比對整段一次都沒跑到。判定寫了卻沒驗，等於沒寫。

How：驗的是判定結果本身，不只是腳本跑得完——每一種情境都給定預期結束碼，對不上就計入失敗並印出前 200 字的輸出。狀態檔放在暫時目錄，冒煙測試不該在使用者真正的 `$JSC_HOME/wp/` 留下痕跡。每次呼叫都接 `</dev/null`：`wp-check` 會讀標準輸入，管線沒人關閉時整支會卡死。建不出暫存目錄也算失敗，不能靜悄悄跳過。

Who：`jsc-hooks:hooks-install` 接線後跑的冒煙測試，以及改動 `sdlc-gate.sh` 歸屬判定的人。
 2026-08-27 11:20:28 +08:00
jiantw83 870f52fbaa feat(sdlc-gate): 工作包閘門加上歸屬比對與領取紀錄 
What：`hooks/sdlc-gate.sh` 新增 `wp-claim {owner}/{repo} {工作包代號} [{PR 編號}] [{分析頁}]` 與 `wp-unclaim {owner}/{repo}` 兩個子命令，`wp-lock` 新增第四個參數收工作包代號，鎖檔改為純文字 `key=value`，`wp-report` 多印第四欄工作包代號。`wp-check` 逐筆判歸屬：`prompt` 多注入一行點名不屬於這裡的 PR，`skill` 擋下 `plan`、`analyze`、`maintain` 時一併點名，`implement` 仍放行但收到同一則提醒。

Why：同一份分析常有好幾包平行進行，每包各自的 worktree 與 PR。原本的鎖檔只記存取庫與 PR 編號，看不出那支 PR 是誰的，於是任何一個工作階段都可能去改別包的程式碼、回別包的留言。

How：歸屬只比一件事——鎖檔的 `wp` 與同一個存取庫領取檔的 `wp` 取數字比一次，兩邊都有值且不相等就是別包的。`WP-03`、`WP-3`、`3` 先正規化再比，不然同一包的幾種寫法會被當成不同包。任何一邊查不到（沒有分析頁、沒寫代號、領取檔不存在）一律當查無歸屬並放行，理由與 `version-guard.sh` 一致：只擋確定違規，否則會把技能組維護自己鎖死。舊版單行 TSV 鎖檔照樣讀得動，讀出來是查無歸屬，換格式不會讓既有的鎖失效。`implement` 一律放行，連別包的 PR 未結清也放行——結清 PR 正是 `implement` 的步驟，擋它會把流程鎖死。分類迴圈用 here-document 餵資料而不用管線，管線右邊是子 shell，判到的違規會在迴圈結束時全部消失。

Who：跑 SDLC 實作階段的每個工作階段，以及 `jsc-sdlc/tools/wp-gate.sh` 的 `claim`、`lock` 與 `owns`。
 2026-08-27 11:20:28 +08:00
jiantw83 667b60c8e9 feat(manifest): 三份 manifest 版本升到 0.2.2 
What：三份 manifest 由 0.2.1 升到 0.2.2。

Why：字表擴充後偵測能力大幅改變，本機沒跟著升版，version-guard.sh 就判不出落後，
使用者不會收到更新提示，繼續用覆蓋率只有兩成的舊字表。

How：以 jsc-meta 的 sync-skill-manifest.sh 統一 bump，三份同步成同一個值。

Who：非程式碼輸出的繁中無亂碼檢查。
 2026-08-27 09:53:55 +08:00
jiantw83 75fba4715c feat(simplified): 字表擴充到 1006 字並補齊跳過清單 
What：簡體字表由 102 字擴充到 1006 字；lang-guard.sh 的跳過清單補上
jsc-meta 的 references/ste100.md 與 tools/ste100-lint.sh。

Why：102 字的舊表覆蓋率太低——拿 21 個常見簡體詞實測只抓到 4 個，「简体字」
「举办」「觉得」「战争」「医药」這類全部漏掉，規則等於形同虛設。跳過清單則是
對稱性問題：規則文件與機檢工具本身會列舉簡體字當範例，不跳過就每次先抓到自己。

How：字表逐字檢查「簡化後才出現的字形」，剔除正體也在用的字（后、台、干、只、
里、面、制、志、出、斗、丑、了、卷、咸、云、留、言、短、困、陷、游、封、吞），
再拿 jsc 全部 11 個存取庫共 221 個檔案的既有正體中文語料回歸驗證，誤報為零。
檔頭寫明排除原則與「改完必須拿語料重驗」的要求。跳過清單比照 ste100-lint.sh 的做法。

Who：非程式碼輸出的繁中無亂碼檢查。
 2026-08-27 09:53:55 +08:00
jiantw83 aee2f19699 feat(manifest): 三份 manifest 版本升到 0.2.1 
What：把 `plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` 三份 manifest 的版本由 0.2.0 升到 0.2.1。

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

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

Who：繁中與編碼檢查 hook 的跨 CLI 支援。
 2026-08-27 09:50:03 +08:00
jiantw83 fe3c5723a5 feat(hooks-install): 文件同步到七支 hook 
What：`README.md` 的 hook 一覽表新增 `lang-guard.sh` 一列（事件、三種模式、逃生門），所有「六支 hook」改七支，環境變數表補 `JSC_LANG_GUARD`，`tools/jsc-wrap.sh` 那列補收尾 sweep；`skills/hooks-install/SKILL.md` 六支改七支並補覆蓋範圍與備註，`description` 的括號清單加上這支；`AGENTS.md` 清單同步，並新增一條繁中無亂碼規則。

Why：文件寫六支、實際跑七支，使用者與 sub agent 都會照文件辦事，少接的那一支永遠沒有人發現。`AGENTS.md` 是各 CLI 讀得到的規則檔，新規則不寫進去就只剩 hook 在擋，模型自己不會知道。

How：README 維持 STE100 繁中；SKILL.md 維持整份英文，`description` 保持 4 句、保留觸發時機。規則正文一律不在本存取庫留副本，只指向 `jsc-meta` 的 `references/ste100.md`，字表位置指向 `hooks/simplified.txt`。

Who：`jsc-hooks` 的文件層，讀者是使用者與執行 `hooks-install` 的 sub agent。
 2026-08-27 09:50:03 +08:00
jiantw83 bbad6566f7 feat(wire-cli): 把 lang-guard.sh 接到五個 CLI 的既有時機 
What：`hooks/hooks.json` 的 `UserPromptSubmit` 加 `lang-guard.sh prompt`、`PostToolUse` 的 `Write|Edit|MultiEdit` 加無參數模式；`tools/wire-cli.sh` 把 codex 的 `notify`、kiro 的 `userPromptSubmit` 串上 sweep，規則檔文字加上 `lang-guard.sh prompt` 的輸出，`smoke` 三種模式各跑一輪，`status` 補盤點項，寫入後驗證一併涵蓋；`tools/jsc-wrap.sh` 收尾再跑一次 sweep；`hooks/ste100-guard.sh` 的注入文字補上適用範圍與 UTF-8 無亂碼。

Why：hook 寫好了不接線等於沒寫。接的位置與 `comment-scope.sh` 完全一樣，因為兩支要解的是同一個問題——只有 claude 有 post-tool hook，其餘四個 CLI 拿不到「剛剛寫了哪個檔」，只能改掃整個工作區。各 CLI 的掃描時機本來就不同：claude 逐檔即時、codex 每輪結束、kiro 每輪提示送出時、copilot 與 antigravity 只有工作階段結束，回報時不能寫成五支一樣。

How：規則檔文字取 `lang-guard.sh prompt` 的實際輸出，不在接線腳本裡抄一份規則，抄了兩邊就會各自漂移。寫入後以 `has_lang_guard()` 比對腳本第一行實際輸出，確認規則檔真的收到那一段。`smoke` 沿用既有的 exit 2 例外：掃描模式掃到違規回 2 是設計行為，不是執行期錯誤。`jsc-wrap.sh` 的 sweep 一律加 `|| true`，包裝器原樣回傳 CLI 自己的結束碼——包裝器改掉結束碼，呼叫端的 `cmd && next` 就會誤判。

Who：`jsc-hooks` 的接線層，由 `hooks-install` 技能對 claude、codex、copilot、antigravity、kiro 五個 CLI 執行。
 2026-08-27 09:50:03 +08:00
jiantw83 e3a9c67781 feat(lang-guard): 新增第七支 hook，強制非程式碼輸出繁中無亂碼 
What：新增 `hooks/lang-guard.sh` 與機檢字表 `hooks/simplified.txt`。腳本比照 `comment-scope.sh` 的結構，一樣三種模式：`prompt` 注入規則摘要、無參數掃剛寫入的單一檔案、`sweep [dir]` 掃整個 git 工作區這次改過的檔案。偵測三項：簡體字、亂碼（U+FFFD 與雙重編碼殘骸）、非 UTF-8 編碼。命中走 stderr 並 exit 2，資料不足或找不到 git 一律安靜 exit 0，逃生門 `JSC_LANG_GUARD=off`。

Why：使用者新增的規則是「非程式碼的輸出一律套用繁中無亂碼」，範圍涵蓋程式碼註解、commit 訊息、PR 描述、wiki 頁、對使用者的回報與各種文件。這條規則原本只有 `ste100-guard.sh` 的提示層，模型看得到卻沒有人檢查，寫出簡體字或亂碼不會有任何回饋。提示層擋不住的事，就要有機檢層。

How：簡體字樣式由字表組出，字表是單一真實來源，腳本裡不留第二份；字表讀不到就安靜跳過這一項，不中斷整支腳本。亂碼一律用位元組比對（`LC_ALL=C`），不靠語系的字元範圍，因為 `grep -E` 的字元範圍在不同語系下行為不一致。掃描深度沿用 `comment-scope.sh`：檔案已追蹤就只掃 `git diff HEAD` 的新增行，不翻舊帳。二進位檔只認 NUL 位元組判定，不拿「非可列印字元」當判準，那會把所有含中文的檔案誤判成二進位。字表刻意排除繁體也在用的字（后、台、干、只、里、面、制、志），並跳過 `simplified.txt`、`ste100-guard.sh`、`lang-guard.sh` 三份以簡體字與亂碼為討論對象的檔案，避免整支 hook 每次先抓到自己。

Who：`jsc-hooks` 的 hook 實作層，供 `hooks/hooks.json` 與 `tools/wire-cli.sh` 接線給五個 CLI 使用。
 2026-08-27 09:50:03 +08:00
jiantw83 542f0aab2c feat(manifest): 三份 manifest 版本升到 0.2.0 
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 支援。
 2026-08-27 09:20:44 +08:00
jiantw83 b23c546079 docs(hooks-install): 據實寫明各 CLI 的註解範圍掃描時機 
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 依循。
 2026-08-27 09:16:32 +08:00
jiantw83 0bebdef46f feat(wire-cli): 把 comment-scope sweep 接到其餘四個 CLI 
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 的使用者。
 2026-08-27 09:16:15 +08:00
jiantw83 8ede74e9e2 feat(comment-scope): 新增 sweep 模式，掃整個 git 工作區 
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 使用。
 2026-08-27 09:15:56 +08:00
jiantw83 7690b697c7 feat(manifest): 三份 manifest 版本升到 0.1.9 
What：`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` 三份 manifest 的 `version` 由 0.1.8 升到 0.1.9。

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

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

Who：`jsc-hooks` 的發佈中繼資料，供 `hooks/version-guard.sh` 與 `jsc-cli:deploy` 比對版本。
 2026-08-26 19:01:36 +08:00
jiantw83 5d60e0f231 feat(hooks-install): 文件同步六支 hook 與降級說明 
What：`skills/hooks-install/SKILL.md`、`README.md`、`AGENTS.md` 三份文件一併改口徑為六支 hook，補上 `comment-scope.sh` 的職責、兩種模式、環境變數 `JSC_COMMENT_SCOPE` 與 `JSC_CHANGED_FILE`，以及各 CLI 的覆蓋範圍差異。

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

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

Who：`jsc-hooks` 的文件層與 `hooks-install` 技能，供操作者與後續 sub agent 依循。
 2026-08-26 19:01:36 +08:00
jiantw83 e2232d26f1 feat(wire-cli): 接線腳本納入註解範圍 hook，五支改六支 
What：`tools/wire-cli.sh` 新增 `comment_scope_text()`、`rules_text()` 與 `has_comment_scope()` 三個函式，把 `comment-scope.sh` 的 `prompt` 模式接進 codex、copilot、antigravity 的規則檔與 kiro 的 hook JSON，`smoke` 與 `status` 兩個子命令也補上這支 hook，全腳本由五支 hook 改口徑為六支。

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

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

Who：`jsc-hooks` 的接線工具層，供 `jsc-hooks:hooks-install` 與 `jsc-hooks:repair` 呼叫。
 2026-08-26 19:01:36 +08:00
jiantw83 f81ceaf145 feat(comment-scope): 新增註解範圍檢查 hook 並接進 claude 的 hooks.json 
What：新增第六支 hook `hooks/comment-scope.sh`，並在 `hooks/hooks.json` 補上兩個接線點：UserPromptSubmit 走 `prompt` 模式、PostToolUse 的 `Write|Edit|MultiEdit` 走掃描模式。

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

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

Who：`jsc-hooks` 的 hook 層，服務 `jsc-hooks:hooks-install` 的接線流程與 `jsc-review:code-review` 的註解契約檢查。
 2026-08-26 19:01:36 +08:00
jiantw83 961af918bf chore(gitignore): 忽略本機接線檔目錄 .kiro/ 
What：在 .gitignore 的暫存分類底下新增 .kiro/ 一行，讓該目錄維持不追蹤。

Why：.kiro/ 是 jsc-hooks:hooks-install 在本機產生的接線檔，內容含本機絕對路徑。這種檔案因人而異，提交進存取庫會讓別人拉到錯的路徑，也會每次接線就冒出雜訊變更。

How：於 .gitignore 加上獨立註解區塊與 .kiro/ 樣式，只忽略不刪檔；本機既有目錄原地保留，git status 不再列出。

Who：hooks 存取庫的版本控管設定，配合 jsc-hooks:hooks-install 的接線產出。
 2026-08-26 18:40:11 +08:00
jiantw83 0c83495ba8 fix(version-guard): 把 jsc-ask:ask 與 jsc-gitea:wiki 加進豁免清單 
What：版本守門 hook 的豁免清單新增 jsc-ask:ask 與 jsc-gitea:wiki 兩支技能，並在檔頭註解補上理由。

Why：jsc-cli:deploy 要問使用者 install/update/uninstall，一定會呼叫 jsc-ask:ask；ask 問完又一定寫回 wiki 才算完成。這兩支只要版本落後就被擋下，訊息還指回 /jsc-cli:deploy，deploy 卡在問不出模式那一步，形成死鎖，跟直接擋 deploy 是同一種問題。

How：在 case "$skill" 的豁免比對加上 jsc-ask:ask 與 jsc-gitea:wiki 兩個樣式，維持原本 exit 0 的略過行為；檔頭豁免清單註解同步補上兩條說明，講清楚死鎖成因。

Who：hooks/version-guard.sh 的外掛版本守門功能，影響 jsc-cli:deploy 的部署流程。
 2026-08-26 18:40:11 +08:00
jiantw83 221742486b fix(sdlc-gate): 工作包鎖檔改依索引區分，避免平行工作包互相覆蓋並修正提示文字 2026-08-26 17:59:21 +08:00
jiantw83 f1bcdc3d72 feat(wire-cli): 新增唯讀的接線盤點子命令 
What: wire-cli.sh 新增 status 子命令，只讀設定檔判斷 jsc 標記段落在不在，不寫檔也不執行 hook。每個接線點印一行 item，以 status=wired、degraded、unwired、skipped 回報。
Why: 體檢類技能要問「hook 接線在不在」，但既有三個子命令都會動到環境：不帶子命令會重新接線、purge 會刪掉、smoke 會真的執行 hook。體檢不該有副作用。
How: 沿用底下接線區塊的同一組檔案位置與標記字串，共用 has_block、toml_root_key、json_top_key 三個判讀函式。codex 的 notify 另外單獨檢查是否落在根層，標記在、鍵被歸進表裡時 codex 讀不到，等同沒接。
Who: 供 jsc-cli:doctor 呼叫的接線檢查。
 2026-08-26 10:44:47 +08:00
jiantw83 65d3c13d22 chore(hooks): 三份 manifest 同步升版到 0.1.7 2026-08-25 18:59:29 +08:00
jiantw83 26a5a4690d docs(hooks): 補上工作包 PR 閘門的 hook 說明與逃生門 2026-08-25 18:59:29 +08:00
jiantw83 b9ad321930 feat(sdlc-gate): 新增工作包 PR 閘門，未結清就擋下別的階段技能 2026-08-25 18:59:29 +08:00
jiantw83 e62511b57f chore(hooks): 三份 manifest 同步升版到 0.1.6 2026-08-25 18:18:10 +08:00
jiantw83 6ecb7d0387 docs(hooks): 同步 purge、smoke 與錯誤掃描的工具與技能說明 2026-08-25 18:18:10 +08:00
jiantw83 b45a98af87 feat(hooks-install): 安裝改為先清空所有 hook 再接線並驗執行期 2026-08-25 18:18:10 +08:00
jiantw83 ad2f944a66 fix(hooks): 修正版本號為單位數格式 2026-08-25 16:39:49 +08:00
jiantw83 c68292acbc feat(hooks): 自動接手失敗接線與修復流程 2026-08-25 16:33:38 +08:00
jiantw83andClaude Opus 5 2982ca4e9f chore(hooks): 三份 manifest 同步升版並同步 marketplace 正本 
What：三份 plugin manifest 版本同步 bump，兩份 marketplace 檔與 plugins/meta 正本對齊。

Why：準則要求技能異動必須同步升版；marketplace 副本必須與正本完全一致。

How：以 jsc-meta 的 tools/sync-skill-manifest.sh 升版，marketplace 檔由正本複製。

Who：jsc-meta:skill-check 例行稽核（2026-08-25）。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-25 14:58:54 +08:00
jiantw83andClaude Opus 5 83170e1b43 docs(hooks): 同步文件與參考資料 
What：更新 README、AGENTS.md、templates 與 references，讓文件敘述與實際行為一致。

Why：稽核發現多處文件與程式行為分歧，違反「每個意義只有單一真實來源」。

How：以實際程式行為為準改寫敘述，重複的規則收成單一來源並以一行指引指過去。

Who：jsc-meta:skill-check 例行稽核（2026-08-25）。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-25 14:58:54 +08:00
jiantw83andClaude Opus 5 fedcfc8b05 fix(hooks): 補齊稽核缺失並修掉護欄失效 
What：依 jsc-meta:skill-check 的稽核結果修正技能與工具——補上每個步驟的可檢核完成條件、
把留在內文的標準輸入輸出流程下放 tools/、修正查表與退碼路由造成的誤判。

Why：稽核發現這些缺失會讓技能在實際執行時走錯分支或靜默通過。
完成條件缺漏是最常被違反的一項；退碼誤判與查表錯誤則會讓良性狀況被當成失敗。

How：逐項對照 references/guidelines.md 的審核檢查清單修正，新增的工具都有
documented exit codes，並以真實執行驗證每條路徑。

Who：jsc-meta:skill-check 例行稽核（2026-08-25）。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-08-25 14:58:54 +08:00
jiantw83andClaude Opus 5 99f5747b9e chore(plugin 版本): 三份 manifest 升版至 0.0.9 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-25 13:03:17 +08:00
jiantw83andClaude Opus 5 8a8e455c87 docs(README): 補上 version-guard report 的用途說明 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-25 13:03:17 +08:00
jiantw83andClaude Opus 5 2736555a75 feat(version-guard): 新增 report 子指令，一次比對所有 plugin 的本機與已發佈版本 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-25 13:03:17 +08:00
jiantw83andClaude Opus 5 3b0c8f0e33 chore(plugin 版本): 三份 manifest 升版至 0.0.8 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-25 11:52:38 +08:00
jiantw83andClaude Opus 5 922a95f147 docs(README): 補上 version-guard 與其環境變數說明 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-25 11:52:38 +08:00