# Sparrow Spatial — repo contract
Live monocular sparse mapping. Everything here is the product:
```
scene.py synthetic camera (deterministic path = contract). stills/stream
core.py pipeline: extract() + step() + SparseMap + Pipeline
overlay.py WINDOW 1: on-scene HUD (tracked points, tails, metric strip)
topmap.py WINDOW 2: top-down sparse panel (points, camera trail, scale)
main.py the live viewer — the product the boss demos
judge.py behavioral gate: run headlessly, prints PASS/FAIL + names owners
demo.md (T7) exact boss instructions to demo both panels
```
## Day-1 state (seed v1)
It runs and it is *crudely correct*: plain goodFeaturesToTrack, plain
Lucas-Kanade, a naive WeakMap whose "map" is not really a map. The judge
fails it on purpose (see its thresholds) — that gap is the backlog.
## House rules
1. New modules keep the seed's APIs (core.py imports them if present;
duck-typing — the rest of the repo must never care).
2. Every change lands with a real commit (git history is the truth).
3. Anything you can't verify doesn't exist: run me
(`python3 judge.py`) before claiming numbers.
4. Never touch scene.py's camera path without a meeting — the judge
and PRs all measure against that trajectory.
5. The two panels are the product: aesthetics violations go to June,
metric regressions to Tomas. `look` at a real frame before arguing.
## Boss usage
cd work/project
pixi run demo # live demo, both panels (--source scene|webcam)
pixi run judge # quality gate (or type `judge` in console)
pixi run scene # the raw feed, if you want it
ALWAYS use the pixi env: `pixi run python <script.py>`. Never system python,
never bare pip — dependency changes are a PR that edits pixi.toml with a note
to the lead. The judge, the viewer, capture, everything runs in the env.