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 " 

 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) {
  // 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 "   });
  }
}

┌─────────────────────────────────────────────────────────┐
│  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:
   - Close parent issue (without moving to Done pipeline)

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 }
  if (!parent) return;

  // 부모의 모든 자식 조회 (검색 DSL: parent: < graphqlId > )
  const siblings = await mcp__zenhub__searchLatestIssues({ query: `parent:${parent.id}` });

  // ⚠️ 빈/조회실패 결과로 인한 조기 close 방지:
  //    자식이 1개 이상이고 전부 CLOSED 일 때만 진행 (빈 배열의 .every 는 true 가 되어 위험).
  if (!siblings || siblings.length === 0) return;    // 판정 불가 → close 안 함
  const allDone = siblings.every(s = >   (s.state ||  " " ).toUpperCase() ===  " CLOSED " );
  if (!allDone) return;

  // 부모를 닫는다 (merge=Close, Done 미사용). GitHub 가 source of truth → 명시적 close 후 양쪽 검증.
  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 "   });  // 동기화 지연 시 재시도
  }

  // 조부모도 재귀적으로 확인 (Story 완료 → Epic 완료 → Project 완료 연쇄)
  await checkAndCloseParent(parent.number);
}

# 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 "

# 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

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