按原因重写高效迭代规则

结论：针对长期迭代仍未完成的问题，明确慢因集中在 Python/remap、tooldata mmap、HAL/native filesystem、smoke fallback 和重验证闭环；后续默认只按三条高收益切片推进，并限制 source-map/docs-only 循环。

检查：git diff --check -- AGENTS.md SKILL.md 通过。instruction-only 文档变更，未运行 simulator native/source-link。

.agents/skills/align-linuxcnc/SKILL.md

@@ -61,6 +61,47 @@ For switchkins/remap table changes, also run:
 5. Run required tests.
 6. Report percent complete, source basis, changed files, and tests.
 
+## Acceleration Rules
+
+When the user says "尽快推进", optimize for completion progress, not just
+more source-map anchoring.
+
+- Prefer work that changes runnable coverage or removes a real blocker:
+  source-linked RS274 behavior, WASM-safe LinuxCNC dependency wrapping,
+  generated LinuxCNC config/remap fixtures, OPFS browser persistence checks, or
+  source-backed bridge/API paths.
+- Do not spend consecutive turns on documentation/source-map-only tightening
+  unless it unblocks a build/test, covers a newly added source path, or the user
+  explicitly asks for documentation. After two source-map-only commits, the next
+  iteration must attempt code, generated fixture, manifest, or executable test
+  progress.
+- Batch one coherent mini-slice instead of one-line guard churn: update the
+  LinuxCNC source basis, the relevant manifest/generator/test, and the minimal
+  shim/bridge in the same commit when they belong to one workstream.
+- Time-box source discovery. If the LinuxCNC source basis cannot be located
+  quickly, switch to another listed target and report the blocked symbol/path
+  instead of inventing behavior.
+- Keep smoke behavior shrinking. Never add project-authored smoke parser
+  semantics; prefer routing tests to LinuxCNC source-linked paths or proving why
+  a fallback remains a tracked blocker.
+
+Impact priority for "尽快推进":
+
+1. Replace or bypass temporary smoke/fallback behavior with LinuxCNC
+   source-linked execution.
+2. Make browser-hostile LinuxCNC dependencies wasm-safe without changing CNC
+   semantics: Python/remap, Boost.Python, dlopen, HAL/filesystem, tooldata.
+3. Add real browser OPFS persistence coverage for WASM reads/writes.
+4. Expand generated LinuxCNC config/remap/kinematics fixtures from source INI,
+   HAL, and remap files.
+5. Strengthen source maps only when they protect one of the above changes.
+
+Commit discipline:
+
+- Commit each coherent slice once required checks pass.
+- Push once after each commit. If HTTP credentials are missing, record the
+  failure and do not waste additional retries in the same turn.
+
 ## Source Pointers
 
 - RS274: `../linuxcnc/src/emc/rs274ngc/`

AGENTS.md

@@ -1,16 +1,22 @@
 # CNC Project Agent Guide
-工作树已经有一批未提交修改，太大了。我把这批改动按 6 个上下文拆更合适
-switchkins/remap 生成器和表
-linuxcnc-kinematics 源清单
-WASM 文件系统和 OPFS 持久化
-浏览器端应用接入
-Node / browser 烟测
-源码链接、构建和文档约束
+
+继续按 `align-linuxcnc` 约束推进。先确认基线，优先完成能降低剩余风险的可验证功能切片；禁止顺手扩展 smoke parser。提交满足后及时提交并推送云仓库，提交标题和说明使用中文，说明源依据、结论和检查结果。
+
+## 现状判断
+
+项目已经迭代很久但仍有大量工作，主要原因不是单个测试失败，而是后段工作集中在 LinuxCNC 浏览器化最难的边界：
+
+- Python/remap、Boost.Python、tooldata mmap、HAL/native filesystem 等 LinuxCNC 依赖不能靠自写兼容逻辑绕过，必须按 LinuxCNC 源码移植、裁剪、封装或替换。
+- 早期 smoke/fallback 体量仍大，后续只能缩减或路由到 LinuxCNC source-linked 路径，不能继续扩语义。
+- 很多提交用于 source-map、guardrail 和边界证明，能防退化但不直接减少功能缺口。
+- 完整验证成本高：native、source-link、Node WASM、真实浏览器 OPFS smoke 都要保持闭环。
+- 如果本地提交未及时推送，云端会严重落后，后续上下文会误判进度。
+
+因此后续默认按“高收益切片”推进，不再把文档/source-map-only 作为主要进度。
+
 ## Mission
 
-Build a browser/WebAssembly CNC simulator whose G-code behavior is aligned
-with LinuxCNC source. This is not an independent compatible interpreter; it is
-a port, trim, wrapper, or platform adaptation of LinuxCNC behavior.
+Build a browser/WebAssembly CNC simulator whose G-code behavior is aligned with LinuxCNC source. This is not an independent compatible interpreter; it is a port, trim, wrapper, or platform adaptation of LinuxCNC behavior.
 
 ## Work Roots
 
@@ -19,50 +25,67 @@ a port, trim, wrapper, or platform adaptation of LinuxCNC behavior.
 - LinuxCNC source: `/home/cnc/桌面/cnc/linuxcnc` or `$LINUXCNC_ROOT`
 - LinuxCNC unit tests: `/home/cnc/桌面/cnc/linuxcnc/unit_tests`
 
-Start every change with:
+Start every simulator change with:
 
 ```bash
 cd /home/cnc/桌面/cnc/wasm-simulator
 git status --short
 ```
 
+For root-level instruction edits, also check:
+
+```bash
+cd /home/cnc/桌面/cnc
+git status --short
+```
+
 ## Non-Negotiable Rules
 
-- Port LinuxCNC source first. Prefer direct source porting, trimming, wrapping,
-  or platform adaptation over project-authored replacements.
+- Port LinuxCNC source first. Prefer direct source porting, trimming, wrapping, or platform adaptation over project-authored replacements.
 - Do not write independent functional CNC behavior.
 - Functional behavior must come from LinuxCNC source code.
-- Do not use documentation, examples, or intuition as the final source when
-  LinuxCNC source is available.
-- Any G/M interpretation, motion, kinematics, coordinates, cutter
-  compensation, canned cycles, parameter expressions, modal state, tool data,
-  remap behavior, or RTCP behavior must first be traced to LinuxCNC source.
-- Allowed project-authored code is limited to LinuxCNC porting/trimming,
-  wrappers, platform shims, thin WASM/API/event bridges, generated fixtures,
-  tests, build scripts, and documentation.
-- Browser-side WASM filesystem access must use OPFS-backed storage. Do not add
-  browser filesystem behavior that bypasses OPFS.
+- Do not use documentation, examples, or intuition as the final source when LinuxCNC source is available.
+- Any G/M interpretation, motion, kinematics, coordinates, cutter compensation, canned cycles, parameter expressions, modal state, tool data, remap behavior, or RTCP behavior must first be traced to LinuxCNC source.
+- Allowed project-authored code is limited to LinuxCNC porting/trimming, wrappers, platform shims, thin WASM/API/event bridges, generated fixtures, tests, build scripts, and documentation.
+- Browser-side WASM filesystem access must use OPFS-backed storage. Do not add browser filesystem behavior that bypasses OPFS.
+- Never expand temporary smoke parser semantics. Prefer deletion, shrinkage, or LinuxCNC source-linked routing.
 
-## Source-First Workflow
+## High-Impact Lanes
 
-1. Pick one small missing source-backed bridge point or behavior gap.
-2. Locate the LinuxCNC source/config/remap first. Prefer:
+When the user asks to continue, default to one of these three lanes unless the user explicitly asks otherwise:
+
+1. Python/remap inert shim 收敛
+   - Compile or link more LinuxCNC Python/remap/Boost.Python source surfaces against inert wasm-safe shims.
+   - Preserve disabled-Python boundaries until a source-backed browser-safe execution plan exists.
+   - Useful outputs: symbol probe, object/link probe, negative-status probe, blocker reduction, manifest/test update.
+
+2. tooldata mmap 后端替换
+   - Move LinuxCNC `tooldata_mmap.cc` behavior toward wasm-safe storage without changing tool semantics.
+   - Useful outputs: backend behavior parity probe, source-backed table load/save coverage, mmap/native-fs blocker shrinkage.
+
+3. smoke parser 缩减到 LinuxCNC source-linked 路径
+   - Replace smoke/fallback coverage with LinuxCNC RS274 source-linked tests and bridge paths.
+   - Useful outputs: deleted smoke branches, tests moved to `linuxcnc-rs274`, source-linked fixture coverage.
+
+## Fast Loop
+
+1. Pick one small missing source-backed bridge point or blocker-reducing gap.
+2. Locate the LinuxCNC source/config/remap first:
 
    ```bash
    rg -n "symbol|gcode|mcode|error text" ../linuxcnc/src ../linuxcnc/configs
    ```
 
-3. Record the source file/function in the test, fixture, manifest, comment, or
-   nearby documentation when the mapping is not obvious.
-4. Add or update an automated test, generated fixture, or manifest entry.
+3. Record the source file/function in the test, fixture, manifest, comment, or nearby documentation when the mapping is not obvious.
+4. Add or update an executable test, generated fixture, probe, or manifest entry.
 5. Implement only the minimal port/wrapper/shim/bridge needed.
-6. Run the required checks.
-7. Report changed files, LinuxCNC source basis, test result, and completion
-   percentage.
+6. Run required checks.
+7. Commit and push once if checks pass.
+8. Report changed files, LinuxCNC source basis, tests, push status, and completion estimate.
 
 ## Required Checks
 
-For code, generated fixture, or source-manifest changes:
+For code, generated fixture, source-manifest, shim, build, or probe changes:
 
 ```bash
 ./test-native.sh
@@ -75,8 +98,25 @@ For generated switchkins/remap table changes, also run:
 ./check-linuxcnc-switchkins-remap-table.sh linuxcnc-kinematics-source-files.txt
 ```
 
-Documentation-only context edits do not require the native/source-link test
-suite; report that tests were not run.
+Documentation-only instruction edits do not require native/source-link; run `git diff --check` and report that full simulator tests were not run.
+
+## Anti-Stall Rules
+
+- Avoid repeated documentation/source-map-only commits. They are allowed only when protecting a new source path, unblocking a build/test, or updating requested process rules.
+- After one source-map-only or docs-only commit, the next simulator iteration should attempt code, generator, fixture, executable probe, or smoke shrinkage.
+- Time-box source discovery. If a source basis cannot be located quickly, report the blocked symbol/path and switch to another high-impact lane.
+- Do not make broad cleanups, UI work, or unrelated refactors while the three high-impact lanes still have blockers.
+- Batch one coherent mini-slice per commit. Do not mix unrelated workstreams.
+- Keep browser persistence OPFS-only.
+
+## Commit And Push
+
+- Commit each coherent slice once required checks pass.
+- Use Chinese commit titles and include a conclusion in the commit body.
+- Push after each successful commit.
+- If HTTP credentials are unavailable, report the failure and continue local progress instead of retrying the same failing push repeatedly.
+- If credentials are already available outside the repository, use a temporary non-interactive credential helper or askpass flow; do not commit credentials.
+- Before finishing, confirm `git status --short` and remote divergence when a push was expected.
 
 ## Current Completion Baseline
 
@@ -85,40 +125,20 @@ Estimated completion: about 72%.
 Materially covered:
 
 - Stable C ABI in `core/include/cnc_sim_api.h`.
-- LinuxCNC RS274 and kinematics source manifests:
-  `linuxcnc-rs274-source-files.txt`,
-  `linuxcnc-rs274-wasm-source-files.txt`, and
-  `linuxcnc-kinematics-source-files.txt`.
+- LinuxCNC RS274 and kinematics source manifests.
 - Native and source-linked RS274 test paths.
 - Canon event bridge and event sink for many interpreter callbacks.
 - Broad regression corpus under `tests/gcode/`.
-- M428/M429/M430 switchkins remap config generation from LinuxCNC INI files and
-  `remap_subs/{428,429,430}remap.ngc` sources.
-- Browser and Node WASM smoke coverage for generated switchkins config cases.
-- Source-backed coverage for many modal motion, coordinate, cutter comp, tool
-  length, probe, canned cycle, O-word, parameter, and M-code paths.
+- Generated M428/M429/M430 switchkins/remap config coverage.
+- Node and real browser WASM smoke coverage including OPFS paths.
 
 Main remaining risks:
 
-- Temporary smoke parser still exists and must continue shrinking.
-- Browser-hostile LinuxCNC dependencies still need deeper replacement or
-  wrapping: Python/Boost.Python remap paths, dynamic loading, HAL/filesystem
-  assumptions, and native tooldata backends.
-- Browser parity depends on maintaining source-backed behavior instead of
-  extending fallback logic.
-- Five-axis and RTCP coverage must remain tied to LinuxCNC kinematics source,
-  remap files, and config files.
-- OPFS integration must be verified in real browser runs, not only Node smoke
-  paths.
-
-## Good Next Targets
-
-- Replace smoke-only behavior with direct LinuxCNC RS274/source-linked paths.
-- Expand wasm-safe replacements for Python/remap/tooldata/dlopen dependencies.
-- Increase generated config coverage from LinuxCNC INI/HAL/remap sources.
-- Keep M428/M429/M430 and RTCP behavior tied to LinuxCNC kinematics/remap
-  source files.
-- Add browser checks that prove WASM file reads/writes persist through OPFS.
+- Temporary smoke parser still exists and must shrink.
+- Python/remap and Boost.Python paths are compile/shim covered but not browser-executed.
+- `tooldata_mmap.cc` native backend remains a core wasm replacement risk.
+- HAL/filesystem assumptions still need source-backed browser-safe boundaries.
+- Five-axis and RTCP coverage must remain tied to LinuxCNC kinematics/remap/config source.
 
 ## Stop Conditions
 

SKILL.md

@@ -0,0 +1,121 @@
+---
+name: align-linuxcnc
+description: Use for this CNC Web/WASM simulator when evaluating progress or changing LinuxCNC G-code behavior, RS274 source integration, kinematics, remaps, tool data, modal state, parameters, tests, fixtures, build scripts, bridge code, or project iteration strategy.
+---
+
+# Align LinuxCNC
+
+## Purpose
+
+Advance the simulator by aligning browser/WASM behavior with LinuxCNC source. The project is not a from-scratch compatible interpreter. It is a source-backed LinuxCNC port, trim, wrapper, or platform adaptation.
+
+## Why Progress Has Been Slow
+
+The remaining work is concentrated in hard browser-hostile LinuxCNC dependencies:
+
+- Python/remap and Boost.Python binding surfaces.
+- Native `tooldata_mmap.cc` storage and filesystem assumptions.
+- HAL/native filesystem/runtime services.
+- Large legacy smoke/fallback parser surface that must shrink instead of grow.
+- Heavy but necessary native/source-link/Node/browser OPFS validation.
+
+Treat source-map and guardrail work as support, not primary progress.
+
+## Hard Rules
+
+- Locate LinuxCNC source before functional changes.
+- Do not invent CNC behavior.
+- Do not extend temporary smoke parser semantics.
+- Keep browser filesystem persistence OPFS-backed.
+- Only write source ports, wrappers, platform shims, thin API/event bridges, generated fixtures, tests, build scripts, and documentation.
+- Preserve user changes in dirty worktrees.
+
+## Start Every Simulator Turn
+
+```bash
+cd /home/cnc/桌面/cnc/wasm-simulator
+git status --short
+```
+
+If editing project instructions:
+
+```bash
+cd /home/cnc/桌面/cnc
+git status --short
+```
+
+## Default High-Impact Lanes
+
+Prefer these lanes in order unless the user asks otherwise:
+
+1. Python/remap inert shim convergence
+   - Compile or link more blocked LinuxCNC Python/Boost.Python/remap sources against inert wasm-safe shims.
+   - Add probes that make remaining non-Python dependencies visible.
+   - Keep Python execution disabled until source-backed browser execution exists.
+
+2. tooldata mmap backend replacement
+   - Replace native mmap/filesystem assumptions with wasm-safe source-backed storage boundaries.
+   - Preserve LinuxCNC `tooldata_mmap.cc`, `tooldata_common.cc`, `tooldata_nml.cc`, and `tooldata_db.cc` semantics through probes.
+
+3. smoke parser shrinkage
+   - Move coverage from smoke/fallback parser into LinuxCNC `linuxcnc-rs274` source-linked paths.
+   - Delete or bypass smoke branches when source-linked behavior covers them.
+
+## Fast Loop
+
+1. Pick one blocker-reducing or executable-coverage slice.
+2. Find the LinuxCNC source/config/remap with `rg`.
+3. Add/update a probe, source-linked test, fixture, manifest, or shim.
+4. Keep the change within one workstream.
+5. Run required checks.
+6. Commit in Chinese and push once.
+7. Report source basis, changed files, checks, push status, and remaining risk.
+
+## Required Checks
+
+For simulator code, fixtures, manifests, shims, probes, or build scripts:
+
+```bash
+./test-native.sh
+./test-linuxcnc-source-link.sh
+```
+
+For switchkins/remap table generation:
+
+```bash
+./check-linuxcnc-switchkins-remap-table.sh linuxcnc-kinematics-source-files.txt
+```
+
+For instruction-only documentation changes, `git diff --check` is sufficient; state that full simulator checks were not run.
+
+## Anti-Stall Policy
+
+- Do not spend consecutive iterations on docs/source-map-only changes unless the user explicitly requests instruction edits.
+- A source-map guard must protect a new source path, prove a blocker boundary, or unblock build/test flow.
+- If source discovery stalls, switch lanes instead of inventing behavior.
+- Prefer executable probes over prose.
+- Prefer blocker shrinkage over broader coverage when both are available.
+
+## Commit And Sync
+
+- Commit coherent slices after checks pass.
+- Push after successful commits.
+- If HTTP credentials are unavailable, report once and continue local work.
+- If credentials are available outside the repo, use temporary non-interactive askpass/helper and do not store secrets in tracked files.
+
+## Source Pointers
+
+- RS274: `../linuxcnc/src/emc/rs274ngc/`
+- Kinematics: `../linuxcnc/src/emc/kinematics/`
+- Tooldata: `../linuxcnc/src/emc/tooldata/`
+- Python plugin: `../linuxcnc/src/emc/pythonplugin/`
+- Canon: `../linuxcnc/src/emc/nml_intf/canon.hh`
+- Sim configs/remaps: `../linuxcnc/configs/sim/`
+
+## Current Priority
+
+Continue from about 72% completion by reducing the remaining hard blockers:
+
+1. Python/remap inert shim convergence.
+2. tooldata mmap backend replacement.
+3. smoke parser shrinkage into LinuxCNC source-linked execution.