# 278 Readmeja Fbbf06b3
> 📘 Maestro Orchestrator — オーケストレーション・フレームワーク（fail-closed + HITL）
- Skill: `tools-only/278-readmeja-fbbf06b3` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/278-readmeja-fbbf06b3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/278-readmeja-fbbf06b3/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-fbbf06b3
---
# 📘 Maestro Orchestrator — オーケストレーション・フレームワーク（fail-closed + HITL）
> English version: [README.md](README.md)
---
## 概要（Overview）
Maestro Orchestrator は **研究／教育用途**のオーケストレーション・フレームワークです。優先する設計原則は以下です。
- **Fail-closed（閉じて安全）**
不確実・不安定・リスクあり → 何も言わずに継続しない
- **HITL（Human-in-the-Loop）**
人間の判断が必要な意思決定は明示的にエスカレーションする
- **トレーサビリティ（追跡可能性）**
最小ARLログにより、意思決定フローを監査可能・再現可能にする
本リポジトリには **実装リファレンス（doc orchestrator）** と、交渉／仲裁／ガバナンス風ワークフロー／ゲーティング挙動を検証する **シミュレーションベンチ** が含まれます。
---
## Quickstart（推奨の最短導線）
まずは “1本動かしてログを確認” してから拡張してください。
### 1) 最新の緊急契約シミュレーター（v4.8）を実行
```bash
python mediation_emergency_contract_sim_v4_8.py
````
### 2) ピン留めされた smoke テスト（v4.8）を実行
```bash
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**
```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）
**Regression test**
```bash
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**
```bash
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（実装リファレンス）**
```bash
python ai_doc_orchestrator_kage3_v1_2_4.py
```
**Emergency contract（v4.8）**
```bash
python mediation_emergency_contract_sim_v4_8.py
```
**Emergency contract（v4.1）**
```bash
python mediation_emergency_contract_sim_v4_1.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
```
---
## プロジェクトの意図／非目標（Intent / Non-goals）
### Intent
* 再現可能な安全／ガバナンスシミュレーション
* 明示的な HITL セマンティクス（pause/reset/ban）
* 監査可能な意思決定トレース（最小ARL）
### Non-goals
* そのまま本番運用できる自律デプロイ
* 無制限な自己目的化エージェント制御
* 明示テスト範囲を超えた安全性主張
---
## データ／安全メモ（Data & safety notes）
* **合成／ダミーデータのみ**を使用してください。
* 実行ログはコミットしないことを推奨（必要なら再現可能な最小証拠に限定）。
* 生成されたzip（bundle）は **レビュー用証拠束**であり、canonical source ではありません。
---
## License
Apache License 2.0（`LICENSE` を参照）