Skip to content

Commit cff7c65

Browse files
hyperpolymathclaude
andcommitted
chore(readme): flip to single-source .adoc + derived .md (ADR-004 pilot)
boj-server is one of two estate repos with a genuine Markdown-only consumer (Glama, which renders README.adoc as raw markup). Per ADR-004, flip it from a hand-authored README.md to authored README.adoc + CI-derived README.md: - README.adoc: new canonical source (bootstrapped from the prior README.md via the ADR-004 recipe; sets :idprefix:/:idseparator: - so the TOC anchors resolve on GitHub and re-derive cleanly). - README.md: now a GENERATED artefact (banner stamped; do not hand-edit). Verified faithful: 11/11 TOC anchors resolve, 12/12 badges intact (incl. Glama), blockquote + inline code round-trip clean. - ECOSYSTEM.a2ml: [publishing.readme] declaration (consumer=glama) — the machine-readable opt-in the derive workflow reads. - .github/workflows/readme-derive.yml: caller for the standards reusable; regenerates + freshness-checks README.md on changes. Local verification (pandoc 3.10 + asciidoctor 2.0.26): vocab gate 98.7%, normalised freshness byte-identical, anchor guard satisfied. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent ed5c741 commit cff7c65

4 files changed

Lines changed: 406 additions & 64 deletions

File tree

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# SPDX-License-Identifier: MPL-2.0
2+
# README single-source derivation (ADR-004): README.adoc is canonical;
3+
# README.md is derived for the Glama MCP directory (Markdown-only renderer).
4+
# This caller delegates to the standards reusable, which reads the
5+
# [publishing.readme] declaration in .machine_readable/*/ECOSYSTEM.a2ml,
6+
# regenerates README.md behind a vocabulary gate, and fails-and-tells if the
7+
# committed README.md is stale relative to README.adoc.
8+
name: README Derive
9+
10+
on:
11+
push:
12+
branches: [main, master]
13+
paths:
14+
- README.adoc
15+
- README.md
16+
- .machine_readable/**/ECOSYSTEM.a2ml
17+
pull_request:
18+
paths:
19+
- README.adoc
20+
- README.md
21+
- .machine_readable/**/ECOSYSTEM.a2ml
22+
23+
permissions:
24+
contents: read
25+
26+
jobs:
27+
readme-derive:
28+
# Pinned to the standards commit that introduced readme-derive-reusable.yml.
29+
# Repin to include hyperpolymath/standards#476 (anchor-ID convention guard)
30+
# once it lands on main; this repo's README.adoc already satisfies it.
31+
uses: hyperpolymath/standards/.github/workflows/readme-derive-reusable.yml@db12a6ad3ef9076d5f7bdcf98d7d15cf8547555a

.machine_readable/6a2/ECOSYSTEM.a2ml

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,3 +48,15 @@ seed-nodes = [
4848
]
4949
dns-status = "hyperpolymath.dev undelegated — registrar action needed (see container/fly/DNS-SETUP.adoc); *.fly.dev hostnames operative"
5050
federation-protocol = "Umoja gossip (X25519 + ChaCha20-Poly1305, UDP 9999, IPv6)"
51+
52+
# ── Publishing (ADR-004: README single-source derivation) ──────────────────
53+
# README.adoc is canonical; README.md is DERIVED (GENERATED banner) for Glama,
54+
# which renders Markdown only. Regenerated + freshness-checked by the
55+
# readme-derive workflow. Never hand-edit README.md.
56+
[publishing.readme]
57+
canonical = "README.adoc"
58+
derive = true
59+
format = "gfm"
60+
path = "README.md"
61+
consumer = "glama"
62+
reason = "Glama MCP directory renders Markdown only; canonical README.adoc renders as raw markup there"

0 commit comments

Comments
 (0)