# task-1629.1 완료 보고서: fireauto Phase 3-F3 자기 학습 — 주간 배치 분석 + 학습 리포트

**S**: fireauto Phase 3 기능 통합의 일부로, audit-trail.jsonl에서 주간 파일 접근 빈도를 분석하여 반복 수정되는 "핫스팟 파일"을 자동 감지하는 학습 시스템(F3)이 요구되었다.

**C**: 이전까지 반복 패턴 감지는 아누 메모리에만 의존했으며, "같은 파일이 여러 task에서 반복 수정되는" 문제를 체계적으로 포착할 방법이 없었다. whisper-briefing에 미처리 학습 피드백을 표시하는 기능도 부재했다.

**Q**: audit-trail 기반 주간 배치 분석으로 핫스팟 파일을 자동 감지하고, 화이트리스트/임계값 설정으로 노이즈를 필터링하며, whisper-briefing에 미처리 건수를 연동할 수 있는가?

**A**: learning-analyzer.py 스크립트, 화이트리스트/임계값 설정 파일, whisper-compile.py 개선을 구현 완료했다. pytest 145건(learning-analyzer 31건 + whisper-compile 114건) 전체 통과, pyright 에러 0건. 실제 audit-trail 데이터(2026-04-07 주, 113 tasks)에서 정상 실행되어 화이트리스트 4건 제외, 핫스팟 0건(실제 데이터상 파일당 1 task만 수정하여 정상) 결과를 확인했다.

## 생성/수정 파일

### 신규 생성 (4개)
- `/home/jay/workspace/scripts/learning-analyzer.py` — 주간 배치 학습 분석 스크립트 (핵심 구현)
- `/home/jay/workspace/config/learning-whitelist.yaml` — 인프라 파일 화이트리스트 (10개 파일 + 10개 패턴)
- `/home/jay/workspace/config/learning-thresholds.yaml` — 분석 임계값 설정 (min_task_count=3, min_task_ratio=0.3)
- `/home/jay/workspace/scripts/tests/test_learning_analyzer.py` — 단위 테스트 (6클래스 31케이스)

### 수정 (1개)
- `/home/jay/workspace/scripts/whisper-compile.py` — `load_pending_learnings` 함수: 파일 수 → 개별 pending 레코드 수 카운트로 변경

### 자동 생성 출력 (1개)
- `/home/jay/workspace/memory/learnings/weekly-2026-04-07.md` — 분석 결과 리포트 (113 tasks, 0 hotspots, 4 whitelist exclusions)

## 테스트 결과

- learning-analyzer 테스트: **31/31 passed** (0.14s)
- whisper-compile 테스트: **114/114 passed** (0.30s)
- pyright: **0 errors, 0 warnings**
- 기능 테스트: `python3 learning-analyzer.py --week 2026-04-07` 정상 실행
- whisper 연동 테스트: pending 레코드 개별 카운트 정상 (3건 = markdown bold 2건 + YAML frontmatter 1건)

## 구현 상세

### learning-analyzer.py 기능
1. audit-trail.jsonl 주간 범위 필터링 (week_start ~ week_start+7d)
2. `/tmp/` 경로 레코드 자동 제외 (테스트 temp 파일)
3. bot==anu 레코드 제외
4. task_id 없거나 unknown인 레코드 제외
5. 파일 경로 정규화 (WORKSPACE_ROOT 프리픽스 제거)
6. 화이트리스트 매칭 (exact file + fnmatch pattern)
7. AND 조건 임계값 (절대값 + 비율 동시 충족)
8. 파일 타입 분류 (.py→refactor_candidate, .yaml/.json/.toml→config_hotspot)
9. 우선순위 분류 (task_count≥5→high, ≥3→medium)
10. 각 핫스팟에 status: pending + 수정 task 목록 포함 (F9 흡수)

### whisper-compile.py 변경
- `load_pending_learnings`: `pattern.search()` (파일당 1건) → `pattern.findall()` (레코드별 카운트)
- 3가지 패턴 매칭: `**status**: pending`, `- **status**: pending`, `status: pending`
- 기존 테스트 100% 호환 유지

### v1 한계 명시
- 리포트/whisper에 "학습 기능 v1 — 에러 유사도 미지원(v2 예정)" 문구 자동 포함

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **generate_report 인터페이스 불일치** — 테스트에서 directory를 전달하나 구현은 file path를 기대. output_dir 파라미터로 변경하여 해결
2. **화이트리스트 패턴 매칭 실패** — compute_hotspots에서 전체 경로가 들어올 때 fnmatch 실패. _normalize_path를 compute_hotspots에서도 호출하도록 수정
3. **테스트 헬퍼 누락 필드** — _make_hotspot에 task_ratio, total_tasks 필드 누락. 필드 추가하여 해결

## 셀프 QC 체크리스트

- [x] 1. 다른 파일 영향: whisper-compile.py의 load_pending_learnings 변경 — 기존 테스트 114건 전체 통과로 호환성 확인
- [x] 2. 엣지 케이스: 빈 audit-trail, 누락 config 파일, unknown task_id, /tmp/ 경로 — 모두 테스트 커버
- [x] 3. 작업 지시와 일치: PRD F3 요구사항 6개 항목 모두 구현
- [x] 4. 에러 처리/보안: 모든 로더에 try/except graceful degradation, 외부 입력 없음
- [x] 5. 테스트 커버리지: 6클래스 31케이스 — load/parse/compute/generate/CLI 전 경로
- [x] 6. 발견 이슈 모두 해결: 3건 자체 해결
- [x] 7. 코드 아키텍처: 순수 함수 분리, 단일 책임 원칙 준수
- [x] 8. 인터페이스 변경: load_pending_learnings 반환값 의미 변경 (파일 수 → 레코드 수) — 기존 테스트에서 동일 결과 보장 확인

## 모델 사용 기록

- 카르티케야(백엔드): learning-analyzer.py + config 파일 + whisper-compile.py 수정 / 사용 모델: sonnet
- 하누만(테스터): test_learning_analyzer.py 작성 / 사용 모델: sonnet

## 세션 통계
- 총 도구 호출: 23회

### 수정 파일 목록
- /home/jay/workspace/scripts/tests/test_learning_analyzer.py: 8회 (Edit, Write)
- bash_cmd: 6회 (Bash)
- /home/jay/workspace/scripts/learning-analyzer.py: 4회 (Edit, Write)
- /home/jay/workspace/config/learning-thresholds.yaml: 1회 (Write)
- /home/jay/workspace/config/learning-whitelist.yaml: 1회 (Write)
- /home/jay/workspace/memory/reports/task-1629.1.md: 1회 (Write)
- /home/jay/workspace/memory/tasks/task-1629.1.md: 1회 (dispatch)
- /home/jay/workspace/scripts/whisper-compile.py: 1회 (Edit)

### 도구 사용 현황
- Edit: 11회
- Bash: 6회
- Write: 5회
- dispatch: 1회