Development record
Once 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 -->
Once 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.
Frontmatter
| id | iss-2610121431244546 |
|---|---|
| type | issue |
| lifecycle | open |
| severity | minor |
.abcd/work/issues/open/iss-2610121431244546-stale-usage-argument-hint-flags-unscoped.md
open on GitHub ↗ · commit history ↗
mentions1
- iss-2610120921497084The 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.