alt/agent-task/m-flutter-operator-console/02+01_headless_validation/PLAN-cloud-G07.md

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:

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

- [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 범위다.

중간 검증

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:

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

- [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를 다룬다.

중간 검증

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

최종 검증

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