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