Add Markdown linting

.github/workflows/ci.yml

@@ -5,6 +5,19 @@ on:
   pull_request:
 
 jobs:
+  markdownlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+
+      - name: Run Markdown lint
+        run: ./scripts/validate_markdown.sh
+
   pre-commit:
     runs-on: ubuntu-latest
     steps:

.markdownlint-cli2.jsonc

@@ -0,0 +1,42 @@
+{
+  "globs": [
+    "**/*.md",
+    "!**/node_modules/**",
+    "!**/.venv/**",
+    "!**/.next/**",
+    "!**/.pytest_cache/**"
+  ],
+  "config": {
+    "default": true,
+    "MD013": false,
+    "MD024": {
+      "siblings_only": true
+    },
+    "MD033": false,
+    "MD046": {
+      "style": "fenced"
+    }
+  },
+  "overrides": [
+    {
+      "filter": [
+        ".github/pull_request_template.md"
+      ],
+      "config": {
+        "MD041": false
+      },
+      "combine": "merge"
+    },
+    {
+      "filter": [
+        "AGENTS.md"
+      ],
+      "config": {
+        "MD004": false,
+        "MD022": false,
+        "MD032": false
+      },
+      "combine": "merge"
+    }
+  ]
+}

CONTRIBUTING.md

@@ -59,6 +59,7 @@ For README, CLI, and package-listing docs, explain user-visible behavior before
 architecture.
 
 Prefer plain, concrete wording when accurate. For example:
+
 - "draft candidate directives"
 - "non-authoritative suggestion"
 - "saved authoritative state"

README.md

@@ -38,7 +38,6 @@ For local development:
 uv sync --group dev
 ```
 
-
 ## Basic Usage
 
 Draft and validate a candidate directive:
@@ -145,7 +144,6 @@ uv run pre-commit run --all-files
 uv run pytest
 ```
 
-
 ## License
 
 Apache-2.0

scripts/validate_markdown.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="$(cd "${script_dir}/.." && pwd)"
+
+cd "${repo_root}"
+
+npx --yes markdownlint-cli2