# bot-status-resolver 사용 가이드

> 도입일: 2026-05-02 | task-2375 산출물 | 대상: 아누(개발실장), 회장 보고 함수

## 목적

봇 상태를 보고할 때 "미완성/멈춤" 같은 단정 키워드를 객관적 라벨(MERGED/ALIVE/IDLE/STALE/UNKNOWN)로 대체한다.

## 배경

2026-05-02 task-2373(페룬, dev6) 사고:
- 아누가 `gh pr list` (PR 없음) + `git log` (commits 4건)만 보고 "봇 멈춤/미완성"으로 회장에게 보고
- **봇 ps 미확인**이 결정적 누락 — 실제 봇은 살아있고 19:40에 PR 생성 중이었음
- 회장 지시: "코드 자동화로 이런 실수 없게 할 수 있지 않을까?"

## 호출 의무

아누가 아래 상황에서 봇 상태를 보고할 때는 반드시 resolver를 먼저 호출한다.

- 회장 보고 (정기/특별)
- task 상태 점검
- 다른 팀에 봇 상태 공유

```bash
python3 /home/jay/workspace/scripts/bot_status_resolver.py --task-id task-XXXX
```

또는 사람 친화적 출력:

```bash
python3 /home/jay/workspace/scripts/bot_status_resolver.py --task-id task-XXXX --format human
```

## 5개 라벨 정의

| 라벨 | 객관적 조건 | 의미 |
|---|---|---|
| **MERGED** | `pr_merged_at != null` | PR 머지 완료 (다른 조건 무시) |
| **ALIVE** | `ps_alive AND last_commit_age_min < 5` | 봇 활발 활동 중 |
| **IDLE** | `ps_alive AND last_commit_age_min >= 5` | 봇 살아있지만 commit 없음 (디버깅/finish-task 진행) |
| **STALE** | `NOT ps_alive AND last_commit_age_min > 30 AND no_pr` | 봇 죽었고 30분+ commit 없고 PR 없음 |
| **UNKNOWN** | 위 4개 조건 모두 불충족 | 판정 불가 (조사 필요) |

판정 순서는 위 표 순서대로 (MERGED가 최우선).

## 보고 규칙

### 금지

- "봇 멈춤", "미완성", "안 돌아감" 같은 단정 키워드
- ps 확인 없이 commits/PR만 보고 상태 판단
- evidence 없는 결론

### 의무

- `bot_status` 라벨만 사용 (5개 중 하나)
- `evidence` 배열을 그대로 인용 (재해석 금지)
- 추가 해석이 필요하면 별도 섹션에 분리

## 사용 예시 5건

### 예시 1 — task-2373 사고 케이스 재구성

```bash
$ python3 scripts/bot_status_resolver.py --task-id task-2373 --format human
dev6 (페룬): IDLE — task-2373 진행 중 (17분 전 commit, PR 생성 중)
```

JSON evidence:
```
["ps:1356421 (alive)", "ps:1439822 (alive)",
 "last_commit:f8e9778 (17m ago)", "no_pr_yet"]
```

→ 회장 보고 시 "봇 멈춤" ❌ → "IDLE — PR 생성 중" ✅

### 예시 2 — 정상 진행 중

```bash
$ python3 scripts/bot_status_resolver.py --task-id task-2380 --format human
dev1 (에리카): ALIVE — task-2380 활발히 진행 중 (2분 전 commit)
```

### 예시 3 — 머지 완료

```bash
$ python3 scripts/bot_status_resolver.py --task-id task-2367 --format human
dev2 (마르스): MERGED — task-2367 완료 (머지됨)
```

### 예시 4 — 진짜 멈춘 봇

```bash
$ python3 scripts/bot_status_resolver.py --task-id task-XXXX --format human
dev5 (이시스): STALE — task-XXXX 멈춤 (45분 전 commit, PR 없음)
```

이 경우는 진짜 봇 멈춤으로 보고 가능.

### 예시 5 — JSON 파이프 처리

```bash
$ python3 scripts/bot_status_resolver.py --task-id task-2375 | jq -r '.bot_status'
IDLE
```

자동화 스크립트에서 활용 가능.

## 회장 보고 템플릿

```
[task-2373 / dev6 페룬 상태]
- bot_status: IDLE
- evidence:
  - ps 살아있음 (PID 1356421, 1439822)
  - last commit 17분 전 (f8e9778)
  - PR 생성 중 (no_pr_yet)
- 판단: 봇 정상 진행 중. PR 생성 단계.
```

vs (잘못된 보고 예시):

```
[잘못된 보고 — 절대 금지]
페룬 봇이 멈춤. PR도 없고 17분간 commit도 없음.
→ ps 미확인. "멈춤" 단정 금지.
```

## 통합 포인트

### 아누 보고 함수에 통합

아누의 보고 생성 로직은 봇 상태 항목에서 resolver를 호출해 `bot_status` + `evidence`만 사용한다. 추측·요약 금지.

### task-2374 (옵션 D 머지 후) 확장

`memory/state/task-XXXX.json` 머지 후, resolver는 state.json도 참조하여 정확도 향상 가능 (후속 작업).

### CI/모니터링 연동

`bot-status-watchdog.py` 등에서 호출하여 STALE 감지 시 알림 자동화 가능.

## 운영 메모

- resolver는 **read-only**다. 어떤 파일도 수정하지 않는다.
- 외부 명령 실패 시 graceful fallback (gh 미설치 → pr_number=null)
- 단위 테스트: `tests/dev3/test_bot_status_resolver.py` (16 cases, 5 labels + 경계값 + 사고 시뮬레이션)
- 최초 실패 사례: 2026-05-02 task-2373 (이 도구가 만들어진 이유)