<!-- task=m-agent-readable-repository-refactor/12+03,06,10,11_readability_baseline plan=0 tag=REFACTOR -->

# Repository readability audit 기준선과 ratchet

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

> 구현 후 계획의 검증 명령을 그대로 실행하고 CODE_REVIEW의 구현 에이전트 소유 섹션에 실제 메모와 stdout/stderr를 채운 뒤 active 파일을 유지한 채 리뷰 준비 완료를 보고한다. 종결 판정, log rename, complete.log와 archive 이동은 code-review 전용이다. 선택된 Milestone의 미해결 구현 잠금 결정이 실제 구현을 차단할 때만 review stub의 사용자 리뷰 요청에 연결 근거를 기록하고 중단한다. 직접 사용자 질문, chat 선택지, request_user_input, USER_REVIEW.md/complete.log 작성은 금지한다. 환경·secret·service, 일반 범위 조정, 후속으로 보완 가능한 증거 공백은 사용자 리뷰 사유가 아니다.

## 배경

테스트 분해가 끝난 구조를 기준으로 사람이 관리하는 추적 소스의 파일 LOC, 함수 크기, task-local read set을 결정적으로 측정해야 한다. 명시적 사유가 있는 기존 초과만 baseline에 고정하고 신규 초과 또는 수치 증가를 실패시키는 audit와 Make target을 추가한다.

## 사용자 리뷰 요청 흐름

사용자 리뷰 요청은 선택된 Milestone의 구현 잠금 결정만 active review stub의 사용자 리뷰 요청 섹션에 agent-ops/skills/common/_templates/implementation-user-review-request-section.md 형식으로 기록한다. 구현 중 직접 사용자 prompt는 금지하며, 타당성 검증과 USER_REVIEW.md 작성은 code-review가 소유한다.

## 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:
  - `readability-baseline`: 추적 소스의 파일/함수/read-set 기준선과 재현 가능한 ratchet audit 도입
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- agent-roadmap/phase/automation-runtime-bridge/milestones/agent-readable-repository-refactor.md
- agent-test/local/rules.md
- agent-test/local/profiles/testing-smoke.md
- Makefile
- .gitignore

### SDD 기준

선택 Milestone은 SDD: 불필요다. 외부 API/proto/config schema와 runtime 책임 경계를 바꾸지 않는 동작 보존형 리팩터링이라는 기록 사유를 적용한다.

### 테스트 환경 규칙

test_env=local. local rules와 testing-smoke profile을 읽었다. Python은 repository dependency를 추가하지 않고 stdlib unittest를 사용한다. 생성 JSON은 /tmp 두 파일로 반복 실행해 cmp하고, Make target은 build/readability-audit.json을 생성한다. source/test 동작 변경이 없어 full-cycle/E2E는 필요하지 않다.

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

새 audit 로직은 테스트가 없다. tracked input/exclusion 정렬, 파일/함수 threshold, same-value allowlist PASS, 신규/증가 FAIL, read-set 합산과 deterministic JSON을 scripts/readability_audit_test.py에 작성한다.

### 심볼 참조

새 Make target readability-audit와 새 Python CLI만 추가한다. 기존 심볼 rename/remove와 call site는 없다.

### 분할 판단

이 디렉터리의 +03,06,10,11은 openai-tests, core-tests, adapter-command-tests, client-tests 최종 sibling의 complete.log를 모두 요구한다. 테스트 분해 뒤의 구조를 baseline으로 고정하기 위한 실제 의존성이고 추가 predecessor는 없다.

### 범위 결정 근거

Git이 추적하는 Go/Dart/Shell/Python/Kotlin/Swift만 입력으로 삼고 proto/gen/**, apps/client/lib/gen/**, build/vendor/data-only는 제외한다. production 동작, CI workflow, agent-ops Skill 내용은 수정하지 않는다.

### 빌드 등급

local-G07: 새 deterministic audit/ratchet CLI, 다언어 함수 계측, baseline schema와 unit/boundary test가 필요하지만 외부 dependency 없이 국소 검증 가능하다.

## 구현 체크리스트

- [ ] [REFACTOR-1] 파일/함수/read-set 기준선과 사유 필수 ratchet을 구현하고 unit test, 반복 JSON cmp, Make audit를 모두 통과시킨다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [REFACTOR-1] readability audit와 baseline schema 구현

- 문제: Makefile:1의 PHONY와 76~77의 test target에는 가독성 audit 진입점이 없고 scripts/에도 추적 파일 LOC/함수/read-set의 결정적 ratchet 도구가 없다.
- 해결 방법:

~~~text
Before
Makefile:1  .PHONY: ... test ... clean
Makefile:76 test:
Makefile:77     go test ./...

After
Makefile              readability-audit target
scripts/readability_audit.py
scripts/readability_baseline.json
scripts/readability_read_sets.json
scripts/readability_audit_test.py
build/readability-audit.json (ignored output)
~~~

- 수정 파일 및 체크리스트:
  - [ ] Makefile: .PHONY와 readability-audit target을 추가한다.
  - [ ] scripts/readability_audit.py: git ls-files -z 입력, exclusion, LOC/함수/read-set 측정, sorted JSON, ratchet check를 구현한다.
  - [ ] scripts/readability_baseline.json: threshold 초과마다 path/metric/value/non-empty reason을 기록한다.
  - [ ] scripts/readability_read_sets.json: 대표 task별 ordered path와 budget/예외 사유를 기록한다.
  - [ ] scripts/readability_audit_test.py: deterministic/exclusion/threshold/ratchet/read-set 정상·경계 테스트를 작성한다.
- 테스트 작성: 새 기능이므로 테스트를 작성한다. scripts/readability_audit_test.py의 test_tracked_inputs_are_sorted_and_generated_paths_excluded, test_threshold_boundaries, test_allowlist_same_value_passes, test_new_or_increased_violation_fails, test_read_set_totals_are_deterministic가 fixture tree와 임시 baseline을 사용해 각각 입력/경계/ratchet/read-set을 assert한다.
- 중간 검증:

~~~bash
python3 -m unittest scripts/readability_audit_test.py
python3 scripts/readability_audit.py --check --output /tmp/iop-readability-a.json
python3 scripts/readability_audit.py --check --output /tmp/iop-readability-b.json
cmp /tmp/iop-readability-a.json /tmp/iop-readability-b.json
~~~

기대 결과: unit tests PASS, 두 audit JSON byte-identical, 신규/증가 초과 없음.

## 의존 관계 및 구현 순서

1. agent-task/m-agent-readable-repository-refactor/03+02_openai_provider_tools/complete.log를 확인한다.
2. agent-task/m-agent-readable-repository-refactor/06+04,05_core_edge_tests/complete.log를 확인한다.
3. agent-task/m-agent-readable-repository-refactor/10+07,08,09_adapter_control_plane_tests/complete.log를 확인한다.
4. agent-task/m-agent-readable-repository-refactor/11_client_tests/complete.log를 확인한다.
5. 디렉터리 이름에 없는 추가 predecessor는 요구하지 않는다.

## 수정 파일 요약

| 파일 | 항목 |
|---|---|
| Makefile | REFACTOR-1 |
| scripts/readability_audit.py | REFACTOR-1 |
| scripts/readability_baseline.json | REFACTOR-1 |
| scripts/readability_read_sets.json | REFACTOR-1 |
| scripts/readability_audit_test.py | REFACTOR-1 |

## 최종 검증

~~~bash
python3 -m unittest scripts/readability_audit_test.py
rm -f /tmp/iop-readability-a.json /tmp/iop-readability-b.json
python3 scripts/readability_audit.py --check --output /tmp/iop-readability-a.json
python3 scripts/readability_audit.py --check --output /tmp/iop-readability-b.json
cmp /tmp/iop-readability-a.json /tmp/iop-readability-b.json
make readability-audit
git diff --check
~~~

기대 결과: unit tests PASS, audit 결과 재현 가능, 신규/증가 초과는 0, baseline 예외마다 사유 존재, Make target PASS.

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

