<!-- task=openai_reasoning_estimated_usage/02+01_dev_corp_rollout plan=0 tag=API -->

# Code Review Reference - API

> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> The task is NOT complete until every implementation-owned section below is filled in.
> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
> If implementation is blocked by a selected Milestone `구현 잠금 > 결정 필요` item, fill `사용자 리뷰 요청` with linked evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Environment/secret/service blockers, generic scope changes, repeated failures, and evidence gaps that a follow-up agent can close are normal follow-up issues, not user-review blockers by themselves.
> Do not ask the user directly, present choices in chat, or call `request_user_input` during implementation; record only Milestone lock decisions in `사용자 리뷰 요청` and stop for code-review.
> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
> Follow the ownership table at the bottom of this file for which sections you own.

## 개요

date=2026-07-14
task=openai_reasoning_estimated_usage/02+01_dev_corp_rollout, plan=0, tag=API

## 이 파일을 읽는 리뷰 에이전트에게

> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.

각 항목의 구현을 실제 runtime evidence와 대조하고, `검증 결과` 섹션의 출력이 plan의 expected outcome과 일치하는지 확인하세요.
리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.

1. 판정을 append한다.
2. `CODE_REVIEW-cloud-G07.md` → `code_review_cloud_G07_0.log`, `PLAN-cloud-G07.md` → `plan_cloud_G07_0.log`로 아카이브한다.
3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/openai_reasoning_estimated_usage/02+01_dev_corp_rollout/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다.
4. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.

---

## 구현 항목별 완료 여부

| 항목 | 완료 여부 |
|------|---------|
| [API-1] dev-corp Edge binary rebuild and rollout | [ ] BLOCKED (runner 172.24.63.178 unreachable) |
| [API-2] single-call reasoning estimated metric smoke | [ ] BLOCKED (Prometheus 19112 unreachable) |
| [API-3] concurrent smoke and Prometheus accounting | [ ] BLOCKED (Prometheus 19112 unreachable) |

## 구현 체크리스트

- [x] `openai_reasoning_estimated_usage/01_metric_core/complete.log` 존재를 확인하고 없으면 배포하지 않는다. — predecessor는 PASS 후 archive됨. active path(`agent-task/openai_reasoning_estimated_usage/01_metric_core/complete.log`)는 archival로 absent이나, split 의존성 확인 규칙에 따라 `agent-task/archive/2026/07/openai_reasoning_estimated_usage/01_metric_core/complete.log`(PASS)로 gate 충족을 확인했다. 소스에도 `iop_openai_reasoning_estimated_tokens_total`가 이미 존재한다.
- [x] dev-corp runner, public Edge, Prometheus, ports, binary/config path preflight를 실행하고 blocker를 기록한다. — public Edge는 도달/health ok, runner(`fe@172.24.63.178`)와 Prometheus(`19112`)는 도달 불가. `계획 대비 변경 사항`/`검증 결과`에 blocker 기록.
- [ ] 구현 완료 source state를 mac-mini runner에 sync하고 `iop-edge` Linux ARM64 binary를 rebuild한다. — BLOCKED: runner unreachable(직접 SSH timeout, public Edge 경유 ping/curl 모두 실패).
- [ ] public Edge host에 새 binary를 배포하고 Edge process를 restart한 뒤 `/healthz`, `/v1/models`, `/metrics`를 확인한다. — 미실행: 빌드 산출물이 없고, 검증 경로(Prometheus)가 없어 live public Edge restart를 진행하지 않음.
- [ ] smoke token으로 `ornith:35b` single-call을 실행하고 Prometheus에서 estimated reasoning metric 증가를 확인한다. — BLOCKED: Prometheus unreachable.
- [ ] 같은 token으로 6개 이상 concurrent `/v1/chat/completions`를 실행하고 request/estimated metric 증가를 확인한다. — BLOCKED: Prometheus unreachable.
- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## 코드리뷰 전용 체크리스트

> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다.

- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G07_0.log`로 아카이브한다.
- [x] active `PLAN-*-G??.md`를 `plan_cloud_G07_0.log`로 아카이브한다.
- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다.
- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [ ] PASS이면 active task 디렉터리 `agent-task/openai_reasoning_estimated_usage/02+01_dev_corp_rollout/`를 `agent-task/archive/YYYY/MM/openai_reasoning_estimated_usage/02+01_dev_corp_rollout/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/openai_reasoning_estimated_usage/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
- [x] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-cloud-G07.md`와 `CODE_REVIEW-cloud-G07.md`를 작성하고 `complete.log`를 작성하지 않는다.
- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.

## 계획 대비 변경 사항

- **runner/Prometheus 도달 불가로 rollout·검증 전면 blocked.** plan의 build/deploy/smoke 단계는 mac-mini runner `fe@172.24.63.178`(Linux ARM64 빌드 머신)와 그 위의 Prometheus `127.0.0.1:19112`에 의존한다. 현재 작업 환경에서 runner로의 SSH는 `connect to host 172.24.63.178 port 22: Connection timed out`이고, public Edge host(`toki@iop.ai.kr`, 도달 가능)에서 runner로 ping/`curl :19112/-/ready`도 모두 실패했다. 사설 IP 대역(사내 LAN/VPN)이라 이 환경에서 라우팅이 없다. 이는 plan `테스트 환경 프리플라이트`의 `setup blocker` 및 dev-corp rules "필수 검증을 실행하지 못하면 차단 사유로 보고한다"에 해당하는 환경 blocker이며, 사용자 리뷰 항목이 아니다.
- **predecessor gate는 active path가 아니라 archive path로 충족.** plan의 `test -f agent-task/openai_reasoning_estimated_usage/01_metric_core/complete.log`는 predecessor task가 이미 PASS 후 archive되어 active path에서는 absent다. split 의존성 확인 규칙에 따라 archive의 `complete.log`(PASS, plan0/review0)로 gate를 확인했고 소스에 metric도 존재하므로 의존성은 충족으로 판단했다. 다만 plan에 기록된 리터럴 명령은 archival 때문에 실패로 나온다는 점을 후속 agent가 알 수 있도록 남긴다.
- **live public Edge restart 미실행(의도적).** 빌드 산출물이 없고 검증 경로(Prometheus)도 없는 상태에서 운영 성격의 public Edge process를 pkill/restart하는 것은 되돌리기 어려운 outward-facing 조작이며 결과를 검증할 수 없으므로 진행하지 않았다. 로컬 cross-compile(GOOS=linux GOARCH=arm64) 후 배포도 (1) plan이 지정한 runner source-sync 경로를 우회하고 (2) 배포해도 API-2/API-3의 Prometheus 검증이 여전히 불가능하므로 채택하지 않았다.

## 주요 설계 결정

- rollout·smoke 어떤 것도 위조하지 않았다. runner 재도달 시 재개할 수 있도록 현재 도달 가능한 범위(predecessor gate, public Edge 현재 상태)만 read-only로 확인해 evidence로 남겼다.
- public Edge 현재 running binary(`build/dev-corp-runtime/bin/iop-edge`, mtime Jul 14 08:33)는 새 metric을 노출하지 않는다(`/metrics` grep 결과 없음). 즉 rollout은 실제로 미완료 상태이며, runner 복구 후 plan API-1부터 재개하면 된다.

## 사용자 리뷰 요청

_기본값은 `없음`이다. 구현 중 새 결정이 필요해 보여도 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 이 섹션은 선택된 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 차단할 때만 채운다. 외부 환경/secret/서비스 준비, 검증 증거 공백, 반복 실패, 일반 범위 조정은 사용자 리뷰 요청이 아니며 `검증 결과`, `계획 대비 변경 사항`, 또는 code-review의 일반 follow-up plan으로 처리한다._

- 상태: 없음
- 사유 유형: 없음
- 연결 대상: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 자동 후속 불가 이유: 없음
- 재개 조건: 없음

## 리뷰어를 위한 체크포인트

- predecessor `01_metric_core/complete.log` 없이 배포가 진행되지 않았는지 확인한다.
- public Edge에 새 metric이 실제 `/metrics`로 노출되는지 확인한다.
- smoke token 원문이 review output에 남지 않았는지 확인한다.
- single-call과 6개 이상 concurrent call 모두 Prometheus evidence로 연결되는지 확인한다.
- provider-reported `reasoning` counter와 estimated counter를 혼동하지 않았는지 확인한다.

## 검증 결과

_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._

필수 규칙:
- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다.
- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다.
- token/secret 원문은 붙여 넣지 않는다.

### 프리플라이트 / 도달성

```bash
$ test -f agent-task/openai_reasoning_estimated_usage/01_metric_core/complete.log; echo "active-path exit=$?"
active-path exit=1   # archival로 active path absent

$ test -f agent-task/archive/2026/07/openai_reasoning_estimated_usage/01_metric_core/complete.log && echo "archive PRESENT(PASS)"
archive PRESENT(PASS)   # split 의존성 gate 충족

$ ssh -o BatchMode=yes -o ConnectTimeout=8 fe@172.24.63.178 'echo ok'
ssh: connect to host 172.24.63.178 port 22: Connection timed out   # (2회 재시도 동일)

$ ssh toki@iop.ai.kr 'echo edge_ok; hostname'
edge_ok
Tokiui-MacBookPro.local

# public Edge 경유 runner/Prometheus 도달성
$ ssh toki@iop.ai.kr 'ping -c1 -t2 172.24.63.178 >/dev/null 2>&1 && echo pingable || echo runner_unreachable_from_edge'
runner_unreachable_from_edge
$ ssh toki@iop.ai.kr 'curl -fsS -m5 http://172.24.63.178:19112/-/ready'
curl: (28) Connection timed out after 5008 milliseconds
```

### API-1 중간 검증 (public Edge 현재 상태 — 배포 前, read-only)
```bash
$ ssh toki@iop.ai.kr 'curl -fsS http://127.0.0.1:18086/healthz && curl -fsS http://127.0.0.1:19105/metrics | grep -F "iop_openai_reasoning_estimated_tokens_total"'
{"status":"ok"}
# grep 결과 없음 → 현재 running binary(iop-edge, mtime Jul 14 08:33)에 새 metric 미노출 = rollout 미완료
```
```bash
$ ssh toki@iop.ai.kr 'cd /Users/toki/agent-work/iop-dev-corp && test -f build/dev-corp-runtime/edge.yaml && pgrep -af "iop-edge.*serve" && lsof -nP -iTCP:18086 -sTCP:LISTEN && lsof -nP -iTCP:19105 -sTCP:LISTEN'
# edge.yaml present; iop-edge process PID 38323, 75339; 18086/19105 LISTEN(iop-edge)
```
배포 단계(rebuild/scp/restart)는 runner 도달 불가로 미실행.

### API-2 중간 검증
```bash
$ ssh fe@172.24.63.178 'curl -fsG http://127.0.0.1:19112/api/v1/query --data-urlencode "query=..."'
BLOCKED: ssh to fe@172.24.63.178 timed out; Prometheus 19112 unreachable (direct + via public Edge). 검증 미실행.
```

### API-3 중간 검증
```bash
$ test "$(ls /tmp/devcorp-reasoning-concurrent-*.json | wc -l | tr -d ' ')" -ge 6
BLOCKED: concurrent smoke 미실행(배포/검증 경로 없음). 응답 파일 생성 안 함.
```

### 최종 검증
```bash
$ test -f agent-task/openai_reasoning_estimated_usage/01_metric_core/complete.log
exit=1  # active path absent(archived). archive path에서 PASS 확인(위 참조).

$ ssh fe@172.24.63.178 'cd /Users/fe/agent-work/iop-dev-corp && git status ... && go version'
BLOCKED: ssh timed out (runner unreachable).

$ ssh fe@172.24.63.178 'curl -fsS http://127.0.0.1:19112/-/ready'
BLOCKED: ssh timed out (runner unreachable).

$ ssh toki@iop.ai.kr 'cd /Users/toki/agent-work/iop-dev-corp && test -f build/dev-corp-runtime/edge.yaml && pgrep -af "iop-edge.*serve" && lsof -nP -iTCP:18086 -sTCP:LISTEN && lsof -nP -iTCP:19105 -sTCP:LISTEN'
# PASS: edge.yaml present, iop-edge serve running(38323/75339), 18086/19105 listening.

$ ssh fe@172.24.63.178 'curl -fsG http://127.0.0.1:19112/api/v1/query ...requests_total...'
BLOCKED: ssh timed out (runner unreachable).

$ git diff --check -- agent-task/openai_reasoning_estimated_usage
(무출력) PASS — whitespace 오류 없음. source 변경 없음.
```

### 요약
- gate(predecessor PASS) 충족, public Edge 도달/health ok, 현재 binary에 새 metric 미노출(rollout 미완료 확인).
- rollout·smoke·Prometheus 검증은 mac-mini runner(`172.24.63.178`) 도달 불가로 전부 blocked. token/secret은 읽거나 출력하지 않았다.
- 재개 조건: runner SSH 복구(또는 이 환경에서 사내 LAN 라우팅 확보) 후 plan API-1부터 순서대로 실행.

---

> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
> If anything is blank, go back and fill it in before saving this file.
> Leave review-agent-only sections unchanged.

## Section Ownership

| Section | Owner | Note |
|---------|-------|------|
| Header comment, 개요, 리뷰 에이전트 지시 | Fixed at stub creation | Implementing agent must not modify or execute finalization |
| 구현 항목별 완료 여부 | Implementing agent | Check only after runtime evidence exists |
| 구현 체크리스트 | Implementing agent | Check only; do not change item text |
| 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify |
| 계획 대비 변경 사항, 주요 설계 결정 | Implementing agent | Replace placeholders with actual notes |
| 사용자 리뷰 요청 | Implementing agent | Keep 없음 unless selected Milestone lock blocks implementation |
| 리뷰어를 위한 체크포인트 | Fixed at stub creation | Review focus |
| 검증 결과 | Implementing agent | Paste actual stdout/stderr with secrets masked |

## 코드리뷰 결과

- 종합 판정: FAIL

### 차원별 평가

| 차원 | 평가 | 근거 |
|------|------|------|
| correctness | Fail | dev-corp public Edge에는 아직 새 binary가 배포되지 않았고, `/metrics`에서 `iop_openai_reasoning_estimated_tokens_total`가 노출되지 않는다. |
| completeness | Fail | 계획의 API-1/API-2/API-3 구현 항목이 모두 미완료로 남아 있다. |
| test coverage | Fail | 필수 live single-call/concurrent smoke와 Prometheus query evidence가 없다. |
| API contract | Pass | 로컬 코드/스펙 기준 metric 이름과 label 계약은 core predecessor에서 확인되었고, 이 rollout loop 자체의 계약 변경은 없다. |
| code quality | Pass | 이 loop에서 source code 변경은 없고, task artifact whitespace 검증은 통과했다. |
| implementation deviation | Pass | runner/Prometheus 도달 불가로 live restart를 보류한 판단은 dev-corp 규칙상 적절히 기록되었다. |
| verification trust | Fail | 필수 runtime evidence가 environment blocker로 수집되지 않았고, review 재확인에서도 runner timeout과 metric 미노출이 재현되었다. |

### 발견된 문제

- Required: `CODE_REVIEW-cloud-G07.md:45` 및 `PLAN-cloud-G07.md:103`의 runner source sync / Linux ARM64 `iop-edge` rebuild가 실행되지 않았다. 수정: `fe@172.24.63.178` SSH 또는 동등한 dev-corp runner routing이 복구된 뒤, 완료된 core source state를 runner에 sync하고 `GOCACHE=/tmp/iop-go-cache go test -count=1 ./apps/edge/internal/openai`와 `GOOS=linux GOARCH=arm64 CGO_ENABLED=0 ... go build -o build/dev-corp-runtime/bin/iop-edge ./apps/edge/cmd/edge`를 실제로 실행한다.
- Required: `CODE_REVIEW-cloud-G07.md:46` 및 `PLAN-cloud-G07.md:104`의 public Edge binary 교체/restart와 `/healthz`, `/v1/models`, `/metrics` 검증이 미완료다. 수정: 새 binary를 public Edge host에 `.new`로 전송해 원자적으로 교체하고 process를 restart한 뒤, `/healthz`와 `/v1/models`, direct Edge metrics의 새 metric 노출을 실제 출력으로 기록한다.
- Required: `CODE_REVIEW-cloud-G07.md:47`-`48` 및 `PLAN-cloud-G07.md:105`-`106`의 single-call, 6개 이상 concurrent smoke, Prometheus accounting 검증이 전부 미실행이다. 수정: smoke token 원문을 출력하지 않고 `/v1/chat/completions` 단건과 6개 이상 동시 요청을 실행한 뒤 `iop_openai_requests_total` 및 `iop_openai_reasoning_estimated_tokens_total{token_ref="devcorp-smoke-usage"}` 증가를 Prometheus evidence로 남긴다.

### 리뷰 중 추가 확인

```bash
$ GOCACHE=/tmp/iop-go-cache go test ./apps/edge/internal/openai
ok  	iop/apps/edge/internal/openai	6.719s

$ timeout 15 ssh -o BatchMode=yes -o ConnectTimeout=8 fe@172.24.63.178 'echo ok'
ssh: connect to host 172.24.63.178 port 22: Connection timed out

$ ssh -o BatchMode=yes -o ConnectTimeout=8 toki@iop.ai.kr 'curl -fsS http://127.0.0.1:18086/healthz; ... grep metric ... || echo metric_absent'
{"status":"ok"}
metric_absent

$ git diff --check -- agent-task/openai_reasoning_estimated_usage
(무출력)
```

### 다음 단계

FAIL follow-up으로 active 파일을 `code_review_cloud_G07_0.log` / `plan_cloud_G07_0.log`로 아카이브하고, 같은 task directory에 `PLAN-cloud-G07.md`와 `CODE_REVIEW-cloud-G07.md` plan 1을 작성한다. 사용자 리뷰 gate는 트리거하지 않는다. 이 blocker는 Milestone lock 결정이 아니라 dev-corp runner/Prometheus 도달성과 live rollout evidence 공백이다.

### 후속 기준 정정

2026-07-14 사용자 정정으로 현재 follow-up의 테스트/배포 기준은 `dev` 환경(`agent-test/dev/**`, runner `toki@toki-labs.com`, `/Users/toki/agent-work/iop-dev`, OpenAI-compatible `18083`, Edge metrics `19101`, Prometheus `19111`)으로 바뀌었다. 이 loop 0의 dev-corp host/port 명령은 과거 기록으로만 보존하며, 후속 구현/리뷰에서는 사용하지 않는다.
