# Start full cycle with work content
/cc-dev:run  " 저자 목록 화면 추가 "

/cc-dev:run 1810

# Jira issue key — title gets prefixed  " UB-123: " , label  " JIRA-UB "   is added
/cc-dev:run UB-123

# A Jira ticket URL also works — the key is extracted from the path
/cc-dev:run https://yourorg.atlassian.net/browse/UB-123

# Specify type
/cc-dev:run --type feat  " Add author list screen " 

 # Specify scope
/cc-dev:run --scope console-author  " Add author list screen " 

 # Specify point
/cc-dev:run --point 5  " Add author list screen " 

 # Sprint assignment
/cc-dev:run --sprint current  " Add author list screen " 

 # PR only (no merge wait)
/cc-dev:run --no-merge  " Add author list screen " 

 # Explicit base branch (manual parent branch setting)
/cc-dev:run --base epic/1810-author-feature 1812

# Skip review (urgent hotfix)
/cc-dev:run --skip-review  " Urgent fix " 

 # Force BDD scenarios (even for non-screen features)
/cc-dev:run --bdd  " API client refactoring " 

 # Skip BDD scenarios and BDD Coverage Gate (even for screen features)
/cc-dev:run --skip-bdd  " Simple list modification " 

 # Skip tests (urgent)
/cc-dev:run --skip-tests  " Urgent fix " 

 # Skip local full-stack integration verification (Step 7.7, default on)
# 로컬 풀스택(serverpod start, 내장 Postgres) 통합 검증을 건너뜀
/cc-dev:run --skip-local-integration  " Backend-only config tweak " 

 # Skip PM requirements refinement (Step 1.5, default on)
# 이슈를 만들기 전 PM 요구사항 정제 단계를 건너뛰고 Step 1의 키워드 추론만 사용
/cc-dev:run --skip-pm  " Urgent one-liner " 

 # Skip design verification (Step 7.3, default on for screen features) — still requires AskUserQuestion confirmation
/cc-dev:run --skip-design-verify  " Urgent hotfix without a simulator handy " 

 # Explicit design-verification target/tolerance
/cc-dev:run --design-target=android --design-tolerance pixel=1,color_delta_e=2  " 저자 상세 화면 추가 "

S5     ACT   브랜치 + In Progress(부모 cascade)    extern:true  writes:zenhub:pipeline,claim:acquire
S6     ACT   BDD 시나리오 작성                     extern:true
S7     ACT   구현 (implementation-agent)           own:lead  tier:standard
S7f    FORK  구현 병렬 (Agent Teams)               width:2  tier:standard  own:T1=kobic_server/lib/**|T2=kobic/lib/**  degrade:width=1
S7j    JOIN  Lead 인터페이스 정합 확인              mode:barrier  because:프론트↔백엔드 인터페이스는 교차 항목
S7.1   ACT   design reference + DDR                writes:.claude/docs/{scope}/design-decisions.md
S7.2   GATE  화면 PR diff 에 CoUI 소스 없음          verdict:git diff --name-only | grep coui  undet:fail  fail:S7R
S7.3   LOOP  design verification (Figma↔runtime)   contract:L-7.3
S7.5   ACT   backend codegen (pod:generate)        writes:**/*.g.dart  own:lead   # 생성물은 Lead 전용
S7.7   GATE  local full-stack integration          verdict:dart test -t integration exit  undet:fail  fail:S7R
S8w    FORK  테스트 코드 작성만 병렬               width:3  tier:standard  own:T1=kobic/test/{unit,bloc}/**|T2=kobic_server/test/**|T3=kobic/integration_test/**  degrade:width=1
S8j    JOIN  테스트 실행 직렬화                     mode:barrier  serialize:1  because:한 워크트리·한 포트에서 flutter test 를 동시 실행할 수 없다
S8     GATE  pr:preflight (unit/widget/integ)      verdict:/cc-dev:pr:preflight exit  undet:fail  fail:S7R
S8.3   GATE  BDD coverage 100% + assertions        verdict:stepCoverage==1  & &   !assertionless  undet:fail  fail:S6R
S8.5   LOOP  runPrePushGate                        contract:L-8.5
S8.7   LOOP  code review gate                      contract:L-8.7
S9.0   GATE  중복 착수 재확인 (--state all+baseRefName) verdict:경쟁 PR 0건 또는 겹침 없음 근거  undet:fail  fail:HALT
S9     GATE  pre-PR 7종                            verdict:mayClose(openChildrenStatus)  undet:fail  fail:HALT
S9x    ACT   gh pr create                          writes:github:pr
S10    ACT   moveIssueToPipeline(Review/QA)        writes:zenhub:pipeline
S10.5  LOOP  CI 대기 ∥ 작업내역 발행                 contract:L-10.5
S10.6  LOOP  CI 실패 수정 → re-push                 contract:L-10.6
S11    LOOP  리뷰 피드백 반영                       contract:L-11
S11.9  GATE  openChildrenStatus === none           verdict:mayClose(...)  undet:fail  fail:HALT
S12    ASK   머지 승인                              options:승인|수정필요|취소  pre:--merge=pre-authorized  unattended:pre 없으면 정지([INCOMPLETE: merge_approval_unavailable])
S12b   GATE  머지 직전 PR base 재해석 + retarget      verdict:baseRefName==findExistingHierarchyBranch(parent)(조회만)  & &   merge-base --is-ancestor origin/{base} origin/{PR head}  & &   rev-list --count origin/{base}..origin/{PR head} > 0  undet:fail  fail:HALT  skip:스택모드
S12g   GATE  머지 직전 CI 재조회                     verdict:gh pr checks --json name,state,bucket 전부 bucket=pass|skipping  undet:fail  fail:S10.6
S12m   ACT   gh pr merge --squash                  writes:github:pr,github:issue
S12.5  ACT   close 검증 + 자식 불변식 복구           writes:github:issue,zenhub:state,git:base,claim:release
S12.6  ACT   Orca 워크트리 반납 표시 (자기 제거 금지)  writes:orca:worktree-card  because:회수는 만든 쪽(부모 batch)의 몫이다
S7R    LOOP  구현 재작업 (rework)                   contract:L-7R
S6R    LOOP  BDD 재작업                             contract:L-6R

S7 -- >   S7f -- >   S7j -- >   S7.2 -- >   S7.3 -- >   S7.5 -- >   S7.7 -- >   S8w -- >   S8j -- >   S8
S8 -- >   S8.3 -- >   S8.5 -- >   S8.7 -- >   S9.0 -- >   S9 -- >   S9x -- >   S10 -- >   S10.5 -- >   S11
S11 -- >   S11.9 -- >   S12 -- >   S12b -- >   S12g -- >   S12m -- >   S12.5 -- >   S12.6
S5    -- >   S7                         # hard prereq 는 S5 (Steps 1–3 을 건너뛰는 경로에서도 S5 는 실행)
S7R   -- >   S7                         # 재작업 루프의 몸통 = Step 7 재실행
S6R   -- >   S6
S10.6 -- >   S8.5                       # 수정 후 re-push 직전 runPrePushGate() 재실행
S7    .. >   S7.1                       # 비차단 참고 — 절대 게이트하지 않는다(전제조건에서도 제외)
S6    .. >   S7                         # advisory: S6 도 S5 를 전제로 하는 형제다
S7.3 ~~ >   S7.5  on:!screenFeature||!figmaSource  record:log+prBodyExtras.designVerification=null(not-applicable)
S7.3 ~~ >   S7.5  on:toolingMissing                record:ASK+prBodyExtras.designVerification(status:skipped)  unattended:스킵 확인 자동 채택
S8   ~~ >   S8.3  on:--skip-tests  & &   ASK== " 스킵 확인 "    record:ASK+prBodyExtras.testsSkipped → PR body            unattended:스킵 확인 자동 채택(플래그가 이미 승인)
S8.3 ~~ >   S8.5  on:--skip-bdd  & &   ASK== " 스킵 확인 "      record:ASK+prBodyExtras.bddSkipped → PR body              unattended:스킵 확인 자동 채택(플래그가 이미 승인)
S8.7 ~~ >   S9.0  on:--skip-review                  record:prBodyExtras.reviewSkipped → PR body
S12  ~~ >   SKIP  on:approval== " 취소 "                   record:PR·브랜치 그대로 유지(되돌리지 않음) + TodoWrite in_progress
S12.6 ~~ >   SKIP on:!orca||워크트리 밖 실행           record:log(no-op — 표시할 카드가 없다)
S7.2 == >   S7R   on:couiSourceInDiff          bound:2  invalidates:S7.2,S7.3,S7.5,S7.7,S8,S8.3,S8.5,S8.7,S9.0,S11.9
S7.3 == >   S7R   on:verify.fail_after_repair  bound:1  invalidates:S7.2,S7.3,S7.5,S7.7,S8,S8.3,S8.5,S8.7,S9.0,S11.9
S7.7 == >   S7R   on:integration.fail          bound:2  invalidates:S7.2,S7.3,S7.5,S7.7,S8,S8.3,S8.5,S8.7,S9.0,S11.9
S8   == >   S7R   on:test.fail                 bound:2  invalidates:S7.2,S7.3,S7.5,S7.7,S8,S8.3,S8.5,S8.7,S9.0,S11.9
S12  == >   S7R   on:approval== " 수정 필요 "         bound:2  invalidates:S7.2,S7.3,S7.5,S7.7,S8,S8.3,S8.5,S8.7,S9.0,S11.9
S8.3 == >   S6R   on:coverage < 1                bound:2  invalidates:S6,S8.3,S8.5,S8.7,S9.0,S11.9
S10.5== >   S10.6 on:ci.fail                   bound:3  invalidates:S8.5,S10.5
S11  == >   S10.6 on:feedback.commit           bound:3  invalidates:S8.5,S10.5
S12g == >   S10.6 on:checks.notSuccess         bound:3  invalidates:S8.5,S10.5

L-7R (구현 재작업)
inv:      진입 시 invalidates: 목록을 pending 으로 되돌린 뒤에만 Step 7 을 재실행한다
prog:     되돌린 게이트 중 재실패로 남은 수, 매 라운드 강한 감소
          no-prog: 같은 게이트가 같은 이유로 두 번 실패하면 Rung 2(`/cc-dev:unstuck`)로 종류를 바꾼다
term:     S7.2·S7.3·S7.7·S8·S8.3·S8.5·S8.7 전부 재통과
budget:   2 rounds (S7.2/S7.7/S8/S12 진입 합산). S7.3 자체 repair 는 별도 bound:1 (L-7.3 소관)
exhaust:  blockIssue(issue,  ' rework_exhausted ' ) — holding 이동 + 사유 코멘트 + 점유 해제.
          PR 은 그대로 두고 중단 (승인 재질문으로 예산을 늘리지 않는다)
          정의: ../rules/zenhub-conventions.md → Pipeline State Contract / blockIssue()
resume:   TodoWrite 상태 + 실패 게이트의 마지막 verdict 재실측 (대화 카운터는 예산이 아니다)
log:       " 7R #1/2: 되돌림 10항목 · 재실패 3→1 "   + 탈락시킨 게이트와 이유

L-6R (BDD 재작업)
inv:      .feature 와 step 함수는 같은 커밋에 들어간다(둘 중 하나만 되돌아가지 않게)
prog:     missingSteps + assertion 없는 step 파일 수, 매 라운드 강한 감소
          no-prog: 동일 잔여면 `/cc-flutter:bdd:generate {scope} --only-steps true` 로 종류를 바꾼다
term:     stepCoverage === 1.0  & &   filesWithoutAssertions.length === 0
budget:   2 rounds
exhaust:  blockIssue(issue,  ' bdd_coverage_exhausted ' ) 후 중단. `--skip-bdd` 로 자동 우회 금지
resume:   .feature ↔ step/ 재스캔 (Step 8.3 판정 재실측)
log:       " 6R #1/2: missing=7→2 assertionless=1→0 "

// L-7R / L-6R 진입 — 되돌림·예산·복귀 지점이 이 함수 하나에만 있다
// (reworkRound·bddReworkRound·isReworkPass 는 Step 0.1 에서 사이클 전역으로 초기화된다)
async function enterRework(node:  " S7R "   |  " S6R " ) {
  const R = {
    S7R: { steps: [ " 7.2 " , " 7.3 " , " 7.5 " , " 7.7 " , " 8 " , " 8.3 " , " 8.5 " , " 8.7 " , " 9.0 " , " 11.9 " ], to:  " 7 " ,
           next: () = >   ++reworkRound,    bound: 2, blocked:  " rework_exhausted "   },
    S6R: { steps: [ " 6 " , " 8.3 " , " 8.5 " , " 8.7 " , " 9.0 " , " 11.9 " ],                        to:  " 6 " ,
           next: () = >   ++bddReworkRound, bound: 2, blocked:  " bdd_coverage_exhausted "   },
  }[node];

  const round = R.next();
  if (round  >   R.bound) {
    // exhaust: 침묵 금지 ·  " 경고 후 계속 "   금지
    // ⚠️ throw 만 하면 이슈는 In Progress 에 남는다 — 보드 반영은 **문구가 아니라 호출**이다.
    //    blockIssue() 가 holding 이동 + 사유 코멘트 + 점유 해제를 한 묶음으로 수행한다
    //    (SoT: ../rules/zenhub-conventions.md → Pipeline State Contract).
    await blockIssue(issue, R.blocked, { detail: `${node} 재작업 예산 ${R.bound} 라운드 소진` });
    throw new Error(
      `⛔ ${node} 재작업 예산 소진(bound:${R.bound}) — BLOCKED( ' ${R.blocked} ' ) 보드 반영 완료, 중단한다. ` +
      `PR/브랜치는 그대로 두고 사람 판단을 기다린다`
    );
  }
  // ⚠️ 여기서 되돌리지 않으면 아무 게이트도 재실행되지 않는다 (completed 는 그대로 통과한다)
  await resetStepsToPending(R.steps);   // TodoWrite 로 해당 항목 status →  " pending "   (아래 TodoWrite Integration)
  if (node ===  " S7R " ) isReworkPass = true;   // Step 7.3 의 mode: " repair "   신호
  console.warn(`♻️ ${node} 라운드 ${round}/${R.bound} — Step ${R.to} 복귀. 되돌림: ${R.steps.join( " · " )}`);
  return await runFromStep(R.to);   // 단계 id 는 STEP_ORDER 와 같은 **문자열**이다 (8.5 가 8 로 접히지 않게)
}

# loop/단계 진입 전 1회 — 결과를 capability 맵으로 보관
for tool in melos serverpod dart flutter gh; do
  command -v  " $tool "   > /dev/null 2 > & 1  & &   echo  " $tool: ok "   || echo  " $tool: MISSING " 
 done

# 디자인 검증 도구(Step 7.3 전용) — 아래  " 예외 "   참고, melos/serverpod 등과 취급이 다르다
claude mcp list 2 > /dev/null | grep -Eq  " figma.*connected "   & &   echo  " figma-mcp: ok "   || echo  " figma-mcp: MISSING " 
 claude mcp list 2 > /dev/null | grep -Eq  " marionette.*connected "   & &   echo  " marionette-mcp: ok "   || echo  " marionette-mcp: MISSING " 
 claude mcp list 2 > /dev/null | grep -Eq  " dart.*connected "   & &   echo  " dart-mcp: ok "   || echo  " dart-mcp: MISSING " 
 flutter devices 2 > /dev/null | grep -Eq  " • "   & &   echo  " device: ok "   || echo  " device: MISSING "

// resolveJiraRef 정의는 Step 1.0 참조 (Jira 키/URL → 키 문자열, 아니면 null)
const startedFrom =
  /^\d+$/.test(rawInput.trim()) ?  " issue_number "   :   // 기존 이슈 번호 — Steps 1–3 생략
  resolveJiraRef(rawInput)      ?  " jira "   :           // Jira 티켓 가져오기 — Steps 1–3 실행
   " work_content " ;                                    // 한 줄 설명 — Steps 1–3 실행

// ── 사이클 전역 재작업 상태 (L-7R / L-6R / L-10.6 의 예산 카운터) ──
// ⚠️ Step 7·Step 6 **재진입이 초기화하지 않는다**. 여기(사이클 진입 1회)에서만 0/false 로 둔다 —
//    되돌아간 자리에서 카운터를 다시 0 으로 만들면 bound: 가 예산이 아니게 되고 순환이 무제한이 된다.
let reworkRound = 0;       // S7.2/S7.7/S8/S12 == >   S7R 진입 횟수 (bound:2)
let bddReworkRound = 0;    // S8.3 == >   S6R 진입 횟수 (bound:2)
let ciFixRound = 0;        // S10.5/S11/S12g == >   S10.6 진입 횟수 (bound:3)
let isReworkPass = false;  // Step 7.3 의 mode: " repair "   신호 (S7R 진입 시 true)

// 식별자는 Step 0 에서 1회 계산해 사이클 내내 고정 (owner = host:worktree, run = 실행 식별자)
const claim = await claimStatus(issue.number, me);   // mine | other-live | stale | none | unknown

# 이슈 번호로 호출된 경우 — 정밀 조회
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner 2 > /dev/null)
gh pr list --repo  " $REPO "   --state open --search  " $ISSUE "   \
  --json number,title,headRefName,author 2 > /dev/null

# 원격 브랜치에 이슈 번호가 박힌 것이 있는지 (숫자 경계로 9440 ↔ 94401 오탐 차단)
git ls-remote --heads origin 2 > /dev/null | grep -E  " [^0-9]${ISSUE}([^0-9]|$) " 

 # ⭐ 부모(Epic/Project) 번호로도 조회한다 — 자식 번호로는 부모 줄기가 안 보인다
OWNER=${REPO%%/*}; NAME=${REPO##*/}
PARENT=$(gh api graphql -f query= " query { repository(owner:\ " $OWNER\ " , name:\ " $NAME\ " ) {
  issue(number: ${ISSUE}) { parent { number } } } } "   \
  --jq  ' .data.repository.issue.parent.number '   2 > /dev/null)
[ -n  " $PARENT "   ]  & &   git ls-remote --heads origin 2 > /dev/null | grep -E  " (epic|project)/${PARENT}- "

gh pr list --repo  " $REPO "   --state all --search  " $ISSUE "   \
  --json number,state,baseRefName,headRefName
# state=MERGED 면 baseRefName 이 epic/*·project/* 여도 그 작업은 끝난 것이다

KEYWORD= " patrol nightly "       # 증상에서 뽑은 2~3 단어
gh issue list --repo  " $REPO "   --state open --search  " $KEYWORD "   --json number,title,createdAt
gh pr list    --repo  " $REPO "   --state open --search  " $KEYWORD "   --json number,title

PARENT=$(gh pr view --json baseRefName -q .baseRefName 2 > /dev/null || echo development)
MINE=$(git diff --name-only  " origin/$PARENT...HEAD "   2 > /dev/null | sort)

git ls-remote --heads origin  ' refs/heads/story/* '   2 > /dev/null \
  | awk  ' {print $2} '   | sed  ' s|refs/heads/|| '   \
  | while read -r BR; do
      N=$(git diff --name-only  " origin/$PARENT...origin/$BR "   2 > /dev/null | sort \
            | comm -12 -  < (printf  ' %s\n '   " $MINE " ) | wc -l | tr -d  '   ' )
      if [  " $N "   -gt 0 ]; then echo  " ⚠️ $BR — 공유 ${N}파일 " ; fi
    done

gh api graphql -f query= ' 
 {
  repository(owner: " {OWNER} " , name: " {REPO} " ) {
    issue(number:{N}) {
      subIssues(first:100) {
        totalCount
        nodes { number title state createdAt }
      }
    }
  }
} '

┌─────────────────────────────────────────────────────────────────┐
│                    /cc-dev:run  " 작업 내용 "                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Step 0.4: 점유 가드 ⛔ (--force-claim 시 스킵)                   │
│  ├── claimStatus(issue) — 점유 대장 + In Progress 조합 판정       │
│  ├── other-live → 착수 금지 ([INCOMPLETE: issue_occupied])        │
│  └── stale → 인수 기록 후 진행 / none → 통과                      │
│                                                                 │
│  Step 0.5: 중복 착수 preflight ⚠️ (--skip-dup-check 시 스킵)      │
│  ├── 열린 PR 조회 (gh pr list --search {issue})                  │
│  ├── 원격 브랜치 조회 (git ls-remote | grep {issue})              │
│  ├── PR 발견 → 중단 + 확인 / 브랜치만 → 경고 + 확인               │
│  └── gh 부재 → 경고 후 진행 (Step 0 계약 준용)                    │
│                                                                 │
│  Step 0.6: 기존 sub-issue 발견 ⚠️ (GD-04, 컨테이너형만)           │
│  ├── gh api graphql sub-issues(issue.number) — completeness    │
│  │   source of truth (ZenHub parent: 검색은  " 최신 20개 " 만 봄)    │
│  └── 겹치는 기존 sub-issue 있으면 재사용, 새로 만들지 않음         │
│                                                                 │
│  Step 1: 작업 내용 분석                                          │
│  ├── 작업 유형 추론 (feat/fix/chore/refactor)                    │
│  ├── 스코프 추출 (feature명)                                     │
│  ├── 화면 타입 감지 (목록/상세/폼)                                │
│  └── 예상 복잡도 산정 (Story Point)                              │
│                                                                 │
│  Step 1.5: PM 요구사항 정제 ⚠️ (--skip-pm 시 스킵)                │
│  ├── pm-spec-agent 호출                                         │
│  ├── (피그마 링크 있으면) get_design_context/get_screenshot 조회  │
│  ├── LOCKED seed-spec 있으면 우선 정합                           │
│  ├── FR/AC, 스코프 In/Out, Story Point 재산정                    │
│  ├── 명시적 --type/--scope/--point 는 그대로 존중                │
│  └── 애매한 부분은  " 가정 " 으로 명시하고 진행 (되묻지 않고 자동 진행)│
│                                                                 │
│  Step 2: ZenHub 이슈 생성                                        │
│  ├── mcp__zenhub__createGitHubIssue                             │
│  ├── 이슈 타입 자동 설정 (Feature/Task/Bug)                      │
│  ├── 라벨 자동 지정                                              │
│  └── Estimate 설정                                              │
│                                                                 │
│  Step 3: Product Backlog 이동                                   │
│  ├── mcp__zenhub__moveIssueToPipeline                           │
│  └── Pipeline: Product Backlog                                  │
│                                                                 │
│  Step 4: 브랜치 생성 ⚠️ 필수 (계층 브랜치 전략)                    │
│  ├── 부모 이슈 감지 (ZenHub parentIssueId 조회)                  │
│  ├── base 브랜치 결정:                                          │
│  │   ├── Sub-task → Story 브랜치 기반                            │
│  │   ├── Story → Epic 브랜치 기반                                │
│  │   ├── Epic → development 기반                                │
│  │   └── 독립 이슈 → development 기반                            │
│  ├── 부모 브랜치 미존재 시 자동 생성                               │
│  ├── issue-branch-agent 호출 (base_branch 전달)                 │
│  ├── {type}/{number}-{slug} 형식                                │
│  └── ⚠️ development/main에 직접 커밋 금지                        │
│                                                                 │
│  Step 5: In Progress 이동 (⭐ 기존 이슈 번호로 시작해도 항상 실행) │
│  ├── issue-state-agent 호출                                     │
│  ├── Pipeline: In Progress → 이동 후 읽어서 확인                │
│  └── cascadeStartToParents — 부모(Epic 등)가 아직 착수 전 칸이면 │
│      조부모까지 함께 In Progress로 이동 (issue-state-agent.md)  │
│                                                                 │
│  Step 6: BDD 시나리오 작성 (screen feature 시)                          │
│  ├── bdd-scenario-agent 호출                                    │
│  ├── Gherkin Feature 파일 생성                                   │
│  ├── Step Definition 생성                                       │
│  └── 커밋:  " test({scope}): ✅ BDD 시나리오 작성 "                    │
│                                                                 │
│  Step 7: 구현 작업                                               │
│  ├── 이슈 내용 기반 구현                                         │
│  └── 증분 커밋 생성                                              │
│                                                                 │
│  Step 7.1: 디자인 레퍼런스·의사결정 (screen feature 시)         │
│  ├── cc-designer 지식 스킬 참고 (ui-/ix-/dsys-* — 비차단)       │
│  ├── 스펙·시안에 답 없는 판단 → design-decision R0→R5 확정      │
│  │   (R2 코드 선례 전수 조사가 핵심 — 사람에게 되묻지 않음)     │
│  ├── DDR 기록: .claude/docs/{scope}/design-decisions.md         │
│  └── 브랜드/법·정책/비가역/스펙충돌 4종만 권고안+확인           │
│                                                                 │
│  Step 7.2: CoUI 패키지 변경 분리 (on CoUI 수정/확장 필요) ⚠️        │
│  ├── composition ladder 선행 (as-is→style→compose→extend)        │
│  ├── extend 필요 확정 시: CoUI 저장소 별도 이슈/브랜치/PR          │
│  │   (additive · coui_flutter + coui_web 양쪽 · 버전범프)         │
│  ├── CoUI PR 선행 머지 → 프로젝트 의존성 갱신                     │
│  └── ⚠️ 화면 PR diff에 CoUI 소스 변경 포함 금지 (Step 9 게이트)    │
│                                                                 │
│  Step 7.3: 디자인 검증 게이트 (screen feature + Figma 소스 시) ⚠️      │
│  ├── (도구/기기 부재 또는 --skip-design-verify 시 AskUserQuestion 확인)│
│  ├── flutter run -d {target} --print-dtd (백그라운드, 별도 프로세스) │
│  ├── [선택·비차단] marionette:smoke — 조립/반응 여부만 빠르게 확인   │
│  ├── pixel-loop:loop  < figma-url >   --mode=create|repair --route=...  │
│  ├── pixel-loop:verify --mode=regression (읽기전용 최종 판정) │
│  ├── 실패 시 pixel-loop repair 1회 재시도 → 그래도 실패면 사용자 확인│
│  └── ⚠️ 무음 스킵 금지 — PR body에 상태(pass/skip/미해결) 영구 기록  │
│                                                                 │
│  Step 7.5: Backend 코드 생성 (on Backend changes) ⚠️                │
│  ├── melos run backend:pod:generate                             │
│  └── 커밋:  " chore(backend): 🔧 코드 생성 "                          │
│                                                                 │
│  Step 7.7: 로컬 풀스택 통합 검증 (Backend/screen feature 시) ⚠️       │
│  ├── (--skip-local-integration 시 스킵, 기본 on)                  │
│  ├── serverpod start (백엔드+내장 Postgres+앱 풀스택 기동)         │
│  ├── [Backend 변경] dart test -t integration (로컬, Docker 불필요) │
│  ├── [screen feature] 프론트를 로컬 백엔드 대상 통합 스모크         │
│  ├── 마이그레이션/로그 → Serverpod MCP 활용                       │
│  ├── 검증 후 serverpod start 종료                                │
│  ├── (3.x 폴백: docker compose up -d + dart run bin/main.dart)   │
│  └── ⚠️ 게이트 실패 시 Step 8 진행 차단                           │
│                                                                 │
│  Step 8: 테스트 작성 및 검증 (필수 게이트) ⚠️                      │
│  ├── [Phase 8a: 테스트 코드 작성]                                  │
│  │   ├── [프론트엔드 - 필수]                                       │
│  │   │   ├── UseCase 단위 테스트 (unit-test-agent)               │
│  │   │   └── BLoC 단위 테스트 (bloc-test-agent)                  │
│  │   ├── [백엔드 - on Backend changes 필수]                       │
│  │   │   ├── 엔드포인트/서비스 단위 테스트 (serverpod-test-agent) │
│  │   │   └── 엔드포인트 통합 테스트 (serverpod-test-agent)        │
│  │   ├── BDD Patrol 테스트 (screen feature 시, 손으로 작성)      │
│  │   └── 커밋:  " test({scope}): ✅ 테스트 작성 "                     │
│  ├── [Phase 8b: PR Preflight 게이트] /cc-dev:pr:preflight --auto-scope  │
│  │   ├── 변경 패키지 자동 감지 (git diff {base}..HEAD)            │
│  │   ├── Unit 레이어 (변경 패키지) — 실패 시 즉시 중단             │
│  │   ├── Widget 레이어 (변경 패키지)                              │
│  │   └── Integration @smoke (디바이스 있으면 조건부 실행)          │
│  └── ⚠️ 게이트 실패 시 Step 8.3 진행 불가 → PR 생성 차단           │
│     정책: cc-dev/rules/pr-preflight-policy.md               │
│                                                                 │
│  Step 8.3: BDD Coverage Gate ⚠️ (--skip-bdd 시 스킵)              │
│  ├── .feature 파일 스캔 (현재 feature 범위)                        │
│  ├── Given/When/Then 스텝 파싱                                    │
│  ├── step/ 폴더에서 매칭 step 함수 검증                             │
│  ├── 각 step 함수 내 assertion (expect/verify) 존재 확인            │
│  ├── ⚠️ step_coverage  <   100% → enterRework( " S6R " ) (bound:2)      │
│  └── --skip-bdd 시 ASK 확인 + PR body 영구 기록 (경고만 금지)      │
│                                                                 │
│  Step 8.5: Pre-push 검증 + DCM format/lint 0건 + DCM 품질 개선 ⚠️ 필수│
│  ├── [Phase 1: DCM 포맷팅 + Dart 린트 자동 수정 + 0건 게이트]      │
│  │   ├── melos run format (dcm format — dart format 대체)         │
│  │   ├── dart fix --apply (린트 자동 수정)                         │
│  │   ├── melos run analyze (Dart SDK 분석)                   │
│  │   ├── error/warning/info 잔존 시 수동 수정 (최대 2회 반복)      │
│  │   └── ⚠️ 2회 시도 후에도 이슈 잔존 시 PR 생성 차단              │
│  ├── [Phase 2: DCM 코드 품질 개선]                                 │
│  │   ├── melos run dcm:analyze (DCM 린트 + 메트릭)               │
│  │   ├── melos run dcm:fix (자동 수정 가능 항목 수정)             │
│  │   ├── melos run dcm:unused-code (미사용 코드 검사)           │
│  │   ├── melos run dcm:analyze (수정 후 재검증)                   │
│  │   └── ⚠️ error 심각도 이슈 잔존 시 PR 생성 차단                 │
│  ├── [Phase 3: 최종 린트 검증]                                     │
│  │   ├── melos run analyze (DCM 수정 후 Dart 재확인)         │
│  │   ├── melos run dcm:analyze (DCM 최종 재확인)                  │
│  │   └── ⚠️ 이슈 0건 필수 — 잔존 시 PR 생성 차단                   │
│  └── 검증 실패 시 Step 9 진행 불가                                │
│                                                                 │
│  Step 8.7: Code Review Gate ⚠️ (gstack 패턴)                    │
│  ├── /cc-quality:review --quick 자동 실행                              │
│  ├── 2-pass 분석:                                               │
│  │   ├── Pass 1: Critical (차단) - 보안, 데이터 안전성, 레이스컨디션 │
│  │   └── Pass 2: Informational (PR body 포함)                   │
│  ├── Critical 발견 시:                                          │
│  │   ├── 자동 수정 시도 (최대 2회)                                │
│  │   └── 수정 불가 시 PR 생성 차단                                │
│  ├── Informational 항목 → PR description에 자동 포함             │
│  └── --skip-review 시 PR body에 미실행 영구 기록                  │
│                                                                 │
│  Step 9.0: 중복 착수 재확인 ⚠️ (--state all · 외부 트래커 키)      │
│  └── 이미 머지된 경쟁 PR 은 --state open 으로 안 보인다           │
│                                                                 │
│  Step 9: PR 생성 (검증 게이트 통과 후, 계층 머지)                  │
│  ├── ⚠️ 브랜치 형식 검증 필수                                    │
│  ├── PR base 결정 (계층 브랜치 전략):                             │
│  │   ├── Sub-task → Story 브랜치 (base)                          │
│  │   ├── Story → Epic 브랜치 (base)                              │
│  │   ├── Epic → development (base)                              │
│  │   └── 독립 이슈 → development (base)                          │
│  ├── 🆕 작업내역 페이지 발행 → URL 확보 (실패 시 마크다운 폴백)   │
│  ├── gh pr create --base {target_branch} (본문에 링크 블록 포함) │
│  ├── Closes #{issue_number} 자동 포함                           │
│  └── ZenHub PR 연결                                             │
│                                                                 │
│  Step 10: Review/QA 이동                                        │
│  ├── mcp__zenhub__moveIssueToPipeline                           │
│  └── Pipeline: Review/QA                                        │
│                                                                 │
│  Step 10.5: CI 대기 ∥ 작업내역 아티팩트 CI 상태 갱신              │
│  ├── gh pr checks --watch 를 백그라운드로 먼저 띄움 ⚠️ 순서 고정  │
│  ├── CI 결과 회수(join) → 같은 URL 로 페이지 내용만 갱신 (댓글 X) │
│  ├── 갱신 실패/도구 부재 → 기존 URL 그대로 유지, 워크플로 계속    │
│  ├── CI 실패/판정불가 → throw (L-10.6 최대 3 라운드, 머지 차단)  │
│  └── 체크 0건 → default base 면 차단, 그 외 PR body 기록          │
│                                                                 │
│  Step 11: 추가 리뷰 피드백 반영                                   │
│  ├── Step 8.7에서 자동 코드 review complete됨                           │
│  ├── PR 리뷰 코멘트 확인 및 추가 피드백 반영                      │
│  ├── 재검토 필요 시 반복                                         │
│  └── /cc-quality:checklist:feature-complete 실행                           │
│                                                                 │
│  Step 11.9: ⛔ 머지 직전 열린-자식 재검증                        │
│  ├── openChildrenStatus (GitHub sub-issues, tri-state)          │
│  ├── open / unknown → 머지 차단 (pre-authorized 도 못 덮음)      │
│  └── 근거: CI·리뷰 사이에 자식이 늘거나 재오픈될 수 있음         │
│                                                                 │
│  Step 12: 머지 승인 대기 (머지 = Close)                          │
│  ├── user approval 요청 (pre-authorized 면 질문만 생략)          │
│  ├── S12g ⛔ gh pr checks 재조회 — 전부 통과일 때만 머지         │
│  ├── 승인 시 스쿼시 머지                                         │
│  ├──  " 수정 필요 "   → enterRework( " S7R " ): 게이트 10개 pending 복귀  │
│  └── GitHub  " Closes # "   키워드로 이슈 자동 Close 시도            │
│                                                                 │
│  Step 12.5: 이슈 Close 검증 + 폴백 ⭐ (ZenHub 2-상태 모델) ⚠️     │
│  ├── GitHub state 확인 (open/closed의 source of truth)           │
│  │   └── 미close 시 gh issue close 로 명시적 종료                 │
│  ├── ZenHub Closed 동기화 확인 (GitHub closed = Closed 1:1)      │
│  │   └── 동기화 지연 시 updateIssue state:CLOSED 강제            │
│  ├── ⛔ 열린-자식 불변식 최종 확인                                │
│  │   └── 위반 시 gh issue reopen + 코멘트 + In Progress 복구      │
│  ├── PR base 브랜치로 이동 + git pull (최신화) ⭐               │
│  └── Step 12.6: Orca 워크트리 반납  " 표시 "   (비차단)               │
│      └── ⛔ 자기 제거 금지 — 회수는 상위 batch 의 머지 큐         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

# 현재 브랜치 확인
BRANCH=$(git rev-parse --abbrev-ref HEAD)

# development/main 체크
if [[ $BRANCH ==  " development "   || $BRANCH ==  " main "   ]]; then
  echo  " ❌ development/main에 직접 커밋할 수 없습니다 " 
   echo  "     /cc-dev:run 스킬은 반드시 feature 브랜치에서 작업합니다 " 
   echo  " " 
   echo  "     올바른 사용법: " 
   echo  "     1. /cc-dev:run \ " 작업 내용\ "   - 이슈 생성부터 시작 " 
   echo  "     2. /cc-dev:run {number} - 기존 이슈로 시작 " 
   exit 1
fi

# ⭐ 이슈번호 포함 검증 (이슈 추적 용이): {type}/{issue_number}-{slug}
#    브랜치 생성 직후 조기 게이트 — 번호 누락을 Step 9(PR 직전)까지 미루지 않고 즉시 차단
if [[ ! $BRANCH =~ ^(initiative|project|epic|story|task|feature|fix|refactor|chore)/[0-9]+- ]]; then
  echo  " ❌ 브랜치명에 이슈번호가 없습니다: $BRANCH " 
   echo  "     형식: {type}/{issue_number}-{slug}  (예: feature/1810-author-list) " 
   echo  "     이슈 추적을 위해 브랜치명에 반드시 이슈번호가 포함돼야 합니다. " 
   echo  "     /cc-dev:run 은 이슈 생성(Step 2) 후 자동으로 번호를 포함해 브랜치를 만듭니다. " 
   exit 1
fi

// 실행 순서대로 나열한 노드 id — flow 블록의 파생. 정수/소수점을 구분하지 않는다.
// (S7f/S7j/S8w/S8j 는 Step 7·8 항목 안, S12b/S12g/S12m 은 Step 12 항목 안, S12.6 은 Step 12.5 항목
//  안, S7R/S6R 은 되돌림 루프이므로 독립 항목을 갖지 않는다 — enterRework() 가 대신 항목들을
//  pending 으로 되돌린다. S12.6 은 비차단 후처리라 뒤에 게이트할 단계가 없다 — 독립 항목으로
//  올리면 no-op 케이스가 영구 pending 으로 남아 시드만 흐려진다.)
const STEP_ORDER = [
   " 0 " ,  " 0.1 " ,  " 0.5 " ,  " 0.6 " ,  " 1 " ,  " 1.5 " ,  " 2 " ,  " 3 " ,  " 4 " ,  " 5 " ,  " 6 " ,
   " 7 " ,  " 7.1 " ,  " 7.2 " ,  " 7.3 " ,  " 7.5 " ,  " 7.7 " ,
   " 8 " ,  " 8.3 " ,  " 8.5 " ,  " 8.7 " ,
   " 9.0 " ,  " 9 " ,  " 10 " ,  " 10.5 " ,  " 11 " ,  " 11.9 " ,  " 12 " ,  " 12.5 " ,
];

// 비차단 노드(flow 블록의 `.. > `) — 시드에는 있지만 전제조건으로 세지 않는다.
// Step 7.1 은 참고 단계이므로 pending 으로 남아도 다음 단계를 막아선 안 된다.
const ADVISORY_STEPS = new Set([ " 7.1 " ]);

// 단계 전제조건 검증 — stepId 는 문자열( " 8.5 " )이다. 숫자로 받으면 8.5 가 다시 8 로 접힌다.
async function validateStepPrerequisites(stepId: string) {
  const todos = await getTodoList();
  const upto = STEP_ORDER.indexOf(String(stepId));
  if (upto  <   0) {
    throw new Error(`❌ 알 수 없는 단계 id: ${stepId} — STEP_ORDER 에 없다(flow 블록과 동기화 필요)`);
  }

  for (const id of STEP_ORDER.slice(0, upto)) {
    if (ADVISORY_STEPS.has(id)) continue;

    // 정확 일치 — startsWith 는  " Step 1 "   이  " Step 1.5 " / " Step 12 "   를 삼킨다
    const step = todos.find(t = >   t.content.match(/^Step ([0-9]+(?:\.[0-9]+)?)/)?.[1] === id);

    // 항목 자체가 없으면  " 검사할 게 없어서 통과 " 가 아니다 — 시드 누락이 곧 게이트 소멸이다(FO-03 계열)
    if (!step) {
      throw new Error(
        `❌ Step ${id} 항목이 TodoWrite 시드에 없습니다 — 시드는 STEP_ORDER 1 항목당 1개여야 합니다. ` +
        `시드를 갱신하고 재실행하세요 (검증 불가 ≠ 통과)`
      );
    }
    if (step.status !==  " completed "   & &   step.status !==  " skipped " ) {
      throw new Error(`
        ❌ Step ${id}이(가) 완료되지 않았습니다.
        현재 상태: ${step.status ||  ' unknown ' }

        먼저 Step ${id}을(를) 완료해주세요.
      `);
    }
  }
}

const jiraKeyPattern = /^([A-Z][A-Z0-9]+)-(\d+)$/;
const jiraUrlPattern = /atlassian\.net\/browse\/([A-Z][A-Z0-9]+-\d+)/;

function resolveJiraRef(input: string): string | null {
  const fromUrl = input.match(jiraUrlPattern)?.[1];
  if (fromUrl) return fromUrl;
  return jiraKeyPattern.test(input) ? input : null;
}

let workContent = rawInput;   // rawInput = 사용자가 넘긴 원본 인자
let jiraIssueKey = null;      //  " UB-123 "   — 전체 키, Step 2 제목 접두사용
let jiraProjectKey = null;    //  " UB "   — Step 2 라벨용

// `startedFrom` 은 Step 0.1(아래  " Execution Flow "   참조)에서 이미 판별돼 있다 —
// 이 Step 1.0 은 `startedFrom ===  " jira " ` 일 때만 본문을 가져온다.
const jiraRef = resolveJiraRef(rawInput);
if (jiraRef) {
  // ⛔ createJiraIssue/editJiraIssue 금지 — 읽기 전용 조회만
  const jiraIssue = await mcp__atlassian__getJiraIssue({ issueKey: jiraRef });
  jiraIssueKey = jiraIssue.key;                     //  " UB-123 " 
   jiraProjectKey = jiraIssue.fields.project.key;    //  " UB " 
   workContent = jiraIssue.fields.description
    ? `${jiraIssue.fields.summary}\n\n${jiraIssue.fields.description}`
    : jiraIssue.fields.summary;
  console.log(`🔗 Jira 티켓 가져옴 (읽기 전용): ${jiraIssueKey}`);
}

// 키워드 기반 타입 자동 추론
const typeKeywords = {
  feat: [ " 추가 " ,  " 구현 " ,  " 생성 " ,  " 만들기 " ,  " 화면 " ],
  fix: [ " 수정 " ,  " 고치기 " ,  " 버그 " ,  " 에러 " ,  " 문제 " ],
  refactor: [ " 개선 " ,  " 리팩토링 " ,  " 정리 " ,  " 최적화 " ],
  chore: [ " 설정 " ,  " 빌드 " ,  " 환경 " ,  " 배포 " ],
  docs: [ " 문서 " ,  " README " ,  " 주석 " ],
  test: [ " 테스트 " ,  " test " ,  " 검증 " ],
};

// 화면 타입 감지
const screenKeywords = {
  list: [ " 목록 " ,  " 리스트 " ,  " list " ,  " 조회 " ,  " 검색 " ],
  detail: [ " 상세 " ,  " detail " ,  " 보기 " ],
  form: [ " 추가 " ,  " 생성 " ,  " 수정 " ,  " 편집 " ,  " form " ,  " 등록 " ],
};

const analysis = {
  type: inferType(workContent),      // feat/fix/refactor...
  scope: extractScope(workContent),  // feature명
  screenType: detectScreen(workContent), // list/detail/form/null
  point: estimatePoint(workContent), // 1/3/5/8
  requiresBdd: screenType !== null,  // screen feature이면 true
  jiraIssueKey,                      // Step 1.0에서 설정, 아니면 null — Step 2 제목 접두사용
  jiraProjectKey,                    // Step 1.0에서 설정, 아니면 null — Step 2 라벨용
};

if (!options.skipPm) {
  // work_content에서 URL 추출 (피그마 등)
  const figmaUrl = extractFigmaUrl(workContent);

  // 기존 확정(LOCKED) 기획 명세가 있으면 우선 사용
  const lockedSeedSpec = await findLockedSeedSpec(analysis.scope); // docs/seed-spec-*.md

  let pmSpec;
  try {
    pmSpec = await Task({
      subagent_type:  " pm-spec-agent " ,
      prompt: `
        work_content: ${workContent}
        initial_analysis: ${JSON.stringify(analysis)}
        explicit_options: ${JSON.stringify({ type: options.type, scope: options.scope, point: options.point })}
        figma_url: ${figmaUrl ??  " none " }
        locked_seed_spec: ${lockedSeedSpec ??  " none " }

        이 작업 요청을 PM 관점(FR/AC, 스코프 In/Out, Fibonacci Story Point)으로 정리해줘.
        애매한 부분은 묻지 말고 합리적으로 가정한 뒤  " Assumptions " 에 명시하고 진행해.
      `,
    });
  } catch (e) {
    console.warn( " ⚠️ PM 요구사항 정제 실패 — Step 1 키워드 추론 결과로 폴백: " , e?.message ?? e);
    pmSpec = null; // degrade, don ' t throw (GD-01과 동일한 계약)
  }

  if (pmSpec) {
    // 명시적 옵션은 그대로 유지, 나머지는 pmSpec으로 승격
    analysis.type = options.type ?? pmSpec.type;
    analysis.scope = options.scope ?? pmSpec.scope;
    analysis.point = options.point ?? pmSpec.point;
    analysis.requiresBdd = pmSpec.screenTypes.length  >   0;
    analysis.issueBody = pmSpec.body; // Step 2가 그대로 사용
  }
} else {
  console.warn( " ⚠️ PM 요구사항 정제를 건너뜁니다 (--skip-pm) " );
}

// 이슈 타입 매핑
const issueTypeMap = {
  feat:  " Feature " ,
  fix:  " Bug " ,
  refactor:  " Task " ,
  chore:  " Task " ,
  docs:  " Task " ,
  test:  " Task " ,
};

// Jira 티켓에서 시작한 경우의 제목 접두사 / 라벨 / 본문 출처 표기 (analysis.jiraIssueKey가 null이면 전부 no-op)
const jiraTitlePrefix = analysis.jiraIssueKey ? `${analysis.jiraIssueKey}: ` :  " " ;
const jiraLabels = analysis.jiraProjectKey ? [`JIRA-${analysis.jiraProjectKey}`] : [];
const jiraBodyFooter = analysis.jiraIssueKey ? `\n\n---\n🔗 Source: Jira ${analysis.jiraIssueKey} (read-only import)` :  " " ;

// 아티팩트 발행 (이슈 생성보다 반드시 먼저 — 역순이면 링크 없는 본문이 먼저 생긴다)
// SoT: rules/zenhub-conventions.md → Issue Body Artifact Contract
// analysis.narrative 는 Step 1.5(pm-spec-agent)의 서술 원고. --skip-pm 이면 비어 있다.
let artifactUrl = null;
if (analysis.narrative  & &   lineCount(analysis.narrative)  >   20  & &   isAvailable( " Artifact " )) {
  try {
    // 경로는 이슈당 고정 — 같은 경로로 재발행하면 같은 URL 이 유지된다
    artifactUrl = await Artifact({
      file_path: `.claude/docs/${analysis.scope}/issue-${slugify(analysis.scope)}.html`,
      favicon:  " 📄 " ,              // 재발행 간 고정
      description: `${analysis.scope} 상세 기획`,
    });
  } catch {
    artifactUrl = null;           // 발행 실패는 이슈 생성을 막지 않는다
  }
}
if (!artifactUrl  & &   analysis.narrative) {
  console.log( " ℹ️ Artifact 미사용 — 전량 마크다운 본문으로 생성 " );
}

// GitHub 이슈 생성
// analysis.issueBody는 Step 1.5(pm-spec-agent)가 채운 계약 블록 — --skip-pm 이거나 정제 실패 시 폴백
// artifactUrl 이 있으면  ' ## 📄 상세 기획 '   링크 블록(🔒 공유 안내 포함)을 계약 블록 앞에 붙이고,
// 없으면 narrative 를 계약 블록 뒤에 그대로 합쳐 종전 전량 마크다운으로 만든다.
const issueBody = artifactUrl
  ? linkBlock(artifactUrl, analysis.narrativeSections) + (analysis.issueBody ?? generateIssueBody(workContent, analysis))
  : (analysis.issueBody ?? generateIssueBody(workContent, analysis)) + (analysis.narrative ??  " " );

const issue = await mcp__zenhub__createGitHubIssue({
  repositoryId: githubRepoId,
  title: `${jiraTitlePrefix}${gitmoji} ${analysis.scope}: ${workContent}`,
  body: issueBody + jiraBodyFooter,
  issueTypeId: getIssueTypeId(issueTypeMap[analysis.type]),
  labels: [...generateLabels(analysis), ...jiraLabels],
});

// Estimate 설정
await mcp__zenhub__setIssueEstimate({
  issueId: issue.id,
  estimate: analysis.point,
});

// ⛔ createJiraIssue / editJiraIssue / transitionJiraIssue 금지 — 조회 도구만 사용
try {
  if (analysis.jiraIssueKey) {
    // 직접 조회 — Step 1.0에서 가져온 원본 Jira 티켓이 여전히 유효한지만 확인
    const src = await mcp__atlassian__getJiraIssue({ issueKey: analysis.jiraIssueKey });
    console.log(`🔎 Jira 원본 확인: ${src.key} — ${src.fields.status.name}`);
  } else {
    // 읽기 전용: 생성된 이슈가 Jira에서도 조회되는지 확인 (예: GitHub 이슈 번호로 검색)
    const found = await mcp__atlassian__searchJiraIssuesUsingJql({
      jql: `text ~  " #${issue.number} "   ORDER BY created DESC`,
      maxResults: 5,
    });
    if (found?.issues?.length) {
      console.log(`🔎 Jira 확인: ${found.issues.map(i = >   i.key).join( " ,  " )}`);
    } else {
      console.log( " 🔎 Jira 확인: 매칭 이슈 없음 (읽기 전용 확인, 워크플로 계속) " );
    }
  }
} catch (e) {
  console.warn( " 🔎 Jira 조회 건너뜀 (읽기 전용, non-blocking): " , e?.message ?? e);
}

// ── 파이프라인 ID 일괄 해석 (fail-closed) ─────────────────────────
// ⚠️ 과거엔 productBacklogPipelineId/inProgressPipelineId/reviewQaPipelineId 가
//    어디에서도 해석되지 않아 move 가 pipelineId=undefined 로 silent no-op 였다(C3).
//    이름이 라이브 파이프라인과 다르면 throw — 무음 누락 금지.
const workspace = await mcp__zenhub__getWorkspacePipelinesAndRepositories();
const pipelineId = (name) = >   {
  const p = workspace.pipelines.find(p = >   p.name === name);
  if (!p) throw new Error(`파이프라인  ' ${name} '   없음. 라이브: ${workspace.pipelines.map(p = >   p.name).join( " ,  " )}`);
  return p.id;
};
const productBacklogPipelineId = pipelineId( " Product Backlog " );
const inProgressPipelineId     = pipelineId( " In Progress " );
const reviewQaPipelineId       = pipelineId( " Review/QA " );

// ⚠️ 이 블록은 Step 3 과 Step 5 를 함께 담고 있지만 **실행 조건이 다르다**:
//    - Step 3(Product Backlog 이동)·Step 2.5(스프린트 배정) → 이슈를 **새로 만든 경로 전용**.
//      `/cc-dev:run {number}`(기존 이슈로 시작)는 Steps 1–3 을 건너뛰므로 해당 없음.
//    - Step 4(브랜치)·**Step 5(In Progress 이동 + 부모 cascade)** → **모든 경로에서 항상 실행**.
//      `/cc-dev:batch` 는 leaf 를 항상 `/cc-dev:run {number}` 로 위임하므로, Step 5 를
//       " Steps 1–3 생략 " 에 휩쓸려 같이 건너뛰면 **보드가 통째로 멈춘다**(Epic 은 Product Backlog,
//      자식은 Product Backlog — 실제로 개발이 도는 동안 아무 칸도 움직이지 않는 상태).

// ── Step 3: Product Backlog 이동 (이슈 신규 생성 경로 전용) ───────
if (startedFrom ===  " work_content "   || startedFrom ===  " jira " ) {
  await mcp__zenhub__moveIssueToPipeline({
    issueId: issue.id,
    pipelineId: productBacklogPipelineId,
  });
}

// ── Step 2.5: 스프린트 배정 (타임라인 가시성 — 신규 생성 경로 전용) ──
// 저수준 타입(Feature/Bug/Task)은 setDatesForIssue(상위 타입 전용)를 쓰지 않고
// 활성 스프린트에 넣어 로드맵/번다운에 노출한다. 기본 on, --no-sprint 로 opt-out.
if (!options.noSprint  & &   startedFrom !==  " issue_number " ) {
  // --sprint 셀렉터: next → 다음(getUpcomingSprint), 그 외(기본 current) → 활성(getSprint)
  const sprint = options.sprint ===  " next " 
     ? await mcp__zenhub__getUpcomingSprint()
    : await mcp__zenhub__getSprint();            // id 없음 = 활성 스프린트
  if (sprint?.id) {
    await mcp__zenhub__addIssuesToSprints({ issueIds: [issue.id], sprintIds: [sprint.id] });
    console.log(`📅 스프린트 배정: ${sprint.name ?? sprint.id}`);
  } else {
    console.warn( " ⚠️ 활성 스프린트 없음 — 스프린트 미배정(로드맵 비가시 가능) " );
  }
}

// ═══════════════════════════════════════════════════════════
// Step 4: 계층 브랜치 전략 - base 브랜치 동적 결정
// ═══════════════════════════════════════════════════════════

// 4-1. 부모 이슈 감지
let baseBranch = options.base ||  " development " ;
let parentIssue = null;

if (!options.base) {
  // ⚠️ ZenHub MCP 에는 id 로 단건 이슈를 가져오는 도구가 없다(getIssue/getChildrenOfParent 미존재).
  //    이슈와 그 부모는 searchLatestIssues 의 nested parentIssue 로 조회한다.
  const issueDetails = await mcp__zenhub__searchLatestIssues({
    query: `#${issue.number}`,
  });
  const self = issueDetails.find(i = >   i.number === issue.number);
  parentIssue = self?.parentIssue ?? null;   // { id, number, title, issueType }

  if (parentIssue) {
    // 부모 브랜치를 확보(없으면 조부모 기반으로 재귀 생성)하고 그 위에서 분기한다.
    // resolveBaseBranch 가 searchLatestIssues 로 계층을 거슬러 올라가며 브랜치를 보장한다.
    baseBranch = await resolveBaseBranch(parentIssue.number);
    console.log(`📐 계층 브랜치: ${baseBranch} 기반으로 분기`);
  }
}

// 4-4. 브랜치 생성 (base 브랜치에서 분기)
await Task({
  subagent_type:  " issue-branch-agent " ,
  prompt: `이슈 #${issue.number} 브랜치 생성 (base: ${baseBranch})`,
  // base_branch 파라미터 전달
});

// ═══════════════════════════════════════════════════════════
// Step 5: In Progress 이동 (⭐ 모든 진입 경로에서 항상 실행 — 생략 불가)
// ═══════════════════════════════════════════════════════════
await mcp__zenhub__moveIssueToPipeline({
  issueId: issue.id,
  pipelineId: inProgressPipelineId,
});

// ⭐ 부모 체인 cascade — 부모(Epic/Project/Initiative)가 아직 착수 전 칸
//    (New Issues/Icebox/Product Backlog/Sprint Backlog)이면 조부모까지 함께 In Progress 로.
//    멱등(이미 In Progress 이상이면 즉시 멈춤) · 닫힌 부모는 건드리지 않음 · 역행 금지.
//    SoT: agents/dev/issue-state-agent.md →  " Automatic Parent Start Cascade " 
 //    ⚠️ 이 호출이 빠지면 자식은 In Progress 인데 Epic 은 Product Backlog 에 남아,
//       보드만 보는 사람에게  " 아직 손도 안 댄 Epic " 으로 보인다.
await cascadeStartToParents(issue.number);

// 읽어서 확인 — pipelineId 오류/권한 문제로 인한 무음 누락 금지
// (위 두 호출은 ../rules/zenhub-conventions.md 의 `reflectBoardState(issue,  " started " )` 와 같은 일을 한다.
//  read-back 은 그 계약의 원칙 3 이다 — 새 검증을 여기서 만드는 것이 아니다)
const afterMove = (await mcp__zenhub__searchLatestIssues({ query: `#${issue.number}` }))
  .find(i = >   i.number === issue.number);
if (afterMove?.pipelineIssue?.pipeline?.name !==  " In Progress " ) {
  console.warn(`⚠️ #${issue.number} In Progress 이동 미확인 (현재: ${afterMove?.pipelineIssue?.pipeline?.name ??  " 조회 실패 " })`);
}

// ⭐ 점유 획득 — In Progress 이동과 **같은 자리**다 (SoT: ../rules/zenhub-conventions.md → Work Claim Contract)
//    ⚠️ 이동만 하고 대장을 쓰지 않으면, 다음 세션은 이 In Progress 가 **내 작업인지 부모 cascade 인지
//       구분할 수 없다** — 그 순간 Step 0.4 가 가진 유일한 신호가 사라진다.
//    ⛔ cascadeStartToParents() 는 대장을 쓰지 않는다. 부모를 잡으면 형제 Epic 이 전부 막힌다.
await acquireClaim(issue, { branch: branchName });   // state: held · owner/run/started/heartbeat 기록
// 이후 각 Step 경계에서 heartbeat(issue) — 마지막 기록이 20분 이내면 생략한다(API 왕복 절약)

// ── 계층 브랜치 해석 계약 구현 (SoT: skills/branch-hierarchy/SKILL.md) ──────────

let _remoteSynced = false;
async function syncRemoteRefs() {                                    // R1
  if (_remoteSynced) return;
  // ⚠️ fetch 없이 origin/* 를 읽으면 다른 머신이 만든 브랜치가  " 없음 "   으로 보인다.
  await Bash(`git fetch origin --prune --quiet || git fetch origin --prune`);
  _remoteSynced = true;
}

// 이슈 레벨 → 계층 브랜치 prefix. resolveBaseBranch 와 S12b 가 공유한다(두 곳에 복제 금지).
function hierarchyPrefixOf(issue): string {
  return issue.issueType ===  " Initiative "   ?  " initiative "   :
         issue.issueType ===  " Project "   ?  " project "   :
         issue.issueType ===  " Epic "   ?  " epic "   :
         issue.issueType ===  " Sub-task "   ?  " task "   :
         issue.parentIssue ?  " story "   :  " feature " ;
}

// 원격에 직접 물어 이 이슈의 계층 브랜치 후보를 전부 찾는다.
// R2: 식별자는 **이슈 번호**다. 재계산한 slug 로 완전일치를 요구하지 않는다
//     (로마자 변환은 세션마다 갈리고, 제목이 수정되면 아예 달라진다).
// baseHint 는 **대장 기록용**이다 — R4 의 커밋 수 비교는 후보들의 공통 조상을 스스로 구한다.
async function findExistingHierarchyBranch(prefix: string, issueNumber: number, baseHint: string): Promise < string | null >   {
  await syncRemoteRefs();
  const raw = await Bash(
    `git ls-remote --heads origin  " refs/heads/${prefix}/${issueNumber}-* "   | sed  ' s|.*refs/heads/|| ' `
  );
  const candidates = raw.split( " \n " ).map(s = >   s.trim()).filter(Boolean);
  if (candidates.length === 0) return null;
  if (candidates.length === 1) return candidates[0];

  // R4 — 후보 2개 이상: 결정적으로 고르고, 고른 사실을 남긴다 (조용한 선택 금지)
  const registered = await readBranchRegistry(issueNumber);          // R3
  let picked = registered  & &   candidates.includes(registered) ? registered : null;
  if (!picked) {
    const prs = JSON.parse(await Bash(
      `gh pr list --state open --json baseRefName,headRefName --limit 100 2 > /dev/null || echo  " [] " `
    ));
    const inPr = candidates.filter(c = >   prs.some(p = >   p.baseRefName === c || p.headRefName === c));
    if (inPr.length === 1) picked = inPr[0];
  }
  if (!picked) {
    // 실제 작업이 쌓인 쪽을 고른다 — ⚠️ 고정 기준(development)으로 세면 안 된다.
    //   후보들의 **fork point 가 다르면**(하나는 initiative/10-x, 하나는 development 에서 갈라짐)
    //   `development..후보` 는 물려받은 조상 커밋까지 세므로 **작업이 없는 쪽이 이긴다**.
    const mergeBase = (await Bash(
      `git merge-base --octopus ${candidates.map(c = >   `origin/${c}`).join( "   " )}`
    )).trim();
    const counts = await Promise.all(candidates.map(async c = >   ({
      c, n: parseInt((await Bash(`git rev-list --count ${mergeBase}..origin/${c}`)).trim(), 10),
    })));
    // 조회 실패(NaN)를 0 으로 뭉개지 않는다 — 하나라도 실패하면 3번을 버리고 4번(사전순)으로 간다.
    if (counts.some(x = >   Number.isNaN(x.n))) {
      picked = [...candidates].sort()[0];
    } else {
      counts.sort((a, b) = >   b.n - a.n || a.c.localeCompare(b.c));
      picked = counts[0].c;
    }
  }
  // 조용한 선택 금지 — 콘솔 + 이슈 코멘트 양쪽에 남긴다. 탈락 후보는 **삭제하지 않는다**
  // (다른 머신에 아직 push 되지 않은 작업이 그 위에 있을 수 있다).
  console.warn(`⚠️ 중복 계층 브랜치 #${issueNumber}: ${candidates.join( " ,  " )} → 채택  ' ${picked} ' `);
  const note = `⚠️ 계층 브랜치가 ${candidates.length}개 발견되어  ' ${picked} '   를 채택했습니다 `
    + `(branch-hierarchy R4). 후보: ${candidates.join( " ,  " )} — 나머지는 삭제하지 않았습니다.`;
  await Bash(`gh issue comment ${issueNumber} --body ${JSON.stringify(note)}`);
  await recordBranchRegistry(issueNumber, picked, baseHint);         // 다음 세션은 1번에서 끝난다
  return picked;
}

// 대장 read/write 는 branch-hierarchy SKILL.md  " R3 "   의 명령 그대로다(여기서 복제하지 않는다).
//   readBranchRegistry(n)                  → 기록된 브랜치명 또는 null (읽기 실패는 null, 차단 아님)
//   recordBranchRegistry(n, branch, base)  → 마커 코멘트 upsert (실패는 비차단 경고)

// 재귀적 base 브랜치 결정
async function resolveBaseBranch(issueNumber: number): Promise < string >   {
  // ⚠️ getIssue 미존재 → searchLatestIssues 로 이슈 + nested parentIssue 조회
  const _found = await mcp__zenhub__searchLatestIssues({ query: `#${issueNumber}` });
  const issue = _found.find(i = >   i.number === issueNumber);
  if (!issue) throw new Error(`이슈 #${issueNumber} 조회 실패 — base 브랜치 해석 불가`);
  // 계층 브랜치 prefix (branch-hierarchy 스킬 기준, 5레벨 — Orca 도입 이후 Initiative/Project도
  // Epic과 동일하게 자기 브랜치를 가진다):
  //   Initiative → initiative/ · Project → project/ · Epic → epic/ · Sub-task → task/
  //   parent 있는 Feature/Bug/Task(=Story) → story/ · parent 없는 단독 이슈 → 기존 feature/
  //   (이 함수는 계층 케이스 전용 — 단독 이슈는 기존 동작 유지)
  const branchPrefix = hierarchyPrefixOf(issue);
  // ⭐ 1순위: **이미 원격에 있는 브랜치를 찾는다** (R1·R2·R4)
  //    다른 머신/세션이 만든 브랜치는 slug 가 다를 수 있으므로 번호 글롭으로 찾는다.
  const found = await findExistingHierarchyBranch(branchPrefix, issue.number,  " development " );
  if (found) return found;

  // 없을 때만 부모를 거슬러 올라간다(있으면 조부모 체인을 건드리지 않는 기존 동작 유지)
  const myBase = issue.parentIssue?.number
    ? await resolveBaseBranch(issue.parentIssue.number)   // 재귀 — 조부모까지 브랜치 보장
    :  " development " ;

  // ⭐ 2순위: 대장에 이름이 있으면 **그 이름 그대로** 재생성한다 (R3)
  //    새 slug 를 만들면 이름이 갈리는 원인을 그대로 재현하는 짓이다.
  const registered = await readBranchRegistry(issue.number);
  // createSlug romanizes non-ASCII and never returns  ' '   (see issue-branch-agent.md). Pass type word for the empty-guard fallback.
  const slug = createSlug(issue.title, branchPrefix);
  const branchName = registered ?? `${branchPrefix}/${issue.number}-${slug}`;
  // Defense-in-depth (LANG-05): a non-romanized Korean-only title must not yield  " feature/25- " .
  if (!registered  & &   (!slug || branchName.endsWith( " - " ))) {
    throw new Error(`빈 slug — 브랜치명 비정상(${branchName}). 제목 로마자 변환 확인 필요`);
  }

  // ⭐ 생성 — base 를 최신화한 뒤 분기하고, **커밋이 0개여도 즉시 push** 한다 (R6).
  //    push 하지 않은 계층 브랜치는 다른 머신에서 존재하지 않는 것과 같고,
  //    `gh pr create --base` 도 그 브랜치를 찾지 못한다.
  //
  // ⛔ base 를 **체크아웃하지 않는다.** `git checkout ${myBase}` 는 그 브랜치가 같은 머신의
  //    **다른 워크트리에 이미 체크아웃돼 있으면 fatal 로 죽는다**:
  //      fatal:  ' development '   is already used by worktree at  ' /path/to/other ' 
   //    Orca 병렬 워크트리 운영에서는 base(=development 등)를 상주 워크트리가 점유하는 것이
  //    **정상 상태**라, 종전의 `git checkout ${myBase} ... || exit 1` 은 그 환경 전체에서
  //    **항상 실패**했다(실측). base 는 분기점으로만 필요하므로 원격 ref 에서 직접 자른다 —
  //    체크아웃이 필요 없을 뿐 아니라, fetch 로 얻은 origin ref 가 로컬 브랜치보다 정확하다.
  await Bash(`
    git fetch origin ${myBase} --quiet || exit 1
    # ⚠️ 같은 이름의 **로컬** 브랜치를 무조건 채택하지 않는다 — 원격이 squash 머지 후 삭제된 뒤
    #    남아 있는 낡은 로컬본을 push 하면 **이미 정리된 diff 를 통째로 되살린다**(squash 커밋은
    #    그 커밋들의 조상이 아니므로 계보 검사에도 안 걸린다).
    if git rev-parse --verify ${branchName}  > /dev/null 2 > & 1; then
      if git merge-base --is-ancestor origin/${myBase} ${branchName}; then
        git checkout ${branchName}                                   # myBase 를 포함 → 이어받는다
      else
        git branch -m ${branchName} ${branchName}-stale-$(date +%s)  # 낡은 로컬본은 보존만
        git checkout -B ${branchName} origin/${myBase}
      fi
    else
      git checkout -B ${branchName} origin/${myBase}
    fi
  `);
  const pushed = await Bash(`git push -u origin ${branchName} 2 > & 1 || echo  " __PUSH_REJECTED__ " `);
  if (pushed.includes( " __PUSH_REJECTED__ " )) {
    // R5 — 그 사이 다른 머신이 먼저 만들었다. 하드 실패도, 새 이름 생성도 하지 않는다.
    // ⚠️ 자기 커밋이 0개면 rebase 하지 않는다 — 그 상태의 `origin/{branch}..HEAD` 는
    //    **base 브랜치의 커밋들**이라, 이미 upstream 에 있는 커밋을 새 해시로 복제해 공유
    //    브랜치에 push 하게 된다(컨테이너→상위 PR diff 오염).
    console.warn(`⚠️ ${branchName} push 거부 — 원격 브랜치를 채택합니다(레이스)`);
    await Bash(`
      git fetch origin ${branchName} || exit 1
      if [  " $(git rev-list --count origin/${myBase}..HEAD) "   -eq 0 ]; then
        git checkout -B ${branchName} origin/${branchName}     # 자기 커밋 없음 → 원격 그대로
      else
        git rebase origin/${branchName} || { echo  " ⛔ rebase 충돌 — 수동 해결 후 재실행 " ; exit 1; }
      fi
      git push -u origin ${branchName}
    `);
  }
  await recordBranchRegistry(issue.number, branchName, myBase);      // R3 — 다음 머신이 이 이름을 쓴다
  console.log(`🌿 계층 브랜치 확보: ${branchName} (base: ${myBase})`);
  return branchName;
}

if (analysis.requiresBdd  & &   !options.skipBdd) {
  // ⚠️ bdd-scenario-agent 는 cc-flutter 가 제공하는 cross-plugin 선택 의존이다(F3).
  //    미설치면 throw 하지 말고 BDD 단계를 skip + 경고하라(미존재 dispatch 를 PASS 로 간주 금지):
  //    if (!isAgentAvailable( " bdd-scenario-agent " )) { console.warn( " ⚠️ BDD skip — cc-flutter 미설치 " ); /* skip BDD */ }
  await Task({
    subagent_type:  " bdd-scenario-agent " ,
    prompt: `
      feature_name: ${analysis.scope}
      screen_type: ${analysis.screenType}

      화면 타입에 맞는 BDD 시나리오를 생성해주세요.
    `,
  });

  // 커밋
  await Bash(`
    git add .
    git commit -m  " test(${analysis.scope}): ✅ BDD 시나리오 작성

    - ${analysis.screenType} 화면 시나리오 추가
    - Step Definition 생성

    Co-Authored-By: Claude  < noreply@anthropic.com > " 
   `);
}

사전 확인 (Step 7 시작 전):
1. CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 환경변수 확인
2. teams_available = true → 병렬 모드 진입
3. teams_available = false → 순차 실행 (아래  " 순차 실행 흐름 "   섹션)
4. 병렬 모드 진입 시 사용자에게 팀 구성 계획 출력 후 승인 요청
   — 무인(--unattended) 계약 ②: 답할 사람이 없으면 승인 없이 스폰하지 않고 순차 실행으로
     강등한다(위 3번 경로) — 기능 차이 없음, 소요 시간만 다름

Agent Teams 사용 가능 시 (tier:standard — 미설정은 기본값이 아니라 degree 2 승수다):
  ├─ Teammate 1: Backend 구현   own: kobic_server/lib/**  (+ kobic_server/pubspec.yaml)
  │   ├─ Serverpod model 정의
  │   ├─ Endpoint 구현
  │   └─ Service 로직
  │       ⛔ melos run backend:pod:generate 는 teammate 가 실행하지 않는다 —
  │          생성물(**/*.g.dart, 클라이언트 패키지)은 두 소유 영역에 동시에 쓰므로
  │          Lead 가 S7j 배리어 이후 Step 7.5 에서 1회만 돌린다 (own:lead)
  │
  └─ Teammate 2: Frontend 구현  own: kobic/lib/**  (+ kobic/pubspec.yaml)
      ├─ Domain Layer (Entity, UseCase, Repository 인터페이스)
      ├─ Data Layer (Repository 구현, DataSource)
      └─ Presentation Layer (BLoC, Page, Widget)

  → S7j JOIN (mode:barrier, because: 프론트↔백엔드 인터페이스는 교차 항목):
    - 프론트/백엔드 인터페이스 일치 확인
    - Import 참조 정합성 확인
    - 이후 생성물 쓰기(Step 7.5)는 Lead 전용

Fallback (순차):
  Backend → Frontend 순차 실행 (기능 차이 없음, 소요 시간만 다름 — agent-teams 의 Fallback Principle)

Agent Teams 사용 가능 시 (tier:standard) — 각 teammate 는 테스트 코드를 **작성만** 한다:
  ├─ Teammate 1: Frontend Unit + BLoC 테스트   own: kobic/test/** (unit·bloc 하위)
  │   ├─ UseCase 단위 테스트 (unit-test-agent)
  │   └─ BLoC 단위 테스트 (bloc-test-agent)
  │
  ├─ Teammate 2: Backend Unit + Integration 테스트  own: kobic_server/test/**
  │   ├─ 엔드포인트 단위 테스트 (serverpod-test-agent)
  │   ├─ 서비스 로직 단위 테스트
  │   └─ 엔드포인트 통합 테스트 (코드 작성까지)
  │
  └─ Teammate 3: BDD Patrol 테스트 (screen feature 시)  own: kobic/integration_test/**
      ├─ Gherkin 시나리오 검증
      └─ Step Definition 작성

  ⛔ teammate 는 `flutter test` / `dart test` 를 실행하지 않는다 — 세 teammate 가 **같은 워크트리**를
     공유하므로 포트·시뮬레이터·빌드 산출물 슬롯이 하나뿐이고(런타임 격리는 워크트리 경로에서 결정적으로
     뽑힌다: `skills/parallel-test-env/SKILL.md`), 동시 실행은 서로의 결과를 오염시킨다.

  → S8j JOIN (mode:barrier + serialize:1, because: 실행 슬롯이 하나뿐):
    - Lead 가 `/cc-dev:pr:preflight --auto-scope` 로 **한 번에 직렬 실행**
    - 전체 tests passed 여부 집계 (미실행 항목은 PASS 아님 — FO-04)
    - 실패 시 PR 생성 차단 → flow 블록 `S8 == >   S7R`

Fallback (순차):
  Unit → BLoC → Backend → BDD 순차 작성 후 동일하게 Lead 가 실행

// 버그가 아니면 no-op. 화면 기능의 디자인 대조는 Step 7.3 이 따로 담당한다(서로 다른 검증이다).
if (analysis.type ===  " fix " ) {
  // 기기 부재·--skip-device 는 **무음 스킵이 아니다** — bugfix.md Step 3.5 의 확인 + 기록 계약을 따른다
  // (waivedGates:  " runtime-repro " , 원인은  ' 추정(런타임 미검증) ' 으로 PR 에 남는다).
  prBodyExtras.runtimeDiagnosis = await runBugfixRuntimeDiagnosis(issue, {
    device: options.device, skipDevice: options.skipDevice, unattended: options.unattended,
  });
}

// 구현 작업 — 버그 이슈면 위 Step 7.0 의 rootCause(file:line)를 근거로 고친다(추측 수정 금지)
await Task({
  subagent_type:  " implementation-agent " ,
  prompt: `이슈 #${issue.number} 구현`,
});

// Backend 변경 감지
const hasBackendChanges = detectBackendChanges(issue);

// 테스트 작성 및 검증 (필수 게이트) ⚠️
if (!options.skipTests) {
  const testTypes = [ " unit " ,  " bloc " ];
  if (analysis.requiresBdd) testTypes.push( " bdd " );
  if (hasBackendChanges) testTypes.push( " backend_unit " ,  " backend_integration " );

  // ──────────────────────────────────────────────────
  // Phase 1: 테스트 플랜 작성
  // ──────────────────────────────────────────────────
  // PR의 Test Plan 항목을 먼저 정의 — 구현 코드의 핵심 동작 시나리오
  const testPlan = generateTestPlan({
    workContent,
    scope: analysis.scope,
    testTypes,
    hasBackendChanges,
    requiresBdd: analysis.requiresBdd,
  });

  // ──────────────────────────────────────────────────
  // Phase 2: 테스트 플랜 기반 테스트 코드 작성
  // ──────────────────────────────────────────────────
  await Task({
    subagent_type:  " test-runner-agent " ,
    prompt: `
      feature_name: ${analysis.scope}
      test_types: ${JSON.stringify(testTypes)}
      test_plan: ${JSON.stringify(testPlan)}
      auto_fix: true
      require_tests: true
      write_tests_for_plan: true
    `,
  });

  // ──────────────────────────────────────────────────
  // Phase 3: 테스트 실행 및 결과 수집
  // ──────────────────────────────────────────────────
  // 3-1. 정적 분석 (dart analyze) — 테스트 코드 컴파일 검증
  // FO-10: 파이프 `| grep -c` 는 grep 의 exit code 만 남겨 dart analyze 의 실패(미설치/크래시)를
  //   0( " clean " )으로 가린다. analyze 를 직접 실행해 exit code 로 판정하고,
  //   명령 미실행/비정상 종료는 0 이 아니라 명시 FAIL 로 둔다(검증 불가 ≠ 통과).
  const analyzeRaw = await Bash(
    `dart analyze ${testPlan.map(t = >   t.file).join( '   ' )} 2 > & 1`
  );
  if (analyzeRaw.exitCode === 127 /* command not found */) {
    throw new Error( " dart analyze 실행 실패(도구/스크립트 부재) — 검증 불가 = 차단 (Step 0 도구 점검 참조) " );
  }
  // dart analyze: exit 0 = 이슈 없음, 그 외 = 이슈 존재(또는 실행 오류 → 차단)
  const analyzeErrors = analyzeRaw.exitCode === 0
    ? 0
    : ((analyzeRaw.stdout.match(/^\s*error\b/gim) || []).length || 1);

  // 3-2. 테스트 실행 (정적 분석 통과 시)
  let testResults = { totalPassed: 0, totalFailed: 0, items: [] };
  if (analyzeErrors === 0) {
    const testOutput = await Bash(
      `flutter test ${testPlan.map(t = >   t.file).filter(Boolean).join( '   ' )} 2 > & 1`
    );
    testResults = parseTestOutput(testOutput.stdout);
  }

  // ──────────────────────────────────────────────────
  // Phase 4: 결과를 PR Test Plan에 반영
  // ──────────────────────────────────────────────────
  prBodyExtras.testPlanResults = testPlan.map(item = >   ({
    ...item,
    analyzePass: analyzeErrors === 0,
    testPass: testResults.items.find(r = >   r.name === item.item)?.passed ?? null,
  }));
  prBodyExtras.testSummary = {
    analyzeErrors,
    totalPassed: testResults.totalPassed,
    totalFailed: testResults.totalFailed,
  };

  // ⚠️ 게이트: 정적 분석 실패 시 PR 생성 차단
  if (analyzeErrors  >   0) {
    throw new Error(`테스트 코드 정적 분석 실패 (${analyzeErrors}건) - 에러 수정 후 재시도`);
  }
  // ⚠️ 게이트: 테스트 실패 시 PR 생성 차단 (런타임 실행 가능했던 경우)
  //   flow 블록 `S8 == >   S7R on:test.fail bound:2` — 되돌림·예산은 enterRework() 한 곳에만 있다.
  //   (단순 throw 는  " 다음에 다시 하자 " 로 끝나 이미 completed 인 게이트들을 그대로 남긴다)
  if (testResults.totalFailed  >   0) {
    console.error(`❌ 테스트 ${testResults.totalFailed}건 실패 — Step 7 재작업으로 되돌린다`);
    return await enterRework( " S7R " );
  }
  // ⚠️ 게이트(FO-04): 실행되지 않은(미검증) 테스트는 PASS 로 간주하지 않는다.
  //   testPass === null 은  " 실패 아님 " 이 아니라  " 검증 안 됨 "   → 차단 상태.
  const unverified = prBodyExtras.testPlanResults.filter(r = >   r.testPass === null);
  if (unverified.length  >   0) {
    throw new Error(`테스트 미실행 ${unverified.length}건 — 검증되지 않은 항목은 PASS 로 간주하지 않음(차단)`);
  }
} else {
  // --skip-tests 사용 시 사용자 확인 필수 — flow 블록 `S8 ~~ >   S8.3 record:ASK+prBodyExtras.testsSkipped`
  // 무인(--unattended) 계약 ③: 플래그로 이미 의도를 밝혔으므로 재확인 없이 스킵 확인을 자동 채택한다.
  const confirm = options.unattended
    ?  " 스킵 확인 " 
     : await AskUserQuestion({
        questions: [{
          header:  " 테스트 스킵 확인 " ,
          question:  " 테스트를 스킵하면 검증 없이 PR이 생성됩니다. 계속하시겠습니까? " ,
          options: [
            { label:  " 스킵 확인 " , description:  " 테스트 없이 진행 (긴급 핫픽스용) — PR body에 영구 기록 "   },
            { label:  " 테스트 실행 " , description:  " 테스트를 실행합니다 "   },
          ],
        }],
      });

  // ⚠️ 답을 실제로 분기한다 — 예전에는 물어보고 답을 버려서  " 테스트 실행 " 을 골라도 스킵됐다.
  if (confirm ===  " 테스트 실행 " ) {
    options.skipTests = false;
    return await runFromStep( " 8 " );         // 같은 단계를 테스트 실행 경로로 재진입 (id 는 문자열)
  }

  // ⚠️ 콘솔 경고는 내구 기록이 아니다 — 스킵 사실은 PR body 로 남는다 (Step 7.3 스킵과 동일 처리)
  prBodyExtras.testsSkipped = { reason:  " --skip-tests (user confirmed) " , at: new Date().toISOString() };
  console.warn( " ⚠️ 테스트 스킵 확인됨 — PR body에  ' 테스트 미검증 '   경고 영구 기록 " );
}