ci(docs): run link gate in PR checks

[Audacity88]

Summary

• Base branch: master
• What changed and why:
  • Adds scripts/ci/docs_links_gate.sh to the required docs-style CI job so PRs exercise the changed-line docs link gate.
  • Extends collect_changed_links.py so it can split HTTP(S) targets from source-relative docs targets and fail on missing source-relative files.
  • Keeps HTTP(S) validation optional when lychee is not provisioned, which keeps the required docs job self-contained.
  • Updates the maintainer CI docs so docs-style lists both the quality gate and link gate.
• Scope boundary: This does not add a full-site crawler, install new CI tools, change release workflows, or run Rust validation.
• Blast radius: Required PR CI for docs changes. A bad link-gate result can block docs PRs until the source-relative link or script rule is fixed.
• Linked issue(s): Closes [Feature]: Run docs link gate in PR checks #8195
• Labels: enhancement, risk: high, size: S, ci, docs, scripts

Validation Evidence (required)

• Commands run and tail output:

  PYTHONPYCACHEPREFIX=<tmp> python3 -m py_compile scripts/ci/collect_changed_links.py
  python3 -c 'import yaml; yaml.safe_load(open(".github/workflows/ci.yml", encoding="utf-8")); print("ci.yml parses")'
  actionlint .github/workflows/ci.yml
  bash -n scripts/ci/docs_links_gate.sh
  shellcheck scripts/ci/docs_links_gate.sh
  git diff --check

  Tail output:

  ci.yml parses
  

  scripts/ci/docs_links_gate.sh fixture checks

  Tail output:

  == valid relative link ==
  Collected 1 added link(s) from 1 docs file(s).
  Checked 1 local docs link target(s).
  No added HTTP(S) links detected in changed docs lines.
  
  == broken relative link ==
  Collected 1 added link(s) from 1 docs file(s).
  Checked 1 local docs link target(s).
  Broken local docs link target(s):
    broken/missing.md
  broken status: 1
  
  == site-absolute generated API link ==
  Collected 0 added link(s) from 1 docs file(s).
  No added links detected in changed docs lines.
  
  == http link with lychee hidden from PATH ==
  Collected 1 added link(s) from 1 docs file(s).
  Added HTTP(S) links detected, but lychee is not installed; skipping optional HTTP(S) validation.
  Install via: cargo install lychee
  

  scripts/ci/docs_links_gate.sh committed-diff fixture checks

  Tail output:

  == committed diff valid relative link ==
  Collected 1 added link(s) from 1 docs file(s).
  Checked 1 local docs link target(s).
  No added HTTP(S) links detected in changed docs lines.
  
  == committed diff broken relative link ==
  Collected 1 added link(s) from 1 docs file(s).
  Checked 1 local docs link target(s).
  Broken local docs link target(s):
    docs/missing.md
  broken diff status: 1
  

  scripts/ci/docs_links_gate.sh HTTP(S) fixture with lychee available

  Tail output:

  Collected 1 added link(s) from 1 docs file(s).
  Checking added HTTP(S) links with lychee (offline mode)...
  Excluded.........1
  Errors...........0
  

• Beyond CI — what did you manually verify? Verified the gate accepts existing source-relative links, rejects missing source-relative links, skips site-absolute generated API links, does not require lychee in a CI-like PATH, and still uses lychee --offline when it is locally available.

• If any command was intentionally skipped, why: Full local scripts/ci/docs_quality_gate.sh markdownlint validation did not complete on this machine. The prose/em-dash portion passed, but the markdownlint step failed under the local Node 23/npm setup with an ESM/CJS package error; a Node 24 npx retry failed in npm before running the gate. GitHub Docs Style passed on head 7af0f31267, covering the required CI docs gate.

Security & Privacy Impact (required)

• New permissions, capabilities, or file system access scope? No
• New external network calls? No
• Secrets / tokens / credentials handling changed? No
• PII, real identities, or personal data in diff, tests, fixtures, or docs? No
• If any Yes, describe the risk and mitigation: N/A

Compatibility (required)

• Backward compatible? Yes
• Config / env / CLI surface changed? Yes
• If No or Yes to either: collect_changed_links.py now accepts optional --http-output and --check-local-targets helper flags. Existing --output callers still work; no user upgrade steps are required.

Rollback (required for risk: medium and risk: high)

• Fast rollback command/path: Revert this PR, or remove the Docs link gate (added links) step from .github/workflows/ci.yml and restore the previous helper behavior.
• Feature flags or config toggles: None
• Observable failure symptoms: The required Docs Style job fails on docs PRs, with logs such as Broken local docs link target(s): or unexpected docs_links_gate.sh output.