chore(docs): convert 8 Markdown-in-.adoc files; gate the dialect

[hyperpolymath]

Follow-on to #71. The estate rule "AsciiDoc by default" was satisfied in letter, not substance.

The problem

Eight files have been a = Title line bolted onto an unmodified Markdown body since the initial commit. They passed check-no-md-in-docs.sh (named .adoc) and Asciidoctor's Markdown-compat mode accepted ## headings and ``` fences without complaint — so they read as "clean" while rendering wrong:

• SPDX headers rendered as visible body text in five files. <!-- ... --> is not a comment in AsciiDoc; the licence header was displaying as page content.
• 21 Markdown pipe-tables rendered as garbage — 11 of them in THREAT-MODEL.adoc, so the threat model's tables did not render at all.
• Markdown links rendered as literal [text](url).
• Every render failure shared one root cause: a Markdown # H1 parses as a level-0 section, and a second level-0 section is a hard error (level 0 sections can only be used when doctype is book).

docs/STATE-VISUALIZER.adoc also turned out to have its entire body wrapped in a bogus [source] block — the cause of the unterminated listing block warning.

The change

Converted: 130 ATX headings, 49 code fences, 21 pipe-tables, 8 HTML comments, 5 links, 121 - [ ] task markers.

Markup only — no prose was reworded, added, or removed. Verified by diffing the word multiset of every file before/after: the only deltas are added AsciiDoc tokens (source, cols, options, header, link, xref) and the removed duplicate-title words. check-docs-render.sh's ALLOWED quarantine drops from 6 entries to 0.

The gate

Adds scripts/check-adoc-not-markdown.sh — the missing third leg:

check	asks
check-no-md-in-docs.sh	extension: is it named .adoc?
check-docs-render.sh	render: does asciidoctor parse it?
check-adoc-not-markdown.sh	dialect: is the body actually AsciiDoc?

The first two cannot catch this class of bug — which is precisely how it survived. The new check is block-aware, so shell # comments inside listing blocks aren't mistaken for headings, and it does not flag valid AsciiDoc that merely looks Markdown-ish (**bold**, - bullets, > quotes, * [ ] checklists). Verified failing on a probe file, not merely passing.

Verification

PASS: 131 .adoc files render cleanly (0 quarantined in ALLOWED)
PASS: 131 .adoc files are genuine AsciiDoc (no Markdown syntax)

Flagged, not actioned (your call)

docs/STATE-VISUALIZER.adoc is template residue — titled = RSR Template Repo — Project Topology, its diagram describes "RSR TEMPLATE HUB" and "NEW REPOSITORY (Consumer of this Template)". It is the RSR template's own architecture doc, never adapted to this project. must-no-template-residue misses it (that check only greps the Justfile for one string). Rewriting or deleting it is a content decision, so this PR only fixes its markup.

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
5 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud