Add fail-fast local parity ladder and staged CI diagnostics

Author: iahncajigas

.github/workflows/matlab-parity-gate.yml

@@ -57,10 +57,27 @@ jobs:
           python3 python/tools/generate_method_parity_matrix.py
           python3 python/tools/generate_implemented_method_coverage.py
 
-      - name: Run MATLAB/Python similarity gate
+      - name: Parity Stage A (core + timeout-front)
+        run: |
+          python/tools/run_parity_ladder.sh core_smoke timeout_front
+
+      - name: Parity Stage B (graphics-mid + heavy-tail)
+        run: |
+          python/tools/run_parity_ladder.sh graphics_mid heavy_tail
+
+      - name: Parity Stage C (full-suite gate report)
         run: |
           python3 python/tools/verify_python_vs_matlab_similarity.py --enforce-gate
 
+      - name: Summarize full-suite parity report
+        if: ${{ always() && !cancelled() }}
+        run: |
+          if [ -f python/reports/python_vs_matlab_similarity_report.json ]; then
+            python3 python/tools/summarize_parity_report.py python/reports/python_vs_matlab_similarity_report.json --json > python/reports/python_vs_matlab_similarity_summary.json
+          else
+            echo "Parity report missing; skipping summary."
+          fi
+
       - name: Freeze similarity baseline
         if: ${{ always() && !cancelled() }}
         run: |
@@ -70,6 +87,38 @@ jobs:
             echo "Similarity report missing; skipping baseline freeze."
           fi
 
+      - name: Collect MATLAB crash diagnostics
+        if: ${{ failure() && !cancelled() }}
+        continue-on-error: true
+        run: |
+          set -euo pipefail
+          OUT_DIR="python/reports/matlab_crash_diagnostics"
+          mkdir -p "$OUT_DIR/diagnostic_reports" "$OUT_DIR/mathworks_crash_reports"
+
+          # Collect macOS crash/ips reports (latest 20) when MATLAB crashes.
+          DIAG_DIR="$HOME/Library/Logs/DiagnosticReports"
+          if [ -d "$DIAG_DIR" ]; then
+            find "$DIAG_DIR" -maxdepth 1 -type f \( -name '*MATLAB*.crash' -o -name '*matlab*.crash' -o -name '*MATLAB*.ips' -o -name '*matlab*.ips' \) -print \
+              | sort \
+              | tail -n 20 \
+              | while IFS= read -r f; do cp -f "$f" "$OUT_DIR/diagnostic_reports/" || true; done
+          fi
+
+          # Collect MathWorks CrashReporter payload files (latest 50).
+          MW_APP_SUPPORT="$HOME/Library/Application Support/MathWorks"
+          if [ -d "$MW_APP_SUPPORT" ]; then
+            find "$MW_APP_SUPPORT" -type d -name crash_reports -print \
+              | while IFS= read -r crash_dir; do
+                  find "$crash_dir" -type f -print || true
+                done \
+              | sort \
+              | tail -n 50 \
+              | while IFS= read -r f; do cp -f "$f" "$OUT_DIR/mathworks_crash_reports/" || true; done
+          fi
+
+          # Keep staged block reports if present for triage context.
+          ls -1 python/reports/parity_block*.json > "$OUT_DIR/parity_block_report_manifest.txt" 2>/dev/null || true
+
       - name: Upload parity reports
         if: ${{ always() && !cancelled() }}
         continue-on-error: true
@@ -80,3 +129,6 @@ jobs:
           path: |
             python/reports/python_vs_matlab_similarity_report.json
             python/reports/python_vs_matlab_similarity_baseline.json
+            python/reports/python_vs_matlab_similarity_summary.json
+            python/reports/parity_block*.json
+            python/reports/matlab_crash_diagnostics/**

.github/workflows/python-ci.yml

@@ -41,6 +41,10 @@ jobs:
           python python/tools/generate_method_parity_matrix.py
           python python/tools/generate_implemented_method_coverage.py
 
+      - name: Verify help docs coverage
+        run: |
+          python python/tools/verify_help_docs_coverage.py
+
       - name: Validate notebooks
         run: |
           python python/tools/verify_examples_notebooks.py

.gitignore

@@ -5,3 +5,4 @@ __pycache__/
 python/plots/
 
 python/docs/_build/
+python/reports/parity_block*.json

python/README.md

@@ -52,6 +52,67 @@ python3 python/tools/verify_offline_standalone.py
 cd python && python3 -m pytest
 ```
 
+### Local parity block debugging
+
+```bash
+python3 python/tools/debug_parity_blocks.py \
+  --set-actions-runner-svc \
+  --matlab-extra-args "-maca64 -nodisplay -noFigureWindows"
+```
+
+Single wrapper command (fail-fast ladder):
+
+```bash
+python/tools/run_parity_ladder.sh
+```
+
+Notes:
+
+- Runs blocks in order: `core_smoke -> timeout_front -> graphics_mid -> heavy_tail -> full_suite`.
+- Exits immediately if a block regresses (`python_ok`, `matlab_ok`, scalar overlap, parity contract, or regression gate).
+- Includes runtime regression guard using machine baseline block times with multiplier `NSTAT_PARITY_RUNTIME_MULTIPLIER` (default `2.5`).
+- Set `NSTAT_PARITY_RUNTIME_MULTIPLIER=0` to disable runtime regression checks.
+- Pass specific block names as args to run subset ladders, e.g.:
+  `python/tools/run_parity_ladder.sh core_smoke timeout_front`.
+
+Use targeted blocks to debug delays locally before running remote CI:
+
+```bash
+# 1) Fast API/parity smoke
+python3 python/tools/debug_parity_blocks.py --blocks core_smoke \
+  --set-actions-runner-svc --matlab-extra-args "-maca64 -nodisplay -noFigureWindows"
+
+# 2) Former timeout-prone front topics
+python3 python/tools/debug_parity_blocks.py --blocks timeout_front \
+  --set-actions-runner-svc --matlab-extra-args "-maca64 -nodisplay -noFigureWindows"
+
+# 3) Graphics-sensitive middle topics
+python3 python/tools/debug_parity_blocks.py --blocks graphics_mid \
+  --set-actions-runner-svc --matlab-extra-args "-maca64 -nodisplay -noFigureWindows"
+
+# 4) Heavy tail topics
+python3 python/tools/debug_parity_blocks.py --blocks heavy_tail \
+  --set-actions-runner-svc --matlab-extra-args "-maca64 -nodisplay -noFigureWindows"
+
+# 5) Full gate-equivalent suite
+python3 python/tools/debug_parity_blocks.py --blocks full_suite \
+  --set-actions-runner-svc --matlab-extra-args "-maca64 -nodisplay -noFigureWindows"
+```
+
+Summarize a parity report quickly:
+
+```bash
+python3 python/tools/summarize_parity_report.py python/reports/parity_block_full_suite.json
+```
+
+Recent local baseline on this machine (MATLAB R2025b, no figure windows):
+
+- `core_smoke`: ~47s
+- `timeout_front`: ~122s
+- `graphics_mid`: ~291s
+- `heavy_tail`: ~385s
+- `full_suite` (25 topics): ~826s
+
 ## CI
 
 - `.github/workflows/python-ci.yml` runs docs, notebook verification, offline standalone checks, and `pytest`.