Address review feedback: consolidate CMake commands, robustify generators

- Consolidate case_constraints.md and physics_constraints.md into a
  single CMake custom command to avoid parallel build races
- Fall back to sorted stage names instead of "all" for unknown stages
- Append extra categories not in CATEGORY_ORDER instead of dropping them
- Print error details for failing example validations in CI

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: sbryngelson

.github/workflows/lint-toolchain.yml

@@ -49,6 +49,7 @@ jobs:
             passed=$((passed + 1))
           else
             echo "FAIL: $case"
+            ./mfc.sh validate "$case" 2>&1 || true
             failed=$((failed + 1))
           fi
         done

CMakeLists.txt

@@ -660,27 +660,19 @@ if (MFC_DOCUMENTATION)
         VERBATIM
     )
 
-    # Generate case_constraints.md from case_validator.py and examples/
+    # Generate case_constraints.md and physics_constraints.md together.
+    # Both are produced by gen_constraints.sh, so a single command avoids races.
     add_custom_command(
         OUTPUT  "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/case_constraints.md"
+                "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/physics_constraints.md"
         DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/toolchain/mfc/gen_case_constraints_docs.py"
+                "${CMAKE_CURRENT_SOURCE_DIR}/toolchain/mfc/gen_physics_docs.py"
                 "${CMAKE_CURRENT_SOURCE_DIR}/toolchain/mfc/case_validator.py"
                 "${CMAKE_CURRENT_SOURCE_DIR}/toolchain/mfc/params/definitions.py"
                 "${examples_DOCs}"
         COMMAND "bash" "${CMAKE_CURRENT_SOURCE_DIR}/docs/gen_constraints.sh"
                        "${CMAKE_CURRENT_SOURCE_DIR}"
-        COMMENT "Generating case_constraints.md"
-        VERBATIM
-    )
-
-    # Generate physics_constraints.md from PHYSICS_DOCS + AST-extracted rules
-    add_custom_command(
-        OUTPUT  "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/physics_constraints.md"
-        DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/toolchain/mfc/gen_physics_docs.py"
-                "${CMAKE_CURRENT_SOURCE_DIR}/toolchain/mfc/case_validator.py"
-        COMMAND "bash" "${CMAKE_CURRENT_SOURCE_DIR}/docs/gen_constraints.sh"
-                       "${CMAKE_CURRENT_SOURCE_DIR}"
-        COMMENT "Generating physics_constraints.md"
+        COMMENT "Generating case_constraints.md and physics_constraints.md"
         VERBATIM
     )
 

toolchain/mfc/gen_physics_docs.py

@@ -110,7 +110,11 @@ def _wrap_code(match: re.Match) -> str:
 def _stages_str(stages: Set[str]) -> str:
     order = ["common", "pre_process", "simulation", "post_process"]
     ordered = [s for s in order if s in stages]
-    return ", ".join(ordered) if ordered else "all"
+    if ordered:
+        return ", ".join(ordered)
+    if stages:
+        return ", ".join(sorted(stages))
+    return "all"
 
 
 def _severity_badge(rules: List[Rule]) -> str:
@@ -193,7 +197,8 @@ def render(rules: List[Rule]) -> str:
         "@ref case_constraints \"Case Creator Guide\".\n"
     )
 
-    for category in CATEGORY_ORDER:
+    extra_categories = [c for c in by_category if c not in CATEGORY_ORDER]
+    for category in CATEGORY_ORDER + sorted(extra_categories):
         methods = by_category.get(category)
         if not methods:
             continue