# v1.11 アップデート: submit_phase 統一 & タスクオーケストレーション
Release Date: 2026-02 (予定)
---
## 設計原則
1. **単一 submit**: 全フェーズの出口は `submit_phase` 一本。LLM が覚えるツール名は 1 つだけ。
2. **自己完結型レスポンス**: 毎回のレスポンスに「次に何をすべきか」「何を返すべきか」を含む。
3. **コンパクト耐性**: LLM のコンテキスト圧縮後も、サーバーが状態を保持し再指示可能。
```
現行の問題:
17 個の submit_* ツール → LLM のコンテキストを圧迫
check_phase_necessity → submit ではない
finalize_changes → submit ではない
merge_to_base → submit ではない
コンパクト後に LLM が「次にどの submit を呼ぶか」を忘れる
v1.11 で統一:
submit_phase 一本（サーバーがフェーズから期待ペイロードを判定）
レスポンスに expected_payload を含む（自己完結型）
get_session_status でいつでも現状復元可能
```
---
## Complete Flow (v1.11)
LLM 側前処理（サーバー呼び出しなし）:
- Flag Check: コマンドオプション解析
- Intent Classification: IMPLEMENT / MODIFY / INVESTIGATE / QUESTION
全ステップの出口は `submit_phase`（Step 1 のみ `start_session`）。
### セッション開始
| Step | Phase | LLM処理内容 | 備考 |
|------|-------|------------|------|
| 1 | — | Intent 判定（実装/調査）→ `start_session` で初期化 | |
| 2 | BRANCH_INTERVENTION | ユーザーに選択肢を提示 | stale ブランチ検出時のみ |
| 3 | DOCUMENT_RESEARCH | Sub-agent で設計文書調査 | |
| 4 | QUERY_FRAME | NL → 構造化スロット抽出 | |
### 探索フェーズ
| Step | Phase | LLM処理内容 | 備考 |
|------|-------|------------|------|
| 5 | EXPLORATION | code-intel ツールで探索 | |
| 6 | Q1 | SEMANTIC 必要性を評価 | サーバー判定で 7 をスキップ可 |
| 7 | SEMANTIC | semantic_search で追加情報収集 | Q1=false 時スキップ |
| 8 | Q2 | VERIFICATION 必要性を評価 | サーバー判定で 9 をスキップ可 |
| 9 | VERIFICATION | 仮説検証 | Q2=false 時スキップ |
| 10 | Q3 | IMPACT_ANALYSIS 必要性を評価 | サーバー判定で 11 をスキップ可 |
| 11 | IMPACT_ANALYSIS | 影響分析 | Q3=false 時スキップ / 調査: SESSION_COMPLETE |
### 実装フェーズ
| Step | Phase | LLM処理内容 | 備考 |
|------|-------|------------|------|
| 12 | READY | タスク分解・計画 | ブランチ作成 |
| 13 | READY | Edit/Write で実装 | タスク数分繰り返し (×N) |
| 14 | READY | 全タスク完了を確認 | 未完了時ブロック |
| 15 | POST_IMPL_VERIFY | verifier プロンプト実行 | fail 時 Step 12 差戻し |
| 16 | VERIFY_INTERVENTION | 介入プロンプト読み取り・実行 | タスク failure_count ≥ 3 時のみ / intervention_count ≥ 2 → user_escalation |
| 17 | PRE_COMMIT | review_changes でレビュー | |
| 18 | QUALITY_REVIEW | 品質チェック | quality_revert_count ≥ 3 → forced_completion |
| 19 | MERGE | — | |
### フェーズマトリクス
サーバーが各 submit_phase レスポンスで次フェーズを決定。LLM はフラグを知る必要がない。
| Step | Phase | 実装 | 調査 | --no-verify | --no-quality | --fast | --quick | --no-doc | -ni | 備考 |
|------|-------|:----:|:----:|:-----------:|:------------:|:------:|:-------:|:--------:|:---:|------|
| 1 | start_session | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | |
| 2 | BRANCH_INTERVENTION | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | stale 検出時のみ |
| 3 | DOCUMENT_RESEARCH | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | |
| 4 | QUERY_FRAME | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | |
| 5 | EXPLORATION | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | |
| 6 | Q1 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | |
| 7 | SEMANTIC | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | Q1=false 時スキップ |
| 8 | Q2 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | |
| 9 | VERIFICATION | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | Q2=false 時スキップ |
| 10 | Q3 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | |
| 11 | IMPACT_ANALYSIS | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | Q3=false 時スキップ |
| 12 | READY (計画) | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ブランチ作成 |
| 13 | READY (実装) | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ×N |
| 14 | READY (完了) | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 未完了時ブロック |
| 15 | POST_IMPL_VERIFY | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | fail→Step 12 差戻し |
| 16 | VERIFY_INTERVENTION | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ | ✅ | ❌ | タスク failure_count ≥ 3 時のみ |
| 17 | PRE_COMMIT | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | |
| 18 | QUALITY_REVIEW | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | |
| 19 | MERGE | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | |
**凡例**:
- **実装**: IMPLEMENT / MODIFY intent（デフォルト）
- **調査**: INVESTIGATE / QUESTION intent（`--only-explore` と同等、探索完了で SESSION_COMPLETE）
- **-ni**: `--no-intervention`（Step 16 VERIFY_INTERVENTION をスキップ）
- フラグ列は実装 intent に対する修飾。調査 intent では Step 12 以降が存在しない。
---
## submit_phase API
### 概要
```python
mcp__code-intel__submit_phase
data: { ... } # フェーズごとに異なる可変ペイロード
```
- LLM が呼ぶツールは `submit_phase` のみ
- サーバーが `SessionState.phase` から現在フェーズを特定し、ペイロードをバリデーション
- サーバーが次フェーズを決定してレスポンスを返す
### レスポンス形式（自己完結型）
全フェーズ共通のレスポンス構造:
```json
{
"phase": "EXPLORATION",
"step": 5,
"instruction": "code-intel ツールでコードベースを探索してください",
"expected_payload": {
"explored_files": "list[str]",
"findings": "list[str]"
},
"call": "submit_phase"
}
```
LLM はレスポンスの `instruction` に従い処理を実行し、`expected_payload` の形式で `submit_phase` を呼ぶ。
コンパクト後でも、直前のレスポンスが残っていれば次のアクションがわかる。
### フェーズ別ペイロード
| Step | Phase | LLM → サーバー (`data`) | サーバー判定 |
|------|-------|------------------------|------------|
| 2 | BRANCH_INTERVENTION | `{choice: "delete" \| "merge" \| "continue"}` | 処理実行 → 次フェーズ |
| 3 | DOCUMENT_RESEARCH | `{documents_reviewed: [...]}` | → 次フェーズ |
| 4 | QUERY_FRAME | `{action_type, target_symbols, scope, constraints}` | → 次フェーズ |
| 5 | EXPLORATION | `{explored_files: [...], findings: [...]}` | → 次フェーズ |
| 6 | Q1 | `{needs_more_information: bool, reason}` | true→SEMANTIC / false→Q2 |
| 7 | SEMANTIC | `{search_results: [...]}` | → 次フェーズ |
| 8 | Q2 | `{has_unverified_hypotheses: bool, reason}` | true→VERIFICATION / false→Q3 |
| 9 | VERIFICATION | `{hypotheses_verified: [...]}` | → 次フェーズ |
| 10 | Q3 | `{needs_impact_analysis: bool, reason}` | true→IMPACT_ANALYSIS / false(実装)→READY / false(調査)→SESSION_COMPLETE |
| 11 | IMPACT_ANALYSIS | `{impact_summary: {...}}` | 実装→READY / 調査→SESSION_COMPLETE |
| 12 | READY (計画) | `{tasks: [{id, description, status, failure_count?, revert_reason?}, ...]}` | タスク登録（冪等） |
| 13 | READY (実装) | `{task_id, summary}` | 順序チェック、×N |
| 14 | READY (完了) | `{}` | 全タスク完了チェック → 次フェーズ |
| 15 | POST_IMPL_VERIFY | `{passed: bool, failed_tasks?: list[task_id], details: str}` | pass→17 / fail→12（タスク別 failure_count ≥ 3 で→16） |
| 16 | VERIFY_INTERVENTION | `{prompt_used, action_taken}` | failure_count リセット → Step 12 差戻し / intervention_count ≥ 2 → user_escalation |
| 17 | PRE_COMMIT | `{reviewed_files: [...], commit_message}` | コミット実行 → 次フェーズ |
| 18 | QUALITY_REVIEW | `{quality_score, issues: [...]}` | 問題なし→MERGE / 問題あり→Step 12 差戻し / quality_revert_count ≥ 3 → forced_completion |
| 19 | MERGE | `{}` | マージ実行 → SESSION_COMPLETE |
**注**: `gate_level="full"` の場合、サーバーは Q1/Q2/Q3 の評価を無視し全フェーズ強制実行。
---
## コンパクト耐性設計
### 前提
```
LLM 会話 ← コンパクト対象（会話履歴が要約される）
↕ MCP プロトコル
MCP サーバー ← コンパクト対象外（SessionState をインメモリ保持）
```
### 4層の耐性
| 層 | 対策 | 効果 |
|----|------|------|
| ツール設計 | `submit_phase` 一本 | 「何を呼ぶか」を忘れない |
| レスポンス設計 | `expected_payload` 付き | 「何を返すか」を忘れない |
| リカバリ | `get_session_status` | 完全復元手段 |
| 防御 | ペイロード不整合検知 | サイレント障害防止 |
### get_session_status によるリカバリ
コンパクト後に LLM が状態を見失った場合:
```json
// get_session_status レスポンス
{
"session_id": "...",
"phase": "VERIFICATION",
"step": 9,
"completed_steps": [1, 2, 3, 4, 5, 6, 7, 8],
"instruction": "仮説検証を実施し submit_phase を呼んでください",
"expected_payload": {
"hypotheses_verified": "list[{hypothesis, result, evidence}]"
},
"task_progress": null
}
```
### ペイロード不整合検知
LLM がフェーズと無関係なペイロードを送った場合:
```json
// サーバーレスポンス
{
"error": "payload_mismatch",
"current_phase": "VERIFICATION",
"step": 9,
"message": "現在は VERIFICATION フェーズです",
"instruction": "仮説検証を実施し submit_phase を呼んでください",
"expected_payload": {
"hypotheses_verified": "list[{hypothesis, result, evidence}]"
}
}
```
---
## タスクオーケストレーション（READY 内部）
READY フェーズは内部的に 3 サブステップ（計画 → 実装 → 完了）を持つ。
全て `submit_phase` で送信し、サーバーが内部状態で判別する。
### Step 12: タスク計画
**分割指針**: サーバーは `.code-intel/task_planning.md` を読み込み、instruction に含める。ユーザーがプロジェクト固有の分割方針にカスタマイズ可能。
デフォルト内容:
- 探索フェーズで特定した全変更対象を漏れなくタスク化すること
- 実装漏れを防ぐための分割であり、粒度は問わない
- 実装後の検証（テスト実行等）はタスクに含めない（POST_IMPL_VERIFY で別途実施）
タスクモデル: `{id, description, status, failure_count?, revert_reason?}`
```python
# 初回
submit_phase(data={
"tasks": [
{"id": "task_1", "description": "CSSコンポーネントユーティリティ化", "status": "pending"},
{"id": "task_2", "description": "@themeトークン化", "status": "pending"},
{"id": "task_3", "description": "未使用CSSクリーンアップ", "status": "pending"}
]
})
# 差戻し時（完了済み + 修正タスクの完全なリスト）
submit_phase(data={
"tasks": [
{"id": "task_1", "description": "CSSコンポーネントユーティリティ化", "status": "completed"},
{"id": "task_2", "description": "@themeトークン化", "status": "completed"},
{"id": "task_3", "description": "未使用CSSクリーンアップ", "status": "completed"},
{"id": "fix_1", "description": "テスト失敗箇所の修正", "status": "pending",
"failure_count": 1, "revert_reason": "テストX失敗"}
]
})
```
**冪等設計**: Step 12 は常に完全なタスクリストを受け取る。初回/差戻しの区別はサーバー側で不要。同じペイロードを再送しても同じ結果になる。
**バリデーション**: READY 以外 → エラー / 空リスト → エラー / pending タスクなし → エラー / ID 重複 → エラー
### Step 13: タスク完了報告 (×N)
```python
submit_phase(data={
"task_id": "task_1",
"summary": "変換完了"
})
```
**バリデーション**: 未登録 → エラー / 不明ID → エラー / 完了済み → エラー / 順序外 → エラー
**レスポンス（次あり）**: `{progress, next_task, instruction, expected_payload}`
**レスポンス（全完了）**: `{all_complete: true, instruction: "submit_phase を空で呼んでください"}`
### Step 14: 実装完了
```python
submit_phase(data={})
```
**サーバー処理**:
```
1. タスク完了チェック（IMPLEMENT/MODIFY のみ）
- 未登録 → ブロック
- 未完了 → ブロック
2. 次フェーズ決定（セッションフラグに基づく）:
--no-verify + --quick → session_complete
--no-verify → PRE_COMMIT
default → POST_IMPL_VERIFY
```
### Step 15: POST_IMPL_VERIFY
```python
submit_phase(data={
"passed": true,
"details": "全テスト通過"
})
```
**サーバー処理**:
```
passed=true:
--quick → session_complete
default → PRE_COMMIT
passed=false:
failed_tasks の failure_count をインクリメント
いずれかのタスクで failure_count >= 3:
-ni / --quick → Step 12 (READY) に差戻し（介入スキップ）
default → Step 16 (VERIFY_INTERVENTION) へ
それ以外 → Step 12 (READY) に差戻し
```
### 差戻し時の動作
POST_IMPL_VERIFY / VERIFY_INTERVENTION / QUALITY_REVIEW から Step 12 に差し戻された場合:
```
1. サーバー: 差戻し理由 + 既存タスク一覧を instruction に含める
2. LLM: 既存タスク（completed）+ 修正タスク（pending）の完全なリストを submit_phase で送信
3. サーバー: リストをそのまま受理（冪等）
4. LLM: pending タスクのみ実装（Step 13 ×N）
5. LLM: 全タスク完了を確認（Step 14）
6. → Step 15 POST_IMPL_VERIFY へ再進行
```
### 安全弁（無限ループ防止）
LLM はコンパクト後にループを認識できないため、全てのループ制限はサーバー側で強制する。
**サーバー管理カウンター**:
```python
class SessionState:
intervention_count: int = 0 # VERIFY_INTERVENTION の実行回数
quality_revert_count: int = 0 # QUALITY_REVIEW からの差戻し回数
# failure_count はタスク別（Task.failure_count）
```
**ループパスと制限**:
| ループパス | トリガー | 制限 | 超過時の動作 |
|-----------|---------|------|-------------|
| POST_IMPL_VERIFY → Step 12 | 検証失敗 | タスク failure_count ≥ 3 | → VERIFY_INTERVENTION |
| VERIFY_INTERVENTION → Step 12 | 介入実行後 | intervention_count ≥ 2 | → user_escalation（instruction で LLM に AskUserQuestion を指示） |
| QUALITY_REVIEW → Step 12 | 品質問題あり | quality_revert_count ≥ 3 | → forced_completion（warning 付きで MERGE へ遷移） |
**user_escalation**: サーバーが instruction に「ユーザーに相談してください」を含める。LLM は AskUserQuestion で判断を委ねる。
**forced_completion**: サーバーが品質問題を残したまま MERGE へ遷移。レスポンスに `warning: "品質問題が未解決のまま完了"` を含める。
**--clean の拡張**:
```
--clean:
既存: stale ブランチ削除
追加: SessionState リセット（全カウンター初期化、状態不整合からの回復）
```
---
## 廃止 API
| 旧 API | 理由 | 代替 |
|--------|------|------|
| `check_phase_necessity` | submit_phase に統合 | `submit_phase` (Q1/Q2/Q3 ペイロード) |
| `set_query_frame` | submit_phase に統合 | `submit_phase` (QUERY_FRAME ペイロード) |
| `begin_phase_gate` | submit_phase に統合 | `submit_phase` (BRANCH_INTERVENTION ペイロード) |
| `complete_task` | submit_phase に統合 | `submit_phase` (READY 実装ペイロード) |
| `submit_for_review` | submit_phase に統合 | `submit_phase` (READY 完了ペイロード) |
| `submit_exploration` | submit_phase に統合 | `submit_phase` (EXPLORATION ペイロード) |
| `submit_semantic` | submit_phase に統合 | `submit_phase` (SEMANTIC ペイロード) |
| `submit_verification` | submit_phase に統合 | `submit_phase` (VERIFICATION ペイロード) |
| `submit_impact_analysis` | submit_phase に統合 | `submit_phase` (IMPACT_ANALYSIS ペイロード) |
| `submit_quality_review` | submit_phase に統合 | `submit_phase` (QUALITY_REVIEW ペイロード) |
| `finalize_changes` | submit_phase に統合 | `submit_phase` (PRE_COMMIT ペイロード) |
| `merge_to_base` | submit_phase に統合 | `submit_phase` (MERGE ペイロード) |
| `record_verification_failure` | submit_phase に統合 | `submit_phase` (POST_IMPL_VERIFY: passed=false) |
| `record_intervention_used` | submit_phase に統合 | `submit_phase` (VERIFY_INTERVENTION ペイロード) |
| `get_intervention_status` | サーバー内部で自動判定 | 不要（failure_count はサーバーが管理） |
---
## 背景
### 問題1: Submit-per-Phase の欠落
探索フェーズは `submit_*` で統一されているが、他のフェーズには:
- READY の出口にタスク完了チェックなし
- POST_IMPL_VERIFY が Phase enum に不在
- `check_phase_necessity` が submit パターンに不統一
- `set_query_frame`, `begin_phase_gate`, `finalize_changes`, `merge_to_base`, `complete_task` が submit 命名でない
### 問題2: LLM のタスクスキップ
- 「十分性判断」が早い: 主要タスク完了時点で残りを省略
- Opus でも Sonnet でも発生（構造的問題）
### 問題3: プロンプト依存
- TodoWrite: LLM が無視可能
- check_task_completion (旧設計): voluntary API = honor system
- サーバーが強制できる仕組みがない
### 問題4: コンテキスト圧迫
- 17 個の submit_* ツール定義がコンテキストを消費
- コンパクト後に LLM が「次にどの submit を呼ぶか」を忘れる
- ツール数削減がコンパクト耐性に直結
---
## Phase Enum の変更
```python
class Phase(Enum):
BRANCH_INTERVENTION = auto() # v1.11 新規 (Step 2: stale ブランチ介入)
DOCUMENT_RESEARCH = auto() # v1.11 新規
QUERY_FRAME = auto() # v1.11 新規
EXPLORATION = auto()
Q1 = auto() # v1.11 新規
SEMANTIC = auto()
Q2 = auto() # v1.11 新規
VERIFICATION = auto()
Q3 = auto() # v1.11 新規
IMPACT_ANALYSIS = auto()
READY = auto()
POST_IMPL_VERIFY = auto() # v1.11 新規
VERIFY_INTERVENTION = auto() # v1.11 新規 (Step 16: 3回失敗介入)
PRE_COMMIT = auto()
QUALITY_REVIEW = auto()
MERGE = auto() # v1.11 新規
```
---
## 変更対象ファイル
| ファイル | 変更内容 | 影響度 |
|----------|----------|--------|
| `tools/session.py` | Phase enum 拡張、タスク管理フィールド・メソッド追加、expected_payload 生成 | 高 |
| `code_intel_server.py` | 旧 submit_* 全廃止、`submit_phase` ハンドラ新設（内部で Phase ディスパッチ）、レスポンス形式統一 | 高 |
| `.claude/commands/code.md` | 全面改訂: `submit_phase` 単一ツール、自己完結型レスポンス、コンパクト耐性 | 高 |
---
## テスト計画
```python
class TestSubmitPhaseDispatch:
"""submit_phase のフェーズディスパッチテスト"""
def test_document_research_payload(self):
"""DOCUMENT_RESEARCH ペイロードを正しく処理"""
def test_query_frame_payload(self):
"""QUERY_FRAME ペイロードを正しく処理"""
def test_exploration_payload(self):
"""EXPLORATION ペイロードを正しく処理"""
def test_payload_mismatch_returns_error(self):
"""フェーズと無関係なペイロード → エラー + 再指示"""
def test_response_contains_expected_payload(self):
"""全レスポンスに expected_payload が含まれる"""
class TestQGates:
"""Q1/Q2/Q3 ゲートテスト（submit_phase 経由）"""
def test_q1_true_enters_semantic(self):
"""submit_phase({needs_more_information: true}) → SEMANTIC"""
def test_q1_false_proceeds_to_q2(self):
"""submit_phase({needs_more_information: false}) → Q2"""
def test_q2_true_enters_verification(self):
"""submit_phase({has_unverified_hypotheses: true}) → VERIFICATION"""
def test_q2_false_proceeds_to_q3(self):
"""submit_phase({has_unverified_hypotheses: false}) → Q3"""
def test_q3_true_enters_impact(self):
"""submit_phase({needs_impact_analysis: true}) → IMPACT_ANALYSIS"""
def test_q3_false_proceeds_to_ready(self):
"""submit_phase({needs_impact_analysis: false}) → READY"""
def test_gate_level_full_forces_all(self):
"""gate_level=full → 全フェーズ強制実行"""
class TestTaskOrchestration:
"""READY フェーズのタスク管理テスト（submit_phase 経由）"""
def test_register_tasks(self):
"""submit_phase({tasks: [...]}) でタスク登録"""
def test_complete_task_in_order(self):
"""submit_phase({task_id: ...}) で順序通り完了"""
def test_reject_wrong_order(self):
"""順序外の task_id → エラー"""
def test_block_incomplete_implementation(self):
"""未完了タスクあり → submit_phase({}) をブロック"""
def test_allow_complete_implementation(self):
"""全タスク完了 → submit_phase({}) で次フェーズへ"""
class TestPostImplVerify:
def test_passed_to_pre_commit(self): ...
def test_passed_quick_to_complete(self): ...
def test_failed_to_ready(self): ...
def test_intervention_after_3(self): ...
class TestBranchIntervention:
"""Step 2: stale ブランチ介入テスト"""
def test_stale_branch_detected(self):
"""stale ブランチ検出時に BRANCH_INTERVENTION へ遷移"""
def test_no_stale_branch_skips(self):
"""stale ブランチなし → DOCUMENT_RESEARCH へスキップ"""
def test_choice_delete(self):
"""choice=delete → ブランチ削除 → 次フェーズ"""
def test_choice_merge(self):
"""choice=merge → ブランチマージ → 次フェーズ"""
def test_choice_continue(self):
"""choice=continue → そのまま次フェーズ"""
class TestVerifyIntervention:
"""Step 16: 検証失敗介入テスト"""
def test_task_failure_count_triggers_intervention(self):
"""タスク failure_count ≥ 3 → VERIFY_INTERVENTION へ遷移"""
def test_intervention_resets_failure_count(self):
"""介入後 failure_count リセット → Step 12 差戻し"""
def test_no_intervention_flag_skips(self):
"""--no-intervention → Step 16 スキップ"""
def test_user_escalation_after_2_interventions(self):
"""intervention_count ≥ 2 → user_escalation 指示"""
class TestLoopSafetyValves:
"""無限ループ防止テスト"""
def test_quality_revert_forced_completion(self):
"""quality_revert_count ≥ 3 → forced_completion（warning 付き MERGE）"""
def test_quality_revert_count_increments(self):
"""QUALITY_REVIEW 差戻しごとに quality_revert_count がインクリメント"""
def test_intervention_count_increments(self):
"""VERIFY_INTERVENTION 実行ごとに intervention_count がインクリメント"""
def test_clean_resets_session_state(self):
"""--clean で SessionState 全カウンターがリセット"""
class TestCompactionResilience:
"""コンパクト耐性テスト"""
def test_get_session_status_returns_expected_payload(self):
"""get_session_status に expected_payload が含まれる"""
def test_payload_mismatch_provides_recovery(self):
"""不整合ペイロード → 現在フェーズの再指示"""
class TestEndToEnd:
def test_default_full_flow(self): ...
def test_quick_flow(self): ...
def test_quick_no_verify_flow(self): ...
def test_fast_flow(self): ...
def test_no_verify_flow(self): ...
def test_investigation_flow(self):
"""INVESTIGATE intent → 探索完了で SESSION_COMPLETE"""
def test_exploration_all_skip_to_ready(self): ...
def test_verification_failure_revert_and_retry(self): ...
def test_quality_review_revert_flow(self):
"""QUALITY_REVIEW 問題あり → Step 12 差戻し → 修正 → 再チェック"""
def test_verify_intervention_flow(self):
"""タスク failure_count ≥ 3 → VERIFY_INTERVENTION → Step 12"""
```
---
## code.md 改定方針
### 設計原則
v1.11 の自己完結型レスポンスにより、サーバーが動的に提供する情報は code.md に記載しない（二重管理回避）。
ただし、MCP はリクエスト/レスポンスモデルのため、LLM が何も呼ばなくなった場合にサーバーからプッシュする手段がない。
code.md はこの「LLM が停止するケース」に対する**唯一のセーフティネット**として機能する。
### 残す / 削る 基準
| 内容 | サーバーが教えられる？ | code.md に必要？ | 理由 |
|------|:-------------------:|:---------------:|------|
| 次に何を submit するか | ✅ expected_payload | ❌ | サーバーが毎回指示 |
| ペイロードの形式 | ✅ expected_payload | ❌ | サーバーが毎回提示 |
| フェーズ遷移先 | ✅ サーバー判定 | ❌ | サーバーが自動決定 |
| 「submit_phase を呼べ」 | ❌ プッシュ不可 | ✅ | LLM 停止時の唯一の復帰手段 |
| 「READY 前に Edit 禁止」 | △ ブロックはする | ✅ | ブロック理由の文脈が必要 |
| 「get_session_status で復帰せよ」 | ❌ プッシュ不可 | ✅ | コンパクト後の復帰手順 |
| フラグの解析方法 | ❌ Step 1 は LLM 側 | ✅ | サーバー呼び出し前の処理 |
| Intent 分類 | ❌ Step 1 は LLM 側 | ✅ | サーバー呼び出し前の処理 |
| 全体フロー概要 | △ 部分的 | ✅ | 概要レベルのみ |
| 探索での並列実行 | ❌ 実行方法はサーバー管轄外 | ✅ | LLM の実行最適化 |
### 改定後の構成（約 400-500 行）
```
1. CRITICAL RULES（コンパクト耐性）
- submit_phase を呼び続けろ
- READY 前の Edit/Write 禁止
- 迷ったら get_session_status
2. ツール概要
- start_session: セッション開始
- submit_phase: 全フェーズの出口（サーバーの instruction に従う）
- get_session_status: 状態復帰
3. フラグ解析（Step 1 前処理）
- --quick, --fast, --no-verify 等のフラグ一覧と動作
4. Intent 分類（Step 1）
- IMPLEMENT / MODIFY / INVESTIGATE / QUESTION
5. 全体フロー概要（19 Step 一覧表のみ）
- 各ステップの詳細ペイロードは記載しない（サーバーが教える）
6. 探索フェーズガイド
- 並列実行（search_text, find_definitions 等）
- code-intel ツールの使い方
7. コンパクト回復手順
- get_session_status → instruction に従う → submit_phase
```
### 削除対象（サーバーが動的に提供）
- 各ステップの詳細ペイロード仕様・バリデーション仕様
- submit_* ツール呼び出し例（submit_exploration, submit_semantic 等）
- レスポンス JSON 例
- ☐☑ チェックボックス管理
- TodoWrite タスク登録手順（サーバー強制のタスクオーケストレーションに置換）
- 介入システムの詳細手順（VERIFY_INTERVENTION フェーズとして自動制御）
---
## 今後の拡張可能性
- **タスク依存関係**: task_2 は task_1 完了後にのみ開始可能
- ~~**タスク追加 API**~~: 冪等な完全リスト送信設計により不要（差戻し時も完全リストを送信）
- **タスク自動生成**: EXPLORATION 結果からタスクリストを自動生成
- **get_session_status 統合**: タスク進捗 + expected_payload を含める
