interface BranchResult {
  success: boolean;
  branch_name: string;
  base_branch: string;
  error?: string;
}

{type}/{issue_number}-{slug}

// IMPORTANT: if `title` contains non-ASCII (e.g. Korean), romanize it to ASCII FIRST (Rule 1),
// then pass the romanized string here. createSlug NEVER returns an empty string.
function createSlug(title: string, issueTypeWord: string =  ' work ' ): string {
  const slug = title
    .toLowerCase()
    .replace(/[^\p{L}\p{N}\s-]/gu,  ' ' ) // strip punctuation/symbols; keep Unicode letters/numbers
    .replace(/[\s_]+/g,  ' - ' )           // spaces/underscores → hyphens
    .replace(/-+/g,  ' - ' )               // collapse consecutive hyphens
    .substring(0, 50)                  // length limit
    .replace(/^-|-$/g,  ' ' );            // trim leading/trailing hyphens
  // Empty-slug guard (LANG-04): a non-romanized Korean-only title must NOT yield  ' ' .
  return slug || issueTypeWord;
}

┌─────────────────────────────────────────────────────────┐
│  Step 1: Check Current State                             │
├─────────────────────────────────────────────────────────┤
│  $ git status                                           │
│  - Check for uncommitted changes                         │
│  - Determine if stash is needed                          │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 2: Handle Changes                                  │
├─────────────────────────────────────────────────────────┤
│  IF changes exist:                                       │
│    $ git stash push -m  " WIP: before #{issue_number} "      │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 3: Sync Base Branch (hierarchical branch support)  │
├─────────────────────────────────────────────────────────┤
│  $ git checkout {base_branch}                           │
│  $ git pull origin {base_branch}                        │
│                                                         │
│  base_branch determination:                              │
│  ├── --base option specified → use that branch           │
│  ├── Sub-task → parent Story branch                      │
│  ├── Story → parent Epic branch                          │
│  ├── Epic → development                                 │
│  └── Independent issue → development (default)           │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 4: Create and Checkout Branch                      │
├─────────────────────────────────────────────────────────┤
│  $ git checkout -b {branch_name}                        │
│  - If branch exists → checkout only                      │
│  - Epic issue → epic/{number}-{slug}                     │
│  - Others → feature/{number}-{slug}                      │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 5: Verify Result                                   │
├─────────────────────────────────────────────────────────┤
│  $ git branch --show-current                            │
│  - Verify branch creation success                        │
│  - Return base_branch info                               │
└─────────────────────────────────────────────────────────┘

# Check current state
git status --porcelain

# If output is not empty, changes exist

# Temporarily save changes
git stash push -m  " WIP: before issue #{issue_number} " 

 # Check stash list
git stash list

# ⭐ 원격 동기화 먼저 — 다른 머신/세션이 만든 계층 브랜치는 fetch 전엔 보이지 않는다
#    (SoT: skills/branch-hierarchy/SKILL.md  " 계층 브랜치 해석 계약 "   R1)
git fetch origin --prune --quiet

# Move to base_branch (default: development, hierarchical: parent branch)
git checkout ${base_branch}

# Update to latest
git pull origin ${base_branch} --rebase

# 1) 이미 있는가 — 원격에 직접 묻는다 (로컬 remote-tracking ref 를 믿지 않는다)
CANDIDATES=$(git ls-remote --heads origin  " refs/heads/{prefix}/{issue_number}-* "   | sed  ' s|.*refs/heads/|| ' )
COUNT=$(printf  ' %s\n '   " $CANDIDATES "   | grep -c .)

# 2) 있으면 그 이름을 그대로 채택한다 — 재계산한 이름으로 새로 만들지 않는다
#    ⛔ ls-remote 결과는 **여러 줄일 수 있다.** 그대로 브랜치명으로 쓰면 checkout 이 실패해,
#        " 복구 표가 실제로 일어난다고 말하는 상태 " (같은 이슈에 계층 브랜치 2개)에서 에이전트가 죽는다.
if [  " $COUNT "   -gt 1 ]; then
  # branch-hierarchy R4 tie-break 를 **여기서 수행한다**: 대장 → 열린 PR base/head → 커밋 수 → 사전순.
  # 채택 후 ⚠️ 경고 로그 + 그 이슈에 후보 목록 코멘트 + 대장 기록. 탈락 후보는 삭제하지 않는다.
  EXISTING={R4 로 고른 단 하나의 후보}
elif [  " $COUNT "   -eq 1 ]; then
  EXISTING= " $CANDIDATES " 
 else
  EXISTING= " " 
 fi

if [ -n  " $EXISTING "   ]; then
  git checkout  " $EXISTING "   2 > /dev/null || git checkout -b  " $EXISTING "   " origin/$EXISTING " 
 else
  # 3) 없을 때만 생성 — 대장( < !-- cc-dev:branch-registry -- > )에 이름이 있으면 그 이름을 쓴다
  git checkout -b {branch_name}
  # 4) ⭐ 커밋이 0개여도 즉시 push — push 안 된 계층 브랜치는 다른 머신에서  " 없는 것 " 이고
  #    `gh pr create --base` 도 찾지 못한다 (R6)
  git push -u origin {branch_name} || {
    # R5 — 레이스: 그 사이 다른 머신이 만들었다. 새 이름을 만들지 말고 원격을 채택한다.
    # ⚠️ 자기 커밋이 0개면 rebase 하지 않는다 — 그 상태의 `origin/{branch}..HEAD` 는 **base
    #    브랜치의 커밋들**이라, 이미 upstream 에 있는 커밋을 새 해시로 복제해 공유 브랜치에 push 한다.
    git fetch origin {branch_name} || exit 1
    if [  " $(git rev-list --count origin/${base_branch}..HEAD) "   -eq 0 ]; then
      git checkout -B {branch_name} origin/{branch_name}    # 자기 커밋 없음 → 원격 그대로 채택
    else
      git rebase origin/{branch_name} || { echo  " ⛔ rebase 충돌 — 수동 해결 후 재실행 " ; exit 1; }
    fi
    git push -u origin {branch_name}
  }
  # 5) 대장에 기록 — 다음 머신·세션이 이 이름을 그대로 쓴다 (R3, 실패는 비차단 경고)
fi

# Check current branch
git branch --show-current

# Verify it matches the expected branch

# Recover stash (after work is done)
git stash pop

# Recover specific item from stash list
git stash apply stash@{0}

# Feature issue
/dev:issue-branch 25  " Community list screen " 

 # Result
branch_name: feature/25-community-list

# Bug issue
/dev:issue-branch 30  " Fix login error "   --type bugfix

# Result
branch_name: bugfix/30-login-error

# Mixed Korean/English title — Korean romanized, special chars removed
/dev:issue-branch 28  " [Story] Community 엔티티 정의 " 
 # Result
branch_name: feature/28-story-community-entity

# Korean-ONLY title — romanized to ASCII, NEVER empty (was the LANG-04 bug:  " feature/25- " )
/dev:issue-branch 25  " 커뮤니티 목록 " 
 # Result
branch_name: feature/25-keomyuniti-moklog

1. issue-cycle queries issue info
   ↓
2. issue-branch-agent called
   - issue_number: 25
   - issue_title:  " Community list screen " 
    - issue_type: feature
   ↓
3. Branch creation complete
   - branch_name: feature/25-community-list
   ↓
4. Passed to implementation-agent