GW-030: Complete human CLI renderer, strict help, quiet/verbose/progress

[trippyogi]

Outcome

Complete the human CLI experience: strict and useful help, action-oriented multi-line rendering, clean stdout/stderr separation, and consistent quiet/verbose/progress behavior across primary commands.

Machine users should consume JSON; humans should receive concise output that explains the verdict, next action, strongest evidence, completed checks, and limitations without reading raw envelopes.

Why this matters

Gitworthy's agent/MCP contract is primary, but the CLI is the debugging surface, onboarding path, CI interface, and fallback for every integration. A one-line or inconsistent renderer makes first use harder and encourages agents or scripts to parse prose.

Scope

• Add practical command help with examples, defaults, bounds, exit codes, and common remediation.
• Ensure unknown flags and invalid combinations remain strict and structured.
• Implement multi-line human renderers for check, hunt, scan, doctor, brief, store, outcome, and partial-run results.
• Route JSON to stdout only and progress/diagnostics to stderr.
• Add consistent --quiet, --verbose, and progress behavior.
• Make color/TTY behavior accessible and disable safely for pipes/CI.
• Include verdict/disposition, summary, next action, strongest evidence URL, checked/not-checked coverage, and partial/error status.
• Never require machine consumers to parse human output.

Non-goals

• No interactive TUI.
• No dashboard.
• No rewriting core verdict policy in the renderer.
• No progress logs on MCP stdio stdout.

Dependencies and readiness

• Depends on GW-007 / issue GW-007: Add strict input validation and structured CLI/MCP errors #16, completed by PR GW-007: Strict CLI/MCP input validation and structured errors #54.
• Depends on GW-028 / issue GW-028: Add complete compact hunt decisions, partial persistence, and resume #37.
• Contributor readiness: BLOCKED until GW-028: Add complete compact hunt decisions, partial persistence, and resume #37 lands. Help and renderer design can be reviewed earlier.

Acceptance criteria

• Every primary command has accurate strict help and at least one realistic example.
• JSON mode emits only the versioned result on stdout.
• Human mode is multi-line, action-oriented, and displays limitations prominently.
• --quiet suppresses progress while preserving final output and errors.
• --verbose adds provider timing/counters without secrets.
• Non-TTY output is stable and free of forced ANSI codes.
• Partial runs, invalid input, auth/rate limits, and operational failures render distinctly.
• Stable exit codes remain: 0 ACT/success, 10 VERIFY/warning, 20 SKIP, 2 invalid input, 1 operational failure.
• CLI docs and snapshots match actual output.

Tests and validation

• Golden snapshots for all verdicts, dispositions, doctor states, partial runs, and errors.
• stdout/stderr separation tests.
• TTY/non-TTY, color/no-color, quiet/verbose matrix.
• Help completeness and invalid-flag tests.
• Secret-redaction tests for verbose diagnostics.
• Packed-package smoke tests for help, version, check, and doctor.
• Accessibility review for color-independent verdict labels.

Suggested check rendering

SKIP · land_only
Open PR #4499 explicitly closes issue #4487.

Next
  Review or help land #4499. Do not open a parallel implementation.

Evidence
  definitive · PR #4499 · https://github.com/.../pull/4499

Checked
  target, policy, linked work

Not checked
  main-tree and duplicate checks skipped after definitive open PR.

Likely implementation areas

• CLI command metadata/help definitions.
• Human renderer modules separate from contracts.
• Progress and diagnostic channel abstraction.
• Snapshot fixtures and docs.

Compatibility

Human output may improve, but JSON contracts and exit-code semantics must remain stable. Release notes should warn users not to parse human text.

[trippyogi]

Shipped initial slice in #75 (multi-line human renderer, --quiet/--verbose). Remaining AC items (strict per-command help, full snapshot matrix, TTY/color) stay open.