iop/agent-task/m-agent-readable-repository-refactor/12+03,06,10,11_readability_baseline/PLAN-local-G07.md

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 문서
• 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 도구가 없다.
• 해결 방법:

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한다.
• 중간 검증:

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

최종 검증

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의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.