From 2f65594077a7d165d5348c6302e2d7914b6e88cb Mon Sep 17 00:00:00 2001 From: BruceChen Date: Tue, 14 Apr 2026 11:15:32 +0000 Subject: [PATCH] docs: document theory-aligned pathing workflow --- docs/guide/pathfinding-research.md | 22 ++++++++++++++++++++++ tools/pathing_data/theory-matrix.md | 5 +++++ tools/pathing_theory/renderers.py | 5 +++++ tools/tests/test_pathing_theory_matrix.py | 5 +++++ 4 files changed, 37 insertions(+) diff --git a/docs/guide/pathfinding-research.md b/docs/guide/pathfinding-research.md index ba6c6656..926e7bb0 100644 --- a/docs/guide/pathfinding-research.md +++ b/docs/guide/pathfinding-research.md @@ -277,6 +277,28 @@ The checked-in contract files live here: For unit tests, `PathingContractAssert` reports planner mismatches, replans, route totals, and per-segment tick overruns directly in the xUnit failure. For live runs, `tools/pathing_contract_report.py` reads the `[PathMetric]` lines emitted by MCC and prints the same route-level and segment-level view, so the offline and live harnesses fail for the same reasons. +## Theory-Aligned Regression Workflow + +The first-wave theory authority now comes from `tools/sim_jump_reach.py`, which writes: + +- `tools/pathing_data/theory-matrix.json` +- `tools/pathing_data/theory-matrix.csv` +- `tools/pathing_data/theory-matrix.md` +- `tools/pathing_data/canonical-live-cases.json` + +Regenerate them with: + +```bash +python3 tools/sim_jump_reach.py --write-artifacts tools/pathing_data +``` + +The theory-aligned live suites read the canonical manifest instead of embedding their own pass and reject expectations: + +- `tools/test-parkour.sh` +- `tools/test-pathing-theory-neo-ceiling.sh` + +That split matters. The theory matrix stays broad and machine-readable. The canonical manifest stays small enough to run live, and the shell suites only need to care about case setup, execution, and recording the outcome. + ## Deterministic live route contract For the short-route and long-route `1.21.11-Vanilla` live harnesses, accepted routes must complete with all of the following: diff --git a/tools/pathing_data/theory-matrix.md b/tools/pathing_data/theory-matrix.md index c450e733..9a982e3c 100644 --- a/tools/pathing_data/theory-matrix.md +++ b/tools/pathing_data/theory-matrix.md @@ -1,5 +1,10 @@ # Theory Matrix +## Canonical live coverage + +This file is generated from `tools/sim_jump_reach.py` and is the first-wave authority +for theory-aligned linear, neo, and headhitter live suites. + | family | subfamily | movement_mode | case_id | expected_reachable | margin | | --- | --- | --- | --- | --- | --- | | linear | flat | walk | linear-flat-walk-mm12-gap0-dy0p0 | True | 5.422586344756974 | diff --git a/tools/pathing_theory/renderers.py b/tools/pathing_theory/renderers.py index de3da5bf..6eda90b7 100644 --- a/tools/pathing_theory/renderers.py +++ b/tools/pathing_theory/renderers.py @@ -36,6 +36,11 @@ def write_theory_artifacts( lines = [ "# Theory Matrix", "", + "## Canonical live coverage", + "", + "This file is generated from `tools/sim_jump_reach.py` and is the first-wave authority", + "for theory-aligned linear, neo, and headhitter live suites.", + "", "| family | subfamily | movement_mode | case_id | expected_reachable | margin |", "| --- | --- | --- | --- | --- | --- |", ] diff --git a/tools/tests/test_pathing_theory_matrix.py b/tools/tests/test_pathing_theory_matrix.py index f0a29384..a1892015 100644 --- a/tools/tests/test_pathing_theory_matrix.py +++ b/tools/tests/test_pathing_theory_matrix.py @@ -1,4 +1,5 @@ import unittest +from pathlib import Path from tools.pathing_theory.simulator import build_theory_cases @@ -22,6 +23,10 @@ class PathingTheoryMatrixTests(unittest.TestCase): self.assertTrue(linear_boundary.expected_reachable) self.assertGreater(linear_boundary.margin, 0.0) + def test_theory_markdown_mentions_canonical_live_coverage(self) -> None: + markdown = Path("tools/pathing_data/theory-matrix.md").read_text(encoding="utf-8") + self.assertIn("Canonical live coverage", markdown) + if __name__ == "__main__": unittest.main()