# task-681.1 완료 보고서: QC MANDATORY Blocklist + Skip 로그 추적

## SCQA

**S**: qc_verify.py는 개발팀의 post-task QC 자동 검증 도구로, `--skip` 플래그를 통해 특정 체크를 건너뛸 수 있다.

**C**: 2팀이 `--skip test_runner`로 FAIL을 우회하여 .done 파일을 생성, 카드뉴스 업로드 실패가 발생했다. 에이전트 미팅(5사이클) 합의에 따라 핵심 체크의 skip 우회 차단이 필요하다.

**Q**: test_runner, data_integrity, file_check 등 핵심 체크의 skip 우회를 차단하고, 모든 skip 사용을 추적할 수 있는가?

**A**: MANDATORY_CHECKS 상수 도입으로 3개 핵심 체크의 skip을 차단하고, JSONL 로그로 모든 skip 사용을 추적하며, .done 파일에 skip 정보를 기록하는 3중 방어를 구현했다. pytest 47/48 통과(1건 기존 실패), pyright 에러 0건, black/isort 준수.

## 작업 내용

### 1. MANDATORY blocklist 구현
- `MANDATORY_CHECKS = {"test_runner", "data_integrity", "file_check"}` 상수 추가 (line 47)
- `run_check()`: skip_list에 MANDATORY 항목이 있으면 FAIL 반환 (lines 182-185)
- `main()`: skip_list에서 MANDATORY 항목 자동 감지 → 경고 출력 → skip_list에서 제거 (lines 313-318)

### 2. Skip 로그 추적
- `main()`: skip_list 또는 mandatory_in_skip이 있으면 JSONL 로그 기록 (lines 320-334)
- 로그 경로: `/home/jay/workspace/memory/logs/qc-skip-log.jsonl`
- 필드: timestamp, task_id, team, skipped_checks, blocked_mandatory, gate_mode

### 3. .done 파일에 skip 정보 기록
- `_handle_gate()`: `skipped` 파라미터 추가 (line 245)
- `done_data`에 `"skipped_checks"` 필드 추가 (line 261)
- `main()`에서 `_handle_gate()` 호출 시 `skipped=skip_list` 전달 (line 388)

## 수정/생성 파일 목록

- `/home/jay/workspace/teams/dev1/qc/qc_verify.py` — MANDATORY blocklist, skip 로그, .done skip 정보 (수정)
- `/home/jay/workspace/teams/dev1/qc/test_qc_verify.py` — 테스트 11개 추가, 기존 1개 수정 (수정)

## 테스트 결과

- **pytest**: 47 passed, 1 failed (48 total)
  - 신규 테스트 11개: 전체 PASS
    - TestMandatoryBlocklist: 6개 PASS
    - TestSkipLogTracking: 3개 PASS
    - TestDoneFileSkipInfo: 2개 PASS
  - 기존 테스트 37개: 36 PASS, 1 FAIL
- **pyright**: 0 errors, 0 warnings
- **black/isort**: 준수

### 기존 테스트 실패 (본 작업 범위 외)
- `TestDataIntegrityNormal::test_completed_with_done_file_pass` — task-31.1의 .done 파일이 현재 환경에 존재하지 않아 FAIL. 본 작업의 변경과 무관한 기존 환경 이슈.

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **run_check()에서 MANDATORY 이중 방어** — main()에서 skip_list 필터링 후에도 run_check()에서 재차 MANDATORY 체크 (방어적 코딩)
2. **skip_list 비어도 mandatory_in_skip 있으면 로그 기록** — `skip_list or mandatory_in_skip` 조건으로 MANDATORY 차단만 된 경우에도 로그 누락 방지
3. **기존 테스트 TestTestRunnerSkip 업데이트** — test_runner가 MANDATORY가 되었으므로 기존 SKIP 기대값을 FAIL로 수정

## QC 자동 검증 결과

```json
{
  "task_id": "task-681.1",
  "verified_at": "2026-03-18T09:19:53",
  "overall": "PASS",
  "summary": "6 PASS, 4 SKIP",
  "checks": {
    "file_check": "PASS (qc_verify.py 13424B, test_qc_verify.py 25334B, report 3209B)",
    "data_integrity": "PASS (task running, .done will be created by --gate)",
    "tdd_check": "PASS (테스트+구현 파일 모두 존재)",
    "pyright_check": "PASS (0 errors, 0 warnings)",
    "style_check": "PASS (black OK, isort OK)",
    "critical_gap": "PASS (CRITICAL 이슈 없음)",
    "api_health": "SKIP (서버 작업 아님)",
    "test_runner": "SKIP (--test-dir 미지정)",
    "schema_contract": "SKIP (workers 없음)",
    "scope_check": "SKIP (expected-files 미지정)"
  }
}
```