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

# Code Review Reference - TEST

> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> Complete the `구현 체크리스트`, fill implementation-owned sections, then stop with active files in place and report ready for review. Finalization is review-agent-only. If blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop.

## 개요

date=2026-06-16
task=m-backtest-scenario-automation/06+05_matrix_seed, plan=0, tag=TEST

## 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

## 이 파일을 읽는 리뷰 에이전트에게

> **[REVIEW AGENT ONLY]** 종결 절차는 코드리뷰 에이전트 전용이다.

PASS이면 active plan/review를 `.log`로 아카이브하고 `complete.log`를 작성한 뒤 `agent-task/archive/YYYY/MM/m-backtest-scenario-automation/06+05_matrix_seed/`로 이동한다. PASS 완료 이벤트 메타데이터만 보고하고 roadmap은 직접 수정하지 않는다.

---

## 구현 항목별 완료 여부

| 항목 | 완료 여부 |
|------|---------|
| [TEST-1] Matrix seed/import handoff and remote success | [x] |

## 구현 체크리스트

- [x] `05+04_runtime_startup` complete.log가 있는지 확인하고 경로를 기록한다.
  - 경로: `agent-task/archive/2026/06/m-backtest-scenario-automation/05+04_runtime_startup/complete.log`
- [x] 신규 원격 DB 기준 matrix 실행 전 seed/import 절차를 선택한다. 기본값은 `backtest_result_summary.yaml`의 import step 또는 동등한 import-only scenario를 먼저 실행하는 것이다.
  - `backtest_result_summary.yaml` 전체 실행으로 결정 (import + backtest 통합 검증)
- [x] 선택한 seed/import 절차를 `apps/cli/testdata/operator/headless_validation.md` 또는 YAML fixture에 raw 값 없이 반영한다.
  - `headless_validation.md`에 "Matrix pre-seed 절차" 섹션 추가
- [x] 원격 runner에서 seed/import 절차 후 `backtest_matrix_success.yaml`을 실행해 exit code 0과 `run_status=succeeded` evidence를 기록한다.
  - 원격 code-server 컨테이너에서 실행; seed exit_code=0, matrix exit_code=0, run_status=succeeded 확인
- [x] handoff 문서나 fixture를 수정했다면 `go test -count=1 ./apps/cli/internal/operator ./apps/cli/internal/cli`를 실행한다.
  - `ok git.toki-labs.com/toki/alt/apps/cli/internal/operator 0.410s`
  - `ok git.toki-labs.com/toki/alt/apps/cli/internal/cli 0.009s`
- [x] `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## 코드리뷰 전용 체크리스트

- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [x] active review/plan을 `.log`로 아카이브한다.
- [ ] PASS이면 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [ ] PASS이면 active task 디렉터리를 archive로 이동한다.
- [ ] PASS이면 roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
- [x] WARN/FAIL이면 다음 active plan/review 또는 `USER_REVIEW.md`를 규칙대로 작성한다.

## 계획 대비 변경 사항

- `bin/kis-sops-env` 기본 SOPS_AGE_KEY_FILE 미탐지 이슈: SSH 세션에서는 age 기본 위치 탐색 실패. `SOPS_AGE_KEY_FILE=<SOPS_AGE_KEY_FILE>`를 명시 주입해 해결. 구현 범위 변경 없음.
- worker/API 기동은 macOS 호스트 `docker exec -d`를 통해 code-server 컨테이너 내부에서 수행. PLAN의 `ssh "$ALT_REMOTE_SSH"` 패턴과 동등한 효과.

## 주요 설계 결정

- runner 구조 변경 없이 handoff 절차(pre-seed)로 matrix determinism 확보: `backtest_result_summary.yaml`을 먼저 실행해 005930 종목 20240527–20240528 bar 2개를 DB에 적재하고, 이후 `backtest_matrix_success.yaml`을 실행해 succeeded 확인.
- 별도 import-only YAML 생성 없이 기존 `backtest_result_summary.yaml` 재사용: 범위 최소화 원칙 적용.

## 사용자 리뷰 요청

_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 구현 에이전트는 사용자에게 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다._

- 상태: 없음
- 사유 유형: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 자동 후속 불가 이유: 없음
- 재개 조건: 없음

## 리뷰어를 위한 체크포인트

- 05 predecessor complete.log가 확인됐는지 본다.
- matrix seed/import 절차가 문서 또는 fixture에 남았고 raw 값이 없는지 확인한다.
- 원격 matrix success JSONL이 exit code 0과 `run_status=succeeded`를 증명하는지 본다.

## 검증 결과

### TEST-1 중간 검증

```bash
$ go test -count=1 ./apps/cli/internal/operator ./apps/cli/internal/cli
ok  	git.toki-labs.com/toki/alt/apps/cli/internal/operator	0.410s
ok  	git.toki-labs.com/toki/alt/apps/cli/internal/cli	0.009s
```

### 최종 검증

```bash
$ git diff --check
(출력 없음, PASS)

$ go test -count=1 ./apps/cli/internal/operator ./apps/cli/internal/cli
ok  	git.toki-labs.com/toki/alt/apps/cli/internal/operator	0.410s
ok  	git.toki-labs.com/toki/alt/apps/cli/internal/cli	0.009s

$ find agent-task/archive -path '*/m-backtest-scenario-automation/05+04_runtime_startup/complete.log' -print -quit
agent-task/archive/2026/06/m-backtest-scenario-automation/05+04_runtime_startup/complete.log

$ # 원격 code-server 컨테이너: backtest_result_summary.yaml (seed/import)
{"action":"import_daily_bars","bar_count":2,"instrument_count":1,"provider":"kis","scenario":"backtest_result_summary","status":"ok","step":"import_kr_daily_bars","type":"step"}
{"action":"start_backtest","run_id":"run-c795f2268c9419716b9389553fb217a0","run_status":"pending","scenario":"backtest_result_summary","status":"ok","step":"start","type":"step"}
{"action":"get_backtest_result","ending_equity":"10000000","run_id":"run-c795f2268c9419716b9389553fb217a0","scenario":"backtest_result_summary","starting_cash":"10000000","status":"ok","step":"result","total_return":"0","type":"step"}
{"exit_code":0,"passed":3,"scenario":"backtest_result_summary","status":"ok","steps":3,"type":"summary"}

$ # 원격 code-server 컨테이너: backtest_matrix_success.yaml (matrix)
{"action":"start_backtest","matrix_run_id":"kr-backtest-smoke__strategy-v1__daily__p1","period_id":"p1","run_id":"run-bb6229e903d04dac54333cbe724761f5","run_status":"pending","scenario":"backtest_matrix_success","status":"ok","step":"kr-backtest-smoke__strategy-v1__daily__p1","strategy_id":"strategy-v1","timeframe":"daily","type":"step","universe":"kr-backtest-smoke"}
{"action":"poll_backtest_run","matrix_run_id":"kr-backtest-smoke__strategy-v1__daily__p1","period_id":"p1","run_id":"run-bb6229e903d04dac54333cbe724761f5","run_status":"succeeded","scenario":"backtest_matrix_success","status":"ok","step":"kr-backtest-smoke__strategy-v1__daily__p1","strategy_id":"strategy-v1","timeframe":"daily","type":"step","universe":"kr-backtest-smoke"}
{"exit_code":0,"passed":1,"scenario":"backtest_matrix_success","status":"ok","steps":1,"type":"summary"}
```

---

> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section?**

## 코드리뷰 결과

- 종합 판정: FAIL
- 차원별 평가:
  - correctness: Fail
  - completeness: Fail
  - test coverage: Pass
  - API contract: Pass
  - code quality: Pass
  - plan deviation: Fail
  - verification trust: Fail
- 발견된 문제:
  - Required: [headless_validation.md](/config/workspace/alt/apps/cli/testdata/operator/headless_validation.md:57)가 신규 원격 DB의 matrix 선행 조건을 `backtest_result_summary.yaml` 전체 실행으로 고정하고, [headless_validation.md](/config/workspace/alt/apps/cli/testdata/operator/headless_validation.md:65)는 이를 `import_daily_bars + full backtest 검증`으로 문서화합니다. 하지만 현재 [backtest_result_summary.yaml](/config/workspace/alt/apps/cli/testdata/operator/backtest_result_summary.yaml:29)는 `start_backtest` 직후 `get_backtest_result`를 호출하고 poll step이 없으며, [07+05_result_poll_remote PLAN](/config/workspace/alt/agent-task/m-backtest-scenario-automation/07+05_result_poll_remote/PLAN-cloud-G06.md:73)는 이 파일의 `start -> poll -> result` 안정화를 별도 active task로 소유합니다. 실제 선행 archive도 `get_backtest_result not_found`를 07 범위로 남겼습니다([complete.log](/config/workspace/alt/agent-task/archive/2026/06/m-backtest-scenario-automation/05+04_runtime_startup/complete.log:23), [code_review_cloud_G08_1.log](/config/workspace/alt/agent-task/archive/2026/06/m-backtest-scenario-automation/05+04_runtime_startup/code_review_cloud_G08_1.log:203)). 이 상태에서는 matrix seed 작업이 미완료 sibling인 result-poll 흐름의 성공에 묶이므로, `matrix-seed`가 요구하는 독립적이고 결정적인 pre-seed 절차를 보장하지 못합니다.
- 필요한 수정:
  - `backtest_matrix_success.yaml` 실행 전에 필요한 데이터만 적재하고 exit 0으로 끝나는 import-only seed 경로를 문서나 fixture로 고정합니다. 기존 fixture를 재사용한다면 같은 universe/symbol/date를 실제로 seed하는지 근거를 남깁니다.
  - full `backtest_result_summary.yaml` 실행을 선행 조건으로 유지하려면 `07+05_result_poll_remote`가 PASS된 뒤 의존 조건을 명확히 반영해야 합니다. 현재 active sibling 상태에서는 이 리뷰를 PASS 처리하지 않습니다.
  - 수정 후 신규 원격 DB 기준 seed/import command와 `backtest_matrix_success.yaml` command의 실제 JSONL evidence를 다시 기록합니다.
- 다음 단계: FAIL 후속 plan/review를 생성한다. USER_REVIEW gate는 트리거하지 않는다.
