You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Make command metadata canonical across help, dispatch, and completions #1606
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.
Activity
codeforester commentedon Oct 15, 2026
Pulled into v1.12.0: this is a prerequisite for the agent-loop, MCP, and matrix work tracked in #2555.