# 部署與驗證

`skill-new`、`skill-update`、`skill-delete`、`skillset-update` 四支異動技能的收尾共用這份流程。四支只在 SKILL.md 留一行指標指過來，不各自抄一份——抄四份會各自漂移，改一次要記得改四個地方。

## 1. 判路線

改動有沒有進存取庫的**預設分支**，決定走哪條路線。marketplace 與 `version-guard.sh` 都讀預設分支，停在 `develop` 的改動 `jsc-cli:deploy` 看不到。

判定交給 `jsc-meta/tools/deploy-route.sh {domain-path}`，不要自己用 `git log` 目測。多個 domain 就每個各跑一次，可以並行。

| 結束碼 | 意思 | 怎麼辦 |
| --- | --- | --- |
| 0 | 改動已在預設分支上 | 走第 2 節的部署路線 |
| 3 | 改動還沒併進預設分支 | 走第 3 節的工作樹路線 |
| 2 | 用法錯誤 | 修參數重跑 |
| 1 | 判不出來：不是 git 存取庫、沒有 origin、fetch 失敗，或取不到預設分支 | 停下回報 stderr 的原因。**1 不等於工作樹路線**，判不出來就問使用者，不要自己挑一條走 |

完成條件：每個受影響的 domain 存取庫都有一個路線判定，且判定來自腳本輸出的 `route` 欄位。

## 2. 部署路線（結束碼 0）

1. 叫用 `jsc-cli:deploy` 的更新模式，讓每支已安裝的 CLI 都載入新版。deploy 收尾會寫 `$JSC_HOME/restart-required.d/{cli}`，一支 CLI 一份；重啟該支 CLI 之後由 `jsc-hooks` 清掉自己那一份。閘門規則見 [`guidelines.md`](guidelines.md) 的「部署後重啟閘門」。
2. deploy 更新不了某些 CLI 時，記下哪幾支確實載入了新版，改用其中一支繼續。一支都沒載入就停下，把這次異動回報為未驗證。

完成條件：`claude plugin list`（或別支已安裝 CLI 的等效指令）印出的 `jsc-{domain}` 版本，等於三份 manifest 現在的版本。

## 3. 工作樹路線（結束碼 3）

改動還沒進預設分支，部署路線的完成條件永遠達不到，所以改對**工作樹**驗證：

1. 第 4 節的驗證對象改成 `{root}/{domain}` 工作樹，不是已安裝的副本。
2. 回報標注「工作樹驗證、尚未部署」。
3. 點名還沒合併的釋出 PR——改動要等它合進預設分支才會到任何 CLI。跨多個存取庫的異動要等最後一支合併，所以全部列出來。刪除技能還要補一句：PR 合併前技能仍然裝著，指令仍然叫得動。

完成條件：第 4 節的驗證在每個工作樹上都通過，且回報裡列出每一支待合的釋出 PR。

## 4. 功能驗證：一定要換一個工作階段

**部署會把閘門立在自己腳下。** `jsc-cli:deploy` 收尾寫下重啟閘門的狀態檔，緊接著在**同一個工作階段**叫用剛做好的技能，那支技能不在豁免清單上就必被擋；連修復路徑 `jsc-cli:doctor` 與 `jsc-cli:setup` 也一起被擋。

解法不是把它們加進豁免清單。豁免只擋得住閘門，擋不住「目前行程還載著舊版」這個事實——豁免過關的驗證，驗到的是舊版行為，等於假通過。

**正解：驗證一律在新的 CLI 行程裡跑。** 用 `jsc-cli/tools/detect-clis.sh` 取得已安裝 CLI 的執行檔路徑，對每支支援非互動 Prompt 的 CLI，另外開一個行程送出最小 Prompt。新行程是新的工作階段，`jsc-hooks` 開場就清掉那支 CLI 自己的狀態檔，載入的也是磁碟上的新版。

四支技能都不得在部署的那個工作階段內叫用剛異動的技能。

驗證項目：

1. 跑 `jsc-meta/tools/list-skills.sh`，確認該技能的列符合這次異動：新增看得到 `{domain}<TAB>{name}` 那一列；更新看得到新的 `description`；刪除看不到那一列。
2. 這次異動碰過的每一支工具，都用真實參數跑一次，把實際結束碼對照工具檔頭宣告的意思。
3. 每支可測的 CLI 各開一個新行程，送出一個最小 Prompt 叫用 `/jsc-{domain}:{name}`，記錄 CLI 結束碼與 stderr。新增與更新要確認載入的是異動後的 SKILL.md 內文，不是「未知指令」；刪除要確認指令已消失，或替代路徑仍可用。各支 CLI 可以並行送。

完成條件：上列三項各有結果；每支可測 CLI 的 Prompt 都沒有非預期 stderr；不可測的 CLI 逐支寫明原因。

## 5. 驗證失敗怎麼辦

Prompt 因為 CLI 工具、plugin 安裝、hook 接線、模型標籤表或設定而失敗時：

1. 先跑 `jsc-cli:doctor`，再用 `jsc-cli:setup` 修待修項目，然後在新行程重跑同一個 Prompt。
2. hook 冒煙測試失敗，交給 `jsc-hooks:hooks-install`，由它把 hook 接線或執行期錯誤轉給 `jsc-hooks:repair`。
3. 根因若在技能組本身的規格、工具或 hook 實作，就修對應 domain，跑 `jsc-meta/tools/sync-skill-manifest.sh {domain-path}` 同步與驗證，再用 `jsc-git:pr` 對 `develop` 開 PR；PR 送出後回到第 1 節重判路線。

任一項對不上——列不見、結束碼不在工具文件裡、指令載不到、Prompt 失敗、非預期 stderr——就修掉成因，回到第 1 節重跑整段。

完成條件：每一項不符都有對應的修正動作與重跑結果，沒有留下「已知失敗但照樣收尾」的項目。