<!-- task=m-flutter-operator-console/01_ux_scope_gate plan=0 tag=UX_SCOPE -->

# Plan - UX_SCOPE

## 구현 에이전트 지시

이 파일은 `m-flutter-operator-console/01_ux_scope_gate` 구현 계약이다. 구현 에이전트는 아래 체크리스트를 수행하고 검증 출력까지 `CODE_REVIEW-cloud-G07.md`의 구현 에이전트 소유 섹션에 기록한 뒤 active 파일을 유지한 채 리뷰를 요청한다. 사용자 결정, 사용자 소유 외부 환경, 범위 충돌이 있으면 review stub의 `사용자 리뷰 요청` 섹션을 채우고 중단한다. 재실행 가능한 검증 증거 공백은 사용자 리뷰 요청이 아니다.

## 배경

현재 Milestone은 실화면 구현 전에 operator console의 의미와 구현 gate를 고정하는 작업이다. 사용자는 화면 구현을 최대한 늦추고, wireframe 없이 agent가 임의로 dashboard depth를 확정하지 않기를 요청했다. 이 계획은 작은 정의성 작업을 먼저 완료해 후속 headless 검증 계획의 경계를 만든다.

## 사용자 리뷰 요청 흐름

구현 중 사용자만 결정할 수 있는 화면 형태, scope 확대, wireframe 승인 조건 변경이 필요하면 `CODE_REVIEW-cloud-G07.md`의 `사용자 리뷰 요청` 섹션에 정확한 결정, 근거, 재개 조건을 기록한다. code-review만 `USER_REVIEW.md` 작성 여부를 판단한다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md`
- Task ids:
  - `scope`: Operator console이 terminal UI가 아니라 dashboard/control surface임을 정의하고 MVP 범위와 비범위를 정리한다.
  - `boundary`: Riverpod/go_router app shell, feature-first 구조, `AltSocketClient`, generated/mapped contracts의 결합 기준을 정리한다.
  - `wireframe-gate`: 후속 `Flutter Operator Console MVP`의 구현 잠금 해제 조건을 화면 wireframe 준비/승인 여부로 정리한다.
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-ops/skills/common/plan/SKILL.md`
- `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`
- `agent-ops/rules/project/rules.md`
- `agent-test/local/rules.md`
- `.gitignore`
- `agent-roadmap/current.md`
- `agent-roadmap/phase/operator-surface/PHASE.md`
- `agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md`
- `agent-roadmap/phase/operator-surface/milestones/flutter-operator-console-mvp.md`

### 테스트 환경 규칙

- 선택한 test_env: `local`.
- `agent-test/local/rules.md`는 존재하며 읽었다.
- 규칙상 로컬 테스트/검증은 금지이고 기본 테스트 환경은 원격이다.
- 이 작업은 roadmap 문서 변경이라 domain smoke profile은 매칭하지 않았다.
- 검증은 구현 에이전트가 원격 또는 cloud 실행 환경에서 `git diff --check`와 deterministic `rg --sort path`로 수행한다.
- agent-test 규칙은 존재하므로 `create-test`는 필요하지 않다.

### 테스트 커버리지 공백

- 런타임 동작 변경 없음. 기존 unit/integration test 커버리지는 영향받지 않는다.
- 문서 gate 누락은 테스트가 아니라 roadmap/code-review 검증으로 확인한다.

### 심볼 참조

- none. 코드 symbol rename/remove 없음.

### 분할 판단

- split decision policy를 계획 작성 전에 평가했다.
- 공유 task group: `agent-task/m-flutter-operator-console/`.
- `01_ux_scope_gate`: scope, boundary, wireframe gate를 먼저 정의한다. 의존 없음.
- `02+01_headless_validation`: headless scenario, state policy, validation handoff를 정리한다. `01_ux_scope_gate` 완료가 선행 조건이다.
- 분할 이유: scope/gate 결정 없이 headless scenario를 확정하면 후속 Milestone 범위가 흔들린다.

### 범위 결정 근거

- `apps/client/**`, `services/api/**`, `services/worker/**` 코드는 수정하지 않는다. 현재 작업은 실화면 구현과 runtime behavior 변경 전 문서 gate 정리다.
- `agent-roadmap/phase/operator-surface/milestones/operator-headless-workflow-validation.md`의 세부 시나리오는 02번 계획에서 다룬다.
- wireframe 자체 작성은 제외한다. 이 작업은 wireframe 준비/승인 조건만 고정한다.

### 빌드 등급

- build lane: `cloud`, grade: `G07`.
- review lane: `cloud`, grade: `G07`.
- 근거: UI/운영 경계 판단이 포함되고 로컬 검증이 금지되어 원격 증거 기록이 필요하다.

## 구현 체크리스트

- [ ] `flutter-operator-console.md`에서 operator console의 제품 의미, MVP 범위, 비범위를 concise하게 고정하고 `[scope]` 완료 조건을 충족한다.
- [ ] `flutter-operator-console.md`에서 Riverpod/go_router, feature-first 구조, `AltSocketClient`, generated/mapped contracts 결합 기준을 정리하고 `[boundary]` 완료 조건을 충족한다.
- [ ] `flutter-operator-console.md`와 `flutter-operator-console-mvp.md`에서 wireframe 준비/사용자 승인을 후속 화면 구현 잠금 해제 조건으로 명확히 맞추고 `[wireframe-gate]` 완료 조건을 충족한다.
- [ ] 원격 또는 cloud 실행 환경에서 최종 검증 명령을 실행하고 실제 stdout/stderr를 review stub에 기록한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## [UX_SCOPE-1] Scope And Non-Scope

### 문제

`agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md:37`은 console이 dashboard/control surface라고 쓰지만, 완료 산출물이 어디에 남는지와 실화면으로 오해하지 않을 비범위가 충분히 고정되어 있지 않다.

Before:

```markdown
37 - [ ] [scope] Operator console이 terminal UI가 아니라 dashboard/control surface임을 정의하고 MVP 범위와 비범위를 정리한다.
```

### 해결 방법

Milestone의 `범위`, `범위 제외`, `작업 컨텍스트`를 보강하고 `[scope]`를 완료 처리한다. 비범위는 실제 Flutter production 화면, wireframe 없는 dashboard depth 확정, chart/form layout 확정으로 제한한다.

After 방향:

```markdown
- [x] [scope] Operator console이 terminal UI가 아니라 dashboard/control surface임을 정의하고 MVP 범위와 비범위를 정리한다.
```

### 수정 파일 및 체크리스트

- [ ] `agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md`의 `범위`와 `범위 제외`를 보강한다.
- [ ] `[scope]` task를 `[x]`로 바꾼다.

### 테스트 작성

테스트 작성 안 함. 코드 동작 변경이 아닌 roadmap 문서 정리다.

### 중간 검증

```bash
rg --sort path -n "\\[x\\] \\[scope\\]|dashboard/control surface|terminal UI|실제 Flutter production 화면" agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md
```

기대 결과: scope 체크와 console 의미/비범위 문구가 모두 검색된다.

## [UX_SCOPE-2] Boundary And Wireframe Gate

### 문제

`agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md:40-41`과 `agent-roadmap/phase/operator-surface/milestones/flutter-operator-console-mvp.md:18-21`은 boundary와 wireframe 조건을 언급하지만, 현재 Milestone 완료와 후속 MVP 잠금 조건의 연결이 review evidence로 복사될 만큼 명확하지 않다.

Before:

```markdown
40 - [ ] [boundary] Riverpod/go_router app shell, feature-first 구조, `AltSocketClient`, generated/mapped contracts의 결합 기준을 정리한다.
41 - [ ] [wireframe-gate] 후속 `Flutter Operator Console MVP`의 구현 잠금 해제 조건을 화면 wireframe 준비/승인 여부로 정리한다.
```

### 해결 방법

현재 Milestone에는 app shell과 provider boundary 원칙을 짧게 고정하고, MVP Milestone의 `구현 잠금`과 `확인 필요` 문구가 wireframe 준비/사용자 승인 없이는 해제될 수 없도록 맞춘다.

After 방향:

```markdown
- [x] [boundary] Riverpod/go_router app shell, feature-first 구조, `AltSocketClient`, generated/mapped contracts의 결합 기준을 정리한다.
- [x] [wireframe-gate] 후속 `Flutter Operator Console MVP`의 구현 잠금 해제 조건을 화면 wireframe 준비/승인 여부로 정리한다.
```

### 수정 파일 및 체크리스트

- [ ] `agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md`의 `작업 컨텍스트`에 boundary 원칙을 남긴다.
- [ ] `agent-roadmap/phase/operator-surface/milestones/flutter-operator-console-mvp.md`의 `구현 잠금`과 `확인 필요`가 wireframe 승인 gate와 일치하는지 확인하고 필요 시 보강한다.
- [ ] `[boundary]`, `[wireframe-gate]` task를 `[x]`로 바꾼다.

### 테스트 작성

테스트 작성 안 함. 코드 동작 변경이 아닌 roadmap gate 정리다.

### 중간 검증

```bash
rg --sort path -n "\\[x\\] \\[(boundary|wireframe-gate)\\]|go_router|Riverpod|AltSocketClient|wireframe|구현 잠금" agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md agent-roadmap/phase/operator-surface/milestones/flutter-operator-console-mvp.md
```

기대 결과: boundary task, wireframe task, MVP 구현 잠금 조건이 모두 검색된다.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md` | UX_SCOPE-1, UX_SCOPE-2 |
| `agent-roadmap/phase/operator-surface/milestones/flutter-operator-console-mvp.md` | UX_SCOPE-2 |

## 최종 검증

```bash
git diff --check -- agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md agent-roadmap/phase/operator-surface/milestones/flutter-operator-console-mvp.md
rg --sort path -n "\\[x\\] \\[(scope|boundary|wireframe-gate)\\]|dashboard/control surface|terminal UI|go_router|Riverpod|AltSocketClient|wireframe|구현 잠금" agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md agent-roadmap/phase/operator-surface/milestones/flutter-operator-console-mvp.md
```

모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
