@didim365/agent-cli-core 0.1.0

package/dist/docs/00_project/ai_adapter/todolist/phase3_provider_extension_todolist.md

@@ -0,0 +1,1382 @@
+# Phase 3: 프로바이더 확장 및 통합
+
+> 기간: 4-6주 | 상태: ⏳ 대기 | 의존성: Phase 2 완료 **v0.8** - 리뷰 3건 반영
+> (중복 등록 안전성, 런타임 wiring 테스트 타깃, --provider 옵션 명확화)
+
+## System Prompt
+
+Always follow TDD principles. For each provider adapter: write failing tests for
+message conversion, stream handling, and error mapping first. Implement minimum
+code to pass. Ensure cross-provider compatibility through integration tests.
+
+---
+
+# PHASE OVERVIEW
+
+## 설계서 참조 (Design Document References)
+
+| 설계서                                                                                | 관련 섹션                                                                            | 참조 목적                             |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------- |
+| [03-technical-design.md](../03-technical-design.md)                                   | §3.3.4-3.3.6 Claude 어댑터/변환기, §3.3.7-3.3.8 OpenAI 어댑터/변환기, §3.4 vLLM 확장 | 각 프로바이더별 어댑터 구현 상세      |
+| [04-integration-design.md](../04-integration-design.md)                               | §4.2 연동 아키텍처, §4.3 공통 타입 시스템                                            | DidimAIStudio 연동 시 프로바이더 통합 |
+| [05-implementation-plan.md](../05-implementation-plan.md)                             | §5.4 Phase 3 상세, §5.5 테스트 및 검증                                               | 마일스톤별 상세 계획, 검증 기준       |
+| [phase3_handoff.md](./phase3_handoff.md)                                              | 연기 항목 카탈로그, messageInspectors 상세, 잔여 의존성 현황                         | Phase 2 → 3 연기 항목 추적            |
+| [EventType 전환 결과서](../working_history/phase2_tradeoff_EventType전환_20260208.md) | 16개 파일 전환, 핸드오프 Critical #1/#2 해소                                         | EventType 전환 완료 근거              |
+
+## 목표
+
+- 🆕 **Phase 2 연기 항목 해소**: Gemini 내부 리팩토링 (파일 이동, 텔레메트리,
+  Agent 결합 해소)
+- Claude 어댑터/변환기 구현
+- OpenAI 어댑터/변환기 구현
+- OpenAI-Compatible(vLLM/sLM) 어댑터 템플릿
+- 통합 테스트 및 문서화
+
+## ⚡ 실행 순서 변경 안내 (2026-02-10)
+
+**원래 계획**: M3.0 → M3.1 → M3.2 → M3.3 → M3.4 → M3.5
+
+**변경된 순서**: M3.0 ✅ → M3.1 ✅ → M3.2 ✅ → **M3.4.A (부분 선행)** → M3.3 →
+M3.4.B (잔여) → M3.5
+
+**변경 사유**:
+
+- M3.4의 90%는 M3.3 없이 진행 가능 (Gemini/Claude/OpenAI 3개 프로바이더로 충분)
+- 3-provider 통합 테스트를 조기에 수행하여 버그 조기 발견
+- M3.3 작업 전에 integration contract 확보
+- 성능 baseline 조기 확립하여 M3.3 영향도 측정 가능
+
+**M3.4.A 선행 범위** (M3.3 독립):
+
+- 3.4.1 전체 — 멀티 프로바이더 통합 테스트 (4개)
+- 3.4.2 중 3개 — Gemini/Claude/OpenAI E2E 테스트 (vLLM 제외)
+- 3.4.3 전체 — 성능 회귀 테스트 (3-provider baseline)
+- 3.4.4 전체 — 문서 업데이트 (vLLM은 placeholder)
+- 3.4.5 전체 — 안정화 작업 (6개)
+
+**M3.4.B 잔여 범위** (M3.3 의존):
+
+- 3.4.2.4 — vLLM E2E 테스트
+- 3.4.4 — vLLM 문서 상세화 (placeholder → full docs)
+
+## 전제 조건
+
+- [x] Phase 2 모든 Milestone 완료 (M2.0~M2.6 + ETC)
+- [x] GeminiAdapter 동등성 검증 완료
+- [x] 기능 플래그 동작 확인
+- [x] 🆕 EventType 전환 완료 (M2.연기 — GeminiEventType→LlmEventType, 16개 파일)
+- [ ] Phase 3 핸드오프 문서 검토 완료
+
+## Phase 2 연기 항목 추적 (핸드오프 기준)
+
+| #    | 핸드오프 항목                             | Priority | 상태        | 해소 위치                    |
+| ---- | ----------------------------------------- | -------- | ----------- | ---------------------------- |
+| 1    | `client.ts` GeminiEventType 참조 정리     | Critical | ✅ 해소됨   | M2.연기 (EventType 전환)     |
+| 2    | `turn.ts` 이벤트 생성점 전환              | Critical | ✅ 해소됨   | M2.연기 (EventType 전환)     |
+| 3    | `chat.ts` → `providers/gemini/chat.ts`    | Critical | ✅ 해소됨   | M3.0.1 (`f56845dab`)         |
+| 4    | `turn.ts` → `providers/gemini/turn.ts`    | Critical | ✅ 해소됨   | M3.0.1 (`f56845dab`)         |
+| 5    | `messageInspectors` 마이그레이션 (4파일)  | High     | ✅ 해소됨   | M3.0.2                       |
+| 6    | `loggingContentGenerator` 텔레메트리 변환 | High     | ✅ 해소됨   | M3.0.3 (`6a09c831d`)         |
+| 7    | `telemetry/semantic.ts` Gemini 결합 해소  | High     | ✅ 해소됨   | M3.0.3 (`6a09c831d`)         |
+| 8    | AuthType 처리 통합 (2.3.1.8)              | Medium   | ⬜ → M3.1+  | 신규 프로바이더 구현 시 함께 |
+| 9    | 성능 검증 (응답 지연/메모리/스트리밍)     | Medium   | ⬜ → M3.4   | M3.4.3                       |
+| 10   | E2E 테스트 통과 검증                      | Medium   | ✅ 해소됨   | M3.4.2 (12 tests PASS)       |
+| 11   | `geminiTypeConversion.ts` 브릿지 정리     | Medium   | ✅ 해소됨   | M3.0.4                       |
+| 12   | `telemetry/sdk.ts` 시그널 핸들러 누수     | Medium   | ✅ 해소됨   | M3.0.3 (`6a09c831d`)         |
+| M2.7 | Agent/Telemetry 결합 해소                 | Watch    | ✅ 해소됨   | M3.0.3 (`6a09c831d`)         |
+| 신규 | 런타임 실행 경로 연결 (ProviderFactory)   | High     | ✅ 해소됨   | M3.0.5                       |
+| 신규 | root index.ts re-export 회귀 테스트       | Medium   | ✅ 해소됨   | M3.0.1.5 (`f56845dab`)       |
+| 신규 | 프로바이더별 registry.register() 작업     | High     | ⬜ → M3.1~3 | M3.1.0.2/M3.2.0.2/M3.3.0.1   |
+| 신규 | SDK 의존성 설치 (@anthropic-ai, openai)   | Low      | ⬜ → M3.1~2 | M3.1.0.1/M3.2.0.1            |
+
+## 산출물
+
+```
+packages/core/src/providers/
+├── gemini/
+│   ├── chat.ts               # 🆕 geminiChat.ts 물리적 이동 (M3.0)
+│   └── turn.ts               # 🆕 Gemini 특화 Turn 이동 (M3.0)
+│
+├── claude/
+│   ├── adapter.ts
+│   ├── converter.ts
+│   ├── eventMapper.ts
+│   └── types.ts
+├── openai/
+│   ├── adapter.ts
+│   ├── converter.ts
+│   ├── eventMapper.ts
+│   └── types.ts
+└── openai-compatible/
+    ├── adapter.ts
+    ├── converter.ts
+    └── types.ts         # eventMapper 선택적 (OpenAI 호환)
+```
+
+---
+
+# 3-STAGE WORK PROCESS (사전작업/본작업/사후작업)
+
+각 Milestone 작업은 다음 3단계로 진행:
+
+## 1️⃣ 사전작업 (Pre-work)
+
+- [ ] 작업 개요 파악: 현재 Milestone 목표 및 세부 작업 확인
+- [ ] 이전 작업 리뷰: Phase 2 완료 확인 및 작업 결과서 확인 (`working_history/`
+      디렉토리)
+- [ ] 이슈 파악: 이전 작업에서 전달된 이슈 및 Open Questions 확인
+- [ ] 설계서 참조: 관련 설계 문서 검토 (03-technical-design.md,
+      04-integration-design.md 등)
+
+## 2️⃣ 본작업 (Main work) - TDD 사이클
+
+- [ ] **Red**: 실패하는 테스트 작성
+- [ ] **Green**: 최소한의 코드로 테스트 통과
+- [ ] **Refactor**: 코드 개선 (테스트 통과 유지)
+- [ ] 체크리스트 업데이트: 작업 완료 시 ✅ 표시
+
+## 3️⃣ 사후작업 (Post-work)
+
+- [ ] 체크리스트 최종 확인: 해당 Milestone 모든 항목 완료 확인
+- [ ] 작업 결과서 작성: `working_history/Phase3_{Milestone}_{작업일자}.md`
+- [ ] 커밋: 변경사항 커밋 및 커밋 ID 기록
+- [ ] 이슈 전달: 다음 작업에 전달할 이슈 문서화
+
+### 작업 결과서 템플릿
+
+- 경로: `docs/ai_adapter/template/03_work_result_report_template.md`
+
+---
+
+# M3.0: 🆕 Phase 2 연기 항목 해소 — Gemini 내부 리팩토링 (3-5일)
+
+> 📚 **참조**: [phase3_handoff.md](./phase3_handoff.md) (연기 항목 카탈로그),
+> [Phase2 ETC 결과서](../working_history/Phase2_ETC_연기작업정리_20260208.md),
+> [EventType 전환 결과서](../working_history/phase2_tradeoff_EventType전환_20260208.md)
+
+## 목표
+
+Phase 2에서 연기된 Gemini 내부 리팩토링 항목을 해소하여 신규 프로바이더 추가
+기반 확보
+
+## 배경
+
+Phase 2 M2.0~M2.6에서 타입 시스템 독립화를 완료했으나, 파일 물리적
+이동/텔레메트리 결합 해소/Agent 레이어 전환 등은 대규모 동작 변경을 수반하여
+Phase 3으로 연기됨. M2.연기에서 EventType 전환(Critical #1, #2)은 이미 해소됨.
+
+## 사전 결정 필요 사항 (Open Questions)
+
+M3.0 착수 전 다음 Open Question의 잠정 결정 권장:
+
+| OQ  | 질문                                       | 영향 범위     | 잠정 방안                                                        |
+| --- | ------------------------------------------ | ------------- | ---------------------------------------------------------------- |
+| Q5  | LocalAgentExecutor의 신규 인터페이스 형태? | 3.0.3.3       | AgentChat 추상 인터페이스 도입 (GeminiChat을 구현체로)           |
+| Q6  | Telemetry usage 표준 스키마 정의?          | 3.0.3.4       | LlmTokenUsage (필수 3필드) 유지, SDK 타입은 변환                 |
+| Q7  | CLI `--provider` 옵션 노출 여부?           | 3.0.5.5, M3.4 | 잠정: 환경변수(`LLM_PROVIDER`)로 충분. CLI 옵션은 M3.4 시점 결정 |
+
+⚠️ 3.0.1~3.0.2, 3.0.4, 3.0.5는 Q5/Q6 무관하게 착수 가능. 3.0.3.3/3.0.3.4만 해당.
+⚠️ Q7은 M3.0.5.5 우선순위 표의 1순위(명시적 provider 인자)가 내부 API 수준임을
+전제. CLI 옵션 추가는 별도 결정.
+
+## 작업 항목
+
+### 3.0.1 Gemini 전용 파일 물리적 이동 (핸드오프 Critical #3, #4)
+
+| ID      | 작업                                                   | 상태 | 테스트 파일                        | 비고                                                                                                                                    |
+| ------- | ------------------------------------------------------ | ---- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| 3.0.1.1 | `core/geminiChat.ts` → `providers/gemini/chat.ts` 이동 | ✅   | 기존 geminiChat.test.ts            | 999라인, re-export로 하위 호환. import 변경 대상 13개 파일                                                                              |
+| 3.0.1.2 | `core/turn.ts` 전체 → `providers/gemini/turn.ts` 이동  | ✅   | 기존 turn.test.ts                  | 324라인, Turn 클래스 전체가 Gemini-specific (GeminiChat 생성자 의존). re-export로 하위 호환. import 변경 대상 10개 파일                 |
+| 3.0.1.3 | 기존 import 경로 re-export 하위 호환성 유지            | ✅   | 기존 테스트 100% 통과              | M2.0 re-export 패턴 재활용                                                                                                              |
+| 3.0.1.4 | core/index.ts export 정리                              | ✅   | `providers/gemini/exports.test.ts` | core/exports.test.ts는 미존재, gemini/ 내 파일 참조                                                                                     |
+| 3.0.1.5 | root `index.ts` re-export 회귀 테스트 추가             | ✅   | `index.test.ts`                    | 7개 회귀 테스트 추가 완료. GeminiChat, StreamEventType, InvalidStreamError, Turn, CompressionStatus, LlmEventType, GeminiEventType 검증 |
+
+**Tidy First 체크리스트**:
+
+- [x] 모든 변경이 순수 구조적 (동작 변경 없음)
+- [x] 각 이동마다 테스트 실행하여 회귀 확인
+- [x] 커밋 메시지에 `[STRUCTURAL]` 태그
+
+### 3.0.2 messageInspectors 마이그레이션 (핸드오프 High #5)
+
+| ID      | 작업                                                                                            | 상태 | 테스트 파일                    | 비고                                                          |
+| ------- | ----------------------------------------------------------------------------------------------- | ---- | ------------------------------ | ------------------------------------------------------------- |
+| 3.0.2.1 | `loopDetectionService.ts` — `isFunctionCall/Response` → `isToolCallMessage/isToolResultMessage` | ✅   | `loopDetectionService.test.ts` | L408,416,437 convertContentToLlmMessage 브릿지 사용           |
+| 3.0.2.2 | `geminiChat.ts` — `isFunctionResponse` 전환                                                     | ✅   | `geminiChat.test.ts`           | chat.ts 이동(3.0.1.1)과 연계, convertContentToLlmMessage 사용 |
+| 3.0.2.3 | `utils/editCorrector.ts` — `isFunctionCall/Response` 전환                                       | ✅   | `editCorrector.test.ts`        | convertContentToLlmMessage 브릿지 사용                        |
+| 3.0.2.4 | `utils/nextSpeakerChecker.ts` — `isFunctionResponse` 전환                                       | ✅   | `nextSpeakerChecker.test.ts`   | convertContentToLlmMessage 브릿지 사용                        |
+
+**대체 함수** (M2.6에서 구현 완료):
+
+- `isToolCallMessage(message: LlmMessage)` — `src/utils/llmUtils.ts:80`
+- `isToolResultMessage(message: LlmMessage)` — `src/utils/llmUtils.ts:92`
+
+⚠️ **주의**: 단순 함수 교체가 아님. 기존 함수는 `Content` 타입, 대체 함수는
+`LlmMessage` 타입. 각 사용처에서 `Content` → `LlmMessage` 타입 전환이 선행되어야
+함.
+
+### 3.0.3 텔레메트리/Agent 레이어 독립화 (핸드오프 High #6, #7 + M2.7 + Medium #12)
+
+| ID      | 작업                                                                        | 상태 | 테스트 파일                                        | 비고                                                                                      |
+| ------- | --------------------------------------------------------------------------- | ---- | -------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| 3.0.3.1 | `loggingContentGenerator.ts` — @google/genai import 제거                    | ✅   | `loggingContentGenerator.test.ts`                  | 11개 SDK 타입 import → 0. contentGenerator.ts re-export 경유 + telemetry 로컬 타입        |
+| 3.0.3.2 | `telemetry/semantic.ts` — Part/Content/Candidate 타입 독립화                | ✅   | `semantic.test.ts`                                 | 6개 로컬 타입 + GeminiFinishReason const 객체. @google/genai 완전 제거                    |
+| 3.0.3.3 | `LocalAgentExecutor` — GeminiChat 직접 결합 해소 (M2.7)                     | ✅   | `local-executor.test.ts`                           | Q5 잠정 방안 적용: AgentChatSession 인터페이스 + ChatSessionFactory 타입 도입             |
+| 3.0.3.4 | `telemetry/types.ts` — `GenerateContentResponseUsageMetadata` 독립화 (M2.7) | ✅   | `telemetry/sdk.test.ts` (types 전용 테스트 미존재) | TelemetryUsageMetadata + TelemetryGenerateConfig 로컬 인터페이스. @google/genai 완전 제거 |
+| 3.0.3.5 | `telemetry/sdk.ts` — SIGTERM/SIGINT 시그널 핸들러 누수 수정 (핸드오프 #12)  | ✅   | `telemetry/sdk.test.ts`                            | named handler + removeListener in shutdown. 신규 테스트 2건                               |
+
+### 3.0.4 변환 브릿지 정리 (핸드오프 Medium #11)
+
+| ID      | 작업                                                                 | 상태 | 테스트 파일                    | 비고                                                     |
+| ------- | -------------------------------------------------------------------- | ---- | ------------------------------ | -------------------------------------------------------- |
+| 3.0.4.1 | `geminiTypeConversion.ts` 브릿지 사용처 확인                         | ✅   | N/A (분석)                     | 6개 사이트, 5개 함수 — 모두 Gemini SDK 타입 입력         |
+| 3.0.4.2 | `providers/gemini/typeConversion.ts`로 이동                          | ✅   | 관련 테스트 파일               | 6개 import 전환 + index.ts export 추가                   |
+| 3.0.4.3 | `utils/geminiTypeConversion.ts` @deprecated + messageInspectors 삭제 | ✅   | `geminiTypeConversion.test.ts` | re-export shim 유지, messageInspectors.ts dead code 삭제 |
+
+### 3.0.5 런타임 실행 경로 연결 (리뷰 #1 반영)
+
+| ID      | 작업                                                                    | 상태 | 테스트 파일                                     | 비고                                                                                                |
+| ------- | ----------------------------------------------------------------------- | ---- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| 3.0.5.1 | `contentGenerator.ts` — `createContentGenerator()` 프로바이더 분기 추가 | ✅   | `contentGenerator.multiProvider.test.ts`        | 멀티 프로바이더 분기 + `wrapAdapterAsGenerator()` 추가                                              |
+| 3.0.5.2 | `ProviderFactory` → 런타임 CLI 경로 통합                                | ✅   | `contentGenerator.multiProvider.test.ts`        | `ProviderFactory.create()` 호출이 contentGenerator에서 런타임 도달 확인 (시나리오 4, 5)             |
+| 3.0.5.3 | `ENABLE_MULTI_PROVIDER` 플래그 분기 확장 및 검증                        | ✅   | `contentGenerator.multiProvider.test.ts`        | off→레거시(시나리오 1,2), on+Gemini→fall-through(시나리오 3,6,7), on+비Gemini→Factory(시나리오 4,5) |
+| 3.0.5.4 | `ProviderRegistry`에 Gemini 어댑터 팩토리 등록 부트스트랩 구현          | ✅   | `bootstrap.test.ts` (7개)                       | `has()` 가드 패턴 채택. `bootstrapGeminiProvider()` in `providers/gemini/bootstrap.ts`              |
+| 3.0.5.5 | 프로바이더 선택 우선순위 통합 및 회귀 테스트                            | ✅   | `contentGenerator.multiProvider.test.ts` (10개) | 7개 회귀 시나리오 전수 통과 + 3개 추가 (llm 위임, 레거시 throw, 부트스트랩 멱등)                    |
+
+⚠️ **주의**: 이 작업 없이는 신규 프로바이더 어댑터(M3.1~M3.3)를 구현해도
+런타임에서 도달 불가. `createContentGenerator()` (contentGenerator.ts:167-259,
+GoogleGenAI 생성: L235)가 `new GoogleGenAI()` 하드코딩.
+`ProviderFactory`/`ProviderSelector`는 테스트에서만 사용되며 런타임 경로 미연결.
+`ENABLE_MULTI_PROVIDER` 플래그는 현재 `adapterBridge.ts`에서만 제어
+(GeminiAdapter 래핑 여부)하며, contentGenerator의 프로바이더 선택에는 관여하지
+않음.
+
+**레지스트리 부트스트랩 설계** (3.0.5.4):
+
+현재 `ProviderRegistry`는 인프라만 존재하고 런타임에서 `register()` 호출이 없음.
+`factory.create('gemini', config)` 호출 시 `PROVIDER_NOT_FOUND` 에러 발생.
+
+**중복 등록 안전성**: `registry.register()` 는 동일 이름 중복 시 예외를 던짐
+(registry.ts:81, `has() && !force` 가드). 부트스트랩이 여러 번 호출될 수 있는
+시나리오(HMR, 테스트 재초기화, Agent 재생성 등)에 대비해야 함.
+
+구현 방안 (택 1):
+
+1. **`has()` 가드 패턴** (권장): 부트스트랩에서 `if (!registry.has('gemini'))`
+   체크 후 등록
+2. **`force: true` 패턴**: `register('gemini', factory, { force: true })` — 항상
+   덮어쓰기
+3. **1회 초기화 보장**: 부트스트랩 함수에 `initialized` 플래그로 중복 호출 방지
+
+초기화 위치 후보:
+
+- `createContentGenerator()` 진입부 (런타임 경로 확실, 단 호출마다 실행)
+- 앱 부트스트랩 (`packages/cli` 초기화 시점, 1회 보장)
+- lazy init (첫 `factory.create()` 호출 시 자동 등록)
+
+```
+// 권장 패턴 (has() 가드)
+function bootstrapProviders(registry: ProviderRegistry): void {
+  if (!registry.has('gemini')) {
+    registry.register('gemini', (config) => new GeminiAdapter(config, modelsApi));
+  }
+}
+```
+
+M3.1~M3.3에서도 각 프로바이더 등록 작업이 필수 (아래 각 마일스톤에 명시).
+M3.1.0.2/M3.2.0.2/M3.3.0.1 모두 동일한 `has()` 가드 패턴 적용.
+
+**프로바이더 선택 우선순위 계약** (3.0.5.5):
+
+현재 2개 분리된 시스템이 상충:
+
+- `contentGenerator.ts`: authType-only 분기 (L204-248), LLM_PROVIDER 미참조
+- `providerSelector.ts`: LLM_PROVIDER > authType > env key 순서
+- `getProviderFromConfig()`: explicit provider > authType > LLM_PROVIDER (또
+  다른 순서)
+
+통합 후 최종 우선순위:
+
+| 순위 | 결정 소스                       | 예시                     | 비고                                                          |
+| ---- | ------------------------------- | ------------------------ | ------------------------------------------------------------- |
+| 1    | 명시적 provider 인자 (내부 API) | `providerName: 'claude'` | 프로그래밍 API 수준. CLI `--provider` 옵션은 미존재 — Q7 참조 |
+| 2    | `LLM_PROVIDER` 환경변수         | `LLM_PROVIDER=openai`    | 환경 기반 선택                                                |
+| 3    | `authType` (Gemini 한정)        | `AuthType.USE_VERTEX_AI` | Gemini 내부 경로 분기                                         |
+| 4    | API Key 환경변수 존재 여부      | `GEMINI_API_KEY` 존재    | 자동 감지 폴백                                                |
+| 5    | 기본값 (Gemini)                 | 모든 미설정 시           | 하위 호환                                                     |
+
+> ⚠️ **Q7**: CLI `--provider` 옵션 추가 여부. 현재
+> `packages/cli/src/config/config.ts`에 해당 옵션이 없음. 1순위는 내부
+> `getProviderFromConfig()`의 프로그래밍 인자로만 존재. CLI 옵션 노출은
+> M3.4(통합/문서) 시점에 결정 가능 — 환경변수(`LLM_PROVIDER`)만으로 충분할 수
+> 있음.
+
+회귀 테스트 시나리오:
+
+| ENABLE_MULTI_PROVIDER | LLM_PROVIDER | authType      | 기대 결과 | 테스트                        |
+| --------------------- | ------------ | ------------- | --------- | ----------------------------- |
+| false                 | (미설정)     | USE_GEMINI    | Gemini    | ✅                            |
+| false                 | claude       | USE_GEMINI    | Gemini    | ✅ (플래그 off → 레거시 경로) |
+| true                  | (미설정)     | USE_GEMINI    | Gemini    | ✅                            |
+| true                  | claude       | (미설정)      | Claude    | ✅                            |
+| true                  | openai       | USE_VERTEX_AI | OpenAI    | ✅ (LLM_PROVIDER 우선)        |
+| true                  | (미설정)     | USE_VERTEX_AI | Gemini    | ✅                            |
+| true                  | (미설정)     | (미설정)      | Gemini    | ✅ (기본값 폴백)              |
+
+**검증 기준**:
+
+- [x] `core/geminiChat.ts` → `providers/gemini/chat.ts` 이동 완료
+- [x] `core/turn.ts` Gemini 특화 분리 완료
+- [x] root `index.ts` re-export 회귀 테스트 통과 (CLI import 호환성)
+- [x] messageInspectors 4개 파일 마이그레이션 완료
+- [x] 텔레메트리 레이어 @google/genai 독립화
+- [x] LocalAgentExecutor GeminiChat 직접 결합 해소
+- [x] `createContentGenerator()` → ProviderFactory 런타임 연결 완료
+- [x] `ENABLE_MULTI_PROVIDER=true` 시 ProviderFactory 경로 도달 검증
+- [x] `registry.register('gemini', ...)` 부트스트랩 동작 확인
+- [x] 부트스트랩 중복 호출 시 예외 미발생 (has() 가드 또는 force 정책)
+- [x] 프로바이더 선택 우선순위 7개 회귀 시나리오 전수 통과
+- [x] 모든 기존 테스트 100% 통과
+- [x] TypeScript 컴파일 에러 없음
+
+---
+
+# M3.1: Claude 어댑터/변환기 구현 (4-5일)
+
+> 📚 **설계서 참조**:
+> [03-technical-design.md §3.3.4 Claude 어댑터](../03-technical-design.md#334-claude-어댑터),
+> [§3.3.5 Claude 타입 변환기](../03-technical-design.md#335-claude-타입-변환기-추가),
+> [§3.3.6 Claude 어댑터 구현](../03-technical-design.md#336-claude-어댑터-추가),
+> [05-implementation-plan.md §M3.1](../05-implementation-plan.md#m31-claude-어댑터변환기-구현-4-5일)
+
+## 목표
+
+Claude 메시지/툴/스트림 변환기 구현
+
+## Claude 특화 고려사항
+
+- System 메시지 분리 필요 (별도 파라미터)
+- 이미지는 base64 필수 (URL 직접 지원 안함)
+- 스트리밍 tool delta 합성 필요
+- `content_block_delta` 이벤트 처리
+
+## 작업 항목
+
+### 3.1.0 사전 준비
+
+| ID      | 작업                                  | 상태 | 테스트 파일         | 비고                                                        |
+| ------- | ------------------------------------- | ---- | ------------------- | ----------------------------------------------------------- |
+| 3.1.0.1 | `@anthropic-ai/sdk` 의존성 설치       | ✅   | N/A                 | `^0.74.0` — packages/core/package.json에 추가 완료 (M3.1.0) |
+| 3.1.0.2 | ProviderRegistry에 Claude 팩토리 등록 | ✅   | `bootstrap.test.ts` | `bootstrapClaudeProvider()` + `has()` 가드 패턴 (M3.1.0)    |
+
+### 3.1.1 ClaudeAdapter 구현
+
+| ID      | 작업                           | 상태 | 테스트 파일       | 비고                                                    |
+| ------- | ------------------------------ | ---- | ----------------- | ------------------------------------------------------- |
+| 3.1.1.1 | `ClaudeAdapter` 클래스 생성    | ✅   | `adapter.test.ts` | ClaudeClient DI 인터페이스 포함 (M3.1.1)                |
+| 3.1.1.2 | `BaseAdapter` 상속 구현        | ✅   | `adapter.test.ts` | validateRequest 상속, mapToProviderConfig 구현 (M3.1.1) |
+| 3.1.1.3 | Anthropic SDK 연동             | ✅   | `adapter.test.ts` | ClaudeClient 인터페이스 통한 DI 패턴 (M3.1.1)           |
+| 3.1.1.4 | `generate()` 메서드 구현       | ✅   | `adapter.test.ts` | generateContent + classifyError (M3.1.1+M3.1.3)         |
+| 3.1.1.5 | `generateStream()` 메서드 구현 | ✅   | `adapter.test.ts` | generateContentStream + yield 패턴 (M3.1.1+M3.1.3)      |
+| 3.1.1.6 | `getCapabilities()` 구현       | ✅   | `adapter.test.ts` | CLAUDE_CAPABILITIES const (M3.1.1)                      |
+| 3.1.1.7 | 설정 검증 (API Key)            | ✅   | `adapter.test.ts` | BaseAdapter.validateRequest 위임 (M3.1.1)               |
+
+**TDD 시나리오**:
+
+```typescript
+describe('ClaudeAdapter', () => {
+  it('should implement BaseAdapter interface', () => {
+    const adapter = new ClaudeAdapter({
+      apiKey: 'test-key',
+      model: 'claude-sonnet-4-20250514',
+    });
+
+    expect(adapter).toBeInstanceOf(BaseAdapter);
+  });
+
+  it('should separate system message in API call', async () => {
+    const adapter = new ClaudeAdapter(config);
+    const request: LlmGenerateRequest = {
+      messages: [
+        {
+          role: LlmRole.System,
+          content: [{ type: 'text', text: 'Be helpful' }],
+        },
+        { role: LlmRole.User, content: [{ type: 'text', text: 'Hi' }] },
+      ],
+    };
+
+    // Mock Anthropic SDK
+    const mockCreate = vi.spyOn(anthropic.messages, 'create');
+    await adapter.generate(request);
+
+    expect(mockCreate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        system: 'Be helpful',
+        messages: [{ role: 'user', content: [{ type: 'text', text: 'Hi' }] }],
+      }),
+    );
+  });
+});
+```
+
+### 3.1.2 Claude 메시지 변환기
+
+| ID      | 작업                             | 상태 | 테스트 파일         | 비고                                               |
+| ------- | -------------------------------- | ---- | ------------------- | -------------------------------------------------- |
+| 3.1.2.1 | `toClaudeMessage()` 변환 함수    | ✅   | `converter.test.ts` | toClaudeMessages + toClaudeContent (M3.1.1+M3.1.2) |
+| 3.1.2.2 | System 메시지 분리 로직          | ✅   | `converter.test.ts` | system 추출 + 복수 system 병합 (M3.1.1)            |
+| 3.1.2.3 | 이미지 URL → base64 변환         | ✅   | `converter.test.ts` | base64 지원, URL은 경고 텍스트 (M3.1.2)            |
+| 3.1.2.4 | `toClaudeTool()` 변환 함수       | ✅   | `converter.test.ts` | toClaudeTools + toClaudeToolChoice (M3.1.1)        |
+| 3.1.2.5 | `fromClaudeResponse()` 변환 함수 | ✅   | `converter.test.ts` | thinking/redacted_thinking 포함 (M3.1.1)           |
+
+**TDD 시나리오**:
+
+```typescript
+describe('Claude Message Converter', () => {
+  it('should extract system message separately', () => {
+    const messages: LlmMessage[] = [
+      {
+        role: LlmRole.System,
+        content: [{ type: 'text', text: 'System prompt' }],
+      },
+      { role: LlmRole.User, content: [{ type: 'text', text: 'User message' }] },
+    ];
+
+    const { systemPrompt, claudeMessages } = toClaudeMessages(messages);
+
+    expect(systemPrompt).toBe('System prompt');
+    expect(claudeMessages).toHaveLength(1);
+    expect(claudeMessages[0].role).toBe('user');
+  });
+
+  it('should convert image URL to base64', async () => {
+    const message: LlmMessage = {
+      role: LlmRole.User,
+      content: [
+        {
+          type: 'image',
+          source: { type: 'url', url: 'https://example.com/image.png' },
+        },
+      ],
+    };
+
+    const claudeMessage = await toClaudeMessage(message);
+
+    expect(claudeMessage.content[0].type).toBe('image');
+    expect(claudeMessage.content[0].source.type).toBe('base64');
+  });
+});
+```
+
+### 3.1.3 Claude 스트림 변환기
+
+| ID      | 작업                           | 상태 | 테스트 파일         | 비고                                                               |
+| ------- | ------------------------------ | ---- | ------------------- | ------------------------------------------------------------------ |
+| 3.1.3.1 | `fromClaudeStreamEvent()` 변환 | ✅   | `converter.test.ts` | convertStreamEvent + createStreamState (M3.1.1)                    |
+| 3.1.3.2 | `content_block_start` 처리     | ✅   | `converter.test.ts` | tool_use 블록 시작 + index 기반 추적 (M3.1.1)                      |
+| 3.1.3.3 | `content_block_delta` 처리     | ✅   | `converter.test.ts` | text_delta, thinking_delta, input_json_delta (M3.1.1)              |
+| 3.1.3.4 | `content_block_stop` 처리      | ✅   | `converter.test.ts` | tool call JSON 파싱 + ToolCallRequest emit (M3.1.1)                |
+| 3.1.3.5 | Tool delta 합성 로직           | ✅   | `converter.test.ts` | parallel tool calls via index-based Map (M3.1.1)                   |
+| 3.1.3.6 | Usage 정보 추출                | ✅   | `converter.test.ts` | message_start input + message_delta output + cache tokens (M3.1.3) |
+
+**TDD 시나리오**:
+
+```typescript
+describe('Claude Stream Converter', () => {
+  it('should convert text delta events', async () => {
+    const claudeEvents = [
+      {
+        type: 'content_block_start',
+        content_block: { type: 'text', text: '' },
+      },
+      {
+        type: 'content_block_delta',
+        delta: { type: 'text_delta', text: 'Hello' },
+      },
+      { type: 'content_block_stop' },
+    ];
+
+    const events: LlmStreamEvent[] = [];
+    for (const event of claudeEvents) {
+      const converted = fromClaudeStreamEvent(event);
+      if (converted) events.push(converted);
+    }
+
+    expect(events[0].type).toBe('text_delta');
+    expect(events[0].text).toBe('Hello');
+  });
+
+  it('should assemble tool call deltas', async () => {
+    const assembler = new StreamAssembler();
+    // Claude tool delta events
+    assembler.push(
+      fromClaudeStreamEvent({
+        type: 'content_block_start',
+        content_block: { type: 'tool_use', id: 'tool_1', name: 'read_file' },
+      }),
+    );
+    assembler.push(
+      fromClaudeStreamEvent({
+        type: 'content_block_delta',
+        delta: { type: 'input_json_delta', partial_json: '{"path":' },
+      }),
+    );
+    assembler.push(
+      fromClaudeStreamEvent({
+        type: 'content_block_delta',
+        delta: { type: 'input_json_delta', partial_json: '"/tmp"}' },
+      }),
+    );
+
+    const result = assembler.getMessage();
+    expect(result.content[0].type).toBe('tool_call');
+    expect(result.content[0].arguments).toEqual({ path: '/tmp' });
+  });
+});
+```
+
+### 3.1.4 Claude 에러 매핑
+
+| ID      | 작업                    | 상태 | 테스트 파일       | 비고                                                          |
+| ------- | ----------------------- | ---- | ----------------- | ------------------------------------------------------------- |
+| 3.1.4.1 | Anthropic SDK 에러 분석 | ✅   | N/A (분석)        | M3.1.3에서 구현 완료 — classifyError duck typing 패턴         |
+| 3.1.4.2 | Rate limit 에러 매핑    | ✅   | `adapter.test.ts` | M3.1.3에서 구현 — 429→RateLimitError (retryable)              |
+| 3.1.4.3 | Auth 에러 매핑          | ✅   | `adapter.test.ts` | M3.1.3에서 구현 — 401/403→AuthenticationError (non-retryable) |
+| 3.1.4.4 | Overloaded 에러 매핑    | ✅   | `adapter.test.ts` | M3.1.3에서 구현 — 529→MODEL_OVERLOADED (retryable)            |
+| 3.1.4.5 | 에러 변환 유틸 함수     | ✅   | `adapter.test.ts` | M3.1.3에서 구현 — classifyError + LlmError passthrough        |
+
+⚠️ **참고**: M3.1.4 전체 범위가 M3.1.3 (스트림 에러 고도화) 작업에서 선행
+구현됨. 설계서 §3.3.6 대비 추가 구현: 400/422→INVALID_REQUEST,
+404→ModelNotFoundError, 500+→SERVER_ERROR, timeout/network 휴리스틱, LlmError
+passthrough.
+
+**검증 기준**:
+
+- [x] Claude 기본 대화 동작
+- [x] Claude 스트리밍 동작
+- [x] Claude 도구 호출 동작
+- [x] Claude 이미지 입력 동작
+
+---
+
+# M3.2: OpenAI 어댑터/변환기 구현 (3-4일)
+
+> 📚 **설계서 참조**:
+> [03-technical-design.md §3.3.7 OpenAI 어댑터](../03-technical-design.md#337-openai-어댑터-구조-예시),
+> [§3.3.8 OpenAI 타입 변환기](../03-technical-design.md#338-openai-타입-변환기-추가),
+> [05-implementation-plan.md §M3.2](../05-implementation-plan.md#m32-openai-어댑터변환기-구현-3-4일)
+
+## 목표
+
+OpenAI 메시지/툴/스트림 변환기 구현
+
+## OpenAI 특화 고려사항
+
+- System 메시지 첫 번째로 위치
+- JSON mode / response_format 지원
+- function_call → tool_calls 전환
+
+## 작업 항목
+
+### 3.2.0 사전 준비
+
+| ID      | 작업                                  | 상태 | 테스트 파일         | 비고                                                                    |
+| ------- | ------------------------------------- | ---- | ------------------- | ----------------------------------------------------------------------- |
+| 3.2.0.1 | `openai` SDK 의존성 설치              | ✅   | N/A                 | `openai@^6.18.0` 설치 (설계서 ^4.70.0보다 최신)                         |
+| 3.2.0.2 | ProviderRegistry에 OpenAI 팩토리 등록 | ✅   | `bootstrap.test.ts` | `bootstrapOpenAiProvider()` — has() 가드, singleton 기본값, config 전달 |
+
+### 3.2.1 OpenAiAdapter 구현
+
+| ID      | 작업                           | 상태 | 테스트 파일       | 비고                                                              |
+| ------- | ------------------------------ | ---- | ----------------- | ----------------------------------------------------------------- |
+| 3.2.1.1 | `OpenAiAdapter` 클래스 생성    | ✅   | `adapter.test.ts` | DI 패턴: `OpenAiClient` 인터페이스                                |
+| 3.2.1.2 | `BaseAdapter` 상속 구현        | ✅   | `adapter.test.ts` | validateRequest, mapToProviderConfig 구현                         |
+| 3.2.1.3 | OpenAI SDK 연동                | ✅   | `adapter.test.ts` | `client.chat.completions.create()` 호출                           |
+| 3.2.1.4 | `generateContent()` 구현       | ✅   | `adapter.test.ts` | 변환→호출→역변환 패턴, classifyError 에러 분류                    |
+| 3.2.1.5 | `generateContentStream()` 구현 | ✅   | `adapter.test.ts` | M3.2.A: 스켈레톤, M3.2.B: 변환기 완성 + `supportsStreaming: true` |
+| 3.2.1.6 | capabilities 선언              | ✅   | `adapter.test.ts` | `supportsTokenCount: false`, `supportsThought: false`             |
+
+**TDD 시나리오**:
+
+```typescript
+describe('OpenAIAdapter', () => {
+  it('should generate response using OpenAI SDK', async () => {
+    const adapter = new OpenAIAdapter({
+      apiKey: 'test-key',
+      model: 'gpt-4o'
+    });
+
+    const request: LlmGenerateRequest = {
+      messages: [{ role: LlmRole.User, content: [{ type: 'text', text: 'Hi' }] }]
+    };
+
+    const response = await adapter.generate(request);
+    expect(response.message).toBeDefined();
+  });
+
+  it('should support JSON mode', async () => {
+    const adapter = new OpenAIAdapter(config);
+    const request: LlmGenerateRequest = {
+      messages: [...],
+      responseFormat: { type: 'json_object' }
+    };
+
+    const mockCreate = vi.spyOn(openai.chat.completions, 'create');
+    await adapter.generate(request);
+
+    expect(mockCreate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        response_format: { type: 'json_object' }
+      })
+    );
+  });
+});
+```
+
+### 3.2.2 OpenAI 메시지 변환기
+
+| ID      | 작업                        | 상태 | 테스트 파일         | 비고                                                    |
+| ------- | --------------------------- | ---- | ------------------- | ------------------------------------------------------- |
+| 3.2.2.1 | `toOpenAiMessages()` 변환   | ✅   | `converter.test.ts` | 4 role (system/user/assistant/tool) + 혼합 content 처리 |
+| 3.2.2.2 | System 메시지 순서 처리     | ✅   | `converter.test.ts` | systemInstruction → 첫 번째 system 메시지로 prepend     |
+| 3.2.2.3 | 이미지 URL/base64 처리      | ✅   | `converter.test.ts` | URL 직접 전달, base64→data URI 변환                     |
+| 3.2.2.4 | `toOpenAiTools()` 변환      | ✅   | `converter.test.ts` | `{ type: 'function', function: {...} }` 래핑            |
+| 3.2.2.5 | `fromOpenAiResponse()` 변환 | ✅   | `converter.test.ts` | text, tool_calls, usage, cached_tokens 추출             |
+| 3.2.2.6 | JSON mode 매핑              | ✅   | `converter.test.ts` | `responseFormat: 'json'` → `{ type: 'json_object' }`    |
+
+**TDD 시나리오**:
+
+```typescript
+describe('OpenAI Message Converter', () => {
+  it('should place system message first', () => {
+    const messages: LlmMessage[] = [
+      { role: LlmRole.User, content: [{ type: 'text', text: 'Hi' }] },
+      { role: LlmRole.System, content: [{ type: 'text', text: 'Be helpful' }] },
+    ];
+
+    const openaiMessages = toOpenAIMessages(messages);
+
+    expect(openaiMessages[0].role).toBe('system');
+    expect(openaiMessages[1].role).toBe('user');
+  });
+
+  it('should convert image URL directly', () => {
+    const message: LlmMessage = {
+      role: LlmRole.User,
+      content: [
+        {
+          type: 'image',
+          source: { type: 'url', url: 'https://example.com/image.png' },
+        },
+      ],
+    };
+
+    const openaiMessage = toOpenAIMessage(message);
+
+    expect(openaiMessage.content[0].type).toBe('image_url');
+    expect(openaiMessage.content[0].image_url.url).toBe(
+      'https://example.com/image.png',
+    );
+  });
+});
+```
+
+### 3.2.3 OpenAI 스트림 변환기
+
+| ID      | 작업                        | 상태 | 테스트 파일         | 비고                                                                                 |
+| ------- | --------------------------- | ---- | ------------------- | ------------------------------------------------------------------------------------ |
+| 3.2.3.1 | `convertStreamEvent()` 변환 | ✅   | `converter.test.ts` | text delta 5건 + tool call 8건 + finish 4건 + usage 4건 + 통합 2건 + 엣지 2건 = 25건 |
+| 3.2.3.2 | 텍스트 델타 처리            | ✅   | `converter.test.ts` | T1-T5: delta.content 비empty → TextDelta, null/empty/role-only 필터링                |
+| 3.2.3.3 | Tool call 델타 처리         | ✅   | `converter.test.ts` | T6-T13: index 기반 축적, 병렬 추적, finish_reason=tool_calls 시 일괄 발행            |
+| 3.2.3.4 | Usage 정보 추출             | ✅   | `converter.test.ts` | T18-T21: usage-only 최종 청크 → MessageEnd, cached_tokens 추출                       |
+
+### 3.2.4 OpenAI 에러 매핑
+
+| ID      | 작업                 | 상태 | 테스트 파일       | 비고                                                                  |
+| ------- | -------------------- | ---- | ----------------- | --------------------------------------------------------------------- |
+| 3.2.4.1 | OpenAI SDK 에러 분석 | ✅   | N/A (분석)        | M3.2.A 사전작업에서 SDK d.ts 전수 분석 완료                           |
+| 3.2.4.2 | Rate limit 에러 매핑 | ✅   | `adapter.test.ts` | 429→RateLimitError, Claude와 동일 패턴                                |
+| 3.2.4.3 | Auth 에러 매핑       | ✅   | `adapter.test.ts` | 401/403→AuthenticationError                                           |
+| 3.2.4.4 | 에러 변환 유틸 함수  | ✅   | `adapter.test.ts` | `classifyError()` — 8 status code + message heuristic + LlmError 보존 |
+
+**검증 기준**:
+
+- [x] OpenAI 기본 대화 동작
+- [x] OpenAI 스트리밍 동작 (M3.2.B — `convertStreamEvent` 25건 + adapter
+      streaming 3건)
+- [x] OpenAI 도구 호출 동작
+- [x] OpenAI JSON mode 동작
+
+---
+
+# M3.3: OpenAI-Compatible(vLLM/sLM) 어댑터 템플릿 (3일)
+
+> 📚 **설계서 참조**:
+> [03-technical-design.md §3.4 vLLM 및 OpenAI 호환 프로바이더 확장](../03-technical-design.md#34-vllm-및-기타-openai-호환-프로바이더-확장),
+> [05-implementation-plan.md §M3.3](../05-implementation-plan.md#m33-openai-compatiblevllmslm-어댑터-템플릿-3일)
+
+## 목표
+
+vLLM, TGI, LM Studio 등 OpenAI 호환 API 지원
+
+## 특화 고려사항
+
+- Custom baseUrl 지원
+- Custom headers 지원
+- 다양한 API Key 헤더 지원
+- 모델별 ChatTemplate 훅
+
+## 작업 항목
+
+### 3.3.0 사전 준비
+
+| ID      | 작업                                             | 상태 | 테스트 파일         | 비고                                                                                                        |
+| ------- | ------------------------------------------------ | ---- | ------------------- | ----------------------------------------------------------------------------------------------------------- |
+| 3.3.0.1 | ProviderRegistry에 OpenAI-Compatible 팩토리 등록 | ✅   | `bootstrap.test.ts` | `bootstrapOpenAiCompatibleProvider()` — has() guard, `LLM_CUSTOM_HEADERS`/`LLM_API_KEY_HEADER` env var 지원 |
+
+### 3.3.1 OpenAICompatibleAdapter 구현
+
+| ID      | 작업                             | 상태 | 테스트 파일         |
+| ------- | -------------------------------- | ---- | ------------------- | ------------------------------------------------------------------- |
+| 3.3.1.1 | `OpenAICompatibleAdapter` 클래스 | ✅   | `adapter.test.ts`   | BaseAdapter + OpenAiAdapter 상속, providerName='openai-compatible'  |
+| 3.3.1.2 | `OpenAIAdapter` 상속             | ✅   | `adapter.test.ts`   | `extends OpenAiAdapter` — converter/classifyError/generate\* 재사용 |
+| 3.3.1.3 | `baseUrl` 설정 지원              | ✅   | `bootstrap.test.ts` | OpenAI SDK `baseURL` 옵션으로 전달                                  |
+| 3.3.1.4 | Custom headers 지원              | ✅   | `bootstrap.test.ts` | `LLM_CUSTOM_HEADERS` env var (JSON) → SDK `defaultHeaders`          |
+| 3.3.1.5 | `apiKeyHeaderName` 지원          | ✅   | `bootstrap.test.ts` | `LLM_API_KEY_HEADER` env var → custom auth header                   |
+| 3.3.1.6 | 연결 테스트 메서드               | ✅   | `adapter.test.ts`   | `testConnection()` — HTTP응답=true, 네트워크에러=false              |
+
+**TDD 시나리오**:
+
+```typescript
+describe('OpenAICompatibleAdapter', () => {
+  it('should use custom baseUrl', async () => {
+    const adapter = new OpenAICompatibleAdapter({
+      baseUrl: 'http://localhost:8000/v1',
+      model: 'meta-llama/Llama-3.1-8B-Instruct',
+    });
+
+    const mockFetch = vi.spyOn(global, 'fetch');
+    await adapter.generate(request);
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      expect.stringContaining('http://localhost:8000/v1'),
+      expect.any(Object),
+    );
+  });
+
+  it('should support custom API key header', async () => {
+    const adapter = new OpenAICompatibleAdapter({
+      baseUrl: 'http://localhost:8000/v1',
+      apiKey: 'my-key',
+      apiKeyHeaderName: 'X-Custom-Auth',
+    });
+
+    const mockFetch = vi.spyOn(global, 'fetch');
+    await adapter.generate(request);
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          'X-Custom-Auth': 'my-key',
+        }),
+      }),
+    );
+  });
+});
+```
+
+### 3.3.2 모델별 템플릿 훅
+
+| ID      | 작업                       | 상태 | 테스트 파일             |
+| ------- | -------------------------- | ---- | ----------------------- | ------------------------------------------------------------------ |
+| 3.3.2.1 | `PromptBuilder` 인터페이스 | ✅   | `promptBuilder.test.ts` | `formatPrompt()` 메서드 — 확장 포인트                              |
+| 3.3.2.2 | Llama3 ChatTemplate        | ✅   | `promptBuilder.test.ts` | `Llama3PromptBuilder` + model hook(`createPromptBuilderForModel`)  |
+| 3.3.2.3 | Mistral ChatTemplate       | ✅   | `promptBuilder.test.ts` | `MistralPromptBuilder` + model hook(`createPromptBuilderForModel`) |
+| 3.3.2.4 | 범용 ChatML 템플릿         | ✅   | `promptBuilder.test.ts` | `ChatMLPromptBuilder` — `<\|im_start\|>/<\|im_end\|>` 토큰         |
+
+### 3.3.3 호환성 시나리오 테스트
+
+| ID      | 작업                    | 상태 | 테스트 파일             |
+| ------- | ----------------------- | ---- | ----------------------- | -------------------------------------------------------------- |
+| 3.3.3.1 | vLLM 호환성 테스트      | ✅   | `compatibility.test.ts` | chat completion + streaming + error + no apiKey (4 tests)      |
+| 3.3.3.2 | TGI 호환성 테스트       | ✅   | `compatibility.test.ts` | chat completion + streaming + error (3 tests)                  |
+| 3.3.3.3 | LM Studio 호환성 테스트 | ✅   | `compatibility.test.ts` | chat completion + streaming (2 tests)                          |
+| 3.3.3.4 | Ollama 호환성 테스트    | ✅   | `compatibility.test.ts` | chat completion + streaming + missing usage graceful (3 tests) |
+
+**검증 기준**:
+
+- [x] vLLM 기본 대화 동작
+- [x] Custom baseUrl 동작
+- [x] Custom headers 동작
+
+---
+
+# M3.4: 통합 테스트/문서/안정화 — ⚡ 부분 선행
+
+> 📚 **설계서 참조**:
+> [04-integration-design.md §4.2 연동 아키텍처](../04-integration-design.md#42-연동-아키텍처)
+> (통합 테스트 시나리오),
+> [05-implementation-plan.md §5.5 테스트 및 검증](../05-implementation-plan.md#55-테스트-및-검증),
+> [§M3.4](../05-implementation-plan.md#m34-통합-테스트문서안정화-5-7일)
+>
+> ⚡ **실행 순서**: M3.4.A (선행) → M3.3 → M3.4.B (잔여)
+>
+> **선행 범위**: Gemini/Claude/OpenAI (3 providers) 기반 통합 테스트 및 문서화
+> **M3.3 의존 항목**: vLLM E2E 테스트, OpenAI-Compatible 문서 상세화
+
+## 목표
+
+멀티 프로바이더 통합 검증 및 문서화 (Phase: 3 providers → 4 providers)
+
+---
+
+## M3.4.A: 선행 가능 항목 (3-Provider Integration)
+
+> **전제 조건**: M3.0 ✅, M3.1 ✅, M3.2 ✅
+>
+> **작업 기간**: 3-4일
+
+## 작업 항목
+
+### 3.4.1 멀티 프로바이더 통합 테스트
+
+| ID      | 작업                        | 상태 | 테스트 파일                         | M3.3 의존 |
+| ------- | --------------------------- | ---- | ----------------------------------- | --------- |
+| 3.4.1.1 | 프로바이더 전환 테스트      | ✅   | `multiProvider.integration.test.ts` | ❌        |
+| 3.4.1.2 | 동시 프로바이더 사용 테스트 | ✅   | `multiProvider.integration.test.ts` | ❌        |
+| 3.4.1.3 | 설정 검증 통합 테스트       | ✅   | `providerConfigIntegration.test.ts` | ❌        |
+| 3.4.1.4 | 에러 처리 통합 테스트       | ✅   | `errorHandling.integration.test.ts` | ❌        |
+
+### 3.4.2 E2E 테스트 시나리오
+
+| ID      | 작업                   | 상태 | 테스트 파일              | M3.3 의존   |
+| ------- | ---------------------- | ---- | ------------------------ | ----------- |
+| 3.4.2.1 | Gemini E2E 테스트      | ✅   | `multi-provider.test.ts` | ❌          |
+| 3.4.2.2 | Claude E2E 테스트      | ✅   | `multi-provider.test.ts` | ❌          |
+| 3.4.2.3 | OpenAI E2E 테스트      | ✅   | `multi-provider.test.ts` | ❌          |
+| 3.4.2.4 | vLLM E2E 테스트 (선택) | ⬜   | E2E                      | ✅ → M3.4.B |
+
+**E2E 테스트 매트릭스 (M3.4.A 선행 범위)**:
+
+| 시나리오      | Gemini | Claude | OpenAI | vLLM (M3.4.B) |
+| ------------- | ------ | ------ | ------ | ------------- |
+| 기본 대화     | ✅     | ✅     | ✅     | ⏳ M3.3 후    |
+| 스트리밍 대화 | ✅     | ✅     | ✅     | ⏳ M3.3 후    |
+| 도구 호출     | ✅     | ✅     | ✅     | ⏳ M3.3 후    |
+| 이미지 입력   | ⬜     | ⬜     | ⬜     | ⏳ M3.3 후    |
+| 에러 처리     | ✅     | ✅     | ✅     | ⏳ M3.3 후    |
+
+### 3.4.3 성능 회귀 테스트 (3-Provider Baseline)
+
+| ID      | 작업                      | 상태 | 테스트 파일                               | M3.3 의존 |
+| ------- | ------------------------- | ---- | ----------------------------------------- | --------- |
+| 3.4.3.1 | 응답 지연 벤치마크        | ✅   | `providers/__tests__/performance.test.ts` | ❌        |
+| 3.4.3.2 | 스트리밍 첫 토큰 벤치마크 | ✅   | `providers/__tests__/performance.test.ts` | ❌        |
+| 3.4.3.3 | 메모리 사용량 프로파일링  | ✅   | `providers/__tests__/performance.test.ts` | ❌        |
+| 3.4.3.4 | 번들 크기 분석            | ✅   | `providers/__tests__/bundleSize.test.ts`  | ❌        |
+
+**성능 기준**:
+
+- 응답 지연 증가 < 50ms
+- 스트리밍 첫 토큰 지연 < 100ms
+- 메모리 증가 < 10%
+- 번들 크기 증가 < 500KB
+
+### 3.4.4 문서 업데이트 (3-Provider + vLLM Placeholder)
+
+| ID      | 작업                  | 상태 | 산출물                  | M3.3 의존 |
+| ------- | --------------------- | ---- | ----------------------- | --------- |
+| 3.4.4.1 | 사용자 가이드 작성    | ✅   | `docs/providers.md`     | 🔶        |
+| 3.4.4.2 | API 레퍼런스 업데이트 | ✅   | `docs/api/`             | ❌        |
+| 3.4.4.3 | 환경변수 문서화       | ✅   | `docs/configuration.md` | 🔶        |
+| 3.4.4.4 | 마이그레이션 가이드   | ✅   | `docs/migration.md`     | ❌        |
+| 3.4.4.5 | README 업데이트       | ✅   | `README.md`             | 🔶        |
+
+🔶 = 3 providers 완전 문서화 + vLLM placeholder 포함, M3.4.B에서 상세화
+
+### 3.4.5 안정화 작업 (3-Provider Scope)
+
+| ID      | 작업               | 상태 | M3.3 의존 | 비고                                                                                                                       |
+| ------- | ------------------ | ---- | --------- | -------------------------------------------------------------------------------------------------------------------------- |
+| 3.4.5.1 | 버그 수정          | ✅   | ❌        | non-Gemini provider + llm\* 메서드 불일치 가드 및 explicit error event 추가                                                |
+| 3.4.5.2 | 에지 케이스 처리   | ✅   | ❌        | llm stream throw 시 Error event 변환, model history 오염 방지                                                              |
+| 3.4.5.3 | 에러 메시지 개선   | ✅   | ❌        | `PROVIDER_METHOD_MISMATCH`, `LLM_STREAM_FAILURE` 코드와 설명 메시지 추가                                                   |
+| 3.4.5.4 | 로깅 개선          | ✅   | ❌        | debug mode에서 non-Gemini 경로 선택/stream throw 상황 로깅                                                                 |
+| 3.4.5.5 | 기능 플래그 정리   | ✅   | ❌        | featureFlag 테스트 재검증(16 PASS) + non-Gemini 경로 guard와 충돌 없는 동작 확인                                           |
+| 3.4.5.6 | 의존성 정합성 검증 | ✅   | ❌        | package/lockfile 검증, `npm ci --ignore-scripts` 성공, `npm run check:lockfile` PASS, bundle 내 anthropic/openai 포함 확인 |
+
+**M3.4.A 검증 기준** (선행 완료 조건):
+
+- [x] 멀티 프로바이더 통합 테스트 통과 (3.4.1.1~3.4.1.4)
+- [x] Gemini/Claude/OpenAI E2E 테스트 통과 (3.4.2.1~3.4.2.3)
+- [x] 성능 회귀 없음 (3-provider baseline 기준 내)
+- [x] 3-provider 문서 완성 (vLLM placeholder 포함)
+- [x] 의존성 검증 (`npm ci` 성공, esbuild bundle 포함 확인)
+
+---
+
+## M3.4.B: M3.3 의존 항목 (vLLM Integration)
+
+> **전제 조건**: M3.3 완료 (OpenAI-Compatible adapter)
+>
+> **작업 기간**: 1-2일
+
+### 3.4.2 E2E 테스트 시나리오 (vLLM Subset)
+
+| ID      | 작업                   | 상태 | 테스트 파일 |
+| ------- | ---------------------- | ---- | ----------- |
+| 3.4.2.4 | vLLM E2E 테스트 (선택) | ⬜   | E2E         |
+
+### 3.4.4 문서 업데이트 (vLLM 상세화)
+
+| ID        | 작업                     | 상태 | 산출물                  |
+| --------- | ------------------------ | ---- | ----------------------- |
+| 3.4.4.1-B | vLLM 섹션 상세화         | ✅   | `docs/providers.md`     |
+| 3.4.4.3-B | LLM_BASE_URL 문서 상세화 | ✅   | `docs/configuration.md` |
+| 3.4.4.5-B | vLLM Quick Start 추가    | ✅   | `README.md`             |
+
+**M3.4.B 검증 기준** (전체 M3.4 완료 조건):
+
+- [ ] vLLM E2E 테스트 통과 (또는 환경 의존 skip 처리)
+- [x] vLLM 문서 완성 (placeholder → full docs)
+- [ ] 전체 M3.4 완료 (M3.4.A + M3.4.B)
+
+---
+
+# M3.5: 테스트 마이그레이션 (3-4일) [v0.2 신규]
+
+> 📚 **설계서 참조**:
+> [05-implementation-plan.md §5.5 테스트 및 검증](../05-implementation-plan.md#55-테스트-및-검증)
+> (테스트 전략),
+> [03-technical-design.md §3.1 타입 시스템](../03-technical-design.md#31-프로바이더-독립적-타입-시스템)
+> (Mock 타입 전환 참조)
+
+## 목표
+
+Gemini 특화 테스트를 프로바이더 중립적 테스트로 전환
+
+## 배경
+
+Phase 2에서 리팩토링된 코드에 대응하여 기존 테스트도 함께 마이그레이션 필요
+
+## 작업 항목
+
+### 3.5.1 테스트 파일 분석
+
+| ID      | 작업                                | 상태 | 산출물           |
+| ------- | ----------------------------------- | ---- | ---------------- |
+| 3.5.1.1 | Gemini 특화 테스트 파일 식별        | ⬜   | 테스트 파일 목록 |
+| 3.5.1.2 | 테스트 내 @google/genai 의존성 분석 | ⬜   | 의존성 매트릭스  |
+| 3.5.1.3 | Mock 객체 Gemini 특화 여부 분석     | ⬜   | Mock 분석 문서   |
+| 3.5.1.4 | 테스트 수정 범위 산정               | ⬜   | 수정 범위 문서   |
+
+**분석 대상 테스트 파일** (실제 존재 확인됨):
+
+```
+packages/core/src/
+├── core/
+│   ├── contentGenerator.test.ts    # GenerateContentParameters 의존
+│   ├── turn.test.ts                # GeminiEventType 의존
+│   ├── geminiChat.test.ts          # Gemini 응답/스트리밍 의존 🆕
+│   ├── baseLlmClient.test.ts       # 🆕 baseLlmClient 의존
+│   ├── loggingContentGenerator.test.ts   # 래퍼 클래스
+│   ├── recordingContentGenerator.test.ts # 래퍼 클래스
+│   └── fakeContentGenerator.test.ts      # Mock 구현
+├── services/
+│   └── modelConfigService.test.ts  # GenerateContentConfig 의존
+├── routing/
+│   ├── modelRouterService.test.ts  # 🆕 라우팅 레이어
+│   └── strategies/*.test.ts        # 🆕 라우팅 전략
+└── utils/
+    ├── tokenCalculation.test.ts    # Part, Content 타입 의존
+    └── partUtils.test.ts           # Part 타입 의존
+```
+
+⚠️ **주의**: `session.test.ts`는 존재하지 않음 (원본 계획서 오류 수정됨)
+
+### 3.5.2 테스트 마이그레이션 전략
+
+| ID      | 작업                      | 상태 | 테스트 파일                     |
+| ------- | ------------------------- | ---- | ------------------------------- |
+| 3.5.2.1 | 공통 Mock Factory 설계    | ⬜   | `testUtils/mockFactory.ts`      |
+| 3.5.2.2 | 프로바이더 중립 Mock 구현 | ⬜   | `testUtils/mockFactory.test.ts` |
+| 3.5.2.3 | 프로바이더별 Mock 어댑터  | ⬜   | `testUtils/mockAdapters.ts`     |
+| 3.5.2.4 | 테스트 데이터 팩토리      | ⬜   | `testUtils/testDataFactory.ts`  |
+
+**TDD 시나리오**:
+
+```typescript
+describe('MockFactory', () => {
+  it('should create provider-agnostic mock message', () => {
+    const mockMessage = MockFactory.createMessage({
+      role: LlmRole.User,
+      text: 'Hello',
+    });
+
+    expect(mockMessage.role).toBe(LlmRole.User);
+    expect(mockMessage.content[0].type).toBe('text');
+  });
+
+  it('should create provider-specific response via adapter', () => {
+    const genericResponse = MockFactory.createResponse({ text: 'Hi' });
+
+    // Gemini용 변환
+    const geminiResponse = MockAdapters.toGemini(genericResponse);
+    expect(geminiResponse).toHaveProperty('candidates');
+
+    // Claude용 변환
+    const claudeResponse = MockAdapters.toClaude(genericResponse);
+    expect(claudeResponse).toHaveProperty('content');
+  });
+});
+```
+
+### 3.5.3 테스트 파일 마이그레이션
+
+| ID      | 작업                                        | 상태 | 우선순위 |
+| ------- | ------------------------------------------- | ---- | -------- |
+| 3.5.3.1 | `contentGenerator.test.ts` 마이그레이션     | ⬜   | 높음     |
+| 3.5.3.2 | `turn.test.ts` 마이그레이션                 | ⬜   | 높음     |
+| 3.5.3.3 | `geminiChat.test.ts` 마이그레이션           | ⬜   | 높음     |
+| 3.5.3.4 | `baseLlmClient.test.ts` 마이그레이션        | ⬜   | 중간     |
+| 3.5.3.5 | `modelConfigService.test.ts` 마이그레이션   | ⬜   | 중간     |
+| 3.5.3.6 | `tokenCalculation.test.ts` 마이그레이션     | ⬜   | 낮음     |
+| 3.5.3.7 | `partUtils.test.ts` 마이그레이션            | ⬜   | 낮음     |
+| 3.5.3.8 | `routing/*.test.ts` 마이그레이션 (7개 파일) | ⬜   | 중간     |
+
+**마이그레이션 패턴**:
+
+```typescript
+// Before: Gemini 특화 테스트
+import type { GenerateContentResponse } from '@google/genai';
+
+const mockResponse: GenerateContentResponse = {
+  candidates: [{ content: { parts: [{ text: 'Hello' }] } }],
+};
+
+// After: 프로바이더 중립 테스트
+import { MockFactory } from '../../testUtils/mockFactory';
+
+const mockResponse = MockFactory.createResponse({ text: 'Hello' });
+// GeminiAdapter 테스트시 GeminiMockAdapter로 변환
+```
+
+### 3.5.4 크로스 프로바이더 테스트 수트
+
+| ID      | 작업                     | 상태 | 테스트 파일                                 |
+| ------- | ------------------------ | ---- | ------------------------------------------- |
+| 3.5.4.1 | 공통 테스트 케이스 정의  | ⬜   | `providers/__tests__/common.ts`             |
+| 3.5.4.2 | 파라미터화된 테스트 구현 | ⬜   | `providers/__tests__/crossProvider.test.ts` |
+| 3.5.4.3 | 프로바이더별 테스트 실행 | ⬜   | CI/CD 설정                                  |
+
+**TDD 시나리오**:
+
+```typescript
+describe.each([
+  ['gemini', GeminiAdapter],
+  ['claude', ClaudeAdapter],
+  ['openai', OpenAIAdapter],
+])('%s adapter', (name, AdapterClass) => {
+  it('should convert user message correctly', () => {
+    const adapter = new AdapterClass(testConfig);
+    const message = MockFactory.createUserMessage('Hello');
+
+    const converted = adapter.convertMessage(message);
+
+    // 각 프로바이더별 검증
+    expect(converted).toMatchProviderSchema(name);
+  });
+
+  it('should handle streaming events', async () => {
+    const adapter = new AdapterClass(testConfig);
+    const events: LlmStreamEvent[] = [];
+
+    for await (const event of adapter.generateStream(request)) {
+      events.push(event);
+    }
+
+    expect(events.some((e) => e.type === 'text_delta')).toBe(true);
+  });
+});
+```
+
+**검증 기준**:
+
+- [ ] 모든 기존 테스트 마이그레이션 완료
+- [ ] 공통 Mock Factory 동작 확인
+- [ ] 크로스 프로바이더 테스트 통과
+- [ ] 테스트 커버리지 유지 (≥80%)
+
+---
+
+# PHASE 3 COMPLETION CHECKLIST
+
+## Phase 2 연기 항목 해소 (M3.0) [v0.4 추가]
+
+- [x] `geminiChat.ts` → `providers/gemini/chat.ts` 물리적 이동 완료 (M3.0.1)
+- [x] `turn.ts` Gemini 특화 로직 분리 완료 (M3.0.1)
+- [x] root `index.ts` re-export 회귀 테스트 통과 (M3.0.1.5)
+- [x] messageInspectors 4개 파일 마이그레이션 완료 (M3.0.2)
+- [x] 텔레메트리 레이어 @google/genai 독립화 (M3.0.3)
+- [x] LocalAgentExecutor GeminiChat 직접 결합 해소 (M3.0.3)
+- [x] `geminiTypeConversion.ts` 브릿지 정리 완료 (M3.0.4)
+- [x] `telemetry/sdk.ts` 시그널 핸들러 누수 수정 (M3.0.3)
+- [ ] `createContentGenerator()` → ProviderFactory 런타임 연결 완료 (3.0.5)
+- [ ] ProviderRegistry Gemini 팩토리 부트스트랩 동작 (3.0.5.4)
+- [ ] 부트스트랩 중복 호출 안전성 검증 (3.0.5.4)
+- [ ] 프로바이더 선택 우선순위 통합 및 7개 회귀 시나리오 통과 (3.0.5.5)
+
+## Quality Gates
+
+- [ ] 모든 단위 테스트 통과
+- [ ] 모든 통합 테스트 통과
+- [ ] 모든 E2E 테스트 통과
+- [ ] TypeScript 컴파일 에러 없음
+- [ ] ESLint 경고 없음
+
+## 성능 검증
+
+- [ ] 응답 지연 증가 < 50ms
+- [ ] 스트리밍 첫 토큰 지연 < 100ms
+- [ ] 메모리 사용량 증가 < 10%
+- [ ] 번들 크기 증가 < 500KB
+
+## 기능 검증
+
+- [ ] Gemini 기존 기능 100% 동작
+- [ ] Claude 핵심 기능 동작
+- [ ] OpenAI 핵심 기능 동작
+- [ ] OpenAI-Compatible 기본 동작
+
+## 산출물 확인
+
+- [ ] `packages/core/src/providers/gemini/chat.ts` 이동 완료 (M3.0)
+- [ ] `packages/core/src/providers/gemini/turn.ts` 분리 완료 (M3.0)
+- [ ] `packages/core/src/providers/claude/` 디렉토리 생성
+- [ ] `packages/core/src/providers/openai/` 디렉토리 생성
+- [ ] `packages/core/src/providers/openai-compatible/` 디렉토리 생성
+- [ ] `@anthropic-ai/sdk`, `openai` 의존성 설치 및 lockfile 동기화
+- [ ] ProviderRegistry에 4개 팩토리 등록 (gemini, claude, openai,
+      openai-compatible)
+- [ ] 사용자 문서 완성
+- [ ] API 레퍼런스 완성
+
+## 테스트 마이그레이션 검증 [v0.2 추가]
+
+- [ ] 모든 기존 테스트 파일 마이그레이션 완료
+- [ ] 공통 Mock Factory 구현 및 테스트 통과
+- [ ] 프로바이더별 Mock 어댑터 동작 확인
+- [ ] 크로스 프로바이더 테스트 수트 통과
+- [ ] 테스트 커버리지 ≥80% 유지
+
+---
+
+# RELEASE PLAN
+
+## 버전 출시 계획
+
+| 버전         | 포함 내용                         | 시점              |
+| ------------ | --------------------------------- | ----------------- |
+| 0.28.0-alpha | GeminiAdapter + 타입 전환         | Phase 2 완료 후   |
+| 0.28.0-beta  | Claude/OpenAI + OpenAI-Compatible | Phase 3 일부 완료 |
+| 0.28.0       | 안정화/문서/테스트                | Phase 3 종료 후   |
+
+## 기능 플래그 관리
+
+```typescript
+// 점진적 활성화
+ENABLE_MULTI_PROVIDER=false  # 기본값: 기존 동작
+ENABLE_MULTI_PROVIDER=true   # 신규 아키텍처 활성화
+```
+
+## 롤백 계획
+
+1. 문제 발생 시 `ENABLE_MULTI_PROVIDER=false` 설정
+2. 기존 Gemini 전용 경로로 즉시 폴백
+3. 이슈 분석 및 수정 후 재배포
+
+---
+
+# DEPENDENCY MANAGEMENT
+
+## 신규 의존성
+
+```json
+{
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.30.0",
+    "openai": "^4.70.0"
+  }
+}
+```
+
+## 번들 최적화
+
+```typescript
+// Dynamic import로 번들 크기 관리
+const ClaudeAdapter = await import('./claude/adapter');
+const OpenAIAdapter = await import('./openai/adapter');
+```
+
+---
+
+# NOTES
+
+## 프로바이더별 주의사항
+
+### Claude
+
+- System 메시지는 별도 파라미터로 전달
+- 이미지 URL은 base64로 변환 필수
+- tool delta 합성 필요
+
+### OpenAI
+
+- System 메시지는 첫 번째 위치
+- JSON mode 지원
+- 이미지 URL 직접 지원
+
+### OpenAI-Compatible
+
+- baseUrl 설정 필수
+- 모델별 capability 차이 존재
+- 일부 기능 미지원 가능
+
+## TDD 원칙
+
+1. 각 프로바이더별 변환 함수 테스트 우선
+2. 스트리밍 합성 테스트 필수
+3. 에러 매핑 테스트 필수
+
+## 참고 문서
+
+- [03-technical-design.md](../03-technical-design.md)
+- [04-integration-design.md](../04-integration-design.md)
+- [05-implementation-plan.md](../05-implementation-plan.md)
+
+---
+
+# CHANGE LOG
+
+## v0.8 (리뷰 3건 반영)
+
+- **이슈 #1 [Medium] — 중복 등록 안전성**:
+  - M3.0.5.4 비고 보강: `registry.register()` 중복 호출 시 예외 발생
+    (registry.ts:81) — `has()` 가드/force 정책/초기화 위치 3가지 방안 명시
+  - 테스트 파일에 `contentGenerator.test.ts` 추가 (런타임 부트스트랩 검증)
+  - 부트스트랩 코드 예시(`has()` 가드 권장 패턴) 추가
+  - M3.1.0.2/M3.2.0.2/M3.3.0.1에 동일 가드 패턴 적용 주석 추가
+  - 검증 기준/Completion Checklist에 "중복 호출 안전성" 항목 추가
+- **이슈 #2 [Medium] — 런타임 wiring 테스트 타깃 보강**:
+  - M3.0.5.2 테스트 파일: `providerConfigIntegration.test.ts` →
+    `contentGenerator.test.ts`, `providerConfigIntegration.test.ts` (복수)
+  - 비고에 "실제 런타임 분기점은 `createContentGenerator()` (L167)" 명시
+  - M3.0.5.4 테스트 파일에 `contentGenerator.test.ts` 추가
+- **이슈 #3 [Low] — `--provider` CLI 옵션 미존재 명확화**:
+  - 우선순위 표 1순위: `--provider claude` → `providerName: 'claude'` (내부 API
+    수준)
+  - Q7 Open Question 신규: CLI `--provider` 옵션 노출 여부 (잠정: 환경변수로
+    충분)
+  - 비고에 "CLI `--provider` 옵션은 미존재 — Q7 참조" 추가
+
+## v0.7 (리뷰 4건 반영)
+
+- **이슈 #1 [High] — 레지스트리 등록 누락**:
+  - M3.0.5.4 신규: ProviderRegistry Gemini 팩토리 부트스트랩 구현
+  - M3.0.5.5 신규: 프로바이더 선택 우선순위 통합 (5단계 우선순위 표 + 7개 회귀
+    시나리오)
+  - M3.1.0.2 신규: `register('claude', ...)` 작업 추가
+  - M3.2.0.2 신규: `register('openai', ...)` 작업 추가
+  - M3.3.0.1 신규: `register('openai-compatible', ...)` 작업 추가
+- **이슈 #2 [Medium] — root index.ts export 테스트 부재**:
+  - M3.0.1.5 신규: root `index.ts` re-export 회귀 테스트 추가 (현재 placeholder)
+  - 검증 기준 및 Completion Checklist에 CLI import 호환성 항목 추가
+- **이슈 #3 [Medium] — 프로바이더 선택 우선순위 충돌**:
+  - M3.0.5.5에 통합 우선순위 표(5단계) 및 회귀 테스트(7시나리오) 추가
+  - 2개 분리 시스템(contentGenerator authType vs providerSelector LLM_PROVIDER)
+    충돌 명시
+- **이슈 #4 [Low] — 의존성 설치 작업 누락**:
+  - M3.1.0.1 신규: `@anthropic-ai/sdk` 설치 작업
+  - M3.2.0.1 신규: `openai` SDK 설치 작업
+  - M3.4.5.6 신규: 의존성 정합성 검증 (lockfile, npm ci, 번들링)
+  - 산출물 확인에 의존성/레지스트리 항목 추가
+
+## v0.6 (코드 기반 검증 반영)
+
+- **geminiChat.ts 라인 수**: 988 → 999라인 정정
+- **turn.ts 분석 정정**: "공통 인터페이스 core 유지" → Turn 클래스 전체가
+  Gemini-specific (324라인, GeminiChat 생성자 의존)
+- **loopDetectionService.ts 라인 번호**: L444/452/473 → L408/416/437 정정
+- **loggingContentGenerator import 수**: "8+" → "11개 SDK 타입" (L7-18 상세)
+  정정
+- **contentGenerator.ts 라인 범위**: "220~250" → "167-259 (GoogleGenAI 생성:
+  L235)" 정정
+- **LocalAgentExecutor 결합 상세**: L753 직접 생성자 호출 + 3개 메서드 하드코딩
+  명시
+- **ENABLE_MULTI_PROVIDER 제어 범위**: adapterBridge에서만 제어,
+  contentGenerator 미연결 명시
+- **import 변경 파일 수**: geminiChat 13개 + turn 10개 = 23개 파일 명시
+- **핸드오프 문서 동기화**: phase3_handoff.md의 라인 번호/수치도 동일 정정
+
+## v0.5 (리뷰 5건 반영)
+
+- **이슈 #1 [High]**: M3.0.5 신규 — 런타임 실행 경로 연결 (contentGenerator.ts →
+  ProviderFactory 연결 3개 작업)
+- **이슈 #2 [High]**: phase3_handoff.md 마일스톤 순서 — 최신 계획서와의 매핑
+  주석 및 H-1~H-5 라벨 추가
+- **이슈 #3 [Medium]**: 테스트 파일명 3건 수정 — `localAgentExecutor.test.ts` →
+  `local-executor.test.ts`, `telemetry/types.test.ts` → `telemetry/sdk.test.ts`,
+  `exports.test.ts` → `providers/gemini/exports.test.ts`
+- **이슈 #4 [Medium]**: 일정 산정 — Phase 3 기간 3-4주 → 4-6주, 전체 일정 8-10주
+  → 9-12주 (M3.0 추가분 반영)
+- **이슈 #5 [Medium]**: Q5/Q6 의존성 명시 — M3.0.3.3/3.0.3.4에 Open Question
+  의존성 주석 추가, 사전 결정 필요 사항 테이블 추가
+- **검증 기준 보강**: 런타임 연결 검증 2건 추가, Completion Checklist에 3.0.5
+  추가
+
+## v0.4 (Phase 2 연기 항목 반영)
+
+- **M3.0 신규 추가**: Phase 2 연기 항목 해소 — Gemini 내부 리팩토링 (3-5일)
+  - 3.0.1: geminiChat.ts/turn.ts 물리적 이동 (핸드오프 Critical #3, #4)
+  - 3.0.2: messageInspectors 마이그레이션 4파일 (핸드오프 High #5)
+  - 3.0.3: 텔레메트리/Agent 레이어 독립화 (핸드오프 High #6, #7 + M2.7 + Medium
+    #12)
+  - 3.0.4: 변환 브릿지 정리 (핸드오프 Medium #11)
+- **전제 조건 갱신**: Phase 2 완료(✅), EventType 전환 완료(✅) 반영
+- **핸드오프 추적 테이블 추가**: 12개 연기 항목 + M2.7의 해소 상태 및 배정 위치
+  추적
+- **설계서 참조 확대**: phase3_handoff.md, EventType 전환 결과서 추가
+- **산출물 갱신**: providers/gemini/chat.ts, turn.ts 이동 반영
+- **Completion Checklist 보강**: M3.0 해소 항목 7건 추가, 산출물에
+  chat.ts/turn.ts 추가
+- **배경**: Phase 2 핸드오프 Critical #1, #2는 M2.연기(EventType 전환)에서 이미
+  해소됨. 나머지 10개 항목을 M3.0에 체계적으로 배정
+
+## v0.3 (2차 리뷰 반영)
+
+- **산출물 디렉토리 구조 수정**: `eventMapper.ts` 추가로 마스터 플랜과 일관성
+  확보
+- **테스트 파일 목록 정정**:
+  - `session.test.ts` 제거 (존재하지 않는 파일)
+  - `geminiChat.test.ts`, `baseLlmClient.test.ts` 추가 (실제 존재 파일)
+  - `routing/*.test.ts` 7개 파일 추가
+- **3.5.3 테스트 마이그레이션 작업 확대**: 6개 → 8개 항목
+
+## v0.2 (소스코드 기반 리뷰 반영)
+
+- **M3.5 신규 추가**: 테스트 마이그레이션 마일스톤 (3-4일)
+  - 3.5.1: 테스트 파일 분석 (Gemini 특화 테스트 식별)
+  - 3.5.2: 테스트 마이그레이션 전략 (Mock Factory, 어댑터)
+  - 3.5.3: 테스트 파일 마이그레이션 (우선순위별)
+  - 3.5.4: 크로스 프로바이더 테스트 수트
+- **완료 체크리스트 보강**: 테스트 마이그레이션 검증 항목 추가
+- **배경**: Phase 2 리팩토링에 따른 테스트 코드 동기화 필요성 반영
+
+## v0.1 (초기 버전)
+
+- M3.1: Claude 어댑터/변환기 구현 (4-5일)
+- M3.2: OpenAI 어댑터/변환기 구현 (3-4일)
+- M3.3: OpenAI-Compatible 어댑터 템플릿 (3일)
+- M3.4: 통합 테스트/문서/안정화 (5-7일)