<!-- task=m-openai-compatible-think-control/04+01,02,03_contract_docs plan=1 tag=REVIEW_API -->

# Plan - REVIEW_API Contract Docs Follow-up

## 이 파일을 읽는 구현 에이전트에게

이 plan은 code-review FAIL 후속 루프다. 범위는 OpenAI-compatible think-control 계약/dev 문서의 provider별 unsupported 정책 보정으로 제한한다. 사용자에게 직접 질문하거나 선택지를 제시하지 않는다. 선택된 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 막을 때만 `CODE_REVIEW-*-G??.md`의 `사용자 리뷰 요청` 섹션에 evidence를 남기고 멈춘다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/knowledge-tool-optimization-extension/milestones/openai-compatible-think-control.md`
- Task ids:
  - `contract-docs`: OpenAI-compatible 계약 문서와 dev 운영 문서가 요청별 thinking/reasoning 제어 field, provider별 unsupported 정책, 기본값을 설명한다.
- Completion mode: check-on-pass

## Archive Evidence Snapshot

- Current archived plan log: `agent-task/m-openai-compatible-think-control/04+01,02,03_contract_docs/plan_local_G03_0.log`
- Current archived review log: `agent-task/m-openai-compatible-think-control/04+01,02,03_contract_docs/code_review_local_G03_0.log`
- Verdict: FAIL
- Required summary:
  - `agent-contract/outer/openai-compatible-api.md:176` explains `reasoning_effort` values as generally supported, but vLLM/vLLM-MLX reject non-`none` effort with `unsupported think control`.
  - `docs/edge-local-dev-guide.md:245` and `docs/edge-local-dev-guide.md:272` present `reasoning_effort=low` as dev-runtime smoke usage, but the provider pool can route to vLLM/vLLM-MLX where that request fails.
- Affected files:
  - `agent-contract/outer/openai-compatible-api.md`
  - `docs/edge-local-dev-guide.md`
  - `docs/openai-compatible-api-contract.md` verification only; keep pointer-only unless link text becomes stale.
- Code evidence:
  - `apps/node/internal/adapters/openai_compat/openai_compat.go:491`: vLLM/vLLM-MLX reject non-`none` `reasoning_effort`.
  - `apps/node/internal/adapters/openai_compat/openai_compat.go:527`: vLLM/vLLM-MLX map disable to `chat_template_kwargs.enable_thinking=false`.
  - `apps/node/internal/adapters/openai_compat/openai_compat.go:533`: vLLM/vLLM-MLX map budget to `chat_template_kwargs.thinking_token_budget`.
  - `apps/node/internal/adapters/openai_compat/openai_compat.go:540`: Lemonade maps disable to top-level `think=false`.
  - `apps/node/internal/adapters/openai_compat/openai_compat.go:546`: Lemonade forwards non-`none` `reasoning_effort`.
  - `apps/node/internal/adapters/openai_compat/openai_compat.go:549`: Lemonade forwards `thinking_token_budget`.
- Verification evidence:
  - Re-run of `rg --sort path -n "think|reasoning_effort|thinking_token_budget|include_reasoning|chat_template_kwargs" agent-contract/outer/openai-compatible-api.md docs/edge-local-dev-guide.md docs/openai-compatible-api-contract.md` matched the archived review output and exposed the missing provider caveat.
- Roadmap carryover:
  - SDD S06 requires contract document diff and documentation verification for `contract-docs`.
  - Predecessor complete logs exist at:
    - `agent-task/archive/2026/07/m-openai-compatible-think-control/01_edge_request_contract/complete.log`
    - `agent-task/archive/2026/07/m-openai-compatible-think-control/02+01_node_provider_mapping/complete.log`
    - `agent-task/archive/2026/07/m-openai-compatible-think-control/03+01_edge_reasoning_visibility/complete.log`
- Allowed narrow reread if needed:
  - `agent-task/m-openai-compatible-think-control/04+01,02,03_contract_docs/code_review_local_G03_0.log`
  - `agent-task/m-openai-compatible-think-control/04+01,02,03_contract_docs/plan_local_G03_0.log`

## 분석 결과

### SDD 기준

- SDD: `agent-roadmap/sdd/knowledge-tool-optimization-extension/openai-compatible-think-control/SDD.md`
- Acceptance Scenario: S06 -> `contract-docs`
- Evidence Map: S06 requires contract document diff and documentation verification.

### 범위 결정 근거

- 코드 변경은 제외한다. 실제 provider mapping은 이미 `apps/node/internal/adapters/openai_compat`에 구현되어 있으며, 이번 루프는 계약/dev 문서가 그 동작을 정확히 설명하도록 맞춘다.
- `docs/openai-compatible-api-contract.md`는 계약 원문 포인터이므로 본문을 복제하지 않는다.
- 외부 dev-runtime smoke 실행은 `05+01,02,03,04_dev_smoke` 범위다. 이번 루프는 deterministic docs search로 검증한다.

### 빌드 등급

- `local-G03`: 문서 보정만 포함하고, 기존 구현/테스트와 line-level 대조로 검증 가능하다.

## 구현 체크리스트

- [x] `agent-contract/outer/openai-compatible-api.md`에 provider별 think-control unsupported/mapping 정책을 추가한다.
- [x] `docs/edge-local-dev-guide.md`의 request-level think-control smoke 설명과 예시가 dev-runtime provider pool에서 실패 가능한 `reasoning_effort=low` 요청을 안정 smoke처럼 안내하지 않도록 보정한다.
- [x] `docs/openai-compatible-api-contract.md`가 원문 포인터 상태인지 확인하고 계약 본문을 복제하지 않는다.
- [x] `rg --sort path -n "think|reasoning_effort|thinking_token_budget|include_reasoning|chat_template_kwargs|unsupported think control|enable_thinking" agent-contract/outer/openai-compatible-api.md docs/edge-local-dev-guide.md docs/openai-compatible-api-contract.md`를 실행해 문서 상태를 확인한다.
- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## 의존 관계 및 구현 순서

- `04+01,02,03_contract_docs` depends on `01`, `02`, and `03`; predecessor complete logs are listed in `Archive Evidence Snapshot`.
- Contract update work should follow `agent-contract/index.md`; matching contract is `agent-contract/outer/openai-compatible-api.md`.

### [REVIEW_API-1] Provider Unsupported Policy Docs

#### 문제

계약 문서와 dev guide가 `reasoning_effort`를 일반 지원 field처럼 설명하지만, 실제 provider mapping은 provider별로 다르다. vLLM/vLLM-MLX는 `reasoning_effort=none`만 disable 의미로 처리하고 `low`/`medium`/`high`는 unsupported error로 반환한다. Lemonade는 non-`none` effort와 budget을 top-level field로 전달한다.

#### 해결 방법

- 계약 원문의 Think 제어 field 섹션 아래에 provider별 정책을 추가한다.
- vLLM/vLLM-MLX:
  - `think=false` 또는 `reasoning_effort=none` -> 내부 `chat_template_kwargs.enable_thinking=false`
  - `think=true` 또는 budget-only -> 내부 `chat_template_kwargs.enable_thinking=true`
  - `thinking_token_budget` -> 내부 `chat_template_kwargs.thinking_token_budget`
  - `reasoning_effort=low|medium|high` -> unsupported think-control error
- Lemonade:
  - `think` -> top-level `think`
  - `reasoning_effort=low|medium|high` -> top-level `reasoning_effort`
  - `thinking_token_budget` -> top-level `thinking_token_budget`
  - `reasoning_effort=none` -> `think=false`, effort field omitted
- Dev guide는 stable smoke 예시를 `think=false`, omitted default, `include_reasoning=false`, 또는 budget-only로 유지하고, `reasoning_effort=low`는 Lemonade-only/provider-specific caveat가 없으면 기본 smoke 예시에서 제거한다.

#### 수정 파일 및 체크리스트

- [x] `agent-contract/outer/openai-compatible-api.md`: provider별 unsupported/mapping 정책 추가.
- [x] `docs/edge-local-dev-guide.md`: dev-runtime think-control smoke caveat와 예시 보정.
- [x] `docs/openai-compatible-api-contract.md`: pointer-only 상태 확인.

#### 테스트 작성

- 코드 테스트 없음. deterministic `rg` 검증과 기존 Node adapter 코드 라인 대조로 충분하다.

#### 중간 검증

```bash
rg --sort path -n "unsupported think control|enable_thinking|reasoning_effort|thinking_token_budget|include_reasoning" agent-contract/outer/openai-compatible-api.md docs/edge-local-dev-guide.md
```

Expected: provider별 unsupported/mapping 정책과 stable dev smoke guidance가 모두 보인다.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `agent-contract/outer/openai-compatible-api.md` | REVIEW_API-1 |
| `docs/edge-local-dev-guide.md` | REVIEW_API-1 |
| `docs/openai-compatible-api-contract.md` | REVIEW_API-1 verification only |

## 최종 검증

```bash
rg --sort path -n "think|reasoning_effort|thinking_token_budget|include_reasoning|chat_template_kwargs|unsupported think control|enable_thinking" agent-contract/outer/openai-compatible-api.md docs/edge-local-dev-guide.md docs/openai-compatible-api-contract.md
```

Expected: contract source describes supported public fields, provider별 unsupported/mapping policy, strict-output default, response visibility, and raw-wrapper prohibition; dev guide references request-level smoke usage without presenting vLLM/vLLM-MLX-unsupported `reasoning_effort=low` as a stable provider-pool smoke; pointer doc remains a pointer.

모든 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
