# Milestone: [route-03] Heavy Plan/Review 실행과 검증 MVP

## 위치

- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
- Phase: [PHASE.md](../PHASE.md)

## 목표

[`IOP 단일 요청 Agent 실행`](iop-owned-single-request-agent-execution.md)이 구현한 exact single-request 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-04에서 연결한다.
이 마일스톤은 Plan/Review 갱신, 검증과 여러 work/review 전이를 IOP-owned request-scoped workspace/tool runtime에서 수행하며 외부 agent의 추가 model/tool HTTP turn에 의존하지 않는다.

## 상태

[스케치]

## 선행 작업

- [`IOP 단일 요청 Agent 실행`](iop-owned-single-request-agent-execution.md)

## 승격 조건

- [ ] `light`에서 `heavy`로 구분되는 작업 규모·위험·검증 요구와 mode 선택 기준을 확정한다.
- [ ] heavy plan의 갱신 단위, review 기록, work/review/repair 전이와 완료 판정을 확정한다.
- [ ] 여러 internal tool cycle, process restart와 중단 후 재개에 필요한 state/artifact 최소 범위를 확정한다.
- [ ] 검증 실패 시 재계획·수정·재검토의 budget, timeout, cancel과 표준 오류 경계를 확정한다.
- [ ] Claude Messages 이후 endpoint 확장과 IOP-owned 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 결정이 모두 해소되어 있다.
  - [ ] single-request 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-04 handler가 생기기 전 fail-closed한다.

### 2. Plan/Review lifecycle

- 기본 workspace root와 identity는 `.iop/job/<request_id>/`와 `request_id`를 그대로 재사용한다.
- route-02의 `plan.md`/`review.md` pair를 최소 기반으로 삼고, 실제 필요가 확정될 때만 추가 파일·revision·checkpoint를 설계한다.
- plan 갱신, work progress, review defect와 repair 결과는 IOP Node의 request-scoped tool executor가 workspace에 반영한다.
- long-running internal tool cycle에서도 동일 request identity, idempotency와 exactly-once final을 유지한다. 외부 Claude 요청을 추가하지 않는다.

### 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
- 범용 interactive shell, desktop session, 외부 workflow process/state와의 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 단일 요청 Agent 실행 SDD](../../../sdd/knowledge-tool-optimization-extension/iop-owned-single-request-agent-execution/SDD.md)
- 표준선(선택): `light`의 single-request coordinator, IOP-owned tool loop, visible stage stream와 표준 오류 계약을 깨지 않고 `heavy` state만 확장한다.
- 표준선(선택): artifact 구조는 필요가 확정된 시점에만 확장하며 route-02에 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-02]` 바로 뒤인 `[route-03]` 3번이다.
- 확인 필요: `구현 잠금 > 결정 필요`
