074 Readmeja 975c8d74

# 📘 Maestro Orchestrator — オーケストレーション・フレームワーク（fail-closed + HITL）

## 1) Context flow（文脈フロー）

### Context Flow Diagram

- **Perception** — 入力を実行可能要素へ分解（タスク化）
- **Context** — 仮定／制約／リスク要因を抽出（ガード理由）
- **Action** — 実行者へ指示、結果検証、分岐（STOP / REROUTE / HITL）

---

## 2) Orchestrator one-page design map（1枚設計図）

### Decision flow map（実装準拠）

`mediator_advice → Meaning → Consistency → RFL → Ethics → ACC → DISPATCH`

**fail-closed 前提**：リスク／曖昧さがあれば **PAUSE_FOR_HITL** または **STOPPED** に倒し、「なぜ」をログに残します。

### Orchestrator one-page design map

画像が表示されない（または小さい）場合は直接開いてください：

- `docs/orchestrator_onepage_design_map.png`

> **RFL は非封印（non-sealing）設計**です：RFL は **PAUSE_FOR_HITL** にエスカレートし、`sealed=true` にはなりません。

---

## 3) Architecture（構成図）

監査可能（audit-ready）かつ fail-closed な制御フローの全体像：

`agents → mediator（risk / pattern / fact）→ evidence verification → HITL（reset / ban）→ audit logs`

### Architecture (unknown progress + HITL)

画像が表示されない（または小さい）場合は直接開いてください：

- `docs/architecture_unknown_progress.png`

---

## 🆕 変更点（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`  
  **KAGE v1.7-IEP** の **RFL relcode 分岐**（RFL は非封印→HITL）を検証するシミュレータ。

- **Updated**: `ai_doc_orchestrator_kage3_v1_2_4.py`  
  Doc orchestrator の参照実装（**post-HITL セマンティクス**）更新。

---

## 🧾 監査ログ & データ安全（IMPORTANT）

このプロジェクトは、再現性と説明責任のために **監査ログ（audit log）**を出力します。  
ログはセッションより長く残り、研究共有され得るため、ログを**センシティブな成果物**として扱う前提で設計してください。

- プロンプト／テストベクタ／ログに **個人情報（PII）**（メール、電話番号、住所、実名、アカウントID等）を入れない
- 実験は **合成データ／ダミーデータ** を優先
- 実行時ログをリポジトリにコミットしない（必要なら **マスキング／保持期限／隔離ディレクトリ**を適用）

### 🔒 監査ログ要件（MUST）

研究共有可能で安全なログにするため：

- **MUST NOT**：PIIや秘密情報を含み得る raw のプロンプト／出力を永続化しない
- **MUST**：sanitized な証拠（redacted / hashed / カテゴリ信号）だけを保存する
- **MUST**：PII様パターンは fail-closed で赤塗り（検知失敗時はログを書かない）
- **MUST**：赤塗りは **値だけでなく辞書キーにも適用**（`@` 等が残存しないこと）
- **MUST**：実行時ログをリポジトリにコミットしない（ローカル隔離を推奨）

#### 最小必須フィールド（実装準拠, MUST）

`run_id, ts, layer, decision, reason_code, sealed, overrideable, final_decider`

#### 任意フィールド（必要なら SHOULD）

`session_id, policy_version, artifact_id, route_id`（すべて **非PII・sanitized 前提**）

#### 保持期限（SHOULD）

- 7 / 30 / 90 日など保持期限を定義し、自動削除すること。

---

## 🧑‍⚖️ HITL セマンティクス（HITL後の挙動を定義）

HITL は曖昧・高リスク時に使用します。責任の所在は監査ログで追跡可能であるべきです。

### HITL 要求時（SYSTEM）

オーケストレーターは `HITL_REQUESTED（SYSTEM）` を出力し、通常以下を含みます：

- `decision=PAUSE_FOR_HITL`
- `sealed=false`
- `overrideable=true`

### HITL 決定時（USER）

ユーザーの選択は `HITL_DECIDED（USER）` として記録します：

- `sealed=false`
- `overrideable=false`
- `final_decider=USER`

選択の伝搬：

- **CONTINUE** → 決定は `RUN` に伝搬
- **STOP** → 決定は `STOPPED` へ

> 注意：`sealed=true` になれるのは **Ethics/ACC のみ**（この場合 `final_decider=SYSTEM`）。

---

## ⚙️ 実行例（Execution Examples）

> “persuasion / reeducation” を想起させるモジュールは **安全評価用途のみ**で、明示的 opt-in がない限り **デフォルト無効** を推奨します。

```bash
python ai_mediation_all_in_one.py
python kage_orchestrator_diverse_v1.py
python ai_governance_mediation_sim.py