docs: scaffold polisher-control foundation

tests/test_state_machine.py

@@ -0,0 +1,26 @@
+import pytest
+
+from polisher_control.state_machine import IllegalTransitionError, MachineState, StateMachine
+
+
+def test_manual_mode_path_returns_to_idle():
+    sm = StateMachine()
+    assert sm.trigger("enter_manual") == MachineState.MANUAL
+    assert sm.trigger("exit_manual") == MachineState.IDLE
+
+
+def test_faulted_requires_reset():
+    sm = StateMachine(MachineState.MANUAL)
+    assert sm.trigger("fault") == MachineState.FAULTED
+    with pytest.raises(IllegalTransitionError):
+        sm.trigger("enter_manual")
+    assert sm.trigger("reset") == MachineState.IDLE
+
+
+def test_operator_acknowledge_required_before_running():
+    sm = StateMachine()
+    sm.trigger("load_job")
+    with pytest.raises(IllegalTransitionError):
+        sm.trigger("start")
+    sm.trigger("operator_acknowledge")
+    assert sm.trigger("start") == MachineState.RUNNING