<!-- task=m-socket-session-loop/01_client_socket_layer plan=2 tag=REVIEW_REVIEW_API -->

# Plan - REVIEW_REVIEW_API

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

`CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채우는 것이 필수 마지막 단계다. 구현 후 검증을 실행하고 실제 출력, 계획 대비 변경, 설계 결정을 review stub에 기록한 뒤 active 파일을 유지하고 리뷰 준비를 보고한다. 사용자 결정, 외부 환경 준비, 범위 충돌 없이는 안전하게 진행할 수 없으면 review stub의 `사용자 리뷰 요청`에 정확한 증거를 남기고 중단한다. `USER_REVIEW.md`, archive, `complete.log` 작성은 code-review 전용이다.

## 배경

두 번째 리뷰도 `FAIL`이다. 소스와 테스트 대부분은 정상화되었지만, 후속 계획의 고정 검증 중 `protoc --dart_out`과 `tools/generate_proto.sh`가 현재 환경에서 `protoc-gen-dart` 미발견으로 재현되지 않았다. 또한 review stub에는 `...` 축약 출력과 닫히지 않은 code fence, 고정 섹션 손상이 남아 verification trust가 충족되지 않았다.

## 사용자 리뷰 요청 흐름

구현 중 차단 조건은 active `CODE_REVIEW-*-G??.md`의 `사용자 리뷰 요청` 섹션에 기록한다. code-review가 그 내용을 검증해 실제 `USER_REVIEW.md` 작성 여부를 결정한다.

## 분석 결과

### 읽은 파일

- `agent-task/m-socket-session-loop/01_client_socket_layer/code_review_cloud_G06_1.log`
- `agent-task/m-socket-session-loop/01_client_socket_layer/plan_cloud_G06_1.log`
- `../proto-socket/tools/generate_proto.sh`
- `../proto-socket/dart/pubspec.yaml`
- `../proto-socket/dart/lib/src/packets/message_common.pb.dart`
- `apps/client/pubspec.yaml`
- `apps/client/lib/src/integrations/socket/alt_socket_client.dart`
- `apps/client/test/integrations/socket/alt_socket_client_test.dart`

### 실패 근거

- `command -v protoc-gen-dart`가 exit 1이다.
- `cd ../proto-socket && protoc --proto_path=proto --dart_out=dart/lib/src/packets message_common.proto`가 `protoc-gen-dart: program not found or is not executable`로 실패한다.
- `cd ../proto-socket && tools/generate_proto.sh`도 `Missing required binary: protoc-gen-dart`로 실패한다.
- archived `code_review_cloud_G06_1.log`에는 최종 검증 출력 축약(`...`)과 닫히지 않은 code fence, 손상된 review-agent fixed instruction이 남아 있다.

### 빌드 등급

- build: `cloud-G07`, review: `cloud-G07`.
- 실제 generation command가 실패했고 verification trust 회복이 핵심이므로 code-review escalation gate에 따라 G07로 올린다.

## 구현 체크리스트

- [ ] `protoc-gen-dart`를 현재 셸 PATH에서 재현 가능하게 준비하고 generation command를 재실행한다. 검증: `command -v protoc-gen-dart`, `protoc-gen-dart --version`, `cd ../proto-socket && protoc --proto_path=proto --dart_out=dart/lib/src/packets message_common.proto`, `cd ../proto-socket && tools/generate_proto.sh`.
- [ ] 고정 검증 명령의 실제 stdout/stderr를 축약 없이 `CODE_REVIEW-cloud-G07.md`에 기록한다. 검증: `cd ../proto-socket/dart && dart analyze`, `cd ../proto-socket/dart && dart test`, `cd ../proto-socket/dart && dart compile js test/browser_ws_import_compile.dart -o /tmp/proto_socket_browser_ws_import_compile.js`, `cd apps/client && flutter test`, `cd apps/client && flutter analyze --no-fatal-infos`, `cd apps/client && flutter build web`.
- [ ] `CODE_REVIEW-cloud-G07.md`의 고정 섹션 구조와 markdown code fence를 보존하고 구현 에이전트 소유 섹션만 채운다. 검증: `rg -n "\\.\\.\\.|agent-ta##" agent-task/m-socket-session-loop/01_client_socket_layer/CODE_REVIEW-cloud-G07.md`.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [REVIEW_REVIEW_API-1] Make protoc-gen-dart reproducible

문제: 이전 review stub는 Dart packet generation이 성공했다고 기록했지만, 리뷰 재실행에서는 `protoc-gen-dart`가 PATH에 없어 실패했다. 이 상태에서는 regenerated packet diff가 실제로 canonical generation flow에서 나온 것인지 확인할 수 없다.

해결 방법:

- `protoc-gen-dart`를 현재 shell PATH에서 실행 가능하게 준비한다. 기본 후보는 `dart pub global activate protoc_plugin 25.0.0` 후 pub cache bin 경로를 PATH에 포함하는 것이다.
- 환경에 따라 다른 설치 경로를 쓰면 `계획 대비 변경 사항`에 정확한 경로와 이유를 기록한다.
- `tools/generate_proto.sh`는 그대로 실행 가능한 상태여야 한다. 스크립트를 수정해야만 재현 가능하다면 변경 전후와 이유를 기록한다.
- `protoc --dart_out` 직접 명령과 `tools/generate_proto.sh`를 모두 재실행한다.

수정 파일 및 체크리스트:

- [ ] 일반적으로 source 변경 없음
- [ ] 필요한 경우 `../proto-socket/tools/generate_proto.sh`
- [ ] generation 결과가 달라지는 경우 `../proto-socket/dart/lib/src/packets/*.dart`

테스트 작성: 별도 테스트 없음. generation command 재현성이 검증이다.

중간 검증:

```bash
command -v protoc-gen-dart
protoc-gen-dart --version
cd ../proto-socket && protoc --proto_path=proto --dart_out=dart/lib/src/packets message_common.proto
cd ../proto-socket && tools/generate_proto.sh
```

기대 결과: 모든 명령이 exit 0이다. no-output 성공도 그대로 기록한다.

### [REVIEW_REVIEW_API-2] Record full verification output

문제: 이전 review stub의 최종 검증에는 `...` 축약이 남아 있었고, code-review 규칙이 요구하는 실제 stdout/stderr가 보존되지 않았다.

해결 방법:

- 모든 고정 검증 명령을 실제 재실행하고 출력 전체를 `CODE_REVIEW-cloud-G07.md`에 붙인다.
- 출력이 길어도 `...`로 줄이지 않는다.
- 실패한 명령이 있으면 실패 stdout/stderr와 exit 상황을 기록하고 사용자 리뷰 요청이 필요한지 판단한다.

수정 파일 및 체크리스트:

- [ ] `agent-task/m-socket-session-loop/01_client_socket_layer/CODE_REVIEW-cloud-G07.md`

테스트 작성: 새 테스트 없음. verification evidence 복구 작업이다.

중간 검증:

```bash
cd ../proto-socket/dart && dart analyze
cd ../proto-socket/dart && dart test
cd ../proto-socket/dart && dart compile js test/browser_ws_import_compile.dart -o /tmp/proto_socket_browser_ws_import_compile.js
cd apps/client && flutter test
cd apps/client && flutter analyze --no-fatal-infos
cd apps/client && flutter build web
```

기대 결과: 모든 명령이 exit 0이고 실제 출력이 review stub에 남는다.

### [REVIEW_REVIEW_API-3] Preserve review stub structure

문제: 이전 review stub에서 review-agent fixed instruction이 `agent-ta## 구현 항목별 완료 여부`로 끊겼고, 최종 code fence가 닫히지 않아 markdown 구조가 깨졌다.

해결 방법:

- archived `code_review_cloud_G06_1.log`는 그대로 두고, active `CODE_REVIEW-cloud-G07.md`의 고정 섹션은 수정하지 않는다.
- 구현 에이전트는 `구현 항목별 완료 여부`, `구현 체크리스트`, `계획 대비 변경 사항`, `주요 설계 결정`, `사용자 리뷰 요청`, `검증 결과`만 채운다.
- 모든 fenced code block이 닫혔는지 확인한다.

수정 파일 및 체크리스트:

- [ ] `agent-task/m-socket-session-loop/01_client_socket_layer/CODE_REVIEW-cloud-G07.md`

테스트 작성: 문서 구조 검증이라 새 테스트 없음.

중간 검증:

```bash
rg -n "\\.\\.\\.|agent-ta##" agent-task/m-socket-session-loop/01_client_socket_layer/CODE_REVIEW-cloud-G07.md
```

기대 결과: 구현 완료 후 해당 command는 아무 결과도 출력하지 않는다.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `agent-task/m-socket-session-loop/01_client_socket_layer/CODE_REVIEW-cloud-G07.md` | REVIEW_REVIEW_API-2, REVIEW_REVIEW_API-3 |
| `../proto-socket/tools/generate_proto.sh` | REVIEW_REVIEW_API-1, 필요한 경우에만 |
| `../proto-socket/dart/lib/src/packets/*.dart` | REVIEW_REVIEW_API-1, regeneration 결과가 달라지는 경우에만 |

## 최종 검증

```bash
command -v protoc-gen-dart
protoc-gen-dart --version
cd ../proto-socket && tools/generate_proto.sh
cd ../proto-socket/dart && dart analyze
cd ../proto-socket/dart && dart test
cd ../proto-socket/dart && dart compile js test/browser_ws_import_compile.dart -o /tmp/proto_socket_browser_ws_import_compile.js
cd apps/client && flutter test
cd apps/client && flutter analyze --no-fatal-infos
cd apps/client && flutter build web
```

기대 결과: 모든 명령이 통과하고, review stub에 축약 없는 실제 출력이 남는다.

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