review worker から session/YAML 構造を隠蔽する

[BlueEventHorizon]

review worker から session/YAML 構造を隠蔽する

背景

現在の /forge:review は orchestrator が review_packet を構築し、refs.yaml / plan.yaml / review_<kind>.md を session_dir に保存して reviewer / evaluator / fixer に渡している。

この設計は、Agent 境界をまたぐ永続化・再開性のためには妥当だが、worker 側が refs.yaml / plan.yaml / review_<kind>.md の物理構造を直接知っているため、責務境界が曖昧になっている。

本来、YAML 構造・session 管理・Python スクリプト呼び出しを意識すべきなのは review orchestrator だけであり、reviewer / evaluator / fixer は orchestrator が選定した入力を汎用的な request として受け取るべき。

問題

• reviewer / evaluator / fixer が refs.yaml や plan.yaml のキー構造に依存している
• 参考文書の「発見」は orchestrator 側に寄っているが、worker は保存形式を知りすぎている
• session YAML の schema を変更すると worker prompt も連動して変更が必要になる
• fixer が plan.yaml を読んで mark_in_progress.py を呼ぶなど、状態遷移責務が worker 側に漏れている
• worker の本来責務が「レビューする / 評価する / 修正する」ではなく「session 構造を解釈する」まで広がっている

提案

session_dir 自体は維持する。ただし、session/YAML は orchestrator 内部の永続化形式に降格し、worker には role 別の request/result 契約だけを見せる。

例:

• ReviewerRequest

  • target_files
  • reference_docs
  • related_code
  • criteria
  • ssot_refs
  • check_order
  • output_path

• EvaluatorRequest

  • findings
  • target_files
  • reference_docs
  • ssot_refs
  • interaction_mode

• FixerRequest

  • finding
  • allowed_files
  • reference_docs
  • related_code
  • mode

worker は refs.yaml / plan.yaml の物理構造を直接読まず、orchestrator が生成した request を読む。状態更新は原則 orchestrator が result を受け取って反映する。

責務分離

orchestrator の責務

• session 作成・再開・cleanup
• refs.yaml / plan.yaml / patch_result.json 等の永続化
• reference_docs / related_code / ssot_refs の選定
• worker request の生成
• worker result の検証
• plan 状態遷移

reviewer の責務

• ReviewerRequest に基づいて target_files をレビューする
• findings を返す
• 参考文書の探索や session schema の解釈は行わない

evaluator の責務

• EvaluatorRequest に基づいて findings を吟味する
• recommendation / reason / auto_fixable 等を返す
• plan.yaml を直接更新しない

fixer の責務

• FixerRequest に含まれる単一 finding を allowed_files 内で修正する
• FixerResult を返す
• plan 状態遷移は行わない

非目標

• session_dir を廃止しない
• YAML/JSON 永続化を廃止しない
• Python スクリプトを廃止しない
• worker に参考文書本文を巨大 prompt として直接貼り付ける設計にはしない

期待効果

• worker prompt が role 本来の責務に集中する
• session schema 変更の影響範囲が orchestrator / facade script に閉じる
• review system の保守性が上がる
• Agent 境界を維持しつつ、YAML 実装詳細の漏洩を防げる
• fixer の副作用境界がより明確になる

実装方針案

1. 現行 refs.yaml / plan.yaml は当面維持する
2. scripts/session/ に request 生成 facade を追加する
   • build_reviewer_request.py
   • build_evaluator_request.py
   • build_fixer_request.py
3. worker prompt を request/result 契約ベースに書き換える
4. evaluator / fixer の plan.yaml 直接更新を orchestrator 側へ寄せる
5. 既存テストに「worker prompt が refs.yaml / plan.yaml の内部 schema に依存しすぎていないこと」を追加する