<!-- task=m-node-provider-first-config-surface/05+01_dev_runtime_docs plan=1 tag=REVIEW_DOCS -->

# Plan - REVIEW_DOCS

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

이 작업은 이전 리뷰 FAIL의 좁은 follow-up이다. 문서/config/test-rule 정리 뒤 반드시 `CODE_REVIEW-local-G04.md`의 구현 에이전트 소유 섹션을 실제 변경 내용과 검증 출력으로 채운다. active 파일은 그대로 두고 리뷰 준비 상태로 멈춘다. 최종 판정, `.log` 아카이브, `complete.log`, task archive 이동은 code-review 전용이다.

선택된 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 막을 때만 review stub의 `사용자 리뷰 요청`을 채우고 멈춘다. 구현 중 직접 사용자에게 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 환경/secret/service blocker, 일반 범위 조정, 검증 증거 공백은 사용자 리뷰 요청이 아니며 `검증 결과` 또는 후속 리뷰에서 다룬다.

## 배경

이전 구현은 provider-first 문구를 추가했지만 실제 예제 일부가 top-level `models[]` provider catalog가 아니라 `openai.models` 문자열 목록을 사용했다. SDD S06은 dev-runtime guide/config 예시에서 Mac CLI resource와 MLX vLLM provider resource가 같은 `providers[]`에 나열되고, `adapters` 중복 선언이 기본 경로가 아니어야 한다. 이번 follow-up은 S06에 맞게 예시와 local smoke rule을 정렬한다.

## 사용자 리뷰 요청 흐름

사용자 리뷰는 선택된 Milestone lock 결정만 active review stub의 `사용자 리뷰 요청` 섹션에 기록한다. 직접 사용자 프롬프트는 금지하며, code-review가 요청을 검증하고 필요할 때만 `USER_REVIEW.md`를 쓴다.

## Archive Evidence Snapshot

- Prior active task: `agent-task/m-node-provider-first-config-surface/05+01_dev_runtime_docs`
- Archived plan log: `agent-task/m-node-provider-first-config-surface/05+01_dev_runtime_docs/plan_local_G04_0.log`
- Archived review log: `agent-task/m-node-provider-first-config-surface/05+01_dev_runtime_docs/code_review_local_G04_0.log`
- Verdict: FAIL
- Required summary:
  - `docs/edge-local-dev-guide.md:53` provider-first example uses `openai.models` instead of top-level `models[].providers`.
  - `configs/edge.yaml:114` provider-first example does not show Mac CLI resources and `mac-mlx-vllm` provider resource in one `providers[]` list as SDD S06 requires.
  - `agent-test/local/edge-smoke.md:84` local test rule still presents the basic field baseline as `openai.adapter`/`openai.models`/`nodes: []` without a separated provider-first dev-runtime baseline.
- Verification evidence:
  - `rg --sort path "model_routes|nodes\\[\\]\\.adapters|adapter:" configs docs agent-test/local`
  - `go test ./packages/go/config`
  - `go run ./apps/edge/cmd/edge --config configs/edge.yaml config check`
- Roadmap carryover: keep `dev-runtime-docs` under the existing Roadmap Targets.
- Narrow reread allowed if needed: the two archived logs listed above only.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/operational-observability-provider-management/milestones/node-provider-first-config-surface.md`
- Task ids:
  - `dev-runtime-docs`: provider-first dev-runtime inventory, config examples, guide, test rules
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/project/domain/platform-common/rules.md`
- `agent-ops/rules/project/domain/testing/rules.md`
- `agent-test/local/rules.md`
- `agent-test/local/edge-smoke.md`
- `agent-test/local/platform-common-smoke.md`
- `agent-roadmap/phase/operational-observability-provider-management/milestones/node-provider-first-config-surface.md`
- `agent-roadmap/sdd/operational-observability-provider-management/node-provider-first-config-surface/SDD.md`
- `agent-contract/index.md`
- `agent-contract/inner/edge-config-runtime-refresh.md`
- `agent-contract/inner/edge-node-runtime-wire.md`
- `packages/go/config/config.go`
- `packages/go/config/config_test.go`
- `configs/edge.yaml`
- `docs/edge-local-dev-guide.md`
- `agent-task/m-node-provider-first-config-surface/05+01_dev_runtime_docs/plan_local_G04_0.log`
- `agent-task/m-node-provider-first-config-surface/05+01_dev_runtime_docs/code_review_local_G04_0.log`

### SDD 기준

- SDD: `agent-roadmap/sdd/operational-observability-provider-management/node-provider-first-config-surface/SDD.md`
- 상태: `[승인됨]`, SDD 잠금 해제, 사용자 리뷰 없음
- 대상 Acceptance Scenario: S06 -> Milestone Task `dev-runtime-docs`
- Evidence Map: docs/inventory/stale-reference check, `dev-runtime-docs` Roadmap Completion과 `rg` stale-reference verification
- 구현 영향: 예시는 top-level `models[]` catalog와 `nodes[].providers[]` resource list를 함께 보여야 하며, Mac CLI + MLX vLLM provider가 같은 node `providers[]` 안에서 확인 가능해야 한다.

### 테스트 환경 규칙

- test_env: local
- 적용 규칙: `agent-test/local/rules.md`, `agent-test/local/edge-smoke.md`, `agent-test/local/platform-common-smoke.md`
- 적용 명령:
  - `rg --sort path "model_routes|nodes\\[\\]\\.adapters|adapter:" configs docs agent-test/local`
  - `go run ./apps/edge/cmd/edge --config configs/edge.yaml config check`
  - `go test ./packages/go/config`
- Go test cache output은 config loader 코드/fixture 미변경이면 허용한다. `configs/edge.yaml`을 바꿨으므로 config check는 반드시 실제 실행한다.

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

- Markdown/YAML comment 예시는 unit test가 직접 검증하지 않는다. `rg` stale-reference check와 `config check` evidence로 SDD S06 충족을 판단한다.
- `agent-test/local/edge-smoke.md`는 문서형 테스트 기준이므로 별도 코드 테스트를 추가하지 않는다.

### 심볼 참조

- renamed/removed symbol 없음.

### 분할 판단

- 기존 split subtask `05+01_dev_runtime_docs` 내부 follow-up이다.
- 변경 범위는 문서/config/test-rule 정렬로 작고, 같은 SDD S06 evidence에 묶인다. 추가 subtask split은 필요 없다.

### 범위 결정 근거

- runtime schema, mapper, dispatch, config refresh 구현 변경은 제외한다.
- dev-runtime 실제 원격 배포와 full-cycle smoke 재수행은 `06+04,05_full_cycle_smoke` 범위다.
- secret, token, private endpoint 원문은 tracked 파일에 쓰지 않는다.

### 빌드 등급

- `local-G04`: SDD/계약 기준이 명확하고 변경은 bounded docs/config/test-rule 정렬이며 deterministic local commands로 확인 가능하다.

## 구현 체크리스트

- [ ] `docs/edge-local-dev-guide.md`의 provider-first 예제를 top-level `models[]` + `nodes[].providers[]` catalog로 고치고 `openai.models`를 provider-pool 예제로 쓰지 않는다.
- [ ] `configs/edge.yaml`의 provider-first 예시가 CLI resources와 `mac-mlx-vllm` provider resource를 같은 node `providers[]`에 보여주고, top-level `models[]` catalog가 provider id를 참조하도록 정리한다.
- [ ] `agent-test/local/edge-smoke.md`에서 legacy/basic field profile과 provider-first dev-runtime baseline을 분리하고 provider-first source of truth 기준을 명시한다.
- [ ] `rg --sort path "model_routes|nodes\\[\\]\\.adapters|adapter:" configs docs agent-test/local`, `go run ./apps/edge/cmd/edge --config configs/edge.yaml config check`, `go test ./packages/go/config`를 실행하고 남은 legacy reference가 의도적 compat 설명인지 기록한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [REVIEW_DOCS-1] Provider-First Guide Example Uses Top-Level Catalog

#### 문제

`docs/edge-local-dev-guide.md:53`의 provider-first 예제는 설명에서 `models[].providers[provider_id]` 연결을 말하지만 실제 YAML은 `openai.models`만 사용한다. `packages/go/config/config.go:61`과 `config.go:248` 기준 provider-pool catalog는 top-level `models[]`다.

#### 해결 방법

예제에 top-level `models:`를 추가하고 `nodes[].providers[].id`를 참조하게 한다. `openai.adapter`/`openai.target`은 legacy fallback 설명으로만 남기고, provider-pool 예제에서 `openai.models`를 routing catalog처럼 쓰지 않는다.

Before (`docs/edge-local-dev-guide.md:53`):

```yaml
openai:
  enabled: true
  listen: "0.0.0.0:18081"
  adapter: "ollama"
  target: "gemma4:26b"
  models:
    - "gemma4:26b"
```

After direction:

```yaml
models:
  - id: "gemma4:26b"
    providers:
      ollama-gemma: "gemma4:26b"

openai:
  enabled: true
  listen: "0.0.0.0:18081"
  adapter: "ollama" # legacy fallback only
  target: "gemma4:26b"
```

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

- [ ] `docs/edge-local-dev-guide.md`: top-level `models[]` catalog 예제 추가.
- [ ] `docs/edge-local-dev-guide.md`: `openai.models`가 provider-pool source of truth처럼 보이는 문구 제거 또는 legacy-only로 재분류.

#### 테스트 작성

코드 테스트는 추가하지 않는다. Markdown 예제 정합성은 stale-reference check와 config 계약 대조로 검증한다.

#### 중간 검증

```bash
rg --sort path "openai\\.models|models\\[\\]\\.providers|models:" docs/edge-local-dev-guide.md
```

기대 결과: provider-first 예제는 top-level `models[]`와 `models[].providers` 연결을 보여주고, `openai.models`가 나오면 legacy-only 설명으로 분류 가능해야 한다.

### [REVIEW_DOCS-2] Config Example Shows CLI And Mac MLX In One Providers List

#### 문제

`configs/edge.yaml:114`의 provider-first 기본 예시는 CLI resources만 보여주며 SDD S06의 Mac CLI + MLX vLLM provider 동시 예시를 충족하지 못한다. 또한 `configs/edge.yaml:89`의 provider type 설명은 계약의 `openai_compat` provider-first 실행 필드를 선명하게 안내하지 못한다.

#### 해결 방법

`configs/edge.yaml`의 recommended provider-first 예시에 top-level `models[]` catalog를 두고, 같은 Mac node `providers[]` 안에 `codex`/`codex-exec` 같은 CLI resources와 `mac-mlx-vllm` OpenAI-compatible provider resource를 함께 둔다. MLX provider는 tracked secret을 쓰지 말고 local endpoint, served model, capacity만 예시로 둔다. legacy `adapters` 예시는 compat 섹션에만 남긴다.

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

- [ ] `configs/edge.yaml`: top-level `models[]` example이 `mac-mlx-vllm` provider id를 참조한다.
- [ ] `configs/edge.yaml`: Mac node provider-first example에 CLI resources와 `mac-mlx-vllm` provider가 같은 `providers[]`에 있다.
- [ ] `configs/edge.yaml`: provider type/field 설명을 `openai_compat` + `provider`/`endpoint` 기준과 맞춘다.
- [ ] `configs/edge.yaml`: legacy `adapters`/`model_routes` reference는 compat/discouraged 설명으로만 남긴다.

#### 테스트 작성

새 unit test는 추가하지 않는다. `configs/edge.yaml`은 `config check`로 YAML/load/validation 정합성을 확인한다.

#### 중간 검증

```bash
go run ./apps/edge/cmd/edge --config configs/edge.yaml config check
```

기대 결과: `OK configs/edge.yaml`.

### [REVIEW_DOCS-3] Local Edge Smoke Rule Separates Legacy Basic And Provider-First Dev Runtime

#### 문제

`agent-test/local/edge-smoke.md:84`의 field Edge 설정 baseline은 `openai.adapter`/`openai.models`/`nodes: []` 중심이다. 이전 plan은 local test rules도 provider-first source of truth와 맞추도록 요구했지만 실제 diff가 없었다.

#### 해결 방법

basic field smoke가 legacy fallback 예시라면 그렇게 명확히 이름 붙이고, dev-runtime provider pool baseline에는 top-level `models[]` + `nodes[].providers[]`가 source of truth라는 기준을 추가한다. `mac-mlx-vllm` candidate와 capacity 기준은 기존 dev-runtime section과 일치시킨다.

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

- [ ] `agent-test/local/edge-smoke.md`: basic field profile이 legacy/basic fallback인지 명시한다.
- [ ] `agent-test/local/edge-smoke.md`: dev-runtime provider-first baseline은 top-level `models[]` + `nodes[].providers[]`로 검증한다고 명시한다.
- [ ] `agent-test/local/edge-smoke.md`: stale-reference check에서 남는 `adapter:`가 intentional compat 또는 console/A2A field인지 분류 가능하게 한다.

#### 테스트 작성

테스트 문서 갱신이므로 코드 테스트는 추가하지 않는다.

#### 중간 검증

```bash
rg --sort path "model_routes|nodes\\[\\]\\.adapters|adapter:" agent-test/local/edge-smoke.md
```

기대 결과: 남은 legacy reference는 legacy/basic fallback, console/A2A field, 또는 compat 설명으로 분류 가능해야 한다.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `docs/edge-local-dev-guide.md` | REVIEW_DOCS-1 |
| `configs/edge.yaml` | REVIEW_DOCS-2 |
| `agent-test/local/edge-smoke.md` | REVIEW_DOCS-3 |

## 최종 검증

```bash
rg --sort path "model_routes|nodes\\[\\]\\.adapters|adapter:" configs docs agent-test/local
```

```bash
go run ./apps/edge/cmd/edge --config configs/edge.yaml config check
```

```bash
go test ./packages/go/config
```

Go test cache output is acceptable when config loader code and config test fixtures are unchanged. 모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
