docs: record Pygments 2.20 exclusion ADR

docs/adr/0001-exclude-pygments-2-20.md

@@ -0,0 +1,53 @@
+# ADR 0001: Exclude Pygments 2.20 from Docs Dependencies
+
+## Status
+
+Accepted
+
+## Date
+
+2026-05-12
+
+## Context
+
+GraphForge builds its documentation with MkDocs Material and several `pymdownx` extensions. The
+docs dependency group intentionally constrained Pygments to `<2.20` because Pygments 2.20.0 changes
+highlighting behavior in a way that breaks `pymdownx` handling when `title=None` is passed through
+the highlighting path.
+
+Dependabot opened PR #546 to widen the docs dependency from `pygments>=2.15,<2.20` to
+`pygments>=2.15,<2.21`. The checked-in lockfile still resolved Pygments 2.19.2, so CI stayed green
+without actually testing Pygments 2.20.0 in the docs environment.
+
+## Decision
+
+Keep excluding Pygments 2.20.x from GraphForge's docs dependency group until the upstream
+compatibility issue with `pymdownx` is fixed and the docs build has been validated against the newer
+Pygments release.
+
+Do not merge automated dependency updates that relax the Pygments upper bound to include 2.20.x
+while the compatibility note remains in `pyproject.toml`.
+
+## Consequences
+
+- Dependabot PRs that only permit Pygments 2.20.x should be closed rather than merged.
+- The docs environment remains on Pygments 2.19.x through the existing constraint and lockfile.
+- The Pygments 2.20.0 Lua lexer ReDoS fix is not relevant to GraphForge's runtime, because Pygments
+  is only used for documentation tooling.
+- The decision can be revisited once `pymdownx` and the MkDocs docs build work cleanly with Pygments
+  2.20.x or newer.
+
+## Validation Before Revisiting
+
+Before relaxing the upper bound:
+
+1. Update the docs dependency group and lockfile so the docs environment resolves the candidate
+   Pygments version.
+2. Confirm the active docs environment imports that candidate version.
+3. Run `uv run --group docs mkdocs build --strict`.
+4. Remove or update the compatibility note in `pyproject.toml`.
+
+## Related Work
+
+- Issue #547: docs: record Pygments 2.20 exclusion decision
+- PR #546: chore(deps-dev): update pygments requirement from `<2.20,>=2.15` to `>=2.15,<2.21`

mkdocs.yml

@@ -174,6 +174,7 @@ nav:
     - Testing Strategy: development/testing.md
     - Release Process: development/release-process.md
     - Release Strategy: development/release-strategy.md
+    - ADR 0001 - Exclude Pygments 2.20: adr/0001-exclude-pygments-2-20.md
   - Research:
     - LLM-Powered Workflows: research/llm-workflows.md
     - AI Agent Grounding: research/agent-grounding.md