# SDD: 지속 갱신 Orchestration

## 위치

- Milestone: [Milestone 문서](../../../phase/workflow-automation/milestones/continuous-refresh-orchestration.md)
- Phase: [PHASE.md](../../../phase/workflow-automation/PHASE.md)

## 상태

[승인됨]

## SDD 잠금

- 상태: 해제
- 사용자 리뷰: 없음
- 잠금 항목:
  - 없음

## 문제 / 비목표

- 문제: workflow runtime과 domain 단계가 있어도 schedule·event·manual trigger를 중복 없이 후보 평가까지 연결하는 표준 갱신 수명주기가 없다.
- 비목표:
  - 평가 통과만으로 production 자동 승격
  - 외부 범용 scheduler 전체 대체
  - 무제한 병렬 refresh

## Source of Truth

| 영역 | 기준 | 메모 |
|------|------|------|
| Roadmap | [Milestone 문서](../../../phase/workflow-automation/milestones/continuous-refresh-orchestration.md) | refresh 범위와 승격 조건 |
| Runtime | [내구성 있는 Workflow Runtime SDD](../durable-workflow-runtime/SDD.md) | lease, retry, cancel과 artifact 계약 |
| Gate | [평가와 승격 Gate SDD](../../quality-governance/evaluation-and-promotion-gates/SDD.md) | candidate evaluation과 promotion 경계 |
| User Decision | 없음 | explicit promotion과 bounded concurrency를 표준선으로 사용한다 |

## State Machine

| 상태 | 진입 조건 | 다음 상태 | 근거 |
|------|-----------|-----------|------|
| queued | 정규화된 trigger와 source revision이 수락됨 | running, superseded, cancelled | refresh run |
| running | workflow lease가 시작됨 | candidate_ready, failed, cancelled | step artifact |
| candidate_ready | index와 evaluation handoff가 완료됨 | completed | candidate identity |
| failed | 재시도 후 step이 실패함 | queued, cancelled | failure artifact |
| completed | candidate와 평가 결과 handoff가 기록됨 | 없음 | terminal event |
| superseded | 같은 revision의 더 이른 run이 소유권을 가짐 | 없음 | dedup record |

## Interface Contract

- 입력: project, knowledge base, source revision, trigger type, policy revision과 idempotency identity
- 출력: refresh run, 단계별 artifact, candidate release, evaluation run과 freshness·cost 지표
- 금지:
  - 같은 knowledge base·source revision을 동시에 둘 이상 실행하지 않는다.
  - 완료 artifact를 무효화하지 않고 처음부터 재실행하지 않는다.
  - refresh completion이 active alias를 직접 변경하지 않는다.

## Acceptance Scenarios

| ID | Milestone Task | Given | When | Then |
|----|----------------|-------|------|------|
| S01 | `trigger-policy` | schedule·event·manual의 같은 revision | 동시 trigger | 하나의 run만 실행되고 나머지는 dedup된다 |
| S02 | `reference-flow` | 유효한 source revision | refresh 실행 | ingest부터 evaluate까지 versioned workflow가 실행된다 |
| S03 | `checkpoint-resume` | 중간 step 완료 후 실패 | 재시도 | 완료 artifact를 재사용해 실패 지점부터 이어간다 |
| S04 | `candidate-handoff` | 평가 통과·실패 candidate | terminal handoff | candidate와 verdict가 gate에 연결되고 alias는 불변이다 |
| S05 | `refresh-observability` | 진행·실패·완료 run | 조회 | freshness·비용·실패 단계·다음 schedule이 노출된다 |

## Evidence Map

| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
|----------|-------------------|------------------|---------------------------|
| S01 | concurrent trigger dedup test | `agent-task/m-continuous-refresh-orchestration/...` | `trigger-policy` single-run evidence |
| S02 | reference workflow integration test | `agent-task/m-continuous-refresh-orchestration/...` | `reference-flow` artifact chain |
| S03 | checkpoint failure injection | `agent-task/m-continuous-refresh-orchestration/...` | `checkpoint-resume` reuse evidence |
| S04 | candidate gate handoff test | `agent-task/m-continuous-refresh-orchestration/...` | `candidate-handoff` no-promotion evidence |
| S05 | refresh metrics·query test | `agent-task/m-continuous-refresh-orchestration/...` | `refresh-observability` evidence |

## Cross-repo Dependencies

- 없음

## Drift Check

- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
- [x] runtime과 promotion gate의 책임을 재사용한다.
- [x] 사용자 리뷰가 필요한 항목이 없다.

## 사용자 리뷰 이력

- 없음

## 작업 컨텍스트

- 표준선: revision idempotency, bounded concurrency, artifact resume, candidate-only handoff
- Milestone은 `[스케치]`이므로 승격 조건이 모두 해소될 때까지 구현 잠금 상태를 유지한다.