Skip to content

013. Shell Support Tier Strategy

Date: 2026-02-15

Status

Accepted

Context

This repository supports both zsh and bash, but previous behavior did not clearly define support tiers. A custom Bash Enter key remap caused unstable terminal behavior and showed that shell customization boundaries were not explicit enough.

We need a long-term strategy that:

  1. Keeps advanced interactive UX where it is strongest.
  2. Keeps server and homelab shells stable and predictable.
  3. Prevents shell-specific features from leaking into shared paths.

Decision

We adopt a tiered shell strategy:

  1. Tier 1 (Full Interactive UX): zsh
  2. Primary shell for workstation environments.

  3. Advanced prompt/plugins/keybindings live in dot_zshrc.tmpl.

  4. Tier 2 (Stable Baseline): bash

  5. First-class supported baseline for servers/homelabs and minimal environments.

  6. dot_bashrc must prioritize terminal safety and compatibility.

  7. Boundary Rules

  8. Shell-specific behavior must remain in shell-specific files.
  9. Shared files (for example dot_aliases) must avoid shell-breaking assumptions.

  10. Bash must not remap Enter (Ctrl-M) via bind -x.

  11. Install and Health-Check Behavior

  12. Workstation installs may set default shell to zsh when allowed.
  13. Server-mode installs keep current shell unchanged by default.
  14. Doctor accepts both bash and zsh as supported shells.

Consequences

Positive

  • Better reliability for headless/server environments.
  • Clear UX expectations by environment.
  • Lower risk from shell-hook regressions.
  • Keeps existing zsh productivity investment.

Negative

  • Requires ongoing discipline to maintain boundaries.
  • Some features are intentionally unavailable in baseline Bash mode.

Compliance

  • Shell support tiers documented in installation and troubleshooting docs.
  • Agent guidance updated with shell policy.
  • Installer behavior aligned with server-mode defaults.
  • Test guardrails added for Bash safety rules.

Addendum (2026-02-17): Bash Baseline Hardening

To better align baseline Bash reliability with established shell policy:

  • Optional Bash tool initialization must be guarded (mise, zoxide, direnv, atuin) so missing binaries do not break shell startup.
  • Bash sessions identified as AI/agent contexts must use isolated history and disable Atuin sync for that session.
  • Bash baseline history defaults should favor durability and low-noise history (append, dedup, ignore-space, prompt-time persistence).
  • These behaviors must be covered by tests to prevent regressions.

Addendum (2026-02-16): Public Task API Stability

To reduce shell and automation drift, we treat top-level mise task names as the public task API:

  • Public API examples: install, update, doctor, test, lint, setup-secrets.
  • Internal namespaces (maintain:*, dev:*, setup:*) are implementation details.
  • Docs, scripts, and workflows must prefer public names for user-facing flows.

Deprecation Policy

When task internals change:

  1. Keep existing public task names stable by updating wrapper delegation.
  2. If a public name must be renamed, keep a compatibility wrapper for at least one minor release.
  3. Mark the old name as deprecated in docs and changelog before removal.
  4. Enforce compliance in CI with contract checks and shell smoke tests.