Lint reStructuredText prose with Vale

Ban em dashes in reStructuredText using the pinned ClearProse Vale style
package.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: adamtheturtle

.gitignore

@@ -112,3 +112,6 @@ secrets.tar
 src/*/_setuptools_scm_version.txt
 
 uv.lock
+
+# Vale styles downloaded by ``vale sync``
+styles/

.pre-commit-config.yaml

@@ -288,6 +288,33 @@ repos:
           - *uv_version
         stages: [pre-commit]
 
+      # Vale enforces prose style rules, such as banning em dashes, in
+      # reStructuredText files.
+      # The rules come from the ``ClearProse`` package pinned in ``.vale.ini``,
+      # which ``vale sync`` downloads into the (gitignored) ``styles``
+      # directory.
+      # Vale needs ``rst2html`` from Docutils on the ``PATH`` to parse
+      # reStructuredText.
+      - id: vale-sync
+        name: vale sync
+        entry: uv run --extra=dev vale sync
+        language: python
+        pass_filenames: false
+        types_or: [rst]
+        additional_dependencies:
+          - *uv_version
+        stages: [pre-commit]
+
+      - id: vale
+        name: vale
+        entry: uv run --extra=dev vale
+        language: python
+        types_or: [rst]
+        require_serial: true
+        additional_dependencies:
+          - *uv_version
+        stages: [pre-commit]
+
       - id: interrogate
         name: interrogate
         entry: uv run --extra=dev -m interrogate

.vale.ini

@@ -0,0 +1,12 @@
+StylesPath = styles
+MinAlertLevel = error
+
+Packages = https://github.com/adamtheturtle/vale-style-clear-prose/releases/download/v1.0.1/ClearProse.zip
+
+[*.rst]
+BasedOnStyles = ClearProse
+
+# Docutils does not know Sphinx roles such as `:ref:`, and renders their
+# argument as ordinary prose. Ignoring role syntax keeps target names, which
+# are not prose, out of the linter.
+TokenIgnores = (:\w+:`[^`]*`)

pyproject.toml

@@ -84,6 +84,7 @@ optional-dependencies.dev = [
     "towncrier==25.8.0",
     "ty==0.0.65",
     "types-requests==2.33.0.20260712",
+    "vale==3.13.0.0",
     "vulture==2.16",
     "vws-python-mock==2026.8.4.2",
     "vws-test-fixtures==2023.3.5",
@@ -286,6 +287,7 @@ ignore = [
     ".git_archival.txt",
     ".pre-commit-config.yaml",
     ".prettierrc",
+    ".vale.ini",
     ".yamlfmt",
     "CHANGELOG.rst",
     "ci",