Every CLI Script Answers --help and Refuses Unknown Arguments Before Writing #2285

What Happens

Agents reach for --help to learn a script's interface, and a script that does not answer it does something else with the argument. The maintainer has seen several agents trip on this, each invocation with consequences nobody could predict beforehand.

The worst case today is repo-config/configure.sh. Its first positional is the mode, and anything other than apply or check falls through to the default, which is apply. The token is then read as the target repository. So repo-config/configure.sh --help prints Applying configuration to --help (model: release) and starts writing. On 2026-10-02 the first API call returned 404, since no repository is named --help, and nothing was written. A token that names a real repository under the logged-in account would have started a configuration write against it.

Survey

• Python CLIs under scripts/ use argparse, which answers --help and refuses an unknown option. The .sh and .ps1 wrappers exec them with "$@" and inherit that. prose_lint.py and repo_gate.py are shims that load a package, and their parsers want the same confirmation.
• The host-setup/ shell and PowerShell entry points handle --help/-Help.
• repo-config/configure.sh has no help. Its unknown first argument becomes an apply target, as described above.
• Hooks under host-setup/agent-safety/claude/ are not command-line tools and are out of scope.

Proposal

1. The rule. Every command-line script the hub ships either answers --help (and -h) by printing its usage and exiting 0 with nothing written, or refuses an argument it does not recognize, exiting non-zero before any read or write. A script that can write does both. No script falls back to a default mode or target when its first argument is unrecognized, and a write mode is never the default. State this in CODESTYLE.md (General, and the Shell section) and in shell-codestyle.
2. configure.sh. Add --help/-h, require the mode explicitly rather than defaulting to apply, and refuse an unknown option or a target that is not shaped owner/name before any API call.
3. A gate. Add a test that runs every tracked command-line entry point with --help and with an unknown --bogus-flag, in a sandbox with no network or credentials, and asserts the first exits 0 with usage text and the second exits non-zero, neither making any API call.