From 49fef7069ea698e4e07afb39920037f16e8e7649 Mon Sep 17 00:00:00 2001
From: Jeffery <jiantw83@yahoo.com>
Date: Mon, 31 Aug 2026 13:43:34 +0800
Subject: [PATCH 1/2] =?UTF-8?q?docs(behaviors):=20=E6=96=B0=E5=A2=9E=20jsc?=
 =?UTF-8?q?-pkg=20=E6=8A=80=E8=83=BD=E8=A1=8C=E7=82=BA=E6=B8=85=E5=96=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

What：
- 新建 references/ 目錄。
- 新增 references/behaviors.md，收錄 pkg-update 一支技能。
- 每支技能一節，節內五列表：觸發時機、關鍵步驟、外部呼叫、完成條件、可驗證跡象。

Why：
- 技能驗證需要一份行為基準來比對。
- 清單放在技能自己的 repo，技能改動與清單就能進同一個 PR。
- 同一個 PR 才不會漂移，也不用跨 repo 開兩條 PR 互卡。

How：
- 盤點 skills/ 下的技能，逐支寫出五個欄位的內容。
- 關鍵步驟寫到工具腳本層級，外部呼叫列出腳本、技能與外部服務。
- 格式交給 meta/tools/check-behaviors.sh 在程式層檢查。

Who：
- 技能驗證流程讀這份清單當基準。
- 日後任何技能異動，都要在同一個 PR 內同步更新這一頁。
---
 references/behaviors.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)
 create mode 100644 references/behaviors.md

diff --git a/references/behaviors.md b/references/behaviors.md
new file mode 100644
index 0000000..3e3db9a
--- /dev/null
+++ b/references/behaviors.md
@@ -0,0 +1,13 @@
+# jsc-pkg 技能行為清單
+
+本頁記錄 jsc-pkg 每支技能的行為基準，供技能驗證比對。技能異動時，在同一個 PR 內一起更新這一頁。
+
+## pkg-update
+
+| 項目 | 內容 |
+| --- | --- |
+| 觸發時機 | 使用者要把一個專案的所有外部套件更新到最新穩定版本時使用。jsc-sdlc 維護階段也把它當成維護動作之一。專案必須是 nodejs、python 或 dotnet，而且工作區必須乾淨。不要用它新增套件、移除套件，也不要用它把單一套件改成指定版本。 |
+| 關鍵步驟 | 先跑 `tools/git-guard.sh check` 當硬閘門，證明目標是 git 工作樹而且 `git status --porcelain` 沒有輸出、跑 `tools/list-packages.sh` 列出每個套件的 ecosystem、名稱與目前版本、對每個 ecosystem 跑 `tools/build-test.sh --detect` 取得建置與測試指令，推不出來就依 jsc-ask:ask 問使用者、每個 ecosystem 開一個 sub agent 並行更新，同一個 ecosystem 內先併發跑 `tools/latest-version.sh` 查版本，再逐一跑 `tools/apply-version.sh` 改寫版本來源檔案、每個 ecosystem 的套件都套用完才跑一次 `tools/install-deps.sh`、跑 `tools/build-test.sh` 建置與測試、真的失敗就從錯誤輸出點出嫌疑套件，用 `tools/apply-version.sh` 把嫌疑套件釘回舊版並寫下原因註解，重新安裝後只重試一次、重試仍失敗才跑 `tools/git-guard.sh revert --confirm-destructive` 還原、成功就報出更新、釘回舊版與跳過三份清單，交給 jsc-git:commit。 |
+| 外部呼叫 | 腳本 `tools/git-guard.sh`、`tools/list-packages.sh`、`tools/latest-version.sh`、`tools/apply-version.sh`、`tools/install-deps.sh`、`tools/build-test.sh`。技能 jsc-ask:ask（問建置與測試指令）、jsc-git:commit（成功後提交）。外部服務為 npm、PyPI、NuGet 三個註冊處，由 `latest-version.sh` 以 curl 查詢。不呼叫 Gitea API。 |
+| 完成條件 | 三種結局各自有完成條件。成功時，步驟 1 列出的每個套件都恰好出現在更新、釘回舊版、跳過其中一份清單，而且已經交給 jsc-git:commit。走還原路線時，`git-guard.sh revert` 回 0，接著報出失敗套件與錯誤摘要。走停手路線時，報出失敗的工具與結束碼、已經套用的套件、已經改寫的版本來源檔案，而且不進入還原步驟。 |
+| 可驗證跡象 | 專案目錄的版本來源檔案被改寫，`git diff` 看得到 package.json、requirements.txt、pyproject.toml 或 `*.csproj` 的版本字串變動。`install-deps.sh` 跑過會留下鎖定檔與安裝產物，例如 package-lock.json、node_modules、bin、obj。釘回舊版的套件旁邊留有一行說明原因的註解，必要時附第三方 issue 連結。成功路線由 jsc-git:commit 產生 commit，`git log` 查得到。走還原路線後，`git status --porcelain` 不印任何內容，被 gitignore 的安裝產物留在原地。這支技能不寫任何 wiki 頁，也不開 PR。 |

From 0dccd19061408b30d6c50fba7824552329dea922 Mon Sep 17 00:00:00 2001
From: Jeffery <jiantw83@yahoo.com>
Date: Mon, 31 Aug 2026 13:43:34 +0800
Subject: [PATCH 2/2] =?UTF-8?q?chore(manifest):=20=E4=B8=89=E4=BB=BD=20man?=
 =?UTF-8?q?ifest=20=E5=8D=87=E7=89=88=E5=88=B0=200.0.9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

What：
- .claude-plugin/plugin.json 版本改成 0.0.9。
- .codex-plugin/plugin.json 版本改成 0.0.9。
- plugin.json 版本改成 0.0.9。

Why：
- 這次新增行為清單，屬於外顯內容變更，要跟著升版。
- 版本守門會比對三份 manifest，版本不一致就報錯。

How：
- 由 0.0.8 遞增到 0.0.9，只改版本欄位。
- 三份檔案改成同一個版本字串。

Who：
- 版本守門讀這三份 manifest 判斷是否需要更新。
- 使用者安裝或更新外掛時，看到的是這個版本。
---
 .claude-plugin/plugin.json | 2 +-
 .codex-plugin/plugin.json  | 2 +-
 plugin.json                | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 2c2e3e3..b454375 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "jsc-pkg",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "套件批次更新（nodejs/python/dotnet），先把嫌疑套件釘回舊版重試一次，真失敗才還原",
   "skills": "./skills",
   "author": {
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 9eb9d69..8efa915 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "jsc-pkg",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "套件批次更新（nodejs/python/dotnet），先把嫌疑套件釘回舊版重試一次，真失敗才還原",
   "skills": "./skills",
   "jsc": {
diff --git a/plugin.json b/plugin.json
index 8572507..92d26ae 100644
--- a/plugin.json
+++ b/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "jsc-pkg",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "套件批次更新（nodejs/python/dotnet），先把嫌疑套件釘回舊版重試一次，真失敗才還原",
   "skills": "./skills/",
   "jsc": {