<!-- task=m-backtest-scenario-automation/06+05_matrix_seed plan=0 tag=TEST -->

# 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](/config/workspace/alt/agent-roadmap/phase/backtest-loop/milestones/backtest-scenario-automation.md:50)는 신규 원격 DB에서도 `backtest_matrix_success.yaml`이 deterministic하게 통과해야 한다고 요구한다. [apps/cli/testdata/operator/backtest_matrix_success.yaml](/config/workspace/alt/apps/cli/testdata/operator/backtest_matrix_success.yaml:10)는 matrix만 선언하고 import step이 없다. [apps/cli/internal/operator/runner.go](/config/workspace/alt/apps/cli/internal/operator/runner.go:1457)는 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`에 추가한다.

#### 중간 검증

```bash
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 변경 시 |

## 최종 검증

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