# v1.6 アップデート
Release Date: 2026-01
## 概要
v1.6 ではブランチライフサイクル管理を強化。残存ブランチの警告、失敗時の自動削除、および `start_session` の分割により、準備フェーズとフェーズゲートの責務を明確に分離。
## 背景
v1.2 で Git ブランチによるゴミ分離を導入したが、以下の問題が残っていた：
| 問題 | 影響 |
|------|------|
| 残存ブランチの警告なし | main にいると `llm_task_*` が残っていても気づかない |
| 失敗時ブランチ放置 | 失敗検出しても該当ブランチが削除されない |
| `start_session` の責務混在 | 準備（session/context）とフェーズゲート（branch/phase）が混在 |
## 設計原則
### 責務分離
| レイヤー | 責務 | 制御主体 |
|---------|------|---------|
| 準備フェーズ | セッション初期化、コンテキスト取得 | Skill |
| フェーズゲート | ブランチ作成、フェーズ遷移 | Server |
| ユーザー介入 | 残存ブランチの処理判断 | Skill（ユーザーに委譲） |
### 状態遷移の明確化
```
[準備完了] → begin_phase_gate → [残存ブランチあり?]
│
┌───────────────────────┼───────────────────────┐
↓ ↓ ↓
[削除を選択] [マージを選択] [続行を選択]
│ │ │
↓ ↓ ↓
cleanup_stale_sessions merge_to_base 残存ブランチを放置
│ │ │
↓ ↓ ↓
begin_phase_gate begin_phase_gate [現在 llm_task_* 上?]
（新規ブランチ作成） （新規ブランチ作成） │
│ │ Yes ─┴─ No
│ │ │ │
│ │ 継続 新規作成
│ │ │ │
└───────────────────────┴───────────┴───────┘
│
↓
[EXPLORATION]
```
---
## 新機能
### 1. 残存ブランチ警告（ユーザー介入）
`begin_phase_gate` 呼び出し時に `llm_task_*` ブランチが残っている場合、**ブランチ作成をブロック**し、ユーザー判断を要求。
#### 判定ロジック
```python
def should_warn_stale_branches():
current = get_current_branch()
task_branches = list_branches("llm_task_*")
# 条件1: 現在タスクブランチ上でない
if current.startswith("llm_task_"):
return False
# 条件2: タスクブランチが1つ以上存在
if len(task_branches) == 0:
return False
return True
```
#### レスポンス設計
**残存ブランチ検出時（ブロック）:**
```json
{
"success": false,
"error": "stale_branches_detected",
"stale_branches": {
"branches": [
{
"name": "llm_task_session_xyz_from_main",
"base_branch": "main",
"has_changes": true,
"commit_count": 3
}
],
"message": "Previous task branches exist. User action required."
},
"recovery_options": {
"delete": "cleanup_stale_sessions を実行後、begin_phase_gate を再実行",
"merge": "merge_to_base を実行後、begin_phase_gate を再実行",
"continue": "begin_phase_gate(resume_current=true) で残存ブランチを放置して続行"
}
}
```
**正常時:**
```json
{
"success": true,
"phase": "EXPLORATION",
"branch": {
"created": true,
"name": "llm_task_abc123_from_main",
"base_branch": "main"
}
}
```
#### Skill の動作
1. `begin_phase_gate` を呼び出す
2. `success: false` かつ `error: "stale_branches_detected"` の場合:
- AskUserQuestion で3択を提示
- ユーザーの選択に応じた処理を実行
- `begin_phase_gate` を再実行
3. `success: true` なら続行
```
AskUserQuestion:
question: "前回のタスクブランチが残っています。どうしますか？"
options:
- label: "削除して続行"
description: "前回の変更を破棄し、クリーンな状態で開始"
- label: "マージして続行"
description: "前回の変更を現在のブランチに取り込んでから開始"
- label: "そのまま続行"
description: "前回のブランチに戻って作業を継続"
```
#### 3択の動作
| 選択 | 残存ブランチ | 新規ブランチ |
|------|-------------|-------------|
| 削除して続行 | 全削除 | 作成 |
| マージして続行 | base にマージ後削除 | 作成 |
| そのまま続行 | **放置** | 状況による（下記参照） |
**「そのまま続行」の詳細:**
| 現在のブランチ | 動作 |
|---------------|------|
| `llm_task_*` 上 | そのまま作業継続（新規ブランチ作成しない） |
| `main` / `dev` 等 | 残存ブランチを放置して新規ブランチ作成 |
### 2. 失敗時ブランチ自動削除
`record_outcome(outcome="failure")` 時に該当セッションのブランチを自動削除。
#### 設計根拠
失敗したセッションの変更は価値がない（むしろ有害）ため、自動的に破棄すべき。
#### ワークフロー
```
前回セッションが失敗と判定
↓
record_outcome(outcome="failure", session_id="previous_session")
↓
1. OutcomeLog に記録
2. 該当ブランチを特定: llm_task_{session_id}_from_{base}
3. ブランチを削除（強制）
↓
レスポンスで削除結果を通知
```
#### レスポンス
```json
{
"success": true,
"outcome": "failure",
"recorded": true,
"branch_cleanup": {
"attempted": true,
"deleted": "llm_task_session_xyz_from_main",
"message": "Failed session branch deleted automatically."
}
}
```
#### ブランチが見つからない場合
```json
{
"success": true,
"outcome": "failure",
"recorded": true,
"branch_cleanup": {
"attempted": true,
"deleted": null,
"message": "No branch found for session (may have been deleted already)."
}
}
```
### 3. start_session 分割
`start_session` を準備とフェーズゲート開始に分離。
#### Before (v1.5)
```
start_session
├── session_id 生成 ← 準備
├── project_rules 取得 ← 準備
├── ChromaDB 同期 ← 準備
├── Git ブランチ作成 ← フェーズゲート（問題）
└── Phase.EXPLORATION ← フェーズゲート（問題）
```
#### After (v1.6)
```
start_session（準備フェーズ）
├── session_id 生成
├── project_rules 取得
└── ChromaDB 同期
begin_phase_gate（フェーズゲート開始）
├── 残存ブランチチェック → ブロック or 続行
├── Git ブランチ作成
└── Phase.EXPLORATION 設定
```
---
## 新ツール
### begin_phase_gate
フェーズゲートを開始し、ブランチを作成する。
#### パラメータ
| パラメータ | 型 | 必須 | デフォルト | 説明 |
|-----------|-----|------|-----------|------|
| session_id | string | Yes | - | start_session で取得した session_id |
| skip_branch | bool | No | false | true: ブランチ作成をスキップ（--quick 用） |
| resume_current | bool | No | false | true: 今いるブランチで続行（「そのまま続行」用） |
#### skip_branch=true の動作
```json
{
"success": true,
"phase": "READY",
"branch": {
"created": false,
"reason": "skip_branch=true (quick mode)"
}
}
```
**注意:** `skip_branch=true` の場合でも残存ブランチチェックは行う。
#### resume_current=true の動作
残存ブランチを放置して続行。現在のブランチによって動作が変わる。
**現在 `llm_task_*` 上の場合:**
```json
{
"success": true,
"phase": "EXPLORATION",
"branch": {
"created": false,
"resumed": true,
"name": "llm_task_session_xyz_from_main",
"reason": "resume_current=true (continuing on current task branch)"
}
}
```
**現在 `main` / `dev` 等の場合:**
```json
{
"success": true,
"phase": "EXPLORATION",
"branch": {
"created": true,
"name": "llm_task_abc123_from_main",
"base_branch": "main",
"stale_branches_ignored": ["llm_task_session_xyz_from_main"]
}
}
```
**動作まとめ:**
- `llm_task_*` 上 → そのまま継続、新規ブランチ作成しない
- `main` / `dev` 等 → 残存ブランチを放置、新規ブランチ作成
---
## 変更されるツール
### start_session
| 項目 | v1.5 | v1.6 |
|------|------|------|
| ブランチ作成 | 行う | **行わない** |
| Phase 設定 | EXPLORATION | **None（未設定）** |
| enable_branch | パラメータあり | **削除** |
#### v1.6 レスポンス
```json
{
"success": true,
"session_id": "abc123",
"essential_context": {
"project_rules": {...}
},
"chromadb": {
"synced": true
},
"next_step": "Call begin_phase_gate to start phase gates"
}
```
### record_outcome
| 項目 | v1.5 | v1.6 |
|------|------|------|
| outcome="failure" | 記録のみ | **記録 + ブランチ削除** |
| outcome="success" | 記録のみ | 変更なし |
---
## フロー変更
### Before (v1.5)
```
1. 準備フェーズ（Skill 制御）
Flag Check → Failure Check → Intent → Session Start（branch含む）
→ DOCUMENT_RESEARCH → QueryFrame
2. フェーズゲート（Server 強制）
EXPLORATION → ... → QUALITY_REVIEW
```
### After (v1.6)
```
1. 準備フェーズ（Skill 制御）
Flag Check → Failure Check → Intent → Session Start（branchなし）
→ DOCUMENT_RESEARCH → QueryFrame
2. フェーズゲート開始（Server + Skill 協調）
begin_phase_gate → [残存ブランチあり?] → [ユーザー介入] → 再実行
3. フェーズゲート（Server 強制）
EXPLORATION → ... → QUALITY_REVIEW
```
---
## Skill プロンプト変更
### Step 2: Session Start（変更）
```markdown
## Step 2: Session Start
**準備フェーズのみ。ブランチ作成はフェーズゲートで行う。**
mcp__code-intel__start_session
intent: "IMPLEMENT"
query: "user's original request"
```
### Step 5: Begin Phase Gate（新規）
```markdown
## Step 5: Begin Phase Gate
**残存ブランチがあればユーザーに確認。**
mcp__code-intel__begin_phase_gate
session_id: "session_id from step 2"
skip_branch: false # --quick の場合 true
**`success: false` かつ `error: "stale_branches_detected"` の場合:**
AskUserQuestion ツールで確認:
question: "前回のタスクブランチが残っています。どうしますか？"
options:
- "削除して続行" → cleanup_stale_sessions 実行後、begin_phase_gate 再実行
- "マージして続行" → merge_to_base 実行後、begin_phase_gate 再実行
- "そのまま続行" → begin_phase_gate(resume_current=true) を実行
```
---
## 設定
`.code-intel/context.yml`:
```yaml
branch_lifecycle:
warn_stale_branches: true # 残存ブランチ警告を有効化（デフォルト: true）
auto_delete_on_failure: true # 失敗時に自動削除（デフォルト: true）
```
---
## 破壊的変更
| 変更 | 影響 | 対応 |
|------|------|------|
| `start_session` の `enable_branch` 削除 | パラメータエラー | パラメータを削除 |
| `start_session` がブランチを作成しない | Phase が None | `begin_phase_gate` を呼ぶ |
| Skill プロンプト更新必須 | 動作しない | code.md を更新 |
---
## マイグレーション
1. Skill プロンプト（code.md）を更新
2. `start_session` 後に `begin_phase_gate` を呼び出すように変更
3. `--quick` モードでは `begin_phase_gate(skip_branch=true)` を使用
---
## 実装チェックリスト
### start_session 変更
- [ ] ブランチ作成ロジックを削除
- [ ] `enable_branch` パラメータを削除
- [ ] レスポンスから `branch` フィールドを削除
- [ ] `next_step` フィールドを追加
### begin_phase_gate 新規作成
- [ ] パラメータ: `session_id`, `skip_branch`, `resume_current`
- [ ] 残存ブランチ検出ロジック
- [ ] `success: false` + `error: "stale_branches_detected"` レスポンス
- [ ] `recovery_options` フィールド
- [ ] ブランチ作成ロジック（start_session から移植）
- [ ] Phase.EXPLORATION 設定
- [ ] `skip_branch=true` 時は READY に遷移
- [ ] `resume_current=true` 時は既存ブランチで続行（`resumed: true`）
### record_outcome 変更
- [ ] `outcome="failure"` 時のブランチ削除ロジック
- [ ] `branch_cleanup` レスポンスフィールド
- [ ] ブランチが見つからない場合のハンドリング
### Skill プロンプト更新
- [ ] Step 2 からブランチ作成関連を削除
- [ ] Step 5 を新規追加
- [ ] 残存ブランチ時の AskUserQuestion フロー
### テスト
- [ ] begin_phase_gate 正常系
- [ ] begin_phase_gate 残存ブランチ検出
- [ ] begin_phase_gate resume_current=true（llm_task_* 上）
- [ ] begin_phase_gate resume_current=true（main 上）
- [ ] begin_phase_gate skip_branch=true
- [ ] record_outcome failure 時のブランチ削除
- [ ] 複数残存ブランチの処理
