tests/ — CI 跑的情境測試

放「不屬於任何一支部署腳本、但 CI 要跑」的測試。不部署：不在 scripts/ 底下， 所以 DD_SCRIPTS ↔ scripts/*.sh 那道一致性檢查不會把它當成要部署的腳本。

關鍵檔案

此層約束

• CI 在兩種 bash 上各跑一次：ubuntu（bash 5）與 macOS 的 /bin/bash 3.2（.github/workflows/ci.yml）。 gate 與它的 hook 都靠 shebang #!/bin/bash 執行，所以在 macOS 上測到的就是使用者機器上的那個 bash
• test-gate.sh 在 gate 的輸出裡看到 shell 錯誤就判失敗（bad substitution、syntax error、command not found、 invalid option、unbound variable，以及 bash 報腳本錯誤固定的「: line N: 」前綴）：bash 3.2 不支援的寫法常常 只印一行錯誤、判斷結果照舊，只看 pass／block 的話 macOS job 照樣全綠。2026-10-01 實測：在 gate 的 staged=$(…) 下一行加 lc=${staged,,}，3.2 下 36 個 ❌、bash 5 全過；shopt -s lastpipe、 ${a[-1]} 這類清單外的錯誤，是加了「: line N: 」前綴才抓到的。test-install.sh 不做這層檢查，靠 set -e： 3.2 在 set -e 下遇到這類錯誤會直接中止
• 兩支都在暫存目錄裡跑、trap 跑完清掉（本機會拿來重跑與做變異測試）
• 腳本開頭是 set -e（2026-10-01 從 ci.yml 內嵌 step 搬出來時照 GitHub Actions 預設的 bash -e 保留）： 預期會被擋的 commit 一律包在 expect 的 if 裡，新增情境時別讓會回非 0 的指令裸跑
  • ⚠️ 預期放行、但會觸發 hook 的指令（git commit --amend 這類）也要包進 expect：裸跑的話， 變異版 gate 擋下它時 set -e 中止整支，後面的情境一則都沒跑，看起來像「只紅了前面幾則」。 2026-10-19 實測：拿「pre-commit 也查報告」的變異跑，整支停在 ⑦ 那行裸跑的 amend，新加的繞過①根本沒跑到； 包進 expect 後才跑完。驗法：變異版與固定版的判定行數（grep -cE '^(✅|❌ .*：(預期 |輸出裡有 shell 錯誤))'）要一樣
• ⚠️⚠️ 變異測試要選對「變異方向」,否則它證明的不是你以為的那件事。曾把 opt-in 守門 [ -d docs/reviews ] || return 1 改成永遠 return 1 (= 功能全關),拿到的紅全部落在新區塊 —— 那證明「新情境在測這個功能」, 跟「opt-in 保護了沒採用的專案」完全無關。對應後者的變異是把那行整個拿掉 (檢查對所有 repo 生效),紅的才會落在舊的那批。三組實測:

  變異	紅	證明的是
  那行 → 永遠 return 1	12	新情境真的在測這個功能
  那行整個拿掉	5,其中 4 在舊的那批	← opt-in 那句的佐證
  --diff-filter=A → ACMR	2	「只改既有報告不算新增」有被釘住
  做法:寫「變異測試證明了 X」之前,先問「把 X 弄壞的最小改動是哪一行」,
  然後改那一行 —— 不是改一個會讓整個功能消失的地方。

• ⚠️⚠️ 一個「恆真」的斷言比沒有斷言更糟。 情境 ① 曾寫 BEFORE_BASE=$(cat "$BASE_FILE") 然後 base_is "$BEFORE_BASE", 但那行讀檔是在 expect … --start-segment 跑完之後 —— 等於拿檔案跟自己比,永遠綠。 實測:對變異版,①的起點確實被搬動了而斷言照樣過;那個不變量實際只有情境 ③ 在守。 做法:斷言「X 沒有被改動」時,快照一定要在被測指令之前取; 而且用變異測試檢查這個斷言本身會不會紅 —— 不會紅的斷言是裝飾品。
• ⚠️ 新增的 review 強制情境刻意跑在「有 docs/reviews/ 目錄」的 repo 裡，而它之前的情境沒有 —— 那正是 opt-in 的證明：加了新功能，既有情境一項都不用改。 寫新情境時不要把 mkdir docs/reviews 往上搬，會把前面那些情境的前提改掉。
• ⚠️ 「剛採用慣例時第一次 --start-segment 被擋」是情境 ①，不是待修的邊角 —— 上一段本來就沒報告，那是真實的導入路徑，預期結果是擋下、不是 pass。
• 本機跑：/bin/bash tests/test-gate.sh（repo 根目錄或任何地方都可以，gate 路徑以腳本位置推算）
  • bash 5（CI 的 ubuntu 那份）要在 repo 根目錄跑（"$PWD" 掛成 /repo）：docker run --rm -v "$PWD":/repo:ro bash:5 sh -c 'apk add --no-cache git >/tmp/apk.log 2>&1 || exit 3; ln -sf /usr/local/bin/bash /bin/bash; cd /tmp && bash /repo/tests/test-gate.sh' —— 映像沒有 git，也沒有 /bin/bash（bash 在 /usr/local/bin/bash，gate 的 shebang 寫 #!/bin/bash），兩步都不能省。 少裝 git，一則情境都沒跑就 git: command not found；少了 ln，gate 跑不起來 —— 直接叫印 /bin/bash: bad interpreter，從 hook 叫印的卻是 …/check-claude-md.sh: not found（檔案明明在，缺的是直譯器；apk add git 也不會順便帶來 /bin/bash）
• 要通過 shellcheck -S warning（CI 的 ShellCheck 清單逐檔寫死，這支已列入）

與上層的關係

gate 本體的規則與「改了 gate 要做變異測試」的規定在 scripts/CLAUDE.md；CI 防線的總表在 根目錄的 DD_PIPELINE_ARCHITECTURE.md。