[chrisjsewell]

needstable.js (#1920) is plain JavaScript typed through // @ts-check and JSDoc, and design/needstable-contract.md §4 records the single command that checks those types. It passes at the tip, but nothing ran it, so any later edit could regress a type silently. This makes it a gate.

• A poe task, typecheck-js-needs, holds the command with the typescript version pinned (typescript@5.9.3): an unpinned npx -p typescript resolves whatever compiler is newest that day, which would let a TypeScript release turn a pull request red with nothing here having changed. To bump it, edit that one literal and run the task. 5.9.3 is the newest 5.9.x; the file is also clean under 7.0.2, today's latest.
• One Lint step runs the task, not a copy of the command, so the gate a developer runs locally and the gate that blocks a pull request cannot drift, the same arrangement as the prek hooks and poe lint. Lint rather than the tests-js lane: it needs no browser, no sphinx and no interpreter matrix, and Lint is a required status context in its own right. No setup-node: ubuntu-latest ships node and npm, and npx -y -p fetches the pinned compiler into the runner's npm cache for the run (about 2.5 s cold on an empty cache, 23 MB unpacked).
• Files checked: needstable.js only. sphinx_needs_collapse.js is jQuery-era, carries no // @ts-check and does not pass --strict; ✨ Port sphinx_needs_collapse.js off jQuery and drop sphinxcontrib-jquery #1922 ports it and is the pull request that adds the second line. The task lists one path per line, so that is a one-line change.
• Docs: §4's "It is not a CI gate here" sentence now says the opposite, and the root AGENTS.md commands block gains the task. No changelog entry: nothing user-visible changed.

Proof the fence bites: with this.sortColumn = -1 (declared @type {number}) changed to a string, the task exits 2 with

src/sphinx_needs/libs/html/needstable.js(452,13): error TS2322: Type 'string' is not assignable to type 'number'.

Closes #1924

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.03%. Comparing base (eb23d5e) to head (0a58b82).
⚠️ Report is 22 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1928      +/-   ##
==========================================
+ Coverage   91.84%   92.03%   +0.19%     
==========================================
  Files         105      105              
  Lines       16231    16279      +48     
==========================================
+ Hits        14907    14983      +76     
+ Misses       1324     1296      -28     

Flag	Coverage Δ
codelinks	93.42% <ø> (ø)
mounts	94.01% <ø> (ø)
pytests	91.40% <ø> (+0.27%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.