# task-96.1 완료 보고서: 이벤트 큐 시스템 구현

## 작업 요약
팀 완료 통보의 순차 처리를 보장하는 FIFO 이벤트 큐 시스템을 구현했습니다.

**문제**: 여러 팀이 동시에 완료되면 독립 세션으로 순서 보장 없이 보고되는 문제
**해결**: 파일 기반 FIFO 큐 + 아누 훅에서 순차 처리 가이드

## 생성/수정 파일 목록

### 새로 생성
- `/home/jay/workspace/memory/event-queue.py` — FIFO 큐 매니저 (EventQueue 클래스 + CLI)
  - 변경 사유: 핵심 큐 매니저 모듈 신규 구현
  - 담당: 불칸 (백엔드)
- `/home/jay/workspace/memory/events/event-queue.json` — 큐 데이터 파일 (초기 상태)
  - 변경 사유: 큐 데이터 저장소 생성
  - 담당: 불칸 (백엔드)
- `/home/jay/workspace/teams/dev1/test_event_queue.py` — 테스트 코드 (31개 테스트)
  - 변경 사유: 전체 기능 검증
  - 담당: 아르고스 (테스터)

### 수정
- `/home/jay/workspace/prompts/team_prompts.py` — 워크플로우에 enqueue 단계 추가
  - `_build_direct_prompt()`: 6단계에 enqueue 명령 추가 (기존 6→7, 7→8 번호 변경)
  - `_build_glm_prompt()`: 8단계에 enqueue 명령 추가 (기존 8→9 번호 변경)
  - 기존 .done + cron 통보 완전 유지 (하위호환)
  - 담당: 헤르메스 (팀장)
- `/home/jay/.claude/hooks/user-prompt-submit.sh` — anu 케이스에 이벤트 큐 count 체크 추가
  - pending > 0이면 "미처리 이벤트 N건 대기 중" 메시지 출력
  - count 실패 시 "0" 폴백으로 안전 처리
  - 담당: 헤르메스 (팀장)

### 건드리지 않은 파일 (작업 지시 준수)
- `_build_work_philosophy_section()` — 미수정
- `_build_verification_section()` — 미수정
- `_build_cowork_section()` — 미수정
- cron 통보 프롬프트의 .done.clear 지시 — 미수정
- 기존 .done 프로토콜 전체 — 호환 유지

## 기술 설계 포인트

### event-queue.py 주요 특징
- **파일 잠금**: `.lock` 파일에 `fcntl.LOCK_EX` (배타적 잠금) → 동시 enqueue 안전
- **Atomic write**: tempfile → `os.replace()` → 프로세스 중단에도 파일 무결성 보장
- **백업 복구**: 쓰기 전 `.bak` 생성 → JSON 손상 시 자동 복구
- **이벤트 ID**: `evt-NNN` 시퀀스 (queue + processed 스캔 후 max+1)

### 검토한 대안과 기각 사유
- **SQLite 기반 큐**: 기각 — 작업 지시에 JSON 파일 명시, 외부 의존성 불필요
- **Redis/외부 큐**: 기각 — 의존성 최소화 원칙, 현재 규모에서 파일 기반이 적절
- **threading.Lock 대신 fcntl**: 채택 — 멀티프로세스(별도 Claude Code 세션)간 잠금 필요

## 테스트 결과

**31 passed, 0 failed** (0.87s)

- FIFO 순서 보장: 4 PASS
- 동시 enqueue 멀티프로세스 (5 workers): 2 PASS
- 빈 큐 graceful 처리: 5 PASS
- CLI 전체 서브커맨드: 8 PASS
- user-prompt-submit.sh 훅 통합: 3 PASS
- build_prompt() enqueue 포함 확인: 5 PASS (dev1/dev2/dev3 모두)
- 기타 통합: 4 PASS

## 버그 유무
발견된 버그 없음.

## 비고
- processed 배열은 무한 증가 가능 → 향후 정리 크론 고려 가능 (현재는 불필요)
- event-queue.py는 하이픈 파일명으로 직접 import 불가 → `importlib.util` 사용 필요 (CLI 사용이 주 목적이므로 문제 없음)
- enqueue는 기존 .done 파일 + cron 통보의 **추가 안전망** 역할 (하위호환 완전 유지)