fix(reports): GitHub Actions annotations never reach the pull request

[Chemaclass]

Problem

bashunit can produce GitHub Actions workflow-command annotations, but they never reach a pull request. Three things are wrong at once:

1. They are written to a file, not stdout. src/reports/print_gha_annotations prints correct ::error file=…,line=…:: lines, but bashunit::reports::generate_gha_log (src/reports/gha.sh:64) redirects them into $output_file, and src/main/run.sh:136-138 only ever calls that variant. GitHub parses workflow commands from the job log. A file nobody cats produces zero annotations.
2. The official action never wires it. action.yml contains no reference to gha, annotation or BASHUNIT_LOG_GHA. Users of TypedDevs/bashunit@v0 get nothing.
3. The flag is undocumented. --log-gha is parsed at src/main/test.sh:193-197 but is missing from bashunit test --help, so it is undiscoverable.

Net effect: a feature that exists in the codebase is unreachable for the end user it was built for.

Proposal

• Auto-detect: when GITHUB_ACTIONS=true and the output is not already TAP/JSON, print annotations to stdout at the end of the run. No flag required.
• --gha-annotations <auto|always|never> to override (auto = the detection above).
• Keep --log-gha <file> for the file variant, and document it in --help.
• Wire the action: action.yml should surface the behaviour and an input to disable it.
• Emit ::error for failures with file= and line= so the annotation lands on the right line of the diff (the data is already collected — _BASHUNIT_REPORTS_TEST_LINES), ::warning for risky, ::notice for incomplete.

Where to change

• src/reports/gha.sh:19 print_gha_annotations (already stdout-correct), :64 generate_gha_log.
• src/main/run.sh:136.
• src/main/test.sh:193 and the --help block.
• action.yml.

Acceptance criteria

• With GITHUB_ACTIONS=true, a failing run prints ::error file=…,line=…,title=…::message to stdout
• Without GITHUB_ACTIONS, nothing extra is printed (no regression for local runs)
• --gha-annotations never suppresses them even under GITHUB_ACTIONS=true
• --gha-annotations always emits them outside GitHub Actions
• --log-gha <file> still writes the file, and now appears in bashunit test --help
• Annotations are correctly percent-encoded (__gha_encode, src/reports/gha.sh:5) — a multi-line failure message stays one annotation
• Annotations are not emitted twice when both auto-detection and --log-gha are active
• action.yml produces annotations on a failing test in a real workflow run (or an equivalent documented manual verification)
• Works under --parallel (regression guard for fix(reports): every report format is empty under --parallel #1004: the rows must be rebuilt in the parent)
• Acceptance test asserting the exact ::error line format

Repo checklist (agent)

• TDD: RED → GREEN → REFACTOR. Write the failing test first.
• Bash 3.0+ only: no printf -v, no += append, no declare -A, no [[ ]], no ${var,,}, no &>>, no ${arr[-1]}. Expanding a possibly-empty array under set -u needs ${arr[@]+"${arr[@]}"}.
• A new CLI flag must be wired in all of these or a parity test fails:
  • parse in src/main/test.sh (report-style flags need export -n, see src/main/test.sh:188-196 for why)
  • validate the value in bashunit::main::validate_config_or_exit (src/main/validate.sh:60) — unvalidated input used to run the wrong thing and exit 0 (Unknown options are silently ignored: a typo'd flag runs a different suite and exits 0 #871, --jobs with a non-integer value hangs on Bash 3.x and is silently ignored on Bash 4.3+ #873)
  • default + env var in src/config/env.sh and a documented line in .env.example
  • --help text in the same block it belongs to
  • both completions/bashunit.bash and completions/_bashunit (anti-drift test feat(cli): bash and zsh completion scripts with an anti-drift test #778 fails otherwise)
• Gates: make sa, make lint, ./bashunit tests/, ./bashunit --parallel tests/. Never run shfmt -w.
• Docs: update docs/command-line.md. Editing docs/assertions.md invalidates the bashunit doc acceptance snapshot — regenerate it.
• CHANGELOG.md: add one line under ## Unreleased.
• Fixtures under tests/acceptance/fixtures/ must not end in *test.sh.
• One issue = one PR.

[Chemaclass]

Done in #1042 (merged).