feat(cli): publish clean, grouped help instead of developer docstrings (#389)

[jasonssdev]

Refs #389 — this carries its help-surface bullets (1 and 2). The remaining four (the reconcile/list vocabulary mismatch, the init embedding-warning placement, and the two doctor items) stay open; #389 explicitly says to split any bullet that grows, and this one did.

What a user actually read before

Typer publishes each command's raw __doc__ unless the command sets help=. No command did. So --help showed things like:

Wires the pure bundle.provenance.resolve_backfill_raises sweep core (design D4/D5) into Typer's confirm-gate

along with decision #717, MVP-3 gap #8 S2a, Slice 1 and ADR-0003.

There was never a choice to make between traceability and a clean surface — help= decouples them. All 26 commands now publish a user-facing line while their docstrings keep every reference maintainers rely on. This matters past --help: MCP tool descriptions are usually derived from the same source, and text that does not help a person will not help an agent.

Grouping, and the part grouping alone did not fix

The 26 commands were listed flat in declaration order, which put purge — irreversible and rare — fourth, while query, the value moment, sat near the bottom. They are now grouped into five panels by what the reader is trying to do: get started, explore, curate, maintain, remove. The rule is written down next to the app so the next contributor applies it rather than matching the nearest-looking neighbour.

Grouping by itself made things worse in one respect, which only showed up on rendering the real output: Rich prints a panel when it first meets a command belonging to it, so declaration order still decided panel order and Remove landed second — the irreversible verbs more prominent than the flat list had them. PANEL_ORDER plus a stable sort of the registry makes reading order explicit instead of a side effect of where a function sits in the file.

Three review rounds, each catching what the last missed

This branch went through three full review cycles. Recording what each found, because the pattern is the point:

Round 1 shipped clean help but left the panel ordering above.

Round 2 found two published lines that were clean but wrong — the real hazard of a sweep like this. adjudicate published "Decide which candidate duplicates are really the same concept, with the model proposing and you confirming", which reads as though invoking it performs merges; its own docstring says the plain invocation is read-only and writing needs a separate flag. suggest-volatility omitted the writes-nothing reassurance its three sibling read-only verbs all state. It also caught a published option help string on forget --scope still carrying the internal token S2a, which the jargon test had passed over because it matched only fixed substrings.

Round 3 fixed an anchor in one of the very patterns round 2 added: \bSlice \d+\b matched a bare Slice 1 but missed Slice 2a and Slice 2b-ii, because there is no word boundary between a digit and the letter after it — and the lettered forms are the ones this codebase mostly uses.

Separately, the sweep's first draft dropped a bounded-scope honesty statement from set-sensitivity's published help that a pre-existing test requires to stay published. The suite caught it, which is exactly what that test is for.

Verification

• uv run pytest -q → 4025 passed, 1 skipped. uv run mypy . → Success, 179 files. ruff check / ruff format clean and convergent.
• Both headline behaviors driven RED→GREEN.
• The strengthened jargon test was mutation-verified: restoring S2a to the published option help fails it with {'forget': ['S2a']}; the substring-only version passed that same mutation, which is why it was replaced.
• The corrected slice pattern was measured against all three real forms plus two near-misses before commit.
• The panel failure now names the command, its bad value and the allowed set. Failing at import is deliberate — a misplaced command should not ship quietly — but failing mutely was not.

Native review

Three lineages, all approved with receipts, all zero blockers: review-6e884bb4642ac6fb (high, 4R), review-f3a75ff7d21f93f8 (high, 4R), review-5c4e2c90128c01d4 (medium, one lens, zero findings).

pre-pr denies this PR, same structural reason as #498, #499 and #500: it measures the whole branch against origin/main while each receipt binds its own increment, so no single receipt covers the union. receipt-binding / candidate-or-paths-mismatch, action explicit-maintainer-action. Every changed line was reviewed and approved.