# 06-决策记录

本文件记录关键技术决策。后续如需变更，必须新增记录说明原因、影响和替代方案，不直接覆盖旧决策。

## 记录模板

```text
## ADR-XXX 标题

日期：
状态：
背景：
决策：
理由：
影响：
变更条件：
```

## ADR-005 当前验收闭合采用“命令全绿 + 条件边界显式锁定”口径

日期：2026-07-09
状态：生效

背景：

本轮已让上游基线、vendor 同步、Native/WASM/Browser/OPFS/UI/Host 聚合命令通过，但 Python remap、User M 外部进程、硬件驱动和实时内核天然涉及浏览器沙箱、外部进程或实时环境限制，不能因为 smoke 全绿就宣称无条件 LinuxCNC full-process 支持。

决策：

`ACC-001` 到 `ACC-023` 的当前闭合采用“可执行命令包全绿 + 条件边界显式锁定”口径：能由 LinuxCNC 源码、Native probe、WASM Node、真实浏览器和 UI/OPFS gate 证明的部分标为完成；Python remap、User M、硬件/实时等仍保留 `manual_promotion_lock`、Blocked 或条件通过说明。

理由：

这样既满足当前发布前命令包 `unexpected_fail=0` 的可复验证据，又避免把浏览器环境无法直接承载的 LinuxCNC 外部进程/实时能力误报为已经完整实现。

影响：

- `04-任务矩阵.md` 中相关任务可以闭合，但状态使用“条件通过”而不是无条件“完成”。
- `05-验收证据.md` 必须保留 inventory `29/29/130/0`、skip/block 分类和 Python remap manual lock 说明。
- 后续如果要解除条件边界，必须新增 ACC 任务、源码归属、runtime owner、fixture 和验收 gate。

变更条件：

只有当对应 runtime 或安全边界真正实现，并且 Native/WASM/Browser/UI 证据同时通过后，才能把条件通过项升级为无条件完成。

## ADR-001 以 LinuxCNC 源码和测试资产作为唯一数控语义基准

日期：2026-07-09
状态：生效

背景：

验收标准明确要求“完全对标 LinuxCNC”必须证明核心数控语义来自 LinuxCNC 源码、测试资产和运行规则，而不是界面相似或项目自研近似实现。

决策：

`wasm-port` 的 G 代码解释、刀补、参数、remap、刀具、轨迹规划、运动学、Task/HAL/Motion 等 CNC 语义只能来自 LinuxCNC 源码复用、vendored 同步或明确的薄封装。JS/TS、浏览器 UI 和项目自有 C/C++ 只能承担文件、调度、展示、持久化、C ABI 和边界桥接职责。

理由：

这能避免 Web 端逐渐形成第二套状态真相，也能让上游测试迁移、Native/WASM/Browser 对比和 blocked table 具备共同基准。

影响：

- 新功能必须先找到 LinuxCNC 源码归属。
- 找不到归属的功能不能宣称为 LinuxCNC 对标功能。
- 疑似自研 CNC 语义必须通过 `verify_no_standalone_cnc_semantics.sh` 或人工审查解释清楚。

变更条件：

只有验收标准更新并允许某类非 LinuxCNC 语义作为产品扩展时，才能改变此决策；即使变更，也必须与 LinuxCNC 对标功能分开标识。

## ADR-002 采用 L0-L5 加 Blocked 的晋级模型

日期：2026-07-09
状态：生效

背景：

只写“完成”无法区分源码已同步、Native 通过、WASM 通过、浏览器通过和 UI 发布，也容易把 full-process 或硬件依赖降级为解释器通过。

决策：

所有任务使用 `L0 已盘点`、`L1 已同步`、`L2 Native 通过`、`L3 WASM 通过`、`L4 Browser 通过`、`L5 UI 发布`、`Blocked` 表达真实进度。

理由：

该模型与验收标准的分层证据体系一致，可以防止跳级宣称，也方便后续按证据缺口继续推进。

影响：

- 任务矩阵必须记录晋级目标。
- 浏览器/UI 功能不能只凭 Native 或 WASM 结果标为 L5。
- Python remap、动态 loadrt、硬件驱动、实时内核等未闭合项应标 Blocked 或条件通过。

变更条件：

如果新增运行层级或验收标准调整证据层级，需要补充状态定义。

## ADR-003 把 `完善wasm/working` 作为总验收推进入口

日期：2026-07-09
状态：生效

背景：

`wasm-port/working` 已存在 task/status JSON 等局部推进文档，并显示当前 task-HAL 工作已闭合。新的验收标准覆盖整个 LinuxCNC 功能树，需要一个更高层的总入口。

决策：

`完善wasm/working` 作为完整 LinuxCNC 对标推进入口，维护总任务矩阵、验收证据和决策记录；`wasm-port/working` 继续作为 `wasm-port` 内部具体阶段文档和历史证据来源。

理由：

这样可以避免把某个已闭合子方向误认为整体验收完成，同时保留既有工作成果。

影响：

- 后续总体验收先看 `完善wasm/working/README.md` 和 `04-任务矩阵.md`。
- 涉及具体实现时，再跳转到 `wasm-port/docs`、`wasm-port/working` 和对应测试。

变更条件：

如果后续决定把总入口迁入 `wasm-port/working`，必须同步迁移任务编号、证据和决策记录，避免两套矩阵并行。

## ADR-004 截图和 UI smoke 只能作为补充证据

日期：2026-07-09
状态：生效

背景：

验收标准明确浏览器测试不能只验证页面元素存在，UI 的坐标、模态、刀具、主轴、程序状态必须与底层 LinuxCNC 状态快照一致。

决策：

截图、录屏、DOM smoke 和页面存在性检查只作为 P5 证据。任何核心语义、OPFS、Worker、UI 状态发布都必须有 C ABI、状态 JSON、OPFS 文件或底层快照证据支撑。

理由：

UI 可以显示正确外观但底层状态错误；P4/P5 分离可以防止验收被外观证据污染。

影响：

- UI 任务必须绑定底层状态断言。
- 真实浏览器 smoke 需要检查运行结果、错误、文件或快照，而不是只检查按钮。

变更条件：

无底层状态可取的纯视觉展示功能可用截图验收，但不得宣称 LinuxCNC 核心语义通过。