fix: enforce deterministic path ordering

Author: xxg1413

_includes/catalog-grid.html

@@ -1,5 +1,6 @@
+{% assign ordered_paths = site.data.resources.catalog.paths | sort: "order" %}
 <nav class="path-grid" aria-label="{% if page.lang == 'zh-CN' %}学习路径{% else %}Learning paths{% endif %}">
-  {% for path in site.data.resources.catalog.paths %}
+  {% for path in ordered_paths %}
     {% assign path_resources = include.resources | where: "path", path.id %}
     <a class="path-card" href="#{{ path.id }}">
       <span class="path-number">0{{ path.order }}</span>
@@ -16,7 +17,7 @@
   {% endfor %}
 </nav>
 
-{% for path in site.data.resources.catalog.paths %}
+{% for path in ordered_paths %}
   {% assign path_resources = include.resources | where: "path", path.id %}
   <section class="path-section" id="{{ path.id }}" aria-labelledby="{{ path.id }}-title">
     <header class="section-heading">

tests/test_catalog.py

@@ -62,6 +62,17 @@ def test_resource_ids_and_urls_reject_unsafe_forms(valid_catalog: dict) -> None:
     assert {"invalid-id", "url-credentials"} <= codes
 
 
+def test_path_orders_must_be_consecutive(valid_catalog: dict) -> None:
+    data = deepcopy(valid_catalog)
+    data["catalog"]["paths"][-1]["order"] = 5
+
+    codes = {
+        issue.code for issue in validate_catalog(data, today=date(2026, 8, 31))
+    }
+
+    assert "order-parity" in codes
+
+
 @pytest.mark.parametrize(
     ("url", "expected"),
     [

tools/catalog.py

@@ -263,6 +263,19 @@ def validate_catalog(
             )
         )
 
+    expected_path_orders = set(range(1, len(EXPECTED_PATH_IDS) + 1))
+    if path_orders != expected_path_orders:
+        missing = sorted(expected_path_orders - path_orders)
+        extra = sorted(path_orders - expected_path_orders)
+        issues.append(
+            ValidationIssue(
+                "order-parity",
+                "$.catalog.paths",
+                f"expected consecutive path orders 1-{len(EXPECTED_PATH_IDS)}; "
+                f"missing={missing}, extra={extra}",
+            )
+        )
+
     resources = data.get("resources")
     if not isinstance(resources, list):
         issues.append(