# task-897.1 완료 보고서: .done 자동 감지 메커니즘 설계

## SCQA

**S (Situation)**: 현재 팀 작업 완료 시 `memory/events/<task_id>.done` 파일이 생성되며, finish-task.sh → notify-completion.py → cokacdir --cron 경로로 아누에게 알림이 전달된다. done-watcher.sh가 systemd 30초 타이머로 stale 에스컬레이션을 수행하고, activity-watcher.py는 3초 폴링을 위한 코드가 있다.

**C (Complication)**: 그러나 notify-completion.py의 `cokacdir --cron --at 1m`은 새 Claude 세션을 생성하여 토큰을 소모한다. activity-watcher.py는 **미실행 상태**이며, `find_done_file` 함수에 팀 무관 반환 버그 + `BOT_TEAM_MAP`에 dev4-8 누락 버그가 발견되었다. 이로 인해 dev8이 11시간 유휴 대기하는 등 리소스 낭비가 반복되고 있다.

**Q (Question)**: 토큰 소모 0, 30초 이내 감지를 보장하면서 기존 시스템과 호환되는 .done 자동 감지 메커니즘을 설계할 수 있는가?

**A (Answer)**: 에이전트 미팅(헤르메스/로키/펜리르, 3사이클)을 통해 **2-Layer 하이브리드 설계**에 만장일치 합의하였다. Layer 1(Primary): notify-completion.py의 cokacdir --cron을 `requests.post()` 직접 Telegram API로 교체 (즉시, 토큰 0). Layer 2(Fallback): done-watcher.sh에 미알림 .done 감지 + 직접 알림 추가 (최대 30초). 추가로 activity-watcher.py의 핵심 버그 2건을 수정하고 systemd 서비스로 등록한다. 펜리르의 mv 기반 원자적 소유권 패턴으로 TOCTOU 레이스 컨디션을 방어한다.

---

## 작업 내용

### 에이전트 미팅 진행
- **참석자**: 헤르메스(1팀장, 주관), 로키(보안팀장, DA), 펜리르(보안팀원, DA 보조)
- **사이클**: 3회 (제안 → 반론 → 합의)
- **결과**: 만장일치 합의 (3/3)

### 검토 방안 5가지 평가

| 방안 | 판정 | 사유 |
|------|------|------|
| A. inotifywait 데몬 | 기각 | 미설치, 신규 데몬 = 기존 결정 위반 |
| B. Systemd Timer 폴링 강화 | 채택 (Fallback) | 기존 30초 타이머 활용, 최소 수정 |
| C. 직접 Telegram API | 채택 (Primary) | 토큰 0, 즉시 감지, notify-completion.py 내부 |
| D. Systemd Path Unit | 기각 | events 디렉토리 노이즈 과다 |
| E. activity-watcher 복구 | 채택 (보조) | 버그 수정 필수, bot-activity idle 전환 |

### 핵심 발견 (3건)

1. **activity-watcher.py `find_done_file` 버그**: 팀과 무관하게 첫 번째 .done 파일을 반환하여 잘못된 작업 ID로 알림 발송. dev8 11시간 유휴의 직접 원인으로 추정.

2. **activity-watcher.py `BOT_TEAM_MAP` 불완전**: dev1-3만 등록, dev4-8 누락. 8팀 체제에서 5팀의 idle 전환이 감지되지 않음.

3. **done-watcher.sh 비원자적 마커 생성**: `touch $escalated_file`이 O_EXCL 없이 사용되어 동시 실행 시 중복 에스컬레이션 가능.

---

## 최종 설계 요약

### 2-Layer 하이브리드 아키텍처

**Layer 1 (Primary, 즉시)**
- notify-completion.py: cokacdir --cron → requests.post() 직접 Telegram Bot API
- 타임아웃 10초, 재시도 3회 (지수 백오프)
- 성공 시 .done.notified 마커 생성 (O_EXCL)

**Layer 2 (Fallback, 최대 30초)**
- done-watcher.sh: 미알림 .done 감지 시 직접 Telegram 알림
- mv 기반 원자적 소유권: .done → .done.processing → 성공: .done.notified / 실패: .done
- flock 동시 실행 방지
- 배치 알림: 다건 동시 감지 시 단일 메시지

**보조 (bot-activity 전환)**
- activity-watcher.py: 버그 수정 + systemd user service 등록

---

## 산출물

| # | 파일 | 설명 |
|---|------|------|
| 1 | memory/meetings/task-897.1-done-polling.md | 에이전트 미팅 기록 (3사이클) |
| 2 | memory/specs/done-polling-spec.md | 최종 설계 스펙 문서 |
| 3 | memory/reports/task-897.1.md | 본 보고서 |

---

## 발견 이슈 및 해결

### 자체 해결 (0건)
- 본 태스크는 설계 작업으로 코드 변경 없음. 발견된 버그는 구현 태스크에서 수정 예정.

### 범위 외 미해결 (3건)
1. **activity-watcher.py find_done_file 버그** — 범위 외 사유: 구현 태스크로 분리 필요 (설계만 완료)
2. **activity-watcher.py BOT_TEAM_MAP 불완전** — 범위 외 사유: 상동
3. **done-watcher.sh 비원자적 마커** — 범위 외 사유: 상동

---

## 구현 로드맵

- **Phase 1 (P0)**: notify-completion.py 수정 + activity-watcher.py 버그 수정 + systemd 등록
- **Phase 2 (P1)**: done-watcher.sh 강화 + 통합 테스트 (8개 시나리오)
- **Phase 3 (P2)**: EnvironmentFile 범위 제한, 16팀 확장 테스트

---

## 셀프 QC 체크리스트

- [x] 1. 이 변경이 다른 파일에 영향을 미치는가? → 설계 문서만 작성, 코드 변경 없음. 구현 시 영향 파일: notify-completion.py, done-watcher.sh, activity-watcher.py, systemd services
- [x] 2. 엣지 케이스는? → 펜리르 8대 시나리오로 분석 완료 (동시완료, TOCTOU, 재부팅, API장애 등)
- [x] 3. 작업 지시와 일치하는가? → task-897.1 요구사항(토큰0, 빠른감지, 호환성, 레이스방지, 선점방지) 모두 충족
- [x] 4. 보안 확인? → 로키 보안 리뷰 완료, Bot Token 관리/symlink 거부/원자적 상태전환 설계
- [x] 5. 테스트 커버리지? → 8개 테스트 시나리오 설계 (T1-T8), 구현 Phase 2에서 실행
- [x] 6. 이슈 모두 해결? → 설계 범위 내 이슈 없음, 발견된 코드 버그 3건은 구현 태스크로 분리

---

## QC 자동 검증

(설계/미팅 작업으로 코드 변경 없음, qc_verify.py --skip api_health --skip test_runner 적용)