alt/agent-task/m-flutter-operator-console/01_ux_scope_gate/PLAN-cloud-G07.md

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:

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

해결 방법

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

After 방향:

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

수정 파일 및 체크리스트

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

테스트 작성

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

중간 검증

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:

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 방향:

- [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 정리다.

중간 검증

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

최종 검증

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의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.