iop/agent-roadmap/phase/knowledge-tool-optimization-extension/PHASE.md

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

## 상태

[계획]

## 목표

Ollama serving 경로와 운영 기반이 안정화된 뒤, 단계 호출, tool/schema 강제, output validation, retry/fallback과 누적 요청 컨텍스트 구성을 IOP의 추론 최적화 계층으로 확장한다.
첫 vertical slice인 IOP Hot Path는 OpenAI-compatible `model=iop` 한 번의 요청 안에서 빠른 cloud `Gemini 3.6 Flash`와 RTX 5090 local target `ornith-fast`를 조합하고, model advisory와 Edge 최종 판정, request-local execution profile, route evidence의 기본을 구축한다.
그 다음 analysis directive/generation/verification을 올바른 request-local plan/review 단계로 일반화하고, Edge가 요청 난이도·기능·예산에 따라 실행 형태와 stage별 adapter/target을 고르는 cloud-first 하이브리드 라우팅으로 연결한다.
cloud-first 운영 근거가 충분히 쌓이면 동일한 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 중 맞는 표면에서 공통 최적화 책임을 제공하는 방향을 다룬다.

## 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을 담당한다.

- [계획] [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로 분류한다.

- [스케치] [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-01] IOP Hot Path One-shot 실행 경로
  - 경로: [[route-01] IOP Hot Path One-shot 실행 경로](milestones/iop-hot-path-one-shot-execution.md)
  - 요약: 외부 `model=iop` 요청을 Gemini 3.6 Flash 즉답 또는 micro-plan, RTX 5090 `ornith-fast` 실행, Gemini 단일 리뷰·보정으로 처리하면서 model advisory, Edge arbiter, request-local profile과 route evidence의 첫 vertical slice를 구축한다.

- [스케치] [route-02] 단계 호출과 검증 최적화 MVP
  - 경로: [[route-02] 단계 호출과 검증 최적화 MVP](milestones/knowledge-tool-validation-optimization.md)
  - 요약: Hot Path의 micro-plan/review를 analysis directive, generation, verification의 bounded request-local 실행 형태로 일반화하고 Edge가 선택할 stage binding 계약을 스케치한다.

- [스케치] [route-03] OpenAI-compatible 하이브리드 요청 수준·실행 형태 라우팅
  - 경로: [[route-03] OpenAI-compatible 하이브리드 요청 수준·실행 형태 라우팅](milestones/openai-compatible-hybrid-request-execution-routing.md)
  - 요약: 폐기된 하이브리드 라우팅 설계에서 IOP Edge 책임만 복원해 cloud model advisory와 deterministic hard gate를 결합하고, Edge가 요청 난이도에 맞는 execution shape와 stage별 adapter/target을 최종 결정한다.

- [스케치] [route-04] RAG 기반 Local Routing Model 운영 전환
  - 경로: [[route-04] 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 책임이다.
- Hot Path, request-local 단계 호출, 하이브리드 라우팅은 순서대로 첫 profile, 올바른 실행 형태 일반화, Edge 범용 선택 정책을 구성한다.
- IOP Edge는 요청 사실과 model advisory를 바탕으로 execution shape와 stage별 adapter/target을 최종 확정한다. IOP Node는 확정된 stage 실행·취소·상태·usage 보고만 담당한다.
- 이 Phase의 plan/review는 하나의 요청 안에서만 유지되는 transient inference stage다. durable Plan/Milestone/CODE_REVIEW artifact, 승인·continuation·workspace mutation 같은 workflow process는 범위 밖이다.
- 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/평가를 공유하지 않는다.