From 3b1be95e625cfd110a42d2ee0d12653dc35f7579 Mon Sep 17 00:00:00 2001 From: toki Date: Sun, 31 May 2026 06:10:30 +0900 Subject: [PATCH] feat: operator console milestone decomposition & tracking docs - decompose flutter-operator-console into sub-milestones (flutter-operator-console-mvp, operator-headless-workflow-validation, flutter-push-notification-boundary) - archive deprecated api-centered-proto-socket-rail milestone - update ROADMAP.md, current.md, operator-surface PHASE.md - add agent-task/m-flutter-operator-console with PLAN & CODE_REVIEW docs - update project rules --- agent-ops/rules/project/rules.md | 8 + agent-roadmap/ROADMAP.md | 2 +- .../api-centered-proto-socket-rail.md | 32 +-- agent-roadmap/current.md | 6 +- agent-roadmap/phase/operator-surface/PHASE.md | 26 ++- .../flutter-operator-console-mvp.md | 72 +++++++ .../milestones/flutter-operator-console.md | 62 +++--- .../flutter-push-notification-boundary.md | 69 +++++++ .../operator-headless-workflow-validation.md | 67 ++++++ .../01_ux_scope_gate/CODE_REVIEW-cloud-G07.md | 136 +++++++++++++ .../01_ux_scope_gate/PLAN-cloud-G07.md | 181 +++++++++++++++++ .../CODE_REVIEW-cloud-G07.md | 147 ++++++++++++++ .../PLAN-cloud-G07.md | 190 ++++++++++++++++++ 13 files changed, 937 insertions(+), 61 deletions(-) rename agent-roadmap/{ => archive}/phase/operator-surface/milestones/api-centered-proto-socket-rail.md (69%) create mode 100644 agent-roadmap/phase/operator-surface/milestones/flutter-operator-console-mvp.md create mode 100644 agent-roadmap/phase/operator-surface/milestones/flutter-push-notification-boundary.md create mode 100644 agent-roadmap/phase/operator-surface/milestones/operator-headless-workflow-validation.md create mode 100644 agent-task/m-flutter-operator-console/01_ux_scope_gate/CODE_REVIEW-cloud-G07.md create mode 100644 agent-task/m-flutter-operator-console/01_ux_scope_gate/PLAN-cloud-G07.md create mode 100644 agent-task/m-flutter-operator-console/02+01_headless_validation/CODE_REVIEW-cloud-G07.md create mode 100644 agent-task/m-flutter-operator-console/02+01_headless_validation/PLAN-cloud-G07.md diff --git a/agent-ops/rules/project/rules.md b/agent-ops/rules/project/rules.md index 5c37cb5..7887dbf 100644 --- a/agent-ops/rules/project/rules.md +++ b/agent-ops/rules/project/rules.md @@ -54,6 +54,14 @@ ALT는 개인 quant system workspace다. Go 서비스와 도구는 루트 `go.wo - Flutter client는 `lib/src/app`에 앱 shell/router를 두고, 기능 화면은 `lib/src/features/feature-name/presentation` 패턴 아래에 둔다. - runtime configuration은 환경변수를 우선하고 로컬 개발 fallback을 둔다. +## 운영 UI 구현 게이트 + +- ALT 운영 기능은 먼저 화면 없이 CLI, terminal output, YAML scenario, log, test fixture처럼 headless 경로로 구성과 결과를 검증한다. +- Flutter 실화면 구현은 해당 기능의 API/worker/domain 경계와 headless 검증 경로가 먼저 안정화된 뒤에 시작한다. +- 운영 화면 구현 Milestone은 화면 wireframe 또는 동등한 화면 정의 산출물이 준비되고 사용자 승인 기준이 문서화되어야 `구현 잠금`을 해제할 수 있다. +- wireframe 없이 agent가 임의로 dashboard depth, navigation, card layout, chart, form 흐름을 확정하지 않는다. +- Flutter 작업 중 화면 구현이 아닌 app shell, provider boundary, generated contract 연결, headless smoke support는 위 게이트를 깨는 실화면 구현으로 보지 않는다. + ## 도메인 매핑 | 경로 패턴 | 도메인 | rules.md | diff --git a/agent-roadmap/ROADMAP.md b/agent-roadmap/ROADMAP.md index ed1f387..e54469d 100644 --- a/agent-roadmap/ROADMAP.md +++ b/agent-roadmap/ROADMAP.md @@ -19,7 +19,7 @@ ALT는 개인용 quant system workspace로, 한국장 일봉 MVP에서 시작해 - [진행중] 백테스트 루프 - 경로: `agent-roadmap/phase/backtest-loop/PHASE.md` - 요약: 일봉 기반 strategy execution, backtest lifecycle, result persistence, repeatable verification을 만든다. -- [계획] 운영 표면 +- [진행중] 운영 표면 - 경로: `agent-roadmap/phase/operator-surface/PHASE.md` - 요약: Flutter client에서 백테스트와 market data 상태를 조회하고 실행할 수 있는 operator console을 만든다. client integration 복제 작업은 별도 프로젝트 산출물로 다룬다. - [계획] 거래 확장 diff --git a/agent-roadmap/phase/operator-surface/milestones/api-centered-proto-socket-rail.md b/agent-roadmap/archive/phase/operator-surface/milestones/api-centered-proto-socket-rail.md similarity index 69% rename from agent-roadmap/phase/operator-surface/milestones/api-centered-proto-socket-rail.md rename to agent-roadmap/archive/phase/operator-surface/milestones/api-centered-proto-socket-rail.md index 2931667..d78ca89 100644 --- a/agent-roadmap/phase/operator-surface/milestones/api-centered-proto-socket-rail.md +++ b/agent-roadmap/archive/phase/operator-surface/milestones/api-centered-proto-socket-rail.md @@ -11,7 +11,7 @@ ALT 내부 runtime boundary의 application message 통신을 API 서버 중심 ## 상태 -[계획] +[완료] ## 구현 잠금 @@ -35,23 +35,25 @@ ALT 내부 runtime boundary의 application message 통신을 API 서버 중심 API 서버를 중심으로 client, worker, 후속 sidecar가 같은 proto-socket 규칙으로 붙을 수 있는 내부 통신 기반을 만든다. - [x] [topology] `client -> api -> worker`를 기본 topology로 고정하고 client가 worker를 직접 제어하지 않도록 경계를 문서와 코드 구조에 반영한다. -- [ ] [api-hub] `services/api`가 operator-facing command/query facade와 proto-socket handler registry를 가진다. 검증: API socket handler 테스트가 hello 외 주요 command/query handler 등록과 request-response 경로를 검증한다. -- [ ] [client-api] Flutter client의 ALT 내부 통신은 `AltSocketClient`와 generated/mapped contracts를 통해 API에만 연결된다. 검증: Flutter socket integration 테스트가 연결, hello, 주요 request wrapper를 검증한다. -- [ ] [api-worker] API와 worker 사이의 내부 command/query/event 통신을 proto-socket으로 연결한다. 검증: Go integration 또는 smoke 테스트가 API에서 worker rail로 hello와 대표 command/query를 왕복한다. -- [ ] [contracts] client-api와 api-worker가 공유할 ALT protobuf message, parser map, codegen 경로를 정리한다. 검증: `bin/contracts-check`와 parser map 테스트가 통과한다. -- [ ] [backtest-rail] backtest run list/detail/result/compare/start 요청이 API를 통해 worker/store 실행 경계로 이어진다. 검증: client가 worker endpoint를 직접 호출하지 않고 API proto-socket 요청만으로 대표 backtest flow를 확인한다. -- [ ] [market-rail] market instrument/bar/status 조회 요청이 API proto-socket handler에서 worker-side read boundary로 이어진다. 검증: API proto-socket 요청으로 market data 대표 조회가 가능하다. +- [x] [api-hub] `services/api`가 operator-facing command/query facade와 proto-socket handler registry를 가진다. 검증: API socket handler 테스트가 hello 외 주요 command/query handler 등록과 request-response 경로를 검증한다. +- [x] [client-api] Flutter client의 ALT 내부 통신은 `AltSocketClient`와 generated/mapped contracts를 통해 API에만 연결된다. 검증: Flutter socket integration 테스트가 연결, hello, 주요 request wrapper를 검증한다. +- [x] [api-worker] API와 worker 사이의 내부 command/query/event 통신을 proto-socket으로 연결한다. 검증: Go integration 또는 smoke 테스트가 API에서 worker rail로 hello와 대표 command/query를 왕복한다. +- [x] [contracts] client-api와 api-worker가 공유할 ALT protobuf message, parser map, codegen 경로를 정리한다. 검증: `bin/contracts-check`와 parser map 테스트가 통과한다. +- [x] [backtest-rail] backtest run list/detail/result/compare/start 요청이 API를 통해 worker/store 실행 경계로 이어진다. 검증: client가 worker endpoint를 직접 호출하지 않고 API proto-socket 요청만으로 대표 backtest flow를 확인한다. +- [x] [market-rail] market instrument/bar/status 조회 요청이 API proto-socket handler에서 worker-side read boundary로 이어진다. 검증: API proto-socket 요청으로 market data 대표 조회가 가능하다. - [x] [exceptions] PostgreSQL, Redis, filesystem, 외부 provider, Nexo/Mattermost/Firebase/platform channel은 adapter 예외로 유지하고 ALT-owned runtime message protocol로 확장하지 않는다. 검증: 새 ALT-owned HTTP/gRPC/direct-worker path가 추가되지 않았음을 코드 검색 또는 리뷰로 확인한다. ## 완료 리뷰 -- 상태: 없음 -- 요청일: 없음 -- 완료 근거: 아직 기능 Task와 검증이 충족되지 않았다. +- 상태: 승인됨 +- 요청일: 2026-05-31 +- 완료 근거: `agent-task/archive/2026/05/m-api-centered-proto-socket-rail/01_contracts_api_registry/complete.log`에서 API handler registry, parser map, `bin/contracts-check`, `go test ./services/api/...` PASS를 확인했다. +- 완료 근거: `02+01_worker_socket_rail`, `03+01_client_api_wrappers`, `04+02_backtest_rail`, `05+02_market_rail` 완료 로그에서 worker rail, Flutter API wrappers, backtest rail, market rail의 최종 PASS와 API/worker/client/contracts 검증 통과를 확인했다. +- 완료 근거: 기존 `topology`, `exceptions` 완료와 합쳐 모든 기능 Task와 Task 내 검증 근거가 충족된 완료 후보 상태다. - 리뷰 필요: - - [ ] 사용자가 완료 결과를 확인했다 - - [ ] archive 이동을 승인했다 -- 리뷰 코멘트: 없음 + - [x] 사용자가 완료 결과를 확인했다 + - [x] archive 이동을 승인했다 +- 리뷰 코멘트: 2026-05-31 사용자 요청으로 완료 승인 후 archive 이동했다. ## 범위 제외 @@ -66,8 +68,8 @@ API 서버를 중심으로 client, worker, 후속 sidecar가 같은 proto-socket - 관련 경로: `services/api/`, `services/worker/`, `apps/client/`, `packages/contracts/` - 표준선(선택): ALT-owned runtime boundary의 application message 통신은 proto-socket과 ALT protobuf payload를 기본값으로 삼고, `services/api`를 얇은 control plane으로 둔다. -- 즉시 처리: `topology`와 `exceptions`는 프로젝트/도메인 rule에 반영했고, 코드 검색으로 client direct-worker path와 새 ALT-owned HTTP/gRPC path가 없음을 확인했다. -- 대형 작업 plan: `agent-task/m-api-centered-proto-socket-rail/` +- 즉시 처리: `topology`, `exceptions`, `api-hub`, `client-api`, `api-worker`, `contracts`, `backtest-rail`, `market-rail`을 완료 로그와 검증 근거에 맞춰 반영했다. +- 대형 작업 plan: `agent-task/m-api-centered-proto-socket-rail/` 완료 로그는 `agent-task/archive/2026/05/m-api-centered-proto-socket-rail/`에 있다. - 선행 작업: Nexo 최신화 및 테스트 완료, Socket Session Loop, Backtest Analysis Surface - 후속 작업: Flutter Operator Console - 확인 필요: 없음 diff --git a/agent-roadmap/current.md b/agent-roadmap/current.md index 24dd290..e6adf38 100644 --- a/agent-roadmap/current.md +++ b/agent-roadmap/current.md @@ -2,14 +2,14 @@ ## 활성 Phase -- [계획] 운영 표면 +- [진행중] 운영 표면 - 경로: `agent-roadmap/phase/operator-surface/PHASE.md` ## 활성 Milestone -- [계획] API-Centered Proto-Socket Rail +- [계획] Flutter Operator Console UX Plan - Phase: `agent-roadmap/phase/operator-surface/PHASE.md` - - 경로: `agent-roadmap/phase/operator-surface/milestones/api-centered-proto-socket-rail.md` + - 경로: `agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md` ## 선택 규칙 diff --git a/agent-roadmap/phase/operator-surface/PHASE.md b/agent-roadmap/phase/operator-surface/PHASE.md index 626c7ec..abe4dad 100644 --- a/agent-roadmap/phase/operator-surface/PHASE.md +++ b/agent-roadmap/phase/operator-surface/PHASE.md @@ -2,23 +2,32 @@ ## 상태 -[계획] +[진행중] ## 목표 -Flutter client를 ALT의 공식 operator surface로 삼아 market data 상태와 backtest 실행 및 결과를 조회할 수 있게 한다. 먼저 API 서버 중심의 proto-socket 내부 통신 rail을 정리하고, client integration 복제와 push host integration 정리는 별도 프로젝트 산출물로 받는다. 이 Phase에서는 web/mobile/desktop 단일 UI 표면을 유지하면서 API와 generated contract 기준을 맞춘다. +Flutter client를 ALT의 공식 operator surface로 삼아 market data 상태와 backtest 실행 및 결과를 조회할 수 있게 한다. 먼저 API 서버 중심의 proto-socket 내부 통신 rail을 정리하고, 화면 없이 CLI/YAML/log/test fixture로 운영 흐름을 검증한 뒤 wireframe이 준비된 경우에만 Flutter 실화면 구현으로 넘어간다. 이 Phase에서는 web/mobile/desktop 단일 UI 표면을 유지하면서 API와 generated contract 기준을 맞추고, push notification은 별도 후속 Milestone으로 분리한다. ## Milestone 흐름 완료된 Milestone은 archive 경로를 가리키고, 검토중, 진행중, 계획 또는 보류 Milestone은 이 Phase 하위 `milestones/` 경로를 가리킨다. 완료, 검토중, 진행중, 계획 순서로 두어 아래로 갈수록 미래 작업에 가까워지게 정렬한다. -- [계획] API-Centered Proto-Socket Rail - - 경로: `agent-roadmap/phase/operator-surface/milestones/api-centered-proto-socket-rail.md` +- [완료] API-Centered Proto-Socket Rail + - 경로: `agent-roadmap/archive/phase/operator-surface/milestones/api-centered-proto-socket-rail.md` - 요약: API 서버를 control plane으로 두고 client-api, api-worker 내부 통신을 proto-socket과 ALT protobuf contracts로 통일한다. -- [계획] Flutter Operator Console +- [계획] Flutter Operator Console UX Plan - 경로: `agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md` - - 요약: Flutter client에서 market data, backtest run, result를 조회하고 실행 요청할 수 있는 운영 화면을 만든다. + - 요약: terminal형 콘솔이 아니라 dashboard/control surface라는 제품 의미를 정하되, 실화면 구현 전 headless 검증 우선 원칙과 wireframe gate를 먼저 정의한다. +- [계획] Operator Headless Workflow Validation + - 경로: `agent-roadmap/phase/operator-surface/milestones/operator-headless-workflow-validation.md` + - 요약: Flutter 화면 없이 terminal/YAML 기반 운영 시나리오로 market data와 backtest 조회/실행 결과를 먼저 검증한다. +- [보류] Flutter Operator Console MVP + - 경로: `agent-roadmap/phase/operator-surface/milestones/flutter-operator-console-mvp.md` + - 요약: headless 운영 검증과 화면 wireframe 승인 뒤에만 Flutter에서 market data, backtest run, result를 조회하고 실행 요청할 수 있는 MVP 화면을 구현한다. +- [스케치] Flutter Push Notification Boundary + - 경로: `agent-roadmap/phase/operator-surface/milestones/flutter-push-notification-boundary.md` + - 요약: push notification을 operator console 본작업에서 분리하고, Firebase/platform channel 등 외부 protocol 경계를 후속 작업으로 정리한다. ## Phase 경계 @@ -26,4 +35,7 @@ Flutter client를 ALT의 공식 operator surface로 삼아 market data 상태와 - 별도 TypeScript web app, 고급 charting 전체, mobile app store 배포 설정은 제외한다. - API 서버를 operator-facing control plane으로 두고, client와 worker는 API를 기준으로 proto-socket rail에 연결한다. - UI는 generated/mapped contracts와 proto-socket client layer를 기준으로 API와 통신한다. -- client skeleton, bootstrap convention, push host integration 복제는 이 프로젝트의 별도 Milestone으로 두지 않고 외부 프로젝트 산출물로 추후 반영한다. +- 운영 기능은 화면 구현 전에 CLI, terminal output, YAML scenario, log, test fixture 같은 headless 경로로 구성과 결과를 먼저 검증한다. +- Flutter 실화면 구현은 headless 검증 완료와 wireframe 준비/승인을 구현 잠금 해제 조건으로 둔다. +- client skeleton과 bootstrap convention은 외부 client integration 프로젝트 산출물을 추후 반영하되, Riverpod/go_router와 API client boundary는 이 Phase의 Flutter 표면 안에서 명시한다. +- push notification은 현재 operator console 범위에서 제외하고 `Flutter Push Notification Boundary` Milestone으로 분리한다. diff --git a/agent-roadmap/phase/operator-surface/milestones/flutter-operator-console-mvp.md b/agent-roadmap/phase/operator-surface/milestones/flutter-operator-console-mvp.md new file mode 100644 index 0000000..c689117 --- /dev/null +++ b/agent-roadmap/phase/operator-surface/milestones/flutter-operator-console-mvp.md @@ -0,0 +1,72 @@ +# Milestone: Flutter Operator Console MVP + +## 위치 + +- Roadmap: `agent-roadmap/ROADMAP.md` +- Phase: `agent-roadmap/phase/operator-surface/PHASE.md` + +## 목표 + +승인된 `Flutter Operator Console UX Plan`과 `Operator Headless Workflow Validation` 결과를 기준으로 Flutter client에 operator dashboard MVP를 구현한다. 화면은 headless 검증으로 확인된 운영 흐름과 준비된 wireframe을 따라가며, terminal UI나 고급 charting이 아니라 반복 운영에 필요한 조회/실행 표면을 우선한다. + +## 상태 + +[보류] + +## 구현 잠금 + +- 상태: 잠금 +- 결정 필요: 아래 체크리스트 + - [ ] `Operator Headless Workflow Validation`이 완료되어 화면 없이 대표 운영 흐름을 검증했다. + - [ ] 화면 wireframe 또는 동등한 화면 정의 산출물이 준비되었고 사용자가 승인했다. + +## 범위 + +- Flutter feature-first 화면 구조 +- socket connection state 표시 +- backtest run list/detail/result 조회 +- start backtest request form과 unavailable/error 응답 표시 +- market data import/status 조회 +- responsive web/mobile/desktop navigation + +## 기능 + +### Epic: [operator-mvp] Flutter operator console MVP + +headless 검증과 wireframe 승인을 거친 운영 흐름만 실제 Flutter 화면과 provider 경계로 옮긴다. + +- [ ] [connect-state] client가 API socket 연결 상태를 표시한다. 검증: Flutter test가 연결/끊김 상태 표시를 검증한다. +- [ ] [backtest-list] backtest run 목록을 조회하고 표시한다. 검증: generated/mapped contracts 기반 repository/provider test가 목록 응답을 화면 model로 전달한다. +- [ ] [backtest-detail] backtest run detail과 result를 표시한다. 검증: detail/result 상태별 widget test가 통과한다. +- [ ] [start-run] operator가 backtest 실행을 요청하고 unavailable/error 응답을 이해 가능한 상태로 본다. 검증: request form과 typed error response test가 통과한다. +- [ ] [market-status] market data import/status를 조회할 수 있다. 검증: market status provider/widget test가 통과한다. +- [ ] [responsive-nav] web/mobile/desktop target에서 기본 navigation이 작동한다. 검증: 주요 viewport별 navigation smoke 또는 widget test가 통과한다. +- [ ] [repo-checks] `bin/test`, `bin/lint`, `bin/build`가 통과한다. + +## 완료 리뷰 + +- 상태: 없음 +- 요청일: 없음 +- 완료 근거: 아직 기능 Task와 검증이 충족되지 않았다. +- 리뷰 필요: + - [ ] 사용자가 완료 결과를 확인했다 + - [ ] archive 이동을 승인했다 +- 리뷰 코멘트: 없음 + +## 범위 제외 + +- UI 기획 없이 임의로 화면 깊이를 확정하는 작업 +- headless 검증 없이 dashboard layout, chart, form 흐름을 먼저 구현하는 작업 +- wireframe 승인 없이 실화면을 구현하는 작업 +- 별도 TypeScript web app +- 고급 charting 전체 +- push notification +- mobile app store 배포 설정 + +## 작업 컨텍스트 + +- 관련 경로: `apps/client/`, `packages/contracts/`, `services/api/` +- 표준선(선택): `go_router`는 화면 이동/URL 구조, Riverpod은 API client/socket state/feature state 주입을 담당한다. UI는 `AltSocketClient` provider와 generated/mapped contracts boundary를 통해 API만 바라본다. +- 선행 작업: Flutter Operator Console UX Plan, Operator Headless Workflow Validation, wireframe 승인 +- 후속 작업: Flutter Push Notification Boundary +- 확인 필요: headless 검증 완료와 wireframe 승인 전에는 구현 잠금을 유지한다. diff --git a/agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md b/agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md index 002e651..fa8b84a 100644 --- a/agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md +++ b/agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md @@ -1,4 +1,4 @@ -# Milestone: Flutter Operator Console +# Milestone: Flutter Operator Console UX Plan ## 위치 @@ -7,7 +7,7 @@ ## 목표 -Flutter client를 ALT의 공식 UI client로 삼아 market data 상태, backtest run, result를 조회하고 실행 요청할 수 있는 operator console을 만든다. 별도 TypeScript web app은 기본 경로로 두지 않는다. +실제 Flutter 화면 구현에 들어가기 전에 operator console의 의미, headless-first 검증 순서, wireframe gate를 고정한다. 이 Milestone의 console은 terminal UI가 아니라 dashboard/control surface지만, 화면 구현은 terminal/YAML 기반 운영 검증과 wireframe 준비가 끝난 뒤로 미룬다. ## 상태 @@ -15,46 +15,37 @@ Flutter client를 ALT의 공식 UI client로 삼아 market data 상태, backtest ## 구현 잠금 -- 상태: 잠금 -- 결정 필요: 아래 체크리스트 - - [ ] 별도 client integration 프로젝트 산출물 반영 전 operator console 화면 구현을 어디까지 진행할지 결정한다. - - [ ] Riverpod/go_router app shell에 공통 client skeleton과 integration boundary를 결합하는 기준을 확정한다. - - [ ] push notification은 이 milestone 범위 제외로 유지하고 별도 client integration 프로젝트 산출물로 다룰지 확인한다. +- 상태: 해제 +- 결정 필요: 없음 ## 범위 -- Flutter feature-first 화면 구조 -- socket connection state -- backtest run list/detail -- start backtest request form -- market data import/status view -- responsive web/mobile/desktop navigation +- operator console의 제품 의미와 MVP 범위 정의 +- dashboard/control surface가 필요한 이유와 아직 구현하지 않을 화면 범위 정의 +- socket connection, backtest, market data의 headless 검증 시나리오 후보 +- loading/empty/error/unavailable/disconnected 상태 정책 +- 실행 요청 입력, 검증, 실패 응답을 YAML/terminal 결과로 먼저 확인하는 정책 +- Riverpod/go_router app shell과 client integration boundary 기준 +- 화면 MVP로 넘어가기 위한 wireframe 준비/승인 기준 -## 필수 기능 +## 기능 -### Epic: [operator-console] Flutter operator console +### Epic: [ux-plan] Flutter operator console UX plan -market data와 backtest 상태를 조회하고 실행 요청할 수 있는 Flutter 운영 표면을 묶는다. +실화면 구현 전에 operator dashboard가 왜 필요한지, 화면 없이 무엇을 먼저 검증할지, 어떤 조건에서 화면 구현 잠금을 풀지 정의한다. -- [ ] [connect-state] client가 API socket 연결 상태를 표시한다. -- [ ] [backtest-list] backtest run 목록을 조회하고 표시한다. -- [ ] [backtest-detail] backtest run detail과 result를 표시한다. -- [ ] [start-run] operator가 backtest 실행을 요청할 수 있다. -- [ ] [market-status] market data import/status를 조회할 수 있다. -- [ ] [responsive-nav] web/mobile/desktop target에서 기본 navigation이 작동한다. - -## 완료 기준 - -- [ ] Flutter test가 주요 화면 shell과 상태 표시를 검증한다. -- [ ] client는 generated/mapped contracts를 통해 API와 통신한다. -- [ ] presentation widget에 production endpoint 가정이 hard-code되지 않는다. -- [ ] `bin/test`, `bin/lint`, `bin/build`가 통과한다. +- [ ] [scope] Operator console이 terminal UI가 아니라 dashboard/control surface임을 정의하고 MVP 범위와 비범위를 정리한다. +- [ ] [headless-first] 화면 구현 전 CLI, terminal output, YAML scenario, log, test fixture로 검증할 운영 흐름을 정리한다. +- [ ] [state-policy] loading/empty/error/unavailable/disconnected 상태와 operator action 가능/불가 정책을 headless 결과 표현 기준으로 정리한다. +- [ ] [boundary] Riverpod/go_router app shell, feature-first 구조, `AltSocketClient`, generated/mapped contracts의 결합 기준을 정리한다. +- [ ] [wireframe-gate] 후속 `Flutter Operator Console MVP`의 구현 잠금 해제 조건을 화면 wireframe 준비/승인 여부로 정리한다. +- [ ] [validation-handoff] 후속 `Operator Headless Workflow Validation`이 실행할 terminal/YAML 시나리오와 결과 확인 기준을 인수 가능한 형태로 정리한다. ## 완료 리뷰 - 상태: 없음 - 요청일: 없음 -- 완료 근거: 아직 필수 기능과 완료 기준이 충족되지 않았다. +- 완료 근거: 아직 기능 Task가 충족되지 않았다. - 리뷰 필요: - [ ] 사용자가 완료 결과를 확인했다 - [ ] archive 이동을 승인했다 @@ -62,6 +53,8 @@ market data와 backtest 상태를 조회하고 실행 요청할 수 있는 Flutt ## 범위 제외 +- 실제 Flutter production 화면 구현 +- wireframe 없이 dashboard layout, chart, form 흐름을 확정하는 작업 - 별도 TypeScript web app - 고급 charting 전체 - push notification @@ -70,8 +63,7 @@ market data와 backtest 상태를 조회하고 실행 요청할 수 있는 Flutt ## 작업 컨텍스트 - 관련 경로: `apps/client/`, `packages/contracts/`, `services/api/` -- 표준선(선택): Flutter는 feature-first Clean Architecture와 Riverpod을 기본 설계 프레임으로 삼는다. -- 선행 작업: Socket Session Loop, Backtest Analysis Surface -- 외부 산출물: client skeleton, bootstrap convention, push host integration 복제는 별도 client integration 프로젝트 결과를 추후 반영한다. -- 후속 작업: Paper Trading Readiness -- 확인 필요: 구현 잠금의 결정 필요 항목 참고. +- 표준선(선택): 운영 기능은 화면보다 headless 검증을 먼저 만든다. Flutter는 feature-first 구조를 따르고, `go_router`는 화면 이동과 URL 구조, Riverpod은 API client/socket state/feature state 주입을 담당한다. Presentation widget은 production endpoint나 socket path를 직접 알지 않는다. +- 선행 작업: API-Centered Proto-Socket Rail +- 후속 작업: Operator Headless Workflow Validation, Flutter Operator Console MVP, Flutter Push Notification Boundary +- 확인 필요: 없음 diff --git a/agent-roadmap/phase/operator-surface/milestones/flutter-push-notification-boundary.md b/agent-roadmap/phase/operator-surface/milestones/flutter-push-notification-boundary.md new file mode 100644 index 0000000..e7fd4b6 --- /dev/null +++ b/agent-roadmap/phase/operator-surface/milestones/flutter-push-notification-boundary.md @@ -0,0 +1,69 @@ +# Milestone: Flutter Push Notification Boundary + +## 위치 + +- Roadmap: `agent-roadmap/ROADMAP.md` +- Phase: `agent-roadmap/phase/operator-surface/PHASE.md` + +## 목표 + +Operator console 본작업에서 push notification을 분리해 후속 작업으로 보존한다. Firebase, platform channel, push host integration처럼 ALT 외부 protocol과 platform boundary가 필요한 영역을 별도 Milestone에서 정의하고, operator dashboard MVP와 뒤섞이지 않게 한다. + +## 상태 + +[스케치] + +## 승격 조건 + +- [ ] push notification이 필요한 operator event 종류와 우선순위를 정한다. +- [ ] Firebase, platform channel, push host integration 중 사용할 외부/protocol 경계를 정한다. +- [ ] client integration 프로젝트 산출물을 어떤 형태로 반영할지 정한다. +- [ ] MVP 구현 단위와 검증 시나리오를 `기능` Task로 구체화한다. + +## 구현 잠금 + +- 상태: 잠금 +- 결정 필요: 아래 체크리스트 + - [ ] push notification의 첫 사용 사례와 대상 플랫폼을 정한다. + - [ ] 외부 provider/protocol 선택과 운영 책임 경계를 정한다. + +## 범위 + +- push notification 사용 사례와 event taxonomy +- Firebase/platform channel/push host integration boundary +- API/worker event와 client notification surface 연결 방식 +- local/dev 검증 전략 + +## 기능 + +### Epic: [push-boundary] Flutter push notification boundary + +아직 구현 가능한 계획이 아니라, operator console에서 분리된 push notification 경계를 계획 상태로 승격하기 위한 후보 범위를 정리한다. + +- [ ] [event-scope] push 대상 operator event 후보와 제외할 event를 정리한다. +- [ ] [protocol-choice] Firebase/platform channel/push host integration 후보와 책임 경계를 비교한다. +- [ ] [mvp-shape] 첫 구현 Milestone으로 자를 수 있는 MVP 범위와 검증 방식을 정리한다. + +## 완료 리뷰 + +- 상태: 없음 +- 요청일: 없음 +- 완료 근거: 아직 스케치 단계이며 승격 조건이 충족되지 않았다. +- 리뷰 필요: + - [ ] 사용자가 완료 결과를 확인했다 + - [ ] archive 이동을 승인했다 +- 리뷰 코멘트: 없음 + +## 범위 제외 + +- 현재 Flutter Operator Console UX Plan과 MVP 구현 +- Firebase 또는 platform channel 실제 연결 구현 +- production push delivery 운영 + +## 작업 컨텍스트 + +- 관련 경로: `apps/client/`, `services/api/`, `services/worker/` +- 표준선(선택): ALT-owned runtime boundary는 proto-socket/ALT protobuf를 기본으로 유지하고, Firebase/platform channel 같은 외부 protocol은 adapter 경계 안에서만 다룬다. +- 선행 작업: Flutter Operator Console MVP, client integration 프로젝트 산출물 +- 후속 작업: 없음 +- 확인 필요: 승격 조건과 구현 잠금 참고. diff --git a/agent-roadmap/phase/operator-surface/milestones/operator-headless-workflow-validation.md b/agent-roadmap/phase/operator-surface/milestones/operator-headless-workflow-validation.md new file mode 100644 index 0000000..167d773 --- /dev/null +++ b/agent-roadmap/phase/operator-surface/milestones/operator-headless-workflow-validation.md @@ -0,0 +1,67 @@ +# Milestone: Operator Headless Workflow Validation + +## 위치 + +- Roadmap: `agent-roadmap/ROADMAP.md` +- Phase: `agent-roadmap/phase/operator-surface/PHASE.md` + +## 목표 + +Flutter 화면 없이 ALT 운영 흐름을 terminal/YAML/log/test fixture 기반으로 먼저 검증한다. market data와 backtest 조회/실행 경로가 화면 없이도 구성, 실행, 결과 확인이 가능해진 뒤에만 operator dashboard 화면 구현 후보로 넘긴다. + +## 상태 + +[계획] + +## 구현 잠금 + +- 상태: 잠금 +- 결정 필요: 아래 체크리스트 + - [ ] `Flutter Operator Console UX Plan`의 headless-first 시나리오와 결과 확인 기준을 승인한다. + +## 범위 + +- YAML 또는 동등한 파일 기반 operator scenario 정의 +- CLI/terminal entrypoint에서 scenario 실행 또는 조회 +- market data status/import 결과 확인 +- backtest list/detail/result/start 요청 결과 확인 +- unavailable/error/disconnected 결과의 machine-readable 또는 grep 가능한 출력 +- 화면 구현 전 검증 evidence 산출 방식 + +## 기능 + +### Epic: [headless-op] Headless operator workflow validation + +운영 화면을 만들기 전에 같은 API/worker 경계를 화면 없이 검증한다. + +- [ ] [scenario-format] operator scenario를 YAML 또는 동등한 파일 형식으로 표현한다. 검증: 예시 scenario가 parser 또는 dry-run 검증을 통과한다. +- [ ] [terminal-run] terminal에서 scenario를 실행하거나 대표 조회를 수행할 수 있다. 검증: CLI 또는 script가 exit code와 요약 출력을 남긴다. +- [ ] [market-check] market data status/import 관련 결과를 화면 없이 확인할 수 있다. 검증: fixture 또는 local smoke가 상태 출력을 확인한다. +- [ ] [backtest-check] backtest list/detail/result/start 관련 결과를 화면 없이 확인할 수 있다. 검증: fixture 또는 local smoke가 성공/실패 결과를 확인한다. +- [ ] [error-output] unavailable/error/disconnected 상태가 화면 없이도 판별 가능한 출력으로 남는다. 검증: typed error 또는 상태 코드 출력 테스트가 통과한다. +- [ ] [handoff] Flutter 화면 MVP로 넘길 수 있는 검증 evidence와 남은 wireframe 의존성을 정리한다. + +## 완료 리뷰 + +- 상태: 없음 +- 요청일: 없음 +- 완료 근거: 아직 기능 Task와 검증이 충족되지 않았다. +- 리뷰 필요: + - [ ] 사용자가 완료 결과를 확인했다 + - [ ] archive 이동을 승인했다 +- 리뷰 코멘트: 없음 + +## 범위 제외 + +- Flutter 실화면 구현 +- dashboard layout, chart, form visual design 확정 +- push notification +- production 운영 자동화 + +## 작업 컨텍스트 + +- 관련 경로: `apps/cli/`, `bin/`, `services/api/`, `services/worker/`, `packages/contracts/` +- 표준선(선택): 화면 구현보다 CLI/YAML/headless smoke를 먼저 만들고, 결과는 exit code와 machine-readable 또는 grep 가능한 출력으로 남긴다. +- 선행 작업: Flutter Operator Console UX Plan +- 후속 작업: Flutter Operator Console MVP +- 확인 필요: UX Plan의 headless 시나리오 승인 전에는 구현 잠금을 유지한다. diff --git a/agent-task/m-flutter-operator-console/01_ux_scope_gate/CODE_REVIEW-cloud-G07.md b/agent-task/m-flutter-operator-console/01_ux_scope_gate/CODE_REVIEW-cloud-G07.md new file mode 100644 index 0000000..b7717aa --- /dev/null +++ b/agent-task/m-flutter-operator-console/01_ux_scope_gate/CODE_REVIEW-cloud-G07.md @@ -0,0 +1,136 @@ + + +# Code Review Reference - UX_SCOPE + +> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.** +> The task is NOT complete until every implementation-owned section below is filled in. +> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving. +> Fill implementation-owned sections, then stop with active files in place and report ready for review. +> If implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Evidence gaps that a follow-up agent can close by rerunning commands or collecting artifacts are normal follow-up issues, not user-review blockers by themselves. +> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume. +> Follow the ownership table at the bottom of this file for which sections you own. + +## 개요 + +date=2026-05-31 +task=m-flutter-operator-console/01_ux_scope_gate, plan=0, tag=UX_SCOPE + +## 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 + +## 이 파일을 읽는 리뷰 에이전트에게 + +> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다. + +각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요. +리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다. + +1. 판정을 append한다. +2. `CODE_REVIEW-cloud-G07.md` → `code_review_cloud_G07_N.log`, `PLAN-cloud-G07.md` → `plan_cloud_G07_M.log`로 아카이브한다. +3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-flutter-operator-console/01_ux_scope_gate/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. +4. PASS이고 task group이 `m-flutter-operator-console`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다. +5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다. + +--- + +## 구현 항목별 완료 여부 + +| 항목 | 완료 여부 | +|------|---------| +| [UX_SCOPE-1] Scope And Non-Scope | [ ] | +| [UX_SCOPE-2] Boundary And Wireframe Gate | [ ] | + +## 구현 체크리스트 + +- [ ] `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의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. + +## 코드리뷰 전용 체크리스트 + +> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다. +> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다. + +- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다. +- [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다. +- [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G07_N.log`로 아카이브한다. +- [ ] active `PLAN-*-G??.md`를 `plan_cloud_G07_M.log`로 아카이브한다. +- [ ] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하여 plan/review/archive 산출물이 추적 가능한지 확인한다. +- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다. +- [ ] PASS이면 active task 디렉터리 `agent-task/m-flutter-operator-console/01_ux_scope_gate/`를 `agent-task/archive/YYYY/MM/m-flutter-operator-console/01_ux_scope_gate/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다. +- [ ] PASS이고 task group이 `m-flutter-operator-console`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다. +- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-flutter-operator-console/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다. +- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-cloud-G07.md`와 `CODE_REVIEW-cloud-G07.md`를 작성하고 `complete.log`를 작성하지 않는다. +- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다. +- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다. + +## 계획 대비 변경 사항 + +_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._ + +## 주요 설계 결정 + +_구현 에이전트가 주요 설계 결정 사항을 기록한다._ + +## 사용자 리뷰 요청 + +_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._ + +- 상태: 없음 +- 사유 유형: 없음 +- 결정 필요: 없음 +- 차단 근거: 없음 +- 실행한 검증/명령: 없음 +- 자동 후속 불가 이유: 없음 +- 재개 조건: 없음 + +## 리뷰어를 위한 체크포인트 + +- `[scope]`, `[boundary]`, `[wireframe-gate]`만 완료 처리했는지 확인한다. +- 실제 Flutter 화면 구현, chart/form layout, production endpoint 가정이 추가되지 않았는지 확인한다. +- MVP Milestone의 `구현 잠금`이 wireframe 준비/사용자 승인 조건을 유지하는지 확인한다. + +## 검증 결과 + +_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._ + +필수 규칙: +- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다. +- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다. +- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다. +- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다. + +### UX_SCOPE-1 중간 검증 +```bash +$ rg --sort path -n "\\[x\\] \\[scope\\]|dashboard/control surface|terminal UI|실제 Flutter production 화면" agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md +(output) +``` + +### UX_SCOPE-2 중간 검증 +```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 +(output) +``` + +### 최종 검증 +```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 +(output) + +$ 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 +(output) +``` + +--- + +> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?** +> If anything is blank, go back and fill it in before saving this file. +> Leave review-agent-only sections unchanged. diff --git a/agent-task/m-flutter-operator-console/01_ux_scope_gate/PLAN-cloud-G07.md b/agent-task/m-flutter-operator-console/01_ux_scope_gate/PLAN-cloud-G07.md new file mode 100644 index 0000000..f7e505c --- /dev/null +++ b/agent-task/m-flutter-operator-console/01_ux_scope_gate/PLAN-cloud-G07.md @@ -0,0 +1,181 @@ + + +# 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`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다. diff --git a/agent-task/m-flutter-operator-console/02+01_headless_validation/CODE_REVIEW-cloud-G07.md b/agent-task/m-flutter-operator-console/02+01_headless_validation/CODE_REVIEW-cloud-G07.md new file mode 100644 index 0000000..73f9915 --- /dev/null +++ b/agent-task/m-flutter-operator-console/02+01_headless_validation/CODE_REVIEW-cloud-G07.md @@ -0,0 +1,147 @@ + + +# Code Review Reference - HEADLESS + +> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.** +> The task is NOT complete until every implementation-owned section below is filled in. +> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving. +> Fill implementation-owned sections, then stop with active files in place and report ready for review. +> If implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Evidence gaps that a follow-up agent can close by rerunning commands or collecting artifacts are normal follow-up issues, not user-review blockers by themselves. +> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume. +> Follow the ownership table at the bottom of this file for which sections you own. + +## 개요 + +date=2026-05-31 +task=m-flutter-operator-console/02+01_headless_validation, plan=0, tag=HEADLESS + +## Roadmap Targets + +- Milestone: `agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md` +- Task ids: + - `headless-first`: 화면 구현 전 CLI, terminal output, YAML scenario, log, test fixture로 검증할 운영 흐름을 정리한다. + - `state-policy`: loading/empty/error/unavailable/disconnected 상태와 operator action 가능/불가 정책을 headless 결과 표현 기준으로 정리한다. + - `validation-handoff`: 후속 `Operator Headless Workflow Validation`이 실행할 terminal/YAML 시나리오와 결과 확인 기준을 인수 가능한 형태로 정리한다. +- Completion mode: check-on-pass + +## 이 파일을 읽는 리뷰 에이전트에게 + +> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다. + +각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요. +리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다. + +1. 판정을 append한다. +2. `CODE_REVIEW-cloud-G07.md` → `code_review_cloud_G07_N.log`, `PLAN-cloud-G07.md` → `plan_cloud_G07_M.log`로 아카이브한다. +3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-flutter-operator-console/02+01_headless_validation/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. +4. PASS이고 task group이 `m-flutter-operator-console`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다. +5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다. + +--- + +## 구현 항목별 완료 여부 + +| 항목 | 완료 여부 | +|------|---------| +| [HEADLESS-1] Headless Scenario And State Policy | [ ] | +| [HEADLESS-2] Validation Handoff | [ ] | + +## 구현 체크리스트 + +- [ ] 구현 시작 전 `agent-task/m-flutter-operator-console/01_ux_scope_gate/complete.log` 존재를 확인한다. +- [ ] `flutter-operator-console.md`에서 CLI, terminal output, YAML scenario, log, test fixture로 검증할 운영 흐름을 정리하고 `[headless-first]` 완료 조건을 충족한다. +- [ ] `flutter-operator-console.md`에서 loading/empty/error/unavailable/disconnected 상태와 operator action 가능/불가 정책을 headless 결과 표현 기준으로 정리하고 `[state-policy]` 완료 조건을 충족한다. +- [ ] `flutter-operator-console.md`와 `operator-headless-workflow-validation.md`에서 후속 validation Milestone의 terminal/YAML 시나리오와 결과 확인 기준을 맞추고 `[validation-handoff]` 완료 조건을 충족한다. +- [ ] 원격 또는 cloud 실행 환경에서 최종 검증 명령을 실행하고 실제 stdout/stderr를 review stub에 기록한다. +- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. + +## 코드리뷰 전용 체크리스트 + +> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다. +> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다. + +- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다. +- [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다. +- [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G07_N.log`로 아카이브한다. +- [ ] active `PLAN-*-G??.md`를 `plan_cloud_G07_M.log`로 아카이브한다. +- [ ] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하여 plan/review/archive 산출물이 추적 가능한지 확인한다. +- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다. +- [ ] PASS이면 active task 디렉터리 `agent-task/m-flutter-operator-console/02+01_headless_validation/`를 `agent-task/archive/YYYY/MM/m-flutter-operator-console/02+01_headless_validation/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다. +- [ ] PASS이고 task group이 `m-flutter-operator-console`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다. +- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-flutter-operator-console/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다. +- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-cloud-G07.md`와 `CODE_REVIEW-cloud-G07.md`를 작성하고 `complete.log`를 작성하지 않는다. +- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다. +- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다. + +## 계획 대비 변경 사항 + +_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._ + +## 주요 설계 결정 + +_구현 에이전트가 주요 설계 결정 사항을 기록한다._ + +## 사용자 리뷰 요청 + +_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._ + +- 상태: 없음 +- 사유 유형: 없음 +- 결정 필요: 없음 +- 차단 근거: 없음 +- 실행한 검증/명령: 없음 +- 자동 후속 불가 이유: 없음 +- 재개 조건: 없음 + +## 리뷰어를 위한 체크포인트 + +- `01_ux_scope_gate`의 `complete.log`가 구현 시작 전 존재했는지 확인한다. +- `[headless-first]`, `[state-policy]`, `[validation-handoff]`만 완료 처리했는지 확인한다. +- 실제 CLI/YAML parser 구현이나 Flutter 화면 구현으로 범위가 확장되지 않았는지 확인한다. +- 후속 `Operator Headless Workflow Validation` Milestone과 handoff 기준이 충돌하지 않는지 확인한다. + +## 검증 결과 + +_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._ + +필수 규칙: +- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다. +- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다. +- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다. +- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다. + +### HEADLESS 의존성 검증 +```bash +$ test -f agent-task/m-flutter-operator-console/01_ux_scope_gate/complete.log +(output) +``` + +### HEADLESS-1 중간 검증 +```bash +$ rg --sort path -n "\\[x\\] \\[(headless-first|state-policy)\\]|YAML|terminal|loading|empty|error|unavailable|disconnected" agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md +(output) +``` + +### HEADLESS-2 중간 검증 +```bash +$ rg --sort path -n "\\[x\\] \\[validation-handoff\\]|Operator Headless Workflow Validation|scenario|terminal|YAML|result|exit code|grep" agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md agent-roadmap/phase/operator-surface/milestones/operator-headless-workflow-validation.md +(output) +``` + +### 최종 검증 +```bash +$ test -f agent-task/m-flutter-operator-console/01_ux_scope_gate/complete.log +(output) + +$ git diff --check -- agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md agent-roadmap/phase/operator-surface/milestones/operator-headless-workflow-validation.md +(output) + +$ rg --sort path -n "\\[x\\] \\[(headless-first|state-policy|validation-handoff)\\]|YAML|terminal|loading|empty|error|unavailable|disconnected|Operator Headless Workflow Validation|exit code|grep" agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md agent-roadmap/phase/operator-surface/milestones/operator-headless-workflow-validation.md +(output) +``` + +--- + +> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?** +> If anything is blank, go back and fill it in before saving this file. +> Leave review-agent-only sections unchanged. diff --git a/agent-task/m-flutter-operator-console/02+01_headless_validation/PLAN-cloud-G07.md b/agent-task/m-flutter-operator-console/02+01_headless_validation/PLAN-cloud-G07.md new file mode 100644 index 0000000..9ebb3d9 --- /dev/null +++ b/agent-task/m-flutter-operator-console/02+01_headless_validation/PLAN-cloud-G07.md @@ -0,0 +1,190 @@ + + +# Plan - HEADLESS + +## 구현 에이전트 지시 + +이 파일은 `m-flutter-operator-console/02+01_headless_validation` 구현 계약이다. 이 subtask는 `01_ux_scope_gate`의 `complete.log`가 있어야 구현을 시작할 수 있다. 구현 에이전트는 아래 체크리스트를 수행하고 검증 출력까지 `CODE_REVIEW-cloud-G07.md`의 구현 에이전트 소유 섹션에 기록한 뒤 active 파일을 유지한 채 리뷰를 요청한다. + +## 배경 + +현재 Milestone은 화면 구현 전에 terminal/YAML 기반 검증 순서를 확정해야 한다. 01번 작업이 scope와 wireframe gate를 고정하면, 이 작업은 그 경계 안에서 headless scenario와 상태 표현, 후속 validation Milestone의 handoff 기준을 만든다. + +## 사용자 리뷰 요청 흐름 + +구현 중 사용자만 결정할 수 있는 operator scenario 우선순위, 화면 선행 요구, scope 확대가 필요하면 `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: + - `headless-first`: 화면 구현 전 CLI, terminal output, YAML scenario, log, test fixture로 검증할 운영 흐름을 정리한다. + - `state-policy`: loading/empty/error/unavailable/disconnected 상태와 operator action 가능/불가 정책을 headless 결과 표현 기준으로 정리한다. + - `validation-handoff`: 후속 `Operator Headless Workflow Validation`이 실행할 terminal/YAML 시나리오와 결과 확인 기준을 인수 가능한 형태로 정리한다. +- 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/operator-headless-workflow-validation.md` + +### 테스트 환경 규칙 + +- 선택한 test_env: `local`. +- `agent-test/local/rules.md`는 존재하며 읽었다. +- 규칙상 로컬 테스트/검증은 금지이고 기본 테스트 환경은 원격이다. +- 이 작업은 roadmap 문서 변경이라 domain smoke profile은 매칭하지 않았다. +- 검증은 구현 에이전트가 원격 또는 cloud 실행 환경에서 dependency check, `git diff --check`, deterministic `rg --sort path`로 수행한다. +- agent-test 규칙은 존재하므로 `create-test`는 필요하지 않다. + +### 테스트 커버리지 공백 + +- 런타임 동작 변경 없음. 기존 unit/integration test 커버리지는 영향받지 않는다. +- headless scenario가 아직 구현되는 것은 아니므로 실제 CLI/YAML parser test는 후속 `Operator Headless Workflow Validation`에서 다룬다. + +### 심볼 참조 + +- 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`: 이 계획이며 predecessor `01`에 의존한다. +- predecessor 상태: 현재 active `agent-task/m-flutter-operator-console/01_ux_scope_gate/complete.log` 없음. 구현 시작 전 해당 파일이 필요하다. + +### 범위 결정 근거 + +- `apps/client/**`, `apps/cli/**`, `bin/**`, `services/api/**`, `services/worker/**` 코드는 수정하지 않는다. 이 작업은 후속 headless validation 구현의 입력을 정리한다. +- 실제 YAML schema, parser, CLI command 구현은 후속 `Operator Headless Workflow Validation`의 범위다. +- Flutter 화면 구현과 wireframe 작성은 제외한다. + +### 빌드 등급 + +- build lane: `cloud`, grade: `G07`. +- review lane: `cloud`, grade: `G07`. +- 근거: terminal/YAML workflow 정의와 원격 검증 증거가 필요하고 로컬 검증이 금지되어 있다. + +## 의존 관계 및 구현 순서 + +- 이 subtask directory 이름은 `02+01_headless_validation`이다. +- 구현 전 `agent-task/m-flutter-operator-console/01_ux_scope_gate/complete.log`가 있어야 한다. +- 의존성은 directory name의 `+01`만 따른다. 추가 의존성을 임의로 만들지 않는다. + +## 구현 체크리스트 + +- [ ] 구현 시작 전 `agent-task/m-flutter-operator-console/01_ux_scope_gate/complete.log` 존재를 확인한다. +- [ ] `flutter-operator-console.md`에서 CLI, terminal output, YAML scenario, log, test fixture로 검증할 운영 흐름을 정리하고 `[headless-first]` 완료 조건을 충족한다. +- [ ] `flutter-operator-console.md`에서 loading/empty/error/unavailable/disconnected 상태와 operator action 가능/불가 정책을 headless 결과 표현 기준으로 정리하고 `[state-policy]` 완료 조건을 충족한다. +- [ ] `flutter-operator-console.md`와 `operator-headless-workflow-validation.md`에서 후속 validation Milestone의 terminal/YAML 시나리오와 결과 확인 기준을 맞추고 `[validation-handoff]` 완료 조건을 충족한다. +- [ ] 원격 또는 cloud 실행 환경에서 최종 검증 명령을 실행하고 실제 stdout/stderr를 review stub에 기록한다. +- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. + +## [HEADLESS-1] Headless Scenario And State Policy + +### 문제 + +`agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md:38-39`는 headless-first와 state-policy task를 갖고 있지만, 어떤 운영 흐름을 화면 없이 검증할지와 상태 표현이 아직 인수 가능한 형태로 정리되어 있지 않다. + +Before: + +```markdown +38 - [ ] [headless-first] 화면 구현 전 CLI, terminal output, YAML scenario, log, test fixture로 검증할 운영 흐름을 정리한다. +39 - [ ] [state-policy] loading/empty/error/unavailable/disconnected 상태와 operator action 가능/불가 정책을 headless 결과 표현 기준으로 정리한다. +``` + +### 해결 방법 + +Milestone에 headless 검증 후보를 socket, market, backtest, error/unavailable/disconnected 흐름으로 나누어 정리한다. 상태 정책은 사람이 읽는 terminal summary와 machine-readable/grep 가능한 key를 함께 요구하도록 남긴다. + +After 방향: + +```markdown +- [x] [headless-first] 화면 구현 전 CLI, terminal output, YAML scenario, log, test fixture로 검증할 운영 흐름을 정리한다. +- [x] [state-policy] loading/empty/error/unavailable/disconnected 상태와 operator action 가능/불가 정책을 headless 결과 표현 기준으로 정리한다. +``` + +### 수정 파일 및 체크리스트 + +- [ ] `agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md`에 headless scenario 후보를 추가한다. +- [ ] `agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md`에 상태별 action 가능/불가 정책을 추가한다. +- [ ] `[headless-first]`, `[state-policy]` task를 `[x]`로 바꾼다. + +### 테스트 작성 + +테스트 작성 안 함. 실제 scenario parser/runner 구현은 후속 Milestone 범위다. + +### 중간 검증 + +```bash +rg --sort path -n "\\[x\\] \\[(headless-first|state-policy)\\]|YAML|terminal|loading|empty|error|unavailable|disconnected" agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md +``` + +기대 결과: headless-first/state-policy 체크와 상태 이름이 모두 검색된다. + +## [HEADLESS-2] Validation Handoff + +### 문제 + +`agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md:42`와 `agent-roadmap/phase/operator-surface/milestones/operator-headless-workflow-validation.md`가 서로 연결되어 있지만, 후속 Milestone이 받을 scenario/result 기준이 아직 충분히 구체적이지 않다. + +Before: + +```markdown +42 - [ ] [validation-handoff] 후속 `Operator Headless Workflow Validation`이 실행할 terminal/YAML 시나리오와 결과 확인 기준을 인수 가능한 형태로 정리한다. +``` + +### 해결 방법 + +현재 Milestone에는 handoff 요약을 남기고, 후속 `Operator Headless Workflow Validation` Milestone의 범위/기능을 scenario format, terminal run, market check, backtest check, error output과 일치하게 보강한다. + +After 방향: + +```markdown +- [x] [validation-handoff] 후속 `Operator Headless Workflow Validation`이 실행할 terminal/YAML 시나리오와 결과 확인 기준을 인수 가능한 형태로 정리한다. +``` + +### 수정 파일 및 체크리스트 + +- [ ] `agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md`에 validation handoff 요약을 남긴다. +- [ ] `agent-roadmap/phase/operator-surface/milestones/operator-headless-workflow-validation.md`가 handoff의 scenario/result 기준과 맞는지 확인하고 필요 시 보강한다. +- [ ] `[validation-handoff]` task를 `[x]`로 바꾼다. + +### 테스트 작성 + +테스트 작성 안 함. 후속 Milestone의 구현 계획에서 CLI/YAML parser와 smoke test를 다룬다. + +### 중간 검증 + +```bash +rg --sort path -n "\\[x\\] \\[validation-handoff\\]|Operator Headless Workflow Validation|scenario|terminal|YAML|result|exit code|grep" agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md agent-roadmap/phase/operator-surface/milestones/operator-headless-workflow-validation.md +``` + +기대 결과: 현재 Milestone의 handoff와 후속 Milestone의 scenario/result 기준이 모두 검색된다. + +## 수정 파일 요약 + +| 파일 | 항목 | +|------|------| +| `agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md` | HEADLESS-1, HEADLESS-2 | +| `agent-roadmap/phase/operator-surface/milestones/operator-headless-workflow-validation.md` | HEADLESS-2 | + +## 최종 검증 + +```bash +test -f agent-task/m-flutter-operator-console/01_ux_scope_gate/complete.log +git diff --check -- agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md agent-roadmap/phase/operator-surface/milestones/operator-headless-workflow-validation.md +rg --sort path -n "\\[x\\] \\[(headless-first|state-policy|validation-handoff)\\]|YAML|terminal|loading|empty|error|unavailable|disconnected|Operator Headless Workflow Validation|exit code|grep" agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md agent-roadmap/phase/operator-surface/milestones/operator-headless-workflow-validation.md +``` + +모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.