ci: require a closing magic word for the Linear link

[jacderida]

Linear issue

Closes V2-1161

Risk tier

• T0 — docs / tooling / CI / pure UX-output. Repo CI only.

Compatibility

• Wire: none
• Storage: none
• API: none

Semver impact

• fix

Test evidence

python3 .github/scripts/test_check_pr.py — 52/52 cases pass, in this repo and
in all six (the self-test job runs the same matrix). The matrix grew from 17 to 52
cases, asserting: one case per closing magic word Linear documents, in the tense an
author would actually write (Closed, Fixed, Resolving, Implemented, …); the
Closes <linear.app issue URL> form; lower-cased input; the linear issue phrase;
the linking-only families (ref, part of, towards, relates to) rejected, since
they attach a PR without driving the Merged transition; word-boundary cases
(prefix/fixture must not match); a magic word with no key; a magic word separated
from its key by a blank line; and bare key or bare issue URL in the body — the last of
which used to pass and now fails, which is the point of the change.

The accepted set is taken verbatim from https://linear.app/docs/github and restated
independently in the test matrix, so the matrix is an assertion about the documented
behaviour rather than a restatement of the implementation.

This PR is its own end-to-end test: it carries the closing form in the body, and the
pull_request event runs the version of check_pr.py from this branch.

New dependency

none

ADR

n/a

Mitigation / rollback

Revert the commit. The check is a CI gate with no runtime surface; reverting restores
the previous linear-link behaviour immediately.

[dirvine]

One blocking issue: this checker does not match Linear’s documented closing syntax. Linear supports close/closes/closed/closing, fix/fixes/fixed/fixing, resolve/resolves/resolved/resolving, complete/completes/completed/completing, implement/implements/implemented/implementing, and linear issue; MAGIC_WORDS accepts only five of those.

For example, Fixed V2-1161 links and closes the issue in Linear, but I reproduced that it exits 1 here. Because this is merge-blocking CI, it would reject valid Linear-linked PRs, while the new comments also incorrectly say these five are the closing words Linear recognises. Please expand MAGIC_WORDS and the tests to cover Linear’s official closing set.

Official reference: https://linear.app/docs/github

[jacderida]

You're right, and I've fixed it — amended and force-pushed.

I checked the claim against https://linear.app/docs/github rather than taking it on trust, and the docs confirm it. MAGIC_WORDS is now the documented closing set, verbatim, all 21 entries:

close, closes, closed, closing
fix, fixes, fixed, fixing
resolve, resolves, resolved, resolving
complete, completes, completed, completing
implement, implements, implemented, implementing
linear issue

Your repro now passes:

$ PR_BODY="Fixed V2-1161" PR_BRANCH=x python3 .github/scripts/check_pr.py linear
✅ Linear link found in the PR body: Fixed V2-1161
(exit 0)

Alternatives are sorted longest-first when the pattern is built, so close cannot shadow closes.

What I did not add, deliberately: the linking-only families the same docs page lists — ref / refs / references, part of / contributes to / toward / towards, and relates to / related to. Those attach the PR but do not drive the status transition on merge, and this issue (V2-1161) exists specifically to make the Merged automation fire. Accepting them would leave the original bug in place under a different spelling. They now have explicit rejection cases in the matrix, and the failure message calls them out by name so nobody hits that wall without an explanation.

On the incorrect comments: also fixed. check_pr.py, PULL_REQUEST_TEMPLATE.md and CLAUDE.md no longer claim five words are the set — they describe the five stems in any tense plus the linear issue phrase, cite the docs page, and state why the linking-only words are excluded.

Tests: the matrix went 30 → 52 cases. It generates one case per closing word from its own tuple, restated independently of check_pr.py so it asserts the documented behaviour rather than mirroring the implementation, plus rejection cases for each linking-only family and for word-boundary near-misses (prefix V2-1161, fixture V2-1161). 52/52 pass in all six repos.

The same amended commit is on all six train repos.

[dirvine]

Follow-up review: the full documented Linear closing-word set is now covered, including the previously rejected forms. The expanded local test suite passes 52/52. Approved.