# Phase: 지식과 도구 최적화 확장

## 상태

[진행중]

## 목표

Ollama serving 경로와 운영 기반이 안정화된 뒤, execution preset, 단계 호출, tool/schema 강제, output validation, retry/fallback과 누적 요청 컨텍스트 구성을 IOP의 추론 최적화 계층으로 확장한다.
첫 vertical slice는 Claude Code의 Anthropic Messages request를 Gemini OpenAI Chat provider로 안전하게 변환하는 protocol bridge 호환을 정리한다. 이 기반 위에서 외부 model을 fixed `light` execution preset에 매핑하고 Claude의 Anthropic Messages 요청 정확히 1회를 유지한 채 승인된 IOP Node가 request-scoped workspace와 도구 실행을 소유하며 Gemini plan → ornith-fast work → Gemini review/repair를 하나의 model 실행처럼 완료한다.
그 다음 단일 요청 lightweight Plan/Review를 장기 작업에 맞는 `heavy` mode로 확장하고, Edge가 외부 model에 매핑된 preset의 허용 mode 중 요청 난이도·기능·예산에 맞는 실행 경로를 고르는 cloud-first 하이브리드 라우팅으로 연결한다.
cloud-first route evidence가 충분히 쌓이면 동일한 mode decision contract를 쓰는 RAG 기반 local routing model을 shadow/canary로 검증해 운영 기본 경로로 점진 전환한다.
caller-neutral 누적 요청 컨텍스트 최적화, repository 장기 기억 RAG, advisor와 Context Hook은 routing evidence RAG와 서로 다른 후속 기능으로 분리한다.
이 Phase는 특정 Agent Shell에 종속되지 않고 OpenAI-compatible, A2A, IOP native protocol 중 맞는 표면에서 공통 최적화 책임을 제공하는 방향을 다룬다.
단일 요청 Agent 실행은 현재 완료된 제품 상태를 기준선으로 유지한다. 구체적 결함이 재현되면 해당 제품 소유 영역에서 국소 수정·검증하며, 측정 도구는 제품 완료 조건이나 실행 차단을 소유하지 않는다.

## Milestone 흐름

완료된 Milestone은 archive 경로를 가리키고, 검토중, 진행중, 계획, 스케치 또는 보류 Milestone은 이 Phase 하위 `milestones/` 경로를 가리킨다.
이 흐름은 해당 Phase 안의 상태 정리이며, Phase를 가로지르는 실행 순서는 아니다.
Milestone은 완료, 검토중, 진행중, 계획, 스케치 또는 보류 상태 그룹으로 정리한다.
Phase를 가로지르는 실제 다음 작업 선택은 [전역 마일스톤 실행 순서](../../priority-queue.md)를 우선한다.

- [완료] Tool Call Runtime 검증 재시도 MVP
  - 경로: [tool-call-runtime-validation-retry](../../archive/phase/knowledge-tool-optimization-extension/milestones/tool-call-runtime-validation-retry.md)
  - 요약: 명시적 `tools[]`/`tool_choice` 계약이 있는 OpenAI-compatible 요청에서 IOP 내부 provider 응답의 마지막 tool call을 검증하고, schema 불일치 시 같은 요청을 bounded exact replay로 재시도하는 runtime-only MVP를 구현한다.

- [완료] OpenAI-compatible Think 제어 MVP
  - 경로: [openai-compatible-think-control](../../archive/phase/knowledge-tool-optimization-extension/milestones/openai-compatible-think-control.md)
  - 요약: OpenAI-compatible Chat Completions 요청에서 thinking/reasoning 생성과 응답 노출을 요청별로 제어하고 provider별 option 매핑과 unsupported 정책을 구현한다.

- [완료] OpenAI-compatible Tool Call Boundary Hardening
  - 경로: [openai-compatible-tool-call-boundary-hardening](../../archive/phase/knowledge-tool-optimization-extension/milestones/openai-compatible-tool-call-boundary-hardening.md)
  - 요약: provider-pool/OpenAI-compatible 응답에서 raw text tool-call block, unknown tool name, chat-template sentinel token이 클라이언트 화면으로 새지 않도록 Edge tool-call 경계를 검증/정규화한다.

- [완료] Stream Evidence Gate Core
  - 경로: [stream-evidence-gate-core](../../archive/phase/knowledge-tool-optimization-extension/milestones/stream-evidence-gate-core.md)
  - 요약: codec의 response-start/event를 첫 safe release까지 stage하고 500-rune rolling, bounded terminal/fragment hold, pre-read 기본값/절대 상한 16 MiB raw-canonical ingress snapshot과 request-snapshot 기반 Filter Registry를 제공한다. Gate Coordinator가 single-flight all-complete evaluation/commit을, RecoveryPlan Coordinator와 host adapter가 strategy별 budget과 최초 실행 제외 기본값/절대 상한 3회의 request 전체 cap 아래 abort·optional one-shot plan prepare·lossless rebuild·cycle별 single re-admission을 담당한다.

- [완료] [route-01] IOP 실행 프리셋과 Hot Path
  - 경로: [[route-01] IOP 실행 프리셋과 Hot Path](../../archive/phase/knowledge-tool-optimization-extension/milestones/iop-hot-path-one-shot-execution.md)
  - 요약: execution preset/config generation, logical request coordinator, direct/light stage, Anthropic/Chat terminal과 관측 기반을 완료했다. caller tool continuation은 최종 제품 원칙이 아니며 exact single-request 내부 실행은 별도 `[route-02]`로 분리했다.

- [계획] [output-01] OpenAI-compatible 출력 검증 필터
  - 경로: [[output-01] OpenAI-compatible 출력 검증 필터](milestones/openai-compatible-output-validation-filters.md)
  - 요약: 실제 의미 필터 전에 local/dev deterministic diagnostic mock으로 실제 codec/Core/Arbiter/recovery/ReleaseSink의 pass·observe-only·blocking recovery와 raw-free timeline을 관측하는 smoke를 선행한다. 이후 OpenAI-compatible Chat Completions와 Responses provider stream의 반복, assistant-history anchor, 동일 tool/action, schema/provider error를 caller-neutral하게 판정하는 Core `Filter` 구현체를 제공한다. filter는 model/provider별 on/off와 semantic decision/RecoveryIntent만 소유하고, 병렬 평가·all-complete arbitration·retry budget·request rebuild/re-admission은 Stream Evidence Gate Core의 공통 Coordinator를 소비한다.

- [계획] [output-02] OpenAI-compatible Incomplete Tool Call Syntax Gate
  - 경로: [[output-02] OpenAI-compatible Incomplete Tool Call Syntax Gate](milestones/openai-compatible-incomplete-tool-call-syntax-gate.md)
  - 요약: terminal provider 응답에서 완성된 tool call 수와 raw/reasoning/content tool-call marker scanner 결과가 불일치하는 케이스를 runtime에서 deterministic하게 판정해 incomplete tool-call syntax로 분류한다.

- [완료] [route-02] IOP 단일 요청 Agent 실행
  - 경로: [[route-02] IOP 단일 요청 Agent 실행](../../archive/phase/knowledge-tool-optimization-extension/milestones/iop-owned-single-request-agent-execution.md)
  - 요약: Claude→IOP `/v1/messages` POST를 정확히 1회로 고정하고 승인된 IOP Node의 request-scoped workspace/tool executor로 Gemini plan → ornith-fast work → Gemini review/repair를 내부에서 완료했다. 실제 Claude S12 smoke에서 ingress 1회, 단일 terminal, 정확한 workspace 결과와 cleanup을 검증했다.

- [완료] [bench-01] Agent 비교 벤치마크 파이프라인 준비
  - 경로: [[bench-01] Agent 비교 벤치마크 파이프라인 준비](../../archive/phase/knowledge-tool-optimization-extension/milestones/agent-comparison-benchmark-pipeline.md)
  - 요약: 모델·caller·prompt·반복 횟수를 manifest로 바꾸고 Claude Code, agy, Codex의 IOP 연결부터 finish/idle, 시간·token·웹 검증·익명 채점·Markdown 보고까지 같은 pipeline으로 재현한다.

- [완료] [bench-route-01] 벤치 경로 최소 HTML 스모크
  - 경로: [[bench-route-01] 벤치 경로 최소 HTML 스모크](../../archive/phase/knowledge-tool-optimization-extension/milestones/benchmark-route-minimal-html-smoke.md)
  - 요약: 벤치에 사용할 9개 caller/model/route 조합이 고정된 최소 `index.html` 생성 요청으로 모두 통과했고, 실패 경로만 귀속·국소 수정·재검증했다.

- [폐기] [bench-02] IOP 원샷 Agent 모델 비교 벤치마크
  - 경로: [[bench-02] IOP 원샷 Agent 모델 비교 벤치마크](../../archive/phase/knowledge-tool-optimization-extension/milestones/iop-one-shot-agent-model-comparison.md)
  - 요약: 전용 harness의 정합성과 복구가 제품 안정성보다 우선되는 목적 역전으로 2026-08-13 폐기했다. 기존 결과와 계획은 재개하지 않는다.

- [완료] [bench-lite-01] 초경량 Agent 모델 비교
  - 경로: [[bench-lite-01] 초경량 Agent 모델 비교](../../archive/phase/knowledge-tool-optimization-extension/milestones/thin-agent-model-comparison-benchmark.md)
  - 요약: 무경합 9개 경로의 외부 시간과 caller-visible 계약을 분리해 재측정했다. provider 실행은 9/9 종료됐고 완전 계약은 6/9이며, Claude caller의 workspace/source projection 3건을 남은 경계 이슈로 분리했다.

- [계획] [surface-01] Inference API Surface와 실행 Lifecycle 책임 경계 리팩터링
  - 경로: [[surface-01] Inference API Surface와 실행 Lifecycle 책임 경계 리팩터링](milestones/inference-api-surface-execution-lifecycle-refactor.md)
  - 요약: `iop-s0`의 bench-02 결과와 제품 delta가 `dev`에 정합화된 뒤 OpenAI Chat/Responses, Anthropic Messages, Gemini의 wire 계약은 surface별로 유지하고, 기존 provider service 경계를 재사용하며 cross-surface handler 재진입과 단계별 lifecycle 소유권만 정리한다.

- [스케치] [output-03] OpenAI-compatible Runtime Output Integrity Filter
  - 경로: [[output-03] OpenAI-compatible Runtime Output Integrity Filter](milestones/openai-compatible-runtime-output-integrity-filter.md)
  - 요약: terminal assistant 응답이 content, valid tool call, 명시 허용 structured/error finish 중 하나를 만족해야 한다는 runtime invariant를 정의하고, empty terminal, reasoning-only, incomplete tool-call syntax 같은 deterministic violation을 공통 filter pipeline과 bounded retry 정책으로 묶는다.

- [스케치] [judge-01] LLM 판별 기반 Missing Tool Call 재시도 Gate
  - 경로: [[judge-01] LLM 판별 기반 Missing Tool Call 재시도 Gate](milestones/llm-judged-missing-tool-call-retry-gate.md)
  - 요약: Pi/dev-corp 같은 tool-bearing 요청에서 provider가 tool 사용 의도를 reasoning했지만 tool call 없이 종료하는 케이스를 LLM judge와 buffered retry 후보로 재검토하고, 정확한 종료/재시도 정책이 정의될 때까지 구현을 잠근다.

- [스케치] [route-03] Heavy Plan/Review 실행과 검증 MVP
  - 경로: [[route-03] Heavy Plan/Review 실행과 검증 MVP](milestones/knowledge-tool-validation-optimization.md)
  - 요약: 단일 요청 Hot Path의 lightweight Plan/Review를 `heavy` mode로 확장해 `heavy-only` preset에서 장기 작업의 plan 갱신, 검증, review/repair cycle, 중단·재개와 stage binding을 먼저 검증한다. mixed mode 선택은 route-04에서 연결한다.

- [스케치] [route-04] Execution Preset 하이브리드 Mode 라우팅
  - 경로: [[route-04] Execution Preset 하이브리드 Mode 라우팅](milestones/openai-compatible-hybrid-request-execution-routing.md)
  - 요약: 폐기된 하이브리드 라우팅 설계에서 IOP Edge 책임만 복원해 cloud advisory와 deterministic hard gate를 결합하고, 이미 선택된 preset의 allowed mode 중 요청 수준에 맞는 실행 경로를 최종 결정한다.

- [스케치] [route-05] RAG 기반 Local Routing Model 운영 전환
  - 경로: [[route-05] RAG 기반 Local Routing Model 운영 전환](milestones/rag-local-routing-model-operations.md)
  - 요약: cloud-first route evidence가 충분한 품질·규모 gate를 통과하면 같은 decision contract를 쓰는 RAG local router를 shadow, canary, primary 순서로 승격하고 cloud judge를 fallback·audit으로 유지한다.

- [스케치] [judge-02] Tool Call 판정 모델 Gate 리뷰
  - 경로: [[judge-02] Tool Call 판정 모델 Gate 리뷰](milestones/tool-call-validator-model-gate-review.md)
  - 요약: 명시적 tool schema만으로 판정할 수 없는 자연어/텍스트/agent-specific tool call 후보를 별도 validator 모델로 분류할지, 어떤 조건에서 허용할지 사용자 리뷰가 필요한 결정 항목으로 스케치한다.

- [스케치] [context-01] Provider 입력 컨텍스트 선택과 축소
  - 경로: [[context-01] Provider 입력 컨텍스트 선택과 축소](milestones/request-context-assembly-optimization.md)
  - 요약: provider 입력으로 누적된 history를 현재 요청 관련성에 따라 과거 요청-답변 단위로 먼저 절단하고, 유지한 답변·tool/search 결과 안에서도 필요한 문단·코드 블록·구간만 남기는 caller-neutral 방향을 스케치한다. provider 응답을 사용자에게 전달하는 출력 경계는 다루지 않는다.

- [스케치] [memory-01] 장기 기억과 RAG 업데이트 사이클 (2차)
  - 경로: [[memory-01] 장기 기억과 RAG 업데이트 사이클 (2차)](milestones/long-term-memory-rag-second-wave.md)
  - 요약: 특정 repo 장기 기억, RAG 저장소, update cycle, MCP 기반 context 절약은 MVP 이후 2차 후보로 스케치한다.

- [스케치] [advisor-01] Advisor와 Context Hook 확장 (2차)
  - 경로: [[advisor-01] Advisor와 Context Hook 확장 (2차)](milestones/advisor-context-hook-second-wave.md)
  - 요약: advisor 역할과 여러 최적화·검증 기능을 실행 흐름에 연결할 수 있는 Context Hook의 호출·실패·노출 경계를 별도 2차 후보로 스케치한다.

## Phase 경계

- 이 Phase는 Ollama 경로와 Edge model group queue가 안정적인 serving 경로로 검증된 뒤 시작한다.
- 이 Phase는 Control Plane/Client 운영 기반과 운영 관측 MVP 없이 현재 provider 확장 Phase 안으로 당겨 구현하지 않는다.
- 기본 `/v1/models`, `/v1/chat/completions`, Edge-Node relay, Ollama option/API passthrough 안정화는 `Ollama 서빙 안정화 기반` Phase 책임이다.
- 추가 추론 서버 provider의 adapter/config/target/model 매핑 표준화는 `추론 서버 provider 확장` Phase 책임이다.
- Claude Code용 Gemini Chat bridge, 단일 요청 Agent 실행, heavy Plan/Review, 하이브리드 라우팅은 순서대로 provider protocol 호환, fixed `light` preset/coordinator와 IOP-owned request-scoped workspace/tool runtime, 장기 작업용 `heavy`, Edge 범용 mode 선택 정책을 구성한다.
- 외부 model 선택이 execution preset을 고정하고, IOP Edge는 요청 사실과 model advisory를 바탕으로 그 preset의 allowed mode와 stage별 canonical model binding을 최종 확정한다. IOP Node는 provider stage 실행·취소·상태·usage 보고뿐 아니라 preset이 승인한 request-scoped workspace 도구 실행을 담당한다.
- plan-bearing one-shot mode는 IOP Node가 승인된 workspace root 아래 `.iop/job/<request_id>/plan.md`와 `review.md`를 직접 생성·읽기·갱신·정리한다. 내부 model tool call/result는 IOP coordinator가 소비하며 Claude에 후속 tool result 요청을 요구하지 않는다.
- 각 stage의 routing, plan, work, review, defect와 repair는 outer stream에 redacted 진행 요약으로만 투영한다. 내부 provider reasoning, control prompt, tool protocol·argument/result, credential과 stage terminal은 공개하지 않고 최종 사용자 결과와 outer terminal만 완결된 응답으로 반환한다.
- target agent나 외부 workflow 제품의 process/state를 실행 의존성으로 연결하지 않는다. 범용 interactive shell과 장기 workflow는 제외하지만, execution preset의 request-scoped workspace/tool executor는 IOP가 소유한다.
- 공식 caller 경로는 현재 제품 기준선을 유지한다. 벤치 준비에서는 벤치 대상 경로만 최소 HTML로 얕게 확인하고, 구체적 회귀가 발생한 경로만 해당 제품 소유 영역에서 검증한다. 전수 재검증 campaign이나 측정 도구를 제품 완료 gate로 두지 않는다.
- cloud model은 초기 semantic judge/teacher 역할을 하고, 충분한 정제 evidence가 쌓인 뒤 RAG local router로 운영 기본을 전환한다. 두 경우 모두 최종 권한은 deterministic hard gate를 적용하는 Edge arbiter에 남는다.
- routing evidence RAG는 route 판정 전용이고, repository 장기 기억 RAG·누적 요청 context·advisor·Context Hook과 corpus/index/평가를 공유하지 않는다.
