# `xyzac-trt.ini` Web/WASM 控制面板实施计划

文档状态：实施基线 v1.0

本计划完全以 [`xyzac-trt-control-panel-web-wasm-design.md`](xyzac-trt-control-panel-web-wasm-design.md) 为设计契约，目标是把以下 LinuxCNC 原生案例的控制面板、数据流和控制流迁移为 Worker/WASM/React/Three.js Web 控制台：

```text
linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.ini
```

它不是 AXIS 的截图复刻计划，而是面向行为、状态、错误、资源、轨迹、RTCP 和恢复结果的 Web-equivalent 实施计划。任何视觉实现都必须服从 Worker/WASM authoritative state。

“完全对标 LinuxCNC 源码”和“全部功能唯一来自 LinuxCNC WASM”定义为唯一权威合同，强制定义见 [`xyzac-trt-web-wasm-source-parity-contract.md`](xyzac-trt-web-wasm-source-parity-contract.md)。若本计划与该合同冲突，以源码对标合同的禁止项、source slice、WASM authority、first divergent tick 和 parity gate 为准。

## 1. 目标与不可变约束

### 1.1 交付目标

完成一个可在浏览器中运行的 XYZAC 五轴 TRT 控制台，覆盖：

1. exact-path 案例解析、资源闭包和启动诊断。
2. Dedicated Worker 中的 WASM 任务、解释器、TP、motion、XYZAC kinematics、HAL/IO 虚拟设备和固定 tick。
3. AXIS 等价的程序、MDI、Manual/Jog、Home、limit、override、spindle、coolant、tool 和 alarm 工作流。
4. `M428/M429/M430` switchkins/RTCP 切换、拒绝边界、状态确认和恢复。
5. XYZAC Cartesian pose、A/C 姿态、五个 joints、tool offset、rotation/axis offsets 和 canonical toolpath 的 Three.js 可视化。
6. protocol.v1 command/result/snapshot/event/stream、operation ledger、checkpoint、Worker 重启和 offline recovery。
7. native/Worker/WASM/React/Three.js 之间的确定性 parity 报告、错误样本和首个 divergent tick。

### 1.2 不可变约束

| 约束 | 实施要求 |
|---|---|
| WASM/Worker 权威 | React 不创建第二份 task、motion、kinematics 或 program authority；本地状态只能是 draft/pending |
| 固定 tick | 解释器、TP、motion、HAL、IO、kinematics、event、journal 以 logical tick 串行执行，不使用墙钟决定结果 |
| exact path | `xyzac-trt.ini` 中的 `HALFILE`、`POSTGUI_HALFILE`、`OPEN_FILE`、`SUBROUTINE_PATH`、`TOOL_TABLE` 和 `PYVCP` 按 exact path 解析，不按 basename 猜文件 |
| RTCP 原语 | `M428/M429/M430` 必须保留 remap 语义和 `motion.switchkins-type` 的确认，禁止前端直接写一个近似值 |
| 一致 gate | UI gate 只是 projection；Worker/runtime 必须再次检查 ESTOP/OFF/ON/HOME/IDLE/RUNNING/PAUSED/limit/fault/kinematics 条件 |
| 轨迹权威 | 预览和 Three.js 使用 canonical WASM trajectory/pose/joints；JS 不能重算 RTCP 结果冒充通过 |
| 单写者 | 一个 session 只有一个 Worker 写入 task/WASM/OPFS journal；多标签页只能观察或持有租约 |
| 幂等恢复 | 每个副作用命令有 operation id、ledger prepare/commit 和结果重查；超时不能盲目重发 |
| 能力拒绝 | 宿主路径、shell、真实硬件、socket、动态库和未授权 Python/HAL 能力稳定返回拒绝码 |
| 发布边界 | 没有官方 oracle、真实硬件、Safari/Firefox、OPFS crash 或许可证输入时保持 blocked，不升级为全 LinuxCNC parity |

## 2. 设计契约追溯

| 设计文档章节 | 本计划对应实施面 |
|---|---|
| §1 范围与版本边界 | `RTCP-00` source/runtime/version lock |
| §2 总体架构 | `RTCP-01` Worker topology、authority boundary |
| §3 启动与初始化 | `RTCP-02` exact case resolver/startup state machine |
| §4 AXIS 主控制面板 | `RTCP-05` UI domain、controls、status projection |
| §5 G-code 加载流 | `RTCP-04` PROGRAM_LOAD/preview/program ledger |
| §6 AUTO 运行流 | `RTCP-06` run/pause/resume/step/abort/restart |
| §7 MDI/Jog/Home/Tool/Offset | `RTCP-07` manual and device workflows |
| §8 SWITCHKINS/RTCP | `RTCP-08` M428/M429/M430/XYZAC kinematics |
| §9 状态真值 | `RTCP-03` snapshot/axis_state/gates |
| §10 Web/WASM mapping | `RTCP-09` protocol and frontend integration |
| §11 测试与限制 | `RTCP-10` parity/recovery/browser gates |

## 3. 功能范围矩阵

### 3.1 P0：必须先闭合的主链

| ID | 功能 | 原生来源/对照 | Web 结果 |
|---|---|---|---|
| P0-01 | 案例选择与启动 | `xyzac-trt.ini`、`run-5axis-rtcp.sh` | `TASK_READY` 或可定位 `BLOCKED_*` |
| P0-02 | 配置/资源图 | INI/HAL/XML/TBL/VAR/NGC/remap | exact path、source hash、missing edge |
| P0-03 | Task/ESTOP/OFF/ON | AXIS `stat.task_state` | axis_state + gate matrix |
| P0-04 | Mode MANUAL/MDI/AUTO | AXIS `ensure_mode`、`on_hal_status_mode_auto` | state transition + command result |
| P0-05 | Program load/open | AXIS `open_file_guts`、`c.program_open` | program hash、line count、preview |
| P0-06 | Canonical preview | AXIS canon/preview | stable segments/source lines |
| P0-07 | Program run | AXIS `task_run` | RUNNING、tick、active line |
| P0-08 | Pause/resume/step | AXIS `task_pause/resume/step` | PAUSED/RESUMED/step endpoint |
| P0-09 | Abort/restart | AXIS `task_stop/reload` | STOPPED/loaded、no duplicate side effect |
| P0-10 | MDI | AXIS `send_mdi_command` | parser result、queue gate、error |
| P0-11 | XYZAC kinematics | `xyzac-trt-kins.c`、`trtfuncs.c` | forward/inverse pose/joints |
| P0-12 | M428/M429/M430 | `428remap.ngc`、`429remap.ngc`、HAL net | active type + verified transition |
| P0-13 | Vismach pose/joints | `xyzac-trt-gui.py` | Three.js pose/joints/toolpath |

### 3.2 P1：操作完整性

| ID | 功能 | 关键边界 |
|---|---|---|
| P1-01 | XYZAC jog | X/Y/Z linear units，A/C angular units，按下/释放 stop |
| P1-02 | Home/unhome | 五 joint homing、共享开关、home sequence、重复 homing |
| P1-03 | Soft/hard limits | limit active、override limit、following error |
| P1-04 | Feed/rapid/spindle override | 范围、非有限值、暂停/ESTOP |
| P1-05 | Spindle/coolant | command/actual/at-speed、冷却状态、fault |
| P1-06 | Tool table/offset | `xyzac-trt.tbl`、tool offset、G43/G49/G43.1 |
| P1-07 | HAL/PyVCP | `type0/1/2-button`、legend、vismach-clear、HAL read |
| P1-08 | Alarm/event timeline | source、severity、operation id、acknowledge |
| P1-09 | Configuration diagnostics | startup/resource/HAL/remap errors |

### 3.3 P2：交付和恢复完整性

| ID | 功能 | 退出要求 |
|---|---|---|
| P2-01 | Checkpoint/journal | tick、program line、kinematics type、pose/joints、hash 可恢复 |
| P2-02 | Worker restart | 无重复 M428/M429、无重复 segment/IO/tool side effect |
| P2-03 | Offline project | 缓存资源、OPFS journal、配额和冲突可诊断 |
| P2-04 | Stream/backpressure | trajectory/HAL/log drop 有 cursor/gap/最终快照 |
| P2-05 | Browser matrix | Chromium/Firefox/Safari 逐项证据；缺环境保持 blocked |
| P2-06 | Native/WASM parity | normal/boundary/error/recovery + deterministic self-hash |

## 4. 目标架构

```text
React/Web UI
  ├── XyzacCaseView / ProgramView / ManualView / RtccpView / DiagnosticsView
  ├── Domain store: task/program/motion/kinematics/hal/devices/recovery
  ├── Pure gate selectors and source control IDs
  └── WorkerClient only
          │ protocol.v1 MessageEnvelope
          ▼
Dedicated sim.worker
  ├── ProtocolGateway + runtime schema validator
  ├── Session/Liveness/Lease manager
  ├── CommandLedger (prepare/ack/result/commit/reconcile)
  ├── XyzacCaseResolver + resource graph
  ├── SimScheduler (fixed logical tick)
  ├── WASM LinuxCncCompat
  │    ├── Task/RS274/TP/Motion
  │    ├── xyzac-trt forward/inverse
  │    ├── remap M428/M429/M430
  │    └── HAL/IO/tool/probe virtual devices
  ├── SnapshotPublisher + StateHash
  ├── OPFS journal/checkpoint/recovery
  └── trajectory/HAL/log stream backpressure
          │ authoritative snapshots/events
          ▼
React projection + Three.js XYZAC Vismach adapter
```

### 4.1 Authority ownership

| 数据 | 唯一 authority | React 是否可写 |
|---|---|---:|
| task state/mode/interp | WASM Task/Interpreter | 否 |
| program parsed state/line | WASM Interpreter/Task | 否 |
| TP queue/active segment | WASM TP | 否 |
| Cartesian pose/XYZAC joints | WASM Kinematics/Motion | 否 |
| switchkins type | WASM/HAL compatibility layer | 只能发请求 |
| homed/limit/following error | WASM Motion/Home/HAL | 否 |
| tool/offset/spindle/coolant | virtual IO/tool runtime | 只能发命令 |
| UI draft/selection | React local store | 是，但不等于运行态 |
| Three.js camera/layer toggle | React/renderer | 是，不影响 motion |

## 5. 实施任务队列

任务状态使用：`queued → in_progress → verified` 或 `in_progress → blocked`。每个任务完成时必须生成报告、自哈希、输入哈希、命令记录、错误边界和下一任务依赖。

### RTCP-00：源码、版本和案例锁定

**目标**：冻结 `xyzac-trt.ini`、所有引用资源、系统运行时和 source symbol 映射。

**直接输入**：

- `xyzac-trt.ini`
- `xyzac-trt.xml`
- `switchkins_postgui.hal`
- `demos/*.ngc`
- `remap_subs/*.ngc`
- `xyzac-trt-kins.c`、`trtfuncs.c`
- `xyzac-trt-gui.py`
- `context-lock.json`

**产物**：

- `coverage/xyzac-trt-web-source-lock.report.json`
- `web/workspace/xyzac-trt-source-contract.mjs`
- exact resource graph、source hash、runtime version record

**验收**：每个 INI path、HAL edge、PyVCP pin、remap、G-code 入口可追溯；缺失资源为明确 blocker。

### RTCP-01：Worker 拓扑和 LinuxCncCompat 外壳

**目标**：建立单 Worker/session/ledger/scheduler 边界，不实现五轴细节。

**产物**：

- `web/worker/xyzac-session.mjs`
- `web/worker/xyzac-scheduler.mjs`
- `web/worker/xyzac-command-ledger.mjs`
- `web/worker/test_xyzac_session.mjs`

**验收**：HELLO/CAPABILITIES/SESSION_ATTACH/SESSION_READY、seq、operation_id、取消、超时重查和重复命令测试通过；Worker 之外不能写 runtime。

### RTCP-02：Exact case resolver 和启动状态机

**目标**：把 `xyzac-trt.ini` 解析到 `TASK_NEW → CONFIG_RESOLVED → HAL_READY → RUNTIME_READY → TASK_READY`。

**要求**：

- 解析 `DISPLAY/TASK/HAL/RS274NGC/KINS/TRAJ/EMCIO`。
- 解析 `LIB:basic_sim.tcl` 的虚拟 HAL 边界。
- exact resolve `OPEN_FILE`、`SUBROUTINE_PATH`、`xyzac-trt.tbl`、`xyzac.var`、`xyzac-trt.xml` 和 `xyzac-trt-gui.py`。
- 识别 `BLOCKED_RESOURCE`、`BLOCKED_HAL`、`BLOCKED_INI`、`BLOCKED_STARTUP`。

**产物**：`web/workspace/xyzac-trt-case-loader.mjs`、startup snapshot、diagnostic report。

### RTCP-03：Authoritative snapshot、axis_state 和 gate matrix

**目标**：将 native task/motion/interp/home/limit/kinematics 状态统一为 Worker snapshot。

**产物**：

- additive `axis_state`
- `kinematics.active_type`
- `configuration.coordinates/joints/topology`
- `gates`（action/enabled/reason）
- `web/worker/test_xyzac_gate_matrix.mjs`

**验收**：ESTOP/OFF/ON/HOME/IDLE/RUNNING/PAUSED、limit/fault/tool/no-file/no-highlight 每项都有 gate reason 和状态哈希。

### RTCP-04：程序加载、canonical preview 和 program ledger

**目标**：实现 AXIS `open_file_guts → program_open → canon/preview → stat.file` 的 Worker/WASM 等价流程。

**要求**：

- source/path/hash/line count 固化。
- preview segment 带 id/source_line/start/end/motion_type/center/normal/turn。
- 解析错误、超限、非有限值、空文件和缺资源 fail closed。
- load/reload/restart 与 ledger/recovery 可重放。

**验收**：native 与 Worker 首个 segment、line count、preview hash、loaded file、invalid G-code 错误码一致。

### RTCP-05：程序运行控制和 AXIS workflow

**目标**：覆盖 Run/Pause/Resume/Step/Abort/Restart/Run-from-line。

**按钮约束**：

```text
RUN      = machine_on && interp_idle && task_file
PAUSE    = machine_on && interp_reading_or_waiting
RESUME   = machine_on && interp_paused
STEP     = machine_on && task_file
ABORT    = machine_on && interp_running
RESTART  = machine_on && interp_idle && task_file
RUN_LINE = RUN && highlight_line != null
```

**验收**：固定 tick 下 pause/resume 不重复 segment，abort 无重复副作用，restart 重置 program state 但保留正确 source hash。

### RTCP-06：MDI、Jog、Home 和 limit

**目标**：实现 XYZAC 手动控制。

**要求**：

- X/Y/Z 线性单位和 A/C 角度单位分离。
- pointerdown/keydown 只发一个 JOG_START；pointerup/keyup/blur/visibilitychange 必须发 JOG_STOP。
- MDI queue limit、running/paused/ESTOP gate 与 native 一致。
- home all、单 joint home、unhome、共享 home switch 和 limit override。
- following error、非有限速度、超范围轴拒绝。

**验收**：每个 X/Y/Z/A/C 轴有 normal/boundary/stop/fault/recovery 样本；A/C 不得被当作 linear mm。

### RTCP-07：HAL、PyVCP、tool、spindle、coolant 和 alarm

**目标**：把 `xyzac-trt.xml` 和 `switchkins_postgui.hal` 中的控件接入 Worker capability。

**功能**：

- type0/type1/type2 button 状态和 `kinstype.is-*` legend。
- `vismach-clear` 只清 visual plot。
- tool table、tool offset、G43/G49/G43.1、tool prepare/change。
- spindle command/actual/at-speed/direction、coolant、manual tool change。
- HAL pin read/write 白名单、类型和权限。
- alarm/event timeline、acknowledge、source file/line。

**验收**：HAL command 不能越权写任意 pin；tool/IO ack、timeout、abort、recovery 和 `REAL-EXCLUDED` 分类都有报告。

### RTCP-08：XYZAC kinematics 和 RTCP

**目标**：实现 `xyzac-trt-kins` 的 forward/inverse、tool offset、rotation/axis offset 和 switchkins。

**阶段拆分**：

1. K0：XYZAC 坐标/joint mapping、单位、limits、finite-value 校验。
2. K1：identity type 0，forward/inverse identity golden。
3. K2：TRT type 1，`trtKinematicsSetup`、XYZAC forward/inverse、`y-offset/z-offset`、tool-offset。
4. K3：userk type 2 capability boundary；无 userk 时稳定拒绝。
5. K4：M428/M429/M430 remap 与 `motion.switchkins-type` handshake。
6. K5：helix_ac/helix_bc、姿态变化、G93/arc、奇异/限位/非有限值。
7. K6：pause/resume/abort/restart/recovery 时 active kinematics type 和 pose/joints 保持一致。

**必须保存**：Cartesian pose、XYZAC joints、A/C angle、tool offset、rotation point、axis offsets、kinematics type、首个 divergent tick、state hash。

### RTCP-09：Protocol v1 和 React 控制台

**目标**：把现有 `axis-contract.mjs`、`AxisOperationController`、`PanelSnapshotV1` 扩展到 XYZAC。

**产物**：

- `KINEMATICS_SELECT`、`VISUAL_CLEAR`、`POWER` 等 additive commands。
- `xyzac-panel-snapshot.v1` additive view 或兼容扩展。
- React `XyzacTrtPanel`、`XyzacProgramPane`、`XyzacKinematicsControl`、`XyzacManualPanel`、`XyzacDiagnostics`。
- gate-aware controls、operation trace、alarm/recovery view。

**验收**：React 不直接调用 WASM/OPFS；所有 controls 只通过 WorkerClient；gate reason、pending、ack、result、error 状态可见。

### RTCP-10：Three.js XYZAC Vismach adapter

**目标**：使用 authoritative `visual.pose/joints/toolpath` 实现五轴模型。

**要求**：

- 机床结构对应 `xyzac-trt-gui.py`：table-x、saddle-y、spindle-z、tilt-a、rotate-c、tool-offset。
- pose/joints 与 toolpath 来自同一 `state_hash`/tick。
- camera/layer/clear 不改变 task/motion/program。
- canvas nonblank、A/C 旋转方向、tool offset、轨迹 active segment 和 resize/mobile 通过。

### RTCP-11：Journal、checkpoint、Worker restart 和 offline recovery

**目标**：恢复完整 XYZAC 运行态。

**checkpoint 最小字段**：

```text
context_id, case_id, source_hashes
simulation_tick, seq, state_hash
task_state, task_mode, interp_state, program_hash, current_line
kinematics_type, kinematics_transition, pose, joints
tool_offset, y_offset, z_offset, rotation_points
TP queue/active segment, HAL/IO/tool pending commands
```

**验收**：

- M428 在 checkpoint 前后不重复执行。
- 暂停程序恢复不重复 segment。
- tool/spindle/coolant/IO side effect 不重复。
- 损坏 checkpoint、缺资源、schema mismatch fail closed。
- Worker 重启后 endpoint pose/joints/program/kinematics/state hash 一致。

### RTCP-12：Native/Worker/Browser parity 和验收闭环

**目标**：形成 selected-case parity report，不冒充全 LinuxCNC release。

**矩阵**：

- Chromium desktop/mobile。
- Firefox/Safari 可用时运行；不可用保留 `HOST_EXCLUDED`/`blocked`。
- native AXIS + xyzac-trt-gui。
- Worker/WASM + React + Three.js。
- normal/boundary/error/limit/pause/abort/restart/recovery。

**产物**：

- `coverage/xyzac-trt-web-wasm-parity.report.json`
- native/worker command golden
- snapshot/trajectory/kinematics self-hash
- failure samples and first divergence report

## 6. 里程碑设计

### M0：Source and Case Contract

**包含**：RTCP-00。

**退出条件**：

- 所有直接引用资源均 exact-path indexed（不以抽样替代）。
- `xyzac-trt.ini` 的 INI/HAL/NGC/XML/Python/C source graph 自哈希稳定。
- 版本、context、运行时和能力边界记录完成。
- 缺失/未索引/宿主资源明确 blocked。

### M1：Worker Startup and State Authority

**包含**：RTCP-01、RTCP-02、RTCP-03。

**退出条件**：

- Worker session handshake、TASK_READY、CAPABILITIES 通过。
- snapshot 包含 task/motion/home/limit/program/kinematics/gates/configuration。
- ESTOP/OFF/ON/HOME/IDLE gate matrix 和 deterministic state hash 通过。
- React 尚未接入前，Worker 测试可独立验证 authority。

### M2：Program and AXIS Operation Workflow

**包含**：RTCP-04、RTCP-05、RTCP-06。

**退出条件**：

- load/preview/run/pause/resume/step/abort/restart/MDI/jog/home 全部有 native/Worker 对照。
- 每个操作的 gate reason、operation id、command result 和 state hash 可追溯。
- running/paused/ESTOP/limit/tool missing 的拒绝不被 UI 绕过。

### M3：HAL/IO/PyVCP and Device Closure

**包含**：RTCP-07。

**退出条件**：

- SWITCHKINS PyVCP 三个按钮和 vismach-clear 的 HAL 图可解析。
- spindle/coolant/tool/probe/hal read/write/ack/error 边界通过。
- 未授权 pin、外部进程、真实硬件被稳定拒绝。

### M4：XYZAC Kinematics and RTCP

**包含**：RTCP-08。

**退出条件**：

- type 0/1/2 切换和 M428/M429/M430 handshake 与 native 一致。
- XYZAC pose/joints/tool offset/axis offset/rotation point 的 forward/inverse golden 通过。
- helix/姿态变化、奇异、limits、non-finite、pause/abort/recovery 样本齐全。
- 首个 divergent tick 可定位；没有 JS kinematics fallback。

### M5：React/Protocol/Three.js Console

**包含**：RTCP-09、RTCP-10。

**退出条件**：

- React 所有按钮只通过 WorkerClient/OperationController。
- Three.js 使用 authoritative snapshot，A/C 方向、tool offset 和 active segment 正确。
- desktop/mobile DOM、canvas nonblank、keyboard/touch、错误/pending/gate UI 通过。

### M6：Recovery and Offline Runtime

**包含**：RTCP-11。

**退出条件**：

- checkpoint/restart/reconcile/replay 无重复副作用。
- OPFS journal、配额、schema mismatch、坏数据和离线重新打开可诊断。
- recovery endpoint state hash 与连续运行一致。

### M7：Selected-Case Parity Acceptance

**包含**：RTCP-12。

**退出条件**：

- native/Worker/WASM/React/Three.js 的选定案例完整矩阵通过。
- 结果报告有 source/input/output hash、命令、状态、首个差异 tick 和失败样本。
- Chromium/Firefox/Safari、官方 oracle、实时硬件、OPFS crash 和许可证边界按真实环境记录。
- 只能声明 `selected_case_verified`；任何外部 blocker 存在时保持 `STOP_RELEASE`。

## 7. 任务依赖图

```text
RTCP-00 source lock
        │
        ▼
RTCP-01 session/ledger ── RTCP-02 case startup ── RTCP-03 snapshot/gates
        │                         │                      │
        └─────────────────────────┴──────────────────────┘
                                  ▼
                 RTCP-04 program/preview
                         │
          ┌──────────────┴──────────────┐
          ▼                             ▼
   RTCP-05 run/control             RTCP-06 manual
          │                             │
          └──────────────┬──────────────┘
                         ▼
                 RTCP-07 HAL/IO/PyVCP
                         │
                         ▼
                 RTCP-08 XYZAC/RTCP
                         │
             ┌───────────┴───────────┐
             ▼                       ▼
      RTCP-09 React/protocol   RTCP-10 Three.js
             │                       │
             └───────────┬───────────┘
                         ▼
                 RTCP-11 recovery
                         │
                         ▼
                 RTCP-12 parity gate
```

不得跳过 RTCP-03 的 authority/gate、RTCP-04 的 canonical program 或 RTCP-08 的 kinematics 就先做“漂亮界面”。

## 8. 统一任务报告格式

每个 `RTCP-*` 任务必须生成 JSON 报告，至少包含：

```json
{
  "schema": "xyzac-trt-web-wasm-task-report.v1",
  "task_id": "RTCP-08",
  "milestone": "M4",
  "status": "verified",
  "context_id": "...",
  "case_path": ".../xyzac-trt.ini",
  "inputs": [{"path": "...", "sha256": "..."}],
  "outputs": [{"path": "...", "sha256": "..."}],
  "commands": [{"name": "...", "status": "passed", "stdout_sha256": "..."}],
  "normal": {},
  "boundaries": [],
  "errors": [],
  "first_divergent_tick": null,
  "known_blockers": [],
  "report_sha256": "..."
}
```

失败样本必须保留，不得删除失败、降低 gate、把资源缺失改成通过或用 JS preview/姿态镜像冒充 native/WASM parity。

## 9. 最低测试命令集合

任务开发期间按范围运行：

```bash
python3 scripts/validate_baseline.py
python3 scripts/validate_download_index.py
python3 scripts/validate_task_pointer.py nextTask1.md --lock context-lock.json
scripts/build-wasm.sh
ctest --test-dir build-native --output-on-failure
```

五轴专属命令：

```bash
./run-5axis-rtcp.sh
./run-5axis-rtcp.sh xyzbc-trt.ini
node web/worker/test_xyzac_trt_case.mjs
node web/worker/test_xyzac_program.mjs
node web/worker/test_xyzac_switchkins.mjs
node web/worker/test_xyzac_rtcp.mjs
node web/worker/test_xyzac_recovery.mjs
npm --prefix web/react run typecheck
npm --prefix web/react run build
```

命令名称在对应任务开始前必须实际创建并纳入报告；不存在的测试命令不能写成已通过。

## 10. 停止条件和阻塞处理

以下任一情况必须将当前任务标记为 blocked，并保留证据：

- `xyzac-trt.ini` 的 source/resource/hal/remap graph 不完整。
- native 运行时版本、锁定 source 或 ABI/protocol/schema 不一致。
- M428/M429 状态切换没有确认、重复执行或首个差异 tick 未定位。
- A/C 角度、tool offset、rotation point、joint pose 由 JS/React 生成。
- ESTOP、limit、following error、pause、abort、recovery 语义不可解释。
- 真实 HAL、动态 loader、宿主 Python、外部进程或真实硬件被错误标记为 Web-equivalent。
- Worker 重启造成重复 G-code、重复 tool/IO side effect 或 checkpoint hash 不一致。
- 只有 Chromium 截图而缺 Firefox/Safari/OPFS/oracle 证据，却要求全量 release。
- 缺少 owner/source/oracle/resource/browser/license 外部输入。

阻塞转移规则：

```text
技术缺陷 → 保留最小复现/错误码/首个 divergent tick → 修复同一任务
源码/ABI/protocol/schema 输入缺失 → SOURCE_BLOCKED → 等待审查输入
宿主/浏览器/硬件缺失 → HOST_EXCLUDED 或 REAL-EXCLUDED → 不伪造通过
发布/owner 决策缺失 → STOP_RELEASE → 不自动刷新 gate
```

## 11. 里程碑交付顺序

后续实施按以下顺序推进，不能在任务依赖未 verified 时跳级：

```text
M0 Source/Case Contract
  → M1 Worker Startup/Authority
  → M2 Program/AXIS Workflow
  → M3 HAL/IO/PyVCP
  → M4 XYZAC/RTCP Kinematics
  → M5 React/Protocol/Three.js
  → M6 Recovery/Offline
  → M7 Selected-Case Parity
```

每个里程碑完成后生成独立报告和自哈希，并将下一里程碑的直接输入、完成门禁、外部 blocker 和停止边界写入任务记录。完成单元测试或界面截图不等于该里程碑完成；必须同时满足 authority、数据流、控制流、错误、恢复和确定性要求。