alt/agent-task/m-backtest-scenario-automation/06+05_matrix_seed/PLAN-cloud-G07.md

Matrix Seed Plan

이 파일을 읽는 구현 에이전트에게

구현 완료 전 CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. finalization은 code-review 전용이다. 사용자 결정, 사용자 소유 외부 환경/secret 준비, 범위 충돌이 필요하면 직접 묻지 말고 review stub의 사용자 리뷰 요청에 정확한 근거를 남긴다.

배경

backtest_matrix_success.yaml은 신규 원격 DB에 데이터가 없으면 matrix start/poll만으로 deterministic하게 성공하기 어렵다. 이 계획은 원격 runtime startup 완료 뒤, matrix 실행 전에 어떤 import/seed 절차를 수행해야 하는지 YAML 또는 handoff 문서에 고정하고 실제 원격 runner에서 exit code 0 evidence를 남긴다.

사용자 리뷰 요청 흐름

구현 중 차단은 active review stub의 사용자 리뷰 요청 섹션에 기록한다. 직접 사용자 prompt는 금지이며 code-review가 USER_REVIEW.md 작성을 소유한다.

Roadmap Targets

• Milestone: agent-roadmap/phase/backtest-loop/milestones/backtest-scenario-automation.md
• Task ids:
  • matrix-seed: matrix scenario가 신규 원격 DB에서도 결정적으로 통과하도록 선행 import/seed 조건을 YAML 또는 handoff 문서에 반영한다.
• Completion mode: check-on-pass

분석 결과

읽은 파일

• agent-roadmap/current.md
• agent-roadmap/phase/backtest-loop/milestones/backtest-scenario-automation.md
• agent-test/local/rules.md
• agent-test/local/operations-smoke.md
• agent-test/local/api-smoke.md
• agent-test/local/worker-smoke.md
• apps/cli/internal/operator/scenario.go
• apps/cli/internal/operator/runner.go
• apps/cli/internal/operator/runner_backtest_test.go
• apps/cli/internal/operator/handoff_test.go
• apps/cli/testdata/operator/backtest_matrix_success.yaml
• apps/cli/testdata/operator/backtest_result_summary.yaml
• apps/cli/testdata/operator/expected/backtest_matrix_success.jsonl
• apps/cli/testdata/operator/headless_validation.md

테스트 환경 규칙

test_env=local이다. operations/api/worker smoke profile을 읽었다. local baseline은 CLI/operator unit tests이며, 완료 검증은 remote runtime에서 backtest_matrix_success.yaml exit code 0을 확인해야 한다. raw host, token, password, account number, endpoint 값은 task artifact에 남기지 않는다.

테스트 커버리지 공백

• 신규 원격 DB seed 상태: unit test가 실제 DB seed 여부를 보장하지 않는다.
• matrix pre-seed 절차: 현재 fixture는 matrix 자체만 선언하므로 handoff 문서 또는 별도 seed scenario 실행 evidence가 필요하다.
• runner 구조 변경: 기본 계획은 runner 변경을 제외한다. remote evidence상 handoff 절차만으로 부족하면 regression test와 함께 범위 확장을 기록한다.

심볼 참조

none. 기본 계획은 rename/remove 없음.

분할 판단

06+05_matrix_seed는 05+04_runtime_startup 완료 후 실행해야 한다. 구현 시작 전 active 또는 archived 05+04_runtime_startup/complete.log를 확인한다. 07+05_result_poll_remote와는 같은 predecessor를 공유하지만 서로 독립적으로 검증 가능하다.

범위 결정 근거

runtime 기동은 predecessor가 소유한다. result summary polling remote evidence는 07+05_result_poll_remote가 소유한다. 이 작업은 matrix seed/import 절차와 matrix success evidence에만 집중한다. runner가 matrix 전에 steps를 실행하도록 바꾸는 구조 변경은 handoff seed 절차로 해결되지 않을 때만 선택한다.

빌드 등급

cloud-G07. 원격 DB seed, KIS import, matrix batch evidence가 외부 runtime에 의존하고, 실패 시 원인이 seed/fixture/runtime 중 어디인지 분리해야 한다.

의존 관계 및 구현 순서

06+05_matrix_seed는 디렉터리명 기준으로 05+04_runtime_startup에 의존한다. 구현 시작 전 05+04_runtime_startup complete.log를 확인한다.

구현 체크리스트

• 05+04_runtime_startup complete.log가 있는지 확인하고 경로를 기록한다.
• 신규 원격 DB 기준 matrix 실행 전 seed/import 절차를 선택한다. 기본값은 backtest_result_summary.yaml의 import step 또는 동등한 import-only scenario를 먼저 실행하는 것이다.
• 선택한 seed/import 절차를 apps/cli/testdata/operator/headless_validation.md 또는 YAML fixture에 raw 값 없이 반영한다.
• 원격 runner에서 seed/import 절차 후 backtest_matrix_success.yaml을 실행해 exit code 0과 run_status=succeeded evidence를 기록한다.
• handoff 문서나 fixture를 수정했다면 go test -count=1 ./apps/cli/internal/operator ./apps/cli/internal/cli를 실행한다.
• CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

[TEST-1] Matrix seed/import handoff and remote success

문제

agent-roadmap/phase/backtest-loop/milestones/backtest-scenario-automation.md는 신규 원격 DB에서도 backtest_matrix_success.yaml이 deterministic하게 통과해야 한다고 요구한다. apps/cli/testdata/operator/backtest_matrix_success.yaml는 matrix만 선언하고 import step이 없다. apps/cli/internal/operator/runner.go는 matrix runs를 바로 시작/poll하므로 같은 YAML에 일반 steps를 추가해도 기본적으로 seed가 먼저 실행된다고 가정하면 안 된다.

해결 방법

먼저 runner 변경 없이 해결한다. 원격 runtime이 떠 있는 상태에서 seed/import scenario를 별도로 실행하고, 그 절차를 headless_validation.md에 matrix precondition으로 남긴다. 이후 backtest_matrix_success.yaml을 실행해 JSONL에서 run_status=succeeded, summary exit_code=0을 확인한다. 이 방식으로 실패하면, 그때만 runner가 matrix 전에 seed steps를 실행하도록 확장하는 follow-up 구현을 계획 대비 변경 사항에 근거와 함께 기록한다.

수정 파일 및 체크리스트

• apps/cli/testdata/operator/headless_validation.md - matrix pre-seed 절차를 raw 값 없이 기록한다.
• apps/cli/testdata/operator/backtest_matrix_success.yaml - YAML 자체에 seed 조건을 반영하기로 결정한 경우만 수정한다.
• apps/cli/internal/operator/runner.go, runner_backtest_test.go - handoff 절차로 부족해 runner 변경이 필요한 경우에만 수정하고 regression test를 추가한다.

테스트 작성

기본 계획에서는 새 unit test를 작성하지 않는다. 문서/fixture만 수정하면 기존 handoff tests가 drift를 잡는다. runner 변경이 발생하면 matrix pre-step regression test를 runner_backtest_test.go에 추가한다.

중간 검증

go test -count=1 ./apps/cli/internal/operator ./apps/cli/internal/cli

기대 결과: exit code 0.

수정 파일 요약

파일	항목
apps/cli/testdata/operator/headless_validation.md	TEST-1
apps/cli/testdata/operator/backtest_matrix_success.yaml	TEST-1, 필요 시
apps/cli/internal/operator/runner.go	TEST-1, 필요 시
apps/cli/internal/operator/runner_backtest_test.go	TEST-1, runner 변경 시

최종 검증

git diff --check
go test -count=1 ./apps/cli/internal/operator ./apps/cli/internal/cli
test -f agent-task/m-backtest-scenario-automation/05+04_runtime_startup/complete.log || find agent-task/archive -path '*/m-backtest-scenario-automation/05+04_runtime_startup/complete.log' -print -quit
ssh "$ALT_REMOTE_SSH" "set -euo pipefail; cd \"$ALT_REMOTE_ALT_ROOT/apps/cli\"; go run ./cmd/alt operator scenario run --file testdata/operator/backtest_result_summary.yaml --api-url \"ws://127.0.0.1:18030/socket\" --output jsonl"
ssh "$ALT_REMOTE_SSH" "set -euo pipefail; cd \"$ALT_REMOTE_ALT_ROOT/apps/cli\"; go run ./cmd/alt operator scenario run --file testdata/operator/backtest_matrix_success.yaml --api-url \"ws://127.0.0.1:18030/socket\" --output jsonl"

기대 결과: seed/import command는 typed success를 포함한다. matrix command는 exit code 0, run_status=succeeded, summary exit_code=0을 기록한다. Go test cache output은 허용하지 않고 -count=1 fresh run을 사용한다.

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