# task-688.1 완료 보고서: QC test_runner --skip 우회 방지 코딩화

## SCQA

**S**: QC 검증(qc_verify.py)의 test_runner가 전체 `tests/` 디렉토리를 대상으로 실행되어, 본인 작업과 무관한 기존 실패에 걸리는 구조였다.

**C**: 이로 인해 봇들이 `--skip test_runner`로 QC를 우회하는 원칙 위반이 반복 발생했다. 기존 코드는 test_runner를 MANDATORY로 차단했지만, 근본 원인(불필요한 전체 테스트 실행)은 미해결.

**Q**: `--check-files` 기반 테스트 자동 추론으로 우회 필요성을 제거하고, 불가피한 skip 시 추적 가능한 MANUAL_SKIP 체계를 도입할 수 있는가?

**A**: `_infer_test_files()` 자동 추론 함수를 도입하여 관련 테스트만 실행하도록 개선했다. `--skip test_runner` 시 MANUAL_SKIP 상태로 기록 + WARN 로그를 강제 출력한다. 신규 테스트 22건 전체 통과, pyright 에러 0건.

## 변경 파일 목록

- `/home/jay/workspace/teams/dev1/qc/qc_verify.py` — 수정 (자동 추론 + MANUAL_SKIP)
- `/home/jay/workspace/teams/dev1/qc/verifiers/test_runner.py` — 수정 (test_files 파라미터 추가)
- `/home/jay/workspace/teams/shared/QC-RULES.md` — 수정 (v3.3 규칙 추가)
- `/home/jay/workspace/tests/test_qc_verify.py` — 신규 생성 (22개 테스트)

## 구현 상세

### 1. qc_verify.py: `--check-files` 기반 테스트 자동 추론
- `_infer_test_files(check_files)` 함수 신설
- 추론 패턴 3가지: workspace_root/tests/, 동일 디렉토리/tests/, 부모 디렉토리/tests/
- 추론된 테스트 파일이 0개면 정당한 SKIP 처리

### 2. `--skip test_runner` MANUAL_SKIP 체계
- `test_runner`를 MANDATORY_CHECKS에서 제거
- skip 시 MANUAL_SKIP 상태 반환 + stderr WARN 로그 강제
- `_summarize()`/`_determine_overall()`에 MANUAL_SKIP 상태 반영 (overall → WARN)

### 3. `--test-dir` 경고
- test_dir 사용 시 stderr에 WARN 출력: "가능하면 --check-files 기반 자동 추론을 사용하세요"

### 4. test_runner.py: test_files 파라미터
- `verify(test_dir, test_files, timeout)` — test_files 우선 처리
- 존재하는 파일만 필터링 후 pytest에 개별 전달

### 5. QC-RULES.md v3.3
- Section 2에 "test_runner 대상 범위 규칙" 추가
- 변경 이력 테이블에 v3.3 항목 추가

## 테스트 결과

- `tests/test_qc_verify.py`: **22/22 PASS** (1.25s)
- pyright: **0 errors, 0 warnings**
- black/isort: 적용 완료

### 테스트 커버리지 (요구사항 4건)
1. `--check-files utils/env_loader.py` → 자동 추론 확인: PASS (TestInferTestFilesFound 3건)
2. `--check-files nonexistent.py` → 정당한 SKIP: PASS (TestRunCheckTestRunnerAutoInferNoFiles 2건)
3. `--skip test_runner` → MANUAL_SKIP + WARN: PASS (TestRunCheckTestRunnerManualSkip 2건)
4. `--test-dir` 호환성 유지: PASS (TestRunCheckTestRunnerWithTestDirWarns 1건)

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **test_runner.verify() 시그니처 하위호환** — test_dir 기본값을 "" 유지, test_files 기본값 None으로 기존 호출 불변
2. **MANUAL_SKIP 상태가 _summarize에 미반영** — counts dict에 MANUAL_SKIP 키 추가
3. **main()의 MANDATORY 차단 메시지가 test_runner 포함** — 메시지 텍스트에서 test_runner 제거

### 범위 외 미해결 (1건)
1. **기존 테스트 1건 실패** (dev1/qc/test_qc_verify.py::test_data_integrity_pass) — task-31.1 .done 파일 부재. 범위 외 사유: 이전 작업의 환경 잔여물.

## QC 검증 결과

- **Overall**: PASS (7 PASS, 3 SKIP)
- test_runner: PASS — `--check-files` 자동 추론으로 `tests/test_qc_verify.py` 발견, 22 passed in 1.23s
- file_check: PASS — 5/5 checks
- data_integrity: PASS
- tdd_check: PASS — 테스트+구현 파일 모두 존재
- pyright_check: PASS — 0 errors, 0 warnings
- style_check: PASS — black/isort OK
- critical_gap: PASS
- api_health: SKIP (서버 작업 아님)
- schema_contract: SKIP (workers 없음)
- scope_check: SKIP (expected-files 미지정)