The Amber Ledger
How many hours did this project actually take, sealed so the number can't be quietly edited.
The ingredients 5 gifts
Pick your depth — take the quick way in, the full walk-through, or the deep build. Same recipe, your call today.
Quick you just want the number, today
Point the chain at your repo, seal the result, done. Four commands, no setup.
You get a defensible hours floor with a tamper-proof seal — enough to answer 'was this 40 hours or 400?' without billing anyone to the minute.
python3 worklog.py . --since "2 weeks ago" --by day --json > buckets.jsonl
python3 timesheet.py buckets.jsonl --break-gap 90m > hours.json
python3 amber.py seal hours.json > hours.amber.json
python3 amber.py verify hours.amber.json # exit 0 = intactWorking you want to understand what each piece does
Read the five parts below — they walk the source→fold→seal shape end to end: gitlog emits commit records, worklog and timesheet fold them into an hours floor, amber+sha256 make that floor auditable.
This is the standard walk-through. Everything you need to wire it yourself is here, in plain language.
Deep you want to build it right, edges and all
The honest edge is the load-bearing part: the number is a FLOOR, biased to under-count. An isolated commit reads as zero; invisible thinking reads as zero. Never bill a client to the minute from it.
The amber seal proves nobody EDITED the estimate — not that the estimate is TRUE. Treat it as 'this number wasn't tampered with,' and pair it with your own judgment about what the repo doesn't capture (design done on a whiteboard, a week of reading).
For a real deployment: pin the break-gap to your team's actual rhythm, re-run verify in CI so a tampered report fails the build, and keep the sealed capsule beside the invoice as the audit trail.
The idea
The one clean, honest, left-to-right pipe in the set — and it actually type-checks: a source at the head feeding two folds. Also the most immediately useful if you freelance. The effort number is derived from byte-truth and tamper-evident: change any input and the seal breaks and names what moved.
The parts + how they wire
gitlog (source — git history to one JSON object per commit) → worklog (fold — group by day or author, counts + subjects) → timesheet (fold — estimate worked-hours as the day's span minus every gap longer than a break threshold) → amber + sha256 seal the finished report into a fixity capsule.
The one piece you build
Almost nothing — a few lines of shell to chain them and pick your break-gap. This is the buildable-in-an-afternoon one.
The technical breakdown
The three stages share a port-verb algebra, so the chain type-checks: gitlog is a source (emits records, consumes none), worklog and timesheet are folds (consume records, emit a reduced view) — a source at the head feeding folds is a well-formed pipeline, which is exactly what typecheck confirms before you run it. It's re-pointable and re-lensable from the same spine: the fold-chain re-points at any repo (swap the gitlog target), and swapping the lens in worklog (group by day vs. author vs. file-churn) gives a different honest report from the same parts. amber + sha256 make the floor auditable: the number you handed a client can be re-checked against the repo, and any edit to the sealed report breaks the capsule's fixity and names the changed member.
The honest edge
timesheet is explicit that commit timestamps bound work, they don't measure it — it's floor-biased and under-counts on purpose (an isolated commit reads as 0; invisible thinking reads as 0). Do not bill a client to the minute with it. It's a defensible floor for 'was this 40 hours or 400,' not a timeclock. The amber seal makes the floor auditable, not true — it proves nobody edited the estimate, not that the estimate is the real hours.
These are ingredients, not instructions you have to follow. Take these parts and cook something — the recipe as written, a variation, or something we'd never have thought of.
Built it, got stuck, or found a mistake? Shea wants to hear it — success stories, questions, and bug reports all land in the same inbox: