docs(#181): add shell return-vs-exit correctness rule to AGENTS.md

[fullsend-ai-coder]

Add a Shell scripting section with guidance on return vs exit context in executed scripts. The review agent will now flag top-level return outside a function body in executed scripts as a medium-severity correctness finding.

---

Closes #181

Post-script verification

• Branch is not main/master (agent/181-shell-return-exit-rule)
• Secret scan passed (gitleaks — b776cf6006a12016eaa21412dc65a3001100e801..HEAD)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 3:23 PM UTC · Completed 3:30 PM UTC
Commit: b776cf6 · View workflow run →

[fullsend-ai-review]

Review — comment

PR: #504 — docs(#181): add shell return-vs-exit correctness rule to AGENTS.md

Summary

This PR adds a well-structured "Shell scripting" section to AGENTS.md, implementing the exact text proposed in issue #181. The change is properly authorized (linked issue with ready-to-code label), correctly scoped (no additions beyond what the issue proposed), and follows the established document style (heading hierarchy, bold "When reviewing..." pattern, backtick formatting).

The review instruction itself — flag top-level return in executed scripts as a medium-severity correctness finding — is correct and valuable. However, the explanatory text contains a technical imprecision about the failure mode of top-level return in bash that is worth addressing.

Findings

1. [medium] Technical imprecision: "hard error" overstates default behavior — AGENTS.md

The documentation states: "return causes a hard error — and under set -euo pipefail, this aborts the script."

In bash, a top-level return in an executed script produces an error message (return: can only 'return' from a function or sourced script) with exit status 2, but execution continues past the return line unless set -e is active. The "hard error" phrasing implies the script always halts, when in fact:

• With set -e: the non-zero exit status triggers abort ✓
• Without set -e: the guard silently fails and execution falls through — arguably worse than an abort (silent wrong behavior vs. loud failure)

The review instruction at the end of the section is correct regardless, but reviewers relying on the explanation to understand the failure mode may misjudge what actually happens at runtime.

Suggested rewording: "return at the top level of an executed script produces a non-fatal error in bash — it prints a diagnostic but execution continues past it. Under set -e (or set -euo pipefail), the non-zero exit status triggers an immediate abort. Without set -e, the guard silently fails and execution falls through."

2. [low] set -euo pipefail attribution is imprecise — AGENTS.md

The abort is caused specifically by -e (errexit). The -u (nounset) and -o pipefail flags are irrelevant to this mechanism. Since set -euo pipefail is commonly used as a unit, this is a minor point, but could confuse someone reasoning about which specific flag matters.

3. [low] Bash-specific behavior stated as universal — AGENTS.md

In POSIX sh (e.g., dash on Debian/Ubuntu), return at the top level of an executed script silently behaves like exit — no error, no diagnostic. The documentation assumes bash behavior without qualification. Since this repo's scripts likely use #!/bin/bash, the practical impact is low, but adding "In bash," as a qualifier would improve precision.

[fullsend-ai-review]

See the review comment for full details.

[fullsend-ai-review]

[medium] technical-accuracy

The phrase "hard error" is misleading. In bash, a top-level return in an executed script produces an error message with exit status 2, but execution continues past the return line unless set -e is active. Without set -e, the guard silently fails and execution falls through (silent wrong behavior), which is arguably worse than an abort. The documentation implies the script always halts.

Suggested fix: Reword to: "return at the top level of an executed script produces a non-fatal error in bash — it prints a diagnostic but execution continues past it. Under set -e (or set -euo pipefail), the non-zero exit status triggers an immediate abort. Without set -e, the guard silently fails and execution falls through."

[fullsend-ai-review]

[low] technical-accuracy

The abort behavior is attributed to set -euo pipefail as a unit, but only -e (errexit) is relevant. The -u (nounset) and -o pipefail flags do not contribute to this mechanism.

Suggested fix: Say "under set -e" or add a parenthetical clarifying that -e is the specific flag that triggers the abort.

[fullsend-ai-review]

[low] technical-accuracy

The claim about return behavior is bash-specific but stated as universal. In POSIX sh (dash), return at top level of an executed script silently behaves like exit — no error, no diagnostic. Adding "In bash," as a qualifier would improve precision.

Suggested fix: Add "In bash," at the start of the sentence, or note the shell-dependent behavior.