Task #1560: 한글 페이지 충실도 오라클 정식화 (tools/verify_hangul_pages.py)

[planet6897]

개요

IR 게이트(hwpx-roundtrip/hwp5-roundtrip)나 rhwp 자체 페이지수로는 검출되지 않는 한글 전용 페이지 붕괴(예: #1557 secCnt — IR diff=0 PASS 인데 한글 8→1, 잔여 단일구역 2→1)를 검출하는 정식 도구 tools/verify_hangul_pages.py 를 신설합니다 (closes #1560).

✅ 단독 PR: upstream:devel 직상. tools/문서만 추가하므로 #1552/#1554/#1557(소스 수정)과 무관 — 독립 머지 가능.

동기

무손실 검증 3회(v1~v3)에서, 가장 심각한 결함이 한글 오라클만 검출함이 반복 실증됐습니다. 그 검증이 임시 스크립트로 흩어져 재현·유지가 안 됐습니다. CLAUDE.md 권위 등급상 Windows+한컴에디터 = 1차 정답지이므로 1급 도구로 승격합니다.

도구

• 입력: --batch <원본> <rt> | --inventory <tsv> --orig-root --rt-root(roundtrip 산출 연동).
• 검사: 원본↔rt 한글 PageCount 비교 → OK/COLLAPSE/EXPAND/ERR.
• 옵션: --status 필터, --sample N --seed S(재현 표본), --pdf(PyMuPDF 교차검증).
• 출력: TSV + 붕괴율 요약 + COLLAPSE 시 종료 코드 1(게이트). 헤더에 git HEAD 기록(stale-binary 측정오보 봉인).
• 견고성: 파일별 예외 격리, pyhwpx/PyMuPDF 미설치 명확 안내. tools/verify_hwpx.py 컨벤션 합류.

검증

• 배치: 36382669 OK(8→8, [HWPX/직렬화] 저장본이 한글에서 다중 페이지→1쪽 붕괴 (IR diff 무관, PASS 파일 포함, 실문서 ~10%) #1557 secCnt 수정 케이스), 36384160 COLLAPSE(29→3), 36387103 COLLAPSE(2→1) → 종료 코드 1.
• 인벤토리+표본: --sample 45 --seed 42 가 v3 측정(1/45=2% 붕괴)을 정확 재현.

한계 / 후속

• 한글 의존(Windows+한컴) — Linux CI 게이트 불가, 한컴 보유 컨트리뷰터의 로컬 오라클.
• 페이지수 비교 한정 — 시각 픽셀 diff(T4)·고정 회귀 말뭉치·pic 시각 triage 는 별도 이슈(측정도구 고도화 2·3순위).

근거: output/poc/fidelity3/report.md, mydocs/manual/hangul_page_oracle.md. 관련: #1557, #1556, #1554.

🤖 Generated with Claude Code

[jangster77]

@planet6897 감사합니다. 최신 devel 기준으로 branch update 후 CI를 다시 확인하고 merge 완료했습니다.

검증 결과:

• Build & Test: pass
• CodeQL/Analyze: pass
• WASM Build: skipped

merge commit: 04a7397
관련 이슈 #1560 은 자동 close 되지 않아 수동으로 close 처리했습니다.