rhwp-fidelity-compare

name	rhwp-fidelity-compare
description	한컴이 내보낸 공식 PDF와 rhwp export-svg를 쪽별로 대조합니다. tools/fidelity_compare의 페이지 시트·픽셀 diff% 랭킹(최악 쪽 우선)·text-report.tsv 문자 멀티셋(소실/과잉/치환)을 후보 검출로 읽고, --font-style·로컬 face 별칭·두부 오염·RHWP_FONT_PATH_DIR·provenance를 닫습니다. 트리거 — 사용자가 "한컴 PDF와 비교", "공식 출력 기준 대조", "fidelity_compare 돌려줘", "한컴이 뽑은 PDF랑 rhwp가 같은지"를 요청할 때. 독립 한컴 PDF가 있을 때만. 자기 일관성 render-diff나 버그 헌팅 여정과는 다른 축이다.

rhwp-fidelity-compare — 한컴 기준 PDF 대조 Skill

에이전트가 한컴이 내보낸 공식 PDF 와 rhwp export-svg 를 쪽별로 대조할 때 쓰는 규약이다. 코어는 이미 있는 tools/fidelity_compare/fidelity_compare.py 와 rhwp export-svg 뿐이다.

이 스킬은 실 에이전트 경로다. gym 이 아니고, 새 CLI 명령을 발명하지 않는다. rhwp-visual-regression(자기 일관성 render-diff) 과 bug-hunter(여정 방법론) 를 이 폴더에서 재작성하지 않는다.

픽셀 diff% 와 문자 멀티셋은 후보 검출이지 절대 판정이 아니다. 최종 시각 판정은 유지자/작업지시자가 visual_verification_governance.md 를 따라 내린다.

상세는 references/ 를 단계별로 연다. SKILL.md 는 인덱스와 정지 규칙만 담는다.

정본:

• tools/fidelity_compare/README.md
• mydocs/manual/verification/visual_verification_governance.md

언제 쓰는가 / 언제 쓰지 않는가

손에 있는 것	정직한 도구	이 스킬
한컴 도구·버전·경로가 기록된 독립 공식 PDF + 원본 HWP/HWPX	tools/fidelity_compare	여기
편집/변환 전후 두 HWP, 공식 PDF 없음	rhwp render-diff	쓰지 않음 → rhwp-visual-regression
같은 파일을 두 번 렌더해 결정성만 본다	render-diff A A	쓰지 않음
원인 미확정 실사용 결함을 여정으로 좁힌다	bug-hunter playbook	후보 검출만 넘긴다
gym pack / 채점 / 리더보드	gym 도구	금지

독립 한컴 PDF 가 없으면 이 하네스는 정직하지 않다. 샘플 옆의 동반 PDF 는 도구·버전·출처를 확인하기 전에는 최종 기준으로 승격하지 않는다.

바이너리·venv

새 fidelity-* 하위명령은 없다. 비교는 저장소 로컬 venv 의 Python 이 기존 하네스를 호출한다.

# 저장소 루트, 최초 1회. 시스템 pip / --break-system-packages 금지
python3.12 -m venv venv
venv/bin/python -m pip install pypdf pypdfium2 pillow

# Windows
py -3.12 -m venv venv
venv\Scripts\python.exe -m pip install pypdf pypdfium2 pillow

• POSIX: venv/bin/python
• Windows: venv\Scripts\python.exe
• Chrome/Chromium 은 --text-only 가 아닐 때 필수
• --text-only 는 pypdf 만 있으면 되고 Chrome·pypdfium2 를 요구하지 않는다
• 하네스 SVG 는 기본 --font-style (로컬 face 별칭, embed 아님)

실행 파일 자동 탐색: rhwp 는 target/release-test → target/release → PATH. Chrome 은 플랫폼 기본 경로. 안 맞으면 RHWP_BIN / CHROME_BIN.

수정 직후 비교 전 최신 바이너리:

cargo build --profile release-test --target-dir target/pr-review
RHWP_BIN=target/pr-review/release-test/rhwp \
  venv/bin/python tools/fidelity_compare/fidelity_compare.py plan 0 9 \
  --out-dir /tmp/rhwp-fidelity-plan

이 cargo build 는 시각 대조용 컴파일 전용 이다. Rust 테스트를 대신하지 않는다.

사다리 (강제 순회 아님)

독립 한컴 PDF 가 있는가
  │
  ├─ 없음 ──▶ rhwp-visual-regression (render-diff). 여기서 멈추지 말고 스킬을 갈아탄다 (F01)
  │
  ├─ 있음, 텍스트 후보만 먼저 ──▶ --text-only [--export-all-svg] [--layout-ledger] (F02)
  │     text-report.tsv 소실/과잉/치환
  │     page-count-ledger.tsv 쪽수 불일치는 후보
  │
  ├─ 픽셀 시트 ──▶ (기본 모드) cmp-pNNN.png + report.tsv 최악 쪽 우선 (F03)
  │     Chrome 필수. 없으면 --text-only 로 내려가거나 정지 (F10)
  │
  ├─ 글꼴 두부 의심 ──▶ --font-style · RHWP_FONT_PATH_DIR · svg-glyph-risk-report.tsv (F04)
  │
  └─ 사람/유지자 시트 감사 ──▶ 실질 결함만 이슈 승격 (F05)
        자동 diff% 통과는 최종 판정이 아니다

질문이 이미 답이면 다음 단으로 내려가지 않는다. 정지 조건은 27_exception_catalog.md 와 아래 표.

요청 → 명령

사용자 요청	명령	레퍼런스
한컴 PDF 랑 같은지	등록키 또는 --source+--reference-pdf+--label	01_when_to_use.md
일단 글자만	--text-only --export-all-svg	06_text_report.md
최악 쪽부터 보자	기본 모드 → report.tsv 내림차순	05_pixel_ranking.md
글자가 □ 로 나온다	--font-style 기본인지, RHWP_FONT_PATH_DIR	07·09·17
윈도에서 돌려	venv\Scripts\python.exe, break-system-packages 금지	03_windows.md
임의 HWP+PDF 쌍	--source --reference-pdf --label --reference-grade	19_direct_pair.md
Chrome 없다	--text-only 또는 정지 F10	13_missing_chrome.md
암호화 PDF	정지 F13. 암호 우회 CLI 발명 금지	16_encrypted_pdf.md

등록 키: plan manual bunjang korexam math eng. 키는 ASCII 글롭이다. 한글 argv 는 배경 셸에서 cp949 로 깨질 수 있다.

# 등록 fixture
venv/bin/python tools/fidelity_compare/fidelity_compare.py plan 0 34 \
  --out-dir /tmp/rhwp-fidelity-plan

# 임의 쌍, 텍스트만
RHWP_BIN=target/release-test/rhwp \
venv/bin/python tools/fidelity_compare/fidelity_compare.py 0 214 \
  --source 'samples/입력.hwp' \
  --reference-pdf 'pdf/한컴-기준.pdf' \
  --label issue-3738-hwp \
  --reference-grade '한컴 2020 기준 PDF' \
  --text-only --export-all-svg --layout-ledger \
  --out-dir /tmp/rhwp-fidelity-issue-3738

Windows:

venv\Scripts\python.exe tools\fidelity_compare\fidelity_compare.py plan 0 9 `
  --out-dir $env:TEMP\rhwp-fidelity-plan

--out-dir 은 지정한 디렉터리 자체를 산출 루트로 쓴다. 생략하면 output/fidelity/<키>/. worktree 를 깨끗이 두려면 저장소 밖 경로를 쓴다.

산출물 (읽는 법)

파일	의미	판정 권위
cmp-pNNN.png	기준 PDF ‖ rhwp 렌더 쪽별 비교 시트	사람 눈
report.tsv	page, diff%, note — 최악 쪽 우선 정렬	후보 순위
text-report.tsv	쪽별 문자 멀티셋. reference_only=소실, svg_only=과잉, 둘 다=치환	후보
provenance.tsv	원본·기준 PDF 경로와 기준 등급	재현 기록
run-state.tsv	requested/completed/missing. 누락이면 종료 코드 ≠ 0	실행 완전성
page-count-ledger.tsv	PDF / SVG / render-tree 쪽수	후보. 전역 page-break 수정 근거 아님
svg-glyph-risk-report.tsv	SVG raw PUA / U+FFFD	두부 후보 (PDF 추출과 독립)

그 외 owner-shift · table-fragment · layout-candidates 는 20_outputs.md. 모두 candidate 다.

text-report.tsv 헤더:

page	reference_only	svg_only	reference_only_chars	svg_only_chars	note

공백·순서를 무시하고 NFC 멀티셋을 비교한다. PDF 텍스트층에 없는 path 글리프, 숨김 텍스트, 추출기 매핑 차이는 최종 시각 판정을 대신하지 않는다.

글꼴·두부

하네스는 rhwp export-svg --font-style 을 기본으로 쓴다. 원 문서 legacy face 와 설치된 family/full name 이 달라도 @font-face src: local(...) 별칭을 Chrome 이 쓰게 해서, 한양중고딕·휴먼명조가 설치돼 있는데도 비교 PNG 가 □ 로 채워지는 하네스 오염 을 막는다.

• 글꼴 바이너리를 SVG 에 embed 하지 않는다 (기본 모드)
• RHWP_FONT_PATH_DIR 로 라이선스 있는 로컬 글꼴 디렉터리를 넘긴다
• 휴먼명조/휴먼고딕의 HMKMM/HMKMG 처럼 EBDT local face 가 Chrome 에서 .notdef 를 그리는 경우, 고정 좌표를 유지한 채 outline 명조·고딕을 먼저 고른다. HY신명조는 원 face 우선순위를 보존한다
• 시트가 온통 두부면 문서 결함이 아니라 하네스 오염 (F14). 글꼴을 고치고 다시 돌린 뒤에야 후보를 읽는다

provenance (필수 기록)

한컴 출력은 도구·버전·출력 경로·폰트에 따라 달라진다. 재현 기록에 남긴다.

필드	예
한컴 도구	한글 2022 / 2024 / 한컴오피스
버전	12.0.0.xxxx
내보내기 경로	파일→PDF로 저장 / 인쇄→PDF / pdf/ 보존본
글꼴	설치 목록 또는 RHWP_FONT_PATH_DIR
원본 경로	samples/....hwp
오라클 PDF 경로	pdf/....-2022.pdf
기준 등급	한컴 2022 기준 PDF / 참고 PDF (미확인)

provenance.tsv 는 role, path, grade 세 열이다. --reference-grade 는 direct pair 에서만 쓴다. bunjang 동반 PDF 는 등급이 "참고" 이며 별도 확인 전에는 최종 기준으로 쓰지 않는다.

정지 규칙

ID	언제	행동
F01	독립 한컴 PDF 없음	rhwp-visual-regression 으로 인계. 가짜 기준 PDF 를 만들지 않음
F02	--text-only 로 후보만 모음	시트 없이 원장만. 결함 확정 금지
F03	report.tsv 상위 쪽	최악부터 시트를 눈으로 감사. diff% 절대값으로 merge 하지 않음
F04	PUA / U+FFFD / □	글꼴 별칭·경로를 먼저. 문서 결함으로 바로 승격 금지
F05	시트 감사 끝	실질 결함만 이슈. 최종 판정은 유지자
F06	gym / 새 CLI 요청	거절. 이 스킬은 기존 하네스만
F07	visual-regression 스킬을 여기서 고침	거절. 이웃 스킬 재작성 금지
F08	bug-hunter 여정을 여기서 다시 씀	거절. 후보만 넘긴다
F09	venv 없음 / 시스템 pip	정지. --break-system-packages 금지 (F15)
F10	Chrome 없음, --text-only 아님	--text-only 로 내리거나 정지. Chrome 설치를 강제 스크립트하지 않음
F11	쪽수 불일치	page-count-ledger.tsv 를 후보로 기록. 전역 page-break 패치 금지
F12	run-state incomplete	누락 쪽을 먼저. 부분 랭킹을 전수로 포장하지 않음
F13	암호화 PDF	정지. 암호 제거 CLI / 우회 발명 금지
F14	시트가 두부 가득	하네스 오염. 글꼴을 고치고 재실행
F15	--break-system-packages	거절. 저장소 venv/ 만
F16	질문이 이미 답	다음 단 금지
F17	samples/ 동반 PDF 를 공식 기준으로 승격	도구·버전 확인 전 금지
F18	원본 HWP 를 비교 중 덮어씀	금지. --out-dir 만 기록

금지 기본값

• 새 비교 CLI (fidelity-diff, pdf-compare, hangul-diff) 발명
• gym pack / gym 과제 / 채점기 작성
• rhwp-visual-regression / bug-hunter 스킬 재작성
• DocumentCore / 렌더러 구현을 이 PR 에서 고침
• 시스템 Python 에 pip install, --break-system-packages
• 암호화 PDF 암호 우회
• diff% 0 을 "한컴과 동일" 으로 발표
• 두부 시트를 문서 회귀로 오진
• 원본을 비교 과정에서 덮어쓰기

인계

• 공식 PDF 없이 전후 레이아웃만 → rhwp-visual-regression
• 원인 미확정 실사용 여정 → bug-hunter (이 하네스 원장을 입력으로)
• 미지 문서 파악만 → rhwp-doc-triage (비교하지 않음)
• 편집 자체 → rhwp-safe-edit / rhwp-form-fill (끝난 뒤 공식 PDF 가 있으면 여기로)
• CLI 일반 → rhwp-cli (export-svg 단건)

상세: 26_handoff.md

예외 경로 (짧게)

예외	증상	처방
Chrome 없음	Chrome/Chromium을 찾을 수 없습니다 exit 2	CHROME_BIN 또는 --text-only (F10)
venv 없음	pypdf/pypdfium2 ImportError exit 2	저장소 venv 재생성 (F09)
쪽수 불일치	ledger 의 PDF≠SVG	후보. 전역 패치 금지 (F11)
암호화 PDF	pypdf/pypdfium2 암호 예외	정지 (F13)
두부 하네스	비교 PNG 가 □ 투성이	RHWP_FONT_PATH_DIR + --font-style 재실행 (F14)

레퍼런스 목차

1. 00_tree.md — 판단 트리
2. 01_when_to_use.md — 독립 PDF 가 있을 때만
3. 02_setup_venv.md — venv · pypdf · pillow
4. 03_windows.md — venv\Scripts\python.exe
5. 04_page_sheets.md — cmp-pNNN.png
6. 05_pixel_ranking.md — 최악 쪽 우선
7. 06_text_report.md — 소실/과잉/치환
8. 07_font_style.md — --font-style
9. 08_local_face_aliases.md — local() 별칭
10. 09_tofu.md — PUA · U+FFFD · □
11. 10_font_path_dir.md — RHWP_FONT_PATH_DIR
12. 11_provenance.md — 도구·버전·경로·글꼴
13. 12_visual_verdict.md — 유지자 판정
14. 13_missing_chrome.md — Chrome 부재
15. 14_missing_venv.md — venv 부재
16. 15_page_count_mismatch.md — 쪽수
17. 16_encrypted_pdf.md — 암호화 PDF

예제: examples/. 기계 가독 픽스처: fixtures/. 처리 결과: mydocs/working/agent_fidelity_compare.md

권위

• tools/fidelity_compare/README.md
• mydocs/manual/verification/visual_verification_governance.md
• mydocs/manual/verification/hangul_pdf_baseline.md
• rhwp export-svg — 이미 있는 명령. 이 스킬이 발명하지 않음
• 이슈: #5329