The vendor freshness gate is advisory and nothing runs it — and #669 describes it wrongly

[syncytium2]

Three things about one gate, filed as a todo plus the INDEX row that was missing.

The gate nobody runs

tools/check_vendor_freshness.sh checks four vendored families against their upstreams. A grep of the tree finds it named in CLAUDE.md, docs/SESSIONS.md, docs/DEPLOY_HOLD.md, four todos and a sapper-feedback note — and in no workflow under .github/, no test under tests/, no hook under .githooks/. It runs when a session remembers to type it.

Worth naming because the failure it exists to catch already happened: third_party/draughtsman/ sat pinned at cb7fc2a for three days while draughtsman had fixed a mis-routed edge in bb83174, and the front page published that figure with nothing red.

The todo says why wiring it into CI is not a one-liner — it resolves upstream through gh against two private repositories, and BUGARACH_INTERFACE2 names a machine-local clone no runner has — and lists the candidates in order of cost. Its own design anticipates this: exit 2 means could not determine, chosen deliberately because a false STALE is its own harm.

The upstream answer can be twelve hours old, and the report doesn't say so

murderboard_freshness.sh caches the resolved upstream HEAD per family in the git common dir for TTL seconds — default 43,200. --refresh is the only bypass. The verdict line names the cached sha as "upstream" without marking it as cached.

That is not hypothetical: it is where #669's wrong claim came from. Its cache held a draughtsman sha written before draughtsman #1 merged, so the session reasoned about a repository state that had stopped existing hours earlier.

The gate does guard the behind-cache direction, with a self-test ("a BEHIND cache is not stale") that keeps a consumer stamped at or after the cached sha from being accused. But provably at-or-ahead of a twelve-hour-old sha is weaker than current, and nothing in the output separates them — in the exact window the gate exists for: upstream merges, a session re-vendors the same day and checks its work.

Credit where it is due: the session that wrote the wrong claim is the one that traced it to this.

A published misreading, corrected

#669 said in its body that the gate "compares each family file with the last upstream commit touching that file" and therefore that the draughtsman family "reports stale permanently." Neither holds, and its author has since corrected the body and confirmed the reading here. The correction is recorded in the tree anyway, because the PR is merged and a later session will meet the claim before it meets any reply:

• There is no per-file history lookup in murderboard_freshness.sh — no git log -- <path>. The first listed file supplies one stamp for the whole family; the others are reported only when they disagree with it, which is the half-finished-re-vendor check.
• That single stamp is compared against upstream HEAD (subject to the cache above).
• So a family reads stale when its upstream moves past the vendored commit, changed files or not. That is the gate working; the cure is a re-vendor bumping every stamp together, which The fair comparison's four architectures, drawn through draughtsman at one slot #660 and The vendored draughtsman stamp names the commit that landed, 0898967 #669 each did.

One more thing recorded

#669 was opened at 17:42 EDT and merged at 17:44 — before CI finished, on a branch whose suite now takes two hours. Three stamp lines over a byte-identical package, so nothing broke. But tools/merge_when_green.sh exists to refuse exactly that, and merging through the API goes around it. Noted, not escalated.

Docs only: one new todo, one INDEX row. tests/test_index_resolves.py 334 passed; sapper, check_quotes and check_pipelines clear.

🤖 Generated with Claude Code

https://claude.ai/code/session_017hQX6iESxBsQk7Jan875e3