feat: check short flags

[silversurfer562]

Only --long forms were scanned, so every -v in generated content was a silent pass. This is the last silent-pass class in the flag checker.

The easy half

A single-letter short flag is unambiguous — it is that flag or nothing — so an absent one is an error, exactly like a long flag.

The half that could have made the tool worse

A longer single-dash token has several valid readings:

Token	Could be
-xzf	a cluster of three flags (tar)
-name	a single-dash long option (find, java)
-j4	a flag with an attached value (make)

Each reading is tried against --help — a cluster verifies when every letter is a known flag, an attached value when the leading flag is known. Only if none verifies is a finding emitted, and then as a warning, not an error: an ambiguous token is unverifiable, not refuted. That's the same rule the checker already applies to a command with no --help.

Splitting -name into four letter flags that don't exist would have been the obvious way to get this wrong, and it would have fired on every find example in every doc.

A dash followed by digits is not a flag. --threshold -5 reads -5 as the value it almost always is. The cost is that a numeric short flag (head -5) goes unchecked; the alternative false-positives on every negative number in a command line. Documented as a known limitation.

A latent bug the feature exposed

_flag_in_help bounded a match on the trailing side only. The trailing bound already stopped -v matching inside --verbose — but nothing stopped it matching the tail of --v, so a command whose help has only --v would report -v as verified. Both sides are now bounded. Covered by evasion_short_flag_hiding_in_long_flag.

Verification

Gate	Result
Tests	173 passed (was 153)
Coverage	97%, flags.py 100%
Corpus precision/recall	passing, 6 new regression cases
Mutation score	82.0% against the 75% gate (937 mutants, up from 890)
Lint	ruff + black clean
Dogfood	verify over its own README/CHANGELOG — no new errors, only the pre-existing "no help for command X" warnings

Version left at 0.4.0 with the entry under [Unreleased]; additive, so the next release is a 0.5.0 minor.

🤖 Generated with Claude Code