hmbown--codewhale/docs/evidence/hotbar-qa-matrix.md

Hotbar QA Matrix

This matrix is the v0.8.66 release gate for #3401. It ties the shipped Hotbar MVP to repeatable checks instead of treating isolated unit tests as sufficient coverage.

Support Level

Source	Support level	Release statement
Built-in app actions	Supported	Default slots dispatch existing app paths through AppAction or in-app state mutation.
Slash commands	Supported	Argument-free and optional-argument commands dispatch through commands::execute; required-argument commands prefill the composer.
MCP tools/resources/prompts	Deferred	Visible through the command palette/MCP manager only until argument and approval gates are wired.
Skills	Deferred	Visible through command palette and slash skill activation; direct Hotbar binding is deferred until activation receipts are wired.
Plugins	Deferred	Visible through /plugins; direct Hotbar binding is deferred until plugin approval gates are wired.

Config States

Scenario	Expected behavior	Evidence
No hotbar config	Default slots resolve to the shipped eight-slot bar.	crates/config/src/tests.rs::hotbar_defaults_when_config_is_absent
Empty hotbar config	hotbar = [] disables all default slots.	crates/config/src/tests.rs::hotbar_empty_array_disables_default_slots; crates/tui/src/config_persistence.rs::persist_hotbar_bindings_writes_empty_array_to_disable_defaults
Partial config	Missing slots render empty without filling from defaults.	crates/tui/src/tui/sidebar.rs::hotbar_panel_slots_handle_empty_partial_and_unknown_config
Unknown actions	Unknown configured actions stay visible as unknown instead of being dropped silently.	crates/config/src/tests.rs::hotbar_validation_warns_without_dropping_unknown_actions; crates/tui/src/tui/sidebar.rs::hotbar_panel_slots_handle_empty_partial_and_unknown_config
Custom labels	Configured labels render and persist with bindings.	crates/tui/src/tui/hotbar/actions.rs::recommended_hotbar_bindings_serialize_action_ids_and_labels; crates/tui/src/tui/ui/tests.rs::hotbar_setup_save_persists_bindings_to_config_path
Workspace overlay	Project config does not replace user-owned Hotbar bindings.	crates/config/src/tests.rs::project_merge_does_not_replace_user_hotbar_bindings
Legacy/user config path	Fresh setup writes the primary config path; existing comments survive replacement.	crates/tui/src/config_persistence.rs::persist_hotbar_bindings_writes_primary_config_path_for_fresh_installs; crates/tui/src/config_persistence.rs::persist_hotbar_bindings_preserves_comments_and_replaces_existing_tables
Failed persistence	Live config and config file remain unchanged and an error is surfaced.	crates/tui/src/tui/ui/tests.rs::hotbar_setup_save_error_leaves_live_config_and_file_unchanged

UI States

Scenario	Expected behavior	Evidence
Normal TUI/composer	Alt-1 through Alt-8 dispatch configured slots; bare digits remain text input.	crates/tui/src/tui/ui/tests.rs::hotbar_alt_digit_fires_from_composer_and_sidebar_states; crates/tui/src/tui/ui/tests.rs::hotbar_bare_digit_inserts_text_even_when_composer_empty
Hidden/sidebar focus states	Hotbar dispatch is still available from hidden, auto, pinned, and focused sidebar states.	crates/tui/src/tui/ui/tests.rs::hotbar_alt_digit_fires_from_composer_and_sidebar_states
Narrow sidebar	Hotbar panel keeps fixed two-row layout and bounded hover/status text.	crates/tui/src/tui/sidebar.rs::hotbar_panel_lines_keep_two_fixed_rows_and_hover_status; docs/evidence/terminal-visual-regression-matrix.md
Modal/overlay open	Modal, approval, picker, decision-card, and onboarding states block Hotbar numeric ownership.	crates/tui/src/tui/ui/tests.rs::hotbar_digits_are_blocked_while_modal_or_onboarding_is_active; crates/tui/src/tui/ui/tests.rs::hotbar_alt_digit_is_blocked_while_inline_selectors_are_open; crates/tui/src/tui/ui/tests.rs::hotbar_alt_digit_is_blocked_while_decision_card_is_active
Setup wizard open/save	Setup lists supported source categories, updates draft bindings, saves, and persists.	crates/tui/src/tui/hotbar/setup.rs::wizard_sources_follow_registered_action_categories; crates/tui/src/tui/hotbar/setup.rs::wizard_save_emits_bindings_but_escape_only_closes; crates/tui/src/tui/ui/tests.rs::hotbar_setup_save_persists_bindings_to_config_path
Restart/re-dispatch	Persisted bindings parse back into config and resolve through the same dispatch path.	crates/config/src/tests.rs::hotbar_tables_parse_and_round_trip; crates/tui/src/tui/ui/tests.rs::hotbar_dispatches_bound_slot_and_ignores_empty_slot

Dispatch Outcomes

Outcome	Expected behavior	Evidence
Handled in-app	Local UI/state actions mutate app state and mark redraw when needed.	crates/tui/src/tui/hotbar/actions.rs::sidebar_toggle_reports_visibility_and_dispatches; crates/tui/src/tui/hotbar/actions.rs::trust_toggle_reports_trust_state_and_dispatches
AppAction return	Actions that must be handled by the event loop return the existing AppAction.	crates/tui/src/tui/hotbar/actions.rs::compact_action_emits_existing_app_action; crates/tui/src/tui/ui/tests.rs::hotbar_dispatches_bound_slot_and_ignores_empty_slot
Composer prefill	Required-argument slash commands prefill the composer instead of firing empty args.	crates/tui/src/tui/hotbar/actions.rs::slash_hotbar_action_prefills_required_argument_command
Disabled reason	Disabled actions are excluded from recommendations and report a reason if manually bound.	crates/tui/src/tui/hotbar/actions.rs::hotbar_recommendations_exclude_disabled_actions; crates/tui/src/tui/ui/tests.rs::hotbar_bound_disabled_action_reports_reason_without_dispatching
Unknown action	Unknown configured action is visible and does not dispatch.	crates/tui/src/tui/sidebar.rs::hotbar_panel_slots_handle_empty_partial_and_unknown_config; crates/tui/src/tui/ui.rs::dispatch_hotbar_slot
Approval-gated/deferred source	Source is explicitly deferred and must not register bindable actions before gates exist.	crates/tui/src/tui/hotbar/actions.rs::source_descriptors_cover_dispatch_boundaries; crates/tui/src/tui/hotbar/actions.rs::deferred_sources_cannot_register_dispatchable_actions

Release Smoke Checklist

Run before claiming Hotbar MVP readiness:

1. cargo test -p codewhale-config hotbar -- --nocapture
2. cargo test -p codewhale-tui --bin codewhale-tui --locked hotbar::actions -- --nocapture
3. cargo test -p codewhale-tui --bin codewhale-tui --locked hotbar_setup -- --nocapture
4. cargo test -p codewhale-tui --bin codewhale-tui --locked hotbar_panel -- --nocapture
5. cargo test -p codewhale-tui --bin codewhale-tui --locked hotbar_alt_digit -- --nocapture
6. cargo test -p codewhale-tui --bin codewhale-tui --locked hotbar_dispatch -- --nocapture

Manual pass, if a release candidate binary is available:

1. Start with no [hotbar] config and verify the default eight slots render in the sidebar with visible Alt1 through Alt8 accelerator labels.
2. Open /hotbar, bind a slash command, save, restart, and verify the binding persists.
3. Press Alt-1 through Alt-8 from composer/sidebar states and verify only Alt chords dispatch.
4. Open command palette, slash menu, setup wizard, decision card, and an approval modal; verify Hotbar digits are blocked while those surfaces own input.
5. Confirm MCP, skill, and plugin entries remain discoverable through their existing command-palette or slash-command paths and are not offered as direct Hotbar bindable actions.