chore(task): archive 08-25-rc-p1-package-boundary

.trellis/tasks/archive/2026-08/08-25-rc-p1-package-boundary/design.md

@@ -0,0 +1,53 @@
+# Phase 1 Technical Design
+
+## Boundary
+
+`packages/road-compiler/` becomes the single implementation owner for native
+road compilation. It is a CommonJS workspace package with explicit public
+entrypoints for compiler APIs, traffic-signal schema, turn-lane helpers, OSM
+parsing, reference conversion, and CLIs. It never imports `area-config`, reads
+`config/areas`, or derives host paths.
+
+The host owns `scripts/lib/area-config.js` and maps normalized configuration to
+the v1 `RoadCompilerInput` shape using `toRoadCompilerInput(area)`. During P1,
+`build-area.js` calls the package in-process; P2 is the only phase that changes
+that call to a child process.
+
+## Source Ownership and Compatibility
+
+The following current `scripts/lib` implementations move into package `src`:
+`native-road`, `complex-junction`, `turn-lane-arrows`, `lane-geometry`,
+`gaode-junction-reference`, `native-traffic-signals`, and `osm`.
+
+Some moved modules also serve legacy host paths: QGIS uses turn-lane arrows,
+vehicle preview and reimport use OSM parsing, and preview tests use lane
+geometry. Those consumers import the package entrypoints after the move. This
+preserves one implementation while allowing host -> package dependency.
+
+Traffic signal ownership follows the matrix in
+`research/traffic-signals-split-matrix.md`: schema, geometry, validation, and
+runtime construction move to the package. The host retains only two file-I/O
+adapters, `readTrafficSignalFeatures()` and `readTrafficSignals()`, both
+delegating to package exports. No duplicated schema code remains.
+
+## Input and Path Handling
+
+The package compiler API accepts only `RoadCompilerInput` from
+`docs/native-road-package-v1.md`. Package CLI commands accept an explicit JSON
+input file (`--input`) and never load area configuration. The compatibility
+host CLI still accepts `--config`, but immediately maps it through
+`toRoadCompilerInput()` before entering the package.
+
+`junctionTemplates.*.referenceFile` changes to a path relative to its area
+configuration. `readAreaConfig()` resolves it while normalizing configuration;
+the package receives an absolute path and does no path resolution.
+
+## Tests and Rollout
+
+The package receives the required Fengshu OSM fixture plus migrated unit tests.
+Its `npm test` must run from the package directory without reading host inputs
+or outputs. After each source batch, run the two Phase 0 parity baselines. The
+existing host command names remain compatibility wrappers through P1.
+
+Rollback is a normal Git revert of the latest batch commit. No module has a
+parallel host copy after its batch lands, preventing divergence.