# 278 Readmeja 76df3aa0
> 📘 Maestro Orchestrator — オーケストレーション・フレームワーク（fail-closed + HITL）
- Skill: `tools-only/278-readmeja-76df3aa0` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/278-readmeja-76df3aa0`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/278-readmeja-76df3aa0/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/tools-only/278-readmeja-76df3aa0
---
# 📘 Maestro Orchestrator — オーケストレーション・フレームワーク（fail-closed + HITL）
> English: [README.md](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**
```bash
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 を参照。