Shell Scripting Standards

Coding quality standards and best practices for all .sh (Bash) and .ps1 (PowerShell) scripts within DAAF. Covers preamble conventions, quoting discipline, error handling philosophy, signal/cleanup patterns, Docker interaction, output formatting, testing strategies, and cross-platform gotchas. Use when authoring new shell scripts (hooks, Docker lifecycle, utilities), reviewing existing scripts for compliance, debugging script failures, or setting up CI for shell code.

Boundary with bash-safety.sh: This skill governs how to write good scripts (coding quality). The bash-safety.sh hook governs what commands are safe to run (runtime safety enforcement). A script can follow every standard in this skill and still be blocked by bash-safety.sh if it contains a dangerous command like rm -rf /. Conversely, a script that passes bash-safety.sh may still be poorly written if it ignores these standards.

Host launcher shims (scripts/host/*.command, scripts/host/*.bat): These standards also apply to the double-click launcher shims. A .command shim is a Bash script that runs on the user's macOS machine, so it follows the host-script Bash 3.2 + BSD userland rules in bash-standards.md. A .bat shim is a Windows batch file that ships with CRLF line endings (declared *.bat -text in .gitattributes, since the installer downloads the raw blob) and ASCII content, and is kept a thin passthrough shim (change into its own folder, verify the delegate is present, hand off to daaf.ps1) rather than growing logic of its own.

How to Use This Skill

Reference File Structure

File	Purpose	When to Read
bash-standards.md	Preambles, quoting, variables, ShellCheck, signal handling, host-script Bash 3.2 portability	Writing or reviewing any .sh file; anything under scripts/host/
powershell-standards.md	Preambles, dual error system, defensive coding, PSScriptAnalyzer	Writing or reviewing any .ps1 file
error-handling.md	Fail-closed philosophy, output conventions, exit codes, Docker errors, dependency validation	Designing error paths for any script
testing.md	BATS, Pester, CI workflows, Docker mocking, test taxonomy, DAAF safety-hook regression batteries	Setting up or running script tests; writing or modifying a bash-safety.sh / enforce-single-command.sh hook
gotchas.md	Bash traps, PowerShell surprises, cross-platform pitfalls	Debugging unexpected script behavior

Reading Order

1. Writing a Bash script? Start with bash-standards.md, then error-handling.md
2. Writing a PowerShell script? Start with powershell-standards.md, then error-handling.md
3. Setting up tests? Read testing.md
4. Script behaving unexpectedly? Go straight to gotchas.md
5. Reviewing a script? Skim bash-standards.md or powershell-standards.md for the compliance checklist, then error-handling.md for error-path quality

Quick Decision Trees

"I need to write a script"

What kind of script?
├─ Bash (.sh)
│   ├─ Preamble and structure → ./references/bash-standards.md
│   ├─ Error handling design → ./references/error-handling.md
│   ├─ Signal handling / cleanup → ./references/bash-standards.md
│   └─ Scratch probe that makes symlinks (self-cleaning) → ./references/bash-standards.md
├─ PowerShell (.ps1)
│   ├─ Preamble and structure → ./references/powershell-standards.md
│   ├─ Native command error handling → ./references/powershell-standards.md
│   └─ Error handling design → ./references/error-handling.md
└─ Either language
    ├─ Docker interaction → ./references/error-handling.md
    ├─ User-facing output → ./references/error-handling.md
    └─ Cross-platform concerns → ./references/gotchas.md

"I need to review a script"

Reviewing a script?
├─ Bash compliance check
│   ├─ Preamble correct? → ./references/bash-standards.md
│   ├─ Quoting discipline? → ./references/bash-standards.md
│   ├─ ShellCheck clean? → ./references/bash-standards.md
│   └─ Error paths robust? → ./references/error-handling.md
├─ PowerShell compliance check
│   ├─ Preamble correct? → ./references/powershell-standards.md
│   ├─ Native command handling? → ./references/powershell-standards.md
│   ├─ PSScriptAnalyzer clean? → ./references/powershell-standards.md
│   └─ Error paths robust? → ./references/error-handling.md
└─ Either language
    ├─ Run parser/linter/tests in-container? → ./references/testing.md
    │   (DAAF_DEV toolchain: pwsh, Pester, PSSA, shellcheck, bats --
    │    PROBE for tools before declaring validation unavailable)
    ├─ Exit code conventions? → ./references/error-handling.md
    └─ Known gotchas present? → ./references/gotchas.md

"Something is broken"

Script behaving unexpectedly?
├─ Bash
│   ├─ Exit code masked → ./references/gotchas.md (local var=$(cmd))
│   ├─ Variable empty/unset → ./references/bash-standards.md (nounset)
│   ├─ Pipeline hiding failure → ./references/bash-standards.md (pipefail)
│   └─ cd went to wrong dir → ./references/gotchas.md (cd without || exit)
├─ PowerShell
│   ├─ Native command error ignored → ./references/gotchas.md ($LASTEXITCODE)
│   ├─ Unexpected return value → ./references/gotchas.md (implicit returns)
│   ├─ $null in ForEach loop → ./references/gotchas.md
│   ├─ Validation not firing → ./references/gotchas.md (omitted params)
│   └─ irm | iex fails with BOM error → ./references/gotchas.md (UTF-8 BOM)
└─ Cross-platform
    ├─ Env var case mismatch → ./references/gotchas.md
    ├─ Aliases missing → ./references/gotchas.md
    └─ Exit code truncated → ./references/gotchas.md

"I need to set up tests"

Testing shell scripts?
├─ Bash testing
│   ├─ BATS setup → ./references/testing.md
│   ├─ Mocking Docker → ./references/testing.md
│   └─ What to test → ./references/testing.md
├─ PowerShell testing
│   ├─ Pester setup → ./references/testing.md
│   ├─ Mocking native commands → ./references/testing.md
│   └─ What to test → ./references/testing.md
└─ CI integration
    ├─ GitHub Actions matrix → ./references/testing.md
    ├─ Lint-only vs full test → ./references/testing.md
    └─ Path filtering → ./references/testing.md

DAAF Script Conventions (Quick Reference)

Existing patterns in DAAF scripts that this skill codifies:

Convention	Description	Example
Strict preamble	set -euo pipefail (Bash) / $ErrorActionPreference = 'Stop' (PS)	Every script, first lines
Numbered progress	[1/4] Checking prerequisites...	All multi-step scripts
DAAF_NESTED flag	Suppress pause-before-exit when scripts compose	[ "${DAAF_NESTED:-}" = "1" ] && exit $ec
ERR trap pattern	Catch unexpected failures, explain recovery	trap 'echo "ERROR: ..."; exit 1' ERR
Preflight checks	Validate all dependencies before any mutation	command -v docker before Docker ops
Idempotent design	Check for prior state before acting	[ -f "$BACKUP" ] && echo "Already backed up"
Fail-closed hooks	Security hooks block on uncertainty	trap ... ERR; exit 2
Backup before destroy	Copy before overwriting	cp -r "$TARGET" "$TARGET.bak"

Bash Compliance Checklist (Summary)

#	Requirement	Quick Check
1	#!/usr/bin/env bash shebang	First line
2	set -euo pipefail	Second line
3	All variables quoted	"$var", "$(cmd)"
4	local separate from $(cmd)	local x; x=$(cmd)
5	No eval, no backticks	Grep for both
6	trap cleanup EXIT for temp files	After variable declarations
7	ShellCheck clean	shellcheck -x -S warning
8	Errors to stderr with action guidance	echo "ERROR: ..." >&2

PowerShell Compliance Checklist (Summary)

#	Requirement	Quick Check
1	$ErrorActionPreference = 'Stop'	First line
2	Set-StrictMode -Version 3.0	Second line (DAAF exception: scripts with a DAAF_TEST_MODE dot-source guard place it immediately after the guard; dot-sourced libraries like daaf_lib.ps1 carry no directive -- see powershell-standards.md > "Strict Mode Placement in DAAF Host Scripts")
3	$LASTEXITCODE checked after every native command	After docker, git, etc.
4	[CmdletBinding()] on functions	Function declarations
5	$null = expr not | Out-Null	Performance
6	No reliance on $? for native commands	Grep for $? near docker/git
7	PSScriptAnalyzer clean	Invoke-ScriptAnalyzer
8	Errors via Write-Error with guidance	Error output
9	ASCII-only content (no BOM)	file script.ps1 reports "ASCII text"
10	No interactive native commands in expression-context function calls	No if (Fn), $x = Fn for functions with docker exec, ssh, etc.

Exit Code Conventions

Code	Meaning	Used By
0	Success	All scripts
1	General error	All scripts
2	Blocked (hook convention)	.claude/hooks/*.sh
10-19	Docker failures	Docker lifecycle scripts
20-29	Configuration errors	Setup/config scripts
30-39	Dependency errors	Preflight validation scripts

Topic Index

Topic	Reference File
Bash shebang and preamble	./references/bash-standards.md
Bash quoting rules	./references/bash-standards.md
Bash variable handling	./references/bash-standards.md
ShellCheck integration	./references/bash-standards.md
Bash signal handling and cleanup	./references/bash-standards.md
Probe / test-harness hygiene (self-cleaning symlinks, workspace invariant checker)	./references/bash-standards.md
Bash never-do list	./references/bash-standards.md
Host-script Bash 3.2 portability (macOS /bin/bash)	./references/bash-standards.md
Banned Bash-4.x-only constructs for host scripts	./references/bash-standards.md
BSD vs GNU userland pitfalls (sed -i, date -d, stat, readlink -f)	./references/bash-standards.md
In-container command availability (Dockerfile-installed set)	./references/bash-standards.md
PowerShell preamble	./references/powershell-standards.md
PowerShell ASCII-only encoding	./references/powershell-standards.md
PowerShell dual error system	./references/powershell-standards.md
PowerShell defensive coding	./references/powershell-standards.md
PowerShell output streams	./references/powershell-standards.md
PSScriptAnalyzer	./references/powershell-standards.md
Fail-closed principle	./references/error-handling.md
User-facing output formatting	./references/error-handling.md
Exit code conventions	./references/error-handling.md
Docker error handling	./references/error-handling.md
Dependency validation	./references/error-handling.md
NO_COLOR and TTY detection	./references/error-handling.md
BATS test framework	./references/testing.md
Pester test framework	./references/testing.md
CI workflow setup	./references/testing.md
Docker mocking strategies	./references/testing.md
Test taxonomy (lint/unit/smoke/integration)	./references/testing.md
In-container validation toolchain (DAAF_DEV: pwsh, Pester, PSScriptAnalyzer, shellcheck, bats)	./references/testing.md
Safety-hook regression batteries (test_safety_hooks.sh, test_enforce_single_command.sh)	./references/testing.md
What to test and what to skip	./references/testing.md
Bash exit code masking	./references/gotchas.md
Bash set -e edge cases	./references/gotchas.md
PowerShell exit in dot-sourced functions	./references/gotchas.md
PowerShell $LASTEXITCODE vs $?	./references/gotchas.md
PowerShell UTF-8 BOM breaks iex	./references/gotchas.md
PowerShell implicit returns	./references/gotchas.md
PowerShell $null pipeline behavior	./references/gotchas.md
Cross-platform env var casing	./references/gotchas.md
Cross-platform alias differences	./references/gotchas.md
Cross-platform exit code truncation	./references/gotchas.md
Cross-platform path separators	./references/gotchas.md
Cross-language octal printf escaping (\\357/\\011 to sh)	./references/gotchas.md
Detached-container (docker run -d) diagnostics routing	./references/error-handling.md