feat(spec-version-guard): 新增版本前置檢查規範、共用腳本與 hook
新增 spec-version-guard 規範（定義遠端發佈版本 vs 當前實際載入版本的比對規則、 fail-closed、錯誤訊息格式）與 scripts/version-guard.mjs（hook／CLI 雙模式， hook 模式輸出 Claude Code/Copilot 相容的 PreToolUse deny JSON）；spec-preflight 的載入順序補上版本檢查第 0 步；新增 hooks/hooks.json 掛 PreToolUse； do-wiki/models/plan-wiki/plugins-uninstall/todo-wiki 五個 skill 檔頭引用新規範 （plugins-install 刻意排除，避免版本落後時擋住自己的修復手段）。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Claude Sonnet 5
@@ -11,9 +11,21 @@ description: JSC plugins 共用「規範前置載入流程」：每個 skill 執
|
||||
|
||||
每個 skill 執行前，依下列順序以 Skill 工具載入，**順序不可顛倒**：
|
||||
|
||||
1. **先載入本規範自身**：`/jsc-shared:spec-preflight`。這一步本身就是探測——載入成功代表 shared plugin 已安裝，可以繼續往下載入其他 spec；載入失敗直接進入〔載入失敗的處理〕。
|
||||
0. **先依 `/jsc-shared:spec-version-guard` 執行版本檢查**：確認當前實際載入的 `jsc-shared`（以及該 skill 所屬 plugin 自己）版本沒有落後於 Gitea `master` 現行版本；不符即中斷本 skill，見〔「版本不符」與「shared 未安裝」是兩種不同中斷原因〕。這一步排在所有 spec 載入之前，避免用舊版規則做事。
|
||||
1. **再載入本規範自身**：`/jsc-shared:spec-preflight`。這一步本身就是探測——載入成功代表 shared plugin 已安裝，可以繼續往下載入其他 spec；載入失敗直接進入〔載入失敗的處理〕。
|
||||
2. **再依該 skill 自己列出的規範清單，逐一載入其他 `/jsc-shared:spec-xxx`**。清單與載入順序由各 skill 自己在檔頭決定（通常照該 skill 內文實際用到的先後順序排列），本規範不代為規定其他 spec 之間的順序。
|
||||
|
||||
## 「版本不符」與「shared 未安裝」是兩種不同中斷原因
|
||||
|
||||
第 0 步（版本檢查）與第 1 步（本規範是否載入得到）失敗時的原因完全不同，**中斷訊息不可混用**：
|
||||
|
||||
| 情境 | 代表什麼 | 中斷訊息依據 |
|
||||
| --- | --- | --- |
|
||||
| 第 0 步版本檢查不符或查不到遠端版本 | shared plugin **已安裝**，但版本落後於 Gitea `master`，或遠端查詢失敗（fail-closed） | 依 `/jsc-shared:spec-version-guard`〔錯誤訊息格式〕，導向 `/jsc-shared:plugins-install` 更新 |
|
||||
| 第 1 步載入不到本規範自身 | shared plugin **根本未安裝** | 依本規範〔載入失敗的處理〕，導向安裝 `https://gitea.jsc.idv.tw/plugins/shared.git` |
|
||||
|
||||
不得把「版本落後」誤報成「未安裝」（使用者會照著安裝流程走卻發現早就裝了），也不得把「未安裝」誤報成「版本落後」（使用者會照著更新指令走卻發現裝不了，因為根本沒有 marketplace）。
|
||||
|
||||
## 載入失敗的處理
|
||||
|
||||
只要**任一** spec（包含本規範自身）載入不到，一律判定為**shared plugin（`jsc-shared`）未安裝**，不視為暫時性錯誤、不重試、不略過繼續：
|
||||
@@ -53,11 +65,12 @@ description: JSC plugins 共用「規範前置載入流程」：每個 skill 執
|
||||
|
||||
先載入 `/jsc-shared:spec-preflight` 並依其流程處理；載入不到即代表 shared plugin 未安裝，
|
||||
依該 spec 詢問使用者是否安裝 `https://gitea.jsc.idv.tw/plugins/shared.git`，不安裝則中斷本 skill。
|
||||
本 skill 需要的規範：`spec-output`、`spec-execution`、`spec-gitea`、…（依各 skill 實際需要的規範清單列出）
|
||||
preflight 的第一件事是依 `/jsc-shared:spec-version-guard` 比對遠端與當前實際載入版本，不符即中斷本 skill。
|
||||
本 skill 需要的規範：`spec-version-guard`、`spec-output`、`spec-execution`、`spec-gitea`、…（依各 skill 實際需要的規範清單列出）
|
||||
```
|
||||
|
||||
- 最後一行的規範清單**只列名稱**，不附一行摘要（摘要是規範內容的重抄，會與本文漂移不一致；需要摘要時直接載入該 spec 看本文）。
|
||||
- 清單順序建議照該 skill 內文實際用到的先後排列，方便對照。
|
||||
- 清單順序建議照該 skill 內文實際用到的先後排列，方便對照；`spec-version-guard` 因為是最前置的檢查，習慣上放在清單最前面。
|
||||
|
||||
## 適用範圍
|
||||
|
||||
|
||||
Reference in New Issue
Block a user