Skip to content

chore: rename docs/specs/SPEC.md and faces.md to .adoc #96

Description

@hyperpolymath

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

  • docs/specs/SPEC.mddocs/specs/SPEC.adoc
  • docs/specs/faces.mddocs/specs/faces.adoc

What "rename" means here

For each file:

  1. git mv docs/specs/<name>.md docs/specs/<name>.adoc
  2. 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
  3. Add the standard preamble at top:
    // SPDX-License-Identifier: PMPL-1.0-or-later
    = <Title>
    :toc: macro
    :toclevels: 2
    :source-highlighter: rouge
    
    toc::[]
    
  4. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions