# SDD: [bench-02] IOP 원샷 Agent 모델 비교 벤치마크

## 위치

- Milestone: [IOP 원샷 Agent 모델 비교 벤치마크](../../../phase/knowledge-tool-optimization-extension/milestones/iop-one-shot-agent-model-comparison.md)
- Phase: [PHASE.md](../../../phase/knowledge-tool-optimization-extension/PHASE.md)

## 상태

[승인됨]

## SDD 잠금

- 상태: 해제
- 사용자 리뷰: 없음
- 잠금 항목:
  - [x] [D01] 실제 비교는 `[route-02]` 정식 기능·필수 smoke와 `[bench-01]` pipeline 준비가 끝난 뒤 시작한다.
  - [x] [D02] 9개 scored 비교군은 모두 dev `../iop-s2` IOP runtime을 경유한다.
  - [x] [D03] 단독군은 Sonnet 5 최고, Gemini 3.6 Flash high, GPT-5.6 luna xhigh이며 Gemini/GPT는 Claude Code와 전용 caller(agy/Codex)를 각각 비교한다.
  - [x] [D04] 하이브리드는 Gemini 또는 GPT가 plan/review/repair를, ornith-fast가 work를 담당하고 각각 Claude Code와 전용 caller를 비교한다.
  - [x] [D05] 동일 이미지 2장과 vanilla HTML/CSS/JS 한 페이지 fixture를 clean workspace에 제공한다.
  - [x] [D06] 초기 repetitions는 cell별 1이며 clean workspace와 fresh caller session에서 사용자 작업 제출 1회부터 finish/complete 후 idle까지 사람 개입 없이 실행한다.
  - [x] [D07] 시간은 첫 output, 첫 file write, model/stage별 작업, tool, queue와 전체 finish/idle을 clock/source와 함께 기록하고 중첩 구간이나 미관측 overhead를 임의 산술 분해하지 않는다.
  - [x] [D08] token은 input/output/reasoning/cached/total과 source를 model/stage별로 기록하고 미제공 값을 exact로 추정하지 않는다.
  - [x] [D09] 결과 identity를 가린 뒤 동일 100점 rubric으로 Codex가 채점하고 자동 검증과 수동 점수를 분리한다.
  - [x] [D10] scored failure는 보존하고 재실행은 새 attempt로 기록하며 성공 결과만 골라 대표하지 않는다.

## 문제 / 비목표

- 문제: `[route-02]` 하이브리드 원샷의 실사용 가치와 overhead를 판단하려면 같은 IOP 경계, task fixture와 평가 기준에서 단독 모델·caller agent 조합과 속도·token·품질을 함께 비교해야 한다. 단일 성공 smoke만으로는 모델·agent·coordinator 차이를 설명할 수 없다.
- 비목표:
  - `[route-02]` 완료 smoke를 대신하거나 benchmark 점수로 완료 상태를 소급 변경
  - 첫 보고서에서 통계적 다회 반복이나 장기/heavy 작업 평가
  - framework 설치·cache 성능 비교
  - model/provider 가격표를 billing-grade 비용으로 확정

## Source of Truth

| 영역 | 기준 | 메모 |
|------|------|------|
| Roadmap | [Milestone 문서](../../../phase/knowledge-tool-optimization-extension/milestones/iop-one-shot-agent-model-comparison.md) | 9개 비교군과 완료 상태 원장 |
| Pipeline | [bench-01 Milestone](../../../phase/knowledge-tool-optimization-extension/milestones/agent-comparison-benchmark-pipeline.md)의 승인된 manifest/runner/report contract | 실행·측정·보고 구현 원본 |
| Testbed | `../iop-s2` dev IOP runtime | 모든 scored model 호출의 IOP 경유 대상 |
| Fixture | versioned prompt, 이미지 2장과 vanilla workspace checksum | 모든 cell의 동일 입력 기준 |
| Evidence | `agent-test/runs/<run-id>/` | attempt별 timeline, usage, validation, screenshot와 score |
| Report | `agent-test/dev/iop-one-shot-agent-comparison-<date>.md` | 현재 프로젝트의 사람이 읽는 비교 결과 |
| API Contract | [Anthropic-Compatible Messages API](../../../../agent-contract/outer/anthropic-compatible-api.md), [OpenAI-Compatible API](../../../../agent-contract/outer/openai-compatible-api.md) | caller ingress, stream/terminal과 usage 기준 |
| Config Contract | [Edge Config And Runtime Refresh](../../../../agent-contract/inner/edge-config-runtime-refresh.md) | model route, preset, protocol profile과 credential 경계 |
| User Decision | D01-D10 | 2026-08-06 확정 방향, 추가 사용자 결정 없음 |

## State Machine

| 상태 | 진입 조건 | 다음 상태 | 근거 |
|------|-----------|-----------|------|
| `blocked` | `[route-02]` smoke 또는 `[bench-01]` 완료 전 | `preflighting`, 종료 | active Milestone 상태와 pipeline evidence |
| `preflighting` | 선행 조건 충족, execution-day caller/route/credential 점검 | `ready`, `blocked` | redacted preflight matrix |
| `ready` | fixture와 C01-C09 immutable manifest 확정 | `running`, `cancelled` | manifest/fixture/rubric digest |
| `running` | seed 순서에 따라 각 cell에 사용자 작업 1회 제출 | `validating`, `failed`, `timed_out`, `cancelled` | cell/attempt event timeline |
| `validating` | cell finish/complete 후 idle 확정 | `scoring`, `failed` | workspace, build/render/test evidence |
| `scoring` | C01-C09 결과 identity 제거 완료 | `analyzing`, `failed` | blind mapping과 rubric worksheet |
| `analyzing` | 자동 gate·시간·usage·score 완비 | `reported`, `failed` | comparison table과 limitation notes |
| `reported` | Markdown과 raw evidence 포인터 생성 | 종료 | report path와 digest |
| `failed` | cell 실행·검증·채점·보고 실패 | `analyzing`, 종료 | 보존된 실패 attempt; 누락 없는 matrix |
| `timed_out` | cell timeout | `analyzing`, 종료 | timeout/cancel/cleanup evidence |
| `cancelled` | 명시 중단 | 종료 | 실행된 cell과 미실행 cell 상태 |

State invariant:

- C01-C09는 동일 fixture checksum, viewport, rubric version, fresh caller session, setup/cache policy와 repetitions=1을 사용한다.
- execution order는 고정 seed로 생성해 보고서에 남기고 결과에 따라 재정렬하지 않는다.
- preflight와 setup usage/time은 scored measurement에 합산하지 않지만 별도 기록한다.
- 한 cell의 사용자 작업은 한 번 제출하며 사람의 feedback, manual edit, restart가 없다.
- model/tool 호출 횟수는 제약이 아니라 측정 대상이며 finish event 뒤 idle까지가 wall-clock terminal이다.
- 실패 cell도 report matrix에 남고 재실행 결과는 원래 attempt를 대체하지 않는다.

## Interface Contract

- 계약 원문: [Anthropic-Compatible Messages API](../../../../agent-contract/outer/anthropic-compatible-api.md), [OpenAI-Compatible API](../../../../agent-contract/outer/openai-compatible-api.md), [Edge Config And Runtime Refresh](../../../../agent-contract/inner/edge-config-runtime-refresh.md)
- 입력:
  - `fixture`: 동일 이미지 2장, one-page 요구사항, vanilla HTML/CSS/JS initial workspace와 checksum이다.
  - `cells`: C01-C09의 caller, IOP route/preset, expected model/stage와 effort binding이다.
  - `repetitions=1`, `session_policy=fresh`, `setup_cache_policy`: 초기 scored attempt 수, conversation/resume 격리와 공통 setup/cache 기준이다.
  - `environment=dev`, `testbed=../iop-s2`: 실제 IOP runtime 선택이다.
  - `completion`: caller별 finish/complete event와 idle 판정 규칙이다.
- 측정 출력:
  - timestamp: submitted, first output, first file write, model/stage start/end, tool start/end, finish, idle의 monotonic 값과 observation source다. overlap과 unavailable을 명시한다.
  - usage: call count, input/output/reasoning/cached/total token과 source다.
  - validation: requirement, build/serve, desktop/mobile, asset/console, responsive/accessibility 결과다.
  - score: rubric version, 항목별 점수/근거와 총점이며 identity mapping과 분리한다.
- 100점 rubric:
  - 요구사항 충족 25, 시각 완성도 25, 반응형·접근성 15, 이미지 활용·디테일 10, 동작 안정성 10, 코드 품질 10, 자체 검증 완결성 5.
- 금지:
  - IOP를 우회한 model 호출을 scored cell로 인정한다.
  - cell마다 prompt, asset, initial workspace나 viewport를 다르게 사용한다.
  - unavailable token을 0으로 기록하거나 estimated 값을 provider-reported와 합친다.
  - evaluator가 identity를 본 상태에서 점수를 조정하거나 결과를 수동 수정한다.

## Acceptance Scenarios

| ID | Milestone Task | Given | When | Then |
|----|----------------|-------|------|------|
| S01 | `fixture-lock` | 이미지 2장과 one-page benchmark brief | fixture 확정 | prompt/assets/workspace/viewports/rubric의 checksum과 version이 모든 cell에 동일하다. |
| S02 | `route-readiness` | C01-C09 caller와 dev IOP | execution-day preflight | auth, model/preset, effort, stream/finish/idle이 모두 확인되거나 exact blocker로 중단된다. |
| S03 | `matrix-lock` | 선행 gate가 통과한 9개 cell | scored manifest 생성 | repetitions=1, 실행 순서 seed, fresh-session/setup-cache 정책, timeout과 expected binding이 immutable하게 기록된다. |
| S04 | `claude-standalone` | C01 clean workspace | Claude Code 사용자 작업 1회 | IOP→Sonnet 최고 effort 결과와 complete/idle evidence가 생성된다. |
| S05 | `gemini-standalone` | C02-C03 clean workspace | Claude Code와 agy 사용자 작업을 각각 1회 제출 | 두 caller 모두 IOP→Gemini high 결과와 caller별 timing/usage를 남긴다. |
| S06 | `gpt-standalone` | C04-C05 clean workspace | Claude Code와 Codex 사용자 작업을 각각 1회 제출 | 두 caller 모두 IOP→GPT xhigh 결과와 caller별 timing/usage를 남긴다. |
| S07 | `gemini-hybrid` | C06-C07 clean workspace | Claude Code와 agy 사용자 작업을 각각 1회 제출 | IOP Gemini plan→ornith work→Gemini review/repair의 stage evidence와 최종 결과를 남긴다. |
| S08 | `gpt-hybrid` | C08-C09 clean workspace | Claude Code와 Codex 사용자 작업을 각각 1회 제출 | IOP GPT plan→ornith work→GPT review/repair의 stage evidence와 최종 결과를 남긴다. |
| S09 | `objective-validation` | C01-C09 성공·실패 workspace | 자동 웹 검증 | 각 cell의 동일 gate 결과, screenshot과 실패 이유가 누락 없이 생성된다. |
| S10 | `quality-scoring` | identity가 제거된 9개 결과 | Codex rubric 평가 | 항목별 점수/근거와 총점이 자동 gate와 분리되어 기록된다. |
| S11 | `performance-usage` | 모든 attempt timeline/usage | 비교 집계 | 첫 output·첫 write·model/tool/queue/total 시간의 clock/source·overlap, 호출 수와 token/source가 cell·stage별 표가 된다. |
| S12 | `benchmark-report` | S01-S11 evidence | 보고서 생성 | 조건·버전·9개 결과·속도·token·품질·실패·한계와 raw evidence 링크가 Markdown에 남는다. |

## Evidence Map

| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
|----------|-------------------|------------------|---------------------------|
| S01 | fixture prompt/assets/workspace/rubric digest | `agent-task/m-iop-one-shot-agent-model-comparison/fixture-lock/` | `fixture-lock` identical-input evidence |
| S02 | redacted C01-C09 preflight matrix | `agent-task/m-iop-one-shot-agent-model-comparison/route-readiness/` | `route-readiness` auth/route/effort/terminal evidence |
| S03 | immutable scored manifest와 order seed | `agent-task/m-iop-one-shot-agent-model-comparison/matrix-lock/` | `matrix-lock` 9-cell/repetitions=1 evidence |
| S04 | C01 event/timing/usage/workspace evidence | `agent-task/m-iop-one-shot-agent-model-comparison/claude-standalone/` | `claude-standalone` one-submission/IOP evidence |
| S05 | C02-C03 caller별 event/timing/usage/workspace evidence | `agent-task/m-iop-one-shot-agent-model-comparison/gemini-standalone/` | `gemini-standalone` two-caller evidence |
| S06 | C04-C05 caller별 event/timing/usage/workspace evidence | `agent-task/m-iop-one-shot-agent-model-comparison/gpt-standalone/` | `gpt-standalone` two-caller evidence |
| S07 | C06-C07 Gemini/ornith stage와 terminal evidence | `agent-task/m-iop-one-shot-agent-model-comparison/gemini-hybrid/` | `gemini-hybrid` two-caller stage evidence |
| S08 | C08-C09 GPT/ornith stage와 terminal evidence | `agent-task/m-iop-one-shot-agent-model-comparison/gpt-hybrid/` | `gpt-hybrid` two-caller stage evidence |
| S09 | build/render/viewport/asset/console/accessibility result와 screenshot | `agent-task/m-iop-one-shot-agent-model-comparison/objective-validation/` | `objective-validation` uniform gate evidence |
| S10 | blind mapping 분리와 Codex rubric worksheet | `agent-task/m-iop-one-shot-agent-model-comparison/quality-scoring/` | `quality-scoring` 100-point evidence |
| S11 | cell/stage별 normalized timeline, calls와 token-source table | `agent-task/m-iop-one-shot-agent-model-comparison/performance-usage/` | `performance-usage` speed/token evidence |
| S12 | `agent-test/dev/` Markdown과 raw run links | `agent-task/m-iop-one-shot-agent-model-comparison/benchmark-report/` | `benchmark-report` complete comparison evidence |

공통 완료 검증은 C01-C09 모두가 success/failure/blocked 중 하나의 terminal evidence를 가지고, 성공 결과의 자동 gate·screenshot·blind score와 모든 attempt의 timing/usage source가 보고서에 연결되는지 확인한다. 필수 credential/model이 없으면 raw secret을 요구하거나 기록하지 않고 운영 절차로 등록을 요청한다.

## Cross-repo Dependencies

- 없음. 같은 IOP 프로젝트의 `[route-02]`와 `[bench-01]` 실행 순서는 [전역 마일스톤 실행 순서](../../../priority-queue.md)에서 관리한다.

## Drift Check

- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
- [x] agent-contract를 쓰는 경우 SDD에 계약 원문을 복제하지 않았다.
- [x] 사용자 리뷰가 필요한 항목은 없고 확정된 D01-D10을 반영했다.

## 사용자 리뷰 이력

- 2026-08-06: 사용자가 Sonnet/Gemini/GPT 단독과 Gemini/GPT 하이브리드의 9개 IOP 경유 비교군, Claude Code·agy·Codex caller, finish/idle 원샷, 초기 1회, dev `../iop-s2`, 동일 정적 웹 fixture와 시간·token·Codex 품질 평가를 확정했다.

## 작업 컨텍스트

- 표준선: 이 비교는 `[route-02]` 완료 이후의 추가 검증이며 정식 smoke의 일부나 대체 evidence가 아니다.
- 후속 SDD: 없음
