add agent-test

2026-07-18 23:55:20 +09:00 · 2026-07-18 23:55:20 +09:00 · d67b128344
commit d67b128344
parent 99fede0812
7 changed files with 630 additions and 0 deletions
--- a/agent-test/README.md
+++ b/agent-test/README.md
@ -0,0 +1,35 @@
+# agent-test 환경 기준
+
+이 디렉터리는 RARA의 환경별 실행 기준과 도메인별 smoke profile을 둔다.
+
+## 기본 환경
+
+- 사용자가 환경을 별도로 지정하지 않으면 기본 테스트 환경은 원격 `dev`다.
+- `dev`의 기준 runner는 `ssh toki@toki-labs.com`이며, 목표 checkout은
+  `/Users/toki/agent-work/rara-dev`다.
+- `local`은 현재 checkout에서 빠르게 수행하는 source 단위 검증이나 사용자가
+  명시적으로 local을 요청한 경우에만 사용한다.
+- 원격 checkout이 없거나 현재 변경과 동기화되지 않았으면 local 결과로 원격
+  evidence를 대신하지 않고 setup/sync 차단 사유를 보고한다.
+
+## 환경 구조
+
+- 환경 공통값과 프리플라이트는 `agent-test/<env>/rules.md`에 둔다.
+- 반복해서 읽어야 하는 runner, checkout, port 상태는
+  `agent-test/<env>/inventory.yaml`에 둔다.
+- 도메인별 검증 기준은 `agent-test/<env>/<domain>-smoke.md`에 둔다.
+- secret, token, password, private key, 개인 endpoint 원문은 기록하지 않는다.
+
+## 현재 환경
+
+- `dev`: 원격 Mac runner를 사용하는 기본 테스트 환경
+- `local`: 현재 host의 빠른 source/build 검증 환경
+
+## 포트 선택 기준
+
+- workspace root의 포트 원장 `.workspace-ops/docs/ports.md`에서 project-owned
+  슬롯과 shared IOP field 포트를 먼저 확인한다.
+- RARA `dev`는 2026-07-18 충돌 점검 당시 미배정이던 `70` 슬롯을 전용으로
+  배정해 사용한다.
+- 실행 직전에는 원격 runner의 실제 listen 상태를 다시 확인한다. 문서에 기록된
+  점검 결과는 영구적인 port lock으로 간주하지 않는다.
--- a/agent-test/dev/control-plane-smoke.md
+++ b/agent-test/dev/control-plane-smoke.md
@ -0,0 +1,92 @@
+---
+test_env: dev
+test_profile: control-plane-smoke
+domain: control-plane
+verification_type: smoke
+last_rule_updated_at: 2026-07-18
+---
+
+# control-plane-smoke dev 테스트
+
+## 읽기 조건
+
+- control-plane 코드, 제어 상태 스키마·쿼리, 실행 진입점을 원격 환경에서 검증할 때
+
+## 적용 범위
+
+- `apps/control-plane/`, `packages/go/controlplane/`, `db/migrations/`, `db/queries/`
+
+## 분류
+
+- domain: control-plane
+- verification_type: smoke
+- scope: 원격 runner의 수명주기 API, 제어 상태, PostgreSQL readiness 검증
+
+## 환경
+
+- host: `ssh toki@toki-labs.com`
+- repo root: `/Users/toki/agent-work/rara-dev`
+- port: Control Plane `127.0.0.1:18070`, PostgreSQL host publish 후보 `127.0.0.1:15470`
+- runtime: Go 1.26
+- package manager: Go modules
+- docker: login shell의 Docker Desktop/Engine 27.4.0, 실행 전 daemon 재확인
+- external service: readiness와 상태 API 검증에는 PostgreSQL 필요
+- model endpoint: 해당 없음
+- credential: database credential 원문은 문서와 출력에 남기지 않는다.
+
+## 명령
+
+- setup: `make setup`
+- lint: 변경한 Go 파일의 `gofmt` 상태와 diff 확인
+- unit: `go test ./packages/go/controlplane/... ./packages/go/database/...`
+- smoke: `go build -o /tmp/rara-control-plane ./apps/control-plane/cmd/control-plane`
+- service: PostgreSQL 준비 후 `RARA_LISTEN=127.0.0.1:18070`과 주입된
+  `RARA_DATABASE_URL`로 binary를 실행하고 `/healthz`, `/readyz`, `/v1/status` 확인
+- e2e: 현재 baseline 없음
+- model: 해당 없음
+- full-cycle: `make test && make build`
+
+## 필수 검증
+
+- 원격 checkout의 HEAD가 검증 대상 source와 일치한다.
+- control-plane과 database package 테스트가 통과한다.
+- control-plane binary가 원격 runner에서 빌드된다.
+- DB 원본 변경 시 `make sqlc` 후 생성물 diff와 CI의 sqlc diff 기준을 확인한다.
+- PostgreSQL이 준비된 경우 `18070`에서 health, readiness, status 응답을 확인한다.
+
+## 보조 검증
+
+- `lsof -nP -iTCP:18070 -sTCP:LISTEN`으로 시작 전 충돌과 종료 후 반환을 확인한다.
+- PostgreSQL host publish가 필요하면 `15470` 점유 여부를 별도로 확인한다.
+
+## 판정 기준
+
+- source identity가 일치하고 테스트·빌드가 exit code 0으로 종료한다.
+- service smoke를 수행한 경우 health와 readiness가 성공하고 `/v1/status`가 응답한다.
+- PostgreSQL 미준비 시 source test/build 통과와 service smoke 차단을 구분해 보고한다.
+
+## 기준 출력 예시
+
+```text
+ok   git.toki-labs.com/toki/rara/packages/go/...
+```
+
+## 차단 기준
+
+- 원격 checkout 부재·source 불일치, Go 1.26 부재, `18070` 점유
+- service smoke에 필요한 PostgreSQL 또는 안전한 database credential 주입 부재
+
+## 보고 항목
+
+- 원격 branch/HEAD:
+- 실행한 명령:
+- 성공한 검증:
+- 실패/차단된 검증:
+- 생략 사유:
+- 남은 위험:
+
+## 금지 사항
+
+- local test 결과를 원격 service evidence로 보고하지 않는다.
+- 운영 secret이나 개인 database URL을 문서와 로그에 남기지 않는다.
+- 생성된 sqlc 파일을 직접 고쳐 테스트를 통과시키지 않는다.
--- a/agent-test/dev/inventory.yaml
+++ b/agent-test/dev/inventory.yaml
@ -0,0 +1,87 @@
+test_env: dev
+profile: remote-mac-runner
+last_updated_at: "2026-07-18"
+
+source:
+  remote_runner:
+    ssh: toki@toki-labs.com
+    os: macOS
+    arch: arm64
+    repo_root: /Users/toki/agent-work/rara-dev
+    checkout_status: provisioning_required
+    observed_at: "2026-07-18"
+  sync:
+    target_ref: exact_commit_under_test
+    remote_dirty_policy: discard_after_identity_review
+    require_local_remote_identity_match: true
+
+runtime:
+  go_required: "1.26"
+  go_observed_login_shell: "1.26.3"
+  python_required: "3.12"
+  python_observed_command: python3.12
+  python_observed_version: "3.12.9"
+  default_python3_observed_version: "3.14.6"
+  login_shell_required_for_tool_path: true
+  docker_cli_observation: available_in_login_shell
+  docker_client_version: "27.4.0"
+  docker_engine_version: "27.4.0"
+  postgres_status: not_verified
+  model_endpoint: not_configured
+
+ports:
+  allocation_basis: workspace_70_slot_assigned_to_rara_after_collision_check_2026_07_18
+  recheck_before_use: true
+  control_plane_http:
+    host: 127.0.0.1
+    port: 18070
+  rag_api_http:
+    host: 127.0.0.1
+    port: 18071
+  go_worker_http:
+    host: 127.0.0.1
+    port: 18072
+  python_executor_grpc:
+    host: 127.0.0.1
+    port: 19070
+  postgres_host_publish:
+    host: 127.0.0.1
+    port: 15470
+    container_port: 5432
+    publish_only_when_required: true
+  reserved:
+    frontend: 13070
+    cache: 16370
+    metrics_diagnostics:
+      - 19170
+      - 19171
+      - 19172
+
+compose_candidate:
+  status: not_implemented
+  project_name: rara-dev-agent
+  network: rara-dev-agent-net
+  subnet_candidate: 10.89.7.0/24
+  subnet_collision_observed: false
+  subnet_observed_at: "2026-07-18"
+  subnet_recheck_before_create: true
+
+services:
+  control_plane:
+    config: configs/control-plane.yaml
+    listen_override: 127.0.0.1:18070
+    health_url: http://127.0.0.1:18070/healthz
+    readiness_url: http://127.0.0.1:18070/readyz
+  rag_api:
+    config: configs/rag-api.yaml
+    listen_override: 127.0.0.1:18071
+    health_url: http://127.0.0.1:18071/healthz
+    readiness_url: http://127.0.0.1:18071/readyz
+  go_worker:
+    config: configs/worker.yaml
+    listen_override: 127.0.0.1:18072
+    health_url: http://127.0.0.1:18072/healthz
+    readiness_url: http://127.0.0.1:18072/readyz
+  python_executor:
+    listen_host: 127.0.0.1
+    listen_port: 19070
--- a/agent-test/dev/platform-common-smoke.md
+++ b/agent-test/dev/platform-common-smoke.md
@ -0,0 +1,98 @@
+---
+test_env: dev
+test_profile: platform-common-smoke
+domain: platform-common
+verification_type: smoke
+last_rule_updated_at: 2026-07-18
+---
+
+# platform-common-smoke dev 테스트
+
+## 읽기 조건
+
+- 설정, database, HTTP lifecycle, observability, artifact store, integration port 또는
+  배포 구성을 원격 환경에서 검증할 때
+
+## 적용 범위
+
+- `packages/go/artifact/`, `packages/go/config/`, `packages/go/database/`,
+  `packages/go/httpserver/`, `packages/go/integration/`,
+  `packages/go/observability/`, `configs/`, `deploy/`
+
+## 분류
+
+- domain: platform-common
+- verification_type: smoke
+- scope: 원격 runner의 공통 adapter, 포트 override, 서비스 조립 검증
+
+## 환경
+
+- host: `ssh toki@toki-labs.com`
+- repo root: `/Users/toki/agent-work/rara-dev`
+- port: HTTP `18070-18072`, Python gRPC `19070`, PostgreSQL host publish 후보 `15470`
+- runtime: macOS arm64, Go 1.26, Python 3.12
+- package manager: Go modules, Python venv/pip
+- docker: login shell의 Docker Desktop/Engine 27.4.0, 일반 비대화형 PATH에는 없음
+- external service: service readiness와 database adapter 통합 검증에는 PostgreSQL 필요
+- model endpoint: 기본값 없음
+- credential: secret/token/API key 원문은 문서와 출력에 남기지 않는다.
+
+## 명령
+
+- setup: `make setup`
+- lint: 변경한 Go 파일의 `gofmt` 상태와 Python Ruff 검사 확인
+- unit: `go test ./packages/go/artifact/... ./packages/go/config/... ./packages/go/database/... ./packages/go/httpserver/... ./packages/go/integration/... ./packages/go/observability/...`
+- smoke: `make build`
+- e2e: PostgreSQL과 dev service override가 준비된 경우 세 Go service의 health/readiness 확인
+- model: integration provider가 명시적으로 준비된 경우에만 수행
+- full-cycle: `make test && make build`
+
+## 필수 검증
+
+- 원격 checkout의 HEAD가 검증 대상 source와 일치한다.
+- 변경된 공통 Go package 테스트가 통과하고 세 Go service가 모두 빌드된다.
+- 원격 실행 시 local 기본 포트 대신 `18070-18072`, `19070`, 필요 시 `15470`을 사용한다.
+- 설정·배포·로그·trace에 secret 원문이 포함되지 않았는지 확인한다.
+- Docker/PostgreSQL 부재 시 integration 검증을 통과로 간주하지 않는다.
+
+## 보조 검증
+
+- `lsof`로 `13070`, `18070-18072`, `15470`, `16370`, `19070`,
+  `19170-19172` 전체를 확인해 `70` 슬롯 부분 충돌을 탐지한다.
+- container runtime이 준비되면 PostgreSQL은 host `15470`에서 container `5432`로
+  publish하고 service readiness를 확인한다.
+- artifact filesystem root가 runner의 허용된 작업 경로 밖으로 벗어나지 않는지 확인한다.
+
+## 판정 기준
+
+- source identity가 일치하고 테스트와 전체 build가 exit code 0으로 종료한다.
+- dev port override가 IOP shared `18080-18099`, `19080`, `19090`을 사용하지 않는다.
+- 실행한 integration만 근거와 함께 통과로 보고하고 미준비 dependency는 차단으로 남긴다.
+
+## 기준 출력 예시
+
+```text
+ok   git.toki-labs.com/toki/rara/packages/go/...
+```
+
+## 차단 기준
+
+- 원격 checkout 부재·source 불일치, 필수 runtime 부재, dev port 점유
+- database 통합 검증에 필요한 PostgreSQL 부재
+- config override 없이 local 포트를 shared remote host에 publish하려는 경우
+
+## 보고 항목
+
+- 원격 branch/HEAD:
+- 실행한 명령:
+- 성공한 검증:
+- 실패/차단된 검증:
+- 생략 사유:
+- 남은 위험:
+
+## 금지 사항
+
+- local 기본 포트 `18080-18082`, `19090`, `5432`를 shared remote runner에
+  그대로 publish하지 않는다.
+- 운영 secret이나 개인 endpoint를 config 또는 테스트 문서에 기록하지 않는다.
+- 공통 adapter 테스트를 특정 plane의 정책 검증으로 대체하지 않는다.
--- a/agent-test/dev/rag-data-plane-smoke.md
+++ b/agent-test/dev/rag-data-plane-smoke.md
@ -0,0 +1,92 @@
+---
+test_env: dev
+test_profile: rag-data-plane-smoke
+domain: rag-data-plane
+verification_type: smoke
+last_rule_updated_at: 2026-07-18
+---
+
+# rag-data-plane-smoke dev 테스트
+
+## 읽기 조건
+
+- retrieve·answer handler, release resolver, engine port, OpenAPI 또는 rag-api를
+  원격 환경에서 검증할 때
+
+## 적용 범위
+
+- `apps/rag-api/`, `packages/go/rag/`, `api/openapi/`
+
+## 분류
+
+- domain: rag-data-plane
+- verification_type: smoke
+- scope: 원격 runner의 retrieve·answer 계약과 rag-api readiness 검증
+
+## 환경
+
+- host: `ssh toki@toki-labs.com`
+- repo root: `/Users/toki/agent-work/rara-dev`
+- port: RAG API `127.0.0.1:18071`, PostgreSQL host publish 후보 `127.0.0.1:15470`
+- runtime: Go 1.26
+- package manager: Go modules
+- docker: login shell의 Docker Desktop/Engine 27.4.0, 실행 전 daemon 재확인
+- external service: readiness·실제 retrieve/answer에는 PostgreSQL과 승인된 integration 필요
+- model endpoint: 기본값 없음
+- credential: integration/database credential 원문은 문서와 출력에 남기지 않는다.
+
+## 명령
+
+- setup: `make setup`
+- lint: 변경한 Go 파일의 `gofmt` 상태와 diff 확인
+- unit: `go test ./packages/go/rag/...`
+- smoke: `go build -o /tmp/rara-rag-api ./apps/rag-api/cmd/rag-api`
+- service: PostgreSQL 준비 후 `RARA_LISTEN=127.0.0.1:18071`과 주입된
+  `RARA_DATABASE_URL`로 binary를 실행하고 `/healthz`, `/readyz` 확인
+- e2e: integration이 명시적으로 준비된 경우에만 `/v1/retrieve`, `/v1/answer`
+  JSON·SSE 계약 확인
+- model: 승인된 generation provider가 있을 때만 수행
+- full-cycle: `make test && make build`
+
+## 필수 검증
+
+- 원격 checkout의 HEAD가 검증 대상 source와 일치한다.
+- RAG handler와 resolver 테스트가 통과하고 rag-api binary가 빌드된다.
+- 공개 요청·응답 변경 시 OpenAPI와 JSON/SSE 오류 의미가 일치한다.
+- PostgreSQL이 준비된 경우 `18071`에서 health와 readiness를 확인한다.
+
+## 보조 검증
+
+- `lsof -nP -iTCP:18071 -sTCP:LISTEN`으로 시작 전 충돌과 종료 후 반환을 확인한다.
+- 준비된 non-production integration이 있을 때 retrieve와 answer 실제 응답을 확인한다.
+
+## 판정 기준
+
+- source identity가 일치하고 테스트·빌드가 exit code 0으로 종료한다.
+- service smoke를 수행한 경우 health와 readiness가 성공한다.
+- 실제 integration이 없으면 handler 단위 테스트와 unavailable 동작까지만 통과로 보고한다.
+
+## 기준 출력 예시
+
+```text
+ok   git.toki-labs.com/toki/rara/packages/go/rag
+```
+
+## 차단 기준
+
+- 원격 checkout 부재·source 불일치, Go 1.26 부재, `18071` 점유
+- readiness에 필요한 PostgreSQL 또는 실제 통합 smoke에 필요한 integration 부재
+
+## 보고 항목
+
+- 원격 branch/HEAD:
+- 실행한 명령:
+- 성공한 검증:
+- 실패/차단된 검증:
+- 생략 사유:
+- 남은 위험:
+
+## 금지 사항
+
+- local test 결과나 unavailable engine을 실제 원격 retrieve·answer 성공으로 보고하지 않는다.
+- secret, token, 개인 endpoint 원문을 기록하지 않는다.
--- a/agent-test/dev/rules.md
+++ b/agent-test/dev/rules.md
@ -0,0 +1,127 @@
+---
+test_env: dev
+last_rule_updated_at: 2026-07-18
+---
+
+# dev 테스트 규칙
+
+**현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.**
+**dev는 RARA의 기본 테스트 환경이며 local host가 아니라 원격 Mac runner를 기준으로 한다.**
+
+## 공통 규칙
+
+- 사용자가 테스트 환경을 별도로 지정하지 않으면 이 `dev` 환경을 기본 기준으로 삼는다.
+- local 검증은 원격 프리플라이트와 source 동기화를 대신하지 않는다.
+- 작업 완료 검증은 변경 범위에 맞는 도메인 profile을 선택한다.
+- 필수 검증을 실행하지 못하면 차단 사유로 보고한다.
+- 최종 보고에는 원격 source identity, 실행 명령, 결과, 생략 사유, 남은 위험을 남긴다.
+- secret, token, password, private key, 개인 endpoint 원문은 tracked 파일이나
+  shell 출력에 남기지 않는다.
+- 원격 서비스는 기본적으로 runner loopback에 bind한다. 외부 공개 검증이 명시된
+  경우에만 별도 접근 경계와 방화벽 상태를 확인한다.
+
+## 기본 환경
+
+- host: `ssh toki@toki-labs.com` 표준 원격 Mac runner
+- repo root: 목표 checkout `/Users/toki/agent-work/rara-dev`
+- checkout 상태: 2026-07-18 점검 시 아직 없음. 최초 원격 검증 전 생성이 필요하다.
+- sync 기준: 검증할 exact source commit을 origin에서 fetch한 뒤 clean checkout하고,
+  local 변경과 원격 HEAD가 동일한지 확인한다.
+- runtime: macOS arm64. 2026-07-18 login shell에서 Go 1.26.3과
+  Python 3.12.9(`python3.12`)를 확인했다.
+- package manager: Go modules, Python venv/pip
+- docker: login shell의 Docker Desktop/Engine 27.4.0을 사용한다. 일반 비대화형
+  SSH PATH에는 Go와 Docker가 없으므로 원격 명령은 login shell 또는 검증된 explicit
+  PATH로 실행한다.
+- external service: readiness·통합 smoke에는 PostgreSQL이 필요하며, 준비되지 않으면
+  source test/build까지만 수행하고 통합 검증은 차단으로 보고한다.
+- model endpoint: 기본값 없음. adaptation/model 통합 검증 시 별도 승인된 endpoint가 필요하다.
+- credential: secret/token/API key 원문은 문서에 기록하지 않는다.
+
+## 포트 매핑
+
+2026-07-18 기준 workspace 원장에 기존 `70` 슬롯 배정이 없고, 원격 runner의 아래
+후보 포트가 listen 중이 아님을 확인한 뒤 RARA `dev` 전용으로 배정했다. 실행 직전
+동일 검사를 반복한다.
+
+| 용도 | local 호환값 | dev 원격값 | bind 기준 |
+|---|---:|---:|---|
+| Control Plane HTTP | `18080` | `18070` | `127.0.0.1:18070` |
+| RAG API HTTP | `18081` | `18071` | `127.0.0.1:18071` |
+| Go Worker HTTP | `18082` | `18072` | `127.0.0.1:18072` |
+| Python Executor gRPC | `19090` | `19070` | `127.0.0.1:19070` |
+| PostgreSQL host publish | `5432` | `15470` | `127.0.0.1:15470 -> 5432` |
+| Frontend reserve | 해당 없음 | `13070` reserved | 현재 RARA runtime에 없음 |
+| Cache reserve | 해당 없음 | `16370` reserved | 현재 RARA runtime에 없음 |
+| Metrics / diagnostics reserve | 해당 없음 | `19170-19172` reserved | 현재 RARA runtime에 없음 |
+
+- `18080-18099`와 `19080/19090`은 IOP shared field/runtime baseline이므로 RARA
+  원격 dev 서비스에 재사용하지 않는다.
+- repo의 `configs/*.yaml` 기본 listen 값은 local 호환값이다. 원격 dev에서는
+  `RARA_LISTEN`과 `RARA_PYTHON_LISTEN_PORT`로 위 dev 값을 명시한다.
+- PostgreSQL host publish가 필요하지 않으면 `15470`을 열지 않고 service와 DB를
+  전용 network 또는 loopback으로만 연결한다.
+
+## 런타임 프로필
+
+- source validation: 원격 checkout에서 `make test && make build`를 기본 완료 검증으로 사용한다.
+- service smoke: PostgreSQL이 준비된 경우 Control Plane `18070`, RAG API `18071`,
+  Go Worker `18072`를 각각 dev override로 실행하고 health/readiness를 확인한다.
+- Python executor smoke: `RARA_PYTHON_LISTEN_HOST=127.0.0.1`과
+  `RARA_PYTHON_LISTEN_PORT=19070`을 사용한다.
+- compose candidate: 향후 remote compose를 추가할 경우
+  `COMPOSE_PROJECT_NAME=rara-dev-agent`, network `rara-dev-agent-net`,
+  subnet `10.89.7.0/24`, PostgreSQL host publish `15470`을 기준으로 한다.
+  2026-07-18 기존 remote Docker network와 subnet이 겹치지 않음을 확인했지만,
+  현재 compose에는 dev override와 network 정의가 없으므로 실제 구성으로 간주하지 않는다.
+- artifact: runner-local filesystem artifact root를 사용하며 공개 artifact HTTP 포트는 없다.
+
+## 프리플라이트
+
+- 원격 검증 전 runner 접속, `/Users/toki/agent-work/rara-dev` 존재 여부, branch,
+  HEAD, dirty 상태, local 변경과 source 동기화 여부를 확인한다.
+- login shell에서 `go version`, `python3.12 --version`, `docker version`, 필요한
+  tool/version, `.venv`의 Python identity를 확인한다. 기본 `python3`은 2026-07-18
+  기준 3.14.6이므로 Python 3.12 venv라고 추정하지 않는다.
+- `13070`, `18070-18072`, `15470`, `16370`, `19070`, `19170-19172`가 다른
+  process에 점유되지 않았는지 확인한다. 미사용 후보까지 함께 확인해 `70` 슬롯의
+  부분 재사용을 방지한다.
+- service smoke 전 config path, `RARA_LISTEN`, `RARA_DATABASE_URL`,
+  artifact root, process identity를 확인한다.
+- Docker daemon과 PostgreSQL container가 실제로 준비되지 않았으면 설치 상태만으로
+  통합 검증 가능하다고 추정하지 않고 integration blocker로 보고한다.
+- checkout 부재, source 불일치, stale binary, port 점유, runtime version 불일치는
+  setup/sync/rebuild 후 해소하거나 차단 사유로 보고한다.
+
+## 노드/서비스 인벤토리 위치
+
+- machine-readable runner·port 기준: `agent-test/dev/inventory.yaml`
+- Control Plane 기준: `agent-test/dev/control-plane-smoke.md`
+- RAG API 기준: `agent-test/dev/rag-data-plane-smoke.md`
+- Go/Python worker 기준: `agent-test/dev/workflow-execution-smoke.md`
+- 공통 config·database·artifact·배포 기준: `agent-test/dev/platform-common-smoke.md`
+
+## 반복 테스트 기준
+
+- 원격 evidence는 current source와 동일한 remote checkout에서만 수집한다.
+- source test/build와 PostgreSQL 의존 service smoke를 구분해 보고한다.
+- 여러 RARA 서비스를 동시에 실행할 때 각 프로세스에 다른 `RARA_LISTEN`을 명시한다.
+- test 종료 후 장기 runtime으로 승인되지 않은 프로세스는 정리하고, 포트가 반환됐는지 확인한다.
+- secret이 포함될 수 있는 database URL과 외부 endpoint는 값 대신 주입 여부만 보고한다.
+
+## 라우팅
+
+- control-plane / smoke / 수명주기 API와 제어 상태 원격 검증:
+  `agent-test/dev/control-plane-smoke.md`
+- rag-data-plane / smoke / retrieve·answer 계약 원격 검증:
+  `agent-test/dev/rag-data-plane-smoke.md`
+- workflow-execution / smoke / Go worker와 Python executor 원격 검증:
+  `agent-test/dev/workflow-execution-smoke.md`
+- platform-common / smoke / config·database·artifact·배포 원격 검증:
+  `agent-test/dev/platform-common-smoke.md`
+
+## 라우팅 규칙
+
+- 여러 항목이 맞으면 모두 읽는다.
+- 도메인 매핑이나 domain rule이 있으면 각 도메인의 `<domain>-smoke`를 baseline으로 둔다.
+- 도메인/검증 시나리오별 문서는 다른 테스트 문서로 라우팅하지 않는다.
--- a/agent-test/dev/workflow-execution-smoke.md
+++ b/agent-test/dev/workflow-execution-smoke.md
@ -0,0 +1,99 @@
+---
+test_env: dev
+test_profile: workflow-execution-smoke
+domain: workflow-execution
+verification_type: smoke
+last_rule_updated_at: 2026-07-18
+---
+
+# workflow-execution-smoke dev 테스트
+
+## 읽기 조건
+
+- Go worker, executor registry, Python executor 또는 Protobuf 실행 계약을 원격
+  환경에서 검증할 때
+
+## 적용 범위
+
+- `apps/worker/`, `packages/go/workflow/`, `packages/python/`, `api/proto/`,
+  `gen/go/rara/v1/`
+
+## 분류
+
+- domain: workflow-execution
+- verification_type: smoke
+- scope: 원격 runner의 Go worker와 Python gRPC executor 검증
+
+## 환경
+
+- host: `ssh toki@toki-labs.com`
+- repo root: `/Users/toki/agent-work/rara-dev`
+- port: Go Worker `127.0.0.1:18072`, Python Executor gRPC `127.0.0.1:19070`
+- runtime: Go 1.26, Python 3.12
+- package manager: Go modules, Python venv/pip
+- docker: login shell의 Docker Desktop/Engine 27.4.0, PostgreSQL 통합 검증 전 daemon 재확인
+- external service: Go worker 상태 전이 검증에는 PostgreSQL 필요
+- model endpoint: 기본값 없음. adaptation 모델 검증은 별도 승인된 endpoint 필요
+- credential: database/model credential 원문은 문서와 출력에 남기지 않는다.
+
+## 명령
+
+- setup: `make setup`
+- lint: `.venv/bin/ruff format --check packages/python/src packages/python/tests && .venv/bin/ruff check packages/python/src packages/python/tests`
+- unit: `go test ./packages/go/workflow/... && PYTHONPATH=packages/python/src .venv/bin/python -m pytest packages/python/tests`
+- smoke: `go build -o /tmp/rara-worker ./apps/worker/cmd/worker`
+- service: PostgreSQL 준비 후 Go worker는 `RARA_LISTEN=127.0.0.1:18072`,
+  Python executor는 `RARA_PYTHON_LISTEN_HOST=127.0.0.1`
+  `RARA_PYTHON_LISTEN_PORT=19070`으로 실행
+- e2e: PostgreSQL과 executor가 준비된 경우 ping step의 lease와 terminal 상태 확인
+- model: ML dependency와 승인된 endpoint가 준비된 경우에만 수행
+- full-cycle: `make test && make build`
+
+## 필수 검증
+
+- 원격 checkout의 HEAD가 검증 대상 source와 일치한다.
+- Go workflow와 Python executor 테스트, Ruff 검사가 통과한다.
+- Go worker binary가 빌드된다.
+- Protobuf 변경 시 `make proto` 후 Go/Python 생성물과 호환성 영향을 확인한다.
+- service smoke 시 `18072`와 `19070`이 각각 의도한 프로세스에만 점유된다.
+
+## 보조 검증
+
+- `lsof -nP -iTCP:18072 -sTCP:LISTEN`과
+  `lsof -nP -iTCP:19070 -sTCP:LISTEN`으로 충돌과 종료 후 반환을 확인한다.
+- PostgreSQL을 준비한 경우 step lease·성공·실패·재시도 상태 전이를 확인한다.
+
+## 판정 기준
+
+- source identity가 일치하고 Go/Python 테스트, Ruff, worker 빌드가 exit code 0으로 종료한다.
+- service smoke를 수행한 경우 Go worker health/readiness와 Python gRPC capability
+  응답을 확인한다.
+- PostgreSQL·ML dependency가 없으면 source 검증과 통합 차단을 구분해 보고한다.
+
+## 기준 출력 예시
+
+```text
+ok   git.toki-labs.com/toki/rara/packages/go/workflow
+```
+
+## 차단 기준
+
+- 원격 checkout 부재·source 불일치, Go 1.26/Python 3.12/`.venv` 부재
+- `18072` 또는 `19070` 점유
+- 상태 전이 검증에 필요한 PostgreSQL 또는 모델 검증에 필요한 ML dependency 부재
+
+## 보고 항목
+
+- 원격 branch/HEAD:
+- 실행한 명령:
+- 성공한 검증:
+- 실패/차단된 검증:
+- 생략 사유:
+- 남은 위험:
+
+## 금지 사항
+
+- local test 결과를 원격 worker/executor evidence로 보고하지 않는다.
+- 생성된 Protobuf 파일을 직접 수정하지 않는다.
+- ML dependency가 없는 환경에서 adaptation 모델 실행이 검증됐다고 보고하지 않는다.
+- secret, token, 개인 endpoint 원문을 기록하지 않는다.