# Complete - m-openai-compatible-think-control/04+01,02,03_contract_docs

## 완료 일시

2026-07-03

## 요약

OpenAI-compatible think-control 계약 문서와 dev 운영 문서를 실제 구현 동작(provider별 unsupported/mapping 정책, 기본값, 응답 노출 정책)과 일치시켰다. 루프 2회(FAIL 1회 → PASS)로 종결.

## 루프 이력

| Plan | Review | Verdict | 메모 |
|------|--------|---------|------|
| `plan_local_G03_0.log` | `code_review_local_G03_0.log` | FAIL | 계약이 `reasoning_effort`를 일반 지원처럼 설명하고 dev guide가 vLLM/vLLM-MLX에서 실패 가능한 effort smoke를 안정 사용처럼 안내함 |
| `plan_local_G03_1.log` | `code_review_local_G03_1.log` | PASS | provider별 unsupported/mapping 정책 문서화, 되돌아가 있던 공개 field 문서 복구 포함. 코드 라인 대조와 deterministic `rg` 재실행 일치 |

## 구현/정리 내용

- `agent-contract/outer/openai-compatible-api.md`: Chat Completions 지원 field 목록에 `think`, `reasoning_effort`, `thinking_token_budget`, `include_reasoning` 추가. Think 제어 field semantics, Provider별 think-control 정책(vLLM/vLLM-MLX 내부 `chat_template_kwargs` 매핑과 `unsupported think control` 오류, Lemonade top-level field 전달, unknown provider pass-through), Conflict 정책(400 규칙 5종), Strict output 강등 정책 문서화. 금지 목록에서 `think`를 제거하고 raw `chat_template_kwargs` wrapper 금지 유지.
- `docs/edge-local-dev-guide.md`: Request-level think-control smoke 섹션 추가 — 안정 smoke 조합(`think=false`, 생략, `include_reasoning=false`, budget-only)과 Lemonade-only/provider-specific `reasoning_effort` 조합 분리, vLLM/vLLM-MLX caveat, curl 예시 3종(secret 원문 없음).
- `docs/openai-compatible-api-contract.md`: pointer-only 상태 유지 확인(변경 없음).

## 최종 검증

- `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` - PASS; 계약 원문 field/정책/금지 라인(:168-219)과 dev guide smoke 안내(:236-273)가 코드와 일치, pointer doc 매칭 없음(원문 미복제). 리뷰 시 동일 명령 재실행으로 출력 일치 확인(38 라인).
- `go test ./apps/edge/internal/openai/ ./apps/node/internal/adapters/openai_compat/` - PASS; ok 2 packages. 문서가 설명하는 Edge 검증/Node provider 매핑 동작 회귀 없음.

## Roadmap Completion

- Milestone: `agent-roadmap/phase/knowledge-tool-optimization-extension/milestones/openai-compatible-think-control.md`
- Completed task ids:
  - `contract-docs`: PASS; evidence=`plan_local_G03_1.log`, `code_review_local_G03_1.log`; 수정 문서=`agent-contract/outer/openai-compatible-api.md`, `docs/edge-local-dev-guide.md` (`docs/openai-compatible-api-contract.md`는 pointer-only 확인); verification=`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`
- Not completed task ids: 없음

## 잔여 Nit

- `think=true`+`reasoning_effort=none` 동시 지정 시 disable이 우선한다는 우선순위 문장이 계약에 명시되어 있지 않다. 코드(`apps/node/internal/adapters/openai_compat/openai_compat.go:527`, `:540`)와 모순 서술은 없고 정책 나열 순서로 유추 가능하므로 후속 문서 보강 후보로만 남긴다.

## 후속 작업

- 없음
