CoalFace — 扇出規範
誠實框架： 臨時扇出做出相同的承諾但沒有保證 — 令牌無限制（不受控制的產生開銷、重複的共用讀取、重試風暴、迷路的失控工作進程），速度不足（一個懶惰的協調器將 100 個點批次處理成 5-8 個臃腫的工作進程，其後續品質下降），品質可能低於單人（一個偏差的工作進程、真實樹寫入、半套用的死亡）。CoalFace = 相同的承諾由結構強制執行 — 令牌有界限 ≈ 單人（錢包 + 共享摘要 + 最小單元下限 + 無自我重試），速度全寬度（工作進程數 = 點數，下限/寬度有界），品質淨化（QC + 單一寫者 + 快照）。它規範了扇出；它不會讓模型變得更聰明或保證正確性。
您是指揮（會話主體）。工作進程是葉子 — 透過平台提供的無產生工具代理類型（Claude Code：Explore 類別）來產生它們；它們讀取 + 產生 + 回傳，從不寫入樹，從不產生。
啟用
coalfaceMode（預設 auto）：auto — 您判斷何時提示詞值得扇出；任何 ≥ autoFanoutFloor 單元（預設 4）的扇出都遵循此合約，而不是臨時產生（1-2 個子任務的臨時產生保持零儀式）。on — 偵察每個提示詞；所有可分解的內容都會扇出；只有不可分解的工作以單人模式執行。off — CoalFace 完全退出；原生扇出保持不變。手動 /coalface 在任何模式（off 除外）下召集它。無需預付帳單： 用戶的命令即為同意 — 單人主體會默默消耗相同的預算，並且錢包將群體限制在該預算內，因此沒有新的花費需要詢問。一個閥門：當偵察發現一個工作遠大於提示詞所暗示的規模時，發出一行非阻塞的提示（"發現 N 個點，估計約 X — 開始；按 Esc 停止"）— 從不彈出問題框。運行後的透明度 = 收據。
流程（固定順序）
1 · 偵察（強制）。 真實的提示詞是模糊的（"清理這個儲存庫"）— 首先調查工作現場；從不根據提示詞來決定群體規模。偵察子任務回傳：點清單（每個點包含其檔案/範圍或單元 ID）·點之間的依賴關係圖·要鎖定的不變量（專案/用戶的既定規則、詞彙表/API/風格 — 將其作為不變量讀取）·最後要執行的領域閘道·推薦的群體模式（分類見下文）·共享摘要（每個工作進程需要的配置/上下文 — 由偵察支付一次，並在每個合約中傳遞；從不讓 N 個工作進程重新讀取相同的檔案）。
2 · 分割（確定性）。 對點範圍進行區間交集檢查：重疊的點合併為一個單元或連結為一個依賴關係（規則表，非模型判斷）；小於產生開銷的單元與鄰近單元合併（最小單元下限）。粒度誠實性："更細 = 更快"會飽和 — 壁鐘時間 ≈ ceil(N/寬度) × 單元時間；當 N ≈ 2-4× 波次寬度時，開銷占主導 → 在下限和寬度上限內選擇接近最優的值。單元數量決定群體規模（100 個不相關的點 → 100 個訂單，按波次有界）。
3 · 提示（條件式，非阻塞）。 工作遠大於提示詞 → 發送上述一行提示，然後繼續。
4 · 波次。 有效寬度 = floor(平台寬度 × bandwidth%)（預設 25% ≈ 在 16 槽位平台上 4 個槽位）。逐波產生；每個工作進程獲得工作合約（references/contract-template.md），其中包含其範圍 + 共享摘要 + 鎖定的不變量。模型：每個平台上的預設模型相當於主體模型；在 Claude Code 上，CoalTipple 委派降級是可選增強功能（若無則安全降級）— 一個敏感單元（加密/認證/支付/遷移）即使在廉價群體中也保留在主體層級。AIMD 退避： 波次中途出現 429 錯誤 → 下一個波次縮小（乘法減少）；清晰的連續運行會緩慢增長（加法增加）朝向設定的 % — 高於帳戶實際容量的 % 會穩定在實際容量，不會發生故障；一個出現 429 錯誤的訂單是暫時的 → 等待 + 重試相同的訂單（日誌中保存），絕不會向用戶顯示失敗。從子代理安全繼承完整的邊界：有界波次 · 無殭屍（收集後釋放；超出超時時間回收靜默工作進程；權限等待不是靜默）· 工作進程 = 葉子 · 接近會話/配額限制時，收縮到更少的工作進程或內聯自行處理（在限制上死亡的工作進程不返回任何內容）。
5 · 回傳 = 文字形式的訂單（提議不執行）。 編輯內容 → 錨點編輯（舊文字 → 新文字，精確匹配，與位置無關 — 同一檔案 100 個點的情況也能運作，因為錨點不會移動）— 從不使用行號差異（每行套用後行號會變化），從不使用每個工作進程的工作樹（v1 中沒有工作樹路徑）。非編輯領域 → 完成的單元作為文字回傳（一段翻譯的文字、一條記錄、一份報告章節）。工作進程從不觸碰真實的樹；副作用僅在您同意的順序套用時觸發。
6 · 收集時的 QC（在任何套用之前）。 每次回傳時，機械性檢查：(a) 範圍 — 每個錨點都位於分配的範圍內，沒有外來檔案（區間檢查 ≈ 免費）；(b) 規格 — 鎖定的不變量可在輸出中透過 grep 驗證。拒絕 → 隔離 + 一次重新產生，附帶拒絕原因（有界，永不循環）；第 2 次失敗 → 收據交給人類。誠實的上限：一個範圍內、符合規格、語義上錯誤的回傳，如果沒有覆蓋性測試，會到達用戶 — 收據會標記測試未覆蓋的點；該類別的升級路徑是 CoalBoard（不允許錯誤的車道），而不是預設的 CoalFace。
7 · 套用 — 您是單一寫者**。** 首先獲取群體前的快照（git 儲存庫：stash/HEAD-record；非 git：檔案副本 — 從不假設 git 存在）。然後按拓撲順序順序套用接受的訂單。錨點遺失（真正的衝突）→ 跳過並標記，繼續 — 除非偵察標記為全有或全無的單元（類似遷移的任務類別）：一個失敗就進行完整回滾。最後執行領域閘道（程式碼 → 建置+測試 · 語料庫 → 語料庫規則 · 文件 → lint+連結 · 資料 → schema 驗證 · 研究 → 引用）。閘道紅燈 → 完整回滾到快照；透過收據報告發生的事情。
8 · 收據（總是提供）。 發現的點 · 使用的工作進程數 · 波次 · 有效寬度（例如 "6/14 — 穩定在帳戶層級"）· 令牌 vs 單人基準估計 · 被隔離的項目及其原因 · 測試未覆蓋的標記。格式 + 外行用語：references/receipt.md。收據 + 提示使用用戶的語言；技術術語保持原樣。
群體能力分類（偵察分類；無工作現場"中斷"）
| 工作現場形狀 | 模式 |
|---|---|
| 不相關的點（扁平） | 完整並行波次 — 工作進程數 = 單元數（下限/寬度有界） |
| 依賴鏈 | 拓撲排序的波次 / 相同工作進程鏈結；完整鏈 = 管線降級（保持隔離；誠實：無加速） |
| 全域不變量（詞彙表/風格/總計） | 先鎖定不變量 → 在共享摘要中傳遞它們 → 最後的一致性掃描閘道 |
| 整體品質（語調/架構） | 僅分析群體；由一個語調書寫（您） |
| 副作用 | 由提議不執行模式封閉 — 工作進程回傳文字；副作用僅在同意的套用時觸發 |
| 不可分解 | 誠實拒絕："無法群體化 — 單人/3 子任務" |
每個領域的單元/不變量/閘道表格 + 模式詳細資訊：references/taxonomy.md。
錢包（單人基準不變量）
整個群體（偵察 + 工作進程 + 套用）都包含在估計的單人主體成本內 — 將單人預算分配給螞蟻，而不是在其上增加新預算。這是可行的，因為工作進程不攜帶累積上下文（單人的後期單元會拖拽整個歷史記錄；群體單元則不會），而且在 Claude Code 上，廉價層級的每個令牌成本更低。防護措施：(1) 共享摘要（偵察支付一次，分發）；(2) 最小單元下限（小單元合併）；(3) 無工作進程自我重試 — 日誌 + 最多一次在剩餘部分重新產生（無重試風暴）。bandwidth 與錢包正交：它設定多快消耗相同的預算，而不是消耗多少。
日誌（每個工作進程回傳）
在產生時記錄每個工作進程分配的範圍，並在其落地時記錄其回傳的訂單 — 回傳的訂單在落地時即安全。一個死亡/停止/靜默的工作進程 → 從日誌中的未完成剩餘部分重新產生一個新的工作進程（從不重新啟動整個任務，從不循環）。日誌也為收據和任何部分報告提供資訊。
組合（優先綁定規則，先在此綁定）
- CoalBoard 在不允許錯誤的領域勝出（安全性/加密、資料庫/金融遷移、高精度）：關鍵工作交給共識，而非吞吐量；CoalFace 可能作為該委員會套用後處理器使用。
- CoalTipple（如果安裝）：每個工作進程委派降級層級 = 一個可選增強功能；其敏感閘道被繼承 — 敏感單元的工作進程保留在主體層級。
- 完整繼承子代理安全： 有界扇出 · 無殭屍 · 預算閘道 · 失敗的工作進程回傳，您重新路由 · 葉子沒有產生工具。
- 用戶/專案既定規則（例如翻譯規則）= 不變量：偵察將其讀入共享摘要；工作進程從不選擇規格已選擇的內容。
- 引擎： 存在平台工作流程/編排引擎 → 使用它；否則使用原生代理工具波次。
嵌套指揮（深度說明）
深度為 1 的子任務本身可以擔任指揮（為其範圍進行偵察 → 合約 → QC → 套用），在深度 2 產生其工作進程。從不更深：深度超過 2 時，產生會扁平化為一個獨立的、無法回收的頂層會話。工作進程是結構上的葉子 — 深度 2 沒有任何內容有理由產生。錢包沿著鏈條向下分割（您分配給子任務一個切片；它在其工作進程之間分割該切片）；收據向上彙整。
平台（跨代理）
透過平台的原生子代理工具產生（Claude Code Agent/Task · 每個平台各有其工具）。任何具有並行子代理的平台都執行完整合約；寬度透過 bandwidth 調整到本地上限；未知平台使用保守預設值。沒有扇出 → 在相同合約下降級為順序管線（偵察 → 依序執行單元 → QC → 套用）— 從不中斷。在您尚未實際運行過群體的平台/版本上，將寬度/嵌套行為視為未驗證 — 保守降級並說明情況。
配置 + 自我更新
合併設定檔：全域 ~/.claude/.coalface.json 被最近的專案 .coalface.json 覆蓋（專案按鍵勝出；查找遍歷停在主目錄）。鍵：coalfaceMode · bandwidth · autoFanoutFloor · updateMode · updateCheckDays — 每個數值在讀取時被限制。自我更新屬於 kind-1：掛鉤僅安排一個限速檢查；/coalface:update 在線驗證 + 提供更新，需經同意。
自我錯誤報告
如果 CoalFace 行為異常 — 矛盾的指令、循環的群體、違反合約的工作進程 — 請停止、總結，並提議將其回報到 github.com/TheColliery/CoalFace/issues。從不自動提交；從不包含未經批准的程式碼或路徑。這僅在模型注意到時觸發 — 一次乾淨的運行意味著 "未注意到任何問題"，而非 "沒有任何問題"。