Orchestrate Jig(流程編排)
合約
協調符合 Jig 當前設計合約的執行導向工作。此技能是一個本地編排操作手冊(runbook),而非 Jig 運行時實現、CLI、提供者適配器或記錄儲存庫。它只能在核准的輸入、當前工具介面、政策立場和可記錄性允許的範圍內,組織人類或 Codex 輔助的執行流程。
執行計畫擁有範圍主導權。它必須已包含由 docs/design/contracts/execution-plan-contract-v0.md 所述的故事集合、依賴關係、工作邊界、完成與證據要求、權限預期、政策/工作設定檔/儲存庫基準參考、約束條件和相容性姿態。此技能可以拒絕、綁定、排程、停止或報告。它不得憑空發明故事、修改依賴關係、削弱政策、新增驗收標準、選擇完成證據、重新解釋範圍外的領域,或將遺失的計畫事實轉換為運行時決策。
紀錄即是證據。每個被治理的決策、授權、停止、證據觀察、審查結果和執行者擁有的動作,在根據 docs/design/contracts/observability-records-contract-v0.md 被視為真實之前,都必須能夠被記錄。任何單獨的敘述、聊天摘要、檢查清單或工作者報告,皆不得覆蓋可記錄的證據封包。
參考邊界
已廢棄的 workflow-kit 編排交付技能僅為先前技術。只有在有助於維護 Jig 自身合約的情況下,才應沿用這些經驗教訓:
- 在分派前預先檢查執行輸入;
- 在預檢之後、而非規劃期間綁定運行時事實;
- 保持工作者產生的變更與執行者擁有的特權動作分離;
- 在聲明完成或落地狀態之前,需要獨立的證據;
- 留下可恢復的、具名(named)的停止點,而非透過猜測來應對缺失的能力。
請勿匯入 workflow-kit 的執行封包路徑、追蹤器架構、每個故事專用的提示資料夾、模型路由表、提供者套件佈局、v-next 分支政策、舊的 PR 發布規則或舊的運行時聲明。如果某個先前技術規則無法映射到 Jig 的 v0 計畫或記錄屬性,請忽略它,並指出該停止點或設計缺口。
輸入
在任何工作者分派或特權動作之前,需要所有以下項目:
- 一個與
execution-plan-contract-v0相容的已核准執行計畫; - 該計畫所綁定的政策參考、工作設定檔參考和儲存庫基準參考;
- 擁有者對在所請求邊界上啟動或預覽的核准;
- 針對運行位置的當前儲存庫/工作樹事實;
- 對於啟動、執行或落地邊界:Agent、執行主機(Execution Host)、Forge 和工作來源(Work Source)的當前驅動程式/接縫(seam)事實,或者如果無法檢查所需的接縫,則需明確停止;
- 對於僅預覽邊界:足夠的綁定事實以記錄
run.previewed,而無需運行身份、工作區分配、提供者配線或特權副作用; - 來自計畫和政策的當前驗證命令和證據要求;
- 一個能夠為此本地運行保留
observability-records-contract-v0屬性的記錄路徑、記錄儲存庫或持久化記錄封包格式。
未知的運行時事實在被檢查之前應保持未知。遺失的計畫事實並非運行時事實;它們是計畫預檢失敗。
預檢
在分派、編輯、推送、PR、合併、狀態發佈或任何 Jig 已開始的聲明之前,執行此閘門。
- 確認已針對受影響的領域閱讀了儲存庫說明文件和真實來源文件:
AGENTS.md、docs/product/jig.md、docs/product/guarantees.md、docs/product/concepts.md、docs/design/README.md、docs/design/contracts/execution-plan-contract-v0.md、docs/design/contracts/observability-records-contract-v0.md、docs/design/core/orchestration.md和docs/design/core/records.md。 - 驗證計畫已獲得擁有者或擁有者規劃步驟的核准。如果缺乏核准,則以
plan-not-approved停止。 - 驗證計畫包含 v0 要求的屬性:
- 計畫身份與來源出處;
- 追踪(track)綁定;
- 故事集合;
- 依賴與資格模型;
- 完成與證據要求;
- 權限與核准需求;
- 政策與工作設定檔參考;
- 堆疊接縫要求;
- 約束與限制。
- 驗證計畫的版本或相容性標記是可理解的。如果不是,則以
plan-format-unsupported停止。 - 驗證每個被選中的故事都具有穩定的 ID、預期邊界、依賴清單、證據要求和權限預期。如果任何被選中的故事要求執行者或工作者推斷範圍,則以
plan-scope-incomplete停止。 - 驗證可以在不重寫計畫的情況下推匯出依賴順序。如果圖形是循環的、矛盾的或需要發明排序,則以
plan-dependency-invalid停止。 - 驗證政策、工作設定檔和儲存庫基準參考都存在,並且與所請求的運行相容。如果它們缺失、不相容,或會削弱啟動時的政策,則以
binding-input-missing停止。 - 驗證所請求的邊界是否受支援:預覽、本地執行協調、證據收集、執行者擁有的發布或停止。預覽是非提交性的:它需要載入、驗證、綁定和一個可記錄的
run.previewed事件,但不需要運行身份、工作區、提供者或特權副作用。如果使用者請求當前儲存庫中不存在的真實 Jig 行為,則以jig-runtime-unavailable停止。
預檢可能會產生一個提議的執行順序、拒絕或具名停止。它不得修復計畫。
運行時綁定
預檢通過後,僅綁定當前事實:
- 工作樹路徑、儲存庫根目錄、分支、基礎分支和乾淨度;
- 生效的政策、工作設定檔和儲存庫基準參考;
- 從計畫圖形中選出的故事以及當前符合資格的故事;
- 當前的驗證命令、審查要求和能力證明要求;
- 當前的擁有者核准狀態和請求的停止邊界;
- 對於啟動、執行或落地邊界:Agent、執行主機、Forge 和工作來源驅動程式的可用性和證明姿態;
- 對於僅預覽邊界:預覽綁定姿態以及可記錄的
run.previewed基礎,而不強制進行提供者配線; - 記錄目的地或記錄封包位置及其編輯/匯出姿態;
- 當前介面上可用的執行者擁有的動作,例如推送、PR 建立、狀態/評論發佈和合併。
在啟動前記錄這些綁定。啟動綁定在恢復過程中是不可變的:恢復可能會從已停止的運行繼續,但不得靜默地交換政策、工作設定檔、儲存庫基準、計畫或驅動程式事實。變更的安全相關假設需要在繼續之前獲得新的擁有者核准和新的證據。
執行者與工作者邊界
保持來自 docs/product/concepts.md 和 docs/design/core/orchestration.md 的產品權限邊界。
- 工作者只能在授權的故事邊界內進行讀取、編輯、執行非特權檢查、產生差異(diff)、產生證據和報告阻礙事項。
- 工作者不得推送、開啟或更新 PR、發佈狀態/評論、合併、擴展權限、編輯政策基準、將故事標記為已落地,或作為事件的權威來撰寫紀錄。
- 執行者負責協調資格、授權、證據評估、紀錄、擁有者升級、推送、PR 建立、狀態/評論發佈、合併、停止、恢復和匯出。
- 特權動作需要執行者權限加上政策/證據基礎。工作者的自我報告永遠不足以將特權動作標記為完成。
- 超出聲明權限的請求應失敗關閉或轉交給擁有者;它永遠不會變成更廣泛的隱含授權。
如果當前介面無法維持此分離,則以 authority-boundary-unsupported 停止。
協調循環
使用計畫圖形和 Jig 生命週期術語,而無需新增狀態。
- 僅啟動其先決條件已根據計畫和當前紀錄「落地」的故事。
- 讓不符合資格的故事保持等待;不要要求工作者自行決定依賴關係。
- 對於符合資格的故事,使用故事邊界、計畫參考、權限預期、證據要求、驗證命令、非目標和變更限制來分派工作者。
- 將工作者輸出視為提議的工作和證據,而非狀態權威。
- 僅根據執行者或委派審查者觀察到的、符合政策的證據來評估「完成」。
- 將
done和landed保留為獨立的里程碑:當滿足證據要求時,故事可以「完成」,而合併仍可能因審查、分支保護、衝突、佇列或擁有者邊界而受阻。 - 僅在必要的證據、擁有者/審查者核准(如需要)以及記錄追加/封包準備全部成功後,才透過執行者擁有的動作來「落地」。
- 如果一個故事受阻,記錄原因和受影響的下游故事;當政策和能力允許時,獨立的兄弟故事可以繼續。
除非未來的 Jig 設計合約引入,否則請勿新增追蹤器、故事封包、提示封包或合併回送模型。
證據與紀錄閘門
在將狀態轉換或被治理的決策視為已接受之前,準備一個可記錄的封包,其中包含適用於所請求邊界的 v0 屬性:
- 對於已提交的啟動/恢復/執行路徑:運行身份、嘗試身份、計畫參考、追踪參考、政策/工作設定檔/儲存庫基準參考和驅動程式上下文;
- 對於僅預覽路徑:計畫參考、追踪參考、政策/工作設定檔/儲存庫基準參考,以及非提交性的
run.previewed基礎,而不發明運行身份或驅動程式上下文; - 使用 Jig 當前事件族的高度來描述事件族與結果;
- 負責的行為者或元件:工作者、執行者、擁有者、委派審查者或驅動程式;
- 基礎:政策規則、證據觀察、核准、能力證明、先前事件或計畫參考;
- 適用的故事 ID;
- 編輯/匯出姿態;
- 足以用於重播或恢復的排序資訊;
- 任何阻塞、停止、通知、恢復檢查點或無雙重效果基礎。
自動化檢查、審查和能力證明必須被觀察或獨立驗證。如果證據缺失、過時、僅為自我報告、無法驗證或無法記錄,則該故事未完成,必須以 evidence-insufficient 停止。
停止
優先使用具名停止而非臨時執行。停止報告必須包含停止名稱、受影響的運行或故事、失敗的閘門、可記錄的基礎、可用的安全恢復檢查點,以及下一個擁有者動作。
除非存在更具體的計畫擁有停止名稱,否則使用以下停止名稱:
plan-not-approved— 無已核准的執行計畫或啟動核准。plan-format-unsupported— 計畫相容性標記或形狀未知。plan-scope-incomplete— 缺少所選故事的範圍、邊界、證據或權限需求。plan-dependency-invalid— 依賴圖形無法按編寫的方式執行。binding-input-missing— 政策、工作設定檔、儲存庫基準或相容性參考缺失或不相容。jig-runtime-unavailable— 請求的行為需要超出當前本地乾執行 CLI (jig preview/jig run/jig inspect) 的 Jig 運行時能力。driver-capability-unavailable— 無法證明所需的 Agent、執行主機、Forge 或工作來源能力。authority-boundary-unsupported— 當前介面無法維持執行者擁有的特權動作和受限的工作者權限。records-store-unavailable— 沒有持久的記錄儲存庫或可記錄封包能夠保留 v0 記錄屬性。evidence-insufficient— 所需的證據缺失、無法驗證、過時或僅為自我報告。owner-decision-required— 政策將一個狹隘的決策路由給擁有者。safety-reapproval-required— 在恢復或落地之前,規則治理或安全相關的輸入發生了變更。
停止是一個有效的結果。當缺失的條件是 Jig 控制、證據、恢復或可觀察性保證的一部分時,請勿將停止軟化為警告。
輸出
返回一個精簡的運行分類帳(ledger),而非完整的對話轉錄:
- 計畫參考和所選故事 ID;
- 已綁定的政策、工作設定檔和儲存庫基準參考;
- 已檢查的運行時事實和未解決的未知事實;
- 符合資格、已啟動、已停放、受阻、已完成、已落地、已拒絕、已停止、已恢復或已完成的狀態(在可記錄的範圍內);
- 觀察到的證據和已運行的驗證命令;
- 已執行或明確未執行的執行者擁有的動作;
- 停止名稱、原因、安全恢復檢查點和下一個擁有者動作;
- 記錄封包/儲存庫參考和編輯姿態;
- 不受支援的能力或設計缺口,應回饋給所屬的 Jig 設計/規劃領域。
如果對於聲稱的狀態不存在可記錄的證據,則將該狀態報告為未經驗證並停止。