Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
fullsend-ai-coder wants to merge 2 commits into from
Closed

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

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fafe9c2
docs(#181): add shell return-vs-exit correctness rule to AGENTS.md
fullsend-ai-coder[bot] Jul 8, 2026
febe916
fix(#181): clarify return behavior precision in shell scripting rule
fullsend-ai-coder[bot] Jul 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,16 @@ The e2e tests require GitHub credentials. There are three ways to provide them:

If only `E2E_GITHUB_USERNAME` and a password source are available, `make e2e-test` will automatically generate a session file before running tests. See `make help` for all available targets.

## Shell scripting

@fullsend-ai-review fullsend-ai-review Bot Jul 11, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[low] structure

The new Shell scripting section sits between the Running e2e tests subsection (under Go code) and the Forge abstraction section. The placement is reasonable but creates a slight topic jump from Go-specific testing to general shell scripting.


### `return` vs `exit` in executed scripts

@fullsend-ai-review fullsend-ai-review Bot Jul 8, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[low] technical-accuracy

The phrase "return causes a hard error" is slightly imprecise. Without set -e, a top-level return in an executed script emits an error diagnostic and sets exit status 2, but the script continues executing subsequent commands — it does not abort. The abort only occurs when set -e (errexit) is active. The guidance is pragmatically correct for set -euo pipefail scripts (standard in this project), but the wording could mislead readers into thinking return alone terminates the script.

Suggested fix: Consider rewording to: "return produces an error (exit status 2) — and under set -e (commonly part of set -euo pipefail), this non-zero status triggers errexit and aborts the script."

@fullsend-ai-review fullsend-ai-review Bot Jul 11, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[low] technical-accuracy

The statement "return causes a hard error" is slightly imprecise. A top-level return in an executed script produces exit status 2 and an error message, but without set -e the script continues execution past the failed return. The abort only occurs because set -e treats the non-zero exit status as fatal. The practical guidance is correct for scripts using set -euo pipefail, but the mechanism description could mislead a reviewer analyzing a script without set -e.

Suggested fix: Consider rewording to: "return is invalid at the top level of an executed script — bash emits an error and the statement fails with exit status 2. Under set -e (commonly set -euo pipefail), this non-zero status aborts the script."


`return` is valid only inside functions or in scripts that are `source`d. At the top level of an executed script (one with a shebang or run via `bash script.sh`), `return` produces an error (exit status 2) — and under `set -e` (commonly part of `set -euo pipefail`), this non-zero status triggers errexit and aborts the script.

This commonly occurs when inlining library code that was previously `source`d. Library-style load guards like `[[ -n "${LOADED:-}" ]] && return 0` must be removed or replaced when the code is inlined into an executed script.

**When reviewing shell scripts:** Flag any top-level `return` (outside a function body) in a script that is executed rather than sourced as a medium-severity correctness finding. Check for this especially when a PR inlines or moves code from a library/sourced file into an executable script.

## Forge abstraction

All git forge operations (GitHub API calls, PR comments, issue creation, workflow dispatch, etc.) **must** go through the `forge.Client` interface defined in `internal/forge/forge.go`. This is a fundamental architectural rule — the codebase supports multiple forges (GitHub, GitLab, Forgejo) and direct coupling to any single forge breaks the abstraction.
Expand Down
Loading