# 게이트 시스템(G1/G2/G3) 일상 운영 매뉴얼
> 버전: 1.0 | 작성일: 2026-04-17 | 대상: 아누(개발실장) + 팀장

---

## 1. 게이트 시스템 개요

보리스 게이트 시스템은 3개 검증 관문(G1 설계 → G2 구현 → G3 머지)으로 구성.
레벨(Lv.0~4)에 따라 검증 깊이만 조절. 게이트 구조 자체는 불변.

| 관문 | 단계 | 목적 |
|------|------|------|
| G1 | 설계 진입 전 | 작업 범위·충돌·보안 사전 검증 |
| G2 | 구현 완료 후 | 기능·품질·보안 검증 |
| G3 | 머지 전 | 독립 검증 + 최종 충돌 분석 후 머지 |

---

## 2. 레벨별 게이트 동작 요약

### Lv.0-1 (단순 수정/설정 변경)

| 관문 | 동작 |
|------|------|
| G1 | 스킵 — task 파일만으로 구현 진입 |
| G2 | 팀 내 셀프 QC (구문 에러, 기본 기능 확인) |
| G3 | 즉시 머지 (`worktree_manager finish --action keep`) |

- auto-commit이 변경사항 자동 보존

---

### Lv.2 (일반 코딩)

| 관문 | 동작 |
|------|------|
| G1 | `affected_files` 필드 필수 / `dispatch.py` 겹침 자동 감지 |
| G2 | 마아트(QC) 또는 팀 테스터 기능 테스트 |
| G3 | `worktree_manager finish --action pr` → Gemini 리뷰 |

- 기계적 충돌 감지 시 집중 리뷰 수행

---

### Lv.3 (복잡한 기능/리팩토링)

| 관문 | 동작 |
|------|------|
| G1 | 3문서 필수 + Codex 사전 검증 PASS + `affected_files` 교차 분석 + sanitize 게이트 |
| G2 | Gemini PR 리뷰 + 마아트 독립 검증 (둘 다 PASS 필요) |
| G3 | `g3_independent_verifier.py` PASS + `worktree finish --action pr` → Gemini + 시맨틱 충돌 분석 → High 0건 시 자동 머지 |

---

### Lv.4 (보안/핵심 인프라)

| 관문 | 동작 |
|------|------|
| G1 | Lv.3 조건 전부 + Agent 미팅 만장일치 + 로키 DA 필수 참여 |
| G2 | Gemini PR 리뷰 + 로키 레드팀 보안 감사 |
| G3 | Lv.3 조건 전부 + 보안 감사 PASS 필수 |

---

## 3. 일상 운영 체크리스트

### 작업 시작 시 (dispatch)

1. `dispatch.py --level N` 으로 레벨 지정
2. Lv.2+: `affected_files` 겹침 경고 확인
3. Lv.3+: 3문서 디렉토리 자동 생성 확인

### 작업 진행 중

1. 팀원 마이크로커밋 확인 (`git log --oneline -5`)
2. Edit 후 grep 검증 확인 지시
3. Lv.2+: TDD 순서 준수 확인 (RED → GREEN → REFACTOR)

### 작업 완료 시

1. L1 스모크테스트 확인 (API curl / Playwright 스크린샷)
2. `qc_verify.py --gate --task-id {task_id}` 실행
3. Lv.3+: `g3_independent_verifier.py` 실행
4. `.done` 이벤트 파일 생성 (`qc_verify.py --gate`가 자동 처리)
5. 보고서 저장 (`memory/reports/{task_id}.md`)

---

## 4. 장애 시 대응

### Codex 장애

- **증상**: `codex_gate_check.py` 타임아웃 또는 API 에러
- **대응**: Codex 검증 스킵, 보고서에 "Codex 장애로 G1 스킵" 명시
- **후속**: Codex 복구 후 수동 재검증 여부 아누 판단

---

### Gemini 타임아웃

- **증상**: PR 생성 후 5분 내 Gemini 리뷰 없음
- **대응**: 리뷰 없이 머지 진행 (`DIRECT-WORKFLOW.md` Step 4.7 참조)
- **후속**: 보고서에 "Gemini 리뷰 타임아웃" 기록

---

### 마아트 QC 폴백

- **증상**: 마아트(QC) 서브에이전트 소환 실패
- **대응**: 팀장이 셀프 QC 강화 (1-A 체크리스트 전체 수행)
- **후속**: 보고서에 "마아트 폴백, 셀프 QC 수행" 기록

---

### qc_verify.py 3회 FAIL (에스컬레이션)

- **증상**: `retry_count ≥ 3`, ESCALATE 상태
- **대응**: `.done` 차단됨. 아누에게 에스컬레이션 보고
- **후속**: 아누가 수동 해결 또는 `retry_count` 초기화

---

### 겹침 경고 (affected_files 충돌)

- **증상**: `dispatch.py`가 두 작업의 `affected_files` 겹침 감지
- **대응**: 두 번째 작업 보류, 첫 번째 작업 `.done` 대기
- **후속**: 첫 번째 완료 후 재dispatch

---

## 5. 정기 점검 사항

### 주간 점검

- [ ] QC FAIL 항목 리뷰: `memory/events/*.retry_count` 확인
- [ ] MEDIUM 분류 리뷰: Gemini가 MEDIUM으로 분류한 코멘트 누적 확인
- [ ] 효과 지표 수집: `python3 scripts/collect_metrics.py --date {date}` 실행
- [ ] 미머지 worktree 확인: `git worktree list` → 1주 이상 방치된 worktree 정리

### 월간 점검

- [ ] 아누 가이드 버전 확인: 신규 시스템 변경 반영 여부
- [ ] `QC-RULES.md` Suppression 목록 검토
- [ ] systemd auto-merge.timer 상태 확인: `systemctl --user status auto-merge.timer`
- [ ] 게이트 효과 ROI 분석: `collect_metrics.py` 월간 데이터 비교

---

## 6. 관련 파일 참조

| 용도 | 경로 |
|------|------|
| 게이트 지시 | `prompts/gate_instructions.py` |
| Codex 검증 | `scripts/codex_gate_check.py` |
| PII 마스킹 | `utils/sanitize_gate.py` |
| 자동 머지 | `scripts/auto_merge.py` |
| G3 독립 검증 | `scripts/g3_independent_verifier.py` |
| QC 규칙 | `teams/shared/QC-RULES.md` |
| 효과 지표 | `memory/specs/metrics-framework.md` |
| 수집 스크립트 | `scripts/collect_metrics.py` |
| Phase 게이트 템플릿 | `memory/specs/phase-gate-checklist.md` |
| 아누 가이드 | `memory/specs/anu-guide.md` |