# task-1623.1 완료 보고서: fireauto Phase 2 — Hook 인프라 강화 [F1, F2, F7]

## S - Situation
fireauto 통합 PRD(prd-fireauto-integration.md) Phase 2로, 기존 Hook 스크립트(post-tool-use.sh, stop-qc-reminder.sh)와 QC 파이프라인(qc_verify.py)에 작업 추적·통계·에러 감지 기능을 추가해야 한다. 현재 audit-trail.jsonl에는 task_id 필드가 없어 "어떤 작업에서 어떤 파일을 수정했는지" 추적이 불가능하다.

## C - Complication
3개 Feature(F1 audit-trail 강화, F2 세션 통계, F7 에러 감지+재시도)를 기존 Hook 스크립트를 확장하여 구현해야 하며, 8개 팀이 동시 사용하는 공유 Hook이므로 회귀 방지가 핵심이다. 또한 COKACDIR_TASK_ID 환경변수가 dispatch.py에서 미주입 상태여서 task_id 전달 방식을 결정해야 했다.

## Q - Question
기존 Hook 기능(팀원 상태 업데이트, QC 리마인더, 봇 idle 기록)의 회귀 없이 3개 Feature를 안전하게 통합할 수 있는가?

## A - Answer
CWD 기반 marker file 방식(.task_id)으로 task_id 전달 문제를 해결하고, 기존 5개 파일을 확장하여 F1·F2·F7을 구현 완료. bash -n 3개, python py_compile 1개, json.tool 1개 — 전체 문법 검증 통과. 기존 audit-trail.jsonl 파서들은 .get() 패턴 사용으로 하위 호환 확인.

---

## 수정 파일 목록

| 파일 | Feature | 변경 내용 |
|------|---------|-----------|
| `/home/jay/.claude/hooks/post-tool-use.sh` | F1, F7-1 | task_id 읽기 + JSONL schema v2 + Bash meaningful 기록 + 에러 카운터 |
| `/home/jay/.claude/hooks/user-prompt-submit.sh` | F1 지원 | 프롬프트에서 task_id 추출 → .task_id marker 파일 생성 |
| `/home/jay/.claude/hooks/stop-qc-reminder.sh` | F2 | 세션 통계 집계 + 보고서 append + .done 미생성 감지 |
| `/home/jay/.claude/settings.json` | F1 | PostToolUse matcher에 Bash 추가 |
| `/home/jay/workspace/teams/shared/qc_verify.py` | F7-2 | pyright_check 재시도 카운터 + 미해결 이슈 보고서 기록 |

## Feature 구현 상세

### F1: audit-trail.jsonl 강화
- task_id 3단계 폴백: CWD/.task_id → COKACDIR_TASK_ID env → "unknown" + stderr 경고
- JSONL에 `task_id`, `schema_version:2` 필드 추가 (기존 레코드와 구별)
- Bash meaningful 기록: git commit/push/merge, npm install/build/test, docker, kubectl, terraform, pip install, pytest 등 7개 패턴
- jq 기반 안전한 JSON 직렬화 (명령어 내 특수문자 이스케이프)
- 명령어 길이 500바이트 제한

### F2: 세션 통계 자동 생성
- Stop hook에서 audit-trail.jsonl task_id 기반 집계
- 파일별 수정 횟수 + 도구별 사용 현황 생성
- reports/{task_id}.md 존재 시 "## 세션 통계" append, 없으면 retrospectives/{task_id}.md 생성
- timeout 5초 래퍼로 성능 보호
- .done 미생성 시 stderr 경고
- dev1~dev8 전 팀 지원 (case 패턴 확장)

### F7: 에러 감지 + 재시도
- **1단계 (Hook)**: Edit/Write 후 tool_output에서 error/failed/exception 패턴 감지 → retry-counters/{task_id}.count 카운터 → 3회 이상 시 stderr 에스컬레이션 경고
- **2단계 (QC)**: pyright_check FAIL 시 retry-counters/{task_id}.pyright_check.qc_count 카운터 관리 → 3회 미만은 재검증 권장, 3회 이상은 보고서에 "미해결 이슈" 자동 기록
- Hook 카운터와 QC 카운터 독립 경로 (상호 참조 없음)

### dispatch.py 환경변수 주입
- 확인 결과: dispatch.py는 cokacdir --cron으로 스케줄링하여 환경변수가 세션에 전달되지 않음
- 대안: CWD marker file 방식(.task_id) 채택 — UserPromptSubmit hook에서 프롬프트의 "작업 ID: task-XXX" 패턴 추출하여 ${CWD}/.task_id 생성
- 기존 .bot-team marker와 동일 패턴으로 일관성 확보

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **COKACDIR_TASK_ID 미주입** — CWD marker file 방식으로 대체 (user-prompt-submit.sh에 task_id 추출 로직 추가)
2. **Bash 명령어 JSON 이스케이프** — jq -nc 사용으로 안전한 직렬화 (echo + 문자열 연결 대신)
3. **dev4~dev8 누락** — stop-qc-reminder.sh case 패턴을 dev1~dev8로 확장

### 범위 외 미해결 (2건)
1. **dispatch.py에 COKACDIR_TASK_ID 환경변수 주입** — 범위 외 사유: dispatch.py는 시스템 공유 파일이며 cokacdir 바이너리의 세션 관리 구조상 env var 전달 불가. marker file로 대체 완료.
2. **dev2 팀 qc_verify.py 동기화** — 범위 외 사유: shared qc_verify.py만 수정 지시. 각 팀 qc_verify.py 복사본은 별도 동기화 작업 필요.

## 테스트 결과

- bash -n post-tool-use.sh: OK
- bash -n stop-qc-reminder.sh: OK
- bash -n user-prompt-submit.sh: OK
- python3 -m json.tool settings.json: OK
- python3 -m py_compile qc_verify.py: OK
- 회귀 분석: audit-trail.jsonl 파서 5개 파일 확인 — 모두 .get() 패턴 사용으로 하위 호환

## 모델 사용 기록

- 오딘 (팀장/Opus): 설계, 분배, 검토, 통합, QC
- 토르 (백엔드/Sonnet): F1+F7-1 post-tool-use.sh + user-prompt-submit.sh + settings.json 구현
- 토르 (백엔드/Sonnet): F2 stop-qc-reminder.sh 세션 통계 구현
- 헤임달 (테스터/Sonnet): F7-2 qc_verify.py 재시도 로직 구현
- haiku: 코드베이스 탐색 2건 (isMeaningfulBash 패턴 검색, 회귀 영향 분석)