# v1.15 LLM メッセージの外部化
Release Date: 2026-02-03
## 目的
- LLM への全メッセージ（エラー・成功・指示）を `phase_contract.yml` に集約し、コードから分離する
- メッセージのカスタマイズを可能にする
- 二重管理（コード内ハードコード + YAML）を解消する
---
## 設計
### YAML 構造
```yaml
phases:
EXPLORATION:
instruction: ...
expected_payload: ...
failures:
empty_result:
error: payload_mismatch
message: "探索結果が空です。code-intel ツールを使って探索し、explored_files と findings を記載して再送してください"
success:
complete:
message: "探索完了。セッションを終了します。"
common_failures:
summary_required:
error: payload_mismatch
message: "summary is required for this phase."
tool_errors:
review_changes:
phase_blocked:
error: phase_blocked
message: "review_changes only allowed in PRE_COMMIT phase, current: {phase}."
```
### 失敗ケース一覧
#### 共通バリデーション（全フェーズ適用）
- [ ] `summary_required` - summary is required for this phase.
- [ ] `tools_used_invalid` - tools_used must be a list (empty list allowed).
- [ ] `exploration_min_tools` - EXPLORATION requires at least 2 distinct tools before submit_phase.
- [ ] `required_tools_not_used` - Required tools not used: {missing_list}.
- [ ] `required_tools_not_reported` - tools_used must include required tools: {missing_reported}.
- [ ] `unknown_phase` - No handler for phase {phase}.
#### BRANCH_INTERVENTION
- [ ] `invalid_choice` - choice must be 'delete', 'merge', or 'continue'.
- [ ] `branch_operation_failed` [user_intervention] - Branch {choice} failed: {errors}. ブランチ操作に失敗しました。ユーザーに失敗内容を通知し、手動での解決を依頼してください。
#### DOCUMENT_RESEARCH
- [ ] `empty_documents` - 指定ドキュメントを読み、`documents_reviewed` に結果を記載して再送してください
#### EXPLORATION
- [ ] `empty_result` - 探索結果が空です。code-intel ツールを使って探索し、`explored_files` と `findings` を記載して再送してください
#### SEMANTIC
- [ ] `empty_search_results` - 検索結果が空です。`semantic_search` を実行し、`search_results` を記載して再送してください
#### VERIFICATION
- [ ] `empty_hypotheses` - 検証結果が空です。仮説を1件ずつ検証し、`hypotheses_verified` を記載して再送してください
- [ ] `result_false_exists` - result=false の仮説があります。全仮説が result=true になるまで再検証し、`hypotheses_verified` を再送してください
#### IMPACT_ANALYSIS
- [ ] `empty_impact_summary` - 影響分析結果が空です。`analyze_impact` を実行し、`impact_summary` を記載して再送してください
#### READY
- [ ] `branch_creation_failed` [user_intervention] - タスクブランチの作成に失敗しました。ユーザーに状況を伝え、`git status` での作業ツリー確認・手動ブランチ作成・`/code --clean` でのリセットのいずれかを依頼してください
- [ ] `phase_mismatch_register` - Task registration is only allowed in READY phase.
- [ ] `empty_tasks` - At least one task is required.
- [ ] `duplicate_task_ids` - Task IDs must be unique.
- [ ] `no_pending_tasks` - At least one task must have status 'pending'.
- [ ] `phase_mismatch_complete` - Task completion only in READY phase.
- [ ] `no_tasks` - No tasks registered. Call submit_phase with tasks first.
- [ ] `unknown_task` - Task '{task_id}' not found.
- [ ] `already_completed` - Task '{task_id}' is already completed.
- [ ] `wrong_order` - Must complete '{expected_task}' before '{task_id}'.
- [ ] `no_tasks_registered` - No tasks registered. Submit task plan first.
- [ ] `incomplete_tasks` - {count} task(s) still pending.
#### PRE_COMMIT
- [ ] `missing_commit_message` - commit_message is required.
- [ ] `branch_manager_not_found` [user_intervention] - タスクブランチが未作成の状態でコミットフェーズに到達しました。ユーザーに状況を伝え、`git branch` でのブランチ状態確認または `/code --clean` でのセッションリセットを依頼してください
- [ ] `review_failed` - discard 判定のファイルに reason が未指定です。理由を付けて `reviewed_files` を再送してください
- [ ] `finalize_failed` [user_intervention] - git commit に失敗しました。ユーザーに状況を伝え、pre-commit hook のエラー出力や `git status` の確認と手動での問題解決を依頼してください。解決後、再度 submit_phase を実行してください
#### QUALITY_REVIEW
- [ ] `commit_execution_failed` [user_intervention] - 品質レビュー後のコミット実行に失敗しました。ユーザーに状況を伝え、`git status` での working tree 確認と手動での問題解決を依頼してください
- [ ] `quality_forced_completion` - 品質問題が未解決のまま完了
#### MERGE
- [ ] `quality_review_required` - QUALITY_REVIEW not completed.
- [ ] `branch_manager_not_found` [user_intervention] - ブランチ管理情報が不整合です。ユーザーに状況を伝え、`git branch` での状態確認または `/code --clean` でのセッションリセットを依頼してください
- [ ] `merge_failed` [user_intervention] - ブランチのマージに失敗しました。ユーザーに状況を伝え、`git status` でのコンフリクト確認と手動解決を依頼してください。解決後、再度 submit_phase を実行してください
#### VERIFY_INTERVENTION
- [ ] `user_escalation` - .code-intel/user_escalation.md の手順に従いユーザーへヘルプ要請を行ってください。使用した手順書の名前/パスを明記して submit_phase で送信してください。
- [ ] `escalation_count` - 介入を {count} 回実行しました。ユーザーに相談してください。
---
### 正常完了メッセージ
セッション終了やフェーズ完了時のメッセージ。
#### Q3 / IMPACT_ANALYSIS（調査完了）
- [ ] `investigation_complete` - 探索完了。セッションを終了します。
#### READY（タスク完了）
- [ ] `session_complete_no_verify_quick` - 全タスク完了。セッション終了（--no-verify + --quick）。
#### POST_IMPL_VERIFY
- [ ] `session_complete_quick` - 検証通過。セッション終了（--quick）。
#### MERGE
- [ ] `no_task_branch_complete` - No task branch. Session complete.
- [ ] `merge_success` - Merged {from_branch} → {to_branch}. Session complete.
---
### ツール固有エラー
submit_phase 以外のツールで発生するエラー。
#### review_changes
- [ ] `phase_blocked` - review_changes only allowed in PRE_COMMIT phase, current: {phase}.
- [ ] `task_branch_not_enabled` - Task branch not enabled. Cannot review changes.
- [ ] `branch_manager_not_found` - Branch manager not found and cannot be recreated (no task_branch_name in session).
#### check_write_target
- [ ] `write_blocked` - Add the file to exploration first, or run additional exploration.
- [ ] `write_phase_blocked` - Write not allowed in phase {phase}
#### add_explored_files
- [ ] `phase_mismatch` - add_explored_files is only allowed in READY phase, current: {phase}.
- [ ] `no_files` - No files provided to add.
#### check_phase_necessity
- [ ] `semantic_needs_more_information_required` - needs_more_information field is required for SEMANTIC assessment
- [ ] `semantic_reason_required` - needs_more_information_reason field is required for SEMANTIC assessment
- [ ] `semantic_needs_more_information_type` - needs_more_information must be a boolean
- [ ] `semantic_reason_length` - needs_more_information_reason must be at least 10 characters
- [ ] `verification_has_unverified_required` - has_unverified_hypotheses field is required for VERIFICATION assessment
- [ ] `verification_reason_required` - has_unverified_hypotheses_reason field is required for VERIFICATION assessment
- [ ] `verification_has_unverified_type` - has_unverified_hypotheses must be a boolean
- [ ] `verification_reason_length` - has_unverified_hypotheses_reason must be at least 10 characters
- [ ] `impact_needs_analysis_required` - needs_impact_analysis field is required for IMPACT_ANALYSIS assessment
- [ ] `impact_reason_required` - needs_impact_analysis_reason field is required for IMPACT_ANALYSIS assessment
- [ ] `impact_needs_analysis_type` - needs_impact_analysis must be a boolean
- [ ] `impact_reason_length` - needs_impact_analysis_reason must be at least 10 characters
#### query
- [ ] `no_pattern` - No pattern specified
- [ ] `no_symbol` - No symbol specified
- [ ] `no_file_path` - No file_path specified
- [ ] `chromadb_not_available` - chromadb is not installed. Install with: pip install chromadb
- [ ] `unknown_tool` - Unknown tool: {tool}
- [ ] `semantic_search_failed` - Semantic search failed: {error}
#### start_session
- [ ] `branch_setup_failed` - (動的: setup_result.error)
- [ ] `branch_setup_exception` - (動的: 例外メッセージ)
---
### セッション関連メッセージ
- [ ] `checkpoint_recovery` - 前回のセッションのチェックポイントが見つかりました。復元する場合は get_session_status(discard_active=true, repo_path=".") を呼び出してください。新規セッションで続行する場合はそのまま submit_phase を呼んでください。
- [ ] `no_active_session` - No active session. Use start_session first.
- [ ] `no_active_session_short` - No active session.
- [ ] `checkpoint_restore_failed` - No active session. Checkpoint found but failed to restore.
- [ ] `invalid_data` - Failed to parse data JSON: {error}.
---
### 共通ヒント
ツールがフェーズでブロックされた時に表示。
- [ ] `phase_blocked_hint` - Use get_session_status to see current phase requirements.
---
### QUERY_FRAME 調査ヒント
QueryFrame フェーズでスロットが未特定の場合に表示。
- [ ] `target_feature_missing` - 対象となる機能やモジュールが特定できません。
- [ ] `observed_issue_missing` - 修正の動機となる『現状の問題』が不明です。
- [ ] `trigger_condition_missing` - 問題が発生する再現条件が特定されていません。
- [ ] `desired_action_missing` - 期待する修正方針が不明です。
---
### 警告メッセージ
- [ ] `truncation_warning` - レスポンスが 256KB を超えたため切り詰めました。パターンを絞り込んでください。
---
## 実装タスク
### メッセージ外部化
- [x] phase_contract.yml に `failures` セクションを追加（フェーズ別）
- [x] phase_contract.yml に `common_failures` セクションを追加
- [x] phase_contract.yml に `success` セクションを追加（フェーズ別）
- [x] phase_contract.yml に `tool_errors` セクションを追加
- [x] phase_contract.yml に `warnings` セクションを追加
- [x] `_load_full_phase_contract()` を追加し全セクションを読み込む
- [x] `_get_message(category, phase, key)` ヘルパー関数を追加
- [x] code_intel_server.py のハードコードメッセージを YAML 参照に置換
- [x] session.py のハードコードメッセージを YAML 参照に置換
- [x] テスト追加: 全メッセージが phase_contract.yml に存在することを検証
### 未使用メソッド削除（session.py）
code_intel_server.py から呼ばれておらず、テストでも使用されていないメソッドを削除。
- [x] `submit_exploration` を削除
- [x] `submit_semantic` を削除
- [x] `submit_for_review` を削除
- [x] `record_intervention_used` を削除
- [x] `reset_verification_failures` を削除
※ 以下は使用されているため残す:
- `submit_verification` (テストで使用)
- `submit_impact_analysis` (テストで使用)
- `submit_pre_commit_review` (code_intel_server.py で使用)
---
## メッセージ件数サマリ
| カテゴリ | 件数 |
|---------|------|
| 共通バリデーション | 6 |
| BRANCH_INTERVENTION | 2 |
| DOCUMENT_RESEARCH | 1 |
| EXPLORATION | 1 |
| SEMANTIC | 1 |
| VERIFICATION | 2 |
| IMPACT_ANALYSIS | 1 |
| READY | 12 |
| PRE_COMMIT | 4 |
| QUALITY_REVIEW | 2 |
| MERGE | 3 |
| VERIFY_INTERVENTION | 2 |
| 正常完了 | 5 |
| ツール固有エラー | 27 |
| セッション関連 | 5 |
| 共通ヒント | 1 |
| QUERY_FRAME 調査ヒント | 4 |
| 警告 | 1 |
| **合計** | **80** |
---
## 期待される効果
- LLM への全メッセージが一元管理される
- プロジェクト固有のメッセージにカスタマイズ可能
- コード変更なしでメッセージ調整可能
- 多言語対応が容易になる
