<!-- task=m-proto-socket-infrastructure-communication-rail/13+11,12_client_diagnostics plan=1 tag=REVIEW_API -->

# Plan - REVIEW_API Client Diagnostics Follow-Up

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

이 계획은 `code_review_cloud_G07_0.log`의 Required findings만 닫는다. 로컬 테스트/검증은 `agent-test/local/rules.md`에 따라 실행하지 말고, 허용된 원격/검증 환경에서 실제 stdout/stderr를 회수한다. 사용자 결정, 사용자 소유 외부 환경, 범위 충돌로 막히면 active review stub의 `사용자 리뷰 요청` 섹션에 정확한 근거와 재개 조건을 채우고 멈춘다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/workflow-core/milestones/proto-socket-infrastructure-communication-rail.md`
- Task ids:
  - `diagnostics`: connection id, protocol version, channel name, error code를 로그와 디버그 표면에서 확인할 수 있게 한다.
- Completion mode: check-on-pass

## 배경

1차 리뷰는 client diagnostics 구현을 FAIL로 판정했다. diagnostics response/event recording과 UI 표면은 추가되었지만, lifecycle 상태 전환이 connection-specific diagnostics 값을 stale 상태로 보존하고 있고, task service error-envelope diagnostics coverage와 필수 Flutter 검증 증거가 없다.

## 범위 결정 근거

- 수정 범위는 `apps/client/lib/src/integrations/proto_socket/proto_socket_lifecycle.dart`, `apps/client/test/integrations/proto_socket_lifecycle_test.dart`, `apps/client/test/integrations/proto_socket_task_service_test.dart`, 필요 시 `apps/client/test/widget_test.dart`로 제한한다.
- task service production API는 가능한 한 유지한다. diagnostics capture는 lifecycle이 반환하는 wrapped transport 흐름을 검증한다.
- Core, contracts, roadmap, predecessor archive는 수정하지 않는다.

## 구현 체크리스트

- [ ] `ProtoSocketLifecycle`가 disconnect, connect failure, reconnect start에서 connection-specific diagnostics fields를 stale 값 없이 정리하게 한다.
- [ ] `proto_socket_lifecycle_test.dart`에 disconnect 및 failed reconnect stale diagnostics regression을 추가한다.
- [ ] `proto_socket_task_service_test.dart`에 `ProtoSocketTaskService` success meta와 error envelope code가 lifecycle diagnostics에 기록되는 테스트를 추가한다.
- [ ] 허용된 원격/검증 환경에서 `cd apps/client && flutter test test/integrations/proto_socket_lifecycle_test.dart test/integrations/proto_socket_task_service_test.dart test/widget_test.dart`를 실행하고 실제 stdout/stderr를 review stub에 기록한다.
- [ ] 허용된 원격/검증 환경에서 `cd apps/client && flutter test`와 `cd apps/client && flutter analyze --no-fatal-infos`를 실행하고 실제 stdout/stderr를 review stub에 기록한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## [REVIEW_API-1] Stale Diagnostics Cleanup

### 문제

[apps/client/lib/src/integrations/proto_socket/proto_socket_lifecycle.dart](/config/workspace/nomadcode/apps/client/lib/src/integrations/proto_socket/proto_socket_lifecycle.dart:27)의 `copyWithState`는 connection id, channel/action, error code, timestamp를 그대로 보존한다. `disconnect()`와 connect failure 경로가 이 helper를 사용하면 debug surface가 disconnected/failed 상태에서도 이전 connection/error 정보를 보여줄 수 있다.

### 해결 방법

state-only transition과 connection reset transition을 분리한다. 예를 들어 `ProtoSocketDiagnostics.forState(next)` 또는 `copyWithState(next, clearConnection: true)`를 추가하고, 아래 흐름에서는 connection-specific fields를 초기화한다.

- 새 connect 시작: 이전 connection id/channel/action/error code/timestamp 초기화
- connect failure: failed state는 유지하되 이전 connection id/channel/action/error code/timestamp 제거
- disconnect: disconnected state로 전환하며 connection id/channel/action/error code/timestamp 제거

`protocolVersion`은 새 envelope에서 다시 채워지게 해도 되고, 제품 판단상 표시가 필요하면 connection-specific 값과 분리해 명시적으로 보존한다. 어떤 선택이든 테스트 기대값에 반영한다.

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

- [ ] `apps/client/lib/src/integrations/proto_socket/proto_socket_lifecycle.dart`: stale diagnostics reset helper 추가 및 connect/disconnect/failure 경로 적용.
- [ ] `apps/client/test/integrations/proto_socket_lifecycle_test.dart`: envelope 기록 후 disconnect 시 stale 값 제거 검증.
- [ ] `apps/client/test/integrations/proto_socket_lifecycle_test.dart`: 이전 envelope 기록 후 failed reconnect 시 stale 값 제거 검증.

### 중간 검증

```bash
cd apps/client && flutter test test/integrations/proto_socket_lifecycle_test.dart
```

허용된 원격/검증 환경에서 실행하고 실제 stdout/stderr를 review stub에 기록한다.

## [REVIEW_API-2] Task Service Diagnostics Coverage

### 문제

[apps/client/test/integrations/proto_socket_task_service_test.dart](/config/workspace/nomadcode/apps/client/test/integrations/proto_socket_task_service_test.dart:93)는 task request shape와 error mapping을 검증하지만, plan이 요구한 `ProtoSocketTaskService` response/error diagnostics capture를 검증하지 않는다.

### 해결 방법

`ProtoSocketLifecycle`와 fake connector/transport를 task service test에 연결한다. `ProtoSocketTaskService(lifecycle.transport!)`를 사용해 다음을 검증한다.

- success response meta의 `connection_id`, `protocol_version`, `channel`, `action`이 `lifecycle.diagnostics`에 기록된다.
- error envelope response를 받은 뒤 service가 기존 `ProtoSocketTaskException`을 던지면서도 diagnostics `errorCode`가 envelope `error.code`로 갱신된다.

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

- [ ] `apps/client/test/integrations/proto_socket_task_service_test.dart`: diagnostics-wrapped transport fake 구성 추가.
- [ ] `apps/client/test/integrations/proto_socket_task_service_test.dart`: success response meta capture 테스트 추가.
- [ ] `apps/client/test/integrations/proto_socket_task_service_test.dart`: error envelope code capture와 기존 exception mapping 유지 테스트 추가.

### 중간 검증

```bash
cd apps/client && flutter test test/integrations/proto_socket_task_service_test.dart
```

허용된 원격/검증 환경에서 실행하고 실제 stdout/stderr를 review stub에 기록한다.

## [REVIEW_API-3] Verification Evidence Recovery

### 문제

1차 review stub의 필수 Flutter 검증 항목은 unchecked 상태였고, 실제 stdout/stderr가 아니라 로컬 규칙상 미실행 사유만 기록됐다. `mobile-smoke` 기준 mobile 변경은 `flutter test`가 필수이며, analyzer 영향이 있으므로 `flutter analyze --no-fatal-infos`도 필요하다.

### 해결 방법

허용된 원격/검증 환경에서 대상 테스트, 전체 Flutter test, analyzer를 실행한다. 로컬에서 실행하지 않는다. 원격 환경도 불가능하면 active review stub의 `사용자 리뷰 요청`에 실행 시도, 실제 출력, user-owned blocker 여부, 재개 조건을 구체적으로 기록한다.

### 검증 명령

```bash
cd apps/client && flutter test test/integrations/proto_socket_lifecycle_test.dart test/integrations/proto_socket_task_service_test.dart test/widget_test.dart
cd apps/client && flutter test
cd apps/client && flutter analyze --no-fatal-infos
```

## 리뷰어 체크포인트

- disconnected/failed/reconnect start 상태에서 이전 `connection_id`, `channel`, `action`, `error_code`, `timestamp`가 UI에 남지 않는가.
- task service success/error response가 lifecycle diagnostics로 기록되면서 기존 `ProtoSocketTaskException` mapping을 깨지 않는가.
- review stub의 `구현 체크리스트` 텍스트와 순서가 이 plan과 정확히 일치하고, 체크박스 외 임의 문구가 추가되지 않았는가.
- 검증 결과에 실제 stdout/stderr가 기록됐는가.
