<!-- task=m-agent-task-runtime-target-selector/06+05_runtime_quota_failover plan=0 tag=REFACTOR -->

# Code Review Reference - REFACTOR

> **[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, record the exact blocker, attempted commands/output, and resume condition only in implementation-owned evidence fields.
> Do not ask the user directly, present choices, call user-input tools, create control-plane stop files, or classify the next state.
> 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-25
task=m-agent-task-runtime-target-selector/06+05_runtime_quota_failover, plan=0, tag=REFACTOR

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

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

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

1. 판정을 append한다.
2. `CODE_REVIEW-cloud-G09.md` → `code_review_cloud_G09_0.log`, `PLAN-local-G08.md` → `plan_local_G08_0.log`로 아카이브한다.
3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-agent-task-runtime-target-selector/06+05_runtime_quota_failover/`로 이동한다. WARN/FAIL이면 code-review skill이 요구하는 다음 filesystem state를 완전히 작성한다.
4. PASS이고 task group이 `m-agent-task-runtime-target-selector`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.

---

## 구현 항목별 완료 여부

| 항목 | 완료 여부 |
|------|---------|
| REFACTOR-2 Runtime quota probe와 resume/failover state machine | [x] |

## 구현 체크리스트

- [x] bounded candidate의 runtime quota probe가 target/profile required-cap argv로 실행되고 probe 오류는 `unknown` snapshot으로 decision에 남는다.
- [x] resume은 시간·본문 변경에도 pinned target을 사용하고, 확정된 provider target 불가 또는 명시적 retry eligibility만 transition history와 invocation target을 변경한다.
- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다.

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

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

- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
- [x] active `CODE_REVIEW-cloud-G09.md`를 `code_review_cloud_G09_0.log`로 아카이브한다.
- [x] active `PLAN-local-G08.md`를 `plan_local_G08_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/m-agent-task-runtime-target-selector/06+05_runtime_quota_failover/`를 `agent-task/archive/YYYY/MM/m-agent-task-runtime-target-selector/06+05_runtime_quota_failover/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
- [ ] PASS이고 task group이 `m-agent-task-runtime-target-selector`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-agent-task-runtime-target-selector/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
- [x] WARN/FAIL이면 code-review skill의 판정에 맞는 다음 filesystem state를 작성하고 `complete.log`를 작성하지 않는다.

## 계획 대비 변경 사항

계획된 경계와 수정을 정확히 준수하여 구현하였으며 계획 대비 변경 사항은 없음.

## 주요 설계 결정

1. `execution_target_policy.py`: `QuotaProbeSpec` 데이터클래스 및 `quota_probe_spec` 함수를 추가하여 target별 required cap 사양(Gemini: `overall` + `model:<target>`, Claude/Codex: `overall`, Local: `None`)을 명시적으로 수립함.
2. `select_execution_target.py`: `probe_candidate_quota` 함수를 추가하여 shell 없이 subprocess로 `iop-node quota-probe --target ... --command ... --required-cap ... --checked-at ...` 명령을 구성·실행함. 파싱 오류 또는 실행 실패 시 snapshot status를 `unknown`으로 정규화함.
3. `dispatch.py` 및 테스트: resume 핀 메커니즘과 failover 및 same-target recovery/promotion 인터그레이션 테스트를 확장하여 day/night 핀 유지, 본문 수정 유지, generation 변환 초기화, provider target 불가 시 failover, candidate 고갈 시 blocker 전환 동작을 검증함.

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

- quota probe argv의 canonical target/profile/required caps와 error→unknown이 producer 계약과 일치하는가.
- persisted prior decision이 resume에 전달되고 시간·본문 변경이 target을 바꾸지 않는가.
- 확정된 provider target 불가와 명시적 retry eligibility만 failover하며 generic failure는 same-target recovery인가.
- 기존 cloud promotion이 normalized transition/history와 같은 stage budget을 사용하는가.

## 검증 결과

### SelectorDispatcherIntegrationTest

명령: `python3 agent-ops/skills/project/orchestrate-agent-task-loop/tests/test_dispatch.py SelectorDispatcherIntegrationTest -v`

exit_code: 0
```
test_dry_run_multiple_ready_tasks_isolation_and_statelessness (__main__.SelectorDispatcherIntegrationTest.test_dry_run_multiple_ready_tasks_isolation_and_statelessness) ... ok
test_dry_run_statelessness_initial_and_resume_previews (__main__.SelectorDispatcherIntegrationTest.test_dry_run_statelessness_initial_and_resume_previews) ... ok
test_qualified_failover_and_blocker_scenarios (__main__.SelectorDispatcherIntegrationTest.test_qualified_failover_and_blocker_scenarios) ... ok
test_resume_pins_target_across_time_and_body_changes_and_resets_on_new_generation (__main__.SelectorDispatcherIntegrationTest.test_resume_pins_target_across_time_and_body_changes_and_resets_on_new_generation) ... ok
test_worker_and_review_initial_invocation_uses_selector (__main__.SelectorDispatcherIntegrationTest.test_worker_and_review_initial_invocation_uses_selector) ... ok

----------------------------------------------------------------------
Ran 5 tests in 5.164s

OK
```

### Selector 전체 회귀

명령: `python3 agent-ops/skills/project/orchestrate-agent-task-loop/tests/test_select_execution_target.py -v`

exit_code: 0
```
----------------------------------------------------------------------
Ran 40 tests in 1.446s

OK
```

### 전체 Python suite

명령: `python3 -m unittest discover -s agent-ops/skills/project/orchestrate-agent-task-loop/tests -p 'test_*.py'`

exit_code: 0
```
----------------------------------------------------------------------
Ran 204 tests in 18.796s

OK
```

### py_compile

명령: `python3 -m py_compile agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py agent-ops/skills/project/orchestrate-agent-task-loop/scripts/execution_target_policy.py agent-ops/skills/project/orchestrate-agent-task-loop/scripts/select_execution_target.py agent-ops/skills/project/orchestrate-agent-task-loop/tests/test_dispatch.py agent-ops/skills/project/orchestrate-agent-task-loop/tests/test_execution_target_policy.py agent-ops/skills/project/orchestrate-agent-task-loop/tests/test_select_execution_target.py`

exit_code: 0
```
(empty output)
```

### diff check

명령: `git diff --check`

exit_code: 0
```
(empty output)
```


---

> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section?**
> If anything is blank, go back and fill it in before saving this file.
> Leave review-agent-only sections unchanged.

## 섹션 소유권

| Section | Owner | Note |
|---------|-------|------|
| Header comment, 개요, 리뷰 에이전트 지시 | Fixed at stub creation | Implementing agent must not modify or execute these (archive, complete.log, and task-directory archive move are review-agent only) |
| Roadmap Targets | Fixed at stub creation from plan when present | Implementing agent must not modify; code-review copies it into `complete.log` as `Roadmap Completion` only on PASS |
| Archive Evidence Snapshot | Fixed at stub creation from plan when present | Implementing agent uses it as default prior-loop context; read only the specific archive files cited there when more detail is required |
| Agent UI Completion | Mixed | Present only for plan-required agent-ui code work; implementing agent fills actual evidence, review agent applies `구현됨` status/evidence update on PASS and copies the section into `complete.log` |
| 구현 항목별 완료 여부 (item names) | Fixed at stub creation | Implementing agent checks `[ ]` → `[x]` only |
| 구현 체크리스트 (item text/order) | Fixed at stub creation from plan | Implementing agent checks `[ ]` → `[x]` only |
| 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify or check this section |
| 계획 대비 변경 사항, 주요 설계 결정 | Implementing agent | Replace placeholder text with actual content |
| 리뷰어를 위한 체크포인트 | Fixed at stub creation | Pre-filled from plan |
| 검증 결과 (section headings + commands) | Fixed at stub creation | Implementing agent fills in command output only; command changes require a `계획 대비 변경 사항` entry |
| 코드리뷰 결과 | Review agent appends | Not included in stub |

## 코드리뷰 결과

### 종합 판정

FAIL

### 차원별 평가

- Correctness: Fail — 실제 quota snapshot의 `available | exhausted`가 모두 `unknown`으로 손실되고 cloud promotion 실행 target이 persisted decision과 어긋난다.
- Completeness: Fail — runtime-probed failover quota 보존과 cloud promotion transition/history 갱신이 계획 범위를 충족하지 않는다.
- Test coverage: Fail — Python probe fixture가 실제 Go JSON schema를 사용하지 않으며 cloud promotion 테스트가 persisted state와 logical context를 검증하지 않는다.
- API contract: Fail — `iop-node quota-probe` producer와 Python consumer의 JSON field 계약이 불일치한다.
- Code quality: Pass — 범위 내 debug 출력, dead code, 미해결 TODO는 발견하지 않았다.
- Implementation deviation: Fail — 계획이 요구한 normalized transition/history가 기존 cloud promotion 경로에 연결되지 않았다.
- Verification trust: Fail — 계획된 204개 Python 테스트와 Go quota-probe 테스트는 통과하지만 실제 producer shape 재현이 실패하므로 성공 출력만으로 runtime 경로를 신뢰할 수 없다.
- Spec conformance: Fail — SDD S04, S09 및 Evidence Map의 quota snapshot·invocation audit 조건을 충족하지 않는다.

### 발견된 문제

- Required — `agent-ops/skills/project/orchestrate-agent-task-loop/scripts/select_execution_target.py:421`, `agent-ops/skills/project/orchestrate-agent-task-loop/scripts/select_execution_target.py:895`: 실제 Go producer는 상태를 `targets[].status`에 기록하지만 consumer는 존재하지 않는 top-level `status`를 읽어 confirmed `available`/`exhausted`를 `unknown`으로 바꾼다. 또한 failover 중 직접 probe한 cloud alternate의 snapshot을 `_selected_quota`에 전달하지 않아 candidate와 selected quota가 불일치한다. 실제 `QuotaSnapshot` shape를 검증·보존하고 adapter/target에 매칭되는 `targets[].status`를 사용하며, 선택된 alternate의 probed snapshot까지 decision quota에 연결하는 회귀 테스트를 추가해야 한다.
- Required — `agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py:3299`: 기존 cloud promotion은 `spec` 지역 변수만 `Claude/Codex`로 바꾸고 `execution_decisions`, `route_transition_history`, cross-adapter logical context를 갱신하지 않는다. qualified promotion을 canonical selector transition으로 만들고 context package를 검증한 뒤 다음 invocation 전에 같은 persisted state에 commit하며, 실제 invocation target·transition history·공통 stage budget·context evidence가 일치하는 통합 테스트를 추가해야 한다.

### 다음 단계

- FAIL: 위 Required findings를 반영한 follow-up PLAN/CODE_REVIEW pair를 생성한다.
