orchestration-envelope

Machine result contract (internal)

対話型スキルは、引き続きテキストを中心にします。ヘッドレスドライバーは境界で簡潔かつ検証済みの結果を取得します。ユーザー向けの各スキルに、同じ JSON セクションを繰り返し追加することはありません。

正規の Turn contract は、これを読み込むエグゼキューターおよびレビュー用スキルのために、引き続きここに置かれます。

実行可能な信頼できる情報源は @gtrabanco/agentic-workflow-schemaです。 型、JSON Schema、renderOutputInstruction(skill)、parseTurn(input)、および compileWorkflowSnapshot(input) が含まれます。このドキュメントではポリシーのみを示します。ここに別のスキーマを複製しないでください。

出力プロファイル

WORKFLOW_SKILL_PROFILES が正式な一覧です。

• workflow-status は常に、厳格な Envelope v2 センサー結果を返します。 そのエンベロープには、detail の下に詳細なプロジェクトビューが含まれます。
• その他のドライバー呼び出し対象スキルは、ドライバーがその呼び出しに renderOutputInstruction(skill) を追加した場合にのみ、SkillOutcome v1 を返します。これには、モデルが所有する少数のフィールド、すなわち outcome、次の intent／targets、blockers、questions、discoveries、および evidence references が含まれます。
• advance（付属の pi パッケージコマンド）はワーカープロファイルではなくコンダクターです。センサーエンベロープに対して決定論的なコードとして実行され、ワーカーの SkillOutcome は出力しません。
• 対話型の呼び出しでは通常の人間向けレポートが出力されます。ドライバー結果は不要です。

どちらの結果も、最後のフェンス付き json ブロックとして出力されます。パッケージはルーティング境界で未知のキーを拒否します。リポジトリの事実をモデルの文章から再構成することはありません。ドライバーは、選択したバージョン管理対象ドキュメントと呼び出し元から渡されたリポジトリの事実を使って、WorkflowSnapshot v1 をコンパイルします。

ドライバープロトコル

1. プロファイルを読み取り、ドライバーによる呼び出しの場合にのみ renderOutputInstruction(skill) を追加します。
2. 最終応答を parseTurn({skill, text, context}) に渡します。返された source と diagnostics は、実行ジャーナルとともに保持します。
3. 機械可読な結果がない、形式が不正、または無効な場合は、同じセッションを一度だけ次の内容で再呼び出しします。Emit only the machine result for the turn above.
4. 修正後の応答を解析します。2回目も失敗した場合は、ドライバーレベルの FAILED とします。無期限に再試行したり、任意の文章をワークフローの事実に変換したりしてはいけません。

互換性の範囲は意図的に限定されています。欠落した値を機械的に特定できる場合に限り、ドキュメント化されたレガシー v2 形式を修正できます。問題の識別情報がないゼロ以外の issue count、対応するものがない数値の unit id、無関係な文章は無効のままであり、ドライバーに通知されます。

コントラクトの進化

• Envelope v2 は新しいドライバーに対して厳格です。detail は必須で（通常は null）、スキル固有の拡張はその中に格納します。たとえば design_candidates は detail.design_candidates に置き、ルートキーにはしません。
• workflow-status は既存のセンサー利用者向けに Envelope v2 を維持します。 parseEnvelope() はレガシー互換のパッケージ API として引き続き提供されます。新しい利用者は parseEnvelopeV2Strict() または parseTurn() を使用します。
• SkillOutcome v1 と WorkflowSnapshot v1 は、別々にバージョン管理された JSON Schema です。公開済みコントラクトへの破壊的変更は、パッケージのメジャーバージョンアップとなります。

正規化されたリポジトリ状態

ドライバーは計画の前に discover-repository-state を呼び出し、固定された docs/workflow/REPOSITORY_STATE.md の参照を保持します。WorkflowSnapshot v1 は不明な点、出所、および明示された矛盾をそのまま保持します。矛盾は黙って置き換えるのではなく、ドライバーが resolve-repository-state にルーティングします。