新下一步执行计划

生成时间：2026-06-09 14:20 CST

本计划接替 `text.txt`。后续执行以本文件为准。

项目纪律：

- 数控/G-code/remap/tool/parameter/planner/kinematics/user-M 语义必须来自
  LinuxCNC upstream 或 vendored LinuxCNC C/C++ source。
- 本项目允许写的代码范围是：构建、source sync、runtime shim、filesystem
  staging、OPFS、WASM/browser boundary、测试胶水、文档。
- 不通过修改 G-code 语义、JS 解释逻辑、或 standalone `Interp::...` 实现来让
  测试通过。
- 需要 INI/tool table/parameter file/SUBROUTINE_PATH/USER_M_PATH/remap-NGC
  上下文的程序，必须带上下文运行，不能脱离配置单独判断。
- browser 不能依赖目录枚举。browser/Node 共享 staging 时，优先使用
  `tools/source-manifest.txt` + INI 文本生成计划。

当前已完成基线：

- 规划 i：G-code run_step 状态输出已完成第一阶段。
  已输出当前行号、statement_uri、进度相关 step、X/Y/Z/A/B/C/U/V/W 位置。
  UI 已优先解析 run_step，fallback 到 canonical event。

- 规划 ii：基础 G-code smoke 已固化代表集。
  `nc_files/3D_Chips.ngc` 已按 tool-table context 运行，裸跑缺 tool 的负向边界
  已明确。

- configs/sim 代表 runtime edge 已覆盖：
  `axis/foam` U/V axis mask、bridge-mill W/remap path、`axis/geometry` M110、
  `external_offsets` M111 和 subroutine staging 已在 native/WASM/browser
  representative smoke 中验证。

- 文件上下文 staging 规则已抽成通用 SDK helper：
  `planIniFileContextStaging()` 负责 generic INI-context manifest-based plan；
  `planSimConfigStaging()` 是 `configs/sim` wrapper；
  Node 和真实 browser smoke 已覆盖 INI、OPEN_FILE、TOOL_TABLE、PARAMETER_FILE、
  multi-directory SUBROUTINE_PATH、USER_M_PATH、executable user-M、remap-NGC 和
  wasmPath 输出。

- 测试分层文档已补齐：
  `docs/compatibility-validation.md` 已记录 4 层测试的入口、当前结果、
  LinuxCNC-owned behavior、host/WASM adapter allowance 和 expected-failure
  policy。

当前验证口径：

- Layer 1: `wasm-port/tests/native/verify_nc_files.sh`
  当前基线：total 107, pass 101, expected_fail 6, unexpected_fail 0。

- Layer 2: `wasm-port/tests/native/verify_sim_configs.sh`
  当前基线：total 159, pass 151, expected_fail 8, unexpected_fail 0。

- Layer 3: `wasm-port/tests/native/verify_native_probes.sh`
  当前应通过，包含 source sync、no-standalone-semantics、native fixture
  baseline、sim-config 和 nc_files checks。

- Layer 4: `wasm-port/tests/host/verify_host_smokes.sh`
  当前应通过，包含 Node WASM、OPFS、browser interpreter 和 browser INI panel
  representative smoke。

新执行顺序：

1. 先稳定当前大批改动，不继续扩大测试面

目标：

- 对当前累计改动做一次完整一致性验证。
- 确认 vendor manifest、native probes、Node/browser smoke 都仍处于可提交状态。
- 在继续新增 upstream tests 前，先把当前批次变成一个清晰、可审查的工作集。

执行：

```bash
git diff --check
wasm-port/tools/verify_vendor_sync.sh
wasm-port/tests/wasm/node/verify_interp_wasm.sh
wasm-port/tests/wasm/node/verify_sim_configs_wasm.sh
wasm-port/tests/browser/verify_interp_browser.sh
wasm-port/tests/host/verify_host_smokes.sh
wasm-port/tests/native/verify_native_probes.sh
```

通过条件：

- `git diff --check` clean。
- `vendor sync validation complete`。
- `interp_wasm_node_smoke=ok`。
- `sim_configs_wasm_node_smoke=ok`。
- `browser_interp_smoke=ok`。
- `host_wasm_opfs_browser_smokes=ok`。
- native summaries 中仍为：
  `sim-configs total 159 pass 151 expected_fail 8 unexpected_fail 0`
  和
  `nc_files total 107 pass 101 expected_fail 6 unexpected_fail 0`。

不做：

- 不新增 upstream fixture。
- 不改 LinuxCNC vendored 文件内容。
- 不把 expected failure 改成 pass，除非 runtime edge 已经通过 vendored source
  路径证明。

2. 整理当前大批改动的提交/审查边界

目标：

- 把当前累计改动按逻辑拆成可审查批次。
- 如果不提交，也至少在文档里列出可拆分边界，方便后续 review。

建议拆分边界：

- Batch A: run_step 状态输出和 UI/browser/Node 断言。
- Batch B: nc_files 代表 smoke 和 `3D_Chips.ngc` tool-table context。
- Batch C: upstream `tests/interp/*`、`tests/ccomp/*` selected fixture 扩展。
- Batch D: G92 parameter persistence、tool table、G10/G52/G71/G72/G76 等
  interpreter regression coverage。
- Batch E: generic INI-context staging helper 和 Node/browser synthetic coverage。
- Batch F: 文档分层、source reuse map、compatibility validation、tracker 更新。

执行：

```bash
git status --short
git diff --stat
git diff --name-only
```

输出要求：

- 记录每个 batch 对应文件。
- 标明哪些新增 `wasm-port/vendor/linuxcnc/...` 文件必须由
  `tools/source-manifest.txt` 和 `verify_vendor_sync.sh` 覆盖。

3. 收敛 configs/sim 剩余 expected failure，不改语义

目标：

- 继续分析 Layer 2 中 8 个 expected_fail。
- 明确哪些只是 upstream `rs274` 缺 task/user-M/runtime context；
  哪些已经由 Layer 3/4 runtime representative smoke 覆盖；
  哪些仍需要新的 runtime adapter 或 blocked entry。

重点对象：

- `axis/foam/foam.ngc`
  已有 U/V axis mask runtime coverage。确认 Layer 2 expected_fail 是否只属于
  native upstream standalone context 限制。

- `axis/vismach/5axis/bridgemill/5axisgui.ngc`
  已有 bridge-mill W/remap representative coverage。确认 expected_fail 是否只
  属于 native full sim/task/HAL boundary。

- `axis/geometry/xyzc.ngc`
  已有 M110 USER_M_PATH deterministic boundary。确认 native expected_fail 与
  runtime coverage 对齐。

- `axis/external_offsets/*.ngc`
  已有 M111 deterministic boundary 和 `opa_demo.ngc -> circles.ngc`
  SUBROUTINE_PATH staging。确认剩余 expected_fail 的具体原因。

- `incremental_repetition_g533.ngc`
  保留 upstream demo expected failure。禁止通过修改 G-code 语义或 runner
  语义让它 pass。

执行：

```bash
wasm-port/tests/native/verify_sim_configs.sh
cat wasm-port/build/native/sim-configs/summary.tsv
```

产出：

- 更新 `docs/compatibility-validation.md` 或
  `docs/linuxcnc-test-porting-tracker.md`，逐条记录 8 个 expected_fail 的当前
  层级归因。
- 如果某项已由 Layer 3/4 覆盖，写明对应验证命令和 smoke assertion。
- 如果某项未覆盖，加入明确 blocked dependency 或下一步 runtime boundary。

4. 将 generic INI-context staging helper 用到更多手写 staging 点

目标：

- 减少 Node/browser 测试中手写 `TOOL_TABLE`、`PARAMETER_FILE`、
  `SUBROUTINE_PATH`、`USER_M_PATH` 和 remap files 的重复。
- 只迁移“已经 vendored 且 manifest 完整”的测试，不扩大功能面。

候选：

- `tests/wasm/node/verify_interp_wasm.mjs` 中带 `test.ini`、`test.tbl`、
  `startup.var`、`subs/*.ngc` 的 upstream regression staging。
- `tests/browser/interp_smoke.html` 中与 Node 同构的 upstream regression
  staging。
- 不急于迁移 five-axis 专用 staging，除非能保持 `executionMode:
  "fiveAxisRemap"` 现有路径清晰。

执行原则：

- 先抽小 helper：`loadPlannedVendorFiles(plan)` 或测试局部 helper。
- 保持 `planIniFileContextStaging()` 只返回 plan，不读文件、不 fetch。
- Node 侧从 filesystem 读 `vendor/linuxcnc/${sourceRel}`。
- Browser 侧 fetch `../../vendor/linuxcnc/${sourceRel}`。
- 每次迁移后跑：

```bash
wasm-port/tests/wasm/node/verify_interp_wasm.sh
wasm-port/tests/browser/verify_interp_browser.sh
wasm-port/tests/host/verify_host_smokes.sh
```

5. 继续 upstream `tests/interp/*` intake，但必须小批量

前置条件：

- 第 1 步完整验证通过。
- 第 2 步当前工作集边界清楚。
- 第 3 步 expected failure 归因没有新疑点。

候选优先级：

- 纯 interpreter file execution。
- 不需要 Python remap。
- 不需要 full task/motion/HAL process。
- 需要 tool table/parameter/subroutine context 的测试，必须通过 INI-context
  staging 运行。
- 有 upstream expected output 或可稳定断言 canonical event/error text。

候选方向：

- `tests/interp/oword-unwind`
  可能适合 continue-on-error runner；先 native probe 验证，再 Node/browser。

- `tests/interp/g6164`
  先确认是否纯 interpreter、是否需要额外 machine/runtime context。

- `tests/interp/compile`
  先判断它是 compile/source test 还是 runtime interpreter test；不要误归类。

- `tests/interp/mdi-*`、`oword-mdi-*`
  默认视为 MDI/UI/full-process 候选，先加入 blocked table，除非能证明存在
  NGC-only subpath。

- `tests/interp/pymove`、`python-self`
  默认 blocked：Python O-word/remap boundary 未实现。

每个 intake 必须执行 checklist：

- 记录 upstream path。
- byte-for-byte vendor 原始文件。
- 更新 `tools/source-manifest.txt` 和 vendor sync。
- 确认 LinuxCNC source ownership。
- 先 native harness/probe，再 Node WASM，再 browser。
- 更新 `docs/source-reuse-map.md`、
  `docs/compatibility-validation.md`、
  `docs/linuxcnc-test-porting-tracker.md`。
- 如 blocked，加入 blocked-test table 并写清 dependency。

6. 不做事项

- 不继续扩大 `configs/sim` 全量 WASM/browser 执行面，除非某个 expected failure
  已经有明确 runtime boundary 价值。
- 不引入 JS G-code parser 或 JS remap/tool/parameter semantics。
- 不编辑 `linuxcnc/` upstream 工作树。
- 不修改 `wasm-port/vendor/linuxcnc/` vendored 文件内容；只能 byte-for-byte copy
  upstream 文件。
- 不绕过 `tools/verify_no_standalone_cnc_semantics.sh`。

推荐下一次立即执行：

1. 运行第 1 步完整一致性验证。
2. 如果通过，执行第 2 步，整理当前工作集 batch 边界。
3. 然后再进入第 3 步，逐条归因 configs/sim 8 个 expected_fail。