From 1a80c5ac81b3f0ccf7b89650f428ac8dc08dab43 Mon Sep 17 00:00:00 2001
From: Juan Sugg <juanpedrosugg@gmail.com>
Date: Fri, 27 Mar 2026 07:50:19 -0300
Subject: [PATCH] docs: sync architecture references

---
 docs/codebase-architecture.md                 |  2 +-
 docs/compatibility-matrix.md                  |  7 +--
 .../docs/test_architecture_docs.py            | 45 +++++++++++++++++++
 3 files changed, 50 insertions(+), 4 deletions(-)

diff --git a/docs/codebase-architecture.md b/docs/codebase-architecture.md
index 0c616e13..530b71ef 100644
--- a/docs/codebase-architecture.md
+++ b/docs/codebase-architecture.md
@@ -11,7 +11,7 @@ formal artifacts in [`docs/architecture-diagram.md`](architecture-diagram.md),
 These counts are a current working-tree snapshot taken on March 27, 2026.
 
 - Source modules under `ser/`: `228`
-- Test modules under `tests/`: `145`
+- Test modules under `tests/`: `150`
 - Public modules outside `_internal/`: `167`
 - Internal owner/helper modules under `_internal/`: `61`
 - Public modules importing `_internal` directly: `24`
diff --git a/docs/compatibility-matrix.md b/docs/compatibility-matrix.md
index ff2ac28c..56885708 100644
--- a/docs/compatibility-matrix.md
+++ b/docs/compatibility-matrix.md
@@ -1,11 +1,12 @@
 # Compatibility Matrix (Live Snapshot)
 
 Date initialized: 2026-02-19
-Last updated: 2026-02-26
+Last updated: 2026-03-27
 Purpose: Track compatibility coverage across Python versions, dependency extras, and runtime profiles.
 Evidence source:
-1. `ser_refactor_implementation_journal.md` (latest: Iteration 57, ratified default/profile policy + Darwin 3.13 support-scope clarification)
-2. `ser_refactor_status.md`
+1. `.github/workflows/darwin-x86_64-validation.yml`
+2. `.github/workflows/linux-python-3_13-cli-validation.yml`
+3. `README.md`
 
 ## Matrix
 
diff --git a/tests/suites/integration/docs/test_architecture_docs.py b/tests/suites/integration/docs/test_architecture_docs.py
index 4c998b8f..07cb7664 100644
--- a/tests/suites/integration/docs/test_architecture_docs.py
+++ b/tests/suites/integration/docs/test_architecture_docs.py
@@ -13,6 +13,15 @@
     r"https://github\.com/jsugg/ser/(?:blob|tree)/main/(docs/[A-Za-z0-9_./-]+)"
 )
 _ARCHITECTURE_RELATIVE_LINK_PATTERN = re.compile(r"\(([^)]+)\)")
+_ARCHITECTURE_COUNT_PATTERN = re.compile(
+    r"- (?P<label>Source modules under `ser/`|Test modules under `tests/`|"
+    r"Public modules outside `_internal/`|Internal owner/helper modules under `_internal/`): "
+    r"`(?P<count>\d+)`"
+)
+_REMOVED_TRACKER_REFERENCES = (
+    "ser_refactor_implementation_journal.md",
+    "ser_refactor_status.md",
+)
 
 
 def _repo_root() -> Path:
@@ -20,6 +29,22 @@ def _repo_root() -> Path:
     return Path(__file__).resolve().parents[4]
 
 
+def _expected_codebase_counts(root: Path) -> dict[str, int]:
+    """Builds the current architecture snapshot counts from the working tree."""
+    source_files = list((root / "ser").rglob("*.py"))
+    test_files = list((root / "tests").rglob("*.py"))
+    return {
+        "Source modules under `ser/`": len(source_files),
+        "Test modules under `tests/`": len(test_files),
+        "Public modules outside `_internal/`": sum(
+            1 for path in source_files if "_internal" not in path.parts
+        ),
+        "Internal owner/helper modules under `_internal/`": sum(
+            1 for path in source_files if "_internal" in path.parts
+        ),
+    }
+
+
 def test_readme_architecture_links_resolve_to_existing_docs() -> None:
     """README architecture links should point at docs artifacts that exist in-tree."""
     root = _repo_root()
@@ -43,3 +68,23 @@ def test_architecture_index_links_resolve_to_existing_docs() -> None:
 
     assert root / "docs" / "adr" / "README.md" in resolved_targets
     assert all(target.is_file() for target in resolved_targets)
+
+
+def test_codebase_architecture_snapshot_counts_match_current_tree() -> None:
+    """Architecture snapshot counts should match the current repository tree."""
+    root = _repo_root()
+    architecture_text = (root / "docs" / "codebase-architecture.md").read_text(encoding="utf-8")
+    reported_counts = {
+        match.group("label"): int(match.group("count"))
+        for match in _ARCHITECTURE_COUNT_PATTERN.finditer(architecture_text)
+    }
+
+    assert reported_counts == _expected_codebase_counts(root)
+
+
+def test_compatibility_matrix_does_not_reference_removed_tracker_docs() -> None:
+    """Compatibility matrix should not point contributors at removed tracker files."""
+    root = _repo_root()
+    compatibility_text = (root / "docs" / "compatibility-matrix.md").read_text(encoding="utf-8")
+
+    assert all(reference not in compatibility_text for reference in _REMOVED_TRACKER_REFERENCES)