chore(task): archive 08-04-add-osm-area-preflight

.trellis/tasks/archive/2026-08/08-04-add-osm-area-preflight/prd.md

@@ -0,0 +1,46 @@
+# Add OSM area preflight
+
+## Goal
+
+在调用 QGIS、Blender 或 Cesium 前，快速验证区域 OSM 是否包含会导致建筑或场景几何错误的人工编辑问题。使用者应得到明确的通过/失败结果和可定位的问题列表，而不必先跑重型构建阶段。
+
+## Confirmed Facts
+
+- `scripts/lib/area-diagnostics.js` 已是区域配置和 OSM 解析的事实源；它已覆盖 bounds、building multipolygon、缺失 node 引用及高度标签，并被 `diagnose:area` 和 `check:area` 共同复用。
+- `diagnose:area` 是全文诊断，包含既有产物、GLB 与 manifest；它不适合成为编辑 OSM 后的轻量独立门槛。
+- 当前 `nantaizi-lake-innovation-valley` 是唯一验证目标。忽略 `action=delete` 的历史对象后，其 OSM 有 1 个健康的建筑 multipolygon 和 23 个有效显式高度标签。
+- 全阶段 manifest 已存在；新预检不应被实现为 `build-area --stages` 的构建阶段。
+
+## Requirements
+
+1. 新增 `npm run preflight:area -- --config config/areas/<area>.json`，只读取区域配置和 OSM XML；不得调用 QGIS、Blender、Cesium、压缩或写入场景产物。
+2. 从共享 diagnostics 模块提供结构化 OSM 预检结果，避免新增第二套 XML/建筑关系解析。
+3. 预检应检查：有效 bounds、way 引用的 node、building way 闭合性和最小节点数、建筑 multipolygon 的 outer/inner member、成员存在性、可拼接闭环，以及 building `height` / `building:levels` 的基本可解析性。
+4. 命令输出简短摘要、错误和警告；存在 blocking error 时以非零退出。
+5. 成功预检写 `<areaDir>/_pipeline/stages/preflight.manifest.json`，记录配置和 OSM 输入的文件摘要、预检摘要、errors 与 warnings。失败预检不得覆盖此前成功 manifest。
+6. `diagnose:area` 显示预检 manifest 的状态；`check:area` 仅在该 manifest 已存在时检查其新鲜度和有效性，避免使历史区域在首次采用前立即失败。
+7. README 和 Pipeline spec 记录命令、退出码与 manifest 所有权。
+
+## Acceptance Criteria
+
+- [x] 当前南台子 OSM 上 `npm run preflight:area -- --config config/areas/nantaizi-lake-innovation-valley.json` 输出 PASS、写入 fresh `preflight.manifest.json`，且不触发重型工具。
+- [x] 预检报告包含 buildings、multipolygon、bounds 和几何健康统计。
+- [x] 通过临时 OSM fixture 验证：缺失/无效 bounds、缺失 node、未闭合 building way、破损 building multipolygon、无效显式 height 都能得到定位明确的 blocking error。
+- [x] `diagnose:area` 显示 preflight manifest，`check:area` 对存在但 stale/invalid 的 preflight manifest 失败。
+- [x] 原有 `diagnose:area` 与 `check:area` 继续通过当前南台子区域。
+- [x] 修改脚本通过 Node 语法检查和 `git diff --check`。
+
+## Out Of Scope
+
+- 不修复 OSM 文件，不自动重组关系或补齐标签。
+- 不检查道路拓扑、转向箭头渲染、osm2streets 的语义兼容性，或任意非建筑面是否合法。
+- 不把预检加入 `build-area` 的默认阶段，也不要求未运行过预检的历史产物立即失败。
+- 不验证 `hanyang-block`。
+
+## Key Decisions
+
+- 缺失 node 引用一律作为 blocking error。它表示 OSM 引用完整性已损坏，即使当前出现在非建筑 way，也不将问题带入后续构建。
+
+## Notes
+
+- 这是跨 CLI、OSM 解析、质量门和 manifest 的改动，按复杂任务处理，需要 design 和 implement 工件后再开始实现。