add agent-roadmap

agent-roadmap/ROADMAP.md

@@ -0,0 +1,58 @@
+# 로드맵
+
+## 고정 실행 순서
+
+- 전역 Milestone 실행 순서는 [전역 마일스톤 실행 순서](priority-queue.md)를 먼저 확인한다.
+- Phase는 도메인/책임 영역이며 순차 실행 게이트가 아니다.
+- Phase 흐름과 상태는 로드맵 구조를 설명하고, 실제 다음 작업 선택은 `priority-queue.md`의 위아래 순서를 우선한다.
+- `priority-queue.md`는 순서 전용 문서이며, 상태, 목표, 범위, 잠금, 기능, 완료 근거는 각 Milestone 문서를 원본으로 삼는다.
+- `priority-queue.md` 항목은 Milestone 제목 링크와 식별용 한 줄 설명만 둔다.
+- `priority-queue.md`는 사용자가 순서 조정을 요청한 경우, Milestone archive 시 완료 항목 제거가 필요한 경우, 큐에 있는 Milestone이 폐기, 경로 변경, split/merge, 또는 실행 의미가 바뀔 정도로 수정된 경우에만 재정렬한다.
+
+## 전체 목표
+
+RARA는 프로젝트마다 달라지는 저장소와 모델 제품을 교체 가능한 integration 뒤에 두면서, 소스 수집부터 검색·응답·평가·릴리스·지속 갱신까지 RAG 수명주기를 표준화하는 운영 플랫폼이 된다. 검증된 데이터는 선택적으로 LoRA/QLoRA adaptation으로 승격할 수 있지만, 주 책임은 최신성과 품질이 관리되는 RAG 운영에 둔다.
+
+## Phase 흐름
+
+Phase는 실행 순서가 아니라 도메인/책임 영역의 구조적 지도다.
+완료된 Phase도 로드맵에서 제거하지 않고, archive의 Phase 문서로 연결한다.
+실제 다음 작업 선택은 [전역 마일스톤 실행 순서](priority-queue.md)의 위아래 순서를 우선한다.
+
+- [진행중] 플랫폼 기반
+  - 경로: [PHASE.md](phase/platform-foundation/PHASE.md)
+  - 요약: integration 카탈로그, secret·artifact 경계와 project-scoped Control Plane API를 제품 중립적으로 고정한다.
+- [계획] 워크플로우 자동화
+  - 경로: [PHASE.md](phase/workflow-automation/PHASE.md)
+  - 요약: 장시간 실행과 재시도에 안전한 workflow runtime과 지속 갱신 루프를 제공한다.
+- [계획] 지식 수명주기
+  - 경로: [PHASE.md](phase/knowledge-lifecycle/PHASE.md)
+  - 요약: 소스 변경을 정규화된 버전 데이터셋과 lineage로 전환한다.
+- [계획] RAG 서빙
+  - 경로: [PHASE.md](phase/rag-serving/PHASE.md)
+  - 요약: 후보 인덱스 게시부터 버전이 식별되는 retrieve·answer까지 온라인 경로를 완성한다.
+- [계획] 품질 거버넌스
+  - 경로: [PHASE.md](phase/quality-governance/PHASE.md)
+  - 요약: 평가, retrieval 정책 최적화, 승격, 롤백, drift와 feedback으로 품질 변화를 통제한다.
+- [스케치] 선택적 adaptation
+  - 경로: [PHASE.md](phase/selective-adaptation/PHASE.md)
+  - 요약: 검증된 데이터만 훈련 데이터셋과 선택적 LoRA/QLoRA 실행으로 승격한다.
+- [스케치] 운영 제품화
+  - 경로: [PHASE.md](phase/operations-productization/PHASE.md)
+  - 요약: identity·권한·감사, 운영 UI와 production 신뢰성 경계를 완성한다.
+
+## 로딩 정책
+
+- 일반 작업에서는 [ROADMAP.md](ROADMAP.md)를 매번 읽지 않는다.
+- Phase를 가로지르는 다음 작업 후보를 고를 때는 [전역 마일스톤 실행 순서](priority-queue.md)를 먼저 확인한다.
+- 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 [current.md](current.md)를 먼저 읽는다.
+- `current.md`는 현재 작업 위치가 아니라 활성 Phase와 활성 Milestone 후보 목록이다.
+- `current.md`는 브랜치별 로컬 포인터이며 git 추적 대상이 아니다.
+- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 활성 Phase와 Milestone 문서를 같은 세션에서 1회 읽는다.
+- 상세 작업은 각 Milestone 문서의 `기능`으로 관리한다. 검증이 필요한 기능만 같은 Task 안에 `검증:`으로 통합한다.
+- 큰 Milestone의 설계 게이트는 [SDD 디렉터리](sdd/)에 두고, Milestone `구현 잠금`의 SDD 조건과 연결한다.
+- `[스케치]` Phase/Milestone은 구현 계획 생성 대상이 아니며 `승격 조건`을 해소한 뒤 `[계획]`으로 전환한다.
+- 모든 기능 Task와 검증이 충족된 Milestone은 먼저 `[검토중]`으로 두고, 완료 근거와 archive 조건이 정리되면 `[완료]`로 전환한다.
+- `agent-roadmap/archive/**`는 일반 작업에서 읽지 않는다.
+- 선택된 Milestone의 `구현 잠금`이 `잠금`이거나 미완료 `결정 필요` 항목이 있으면 구현 계획과 코드 구현을 시작하지 않는다.
+- `SDD: 필요` Milestone은 SDD 상태가 `[승인됨]`이고 SDD 잠금이 해제되었으며 사용자 리뷰가 없어야 구현 계획을 만들 수 있다.

agent-roadmap/phase/knowledge-lifecycle/PHASE.md

@@ -0,0 +1,23 @@
+# Phase: 지식 수명주기
+
+## 상태
+
+[계획]
+
+## 목표
+
+외부 소스의 추가·변경·삭제·ACL 변화를 일관된 변경 스트림으로 받아 정규화된 dataset version과 artifact lineage로 만든다. 저장소 제품과 무관하게 동일한 최신화·재처리·재현성 계약을 제공한다.
+
+## Milestone 흐름
+
+Phase를 가로지르는 실제 다음 작업 선택은 [전역 마일스톤 실행 순서](../../priority-queue.md)를 우선한다.
+
+- [계획] 수집과 Dataset 수명주기
+  - 경로: [수집과 Dataset 수명주기](milestones/ingestion-and-dataset-lifecycle.md)
+  - 요약: source cursor, tombstone, 정규화, versioning과 lineage를 한 수집 수명주기로 완성한다.
+
+## Phase 경계
+
+- source connector는 제품별 읽기 동작만 담당하고 dataset 상태와 lineage는 RARA가 소유한다.
+- 원본 snapshot, 정규화 결과와 retrieval dataset은 서로 다른 불변 version으로 남긴다.
+- source 삭제와 ACL 변경을 단순 upsert로 덮어쓰지 않는다.

agent-roadmap/phase/knowledge-lifecycle/milestones/ingestion-and-dataset-lifecycle.md

@@ -0,0 +1,78 @@
+# Milestone: 수집과 Dataset 수명주기
+
+## 위치
+
+- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
+- Phase: [PHASE.md](../PHASE.md)
+
+## 목표
+
+외부 source change stream을 replay 가능한 raw snapshot, 정규화 artifact와 versioned dataset으로 전환한다. 추가·수정뿐 아니라 삭제, ACL과 source revision을 lineage에 남겨 최신화와 재처리를 재현 가능하게 한다.
+
+## 상태
+
+[계획]
+
+## 구현 잠금
+
+- 상태: 해제
+- SDD: 필요
+- SDD 문서: [SDD.md](../../../sdd/knowledge-lifecycle/ingestion-and-dataset-lifecycle/SDD.md)
+- SDD 사유: source cursor, tombstone, dataset version, artifact lineage와 재처리 lifecycle을 정의한다.
+- 잠금 해제 조건:
+  - [x] SDD 잠금이 해제되어 있다.
+  - [x] SDD 사용자 리뷰가 없거나 승인/해결되었다.
+  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
+  - [x] Evidence Map이 완료 시 Roadmap Completion과 최종 검증 evidence로 검증 가능하게 연결되어 있다.
+- 결정 필요: 없음
+
+## 범위
+
+- source registration, cursor, revision과 incremental/full sync
+- upsert, delete tombstone, ACL change와 replay 가능한 raw snapshot
+- parser·normalizer·chunker adapter와 canonical document schema
+- raw, normalized, retrieval dataset version과 artifact lineage
+- content hash deduplication, quarantine와 deterministic rebuild
+- source connector conformance와 restart smoke
+
+## 기능
+
+### Epic: [source-sync] 변경 수집
+
+제품별 source 변화를 공통 change stream과 cursor로 정규화한다.
+
+- [ ] [source-cursor] full·incremental sync cursor와 source revision을 원자적으로 기록하고 재시작 시 마지막 확정 지점부터 이어간다.
+- [ ] [change-semantics] upsert, tombstone, ACL change를 구분하고 삭제된 문서가 다음 dataset에 남지 않게 한다.
+- [ ] [connector-conformance] fake connector와 최소 실제 connector가 paging, retry, tombstone과 cursor conformance suite를 통과한다.
+
+### Epic: [dataset] 불변 Dataset과 Lineage
+
+동일 입력과 recipe에서 동일한 dataset version을 재현한다.
+
+- [ ] [normalization] parser·normalizer·chunker 결과를 canonical schema와 versioned recipe로 저장한다.
+- [ ] [dataset-version] raw, normalized, retrieval dataset을 불변 version과 content hash로 게시한다.
+- [ ] [artifact-lineage] source revision부터 chunk·dataset artifact까지 parent-child lineage와 생성 step을 추적한다.
+- [ ] [rebuild-recovery] 실패 artifact를 격리하고 동일 revision 재실행에서 확정된 결과를 재사용한다. 검증: PostgreSQL과 filesystem artifact store를 사용한 중단·재개 smoke가 통과한다.
+
+## 완료 리뷰
+
+- 상태: 없음
+- 요청일: 없음
+- 완료 근거: 모든 기능 Task와 검증 충족 및 구현 잠금 해제 여부를 완료 시 기록한다.
+- 검토 항목: source replay, tombstone·ACL, deterministic rebuild와 lineage evidence
+- agent-ui 상태 반영: 해당 없음
+- 리뷰 코멘트: 없음
+
+## 범위 제외
+
+- retrieval backend index 작성과 release 승격
+- 특정 문서 저장소를 기본 source로 강제
+- 원본 대용량 content를 PostgreSQL row에 직접 저장
+
+## 작업 컨텍스트
+
+- 관련 경로: `packages/go/integration/`, `packages/go/controlplane/`, `packages/go/artifact/`, `db/`
+- 표준선(선택): immutable dataset version, content-addressed artifact, cursor commit after durable artifact
+- 선행 작업: [Integration 카탈로그와 Secret 경계](../../platform-foundation/milestones/integration-catalog-and-secrets.md), [내구성 있는 Workflow Runtime](../../workflow-automation/milestones/durable-workflow-runtime.md)
+- 후속 작업: [Index 게시와 Release 수명주기](../../rag-serving/milestones/index-publication-and-release.md)
+- 확인 필요: 없음

agent-roadmap/phase/operations-productization/PHASE.md

@@ -0,0 +1,29 @@
+# Phase: 운영 제품화
+
+## 상태
+
+[스케치]
+
+## 목표
+
+여러 프로젝트와 workflow를 하나의 플랫폼에서 안전하게 운영할 수 있도록 격리, 권한, 감사, UI와 production 운영 경계를 제공한다. 내부 API를 먼저 안정화한 뒤 운영자 경험과 배포 형태를 확정한다.
+
+## Milestone 흐름
+
+Phase를 가로지르는 실제 다음 작업 선택은 [전역 마일스톤 실행 순서](../../priority-queue.md)를 우선한다.
+
+- [스케치] Identity·권한과 감사
+  - 경로: [Identity·권한과 감사](milestones/multi-project-security-and-audit.md)
+  - 요약: 공통 project boundary 위에 identity 연동, 세분화된 권한, audit와 retention을 설계한다.
+- [스케치] 운영 UI
+  - 경로: [운영 UI](milestones/operations-ui.md)
+  - 요약: 공통 Control Plane API를 소비하는 운영 화면과 승인 경험을 제품화한다.
+- [스케치] Production 신뢰성
+  - 경로: [Production 신뢰성](milestones/production-reliability.md)
+  - 요약: 배포 profile, backup·restore, 관측성과 재해 복구를 제품화한다.
+
+## Phase 경계
+
+- UI가 안정되지 않은 내부 계약을 별도로 재정의하지 않고 control-plane API를 소비한다.
+- 인증 공급자와 배포 환경은 adapter 또는 deployment profile로 분리한다.
+- production 운영을 위해 retrieval·artifact 저장소를 RARA 자체 구현으로 고정하지 않는다.

agent-roadmap/phase/operations-productization/milestones/multi-project-security-and-audit.md

@@ -0,0 +1,88 @@
+# Milestone: Identity·권한과 감사
+
+## 위치
+
+- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
+- Phase: [PHASE.md](../PHASE.md)
+
+## 목표
+
+[Control Plane Resource API](../../platform-foundation/milestones/control-plane-resource-api.md)가 강제하는 project boundary 위에 사용자·서비스 identity, 세분화된 권한, secret 접근, 감사와 데이터 보존 정책을 제품화한다.
+
+## 상태
+
+[스케치]
+
+## 승격 조건
+
+- [ ] RARA 내장 인증과 외부 identity provider 연동의 책임 경계를 결정한다.
+- [ ] project·service account·role·permission 모델을 정의한다.
+- [ ] audit event와 trace retention·redaction 정책을 정의한다.
+- [ ] secret resolver의 identity·permission 강제 지점을 정의한다.
+- [x] 보안·보존·API lifecycle을 다루는 SDD 필요성을 확정하고 초안을 작성했다.
+
+## 구현 잠금
+
+- 상태: 잠금
+- SDD: 필요
+- SDD 문서: [SDD.md](../../../sdd/operations-productization/multi-project-security-and-audit/SDD.md)
+- SDD 사유: external identity mapping, authorization, secret resolution, immutable audit와 retention 계약을 정의한다.
+- 잠금 해제 조건:
+  - [ ] SDD 잠금이 해제되어 있다.
+  - [ ] SDD 사용자 리뷰가 승인/해결되었다.
+  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
+  - [x] Evidence Map이 완료 시 Roadmap Completion과 최종 검증 evidence로 검증 가능하게 연결되어 있다.
+  - [ ] 모든 승격 조건이 해소되고 Milestone 상태가 `[계획]`이다.
+- 결정 필요:
+  - 초기 인증 source of truth를 RARA가 소유할지 외부 identity provider에 위임할지
+
+## 범위
+
+- external user·service identity mapping과 project membership
+- role·permission과 API·worker authorization
+- integration secret reference의 project scope
+- immutable audit event와 actor·reason
+- query·answer·feedback retention, redaction와 deletion
+- authorization·secret·audit tampering negative test
+
+## 기능
+
+### Epic: [access] Identity와 권한
+
+공통 project boundary 위에서 actor의 resource·action 권한을 일관되게 판정한다.
+
+- [ ] [identity-boundary] user, service account와 external identity mapping의 source of truth와 동기화 책임을 정의한다.
+- [ ] [rbac] project role과 resource·action permission을 정의하고 API·worker에 적용한다.
+- [ ] [secret-scope] secret reference가 다른 project 또는 unauthorized executor에서 resolve되지 않게 한다.
+
+### Epic: [audit] 감사와 데이터 보존
+
+민감 원문을 과도하게 저장하지 않으면서 변경 근거를 추적한다.
+
+- [ ] [audit-events] actor, action, target, reason, result와 correlation identity를 immutable event로 남긴다.
+- [ ] [retention-policy] trace, feedback, dataset와 audit 유형별 retention·redaction·deletion 정책을 적용한다.
+- [ ] [isolation-tests] unauthorized action·secret 접근, identity mapping 오류와 audit tampering negative test를 제공한다.
+
+## 완료 리뷰
+
+- 상태: 없음
+- 요청일: 없음
+- 완료 근거: 스케치 단계이며 `[계획]` 승격 뒤 기록한다.
+- 검토 항목: 사용자 결정, 승격 조건과 후속 SDD gate
+- agent-ui 상태 반영: 해당 없음
+- 리뷰 코멘트: 없음
+
+## 범위 제외
+
+- identity provider 제품 자체 구현
+- project-scoped resource identity와 기본 cross-project 차단의 재구현
+- retrieval backend의 vendor 내부 ACL 엔진 대체
+- 운영 조직의 compliance 인증 절차
+
+## 작업 컨텍스트
+
+- 관련 경로: `apps/`, `packages/go/`, `packages/python/`, `db/`, `configs/`
+- 표준선(선택): deny-by-default, project-scoped identity, secret reference, immutable audit
+- 선행 작업: [Control Plane Resource API](../../platform-foundation/milestones/control-plane-resource-api.md), [평가와 승격 Gate](../../quality-governance/milestones/evaluation-and-promotion-gates.md)
+- 후속 작업: [운영 UI](operations-ui.md), [Production 신뢰성](production-reliability.md)
+- 확인 필요: `구현 잠금 > 결정 필요`

agent-roadmap/phase/operations-productization/milestones/operations-ui.md

@@ -0,0 +1,79 @@
+# Milestone: 운영 UI
+
+## 위치
+
+- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
+- Phase: [PHASE.md](../PHASE.md)
+
+## 목표
+
+운영자가 프로젝트, integration, source, workflow, dataset, evaluation과 release를 데이터베이스나 내부 파일을 직접 조회하지 않고 관찰·제어할 수 있게 한다. UI는 공통 Control Plane API와 권한·감사 계약만 소비한다.
+
+## 상태
+
+[스케치]
+
+## 승격 조건
+
+- [ ] 첫 사용자 역할과 역할별 핵심 운영 여정을 확정한다.
+- [ ] 브라우저 중심 Flutter UI와 다른 전달 형태 중 초기 delivery surface를 확정한다.
+- [ ] resource·workflow·quality 화면의 최소 정보 구조와 승인 동작을 정의한다.
+- [ ] agent-ui를 생성하고 Control Plane API·권한 계약과 연결한다.
+- [x] API·권한·승인 흐름을 다루는 SDD 필요성을 확정하고 초안을 작성했다.
+
+## 구현 잠금
+
+- 상태: 잠금
+- SDD: 필요
+- SDD 문서: [SDD.md](../../../sdd/operations-productization/operations-ui/SDD.md)
+- SDD 사유: UI 소비 API, 사용자 역할, 권한, 수동 promotion·rollback과 audit 계약을 정의한다.
+- 잠금 해제 조건:
+  - [ ] SDD 잠금이 해제되어 있다.
+  - [ ] SDD 사용자 리뷰가 승인/해결되었다.
+  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
+  - [x] Evidence Map이 완료 시 Roadmap Completion과 최종 검증 evidence로 검증 가능하게 연결되어 있다.
+  - [ ] 모든 승격 조건이 해소되고 Milestone 상태가 `[계획]`이다.
+- 결정 필요:
+  - 첫 운영 UI의 delivery surface와 우선 사용자 역할
+
+## 범위
+
+- project·integration·source·knowledge base 관리 화면
+- workflow run·step, dataset lineage와 artifact 탐색
+- evaluation 비교, release promotion·rollback 승인 흐름
+- 권한에 따른 action 노출과 audit reason 입력
+- health·readiness·SLO 상태 조회
+
+## 기능
+
+### Epic: [ops-ui] 운영자 Workflow
+
+공통 API가 제공하는 상태와 명령을 역할에 맞는 운영 여정으로 구성한다.
+
+- [ ] [resource-ui] project, integration, source와 knowledge base 상태를 조회·관리한다.
+- [ ] [workflow-ui] workflow run, step progress, retry·cancel과 artifact lineage를 탐색한다.
+- [ ] [quality-ui] evaluation 비교, promotion eligibility, 수동 승격과 rollback을 audit reason과 함께 제공한다.
+- [ ] [accessibility-state] loading·empty·error·forbidden·stale revision 상태와 접근성 기준을 일관되게 표현한다.
+
+## 완료 리뷰
+
+- 상태: 없음
+- 요청일: 없음
+- 완료 근거: 스케치 단계이며 `[계획]` 승격 뒤 기록한다.
+- 검토 항목: 사용자 결정, agent-ui, API·권한·승인 흐름
+- agent-ui 상태 반영: 해당 없음
+- 리뷰 코멘트: `[계획]` 승격 시 agent-ui 생성과 상태 반영 방식을 함께 확정한다.
+
+## 범위 제외
+
+- UI가 Control Plane 외 별도 운영 상태를 소유하는 구조
+- production 배포·backup·restore 구현
+- identity provider 제품 자체 구현
+
+## 작업 컨텍스트
+
+- 관련 경로: `apps/client/`, `api/openapi/`, `agent-ui/`
+- 표준선(선택): API-first UI, least privilege, explicit destructive action, auditable approval
+- 선행 작업: [Control Plane Resource API](../../platform-foundation/milestones/control-plane-resource-api.md), [Identity·권한과 감사](multi-project-security-and-audit.md)
+- 후속 작업: [Production 신뢰성](production-reliability.md)
+- 확인 필요: `구현 잠금 > 결정 필요`

agent-roadmap/phase/operations-productization/milestones/production-reliability.md

@@ -0,0 +1,85 @@
+# Milestone: Production 신뢰성
+
+## 위치
+
+- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
+- Phase: [PHASE.md](../PHASE.md)
+
+## 목표
+
+RARA를 선택한 production 환경에 반복 배포하고, PostgreSQL 제어 상태와 외부 artifact·index 참조를 일관되게 백업·복구하며, 핵심 SLO와 장애 대응을 검증 가능한 운영 profile로 제공한다.
+
+## 상태
+
+[스케치]
+
+## 승격 조건
+
+- [ ] 첫 production 배포 profile의 목표 환경과 지원 topology를 확정한다.
+- [ ] PostgreSQL, artifact와 retrieval backend의 backup·restore 책임 경계를 확정한다.
+- [ ] 초기 SLO·RPO·RTO와 alert ownership을 정의한다.
+- [ ] migration, restart, restore와 provider outage 검증 범위를 정의한다.
+- [x] 배포·복구·SLO lifecycle을 다루는 SDD 필요성을 확정하고 초안을 작성했다.
+
+## 구현 잠금
+
+- 상태: 잠금
+- SDD: 필요
+- SDD 문서: [SDD.md](../../../sdd/operations-productization/production-reliability/SDD.md)
+- SDD 사유: deployment profile, migration, backup·restore, SLO와 disaster recovery 계약을 정의한다.
+- 잠금 해제 조건:
+  - [ ] SDD 잠금이 해제되어 있다.
+  - [ ] SDD 사용자 리뷰가 승인/해결되었다.
+  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
+  - [x] Evidence Map이 완료 시 Roadmap Completion과 최종 검증 evidence로 검증 가능하게 연결되어 있다.
+  - [ ] 모든 승격 조건이 해소되고 Milestone 상태가 `[계획]`이다.
+- 결정 필요:
+  - 첫 production 배포 profile의 목표 환경
+
+## 범위
+
+- 로컬·단일 노드와 선택한 production deployment profile
+- 구성·secret·migration·rolling restart 경계
+- PostgreSQL control state와 외부 artifact·index pointer backup·restore
+- ingestion freshness, workflow latency, RAG latency·error와 provider health SLO
+- restore·provider outage·migration disaster smoke
+
+## 기능
+
+### Epic: [production] 배포와 변경
+
+배포 환경별 차이를 profile로 제한하고 schema·service 변경을 반복 가능하게 만든다.
+
+- [ ] [deployment-profiles] 로컬·단일 노드와 선택한 production profile의 topology, 구성, secret와 resource requirement를 제공한다.
+- [ ] [migration-rollout] schema migration, service rollout·rollback과 compatibility preflight를 자동화한다.
+
+### Epic: [reliability] 복구와 관측
+
+상태 저장소가 분리된 구조에서도 복구 순서와 운영 목표를 검증한다.
+
+- [ ] [backup-restore] PostgreSQL과 외부 artifact·index pointer의 일관된 backup·restore 절차와 manifest를 제공한다.
+- [ ] [slo-observability] freshness, workflow, RAG와 provider health SLI·SLO·alert를 노출한다.
+- [ ] [disaster-smoke] migration, rolling restart, restore와 provider outage smoke를 자동화하고 RPO·RTO evidence를 남긴다.
+
+## 완료 리뷰
+
+- 상태: 없음
+- 요청일: 없음
+- 완료 근거: 스케치 단계이며 `[계획]` 승격 뒤 기록한다.
+- 검토 항목: 사용자 결정, backup consistency, restore rehearsal와 SLO evidence
+- agent-ui 상태 반영: 해당 없음
+- 리뷰 코멘트: 없음
+
+## 범위 제외
+
+- 모든 cloud·orchestrator 환경 동시 지원
+- retrieval·artifact 저장소 제품 자체 구현
+- 조직 전체 incident management 제품 구현
+
+## 작업 컨텍스트
+
+- 관련 경로: `configs/`, `deploy/`, `db/`, `apps/`
+- 표준선(선택): profile-based deployment, tested restore, observable SLO, explicit RPO·RTO
+- 선행 작업: [Identity·권한과 감사](multi-project-security-and-audit.md), [운영 UI](operations-ui.md)
+- 후속 작업: 없음
+- 확인 필요: `구현 잠금 > 결정 필요`

agent-roadmap/phase/platform-foundation/PHASE.md

@@ -0,0 +1,30 @@
+# Phase: 플랫폼 기반
+
+## 상태
+
+[진행중]
+
+## 목표
+
+RARA의 각 plane이 공통으로 사용하는 실행·설정·관측·integration 기반을 안정화한다. 외부 제품은 versioned capability와 secret reference를 가진 adapter 뒤에 두고, 공통 계층에는 RAG·workflow 정책을 넣지 않는다.
+
+## Milestone 흐름
+
+Phase를 가로지르는 실제 다음 작업 선택은 [전역 마일스톤 실행 순서](../../priority-queue.md)를 우선한다.
+
+- [검토중] 플랫폼 스캐폴드 기준선
+  - 경로: [플랫폼 스캐폴드 기준선](milestones/platform-scaffold-baseline.md)
+  - 요약: 현재 Go·Python·PostgreSQL 스캐폴드와 검증 흐름을 첫 기준선으로 닫는다.
+- [계획] Integration 카탈로그와 Secret 경계
+  - 경로: [Integration 카탈로그와 Secret 경계](milestones/integration-catalog-and-secrets.md)
+  - 요약: provider capability, 구성 검증, secret resolution과 runtime binding을 표준화한다.
+- [계획] Control Plane Resource API
+  - 경로: [Control Plane Resource API](milestones/control-plane-resource-api.md)
+  - 요약: 프로젝트 경계, resource lifecycle, 일관된 오류·페이지네이션·동시성 계약을 제공한다.
+
+## Phase 경계
+
+- 공통 계층은 plane별 수명주기와 온라인 RAG 정책을 소유하지 않는다.
+- PostgreSQL은 제어 상태만 저장하며 retrieval index와 대형 artifact를 내장 책임으로 삼지 않는다.
+- 특정 vendor SDK 타입과 credential 원문을 공통 계약에 노출하지 않는다.
+- 모든 관리 resource는 project scope를 필수 경계로 사용하며 교차 프로젝트 접근을 기본 거부한다.

agent-roadmap/phase/platform-foundation/milestones/control-plane-resource-api.md

@@ -0,0 +1,76 @@
+# Milestone: Control Plane Resource API
+
+## 위치
+
+- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
+- Phase: [PHASE.md](../PHASE.md)
+
+## 목표
+
+project를 격리 root로 두고 knowledge base, source, dataset, workflow, evaluation과 release를 동일한 관리 계약으로 생성·조회·변경할 수 있게 한다. 모든 project-owned 요청은 project scope를 강제하고 장시간 실행·온라인 RAG·운영 UI가 재사용할 안정적인 Control Plane 경계를 제공한다.
+
+## 상태
+
+[계획]
+
+## 구현 잠금
+
+- 상태: 해제
+- SDD: 필요
+- SDD 문서: [SDD.md](../../../sdd/platform-foundation/control-plane-resource-api/SDD.md)
+- SDD 사유: resource API, project isolation, idempotency, optimistic concurrency와 오류 schema를 정의한다.
+- 잠금 해제 조건:
+  - [x] SDD 잠금이 해제되어 있다.
+  - [x] SDD 사용자 리뷰가 없거나 승인/해결되었다.
+  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
+  - [x] Evidence Map이 완료 시 Roadmap Completion과 최종 검증 evidence로 검증 가능하게 연결되어 있다.
+- 결정 필요: 없음
+
+## 범위
+
+- project root identity와 project-owned resource identity
+- knowledge base, source, dataset, workflow, evaluation과 release 관리 API
+- cursor pagination, filter, stable error와 revision 기반 optimistic concurrency
+- mutation idempotency와 conflict 의미
+- OpenAPI·내부 계약 포인터와 lifecycle contract test
+
+## 기능
+
+### Epic: [resources] 공통 Resource 수명주기
+
+각 도메인이 서로 다른 관리 API 의미를 재정의하지 않게 공통 경계를 만든다.
+
+- [ ] [project-boundary] project를 격리 root로 정의하고 모든 project-owned resource identity와 query에 project scope를 강제하며 교차 프로젝트 접근을 기본 거부한다.
+- [ ] [resource-lifecycle] project, knowledge base, source, dataset, workflow, evaluation과 release의 생성·조회·목록·변경·비활성화 계약을 제공한다.
+- [ ] [api-consistency] cursor pagination, filter, stable error envelope과 revision 기반 optimistic concurrency를 일관되게 적용한다.
+- [ ] [mutation-idempotency] 생성과 명령형 변경에 idempotency key, replay와 conflict 의미를 적용한다.
+
+### Epic: [contracts] 소비자 계약
+
+CLI, UI, worker와 외부 자동화가 같은 계약을 검증할 수 있게 한다.
+
+- [ ] [management-contract] 관리 API를 versioned OpenAPI로 게시하고 `agent-contract`가 도입되면 원문 포인터를 연결한다.
+- [ ] [lifecycle-tests] resource별 상태 전이, idempotency, stale revision과 cross-project read·write negative contract test를 제공한다.
+
+## 완료 리뷰
+
+- 상태: 없음
+- 요청일: 없음
+- 완료 근거: 모든 기능 Task와 검증 충족 및 구현 잠금 해제 여부를 완료 시 기록한다.
+- 검토 항목: project scope 강제, replay·conflict 의미, resource lifecycle과 계약 호환성
+- agent-ui 상태 반영: 해당 없음
+- 리뷰 코멘트: 없음
+
+## 범위 제외
+
+- 외부 identity provider 연동과 세분화된 RBAC
+- online retrieve·answer data plane
+- 운영 UI 구현
+
+## 작업 컨텍스트
+
+- 관련 경로: `apps/control-plane/`, `api/openapi/`, `packages/go/controlplane/`, `db/`
+- 표준선(선택): project-scoped identity, stable error, cursor pagination, optimistic concurrency, idempotent mutation
+- 선행 작업: [Integration 카탈로그와 Secret 경계](integration-catalog-and-secrets.md)
+- 후속 작업: [내구성 있는 Workflow Runtime](../../workflow-automation/milestones/durable-workflow-runtime.md), [수집과 Dataset 수명주기](../../knowledge-lifecycle/milestones/ingestion-and-dataset-lifecycle.md)
+- 확인 필요: 없음

agent-roadmap/phase/platform-foundation/milestones/integration-catalog-and-secrets.md

@@ -0,0 +1,76 @@
+# Milestone: Integration 카탈로그와 Secret 경계
+
+## 위치
+
+- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
+- Phase: [PHASE.md](../PHASE.md)
+
+## 목표
+
+source, retrieval, artifact, embedding, rerank, generation과 executor 구현을 versioned capability로 등록·검증·비활성화할 수 있게 한다. 구성에는 secret 원문을 저장하지 않고 runtime secret resolver를 통해 필요한 시점에만 주입한다.
+
+## 상태
+
+[계획]
+
+## 구현 잠금
+
+- 상태: 해제
+- SDD: 필요
+- SDD 문서: [SDD.md](../../../sdd/platform-foundation/integration-catalog-and-secrets/SDD.md)
+- SDD 사유: integration lifecycle, config schema, secret resolution과 runtime binding 계약을 변경한다.
+- 잠금 해제 조건:
+  - [x] SDD 잠금이 해제되어 있다.
+  - [x] SDD 사용자 리뷰가 없거나 승인/해결되었다.
+  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
+  - [x] Evidence Map이 완료 시 Roadmap Completion과 최종 검증 evidence로 검증 가능하게 연결되어 있다.
+- 결정 필요: 없음
+
+## 범위
+
+- integration instance CRUD, kind, implementation, schema version과 capability manifest
+- 구성 schema 검증과 secret reference 분리
+- compile-time factory registry와 runtime instance binding
+- provider별 health/readiness와 conformance 검증
+- 민감 정보가 제외된 audit·metric·trace
+
+## 기능
+
+### Epic: [catalog] Integration 수명주기
+
+제품별 구현을 공통 identity와 capability로 관리한다.
+
+- [ ] [catalog-lifecycle] project 범위에서 integration instance를 생성·조회·갱신·비활성화하고 revision을 보존한다.
+- [ ] [manifest-validation] kind, implementation, schema version, capability와 config schema 호환성을 활성화 전에 검증한다.
+- [ ] [secret-resolution] integration config에는 `secret_ref`만 저장하고 resolver가 실행 시점에 secret을 제공한다.
+- [ ] [runtime-binding] 활성 instance를 compile-time factory와 결합하고 capability가 맞지 않으면 fail-closed로 차단한다.
+
+### Epic: [conformance] Provider 독립성 검증
+
+vendor 구현이 동일한 동작 계약을 지키는지 자동 확인한다.
+
+- [ ] [conformance-suite] source, retrieval, model, artifact와 executor port별 conformance suite를 제공한다. 검증: fake adapter와 최소 실제 adapter가 동일 suite를 통과한다.
+- [ ] [adapter-telemetry] provider 호출의 latency, error class와 capability identity를 secret 없이 관측 가능하게 남긴다.
+
+## 완료 리뷰
+
+- 상태: 없음
+- 요청일: 없음
+- 완료 근거: 모든 기능 Task와 검증 충족 및 구현 잠금 해제 여부를 완료 시 기록한다.
+- 검토 항목: SDD Evidence Map과 conformance 결과
+- agent-ui 상태 반영: 해당 없음
+- 리뷰 코멘트: 없음
+
+## 범위 제외
+
+- runtime Go plugin 로딩과 임의 바이너리 설치
+- 특정 vendor를 기본 retrieval 또는 model provider로 고정
+- secret vault 제품 자체 구현
+
+## 작업 컨텍스트
+
+- 관련 경로: `packages/go/integration/`, `packages/go/config/`, `packages/go/controlplane/`, `db/`
+- 표준선(선택): compile-time registry, versioned manifest, fail-closed binding, secret reference
+- 선행 작업: [플랫폼 스캐폴드 기준선](platform-scaffold-baseline.md)
+- 후속 작업: [수집과 Dataset 수명주기](../../knowledge-lifecycle/milestones/ingestion-and-dataset-lifecycle.md), [Index 게시와 Release 수명주기](../../rag-serving/milestones/index-publication-and-release.md)
+- 확인 필요: 없음

agent-roadmap/phase/platform-foundation/milestones/platform-scaffold-baseline.md

@@ -0,0 +1,66 @@
+# Milestone: 플랫폼 스캐폴드 기준선
+
+## 위치
+
+- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
+- Phase: [PHASE.md](../PHASE.md)
+
+## 목표
+
+현재 생성된 Go·Python·PostgreSQL 스캐폴드가 RARA의 책임 경계와 재현 가능한 개발 흐름을 충족하는지 검토하고 첫 구현 기준선으로 닫는다.
+
+## 상태
+
+[검토중]
+
+## 구현 잠금
+
+- 상태: 해제
+- SDD: 불필요
+- SDD 문서: 없음
+- SDD 사유: 이미 구현·검증된 단일 저장소 스캐폴드의 완료 근거를 정리하는 작업이며 새 API나 상태 머신을 설계하지 않는다.
+- 잠금 해제 조건: 없음
+- 결정 필요: 없음
+
+## 범위
+
+- Go control-plane, rag-api, worker 실행 진입점
+- PostgreSQL 18 제어 상태 스키마와 sqlc 생성 흐름
+- Go/Python Protobuf executor 계약과 Python worker
+- product-neutral integration port, artifact adapter, 공통 설정과 관측성
+- Make, CI, Docker 개발 자산과 로컬 검증 기준
+
+## 기능
+
+### Epic: [baseline] 실행 가능한 플랫폼 기준선
+
+RARA가 후속 Milestone을 수용할 수 있는 저장소 구조와 빌드 계약을 기준선으로 고정한다.
+
+- [x] [service-layout] control-plane, rag-api, Go worker와 Python executor의 실행 구조를 구성했다.
+- [x] [state-schema] project, knowledge, workflow, evaluation, release, trace 제어 상태와 sqlc 쿼리 원본을 구성했다.
+- [x] [public-contracts] HTTP/JSON·SSE OpenAPI와 Go/Python executor Protobuf 계약을 구성했다.
+- [x] [adapter-boundary] source, retrieval, embedding, rerank, generation, secret, artifact의 제품 중립 경계를 구성했다.
+- [x] [developer-loop] `make setup`, `make test`, `make build`, `sqlc diff`가 재현 가능하게 동작한다. 검증: 로컬 명령이 모두 성공하고 세 Go 바이너리가 생성된다.
+
+## 완료 리뷰
+
+- 상태: 검토중
+- 요청일: 2026-07-18
+- 완료 근거: Go 전체 테스트와 Python 테스트 3개가 통과했고, sqlc compile/diff와 세 서비스 빌드 및 control-plane HTTP smoke를 확인했다.
+- 검토 항목: 실제 PostgreSQL 인스턴스에 초기 migration을 적용하는 통합 evidence와 저장소 첫 기준선 반영 여부
+- agent-ui 상태 반영: 해당 없음
+- 리뷰 코멘트: PostgreSQL 실행 환경이 준비되면 migration up/down smoke를 추가 확인한 뒤 완료 archive 후보로 전환한다.
+
+## 범위 제외
+
+- 실제 retrieval backend, model provider와 source connector 구현
+- production 인증, 권한과 운영 UI
+- LoRA/QLoRA 학습 실행
+
+## 작업 컨텍스트
+
+- 관련 경로: `apps/`, `packages/`, `api/`, `db/`, `configs/`, `deploy/`
+- 표준선(선택): [프로젝트 규칙](../../../../agent-ops/rules/project/rules.md)과 각 domain rule의 책임 경계
+- 선행 작업: 없음
+- 후속 작업: [Integration 카탈로그와 Secret 경계](integration-catalog-and-secrets.md)
+- 확인 필요: 실제 PostgreSQL migration smoke 환경

agent-roadmap/phase/quality-governance/PHASE.md

@@ -0,0 +1,30 @@
+# Phase: 품질 거버넌스
+
+## 상태
+
+[계획]
+
+## 목표
+
+RAG 변경을 감각이 아닌 재현 가능한 평가와 운영 지표로 판단한다. 후보 release는 기준선 비교와 정책 gate를 거쳐 명시적으로 승격하고, drift와 feedback은 무조건 학습하지 않고 선별된 보정 입력으로 관리한다.
+
+## Milestone 흐름
+
+Phase를 가로지르는 실제 다음 작업 선택은 [전역 마일스톤 실행 순서](../../priority-queue.md)를 우선한다.
+
+- [계획] 평가와 승격 Gate
+  - 경로: [평가와 승격 Gate](milestones/evaluation-and-promotion-gates.md)
+  - 요약: evaluation suite, 기준선 비교, 수동 승격과 rollback audit를 완성한다.
+- [계획] Retrieval 정책 최적화
+  - 경로: [Retrieval 정책 최적화](milestones/retrieval-policy-optimization.md)
+  - 요약: chunking·embedding·hybrid·rerank·query 변환 정책을 재현 가능한 실험과 gate로 최적화한다.
+- [스케치] Drift와 선별 Feedback
+  - 경로: [Drift와 선별 Feedback](milestones/drift-and-selective-feedback.md)
+  - 요약: 저신뢰와 shadow 불일치만 선별해 보정 데이터로 축적하는 정책을 설계한다.
+
+## Phase 경계
+
+- active 경로의 모든 요청을 무조건 학습 데이터로 저장하지 않는다.
+- 평가 결과만으로 production을 자동 승격하지 않고 초기 운영은 명시적 수동 승격을 유지한다.
+- 정책 실험의 승자가 active release를 직접 변경하지 않고 candidate policy와 평가 근거만 생성한다.
+- 품질 지표와 운영 trace의 보존 기간·민감 데이터 정책을 분리한다.

agent-roadmap/phase/quality-governance/milestones/drift-and-selective-feedback.md

@@ -0,0 +1,85 @@
+# Milestone: Drift와 선별 Feedback
+
+## 위치
+
+- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
+- Phase: [PHASE.md](../PHASE.md)
+
+## 목표
+
+active RAG의 품질 변화를 window 단위로 감시하고, 모든 요청이 아니라 낮은 confidence, 오류, 사용자 feedback과 제한된 shadow 비교에서 의미 있는 차이가 난 사례만 보정 후보로 남긴다.
+
+## 상태
+
+[스케치]
+
+## 승격 조건
+
+- [ ] confidence가 provider 자기보고 값이 아니라 calibration된 신호 조합이 되도록 정의한다.
+- [ ] shadow 실행 비율, 비용 한도와 데이터 보존 정책을 정의한다.
+- [ ] 차이 판정 metric과 review queue 진입 기준을 정의한다.
+- [ ] active 로컬 경로의 전량 수집을 금지하고 opt-in·선별 수집 경계를 고정한다.
+- [x] 비용·보존·feedback lifecycle을 다루는 SDD 필요성을 확정하고 SDD를 작성했다.
+
+## 구현 잠금
+
+- 상태: 잠금
+- SDD: 필요
+- SDD 문서: [SDD.md](../../../sdd/quality-governance/drift-and-selective-feedback/SDD.md)
+- SDD 사유: selective capture lifecycle, bounded shadow, privacy·retention과 feedback routing 계약을 정의한다.
+- 잠금 해제 조건:
+  - [x] SDD 잠금이 해제되어 있다.
+  - [x] SDD 사용자 리뷰가 없거나 승인/해결되었다.
+  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
+  - [x] Evidence Map이 완료 시 Roadmap Completion과 최종 검증 evidence로 검증 가능하게 연결되어 있다.
+  - [ ] 모든 승격 조건이 해소되고 Milestone 상태가 `[계획]`이다.
+- 결정 필요: 없음
+
+## 범위
+
+- release·source freshness와 online quality drift window
+- calibrated confidence와 failure·user feedback signal
+- 제한된 기간의 teacher·shadow 동시 실행과 결과 차이
+- selective feedback queue, 중복 제거와 민감 정보 필터
+- RAG 보정과 training candidate로의 분리된 handoff
+
+## 기능
+
+### Epic: [drift] 품질 변화 감지
+
+단일 request가 아니라 release와 기간별 품질 추세를 감시한다.
+
+- [ ] [drift-windows] quality, latency, freshness와 failure 지표를 release·segment별 window로 집계한다.
+- [ ] [confidence-calibration] retrieval coverage, rerank margin, generation validation과 provider signal을 calibration한다.
+- [ ] [shadow-comparison] 설정된 비율과 비용 한도 안에서 teacher·shadow 결과 차이를 비교한다.
+
+### Epic: [feedback] 선별 보정 입력
+
+운영 요청 전량을 저장하지 않고 보정 가치가 높은 사례만 provenance와 함께 남긴다.
+
+- [ ] [selective-capture] low-confidence, 큰 shadow 차이, explicit feedback과 error 사례만 정책에 따라 수집한다.
+- [ ] [privacy-dedup] 보존 전 redaction, consent·retention 검증과 semantic deduplication을 적용한다.
+- [ ] [feedback-routing] 사례를 RAG source 보정, evaluation case 또는 training candidate로 분류한다.
+
+## 완료 리뷰
+
+- 상태: 없음
+- 요청일: 없음
+- 완료 근거: 스케치 단계이며 `[계획]` 승격 뒤 기록한다.
+- 검토 항목: 승격 조건과 후속 SDD gate
+- agent-ui 상태 반영: 해당 없음
+- 리뷰 코멘트: 없음
+
+## 범위 제외
+
+- active 경로의 무조건적 전량 저장과 자기 학습
+- confidence threshold 하나만으로 자동 모델 교체
+- shadow 결과의 자동 정답 취급
+
+## 작업 컨텍스트
+
+- 관련 경로: `packages/go/controlplane/`, `packages/go/rag/`, `packages/go/workflow/`, `db/`
+- 표준선(선택): selective capture, bounded shadow, calibrated confidence, human-auditable provenance
+- 선행 작업: [평가와 승격 Gate](evaluation-and-promotion-gates.md), [지속 갱신 Orchestration](../../workflow-automation/milestones/continuous-refresh-orchestration.md)
+- 후속 작업: [훈련 Dataset 정제](../../selective-adaptation/milestones/training-dataset-curation.md)
+- 확인 필요: 없음

agent-roadmap/phase/quality-governance/milestones/evaluation-and-promotion-gates.md

@@ -0,0 +1,78 @@
+# Milestone: 평가와 승격 Gate
+
+## 위치
+
+- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
+- Phase: [PHASE.md](../PHASE.md)
+
+## 목표
+
+candidate release를 고정된 evaluation suite와 기준선 release에 대해 재현 가능하게 평가한다. 임계값과 필수 metric을 통과한 후보만 수동 승격 대상으로 만들고, 결정·결과·rollback 근거를 감사 가능하게 남긴다.
+
+## 상태
+
+[계획]
+
+## 구현 잠금
+
+- 상태: 해제
+- SDD: 필요
+- SDD 문서: [SDD.md](../../../sdd/quality-governance/evaluation-and-promotion-gates/SDD.md)
+- SDD 사유: evaluation lifecycle, metric gate, 수동 승인과 release promotion 상태 전이를 정의한다.
+- 잠금 해제 조건:
+  - [x] SDD 잠금이 해제되어 있다.
+  - [x] SDD 사용자 리뷰가 없거나 승인/해결되었다.
+  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
+  - [x] Evidence Map이 완료 시 Roadmap Completion과 최종 검증 evidence로 검증 가능하게 연결되어 있다.
+- 결정 필요: 없음
+
+## 범위
+
+- versioned evaluation suite, case, expectation과 dataset
+- candidate·baseline 동일 조건 실행
+- retrieval·answer·latency·cost metric과 required threshold
+- pass, fail, invalid 평가 상태와 재실행
+- 수동 promotion command, audit와 rollback pointer
+- evaluation result와 release·workflow lineage
+
+## 기능
+
+### Epic: [evaluation] 재현 가능한 비교
+
+후보 품질을 동일 입력과 policy에서 기준선과 비교한다.
+
+- [ ] [suite-versioning] evaluation suite, case, expectation과 evaluator version을 불변 revision으로 관리한다.
+- [ ] [candidate-baseline] candidate와 baseline release를 같은 case·metric 구성으로 실행하고 각 evaluation run이 비교한 불변 release identity를 참조하게 한다.
+- [ ] [metric-gates] retrieval, answer, latency와 cost metric에 required threshold와 regression tolerance를 적용한다.
+- [ ] [evaluation-state] pending, running, passed, failed, invalid 상태와 재실행 idempotency를 보존한다.
+
+### Epic: [promotion] 운영 승인과 Rollback
+
+평가와 production 변경 사이에 명시적 운영 결정을 둔다.
+
+- [ ] [promotion-eligibility] 모든 required gate가 통과한 candidate만 promotion eligible로 표시한다.
+- [ ] [manual-promotion] release와 evaluation evidence를 연결한 promotion decision을 만들고 명시적 운영 명령으로 alias를 전환하며 actor·근거를 audit한다.
+- [ ] [rollback-audit] 이전 release로 rollback하고 평가·승격·rollback chain을 조회할 수 있다. 검증: regression 차단, 승인 경쟁과 rollback 통합 테스트가 통과한다.
+
+## 완료 리뷰
+
+- 상태: 없음
+- 요청일: 없음
+- 완료 근거: 모든 기능 Task와 검증 충족 및 구현 잠금 해제 여부를 완료 시 기록한다.
+- 검토 항목: candidate-baseline 재현성, required gate 차단, 수동 promotion과 rollback audit
+- agent-ui 상태 반영: 해당 없음
+- 리뷰 코멘트: 없음
+
+## 범위 제외
+
+- metric 통과만으로 자동 production 승격
+- 범용 LLM judge 플랫폼 전체 구현
+- evaluation dataset을 training dataset과 동일 객체로 사용
+
+## 작업 컨텍스트
+
+- 관련 경로: `packages/go/controlplane/`, `packages/go/workflow/`, `packages/python/`, `db/`
+- 표준선(선택): immutable suite revision, baseline comparison, explicit promotion
+- 선행 작업: [Retrieve와 Answer Pipeline](../../rag-serving/milestones/retrieval-and-answer-pipeline.md), [Index 게시와 Release 수명주기](../../rag-serving/milestones/index-publication-and-release.md)
+- 후속 작업: [지속 갱신 Orchestration](../../workflow-automation/milestones/continuous-refresh-orchestration.md), [Drift와 선별 Feedback](drift-and-selective-feedback.md)
+- 확인 필요: 없음

agent-roadmap/phase/quality-governance/milestones/retrieval-policy-optimization.md

@@ -0,0 +1,76 @@
+# Milestone: Retrieval 정책 최적화
+
+## 위치
+
+- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
+- Phase: [PHASE.md](../PHASE.md)
+
+## 목표
+
+chunking, embedding, sparse·dense fusion, rerank와 query 변환 정책을 versioned 실험으로 비교해 품질·지연·비용 기준을 만족하는 candidate policy를 만든다. 실험 결과는 자동으로 production을 바꾸지 않고 평가·승격 gate의 명시적 결정 입력이 된다.
+
+## 상태
+
+[계획]
+
+## 구현 잠금
+
+- 상태: 해제
+- SDD: 필요
+- SDD 문서: [SDD.md](../../../sdd/quality-governance/retrieval-policy-optimization/SDD.md)
+- SDD 사유: policy experiment lifecycle, 재현성, 예산 제한과 promotion handoff를 정의한다.
+- 잠금 해제 조건:
+  - [x] SDD 잠금이 해제되어 있다.
+  - [x] SDD 사용자 리뷰가 없거나 승인/해결되었다.
+  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
+  - [x] Evidence Map이 완료 시 Roadmap Completion과 최종 검증 evidence로 검증 가능하게 연결되어 있다.
+- 결정 필요: 없음
+
+## 범위
+
+- chunking, embedding, hybrid retrieval, rerank와 query transformation 정책 공간
+- dataset·suite·provider·seed·budget을 고정한 experiment revision
+- candidate와 baseline의 품질·latency·cost 비교
+- 제약 조건을 만족하는 candidate policy 선택
+- 평가·승격 gate로의 명시적 handoff
+
+## 기능
+
+### Epic: [experiment] 재현 가능한 정책 실험
+
+검색 정책 변경을 임의 프롬프트 조정이 아닌 비교 가능한 artifact로 만든다.
+
+- [ ] [policy-space] chunking, embedding, hybrid fusion, rerank와 query transformation의 탐색 가능한 policy schema와 capability constraint를 정의한다.
+- [ ] [experiment-snapshot] dataset, evaluation suite, provider revision, seed와 budget을 불변 experiment revision으로 묶는다.
+- [ ] [offline-comparison] candidate와 baseline을 같은 입력으로 실행하고 품질·latency·cost 결과와 lineage를 기록한다.
+
+### Epic: [selection] Candidate Policy 선별
+
+최고 점수 하나가 아니라 필수 제약과 회귀 허용치를 통과한 정책만 후속 대상으로 만든다.
+
+- [ ] [constraint-gates] 품질 threshold, regression tolerance, latency와 cost budget을 적용해 후보를 통과·차단한다.
+- [ ] [candidate-selection] 통과 후보의 policy snapshot과 비교 근거를 candidate release 입력으로 게시한다.
+- [ ] [promotion-handoff] candidate policy와 evaluation evidence를 승격 gate에 전달하되 active alias는 직접 변경하지 않는다.
+
+## 완료 리뷰
+
+- 상태: 없음
+- 요청일: 없음
+- 완료 근거: 모든 기능 Task와 검증 충족 및 구현 잠금 해제 여부를 완료 시 기록한다.
+- 검토 항목: experiment 재현성, provider capability 차이, budget gate와 수동 승격 경계
+- agent-ui 상태 반영: 해당 없음
+- 리뷰 코멘트: 없음
+
+## 범위 제외
+
+- production alias 자동 변경
+- 범용 AutoML·hyperparameter optimization 제품
+- retrieval backend 내부 알고리즘 구현
+
+## 작업 컨텍스트
+
+- 관련 경로: `packages/go/controlplane/`, `packages/go/rag/`, `packages/go/workflow/`, `packages/python/`, `db/`
+- 표준선(선택): immutable experiment revision, same-condition comparison, budget-aware selection, explicit promotion
+- 선행 작업: [평가와 승격 Gate](evaluation-and-promotion-gates.md), [Retrieve와 Answer Pipeline](../../rag-serving/milestones/retrieval-and-answer-pipeline.md)
+- 후속 작업: [지속 갱신 Orchestration](../../workflow-automation/milestones/continuous-refresh-orchestration.md)
+- 확인 필요: 없음

agent-roadmap/phase/rag-serving/PHASE.md

@@ -0,0 +1,26 @@
+# Phase: RAG 서빙
+
+## 상태
+
+[계획]
+
+## 목표
+
+검증 가능한 dataset을 retrieval backend에 후보 인덱스로 게시하고, 명시적으로 승격된 release만 온라인 retrieve·answer에서 소비한다. 모든 응답은 release와 evidence identity를 노출하고 JSON·SSE 오류 의미를 일치시킨다.
+
+## Milestone 흐름
+
+Phase를 가로지르는 실제 다음 작업 선택은 [전역 마일스톤 실행 순서](../../priority-queue.md)를 우선한다.
+
+- [계획] Index 게시와 Release 수명주기
+  - 경로: [Index 게시와 Release 수명주기](milestones/index-publication-and-release.md)
+  - 요약: 후보 index, 불변 release, alias 승격과 rollback을 완성한다.
+- [계획] Retrieve와 Answer Pipeline
+  - 경로: [Retrieve와 Answer Pipeline](milestones/retrieval-and-answer-pipeline.md)
+  - 요약: retrieval, rerank, context assembly, generation과 evidence trace를 온라인 API로 제공한다.
+
+## Phase 경계
+
+- 온라인 경로는 candidate release를 암묵적으로 production에 승격하지 않는다.
+- retrieval backend와 model provider의 vendor 타입을 공개 API에 노출하지 않는다.
+- 인덱스 작성·평가는 workflow에서 수행하고 온라인 경로는 승격된 release만 읽는다.

agent-roadmap/phase/rag-serving/milestones/index-publication-and-release.md

@@ -0,0 +1,77 @@
+# Milestone: Index 게시와 Release 수명주기
+
+## 위치
+
+- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
+- Phase: [PHASE.md](../PHASE.md)
+
+## 목표
+
+retrieval dataset version을 backend별 후보 index로 게시하고, 평가 가능한 불변 release로 묶는다. production alias 전환과 rollback은 원자적·명시적으로 수행하며 온라인 요청이 부분 게시 상태를 보지 않게 한다.
+
+## 상태
+
+[계획]
+
+## 구현 잠금
+
+- 상태: 해제
+- SDD: 필요
+- SDD 문서: [SDD.md](../../../sdd/rag-serving/index-publication-and-release/SDD.md)
+- SDD 사유: index publish, release 상태 머신, alias promotion·rollback과 backend identity 계약을 정의한다.
+- 잠금 해제 조건:
+  - [x] SDD 잠금이 해제되어 있다.
+  - [x] SDD 사용자 리뷰가 없거나 승인/해결되었다.
+  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
+  - [x] Evidence Map이 완료 시 Roadmap Completion과 최종 검증 evidence로 검증 가능하게 연결되어 있다.
+- 결정 필요: 없음
+
+## 범위
+
+- retrieval policy와 embedding·backend capability 사전 검증
+- candidate index build·publish와 external backend identity
+- dataset, index artifact, policy snapshot을 묶는 immutable release
+- candidate, active, retired, failed 상태와 alias version
+- transaction 기반 explicit promotion과 rollback
+- orphan index 정리와 backend reconciliation
+
+## 기능
+
+### Epic: [index] Candidate Index 게시
+
+완료되지 않은 index가 온라인 alias에 노출되지 않게 게시 단계를 분리한다.
+
+- [ ] [preflight] dataset schema, embedding dimension, backend capability와 retrieval policy 호환성을 build 전에 검증한다.
+- [ ] [candidate-build] content-addressed dataset과 policy로 candidate index를 만들고 external identity와 manifest를 기록한다.
+- [ ] [publish-reconcile] backend publish 결과를 멱등하게 반영하고 timeout·부분 실패 뒤 상태를 reconciliation한다.
+
+### Epic: [release] 명시적 Release 전환
+
+온라인 소비자가 항상 하나의 완전한 release identity를 보게 한다.
+
+- [ ] [release-snapshot] dataset version, index identity와 retrieval·generation policy를 immutable release content로 묶는다.
+- [ ] [alias-promotion] release와 evaluation evidence를 연결한 명시적 promotion decision을 받아 candidate를 active alias로 원자적으로 승격한다.
+- [ ] [rollback-retire] 이전 release로 alias를 롤백하고 더 이상 참조되지 않는 index를 안전하게 retire한다. 검증: promotion 경쟁, rollback과 backend failure 통합 테스트가 통과한다.
+
+## 완료 리뷰
+
+- 상태: 없음
+- 요청일: 없음
+- 완료 근거: 모든 기능 Task와 검증 충족 및 구현 잠금 해제 여부를 완료 시 기록한다.
+- 검토 항목: partial publish, concurrent promotion, rollback과 backend reconciliation
+- agent-ui 상태 반영: 해당 없음
+- 리뷰 코멘트: 없음
+
+## 범위 제외
+
+- 평가 결과만으로 production 자동 승격
+- retrieval backend 내부 index 포맷 통일
+- mutable production index의 in-place update
+
+## 작업 컨텍스트
+
+- 관련 경로: `packages/go/controlplane/`, `packages/go/integration/`, `db/`
+- 표준선(선택): candidate-before-active, immutable release, explicit alias transaction
+- 선행 작업: [수집과 Dataset 수명주기](../../knowledge-lifecycle/milestones/ingestion-and-dataset-lifecycle.md), [내구성 있는 Workflow Runtime](../../workflow-automation/milestones/durable-workflow-runtime.md)
+- 후속 작업: [Retrieve와 Answer Pipeline](retrieval-and-answer-pipeline.md), [평가와 승격 Gate](../../quality-governance/milestones/evaluation-and-promotion-gates.md)
+- 확인 필요: 없음

agent-roadmap/phase/rag-serving/milestones/retrieval-and-answer-pipeline.md

@@ -0,0 +1,78 @@
+# Milestone: Retrieve와 Answer Pipeline
+
+## 위치
+
+- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
+- Phase: [PHASE.md](../PHASE.md)
+
+## 목표
+
+활성 release의 versioned policy를 해석해 retrieval, rerank, context assembly와 generation을 실행한다. JSON과 SSE 모두 release, evidence, trace identity와 일관된 오류를 반환하고 특정 provider 장애를 공개 계약으로 정규화한다.
+
+## 상태
+
+[계획]
+
+## 구현 잠금
+
+- 상태: 해제
+- SDD: 필요
+- SDD 문서: [SDD.md](../../../sdd/rag-serving/retrieval-and-answer-pipeline/SDD.md)
+- SDD 사유: 공개 OpenAPI·SSE, provider 호출 순서, trace retention과 failure mapping 계약을 변경한다.
+- 잠금 해제 조건:
+  - [x] SDD 잠금이 해제되어 있다.
+  - [x] SDD 사용자 리뷰가 없거나 승인/해결되었다.
+  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
+  - [x] Evidence Map이 완료 시 Roadmap Completion과 최종 검증 evidence로 검증 가능하게 연결되어 있다.
+- 결정 필요: 없음
+
+## 범위
+
+- project, knowledge base와 release alias 해석
+- query embedding, retrieval backend search, filter와 top-k
+- rerank, context budget, evidence·citation assembly
+- generation provider와 JSON·SSE answer
+- trace identity, release identity, usage·latency와 만료 보존
+- provider timeout, unavailable, invalid policy와 partial stream 오류
+
+## 기능
+
+### Epic: [retrieve] Versioned 검색
+
+동일 release와 요청이 동일한 정책 경로를 사용하도록 온라인 검색을 고정한다.
+
+- [ ] [release-resolution] 요청마다 active release를 해석하고 response와 trace에 release id·alias·version을 포함한다.
+- [ ] [retrieval-policy] embedding, filter, backend search와 top-k를 release policy와 capability에 따라 실행한다.
+- [ ] [rerank-context] rerank와 context budget을 적용하고 rank, score, citation과 metadata를 안정된 evidence로 반환한다.
+
+### Epic: [answer] 생성과 Streaming
+
+검색 evidence를 보존하면서 non-streaming과 streaming 응답 의미를 일치시킨다.
+
+- [ ] [generation] generation provider에 query, evidence와 versioned policy를 전달하고 answer·usage를 반환한다.
+- [ ] [sse-contract] metadata, evidence, delta, completed, error SSE event를 순서 있게 전송하고 JSON 오류 의미와 대응시킨다.
+- [ ] [trace-retention] query·answer 원문 저장은 policy에 따라 선택하고 모든 저장 trace에 expiry를 강제한다.
+- [ ] [provider-failures] timeout, unavailable, capability mismatch와 partial stream failure를 공개 오류 코드로 정규화한다. 검증: fake provider matrix와 HTTP/SSE contract test가 통과한다.
+
+## 완료 리뷰
+
+- 상태: 없음
+- 요청일: 없음
+- 완료 근거: 모든 기능 Task와 검증 충족 및 구현 잠금 해제 여부를 완료 시 기록한다.
+- 검토 항목: OpenAPI·handler drift, JSON/SSE parity, release evidence와 trace expiry
+- agent-ui 상태 반영: 해당 없음
+- 리뷰 코멘트: 없음
+
+## 범위 제외
+
+- request 시점의 index 작성과 release 승격
+- 특정 vector DB 또는 model SDK 타입의 공개 노출
+- 무기한 raw query·answer 보존
+
+## 작업 컨텍스트
+
+- 관련 경로: `packages/go/rag/`, `packages/go/integration/`, `api/openapi/`, `db/queries/traces.sql`
+- 표준선(선택): active release read-only, evidence-first response, JSON/SSE semantic parity
+- 선행 작업: [Index 게시와 Release 수명주기](index-publication-and-release.md), [Integration 카탈로그와 Secret 경계](../../platform-foundation/milestones/integration-catalog-and-secrets.md)
+- 후속 작업: [평가와 승격 Gate](../../quality-governance/milestones/evaluation-and-promotion-gates.md)
+- 확인 필요: 없음

agent-roadmap/phase/selective-adaptation/PHASE.md

@@ -0,0 +1,26 @@
+# Phase: 선택적 Adaptation
+
+## 상태
+
+[스케치]
+
+## 목표
+
+RAG 운영에서 검증된 일부 데이터만 재현 가능한 훈련 dataset으로 승격하고, 필요할 때 LoRA/QLoRA를 실행할 수 있는 선택적 adaptation 경로를 제공한다. RARA의 기본 용도는 RAG이며 tuning은 품질·비용상 이점이 검증된 경우에만 사용한다.
+
+## Milestone 흐름
+
+Phase를 가로지르는 실제 다음 작업 선택은 [전역 마일스톤 실행 순서](../../priority-queue.md)를 우선한다.
+
+- [스케치] 훈련 Dataset 정제
+  - 경로: [훈련 Dataset 정제](milestones/training-dataset-curation.md)
+  - 요약: 선별 feedback을 provenance가 있는 train·validation·holdout dataset으로 만든다.
+- [스케치] LoRA와 QLoRA 실행
+  - 경로: [LoRA와 QLoRA 실행](milestones/lora-qlora-execution.md)
+  - 요약: Python executor 기반 adaptation, 평가와 model artifact 승격 경계를 설계한다.
+
+## Phase 경계
+
+- 실시간 자기 학습과 production 모델의 직접 갱신을 지원하지 않는다.
+- 훈련 dataset은 평가용 dataset과 분리하고 source와 teacher provenance를 보존한다.
+- 특정 ML 프레임워크와 GPU 환경을 제어 플레인 핵심 상태 모델에 하드코딩하지 않는다.

agent-roadmap/phase/selective-adaptation/milestones/lora-qlora-execution.md

@@ -0,0 +1,86 @@
+# Milestone: LoRA와 QLoRA 실행
+
+## 위치
+
+- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
+- Phase: [PHASE.md](../PHASE.md)
+
+## 목표
+
+검증된 training dataset release와 versioned recipe로 LoRA/QLoRA job을 실행하고, 결과 adapter artifact를 평가 뒤 승격할 수 있게 한다. ML framework와 compute 환경은 executor capability 뒤에 둔다.
+
+## 상태
+
+[스케치]
+
+## 승격 조건
+
+- [ ] 지원할 첫 base model·framework·artifact 포맷의 최소 호환 범위를 정의한다.
+- [ ] GPU·quantization capability와 scheduler 책임 경계를 정의한다.
+- [ ] 학습 비용·시간 한도와 cancel·checkpoint 정책을 정의한다.
+- [ ] adaptation 결과 evaluation과 promotion 기준을 정의한다.
+- [x] executor·artifact·비용과 promotion lifecycle을 다루는 SDD 필요성을 확정하고 초안을 작성했다.
+
+## 구현 잠금
+
+- 상태: 잠금
+- SDD: 필요
+- SDD 문서: [SDD.md](../../../sdd/selective-adaptation/lora-qlora-execution/SDD.md)
+- SDD 사유: capability preflight, 장시간 training 상태, checkpoint·cancel, artifact와 promotion 계약을 정의한다.
+- 잠금 해제 조건:
+  - [ ] SDD 잠금이 해제되어 있다.
+  - [ ] SDD 사용자 리뷰가 승인/해결되었다.
+  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
+  - [x] Evidence Map이 완료 시 Roadmap Completion과 최종 검증 evidence로 검증 가능하게 연결되어 있다.
+  - [ ] 모든 승격 조건이 해소되고 Milestone 상태가 `[계획]`이다.
+- 결정 필요:
+  - 첫 지원 base model family와 배포 대상의 우선순위
+
+## 범위
+
+- Python executor adaptation capability와 preflight
+- LoRA·QLoRA versioned recipe와 deterministic seed
+- checkpoint, progress, cancel와 retry-safe artifact
+- adapter artifact manifest와 base model compatibility
+- baseline evaluation, candidate promotion과 rollback
+
+## 기능
+
+### Epic: [training] Adaptation 실행
+
+compute와 framework 차이를 capability-aware executor 뒤에 둔다.
+
+- [ ] [preflight-capability] base model, precision, quantization, memory와 library capability를 job 수락 전에 검증한다.
+- [ ] [training-job] versioned dataset·recipe로 LoRA 또는 QLoRA를 실행하고 progress와 usage를 보고한다.
+- [ ] [checkpoint-cancel] checkpoint, graceful cancel과 terminal failure artifact를 명시적으로 처리한다.
+
+### Epic: [model-release] Adapter Artifact 승격
+
+학습 완료가 곧 production 사용을 의미하지 않게 평가와 release를 분리한다.
+
+- [ ] [adapter-manifest] base model identity, dataset, recipe, library version과 content hash를 manifest에 남긴다.
+- [ ] [adaptation-evaluation] baseline과 candidate adapter를 같은 evaluation suite로 비교한다.
+- [ ] [adapter-promotion] 통과한 adapter만 명시적으로 승격하고 이전 adapter로 rollback할 수 있게 한다.
+
+## 완료 리뷰
+
+- 상태: 없음
+- 요청일: 없음
+- 완료 근거: 스케치 단계이며 `[계획]` 승격 뒤 기록한다.
+- 검토 항목: 승격 조건과 후속 SDD gate
+- agent-ui 상태 반영: 해당 없음
+- 리뷰 코멘트: 없음
+
+## 범위 제외
+
+- base model full fine-tuning
+- 실시간 online learning
+- GPU scheduler와 model registry 제품 자체 구현
+
+## 작업 컨텍스트
+
+- 관련 경로: `packages/python/`, `api/proto/`, `packages/go/workflow/`, `packages/go/controlplane/`
+- 표준선(선택): optional adaptation, capability preflight, evaluation-before-promotion
+- 선행 작업: [훈련 Dataset 정제](training-dataset-curation.md), [내구성 있는 Workflow Runtime](../../workflow-automation/milestones/durable-workflow-runtime.md)
+- 후속 작업: 없음
+- 확인 필요: `구현 잠금 > 결정 필요`

agent-roadmap/phase/selective-adaptation/milestones/training-dataset-curation.md

@@ -0,0 +1,85 @@
+# Milestone: 훈련 Dataset 정제
+
+## 위치
+
+- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
+- Phase: [PHASE.md](../PHASE.md)
+
+## 목표
+
+evaluation과 selective feedback에서 검증된 사례를 provenance가 있는 training candidate로 관리하고, 중복·오염·누출을 제거한 train·validation·holdout dataset release로 승격한다.
+
+## 상태
+
+[스케치]
+
+## 승격 조건
+
+- [ ] RAG 보정 사례와 tuning 후보를 분리하는 승격 기준을 정의한다.
+- [ ] teacher provenance, license, consent와 retention 필드를 확정한다.
+- [ ] train·validation·holdout 분리와 contamination 검출 기준을 정의한다.
+- [ ] dataset quality gate와 사용자 승인 필요 범위를 정의한다.
+- [x] training candidate와 dataset promotion lifecycle을 다루는 SDD 필요성을 확정하고 SDD를 작성했다.
+
+## 구현 잠금
+
+- 상태: 잠금
+- SDD: 필요
+- SDD 문서: [SDD.md](../../../sdd/selective-adaptation/training-dataset-curation/SDD.md)
+- SDD 사유: candidate review, provenance·retention, split과 immutable training release 상태 계약을 정의한다.
+- 잠금 해제 조건:
+  - [x] SDD 잠금이 해제되어 있다.
+  - [x] SDD 사용자 리뷰가 없거나 승인/해결되었다.
+  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
+  - [x] Evidence Map이 완료 시 Roadmap Completion과 최종 검증 evidence로 검증 가능하게 연결되어 있다.
+  - [ ] 모든 승격 조건이 해소되고 Milestone 상태가 `[계획]`이다.
+- 결정 필요: 없음
+
+## 범위
+
+- training candidate와 검토 상태
+- teacher·source·release·feedback provenance
+- redaction, deduplication, label consistency와 contamination 검사
+- train·validation·holdout split과 불변 dataset release
+- recipe, statistics와 quality report
+
+## 기능
+
+### Epic: [candidate] 훈련 후보 수명주기
+
+운영 데이터가 검증 없이 바로 학습에 들어가지 않게 승격 단계를 둔다.
+
+- [ ] [candidate-intake] evaluation·feedback 사례를 provenance와 policy verdict를 가진 candidate로 수집한다.
+- [ ] [candidate-review] reject, quarantine, accepted 상태와 이유를 보존한다.
+- [ ] [redaction-dedup] 민감 정보 제거, exact·semantic deduplication과 license 검증을 수행한다.
+
+### Epic: [dataset] 재현 가능한 훈련 Release
+
+동일 recipe에서 동일 split과 quality report를 재현한다.
+
+- [ ] [dataset-split] entity·source leakage를 막는 train·validation·holdout 분리를 수행한다.
+- [ ] [contamination-check] evaluation·holdout contamination과 label conflict를 탐지한다.
+- [ ] [training-release] content hash, recipe, statistics와 provenance를 가진 불변 training dataset release를 게시한다.
+
+## 완료 리뷰
+
+- 상태: 없음
+- 요청일: 없음
+- 완료 근거: 스케치 단계이며 `[계획]` 승격 뒤 기록한다.
+- 검토 항목: 승격 조건과 후속 SDD gate
+- agent-ui 상태 반영: 해당 없음
+- 리뷰 코멘트: 없음
+
+## 범위 제외
+
+- 운영 trace 전량을 자동 training data로 사용
+- evaluation dataset과 holdout dataset의 혼용
+- 모델 학습 실행 자체
+
+## 작업 컨텍스트
+
+- 관련 경로: `packages/go/controlplane/`, `packages/go/workflow/`, `packages/python/`, `db/`
+- 표준선(선택): provenance-first, immutable split, contamination gate
+- 선행 작업: [Drift와 선별 Feedback](../../quality-governance/milestones/drift-and-selective-feedback.md)
+- 후속 작업: [LoRA와 QLoRA 실행](lora-qlora-execution.md)
+- 확인 필요: 없음

agent-roadmap/phase/workflow-automation/PHASE.md

@@ -0,0 +1,26 @@
+# Phase: 워크플로우 자동화
+
+## 상태
+
+[계획]
+
+## 목표
+
+수집, 정제, 인덱싱, 평가와 adaptation을 동일한 실행 원칙으로 처리하는 내구성 있는 workflow runtime을 제공한다. 장시간 작업이 중단되더라도 lease, idempotency, artifact와 영속 상태를 기준으로 안전하게 이어갈 수 있게 한다.
+
+## Milestone 흐름
+
+Phase를 가로지르는 실제 다음 작업 선택은 [전역 마일스톤 실행 순서](../../priority-queue.md)를 우선한다.
+
+- [계획] 내구성 있는 Workflow Runtime
+  - 경로: [내구성 있는 Workflow Runtime](milestones/durable-workflow-runtime.md)
+  - 요약: lease 갱신, retry, cancel, Go/Python executor와 결과 artifact 계약을 완성한다.
+- [스케치] 지속 갱신 Orchestration
+  - 경로: [지속 갱신 Orchestration](milestones/continuous-refresh-orchestration.md)
+  - 요약: 주기·이벤트 기반 후보 생성과 평가 루프를 표준 workflow로 승격한다.
+
+## Phase 경계
+
+- workflow runtime은 RAG 품질 정책이나 release 승격 결정을 자체 소유하지 않는다.
+- executor는 lease된 step만 실행하고 제어 상태는 PostgreSQL을 source of truth로 사용한다.
+- 온라인 retrieve·answer 요청을 비동기 worker 경로로 우회하지 않는다.

agent-roadmap/phase/workflow-automation/milestones/continuous-refresh-orchestration.md

@@ -0,0 +1,79 @@
+# Milestone: 지속 갱신 Orchestration
+
+## 위치
+
+- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
+- Phase: [PHASE.md](../PHASE.md)
+
+## 목표
+
+source 변화와 정기 schedule을 기준으로 수집·정제·인덱싱·평가를 반복하고 candidate release까지 만드는 표준 갱신 workflow를 제공한다. 초기 운영에서 production 승격은 자동화하지 않고 명시적 gate 뒤에 둔다.
+
+## 상태
+
+[스케치]
+
+## 승격 조건
+
+- [ ] schedule, source event와 수동 실행의 trigger 중복 제거 규칙을 확정한다.
+- [ ] knowledge base별 refresh policy와 동시 실행 제한을 정의한다.
+- [ ] 실패 지점부터 재개할 artifact·revision 기준을 정의한다.
+- [ ] [평가와 승격 Gate](../../quality-governance/milestones/evaluation-and-promotion-gates.md)의 candidate handoff 계약을 연결한다.
+- [x] lifecycle·schedule·candidate handoff를 다루는 SDD 필요성을 확정하고 SDD를 작성했다.
+
+## 구현 잠금
+
+- 상태: 잠금
+- SDD: 필요
+- SDD 문서: [SDD.md](../../../sdd/workflow-automation/continuous-refresh-orchestration/SDD.md)
+- SDD 사유: trigger deduplication, 동시 실행, checkpoint·resume과 candidate handoff 상태 계약을 정의한다.
+- 잠금 해제 조건:
+  - [x] SDD 잠금이 해제되어 있다.
+  - [x] SDD 사용자 리뷰가 없거나 승인/해결되었다.
+  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
+  - [x] Evidence Map이 완료 시 Roadmap Completion과 최종 검증 evidence로 검증 가능하게 연결되어 있다.
+  - [ ] 모든 승격 조건이 해소되고 Milestone 상태가 `[계획]`이다.
+- 결정 필요: 없음
+
+## 범위
+
+- schedule, source event와 수동 trigger의 표준 입력
+- source revision 기반 deduplication과 concurrent run 제한
+- 수집부터 candidate evaluation까지의 reference workflow
+- 단계별 artifact checkpoint와 실패 재개
+- refresh history, 비용·duration·freshness 지표
+
+## 기능
+
+### Epic: [refresh] 반복 갱신 루프
+
+프로젝트마다 재구현하지 않아도 되는 기본 RAG 최신화 workflow를 정의한다.
+
+- [ ] [trigger-policy] schedule·event·manual trigger를 정규화하고 같은 source revision의 중복 run을 막는다.
+- [ ] [reference-flow] ingest, normalize, dataset, index, evaluate 단계를 versioned reference workflow로 제공한다.
+- [ ] [checkpoint-resume] 완료 artifact와 revision을 재사용해 실패 단계부터 안전하게 재개한다.
+- [ ] [candidate-handoff] 통과·실패한 평가 결과와 candidate release를 승격 gate에 전달한다.
+- [ ] [refresh-observability] freshness lag, 처리량, 비용, 실패 단계와 다음 예정 실행을 노출한다.
+
+## 완료 리뷰
+
+- 상태: 없음
+- 요청일: 없음
+- 완료 근거: 스케치 단계이며 `[계획]` 승격 뒤 기록한다.
+- 검토 항목: 승격 조건과 후속 SDD gate
+- agent-ui 상태 반영: 해당 없음
+- 리뷰 코멘트: 없음
+
+## 범위 제외
+
+- evaluation 통과만으로 production release 자동 승격
+- 외부 범용 workflow 제품의 모든 기능 재구현
+- 무제한 병렬 refresh
+
+## 작업 컨텍스트
+
+- 관련 경로: `packages/go/workflow/`, `packages/go/controlplane/`, `db/`
+- 표준선(선택): candidate build와 explicit promotion 분리, revision 기반 idempotency
+- 선행 작업: [내구성 있는 Workflow Runtime](durable-workflow-runtime.md), [평가와 승격 Gate](../../quality-governance/milestones/evaluation-and-promotion-gates.md)
+- 후속 작업: [Drift와 선별 Feedback](../../quality-governance/milestones/drift-and-selective-feedback.md)
+- 확인 필요: 없음

agent-roadmap/phase/workflow-automation/milestones/durable-workflow-runtime.md

@@ -0,0 +1,78 @@
+# Milestone: 내구성 있는 Workflow Runtime
+
+## 위치
+
+- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
+- Phase: [PHASE.md](../PHASE.md)
+
+## 목표
+
+수집·정제·인덱싱·평가·adaptation step을 동일한 영속 상태와 실행 계약으로 처리한다. worker 중단과 timeout에도 lease 소유권, idempotency와 artifact 결과를 기준으로 중복 부작용 없이 재시도할 수 있게 한다.
+
+## 상태
+
+[계획]
+
+## 구현 잠금
+
+- 상태: 해제
+- SDD: 필요
+- SDD 문서: [SDD.md](../../../sdd/workflow-automation/durable-workflow-runtime/SDD.md)
+- SDD 사유: workflow와 step 상태 머신, lease, retry, cancel, Protobuf 진행 이벤트 계약을 변경한다.
+- 잠금 해제 조건:
+  - [x] SDD 잠금이 해제되어 있다.
+  - [x] SDD 사용자 리뷰가 없거나 승인/해결되었다.
+  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
+  - [x] Evidence Map이 완료 시 Roadmap Completion과 최종 검증 evidence로 검증 가능하게 연결되어 있다.
+- 결정 필요: 없음
+
+## 범위
+
+- immutable workflow definition version과 run·step state machine
+- PostgreSQL `SKIP LOCKED` lease, heartbeat, expiry와 ownership 검증
+- idempotency, retry backoff, terminal failure, cancel과 timeout
+- Go executor registry와 out-of-process Python executor adapter
+- progress event, artifact manifest와 결과 반영
+- worker crash·restart와 orphan lease 회수
+
+## 기능
+
+### Epic: [runtime] 영속 실행 상태
+
+동일 step이 여러 worker에서 동시에 부작용을 만들지 않도록 실행권을 제어한다.
+
+- [ ] [run-state] workflow run과 step run의 허용 상태 전이와 parent 완료 집계를 구현한다.
+- [ ] [lease-heartbeat] lease 획득·갱신·만료·회수를 ownership 조건으로 처리한다. 검증: 경쟁 worker와 worker crash 통합 테스트에서 단일 유효 owner만 완료 처리한다.
+- [ ] [retry-idempotency] retryable·terminal 오류, backoff와 idempotency key를 적용해 중복 결과를 방지한다.
+- [ ] [cancel-timeout] 대기·실행 step의 취소와 deadline 초과를 Go·Python executor에 전파한다.
+
+### Epic: [executor] 실행기 상호운용
+
+언어와 ML 프레임워크가 달라도 동일한 진행·결과 계약을 사용한다.
+
+- [ ] [executor-routing] capability와 executor kind에 따라 Go 또는 Python executor를 선택하고 호환되지 않는 job을 실행 전에 거부한다.
+- [ ] [progress-artifacts] 순서 있는 progress event, 결과 payload와 content-addressed artifact manifest를 영속 상태에 반영한다.
+- [ ] [restart-smoke] worker 재시작 뒤 만료 lease를 회수하고 완료·실패 상태가 유실되지 않는다. 검증: PostgreSQL과 Go/Python worker를 사용한 restart smoke가 통과한다.
+
+## 완료 리뷰
+
+- 상태: 없음
+- 요청일: 없음
+- 완료 근거: 모든 기능 Task와 검증 충족 및 구현 잠금 해제 여부를 완료 시 기록한다.
+- 검토 항목: 경쟁 lease, crash recovery, retry와 Go/Python field smoke
+- agent-ui 상태 반영: 해당 없음
+- 리뷰 코멘트: 없음
+
+## 범위 제외
+
+- 범용 DAG 편집기와 외부 workflow 엔진 도입
+- workflow step 내부의 RAG 품질 정책
+- production release 자동 승격
+
+## 작업 컨텍스트
+
+- 관련 경로: `packages/go/workflow/`, `packages/python/`, `api/proto/`, `db/queries/workflows.sql`
+- 표준선(선택): PostgreSQL lease queue, at-least-once 실행과 idempotent side effect
+- 선행 작업: [플랫폼 스캐폴드 기준선](../../platform-foundation/milestones/platform-scaffold-baseline.md)
+- 후속 작업: [수집과 Dataset 수명주기](../../knowledge-lifecycle/milestones/ingestion-and-dataset-lifecycle.md), [지속 갱신 Orchestration](continuous-refresh-orchestration.md)
+- 확인 필요: 없음

agent-roadmap/priority-queue.md

@@ -0,0 +1,38 @@
+# 전역 마일스톤 실행 순서
+
+이 문서는 Phase를 가로지르는 Milestone 실행 순서만 기록한다. 위에 있는 항목을 먼저 검토한다.
+
+## 실행 순서
+
+1. [플랫폼 스캐폴드 기준선](phase/platform-foundation/milestones/platform-scaffold-baseline.md)
+   현재 스캐폴드의 완료 근거를 검토하고 첫 구현 기준선으로 닫는다.
+2. [Integration 카탈로그와 Secret 경계](phase/platform-foundation/milestones/integration-catalog-and-secrets.md)
+   교체 가능한 provider를 검증·구성·바인딩하는 공통 계약을 완성한다.
+3. [Control Plane Resource API](phase/platform-foundation/milestones/control-plane-resource-api.md)
+   프로젝트 경계를 강제하는 공통 resource lifecycle API와 변경 계약을 완성한다.
+4. [내구성 있는 Workflow Runtime](phase/workflow-automation/milestones/durable-workflow-runtime.md)
+   lease, 재시도, 취소, 진행 이벤트를 포함한 장시간 실행 기반을 완성한다.
+5. [수집과 Dataset 수명주기](phase/knowledge-lifecycle/milestones/ingestion-and-dataset-lifecycle.md)
+   소스 변경을 정규화·버전 관리·lineage 추적 가능한 데이터셋으로 만든다.
+6. [Index 게시와 Release 수명주기](phase/rag-serving/milestones/index-publication-and-release.md)
+   후보 인덱스를 불변 릴리스로 게시하고 alias 승격과 롤백을 제공한다.
+7. [Retrieve와 Answer Pipeline](phase/rag-serving/milestones/retrieval-and-answer-pipeline.md)
+   릴리스 정책을 적용한 검색·리랭크·컨텍스트·생성 API를 완성한다.
+8. [평가와 승격 Gate](phase/quality-governance/milestones/evaluation-and-promotion-gates.md)
+   후보와 기준선을 비교해 명시적 승격·차단·롤백을 결정한다.
+9. [Retrieval 정책 최적화](phase/quality-governance/milestones/retrieval-policy-optimization.md)
+   검색 정책 후보를 재현 가능한 실험과 평가로 비교하고 명시적 승격 대상으로 만든다.
+10. [지속 갱신 Orchestration](phase/workflow-automation/milestones/continuous-refresh-orchestration.md)
+   주기·이벤트 기반으로 후보 생성과 평가를 반복하는 갱신 루프를 설계한다.
+11. [Drift와 선별 Feedback](phase/quality-governance/milestones/drift-and-selective-feedback.md)
+   저신뢰·shadow 불일치만 선별하는 품질 보정 데이터 흐름을 설계한다.
+12. [훈련 Dataset 정제](phase/selective-adaptation/milestones/training-dataset-curation.md)
+    검증된 feedback을 재현 가능한 train·validation·holdout 데이터셋으로 승격한다.
+13. [LoRA와 QLoRA 실행](phase/selective-adaptation/milestones/lora-qlora-execution.md)
+    선택적 adaptation 실행과 평가·artifact 승격 경계를 설계한다.
+14. [Identity·권한과 감사](phase/operations-productization/milestones/multi-project-security-and-audit.md)
+    외부 identity 연동, 세분화된 권한, 감사와 보존 정책을 제품화한다.
+15. [운영 UI](phase/operations-productization/milestones/operations-ui.md)
+    공통 Control Plane API를 소비하는 운영자 화면과 승인 흐름을 설계한다.
+16. [Production 신뢰성](phase/operations-productization/milestones/production-reliability.md)
+    배포 profile, 백업·복구, SLO와 장애 검증 경계를 설계한다.

agent-roadmap/sdd/knowledge-lifecycle/ingestion-and-dataset-lifecycle/SDD.md

@@ -0,0 +1,104 @@
+# SDD: 수집과 Dataset 수명주기
+
+## 위치
+
+- Milestone: [Milestone 문서](../../../phase/knowledge-lifecycle/milestones/ingestion-and-dataset-lifecycle.md)
+- Phase: [PHASE.md](../../../phase/knowledge-lifecycle/PHASE.md)
+
+## 상태
+
+[승인됨]
+
+## SDD 잠금
+
+- 상태: 해제
+- 사용자 리뷰: 없음
+- 잠금 항목:
+  - 없음
+
+## 문제 / 비목표
+
+- 문제: source change port와 dataset·artifact 테이블은 있으나 cursor commit, tombstone·ACL, canonical normalization, immutable version과 deterministic rebuild의 end-to-end 의미가 고정되지 않았다.
+- 비목표:
+  - retrieval index build와 release promotion
+  - source vendor별 모든 기능 표준화
+  - 대형 원문 content의 PostgreSQL 직접 저장
+
+## Source of Truth
+
+| 영역 | 기준 | 메모 |
+|------|------|------|
+| Roadmap | [Milestone 문서](../../../phase/knowledge-lifecycle/milestones/ingestion-and-dataset-lifecycle.md) | 수집·dataset 범위와 상태 원장 |
+| Code | [Source port](../../../../packages/go/integration/ports.go) | source cursor와 change stream 기준 |
+| External Provider | source revision·cursor | connector는 provider revision을 opaque 값으로 전달한다 |
+| User Decision | 없음 | RARA가 dataset·lineage를 소유하는 책임이 확정되어 있다 |
+
+## State Machine
+
+| 상태 | 진입 조건 | 다음 상태 | 근거 |
+|------|-----------|-----------|------|
+| pending | source가 등록되거나 새 revision이 감지됨 | syncing, disabled | source state |
+| syncing | workflow가 cursor lease와 snapshot을 획득함 | ready, failed | workflow run |
+| ready | raw·normalized·retrieval dataset version이 확정됨 | syncing, disabled | dataset publish event |
+| failed | step 오류로 cursor가 확정되지 않음 | syncing, disabled | failure result |
+| disabled | source가 운영상 비활성화됨 | pending | control-plane mutation |
+
+## Interface Contract
+
+- 계약 원문: [Source port](../../../../packages/go/integration/ports.go)
+- 입력:
+  - `SourceCursor`: 마지막 확정 provider revision과 opaque state
+  - `SourceChange`: key, operation, content, media type, metadata, ACL, revision, observed_at
+  - `recipe`: parser·normalizer·chunker version과 설정
+- 출력:
+  - raw snapshot artifact와 다음 cursor
+  - normalized document·chunk artifact
+  - immutable dataset version, stats와 lineage
+- 금지:
+  - artifact가 durable하지 않은 상태에서 cursor를 확정하지 않는다.
+  - tombstone과 ACL change를 일반 upsert로 축약하지 않는다.
+  - 동일 dataset version의 content를 in-place 변경하지 않는다.
+
+## Acceptance Scenarios
+
+| ID | Milestone Task | Given | When | Then |
+|----|----------------|-------|------|------|
+| S01 | `source-cursor` | paged source와 중간 failure | sync 재실행 | 마지막 durable cursor부터 재개하고 change를 잃지 않는다 |
+| S02 | `change-semantics` | upsert·delete·ACL change | 다음 dataset 생성 | 삭제 content가 제거되고 ACL revision이 lineage에 남는다 |
+| S03 | `connector-conformance` | fake와 최소 실제 connector | conformance suite | paging, retry, tombstone, cursor 시나리오를 통과한다 |
+| S04 | `normalization` | 동일 raw snapshot과 recipe | 반복 정규화 | canonical schema와 동일 content hash를 만든다 |
+| S05 | `dataset-version` | raw·normalized·retrieval artifact | publish | 목적별 불변 version과 stats가 생성된다 |
+| S06 | `artifact-lineage` | source revision부터 chunk 결과 | lineage 조회 | parent-child와 생성 step chain이 끊기지 않는다 |
+| S07 | `rebuild-recovery` | artifact publish 전후 failure | 동일 revision 재실행 | 확정 artifact를 재사용하고 실패 artifact는 격리한다 |
+
+## Evidence Map
+
+| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
+|----------|-------------------|------------------|---------------------------|
+| S01 | cursor commit·resume integration test | `agent-task/m-ingestion-and-dataset-lifecycle/...` | `source-cursor` no-loss evidence |
+| S02 | tombstone·ACL dataset diff | `agent-task/m-ingestion-and-dataset-lifecycle/...` | `change-semantics` deletion·ACL evidence |
+| S03 | connector conformance matrix | `agent-task/m-ingestion-and-dataset-lifecycle/...` | `connector-conformance` 결과 |
+| S04 | deterministic normalization test | `agent-task/m-ingestion-and-dataset-lifecycle/...` | `normalization` hash evidence |
+| S05 | immutable version mutation negative test | `agent-task/m-ingestion-and-dataset-lifecycle/...` | `dataset-version` version evidence |
+| S06 | lineage traversal query test | `agent-task/m-ingestion-and-dataset-lifecycle/...` | `artifact-lineage` full chain |
+| S07 | PostgreSQL·artifact fault injection smoke | `agent-task/m-ingestion-and-dataset-lifecycle/...` | `rebuild-recovery` reuse·quarantine evidence |
+
+## Cross-repo Dependencies
+
+- 없음
+
+## Drift Check
+
+- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
+- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
+- [x] source 계약 원문은 port 링크로 참조했다.
+- [x] 사용자 리뷰가 필요한 항목이 없다.
+
+## 사용자 리뷰 이력
+
+- 없음
+
+## 작업 컨텍스트
+
+- 표준선: cursor-after-durable-write, immutable dataset version, content-addressed artifact, explicit tombstone·ACL
+- 후속 SDD: [Index 게시와 Release 수명주기](../../rag-serving/index-publication-and-release/SDD.md)

agent-roadmap/sdd/operations-productization/multi-project-security-and-audit/SDD.md

@@ -0,0 +1,94 @@
+# SDD: Identity·권한과 감사
+
+## 위치
+
+- Milestone: [Milestone 문서](../../../phase/operations-productization/milestones/multi-project-security-and-audit.md)
+- Phase: [PHASE.md](../../../phase/operations-productization/PHASE.md)
+
+## 상태
+
+[초안]
+
+## SDD 잠금
+
+- 상태: 잠금
+- 사용자 리뷰: [요청됨](USER_REVIEW.md)
+- 잠금 항목:
+  - [D01] 초기 identity source of truth와 연동 방식
+
+## 문제 / 비목표
+
+- 문제: project boundary만으로는 사용자·서비스 actor mapping, resource·action authorization, secret access와 immutable audit·retention을 제품 수준으로 운영할 수 없다.
+- 비목표:
+  - identity provider 제품 구현
+  - 기본 project-scoped resource identity 재구현
+  - retrieval backend 내부 ACL 엔진 대체
+
+## Source of Truth
+
+| 영역 | 기준 | 메모 |
+|------|------|------|
+| Roadmap | [Milestone 문서](../../../phase/operations-productization/milestones/multi-project-security-and-audit.md) | identity·권한·감사 범위 |
+| Project Boundary | [Control Plane Resource API SDD](../../platform-foundation/control-plane-resource-api/SDD.md) | resource scope와 cross-project 기본 차단 |
+| Secret | [Integration 카탈로그 SDD](../../platform-foundation/integration-catalog-and-secrets/SDD.md) | secret reference와 runtime resolution |
+| User Decision | [USER_REVIEW.md](USER_REVIEW.md) | identity source of truth |
+
+## State Machine
+
+| 상태 | 진입 조건 | 다음 상태 | 근거 |
+|------|-----------|-----------|------|
+| pending | external 또는 local identity가 처음 관찰됨 | active, rejected | mapping record |
+| active | identity mapping과 project membership이 유효함 | suspended, revoked | membership revision |
+| suspended | 일시 차단 또는 provider 상태 불명확 | active, revoked | admin action |
+| revoked | mapping·credential 사용이 종료됨 | 없음 | revoke audit |
+
+## Interface Contract
+
+- 입력: authenticated principal, project, resource, action, reason과 correlation identity
+- 출력: allow·deny decision, matched policy revision, secret resolution scope와 immutable audit event
+- 금지:
+  - identity mapping이 불명확한 principal을 implicit admin으로 처리하지 않는다.
+  - authorization decision 없이 secret을 resolve하지 않는다.
+  - audit actor·reason·result를 사후 수정하지 않는다.
+
+## Acceptance Scenarios
+
+| ID | Milestone Task | Given | When | Then |
+|----|----------------|-------|------|------|
+| S01 | `identity-boundary` | user·service·external principal | mapping·sync | source와 project membership이 추적 가능하게 연결된다 |
+| S02 | `rbac` | role·resource·action policy | API·worker 요청 | 같은 policy revision으로 allow·deny가 결정된다 |
+| S03 | `secret-scope` | identity·project·executor | secret resolve | 승인된 범위만 일회성으로 resolve된다 |
+| S04 | `audit-events` | 변경·거부·실패 action | 처리 | actor·target·reason·result가 immutable event로 남는다 |
+| S05 | `retention-policy` | trace·feedback·dataset·audit | 만료·삭제 | 유형별 redaction·retention·deletion 규칙이 적용된다 |
+| S06 | `isolation-tests` | unauthorized·mapping 오류·tampering case | negative suite | action·secret이 차단되고 audit 변조가 검출된다 |
+
+## Evidence Map
+
+| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
+|----------|-------------------|------------------|---------------------------|
+| S01 | identity mapping lifecycle test | `agent-task/m-multi-project-security-and-audit/...` | `identity-boundary` evidence |
+| S02 | role·permission matrix | `agent-task/m-multi-project-security-and-audit/...` | `rbac` allow·deny evidence |
+| S03 | cross-project·executor secret test | `agent-task/m-multi-project-security-and-audit/...` | `secret-scope` deny evidence |
+| S04 | immutable audit test | `agent-task/m-multi-project-security-and-audit/...` | `audit-events` chain |
+| S05 | retention·redaction deletion test | `agent-task/m-multi-project-security-and-audit/...` | `retention-policy` evidence |
+| S06 | authorization·tamper negative suite | `agent-task/m-multi-project-security-and-audit/...` | `isolation-tests` PASS |
+
+## Cross-repo Dependencies
+
+- 없음
+
+## Drift Check
+
+- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
+- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
+- [x] project boundary와 identity·authorization 책임을 분리했다.
+- [ ] 사용자 결정 [D01]이 해결되었다.
+
+## 사용자 리뷰 이력
+
+- [USER_REVIEW.md](USER_REVIEW.md) 요청 중
+
+## 작업 컨텍스트
+
+- 표준선: deny-by-default, external principal mapping, policy revision, scoped secret, immutable audit
+- Milestone은 `[스케치]`이며 [D01]과 승격 조건이 해소될 때까지 구현 잠금 상태를 유지한다.

agent-roadmap/sdd/operations-productization/multi-project-security-and-audit/USER_REVIEW.md

@@ -0,0 +1,37 @@
+# SDD User Review
+
+## 상태
+
+요청됨
+
+## 검토 대상
+
+- SDD: [SDD.md](SDD.md)
+- Milestone: [Milestone 문서](../../../phase/operations-productization/milestones/multi-project-security-and-audit.md)
+
+## 사용자 결정 항목
+
+### [D01] 초기 Identity Source of Truth
+
+- 결정 필요: 초기 사용자·서비스 identity를 RARA가 직접 소유할지 외부 identity provider에서 매핑할지 결정해야 한다.
+- 추천안: 외부 identity provider를 source of truth로 두고 RARA는 immutable external subject와 project membership·role mapping만 소유한다.
+- 대안: 초기에는 RARA 내장 계정을 제공하고 이후 federation을 추가한다.
+- 영향: 인증 API 범위, account lifecycle, credential 책임, 운영 UI와 감사 schema가 달라진다.
+- 적용 위치:
+  - SDD: `Source of Truth`, `State Machine`, `Interface Contract`
+  - Milestone: `승격 조건`, `구현 잠금`
+
+## 승인 항목
+
+- [ ] 위 결정 항목을 승인했다.
+- [ ] SDD 잠금 해제를 승인했다.
+
+## 답변 기록
+
+- 없음
+
+## 해결 조건
+
+- 모든 사용자 결정 항목의 답변이 SDD에 반영되어 있다.
+- `USER_REVIEW.md`가 `user_review_N.log`로 이동되어 있다.
+- 남은 잠금 항목이 없으면 SDD 상태가 `[승인됨]`이고 `SDD 잠금` 상태가 `해제`다.

agent-roadmap/sdd/operations-productization/operations-ui/SDD.md

@@ -0,0 +1,85 @@
+# SDD: 운영 UI
+
+## 위치
+
+- Milestone: [Milestone 문서](../../../phase/operations-productization/milestones/operations-ui.md)
+- Phase: [PHASE.md](../../../phase/operations-productization/PHASE.md)
+
+## 상태
+
+[초안]
+
+## SDD 잠금
+
+- 상태: 잠금
+- 사용자 리뷰: [요청됨](USER_REVIEW.md)
+- 잠금 항목:
+  - [D01] 첫 delivery surface와 우선 사용자 역할
+
+## 문제 / 비목표
+
+- 문제: Control Plane resource와 workflow·quality 상태를 API나 DB로 직접 조작하지 않고 권한·감사와 함께 운영할 제품 surface가 필요하다.
+- 비목표:
+  - 별도 운영 상태 저장
+  - production 배포·backup·restore
+  - identity provider 구현
+
+## Source of Truth
+
+| 영역 | 기준 | 메모 |
+|------|------|------|
+| Roadmap | [Milestone 문서](../../../phase/operations-productization/milestones/operations-ui.md) | 운영 여정과 화면 범위 |
+| API | [Control Plane Resource API SDD](../../platform-foundation/control-plane-resource-api/SDD.md) | resource lifecycle과 오류 계약 |
+| Security | [Identity·권한과 감사 SDD](../multi-project-security-and-audit/SDD.md) | role, action과 audit |
+| User Decision | [USER_REVIEW.md](USER_REVIEW.md) | delivery surface와 첫 역할 |
+
+## State Machine
+
+UI는 독립 도메인 상태를 소유하지 않는다. resource·workflow·evaluation·release 상태를 API에서 읽고, mutation은 `idle -> submitting -> succeeded | failed | conflict`의 화면 상태로만 표현한다.
+
+## Interface Contract
+
+- 입력: project-scoped resource query, workflow command, promotion·rollback command, revision과 audit reason
+- 출력: resource·lineage·quality view model, action result와 stable error presentation
+- 금지:
+  - UI 전용 backend 상태로 domain lifecycle을 복제하지 않는다.
+  - forbidden action을 단순히 숨기는 것만으로 authorization을 대체하지 않는다.
+  - destructive action을 stale revision·reason 없이 제출하지 않는다.
+
+## Acceptance Scenarios
+
+| ID | Milestone Task | Given | When | Then |
+|----|----------------|-------|------|------|
+| S01 | `resource-ui` | project-scoped resource | 조회·변경 | state·revision·validation 결과가 API와 일치한다 |
+| S02 | `workflow-ui` | running·failed workflow | 조회·retry·cancel | step·artifact lineage와 command 결과가 표시된다 |
+| S03 | `quality-ui` | evaluation과 eligible release | promotion·rollback | 비교 근거·actor reason·결과 audit가 연결된다 |
+| S04 | `accessibility-state` | loading·empty·error·forbidden·conflict | 화면 전환 | 역할과 접근성 기준에 맞는 상태가 일관되게 표현된다 |
+
+## Evidence Map
+
+| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
+|----------|-------------------|------------------|---------------------------|
+| S01 | resource UI contract·component test | `agent-task/m-operations-ui/...` | `resource-ui` evidence |
+| S02 | workflow state·command test | `agent-task/m-operations-ui/...` | `workflow-ui` evidence |
+| S03 | promotion·rollback end-to-end test | `agent-task/m-operations-ui/...` | `quality-ui` audit evidence |
+| S04 | state matrix·accessibility validation | `agent-task/m-operations-ui/...` | `accessibility-state` evidence |
+
+## Cross-repo Dependencies
+
+- 없음
+
+## Drift Check
+
+- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
+- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
+- [x] UI가 Control Plane API를 단일 source로 사용한다.
+- [ ] 사용자 결정 [D01]이 해결되었다.
+
+## 사용자 리뷰 이력
+
+- [USER_REVIEW.md](USER_REVIEW.md) 요청 중
+
+## 작업 컨텍스트
+
+- 표준선: API-first UI, least privilege, stale-write protection, accessible state
+- Milestone은 `[스케치]`이며 agent-ui 생성, [D01]과 승격 조건이 해소될 때까지 구현 잠금 상태를 유지한다.

agent-roadmap/sdd/operations-productization/operations-ui/USER_REVIEW.md

@@ -0,0 +1,37 @@
+# SDD User Review
+
+## 상태
+
+요청됨
+
+## 검토 대상
+
+- SDD: [SDD.md](SDD.md)
+- Milestone: [Milestone 문서](../../../phase/operations-productization/milestones/operations-ui.md)
+
+## 사용자 결정 항목
+
+### [D01] 첫 운영 UI Surface와 역할
+
+- 결정 필요: 첫 delivery surface와 MVP가 우선 지원할 사용자 역할을 확정해야 한다.
+- 추천안: 브라우저 중심 Flutter UI와 플랫폼 운영자 역할 하나로 시작하고, project operator·viewer는 후속 권한 profile로 확장한다.
+- 대안: CLI·TUI를 먼저 제공하거나 여러 역할을 첫 버전에 동시에 지원한다.
+- 영향: agent-ui 정보 구조, 인증 연동, route, 권한 matrix, 테스트 surface와 일정이 달라진다.
+- 적용 위치:
+  - SDD: `Source of Truth`, `Interface Contract`
+  - Milestone: `승격 조건`, `구현 잠금`
+
+## 승인 항목
+
+- [ ] 위 결정 항목을 승인했다.
+- [ ] SDD 잠금 해제를 승인했다.
+
+## 답변 기록
+
+- 없음
+
+## 해결 조건
+
+- 모든 사용자 결정 항목의 답변이 SDD에 반영되어 있다.
+- `USER_REVIEW.md`가 `user_review_N.log`로 이동되어 있다.
+- 남은 잠금 항목이 없으면 SDD 상태가 `[승인됨]`이고 `SDD 잠금` 상태가 `해제`다.

agent-roadmap/sdd/operations-productization/production-reliability/SDD.md

@@ -0,0 +1,94 @@
+# SDD: Production 신뢰성
+
+## 위치
+
+- Milestone: [Milestone 문서](../../../phase/operations-productization/milestones/production-reliability.md)
+- Phase: [PHASE.md](../../../phase/operations-productization/PHASE.md)
+
+## 상태
+
+[초안]
+
+## SDD 잠금
+
+- 상태: 잠금
+- 사용자 리뷰: [요청됨](USER_REVIEW.md)
+- 잠금 항목:
+  - [D01] 첫 production 배포 profile의 목표 환경
+
+## 문제 / 비목표
+
+- 문제: 개발 스캐폴드에서 production 운영으로 전환하려면 환경별 deployment profile, migration·rollback, 분리 저장소 backup·restore와 SLO·재해 검증 계약이 필요하다.
+- 비목표:
+  - 모든 cloud·orchestrator 동시 지원
+  - 외부 retrieval·artifact 저장소 자체 구현
+  - 조직 전체 incident management 제품
+
+## Source of Truth
+
+| 영역 | 기준 | 메모 |
+|------|------|------|
+| Roadmap | [Milestone 문서](../../../phase/operations-productization/milestones/production-reliability.md) | 배포·복구·관측 범위 |
+| Control State | PostgreSQL migration과 backup manifest | 제어 상태 source of truth |
+| External State | provider별 artifact·index identity와 backup pointer | adapter가 복구 capability를 노출한다 |
+| User Decision | [USER_REVIEW.md](USER_REVIEW.md) | 첫 production 환경과 topology |
+
+## State Machine
+
+| 상태 | 진입 조건 | 다음 상태 | 근거 |
+|------|-----------|-----------|------|
+| planned | profile·version·migration preflight가 생성됨 | deploying, rejected | deployment record |
+| deploying | rollout이 시작됨 | healthy, degraded, failed, rolling_back | health event |
+| healthy | readiness와 필수 smoke가 통과함 | degraded, deploying | release status |
+| degraded | SLO 또는 provider dependency가 임계치를 위반함 | healthy, rolling_back, failed | alert event |
+| rolling_back | 이전 compatible version 복구가 시작됨 | healthy, failed | rollback event |
+| failed | rollout·rollback이 복구 불가로 실패함 | planned | incident evidence |
+
+## Interface Contract
+
+- 입력: deployment profile revision, application·schema version, secret references, backup manifest와 recovery target
+- 출력: rollout state, migration result, backup·restore manifest, SLI·SLO와 RPO·RTO evidence
+- 금지:
+  - 호환성 preflight와 backup 없이 destructive migration을 실행하지 않는다.
+  - 외부 artifact·index pointer를 검증하지 않은 DB snapshot을 복구 완료로 선언하지 않는다.
+  - readiness만으로 데이터 복구와 핵심 workflow smoke를 대체하지 않는다.
+
+## Acceptance Scenarios
+
+| ID | Milestone Task | Given | When | Then |
+|----|----------------|-------|------|------|
+| S01 | `deployment-profiles` | local·single-node·선택 production 환경 | config render | topology·secret·resource 요구가 profile로 분리된다 |
+| S02 | `migration-rollout` | compatible·incompatible schema change | rollout·rollback | preflight가 위험 변경을 차단하고 이전 버전으로 복구한다 |
+| S03 | `backup-restore` | PostgreSQL과 외부 pointer | backup·restore | 일관된 manifest와 검증된 resource identity가 복구된다 |
+| S04 | `slo-observability` | ingestion·workflow·RAG·provider signal | 집계 | SLI·SLO·alert 상태가 원인과 함께 노출된다 |
+| S05 | `disaster-smoke` | restart·restore·provider outage | smoke 실행 | RPO·RTO와 기능 복구 evidence가 생성된다 |
+
+## Evidence Map
+
+| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
+|----------|-------------------|------------------|---------------------------|
+| S01 | profile render·validation test | `agent-task/m-production-reliability/...` | `deployment-profiles` evidence |
+| S02 | migration compatibility·rollback test | `agent-task/m-production-reliability/...` | `migration-rollout` evidence |
+| S03 | backup·restore rehearsal | `agent-task/m-production-reliability/...` | `backup-restore` manifest |
+| S04 | SLI calculation·alert test | `agent-task/m-production-reliability/...` | `slo-observability` evidence |
+| S05 | disaster scenario suite | `agent-task/m-production-reliability/...` | `disaster-smoke` RPO·RTO evidence |
+
+## Cross-repo Dependencies
+
+- 없음
+
+## Drift Check
+
+- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
+- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
+- [x] 제어 상태와 외부 artifact·index 복구 책임을 분리했다.
+- [ ] 사용자 결정 [D01]이 해결되었다.
+
+## 사용자 리뷰 이력
+
+- [USER_REVIEW.md](USER_REVIEW.md) 요청 중
+
+## 작업 컨텍스트
+
+- 표준선: versioned profile, compatibility preflight, manifest-based restore, SLO evidence
+- Milestone은 `[스케치]`이며 [D01]과 승격 조건이 해소될 때까지 구현 잠금 상태를 유지한다.

agent-roadmap/sdd/operations-productization/production-reliability/USER_REVIEW.md

@@ -0,0 +1,37 @@
+# SDD User Review
+
+## 상태
+
+요청됨
+
+## 검토 대상
+
+- SDD: [SDD.md](SDD.md)
+- Milestone: [Milestone 문서](../../../phase/operations-productization/milestones/production-reliability.md)
+
+## 사용자 결정 항목
+
+### [D01] 첫 Production 배포 Profile
+
+- 결정 필요: 첫 production 목표 환경과 지원 topology를 확정해야 한다.
+- 추천안: 컨테이너 기반 단일 노드 profile을 먼저 production 기준선으로 만들고, 외부 PostgreSQL·artifact·retrieval provider를 연결한 뒤 분산 orchestrator profile을 후속으로 둔다.
+- 대안: 처음부터 Kubernetes 기반 다중 replica profile을 기준선으로 삼는다.
+- 영향: 배포 artifact, secret 방식, migration·rollout, backup orchestration, HA·SLO와 테스트 인프라가 달라진다.
+- 적용 위치:
+  - SDD: `Source of Truth`, `State Machine`, `Acceptance Scenarios`
+  - Milestone: `승격 조건`, `구현 잠금`
+
+## 승인 항목
+
+- [ ] 위 결정 항목을 승인했다.
+- [ ] SDD 잠금 해제를 승인했다.
+
+## 답변 기록
+
+- 없음
+
+## 해결 조건
+
+- 모든 사용자 결정 항목의 답변이 SDD에 반영되어 있다.
+- `USER_REVIEW.md`가 `user_review_N.log`로 이동되어 있다.
+- 남은 잠금 항목이 없으면 SDD 상태가 `[승인됨]`이고 `SDD 잠금` 상태가 `해제`다.

agent-roadmap/sdd/platform-foundation/control-plane-resource-api/SDD.md

@@ -0,0 +1,103 @@
+# SDD: Control Plane Resource API
+
+## 위치
+
+- Milestone: [Milestone 문서](../../../phase/platform-foundation/milestones/control-plane-resource-api.md)
+- Phase: [PHASE.md](../../../phase/platform-foundation/PHASE.md)
+
+## 상태
+
+[승인됨]
+
+## SDD 잠금
+
+- 상태: 해제
+- 사용자 리뷰: 없음
+- 잠금 항목:
+  - 없음
+
+## 문제 / 비목표
+
+- 문제: domain schema와 service scaffold는 있으나 운영 UI·CLI·worker가 공유할 project-scoped resource lifecycle, 오류, 페이지네이션과 동시성 계약이 없다.
+- 비목표:
+  - 외부 identity provider 연동과 세분화된 RBAC
+  - online retrieve·answer data plane
+  - UI 구현
+
+## Source of Truth
+
+| 영역 | 기준 | 메모 |
+|------|------|------|
+| Roadmap | [Milestone 문서](../../../phase/platform-foundation/milestones/control-plane-resource-api.md) | 관리 resource 범위와 project boundary |
+| Code | [Control Plane 앱](../../../../apps/control-plane/) | HTTP 진입점과 composition root |
+| Schema | [초기 제어 상태 스키마](../../../../db/migrations/00001_initial.sql) | project와 초기 resource identity |
+| User Decision | 없음 | project-scoped 관리 경계를 초기 표준선으로 사용한다 |
+
+## State Machine
+
+| 상태 | 진입 조건 | 다음 상태 | 근거 |
+|------|-----------|-----------|------|
+| active | 비활성화 가능한 구성 resource 생성과 validation이 성공함 | disabled | resource revision |
+| disabled | 명시적 비활성화가 revision 조건과 함께 성공함 | active | mutation audit |
+
+이 공통 상태는 source·knowledge base 같은 구성 resource에만 적용한다. dataset·workflow·evaluation·release의 세부 상태는 각 수명주기 SDD가 소유하며 공통 API가 임의로 합치지 않는다.
+
+## Interface Contract
+
+- 계약 원문: `api/openapi/`에 versioned management API를 게시하고 구현 시 source of truth로 사용한다.
+- 입력:
+  - `project_id`: 모든 project-owned resource route와 query의 필수 scope. project 자체는 격리 root identity로 다룬다.
+  - `Idempotency-Key`: 생성과 명령형 mutation의 replay identity
+  - `If-Match` 또는 동등한 `revision`: optimistic concurrency 조건
+  - cursor, filter와 bounded page size
+- 출력:
+  - stable resource identity, revision과 lifecycle state
+  - opaque next cursor
+  - stable error code, message, correlation identity와 retryability
+- 금지:
+  - project-owned resource에 project scope 없는 목록·변경 요청을 허용하지 않는다.
+  - offset pagination을 공개 안정 계약으로 사용하지 않는다.
+  - stale revision을 last-write-wins로 덮어쓰지 않는다.
+  - 같은 idempotency key의 다른 payload를 성공 replay로 처리하지 않는다.
+
+## Acceptance Scenarios
+
+| ID | Milestone Task | Given | When | Then |
+|----|----------------|-------|------|------|
+| S01 | `project-boundary` | 서로 다른 두 project와 resource | 교차 project read·write | 존재 여부를 누출하지 않고 거부한다 |
+| S02 | `resource-lifecycle` | 지원 resource 종류 | create·get·list·update·disable | 공통 identity·revision 의미로 동작한다 |
+| S03 | `api-consistency` | 여러 page와 stale revision | list·update | cursor는 안정적으로 이어지고 stale write는 conflict가 된다 |
+| S04 | `mutation-idempotency` | 동일 key의 동일·상이 payload | mutation replay | 동일 payload는 같은 결과, 상이 payload는 conflict가 된다 |
+| S05 | `management-contract` | 관리 API schema | 계약 게시 | 소비자가 versioned OpenAPI로 요청·오류를 생성·검증한다 |
+| S06 | `lifecycle-tests` | resource와 project matrix | contract suite 실행 | 상태 전이와 cross-project negative case가 통과한다 |
+
+## Evidence Map
+
+| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
+|----------|-------------------|------------------|---------------------------|
+| S01 | cross-project negative integration test | `agent-task/m-control-plane-resource-api/...` | `project-boundary` deny evidence |
+| S02 | resource lifecycle contract matrix | `agent-task/m-control-plane-resource-api/...` | `resource-lifecycle` API evidence |
+| S03 | cursor·stale revision test | `agent-task/m-control-plane-resource-api/...` | `api-consistency` pagination·conflict evidence |
+| S04 | idempotency replay·mismatch test | `agent-task/m-control-plane-resource-api/...` | `mutation-idempotency` replay evidence |
+| S05 | OpenAPI validation·compatibility check | `agent-task/m-control-plane-resource-api/...` | `management-contract` artifact |
+| S06 | lifecycle and isolation suite | `agent-task/m-control-plane-resource-api/...` | `lifecycle-tests` PASS evidence |
+
+## Cross-repo Dependencies
+
+- 없음
+
+## Drift Check
+
+- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
+- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
+- [x] project boundary와 도메인별 lifecycle 책임을 분리했다.
+- [x] 사용자 리뷰가 필요한 항목이 없다.
+
+## 사용자 리뷰 이력
+
+- 없음
+
+## 작업 컨텍스트
+
+- 표준선: project-scoped identity, cursor pagination, optimistic concurrency, stable error, idempotent mutation
+- 후속 SDD: [내구성 있는 Workflow Runtime](../../workflow-automation/durable-workflow-runtime/SDD.md), [수집과 Dataset 수명주기](../../knowledge-lifecycle/ingestion-and-dataset-lifecycle/SDD.md)

agent-roadmap/sdd/platform-foundation/integration-catalog-and-secrets/SDD.md

@@ -0,0 +1,103 @@
+# SDD: Integration 카탈로그와 Secret 경계
+
+## 위치
+
+- Milestone: [Milestone 문서](../../../phase/platform-foundation/milestones/integration-catalog-and-secrets.md)
+- Phase: [PHASE.md](../../../phase/platform-foundation/PHASE.md)
+
+## 상태
+
+[승인됨]
+
+## SDD 잠금
+
+- 상태: 해제
+- 사용자 리뷰: 없음
+- 잠금 항목:
+  - 없음
+
+## 문제 / 비목표
+
+- 문제: 제품 중립 port는 존재하지만 integration instance의 수명주기, manifest 호환성, secret resolution과 runtime binding 규칙이 아직 실행 가능한 계약으로 연결되지 않았다.
+- 비목표:
+  - runtime Go plugin과 임의 바이너리 설치
+  - secret vault 제품 자체 구현
+  - vendor request·response 타입의 공통 계약 노출
+
+## Source of Truth
+
+| 영역 | 기준 | 메모 |
+|------|------|------|
+| Roadmap | [Milestone 문서](../../../phase/platform-foundation/milestones/integration-catalog-and-secrets.md) | 범위와 완료 상태 원장 |
+| Code | [Integration ports](../../../../packages/go/integration/ports.go) | 제품 중립 capability 계약 |
+| External Provider | 없음 | provider별 adapter는 이 계약을 구현한다 |
+| User Decision | 없음 | secret reference와 compile-time registry 방향이 확정되어 있다 |
+
+## State Machine
+
+| 상태 | 진입 조건 | 다음 상태 | 근거 |
+|------|-----------|-----------|------|
+| configured | instance와 config·secret_ref가 저장됨 | validated, invalid | control-plane mutation |
+| validated | manifest와 config schema가 호환됨 | active, disabled, invalid | conformance 결과 |
+| active | factory binding과 필수 health가 통과함 | disabled, invalid | activation event |
+| disabled | 운영자 또는 정책이 비활성화함 | validated | revision update |
+| invalid | schema·capability·secret binding이 실패함 | configured, validated | validation evidence |
+
+## Interface Contract
+
+- 계약 원문: [Integration ports](../../../../packages/go/integration/ports.go)
+- 입력:
+  - `project_id`: integration을 소유하는 project
+  - `kind`, `implementation`, `schema_version`: factory와 manifest identity
+  - `config`: secret 원문이 없는 adapter 설정
+  - `secret_ref`: runtime resolver에 전달할 opaque reference
+- 출력:
+  - `capabilities`: 검증된 versioned capability
+  - `binding`: 요청 범위에서 사용할 typed adapter
+  - `health`: 활성화와 readiness에 사용할 상태
+- 금지:
+  - config, log, trace, error에 secret 원문을 저장하지 않는다.
+  - capability가 맞지 않는 adapter를 fallback으로 암묵 선택하지 않는다.
+  - 특정 vendor 타입을 control-plane이나 RAG 공개 계약으로 노출하지 않는다.
+
+## Acceptance Scenarios
+
+| ID | Milestone Task | Given | When | Then |
+|----|----------------|-------|------|------|
+| S01 | `catalog-lifecycle` | project와 유효한 instance revision | create·update·disable 요청 | revision과 상태가 project 범위에서 조회된다 |
+| S02 | `manifest-validation` | 호환·비호환 manifest와 config | 활성화 검증 | 호환 항목만 validated로 전이한다 |
+| S03 | `secret-resolution` | secret_ref가 있는 instance | runtime binding | resolver가 요청 시점에만 secret을 제공하고 원문이 영속화되지 않는다 |
+| S04 | `runtime-binding` | active instance와 factory registry | adapter 요청 | kind·version·capability가 일치하는 typed adapter만 반환한다 |
+| S05 | `conformance-suite` | fake와 최소 실제 adapter | port conformance 실행 | 동일 필수 시나리오를 통과한다 |
+| S06 | `adapter-telemetry` | 성공·실패 provider 호출 | metric·trace 수집 | capability identity와 오류 등급은 남고 secret은 남지 않는다 |
+
+## Evidence Map
+
+| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
+|----------|-------------------|------------------|---------------------------|
+| S01 | control-plane integration lifecycle test | `agent-task/m-integration-catalog-and-secrets/...` | `catalog-lifecycle` 완료와 revision evidence |
+| S02 | manifest·config validation matrix | `agent-task/m-integration-catalog-and-secrets/...` | `manifest-validation` pass·reject evidence |
+| S03 | secret persistence·log negative test | `agent-task/m-integration-catalog-and-secrets/...` | `secret-resolution` redaction evidence |
+| S04 | capability binding unit·integration test | `agent-task/m-integration-catalog-and-secrets/...` | `runtime-binding` fail-closed evidence |
+| S05 | fake·실제 adapter conformance 결과 | `agent-task/m-integration-catalog-and-secrets/...` | `conformance-suite` provider matrix |
+| S06 | telemetry snapshot과 secret scan | `agent-task/m-integration-catalog-and-secrets/...` | `adapter-telemetry` metric·trace evidence |
+
+## Cross-repo Dependencies
+
+- 없음
+
+## Drift Check
+
+- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
+- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
+- [x] agent-contract 원문을 SDD에 복제하지 않았다.
+- [x] 사용자 리뷰가 필요한 항목이 없다.
+
+## 사용자 리뷰 이력
+
+- 없음
+
+## 작업 컨텍스트
+
+- 표준선: compile-time registry, versioned manifest, fail-closed binding, secret reference
+- 후속 SDD: [수집과 Dataset 수명주기](../../knowledge-lifecycle/ingestion-and-dataset-lifecycle/SDD.md), [Index 게시와 Release 수명주기](../../rag-serving/index-publication-and-release/SDD.md)

agent-roadmap/sdd/quality-governance/drift-and-selective-feedback/SDD.md

@@ -0,0 +1,96 @@
+# SDD: Drift와 선별 Feedback
+
+## 위치
+
+- Milestone: [Milestone 문서](../../../phase/quality-governance/milestones/drift-and-selective-feedback.md)
+- Phase: [PHASE.md](../../../phase/quality-governance/PHASE.md)
+
+## 상태
+
+[승인됨]
+
+## SDD 잠금
+
+- 상태: 해제
+- 사용자 리뷰: 없음
+- 잠금 항목:
+  - 없음
+
+## 문제 / 비목표
+
+- 문제: 운영 품질 변화와 저신뢰 사례를 감지하되 요청 전량 저장·자기 학습 없이 보정 가치가 있는 사례만 안전하게 분류하는 계약이 없다.
+- 비목표:
+  - active 요청 전량 저장
+  - confidence 하나로 자동 모델 교체
+  - shadow 결과를 자동 정답으로 취급
+
+## Source of Truth
+
+| 영역 | 기준 | 메모 |
+|------|------|------|
+| Roadmap | [Milestone 문서](../../../phase/quality-governance/milestones/drift-and-selective-feedback.md) | drift와 selective capture 경계 |
+| Evaluation | [평가와 승격 Gate SDD](../evaluation-and-promotion-gates/SDD.md) | 비교 metric과 evaluation case |
+| Release | [Retrieve와 Answer Pipeline SDD](../../rag-serving/retrieval-and-answer-pipeline/SDD.md) | release·evidence trace |
+| User Decision | 없음 | shadow 비율·보존기간은 project policy로 구성한다 |
+
+## State Machine
+
+| 상태 | 진입 조건 | 다음 상태 | 근거 |
+|------|-----------|-----------|------|
+| observed | drift·confidence·feedback signal이 생성됨 | selected, discarded | signal event |
+| selected | capture policy와 privacy precheck를 통과함 | quarantined, routed, discarded | selection verdict |
+| quarantined | consent·license·민감 정보 확인이 필요함 | routed, discarded | review record |
+| routed | RAG 보정·evaluation·training 후보로 분류됨 | expired | feedback item |
+| discarded | 가치·정책 기준을 통과하지 못함 | 없음 | reason code |
+| expired | retention이 만료됨 | 없음 | deletion event |
+
+## Interface Contract
+
+- 입력: release·segment window, calibrated signals, bounded shadow result, explicit feedback와 capture policy
+- 출력: drift aggregate, redacted feedback item, provenance, route와 retention deadline
+- 금지:
+  - opt-in·선별 policy 없이 원문 요청을 저장하지 않는다.
+  - shadow 결과를 검증 없이 teacher label로 승격하지 않는다.
+  - project retention을 넘겨 원문을 유지하지 않는다.
+
+## Acceptance Scenarios
+
+| ID | Milestone Task | Given | When | Then |
+|----|----------------|-------|------|------|
+| S01 | `drift-windows` | release·segment별 metric | window 집계 | quality·latency·freshness 추세가 분리된다 |
+| S02 | `confidence-calibration` | retrieval·rerank·validation signal | calibration | 재현 가능한 confidence와 calibration evidence가 생성된다 |
+| S03 | `shadow-comparison` | 비율·비용 제한 | shadow 실행 | 한도 안의 사례만 비교되고 usage가 남는다 |
+| S04 | `selective-capture` | low-confidence·차이·feedback·error | selection | 정책을 통과한 사례만 저장 후보가 된다 |
+| S05 | `privacy-dedup` | 저장 후보와 privacy policy | 보존 전 처리 | redaction·consent·retention·dedup이 적용된다 |
+| S06 | `feedback-routing` | 검증된 feedback item | 분류 | RAG·evaluation·training 중 명시적 route가 기록된다 |
+
+## Evidence Map
+
+| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
+|----------|-------------------|------------------|---------------------------|
+| S01 | release·segment aggregation test | `agent-task/m-drift-and-selective-feedback/...` | `drift-windows` trend evidence |
+| S02 | calibration dataset·metric test | `agent-task/m-drift-and-selective-feedback/...` | `confidence-calibration` evidence |
+| S03 | shadow budget boundary test | `agent-task/m-drift-and-selective-feedback/...` | `shadow-comparison` bounded usage |
+| S04 | selective capture policy matrix | `agent-task/m-drift-and-selective-feedback/...` | `selective-capture` accept·discard evidence |
+| S05 | privacy·retention·dedup test | `agent-task/m-drift-and-selective-feedback/...` | `privacy-dedup` evidence |
+| S06 | routing decision matrix | `agent-task/m-drift-and-selective-feedback/...` | `feedback-routing` provenance |
+
+## Cross-repo Dependencies
+
+- 없음
+
+## Drift Check
+
+- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
+- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
+- [x] active 전량 수집 금지와 bounded shadow를 고정했다.
+- [x] 사용자 리뷰가 필요한 항목이 없다.
+
+## 사용자 리뷰 이력
+
+- 없음
+
+## 작업 컨텍스트
+
+- 표준선: selective capture, calibrated signals, bounded shadow, privacy-before-retention
+- Milestone은 `[스케치]`이므로 승격 조건이 모두 해소될 때까지 구현 잠금 상태를 유지한다.

agent-roadmap/sdd/quality-governance/evaluation-and-promotion-gates/SDD.md

@@ -0,0 +1,108 @@
+# SDD: 평가와 승격 Gate
+
+## 위치
+
+- Milestone: [Milestone 문서](../../../phase/quality-governance/milestones/evaluation-and-promotion-gates.md)
+- Phase: [PHASE.md](../../../phase/quality-governance/PHASE.md)
+
+## 상태
+
+[승인됨]
+
+## SDD 잠금
+
+- 상태: 해제
+- 사용자 리뷰: 없음
+- 잠금 항목:
+  - 없음
+
+## 문제 / 비목표
+
+- 문제: evaluation·release 상태 스키마는 있으나 suite revision, candidate-baseline 비교, metric gate, 수동 promotion 자격과 rollback audit의 연결 계약이 없다.
+- 비목표:
+  - 자동 production promotion
+  - 범용 LLM judge 제품 전체 구현
+  - evaluation과 training dataset의 동일 객체 사용
+
+## Source of Truth
+
+| 영역 | 기준 | 메모 |
+|------|------|------|
+| Roadmap | [Milestone 문서](../../../phase/quality-governance/milestones/evaluation-and-promotion-gates.md) | 평가·승격 범위와 상태 원장 |
+| Code | [초기 제어 상태 스키마](../../../../db/migrations/00001_initial.sql) | suite, run, result와 release 상태 기준 |
+| External Provider | evaluator와 model provider version | evaluation 실행 identity로 snapshot한다 |
+| User Decision | 없음 | 초기 production 승격은 수동이라는 정책이 확정되어 있다 |
+
+## State Machine
+
+| 상태 | 진입 조건 | 다음 상태 | 근거 |
+|------|-----------|-----------|------|
+| pending | suite revision과 candidate·baseline이 고정됨 | running, cancelled | evaluation run |
+| running | evaluator step이 lease됨 | passed, failed, invalid, cancelled | metric result |
+| passed | 모든 required gate와 tolerance가 충족됨 | promotion_eligible | gate evaluation |
+| failed | required gate 또는 regression tolerance가 실패함 | pending | result evidence |
+| invalid | case·provider·metric 계약이 완전하지 않음 | pending | validation error |
+| promotion_eligible | passed 결과가 candidate에 연결됨 | promoted, expired | operator action |
+| promoted | 수동 alias transaction이 성공함 | rolled_back | audit event |
+| rolled_back | 이전 release가 다시 active가 됨 | 없음 | rollback event |
+
+## Interface Contract
+
+- 계약 원문: [초기 제어 상태 스키마](../../../../db/migrations/00001_initial.sql)
+- 입력:
+  - `suite_revision`: case, expectation과 evaluator version
+  - `candidate_release_id`, `baseline_release_id`: 비교 대상
+  - `metric_policy`: required metric, threshold, regression tolerance
+  - `actor`, `reason`: 수동 promotion·rollback 근거
+- 출력:
+  - case별 result, aggregate metrics와 pass·fail·invalid verdict
+  - candidate release와 evaluation evidence를 연결한 promotion decision 또는 차단 이유
+  - release alias mutation과 immutable audit chain
+- 금지:
+  - invalid 또는 failed evaluation을 promotion eligible로 만들지 않는다.
+  - actor·reason 없이 production alias를 변경하지 않는다.
+  - evaluation case·metric revision이 다른 결과를 같은 run으로 합치지 않는다.
+
+## Acceptance Scenarios
+
+| ID | Milestone Task | Given | When | Then |
+|----|----------------|-------|------|------|
+| S01 | `suite-versioning` | suite·case·evaluator 변경 | revision 생성 | 이전 run이 원래 revision을 계속 참조한다 |
+| S02 | `candidate-baseline` | candidate와 baseline release | evaluation run | 동일 case·metric 조건의 비교 결과와 두 불변 release 참조가 생성된다 |
+| S03 | `metric-gates` | required threshold와 regression tolerance | aggregate 계산 | 실패 metric이 promotion을 차단하고 이유가 남는다 |
+| S04 | `evaluation-state` | retry·cancel·invalid provider response | run 실행 | idempotent 상태 전이와 terminal verdict를 보존한다 |
+| S05 | `promotion-eligibility` | 모든 required gate pass·fail 후보 | eligibility 계산 | pass 후보만 eligible이 된다 |
+| S06 | `manual-promotion` | eligible candidate, evaluation evidence와 actor·reason | promotion 명령 | promotion decision이 release·evidence를 연결하고 alias 전환 audit가 남는다 |
+| S07 | `rollback-audit` | promoted release와 이전 release | rollback 명령 | 이전 release가 active가 되고 decision chain을 조회할 수 있다 |
+
+## Evidence Map
+
+| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
+|----------|-------------------|------------------|---------------------------|
+| S01 | suite revision immutability test | `agent-task/m-evaluation-and-promotion-gates/...` | `suite-versioning` revision evidence |
+| S02 | candidate-baseline deterministic run | `agent-task/m-evaluation-and-promotion-gates/...` | `candidate-baseline` comparison evidence |
+| S03 | threshold·regression metric matrix | `agent-task/m-evaluation-and-promotion-gates/...` | `metric-gates` block reason |
+| S04 | retry·cancel·invalid state test | `agent-task/m-evaluation-and-promotion-gates/...` | `evaluation-state` transition evidence |
+| S05 | eligibility positive·negative test | `agent-task/m-evaluation-and-promotion-gates/...` | `promotion-eligibility` verdict |
+| S06 | concurrent manual promotion transaction test | `agent-task/m-evaluation-and-promotion-gates/...` | `manual-promotion` actor·reason audit |
+| S07 | rollback integration test | `agent-task/m-evaluation-and-promotion-gates/...` | `rollback-audit` release chain |
+
+## Cross-repo Dependencies
+
+- 없음
+
+## Drift Check
+
+- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
+- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
+- [x] schema 원문은 링크로 참조하고 복제하지 않았다.
+- [x] 사용자 리뷰가 필요한 항목이 없다.
+
+## 사용자 리뷰 이력
+
+- 없음
+
+## 작업 컨텍스트
+
+- 표준선: immutable suite revision, same-condition baseline comparison, required gate, explicit promotion
+- 후속 SDD: 없음

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

@@ -0,0 +1,103 @@
+# SDD: Retrieval 정책 최적화
+
+## 위치
+
+- Milestone: [Milestone 문서](../../../phase/quality-governance/milestones/retrieval-policy-optimization.md)
+- Phase: [PHASE.md](../../../phase/quality-governance/PHASE.md)
+
+## 상태
+
+[승인됨]
+
+## SDD 잠금
+
+- 상태: 해제
+- 사용자 리뷰: 없음
+- 잠금 항목:
+  - 없음
+
+## 문제 / 비목표
+
+- 문제: retrieval과 evaluation 경로가 있어도 chunking·embedding·hybrid·rerank·query 변환 선택을 재현 가능한 정책 실험과 비용 제약으로 개선하는 루프가 없다.
+- 비목표:
+  - production 자동 승격
+  - 범용 AutoML 제품
+  - provider 내부 retrieval 알고리즘 구현
+
+## Source of Truth
+
+| 영역 | 기준 | 메모 |
+|------|------|------|
+| Roadmap | [Milestone 문서](../../../phase/quality-governance/milestones/retrieval-policy-optimization.md) | 정책 최적화 범위와 gate |
+| Evaluation | [평가와 승격 Gate SDD](../evaluation-and-promotion-gates/SDD.md) | suite, metric과 promotion evidence |
+| Serving | [Retrieve와 Answer Pipeline SDD](../../rag-serving/retrieval-and-answer-pipeline/SDD.md) | 실행 가능한 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
+
+- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
+- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
+- [x] evaluation과 release promotion 책임을 재사용한다.
+- [x] 사용자 리뷰가 필요한 항목이 없다.
+
+## 사용자 리뷰 이력
+
+- 없음
+
+## 작업 컨텍스트
+
+- 표준선: immutable experiment, capability-aware policy space, multi-objective gate, explicit promotion
+- 후속 SDD: [지속 갱신 Orchestration](../../workflow-automation/continuous-refresh-orchestration/SDD.md)

agent-roadmap/sdd/rag-serving/index-publication-and-release/SDD.md

@@ -0,0 +1,103 @@
+# SDD: Index 게시와 Release 수명주기
+
+## 위치
+
+- Milestone: [Milestone 문서](../../../phase/rag-serving/milestones/index-publication-and-release.md)
+- Phase: [PHASE.md](../../../phase/rag-serving/PHASE.md)
+
+## 상태
+
+[승인됨]
+
+## SDD 잠금
+
+- 상태: 해제
+- 사용자 리뷰: 없음
+- 잠금 항목:
+  - 없음
+
+## 문제 / 비목표
+
+- 문제: retrieval backend publish port와 release 테이블은 있으나 partial publish, external identity reconciliation, immutable release와 atomic alias 전환의 end-to-end 계약이 없다.
+- 비목표:
+  - backend 내부 index 포맷 통일
+  - mutable production index update
+  - 평가 결과만으로 자동 production 승격
+
+## Source of Truth
+
+| 영역 | 기준 | 메모 |
+|------|------|------|
+| Roadmap | [Milestone 문서](../../../phase/rag-serving/milestones/index-publication-and-release.md) | index·release 범위와 상태 원장 |
+| Code | [Retrieval backend port](../../../../packages/go/integration/ports.go) | publish·retrieve·retire 제품 중립 계약 |
+| External Provider | `PublishedIndex.external_id`와 `revision` | backend index identity |
+| User Decision | 없음 | candidate-before-active와 수동 승격 방향이 확정되어 있다 |
+
+## State Machine
+
+| 상태 | 진입 조건 | 다음 상태 | 근거 |
+|------|-----------|-----------|------|
+| candidate | dataset·policy snapshot과 index build가 생성됨 | active, failed, retired | release row |
+| active | 유효한 promotion decision과 수동 promotion transaction이 통과함 | retired | alias event |
+| failed | build·publish·reconciliation이 복구 불가로 실패함 | candidate, retired | workflow result |
+| retired | alias가 다른 release를 가리키고 참조가 종료됨 | 없음 | retire event |
+
+## Interface Contract
+
+- 계약 원문: [Retrieval backend port](../../../../packages/go/integration/ports.go)
+- 입력:
+  - `IndexPublication`: project, knowledge base, release, dataset URI·hash와 policy
+  - `release`: dataset version, index identity와 retrieval·generation policy로 구성된 불변 content
+  - `promotion_decision_id`: release와 외부 evaluation evidence를 연결한 승격 결정
+  - `alias`: knowledge base 범위의 production 등 논리 이름
+- 출력:
+  - `PublishedIndex`: backend external identity, revision과 metadata
+  - immutable release identity와 상태
+  - promotion·rollback audit event
+- 금지:
+  - publish가 확정되지 않은 index를 active alias에 연결하지 않는다.
+  - active release content와 policy를 in-place 변경하지 않는다.
+  - evaluation 결과나 promotion 상태 변경으로 release content를 수정하지 않는다.
+  - 하나의 knowledge base alias에 둘 이상의 active release를 허용하지 않는다.
+
+## Acceptance Scenarios
+
+| ID | Milestone Task | Given | When | Then |
+|----|----------------|-------|------|------|
+| S01 | `preflight` | dataset과 backend·embedding capability | candidate build 요청 | 호환되는 조합만 build를 시작한다 |
+| S02 | `candidate-build` | 불변 dataset과 policy | backend publish | external identity와 manifest가 candidate에 연결된다 |
+| S03 | `publish-reconcile` | publish timeout 또는 부분 응답 | reconciliation | 동일 idempotency로 중복 index 없이 상태를 확정한다 |
+| S04 | `release-snapshot` | dataset·index·policy snapshot | release 생성 | content가 변경 불가능한 version으로 저장된다 |
+| S05 | `alias-promotion` | 유효한 promotion decision과 active alias | 수동 promotion | transaction 후 alias가 정확히 한 release를 가리킨다 |
+| S06 | `rollback-retire` | 현재와 이전 active release | rollback·retire | 이전 release가 active가 되고 참조 없는 index만 retire된다 |
+
+## Evidence Map
+
+| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
+|----------|-------------------|------------------|---------------------------|
+| S01 | capability·policy preflight matrix | `agent-task/m-index-publication-and-release/...` | `preflight` accept·reject evidence |
+| S02 | candidate publish integration test | `agent-task/m-index-publication-and-release/...` | `candidate-build` manifest evidence |
+| S03 | timeout·duplicate fault injection | `agent-task/m-index-publication-and-release/...` | `publish-reconcile` idempotency evidence |
+| S04 | immutable release mutation negative test | `agent-task/m-index-publication-and-release/...` | `release-snapshot` immutability evidence |
+| S05 | concurrent promotion transaction test | `agent-task/m-index-publication-and-release/...` | `alias-promotion` single-active evidence |
+| S06 | rollback·retire backend smoke | `agent-task/m-index-publication-and-release/...` | `rollback-retire` rollback·GC evidence |
+
+## Cross-repo Dependencies
+
+- 없음
+
+## Drift Check
+
+- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
+- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
+- [x] retrieval backend 계약 원문은 port 링크로 참조했다.
+- [x] 사용자 리뷰가 필요한 항목이 없다.
+
+## 사용자 리뷰 이력
+
+- 없음
+
+## 작업 컨텍스트
+
+- 표준선: candidate-before-active, immutable release, external identity reconciliation, explicit promotion
+- 후속 SDD: [Retrieve와 Answer Pipeline](../retrieval-and-answer-pipeline/SDD.md), [평가와 승격 Gate](../../quality-governance/evaluation-and-promotion-gates/SDD.md)

agent-roadmap/sdd/rag-serving/retrieval-and-answer-pipeline/SDD.md

@@ -0,0 +1,106 @@
+# SDD: Retrieve와 Answer Pipeline
+
+## 위치
+
+- Milestone: [Milestone 문서](../../../phase/rag-serving/milestones/retrieval-and-answer-pipeline.md)
+- Phase: [PHASE.md](../../../phase/rag-serving/PHASE.md)
+
+## 상태
+
+[승인됨]
+
+## SDD 잠금
+
+- 상태: 해제
+- 사용자 리뷰: 없음
+- 잠금 항목:
+  - 없음
+
+## 문제 / 비목표
+
+- 문제: 공개 handler와 release resolver는 존재하지만 실제 integration pipeline, JSON·SSE parity, evidence·trace 보존과 provider failure mapping이 구현되지 않아 정상 요청도 의도적으로 unavailable 상태다.
+- 비목표:
+  - request 시점 index 작성과 promotion
+  - 특정 provider SDK의 공개 노출
+  - raw query·answer의 무기한 저장
+
+## Source of Truth
+
+| 영역 | 기준 | 메모 |
+|------|------|------|
+| Roadmap | [Milestone 문서](../../../phase/rag-serving/milestones/retrieval-and-answer-pipeline.md) | 온라인 pipeline 범위와 상태 원장 |
+| Code | [RAG OpenAPI](../../../../api/openapi/rara-v1.yaml) | 공개 HTTP·SSE 계약 |
+| External Provider | active release의 integration instance identity | retrieval·model 호출 대상 |
+| User Decision | 없음 | release identity와 evidence-first 응답 방향이 확정되어 있다 |
+
+## State Machine
+
+| 상태 | 진입 조건 | 다음 상태 | 근거 |
+|------|-----------|-----------|------|
+| received | 요청 JSON 검증이 시작됨 | resolved, failed | HTTP request |
+| resolved | active release와 policy가 해석됨 | retrieving, failed | release query |
+| retrieving | backend search가 실행됨 | reranking, generating, completed, failed | provider result |
+| reranking | candidate evidence가 재정렬됨 | generating, completed, failed | rerank result |
+| generating | answer provider와 SSE stream이 실행됨 | completed, failed | generation event |
+| completed | response와 expiry가 있는 trace가 확정됨 | 없음 | completed response |
+| failed | 공개 오류와 가능한 trace가 확정됨 | 없음 | error response |
+
+## Interface Contract
+
+- 계약 원문: [RAG OpenAPI](../../../../api/openapi/rara-v1.yaml)
+- 입력:
+  - `project_id`, `knowledge_base_id`, `release_alias`: release selector
+  - `query`, `top_k`, `filters`: retrieval 입력
+  - `stream`, `generation`: answer mode와 generation 설정
+- 출력:
+  - `trace_id`와 `release`: 요청과 versioned policy identity
+  - `evidence`: rank, score, content, citation과 metadata
+  - `answer`, `usage` 또는 SSE metadata·evidence·delta·completed·error
+- 금지:
+  - active가 아닌 release를 alias fallback으로 제공하지 않는다.
+  - JSON과 SSE에서 같은 실패를 상충하는 코드·의미로 반환하지 않는다.
+  - expiry 없는 RAG trace를 저장하지 않는다.
+
+## Acceptance Scenarios
+
+| ID | Milestone Task | Given | When | Then |
+|----|----------------|-------|------|------|
+| S01 | `release-resolution` | active·missing release selector | retrieve·answer 요청 | active identity를 반환하거나 stable not-found를 반환한다 |
+| S02 | `retrieval-policy` | versioned embedding·backend policy | retrieve 실행 | capability에 맞는 provider와 filter·top-k를 적용한다 |
+| S03 | `rerank-context` | retrieval candidates와 budget | rerank·assembly | stable evidence rank와 bounded context를 만든다 |
+| S04 | `generation` | evidence와 generation policy | non-stream answer | answer, evidence, release와 usage를 반환한다 |
+| S05 | `sse-contract` | streaming answer | provider delta·terminal event | metadata부터 completed 또는 error까지 순서 있게 전송한다 |
+| S06 | `trace-retention` | trace enabled·disabled와 raw retention policy | 요청 완료 | 필요한 identity는 남고 원문·expiry는 policy를 따른다 |
+| S07 | `provider-failures` | timeout·unavailable·partial stream·capability mismatch | provider 호출 | stable 공개 오류와 올바른 HTTP·SSE terminal을 반환한다 |
+
+## Evidence Map
+
+| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
+|----------|-------------------|------------------|---------------------------|
+| S01 | release resolver contract test | `agent-task/m-retrieval-and-answer-pipeline/...` | `release-resolution` active·not-found evidence |
+| S02 | fake embedding·retrieval provider matrix | `agent-task/m-retrieval-and-answer-pipeline/...` | `retrieval-policy` policy evidence |
+| S03 | rerank·context budget golden test | `agent-task/m-retrieval-and-answer-pipeline/...` | `rerank-context` evidence ordering |
+| S04 | non-stream HTTP contract test | `agent-task/m-retrieval-and-answer-pipeline/...` | `generation` response evidence |
+| S05 | SSE event sequence contract test | `agent-task/m-retrieval-and-answer-pipeline/...` | `sse-contract` terminal sequence |
+| S06 | retention·redaction DB test | `agent-task/m-retrieval-and-answer-pipeline/...` | `trace-retention` expiry evidence |
+| S07 | provider fault matrix와 HTTP smoke | `agent-task/m-retrieval-and-answer-pipeline/...` | `provider-failures` JSON·SSE parity |
+
+## Cross-repo Dependencies
+
+- 없음
+
+## Drift Check
+
+- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
+- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
+- [x] 공개 계약 원문은 OpenAPI 링크로 참조했다.
+- [x] 사용자 리뷰가 필요한 항목이 없다.
+
+## 사용자 리뷰 이력
+
+- 없음
+
+## 작업 컨텍스트
+
+- 표준선: active release read-only, evidence-first, provider-neutral pipeline, JSON/SSE semantic parity
+- 후속 SDD: [평가와 승격 Gate](../../quality-governance/evaluation-and-promotion-gates/SDD.md)

agent-roadmap/sdd/selective-adaptation/lora-qlora-execution/SDD.md

@@ -0,0 +1,97 @@
+# SDD: LoRA와 QLoRA 실행
+
+## 위치
+
+- Milestone: [Milestone 문서](../../../phase/selective-adaptation/milestones/lora-qlora-execution.md)
+- Phase: [PHASE.md](../../../phase/selective-adaptation/PHASE.md)
+
+## 상태
+
+[초안]
+
+## SDD 잠금
+
+- 상태: 잠금
+- 사용자 리뷰: [요청됨](USER_REVIEW.md)
+- 잠금 항목:
+  - [D01] 첫 지원 base model family와 배포 대상 우선순위
+
+## 문제 / 비목표
+
+- 문제: 검증된 training dataset에서 선택적으로 LoRA·QLoRA를 실행하려면 compute·framework capability, checkpoint·cancel, artifact identity와 평가 후 승격 계약이 필요하다.
+- 비목표:
+  - base model full fine-tuning
+  - 실시간 online learning
+  - GPU scheduler·model registry 제품 자체 구현
+
+## Source of Truth
+
+| 영역 | 기준 | 메모 |
+|------|------|------|
+| Roadmap | [Milestone 문서](../../../phase/selective-adaptation/milestones/lora-qlora-execution.md) | adaptation 범위와 선택적 실행 원칙 |
+| Dataset | [훈련 Dataset 정제 SDD](../training-dataset-curation/SDD.md) | 불변 training dataset release |
+| Runtime | [내구성 있는 Workflow Runtime SDD](../../workflow-automation/durable-workflow-runtime/SDD.md) | lease, checkpoint, cancel과 artifact |
+| User Decision | [USER_REVIEW.md](USER_REVIEW.md) | 첫 지원 model family와 배포 대상 |
+
+## State Machine
+
+| 상태 | 진입 조건 | 다음 상태 | 근거 |
+|------|-----------|-----------|------|
+| pending | dataset·recipe·capability preflight가 통과함 | running, rejected, cancelled | training job |
+| running | executor가 lease와 compute를 확보함 | checkpointed, evaluating, failed, cancelled | progress event |
+| checkpointed | 재개 가능한 checkpoint가 게시됨 | running, failed, cancelled | checkpoint manifest |
+| evaluating | 최종 adapter artifact가 생성됨 | promotable, rejected, failed | evaluation result |
+| promotable | required gate를 통과함 | promoted, expired | promotion decision |
+| promoted | 명시적 adapter alias 전환이 성공함 | rolled_back | audit event |
+| rolled_back | 이전 adapter가 다시 active가 됨 | 없음 | rollback event |
+
+## Interface Contract
+
+- 입력: base model identity, training dataset release, versioned recipe, seed, resource limit와 executor capability
+- 출력: progress·usage, checkpoint, adapter manifest, evaluation evidence와 promotion decision
+- 금지:
+  - capability preflight 실패 job을 실행하지 않는다.
+  - cancelled·failed job의 불완전 artifact를 promotable로 만들지 않는다.
+  - evaluation 없이 adapter alias를 변경하지 않는다.
+
+## Acceptance Scenarios
+
+| ID | Milestone Task | Given | When | Then |
+|----|----------------|-------|------|------|
+| S01 | `preflight-capability` | model·precision·quantization·memory 요구 | job 수락 | 호환 executor만 수락하고 불일치는 거부한다 |
+| S02 | `training-job` | dataset·recipe·seed | LoRA·QLoRA 실행 | progress·usage와 재현 identity가 남는다 |
+| S03 | `checkpoint-cancel` | 실행 중 checkpoint·cancel·failure | 상태 전이 | 안전한 terminal state와 재개 가능한 artifact가 구분된다 |
+| S04 | `adapter-manifest` | 학습 완료 adapter | manifest 생성 | base model·dataset·recipe·library·hash가 고정된다 |
+| S05 | `adaptation-evaluation` | baseline과 candidate adapter | 동일 suite 실행 | 비교 metric과 required gate가 생성된다 |
+| S06 | `adapter-promotion` | gate 통과·실패 adapter | promotion·rollback | 통과 후보만 명시적으로 승격하고 이전 버전으로 복구한다 |
+
+## Evidence Map
+
+| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
+|----------|-------------------|------------------|---------------------------|
+| S01 | executor capability matrix | `agent-task/m-lora-qlora-execution/...` | `preflight-capability` evidence |
+| S02 | deterministic small training smoke | `agent-task/m-lora-qlora-execution/...` | `training-job` artifact·usage |
+| S03 | checkpoint·cancel fault injection | `agent-task/m-lora-qlora-execution/...` | `checkpoint-cancel` transition evidence |
+| S04 | manifest schema·hash test | `agent-task/m-lora-qlora-execution/...` | `adapter-manifest` evidence |
+| S05 | baseline comparison run | `agent-task/m-lora-qlora-execution/...` | `adaptation-evaluation` metrics |
+| S06 | promotion·rollback integration test | `agent-task/m-lora-qlora-execution/...` | `adapter-promotion` audit |
+
+## Cross-repo Dependencies
+
+- 없음
+
+## Drift Check
+
+- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
+- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
+- [x] adaptation을 기본 RAG 경로와 분리했다.
+- [ ] 사용자 결정 [D01]이 해결되었다.
+
+## 사용자 리뷰 이력
+
+- [USER_REVIEW.md](USER_REVIEW.md) 요청 중
+
+## 작업 컨텍스트
+
+- 표준선: optional adaptation, capability preflight, immutable manifest, evaluation-before-promotion
+- Milestone은 `[스케치]`이며 [D01]과 승격 조건이 해소될 때까지 구현 잠금 상태를 유지한다.

agent-roadmap/sdd/selective-adaptation/lora-qlora-execution/USER_REVIEW.md

@@ -0,0 +1,37 @@
+# SDD User Review
+
+## 상태
+
+요청됨
+
+## 검토 대상
+
+- SDD: [SDD.md](SDD.md)
+- Milestone: [Milestone 문서](../../../phase/selective-adaptation/milestones/lora-qlora-execution.md)
+
+## 사용자 결정 항목
+
+### [D01] 첫 Adaptation 호환 범위
+
+- 결정 필요: 첫 지원 base model family와 실제 adapter 배포 대상을 무엇으로 둘지 결정해야 한다.
+- 추천안: 첫 운영 대상 로컬 모델 family 하나와 PEFT 호환 adapter 포맷 하나로 제한하고, 해당 adapter를 소비할 inference runtime을 같은 범위에 고정한다.
+- 대안: 여러 model family를 capability matrix로 동시에 지원한다.
+- 영향: Python dependency, GPU preflight, artifact manifest, evaluation·deployment compatibility와 MVP 일정이 달라진다.
+- 적용 위치:
+  - SDD: `Source of Truth`, `Interface Contract`
+  - Milestone: `승격 조건`, `구현 잠금`
+
+## 승인 항목
+
+- [ ] 위 결정 항목을 승인했다.
+- [ ] SDD 잠금 해제를 승인했다.
+
+## 답변 기록
+
+- 없음
+
+## 해결 조건
+
+- 모든 사용자 결정 항목의 답변이 SDD에 반영되어 있다.
+- `USER_REVIEW.md`가 `user_review_N.log`로 이동되어 있다.
+- 남은 잠금 항목이 없으면 SDD 상태가 `[승인됨]`이고 `SDD 잠금` 상태가 `해제`다.

agent-roadmap/sdd/selective-adaptation/training-dataset-curation/SDD.md

@@ -0,0 +1,96 @@
+# SDD: 훈련 Dataset 정제
+
+## 위치
+
+- Milestone: [Milestone 문서](../../../phase/selective-adaptation/milestones/training-dataset-curation.md)
+- Phase: [PHASE.md](../../../phase/selective-adaptation/PHASE.md)
+
+## 상태
+
+[승인됨]
+
+## SDD 잠금
+
+- 상태: 해제
+- 사용자 리뷰: 없음
+- 잠금 항목:
+  - 없음
+
+## 문제 / 비목표
+
+- 문제: feedback과 evaluation 사례를 provenance·privacy·contamination gate 없이 학습에 사용하지 않도록 candidate review와 불변 split release 계약이 필요하다.
+- 비목표:
+  - 운영 trace 전량 자동 사용
+  - evaluation·holdout 혼용
+  - 모델 학습 실행
+
+## Source of Truth
+
+| 영역 | 기준 | 메모 |
+|------|------|------|
+| Roadmap | [Milestone 문서](../../../phase/selective-adaptation/milestones/training-dataset-curation.md) | training candidate와 release 범위 |
+| Feedback | [Drift와 선별 Feedback SDD](../../quality-governance/drift-and-selective-feedback/SDD.md) | 선별 capture와 provenance |
+| Dataset | [수집과 Dataset 수명주기 SDD](../../knowledge-lifecycle/ingestion-and-dataset-lifecycle/SDD.md) | 불변 version과 lineage 원칙 |
+| User Decision | 없음 | provenance-first와 holdout 분리를 표준선으로 사용한다 |
+
+## State Machine
+
+| 상태 | 진입 조건 | 다음 상태 | 근거 |
+|------|-----------|-----------|------|
+| candidate | provenance와 policy verdict가 있는 사례가 들어옴 | accepted, rejected, quarantined | candidate row |
+| quarantined | consent·license·label 확인이 필요함 | accepted, rejected | review record |
+| accepted | privacy·license·quality precheck를 통과함 | released | acceptance event |
+| rejected | 기준을 통과하지 못함 | 없음 | reason code |
+| released | split·contamination gate와 content hash가 확정됨 | superseded | dataset release |
+| superseded | 더 최신 release가 게시됨 | 없음 | lineage |
+
+## Interface Contract
+
+- 입력: evaluation·feedback identity, source·teacher provenance, license·consent·retention과 label
+- 출력: review verdict, redacted candidate, deterministic split, quality report와 immutable training dataset release
+- 금지:
+  - provenance·consent가 불명확한 candidate를 accepted로 만들지 않는다.
+  - 같은 entity·source를 무작위로 나눠 split leakage를 만들지 않는다.
+  - evaluation holdout과 중복된 사례를 release에 포함하지 않는다.
+
+## Acceptance Scenarios
+
+| ID | Milestone Task | Given | When | Then |
+|----|----------------|-------|------|------|
+| S01 | `candidate-intake` | evaluation·feedback 사례 | intake | provenance와 policy verdict가 candidate에 고정된다 |
+| S02 | `candidate-review` | 유효·불명확·금지 사례 | review | accepted·quarantined·rejected와 이유가 남는다 |
+| S03 | `redaction-dedup` | accepted 후보 | 정제 | 민감 정보·중복·license 위반이 제거된다 |
+| S04 | `dataset-split` | 정제된 후보와 seed | split | entity·source leakage 없는 재현 가능한 split이 생성된다 |
+| S05 | `contamination-check` | split과 evaluation·holdout | 검사 | contamination과 label conflict가 release를 차단한다 |
+| S06 | `training-release` | 모든 gate 통과 split | 게시 | hash·recipe·statistics·provenance가 있는 불변 release가 생긴다 |
+
+## Evidence Map
+
+| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
+|----------|-------------------|------------------|---------------------------|
+| S01 | intake provenance contract test | `agent-task/m-training-dataset-curation/...` | `candidate-intake` evidence |
+| S02 | review state matrix | `agent-task/m-training-dataset-curation/...` | `candidate-review` verdict evidence |
+| S03 | redaction·dedup·license test | `agent-task/m-training-dataset-curation/...` | `redaction-dedup` evidence |
+| S04 | deterministic leakage-safe split test | `agent-task/m-training-dataset-curation/...` | `dataset-split` reproducibility |
+| S05 | contamination·conflict negative test | `agent-task/m-training-dataset-curation/...` | `contamination-check` block evidence |
+| S06 | immutable release reconstruction | `agent-task/m-training-dataset-curation/...` | `training-release` manifest |
+
+## Cross-repo Dependencies
+
+- 없음
+
+## Drift Check
+
+- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
+- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
+- [x] evaluation과 training holdout 경계를 분리했다.
+- [x] 사용자 리뷰가 필요한 항목이 없다.
+
+## 사용자 리뷰 이력
+
+- 없음
+
+## 작업 컨텍스트
+
+- 표준선: provenance-first, explicit review, deterministic split, contamination gate
+- Milestone은 `[스케치]`이므로 승격 조건이 모두 해소될 때까지 구현 잠금 상태를 유지한다.

agent-roadmap/sdd/workflow-automation/continuous-refresh-orchestration/SDD.md

@@ -0,0 +1,94 @@
+# 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은 `[스케치]`이므로 승격 조건이 모두 해소될 때까지 구현 잠금 상태를 유지한다.

agent-roadmap/sdd/workflow-automation/durable-workflow-runtime/SDD.md

@@ -0,0 +1,106 @@
+# SDD: 내구성 있는 Workflow Runtime
+
+## 위치
+
+- Milestone: [Milestone 문서](../../../phase/workflow-automation/milestones/durable-workflow-runtime.md)
+- Phase: [PHASE.md](../../../phase/workflow-automation/PHASE.md)
+
+## 상태
+
+[승인됨]
+
+## SDD 잠금
+
+- 상태: 해제
+- 사용자 리뷰: 없음
+- 잠금 항목:
+  - 없음
+
+## 문제 / 비목표
+
+- 문제: 현재 step queue는 기본 lease와 retry만 제공하며 heartbeat, parent 집계, crash recovery와 Go/Python executor 상호운용이 장시간 작업을 안전하게 닫을 수준으로 완성되지 않았다.
+- 비목표:
+  - 범용 DAG 편집기
+  - 외부 workflow 엔진의 전체 기능 복제
+  - RAG 평가와 release 승격 정책 소유
+
+## Source of Truth
+
+| 영역 | 기준 | 메모 |
+|------|------|------|
+| Roadmap | [Milestone 문서](../../../phase/workflow-automation/milestones/durable-workflow-runtime.md) | 상태와 완료 범위 원장 |
+| Code | [Executor Protobuf](../../../../api/proto/rara/v1/executor.proto) | Go/Python 실행 wire contract |
+| External Provider | 없음 | PostgreSQL과 executor가 내부 source of truth를 사용한다 |
+| User Decision | 없음 | at-least-once와 idempotent side effect 방향이 확정되어 있다 |
+
+## State Machine
+
+| 상태 | 진입 조건 | 다음 상태 | 근거 |
+|------|-----------|-----------|------|
+| pending | step이 생성되고 dependency가 충족됨 | leased, cancelled | queue row |
+| leased | worker가 만료 시간과 owner를 획득함 | running, retryable_failed, terminal_failed, cancelled | lease mutation |
+| running | owner가 실행 시작을 확정함 | succeeded, retryable_failed, terminal_failed, cancelled | progress event |
+| retryable_failed | 재시도 가능하고 attempt가 남음 | leased, cancelled | retry policy |
+| succeeded | 결과와 artifact가 영속화됨 | 없음 | terminal event |
+| terminal_failed | 재시도 불가 또는 attempt 소진 | 없음 | terminal event |
+| cancelled | 취소가 확정되고 executor가 종료됨 | 없음 | cancel event |
+
+## Interface Contract
+
+- 계약 원문: [Executor Protobuf](../../../../api/proto/rara/v1/executor.proto)
+- 입력:
+  - `workflow_run_id`, `step_run_id`, `idempotency_key`: 실행 identity
+  - `executor_kind`, `kind`, `attempt`, `deadline`: routing과 실행 제한
+  - `input`, `input_artifacts`: 불변 step 입력
+- 출력:
+  - `ProgressEvent`: sequence가 증가하는 accepted·running·progress·terminal event
+  - `JobResult`: output과 artifact manifest
+  - `JobError`: stable code, retryable과 details
+- 금지:
+  - 유효 lease owner가 아닌 worker가 상태나 결과를 갱신하지 않는다.
+  - terminal 상태에서 비terminal 상태로 되돌리지 않는다.
+  - job payload와 progress에 secret 원문을 넣지 않는다.
+
+## Acceptance Scenarios
+
+| ID | Milestone Task | Given | When | Then |
+|----|----------------|-------|------|------|
+| S01 | `run-state` | 여러 step을 가진 workflow run | step terminal 상태가 반영됨 | parent run이 허용된 집계 상태로만 전이한다 |
+| S02 | `lease-heartbeat` | 경쟁 worker와 짧은 lease | lease·heartbeat·expiry 실행 | 한 owner만 완료하고 만료 lease는 회수된다 |
+| S03 | `retry-idempotency` | retryable error와 동일 idempotency key | 재실행 | attempt와 backoff가 증가하고 side effect는 중복되지 않는다 |
+| S04 | `cancel-timeout` | leased·running Go/Python job | cancel 또는 deadline | executor와 DB 상태가 cancelled 또는 terminal failure로 닫힌다 |
+| S05 | `executor-routing` | capability가 다른 Go·Python executor | job routing | 호환 executor만 수락하고 나머지는 실행 전 거부한다 |
+| S06 | `progress-artifacts` | sequence event와 artifact 결과 | event 반영 | 순서·terminal·lineage가 영속 상태에 보존된다 |
+| S07 | `restart-smoke` | 실행 중 worker crash | lease expiry 뒤 worker restart | orphan step을 회수하고 완료·실패 결과가 유실되지 않는다 |
+
+## Evidence Map
+
+| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
+|----------|-------------------|------------------|---------------------------|
+| S01 | run·step state transition test | `agent-task/m-durable-workflow-runtime/...` | `run-state` transition matrix |
+| S02 | concurrent lease와 heartbeat integration test | `agent-task/m-durable-workflow-runtime/...` | `lease-heartbeat` single-owner evidence |
+| S03 | retry·idempotency fault injection | `agent-task/m-durable-workflow-runtime/...` | `retry-idempotency` no-duplicate evidence |
+| S04 | Go·Python cancel·deadline smoke | `agent-task/m-durable-workflow-runtime/...` | `cancel-timeout` terminal evidence |
+| S05 | capability routing matrix | `agent-task/m-durable-workflow-runtime/...` | `executor-routing` accept·reject evidence |
+| S06 | progress ordering과 artifact lineage test | `agent-task/m-durable-workflow-runtime/...` | `progress-artifacts` persistence evidence |
+| S07 | PostgreSQL·worker restart field smoke | `agent-task/m-durable-workflow-runtime/...` | `restart-smoke` recovery evidence |
+
+## Cross-repo Dependencies
+
+- 없음
+
+## Drift Check
+
+- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
+- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
+- [x] executor 계약 원문은 Protobuf 링크로 참조했다.
+- [x] 사용자 리뷰가 필요한 항목이 없다.
+
+## 사용자 리뷰 이력
+
+- 없음
+
+## 작업 컨텍스트
+
+- 표준선: PostgreSQL lease queue, at-least-once execution, idempotent side effects, terminal progress event
+- 후속 SDD: [수집과 Dataset 수명주기](../../knowledge-lifecycle/ingestion-and-dataset-lifecycle/SDD.md)