PDFToMD/docs/Sprints/SPRINT2CONTRACT.md

# Sprint 2 Contract: Paths, Input Discovery, And Overwrite Planning

Status: Completed
Last updated: 2026-05-07

## Objective

Implement deterministic input discovery and output path planning before any PDF conversion logic exists.

Sprint 2 must establish:

- A project-owned path planning module for local PDF inputs.
- Deterministic discovery for a single PDF, a directory, and optional recursive directory traversal.
- Deterministic planned output paths for Markdown, assets, metadata JSON, quality report, and optional raw MinerU output.
- Preflight overwrite conflict detection that prevents accidental replacement unless overwrite is explicitly allowed.
- Fast unit tests using generated temporary files, including non-ASCII filenames.

Sprint 2 is path planning only. It must not run MinerU, parse PDFs, write conversion outputs, normalize Markdown, create metadata content, or add the real `convert` command behavior.

## Current Precondition

Sprint 1 is complete:

- `uv` is installed per-user at `C:\Users\user\.local\bin`.
- `pyproject.toml`, `uv.lock`, the `pdf2md` package, CLI placeholder, and fast pytest loop exist.
- `uv sync` and `uv run pytest` passed.

If a new shell cannot find `uv`, prepend `C:\Users\user\.local\bin` to PATH for verification commands and record that in `PROGRESS.md`.

## Touched Surfaces

Allowed:

- `src/pdf2md/paths.py`
- `src/pdf2md/conversion.py` only for a minimal type boundary if path planning cannot be tested cleanly without it
- `src/pdf2md/cli.py` only if a minimal parser hook is needed for path-planning tests; do not expose working conversion behavior
- `tests/test_paths.py` or `tests/unit/test_paths.py`
- `tests/test_cli.py` only for path-planning parser coverage if `cli.py` changes
- `README.md` only if setup/test instructions need a small update
- `PLAN.md` only for current-goal coordination updates required by the shared agent workflow
- `PROGRESS.md`
- `docs/V1IMPLEMENTATIONPLAN.md` only if sequencing or constraints need adjustment
- `docs/Sprints/SPRINT2CONTRACT.md`

Not allowed:

- `src/pdf2md/mineru_adapter.py`
- `src/pdf2md/ir.py`
- `src/pdf2md/markdown.py`
- `src/pdf2md/metadata.py`
- `src/pdf2md/quality.py`
- `src/pdf2md/report.py`
- `src/pdf2md/doctor.py`
- `scripts/`
- Any real MinerU invocation
- Any model download or install script
- Any file parsing beyond local filesystem path and extension checks
- Any conversion output writing beyond temporary files created by tests
- Any committed file under `samples/`

## Expected Outputs

Sprint 2 should produce:

1. Input discovery
   - Accept a local path that is either a PDF file or a directory.
   - Treat `.pdf` extension matching as case-insensitive.
   - Reject a non-existent path with a clear project-owned error.
   - Reject a non-PDF file with a clear project-owned error.
   - Reject a directory with no discovered PDFs with a clear project-owned error.
   - Discover only direct child PDFs for directory input unless recursive traversal is requested.
   - Discover nested PDFs only when recursive traversal is requested.
   - Return discovered PDFs in a deterministic order.

2. Output path plan
   - For each discovered PDF, plan:
     - Markdown path: `<output-root>/<relative-parent>/<stem>.md`.
     - Assets directory: `<output-root>/<relative-parent>/<stem>.assets`.
     - Metadata path when metadata is enabled: `<output-root>/<relative-parent>/<stem>.metadata.json`.
     - Quality report path: `<output-root>/<relative-parent>/<stem>.report.md`.
     - Raw MinerU directory when raw output is kept: `<output-root>/<relative-parent>/<stem>.raw`.
   - For a single PDF input, `relative-parent` is empty unless the implementation has a tested reason to preserve more context.
   - For recursive directory input, preserve the source-relative subdirectory under the output root to avoid filename collisions.
   - Keep planned paths local filesystem paths. Do not introduce URI, URL, cloud, or remote storage handling.

3. Overwrite preflight
   - Detect existing planned file or directory outputs before conversion writes occur.
   - Report all detected conflicts in one project-owned error instead of failing on the first conflict.
   - Allow conflicts only when overwrite is explicitly enabled.
   - Do not delete or replace files in Sprint 2.

4. Tests
   - Unit tests for single PDF discovery.
   - Unit tests for non-recursive directory discovery.
   - Unit tests for recursive directory discovery.
   - Unit tests for deterministic ordering.
   - Unit tests for non-ASCII filenames, including Korean filenames, using temporary files.
   - Unit tests for invalid input errors.
   - Unit tests for planned Markdown, assets, metadata, report, and raw output paths.
   - Unit tests for overwrite conflict detection.

5. Handoff
   - `PROGRESS.md` records changed files, commands run, tests passed or blocked, known failures, residual risks, and next action.

## Non-Goals

- Do not implement PDF conversion.
- Do not implement conversion orchestration.
- Do not implement the MinerU adapter.
- Do not run MinerU.
- Do not install MinerU 3.1.0.
- Do not download MinerU models.
- Do not parse PDF contents.
- Do not compute source SHA-256.
- Do not implement Markdown normalization.
- Do not implement metadata JSON content.
- Do not implement `.report.md` content.
- Do not implement `pdf2md convert` as a working command.
- Do not implement `pdf2md doctor`.
- Do not add runtime engine selection.
- Do not add alternate conversion engines.
- Do not add cloud, remote API, router, HTTP client backend, or remote OpenAI-compatible backend support.

## Work Packages

### WP2.1: Path Planning Types And Errors

Owner:

- `feature-generator-agent`

Actions:

- Add the smallest project-owned types needed to represent discovered inputs, planned outputs, and overwrite conflicts.
- Add clear project-owned exceptions or error result types for invalid inputs and conflicts.
- Avoid public API promises beyond what Sprint 2 tests verify.

Output:

- Path planning can be tested without converter execution.

### WP2.2: Input Discovery

Owner:

- `feature-generator-agent`

Actions:

- Implement single PDF and directory discovery.
- Require explicit recursive mode for subdirectory traversal.
- Sort results deterministically.
- Preserve local `Path` objects rather than converting to strings early.

Output:

- Discovery behavior matches PRD directory and recursive requirements.

### WP2.3: Output Planning

Owner:

- `feature-generator-agent`

Actions:

- Plan Markdown, assets, metadata, report, and optional raw output paths.
- Preserve relative subdirectories for recursive directory input.
- Keep all planned outputs under the requested output root.

Output:

- Later conversion code can write outputs without rediscovering naming rules.

### WP2.4: Overwrite Conflict Detection

Owner:

- `feature-generator-agent`

Actions:

- Check whether any planned output already exists.
- Return or raise a structured conflict list when overwrite is not enabled.
- Permit the plan when overwrite is enabled without deleting anything.

Output:

- Existing user files are protected before conversion starts.

### WP2.5: Independent Evaluation

Owner:

- `evaluation-agent`

Actions:

- Review the completed path planning implementation against this contract.
- Verify no conversion behavior, MinerU execution, remote runtime path, or alternate engine was added.
- Verify `samples/` remains untracked and unstaged.
- Verify tests use temporary files, not committed sample PDFs.

Output:

- PASS/FAIL notes with any missing acceptance criteria.

## Verification Checks

Required:

- `git status --short` before staging confirms `samples/` remains untracked.
- `uv --version` is run and result is recorded.
- `uv sync` passes.
- `uv run pytest` passes.
- Targeted path planning tests pass.
- Tests do not require MinerU, CUDA, GPU, model files, `samples/`, or network.
- No real MinerU dependency is required for default tests.
- No model downloads occur.
- No network calls are required.
- No candidate engine comparison is reintroduced.
- No conversion behavior is implemented.
- No output files are written outside temporary test directories.
- `git diff --check` passes.

Recommended:

- Use temporary directories for all filesystem tests.
- Include Windows-relevant path behavior without hard-coding Windows-only separators in assertions.
- Use `requirements-guard-agent` if path planning reveals a contradiction in PRD or architecture wording.

## Hard Failure Criteria

Sprint 2 fails and must stop for a user decision if any of these are true:

- Directory conversion descends recursively without explicit recursive intent.
- Existing planned outputs can be overwritten without explicit overwrite intent.
- Planned output paths can escape the requested output root.
- Default tests require MinerU, CUDA, GPU, model files, network, or `samples/`.
- The implementation parses PDF contents or invokes conversion behavior.
- The implementation introduces alternate engines or runtime engine selection.
- The implementation introduces `--api-url`, remote APIs, router mode, HTTP client backends, or remote OpenAI-compatible backends.
- `samples/` is staged or committed.

## Acceptance Criteria

Sprint 2 is complete when:

- `src/pdf2md/paths.py` exists and owns input discovery plus output path planning.
- Single PDF discovery is tested.
- Non-recursive and recursive directory discovery are tested.
- Non-ASCII PDF filenames are tested with generated temporary files.
- Markdown, assets, metadata JSON, report Markdown, and optional raw output paths are tested.
- Existing-output conflict detection is tested with and without overwrite enabled.
- No conversion, MinerU, Markdown normalization, metadata content, report content, or doctor behavior is implemented.
- `uv sync` passes.
- `uv run pytest` passes.
- `PROGRESS.md` records checks performed and residual risks.
- Independent evaluation is complete.
- The completed change is committed.

## Handoff Fields

Use these fields when Sprint 2 completes:

- Files changed:
- Commands run:
- Tests passed:
- Tests blocked:
- Known failures:
- Residual risks:
- User decisions needed:
- Go/no-go recommendation for Sprint 3:
- Next action: