<!-- task=m-agent-readable-repository-refactor/04+01,03_openai_complexity plan=1 tag=REVIEW_REFACTOR_DISPATCH -->

# Readability ratchet baseline 복구 계획

## 이 파일을 읽는 구현 에이전트에게

이 plan은 이전 리뷰의 Required 1건만 해결한다. `scripts/readability_baseline.json`을 canonical ratchet schema로 복구하고 고정 검증을 실행한 뒤 `CODE_REVIEW-local-G05.md`의 구현 에이전트 소유 섹션에 실제 출력과 변경 근거를 채운다. active 파일은 유지하고 ready for review만 보고한다. 최종 판정, log rename, `complete.log`, archive 이동은 코드리뷰 에이전트 전용이다. 선택된 Milestone `구현 잠금 > 결정 필요` 항목이 구현을 막을 때만 review stub의 `사용자 리뷰 요청`을 채우며, 직접 사용자 질문·선택지 제시·`request_user_input` 호출·`USER_REVIEW.md` 생성은 금지한다. 환경/secret/service 차단, 일반 범위 변경, 재실행 가능한 검증 공백은 사용자 리뷰 요청이 아니다.

## 배경

이전 구현의 Go 회귀와 mock E2E는 재검증에서 통과했다. 그러나 `scripts/readability_baseline.json`이 ratchet baseline이 아니라 전체 worktree audit report로 덮여 있어 `make readability-audit`가 exit 4로 실패했고, 기록된 `RATCHET OK`를 재현하지 못했다. 코드 동작은 건드리지 않고 baseline 형식과 검증 신뢰만 복구한다.

## 사용자 리뷰 요청 흐름

사용자 리뷰 요청은 선택된 Milestone의 `구현 잠금 > 결정 필요` 항목만 active review stub의 동일 섹션에 기록한다. 구현 중 직접 사용자에게 묻지 않으며, 코드리뷰 에이전트가 요청의 정당성을 확인하고 필요한 경우에만 실제 `USER_REVIEW.md`를 작성한다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/automation-runtime-bridge/milestones/agent-readable-repository-refactor.md`
- Milestone link: [Milestone 문서](agent-roadmap/phase/automation-runtime-bridge/milestones/agent-readable-repository-refactor.md)
- Task ids:
  - `stream-session`: normalized SSE 상태와 terminal 처리를 명명된 session으로 구조화
  - `dispatch-context`: Chat/Responses/provider-pool 인자와 reservation/release lifecycle 구조화
- Completion mode: check-on-pass

## Archive Evidence Snapshot

- Prior plan: `agent-task/m-agent-readable-repository-refactor/04+01,03_openai_complexity/plan_cloud_G08_0.log`
- Prior review: `agent-task/m-agent-readable-repository-refactor/04+01,03_openai_complexity/code_review_cloud_G08_0.log`
- Verdict: FAIL
- Findings: Required 1, Suggested 0, Nit 0
- Issue summary: `scripts/readability_baseline.json:2`가 canonical baseline schema가 아니라 전체 audit report여서 `make readability-audit`가 193개 violation을 `new violation not in baseline`으로 판정했다.
- Affected files: `scripts/readability_baseline.json`
- Verification evidence: targeted OpenAI/service tests, 전체 Edge/Node tests, race-focused session/reservation tests, `IOP_E2E_PROFILE=mock make test-e2e`, `gofmt -d`, `git diff --check`는 PASS. `make readability-audit`만 exit 4로 FAIL.
- Roadmap carryover: `stream-session`, `dispatch-context`는 baseline 복구와 ratchet 재검증이 PASS할 때만 완료 근거로 전달한다.
- Narrow reread allowed: 위 prior plan/review log 두 파일만 필요할 때 좁게 다시 읽는다.

## 분석 결과

### 읽은 파일

- `scripts/readability_baseline.json`
- `scripts/readability_read_sets.json`
- `scripts/readability_audit.py`
- `scripts/readability_audit_test.py`
- `Makefile`
- `agent-test/local/rules.md`
- `agent-test/local/edge-smoke.md`
- `agent-test/local/node-smoke.md`
- `agent-test/local/testing-smoke.md`
- `agent-roadmap/phase/automation-runtime-bridge/milestones/agent-readable-repository-refactor.md`
- `agent-task/m-agent-readable-repository-refactor/04+01,03_openai_complexity/plan_cloud_G08_0.log`
- `agent-task/m-agent-readable-repository-refactor/04+01,03_openai_complexity/code_review_cloud_G08_0.log`

### SDD 기준

- SDD: 불필요
- 사유: 외부 API/proto/config schema와 runtime 책임 경계를 바꾸지 않는 동작 보존형 리팩터링이며 이번 후속은 ratchet baseline 데이터 복구만 수행한다.

### 테스트 환경 규칙

- `test_env=local`
- `agent-test/local/rules.md`, `edge-smoke.md`, `node-smoke.md`, `testing-smoke.md`를 적용한다.
- baseline schema는 `scripts/readability_audit.py`의 strict validator와 `scripts/readability_audit_test.py`를 기준으로 확인한다.
- fresh Go 결과가 필요하므로 `-count=1`과 `/tmp/iop-go-cache`를 사용한다.
- 외부 provider, Docker, emulator는 필요하지 않다.

### 테스트 커버리지 공백

- canonical baseline schema 오류는 기존 `make readability-audit`가 즉시 재현하므로 신규 테스트 파일은 필요하지 않다.
- 기존 strict baseline schema unit tests와 실제 tracked baseline을 읽는 `make readability-audit`를 함께 실행한다.
- stream/context/reservation 동작은 이전 리뷰와 재검증에서 대상·전체·race tests가 통과했다.

### 심볼 참조

- 변경할 Go/Python symbol 없음.
- `scripts/readability_baseline.json`의 root schema만 복구한다.

### 분할 판단

- split 정책을 재평가했다.
- Required 이슈 1건, 데이터 파일 1개, 단일 검증 경계이므로 추가 subtask 분리는 인위적이다.
- 원래 task path와 Roadmap Targets를 유지하는 단일 follow-up이 가장 작고 안전하다.
- 선행 `01_openai_modules`, `03_service_node_modules`는 각각 `agent-task/archive/2026/07/m-agent-readable-repository-refactor/01_openai_modules/complete.log`, `agent-task/archive/2026/07/m-agent-readable-repository-refactor/03_service_node_modules/complete.log`로 충족됐다.

### 범위 결정 근거

- 포함: `scripts/readability_baseline.json` canonical schema 복구와 기존 검증 재실행.
- 제외: `scripts/readability_read_sets.json`, audit 알고리즘, OpenAI/service/Node 코드, agent-spec/contract pointer, 다른 active sibling 변경.
- 현재 전체 audit report는 근거로만 사용하고 repo 내부에 별도 tool artifact로 남기지 않는다. 임시 변환물은 `/tmp`에 둔다.

### 빌드 등급

- `local-G05`: 오류가 단일 JSON schema와 결정적 local 명령으로 재현되며 제품 동작 판단이나 외부 환경이 필요하지 않다.

## 구현 체크리스트

- [ ] `scripts/readability_baseline.json`을 현재 violation identity와 실제 over-budget read-set total을 보존하는 canonical ratchet schema로 복구하고 전체 audit report root를 제거한다.
- [ ] strict schema 검사, readability unit tests, 대상 Go 회귀, `make readability-audit`, `git diff --check`를 fresh 실행해 모두 통과시킨다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [REVIEW_REFACTOR_DISPATCH-1] Canonical readability baseline 복구

문제: `scripts/readability_baseline.json:2`가 아래처럼 전체 audit report root를 사용한다.

```json
{
  "audit_version": "2.0",
  "input_mode": "worktree",
  "files": []
}
```

해결 방법: 현재 report의 `violations`를 metric별 stable identity로 변환하고, compact baseline을 적용한 뒤 다시 산출한 실제 over-budget `task_read_sets` total만 canonical schema에 둔다. 기존보다 낮아진 violation은 낮은 값을 유지하고, 삭제된 identity를 되살리지 않는다. 변환용 report와 후보 파일은 `/tmp`에 만들고 최종 tracked 파일만 교체한다.

```json
{
  "version": "2.0",
  "generated_at": "2026-07-17",
  "file_thresholds": [],
  "function_thresholds": [],
  "task_read_set_totals": []
}
```

수정 파일 및 체크리스트:

- [ ] `scripts/readability_baseline.json`: root key를 canonical 다섯 key로 제한한다.
- [ ] `file_thresholds`: `file_loc` identity와 현재 이하 value만 둔다.
- [ ] `function_thresholds`: `path + function` identity와 현재 이하 value만 둔다.
- [ ] `task_read_set_totals`: compact baseline 적용 뒤 실제 over-budget total로 2-pass 재산출한다.
- [ ] `audit_version`, `input_mode`, `files`, `violations`, `summary`, `policy`, `task_read_sets`를 baseline root에 남기지 않는다.

테스트 작성: 신규 테스트는 작성하지 않는다. `scripts/readability_audit_test.py`의 strict schema tests와 실제 `make readability-audit`가 이 회귀를 직접 검출한다.

중간 검증:

```bash
jq -e 'keys == ["file_thresholds","function_thresholds","generated_at","task_read_set_totals","version"]' scripts/readability_baseline.json
python3 scripts/readability_audit_test.py
make readability-audit
```

기대 결과: `jq`와 unit tests가 exit 0이고 audit가 `RATCHET OK`를 출력한다.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `scripts/readability_baseline.json` | REVIEW_REFACTOR_DISPATCH-1 |

## 최종 검증

```bash
jq -e 'keys == ["file_thresholds","function_thresholds","generated_at","task_read_set_totals","version"]' scripts/readability_baseline.json
python3 scripts/readability_audit_test.py
GOCACHE=/tmp/iop-go-cache go test -count=1 ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/node/internal/node
make readability-audit
git diff --check
```

모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
