Constrain external docs migration districts

Author: 8Dionysus

scripts/docs_districts/validate_docs_migration_map.py

@@ -9,8 +9,10 @@
     from scripts.docs_districts.docs_thematic_common import REPO_ROOT, load_classifier, validate_classifier_shape
 
 
-def main() -> int:
-    classifier = load_classifier(REPO_ROOT)
+EXTERNAL_OWNER_ROUTE_DISTRICT = "traces"
+
+
+def validate_migration_map(classifier: dict, repo_root: Path = REPO_ROOT) -> list[str]:
     errors = validate_classifier_shape(classifier)
     districts = classifier.get("districts", {})
 
@@ -36,16 +38,28 @@ def main() -> int:
         if target_dir != district_path:
             if not external_owner_route:
                 errors.append(f"pattern migration target_dir {target_dir} does not match district {district}")
-            elif external_owner_route != target_dir:
-                errors.append(
-                    f"pattern migration external_owner_route {external_owner_route} must match target_dir {target_dir}"
-                )
-            elif not (REPO_ROOT / external_owner_route).is_dir():
-                errors.append(f"pattern migration external owner route does not exist: {external_owner_route}")
+            else:
+                if district != EXTERNAL_OWNER_ROUTE_DISTRICT:
+                    errors.append(
+                        f"pattern migration external owner route {source_glob} must use district "
+                        f"{EXTERNAL_OWNER_ROUTE_DISTRICT}, got {district}"
+                    )
+                if external_owner_route != target_dir:
+                    errors.append(
+                        f"pattern migration external_owner_route {external_owner_route} must match target_dir {target_dir}"
+                    )
+                elif not (repo_root / external_owner_route).is_dir():
+                    errors.append(f"pattern migration external owner route does not exist: {external_owner_route}")
 
         if source_glob.startswith("docs/") and "README" in source_glob.upper():
             errors.append(f"pattern migration must not catch README surfaces: {source_glob}")
 
+    return errors
+
+
+def main() -> int:
+    classifier = load_classifier(REPO_ROOT)
+    errors = validate_migration_map(classifier, REPO_ROOT)
     if errors:
         raise SystemExit("docs migration map validation failed:\n- " + "\n- ".join(errors))
     print("docs migration map validated")

tests/test_docs_migration_map.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
+import copy, tempfile
 import sys, unittest
 from pathlib import Path
 ROOT=Path(__file__).resolve().parents[1]; sys.path.insert(0,str(ROOT/'scripts'))
-from scripts.docs_districts.docs_thematic_common import load_classifier
+from scripts.docs_districts.docs_thematic_common import build_plan, load_classifier
+from scripts.docs_districts.validate_docs_migration_map import validate_migration_map
 class DocsMigrationMapTests(unittest.TestCase):
     def setUp(self): self.c=load_classifier(ROOT)
     def test_all_exact_migrations_target_known_districts(self):
@@ -15,6 +17,24 @@ def test_external_pattern_routes_are_explicit(self):
                 self.assertIn('external_owner_route', item)
                 self.assertEqual(item['external_owner_route'], item['target_dir'])
                 self.assertTrue((ROOT/item['external_owner_route']).is_dir(), item['external_owner_route'])
+    def test_external_pattern_routes_are_bound_to_traces_district(self):
+        classifier=copy.deepcopy(self.c)
+        rule=next(item for item in classifier['pattern_migrations'] if item['source_glob']=='docs/EXPERIENCE_*.md')
+        rule['district']='decisions'
+        errors=validate_migration_map(classifier, ROOT)
+        self.assertIn('must use district traces, got decisions', '\n'.join(errors))
+    def test_experience_wildcard_routes_to_external_owner_route(self):
+        name='EXPERIENCE_'+'ROUTE.md'
+        source='docs/'+name
+        with tempfile.TemporaryDirectory() as tmp:
+            root=Path(tmp)
+            (root/'docs').mkdir()
+            (root/'docs'/name).write_text('# Experience route\n', encoding='utf-8')
+            (root/'mechanics'/'experience'/'legacy'/'raw').mkdir(parents=True)
+            moves=build_plan(root,self.c)
+        move=next(item for item in moves if item['source']==source)
+        self.assertEqual(move['target'],'mechanics/experience/legacy/raw/'+name)
+        self.assertEqual(move['district'],'traces')
     def test_no_current_root_allowlist_item_is_exact_moved(self):
         allow=set(self.c['current_root_allowlist']); moved={Path(i['source']).name for i in self.c['exact_migrations']}; self.assertFalse(allow & moved)
 if __name__=='__main__': unittest.main()