DEVX-118: feat: enhance documentation-as-code with badges, version refs, Vale

- Fix badge system: clean .badges dir from orphan branch, add version
  verification, make badges job depend on release (avoids stale version
  badge race condition)
- Add check_doc_versions.py: lint tool that verifies docs version
  references match current __version__, with --fix for auto-update
- Integrate check_doc_versions into release process (auto-updates docs
  on every release commit)
- Add Vale prose linter integration: .vale.ini, custom styles for
  terminology and code block language, CI step, make target
- Fix stale version references in docs (0.27.0 → 0.33.4)
- Fix e.g. → for example in docs (Google.Latin Vale rule)
- Add CI steps for check_doc_versions and Vale to quality workflow
- Add make targets: devx-check-doc-versions, devx-vale

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

tests/unit/test_push_badges.py

@@ -68,10 +68,12 @@ class TestPushToBadgesBranch:
 
         sha_result = MagicMock()
         sha_result.stdout = "abc123\n"
+        diff_result = MagicMock()
+        diff_result.stdout = "coverage.svg\n"
         default_result = MagicMock()
         with patch(
             "subprocess.run",
-            side_effect=[default_result] * 7 + [sha_result],
+            side_effect=[default_result] * 6 + [diff_result] + [default_result, default_result, sha_result],
         ) as mock_run:
             sha = push_badges.push_to_badges_branch(str(badges_dir))
 
@@ -143,6 +145,40 @@ class TestUpdateReadmeWithBadgeSha:
             push_badges.update_readme_with_badge_sha("abc123def456", repo_root=tmp_path)
         # Should not raise
 
+    def test_version_verification_stale(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        readme = tmp_path / "README.md"
+        readme.write_text("[![Tests](https://git.oblachno.oblachno.fyi/my-org/my-repo/raw/branch/badges/tests.svg)]")
+        monkeypatch.chdir(tmp_path)
+        badges_dir = tmp_path / ".badges"
+        badges_dir.mkdir(exist_ok=True)
+        (badges_dir / "version.svg").write_text("version: v0.27.0")
+        with patch("subprocess.run"):
+            with patch("devx.tools.generate_badges.detect_package_name", return_value="devx"):
+                with patch("devx.tools.generate_badges.read_version", return_value="0.33.4"):
+                    push_badges.update_readme_with_badge_sha("abc123def456", repo_root=tmp_path)
+
+    def test_version_verification_current(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        readme = tmp_path / "README.md"
+        readme.write_text("[![Tests](https://git.oblachno.oblachno.fyi/my-org/my-repo/raw/branch/badges/tests.svg)]")
+        monkeypatch.chdir(tmp_path)
+        badges_dir = tmp_path / ".badges"
+        badges_dir.mkdir(exist_ok=True)
+        (badges_dir / "version.svg").write_text("version: v0.33.4")
+        with patch("subprocess.run"):
+            with patch("devx.tools.generate_badges.detect_package_name", return_value="devx"):
+                with patch("devx.tools.generate_badges.read_version", return_value="0.33.4"):
+                    push_badges.update_readme_with_badge_sha("abc123def456", repo_root=tmp_path)
+
+    def test_version_verification_no_badges_dir(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        readme = tmp_path / "README.md"
+        readme.write_text("[![Tests](https://git.oblachno.oblachno.fyi/my-org/my-repo/raw/branch/badges/tests.svg)]")
+        monkeypatch.chdir(tmp_path)
+        # No .badges/version.svg exists — should skip verification gracefully
+        with patch("subprocess.run"):
+            with patch("devx.tools.generate_badges.detect_package_name", return_value="devx"):
+                with patch("devx.tools.generate_badges.read_version", return_value="0.33.4"):
+                    push_badges.update_readme_with_badge_sha("abc123def456", repo_root=tmp_path)
+
 
 class TestMain:
     def test_success(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: