# v1.6 Update
Release Date: 2026-01
## Overview
v1.6 enhances branch lifecycle management with stale branch warnings, automatic deletion on failure, and separation of `start_session` into preparation and phase gate responsibilities.
## Background
v1.2 introduced Git branch isolation for garbage detection, but several issues remained:
| Issue | Impact |
|-------|--------|
| No stale branch warning | `llm_task_*` branches can remain unnoticed when on main |
| Branch not deleted on failure | Failed session branches are left behind |
| Mixed responsibilities in `start_session` | Preparation (session/context) and phase gate (branch/phase) were combined |
## Design Principles
### Separation of Concerns
| Layer | Responsibility | Controlled By |
|-------|---------------|---------------|
| Preparation Phase | Session initialization, context retrieval | Skill |
| Phase Gate | Branch creation, phase transitions | Server |
| User Intervention | Decision on stale branch handling | Skill (delegated to user) |
### State Transition Clarity
```
[Preparation Done] → begin_phase_gate → [Stale branches exist?]
│
┌───────────────────────────────┼───────────────────────────────┐
↓ ↓ ↓
[Delete chosen] [Merge chosen] [Ignore chosen]
│ │ │
↓ ↓ ↓
cleanup_stale_sessions merge_to_base (do nothing)
│ │ │
└───────────────────────────────┴───────────────────────────────┘
│
↓
begin_phase_gate (retry)
│
↓
[Branch created]
│
↓
[EXPLORATION]
```
---
## New Features
### 1. Stale Branch Warning (User Intervention)
When `begin_phase_gate` is called and `llm_task_*` branches exist, **block branch creation** and require user decision.
#### Detection Logic
```python
def should_warn_stale_branches():
current = get_current_branch()
task_branches = list_branches("llm_task_*")
# Condition 1: Not currently on a task branch
if current.startswith("llm_task_"):
return False
# Condition 2: At least one task branch exists
if len(task_branches) == 0:
return False
return True
```
#### Response Design
**When stale branches detected (blocked):**
```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": "Run cleanup_stale_sessions, then retry begin_phase_gate",
"merge": "Run merge_to_base, then retry begin_phase_gate",
"continue": "Call begin_phase_gate(resume_current=true) to leave stale branches and continue"
}
}
```
**Normal case:**
```json
{
"success": true,
"phase": "EXPLORATION",
"branch": {
"created": true,
"name": "llm_task_abc123_from_main",
"base_branch": "main"
}
}
```
#### Skill Behavior
1. Call `begin_phase_gate`
2. If `success: false` and `error: "stale_branches_detected"`:
- Present 3 choices via AskUserQuestion
- Execute action based on user's choice
- Retry `begin_phase_gate`
3. If `success: true`, continue
```
AskUserQuestion:
question: "Previous task branches exist. What would you like to do?"
options:
- label: "Delete and continue"
description: "Discard previous changes and start clean"
- label: "Merge and continue"
description: "Incorporate previous changes into current branch first"
- label: "Continue as-is"
description: "Keep previous branches and start new session"
```
#### Three Choices
| Choice | Stale Branches | New Branch |
|--------|----------------|------------|
| Delete and continue | Delete all | Create |
| Merge and continue | Merge to base, then delete | Create |
| Continue as-is | **Leave as-is** | Depends (see below) |
**"Continue as-is" Details:**
| Current Branch | Action |
|----------------|--------|
| On `llm_task_*` | Continue working (no new branch) |
| On `main` / `dev` etc. | Leave stale branches, create new branch |
### 2. Automatic Branch Deletion on Failure
When `record_outcome(outcome="failure")` is called, automatically delete the session's branch.
#### Design Rationale
Failed session changes have no value (may be harmful), so they should be automatically discarded.
#### Workflow
```
Previous session detected as failure
↓
record_outcome(outcome="failure", session_id="previous_session")
↓
1. Record to OutcomeLog
2. Identify branch: llm_task_{session_id}_from_{base}
3. Delete branch (force)
↓
Return deletion result in response
```
#### Response
```json
{
"success": true,
"outcome": "failure",
"recorded": true,
"branch_cleanup": {
"attempted": true,
"deleted": "llm_task_session_xyz_from_main",
"message": "Failed session branch deleted automatically."
}
}
```
#### When Branch Not Found
```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 Split
Separate `start_session` into preparation and phase gate initialization.
#### Before (v1.5)
```
start_session
├── session_id generation ← Preparation
├── project_rules retrieval ← Preparation
├── ChromaDB sync ← Preparation
├── Git branch creation ← Phase Gate (problem)
└── Phase.EXPLORATION set ← Phase Gate (problem)
```
#### After (v1.6)
```
start_session (Preparation phase)
├── session_id generation
├── project_rules retrieval
└── ChromaDB sync
begin_phase_gate (Phase gate start)
├── Stale branch check → Block or continue
├── Git branch creation
└── Phase.EXPLORATION set
```
---
## New Tools
### begin_phase_gate
Start phase gate and create branch.
#### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| session_id | string | Yes | - | session_id from start_session |
| skip_branch | bool | No | false | true: Skip branch creation (for --quick) |
| resume_current | bool | No | false | true: Continue on current branch (for "Continue as-is") |
#### skip_branch=true Behavior
```json
{
"success": true,
"phase": "READY",
"branch": {
"created": false,
"reason": "skip_branch=true (quick mode)"
}
}
```
**Note:** Stale branch check is still performed even when `skip_branch=true`.
#### resume_current=true Behavior
Leave stale branches as-is and continue. Behavior depends on current branch.
**When on `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)"
}
}
```
**When on `main` / `dev` etc.:**
```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"]
}
}
```
**Summary:**
- On `llm_task_*` → Continue as-is, no new branch
- On `main` / `dev` etc. → Leave stale branches, create new branch
---
## Modified Tools
### start_session
| Item | v1.5 | v1.6 |
|------|------|------|
| Branch creation | Yes | **No** |
| Phase set | EXPLORATION | **None (unset)** |
| enable_branch | Parameter exists | **Removed** |
#### v1.6 Response
```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
| Item | v1.5 | v1.6 |
|------|------|------|
| outcome="failure" | Record only | **Record + delete branch** |
| outcome="success" | Record only | No change |
---
## Flow Changes
### Before (v1.5)
```
1. Preparation (Skill controlled)
Flag Check → Failure Check → Intent → Session Start (includes branch)
→ DOCUMENT_RESEARCH → QueryFrame
2. Phase Gates (Server enforced)
EXPLORATION → ... → QUALITY_REVIEW
```
### After (v1.6)
```
1. Preparation (Skill controlled)
Flag Check → Failure Check → Intent → Session Start (no branch)
→ DOCUMENT_RESEARCH → QueryFrame
2. Phase Gate Start (Server + Skill cooperation)
begin_phase_gate → [Stale branches?] → [User intervention] → Retry
3. Phase Gates (Server enforced)
EXPLORATION → ... → QUALITY_REVIEW
```
---
## Skill Prompt Changes
### Step 2: Session Start (Modified)
```markdown
## Step 2: Session Start
**Preparation phase only. Branch creation moved to phase gate.**
mcp__code-intel__start_session
intent: "IMPLEMENT"
query: "user's original request"
```
### Step 5: Begin Phase Gate (New)
```markdown
## Step 5: Begin Phase Gate
**Ask user if stale branches exist.**
mcp__code-intel__begin_phase_gate
session_id: "session_id from step 2"
skip_branch: false # true for --quick
**If `success: false` and `error: "stale_branches_detected"`:**
AskUserQuestion:
question: "Previous task branches exist. What would you like to do?"
options:
- "Delete and continue" → Run cleanup_stale_sessions, then retry begin_phase_gate
- "Merge and continue" → Run merge_to_base, then retry begin_phase_gate
- "Continue as-is" → Call begin_phase_gate(resume_current=true)
```
---
## Configuration
`.code-intel/context.yml`:
```yaml
branch_lifecycle:
warn_stale_branches: true # Enable stale branch warning (default: true)
auto_delete_on_failure: true # Auto-delete on failure (default: true)
```
---
## Breaking Changes
| Change | Impact | Resolution |
|--------|--------|------------|
| `start_session` `enable_branch` removed | Parameter error | Remove parameter |
| `start_session` doesn't create branch | Phase is None | Call `begin_phase_gate` |
| Skill prompt update required | Won't work | Update code.md |
---
## Migration
1. Update Skill prompt (code.md)
2. Call `begin_phase_gate` after `start_session`
3. Use `begin_phase_gate(skip_branch=true)` for `--quick` mode
---
## Implementation Checklist
### start_session Changes
- [ ] Remove branch creation logic
- [ ] Remove `enable_branch` parameter
- [ ] Remove `branch` field from response
- [ ] Add `next_step` field
### begin_phase_gate New Tool
- [ ] Parameters: `session_id`, `skip_branch`, `resume_current`
- [ ] Stale branch detection logic
- [ ] `success: false` + `error: "stale_branches_detected"` response
- [ ] `recovery_options` field
- [ ] Branch creation logic (move from start_session)
- [ ] Phase.EXPLORATION set
- [ ] `skip_branch=true` transitions to READY
- [ ] `resume_current=true` continues on existing branch (`resumed: true`)
### record_outcome Changes
- [ ] Branch deletion logic for `outcome="failure"`
- [ ] `branch_cleanup` response field
- [ ] Handle branch not found case
### Skill Prompt Update
- [ ] Remove branch creation from Step 2
- [ ] Add new Step 5
- [ ] AskUserQuestion flow for stale branches
### Tests
- [ ] begin_phase_gate normal case
- [ ] begin_phase_gate stale branch detection
- [ ] begin_phase_gate resume_current=true (on llm_task_*)
- [ ] begin_phase_gate resume_current=true (on main)
- [ ] begin_phase_gate skip_branch=true
- [ ] record_outcome failure branch deletion
- [ ] Multiple stale branches handling
