wasm-simulator/docs/linuxcnc-source-policy.md

# LinuxCNC Source Policy

The simulator must not grow independently designed functional behavior.
Functional behavior must come from LinuxCNC source code.

Allowed project code:

- Thin adapters between LinuxCNC source code and the simulator C API.
- Platform shims needed to compile LinuxCNC code for native tests or wasm.
- Event serialization, test fixtures, build scripts, and documentation.
- Temporary smoke scaffolding only when it is explicitly marked as temporary.

Not allowed as final behavior:

- Hand-written G-code interpretation semantics.
- Hand-derived kinematics, RTCP, coordinate transform, cutter compensation, canned cycle, modal, parameter, or expression behavior.
- Behavior copied from documentation, controller intuition, or examples without checking the LinuxCNC implementation.

Required workflow for every functional change:

1. Identify the LinuxCNC source file and function that defines the behavior.
2. Add or update a test that demonstrates the LinuxCNC behavior.
3. Port, wrap, or route to that LinuxCNC implementation.
4. Record the source file/function in code comments or nearby documentation when the mapping is not obvious.
5. Run `./test-native.sh` and `./test-linuxcnc-source-link.sh`.

Current temporary exceptions:

- The smoke parser exists only to exercise the public API and UI around remaining fallback paths; native, source-linked, and wasm smoke coverage now route LinuxCNC RS274 behavior through the LinuxCNC-backed interpreter.
- RTCP pivot behavior is limited to LinuxCNC source-backed switchkins paths; unsupported switchkins types must not fall back to hand-derived geometry.

Both exceptions should shrink over time. New functional behavior should not be added to them unless it is directly copied from, or routed to, LinuxCNC source code.