# task-619.1 완료 보고서: bot-activity.json 실시간 감시 → 완료 즉시 감지 시스템

**작성자**: 라(Ra, 개발3팀장) | **작성일**: 2026-03-16 | **검증 레벨**: critical

---

## SCQA

**S**: `.done` 프로토콜이 4차례 개선(607.1, 609.1, 613.1, 616.1)에도 완료 감지 신뢰성 문제가 반복되어 왔다. Pull 모델은 실시간이 아니고, 5분 cron + 30분 에스컬레이션은 너무 느리다. 반면 대시보드의 bot-activity.json은 처리 중↔유휴 상태를 실시간으로 정확하게 반영하고 있다.

**C**: 제이회장님의 직접 제안 — "작업중 초록불 꺼지면 위스퍼가 너한테 푸시" — 을 구현하지 못한 상태이므로, 완료 알림은 여전히 지연(최대 30분)되거나 누락되는 위험이 있다.

**Q**: bot-activity.json의 `processing → idle` 전환을 실시간으로 감지하여 .done 파일 확인 즉시 텔레그램 알림을 보낼 수 있는가?

**A**: 3초 폴링 방식의 `activity-watcher.py` 데몬을 신규 구현하여 전환 감지 후 즉각 알림을 전송. 18개 테스트 전체 PASS, pyright 에러 0건, black/isort OK. 데몬 실행 중(PID 539136)이며 done-protocol.log에 이벤트 기록 확인. done-watcher.sh에는 중복 알림 방지 로직을 추가해 백업 역할로 재조정.

---

## 구현 상세

### 신규 파일

| 파일 | 역할 | 크기 |
|------|------|------|
| `scripts/activity-watcher.py` | 3초 폴링 감시 데몬 | 7,780 bytes |
| `scripts/start-activity-watcher.sh` | start/stop/restart/status/logs 관리 | 2,285 bytes |
| `scripts/tests/test_activity_watcher.py` | 테스트 스위트 (18개) | 10,935 bytes |

### 수정 파일

- `scripts/done-watcher.sh`: 중복 알림 방지 로직 추가 (라인 23-27)
  ```bash
  if grep -q "\[activity-watcher\].*${task_id}.*완료 감지" "$LOG" 2>/dev/null; then
      log "${task_id}: activity-watcher가 이미 완료 감지, done-watcher 스킵"
      continue
  fi
  ```

### 데몬 실행 상태

```
$ bash scripts/start-activity-watcher.sh status
running (PID 539136)

$ tail -2 logs/done-protocol.log
[2026-03-16T16:46:18.045388+09:00] [activity-watcher] activity-watcher 시작
[2026-03-16T16:46:18.045512+09:00] [activity-watcher] 초기 상태 로드 완료: {'anu': 'idle', 'dev1': 'idle', 'dev2': 'processing', 'dev3': 'idle'}
```

---

## 완료 기준 체크리스트

- [x] activity-watcher.py 작성 및 정상 동작
- [x] start-activity-watcher.sh 시작/중지/상태 스크립트
- [x] 테스트 전체 통과 (18 passed, 0 failed)
- [x] done-watcher.sh 중복 알림 방지 로직 추가
- [x] activity-watcher 데몬 실행하여 실제 작동 확인 (PID 539136)
- [x] done-protocol.log에 이벤트 기록 확인

---

## 테스트 결과

```
18 passed in 0.08s
```

테스트 케이스 7종 (명세 §5 기준):
1. processing→idle 전환 감지 정상 동작 ✅
2. idle→idle (변화 없음) 시 알림 안 보냄 ✅
3. .done 파일 존재 시 알림 전송 ✅
4. .done 파일 미존재 시 로그만 기록 ✅
5. anu 봇 상태 변화 무시 ✅
6. JSON 파싱 에러 시 크래시 안 남 ✅
7. 시작 시 초기 상태 로딩 (오알림 방지) ✅

---

## 발견 이슈 및 해결

### 자체 해결 (1건)

1. **COKACDIR_KEY_ANU 하드코딩 fallback** — 환경변수 미설정 시 즉시 종료로 수정
   - 상세: `activity-watcher.py` 라인 151, `os.environ.get("COKACDIR_KEY_ANU", "c119085addb0f8b7")` → fallback 제거
   - COKACDIR_CHAT_ID는 기존 코드베이스 패턴(notify-completion.py)과 동일하게 기본값 유지 (공개값, 비민감)
   - 수정 후 pyright 0건, black OK 재확인

<details>
<summary>범위 외 pre-existing 실패 테스트 (본 작업과 무관)</summary>

- `tests/test_notify_completion.py`: `create_done_clear` 속성 미존재 (AttributeError) — notify-completion.py에서 이전에 제거된 함수 참조
- `tests/test_group_chat.py`: 페르소나 카운트 불일치 (21 예상, 20 실제) — 팀 구성 변경 미반영
- `tests/test_integration.py`: 임시 디렉토리에서 파일 미존재 — 테스트 환경 설정 이슈
- 모두 본 작업 변경 전부터 존재하는 실패이며 task-619.1 변경으로 인한 회귀 없음

</details>

---

## QC 검증 결과

### 자동 검증 (qc_verify.py)

```json
{
  "overall": "FAIL (file_check만 FAIL - finish-task.sh 실행 전 정상)",
  "checks": {
    "file_check": "FAIL (task-619.1.done 미존재 — 완료 처리 전 정상 상태)",
    "data_integrity": "PASS",
    "test_runner": "PASS (855 passed)",
    "tdd_check": "PASS",
    "pyright_check": "PASS (0 errors, 0 warnings)",
    "style_check": "PASS (black OK, isort OK)"
  },
  "summary": "6 PASS, 1 FAIL (정상), 3 SKIP"
}
```

### 마아트 독립 검증

**최종 판정: PASS**

완료 기준 6개 항목 전부 충족 확인. 코드 품질, 테스트, 데몬 실행, 로그 기록, 중복 알림 방지 로직 모두 스펙 대비 정상 구현 확인. file_check FAIL은 finish-task.sh 실행 전 정상 상태.

---

## GLM(openclaw) 평가

- 구현 완성도: 완료 기준 6개 항목 모두 충족
- 코드 품질: pyright 0건, black/isort OK
- 테스트: 명세 7개 케이스 + 추가 11개 = 18개 전체 작성
- 보안 이슈: COKACDIR_KEY_ANU 하드코딩 fallback (라 팀장 직접 수정)
- start-activity-watcher.sh: 명세(start/stop/status) 이상으로 restart/logs 추가 구현