 jiantw83
|
c4fdd8b2d8
|
Merge pull request '新增 frontmatter 解析檢查，改寫五支 CLI 的 hook 接線準則' (#50) from feat/cli-hook-rewire/frontmatter-lint-and-guidelines into feat/cli-hook-rewire/main
|
2026-09-01 00:56:11 +00:00 |
|
|
jiantw83
|
7894fa073e
|
chore(manifest): 三份 manifest 版本號提升到 0.2.5
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 這一側的發版收尾。
|
2026-08-31 19:13:03 +08:00 |
|
|
jiantw83
|
4a741071e5
|
docs(frontmatter-lint): 同步 README 與行為清單的 frontmatter 檢查
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 這一側的文件同步。
|
2026-08-31 19:13:03 +08:00 |
|
|
jiantw83
|
beede79d3a
|
docs(guidelines): 改寫 hook 準則裡五支 CLI 的接線事實
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 這一側的規範文件。
|
2026-08-31 19:13:03 +08:00 |
|
|
jiantw83
|
d879e634c0
|
feat(frontmatter-lint): 新增 SKILL.md frontmatter 解析檢查並併入例行稽核
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 這一側的稽核工具。
|
2026-08-31 19:13:03 +08:00 |
|