# 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 실행의 정식 smoke 이후 비교 검증은 별도 benchmark lane에서 수행하며, 준비 pipeline은 병렬 구축하고 실제 scored 비교는 route-02 완료 뒤 실행한다.

## 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 실행](milestones/iop-owned-single-request-agent-execution.md)
  - 요약: Claude→IOP `/v1/messages` POST를 정확히 1회로 고정하고, 승인된 IOP Node의 request-scoped workspace/tool executor로 Gemini 3.6 Flash high plan → ornith-fast work → Gemini 3.6 Flash high review/repair를 내부에서 끝낸 뒤 하나의 outer stream과 terminal을 반환한다.

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

- [계획] [bench-02] IOP 원샷 Agent 모델 비교 벤치마크
  - 경로: [[bench-02] IOP 원샷 Agent 모델 비교 벤치마크](milestones/iop-one-shot-agent-model-comparison.md)
  - 요약: route-02 정식 smoke와 benchmark pipeline 준비 뒤 dev `../iop-s2`에서 동일 정적 웹 fixture로 9개 IOP 경유 단독·하이브리드 caller 조합을 각각 한 번 실행해 속도·token·품질을 비교한다.

- [스케치] [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가 소유한다.
- benchmark skill/pipeline은 제품 coordinator가 아니라 dev 검증 harness다. 준비 작업은 route-02와 병렬일 수 있지만 실제 scored 비교는 route-02 정식 기능·필수 smoke와 benchmark pipeline 완료 뒤 별도 Milestone에서 수행한다.
- 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/평가를 공유하지 않는다.
