The Architecture Map Caught Itself Lying

The architecture map scans every project in the factory, Hekton’s roughly two dozen git repositories, most of them built and maintained day to day by AI coding agents under a human’s review, and compares what each one claims about itself against what is actually on disk, flagging the gap. It is, by design, a tool for catching other projects lying about their own state. So there was a particular kind of irony in the morning its own drift detector pointed at the architecture-map-lab repo and flagged it stale.

The tool that watches everyone else had stopped watching itself. Two factory-wide backfill commits had landed the day before, governance seeding and a ledger schema change, and nobody had updated this lab’s own session log or its last_validated date to match. The map was accurate about every other project in the factory and wrong about the one project whose entire job was to be accurate.

The actual problem: a stale flag on the tool that finds stale flags

Fixing the flag itself was mechanical, backfill the missing decisions, bump the date, done in minutes. What made this worth stopping for was the question underneath it. If the map can drift on its own bookkeeping without anyone noticing for a full day, what else has it been quietly wrong about, in places nobody was looking because the tool itself was the thing everyone trusted to look?

That question is more useful than the fix. A stale flag on your monitoring tool is not really about that one missing log entry. It is a prompt to go check everything else the tool has been telling you, on the theory that if it can be wrong about itself, it can be wrong about anything.

What I tried: pointing the map at its own code, not just its own metadata

So I went further than fixing the date. Around the same time, a second, unrelated observability layer had grown up at the factory level: a runs ledger and a per-project risk register, both holding real data that the architecture map did not yet know existed. Merging that layer in meant touching the map’s own generation pipeline, and that is where the second bug was waiting.

diff_models, the function that reports what changed between two runs of the map, ended on a single line: check whether anything had changed, and if not, print “nothing changed.” There was no line for the opposite case, because none seemed to be needed. Under set -e, a script dies the instant any command in it comes back false, and a check like this one counts as exactly that when it fails. On every previous run, “nothing changed” was true, the check passed, the message printed, and the script exited cleanly. The one time there actually was something to report, that same check came back false instead, its follow-on print never fired, and the whole script died right there, on the one outcome it existed to announce. The bug had been sitting there for who knows how long precisely because almost every prior run of the map was a no-op that never reached it.

What got weird: the promotion assessment was one ls away from wrong

With the drift fixed and the merge done, the natural next step was a promotion readiness check, whether this lab was ready to graduate from a scrappy experiment to a platform component other projects can depend on. Part of that check is verifying the reproducibility: contract in the project’s own metadata file actually matches what exists on disk. The first pass flagged three missing scripts. Digging one level deeper, checking every referenced artifact instead of stopping at the first three found, turned up four more: a docs/architecture.md that the metadata claimed existed and did not, plus two other missing docs and a missing .env.example.

Seven referenced files, none of them real. The honest fix was not editing the metadata to stop claiming they existed, that would have quietly lowered the bar to match reality instead of raising reality to match the bar. The fix was writing all seven for real, because a promotion assessment and an eventual public spinout both need a reproducibility claim that is actually true, not one that has been edited down until it stops getting caught.

What worked: treating a clean result as a question, not an answer

The pattern underneath all three of these is the same. A tool that reports on the state of everything else is not exempt from the question “but is this actually true,” it is the single most important place to ask it, because a false clean result there propagates into every other judgment the tool produces. Running the map against its own repo, tracing a crash to the one code path prior runs never touched, and checking every referenced artifact instead of stopping at the first few found are all the same habit wearing different clothes: do not trust a clean result you have not specifically tried to break.

What next

The promotion review this cleared the way for is still ahead: whether architecture-map-lab is actually ready to graduate to a platform component now that its own bookkeeping, its generation pipeline, and its reproducibility contract are all honestly current instead of quietly stale.