---
name: e2e-smoke
version: 1.1.0
description: scripts/dev/edge.sh와 scripts/dev/node.sh 기반 repo 내부 edge-node 진단, 보조 E2E smoke, 실제 외부 CLI 통합 검증 절차
---

# e2e-smoke

## 목적

repo 내부 edge-node 진단이 필요할 때 `scripts/dev/edge.sh`와 `scripts/dev/node.sh`를 각각 실행하고, edge console에서 메시지 2회와 command 명령을 직접 보내 결과가 edge 화면에 표시되는지 검증한다. field 사용자 기본 UX는 Edge가 제시한 bootstrap 명령이며, `scripts/dev/*` helper를 공식 사용자 경로로 안내하지 않는다. `make test-e2e`와 `scripts/e2e-smoke.sh`는 최소 생존을 빠르게 확인하는 보조 smoke일 뿐이며, 사용자 실행 파이프라인 변경의 완료 기준이 아니다.

## 언제 호출할지

- 사용자 실행 파이프라인에 닿는 작업을 완료한 뒤 검증 단계에 들어갈 때
- `scripts/dev/**`, `Makefile`, `apps/*/cmd/**`, `apps/*/internal/bootstrap/**`, edge-node transport/service/registry, adapter 실행/stream/cancel/status 경로를 변경했을 때
- `configs/**`, `packages/go/config/**`, 관련 protobuf 계약 변경이 edge-node 실행 방식에 영향을 줄 때
- `make test-e2e` 또는 보조 E2E smoke 스크립트를 만들거나 갱신할 때

## 입력

- `scope`: 검증할 변경 범위와 영향을 받은 도메인 (필수)
- `mode`: `bin-diagnostic`, `mock-smoke`, `real-cli`, `full-cycle`, `all` 중 하나 (선택, 기본값: `bin-diagnostic`)
- `profiles`: 검증할 실제 외부 CLI profile 목록. 지정하지 않으면 기준 profile인 `claude`, `antigravity`, `codex`, `opencode`를 대상으로 한다. (선택)
- `config_strategy`: 임시 config 파일 또는 환경 변수 override 방식 (선택)

## 먼저 확인할 것

- [ ] `agent-ops/rules/project/domain/testing/rules.md`를 읽고 이번 작업에 필요한 repo 내부 edge-node 진단 또는 field bootstrap 검증 범위를 확인한다.
- [ ] `scripts/dev/edge.sh`와 `scripts/dev/node.sh`는 repo 내부 진단 helper이며 field 사용자 기본 entrypoint가 아님을 확인한다.
- [ ] `make test-e2e` 같은 고정 smoke 명령은 보조 확인으로만 취급한다.
- [ ] 기본 `configs/*.yaml`을 오염시키지 않도록 임시 config 또는 환경 변수 override 전략을 정한다.
- [ ] 실제 외부 CLI 검증이 필요한 경우 command 경로, 로그인/계정 상태, provider 설정, workspace 권한이 준비되어 있는지 확인한다.

## 실행 절차

1. **검증 범위 결정**
   - 변경 파일이 사용자 실행 파이프라인에 닿는지 확인한다.
   - 필수 검증은 `go test ./...` 또는 대상 패키지 테스트와 변경 범위에 맞는 full-cycle 실제 구동이다. repo 내부 edge-node 진단에는 `scripts/dev/edge.sh`와 `scripts/dev/node.sh`를 사용할 수 있다.
   - 보조 smoke는 실행할 수 있으면 기록하되, 통과만으로 완료 처리하지 않는다.
   - 풀테스트에서는 실제 외부 CLI profile 검증을 full-cycle에 포함한다.

2. **repo 내부 edge-node 진단 준비**
   - edge와 node는 `scripts/dev/edge.sh`, `scripts/dev/node.sh`를 각각 별도 프로세스로 실행한다. 이 흐름은 내부 진단용이며 사용자-facing field bootstrap 안내가 아니다.
   - 임시 edge/node config 또는 환경 변수 override를 사용하고, edge listen 주소와 node edge 주소는 충돌을 피하기 위해 임시 포트를 사용한다.
   - 검증용 target은 변경 범위에 맞춘다. 외부 CLI 자체가 검증 대상이 아니면 deterministic CLI profile을 사용해 메시지 출력 내용을 분명하게 만든다.

3. **startup/register cycle**
   - 먼저 `scripts/dev/edge.sh`를 실행해 edge console prompt가 뜨는지 확인한다.
   - 다른 프로세스에서 `scripts/dev/node.sh`를 실행해 node가 edge에 연결되는지 확인한다.
   - edge 화면에 `[node-*-event] connected reason="registered"`가 표시되어야 한다.
   - edge console에서 `/nodes`를 입력하고 node ID와 alias가 표시되어야 한다.

4. **메시지 2회 왕복 기준**
   - edge console prompt에 메시지를 한 번 입력한다.
   - 첫 번째 요청에서 `[edge] sent`, `[node-*-event] start`, 비어 있지 않은 `[node-*-message]`, `[node-*-event] complete`가 edge 화면에 도착해야 한다.
   - node 로컬 출력에 생성된 같은 run의 `[node-message]` payload 라인 목록이 edge console의 `[node-*-message]` payload 라인 목록과 내용/순서까지 동일한지 비교한다.
   - complete event만으로 정상 판정하지 않는다. complete event는 node가 생성한 모든 message payload가 edge에 동일하게 표시된 뒤의 마감 신호여야 한다.
   - 답변이 끝나기 전에 edge complete가 먼저 표시되거나 complete 뒤에 같은 run의 message가 추가로 표시되면 실패로 판정한다.
   - 같은 session에서 두 번째 메시지를 입력하고 같은 출력 흐름이 다시 도착해야 한다.
   - 두 번째 메시지가 첫 번째 메시지 이후에도 같은 edge-node 연결에서 정상 처리되는지 확인한다.
   - foreground run에서는 complete event 전에 다음 검증으로 넘어가지 않는다.

5. **edge command 응답 기준**
   - edge console에서 command를 직접 입력하고 결과가 edge 화면에 도착하는지 확인한다.
   - 기본 command 기준은 `/nodes`, `/capabilities`, `/transport`, `/sessions`이다.
   - persistent profile이면 `/terminate-session`을 실행하고 성공 출력 또는 명확한 unsupported/error 출력을 확인한다.
   - status 경로를 바꾼 작업은 `/status` 결과를 확인한다. 지원 profile이면 status 출력 내용을 확인하고, 미지원 profile이면 명확한 unsupported error를 확인한다.
   - multi-node/routing을 바꾼 작업은 node 2대를 실제로 붙여 ambiguous error와 `/node <id|alias>` 선택 후 라우팅을 확인한다.
   - cancel/timeout/persistent session을 바꾼 작업은 해당 cycle도 실제 구동으로 확인한다.

6. **기준 출력 예시**

```text
edge> /nodes
  test-node (test-node)

edge> Convert token iop_manual_one and reply only with converted token
[edge] sent run_id=manual-... node=test-node adapter=cli target=fake-cli session=default background=false
[node-test-node-event] start run_id=manual-...
[node-test-node-message] IOP_MANUAL_ONE_OK
[node-test-node-message] IOP_MANUAL_ONE_TAIL
[node-test-node-event] complete run_id=manual-... detail="idle-timeout"

edge> Convert token iop_manual_two and reply only with converted token
[edge] sent run_id=manual-... node=test-node adapter=cli target=fake-cli session=default background=false
[node-test-node-event] start run_id=manual-...
[node-test-node-message] IOP_MANUAL_TWO_OK
[node-test-node-message] IOP_MANUAL_TWO_TAIL
[node-test-node-event] complete run_id=manual-... detail="idle-timeout"

edge> /capabilities
[node-test-node-capabilities] target=fake-cli session=default
  adapter = cli
  max_concurrency = 4
  targets = fake-cli

edge> /transport
[node-test-node-transport] target=fake-cli session=default
  adapter = cli
  connected = true
  node_id = test-node
  session_id = default
  target = fake-cli

edge> /sessions
[node-test-node-sessions] target=fake-cli session=default
  count = 1
  sessions = persistent:fake-cli/default

edge> /terminate-session
terminated session default node=test-node
```

7. **보조 E2E smoke**
   - `make test-e2e` 또는 `scripts/e2e-smoke.sh`는 보조 확인으로 실행할 수 있다.
   - 보조 smoke에서는 mock adapter와 임시 설정/포트를 사용해 외부 CLI 의존성 없이 최소 생존을 확인한다.
   - 보조 smoke 통과를 repo 내부 edge-node 진단 또는 field bootstrap 검증 통과로 대체해 보고하지 않는다.

8. **CLI profile 실제 구동 검증**
   - 풀테스트에서는 기준 실제 외부 CLI profile을 한 번씩 실제 구동한다.
   - `claude`, `antigravity`, `codex`, `opencode`를 대상으로 같은 session 메시지를 최소 2회 주고받는다.
   - 각 profile에서 start, delta-or-message, complete 출력이 모두 생기는지 확인한다.
   - command, 로그인, provider, workspace 권한, 원격 endpoint 문제로 실행할 수 없거나 실패한 profile은 누락이 아니라 실패/blocker로 profile별 보고한다.

9. **결과 보고**
   - 실행한 Go 테스트 명령과 결과를 적는다.
   - repo 내부 edge-node 진단에서 사용한 config 전략, 메시지 2회 결과, command 응답 결과를 적는다.
   - 보조 smoke를 실행했다면 별도 항목으로만 적는다.
   - full-cycle에서 돌린 cycle 목록과 돌리지 못한 cycle 목록을 구분해 적는다.
   - 필수 검증을 실행하지 못했다면 이유와 남은 위험을 명시한다.

## 실행 결과 검증

- [ ] 일반 Go 테스트 또는 대상 패키지 테스트 결과가 보고되었는가
- [ ] `scripts/dev/edge.sh`와 `scripts/dev/node.sh`를 각각 실행한 repo 내부 edge-node 진단 결과가 보고되었는가
- [ ] node register와 `/nodes` 결과가 edge 화면에 표시되었는가
- [ ] 같은 session에서 메시지 2회가 각각 sent/start/message/complete로 표시되었는가
- [ ] node 로컬 `[node-message]` payload 라인 목록이 edge `[node-*-message]` 출력과 run별로 내용/순서까지 동일한가
- [ ] edge complete가 같은 run의 마지막 message 출력 이후에 표시되고, complete 뒤에 같은 run의 message가 추가로 표시되지 않았는가
- [ ] `/capabilities`, `/transport`, `/sessions`, 관련 command 결과가 edge 화면에 표시되었는가
- [ ] 보조 smoke를 실행했다면 repo 내부 edge-node 진단 또는 field bootstrap 검증과 구분해 보고했는가
- [ ] 풀테스트에서 실제 외부 CLI profile별 메시지 왕복과 `/status` 결과가 보고되었는가
- 검증 실패 시: 실패한 항목, 관련 로그/출력 요약, 남은 위험을 최종 보고에 포함한다.

## 출력 형식

```text
검증 결과
- Go 테스트: <명령> - <통과|실패|미실행 사유>
- Repo 내부 edge-node 진단: <통과|실패|미실행 사유>
- 메시지 왕복: message x2 - <통과|실패|미실행 사유>
- Node message relay: node local payload == edge rendered payload - <통과|실패|미실행 사유>
- Edge command 응답: /nodes, /capabilities, /transport, /sessions, <관련 command> - <통과|실패|미실행 사유>
- 보조 E2E smoke: <mock|real-cli|미실행> - <통과|실패|미실행 사유>
- Full-cycle 실제 구동: <통과|실패|미실행 사유>
- Real CLI profile: <profile별 통과|실패|blocker>
- 남은 위험: <없음 또는 내용>
```

## 금지 사항

- 사용자 실행 파이프라인에 닿는 변경을 하고 유닛/패키지 테스트만으로 완료 처리하지 않는다.
- `make test-e2e`, `scripts/e2e-smoke.sh`, 또는 smoke 통과 출력만으로 완료 처리하지 않는다.
- 관련 작업 후 필요한 full-cycle 실제 구동 또는 repo 내부 edge-node 진단을 비용이 크다는 이유만으로 생략하지 않는다.
- 보조 E2E smoke를 외부 CLI 설치, 로그인, 네트워크 계정 상태에 의존하게 만들지 않는다.
- 검증을 위해 기본 `configs/*.yaml`을 임시값으로 오염시키지 않는다.
- 필수 검증을 실행하지 못했는데 조용히 생략하지 않는다.
