feat(readme): enforce anchor-ID convention + document .adoc bootstrap (ADR-004)

Discovered while verifying the Phase C pilot on boj-server's real README:
a machine md->adoc conversion of a README with an intra-doc TOC produces
dead TOC links, because Asciidoctor's default section IDs are
'_prefixed_underscored' while GitHub Markdown anchors are
'lowercase-hyphenated'. The vocabulary gate cannot catch this (it checks
words, not link targets).

- readme-derive-reusable.yml: new 'Anchor-ID convention guard' step —
  if the canonical .adoc has link:#… anchors but does not set ':idprefix:'
  (empty) and ':idseparator: -', fail-and-tell before deriving.
- ADR-004: new 'Bootstrapping a canonical .adoc' section — the mandatory
  idprefix/idseparator convention + the one-time md->adoc bootstrap recipe,
  both verified end-to-end on boj-server (11/11 TOC anchors resolve, 12/12
  badges intact, >=98% vocab with only AsciiDoc scaffolding tokens 'lost').

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

Author: hyperpolymath

.github/workflows/readme-derive-reusable.yml

@@ -126,6 +126,31 @@ jobs:
             https://github.com/hyperpolymath/standards.git "$RUNNER_TEMP/standards"
           chmod +x "$RUNNER_TEMP/standards/.github/scripts/readme-vocab-gate.sh"
 
+      - name: Anchor-ID convention guard
+        if: steps.decl.outputs.derive == 'true'
+        env:
+          CANONICAL: ${{ steps.decl.outputs.canonical }}
+        run: |
+          set -euo pipefail
+          # A canonical .adoc with intra-document anchor links (link:#foo[] or
+          # <<foo>> written as #foo) only renders a working TOC on GitHub and
+          # re-derives to matching Markdown anchors when it opts out of
+          # Asciidoctor's default '_prefixed_underscored' section IDs. So if the
+          # source uses #anchors, it MUST set :idprefix: (empty) and
+          # :idseparator: -  — otherwise every TOC link silently dead-links
+          # (a failure the vocabulary gate cannot see, since it checks words not
+          # link targets). See ADR-004 "Bootstrapping a canonical .adoc".
+          if grep -qE 'link:#[a-z0-9-]+\[' "$CANONICAL"; then
+            if ! grep -qE '^:idprefix:[[:space:]]*$' "$CANONICAL" \
+               || ! grep -qE '^:idseparator:[[:space:]]+-[[:space:]]*$' "$CANONICAL"; then
+              echo "::error::$CANONICAL has intra-doc anchor links (link:#…) but does not set ':idprefix:' (empty) and ':idseparator: -' in its header. Without them Asciidoctor generates '_underscored' section IDs and every #anchor TOC link dead-links on GitHub and in the derived README.md. Add both attributes to the document header (see ADR-004)."
+              exit 1
+            fi
+            echo "✓ anchor-ID convention satisfied (idprefix/idseparator set)"
+          else
+            echo "✓ no intra-doc anchors — convention not required"
+          fi
+
       - name: Derive Markdown from AsciiDoc
         if: steps.decl.outputs.derive == 'true'
         env:

docs/decisions/ADR-004-readme-single-source-derive.adoc

@@ -98,6 +98,56 @@ Rules:
 * Any estate sweep touching README format MUST read this block first
   and skip undeclared repos. This is the anti-runaway guard.
 
+=== Bootstrapping a canonical `.adoc` from an existing `README.md`
+
+The derive direction (`.adoc → .md`) is a clean one-shot. Producing the
+*initial* canonical `.adoc` from a rich existing `README.md` is a
+one-time authoring step, not part of the CI path, and has one sharp edge
+verified on boj-server's real README (264 lines, 12 badges, 15-entry TOC):
+
+**Anchor-ID convention (mandatory when the README has an intra-doc TOC).**
+GitHub Markdown auto-anchors headings as lowercase-hyphenated
+(`## Capabilities overview` → `#capabilities-overview`). Asciidoctor
+instead defaults to `_prefixed_underscored` IDs
+(`_capabilities_overview`), so a converted `link:#capabilities-overview[]`
+TOC would dead-link on GitHub *and* re-derive to a broken Markdown anchor.
+The canonical `.adoc` MUST therefore set, in its document header:
+
+[source,asciidoc]
+----
+= Project Title
+:idprefix:
+:idseparator: -
+----
+
+With those two attributes, `== Features` → id `features`,
+`== Capabilities overview` → id `capabilities-overview` — matching GitHub
+Markdown exactly. `readme-derive-reusable.yml` enforces this: if the
+canonical source contains `link:#…[]` anchors without both attributes, the
+job fails-and-tells (the vocabulary gate cannot catch this — it checks
+words, not link targets).
+
+**One-time bootstrap recipe** (verified end-to-end on boj-server —
+faithful round-trip: 11/11 TOC anchors resolve, 12/12 badges intact,
+≥98% vocab, only AsciiDoc scaffolding tokens "lost"):
+
+[source,bash]
+----
+# 1. md -> asciidoc body
+pandoc -f gfm -t asciidoc --wrap=preserve README.md -o body.adoc
+# 2. promote every heading one level (== -> =, === -> ==, …) so the top
+#    heading becomes the '= doctitle' and section nesting stays correct
+sed -E 's/^==(=*) /=\1 /' body.adoc > body2.adoc
+# 3. assemble canonical README.adoc: SPDX header + '= Title' +
+#    :idprefix:/:idseparator: -  + body2 (minus its first title line)
+# 4. sanity: render to HTML, confirm section ids match the TOC anchors
+----
+
+pandoc wraps inline code containing `_ * { +` in AsciiDoc passthroughs
+(`++_*++`, `{plus}`) — correct and harmless (renders as literal text; the
+derived `.md` comes back clean), just visible noise in the source. Accept
+it, or tidy by hand; do not "fix" it in a way that changes rendered output.
+
 === Derivation pipeline (reusable workflow, `standards`)
 
 One reusable workflow, `readme-derive.yml`, called by opted-in repos