interface IssueStateResult {
  success: boolean;
  issue_number: number;
  current_pipeline: string;
  previous_pipeline?: string;
  state:  ' OPEN '   |  ' CLOSED ' ;
  parent_issue?: {
    number: number;
    all_children_done: boolean;
  };
  error?: string;
}

New Issues → Product Backlog → Sprint Backlog → In Progress → Review/QA → [Merge = Close → Closed]

1. Branch creation complete
   → move_pipeline:  " In Progress " 
    → action: claim  (이 세션이 이 이슈를 잡았다는 대장 기록 — 이동과 같은 자리)
   → cascadeStartToParents (부모 체인이 아직 착수 전 칸이면 조부모까지 함께 이동)
   → ⛔ cascade 로 올린 부모에는 claim 을 쓰지 않는다. 부모를 잡으면 형제 작업이 전부 막힌다

2. PR creation complete
   → move_pipeline:  " Review/QA " 
    → ⚠️ deployment-gated trackers (Jira/Unibook): SKIP — keep  " In Progress " ;
     move to  " In Review "   only when the merge is reflected in the staging deploy
     (see rules/deployment-gated-status.md)

3. PR merge complete (merge = Close)
   → Issue auto-closes via GitHub  " Closes # "   keyword → ZenHub syncs to Closed
   → Never move to Done (Done ≠ closed)
   → action: verify_closed  (verify GitHub closed + ZenHub Closed, fallback if not)

4. All child issues completed (parent issue)
   → Close parent issue (directly Close, never via Done)

┌─────────────────────────────────────────────────────────┐
│  Step 1: Query Issue Info                                │
├─────────────────────────────────────────────────────────┤
│  mcp__zenhub__searchLatestIssues                        │
│  - Query issue ID                                        │
│  - Check current Pipeline                                │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 2: Move Pipeline                                   │
├─────────────────────────────────────────────────────────┤
│  mcp__zenhub__moveIssueToPipeline                       │
│  - issueId: {issue_graphql_id}                          │
│  - pipelineId: {target_pipeline_id}                     │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 3: Verify Result                                   │
├─────────────────────────────────────────────────────────┤
│  - Verify move success                                   │
│  - Return current Pipeline                               │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│  Step 1: Close Issue                                     │
├─────────────────────────────────────────────────────────┤
│  mcp__zenhub__updateIssue                               │
│  - issueId: {issue_graphql_id}                          │
│  - state:  " CLOSED "                                        │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 2: Check Parent Issue                              │
├─────────────────────────────────────────────────────────┤
│  IF parent issue exists:                                 │
│    - Check status of all child issues                    │
│    - If all completed → close parent issue               │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│  Step 1: Verify GitHub state (source of truth)          │
├─────────────────────────────────────────────────────────┤
│  $ gh issue view {N} --json state -q .state             │
│  IF state !=  " CLOSED " :                                   │
│    # `Closes #N` did not fire → close explicitly         │
│    $ gh issue close {N} --reason completed               │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 2: Verify ZenHub synced to Closed pipeline        │
├─────────────────────────────────────────────────────────┤
│  mcp__zenhub__searchClosedIssues({ query:  " #{N} "   })     │
│  IF issue not in closed results (sync lag):              │
│    mcp__zenhub__updateIssue({ issueId, state:  " CLOSED "   })│
└─────────────────────────────────────────────────────────┘

// Closure verification + fallback
async function verifyClosed(issueNumber: number, issueId: string) {
  // 0. ⛔ Parent Closure Invariant — 열린 자식 위에서 닫지 않는다.
  //    이 이슈가 컨테이너면, 닫기 전에 자식이 전부 닫혔는지 확인한다.
  //    (rules/zenhub-conventions.md →  " Parent Closure Invariant " )
  const kids = await openChildrenStatus(issueNumber);
  if (kids.status !==  " none " ) {
    // 이미 GitHub 이 `Closes #N` 으로 닫아버린 경우 → 재오픈으로 복구, 아니면 close 자체를 하지 않는다.
    const state = (await Bash(`gh issue view ${issueNumber} --json state -q .state`)).trim();
    if (state ===  " CLOSED "   & &   kids.status ===  " open " ) {
      await Bash(`gh issue reopen ${issueNumber}`);
      await Bash(`gh issue comment ${issueNumber} --body  " ⚠️ 열린 하위 이슈가 남아 재오픈했습니다: ${kids.open.map(c = >   " # "   + c.number).join( " ,  " )} " `);
      // reopen 이후에만 파이프라인 이동 (닫힌 이슈를 열린 칸으로 옮기면 GitHub 이 재오픈시킨다)
      const pipelines = (await mcp__zenhub__getWorkspacePipelinesAndRepositories()).pipelines;
      await mcp__zenhub__moveIssueToPipeline({ issueId, pipelineId: getPipelineId( " progress " , pipelines) }); // 아래 PIPELINE_NAMES 참조 (fail-closed)
    }
    return { success: false, reason: `open_children:${kids.status}`, open: kids.open };
  }

  // 1. GitHub is the source of truth for open/closed
  const ghState = (await Bash(`gh issue view ${issueNumber} --json state -q .state`)).trim();
  if (ghState !==  " CLOSED " ) {
    await Bash(`gh issue close ${issueNumber} --reason completed`);
  }
  // 2. Confirm ZenHub synced GitHub closed → Closed pipeline
  const closed = await mcp__zenhub__searchClosedIssues({ query: `#${issueNumber}` });
  if (!closed.find(i = >   i.number === issueNumber)) {
    await mcp__zenhub__updateIssue({ issueId, state:  " CLOSED "   });
  }
  return { success: true };
}

┌─────────────────────────────────────────────────────────┐
│  Query Issue Status                                      │
├─────────────────────────────────────────────────────────┤
│  mcp__zenhub__searchLatestIssues                        │
│  - Return issue state                                    │
│  - Return Pipeline info                                  │
│  - Return parent/child relationships                     │
└─────────────────────────────────────────────────────────┘

// Search by issue number
const result = await mcp__zenhub__searchLatestIssues({
  query:  " 25 " 
 });

// Extract issue info from result
const issue = result.find(i = >   i.number === 25);
const issueId = issue.id;  // GraphQL ID
const pipelineId = issue.pipelineIssue.pipeline.id;

// Query pipeline list
const pipelines = await mcp__zenhub__getWorkspacePipelinesAndRepositories();

// Find Pipeline ID
const targetPipeline = pipelines.pipelines.find(
  p = >   p.name ===  " In Progress " 
 );

// Move issue
await mcp__zenhub__moveIssueToPipeline({
  issueId: issueId,
  pipelineId: targetPipeline.id
});

// Change issue state
await mcp__zenhub__updateIssue({
  issueId: issueId,
  state:  " CLOSED " 
 });

// Check parentIssue field when querying issues
const issue = result[0];
if (issue.parentIssue) {
  const parentNumber = issue.parentIssue.number;
  // Check all children of the parent issue
}

// Query workspace info
const workspace = await mcp__zenhub__getWorkspacePipelinesAndRepositories();

// Pipeline list
workspace.pipelines.forEach(p = >   {
  console.log(`${p.name}: ${p.id}`);
});

// ⚠️ 값은 라이브 파이프라인 이름과 정확히 일치해야 한다.
//    (과거  ' Backlog ' / ' Review '   는 실재 컬럼이 아니라 find() 가 undefined → silent no-op 였다.)
const PIPELINE_NAMES = {
   ' new ' :  ' New Issues ' ,
   ' icebox ' :  ' Icebox ' ,
   ' backlog ' :  ' Product Backlog ' ,
   ' sprint ' :  ' Sprint Backlog ' ,
   ' progress ' :  ' In Progress ' ,
   ' review ' :  ' Review/QA ' ,
  //  ' done ' / ' closed '   없음 — Done 컬럼 미사용, Closed 는 GitHub state(컬럼 아님)
};

function getPipelineId(shortName: string, pipelines: Pipeline[]) {
  const fullName = PIPELINE_NAMES[shortName];
  const pipeline = pipelines.find(p = >   p.name === fullName);
  // fail-closed: 못 찾으면 throw (undefined 를 그대로 move 에 넘겨 무음 누락하는 것을 금지)
  if (!pipeline) {
    throw new Error(
      `Pipeline  ' ${fullName ?? shortName} '   not found. Live: ${pipelines.map(p = >   p.name).join( " ,  " )}`
    );
  }
  return pipeline.id;
}

1. Close child issue
   ↓
2. Query parent issue
   ↓
3. Check status of all child issues
   ↓
4. If all are CLOSED and parent is not already CLOSED:
   - Parent type has its own branch (Initiative/Project/Epic/Story — see branch-hierarchy skill)?
       → Do NOT close. Warn:  " run /cc-dev:batch {parent} to finish the PR cascade. " 
    - Parent type has no branch (legacy fallback — non-standard container type)?
       → Close parent issue directly (without moving to Done pipeline), as before.

// 부모가 자기 브랜치를 갖는 레벨인지 판정 — resolveBaseBranch()(commands/run.md)와 동일 매핑.
// Sub-task는 절대 남의 부모가 될 수 없으므로(최하위 레벨) 여기 없다.
const BRANCH_BEARING_PARENT_TYPES = [ " Initiative " ,  " Project " ,  " Epic " ,  " Feature " ,  " Bug " ,  " Task " ];

async function checkAndCloseParent(childIssueNumber: number) {
  // ⚠️ ZenHub MCP 에는 getIssue / getChildrenOfParent 가 없다 — searchLatestIssues 로만 조회한다.
  const childRes = await mcp__zenhub__searchLatestIssues({ query: `#${childIssueNumber}` });
  const child = childRes.find(i = >   i.number === childIssueNumber);
  const parent = child?.parentIssue;                 // { id, number, issueType }
  if (!parent) return;

  // ⚠️ GD-04: parent: < graphqlId >   검색(ZenHub searchLatestIssues)은 **금지** —
  //     " 최신 20개 이슈 "   안에서만 필터링해, 오래 안 건드린 sibling 이 창 밖으로
  //    밀려나면 조용히 빠진다.  " 빈 배열이면 close 안 함 "   가드는 완전 누락은
  //    막아도 *부분* 누락은 못 막는다 — 보이는 sibling 이 전부 CLOSED 면
  //    `.every()` 가 true 를 반환해 안 보이는 OPEN sibling 을 놓친 채 조기 close 한다.
  //    그래서 completeness 는 GitHub 네이티브 sub-issues 를 source of truth 로 쓴다
  //    (`ghNativeSubIssues()`, `commands/run.md` Step 0.6).
  // ⛔ 여기서는 그 조회를 tri-state 로 감싼 `openChildrenStatus()` 를 쓴다 —
  //    Child Enumeration Contract(`rules/zenhub-conventions.md`) 가 단일 정의이며,
  //    조회 실패(`unknown`)를  " 자식 없음 "   으로 읽지 않는 것까지 계약에 포함된다.
  const kids = await openChildrenStatus(parent.number);  //  " open "   |  " none "   |  " unknown " 
   if (kids.status !==  " none " ) return;                    // 열림/판정불가 → close 안 함

  // ⚠️ 눈먼 조회(blind lookup) 감지 — 이 함수의 진입 조건상 childIssueNumber 는 parent 의 자식이다.
  //    따라서 열거 결과에 그 자신이 없으면  " 자식 0건 "   이 아니라 **조회가 눈먼 것**이다.
  //    (일반 게이트에서는 `[]` = 검증된 leaf 가 맞지만, 여기서는 논리적으로 불가능한 값이다)
  if (!kids.all.some(s = >   s.number === childIssueNumber)) {
    console.warn(
      `⚠️ #${parent.number} 자식 열거에 방금 닫은 #${childIssueNumber} 가 없음 — 조회 신뢰 불가, 부모를 닫지 않습니다`
    );
    return;
  }

  // 이미 닫혀 있으면(예: /cc-dev:batch가 이미 이 부모를 처리) no-op.
  const parentState = (await Bash(`gh issue view ${parent.number} --json state -q .state`)).trim();
  if (parentState ===  " CLOSED " ) return;

  if (BRANCH_BEARING_PARENT_TYPES.includes(parent.issueType)) {
    // 부모가 자기 브랜치를 가진 레벨 → 여기서 닫지 않는다. 실제 병합+close는
    // /cc-dev:batch {parent.number}의 컨테이너-종료 단계 책임.
    console.warn(
      `⚠️ #${parent.number}(${parent.issueType})의 모든 자식이 닫혔습니다 — ` +
      `부모 자신의 브랜치는 아직 병합되지 않았을 수 있습니다. ` +
      `/cc-dev:batch ${parent.number} 를 실행해 PR 생성·머지·close를 마무리하세요.`
    );
    return; // 조부모까지 자동 cascade 하지 않는다 — 재실행 단위를 명시적으로 남긴다.
  }

  // 레거시 폴백: 부모가 브랜치 없는 커스텀 컨테이너 타입일 때만 예전처럼 즉시 닫는다.
  await Bash(`gh issue close ${parent.number} --reason completed`);
  await mcp__zenhub__updateIssue({ issueId: parent.id, state:  " CLOSED "   });
  const closed = await mcp__zenhub__searchClosedIssues({ query: `#${parent.number}` });
  if (!closed.find(i = >   i.number === parent.number)) {
    await mcp__zenhub__updateIssue({ issueId: parent.id, state:  " CLOSED "   });  // 동기화 지연 시 재시도
  }

  // 조부모도 재귀적으로 확인 (레거시 폴백 경로 한정 — 브랜치 신호 경로는 위에서 이미 return)
  await checkAndCloseParent(parent.number);
}

const PRE_PROGRESS_PIPELINES = [ " New Issues " ,  " Icebox " ,  " Product Backlog " ,  " Sprint Backlog " ];

async function cascadeStartToParents(issueNumber: number) {
  const pipelines = (await mcp__zenhub__getWorkspacePipelinesAndRepositories()).pipelines;
  const inProgressId = getPipelineId( " progress " , pipelines); // fail-closed — 위 PIPELINE_NAMES 참조

  let current = issueNumber;
  for (let depth = 0; depth  <   10; depth++) { // 표준 계층 최대 5레벨 — 순환 방지용 여유 상한
    const res = await mcp__zenhub__searchLatestIssues({ query: `#${current}` });
    const issue = res.find(i = >   i.number === current);
    const parent = issue?.parentIssue;                 // { id, number, issueType }
    if (!parent) return;                                // 최상위 도달

    const parentRes = await mcp__zenhub__searchLatestIssues({ query: `#${parent.number}` });
    const parentInfo = parentRes.find(i = >   i.number === parent.number);
    if (!parentInfo) return;                            // 조회 실패 — 조용히 중단(하위 착수 자체는 막지 않음)

    // 이미 닫힌 부모는 절대 건드리지 않는다 — 닫힌 이슈를 열린 컬럼으로 옮기면 GitHub에서 재오픈된다
    // (zenhub-conventions.md →  " Issue Closure Policy "   의  " Never moveIssueToPipeline a closed issue "   그대로 적용)
    if ((parentInfo.state ||  " " ).toUpperCase() ===  " CLOSED " ) return;

    const parentPipeline = parentInfo.pipelineIssue?.pipeline?.name;
    // 이미 In Progress 이상(Review/QA 등)이면 역행시키지 않고 여기서 멈춘다 —
    // 그 시점에 이미 한 번 cascade됐을 것이므로 더 올라갈 필요도 없다.
    if (!PRE_PROGRESS_PIPELINES.includes(parentPipeline)) return;

    await mcp__zenhub__moveIssueToPipeline({ issueId: parentInfo.id, pipelineId: inProgressId });

    current = parent.number; // 조부모까지 계속 cascade
  }
}

# Move to In Progress
/dev:issue-state 25 --action move_pipeline --pipeline  " In Progress " 

 # Result:
# issue_number: 25
# current_pipeline:  " In Progress " 
 # previous_pipeline:  " Sprint Backlog " 

 # 이어서(같은 호출의 일부로) cascadeStartToParents(25) 실행:
#   #25 의 부모(예: Epic #10)가 아직  " Product Backlog " 면 →  " In Progress " 로 함께 이동
#   Epic #10 의 부모(Project #3)가 아직 착수 전 칸이면 → 그것도 이동, 최상위까지 반복

# Move to Review
/dev:issue-state 25 --action move_pipeline --pipeline  " Review/QA "

# Issue auto-closes via GitHub  " Closes # "   keyword → ZenHub syncs to Closed.
# Never move to Done (Done ≠ closed). Then VERIFY + fallback:
/dev:issue-state 25 --action verify_closed
#   1. gh issue view 25 → if not CLOSED → gh issue close 25 --reason completed
#   2. searchClosedIssues  " #25 "   → if missing → updateIssue state:CLOSED
# Parent issue is auto-checked when all children are closed —
# if the parent has its own branch (Initiative/Project/Epic/Story), this only
# WARNS ( " run /cc-dev:batch {parent} " ), it does not close the parent itself.

1. Log the error
2. Return current state
3. Report failure (success: false)