# Milestone: 전역 설계 부채 리팩토링 기반

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/automation-runtime-bridge/PHASE.md`

## 목표

원격 터미널 브리지와 이후 Control Plane/Client 운영 확장을 얹기 전에 현재 코드베이스의 설계 부채를 정리한다.
Edge, Node, Control Plane, Client, proto/config 경계에서 책임이 섞인 부분을 분리하고, 공개 계약과 tracked 예시 설정이 장기 운영 방향을 흐리지 않게 만든다.

## 상태

[완료]

## 구현 잠금

- 상태: 해제
- 결정 필요: 없음

## 범위

- Edge CLI, Edge service, OpenAI-compatible 입력 표면의 책임 분리
- Node CLI adapter, persistent terminal/SSE 실행기, adapter routing 기본값 정리
- Control Plane HTTP/API handler와 fleet status 호출 구조 정리
- Client 상태/DTO/repository/widget 경계 정리
- proto status/legacy contract와 tracked config/artifact hygiene 정리
- 원격 터미널 브리지 POC가 기대는 terminal/session/event 경계의 선행 리팩토링

## 기능

### Epic: [edge-boundary] Edge Boundary Refactor

Edge 내부에서 CLI command, service orchestration, external compatibility surface가 서로 커지는 것을 막는다.

- [x] [edge-cmd-split] `apps/edge/cmd/edge/main.go`의 config resolution, bootstrap pack, node registration, YAML patch, smoke client 로직을 기존 동작을 유지한 채 내부 패키지 또는 작은 모듈로 분리한다.
- [x] [edge-service-split] `apps/edge/internal/service`를 run dispatch, node command, control command, capability/status provider 책임으로 분리하고 health simulation 같은 임시 command 구현을 실제 상태 조회 경계와 분리한다.
- [x] [openai-surface-split] `apps/edge/internal/openai`에서 HTTP lifecycle, chat request mapping, run stream/result collection, strict output policy, Ollama passthrough를 분리해 OpenAI-compatible 표면이 IOP native 기능을 흡수하지 않게 한다.
- [x] [event-bus-contract] Edge event bus의 drop, replay, immutability, future persistence 정책을 코드 경계와 테스트로 명확히 한다. 검증: `go test ./apps/edge/internal/events` 통과.

### Epic: [node-runtime] Node Runtime Boundary

Node CLI automation runtime을 remote terminal bridge가 재사용할 수 있는 단위와 provider-specific 실행 단위로 나눈다.

- [x] [cli-executor-split] `apps/node/internal/adapters/cli`의 mode dispatch와 session map 소유를 executor/strategy 경계로 분리한다. 검증: `agent-task/archive/2026/06/m-architecture-refactor-foundation/04_cli_executor_split/complete.log`
- [x] [terminal-core] persistent PTY 실행, screen rendering, resize/input/signal/close 기반이 될 terminal session core를 provider-specific Claude/OpenCode 처리와 분리한다. 검증: `agent-task/archive/2026/06/m-architecture-refactor-foundation/05+04_terminal_core/complete.log`
- [x] [router-default] Node adapter registry가 mock 기본값으로 오류를 숨기지 않도록 production 실행 경로의 empty adapter 처리 정책을 명시하고 적용한다.
- [x] [vllm-surface] vLLM adapter skeleton을 명확히 experimental/disabled로 낮추거나 실행 가능한 streaming adapter로 승격한다.

### Epic: [cp-client] Control Plane and Client Boundary

Control Plane과 Flutter Client가 multi-edge 운영면으로 커질 때 선형 지연과 상태 결합이 커지지 않게 한다.

- [x] [cp-api-split] `apps/control-plane/cmd/control-plane/main.go`의 server lifecycle, HTTP handler, DTO conversion, Edge command/fleet orchestration을 분리한다. 검증: `agent-task/archive/2026/06/m-architecture-refactor-foundation/06_cp_api_split/complete.log`
- [x] [fleet-polling] `/fleet/status`와 fleet command 호출을 bounded concurrency, cache, timeout 정책으로 정리한다. 검증: `agent-task/archive/2026/06/m-architecture-refactor-foundation/07+06_fleet_polling/complete.log`
- [x] [client-state-split] Flutter client의 bootstrap, status state, DTO, repository, panel widget 경계를 분리하고 Firebase/Mattermost 같은 외부 통합은 선택적으로 초기화되게 한다. 검증: `agent-task/archive/2026/06/m-architecture-refactor-foundation/08_client_state_split/complete.log`

### Epic: [contract-hygiene] Contract and Repository Hygiene

공개 계약과 tracked 예시 파일이 실제 운영 원칙과 어긋나지 않게 정리한다.

- [x] [status-config-summary] Control Plane status contract에서 full `NodeConfigPayload` 노출 여지를 제거하거나 summary-only DTO로 고정한다. 검증: `go test -count=1 ./apps/control-plane/... ./packages/go/... ./proto/gen/...`
- [x] [proto-legacy] legacy scheduling/node registration proto placeholder를 deprecated/reserved/remove 중 하나로 정리하고 생성 코드와 call-site를 맞춘다. 검증: `agent-task/archive/2026/06/m-architecture-refactor-foundation/09_proto_legacy_contract/complete.log`
- [x] [sample-config] tracked `configs/*.yaml`에서 로컬 IP, host명, token, 위험한 bypass flag, 개인 경로를 제거하고 안전한 example/default 기준으로 재정리한다. 검증: `go test -count=1 ./apps/edge/cmd/edge ./apps/node/cmd/node`
- [x] [git-artifacts] tracked Flutter build artifact를 제거하고 package build 산출물이 다시 추적되지 않도록 ignore 규칙을 보강한다. 검증: `git ls-files | rg --sort path 'packages/flutter/iop_console/build|(^|/)build/.*(cache|unit_test_assets|native_assets|\.dill|\.otf|\.frag|NOTICES)'`

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-06-07
- 완료 근거: `edge-boundary`, `node-runtime`, `cp-client`, `contract-hygiene`의 모든 기능 Task가 완료 근거와 함께 `[x]` 상태다. 마지막 남은 `proto-legacy`는 `agent-task/archive/2026/06/m-architecture-refactor-foundation/09_proto_legacy_contract/complete.log`의 `Roadmap Completion` 근거로 완료 처리했다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 사용자 요청으로 Milestone 종료를 승인하고 archive 이동을 반영했다.

## 범위 제외

- 원격 터미널 브리지 open/input/output/resize/signal/close 기능 구현
- 새로운 terminal transport(SSH/WinRM/serial) 구현
- OpenAI Responses API, A2A streaming, provider 품질 최적화 같은 신규 제품 기능
- 정책/audit 상세 schema 확정
- 완료된 archive 문서 재포맷

## 작업 컨텍스트

- 관련 경로: `apps/edge`, `apps/node`, `apps/control-plane`, `apps/client`, `packages/flutter/iop_console`, `proto/iop`, `configs`, `.gitignore`
- 표준선(선택): Control Plane은 Edge를 통해 관찰/제어하고, Edge는 Node 실행 그룹 상태를 소유하며, Node는 adapter execution과 terminal transport 실행자 역할을 유지한다. OpenAI-compatible/A2A 표면은 IOP native terminal 제어를 흡수하지 않는다.
- 선행 작업: 설계 부채 색인 리뷰
- 후속 작업: 원격 터미널 브리지 POC
- 최근 완료 작업: `agent-task/archive/2026/06/m-architecture-refactor-foundation/06_cp_api_split/complete.log`, `agent-task/archive/2026/06/m-architecture-refactor-foundation/07+06_fleet_polling/complete.log`, `agent-task/archive/2026/06/m-architecture-refactor-foundation/08_client_state_split/complete.log`, `agent-task/archive/2026/06/m-architecture-refactor-foundation/09_proto_legacy_contract/complete.log`
- active plan: 없음
- 확인 필요: 없음
- 잔여 리스크 처리: 완료 후보를 되돌릴 수준의 결함은 아니지만 원격 터미널 브리지 POC 전에 고정해야 할 Client HTTP lifecycle, Edge run surface, Node terminal core, typed adapter config 리스크를 `agent-roadmap/phase/automation-runtime-bridge/milestones/bridge-boundary-hardening.md` 후속 Milestone으로 승격했다.