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

# 교차검증 풀스택 워크플로우 — 맥락 노트 (Context Notes)

> 프로젝트: 교차검증 풀스택 워크플로우 도입 + server.py 모듈 분할
> 작성일: 2026-04-15
> 목적: 왜 이렇게 결정했는지, 어떤 자료를 참조했는지, 미래의 세션이 맥락을 완전히 복원할 수 있도록 기록
> 문서 버전: v1.0

---

## 1. 왜 이 프로젝트가 시작되었는가

### 1.1 트리거 이벤트 (2026-04-15)
대시보드 작업 중 **동일한 기능이 5회 이상 원복**되는 사태 발생:
- H1/H2 드롭다운: 5번 구현 → 5번 원복 → 제이회장님 "이젠 웃음만 나온다 몇번째냐 이게"
- 정제 UI 3건 (progress bar 닫기, 이력 동적 갱신, 미반영 표시): 구현 → 원복 → 재구현 → 원복
- 히스토리 삭제 기능: 프론트엔드만 살아나고 백엔드 API 사라짐
- 네이버블로그 다크모드 색상: 수정 → 원복

### 1.2 근본 원인 분석
1. **server.py 7600줄 모놀리스**: 모든 팀이 같은 파일을 수정 → 머지 충돌 필연
2. **커밋 누락**: 코드 수정 후 커밋하지 않은 상태에서 다른 팀의 worktree 머지로 덮어쓰임
3. **검증 부재**: 구현 후 검증 없이 즉시 머지 → 사일런트 리그레션 미감지
4. **main 최신화 없는 머지**: worktree finish 시 main 최신 상태를 반영하지 않고 머지

### 1.3 이미 해결된 부분 (이 세션에서)
- auto-commit hook 도입 (PostToolUse, 30초 디바운스, main 제외)
- worktree_manager.py에 `git merge main --no-edit` 강제
- wip auto-push (10분 디바운스, 원격 task/ 브랜치)
- subprocess start_new_session (서버 재시작 독립)

### 1.4 아직 해결 안 된 근본 문제
- server.py 7600줄이 여전히 단일 파일 → 구조적 머지 충돌 원인
- 레벨별 차등 검증 체계 없음 → 단순 버그 수정도 풀 검증, 중대 변경도 경량 검증
- 외부 AI 교차검증 미도입 → 같은 모델(Claude)의 인지 편향 내에서만 검증

---

## 2. 결정 근거 기록

### 2.1 왜 13단계가 아닌 3게이트인가?

**미팅 Cycle 1, 다빈치 제안:**
> "핵심 문제는 워크플로우 단계 수가 아니라 파일 단위 잠금이 없다는 것. 13단계 직렬은 과잉. 3개 게이트(설계→구현→머지)로 묶고, 각 게이트의 검증 깊이만 레벨에 따라 조절하면 '어떤 단계를 빼나'가 아니라 '이 게이트의 검증 깊이를 몇으로 하나'로 바뀌어 설계가 단순해진다."

**근거**: 직렬 단계 나열은 단계 간 순서 의존성과 전체 리드타임 증가를 야기한다. 게이트 패턴은 독립적 검증 포인트로, 레벨에 따라 깊이만 조절하므로 유연성이 높다.

### 2.2 왜 server.py 분할이 교차검증보다 우선인가?

**미팅 Cycle 1 합의 #2:**
> "server.py 분할이 교차검증보다 우선. 분할하면 충돌 자체가 60% 감소."

**로키 DA 보강:**
> "교차검증만 강화하면 '충돌을 더 잘 발견'할 뿐 '충돌 자체를 줄이지' 못한다."

**비너스 3인 분석:**
> "server.py 7600줄 단일 파일에 대한 Gemini 리뷰는 컨텍스트 윈도우 한계로 품질 저하. server.py 분할 완료가 Gemini 통합의 사실상 선행 조건."

**근거**: 문제의 근본 원인(7600줄 단일 파일)을 해결하지 않고 검증만 강화하는 것은 증상 치료. 모듈화가 제이회장님의 핵심 철학("모듈화 = 사고방식").

### 2.3 왜 Gemini 리뷰를 2회에서 1회로 줄였는가?

**미팅 Cycle 1 합의 #4:**
> "Gemini 2회 리뷰는 비효율 → 1회 + 체크리스트 확인"

**로키 DA (Cycle 1):**
> "검증자 6회는 각 검증자가 '앞에서 걸렀겠지'라고 가정하는 방관 효과를 유발. 보안 업계에서 검증자 3인 초과 시 실제 탐지율 오히려 하락."

**근거**: Validation Fatigue 현상. 검증 횟수를 늘리는 것보다 각 검증의 품질(집중도, 책임감)을 높이는 것이 효과적.

### 2.4 왜 Codex는 리뷰가 아닌 사전 설계 검증에 활용하는가?

**미팅 Cycle 1 합의 #5:**
> "Codex는 리뷰보다 사전 설계 검증에 활용"

**Cycle 2 합의 C2-4:**
> "설계 전 = Codex(수동), 구현 후 = Gemini(코드 리뷰)"

**근거**: 아누 가이드의 "생성하는 지능 ≠ 검증하는 지능" 원칙 적용. Codex는 생성(설계) 관점에서 호환성을 사전 체크하고, Gemini는 독립적으로 구현 결과를 사후 검증. 역할 분리를 통한 상호 견제.

### 2.5 왜 dispatch.py가 게이트를 자동 적용해야 하는가?

**헤르메스 (Cycle 1):**
> "13단계를 팀장이 매번 수동으로 따르는 건 불가능. 3일 안에 무시하기 시작한다. 실행 가능한 유일한 방법은 dispatch.py가 레벨에 따라 자동으로 게이트를 삽입하는 것."

**근거**: 인간/AI 모두 수동 프로세스는 피로로 인해 무시하게 된다. 코드로 강제하는 것만이 지속 가능한 방법. 아누 가이드 1.1절 "훅 자동 실행 흐름"과 일치.

### 2.6 왜 교차검증은 겹침 감지 시에만 Gemini 집중 리뷰인가?

**Cycle 2 합의 C2-3:**
> "교차검증은 겹침 감지 시에만 Gemini 집중 리뷰"

**야누스 (Cycle 1):**
> "레벨1~2는 속도 우선이 맞다. 원복 확률 자체가 낮고, 원복 비용도 작다. 핵심 변수는 '동시 작업 수'. 병렬 3팀 이상 동시 작업 시에는 레벨2라도 머지 검증 강화."

**근거**: 모든 작업에 Gemini 리뷰를 적용하면 처리량 50% 하락(야누스 분석). 위험이 높은 경우(파일 겹침, 병렬 작업)에만 집중 리뷰하여 비용 효율 극대화.

### 2.7 왜 통합 테스트를 아누가 아닌 자동화로 하는가?

**Cycle 4→5 수정:**
원래 G3 Lv.4 오케스트레이터가 아누(수동)였으나, 제이회장님이 "아누가 통합테스트 트리거면 다른 업무 못하는 것 아닌가?" 질문.

**Cycle 5 합의: Graduated Auto-Gate**
- L1(Batch Watchdog) → L2(Pre-flight) → L3(Integration Test) 자동 파이프라인
- FAIL 시에만 아누 개입
- 마아트(Sonnet) 의존 불필요: 기계적 검증 + pytest로 대체

**근거**: 아누는 오케스트레이터이지 실행자가 아니다. 기계적 검증(충돌 감지, 테스트 실행)은 자동화하고, 판단이 필요한 FAIL 케이스에만 인간/아누가 개입.

### 2.8 왜 Gemini 리뷰 대응을 아누가 아닌 팀장 봇이 하는가?

**제이회장님 지시 (2026-04-15):**
> "팀장 봇이 답글을 다는게 좋지 않을까? 아누 너가 계속 트래킹하면 안될거 같다. 팀장봇이 sonnet이어도 방금 전에 수정하고 git push한 내용이니 같은 세션에 있으니까 판단하는데는 문제 없지?"

**근거**:
1. 팀장 봇이 같은 세션에서 방금 수정한 코드 → 맥락을 완전히 이해 → Sonnet이어도 판단 가능
2. 아누가 매번 Gemini 리뷰를 트래킹하면 아누가 병목이 됨 (Cycle 5에서 "아누가 통합테스트 트리거면 다른 업무 못하는 문제"와 동일 패턴)
3. 봇이 gh api로 PR 코멘트를 읽고 답글을 다는 것이 기술적으로 가능

**Gemini 리뷰 판정 누락 발견 (2026-04-15)**:
원래 계획서에 "Gemini PASS 필요"만 있고, PASS 기준/수용·기각 프로세스가 없었음. 제이회장님 지적으로 2.5절(판정 프로세스) 추가됨.

### 2.9 왜 마아트(Sonnet)가 아닌 Gemini/Codex인가?

**제이회장님 질문 (Cycle 4→5):**
> "마아트는 소넷이잖아. 다른 방법 없을까?"

**미팅 재논의 결과:**
- 마아트 역할: G2 내부 QC (기존 역할 유지) + Gemini 폴백
- Gemini: 다른 모델 엔진으로 인지 편향 차단 시도
- Codex: OpenAI 엔진으로 설계 관점 교차 체크

**비너스 반론:**
> "Claude/Gemini/GPT 모두 동일한 학습 데이터 편향을 상당 부분 공유. 진정한 교차검증은 AI-인간 간."

**근거**: 같은 Claude 모델 내에서의 교차검증(마아트 Sonnet vs 팀장 Sonnet)은 인지 편향 차단에 한계가 있다. 다른 엔진을 도입하여 편향 다양화를 시도하되, 효과는 Phase 1 후 실측으로 판단.

### 2.10 왜 Phase 1만 한정승인인가?

**아누 3인 분석:**
> "기반 인프라(gate_instructions.py, affected_files, batch_id)가 없는 상태에서 7주 전체 로드맵 승인은 '죽은 코드/스킬 금지' 원칙에 저촉."

**아틀라스 분석:**
> "Codex API 키 401 Unauthorized. 키 갱신 + 헬스체크 자동화 선행 필요."

**비너스 분석:**
> "server.py 분할 완료가 Gemini 통합의 선행 조건. Phase 3을 Phase 4 이후로 재배치 권고."

**근거**: 3인 전원 CONDITIONAL 판정. 기반이 없는 상태에서 전체를 승인하면 실행 불가 항목이 포함될 위험. Phase 1을 실행하여 기반을 구축하고, 실측 데이터로 나머지를 재판단하는 것이 안전.

---

## 3. 미팅 사이클별 진화 기록

### 3.1 Cycle 1: 구조 설계

**핵심 합의 5건:**
1. 13단계 직렬 과잉 → 3개 게이트로 단순화
2. server.py 분할이 교차검증보다 우선 — 분할하면 충돌 자체 60% 감소
3. dispatch.py가 레벨별 게이트를 자동 적용해야 실행 가능 (수동 준수 불가)
4. Gemini 2회 리뷰 비효율 → 1회 + 체크리스트 확인
5. Codex는 리뷰보다 사전 설계 검증에 활용

**참여자 핵심 주장:**
- **다빈치**: 게이트 패턴 제안, server.py 분할 선행 강조
- **로키**: 검증 피로, 머지 시점 gap, auto-commit 주기 문제 지적
- **야누스**: 속도 vs 품질 트레이드오프 분석 (Lv.1-2 속도 우선, Lv.3-4 품질 우선), "동시 작업 수"가 핵심 변수
- **헤르메스**: dispatch.py 자동 게이트 삽입이 유일한 실행 가능 방법
- **비너스**: Gemini Code Assist GitHub App 활용, server.py 단일 파일 리뷰 한계
- **아틀라스**: Codex CLI exec 파이프라인, sandbox read-only 제약
- **프로메테우스**: 단계적 도입 (Lv.3→Lv.4→전체), 효과 측정 데이터 기반
- **불칸**: auto_merge.py 확장, 인프라 관점 실행 가능성
- **이리스**: 개발자 경험(DX), 게이트 피로 최소화, 자동화 필수

### 3.2 Cycle 2: 운영 규칙 + 역할 분리

**핵심 합의 5건:**
- C2-1: 파일 분할 전까지 dispatch 직렬화(lock) + 운영 규칙 이중 적용
- C2-2: task 파일에 affected_files 필드 표준화
- C2-3: 교차검증은 겹침 감지 시에만 Gemini 집중 리뷰
- C2-4: 설계 전 = Codex(수동), 구현 후 = Gemini(코드 리뷰)
- C2-5: 스크린샷 diff + Codex 자동화는 수요 증명 후

**로키 DA (Cycle 2) 핵심 반론:**
- affected_files 예측 불완전성 → 2단계 감지(dispatch + 머지)로 보완
- dispatch.py 복잡화 → Gemini는 worktree_manager에 배치
- 가장 단순한 대안: 대형 파일 동시 수정 금지 (운영 규칙)

### 3.3 Cycle 3: 최종 합의 집대성

**핵심 산출물:**
1. 보리스 게이트 시스템 최종 매트릭스 (G1/G2/G3 × Lv.0-4)
2. 3 Step Why × Cross-Verification 매핑
3. server.py 9개 모듈 분할 맵
4. dispatch.py 자동 게이트 설계
5. Gemini/Codex 통합 방안
6. 3문서 레벨별 관리 기준
7. 5 Phase 7주 실행 로드맵

**기존 시스템 호환성 테이블 확정:**
- 보리스 워크플로우, 3문서, 핵미사일, QC, 마아트, 로키, worktree, auto-commit, Task ID v2 — 전부 호환.

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

**기각된 대안 3건:**
1. 가상 모듈 경계(리전 마커): 물리적 분할보다 효과 부족
2. Codex API 자동화: 수동 트리거로 충분, 자동화는 수요 증명 후
3. Auto-Rebase Bot: 시맨틱 충돌 미감지 리스크

### 3.4 Cycle 4: 오케스트레이션 자동화 전환 (복원: task-1908)

> 기존에 "기록 누락"으로 표기되었으나, Cycle 5 내부 기록 및 아누 3인 분석에서 복원.

**핵심 합의 2건:**
1. G3 Lv.4 오케스트레이터를 아누(수동) → Graduated Auto-Gate(자동)로 전환. FAIL 시에만 아누 개입.
2. 마아트(Sonnet) 의존 제거 → 기계적 검증 + pytest로 대체. 마아트는 G2 내부 QC + Gemini 폴백으로 역할 재정의.

**발단 (제이회장님 피드백 2건):**
- "아누가 통합테스트 트리거면 다른 업무 못하는 것 아닌가?" → 아누 수동 오케스트레이션의 병목 문제 지적
- "마아트는 소넷이잖아. 다른 방법 없을까?" → 같은 Claude 모델 내 교차검증 한계 지적

**결론:**
- 아누: 오케스트레이터 역할 유지, 기계적 검증(Batch Watchdog/Pre-flight/Integration Test)은 자동화
- 마아트: G2 내부 QC + Gemini 장애 시 폴백으로 역할 축소
- 외부 AI(Gemini/Codex): 인지 편향 차단을 위한 교차검증 도입 결정

**Cycle 5로의 연결**: 이 합의를 구체화하여 Graduated Auto-Gate 3-Layer(L1/L2/L3) 설계가 Cycle 5에서 확정됨.

### 3.5 Cycle 5: 통합 테스트 자동화

**핵심 합의: Graduated Auto-Gate 3-Layer**
- L1 Batch Watchdog: 전팀 .done 수집 추적, 1분 cron, TTL 2시간
- L2 Pre-flight Check: 기계적 충돌 검증, L1 완료 시 자동
- L3 Integration Test: pytest tests/integration/, L2 PASS 시 자동
- FAIL 시에만 아누 판단

**전제 조건:**
- tests/integration/ 통합 테스트 스위트 선행 구축 (현재 2개만 존재)
- dispatch.py에 batch_id 필드 추가
- auto_merge.py에 batch completion check + TTL 추가

**발단**: 제이회장님의 "마아트는 소넷이잖아. 다른 방법 없을까?" + "아누가 다른 업무 못하는 거 아닌가?" 피드백

---

## 4. 3인 병렬 심층 분석 상세 기록

### 4.1 아누 (Claude Opus) 분석

**전체 구조 평가:**
보리스 게이트 시스템(G1/G2/G3)은 기존 보리스 워크플로우, 3문서, 핵미사일 발사코드를 훼손하지 않으면서 그 위에 레벨별 검증 강도를 오버레이한 설계. "생성하는 지능과 검증하는 지능"의 분리가 게이트 단위로 명시된 점은 아누 가이드 근본 원칙(섹션 0)과 정확히 합치. 3 Step Why를 교차 모델 검증에 매핑한 것은 구조적으로 건전. 다만 Cycle 4 누락으로 합의 과정 연속성에 구멍.

**논리적 모순/빈틈 6건:**
1. Cycle 4 누락: "총 사이클 수: 3"이라 명시했으나 실제 5사이클. Cycle 4 제목/내용 없이 "Cycle 4 수정"만 언급.
2. server.py 모듈 소유팀: devops(야누스 1인)가 ~1100줄 소유 비현실적.
3. affected_files 2단계 감지: 머지 시점 감지 후 조치(재구현? 수동 병합?) 미명시.
4. Gemini PR 리뷰 vs 현재 워크플로우: auto_merge.py가 PR 없이 직접 머지 → PR 전환 시 재설계 필요, 로드맵 미반영.
5. G3 Lv.4 전팀 완료 대기: 8팀 병렬 시 최느린 팀이 병목. TTL 초과 시 대기 중 worktree stale 문제.
6. "대형 파일 동시 수정 금지" 운영 규칙: 로키 DA 제안이 기각/채택 기록 없이 소멸.

**실행 불가능한 부분 5건:**
1. gate_instructions.py 미존재 (구현 필요)
2. Codex codex-plugin-cc 미검증 (환각 위험)
3. Gemini GitHub App 미설치 (설치+권한+비용 미확인)
4. auto_merge.py batch_id/TTL 미구현 ("1~2일" 과소 추정 가능)
5. tests/integration/ 스위트 사실상 부재 (2개만, "지속적"은 희망사항)

**누락된 고려사항 7건:**
1. server.py 분할 시 무중단 전환 계획
2. Task ID v2와 batch_id 관계 미정의
3. 로키 역할 과부하 (보안+DA+G2 Lv.4+FAIL 보조)
4. 마아트 폴백 시 검증 품질 차이 (인지 편향 차단 불가)
5. 한정승인과 게이트 시스템 상호작용 미정의
6. dispatch.py 직렬화 lock 구체적 구현 미정
7. 7주 로드맵 팀별 리소스 배분 미계획

**최종 판정: CONDITIONAL**
- Phase 1만 한정승인 → 구현 → 효과 측정 → 재판단

### 4.2 비너스 (Gemini) 분석

**Gemini 통합 실현 가능성:**
- Gemini Code Assist GitHub App은 PR 기반 자동 리뷰에 특화 → "G2 구현 후 Gemini 리뷰" 설계와 기술적 정합
- 제약: 리포지토리 전체 컨텍스트 이해 제한, 보험 도메인 비즈니스 로직 검증 불가, server.py 7600줄 단일 파일 리뷰 품질 저하
- **판정: 조건부. server.py 분할 완료가 선행 조건.**

**교차검증 파이프라인 현실성 3가지 병목:**
1. **레이턴시**: Codex G1 + Gemini G2 직렬 배치 시 Lv.3 기준 20-40분 추가 대기 → 유휴 팀 양산
2. **인지 편향 차단 과대평가**: Claude/Gemini/GPT 동일 학습 데이터 편향 공유. 진정한 교차검증은 AI-인간 간.
3. **폴백 전략 역설**: "마아트 폴백 가능" → "평시에도 마아트로 충분한 것 아닌가?" Gemini 부가가치 미실증.

**보안/프라이버시 리스크:**
- GitHub PR 통한 코드 Google 서버 전송
- 보험 고객 데이터 스키마, 수수료 계산 로직, API 키 패턴 노출 위험
- 금소법/개인정보보호법 외부 전송 문제
- **sanitize 게이트 필수** (미팅에서 PII 마스킹 언급 전혀 없었음)

**누락된 고려사항 4건:**
1. 비용 추정 부재 (Gemini Enterprise + Codex API 월간 비용)
2. 모델 버전 호환성 (Google 모델 업데이트 종속)
3. UI/디자인 교차검증 공백 (프론트엔드 변경의 시각적 검증)
4. Rate Limit (8팀 병렬 PR 시 시간당 제한)

**Graduated Auto-Gate 충돌:**
- G2 Gemini FAIL 시 L2 Pre-flight 동작 미정의

**최종 판정: CONDITIONAL**
- sanitize 게이트 + server.py 분할 선행 + 비용/ROI + Lv.3-4 한정

### 4.3 아틀라스 (Codex) 분석

**Codex 통합 실현 가능성:**
- 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 플러그인 통합은 미구현
- **판정: 기술적 가능, 운영 환경 즉시 적용 불가.**

**G1 설계 게이트 Codex 활용:**
- Lv.3 사전 검증 실현 가능 (`/review` 기능, 설계문서+affected_files 전달)
- 컨텍스트 윈도우 약 258k 토큰 → server.py 단독 분석 가능, 다중 파일 한계
- **위험**: "Codex 사전 검증" 구체적 프로토콜 미정의 (입력/출력/판정기준 없음)
- Lv.4 "Codex + Agent 미팅 만장일치"에서 Codex 신뢰도 교차 확인 방법 불명확

**비용/속도:**
- Codex CLI 자체 무료 (Pro/Plus 포함)
- API 호출 시 토큰 비용 발생
- gpt-5.1-codex-mini 응답 2-5초, 7600줄 전체 분석 10-30초
- Lv.3+ 작업에만 호출 → 일일 3-5건이면 미미

**누락된 고려사항 6건:**
1. API 키 관리: 키 만료 시 G1 전면 블로킹
2. Codex 출력 파싱: 자연어→PASS/FAIL 파서 필요 (`--output-schema`)
3. Codex vs Claude Code 도구 접근: exec sandbox read-only, LSP 불가
4. 모델 버전 갭: gpt-5.1 → gpt-5.3/5.4 fallback 맵 미반영
5. server.py 분할과 시간 충돌: Phase 3 시점에 이미 분할 완료 가능
6. "설계 전 = Codex" 역할 모호: 논리적 일관성 vs 호환성 vs 패턴 적합성 미정의

**최종 판정: CONDITIONAL**
- API 키 정상화 + 검증 프로토콜 명문화 + 모델 업데이트

---

## 5. 참조 자료 위치

### 5.1 미팅 기록
- `/home/jay/workspace/memory/meetings/2026-04-15-cross-verification-fullstack-workflow.md`
  - Cycle 1~3 합의 + Cycle 5 합의 + 기각된 대안 + 로키 DA + 기존 시스템 매핑

### 5.2 아누 가이드
- `/home/jay/workspace/memory/specs/anu-guide.md` (v1.3)
  - 섹션 0: 근본 원칙 (인지적 편향 제어, 생성↔검증 분리)
  - 섹션 2: 작업 기억 시스템 (3문서, 핵미사일, Phase 분리)
  - 섹션 3: 자동 품질 검사 (QC, 셀프체크, 런타임 검증)
  - 섹션 4: 전문 에이전트 (교차 검증 원칙)

### 5.3 기존 인프라 코드
- `/home/jay/workspace/dispatch.py` — 위임 시스템 (gate_instructions 연동 대상)
- `/home/jay/workspace/scripts/worktree_manager.py` — worktree 격리 + 머지 (G3 기반)
- `/home/jay/workspace/hooks/auto-commit.sh` — 자동 커밋 (게이트 독립)
- `/home/jay/workspace/dashboard/server.py` — 분할 대상 (7600줄)
- `/home/jay/workspace/scripts/auto_merge.py` — 자동 머지 (batch_id/TTL 확장 대상)

### 5.4 조직 구조
- `/home/jay/workspace/memory/organization-structure.json`
  - 8팀 CC + 횡단 CR 체제
  - server.py 모듈 소유팀 배정 시 참조

### 5.5 작업 레벨 시스템
- `/home/jay/workspace/memory/specs/work-level-system.md`
  - Lv.0~4 판정 기준
  - 게이트 매트릭스 레벨 기준

### 5.6 제이회장님 핵심 피드백 (이 세션)
- "몇 번이나 수정 요청했는데!!!" — H1/H2 원복 관련
- "이젠 웃음만 나온다 몇번째냐 이게" — 반복 원복 피로
- "sync이전으로 분류되어 있는 리스트는 왜 건들였어???" — 데이터 정합성
- "아누가 통합테스트 트리거면 다른 업무 못하는 거 아닌가?" — Cycle 4→5 전환 계기
- "마아트는 소넷이잖아. 다른 방법 없을까?" — 외부 AI 도입 계기
- "절대 요약하거나 누락해서 내용 줄어들면 안 되고 전체 집대성" — 3문서 작성 지시

---

## 6. 핵심 용어 정리

- **보리스 게이트 시스템**: G1(설계)/G2(구현)/G3(머지) 3개 게이트 × Lv.0-4 차등 검증
- **Graduated Auto-Gate**: L1(Batch Watchdog)/L2(Pre-flight)/L3(Integration Test) 자동화 계층
- **3 Step Why**: 1st Why(구현팀)→2nd Why(교차모델)→3rd Why(적대적검증) 품질 검증
- **affected_files**: task 파일에 명시하는 변경 대상 파일 목록 (겹침 감지용)
- **batch_id**: 병렬 위임 그루핑 식별자 (전팀 완료 감지용)
- **gate_instructions.py**: 레벨별 게이트 지시를 프롬프트에 자동 삽입하는 모듈
- **sanitize 게이트**: 외부 AI 전송 전 PII/비즈니스 로직 마스킹 자동화
- **핵미사일 발사코드**: Context Purge + Checkpointing + 제이회장님 승인 프로토콜
- **TTL**: Time To Live. Batch Watchdog에서 전팀 완료 대기 최대 시간 (2시간)

---

---

## 추가 결정 사항 (2026-04-16)

### MEDIUM 3분류 기준 결정
- **결정일**: 2026-04-16
- **근거**: Agent 미팅 3사이클 전원합의 (9/9)
- **미팅 기록**: `memory/meetings/2026-04-16-gemini-medium-review-criteria.md`
- **참여**: 마르둑, 엔키, 이쉬타르, 나부, 닌기르수, 로키(DA), 마아트(DA), 비너스, 아틀라스

#### 왜 3분류인가
- 제이회장님 지시: "선택사항이면 선택하는 기준이 있어야하고 그 기준에 충족하면 수정을 해야함"
- 기존 "참고 사항"만으로는 MEDIUM 처리가 일관되지 않음
- 카테고리 기반 FIX/SKIP + 나머지 DEFER로 자동화 + 안전장치 확보

#### 왜 점진적 자동화인가
- 아틀라스 제안: 처음부터 자동 분류하면 오분류 위험 높음
- Gemini MEDIUM 오탐률 32-35% (비너스 분석)
- Week 1-2 수동 수집으로 데이터 축적 → 패턴 기반 자동화로 정확도 확보
- 마아트 DA: 오분류율 >30% 시 FIX만 자동화로 축소하는 안전장치

#### 기대효과 수치 목표
- 3개월 후 리뷰 시간 50% 단축 (비너스 제안, 전원 동의)
- MEDIUM 자동 분류 정확도 85%+ (엔키 제안)
- 보고서 "완료" ≠ 실제 미반영 사례 0건 (검증 게이트 도입 목표)

#### 기각된 대안
- A안(전부 자동 기각): 보안 MEDIUM 놓칠 위험 → 로키 반대
- B안(전부 아누 수동): 주당 30-45분 부하 → 나부 반대

### 검증 게이트 (verification-before-completion) 결정
- **결정일**: 2026-04-16
- **근거**: Agent 미팅 4사이클 전원합의 (9/9)
- **미팅 기록**: `memory/meetings/2026-04-16-verification-gate-process.md`

#### 왜 검증 게이트가 필요한가
- task-1841: 보고서 "완료" → 검증하니 7/8 FAIL (코드 미반영)
- task-1828: 보고서 "완료" → 검증하니 3/4 FAIL
- 3문서 체계에 "보고서 내용과 실제 코드 불일치를 잡는 게이트"가 없었음

#### "정상동작"의 정의 (제이회장님 직접 정의, 2026-04-16)
- ~~1. 코드단에서 오류 없다~~ → X (이것만으로 부족)
- **2. 사람이 사용할 때도 문제없이 기능이 정상동작한다** → O (이것이 진짜 기준)

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

#### 실패 사례 (2026-04-15, 이 규칙이 필요한 이유)
- 신호등: grep "borrowed_tasks" → 있음 ✅ → API 호출 → 없음 ❌ (서버 미재시작)
- 정제: knowledge_extractor_v2.py 수정 ✅ → 실행 → 2947개 전체 처리 ❌ (월 필터링 미동작)
- micro-commit: 보고서 "3계층 완료" ✅ → 검증 → 1/4만 적용 ❌

#### 재작업 안전장치
- 재작업 시 L1 자가 검증 재수행 의무 (건너뛰기 금지)
- 재시도 상한 3회 — 3회 초과 시 아누 에스컬레이션 (제이회장님 판단)
- 근거: 마아트 DA 지적 — "재작업 무한 루프 + 루프 탈출 조건 미정의" 위험

#### 기각된 대안
- "마아트 전수 검증만": 마아트 리소스 부하 과다 → 피어리뷰 병행으로 해소
- "검증 없이 보고서 신뢰": 반복 실패로 불가 확인

### Phase 3 진행 상태 업데이트 (2026-04-16 최신)
- Phase 3.1 리서치: ✅ 완료 (task-1860)
- Phase 3.2 sanitize: ✅ 완료 + 검증 PASS (task-1862_a, task-1864)
- Phase 3.3 Codex 통합: ✅ 완료 + 검증 PASS (task-1862_b, task-1864)
- Phase 3.4 Gemini 통합: ✅ 완료 + 검증 PASS (task-1862_c, task-1864) + 미해결 수정 (task-1866)
- Phase 3.5 3 Step Why: ⬜ 미시작
- Phase 3.6 MEDIUM 분류 + HIGH 자동 수정: ⬜ 미시작 (미팅 합의 완료)
- Phase 3.7 CodeGraph 파일럿: 🚀 진행 중 (task-1869, 7팀, 미팅 합의 완료)

### 횡단 완료 항목 (2026-04-16)
- 와치독 안정화: Task ID v2 준수 (task-1867) + .done 경합 버그 수정 (task-1870)
- Task ID 포맷 v2: generate_task_id (task-1853), task-timer (task-1856), 와치독 (task-1867)
- affected_files 파싱 버그 수정 (task-1865)
- 반복 스케줄 8팀 이관, weekly-report 기간 수정 (task-1868)
- codex-plugin-cc 설치 + ChatGPT Plus 인증
- codex_gate_check.py Codex CC 플러그인 연동 전환 (task-1941): companion→exec→maat 3단계 캐스케이드 + 마아트 폴백 강화 + stdin 전달(Errno 7 방지)

### Gemini PR 리뷰 강제 적용 (task-1970, 2026-04-20)

#### 발견 경위
- task-1968에서 Gemini 리뷰 시스템의 구조적 허점 6건(A~F) 발견
- 파서가 Gemini 실제 포맷(`![high](URL)`)을 감지하지 못하고, 타임아웃 시 무조건 머지, QC/G3에 교차검증이 없어 팀장의 "High 0건" 거짓 보고가 시스템을 통과하는 구조적 결함

#### 해결 방법
- A. 타임아웃 차단: `blocked_by_timeout` 상태 도입
- B. 파서 패턴 수정: Gemini 실제 img alt text + SVG URL 정규식 추가
- C. 파싱 실패 기본값 해소: B 수정으로 파싱 성공률 100%
- D. 기각 사유 필수: `[DISMISS]` 포맷 + "사유 없는 기각은 QC FAIL"
- E. QC/G3 교차검증 추가: gemini_review_check verifier + g3 check_gemini_review
- F. collect_mode=False 기본값: 자동 수정 루프 활성화

#### 설계 판단 근거
- 3중 방어 레이어(자동 방어 + QC 방어 + 거버넌스 방어)로 허점 원천 차단
- 20건 신규 테스트 + 기존 35건 테스트 전체 PASS
- 기각 사유 히스토리 보존으로 패턴 학습 데이터 축적 가능

### .done 자동 검증 게이트 (task-1972, 2026-04-20)

#### 발견 경위
- 에이전트 미팅 전수조사 결과 적발률 34% (47건 중 16건) — 코드가 실제로 존재하지 않는데 완료 보고된 사례 구조적 문제

#### 해결 방법
- 생산자 게이트: signature_check verifier — task 파일의 `## 완료 시그니처` 섹션에서 grep/pytest 패턴 파싱 후 자동 실행
- 소비자 게이트: verify_done.py — .done 생성 후 재검증, 실패 시 `.done.rejected` 생성
- 이중 검증으로 거짓 완료 원천 차단

#### 설계 판단 근거
- Lv.1-2는 grep만, Lv.3+는 grep+pytest 검증으로 레벨별 차등
- 시그니처 없는 기존 task는 SKIP (하위 호환 유지)
- 15건 테스트 전체 PASS + 자기 시그니처 검증 4/4 PASS

### Chrome DevTools MCP 통합 (task-1984, 2026-04-20)

#### 발견 경위
- L1 스모크테스트에서 Playwright만으로는 Lighthouse 성능 감사, 네트워크 분석, 콘솔 에러 확인 등 DevTools 전용 기능을 활용할 수 없는 한계

#### 해결 방법
- `~/.claude/settings.json`에 chrome-devtools-mcp 서버 headless 모드 추가
- 외부 데이터 전송 차단 플래그 적용 (`--usageStatistics false`, `--performanceCrux false`)
- DIRECT-WORKFLOW.md Step 4.8에 6개 핵심 도구 안내 추가

#### 설계 판단 근거
- 기존 Playwright MCP와 충돌 없이 공존 확인
- headless 모드로 서버 환경에서 안정 실행
- 선택적 활용 (필수 아닌 심층 검증용) — L1 스모크테스트의 깊이 확장

### 3문서 2유형 체계 결정
- **결정일**: 2026-04-16
- **근거**: Agent 미팅 2사이클 전원합의 (task-1872)
- **미팅 기록**: `memory/meetings/2026-04-16-3docs-two-types.md`

#### 문서 체계
- 시스템 3문서: 기존 `memory/plans/<프로젝트>/` 유지
- 작업 3문서: `memory/plans/tasks/{task_id}/` 신규
- YAML: `scope: system | task` 필드 필수 추가
- 아카이브: 완료 후 `memory/plans/tasks/archived/{task_id}/`로 이동

#### 코드 실행단 설계 (12개 파일, ~327 라인)
1. dispatch.py: `_create_task_docs()` 함수 → Lv.3+ 자동 생성 (+45줄)
2. team_prompts.py: Lv.3+ 프롬프트에 작업 3문서 경로 삽입 (+20줄)
3. DIRECT-WORKFLOW.md: Step 2.3 "작업 3문서 초기화" (+12줄)
4. qc_verify.py: `three_docs_check` verifier 신규 (~80줄)
5. verification-before-completion: 3문서 완성 검증 (+25줄)
6. nuclear-approval: 작업 3문서 검증 (+10줄)
7. 템플릿: `prompts/templates/task-docs/` 3파일

#### 구현 순서
Phase 1(스키마) → Phase 2(템플릿+dispatch) → Phase 3(prompts+workflow) → Phase 4(QC verifier) → Phase 5(검증 연동) → Phase 6(테스트)

#### 쟁점 해소
- 경로 분리: 하위 분기 방식 (기존 경로 하위호환 유지)
- YAML 필드명: `scope` 채택 (기존 네이밍 컨벤션 일관성)
- 워크플로우 삽입: 2단계 접근 (Step 2.3 초기화 + 완료 시 검증)

### CodeGraph 도입 결정
- **결정일**: 2026-04-16
- **근거**: Agent 미팅 2사이클 전원합의 (10/10)
- **미팅 기록**: `memory/meetings/2026-04-16-codegraph-adoption.md`
- Phase 1: code-review-graph vs 자체 AST 스크립트 2주 파일럿 비교
- Phase 2: 승자 본 도입 + TS/React 검증 + CodeGraphContext MCP
- 로키 DA 지적 수용: 자체 스크립트 폴백으로 외부 의존성 탈출구 확보

### 2026-04-16 보고서≠구현 원인분석 미팅
- 참가자: 9명 (5팀 전체 + 로키/마아트/비너스/아틀라스)
- 상세: memory/meetings/2026-04-16-report-impl-gap-analysis.md
- 합의: Tier 1~3 방지책 채택
- 근본 원인 4가지 도출: Edit 조용한 실패, 서브에이전트 격리, selfQC 맹점, 대형 파일 실패

### 로키 역할 과부하 검토 (task-1908, 2026-04-16)

> 근거: 아누 3인 분석에서 "누락된 고려사항 #3"으로 지적 (섹션 4.1)

#### 현재 역할 4건
1. **보안팀장**: 보안 감사/리뷰 수행. security 레벨 QC에서 필수 참여.
2. **DA (Devil's Advocate)**: Agent 미팅에서 반론/비판적 분석. 모든 Cycle에서 활동.
3. **G2 Lv.4 레드팀**: 보리스 게이트 G2에서 Lv.4 작업의 적대적 검증 수행.
4. **FAIL 보조**: Graduated Auto-Gate FAIL 시 아누와 함께 원인 분석 보조.

#### 역할 충돌 분석
- **보안팀장 × DA**: 충돌 낮음. DA 역할은 미팅 시에만 활성화되며, 보안 관점이 DA 반론에 시너지.
- **보안팀장 × G2 Lv.4 레드팀**: 충돌 중간. Lv.4 작업이 빈번하면 보안 감사와 시간 경합. 현재 Lv.4 작업은 주 1-2건으로 관리 가능.
- **DA × G2 Lv.4 레드팀**: 충돌 낮음. DA는 설계 단계(G1), 레드팀은 구현 단계(G2)로 시점 분리.
- **FAIL 보조**: 비정기적 역할. FAIL 발생 시에만 활성화되므로 상시 부하 아님.

#### 결론 및 권고
- **현시점에서는 역할 분리 불필요**: Lv.4 작업이 주 1-2건이고, FAIL 보조는 비정기적이므로 과부하 위험 낮음.
- **주의 시점**: server.py 분할 완료 후 8팀 병렬 작업이 본격화되면 G2 Lv.4 레드팀 빈도 증가 가능. 그 시점에 재평가 권고.
- **대안 (필요 시)**: FAIL 보조 역할을 마아트에게 이관 (마아트는 G2 QC 담당으로 문맥 보유). 보안팀장 + DA + G2 Lv.4 레드팀은 로키 고유 역할로 유지.

### 2026-04-20 dispatch.py 봇 Lazy Start 문제 발견 및 해결 (task-1971)

#### 발견 경위
- 서버/cokacdir 재부팅 후 dispatch.py로 작업 위임 시 봇이 메시지를 수신하지 못하는 현상 발견
- cokacdir는 정상 가동, cron 등록 성공, 스케줄 실행됨
- 그러나 봇의 Claude 세션이 lazy start(첫 수동 메시지 수신 시에만 시작)
- cron 메시지가 Claude 세션 시작 전에 도착하면 소실

#### 근본 원인
- cokacdir v0.4.96은 봇 세션을 lazy start함
- 텔레그램 메시지 수신은 되지만, Claude 프로세스가 떠있지 않으면 처리 불가
- 서버 재부팅 후 첫 dispatch가 실패하는 원인

#### 해결 방법
- dispatch 전 `ps aux`로 봇의 Claude 프로세스 존재 확인
- 프로세스 미감지 시 빈 ping 메시지(".")로 세션 기동 유도
- wake-up 후 polling으로 세션 시작 대기 (최대 25초)
- 실패 시 dispatch 딜레이를 30초로 확대하여 자연 기동 대기

#### 설계 판단 근거
- wake-up 메시지로 "."(마침표 1자)를 사용 — 봇이 수신해도 무의미한 입력으로 실제 작업에 영향 없음
- 딜레이 확대(10초→30초)는 보수적 접근 — wake-up 실패 시에도 자연 기동을 기다려 작업 손실 최소화
- 기존 dispatch 로직 변경 없음 — wake-up 로직은 cokacdir --cron 호출 직전에 삽입되어 기존 흐름을 방해하지 않음

*이 맥락 노트는 모든 결정의 근거, 미팅 진화 과정, 3인 분석 상세, 참조 자료 위치를 빠짐없이 기록하여 미래 세션이 맥락을 완전히 복원할 수 있도록 한다.*