閘教的那條出路要真的走得通（inkstone/ISEP#112）

comment-carries-task-guard 擋下留言時教人跑 `scripts/ticket subtask …`，
而那一行跑不動。兩個獨立的原因，各自都足以害死它：

① 相對路徑對「貼上去那個人的 cwd」解析。總管的 cwd 是 InkStoneCo/，
   那裡的 scripts/ticket 是停在 08-27 之前的舊複本（grep -c subtask → 0），
   照著貼只印出它「四個動詞」的說明然後 exit 0。
② 用法是手抄的第二份，而它已經漂了：寫了 --assign 卻沒有 --next，
   正本會因為「指派了人卻沒寫 --next」直接擋下（exit 2，在打 API 之前）。

修法是拿掉可以漂的那一格，不是把兩份對齊一次：
- 路徑     scripts/ticket 的 self_path()（__file__ 的絕對路徑）
           ⇒ 印指令的人與跑指令的人是同一個檔案
- 用法     USAGE / usage_text() 一份，閘去 `ticket usage subtask --example` 現要
- 內文模板 body_template() 由 REQUIRED_SECTIONS 現生，跟檢查同源

新增動詞 `ticket usage <verb> [--example] [--parent] [--draft]`。
閘的訊息改成整塊可貼可跑：腳本絕對路徑、母票已填、內文草稿附在同一塊裡，
只剩標題／目標／驗收條件三格是機器不可能知道的。
正本叫不動時 fail-open 的只有「訊息內容」（只指路，不補一份手抄用法），
擋不擋不受影響。

測試 scripts/test-comment-carries-task-guard.sh 22 → 29 條。
新增的 ⑮–㉑ 驗的是「出路走不走得通」，不是「有沒有擋」——
⑱ 把閘 stderr 裡那塊指令原樣抽出來、只填三格、真的執行一次，
離開碼必須是 1（走到網路才停）；是 2 就代表這個病復發。
六個變異全部驗過會紅（相對路徑／閘自己抄用法／--assign 沒配 --next／
模板寫死少一段／fallback 補回手抄用法）。

版本：待總管定版（plugin update 比的是版本號不是內容）。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SP7DiGMfSkWjZ15CHMbPFE

docs/TESTING.md

@@ -71,15 +71,32 @@ bash scripts/test-ticket-where-seen-guard.sh
   人就學會忽略它
 - 最後那組 `fd_is_devnull` 紅 ⇒ 判準從「fstat 問得出來的事實」滑回猜文字
 
-### A11 — 討論串裡的任務要長成子票：22 條
+### A11 — 討論串裡的任務要長成子票：29 條
 ```
 bash scripts/test-comment-carries-task-guard.sh
 ```
-**該看到**：`22/22 通過`。
+**該看到**：`29/29 通過`。全程離線（`TICKET_HOST` 指到連不上的位址），不開任何測試票。
 **失敗**：
 - 「該擋」6 條任一紅 ⇒ 08-26 那則真的掉了的留言形狀（「等雲端那半出貨才驗得了」）會漏抓
 - 「不該擋」10 條任一紅 ⇒ **誤攔，這比漏擋嚴重**——每次留言都被擋，人就學會忽略它
-- 最後兩條（`-F <檔>`）紅 ⇒ 內文放在檔案裡時閘看不到，等於走 `ticket say` 就自動繞過
+- `-F <檔>` 那兩條紅 ⇒ 內文放在檔案裡時閘看不到，等於走 `ticket say` 就自動繞過
+- **⑮～⑳（`inkstone/ISEP#112`）**：這一組驗的不是「有沒有擋」，是**擋下來之後教的那條路走不走得通**。
+  - ⑮⑯ 紅 ⇒ 訊息又印出相對路徑的 `scripts/ticket`。相對路徑是對**貼上去那個人的 cwd**
+    解析的，而 `InkStoneCo/scripts/ticket` 是舊複本（`grep -c subtask` → 0）
+    ⇒ 照著貼會印出它「四個動詞」的說明然後什麼都沒發生。
+  - ⑰ 紅 ⇒ 閘又自己抄了一份用法（它應該去 `ticket usage subtask` 現要）。
+  - **⑱ 紅 ⇒ 最嚴重**：把訊息裡那塊指令原樣抽出來、只填標題／目標／驗收條件三格，
+    **真的執行**，離開碼必須是 1（走到網路才停）。是 2 就表示又被某道閘擋下，
+    這張票的病復發了。
+  - ⑲ 是 ⑱ 的鑑別力對照（把閘原本那組 `--assign` 沒配 `--next` 接回去，必須紅）；
+    ⑲ 綠不了就代表 ⑱ 那條綠燈沒有意義。
+  - ⑳ 紅 ⇒ 內文草稿模板跟 `REQUIRED_SECTIONS` 分家了，會生出「照著貼卻過不了自己那道閘」的票。
+  - ㉑ 紅 ⇒ 正本叫不動時（雲端裝壞、路徑不對）閘不是不擋了，就是**又在訊息裡補了一份手抄用法**。
+    fail-open 的只准是「訊息內容」，不准是「擋不擋」；而補一份副本就是把這張票拔掉的東西裝回去。
+
+> 🔴 **這一組刻意驗訊息內容，不是只驗離開碼。** `system-dev/wiki/mistakes.md`
+> 記過：訊息壞掉時閘照樣 `exit 2`，只看離開碼完全看不出來——
+> 而這張票（`inkstone/ISEP#112`）就是那個形狀的極端版：**閘擋對了，但它教的解法根本不存在。**
 
 ### A12 — 收工要把棒子交回來：10 條
 ```

docs/governance/sdd-gitea-governance.md

@@ -853,7 +853,7 @@ scripts/ticket mine [--user <誰>]
 
 | 閘 | 掛在哪 | 抓什麼 | 測試 |
 |---|---|---|---|
-| `hooks/comment-carries-task-guard.sh` | PreToolUse `Bash` | 留言裡帶「等 X 才…／驗不了／還沒…」這種**未完成的未來式**，卻沒開子票 → 擋一次 | `scripts/test-comment-carries-task-guard.sh`（22 條） |
+| `hooks/comment-carries-task-guard.sh` | PreToolUse `Bash` | 留言裡帶「等 X 才…／驗不了／還沒…」這種**未完成的未來式**，卻沒開子票 → 擋一次 | `scripts/test-comment-carries-task-guard.sh`（29 條） |
 | `hooks/baton-handback-guard.sh` | PostToolUse `Agent\|Task` | 一條線收工，票上**指派／tag／下一步**缺哪一格 → 當場說出來（提醒，不擋） | `scripts/test-baton-handback-guard.sh`（10 條） |
 
 🔴 **兩支閘的誤攔設計**：`comment-carries-task-guard` 同一 session 只擋一次，

docs/hooks-inventory.md

@@ -128,7 +128,7 @@
 | `milestone-due-guard.sh` | AI 想開一個新的里程碑（milestone）卻沒填期限就擋下，**填 `9999-01-01` 一樣擋**——那是「沒有期限」穿了一件期限的衣服，盤點時每一格看起來都有值，其實一格都沒有。只管「建里程碑」這個動作，查詢／改別的欄位都放行。 | 🛑 擋 |
 | `milestone-account-guard.sh` | AI 想直接打 API 把某個里程碑改成「已關閉」，卻**還沒留下「估多久／花多久／差多少／為什麼差」**就擋下。跟上一列是同一條線的兩端：那支管**開**里程碑要有真的期限，這支管**關**的時候要留下帳。走正門 `scripts/milestone-account close` 就會自己算（數字取自 Gitea 的 `created_at`／`due_on`／`closed_at`，不用手填），差超過 ±25% 才要你從**七個固定代號**裡挑一個，而且那個代號要有 Gitea 時間軸撐得住——**不採信自述**。純讀取／建里程碑／改期限／只是談論它／走正門，全部放行；真要手動關就在指令裡加 `milestone-account-ok`（留痕）。 | 🛑 擋 |
 | `reply-identity-guard.sh` | 直接打 Gitea API 貼留言到票上時，內文第一行沒有 `【身份】`（`總管`／`subagent`／`leo`）就擋下——票上多條線並行時，看不出哪一則是誰寫的。純讀取、走 `scripts/ticket` 正門、指令裡加 `reply-identity-ok` 都放行。 | 🛑 擋 |
-| `comment-carries-task-guard.sh` | AI 要在票裡留一則「等某某上線才驗得了」這種**還沒做完的事**，卻沒有把它開成一張子票時，擋一次。留言沒人會回頭讀，票的 open／closed 撈一次就看得到。 | 🛑 擋（同一輪只擋一次） |
+| `comment-carries-task-guard.sh` | AI 要在票裡留一則「等某某上線才驗得了」這種**還沒做完的事**，卻沒有把它開成一張子票時，擋一次。留言沒人會回頭讀，票的 open／closed 撈一次就看得到。**擋下來時印的是一整塊可以直接貼著跑的指令**（腳本用絕對路徑、母票已經填好、內文草稿附在同一塊裡），那塊字是跟 `scripts/ticket usage subtask` 現要的，不是閘自己抄的一份（`inkstone/ISEP#112`）。 | 🛑 擋（同一輪只擋一次） |
 | `search-is-not-proof-guard.sh` | AI 用知識庫的**搜尋**找到一筆東西，然後把那筆東西的原始編號直接貼進票裡或派工單裡，當成「某個功能壞了」的證據——而它從沒用正規的檢索路徑去查過那筆——擋一次。你關心的是：不會再有人拿錯的方法量出一個錯的結論，然後退回一張其實已經做完的票。 | 🛑 擋（同一輪只擋一次） |
 | `line-needs-own-worktree.sh` | 一條派工線想在**大家共用的那份工作目錄**裡切分支（`git checkout`／`git switch`）就擋下，叫它先開一份自己的 worktree。你關心的是：不會再有人交回工作時把某個 repo 留在自己的分支上，而下一個人在同一個目錄跑出貨、讀到的是別人留下的 HEAD。**總管在自己的目錄裡切分支不管**（那是他的目錄）；已經在自己 worktree 裡的切換全部放行；還原檔案（`git checkout -- 檔`）不管。擋下來的同時會順手把「指向空氣」的 worktree 登記清掉。 | 🛑 擋 |
 | `diagnosis-evidence-guard.sh` | 你想把一段有份量的東西寫上票，而這個 session **沒派人去查過那張票**、那段話裡也**沒有任何走得過去的出處**（檔案:行號／commit／comment 號／票號／網址／貼出來的實測輸出）就擋一次——未經調查的診斷寫在票上會長得像事實，工人會照著它去驗證而不是去查。派過人查、或把出處帶上，都放行；一句短回覆不管。 | 🛑 擋 |

hooks/comment-carries-task-guard.sh

@@ -103,10 +103,64 @@ WARNED="/tmp/.comment-task-guard-warned-$SID"
 [ -f "$WARNED" ] && exit 0     # 同一 session 只擋一次，不鬼打牆
 date +%s > "$WARNED"
 
-cat >&2 <<EOF
+# ── 出路要真的走得通（inkstone/ISEP#112）────────────────────────────────
+#
+# 這支閘 08-27 上線時印的是 `scripts/ticket subtask …`，而那一行**跑不動**，
+# 兩個獨立的原因（2026-08-31 實測，各自都足以害死它）：
+#
+#   ① 相對路徑對「貼上去那個人的 cwd」解析。總管的 cwd 是 `InkStoneCo/`，
+#      那裡的 `scripts/ticket` 是舊複本（`grep -c subtask` → 0），
+#      照著貼只會印出它「四個動詞」的說明然後 exit 0。
+#   ② 用法是**手抄的第二份**，而它已經漂了：寫了 `--assign` 卻沒有 `--next`，
+#      而正本會因為「指派了人卻沒寫 --next」直接擋下。
+#
+# 票上的判決：「**當它教的做法不存在，它就從『幫你』變成『擋你』**——
+#   而且被擋的人當下正在做別的事，最可能的反應是找個理由繞過去。」
+#
+# 🔴 所以這裡**不准再抄一份用法**。整塊指令去正本要：
+#      "$TICKET" usage subtask --example --parent <母票> --draft <草稿路徑>
+#    正本印的路徑是它自己的 `__file__`（絕對路徑）⇒ 印指令的人與跑指令的人
+#    是同一個檔案，沒有第二種可能。
+ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+TICKET="$ROOT/scripts/ticket"
+
+# 母票是誰：兩條路都認（走正門 `ticket say`，或直接打 API）。認不出來就留 <母票 …>，
+# 正本那邊會照樣印出可讀的樣板——**寧可少填一格，不要猜錯一張票**。
+PARENT=$(printf '%s' "$CMD" | python3 -c '
+import re, sys
+c = sys.stdin.read()
+m = re.search(r"/repos/([\w.-]+)/([\w.-]+)/issues/(\d+)/comments", c)
+if m:
+    print("%s/%s#%s" % m.groups()); raise SystemExit
+m = re.search(r"\bticket\s+say\s+([\w.-]+)/([\w.-]+)#(\d+)", c)
+if m:
+    print("%s/%s#%s" % m.groups())
+' 2>/dev/null)
+
+DRAFT="/tmp/isep-subtask-$SID.md"
+EXAMPLE=$(python3 "$TICKET" usage subtask --example \
+            ${PARENT:+--parent "$PARENT"} --draft "$DRAFT" 2>/dev/null) || EXAMPLE=""
+MORE=$(python3 "$TICKET" usage subtask 2>/dev/null) || MORE=""
+
+# fail-open 的**訊息**（不是閘）：正本叫不動時仍然要擋，但不准在這裡補一份手抄用法
+# ——那樣就把剛拔掉的那個副本裝回來了。只指路，指到唯一那一份。
+LEAD="整段複製貼上就跑得動。腳本是絕對路徑、母票已經填好、必填段落已經在草稿裡，
+  只剩三格是機器不可能知道的：標題、目標、驗收條件——改完那三格再送。
+  （下面這塊**不要縮排**，\`<<'MD'\` 的結束標記要頂在行首。）"
+if [ -z "$EXAMPLE" ]; then
+  LEAD="把它長成子票。**這台機器叫不動正本，所以下面只給路、不給整塊指令**
+  ——這裡刻意不補一份手抄的用法，那份副本正是 inkstone/ISEP#112 拔掉的東西。"
+  EXAMPLE="python3 $TICKET usage subtask --example"
+  MORE=""
+fi
+
+# 🔴 訊息一律用 `<<'EOF'`（標記加引號）＋ 事後用 python 換佔位符。
+#    ISEP wiki mistakes.md 記過：不加引號的 heredoc 會把訊息裡的反引號當命令執行，
+#    而**閘照樣 exit 2，所以只看離開碼的測試完全看不出來**。
+MSG=$(cat <<'EOF'
 🎫 這則留言裡藏著一件**還沒做完的事**，而它現在只是文字。
 
-命中的詞：$HIT
+命中的詞：__HIT__
 
 【leo 2026-08-27】「**每個任務長出子票做為這張票的相依⋯⋯票沒完工可以察覺嗎？**」
 
@@ -115,18 +169,32 @@ cat >&2 <<EOF
   08-26 18-23  總管真的出貨了                                          ← 條件滿足，沒人知道
   08-27 11:xx  leo 問「這 14 小時前的，你派了還是沒派？」               ← 才被撿起來
 
-【怎麼做】把它長成子票，Gitea 原生相依會**硬擋**母票關閉（實測 412）：
+【怎麼做】__LEAD__
 
-  scripts/ticket subtask <母票 owner/repo#N> \\
-      --title "身為<誰>，我要<什麼>，我才<為什麼>" \\
-      -F <內文檔> --label s/todo --assign <誰做>
-
-  ⇒ 子票沒關，母票關不掉。**不是提醒，是平台保證。**
+__EXAMPLE__
+__MORE__
+  ⇒ 子票沒關，母票關不掉。**不是提醒，是平台保證**（Gitea 原生相依，實測 412）。
 
 【粒度】leo 2026-08-27：「**小任務做完就關閉，不會讓池子爆掉，
   每個事情沒有歷史記錄才是大問題**」⇒ 判準是「這件事需要被記得嗎」，
   傾向**多開票**。不要用「會不會太多」當理由不開。
 
-【真的不是待辦】在指令裡加 \`no-subtask: <一句理由>\` 重送（留痕）。
+【真的不是待辦】在指令裡加 `no-subtask: <一句理由>` 重送（留痕）。
 EOF
+)
+
+MORE_BLOCK=""
+[ -n "$MORE" ] && MORE_BLOCK="
+  還有哪些參數（指派給誰＋下一步、旅程標籤、換 repo）：
+$(printf '%s' "$MORE" | sed 's/^/    /; s/[[:space:]]*$//')
+"
+
+HIT="$HIT" LEAD="$LEAD" EXAMPLE="$EXAMPLE" MORE_BLOCK="$MORE_BLOCK" MSG="$MSG" python3 -c '
+import os, sys
+m = os.environ["MSG"]
+for k in ("HIT", "LEAD", "EXAMPLE"):
+    m = m.replace("__%s__" % k, os.environ.get(k, ""))
+m = m.replace("__MORE__", os.environ.get("MORE_BLOCK", ""))
+sys.stderr.write(m + "\n")
+'
 exit 2

scripts/test-comment-carries-task-guard.sh

@@ -64,6 +64,158 @@ printf '已驗完，全部綠燈\n' > "$TMPF"
 run 0 "scripts/ticket say inkstone/arcrun-rag#136 -F $TMPF"
 rm -f "$TMPF" "/tmp/.comment-task-guard-warned-$SID"
 
+echo "── 閘教的那行指令要真的跑得動（inkstone/ISEP#112）──"
+# 🔴 這一組**不看離開碼**，看訊息內容、而且**真的把訊息裡那塊指令執行一次**。
+#    ISEP wiki mistakes.md 記過：訊息壞掉時閘照樣 exit 2，只驗離開碼完全看不出來。
+#    這張票就是那個形狀的極端版——閘擋對了，但它教的解法**根本不存在**。
+SID2=test-cctg-msg-$$
+rm -f "/tmp/.comment-task-guard-warned-$SID2"
+PAYLOAD=$(python3 -c '
+import json, sys
+cmd = ("curl -X POST \"$API/repos/inkstone/arcrun-rag/issues/136/comments\" "
+       "-d \x27{\"body\":\"Phase 1 的驗收在雲端那半出貨之前驗不了\"}\x27")
+print(json.dumps({"session_id": sys.argv[1], "tool_name": "Bash",
+                  "tool_input": {"command": cmd}}, ensure_ascii=False))
+' "$SID2")
+MSGFILE=$(mktemp)
+printf '%s' "$PAYLOAD" | bash "$H" 2>"$MSGFILE" >/dev/null
+rm -f "/tmp/.comment-task-guard-warned-$SID2"
+
+RESFILE=$(mktemp)
+PAYFILE=$(mktemp); printf '%s' "$PAYLOAD" > "$PAYFILE"
+rm -f "/tmp/.comment-task-guard-warned-$SID2"
+MSGFILE="$MSGFILE" RESFILE="$RESFILE" GUARD="$H" PAYLOAD="$PAYFILE" python3 - <<'PY'
+import io, os, re, subprocess, sys
+
+msg = io.open(os.environ["MSGFILE"], encoding="utf-8").read()
+res = []
+
+
+def t(ok, name, detail=""):
+    res.append((bool(ok), name, detail))
+
+
+here = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) \
+    if "__file__" in dir() else os.getcwd()
+ticket = os.path.realpath(os.path.join(os.getcwd(), "scripts", "ticket"))
+
+# ⑮ 那塊指令**真正要執行的那一行**，開頭是絕對路徑，而且指到這一份正本。
+#    🔴 判準刻意放在「要執行的那一行」上，不是「訊息裡出現過的所有路徑」——
+#      後者在相對路徑混進來時是**空過**的（別的行還有絕對路徑，all() 照樣真）。
+#      2026-08-31 變異測試當場抓到：把 example 改回相對路徑，舊寫法的 ⑮ 沒紅。
+run_line = ""
+for l in msg.splitlines():
+    if " subtask " in l and l.strip().endswith("\\"):
+        run_line = l.strip()
+        break
+first = run_line.split()[0] if run_line else ""
+t(first.startswith("/") and os.path.realpath(first) == ticket,
+  "⑮ 要執行的那一行開頭是絕對路徑，且就是這一份正本",
+  "那一行：%s" % (run_line or "（找不到）"))
+
+# ⑯ 訊息裡**不准**出現相對的 `scripts/ticket`
+#    相對路徑是對「貼上去那個人的 cwd」解析的，而 InkStoneCo/scripts/ticket 是舊複本。
+rel = [l for l in msg.splitlines()
+       if re.search(r"(?<![\w/])scripts/ticket\b", l)]
+t(not rel, "⑯ 訊息裡沒有任何相對路徑的 scripts/ticket",
+  "違規行：%s" % (rel[:2] or ""))
+
+# ⑰ 訊息裡的用法區塊 ＝ `ticket usage subtask` 的輸出（**一字不差**）
+#    這就是「不再有第二份可以漂」的機械證明：漂了這一條當場紅。
+usage = subprocess.run([sys.executable, ticket, "usage", "subtask"],
+                       capture_output=True, text=True).stdout.strip()
+flat_msg = "\n".join(l.strip() for l in msg.splitlines())
+flat_use = "\n".join(l.strip() for l in usage.splitlines())
+t(flat_use and flat_use in flat_msg,
+  "⑰ 訊息裡的用法就是 `ticket usage subtask` 的輸出，沒有第二份",
+  "" if flat_use in flat_msg else "訊息裡找不到正本印的用法")
+
+
+def extract_block(m):
+    """把訊息裡那塊指令**原樣**抽出來——不重新產生，否則就驗不到漂移。"""
+    lines = m.splitlines()
+    i = next(k for k, l in enumerate(lines) if l.startswith("cat > "))
+    md = next(k for k in range(i, len(lines)) if lines[k] == "MD")
+    j = next(k for k in range(md + 1, len(lines)) if not lines[k].endswith("\\"))
+    return "\n".join(lines[i:j + 1])
+
+
+def fill(block):
+    """只填三格機器不可能知道的：標題、目標、驗收條件。其餘一個字都不改。"""
+    block = (block.replace("<誰>", "跑這行指令的人")
+                  .replace("<什麼>", "它真的跑得動")
+                  .replace("<為什麼>", "不會被迫去繞過它"))
+    return re.sub(r"<[^<>\n]+>", "測試填的內容", block)
+
+
+ENV = dict(os.environ, TICKET_HOST="http://127.0.0.1:9",
+           GITEA_TOKEN_CLAUDE_CODE="dummy", GITEA_TOKEN="dummy")
+
+# ⑱ ★ 把它原樣貼上、只填那三格，**真的跑一次**。
+#    離開碼 2 ＝ 被某道閘擋下（動詞不存在／旗標不成組／標題不合格…）＝ 這張票的病復發
+#    離開碼 1 ＝ 一路走到網路才炸（TICKET_HOST 指到連不上的位址）＝ 參數全部過關
+try:
+    blk = fill(extract_block(msg))
+    r = subprocess.run(["bash", "-c", blk], capture_output=True, text=True, env=ENV)
+    code = r.returncode
+except StopIteration:
+    blk, code, r = "", -1, None
+t(code == 1, "⑱ ★ 訊息裡那塊指令原樣貼上就跑得完（走到網路才停，不是被閘擋）",
+  "離開碼 %s（2 ＝ 又被某道閘擋下）%s"
+  % (code, ("｜" + (r.stderr or "").strip().splitlines()[0][:80]) if r and code == 2 else ""))
+
+# ⑲ 鑑別力對照：⑱ 不是「只要跑就會過」。
+#    把閘**原本**印的那組旗標（`--assign <誰做>` 沒配 `--next`）接回去 ⇒ 必須紅。
+if blk:
+    bad = blk.rstrip() + " --assign claude-code"
+    rb = subprocess.run(["bash", "-c", bad], capture_output=True, text=True, env=ENV)
+    t(rb.returncode == 2,
+      "⑲ 對照組：閘原本那組旗標（--assign 沒配 --next）確實跑不完",
+      "離開碼 %s（要是 2；不是 2 就表示 ⑱ 沒有鑑別力）" % rb.returncode)
+else:
+    t(False, "⑲ 對照組：抽不出指令區塊", "")
+
+# ⑳ 草稿模板與必填檢查**同源**：模板裡一定有 REQUIRED_SECTIONS 的每一段。
+#    寫死一份模板的話，有人往 REQUIRED_SECTIONS 加一段就會生出
+#    「照著貼卻過不了自己那道閘」的票——正是這張票要修的形狀。
+req = subprocess.run(
+    [sys.executable, "-c",
+     "import runpy,sys;m=runpy.run_path(sys.argv[1]);"
+     "print('\\x00'.join(m['REQUIRED_SECTIONS']));"
+     "print(m['body_template']())", ticket],
+    capture_output=True, text=True)
+head, _, tmpl = req.stdout.partition("\n")
+secs = [x for x in head.split("\x00") if x]
+t(secs and all(x in tmpl for x in secs) and all(x in msg for x in secs),
+  "⑳ 草稿模板由 REQUIRED_SECTIONS 現生，訊息裡也齊",
+  "必填段：%s" % secs)
+
+# ㉑ 正本叫不動時（雲端裝壞、路徑不對）：**閘照樣擋**，而且**不准就地補一份手抄用法**
+#    ——那份副本正是這張票拔掉的東西。fail-open 的是「訊息內容」，不是「擋不擋」。
+fb = subprocess.run(["bash", os.environ["GUARD"]],
+                    input=io.open(os.environ["PAYLOAD"], encoding="utf-8").read(),
+                    capture_output=True, text=True,
+                    env=dict(os.environ, CLAUDE_PLUGIN_ROOT="/tmp/isep-no-such-root"))
+fbmsg = fb.stderr
+t(fb.returncode == 2 and "usage subtask" in fbmsg
+  and "--title" not in fbmsg and "[--journey" not in fbmsg,
+  "㉑ 正本叫不動時仍然擋，且只指路、不補一份手抄用法",
+  "離開碼 %s｜訊息裡有沒有手抄用法：%s"
+  % (fb.returncode, "有（違規）" if "[--journey" in fbmsg else "沒有"))
+
+npass = 0
+for ok, name, detail in res:
+    print("  %s %s%s" % ("✅" if ok else "❌", name,
+                         ("　※ " + detail) if (detail and not ok) else ""))
+    npass += 1 if ok else 0
+io.open(os.environ["RESFILE"], "w", encoding="utf-8").write(
+    "%d %d" % (npass, len(res) - npass))
+PY
+read -r P2 F2 < "$RESFILE"
+PASS=$((PASS + P2)); FAIL=$((FAIL + F2))
+rm -f "$MSGFILE" "$RESFILE" "$PAYFILE" "/tmp/isep-subtask-$SID2.md" \
+      "/tmp/.comment-task-guard-warned-$SID2"
+
 echo
 echo "$PASS/$((PASS+FAIL)) 通過"
 [ "$FAIL" = 0 ]

scripts/ticket

@@ -26,6 +26,8 @@ leo 2026-08-16 三句話，本工具就是它們的機械化：
     ticket mine [--user <誰>]                     撈一次：棒子在誰手上、每根下一步是什麼
     ticket loose                                  撈一次：下游都關了、自己還開著的頂層票
 
+    ticket usage <動詞> [--example]               用法的唯一真相源——**閘印的那一行從這裡來**
+
 票的寫法：`owner/repo#N`，例：`inkstone/InkStoneCo#44`
 """
 import json
@@ -504,6 +506,10 @@ def _writeback(owner, repo, num, deliv):
                           for i in open_left]
                 lines += ["", "⇒ 本票維持原狀，不要當成可以收了。"]
             else:
+                # 🔴 這一段是要**貼進 Gitea 留言**的，所以 `ticket close` 刻意寫成相對的
+                #    ——留言會被別台機器讀到，寫死本機的絕對路徑等於寫死一個他們沒有的檔案。
+                #    絕對路徑那條規約（inkstone/ISEP#112）管的是**印到終端機、要人複製貼上**的字，
+                #    兩者分界就是這一句：「這行字會被誰複製、在哪台機器上跑？」
                 lines += ["", "**這是最後一張下游——本票的下游已經全部關閉。**", "",
                           f"{BATON_MARK}　→ `{HANDBACK_TO}`", "",
                           "**下一步**：驗一次頂層要的東西真的到齊了，到齊就 "
@@ -719,6 +725,134 @@ def writeback_plan(parent_state, parent_deps):
     return ("note" if open_left else "handback"), open_left
 
 
+# ══════════════════════════════════════════════════════════════════════════
+# inkstone/ISEP#112 — 閘教的那行指令要真的跑得動
+#
+# 票上的原話：「**當它教的做法不存在，它就從『幫你』變成『擋你』**——
+#   而且被擋的人當下正在做別的事，最可能的反應是找個理由繞過去。」
+#
+# 那次它為什麼跑不動，兩個獨立的原因（2026-08-31 實測，兩個都會單獨害死它）：
+#
+#   ① **相對路徑**。閘印的是 `scripts/ticket subtask …`，而相對路徑是對
+#      **貼上去那個人的 cwd** 解析的。總管的 cwd 是 `InkStoneCo/`，那裡的
+#      `scripts/ticket` 是本檔停在 2026-08-27 之前的**舊複本**：
+#          grep -c subtask InkStoneCo/scripts/ticket  → 0
+#      它的 docstring 只列到「四個動詞」，於是照著貼會印出那段說明、exit 0、
+#      什麼都沒發生 —— 正是票上寫的症狀。
+#      （`hooks/lib/beacon_report.py` ② 已經會在 SessionStart 報這個舊複本，
+#        但**報告不會改掉閘印出來的那一行**。）
+#
+#   ② **用法各寫一份**。閘手寫了一段用法，`cmd_subtask` 的 die() 又寫了一段。
+#      兩份已經漂了：閘那份寫 `--assign <誰做>` 卻**沒有 `--next`**，
+#      而 cmd_subtask 會因為「🚫 指派了人卻沒寫 --next。」直接 die（實測 exit 2，
+#      而且是在打任何 API 之前，所以離線也複現得出來）。
+#      ⇒ 就算路徑對了，那一行照樣跑不完。
+#
+# 🔴 修法是**拿掉可以漂的那一格**，不是把兩份對齊一次：
+#      · 路徑     → self_path()，`__file__` 的絕對路徑。印指令的人與跑指令的人
+#                   是同一個檔案，沒有第二種可能。
+#      · 用法     → USAGE 這一份。閘去 `ticket usage subtask` 拿，不自己抄。
+#      · 內文模板 → body_template() 由 REQUIRED_SECTIONS 現生。
+#                   檢查與模板同一個來源 ⇒ 模板不可能少一段。
+# ══════════════════════════════════════════════════════════════════════════
+
+def self_path():
+    """這支腳本自己的絕對路徑。**閘印出來的指令一律用它。**
+
+    不用 `sys.argv[0]`：那是「別人怎麼叫我」，被相對路徑叫進來時它就是相對的。
+    `__file__` 走 realpath 是「我是誰」——貼到任何 cwd 底下都指得回同一個檔案。
+    """
+    return os.path.realpath(__file__)
+
+
+# 每一段必填欄位的草稿提示。**鍵一定要是 REQUIRED_SECTIONS 裡的字串**——
+# 對不上也不會漏掉那一段（下面會退成 `<填這裡>`），只是提示變笨。
+SECTION_HINTS = {
+    "## 目標": "<這件事要達成什麼。寫目的，不要寫做法>",
+    "## 驗收條件": "- [ ] <怎麼算做完——別人可以自己跑一次的那種>",
+    "## deliverable 類型": "code",
+}
+
+
+def body_template():
+    """子票內文的草稿，**用 REQUIRED_SECTIONS 現生**。
+
+    🔴 不要把這段字面寫死：寫死就變成第二份，而 `cmd_subtask` 檢查的是
+       REQUIRED_SECTIONS。有人往那個清單加一段，寫死的模板就會生出一張
+       **照著貼卻過不了自己那道閘**的票 —— 這張票要修的就是這個形狀。
+    """
+    out = []
+    for sec in REQUIRED_SECTIONS:
+        out.append(sec)
+        out.append(SECTION_HINTS.get(sec, "<填這裡>"))
+        out.append("")
+    return "\n".join(out).rstrip() + "\n"
+
+
+def subtask_example(parent=None, draft=None):
+    """可以整段複製貼上的那一塊：先把內文草稿寫出來，再開子票。
+
+    刻意**不放 `--assign`**：`--assign` 沒配 `--next` 會被擋（見 cmd_subtask），
+    而一行印出來卻跑不完的指令，正是這張票在修的病。要指派的人看 USAGE 那份，
+    那裡兩個參數是綁在一起寫的。
+
+    留在 <> 裡的只有三件**機器不可能知道**的事：標題、目標、驗收條件。
+    其餘（腳本路徑、母票、必填段落、標籤）全部已經填好。
+    """
+    parent = parent or "<母票 owner/repo#N>"
+    draft = draft or "/tmp/subtask-body.md"
+    return (
+        "cat > %s <<'MD'\n" % draft
+        + body_template()
+        + "MD\n"
+        + "%s subtask %s \\\n" % (self_path(), parent)
+        + '    --title "身為<誰>，我要<什麼>，我才<為什麼>" \\\n'
+        + "    -F %s --label s/todo\n" % draft
+    )
+
+
+# 🔴 `{bin}` 一定要留成佔位符、由 usage_text() 現填 self_path()：
+#    用法裡寫死 `ticket` 或 `scripts/ticket`，讀的人照著貼就又踩回這張票的坑。
+USAGE = {
+    "subtask":
+        "用法：{bin} subtask <母票 owner/repo#N> --title \"<User Story>\" -F <內文檔>\n"
+        "      [--repo <收件 repo，預設跟母票同一個>] [--label <s/xxx，預設 s/todo>]\n"
+        "      [--journey <旅程名>]　← 這件事服務哪條使用者旅程（對不上就不要加）\n"
+        "      [--assign <誰做> --next \"<他第一件事要做什麼>\"]　← 這兩個是一組，"
+        "指派了就一定要寫下一步\n"
+        "\n（`ticket handoff` 是同一個動作的別名：頂層票 → 下游 repo）",
+}
+
+
+def usage_text(verb):
+    """用法的**唯一**一份，路徑現填成絕對路徑（inkstone/ISEP#112）。"""
+    return USAGE[verb].format(bin=self_path())
+
+
+def cmd_usage(argv):
+    """把「用法」與「可以貼著跑的那一塊」交給同一個地方產生（inkstone/ISEP#112）。
+
+    閘的訊息**呼叫這一支**，不自己抄一份 ⇒ 訊息與能跑的指令之間沒有第二份可以漂。
+    """
+    verbs = "|".join(sorted(USAGE))
+    if not argv or argv[0] not in USAGE:
+        die("用法：ticket usage <%s> [--example] [--parent <owner/repo#N>] "
+            "[--draft <內文檔路徑>]\n"
+            "  --example ＝ 印一塊可以整段貼著跑的指令（路徑是絕對路徑，母票已填好）" % verbs)
+    verb = argv[0]
+
+    def opt(name, default=None):
+        return argv[argv.index(name) + 1] if name in argv else default
+
+    if "--example" in argv:
+        if verb != "subtask":
+            die("🚫 `ticket usage %s --example` 還沒有可貼著跑的版本。\n"
+                "   先看用法：ticket usage %s" % (verb, verb))
+        sys.stdout.write(subtask_example(opt("--parent"), opt("--draft")))
+        return
+    sys.stdout.write(usage_text(verb).rstrip() + "\n")
+
+
 # ── subtask ──────────────────────────────────────────────────────────────
 def cmd_subtask(argv):
     """把「討論串裡的一件事」長成看得見的子票，並掛成母票的 Gitea 原生相依。
@@ -737,11 +871,9 @@ def cmd_subtask(argv):
     不是「新開一條線」——那道閘擋的是後者。
     """
     if len(argv) < 1:
-        die("用法：ticket subtask <母票 owner/repo#N> --title \"<User Story>\" -F <內文檔>\n"
-            "      [--repo <收件 repo，預設跟母票同一個>] [--label <s/xxx，預設 s/todo>]\n"
-            "      [--journey <旅程名>]　← 這件事服務哪條使用者旅程（對不上就不要加）\n"
-            "      [--assign <誰做> --next \"<他第一件事要做什麼>\"]　← 指派了就一定要寫下一步\n"
-            "\n（`ticket handoff` 是同一個動作的別名：頂層票 → 下游 repo）")
+        # 🔴 用法只有 USAGE 那一份（inkstone/ISEP#112）。這裡不准再抄一段：
+        #    抄一段就是又多一個會漂的副本，而閘印的那一行也是從 USAGE 來的。
+        die(usage_text("subtask"))
     powner, prepo, pnum = parse_ref(argv[0])
 
     def opt(name, default=None):
@@ -830,7 +962,7 @@ def cmd_subtask(argv):
         print(f"   旅程：`{jlabel}`（母子兩端都貼——只貼一端就聚不起來）")
     else:
         print("   旅程：沒有貼（沒給 --journey）。對得上就補一次："
-              f"`ticket subtask … --journey <旅程名>`；對不上就不要硬湊。")
+              f"`{self_path()} subtask … --journey <旅程名>`；對不上就不要硬湊。")
     print(f"\n📌 母票 {powner}/{prepo}#{pnum} 目前有 {len(openn)} 張未關的相依：")
     for i in deps:
         mark = "◻" if i["state"] == "open" else "☑"
@@ -1026,8 +1158,10 @@ def cmd_loose(argv):
         for d in deps:
             print(f"      ☑ {d['repository']['full_name']}#{d['number']}"
                   f"　{d['title'][:52]}")
-        print(f"    → 驗過就關：ticket close {full}#{n} --deliverable <URL>")
-        print(f"      還缺東西：ticket subtask {full}#{n} --title \"<US>\" -F <檔>")
+        # 絕對路徑（inkstone/ISEP#112）：相對的 `scripts/ticket` 會被貼到別的 cwd 底下，
+        # 在那裡叫到的可能是本檔的舊複本（`InkStoneCo/scripts/ticket` 就是）。
+        print(f"    → 驗過就關：{self_path()} close {full}#{n} --deliverable <URL>")
+        print(f"      還缺東西：{self_path()} subtask {full}#{n} --title \"<US>\" -F <檔>")
         print()
 
     print("📌 這張表撈的是**機械事實**（相依邊的 state），不是猜文字。")
@@ -1038,7 +1172,8 @@ def cmd_loose(argv):
 
 CMDS = {"where": cmd_where, "say": cmd_say, "new": cmd_new, "close": cmd_close,
         "decide": cmd_decide, "subtask": cmd_subtask, "handoff": cmd_subtask,
-        "handback": cmd_handback, "mine": cmd_mine, "loose": cmd_loose}
+        "handback": cmd_handback, "mine": cmd_mine, "loose": cmd_loose,
+        "usage": cmd_usage}
 
 if __name__ == "__main__":
     if len(sys.argv) < 2 or sys.argv[1] not in CMDS:

system-dev/wiki/mistakes.md

@@ -154,3 +154,48 @@ leo 當場：「**這些為什麼不寫到票裡？**」
 📌 KBDB 缺這一段: 2026-08-31 用 `kbdb_search(mode='semantic')` 查
    「SDD 生命週期／單一活性／取消 Active SDD」**0 命中**（最接近的是 2026-08-09
    一張講 SDD × Gitea 整合摩擦的卡，那是裁決之前）。⇒ 這條開發史還沒進 KBDB。
+
+## ⚠️ MISTAKE: 閘擋對了，但它印出來的那條出路**跑不動**
+
+票: `inkstone/ISEP#112`
+日期: 2026-08-31
+
+症狀: `comment-carries-task-guard.sh` 擋下留言時教你跑
+      `scripts/ticket subtask …`。照著貼，會印出一段「四個動詞」的說明然後
+      什麼都沒發生。被擋的人當下正在做別的事，最可能的反應是**找個理由繞過去**。
+
+實查: 兩個**各自獨立**的原因，任何一個單獨存在都足以害死它——
+  ① **相對路徑**。閘印的是 `scripts/ticket`，而相對路徑是對
+     **貼上去那個人的 cwd** 解析的。總管的 cwd 是 `InkStoneCo/`，
+     那裡的 `scripts/ticket` 是正本停在 2026-08-27 之前的舊複本：
+     `grep -c subtask InkStoneCo/scripts/ticket` → **0**（正本是 10）。
+     ⇒ 「`subtask` 這個子命令不存在」這個結論**在那個 cwd 底下是真的**。
+  ② **用法各寫一份**。閘手抄了一段用法，`cmd_subtask` 的 `die()` 又寫了一段。
+     兩份已經漂了：閘那份寫 `--assign <誰做>` 卻**沒有 `--next`**，
+     而正本會因為「指派了人卻沒寫 --next」直接擋下（實測 exit 2）。
+     ⇒ **就算路徑對了，那一行照樣跑不完。**
+
+原因: 閘的訊息與它教的那支工具是**兩份各自維護的字**。
+      `hooks/lib/beacon_report.py` ② 早就會在 SessionStart 報「專案裡有舊複本」，
+      **但報告不會改掉閘印出來的那一行**——知道有這個坑，跟那一行會不會踩到它，
+      是兩件事。
+
+正確做法:
+  - **路徑**：印出來要人複製的指令，一律用正本自己的 `__file__` 絕對路徑
+    （`scripts/ticket` 的 `self_path()`）。印指令的人與跑指令的人是同一個檔案，
+    沒有第二種可能。
+    ⚠️ 分界線是「**這行字會被誰複製、在哪台機器上跑？**」——
+    要**貼進 Gitea 留言**的指令反而要維持相對寫法（留言會被別台機器讀到）。
+  - **用法**：只留一份（`scripts/ticket` 的 `USAGE`／`usage_text()`），
+    閘去 `ticket usage subtask --example` 現要，不自己抄。
+  - **模板**：子票內文草稿由 `REQUIRED_SECTIONS` 現生（`body_template()`），
+    跟檢查同源 ⇒ 不可能生出「照著貼卻過不了自己那道閘」的票。
+
+🔴 **驗法要驗到「它跑不跑得動」，不是「它有沒有擋」。**
+`scripts/test-comment-carries-task-guard.sh` ⑱ 把閘 stderr 裡那塊指令
+**原樣抽出來、只填三格、真的執行一次**：離開碼 1（走到網路才停）＝過，
+2（被某道閘擋下）＝這個病復發。⑲ 是它的鑑別力對照組。
+
+📌 推廣：**一支閘的價值是「擋下來 ＋ 給一條走得通的路」。**
+出路走不通時它不是幫你，是擋你——而被擋的人不會停下來修閘，
+他會去找繞過去的方法。所以「出路能不能跑」要跟「判準準不準」一樣被測。