Spec Format: Markdown + YAML Hybrid

We store each Spec as a Markdown file with YAML front-matter. The front-matter carries structured metadata (id, tools, severity, appliesTo, dependsOn) that scripts can parse; the Markdown body carries the human-readable explanation of why this rule exists and what it means in our codebase.

Considered options: - Pure YAML — machine-friendly but poor git diff, poor readability, no room for explanation. - Pure Markdown — great readability but no structured metadata for tooling. - Markdown + YAML front-matter — best of both: structured and readable.

Consequences: - Every Spec file follows the same template, making bulk operations (lint, render, sync) predictable. - Git diffs stay meaningful — changes to the explanation don't shuffle metadata fields. - MkDocs can render Markdown natively; front-matter is ignored by the renderer unless explicitly parsed.