Building the devlog, and teaching it when it's wrong

So the site exists now, and this is the entry about building it.

The public side is what you're reading: entries, and a [systems page](roadmap.php) tracking how far along each piece is. The private side is the part I actually built it for — a documents area, and notes I can jot into without deciding whether they're worth publishing.

Why a documents area, specifically

I build this project with Claude Code, and the documentation problem showed up early. The repo carries a fairly large set of written-down knowledge — how the placement rules work, which Unity traps have already cost me a day, what the last device run measured. That knowledge is genuinely load-bearing: it gets read at the start of every session and trusted.

Which means a stale line is worse than a missing one. A missing line makes someone go and look. A wrong line gets believed. I've already had a document confidently describe a scene layout that had been torn down and rebuilt, and the cost of that isn't the wrong sentence — it's the hour spent acting on it.

So what I wanted wasn't a place to put documents. It was something that would tell me when a document had stopped being true.

The bit I think is actually clever

Each document can record the path it was generated from. On every push, a GitHub Action hashes those paths and tells the site which ones have moved on. Anything generated from changed code gets flagged out of date in my admin area, and the run summary lists them.

The trick is what it hashes. It doesn't hash the file contents itself — it asks git for its own object id for that path:

git rev-parse HEAD:.agent-tools/setpieces/

That's a blob id for a file and a tree id for a directory, and it's the same value GitHub shows. Three things fall out of that for free:

• It changes exactly when the tracked contents change. Not when a timestamp moves, not when a file gets touched and saved identically.
• It's stable across machines and clones, so my desktop and a CI runner agree without coordinating.
• Uncommitted work gets a -wip suffix, so a document generated from my working tree is visibly distinguishable from one generated from a commit.

That last one matters more than it sounds. Most of my documentation gets written mid-session, against code that isn't committed yet. Without the suffix those documents would look permanently current, because the next commit is what they'd be compared against.

If the path isn't in git at all it falls back to hashing the files, so the tool still works outside a repo.

First document in

The set-piece system, which is the largest thing I've built lately: a way to approve a composition of objects once — a ruined building, a shrine — save it as a template, and let a generator drop it anywhere at any rotation still knowing it's exactly the thing I signed off on.

It's about 22,000 characters and it went up cleanly, byte for byte identical on the round trip, which I checked rather than assumed. Its source path is registered, so the moment I change that code the document goes amber.

What's still missing

Being honest about the gaps, roughly in the order I want them:

1. Commit to entry. Pass a commit range when drafting, so an entry records what actually shipped in it and links the diff. Right now I retype that from memory, which is exactly the kind of thing that goes stale.
2. A webhook instead of the Action. GitHub pings the site on push and the site does its own check. Removes the round trip and the stored token, but needs signature verification doing properly.
3. Release entries from tags. Tag a version, get a draft with the commits since the last one.
4. Issues to systems. Point a milestone at a GitHub label and let the progress bar reflect closed issues instead of a number I type in by hand.

That last one is the same idea as the whole documents area, applied to the roadmap: a number I maintain by hand is a number that will be wrong, and the only question is when.