ci/docs: wire docs sync validator into workflows and tighten tests

.gitea/workflows/ci.yml

@@ -47,6 +47,9 @@ jobs:
       - name: Validate Ouroboros docs
         run: python3 scripts/validate_ouroboros_docs.py
 
+      - name: Validate docs sync
+        run: python3 scripts/validate_docs_sync.py
+
       - name: Lint
         run: ruff check src/ tests/
 

.github/workflows/ci.yml

@@ -44,6 +44,9 @@ jobs:
       - name: Validate Ouroboros docs
         run: python3 scripts/validate_ouroboros_docs.py
 
+      - name: Validate docs sync
+        run: python3 scripts/validate_docs_sync.py
+
       - name: Lint
         run: ruff check src/ tests/
 

scripts/validate_docs_sync.py

@@ -54,11 +54,7 @@ def validate_summary_docs_reference_core_docs(errors: list[str]) -> None:
         "CLAUDE.md": ("docs/workflow.md", "docs/commands.md"),
     }
     for file_name, links in required_links.items():
-        doc_path = (
+        doc_path = REQUIRED_FILES[file_name]
-            REQUIRED_FILES["README.md"]
-            if file_name == "README.md"
-            else REQUIRED_FILES["CLAUDE.md"]
-        )
         text = _read(doc_path)
         for link in links:
             if link not in text:
@@ -110,8 +106,13 @@ def main() -> int:
     claude_text = _read(REQUIRED_FILES["CLAUDE.md"])
     validate_links_resolve(REQUIRED_FILES["README.md"], readme_text, errors)
     validate_links_resolve(REQUIRED_FILES["CLAUDE.md"], claude_text, errors)
-    validate_links_resolve(REQUIRED_FILES["commands"], _read(REQUIRED_FILES["commands"]), errors)
+    validate_links_resolve(
+        REQUIRED_FILES["commands"], _read(REQUIRED_FILES["commands"]), errors
+    )
     validate_links_resolve(REQUIRED_FILES["testing"], _read(REQUIRED_FILES["testing"]), errors)
+    validate_links_resolve(
+        REQUIRED_FILES["workflow"], _read(REQUIRED_FILES["workflow"]), errors
+    )
 
     validate_summary_docs_reference_core_docs(errors)
     validate_commands_endpoint_duplicates(errors)

tests/test_validate_docs_sync.py

@@ -69,6 +69,27 @@ def test_validate_summary_docs_reference_core_docs(monkeypatch) -> None:
     assert errors == []
 
 
+def test_validate_summary_docs_reference_core_docs_reports_missing_links(
+    monkeypatch,
+) -> None:
+    module = _load_module()
+    errors: list[str] = []
+    fake_docs = {
+        str(module.REQUIRED_FILES["README.md"]): "docs/workflow.md",
+        str(module.REQUIRED_FILES["CLAUDE.md"]): "docs/workflow.md",
+    }
+
+    def fake_read(path: Path) -> str:
+        return fake_docs[str(path)]
+
+    monkeypatch.setattr(module, "_read", fake_read)
+    module.validate_summary_docs_reference_core_docs(errors)
+
+    assert any("README.md" in err and "docs/commands.md" in err for err in errors)
+    assert any("README.md" in err and "docs/testing.md" in err for err in errors)
+    assert any("CLAUDE.md" in err and "docs/commands.md" in err for err in errors)
+
+
 def test_validate_commands_endpoint_duplicates_reports_duplicates(monkeypatch) -> None:
     module = _load_module()
     errors: list[str] = []