sequential-workflow

1. Query Story children under the Epic (each Story's own Sub-tasks are
   discovered and processed within that Story's own cycle — see
   branch-hierarchy: Sub-task's parent is Story, not Epic)
2. Filter issues in the New Issues pipeline
3. Sort by priority and issue number
4. Select the first issue

0. ⛔ Claim guard — claimStatus(issue) 가 "other-live" 면 이 Story 는 다른 세션이 잡고 있다.
   착수하지 않고 SKIPPED-OCCUPIED 로 기록한 뒤 다음 Story 로 넘어간다(보드·대장을 건드리지 않는다).
   판정 SoT: ../rules/zenhub-conventions.md → Work Claim Contract
1. Move the issue to the "In Progress" pipeline + acquireClaim(issue)
   → 이동만 하고 대장을 쓰지 않으면 다음 세션이 이 In Progress 를 부모 cascade 와 구분하지 못한다
   → cascade the same move up through any parent still in a pre-progress pipeline
     (New Issues/Icebox/Product Backlog/Sprint Backlog) — see
     agents/dev/issue-state-agent.md → cascadeStartToParents. Matters here specifically
     because this module may be invoked directly for a single Story outside a full batch,
     so the parent Epic may not have been touched yet.
2. Create branch: feature/{issue}-{slug}
3. Analyze issue requirements (title, body, acceptance criteria)

1. Analyze existing codebase
2. Implement code matching the requirements
3. Write tests (as needed)
4. Verify build and analysis pass

1. Commit changes (include Closes #{issue})
2. Push branch
3. Create PR as a draft (gh pr create --draft — 초안에서는 가벼운 CI 층만 돈다)
4. Move issue to "Review/QA" pipeline (reflectBoardState(issue, "review") — 점유는 유지)
5. 로컬 점검 통과 확인 → gh pr ready → ready 뒤 새 CI run 을 기다려 판정(초안의 초록 ≠ 통과,
   상세는 `../commands/run.md` Step 10.5 · `../skills/ci-receipts/SKILL.md`)

1. Check review feedback
2. ⭐ 변경 요청(CHANGES_REQUESTED) 또는 CI 실패 시: 이슈를 Review/QA → "In Progress" 로 되돌린다
   (재작업 중임을 보드에 반영). fail-closed find() 로 pipelineId 해석.
3. Add fix commits → re-push → 다시 "Review/QA" 로 이동
   (CI 실패는 로컬에서 재현 · 수정 · 검증한 뒤 push — CI 시험 루프 금지. 재현되지 않는 플레이크 · 러너
    문제는 `gh run rerun <run-id> --failed` 로 실패 잡만 다시. 리뷰 반영은 모아서 한 번 push)
4. Wait for approval

1. Squash merge PR
1.5. ⛔ 열린 자식 확인 — 이 이슈에 열린 자식이 있으면 **닫지 않는다**(이미 `Closes #N` 으로 닫혔다면
   `gh issue reopen` 으로 복구). 판정은 `openChildrenStatus()` tri-state — `rules/zenhub-conventions.md`
   → "Parent Closure Invariant". Story/Sub-task leaf 에서는 사실상 no-op 이다.
2. ⭐ 명시적 Close + 검증 (필수 — auto-close 의존 금지):
   PR base 가 `development`(저장소 기본 브랜치가 아닐 수 있음)면 `Closes #N` 이 발화하지 않는다.
   - STATE=$(gh issue view {N} --json state -q .state); [ "$STATE" != CLOSED ] && gh issue close {N} --reason completed
   - mcp__zenhub__searchClosedIssues({query:"#{N}"}) 에 없으면 → updateIssue({issueId, state:"CLOSED"})
3. Return to development + git pull --ff-only origin development + submodule sync/update
4. Go back to Phase 1 — **단, 종료 조건에 걸리지 않을 때만**(아래 루프 계약):
   - Phase 1 재조회가 이번 run 의 `attempted` 집합에 **없는** 이슈를 0개 내놓으면 정지한다
     (`attempted` = 이번 run 에서 착수한 이슈 번호 집합. 성공·BLOCKED 모두 넣는다 —
      BLOCKED 를 빼면 같은 이슈를 영원히 다시 고른다)
   - 조회 실패는 빈 집합이 아니다 — `unknown` 은 "다 끝났다" 가 아니라 **정지 + 기록**이다
   - 연속 K = 3 pass 동안 어떤 이슈도 closed 또는 BLOCKED 로 전이되지 않으면 정지한다
     (no-progress stop — 이슈가 계속 나오는데 아무것도 끝나지 않는 상태)

inv:      매 pass 진입·종료 시 attempted 는 단조 증가하고 이번 run 에서 착수한 모든 이슈를 담는다
          (attempted 에 넣지 않고 같은 이슈를 다시 고르는 경로 금지)
prog:     remaining = |Phase 1 후보 − attempted|, pass 하나마다 강한 감소
          no-prog: remaining 이 줄지 않은 pass 는 noProgressStreak++ (예산에서 차감)
term:     remaining == 0 (= attempted 에 없는 이슈가 없다) || noProgressStreak == 3
budget:   pass 당 이슈 1개 · noProgressStreak K = 3 연속 pass · 이슈당 사다리 예산 4 attempts
          (run 당 이슈 수 상한은 데이터 주도 — 예산은 K 와 이슈별 사다리 카운터가 진다)
exhaust:  정지 + 남은 후보·BLOCKED 목록을 컨테이너 이슈 코멘트에 내구 기록. 조용한 종료 금지
resume:   ZenHub 파이프라인 재조회 + 각 이슈의 `<!-- cc-dev:stall-ladder -->` 코멘트.
          attempted 는 run 범위(대화 구조라 `/clear` 를 못 넘는다) — 그래서 재개를 가로지르는
          예산은 K 가 아니라 이슈별 **내구** 사다리 카운터가 진다
log:      선택마다 한 줄 — `▶ #1415 selected (attempted 3, remaining 5→4, streak 0)`
          + 정지 시 이유 한 줄(`remaining==0` | `noProgressStreak==3` | `query=unknown`)

const workspace = await mcp__zenhub__getWorkspacePipelinesAndRepositories();
const pipelines = workspace.pipelines;
const repos = workspace.githubRepositories;   // ⚠️ 필드명은 githubRepositories (repositories 아님)

// fail-closed 해석 — 못 찾으면 throw (rename/오타 시 undefined.id 무음 누락 방지)
const pid = (n) => { const p = pipelines.find(p => p.name === n); if (!p) throw new Error(`'${n}' 없음. 라이브: ${pipelines.map(p => p.name).join(", ")}`); return p; };
const newIssues = pid("New Issues");
const inProgress = pid("In Progress");
const reviewQA = pid("Review/QA");

mcp__zenhub__searchLatestIssues({ query: "SALES-001" })

// Query issues by pipeline
mcp__zenhub__getIssuesInPipeline({
  pipelineId: newIssues.id,
  repositoryIds: [repos[0].id]
})

// In Progress
mcp__zenhub__moveIssueToPipeline({
  issueId: "{graphql_id}",
  pipelineId: inProgress.id
})

// Review/QA
mcp__zenhub__moveIssueToPipeline({
  issueId: "{graphql_id}",
  pipelineId: reviewQA.id
})

# Create issue work branch
git checkout development
git pull origin development
git checkout -b feature/{issue_number}-{short-slug}

# Example
git checkout -b feature/1415-sales-kpi-summary

# Korean commit message + Gitmoji
feat(console): ✨ 매출 KPI 요약 카드 구현 (#1415)

- 총 결제액 표시
- 총 판매량 표시
- 전월 대비 증감률 표시

Closes #1415
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

gh pr create --draft \
  --base development \
  --title "feat(console): ✨ 매출 KPI 요약 카드 구현 (#1415)" \
  --body "$(cat <<'EOF'
## Summary
- Implement sales KPI summary card component
- Display total payment amount and sales volume
- Calculate month-over-month growth rate

## Related Issue
Closes #1415

## Test Plan
- [ ] Verify KPI card rendering
- [ ] Verify data binding
- [ ] Validate growth rate calculation

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

Rung 1 — Same-strategy retry (existing):   budget = 2 attempts
  Re-run the same fix **at most 2 times** (e.g. lint/format/build
  auto-fix as in Error Recovery below). An unquantified "small, bounded"
  count is not a budget — in practice it never terminates.
  Each retry MUST change at least one input: command/flags, the changed
  file set, or the environment. A re-run with an identical input set is
  not an attempt but a repeat — it consumes no budget and goes straight
  to Rung 2 (`no-prog:` 위반).

Rung 2 — Lateral reframe (on repeated IDENTICAL failure):
                                           budget = 2 reframes, ≤ 1 persona switch
  When the SAME failure repeats (judged SEMANTICALLY, not by string
  diff — see note), escalate to /cc-dev:unstuck solo with an affinity
  persona from the symptom table below. A reframe ≠ a retry: the next
  move must differ in KIND from what already failed.
  **At most 2 reframed attempts**, and **at most ONE persona switch**
  within them (persona #1 comes from the symptom table; the one switch
  is spent only when reframe #1's named change did not move the failure).
  Each reframed attempt must NAME which of {tool, layer, data,
  assumption} it changed — that name IS this rung's progress measure.
  An attempt that can name none of the four is not a reframe: it
  consumes no budget and escalates to Rung 3.

Rung 3 — BLOCKED + CONTINUE (보드 반영 포함):
  횡적 reframe 도 소진되고 Story 가 여전히 안 풀리면 blockIssue(issue, 'unstuck_exhausted')
  후 배치를 CONTINUE 한다(Epic 전체 중단 금지). 그 한 번의 호출이 아래 셋을 묶어 수행한다:
    - 차단 의존이 있으면 createBlockage({blockedIssueId, blockingIssueId}) 로 기록
      (차단자가 이슈일 때만 — CI 실패·예산 소진에는 가짜 이슈를 만들지 않는다)
    - 활성 작업과 구분되도록 holding 컬럼(Sprint Backlog)으로 이동 — In Progress 에 방치 금지
    - **점유 해제** — 빠뜨리면 이 Story 는 TTL(4h)까지 다른 세션에게 "누가 하고 있다"로 읽힌다
    - 정의·blocked→unblocked 계약은 rules/zenhub-conventions.md → Pipeline State Contract 참조
    - 소진된 사다리 상태를 아래 카운터 코멘트에 state:blocked(unstuck_exhausted) 로 확정한다
  (BLOCKED Story 는 Phase 0 멱등 resume 으로 다시 집히지만, **사다리는 rung 1 로 리셋되지
   않는다** — 남은 예산이 있을 때만 재시도한다. 아래 "Ladder Counter Persistence" 참조.)

- 위치: 막힌 그 이슈 자신의 마커 코멘트 `<!-- cc-dev:stall-ladder -->`
  (upsert 프로토콜은 `../skills/branch-hierarchy/SKILL.md` R3 의 마커 코멘트 읽기·쓰기 절차를 재사용 — 복제 금지)
- 항목: | rung | attempts_used | persona | persona_switched(0|1) | changed({tool|layer|data|assumption})
        | last_cause(LLM-SEMANTIC 요약) | state: climbing / blocked(unstuck_exhausted) |
- 갱신 시점: **rung 전이마다 즉시**(다음 attempt 를 시작하기 전에) upsert 한다. 몰아서 쓰면
  크래시 한 번에 카운터가 사라지고 예산이 리셋된다.
- 재개: 이 이슈를 다시 집으면 코멘트를 **먼저 읽고** 남은 예산부터 이어 쓴다. 코멘트가 없으면
  rung 1 / attempts_used 0 이 초기값이고, **조회 실패는 "없음"이 아니라 unknown** 이므로 사다리를
  새로 시작하지 않고 blocked 로 둔다(`../rules/orchestration-graph.md` §3.2 empty-set pass).
- batch 하위에서 돌 때: `../commands/batch.md` → "Stall Ladder" 의 시도 대장(attempt ledger)은
  **컨테이너 쪽 바깥 예산**(child 1개당 누적 처리 pass 수)이고, 이 코멘트는 **그 pass 안쪽의
  rung/attempt** 다. 단위가 다르므로 서로 덮어쓰지 않고 곱해진다(outer × inner). 둘 중 하나라도
  소진되면 재시도는 없다.

inv:      매 attempt 진입·종료 시 (rung, attempts_used) 가 마커 코멘트의 값과 일치한다
          Rung 1 attempt 는 직전 attempt 와 입력 집합이 다르다
prog:     attemptsLeft = (2 - rung1Used) + (2 - rung2Used), 매 attempt 강한 감소
          no-prog: 입력이 같은 재실행(Rung 1) 또는 {tool,layer,data,assumption} 중 무엇도
          이름 대지 못한 리프레임(Rung 2) 은 예산을 쓰지 않고 곧바로 다음 rung 으로 올린다
term:     막힌 게이트가 통과 || attemptsLeft == 0 → Rung 3
budget:   Rung 1 = 2 attempts · Rung 2 = 2 reframes(persona 교체 ≤ 1) · Rung 3 = 종단 1회
          = 이슈당 최대 4 attempts, **batch 재실행을 가로질러 합산**한다(대화 카운터 아님)
exhaust:  Rung 3 = blockIssue(issue, 'unstuck_exhausted') (보드 + 점유 해제) + 형제 CONTINUE.
          디스패치된 워커 안에서 `AskUserQuestion` 을 exhaust 로 쓰지 않는다(물어볼 사람이 없다)
resume:   막힌 이슈의 `<!-- cc-dev:stall-ladder -->` 코멘트를 읽어 위치를 판정한다.
          코멘트 upsert 는 멱등이고, 사다리는 resume 마다 rung 1 로 되돌아가지 않는다
log:      rung 전이마다 한 줄(rung · attempt index · 고른 persona) —
          `🪜 rung 2 attempt 1/2 persona=hacker changed=assumption cause={의미 요약}`
          Rung 3 도달 시 잔여 상태와 **탈락시킨 이슈**를 같은 코멘트에 내구 기록

# Analyze error
melos run analyze 2>&1 | head -50

# Common fixes
melos run format
melos run build

# Same failure (semantically) after Rung 1 retries → lateral reframe
/cc-dev:unstuck solo <affinity-persona>   # see Affinity Symptom Table

# Reframe didn't unblock → mark BLOCKED and move on
mark Story BLOCKED('unstuck_exhausted'); CONTINUE to next Story  # Epic NOT halted

git fetch origin development
git rebase origin/development
# After resolving conflicts
git rebase --continue