iop/agent-test/_templates/env-rules-template.md

test_env	last_rule_updated_at
<env>	<YYYY-MM-DD>

테스트 규칙

현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다. 테스트 환경의 핵심 실행 모드와 local/dev/qa 등 다른 환경과의 공존 기준을 이 문서에 둔다.

공통 규칙

• 테스트/검증은 이 파일을 기준으로 판단한다.
• 작업 완료 검증은 변경 범위 기준으로 선택한다.
• 필수 검증을 실행하지 못하면 차단 사유로 보고한다.
• 최종 보고에는 실행 명령, 결과, 생략 사유, 남은 위험을 남긴다.
• 환경값, secret, 개인 endpoint는 tracked docs/roadmap에 쓰지 않는다.
• token/secret 원문은 원격 환경에서 주입하고, shell stdout/stderr와 최종 보고에 출력하지 않는다.
• 테스트용 Docker 환경을 작성/수정할 때는 Docker Compose networks, IPAM subnet, static IPv4, extra_hosts, host publish 문서 어디에도 host LAN/VPN과 충돌하는 대역을 사용하지 않는다.

기본 환경

• host: <기본 실행 host 또는 runner SSH>
• repo root: <원격/로컬 repo root>
• sync 기준: <source sync 판단 기준>
• env file: <compose/env file 기준 또는 해당 없음>
• compose identity: <COMPOSE_PROJECT_NAME / network 또는 해당 없음>
• port: <핵심 포트 요약>
• optional field ports: <선택 포트 또는 해당 없음>
• runtime: <Go/Flutter/Docker/외부 runtime>
• package manager: <Go modules / Makefile / Flutter pub 등>
• docker: <Docker 사용 기준>
• external service: <외부 서비스 URL/host 요약>
• model endpoint: <OpenAI-compatible 등 모델 endpoint>
• credential: secret/token/API key 원문은 문서에 기록하지 않는다.

포트 매핑

용도	local/test	dev
Web preview	13000-13099	13001	<port 또는 해당 없음>
Control Plane HTTP	18000	18001	<port 또는 해당 없음>
CP Client WS	19080	19001	<port 또는 해당 없음>
CP-Edge wire	19081	19002	<port 또는 해당 없음>
Edge-Node TCP	19090	19003	<port 또는 해당 없음>
Edge artifact/bootstrap	18080	18082	<port 또는 해당 없음>
Edge OpenAI-compatible	18081	18083	<port 또는 해당 없음>
Edge metrics	19092	19101	<port 또는 해당 없음>
Control Plane metrics	19100	19103	<port 또는 해당 없음>
Prometheus UI/API	19110	19111	<port 또는 해당 없음>
Grafana UI	19120	19121	<port 또는 해당 없음>
PostgreSQL host publish	15400	15401	<port 또는 해당 없음>
Redis host publish	16300	16301	<port 또는 해당 없음>

<환경 안에서 compose/native/dev-runtime처럼 Edge-Node TCP가 갈라지면 여기에 명시한다.>

런타임 프로필

• local quick check: 현재 checkout에서 가능한 quick check를 우선 실행한다.
• remote runner: <SSH, repo root, 어떤 evidence에 쓰는지>
• compose stack: <compose file/env file/project/network/주요 포트>
• native/direct Edge profile: <필요 시 artifact/openai/metrics/edge-node 포트>
• provider pool profile: <필요 시 config path, model alias, Edge-Node TCP>
• external provider field: <필요 시 SSH/user/IP/provider endpoint>

프리플라이트

• 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, 잘못된 identity, missing command, closed port, host OS 불일치, source 미동기화가 확인되면 plan은 먼저 setup/sync/rebuild 단계를 만들거나 blocker로 보고한다. remote deploy 환경에서 dirty 변경을 보존하지 않는 정책이면 배포 전 clean sync와 rebuild를 기본 단계로 둔다. profile 값을 이미 참이라고 가정한 검증 명령만 쓰지 않는다.

노드/Provider 인벤토리 위치

• machine-readable 인벤토리 기준: agent-test/<env>/inventory.yaml 또는 해당 없음
• Edge/OpenAI-compatible 입력 표면 상세 기준: agent-test/<env>/edge-smoke.md
• Node 접속과 bootstrap 상세 기준: agent-test/<env>/node-smoke.md
• 공통 provider config 계약 기준: agent-test/<env>/platform-common-smoke.md
• compose stack 기준: agent-test/<env>/control-plane-smoke.md, agent-test/<env>/client-smoke.md, agent-test/<env>/testing-smoke.md

Field/bootstrap 반복 테스트 기준

• field/bootstrap 검증은 이 환경의 runner, checkout, artifact 기준으로 수행한다. 세부 Edge/Node profile은 해당 env의 edge-smoke.md와 node-smoke.md를 따른다.
• compose stack과 native/provider-pool profile이 서로 다른 Edge-Node TCP를 쓰면 두 프로필을 섞어서 판정하지 않는다.
• 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을 기본으로 사용한다.
• provider capacity, model/provider mapping의 live apply는 해당 Edge binary가 config refresh를 제공하는 경우에만 사용한다. refresh 지원이 필요한 환경에서 subcommand나 admin port가 없으면 stale binary로 보고 clean sync/rebuild를 먼저 수행한다.
• Edge process restart 또는 일시 단절 후에는 Node reconnect 정책을 검증한다. retry 한계를 넘겨 Node process가 종료된 경우에만 해당 Node host에서 새 bootstrap 실행이 필요하다.

라우팅

• node / smoke / node 실행 파이프라인 baseline: agent-test/<env>/node-smoke.md
• edge / smoke / edge 실행 그룹과 입력 표면 baseline: agent-test/<env>/edge-smoke.md
• control-plane / smoke / control-plane health와 wire baseline: agent-test/<env>/control-plane-smoke.md
• client / smoke / Flutter client와 IOP console package baseline: agent-test/<env>/client-smoke.md
• platform-common / smoke / 공통 설정과 protobuf 계약 baseline: agent-test/<env>/platform-common-smoke.md
• testing / smoke / 테스트 도구와 full-cycle 검증 baseline: agent-test/<env>/testing-smoke.md

라우팅 규칙

• 여러 항목이 맞으면 모두 읽는다.
• 도메인 매핑이나 domain rule이 있으면 각 도메인의 <domain>-smoke 문서를 기본 baseline으로 둔다.
• 도메인이 아직 없을 때만 project-smoke를 fallback baseline으로 둔다.
• 도메인/검증 시나리오별 문서는 다른 테스트 문서로 라우팅하지 않는다.