# Milestone: [bench-01] Agent 비교 벤치마크 파이프라인 준비

## 위치

- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
- Phase: [PHASE.md](../PHASE.md)
- SDD: [SDD.md](../../../sdd/knowledge-tool-optimization-extension/agent-comparison-benchmark-pipeline/SDD.md)

## 목표

IOP를 경유하는 Claude Code, agy, Codex의 단독 모델·하이브리드 원샷 실행을 같은 절차로 반복 비교할 수 있도록 project-local skill과 설정 기반 benchmark pipeline을 만든다.
모델, caller agent, prompt fixture와 반복 횟수는 데이터로 바꾸고, 고정 pipeline은 격리 workspace 준비부터 finish/idle 판정, 시간·token·웹 검증·품질 채점·Markdown 보고까지 재현 가능한 evidence로 남긴다.

## 상태

[완료]

## 구현 잠금

- 상태: 해제
- SDD: 필요
- SDD 문서: [Agent 비교 벤치마크 파이프라인 준비 SDD](../../../sdd/knowledge-tool-optimization-extension/agent-comparison-benchmark-pipeline/SDD.md)
- SDD 사유: 외부 CLI의 IOP API 연결, credential/model preflight, 실제 provider 호출, 반복 실행·비용·secret-safe evidence와 실패 분기 계약을 함께 고정해야 한다.
- SDD 상태: 승인됨
- SDD 잠금: 해제
- SDD 사용자 리뷰: 없음
- 잠금 해제 조건: 아래 체크리스트
  - [x] SDD 잠금이 해제되어 있다.
  - [x] SDD 사용자 리뷰가 없거나 승인/해결되었다.
  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
  - [x] Evidence Map이 완료 시 `complete.log`의 `milestone-task` id별 집계와 최종 검증 evidence로 검증 가능하게 연결되어 있다.
- 결정 필요: 없음

## 범위

- pipeline은 `preflight → fixture/workspace 격리 → agent 실행 → finish/idle 대기 → evidence 수집 → 웹 검증 → 익명 품질 채점 → Markdown 보고` 순서를 고정한다.
- benchmark manifest는 caller agent, IOP model/preset route, effort, prompt/asset fixture, 반복 횟수, timeout과 output 위치를 선언한다.
- 초기 caller adapter는 Claude Code, agy와 Codex를 지원하고 모든 scored model 실행이 IOP Edge를 경유했음을 검증한다.
- `../iop-s2`는 dev runtime 테스트베드로 사용하며, 비교 결과물은 매 run의 격리된 임시 workspace에 생성해 테스트베드 source를 수정하지 않는다.
- 병렬 준비 단계의 live preflight는 Claude Sonnet 5 최고 effort, Gemini 3.6 Flash high, GPT-5.6 luna xhigh의 IOP direct route와 caller endpoint/auth/stream/finish/idle 호환을 검증한다. generic runner는 execution preset route도 manifest로 받을 수 있게 만들되 아직 구현 중인 Gemini/GPT hybrid preset의 live readiness는 `[bench-02]` 실행 직전 gate에서 검증한다.
- raw run evidence는 `agent-test/runs/<run-id>/` 아래에 격리하고 최종 비교 보고서는 `agent-test/dev/` 아래 Markdown으로 생성할 수 있게 한다.

## 기능

### Epic: [pipeline-contract] 설정 기반 실행 파이프라인

모델과 요청이 늘어나도 실행 코드를 복제하지 않는 고정 lifecycle과 가변 manifest를 제공한다.

- [x] [benchmark-manifest] caller agent, IOP route/preset, model/effort, prompt·asset fixture, `repetitions`, timeout과 evidence 경로를 선언하고 schema 검증하는 benchmark manifest를 제공한다.
- [x] [benchmark-skill] `agent-ops/skills/project/iop-agent-comparison-benchmark/` project-local skill이 준비 상태를 확인하고 pipeline의 manifest 검증·실행·재개·보고 명령을 일관되게 안내하되 실제 제품 호출은 deterministic script에 위임한다.
- [x] [isolated-workspace] `../iop-s2` dev runtime과 분리된 run별 clean workspace와 fresh caller session을 동일 fixture/checksum에서 만들고 비교군 사이 파일·대화 history·resume state·결과 오염을 막으며 공통 setup/cache 정책을 기록한다.
- [x] [run-lifecycle] 한 번의 사용자 작업 제출 뒤 caller별 event를 수집해 finish/complete 후 idle까지 기다리고 timeout·cancel·process cleanup을 bounded하게 처리한다.
- [x] [repeat-attempt] 초기 기본값 1과 사용자 지정 반복 횟수를 지원하고, scored failure를 덮어쓰지 않으며 재실행은 새 attempt로 보존한다.

### Epic: [agent-connectivity] IOP Agent 연결과 route preflight

각 caller가 IOP를 실제 provider endpoint로 소비하는지 검증하고 설정 문제와 구현 gap을 구분한다.

- [x] [claude-iop] Claude Code가 IOP를 통해 Sonnet, Gemini와 GPT direct route를 인증·조회·호출할 수 있는 runner와 redacted preflight를 제공하고 arbitrary preset route를 받을 수 있는 adapter 계약은 fixture로 검증한다.
- [x] [agy-iop] agy가 IOP를 통해 Gemini direct route를 호출하고 stream·finish/idle을 수신할 수 있는지 검증하며 필요한 client 설정과 generic preset route 입력을 secret-safe fixture로 분리한다.
- [x] [codex-iop] Codex가 IOP를 통해 GPT direct route를 호출하고 stream·finish/idle을 수신할 수 있는지 검증하며 필요한 client 설정과 generic preset route 입력을 secret-safe fixture로 분리한다.
- [x] [effort-route] Sonnet 최고 effort, Gemini high와 GPT xhigh가 각 caller→IOP→provider 경계에서 요청·effective model evidence로 확인되고 unsupported 값이나 alias를 임의 치환하지 않는다.
- [x] [connection-gap] credential/model 누락은 안전한 등록 요청으로, endpoint/auth/protocol/stream 비호환은 별도 구현 Plan 후보로 분류하고 해당 비교군을 우회 성공으로 처리하지 않는다.

### Epic: [evidence-report] 측정·검증·보고

서로 다른 caller의 event를 공통 측정 schema로 정규화하고 원본 evidence와 사람이 읽는 결과를 함께 남긴다.

- [x] [timing-usage] prompt 제출, 첫 output, 첫 file write, model 호출별 작업시간, tool 시간, queue와 finish/idle 전체시간 및 호출 횟수·input/output/reasoning/cached/total token을 clock/source와 함께 수집하고 중첩 구간이나 미관측 overhead를 임의 산술 분해하지 않는다.
- [x] [web-validation] vanilla HTML/CSS/JS 한 페이지 fixture를 build/serve하고 desktop·mobile render, 이미지 2장, console/asset 오류, 반응형·접근성 최소 gate와 screenshot을 자동 검증한다.
- [x] [blind-score] 비교군 identity를 가린 결과물과 screenshot에 동일 100점 rubric을 적용하고 자동 gate와 Codex의 수동 품질 점수를 분리해 기록한다.
- [x] [report-output] manifest, 환경·버전, preflight, attempt, 시간·token·품질 표, 실패·미제공 값과 한계를 포함한 Markdown 보고서를 raw evidence 포인터와 함께 생성한다.

## 완료 리뷰

- 상태: 통과
- 요청일: 2026-08-12
- 완료 근거: archive canonical `complete.log` 18건과 매칭된 최종 PASS plan/review header, SDD S01-S14 evidence를 Task id별로 집계했다. direct connectivity, source-aware timing/usage, Chromium web gate에 이어 identity 익명화·100점 rubric·fresh evaluator provenance, all-status/tie Markdown report와 공개 `report` CLI 계약을 확인했다. 최종 benchmark discovery 421개와 관련 표적 회귀·manifest·CLI·`git diff --check`이 모두 PASS했다.
- Spec sync: Spec updated — [Agent 비교 벤치마크 파이프라인 living spec](../../../../../agent-spec/testing/agent-comparison-benchmark.md)
- 검토 항목: 없음
- 리뷰 코멘트: code audit, local test, manifest/CLI 계약과 living spec gate가 모두 충족되어 2026-08-12 archive했다.

## 범위 제외

- `[route-02]` 정식 기능 구현이나 그 완료 smoke를 대신하는 작업
- 9개 비교군의 실제 scored 실행과 최종 비교 결론 작성
- 구현 전 Gemini/GPT hybrid preset을 live success로 요구해 `[route-02]`와의 병렬 준비를 차단하는 검증
- 특정 model/agent 조합에 맞춘 hard-coded 일회성 script
- Agent-Ops task dispatcher를 IOP 제품 runtime/API 비교 harness로 재사용하는 방식
- raw API key, IOP token, private endpoint, prompt/tool 원문을 tracked evidence에 기록하는 방식

## 작업 컨텍스트

- 관련 경로: `agent-ops/skills/project/iop-agent-comparison-benchmark/`, `agent-test/`, `scripts/`, `agent-contract/outer/`, `../iop-s2`
- 표준선: skill은 orchestration과 안전한 사용법을 소유하고, 설정 기반 script가 실제 CLI/IOP entrypoint 호출과 deterministic evidence 생성을 소유한다.
- 표준선: preflight 호출은 scored attempt에서 제외하되 setup evidence와 사용량을 별도로 표시한다.
- 실행 순서와 차단 관계: [전역 마일스톤 실행 순서](../../../priority-queue.md)
- 관련 Milestone: [[route-02] IOP 단일 요청 Agent 실행](../../../archive/phase/knowledge-tool-optimization-extension/milestones/iop-owned-single-request-agent-execution.md), [[bench-02] IOP 원샷 Agent 모델 비교 벤치마크](iop-one-shot-agent-model-comparison.md)
- 확인 필요: 없음
