<!-- task=m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics plan=0 tag=API -->

# Plan - API Diagnostics Contract

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

`CODE_REVIEW-cloud-G06.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 반드시 채운다. 구현 후 검증을 실행하고 active 파일은 그대로 둔 채 리뷰 준비를 보고한다. 최종 판정, log rename, `complete.log`, archive 이동은 code-review-skill 전용이다. 사용자 결정, 사용자 소유 외부 환경, 범위 충돌로 막히면 review stub의 `사용자 리뷰 요청` 섹션에 정확한 근거와 재개 조건을 채우고 멈춘다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 닫을 수 있는 증거 공백은 사용자 리뷰 요청이 아니다.

## 배경

`diagnostics` 작업은 connection id, protocol version, channel name, error code를 로그와 디버그 표면에서 확인 가능하게 해야 한다. 현재 contracts note에는 envelope meta 예시만 있고, diagnostics 필드의 필수/선택 의미와 consumer 책임이 분리되어 있지 않다. Core와 Client 구현 전에 문서 후보를 먼저 고정해 후속 split 작업의 기준으로 삼는다.

## 사용자 리뷰 요청 흐름

구현 중 차단 사유는 active review stub의 `사용자 리뷰 요청` 섹션에 기록한다. 이 섹션은 `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`를 기준으로 하며, code-review가 검증 후 실제 `USER_REVIEW.md` 작성 여부를 결정한다.

## 분석 결과

### 읽은 파일

- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/private/rules.md`
- `agent-ops/rules/common/rules-roadmap.md`
- `agent-ops/skills/common/router.md`
- `agent-ops/skills/common/plan/SKILL.md`
- `agent-ops/skills/common/update-roadmap/SKILL.md`
- `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`
- `agent-roadmap/current.md`
- `agent-roadmap/phase/workflow-core/PHASE.md`
- `agent-roadmap/phase/external-integration/PHASE.md`
- `agent-roadmap/phase/workflow-core/milestones/proto-socket-infrastructure-communication-rail.md`
- `agent-ops/rules/project/domain/workspace-ops/rules.md`
- `agent-ops/rules/project/domain/mobile/rules.md`
- `agent-ops/rules/project/domain/core/rules.md`
- `agent-ops/rules/project/domain/contracts/rules.md`
- `agent-test/local/rules.md`
- `agent-test/local/contracts-smoke.md`
- `agent-test/local/core-smoke.md`
- `agent-test/local/mobile-smoke.md`
- `agent-test/local/workspace-ops-smoke.md`
- `packages/contracts/README.md`
- `packages/contracts/notes/flutter-core-api-candidates.md`
- `services/core/internal/protosocket/server.go`
- `services/core/internal/protosocket/dispatcher.go`
- `services/core/internal/protosocket/envelope.go`
- `services/core/internal/protosocket/events.go`
- `services/core/internal/protosocket/tasks.go`
- `services/core/internal/http/router.go`
- `services/core/internal/protosocket/server_test.go`
- `services/core/internal/protosocket/tasks_test.go`
- `services/core/internal/protosocket/envelope_test.go`
- `apps/client/pubspec.yaml`
- `apps/client/analysis_options.yaml`
- `apps/client/lib/src/app/bootstrap.dart`
- `apps/client/lib/src/app/nomadcode_client_app.dart`
- `apps/client/lib/src/integrations/proto_socket/proto_socket_client.dart`
- `apps/client/lib/src/integrations/proto_socket/proto_socket_endpoint_config.dart`
- `apps/client/lib/src/integrations/proto_socket/proto_socket_envelope.dart`
- `apps/client/lib/src/integrations/proto_socket/proto_socket_lifecycle.dart`
- `apps/client/lib/src/integrations/proto_socket/proto_socket_task_service.dart`
- `apps/client/lib/src/features/workspaces/domain/project_workspace.dart`
- `apps/client/lib/src/features/workspaces/domain/workspace_task.dart`
- `apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart`
- `apps/client/test/integrations/proto_socket_endpoint_config_test.dart`
- `apps/client/test/integrations/proto_socket_envelope_test.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`

### 테스트 환경 규칙

`test_env=local`로 판단했고 `agent-test/local/rules.md`를 읽었다. 이 파일은 로컬 테스트 금지를 명시하므로 현 세션에서는 검증 명령을 실행하지 않는다. 적용 profile은 `contracts-smoke`, `workspace-ops-smoke`이며, contracts 변경의 자동 test command는 없고 문서 링크/경로 수동 확인과 `git diff --check`가 보조 검증이다. 후속 구현/리뷰 에이전트는 사용자 또는 런타임이 허용한 원격/검증 환경에서 명령을 실행해야 한다.

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

- Diagnostics contract note 보강: 자동 테스트 없음. `git diff --check`와 후속 Core/Client plan의 테스트가 소비자 검증을 담당한다.

### 심볼 참조

none. 이 subtask는 symbol rename/remove를 하지 않는다.

### 분할 판단

split decision policy를 먼저 평가했다. 전체 diagnostics 작업은 contracts, core, mobile 경계를 동시에 건드리고 protocol/schema 및 UI debug surface 리스크가 달라 multi-plan으로 분할한다. 공유 task group은 `m-proto-socket-infrastructure-communication-rail`이다.

- `11_contracts_diagnostics`: 선행 diagnostics field 계약 정리, dependency 없음.
- `12+11_core_diagnostics`: Core 로그/meta 구현, `11` 완료 필요. 현재 predecessor `11`은 active/archive `complete.log` 없음.
- `13+11,12_client_diagnostics`: Client 디버그 표면 구현, `11`, `12` 완료 필요. 현재 predecessor `11`, `12`는 active/archive `complete.log` 없음.

### 범위 결정 근거

이 subtask는 `packages/contracts/notes/flutter-core-api-candidates.md`만 수정한다. Go core 구현, Flutter client 구현, generated schema 도입은 후속 subtasks로 분리한다. 실제 source schema가 아직 없으므로 후보 note에만 additive로 기록한다.

### 빌드 등급

`cloud-G06`: 문서 변경이지만 protocol/schema 후보를 고정하고 후속 core/client 구현의 기준이 되므로 cloud review가 적합하다.

## 구현 체크리스트

- [ ] `packages/contracts/notes/flutter-core-api-candidates.md`에 diagnostics meta 필드, 로그 필드, client debug surface 소비 기준을 additive 후보로 정리한다.
- [ ] `git diff --check`를 허용된 원격/검증 환경에서 실행해 Markdown/whitespace 오류가 없는지 확인한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [API-1] Diagnostics Contract Note

#### 문제

[packages/contracts/notes/flutter-core-api-candidates.md](/config/workspace/nomadcode/packages/contracts/notes/flutter-core-api-candidates.md:49)는 `meta.connection_id` 예시만 있고 protocol version, channel, action, error code를 로그/디버그 표면에서 어떻게 다룰지 명시하지 않는다.

Before:

```markdown
49	    "meta": {
50	      "connection_id": "conn-id",
51	      "timestamp": "2026-05-30T00:00:00Z"
52	    }
```

#### 해결 방법

`1.2 proto-socket Semantic Envelope 후보` 뒤 또는 `1.5 Task Channel Actions` 뒤에 `Diagnostics 필드 후보` subsection을 추가한다. 최소 필드는 `connection_id`, `protocol_version`, `channel`, `action`, `error.code`, `timestamp`로 두고, secret/token/payload 원문은 로그와 UI debug surface에 노출하지 않는다고 적는다.

After:

```markdown
### 1.x Diagnostics 필드 후보
- Core log attributes: `connection_id`, `protocol_version`, `channel`, `action`, `error_code`.
- Envelope meta: response/event는 가능한 경우 `connection_id`, `protocol_version`, `channel`, `action`을 포함한다.
- Client debug surface: 연결 상태, connection id, protocol version, 최근 channel/action/error code만 표시하고 auth/payload 원문은 표시하지 않는다.
```

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

- [ ] `packages/contracts/notes/flutter-core-api-candidates.md`: diagnostics subsection 추가.

#### 테스트 작성

자동 테스트는 작성하지 않는다. contracts 도메인은 현재 README/compatibility note 중심이고 `agent-test/local/contracts-smoke.md`에도 확인된 자동 test command가 없다.

#### 중간 검증

```bash
git diff --check
```

기대 결과: 출력 없이 종료한다. 현 세션에서는 local 테스트 금지 규칙 때문에 실행하지 않는다.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `packages/contracts/notes/flutter-core-api-candidates.md` | API-1 |

## 최종 검증

```bash
git diff --check
```

기대 결과: 출력 없이 종료한다. 명령은 허용된 원격/검증 환경에서 실행한다.

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