Phase 1: replace legacy spreadsheet with validated, version-controlled inventory

[sr320]

Replaces the spreadsheet in legacy/ with version-controlled, validated data, and records the plan for the rest of the system.

Two commits: the plan and governance docs, then the migration tooling and generated data.

What's here

PLAN.md	Architecture and phased plan, including the optional LLM photo-description pipeline
PHOTO_POLICY.md	Photo rules — mandatory because this repo is public
.github/CODEOWNERS	@sr320 and @kubu4 both maintain
.github/workflows/validate.yml	CI gate on every PR touching data/
scripts/migrate_legacy.py	One-time xlsx → CSV migration
scripts/validate.py	Schema, closed-set, referential-integrity, and date validation
data/*.csv	499 items, 173 locations, 16 rows needing a human pass

Decisions this encodes

Public repo. This puts the whole privacy burden on the photo path, so PHOTO_POLICY.md ships now rather than with Phase 4, and three guardrails are mandatory rather than nice-to-have: strip all EXIF, review the image itself and not just the items derived from it, and allow rejection on privacy grounds alone. The reasoning worth agreeing on before Phase 4: a merged photo is permanent — it survives in history, in every fork, and in whatever already scraped it — so pre-merge review is the only control that actually works.

Both maintainers can merge. Enough that nobody is a single point of failure, few enough that review actually happens.

Migration judgment calls

The migration never guesses silently. Ambiguous legacy rows go to data/review_queue.csv with a stated reason instead of into items.csv:

• Semicolons split automatically; commas don't. Microcentrifuge tubes, conical screw top tubes, screw caps is three items, but DNeasy 96 blood and tissue kit (4) & (50) is one. Comma-only cells stay whole and carry a suggested split for a human to accept or reject.
• Five rows on the drawers/cabinets sheet are coarse restatements of the dedicated Rm 213 shelf sheet. Importing them would have created ~40 duplicate items, so they're queued for reconciliation. Nothing dropped, nothing duplicated.
• The date column held commentary — Very likely all expired, n.d., 08/2010 from FHL. That text moves to notes rather than being discarded, and partial dates keep their real precision (08/2010 → 2010-08) instead of having a day invented for them.

The staleness is now data

Every migrated row carries status=unverified and last_verified=2021-08-29 — the spreadsheet's own claim about when it was last touched. validate.py reports it on every run:

items                499
locations            173
unverified           499 (100%)
not verified in 1y   499 (100%)
locations w/o items  46

Five years of drift is a queryable field instead of a caveat someone has to remember. The source column (legacy-xlsx | manual | photo-llm) makes provenance permanent, so a later audit can always ask which rows a model wrote.

Two schema additions worth a look

• glassware and office categories alongside the lab ones. Without them roughly half the inventory landed in other, which would make the planned category filter useless. Now 25%, which is honest for a drawer containing a Nintendo.
• An owner column, since the legacy storage bins tag contents - Goetz.

Say so if you'd rather not track either.

Verification

validate.py is stdlib-only, so there's nothing to install and nothing to break when a dependency moves. Tested against nine injected faults — duplicate item ids, dangling location refs, non-ISO dates, self-parenting locations, unknown category, and a photo-llm row with no photo_id — all nine caught, exit 1.

location_id is deliberately short and stable (209-CAB-01, 213-F20-S02-D08) because it becomes a URL fragment and a QR-sticker payload; deriving ids from prose labels produced 60-character identifiers. Prose-numbered places get an X01 sequence so they can never collide with numerically-numbered ones.

Open questions

• Are room 230 and the -80 room yours to track? 4 locations, trivial to drop.
• Freezer boxes: v1 tracks the box, not the tube. Sample-level tracking is a different problem and probably its own tool.

Next

Phase 2 — search UI and QR stickers. Deliberately before the add-item forms: search value has to land before anyone is asked to enter data, or this goes the way of the spreadsheet.

🤖 Generated with Claude Code