[tannevaled]

wired: match the invocation, not the prose

tools/wired is the guard over the other four: its test fails when a tool under
tools/ is invoked by no workflow. It exists because the MkDocs-to-Hugo move
(#28) rewrote the workflows and dropped two documentation guards while leaving
them in the tree — a guard nothing calls is indistinguishable from a guard that
passes, since both are silent.

It matched the tool's bare name anywhere in the concatenated workflow text.
Which means it was already partly answering on prose:

.github/workflows/docs.yml:106:  go run ./tools/docexample --rbgo /tmp/rbgo --root content/en
.github/workflows/docs.yml:108:  # docexample judges the examples that claim an answer -- 11 of them. The

Measured, by planting it

Replaced line 106 with an echo, leaving the comment, and counted both rules
against that state rather than reasoning about them:

$ grep -rno "docexample" .github/workflows
.github/workflows/docs.yml:108:docexample          <- the OLD rule: still 1 match → "wired"

$ grep -rno "tools/docexample" .github/workflows
(nothing)                                          <- the NEW rule: 0 matches → unwired

and the gate itself, under the new rule:

--- FAIL: TestEveryToolIsWiredIntoAWorkflow
    no workflow invokes [docexample].

So the one defect this package exists to catch was invisible for the one tool
whose step carries a comment about it. Line 106 is restored byte-for-byte.

Still deliberately crude

The existing comment argues the crudeness is a choice — "it looks for the
directory's name in the YAML, not for a correctly formed step … a crude test
that would have failed #28 beats a precise one nobody wrote" — and that
argument is kept. This does not start parsing YAML or validating steps. It only
stops treating "appears in a sentence" and "appears in a command" as the same
claim, and tools/ is what every spelling of an invocation has in common:

go run ./tools/upstreamlinks --root content/en
go run github.com/go-embedded-ruby/docs/tools/conformancefigure@v0.6.0
cd tools/docexample && go run .

while a prose comment does not. All three are test cases.

A workflow that invoked a tool some other way — through a variable, a matrix —
now reads as unwired. That fails loudly rather than quietly, which is the
direction this particular guard should be wrong in.

Tests

TestAMentionInProseIsNotAnInvocation asserts both halves together — the comment
alone must not count, and each real invocation must still count — so a rule
tightened into matching nothing cannot pass it. The repository's live state is
unchanged: 4 tools under tools/, all four invoked.

The failure message said "no workflow mentions", which is now the wrong word
for what is checked; it says "invokes" and names the pattern, because the message
is what the next person acts on.

README: tools/wired was not described at all — a reader could not tell the
wiring was asserted. One paragraph, with the reason and this defect.

Co-Authored-By: Claude Opus 5 noreply@anthropic.com

🤖 Generated with Claude Code