<!-- task=02+edge_setup_cli plan=2 tag=REVIEW_REVIEW_EDGECLI -->

# Edge Setup CLI Follow-up Plan

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

**구현 마지막 단계에서 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채우는 것은 필수다. 이 파일을 채우기 전에는 작업이 완료된 것이 아니다.** 구현 체크리스트를 기준으로 작업하고, 중간/최종 검증의 실제 stdout/stderr를 review 파일에 기록하라. review 파일의 아카이브 지시와 `코드리뷰 전용 체크리스트`는 리뷰 에이전트 전용이다.

## 배경

plan=1 리뷰 결과는 `FAIL`이다. 루트 workspace에서는 edge cmd 검증이 통과했지만, `GOWORK=off` module mode에서는 기존 missing module 오류가 재현되어 Go module/import 계약이 아직 정리되지 않았다. 또한 `docs/deploy-dev.md`는 정리됐지만 `docs/architecture.md`에는 현재 구현되지 않은 `iop-node setup` 경로가 공식 흐름처럼 남아 있다.

## 의존 관계 및 구현 순서

- 선행 로그: `plan_cloud_G07_0.log`, `code_review_cloud_G07_0.log`, `plan_cloud_G07_1.log`, `code_review_cloud_G07_1.log`
- 이 follow-up은 `code_review_cloud_G07_1.log`의 Required 이슈를 닫기 위한 작업이다.
- `agent-task/03+node_setup_cli`와 병렬일 수 있지만, 이 task 단독 완료 상태에서도 현재 node CLI와 문서가 모순되면 안 된다.

## 분석 결과

### 읽은 파일

- `agent-task/02+edge_setup_cli/code_review_cloud_G07_1.log`
- `agent-task/02+edge_setup_cli/plan_cloud_G07_1.log`
- `go.mod`
- `go.work`
- `go.work.sum`
- `apps/node/cmd/node/main.go`
- `docs/architecture.md`
- `docs/deploy-dev.md`

### 실패 요약

- `GOWORK=off go test -count=1 ./apps/edge/cmd/edge ./packages/hostsetup`가 `git.toki-labs.com/toki/proto-socket/go/packets` missing module 오류로 실패한다.
- `docs/architecture.md:122`와 `docs/architecture.md:136`은 현재 없는 `iop-node setup`을 초기 공식 운영 경로처럼 안내한다.

### 범위 결정 근거

- Required 이슈만 좁게 닫는다.
- edge CLI 명령 동작 자체는 재설계하지 않는다.
- node CLI 구현은 이 task에서 추가하지 않는다.
- `../proto-socket` repo를 수정하지 않는다. 필요한 변경은 iop repo의 module/import/docs 계약 안에서 해결한다.

### 빌드 등급

- build: `cloud-G07`, review: `cloud-G07`
- 근거: Go module/workspace 계약, CLI 검증, 문서 API 계약을 함께 다룬다.

## 구현 체크리스트

- [ ] [REVIEW_REVIEW_EDGECLI-1] edge cmd 검증이 workspace mode와 module mode 모두에서 재현되도록 Go module/import 계약을 정리한다.
- [ ] [REVIEW_REVIEW_EDGECLI-2] `docs/architecture.md`의 node setup 안내가 현재 구현 상태와 모순되지 않게 정리한다.
- [ ] 중간 검증과 최종 검증 명령을 실행하고 실제 출력을 기록한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [REVIEW_REVIEW_EDGECLI-1] edge cmd 검증이 workspace mode와 module mode 모두에서 재현되도록 Go module/import 계약을 정리한다

#### 문제

`go.work` 추가로 일반 `go test`는 통과하지만, module-only mode는 여전히 실패한다.

```bash
GOWORK=off go test -count=1 ./apps/edge/cmd/edge ./packages/hostsetup
```

실패 원인은 iop `go.mod`가 `git.toki-labs.com/toki/common-proto-socket/go => ../proto-socket/go`를 replace하지만, local module의 실제 module path와 내부 import는 `git.toki-labs.com/toki/proto-socket/go` 계열이라는 점이다.

#### 해결 방법

iop repo 안에서 module/import 계약을 정리해 아래 두 모드가 모두 통과하게 만든다.

- workspace mode: `go test -count=1 ./apps/edge/cmd/edge ./packages/hostsetup`
- module mode: `GOWORK=off go test -count=1 ./apps/edge/cmd/edge ./packages/hostsetup`

구현 후보:

- iop의 proto-socket import/require/replace를 local module의 canonical path와 일치시키고, stale `common-proto-socket` 참조를 정리한다.
- 또는 `common-proto-socket` 경계를 유지해야 한다면 module mode에서도 nested `proto-socket/go/packets` import가 해결되는 명시적 require/replace 조합을 검증한다.

`go.work`와 `go.work.sum`은 공식 repo 계약으로 남길지, module 계약 정리 후 제거할지 결정한다. 남긴다면 이유를 `주요 설계 결정`에 기록하고, 제거한다면 untracked/generated 파일을 남기지 않는다.

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

- [ ] `go.mod` 및 필요 시 `go.sum` 수정.
- [ ] 필요 시 `apps/**`의 proto-socket import 경로 수정.
- [ ] `go.work`/`go.work.sum` 유지 여부 결정 및 정리.
- [ ] workspace mode와 `GOWORK=off` mode 모두에서 edge cmd 검증 성공 확인.

#### 중간 검증

```bash
go test -count=1 ./apps/edge/cmd/edge ./packages/hostsetup
GOWORK=off go test -count=1 ./apps/edge/cmd/edge ./packages/hostsetup
go run ./apps/edge/cmd/edge version
go run ./apps/edge/cmd/edge config check --config configs/edge.yaml
go run ./apps/edge/cmd/edge setup --dry-run --binary /usr/local/bin/iop-edge
```

### [REVIEW_REVIEW_EDGECLI-2] `docs/architecture.md`의 node setup 안내가 현재 구현 상태와 모순되지 않게 정리한다

#### 문제

`docs/deploy-dev.md`는 edge 전용 현재 구현 문서로 정리됐지만, `docs/architecture.md`에는 다음 문구가 남아 있다.

- `초기 공식 경로는 iop-edge setup과 iop-node setup 하나로 고정`
- `node host: iop-node setup -> systemd unit + config/data directories`

현재 `apps/node/cmd/node/main.go`에는 `setup`과 `config check`가 없다.

#### 해결 방법

architecture 문서도 현재 구현과 계획 상태를 구분한다.

- edge setup은 현재 구현된 경로로 설명한다.
- node setup은 `agent-task/03+node_setup_cli` 완료 후 제공될 예정임을 명시하거나, 현재형 공식 경로에서 제거한다.
- 장기 아키텍처 방향은 유지하되, 현재 CLI 계약과 충돌하지 않게 문장을 조정한다.

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

- [ ] `docs/architecture.md` 수정.
- [ ] repo 문서 전역에서 현재 없는 `iop-node setup`/`iop-node config check`가 공식 현재 경로처럼 남아 있지 않은지 확인.

#### 중간 검증

```bash
rg --sort path -n "iop-node setup|iop-node config check|sudo iop-node setup" docs README.md apps/node apps/edge
```

검색 결과가 남는 경우, 현재 구현된 명령인지 또는 후속 task 예정임이 같은 문맥에서 명확해야 한다.

## 수정 파일 요약

| 파일 | 항목 |
|---|---|
| `go.mod` | REVIEW_REVIEW_EDGECLI-1 |
| `go.sum` | REVIEW_REVIEW_EDGECLI-1, 필요 시 |
| `go.work` | REVIEW_REVIEW_EDGECLI-1, 유지/삭제 결정 |
| `go.work.sum` | REVIEW_REVIEW_EDGECLI-1, 유지/삭제 결정 |
| `apps/**` Go import 파일 | REVIEW_REVIEW_EDGECLI-1, 필요 시 |
| `docs/architecture.md` | REVIEW_REVIEW_EDGECLI-2 |

## 최종 검증

```bash
gofmt -w apps/edge/cmd/edge packages/hostsetup
go test -count=1 ./apps/edge/cmd/edge ./packages/hostsetup
GOWORK=off go test -count=1 ./apps/edge/cmd/edge ./packages/hostsetup
go test -count=1 ./packages/config ./packages/hostsetup ./packages/version
go test -count=1 ./...
go run ./apps/edge/cmd/edge version
go run ./apps/edge/cmd/edge config check --config configs/edge.yaml
go run ./apps/edge/cmd/edge setup --dry-run --binary /usr/local/bin/iop-edge
rg --sort path -n "service install|service status|\\brender\\b" docs apps/edge/README.md
rg --sort path -n "iop-node setup|iop-node config check|sudo iop-node setup" docs README.md apps/node apps/edge
```

검색 결과가 남는 경우, 해당 hit가 금지 명령의 공식 현재 경로 소개가 아니거나 node follow-up 예정임이 명확해야 한다.

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