# Starter contract: Polars migration with tests as the oracle (backlog #17)

Pre-filled from `templates/requirement.md`. Adam converted one simpler repo "in an afternoon". This starter makes that repeatable and checkable.

> **On the board:** this is **OODLE-203** on the mock Jira board. Best Wave-1 opening: connect the `oodle-jira` MCP and say *"grab OODLE-203 and grill me"*. Then compare what you froze against this contract.

## WHO

- User: engineers on a Pandas repo eyeing Polars.
- Situation: migration looked expensive by hand; one small repo (or one module) is in scope for the hackathon.
- Task they are trying to complete: convert Pandas code to Polars with proof nothing broke.

## WHAT

- Required behaviour (not implementation): `[chosen repo/module]` runs on Polars with the existing test suite green and Pandas removed from its dependencies.
- Input: the repo, its test suite, a worktree/branch of its own.
- Output: a passing branch + a diff stat + a short migration log (patterns that converted cleanly vs. needed thought).

## WHY

- Intent: prove "tests as the oracle": the migration is exactly as trustworthy as the suite that gates it.
- Business outcome: a repeatable recipe that makes the next repo's migration an afternoon, not a quarter.
- Evidence/source: Richard + Adam interviews; backlog #17.

## NOT

- Explicit exclusions: no behaviour changes, no "improvements while we're in here", no test edits to make failures pass.
- Protected areas: main branch. All work in a worktree/branch.
- Agent must never: delete or skip a failing test to get to green.

## DONE

- Acceptance signals that pass or fail: full test suite green before (baseline) and after; `grep` finds no pandas import; diff reviewed by the pair.
- Authoritative verifier: the existing test suite, run before and after. Record both outputs.

### Scenarios

```gherkin
Scenario: happy path
  Given the suite is green on Pandas at baseline
  When the migration completes
  Then the same suite is green on Polars with no test modified

Scenario: edge case
  Given a Pandas idiom with no direct Polars equivalent
  When the agent converts it
  Then the migration log names the pattern and the chosen equivalent

Scenario: explicit exclusion
  Given a test that fails after conversion
  When the agent proposes a fix
  Then it fixes the code, never edits the test to pass
```