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

# Code Review Reference - REVIEW_REVIEW_REVIEW_REVIEW_REVIEW_REVIEW_REVIEW_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 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-17
task=m-agent-readable-repository-refactor/12+03,06,10,11_readability_baseline, plan=7, tag=REVIEW_REVIEW_REVIEW_REVIEW_REVIEW_REVIEW_REVIEW_REFACTOR

## 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

## Archive Evidence Snapshot

- 루프 이력:
  - `plan_local_G07_0.log` / `code_review_local_G07_0.log`: FAIL, Required 4 / Suggested 0 / Nit 0.
  - `plan_local_G09_1.log` / `code_review_local_G09_1.log`: FAIL, Required 5 / Suggested 0 / Nit 0.
  - `plan_cloud_G07_2.log` / `code_review_cloud_G07_2.log`: FAIL, Required 5 / Suggested 0 / Nit 0.
  - `plan_cloud_G07_3.log` / `code_review_cloud_G07_3.log`: FAIL, Required 4 / Suggested 0 / Nit 0.
  - `plan_local_G09_4.log` / `code_review_local_G09_4.log`: FAIL, Required 2 / Suggested 0 / Nit 0.
  - `plan_local_G09_5.log` / `code_review_local_G09_5.log`: FAIL, Required 1 / Suggested 0 / Nit 0.
  - `plan_local_G09_6.log` / `code_review_local_G09_6.log`: FAIL, Required 1 / Suggested 0 / Nit 0.
- 현재 아카이브 작업: `agent-task/m-agent-readable-repository-refactor/12+03,06,10,11_readability_baseline/plan_local_G09_6.log`
- 현재 아카이브 리뷰: `agent-task/m-agent-readable-repository-refactor/12+03,06,10,11_readability_baseline/code_review_local_G09_6.log`
- 판정: FAIL
- Required 1 / Suggested 0 / Nit 0
  - `KOTLIN_BARE_COMPARISON_RE`가 `<`/`>` 앞 공백을 요구하고, custom infix operand 판정이 literal이 지워진 cleaned text만 사용해 `1<`, `2>`, `"x" then` 연속식을 누락한다.
- 영향 파일: `scripts/readability_audit.py`, `scripts/readability_audit_test.py`, `scripts/readability_baseline.json`.
- 검증 증거: 제출 및 독립 재실행에서 118 unit, worktree 2회 byte-identical JSON, tracked/worktree RATCHET, baseline exact projection, Make target, `git diff --check`는 PASS했다. 독립 grammar probe의 `C.lessNoSpace`, `C.greaterNoSpace`, `C.stringInfix`는 모두 기대 2 LOC 대신 1 LOC였다.
- Roadmap carryover: `readability-baseline` Task는 PASS 전까지 미완료로 유지한다.
- 추가 상세가 필요하면 위 `plan_local_G09_6.log`와 `code_review_local_G09_6.log`만 좁게 재확인한다.

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

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

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

1. 판정을 append한다.
2. `CODE_REVIEW-local-G09.md` → `code_review_local_G09_N.log`, `PLAN-local-G09.md` → `plan_local_G09_M.log`로 아카이브한다.
3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-agent-readable-repository-refactor/12+03,06,10,11_readability_baseline/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 연결된 Milestone 결정으로 완료/PASS 해소되면 code-review가 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다.
4. PASS이고 task group이 `m-<milestone-slug>`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.

---

## 구현 항목별 완료 여부

| 항목 | 완료 여부 |
|------|---------|
| [REVIEW_REVIEW_REVIEW_REVIEW_REVIEW_REVIEW_REVIEW_REFACTOR-1] Kotlin comparison 및 literal infix continuation | [x] |

## 구현 체크리스트

- [x] [REVIEW_REVIEW_REVIEW_REVIEW_REVIEW_REVIEW_REVIEW_REFACTOR-1] Kotlin comparison token을 spacing-independent하게 판정하고 literal 좌항 custom infix의 raw operand evidence를 보존하면서 sibling 경계를 유지한다.
- [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_{review_lane}_GNN_N.log`로 아카이브한다.
- [x] active `PLAN-*-G??.md`를 `plan_{build_lane}_GNN_M.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/{task_name}/`를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
- [ ] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/{task_group}/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
- [x] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-{build_lane}-GNN.md`와 `CODE_REVIEW-{review_lane}-GNN.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`를 남기지 않는다.
- [ ] USER_REVIEW가 연결된 Milestone 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.

## 계획 대비 변경 사항

- 없음. 계획된 3개 파일(`scripts/readability_audit.py`, `scripts/readability_audit_test.py`, `scripts/readability_baseline.json`)만 수정했고, 검증 명령은 계획 그대로 실행했다.
- baseline 고정점 갱신은 계획이 허용한 identity 값 변화만 반영했다: `scripts/readability_audit.py` file_loc `1854→1874`, `scripts/readability_audit_test.py` file_loc `2157→2174`, `readability-baseline` read_set_total `5980→6017`. 세 항목 모두 기존 reason을 그대로 보존했고 신규 helper violation은 없다(전체 violation 209 유지, 함수 identity 신규 초과 없음).

## 주요 설계 결정

- `KOTLIN_BARE_COMPARISON_RE`를 `r"\s[<>]$"`에서 `r"[<>]$"`로 바꿔 comparison token 판정에서 lexical spacing 요구를 제거했다. depth-0 expression 줄이 bare `<`/`>`로 끝나면 Kotlin grammar상 RHS를 기다리는 comparison이며, expression 위치의 generic argument list는 닫는 `>` 뒤에 호출/참조 token이 이어지므로 줄 끝 bare `<`/`>`와 충돌하지 않는다. `<=`, `>=`, `->`, `..<`는 기존 `KOTLIN_SUFFIX_TOKENS` 검사가 먼저 처리하므로 판정 순서는 그대로다.
- literal 좌항 custom infix는 raw/cleaned 정렬 evidence로 판정한다. blanking이 문자 길이를 보존하므로(`_strip_comments_and_strings`가 non-newline 문자를 공백으로 치환) cleaned text의 match 위치를 raw slice에 그대로 적용할 수 있다. token(identifier, keyword 제외) 판정은 기존대로 cleaned text에서 하고, identifier 앞 raw prefix가 `"` 또는 `'`로 끝날 때만 literal operand로 인정한다(`"x" then` 연속, char literal 포함). raw quote는 cleaned에서 항상 blank되므로 이 검사는 literal일 때만 참이 된다.
- raw literal operand 검사를 cleaned operand 검사보다 먼저 두었다. `1 + "x" then`처럼 cleaned prefix가 operator로 끝나는 경우에도 직전 raw operand가 literal이면 infix 연속이 grammar상 옳기 때문이다. cleaned operand가 비거나(`value` 단독 identifier) quote evidence가 없으면 기존 negative 경로를 그대로 타서 완결 simple identifier와 마지막 sibling은 1 LOC로 유지된다.
- aligned raw 전달은 `_extract_functions_brace`의 `source.splitlines()`를 `_find_expression_end(..., raw_lines)` → `_kotlin_expression_continues(..., raw_content)` → `_kotlin_trailing_continuation(..., raw_content)` → `_kotlin_trailing_infix_identifier(text, raw_text)` 체인 전체에 일관되게 연결했다. `_find_expression_end`의 `raw_lines`는 optional(default `None`이면 cleaned lines 대용)로 두어 Kotlin 외 언어(Dart 등)의 기존 호출 계약과 `;` 종료 계약을 바꾸지 않았고, raw slice 평가는 `lang == "kotlin"` 단락 뒤에서만 일어난다.

## 사용자 리뷰 요청

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

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

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

- 공백 없는 `<`/`>` comparison이 각 RHS까지 포함되는가.
- string literal 좌항 custom infix가 포함되면서 완결 simple identifier는 한 줄로 남는가.
- 다음 declaration/annotation/type close와 마지막 sibling을 삼키지 않는가.
- 기존 comparison/word/range/custom/leading operator, Dart expression body, Shell lexer 회귀가 없는가.
- 추가 helper가 신규 function violation을 만들지 않고 baseline reason과 exact projection이 고정점으로 유지되는가.

## 검증 결과

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

필수 규칙:
- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다.
- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다.
- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다.
- mobile/UI hang, timeout, 또는 2분 무진행은 blind retry를 중단하고 focused rerun 명령과 screenshot/window/UI-tree evidence path를 남기며, 불가능하면 정확한 사유를 남긴다.

### REVIEW_REVIEW_REVIEW_REVIEW_REVIEW_REVIEW_REVIEW_REFACTOR-1 중간 검증

~~~
$ python3 -m unittest scripts.readability_audit_test.TestMultiLanguageFunctionIdentity.test_kotlin_depth_zero_operator_grammar_continuations_span_full_expression scripts.readability_audit_test.TestMultiLanguageFunctionIdentity.test_kotlin_depth_zero_expression_continuations_span_full_expression scripts.readability_audit_test.TestMultiLanguageFunctionIdentity.test_kotlin_multiline_expression_body_spans_full_expression
...
----------------------------------------------------------------------
Ran 3 tests in 0.001s

OK

$ python3 - <<'PY'
from scripts import readability_audit as ra

source = '''class C {
  infix fun String.then(other: Int) = other
  fun lessNoSpace() = 1<
    2
  fun greaterNoSpace() = 2>
    1
  fun stringInfix() = "x" then
    1
  fun plain(value: Int) = value
  fun done() = 3
}
'''
actual = {f['name']: (f['start'], f['end'], f['loc'])
          for f in ra._extract_functions_kotlin(source, 'probe.kt')}
for name in ('C.lessNoSpace', 'C.greaterNoSpace', 'C.stringInfix'):
    assert actual[name][2] == 2, (name, actual[name])
for name in ('C.plain', 'C.done'):
    assert actual[name][2] == 1, (name, actual[name])
print('kotlin-spacing-independent-comparisons=exact')
print('kotlin-literal-infix-and-sibling-boundary=exact')
PY
kotlin-spacing-independent-comparisons=exact
kotlin-literal-infix-and-sibling-boundary=exact
~~~

### 최종 검증

~~~
$ python3 -m unittest scripts.readability_audit_test
......................................................................................................................
----------------------------------------------------------------------
Ran 118 tests in 1.912s

OK

$ python3 - <<'PY'
from scripts import readability_audit as ra

source = '''class C {
  infix fun String.then(other: Int) = other
  fun lessNoSpace() = 1<
    2
  fun greaterNoSpace() = 2>
    1
  fun stringInfix() = "x" then
    1
  fun plain(value: Int) = value
  fun done() = 3
}
'''
actual = {f['name']: (f['start'], f['end'], f['loc'])
          for f in ra._extract_functions_kotlin(source, 'probe.kt')}
for name in ('C.lessNoSpace', 'C.greaterNoSpace', 'C.stringInfix'):
    assert actual[name][2] == 2, (name, actual[name])
for name in ('C.plain', 'C.done'):
    assert actual[name][2] == 1, (name, actual[name])
print('kotlin-spacing-independent-comparisons=exact')
print('kotlin-literal-infix-and-sibling-boundary=exact')
PY
kotlin-spacing-independent-comparisons=exact
kotlin-literal-infix-and-sibling-boundary=exact

$ rm -f /tmp/iop-readability-followup-o.json /tmp/iop-readability-followup-p.json /tmp/iop-readability-followup-tracked-7.json
$ python3 scripts/readability_audit.py --check --input-mode worktree --output /tmp/iop-readability-followup-o.json
RATCHET OK: no new or increased violations.
readability-audit: 336 files, 107980 LOC, 3161 functions, 209 violations
$ python3 scripts/readability_audit.py --check --input-mode worktree --output /tmp/iop-readability-followup-p.json
RATCHET OK: no new or increased violations.
readability-audit: 336 files, 107980 LOC, 3161 functions, 209 violations
$ cmp /tmp/iop-readability-followup-o.json /tmp/iop-readability-followup-p.json
(출력 없음, exit 0)
$ python3 scripts/readability_audit.py --check --input-mode tracked --output /tmp/iop-readability-followup-tracked-7.json
RATCHET OK: no new or increased violations.
readability-audit: 266 files, 74012 LOC, 2199 functions, 133 violations

$ python3 - <<'PY'
import collections
import json

with open('/tmp/iop-readability-followup-o.json', encoding='utf-8') as handle:
    report = json.load(handle)
with open('scripts/readability_baseline.json', encoding='utf-8') as handle:
    baseline = json.load(handle)
identities = [(entry['path'], function['name'])
              for entry in report['files']
              for function in entry.get('functions', [])]
assert not [key for key, count in collections.Counter(identities).items() if count > 1]
current_violations = sorted(
    (v['path'], v['metric'], v.get('function', ''), v['level'], v['value'])
    for v in report['violations'])
baseline_violations = sorted(
    (v['path'], v['metric'], v.get('function', ''), v['level'], v['value'])
    for section in ('file_thresholds', 'function_thresholds')
    for v in baseline[section])
assert current_violations == baseline_violations
current_totals = sorted(
    (task['task_id'], task['total_loc'])
    for task in report['task_read_sets']
    if task['total_loc'] > task['budget']['max_total_loc'])
baseline_totals = sorted((entry['task_id'], entry['value'])
                         for entry in baseline['task_read_set_totals'])
assert current_totals == baseline_totals
print('duplicate-function-identities=[]')
print('baseline-projection=exact')
PY
duplicate-function-identities=[]
baseline-projection=exact

$ make readability-audit
python3 scripts/readability_audit.py --check --input-mode worktree --output build/readability-audit.json
RATCHET OK: no new or increased violations.
readability-audit: 336 files, 107980 LOC, 3161 functions, 209 violations

$ git diff --check
(출력 없음, exit 0)
~~~

---

> **[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 | Owner | Note |
|---------|-------|------|
| Header comment, 개요, 리뷰 에이전트 지시 | Fixed at stub creation | Implementing agent must not modify or execute these |
| Roadmap Targets | Fixed at stub creation from plan | Implementing agent must not modify; code-review copies it into `complete.log` only on PASS |
| Archive Evidence Snapshot | Fixed at stub creation from plan | Implementing agent uses it as prior-loop context and reads only specifically allowed logs |
| 구현 항목별 완료 여부 | Fixed item names | Implementing agent changes only `[ ]` to `[x]` |
| 구현 체크리스트 | Fixed from plan | Implementing agent changes only `[ ]` to `[x]`; final item is mandatory |
| 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify |
| 계획 대비 변경 사항, 주요 설계 결정 | Implementing agent | Replace placeholders with actual content |
| 사용자 리뷰 요청 | Implementing agent | Keep `상태: 없음` unless a selected Milestone lock decision blocks implementation |
| 리뷰어를 위한 체크포인트 | Fixed at stub creation | Pre-filled from plan |
| 검증 결과 | Fixed commands | Implementing agent fills actual output only |
| 코드리뷰 결과 | Review agent appends | Not included in stub |

## 코드리뷰 결과

- 종합 판정: FAIL
- 차원별 평가:
  - correctness: Fail
  - completeness: Fail
  - test coverage: Fail
  - API contract: Pass
  - code quality: Fail
  - implementation deviation: Fail
  - verification trust: Pass
- 발견된 문제:
  - Required — `scripts/readability_audit.py:510`: `KOTLIN_BARE_COMPARISON_RE = r"[<>]$"`는 공백 없는 comparison의 `>`뿐 아니라 `value as List<Int>` / `value is List<Int>`처럼 완결된 generic type의 closing `>`도 무조건 continuation으로 판정한다. 독립 probe에서 `C.cast`가 2∼5번 줄(4 LOC)을 삼키고 `C.typed`, `C.greater`가 extractor 결과에서 누락되었다. Kotlin grammar상 `as`/`is`의 RHS는 generic parameter를 포함할 수 있는 `type`이므로 현재 주석의 “generic argument list가 줄 끝 `>`로 종료될 수 없다”는 가정이 성립하지 않는다. spacing-independent `1>` comparison은 유지하되, cast/type-test의 완결 generic type closer를 비교 연산자와 구분하도록 token/context 판정을 보정하고, nested generic cast/type-test와 뒤이은 sibling identity/start/end/LOC negative regression을 추가한다.
- 다음 단계: FAIL 후속 `PLAN-local-G09.md` / `CODE_REVIEW-local-G09.md`에서 generic type closer와 no-space comparison을 구분하고 sibling 누락 회귀를 고정한다.
