rara/agent-roadmap/sdd/quality-governance/retrieval-policy-optimization/SDD.md

SDD: Retrieval 정책 최적화

위치

• Milestone: Milestone 문서
• Phase: PHASE.md

상태

[승인됨]

SDD 잠금

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

문제 / 비목표

• 문제: retrieval과 evaluation 경로가 있어도 chunking·embedding·hybrid·rerank·query 변환 선택을 재현 가능한 정책 실험과 비용 제약으로 개선하는 루프가 없다.
• 비목표:
  • production 자동 승격
  • 범용 AutoML 제품
  • provider 내부 retrieval 알고리즘 구현

Source of Truth

영역	기준	메모
Roadmap	Milestone 문서	정책 최적화 범위와 gate
Evaluation	평가와 승격 Gate SDD	suite, metric과 promotion evidence
Serving	Retrieve와 Answer Pipeline SDD	실행 가능한 retrieval policy 경계
User Decision	없음	자동 승격 금지와 비용 제약을 초기 표준선으로 사용한다

State Machine

상태	진입 조건	다음 상태	근거
pending	policy space와 experiment revision이 검증됨	running, cancelled	experiment row
running	후보 실행이 시작됨	passed, failed, invalid, cancelled	workflow result
passed	필수 품질·지연·비용 gate를 충족함	selected, superseded	metric verdict
failed	필수 gate 또는 regression tolerance를 실패함	pending	result evidence
invalid	provider capability·dataset·suite 계약이 불완전함	pending	validation error
selected	명시적 selection이 candidate policy를 게시함	superseded	selection record
superseded	더 최신 candidate가 선택됨	없음	lineage

Interface Contract

• 입력:
  • policy_space_revision: chunking, embedding, hybrid, rerank와 query transformation 후보
  • experiment_revision: dataset, suite, provider revision, seed와 budget
  • constraint_policy: required quality, regression tolerance, latency와 cost limit
• 출력:
  • 후보별 metrics, usage, lineage와 verdict
  • immutable candidate policy snapshot
  • evaluation·promotion gate가 소비할 selection evidence
• 금지:
  • 비교 중 dataset·suite·provider revision을 변경하지 않는다.
  • 품질 점수만으로 latency·cost hard limit를 무시하지 않는다.
  • selected policy가 active release alias를 직접 변경하지 않는다.

Acceptance Scenarios

ID	Milestone Task	Given	When	Then
S01	policy-space	provider capability와 policy 후보	validation	실행 가능한 조합만 experiment에 들어간다
S02	experiment-snapshot	dataset·suite·provider·seed·budget	revision 생성	재실행 가능한 불변 snapshot이 생성된다
S03	offline-comparison	candidate와 baseline	동일 조건 실행	품질·latency·cost와 lineage가 함께 기록된다
S04	constraint-gates	metric과 hard budget	verdict 계산	필수 gate 실패 후보는 선택 대상에서 제외된다
S05	candidate-selection	둘 이상의 통과 후보	selection	근거와 immutable policy snapshot이 게시된다
S06	promotion-handoff	selected policy와 evaluation evidence	handoff	승격 gate가 소비하되 active alias는 바뀌지 않는다

Evidence Map

Scenario	Required Evidence	agent-task 연결	완료 Evidence 기대
S01	capability·policy validation matrix	agent-task/m-retrieval-policy-optimization/...	policy-space accept·reject evidence
S02	revision immutability·replay test	agent-task/m-retrieval-policy-optimization/...	experiment-snapshot reproducibility
S03	same-condition comparison run	agent-task/m-retrieval-policy-optimization/...	offline-comparison metric lineage
S04	quality·latency·cost gate matrix	agent-task/m-retrieval-policy-optimization/...	constraint-gates verdict
S05	deterministic candidate selection test	agent-task/m-retrieval-policy-optimization/...	candidate-selection snapshot
S06	no-auto-promotion integration test	agent-task/m-retrieval-policy-optimization/...	promotion-handoff boundary evidence

Cross-repo Dependencies

• 없음

Drift Check

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

사용자 리뷰 이력

• 없음

작업 컨텍스트

• 표준선: immutable experiment, capability-aware policy space, multi-objective gate, explicit promotion
• 후속 SDD: 지속 갱신 Orchestration