Files
osmWorkflow/.trellis/tasks/08-18-native-only-pipeline-replacement/prd.md

3.7 KiB

Complete native-only pipeline replacement

Goal

Make the native road compiler the primary and complete production path. A normal build of an area must generate Blender, Cesium/package, and preview outputs directly from OSM plus native artifacts without installing or running QGIS, GDAL, or osm2streets.

The existing QGIS/osm2streets workflow remains available only as an explicit legacy/debug path and an optional Workbench reference layer. It is protected by the qgis-original-baseline-20260818 tag on main.

Confirmed Current Gaps

  • normalizeAreaConfig() defaults stages.intermediates to true and blender.roadProvider to osm2streets.
  • build-area.js sends intermediates to build-osm2streets-qgis.js and reimport to GDAL/QGIS.
  • Native Blender input exists, but preview still requires osm2streets_web_out/lane_polygons.geojson, network.json, and intersection_surface.geojson for vehicle-route generation.
  • Package/runtime publication still copies outputs.<area>.trafficSignals from the legacy GeoJSON directory instead of the native-road runtime artifact.
  • README, config templates, stage names, and manifest descriptions still present QGIS as the normal workflow.

Requirements

  • R1: Native is the default road provider and default build stages do not invoke QGIS, GDAL, or osm2streets.
  • R2: Native build generates all required road, lane, marking, junction, stop-line, and traffic-signal inputs consumed by Blender and preview; no native stage reads osm2streets_web_out.
  • R3: Native package publication copies runtime traffic signals and any other runtime descriptors from native-road outputs, with stable package-relative URIs.
  • R4: Native preview route generation uses native lane/road topology and native intersection geometry, or explicitly omits the optional vehicle route when native route data is unavailable; it must not fail because legacy osm2streets files are absent.
  • R5: QGIS/osm2streets stages remain callable only through an explicit legacy provider/stage selection and are not part of native defaults or native manifests. Workbench may display their existing GeoJSON as a clearly labeled reference/comparison layer, but native editing, compile, package, and preview results must not depend on it.
  • R6: Documentation and config templates describe native-only as the primary workflow and clearly mark the legacy path as transitional/debug-only.

Acceptance Criteria

  • A clean native-only area build succeeds with QGIS absent and no osm2streets-js-node runtime call, producing .blend, package manifest/GLB, runtime traffic signals, and preview HTML.
  • Native preview opens when osm2streets_web_out/ is absent; optional vehicle cruise either uses native route data or is omitted with a visible non-fatal diagnostic.
  • Native package manifest contains runtime traffic-signal anchors sourced from native-road/traffic-signals.json; disabled signals remain absent from runtime.
  • Workbench edits survive save, native recompile, package publication, and preview reload without QGIS or osm2streets files.
  • Explicit legacy QGIS/osm2streets commands still pass their existing focused tests, but no longer run when using native defaults.
  • Workbench remains usable when the optional osm2streets reference directory is absent; only the reference layer/comparison counters degrade to unavailable.
  • Tests assert the native-only dependency boundary and the QGIS baseline tag is documented.

Out Of Scope

  • Reimplementing QGIS editing features in the native compiler beyond existing Workbench controls.
  • Deleting legacy scripts or historical output files in this task; they remain rollback/debug tooling.
  • Changing Blender/Cesium visual semantics unrelated to removing the input dependency.