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

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