tools-only 📘 Maestro Orchestrator — オーケストレーション・フレームワーク（fail-closed + HITL）
English: README.md
Overview（概要）
Maestro Orchestrator は 研究 / 教育用途 のオーケストレーション・フレームワークです。重視するのは次の3点です：
- Fail-closed（フェイルクローズ）
不確実・不安定・危険があるなら → 黙って続行しない。 - HITL（Human-in-the-Loop）
人間の判断が必要な箇所は明示的にエスカレーションする。 - Traceability（追跡可能性）
意思決定フローは最小ARLログで監査可能・再現可能にする。
このリポジトリには 実装リファレンス（doc orchestrators） と、 交渉・仲裁・ガバナンス風ワークフロー・ゲーティング挙動を検証する シミュレーションベンチ が含まれます。
Architecture（高レベル）
監査可能で fail-closed な制御フロー：
agents
→ mediator（risk / pattern / fact）
→ evidence verification
→ HITL（pause / reset / ban）
→ audit logs（ARL）
画像が表示されない場合は、
docs/architecture_unknown_progress.pngが同一ブランチに存在するか、ファイル名の大文字小文字が一致しているか（case-sensitive）を確認してください。
Architecture（コード整合図）
以下の図は 現行コードと用語に完全整合 しています。
監査性と曖昧性排除のため、状態遷移 と ゲート順序 を意図的に分離しています。
この図は ドキュメントのみ であり、ロジック変更は一切ありません。
1) State Machine（コード整合）
実行が HITLで停止（PAUSE） する箇所、
または SEALEDで恒久停止（STOPPED） する箇所を最小状態遷移として示します。
Notes
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 であり、設計上 override 不可です。
2) Gate Pipeline（コード整合）
状態遷移とは独立に、評価ゲートの 順序 を表します。
Notes
- この図は ゲート順序 を示すもので、状態遷移ではありません。
PAUSEは HITLが必要（人間の判断待ち）を意味します。STOPPED (SEALED)は 非回復の安全停止 を意味します。
Design intent
- State Machine は「どこで停止/中断するか？」に答える
- Gate Pipeline は「どの順で判断するか？」に答える
分離することで曖昧性が減り、監査可能性が保たれます。
Maintenance note
画像が表示されない場合：
docs/配下に存在するか確認- ファイル名の大文字小文字を含めて一致しているか確認（case-sensitive）
- リンク更新時はファイル一覧からコピペ推奨
What’s new（2026-01-21）
- New:
ai_mediation_hitl_reset_full_with_unknown_progress.py
unknown progress シナリオ（HITL/RESET）用シミュレータ - New:
ai_mediation_hitl_reset_full_kage_arl公開用_rfl_relcodes_branches.py
v1.7-IEP 整合：RFL relcode 分岐（RFLは非封印→HITLへ） - Updated:
ai_doc_orchestrator_kage3_v1_2_4.py
post-HITL の意味論を反映して更新
What’s new（2026-02-03）
イベント駆動のガバナンス風ワークフロー を導入（fail-closed + HITL + audit-ready）
New:
mediation_emergency_contract_sim_v1.py
最小の緊急ワークフロー：USER auth → AI draft → ADMIN finalize → contract effective
不正 / 期限切れイベントは fail-closed で停止し、最小ARL（JSONL）を出力。
New:
mediation_emergency_contract_sim_v4.py
v1を拡張：- evidence gate
- draft lint gate
- trust / grant による HITL 摩擦低減
What’s new（2026-02-05）
New:
mediation_emergency_contract_sim_v4_1.py
v4.1 は v4.0 の 挙動を契約として固定 する tightening 版（期待値を明示しコード整合）RFLは非封印
境界不安定はPAUSE_FOR_HITL（sealed=false/overrideable=true）で人間判断へ。Fabricationは早期検知、封印は ethics のみ
捏造は evidence でフラグされるが、封印停止 はethics_gateのみが発行（sealed=true）。trust/grant の摩擦低減は維持
条件成立時のAUTH auto-skip を維持しつつ、ARLに理由を記録。
Quick run
python mediation_emergency_contract_sim_v4_1.py
Expected
NORMAL -> CONTRACT_EFFECTIVE
FABRICATE -> STOPPED（sealed=true in ethics_gate）
RFL_STOP -> STOPPED（sealed=false via HITL stop）
v4.1 regression test v4.1の挙動を契約として固定するpytest：
NORMAL -> CONTRACT_EFFECTIVE（not sealed）
FABRICATE -> STOPPED（sealed=true in ethics_gate）
RFL_STOP -> STOPPED（sealed=false via HITL stop）
Invariant：SEALEDは ethics_gate/acc_gate のみ（RFLは封印しない）
単体実行：
bash
pytest -q tests/test_mediation_emergency_contract_sim_v4_1.py What’s new（2026-02-07） New: mediation_emergency_contract_sim_v4_4.py 緊急契約ワークフローベンチ v4.4（fail-closed + HITL + minimal ARL）
New: mediation_emergency_contract_sim_v4_4_stress.py v4.4 ストレス実行（分布 + invariant 検証）
New: stress_results_v4_4_1000.json ストレス結果（1,000回）
New: stress_results_v4_4_10000.json ストレス結果（10,000回）
Stress-pinned invariants
SEALED は ethics_gate / acc_gate のみ（RFLは封印しない）
RFLは非封印（RFL→PAUSE_FOR_HITL、人間が決める）
What’s new（2026-02-08） New: mediation_emergency_contract_sim_v4_6.py 緊急契約ワークフローベンチ v4.6（fail-closed + HITL + minimal ARL）
New: stress_results_v4_6_100000.json v4.6 の再現可能ストレス証跡（100,000回）
New: mediation_emergency_contract_sim_v4_7_full.py v4.7 は、低信頼状態での「最短ルート（shortest-path）リトライ」を減らし、 clean completion を上げるために 最上位（最高スコア）エージェントによる指導（coaching） を導入。
Why v4.7（v4.6で見つかった点）
v4.6 のストレスで、低信頼スコア状態のエージェントが最短ルートを狙ってリトライし、 その結果 2件 STOPPED となる挙動が観測されました。 v4.7 は指導（coaching）により、リトライ前に状態改善が見込まれ、この失敗モード低減を狙います。
v4.6 STOPPED（2件）：reason_code=TRUST_SCORE_LOW @ model_trust_gate（fail-closed）
ガードレール（設計段階での事故予防）
ガードレールは設計段階から入っていたため、不安全条件は 早期にfail-closedで停止し、 黙って続行して事故化することを未然に防げました。
v4.6 stress snapshot（100,000回） CONTRACT_EFFECTIVE：73,307
STOPPED：18,385
INIT：8,308
v4.7 のストレス結果は後日公開（同フォーマット）
V1 → V4：実際に何が変わったか mediation_emergency_contract_sim_v1.py は 最小パイプライン： 線形のイベント駆動ワークフロー + fail-closed 停止 + 最小監査ログ。
mediation_emergency_contract_sim_v4.py はそれを 繰り返し可能なガバナンス・ベンチ にする（早期reject + 制御された自動化）ための拡張。
v4で追加 Evidence gate evidence bundle の基本検証。不正・無関係・捏造は fail-closed。
Draft lint gate draft-only とスコープ境界を強制。ノイズ耐性を上げ誤検知を抑える。
Trust system（score + streak + cooldown） 成功で上がり、失敗で下がる。cooldown で危険な自動化を抑制。遷移はARLに記録。
AUTH HITL auto-skip（安全な摩擦低減） trust閾値 + 承認streak + grant が成立した場合のみ、同一条件のAUTH HITLをスキップし、理由をARLへ。
要するに
V1：「最小監査ログでfail-closedを成立させられるか？」
V4：「監査性を落とさずスケールして反復運用できるか？」
⚙️ Execution Examples（実行例） まずは 1本だけ 動かして挙動とログを確認し、次に広げてください。
NOTE：本リポジトリは 研究 / 教育用途 です。 ダミーデータ を使い、実行時ログはコミットしないでください。
Recommended Doc orchestrator（リファレンス） bash
python ai_doc_orchestrator_kage3_v1_2_4.py Emergency contract workflow（v4） bash
python mediation_emergency_contract_sim_v4.py Emergency contract workflow（v4.1） bash
python mediation_emergency_contract_sim_v4_1.py Emergency contract workflow（v4.4） bash
python mediation_emergency_contract_sim_v4_4.py Emergency contract stress（v4.4） bash
python mediation_emergency_contract_sim_v4_4_stress.py --runs 10000 --out stress_results_v4_4_10000.json Emergency contract workflow（v4.6） bash
python mediation_emergency_contract_sim_v4_6.py Emergency contract workflow（v4.7） bash
python mediation_emergency_contract_sim_v4_7_full.py Project intent / non-goals（意図 / 非目標） Intent（意図） 再現可能な安全・ガバナンスシミュレーション
明示的なHITL意味論
監査可能な意思決定トレース
Non-goals（非目標） 本番環境での自律運用
無制限な自己指向エージェント制御
テストで明示された範囲を超える安全性主張
License（ライセンス） Apache-2.0. 詳細は LICENSE を参照。