<!-- task=m-runner-proto-socket-transport-hardening/04+01_compat_boundary plan=1 tag=REVIEW_API -->

# Plan - REVIEW_API

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

`CODE_REVIEW-local-G04.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채우는 것까지가 구현입니다. 검증을 실행하고 실제 stdout/stderr를 붙인 뒤 active 파일을 그대로 두고 review ready로 보고하세요. 선택된 SDD 결정 또는 Milestone `구현 잠금 > 결정 필요` 항목이 막으면 review stub의 `사용자 리뷰 요청` 섹션을 채우고 멈추며, 직접 사용자에게 질문하거나 `USER_REVIEW.md`, `complete.log`, archive를 만들지 않습니다. 환경/secret/서비스 문제나 증거 공백은 일반 follow-up 대상으로 기록합니다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/control-plane-product-surface/milestones/runner-proto-socket-transport-hardening.md`
- Task ids:
  - `compat-boundary`: HTTP job claim/polling/report/log/artifact 경로를 compatibility fallback으로 격리하고 기본 runner path 명명에서 제외한다.
- Completion mode: check-on-pass
- Split dependency:
  - `01_socket_lifecycle` PASS complete evidence가 확인됨: `agent-task/archive/2026/06/m-runner-proto-socket-transport-hardening/01_socket_lifecycle/complete.log`

## Spec Targets

- SDD: `agent-roadmap/sdd/control-plane-product-surface/runner-proto-socket-transport-hardening/SDD.md`
- Acceptance scenarios:
  - `S05`: task=`compat-boundary`; evidence=`HTTP job claim/report/log/artifact 경로가 compatibility fallback으로 격리되고 기본 smoke/문서가 socket path를 기준으로 한다.`
- Completion mode: spec-check-on-pass

## Archive Evidence Snapshot

- Archived plan: `agent-task/m-runner-proto-socket-transport-hardening/04+01_compat_boundary/plan_cloud_G07_0.log`
- Archived review: `agent-task/m-runner-proto-socket-transport-hardening/04+01_compat_boundary/code_review_cloud_G07_0.log`
- Verdict: FAIL
- Required summary:
  - `apps/runner/test/oto_server_connection_smoke_test.dart`에 HTTP `OtoServerRegistrationClient`/`claimJob` 기반 smoke 테스트가 compatibility/fallback 이름이나 그룹 없이 남아 있다. 확인된 시작점: `:828`, `:967`, `:1093`, `:1234`.
  - archived review의 `rg --sort path ...` 검증 출력은 실제 stdout과 맞지 않고 최종 검증도 요약 문구만 남겼다.
- Affected files:
  - `apps/runner/test/oto_server_connection_smoke_test.dart`
  - `agent-task/m-runner-proto-socket-transport-hardening/04+01_compat_boundary/CODE_REVIEW-local-G04.md`
- Verification evidence:
  - Reviewer ran `rg --sort path -n "test\\(|OtoServerRegistrationClient\\(|claimNextJob|jobs\\.claim|OtoServerJobClient\\(" apps/runner/test/oto_server_connection_smoke_test.dart apps/runner/test/oto_agent_registration_test.dart` and found unlabelled HTTP smoke test names.
  - Reviewer ran `git diff --check`; no whitespace errors.
- Allowed narrow archive reread:
  - `agent-task/m-runner-proto-socket-transport-hardening/04+01_compat_boundary/plan_cloud_G07_0.log`
  - `agent-task/m-runner-proto-socket-transport-hardening/04+01_compat_boundary/code_review_cloud_G07_0.log`

## 범위 결정 근거

후속 작업은 SDD `S05` 완료 증거를 막는 테스트 이름/그룹 누락과 검증 출력 불일치만 고친다. HTTP endpoint 동작, runner transport 구현, route 추가/삭제는 범위가 아니다.

## 구현 체크리스트

- [ ] [REVIEW_API-1] 남은 HTTP compatibility fallback smoke 테스트 이름/그룹을 모두 기본 socket smoke와 분리한다. 검증: `rg --sort path -n "test\\(|OtoServerRegistrationClient\\(|claimNextJob|jobs\\.claim|OtoServerJobClient\\(" apps/runner/test/oto_server_connection_smoke_test.dart apps/runner/test/oto_agent_registration_test.dart`
- [ ] [REVIEW_API-2] 검증 신뢰도를 회복한다. 검증: 아래 최종 검증 명령 전체의 실제 stdout/stderr를 `CODE_REVIEW-local-G04.md`에 붙인다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [REVIEW_API-1] HTTP compatibility fallback smoke 이름/그룹 정리

문제: `apps/runner/test/oto_server_connection_smoke_test.dart`에는 HTTP `OtoServerRegistrationClient`와 `claimJob` 기반 smoke가 남아 있지만, 일부 테스트 이름이 compatibility/fallback 맥락을 드러내지 않는다. 특히 `:828`, `:967`, `:1093`, `:1234` 부근 테스트는 기본 runner path처럼 읽힐 수 있다.

해결 방법:

```text
before: remoteRunExecutor runOnce reports declared artifacts to Go OTO Server (API-3)
after:  remoteRunExecutor runOnce reports declared artifacts via compatibility fallback HTTP (API-3)
```

수정 체크리스트:

- [ ] `oto_server_connection_smoke_test.dart`의 모든 HTTP registration/client 기반 테스트명을 compatibility fallback 맥락으로 정리한다.
- [ ] 필요하면 HTTP compatibility tests를 명시적 group으로 묶되, 기존 socket tests 이름은 socket 기본 경로로 유지한다.
- [ ] `OtoServerSocketRegistrationClient` 기반 테스트명은 socket/default path로 유지하고 HTTP compatibility 이름과 섞이지 않게 한다.
- [ ] 테스트 동작과 assertion은 변경하지 않는다.

테스트 결정: 테스트명/그룹 변경이므로 targeted Dart smoke와 deterministic grep을 실행한다.

중간 검증:

```bash
rg --sort path -n "test\\(|OtoServerRegistrationClient\\(|claimNextJob|jobs\\.claim|OtoServerJobClient\\(" apps/runner/test/oto_server_connection_smoke_test.dart apps/runner/test/oto_agent_registration_test.dart
```

기대 결과: HTTP registration/client/claim 기반 테스트는 모두 compatibility/fallback 이름이나 그룹 안에서 확인되고, socket tests는 socket 이름으로 분리되어 보인다.

### [REVIEW_API-2] 검증 stdout/stderr 신뢰 회복

문제: 이전 review stub의 `rg --sort path ...` 출력은 실제 명령 출력과 맞지 않았고, 최종 검증은 실제 stdout 대신 요약을 남겼다. 이 상태로는 SDD `S05`의 Evidence Map을 신뢰하기 어렵다.

해결 방법:

계획의 최종 검증을 다시 실행하고 `CODE_REVIEW-local-G04.md`의 검증 결과에 실제 stdout/stderr를 그대로 붙인다. 출력이 길면 핵심 명령의 실제 행을 생략 없이 붙이고, 생략이 불가피하면 어떤 명령의 어떤 출력이 생략됐는지와 별도 evidence path를 남긴다.

수정 체크리스트:

- [ ] `rg --sort path ...` 출력이 실제 현재 파일 내용과 일치한다.
- [ ] Dart targeted smoke 출력과 analyzer 출력이 실제 stdout/stderr로 기록된다.
- [ ] Go test 출력이 실제 stdout/stderr로 기록된다.
- [ ] local agent-smoke 규칙의 agent 관련 test command를 실행하거나, 미실행 시 정확한 차단 사유를 남긴다.

테스트 결정: agent domain/test rule 검증을 다시 수행한다.

중간 검증:

```bash
cd apps/runner && dart analyze
```

기대 결과: `No issues found!`

## 최종 검증

```bash
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
cd services/core && go test -count=1 ./...
cd apps/runner && dart analyze
rg --sort path -n "OtoServerRegistrationClient|claimNextJob|jobs/claim|HTTP polling|compatibility|fallback|socket" apps/runner/lib apps/runner/test services/core/internal/httpserver agent-ops/rules/project/domain/agent/rules.md agent-test/local/agent-smoke.md
rg --sort path -n "test\\(|OtoServerRegistrationClient\\(|claimNextJob|jobs\\.claim|OtoServerJobClient\\(" apps/runner/test/oto_server_connection_smoke_test.dart apps/runner/test/oto_agent_registration_test.dart
```

기대 결과: tests/analyzer 통과. grep 결과에서 HTTP registration/client/claim/polling 경로는 compatibility/fallback 맥락으로 보이고, socket registration/session smoke는 socket 기본 경로로 분리되어 보인다.
