Make command metadata canonical across help, dispatch, and completions

[codeforester]

Goal

Create one canonical source for Base command metadata so help, dispatch validation, completions, references, and tests cannot silently diverge.

Background

Top-level help currently lists workspace commands without the shipped workspace onboarding subcommand, while nested workspace help, dispatch, and shell completions include it. Existing tests pass because different tests encode the inconsistent surfaces.

Closed issues #1055, #1067, and #1487 repaired individual completion drift, while #1192 added contract checks. Those repairs did not remove the multiple sources of truth.

Scope

• Define a canonical command record containing at least command/group name, summary, aliases, subcommands, flags, and stability tier where applicable.
• Pilot the model on the workspace command family, including onboarding.
• Generate or validate top-level help, nested help, dispatch metadata, Bash/Zsh completions, and command-reference data from the canonical record.
• Add a regression proving a new command cannot be shipped on only one surface.
• Document which shell-stateful behaviors remain hand-written.

Acceptance Criteria

• workspace onboarding appears consistently across every public discovery surface.
• Workspace command metadata has one authoritative definition.
• Tests fail when help, dispatch, completions, or command reference drift.
• The pilot establishes a documented migration path for other command families.
• Public command names and behavior remain backward compatible.

Validation

• Focused BATS for help, workspace dispatch, and completions.
• Any focused Python tests for generated metadata.
• Bash and Zsh syntax checks.
• Contract test runner.
• git diff --check.

Non-Goals

• Do not rewrite the entire CLI in one issue.
• Do not move shell-state mutation into Python.
• Do not change existing command names solely for aesthetic consistency.

Project Fields

• Status: Backlog
• Priority: P2
• Size: M
• Area: CLI
• Initiative: Contract Hardening

Agent Assignment

Human first for the canonical format and workspace pilot. Keep the initial implementation narrow and behavior-preserving.