tools-only 📘 Maestro Orchestrator — オーケストレーション・フレームワーク（fail-closed + HITL）
English version: README.md
概要（Overview）
Maestro Orchestrator は 研究／教育用途のオーケストレーション・フレームワークです。優先する設計原則は以下です。
- Fail-closed（閉じて安全）
不確実・不安定・リスクあり → 何も言わずに継続しない - HITL（Human-in-the-Loop）
人間の判断が必要な意思決定は明示的にエスカレーションする - トレーサビリティ（追跡可能性）
最小ARLログにより、意思決定フローを監査可能・再現可能にする
本リポジトリには 実装リファレンス（doc orchestrator） と、交渉／仲裁／ガバナンス風ワークフロー／ゲーティング挙動を検証する シミュレーションベンチ が含まれます。
Quickstart（推奨の最短導線）
まずは “1本動かしてログを確認” してから拡張してください。
1) 最新の緊急契約シミュレーター（v4.8）を実行
python mediation_emergency_contract_sim_v4_8.py
2) ピン留めされた smoke テスト（v4.8）を実行
pytest -q tests/test_mediation_emergency_contract_sim_v4_8_smoke_metrics.py
3) 任意：evidence bundle（生成物）を確認
docs/artifacts/v4_8_artifacts_bundle.zip
注：zip（evidence bundle）は テスト／実行によって生成される成果物です。 正（canonical）は “生成スクリプト＋テスト” 側であり、zipはレビュー用証拠束として扱ってください。
アーキテクチャ（高レベル）
監査可能で fail-closed な制御フロー：
agents → mediator（risk / pattern / fact） → evidence verification → HITL（pause / reset / ban） → audit logs（ARL）
画像が表示されない場合：
docs/architecture_unknown_progress.pngが同一ブランチに存在すること、ファイル名の大文字小文字が一致していること（case-sensitive）を確認してください。
アーキテクチャ（コード整合の図）
以下の図は 現在のコード用語に整合しています。 監査性と曖昧さ排除のため、状態遷移（State transitions） と ゲート順序（Gate order） を分離しています。
ドキュメントのみ。ロジック変更はありません。
1) 状態機械（State Machine / code-aligned）
どこで PAUSE（HITL） するか、どこで STOP（SEALED） するかを最小の遷移で表します。
主経路（Primary execution path）
INIT → PAUSE_FOR_HITL_AUTH → AUTH_VERIFIED → DRAFT_READY → PAUSE_FOR_HITL_FINALIZE → CONTRACT_EFFECTIVE
補足
PAUSE_FOR_HITL_*は明示的な Human-in-the-Loop 判断点（ユーザー承認／管理者確定）です。STOPPED（SEALED）は以下で到達します：- evidence が無効／捏造
- 認可（authorization）期限切れ
- draft lint 失敗
SEALED は fail-closed であり、設計上 non-overrideable（上書き不可）です。
2) ゲートパイプライン（Gate Pipeline / code-aligned）
評価ゲートの 順序 を示します（状態遷移とは独立）。
補足
- この図は ゲート順序 を表します（状態遷移ではありません）。
PAUSEは HITL必須（人間判断待ち）を意味します。STOPPED（SEALED）は 回復不能の安全停止 を意味します。
設計意図
- State Machine が答えること： 「どこで止まる／止める（PAUSE/STOP）か」
- Gate Pipeline が答えること： 「意思決定をどの順で評価するか」
分離することで曖昧さを避け、監査可能性を維持します。
メンテナンス注記
画像が表示されない場合：
docs/配下に存在するか- ファイル名が完全一致しているか（case-sensitive）
- リンク更新時はファイル一覧からコピペ推奨
What’s new（更新情報）
このREADMEは Quickstart と設計の要点を最短で伝えるために最小構成に保っています。 詳細な更新履歴（何が追加・変更・修正されたか）は、以下を一次情報として参照してください。
- Commit history（最も正確な差分の履歴） https://github.com/japan1988/multi-agent-mediation/commits/main
- Releases（節目ごとの要約・配布） https://github.com/japan1988/multi-agent-mediation/releases
方針：トップレベルREADMEのタイムラインは肥大化させず、履歴は commits / releases に集約します。
V1 → V4：何が本質的に変わったか
mediation_emergency_contract_sim_v1.py は最小構成：線形イベント駆動のワークフロー＋fail-closed＋最小ARL。
mediation_emergency_contract_sim_v4.py はそれを “ガバナンス検証ベンチ” にするため、早期拒否と制御された自動化を追加。
v4で追加された要素
- Evidence gate evidence bundle の基本検証。無効／無関連／捏造は fail-closed で停止。
- Draft lint gate “ドラフトの範囲” と “スコープ境界” を管理者確定前に強制。
- Trust system（score + streak + cooldown） HITL結果に応じて trust を更新し、失敗後の危険な自動化を cooldown で抑制。遷移はARLへ。
- AUTH HITL auto-skip（安全な摩擦低減） trust閾値＋承認streak＋有効grant が揃う場合、同一条件でのAUTH HITLをスキップ可能（理由はARLへ記録）。
実行例（Execution examples）
Doc orchestrator（実装リファレンス）
python ai_doc_orchestrator_kage3_v1_2_4.py
Emergency contract（v4.8）
python mediation_emergency_contract_sim_v4_8.py
Emergency contract（v4.1）
python mediation_emergency_contract_sim_v4_1.py
Emergency contract stress（v4.4）
python mediation_emergency_contract_sim_v4_4_stress.py --runs 10000 --out stress_results_v4_4_10000.json
プロジェクトの意図／非目標（Intent / Non-goals）
Intent
- 再現可能な安全／ガバナンスシミュレーション
- 明示的な HITL セマンティクス（pause/reset/ban）
- 監査可能な意思決定トレース（最小ARL）
Non-goals
- そのまま本番運用できる自律デプロイ
- 無制限な自己目的化エージェント制御
- 明示テスト範囲を超えた安全性主張
データ／安全メモ（Data & safety notes）
- 合成／ダミーデータのみを使用してください。
- 実行ログはコミットしないことを推奨（必要なら再現可能な最小証拠に限定）。
- 生成されたzip（bundle）は レビュー用証拠束であり、canonical source ではありません。
License
Apache License 2.0（LICENSE を参照）