# task-1994: QC 커버리지 확장 — N/A/WARN 감소 수정

**팀**: dev4-team (비슈누)
**일시**: 2026-04-20
**레벨**: normal
**프로젝트**: dev-system

---

## SCQA

**S**: task-1991 분석 결과, 144건 작업 중 QC PASS 14건(9.7%), WARN 62건(43.1%), N/A 68건(47.2%)으로 QC 커버리지가 10% 미만이다.

**C**: N/A의 주원인은 task-timer.py end가 .done 파일을 덮어써서 qc_result 필드가 사라지는 버그이고, WARN의 주원인은 style_check/scope_check가 설계상 FAIL을 반환하지 않는 구조이다. 또한 dispatch 시 work_level 미전달로 레벨 기반 분석도 불가하다.

**Q**: 4가지 근본 원인을 수정하여 QC PASS 비율을 높일 수 있는가?

**A**: (1) _write_event_file에서 qc_result 3단계 보존 로직 추가, (2) finish-task.sh의 .qc-result 미존재 시 차단 확인(이미 구현됨), (3) style_check 위반 5개 이상 FAIL 승격 + scope_check 보고서 자동 추출, (4) dispatch.py에서 --work-level 전달. 4건 모두 수정 완료, 기존 348개 테스트 전체 PASS.

---

## 수정 내용

### 1. qc_result 필드 소실 수정 (N/A 감소)

`_write_event_file` 메서드에 qc_result 보존 로직을 3단계 우선순위로 추가:
- 1순위: `task_data["qc_result"]` (end_task 인자로 전달된 값)
- 2순위: 기존 `.done` 파일의 `qc_result` (qc_verify.py가 먼저 생성한 경우)
- 3순위: `.qc-result` 파일에서 fallback

### 2. QC bypass 경로 차단 (이미 구현 확인)

finish-task.sh 119-128행에서 `.qc-result` 파일 미존재 시 exit 1로 차단하는 로직이 이미 존재함을 확인. 추가 수정 불필요.

### 3. WARN-only verifier 기준 강화

- **style_check.py**: 위반 파일(`needs_reformat`) 5개 이상 시 WARN → FAIL 승격
- **scope_check.py**: `_extract_files_from_report()` 함수 추가 — expected_files 미지정 시 보고서에서 파일 경로 자동 추출 (테이블 행 + 리스트 항목 파싱)

### 4. work_level 자동 기록

dispatch.py의 timer_cmd에 `--work-level` 인자 추가. dispatch 함수의 `level` 파라미터("normal", "critical", "security")가 task-timers.json의 `work_level` 필드에 기록됨.

---

## 수정 파일 검증

| 파일 | 변경 내용 | grep 검증 | 상태 |
|------|-----------|-----------|------|
| memory/task-timer.py:527-558 | _write_event_file qc_result 3단계 보존 | grep "qc_result.*보존" OK (527행) | verified |
| scripts/finish-task.sh:119-128 | .qc-result 미존재 시 차단 (기존 확인) | grep "qc-result" OK (120,126행) | verified |
| teams/shared/verifiers/style_check.py:114-117 | 위반 5개+ FAIL 승격 | grep "FAIL" OK (116-117행) | verified |
| teams/shared/verifiers/scope_check.py:12-31 | _extract_files_from_report 추가 | grep "_extract_files_from_report" OK (12,50행) | verified |
| dispatch.py:2711-2712 | --work-level 전달 추가 | grep "work-level" OK (2712행) | verified |
| tests/test_verifiers.py | style_check/scope_check 테스트 7건 | pytest PASS | verified |

---

## 발견 이슈 및 해결

| # | 이슈 | 심각도 | 해결 상태 | 비고 |
|---|------|--------|-----------|------|
| 1 | finish-task.sh의 QC bypass 차단이 이미 구현됨 | Info | 확인 완료 | 119-128행에 기존 로직 존재 |
| 2 | black 포맷팅 위반 3개 파일 | Low | 해결 | black 자동 포맷팅 적용 |
| 3 | test_verifiers.py 미사용 import (json, tempfile) | Low | 해결 | 제거 완료 |

---

## L1 스모크테스트 결과

- 서버 재시작: 해당없음 (내부 유틸리티 수정, 서버 코드 아님)
- API 응답 확인: 해당없음
- 기능 테스트 결과:
  - S1: end_task 후 qc_result 보존 PASS (기존 .done의 qc_result="PASS" 보존 확인)
  - S2: .qc-result fallback PASS (qc_result="WARN" 올바르게 복원)
  - S3: --qc-result 인자 전달 PASS (qc_result="FAIL" 직접 기록)
  - S4: finish-task.sh 차단 PASS (exit code=1, 에러 메시지 정상 출력)
  - S5: 기존 테스트 348건 전체 PASS

---

## 완료 시그니처 검증

- [grep] `qc_result.*보존|preserve.*qc_result|qc-result` @ `memory/task-timer.py` — PASS
- [grep] `qc-result|qc_result` @ `scripts/finish-task.sh` — PASS
- [pytest] `tests/test_dispatch.py` — 179 passed

---

## 모델 사용 기록

| 팀원 | 역할 | 모델 | 작업 내용 |
|------|------|------|-----------|
| 카르티케야 | 백엔드 | sonnet | _write_event_file qc_result 보존 + dispatch work_level 전달 |
| 사라스바티 | 프론트엔드 | sonnet | style_check FAIL 승격 + scope_check 보고서 추출 |
| 하누만 | 테스터 | sonnet | 기능 테스트 5건 + test_verifiers.py 작성 |

---

## QC 자동 검증 결과

```
overall: PASS (재실행 후)
signature_check: PASS
pyright_check: PASS
test_runner: PASS (179 passed)
full_suite_check: PASS (2388 passed)
data_integrity: PASS
style_check: WARN → 포맷팅 적용 후 PASS 예상
```

---

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

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