docs: v0.2.0 로드맵을 CLI → Document IR 로 전환

변경사항:
- 상류 rhwp 크레이트가 이미 동일 이름 rhwp 바이너리를 제공하여 CLI 중복 회피 목적으로 v0.2.0 스코프를 Document IR 도입으로 변경
- v0.2.0/ir.md 신규: Pydantic V2 + JSON Schema Draft 2020-12 기반 Document IR 설계 (Section/Paragraph/Table/InlineRun/Provenance, 본문/장식 분리, 스키마 버저닝)
- v0.2.0/cli.md 삭제
- design/v0.2.0/ir-design-research.md 신규: 7개 설계 의사결정(Block 유니온 확장·HTML 레이어·char 오프셋 단위·schema_version 타입·iter API·to_ir 캐싱·스키마 호스팅)을 수행자+검증자 2인 1조 병렬 리서치로 확정
- phase-2/3/4 버전 재매핑: IR 도입이 v0.2.0 으로 당겨지면서 후속 Phase 한 번씩 하향 (IR 확장 v0.3.0, view+RAG v0.4~0.6, writeback v0.7~1.0)
- roadmap/README.md 버전 계획 표 갱신 + CLI 폐기 경위 각주

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: DanMeon

docs/design/v0.2.0/ir-design-research.md

@@ -4,8 +4,8 @@ rhwp-python 의 버전별 로드맵. 완료된 단계는 참고 자료, 미래 
 
 ## 현재 상태
 
-- **v0.1.0** — Phase 1 Python 바인딩 분사 + PyPI 배포 준비 (인프라 완료, 릴리스 실행 예정)
-- **v0.2.0** — CLI 도입 (계획)
+- **v0.1.1** — sdist 크기 수정 완료, PyPI 배포 완료
+- **v0.2.0** — Document IR v1 (Pydantic + JSON Schema) 계획
 - **v0.3.0+** — Phase 2 이후 기능 (설계 단계)
 
 ## 버전 계획
@@ -14,11 +14,13 @@ rhwp-python 의 버전별 로드맵. 완료된 단계는 참고 자료, 미래 
 
 | 버전·단계 | 주제 | 문서 |
 |---|---|---|
-| v0.1.0 | rhwp-python 분사 + PyPI 런칭 | [v0.1.0/rhwp-python.md](v0.1.0/rhwp-python.md) |
-| v0.2.0 | CLI (`rhwp` 커맨드 + 서브커맨드) | [v0.2.0/cli.md](v0.2.0/cli.md) |
-| Phase 2 (v0.3~0.4) | 계층 JSON IR 스키마 | [phase-2.md](phase-2.md) |
-| Phase 3 (v0.5~0.7) | view 렌더러 + RAG 로더 확장 | [phase-3.md](phase-3.md) |
-| Phase 4 (v0.8~1.0) | JSON IR → HWP 역생성 | [phase-4.md](phase-4.md) |
+| v0.1.0 / v0.1.1 | rhwp-python 분사 + PyPI 런칭 (sdist 보정 포함) | [v0.1.0/rhwp-python.md](v0.1.0/rhwp-python.md) |
+| v0.2.0 | Document IR v1 — Pydantic 모델 + JSON Schema 공개 | [v0.2.0/ir.md](v0.2.0/ir.md) |
+| Phase 2 (v0.3.0) | IR 확장 (이미지·수식·각주·머리글꼬리·TocEntry·Field) | [phase-2.md](phase-2.md) |
+| Phase 3 (v0.4~0.6) | view 렌더러 + RAG 로더 확장 | [phase-3.md](phase-3.md) |
+| Phase 4 (v0.7~1.0) | JSON IR → HWP 역생성 | [phase-4.md](phase-4.md) |
+
+> CLI 는 v0.2.0 원안이었으나 상류 Rust 크레이트(`edwardkim/rhwp`)가 이미 동일 이름의 `rhwp` 바이너리를 제공하여 폐기. 상세 경위와 재검토 조건은 [v0.2.0/ir.md § 방향 전환 배경](v0.2.0/ir.md).
 
 ## 원칙
 
@@ -32,10 +34,10 @@ rhwp-python 의 버전별 로드맵. 완료된 단계는 참고 자료, 미래 
 
 | 버전 | 대략 목표 시점 |
 |---|---|
-| v0.1.0 | 2026 Q2 |
+| v0.1.0 / v0.1.1 | 2026 Q2 (배포 완료) |
 | v0.2.0 | 2026 Q2 ~ Q3 |
-| v0.3.0 ~ v0.4.0 | 2026 Q3 ~ Q4 |
-| v0.5.0 ~ v0.7.0 | 2027 |
+| v0.3.0 | 2026 Q3 ~ Q4 |
+| v0.4.0 ~ v0.6.0 | 2027 |
 | v1.0.0 | 2027+ |
 
 타임라인은 **유동적** — 상류 `edwardkim/rhwp` 진척과 커뮤니티 수요에 따라 변경.

docs/roadmap/README.md

@@ -1,62 +1,53 @@
-# Phase 2 — 계층 JSON IR 스키마
+# Phase 2 — Document IR 확장
 
-**대상 버전**: v0.3.0 ~ v0.4.0
-**선행 조건**: v0.1.x (Phase 1 바인딩) GA, v0.2.x (CLI) 안정
+**대상 버전**: v0.3.0
+**선행 조건**: v0.2.0 Document IR v1 (기본 스키마) GA — [v0.2.0/ir.md](v0.2.0/ir.md)
+
+## 포지셔닝 변경 안내
+
+Phase 2 원안은 "계층 JSON IR 스키마 도입 + 확장" (v0.3.0 ~ v0.4.0 두 릴리스) 이었으나, v0.2.0 의 CLI 계획이 폐기되면서 **IR 도입 자체를 v0.2.0 으로 당김**. Phase 2 는 이제 v0.2.0 기본 스키마 위의 **확장 타입** 만 다룬다.
+
+- **v0.2.0 (Phase 2 전) — 기본 IR**: Document / Section / Paragraph / Table / Cell / InlineRun / Provenance + JSON Schema v1.0
+- **v0.3.0 (Phase 2) — IR 확장**: 이미지 / 수식 / 각주 / 미주 / 머리글 / 꼬리말 / 목차항목 / 필드 + JSON Schema v1.1
 
 ## 목표
 
-HWP 문서를 구조화된 JSON (Intermediate Representation) 으로 추출해 RAG 파이프라인에서 **의미 단위**로 활용. 텍스트 추출만 가능했던 Phase 1 을 넘어 문서의 계층 구조를 유지.
-
-## 범위
-
-- 재귀 중첩 표 (`TableCell` 안의 또 다른 `Table`) 를 IR 노드로 재구성
-- `rowspan` / `colspan` 병합 셀 보존
-- 비의미 셀 (레이아웃용 빈 셀 등) 에 시맨틱 태그 부여 — RAG 가 노이즈로 필터링 가능
-- 문단·섹션·페이지 경계 보존
-
-## 예시 IR (초안)
-
-```json
-{
-  "type": "Document",
-  "metadata": { "source": "a.hwp", "page_count": 3 },
-  "sections": [
-    {
-      "type": "Section",
-      "blocks": [
-        { "type": "Paragraph", "text": "..." },
-        {
-          "type": "Table",
-          "rows": [
-            [
-              { "type": "Cell", "rowspan": 2, "colspan": 1, "blocks": [...] },
-              { "type": "Cell", "semantic": "placeholder" }
-            ]
-          ]
-        }
-      ]
-    }
-  ]
-}
-```
-
-## Python API (초안)
-
-```python
-doc = rhwp.parse("a.hwp")
-ir = doc.to_ir()              # Python dict (JSON-serializable)
-ir_json: str = doc.to_ir_json()
-```
-
-## 릴리스 분할
-
-| 버전 | 범위 |
-|---|---|
-| v0.3.0 | IR 기본 스키마 (Paragraph / Section / Table) |
-| v0.4.0 | IR 확장 (이미지 / 수식 / 각주 / 머리글꼬리) |
+v0.2.0 에서 확보한 RAG-친화적 기본 구조에 HWP 문서의 고유 의미 요소를 추가한다. 확장은 **후방 호환** 이 원칙 — 기존 소비자는 새 `Block.kind` 를 모르더라도 v0.2.0 시절 처리를 그대로 수행할 수 있어야 함 (unknown-kind graceful skip).
+
+## 추가되는 블록 타입
+
+### 일반 문서 요소 (DocLayNet 파생)
+
+- **`PictureBlock`** — 이미지. `ref_mode: Literal["placeholder" | "embedded" | "external"]` (Docling `ImageRefMode` 패턴), `mime_type`, `caption`. 바이너리는 v0.3.0 에서 `placeholder` (텍스트 치환) 기본값, 임베딩은 v0.4.0+
+- **`FormulaBlock`** — 수식. HWP 수식은 자체 기호 체계 — `raw: str` (원본) + `tex: str | None` (향후 변환) 이중 필드
+- **`FootnoteBlock` / `EndnoteBlock`** — 각주/미주. `ref_id`, `number`, `content: list[Block]` (본문 재귀)
+- **`ListItemBlock`** — 목록 항목. `level: int`, `marker: str`, `inlines`
+- **`CaptionBlock`** — 표/그림 캡션. `refers_to: str | None` (대상 블록 id)
+
+### HWP 고유 요소
+
+- **`TocEntryBlock`** — 목차 항목. `level: int`, `page_no: int | None`, `target_id: str | None`
+- **`FieldBlock`** — 상호참조/변수 필드. `kind: "cross_ref" | "date" | "page_no" | ...`, `cached_value: str`
+- **`RevisionMark`** — 변경 이력 마커. v0.3.0 스코프 여부 재평가 (상류 지원 상태 확인 필요)
+
+### Furniture 채움
+
+v0.2.0 에서 `furniture.page_headers`/`page_footers` 는 빈 리스트로 출고됐으나 v0.3.0 에서 실제 내용 채움. 스키마 변화 없음 — 값 채움만.
+
+## JSON Schema 변경
+
+- `schema_version`: `Literal["1.0"]` → `Literal["1.0", "1.1"]` 확장
+- `Block` discriminated union 에 새 멤버 추가
+- `$id` URL 은 동일 유지 (`hwp_ir_v1.json`) — `v1` major 안의 minor 추가
+- 별도 스냅샷: `hwp_ir_v1_1.json` 게시 (구 버전 소비자를 위해)
+
+## 릴리스 일정
+
+단일 릴리스 (v0.3.0) — 8개 신규 블록 타입을 한 번에 안정화. 개별 타입별로 릴리스를 쪼개면 소비자가 어떤 Block 멤버가 존재하는지 반복 확인해야 함.
 
 ## 미확정 이슈
 
-- IR 스키마를 Pydantic 모델로 노출할지 / dict 만 반환할지
-- JSON Schema 버전 관리 (`$schema` URL) 정책
-- 대용량 문서 스트리밍 IR (generator 기반 `iter_blocks()`)
+- **이미지 임베딩 전략** — `embedded` 모드 지원 여부. base64 라 IR JSON 크기가 수 MB 단위로 증가할 수 있음. Docling 은 `PictureRefMode.PLACEHOLDER` 기본값 채택 — 동일 기본값 권장
+- **수식 TeX 변환** — HWP 수식 → LaTeX 매핑. 상류 지원 확인 필요. 미지원 시 v0.3.0 은 `raw` 만, v0.4.0+ 에서 TeX 추가
+- **`FieldBlock.kind` 열거값** — HWP 필드 타입이 수십 개. 닫힌 `Literal` 로 시작하면 미지 필드에 대해 `ValidationError`. 대안: `kind: str` + `known_kind: FieldKind | None` 이중 필드
+- **중첩 Footnote 블록의 재귀 깊이** — 각주 내부에 표·그림 허용할 것인가? v0.3.0 초판은 단락 + 인라인만 허용하여 검증 부담 최소화

docs/roadmap/phase-2.md

@@ -1,38 +1,51 @@
-# Phase 3 — view 렌더러 + RAG 로더 확장
+# Phase 3 — view 렌더러 + RAG 프레임워크 통합
 
-**대상 버전**: v0.5.0 ~ v0.7.0
-**선행 조건**: Phase 2 IR 스키마 안정 (v0.4.x)
+**대상 버전**: v0.4.0 ~ v0.6.0
+**선행 조건**: Phase 2 IR 확장 (v0.3.0) 안정
+
+> 원안 대비 버전이 한 번씩 당겨짐 (v0.5~v0.7 → v0.4~v0.6) — v0.2.0 에서 IR 도입이 앞당겨지면서 후속 Phase 도 일괄 하향 이동.
 
 ## 목표
 
-IR 을 다른 포맷으로 렌더링하고, LangChain 외 RAG 프레임워크로 통합 확장.
+v0.2.0/v0.3.0 에서 확정된 IR 을 다른 포맷으로 렌더링(view) 하고, LangChain 외의 RAG 프레임워크와 통합한다. HtmlRAG (WWW 2025, arXiv:2411.02959) 등 최근 연구는 LLM 에 문서를 제공할 때 **구조를 보존하는 HTML** 이 평문화 대비 우수함을 보고하므로, view 변환 품질이 RAG 체감 성능과 직결된다.
 
 ## 범위
 
-### view 렌더러
+### view 렌더러 (v0.4.0)
+
+- `HwpDocument.to_markdown()` — IR → CommonMark + GFM 확장
+  - 표는 GFM `|a|b|` 형태. `rowspan`/`colspan` 이 있는 셀은 GFM 으로 표현 불가 → HTML 인라인으로 폴백
+  - 머리글·꼬리말은 YAML frontmatter (선택) 또는 주석 블록
+  - 각주/미주는 CommonMark footnote 확장
+  - 수식은 `$$ ... $$` (KaTeX 호환) — `FormulaBlock.tex` 가 있을 때만
+- `HwpDocument.to_html()` — IR → HTML5
+  - `<article>`, `<section>`, `<table>` 등 시맨틱 태그
+  - 접근성: `<caption>`, `<th scope>`, `aria-*` 기본 포함
+  - CSS 는 기본 미동봉, 별도 `to_html(include_css=True)` 옵션
+  - 이미지 처리: `Picture.ref_mode` 를 따름 (`placeholder` → `<img alt>`, `embedded` → base64 `src=`, `external` → 외부 파일 + 경로 반환)
 
-- `to_markdown()` — IR → CommonMark
-  - 표는 GFM `|a|b|` 형태, 중첩 표는 GFM fenced block 또는 HTML 인라인
-  - 머리글·꼬리글은 frontmatter 또는 주석 처리
-- `to_html()` — IR → HTML
-  - minimal CSS, 접근성 고려 (semantic tags)
-  - 이미지는 base64 inline 또는 외부 파일 참조 선택
+HTML 은 `TableBlock.html` 과 별개 — TableBlock 수준 HTML 은 표 하나의 HTML 조각 (RAG 주입용), 문서 전체 `to_html()` 은 완전한 HTML5 문서 (브라우저 표시용).
 
-### RAG 통합 확장
+### RAG 통합 확장 (v0.5.0 ~ v0.6.0)
 
-- `rhwp.integrations.llamaindex.HwpReader` — LlamaIndex `BaseReader` 구현
-- (선택) `rhwp.integrations.haystack.HwpConverter` — Haystack 2.x `Converter`
+- **v0.5.0** — `rhwp.integrations.llamaindex.HwpReader` (LlamaIndex `BaseReader` 구현)
+  - `load_data()` / `lazy_load_data()` 동기 + async
+  - IR → `Document`/`TextNode` 변환, `parent_id`/`prev`/`next` 링크 보존 (연구 결과 § 1 참조)
+  - 섹션·단락을 `NodeRelationship.PARENT/CHILD` 로 표현 → `AutoMergingRetriever` 호환
+- **v0.6.0** — `rhwp.integrations.haystack.HwpConverter` (Haystack 2.x `Converter`) — **커뮤니티 수요 확인 후**
+  - Haystack `Document` 로 변환, `meta` 에 섹션 경계 힌트 저장
 
 ## 릴리스 분할
 
 | 버전 | 범위 |
 |---|---|
-| v0.5.0 | `to_markdown()` / `to_html()` view |
-| v0.6.0 | LlamaIndex 통합 |
-| v0.7.0 | (선택) Haystack 통합 — 커뮤니티 수요 확인 후 |
+| v0.4.0 | `to_markdown()` / `to_html()` view — 표 rowspan/colspan HTML 인라인 처리 포함 |
+| v0.5.0 | LlamaIndex 통합 (`HwpReader`, AutoMergingRetriever 호환 node 트리) |
+| v0.6.0 | Haystack 통합 (커뮤니티 수요 확인 후) + LangChain 로더의 IR 직접 활용 (breadcrumb 자동 삽입 등 Anthropic Contextual Retrieval 스타일) |
 
 ## 미확정 이슈
 
-- Markdown 방언 (CommonMark vs GFM vs Pandoc) — 기본 GFM, 확장 옵션 플래그
-- HTML 출력의 CSS 동봉 여부 — 기본 미동봉, 별도 함수로 제공
-- LlamaIndex 가 IR 스키마를 그대로 소비 가능할지, 혹은 LlamaIndex-native 타입으로 변환 레이어 필요할지
+- **Markdown 방언** — CommonMark / GFM / Pandoc Markdown / MyST. 기본값 GFM (표·각주 지원). Pandoc-compatible 플래그는 별도 옵션
+- **HTML 출력의 CSS 동봉 여부** — 기본 미동봉, `include_css: bool` 또는 별도 `style_bundle()` 함수
+- **LlamaIndex 가 IR 스키마를 그대로 소비 가능한가** — 현재 LlamaIndex `BaseNode` 는 자유형 `metadata: dict`. 완전 호환은 불가 (IR 의 Pydantic 타입 손실). 변환 레이어 필수 — 메타데이터에 `rhwp.ir.json` 키로 원본 IR 직렬화 보존하여 라운드트립 가능하게 설계
+- **Contextual Retrieval 자동 지원 여부** — Anthropic 기법은 LLM 호출 비용 유발. rhwp-python 이 이를 내장하면 비용이 사용자에게 불투명 → **미내장**. 대신 `doc.breadcrumb(node_id)` 헬퍼로 사용자가 수동 결합 가능하게 설계

docs/roadmap/phase-3.md

@@ -1,7 +1,7 @@
 # Phase 4 — JSON IR → HWP 역생성
 
-**대상 버전**: v1.0.0 (안정화 + writeback 지원)
-**선행 조건**: rhwp Rust 코어의 HWP writer API 안정
+**대상 버전**: v0.7.0 ~ v1.0.0 (안정화 + writeback 지원)
+**선행 조건**: Phase 3 (v0.6.0 까지) GA + rhwp Rust 코어의 HWP writer API 안정
 
 ## 목표
 
@@ -25,9 +25,10 @@ Phase 4 는 rhwp **Rust 코어의 쓰기 API 성숙도** 에 좌우됨. 업스
 
 | 버전 | 범위 |
 |---|---|
-| v0.8.0 (예상) | HWPX writeback baseline (단순 문서 왕복) |
-| v0.9.0 (예상) | HWPX writeback 확장 (표·이미지·수식) |
-| v1.0.0 | HWP5 writeback + API 안정 선언 |
+| v0.7.0 | HWPX writeback baseline (단순 문서 왕복) |
+| v0.8.0 | HWPX writeback 확장 (표·이미지·수식) |
+| v0.9.0 | HWP5 writeback baseline |
+| v1.0.0 | HWP5 writeback 확장 + API 안정 선언 |
 
 ## 1.0 안정화 기준