gate-guard / hooks

一支 PreToolUse(Bash) hook：Claude 要執行的 git commit 帶了 --no-verify、-n，或用 -c core.hooksPath= 當場關掉 hook 時直接 deny，堵住「被 CLAUDE.md gate 擋下就繞過」這條路。 git 的 --no-verify 會跳過 pre-commit hook，gate（scripts/check-claude-md.sh）自己看不到那次 commit。

關鍵檔案

此層約束

• 只擋 git commit。git config core.hooksPath scripts/githooks 是開發本 repo 的標準設定、 git config --get core.hooksPath 是 /dd-init Phase 3 會跑的指令，兩者都必須放行； git log -n 5、grep -n 這類 -n 也一樣。新增規則前先在測試裡補「要放行」的案例
• commit 訊息內文不能誤擋。Claude 慣用 git commit -m "$(cat <<'EOF' … EOF)"，也可能用 git commit -F - <<'EOF'，訊息裡常出現 -n、--no-verify 字樣。斷詞尊重單雙引號；heredoc 內文 收成一個 token 不當指令看（只有交給 bash／sh 執行時才遞迴檢查）；-m／-F／-C／-c／-t 等會吃掉 下一個 token 的選項要跳過它的參數，但不能跳過分號（arg_next），否則後面整段指令會被漏看。 2026-10-01 拿 repo 全部 228 則 commit 訊息套進兩種 heredoc 寫法重播，誤擋 0 —— 改斷詞後重跑一次
• 它只擋 Claude。使用者自己在終端機打 --no-verify 不經過 Claude Code，擋不到，也不該擋
• 刻意在所有專案都擋（2026-10-01 使用者決定），包括沒跑過 /dd-init、沒有 CLAUDE.md gate 的專案： gate-guard 裝在 ~/.claude/skills/，本來就是全域的，而 Claude 本來就不該自己跳過任何 hook。 使用者真的要跳過時自己在終端機執行 —— deny 理由的最後一句就是在講這個，別把它刪掉
• 斷詞是簡化版，處理：單雙引號、反斜線、# 註解、heredoc（<<、<<-）、分隔符號（2>&1 這類 重導向裡的 & 不算分隔）；指令前面的環境變數、保留字（if then do { ! …）、重導向；nice、timeout、 sudo、xargs 這類包一層的指令。會再遞迴檢查、最多巢狀 3 層：bash -c 的參數、交給 shell 的 heredoc、eval 的參數、雙引號裡的 $(…) 與 `…`、git -c alias.X=… 定義的別名。 抓不到的：export 或 git config 先設好、隔一段才 commit（含 git config core.hooksPath、 事先用 git config alias.ci … 設好的別名）、$(…) 裡括號不成對、--mess 這種長選項縮寫 （會多擋：被當成旗標而不是訊息）—— 別把它寫成完整防線
• 外部指令只用 cat、awk、jq／python3：測試第 2 輪的 PATH 只放這幾支、第 3 輪只放 cat、awk， 多用別的指令（sed、tr…）會讓那兩輪整排失敗。awk 要同時相容 macOS 的 BWK awk、ubuntu 的 mawk、 gawk（2026-10-01 含 busybox 四種 awk 都實測過全套測試）。index(s, "") 在 BWK awk、mawk、gawk 回 1， busybox 回 0（2026-10-01 實測），拿 substr 的結果當 index 的第二個參數之前，先確認位置在範圍內
• 改這支後必須跑 ./test-guard-no-verify.sh（同目錄，CI 也會跑）；兩支都要過 shellcheck -S warning、可在 macOS bash 3.2 執行。測試腳本是 set -u、不可加 -e： 它要抓 hook 的非 0 結束碼，加 -e 會讓第一個失敗案例直接把測試殺掉

與上層的關係

gate-guard 是只有 hook、沒有 skill 的 plugin（上層只有 .claude-plugin/plugin.json，沒有 SKILL.md）， 由 install-dd-pipeline.sh 的 PROMOTED_SKILLS 部署到 ~/.claude/skills/gate-guard/，Claude Code 把它當 skills-dir plugin 載入（gate-guard@skills-dir）、自動掛上 hooks.json。2026-09-30 用全新的 claude -p 實測過：git commit --no-verify 被 deny、理由原文照印，一般 commit 照常成功。

它補強 claude-dd 唯一的強制機制 —— 根目錄 scripts/check-claude-md.sh 的 pre-commit gate。 gate 被擋時印的訊息也指向同一個逃生口（SKIP_DOC_CHECK=1），兩邊的說法要一致。