278 Readmeja Fbbf06b3

📘 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（タイムライン）

2026-01-21

Added

• ai_mediation_hitl_reset_full_with_unknown_progress.py unknown progress（進捗不明）シナリオを HITL/RESET 付きで扱うシミュレーター。
• ai_mediation_hitl_reset_full_kage_arl公開用_rfl_relcodes_branches.py v1.7-IEP 整合の RFL relcode 分岐シミュレーター（RFLは非封印 → HITLへ）。

Changed

• ai_doc_orchestrator_kage3_v1_2_4.py post-HITL のセマンティクスを反映して更新。

2026-02-03

Added

• mediation_emergency_contract_sim_v1.py 最小の緊急ワークフロー： USER auth → AI draft → ADMIN finalize → contract effective 無効／期限切れは fail-closed で停止し、最小ARL（JSONL）を出力。

• mediation_emergency_contract_sim_v4.py v1 を拡張し、以下を追加：

  • evidence gate
  • draft lint gate
  • trust / grant による HITL 摩擦低減

2026-02-05（v4.1：挙動の締め）

Changed

• RFLは非封印（non-sealing） 境界が不安定な提案は PAUSE_FOR_HITL（sealed=false / overrideable=true）で人間判断へ。
• 捏造は早期検知、封印は倫理のみ 捏造は evidence gate で検知し、実際の封印（sealed=true）は ethics_gate のみが発行。
• trust/grant による摩擦低減は維持 閾値を満たす場合は AUTH HITL を安全にスキップしつつ、理由をARLに記録。

Repro

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）

Regression test

pytest -q tests/test_mediation_emergency_contract_sim_v4_1.py

Pinned invariants

• SEALED は ethics_gate / acc_gate のみ（RFLは封印しない）
• RFL は非封印設計（RFL → PAUSE_FOR_HITL → 人間判断）

2026-02-07（v4.4 + stress evidence）

Added

• mediation_emergency_contract_sim_v4_4.py 緊急契約ワークフローベンチ v4.4（fail-closed + HITL + minimal ARL）
• mediation_emergency_contract_sim_v4_4_stress.py v4.4 用ストレス実行（分布＋不変条件チェック）
• stress_results_v4_4_1000.json ストレス結果（1,000回）
• stress_results_v4_4_10000.json ストレス結果（10,000回）

Pinned invariants

• SEALED は ethics_gate / acc_gate のみ（RFLは封印しない）
• RFL は非封印設計（RFL → PAUSE_FOR_HITL → 人間判断）

2026-02-08（v4.6 + 100k stress baseline）

Added

• mediation_emergency_contract_sim_v4_6.py 緊急契約ワークフローベンチ v4.6（fail-closed + HITL + minimal ARL）
• stress_results_v4_6_100000.json 再現可能なストレス証拠（100,000回）

Why（v4.6が確立したもの）

• v4.6 は “unsafe path を早期停止してARLへ落とす” ための再現可能ベースライン。

2026-02-08（v4.7：coaching + compliance signal）

Added

• mediation_emergency_contract_sim_v4_7_full.py 最高スコアのエージェントが coaching を行い、低trustの「最短経路リトライ」を抑え、clean completion を改善。

• （任意機能）evaluation multiplier loop “不正なし完遂” を蓄積し倍率（+0.1 / 上限あり）を管理、HITL finalize で報酬を確定。

Changed

• 重要修正： draft_lint_gate の word-boundary 正規表現が機能していなかった raw string で \\b（二重バックスラッシュ）を使っていたため \b が word boundary として効かず、Safetyパターンが事実上死んでいた。 修正：\\b → \b（7箇所）で本来の検知挙動に復帰。

Evidence（限定マイクロベンチ）

• stress_report_v4_7_draft_lint_100k_seed42.json word-boundary 修正後、停止率が設定重みと整合することを確認。

注：このベンチは draft_lint_gate に限定。一般的な安全性主張ではありません。

2026-02-09（v4.8：ARL詳細化 + evidence bundle）

Diff summary（v4.6 / v4.7 / v4.8）

• v4.6：ベースライン + 100k stress 証拠（fail-closed + HITL + minimal ARL）
• v4.7：挙動改善（coaching / compliance signal、任意で評価ループ）+ draft lint 正規表現の堅牢化
• v4.8：観測性改善（ARLの粒度 + evidence bundle）→ STOP/PAUSE の原因がレビュー可能・改善可能に

Changed

• v4.8 は ARLの詳細化 に注力し、STOP/PAUSE の理由が抽象的すぎて改善に繋がらない問題を軽減 （人間の再トリアージ負担を下げ、反復改善を速くする）

Added

• mediation_emergency_contract_sim_v4_8.py
• tests/test_mediation_emergency_contract_sim_v4_8_smoke_metrics.py
• docs/artifacts/v4_8_artifacts_bundle.zip（ARL + results + report）

Repro

python mediation_emergency_contract_sim_v4_8.py
pytest -q tests/test_mediation_emergency_contract_sim_v4_8_smoke_metrics.py

Note

• zip は テスト／実行で生成される evidence bundle。canonical source として扱わないこと。

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 を参照）