役割: 継続開発時の設計判断基準となる正本
対象読者: 新しい Brain（Claude Code やその後継モデル）
更新条件: 設計原則・責務境界・配置ルールが変わった時のみ
この文書は、Butler Layer のソース一式を毎回深掘りしなくても、
新しい Brain が同じ設計思想・責務分離・実装配置ルールに従って機能追加や修正を継続できる
ための基準書である。
この文書に書くもの: 設計原則・責務境界・配置ルール・不変条件（数週間後も有効なもの）
この文書に書かないもの: 直近 TODO・設定値・進捗（→ STARTUP_CONTEXT.md）/ 詳細仕様・スキーマ（→ docs/reference/）
理想的な理解順序（docs/README.md → 本書 → 以下の順）:
セッション開始時の最低限必読は CLAUDE.md で別途定義。この順序はその思想的根拠。
docs/README.md（全体の地図と区分を把握する）docs/vision/00_ビジョン定義書.md（なぜそのルールがあるかを理解する）docs/reference/ 群（詳細仕様）butler__get_skill_usage(<スキル名>) で registry 登録済みスキルのコントラクトを確認する（全 Intent を網羅しない点に注意）STARTUP_CONTEXT.md（今どこで止まっているかを確認する）Brain のトークン消費を低レベル作業から切り離し、判断・設計・会話に集中させること。
そのために以下を実現する。
「Butler に教える（teach）コストを惜しまない」 ことがこのシステムの成長の源泉である。
Brain が直接実行できても、Butler を育てる観点から委任を選ぶ。
Brain は「何を達成するか」を定義する。
ステップ A → B → C の反復・収集・実行手順は Butler 側へ寄せる。
Brain が get_status を繰り返し呼んでいたら、設計を見直す。
Brain と Butler の協調は、Task Contract / Result Contract / 状態遷移の合意で成立する。
曖昧な自然言語依存を増やさない。契約の型を守ることが、AI モデルを超えた継続性を保証する。
成功可否は要約文ではなく、実行証跡と verifier で判定する。
モデルの自己申告を信頼しすぎない。SQLite と Trilium に証跡を残す。
Intent ドメインに属する運用作業は、Brain が自力でできても Butler に委任する。
Butler が知らないなら teach し、学習させる。自力実行は例外であり、原則ではない。
全体で再利用する基盤は core に置く。
用途固有の機能は capability または SOP に置く。
core を汚染する capability の追加は設計劣化の兆候。
設計や責務境界に影響する変更は、関連する reference 文書と本書を同じ作業で更新する。
コードだけ更新して文書が古くなることを防ぐ。
破壊的・不可逆操作の承認ゲートは Butler から Brain 経由で人間に委ねる。
Butler が人間に直接話しかける構造を入れない。承認を自動スキップする構造を入れない。
Brain (Claude Code / 後継モデル)
│ 判断・設計・要求定義・結果解釈
│ Task Contract を作り submit する
│ 承認ゲートと need_input への応答のみ担う
│
↓ butler__submit_task / butler__approve / butler__teach
Butler (Python MCP サーバー)
│ 契約検証 → SOP 解決 / スキルハンドラー → 実行 → 検証 → 証跡記録
│ Orchestrator が自律実行（Brain を起こさない）
│ SOP 不明時は need_input を返し Brain に教わる
│
↓ mcp_call ステップ / cmd ステップ / agent_executor (Qwen)
外部サービス (Trilium / Gitea / Docker 等)
実際のデータ・処理の宿
| 責務 | 内容 |
|---|---|
| 要求の定義 | 何を達成するかを Task Contract に落とす |
| 成功条件の定義 | success_criteria を明確に書く |
| リスク許容判断 | require_approval_for で承認対象を指定する |
| 結果の最終解釈 | ok が返っても証跡を読んで妥当性を確認する |
| SOP 修正の採否判断 | need_input 時に butler__teach で教える |
Brain がやってはいけないこと: 実行コマンドを自分で組み立てて Bash で叩く、Trilium API を直接呼ぶ、ループで状態を監視する。
| 責務 | モジュール |
|---|---|
| 契約検証 | models.py (Pydantic) |
| SOP 解決 / スキルハンドラー起動 | sop_resolver.py / orchestrator.py |
| 承認ゲート制御 | approval.py / policy.py |
| ステップ実行 (cmd / check / wait / mcp_call) | executor.py |
| 証跡記録 | recorder.py / db.py |
| Qwen 判断ゲート（承認要否 / エラー分類） | qwen_gate.py |
| Qwen 自律実行（agent モード） | agent_executor.py |
| スキル自己記述 | skills_registry.py |
Qwen は Butler が使う道具であり、二つの異なる文脈で使われる。
役割 A: 判断ゲート（通常フロー）
承認要否判断とエラー分類のみ担う。qwen_gate.py 経由。
Python 側が状態遷移・記録の主導権を持つ。
役割 B: 自律実行器（delegation_mode: "agent" 時）
SOP や handler で表現できない自由度の高いタスクを Qwen が自律実行する。agent_executor.py 経由。
ツール定義（tools.py）の範囲内で動く。Brain の指示なしに実行が進む。
Qwen の出力をそのまま信頼せず、常に証跡で検証する原則は両役割で共通。
| データ | 場所 | 役割 |
|---|---|---|
| 機械向け真実源 | SQLite (butler.db) |
タスク状態・証跡・SOP・セッション |
| 人間向け知識の外部記憶 | Trilium | 設計記録・SOP ドキュメント・作業履歴 |
| セッション再開用キャッシュ | STARTUP_CONTEXT.md |
直近進捗・設定値・TODO |
butler/ コア（butler/*.py）に置くもの判定基準: 複数の capability で共通利用される、または Butler 全体の動作原理に関わる。
新機能追加時に core への変更が必要なら、それは設計の見直しサイン。
core は capability に依存しない（依存方向は capability → core の一方向のみ）。
butler/capabilities/<skill>/ に置くもの判定基準: 特定ドメイン専用のフローで、コアを変更せずに追加できる。
capabilities/
<skill>/
handler.py # HANDLED_INTENTS を宣言。Orchestrator が動的ロード
tools.py # agent モード用ツール定義（TOOL_DEFS / run_tool）
_utils.py # スキル内共通ユーティリティ（必要時のみ）
HANDLED_INTENTS に Intent を列挙することで、Orchestrator は core を変更せずにハンドラーを認識する。
handler.py だけで完結する場合、tools.py は不要。
sops テーブル）に置くもの判定基準: 手順が安定していて、Intent × Target で識別でき、Step kind で表現できる。
SOP は teach_if_unknown → candidate → 成功実績で active のライフサイクルで育つ。
手順が将来変わりやすい場合は SOP で吸収できる（active から deprecated へ移行）。
skills_registry.py に置くものBrain 向けのスリム版スキルドキュメント（呼び出しに必要な最小情報のみ）。
2層構造になっている:
"butler" エントリ: 共通コントラクト構造 + スキル一覧テーブル。Brain が最初に1回取得するtarget.service・payload の必須フィールド・注意点のみフル JSON コントラクト例・レスポンス例は docs/reference/skill_contracts_detail.md に分離。
Brain が必要な場合のみ Read する。
全 Intent を網羅するものではない。known_only handler や高頻度スキルのうち、
Brain に正確なコントラクトを伝える必要があるものだけが登録される。
新スキルを追加した場合は登録を検討するが、必須ではない（SOP のみで動くものは不要）。
Butler が担うべき Intent の一覧。Brain はこれらを自力実行せず委任する。
| Intent | 実装状態 | 方式 |
|---|---|---|
read_from_trilium |
実装済み | known_only handler |
record_to_trilium |
実装済み | agent モード (SOP + tools.py) |
reorganize_trilium_tree |
実装済み | known_only handler |
git_commit |
実装済み | known_only handler |
git_push |
実装済み（NEED_APPROVAL 必須） | known_only handler |
git_pull |
実装済み | known_only handler |
git_create_remote_repo |
実装済み・現在 BLOCKED | known_only handler（Gitea Basic 認証待ち） |
collect_logs |
部分実装（service=test target のみ SOP あり） |
teach_if_unknown で他 target を追加可 |
triage |
部分実装（service=test target のみ SOP あり） |
teach_if_unknown で他 target を追加可 |
commit_push |
SOP 未登録 | teach_if_unknown |
bootstrap_context |
SOP 未登録 | teach_if_unknown |
update_sop |
SOP 未登録 | teach_if_unknown |
add_project_to_wiki |
実装済み | known_only handler（push 前に承認） |
sync_wiki |
実装済み | known_only handler（push 前に承認） |
deploy |
未実装（設計域） | Phase 8-A 予定 |
restart |
未実装（設計域） | Phase 8-A 予定 |
health_check |
未実装（設計域） | Phase 8-E 予定 |
「部分実装」の Intent は、既存 SOP の target_signature と一致する target なら実行できる。
別 target で提出すると need_input が返る → butler__teach で手順を教えると SOP に追加される。
「SOP 未登録」の Intent は teach_if_unknown で提出すると常に need_input が返る。
Intent の実装状態は以下の2系統に分かれる。正本が異なる点に注意。
butler/capabilities/*/handler.py の HANDLED_INTENTS が正本。sops テーブルには出てこない。butler.db の sops テーブルが正本。登録済み target_signature を確認することで、何が動くか分かる。新 Intent を追加する際は、このテーブルも更新する。
1. その機能は Brain の判断仕事か、Butler の運用仕事か？
→ Brain の仕事なら Butler に委任しない
2. Butler の仕事なら、SOP（定型手順）で表現可能か？
→ 可能なら teach → SOP 化。capability 不要
3. SOP では足りないか（stateful フロー / 複数ツール束ね / HITL 必要）？
→ capability handler 化を検討（handler.py + HANDLED_INTENTS）
4. その capability は複数スキルに共通か？
→ core への追加を検討（ただし慎重に。core 肥大化を避ける）
5. 追加後に Brain が細かく往復する設計になっていないか確認する
（Brain がループしていたら設計を見直す）
6. 証跡・承認・検証の扱いが既存原則を崩していないか確認する
7. 関連文書（本書の Intent テーブル含む）を同時更新する。
handler 追加なら `HANDLED_INTENTS`、SOP 追加なら `butler.db` が正本。
registry（`skills_registry.py`）は Brain 向けにコントラクトを公開したい場合のみ更新する。
Task Contract の完全仕様は docs/reference/02_契約通信仕様書.md を参照。
各スキルのコントラクト情報は butler__get_skill_usage("butler") で共通構造を、
butler__get_skill_usage(<スキル名>) で個別の呼び出し方を取得する。
フル JSON 例が必要な場合は docs/reference/skill_contracts_detail.md を Read する。
Brain が必ず指定するフィールド: task_id, intent, target, delegation_mode, constraints, success_criteria, requested_by, requested_at
| モード | 使う状況 |
|---|---|
known_only |
capability handler が存在するスキル（確実に動く） |
teach_if_unknown |
SOP が未知かもしれないが Butler に学ばせたい |
agent |
SOP でも handler でも表現できない自由度の高いタスク（Qwen 自律） |
Butler が need_input を返したら、Brain は butler__teach で構造化 Steps を渡す。
Step の型定義は butler/models.py の Step クラスを参照（kind, value, server, tool, params）。
完全なフォーマットは docs/reference/03_実行SOP仕様書.md を参照。
自然言語の指示を Butler に渡しても機能しない。必ず構造化する。
butler__submit_task # タスク提出
butler__get_status # 状態確認（同期実行スキルは不要）
butler__approve # HITL 承認
butler__teach # SOP 教示（need_input 時）
butler__cancel_task # キャンセル
butler__list_skills # スキル一覧確認
butler__get_skill_usage # スキルコントラクト確認
butler__approve の decision 値: "approve" または "deny" のみ有効。"approved" は無効。
mcp__trilium__* を直接呼ばない。必ず read_from_trilium / record_to_trilium 経由で Butler に委任する。
以下は変更してはいけない設計上の不変条件。変更が必要な場合は本書の更新と合わせて議論する。
get_status）」のいずれかで行う。Butler から Brain を呼び出す構造を入れない。output_file を Read 後に必ず削除する。以下のいずれかが起きたら本書を更新する。
以下は本書に書かない。
STARTUP_CONTEXT.mdSTARTUP_CONTEXT.mddocs/reference/skills_registry.py（スリム版）/ docs/reference/skill_contracts_detail.md（詳細版）/ docs/capabilities/| 順序 | 参照先 | 目的 |
|---|---|---|
| 1 | docs/README.md |
文書区分と全体の地図を把握する |
| 2 | 本書 | 設計哲学・責務境界・配置ルールを理解する |
| 3 | docs/vision/00_ビジョン定義書.md |
最上位目的・スキル構造・tools.py 規約を深掘りする |
| 4 | docs/reference/01_アーキテクチャ定義書.md |
Orchestrator 内部構成・ガバナンスを詳細確認 |
| 5 | docs/reference/02_契約通信仕様書.md |
Task/Result Contract の完全仕様 |
| 6 | docs/reference/03_実行SOP仕様書.md |
SOP 実行・Step kind・butler__teach フォーマット |
| 7 | docs/reference/04_データ運用仕様書.md |
SQLite スキーマ・冪等性・KPI |
| 8 | docs/reference/05_Brain動作原則.md |
Brain が守るルールの詳細 |
| 9 | 該当 capability 仕様 | スキル固有の詳細（必要な場合のみ） |
| 10 | butler__get_skill_usage("butler") → 個別スキル |
共通構造 → 個別呼び出し方を段階的に取得する（全 Intent を網羅しない） |
| 11 | docs/reference/skill_contracts_detail.md |
フル JSON コントラクト例・レスポンス例（必要時のみ Read） |
| 11 | STARTUP_CONTEXT.md |
実務再開時のみ — 直近の進捗・TODO・設定値を把握する |