Background
The estate documentation-format rule (DOC-FORMAT in .claude/CLAUDE.md) is:
All documentation files in docs/ must use .adoc extension.
Exception: GitHub community-health files must use .md by name (CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, CHANGELOG.md, README.md).
Two files in docs/specs/ on main predate this rule and still use .md. Neither matches the community-health exception.
Files to rename
What "rename" means here
For each file:
git mv docs/specs/<name>.md docs/specs/<name>.adoc
- Convert Markdown syntax to AsciiDoc:
- Headings:
#/##/###/#### → =/==/===/====
- Pipe-tables →
[cols="..."] |=== blocks
- Fenced code (```lang) →
[source,lang] `----` listings
- Emphasis:
**bold** → *bold*, *italic* → _italic_
- Inline code (
`x`) stays the same
- Add the standard preamble at top:
// SPDX-License-Identifier: PMPL-1.0-or-later
= <Title>
:toc: macro
:toclevels: 2
:source-highlighter: rouge
toc::[]
- Grep the rest of the repo for inbound references to the old
.md paths and update each one (e.g. docs/specs/SPEC.md referenced from other specs, READMEs, justfiles, CI scripts, the bin/main.ml --help blurb if applicable).
Acceptance
- Both files renamed and rewritten in valid AsciiDoc.
git grep -nE 'docs/specs/(SPEC|faces)\.md' returns no hits except in CHANGELOG-style historical notes.
- The PR body lists every inbound reference touched.
Why this is good-first-issue
The conversion is mechanical, the rule is documented in .claude/CLAUDE.md (DOC-FORMAT), and docs/specs/affex-spec.adoc (landed on PR #93's branch) is a worked example of the same Markdown → AsciiDoc conversion at this scale.
Out of scope
- Do not touch any open PR's branch as part of this work —
SPEC.md and faces.md show up in several open PRs' diffs and renaming them mid-PR creates merge churn. Wait for those PRs to merge or be closed, then do this rename in a single small PR against main.
Background
The estate documentation-format rule (
DOC-FORMATin.claude/CLAUDE.md) is:Two files in
docs/specs/onmainpredate this rule and still use.md. Neither matches the community-health exception.Files to rename
docs/specs/SPEC.md→docs/specs/SPEC.adocdocs/specs/faces.md→docs/specs/faces.adocWhat "rename" means here
For each file:
git mv docs/specs/<name>.md docs/specs/<name>.adoc#/##/###/####→=/==/===/====[cols="..."]|===blocks[source,lang]`----` listings**bold**→*bold*,*italic*→_italic_`x`) stays the same.mdpaths and update each one (e.g.docs/specs/SPEC.mdreferenced from other specs, READMEs, justfiles, CI scripts, thebin/main.ml --helpblurb if applicable).Acceptance
git grep -nE 'docs/specs/(SPEC|faces)\.md'returns no hits except in CHANGELOG-style historical notes.Why this is
good-first-issueThe conversion is mechanical, the rule is documented in
.claude/CLAUDE.md(DOC-FORMAT), anddocs/specs/affex-spec.adoc(landed on PR #93's branch) is a worked example of the same Markdown → AsciiDoc conversion at this scale.Out of scope
SPEC.mdandfaces.mdshow up in several open PRs' diffs and renaming them mid-PR creates merge churn. Wait for those PRs to merge or be closed, then do this rename in a single small PR againstmain.