docs: insights-driven guardrails — SSH pre-flight, bash safety, infra approval, dispatch pre-flight, session end, ask-minimax fallback

claude/scripting-conventions.md

@@ -1,5 +1,16 @@
 # Scripting Conventions
 
+## Bash safety
+
+- Open every script with `set -euo pipefail` — fail fast on errors, unset vars, and pipeline failures.
+- `grep` exits 1 on no match — under `set -e` use `grep ... || true`; under `pipefail`, beware `grep ... | head` triggering SIGPIPE (use `|| true` on the grep side).
+- One stdin per process — never pipe into a command that also reads a heredoc; pick one input source.
+- Validate JSON before consuming: `jq empty <file>` or `python3 -m json.tool <file>`. Especially before dispatch loops that iterate over JSON state.
+- Quote all expansions: `"$var"`, `"${array[@]}"`. Bare expansions split on whitespace.
+- Edit-tool `replace_all` is a substring match — a short `old_string` like `2` will corrupt `24` → `244`. Make `old_string` unique (add surrounding context) or use individual targeted edits.
+
+## Conventions
+
 - All scripts live in `scripts/` and run from the repository root
 - Scripts should be idempotent and safe to re-run
 - Use colour output for pass/fail indicators in verification scripts