fix: doc-reference lint, review follow-ups, preflight portability, and homebrew release trigger

[sbryngelson]

Summary

Fixes the Lint Toolchain / Precheck failure that #1855 introduced on master (run 34670170525). Three errors, all from lint_docs.py:

contributing.md:220       single-backtick span `$:GPU_UPDATE(device='[name]')` contains a single quote
gpuParallelization.md:877 single-backtick span `GPU_ROUTINE(parallelism='[seq]')` contains a single quote
testing.md:16             links to #selection-and-execution-pitfalls but no anchor exists

Doxygen treats a single quote inside a single-backtick span as ending the span, so both spans become double-backticked. The testing.md cross-reference gets its matching {#selection-and-execution-pitfalls} anchor on the target header.

Three lines changed, no prose edits.

Verification

python3 toolchain/mfc/lint_docs.py exits 0, and ./mfc.sh precheck reports "Doc references are valid" along with formatting, spelling, source lint, parameter docs, and example validation.

Precheck's toolchain-lint step fails locally with 13 test_preflight* failures, but those reproduce identically on unmodified upstream/master (git stash and re-run), are macOS-specific probing tests around srun/mpirun, and passed in the same CI run that caught the doc errors. They are unrelated to this change.

Review follow-ups from #1855

Copilot's review of #1855 raised four points; two are taken here.

Lint pointers now name documentation that exists. The error message in check_device_routine_element_args said see sbryngelson/compiler-bugs cce/acc-routine-element-by-reference, which is not actionable from a CI log. It now names the Silent-Failure Traps section of docs/documentation/gpuParallelization.md — repo-local, so it survives any change to the external repo's layout. That section gains the {#silent-failure-traps} anchor Doxygen requires, so the reference is real rather than nominal. The docstring keeps the full trail: the docs section, #1815, and a full URL to the reproducer, whose path was checked to exist rather than assumed.

.claude/CLAUDE.md: trailing whitespace removed from two lines, and three grammar slips fixed ("CFD result need verification PR is correct", "follow existing the source's", "while being correctness").

Not taken: the review also asked to preserve a "previously-local breadcrumb" in the docstring. That breadcrumb was .claude/rules/common-pitfalls.md, the file #1855 removed, so there was nothing left to point at — which is what prompted the repoint above.

Verification

python3 toolchain/mfc/lint_docs.py exits 0. check_device_routine_element_args still runs against the tree and reports 0 findings, unchanged. ./mfc.sh lint reports the same 13 test_preflight* failures as unmodified upstream/master, so this change adds none.

Preflight portability

Unrelated to the docs above, but folded in here rather than split into its own PR. ./mfc.sh precheck could not pass on macOS: its toolchain-lint step reported 13 failures across the five *preflight* test files. Both causes are real bugs in .github/scripts/preflight.sh, not test-environment noise.

1. find -printf is GNU-only. newest_syscheck ran find ... -printf '%T@ %p\n' 2>/dev/null. A BSD find rejects -printf, the error is swallowed by the redirect, discovery returns nothing, and the script prints "no syscheck binary under build/install; skipping node probe" and exits healthy. It now uses -exec ls -t {} +, which also removes the sort/cut pipeline.
2. set -u plus an empty array under bash 3.2. run_probe "${launcher[@]}" aborts with launcher[@]: unbound variable on the bash macOS ships; bash 4.4 changed this, so Linux never sees it. Now ${launcher[@]+"${launcher[@]}"}.

The test fixture gains ls in its hermetic PATH, since the script now calls it.

Worth noting for review: two tests were passing vacuously before. test_does_not_report_a_node_fault_merely_because_pmix_printed_a_warning and test_a_missing_launcher_is_not_blamed_on_the_node assert a healthy exit, and a skipped probe also exits healthy. They began failing once discovery worked and passed again after the bash fix, so the prior state was 13 red plus at least 2 false greens.

Verified on both toolchains rather than on the BSD side only:

	old -printf	new -exec ls -t {} +
GNU findutils 4.11.0	picks the newest	picks the newest
BSD /usr/bin/find	returns nothing	picks the newest

The five preflight files give 29 passed against system BSD find with bash 3.2.57, and test_preflight.py gives 12 passed with the fixture temporarily pointed at GNU findutils 4.11.0 with bash 5.3.15, as a stand-in for the CI stack. That fixture change was reverted. ./mfc.sh precheck is now green end to end, and this commit passed the pre-commit hook without --no-verify.

Homebrew release trigger

v5.7.0 published without a formula update. homebrew-release.yml triggered on push: tags: v*, and GitHub skips push-triggered workflows when the head commit message carries [skip ci] — which MFC's tags land on, because they point at the coverage-map commit:

release	tagged commit	homebrew-release
v5.6.0	test: refresh coverage map [skip ci]	no run; rescued by a manual workflow_dispatch 3 min after publish
v5.6.1	fix(container): disable -Mfprelaxed…	fired automatically, 2 s after publish
v5.7.0	test: refresh coverage map [skip ci]	no run, and no rescue

docker.yml was unaffected across all three because it triggers on release: [published], and a release event is not a push event — its v5.7.0 run exists and is only waiting on a runner. This moves homebrew-release.yml to that same trigger, so the formula update no longer depends on what the tagged commit message happens to say.

Two follow-on changes: the version now comes from github.event.release.tag_name (with any v stripped) rather than GITHUB_REF, and prereleases are skipped via a job-level if rather than failing the X.Y.Z regex with a red job.

actionlint reports the same 21 findings before and after this edit — all pre-existing shellcheck SC2086/SC2129 notes on the pre-existing $GITHUB_STEP_SUMMARY steps — so the change introduces none.

Note this does not retroactively publish v5.7.0's formula; that still needs a one-off gh workflow run homebrew-release.yml -f version=5.7.0.

Note on tooling

Written with assistance from Claude Code. The original error was mine: the checks were verified by calling three functions out of lint_docs.py by name rather than running the script, so the backtick and anchor checks never executed.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Pull request overview

Fixes doc-reference lint failures introduced in #1855 by adjusting inline-code delimiters that contain single quotes and by adding a missing documentation anchor for an intra-doc link.

Changes:

• Add a {#...} anchor to the “Selection and Execution Pitfalls” header so #selection-and-execution-pitfalls resolves.
• Switch two inline-code spans from single backticks to double backticks to avoid Doxygen’s single-quote parsing issue.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
docs/documentation/testing.md	Adds the missing selection-and-execution-pitfalls anchor to satisfy cross-reference lint.
docs/documentation/gpuParallelization.md	Uses double-backtick inline code for a macro call containing single quotes to satisfy lint.
docs/documentation/contributing.md	Uses double-backtick inline code for a directive containing single quotes to satisfy lint.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.