tools/check-requires.sh

@@ -4,11 +4,17 @@
 #   check-requires.sh {claude|codex|copilot|antigravity|kiro} {manifest}
 # 輸出（單行，可供程式判讀）：
 #   status=ok reason={沒有宣告相依版本|相依版本符合：...}
-#   status=blocked reason={缺哪一個 plugin、差哪一版，或 manifest 讀不到}
+#   status=blocked reason={缺哪一個 plugin、差哪一版}
+#   status=unknown reason={manifest 讀不到、不是有效 JSON，或缺 python3}
 # 結束碼：0=通過（沒有宣告相依，或全部符合）
-#         1=擋下（相依版本不符、缺相依 plugin、manifest 不存在或不是有效 JSON、缺 python3）
+#         1=相依版本不符或缺相依 plugin
 #         2=用法錯誤（參數個數不對，或 CLI 代號不在五個之內）
-# deploy.sh update 在每個 domain 更新前呼叫一次；擋下就跳過該 domain，不更新到一半才失敗。
+#         4=判不出結論（manifest 不存在、不是有效 JSON、缺 python3）
+# 1 與 4 分開的理由：兩者都不是「通過」，但成因完全不同。混成同一個碼，呼叫端就只能
+# 用同一句話講兩件事，環境壞掉會被說成版本落後，操作者照著去補版本永遠補不到問題點。
+# deploy.sh update 在每個 domain 更新前呼叫一次，但擋下不代表跳過：deploy.sh 照樣更新，
+# 只印一行提醒說缺哪一版。跳過會讓落後的 domain 永遠更新不到，形成死鎖。
+# 真正的阻擋在 jsc-hooks 的 version-guard.sh，技能被叫用時才擋。
 set -u
 
 usage() {
@@ -26,14 +32,14 @@ case "$CLI" in
 esac
 
 [ -f "$MANIFEST" ] || {
-  printf 'status=blocked reason=找不到 manifest：%s\n' "$MANIFEST"
+  printf 'status=unknown reason=找不到 manifest：%s\n' "$MANIFEST"
-  exit 1
+  exit 4
 }
 
 command -v python3 >/dev/null 2>&1 || {
   # 直接讓 shell 回 127 的話，呼叫端會看到一個沒宣告過的結束碼，也讀不到原因。
-  printf 'status=blocked reason=找不到 python3，無法解析 manifest：%s\n' "$MANIFEST"
+  printf 'status=unknown reason=找不到 python3，無法解析 manifest：%s\n' "$MANIFEST"
-  exit 1
+  exit 4
 }
 
 JSC_HOME_DIR="${JSC_HOME:-$HOME/.jsc}"
@@ -53,8 +59,8 @@ try:
     with open(manifest, encoding="utf-8") as fh:
         data = json.load(fh)
 except Exception as exc:
-    print(f"status=blocked reason=manifest 不是有效 JSON：{manifest}：{exc}")
+    print(f"status=unknown reason=manifest 不是有效 JSON：{manifest}：{exc}")
-    sys.exit(1)
+    sys.exit(4)
 
 requires = ((data.get("jsc") or {}).get("requires") or {})
 if not requires: