wiki: 記一條坑——閘的釋放章 stat -f %m 先，雲端 Linux 永遠放行不了

三支閘的 stamp_ok/退回機制都用 `stat -f %m … || stat -c %Y …` 取 mtime。
GNU (Linux) 的 `stat -f` 是 --file-system，%m 被當成檔名 ⇒ 把整張檔案系統表印到
stdout（被 $() 收進去）且 exit 1 ⇒ MT 變非數字 ⇒ case *[!0-9]* 命中 ⇒ 釋放章永遠失效。
dev 在 macOS（BSD `-f %m` 正常）所以本機測不出來，一到雲端 Linux 就咬。

實際後果（2026-08-23 雲端 cloud-worker 實撞）：
- prod-write-guard：總管 touch /tmp/.prod-write-ok 也放行不了 ⇒ routine 的心跳打不出去
- main-and-prod-push-guard：arm 章在 Linux 形同虛設
- stage-before-prod-guard：stage 已驗的退回機制失效

改法：GNU 先、BSD 後（stat -c %Y … || stat -f %m …），兩平台都正確。

驗證（Linux）：抽出 patched stamp_ok 實跑——
  新戳記→rc=0（釋放、單次消耗）／無戳記→rc=1（擋）／逾時>900s→rc=1（過期）。
反證：舊順序帶新戳記→rc=2（確認舊版在 Linux 是壞的）。

hooks/main-and-prod-push-guard.sh

@@ -87,7 +87,9 @@ STAMP="/tmp/.main-push-ok"
 stamp_ok() {
   [ -f "$STAMP" ] || return 1
   NOW=$(date +%s 2>/dev/null || echo 0)
-  MT=$(stat -f %m "$STAMP" 2>/dev/null || stat -c %Y "$STAMP" 2>/dev/null || echo 0)
+  # 🔴 GNU (Linux) 先、BSD (macOS) 後——順序反了戳記在雲端永遠失效（見 prod-write-guard.sh 同段註解）：
+  #   GNU 的 `stat -f` 是 --file-system，`%m` 被當成檔名 ⇒ 印出檔案系統表且 exit 1 ⇒ MT 非數字 ⇒ arm 章在 Linux 永不生效。
+  MT=$(stat -c %Y "$STAMP" 2>/dev/null || stat -f %m "$STAMP" 2>/dev/null || echo 0)
   case "$NOW$MT" in *[!0-9]*) return 1 ;; esac
   [ "$NOW" -gt 0 ] && [ "$MT" -gt 0 ] || return 1
   [ $((NOW - MT)) -lt 900 ] || return 1

hooks/prod-write-guard.sh

@@ -52,7 +52,11 @@ STAMP="/tmp/.prod-write-ok"
 stamp_ok() {
   [ -f "$STAMP" ] || return 1
   NOW=$(date +%s 2>/dev/null || echo 0)
-  MT=$(stat -f %m "$STAMP" 2>/dev/null || stat -c %Y "$STAMP" 2>/dev/null || echo 0)
+  # 🔴 GNU (Linux) 先、BSD (macOS) 後——順序反了戳記在雲端永遠失效：
+  #   GNU 的 `stat -f` 是 --file-system，`%m` 被當成檔名 ⇒ 把整張檔案系統表印到
+  #   stdout（被 $() 收進去）且 exit 1 ⇒ MT 變非數字 ⇒ 這道閘的釋放章在 Linux 永不生效。
+  #   dev 在 macOS（BSD `-f %m` 正常）所以沒被抓到，一到雲端 Linux 就咬（實測 2026-08-23）。
+  MT=$(stat -c %Y "$STAMP" 2>/dev/null || stat -f %m "$STAMP" 2>/dev/null || echo 0)
   case "$NOW$MT" in *[!0-9]*) return 1 ;; esac
   [ "$NOW" -gt 0 ] && [ "$MT" -gt 0 ] || return 1
   [ $((NOW - MT)) -lt 900 ] || return 1

hooks/stage-before-prod-guard.sh

@@ -172,7 +172,8 @@ for STAMP in /tmp/.stage-ok-by-leo /tmp/.stage-verified; do
   #    抽數字會得到天文數字 ⇒ `now - t` 是**負數** ⇒ `< 21600` 成立 ⇒ **永遠放行**。
   #    ⇒ 只有「不晚於現在」的時間戳才算數；不合理就退回 mtime，別當成通過。
   if [ "$t" -eq 0 ] || [ "$t" -gt "$now" ]; then
-    t=$(stat -f %m "$STAMP" 2>/dev/null || stat -c %Y "$STAMP" 2>/dev/null || echo 0)
+    # 🔴 GNU (Linux) 先、BSD (macOS) 後（見 prod-write-guard.sh 同段註解）：反了 stat -f %m 會在 Linux 印檔案系統表 ⇒ t 非數字 ⇒ 退回機制失效。
+    t=$(stat -c %Y "$STAMP" 2>/dev/null || stat -f %m "$STAMP" 2>/dev/null || echo 0)
   fi
   [ "$t" -gt 0 ] && [ "$((now - t))" -lt 21600 ] && exit 0   # 6 小時內驗過 stage → 放行
 done

system-dev/wiki/mistakes.md

@@ -35,3 +35,20 @@ Gitea 上**一個 release tag 都沒有**。
 ⇒ 「東西做出來了」與「有人在用它」是兩件事，而只有後者算交付。
 ⇒ 判準：**去執行環境查它有沒有被載入**（`claude plugin list` / `claude plugin details`），
    不要從 repo 裡有什麼檔案去推論。
+
+## ⚠️ MISTAKE: 閘的「釋放章」用 `stat -f %m` 先，雲端 Linux 永遠放行不了
+
+2026-08-23 雲端 cloud-worker 實撞：三支閘（`prod-write-guard`／`main-and-prod-push-guard`／
+`stage-before-prod-guard`）取戳記 mtime 都寫成 `stat -f %m … || stat -c %Y …`。
+GNU（Linux）的 `stat -f` 是 `--file-system`，`%m` 被當成**檔名** ⇒ 把整張檔案系統表印到
+stdout（被 `$()` 收進去）且 exit 1 ⇒ 時間變數變非數字 ⇒ `case *[!0-9]*` 命中 ⇒ 釋放章判無效。
+後果：總管 `touch /tmp/.prod-write-ok` 在雲端**從沒生效過**，連 routine 要求的心跳都打不出去。
+
+⇒ 正確做法：**GNU 先、BSD 後** → `stat -c %Y … || stat -f %m …`（Linux 走前者、macOS 走後者）。
+⇒ 為什麼本機測不出來：dev 在 macOS，BSD `stat -f %m` 本來就正常 ⇒ 這種「只咬某一個 OS」的坑，
+   **驗證要在真正會跑的環境（雲端 Linux）跑，不能只在 dev 機跑**。
+⇒ 同款第二例（同日抓到，未修）：`history-first-guard` 的逃生口說明寫 `touch /tmp/.kbdb-down`，
+   但它讀該檔是 `cat` 出來當時間戳算術——**空 `touch` 會炸**，正解是 `date +%s > /tmp/.kbdb-down`。
+   教訓：**逃生口本身也要被測**，不然閘壞了連逃生口都用不了。
+   （修復：分支 `fix/stamp-release-stat-ordering-linux`；回報 ISEP#30 / InkStoneCo#14）
+   日期: 2026-08-23