fix(dev): 優化 SDKMAN JDK 切換流程

[SamWang32191]

摘要

• 擴大 sdkman-switch-jdk 對 Java／JDK 版本問題的觸發描述，並同步 plugin lockstep 版本至 0.1.8
• 將已安裝 exact candidate 的一次性執行改為無狀態 fast path，不初始化 SDKMAN、不呼叫 sdk use、不讀寫 default，也不取得 default-state lock
• 將永久 default 流程移至獨立 reference，並修正 lock 建立失敗的診斷訊息
• 更新 compound command 指引為 non-login bash -c，避免 profile 覆寫 runner 選定的 JDK

背景與原因

V2 integration task 多次使用這個 skill 時，遇到三類可避免的摩擦：隔離 runner 被既有 lock-path 狀態擋住、login shell 把 Java 8 切回 Java 21，以及 lock 建立失敗被誤報為型別錯誤。對已完整安裝的 exact candidate，這些 default-state 操作不是執行命令所需，因此改為直接設定精確 JAVA_HOME／PATH 並 exec payload。

主要變更

• run-java.sh 僅驗證 SDKMAN root、candidate 與 bin/java，不再 source SDKMAN 或修改 default
• 明確拒絕相對 SDKMAN_DIR、保留空 PATH 安全行為，並先以 exact Java 執行版本探測
• sdkman-current-state.sh 區分 unsafe lock path 與 lock creation failure
• SKILL.md 聚焦預設無狀態流程；永久 default 操作搬到 references/default-scope.md
• contract tests 覆蓋無初始化 fast path、空 PATH、bash -c／bash -lc 差異、invalid identifier、probe failure 與 lock 診斷

驗證

• /bin/bash test/sdkman-switch-jdk-contract.sh：40/40
• 相關 Bash scripts bash -n
• skill quick_validate.py
• Node 24 repository version-management tests：13/13
• plugin manifests 與 VERSION=0.1.8 lockstep check
• real CLI smoke：read-only、無 init 的 SDKMAN root 可執行已安裝 Java 8
• git diff --check

風險與取捨

• fast path 刻意不載入 SDKMAN extension 或 native override，只適用已完整安裝且穩定的 exact candidate
• fast path 不與同一 candidate tree 的安裝／替換操作序列化；文件要求等待同一 identifier 的安裝或替換完成
• 安裝、永久 default 與完整 project environment 仍保留原本有狀態且具 default 保護的流程

[SamWang32191]

APPROVE (advisory) — 九個審查軸皆已完整檢查，未發現 must-fix

Coverage & checks

Axis	Status
Correctness	clean — 追蹤 exact candidate 驗證、實體路徑、PATH 組裝、版本探測、payload exec 與各種 lock-path 分類
Spec conformance	clean — 將 fast path、shell 指引、default-scope 拆分、lock 診斷與 0.1.8 升版逐項對回 10 個變更檔
Scope (out-of-scope)	clean — 每個變更檔都可直接映射至 fast path、文件拆分、診斷、契約測試或 lockstep 升版意圖
Convention conformance	clean — 對照 base ref 的 AGENTS.md，確認 stable SemVer、VERSION／manifest lockstep、marketplace 與繁體中文規則
Security	clean — 檢查 identifier allowlist、absolute SDKMAN root、candidate regular-file target、argv 邊界與 unsafe lock-path 拒絕
Readability & simplicity	clean — runner 收斂為 root、candidate、environment、probe、exec 五段，永久 default 流程隔離至具名 reference
Architecture	clean — 無狀態 exact-candidate runner 與有狀態安裝／project runner 的責任邊界清楚，未新增反向耦合或依賴
Performance	clean — fast path 不再初始化 SDKMAN、建立 default-state lock、呼叫 sdk use 或 reconciliation，且候選列舉維持單層有界
Test coverage	clean — 靜態核對新增 contract cases 已覆蓋 fast path、PATH、argv、probe、candidate、identifier 與 lock 診斷邊界

• Verified — GitHub 平台上的 SDKMAN JDK script contracts、Node.js 22、Node.js 24 與 GitGuardian 四項檢查皆成功；本輪為 static-only review，未在本機執行 PR 程式、測試或 build。
• Out-of-band — 以固定 head SHA 唯讀補查完整 runner／state helper，並以 base SHA 的 AGENTS.md 檢查規範符合性。

🤖 Reviewed by GPT-5.6

(self-review — 同一帳號；GitHub 會以 event=COMMENT 記錄且不顯示 badge，所以上述 verdict 僅供參考。)