# v1.15 LLM Message Externalization
Release Date: 2026-02-03
## Purpose
- Consolidate all messages to LLM (errors, success, instructions) in `phase_contract.yml`, separating from code
- Enable message customization
- Eliminate dual management (code hardcoding + YAML)
---
## Design
### YAML Structure
```yaml
phases:
EXPLORATION:
instruction: ...
expected_payload: ...
failures:
empty_result:
error: payload_mismatch
message: "Exploration result is empty. Use code-intel tools to explore and include explored_files and findings in your submission"
success:
complete:
message: "Exploration complete. Ending session."
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}."
```
### Failure Case List
#### Common Validation (Applied to All Phases)
- [ ] `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}. Branch operation failed. Notify user of failure content and request manual resolution.
#### DOCUMENT_RESEARCH
- [ ] `empty_documents` - Read the specified documents and include results in `documents_reviewed`, then resubmit
#### EXPLORATION
- [ ] `empty_result` - Exploration result is empty. Use code-intel tools to explore and include `explored_files` and `findings` in your submission
#### SEMANTIC
- [ ] `empty_search_results` - Search results are empty. Execute `semantic_search` and include `search_results` in your submission
#### VERIFICATION
- [ ] `empty_hypotheses` - Verification results are empty. Verify hypotheses one by one and include `hypotheses_verified` in your submission
- [ ] `result_false_exists` - Hypotheses with result=false exist. Re-verify until all hypotheses have result=true and resubmit `hypotheses_verified`
#### IMPACT_ANALYSIS
- [ ] `empty_impact_summary` - Impact analysis results are empty. Execute `analyze_impact` and include `impact_summary` in your submission
#### READY
- [ ] `branch_creation_failed` [user_intervention] - Task branch creation failed. Inform user of situation and request one of: checking working tree with `git status`, manual branch creation, or session reset with `/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] - Reached commit phase without task branch created. Inform user of situation and request branch state check with `git branch` or session reset with `/code --clean`
- [ ] `review_failed` - Files judged as discard are missing reason. Add reason to `reviewed_files` and resubmit
- [ ] `finalize_failed` [user_intervention] - git commit failed. Inform user of situation and request checking pre-commit hook error output or `git status` for manual problem resolution. After resolution, execute submit_phase again
#### QUALITY_REVIEW
- [ ] `commit_execution_failed` [user_intervention] - Commit execution after quality review failed. Inform user of situation and request checking working tree with `git status` for manual problem resolution
- [ ] `quality_forced_completion` - Completed with unresolved quality issues
#### MERGE
- [ ] `quality_review_required` - QUALITY_REVIEW not completed.
- [ ] `branch_manager_not_found` [user_intervention] - Branch management information is inconsistent. Inform user of situation and request state check with `git branch` or session reset with `/code --clean`
- [ ] `merge_failed` [user_intervention] - Branch merge failed. Inform user of situation and request checking conflicts with `git status` for manual resolution. After resolution, execute submit_phase again
#### VERIFY_INTERVENTION
- [ ] `user_escalation` - Follow procedures in .code-intel/user_escalation.md to request help from user. Specify the procedure document name/path used when submitting via submit_phase.
- [ ] `escalation_count` - Intervention executed {count} times. Please consult with user.
---
### Success Messages
Messages for session end or phase completion.
#### Q3 / IMPACT_ANALYSIS (Investigation Complete)
- [ ] `investigation_complete` - Exploration complete. Ending session.
#### READY (Task Complete)
- [ ] `session_complete_no_verify_quick` - All tasks complete. Session ended (--no-verify + --quick).
#### POST_IMPL_VERIFY
- [ ] `session_complete_quick` - Verification passed. Session ended (--quick).
#### MERGE
- [ ] `no_task_branch_complete` - No task branch. Session complete.
- [ ] `merge_success` - Merged {from_branch} → {to_branch}. Session complete.
---
### Tool-Specific Errors
Errors occurring in tools other than 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` - (dynamic: setup_result.error)
- [ ] `branch_setup_exception` - (dynamic: exception message)
---
### Session-Related Messages
- [ ] `checkpoint_recovery` - Previous session checkpoint found. To restore, call get_session_status(discard_active=true, repo_path="."). To continue with new session, call submit_phase as-is.
- [ ] `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}.
---
### Common Hints
Displayed when tool is blocked by phase.
- [ ] `phase_blocked_hint` - Use get_session_status to see current phase requirements.
---
### QUERY_FRAME Investigation Hints
Displayed when slots are unidentified in QueryFrame phase.
- [ ] `target_feature_missing` - Target feature or module cannot be identified.
- [ ] `observed_issue_missing` - The 'current problem' motivating the fix is unclear.
- [ ] `trigger_condition_missing` - Reproduction conditions for the issue are not identified.
- [ ] `desired_action_missing` - Expected fix approach is unclear.
---
### Warning Messages
- [ ] `truncation_warning` - Response exceeded 256KB and was truncated. Please refine your pattern.
---
## Implementation Tasks
### Message Externalization
- [x] Add `failures` section to phase_contract.yml (per phase)
- [x] Add `common_failures` section to phase_contract.yml
- [x] Add `success` section to phase_contract.yml (per phase)
- [x] Add `tool_errors` section to phase_contract.yml
- [x] Add `warnings` section to phase_contract.yml
- [x] Add `_load_full_phase_contract()` to load all sections
- [x] Add `_get_message(category, phase, key)` helper function
- [x] Replace hardcoded messages in code_intel_server.py with YAML references
- [x] Replace hardcoded messages in session.py with YAML references
- [x] Add test: Verify all messages exist in phase_contract.yml
### Unused Method Removal (session.py)
Remove methods not called from code_intel_server.py and not used in tests.
- [x] Remove `submit_exploration`
- [x] Remove `submit_semantic`
- [x] Remove `submit_for_review`
- [x] Remove `record_intervention_used`
- [x] Remove `reset_verification_failures`
※ Keep the following as they are used:
- `submit_verification` (used in tests)
- `submit_impact_analysis` (used in tests)
- `submit_pre_commit_review` (used in code_intel_server.py)
---
## Message Count Summary
| Category | Count |
|----------|-------|
| Common Validation | 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 |
| Success | 5 |
| Tool-Specific Errors | 27 |
| Session-Related | 5 |
| Common Hints | 1 |
| QUERY_FRAME Investigation Hints | 4 |
| Warnings | 1 |
| **Total** | **80** |
---
## Expected Benefits
- All messages to LLM are centrally managed
- Customizable to project-specific messages
- Message adjustments possible without code changes
- Multi-language support becomes easier
