# task-113.1 보고서: Hook 파일 동시 쓰기 경쟁 조건(Race Condition) 수정

## 작업 내용
4개 hook 파일에서 JSON 동시 쓰기 시 flock(파일 잠금)을 추가하여 Race Condition 방지.
여러 봇이 동시에 같은 JSON 파일을 읽고-변환-쓰는 과정에서 파일이 깨지는 문제(UTF-8 corruption) 해결.

## 수정 파일 목록 (4개)

| 파일 | 변경 내용 | Lock 파일 |
|------|----------|-----------|
| /home/jay/.claude/hooks/pre-tool-use.sh | member-status.json 쓰기 블록에 flock 서브셸 추가 | .member-status.lock |
| /home/jay/.claude/hooks/post-tool-use.sh | member-status.json 쓰기 블록에 flock 추가 | .member-status.lock |
| /home/jay/.claude/hooks/user-prompt-submit.sh | bot-activity.json 쓰기 블록에 flock 추가 | .bot-activity.lock |
| /home/jay/.claude/hooks/stop-qc-reminder.sh | bot-activity.json 쓰기 블록에 flock 추가 | .bot-activity.lock |

## 수정 패턴
```bash
LOCK="/home/jay/workspace/memory/events/.<파일명>.lock"
(
  flock -w 5 200 || exit 0
  # 기존 jq 읽기-변환-쓰기 로직 그대로 유지
) 200>"$LOCK"
```
- `flock -w 5 200`: fd 200에 대해 최대 5초 대기 후 잠금 획득
- `|| exit 0`: 잠금 실패 시 안전하게 종료 (hook이 Claude를 차단하지 않음)
- 기존 `jq + mv` atomic write 패턴 완전 유지
- 기존 `trap 'exit 0' ERR` 패턴 유지

## 생성 파일
- /home/jay/workspace/teams/dev2/plan-task-113.1.md (실행 계획서)

## 테스트 결과 (헤임달)
- bash -n 문법 검증: 4/4 파일 통과
- flock 패턴 존재 확인: 4/4 파일 적용 확인
- Lock 파일 명명 규칙 일관성: 확인
- 동시 쓰기 시뮬레이션 (10개 프로세스 병렬): count=10 정확히 일치
- flock 실패 시 exit 0 안전 종료: 확인
- atomic write 패턴 유지: 확인
- trap 'exit 0' ERR 유지: 확인

## 버그 유무
없음

## 팀장 검토 결과
- 오딘(직접 수행): 4개 파일 편집 - 1차 완료, 수정 사항 없음
- 헤임달(테스터): 7개 검증 항목 모두 통과 - 1차 검토 통과, 수정 사항 없음
- 토르/프레이야/미미르: 본 작업은 shell hook 수정으로, 백엔드/프론트엔드/UX 역할 불필요하여 미배정

## 검토한 대안과 기각 사유
1. **lockfile 유틸리티 사용** → 기각: flock이 POSIX 표준에 더 가깝고, 별도 패키지 의존성 없음
2. **fd 번호를 9 대신 200 사용** → 채택: fd 200은 관례적으로 flock 전용으로 사용되며 충돌 가능성 극히 낮음
3. **flock 타임아웃 10초** → 기각: JSON 쓰기는 ms 단위로 5초면 충분. 오히려 긴 타임아웃은 hook 지연 유발
4. **전체 hook을 flock으로 감싸기** → 기각: 쓰기 블록만 감싸야 잠금 범위 최소화, 다른 로직(파싱 등)에 불필요한 대기 방지

## 수정 기록 로그
- 2026-03-02 오딘: pre-tool-use.sh 79-89줄 → flock 서브셸로 래핑
- 2026-03-02 오딘: post-tool-use.sh 70-86줄 → flock 추가 + 200> redirect 추가
- 2026-03-02 오딘: user-prompt-submit.sh 26-44줄 → flock 추가 + 200> redirect 추가
- 2026-03-02 오딘: stop-qc-reminder.sh 40-56줄 → flock 추가 + 200> redirect 추가

## 셀프 QC (System 2 Forcing)

### 1. 이 변경이 다른 파일에 영향을 미치는가?
Lock 파일(.member-status.lock, .bot-activity.lock)이 /home/jay/workspace/memory/events/ 디렉토리에 새로 생성됨. 이 파일들은 flock 전용이며 다른 프로세스가 참조하지 않으므로 영향 없음. 4개 hook 파일은 서로 독립적으로 동작하며, 같은 JSON을 쓰는 파일끼리 같은 lock을 공유하여 정확히 의도대로 동기화됨.

### 2. 이 로직의 엣지 케이스는 무엇인가?
- flock 타임아웃(5초 초과): `|| exit 0`으로 안전 종료. 상태 업데이트 누락되지만 다음 hook 호출에서 갱신됨.
- Lock 파일이 없는 경우: `200>"$LOCK"`이 자동 생성하므로 문제 없음.
- 디스크 풀: lock 파일 생성 실패 → flock 실패 → exit 0 → 안전 종료.
- 프로세스 비정상 종료: flock은 fd 기반이므로 프로세스 종료 시 자동 해제.

### 3. 이 구현이 작업 지시와 정확히 일치하는가?
작업 지시: "각 파일에서 JSON 쓰기 블록을 flock으로 감싸기. 패턴: ( flock -w 5 200 || exit 0; 기존 jq 로직 ) 200>LOCK". 구현: 4개 파일 모두 정확히 이 패턴으로 적용함. member-status.json은 .member-status.lock, bot-activity.json은 .bot-activity.lock 사용. 지시사항 100% 일치.

### 4. 에러 처리와 보안은 확인했는가?
- flock 실패 시 exit 0: hook이 절대 Claude를 차단하지 않음 (확인)
- trap 'exit 0' ERR: 기존 패턴 유지 (확인)
- 2>/dev/null || true: 기존 에러 억제 패턴 유지 (확인)
- Lock 파일 경로: 쓰기 대상과 같은 디렉토리에 dot-prefix로 생성. 보안 위험 없음.

### 5. 테스트가 모든 경로를 커버하는가?
- 정상 경로: 10개 동시 프로세스 쓰기 시뮬레이션으로 검증 (count=10 정확)
- 문법 오류: bash -n으로 4파일 모두 검증
- flock 패턴 존재: grep으로 확인
- 실패 경로: flock 실패 시 exit 0 동작 확인
- atomic write 유지: jq + mv 패턴 보존 확인
- 커버되지 않는 경로: 실제 Claude hook 컨텍스트에서의 실행은 운영 환경에서만 확인 가능 (시뮬레이션으로 대체)