Issue Loop

---
name: issue-loop
description: ai-task 이슈를 우선순위대로 구현→리뷰→머지까지 서브에이전트로 자동 반복하는 루프. 중단돼도 GitHub 상태로 재개. Trigger — /issue-loop
---

# /issue-loop

`/spec → /implement-issue → /review-pr`을 매번 세션을 열어 돌리는 대신, **루프 드라이버가 GitHub 상태를 읽고 각 걸음을 새 서브에이전트에 위임**해 자동 반복한다. 원본의 원칙 유지: ① 이슈 1개 = 세션 1개, ② 리뷰는 구현과 다른 세션 (둘 다 걸음별 독립 서브에이전트로 자동 충족), ③ 설계 분해안·UI 시안 승인과 `risk:high` 머지는 **언제나 사람** — 일반 머지는 기본 모드에선 사람이 결정하고 루프가 실행, 무인 모드에선 강화 리뷰가 대신한다.

## Usage

```
/issue-loop                      # 이어하기: GitHub 상태를 읽고 루프 시작/재개
/issue-loop "<기능 설명>"         # 설계부터: spec(분해안·UI 시안 승인은 사람) → 이슈 등록 → 루프
/issue-loop <상위 이슈 번호>       # 특정 기능([Feature] 이슈)으로 범위 제한
/issue-loop --label <태그>        # 내가 붙인 태그가 있는 이슈만 (ai-task와 AND) — 범위 내 전부 완료가 목표
/issue-loop --once               # 한 걸음만 진행하고 종료
/issue-loop --status             # 상태판 + 다음 계획만 출력 (dispatch 없음)
/issue-loop --max N              # 걸음 수 안전상한 (기본: max(20, 범위 내 이슈 수 × 4))
/issue-loop --unattended         # 완전 무인: agent:auto 이슈만 · 질문 대신 건너뜀 · 강화 리뷰 통과 PR 자동 머지
/issue-loop --economy            # 한도 절약: 구현을 전부 sonnet으로 (리뷰·설계는 opus 유지)
/issue-loop --usage-guard N      # 사용량 추정치가 N% 넘으면 걸음 경계에서 우아하게 중단 (기본 90, ccusage 필요)
```

## 0. 사전 확인 (매 실행 첫 단계)

1. `git rev-parse --show-toplevel`이 현재 디렉토리와 같은지 — 아니면 대상 저장소 루트로 이동을 안내하고 중단
2. `gh auth status` 통과 여부
3. `.claude/commands/implement-issue.md`·`.claude/commands/review-pr.md` 존재 여부 — 없으면 issue-template `install.sh` 실행을 안내하고 중단 (서브에이전트가 이 파일들을 계약서로 읽는다)
4. `--label <태그>`가 주어졌으면: `gh label list`에 그 태그가 존재하는지, 그 태그가 붙은 열린 ai-task 이슈가 1개 이상인지 확인 — 없으면 오타 가능성을 알리고 중단 (조용히 빈 루프를 돌지 않는다)
5. **판정 라벨 존재 보장**: `review:approved`·`review:rejected`·`needs-respec`는 루프의 **상태 원본**이다 — `gh label list`에 없으면 즉시 생성한다 (`gh label create <이름> --color <색> 2>/dev/null || true`). 없는 채로 돌면 판정 라벨이 안 붙어 같은 PR을 무한 재리뷰한다
6. **브랜치 보호 확인 (1인 개발 감지)**: `gh api "repos/{owner}/{repo}/branches/<기본브랜치>/protection/required_pull_request_reviews" --jq .required_approving_review_count 2>/dev/null` — 값이 1 이상이면, 자기 PR을 자기가 승인할 수 없으므로 1인 리포에선 라벨 승인만으로 `gh pr merge`가 거부된다고 **루프 시작 전에 경고**한다 (보호 규칙 완화 / 머지는 사람이 GitHub에서 직접 — 중 택일 안내). 조회 실패(보호 없음 404·권한 부족)는 조용히 건너뛴다
7. 저널 디렉토리 준비: `mkdir -p .claude/issue-loop` 하고, `.gitignore`에 `.claude/issue-loop/`가 없으면 추가 (저널은 로컬 상태 — 커밋 금지). 반대로 **`.design/`과 `docs/design/`은 커밋 대상이다** — 이슈가 참조하는 계약물이므로 gitignore에 넣지 않는다
8. 저널 마지막에 `⏸ INTERRUPTED` 블록이 있으면 그 내용을 사용자에게 요약해 보여주고 이어서 진행 (상태 원본은 GitHub이므로 저널은 참고 컨텍스트일 뿐 — 재개는 항상 GitHub 상태 재수집으로 시작한다)

## 드라이버 원칙

- **드라이버(이 세션)는 얇게 유지한다.** 상태 수집·판단·dispatch·저널 기록만 한다. **구현·리뷰를 이 세션에서 직접 하지 않는다** — 컨텍스트가 비대해지면 루프가 오래 못 가고, 셀프 리뷰 금지 원칙도 깨진다.
- **GitHub이 상태 원본이다.** 이슈·PR·라벨에서 매 걸음 다시 계산한다. 저널은 반려 횟수·중단 지점 같은 보조 기록.
- 각 걸음은 Agent 툴로 **새 서브에이전트**를 만들어 수행한다 (`subagent_type: general-purpose`, `model:`은 아래 라우팅 표).

### 드라이버 컨텍스트 절식 — 긴 루프의 생존 조건

드라이버 컨텍스트가 크면 걸음마다 비용이 늘고, 컴팩션(자동 요약)이 일어나면 판단 근거가 뭉개진다. 규칙:

- **본문 전문을 드라이버에 들이지 않는다.** 상태 수집은 `--jq`로 필요한 필드만 추출한다 — 이슈: 번호·제목·라벨·본문 중 `선행: #N` 줄과 코드 앵커의 **파일 경로만**. PR: 번호·라벨·`Closes #N`·변경 파일 목록만. 계약 전문은 그걸 실제로 쓰는 **에이전트가 직접 읽는다** (이슈 번호만 넘기면 된다)
- **에이전트 반환도 절식.** 공통 규칙에 포함: 작업 로그·diff·파일 내용을 반환하지 마라 — `RESULT:` 한 줄 + 최대 5줄 요약만. 상세는 GitHub(PR 본문·코멘트·리뷰)에 적재하는 것이 원칙 (그래야 다음 에이전트도 읽는다)
- **저널이 외부 메모리다.** 기억해야 할 것(제외 목록·보류 PR·머지 방식·범위·걸음 수)은 컨텍스트가 아니라 저널에 적는다. **10걸음마다 체크포인트 블록**을 저널에 남긴다 — 컴팩션이나 중단 후에도 저널 + GitHub만으로 완전 복원되도록
- **컴팩션은 감지가 아니라 가정이다.** 긴 루프에서 자동 컴팩션은 반드시 일어난다고 가정하고, **매 걸음 시작 시 저널의 마지막 체크포인트와 그 이후 항목을 다시 읽어** 판단 상태(제외 목록·보류·모드·머지 방식)를 재정렬한다 — 몇 줄이라 비용은 무시 가능하고, 이렇게 하면 컴팩션이 언제 어떻게 일어나든 무해하다. 컨텍스트 기억과 저널이 다르면 **저널이 이긴다**
- 컴팩션이 명시적으로 보이면 (대화 요약 표시): 감독 모드에선 진행 중 걸음을 끝내고 체크포인트 후 "새 세션에서 `/issue-loop` 재실행"을 제안한다 — 상태가 전부 밖에 있어 무손실이고, 신선한 컨텍스트가 뭉개진 요약보다 낫다. 무인 모드는 저널 재독 규칙 덕에 그대로 계속한다

## Phase 0 — 설계 (인자가 기능 설명일 때만)

1. **설계 초안 에이전트** dispatch (`model: opus`):
   > `.claude/commands/spec.md`를 읽고 절차 1~2(코드 검증 → UI 판정 → 설계문서 작성 → 이슈 분해안, UI full 티어면 시안 v1 생성까지)만 수행하라. **이슈 등록(절차 4)과 사용자 확인 라운드는 하지 마라.** 시안은 spec.md의 시안 규칙만으로 완결되게 산출하라 (서브에이전트 세션에는 외부 시안 스킬이 주입되지 않을 수 있다). 반환: 설계문서 경로·분해안(제목/의존/검증 명령/크기/실행방식 라벨/UI 티어)·UI 판정 결과(있음/없음/보류 + 근거 요약)·시안 파일 경로·마일스톤 후보(`gh api`로 마감일 안 지난 것 조회). 시안 HTML 본문은 반환하지 마라.
2. 반환된 분해안을 사용자에게 보여주고 **승인을 받는다** (AskUserQuestion — 승인 / 시안 수정 지시 / 분해안 수정 지시 / 중단, 마일스톤 선택 포함). full 티어면 시안 파일 경로를 함께 제시한다 (사용자는 브라우저로 연다). '시안 수정 지시'면 피드백을 담아 설계 에이전트를 재dispatch해 vN+1을 만들게 한다 — **수정 라운드 상한 3회**, 초과하면 대화형 `/spec` 세션으로 전환을 안내한다. UI 판정 '보류'는 이 게이트에서 확인받는다. 이 게이트는 자동화하지 않는다.
3. 승인되면 **등록 에이전트** dispatch (`model: sonnet`):
   > `.claude/commands/spec.md` 절차 3의 승인 반영(meta.json `status: approved`·`approvedVersion`·`updatedAt` 갱신 + 시안 배너 '승인됨')과 절차 4-0(승인 산출물 커밋·푸시)을 먼저 수행한 뒤, 절차 4를 승인된 분해안 그대로 수행해 이슈를 등록하고, 등록된 이슈 번호 목록을 반환하라. 커밋이 실패하면 이슈를 등록하지 말고 BLOCKED로 사유를 반환하라.
4. 등록 결과를 저널에 기록하고 루프 진입.

## 루프 — 매 걸음

### 1. 상태 수집

```bash
gh issue list --label ai-task --state open --json number,title,body,labels,milestone   # --label <태그> 지정 시 추가 (AND 조건)
gh pr list --state open --json number,title,body,labels,headRefName
gh pr list --state merged --limit 10 --json number,title,body
```

- 이슈 본문 `선행: #N` → 의존 그래프, PR 본문 `Closes #N` → 이슈↔PR 연결
- `[Feature]` 접두어 = 추적용 상위 이슈 (구현 대상 아님)
- **범위 한정**: 상위 이슈 번호가 주어지면 그 sub-issue 트리로, `--label <태그>`가 주어지면 그 태그가 붙은 이슈로 한정 (둘 다 주면 AND). **범위 밖 이슈는 어떤 걸음의 대상도 아니다** — 단, 앵커 충돌 검사는 범위 밖 열린 PR도 포함해 수행한다 (파일이 겹치면 남의 작업이라도 기다려야 하므로)
- PR의 범위 판정은 라벨이 아니라 `Closes #N`이 가리키는 **이슈의 범위 소속**으로 한다 (라벨 승계 누락에 안전)
- 선행 이슈가 범위 밖이면 그 완료 여부는 그대로 존중한다 — 범위는 "무엇을 착수하나"만 제한하고 의존 그래프는 전체를 본다

### 2. 다음 행동 결정 (위에서부터 첫 매치 — 하나만)

먼저 **제외 목록**을 만든다 — 아래에 해당하는 이슈와 그 PR은 **순위 1~4 어디에도 걸리지 않는다** (종료 보고의 에스컬레이션으로만 감):

- 반려 2회 누적 이슈 — 횟수는 저널이 아니라 **GitHub 원본**으로 센다. 근거는 **라벨 부착 이력**이다 (1인 개발에선 자기 PR에 `--request-changes`가 항상 거부되어 `CHANGES_REQUESTED` 리뷰가 0으로 남으므로, 리뷰 상태는 세지 않는다):
  `gh api repos/{owner}/{repo}/issues/<PR번호>/timeline --paginate --jq '[.[] | select(.event=="labeled" and .label.name=="review:rejected")] | length'`
  — 재작업 때 라벨을 떼어도 timeline 이벤트는 남으므로 반려 1회 = 이벤트 1개. 조회가 실패하면 폴백으로 PR 코멘트·리뷰 본문의 `<!-- review-verdict: rejected -->` 마커 수를 센다. 저널은 머신을 옮기면 사라지므로 카운트 근거로 쓰지 않는다
- `needs-respec` 라벨 이슈
- `FAILED`/`BLOCKED` 2회 이슈, `NEEDS_HUMAN`으로 건너뛴 이슈 (무인 모드)

| 순위 | 조건 | 행동 | 모델 |
|---|---|---|---|
| 1 | 열린 범위 내 PR에 `review:*` 라벨 없음 | **리뷰** dispatch (오래된 PR부터) | opus |
| 2 | 열린 범위 내 PR에 `review:rejected` | **재작업** dispatch | opus |
| 3 | `review:approved` PR 있음 (`risk:high`·보류 표시 제외) | **머지 게이트** — 아래 참조 | — |
| 4 | 착수 가능 이슈 있음 (아래 조건) | **구현** dispatch (번호 가장 앞선 것 = 의존 순서) | 아래 라우팅 |
| 5 | 하위 이슈 전부 닫힌 `[Feature]` 있음 | 닫기 후보로 **기록만** (자동으로 닫지 않음) | — |
| 6 | 해당 없음 | **종료 보고** | — |

순위 1~3의 "PR"은 `Closes #N`이 **범위 내 ai-task 이슈**를 가리키는 PR만이다 — 사람이 연 일반 PR, `Closes` 없는 PR, 범위 밖 이슈의 PR은 건드리지 않는다.

순위 5의 닫기 후보 보고에는, 해당 기능의 `.design/<슬러그>/meta.json`이 있으면 `status: shipped` 갱신 커밋 제안을 함께 싣는다 (전이도 사람 확인 후 실행 — 낡은 approved 시안이 다음 설계 세션의 오염원이 되는 것을 막는다).

**착수 가능 조건 (순위 4)** — 전부 만족해야 한다:

- 선행 이슈 전부 닫힘 · 연결된 열린 PR 없음 · `needs-respec` 아님
- **앵커 충돌 검사**: 이슈의 코드 앵커 파일이 **열린 PR들의 변경 파일**(`gh pr view <N> --json files`)과 하나도 겹치지 않음. 겹치면 그 PR이 머지될 때까지 ⛔ 보류 — `/spec`의 병렬 안전 규칙은 같은 기능 분해 안에서만 유효하므로, **여러 기능을 동시에 돌릴 때의 파일 서로소는 드라이버가 여기서 강제한다**
- `agent:assist` 이슈면: 사용자에게 한 번 묻는다 (진행 / 건너뜀). `--unattended`면 묻지 않고 건너뛰고 종료 보고에 명시

### 머지 게이트 (순위 3) — 머지 결정은 사람, 실행은 루프

승인 PR을 쌓아두면 후속 이슈가 블락되어 정체되고(이슈는 머지로만 닫힘), 다음 구현이 낡은 main 기준이 되어 충돌한다. 그래서 승인 PR은 **다음 걸음 전에** 비운다 — 결정은 사람, 실행은 루프 (AskUserQuestion, 여러 건이면 묶어서 한 번에):

> PR #14 (issue #11) 승인됨 — #12·#13이 블락 대기 중. 지금 머지하고 계속할까요?
> — 머지하고 계속 / 판정 요약 먼저 보기 / 이 PR은 보류 (내가 직접 처리)

질문에는 해당 PR 판정문의 `(수동)` 항목 유무를 한 줄로 함께 표기한다 — 있으면 항목 내용과 (시안 대조 항목이면) 승인 시안 경로를 실어, 사람이 "판정 요약 먼저 보기"를 누르지 않아도 머지 전에 확인할 것이 남았음을 알게 한다.

- **머지 승낙 시**: `gh pr merge <N> --squash --delete-branch` (머지 방식은 첫 질문 때 merge/squash/rebase 중 확인하고 저널에 기록해 반복 질문 방지 — squash 권장: 문제 발견 시 PR 단위 revert 한 번으로 되돌림) → `Closes #N`으로 이슈 자동 닫힘 → 블락 해제 → 루프 계속. 브랜치 보호(승인 리뷰 필수)로 머지가 거부되면 재시도하지 않는다 — 1인 리포에선 라벨 승인이 GitHub 필수 리뷰를 채우지 못하므로, 머지 대기열에 **"보호 규칙으로 자동 머지 불가 — 사람 처리 필요"**로 보고하고 다음 순위로 넘어간다
- **보류 선택 시**: 그 PR에 보류 표시를 저널에 남기고 (같은 PR로 다시 묻지 않음) 다음 순위로 — 단, 그 PR의 변경 파일과 앵커가 겹치는 이슈·후속 이슈는 계속 ⛔로 남는다는 걸 함께 알린다
- **`--unattended`(무인 모드): 묻지 않고 자동 머지한다.** 단 아래 전부 충족할 때만:
  - 리뷰가 **강화 리뷰**(아래 리뷰 템플릿의 무인 모드 추가 항목)로 수행되어 `APPROVED`
  - `risk:high` 아님 · `agent:auto` 이슈
  - CI가 있으면 `gh pr checks <N>` 전부 통과 (pending이면 완료까지 대기)
  - 하나라도 미충족 → 머지하지 않고 머지 대기열로 보고
- `risk:high` PR은 모드와 무관하게 게이트 대상 제외 — 머지 대기열에 **"사람 리뷰 필수"** 표시로만 보고하고, 사람이 GitHub에서 직접 리뷰·머지

### 구현 모델 라우팅 (업무 크기·난이도 기반)

| 조건 | 모델 |
|---|---|
| `size:S` 이고 `risk:high` 아님 | sonnet |
| `size:M` 또는 `risk:high` | opus |
| 재작업 (반려 후) | opus — 한 번 실패한 작업은 승격 |
| 리뷰 · 설계 | opus 고정 — 어떤 경우에도 강등하지 않는다 (자동 머지의 품질 근거) |

- `--economy`: 구현·재작업을 전부 sonnet으로 (리뷰·설계는 그대로 opus). 한도를 아끼고 싶은 날 사용 — 반려율이 오르면 반려 2회 안전장치가 잡는다
- **opus 한도 소진 폴백**: opus dispatch가 사용량 한도로 실패하면 — **구현**은 sonnet으로 1회 폴백 재시도하고 저널에 기록. **리뷰·설계**는 폴백하지 않고 "중단과 재개"를 수행한다 (품질 게이트를 낮춰서 계속 도는 것보다 멈추는 게 낫다)
- 잔여 한도를 실시간 조회할 방법은 없으므로 "usage에 따라 자동 선택"은 하지 않는다 — 사전 선택은 `--economy`, 사후 대응은 위 폴백이 담당한다

### 3. dispatch — 에이전트 프롬프트 템플릿

에이전트는 사용자와 대화할 수 없으므로, 세 템플릿 모두 다음 공통 규칙을 포함시킨다:

> 이슈/계약에 없는 판단이 필요해지면 임의로 정하지 말고 그 지점에서 멈추고 `NEEDS_HUMAN`으로 질문을 반환하라. 시작 전에 `git status`로 워킹트리를 확인하라 — **네가 만들지 않은 uncommitted 변경**이 있으면 건드리지 말고 `BLOCKED`로 상황을 반환하라 (이전 걸음의 잔재일 수 있다). 작업이 끝나면 커밋 안 된 변경을 남기지 마라. 반환은 절식하라: 작업 로그·diff·파일 내용을 반환하지 마라 — 상세 기록은 GitHub(PR 본문·코멘트·리뷰)에 적재하고, 반환은 **최대 5줄 요약 + 마지막 줄에 정확히 한 줄**:
> `RESULT: <STATUS> | issue=<N> | pr=<N|-> | note=<한 줄 요약>`

**구현** (STATUS: `PR_CREATED` / `NEEDS_RESPEC` / `BLOCKED` / `NEEDS_HUMAN` / `FAILED`):
> 너는 구현 담당 엔지니어다. `<repo root>`에서 `.claude/commands/implement-issue.md`를 읽고 그 절차를 `$ARGUMENTS=<이슈 번호>`로 그대로 수행하라. 추가 규칙: ① 브랜치는 반드시 **최신 기본 브랜치에서** 분기하라 — `git fetch origin` 후 `git checkout -b task/<이슈번호>-<슬러그> origin/<기본브랜치>` (낡은 로컬 main 기준 구현이 의미 충돌의 주범이다). ② `task/<이슈번호>-*` 브랜치가 이미 있으면 (이전 중단의 잔재) 새로 만들지 말고 checkout해서 상태를 점검하고 이어서 작업하라. ③ 검증 명령이 실패하면 고치고 재실행하되, 3회 연속 같은 실패면 `FAILED`로 원인을 반환하라.

**리뷰** (STATUS: `APPROVED` / `REJECTED` / `NEEDS_HUMAN`):
> 너는 리뷰 담당 시니어 아키텍트다. 이 PR의 구현에 관여한 적 없는 독립 세션이다. `<repo root>`에서 `.claude/commands/review-pr.md`를 읽고 그 절차를 PR #<N>, 이슈 #<M>으로 그대로 수행하라 — 판정 전문의 PR 기록과 `review:approved`/`review:rejected` 라벨 부착까지. 단, 절차 6(머지 여부 질문)은 하지 마라 — 머지는 드라이버가 처리한다.

`--unattended`면 리뷰 프롬프트에 **강화 리뷰 항목**을 추가한다 — 자동 머지의 근거가 되므로 "의심되면"이 아니라 전부 의무이며, 하나라도 미달이면 `REJECTED`:
> ① 이슈의 검증 명령어를 **네가 직접 재실행**해 통과를 확인하라 (PR 본문의 결과 보고를 믿지 마라). ② 저장소의 **전체 테스트 스위트**를 실행해 회귀가 없는지 확인하라 (테스트 명령은 CLAUDE.md·package.json·Makefile 등에서 찾는다). ③ 변경된 동작에 대한 **테스트가 추가·갱신됐는지** 확인하라 — 검증 명령이 수동 확인뿐인 변경은 반려 사유다. ④ 인터페이스(공개 함수 시그니처·API·스키마·설정)가 바뀌었으면 관련 **문서(README·docs/)가 갱신됐는지** 확인하라. ⑤ `(수동)` 표기 완료 기준이 있으면 자동 머지 불가 — `NEEDS_HUMAN`으로 반환하라 (승인 시안이 있어도 이 규칙은 유지된다 — 리뷰가 시안 대비 자동 검증을 수행하는 환경이 갖춰지기 전까지 UI full 티어 이슈는 무인 완주 대상이 아니다).

**재작업** (STATUS: `REWORK_PUSHED` / `NEEDS_RESPEC` / `NEEDS_HUMAN` / `FAILED`):
> 너는 구현 담당 엔지니어다. `.claude/commands/implement-issue.md`의 재작업 경로를 수행하라: PR #<N>의 반려 사유(리뷰·코멘트)를 읽고, 기존 브랜치에서 지적 사항을 고쳐 push하고, 각 지적에 어떻게 대응했는지 PR 코멘트로 남겨라.

### 4. 결과 처리

| STATUS | 드라이버 행동 |
|---|---|
| `PR_CREATED` | 저널 기록 → 다음 걸음 (순위 1이 리뷰를 잡는다) |
| `REWORK_PUSHED` | `gh pr edit <N> --remove-label review:rejected` → 다음 걸음에 재리뷰 |
| `APPROVED` | 머지 대기열에 추가 → 다음 걸음 |
| `REJECTED` | 저널에서 이 이슈의 누적 반려 횟수 확인 — **2회째면 루프에서 제외**하고 사람 에스컬레이션 목록에 추가 (반려 루프 방지). 아니면 다음 걸음 |
| `NEEDS_RESPEC` | 해당 이슈 제외 (라벨은 에이전트가 이미 부착) → 다음 걸음 |
| `NEEDS_HUMAN` | 기본 모드: 루프 일시정지 → 에이전트의 질문을 사용자에게 전달 (AskUserQuestion) → 답을 프롬프트에 넣어 같은 걸음 재dispatch. `--unattended`: 묻지 않고 해당 이슈를 건너뛰고 질문을 에스컬레이션 목록에 기록 |
| `BLOCKED` / `FAILED` | 1회 재시도 → 또 실패면 해당 이슈 제외하고 다음 걸음, 종료 보고에 사유 명시 |
| RESULT 줄 파싱 불가 / 에이전트 소멸 | 사용량 한도 가능성 — 아래 "중단과 재개" 수행 |

### 5. 저널 기록 (매 걸음 dispatch 직전·직후)

`.claude/issue-loop/journal.md`에 append:

```markdown
## step 3 — 2026-07-10 18:40
- action: implement #12 (size:S → sonnet)
- result: PR_CREATED | issue=12 | pr=15 | note=검증 3건 통과
- next: review #15
```

10걸음마다 **체크포인트 블록** — 컴팩션·중단 후 저널+GitHub만으로 복원 가능한 전체 스냅샷:

```markdown
## ✔ CHECKPOINT — step 10
- 범위: --label walter (이슈 8개 중 3 완료)
- 제외: #16 (반려 2회) · 보류 PR: 없음
- 머지 방식: squash · 모드: 감독
```

### 6. 종료 조건

**기본 목표는 범위 내 이슈 전부 완료** (순위 6 매치 = 범위 안에 더 할 일 없음). 그 외 종료: `--once` · 사용자 중단 · `--max` 도달. `--max` 기본값은 `max(20, 범위 내 열린 이슈 수 × 4)` — 이슈 하나가 보통 구현+리뷰+머지 2~3걸음이므로 정상 완주엔 안 걸리고, 폭주(반려 무한 반복 등)만 막는 안전상한이다.

### 사용량 가드 — 한도에 부딪히기 전에 멈춘다

한도 초과로 걸음 **중간**에 죽으면 잔재가 남으므로, **걸음 사이 경계**에서 미리 멈춘다:

- 매 걸음 dispatch 전 `npx ccusage@latest blocks --json 2>/dev/null`로 5시간 블록 사용량 추정 — **도구가 없거나 실패하면 조용히 건너뛴다** (가드는 보너스, 의존성 아님)
- 임계(기본 90%, `--usage-guard N`) 초과 시: 새 걸음을 시작하지 않고 INTERRUPTED 저널 + **블록 리셋 시각**을 남기고 종료
- 자동 대기·천천히 돌기는 하지 않는다 — "빠르게 진행 → 임계 중단 → 리셋 후 재실행"이 기본 전략

## 중단과 재개 (사용량 한도 대응)

에이전트가 결과 없이 소멸하거나 usage limit 오류가 감지되면, **종료 전에 반드시** 저널에 기록한다:

```markdown
## ⏸ INTERRUPTED — 2026-07-10 19:02
- 진행: step 7까지 완료, step 8(review #15) dispatch 중 중단
- 잔재: 브랜치 task/12-refresh 존재 · PR #15 리뷰 미완
- 재개: 한도 리셋 후 저장소 루트에서 `/issue-loop` 재실행 — GitHub 상태로 이어감
- 머지 대기열: #14 (review:approved)
```

그리고 사용자에게 같은 내용을 보고하고 멈춘다. **자동 대기·자동 재시도는 하지 않는다.**

재개는 특별한 절차가 없다: 상태가 전부 GitHub(이슈·PR·라벨·브랜치)에 있으므로 `/issue-loop`를 다시 실행하면 상태 수집부터 자연히 이어진다. 저널은 반려 횟수와 중단 경고를 복원하는 데만 쓴다. gh 인증만 있으면 **다른 머신·다른 세션(Claude Code CLI/웹)에서도 같은 방식으로 재개된다.**

## 종료 보고 형식

```markdown
## issue-loop 결과 (N걸음)

[기능 슬러그] #<상위>
  1/3 ✅ #11 (PR #14 승인 — 머지 대기)
  2/3 🔍 #12 (PR #15 리뷰 반려 1회 → 재작업 → 재리뷰 승인)
  3/3 ⛔ #13 (선행 #12 머지 대기)

### 🔀 머지 대기열 — 사람이 결정할 것
- PR #14 (issue #11) — review:approved
- PR #15 (issue #12) — review:approved · risk:high → 사람 리뷰 필수

### ⚠ 에스컬레이션
- #16 반려 2회 — 계약 재검토 필요
- #17 needs-respec — 설계 전제 깨짐 (이슈 코멘트 참조)

### 다음
- 머지 후 `/issue-loop` 재실행 → 블락 해제된 이슈 이어서 진행
- 열린 이슈가 없으면 `/issue-loop "<다음 기능>"`
```

## 하지 않는 것

- 설계 분해안·UI 시안 무승인 등록, 상위 이슈 닫기, `needs-respec` 계약 재설계 (모두 사람)
- `risk:high` PR 머지 (모드 무관 — 언제나 사람)
- 기본 모드에서 사용자 확인 없는 머지 / 무인 모드에서 강화 리뷰·CI 미통과 PR 머지
- 이 세션에서 직접 구현·리뷰
- 한도 도달 시 자동 대기 후 재시도