The stale-usage note matches a flag anywhere on the verb's command page, not under the sub-verb typed: build next --dry-run was called documented because commands/build.md mentions '/abcd:drain --dry-run' in prose, so the note blamed the binary's age for a flag build next never had.

Frontmatter

.abcd/work/issues/resolved/iss-2610120921497084-the-stale-usage-note-matches-a-flag.md
open on GitHub ↗ · commit history ↗

mentions2

• iss-2610121206277151The stale-usage note's classifier (internal/surface/cli/staleusage.go) reads a positional argument under a verb that has sub-verbs as an unknown sub-verb: 'abcd build itd-1 --frob-top' takes itd-1 for a sub-verb of build, so a flag the build page genuinely documents for 'abcd build <itd-N>' gets no stale-binary note. It fails safe (the plain unknown-flag refusal, never wrong advice), but a stale binary is then not told why. Found by the fix for iss-2610120921425348 and iss-2610120921497084 (branch fix/stale-usage-notes), which left it outside those remedies. <!-- record-lint: forward-looking -->
• iss-2610121431244546Once the fix for iss-2610120921497084 scopes the stale-usage flag match to fenced synopsis lines (internal/surface/cli/staleusage.go, synopsisCarriesFlag), a flag a command page documents only in its argument-hint front matter or in inline-backtick prose no longer counts as documented. About 60 flags across commands/*.md appear only there (capture resolve's [--commit <sha>], build's --release and --discard, ahoy install --yes), so a release PATH copy that predates one of them now prints the plain unknown-flag error and withholds the true stale-copy note. Fails safe (silence, never a false claim). Found by the ruthless review of fix/stale-usage-notes, 2026-10-12. <!-- record-lint: forward-looking -->