[Vivswan]

What this changes

linkTargets: a `](...)` regex over lines outside fences, a scheme filter, a try/catch decode
  ->  the file's own linkDestinations (rendered HTML, HTMLRewriter href/src, entity decoding),
      each destination resolved with URL.parse against the docs site origin

differential, old against new, the browser's reading as the referee:
  45 real pages (42 docs, README, CONTRIBUTING, SECURITY)   424 targets   0 differ
  3000 generated documents, 33 link forms                   new = browser 3000/3000, old = browser 631/3000

How

• Thirteen link forms read differently in isolation (titles, angle brackets, reference style, raw HTML, tel:, code spans, escaped brackets, encodings); each new answer is the browser's. No real page carries one.
• External is decided by the URL parser: a null parse or an origin other than the docs site, which covers absolute URLs, //host/ network paths, and non-special schemes such as git+ssh:.
• The parser trims padding and splits query and fragment before the path is percent-decoded, so an encoded %23 stays in the path and 50%%20done.md reads as 50% done.md.
• Library: linkDestinations, already in the same file; the WHATWG URL and entities cover resolution and decoding.

Proof

• Tests: guides 253 pass; the new guard pins the thirteen forms, both decodings, and the four forms from review, each seen red against the scan it replaced.
• Gates: typecheck, fleet biome 0, member-shape 0, line cap.

Technical details

• A link that climbs above the repository root is clamped at the dummy origin's root, as a browser clamps at a site root, and then reported missing; a.md# yields no fragment (the page itself); a malformed absolute reference such as https:// is skipped as external.
• LinkTarget.path is repository-relative, so the three tests resolve with join(ROOT, path) and the fragment-only special case is gone.
• The old scan's unclosed-fence throw has its successor in the heading test over the same files.
• Files: test/docs/guides.test.ts.

[github-actions]

File size check

0 over a hard cap (fails), 6 warning(s).

File	Size	Tier	Cap
src/engine/diff.ts:56	11 comment lines	warn	10
src/github/api-error.ts:9	11 comment lines	warn	10
src/problem.ts:73	18 comment lines	warn	10
src/sections/contract/errors.ts:13	11 comment lines	warn	10
src/sections/contract/module.ts:55	12 comment lines	warn	10
src/sections/shared/list/decl.ts:265	14 comment lines	warn	10

Split the file, wrap the line, shorten or exempt the comment, or list the path in .file-size-allow.local with a # reason.

5 managed file(s) skipped; repo-platform owns them.

[Copilot]

🟡 Changes recommended

Valid rendered links can still cause false documentation failures because URL normalization and external-link filtering are incomplete.

2 open issues

• Recognize network-path and case-insensitive scheme URLs as external · New
• Normalize HTML link whitespace and query strings before file checks · New

What changed in this PR

This PR replaces the documentation tests' regex-based link scan with the existing rendered-HTML extractor, bringing link validation closer to browser behavior.

Changes:

• Reuses linkDestinations for local-file, fragment, and orphan-page checks.
• Decodes paths and fragments separately with tolerant percent decoding.
• Adds mutation coverage for link forms the regex handled incorrectly.

File	Description
test/​docs/​guides.test.ts	Refactors link extraction and decoding, updates guards, and adds regression cases.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

The focused test-only refactor addresses the prior feedback and has no unresolved blocking findings.

No open issues 🎉

2 resolved since last review

• Normalize HTML link whitespace and query strings before file checks
• Recognize network-path and case-insensitive scheme URLs as external

_{Review effort: Balanced}