iop/agent-test/dev/rules.md

test_env	last_rule_updated_at
dev	2026-06-24

dev 테스트 규칙

현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다. dev 테스트 환경은 local 테스트 조건을 그대로 따르되, 같은 원격 host에서 local/test stack과 공존하도록 host publish 포트와 compose project/network를 분리한다.

공통 규칙

• dev 테스트/검증은 이 파일을 기준으로 판단한다.
• 작업 완료 검증은 변경 범위 기준으로 선택한다.
• 필수 검증을 실행하지 못하면 차단 사유로 보고한다.
• 새 테스트 환경을 추가하거나 환경 구조를 바꿀 때는 agent-test/README.md와 agent-test/_templates/의 확장 기준을 따른다.
• 최종 보고에는 실행 명령, 결과, 생략 사유, 남은 위험을 남긴다.
• 환경값, 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 기준: dev 배포 전 원격 runner checkout은 git fetch origin main, git reset --hard origin/main, git clean -fd로 clean 상태를 만든 뒤 빌드한다. dev runner의 dirty 변경은 보존 대상으로 보지 않는다.
• 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

dev-runtime provider pool은 compose Edge-Node TCP 19003이 아니라 native Edge listen 18084를 사용한다. 세부 기준은 agent-test/dev/edge-smoke.md와 agent-test/dev/node-smoke.md를 따른다.

런타임 프로필

• local quick check: 현재 checkout에서 Go quick check를 우선 실행한다.
• remote runner: dev runtime evidence, Flutter client, Docker compose, field/bootstrap, 외부 runtime evidence는 ssh toki@toki-labs.com의 /Users/toki/agent-work/iop-dev 기준으로 수행한다.
• compose dev stack: .env.dev.example, COMPOSE_PROJECT_NAME=iop-dev-agent, IOP_COMPOSE_NETWORK=iop-dev-agent-net, Edge-Node TCP 19003을 사용한다.
• Edge direct dev profile: artifact/bootstrap 18082, OpenAI-compatible 18083, metrics 19101을 필요할 때만 사용한다.
• dev-runtime provider pool: /Users/toki/agent-work/iop-dev/build/dev-runtime/edge.yaml과 Edge-Node TCP toki-labs.com:18084를 사용한다. 3-node/provider 세부는 agent-test/dev/edge-smoke.md와 agent-test/dev/node-smoke.md를 따른다.
• external provider field: GX10 vLLM은 ssh toki@192.168.0.91, OneXPlayer Lemonade는 현재 작업 호스트에서 ssh r0bin@192.168.0.59로 직접 접속해 확인한다. OneXPlayer 접속은 원격 runner 경유를 필수 조건으로 보지 않는다.

프리플라이트

• plan 작성 시 필수 검증이 현재 checkout을 벗어나 원격 runner, field/bootstrap, 외부 provider, Docker/code-server, emulator/device, 공유 장기 runtime을 사용하면 먼저 테스트 환경 프리플라이트를 계획에 기록한다.
• 테스트 환경 프리플라이트에는 runner, repo root/workdir, branch/HEAD/dirty 상태, local 변경과 원격 source 동기화 여부, binary/artifact 경로와 필요한 help/version 출력, config path, runtime identity, port/process 상태, 외부 host, OS/arch 가정을 포함한다.
• 프리플라이트에서 dirty/divergent checkout 또는 stale artifact가 확인되면 dev 배포에서는 먼저 원격 checkout을 clean sync하고 dev-runtime 바이너리를 rebuild한다. 잘못된 identity, missing command, closed port, host OS 불일치, source 미동기화가 확인되면 plan은 setup/sync/rebuild 단계를 만들거나 blocker로 보고한다. profile 값을 이미 참이라고 가정한 검증 명령만 쓰지 않는다.

노드/Provider 인벤토리 위치

• dev-runtime provider pool machine-readable 기준: agent-test/dev/inventory.yaml
• dev-runtime provider pool과 Edge/OpenAI-compatible 입력 표면 상세 기준: agent-test/dev/edge-smoke.md
• dev-runtime Node 접속과 bootstrap 상세 기준: agent-test/dev/node-smoke.md
• 공통 provider config 계약 기준: agent-test/dev/platform-common-smoke.md
• compose dev stack 기준: agent-test/dev/control-plane-smoke.md, agent-test/dev/client-smoke.md, agent-test/dev/testing-smoke.md

Field/bootstrap 반복 테스트 기준

• field/bootstrap 검증은 원격 runner의 /Users/toki/agent-work/iop-dev checkout과 dev-runtime artifact를 기준으로 수행한다. 세부 Edge/Node profile은 agent-test/dev/edge-smoke.md와 agent-test/dev/node-smoke.md를 따른다.
• compose dev stack은 Edge-Node TCP 19003을 사용하고, dev-runtime provider pool은 native Edge listen 18084를 사용한다. 두 프로필을 섞어서 판정하지 않는다.
• Node bootstrap은 Edge의 node register가 출력한 OS별 완성 명령을 그대로 사용한다. 사용자에게 안내하는 명령에는 임의 placeholder, 수동 token 치환, IOP_*= named environment parameter를 넣지 않는다.
• token, API key, private credential 원문은 tracked docs, roadmap, 테스트 규칙에 기록하지 않는다. 실행 증거에는 token을 마스킹하거나 명령 생성 사실만 남긴다.
• Linux/macOS Node는 생성된 curl | bash 계열 명령을 사용한다. Windows Node는 native PowerShell bootstrap을 기본으로 사용한다.
• dev-runtime 배포는 clean sync 후 build/dev-runtime/bin/edge, mac node, Linux/Windows node binary를 같은 source 기준으로 rebuild한다. 배포 후 edge config refresh --help, 19093 port, config refresh --mode dry-run을 확인한다.
• provider capacity, model/provider mapping은 config check와 config refresh --mode dry-run을 통과한 뒤 config refresh --mode apply로 반영한다. refresh subcommand 또는 19093 admin port가 없으면 바이너리 rebuild 누락으로 보고 먼저 rebuild한다.
• Edge process restart 또는 일시 단절 후에는 Node reconnect 정책을 검증한다. retry 한계를 넘겨 Node process가 종료된 경우에만 해당 Node host에서 새 bootstrap 실행이 필요하다.

라우팅

• node / smoke / node 실행 파이프라인 baseline: agent-test/dev/node-smoke.md
• edge / smoke / edge 실행 그룹과 입력 표면 baseline: agent-test/dev/edge-smoke.md
• dev-runtime provider pool, 3-node 연결, GX10 vLLM, OneXPlayer Lemonade, mac CLI node 점검: agent-test/dev/edge-smoke.md, agent-test/dev/node-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으로 둔다.
• 도메인/검증 시나리오별 문서는 다른 테스트 문서로 라우팅하지 않는다.