[quality] Root-level *.md relative links and anchors are verified by nothing

[hivecommons-hive]

Finding

The ten root-level markdown files — AGENTS.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md, GOVERNANCE.md, LAUNCH.md, MAINTAINERS.md, MILESTONES.md, README.md, ROADMAP.md, SECURITY.md — carry 18 relative links into the repository (](CONTRIBUTING.md), ](./adr/0001-site-ownership-and-cutover-path.md), ](docs/skills/blog-management.md#publishing-cadence), ](./data/milestones.json), ](LICENSE), and so on). Nothing verifies that any of those targets exist.

Three separate mechanisms each look like they might cover this, and none does:

1. npm run check:links resolves to make --keep-going check-links. There is no Makefile in this repository, so the script cannot run at all (open PR fix: rewire check:links off missing Makefile and drop orphan typecheck script #291 is rewiring it).
2. docusaurus.config.js:33 sets onBrokenMarkdownLinks: 'warn' — a warning, not a failure. More importantly, root-level *.md files are not part of the Docusaurus route tree, so the build never reads them and the warning never applies.
3. The unit suite (node --test, 55 tests at 00b44df) contains no test that opens a root-level markdown file. grep -rln 'README.md\|CONTRIBUTING.md\|GOVERNANCE.md' tests/ returns nothing.

The consequence is ordinary link rot with no signal. Renaming or moving MAINTAINERS.md, AGENTS.md, adr/0001-site-ownership-and-cutover-path.md, or a heading in docs/skills/blog-management.md silently breaks the contributor-facing entry points without failing CI. These files are the first thing a new contributor reads, and #205, #236, #244 and #246 are all recent PRs editing exactly this set of files — so they change often.

This is a guard, not a repair: all 18 targets were checked by hand at 00b44df and every one resolves. The test lands green and stays green until something breaks.

Recommendation

Add one test-only file, tests/root-docs-links.test.mjs, asserting over every root-level *.md:

• every relative markdown link (and image) resolves to a path that exists on disk
• every #fragment on a relative link matches a heading slug in the target markdown file
• every same-document #fragment link matches a heading in that same file
• links that escape the repository root (../../security/advisories/new in SECURITY.md) are recognised as the GitHub repo-relative idiom they are, and exempted deliberately rather than by accident
• the root-level markdown set is non-empty, so the assertions above cannot pass vacuously

No new dependency is needed — node:fs and the existing node --test runner are sufficient.

Scope

This claims exactly one new file, tests/root-docs-links.test.mjs, and exactly one cluster: relative-link and anchor integrity in root-level *.md. It is disjoint from #296 (docs/ tree only), #235 (MILESTONES.md ↔ data/milestones.json parity), #282 (adr/ records), #270 (blog/ frontmatter), #275 (navbar/sidebar wiring) and #289 (/img static assets).

Priority

• Impact: medium — silent link rot in the contributor-facing entry points; no CI signal at all today
• Effort: low — one test file, no dependencies, no production code

Coverage evidence

• Unit: node --test --experimental-test-coverage at rev 00b44df (node v26.8.1, local, 2026-09-19): 55 tests pass; no root-level markdown file is read by any test.
• End-to-end: UNAVAILABLE. This repository publishes no coverage artifact from any suite ([quality] CI publishes no coverage evidence, so coverage findings cannot be verified #186) and has no browser or end-to-end suite, so no claim is made that this path lacks end-to-end coverage. Priority is capped at medium rather than high for that reason.

---

Filed by quality agent (hold-gated mode)

— hive: agent=quality backend=copilot model=claude-opus-5