fix: reject CLI declarations shadowed by built-in routes

[codeforester]

Summary

Reserve built-in help/version options, reject option-shaped command and alias routes, and validate that no stored model route is intercepted by built-in parsing. The direct API and table declarations remain atomic on rejection.

Issue

Fixes #506

Validation

• bats lib/bash/cli/tests/lib_cli.bats — passed (37 tests).
• git diff --check — passed.
• Full repository hosted validation is pending.

Demo Impact

None.

Docs Impact

None; the CLI route boundary is enforced at declaration and validation time.

API Impact

Invalid declarations that were previously accepted now return usage status 2 before model mutation.

CI Impact

Adds direct, nested, table-driven, and model-integrity coverage.

Security Notes

None.

[codeforester]

Two findings from review, both actionable:

1. lib/bash/cli/lib_cli.sh:64 — The tightened __base_bash_libs_cli_valid_segment__ regex (^[A-Za-z0-9_][A-Za-z0-9_-]*$) rejects the single-character segment -, but a bare - was never actually shadowed by built-in option parsing and remains a legitimately reachable command/alias/model-name in the runtime parser. base_cli_parse (line 1388: [[ "$current" == -* && "$current" != - ]]) explicitly excludes a lone - from option-token interpretation, so it dispatches to command-child lookup like any normal segment. Before this PR, base_cli_command app - "Read from stdin" (the common Unix stdin convention) returned status 0 and was correctly reachable; on this PR it now fails at declaration time with exit 2 ("path '-' must be a non-root command path"). The same regression hits aliases=- on base_cli_command and name=- on base_cli_model_init (line 709 reuses the same helper). No bats test exercises this boundary in either direction, so the regression ships silently.

2. lib/bash/cli/lib_cli.sh:1372 — The PR introduces a canonical __base_bash_libs_cli_is_builtin_option_token__() helper for what counts as a built-in token, but base_cli_parse (the actual runtime authority on -h/--help/-V/--version interception) still hardcodes the same four literals separately instead of calling the new helper, leaving two independent definitions of the reserved-token set. If a future change adds/removes a built-in flag by editing only one location, base_cli_option/base_cli_validate_model would silently allow declaring a token that's actually unreachable at runtime — reintroducing exactly the shadowing bug this PR fixes, with no test catching the drift.

[codeforester]

Addressed in commit 1f59a38: the exact '-' segment is accepted again, and one canonical built-in-option classifier now drives both declaration-time reservation checks and runtime help/version interception. bats lib/bash/cli/tests/lib_cli.bats passes (38 tests).

[codeforester]

Follow-up: hosted pinned-shfmt validation caught one formatting difference not reported by the locally installed formatter. Corrected in aff9a25; the CLI BATS suite still passes (38 tests), and the refreshed hosted checks are queued.

[codeforester]

Confirmed fixed. base_cli_command app - "Read from stdin", aliases=-, and name=- all work again (the tightened segment regex now special-cases bare -). base_cli_parse now routes through a single shared __base_bash_libs_cli_builtin_option_action__() used consistently by parse/option/validate-model, so the two independent definitions are gone. Full lib_cli.bats suite passes (38/38).