feat: add OSM turn lane arrows

.trellis/tasks/08-04-add-osm-turn-lane-arrows/design.md

@@ -0,0 +1,74 @@
+# Design: OSM turn-lane arrows
+
+## Boundaries
+
+- `scripts/build-osm2streets-qgis.js` remains the intermediates owner. It will
+  append generated custom features to the existing in-memory `laneArrows`
+  collection before it is written as `lane_arrows_webscale.geojson`.
+- No render layer, QGIS symbol, Blender material, or Cesium export contract
+  changes. Existing `lane_arrows_webscale` styling and catalog ownership apply
+  to generated features automatically.
+- Vendored upstream artwork lives under a dedicated repository-local asset
+  directory with its CC0 license and a machine-readable manifest. The manifest
+  is the source of truth for upstream path, source revision, local path,
+  support status, and test status.
+
+## Asset Contract
+
+- Import every arrow SVG from `openstreetmap/lane-icons/docs/` that represents
+  an arrow. Preserve the source bytes and retain `LICENSE.md` with the assets.
+- Mark only `through`, `left`, `right`, `through;left`, and `through;right` as
+  `supported` and `tested` in the manifest. All remaining imported arrows are
+  `unsupported` and `untested`; no production parser may select them.
+- The upstream repository has left-side examples only. Derive `right` and
+  `through;right` through a deterministic horizontal mirror of the matching
+  left-side geometry, recording `derived_from` in the manifest.
+
+## Data Flow
+
+1. Parse OSM ways once using the existing OSM parser.
+2. Read `turn:lanes:forward` / `turn:lanes:backward`, split lane declarations
+   by `|`, and map only the five supported normalized maneuvers to manifest
+   entries.
+3. For each valid lane near a determinable intersection endpoint, calculate a
+   stable lane center and road-local axis; transform the selected local arrow
+   polygon into WGS84 coordinates.
+4. Add a GeoJSON feature with existing render-layer behavior and explicit
+   provenance: custom source, OSM way id, direction, lane index, maneuver,
+   source asset, and deterministic feature id/order.
+5. Record a structured skipped item when tags, lane geometry, or endpoint
+   classification are insufficient. Do not invent a fallback location.
+6. Existing normalization, scene merge, GeoPackage import, Blender assembly,
+   and Cesium export consume the expanded collection unchanged.
+
+## Geometry and Compatibility
+
+- Parse only the vendored SVG subset used by supported assets at build time:
+  `line` elements and `path` commands are converted into local meter-scale
+  polygons, with cubic curves sampled and SVG strokes expanded into outlines.
+  The source SVG is the sole geometry authority; no hand-drawn replacement
+  template is permitted. This stays dependency-free because the supported
+  upstream syntax is intentionally small and covered by Node tests.
+- Use the upstream Standard Arrow shape as the geometry basis, but let the
+  existing QGIS fill and outline preserve the project's visual language.
+- Preserve the existing osm2streets-generated arrow features. Custom features
+  are additive and have provenance that distinguishes them from upstream
+  osm2streets output.
+- Deterministic ordering is by way id, travel direction, and lane index.
+- Each asset manifest entry defines the source SVG's shaft-axis `anchor_x`.
+  Placement aligns that axis, rather than the SVG viewBox center, with the
+  lane centerline. Mirrored right-side variants mirror around the same axis.
+- Upstream SVG units are converted at `0.10 m` per unit. This calibrates their
+  local extent against the existing approximately 1.4 m osm2streets arrows;
+  do not use SVG display-pixel scale as road-marking scale.
+
+## Risks and Rollback
+
+- OSM lane counts, one-way semantics, or endpoint topology can be incomplete.
+  These cases remain skipped with diagnostics rather than creating misleading
+  markings.
+- Asset import is self-contained and CC0. Rollback removes the custom feature
+  generation and local asset directory; the existing arrow layer remains
+  unchanged.
+- User approval of the two initial visual samples is required before the
+  feature is enabled in production output.