<!-- task=m-performance-hotspot-optimization/01_hotspot_report plan=0 tag=TEST -->

# Plan - TEST

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

`CODE_REVIEW-local-G05.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채우는 것까지가 구현입니다. 검증을 실행하고 실제 stdout/stderr를 붙여 넣은 뒤 active 파일을 그대로 두고 리뷰 준비를 보고하세요. 사용자 결정, 사용자 소유 외부 환경, 또는 계획 범위 변경 없이는 진행할 수 없으면 review stub의 `사용자 리뷰 요청` 섹션에 근거와 재개 조건을 채우고 멈추세요. 후속 에이전트가 명령 재실행이나 산출물 수집으로 닫을 수 있는 증거 공백은 사용자 리뷰 요청이 아닙니다.

## 배경

`performance-hotspot-optimization` 마일스톤의 두 번째 Epic `[hotspot]`에는 병목 리포트와 Go/Python reference 정리 두 작업이 남아 있었다. Go/Python reference 정리는 기존 측정 근거가 이미 충분해 바로 완료 처리했다. `[hotspot-report]`는 여러 결과 파일에 흩어진 Dart, TypeScript, Kotlin, gateway 근거를 하나의 검토 가능한 리포트로 정리해야 하므로 구현 루프에 태운다.

## 사용자 리뷰 요청 흐름

구현 중 차단이 있으면 `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` 형식으로 active review stub의 `사용자 리뷰 요청` 섹션을 채운다. `USER_REVIEW.md` 작성과 차단 판단은 code-review가 담당한다.

## Roadmap Targets

- Milestone: `agent-roadmap/milestones/performance-hotspot-optimization.md`
- Task ids:
  - `hotspot-report`: Dart TCP fixed latency/large payload/isolate gateway hardening, TypeScript WS large payload, Kotlin WS latency/slow-mix 검증 모델, TypeScript gateway overhead를 병목 리포트로 정리
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-ops/rules/project/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/ROADMAP.md`
- `agent-roadmap/milestones/performance-hotspot-optimization.md`
- `agent-test/local/rules.md`
- `agent-test/local/proto-socket-performance-baseline.md`
- `agent-test/local/proto-socket-full-matrix.md`
- `agent-test/runs/20260603-062724-proto-socket-stress-full.md`
- `agent-test/runs/20260602-232000-proto-socket-stress-full.md`
- `agent-test/runs/20260603-080241-proto-socket-stress-full.md`
- `agent-test/runs/20260603-035342-proto-socket-stress-quick.md`
- `agent-test/runs/20260603-035352-proto-socket-stress-quick.md`
- `agent-test/runs/20260603-095712-proto-socket-performance-quick.md`
- `.gitignore`

### 테스트 환경 규칙

test_env는 `local`이다. `agent-test/local/rules.md`를 읽었고, 성능/latency/payload/gateway 근거 작업이므로 `agent-test/local/proto-socket-performance-baseline.md`를 적용한다. 전체 호환성 회귀는 코드 변경이 없으므로 필수 최종 검증이 아니라 보조 검증으로만 남긴다. 이 plan의 변경은 문서/로드맵 정리라 성능 측정을 새로 실행하지 않고, 기존 결과 파일의 row 근거가 마일스톤에 정확히 연결되는지 `rg --sort path`와 `git diff --check`로 검증한다.

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

- 병목 리포트 문서화: 기존 stress/performance 기록이 증거다. 새 런타임 동작이 없으므로 unit test 추가는 하지 않는다.
- idle `run_performance.sh --full` 기준점: 아직 결과 파일이 없다. `[idle-full]`과 `[compare-rule]`은 이번 범위에서 완료 주장하지 않는다.
- 코드 성능 개선: 이번 범위가 아니다. 이후 TypeScript/Dart/Kotlin 구현 plan에서 별도 성능 검증을 지정한다.

### 심볼 참조

none. 이름 변경, 삭제, import 변경이 없다.

### 분할 판단

분할 정책을 먼저 평가했다. 공유 task group은 `agent-task/m-performance-hotspot-optimization/`이고 현재 생성하는 subtask는 `01_hotspot_report`다. 선행 subtask는 없다. `[hotspot-report]`는 로드맵/결과 근거 정리만 다루는 단일 산출물이므로 TypeScript gateway 구현, Dart TCP 구현, Kotlin WS 구현과 분리한다.

### 범위 결정 근거

수정 대상은 `agent-roadmap/milestones/performance-hotspot-optimization.md`와 active task artifact로 제한한다. `dart/`, `go/`, `kotlin/`, `python/`, `typescript/`, `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/`는 구현 대상이 아니다. `agent-test/runs/**`는 근거로만 읽고 수정하지 않는다.

### 빌드 등급

build=`local-G05`, review=`local-G05`. 코드 변경 없는 milestone-linked 문서 작업이지만, 여러 성능 결과를 정확히 연결해야 해서 중간 난도로 둔다.

## 구현 체크리스트

- [ ] `[hotspot-report]` 근거를 마일스톤 안에 하나의 병목 리포트 섹션 또는 표로 정리한다.
- [ ] Dart TCP, Dart isolate gateway, TypeScript WS 1MB, Kotlin WS/slow-mix, TypeScript gateway overhead 각각에 근거 파일, row, p99/throughput/memory, 후속 Task id를 연결한다.
- [ ] Go/Python reference fast path는 병목 리포트의 비교 기준으로만 인용하고, 최우선 런타임 최적화 대상으로 쓰지 않는다.
- [ ] `[idle-full]`과 `[compare-rule]`은 미완으로 유지하고, full idle baseline 부재를 명시한다.
- [ ] `git diff --check`와 deterministic `rg --sort path` 검증을 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [TEST-1] 핫스팟 리포트 정리

#### 문제

[agent-roadmap/milestones/performance-hotspot-optimization.md](/config/workspace/proto-socket/agent-roadmap/milestones/performance-hotspot-optimization.md:41)의 `[hotspot]` Epic은 병목 우선순위 확정을 요구하지만, [agent-roadmap/milestones/performance-hotspot-optimization.md](/config/workspace/proto-socket/agent-roadmap/milestones/performance-hotspot-optimization.md:171)의 참고 결과는 긴 bullet 목록이라 `[hotspot-report]` 검증 조건인 “근거 파일, 대상 row, p99/throughput/memory 수치, 개선 전 기준값”을 한눈에 검토하기 어렵다.

Before:

```markdown
45 - [ ] [hotspot-report] Dart TCP fixed latency/large payload/isolate gateway hardening, TypeScript WS large payload, Kotlin WS latency/slow-mix 검증 모델, TypeScript gateway overhead를 병목 리포트로 정리한다. 검증: 각 병목 후보에 근거 결과 파일, 대상 row, p99/throughput/memory 수치, 개선 전 기준값이 기록된다.
171 - 참고 결과:
172   - `agent-test/runs/20260603-062724-proto-socket-stress-full.md`는 ...
```

#### 해결 방법

`작업 컨텍스트` 아래에 병목 리포트 subsection 또는 compact table을 추가한다. 각 row는 병목 후보, 근거 result file, 대상 row/axis, 핵심 수치, 판정, 후속 Task id를 포함한다. `[hotspot-report]` 체크는 이 plan의 Roadmap Targets로 처리되므로 구현 중 직접 체크하지 않는다.

After:

```markdown
## 작업 컨텍스트

- 병목 리포트:
  - Dart TCP fixed latency / 1MB: ... 근거 ... 후속 Task ...
  - TypeScript WS 1MB: ... 근거 ... 후속 Task ...
  - Kotlin WS latency / slow-mix: ... 근거 ... 후속 Task ...
  - TypeScript gateway overhead: ... 근거 ... 후속 Task ...
```

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

- [ ] `agent-roadmap/milestones/performance-hotspot-optimization.md`: 병목 리포트 subsection/table을 추가한다.
- [ ] `agent-roadmap/milestones/performance-hotspot-optimization.md`: full idle baseline 부재와 quick/full stress 근거의 지위를 구분한다.
- [ ] `agent-roadmap/milestones/performance-hotspot-optimization.md`: `[hotspot-report]` checkbox는 직접 변경하지 않는다.

#### 테스트 작성

테스트 파일은 추가하지 않는다. 런타임 코드 변경이 없고, 검증 대상은 기존 stress/performance 결과 파일과 마일스톤 문서의 연결성이다.

#### 중간 검증

```bash
rg --sort path -n "병목 리포트|Dart TCP|TypeScript WS|Kotlin WS|TypeScript gateway|hotspot-report|idle-full|compare-rule" agent-roadmap/milestones/performance-hotspot-optimization.md
```

기대 결과: 병목 리포트와 `[hotspot-report]`, `[idle-full]`, `[compare-rule]` 상태가 함께 출력된다.

## 수정 파일 요약

| 파일 | 항목 |
|---|---|
| `agent-roadmap/milestones/performance-hotspot-optimization.md` | TEST-1 |
| `agent-task/m-performance-hotspot-optimization/01_hotspot_report/PLAN-local-G05.md` | task artifact |
| `agent-task/m-performance-hotspot-optimization/01_hotspot_report/CODE_REVIEW-local-G05.md` | task artifact |

## 최종 검증

```bash
git diff --check
rg --sort path -n "병목 리포트|agent-test/runs/20260603-062724-proto-socket-stress-full.md|agent-test/runs/20260602-232000-proto-socket-stress-full.md|agent-test/runs/20260603-080241-proto-socket-stress-full.md|Dart TCP|TypeScript WS|Kotlin WS|TypeScript gateway|Go|Python" agent-roadmap/milestones/performance-hotspot-optimization.md
```

기대 결과: `git diff --check`는 출력 없이 0으로 종료한다. `rg`는 병목 리포트와 각 근거 파일/언어 후보를 출력한다.

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