Add 4 staleness-prevention lint checks and complete PHYSICS_DOCS coverage

New lint checks in lint_docs.py:
- check_physics_docs_coverage: flags check methods missing PHYSICS_DOCS entries
- check_identifier_refs: validates Python identifiers in contributing.md
  (PHYSICS_DOCS, CONSTRAINTS, DEPENDENCIES, REGISTRY) still exist in source
- check_cli_refs: validates ./mfc.sh commands in running.md match CLI schema
- Expanded DOCS list to cover all hand-written docs for file path validation

Added PHYSICS_DOCS entries for 16 previously undocumented check methods
and added 11 mechanical/structural methods to the skip set.

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

Author: sbryngelson

toolchain/mfc/case_validator.py

@@ -242,6 +242,145 @@
             "Global dimensions must be even. Incompatible with cylindrical coordinates."
         ),
     },
+    "check_adaptive_time_stepping": {
+        "title": "Adaptive Time Stepping",
+        "category": "Numerical Schemes",
+        "explanation": (
+            "Requires RK3 time stepper. Only compatible with polytropic or "
+            "Lagrangian bubble models. Incompatible with QBMM."
+        ),
+    },
+    "check_adv_n": {
+        "title": "Bubble Advection",
+        "category": "Bubble Physics",
+        "explanation": (
+            "Bubble advection (adv_n) requires single-fluid Euler bubble solver. "
+            "Incompatible with QBMM."
+        ),
+    },
+    "check_body_forces": {
+        "title": "Body Forces",
+        "category": "Feature Compatibility",
+        "explanation": (
+            "Body force parameters (k, w, p, g components) must be fully specified "
+            "for each active dimension."
+        ),
+    },
+    "check_continuum_damage": {
+        "title": "Continuum Damage Modeling",
+        "category": "Feature Compatibility",
+        "explanation": (
+            "Requires model_eqns = 2 and specification of tau_star, "
+            "cont_damage_s, and alpha_bar parameters."
+        ),
+    },
+    "check_grcbc": {
+        "title": "Generalized Relaxation CBC",
+        "category": "Boundary Conditions",
+        "explanation": (
+            "GRCBC requires specific BC values: -7 (inflow) or -8 (outflow). "
+            "Inflow requires velocity and pressure specification."
+        ),
+    },
+    "check_hyperelasticity": {
+        "title": "Hyperelasticity",
+        "category": "Feature Compatibility",
+        "explanation": (
+            "Pre-stress requires hyperelasticity. Not supported with "
+            "model_eqns = 1. Requires HLL Riemann solver."
+        ),
+    },
+    "check_ibm": {
+        "title": "Immersed Boundary Method",
+        "category": "Domain and Geometry",
+        "explanation": (
+            "Requires 2D or 3D (n > 0). Number of immersed boundaries "
+            "must be between 1 and 10."
+        ),
+    },
+    "check_igr_simulation": {
+        "title": "IGR Simulation Constraints",
+        "category": "Numerical Schemes",
+        "explanation": (
+            "Iterative ghost-cell remapping has numerous incompatibilities "
+            "including polytropic, bubbles, surface tension, MHD, and elasticity."
+        ),
+    },
+    "check_mhd_simulation": {
+        "title": "MHD Simulation Constraints",
+        "category": "Feature Compatibility",
+        "explanation": (
+            "MHD requires HLL or HLLD Riemann solver. HLLD unavailable for "
+            "relativistic MHD. Hyperbolic divergence cleaning not supported in 1D."
+        ),
+    },
+    "check_model_eqns_simulation": {
+        "title": "Six-Equation Model Constraints",
+        "category": "Model Equations",
+        "explanation": (
+            "The six-equation model (model_eqns = 3) requires arithmetic "
+            "averaging and specific wave speed calculation methods."
+        ),
+        "references": ["Saurel09"],
+    },
+    "check_muscl_simulation": {
+        "title": "MUSCL Simulation Constraints",
+        "category": "Numerical Schemes",
+        "explanation": (
+            "Second-order MUSCL reconstruction requires a flux limiter "
+            "selection (muscl_lim in 1-5)."
+        ),
+    },
+    "check_partial_density": {
+        "title": "Partial Density Output",
+        "category": "Post-Processing",
+        "explanation": (
+            "Multi-phase partial density output is incompatible with "
+            "model_eqns = 1 (single-fluid gamma-law)."
+        ),
+    },
+    "check_qbmm_and_polydisperse": {
+        "title": "QBMM and Polydisperse Bubbles",
+        "category": "Bubble Physics",
+        "explanation": (
+            "Both require Euler bubble solver. Polydisperse requires "
+            "poly_sigma > 0. QBMM requires nnode = 4."
+        ),
+        "references": ["Bryngelson21"],
+    },
+    "check_riemann_solver": {
+        "title": "Riemann Solver Selection",
+        "category": "Numerical Schemes",
+        "explanation": (
+            "Five solvers available with different model compatibility. "
+            "Six-equation model requires HLLC. Exact solver does not support "
+            "wave_speeds. Low-Mach correction 2 requires HLLC."
+        ),
+    },
+    "check_schlieren": {
+        "title": "Schlieren Visualization",
+        "category": "Post-Processing",
+        "explanation": (
+            "Requires finite difference order and at least 2D (n > 0). "
+            "Each schlieren_alpha coefficient must be positive."
+        ),
+    },
+    "check_volume_fraction": {
+        "title": "Volume Fraction Output",
+        "category": "Post-Processing",
+        "explanation": (
+            "Volume fraction output is incompatible with model_eqns = 1 "
+            "(single-fluid gamma-law). Requires multi-component model."
+        ),
+    },
+    "check_weno_simulation": {
+        "title": "WENO Simulation Constraints",
+        "category": "Numerical Schemes",
+        "explanation": (
+            "Five WENO variants with mutual exclusivity constraints. "
+            "weno_avg incompatible with model_eqns = 1."
+        ),
+    },
 }
 
 

toolchain/mfc/lint_docs.py

@@ -4,13 +4,19 @@
 import sys
 from pathlib import Path
 
-# Docs to scan for file path references
+# Docs to scan for file path references (all hand-written docs with code refs)
 DOCS = [
     "docs/documentation/contributing.md",
     "docs/documentation/gpuParallelization.md",
     "docs/documentation/running.md",
     "docs/documentation/case.md",
     "docs/documentation/equations.md",
+    "docs/documentation/testing.md",
+    "docs/documentation/getting-started.md",
+    "docs/documentation/docker.md",
+    "docs/documentation/troubleshooting.md",
+    "docs/documentation/visualization.md",
+    "docs/documentation/expectedPerformance.md",
     ".github/copilot-instructions.md",
 ]
 
@@ -386,6 +392,143 @@ def check_page_refs(repo_root: Path) -> list[str]:
     return errors
 
 
+def check_physics_docs_coverage(repo_root: Path) -> list[str]:
+    """Check that all check methods with enforcement calls have PHYSICS_DOCS entries."""
+    toolchain_dir = str(repo_root / "toolchain")
+    if toolchain_dir not in sys.path:
+        sys.path.insert(0, toolchain_dir)
+    try:
+        from mfc.case_validator import PHYSICS_DOCS  # pylint: disable=import-outside-toplevel
+        from mfc.params.ast_analyzer import analyze_case_validator  # pylint: disable=import-outside-toplevel
+    except ImportError:
+        return []
+
+    # Methods that are purely structural/mechanical and don't need physics docs
+    skip = {
+        "check_parameter_types",     # type validation, not physics
+        "check_output_format",       # output format selection
+        "check_restart",             # restart file logistics
+        "check_parallel_io_pre_process",  # parallel I/O settings
+        "check_misc_pre_process",    # miscellaneous pre-process flags
+        "check_bc_patches",          # boundary patch geometry
+        "check_grid_stretching",     # grid stretching parameters
+        "check_qbmm_pre_process",    # QBMM pre-process settings
+        "check_probe_integral_output",  # probe/integral output settings
+        "check_finite_difference",   # fd_order value validation
+        "check_flux_limiter",        # output dimension requirements
+        "check_liutex_post",         # output dimension requirements
+        "check_momentum_post",       # output dimension requirements
+        "check_velocity_post",       # output dimension requirements
+        "check_surface_tension_post",  # output feature dependency
+        "check_no_flow_variables",   # output variable selection
+        "check_partial_domain",      # output format settings
+        "check_perturb_density",     # parameter pairing validation
+        "check_qm",                  # output dimension requirements
+        "check_chemistry",           # runtime Cantera validation only
+    }
+
+    validator_path = repo_root / "toolchain" / "mfc" / "case_validator.py"
+    analysis = analyze_case_validator(validator_path)
+    rules = analysis["rules"]
+
+    # Find methods that have at least one prohibit/warn call
+    methods_with_rules = {r.method for r in rules}
+
+    errors = []
+    for method in sorted(methods_with_rules):
+        if method in PHYSICS_DOCS:
+            continue
+        if method in skip:
+            continue
+        errors.append(
+            f"  {method} has validation rules but no PHYSICS_DOCS entry."
+            " Fix: add entry to PHYSICS_DOCS in case_validator.py"
+            " or add to skip set in lint_docs.py"
+        )
+
+    return errors
+
+
+# Important Python identifiers in contributing.md mapped to files where they must exist.
+# If an identifier is renamed or removed, this check catches the stale doc reference.
+_CONTRIBUTING_IDENTIFIERS = {
+    "PHYSICS_DOCS": "toolchain/mfc/case_validator.py",
+    "CONSTRAINTS": "toolchain/mfc/params/definitions.py",
+    "DEPENDENCIES": "toolchain/mfc/params/definitions.py",
+    "REGISTRY": "toolchain/mfc/params/__init__.py",
+}
+
+
+def check_identifier_refs(repo_root: Path) -> list[str]:
+    """Check that important identifiers referenced in contributing.md still exist."""
+    doc_path = repo_root / "docs" / "documentation" / "contributing.md"
+    if not doc_path.exists():
+        return []
+
+    text = _strip_code_blocks(doc_path.read_text(encoding="utf-8"))
+    errors = []
+
+    for identifier, source_file in _CONTRIBUTING_IDENTIFIERS.items():
+        # Check identifier is actually referenced in the doc
+        if f"`{identifier}" not in text:
+            continue
+        source_path = repo_root / source_file
+        if not source_path.exists():
+            errors.append(
+                f"  contributing.md references `{identifier}` in {source_file}"
+                f" but {source_file} does not exist"
+            )
+            continue
+        source_text = source_path.read_text(encoding="utf-8")
+        if identifier not in source_text:
+            errors.append(
+                f"  contributing.md references `{identifier}` but it was not"
+                f" found in {source_file}. Fix: update the docs or the identifier"
+            )
+
+    return errors
+
+
+# Match ./mfc.sh <command> patterns (the subcommand name)
+_CLI_CMD_RE = re.compile(r"\./mfc\.sh\s+([a-z][a-z_-]*)")
+
+
+def check_cli_refs(repo_root: Path) -> list[str]:
+    """Check that ./mfc.sh commands referenced in docs exist in the CLI schema."""
+    toolchain_dir = str(repo_root / "toolchain")
+    if toolchain_dir not in sys.path:
+        sys.path.insert(0, toolchain_dir)
+    try:
+        from mfc.cli.commands import MFC_CLI_SCHEMA  # pylint: disable=import-outside-toplevel
+    except ImportError:
+        return []
+
+    valid_commands = {cmd.name for cmd in MFC_CLI_SCHEMA.commands}
+    # Also accept "init" (shell function) and "load" (shell function)
+    valid_commands.update({"init", "load"})
+
+    errors = []
+    doc_path = repo_root / "docs" / "documentation" / "running.md"
+    if not doc_path.exists():
+        return []
+
+    text = _strip_code_blocks(doc_path.read_text(encoding="utf-8"))
+    seen = set()
+    for match in _CLI_CMD_RE.finditer(text):
+        cmd = match.group(1)
+        if cmd in seen or cmd in valid_commands:
+            seen.add(cmd)
+            continue
+        seen.add(cmd)
+        errors.append(
+            f"  running.md references './mfc.sh {cmd}' but '{cmd}'"
+            " is not a known CLI command."
+            " Fix: update the command name or remove the reference"
+        )
+
+    return errors
+
+
 def main():
     repo_root = Path(__file__).resolve().parents[2]
 
@@ -397,6 +540,9 @@ def main():
     all_errors.extend(check_math_syntax(repo_root))
     all_errors.extend(check_doxygen_percent(repo_root))
     all_errors.extend(check_section_anchors(repo_root))
+    all_errors.extend(check_physics_docs_coverage(repo_root))
+    all_errors.extend(check_identifier_refs(repo_root))
+    all_errors.extend(check_cli_refs(repo_root))
 
     if all_errors:
         print("Doc reference check failed:")