<!-- task=01_proto_socket_naming plan=0 tag=PSN -->

# Proto Socket Naming 통일 계획 - PSN

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

**`CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채우는 것은 필수 최종 단계다. 이 파일이 채워지기 전에는 작업이 완료된 것이 아니다.**
구현 체크리스트를 기준으로 작업하고, plan과 review stub 양쪽 체크리스트를 모두 완료하며, 중간/최종 검증의 실제 stdout/stderr를 `CODE_REVIEW-*-G??.md`에 기록한다.
review 파일의 `이 파일을 읽는 리뷰 에이전트에게` 섹션에 있는 아카이브 지시는 실행하지 않는다. `코드리뷰 전용 체크리스트`도 구현 에이전트가 수정하거나 체크하지 않는다.

## 배경

`common-proto-socket`은 이전 프로젝트명이고, 현재 저장소와 TypeScript 패키지는 `proto-socket`을 기준으로 정리되어 있다.
Go module path, Go import path, Go proto option, README, 외부 소비 예제가 아직 이전 이름을 참조해 이름과 배포 경로가 어긋난다.
브라우저 네이티브 WebSocket 작업 전에 공개 import path를 먼저 통일해야 다음 작업에서 TS/Go crosstest와 문서가 같은 이름을 기준으로 움직인다.

## 의존 관계 및 구현 순서

이 계획은 선행 작업이 없다.
`agent-task/01+browser_native_ws`는 이 작업이 PASS되어 `complete.log`까지 생성된 뒤 시작한다.

## 분석 결과

### 읽은 파일

- `AGENTS.md`
- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/project/domain/go/rules.md`
- `agent-ops/rules/project/domain/protocol/rules.md`
- `agent-ops/rules/project/domain/tools/rules.md`
- `agent-ops/skills/common/plan/SKILL.md`
- `README.md`
- `PROTOCOL.md`
- `go/go.mod`
- `go/base_client.go`
- `go/communicator.go`
- `go/communicator_nonce_test.go`
- `go/tcp_client.go`
- `go/tcp_server.go`
- `go/ws_client.go`
- `go/ws_server.go`
- `go/packets/message_common.proto`
- `go/test/communicator_test.go`
- `go/test/heartbeat_test.go`
- `go/test/tcp_test.go`
- `go/test/test_helpers_test.go`
- `go/test/tls_test.go`
- `go/test/ws_test.go`
- `examples/go-module-consumer/README.md`
- `examples/go-module-consumer/go.mod`
- `examples/go-module-consumer/go.sum`
- `examples/go-module-consumer/main.go`

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

- Go module/import path 변경: 기존 `cd go && go test -count=1 ./...`가 모든 Go 패키지 import compile을 검증한다. 별도 신규 테스트는 필요 없다.
- `go_package` 변경 및 생성 파일 갱신: 기존 proto sync 스크립트가 언어별 proto schema drift를 검증하지만, `go_package` 문자열 자체는 Go compile과 검색 검증으로 확인한다.
- README와 외부 소비 예제 변경: 기존 자동 테스트가 없다. 임시 디렉터리에서 local `replace`를 주입해 `go run .`으로 예제 compile을 검증한다.

### 심볼 참조

변경 대상 문자열은 `git.toki-labs.com/toki/common-proto-socket/go`와 `common-proto-socket`이다. `rg --sort path -n "common-proto-socket|common_proto_socket|common proto socket" . -g '!agent-task/archive/**' -g '!dart/.dart_tool/**' -g '!python/.pytest_cache/**'`에서 확인한 변경 필요 위치:

- `README.md:110`
- `README.md:111`
- `examples/go-module-consumer/README.md:31`
- `examples/go-module-consumer/go.mod:5`
- `examples/go-module-consumer/go.sum:1`
- `examples/go-module-consumer/go.sum:2`
- `examples/go-module-consumer/main.go:6`
- `go/base_client.go:8`
- `go/communicator.go:13`
- `go/communicator_nonce_test.go:10`
- `go/crosstest/dart_go_client/main.go:15`
- `go/crosstest/dart_go_client/main.go:16`
- `go/crosstest/go_dart.go:24`
- `go/crosstest/go_dart.go:25`
- `go/crosstest/go_kotlin.go:24`
- `go/crosstest/go_kotlin.go:25`
- `go/crosstest/go_python.go:24`
- `go/crosstest/go_python.go:25`
- `go/crosstest/go_typescript.go:24`
- `go/crosstest/go_typescript.go:25`
- `go/crosstest/kotlin_go_client/main.go:15`
- `go/crosstest/kotlin_go_client/main.go:16`
- `go/crosstest/python_go_client/main.go:15`
- `go/crosstest/python_go_client/main.go:16`
- `go/crosstest/typescript_go_client/main.go:15`
- `go/crosstest/typescript_go_client/main.go:16`
- `go/examples/tcp_echo/main.go:10`
- `go/examples/tcp_echo/main.go:11`
- `go/examples/ws_echo/main.go:9`
- `go/examples/ws_echo/main.go:10`
- `go/go.mod:1`
- `go/packets/message_common.pb.go:194`
- `go/packets/message_common.proto:3`
- `go/tcp_client.go:15`
- `go/test/communicator_test.go:11`
- `go/test/communicator_test.go:12`
- `go/test/heartbeat_test.go:15`
- `go/test/tcp_test.go:11`
- `go/test/tcp_test.go:12`
- `go/test/test_helpers_test.go:16`
- `go/test/test_helpers_test.go:17`
- `go/test/tls_test.go:11`
- `go/test/tls_test.go:12`
- `go/test/ws_test.go:12`
- `go/test/ws_test.go:13`
- `go/ws_client.go:13`

### 범위 결정 근거

- `agent-task/archive/**`는 프로젝트 규칙에 따라 읽거나 변경하지 않는다.
- Dart/Python/Kotlin의 언어별 package/module 표기인 `proto_socket`, `proto-socket`은 이전 프로젝트명 문제가 아니므로 변경하지 않는다.
- 프로토콜 메시지 schema는 변경하지 않는다. Go proto 복사본의 `go_package` option과 생성 산출물만 갱신한다.
- 원격 Forgejo 저장소명 변경, tag 생성, module publish는 이 구현 범위를 벗어난 운영 작업이다. 예제 검증은 local `replace`로 수행한다.

### 빌드 등급

build=`cloud-G08`, review=`cloud-G08`. Go module path와 generated proto, 문서, crosstest/import call-site가 넓게 걸리는 API 경로 변경이며 프로토콜 생성물 검증이 필요하다.

## 구현 체크리스트

- [ ] [PSN-1] Go module path, Go imports, Go proto option, generated packet 파일을 `proto-socket` 기준으로 갱신한다.
- [ ] [PSN-2] README와 Go module consumer 예제를 새 module path 기준으로 갱신한다.
- [ ] [PSN-3] 중간 검증과 최종 검증 명령을 실행하고 실제 출력을 review stub에 기록한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [PSN-1] Go module path와 proto 생성물 갱신

#### 문제

`go/go.mod:1`의 module path가 이전 이름을 사용한다.

```go
// go/go.mod:1
module git.toki-labs.com/toki/common-proto-socket/go
```

`go/packets/message_common.proto:3`의 Go package option도 이전 module path를 포함한다.

```proto
// go/packets/message_common.proto:3
option go_package = "git.toki-labs.com/toki/common-proto-socket/go/packets";
```

Go 소스, Go 테스트, crosstest, 예제는 같은 이전 import path를 참조한다. 예: `go/base_client.go:8`.

```go
// go/base_client.go:8
"git.toki-labs.com/toki/common-proto-socket/go/packets"
```

#### 해결 방법

module path와 모든 Go import path를 `git.toki-labs.com/toki/proto-socket/go`로 치환한다.

```go
// go/go.mod:1
module git.toki-labs.com/toki/proto-socket/go
```

```proto
// go/packets/message_common.proto:3
option go_package = "git.toki-labs.com/toki/proto-socket/go/packets";
```

```go
// go/base_client.go:8
"git.toki-labs.com/toki/proto-socket/go/packets"
```

`go/packets/message_common.pb.go`는 직접 문자열 패치로 맞추지 말고 기존 proto 생성 경로로 재생성한다. 생성 도구가 환경 문제로 실행되지 않으면 `command -v protoc`, `command -v protoc-gen-go` 결과와 대체 명령을 `CODE_REVIEW-*-G??.md`의 `계획 대비 변경 사항`에 남긴다.

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

- [ ] `go/go.mod` module path 변경
- [ ] `go/packets/message_common.proto`의 `go_package` 변경
- [ ] `go/packets/message_common.pb.go` 재생성
- [ ] `go/base_client.go` import 변경
- [ ] `go/communicator.go` import 변경
- [ ] `go/communicator_nonce_test.go` import 변경
- [ ] `go/tcp_client.go` import 변경
- [ ] `go/ws_client.go` import 변경
- [ ] `go/test/*.go` import 변경
- [ ] `go/crosstest/**/*.go` import 변경
- [ ] `go/examples/**/*.go` import 변경

#### 테스트 작성

신규 테스트는 작성하지 않는다. 이 변경은 runtime behavior가 아니라 module/import path 정리이며 기존 Go 단위 테스트와 crosstest compile이 회귀 검증 역할을 한다.

#### 중간 검증

```bash
tools/generate_proto.sh
```

예상 결과: 성공 종료. Go 생성물의 `go_package` 경로가 새 module path를 포함한다.

```bash
tools/check_proto_sync.sh
```

예상 결과: 성공 종료.

```bash
cd go && go test -count=1 ./...
```

예상 결과: 모든 Go 패키지 테스트 성공. fresh 실행이 필요하므로 Go test cache 출력은 허용하지 않는다.

### [PSN-2] 문서와 Go module consumer 예제 갱신

#### 문제

README quick start가 이전 import path를 안내한다.

```go
// README.md:110-111
protoSocket "git.toki-labs.com/toki/common-proto-socket/go"
"git.toki-labs.com/toki/common-proto-socket/go/packets"
```

외부 소비 예제도 이전 module path를 require/import한다.

```go
// examples/go-module-consumer/main.go:6
protoSocket "git.toki-labs.com/toki/common-proto-socket/go"
```

```go
// examples/go-module-consumer/go.mod:5
require git.toki-labs.com/toki/common-proto-socket/go v0.0.0-20260501220005-284b66a22300
```

#### 해결 방법

README와 예제의 안내/import/require를 `git.toki-labs.com/toki/proto-socket/go`로 바꾼다.
`examples/go-module-consumer/go.sum`의 이전 module path checksum은 제거한다. 새 module path가 원격에 publish되지 않은 상태에서 임의 checksum을 만들지 않는다.

```go
// README.md:110-111
protoSocket "git.toki-labs.com/toki/proto-socket/go"
"git.toki-labs.com/toki/proto-socket/go/packets"
```

```go
// examples/go-module-consumer/main.go:6
protoSocket "git.toki-labs.com/toki/proto-socket/go"
```

```go
// examples/go-module-consumer/go.mod:5
require git.toki-labs.com/toki/proto-socket/go v0.0.0-20260501220005-284b66a22300
```

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

- [ ] `README.md` Go quick start import path 변경
- [ ] `examples/go-module-consumer/README.md` install command 변경
- [ ] `examples/go-module-consumer/go.mod` require path 변경
- [ ] `examples/go-module-consumer/go.sum` old path checksum 제거
- [ ] `examples/go-module-consumer/main.go` import path 변경

#### 테스트 작성

신규 테스트는 작성하지 않는다. 예제 compile 검증은 임시 디렉터리에서 local replace를 주입해 실행한다.

#### 중간 검증

```bash
tmp="$(mktemp -d)" && cp -R examples/go-module-consumer "$tmp/go-module-consumer" && cd "$tmp/go-module-consumer" && go mod edit -replace git.toki-labs.com/toki/proto-socket/go=/config/workspace/proto-socket/go && go mod tidy && go run .
```

예상 결과: `proto-socket import OK` 출력 후 성공 종료. 임시 디렉터리만 사용하며 저장소 파일을 변경하지 않는다.

### [PSN-3] 이름 잔여물 검색 검증

#### 문제

이 작업의 성공 조건은 이전 프로젝트명 잔여 참조가 없는 것이다. 일부 잔여 문자열은 generated file, docs, sum 파일에 남기 쉬워 search contract가 필요하다.

#### 해결 방법

정렬된 `rg` 명령으로 archive와 캐시 경로를 제외하고 이전 이름을 검색한다. 결과가 있으면 모두 변경 필요 항목으로 처리한다.

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

- [ ] 최종 검색 명령 결과가 비어 있는지 확인
- [ ] 남은 결과가 있다면 의도된 예외인지 evidence를 남기거나 제거

#### 테스트 작성

검색 검증만 수행한다. 신규 테스트는 작성하지 않는다.

#### 중간 검증

```bash
rg --sort path -n "common-proto-socket|common_proto_socket|common proto socket" . -g '!agent-task/archive/**' -g '!dart/.dart_tool/**' -g '!python/.pytest_cache/**'
```

예상 결과: 출력 없음.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `go/go.mod` | PSN-1 |
| `go/packets/message_common.proto` | PSN-1 |
| `go/packets/message_common.pb.go` | PSN-1 |
| `go/*.go` | PSN-1 |
| `go/test/*.go` | PSN-1 |
| `go/crosstest/**/*.go` | PSN-1 |
| `go/examples/**/*.go` | PSN-1 |
| `README.md` | PSN-2 |
| `examples/go-module-consumer/README.md` | PSN-2 |
| `examples/go-module-consumer/go.mod` | PSN-2 |
| `examples/go-module-consumer/go.sum` | PSN-2 |
| `examples/go-module-consumer/main.go` | PSN-2 |

## 최종 검증

```bash
tools/generate_proto.sh
```

예상 결과: 성공 종료.

```bash
tools/check_proto_sync.sh
```

예상 결과: 성공 종료.

```bash
cd go && go test -count=1 ./...
```

예상 결과: 모든 테스트 성공. Go test cache 출력은 허용하지 않는다.

```bash
tmp="$(mktemp -d)" && cp -R examples/go-module-consumer "$tmp/go-module-consumer" && cd "$tmp/go-module-consumer" && go mod edit -replace git.toki-labs.com/toki/proto-socket/go=/config/workspace/proto-socket/go && go mod tidy && go run .
```

예상 결과: `proto-socket import OK` 출력 후 성공 종료.

```bash
rg --sort path -n "common-proto-socket|common_proto_socket|common proto socket" . -g '!agent-task/archive/**' -g '!dart/.dart_tool/**' -g '!python/.pytest_cache/**'
```

예상 결과: 출력 없음.

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