add files

docs/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,121 @@
+# Implementation Phase Plan
+
+이 문서는 PDFtoMD 구현 전체를 phase 단위로 나눈 실행 계획입니다. 각 phase의 상세 실행 티켓은 `phases/{phase}/stepN.md`에 둡니다.
+
+## Planning Principles
+- 1차 목표는 Windows native, local-first CLI/library 변환 엔진입니다.
+- PyQt UI는 core API와 CLI가 안정화된 뒤 thin client로 구현합니다.
+- 각 phase는 이전 phase의 산출물을 전제로 하며, phase 안의 step은 하나의 agent가 독립 실행할 수 있어야 합니다.
+- 구현 phase는 TDD를 기본으로 합니다.
+- Parser 책임 경계는 유지합니다: Marker는 문서 구조, Nougat은 수식, PyMuPDF는 사전 분석과 저수준 PDF 작업입니다.
+
+## Phase Overview
+
+| Phase | Goal | Primary Output | Depends On |
+| --- | --- | --- | --- |
+| 0. Harness foundation | 실행 가능한 Harness 기반과 최소 품질 토대 | sample metadata, core models, preanalysis contract, quality gates | current docs |
+| 1. Core runtime contracts | 변환 옵션, 입력 정규화, 출력 bundle 계약, path/cache 정책 | stable API contracts and tests | Phase 0 |
+| 2. Marker adapter | Marker 실행과 block normalization 경계 구현 | Marker adapter, OCR handoff, block mapping tests | Phase 1 |
+| 3. Formula pipeline | Nougat formula-only handoff와 LaTeX 검증/fallback | formula detector, Nougat adapter, repair/fallback tests | Phase 2 |
+| 4. Semantic enrichment | 문단, reading order, header/footer, 참조 관계 보강 | enrichment pipeline and reference index | Phase 2, 3 |
+| 5. Markdown rendering and assets | Markdown chunk, table, figure, asset writer 구현 | deterministic Markdown bundle writer | Phase 4 |
+| 6. CLI runtime and resume | CLI, progress/logging, runtime, OOM, resume 구현 | user-facing local CLI | Phase 5 |
+| 7. MVP quality hardening | samples 기반 end-to-end 품질 검증과 회귀 안정화 | MVP acceptance suite | Phase 6 |
+| 8. Release docs and packaging | 설치, 모델 cache, offline, release 문서 정리 | local release-ready docs/scripts | Phase 7 |
+| 9. PyQt thin client | CLI/library를 호출하는 Windows UI | optional PyQt UI | Phase 8 |
+
+## Phase 0: Harness Foundation
+- Directory: `phases/0-harness-foundation`
+- Purpose: 구현 전 공통 모델, sample metadata, PyMuPDF pre-analysis contract, Markdown quality gates를 만든다.
+- Steps:
+  1. `sample-metadata-contract`
+  2. `core-package-skeleton`
+  3. `page-preanalysis-contract`
+  4. `markdown-quality-gates`
+
+## Phase 1: Core Runtime Contracts
+- Directory: `phases/1-core-runtime-contracts`
+- Purpose: parser 실행 전에 모든 phase가 공유할 입력, 옵션, path, output contract를 안정화한다.
+- Steps:
+  1. `input-normalization-slug`
+  2. `conversion-options-config`
+  3. `output-bundle-contract`
+  4. `runtime-cache-policy`
+
+## Phase 2: Marker Adapter
+- Directory: `phases/2-marker-adapter`
+- Purpose: Marker를 primary parser로 연결하고, OCR/page plan과 Marker 구조화 출력을 내부 block model로 매핑한다.
+- Steps:
+  1. `marker-invocation-adapter`
+  2. `ocr-plan-handoff`
+  3. `marker-block-normalization`
+  4. `marker-failure-reporting`
+
+## Phase 3: Formula Pipeline
+- Directory: `phases/3-formula-pipeline`
+- Purpose: Nougat을 formula-only parser로 연결하고, 수식 delimiter, numbering, fallback을 안정화한다.
+- Steps:
+  1. `formula-block-detection`
+  2. `nougat-command-adapter`
+  3. `latex-validation-repair`
+  4. `formula-reference-links`
+
+## Phase 4: Semantic Enrichment
+- Directory: `phases/4-semantic-enrichment`
+- Purpose: Marker block을 Markdown에 적합한 논리 구조로 보강한다.
+- Steps:
+  1. `reading-order-checks`
+  2. `paragraph-stitching`
+  3. `header-footer-filtering`
+  4. `reference-indexing`
+
+## Phase 5: Markdown Rendering And Assets
+- Directory: `phases/5-markdown-rendering-assets`
+- Purpose: chunked Markdown bundle과 image/table asset 출력을 결정적으로 생성한다.
+- Steps:
+  1. `markdown-block-renderer`
+  2. `table-renderer-fallbacks`
+  3. `figure-asset-writer`
+  4. `chunk-renderer`
+
+## Phase 6: CLI Runtime And Resume
+- Directory: `phases/6-cli-runtime-resume`
+- Purpose: 변환 엔진을 사용자가 실행할 수 있는 CLI로 묶고 runtime/recovery 정책을 구현한다.
+- Steps:
+  1. `cli-entrypoint-options`
+  2. `progress-logging`
+  3. `resume-state`
+  4. `device-oom-policy`
+  5. `model-cache-offline`
+
+## Phase 7: MVP Quality Hardening
+- Directory: `phases/7-mvp-quality-hardening`
+- Purpose: sample corpus 기준으로 end-to-end 품질을 고정하고 MVP 수락 기준을 통과시킨다.
+- Steps:
+  1. `sample-smoke-conversions`
+  2. `quality-metrics-report`
+  3. `regression-thresholds`
+  4. `mvp-fix-sweep`
+
+## Phase 8: Release Docs And Packaging
+- Directory: `phases/8-release-docs-packaging`
+- Purpose: 개인용 로컬 실행 기준으로 설치, 모델 다운로드, offline 실행, release checklist를 정리한다.
+- Steps:
+  1. `readme-usage-flow`
+  2. `environment-bootstrap-docs`
+  3. `license-checkpoint`
+  4. `release-checklist`
+
+## Phase 9: PyQt Thin Client
+- Directory: `phases/9-pyqt-thin-client`
+- Purpose: core engine을 중복 구현하지 않는 Windows UI를 만든다.
+- Steps:
+  1. `ui-api-contract`
+  2. `pyqt-shell`
+  3. `ui-progress-resume`
+  4. `ui-packaging-notes`
+
+## Deferred Backlog
+- Hosted conversion API는 현재 phase plan에 포함하지 않습니다.
+- LLM correction mode는 기본 경로가 아니며, MVP 이후 별도 ADR과 phase 계획이 필요합니다.
+- 배포/상업적 사용이 현실화되면 Marker GPL과 model weight license를 별도 법적 검토 대상으로 둡니다.