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

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

English version: 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

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