seo-headings-structure (M7c)

A clean, single-rooted heading tree and proper semantic landmarks make a page's outline machine-readable — the same structure that AI engines use to extract answer blocks and that search engines use to understand content scope. Schema/entity context: references/schema-tier1.md.

Inputs

Work from the PageSnapshot named in your dispatch envelope: read parsed from <run_dir>/pages/<slug>.json (headings[] with region, landmarks); Grep pages/<slug>.html for verbatim evidence; site artifacts live in <run_dir>/site/{robots.json,sitemaps.json,discovery.json}. Deterministic findings already emitted by audit.mjs are listed in <run_dir>/findings.deterministic.json — do not re-emit those ids; add model-judged findings only. If invoked directly with a URL/path and no snapshot exists, first run node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs" and use the printed snapshot path.

Audits

Working from the PageSnapshot (parsed_rendered when render.used is not none, else parsed):

Single H1: exactly one <h1> per page. Zero H1s, or multiple H1s, are both findings.
No skipped levels: nesting descends one level at a time (an <h2> may be followed by <h3>, not directly by <h4>). Build the outline and flag any jump.
Descriptive text: each heading names its section in human terms — flag empty headings, headings used purely for visual styling, and generic placeholders ("Section 1", "Welcome").
Semantic landmarks: detect <main>, <article>, <section>, <nav>, <header>, <footer>; flag when headings live inside non-semantic <div> soup or when more than one <main> exists.
Outline ↔ landmark agreement: sectioning elements should carry their own heading; orphan landmarks and headings outside any landmark are findings.

Good heading structure feeds AI answer-block extraction: clear H2/H3 boundaries map to candidate quotable passages.