add agent-test dev smoke tests and update config files

2026-06-12 19:07:04 +09:00 · 2026-06-12 19:07:04 +09:00 · 1a90b7fe09
commit 1a90b7fe09
parent 7398f326b3
13 changed files with 685 additions and 3 deletions
--- a/.env.dev.example
+++ b/.env.dev.example
@ -0,0 +1,20 @@
+COMPOSE_PROJECT_NAME=iop-dev-agent
+IOP_COMPOSE_NETWORK=iop-dev-agent-net
+
+IOP_CONTROL_PLANE_HTTP_PORT=18001
+IOP_CONTROL_PLANE_WIRE_PORT=19001
+IOP_CONTROL_PLANE_EDGE_WIRE_PORT=19002
+IOP_EDGE_NODE_PORT=19003
+IOP_WEB_PORT=13001
+
+IOP_CONTROL_PLANE_HTTP_URL=http://toki-labs.com:18001
+IOP_CONTROL_PLANE_WIRE_URL=ws://toki-labs.com:19001/client
+
+IOP_POSTGRES_USER=iop
+IOP_POSTGRES_PASSWORD=iop_dev_password
+IOP_POSTGRES_DB=iop-control-plane-dev-agent
+IOP_POSTGRES_PORT=15401
+
+IOP_REDIS_PORT=16301
+IOP_REDIS_DB=3
+IOP_REDIS_KEY_PREFIX=iop:control-plane:dev-agent:
--- a/AGENTS.md
+++ b/AGENTS.md
@ -42,3 +42,4 @@
 **테스트 실행/검증 작업이 포함된 경우, 작업 환경에 맞게 최초 1회 읽고 수행한다. 환경 미지정은 local로 본다.**

 - local: `agent-test/local/rules.md` (없으면 `create-test`)
+- dev: `agent-test/dev/rules.md` (없으면 `create-test`)
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -42,3 +42,4 @@
 **테스트 실행/검증 작업이 포함된 경우, 작업 환경에 맞게 최초 1회 읽고 수행한다. 환경 미지정은 local로 본다.**

 - local: `agent-test/local/rules.md` (없으면 `create-test`)
+- dev: `agent-test/dev/rules.md` (없으면 `create-test`)
--- a/GEMINI.md
+++ b/GEMINI.md
@ -42,3 +42,4 @@
 **테스트 실행/검증 작업이 포함된 경우, 작업 환경에 맞게 최초 1회 읽고 수행한다. 환경 미지정은 local로 본다.**

 - local: `agent-test/local/rules.md` (없으면 `create-test`)
+- dev: `agent-test/dev/rules.md` (없으면 `create-test`)
--- a/6
+++ b/6
@ -18,6 +18,8 @@ NODE_TARGETS ?= linux-arm64 linux-amd64 darwin-arm64 darwin-amd64 windows-arm64
 NODE_TARGET_PARTS = $(subst -, ,$(NODE_TARGET))
 NODE_GOOS = $(word 1,$(NODE_TARGET_PARTS))
 NODE_GOARCH = $(word 2,$(NODE_TARGET_PARTS))
+IOP_CONTROL_PLANE_HTTP_URL ?= http://localhost:18000
+IOP_CONTROL_PLANE_WIRE_URL ?= ws://localhost:19080/client

 all: build

@ -128,8 +130,8 @@ client-test:

 client-build-web:
 	cd apps/client && flutter build web \
-		--dart-define=IOP_CONTROL_PLANE_HTTP_URL=http://localhost:18000 \
-		--dart-define=IOP_CONTROL_PLANE_WIRE_URL=ws://localhost:19080/client
+		--dart-define=IOP_CONTROL_PLANE_HTTP_URL=$(IOP_CONTROL_PLANE_HTTP_URL) \
+		--dart-define=IOP_CONTROL_PLANE_WIRE_URL=$(IOP_CONTROL_PLANE_WIRE_URL)

 clean:
 	rm -rf build
--- a/agent-test/dev/client-smoke.md
+++ b/agent-test/dev/client-smoke.md
@ -0,0 +1,98 @@
+---
+test_env: dev
+test_profile: client-smoke
+domain: client
+verification_type: smoke
+last_rule_updated_at: 2026-06-12
+---
+
+# client-smoke dev 테스트
+
+## 읽기 조건
+
+- `apps/client/**` 또는 `packages/flutter/iop_console/**` 변경의 dev 테스트, 검증, 실행 조건 판단이 필요한 경우
+
+## 적용 범위
+
+- IOP Flutter client app shell
+- IOP-owned embeddable console package
+- Client-Control Plane proto-socket hello baseline
+- Flutter widget/unit tests
+- dev web preview와 compose web build URL 주입
+
+## 분류
+
+- domain: client
+- verification_type: smoke
+- scope: Flutter client와 IOP console package 변경
+
+## 환경
+
+- host: Flutter client 또는 `packages/flutter/iop_console`가 포함된 runtime evidence는 원격 runner `ssh toki@toki-labs.com`의 `/Users/toki/agent-work/iop-dev` 기준으로 수행한다.
+- port: web/dev preview `13001`, Control Plane HTTP `18001`, Portal/Control Plane wire test endpoint `19001`, Edge-Node TCP transport `19003`.
+- runtime: Flutter/Dart
+- package manager: Flutter pub
+- docker: compose 검증은 `docker compose --env-file .env.dev.example ...` 기준이다.
+- external service: sibling path dependencies `../agent-shell`, `../nexo/packages/messaging_flutter`, `../proto-socket/dart`
+- model endpoint:
+- credential: token/secret 원문은 문서에 기록하지 않는다.
+
+명령은 원격 runner 사용 시 `/Users/toki/agent-work/iop-dev` 기준으로 실행한다. 현재 작업 컨테이너의 변경분이 원격 checkout에 동기화되지 않았으면 원격 검증 완료로 보지 않는다.
+
+## 명령
+
+- setup: `cd apps/client && flutter pub get`
+- package-setup: `cd packages/flutter/iop_console && flutter pub get`
+- unit: `cd apps/client && flutter test`
+- package-unit: `cd packages/flutter/iop_console && flutter test`
+- lint: `cd apps/client && flutter analyze --no-fatal-infos`
+- smoke: `cd apps/client && flutter test`
+- e2e: `IOP_WEB_PORT=13001 IOP_CONTROL_PLANE_HTTP_URL=http://toki-labs.com:18001 IOP_CONTROL_PLANE_WIRE_URL=ws://toki-labs.com:19001/client ./scripts/dev/web.sh`
+- compose-e2e: `IOP_EDGE_NODE_TOKEN=<token> docker compose --env-file .env.dev.example up --build`
+- web-build: `make client-build-web IOP_CONTROL_PLANE_HTTP_URL=http://toki-labs.com:18001 IOP_CONTROL_PLANE_WIRE_URL=ws://toki-labs.com:19001/client`
+- model:
+- full-cycle:
+
+## 필수 검증
+
+- client 또는 `packages/flutter/iop_console` 변경은 최소 `cd apps/client && flutter test`로 확인한다.
+- `packages/flutter/iop_console` 자체 API나 widget 구조가 바뀌면 `cd packages/flutter/iop_console && flutter test` 실행 가능 여부를 확인한다.
+- analyzer 영향이 있는 dependency, app shell, generated import 변경이면 `cd apps/client && flutter analyze --no-fatal-infos`를 함께 확인한다.
+- Web build/deploy, `apps/client/Dockerfile`, `docker-compose.yml`, `scripts/dev/web.sh`, `Makefile client-build-web` 변경은 원격 runner에서 dev-server 기동 또는 compose build 중 변경 범위에 맞는 경로를 확인하고, 외부 브라우저 확인 URL이 `http://toki-labs.com:13001` 계열인지 보고한다.
+- compose 경로를 확인할 때는 `IOP_EDGE_NODE_TOKEN`을 원격 runner 환경에서 주입하고, token 원문은 tracked 파일에 기록하지 않는다.
+
+## 보조 검증
+
+- `cd apps/client && flutter pub get`
+- `cd packages/flutter/iop_console && flutter pub get`
+
+## 판정 기준
+
+- Flutter test가 실패 없이 종료한다.
+- Analyzer는 기존 non-fatal info를 기능 실패로 확대하지 않는다.
+- path dependency가 없어 실행하지 못하면 누락된 sibling workspace를 차단 사유로 보고한다.
+- dev web preview가 필요한 경우 browser-facing URL과 compiled Control Plane HTTP/WS URL이 모두 dev 포트(`13001`, `18001`, `19001`)를 사용한다.
+
+## 기준 출력 예시
+
+```text
+All tests passed!
+```
+
+## 차단 기준
+
+- 원격 runner 접근, Flutter SDK, Docker compose, 또는 필요한 dev 포트 개방이 없어 client runtime 검증을 실행할 수 없다.
+- 필요한 sibling path dependency가 없어 `flutter pub get` 또는 test가 진행되지 않는다.
+
+## 보고 항목
+
+- 실행한 명령:
+- 성공한 검증:
+- 실패/차단된 검증:
+- 생략 사유:
+- 남은 위험:
+
+## 금지 사항
+
+- secret, token, 개인 endpoint 원문은 tracked 파일에 기록하지 않는다.
+- IOP client에 NomadCode product shell UX를 직접 복제하지 않는다.
--- a/agent-test/dev/control-plane-smoke.md
+++ b/agent-test/dev/control-plane-smoke.md
@ -0,0 +1,95 @@
+---
+test_env: dev
+test_profile: control-plane-smoke
+domain: control-plane
+verification_type: smoke
+last_rule_updated_at: 2026-06-12
+---
+
+# control-plane-smoke dev 테스트
+
+## 읽기 조건
+
+- `apps/control-plane/**` 변경 또는 Control Plane health/readiness, config loading, wire endpoint dev 검증 판단이 필요한 경우
+
+## 적용 범위
+
+- `apps/control-plane/cmd/control-plane/**`
+- `apps/control-plane/internal/wire/**`
+- `apps/control-plane/Dockerfile`
+- Control Plane HTTP health/readiness와 proto-socket WebSocket hello baseline
+- Control Plane-Edge TCP wire endpoint, Edge outbound hello, disconnect baseline
+- dev compose host publish와 DB/Redis 분리
+
+## 분류
+
+- domain: control-plane
+- verification_type: smoke
+- scope: control-plane HTTP와 wire baseline
+
+## 환경
+
+- host: Docker compose 또는 Flutter client가 포함된 runtime evidence는 원격 runner `ssh toki@toki-labs.com`의 `/Users/toki/agent-work/iop-dev` 기준으로 수행한다.
+- port: Control Plane HTTP `18001` (host-facing), Portal/Control Plane wire test endpoint `19001`, CP-Edge wire `19002`, Edge-Node TCP transport `19003`, web/dev preview `13001`.
+- runtime: Go `1.24`, Docker compose
+- package manager: Go modules / Makefile
+- docker: `docker-compose.yml`에 postgres, redis, control-plane, edge, web service가 정의되어 있다. dev 검증은 `docker compose --env-file .env.dev.example ...`로 수행한다.
+- external service: postgres host publish `15401`, redis host publish `16301`
+- model endpoint:
+- credential: DB/Redis credential 원문은 문서에 기록하지 않는다.
+
+## 명령
+
+- setup: `IOP_EDGE_NODE_TOKEN=<token> docker compose --env-file .env.dev.example up -d postgres redis control-plane edge web`
+- lint:
+- unit: `go test ./apps/control-plane/...`
+- smoke: `curl -fsS http://127.0.0.1:18001/healthz`, `curl -fsS http://127.0.0.1:18001/readyz`
+- e2e: `make test-control-plane-edge-wire`는 보조 smoke이며 기본 포트를 쓰는 스크립트이므로 dev 포트 override 가능 여부를 먼저 확인한다.
+- model:
+- full-cycle: Control Plane command, health/readiness, wire hello 수동 검증
+
+## 필수 검증
+
+- 변경한 control-plane 패키지 또는 `go test ./apps/control-plane/...`를 실행한다.
+- HTTP lifecycle 변경 시 dev port `/healthz`와 `/readyz`를 확인한다.
+- Client-Control Plane wire protocol 변경 시 proto-socket WebSocket hello baseline을 dev wire port `19001` 기준으로 확인한다.
+- Control Plane-Edge TCP wire, Edge outbound connector, registry lifecycle 변경 시 dev `19002` 기준으로 hello accepted, Edge connected, Edge disconnected marker를 확인한다.
+
+## 보조 검증
+
+- docker compose control-plane service healthcheck를 확인한다.
+- Edge 포함 compose 검증에서는 `IOP_EDGE_NODE_TOKEN`을 원격 runner 환경에서 주입하고, token 원문은 tracked 파일에 기록하지 않는다.
+
+## 판정 기준
+
+- control-plane service가 dev stack으로 기동되고 health endpoint가 성공 응답을 반환한다.
+- wire endpoint는 Control Plane 브라우저/앱 경계로 유지되고 Node 직접 연결/스케줄링 경로로 확장되지 않는다.
+- dev stack은 local/test stack의 host publish 포트(`13000`, `18000`, `19080`, `19081`, `15400`, `16300`)를 점유하지 않는다.
+
+## 기준 출력 예시
+
+```text
+curl -fsS http://127.0.0.1:18001/healthz
+curl -fsS http://127.0.0.1:18001/readyz
+```
+
+## 차단 기준
+
+- docker compose 실행 권한 또는 postgres/redis service 기동이 불가능하다.
+- 현재 작업 컨테이너에서 Docker-in-Docker가 필요해지는 검증은 수행하지 않고 원격 runner 차단으로 보고한다.
+- 실제 DB/Redis credential 확인이 필요한데 안전하게 제공되지 않았다.
+- dev 포트가 이미 점유되어 있어 local/test stack과 공존할 수 없다.
+
+## 보고 항목
+
+- 실행한 명령:
+- 성공한 검증:
+- 실패/차단된 검증:
+- 생략 사유:
+- 남은 위험:
+
+## 금지 사항
+
+- Control Plane에서 Node 직접 연결이나 직접 스케줄링을 제품 기본 계약으로 만들지 않는다.
+- 실제 DB/Redis credential이나 private endpoint를 tracked docs/rules에 기록하지 않는다.
+- secret, token, 개인 endpoint 원문은 tracked 파일에 기록하지 않는다.
--- a/agent-test/dev/edge-smoke.md
+++ b/agent-test/dev/edge-smoke.md
@ -0,0 +1,100 @@
+---
+test_env: dev
+test_profile: edge-smoke
+domain: edge
+verification_type: smoke
+last_rule_updated_at: 2026-06-12
+---
+
+# edge-smoke dev 테스트
+
+## 읽기 조건
+
+- `apps/edge/**` 변경 또는 edge registry, transport, service, console, OpenAI-compatible/A2A 입력 표면 dev 검증 판단이 필요한 경우
+
+## 적용 범위
+
+- `apps/edge/cmd/edge/**`
+- `apps/edge/internal/bootstrap/**`
+- `apps/edge/internal/transport/**`
+- `apps/edge/internal/service/**`
+- `apps/edge/internal/events/**`
+- `apps/edge/internal/input/**`
+- `apps/edge/internal/openai/**`
+- `apps/edge/internal/opsconsole/**`
+- `apps/edge/internal/node/**`
+
+## 분류
+
+- domain: edge
+- verification_type: smoke
+- scope: edge 실행 그룹, node registry, input surface baseline
+
+## 환경
+
+- host: local checkout. dev runtime, external CLI, shared port evidence가 필요하면 원격 runner를 사용한다.
+- port: compose Edge-Node TCP transport `19003`; dev artifact/bootstrap HTTP 후보 `18082`, dev Edge OpenAI-compatible HTTP 후보 `18083`, dev Edge metrics 후보 `19101`.
+- runtime: Go `1.24`
+- package manager: Go modules / Makefile
+- docker: unit/smoke quick check는 Docker를 요구하지 않는다. compose dev 검증은 `docker compose --env-file .env.dev.example ...`로 수행한다.
+- external service: dev artifact/base URL 후보 `http://toki-labs.com:18082`, dev Edge runtime 주소 후보 `toki-labs.com:19003`
+- model endpoint: dev OpenAI-compatible base URL 후보 `http://toki-labs.com:18083/v1`
+- credential: token/secret 원문은 문서에 기록하지 않는다.
+
+## 명령
+
+- setup:
+- lint:
+- unit: `go test ./apps/edge/...`
+- smoke: `./scripts/e2e-smoke.sh`는 기본 포트 임시 설정을 쓰는 보조 smoke이므로 dev 포트 override 필요 여부를 먼저 확인한다.
+- e2e: `make test-e2e`는 보조 smoke이며 full-cycle 실제 구동을 대체하지 않는다.
+- model: dev OpenAI-compatible profile을 띄운 경우 `iop-edge smoke openai --base-url http://127.0.0.1:18083`
+- full-cycle: repo 내부 edge-node 진단, `iop-edge smoke openai`, OpenAI-compatible 입력 표면 수동 검증
+
+## 필수 검증
+
+- 변경한 edge 패키지 또는 `go test ./apps/edge/...`를 실행한다.
+- registry, service, transport, console, HTTP/A2A 입력 표면을 바꾼 경우 edge-node 메시지 2회 왕복과 command 응답을 확인한다.
+- OpenAI-compatible 경계를 바꾼 경우 dev `18083` 기준 `iop-edge smoke openai` 또는 동등한 `/healthz`, `/v1/models`, `/v1/responses` 확인으로 edge service와 node adapter 경로 수렴을 확인한다.
+- bootstrap/artifact 경계를 바꾼 경우 dev artifact/base URL 후보 `18082`가 local/test `18080` field baseline을 덮어쓰지 않는지 확인한다.
+
+## 보조 검증
+
+- `./scripts/e2e-smoke.sh`는 edge-node 최소 생존 확인에 사용한다.
+- `./scripts/e2e-openai-ollama.sh`는 OpenAI-compatible Ollama 입력 표면 보조 확인에 사용한다.
+
+## 판정 기준
+
+- node 등록, `/nodes`, console 메시지 전송, 기대 payload를 포함한 `[node-*-message]` 출력, 같은 run의 complete event가 확인된다.
+- node 로컬 `[node-message]` payload 라인 목록과 edge `[node-*-message]` payload 라인 목록이 run별로 내용/순서까지 동일해야 한다.
+- edge complete는 같은 run의 마지막 `[node-*-message]` 이후에만 정상이다.
+- OpenAI-compatible smoke에서 `/healthz`, `/v1/models`, `/v1/responses`가 기대 상태로 응답한다.
+- bootstrap 사용자 명령은 완성된 URL과 positional token 하나만 포함한다.
+
+## 기준 출력 예시
+
+```text
+edge> /nodes
+[edge] sent run_id=...
+[node-*-message] IOP_EXPECTED_REPLY
+[node-*-event] complete
+```
+
+## 차단 기준
+
+- dev host 또는 Edge-Node TCP port 접근이 불가능하다.
+- 외부 CLI profile 검증에 필요한 CLI 설치, 계정, provider 상태가 없다.
+- dev artifact/model/metrics 포트가 기존 field baseline과 충돌한다.
+
+## 보고 항목
+
+- 실행한 명령:
+- 성공한 검증:
+- 실패/차단된 검증:
+- 생략 사유:
+- 남은 위험:
+
+## 금지 사항
+
+- secret, token, 개인 endpoint 원문은 tracked 파일에 기록하지 않는다.
+- field baseline 포트(`18080`, `18081`, `19090`, `19092`)를 dev 전용 포트로 재사용하지 않는다.
--- a/agent-test/dev/node-smoke.md
+++ b/agent-test/dev/node-smoke.md
@ -0,0 +1,100 @@
+---
+test_env: dev
+test_profile: node-smoke
+domain: node
+verification_type: smoke
+last_rule_updated_at: 2026-06-12
+---
+
+# node-smoke dev 테스트
+
+## 읽기 조건
+
+- `apps/node/**` 변경 또는 node 실행, adapter, transport, router, store dev 검증 판단이 필요한 경우
+
+## 적용 범위
+
+- `apps/node/cmd/node/**`
+- `apps/node/internal/bootstrap/**`
+- `apps/node/internal/node/**`
+- `apps/node/internal/runtime/**`
+- `apps/node/internal/router/**`
+- `apps/node/internal/transport/**`
+- `apps/node/internal/adapters/**`
+- `apps/node/internal/store/**`
+
+## 분류
+
+- domain: node
+- verification_type: smoke
+- scope: node 실행 파이프라인과 edge 연결 baseline
+
+## 환경
+
+- host: local checkout. dev host, external CLI profile, shared Edge runtime evidence가 필요하면 원격 runner를 사용한다.
+- port: dev Edge-Node TCP transport `19003`
+- runtime: Go `1.24`
+- package manager: Go modules / Makefile
+- docker: unit/smoke quick check는 Docker를 요구하지 않는다. compose dev 검증은 `docker compose --env-file .env.dev.example ...`로 수행한다.
+- external service: dev Edge runtime 주소 후보 `toki-labs.com:19003`
+- model endpoint: dev OpenAI-compatible base URL 후보 `http://toki-labs.com:18083/v1`
+- credential: token/secret 원문은 문서에 기록하지 않는다.
+
+## 명령
+
+- setup:
+- lint:
+- unit: `go test ./apps/node/...`
+- smoke: `./scripts/e2e-smoke.sh`는 기본 포트 임시 설정을 쓰는 보조 smoke이므로 dev 포트 override 필요 여부를 먼저 확인한다.
+- e2e: `make test-e2e`
+- model:
+- full-cycle: repo 내부 edge-node 진단과 사용자 실행 cycle 수동 검증
+
+## 필수 검증
+
+- 변경한 node 패키지 또는 `go test ./apps/node/...`를 실행한다.
+- 실행 요청, stream, cancel, status, session, adapter registry 경로를 바꾼 경우 repo 내부 edge-node 진단과 full-cycle 실제 구동 기준을 함께 적용한다.
+- CLI profile 변경 시 `/capabilities`, `/transport`, `/sessions`, persistent profile이면 `/terminate-session`을 확인한다.
+- dev Edge runtime으로 연결하는 경우 Node가 `19003`을 사용하고 local/test `19090` field baseline으로 붙지 않는지 확인한다.
+
+## 보조 검증
+
+- `./scripts/e2e-smoke.sh`는 mock adapter 기반 보조 smoke로 사용한다.
+- `make test-e2e`는 보조 smoke이며 full-cycle 실제 구동을 대체하지 않는다.
+
+## 판정 기준
+
+- node 등록 후 edge console에서 node가 조회된다.
+- 같은 session에서 메시지 2회가 start, 기대 payload를 포함한 `[node-*-message]`, 같은 run의 complete 순서로 edge 화면에 도착한다.
+- node 로컬 `[node-message]` payload 라인 목록과 edge `[node-*-message]` payload 라인 목록이 run별로 내용/순서까지 동일해야 한다.
+- edge complete는 같은 run의 마지막 `[node-*-message]` 이후에만 정상이다.
+- command 결과가 `[node-*-<command>]` 또는 명확한 성공/unsupported/error 출력으로 edge 화면에 표시된다.
+
+## 기준 출력 예시
+
+```text
+edge> /nodes
+edge> Convert token iop_manual_one and reply only with converted token
+[node-*-event] start
+[node-*-message] IOP_MANUAL_ONE_OK
+[node-*-event] complete
+```
+
+## 차단 기준
+
+- dev host 또는 Edge-Node TCP port 접근이 불가능하다.
+- 외부 CLI profile 검증에 필요한 CLI 설치, 계정, provider 상태가 없다.
+
+## 보고 항목
+
+- 실행한 명령:
+- 성공한 검증:
+- 실패/차단된 검증:
+- 생략 사유:
+- 남은 위험:
+
+## 금지 사항
+
+- 사용자 실행 파이프라인 변경을 unit test만으로 완료 처리하지 않는다.
+- `proto/gen/iop/*.pb.go` 생성 파일을 직접 수정하지 않는다.
+- secret, token, 개인 endpoint 원문은 tracked 파일에 기록하지 않는다.
--- a/agent-test/dev/platform-common-smoke.md
+++ b/agent-test/dev/platform-common-smoke.md
@ -0,0 +1,92 @@
+---
+test_env: dev
+test_profile: platform-common-smoke
+domain: platform-common
+verification_type: smoke
+last_rule_updated_at: 2026-06-12
+---
+
+# platform-common-smoke dev 테스트
+
+## 읽기 조건
+
+- `packages/go/**`, `proto/**`, `configs/**` 변경 또는 공통 설정, protobuf 계약, host setup dev 검증 판단이 필요한 경우
+
+## 적용 범위
+
+- `packages/go/**`
+- `proto/iop/**`
+- `proto/gen/iop/**`
+- `configs/**`
+- dev env/compose/config 계약
+
+## 분류
+
+- domain: platform-common
+- verification_type: smoke
+- scope: 공통 패키지, 설정, protobuf 계약 baseline
+
+## 환경
+
+- host: local checkout. dev field/runtime evidence가 필요한 경우에만 원격 runner를 사용한다.
+- port: dev Edge-Node TCP transport `19003`, dev Edge OpenAI-compatible HTTP 후보 `18083`, dev Portal/Control Plane wire test endpoint `19001`, dev artifact/bootstrap 후보 `18082`.
+- runtime: Go `1.24`
+- package manager: Go modules / Makefile
+- docker: unit/codegen quick check는 Docker를 요구하지 않는다. compose dev 검증은 `docker compose --env-file .env.dev.example ...`로 수행한다.
+- external service: dev artifact/base URL 후보 `http://toki-labs.com:18082`
+- model endpoint: dev OpenAI-compatible base URL 후보 `http://toki-labs.com:18083/v1`
+- credential: token/secret 원문은 문서에 기록하지 않는다.
+
+## 명령
+
+- setup:
+- lint:
+- unit: `go test ./packages/go/... ./proto/gen/...`
+- smoke: `go test ./...`
+- e2e: `make test-e2e`
+- model:
+- full-cycle: 설정/proto 변경이 사용자 실행 파이프라인에 닿으면 edge-node 실제 구동 검증
+
+## 필수 검증
+
+- 공통 패키지 변경 시 변경 패키지 테스트 또는 `go test ./packages/go/... ./proto/gen/...`를 실행한다.
+- protobuf 원본 변경 시 `make proto`로 Go 생성물을 갱신하고 생성물 diff를 확인한다.
+- config 계약 변경 시 `packages/go/config` struct/default와 `configs/*.yaml` 예시가 일치하는지 확인한다.
+- dev env/compose 계약 변경 시 `.env.dev.example`, `docker-compose.yml`, `agent-test/dev/rules.md`의 포트가 서로 일치하는지 확인한다.
+
+## 보조 검증
+
+- `go test ./...`는 저장소 전체 회귀 확인으로 사용한다.
+- 실행 경로에 닿는 config/proto 변경은 `make test-e2e`를 보조 확인으로 사용할 수 있다.
+
+## 판정 기준
+
+- 공통 패키지는 앱 내부 패키지를 import하지 않는다.
+- proto 생성물은 원본 proto와 `make proto` 결과로만 갱신된다.
+- 설정 예시는 loader/default와 어긋나지 않는다.
+- dev 포트는 local/test 포트를 덮어쓰지 않고 dev profile에서만 사용된다.
+
+## 기준 출력 예시
+
+```text
+go test ./packages/go/... ./proto/gen/...
+```
+
+## 차단 기준
+
+- `protoc` 또는 `protoc-gen-go`가 없어서 proto 생성 검증을 실행할 수 없다.
+- config 변경이 실제 환경값이나 credential 없이는 판정 불가능하다.
+
+## 보고 항목
+
+- 실행한 명령:
+- 성공한 검증:
+- 실패/차단된 검증:
+- 생략 사유:
+- 남은 위험:
+
+## 금지 사항
+
+- `proto/gen/iop/*.pb.go` 생성 파일을 직접 수정하지 않는다.
+- 앱 하나만을 위한 임시 타입을 충분한 근거 없이 공통 패키지로 승격하지 않는다.
+- secret, token, 개인 endpoint 원문은 tracked 파일에 기록하지 않는다.
--- a/agent-test/dev/rules.md
+++ b/agent-test/dev/rules.md
@ -0,0 +1,67 @@
+---
+test_env: dev
+last_rule_updated_at: 2026-06-12
+---
+
+# dev 테스트 규칙
+
+**현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.**
+**dev 테스트 환경은 local 테스트 조건을 그대로 따르되, 같은 원격 host에서 local/test stack과 공존하도록 host publish 포트와 compose project/network를 분리한다.**
+
+## 공통 규칙
+
+- dev 테스트/검증은 이 파일을 기준으로 판단한다.
+- 작업 완료 검증은 변경 범위 기준으로 선택한다.
+- 필수 검증을 실행하지 못하면 차단 사유로 보고한다.
+- 최종 보고에는 실행 명령, 결과, 생략 사유, 남은 위험을 남긴다.
+- 환경값, secret, 개인 endpoint는 tracked docs/roadmap에 쓰지 않는다.
+- token/secret 원문은 원격 환경에서 주입하고, shell stdout/stderr와 최종 보고에 출력하지 않는다.
+- 테스트용 Docker 환경을 작성/수정할 때는 Docker Compose `networks`, IPAM subnet, static IPv4, `extra_hosts`, host publish 문서 어디에도 `192.168.0.0/24` (`192.168.0.X`) 대역을 사용하지 않는다.
+- 새 Docker 테스트 subnet이 필요하면 기존 프로젝트 포트/네트워크 표준을 먼저 따르고, 불가피한 경우 host LAN/VPN과 충돌하지 않는 `192.168.0.0/24` 밖의 private subnet만 사용한다.
+
+## 기본 환경
+
+- host: dev runtime evidence는 원격 runner `ssh toki@toki-labs.com`의 `/Users/toki/agent-work/iop-dev` 기준으로 수행한다.
+- repo root: 명령은 원격 checkout `/Users/toki/agent-work/iop-dev` 기준으로 실행한다.
+- sync 기준: 원격 runner를 사용하는 경우 local uncommitted 변경은 원격 repo에 자동 반영되지 않는다. 동기화되지 않았으면 현재 변경분 검증으로 보지 않는다.
+- env file: dev stack은 `docker compose --env-file .env.dev.example ...`로 명시한다.
+- compose identity: `COMPOSE_PROJECT_NAME=iop-dev-agent`, `IOP_COMPOSE_NETWORK=iop-dev-agent-net`.
+- port: web/dev preview `13001`, Control Plane HTTP `18001`, Portal/Control Plane wire test endpoint `19001`, CP-Edge wire `19002`, Edge-Node TCP transport `19003`, Postgres host publish `15401`, Redis host publish `16301`.
+- optional dev field ports: artifact/bootstrap HTTP `18082`, Edge OpenAI-compatible HTTP `18083`, Edge metrics `19101`. 이 값은 compose 기본 stack에 publish되지 않으며 field/bootstrap 또는 Edge direct dev profile이 필요할 때만 사용한다.
+- runtime: Go quick check는 local toolchain을 우선한다. Flutter client 포함 검증과 Docker/code-server/full-cycle runtime은 원격 runner를 사용한다.
+- package manager: Go modules / Makefile / Flutter pub
+- docker: 현재 작업 컨테이너에서는 Docker-in-Docker를 사용하지 않는다. Docker compose 검증은 원격 runner 또는 code-server 환경에서 수행한다.
+- external service: dev compose Control Plane HTTP `http://toki-labs.com:18001`, dev Client wire `ws://toki-labs.com:19001/client`.
+- model endpoint: dev Edge OpenAI-compatible profile을 별도로 띄우는 경우 `http://toki-labs.com:18083/v1`.
+- credential: token/secret 원문은 문서에 기록하지 않는다.
+
+## 포트 매핑
+
+| 용도 | local/test | dev |
+|---|---:|---:|
+| Web preview | `13000` | `13001` |
+| Control Plane HTTP | `18000` | `18001` |
+| CP Client WS | `19080` | `19001` |
+| CP-Edge wire | `19081` | `19002` |
+| Edge-Node TCP | `19090` | `19003` |
+| Edge artifact/bootstrap | `18080` | `18082` |
+| Edge OpenAI-compatible | `18081` | `18083` |
+| Edge metrics | `19092` | `19101` |
+| PostgreSQL host publish | `15400` | `15401` |
+| Redis host publish | `16300` | `16301` |
+
+## 라우팅
+
+- node / smoke / node 실행 파이프라인 baseline: `agent-test/dev/node-smoke.md`
+- edge / smoke / edge 실행 그룹과 입력 표면 baseline: `agent-test/dev/edge-smoke.md`
+- control-plane / smoke / control-plane health와 wire baseline: `agent-test/dev/control-plane-smoke.md`
+- client / smoke / Flutter client와 IOP console package baseline: `agent-test/dev/client-smoke.md`
+- platform-common / smoke / 공통 설정과 protobuf 계약 baseline: `agent-test/dev/platform-common-smoke.md`
+- testing / smoke / 테스트 도구와 full-cycle 검증 baseline: `agent-test/dev/testing-smoke.md`
+
+## 라우팅 규칙
+
+- 여러 항목이 맞으면 모두 읽는다.
+- 도메인 매핑이나 domain rule이 있으면 각 도메인의 `<domain>-smoke` 문서를 기본 baseline으로 둔다.
+- 도메인이 아직 없을 때만 project-smoke를 fallback baseline으로 둔다.
+- 도메인/검증 시나리오별 문서는 다른 테스트 문서로 라우팅하지 않는다.
--- a/agent-test/dev/testing-smoke.md
+++ b/agent-test/dev/testing-smoke.md
@ -0,0 +1,105 @@
+---
+test_env: dev
+test_profile: testing-smoke
+domain: testing
+verification_type: smoke
+last_rule_updated_at: 2026-06-12
+---
+
+# testing-smoke dev 테스트
+
+## 읽기 조건
+
+- `Makefile`, `scripts/dev/**`, `scripts/e2e-*.sh`, bootstrap pack, 테스트/검증 절차, dev compose/profile 변경 판단이 필요한 경우
+
+## 적용 범위
+
+- `Makefile`
+- `scripts/dev/edge.sh`
+- `scripts/dev/node.sh`
+- `scripts/e2e-smoke.sh`
+- `scripts/e2e-openai-ollama.sh`
+- `iop-edge bootstrap pack`
+- `docker-compose.yml`
+- `.env.dev.example`
+- `agent-test/dev/**`
+
+## 분류
+
+- domain: testing
+- verification_type: smoke
+- scope: 테스트 도구, 보조 smoke, full-cycle 실제 구동 기준
+
+## 환경
+
+- host: local checkout. Flutter client 포함 검증, Docker compose, field/bootstrap, artifact server, external CLI profile evidence가 필요하면 원격 runner를 사용한다.
+- port: web/dev preview `13001`, artifact/bootstrap HTTP 후보 `18082`, Edge OpenAI-compatible HTTP 후보 `18083`, Portal/Control Plane wire test endpoint `19001`, CP-Edge wire `19002`, Edge-Node TCP transport `19003`, Edge metrics 후보 `19101`.
+- runtime: Go `1.24`
+- package manager: Go modules / Makefile
+- docker: quick check는 Docker를 요구하지 않는다. 현재 작업 컨테이너에서는 Docker-in-Docker를 사용하지 않으며, Docker compose 검증은 원격 runner 또는 code-server 환경에서 수행한다.
+- external service: dev Control Plane HTTP `http://toki-labs.com:18001`, dev Client wire `ws://toki-labs.com:19001/client`, dev Edge runtime 후보 `toki-labs.com:19003`
+- model endpoint: dev OpenAI-compatible base URL 후보 `http://toki-labs.com:18083/v1`
+- credential: token/secret 원문은 문서에 기록하지 않는다.
+
+## 명령
+
+- setup:
+- lint:
+- unit: `make test`
+- smoke: `./scripts/e2e-smoke.sh`
+- compose-smoke: `IOP_EDGE_NODE_TOKEN=<token> docker compose --env-file .env.dev.example up -d postgres redis control-plane edge web`
+- compose-health: `curl -fsS http://127.0.0.1:18001/healthz`
+- e2e: `make test-e2e`
+- model: `./scripts/e2e-openai-ollama.sh`
+- full-cycle: `make pack-node-target`, repo 내부 edge-node 진단, field bootstrap UX, 실제 외부 CLI profile 검증
+
+## 필수 검증
+
+- 테스트 도구 자체를 바꾼 경우 해당 도구를 직접 실행해 성공/실패 판정을 확인한다.
+- 사용자 실행 파이프라인에 닿는 변경은 일반 Go 테스트와 변경 범위에 맞는 full-cycle 실제 구동을 함께 검증한다.
+- dev compose/profile 변경 시 `docker compose --env-file .env.dev.example config`로 렌더링된 host publish 포트와 network name을 확인한다.
+- `iop-edge bootstrap pack`, `make pack-edge`, 내장 artifact server 변경 시 현재 host target build와 artifact/checksum/bootstrap script를 확인한다.
+- field/bootstrap/deploy 작업은 one-line bootstrap UX 기준을 적용한다.
+- 사용자에게 전달하는 Node bootstrap 명령은 완성된 URL과 token positional value 하나만 포함한다.
+
+## 보조 검증
+
+- `make test-e2e`, `./scripts/e2e-smoke.sh`, `./scripts/e2e-openai-ollama.sh`는 보조 smoke다.
+- 보조 smoke는 full-cycle 실제 구동이나 field bootstrap 검증을 대체하지 않는다.
+
+## 판정 기준
+
+- dev compose는 `COMPOSE_PROJECT_NAME=iop-dev-agent`와 `IOP_COMPOSE_NETWORK=iop-dev-agent-net`을 사용한다.
+- dev compose가 local/test 포트 `13000`, `18000`, `19080`, `19081`, `15400`, `16300`을 점유하지 않는다.
+- edge console에서 메시지 2회가 각각 기대 payload를 포함한 `[node-*-message]`로 표시되고, command 결과가 edge 화면에 도착한다.
+- node 로컬 `[node-message]` payload 라인 목록과 edge `[node-*-message]` payload 라인 목록이 run별로 내용/순서까지 동일해야 한다.
+- Node bootstrap UX는 `curl -fsSL <완성된-bootstrap-url> | bash -s <token>` 형태를 유지한다.
+
+## 기준 출력 예시
+
+```text
+docker compose --env-file .env.dev.example config
+curl -fsS http://127.0.0.1:18001/healthz
+```
+
+## 차단 기준
+
+- dev host 접근, 지정 port, 외부 CLI 설치/계정/provider 상태가 없어 필수 검증을 수행할 수 없다.
+- 사용자가 명시하지 않았는데 code-server 컨테이너 재시작이 필요한 상황이다.
+- dev 포트가 이미 사용 중이라 local/test stack과 공존할 수 없다.
+
+## 보고 항목
+
+- 실행한 명령:
+- 성공한 검증:
+- 실패/차단된 검증:
+- 생략 사유:
+- 남은 위험:
+
+## 금지 사항
+
+- 보조 E2E smoke 통과만으로 완료 처리하지 않는다.
+- 사용자 기본 경로에서 `IOP_ARTIFACT_BASE_URL=...`, `IOP_EDGE_ADDR=...`, `IOP_NODE_TOKEN=...` 같은 named environment parameter를 요구하지 않는다.
+- 사용자가 명시하지 않으면 code-server 컨테이너를 재시작하지 않는다.
+- 환경값을 사람용 docs나 roadmap에 복사하지 않는다.
+- secret, token, 개인 endpoint 원문은 tracked 파일에 기록하지 않는다.
--- a/docker-compose.yml
+++ b/docker-compose.yml
@ -95,7 +95,7 @@ volumes:

 networks:
  default:
-    name: iop-dev-net
+    name: ${IOP_COMPOSE_NETWORK:-iop-dev-net}
    ipam:
      config:
        - subnet: 10.89.0.0/24