102 lines
6.9 KiB
Markdown
102 lines
6.9 KiB
Markdown
# Milestone: [route-02] Heavy Plan/Review 실행과 검증 MVP
|
|
|
|
## 위치
|
|
|
|
- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
|
|
- Phase: [PHASE.md](../PHASE.md)
|
|
|
|
## 목표
|
|
|
|
[`IOP 실행 프리셋과 Hot Path`](iop-hot-path-one-shot-execution.md)가 구현한 preset/coordinator와 lightweight Plan/Review를 장기·고난도 작업용 `heavy` execution mode로 확장한다.
|
|
`heavy`는 별도 제품이나 고정 model 조합이 아니라 execution preset이 선택적으로 포함할 수 있는 mode handler다. preset마다 planner, worker, reviewer와 repair model/options를 다르게 배치할 수 있다. 이 마일스톤에서는 `heavy-only` preset으로 lifecycle을 먼저 검증하고, `direct/light/heavy` 혼합 선택은 후속 route-03에서 연결한다.
|
|
이 마일스톤은 Plan/Review 갱신, 검증, 여러 work/review 전이와 중단·재개가 필요한 작업을 IOP의 하나의 논리 `request_id` 수명으로 다루되 target agent나 외부 workflow 제품의 adapter, process 또는 state를 공유하지 않는다.
|
|
|
|
## 상태
|
|
|
|
[스케치]
|
|
|
|
## 선행 작업
|
|
|
|
- [`IOP 실행 프리셋과 Hot Path`](iop-hot-path-one-shot-execution.md)
|
|
|
|
## 승격 조건
|
|
|
|
- [ ] `light`에서 `heavy`로 구분되는 작업 규모·위험·검증 요구와 mode 선택 기준을 확정한다.
|
|
- [ ] heavy plan의 갱신 단위, review 기록, work/review/repair 전이와 완료 판정을 확정한다.
|
|
- [ ] 여러 agent tool turn, process restart와 중단 후 재개에 필요한 state/artifact 최소 범위를 확정한다.
|
|
- [ ] 검증 실패 시 재계획·수정·재검토의 budget, timeout, cancel과 표준 오류 경계를 확정한다.
|
|
- [ ] Claude/Pi 이후 endpoint 확장과 workspace capability admission 범위를 확정한다.
|
|
- [ ] API/config/event/artifact lifecycle 구현 전 필수 SDD를 작성·승인한다.
|
|
|
|
## 구현 잠금
|
|
|
|
- 상태: 잠금
|
|
- SDD: 불필요
|
|
- SDD 문서: 없음
|
|
- SDD 사유: 현재는 `heavy` mode의 책임과 `light`와의 경계를 정리한 후속 스케치다. 장기 state, artifact 갱신, retry/review와 resume 계약을 구현하기 전에 필수 SDD가 필요하다.
|
|
- 잠금 해제 조건: 아래 체크리스트
|
|
- [ ] 승격 조건의 lifecycle·artifact·budget·resume 결정이 모두 해소되어 있다.
|
|
- [ ] 현재 Hot Path에 추가할 부분과 공통 coordinator를 변경할 부분이 분리되어 있다.
|
|
- [ ] 구현 가능한 첫 heavy profile과 후속 확장 범위가 분리되어 있다.
|
|
- [ ] 필요한 SDD가 작성·승인되어 있다.
|
|
- 결정 필요: `승격 조건`과 동일
|
|
|
|
## 범위
|
|
|
|
### 1. Heavy mode contract
|
|
|
|
- `heavy`는 preset `allowed_modes`와 registered handler로 추가하며 외부 model에 별도 하드코딩하지 않는다.
|
|
- preset stage binding은 기존 canonical model/provider resolution을 사용하고 planner/worker/reviewer/repair 역할의 model과 옵션을 operator가 구성한다.
|
|
- 이 마일스톤의 실행 검증은 `allowed_modes=[heavy]`인 unambiguous preset에서 fused selector/planner가 heavy plan을 작성하는 경로로 한정한다. selector가 `light/heavy` 난이도를 비교하거나 mixed mode를 고르는 계약은 도입하지 않는다.
|
|
- schema는 후속 `plan-only(light/heavy)`, balanced와 custom 조합을 막지 않지만, 둘 이상의 실행 가능한 mode 중 semantic selection을 요구하는 preset은 route-03 handler가 생기기 전 fail-closed한다.
|
|
|
|
### 2. Plan/Review lifecycle
|
|
|
|
- 기본 workspace root와 identity는 `.iop/job/<request_id>/`와 `request_id`를 그대로 재사용한다.
|
|
- route-01의 `plan.md`/`review.md` pair를 최소 기반으로 삼고, 실제 필요가 확정될 때만 추가 파일·revision·checkpoint를 설계한다.
|
|
- plan 갱신, work progress, review defect와 repair 결과는 agent의 기존 tool call로 workspace에 반영한다. IOP는 stage와 terminal을 조정하지만 workspace를 직접 소유하지 않는다.
|
|
- long-running tool round-trip과 재연결에서도 동일 request identity, idempotency와 exactly-once final을 유지한다.
|
|
|
|
### 3. 검증과 회귀
|
|
|
|
- plan의 목표·제약·검증 기준과 실제 결과를 reviewer가 비교하고 pass, repair, replan 또는 terminal error를 결정한다.
|
|
- model 판단은 Edge가 검증하는 advisory이며 preset 밖 target/mode, 임의 path와 capability를 실행 권한으로 사용하지 않는다.
|
|
- review/replan/repair는 합의된 request budget 안에서만 반복하며 한도 초과는 별도 성공 상태가 아니라 표준 timeout/execution error다.
|
|
- routing, plan 갱신, work, review, defect, replan과 repair 출력은 사용자에게 endpoint-native stream으로 모두 보인다.
|
|
|
|
## 기능
|
|
|
|
### Epic: [heavy-lifecycle] Heavy Plan/Review Lifecycle
|
|
|
|
- [ ] [heavy-handler] preset registry에 `heavy` handler와 stage role contract를 추가하고 `heavy-only` preset에서 model/options를 바인딩·검증한다.
|
|
- [ ] [plan-lifecycle] plan 생성·갱신·검증 기준과 최소 artifact evolution을 정의한다.
|
|
- [ ] [review-cycle] reviewer verdict에 따른 repair, replan, re-review와 완료 state machine을 정의한다.
|
|
- [ ] [resume-state] 여러 tool turn, reconnect/restart의 correlation, idempotency와 cleanup 경계를 정의한다.
|
|
- [ ] [heavy-review] 대표 장기 작업에서 `light` 대비 mode 경계, 품질·지연·비용과 오류 처리를 사용자 검토 가능한 evidence로 남긴다.
|
|
|
|
## 완료 리뷰
|
|
|
|
- 상태: 없음
|
|
- 요청일: 없음
|
|
- 완료 근거: 후속 `heavy` 방향 스케치이며 승격 조건, SDD와 기능 Task가 아직 충족되지 않았다.
|
|
- 검토 항목: 없음
|
|
- 리뷰 코멘트: 없음
|
|
|
|
## 범위 제외
|
|
|
|
- execution preset과 무관한 별도 heavyweight 제품/API
|
|
- target agent나 외부 workflow 제품의 process/state/contract, terminal/PTY 또는 agent별 adapter와의 runtime 연결
|
|
- 모든 미래 mode를 미리 수용하는 범용 DAG/plugin engine
|
|
- 하이브리드 mode selector의 production evidence 정책과 RAG local router 운영
|
|
- `direct/light/heavy` 혼합 preset의 난이도 기반 mode 선택
|
|
- repository 장기 기억 RAG와 누적 대화 context 최적화
|
|
|
|
## 작업 컨텍스트
|
|
|
|
- 관련 경로: `apps/edge/internal/openai`, `apps/edge/internal/service`, `packages/go/config`, `packages/go/streamgate`
|
|
- 선행 SDD: [IOP 실행 프리셋과 Hot Path SDD](../../../sdd/knowledge-tool-optimization-extension/iop-hot-path-one-shot-execution/SDD.md)
|
|
- 표준선(선택): `light`의 request coordinator, endpoint-native tool call, visible stage stream와 표준 오류 계약을 깨지 않고 `heavy` state만 확장한다.
|
|
- 표준선(선택): artifact 구조는 필요가 확정된 시점에만 확장하며 route-01에 manifest/revision/empty directory를 선반영하지 않는다.
|
|
- 후속 작업: [Execution Preset 하이브리드 Mode 라우팅](openai-compatible-hybrid-request-execution-routing.md), [RAG 기반 Local Routing Model 운영 전환](rag-local-routing-model-operations.md)
|
|
- 큐 배치: `[route-01]` 바로 뒤인 `[route-02]` 2번이다.
|
|
- 확인 필요: `구현 잠금 > 결정 필요`
|