update roadmap and SDD files

2026-06-17 20:17:09 +09:00 · 2026-06-17 20:17:09 +09:00 · 1f1cfcabfa
commit 1f1cfcabfa
parent 7c81079e8c
6 changed files with 340 additions and 3 deletions
--- a/agent-roadmap/phase/backtest-loop/milestones/backtest-multi-timeframe-coverage.md
+++ b/agent-roadmap/phase/backtest-loop/milestones/backtest-multi-timeframe-coverage.md
@ -26,8 +26,10 @@
 - 잠금 해제 조건: 아래 체크리스트
  - [ ] SDD 잠금이 해제되어 있다.
  - [ ] SDD 사용자 리뷰가 없거나 승인/해결되었다.
+  - [ ] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
+  - [ ] Evidence Map이 plan의 `Spec Targets`와 완료 시 `Spec Completion`으로 검증 가능하게 연결되어 있다.
 - 결정 필요: 아래 체크리스트
-  - [ ] 분봉 기본 단위를 `1m`만으로 시작할지, 기존 vocabulary처럼 `1m`/`5m`를 함께 기본 지원할지 결정한다.
+  - [ ] 분봉 1차 import/backtest 검증 baseline을 `1m`만으로 시작할지, 기존 vocabulary처럼 `1m`/`5m`를 함께 포함할지 결정한다.
  - [ ] 월봉을 provider 원천 데이터로 우선 받을지, 일봉에서 deterministic aggregation으로 생성할지 기본 우선순위를 결정한다.

 ## 범위
@ -90,4 +92,4 @@
 - 표준선(선택): 백테스트는 먼저 단일 timeframe run을 확실히 닫고, 여러 timeframe을 동시에 참조하는 전략은 후속 Milestone으로 미룬다.
 - 선행 작업: Backtest Data Collection Infrastructure, Backtest Scenario Automation
 - 후속 작업: Scheduled Market Data Refresh의 multi-timeframe cadence 보강, Multi-Timeframe Strategy Composition 후보
- 확인 필요: 분봉 기본 단위와 월봉 source-of-truth 우선순위는 SDD에서 사용자 결정으로 확정한다.
+- 확인 필요: 분봉 1차 import/backtest 검증 baseline과 월봉 source-of-truth 우선순위는 SDD에서 사용자 결정으로 확정한다.
--- a/agent-roadmap/phase/backtest-loop/milestones/scheduled-market-data-refresh.md
+++ b/agent-roadmap/phase/backtest-loop/milestones/scheduled-market-data-refresh.md
@ -26,7 +26,10 @@
 - 잠금 해제 조건: 아래 체크리스트
  - [ ] SDD 잠금이 해제되어 있다.
  - [ ] SDD 사용자 리뷰가 없거나 승인/해결되었다.
- 결정 필요: 없음
+  - [ ] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
+  - [ ] Evidence Map이 plan의 `Spec Targets`와 완료 시 `Spec Completion`으로 검증 가능하게 연결되어 있다.
+- 결정 필요: 아래 체크리스트
+  - [ ] scheduler를 worker 내장 loop, OS/systemd timer, external cron 중 어디까지 1차 구현으로 둘지 확정한다.

 ## 범위

--- a/agent-roadmap/sdd/backtest-loop/backtest-multi-timeframe-coverage/SDD.md
+++ b/agent-roadmap/sdd/backtest-loop/backtest-multi-timeframe-coverage/SDD.md
@ -0,0 +1,127 @@
+# SDD: Backtest Multi-Timeframe Coverage
+
+## 위치
+
+- Milestone: `agent-roadmap/phase/backtest-loop/milestones/backtest-multi-timeframe-coverage.md`
+- Phase: `agent-roadmap/phase/backtest-loop/PHASE.md`
+
+## 상태
+
+[검토중]
+
+## SDD 잠금
+
+- 상태: 잠금
+- 사용자 리뷰: `USER_REVIEW.md`
+- 잠금 항목:
+  - [ ] [D01] 분봉 1차 import/backtest 검증 baseline을 `1m`만으로 시작할지, 기존 vocabulary처럼 `1m`/`5m`를 함께 포함할지 결정한다.
+  - [ ] [D02] 월봉의 기본 source of truth를 provider 원천 데이터 우선으로 둘지, 일봉 기반 deterministic aggregation 우선으로 둘지 결정한다.
+
+## 문제 / 비목표
+
+- 문제: ALT의 일봉 MVP 경로는 contracts, domain, storage, CLI scenario, backtest run이 닫혀 있지만 월봉과 분봉은 vocabulary, provider capability, 저장 key, backtest selector, freshness/readiness 의미가 함께 확정되어야 한다.
+- 비목표:
+  - 여러 timeframe을 동시에 참조하는 strategy DSL 또는 factor language 설계
+  - tick data, order book, 실시간 streaming bar construction
+  - Flutter 운영 화면 구현
+  - 실거래 order routing 또는 broker execution 변경
+  - 외부 provider credential 값이나 개인 secret 문서화
+
+## Source of Truth
+
+| 영역 | 기준 | 메모 |
+|------|------|------|
+| Roadmap | `agent-roadmap/phase/backtest-loop/milestones/backtest-multi-timeframe-coverage.md` | Milestone 목표, 기능 Task, 범위 제외, 완료 후보 반영 기준 |
+| Code | `packages/contracts/proto/alt/v1/common.proto` | `Timeframe` enum 원천. 현재 `DAILY`, `MINUTE_1`, `MINUTE_5`가 있으며 월봉 추가가 필요하다. |
+| Code | `packages/domain/market/types.go` | domain `market.Timeframe` 원천. 현재 `1d`, `1m`, `5m`가 있다. |
+| Code | `packages/contracts/proto/alt/v1/market.proto`, `packages/contracts/proto/alt/v1/backtest.proto` | `Bar`, `ListBarsRequest`, `BacktestRunSpec`의 timeframe 전달 계약 |
+| Code | `apps/cli/internal/operator/scenario.go` | scenario string vocabulary와 matrix validation 기준 |
+| Code | `services/worker/internal/storage/postgres/queries/queries.sql` | `bars` key는 `(instrument_id, timeframe, timestamp)`이며 timeframe별 독립 저장 기준이다. |
+| Code | `services/worker/internal/storage/postgres/migrate_test.go` | `bars` table은 normalized OHLCV 저장 계약을 유지하며 provider raw payload를 섞지 않는다. |
+| Code | `services/worker/internal/backtest/bar_source.go` | backtest run selector가 storage에서 timeframe별 bars를 읽는 기준이다. |
+| External Provider | KIS | provider capability와 실제 지원 timeframe을 명시적으로 accepted/rejected로 판정해야 한다. |
+| User Decision | D01, D02 | 분봉 1차 import/backtest 검증 baseline과 월봉 source of truth 우선순위가 구현 잠금 해제 조건이다. |
+
+## State Machine
+
+| 상태 | 진입 조건 | 다음 상태 | 근거 |
+|------|-----------|-----------|------|
+| `candidate` | monthly/daily/minute timeframe이 scenario 또는 API 입력에 등장한다. | `accepted` 또는 `rejected` | proto/domain/CLI validation, provider capability matrix |
+| `rejected` | provider, market, venue, asset type, timeframe 조합이 지원되지 않는다. | terminal | typed error, stable text/JSONL rejected fixture |
+| `accepted` | 조합이 capability matrix를 통과한다. | `imported` 또는 `aggregated` | provider import 또는 deterministic aggregation action |
+| `imported` | provider 원천 bars가 normalized OHLCV로 저장된다. | `stored` | importer result, `bars` upsert |
+| `aggregated` | 일봉 fixture 또는 저장 데이터에서 월봉 OHLCV가 결정적으로 생성된다. | `stored` | aggregation provenance, deterministic monthly fixture |
+| `stored` | `bars`가 `(instrument_id, timeframe, timestamp)` key로 저장된다. | `backtest-selectable` 또는 `readiness-checked` | storage query, list bars scenario |
+| `backtest-selectable` | `BacktestRunSpec.timeframe`와 selector가 저장 bars를 찾는다. | `backtest-run-terminal` | matrix dry-run, backtest run/result fixture |
+| `readiness-checked` | collection freshness가 timeframe별 latest/missing/gap/duplicate를 계산한다. | terminal | CLI text/JSONL freshness output |
+| `backtest-run-terminal` | engine이 selected bars로 run을 완료한다. | terminal | deterministic result, run status/result summary |
+
+## Interface Contract
+
+- 계약 원문: 없음
+- 입력:
+  - `Timeframe`: proto enum과 domain value, CLI string의 동일 의미 매핑. `daily`, `minute_1`, `minute_5` 기존 vocabulary는 호환 유지하고 `monthly`를 추가한다. D01은 기존 vocabulary 제거 여부가 아니라 1차 import/backtest 검증 baseline에 `minute_5`까지 포함할지 결정한다.
+  - `provider_capability`: provider, market, venue, asset type, timeframe별 accepted/rejected와 거부 사유.
+  - `bar_source`: provider 원천 bars 또는 deterministic aggregation 결과.
+  - `BacktestRunSpec.timeframe`: backtest matrix와 run selector가 사용할 단일 timeframe.
+  - `freshness_request`: universe, timeframe, from/to window, expected dates.
+- 출력:
+  - `Bar`: instrument id, timeframe, timestamp, normalized OHLCV.
+  - `provenance`: 월봉이 provider 원천인지 daily aggregation인지 확인 가능한 근거. 1차 완료 근거는 stable CLI/JSONL 또는 fixture output에 남기고, durable metadata가 필요하면 normalized `bars` key를 깨지 않는 별도 metadata 경계를 둔다.
+  - `readiness`: timeframe별 latest, missing, gap, duplicate, provider delay 상태.
+  - `backtest_result`: timeframe별 deterministic run id, status, result summary.
+- 금지:
+  - unsupported provider/timeframe 조합을 daily로 조용히 fallback하지 않는다.
+  - monthly/daily/minute bars를 같은 query나 result에서 timeframe 구분 없이 섞지 않는다.
+  - provider raw payload를 `bars` table의 정규화 계약에 섞지 않는다.
+  - 여러 timeframe을 동시에 참조하는 전략 DSL은 이번 Milestone에서 확정하지 않는다.
+
+## Acceptance Scenarios
+
+| ID | Milestone Task | Given | When | Then |
+|----|----------------|-------|------|------|
+| S01 | `timeframe-vocab` | 기존 `daily`, `minute_1`, `minute_5` vocabulary와 신규 monthly 요구가 있다. | proto/domain/CLI mapping을 검증한다. | monthly가 추가되고 기존 daily/minute compatibility가 유지된다. |
+| S02 | `capability-matrix` | KIS KR/US venue와 monthly/daily/minute 후보가 있다. | capability matrix validation을 실행한다. | accepted/rejected case와 거부 사유가 명시적으로 나온다. |
+| S03 | `minute-ingest` | 분봉 import 요청 또는 미지원 조합 fixture가 있다. | provider import 또는 reject path를 실행한다. | success 또는 typed rejection이 stable text/JSONL로 남는다. |
+| S04 | `monthly-bars` | 동일 daily fixture와 D02 source-of-truth 결정이 있다. | 월봉 provider import 또는 deterministic aggregation을 실행한다. | deterministic monthly OHLCV와 provenance가 남는다. |
+| S05 | `store-query` | 동일 instrument의 monthly/daily/minute bars가 있다. | 저장 후 timeframe별 조회를 실행한다. | 각 timeframe이 독립 조회되고 서로 섞이지 않는다. |
+| S06 | `run-selector` | monthly/daily/minute scenario matrix가 있다. | dry-run validation과 matrix expand를 실행한다. | timeframe별 run id와 기간 검증 결과가 생성된다. |
+| S07 | `fill-policy` | monthly/daily/minute fixture bars와 동일 전략이 있다. | backtest engine fixture를 실행한다. | timeframe별 deterministic result가 나온다. |
+| S08 | `freshness-readiness` | monthly/daily/minute freshness fixture가 있다. | collection freshness/readiness scenario를 실행한다. | latest/missing/gap/duplicate 상태가 timeframe별로 구분된다. |
+
+## Evidence Map
+
+| Scenario | Required Evidence | `agent-task` 연결 | `Spec Completion` 기대 |
+|----------|-------------------|------------------|---------------------------|
+| S01 | contracts/domain/CLI mapping test | `agent-task/m-backtest-multi-timeframe-coverage/...` | `timeframe-vocab` task와 monthly 추가 및 기존 daily/minute compatibility test 결과 |
+| S02 | capability matrix accepted/rejected tests | `agent-task/m-backtest-multi-timeframe-coverage/...` | `capability-matrix` task와 KIS KR/US case 결과 |
+| S03 | minute import success 또는 typed reject fixture | `agent-task/m-backtest-multi-timeframe-coverage/...` | `minute-ingest` task와 stable text/JSONL evidence |
+| S04 | deterministic monthly OHLCV fixture와 provenance evidence | `agent-task/m-backtest-multi-timeframe-coverage/...` | `monthly-bars` task와 D02 반영 결과 |
+| S05 | storage/query test for `(instrument_id, timeframe, timestamp)` isolation | `agent-task/m-backtest-multi-timeframe-coverage/...` | `store-query` task와 독립 조회 결과 |
+| S06 | matrix expand and dry-run validation output | `agent-task/m-backtest-multi-timeframe-coverage/...` | `run-selector` task와 monthly/daily/minute run id evidence |
+| S07 | deterministic backtest fixture results | `agent-task/m-backtest-multi-timeframe-coverage/...` | `fill-policy` task와 timeframe별 result evidence |
+| S08 | freshness/readiness fixture text/JSONL | `agent-task/m-backtest-multi-timeframe-coverage/...` | `freshness-readiness` task와 timeframe별 latest/missing/gap/duplicate evidence |
+
+## Cross-repo Dependencies
+
+- 없음
+
+## Drift Check
+
+- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
+- [x] Evidence Map이 plan/code-review/complete.log에서 검증 가능하다.
+- [x] agent-contract를 쓰는 경우 SDD에 계약 원문을 복제하지 않았다.
+- [x] 사용자 리뷰가 필요한 항목은 `USER_REVIEW.md`에만 남겼다.
+
+## 사용자 리뷰 이력
+
+- 없음
+
+## 작업 컨텍스트
+
+- 표준선: 일봉 MVP 경로는 이미 완료된 기준선이며 multi-timeframe은 기존 daily 경로를 깨지 않고 additive하게 확장한다.
+- 표준선: proto-socket과 `packages/contracts/proto`가 ALT runtime 사이의 통신 기준이다.
+- 표준선: `services/api`는 얇은 control plane으로 유지하고 provider import, aggregation, backtest execution은 worker 경계에 둔다.
+- 표준선: provider가 직접 제공하지 않는 timeframe은 deterministic aggregation 또는 typed rejection 중 하나로만 처리한다.
+- 표준선: 백테스트는 먼저 단일 timeframe run을 확실히 닫고 multi-timeframe composition은 후속 Milestone으로 미룬다.
+- 후속 SDD: `agent-roadmap/sdd/backtest-loop/scheduled-market-data-refresh/SDD.md`
--- a/agent-roadmap/sdd/backtest-loop/backtest-multi-timeframe-coverage/USER_REVIEW.md
+++ b/agent-roadmap/sdd/backtest-loop/backtest-multi-timeframe-coverage/USER_REVIEW.md
@ -0,0 +1,47 @@
+# SDD User Review
+
+## 상태
+
+요청됨
+
+## 검토 대상
+
+- SDD: `agent-roadmap/sdd/backtest-loop/backtest-multi-timeframe-coverage/SDD.md`
+- Milestone: `agent-roadmap/phase/backtest-loop/milestones/backtest-multi-timeframe-coverage.md`
+
+## 사용자 결정 항목
+
+### [D01] 분봉 1차 검증 baseline
+
+- 결정 필요: 분봉 1차 import/backtest 검증 baseline을 `1m`만으로 시작할지, 기존 vocabulary처럼 `1m`/`5m`를 함께 포함할지 결정한다.
+- 추천안: 기존 proto/domain/CLI vocabulary의 `minute_5`는 호환 유지하고, 1차 import/backtest 검증 baseline에는 `1m`/`5m`를 함께 포함한다. provider capability가 실제 지원 여부를 accepted/rejected로 판정하게 한다.
+- 대안: 기존 `minute_5` vocabulary는 유지하되, 1차 import/backtest 검증 baseline은 `1m`만 닫고 `5m` provider/backtest fixture는 후속으로 미룬다.
+- 영향: scope와 fixture 수가 달라진다. `1m`/`5m`를 함께 검증하면 기존 vocabulary와 더 잘 맞지만 provider별 reject case를 더 명시해야 한다. `1m`만 닫아도 기존 `minute_5` mapping은 제거하지 않는다.
+- 적용 위치:
+  - SDD: `SDD 잠금`, `Interface Contract`, `Acceptance Scenarios`
+  - Milestone: `구현 잠금`, `timeframe-vocab`, `minute-ingest`
+
+### [D02] 월봉 source of truth 우선순위
+
+- 결정 필요: 월봉을 provider 원천 데이터로 우선 받을지, 일봉에서 deterministic aggregation으로 생성할지 기본 우선순위를 결정한다.
+- 추천안: 1차 구현은 일봉 기반 deterministic aggregation을 기본 source of truth로 두고, provider 월봉은 capability가 확인될 때 후속 또는 provider-specific path로 추가한다.
+- 대안: provider 월봉 원천 데이터를 우선하고 일봉 aggregation은 fallback으로 둔다.
+- 영향: provider 의존도와 검증 방식이 달라진다. deterministic aggregation 우선은 현재 daily MVP와 fixture를 재사용하기 쉬운 대신 provenance를 반드시 남겨야 한다.
+- 적용 위치:
+  - SDD: `Source of Truth`, `State Machine`, `Interface Contract`, `Acceptance Scenarios`
+  - Milestone: `구현 잠금`, `monthly-bars`
+
+## 승인 항목
+
+- [ ] 위 결정 항목을 승인했다.
+- [ ] SDD 잠금 해제를 승인했다.
+
+## 답변 기록
+
+- 없음
+
+## 해결 조건
+
+- 모든 사용자 결정 항목의 답변이 SDD에 반영되어 있다.
+- `USER_REVIEW.md`가 `user_review_N.log`로 이동되어 있다.
+- 남은 잠금 항목이 없으면 SDD 상태가 `[승인됨]`이고 `SDD 잠금` 상태가 `해제`다.
--- a/agent-roadmap/sdd/backtest-loop/scheduled-market-data-refresh/SDD.md
+++ b/agent-roadmap/sdd/backtest-loop/scheduled-market-data-refresh/SDD.md
@ -0,0 +1,121 @@
+# SDD: Scheduled Market Data Refresh
+
+## 위치
+
+- Milestone: `agent-roadmap/phase/backtest-loop/milestones/scheduled-market-data-refresh.md`
+- Phase: `agent-roadmap/phase/backtest-loop/PHASE.md`
+
+## 상태
+
+[검토중]
+
+## SDD 잠금
+
+- 상태: 잠금
+- 사용자 리뷰: `USER_REVIEW.md`
+- 잠금 항목:
+  - [ ] [D01] scheduler를 worker 내장 loop, OS/systemd timer, external cron 중 어디까지 1차 구현으로 둘지 확정한다.
+
+## 문제 / 비목표
+
+- 문제: market data import가 수동 scenario 실행에만 의존하면 원격 서버의 backtest input freshness를 반복 확인하기 어렵다. scheduler는 provider 호출, DB upsert, retry/backfill, freshness/readiness, remote smoke까지 같은 운영 경계로 묶어야 한다.
+- 비목표:
+  - Flutter 운영 화면 구현
+  - 새 strategy 판단 로직 또는 투자 의사결정 알고리즘 설계
+  - paper/live order routing과 실거래 adapter 변경
+  - 월봉/분봉 provider import와 backtest engine 지원 확장 전체
+  - 외부 provider credential 값이나 개인 secret 문서화
+
+## Source of Truth
+
+| 영역 | 기준 | 메모 |
+|------|------|------|
+| Roadmap | `agent-roadmap/phase/backtest-loop/milestones/scheduled-market-data-refresh.md` | Milestone 목표, 기능 Task, 범위 제외, 완료 후보 반영 기준 |
+| Code | `services/worker/cmd/alt-worker/main.go` | worker runtime wiring과 job runner 등록 기준 |
+| Code | `services/worker/internal/config/config.go` | worker runtime env/config source of truth. scheduler config는 secret 값을 직접 보관하지 않는다. |
+| Code | `services/worker/internal/jobs/marketdata_jobs.go` | `import_daily_bars` job payload, provider capability gate, importer dispatch 기준 |
+| Code | `services/worker/internal/storage/postgres/queries/queries.sql` | `bars` upsert idempotency 기준 |
+| Code | `apps/cli/internal/operator/scenario.go` | scenario validation, `collection_freshness`, matrix/readiness smoke 기준 |
+| Code | `apps/cli/testdata/operator/headless_validation.md` | operator-facing headless evidence key와 scenario handoff 기준 |
+| External Provider | KIS | scheduled tick이 호출할 provider이며 delay, gap, missing, typed error를 상태로 남겨야 한다. |
+| User Decision | D01 | scheduler 실행 주체와 운영 책임 경계가 구현 잠금 해제 조건이다. |
+
+## State Machine
+
+| 상태 | 진입 조건 | 다음 상태 | 근거 |
+|------|-----------|-----------|------|
+| `config-candidate` | schedule config가 named universe, provider, selector, timeframe, cadence, timezone, backfill window를 선언한다. | `config-valid` 또는 `config-rejected` | validate/dry-run output |
+| `config-rejected` | 필수 필드 누락 또는 provider/timeframe 조합 미지원이다. | terminal | typed validation error, stable text/JSONL |
+| `config-valid` | schedule config가 validation을 통과한다. | `scheduled` | next window calculation |
+| `scheduled` | tick 시간이 도래하거나 manual tick smoke가 실행된다. | `running` 또는 `skipped` | scheduler log/status |
+| `skipped` | 동일 tick이 이미 running이거나 lock/idempotency guard가 막는다. | terminal | duplicate tick evidence |
+| `running` | import job이 provider와 DB upsert를 실행한다. | `succeeded`, `stale`, 또는 `failed` | job result, importer result, DB state |
+| `succeeded` | import와 freshness/readiness가 expected window를 만족한다. | `ready-for-backtest` | status JSONL, freshness output |
+| `stale` | provider delay, missing, gap이 남아 backfill/retry가 필요하다. | `scheduled` 또는 terminal | retry/backfill calculation, stale status |
+| `failed` | provider, config, DB, runtime 오류가 발생한다. | `scheduled` 또는 terminal | last_error, error status |
+| `ready-for-backtest` | scheduler가 적재한 데이터로 selector가 bars를 찾는다. | terminal | backtest matrix/result smoke exit code `0` |
+
+## Interface Contract
+
+- 계약 원문: 없음
+- 입력:
+  - `schedule_config`: named universe별 provider, selector, timeframe, cadence, timezone, backfill window.
+  - `tick`: scheduled 또는 manual smoke로 실행되는 refresh trigger.
+  - `provider_capability`: provider, market, venue, timeframe별 accepted/rejected 판정.
+  - `runtime_env`: provider credential과 DB URL은 config 파일에 쓰지 않고 원격 runtime env/SOPS 주입 경계에서 제공한다.
+  - `freshness_window`: latest, expected dates, missing/gap/duplicate/provider delay를 계산할 기간.
+- 출력:
+  - `refresh_status`: last_success, last_error, next_run, imported bar count, missing/gap/duplicate/provider_delay.
+  - `job_result`: import job success/stale/error와 retry/backfill decision.
+  - `readiness`: backtest selector가 scheduled import 결과를 사용할 수 있는지에 대한 headless result.
+  - `remote_smoke`: migration, runtime startup, tick, freshness query, backtest selector/result scenario exit code.
+- 금지:
+  - schedule config에 secret 값을 저장하지 않는다.
+  - 동일 tick 재실행이 duplicate `bars` row를 만들지 않는다.
+  - provider delay나 gap을 성공으로 조용히 숨기지 않는다.
+  - scheduler가 Flutter 화면 구현을 전제하지 않는다.
+  - 월봉/분봉 import 확장은 이 Milestone에서 새로 확정하지 않고 지원되는 timeframe만 대상으로 삼는다.
+
+## Acceptance Scenarios
+
+| ID | Milestone Task | Given | When | Then |
+|----|----------------|-------|------|------|
+| S01 | `schedule-config` | named universe별 provider, selector, timeframe, cadence, timezone, backfill window가 있다. | validate/dry-run을 실행한다. | next window와 rejected combination이 text/JSONL로 출력된다. |
+| S02 | `scheduled-runner` | 원격 runtime과 idempotent `bars` upsert가 있다. | scheduler tick을 2회 실행한다. | duplicate row 없이 freshness/readiness output이 남는다. |
+| S03 | `retry-backfill` | provider delay, missing, gap fixture가 있다. | retry/backfill calculation을 실행한다. | stale/error 상태와 backfill window가 stable text/JSONL로 구분된다. |
+| S04 | `refresh-status` | success, stale, error 상태가 있다. | status scenario를 실행한다. | last_success, last_error, next_run, bar count, missing/gap/duplicate/provider_delay가 구분된다. |
+| S05 | `backtest-readiness` | scheduler tick이 bars를 적재했다. | remote runner에서 backtest matrix 또는 result summary scenario를 실행한다. | exit code `0`과 result/readiness evidence가 남는다. |
+
+## Evidence Map
+
+| Scenario | Required Evidence | `agent-task` 연결 | `Spec Completion` 기대 |
+|----------|-------------------|------------------|---------------------------|
+| S01 | schedule config validate test와 dry-run text/JSONL | `agent-task/m-scheduled-market-data-refresh/...` | `schedule-config` task와 next window/rejected combination evidence |
+| S02 | duplicate tick smoke, `bars` key 중복 없음, freshness/readiness output | `agent-task/m-scheduled-market-data-refresh/...` | `scheduled-runner` task와 2회 tick idempotency evidence |
+| S03 | missing/gap/provider delay fixture 또는 local smoke | `agent-task/m-scheduled-market-data-refresh/...` | `retry-backfill` task와 stale/error/backfill evidence |
+| S04 | success/stale/error status scenario expected JSONL | `agent-task/m-scheduled-market-data-refresh/...` | `refresh-status` task와 status field evidence |
+| S05 | remote runner smoke after scheduler tick | `agent-task/m-scheduled-market-data-refresh/...` | `backtest-readiness` task와 exit code `0` evidence |
+
+## Cross-repo Dependencies
+
+- 없음
+
+## Drift Check
+
+- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
+- [x] Evidence Map이 plan/code-review/complete.log에서 검증 가능하다.
+- [x] agent-contract를 쓰는 경우 SDD에 계약 원문을 복제하지 않았다.
+- [x] 사용자 리뷰가 필요한 항목은 `USER_REVIEW.md`에만 남겼다.
+
+## 사용자 리뷰 이력
+
+- 없음
+
+## 작업 컨텍스트
+
+- 표준선: 운영 기능은 먼저 화면 없이 CLI, YAML scenario, JSONL/text output, fixture, remote smoke로 검증한다.
+- 표준선: scheduled import는 provider 호출과 DB upsert를 idempotent하게 유지하고 동일 tick 재실행이 중복 row를 만들지 않아야 한다.
+- 표준선: `services/worker`가 데이터 수집, 정규화, backtest, scheduled job처럼 오래 걸리거나 비동기적인 일을 담당한다.
+- 표준선: scheduler config에는 secret 값을 넣지 않고 원격 runtime env/SOPS 주입 경계를 따른다.
+- 표준선: `services/api`는 client-facing 요청을 worker 실행/조회 경계로 중계하는 control plane으로 남긴다.
+- 후속 SDD: 없음
--- a/agent-roadmap/sdd/backtest-loop/scheduled-market-data-refresh/USER_REVIEW.md
+++ b/agent-roadmap/sdd/backtest-loop/scheduled-market-data-refresh/USER_REVIEW.md
@ -0,0 +1,37 @@
+# SDD User Review
+
+## 상태
+
+요청됨
+
+## 검토 대상
+
+- SDD: `agent-roadmap/sdd/backtest-loop/scheduled-market-data-refresh/SDD.md`
+- Milestone: `agent-roadmap/phase/backtest-loop/milestones/scheduled-market-data-refresh.md`
+
+## 사용자 결정 항목
+
+### [D01] scheduler 실행 주체
+
+- 결정 필요: scheduler를 worker 내장 loop, OS/systemd timer, external cron 중 어디까지 1차 구현으로 둘지 확정한다.
+- 추천안: 1차 구현은 `services/worker` 내장 scheduler loop로 두고, OS/systemd는 worker process supervision까지만 맡긴다. external cron은 후속 운영 옵션으로 남긴다.
+- 대안: systemd timer 또는 external cron이 CLI/manual tick을 호출하고 worker는 import/readiness action만 수행한다.
+- 영향: 운영 책임 경계와 failure surface가 달라진다. worker 내장 loop는 ALT runtime 내부에서 status, retry, idempotency를 한곳에 모으기 쉽고, cron 방식은 process lifecycle과 schedule state가 외부로 분산된다.
+- 적용 위치:
+  - SDD: `SDD 잠금`, `State Machine`, `Interface Contract`
+  - Milestone: `구현 잠금`, `schedule-config`, `scheduled-runner`
+
+## 승인 항목
+
+- [ ] 위 결정 항목을 승인했다.
+- [ ] SDD 잠금 해제를 승인했다.
+
+## 답변 기록
+
+- 없음
+
+## 해결 조건
+
+- 모든 사용자 결정 항목의 답변이 SDD에 반영되어 있다.
+- `USER_REVIEW.md`가 `user_review_N.log`로 이동되어 있다.
+- 남은 잠금 항목이 없으면 SDD 상태가 `[승인됨]`이고 `SDD 잠금` 상태가 `해제`다.