PDFToMD/docs/Sprints/SPRINT1CONTRACT.md

Sprint 1 Contract: Project Scaffold And Fast Test Loop

Status: Completed Last updated: 2026-05-07

Objective

Create the minimal Python project scaffold and fast local test loop for the PDF-to-Markdown converter.

Sprint 1 must establish:

• A uv-managed Python 3.12 project.
• A source package importable as pdf2md.
• A reserved pdf2md CLI entry point that does not implement conversion yet.
• A fast test command that runs without MinerU, model downloads, GPU access, sample PDFs, or network access.

Sprint 1 is scaffolding only. It must not implement PDF conversion, MinerU execution, Markdown normalization, metadata generation, or report generation.

Current Precondition

Sprint 0 found that uv was not available on PATH in the current local environment.

Sprint 1 resolved this by installing uv per-user at C:\Users\user\.local\bin.

Before Sprint 1 can be accepted, one of these must happen:

• uv is installed and uv --version succeeds.
• The user explicitly approves including uv bootstrap documentation or setup handling as part of Sprint 1, and the contract result records that uv sync could not be run locally.

Do not silently replace uv with another package manager.

Touched Surfaces

Allowed:

• pyproject.toml
• uv.lock
• .gitignore
• src/pdf2md/__init__.py
• src/pdf2md/cli.py only for a minimal placeholder CLI if needed for entry point verification
• tests/
• README.md only for minimal setup/test instructions if needed
• 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/SPRINT1CONTRACT.md

Not allowed:

• src/pdf2md/conversion.py
• src/pdf2md/mineru_adapter.py
• src/pdf2md/paths.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 committed file under samples/

Expected Outputs

Sprint 1 should produce:

1. Project package scaffold

   • pyproject.toml with project metadata.
   • Python requirement constrained to Python 3.12.
   • Build configuration suitable for a src/ layout.
   • uv.lock generated by uv sync.
   • .gitignore entries for local virtual environments, pytest cache, and Python bytecode.
   • Minimal test dependency configuration.
   • CLI entry point name reserved as pdf2md.

2. Minimal source package

   • src/pdf2md/__init__.py.
   • A stable package import surface.
   • Optional minimal src/pdf2md/cli.py placeholder that exits clearly and does not imply conversion is implemented.

3. Fast test loop

   • A minimal test suite that verifies the package imports.
   • If a CLI placeholder is added, a smoke test that verifies the CLI entry point is wired without invoking conversion.
   • Tests must not require MinerU, CUDA, GPU, model files, samples/, or network.

4. Developer workflow

   • uv sync should work when uv is installed.
   • uv run pytest should work when uv is installed.
   • If uv is still missing locally, record the failure explicitly in PROGRESS.md and do not mark Sprint 1 complete.

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 discovery.
• 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 implement Markdown normalization.
• Do not implement metadata JSON or .report.md output.
• Do not implement pdf2md doctor; a CLI placeholder may mention future commands, but it must not create a doctor module.
• 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

WP1.1: Scaffold Metadata

Owner:

• feature-generator-agent

Actions:

• Create the minimal pyproject.toml.
• Use Python 3.12 constraints.
• Configure a src/ package layout.
• Configure pytest as the fast local test runner.
• Reserve the pdf2md console script.

Output:

• A minimal, maintainable scaffold without speculative dependencies.

WP1.2: Package Import Surface

Owner:

• feature-generator-agent

Actions:

• Create src/pdf2md/__init__.py.
• Expose only a minimal version/import surface.
• Avoid public API promises beyond what Sprint 1 verifies.

Output:

• import pdf2md succeeds.

WP1.3: CLI Placeholder

Owner:

• feature-generator-agent

Actions:

• If needed for console script verification, create src/pdf2md/cli.py.
• The placeholder may expose a help message or a clear "not implemented yet" command.
• It must not create conversion flags beyond the reserved command shape unless tests need them.

Output:

• pdf2md entry point is wired without implying conversion works.

WP1.4: Fast Tests

Owner:

• feature-generator-agent
• evaluation-agent

Actions:

• Add minimal tests for package import and optional CLI placeholder behavior.
• Ensure tests are local, fast, and independent of MinerU/model/GPU/network state.

Output:

• uv run pytest passes when uv is available.

WP1.5: Independent Evaluation

Owner:

• evaluation-agent

Actions:

• Review the completed scaffold against this contract.
• Verify no converter implementation was added.
• Verify samples/ remains untracked and unstaged.
• Verify no runtime remote path or alternate engine was introduced.

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 if uv is available.
• uv run pytest passes if uv is available.
• If uv is unavailable, Sprint 1 is marked blocked rather than complete.
• Import test passes through the configured test command.
• 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.
• git diff --check passes.

Recommended:

• Keep pyproject.toml dependency list minimal.
• Avoid adding README content beyond setup/test instructions needed for the scaffold.
• Use requirements-guard-agent to check document consistency if the scaffold reveals a sequencing issue.

Hard Failure Criteria

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

• uv remains unavailable and the user has not approved bootstrap handling.
• The project cannot be installed as a Python 3.12 package.
• The package cannot be imported as pdf2md.
• Default tests require MinerU, model downloads, GPU access, sample PDFs, or network access.
• The scaffold introduces conversion logic outside Sprint 1 scope.
• The scaffold introduces alternate engines or runtime engine selection.
• The scaffold introduces --api-url, remote APIs, router mode, HTTP client backends, or remote OpenAI-compatible backends.
• samples/ is staged or committed.

Acceptance Criteria

Sprint 1 is complete when:

• pyproject.toml exists and defines a minimal Python 3.12 uv project.
• src/pdf2md/__init__.py exists and import pdf2md works through the project environment.
• uv sync passes.
• uv run pytest passes.
• The pdf2md CLI entry point is reserved and does not imply conversion is implemented.
• No converter implementation code beyond the allowed placeholder exists.
• No default test depends on MinerU, GPU, model files, network, or samples/.
• PROGRESS.md records checks performed and residual risks.
• Independent evaluation is complete.
• The completed change is committed.

Handoff Fields

Use these fields when Sprint 1 completes:

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