chore(task): archive 08-25-rc-p2-repo-split

2026-08-26 09:28:33 +08:00
parent 7d4b3b566a
commit 969b57106f
6 changed files with 2 additions and 2 deletions
--- a/.trellis/tasks/archive/2026-08/08-25-rc-p2-repo-split/check.jsonl
+++ b/.trellis/tasks/archive/2026-08/08-25-rc-p2-repo-split/check.jsonl
@@ -0,0 +1,4 @@
+{"file":".trellis/spec/pipeline/external-tools.md","reason":"检查 CLI 子进程错误、signal 与日志处理是否符合宿主管线约定。"}
+{"file":".trellis/spec/pipeline/cli-and-stages.md","reason":"检查编译阶段、完成标记和 stage manifest 的跨层影响。"}
+{"file":".trellis/spec/guides/cross-layer-thinking-guide.md","reason":"检查配置、Node pipeline、Blender 消费链的边界没有漂移。"}
+{"file":".trellis/spec/guides/artifact-parity-guide.md","reason":"检查两个有效区域的严格基线 parity。"}
--- a/.trellis/tasks/archive/2026-08/08-25-rc-p2-repo-split/design.md
+++ b/.trellis/tasks/archive/2026-08/08-25-rc-p2-repo-split/design.md
@@ -0,0 +1,44 @@
+# Phase 2：独立仓库与 CLI 边界设计
+
+## Architecture
+
+P1 已将实现收敛到 `packages/road-compiler/`。P2 把该目录以保留历史的方式导出为独立 package 仓库，保留两个明确方向的边界：
+
+```
+宿主 area config
+  -> scripts/lib/area-config.js
+  -> RoadCompilerInput JSON（宿主 staging）
+  -> @osm-asset/road-compiler CLI（子进程）
+  -> native-road/ + NATIVE_ROAD_COMPILE_DONE
+  -> build-area.js / Blender / preview
+```
+
+编译器不知道区域配置、宿主仓库、Blender 或宿主输出目录约定以外的输入路径。宿主不知道 compiler 内部源文件；它只拥有输入 JSON、CLI 的完成标记和写出的契约文件。
+
+## CLI Contract
+
+- CLI 接收一个 JSON 文件中的 `RoadCompilerInput`，而不是宿主的 area config。
+- `comparisonDir` 继续作为可选输入，以维持现有 `comparison.json` 产物和 P0 baseline 的可比性。
+- 成功只打印一次 `NATIVE_ROAD_COMPILE_DONE <JSON>`。payload 必须至少含 `areaId`、`output`、`roads`、`endpoints` 和 `diagnostics`。
+- `build-area.js` 保持同步批处理模式，子进程日志对用户可见；为了验证标记，输出同时被捕获或 tee。它对启动失败、非零状态、signal、缺失/重复/非法标记和 payload 与当前输入不一致都报错。
+- 产物先由 compiler 的现有 staging/atomic promotion 逻辑写入目标 `native-road/`；宿主不接管这一写入过程。
+
+## Repository Contents
+
+独立仓库拥有：compiler source、public API、CLI、check、workbench、fixture、两个 parity baseline、契约文档、README、package lockfile 和 workbench 的 `ol` 依赖。测试和 workbench 均必须在没有宿主 checkout 的环境运行。
+
+宿主保留：area-config 读取/归一化、`RoadCompilerInput` 映射、pipeline 阶段编排、Blender/preview、区域配置、运行产物和一份升级回归 baseline。宿主 spec 仅保留指针，契约正文随 compiler 仓库维护。
+
+## History Extraction
+
+导出只允许 `git subtree split` 或 `git filter-repo`。必须在独立仓库验证 `git log --follow src/compile/native-road.js`；验证的是迁移前的逻辑历史，而非仅 P1 的边界移动提交。导出和验证先在临时分支/clone 完成，外部远端创建和 push 必须使用用户给出的地址和授权范围。
+
+## Dependency and Rollout
+
+初始发布源定为私有 `https://git.app.que01.top/que01/road-compiler.git`。仓库以带注释 tag `v0.1.0` 首发，宿主以该精确 tag 作为依赖并写入 lockfile。开发临时形态可以指向独立 checkout 的本地 `file:` 依赖；它不能成为验收时的唯一消费方式。两个区域 parity 通过后删除 `packages/road-compiler/`；回滚由 revert 宿主消费改造实现，不能让 production host 继续直接 import 该目录。
+
+## Compatibility and Risks
+
+这是位置和调用方式迁移，不改变 compiler 行为。两个区域的 strict content/order hash 是主要 oracle；信号文档的确定性生成仍应通过 parity 覆盖。P2 不处理 `check:area` 的历史 stage-manifest freshness warning，也不把 Blender/Metal 沙箱问题归因为道路产物。
+
+若外部 CLI 无法及时使用，回滚宿主消费 commit 即可；外部仓库历史和 tag 不需要删除。对于完整 Blender 构建，macOS Metal 初始化必须在提权的宿主环境运行。
--- a/.trellis/tasks/archive/2026-08/08-25-rc-p2-repo-split/implement.jsonl
+++ b/.trellis/tasks/archive/2026-08/08-25-rc-p2-repo-split/implement.jsonl
@@ -0,0 +1,4 @@
+{"file":".trellis/spec/pipeline/external-tools.md","reason":"CLI 子进程必须沿用管线的启动、日志和失败状态语义。"}
+{"file":".trellis/spec/pipeline/cli-and-stages.md","reason":"编译是 Blender 前的 pipeline 输入阶段，需保持阶段与 stdout 契约。"}
+{"file":".trellis/spec/config/index.md","reason":"宿主拥有区域配置归一化及 RoadCompilerInput 映射。"}
+{"file":".trellis/spec/guides/artifact-parity-guide.md","reason":"本阶段声称产物不变，必须用严格 parity 验证。"}
--- a/.trellis/tasks/archive/2026-08/08-25-rc-p2-repo-split/implement.md
+++ b/.trellis/tasks/archive/2026-08/08-25-rc-p2-repo-split/implement.md
@@ -0,0 +1,55 @@
+# Phase 2 执行计划
+
+执行前提：用户已在最新 P2 规划摘要后明确批准。发布目标已定为私有 `https://git.app.que01.top/que01/road-compiler.git`，首发 tag 为 `v0.1.0`。
+
+## 1. 导出并核验历史
+
+- [ ] 创建临时 export 分支或临时 clone，使用 `git subtree split --prefix=packages/road-compiler` 或 `git filter-repo --path packages/road-compiler/ --path-rename packages/road-compiler/:` 导出。
+- [ ] 在导出仓库验证 `git log --follow src/compile/native-road.js` 包含 2026-08-13 以来的 native compiler 历史。
+- [ ] 在私有 `https://git.app.que01.top/que01/road-compiler.git` 创建并推送独立仓库；创建带注释的 `v0.1.0` tag。
+
+## 2. 使编译器仓库自持
+
+- [ ] 将 CLI 作为 package `bin` 入口，接受由宿主写出的 `RoadCompilerInput` JSON，并继续输出唯一的 `NATIVE_ROAD_COMPILE_DONE` JSON 标记。
+- [ ] 补全 `package.json`、锁文件和 `ol` 依赖；workbench vendor 文件从自身安装目录提供。
+- [ ] 迁入 `docs/native-road-package-v1.md`、两个 baseline 和它们的测试驱动，新增独立 README。
+- [ ] 在不含宿主文件的临时 clone 内执行依赖安装、单元测试、两区域 parity 与 workbench 启动测试。
+- [ ] grep 验证没有 `area-config`、`config/areas`、宿主项目名或宿主相对路径引用。
+
+## 3. 宿主改为外部 CLI 消费
+
+- [ ] 将 compiler 以精确 git tag `v0.1.0` 安装到宿主并记录 lockfile；禁止范围版本、`latest`、`*` 和裸分支。
+- [ ] 将 `toRoadCompilerInput()` 序列化到每个区域的 pipeline staging 目录，传给 compiler CLI。
+- [ ] 在 `build-area.js` 的 blender 前置阶段调用 CLI。沿用管线的 `spawnSync` / `runCommand` 失败语义（启动错误、exit status、signal）和直通日志；缓冲或 tee stdout 后，解析恰好一个完成标记并验证其 `areaId`、`output` 与当前区域匹配。
+- [ ] 将 host workbench 的 fresh compile 回调切换到同一 CLI，不改变 fresh-process 行为。
+- [ ] 把所有 host 对 `packages/road-compiler/**` 的直接 import 替换成已安装包的公开 API 或 CLI；两个区域 parity 均通过后删除 in-host 副本。
+- [ ] 将宿主 pipeline spec 改为指向编译器仓库所拥有的契约文档。
+
+## 4. 验证与发布门
+
+新仓库（干净 clone）：
+
+```bash
+npm ci
+npm test
+npm run test:road-parity
+npm run road:workbench -- --config test/fixtures/fengshu-er-road.input.json --no-compile
+```
+
+宿主两个有效区域的逐字节 parity：
+
+```bash
+node scripts/road-parity.js --config config/areas/fengshu-er-road.json \
+  --compare .trellis/tasks/08-25-road-compiler-extraction/baseline/fengshu-er-road.json
+node scripts/road-parity.js --config config/areas/nantaizi-lake-innovation-valley.json \
+  --compare .trellis/tasks/08-25-road-compiler-extraction/baseline/nantaizi-lake-innovation-valley.json
+```
+
+- [ ] 为 CLI 标记成功、缺失、重复、非法 JSON、areaId 不匹配和 output 不匹配补测试。
+- [ ] 跑 package 单测、宿主 native-road / workbench / traffic signals / turn-lane-arrows 测试，以及两个 parity 检查。
+- [ ] 使用 `trellis-check` 做最终跨层检查；Blender 完整构建需以提权方式运行，原因是 macOS Metal 初始化不能在沙箱内启动。
+
+## Rollback
+
+- 外部仓库和已发布 tag 保留不动；在宿主 revert 消费改造即可回到 P1 边界。
+- 若按决定临时保留 in-host 副本，可将依赖回指该副本以恢复；该退路不取代 host parity 验证。
--- a/.trellis/tasks/archive/2026-08/08-25-rc-p2-repo-split/prd.md
+++ b/.trellis/tasks/archive/2026-08/08-25-rc-p2-repo-split/prd.md
@@ -0,0 +1,62 @@
+# Phase 2：拆仓库
+
+父任务：`.trellis/tasks/08-25-road-compiler-extraction/`
+
+## Goal
+
+把当前 `packages/road-compiler/` 拆为保留 git 历史、可脱离宿主独立测试和运行的仓库；宿主改为消费一个锁定版本的编译器 CLI。这样道路编译器可以独立演进，宿主依然通过版本化文件契约稳定构建场景。
+
+## Confirmed Facts
+
+- P1 已完成：编译器实现和 workbench 的所有权在 `packages/road-compiler/`；宿主负责将区域配置映射为 `RoadCompilerInput`。
+- `git log --follow packages/road-compiler/src/compile/native-road.js` 已能追溯到 2026-08-13 的 native-road compiler 历史。
+- 契约为 `native-road-package/v1`，完成标记为 `NATIVE_ROAD_COMPILE_DONE <json>`；`comparisonDir` 是可选输入，继续保留 `comparison.json`。
+- 当前宿主远端为内部 Git 服务 `https://git.app.que01.top/que01/osmWorkflow.git`；P2 独立编译器仓库定为私有 `https://git.app.que01.top/que01/road-compiler.git`。
+- 可维护范围只有 `fengshu-er-road` 和 `nantaizi-lake-innovation-valley`。`hanyang-block` 是废案，不参与基线、测试、验收或迁移语料。
+
+## Requirements
+
+### R2.1 保留 Git 历史
+
+- 用 `git subtree split` 或 `git filter-repo` 导出，不得以复制目录再 `git init` 替代。
+- 新仓库中 `git log --follow src/compile/native-road.js` 必须能追溯到 P1 之前的 native-road compiler 提交。
+
+### R2.2 新仓库可独立运行
+
+- 新仓库拥有 compiler、CLI、check、workbench、其测试 fixture、两个 parity baseline、契约文档和 README。
+- 新仓库 own `ol` 及其 workbench 所需的运行依赖；workbench 不得从宿主 `node_modules` 提供浏览器资源。
+- 新仓库不得引用宿主的 `area-config`、`config/areas`、`scripts/` 或本仓库绝对路径。
+
+### R2.3 宿主的消费边界
+
+- `scripts/lib/area-config.js` 继续是唯一的区域配置归一化与 `RoadCompilerInput` 映射位置。
+- `scripts/build-area.js` 用已安装编译器的 CLI 子进程编译，继承 stdout/stderr，检查启动错误、退出状态和 signal，并解析且校验唯一的 `NATIVE_ROAD_COMPILE_DONE` 标记。
+- 宿主只依赖 CLI、写入的文件和版本化输入 JSON；不再以相对路径 import 编译器内部模块。保留的宿主 signal 文件 I/O 适配层改为只调用公开包 API。
+- `road-workbench` 保持每次编译均启动新进程的语义，但改为调用已安装 CLI。
+
+### R2.4 版本与迁移
+
+- 宿主依赖必须锁定一个具体编译器版本，禁止 `latest` 或 `*`；包版本与 `native-road-package/v1` 的契约版本独立演进。
+- 初始分发使用带注释的 git tag `v0.1.0`；宿主锁定该 tag。完整 parity 验证后移除 `packages/road-compiler/`，不保留 in-host 副本作为正常消费路径。
+- 宿主保留两份 baseline，用来验证今后升级编译器版本后没有产物漂移。
+
+## Acceptance Criteria
+
+- [ ] AC2.1 独立仓库的 `git log --follow src/compile/native-road.js` 可见 P1 前的 compiler 历史。
+- [ ] AC2.2 在未 clone 宿主的干净目录中，新仓库 `npm ci`（或等价锁文件安装）和 `npm test` 均通过。
+- [ ] AC2.3 新仓库的两区域 parity（`fengshu-er-road`、`nantaizi-lake-innovation-valley`）均与迁入 baseline 完全一致。
+- [ ] AC2.4 宿主用锁版本依赖运行 CLI；`build-area.js` 成功解析一个有效的 `NATIVE_ROAD_COMPILE_DONE` 标记，缺失、重复或非法标记会失败。
+- [ ] AC2.5 宿主的两个区域 parity 均对保留 baseline 全绿。
+- [ ] AC2.6 宿主 `package.json` 的 compiler 依赖是具体、可复现版本，不是 `latest`、`*` 或裸分支。
+- [ ] AC2.7 编译器仓库对宿主反向依赖为 0，且其 workbench 可独立启动。
+
+## Out of Scope
+
+- 编译器几何、规则或输出内容改动。
+- 图层 manifest 和道路/建筑渲染分离（Phase 3）。
+- drawtonomy 扩展（Phase 4）。
+- `hanyang-block` 修复、迁移或作为验收样本。
+
+## Release Decision
+
+独立仓库为私有 `https://git.app.que01.top/que01/road-compiler.git`。首发以带注释 tag `v0.1.0` 发布，宿主依赖精确锁定该 tag；两个区域 parity 均通过后删除 `packages/road-compiler/`。该决定授权 P2 在该内部远端创建和推送仓库，但不授权发布到 npm 或其他托管平台。
--- a/.trellis/tasks/archive/2026-08/08-25-rc-p2-repo-split/task.json
+++ b/.trellis/tasks/archive/2026-08/08-25-rc-p2-repo-split/task.json
@@ -0,0 +1,26 @@
+{
+  "id": "rc-p2-repo-split",
+  "name": "rc-p2-repo-split",
+  "title": "Phase 2：拆仓库",
+  "description": "保留 git 历史拆出独立仓库，宿主以锁版本依赖消费，子进程为主契约",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P1",
+  "creator": "dingkang",
+  "assignee": "dingkang",
+  "createdAt": "2026-08-25",
+  "completedAt": "2026-08-26",
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": "08-25-road-compiler-extraction",
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}