From 6656adc2b7c7e7e399d6704fddf68cc7376e9558 Mon Sep 17 00:00:00 2001
From: agentson <agentson@localhost>
Date: Sun, 1 Mar 2026 23:09:20 +0900
Subject: [PATCH] ci/docs: wire docs sync validator into workflows and tighten
 tests

---
 .gitea/workflows/ci.yml          |  3 +++
 .github/workflows/ci.yml         |  3 +++
 scripts/validate_docs_sync.py    | 13 +++++++------
 tests/test_validate_docs_sync.py | 21 +++++++++++++++++++++
 4 files changed, 34 insertions(+), 6 deletions(-)

diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml
index 9ee06db..d992e70 100644
--- a/.gitea/workflows/ci.yml
+++ b/.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/
 
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 40f340d..d2e5f1f 100644
--- a/.github/workflows/ci.yml
+++ b/.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/
 
diff --git a/scripts/validate_docs_sync.py b/scripts/validate_docs_sync.py
index 87cf519..0dc83c2 100644
--- a/scripts/validate_docs_sync.py
+++ b/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 = (
-            REQUIRED_FILES["README.md"]
-            if file_name == "README.md"
-            else REQUIRED_FILES["CLAUDE.md"]
-        )
+        doc_path = REQUIRED_FILES[file_name]
         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)
diff --git a/tests/test_validate_docs_sync.py b/tests/test_validate_docs_sync.py
index 793c795..5c8309f 100644
--- a/tests/test_validate_docs_sync.py
+++ b/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] = []