zcl

ZCL Orchestrator（Codex Skill）

このスキルは、起動されたミッションエージェントではなく、オーケストレーター（あなた）向けです。

ネイティブランタイムの境界（現在）

• ZCL では、zcl suite run および runner.type=codex_app_server を使用するキャンペーンフローで、ネイティブランタイムによる実行が第一級機能としてサポートされています。
• ランタイムの選択は戦略ベースで決定論的に行われ、順序付きフォールバックチェーン（--runtime-strategies、ZCL_RUNTIME_STRATEGIES）を使用します。
• プロセスランナーモードも明示的なフォールバック（--session-isolation process）として引き続きサポートされています。
• ネイティブランタイム戦略のヘルス状態と失敗クラスは型付けされ、アーティファクト／JSON 出力に表示されます。

機能マトリックス

機能	実装済み	適用済み	備考
ネイティブスイート実行（--session-isolation native）	はい	はい	ネイティブモードでは、suite run によりプロセスランナーコマンドの使用が禁止されます。
ランタイム戦略のフォールバックチェーン	はい	はい	順序付きの戦略 ID、機能チェック、戦略ごとの型付き失敗。
ネイティブキャンペーンランナー（runner.type=codex_app_server）	はい	はい	フローごとの runner.command は不要です。
ネイティブイベントトレースのマッピング（tool=native）	はい	はい	リダクション＋上限＋整合性フラグが維持されます。
ミッション専用の結果チャネル最終処理	はい	はい	minResultTurn による 3 ターンのワークフロー。
プロバイダーのオンボーディング構造	はい	一部	provider_stub は、未対応の機能の動作を示します。
ランタイム失敗の分類（認証／レート制限／ストリーム／クラッシュ／リスナー／停止）	はい	はい	サマリーとフィードバックの失敗ペイロードに、型付きの ZCL_E_RUNTIME_* コードが含まれます。

主なエビデンス：

• .zcl/.../tool.calls.jsonl
• .zcl/.../feedback.json

オペレーターによる実行方法

「これを ZCL 経由で実行して」と依頼された場合は、次の順序で実行します。

1. zcl init
2. 任意の事前チェック：
   • zcl update status --json
   • zcl doctor --json
3. 任意の単一試行の割り当てパス：
   • zcl attempt start --suite <suiteId> --mission <missionId> --prompt <text> --isolation-model native_spawn --json
4. 推奨されるネイティブスイートパス：
   • zcl suite run --file <suite.(yaml|yml|json)> --session-isolation native --runtime-strategies codex_app_server --feedback-policy auto_fail --finalization-mode auto_from_result_json --result-channel file_json --result-min-turn 3 --campaign-id <campaignId> --progress-jsonl <path|-> --json
5. プロセスフォールバックパス：
   • zcl suite run --file <suite.(yaml|yml|json)> --session-isolation process --feedback-policy auto_fail --finalization-mode auto_from_result_json --result-channel file_json --result-min-turn 3 --campaign-id <campaignId> --progress-jsonl <path|-> --shim tool-cli --json -- <runner-cmd> [args...]
6. 第一級のキャンペーンパス：
   • zcl campaign lint --spec <campaign.(yaml|yml|json)> --json
   • zcl campaign canary --spec <campaign.(yaml|yml|json)> --missions 3 --json
   • zcl campaign run --spec <campaign.(yaml|yml|json)> --json
   • zcl campaign resume --campaign-id <id> --json
   • zcl campaign status --campaign-id <id> --json
   • zcl campaign report --campaign-id <id> --allow-invalid --json
   • zcl campaign publish-check --campaign-id <id> --json
7. アーティファクトから検証／レポートを実行：
   • zcl report --strict <attemptDir|runDir>
   • zcl validate --strict <attemptDir|runDir>
   • zcl attempt explain --json <attemptDir>

ハーネスを考慮したプロンプト向けの明示的な最終処理パス：

• zcl feedback --ok --result <text> または zcl feedback --fail --result-json <json>

オペレーター向けガードレール

• ネイティブスイートでは、ネイティブターンの実行前にタイムアウト時間の計測を開始するようになりました。停止したネイティブ試行は ZCL_E_RUNTIME_STALL として分類されます。
• ネイティブスイートのオーケストレーションでは、失敗時にも事後分析の継続に必要な最終成果物（feedback.json と、ベストエフォートで生成する attempt.report.json）が必ず作成されるようになりました。
• 保存済みの campaign.run.state.json が、現在の仕様に基づくミッション選択と一致しない場合（たとえば、選択結果が空でないのに totalMissions=0 の場合）、キャンペーンの読み取り／レポート／再開コマンドは ZCL_E_CAMPAIGN_STATE_DRIFT を返して即時終了します。
• CI／自動化では、プロセスの終了コードによる分岐なしにレポートのペイロードを収集するため、zcl campaign report --allow-invalid --json を推奨します。厳格な公開ゲートとしては zcl campaign publish-check を使用してください。

キャンペーンのガイダンス

推奨するネイティブ Codex フロー：

flows:
  - flowId: codex-native
    runner:
      type: codex_app_server
      sessionIsolation: native
      runtimeStrategies: ["codex_app_server"]
      feedbackPolicy: auto_fail
      freshAgentPerAttempt: true

ミッションのみを使用する推奨バリエーション：

promptMode: mission_only
flows:
  - flowId: codex-native
    runner:
      type: codex_app_server
      sessionIsolation: native
      runtimeStrategies: ["codex_app_server"]
      finalization:
        mode: auto_from_result_json
        minResultTurn: 3
        resultChannel:
          kind: file_json
          path: mission.result.json

プロンプトポリシー

キャンペーンごとに、次のモードを1つだけ使用してください。

• promptMode: mission_only（推奨）：ミッションの意図と出力契約のみを含めます。ハーネスに関する用語は含めません。
• promptMode: default：ハーネスを考慮したプロンプトを使用できます。

ネイティブを推奨する基準（測定済み）

CI／夜間チェックで次の両方を満たす場合、Codex ネイティブランタイムを推奨します。

1. 信頼性：ネイティブによる20試行の並列スモークテストの成功率が95％以上。
2. スループット：同じ実行がCIワーカーベースラインで30秒以内に完了すること。

ガードテストのパス：

• internal/interfaces/cli/suite_run_integration_test.go（TestSuiteRun_NativeParallelUniqueSessions、TestSuiteRun_NativeSchedulerRateLimitIsDeterministic）。

テンプレート

• examples/campaign.canonical.yaml
• examples/campaign.no-context.comparison.yaml
• examples/campaign.no-context.codex-exec.yaml
• examples/campaign.no-context.codex-subagent.yaml
• examples/campaign.no-context.claude-subagent.yaml
• examples/campaign.native.codex.minimal.yaml
• examples/campaign.native.codex.advanced.yaml
• docs/migration/shell-adapter-to-native-codex.md