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

name, description

name	description
align-linuxcnc	Use this skill for this CNC Web/WASM simulator whenever evaluating progress or changing LinuxCNC G-code behavior, RS274 source integration, kinematics, M428/M429/M430 remaps, tool data, modal state, parameters, tests, fixtures, build scripts, or bridge code.

Align LinuxCNC

Mission

Advance the simulator only by aligning it with LinuxCNC source behavior. The project goal is a LinuxCNC-source-backed Web/WASM CNC simulator, not a from-scratch compatible interpreter.

Hard Constraints

• Port-first: prefer direct LinuxCNC source porting, trimming, wrapping, or platform adaptation over project-authored replacements.
• Do not write independent functional CNC behavior.
• Do not use intuition or documentation as the final behavioral source.
• Before any functional change, locate LinuxCNC source in ../linuxcnc/src or ../linuxcnc/configs.
• Allowed code: LinuxCNC source port/wrap/trim/adaptation, platform shims, thin wasm/API/event bridges, generated fixtures, tests, build scripts, docs.
• Temporary smoke paths may be tested, but should shrink over time.
• Browser-side WASM filesystem access must use OPFS-backed storage.

Work Directory

cd /home/cnc/桌面/cnc/wasm-simulator
git status --short

Related roots:

• Project root: /home/cnc/桌面/cnc
• LinuxCNC source: /home/cnc/桌面/cnc/linuxcnc or $LINUXCNC_ROOT
• LinuxCNC unit tests: /home/cnc/桌面/cnc/linuxcnc/unit_tests

Required Checks

For code or generated fixture changes, run:

./test-native.sh
./test-linuxcnc-source-link.sh

For switchkins/remap table changes, also run:

./check-linuxcnc-switchkins-remap-table.sh linuxcnc-kinematics-source-files.txt

Fast Loop

1. Pick one tiny gap.
2. Find the LinuxCNC source/config/remap.
3. Add or update a source-backed test/fixture.
4. Implement only bridge/shim/wrapper/generator changes.
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/
• Kinematics: ../linuxcnc/src/emc/kinematics/
• Tooldata: ../linuxcnc/src/emc/tooldata/
• Canon: ../linuxcnc/src/emc/nml_intf/canon.hh
• Sim remaps/configs: ../linuxcnc/configs/sim/

Useful project docs:

• docs/linuxcnc-source-policy.md
• docs/linuxcnc-porting.md
• docs/linuxcnc-rs274-source-map.md
• linuxcnc-rs274-source-files.txt
• linuxcnc-rs274-wasm-source-files.txt
• linuxcnc-kinematics-source-files.txt

Current Baseline

Completion estimate: about 72%.

Strong areas: source manifests, native/source-linked RS274 runners, broad G-code regression corpus, generated M428/M429/M430 switchkins remap fixtures, Node/browser WASM smoke coverage.

Main remaining risks: smoke parser removal, Python/Boost.Python remap replacement, dynamic loading shims, tooldata/HAL/filesystem assumptions, continued source-backed expansion of kinematics/RTCP coverage, and real browser verification that WASM file reads/writes persist through OPFS.