From 2a5599d92c917c5ecafaa81f2ca78d8d316390d0 Mon Sep 17 00:00:00 2001 From: toki Date: Sun, 31 May 2026 10:15:25 +0900 Subject: [PATCH] =?UTF-8?q?docs(agent-ops):=20operator-surface=20=EB=A7=88?= =?UTF-8?q?=EC=9D=BC=EC=8A=A4=ED=86=A4=EC=9D=84=20=EA=B0=B1=EC=8B=A0?= =?UTF-8?q?=ED=95=98=EA=B3=A0=20=EC=99=84=EB=A3=8C=EB=90=9C=20=EC=9E=91?= =?UTF-8?q?=EC=97=85=20=ED=8C=8C=EC=9D=BC=EC=9D=84=20=EC=A0=95=EB=A6=AC?= =?UTF-8?q?=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- agent-roadmap/current.md | 2 +- agent-roadmap/phase/operator-surface/PHASE.md | 4 +- .../milestones/flutter-operator-console.md | 78 ++++++- .../operator-headless-workflow-validation.md | 16 ++ .../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 ------------------ 8 files changed, 86 insertions(+), 668 deletions(-) delete mode 100644 agent-task/m-flutter-operator-console/01_ux_scope_gate/CODE_REVIEW-cloud-G07.md delete mode 100644 agent-task/m-flutter-operator-console/01_ux_scope_gate/PLAN-cloud-G07.md delete mode 100644 agent-task/m-flutter-operator-console/02+01_headless_validation/CODE_REVIEW-cloud-G07.md delete mode 100644 agent-task/m-flutter-operator-console/02+01_headless_validation/PLAN-cloud-G07.md diff --git a/agent-roadmap/current.md b/agent-roadmap/current.md index e6adf38..cc21cbb 100644 --- a/agent-roadmap/current.md +++ b/agent-roadmap/current.md @@ -7,7 +7,7 @@ ## 활성 Milestone -- [계획] Flutter Operator Console UX Plan +- [검토중] Flutter Operator Console UX Plan - Phase: `agent-roadmap/phase/operator-surface/PHASE.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 52684bb..6070230 100644 --- a/agent-roadmap/phase/operator-surface/PHASE.md +++ b/agent-roadmap/phase/operator-surface/PHASE.md @@ -19,9 +19,9 @@ Flutter client를 ALT의 공식 operator surface로 삼아 market data 상태와 - [완료] Operator Runtime Reliability Refactor - 경로: `agent-roadmap/archive/phase/operator-surface/milestones/operator-runtime-refactor.md` - 요약: Flutter operator console/headless validation 전에 API-worker lifecycle, worker execution wiring, capability reporting, client bootstrap, 원격 테스트 룰을 정리한다. -- [계획] Flutter Operator Console UX Plan +- [검토중] Flutter Operator Console UX Plan - 경로: `agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md` - - 요약: terminal형 콘솔이 아니라 dashboard/control surface라는 제품 의미를 정하되, 실화면 구현 전 headless 검증 우선 원칙과 wireframe gate를 먼저 정의한다. + - 요약: terminal형 콘솔이 아니라 dashboard/control surface라는 제품 의미, headless 검증 우선 원칙, 상태 정책, wireframe gate, validation handoff를 정리한 완료 후보 상태다. - [계획] Operator Headless Workflow Validation - 경로: `agent-roadmap/phase/operator-surface/milestones/operator-headless-workflow-validation.md` - 요약: Flutter 화면 없이 terminal/YAML 기반 운영 시나리오로 market data와 backtest 조회/실행 결과를 먼저 검증한다. 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 fa8b84a..00a116d 100644 --- a/agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md +++ b/agent-roadmap/phase/operator-surface/milestones/flutter-operator-console.md @@ -11,7 +11,7 @@ ## 상태 -[계획] +[검토중] ## 구현 잠금 @@ -34,22 +34,76 @@ 실화면 구현 전에 operator dashboard가 왜 필요한지, 화면 없이 무엇을 먼저 검증할지, 어떤 조건에서 화면 구현 잠금을 풀지 정의한다. -- [ ] [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 시나리오와 결과 확인 기준을 인수 가능한 형태로 정리한다. +- [x] [scope] Operator console이 terminal UI가 아니라 dashboard/control surface임을 정의하고 MVP 범위와 비범위를 정리한다. +- [x] [headless-first] 화면 구현 전 CLI, terminal output, YAML scenario, log, test fixture로 검증할 운영 흐름을 정리한다. +- [x] [state-policy] loading/empty/error/unavailable/disconnected 상태와 operator action 가능/불가 정책을 headless 결과 표현 기준으로 정리한다. +- [x] [boundary] Riverpod/go_router app shell, feature-first 구조, `AltSocketClient`, generated/mapped contracts의 결합 기준을 정리한다. +- [x] [wireframe-gate] 후속 `Flutter Operator Console MVP`의 구현 잠금 해제 조건을 화면 wireframe 준비/승인 여부로 정리한다. +- [x] [validation-handoff] 후속 `Operator Headless Workflow Validation`이 실행할 terminal/YAML 시나리오와 결과 확인 기준을 인수 가능한 형태로 정리한다. + +## UX 계획 산출물 + +### Console 의미와 MVP 범위 + +- Operator console은 terminal UI가 아니라 API 서버를 control plane으로 삼는 dashboard/control surface다. +- MVP 화면은 market data 상태 조회, backtest run 요청, run 상태 조회, result 요약 조회, connection/disconnected 상태 노출에 한정한다. +- 화면은 operator가 반복적으로 상태를 훑고 실행 요청을 판단하는 표면이며, worker job 구현이나 strategy authoring IDE 역할을 맡지 않는다. +- 비범위는 production charting 전체, mobile app store 배포, push notification, wireframe 없는 layout 확정, worker 직접 제어, 별도 TypeScript web app이다. + +### Headless-first 검증 흐름 + +- 화면 구현 전에 API connection smoke, capability 조회, market data 상태 조회, backtest 실행 요청, run 상태 폴링, result 요약 조회, 실패 응답 표현을 CLI 또는 terminal output으로 확인한다. +- 실행 요청 입력은 YAML scenario로 고정하고, 성공/실패 기대값은 log 또는 test fixture에서 재현 가능해야 한다. +- Flutter 화면은 headless 검증에서 확인된 요청/응답 shape와 상태 전이를 소비한다. 화면이 아직 없는 동안에도 운영 흐름의 입력, 출력, 실패 이유는 terminal에서 읽을 수 있어야 한다. +- 검증 결과는 후속 `Operator Headless Workflow Validation` Milestone이 인수하며, 그 Milestone은 실제 command, fixture, expected output을 확정한다. + +### 상태와 action 정책 + +| 상태 | Headless 표현 기준 | Operator action | +|------|--------------------|-----------------| +| loading | 요청 시작, 응답 대기, run polling 중임을 단계와 함께 출력한다. | 같은 대상 중복 실행은 막고 refresh/cancel 가능 여부만 명시한다. | +| empty | 조회는 성공했지만 market data, run, result가 없는 상태를 출력한다. | import/backtest 실행처럼 다음 생성 action이 있으면 활성화한다. | +| error | 요청 실패, validation 실패, worker 실패를 구분하고 correlation id 또는 run id가 있으면 함께 출력한다. | 입력 수정이나 retry 가능한 action만 허용하고 파괴적 재시도는 요구하지 않는다. | +| unavailable | capability 미지원, worker 미준비, 외부 provider 미설정처럼 현재 환경에서 불가능한 이유를 출력한다. | 해당 action은 비활성화하고 필요한 설정이나 선행 흐름을 안내 가능한 데이터로 남긴다. | +| disconnected | socket 연결 없음, reconnecting, handshake 실패를 구분해 출력한다. | API 의존 action은 비활성화하고 reconnect 또는 diagnostic action만 남긴다. | + +### Client boundary + +- `go_router`는 operator console의 route와 URL 구조를 소유한다. feature widget은 route path 문자열을 직접 흩뿌리지 않는다. +- Riverpod은 socket client, connection state, feature state, command submission state를 주입한다. +- `AltSocketClient`는 proto-socket connection과 ALT request/response dispatch boundary를 감싼다. Presentation widget은 production endpoint, socket path, generated protobuf detail을 직접 알지 않는다. +- Generated contracts와 mapped view model 사이의 변환은 feature data/application boundary에서 수행한다. Widget은 operator-facing label, status, action availability만 소비한다. +- app shell, provider boundary, generated contract 연결, headless smoke support는 화면 구현 잠금을 깨는 실화면 구현으로 보지 않는다. + +### Wireframe gate + +- `Flutter Operator Console MVP`의 구현 잠금은 headless validation 결과와 화면 wireframe이 준비된 뒤 해제한다. +- Wireframe은 navigation, market data status panel, backtest request form, run list/detail, result summary, loading/empty/error/unavailable/disconnected 표현을 포함해야 한다. +- Wireframe 승인 전에는 dashboard depth, card layout, chart choice, form flow를 코드로 확정하지 않는다. +- Wireframe은 web/mobile/desktop 단일 UI 표면을 전제로 하되, MVP 승인 기준은 web-first 운영 흐름 확인으로 둔다. + +### Headless validation handoff + +후속 `Operator Headless Workflow Validation` Milestone은 아래 시나리오를 terminal/YAML 기반으로 구체화한다. + +- `api_connection_smoke`: API socket connect, handshake/capability 조회, disconnected/reconnect 실패 표현 확인. +- `market_data_status_query`: symbol/date range 입력으로 market data availability와 empty/unavailable 상태 확인. +- `backtest_run_request`: YAML scenario의 strategy, symbol universe, date range, initial capital 입력 검증과 run 생성 응답 확인. +- `backtest_run_polling`: run id 기반 상태 전이와 실패 사유 표현 확인. +- `backtest_result_summary`: completed run의 summary metrics, empty result, missing run id 에러 확인. +- `invalid_request_matrix`: 필수 입력 누락, 잘못된 symbol/date/capital, 지원하지 않는 capability의 validation 응답 확인. + +각 시나리오는 command, input fixture, expected terminal/log output, exit status, 확인할 protobuf/view-model field를 함께 남겨 Flutter MVP가 같은 상태 정책을 소비할 수 있어야 한다. ## 완료 리뷰 -- 상태: 없음 -- 요청일: 없음 -- 완료 근거: 아직 기능 Task가 충족되지 않았다. +- 상태: 요청됨 +- 요청일: 2026-05-31 +- 완료 근거: `UX 계획 산출물`에 console scope, headless-first 흐름, 상태 정책, client boundary, wireframe gate, validation handoff가 정리되었고 모든 기능 Task가 체크되었다. - 리뷰 필요: - [ ] 사용자가 완료 결과를 확인했다 - [ ] archive 이동을 승인했다 -- 리뷰 코멘트: 없음 +- 리뷰 코멘트: 현재 Milestone은 문서형 UX 계획 산출물로 완료 후보이며, 후속 구현성 작업은 `Operator Headless Workflow Validation`과 `Flutter Operator Console MVP`에서 다룬다. ## 범위 제외 @@ -67,3 +121,5 @@ - 선행 작업: API-Centered Proto-Socket Rail - 후속 작업: Operator Headless Workflow Validation, Flutter Operator Console MVP, Flutter Push Notification Boundary - 확인 필요: 없음 +- Workspace 잠금: 관련 lock 없음 +- Plan 판단: 현재 Milestone의 기능 Task는 문서형 계획 산출물로 직접 처리했다. 별도 `agent-task` plan이 필요한 코드 구현 또는 headless command 구현은 후속 Milestone 범위다. 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 index 167d773..17f516d 100644 --- a/agent-roadmap/phase/operator-surface/milestones/operator-headless-workflow-validation.md +++ b/agent-roadmap/phase/operator-surface/milestones/operator-headless-workflow-validation.md @@ -27,6 +27,7 @@ Flutter 화면 없이 ALT 운영 흐름을 terminal/YAML/log/test fixture 기반 - backtest list/detail/result/start 요청 결과 확인 - unavailable/error/disconnected 결과의 machine-readable 또는 grep 가능한 출력 - 화면 구현 전 검증 evidence 산출 방식 +- `api_connection_smoke`, `market_data_status_query`, `backtest_run_request`, `backtest_run_polling`, `backtest_result_summary`, `invalid_request_matrix` 시나리오의 command/input/output/exit code 기준 확정 ## 기능 @@ -65,3 +66,18 @@ Flutter 화면 없이 ALT 운영 흐름을 terminal/YAML/log/test fixture 기반 - 선행 작업: Flutter Operator Console UX Plan - 후속 작업: Flutter Operator Console MVP - 확인 필요: UX Plan의 headless 시나리오 승인 전에는 구현 잠금을 유지한다. + +## UX Plan handoff 기준 + +`Flutter Operator Console UX Plan`에서 넘기는 headless validation 후보는 다음 실행 단위로 구체화한다. + +| Scenario | 입력 | 확인 결과 | +|----------|------|-----------| +| `api_connection_smoke` | API socket host/path와 optional reconnect 설정 | handshake/capability, disconnected/reconnect 실패, exit code | +| `market_data_status_query` | symbol, date range, provider/capability option | availability, empty, unavailable 상태와 grep 가능한 status key | +| `backtest_run_request` | strategy, symbol universe, date range, initial capital | validation success/failure, run id, typed error key | +| `backtest_run_polling` | run id, polling timeout | queued/running/completed/failed 전이와 실패 사유 | +| `backtest_result_summary` | completed run id | summary metrics, empty result, missing run id error | +| `invalid_request_matrix` | 필수 입력 누락 또는 잘못된 symbol/date/capital/capability | validation error, unavailable/error 구분, non-zero exit code | + +각 scenario는 command, YAML 또는 동등 fixture, expected terminal/log output, exit code, 확인할 protobuf 또는 view-model field를 evidence로 남긴다. 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 deleted file mode 100644 index b7717aa..0000000 --- a/agent-task/m-flutter-operator-console/01_ux_scope_gate/CODE_REVIEW-cloud-G07.md +++ /dev/null @@ -1,136 +0,0 @@ - - -# 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 deleted file mode 100644 index f7e505c..0000000 --- a/agent-task/m-flutter-operator-console/01_ux_scope_gate/PLAN-cloud-G07.md +++ /dev/null @@ -1,181 +0,0 @@ - - -# 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 deleted file mode 100644 index 73f9915..0000000 --- a/agent-task/m-flutter-operator-console/02+01_headless_validation/CODE_REVIEW-cloud-G07.md +++ /dev/null @@ -1,147 +0,0 @@ - - -# 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 deleted file mode 100644 index 9ebb3d9..0000000 --- a/agent-task/m-flutter-operator-console/02+01_headless_validation/PLAN-cloud-G07.md +++ /dev/null @@ -1,190 +0,0 @@ - - -# 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`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.