PDFToMD/docs/IMPLEMENTATION_PLAN.md

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를 별도 법적 검토 대상으로 둡니다.