[quality] docs/ relative markdown links and frontmatter have no test gate (onBrokenMarkdownLinks is 'warn') #294

Finding

Nothing in the repo verifies the docs/ markdown tree, and the site build does not
catch relative-link breakage either.

No unit coverage. node --test --experimental-test-coverage at rev 00b44df
(node v26.8.1, run locally 2026-09-18) passes 55 tests across the 6 files in tests/,
all of which exercise scripts/ validators. grep -rln 'docs/' tests/ returns nothing —
no test reads the docs/ tree.

The build only warns. docusaurus.config.js:33 sets onBrokenMarkdownLinks: 'warn'.
onBrokenLinks: 'throw' on line 32 covers resolved route links, not relative markdown
paths between files. So a doc-to-doc link like [doc-authoring.md](doc-authoring.md) that
stops resolving — a rename, a moved file, a deleted section anchor — emits a warning and
deploy-gh-pages.yml still publishes a page with a dead link.

Verified locally at rev 00b44df that the contract currently holds: every relative
doc-to-doc link in the 28 docs resolves, and every #fragment on those links matches a
heading in its target doc. So a guarding test lands green today and is a pure regression gate.

Recommendation

Add tests/docs-contract.test.mjs asserting, over every docs/**/*.md{,x}:

• every relative doc-to-doc markdown link resolves to a file that exists (with .md/.mdx
  extension resolution, matching how Docusaurus resolves them)
• every #fragment on such a link matches a heading slug present in the target document
• every frontmatter block that is present is parseable YAML-ish key/value (no truncated
  or unterminated --- fence)
• every doc in a sidebar-autogenerated directory (architectures, community, per
  sidebars.js) carries a title

Scoped deliberately to the markdown-link and frontmatter-integrity contract. Route/slug
uniqueness, navbar wiring and sidebar reachability are claimed by #275; the
data/architectures catalog-to-docs contract by #260; blog/ frontmatter by #270; adr/
by #282; /img static asset resolution by #289. This issue claims none of that ground.

Out of scope here, noted for a maintainer

docs/skills/{manifest,doc-authoring,blog-management,skill-improvement}.md carry no
frontmatter at all, and docs/skills/ui-standards.md has no title. None of the five is
referenced by sidebars.js or the navbar, yet living under docs/ means Docusaurus builds
and publishes them. Deciding whether those pages belong on the public site is a content call,
not a testing one, so the test above does not assert a title/description on them.

Priority

• Impact: medium
• Effort: low

Filed by quality agent (hold-gated mode)

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