grace-multiagent-execute

複数のエージェントを使って GRACE 開発計画を実行し、計画成果物と共有コンテキストの一貫性を保ちます。

前提条件

• モジュールの契約と実装順序を記した docs/development-plan.xml が存在する必要があります
• docs/knowledge-graph.xml が存在する必要があります
• モジュールごとの検証コマンドとゲートの要件を記した docs/verification-plan.xml が存在することが望ましいです
• docs/operational-packets.xml が存在する場合は、正規のパケットおよび差分の参照元として使用します
• 計画またはグラフが不足している場合は、直ちに中止し、大規模なエージェント投入の前にユーザー自身で $grace-plan を実行するよう伝えます
• 検証計画が不足しているか、まだ骨子のみの場合は、直ちに中止し、大規模なエージェント投入の前にユーザー自身で $grace-verification を実行するよう伝えます
• モジュールごとの検証コマンドがすでにある場合、または明確に定義できる場合にのみ、このスキルを優先します

基本原則

アーキテクチャの正しさではなく、モジュールの実装を並列化します。

• 共有成果物である docs/development-plan.xml、docs/knowledge-graph.xml、docs/verification-plan.xml、フェーズのステータス、実行キューは、1 人のコントローラーが管理します
• ワーカーエージェントが担当するのは、割り当てられたモジュールのファイルとモジュール固有のテストのみです
• レビュアーがモジュールの成果物を検証してから、コントローラーがグラフと計画を更新します
• スピードは、コンテキストのより適切なパッケージ化、共有成果物のまとめた処理、範囲を限定したレビューによって高めます。ワーカーにアーキテクチャを独自に考案させてはなりません
• パケットは、ワーカーが進行中に目標の解釈を確認しなくても済むだけの内容にします
• コントローラーによるチェックポイントは、作業中の頻繁な介入より重要です。曖昧な追加プロンプトでワーカーが自ら修正することを期待するのではなく、ウェーブ間にパケットを改訂します

複数のエージェントが同じモジュール、同じ共有 XML ファイル、または密接に結合した同じ範囲を編集する場合、それはマルチエージェントのウェーブではありません。代わりに $grace-execute を使用してください。

実行プロファイル

ユーザーから別の指定がない限り、デフォルトの balanced を使用します。

safe

• エージェントを投入する前に、提案するウェーブの承認を求めます
• すべてのモジュールの成果物について、契約レビューと検証レビューを実施します
• 各ウェーブ後に対象を絞ったグラフ同期を行い、各フェーズの境界で全体を更新します
• モジュールが新規性の高いもの、リスクの高いもの、または十分に把握されていない統合領域に触れる場合に使用します

balanced（デフォルト）

• 実行開始時に計画とグラフを一度解析します
• 実行中に計画が変更されない限り、実行スケジュールについて開始前に一度承認を求めます
• 各ワーカーに XML 成果物全体を読み直させるのではなく、簡潔な実行パケットを渡します
• ワーカーごとにモジュール固有の検証を実施し、モジュールごとに範囲を限定したゲートレビューを行い、ウェーブまたはフェーズごとに整合性チェックをまとめて実施します
• 各ウェーブ後に対象を絞ったグラフ同期を行います。全体の更新は、フェーズの境界、ドリフトが疑われる場合、または最終的なまとめの際にのみ行います

fast

• 十分に成熟し、堅牢な検証体制と安定したアーキテクチャを備えたコードベースでのみ使用します
• 問題または計画変更が発生しない限り、実行全体について一度だけ承認を求めます
• ワーカーパケットは簡潔にし、厳密な範囲の実行に必要な最小限のコンテキストのみを求めます
• ウェーブ中にブロックするのは、範囲を限定したレビューで見つかった重大な問題のみとし、より詳細な整合性監査はフェーズ終了時または最終的なまとめの際にまとめて実施します
• 全体の更新は、フェーズ完了時または最終的な整合性調整時に行います

モジュールごとに、必ず新しいワーカーを割り当てます。モジュール間でワーカーセッションを再利用して、このワークフローを最適化してはなりません。

プロセス

ステップ 1：実行ウェーブを一度だけ構築する

実行ごとに docs/development-plan.xml、docs/knowledge-graph.xml、docs/verification-plan.xml を一度読み込み、実行キューのコントローラービューを構築します。

1. 未完了の Phase-N と step-N の項目を解析します

2. ステップを並列実行可能なウェーブにグループ化します

3. ステップが並列実行可能なのは、次のすべてを満たす場合に限ります：

   • すべての依存関係がすでに完了している
   • ウェーブ内の他のすべてのステップと書き込み対象が重複しない
   • 同じ統合箇所への編集を共有する必要がない

4. 実行プロファイルとして safe、balanced、fast のいずれかを選択します

5. 各ウェーブについて、すべてのモジュール用に簡潔な実行パケットを準備します。パケットには次の内容を含めます：

   • モジュール ID と目的
   • 対象ファイルパスと正確な書き込み範囲
   • プロジェクトで定義されている場合は、docs/technology.xml から抜粋した優先スタックまたはツール
   • docs/development-plan.xml から抜粋したモジュールの契約
   • docs/knowledge-graph.xml から抜粋したモジュールのグラフエントリー
   • DEPENDS に含まれるすべてのモジュールの依存関係契約の要約
   • docs/verification-plan.xml から抜粋した検証内容。モジュール固有のコマンド、必須シナリオ、必須ログマーカー、対象テストファイルを含めます
   • 書き込み範囲内で許容される前提条件または未解決の依存関係
   • ワーカーを直ちに停止させる停止条件または再計画のトリガー
   • 修正またはレビューのループに対する再試行予算
   • マージ後に実行するウェーブレベルの統合チェック
   • 想定されるグラフ差分の項目：インポート、パブリックエクスポート、パブリックアノテーション、CrossLinks
   • 想定される検証差分の項目：テストファイル、コマンド、マーカー、フェーズのフォローアップに関する注記

   docs/operational-packets.xml が存在する場合は、正規の ExecutionPacket、GraphDelta、VerificationDelta のテンプレートに合わせてパケットと差分案を作成します。

提案するウェーブ、選択したプロファイル、パケットの範囲をユーザーに提示します。safe の場合は、各ディスパッチの前に承認を待ちます。balanced と fast の場合は、計画に変更がない限り、最初の承認だけで十分です。

ステップ 2：担当範囲を割り当てる

ディスパッチの前に、担当範囲を明確に定義します：

• コントローラー：
  • docs/development-plan.xml を担当します
  • docs/knowledge-graph.xml を担当します
  • docs/verification-plan.xml を担当します
  • ウェーブパケット、フェーズの完了、共有アーティファクトに触れるコミットを担当します
• ワーカーエージェント：
  • 1 つのモジュール、または明示的に境界が定められた 1 つの範囲を担当します
  • そのモジュールのソースファイルとモジュール固有のテストのみを編集できます
  • 共有の計画アーティファクトを直接変更してはなりません
• レビューエージェント：
  • 契約への準拠、GRACE マークアップ、インポート、グラフ差分の正確性、検証エビデンスを読み取り専用で検証します

ワーカーが、不足しているモジュールや新たな依存関係が必要だと発見した場合、そのワーカーを停止し、先に進む前に計画を改訂するようユーザーに依頼します。気付かれないままアーキテクチャが逸脱することを許してはなりません。

Step 3: 各ウェーブで新しいワーカーエージェントを割り当てる

承認された各ウェーブについて、次の手順を実行します。

1. モジュールごとに新しいワーカーエージェントを1つ割り当てます
2. 各ワーカーには、実行パケットと書き込み範囲内のファイルのみを渡します
3. ワーカーに次の作業を求めます。
   • パケット内のモジュール契約と検証抜粋を使って、コードを生成または更新する
   • MODULE_CONTRACT、MODULE_MAP、CHANGE_SUMMARY、関数契約、セマンティックブロックを保持する
   • 関数シグネチャとドキュメント文字列／コメントの両方の上にSTART_CONTRACT/END_CONTRACTを配置する
   • モジュール内のテストのみを追加または更新する
     • 重要な分岐に必要な安定したログマーカーを保持または追加する
     • モジュール内の検証のみを実行する
     • 維持した前提、実行したコマンド、取得した証拠、リトライ予算を消費したかどうかを含む、簡潔なチェックポイント報告を返す
     • モジュール内の検証が通った後に、次の形式で作業をコミットする

       grace(MODULE_ID): <実施内容を表す命令形のフレーズ>
       
       <File|Function|Export> <name>: <変更内容と理由>
       <File|Function|Export> <name>: <変更内容と理由>
       

       すべてのコミット本文で、変更した具体的なファイル、関数、またはエクスポートを列挙し、それぞれに対して行った作業を説明する必要があります。「Xを堅牢化する」「Yの証拠を追加する」「Zを適用する」などの一般的なフレーズは禁止されています。「loadPivvConfigでENOENTを捕捉し、CONFIG_NOT_FOUNDをスローする」「memory-store.reuseRecordの重複排除キー衝突の回帰テストを追加する」「部分フラッシュに対して書き込みフェーズのトランスクリプトを保護する」など、具体的な説明を優先してください。 各チェックポイントのコミットは、履歴が一連の説明として読めるよう、単一のまとまりのある変更に絞ります。
   • 変更したファイル、検証の証拠、グラフ差分案、検証差分案、コミットハッシュ、統合に関する前提を含む結果パケットを返す

ワーカー向け共有アーティファクトのルール：

• 実装用として、実行パケットにローカルファイルのヘッダーの詳細を含めてもかまいません
• グラフ差分と計画差分には、非公開のヘルパーの変更ではなく、公開モジュール契約／インターフェースの変更のみを含めます

Step 4: 最小限の安全な範囲でレビューする

各ワーカーの作業が完了したら、次の手順を実行します。

1. 変更されたファイルと実行パケットを対象に、範囲を絞った契約レビューを実行します
2. モジュール内のテストと検証の証拠を対象に、範囲を絞った検証レビューを実行します
3. 次の場合に限り、完全な $grace-reviewer 監査にエスカレーションします。
   • モジュール間のずれが疑われる
   • グラフ差分がパケットまたは実際のインポートと矛盾する
   • 検証差分がパケットまたは実際のテスト／ログマーカーと矛盾する
   • 選択したプロファイルに対して検証が不十分である
   • フェーズ境界の監査が必要である
4. 問題が見つかった場合：
   • 同じワーカーに修正を依頼します
   • 修正ループの範囲を限定します。パケットで予算が定義されていない場合、各ワーカーのレビューサイクルは最大2回をデフォルトとします
   • エスカレーションが必要な場合を除き、影響を受けるレビューのみを再実行します
5. 承認済みのモジュール出力のみをコントローラー統合に進めます

Step 5: コントローラー統合とバッチグラフ同期

ウェーブ内のすべてのモジュールが承認されたら、次の手順を実行します。

1. 受け入れ済みのモジュール出力を統合します
2. グラフ差分案をdocs/knowledge-graph.xmlに一度だけ、中央で適用します
3. 検証差分案をdocs/verification-plan.xmlに一度だけ、中央で適用します
4. 各ウェーブにつき一度、docs/development-plan.xmlのステップステータスを更新します
5. 変更されたモジュールと影響を受けた依存関係の範囲に対して、対象を絞って$grace-refreshを実行します
6. 対象を絞ったリフレッシュでより広範なずれが報告された場合は、次のウェーブの前に完全なリフレッシュへエスカレーションします
7. ウェーブで自動チェックが不十分または欠落していることが判明した場合は、実行を停止し、続行する前にユーザー自身で$grace-verificationを実行するよう伝えます
8. ウェーブによってパケットの形式、実行ポリシー、または検証の深さが大きく変わった場合は、次のウェーブを割り当てる前にgrace lint --profile autonomous --path <project-root>を実行します

ステップ 6：段階ごとに検証する

正確性を担保できる範囲で、最小の段階で検証を実行します。

• ワーカーレベル：モジュール内の型チェック、リンター、単体テスト、決定論的なローカルアサーション
• ウェーブレベル：ウェーブで変更したマージ済みの対象範囲のみを統合チェック
• フェーズレベル：全テストスイート、完全な整合性監査、フェーズ完了とする前の最終的なグラフと検証の突き合わせ

リスクプロファイル上必要でない限り、モジュールが正常に完了するたびにリポジトリ全体のテストやグラフスキャンを実行しないでください。

ステップ 7：コントローラーによる共有アーティファクトのコミットと報告

各ウェーブの後、コントローラーは変更された共有アーティファクトのみをコミットします。

• ウェーブの結果を反映して docs/knowledge-graph.xml、docs/verification-plan.xml、docs/development-plan.xml を更新します
• 次の形式でコミットします。

  grace(meta): sync <artifacts updated> after wave N
  
  <module-id>: <what changed in the graph/plan/verification for this module>
  <module-id>: <what changed in the graph/plan/verification for this module>
  

  共有アーティファクトのエントリに実際に変更があったモジュールのみを列挙し、更新内容を説明します（例：「M-CONFIG：step-1 を完了済みにし、グラフに公開エクスポートを追加」）。差分がないモジュールは省略します。

ワーカーによる実装のコミットは、ステップ 3 でモジュールごとにすでに完了しています。コントローラーがコミットするのは共有の計画アーティファクトのみです。

各ウェーブの後、次の内容を報告します。

=== WAVE COMPLETE ===
Wave: N
Profile: safe / balanced / fast
Modules: M-xxx, M-yyy
Approved: count/count
Graph sync: targeted passed / targeted fixed / escalated to full refresh
Verification: module-local passed / wave checks passed / follow-up required
Remaining waves: count

ディスパッチのルール

• 計画に変更がない限り、1 回の実行につき共有 XML アーティファクトを解析するのは 1 回だけにします
• ワーカーに生の XML を繰り返し読み込ませるより、コントローラーが作成した実行パケットを優先します
• 並列化するのは独立したモジュール間に限り、依存関係が不明なものを並列化しないでください
• ワーカーに新しいアーキテクチャを考案させないでください
• 複数のワーカーに同じ共有 XML アーティファクトを並行して編集させないでください
• モジュール間でワーカーセッションを再利用せず、ワーカーは新しくし、パケットは簡潔に保ちます
• すべてのワーカーに、担当ファイルと成功基準を正確に指定します
• 検証に合格したら、ワーカーは実装をコミットする必要があります。コントローラーを待たないでください
• コントローラーがコミットするのは共有アーティファクト（グラフ、計画、検証）のみで、実装ファイルは対象外です
• ウェーブの実行中は、対象を絞った更新と範囲を限定したレビューを優先します
• 完全なレビュアー監査と全体スキャンは、フェーズの区切り、ドリフトの疑い、重大な障害がある場合に限って実施します
• 検証が不十分な場合は速度を落とし、safe に切り替えます。fast が安全であるかのように扱わないでください

使用しない場合

• モジュールが 1 つしか残っていない場合
• ステップ同士の結びつきが強く、同じファイルを共有している場合
• 計画が頻繁に変更されている場合
• チームが信頼できるモジュール内検証をまだ定義していない場合

依存関係のリスクが並列化による利点を上回る場合は、順次実行に $grace-execute を使用してください。