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

行為清單那一節四列兩邊都改過，但改的是不同層面：分支改「目錄頁怎麼寫」——索引
從表格列變成一個報告一個大標題區塊、寫入語意委派給共用工具；develop 改「根目錄
怎麼解」——前置步驟解出兩條字面絕對路徑再拿去叫工具。逐列用差異區間比對過，
兩邊在共同基底上動到的位置完全不重疊，所以照基底的座標把兩組改動一起套回去，
不是取其中一邊。

技能本文那一段同理：分支把整段改寫成區塊語意，develop 只在指令路徑前面補了
根目錄前綴。取分支那一版再補上前綴。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-07 09:10:57 +08:00
admin 27a3865e87 Merge pull request 'status 加 --verdict，把狀態與成敗兩種語意分開' (#86) from feat/wire-cli-status-verdict-flag into develop 
Reviewed-on: #86
 2026-09-04 10:09:51 +00: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
admin 8e37ab3191 Merge pull request '共用函式庫補上 stdin JSON 的載入期預設值，四條收尾路徑不再吐未設定訊息' (#84) from fix/stdin-json-default-in-shared-lib into develop 
Reviewed-on: #84
 2026-09-03 05:35:21 +00: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
admin 2704a7fa8f Merge pull request '跨外掛路徑改實體解析，修好失效的版本閘門，並讓接線腳本不再可能把連結指向自己' (#82) from fix/physical-path-resolution-across-plugins into develop 
Reviewed-on: #82
 2026-09-03 04:40:20 +00: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
admin f0fd92eb33 Merge pull request 'hooks-install 的腳本呼叫改用執行期解出的字面絕對路徑，讓無人看管的輪次不再卡在第一支腳本' (#80) from fix/literal-absolute-paths-for-hooks-wiring into develop 
Reviewed-on: #80
 2026-09-03 02:52:04 +00: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 bd1a705ea8 chore(plugin 版本): 三份 manifest 升版至 0.4.2 
What：
三份 plugin manifest 的版號由 0.4.1 同步升到 0.4.2，README 的技能目錄確認沒有新增或移除小節。

Why：
版本閘門比對相依版本時看的是 manifest 版號。改了內容卻不升版，安裝端拿到新檔案卻還是舊版判定，落後的一方擋不下來。

How：
以 jsc-meta 的技能清單同步工具一次改三份，結束碼 0，避免三份版號各自手改而對不起來。

Who：
安裝或更新 jsc 技能組的操作者。
 2026-09-02 18:02:20 +08:00
jiantw83 02caedf91e feat(異常目錄頁): 索引改成 H2 區塊條列並委派共用工具 
What：
異常目錄頁的版面從 markdown 表格改成一筆異常一個 H2 區塊，標題就是那一筆的異常頁頁名，時間、頁名、存取庫名稱、觸發 hook、退出碼、摘要六個欄位改成標題底下的一層條列，頁上不再留任何表格。失敗回報腳本不再自己讀回舊頁、附加新列、整頁寫回，改成只組出自己那一個區塊，交給 jsc-gitea 的目錄頁工具做讀回、比對與整頁寫回。範本、技能敘述、行為清單與說明文件一併對齊。

Why：
目錄頁有十幾份，各自在自己的腳本裡寫一套「讀得回舊內容才寫」的判斷，錯一次就少一筆紀錄，而且每一頁長出來的樣子都不一樣。版面與寫入語意收回一份正本之後，改一次全部跟著改。表格欄位遇到換行或半形豎線還會被切斷，條列沒有這個問題。

How：
失敗回報腳本移除目錄專用存取庫的解析與整頁組裝，改為組出區塊檔之後呼叫共用工具的 upsert，並依它的結束碼分流：3 是目錄頁的存取庫沒設定，找不到那支腳本也走同一條，兩者都只寫異常頁、跳過目錄頁、仍回 0；其餘非零一律以 4 回報。摘要不再替換半形豎線，改成把換行併成一行。傳進去的欄位序號 2 指舊表格版持有內容頁連結的那一欄，只供舊頁自動轉條列時取標題用。

Who：
使用 jsc-hooks 失敗回報流程的操作者，以及所有讀異常目錄頁追問題的人。
 2026-09-02 18:01:33 +08:00
admin 9adb39d21a Merge pull request '技能與 hook 的執行結果寫進本機事件流，供助理排空' (#77) from feat/status-event-stream into develop 
Reviewed-on: #77
 2026-09-02 07:48:47 +00: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
admin 97c56212df Merge pull request '接線盤點列舉每一個接線點，模型能力鎖不再被誤判成沒接線' (#76) from fix/wire-status-itemize-all-hooks into develop 
Reviewed-on: #76
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>
 2026-09-02 07:32:01 +00: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
admin 56aa3e832f Merge pull request '連結一律寫成 [文字](絕對網址)，並在寫入前驗證連得到' (#75) from feat/link-verification/main into develop 
Reviewed-on: #75
 2026-09-02 06:46:41 +00: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
admin 2a6097528a Merge pull request 'feat(wiki): 異常目錄頁改走專用存取庫，並修正目錄列連結恆空' (#73) from feat/wiki-contents-repo/main into develop 
Reviewed-on: #73
 2026-09-02 04:20:18 +00: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
admin ccbf0b8ef7 Merge pull request '能力閘門依 CLI 分流並隔離狀態檔，判不出能力一律擋下' (#72) from fix/sdlc-gate-cli-isolation into develop 
Reviewed-on: #72
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>
 2026-09-02 03:11:42 +00: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
admin 49c9009090 Merge pull request '釋出助理心跳與運行閘門（閘門未接線）' (#69) from feat/assistant-gate-and-heartbeat/main into develop 
Reviewed-on: #69
 2026-09-01 07:41:19 +00:00
admin 730f21a0e8 Merge pull request 'feat/assistant-gate-and-heartbeat/heartbeat' (#68) from feat/assistant-gate-and-heartbeat/heartbeat into feat/assistant-gate-and-heartbeat/main 
Reviewed-on: #68
 2026-09-01 07:24:22 +00: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
admin 9de64ead7e Merge pull request '放行 jsc-assist 的 marketplace 條目到預設分支' (#66) from chore/marketplace-assist-registry/main into develop 
Reviewed-on: #66
 2026-09-01 04:55:20 +00:00
admin 59844c0a18 Merge pull request 'chore/marketplace-assist-registry/sync-copies' (#65) from chore/marketplace-assist-registry/sync-copies into chore/marketplace-assist-registry/main 
Reviewed-on: #65
 2026-09-01 04:53:34 +00: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
admin ea50b7d915 Merge pull request '釋出 jsc-hooks 0.3.6：頁面編號偵測補齊型別' (#63) from feat/monitor-wiki-page-type/main into develop 
Reviewed-on: #63
 2026-09-01 04:42:59 +00:00
admin 3cf8d82ffd Merge pull request 'feat/monitor-wiki-page-type/page-id-regex' (#62) from feat/monitor-wiki-page-type/page-id-regex into feat/monitor-wiki-page-type/main 
Reviewed-on: #62
 2026-09-01 04:28:26 +00: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
admin 417fe1a413 Merge pull request 'fix/smoke-deny-assertion-per-cli' (#60) from fix/smoke-deny-assertion-per-cli into develop 
Reviewed-on: #60
 2026-09-01 03:50:57 +00: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