作成日: 2026-04-15
ステータス: Draft
関連文書:
implement_worker.py の ImplementWorker は、3層アーキテクチャ（#48）の整理により
ImplementMaid として再定義される。
本書は ImplementMaid の責務・シーケンス・Goose との関係を明確に定義する。
旧称 ImplementWorker は誤解を招く。
| 旧称 | 新称 | 理由 |
|---|---|---|
ImplementWorker |
ImplementMaid |
LLM（Goose）を動かす層は Maid であり Worker ではない |
implement_worker.py |
implement_maid.py |
ファイル名・クラス名も合わせて改名する |
3層アーキテクチャにおける位置づけ：
Brain
│ MCP
▼
Orchestrator（mcp_facade.py + router.py）
│
▼
ImplementMaid（implement_maid.py） ← ここ
│
├─→ Goose（ファイル編集のみ）
└─→ git_worker（git 操作）
ImplementMaid は「Goose に実装を委任し、git 操作を自ら管理する監督者」である。
| 責務 | 担当 | 備考 |
|---|---|---|
| ブランチ作成 | ImplementMaid | Goose 起動前に butler/task-{id} を切る |
| Prompt 構築 | ImplementMaid | _build_prompt() で Goose に渡す指示を組み立てる |
| Goose 起動 | ImplementMaid | --no-profile + developer + worker_mcp で起動 |
| Goose の監視 | ImplementMaid | watchdog / stagnation 検知 |
| git 操作（コミット） | ImplementMaid | Goose 終了後に変更を確認してコミットする |
| Goose の git 直叩き検知 | ImplementMaid | baseline と比較し、不正コミットを検知する |
| 検証（verify） | ImplementMaid | changed_files / test_commands / scope_violation を確認 |
| 再試行（supervision） | ImplementMaid | 最大3回（初回1回 + 再依頼2回） |
| evidence 返却 | ImplementMaid | Brain に結果を返す |
| 項目 | 担当 |
|---|---|
| ファイル編集 | Goose（developer 拡張） |
| ブランチの main へのマージ | Brain が判断し、Orchestrator 経由で実行 |
| git push | Brain が判断し、Orchestrator 経由で実行 |
| issue へのコメント | Brain または Orchestrator 経由 |
Goose は「ファイルを編集するだけの実行エージェント」である。
developer 拡張を使ったファイル読み書き・シェル実行worker_mcp のツールを使った操作（Gitea コメント等、将来拡張）Goose は developer 拡張のシェルで git commit を直接叩くことが技術的には可能。
これを完全に防ぐことはできないが、ImplementMaid の管理下に置くことで対処する。
対処方針：
_record_baseline() で git 状態を記録するImplementMaid が Goose を起動する際のフラグ：
goose run --instructions - --no-session --quiet
--provider {maid.provider}
--model {maid.model}
--no-profile # ユーザー設定を無視（循環防止）
--with-builtin developer # ファイル編集に必要
--with-extension "uv run --project {butler2_root} python -m butler.worker_mcp"
[--with-extension "..." ...] # launch_config.additional_extensions から
--no-profile を使う理由：
~/.config/goose/config.yaml に依存しない（環境差をなくす）run_implement が含まれる Orchestrator MCP を Goose に渡さない（循環防止）--provider / --model CLI フラグで明示的に渡すworker_mcp は Worker 層の MCP サーバーであり、Goose 専用ではない。
3層アーキテクチャにおける Worker 層へのアクセス経路を MCP として公開する。
| ツール種別 | 含む | 備考 |
|---|---|---|
| git ツール（git_commit / git_push / git_pull） | ✅ | Brain → Orchestrator → Worker 経路でも使用 |
| Gitea 書き込みツール | ✅ | issue コメント追加・更新・クローズ |
Goose は worker_mcp の git ツールに接続できるが、
_build_prompt() の git 禁止ルールにより git 操作を行わないよう指示される。
Goose が git を直叩きした場合は ImplementMaid が検知して対処する（section 4.3 参照）。
Brain
│ run_implement(goal, spec, target_paths, ...)
▼
Orchestrator（mcp_facade.py）
│ execute_task(TaskContract{intent="implement"}) ※Orchestrator内部ルーティング表記
▼
ImplementMaid
│
├─[0] 事前チェック: 未コミット変更がないことを確認
│ └─ 未コミット変更あり → 即時 need_input を返す（Maid 起動しない）
├─[1] branch 作成: git checkout -b butler/task-{id}
├─[2] baseline 記録: _record_baseline()
├─[3] prompt 構築: _build_prompt()
│ └─ goal / spec / scope / target_paths
│ └─ 「git 操作は行わないこと」の明示
├─[4] Goose 起動
│ └─ --no-profile --with-builtin developer --with-extension worker_mcp
│
│ [Goose が動く]
│ Goose: ファイルを探索・編集・テスト実行
│
├─[5] Goose 終了後：git 状態確認
│ └─ Goose が直接コミットしていないか確認
│ └─ changed_files を算出
├─[6] ImplementMaid が変更をコミット（git_worker 経由）
├─[7] verifier 実行
│ └─ scope_violation / test_commands / file_checks
│
├─[8a] 成功 → evidence を返す
└─[8b] 失敗 → supervision（[3]に戻る、最大3回）
└─ 前回の失敗内容を compact prompt に含める
Orchestrator
│ ResultContract を Brain に返す
▼
Brain
│ evidence を確認・判断
├─ OK → Orchestrator に git_push / merge 等を依頼
└─ NG → 再依頼 or Brain 直実装 or task 分割
Brain は Orchestrator（mcp_facade.py）経由で git 操作を行う。
これは ImplementMaid とは独立した経路。
Brain
│ git_commit(project_root, message)
▼
Orchestrator（mcp_facade.py）
│ execute_task(TaskContract{intent="git_commit"})
▼
git_worker
│ git commit を実行
▼
Orchestrator → Brain: ResultContract
Goose（実行中）
│ worker_mcp のツールを呼ぶ（例: leave_note）
▼
worker_mcp（stdio MCP サーバー）
│ execute_task(TaskContract{intent="record_to_gitea"})
▼
gitea_issue_worker
│ Gitea API を叩く
▼
worker_mcp → Goose: 結果
_build_prompt() の追加方針）既存の prompt 構成（goal / spec / scope / target_paths 等）に加え、以下を明示する：
## ツール使用ルール
- git commit / git push / git merge は直接実行しないこと
- 変更の保存・コミットは ImplementMaid が行う
- ファイル編集は developer 拡張を使うこと
将来 worker_mcp に抽象化ツールを追加した際は、そのツール名と使用タイミングをここに追記する。
| 項目 | 状態 |
|---|---|
Goose 起動に --no-profile / --with-extension worker_mcp を追加 |
✅ 実装済み（#48） |
| worker_mcp サーバー（butler/worker_mcp.py） | ✅ 実装済み（#48） |
ImplementWorker → ImplementMaid 改名 |
✅ 実装済み |
| ImplementMaid が Goose 終了後にコミットする | ✅ 実装済み |
| Goose の git 直叩き検知ロジック | ✅ 実装済み |
_build_prompt() に git 禁止ルールを追加 |
✅ 実装済み |
worker_mcp のツール抽象化（save_progress 等） |
❌ 未実装・設計中 |