宣告 vs 實際依賴

讀 repo 只顯示宣告了什麼。它在結構上看不見「機器實際依賴、但 repo 沒宣告」的部分——因為那些依賴根本不在 repo 裡，無從讀起。

實際依賴散落在 repo 追蹤不到的地方：

• 安裝器寫進非-repo 追蹤的 shell profile。裝 Homebrew、rustup、nvm、conda 這類工具時，安裝器常會在 ~/.bashrc、~/.zprofile、~/.profile 尾端 append 一行 PATH 或 init。如果 dotfile 沒把這些 profile 收進 repo（或沒在自己管理的 env.zsh 重新宣告），新機器上工具裝了、shell 卻找不到（見 PATH 的集中宣告）。
• 系統層的 PATH drop-in。官方 .pkg / 套件會丟 /etc/paths.d/（macOS）或 /etc/profile.d/（Linux）的檔案來設 PATH。這些是系統檔、不在家目錄的 dotfile 範圍，重灌後不會自己回來。
• 手動裝過、忘了它存在的 runtime。幾個月前手動裝的 Go、Node、Python 就在機器上，於是 bootstrap 從沒被迫處理「這台沒有 runtime」的情況。
• 來源寄居在別專案的工具。一個全域使用的 CLI，來源目錄卻在某個別專案的 checkout 裡（~/project/foo/tools/bar）。換機器那個專案不在，工具就裝不回來——重建鏈斷在那個 checkout。

原機是一台被污染的儀器

一台工作機的狀態只增不減，而且從不標示哪些是承重的。每次手動安裝、每個編輯 profile 的 installer、每個指向本地目錄的工具，都加進一條 repo 不知道的依賴。

因此「在原機上驗證 dotfile 可不可重現」本身是矛盾的：原機正是累積了所有這些未宣告狀態的機器，它偵測不到自己的污染。讀 repo「看起來很完整」的那種完整感，來自原機把缺口補起來了——換一台乾淨機器，那些補丁全部消失。

怎麼驗：乾淨機器實跑

驗證要在一台沒有累積狀態的機器上跑，且要跑真正宣告的步驟：

1. 乾淨 = 沒有任何累積狀態：全新 VM、拋棄式 container、或全新使用者帳號——不是原機、也不是用過的機器。涵蓋目標作業系統（見 可觀測的 bootstrap 對「要在真正乾淨、且涵蓋目標 OS 的環境各跑一次」的展開）。
2. 跑真實的 install，不是讀 repo、也不是心裡走一遍：靜態檢視跟原機共享同一組盲點——它看得到宣告，看不到缺的依賴。
3. 每個失敗都是一條未宣告的依賴：乾淨機器跟預期分歧的每一個點，都指出一條 repo 漏掉的狀態。把它搬進 repo（收進 dotfile、或在 install.sh 補上），或明確標成刻意手動。產出不是「通過了」，是「原本沒被意識到的依賴清單」。
4. 驗證用的乾淨機器跑過一次就被污染了：有意義的重跑之間要重置（VM 還原快照、container 重建）。

這條紀律的定期版本：每隔一段時間在拋棄式環境跑一次完整 bootstrap，確認這份重建指令真的還能重建（見 同步策略與機密處理）。

判讀訊號

這條原則的工程檢討版（跨平台、非 dotfile 專屬）見 報告 #227：可重現性只有乾淨機器重跑才驗得出。

本卡抽自一次 dotfiles bootstrap 的乾淨機器冷測：在全新 macOS VM 上跑 install.sh，一路撞出多個只在乾淨機器現形的失敗，每一個都追得回「原機上存在、但 repo 沒記錄」的狀態。限制：單一案例、平台是 macOS（涉及的狀態類型如 shell profile、/etc/paths.d 帶 macOS 色彩）；但機制（repo 沒記錄的既有狀態掩蓋重現缺口）不依賴平台，Linux 的 ~/.bashrc、系統 package 手裝殘留同型。

核心原則

環境實際依賴的狀態，散落在 repo 之外的許多地方：安裝器寫進 shell profile 的那行、系統 PATH 的 drop-in 檔、幾個月前手動跑過的 installer、來源寄居在別專案裡的工具——這些 repo 不追蹤的檔案與設定，無聲地讓整台工作機得以運作。因此「這個環境能從 repo 重現」在被驗證之前只是一個宣稱；真正的驗證，是在一台沒有這些累積狀態的機器上、把宣告的步驟重跑一遍。

驗證的工具是「在乾淨機器上實跑重現」、不是「讀 repo」——讀 repo 只顯示宣告了什麼，實跑重現才顯示實際依賴什麼。兩者的差額，正好是那些被依賴、卻沒被宣告的狀態。

情境

dotfiles repo 宣稱能重現開發環境：clone + 跑 install.sh。在原機上一切正常。同一支 install.sh 在全新 macOS VM 上跑，撞出一連串失敗，每個都追得回「原機有、repo 沒有」的狀態：

• brew 跟所有 brew 裝的工具都不在 PATH——原機的 ~/.zprofile 有一行 eval brew shellenv，那是安裝器寫過一次、repo 從未追蹤的檔。
• Go 的 binary 靠 /etc/paths.d/go 被找到，那是官方 pkg installer 丟的系統檔，不在 repo。
• node / go / uv / flutter「本來就在」，因為幾個月前手動裝過。
• 幾個 workflow 工具在原機上 by-name 裝得起來，因為它們的來源目錄（別專案的 .claude/skills/）在本地存在；到乾淨機器上它們不在 PyPI、直接失敗。

這些沒有一個在「讀 repo」或跑 bash -n 時出現。

為什麼

工作機的狀態只增不減，而且從不標示哪些是承重的。每次手動安裝、每個編輯 shell profile 或丟 paths.d 檔的 installer、每個指向本地目錄的工具——每一筆都加進一條 repo 不知道的依賴。讀 repo 只能揭露已宣告的內容，在結構上看不見「被依賴、卻未宣告」的部分。能量到真實依賴的儀器，是乾淨機器重現：一台沒有任何累積狀態的機器跑過宣告的步驟，每一個與預期分歧的點，都是一條未宣告的依賴。

這也是為什麼「在我機器上能跑」是量測問題、不是人的問題：原機是一台被污染的儀器，它偵測不到自己的污染。

理想做法

1. 把任何「可重現 / portable / 從 repo 就能裝起來」的宣稱當成未驗證，直到一次乾淨機器重現通過。
2. 乾淨 = 沒有任何累積狀態：全新 VM、全新使用者帳號、拋棄式 container——不是原機、也不是用過的機器。
3. 跑真正宣告的步驟（clone + 真實的 install），不是心裡走一遍、也不是 lint。靜態推理跟原機共享同一組盲點。
4. 每個分歧都是 finding：指出那條未宣告的狀態，把它搬進 repo（或明確標成刻意手動）。產出是「原本沒被意識到的依賴狀態清單」、不是「通過了」。
5. 儀器本身要保持乾淨：一台跑過一次重現的 VM 現在被污染了；有意義的重跑之間要重置它。

沒這樣做的麻煩

重現宣稱會一路成立，直到它真的要緊的那一刻——新同事的筆電、重灌後的機器、CI runner、換的下一台機器。所有撐著原機的未宣告狀態都不在了，失敗一次全部到齊，在最不方便的時機、落到一個不知道是哪個非-repo 檔在撐著的人手上。而且因為讀 repo「看起來很完整」，這個缺口讀起來像「全都涵蓋了」——正是靜默截斷的失敗模式。

跟其他抽象層原則的關係

• #248 推翻一個假說之後，替補者是在驗屍的空檔裡上位的：本卡處理環境宣告與實際依賴的落差，#248 處理解釋的宣告與它的驗證的落差。共同結構是未經對照的敘述讀起來與已驗證的敘述完全相同，因此都要靠一次刻意的獨立執行才分得開——那裡是乾淨機器，這裡是對照組。
• #249 對當下段落沒有收益的標註不會自發發生：同屬宣告與實際的落差家族，落差的位置不同。本卡在環境（讀 repo 只看到宣告了什麼），那張卡在文字（讀段落只看到論證成立、看不到它建立在什麼條件上）。共同點是缺的東西不產生訊號，要靠一個刻意的動作才現形。

判讀徵兆