orro --help must show the surface it actually has (0.2.25)

[moonweave]

Fixes Moonweave-Systems/witnessd#228.

What happened to a real operator

An agent session followed the ORRO skill document, probed the installed CLI first, and saw this:

usage: orro [-h] [--engine-command ENGINE_COMMAND] [--json] [--version]
            {boundary,self-test,delegate} ...

None of setup, flow, ship or proofrun appeared, so it concluded the install was a legacy shim, declared ORRO not runnable on that machine, and fell back to calling Codex directly. The install was healthy — the wrapper auto-delegates any unknown first argument to the pinned engine, and every documented command worked.

Reproduced from the published package: pip install orro==0.2.24 in a fresh venv gives exactly that. The tiered command list was present, but in the argparse epilog, more than twenty lines down past the whole options block. The first screen advertised a three-command surface.

This is the claim-versus-reality drift this project exists to catch, aimed at itself. Nothing was broken except what the tool said about itself, and that was enough for a careful reader to walk away.

What changed

usage: now enumerates the delegated commands as real subcommands, and the line immediately after it states that they are delegated to the pinned engine and that the wrapper implements no engine logic. The surface is legible where a reader already looks, rather than further down.

orro self-test gained a doc↔surface parity check: every public command named in the packaged skill documents must resolve through the wrapper's dispatch. Both lists come from their existing single sources rather than a new hardcoded copy. Verified in both directions — adding a reference to a non-existent command in the packaged skill document makes self-test fail with ERR_ORRO_WRAPPER_SURFACE_PARITY, naming the offending command; removing it passes again. Drift is now a failing test rather than a support incident.

Installation docs record that the console script is the only supported entrypoint. uv run python3 -m orro resolves through ambient project-venv discovery to an unrelated environment and reports No module named orro, which reinforced the wrong conclusion in the reported session.

Scope

No command added, removed or renamed; delegation behaviour unchanged; the wrapper remains a wrapper. Verified from a wheel in a fresh virtual environment rather than the checkout, because this defect is only visible in an installation: orro flow, orro setup and orro ship all still delegate correctly.

🤖 Generated with Claude Code