crucible 是做什麼的？
平行領域探查 → 對抗性審查 → 規劃 → 驗證 → SPEC → 實作 → 合併請求。
檔案所有權規則
子代理程式絕對不寫入檔案。 它們只以文字形式回傳結果。您（協調者）負責寫入所有成品。檔案是跨階段的交接依據——子代理程式的記憶並非如此。
設定
解析呼叫中的參數：
- Domains（必要）——需稽核的使用者面向領域，例如
player、curator - Scope hint（選用）——縮小領域內的焦點，例如
lobby SSE、role selection
決定輸出目錄：.crucible/run-<N>/，其中 N 是下一個未使用的整數。
先前執行檢查：掃描 .crucible/ 中現有的執行目錄。讀取每個 findings.json。將其已確認的 ID 作為跳過清單饋入階段 1 的代理程式——不要重新發現已知已修復的問題；將精力集中在缺口上。
本次執行寫入的檔案（全部由協調者執行）：
| 檔案 | 階段 | 角色 |
|---|---|---|
codebase-map.md | 1 | 逐字注入所有下游代理程式的上下文 |
recon-<domain>.json | 1 | 每個領域的原始發現 |
findings.json | 1→2→4 | 合併後的發現；每個階段附加判決結果 |
PLAN.md | 3 | 按優先順序排列的修復計畫 |
SPEC.md | 5 | 每個發現的修正前後程式碼及測試案例 |
階段 1 — 探查
在啟動代理程式之前，必須先閱讀 references/recon-phase.md。
為每個已宣告的領域啟動一個研究代理程式，全部平行執行。提供給每個代理程式：程式碼庫路徑、領域名稱、範圍提示（如有）、要跳過的先前已知 ID。
代理程式回傳 JSON 文字。如果代理程式回傳的是散文而非 JSON 陣列，則使用 assets/findings-schema.json 中的確切結構形狀重新提示一次。如果再次失敗，則寫入一個空的 recon-<domain>.json（[]），並在 codebase-map.md 中記錄失敗原因。繼續執行——一個領域失敗是可恢復的；不要中止整個執行。
收集有效的回應，然後：
- 為每個代理程式的回應寫入
recon-<domain>.json - 綜合生成
codebase-map.md——關鍵檔案路徑、領域邊界、共享模組、慣例 - 將所有領域的發現合併到
findings.json中
完成條件：每個領域都有 recon-<domain>.json、codebase-map.md 已寫入、findings.json 已寫入。在階段 2 之前，請勿載入 references/adversarial-phase.md。
階段 2 — 對抗性審查
在啟動代理程式之前，必須先閱讀 references/adversarial-phase.md。
為每個發現啟動一個通用代理程式（批次處理來自同一個領域的發現）。每個代理程式會取得發現 JSON 和 codebase-map.md——而不是探查代理程式的推理過程。獨立性邊界是品質把關的關鍵。
代理程式回傳 CONFIRMED / REJECTED / DOWNGRADED，並附上程式碼證據。將每個判決結果附加到 findings.json 中相對應的條目。執行 node scripts/validate-findings.cjs findings.json——在階段 3 之前修正任何結構錯誤。
當驗證器本身無法執行時——node 不在 PATH 中、腳本或其結構描述遺失、使用方式錯誤，或驗證開始前的任何失敗（Failed to load schema、Failed to parse JSON）——這不是通過。在發現輸出和 SPEC 交接檔案的頂部註明 ⚠ findings unvalidated — validator unavailable: <reason>，然後繼續。相反地，結構描述拒絕則總是會阻斷：修正發現、重新執行，在拒絕的情況下不得繼續。兩者目前都會退出碼為 1，因此請讀取錯誤文字，而不是退出碼。
完成條件：每個發現都有 adversarial_verdict 欄位。結構驗證通過。從此時起，請勿重新載入 references/recon-phase.md。
階段 3 — 計畫綜合
零發現檢查：在綜合之前，計算 findings.json 中已確認與降級的條目數量。如果為零，則寫入 .crucible/run-<N>/REPORT.md，內容只有一行「No actionable findings after adversarial review.」。停止——不要開啟合併請求。
將 findings.json 中已確認與降級的發現綜合到 PLAN.md：
- P1（嚴重/高）：核心流程損壞、資料遺失、永久斷線
- P2（中）：使用者可見錯誤、缺少復原路徑
- P3（低）：潤飾、文件偏差、文案問題
將共享根因的發現分組——一個修復可能解決多個問題。分組時：分組中最高嚴重性設定該組的優先級。如果分組的發現有衝突的修復方法，則將其拆分——共享根因不要求共享修復。在存在依賴關係的地方宣告修復順序。完全排除被拒絕的發現。
完成條件：PLAN.md 已寫入；每個已確認的發現恰好出現一次。
階段 4 — 獨立驗證
為每個 P1 + P2 發現啟動一個研究代理程式，全部平行執行。告知每個代理程式：「你並非此發現的撰寫者。請根據當前原始碼驗證每一個事實主張。」
每個代理程式檢查：檔案是否存在於指定路徑、行號是否與描述的程式碼相符、領域名稱是否正確、所描述的模式是否實際存在。回傳 VERIFIED / CORRECTED [field: wrong → right] / REJECTED [reason]。
將所有修正應用到 PLAN.md 和 findings.json。再次執行結構驗證。PLAN.md 和 findings.json 必須一致——交付物之間不得有不一致。
完成條件：所有 P1+P2 發現均已驗證。所有修正均已應用。結構驗證通過。
階段 5 — SPEC
撰寫 SPEC.md，為每個已確認的發現（按 P1 → P2 → P3 順序）提供一個章節：
- 確切的檔案路徑 + 行號範圍（已驗證）
- 修正前的程式碼（真實原始碼，而非虛擬碼）
- 修正後的程式碼（具體的修復方案）
- 測試案例：每個測試必須驗證的行為用一句話描述
執行 node scripts/validate-findings.cjs findings.json 作為最終檢查。
完成條件：PLAN.md 中的每個條目都有對應的 SPEC 章節。驗證通過。
階段 6 — 交接
- 更新任何會改變使用者行為的發現的流程文件（
docs/flows/） - 使用
SPEC.md呼叫implement技能 - 開啟一個合併請求——這是人機迴圈（HITL）的關卡；無需請求中間批准
合併請求主體：連結至 PLAN.md、按嚴重性分類的發現數量、連結至 SPEC.md、已更新的流程文件清單。
絕對不要
-
絕對不要要求子代理程式寫入檔案 替代方案： 讓代理程式以文字形式回傳內容；您自己寫入檔案。 原因： 跨階段的狀態存在於檔案中。如果代理程式直接寫入，協調者將失去規範副本，並且無法在階段 4 修正後協調交付物。
-
絕對不要將探查代理程式的推理鏈提供給對抗性代理程式 替代方案： 僅傳遞結構化的發現（JSON）和
codebase-map.md。 原因： 看到探查代理程式的邏輯會將對抗性代理程式錨定在相同的假設上——獨立性邊界是消除假陽性的關鍵。 -
絕對不要在結構驗證失敗的情況下繼續階段 2 替代方案： 在綜合計畫之前，修正
findings.json中失敗的欄位。 原因： 基於格式錯誤的發現所建立的計畫，會產生帶有錯誤檔案路徑與行號的 SPEC，而implement技能無法使用這樣的 SPEC。 -
絕對不要在還有任何 P1/P2 發現的
verification為"pending"時撰寫SPEC.md替代方案： 執行node scripts/validate-findings.cjs findings.json --pre-spec，並在階段 5 之前解決所有失敗。 原因：--pre-spec保護機制存在於驗證器腳本中，但若非主動呼叫則不可見——跳過此呼叫的代理程式將會基於未經驗證的檔案路徑來撰寫 SPEC，並無聲地將錯誤的行號傳遞給implement。