dowafu 0.1.0 → 0.3.0

package/publish/{.agents → zh-tw/.agents}/skills/find-holes-external/SKILL.md

@@ -3,7 +3,7 @@ name: find-holes-external
 description: 把規劃書段落派給外部模型（OpenAI／DeepSeek／Gemini／Anthropic）做找漏洞審查，經本地 dowafu CLI 執行，spoke 唯讀且受白名單控管。適用於需要異質視角、或要對照真實原始碼審查規劃書時。用法：/find-holes-external <規劃書檔案路徑> [聚焦章節或問題]
 metadata:
   derived-from: ".claude/skills/find-holes-external/SKILL.md"
-  derived-from-sha256: "e7ac49121ec6b918fef3cb67ff9c911562cd0056e542c76957782ea68caa468c"
+  derived-from-sha256: "904b0dd5df9af5faf24408fa5403b392a6d64ad595f3eeaa16a681aaa01ad1ef"
 ---
 
 # find-holes-external — 外派找漏洞
@@ -70,8 +70,8 @@ dowafu --version
 **四、實跑用背景執行，進度靠檔案而不是終端機輸出。**
 
 用檔案讀取工具輪詢 `tmp/spoke/<ticket-id>/run.jsonl`：CLI 逐事件寫入該檔，讀得出跑到
-哪一輪、有沒有 `round_error`，看到兩個 `spoke_end` 就是跑完。背景終端機的輸出不保證拿
-得到，而單支 spoke 可能跑上好幾分鐘。
+哪一輪、有沒有 `round_error`。**完成判定見 §5**——「兩個 `spoke_end`」只是其中一半。
+背景終端機的輸出不保證拿得到，而單支 spoke 可能跑上好幾分鐘。
 
 > **把終端機當啟動器，不要當資料通道。**
 
@@ -115,6 +115,16 @@ dowafu --version
 換一批對準答案位置的檔案，同一個 lens 就抓得到。**這個自問是為了在派工前擋下落差，
 不是派工後才發現。**
 
+### 每支 spoke 各一張表——清單是按 lens 裁的，不是整批派工裁一次
+
+**那張表每支 spoke 各填一張。** 每支的問題不同，清單就不同；因為「湊一份比較省事」而拿
+同一份餵兩支 lens，只有其中一支需要的那個檔就是這樣掉的。兩支最後真的拿到同一批檔也
+可以，但要說得出為什麼——**清單相同是結論，不是起點**。
+
+**一份清單餵兩支 lens，會往交集收斂，而不是聯集。** 最先掉的是「只有其中一支需要」的檔，
+而那正是那支 lens 被派去看的東西；spoke 這時只能把缺口寫進「無法驗證」欄，而用這種方式
+發現要付一整輪派工的錢。為省錢裁清單是合理的——但要**各自對著自己的問題裁**。
+
 ### lens
 
 | agent | 視角 |
@@ -161,8 +171,10 @@ dowafu --version
 | hole-finder-feasibility | gemini | gemini-3.1-flash-lite | |
 ```
 
-首行 `<!-- format: v1 -->` **必須有**；`model` 必填；`effort` 留白即可（自動用各家預設）；
-只列你要派的那幾個。
+首行 `<!-- format: v1 -->` **必須有**；`model` 必填；只列你要派的那幾個。`effort` 留白
+即為 **`high`**——四家的 `reasoning.default` 目前都是 `high`。要調就查
+`providers.json` 的 `reasoning.allowed`，**各家值域不同**（例如 `deepseek` 沒有
+`medium`）；填了不在值域內的值會被擋下並列出允許值，不會靜默降級。
 
 ### `_shared.md`（所有 spoke 共用）
 
@@ -201,7 +213,9 @@ dowafu --version
 3. **允許清單要涵蓋「回答這些問題實際需要的檔案」。** 逐題自問：要回答這題得讀哪些檔？
    漏了的話 spoke 只能在「無法驗證」欄記下缺什麼——**那是派工端的失誤，不是它的問題**。
    路徑**相對 repo 根目錄**。留空也合法（純文字審查），但那樣就讀不到程式碼，會少掉
-   「文件說 X、`src/foo.ts:42` 其實是 Y」這類最有價值的發現。
+   「文件說 X、`src/foo.ts:42` 其實是 Y」這類最有價值的發現。**清單屬於這一份
+   `<agent>.md`，不屬於整批派工**——不要把另一支的清單整份複製過來：對它有用、對這一支
+   沒用的檔，在讀取順序裡是純負擔；反過來就是漏洞。
 
 4. **大的檔案排在清單最後——這能省掉一半成本。** spoke **嚴格照清單順序**讀檔，而多數
    模型**一輪只叫一個檔**，每一輪又會把先前讀過的全部內容重送一次。所以一個檔被重複
@@ -260,10 +274,24 @@ dowafu tmp/dispatch/<ticket-id> --repo-root . --dry-run
 | 允許清單估算 ＋ 檔數 | spoke 讀得到哪些東西、多大 |
 | 最壞總消耗 | **這是上限不是預期值**（各 spoke 的 cap 加總），實際通常遠低於此 |
 
-報表只給 token，不給金額——**要換算成錢就自己依型號價目算給他看**，別讓他自己猜。
+**用自己的話、用表格轉述——除非你是逐位元組貼上原輸出，否則不要放進 code fence。**
+code fence 的語意就是「這是工具印出來的」，把改寫過的內容裝進去，等於宣稱一個你其實
+沒做到的準確度。改寫沒有問題，而且常常比原輸出好讀；把改寫冒充成原輸出才有問題。
 
-然後逐項核對：`repoRoot` 是這個專案、`model` 跟你寫的一致、`effort` 不是空的、估算
-token 量級合理、**沒有 `⚠ 輸出目錄…未被…忽略` 的警告**。
+**要轉述就連限定語一起轉。** 報表裡那些限定語，正是讓數字不會被誤讀的部分——總量是上限
+而非預期值、價目取自哪一天、估算建立在什麼假設上、每支 lens 收尾句的確認行。它們看起來
+最像可以省的，卻正是讓這些數字能拿來做決定的東西。**限定語一刪，你交給使用者的數字就
+比工具給你的更硬。**
+
+報表只給 token，不給金額，且**只在乾跑階段成立**。要換算成錢，**價目來源是
+`providers.json` 的 `pricing`（`inputPerM`／`cachedInputPerM`／`outputPerM`），不要查
+官網**——那份數字就是 CLI 計費用的，查官網會讓「你報的錢」與「CLI 算的錢」對不上。
+`pricingSource.asOf` 看起來過舊就回報使用者，不要自行改數字（要改是改
+`providers.json`）。**實跑**的 `summary.md` 有「估算成本」欄，每支 spoke 結束也會印
+一行 `cost=`，那是 CLI 自己算好的金額，**直接轉述即可，不必自己算**。
+
+然後逐項核對：`repoRoot` 是這個專案、`model` 跟你寫的一致、**報表印出的 `effort` 是
+你預期的那一級**、估算 token 量級合理、**沒有 `⚠ 輸出目錄…未被…忽略` 的警告**。
 
 任何一項不對就修工單重跑，**不要往下走**。
 
@@ -271,6 +299,21 @@ token 量級合理、**沒有 `⚠ 輸出目錄…未被…忽略` 的警告**
 
 ## 5. 實跑
 
+**輸出目錄必須是一個還不存在的目錄。** 先看 `tmp/spoke/<ticket-id>/`：已經有東西了就
+**換一個新的 ticket-id 派出去**——換 id 不花錢，碰撞這件事就不存在了。
+
+**刪產物是使用者的決定，永遠不是你的。** 派工前不行、順手整理不行、「它擋路」也不行。
+你可以問要不要清掉，但不可以自己清，也不可以直接跑上去。那底下的東西是花錢買來的，
+而目錄本身不會告訴你使用者還要不要它。（第 7 節的清理是另一回事：那是**裁決之後**、
+他說了才做的。）
+
+**這條有 CLI 撐著。** 目錄非空時它會在派工前中止——沒呼叫任何 API、沒花任何錢——
+並要你換一個 ticket-id。**沒有可以蓋過它的旗標**：清目錄是使用者的動作，
+不是你能帶的參數。
+
+CLI 開跑時會清空 `run.jsonl`（舊事件會讓你數錯），**但那一步只在它真的跑起來時才執行**。
+啟動失敗的話，上一次的產物原封不動留著——而**檔案不會告訴你它是不是這一次的**。
+
 ```bash
 dowafu tmp/dispatch/<ticket-id> --repo-root . --yes
 ```
@@ -290,9 +333,37 @@ dowafu tmp/dispatch/<ticket-id> --repo-root . --yes
 > **前景執行本身另有外部工具的逾時上限**（十分鐘量級），與 `--timeout` 無關、擋不住。
 > **預估這次會跑久（清單大、問題多、選了較慢的型號）就改背景執行**，不要在前景硬等。
 
+### 啟動確認：先確認它真的跑起來了，再開始等
+
+**下指令之前先記下當下時間**（`date -u +%Y-%m-%dT%H:%M:%SZ`），下完隔十幾秒讀一次
+`tmp/spoke/<ticket-id>/run.jsonl`：
+
+| 讀到 | 判定 |
+| --- | --- |
+| 檔案不存在 | **沒跑起來**——CLI 一開跑就會建它，這不是「還在等 API」 |
+| 有 `spoke_start`，`ts` 晚於你下指令的時刻 | 起來了，開始輪詢 |
+| 有內容，但 `ts` 早於你下指令的時刻 | **沒跑起來，你讀到的是上一次的產物** |
+
+`ts` 是每一行都有的 ISO 8601 時間戳，**這是判斷「這一份是不是這一次」的唯一機械依據**。
+
+**沒跑起來就不要繼續等。** 這個失敗形態自己看不出來：舊產物的兩個 `spoke_end` 都是
+`succeeded`，格式、稽核欄、成本全部正常，唯一的破綻是時間戳。
+
+### 等多久算不正常
+
+**看的不是總耗時，是 `run.jsonl` 有沒有在長。** 單支 spoke 跑上十分鐘是正常的，但
+**十分鐘之內一定會有新事件寫進來**——單次 API 呼叫的逾時預設就是十分鐘，而逾時與重試
+各自都會寫一行 `round_error`。
+
+> **超過十分鐘沒有任何新事件，就停下來告訴使用者**，不要繼續等、也不要自行重跑。
+> 把最後一個事件與它的 `ts` 一起報給他，讓他判斷。
+
 **進度一律以 `run.jsonl` 為準**——CLI 逐事件寫入該檔，中途 Ctrl-C 也讀得出跑到哪。
 終端機那條通道不保證拿得到（見 §1.5 第四條），`run.jsonl` 不受影響。
 
+**跑完的判定是兩件事同時成立**：兩個 `spoke_end`，**而且**這份 `run.jsonl` 通過了上面的
+啟動確認。只看 `spoke_end` 會把上一次的產物當成這一次的結果。
+
 **真的撞到失敗或逾時：要不要重跑由使用者決定，不要自行重跑。** 重跑是重新付費，中斷前已
 花的錢救不回來（沒有 resume 機制）。把中斷時的狀態（`run.jsonl` 讀到哪、失敗訊息）告訴
 使用者，讓他判斷要不要重來——這與「零讀取就整份重跑」不衝突：那條是「判定沒跑」，這裡是
@@ -300,26 +371,43 @@ dowafu tmp/dispatch/<ticket-id> --repo-root . --yes
 
 ---
 
-## 6. 回收——先原文、後融合
+## 6. 回收——摘要優先，原文為例外
 
 產物在 `tmp/spoke/<ticket-id>/`：`<agent>.md`（原文）、`summary.md`（稽核表）、
 `run.jsonl`（執行記錄）、`raw/`（完整請求與回應）。
 
+> **回收之前先確認 §5 的啟動確認過了。** 這個目錄底下的任何檔案，都不會告訴你它是不是
+> 這一次的產物。
+
 **呈現順序不得更動**：
 
-1. **逐個 spoke 的內容都要讓使用者看到**，標明 lens 與模型。規模小（單份幾十行）就直接
-   原文照登。**規模大到不適合整份貼出時**，可以摘要，但四件事缺一不可：
+1. **逐個 spoke 的內容都要讓使用者看到**，標明 lens 與模型。**摘要是預設**，滿足以下
+   四個必要條件：
    1. **明確宣告取捨**——在摘要開頭寫明「本節為摘要，非逐字照登」，不安靜地摘掉
    2. **判讀涵蓋每一條，無一略過**——每個 spoke 的每一條觀察都要在後面的「hub 判讀」出現，
       這是取代「原文照登」的可稽核性來源：原文不在你眼前列出，不代表它沒被看過
    3. **指出原文路徑**（`tmp/spoke/<ticket-id>/<agent>.md`），使用者隨時可自行比對
-   4. **只在產物尚未清理時才成立**——第 7 節清掉之後就沒有底本可查，那個情境下原文照登
-      仍是唯一選擇，不能摘要
+   4. **只在產物尚未清理時才成立**——第 7 節清掉之後就沒有底本可查
    > 這條規則要防的不是「沒有原文」，是**防止 hub 只挑對自己有利的講**。滿足以上四件事，
    > 手段換成摘要也一樣防得住；換句話說，要守住的是目的，不是「原文」這個手段本身。
 
-   > **沒有把握做到這四件事，就不要摘要——整份照登。**
-2. **`summary.md` 的稽核表併進原文區一併照登。**
+   **原文照登用於兩種情形**：產物已被第 7 節清掉（沒有底本可查，摘要不成立），或單份
+   規模小到摘要反而多此一舉。除此之外都走摘要。
+
+   **做不到第 2 條就不要派這麼多 spoke**——問題出在派工規模，不在呈現方式；不要拿
+   「沒把握」當理由退回整份照登。
+2. **`summary.md` 的稽核欄轉述進上面那一節——它印出來的每一段都要點名。** 每支 spoke
+   一段一行，**順序照 `summary.md` 印的**：`工具呼叫` 在最前面，排在 `收尾句` 之前。
+   某一段是空的時候，CLI 會自己印它的空值字（中文那套印 `無`），**照它印的抄，
+   而且一段都不准漏掉**。全部寫出來不比只寫大部分貴，而少一個段名使用者看得出來，
+   少一列他看不出來。
+
+   **`⚠` 開頭的那幾段不准省，`(無法稽核)` 也不准省。** 它們不是那幾個欄位以外的裝飾，
+   是稽核在告訴你出事了；省掉它們，使用者手上就只剩下說「沒事」的那幾段。
+
+   **有內容的段落一律逐字照抄。** 只有 `pass` 與 CLI 自己的空值字可以壓縮。說「沒事」的
+   段落留著最省事，說「有事」的那段才是會被刪掉的——所以這條規則是刻意不對稱的：
+   **一段講的東西越多，你對它的處置自由越少。**
 3. **之後另立「hub 判讀」一節**——去重，逐條標註你的初步判讀（成立／不成立＋為什麼／
    需使用者裁決）。
 
@@ -351,8 +439,8 @@ dowafu tmp/dispatch/<ticket-id> --repo-root . --yes
 
 | 欄位 | 意思 |
 | --- | --- |
+| `工具呼叫:N（允許 N／拒絕 N）` | 讀了幾次、幾次被拒——`run.jsonl` `toolCalls[]` 的統計。**印在最前面**，排在收尾句之前 |
 | `收尾句` | pass／fail |
-| `工具呼叫:N（允許 N／拒絕 N）` | 讀了幾次、幾次被拒——`run.jsonl` `toolCalls[]` 的統計 |
 | `觀察:N` | 條數；`無法計數` 表示格式無法辨識，翻原文確認 |
 | `清單外引用` | 引用了允許清單外的路徑，**可能是臆測**——對照 `toolCalls[]` 判斷。**此欄至今沒抓到過真正的幻覺**：抓到的多半是 spoke 照抄素材的縮寫路徑、轉述素材裡提過但自己標明讀不到的路徑，或絕對／相對路徑混用。先查該路徑是不是出現在你自己的 `_shared.md` 裡，或只是寫法不同，不要預設是編的 |
 | `無法驗證欄` | 有沒有照模板寫這一節。**判讀產出品質時看這欄有多具體**（例如逐項標明哪個結論依賴哪個不可讀的檔案），不要看觀察條數——條數不可靠，重疊、灌水都會推高條數但不代表品質 |
@@ -398,6 +486,9 @@ dowafu tmp/dispatch/<ticket-id> --repo-root . --yes
 rm -rf tmp/spoke/<ticket-id> tmp/dispatch/<ticket-id>
 ```
 
+**這是整套流程裡唯一會刪東西的地方，而且要等使用者裁決完、他說了才刪。** 其他任何時候
+——包括派工前那個擋路的目錄——一律照第 5 節：可以問，不可以自己刪。
+
 lens 定義留著，下次還會用。
 
 ---
@@ -411,7 +502,7 @@ lens 定義留著，下次還會用。
 | 真失敗或逾時 | **要不要重跑問使用者，不要自行重跑**——重跑是重新付費，中斷前的花費救不回來 |
 | 撞 429 | 加 `--concurrency 1` 重跑 |
 | 報告品質差 | 換一個型號重跑，或同一組設定再跑一次取聯集（見第 3 節「跑 2–3 次怎麼做」） |
-| 缺 API key | 使用者要在 `~/.config/dispatch/.env` 設定，**你不要去碰那個檔** |
+| 缺 API key | 使用者要在 `~/.config/dowafu/.env` 設定，**你不要去碰那個檔** |
 | 找不到 `dowafu` | **查不到不代表沒安裝**——見 §1.5，多半是沙箱不讀家目錄 |
 | `Operation not permitted` | host 的沙箱擋的，**不是工單或指令的問題**。照提示放行再跑一次 |
 

package/publish/{.agents → zh-tw/.agents}/skills/preflight/SKILL.md

@@ -3,7 +3,7 @@ name: preflight
 description: 開工前檢查這個專案的環境有沒有把工作流程靜默停用：流程規範那一章的內容讀不讀得到、skill 與 lens 齊不齊、tmp/ 有沒有被 gitignore、dowafu 跑不跑得起來。只讀、只報告，不改任何設定。
 metadata:
   derived-from: ".claude/skills/preflight/SKILL.md"
-  derived-from-sha256: "2fd8ab69bb7b4c898c9c63bc94a53e7eb041643c343dbae3d175cdccb384bd64"
+  derived-from-sha256: "76de7252b80e1de0256a858467415a99607914f49afae3e1b181f5db43ab796e"
 ---
 
 # preflight — 環境前置檢查
@@ -35,7 +35,7 @@ grep -n "規劃→實作→驗收流程規範" CLAUDE.md AGENTS.md workflow_spec
 
 echo "=== skill 與 lens ==="
 ls .claude/skills/ 2>/dev/null
-ls .claude/agents/hole-finder-*.md 2>/dev/null
+ls .claude/agents/hole-finder*.md 2>/dev/null
 
 echo "=== tmp/ ==="
 git check-ignore -q tmp && echo "已忽略" || echo "未忽略"
@@ -52,6 +52,11 @@ git check-ignore -q tmp && echo "已忽略" || echo "未忽略"
 讀完在回報裡註明「規範不在自動載入範圍內，本次是手動讀取的」——讓使用者知道換個
 session 又會漏掉。
 
+**找到不只一份，就要講明哪一份會被自動載入。** 專案可能本來就把這一章內嵌在入口檔裡，
+而根目錄又多一份 `workflow_spec.md`——兩份的語言還可能不同（語言套件各裝各的）。
+這時只回報「內容讀得到」不夠：要指出**你 context 裡的是哪一份**，以及兩份之間沒有任何
+同步機制。自動載入的那一份，才是之後每個 session 真正生效的那一份。
+
 > **為什麼會讀不到？** 入口檔因 host 而異：Claude Code 讀 `CLAUDE.md`（**不讀
 > `AGENTS.md`**），其他 host 多半讀 repo 根的 `AGENTS.md`。而 `@xxx.md` 是 Claude Code
 > 的 import 語法，**別的 host 不會展開它**——那時你看到的只是一行字，規範內容從來沒進
@@ -59,8 +64,20 @@ session 又會漏掉。
 
 ### skill 與 lens
 
-`.claude/skills/find-holes-external/` 與 `.claude/agents/hole-finder-*.md` 在不在。
-（後者 glob 會列出通用的 `hole-finder.md` 加三個 lens，四個都算正常。）
+`.claude/skills/find-holes-external/` 與 lens 定義在不在。**回報你實際看到的檔名，
+缺哪個就點名**——「看到三個」不算檢查，是哪三個才算。
+
+應該有四個，四個都算正常：
+
+| 檔 | 是什麼 |
+| --- | --- |
+| `hole-finder.md` | 通用 lens |
+| `hole-finder-cost.md` | 成本 |
+| `hole-finder-feasibility.md` | 可行性 |
+| `hole-finder-safety.md` | 安全、併發、失敗態 |
+
+> 上面那道 glob 的 `*` 前面沒有連字號是刻意的：`hole-finder-*.md` 配不到
+> `hole-finder.md`，拿它去數卻期待四個，怎麼數都對不起來。
 
 **lens 缺了不要自己補寫**——它是 spoke 的 system prompt 來源，自己寫的版本會讓產出跟
 稽核判準對不上。
@@ -89,7 +106,7 @@ dowafu --version
 
 | 症狀 | 意思 | 怎麼回報 |
 | --- | --- | --- |
-| `Operation not permitted` | **沙箱擋的**，不是沒安裝。CLI 多半裝在家目錄底下，而沙箱預設不讀家目錄 | 照 host 的提示放行後重試。順帶告訴使用者：API key（`~/.config/dispatch/.env`）與對外網路同樣被擋，派工時一併要放行 |
+| `Operation not permitted` | **沙箱擋的**，不是沒安裝。CLI 多半裝在家目錄底下，而沙箱預設不讀家目錄 | 照 host 的提示放行後重試。順帶告訴使用者：API key（`~/.config/dowafu/.env`）與對外網路同樣被擋，派工時一併要放行 |
 | `command not found` | 可能沒裝，也可能裝在 PATH 之外 | 問使用者 CLI 裝在哪（請他跑 `which dowafu`），**不要自己搜檔案系統** |
 
 **`command -v dowafu` 查不到不代表沒安裝**，別拿那個當判準。

package/publish/{.claude → zh-tw/.claude}/skills/find-holes/SKILL.md

@@ -70,7 +70,8 @@ description: 【Claude Code 內派專用；VS Code 環境改用 find-holes-exter
   裁這份清單時**逐題自問：「這一題的答案在哪個檔？那個檔在清單裡嗎？」**
   按 lens 的名稱配檔案（safety 就給安全相關的）會配錯——**lens 是看的角度，
   清單是看的材料**。清單對不準問題的答案位置，spoke 物理上不可能答對。
-  **漏了是派工端的失誤，不是 spoke 的問題。**
+  **漏了是派工端的失誤，不是 spoke 的問題。每支 spoke 的清單各自對著自己的問題裁**
+  ——不要因為湊一份比較省事就給兩支同一份；掉的會是只有其中一支需要的那個檔。
 
 - **清單內把大檔排在最後**（依檔案大小遞增）。spoke 照清單順序讀檔，每輪會重送先前
   讀過的全部內容，所以排越前面被重複計費越多次，差距可以到將近一倍。
@@ -79,10 +80,26 @@ description: 【Claude Code 內派專用；VS Code 環境改用 find-holes-exter
 - **產出格式**：「觀察＋依據（檔案:行號 或 推理）」的清單。**不得**給結論裁決、
   嚴重度分級、「應該改成」的替代設計、採用建議；不確定的寫成問題，不寫成缺陷。
 
-### 4. 回收：先原文、後融合
+### 4. 回收——摘要優先，原文為例外
 
-每個 spoke 的回報**逐個原文照登**，標明 lens 與模型，**不得刪節、改寫或只給總結**——
-使用者必須看得到每個 spoke 各自說了什麼。
+每個 spoke 的回報都要讓使用者看到，標明 lens 與模型。**摘要是預設**，滿足以下四個
+必要條件：
+
+1. **明確宣告取捨**——在摘要開頭寫明「本節為摘要，非逐字照登」，不安靜地摘掉
+2. **判讀涵蓋每一條，無一略過**——每個 spoke 的每一條觀察都要在後面的「hub 判讀」出現，
+   這是取代「原文照登」的可稽核性來源：原文不在你眼前列出，不代表它沒被看過
+3. **原文仍在這輪對話裡**——sub-agent 回傳的完整內容留在上下文中，使用者要求時可以
+   重新貼出核對
+4. **只在原文還找得到時才成立**——原文若已不在上下文範圍內，就沒有底本可查
+
+> 這條規則要防的不是「沒有原文」，是**防止 hub 只挑對自己有利的講**。滿足以上四件事，
+> 手段換成摘要也一樣防得住；換句話說，要守住的是目的，不是「原文」這個手段本身。
+
+**原文照登用於兩種情形**：原文已不在上下文裡（沒有底本可查，摘要不成立），或單份規模
+小到摘要反而多此一舉。除此之外都走摘要。
+
+**做不到第 2 條就不要派這麼多 spoke**——問題出在派工規模，不在呈現方式；不要拿
+「沒把握」當理由退回整份照登。
 
 之後**另立「hub 判讀」一節**：去重，逐條標註你的初步判讀（成立／不成立＋為什麼／
 需使用者裁決）。

package/publish/{.claude → zh-tw/.claude}/skills/find-holes-external/SKILL.md

@@ -87,8 +87,8 @@ dowafu --version
 **四、實跑用背景執行，進度靠檔案而不是終端機輸出。**
 
 用檔案讀取工具輪詢 `tmp/spoke/<ticket-id>/run.jsonl`：CLI 逐事件寫入該檔，讀得出跑到
-哪一輪、有沒有 `round_error`，看到兩個 `spoke_end` 就是跑完。背景終端機的輸出不保證拿
-得到，而單支 spoke 可能跑上好幾分鐘。
+哪一輪、有沒有 `round_error`。**完成判定見 §5**——「兩個 `spoke_end`」只是其中一半。
+背景終端機的輸出不保證拿得到，而單支 spoke 可能跑上好幾分鐘。
 
 > **把終端機當啟動器，不要當資料通道。**
 
@@ -132,6 +132,16 @@ dowafu --version
 換一批對準答案位置的檔案，同一個 lens 就抓得到。**這個自問是為了在派工前擋下落差，
 不是派工後才發現。**
 
+### 每支 spoke 各一張表——清單是按 lens 裁的，不是整批派工裁一次
+
+**那張表每支 spoke 各填一張。** 每支的問題不同，清單就不同；因為「湊一份比較省事」而拿
+同一份餵兩支 lens，只有其中一支需要的那個檔就是這樣掉的。兩支最後真的拿到同一批檔也
+可以，但要說得出為什麼——**清單相同是結論，不是起點**。
+
+**一份清單餵兩支 lens，會往交集收斂，而不是聯集。** 最先掉的是「只有其中一支需要」的檔，
+而那正是那支 lens 被派去看的東西；spoke 這時只能把缺口寫進「無法驗證」欄，而用這種方式
+發現要付一整輪派工的錢。為省錢裁清單是合理的——但要**各自對著自己的問題裁**。
+
 ### lens
 
 | agent | 視角 |
@@ -178,8 +188,10 @@ dowafu --version
 | hole-finder-feasibility | gemini | gemini-3.1-flash-lite | |
 ```
 
-首行 `<!-- format: v1 -->` **必須有**；`model` 必填；`effort` 留白即可（自動用各家預設）；
-只列你要派的那幾個。
+首行 `<!-- format: v1 -->` **必須有**；`model` 必填；只列你要派的那幾個。`effort` 留白
+即為 **`high`**——四家的 `reasoning.default` 目前都是 `high`。要調就查
+`providers.json` 的 `reasoning.allowed`，**各家值域不同**（例如 `deepseek` 沒有
+`medium`）；填了不在值域內的值會被擋下並列出允許值，不會靜默降級。
 
 ### `_shared.md`（所有 spoke 共用）
 
@@ -218,7 +230,9 @@ dowafu --version
 3. **允許清單要涵蓋「回答這些問題實際需要的檔案」。** 逐題自問：要回答這題得讀哪些檔？
    漏了的話 spoke 只能在「無法驗證」欄記下缺什麼——**那是派工端的失誤，不是它的問題**。
    路徑**相對 repo 根目錄**。留空也合法（純文字審查），但那樣就讀不到程式碼，會少掉
-   「文件說 X、`src/foo.ts:42` 其實是 Y」這類最有價值的發現。
+   「文件說 X、`src/foo.ts:42` 其實是 Y」這類最有價值的發現。**清單屬於這一份
+   `<agent>.md`，不屬於整批派工**——不要把另一支的清單整份複製過來：對它有用、對這一支
+   沒用的檔，在讀取順序裡是純負擔；反過來就是漏洞。
 
 4. **大的檔案排在清單最後——這能省掉一半成本。** spoke **嚴格照清單順序**讀檔，而多數
    模型**一輪只叫一個檔**，每一輪又會把先前讀過的全部內容重送一次。所以一個檔被重複
@@ -277,10 +291,24 @@ dowafu tmp/dispatch/<ticket-id> --repo-root . --dry-run
 | 允許清單估算 ＋ 檔數 | spoke 讀得到哪些東西、多大 |
 | 最壞總消耗 | **這是上限不是預期值**（各 spoke 的 cap 加總），實際通常遠低於此 |
 
-報表只給 token，不給金額——**要換算成錢就自己依型號價目算給他看**，別讓他自己猜。
+**用自己的話、用表格轉述——除非你是逐位元組貼上原輸出，否則不要放進 code fence。**
+code fence 的語意就是「這是工具印出來的」，把改寫過的內容裝進去，等於宣稱一個你其實
+沒做到的準確度。改寫沒有問題，而且常常比原輸出好讀；把改寫冒充成原輸出才有問題。
 
-然後逐項核對：`repoRoot` 是這個專案、`model` 跟你寫的一致、`effort` 不是空的、估算
-token 量級合理、**沒有 `⚠ 輸出目錄…未被…忽略` 的警告**。
+**要轉述就連限定語一起轉。** 報表裡那些限定語，正是讓數字不會被誤讀的部分——總量是上限
+而非預期值、價目取自哪一天、估算建立在什麼假設上、每支 lens 收尾句的確認行。它們看起來
+最像可以省的，卻正是讓這些數字能拿來做決定的東西。**限定語一刪，你交給使用者的數字就
+比工具給你的更硬。**
+
+報表只給 token，不給金額，且**只在乾跑階段成立**。要換算成錢，**價目來源是
+`providers.json` 的 `pricing`（`inputPerM`／`cachedInputPerM`／`outputPerM`），不要查
+官網**——那份數字就是 CLI 計費用的，查官網會讓「你報的錢」與「CLI 算的錢」對不上。
+`pricingSource.asOf` 看起來過舊就回報使用者，不要自行改數字（要改是改
+`providers.json`）。**實跑**的 `summary.md` 有「估算成本」欄，每支 spoke 結束也會印
+一行 `cost=`，那是 CLI 自己算好的金額，**直接轉述即可，不必自己算**。
+
+然後逐項核對：`repoRoot` 是這個專案、`model` 跟你寫的一致、**報表印出的 `effort` 是
+你預期的那一級**、估算 token 量級合理、**沒有 `⚠ 輸出目錄…未被…忽略` 的警告**。
 
 任何一項不對就修工單重跑，**不要往下走**。
 
@@ -288,6 +316,21 @@ token 量級合理、**沒有 `⚠ 輸出目錄…未被…忽略` 的警告**
 
 ## 5. 實跑
 
+**輸出目錄必須是一個還不存在的目錄。** 先看 `tmp/spoke/<ticket-id>/`：已經有東西了就
+**換一個新的 ticket-id 派出去**——換 id 不花錢，碰撞這件事就不存在了。
+
+**刪產物是使用者的決定，永遠不是你的。** 派工前不行、順手整理不行、「它擋路」也不行。
+你可以問要不要清掉，但不可以自己清，也不可以直接跑上去。那底下的東西是花錢買來的，
+而目錄本身不會告訴你使用者還要不要它。（第 7 節的清理是另一回事：那是**裁決之後**、
+他說了才做的。）
+
+**這條有 CLI 撐著。** 目錄非空時它會在派工前中止——沒呼叫任何 API、沒花任何錢——
+並要你換一個 ticket-id。**沒有可以蓋過它的旗標**：清目錄是使用者的動作，
+不是你能帶的參數。
+
+CLI 開跑時會清空 `run.jsonl`（舊事件會讓你數錯），**但那一步只在它真的跑起來時才執行**。
+啟動失敗的話，上一次的產物原封不動留著——而**檔案不會告訴你它是不是這一次的**。
+
 ```bash
 dowafu tmp/dispatch/<ticket-id> --repo-root . --yes
 ```
@@ -306,9 +349,37 @@ dowafu tmp/dispatch/<ticket-id> --repo-root . --yes
 > **前景執行本身另有外部工具的逾時上限**（十分鐘量級），與 `--timeout` 無關、擋不住。
 > **預估這次會跑久（清單大、問題多、選了較慢的型號）就改背景執行**，不要在前景硬等。
 
+### 啟動確認：先確認它真的跑起來了，再開始等
+
+**下指令之前先記下當下時間**（`date -u +%Y-%m-%dT%H:%M:%SZ`），下完隔十幾秒讀一次
+`tmp/spoke/<ticket-id>/run.jsonl`：
+
+| 讀到 | 判定 |
+| --- | --- |
+| 檔案不存在 | **沒跑起來**——CLI 一開跑就會建它，這不是「還在等 API」 |
+| 有 `spoke_start`，`ts` 晚於你下指令的時刻 | 起來了，開始輪詢 |
+| 有內容，但 `ts` 早於你下指令的時刻 | **沒跑起來，你讀到的是上一次的產物** |
+
+`ts` 是每一行都有的 ISO 8601 時間戳，**這是判斷「這一份是不是這一次」的唯一機械依據**。
+
+**沒跑起來就不要繼續等。** 這個失敗形態自己看不出來：舊產物的兩個 `spoke_end` 都是
+`succeeded`，格式、稽核欄、成本全部正常，唯一的破綻是時間戳。
+
+### 等多久算不正常
+
+**看的不是總耗時，是 `run.jsonl` 有沒有在長。** 單支 spoke 跑上十分鐘是正常的，但
+**十分鐘之內一定會有新事件寫進來**——單次 API 呼叫的逾時預設就是十分鐘，而逾時與重試
+各自都會寫一行 `round_error`。
+
+> **超過十分鐘沒有任何新事件，就停下來告訴使用者**，不要繼續等、也不要自行重跑。
+> 把最後一個事件與它的 `ts` 一起報給他，讓他判斷。
+
 **進度一律以 `run.jsonl` 為準**——CLI 逐事件寫入該檔，中途 Ctrl-C 也讀得出跑到哪。
 終端機那條通道可不可靠依 host 而定（見 §1.5），`run.jsonl` 不受影響。
 
+**跑完的判定是兩件事同時成立**：兩個 `spoke_end`，**而且**這份 `run.jsonl` 通過了上面的
+啟動確認。只看 `spoke_end` 會把上一次的產物當成這一次的結果。
+
 **真的撞到失敗或逾時：要不要重跑由使用者決定，不要自行重跑。** 重跑是重新付費，中斷前已
 花的錢救不回來（沒有 resume 機制）。把中斷時的狀態（`run.jsonl` 讀到哪、失敗訊息）告訴
 使用者，讓他判斷要不要重來——這與「零讀取就整份重跑」不衝突：那條是「判定沒跑」，這裡是
@@ -316,26 +387,43 @@ dowafu tmp/dispatch/<ticket-id> --repo-root . --yes
 
 ---
 
-## 6. 回收——先原文、後融合
+## 6. 回收——摘要優先，原文為例外
 
 產物在 `tmp/spoke/<ticket-id>/`：`<agent>.md`（原文）、`summary.md`（稽核表）、
 `run.jsonl`（執行記錄）、`raw/`（完整請求與回應）。
 
+> **回收之前先確認 §5 的啟動確認過了。** 這個目錄底下的任何檔案，都不會告訴你它是不是
+> 這一次的產物。
+
 **呈現順序不得更動**：
 
-1. **逐個 spoke 的內容都要讓使用者看到**，標明 lens 與模型。規模小（單份幾十行）就直接
-   原文照登。**規模大到不適合整份貼出時**，可以摘要，但四件事缺一不可：
+1. **逐個 spoke 的內容都要讓使用者看到**，標明 lens 與模型。**摘要是預設**，滿足以下
+   四個必要條件：
    1. **明確宣告取捨**——在摘要開頭寫明「本節為摘要，非逐字照登」，不安靜地摘掉
    2. **判讀涵蓋每一條，無一略過**——每個 spoke 的每一條觀察都要在後面的「hub 判讀」出現，
       這是取代「原文照登」的可稽核性來源：原文不在你眼前列出，不代表它沒被看過
    3. **指出原文路徑**（`tmp/spoke/<ticket-id>/<agent>.md`），使用者隨時可自行比對
-   4. **只在產物尚未清理時才成立**——第 7 節清掉之後就沒有底本可查，那個情境下原文照登
-      仍是唯一選擇，不能摘要
+   4. **只在產物尚未清理時才成立**——第 7 節清掉之後就沒有底本可查
    > 這條規則要防的不是「沒有原文」，是**防止 hub 只挑對自己有利的講**。滿足以上四件事，
    > 手段換成摘要也一樣防得住；換句話說，要守住的是目的，不是「原文」這個手段本身。
 
-   > **沒有把握做到這四件事，就不要摘要——整份照登。**
-2. **`summary.md` 的稽核表併進原文區一併照登。**
+   **原文照登用於兩種情形**：產物已被第 7 節清掉（沒有底本可查，摘要不成立），或單份
+   規模小到摘要反而多此一舉。除此之外都走摘要。
+
+   **做不到第 2 條就不要派這麼多 spoke**——問題出在派工規模，不在呈現方式；不要拿
+   「沒把握」當理由退回整份照登。
+2. **`summary.md` 的稽核欄轉述進上面那一節——它印出來的每一段都要點名。** 每支 spoke
+   一段一行，**順序照 `summary.md` 印的**：`工具呼叫` 在最前面，排在 `收尾句` 之前。
+   某一段是空的時候，CLI 會自己印它的空值字（中文那套印 `無`），**照它印的抄，
+   而且一段都不准漏掉**。全部寫出來不比只寫大部分貴，而少一個段名使用者看得出來，
+   少一列他看不出來。
+
+   **`⚠` 開頭的那幾段不准省，`(無法稽核)` 也不准省。** 它們不是那幾個欄位以外的裝飾，
+   是稽核在告訴你出事了；省掉它們，使用者手上就只剩下說「沒事」的那幾段。
+
+   **有內容的段落一律逐字照抄。** 只有 `pass` 與 CLI 自己的空值字可以壓縮。說「沒事」的
+   段落留著最省事，說「有事」的那段才是會被刪掉的——所以這條規則是刻意不對稱的：
+   **一段講的東西越多，你對它的處置自由越少。**
 3. **之後另立「hub 判讀」一節**——去重，逐條標註你的初步判讀（成立／不成立＋為什麼／
    需使用者裁決）。
 
@@ -367,8 +455,8 @@ dowafu tmp/dispatch/<ticket-id> --repo-root . --yes
 
 | 欄位 | 意思 |
 | --- | --- |
+| `工具呼叫:N（允許 N／拒絕 N）` | 讀了幾次、幾次被拒——`run.jsonl` `toolCalls[]` 的統計。**印在最前面**，排在收尾句之前 |
 | `收尾句` | pass／fail |
-| `工具呼叫:N（允許 N／拒絕 N）` | 讀了幾次、幾次被拒——`run.jsonl` `toolCalls[]` 的統計 |
 | `觀察:N` | 條數；`無法計數` 表示格式無法辨識，翻原文確認 |
 | `清單外引用` | 引用了允許清單外的路徑，**可能是臆測**——對照 `toolCalls[]` 判斷。**此欄至今沒抓到過真正的幻覺**：抓到的多半是 spoke 照抄素材的縮寫路徑、轉述素材裡提過但自己標明讀不到的路徑，或絕對／相對路徑混用。先查該路徑是不是出現在你自己的 `_shared.md` 裡，或只是寫法不同，不要預設是編的 |
 | `無法驗證欄` | 有沒有照模板寫這一節。**判讀產出品質時看這欄有多具體**（例如逐項標明哪個結論依賴哪個不可讀的檔案），不要看觀察條數——條數不可靠，重疊、灌水都會推高條數但不代表品質 |
@@ -414,6 +502,9 @@ dowafu tmp/dispatch/<ticket-id> --repo-root . --yes
 rm -rf tmp/spoke/<ticket-id> tmp/dispatch/<ticket-id>
 ```
 
+**這是整套流程裡唯一會刪東西的地方，而且要等使用者裁決完、他說了才刪。** 其他任何時候
+——包括派工前那個擋路的目錄——一律照第 5 節：可以問，不可以自己刪。
+
 lens 定義留著，下次還會用。
 
 ---
@@ -427,7 +518,7 @@ lens 定義留著，下次還會用。
 | 真失敗或逾時 | **要不要重跑問使用者，不要自行重跑**——重跑是重新付費，中斷前的花費救不回來 |
 | 撞 429 | 加 `--concurrency 1` 重跑 |
 | 報告品質差 | 換一個型號重跑，或同一組設定再跑一次取聯集（見第 3 節「跑 2–3 次怎麼做」） |
-| 缺 API key | 使用者要在 `~/.config/dispatch/.env` 設定，**你不要去碰那個檔** |
+| 缺 API key | 使用者要在 `~/.config/dowafu/.env` 設定，**你不要去碰那個檔** |
 | 找不到 `dowafu` | **查不到不代表沒安裝**——見 §1.5，多半是沙箱不讀家目錄 |
 | `Operation not permitted` | host 的沙箱擋的，**不是工單或指令的問題**。照提示放行再跑一次 |
 

package/publish/{.claude → zh-tw/.claude}/skills/preflight/SKILL.md

@@ -45,7 +45,7 @@ grep -n "規劃→實作→驗收流程規範" CLAUDE.md AGENTS.md workflow_spec
 
 echo "=== skill 與 lens ==="
 ls .claude/skills/ 2>/dev/null
-ls .claude/agents/hole-finder-*.md 2>/dev/null
+ls .claude/agents/hole-finder*.md 2>/dev/null
 
 echo "=== tmp/ ==="
 git check-ignore -q tmp && echo "已忽略" || echo "未忽略"
@@ -62,6 +62,11 @@ git check-ignore -q tmp && echo "已忽略" || echo "未忽略"
 讀完在回報裡註明「規範不在自動載入範圍內，本次是手動讀取的」——讓使用者知道換個
 session 又會漏掉。
 
+**找到不只一份，就要講明哪一份會被自動載入。** 專案可能本來就把這一章內嵌在入口檔裡，
+而根目錄又多一份 `workflow_spec.md`——兩份的語言還可能不同（語言套件各裝各的）。
+這時只回報「內容讀得到」不夠：要指出**你 context 裡的是哪一份**，以及兩份之間沒有任何
+同步機制。自動載入的那一份，才是之後每個 session 真正生效的那一份。
+
 > **為什麼會讀不到？** 入口檔因 host 而異：Claude Code 讀 `CLAUDE.md`（**不讀
 > `AGENTS.md`**），其他 host 多半讀 repo 根的 `AGENTS.md`。而 `@xxx.md` 是 Claude Code
 > 的 import 語法，**別的 host 不會展開它**——那時你看到的只是一行字，規範內容從來沒進
@@ -69,8 +74,20 @@ session 又會漏掉。
 
 ### skill 與 lens
 
-`.claude/skills/find-holes-external/` 與 `.claude/agents/hole-finder-*.md` 在不在。
-（後者 glob 會列出通用的 `hole-finder.md` 加三個 lens，四個都算正常。）
+`.claude/skills/find-holes-external/` 與 lens 定義在不在。**回報你實際看到的檔名，
+缺哪個就點名**——「看到三個」不算檢查，是哪三個才算。
+
+應該有四個，四個都算正常：
+
+| 檔 | 是什麼 |
+| --- | --- |
+| `hole-finder.md` | 通用 lens |
+| `hole-finder-cost.md` | 成本 |
+| `hole-finder-feasibility.md` | 可行性 |
+| `hole-finder-safety.md` | 安全、併發、失敗態 |
+
+> 上面那道 glob 的 `*` 前面沒有連字號是刻意的：`hole-finder-*.md` 配不到
+> `hole-finder.md`，拿它去數卻期待四個，怎麼數都對不起來。
 
 **lens 缺了不要自己補寫**——它是 spoke 的 system prompt 來源，自己寫的版本會讓產出跟
 稽核判準對不上。
@@ -158,7 +175,7 @@ dowafu --version
 
 | 症狀 | 意思 | 怎麼回報 |
 | --- | --- | --- |
-| `Operation not permitted` | **沙箱擋的**，不是沒安裝。CLI 多半裝在家目錄底下，而沙箱預設不讀家目錄 | 照 host 的提示放行後重試。順帶告訴使用者：API key（`~/.config/dispatch/.env`）與對外網路同樣被擋，派工時一併要放行 |
+| `Operation not permitted` | **沙箱擋的**，不是沒安裝。CLI 多半裝在家目錄底下，而沙箱預設不讀家目錄 | 照 host 的提示放行後重試。順帶告訴使用者：API key（`~/.config/dowafu/.env`）與對外網路同樣被擋，派工時一併要放行 |
 | `command not found` | 可能沒裝，也可能裝在 PATH 之外 | 問使用者 CLI 裝在哪（請他跑 `which dowafu`），**不要自己搜檔案系統** |
 
 **`command -v dowafu` 查不到不代表沒安裝**，別拿那個當判準。

package/publish/{README.md → zh-tw/README.md}

@@ -65,6 +65,22 @@ import 機制**。兩種讀者得分別交代，否則其中一邊會靜默漏
 
 目標專案若沒有 `CLAUDE.md`，另建一個、內容一行 `@AGENTS.md` 即可（官方建議做法）。
 
+### 專案本來就有一章流程規範時
+
+很多專案本來就有一份，直接貼在入口檔裡——而且語言可能跟你剛裝的這套不同，因為每個語言
+套件各帶各的 `workflow_spec.md`。就這樣把檔案複製進去，專案裡會變成**兩份、而且沒有任何
+機制保證同步**；真正管到每個 session 的是入口檔會自動載入的那一份——**是本來就在的那章，
+不是你剛裝的那個檔**。
+
+二選一，另一份要拿掉：
+
+- **留 `workflow_spec.md`**（建議）：把入口檔裡舊的那一章刪掉，換成上面那段 import
+- **留內嵌的那一章**：把它的內容換成你要統一的語言那份 `workflow_spec.md` 的內容，
+  並且**不要**把 `workflow_spec.md` 複製進專案
+
+不論走哪一條，專案裡最後**只留一份**。裝完跑一次 `preflight`——它會回報實際在 context
+裡的是哪一份，所以這個決定就算漏掉了，還有一道會抓到。
+
 ## 這裡不准出現的東西
 
 `publish/` 的內容會在一個不知道來源專案存在的地方執行，所以不得出現絕對路徑、來源專案的