iop/agent-roadmap/sdd/knowledge-tool-optimization-extension/agent-comparison-benchmark-pipeline/SDD.md

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

위치

• Milestone: Agent 비교 벤치마크 파이프라인 준비
• Phase: PHASE.md

상태

[승인됨]

SDD 잠금

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

• Milestone 기능 Task와 Acceptance Scenario가 일치한다.
• Evidence Map이 code-review/complete.log에서 검증 가능하다.
• agent-contract를 쓰는 경우 SDD에 계약 원문을 복제하지 않았다.
• 사용자 리뷰가 필요한 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 모델 비교 벤치마크