# QC 규칙 확장 (QC-RULES-EXTENDED)

> 이 파일은 critical/security 레벨 또는 workers/ 변경 시 읽으세요.
> 기본 QC 규칙은 QC-RULES.md를 참조하세요.

---

## 1-B. 데이터 계약 체크리스트 (아래 조건 해당 시 추가 적용)

**적용 조건** (해당 경로의 파일이 이번 변경에 포함된 경우):
- `workers/` 하위 파일 변경
- `src/types/`, `src/services/` 하위 파일 변경
- `shared/schemas/` 하위 파일 변경

위 조건 중 하나라도 해당하면:
- [ ] 6-1. `shared/schemas/{name}.schema.json`이 Pydantic 모델과 동기화되어 있는가?
         (미동기화 시: `make export-schema` 실행)
- [ ] 6-2. `shared/schemas/{name}.sample.normal.json`이 Worker 실제 출력 기반으로 최신 상태인가?
- [ ] 6-3. Python 계약 테스트 재실행: `pytest workers/{name}/tests/test_contract.py`
- [ ] 6-4. TypeScript 계약 테스트 재실행: `vitest run tests/integration/`
- [ ] 6-5. camelCase ↔ snake_case 변환이 Zod transform에 반영되어 있는가?

**중요**: "해당 없음"은 위 조건에 해당하는 파일이 이번 변경에 없을 때만 허용.
         `workers/` 파일 변경 시 이 체크리스트를 우회하는 것은 계약 위반입니다.

---

## 1.5. 인터페이스 계약 관리 (참조 사항)

### 계약 파일 위치 및 소유권

| 파일 | 역할 | 생성 방법 | 소유자 |
|------|------|-----------|--------|
| `shared/schemas/{name}.schema.json` | 언어 독립적 계약 정의 (파생 아티팩트) | `make export-schema` 자동 생성 | 마아트 (QC) |
| `shared/schemas/{name}.sample.normal.json` | 정상 케이스 Worker 출력 샘플 | Worker 실제 실행 결과 | 토르 (Worker 담당) |
| `shared/schemas/{name}.sample.edge.json` | 엣지 케이스 샘플 | 수동 작성 | 헤임달 (테스터) |
| `workers/{name}/models.py` | Pydantic 출력 모델 (진정한 SSoT) | 수동 작성 (필수) | 해당 Worker 개발자 |
| `shared/schemas/{name}.schema.ts` | Zod 스키마 + camelCase transform | schema.json 기반 수동 작성 | 프레이야 (Frontend) |

### 기술 표준

- Python Worker 스키마: **Pydantic v2** (`model_json_schema()` 사용. `schema()` 사용 금지)
- TypeScript Frontend 스키마: **Zod** (`safeParse` 사용, `as` 타입 단언 사용 금지)
- 공유 계약 파일: **JSON Schema** (`.schema.json`)
- Python 계약 검증 라이브러리: **jsonschema**
- camelCase 변환 책임: **Zod transform 레이어** (humps 등 별도 라이브러리 사용 금지)

### Worker 추가 시 의무 사항

새 Worker `{name}`을 추가할 때 반드시 생성해야 하는 파일 (누락 시 schema_contract.py verifier FAIL):
1. `workers/{name}/models.py` — Pydantic 출력 모델 (BaseWorker 상속 시 강제됨)
2. `workers/{name}/tests/test_contract.py` — Python 계약 테스트
3. `shared/schemas/{name}.schema.json` — `make export-schema`로 생성
4. `shared/schemas/{name}.sample.normal.json` — 정상 케이스 샘플
5. `shared/schemas/{name}.sample.edge.json` — 엣지 케이스 샘플
6. `shared/schemas/{name}.schema.ts` — Zod 스키마

---

## 3. 마아트 독립 검증 (critical 이상)

자동 검증 완료 후 Task tool로 마아트(QC 매니저) 역할 서브에이전트를 소집하여 독립 재검증을 수행하세요:
- subagent_type=general-purpose로 Task tool 호출
- 마아트에게 전달할 정보 (컨텍스트 격리 원칙):
  - 작업 명세 파일 경로 (개발 과정 설명 금지)
  - qc_verify.py 실행 명령: `python3 /home/jay/workspace/teams/dev1/qc/qc_verify.py --task-id <TASK_ID>`
  - 생성/수정된 파일 경로 목록
- 마아트에게 전달하지 않을 것:
  - 개발 결정 이유나 수정 히스토리
  - 팀장의 셀프 QC 결론
- 마아트 역할 지시:
  "당신은 마아트(QC 매니저)입니다. 개발자 보고를 절대 신뢰하지 않습니다.
  1. qc_verify.py를 직접 실행하세요: python3 /home/jay/workspace/teams/dev1/qc/qc_verify.py --task-id <TASK_ID>
  2. 작업 명세 파일을 직접 읽고 결과물과 대조하세요.
  3. 테스트가 있으면 직접 재실행하세요.
  4. 서버 작업이면 curl로 API 응답을 직접 확인하세요.
  5. FAIL 항목이 있으면 구체적 불일치와 재작업 요청을 기록하세요.
  6. 개발팀의 설명이나 맥락에 의존하지 말고, 코드와 실행 결과만으로 판단하세요.
  7. [v2.0] 데이터 모델 변경이 포함된 경우:
     - pytest workers/{name}/tests/test_contract.py 직접 재실행
     - vitest run tests/integration/ 직접 재실행
     - shared/schemas/ 파일 변경 이력 검토 (CODEOWNERS 리뷰)
     - schema_contract verifier의 WARN 항목 직접 확인"
- 마아트 검증 결과를 최종 보고서에 포함하세요.

---

## 4. 로키 보안 감사 (security 레벨만)

마아트 검증 완료 후 Task tool로 로키(레드팀 리더) 역할 서브에이전트를 소집하여 보안 감사를 수행하세요:
- subagent_type=general-purpose로 Task tool 호출
- 로키 역할 지시: "당신은 로키(레드팀 리더)입니다. 아래 작업 결과물을 공격자 관점에서 보안 감사하세요."
- 로키가 수행할 보안 점검 항목:
  - OWASP Top 10 체크
  - 입력값 검증 확인
  - 인증/권한 처리 확인
  - 민감 정보 노출 점검
  - **[v2.0]** `shared/schemas/*.schema.json` 무결성 해시 확인 (스키마 파일의 무단 변경 가능성 배제)
  - **[v2.0]** 인증/인가 로직 변경 여부 확인
  - **[v2.0]** 민감 데이터 로깅/노출 가능성 검토
  - **[v2.0]** 의존성 패키지 취약점 스캔
- 로키 보안 감사 결과를 최종 보고서에 포함하세요.