收攏 frontmatter 檢查與五支 CLI 的 hook 接線準則改寫 #51

2026-09-01T00:58:00Z

jiantw83 commented

2026-09-01 00:58:00 +00:00

摘要

需求描述：修正 codex、copilot、antigravity、kiro 四支 CLI 的 hook 接線。四支都有能介入的 pre-tool 事件，過去接錯位置，導致版本前置檢查與部署後重啟閘門長期完全失效，文件還寫著「這些 CLI 沒有 pre-tool hook」。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
`tools/lint-frontmatter.sh`	新增。檢查 frontmatter 能不能安全解析，把缺陷 6 擋在程式層
`references/guidelines.md`	四處：「Hook 規則」第 3 條、新增共用腳本節、改寫「版本前置檢查」與「部署後重啟閘門」、審核檢查清單加一項
`skills/skill-check/SKILL.md`	`lint-frontmatter.sh` 併進第一組稽核，明寫退出 3 不算通過
`references/behaviors.md`、README	同步

這一批抓到的六個缺陷

六個全部不會報錯——設定寫得看起來正確，CLI 靜默不理，日誌、結束碼與 status 都沒有痕跡。

#	缺陷	後果
1	codex 的 matcher 用 `Skill`，但 Codex 沒有 `Skill` 工具	三支 hook 從未執行
2	codex 的 `hooks` 鍵寫成內嵌物件，實際是路徑字串	可能讓整份 manifest 解不出來
3	antigravity 的 `PreToolUse` 寫成 Flat，實際要 Grouped	事件被靜默丟棄，連 `actions` 鍵都不生成
4	三支接線的命令沒帶 `JSC_CLI={代號}`	設定、matcher、`status` 全綠，閘門一次都不擋
5	copilot 的位置指向腳本目錄不是設定目錄	設定永遠不會被讀
6	6 支技能 description 的 YAML 純量語法錯	Antigravity 靜默丟棄，34 支只認 28 支

第 4 個最險：前三個修完之後一切看起來都對，閘門仍然完全不會作用。

設計重點

準則原本寫著只有 claude 有 pre-tool hook，那是錯的。錯誤結論被寫進準則之後就沒人再查，兩道閘門因此在四支 CLI 上長期失效。
稽核抓到一處自相矛盾並修正：原本寫「五支全都有能阻擋的 pre-tool 事件，只有 kiro 例外」，前後半句互斥，把 kiro 的能力寫高了。
lint-frontmatter.sh 的退出 3 明寫不算通過：那是「什麼都沒掃」，不是「掃過沒問題」。

方法論

照文件寫不夠，要去問 CLI 自己讀到什麼。這次用到的唯讀管道：agy -p "/hooks"（不吃 quota）、kiro-cli agent validate、codex 的 [hooks.state] 登記內容。copilot 沒有這種管道，所以它的形狀維持未證。

測試結果

check-behaviors.sh、lint-frontmatter.sh、ste100-lint.sh 對 10 個 domain 全部退出 0。
lint-scripts.sh 9 個退出 0，ask 退出 3（沒有腳本可掃）。
wire-cli.sh smoke codex 退出 0，lines 由腳本自印，接線形狀 26 條斷言、每條正向配一條反向。
反證多輪：改壞判定、拿掉修法、抽掉 JSC_CLI、用改前版本重組假樹，每一種都抓得到並回非零。
未跑「開新 CLI 行程送最小 Prompt」：這條 PR 合併前，CLI 載入的仍是舊的已安裝副本。

驗證等級

CLI	形狀	觸發
claude	實證	實證
codex	實證	未驗證
antigravity	實證	未驗證，對話 quota 用盡
copilot	未證	未驗證
kiro	實證	部分實證：`agentSpawn`、`userPromptSubmit` 實跑觸發

kiro 的 verdict 是 degraded，理由是 CLI 限制不是接線問題：技能走 ResolveSkill 這個 agent 內部請求，preToolUse 攔不到技能叫用，userPromptSubmit 的非零結束碼也擋不下那一輪。

尚未做的事

write-guard.sh 三種模式與 SDLC 模型鎖在四支非 claude CLI 上尚未接線。那是還沒做，不是驗不過。
kiro 的 resources 兩層 glob 能不能修好技能可見性未驗證。kiro 目前預設資源 glob 只掃一層，34 支技能一支都載不到。

前置 Push Request

無

## 摘要 - 需求描述：修正 codex、copilot、antigravity、kiro 四支 CLI 的 hook 接線。四支都有能介入的 pre-tool 事件，過去接錯位置，導致版本前置檢查與部署後重啟閘門長期完全失效，文件還寫著「這些 CLI 沒有 pre-tool hook」。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `tools/lint-frontmatter.sh` | 新增。檢查 frontmatter 能不能安全解析，把缺陷 6 擋在程式層 | | `references/guidelines.md` | 四處：「Hook 規則」第 3 條、新增共用腳本節、改寫「版本前置檢查」與「部署後重啟閘門」、審核檢查清單加一項 | | `skills/skill-check/SKILL.md` | `lint-frontmatter.sh` 併進第一組稽核，明寫退出 3 不算通過 | | `references/behaviors.md`、README | 同步 | ## 這一批抓到的六個缺陷六個全部不會報錯——設定寫得看起來正確，CLI 靜默不理，日誌、結束碼與 `status` 都沒有痕跡。 | # | 缺陷 | 後果 | | --- | --- | --- | | 1 | codex 的 matcher 用 `Skill`，但 Codex 沒有 `Skill` 工具 | 三支 hook 從未執行 | | 2 | codex 的 `hooks` 鍵寫成內嵌物件，實際是路徑字串 | 可能讓整份 manifest 解不出來 | | 3 | antigravity 的 `PreToolUse` 寫成 Flat，實際要 Grouped | 事件被靜默丟棄，連 `actions` 鍵都不生成 | | 4 | 三支接線的命令沒帶 `JSC_CLI={代號}` | 設定、matcher、`status` 全綠，閘門一次都不擋 | | 5 | copilot 的位置指向腳本目錄不是設定目錄 | 設定永遠不會被讀 | | 6 | 6 支技能 description 的 YAML 純量語法錯 | Antigravity 靜默丟棄，34 支只認 28 支 | 第 4 個最險：前三個修完之後一切看起來都對，閘門仍然完全不會作用。 ## 設計重點 - 準則原本寫著只有 claude 有 pre-tool hook，那是錯的。錯誤結論被寫進準則之後就沒人再查，兩道閘門因此在四支 CLI 上長期失效。 - 稽核抓到一處自相矛盾並修正：原本寫「五支全都有能阻擋的 pre-tool 事件，只有 kiro 例外」，前後半句互斥，把 kiro 的能力寫高了。 - `lint-frontmatter.sh` 的退出 3 明寫不算通過：那是「什麼都沒掃」，不是「掃過沒問題」。 ## 方法論照文件寫不夠，要去問 CLI 自己讀到什麼。這次用到的唯讀管道：`agy -p "/hooks"`（不吃 quota）、`kiro-cli agent validate`、codex 的 `[hooks.state]` 登記內容。copilot 沒有這種管道，所以它的形狀維持未證。 ## 測試結果 - `check-behaviors.sh`、`lint-frontmatter.sh`、`ste100-lint.sh` 對 10 個 domain 全部退出 0。 - `lint-scripts.sh` 9 個退出 0，`ask` 退出 3（沒有腳本可掃）。 - `wire-cli.sh smoke codex` 退出 0，`lines` 由腳本自印，接線形狀 26 條斷言、每條正向配一條反向。 - 反證多輪：改壞判定、拿掉修法、抽掉 `JSC_CLI`、用改前版本重組假樹，每一種都抓得到並回非零。 - 未跑「開新 CLI 行程送最小 Prompt」：這條 PR 合併前，CLI 載入的仍是舊的已安裝副本。 ## 驗證等級 | CLI | 形狀 | 觸發 | | --- | --- | --- | | claude | 實證 | 實證 | | codex | 實證 | 未驗證 | | antigravity | 實證 | 未驗證，對話 quota 用盡 | | copilot | **未證** | 未驗證 | | kiro | 實證 | 部分實證：`agentSpawn`、`userPromptSubmit` 實跑觸發 | kiro 的 verdict 是 `degraded`，理由是 CLI 限制不是接線問題：技能走 `ResolveSkill` 這個 agent 內部請求，`preToolUse` 攔不到技能叫用，`userPromptSubmit` 的非零結束碼也擋不下那一輪。 ## 尚未做的事 - `write-guard.sh` 三種模式與 SDLC 模型鎖在四支非 claude CLI 上尚未接線。那是還沒做，不是驗不過。 - kiro 的 `resources` 兩層 glob 能不能修好技能可見性未驗證。kiro 目前預設資源 glob 只掃一層，34 支技能一支都載不到。 ## 前置 Push Request - 無

jiantw83 added 5 commits 2026-09-01 00:58:01 +00:00

feat(frontmatter-lint): 新增 SKILL.md frontmatter 解析檢查並併入例行稽核 d879e634c0

What：
- 新增 tools/lint-frontmatter.sh，掃一個 domain 每支 skills/*/SKILL.md 的 frontmatter，檢查分隔線成對、必要鍵齊全、未加引號的純量不含「冒號加空白」、起頭字元不是 YAML 特殊字元、加了引號的值收得起來，共五項。
- 改寫 skills/skill-check/SKILL.md 的第一組稽核，把這支腳本併進去成為第 2 步，原本的行為清單檢查、結束碼路由檢查、hook smoke 依序後移。
- 第二組留白的檢查清單項目由四項改成五項，第 3 步的合併說明、三組的完成條件、第 6 步的重驗完成條件同步改寫。

Why：
- 抓到 6 支技能的 description 是未加引號的 YAML 純量、內容含「冒號加空白」。那在 YAML 是鍵的分隔符號，整份 frontmatter 當場語法錯誤。
- Antigravity 讀到語法錯誤就靜默丟棄整支技能。磁碟上 34 支，它只認 28 支。載入器不報、CLI 不報，技能清單只是少了幾列。
- 這種缺陷唯一的發現途徑是逐檔比對磁碟數量與載入數量。人工比對 10 個 domain 每次稽核都要重做一遍，還會漏。輸入輸出固定的判定就交給程式。

How：
- 腳本用 awk 自己判定 YAML 1.2 的 plain scalar 規則，不相依 pyyaml。護欄不綁在一個不保證存在的相依上，才跑得到每一台機器。
- 單引號的跳脫是重複一次、雙引號的跳脫是反斜線，兩套規則不同，所以引號改用逐字掃描，不用正規表示式一次比對兩種。
- 結束碼分四種：0 是掃到 SKILL.md 且五項全過、1 是有不合格項目（清單走 stderr，格式 {檔案}:{鍵}:{說明}）、2 是用法錯誤、3 是什麼都沒掃。
- SKILL.md 明寫退出 3 不算通過，並把「每個 domain 的 lint-frontmatter.sh 退出 0」列進第 6 步的完成條件。

Who：
屬 CLI hook 接線修正（jsc-hooks 0.3.4）在 meta 這一側的稽核工具。

docs(guidelines): 改寫 hook 準則裡五支 CLI 的接線事實 beede79d3a

What：
- 改寫「Hook 規則」第 3 條，寫明五支 CLI 的 hook 負載形態各不相同，沒有哪一支是基準格式。
- 新增「技能名解析與阻擋輸出的共用腳本」節，列出 skill-name.sh 與 deny.sh 的用法、各 CLI 的技能名取值來源、抽成共用腳本的理由。
- 改寫「版本前置檢查」，補上五支 CLI 的接線位置表、逐支陷阱表、未實測部分的標明規則。
- 改寫「部署後重啟閘門」，指名 restart-gate.sh，並寫明接線位置與版本前置檢查完全相同。
- 審核檢查清單新增一項：該 domain 的 lint-frontmatter.sh 要退出 0，退出 3 不算通過。

Why：
- 這一節以前寫著「只有 claude 接得上，其餘四支沒有 pre-tool hook」。那是錯的。四支全都有能阻擋的 pre-tool 事件，是我們接錯位置。
- 四個無聲失效逐一坐實了這件事：codex 的 matcher 用 Skill，但 Codex 沒有 Skill 工具，技能是模型用 Bash 讀 SKILL.md；codex 的 hooks 鍵寫成內嵌物件，實際規格是路徑字串；antigravity 的 PreToolUse 寫成 Flat，實際要 matcher 加 hooks 包一層的 Grouped；三支新接的命令沒帶 JSC_CLI={代號}，閘門認不出自己跑在哪支 CLI 上，一次都擋不下來。
- 錯誤的結論被寫進準則之後就沒有人再去查。版本前置檢查與部署後重啟閘門因此在四支 CLI 上長期失效，而且失效是安靜的：hook 沒被觸發不會報錯，看起來就跟「沒有東西該擋」一樣。

How：
- 接線位置表每一列都經過執行檔抽出或本機實測，事件名、matcher、寫入檔案、阻擋方式逐欄寫死。
- verdict 據實分級：claude、codex、copilot、antigravity 寫 wired；kiro 的技能叫用走 ResolveSkill 內部請求、不走工具管線，攔不到，寫 degraded，不寫 failed。
- antigravity 與 kiro 的觸發沒有實跑驗證，另段標明，回報時不得混進已驗證的結論。
- 兩道閘門共用同一套接線，就共用同一份事實表。重啟閘門那節只指回接線位置表，不另寫一份能力描述，避免改一份、漏一份。

Who：
屬 CLI hook 接線修正（jsc-hooks 0.3.4）在 meta 這一側的規範文件。

docs(frontmatter-lint): 同步 README 與行為清單的 frontmatter 檢查 4a741071e5

What：
- README 的 skill-check 段落，第一組稽核補上 lint-frontmatter.sh。
- README 的工具表新增 tools/lint-frontmatter.sh 一列，寫明五項檢查、不相依 YAML 套件、四種結束碼、退出 3 不等於通過。
- references/behaviors.md 的 skill-check 表改寫四列：關鍵步驟、外部呼叫、完成條件、可驗證跡象。

Why：
- 準則要求該 domain 的 behaviors.md 與 skills/ 相符，check-behaviors.sh 才會退出 0；README 的「Skills 目錄」也要跟著改動同步。
- 文件沒跟上，稽核就查不到這支新腳本，也不知道退出 3 是什麼都沒掃。這支腳本擋的正是靜默失效，文件本身先靜默漏掉它，等於白做。

How：
- 照 skills/skill-check/SKILL.md 的新流程改寫，關鍵步驟寫明第一組平行跑腳本檢查、frontmatter 檢查、行為清單檢查與 hook smoke。
- 外部呼叫清單依實際呼叫順序插入 tools/lint-frontmatter.sh。
- 完成條件補上「frontmatter 檢查退出 3 是什麼都沒掃，不算通過」，可驗證跡象補上「每個 domain 的 lint-frontmatter.sh 退出 0」。
- 第二組留白項目由四項改五項，同步寫進關鍵步驟的合併說明。

Who：
屬 CLI hook 接線修正（jsc-hooks 0.3.4）在 meta 這一側的文件同步。

chore(manifest): 三份 manifest 版本號提升到 0.2.5 7894fa073e

What：
- plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json 的 version 由 0.2.4 提升到 0.2.5。

Why：
- 準則要求改動連帶提升三份 manifest 的 version，README 的「Skills 目錄」與 manifest 同步。
- 版本前置檢查靠 manifest 版本判定本機載入版本有沒有落後遠端發佈版本。版本號不動，這批新增的 frontmatter 檢查與改寫過的 hook 準則就發不出去，各機器也擋不到舊版。

How：
- 由主流程的 sync-skill-manifest.sh 同步三份，只動 version 欄，其餘欄位不變。
- 三份的 name 與 description 逐位元一致，避免各 CLI 讀到不同內容。

Who：
屬 CLI hook 接線修正（jsc-hooks 0.3.4）在 meta 這一側的發版收尾。

Merge pull request '新增 frontmatter 解析檢查，改寫五支 CLI 的 hook 接線準則' (#50 ) from feat/cli-hook-rewire/frontmatter-lint-and-guidelines into feat/cli-hook-rewire/main c4fdd8b2d8

jiantw83 merged commit 06fe739070 into develop

2026-09-01 00:58:43 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: plugins/meta#51