Kronuz/campaign

Campaign (活動管理)

主導者(lead) (主要 session) 將擁有者(owner) 的目標轉化為任務(quests)。一個貢獻者(contributor) 代理在它自己的分支上完成每個任務；機器工作進入一個工作佇列(job queue)，該佇列在沒有任何代理等待的情況下，於精確的提交點執行這些工作。當一個任務的風險需要時，一個審查者(reviewer) 代理會從全新的上下文中檢查該任務。campaign land 只有在任務在精確的程式碼上通過檢查、每個標準都有其所需的證據、且每個必要的審查都接受了它所審查的程式碼時，才會將其放置到 main 分支上。所有重要事項都保存在儲存庫中，因此任何代理（包括主導者）都可以被替換。

goals ─► PLAN ─► quests ─► campaign start ─► contributor ─► jobs (quiet) ─► evidence
                                                  │                              │
                                                  └─► reviewer (by risk) ─► accept ─► campaign land

不變定律 (Invariants)

1. 證據，而非敘述。 只有當一個工作在被合併的程式碼上實際運行時，檢查才算數；日誌中的一行或審查者的口頭背書永遠不能視為綠燈測試。
2. 每個檔案集只有一個寫入者。 campaign start 會拒絕重疊的檔案集；land 會拒絕修改任務檔案集之外的更改，以及編輯主導者檔案的更改。
3. 先有標準，後有程式碼。 主導者撰寫每個任務的驗收標準及其所需的證據；貢獻者不得編輯它們，且更改後的任務檔案會使先前的驗收失效。
4. 審查跟隨風險。 每個需要審查的風險都指派一位新的審查者；一個驗收涵蓋該審查所檢查的程式碼及審查的確切內容。
5. 沒有任何削弱是悄無聲息的。 降低風險、移除審查維度或檢查、豁免審查、在沒有 CI 的情況下合併或記錄手動完成的合併都需要一個理由，該工具會記錄這個理由。
6. 狀態存在於檔案中。 .campaign/<campaign>/ 和 git 記錄了活動的運行方式；產品的說明文件則位於其所描述儲存庫的 docs/ 目錄下。
7. 代理永遠不等待機器，且測量永遠在隔離環境中運行。
8. 擁有者決定目標、範圍以及任何對用戶可見行為的移除或縮減。 主導者決定其餘事項並記錄在 PLAN.md 中。活動從不租用機器 或產生任何其他可計費資源。

角色 (Roles)

角色	職責	撰寫內容
擁有者 (人類)	目標、非目標、保留決策	PLAN.md 目標
主導者 (主要 session)	規劃任務、啟動代理、接受審查、合併、向擁有者報告	state.json (僅透過 campaign)、任務檔案、PLAN.md、main
貢獻者 (campaign-contributor 代理)	一個任務或子任務，依據其指派	其分支和日誌
審查者 (campaign-reviewer 代理)	從全新上下文中，透過一個維度審查一個任務	一份審查檔案

一個貢獻者的指派(assignment) 指明工作的種類；除了實作之外，每種工作類型在 references/assignments/<name>.md 中都有一個方法。主導者在每次啟動時指定指派、模型層級和投入程度，根據工作本身而非習慣來選擇：

指派	適用場景	層級，投入程度
implementation	具有具體標準的功能和修復	economical, medium (低和一般風險)；strong, high (高和嚴重風險，或在 economical 嘗試停滯後)
design	針對重要計畫的任務列表；格式、協定、持久性、並發性	strong, high；對於即將定案的設計使用 max
research	極少使用：當機制本身是限制時	strong, max
performance	效能分析和最佳化	strong, high
exploration	探索批次中的一個目標，或一個快速問題	economical, medium
documentation	文件、指南、README	economical, medium
maintenance	跨儲存庫的一次性機械性變更	economical, medium

審查者使用 strong 層級和高投入程度（嚴重任務使用 max）；對於嚴重任務和計畫挑戰，當 harness 提供時，使用來自不同模型家族的審查者。每個 harness 對應各層級的模型在 references/harness.md 中。根據結果（campaign usage、滿足標準、返工）而非僅僅是價格來更改預設值。主導者自己進行小的編輯（五行修復、微不足道的衝突）：啟動一個新代理的成本更高。

啟動一個活動 (Start a campaign)

1. 在主儲存庫的主要 checkout 中：campaign init --name NAME [--ci github]。擁有者在 .campaign/<campaign>/PLAN.md 中撰寫目標、非目標、限制和保留決策。
2. 將目標拆分為任務：campaign new ID --title T --risk R --files GLOBS [--needs IDS] [--after IDS] [--provides C] [--consumes C] [--milestone M] --check NAME[:LEVEL[:MIN]]=CMD。填寫每個任務檔案（.campaign/<campaign>/quests/ID.md）：成果、標準 A1... 每個標準附帶其所需的證據（見下方證據章節）、合約、決策、哪些部分可以提前合併。
3. 當架構影響重大時，一個審查者（design 維度）會在開始構建任何東西之前挑戰計畫和任務列表。這是唯一值得等待的審查。

任務 (Quests)

• 大小： 能夠交付一個完整、有意義行為的最小變更，且審查者能記在腦中，通常幾百到約 1500 行。拆分更大的任務；將不值得單獨合併的變更折疊到它所服務的任務中。
• needs 必須在任務啟動前合併；after 必須在任務合併前合併。一個任務可以針對一個 after 依賴啟動，前提是該依賴的任務檔案固定了合約。
• 合約 (--provides, --consumes) 命名了 API、格式和協定，以便 campaign check 能夠看到兩個觸及同一個合約的任務。
• 子任務 (Tasks)： 一個任務內部的並行編寫者（campaign start ID --task T --files GLOBS），由主導者合併到任務分支。該任務仍然只被審查一次。
• 增量 (Increments)： campaign land ID --upto COMMIT --reason R 會合併一個前置部分，前提是任務檔案中的「可提前合併 (May land early)」部分允許（保留行為的重構、測試、未使用的內部 API、被禁用開關後的程式碼）。永遠不能提前的部分：磁碟或網路上的位元組、公開 API、用戶可見行為，或審查存在的目的。
• 跨儲存庫工作 是由 after 排序的多個任務（--repo PATH），並有一個整合工作來固定每個儲存庫的提交（--ref NAME=PATH@REF）。合併是有序的，而非原子性的：每個中間狀態都必須能正常工作。
• 訊息： 一個代理在其機器上的任何活動中，對於它當前未處理的任務有發現時，可以發送 campaign message NAME:ID "文字" --from WHO。該任務在它的某個日誌以其 id（msg-N）回覆之前，或主導者關閉它之前（campaign message ID --close msg-N --reason R），不得合併；NAME: 寫給該活動的主導者，並且永遠不會阻止合併。詳情和其他機器：references/host.md，訊息章節。
• 範圍變更： 新的需求首先放入任務檔案（一個標準，或者如果它可以單獨合併則作為一個新任務），然後交給貢獻者；被取代的工作使用 campaign set ID status=dropped reason=...。

直接路徑優先 (Direct path first)

只有決定下一步的事情才會阻塞它。一個任務的關卡檢查 (gate checks)（--check：建置、測試及其風險所需的證據）會阻止其合併。其延遲檢查 (deferred checks)（--later：其他平台、長時間浸泡、完整矩陣、擴展模糊測試）以低優先級排隊在已合併的程式碼上，並且必須在里程碑關閉前通過。一個紅色的結果是 campaign check 中的錯誤：向前修復或還原，然後 campaign verify ID --deferred 在 main 上重新運行它們。高或嚴重風險所需的證據（並發性的 TSan、解碼器的模糊測試、持久性的崩潰模型）始終是關卡檢查。慢速的 CI 工作流程可以同樣的方式改為非關卡檢查（campaign config ci_later=NAME,...）。

運行一個任務 (Run a quest)

1. campaign start ID 在其自己的工作樹中建立 quest/<campaign>/ID 並附帶一個日誌。在背景中啟動一個貢獻者，以便可以透過訊息恢復，使用「貢獻者」提示詞（references/prompts.md）；只有當準備好、不重疊且不等待同一台機器時，才並行運行任務。
2. 貢獻者在其工作樹中工作，保持其日誌最新，並以工作的形式產生證據：campaign job submit --quest ID --level L --minutes M -- CMD 和 campaign verify ID。當只剩下工作時，它記錄這些工作的 id 並結束其回合。
3. 主導者使用一個背景 campaign wait --commits 等待（在工作結束、分支移動或訊息到達之前不消耗 token），然後在其上下文仍然很小（約 150k token）時透過訊息恢復貢獻者。較大的上下文，或無法恢復它的 harness，會得到一個帶有「Resume (恢復)」提示詞的全新貢獻者，該提示詞會從日誌和工作記錄中重建。
4. 當日誌顯示「準備好審查 (ready for review)」時，主導者設定 status=review 並啟動風險所需的審查者；每個審查者撰寫 .campaign/<campaign>/reviews/ID-LENS.md。主導者將阻塞性發現透過 id 傳遞給貢獻者。
5. campaign accept ID LENS 在審查批准後，或在變更（CHANGES）以確認工作完成後執行（風險和審查）；它提交包含驗收的審查檔案。然後執行 campaign land ID，它也會移除任務的工作樹、已合併的分支和建置槽位，並記錄它保留了什麼。

探索批次 (Exploration batches)

對於值得探索的清單（新的基準測試中的落後行、性能分析的熱點、證據不足的程式碼、累積的小錯誤），可以一次發送幾個 economical 貢獻者，每個處理一個目標，目標來自對當前 main 的最新測量：references/assignments/exploration.md。批次的大小由其目標以及主導者能夠審查和合併的容量決定，切勿根據空閒配額。

風險與審查 (Risk and review)

風險 (首次符合者取勝)	開始建置前	最終合併前
critical (嚴重)：不可逆的（為發布凍結格式或協定、遷移用戶資料、移除用戶可見行為）	擁有者批准；一次 design 審查	高風險的審查，加上審查者自己運行的驗收證據
high (高)：持久性格式、網路協定、持久性、並發性、安全面、共享公開 API	當決策難以逆轉時，一次 design 審查	由主導風險維度（durability、security 或 correctness）進行一次審查
normal (一般)：普通功能和修復	—	一次 correctness 審查，或對於有強力證據的小變更使用 --waive REASON
low (低)：文件、測試、工具、機械性編輯、保留行為的重構	—	檢查通過；主導者閱讀 diff

• 預設為一個審查者， 處理任務引發的所有風險問題（提示詞中命名三到五個）。只有在需要獨立專業知識或獨立性的問題時才需要第二個審查者。
• 審查與其所審查的內容綁定。 它命名了審查的提交 (Commit:)、一個判決和一個發現表格，每行包含 ID、是否阻塞 (Blocking: yes/no) 和類型 (Kind: defect, gap, nit)。APPROVE 覆蓋該提交的程式碼；僅觸及 .campaign/ 的提交保持有效。在驗收後編輯審查會使驗收無效。
• 修復由工作確認，而非重新審查。 對於每個阻塞性發現，在修復後的提交上將偵測方法或新測試作為工作重新運行，然後執行 campaign accept ID LENS --confirm C1=JOB --confirm C2=JOB。一個工作僅當其在任務儲存庫中接受的程式碼上通過時才確認；阻塞性缺陷需要更改程式碼；該工具會記錄相同的偵測方法是否在審查的提交上失敗。一個修復更改了審查從未見過的檔案，則需要返回給審查者（審查命名修復後的提交並批准），除非 --fix-scope REASON 說明為何它沒有添加新機制（例如，為某個發現添加的回歸測試）。
• 兩輪修復，然後停止。 第三輪意味著任務或設計是錯誤的：重新規劃或詢問擁有者。非阻塞性發現變成一個後續任務，或者帶著理由被丟棄。
• 設計只審查一次。 使用可執行的模型或測試來解決有爭議的行為，而不是另一輪文字討論。
• 任務必須通過的條件只能透過記錄變更： campaign set ID ... --weaken REASON 降低其風險、移除一個維度，或移除、更改或推遲一個檢查；此變更會保留在其歷史中，由 campaign status ID 顯示，並使其驗收失效。風險所需的審查（低風險以上的程式碼審查，嚴重風險的設計審查）不能被移除，且一旦存在審查，豁免就會被拒絕。
• 系統審查基於事件，而非固定時間： 當 campaign check 報告兩個任務更改同一個檔案或合約時，請求一個審查者（system 維度）處理該特定問題。
• 產出率 (Yield)： campaign status --reviews 計算判決和阻塞性缺陷的數量。一個在特定類型的大約五個任務中都找不到實質問題的可選審查（一般風險）將會被該類型任務的審查流程中移除；高和嚴重風險的審查永遠不會因產出率而被移除。

證據 (Evidence)

任務檔案中的每個標準都命名了其所需的證據；日誌的證據表格為每個標準提供一行，而合併時會檢查在正要被合併的程式碼上的每一行：

標準	其行必須命名
- A1 ... (無標籤)	一個在該程式碼上通過的工作（它自己，或重新運行的同一工作）
- A2 [artifact] ...	一個提交到任務儲存庫中的 path
- A3 [decision] ...	PLAN.md 的決策表格中的一個 id
- A4 [manual] ...	誰手動檢查了什麼；標記為手動，永遠不能作為自動化證明

證據應與聲明成正比（references/review.md）：測試檢查數值，而非計數；修復應包含一個沒有此修復就會失敗的測試；聲明應有一個突變體測試能被殺死；清理器應在單獨的建置中運行。效能聲明應遵循 references/measurement.md：在命名的提交點上有前後對比，對於任何決定性的數值應使用 exclusive，並誠實地呈現數量級。

機器工作 (Machine work)

等級	用途	隔離 (quiet)
none	微小的單執行緒探測	無需等待
light	建置、測試套件、模糊測試	少量並行執行，nice 19
strict	煙霧計時、行為測試	在 Linux 上獨佔核心；在 macOS 上獨佔機器
exclusive	決定

…

[已截斷以利翻譯]