pixcull: Instructions file for Claude Code

PixCull — working agreement for Claude

Local-first AI photo-(and now video-)culling tool for professional photographers. This file is the standing contract for how to work in this repo. Read it before each session.

Golden rules

1. Always git -C ~/Downloads/zero-basics-python/2/pixcull …. The cwd can drift up to the parent zero-basics-python course repo (a different git repo on branch master). Never run bare git from an ambiguous cwd — always pass -C <this repo's abspath>. pixcull-restored beside it is a stale 2.75 checkout; only its pixcull/.venv is still used (make expects pixcull/.venv inside this repo, so call that interpreter directly).
2. Test gate before every commit: python -m pytest tests/ --ignore=tests/test_v1_1_scripts.py (must be green; 5 skips expected — 2 face-fixture + 3 zeroconf). On the pixcull checkout as of v3.89 the local count is 14, all environmental: 2 face-fixture, 4 Paraformer weights, 3 rescorer_v1.joblib absent from the repo-root models/, 5 exiftool not installed (CI installs it). zeroconf is installed here now. A different number means a skip appeared or vanished — name it before committing. Locally also --ignore test_lightbox_stability.py and test_visual_smoke.py (headless capture is killed by this host). Stop any pixcull m3 open / serve first (pkill -f 'pixcull m3 open'). A review server left running costs the suite enough headroom that test_clip_cache_freeride and test_e2e_smoke fail with Cannot send a request, as the client has been closed and a CLIP offline-load error — which reads as a real CLIP regression and is not one. Verified 2026-08-16: 2 failed with it up, 1990 passed with it stopped, same commit. The ASR real-engine lane needs its weights pointed at: export MODELSCOPE_CACHE=/Volumes/<drive>/pixcull-models/modelscope (and HF_HOME=…/hf for MLX-Whisper) or tests/test_transcribe_real_engine.py adds 4 more skips. With it set the count is back to 5 and those tests actually run — which is the point: v2.43.2's three bugs were all invisible until the engine was really started.
3. Commit trailer: end every commit message with Co-Authored-By: Claude Opus 5 <[email protected]>. (Was 4.8; the trailer names whichever model actually wrote the commit, so it changes when the model does.)
4. Commit / push only when asked. Pushing to GitHub or ModelScope is publishing public content — confirm first, then run the audit (below) before any push.
5. make preflight AFTER the release commit, before the push (v3.70; the ordering is v3.72). Twenty-one test files, ~21 s, no models: the version rail, both READMEs, the changelogs, the dependency pins, the settings registry, the docs' command names, repo hygiene, the skip ledger. Eight of the last twenty releases needed a fixup commit and the recent ones were all this: the product change was right and the bookkeeping around it was not, learned from a runner nine minutes later. The list is drift-checked by tests/test_preflight_covers.py, which finds bookkeeping gates the list has not got — it found ten the hour it was written. Order matters: test_release_rail.py and test_readme_style.py measure distance from the newest release commit, so running them before committing counts one release fewer and they pass on a tree that CI will fail. That happened on v3.72 — preflight green, push, CI red — so preflight now warns when the tree is dirty.