---
task_id: task-1837
type: plan
scope: system
project: cross-verification-workflow
created: 2026-04-15
updated: 2026-04-20
status: approved
---

# 교차검증 풀스택 워크플로우 — 계획서 (Plan)

> 프로젝트: 교차검증 풀스택 워크플로우 도입 + server.py 모듈 분할
> 작성일: 2026-04-15
> 근거: Agent 미팅 5사이클 합의 + 3인 병렬 심층 분석 (아누/비너스/아틀라스)
> 문서 버전: v1.1 (2026-04-16 검증 게이트 + MEDIUM 기준 추가)

---

## 0. 배경 및 동기

### 0.1 문제 정의
2026-04-15 대시보드 작업에서 반복 발생한 문제:
- **worktree 머지 충돌**: 8팀 병렬 작업 시 같은 파일(server.py 7600줄)을 동시 수정하여 머지 충돌 빈발
- **커밋 누락**: 코드 수정 후 커밋하지 않은 상태에서 다른 팀의 worktree 머지로 변경사항 덮어쓰임
- **기능 원복**: H1/H2 드롭다운, 정제 UI, 히스토리 삭제 등이 5회 이상 원복됨
- **검증 부재**: 구현 후 검증 없이 머지하여 사일런트 리그레션 발생

### 0.2 목표
1. 레벨별 차등 검증 체계(보리스 게이트 시스템) 도입으로 품질과 속도의 균형 달성
2. server.py 7600줄 모놀리스를 9개 모듈로 분할하여 머지 충돌 근본 해결
3. 외부 AI(Gemini/Codex) 교차검증으로 인지 편향 구조적 차단
4. 기존 시스템(보리스 워크플로우, 3문서, 핵미사일 발사코드, worktree, auto-commit)과 완전 호환

### 0.3 미팅 참여 페르소나
다빈치(천재적사고), 로키(레드팀/DA), 야누스(양면분석), 헤르메스(개발1팀), 비너스(Gemini/디자인센터), 아틀라스(Codex센터), 프로메테우스(혁신전략), 불칸(인프라/성능), 이리스(커뮤니케이션/UX)

---

## 1. 보리스 게이트 시스템 (Boris Gate System)

### 1.1 설계 원리
기존 보리스 워크플로우(Annotation Cycle)의 상위에 3개 게이트를 오버레이한다.
단계를 직렬로 나열하지 않고, 3개 게이트(설계검증 → 구현검증 → 머지검증)로 묶어 각 게이트의 검증 깊이만 레벨에 따라 조절한다.

**핵심 원칙:**
- G1은 "만드는 지능"(Codex/설계팀) — 사전 검증
- G2는 "검증하는 지능"(Gemini/마아트/로키) — 구현 후 검증
- G3는 기계적 검증(자동화) — 머지 안전성 확보
- 기존 보리스 워크플로우 + 3문서 + 핵미사일 발사코드와 완전 호환

### 1.2 게이트별 레벨 매트릭스

#### G1 설계 게이트 (Gate 1: Design Verification)

**Lv.0-1 (스킵)**:
- G1 게이트 통과 조건 없음
- task 파일 작성만으로 바로 구현 진입

**Lv.2 (affected_files 확인)**:
- task 파일에 `affected_files` 필드 필수 기재
- dispatch.py가 자동으로 affected_files 겹침 감지
- 겹침 발견 시 → 아누에게 경고 (동시 수정 위험)

**Lv.3 (Codex 사전 검증)**:
- 3문서 필수 (리서치 → 미팅 → 3문서 → 핵미사일 → 코딩)
- Codex CLI로 설계 문서 + affected_files + 기존 코드 교차 분석
- Codex 검증 프로토콜: 입력(설계문서 + affected_files + 기존 코드) → 출력(JSON: `{pass: bool, risks: [], suggestions: []}`) → 판정(severity:critical 0개이면 PASS)
- FAIL 시 → 설계 재검토 → 재미팅

**Lv.4 (Codex + Agent 미팅 만장일치)**:
- 3문서 필수 + Agent 미팅 만장일치 합의 도달
- Codex 사전 검증 PASS 후
- 미팅 페르소나 전원 동의 확인 (로키 DA 포함 필수)
- 핵미사일 발사코드 통과 후 코딩 시작

#### G2 구현 게이트 (Gate 2: Implementation Verification)

**Lv.0-1 (경량 QC)**:
- 팀 내 셀프 QC (구문 에러, 기본 기능 확인)
- auto-commit이 변경사항을 자동 보존

**Lv.2 (팀 테스터)**:
- 마아트(QC) 또는 팀 테스터가 기능 테스트
- 기존 QC 프로세스 그대로 적용

**Lv.3 (Gemini + 마아트)**:
- Gemini GitHub App PR 자동 리뷰 (코드 패턴, 구문, 보안)
- 마아트(QC) 독립 검증 (도메인 로직, 비즈니스 규칙)
- Gemini 리뷰 판정 프로세스 (아래 2.5절) 적용 후 PASS 필요

**Lv.4 (Gemini + 로키 레드팀)**:
- Gemini PR 리뷰 + 마아트 QC
- 로키 레드팀 투입 (보안 취약점 탐지, 적대적 테스트)
- Gemini 리뷰 판정 프로세스 (아래 2.5절) 적용 후 PASS 필요

#### G3 머지 게이트 (Gate 3: Merge Verification)

**Lv.0-1 (즉시 머지)**:
- worktree finish 시 자동 머지
- `git merge main --no-edit` 강제 (기 구현됨)

**Lv.2 (main 최신화 후 머지)**:
- 머지 전 반드시 main 최신화
- 충돌 발생 시 수동 해결 후 머지

**Lv.3 (충돌 감지 시 Gemini 집중 리뷰)**:
- main 최신화 후 충돌 감지
- 충돌 파일에 대해 Gemini 집중 코드 리뷰
- 시맨틱 충돌(코드 구조 변경, 의미 변화) 분석

**Lv.4 (전팀 완료 대기 + 통합 테스트)**:
- Graduated Auto-Gate 3-Layer 적용 (아래 섹션 4 참조)
- 전팀 .done 수집 → Pre-flight 충돌 검증 → 통합 테스트
- TTL 2시간 초과 시 Telegram 경고 → 아누 판단

---

## 1.4 3문서 2유형 체계 (2026-04-16 미팅 합의)

> 미팅 기록: `memory/meetings/2026-04-16-3docs-two-types.md`

### 시스템 3문서
- 전체 아키텍처/프로세스 정의 (예: 교차검증 워크플로우)
- 경로: `memory/plans/<프로젝트명>/`
- 변경 빈도 낮음, 장기 참조 문서

### 작업 3문서
- Lv.3+ 개별 작업마다 생성
- 경로: `memory/plans/tasks/{task_id}/`
- YAML: `scope: task` 필수
- 완료 시 아카이브: `memory/plans/tasks/archived/{task_id}/`

### 코드 실행단 (12개 파일, ~327 라인)

**dispatch.py** (+45줄): `_create_task_docs(task_id, level)` 함수
- level >= 3일 때 `memory/plans/tasks/{task_id}/` 자동 생성
- 템플릿 배치 + YAML frontmatter 자동 채움
- 보안: task_id 정규식 + path traversal 방어

**team_prompts.py** (+20줄): "## 작업 3문서" 섹션 삽입 (Lv.3+)

**DIRECT-WORKFLOW.md** (+12줄): Step 2.3 "작업 3문서 초기화"

**three_docs_check verifier** (~80줄 신규):
- FAIL 5조건: 파일 미존재, YAML 누락, type 오류, checklist 미완료, 0바이트
- WARN 3조건: draft 상태, 30일+ 미갱신, task_id 불일치

**verification-before-completion** (+25줄): 디렉토리/파일/checklist/YAML 검증

**nuclear-approval** (+10줄): scope:task 경로 + checklist [x] + status=done

**템플릿** (3파일 신규): `prompts/templates/task-docs/`

---

## 1.5 한정승인과 게이트 시스템 상호작용

> 맥락노트/체크리스트에 이미 정의. 계획서에 명시.

**"나→아누 한정승인"**: 아누가 게이트 통과 주체. Phase별로 아누가 G1/G2/G3 판정.
**"X팀 한정승인"**: 팀장이 게이트 통과 주체. 팀장이 자체적으로 G1/G2/G3 판정.

한정승인 작업의 게이트 레벨: 위임 시 지정된 `--level`에 따라 차등 적용.

---

## 1.6 검증 게이트 (Verification-Before-Completion)

> 2026-04-16 Agent 미팅 4사이클 전원합의 (9/9)
> 근거: 보고서 "완료" ≠ 실제 코드 반영 문제 반복 발생 (task-1841: 7/8 FAIL, task-1828: 3/4 FAIL)

### 핵심 원칙
**"정상동작" = 사람이 사용할 때도 문제없이 기능이 동작하는 것.**
코드에 에러 없고 pytest 통과해도, 실제 UI에서 안 되면 미완료.

#### 코드 검증 ≠ 정상동작 (실패 사례, 2026-04-15)
- 신호등: grep으로 코드 존재 확인 ✅ → 서버 미재시작 → **대시보드에서 안 보임** ❌
- borrowed_tasks: grep으로 존재 확인 ✅ → API 호출 → **필드 없음** ❌ (서버 미재시작)
- 정제: 코드 반영 ✅ → 실제 정제 실행 → **2947개 전체 스레드 처리** ❌ (월 필터링 미동작)

#### 스모크테스트 정의
**스모크테스트 = 실제 UI에서 해당 기능을 사람처럼 사용하여 동작 확인.**
- 대시보드 기능: 브라우저에서 해당 탭/버튼 클릭 → 기대 결과 확인
- API 기능: curl로 실제 엔드포인트 호출 → 응답 확인
- 백그라운드 프로세스: 실제 실행 → 결과 파일/로그 확인
- **서버 재시작 필수**: 코드 수정 후 반드시 서버 재시작 → 반영 확인

### L1 자가 검증 (전 레벨 필수, .done 생성 전)

| 항목 | 전 레벨 | Lv.3+ |
|------|---------|-------|
| pytest 통과 | 필수 | 필수 |
| linter/type-check | 필수 | 필수 |
| **스모크테스트** (아래 정의 참조) | 필수 | 필수 |
| 서버 재시작 후 반영 확인 | 필수 | 필수 |
| Codex 사전 스캔 | - | 필수 |
| 프론트: 스크린샷 첨부 또는 Playwright E2E | 해당 시 | 해당 시 |

### L2 독립 검증 (Lv.2+, .done 후)

| 레벨 | 검증 방식 |
|------|---------|
| Lv.2 | 피어리뷰 (다른 팀 코드 확인) OR 마아트 spot check |
| Lv.3+ | 마아트 전수 검증 + Gemini PR 리뷰 |

역할 분리: Gemini = 스타일/보안/성능, 마아트 = 로직 정확성

### 체크박스 기준
- `[x]` = **L1+L2 검증 통과** (코드 작성 완료가 아님)

### 재작업 안전장치
- 재작업 시 L1 재수행 의무
- 재시도 상한 3회
- 3회 초과 시 아누 에스컬레이션 (제이회장님 판단)

### 기대효과 목표 (2026-04-16 미팅 합의)
- 3개월 후 리뷰 시간 **50% 단축** (현재 수동 검토 대비)
- MEDIUM 자동 분류 정확도 **85%+**
- 보고서 "완료" ≠ 실제 미반영 사례 **0건** 목표

---

## 2. 3 Step Why × Cross-Verification

### 2.1 설계
기존 "3 Step Why" 품질 검증에 교차 모델 검증을 매핑:

- **1st Why (구현팀 자문)**: "왜 이 구현이 맞는가?" → 답변 A
  - 구현팀이 자신의 코드에 대해 논리적 근거 제시
  - G2 통과 후 수행

- **2nd Why (교차 모델 검증)**: "왜 A가 최선인가?" → Gemini/Codex가 답변 B
  - 다른 AI 엔진이 독립적으로 구현의 최적성을 검증
  - 모델 다양성으로 인지 편향 구조적 차단 시도

- **3rd Why (적대적 검증)**: "왜 B가 최선인가?" → 로키(DA)가 답변 C
  - Devil's Advocate 관점에서 최선이 아닌 이유를 적극 탐색
  - A-B-C 일관성이 확보되면 검증 통과

### 2.2 적용 범위
- Lv.0-2: 3 Step Why 불필요 (팀 내 셀프 QC 또는 마아트 QC로 충분)
- Lv.3: 1st Why + 2nd Why 적용
- Lv.4: 1st Why + 2nd Why + 3rd Why 전체 적용

### 2.3 3인 분석 주의사항 (비너스)
> "Claude/Gemini/GPT 모두 동일한 학습 데이터 편향을 상당 부분 공유한다. 진정한 교차검증은 AI 간이 아닌, AI-인간(제이회장님) 간에서 발생한다. 3 Step Why의 3rd Why를 로키(DA)가 담당하는 것은 결국 같은 Claude 엔진이므로 '모델 다양성'이라는 논거가 약해진다."

→ 이 한계를 인지하고, 핵미사일 발사코드(제이회장님 최종 승인)가 AI 간 교차검증의 상위 게이트로 기능함을 명시.

### 2.5 Gemini PR 리뷰 판정 프로세스

Gemini Code Assist가 PR에 코드 리뷰를 달면, 아누가 각 코멘트를 **수용/기각/보류** 3단계로 판정한다.

#### PASS 기준
- **미수정 High 0건**이면 PASS (기각된 High는 카운트하지 않음)
- **MEDIUM은 3분류 기준에 따라 자동 판정** (2026-04-16 Agent 미팅 9/9 전원합의)
- 기각 시 반드시 **기각 사유**를 PR 코멘트로 기록 (히스토리 보존)

#### HIGH 판정
- **자동 수정 필수** — 봇이 HIGH 코멘트 읽고 → 코드 수정 → 재push → Gemini 재리뷰
- 미수정 High 0건이어야 머지 PASS

#### MEDIUM 3분류 (2026-04-16 합의)

**MEDIUM-FIX (자동 수정)**:
- 보안: SQL 주입, XSS, 권한 검증 누락, 암호화 약화, 에러 정보 유출
- 안정성: 에러 핸들링 누락, 타임아웃 미설정, 트랜잭션 누락
- 데이터: 시간대 미명시, 경계값 처리(off-by-one)
- 환경: 하드코딩 경로/키, API 검증 누락
- 프론트: 접근성(a11y), 메모리 누수(미정리 이벤트리스너), 전역 상태 누수

**MEDIUM-SKIP (자동 기각)**:
- 스타일: 변수명, 주석 오타, 불필요 괄호, import 정렬
- 타입: 타입 힌트 누락 (런타임 무관)
- 컨벤션: 코딩 스타일 차이

**MEDIUM-DEFER (보류)**:
- 위 둘에 해당 안 되는 경우
- Gemini 신뢰도 점수 <70인 경우 자동 DEFER
- 동시성/캐시 관련 (Gemini 감지 한계)

#### MEDIUM 운영 방식 (점진적 자동화)
- Week 1-2: 전부 DEFER로 수집, 팀장 수동 분류 (데이터 축적)
- Week 3-4: 축적 데이터로 패턴 분석, FIX/SKIP 자동 분류 규칙 확정
- Week 5+: 자동 분류 가동, 주간 10% 샘플 검토

#### MEDIUM 안전장치
- 자동 FIX 전 15분 대기 (팀장 오버라이드 가능)
- MEDIUM-SKIP → 프로덕션 버그 발생 시 해당 카테고리 자동 FIX 승격
- Gemini 오분류율 >30% 시 FIX만 자동화로 축소
- 주간 보고: 카테고리별 FIX/SKIP/DEFER 건수 + 오분류율

#### LOW 판정
- 무시 (머지 판정에 영향 없음)

#### 판정 분류 (아누 수동 시)
- **수용 (Accept)**: 실제 버그/보안 이슈 → 팀에 수정 위임
- **기각 (Dismiss)**: 의도적 설계, 도메인 특성, 환경 제약 등 → PR에 기각 사유 코멘트
- **보류 (Defer)**: 아누 판단 불가 → 제이회장님 판단 요청

#### 기각 패턴 학습
- 동일 유형이 3회 이상 반복 기각되면 → `.gemini/config.yaml`에 예외 규칙 등록
- 예: "하드코딩 경로 경고" → 단일 서버 환경에서 의도적 → 예외 등록

#### 레벨별 적용
- **Lv.0-2**: Gemini 리뷰 참고만 (판정 의무 없음)
- **Lv.3**: High 이슈는 수용/기각 판정 필수, 무시 금지
- **Lv.4**: High + Medium 이슈 모두 수용/기각 판정 필수

#### 실증 데이터 (2026-04-15 테스트 PR #1)
- High 1건: ads_integration.py GAQL 쿼리 int 캐스팅 → **수용** (실제 보안 이슈)
- Medium 5건: KST 명시, 유사도 알고리즘, All Stop 오킬 위험, Firebase 경로, worktree merge 기준 → 개별 판정 필요

---

## 3. server.py 9개 모듈 분할

### 3.1 분할 맵

**server.py (core) — ~400줄**
- 책임: HTTP 서버, 라우팅, CORS, 모듈 로딩
- 소유: 인프라팀 (야누스 단독이 아닌 dev팀 지원 필요)
- 비고: 3인 분석에서 "devops=야누스 1인이 ~1100줄 소유는 비현실적" 지적 → 인프라팀 + dev팀 합동으로 변경

**routes_get.py — ~2400줄**
- 책임: GET 핸들러 전체
- 소유: dev1/dev2팀

**routes_post.py — ~2100줄**
- 책임: POST/PUT/DELETE 핸들러
- 소유: dev1/dev2팀

**blog_engine.py — ~700줄**
- 책임: 블로그 분석, 경쟁분석
- 소유: dev3/dev4팀

**blog_writer.py — ~500줄**
- 책임: 블로그 백그라운드 생성
- 소유: dev3/dev4팀

**wiki_engine.py — ~300줄**
- 책임: Wiki/Firebase 연동, 양방향 Sync
- 소유: dev5/dev6팀

**absorption.py — ~100줄**
- 책임: Absorption 데이터 처리
- 소유: dev7팀

**ads_integration.py — ~400줄**
- 책임: Meta/Google/Naver 광고 API 연동
- 소유: dev7/dev8팀

**system_monitor.py — ~700줄**
- 책임: 시스템 상태 모니터링, 인증, All Stop
- 소유: 인프라팀 (야누스 + dev팀 지원)

### 3.2 분할 Phase 순서

**Phase 1 (유틸 추출)**:
- 공통 유틸리티 함수, 상수, 설정값을 별도 모듈로 추출
- import 구조 정리
- 서비스 중단 없이 진행 가능

**Phase 2 (서비스 추출)**:
- blog_engine.py, blog_writer.py, wiki_engine.py, absorption.py, ads_integration.py 추출
- 각 모듈이 독립 동작하도록 인터페이스 정리
- 스모크 테스트 선행 필수 (3인 분석: "server.py 분할 시 서비스 중단 → 스모크 테스트 선행 필수")

**Phase 3 (라우트 추출)**:
- routes_get.py, routes_post.py 추출
- 핸들러 간 의존성 정리
- 가장 큰 변경 — 충돌 위험 최대 → 단독 팀 작업 권장

**Phase 4 (코어 정리)**:
- server.py를 core 역할만 남김 (~400줄)
- system_monitor.py 추출
- 라우팅 테이블 정리
- 무중단 전환 계획 수립 필요 (3인 분석: "분할 중 서비스 중단 계획 부재" 지적 반영)

### 3.3 분할의 교차검증 효과
- 모듈 분할 후 각 팀이 담당 파일만 수정 → 머지 충돌 60% 이상 감소 (Cycle 1 합의)
- Gemini PR 리뷰가 파일 단위 diff에 최적화되어 있어, 분할 후 리뷰 품질 대폭 향상
- affected_files 예측 정확도 향상 (작은 파일 = 영향 범위 명확)

---

## 4. Graduated Auto-Gate 3-Layer (G3 Lv.4 통합 테스트 자동화)

### 4.1 설계 (Cycle 5 합의)

**L1: Batch Watchdog**
- 역할: 전팀 .done 파일 수집 추적
- 트리거: 1분 cron
- PASS: 전팀 .done 도착 → L2 자동 진행
- FAIL: TTL 2시간 초과 → Telegram 경고 → 아누 판단

**L2: Pre-flight Check**
- 역할: 기계적 충돌 검증
- 트리거: L1 완료
- PASS: 충돌 없음 → L3 자동 진행
- FAIL: 충돌 파일 목록 → 아누 판단

**L3: Integration Test**
- 역할: pytest tests/integration/ 실행
- 트리거: L2 PASS
- PASS: 전체 테스트 통과 → 자동 완료 보고
- FAIL: 실패 로그 → 아누 판단

### 4.2 Cycle 4→5 수정사항
- G3 Lv.4 오케스트레이터: ~~아누 수동~~ → Graduated Auto-Gate (자동) + FAIL 시에만 아누 개입
- 마아트(Sonnet) 의존: 불필요 (기계적 검증 + pytest로 대체)
- 3인 분석(아누): "아누가 통합테스트 트리거면 다른 업무 못하는 문제" → 자동화로 해결

### 4.3 전제 조건
- tests/integration/ 통합 테스트 스위트 구축 (현재 2개 파일만 존재 → 지속적 확장 필요)
- dispatch.py에 batch_id 필드 추가
- auto_merge.py에 batch completion check + TTL 로직 추가
- batch_id와 Task ID v2 포맷의 관계 정의 필요 (3인 분석: "관계 미정의" 지적)

---

## 5. dispatch.py 자동 게이트

### 5.1 gate_instructions.py 신규 생성
- 위치: `prompts/gate_instructions.py`
- 역할: 레벨별 게이트 지시를 팀장 프롬프트에 자동 삽입
- dispatch.py가 레벨 판정 후 해당 게이트 지시를 프롬프트에 포함

### 5.2 affected_files 필드 표준화
- Lv.2 이상 task 파일에 `affected_files` 필드 강제
- dispatch.py가 겹침 감지: 동일 파일을 다른 팀이 동시 수정 중이면 경고
- 로키 DA(Cycle 2): "affected_files 예측 불완전" → 2단계 감지(dispatch + 머지)로 보완

### 5.3 레벨 자동 추정 + 경고
- 아누 수동 판정 레벨 < 자동 추정 레벨 시 경고 표시
- hard-rule: changed_files >= 3 → 최소 Lv.2 강제
- 로키 DA(Cycle 3): "레벨 수동 판정 → 게이트 우회 위험" → 자동 추정 경고로 대응

### 5.4 dispatch 직렬화 (임시 조치)
- Cycle 2 합의(C2-1): 파일 분할 전까지 dispatch 직렬화(lock) + 운영 규칙 이중 적용
- server.py 같은 대형 파일에 대해 동시 수정 제한
- 구현 방식 미정 (코드 lock vs 운영 규칙) → Phase 1에서 결정

### 5.5 batch_id 필드
- 병렬 위임 시 완료 추적을 위한 batch 식별자
- Graduated Auto-Gate L1(Batch Watchdog)이 batch_id로 전팀 완료 감지
- Task ID v2와의 관계: batch_id는 Task ID의 상위 그루핑 개념 (별도 네임스페이스)

### 5.6 봇 Lazy Start 대응 (task-1971, 2026-04-20)

서버/cokacdir 재부팅 후 dispatch 시 봇의 Claude 세션이 lazy start(첫 메시지 수신 시에만 시작)되어 cron 메시지가 소실되는 문제 대응.

**구현:**
- `_check_bot_process(key)`: `ps aux`에서 봇 key_hash로 Claude 프로세스 존재 확인
- `_wake_up_bot(chat_id, key)`: 프로세스 미감지 시 빈 ping 메시지(".")를 cokacdir로 전송하여 세션 기동 유도
- wake-up 후 최대 25초 대기 (5초 간격 polling)
- wake-up 실패 시 dispatch 딜레이를 10초→30초로 확대
- 프로세스가 이미 존재하면 wake-up 생략 (불필요한 메시지 방지)

**적용 위치:**
- `dispatch()` 함수: cokacdir --cron 호출 직전
- `_dispatch_composite()` 함수: 동일 위치

**로깅:**
- `[lazy-start]` 프리픽스로 WARNING/INFO 로그 출력
- 프로세스 미감지, wake-up 전송, 세션 시작 확인, 딜레이 확대 등 주요 이벤트 기록

---

## 6. Gemini/Codex 외부 AI 통합

### 6.1 Gemini 통합

**역할**: G2 구현 후 코드 리뷰 (GitHub PR 기반)

**기술 스택**:
- Gemini Code Assist GitHub App 설치 (무료 tier)
- PR 생성 시 자동 리뷰 트리거
- 리뷰 결과를 코멘트로 PR에 기록

**제약 (비너스 분석)**:
- 리포지토리 전체 컨텍스트 이해 제한적
- 보험 도메인 비즈니스 로직의 의미론적 검증 불가 → 마아트가 보완
- server.py 7600줄 단일 파일에 대한 리뷰는 컨텍스트 윈도우 한계로 품질 저하 → **server.py 분할 완료가 Gemini 통합의 사실상 선행 조건**
- Rate limit: 8팀 병렬 PR 시 시간당 리뷰 제한 도달 가능성

**보안 리스크 (비너스 분석)**:
- GitHub PR을 통해 코드가 Google 서버로 전송됨
- 보험 고객 데이터 스키마, 수수료 계산 로직, API 키 패턴 노출 위험
- 금소법/개인정보보호법 관점 외부 전송 문제 가능
- **sanitize 게이트 필수**: 외부 AI 전송 전 PII/비즈니스 로직 마스킹 자동화 (기존 sanitize 스킬 파이프라인 통합)

**현재 PR 플로우 충돌 (아누 분석)**:
- 현재 시스템은 worktree 기반 auto_merge.py가 PR 없이 직접 머지
- PR 기반으로 전환하면 auto_merge.py 전체 플로우 재설계 필요
- 로드맵에 이 변경 범위 미반영 → Phase 3에서 추가 고려

**팀장 봇 Gemini 대응 워크플로우 (2026-04-15 추가)**:
- 아누가 Gemini 리뷰를 트래킹하는 대신, **작업한 팀장 봇이 직접** Gemini 리뷰에 대응
- 같은 세션에서 방금 수정한 코드이므로 맥락을 완전히 이해 → Sonnet이어도 판단 가능
- 아누 병목 제거

워크플로우:
```
팀장 봇 코드 수정 → git push → PR 생성 (gh pr create)
→ Gemini 리뷰 대기 (5분, gh api로 polling)
→ 팀장 봇이 gh api로 Gemini 코멘트 읽기
→ 각 코멘트 수용/기각 판정 (계획서 2.5절 기준)
  - 수용: 코드 수정 + 재push
  - 기각: PR에 기각 사유 코멘트 (gh api로 답글)
→ 미수정 High 0건 확인 → PASS
→ merge + .done 생성
```

구현 필요 사항:
- worktree_manager.py cmd_finish에 PR 생성 + Gemini 대기 + 대응 로직 추가
- 또는 DIRECT-WORKFLOW.md에 "Gemini 리뷰 대응" 단계 추가 (팀장 프롬프트 수준)
- gh CLI 권한 확인 (봇 세션에서 gh api 사용 가능 여부)

### 6.2 Codex 통합

**역할**: G1 설계 전 사전 검증

**기술 스택**:
- Codex CLI v0.106.0 (서버 설치 완료)
- `codex exec` 서브커맨드로 비대화형 파이프라인 통합
- CLIRunner.run_codex()로 subprocess 기반 호출

**현재 상태 (아틀라스 분석)**:
- **API 키 401 Unauthorized** → 키 갱신 필요
- 현재 모델: gpt-5.1-codex-mini (2세대 뒤처짐) → gpt-5.3-codex 이상 업그레이드 필요
- codex-plugin-cc는 실제로는 CLIRunner 통한 subprocess 호출이며, 진정한 MCP 플러그인 통합은 미구현

**제약 (아틀라스 분석)**:
- Codex CLI exec 모드는 sandbox read-only → 파일 읽기만 가능, LSP 심층 분석 불가
- 컨텍스트 윈도우 약 258k 토큰 → server.py 단독 분석은 가능하나 다중 파일은 한계
- "Codex 사전 검증"의 구체적 프로토콜(입력/출력/판정기준) 미정의
- Codex 출력이 자연어 → PASS/FAIL 기계적 판정 파서 필요 (`--output-schema` 플래그 활용)

**비용**:
- Codex CLI 자체는 Pro/Plus 구독 포함 (무료)
- API 호출 시 토큰 비용 발생
- Lv.3+ 작업에만 호출 → 일일 3-5건 수준이면 비용 미미

### 6.3 역할 분리 원칙
- **설계 전 = Codex**: 설계 문서의 기존 코드 호환성, 충돌 위험, 아키텍처 패턴 적합성 분석
- **구현 후 = Gemini**: PR 기반 코드 패턴, 구문, 보안, 스타일 리뷰
- **폴백**: 외부 AI 장애 시 마아트 독립 검증으로 대체

### 6.4 비너스 핵심 질문
> "폴백이 가능하다면, 평시에도 마아트로 충분한 것 아닌가? Gemini 리뷰가 마아트 대비 실질적 부가가치를 제공하는 시나리오가 아직 실증되지 않았다."

→ Phase 1 한정 적용 후 효과 측정으로 답을 구한다. ROI 미실증 상태에서 전면 도입하지 않는다.

---

## 7. 3문서 레벨별 관리

### 7.1 적용 기준
- **Lv.0-2**: 3문서 불필요 (task 파일 + affected_files로 충분)
- **Lv.3**: 3문서 필수 (리서치 → 미팅 → 3문서 → 핵미사일 → 코딩)
- **Lv.4**: 3문서 필수 + Agent 미팅 만장일치 + Codex 검증

### 7.2 기존 프로세스와의 관계
아누 가이드 2.2절의 프로젝트 시작 프로세스 그대로 유지:
```
Phase 0: 리서치 → Phase 1: Agent 미팅 → Phase 2: 3문서 → Phase 3: 핵미사일 → Phase 4~N: 코딩
```
보리스 게이트는 이 프로세스의 Phase 4~N(코딩) 단계에 G1/G2/G3를 오버레이한다.

---

## 8. 기존 시스템 → 신규 매핑

### 8.1 호환성 매핑

**보리스 워크플로우** → G1 사전 단계 | 변경 없음
- Annotation Cycle은 그대로 유지. 보리스 게이트는 코딩 단계에 적용.

**3문서 시스템** → G1 통과 조건 (Lv.3+) | 변경 없음
- 기존 3문서(계획서/맥락노트/체크리스트) 체계 완전 유지.

**핵미사일 발사코드** → G1 최종 단계 | 변경 없음
- Context Purge + Checkpointing + 제이회장님 승인. 불변.

**QC 프로세스** → G2 흡수 | level 매핑 확장
- 기존 마아트 QC가 G2 내부로 흡수.
- Lv.3+에서 Gemini 리뷰 추가.

**마아트 독립 검증** → G2 내부 + Gemini 폴백 | 역할 추가
- 기존 마아트 역할 유지 + 외부 AI 장애 시 폴백 담당.

**로키 레드팀** → G2 Lv.4 필수 + DA | 변경 없음
- 보안 감사 + Devil's Advocate. 모든 미팅 필수 참석.

**worktree 격리** → G3 기반 | 변경 없음
- worktree 기반 격리 + 머지 전 main 최신화 강제.

**auto-commit** → 게이트 독립 | 변경 없음
- PostToolUse hook, 30초 디바운스, main 제외. 게이트와 무관하게 동작.

**Task ID v2** → 변경 없음
- Phase/병렬/재시도 포맷 그대로 유지.

### 8.2 신규 추가 요소

- **gate_instructions.py**: 레벨별 게이트 지시 자동 삽입 (prompts/ 신규)
- **affected_files 필드**: task 파일 표준 필드 (Lv.2+)
- **batch_id 필드**: dispatch.py 병렬 위임 그루핑
- **Graduated Auto-Gate**: auto_merge.py 확장 (L1/L2/L3)
- **sanitize 게이트**: 외부 AI 전송 전 PII 마스킹 (비너스 분석에서 필수 지정)

---

## 9. 기각된 대안

### 9.1 가상 모듈 경계 (리전 마커)
- 물리적 분할 대신 `# region` 마커로 논리적 분리
- 기각 사유: 물리적 분할보다 효과 부족. 머지 충돌은 파일 단위에서 발생하므로 리전 마커로는 해결 불가.

### 9.2 Codex API 자동화
- G1에서 Codex를 자동 호출하여 결과를 파이프라인에 바로 반영
- 기각 사유: 수동 트리거로 충분. 자동화는 수요 증명 후 도입 (C2-5 합의).

### 9.3 Auto-Rebase Bot
- 머지 전 자동 rebase로 충돌 사전 해결
- 기각 사유: 시맨틱 충돌(코드 의미 변화) 미감지 리스크. 텍스트 충돌만 해결하고 로직 충돌은 놓침.

### 9.4 로키 DA 제안: "대형 파일 동시 수정 금지" 운영 규칙
- Cycle 2에서 로키가 "가장 단순한 대안"으로 제안
- 최종 합의에서 명시적 채택/기각 기록 없음
- 아누 분석: 제이회장님의 모듈화 사고방식에 가장 부합하는 대안. server.py 분할이 이 대안의 물리적 구현에 해당.
- **실질적으로 server.py 분할(섹션 3)이 이 대안을 근본 해결함.**

---

## 10. 실행 로드맵

### 10.1 5 Phase 계획 (원안: 약 7주, 조건부 실행)

**Phase 1 (1주) — 기반 인프라**
- [ ] gate_instructions.py 신규 생성
- [ ] dispatch.py에 affected_files 필드 추가
- [ ] dispatch.py에 batch_id 필드 추가
- [ ] 레벨 자동 추정 경고 로직
- [ ] 셀프 디버깅 강화
- 이 Phase만 한정승인 → 구현 → 효과 측정

**Phase 2 (2주) — server.py 분할 전반**
- [ ] Phase 1 분할: 유틸리티 함수/상수/설정 추출
- [ ] Phase 2 분할: blog_engine, blog_writer, wiki_engine, absorption, ads_integration 추출
- [ ] 스모크 테스트 + 무중단 전환 확인
- Phase 1 효과 측정 결과에 따라 진행 여부 재판단

**Phase 3 (1주) — 교차검증 파이프라인**
- [ ] Gemini GitHub App 설치 + PR 플로우 전환 설계
- [ ] Codex API 키 갱신 + 헬스체크 자동화
- [ ] Codex 검증 프로토콜 명문화 (입력/출력/판정기준)
- [ ] sanitize 게이트 구축 (외부 AI 전송 전 PII 마스킹)
- [ ] Codex 모델 업그레이드 (gpt-5.1-codex-mini → gpt-5.3-codex+)
- **비너스 권고: Phase 3를 Phase 4 이후로 재배치 (server.py 분할 선행)**
- 3인 분석에서 전원 "server.py 분할이 Gemini 통합의 선행 조건"으로 판정

**Phase 4 (2주) — server.py 분할 후반**
- [ ] Phase 3 분할: routes_get, routes_post 추출
- [ ] Phase 4 분할: server.py core 정리, system_monitor 추출
- [ ] 라우팅 테이블 정리
- [ ] 통합 테스트 확장

**Phase 5 (1주) — 통합 테스트 + 효과 측정**
- [ ] tests/integration/ 스위트 확장 (현재 2개 → 목표 10개+)
- [ ] Graduated Auto-Gate 3-Layer 구현 (auto_merge.py 확장)
- [ ] 레벨 자동 추정 정확도 검증
- [ ] 효과 측정: 머지 충돌 감소율, 원복 발생률, 팀 생산성 비교
- [ ] 비용/ROI 산정: Gemini + Codex vs 마아트 독립 검증 대비

### 10.2 3인 분석 합의: Phase 1 한정승인 접근

**전원 CONDITIONAL 판정 → Phase 1만 먼저 실행하고 효과 측정 후 재판단.**

이유:
- 기반 인프라(gate_instructions.py, affected_files, batch_id)가 없는 상태에서 7주 전체 로드맵 승인은 "죽은 코드/스킬 금지" 원칙에 저촉 (아누 분석)
- server.py 분할이 Gemini 통합의 선행 조건 (비너스 분석)
- Codex API 키 401, 검증 프로토콜 미정의 (아틀라스 분석)

### 10.3 로드맵 순서 재배치 (3인 분석 반영)

권고 순서:
```
Phase 1 (기반) → Phase 2 (분할 전반) → Phase 4 (분할 후반) → Phase 3 (교차검증) → Phase 5 (측정)
```
- Phase 3(교차검증)을 Phase 4(분할 후반) 이후로 이동
- server.py 분할 완료 → Gemini 통합 활성화 순서

---

## 14. 로키 DA 경고사항 전체 (Cycle 1~5)

### Cycle 1 DA
1. **검증 피로(Validation Fatigue)**: 검증자 6회는 "앞에서 걸렀겠지" 방관 효과 유발. 보안 업계에서 검증자 3인 초과 시 실제 탐지율 오히려 하락.
2. **머지 시점 gap**: 구현 후 PR 생성까지 시간차 동안 main 진행 → 검증 시점 코드와 머지 시점 코드가 다름.
3. **커밋 안 한 변경사항 손실**: 워크플로우가 아니라 auto-commit 주기 문제. 5분 간격 auto-commit이 없으면 아무리 교차검증해도 손실. → 해결됨 (auto-commit hook 30초)

### Cycle 2 DA
1. **affected_files 예측 불완전성**: 2단계 감지(dispatch + 머지)로 보완, 단 머지 시점 감지 후 조치(재구현? 수동 병합?) 미명시.
2. **dispatch.py 복잡화**: Gemini 로직은 dispatch가 아닌 worktree_manager에 배치.
3. **가장 단순한 대안**: 대형 파일 동시 수정 금지 (운영 규칙). → server.py 분할이 물리적으로 해결.

### Cycle 3 DA
1. **레벨 수동 판정 → 게이트 우회 위험**: 자동 추정 경고로 대응.
2. **외부 AI 장애 → 파이프라인 블로킹**: 마아트 폴백으로 대응.
3. **server.py 분할 시 서비스 중단**: 스모크 테스트 선행 필수.
4. **게이트 피로**: "위험 1개 집중" 방식 Lv.1-2에 적용.

---

## 15. 3인 심층 분석 CONDITIONAL 조건 종합

### 15.1 아누 (Claude Opus) CONDITIONAL 조건

1. **Cycle 4 복원 및 사이클 수 정정**: 합의 과정 완전성을 위해 Cycle 4 내용 명시적 보완 필요. 보리스 워크플로우의 "매 사이클 기록" 원칙 위반.

2. **외부 AI(Codex/Gemini) 통합 사전 리서치 필수**: codex-plugin-cc 실재 여부, Gemini GitHub App private repo 대응, 비용 확인 후 설계 반영. 확인 없이 로드맵에 넣은 것은 "모르면 모른다고 할 것" 원칙 위반 가능성.

3. **Phase 1 선행 후 재검증**: gate_instructions.py + affected_files + batch_id 실제 구현 후 나머지 Phase 실행 가능성 재평가. 기반 인프라 없는 상태에서 7주 전체 로드맵 승인은 "죽은 코드/스킬 금지" 원칙 저촉.

4. **server.py 모듈 소유팀 배정 vs 실제 팀 구성 불일치**: devops=야누스 1인이 ~1100줄 소유 비현실적 → 인프라팀+dev팀 합동으로 변경.

5. **PR 플로우 충돌**: 현재 auto_merge.py가 PR 없이 직접 머지 → PR 기반 전환 시 재설계 필요, 로드맵 미반영.

6. **한정승인과 게이트 시스템 상호작용**: 한정승인된 작업의 게이트를 누가 통과시키는지 미정의.

7. **dispatch.py 직렬화 lock 구체적 구현**: 코드 lock vs 운영 규칙 미결정.

8. **7주 로드맵 리소스 배분**: 어느 팀이 각 Phase 담당하는지 미배정.

### 15.2 비너스 (Gemini) CONDITIONAL 조건

1. **sanitize 게이트 필수**: 외부 AI 전송 전 PII/비즈니스 로직 마스킹 자동화. 기존 sanitize 스킬 파이프라인 통합.

2. **server.py 분할 선행**: Phase 2-4 완료 후에만 Gemini 리뷰 활성화. Phase 3을 Phase 4 이후로 재배치 권고.

3. **비용/ROI 산정**: Gemini Enterprise + Codex API 월간 예상 비용 vs 마아트 독립 검증 대비 결함 감소율 실측.

4. **Lv.3-4 한정 적용**: Lv.0-2에서 외부 AI 교차검증은 과잉. 마아트+팀 테스터로 충분.

5. **Graduated Auto-Gate와 Gemini 리뷰 인터페이스 명세**: G2 Gemini FAIL 시 L2/L3 자동 게이트 동작 정의 필요.

6. **인지 편향 차단 효과 과대평가**: Claude/Gemini/GPT 동일 학습 데이터 편향 공유. 진정한 교차검증은 AI-인간 간.

7. **Rate Limit**: 8팀 병렬 PR 시 Gemini Code Assist 시간당 리뷰 제한.

8. **UI/디자인 교차검증 공백**: 프론트엔드 변경의 시각적 검증 미고려.

### 15.3 아틀라스 (Codex) CONDITIONAL 조건

1. **API 키 정상화 + 헬스체크 자동화**: 현재 401 Unauthorized. 키 갱신 + 키 로테이션 자동화 선행.

2. **Codex 검증 프로토콜 명문화**: 입력(설계문서+affected_files+기존코드), 출력 스키마(JSON: `{pass, risks, suggestions}`), 판정 기준(critical 0개=PASS).

3. **모델 버전 업데이트**: gpt-5.1-codex-mini → gpt-5.3-codex 이상. 컨텍스트 컴팩션 기능 활용.

4. **"설계 전 = Codex" 역할 모호성**: 논리적 일관성 검증인지, 호환성 분석인지, 패턴 적합성인지 정의 필요.

5. **Codex vs Claude Code 도구 접근 차이**: Codex exec는 sandbox read-only, LSP 심층 분석 불가. 정적 텍스트 분석 수준.

6. **server.py 분할과의 시간 충돌**: Phase 3 Codex 연동 시점에 이미 파일 분할 완료 가능 → 대형 파일 분석 능력이 과도기에만 필요.

---

## 16. 추천 실행 전략 (3인 분석 합의)

**Phase 1만 한정승인 → 구현 → 효과 측정 → Phase 2 이후 재판단.**

Phase 1 완료 시 확인할 지표:
1. gate_instructions.py 동작 확인: 레벨별 게이트 지시가 프롬프트에 정상 삽입되는가?
2. affected_files 겹침 감지: 동시 수정 경고가 실제로 동작하는가?
3. batch_id 완료 추적: 병렬 위임 완료 감지가 정확한가?
4. 레벨 자동 추정: 수동 판정과 자동 추정의 일치율은?

이 지표를 기반으로 Phase 2~5 진행 여부와 순서를 재판단한다.

---

---

## 9. 보고서≠구현 방지 체계 (task-1874)

> 도입일: 2026-04-16 | 근거: Agent 미팅 9명 전원합의 (task-1874)

### 9.1 근본 원인
1. Edit 도구 조용한 실패 + 보고 생성 편향
2. 서브에이전트 컨텍스트 격리
3. selfQC 자기보고 맹점
4. 파일 크기-실패 양의 상관관계 (2000줄+)

### 9.2 방지책 로드맵
- Tier 1 (즉시): Edit 직후 grep 검증 의무화, 보고서 planned/verified 분리
- Tier 2 (1주): Large-File Protocol, 심볼 존재 검증기, File-Touch Ratio
- Tier 3 (1개월): G3 독립 검증 에이전트

---

## 10. dispatch.py 봇 lazy start 대응 (task-1971)

> 도입일: 2026-04-20 | 근거: 서버 재부팅 후 cron 작업 소실 문제 실발생

### 10.1 문제 정의
서버/cokacdir 재부팅 후 봇의 Claude 세션이 lazy start 방식으로 동작.
cron 메시지가 Claude 프로세스 기동 전에 도착하면 소실됨.

### 10.2 해결 로직
1. **프로세스 확인**: `_check_bot_process(key)` — pgrep으로 cokacdir 프로세스 존재 여부 판별
2. **wake-up 전송**: `_wake_up_bot(chat_id, key)` — "." ping 메시지 전송 후 polling(최대 25초)
3. **딜레이 확대**: wake-up 실패 시 dispatch 딜레이를 10초→30초로 확대
4. **적용 범위**: `dispatch()` + `_dispatch_composite()` 양쪽에 통합

*이 계획서는 Agent 미팅 5사이클 전체 합의사항 + 아누/비너스/아틀라스 3인 병렬 심층 분석(전원 CONDITIONAL) + 로키 DA 경고사항을 빠짐없이 집대성한 것이다. 핵미사일 발사코드(Context Purge + 제이회장님 승인) 전까지 DON'T IMPLEMENT.*

---

## 11. Gemini PR 리뷰 강제 적용 (task-1970)

> 도입일: 2026-04-20 | 근거: task-1968 분석에서 발견된 Gemini 리뷰 허점 6건 수정

### 11.1 수정된 허점
- **A. Gemini 타임아웃 시 머지 차단**: `blocked_by_timeout` 상태 도입. 타임아웃 시 PR 자동 머지 방지.
- **B. 파서 패턴 수정**: `![high](URL)`, `![critical](URL)`, `![medium](URL)` Gemini 실제 포맷 감지 추가. SVG URL 패턴 추가.
- **C. 파싱 실패 기본값 해소**: B 수정으로 파싱 성공률 100% 달성.
- **D. 기각 사유 필수 규칙**: DIRECT-WORKFLOW.md에 `[DISMISS]` 포맷 + "사유 없는 기각은 QC FAIL" 명시.
- **E. QC/G3 교차검증**: `gemini_review_check` verifier 신설 + g3_independent_verifier에 `check_gemini_review` 추가. 보고서 "High N건"과 실제 severity 교차검증.
- **F. collect_mode 기본값 변경**: `True→False`로 자동 수정 루프 기본 활성화.

### 11.2 방어 레이어 구조
- 자동 방어: 파서 패턴(B/C), 타임아웃 차단(A), 자동 수정 활성화(F)
- QC 방어: gemini_review_check verifier + g3 교차검증(E)
- 거버넌스 방어: 기각 사유 필수 규칙(D)

---

## 12. .done 자동 검증 게이트 (task-1972)

> 도입일: 2026-04-20 | 근거: 에이전트 미팅 전수조사 적발률 34% — 코드 미존재 완료 보고 구조적 문제

### 12.1 이중 검증 체계
- **생산자 게이트 (signature_check verifier)**: qc_verify.py의 ALL_CHECKS에 등록. task 파일의 `## 완료 시그니처` 섹션에서 grep/pytest 패턴을 파싱하여 자동 실행.
- **소비자 게이트 (verify_done.py)**: .done 파일 생성 후 실제 코드 존재 여부 재검증. 실패 시 `.done.rejected` 생성.

### 12.2 레벨별 검증 범위
- Lv.1-2: `[grep]` 시그니처만 검증
- Lv.3+: `[grep]` + `[pytest]` 모두 검증

### 12.3 하위 호환성
- `## 완료 시그니처` 섹션이 없는 기존 task → SKIP (하위 호환 유지)

---

## 13. Chrome DevTools MCP 통합 (task-1984)

> 도입일: 2026-04-20 | 근거: L1 스모크테스트 강화를 위한 DevTools 도구 접근

### 13.1 설정
- `~/.claude/settings.json`에 chrome-devtools-mcp 서버 headless 모드 추가
- `--usageStatistics false`, `--performanceCrux false` 플래그로 외부 데이터 전송 차단
- 기존 Playwright MCP와 공존 확인

### 13.2 L1 스모크테스트 활용 도구 (6종)
- `navigate`: 페이지 이동 및 접근성 확인
- `take_screenshot`: 스크린샷 캡처 (Playwright 대체 가능)
- `snapshot`: 페이지 접근성 트리 스냅샷
- `console_messages`: 콘솔 에러/경고 확인
- `lighthouse`: Lighthouse 접근성/SEO/성능 감사
- `network`: API 호출 패턴 및 실패 요청 확인

### 13.3 듀얼 MCP QC 자동화 (task-2021)
- `browser_verify` verifier 신설: qc_verify.py ALL_CHECKS에 등록
- 프론트엔드 변경 감지 → 스크린샷/보고서 증거 자동 확인
- 판정: SKIP(비프론트) / PASS(증거 완비) / WARN(Lighthouse 미기록) / FAIL(스크린샷 없음)
- MCP 직접 호출이 아닌 증거 기반 검증 (팀장 DIRECT-WORKFLOW 준수 여부 자동 확인)