feat(readme): enforce anchor-ID convention + document .adoc bootstrap (ADR-004)#476
Merged
Merged
Conversation
…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>
hyperpolymath
enabled auto-merge (squash)
July 9, 2026 06:20
…rivation Make derivation reproducible so the freshness check is trustworthy: - Install step pins pandoc 3.10 + asciidoctor 2.0.26 + asciidoctor-reducer 1.1.1 (was: floating apt/gem latest). The committed README.md must be generated by the same versions CI runs, or cosmetic toolchain drift would be misreported as staleness. Bump deliberately + regenerate; never float. - Freshness check normalises (strip banner, trim trailing WS, squeeze blank runs) before diffing — belt-and-braces so a harmless whitespace nudge is not flagged, while real prose/structure/anchor changes still show. Verified against boj-server's real README end-to-end: normalised body byte-identical on re-derive, vocab 98.7%, anchor guard satisfied. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
hyperpolymath
disabled auto-merge
July 9, 2026 08:33
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #475 (merged). A finding from verifying the Phase C pilot on boj-server's real README.
The finding
A machine
md → adocconversion of a README with an intra-doc TOC produces dead TOC links: Asciidoctor's default section IDs are_prefixed_underscoredwhile GitHub Markdown anchors arelowercase-hyphenated. So[Features](#features)→link:#features[]points at#featuresbut the heading's real ID is_features. The vocabulary gate cannot catch this — it checks words, not link targets.Fix
readme-derive-reusable.yml— new Anchor-ID convention guard step: if the canonical.adochaslink:#…anchors but doesn't set:idprefix:(empty) and:idseparator: -, fail-and-tell before deriving.md→adocbootstrap recipe.Verified end-to-end on boj-server (via containerised pandoc 3.10 + asciidoctor 2.0.26)
With the convention applied: 11/11 TOC anchors resolve, 12/12 badges intact (incl. Glama), proper
h2/h3nesting, vocab 98.7% — and the only "lost" tokens are AsciiDoc scaffolding (cols,options,idprefix,filecopyrighttext…), i.e. zero real prose lost. Blockquote + inline code (boj_*,{error, hint}) round-trip clean.Unblocks the boj-server + profile-repo pilot PRs (which will be un-armed pending owner visual-check on Glama / the profile page).
🤖 Generated with Claude Code