Add area quality gate

.trellis/spec/pipeline/cli-and-stages.md

@@ -12,6 +12,7 @@
 | `scripts/build-osm2streets-qgis.js` | intermediates 阶段的实现 | 由 build-area 调起；`npm run build:qgis` 可单跑 |
 | `scripts/reimport-gpkg.js` | reimport 阶段的实现 | 由 build-area 调起 |
 | `scripts/diagnose-area.js` | 快速区域诊断；只读配置、OSM 和已有产物 | `npm run diagnose:area` |
+| `scripts/check-area.js` | 区域质量门；复用诊断事实源并给出 PASS/FAIL 退出码 | `npm run check:area` |
 
 `scripts/parity.js` 和 `scripts/glb-digest.js` 是校验工具，不属于构建链，见
 [产物一致性指南](../guides/artifact-parity-guide.md)。
@@ -210,6 +211,91 @@ const glb = area.outputs.glb;
 
 ---
 
+## 区域质量门命令
+
+### 1. Scope / Trigger
+
+`check:area` 是提交或交付某个区域前的只读质量门。它复用 `scripts/lib/area-diagnostics.js`
+里的 OSM、产物、metadata、stage manifest 和 GLB digest 检查，只负责把诊断结果分类为
+failure / warning 并设置退出码。
+
+它不属于构建阶段，不进入 `--stages`，也不调用 QGIS、Blender、Cesium、压缩或重建。
+
+### 2. Signatures
+
+```bash
+npm run check:area
+npm run check:area -- --config config/areas/<area>.json
+```
+
+底层入口：
+
+```bash
+node scripts/check-area.js [--config config/areas/<area>.json]
+```
+
+### 3. Contracts
+
+- 不传 `--config` 时默认读取 `config/areas/nantaizi-lake-innovation-valley.json`。
+- 区域配置必须通过 `scripts/lib/area-config.js` 的 `readAreaConfig()` 归一化。
+- OSM / artifacts / metadata / GLB / manifest 的解析和检查必须来自
+  `scripts/lib/area-diagnostics.js`，不要在 `check-area.js` 里复制解析逻辑。
+- 输出为短 text report，包含 area、config、output、GLB 摘要、PASS/FAIL、failure
+  计数和 warning 计数。
+- 有 failure 时 `process.exitCode = 1`；只有 warning 或全绿时 `process.exitCode = 0`。
+
+### 4. Validation & Error Matrix
+
+| 条件 | 结果 |
+|---|---|
+| 配置文件不存在 / `id` 缺失 / OSM 文件不存在 | 共享诊断抛错，非零 |
+| OSM `<bounds>` 缺失或无效 | failure |
+| building multipolygon 缺 outer / unresolved way / open ring | failure |
+| building `height` 不能解析为正数米 | failure |
+| Cesium GLB / metadata / preview 缺失或类型错误 | failure |
+| metadata JSON 损坏 | failure |
+| GLB size / nodes / images 超保守预算 | failure |
+| expected stage manifest 缺失、损坏或 stale | failure |
+| stage manifest warning 内容包含 budget exceeded | failure |
+| QGIS preview 缺失 | warning，不阻断 |
+| GeoJSON / GeoPackage / QGIS project / Blend / render 缺失 | warning，不阻断 |
+| OSM way 引用缺失 node | warning |
+| metadata 存在但没有 `assets[]` | warning |
+
+### 5. Good/Base/Bad Cases
+
+- Good: `diagnose:area` 用于调查完整细节，`check:area` 用于提交前给 CI/人一个明确退出码。
+- Base: 旧区域只缺 QGIS preview 时，`check:area` 仍 PASS，但报告 warning。
+- Bad: `check:area` 内部重新拼输出路径或重新解析 GLB budget；这会和诊断事实源漂移。
+- Bad: 把 `check:area` 做成 `build-area --stages check`；质量门是只读命令，不是构建阶段。
+
+### 6. Tests Required
+
+- `node --check scripts/lib/area-diagnostics.js`
+- `node --check scripts/diagnose-area.js`
+- `node --check scripts/check-area.js`
+- `npm run diagnose:area -- --config config/areas/nantaizi-lake-innovation-valley.json`
+- `npm run check:area -- --config config/areas/nantaizi-lake-innovation-valley.json`
+- 用临时配置指向不存在的输出目录，确认 `node scripts/check-area.js --config <tmp>` 非零退出。
+
+### 7. Wrong vs Correct
+
+Wrong:
+
+```js
+const metadata = JSON.parse(fs.readFileSync("outputs/a/a.json", "utf8"));
+const glb = glbDigest("outputs/a/a.glb");
+```
+
+Correct:
+
+```js
+const result = analyzeArea(configPath, { repoRoot });
+const gate = classifyAreaQuality(result);
+```
+
+---
+
 ## Stage Manifest 契约
 
 ### 1. Scope / Trigger
@@ -359,7 +445,8 @@ writeStageManifest(area, {
 - `build-osm2streets-qgis.js:153`
 - `reimport-gpkg.js:93`
 - `compress-glb.js:16`
-- `diagnose-area.js:17`
+- `diagnose-area.js:13`
+- `check-area.js:13`
 
 ```js
 --kebab-case value   →   { kebabCase: "value" }

.trellis/spec/pipeline/index.md

@@ -13,7 +13,7 @@
 | 改九个 osm2streets 图层（增/删/改顺序/改色） | [图层表](./layer-registry.md) ← **最容易出静默错误** |
 | 调 QGIS / GDAL / Blender 子进程 | [外部工具调用](./external-tools.md) |
 | 加阶段、加 CLI 参数、改配置字段 | [CLI 与阶段](./cli-and-stages.md) |
-| 改区域诊断命令或共享区域配置归一化 | [CLI 与阶段](./cli-and-stages.md#区域诊断命令) |
+| 改区域诊断/质量门命令或共享区域配置归一化 | [CLI 与阶段](./cli-and-stages.md#区域诊断命令) 和 [质量门](./cli-and-stages.md#区域质量门命令) |
 | 改 stage manifest 写入、读取或 stale 判断 | [CLI 与阶段](./cli-and-stages.md#stage-manifest-契约) |
 | 改预览页生成 | [../preview/](../preview/index.md) |
 | 声称"纯重构，产物不变" | [产物一致性指南](../guides/artifact-parity-guide.md) |
@@ -84,7 +84,9 @@ config/areas/<id>.json
 | 文件 | 行数 | 职责 |
 |---|---|---|
 | `build-area.js` | 815 | 主入口：区域配置读取、阶段调度、Cesium 预览页、车辆巡航和 stage manifest 写入 |
-| `diagnose-area.js` | 557 | 快速诊断：OSM building relation、植被统计、现有产物、stage manifest 和 GLB digest |
+| `diagnose-area.js` | 36 | 快速诊断入口：调用共享 area diagnostics 并打印完整报告 |
+| `check-area.js` | 74 | 区域质量门入口：调用共享 area diagnostics，输出 PASS/FAIL 并设置退出码 |
+| `lib/area-diagnostics.js` | 660 | 共享区域诊断事实源：OSM、产物、metadata、stage manifest、GLB digest 和质量门分类 |
 | `lib/area-config.js` | 135 | 区域配置归一化与输出路径推导，供 build / diagnose 复用 |
 | `lib/stage-manifest.js` | 100 | stage manifest 路径、文件记录、GLB budget warning 和原子 JSON 写入 |
 | `build-osm2streets-qgis.js` | 1468 | intermediates：osm2streets 解析、图层拆分、人行道转角合成、GeoPackage 与 QGIS 工程生成 |