README.md

@@ -1,6 +1,6 @@
 # jsc-pkg — 套件批次更新
 
-jsc 技能組的 pkg domain：把專案所有外部套件更新到最新穩定版本，完成後執行建置與測試，失敗則還原變更。支援 nodejs / python / dotnet。
+jsc 技能組的 pkg domain：把專案所有外部套件更新到最新穩定版本，完成後執行建置與測試。過不了先把嫌疑套件釘回舊版重試一次，真的裝不起來或建置測試仍過不了才還原變更。支援 nodejs / python / dotnet。
 
 ## 安裝、更新、移除
 
@@ -20,28 +20,35 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
 
 ## 工具
 
-五支工具都靠 python3 解析或改寫檔案。少了 python3，每一支都回報「需要的指令不存在」，不會裝成查無套件。
+`list-packages.sh`、`latest-version.sh`、`apply-version.sh`、`build-test.sh` 靠 python3 解析或改寫檔案。少了 python3，這幾支都回報「需要的指令不存在」，不會裝成查無套件。`install-deps.sh` 不碰 python3，它把安裝交給各生態系自己的安裝器；`git-guard.sh` 只用 git。每支工具實際需要哪些指令，看下表最右欄。
 
 | 工具 | 用途 | 需要的指令 |
 | --- | --- | --- |
+| `tools/git-guard.sh` | `git-guard.sh check <project dir>` 確認是 git 工作樹且工作區乾淨；`git-guard.sh revert <project dir> --confirm-destructive` 還原工作區 | git |
 | `tools/list-packages.sh` | `list-packages.sh [專案目錄]` 偵測專案類型並列出所有外部套件與目前版本（TSV：ecosystem / name / current） | python3 |
 | `tools/latest-version.sh` | `latest-version.sh <ecosystem> <name>` 查最新穩定版（npm / pypi / nuget） | curl、python3 |
 | `tools/apply-version.sh` | `apply-version.sh <ecosystem> <project dir> <name> <version>` 改寫版本來源檔案，把套件釘選到指定版本 | python3 |
 | `tools/install-deps.sh` | `install-deps.sh <ecosystem> <project dir>` 重新解析並安裝相依套件（npm install、pip install、dotnet restore） | npm、pip、dotnet |
-| `tools/build-test.sh` | `build-test.sh <ecosystem> <project dir>` 偵測並執行建置與測試 | npm、python3、pytest、dotnet |
+| `tools/build-test.sh` | `build-test.sh [--detect] <ecosystem> <project dir>` 偵測並執行建置與測試；`--detect` 只偵測不執行，用來在動任何檔案之前先問出推不出指令的情況 | npm、python3、pytest、dotnet |
+
+### 還原的破壞性前提
+
+`git-guard.sh revert` 會執行 `git clean -fd`，未追蹤檔案刪掉沒有 reflog 可救。所以前提判定寫在腳本裡，不寫在技能內文：目錄存在、git 指令存在、確實是 git 工作樹（不是裸存取庫）、呼叫端明確傳入 `--confirm-destructive`、目標不是檔案系統根目錄，五條全過才會跑第一個破壞性指令。任何一條不過就回 1、4、5 或 6，工作區一個位元組都不動。
+
+`check` 的乾淨判定看整個存取庫，`revert` 的還原只作用在專案目錄以下：判定從嚴，動手從窄。
 
 ### 結束碼總表
 
-一個數字只有一個意思，五支工具共用。新增工具請沿用這張表，不要自己編號。
+一個數字一個類別，六支工具共用；同一個類別在各工具指的對象可以不同，差別寫在該列裡。新增工具請沿用這張表，不要自己編號。
 
 | 碼 | 意思 | 呼叫方的動作 |
 | --- | --- | --- |
 | 0 | 成功 | 繼續 |
 | 1 | 參數個數不對 | 停手 |
-| 2 | ecosystem 不認識 | 停手 |
+| 2 | 不認識的輸入：多數工具是 ecosystem 不認識，`git-guard.sh` 是子指令不認識 | 停手 |
 | 3 | 該 ecosystem 沒有來源檔案 | 跳過這個 ecosystem 或套件 |
 | 4 | 依工具而定：`list-packages.sh`、`build-test.sh`、`install-deps.sh` 是指令不存在（停手）；`latest-version.sh`、`apply-version.sh` 是查不到該套件（跳過） | 見左欄 |
-| 5 | 依工具而定：`latest-version.sh`、`apply-version.sh` 是指令不存在（停手）；`build-test.sh` 是推不出建置或測試指令（改問使用者） | 見左欄 |
+| 5 | 依工具而定：`latest-version.sh`、`apply-version.sh` 是指令不存在（停手）；`build-test.sh` 是推不出建置或測試指令（改問使用者）；`git-guard.sh` 是前提不成立，指不是 git 工作樹、工作區不乾淨、還原後仍不乾淨（停手） | 見左欄 |
 | 6 | 找不到專案目錄 | 停手 |
 | 其他 | 底層指令的結束碼 | 只有 `install-deps.sh`、`build-test.sh` 會走還原 |
 
@@ -49,7 +56,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
 
 4 與 5 在各工具間意思不同，是為了保住既有的跳過路由；新增工具請優先用 4 表示指令不存在。
 
-回 1、回 2、回 6 與回「指令不存在」時，技能只回報並停手，不還原工作樹——工具鏈壞了不是套件壞了，還原只會白白刪掉檔案。
+回 1、回 2、回 6 與回「指令不存在」時，技能只回報並停手，不還原工作樹——工具鏈壞了不是套件壞了，還原只會白白刪掉檔案。停手不等於沒動過檔案：更新步驟跑到一半才停手時，已改寫的版本來源檔案留在原地，技能要一併報出改了哪些檔案與哪些套件。
 
 ## Skills 目錄
 
@@ -59,9 +66,9 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
 
 ### `pkg-update`
 
-套件批次更新：列套件 → 查最新穩定版 → 逐 ecosystem 以 sub agent 更新 → 建置與測試（指令不明時決策樹詢問）→ 失敗還原全部變更。
+套件批次更新：先驗 git 工作區乾淨當硬閘門，過了才列套件並問出建置與測試指令 → 各 ecosystem 以 sub agent 並行更新 → 建置與測試，失敗先把兇手釘回舊版重試一次 → 仍失敗才還原全部變更。
 
-更新途中要在版本來源檔案或程式碼留註解時，只寫鎖版本或繞道的原因，不寫內部議題編號、工作包編號、人名與 @ 提及、產生來源署名；第三方套件的 issue 連結可以寫，用來說明繞道成因與解除條件。完整清單與白名單見 [`jsc-review`](https://gitea.jsc.idv.tw/plugins/review) 的 `references/comment-scope.md`。
+更新途中要在版本來源檔案或程式碼留註解時，只寫繞道或釘回舊版的原因；第三方套件的 issue 連結可以寫，用來說明成因與解除條件。禁止清單的正本只有一份，在 [`jsc-review`](https://gitea.jsc.idv.tw/plugins/review) 的 `references/comment-scope.md`，由 `jsc-hooks` 的 `hooks/comment-scope.sh` 在程式層強制。
 
 <!-- JSC-SKILLS:END -->