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

The estate rule "AsciiDoc by default" was satisfied in letter, not substance.
Eight files were a `= Title` line bolted onto an unmodified Markdown body,
committed that way 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 looked clean while rendering wrong:

  - SPDX headers wrapped in <!-- --> rendered as *visible body text* in five
    files (HTML comments are not comments in AsciiDoc).
  - 21 Markdown pipe-tables rendered as garbage, 11 of them in THREAT-MODEL —
    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").

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,
where the only deltas are added AsciiDoc tokens and the removed duplicate-title
words. check-docs-render.sh's ALLOWED quarantine drops from 6 entries to 0.

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

  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 how it survived. The new
check is block-aware, so shell `# comments` inside listing blocks are not
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.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: hyperpolymath

.github/workflows/quality.yml

@@ -74,3 +74,9 @@ jobs:
 
       - name: Check every .adoc renders
         run: ./scripts/check-docs-render.sh .
+
+      # ...and that it renders *because it is AsciiDoc*, not because
+      # Asciidoctor's Markdown-compat mode quietly accepted a Markdown body.
+      # Needs no asciidoctor — it is a pure syntax scan.
+      - name: Check every .adoc is AsciiDoc, not Markdown
+        run: ./scripts/check-adoc-not-markdown.sh .

.machine_readable/ai/PLACEHOLDERS.adoc

@@ -1,21 +1,22 @@
 = Template Placeholders
-# Template Placeholders
 
 All placeholders in this template follow the `{{PLACEHOLDER}}` pattern.
 After cloning, replace them with your project-specific values.
 
-## Recommended: Interactive Bootstrap
+== Recommended: Interactive Bootstrap
 
-```bash
+[source,bash]
+----
 just init
-```
+----
 
 This interactively prompts for all values, replaces every placeholder,
 validates the result, and runs k9-svc checks if available.
 
-## Manual Replace
+== Manual Replace
 
-```bash
+[source,bash]
+----
 # If you prefer manual replacement (run from repo root)
 
 sed -i 's/Jonathan D.A. Jewell/Jane Doe/g' $(grep -rl 'Jonathan D.A. Jewell' .)
@@ -28,80 +29,104 @@ sed -i 's/the-nash-equilibrium/my-project/g' $(grep -rl 'the-nash-equilibrium' .
 sed -i 's/github.com/github.com/g' $(grep -rl 'github.com' .)
 sed -i "s/2026/$(date +%Y)/g" $(grep -rl '2026' .)
 sed -i "s/{{CURRENT_DATE}}/$(date +%Y-%m-%d)/g" $(grep -rl '{{CURRENT_DATE}}' .)
-```
+----
 
-## Placeholder Reference
+== Placeholder Reference
 
-### Author & Copyright
+=== Author & Copyright
 
-| Placeholder | Description | Example | Files |
-|---|---|---|---|
-| `Jonathan D.A. Jewell` | Full legal name | `Jane Doe` | SPDX headers (all files), MAINTAINERS.md, .mailmap, .reuse/dep5, docs/AI-CONVENTIONS.md |
-| `j.d.a.jewell@open.ac.uk` | Primary contact email | `jane@example.org` | SPDX headers (all files), .mailmap, .reuse/dep5, .well-known/humans.txt |
-| `{{AUTHOR_EMAIL_ALT}}` | Previous/secondary email (for .mailmap) | `old@example.com` | .mailmap |
-| `{{AUTHOR_ORG}}` | Author's organization/affiliation | `Acme University` | project-metadata.k9.ncl |
-| `{{AUTHOR_LAST}}` | Author surname (for citations) | `Doe` | docs/CITATIONS.adoc |
-| `{{AUTHOR_FIRST}}` | Author first name (for citations) | `Jane` | docs/CITATIONS.adoc |
-| `{{AUTHOR_INITIALS}}` | Author initials (for citations) | `J.` | docs/CITATIONS.adoc |
+[cols="1,1,1,1",options="header"]
+|===
+| Placeholder | Description | Example | Files
 
-### Project Identity
+| `Jonathan D.A. Jewell` | Full legal name | `Jane Doe` | SPDX headers (all files), MAINTAINERS.md, .mailmap, .reuse/dep5, docs/AI-CONVENTIONS.md
+| `j.d.a.jewell@open.ac.uk` | Primary contact email | `jane@example.org` | SPDX headers (all files), .mailmap, .reuse/dep5, .well-known/humans.txt
+| `{{AUTHOR_EMAIL_ALT}}` | Previous/secondary email (for .mailmap) | `old@example.com` | .mailmap
+| `{{AUTHOR_ORG}}` | Author's organization/affiliation | `Acme University` | project-metadata.k9.ncl
+| `{{AUTHOR_LAST}}` | Author surname (for citations) | `Doe` | docs/CITATIONS.adoc
+| `{{AUTHOR_FIRST}}` | Author first name (for citations) | `Jane` | docs/CITATIONS.adoc
+| `{{AUTHOR_INITIALS}}` | Author initials (for citations) | `J.` | docs/CITATIONS.adoc
+|===
 
-| Placeholder | Description | Example | Files |
-|---|---|---|---|
-| `The Nash Equilibrium` | Human-readable project name | `My Project` | SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, GOVERNANCE.md, MAINTAINERS.md, flake.nix, devcontainer.json |
-| `6X strategy board game exploring economic systems, planetary boundaries, and post-scarcity futures` | One-line description | `A tool for X` | flake.nix |
-| `{{PROJECT}}` | Uppercase identifier (for Idris2 modules, C macros) | `MY_PROJECT` | ABI-FFI-README.md, src/interface/abi/*.idr, src/interface/ffi/*.zig |
-| `the-nash-equilibrium` | Lowercase identifier (for C symbols, filenames) | `my_project` | ABI-FFI-README.md, src/interface/ffi/*.zig |
-| `the-nash-equilibrium` | Repository name (slug) | `my-project` | CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, cliff.toml |
-| `hyperpolymath` | GitHub/GitLab org or username | `my-org` | SPDX headers, CONTRIBUTING.md, SECURITY.md, GOVERNANCE.md, MAINTAINERS.md, CODEOWNERS, mirror.yml, cliff.toml |
-| `github.com` | Git forge domain | `github.com` | CONTRIBUTING.md |
+=== Project Identity
 
-### Dates
+[cols="1,1,1,1",options="header"]
+|===
+| Placeholder | Description | Example | Files
 
-| Placeholder | Description | Example | Files |
-|---|---|---|---|
-| `2026` | Current year | `2026` | SPDX headers (all files), GOVERNANCE.md, MAINTAINERS.md |
-| `{{CURRENT_DATE}}` | Current date (ISO) | `2026-02-14` | STATE.a2ml, MAINTAINERS.md |
-| `{{DATE}}` | Last updated date | `2026-02-14` | TOPOLOGY.md, THREAT-MODEL.md |
+| `The Nash Equilibrium` | Human-readable project name | `My Project` | SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, GOVERNANCE.md, MAINTAINERS.md, flake.nix, devcontainer.json
+| `6X strategy board game exploring economic systems, planetary boundaries, and post-scarcity futures` | One-line description | `A tool for X` | flake.nix
+| `{{PROJECT}}` | Uppercase identifier (for Idris2 modules, C macros) | `MY_PROJECT` | ABI-FFI-README.md, src/interface/abi/*.idr, src/interface/ffi/*.zig
+| `the-nash-equilibrium` | Lowercase identifier (for C symbols, filenames) | `my_project` | ABI-FFI-README.md, src/interface/ffi/*.zig
+| `the-nash-equilibrium` | Repository name (slug) | `my-project` | CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, cliff.toml
+| `hyperpolymath` | GitHub/GitLab org or username | `my-org` | SPDX headers, CONTRIBUTING.md, SECURITY.md, GOVERNANCE.md, MAINTAINERS.md, CODEOWNERS, mirror.yml, cliff.toml
+| `github.com` | Git forge domain | `github.com` | CONTRIBUTING.md
+|===
 
-### Contact & Security
+=== Dates
 
-| Placeholder | Description | Example | Files |
-|---|---|---|---|
-| `j.d.a.jewell@open.ac.uk` | Security contact email | `security@example.org` | SECURITY.md |
-| `TODO` | 40-char PGP fingerprint | `ABCD 1234 ...` | SECURITY.md |
-| `TODO` | URL to public PGP key | `https://keys.openpgp.org/...` | SECURITY.md |
-| `{{WEBSITE}}` | Project website | `https://example.org` | SECURITY.md |
-| `j.d.a.jewell@open.ac.uk` | Conduct reports email | `conduct@example.org` | CODE_OF_CONDUCT.md |
-| `maintainers` | Conduct committee name | `Code of Conduct Committee` | CODE_OF_CONDUCT.md |
-| `48 hours` | SLA for initial response | `48 hours` | CODE_OF_CONDUCT.md |
+[cols="1,1,1,1",options="header"]
+|===
+| Placeholder | Description | Example | Files
 
-### Git
+| `2026` | Current year | `2026` | SPDX headers (all files), GOVERNANCE.md, MAINTAINERS.md
+| `{{CURRENT_DATE}}` | Current date (ISO) | `2026-02-14` | STATE.a2ml, MAINTAINERS.md
+| `{{DATE}}` | Last updated date | `2026-02-14` | TOPOLOGY.md, THREAT-MODEL.md
+|===
 
-| Placeholder | Description | Example | Files |
-|---|---|---|---|
-| `main` | Main branch name | `main` | CONTRIBUTING.md |
+=== Contact & Security
 
-### Build
+[cols="1,1,1,1",options="header"]
+|===
+| Placeholder | Description | Example | Files
 
-| Placeholder | Description | Example | Files |
-|---|---|---|---|
-| `{{LICENSE}}` | License name | `AGPL-3.0-or-later` | ABI-FFI-README.md |
-| `6X strategy board game` | One-line project description | `FFI bridges between languages` | STATE.a2ml |
+| `j.d.a.jewell@open.ac.uk` | Security contact email | `security@example.org` | SECURITY.md
+| `TODO` | 40-char PGP fingerprint | `ABCD 1234 ...` | SECURITY.md
+| `TODO` | URL to public PGP key | `https://keys.openpgp.org/...` | SECURITY.md
+| `{{WEBSITE}}` | Project website | `https://example.org` | SECURITY.md
+| `j.d.a.jewell@open.ac.uk` | Conduct reports email | `conduct@example.org` | CODE_OF_CONDUCT.md
+| `maintainers` | Conduct committee name | `Code of Conduct Committee` | CODE_OF_CONDUCT.md
+| `48 hours` | SLA for initial response | `48 hours` | CODE_OF_CONDUCT.md
+|===
 
-### AI Manifest
+=== Git
 
-| Placeholder | Description | Example | Files |
-|---|---|---|---|
-| `[YOUR-REPO-NAME]` | Repository name | `my-project` | 0-AI-MANIFEST.a2ml |
-| `[DATE]` | Creation date | `2026-02-14` | 0-AI-MANIFEST.a2ml |
-| `[YOUR-NAME/ORG]` | Maintainer name | `hyperpolymath` | 0-AI-MANIFEST.a2ml |
+[cols="1,1,1,1",options="header"]
+|===
+| Placeholder | Description | Example | Files
 
-### AI Installation Guide
+| `main` | Main branch name | `main` | CONTRIBUTING.md
+|===
 
-| Marker | Description | Files |
-|---|---|---|
-| `[TODO-AI-INSTALL]` | Unfilled section in AI installation guide | `docs/AI_INSTALLATION_GUIDE.adoc`, `docs/AI-INSTALL-README-SECTION.adoc`, `README.adoc` |
+=== Build
+
+[cols="1,1,1,1",options="header"]
+|===
+| Placeholder | Description | Example | Files
+
+| `{{LICENSE}}` | License name | `AGPL-3.0-or-later` | ABI-FFI-README.md
+| `6X strategy board game` | One-line project description | `FFI bridges between languages` | STATE.a2ml
+|===
+
+=== AI Manifest
+
+[cols="1,1,1,1",options="header"]
+|===
+| Placeholder | Description | Example | Files
+
+| `[YOUR-REPO-NAME]` | Repository name | `my-project` | 0-AI-MANIFEST.a2ml
+| `[DATE]` | Creation date | `2026-02-14` | 0-AI-MANIFEST.a2ml
+| `[YOUR-NAME/ORG]` | Maintainer name | `hyperpolymath` | 0-AI-MANIFEST.a2ml
+|===
+
+=== AI Installation Guide
+
+[cols="1,1,1",options="header"]
+|===
+| Marker | Description | Files
+
+| `[TODO-AI-INSTALL]` | Unfilled section in AI installation guide | `docs/AI_INSTALLATION_GUIDE.adoc`, `docs/AI-INSTALL-README-SECTION.adoc`, `README.adoc`
+|===
 
 These are **not** standard `{{PLACEHOLDER}}` markers -- they are TODO markers
 that must be replaced with project-specific content before release. They mark
@@ -118,25 +143,29 @@ sections where the developer (or AI) must fill in:
 
 **finishbot checks:** `just validate-ai-install` verifies no `[TODO-AI-INSTALL]` markers remain.
 
-## Deletion Markers
+== Deletion Markers
 
 Some files contain deletion instructions:
 
-| Marker | Meaning | File |
-|---|---|---|
-| `{{~ ... ~}}` | Delete this entire line after reading | ABI-FFI-README.md (line 1) |
+[cols="1,1,1",options="header"]
+|===
+| Marker | Meaning | File
+
+| `{{~ ... ~}}` | Delete this entire line after reading | ABI-FFI-README.md (line 1)
+|===
 
-## Verification
+== Verification
 
 After replacing all placeholders, verify none remain:
 
-```bash
+[source,bash]
+----
 grep -rn '{{' . --include='*.md' --include='*.adoc' --include='*.a2ml' \
   --include='*.scm' --include='*.idr' --include='*.zig' --include='*.res' \
   --include='Justfile' --include='*.nix' --include='*.toml' --include='*.yml' \
   --include='*.yaml' --include='*.hs' --include='*.ncl' --include='*.txt' \
   --include='*.json' --include='Containerfile' --include='dep5' \
   | grep -v 'PLACEHOLDERS.md' | grep -v 'node_modules'
-```
+----
 
 If the above command produces no output, all placeholders have been replaced.

Justfile

@@ -281,10 +281,20 @@ docs:
     just man
     @echo "Documentation generated in docs/"
 
-# Check every .adoc actually renders (content-side counterpart to the .md ban)
-docs-check:
+# Check the docs three ways: named .adoc, parses, and is actually AsciiDoc.
+# The three are independent — eight files once passed the first two while their
+# bodies were still Markdown (SPDX headers rendering as visible text, tables
+# rendering as garbage). See scripts/check-adoc-not-markdown.sh.
+docs-check: docs-check-render docs-check-dialect
+
+# Every .adoc must parse (content-side counterpart to the .md extension ban)
+docs-check-render:
     @./scripts/check-docs-render.sh .
 
+# Every .adoc must be AsciiDoc, not Markdown wearing an .adoc extension
+docs-check-dialect:
+    @./scripts/check-adoc-not-markdown.sh .
+
 # Render the docs to HTML for local reading [reversible: rm -rf docs/generated/html]
 docs-html:
     #!/usr/bin/env bash

docs/STATE-VISUALIZER.adoc

@@ -1,15 +1,11 @@
-= Project State Visualizer
-[source]
-----
-<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
-<!-- TOPOLOGY.md — Project architecture map and completion dashboard -->
-<!-- Last updated: 2026-02-28 -->
-
-# RSR Template Repo — Project Topology
+// SPDX-License-Identifier: CC-BY-SA-4.0
+// TOPOLOGY.md — Project architecture map and completion dashboard
+// Last updated: 2026-02-28
+= RSR Template Repo — Project Topology
 
-## System Architecture
+== System Architecture
 
-```
+----
                         ┌─────────────────────────────────────────┐
                         │              NEW REPOSITORY             │
                         │        (Consumer of this Template)      │
@@ -56,11 +52,11 @@
                         │  Justfile / Mustfile  .machine_readable/  │
                         │  Codeowners / Reuse   0-AI-MANIFEST.a2ml  │
                         └─────────────────────────────────────────┘
-```
+----
 
-## Completion Dashboard
+== Completion Dashboard
 
-```
+----
 COMPONENT                          STATUS              NOTES
 ─────────────────────────────────  ──────────────────  ─────────────────────────────────
 CORE STANDARDS
@@ -92,11 +88,11 @@ REPO INFRASTRUCTURE
 
 ─────────────────────────────────────────────────────────────────────────────
 OVERALL:                            ██████████ 100%    RSR Template Stable & Certified
-```
+----
 
-## Key Dependencies
+== Key Dependencies
 
-```
+----
 Philosophy ──────► RSR Standard ──────► Template Scaffolding ──► New Repo
      │                 │                      │                    │
      ▼                 ▼                      ▼                    ▼
@@ -112,9 +108,9 @@ CCCP Policy ─────► 0-AI-MANIFEST ────────► Justfil
                                               │
                                               ▼
                                          k9-svc deploy
-```
+----
 
-## Update Protocol
+== Update Protocol
 
 This file is maintained by both humans and AI agents. When updating:
 
@@ -125,4 +121,3 @@ This file is maintained by both humans and AI agents. When updating:
 
 Progress bars use: `█` (filled) and `░` (empty), 10 characters wide.
 Percentages: 0%, 10%, 20%, ... 100% (in 10% increments).
-----