Skip to content

Shell Support Compliance Plan

Status: ✅ Completed Created: 2026-02-15 Archived: 2026-02-16 Decision Source: ADR-013

Goal

Perform a full repository compliance sweep so shell behavior matches ADR-013 everywhere:

  • zsh: full interactive UX tier.
  • bash: stable baseline tier.
  • Shared files: safe in both shells.

Why This Plan Exists

ADR-013 defines policy. This plan is the execution checklist for verification and closure of remaining gaps.

Implementation Summary (2026-02-15)

  • Updated mise-tasks/maintain/doctor to treat Bash baseline as supported without requiring Zsh.
  • Updated mise-tasks/setup/install so server mode skips Antidote installation.
  • Updated shell-policy tests in tests/doctor.bats, tests/provisioning.bats, and tests/server_deployment.bats.
  • Updated troubleshooting restart guidance to shell-agnostic restart commands.

Scope

In scope:

  • Dotfiles and shell config (dot_bashrc, dot_zshrc.tmpl, dot_aliases).
  • Installer/doctor/runtime scripts (mise-tasks/*, scripts/*).
  • Tests and CI guardrails.
  • User docs and agent guidance.

Out of scope:

  • Large UX redesign for shell prompts/plugins.
  • New tool additions unrelated to shell policy.

Execution Workflow

  1. Branch and Baseline
  2. Create a branch for compliance work.
  3. Capture baseline outputs for comparison.

  4. Run: 

    git status --short
bash -n dot_bashrc dot_aliases scripts/bootstrap mise-tasks/setup/install mise-tasks/maintain/doctor

  5. Inventory Shell-Specific Patterns

  6. Find risky or shell-specific patterns: 
    rg -n "bind -x|\\\\C-m|setopt|unsetopt|bindkey|add-zsh-hook|zle|compinit|source ~/.config/welcome\\.zsh" -S
  7. Classify each hit as:
  8. zsh-only (expected)
  9. bash-safe (expected)

  10. shared-file risk (must fix)

  11. Apply Policy Boundaries

  12. dot_bashrc:
  13. no Enter remaps (bind -x ... \C-m forbidden)
  14. no Zsh-only primitives
  15. dot_zshrc.tmpl:
  16. advanced interactive behavior allowed
  17. dot_aliases:
  18. keep shared commands shell-safe
  19. gate/dispatch zsh-only behavior explicitly
  20. Installer and doctor:
  21. server mode keeps baseline shell

  22. doctor treats bash and zsh as supported

  23. Test/Guardrail Coverage

  24. Ensure tests assert policy and catch regressions.
  25. Minimum checks: 
    bash -n dot_bashrc dot_aliases scripts/bootstrap mise-tasks/setup/install mise-tasks/maintain/doctor
zsh -n dot_aliases
mise run test -- tests/configs.bats tests/provisioning.bats tests/doctor.bats

  26. If mise is unavailable: 

    bats tests/configs.bats tests/provisioning.bats tests/doctor.bats

  27. Docs and Agent Consistency

  28. Confirm docs reflect shell tiers and restart guidance.
  29. Confirm AGENTS.md guidance matches ADR-013.
  30. Ensure links/nav include ADR-013 and this plan as needed.

Acceptance Criteria

  • No Bash Enter remap in repository-managed Bash config.
  • Shared shell files do not directly execute Zsh-only constructs without guards.
  • Server mode does not force shell changes.
  • Doctor messaging accepts both supported shells.
  • Tests include explicit shell-policy guardrails.
  • Installation/troubleshooting docs state tiered shell policy.

Evidence to Include in PR

  • git diff --stat
  • Output of syntax checks
  • Output of targeted test run
  • Short list of policy gaps fixed
  • Any intentionally deferred items with rationale

Handoff Template (for another AI)

Use this exact structure in the final report:

  1. Files audited
  2. Policy violations found
  3. Fixes applied
  4. Validation output summary
  5. Remaining risks or follow-ups

Rollback Strategy

If regressions appear:

  1. Revert only the offending commit(s).
  2. Re-run syntax and targeted shell-policy tests.
  3. Re-apply fixes incrementally with narrower scope.