140-bash

Bash Engineering Gates

This rule owns mandatory policy only. Use the Bash skill (${HANDBOOK_ROOT}/skills/bash-shell-scripting/SKILL.md) for authoring patterns and the automation skill (${HANDBOOK_ROOT}/skills/scripting-automation/SKILL.md) for retries, locks, signals, idempotency, and BATS.

Shell and Error Semantics

• Declare the intended interpreter. Use #!/usr/bin/env bash only when Bash features are required; do not claim POSIX sh portability while using Bash syntax.
• For new non-trivial Bash scripts, use set -euo pipefail or document a controlled alternative when expected nonzero statuses make errexit unsafe.
• Handle expected failures explicitly with if, case, ||, or a narrowly scoped error-mode change. Never hide failures with blanket || true.
• Use an ERR trap only when it adds actionable context; it is not a substitute for explicit error handling.

Data and Argument Safety

• Quote expansions by default: "${value}", "${array[@]}", and "$@".
• Preserve argument boundaries. Never use unquoted $@, $*, command output, or glob expansion as an argument list.
• Use arrays for command arguments. Do not build commands as strings and do not use eval on untrusted or dynamically assembled data.
• Validate allowlisted formats before passing external input to commands, paths, regular expressions, or interpreters.
• Use printf, not echo -e, for deterministic output.

Files, Processes, and Secrets

• Create temporary files and directories with mktemp; install a cleanup trap immediately after successful creation.
• Quote paths, use -- before user-controlled path operands where supported, and avoid predictable temporary names.
• Check command availability before use and fail with a clear remediation message.
• Do not expose secrets through command-line arguments, tracing, logs, process listings, or generated files. Disable set -x around sensitive operations.
• Bound retries, waits, and background processes; preserve exit status and clean up children on termination.