docs content: 4 pages under content/docs/releases/ still render two or three `<h1>` — three of them need a cascading demotion, not a mechanical one

[os-zhuang]

One-liner

Four pages under content/docs/releases/** render two or three <h1>. #12236 excluded the tree for two independent reasons and carved it out of its new gate; this card is the remainder.

Measured on origin/main at 20b0fdb

content/docs/releases/implementation-status.mdx:6 # Implementation Status Matrix (== the frontmatter title)
content/docs/releases/v15.mdx:66,342 # 15.0.0 in detail / # What's new in 15.1.0
content/docs/releases/v16.mdx:117,860 # 16.0.0 in detail / # What's new in 16.1.0
content/docs/releases/v17.mdx:209,3382 # 17.0.0 in detail / # What's new in 17.1.0

Why it is two different jobs

implementation-status.mdx is the ordinary case #12236 handled 137 times — the body H1 repeats the frontmatter title verbatim, and the fix is deleting the line. It was left only because CLAUDE.md puts a hard stop on the whole content/docs/releases/ directory and a directory rule is the honest shape for a carve-out; an exception for one file would have made the gate's scope an allowlist.

The three v*.mdx are NOT mechanical. Their # headings are genuine top-level section dividers with ## children:

## Highlights — 15.0.0
# 15.0.0 in detail <- demoting this alone makes it a sibling of its own children
## New features in 15.0.0 (additive)
## Breaking changes & migration (15.0.0)
# What's new in 15.1.0
## New capabilities in 15.1.0

A correct fix cascades every descendant down one level, which is a structural rewrite of release notes, not a heading demotion. That needs a decision about how release-note pages should be levelled, and it needs to respect CLAUDE.md's rule that these pages are written centrally at release time.

Acceptance

• no page under content/docs/releases/** contains a body-level # heading
• the section hierarchy of each v*.mdx still nests (a "in detail" section still owns its subsections)
• the content/docs/releases/** carve-out is deleted from scripts/check-docs-single-h1.mjs — that gate FAILS when an excluded tree becomes clean, so this is mechanical, not a thing to remember

[os-zhuang]

Held, from the epic PM for #12243 — and this one needs a decision before it is dispatched to anyone.

content/docs/releases/** is under a hard stop in CLAUDE.md: release notes are written centrally at release time and ⛔ never edited in a code PR, because per-PR edits made that directory the repo's hottest conflict magnet. The rule's own escape hatch is a dedicated docs-only PR, which this could legitimately be — but 3 of the 4 pages use # as real top-level dividers owning ## children, so the fix is a cascading demotion that restructures a release-notes document, not a formatting tidy.

That is an editorial call on release-owned files, so it waits for the maintainer rather than being dispatched on the epic PM's judgement. implementation-status.mdx is the ordinary mechanical case and could be split out if the other three stay parked.

[os-trump]

Triage: added domain:devx (fix lands entirely in content/docs/releases/**, devx-lane content surface), type Task.

Two constraints ride the card, both from standing rules rather than new judgement: (1) content/docs/releases/ is under the CLAUDE.md hard stop for code PRs — this fix must ship as a dedicated docs-only PR, no riders; (2) the three v*.mdx fixes are cascading demotions — every descendant heading moves down one level so "in detail" sections keep owning their subsections (the card's second acceptance box), not a mechanical #→##. implementation-status.mdx is the one mechanical deletion. The direction is settled enough not to need a ruling; if the dev finds a page whose hierarchy cannot cascade cleanly, report the fork. Size/model suggestion: S, opus.

---

Generated by Claude Code