mesh

mesh

意図

$mesh は、繰り返し発生する末端作業の形が整った後に、Codex で高ファンアウトのバッチ実行を行うための手段です。

計画や分解ではなく、すでに形が整った末端作業に使用します。

次の場合に使用します。

• ユーザーが明示的に $mesh を要求した場合、または繰り返し発生する末端作業がすでに明確に行単位に整理されている場合
• ワークロードが行単位に整理され、均質である場合
• 各行を独立して処理できる場合
• 各行が、固有のスコープと受け入れ基準を持つ実質的な作業単位を表す場合
• 行ごとの結果を構造化して CSV にエクスポートしたい場合
• 計画が完了しており、残っている作業が末端の実行だけである場合

次の場合は使用しないでください。

• 作業が調査、レビュー、議論、設計である場合
• タスクの分解や共有の判断がまだ必要な場合
• タスク間でコンテキストを共有している、または相互に依存している場合
• 複数のワーカーが同じ変更可能なスコープに触れる場合
• 直接の spawn_agent への委任またはローカルでの実行のほうが明確な場合

ネイティブアーキテクチャとの適合性

• $mesh は、別個のランタイムプロトコルではなく、spawn_agents_on_csv に対応します。
• バッチジョブは、CSV の行ごとにワーカーのサブエージェントを 1 つ起動します。
• メインの呼び出しは、バッチが完了するまでブロックします。
• 各ワーカーは、report_agent_job_result を必ず 1 回だけ呼び出す必要があります。
• 結果は、output_csv_path またはデフォルトの出力 CSV にエクスポートされます。
• 計画はバッチの開始前に行い、$mesh はすでに形が整った行を実行します。

推奨される用途

• 行ごとに 1 ファイルを監査する
• 行ごとに 1 件のチケット、ログのチャンク、またはドキュメントを分類する
• 多数の入力から構造化フィールドを抽出する
• 出力が互いに重複しないファイル一覧に対して、同じ範囲の限定された変換を実行する
• $select または $teams によってすでに作業のまとまりが整えられた後、行ごとに 1 つの独立した実装単位を実行する

作業が不均質な場合は、代わりに $teams または直接の spawn_agent を使用してください。

複合タスクと末端タスクの適合性

各行がすでに末端タスクになっている場合に限り、$mesh を使用してください。

• CSV 列から入力が明確に定まっている
• すべての行に対して 1 つの指示テンプレートを使用する
• 行間の調整が不要である
• 行ごとに構造化された結果が 1 つある

行のスキーマを決める、アプローチに異議を唱える、または戦略を比較する必要がある場合は、$mesh を使う前に、通常は $teams またはローカルでその作業を行ってください。

実質的な作業単位に関するルール

• 1 行は、固有の書き込みまたは読み取りスコープと 1 つの受け入れ基準を持つ、固有の作業単位を表す必要があります。
• レーン数、証拠数、または並列実行数を増やすためだけに、同じスコープで行を増やさないでください。
• その作業単位の証拠として、問題なく完了したプライマリ行を十分なものとして扱ってください。
• セカンダリのレビュー、コーダー、修正担当、証明担当、または統合担当の行を追加するのは、先行する行で具体的なブロッカー、証明の失敗、または再度の対応が必要な重要な差分が報告された場合に限ってください。
• 非推奨のシム（reducer、mentor、locksmith、applier）を、新規の行として使用してはいけません。

推奨フロー

1. 計画が完了しており、行が本当に均質かつ独立していることを確認します。
2. 安定したヘッダーを持つ CSV を作成し、必要に応じて安定した id_column を指定します。実質的な作業単位ごとに 1 行にします。
   • バッチの元になったものが OrchPlan または $st のクレームセットである場合は、安定した行 ID として task_id を優先してください。
3. {column} プレースホルダーを使用し、行ごとにプライマリ成果物を 1 つ指定した指示テンプレートを作成します。
4. 必要な制御項目だけを選択します。output_schema、output_csv_path、max_concurrency、max_runtime_seconds を使用し、より低い上限が必要な場合を除き、max_concurrency は安全に実行できる行数に設定します。
5. spawn_agents_on_csv を実行します。
6. 具体的なブロッカー、証明の失敗、または再度の対応が必要な重要な差分を報告した作業単位に限り、セカンダリ行を追加します。
7. エクスポートされた CSV を確認し、統合作業やフォローアップ作業をローカルまたは $teams で行います。
   • $st が実行状態を管理している場合は、波を終了する前に st import-mesh-results --input <output.csv> でエクスポート結果を反映します。

具体例

例 1：1 行につき 1 ファイルを監査する

目的：

すべての Markdown ファイルで必須のフロントマターキーを確認し、ファイルごとに 1 行の結果をエクスポートします。

CSV の例：

id,path
1,docs/intro.md
2,docs/setup.md

指示テンプレートの例：

Inspect {path}. Report whether the required frontmatter keys exist and list any missing keys.

$mesh を使う理由：

• すべての行で同じテンプレートを使います
• 各行は独立しています
• ファイルごとに 1 つの構造化オブジェクトとして結果を取得できます

例 2：サポートチケットを分類する

目的：

2,000 件のサポートチケットを製品領域と緊急度で分類し、ラベルを CSV にエクスポートします。

CSV の例：

ticket_id,text
T-1001,"Billing page shows a 500 error"
T-1002,"How do I rotate an API key?"

出力スキーマの例：

{
  "type": "object",
  "properties": {
    "area": { "type": "string" },
    "urgency": { "type": "string" },
    "needs_human": { "type": "boolean" }
  },
  "required": ["area", "urgency", "needs_human"]
}

$mesh を使う理由：

• これは繰り返し実行する読み取り専用の分類作業です
• スキーマにより、行ごとの出力を簡単に比較し、後処理できます

例 3：重複しないファイル変換

目的：

生成済みの大量の要約を書き換え、入力ファイルごとに 1 つの出力ファイルを作成します。出力先は重複しません。

適切な $mesh の設定：

• id,input_path,output_path などの CSV 列
• {input_path} を読み取り、{output_path} のみを書き込む 1 つの指示テンプレート
• 行の処理が成功したかどうかを確認する 1 つの JSON 結果

$mesh を使う理由：

• 書き込み範囲が重複しません
• 範囲が限定された同じ変換を、すべての行で繰り返します

例 4：重複しない実装単位

目的：

各タスクがすでに重複しない範囲を持つ OrchPlan から、安全に実行できる最初の実装フェーズを実行します。

適切な $mesh の設定：

• id,objective,write_scope,proof_command などの CSV 列
• レビュアーのレーンごとではなく、実装単位ごとに 1 つのプライマリ行を設定します
• max_concurrency を、安全に並行実行できる重複しない単位の数に設定します
• 証明に失敗した、またはブロッカーが報告された単位に限り、後続の証明担当または修正担当の行を追加します

$mesh を使う理由：

• 計画が完了した後の、繰り返し実行する末端の処理です
• 各行は固有の範囲を担当し、具体的な受け入れ目標を持ちます
• 架空の証拠レーンを作らずに、バッチを実際に並列化できます

反例：共有コードにまたがる 1 つの機能

次の作業に $mesh を使わないでください。

共有パーサーロジック、サーバーの動作、UI を変更する機能を追加します。

使わない理由：

• 依然として分解と調整が必要です
• 各行は独立していません
• 変更可能な共有ファイルがあるため、$teams またはローカル実行のほうが安全です

行の設計ルール

• 各行の目的を具体的かつ限定的にします。
• 各行を、固有の範囲と受け入れ目標を持つ、実質的な作業単位にします。
• write_scope を、codex/skills/select/references/lock-roots.md に記載されている正規のロックルート契約に合わせます。
• 読み取り専用の作業、または重複しない書き込み範囲を優先します。
• 結果オブジェクトを構造化し、行をまたいで比較できるようにします。
• 後で出力を照合する場合は、安定した行 ID を使います。
• ブロッカーまたは証明の失敗によって後続作業が正当化されない限り、同じ範囲に対して役割やレーンごとに行を増やさないでください。
• 削減の考え方が必要な場合は、approach=reduce を設定して coder 内で対応し、新しい行タイプとして reducer を復活させないでください。
• 行で変更可能な共有状態を使う必要がある場合は、そこで停止し、$mesh 以外の方法に切り替えてください。
• 行で計画が必要な場合は、そこで停止し、バッチ実行の前に分解を完了してください。

結果の契約

• すべてのワーカーは report_agent_job_result を介して、JSON の結果を正確に 1 つ報告する必要があります。
• 報告がない場合は失敗です。
• 説明文には権威がありません。重要なのは構造化された結果です。
• output_schema を指定する場合は、必要なフィールドに合わせて最小限にします。

references/output-contract.md を参照してください。

アンチパターン

• $teams の一般的な代替として $mesh を使う
• バッチワーカー内で再帰的な計画や議論を行う
• 密接に結び付いた実装を、依存関係のある複数の行に分割する
• 行間で書き込み範囲を重複させる
• 実質的な作業がすでに完了した後で、形式だけのエビデンス収集ウェーブを開始する
• ブロッカーを受けていないのに、同じ範囲にコーダー／修正担当／検証担当／統合担当の行を増やす
• 稼働中のコアロールではなく、非推奨のシムを通じて新しい作業を振り分ける
• 構造化された結果フィールドではなく、自由形式のテキストに頼る
• csv_path と output_csv_path に同じパスを使う

references/orchestration-anti-patterns.md を参照してください。

最終回答

メッシュが実際に実行された場合は、文章で簡潔な Orchestration Ledger を含めてください。

適切なフィールド：

• Skills used
• Subagents
• Artifacts produced
• Cleanup status

オーケストレーションが実行されなかった場合、このセクションは省略してください。

$teams からの引き継ぎ

$teams から $mesh に作業を引き継ぐ場合、引き継ぎには以下を含めてください。

• 計画が完了しており、残るのはリーフの実行のみであることの確認
• CSV または行スキーマ
• 指示テンプレート
• 想定される出力フィールド
• 並行処理やタイムアウトに関する前提

ランタイムが実際に提供していないレーン、クォーラム、ステートマシンのプロトコルを追加しないでください。