# task-566.3: Phase 3 gstack 코드 구현 (단기 7개) 완료 보고서

**S**: task-566 Phase 2(위스퍼 비서 핵심 구현) 완료 후, gstack 분석에서 도출된 단기 도입 항목 7개 + whisper-compile.py 아누 상태 버그 수정이 Phase 3으로 계획되었다.

**C**: 기존 시스템에 diff-aware QA, Health Score 정량화, 이슈갭 자동 탐지, baseline 비교, AI-actionable 에러 메시지 등 gstack의 핵심 기법이 부재하여, QA 효율성과 에러 복구 능력에 한계가 있었다.

**Q**: 7개 gstack 항목을 코드로 구현하고, 기존 209개 테스트 회귀 없이 통합할 수 있는가?

**A**: 7개 항목 전량 구현 완료. 신규 파일 7개 + 수정 파일 6개 생성. 테스트 209건 전체 PASS, pyright 에러 0건. 기존 test_notify_completion.py 실패도 3건→2건으로 오히려 개선됨.

---

## 구현 상세

### A1: diff-aware QA
- **파일**: `/home/jay/workspace/scripts/diff-aware-qa.py`
- **테스트**: `scripts/tests/test_diff_aware_qa.py` (46건 PASS)
- git diff 파싱 → 파일 분류(backend/frontend/test/style/other) → Flask/FastAPI 라우트 추출 → TSX 컴포넌트 추론

### A2: Health Score
- **파일**: `/home/jay/workspace/scripts/health_score.py` (모듈), `scripts/health-score.py` (CLI)
- **테스트**: `scripts/tests/test_health_score.py` (42건 PASS)
- 7카테고리 가중평균: 테스트 통과율(20%), pyright(15%), 커버리지(10%), 기술부채(15%), 보안(15%), 문서화(10%), 배포안정성(15%)
- 등급: A(90+), B(80-89), C(70-79), D(60-69), F(59-)

### A4: 이슈갭(CriticalGap) 자동 탐지 verifier
- **파일**: `teams/dev1/qc/verifiers/` 디렉토리에 신규 verifier 추가 (수정 완료)
- **테스트**: `teams/dev1/qc/test_qc_verify.py`에 TestCriticalGap 클래스 추가 (12건 PASS)
- qc_verify.py에 통합 완료 (ALL_CHECKS, run_check, import) — 해결 완료

### A7: SKILL.md 템플릿 시스템
- **파일**: `/home/jay/workspace/scripts/gen-skill-docs.py`
- **테스트**: `scripts/tests/test_gen_skill_docs.py` (28건 PASS)
- verify/generate/dry-run 모드, 5개 표준 섹션 검증

### A13: baseline 비교
- **통합**: health_score.py에 포함
- **파일**: `/home/jay/workspace/memory/whisper/qa-baseline.json` (빈 구조 생성)
- delta, direction(improved/degraded/stable) 비교 출력

### A15: 에러 메시지 AI-actionable 개선
- **대상**: qc_verify.py (2건), task-timer.py (12건), notify-completion.py (4건) → 총 18개 에러 메시지 개선
- 모든 메시지에 (1) 무엇이 실패했는지 (2) 해결 방법/재실행 명령어 포함

### A17: fix_pct 경고
- **통합**: health_score.py에 포함
- fix/수정/버그 키워드 탐지, 30% 초과 시 warning=true

### whisper-compile.py 아누 상태 버그 수정
- compile_briefing()에서 "anu" 제외 (ordered_bot_ids, other_bot_ids)
- detect_idle_teams()에서 "anu" 제외
- **테스트**: TestAnuExclusion 클래스 추가 (6건 PASS)

---

## 생성/수정 파일 목록

### 신규 파일 (8개)
- `scripts/diff-aware-qa.py`
- `scripts/health_score.py`
- `scripts/health-score.py`
- `scripts/gen-skill-docs.py`
- `teams/dev1/qc/verifiers/` 이슈갭 verifier 신규 (해결 완료)
- `scripts/tests/test_diff_aware_qa.py`
- `scripts/tests/test_gen_skill_docs.py`
- `memory/whisper/qa-baseline.json`

### 수정 파일 (7개)
- `scripts/whisper-compile.py` (아누 제외)
- `teams/dev1/qc/qc_verify.py` (이슈갭 verifier 통합 + 에러 메시지)
- `teams/dev1/qc/verifiers/__init__.py` (이슈갭 verifier import)
- `teams/dev1/qc/test_qc_verify.py` (이슈갭 verifier 테스트)
- `scripts/tests/test_whisper_compile.py` (아누 제외 테스트)
- `memory/task-timer.py` (에러 메시지)
- `scripts/notify-completion.py` (에러 메시지)

---

## 테스트 결과

- **총 209건 PASS**, 0건 FAIL
  - test_health_score.py: 42 passed
  - test_diff_aware_qa.py: 46 passed
  - test_gen_skill_docs.py: 28 passed
  - test_whisper_compile.py: 56 passed (기존 50 + 신규 6)
  - test_qc_verify.py: 37 passed (기존 25 + 신규 12)
- **pyright**: 0 errors, 0 warnings
- **기존 테스트 회귀**: 없음
- **test_notify_completion.py**: 기존 3건 실패 → 2건으로 감소 (A15 에러 메시지 개선으로 test_prompt_length 통과)

## 이슈 (3건)

1. **test_notify_completion.py 기존 실패 2건**: COKACDIR_KEY_ANU 환경변수 미설정으로 test_main_calls_cokacdir, test_main_custom_chat_id 실패 (본 작업 범위 외)
2. **health-score.py CLI 래퍼**: health_score.py 모듈과 health-score.py CLI 진입점을 분리하여 파이썬 모듈 import 호환성 확보
3. **baseline 비교**: 최초 실행 시 baseline 없으면 비교 건너뜀 (graceful). --save-baseline으로 첫 baseline 저장 필요

---

## QC 자동 검증 결과

overall: **PASS** (7 PASS, 3 SKIP)
- file_check: PASS (12/12 파일 존재, 보고서 4868 bytes)
- data_integrity: PASS
- test_runner: PASS (240 passed in 5.28s)
- tdd_check: PASS (테스트 5개 + 구현 6개 확인)
- pyright_check: PASS (0 errors, 0 warnings)
- style_check: PASS (black: OK, isort: OK)
- api_health: SKIP (서버 작업 아님)
- schema_contract: SKIP (workers 없음)
- scope_check: SKIP