[chrsmith]

Human Summary

This repository contains many important Markdown files. However, the formatting of those is inconsistent. And in some cases, notably PRINCIPLES.md, this makes reviewing edits nearly impossible. (An entire paragraph of text is on a single "line" in the file, which trips up most diffing algorithms.)

This PR adds a dependency on an automated Markdown formatter, rvben/rumdl, and wires it up to CI/CD. You will now get a build error if you try to submit changes to a Markdown file that introduces any sort of diff from (cargo fmt-markdown).

Generated Markdown files are excluded from this.

Summary

Most Markdown docs in this repo put each paragraph on one long line, which makes diffs and reviews hard to read. This PR adds a pinned Markdown formatter, enforces it in CI, and applies it to the existing docs.

Commit 1: tooling (Add cargo validate markdown and cargo fmt-markdown)

• cargo fmt-markdown rewraps Markdown in place: paragraphs, lists and blockquotes are filled to 80 columns, and table columns are aligned.
• cargo validate markdown (also part of cargo validate) fails when files need reformatting and prints: "Markdown formatting check failed. Run cargo fmt-markdown to rewrap the files listed above, then commit the result."
• A new CI step, Validate Markdown, runs the check and adds an ::error:: annotation with the same instruction.
• The formatter is rumdl, pinned to 0.2.79 in xtask/src/markdown.rs. On first use it is installed into target/tools/ with cargo install --locked --version =0.2.79, so nothing comes from PATH. crates.io releases are immutable, cargo verifies checksums, and --locked uses rumdl's published lockfile. CI caches target/tools with actions/cache, pinned by SHA.
• .rumdl.toml enables only line wrapping (MD013, normalize reflow mode) and table alignment (MD060). It excludes CHANGELOG.md, which release tooling generates, and changelog/*/*.md fragments, where each line is a separate entry. Headings, code blocks and long unbreakable inline code spans are left as they are.
• AGENTS.md and CONTRIBUTING.md now document the new commands.

Commit 2: bulk reformat (Rewrap human-authored Markdown at 80 columns)

• This commit is only the output of cargo fmt-markdown across 70 files; review commit 1 separately.
• Every changed file was rendered to HTML (CommonMark plus tables) before and after the change, and the output is identical.

Test plan

• cargo validate passes locally (Rust, Markdown, Python, TypeScript, Go, Java, .NET)
• cargo validate markdown exits non-zero with the message above on unformatted docs
• Rendered HTML is unchanged for all 70 reformatted files

Internal tooling only, so this needs the skip-changelog label.

🤖 Generated with Claude Code