Complete XYZAC LinuxCNC WASM parity and smooth 3D preview

2026-08-28 06:24:50 +08:00
parent e8fe323aab
commit 1a7995fa9b
181 changed files with 36854 additions and 215 deletions
--- a/doc-rtcp/xyzac-trt-web-wasm-implementation-plan.md
+++ b/doc-rtcp/xyzac-trt-web-wasm-implementation-plan.md
@@ -0,0 +1,572 @@
+# `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、数据流、控制流、错误、恢复和确定性要求。