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

## 위치

- Milestone: [Agent 비교 벤치마크 파이프라인 준비](../../../phase/knowledge-tool-optimization-extension/milestones/agent-comparison-benchmark-pipeline.md)
- Phase: [PHASE.md](../../../phase/knowledge-tool-optimization-extension/PHASE.md)

## 상태

[승인됨]

## SDD 잠금

- 상태: 해제
- 사용자 리뷰: 없음
- 잠금 항목:
  - [x] [D01] benchmark 준비는 `[route-02]`와 병렬로 진행하며 direct route live connectivity와 generic preset runner fixture까지만 완료 조건으로 둔다. 실제 Gemini/GPT hybrid preset live readiness와 scored 비교는 `[route-02]` 정식 smoke 뒤의 별도 `[bench-02]`가 소유한다.
  - [x] [D02] 모든 scored model 호출은 IOP를 경유하며 Claude Code, agy, Codex 차이는 runner adapter가 흡수한다.
  - [x] [D03] pipeline lifecycle은 고정하고 agent/model/preset/effort/prompt/assets/repetitions는 manifest로 바꾼다.
  - [x] [D04] 원샷은 사용자 작업 제출 1회부터 finish/complete 후 idle까지이며 내부 model/tool 호출 횟수는 제한하지 않고 측정한다.
  - [x] [D05] dev runtime 테스트베드는 `../iop-s2`이고 결과물은 run별 격리 workspace에 생성해 테스트베드 source를 수정하지 않는다.
  - [x] [D06] 초기 반복 횟수는 1이지만 pipeline은 양수 `repetitions`를 지원한다.
  - [x] [D07] credential/model/effort 누락은 등록·지원 요청으로, agy/Codex endpoint/auth/protocol/stream gap은 별도 구현 Plan 후보로 분류한다.
  - [x] [D08] 실제 CLI/IOP entrypoint를 직접 호출하며 Agent-Ops task dispatcher를 제품 runtime이나 benchmark harness로 사용하지 않는다.
  - [x] [D09] provider가 보고하지 않은 token은 `unavailable`로 기록하고 추정값을 exact source와 섞지 않는다.
  - [x] [D10] 각 cell은 fresh caller session과 clean workspace를 사용하고 공통 setup/cache 정책을 기록하며, timing은 관측 clock/source를 보존하고 중첩 구간을 임의 합산하지 않는다.
  - [x] [D11] 공통 과업은 중립적인 제품 소개 landing page로 고정한다. 필수 산출물은 `index.html`, `styles.css`, `script.js`이고 저장소가 제공하는 로컬 이미지 2장을 입력으로 사용한다. 외부 network asset, framework, build 도구는 금지하며 정확한 prompt·copy·asset checksum은 versioned fixture가 소유한다.
  - [x] [D12] Codex 수동 품질 rubric은 task fidelity 25, visual hierarchy 25, responsive composition 20, typography/readability 15, polish/consistency 15의 100점으로 고정한다. asset·console·접근성 같은 pass/fail 자동 gate는 수동 점수에 다시 합산하지 않는다.
  - [x] [D13] 실행 성공과 모든 필수 web gate를 통과한 attempt만 수동 채점한다. 나머지는 정확한 실패 사유와 함께 `unscored`로 보고하고 0점으로 바꾸지 않으며, 총점 동점은 임의 tie-break 없이 그대로 유지한다.
  - [x] [D14] manifest에 별도 evaluator IOP route/model/effort binding과 rubric revision을 명시하고 fresh evaluator session 1회만 허용한다. invalid worksheet나 evaluator 실패는 대체 model 또는 합성 점수 없이 `scoring_failed`로 보존하며, 재시도는 새 scoring attempt id로만 명시적으로 수행한다.

## 문제 / 비목표

- 문제: 모델, caller agent, prompt와 반복 횟수를 바꿀 때마다 수동 명령과 임시 측정 방식을 다시 만들면 시간·token·품질 비교가 재현되지 않고, 연결 실패나 scored failure가 선택적으로 누락될 수 있다. 고정 lifecycle, adapter 경계, 공통 evidence schema와 secret-safe report가 필요하다.
- 비목표:
  - `[route-02]` 제품 구현 또는 필수 smoke 대체
  - 9개 비교군의 실제 scored 실행과 우열 결론
  - 범용 CI/CD scheduler나 장기 agent orchestration 제품
  - raw credential, private endpoint, prompt/tool 원문을 tracked evidence에 저장하는 기능

## Source of Truth

| 영역 | 기준 | 메모 |
|------|------|------|
| Roadmap | [Milestone 문서](../../../phase/knowledge-tool-optimization-extension/milestones/agent-comparison-benchmark-pipeline.md) | pipeline 기능 Task와 완료 상태 원장 |
| Skill | `agent-ops/skills/project/iop-agent-comparison-benchmark/` | 사용자 요청 해석, preflight와 실행·보고 진입점 |
| Pipeline | project-owned benchmark runner와 manifest schema | lifecycle, adapter, attempt/evidence 생성 구현 원본; exact 경로는 Plan에서 기존 testing 구조에 맞춰 확정 |
| Test Evidence | `agent-test/runs/<run-id>/`, `agent-test/dev/` | raw run evidence와 날짜별 Markdown report |
| Dev Testbed | `../iop-s2` | IOP dev runtime; scored 결과 workspace의 source가 아님 |
| API Contract | [Anthropic-Compatible Messages API](../../../../agent-contract/outer/anthropic-compatible-api.md), [OpenAI-Compatible API](../../../../agent-contract/outer/openai-compatible-api.md) | Claude Code/agy/Codex의 IOP ingress와 terminal/usage 기준 |
| Config Contract | [Edge Config And Runtime Refresh](../../../../agent-contract/inner/edge-config-runtime-refresh.md) | model route, execution preset, protocol profile, credential 경계 |
| Fixture | versioned landing-page prompt, copy와 local image asset checksum | 모든 비교군의 동일 입력과 필수 `index.html`·`styles.css`·`script.js` 산출물 기준 |
| Rubric | manifest `rubric_version`이 가리키는 100점 worksheet contract | D12 항목·가중치와 자동 gate 분리 기준 |
| Evaluator | manifest evaluator binding과 scoring attempt record | D14 IOP route/model/effort, fresh session, 실패·재시도 provenance |
| User Decision | D01-D14 | D01-D10은 2026-08-06, D11-D14는 2026-08-11 확정 |

## State Machine

| 상태 | 진입 조건 | 다음 상태 | 근거 |
|------|-----------|-----------|------|
| `defined` | manifest schema와 pipeline version을 load | `preflighting`, `rejected` | validated manifest, fixture checksum |
| `preflighting` | caller binary/config와 IOP dev route를 secret-safe로 점검 | `ready`, `blocked`, `rejected` | CLI version, auth/model/endpoint/effort/stream result |
| `ready` | 모든 선택 cell의 preflight와 isolated workspace 준비 완료 | `running`, `cancelled` | immutable run manifest와 workspace locator |
| `running` | caller에 사용자 작업을 한 번 제출 | `validating`, `failed`, `timed_out`, `cancelled` | normalized event timeline, process exit와 idle marker |
| `validating` | finish/complete 후 idle 또는 terminal failure 확정 | `scoring`, `reported`, `failed` | workspace checksum, build/render/test evidence |
| `scoring` | 필수 web gate를 통과한 익명화 결과와 screenshot 준비 | `reported`, `scoring_failed` | rubric version, fresh evaluator binding과 scoring attempt record |
| `scoring_failed` | evaluator 실패 또는 invalid worksheet | `scoring`, `reported` | 실패가 보존된 scoring attempt와 명시적으로 생성한 새 retry attempt 또는 unscored 보고 |
| `reported` | raw evidence와 Markdown summary 원자적 생성 | 종료 | report path, manifest/evidence digest |
| `blocked` | credential/model 누락 또는 client↔IOP 호환 gap | `preflighting`, 종료 | redacted blocker classification과 후속 Plan 후보 |
| `rejected` | manifest, fixture, path, repetitions 또는 secret policy 위반 | 종료 | validation error |
| `failed` | scored 실행·검증·보고 실패 | 종료 | 보존된 attempt와 failure class |
| `timed_out` | run 전체 timeout 초과 | 종료 | timeout/cancel/cleanup evidence |
| `cancelled` | 사용자 또는 process cancellation | 종료 | child process cleanup evidence |

State invariant:

- 하나의 attempt는 immutable manifest cell, repetition index, fixture checksum, clean workspace generation과 fresh caller session identity를 가진다. 이전 conversation/resume state를 재사용하지 않는다.
- preflight는 scored attempt가 아니며 setup time/usage를 별도 evidence로 둔다.
- scored attempt가 시작된 뒤의 실패는 삭제하거나 같은 attempt id로 재실행하지 않는다.
- finish/complete event만으로 성공 판정하지 않고 caller adapter가 idle과 process/output quiescence를 함께 확정한다.
- 실행 성공과 모든 필수 web gate를 통과한 attempt만 scoring 대상이다. 나머지는 0점이 아닌 `unscored`와 정확한 실패 사유로 보존한다.
- evaluator 실패나 invalid worksheet는 같은 scoring attempt 안에서 자동 보정·재시도·대체하지 않는다. 재시도는 새 scoring attempt id를 가진다.
- raw credential과 private endpoint는 manifest, event, log, metric, screenshot, report에 기록하지 않는다.

## 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)
- manifest 입력:
  - `pipeline_version`, `environment=dev`, `testbed=../iop-s2`: 실행 contract와 테스트베드 선택이다.
  - `fixture`: 중립적인 제품 소개 landing page prompt·copy, 저장소가 제공하는 로컬 이미지 2장과 initial workspace checksum/version이다. 필수 산출물은 `index.html`, `styles.css`, `script.js`이며 외부 network asset, framework, build 도구를 허용하지 않는다.
  - `matrix[]`: stable cell id, caller(`claude|agy|codex`), IOP route/preset, expected model/stage binding과 effort다.
  - `repetitions`: 1 이상의 실행 횟수이며 초기 비교 manifest는 1이다.
  - `session_policy=fresh`, `setup_cache_policy`, `timeout`, `viewports`, `rubric_version`, `output_root`: 격리, 공통 setup/cache와 bounded 실행·검증·보고 옵션이다.
  - `evaluator`: Codex evaluator의 IOP route/model/effort binding과 rubric revision이다. 각 scoring attempt는 fresh session 1회와 이 immutable binding을 가진다.
- runner adapter 출력:
  - 공통 timeline은 `submitted`, `first_output`, `first_file_write`, model call start/end, tool start/end, finish/complete, idle와 terminal outcome을 monotonic timestamp와 observation source로 표현한다. 구간이 겹치거나 source가 없으면 별도 `overlap|unavailable`로 남기고 `total-model-tool`을 authoritative overhead로 단정하지 않는다.
  - usage는 model/stage, input/output/reasoning/cached/total, source(`provider_reported|client_reported|iop_ledger|estimated|unavailable`)와 호출 횟수를 보존한다.
  - caller 고유 event는 raw evidence에 bounded/redacted 형태로 남기되 공통 field를 추정해 성공으로 만들지 않는다.
- pipeline 출력:
  - attempt manifest, normalized timeline/usage, verification JSON, screenshot, score worksheet와 Markdown report를 run id 아래 연결한다.
  - 수동 100점 worksheet는 task fidelity 25, visual hierarchy 25, responsive composition 20, typography/readability 15, polish/consistency 15를 사용한다. asset·console·접근성 pass/fail은 자동 gate에만 두고 수동 점수에 중복 합산하지 않는다.
  - 실행 또는 필수 web gate 실패는 `unscored`로, evaluator/worksheet 실패는 `scoring_failed`로 기록한다. 동점은 유지하고 실패를 0점으로 변환하거나 임의 tie-break를 적용하지 않는다.
  - 명시적 scoring 재시도는 이전 실패를 보존한 새 scoring attempt id를 생성한다.
- 금지:
  - caller가 IOP를 우회한 provider 호출을 scored IOP cell로 인정한다.
  - unsupported model alias나 effort를 다른 값으로 조용히 대체한다.
  - preflight 성공을 실제 scored 결과로 재사용한다.
  - evaluator 실패를 다른 model이나 합성 점수로 대체하거나 invalid worksheet를 임의 보정한다.
  - raw secret이나 prompt/tool 원문을 tracked artifact에 포함한다.

## Acceptance Scenarios

| ID | Milestone Task | Given | When | Then |
|----|----------------|-------|------|------|
| S01 | `benchmark-manifest` | 새로운 model/agent/prompt/repetition 조합 | manifest validate | schema에 맞는 조합만 canonical ordering으로 확정되고 code 변경 없이 matrix가 늘어난다. |
| S02 | `benchmark-skill` | 사용자가 benchmark 준비·실행·보고를 요청 | skill 진입 | required context와 preflight를 확인하고 deterministic pipeline 명령으로 연결한다. |
| S03 | `isolated-workspace` | 같은 fixture를 쓰는 여러 cell/attempt | workspace 준비 | 동일 checksum의 clean workspace와 fresh caller session이 생성되고 `../iop-s2` source, 이전 history/resume state와 다른 attempt가 변경·재사용되지 않는다. |
| S04 | `run-lifecycle` | caller별 서로 다른 event/exit 형태 | 사용자 작업 1회 제출 | finish/complete와 idle까지 bounded 대기하고 terminal outcome을 공통 timeline으로 만든다. |
| S05 | `repeat-attempt` | `repetitions=1` 또는 더 큰 값과 중간 failure | matrix 실행 | cell별 repetition/attempt id가 안정적으로 생성되고 failure와 재실행이 덮어써지지 않는다. |
| S06 | `claude-iop` | IOP dev direct route와 Claude Code | Sonnet/Gemini/GPT direct preflight와 generic preset fixture 검증 | direct auth/model/stream/terminal과 arbitrary preset route adapter 계약이 확인된다. |
| S07 | `agy-iop` | IOP dev Gemini direct route와 agy | direct preflight와 generic preset fixture 검증 | 지원이면 IOP 경유가 입증되고 아니면 정확한 호환 gap이 기록된다. |
| S08 | `codex-iop` | IOP dev GPT direct route와 Codex | direct preflight와 generic preset fixture 검증 | 지원이면 IOP 경유가 입증되고 아니면 정확한 호환 gap이 기록된다. |
| S09 | `effort-route` | Sonnet 최고/Gemini high/GPT xhigh 요청 | 각 route preflight | requested/effective model·effort가 확인되며 unsupported 값은 fail-closed다. |
| S10 | `connection-gap` | credential/model 또는 endpoint/auth/protocol/stream 실패 | blocker 분류 | 안전한 등록 요청 또는 별도 구현 Plan 후보가 만들어지고 우회 PASS가 없다. |
| S11 | `timing-usage` | caller/model별 event와 provider usage 편차 | evidence normalize | 첫 output·첫 write·model/tool/queue/total 시간의 clock/source와 overlap, 호출 횟수와 token source/미제공이 보존된다. |
| S12 | `web-validation` | versioned landing-page fixture와 필수 HTML/CSS/JS·로컬 이미지 2장 | build/serve/render 검증 | 외부 network asset·framework·build 도구 없이 desktop/mobile screenshot, asset/console, 반응형·접근성 자동 gate evidence가 생성된다. |
| S13 | `blind-score` | 모든 필수 web gate를 통과하고 identity가 제거된 결과물과 screenshot | manifest가 고정한 fresh Codex evaluator 1회 실행 | D12의 동일 100점 rubric 항목별 점수와 근거가 자동 gate와 분리되어 기록되며 실패·invalid worksheet는 `scoring_failed`, 부적격 결과는 `unscored`로 남는다. |
| S14 | `report-output` | 성공·실패·blocked·unscored·scoring_failed attempt evidence | 보고 생성 | 조건·버전·시간·token·품질·동점·한계, evaluator/scoring attempt provenance와 raw evidence 포인터가 있는 Markdown이 생성된다. |

## Evidence Map

| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
|----------|-------------------|------------------|---------------------------|
| S01 | manifest schema/fixture validation과 matrix extension test | `agent-task/m-agent-comparison-benchmark-pipeline/benchmark-manifest/` | `benchmark-manifest` config-driven matrix evidence |
| S02 | project skill validation과 dry command transcript | `agent-task/m-agent-comparison-benchmark-pipeline/benchmark-skill/` | `benchmark-skill` deterministic entrypoint evidence |
| S03 | workspace checksum, containment와 non-mutation test | `agent-task/m-agent-comparison-benchmark-pipeline/isolated-workspace/` | `isolated-workspace` clean isolation evidence |
| S04 | fake/fixture event streams와 real CLI lifecycle probe | `agent-task/m-agent-comparison-benchmark-pipeline/run-lifecycle/` | `run-lifecycle` finish+idle/timeout/cancel evidence |
| S05 | repetition ordering, failure preservation과 resume test | `agent-task/m-agent-comparison-benchmark-pipeline/repeat-attempt/` | `repeat-attempt` immutable attempt evidence |
| S06 | redacted Claude Code→IOP preflight | `agent-task/m-agent-comparison-benchmark-pipeline/claude-iop/` | `claude-iop` route/auth/stream evidence |
| S07 | redacted agy→IOP preflight 또는 exact blocker | `agent-task/m-agent-comparison-benchmark-pipeline/agy-iop/` | `agy-iop` supported/gap evidence |
| S08 | redacted Codex→IOP preflight 또는 exact blocker | `agent-task/m-agent-comparison-benchmark-pipeline/codex-iop/` | `codex-iop` supported/gap evidence |
| S09 | requested/effective route/model/effort matrix | `agent-task/m-agent-comparison-benchmark-pipeline/effort-route/` | `effort-route` no-substitution evidence |
| S10 | blocker classifier와 follow-up routing test | `agent-task/m-agent-comparison-benchmark-pipeline/connection-gap/` | `connection-gap` registration/Plan routing evidence |
| S11 | normalized timeline/usage fixtures와 unavailable handling | `agent-task/m-agent-comparison-benchmark-pipeline/timing-usage/` | `timing-usage` source-aware metric evidence |
| S12 | versioned landing-page fixture checksum, 필수 산출물·로컬 이미지 2장, viewport screenshot과 automatic gate result | `agent-task/m-agent-comparison-benchmark-pipeline/web-validation/` | `web-validation` deterministic render/console/accessibility evidence |
| S13 | anonymization mapping 분리, manifest evaluator binding, D12 worksheet schema, fresh-session·unscored·scoring_failed·새 retry id test | `agent-task/m-agent-comparison-benchmark-pipeline/blind-score/` | `blind-score` unbiased score와 evaluator provenance evidence |
| S14 | success/failure/blocked/unscored/scoring_failed와 동점 report golden test | `agent-task/m-agent-comparison-benchmark-pipeline/report-output/` | `report-output` Markdown/raw-link와 scoring provenance evidence |

공통 완료 검증은 pipeline unit/integration test에서 실제 provider를 호출하지 않는 fake runner guard, manifest/schema validation, workspace containment·cleanup, secret redaction, report golden test와 `git diff --check`를 포함한다. 실제 외부 CLI 호출은 S06-S10의 명시적인 redacted dev preflight로만 분리한다.

## Cross-repo Dependencies

- 없음. `../iop-s2`는 같은 IOP 프로젝트의 dev 테스트베드 workspace이며 별도 프로젝트 Milestone 의존성으로 취급하지 않는다.

## Drift Check

- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
- [x] agent-contract를 쓰는 경우 SDD에 계약 원문을 복제하지 않았다.
- [x] 사용자 리뷰가 필요한 D11-D14를 해결하고 승인 내용을 SDD에 반영했다.

## 사용자 리뷰 이력

- 2026-08-06: 사용자가 모든 비교군의 IOP 경유, Claude Code와 agy/Codex caller 조합, finish/idle 기준 원샷, 초기 1회·가변 반복 pipeline, dev `../iop-s2` 테스트베드와 post-smoke 실제 비교를 확정했다.
- 2026-08-11: 사용자가 D11-D14 추천안을 모두 승인했다. landing page fixture·로컬 이미지 2장·HTML/CSS/JS 산출물, D12 100점 rubric, gate 통과 attempt만 scoring·동점 유지, manifest-bound fresh Codex evaluator와 새 attempt retry 정책을 확정했다.

## 작업 컨텍스트

- 표준선: project-local skill은 orchestration을, deterministic pipeline은 실제 CLI/IOP 호출과 evidence lifecycle을 소유한다. Agent-Ops dispatcher와 IOP 제품 runtime 책임을 섞지 않는다.
- 후속 SDD: [IOP 원샷 Agent 모델 비교 벤치마크](../iop-one-shot-agent-model-comparison/SDD.md)
