Migrate compatible basectl option parsers to the shared arg_parse contract

[codeforester]

Goal

Migrate compatible basectl option parsers to the shared arg_parse contract and reduce repeated shell parsing policy.

Background

Production shell currently contains dozens of manual while (($#)) parser loops across many command files, while only a small surface uses the shared argument-parsing helper. The duplication creates inconsistent handling of usage errors, pass-through arguments, repeated options, and the repository-wide --option=value policy.

#1435 adopted argument helpers in a narrow initial slice and explicitly deferred complex or repeated-option parsers. Generic repo.sh and setup_common.sh splitting has already been addressed by #1072, #1563, #1570, and #1591; this issue is specifically about parser contracts, not file size.

Scope

• Inventory command parsers compatible with the current shared arg_parse helper.
• Migrate a first low-risk group with equivalent flags and positional behavior.
• Preserve usage text, exit code 2 behavior, -- pass-through, and the current rejection of --option=value where applicable.
• Record blockers for commands with repeated flags, interleaved positionals, or command-specific semantics.
• Add focused parser contract tests before each migration slice.

Acceptance Criteria

• The first compatible command group uses the shared parser contract.
• User-visible parsing, errors, and exit codes remain stable.
• Repeated or complex parsers are explicitly inventoried rather than forced into an unsuitable abstraction.
• New compatible command parsers have a documented default helper path.
• Focused tests cover successful parsing and important rejection cases.

Validation

• Focused BATS for migrated commands.
• Shared argument parser tests.
• Bash and Zsh syntax checks.
• ShellCheck for touched files.
• git diff --check.

Non-Goals

• Do not rewrite repo.sh or gh.sh wholesale.
• Do not change public flag syntax in this issue.
• Do not weaken special handling for repeated options or pass-through arguments.

Project Fields

• Status: Backlog
• Priority: P3
• Size: M
• Area: Shell
• Initiative: Contract Hardening

Agent Assignment

Agent-ready after a human chooses the first compatible command group. Keep migrations small and behavior-preserving.