# task-938.1 완료 보고서: 작업별 토큰 사용량 추적 엔진 + 워크플로우 통합

## SCQA

**S**: 운영 중인 작업 파이프라인에서 task-timers.json으로 작업별 소요 시간은 추적되고 있으나, 각 작업의 토큰 사용량 데이터는 수집되지 않아 비용 분석이 불가능했다.

**C**: Claude Code 세션 JSONL 파일에 메시지별 토큰 사용량이 기록되어 있으나, 이를 작업(task)에 매핑하여 집계하는 시스템이 없어 "어떤 작업이 토큰을 이상하게 많이 소모했는지" 파악할 수 없었다.

**Q**: JSONL 세션 데이터를 파싱하여 작업별 토큰 사용량을 자동 추적하고, 이상치를 감지하며, 대시보드에서 조회할 수 있는 시스템을 구축할 수 있는가?

**A**: 6개 Phase 전체 구현 완료. 토큰 파싱 엔진(token-tracker.py)으로 1,956개 JSONL 세션을 스캔하여 763개 태스크의 토큰 원장을 생성했다. task-timers.json 623건에 토큰 데이터 연동, 대시보드 API 2개 추가, SCQA 템플릿에 토큰 섹션 추가. pytest 24/24 통과, pyright 에러 0건.

## 생성/수정 파일 목록

**신규 생성 (3건)**
- `scripts/token-tracker.py` (193줄) — 토큰 파싱 엔진 + CLI
- `scripts/tests/test_token_tracker.py` (193줄) — 24개 테스트
- `memory/token-ledger.json` — 초기 스캔 결과 (763 태스크)

**수정 (2건)**
- `dashboard/server.py` — API 엔드포인트 2개 추가 + tasks API token_usage 연동
- `memory/specs/scqa-report-template.md` — 토큰 사용량 섹션 추가 (v1.2)

**자동 갱신 (1건)**
- `memory/task-timers.json` — 623건 태스크에 token_usage 필드 추가

## Phase별 구현 내역

**Phase 1 - 토큰 파싱 엔진**: parse_session()으로 JSONL 파일 파싱, user 메시지에서 task_id/team_id 정규식 추출, assistant 메시지에서 4종 토큰(input/cache_creation/cache_read/output) 집계

**Phase 2 - task-timer 연동**: enrich 명령으로 token-ledger.json → task-timers.json 자동 매핑. 기존 필드 보존 (하위 호환)

**Phase 3 - 워크플로우 통합**: SCQA 보고서 템플릿에 토큰 사용량 기재 항목 추가 (v1.2)

**Phase 4 - 대시보드 API**: `/api/token-usage` (전체/개별 조회), `/api/token-anomaly` (이상치), `/api/tasks` 응답에 token_usage 필드 자동 주입

**Phase 5 - 비용 추정**: 모델별 가격 적용 (Opus $15/$75, Sonnet $3/$15, Haiku $0.80/$4). 캐시: read 10%, creation 25%

**Phase 6 - 테스트**: 24개 테스트 (파싱 4, 매핑 5, 비용 6, 이상치 3, CLI 6)

## 초기 스캔 결과 (정량 데이터)

- 스캔 파일: 1,956개 JSONL
- 기록 태스크: 763개
- 총 토큰: 2,188,338,875
- 태스크당 평균: 2,868,071 토큰
- 총 비용 추정: $3,006.11
- 이상치 감지: 70건 (평균의 2배 이상)
- Top 1: task-4.4 (627M 토큰, 218.7x, $240.56)

## 테스트 결과

- pytest: 24/24 PASSED (0.09s)
- pyright: 0 errors, 0 warnings, 0 informations (token-tracker.py + test + server.py)
- black + isort: 적용 완료
- 파일 크기: 193줄 + 193줄 (200줄 제한 준수)

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **봇 워크스페이스 세션에 task_id 없음** — cokacdir 워크스페이스(디스패치 세션)에만 task_id가 포함됨을 확인. 두 소스 모두 스캔하되 task_id 매칭된 세션만 원장에 기록하는 방식으로 처리
2. **content가 list 형태인 경우** — user 메시지의 content가 string이 아닌 list[dict] 형태도 있음. `_text()` 헬퍼로 양쪽 모두 처리
3. **task-4.4 토큰 이상치** — 초기 다중 세션이 동일 task_id로 기록되어 627M 토큰 집계. 이는 정상 동작이며, anomaly 명령으로 감지 가능

## CLI 사용법

```bash
python3 scripts/token-tracker.py scan        # 전체 스캔 → 원장 갱신
python3 scripts/token-tracker.py get --task task-930.1  # 특정 태스크
python3 scripts/token-tracker.py summary     # 요약 보고
python3 scripts/token-tracker.py anomaly     # 이상치 감지
python3 scripts/token-tracker.py enrich      # task-timers.json 연동
```

## 대시보드 API

- `GET /api/token-usage` — 전체 토큰 원장
- `GET /api/token-usage?task=task-930.1` — 특정 태스크
- `GET /api/token-anomaly` — 이상치 목록
- `GET /api/tasks` — 기존 응답에 token_usage 필드 자동 포함