---
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.