3.7 KiB
3.7 KiB
Phase 0：冻结契约与 parity 基线
父任务：.trellis/tasks/08-25-road-compiler-extraction/
契约权威定义：父任务 design.md §1
Goal
在任何代码移动之前，把 native-road-package/v1 契约落成仓库内文档，
并为两个有效区域建立可复跑的逐文件 parity 基线，作为全案唯一 oracle。
本阶段不移动、不重构任何生产代码。 只新增文档、基线数据和一个校验脚本。
Requirements
R0.1 契约文档
- 把父任务
design.md§1（输入契约 / 输出契约 / 消费方式）落成docs/native-road-package-v1.md。 - 文档必须列全 12 个图层名、
compiled.json顶层结构、diagnostics.json记录形状、 stdout 标记格式。 - Phase 2 会把该文档搬进编译器仓库，此处先落在宿主。
R0.2 确定性前置核查 🔴
基线只有在编译器确定性的前提下才有意义。 必须先证明这一点。
- 对同一输入连续跑两次
road:compile，比较全部输出文件。 - 识别并记录所有 volatile 字段（时间戳、绝对路径、staging 目录名、
任何来自
mkdtemp的随机名、Map/Set 迭代顺序敏感的输出）。 - 校验脚本必须归一化或排除这些字段。
- 若发现真实的非确定性（相同输入产出不同几何），必须先修掉再继续， 否则整个拆分没有 oracle。
R0.3 parity 校验脚本
- 新增
scripts/road-parity.js（宿主侧，Phase 2 随编译器搬走）。 - 能力：
--snapshot <out.json>遍历指定区域的native-road/全部文件 +native-traffic-signals.json，归一化后输出排序稳定的 checksum 清单--compare <baseline.json>与基线比对，差异逐文件报告- 非零退出码表示不一致
- GeoJSON 需按稳定键排序后再 hash（避免 feature 顺序抖动造成假阳性），
但顺序本身若变化必须被报告——用两个 hash：
contentHash（排序后） 与orderHash（原序），分别报告。
R0.4 两区域基线
- 区域：
fengshu-er-road、nantaizi-lake-innovation-valley - 从干净状态跑
npm run road:compile，产出基线 JSON 提交进版本控制 - 基线文件位置：
.trellis/tasks/08-25-road-compiler-extraction/baseline/<area>.json（Phase 2 搬进编译器仓库当测试语料，见父任务 R4）
hanyang-block 是废案，不纳入编译、快照或后续 parity 兼容范围。
R0.5 K2 决策定档
comparison.json 依赖宿主 osm2streets 产物（compile-native-roads.js:87 读
area.outputs.geojsonDir），拆出后不可达。本阶段必须做出决策并写入契约文档：
- 方案 A：移除
comparison.json（osm2streets 已 legacy） - 方案 B：保留，
comparisonDir作为可选输入注入 - 倾向 A。决策写入
docs/native-road-package-v1.md的「已移除能力」一节。
Acceptance Criteria
- AC0.1
docs/native-road-package-v1.md存在，覆盖输入契约、输出契约、 12 图层清单、stdout 标记、已移除能力 - AC0.2 连续两次编译的 parity 比对通过（确定性已证明），volatile 字段清单已记录在文档内
- AC0.3
scripts/road-parity.js可用，--snapshot/--compare均工作， 不一致时非零退出 - AC0.4 两个区域基线 JSON 已提交，且每个都能用
--compare自比对通过 - AC0.5 K2 决策已定档并写入契约文档
- AC0.6 未修改任何生产代码（
git diff只含新增文档 / 脚本 / 基线）
依赖与顺序
- 无前置依赖，本阶段是全案入口
- 阻塞 Phase 1、2、3、4 —— 没有基线就没有 oracle
Out of Scope
- 任何生产代码改动（含"顺手修一下"）
- 目录结构调整
compiled.json结构变更