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

# Plan - API Contract Docs

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

이 plan은 `01_edge_request_contract`, `02+01_node_provider_mapping`, `03+01_edge_reasoning_visibility`가 PASS complete된 뒤 구현한다. 계약 문서를 실제 코드와 다르게 선반영하지 않는다. 구현 완료는 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운 상태이며, finalization은 code-review 전용이다.

## 배경

현재 계약 원문은 Chat Completions 지원 필드 목록에서 think-control 필드를 빼고, 금지 목록에서는 `think`를 provider 전용 field로 거부한다고 설명한다. 앞선 split들이 공개 field와 provider mapping, response visibility를 구현한 뒤 계약 원문과 dev 운영 문서에 그 결과를 맞춰야 한다. `docs/openai-compatible-api-contract.md`는 계약 원문 포인터이므로 원문 복제 없이 유지한다.

## 사용자 리뷰 요청 흐름

사용자 리뷰 요청은 선택된 Milestone lock decision이 실구현을 막을 때만 review stub의 `사용자 리뷰 요청` 섹션에 기록한다. 문서 문구 조정, evidence 공백, 외부 smoke 실패는 사용자 리뷰가 아니라 follow-up/review finding으로 처리한다.

## 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

## 분석 결과

### 읽은 파일

- `agent-roadmap/phase/knowledge-tool-optimization-extension/milestones/openai-compatible-think-control.md`
- `agent-roadmap/sdd/knowledge-tool-optimization-extension/openai-compatible-think-control/SDD.md`
- `agent-contract/index.md`
- `agent-contract/outer/openai-compatible-api.md`
- `docs/openai-compatible-api-contract.md`
- `docs/edge-local-dev-guide.md`
- `agent-test/local/rules.md`
- `agent-test/local/edge-smoke.md`

### SDD 기준

- SDD: `agent-roadmap/sdd/knowledge-tool-optimization-extension/openai-compatible-think-control/SDD.md`
- 상태: `[승인됨]`, SDD 잠금: `해제`, 사용자 리뷰: 없음
- Acceptance Scenario: S06 -> `contract-docs`
- Evidence Map: S06 requires contract document diff and documentation verification.

### 테스트 환경 규칙

- test_env: `local`
- 읽은 env/profile: `agent-test/local/rules.md`, `agent-test/local/edge-smoke.md`
- 적용 명령: deterministic docs search with `rg --sort path`, plus targeted Go tests from completed code splits if reviewer wants behavior/doc consistency.
- 외부 runner preflight: none. This docs split must not run external dev-runtime smoke.

### 테스트 커버리지 공백

- Docs currently do not describe `think`, `reasoning_effort`, `thinking_token_budget`, `include_reasoning`.
- Docs currently say `think` is forbidden for Chat Completions.
- Dev guide mentions provider runtime `enable_thinking=false` but not request-level overrides or response exposure policy.

### 심볼 참조

- renamed/removed symbol: none.

### 분할 판단

- current subtask: `04+01,02,03_contract_docs`
- dependency from directory name: predecessors `01`, `02`, `03`
- predecessor completion: all missing in active and archive lookup at plan creation.
- split reason: docs must mirror finalized code behavior and unsupported policy; writing them before code would create false public guidance.

### 범위 결정 근거

- Code changes are excluded. If implementation finds docs cannot match code, stop and record a normal review/follow-up issue rather than inventing contract behavior.
- `docs/openai-compatible-api-contract.md` should remain a pointer unless the project rule changes.
- External dev smoke evidence is excluded to `05+01,02,03,04_dev_smoke`.

### 빌드 등급

- `local-G03`: docs-only after code completion, with contract source-of-truth discipline.

## 구현 체크리스트

- [ ] Predecessor `complete.log` for `01`, `02`, and `03`를 확인한 뒤 시작한다.
- [ ] `agent-contract/outer/openai-compatible-api.md`의 Chat Completions field list, field semantics, conflict/unsupported policy, response visibility policy, forbidden field list를 구현 결과와 일치시킨다.
- [ ] `docs/edge-local-dev-guide.md`의 dev-runtime provider pool section에 request-level think-control smoke usage와 default/visibility caveat를 짧게 추가한다.
- [ ] `docs/openai-compatible-api-contract.md`가 원문 포인터로 유지되는지 확인하고 계약 본문을 복제하지 않는다.
- [ ] `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`를 실행해 문서 상태를 확인한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## 의존 관계 및 구현 순서

- `04+01,02,03_contract_docs` decodes to `depends_on=[01,02,03]`.
- Do not implement until all three predecessors have `complete.log`.
- Contract update work should follow `agent-contract/index.md`; if the implementation turn triggers contract-update skill routing, read the matched skill before editing.

### [API-1] OpenAI-Compatible Contract Update

#### 문제

[agent-contract/outer/openai-compatible-api.md](/config/workspace/iop/agent-contract/outer/openai-compatible-api.md:148)의 supported field list lacks think-control fields, and [agent-contract/outer/openai-compatible-api.md](/config/workspace/iop/agent-contract/outer/openai-compatible-api.md:179) forbids `think`.

Before:

```markdown
<!-- agent-contract/outer/openai-compatible-api.md:148 -->
현재 지원하는 Chat Completions request field:
...
- `store`
...
- `options`, `think`, `format`, `keep_alive` 같은 provider/Ollama 전용 request field
```

After:

```markdown
현재 지원하는 Chat Completions request field:
...
- `think`
- `reasoning_effort`
- `thinking_token_budget`
- `include_reasoning`

Think 제어 field:
- `think`: ...
- `include_reasoning`: response exposure only ...
```

#### 해결 방법

- Add field semantics from approved SDD without copying the whole SDD.
- Describe default behavior: omitted fields preserve provider default.
- Describe unsupported policy from implemented code: invalid conflicts are 400 at Edge; provider-specific unsupported mapping returns clear compatibility/run error according to implementation.
- Keep raw `options` and raw `chat_template_kwargs` forbidden.

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

- [ ] `agent-contract/outer/openai-compatible-api.md`: source-of-truth update.

#### 테스트 작성

- No code test. Use deterministic `rg` verification and review against completed code split behavior.

#### 중간 검증

```bash
rg --sort path -n "think|reasoning_effort|thinking_token_budget|include_reasoning|chat_template_kwargs" agent-contract/outer/openai-compatible-api.md
```

Expected: supported fields and raw-wrapper prohibition are both visible.

### [API-2] Dev Operations Docs Update

#### 문제

[docs/edge-local-dev-guide.md](/config/workspace/iop/docs/edge-local-dev-guide.md:236) says Qwen models may include thinking/reasoning output but does not describe request-level control or visibility suppression.

#### 해결 방법

- Add a concise subsection near the dev-runtime provider pool smoke notes.
- Include sample intent, not secrets: `think=false`, omitted default, `include_reasoning=false`.
- Do not write bearer tokens or private endpoint secrets.

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

- [ ] `docs/edge-local-dev-guide.md`: dev-runtime think-control note.
- [ ] `docs/openai-compatible-api-contract.md`: confirm pointer-only state; edit only if link text becomes stale.

#### 테스트 작성

- No code test. Use deterministic `rg` verification.

#### 중간 검증

```bash
rg --sort path -n "think=false|include_reasoning|reasoning_effort|thinking_token_budget" docs/edge-local-dev-guide.md docs/openai-compatible-api-contract.md
```

Expected: dev guide contains request-level guidance; pointer doc does not duplicate contract body unless intentionally updated.

## 수정 파일 요약

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

## 최종 검증

```bash
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
```

Expected: contract source describes supported public fields and keeps raw provider wrappers forbidden; dev guide references request-level smoke usage; pointer doc remains a pointer.

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