osmWorkflow/.trellis/tasks/archive/2026-08/08-03-extract-road-module/implement.md

Implementation Plan

Checklist

1. Capture a parity baseline before product-code edits.
2. Add blender/osmassets/roads.py with current GeoJSON road layer assembly and OSM fallback logic.
3. Import roads.py in blender/generate_scene.py.
4. Remove inline add_geojson_layer() from generate_scene.py.
5. Replace the GeoJSON road layer call site with roads.assemble_geojson_layer(...).
6. Replace the OSM fallback loop with roads.assemble_osm_fallback(...).
7. Run Python validation:
   • python3 -m py_compile blender/osmassets/roads.py
   • python3 -m py_compile blender/generate_scene.py
   • python3 -m unittest blender/tests/test_pure.py
8. Capture parity after the refactor.
9. Compare before/after parity snapshots and inspect any non-ignored diff.
10. Update .trellis/spec and docs/changelog.md only for durable status or convention changes discovered during implementation.
11. Commit, archive the task, and record the journal entry.

Validation Commands

node scripts/parity.js capture road-module-before --stages blender,cesium
python3 -m py_compile blender/osmassets/roads.py
python3 -m py_compile blender/generate_scene.py
python3 -m unittest blender/tests/test_pure.py
node scripts/parity.js capture road-module-after --stages blender,cesium
node scripts/parity.js compare road-module-before road-module-after

Risk Points

• ROAD_LAYERS order is load-bearing. Do not reorder, filter, or copy it into a second list.
• road_counts must remain owned by generate_scene.py; fallback roads must still leave it unchanged.
• Layer catalog warning: print text must remain unchanged because it is the only runtime warning for JS/Python layer drift.
• Road_<layer_id> and OSM_Road_<way_id> names affect parity digests.
• clip_polygon() and feature_in_bounds() behavior must be reused exactly; do not replace with new geometry logic.
• Parity is mandatory because this is a pure refactor of bpy-layer scene generation.