# Maestro Orchestrator — オーケストレーション・フレームワーク（fail-closed + HITL）
> agents → mediator（risk / pattern / fact） → evidence verification → HITL（pause / reset / ban） → audit logs（ARL）
- Skill: `tools-only/maestro-orchestrator-fail-closed-plus-hitl` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/maestro-orchestrator-fail-closed-plus-hitl`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/maestro-orchestrator-fail-closed-plus-hitl/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/maestro-orchestrator-fail-closed-plus-hitl
---
# 📘 Maestro Orchestrator — オーケストレーション・フレームワーク（fail-closed + HITL）
> English version: [README.md](README.md)
---
## 概要（Overview）
Maestro Orchestrator は **研究 / 教育用途** のオーケストレーション・フレームワークです。主に次を優先します。
- **Fail-closed**
不確実・不安定・リスクがある場合 → 黙って続行しない。
- **HITL（Human-in-the-Loop）**
人間の判断が必要な箇所は明示的にエスカレーションする。
- **トレーサビリティ（Traceability）**
最小ARLログにより、意思決定フローを監査可能・再現可能にする。
このリポジトリには、**実装参照（doc orchestrators）** と、交渉・仲裁・ガバナンス系ワークフロー・ゲート挙動の **シミュレーションベンチ** が含まれます。
---
## アーキテクチャ（高レベル）
監査可能で fail-closed な制御フロー：
agents
→ mediator（risk / pattern / fact）
→ evidence verification
→ HITL（pause / reset / ban）
→ audit logs（ARL）
> 画像が表示されない場合は、以下を確認してください：
> `docs/architecture_unknown_progress.png` が同一ブランチ上に存在し、ファイル名が完全一致（大文字小文字含む）していること。
---
## アーキテクチャ（コード整合ダイアグラム）
以下の図は、**現行コードと用語に完全に整合**しています。
監査性と曖昧性回避のため、**状態遷移（state transitions）** と **ゲート順序（gate order）** を意図的に分離しています。
この図は **ドキュメント用途のみ** であり、**ロジック変更は一切ありません。**
---
### 1) ステートマシン（code-aligned）
実行が **停止（SEALED）** または **一時停止（HITL）** するポイントを示す最小ライフサイクル遷移。
**Notes**
**Primary execution path**
INIT
→ PAUSE_FOR_HITL_AUTH
→ AUTH_VERIFIED
→ DRAFT_READY
→ PAUSE_FOR_HITL_FINALIZE
→ CONTRACT_EFFECTIVE
- `PAUSE_FOR_HITL_*` は明示的な **HITL（人間判断待ち）** を表します（ユーザー承認／管理者承認）。
- `STOPPED (SEALED)` 到達条件：
- invalid / fabricated evidence
- authorization expiry
- draft lint failure
- **SEALED 停止は fail-closed であり、設計上 non-overrideable です。**
---
### 2) ゲートパイプライン（code-aligned）
ライフサイクル遷移とは独立した、ゲート評価順序。
**Notes**
- この図は **状態遷移ではなくゲート順序** を示します。
- `PAUSE` は **HITLが必要**（人間判断待ち）を示します。
- `STOPPED (SEALED)` は **非回復の安全停止** を示します。
**Design intent**
- **State Machine** が答えるもの：
*「どこで止まる／どこで一時停止するか？」*
- **Gate Pipeline** が答えるもの：
*「どの順序で判断するか？」*
分離することで曖昧性を避け、監査可能性を保ちます。
**Maintenance note**
画像が表示されない場合：
- `docs/` 配下に存在すること
- ファイル名が完全一致（大文字小文字含む）していること
- リンク更新時はファイル一覧からコピペ推奨
---
## What’s new (2026-01-21)
- **New**: `ai_mediation_hitl_reset_full_with_unknown_progress.py`
Simulator for **unknown progress** scenarios with HITL/RESET semantics.
- **New**: `ai_mediation_hitl_reset_full_kage_arl公開用_rfl_relcodes_branches.py`
v1.7-IEP aligned simulator for **RFL relcode branching**
(RFL is non-sealing → escalates to HITL).
- **Updated**: `ai_doc_orchestrator_kage3_v1_2_4.py`
Doc orchestrator reference updated with **post-HITL semantics**.
---
## What’s new (2026-02-03)
Introduced an **event-driven governance-style workflow**
(fail-closed + HITL + audit-ready).
- **New**: `mediation_emergency_contract_sim_v1.py`
Minimal emergency workflow simulator:
USER auth → AI draft → ADMIN finalize → contract effective
Invalid or expired events fail-closed and stop execution,
producing a minimal ARL (JSONL).
- **New**: `mediation_emergency_contract_sim_v4.py`
Extended v1 with:
- evidence gate
- draft lint gate
- trust / grant–based HITL friction reduction
---
## What’s new (2026-02-05)
- **New**: `mediation_emergency_contract_sim_v4_1.py`
v4.1 is a **behavior-tightening** update over v4.0 to make the bench expectations explicit and code-aligned:
- **RFL is non-sealing by design**
Boundary-unstable proposals trigger `PAUSE_FOR_HITL` with `sealed=false` and `overrideable=true` (human decides).
- **Fabrication is detected early, but sealing occurs only in ethics**
Evidence fabrication is flagged in the evidence gate, and the **only sealing stop** is issued by `ethics_gate`
(`STOPPED` with `sealed=true`).
- **Trust/grant friction reduction remains supported**
Trust/grant-based AUTH auto-skip behavior is preserved (when thresholds are satisfied), while still logging reasons to ARL.
**Quick run**
```bash
python mediation_emergency_contract_sim_v4_1.py
Expected
rust
NORMAL -> CONTRACT_EFFECTIVE
FABRICATE -> STOPPED (sealed=true in ethics_gate)
RFL_STOP -> STOPPED (sealed=false via HITL stop)
v4.1 regression test
This repo includes a dedicated pytest file that pins v4.1 behavior as a contract:
NORMAL -> CONTRACT_EFFECTIVE (not sealed)
FABRICATE -> STOPPED (sealed=true in ethics_gate)
RFL_STOP -> STOPPED (sealed=false via HITL stop)
Invariant: SEALED is issued only by ethics_gate/acc_gate (RFL never seals).
Run only this test file:
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
Emergency contract workflow bench v4.4 (fail-closed + HITL + minimal ARL).
New: mediation_emergency_contract_sim_v4_4_stress.py
Stress runner for v4.4 (distribution + invariant checks).
New: stress_results_v4_4_1000.json
Stress summary (1,000 runs).
New: stress_results_v4_4_10000.json
Stress summary (10,000 runs).
Stress-pinned invariants
SEALED is issued only by ethics_gate / acc_gate (RFL never seals).
RFL is non-sealing by design (RFL → PAUSE_FOR_HITL, human decides).
What’s new (2026-02-08)
New: mediation_emergency_contract_sim_v4_6.py
Emergency contract workflow bench v4.6 (fail-closed + HITL + minimal ARL).
New: stress_results_v4_6_100000.json
Reproducible stress evidence for v4.6 (100,000 runs).
New: mediation_emergency_contract_sim_v4_7_full.py
v4.7 introduces coaching by the top (highest-score) agent to reduce low-trust “shortest-path” retries
and improve clean completion.
Why v4.7 (what was found in v4.6)
In v4.6 stress (100,000 runs), 2 runs STOPPED due to low trust where an agent attempted a low-trust
“shortest-path” retry.
v4.7 adds a guidance step (coaching) to improve the agent state before retrying, and is expected to reduce this failure mode.
v4.6 STOPPED (2 cases): reason_code=TRUST_SCORE_LOW @ model_trust_gate (fail-closed)
Guardrail note (design-time prevention)
The guardrails were already present at design time, so these unsafe conditions were stopped early (fail-closed)
instead of silently continuing and becoming incidents.
v4.6 stress snapshot (100,000 runs)
CONTRACT_EFFECTIVE: 73,307
STOPPED: 18,385
INIT: 8,308
v4.7 (regex fix + re-run)
1) Critical fix: word-boundary regex was not functioning in draft_lint_gate
In the current upload, draft_lint_gate regex patterns used raw strings with \\b (double backslash),
so \b did not work as a “word boundary”, and the Safety patterns were effectively dead.
Fix: \\b → \b (7 occurrences) so word-boundary matching works as intended.
Goal: restore intended detection behavior for Safety patterns that assume word boundaries,
ensuring they correctly trigger fail-closed stops.
2) Focused stress after the fix (100,000 runs / seed=42)
Added stress_report_v4_7_draft_lint_100k_seed42.json
Verified that Safety stop rate aligns with the intended behavior (≈ “draft reach × weight”) after the word-boundary fix.
Reproducibility
This is a focused micro-bench for draft_lint_gate (generate → mutate → lint), with fixed weights:
ok=0.86, out_of_scope=0.04, legal_binding=0.05, discrimination=0.05.
Observed (100,000 runs / seed=42)
Category Expected weight Observed rate Observed count
DRAFT_LINT_OK 0.86 0.86022 86,022
DRAFT_OUT_OF_SCOPE 0.04 0.03902 3,902
SAFETY_LEGAL_BINDING_CLAIM 0.05 0.05000 5,000
SAFETY_DISCRIMINATION_TERM 0.05 0.05076 5,076
SAFETY_STOP_RATE (total) 0.10 0.10076 10,076
TOTAL_FAIL_RATE 0.14 0.13978 13,978
Note: This result validates the intended behavior of draft_lint_gate after the regex word-boundary fix.
This micro-bench is scoped to draft_lint_gate only and is not a general safety claim.
V1 → V4: What actually changed
mediation_emergency_contract_sim_v1.py demonstrates the minimum viable pipeline:
a linear, event-driven workflow with fail-closed stops and minimal audit logs.
mediation_emergency_contract_sim_v4.py turns that pipeline into a
repeatable governance bench by adding early rejection and controlled automation.
Added in v4
Evidence gate
Basic verification of evidence bundles. Invalid, irrelevant, or fabricated evidence triggers fail-closed stops.
Draft lint gate
Enforces draft-only semantics and scope boundaries before admin finalization. Hardened against markdown/emphasis noise
to reduce false positives.
Trust system (score + streak + cooldown)
Trust increases on successful HITL outcomes and decreases on failures. Cooldown prevents unsafe automation after errors.
All trust transitions are logged in ARL.
AUTH HITL auto-skip (safe friction reduction)
When trust threshold + approval streak + valid grant are satisfied,
AUTH HITL can be skipped for the same scenario/location only,
while recording the reason in ARL.
実行例（Execution Examples）
まずは1本動かして挙動とログを確認し、その後に広げてください。
NOTE: このリポジトリは research / educational です。
合成データ（ダミー）を使用し、実行時ログをコミットしないでください。
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
Reproducible safety and governance simulations
Explicit HITL semantics
Audit-ready decision traces
Non-goals
Production-grade autonomous deployment
Unbounded self-directed agent control
Safety claims beyond what is explicitly tested
License
Apache License 2.0（LICENSE を参照）