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

mydocs/manual/hangul_page_oracle.md

@@ -0,0 +1,60 @@
+# 한글 페이지 충실도 오라클 가이드 (Task #1560)
+
+`tools/verify_hangul_pages.py` — 원본 ↔ 저장본(rt)을 한컴오피스로 열어 **PageCount** 를
+비교하여, IR 게이트가 못 잡는 **한글 전용 페이지 붕괴**를 검출하는 정식 도구.
+
+## 1. 왜 필요한가
+무손실 검증(`hwpx-roundtrip`/`hwp5-roundtrip`)의 IR diff 와 rhwp 자체 페이지수로는
+**한글에서만 나타나는 페이지 붕괴**가 검출되지 않는다(예: #1557 secCnt — IR diff=0 PASS
+인데 한글 8→1). CLAUDE.md 권위 등급상 Windows+한컴에디터가 1차 정답지이므로, 이 오라클을
+재현 가능·게이트 가능한 도구로 정식화했다. (임시 스크립트 `output/poc/fidelity*/t3_*.py` 대체)
+
+## 2. 요구사항
+- Windows + 한컴오피스 2010+, `pip install pyhwpx`.
+- `--pdf` 옵션 사용 시 `pip install pymupdf`.
+- 다이얼로그 차단 전제(FilePathCheckerModule 등록 — `hwp_com_automation` 메모리 룰).
+
+## 3. 사용법
+
+### 배치 모드 (원본 폴더 ↔ rt 폴더)
+```bash
+python tools/verify_hangul_pages.py --batch <원본_폴더> <rt_폴더> -o out.tsv
+```
+원본을 재귀 스캔하여 상대경로로 rt(`{stem}.rt.hwpx`/`.rt.hwp`)를 매칭.
+
+### 인벤토리 모드 (roundtrip 산출 TSV 기준)
+```bash
+rhwp hwpx-roundtrip --batch <원본_폴더> -o out/rt        # 1) rt + inventory.tsv 생성
+python tools/verify_hangul_pages.py \                     # 2) 한글 페이지 비교
+    --inventory out/rt/inventory.tsv \
+    --orig-root <원본_폴더> --rt-root out/rt \
+    --status IR_DIFF,PASS --sample 40 --seed 42 [--pdf] -o out/hangul_pages.tsv
+```
+
+### 옵션
+| 옵션 | 설명 |
+|------|------|
+| `--batch ORIG RT` / `--inventory TSV` | 입력(상호배타). 인벤토리는 `--orig-root`·`--rt-root` 필요 |
+| `--status A,B` | 인벤토리 상태 필터(예: `IR_DIFF,PASS`) |
+| `--sample N --seed S` | 재현 가능한 무작위 표본(0=전수) |
+| `--pdf` | 한글 PDF 내보내기 후 PyMuPDF 페이지수 교차검증 |
+| `-o TSV` | 결과 저장(헤더에 `git_head` 기록) |
+| `--visible` | 한글 창 표시(디버깅) |
+
+## 4. 판정·종료코드
+- `OK`(원본=rt) / `COLLAPSE`(rt<원본) / `EXPAND`(rt>원본) / `ERR`(파일별 오류, 격리).
+- **COLLAPSE ≥ 1 이면 종료 코드 1**(게이트). pyhwpx/PyMuPDF 미설치·입력 오류는 2.
+- 콘솔·TSV 헤더에 **git HEAD** 기록 → stale-binary 측정 오보(v1 F2') 재발 봉인.
+
+## 5. 한계
+- **한글 의존**: Windows+한컴 전용. Linux CI 게이트 불가 — 한컴 보유 컨트리뷰터의 **로컬 오라클**.
+- 한글 COM 불안정(행/팝업) 가능 — 파일별 예외 격리로 전체 중단은 방지하나, 개별 ERR 은 수동 확인.
+- 대량은 `--sample` 권장(한글 1건당 수 초). 전수는 시간 소요.
+- **페이지수 비교**이며 시각 픽셀 충실도는 검사하지 않음(T4 시각 diff 는 후속 별도).
+
+## 6. 관련
+- 수행/구현 계획: `mydocs/plans/task_m100_1560{,_impl}.md`
+- 단계 보고서: `mydocs/working/task_m100_1560_stage{1..3}.md`
+- 최종 보고서: `mydocs/report/task_m100_1560_report.md`
+- 배경(붕괴 발견): `output/poc/fidelity3/report.md`, #1557(secCnt)
+- 컨벤션: `tools/verify_hwpx.py`(단일파일 한글 검증)

mydocs/plans/task_m100_1560.md

@@ -0,0 +1,44 @@
+# Task #1560: 한글 페이지 충실도 오라클 정식화 — 수행계획서
+
+## 목표
+무손실 검증에서 **IR 게이트가 못 잡는 한글 페이지 붕괴**(예: #1557 secCnt, 잔여 2→1)를
+**재현 가능·게이트 가능**하게 검출하는 정식 도구 `tools/verify_hangul_pages.py` 를 신설한다.
+흩어진 임시 스크립트(`output/poc/fidelity*/t3_*.py`)를 대체한다.
+
+## 배경
+- v1~v3 실증: 최악 결함(페이지 붕괴)은 `hwpx-roundtrip`·rhwp 페이지수 모두 미검출,
+  **한글 PageCount 비교로만** 발견·정량화(붕괴율 10%→2% 추적).
+- CLAUDE.md 권위 등급: Windows+한컴에디터 = 1차 정답지. 그 오라클이 임시 스크립트라 재현·유지 불가.
+- 기존 컨벤션: `tools/verify_hwpx.py`(pyhwpx 단일파일 검증), `tools/verify_all.py`.
+
+## 범위
+**포함(In)**
+- `tools/verify_hangul_pages.py`: 원본↔rt 쌍의 한글 `PageCount` 배치 비교.
+  - 입력: `--batch <orig_dir> <rt_dir>`(stem/상대경로 매칭) | `--inventory <tsv>`+rt루트.
+  - `--sample N [--seed S]`, 상태 필터, `--pdf`(PDF 페이지수 교차검증, 선택).
+  - 출력: TSV(status/orig_pg/rt_pg/verdict) + 요약(붕괴율) + **COLLAPSE 시 종료 코드 1**.
+  - 견고성: 파일별 예외 격리·스킵, 손상 ZIP 스킵.
+  - 재현성: 헤더에 git HEAD·바이너리 빌드시각 기록(stale-binary 함정 방지).
+- 매뉴얼 `mydocs/manual/hangul_page_oracle.md`.
+
+**제외(Out)**
+- 시각 픽셀 diff(T4)·고정 회귀 말뭉치·pic 시각 triage(각 별도 이슈).
+- rhwp 소스 변경 없음(순수 도구/문서). Hangul 의존이라 Linux CI 게이트는 불가(로컬 오라클).
+
+## 검증·판정 기준
+- 알려진 케이스 재현: secCnt **수정 전 rt**(예: 보관본)에서 COLLAPSE 검출, **수정 후 rt**(fidelity3)에서 OK.
+- v3 표본 재측정 결과(붕괴율 ~2%, 잔여 36387103 2→1)를 도구가 동일 재현.
+- `--inventory` 모드가 `hwpx-roundtrip`/`hwp5-roundtrip` 산출 TSV와 호환.
+- pyhwpx 미설치/비-Windows 환경에서 명확한 안내 후 비정상 종료(크래시 금지).
+
+## 위험/주의
+- 한글 COM 불안정(행/팝업) — 파일별 try/except + 필요시 Hangul 재기동, `clear(option=1)` 정리.
+- 대량 실행 시간 — `--sample` 기본 권장, 전수는 옵션.
+- 다이얼로그 차단(FilePathCheckerModule 등록 전제, 메모리 룰 정합).
+
+## 다음 단계
+승인 시 **구현 계획서**(`task_m100_1560_impl.md`, 3단계):
+1. 핵심 도구(배치/inventory 입력 + PageCount 비교 + TSV/종료코드)
+2. 견고성·재현성(예외 격리·HEAD 기록·`--pdf`·`--sample`) + 기존 t3 스크립트 대체
+3. 매뉴얼 + 알려진 케이스 재현 검증 + 최종 보고
+작성 → 재승인 후 진행.

mydocs/plans/task_m100_1560_impl.md

@@ -0,0 +1,30 @@
+# Task #1560: 한글 페이지 충실도 오라클 — 구현 계획서
+
+> 수행계획서 `task_m100_1560.md`(승인). 3단계. 소스 변경 없음(도구/문서).
+> 컨벤션: `tools/verify_hwpx.py`(argparse + pyhwpx + 종료코드).
+
+## Stage 1 — 핵심 도구
+- `tools/verify_hangul_pages.py`:
+  - 입력 `--batch <orig_dir> <rt_dir>` (재귀, stem/상대경로 매칭, rt 접미사 `.rt.hwpx`/`.rt.hwp`).
+  - 각 쌍 한글 `PageCount` 비교 → `OK`/`COLLAPSE`/`EXPAND`/`MISSING`/`ERR`.
+  - TSV(`verdict/orig_pg/rt_pg/rel`) + 요약(붕괴율) + **COLLAPSE>0 시 exit 1**.
+  - pyhwpx 미설치/비-Windows 명확 안내 후 종료(크래시 금지).
+- 검증: fidelity3 rt 로 36382669 OK(8→8), 36387103 COLLAPSE(2→1) 검출.
+- 산출: `task_m100_1560_stage1.md` + 커밋.
+
+## Stage 2 — 견고성·재현성·입력 확장
+- `--inventory <tsv>`(hwpx/hwp5-roundtrip 산출) + `--rt-root` 모드, `--status` 필터.
+- `--sample N [--seed S]`, `--pdf`(PDF 페이지수 교차검증, 선택).
+- 파일별 try/except 격리(한글 행/오류 스킵), `clear(option=1)` 정리.
+- 재현성: 출력 헤더에 git HEAD + (지정 시) 바이너리 빌드시각 기록.
+- 산출: `task_m100_1560_stage2.md` + 커밋.
+
+## Stage 3 — 매뉴얼 + 검증 + 임시 스크립트 대체 + 최종 보고
+- `mydocs/manual/hangul_page_oracle.md`(사용법·등급·한계).
+- 알려진 케이스 재현: v3 표본(~2% 붕괴, 36387103) 동일 재현 + 종료코드 확인.
+- `output/poc/fidelity*/t3_*.py` 대체 안내(도구로 일원화).
+- `mydocs/report/task_m100_1560_report.md` + 커밋.
+
+## 주의
+- 한글 COM 불안정 대응(예외 격리, 필요시 재기동). 다이얼로그 차단 전제(FilePathCheckerModule).
+- 대량 시 `--sample` 권장. rhwp 소스 무변경.

mydocs/report/task_m100_1560_report.md

@@ -0,0 +1,38 @@
+# Task #1560 최종 결과보고서 — 한글 페이지 충실도 오라클 정식화
+
+- 이슈: #1560 (M100)
+- 브랜치: `local/task1560` (from devel = #1552+#1554+#1557)
+- 일자: 2026-06-26
+
+## 1. 목표 및 결과
+IR 게이트가 못 잡는 **한글 전용 페이지 붕괴**(#1557 secCnt류, 잔여 2→1)를 재현·게이트
+가능하게 검출하는 정식 도구 `tools/verify_hangul_pages.py` 를 신설. 흩어진 임시
+스크립트(`output/poc/fidelity*/t3_*.py`)를 일원화.
+
+## 2. 도구 개요
+- 입력: `--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** 기록.
+- 견고성: 파일별 예외 격리, pyhwpx/PyMuPDF 미설치 명확 안내.
+
+## 3. 검증
+- 알려진 케이스(배치): 36382669 **OK**(8→8, secCnt 수정), 36384160 **COLLAPSE**(29→3),
+  36387103 **COLLAPSE**(2→1) → 종료 코드 1.
+- 인벤토리+표본 재현: `--sample 45 --seed 42` 가 v3 임시 스크립트 결과(**1/45=2% 붕괴**)를 정확 재현.
+- git HEAD(b086bd5a) 기록 확인.
+
+## 4. 가치
+페이지 붕괴 같은 **IR-blind 최악 클래스를 재현 가능·게이트 가능**하게 만들었다. 향후
+secCnt류 회귀를 한컴 보유 환경에서 즉시 감지. `hwpx-roundtrip`/`hwp5-roundtrip` 산출
+inventory 와 직접 연동.
+
+## 5. 한계 / 후속
+- 한글 의존(Windows+한컴) — Linux CI 게이트 불가, 로컬 오라클.
+- 페이지수 비교 한정 — **시각 픽셀 diff(T4)**·**고정 실문서 회귀 말뭉치**·**pic 시각 triage**는
+  별도 이슈(측정도구 고도화 2·3순위).
+
+## 6. 변경 파일
+- 신규: `tools/verify_hangul_pages.py`, `mydocs/manual/hangul_page_oracle.md`
+- 계획/보고: `mydocs/plans/task_m100_1560{,_impl}.md`, `mydocs/working/task_m100_1560_stage{1..3}.md`
+- rhwp 소스 무변경(순수 도구/문서).

mydocs/working/task_m100_1560_stage1.md

@@ -0,0 +1,22 @@
+# Task #1560 Stage 1 완료보고서 — 핵심 도구
+
+## 변경
+- 신규 `tools/verify_hangul_pages.py`:
+  - `--batch <원본_폴더> <rt_폴더>`: 원본 재귀 스캔 → 상대경로 매칭으로 rt(`.rt.hwpx`/`.rt.hwp`) 탐색.
+  - 각 쌍 한글 `PageCount` 비교 → `OK`/`COLLAPSE`/`EXPAND`/`ERR`.
+  - 파일별 try/except 격리(한글 행/오류로 전체 중단 방지), `clear(option=1)` 정리.
+  - TSV(`verdict/orig_pg/rt_pg/note/rel`) + 요약(붕괴율) + **COLLAPSE>0 시 종료 코드 1**(게이트).
+  - pyhwpx 미설치 시 명확 안내 후 종료 코드 2(크래시 금지).
+  - `tools/verify_hwpx.py` 컨벤션(argparse+pyhwpx+종료코드) 합류.
+
+## 검증 (알려진 케이스 3건)
+```
+[1/3]       OK  pg 8->8   36382669   # #1557 secCnt 수정 케이스 — 정상 OK
+[2/3] COLLAPSE  pg 29->3  36384160   # secCnt 부분복구 잔여 — 붕괴 검출
+[3/3] COLLAPSE  pg 2->1   36387103   # 단일구역 잔여 — 붕괴 검출
+종료 코드 1 (COLLAPSE 존재)
+```
+IR 게이트가 못 잡는 붕괴를 정확히 검출하고 게이트 종료코드 동작 확인.
+
+## 다음
+Stage 2 — `--inventory`/`--sample`/`--pdf`/`--status` + 재현성(git HEAD 기록).

mydocs/working/task_m100_1560_stage2.md

@@ -0,0 +1,23 @@
+# Task #1560 Stage 2 완료보고서 — 입력 확장 + 재현성
+
+## 변경 (`tools/verify_hangul_pages.py`)
+- `--inventory <tsv> --orig-root <dir> --rt-root <dir>`: roundtrip `inventory.tsv`
+  의 `sample`/`status` 컬럼 기준으로 쌍 수집. `--status IR_DIFF,PASS` 필터.
+- `--sample N [--seed S]`: 재현 가능한 무작위 표본(시드 고정).
+- `--pdf`: 한글 PDF 내보내기 후 PyMuPDF 페이지수 교차검증(렌더 기준 강화).
+- 재현성: 콘솔/TSV 헤더에 **git HEAD** 기록(stale-binary 함정 방지, v1 F2' 재발 봉인).
+- `--batch`(Stage 1)와 상호배타 그룹.
+
+## 검증
+```
+python tools/verify_hangul_pages.py --inventory output/poc/fidelity3/hwpx/inventory.tsv \
+  --orig-root <hwpdocs> --rt-root output/poc/fidelity3/hwpx \
+  --status IR_DIFF,PASS --sample 45 --seed 42 -o ...
+
+# git HEAD=b086bd5a | 대상 45건
+=== 45건 / OK=44 COLLAPSE=1 (붕괴율 2%) ===  종료 코드 1
+```
+v3 임시 스크립트(`t3_v3.py`) 결과(1/45=2%)를 **정확히 재현**. 인벤토리·표본·종료코드·HEAD 기록 동작 확인.
+
+## 다음
+Stage 3 — 매뉴얼 + 임시 스크립트 대체 안내 + 최종 보고.

mydocs/working/task_m100_1560_stage3.md

@@ -0,0 +1,14 @@
+# Task #1560 Stage 3 완료보고서 — 매뉴얼 + 검증 + 최종 보고
+
+## 변경
+- 신규 `mydocs/manual/hangul_page_oracle.md` (사용법·판정·종료코드·한계·워크플로 연동).
+- 최종 보고서 `mydocs/report/task_m100_1560_report.md`.
+- 임시 스크립트(`output/poc/fidelity*/t3_*.py`)를 본 도구로 대체(매뉴얼에 명시).
+
+## 최종 검증
+- 배치/인벤토리 두 모드 동작, `--sample 45 --seed 42` 가 v3 결과(1/45=2%) 재현.
+- 알려진 붕괴 케이스(36384160·36387103) 검출, secCnt 수정 케이스(36382669) OK.
+- 종료 코드 1(게이트), git HEAD(b086bd5a) 기록.
+
+## 결론
+한글 페이지 오라클 정식화 완료. IR-blind 페이지 붕괴를 재현·게이트 가능하게 검출.