I Built a Triage Tool Whose Only Promise Is That Every Item Lands on Exactly One Shelf

Description and use

Shelf automatically sorts folder items into user‑defined project shelves, ensuring each item lands on exactly one shelf with a reason and provenance, and verifies the partition on every build.

Problem

Managing a mixed folder of notes, screenshots, and links leads to items being misfiled or duplicated, making it hard to track what belongs to which project or who is waiting on you.

Outcome

Shelf ensures every item is assigned to exactly one shelf with a documented reason and provenance, preventing silent drops or duplicate filings. The board shows a total count that matches the folder contents, and the build fails if the invariant is violated.

Workflow

• 1. Define a project list in a Markdown file (e.g., demo/projects.md).
• 2. Place items (files, images, sidecars) in a folder (e.g., demo/pile).
• 3. Run python shelf.py build --pile demo/pile --projects demo/projects.md.
• 4. Shelf extracts text via OCR or sidecar files, scores against project terms, and assigns each item to a shelf.
• 5. Shelf writes a board.md with shelves, items, reasons, and provenance.
• 6. Shelf runs a partition check that asserts every item lands on a valid shelf, has a reason, and the total count matches the number of items.
• 7. If any assertion fails, the build fails, alerting the user to the misfiled item.

Evidence

shelf reads the folder, pulls text out of whatever it can, scores that text against a project list you wrote, and writes a board.

Source

It runs on every build and the run fails if it does not hold.

Source

Python 3.10+, standard library only. 51 tests, 124 cross-language verifier asserts, 29 in-page checks, 0 failures.

Source