From d4546ecbfdd0e166b8c634092c0d7c5009618cea Mon Sep 17 00:00:00 2001 From: toki Date: Sat, 18 Jul 2026 19:31:48 +0900 Subject: [PATCH] add agent-roadmap --- agent-roadmap/ROADMAP.md | 58 ++++++++++ .../phase/knowledge-lifecycle/PHASE.md | 23 ++++ .../ingestion-and-dataset-lifecycle.md | 78 +++++++++++++ .../phase/operations-productization/PHASE.md | 29 +++++ .../multi-project-security-and-audit.md | 88 ++++++++++++++ .../milestones/operations-ui.md | 79 +++++++++++++ .../milestones/production-reliability.md | 85 ++++++++++++++ .../phase/platform-foundation/PHASE.md | 30 +++++ .../milestones/control-plane-resource-api.md | 76 ++++++++++++ .../integration-catalog-and-secrets.md | 76 ++++++++++++ .../milestones/platform-scaffold-baseline.md | 66 +++++++++++ .../phase/quality-governance/PHASE.md | 30 +++++ .../drift-and-selective-feedback.md | 85 ++++++++++++++ .../evaluation-and-promotion-gates.md | 78 +++++++++++++ .../retrieval-policy-optimization.md | 76 ++++++++++++ agent-roadmap/phase/rag-serving/PHASE.md | 26 +++++ .../index-publication-and-release.md | 77 +++++++++++++ .../retrieval-and-answer-pipeline.md | 78 +++++++++++++ .../phase/selective-adaptation/PHASE.md | 26 +++++ .../milestones/lora-qlora-execution.md | 86 ++++++++++++++ .../milestones/training-dataset-curation.md | 85 ++++++++++++++ .../phase/workflow-automation/PHASE.md | 26 +++++ .../continuous-refresh-orchestration.md | 79 +++++++++++++ .../milestones/durable-workflow-runtime.md | 78 +++++++++++++ agent-roadmap/priority-queue.md | 38 ++++++ .../ingestion-and-dataset-lifecycle/SDD.md | 104 +++++++++++++++++ .../multi-project-security-and-audit/SDD.md | 94 +++++++++++++++ .../USER_REVIEW.md | 37 ++++++ .../operations-ui/SDD.md | 85 ++++++++++++++ .../operations-ui/USER_REVIEW.md | 37 ++++++ .../production-reliability/SDD.md | 94 +++++++++++++++ .../production-reliability/USER_REVIEW.md | 37 ++++++ .../control-plane-resource-api/SDD.md | 103 +++++++++++++++++ .../integration-catalog-and-secrets/SDD.md | 103 +++++++++++++++++ .../drift-and-selective-feedback/SDD.md | 96 ++++++++++++++++ .../evaluation-and-promotion-gates/SDD.md | 108 ++++++++++++++++++ .../retrieval-policy-optimization/SDD.md | 103 +++++++++++++++++ .../index-publication-and-release/SDD.md | 103 +++++++++++++++++ .../retrieval-and-answer-pipeline/SDD.md | 106 +++++++++++++++++ .../lora-qlora-execution/SDD.md | 97 ++++++++++++++++ .../lora-qlora-execution/USER_REVIEW.md | 37 ++++++ .../training-dataset-curation/SDD.md | 96 ++++++++++++++++ .../continuous-refresh-orchestration/SDD.md | 94 +++++++++++++++ .../durable-workflow-runtime/SDD.md | 106 +++++++++++++++++ 44 files changed, 3196 insertions(+) create mode 100644 agent-roadmap/ROADMAP.md create mode 100644 agent-roadmap/phase/knowledge-lifecycle/PHASE.md create mode 100644 agent-roadmap/phase/knowledge-lifecycle/milestones/ingestion-and-dataset-lifecycle.md create mode 100644 agent-roadmap/phase/operations-productization/PHASE.md create mode 100644 agent-roadmap/phase/operations-productization/milestones/multi-project-security-and-audit.md create mode 100644 agent-roadmap/phase/operations-productization/milestones/operations-ui.md create mode 100644 agent-roadmap/phase/operations-productization/milestones/production-reliability.md create mode 100644 agent-roadmap/phase/platform-foundation/PHASE.md create mode 100644 agent-roadmap/phase/platform-foundation/milestones/control-plane-resource-api.md create mode 100644 agent-roadmap/phase/platform-foundation/milestones/integration-catalog-and-secrets.md create mode 100644 agent-roadmap/phase/platform-foundation/milestones/platform-scaffold-baseline.md create mode 100644 agent-roadmap/phase/quality-governance/PHASE.md create mode 100644 agent-roadmap/phase/quality-governance/milestones/drift-and-selective-feedback.md create mode 100644 agent-roadmap/phase/quality-governance/milestones/evaluation-and-promotion-gates.md create mode 100644 agent-roadmap/phase/quality-governance/milestones/retrieval-policy-optimization.md create mode 100644 agent-roadmap/phase/rag-serving/PHASE.md create mode 100644 agent-roadmap/phase/rag-serving/milestones/index-publication-and-release.md create mode 100644 agent-roadmap/phase/rag-serving/milestones/retrieval-and-answer-pipeline.md create mode 100644 agent-roadmap/phase/selective-adaptation/PHASE.md create mode 100644 agent-roadmap/phase/selective-adaptation/milestones/lora-qlora-execution.md create mode 100644 agent-roadmap/phase/selective-adaptation/milestones/training-dataset-curation.md create mode 100644 agent-roadmap/phase/workflow-automation/PHASE.md create mode 100644 agent-roadmap/phase/workflow-automation/milestones/continuous-refresh-orchestration.md create mode 100644 agent-roadmap/phase/workflow-automation/milestones/durable-workflow-runtime.md create mode 100644 agent-roadmap/priority-queue.md create mode 100644 agent-roadmap/sdd/knowledge-lifecycle/ingestion-and-dataset-lifecycle/SDD.md create mode 100644 agent-roadmap/sdd/operations-productization/multi-project-security-and-audit/SDD.md create mode 100644 agent-roadmap/sdd/operations-productization/multi-project-security-and-audit/USER_REVIEW.md create mode 100644 agent-roadmap/sdd/operations-productization/operations-ui/SDD.md create mode 100644 agent-roadmap/sdd/operations-productization/operations-ui/USER_REVIEW.md create mode 100644 agent-roadmap/sdd/operations-productization/production-reliability/SDD.md create mode 100644 agent-roadmap/sdd/operations-productization/production-reliability/USER_REVIEW.md create mode 100644 agent-roadmap/sdd/platform-foundation/control-plane-resource-api/SDD.md create mode 100644 agent-roadmap/sdd/platform-foundation/integration-catalog-and-secrets/SDD.md create mode 100644 agent-roadmap/sdd/quality-governance/drift-and-selective-feedback/SDD.md create mode 100644 agent-roadmap/sdd/quality-governance/evaluation-and-promotion-gates/SDD.md create mode 100644 agent-roadmap/sdd/quality-governance/retrieval-policy-optimization/SDD.md create mode 100644 agent-roadmap/sdd/rag-serving/index-publication-and-release/SDD.md create mode 100644 agent-roadmap/sdd/rag-serving/retrieval-and-answer-pipeline/SDD.md create mode 100644 agent-roadmap/sdd/selective-adaptation/lora-qlora-execution/SDD.md create mode 100644 agent-roadmap/sdd/selective-adaptation/lora-qlora-execution/USER_REVIEW.md create mode 100644 agent-roadmap/sdd/selective-adaptation/training-dataset-curation/SDD.md create mode 100644 agent-roadmap/sdd/workflow-automation/continuous-refresh-orchestration/SDD.md create mode 100644 agent-roadmap/sdd/workflow-automation/durable-workflow-runtime/SDD.md diff --git a/agent-roadmap/ROADMAP.md b/agent-roadmap/ROADMAP.md new file mode 100644 index 0000000..b797672 --- /dev/null +++ b/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 잠금이 해제되었으며 사용자 리뷰가 없어야 구현 계획을 만들 수 있다. diff --git a/agent-roadmap/phase/knowledge-lifecycle/PHASE.md b/agent-roadmap/phase/knowledge-lifecycle/PHASE.md new file mode 100644 index 0000000..20a1ad7 --- /dev/null +++ b/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로 덮어쓰지 않는다. diff --git a/agent-roadmap/phase/knowledge-lifecycle/milestones/ingestion-and-dataset-lifecycle.md b/agent-roadmap/phase/knowledge-lifecycle/milestones/ingestion-and-dataset-lifecycle.md new file mode 100644 index 0000000..1078308 --- /dev/null +++ b/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) +- 확인 필요: 없음 diff --git a/agent-roadmap/phase/operations-productization/PHASE.md b/agent-roadmap/phase/operations-productization/PHASE.md new file mode 100644 index 0000000..3c744a7 --- /dev/null +++ b/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 자체 구현으로 고정하지 않는다. diff --git a/agent-roadmap/phase/operations-productization/milestones/multi-project-security-and-audit.md b/agent-roadmap/phase/operations-productization/milestones/multi-project-security-and-audit.md new file mode 100644 index 0000000..155a470 --- /dev/null +++ b/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) +- 확인 필요: `구현 잠금 > 결정 필요` diff --git a/agent-roadmap/phase/operations-productization/milestones/operations-ui.md b/agent-roadmap/phase/operations-productization/milestones/operations-ui.md new file mode 100644 index 0000000..538b96a --- /dev/null +++ b/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) +- 확인 필요: `구현 잠금 > 결정 필요` diff --git a/agent-roadmap/phase/operations-productization/milestones/production-reliability.md b/agent-roadmap/phase/operations-productization/milestones/production-reliability.md new file mode 100644 index 0000000..439ce08 --- /dev/null +++ b/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) +- 후속 작업: 없음 +- 확인 필요: `구현 잠금 > 결정 필요` diff --git a/agent-roadmap/phase/platform-foundation/PHASE.md b/agent-roadmap/phase/platform-foundation/PHASE.md new file mode 100644 index 0000000..ef6a3aa --- /dev/null +++ b/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를 필수 경계로 사용하며 교차 프로젝트 접근을 기본 거부한다. diff --git a/agent-roadmap/phase/platform-foundation/milestones/control-plane-resource-api.md b/agent-roadmap/phase/platform-foundation/milestones/control-plane-resource-api.md new file mode 100644 index 0000000..8d5109e --- /dev/null +++ b/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) +- 확인 필요: 없음 diff --git a/agent-roadmap/phase/platform-foundation/milestones/integration-catalog-and-secrets.md b/agent-roadmap/phase/platform-foundation/milestones/integration-catalog-and-secrets.md new file mode 100644 index 0000000..6f43167 --- /dev/null +++ b/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) +- 확인 필요: 없음 diff --git a/agent-roadmap/phase/platform-foundation/milestones/platform-scaffold-baseline.md b/agent-roadmap/phase/platform-foundation/milestones/platform-scaffold-baseline.md new file mode 100644 index 0000000..311c32b --- /dev/null +++ b/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 환경 diff --git a/agent-roadmap/phase/quality-governance/PHASE.md b/agent-roadmap/phase/quality-governance/PHASE.md new file mode 100644 index 0000000..62069eb --- /dev/null +++ b/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의 보존 기간·민감 데이터 정책을 분리한다. diff --git a/agent-roadmap/phase/quality-governance/milestones/drift-and-selective-feedback.md b/agent-roadmap/phase/quality-governance/milestones/drift-and-selective-feedback.md new file mode 100644 index 0000000..d894a56 --- /dev/null +++ b/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) +- 확인 필요: 없음 diff --git a/agent-roadmap/phase/quality-governance/milestones/evaluation-and-promotion-gates.md b/agent-roadmap/phase/quality-governance/milestones/evaluation-and-promotion-gates.md new file mode 100644 index 0000000..9490ec0 --- /dev/null +++ b/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) +- 확인 필요: 없음 diff --git a/agent-roadmap/phase/quality-governance/milestones/retrieval-policy-optimization.md b/agent-roadmap/phase/quality-governance/milestones/retrieval-policy-optimization.md new file mode 100644 index 0000000..d7ce9d8 --- /dev/null +++ b/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) +- 확인 필요: 없음 diff --git a/agent-roadmap/phase/rag-serving/PHASE.md b/agent-roadmap/phase/rag-serving/PHASE.md new file mode 100644 index 0000000..30c95ab --- /dev/null +++ b/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만 읽는다. diff --git a/agent-roadmap/phase/rag-serving/milestones/index-publication-and-release.md b/agent-roadmap/phase/rag-serving/milestones/index-publication-and-release.md new file mode 100644 index 0000000..eb62093 --- /dev/null +++ b/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) +- 확인 필요: 없음 diff --git a/agent-roadmap/phase/rag-serving/milestones/retrieval-and-answer-pipeline.md b/agent-roadmap/phase/rag-serving/milestones/retrieval-and-answer-pipeline.md new file mode 100644 index 0000000..e3d6e3b --- /dev/null +++ b/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) +- 확인 필요: 없음 diff --git a/agent-roadmap/phase/selective-adaptation/PHASE.md b/agent-roadmap/phase/selective-adaptation/PHASE.md new file mode 100644 index 0000000..c1d0958 --- /dev/null +++ b/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 환경을 제어 플레인 핵심 상태 모델에 하드코딩하지 않는다. diff --git a/agent-roadmap/phase/selective-adaptation/milestones/lora-qlora-execution.md b/agent-roadmap/phase/selective-adaptation/milestones/lora-qlora-execution.md new file mode 100644 index 0000000..c9c89ab --- /dev/null +++ b/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) +- 후속 작업: 없음 +- 확인 필요: `구현 잠금 > 결정 필요` diff --git a/agent-roadmap/phase/selective-adaptation/milestones/training-dataset-curation.md b/agent-roadmap/phase/selective-adaptation/milestones/training-dataset-curation.md new file mode 100644 index 0000000..5d95e2b --- /dev/null +++ b/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) +- 확인 필요: 없음 diff --git a/agent-roadmap/phase/workflow-automation/PHASE.md b/agent-roadmap/phase/workflow-automation/PHASE.md new file mode 100644 index 0000000..0e59fcc --- /dev/null +++ b/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 경로로 우회하지 않는다. diff --git a/agent-roadmap/phase/workflow-automation/milestones/continuous-refresh-orchestration.md b/agent-roadmap/phase/workflow-automation/milestones/continuous-refresh-orchestration.md new file mode 100644 index 0000000..999560e --- /dev/null +++ b/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) +- 확인 필요: 없음 diff --git a/agent-roadmap/phase/workflow-automation/milestones/durable-workflow-runtime.md b/agent-roadmap/phase/workflow-automation/milestones/durable-workflow-runtime.md new file mode 100644 index 0000000..0769499 --- /dev/null +++ b/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) +- 확인 필요: 없음 diff --git a/agent-roadmap/priority-queue.md b/agent-roadmap/priority-queue.md new file mode 100644 index 0000000..e37a8ad --- /dev/null +++ b/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와 장애 검증 경계를 설계한다. diff --git a/agent-roadmap/sdd/knowledge-lifecycle/ingestion-and-dataset-lifecycle/SDD.md b/agent-roadmap/sdd/knowledge-lifecycle/ingestion-and-dataset-lifecycle/SDD.md new file mode 100644 index 0000000..30ad98a --- /dev/null +++ b/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) diff --git a/agent-roadmap/sdd/operations-productization/multi-project-security-and-audit/SDD.md b/agent-roadmap/sdd/operations-productization/multi-project-security-and-audit/SDD.md new file mode 100644 index 0000000..777cd6f --- /dev/null +++ b/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]과 승격 조건이 해소될 때까지 구현 잠금 상태를 유지한다. diff --git a/agent-roadmap/sdd/operations-productization/multi-project-security-and-audit/USER_REVIEW.md b/agent-roadmap/sdd/operations-productization/multi-project-security-and-audit/USER_REVIEW.md new file mode 100644 index 0000000..bdbd194 --- /dev/null +++ b/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 잠금` 상태가 `해제`다. diff --git a/agent-roadmap/sdd/operations-productization/operations-ui/SDD.md b/agent-roadmap/sdd/operations-productization/operations-ui/SDD.md new file mode 100644 index 0000000..6e9d90b --- /dev/null +++ b/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]과 승격 조건이 해소될 때까지 구현 잠금 상태를 유지한다. diff --git a/agent-roadmap/sdd/operations-productization/operations-ui/USER_REVIEW.md b/agent-roadmap/sdd/operations-productization/operations-ui/USER_REVIEW.md new file mode 100644 index 0000000..79adc67 --- /dev/null +++ b/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 잠금` 상태가 `해제`다. diff --git a/agent-roadmap/sdd/operations-productization/production-reliability/SDD.md b/agent-roadmap/sdd/operations-productization/production-reliability/SDD.md new file mode 100644 index 0000000..c74212d --- /dev/null +++ b/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]과 승격 조건이 해소될 때까지 구현 잠금 상태를 유지한다. diff --git a/agent-roadmap/sdd/operations-productization/production-reliability/USER_REVIEW.md b/agent-roadmap/sdd/operations-productization/production-reliability/USER_REVIEW.md new file mode 100644 index 0000000..17b1f90 --- /dev/null +++ b/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 잠금` 상태가 `해제`다. diff --git a/agent-roadmap/sdd/platform-foundation/control-plane-resource-api/SDD.md b/agent-roadmap/sdd/platform-foundation/control-plane-resource-api/SDD.md new file mode 100644 index 0000000..049e359 --- /dev/null +++ b/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) diff --git a/agent-roadmap/sdd/platform-foundation/integration-catalog-and-secrets/SDD.md b/agent-roadmap/sdd/platform-foundation/integration-catalog-and-secrets/SDD.md new file mode 100644 index 0000000..7a8f5cd --- /dev/null +++ b/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) diff --git a/agent-roadmap/sdd/quality-governance/drift-and-selective-feedback/SDD.md b/agent-roadmap/sdd/quality-governance/drift-and-selective-feedback/SDD.md new file mode 100644 index 0000000..0634517 --- /dev/null +++ b/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은 `[스케치]`이므로 승격 조건이 모두 해소될 때까지 구현 잠금 상태를 유지한다. diff --git a/agent-roadmap/sdd/quality-governance/evaluation-and-promotion-gates/SDD.md b/agent-roadmap/sdd/quality-governance/evaluation-and-promotion-gates/SDD.md new file mode 100644 index 0000000..3035011 --- /dev/null +++ b/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: 없음 diff --git a/agent-roadmap/sdd/quality-governance/retrieval-policy-optimization/SDD.md b/agent-roadmap/sdd/quality-governance/retrieval-policy-optimization/SDD.md new file mode 100644 index 0000000..8d92a37 --- /dev/null +++ b/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) diff --git a/agent-roadmap/sdd/rag-serving/index-publication-and-release/SDD.md b/agent-roadmap/sdd/rag-serving/index-publication-and-release/SDD.md new file mode 100644 index 0000000..dc986ee --- /dev/null +++ b/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) diff --git a/agent-roadmap/sdd/rag-serving/retrieval-and-answer-pipeline/SDD.md b/agent-roadmap/sdd/rag-serving/retrieval-and-answer-pipeline/SDD.md new file mode 100644 index 0000000..e1f90e1 --- /dev/null +++ b/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) diff --git a/agent-roadmap/sdd/selective-adaptation/lora-qlora-execution/SDD.md b/agent-roadmap/sdd/selective-adaptation/lora-qlora-execution/SDD.md new file mode 100644 index 0000000..697972f --- /dev/null +++ b/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]과 승격 조건이 해소될 때까지 구현 잠금 상태를 유지한다. diff --git a/agent-roadmap/sdd/selective-adaptation/lora-qlora-execution/USER_REVIEW.md b/agent-roadmap/sdd/selective-adaptation/lora-qlora-execution/USER_REVIEW.md new file mode 100644 index 0000000..2de34a7 --- /dev/null +++ b/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 잠금` 상태가 `해제`다. diff --git a/agent-roadmap/sdd/selective-adaptation/training-dataset-curation/SDD.md b/agent-roadmap/sdd/selective-adaptation/training-dataset-curation/SDD.md new file mode 100644 index 0000000..a5c7ea3 --- /dev/null +++ b/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은 `[스케치]`이므로 승격 조건이 모두 해소될 때까지 구현 잠금 상태를 유지한다. diff --git a/agent-roadmap/sdd/workflow-automation/continuous-refresh-orchestration/SDD.md b/agent-roadmap/sdd/workflow-automation/continuous-refresh-orchestration/SDD.md new file mode 100644 index 0000000..da64636 --- /dev/null +++ b/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은 `[스케치]`이므로 승격 조건이 모두 해소될 때까지 구현 잠금 상태를 유지한다. diff --git a/agent-roadmap/sdd/workflow-automation/durable-workflow-runtime/SDD.md b/agent-roadmap/sdd/workflow-automation/durable-workflow-runtime/SDD.md new file mode 100644 index 0000000..5a83c1b --- /dev/null +++ b/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)