tools-only 📘 Maestro Orchestrator — オーケストレーション・フレームワーク（fail-closed + HITL）
English version: README.md
目的（研究・教育）
これは研究/教育目的の参照実装（プロトタイプ）です。有害行為の実行・助長（例：悪用、侵入、監視、なりすまし、破壊、データ窃取 等）や、 利用環境/サービスの 利用規約・ポリシー、法令、社内ルール に反する用途に使わないでください。
本プロジェクトは 教育/研究および防御的な検証（例：ログ肥大の抑制、fail-closed + HITL 動作の検証）を主目的としており、 攻撃手口の公開や不正行為の促進を意図しません。
利用は自己責任です。必ず関連する 利用規約/ポリシー を確認し、まずは 隔離環境でのローカル検証（外部ネットワークなし、実データ/実システムなし）から始めてください。
本コード・文書・生成物（例：zip バンドル）は 現状有姿（AS IS）・無保証で提供され、適用法で許される最大限の範囲で、 作者は利用に起因する一切の損害について 責任を負いません（第三者による悪用を含む）。
同梱の コードブックはデモ/参照用の成果物です。そのまま実運用に使わず、要件・脅威モデル・規約/ポリシーに基づき自作してください。
テスト/結果の免責: スモークテストやストレス実行は、特定条件下で実行されたシナリオの範囲でのみ検証します。実運用での正しさ・安全性・セキュリティ・適合性を保証しません。
概要
Maestro Orchestrator は 研究 / 教育 向けのオーケストレーション・フレームワークで、以下を優先します。
Fail-closed（失敗時は安全側）
不確実・不安定・リスクがある場合は、黙って先に進まず停止/保留する。HITL（Human-in-the-Loop）
人間の判断が必要な局面は明示的にエスカレーションする。トレーサビリティ
意思決定フローを最小ARLログで監査可能・再現可能にする。
このリポジトリには、参照実装（ドキュメント・オーケストレーター等）と、 交渉/調停/ガバナンス風ワークフローにおけるゲート動作を検証する シミュレーションベンチが含まれます。
クイックスタート（推奨ルート）
v5.1.x は再現性 + 契約チェックのための推奨系。v4.x はレガシーの安定ベンチとして維持。
まずは 1 本のスクリプトで挙動とログを確認し、徐々に拡張してください。
1) 推奨：緊急コントラクト・シミュレータ（v5.1.2）
python mediation_emergency_contract_sim_v5_1_2.py --runs 100
2) 契約テスト（v5.1.x：シミュレータ + コードブック整合）
pytest -q tests/test_v5_1_codebook_consistency.py
3) デモコードブックの確認 / ピン留め（v5.1-demo.1）
log_codebook_v5_1_demo_1.json（デモ用コードブック。成果物交換時は バージョンを固定）
注意：コードブックはログ項目の圧縮（エンコード/デコード）目的であり、暗号ではありません（秘匿性はありません）。
4) 任意：レガシー安定ベンチ（v4.8）
python mediation_emergency_contract_sim_v4_8.py
pytest -q tests/test_mediation_emergency_contract_sim_v4_8_smoke_metrics.py
5) 任意：証拠バンドル（v4.8 生成物）
docs/artifacts/v4_8_artifacts_bundle.zip
zip は実行/テストにより生成される成果物です。
正のソースは生成スクリプト + テストです。
ストレステスト（安全側デフォルト）
v5.1.2 はデフォルトでメモリ暴走を避ける設計です。
集計のみ（aggregation-only） がデフォルト（keep_runs=False）：各runの詳細結果をメモリに保持しない
任意：異常時のみ ARL 保存（INC#... でインデックス化）
A) 軽いスモーク → 中規模ストレス（推奨ランプ）
# 1) Smoke
python mediation_emergency_contract_sim_v5_1_2.py --runs 200
# 2) Medium stress（集計のみのまま）
python mediation_emergency_contract_sim_v5_1_2.py --runs 10000 --seed 42
B) 異常を意図的に発生（例：捏造率10%を200回）
異常runが発生すると、設定により INC# ファイルが生成されます。
python mediation_emergency_contract_sim_v5_1_2.py \
--runs 200 \
--fabricate-rate 0.1 \
--seed 42 \
--save-arl-on-abnormal \
--arl-out-dir arl_out \
--max-arl-files 1000
生成物（異常が出た場合）：
arl_out/INC#000001__SIM#B000xx.arl.jsonl（incident ARL）
arl_out/incident_index.jsonl（incident index：1行=1件）
arl_out/incident_counter.txt（永続カウンタ）
--max-arl-files でディスク増加を上限管理できます。
アーキテクチャ（高レベル）
監査可能で fail-closed な制御フロー：
agents
→ mediator（risk / pattern / fact）
→ evidence verification
→ HITL（pause / reset / ban）
→ audit logs（ARL）
アーキテクチャ（コード整合図）
以下の図は、現行コード語彙に整合したものです。
監査性と曖昧性排除のため、状態遷移とゲート順を分離しています。
※ドキュメント用。ロジック変更は含みません。
1) 状態機械（コード整合）
<p align="center"> <img src="docs/architecture_state_machine_code_aligned.png" alt="State Machine (code-aligned)" width="720"> </p>
主経路：
INIT
→ PAUSE_FOR_HITL_AUTH
→ AUTH_VERIFIED
→ DRAFT_READY
→ PAUSE_FOR_HITL_FINALIZE
→ CONTRACT_EFFECTIVE
注記：
PAUSE_FOR_HITL_* は HITL が必要な停止点（ユーザー承認 / 管理者承認）。
STOPPED (SEALED) は以下で到達：
証拠が無効または捏造
認可期限切れ
ドラフトlint失敗
SEALED は fail-closed で 非override。
2) ゲート・パイプライン（コード整合）
<p align="center"> <img src="docs/architecture_gate_pipeline_code_aligned.png" alt="Gate Pipeline (code-aligned)" width="720"> </p>
注記：
これは状態遷移ではなく、ゲート評価順を表します。
PAUSE は HITL 必須（人間判断待ち）。
STOPPED (SEALED) は非回復の安全停止。
設計意図：
状態機械：どこで停止/保留/終了するか
ゲート順：どの順序で判断するか
分離により曖昧性を排除し、監査可能性を維持します。
v5.0.1 → v5.1.2：何が変わった？（差分）
まとめ（README向け）
v5.1.2 は 大規模runの安定性 と incident-only 永続化 を強化しています。
デフォルトが「集計のみ（aggregation-only）」
大きな --runs でも、各runの結果をメモリに保持しない（メモリ爆発を回避）
出力はカウンタ + HITL要約中心（itemsは任意）
incident インデックス化（任意機能）
異常runに INC#000001... を付与
異常ARLは {arl_out_dir}/{incident_id}__{run_id}.arl.jsonl
インデックスは {arl_out_dir}/incident_index.jsonl に追記
永続カウンタは {arl_out_dir}/incident_counter.txt
維持されている要素
異常時のみ ARL 永続化（pre-context + incident + post-context）
改ざん検知のARLハッシュチェーン（OSSデモは demo key がデフォルト）
捏造率ミックス + 再現性（--fabricate-rate / --seed）
不変条件：
sealed は ethics_gate / acc_gate のみが設定可能
relativity_gate は決して sealed にならない（PAUSE_FOR_HITL, overrideable=True, sealed=False）
V1 → V4：何が増えた？（概念）
mediation_emergency_contract_sim_v1.py は最小パイプライン（イベント駆動、fail-closed、最小ログ）。
mediation_emergency_contract_sim_v4.py はそれを 再現可能なガバナンスベンチに拡張：
v4で追加：
Evidence gate（無効/捏造で fail-closed 停止）
Draft lint gate（ドラフト専用の境界を強制）
Trust（スコア + streak + cooldown）
AUTH HITL の自動スキップ（trust + grant 条件、理由はARLに残す）
V4 → V5：何が強化された？（概念）
v4は安定ベンチ（スモーク/ストレス）中心。
v5は 成果物レベルの再現性 と 契約的整合チェック を追加。
v5で追加/強化：
ログコードブック（デモ） + 契約テスト（pytest）
layer/decision/final_decider/reason_code の語彙を固定し、ドリフトを防止。
再現性の「固定対象」を明示
simulator/test/codebook をピン留めして再現可能に。
不変条件の検査を明文化
“sealedはethics/accのみ” 等をテストで固定。
v5でも変わらないこと：
研究/教育目的
fail-closed + HITL の意味論
ダミー/合成データのみ、隔離環境推奨
安全性/セキュリティ保証はしない（コードブックは暗号ではない）
実行例
Doc orchestrator（参照実装）
python ai_doc_orchestrator_kage3_v1_2_4.py
Emergency contract（推奨：v5.1.2） + 契約テスト
python mediation_emergency_contract_sim_v5_1_2.py
pytest -q tests/test_v5_1_codebook_consistency.py
Emergency contract（レガシー安定：v4.8）
python mediation_emergency_contract_sim_v4_8.py
pytest -q tests/test_mediation_emergency_contract_sim_v4_8_smoke_metrics.py
Emergency contract（v4.4 stress）
python mediation_emergency_contract_sim_v4_4_stress.py --runs 10000 --out stress_results_v4_4_10000.json
プロジェクトの意図 / 非意図
意図：
安全性・ガバナンス系シミュレーションの再現可能化
HITL（pause/reset/ban）の明示
監査可能な決定トレース（最小ARL）
非意図：
本番運用の自律配備
無制限の自己目的型エージェント制御
実運用の安全性保証（テスト範囲外を保証しない）
データ & 安全メモ
合成/ダミーデータのみ使用。
実行ログは原則コミットしない（成果物は最小・再現性重視）。
生成zipは「レビュー可能な証拠」であり、正のソースではない。
ライセンス
Apache License 2.0（LICENSE
）