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.