cli: one declaration for the commands, and the documents held to it

[donislawdev]

Closes O201. Three lists said the same thing, no two of them were compared, and all three were green.

• the block tfg --help prints was a raw string beside the switch that dispatched
• the website copied that block by hand
• the flag table in README was typed out separately from the flag set generate builds

README was missing --damage, added to the program the same day, and nothing said so.

Measured before writing anything

The naive fix would not have worked, and this is why:

list	count	contents
dispatch, verbs taking arguments	8	generate validate verify cleanup recipe preset formats damage
the Commands: block	10	those eight, but recipe fmt, plus version and license

All four differences are legitimate - recipe branches on one word and prints as two, and version/license do not take args[1:]. A guard comparing the two lists would have raised four false alarms. That is what shaped the declaration into separate fields rather than one name.

The change

Run and the help both come from one table in internal/cli/commands.go.

The output is byte for byte what it was - the same sha256 across --help, --version and an unknown command. This is a refactor, not something a user of the tool can see.

The fields are apart because they answer different questions. Verb is what the dispatch matches. Aliases reach the same place and are not printed, which is how four spellings of licence exist without the help turning into a spelling lesson. Shown replaces the verb in the help where they differ, and only recipe does. An empty summary means reachable but unlisted, which is help itself.

Guards

The other two lists are documents, which no declaration can generate. Each guard asks a rule, not a list of exceptions:

• every command the help lists is a verb the tool answers to - asked with the first word of the printed name, because that is what a reader types
• every command it does not list does nothing except print that help, compared against the help itself - which tells help apart from a verb somebody forgot to describe, without naming either
• the README table is compared against the flag set generate really builds, both directions, with a shape check first so a change in flag.PrintDefaults cannot leave the map empty and every comparison trivially true
• the English page repeats the program's own sentences word for word, which is all that can be asked where the Polish page describes the same command in Polish on purpose

TestEveryCommandTakingItsOwnArgumentsIsWatchedForHelp read the dispatch with go/ast and refused to pass when that switch disappeared - exactly what it was built to do. It asks behaviour now: a command with its own flag set refuses an unknown flag with ExitUsage, one that ignores what follows answers normally. All eleven verbs, eight to three, no exception to write down.

What this cost

Five mutations were invalidated at once - four by code moving out of cli.go, one by my own pattern written against a line I then reflowed. All five reported SKIP, which reads as proven, and only staleness.py said otherwise. Repointed and rerun.

Three came back NOT CAUGHT or BROKEN, each for a different reason, and one was a real hole in a new guard: it asked the declaration about its own verb rather than about the printed name, so an entry printing one word and dispatching on another passed. The fix is a repair, not a mutation tweak.

internal/guard/site_test.go crossed into the crowding band, answered with a cut rather than a larger number - the command knowledge moved to the new file where it belongs.

Verification

Full suite green, gofmt from $(go env GOROOT)/bin and go vet clean, journey.py 300 of 300, staleness.py reports every pattern occurring exactly once across 958 entries, ten mutations run and all caught.

🤖 Generated with Claude Code