<!-- task=m-agent-registration-capability-boundary/01_agent_port plan=0 tag=REFACTOR -->

# Code Review Reference - REFACTOR

> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> The task is NOT complete until every implementation-owned section below is filled in.
> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
> If implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`.
> Finalization is review-agent-only.

## 개요

date=2026-06-10
task=m-agent-registration-capability-boundary/01_agent_port, plan=0, tag=REFACTOR

## Roadmap Targets

- Milestone: `agent-roadmap/phase/message-based-build-agent/milestones/agent-registration-capability-boundary.md`
- Task ids:
  - `agent-port`: agent 등록에 필요한 capability provider 계약과 기본값 주입 지점을 정의한다.
- Completion mode: check-on-pass

## 이 파일을 읽는 리뷰 에이전트에게

> **[REVIEW AGENT ONLY]** 종결 절차는 코드리뷰 에이전트 전용이다.

각 항목의 구현을 실제 소스 파일과 대조하고 검증 출력이 코드와 일치하는지 확인하세요.

## 구현 항목별 완료 여부

| 항목 | 완료 여부 |
|------|---------|
| [REFACTOR-1] Agent Capability Provider Port | [x] |

## 구현 체크리스트

- [x] agent 등록 capability provider port와 immutable capability model을 agent 도메인 파일에 추가한다.
- [x] `OtoServerRegistrationClient`가 `commandTypes` 직접 list 대신 provider를 받을 수 있는 주입 지점을 준비하되 기존 `commandTypes:` call site는 깨지지 않게 유지한다.
- [x] `oto_agent_registration_test.dart`에 fake provider 기반 request build test를 추가한다.
- [x] 중간/최종 검증을 실행한다.
- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## 코드리뷰 전용 체크리스트

- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [x] active plan/review 파일을 `.log`로 아카이브한다.
- [x] PASS이면 `complete.log` 작성 후 task directory를 archive로 이동한다.
- [x] PASS이고 task group이 `m-agent-registration-capability-boundary`이면 런타임 완료 이벤트 메타데이터를 보고한다.

## 계획 대비 변경 사항

- 계획 범위대로 `apps/runner/lib/oto/agent/runner_capability_provider.dart`를 추가했다.
- 기존 `commandTypes:` call site 호환을 유지하기 위해 `OtoServerRegistrationClient` 내부에서 static provider로 감싸도록 구현했다.
- command catalog 기반 default provider는 후속 `02` adapter 작업 전까지 `registration_client.dart` 내부에 남겼다.

## 주요 설계 결정

- `RunnerCapabilityProvider.snapshot()`이 registration payload에 필요한 `name`, `version`, `commandTypes`를 한 번에 제공하도록 했다.
- `RunnerCapabilitySnapshot.commandTypes`는 `List.unmodifiable`로 고정해 request build 중 외부 mutable iterable 영향이 없게 했다.
- 명시 `capabilityProvider`가 있으면 우선 사용하고, 없으면 기존 `commandTypes:` 또는 기존 기본 command catalog 계산 경로를 provider 형태로 정규화했다.

## 사용자 리뷰 요청

_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다._

- 상태: 없음
- 사유 유형: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 자동 후속 불가 이유: 없음
- 재개 조건: 없음

## 리뷰어를 위한 체크포인트

- agent port가 command 도메인 type을 import하지 않는지 확인
- 기존 `commandTypes:` call site 호환이 유지되는지 확인
- fake provider test가 request payload 의미를 검증하는지 확인

## 검증 결과

### REFACTOR-1 중간 검증

```text
$ cd apps/runner && dart test test/oto_agent_registration_test.dart
00:01 +36: All tests passed!
```

### 최종 검증

```text
$ cd apps/runner && dart analyze
Analyzing runner...
No issues found!

$ cd apps/runner && dart test test/oto_agent_registration_test.dart
00:01 +36: All tests passed!

$ cd apps/runner && dart test test/oto_agent_migration_plan_test.dart test/oto_agent_bootstrap_script_test.dart test/oto_agent_cli_test.dart test/oto_agent_config_test.dart test/oto_agent_registration_test.dart test/oto_server_connection_smoke_test.dart
00:10 +74: All tests passed!
```

## 코드리뷰 결과

- 종합 판정: PASS
- 차원별 평가:
  - correctness: Pass
  - completeness: Pass
  - test coverage: Pass
  - API contract: Pass
  - code quality: Pass
  - plan deviation: Pass
  - verification trust: Pass
- 발견된 문제: 없음
- 다음 단계: PASS이므로 `complete.log`를 작성하고 task directory를 archive로 이동한다.

리뷰 메모:
- `RunnerCapabilityProvider`와 `RunnerCapabilitySnapshot`은 agent 도메인 파일에 추가되었고, provider port 자체는 command 도메인을 import하지 않는다.
- `OtoServerRegistrationClient`는 `capabilityProvider` 주입 표면을 추가하면서 기존 `commandTypes:` 호출 경로를 유지한다.
- fake provider 기반 request build test가 capability name/version과 command catalog payload를 검증한다.
- 리뷰 중 `apps/runner/test/oto_agent_registration_test.dart`에 `dart format`을 적용해 비동작성 포맷 drift를 정리했다.
- 재검증:
  - `cd apps/runner && dart analyze` - PASS; `No issues found!`
  - `cd apps/runner && dart test test/oto_agent_registration_test.dart` - PASS; `+36: All tests passed!`
  - `cd apps/runner && dart test test/oto_agent_migration_plan_test.dart test/oto_agent_bootstrap_script_test.dart test/oto_agent_cli_test.dart test/oto_agent_config_test.dart test/oto_agent_registration_test.dart test/oto_server_connection_smoke_test.dart` - PASS; `+74: All tests passed!`
