docs(#251): add shell return-vs-exit correctness rule

[fullsend-ai-coder]

Add a Shell scripting section to AGENTS.md with guidance on the return-vs-exit distinction in executed vs sourced scripts. The review agent previously dismissed a top-level return in an executed script as harmless dead code (PR fullsend-ai#3182). In bash, return at script top level is invalid and causes a hard abort under set -euo pipefail, regardless of reachability.

---

Closes #251

Post-script verification

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

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 4:41 PM UTC · Completed 4:45 PM UTC
Commit: d8e3df7 · View workflow run →

[fullsend-ai-review]

Review — approve

PR: #282 · docs(#251): add shell return-vs-exit correctness rule
Commit: 43bf6058

Summary

Single-file documentation change adding a "Shell scripting" section to AGENTS.md with guidance on the return-vs-exit distinction in executed vs sourced scripts. The change directly addresses a missed review finding from PR fullsend-ai#3182, where a top-level return in an inlined library was incorrectly dismissed as harmless dead code.

Analysis

Correctness — The technical content is accurate. return at script top level in bash produces return: can only 'return' from a function or sourced script and exits non-zero, which under set -euo pipefail aborts the script. The example pattern ([[ -n "${LOADED:-}" ]] && return 0) correctly illustrates the most common source of this bug. The medium-severity guidance for review findings is appropriately calibrated.

Intent & coherence — The committed text matches the proposed change in issue #251 verbatim. The commit message uses the correct docs(#251): prefix per COMMITS.md conventions. The scope is tightly focused — one section, one rule, one file. The bot author is exempt from DCO per AGENTS.md policy.

Style & placement — The new ## Shell scripting section with its ### return vs exit in executed scripts subsection follows the existing heading hierarchy (parallel to ## Go code, ## Forge abstraction). Bold emphasis for review guidance ("When reviewing shell scripts:") is consistent with patterns in the Forge abstraction section. No formatting issues.

Security — Documentation-only change; no security implications.

Documentation currency — N/A (this is the documentation change).

Cross-repo contracts — No external interfaces affected.

No findings above the severity threshold.

---

Protected paths detected — this PR modifies files under one or more
protected paths. The review agent cannot approve PRs that touch these paths.
A human reviewer must approve this PR.

Protected files in this PR:

• AGENTS.md

---

Labels: PR adds documentation to AGENTS.md

[guyoron1]

/fs-fix

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 5:38 PM UTC · Completed 5:44 PM UTC
Commit: d8e3df7 · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

No actionable review feedback was found. The review body was empty and the human instruction was 'none'. The PR modifies only AGENTS.md (a protected path). No code changes were made.

Disagreed (1):

1. No actionable review feedback found: The review body file was empty and HUMAN_INSTRUCTION was 'none'. No review findings to address. The only file changed by this PR (AGENTS.md) is a protected path that the fix agent should not modify without explicit instruction.

Tests: passed

_{Updated by fullsend fix agent}