docs(agents): tooling + architecture-upkeep rules, with tool tests (#24)

Merged PR #24: tooling + architecture-upkeep rules, tool tests

Co-authored-by: Zwitschi <zwitschi82@gmail.com>

Tools/tests/test_block_height_report.py

@@ -0,0 +1,53 @@
+"""Tests for Geo/tools/block_height_report.py::classify_height.
+
+The Geo tools live outside `Tools/`, so the test adds `Geo/tools` to `sys.path`
+before importing the module by name.
+"""
+
+import os
+import sys
+import unittest
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+sys.path.insert(0, os.path.join(ROOT, "Geo", "tools"))
+
+import block_height_report as bhr  # noqa: E402
+
+
+class ClassifyHeightTest(unittest.TestCase):
+    def test_height_tag_wins(self):
+        height, source = bhr.classify_height({"building": "yes", "height": "18.1"})
+        self.assertEqual(height, 18.1)
+        self.assertEqual(source, "height tag")
+
+    def test_height_tag_beats_levels(self):
+        height, _ = bhr.classify_height(
+            {"building": "yes", "height": "12.5", "building:levels": "4"})
+        self.assertEqual(height, 12.5)
+
+    def test_levels_derive_height(self):
+        height, source = bhr.classify_height(
+            {"building": "yes", "building:levels": "4"}, level_height=3.2)
+        self.assertEqual(height, 12.8)
+        self.assertIn("levels x", source)
+
+    def test_roof_is_not_a_building_volume(self):
+        # building=roof at layer=1 is an elevated canopy, not a two-storey block.
+        height, source = bhr.classify_height({"building": "roof", "layer": "1"})
+        self.assertEqual(height, 0.0)
+        self.assertIn("not a building volume (roof)", source)
+
+    def test_transit_shelter_is_not_a_building_volume(self):
+        height, source = bhr.classify_height(
+            {"building": "yes", "amenity": "shelter", "shelter_type": "public_transport"})
+        self.assertEqual(height, 0.0)
+        self.assertIn("not a building volume (shelter)", source)
+
+    def test_missing_data_falls_back_to_a_flagged_guess(self):
+        height, source = bhr.classify_height({"building": "yes"})
+        self.assertEqual(height, 2 * bhr.LEVEL_HEIGHT)
+        self.assertTrue(source.startswith("GUESS"))
+
+
+if __name__ == "__main__":
+    unittest.main()